Auth / 세션 / TURN·ICE 발급 — 코드레벨 동작 흐름 P2코드레벨

마지막 업데이트 2026-07-22

작성일: 2026-06-14 대상: 개발자 — 인증·세션·WebRTC 자격증명 파악 핵심 파일: lib/session.ts, lib/auth-refresh.ts, api/{members,users}/auth, api/ice-servers

개요 · 범위

치료사(member)·아동(child) PIN 로그인과 세션(쿠키) 관리, 토큰 갱신, 그리고 WebRTC용 TURN/ICE 자격증명 발급. Next.js가 BFF로서 외부 ppi-api 인증을 중계하고 토큰을 암호화 쿠키(iron-session)에 보관한다.

PIN 로그인 api/members/auth, api/users/auth

POST /api/members/auth { name, pin }   // 치료사
POST /api/users/auth   { name, pin }   // 아동
  → ppiApiClient.login(name, pin)      // 외부 ppi-api
  → session.{accessToken, refreshToken, accessTokenExpiresAt, *Id, *Name, role}
  → session.save()  (암호화 쿠키)

PIN 길이 검증(4~16). 인증 실패 시 AUTHENTICATION_FAILED + 원 status 전달.
응답 본문엔 토큰을 넣지 않고 member/child 식별 정보만 반환(토큰은 httpOnly 쿠키에만).

세션 (iron-session) lib/session.ts

	member	child
쿠키	`ppi-member-session`	`ppi-child-session`
보관	accessToken/refreshToken/accessTokenExpiresAt + 식별 정보
옵션	httpOnly, secure(prod), sameSite lax, maxAge 14일, SESSION_SECRET 암호화

만료 버퍼 30분: isAccessTokenExpired는 만료 30분 전부터 만료로 본다. 수업(20분) 동안 BFF 호출이 없어 토큰이 만료되는 일을 막기 위한 선제 갱신 버퍼.

토큰 갱신 lib/auth-refresh.ts

refresh 결과를 3가지로 분류해 "세션 폐기 vs 유지"를 정확히 판단한다(잘못 폐기하면 수업 중 로그아웃).

RefreshOutcome	의미 / 처리
`refreshed`	새 accessToken + expiresAt
`invalid` (401만)	refresh token 무효 → 세션 폐기 OK
`transient` (400/5xx/네트워크)	일시 장애 → 세션 유지(폐기 근거 아님), warn 로깅

핵심 컨벤션: ppi-api는 401만 refresh token 무효 신호. 400(BFF 요청 버그)/5xx(ppi-api 장애)로 세션을 폐기하면 안 된다 — 일시 장애에 사용자가 로그아웃되는 회귀 방지.

TURN/ICE 발급 api/ice-servers/route.ts

GET /api/ice-servers
  → getMeteredApiKey()  (SSM/시크릿)
  → GET ppi.metered.live/api/v1/turn/credentials?apiKey=...
  → { iceServers: [{ urls, username, credential }] }

Metered.ca에서 TURN 자격증명을 발급받아 클라이언트에 전달. WebRTC(#1 OpenAI, #11 P2P)의 RTCConfiguration.iceServers로 사용.
오류 분류: 400 TURN_CRED_NO_API_KEY, 401 TURN_CRED_INVALID_API_KEY, 그 외 TURN_CRED_UNKNOWN_ERROR.
apiKey는 서버에서만(getMeteredApiKey) — 클라이언트 비노출.

함정 · 주의

401만 세션 폐기: refresh transient(400/5xx/네트워크)를 invalid로 처리하면 일시 장애에 강제 로그아웃. classifyRefresh 분류를 지킬 것.
만료 버퍼 30분: 수업 길이(20분)보다 커야 수업 중 만료를 막는다. 버퍼를 줄이면 수업 도중 토큰 만료 위험.
토큰은 쿠키에만: 응답 본문/클라이언트에 토큰을 노출하지 않는다(httpOnly). BFF 패턴 유지.
TURN 필수: 제한적 NAT/방화벽에서 ICE 후보가 TURN 없이는 연결 실패. ice-servers 발급 실패 시 WebRTC 연결률 저하(#11 재연결과 연계).
member/child 분리: 쿠키·세션·refresh가 역할별로 분리. 한쪽 로직 변경 시 다른 쪽 누락 주의.

파일 · 라인 레퍼런스

파일	역할
api/members/auth/route.ts, api/users/auth/route.ts	PIN 로그인 BFF
lib/session.ts	iron-session member/child 쿠키·만료 버퍼
lib/auth-refresh.ts	refresh 결과 분류(refreshed/invalid/transient)
api/ice-servers/route.ts	Metered TURN 자격증명
lib/ppi-api-client.ts	외부 ppi-api 클라이언트