손목밴드

비유 ↔ 용어

손목밴드

액세스 토큰 (JWT, 짧게 씀). 화면 기본 15초, 서버 기본 20초

재발급 영수증

리프레시 토큰 (기본 1일). DB에는 원문 대신 SHA-256 해시만 저장

주머니

메모리 (자바스크립트 변수). 액세스 토큰을 여기에 둬요

금고

httpOnly 쿠키 bv_refresh_token (Path=/auth)

가방

localStorage. 스크립트가 다 열어 볼 수 있어요

영수증 바꾸기

회전(rotation): 쓴 토큰은 used, 같은 familyId로 새 토큰

복사본이 들킴

재사용 감지: used 토큰이 또 오면 그 로그인(family) 전체 revoked

대표 한 명만

single-flight: 동시에 401이 나도 refresh는 한 번

요청 흐름

1. 브라우저 → API POST /auth/login { username, password, accessTokenTtlSeconds }. 모든 요청은 credentials: 'include'로 보내요.
2. API → MySQL AuthService.login이 scrypt로 비밀번호를 확인하고, RefreshTokenStore.issueNewFamily가 새 familyId로 첫 토큰 행을 만들어요.
   • 비밀번호가 틀리면 401 invalid_credentials
3. API → 브라우저 200 { user, accessToken, accessTokenExpiresAt, refreshToken } + Set-Cookie: bv_refresh_token=…; HttpOnly; Path=/auth. 액세스 토큰은 React 상태(메모리)에만 둬요.
4. 브라우저 → API GET /auth/me + Authorization: Bearer <액세스 토큰>. AccessTokenGuard가 서명과 만료만 확인해요 (DB 조회 없음).
   • 만료면 401 access_token_expired → 다음 단계로
   • 헤더가 없거나 위조면 401 access_token_missing / access_token_invalid
5. 브라우저 → API refreshWithCookieOnce()(single-flight)로 POST /auth/refresh를 한 번만 보내요. 쿠키는 브라우저가 알아서 붙여요.
6. API → MySQL RefreshTokenStore.rotate가 해시로 행을 찾고, 조건부 UPDATE(status = 'active'일 때만 used)로 한 요청만 통과시켜요.
   • 통과: 같은 familyId, parentId = 방금 쓴 토큰으로 새 행 → 200 + 새 AT + 새 Set-Cookie
   • 이미 used: family 전체 revoked → 401 refresh_token_reuse_detected, 쿠키 삭제
   • revoked / 만료 / 모르는 토큰: 401 refresh_token_revoked / refresh_token_expired / refresh_token_invalid
7. 브라우저 → API 새 액세스 토큰으로 GET /auth/me를 한 번 더 보내요.
8. 브라우저 새로고침하면 메모리의 액세스 토큰이 사라져요. 페이지가 뜰 때 쿠키로 POST /auth/refresh를 보내 조용히 복구해요.
9. 브라우저 → API POST /auth/logout은 그 family의 토큰을 모두 revoked(logout)로 바꾸고 쿠키를 지워요.

DB에는 이렇게 남아요

표를 이렇게 읽어요

• 세 행 모두 familyId가 같아요 (ac03c858…). parentId를 따라가면 회전 순서가 보여요.
• 복사본을 내기 전에는 위 두 행이 used, 마지막 행이 active였어요. 복사본 한 번에 셋 다 같은 시각에 revoked가 됐어요.

프론트 관점

• 액세스 토큰은 메모리에만 둬요. localStorage에 두면 끼어든 스크립트가 꺼내 가요.
• refresh는 꼭 single-flight로 묶어요. 동시에 5개가 따로 가면 4개가 "이미 쓴 토큰"이 되어 로그인이 통째로 취소돼요.
• React StrictMode에서 effect가 두 번 돌아도 같은 Promise를 공유해서 회전은 한 번이에요.

한계·운영에선

• 액세스 토큰은 서버가 기록하지 않아요. 로그아웃해도 만료될 때까지는 통과해요. 그래서 짧게 둬요.
• single-flight는 탭 하나 안에서만 묶여요. 탭 여러 개가 동시에 갱신하면 재사용 감지에 걸릴 수 있어요.
• 웹과 API가 다른 사이트면 쿠키가 SameSite=None; Secure(+ Partitioned)여야 해요.
• 도둑 데모용 /auth/demo/*는 AUTH_DEMO_ENDPOINTS=true일 때만 열려요. 운영에선 끄세요.

개발자 도구로 보면

• Application → Cookies에 bv_refresh_token이 HttpOnly로 보여요. 콘솔의 document.cookie로는 안 보여요.
• 쿠키는 /auth 경로 요청에만 붙어요. POST /auth/refresh의 요청 헤더에서 Cookie, 응답에서 새 Set-Cookie를 확인할 수 있어요.
• 아래 JWT 디코더로 액세스 토큰의 sub, username, familyId, iat, exp를 볼 수 있어요.

코드·문서

1. wristband/api.ts
2. auth.controller.ts
3. auth.service.ts
4. refresh-token.store.ts · 회전·재사용 감지
5. access-token.guard.ts
6. AuthDemo.tsx · 401 → refresh → 재시도
7. lib/single-flight.ts
8. docs/auth-tokens.md · 설계 문서