docs: 인증을 쿠키 기반 JWT로 개정 + 인증 설계 문서(11) 신설

[cherry-go-round]

요약

인증을 쿠키 기반 JWT로 개정하고, 그 결정 근거를 담은 11_인증_설계.md를 신설합니다. 관련 문서 5개의 정합성도 함께 맞췄습니다.

⚠️ 프론트엔드가 반드시 알아야 할 변경

기존 "POST 토큰 교환" 흐름은 폐기됐습니다. 콜백 후 클라이언트가 토큰을 교환하는 단계가 없습니다.

	기존 (폐기)	변경 후
콜백 응답	JSON 본문에 accessToken·refreshToken	302 리다이렉트 + Set-Cookie
토큰 교환	클라이언트가 별도 POST 호출	없음. 서버가 콜백에서 쿠키를 심고 끝
토큰 보관	클라이언트가 저장	클라이언트는 보관하지도 읽지도 않음
요청 인증	Authorization: Bearer 헤더	쿠키 자동 전송 (withCredentials)
신규 가입	SIGNUP_REQUIRED → 약관 동의 API	없음. 콜백에서 즉시 회원 생성

이전 문서를 보고 구현을 시작하셨다면 위 흐름으로 바꿔주세요.

배경

BFF와 리소스 서버를 한 서버로 운영하기로 하면서 토큰 전달 방식을 다시 정했습니다. IETF draft-ietf-oauth-browser-based-apps는 아키텍처를 "decreasing order of security"로 나열하며 BFF를 개인 데이터를 다루는 애플리케이션에 "strongly recommended"로 두고, BFF 쿠키에 Secure·HttpOnly를 MUST로 요구합니다. PinLog은 개인의 장소 기록과 위치 데이터를 다루므로 여기에 해당합니다.

약관 동의는 클라이언트가 로그인 시작 이전 화면에서 전담하기로 하여 서버 API가 없어졌습니다.

#11(공통 응답 봉투) 머지 후 그 위로 rebase했습니다. 조정 내역은 아래 3번에 있습니다.

변경 내용

1. 11_인증_설계.md 신설 — 프론트엔드 소통용

결정의 근거와 클라이언트가 지켜야 할 계약을 한 곳에 모았습니다. 구현 세부는 담지 않았습니다.

• IETF 아키텍처 등급과 BFF 쿠키 요구사항, XSS·CSRF 맞교환, 쿠키를 택한 이유
• 클라이언트 계약 — withCredentials, CSRF 헤더, 응답 봉투 예외, 401 처리와 동시 재발급 금지(single-flight), 로그인은 페이지 이동
• 검토했으나 채택하지 않은 대안 4가지와 이유
• 배포 오리진과 쿠키 — same-origin 근거, Lax를 고른 이유, 로컬 개발 주의
• 레퍼런스 (IETF, RFC 9700, OWASP, MDN)

2. 08_API_명세.md 개정

절	변경
헤더	context-path(/api/core)와 API 버전(v1) 분리 표기. 클라이언트 base URL 환경변수 값은 /api/core/v1
§1.1	Bearer 헤더 → HttpOnly+Secure+SameSite=Lax 쿠키. Refresh 쿠키 Path 제한. memberId 미반환
§1.5	상태 코드 표에 403 추가 (CSRF 실패)
§1.7	CSRF 절 신설 — XSRF-TOKEN 쿠키 → X-XSRF-TOKEN 헤더
§1.8	로그인 표시 쿠키 신설 — logged_in
§2.1	POST /me/agreements 제거
§3.2	SIGNUP_REQUIRED·signupToken 분기 제거. 콜백에서 즉시 회원 생성 후 Set-Cookie + 302
§3.3	약관 동의 절 삭제. 재발급을 쿠키 기반으로 전환, 동시 재발급 금지 명시
§3.6	회원 탈퇴 상세 신설

3. #11(공통 응답 봉투)과의 조정

• CSRF 절을 §1.6 → §1.7로 이동 (#11이 §1.6을 공통 응답 형식에 사용)
• §1.5 traceId 추가분 폐기 — docs(S15P11A705-54): API 명세에 공통 응답 봉투 형식 반영 #11 쪽 설명을 그대로 사용
• 인증 Endpoint는 봉투 예외임을 명시 — 콜백 302, 재발급 200(본문 없음), 로그아웃 204라 감쌀 본문이 없습니다. 오류만 봉투를 따릅니다
• 기본 경로 표기 정정 — /api/core는 인프라 고정 context-path, v1은 API 버전 세그먼트로 둘 다 맞습니다. 관계가 드러나도록 헤더를 나눴습니다

4. 확정한 값

infra/docs/backend-conventions.md의 Traefik 경로 라우팅상 프론트와 API가 same-origin이라는 사실이 대부분을 결정했습니다.

항목	확정값	비고
SameSite	Lax	프론트 의견과 일치
CORS	운영 불필요, 로컬만 필요	same-origin
콜백 복귀 경로	/auth/callback, 실패 시 ?error=OAUTH_FAILED	프론트 의견과 일치
API base URL	/api/core/v1	본문 37곳 모두 이 값으로 통일되어 있음
로그인 상태 확인	logged_in 표시 쿠키	프론트 의견 반영해 B안 채택
회원 탈퇴 상세	§3.6 신설	정책 정의서 10장 + ERD 마스킹

5. 정합성 맞춘 문서

• 06_데이터모델_및_무결성.md §8 — "동의 완료 전 member를 생성하지 않는다"가 확정으로 박혀 있어 정면 충돌했습니다. 뒤집었습니다
• 09_유저플로우.md §1 — 가입 다이어그램에서 동의 분기 제거, 약관을 로그인 이전으로 이동
• 10_MVP_기능범위.md · 02_정책_정의서.md · 04_익명SNS_공개정책.md — 약관 안내 시점 표현 정리
• README.md 문서 구조 표에 11 추가

리뷰 회신 반영 (@TrossYou)

요청	처리
base path 통일 + VITE_API_BASE_URL 값 확정	본문 37곳은 이미 전부 /api/core/v1 이었고, 헤더 한 줄만 /api/core라 어긋나 보였습니다. 둘의 관계를 헤더에 명시하고 환경변수에는 /api/core/v1을 넣는다는 문장을 추가했습니다
토큰 교환 폐기 명시	이 본문 최상단에 비교표로 넣었습니다
SameSite Lax	일치. 확정
콜백 URL /auth/callback (+?error=OAUTH_FAILED)	일치. 확정
로그인 확인 (B) 보조 쿠키 + 오용 방지 문구	B안으로 변경했습니다. GET /auth/session을 철회하고 logged_in 쿠키로 대체(§1.8). "UI 힌트 전용 / 인가 판단 금지 / 실제 인가는 서버가 매 요청 검증"을 인용 블록으로 강조했고, 11 §5.2에도 같은 경고를 넣었습니다

남은 리뷰 항목

1. 02·04는 정책 문서라 소유가 다릅니다

기획 담당 확인을 부탁드립니다. 결정된 흐름에 맞춰 문장만 정리했고 새로운 정책 판단을 넣지는 않았습니다.

2. 법적 리스크

"진행하면 동의한 것으로 간주"는 필수 약관, 특히 개인정보 수집·이용 동의에 대해 명시적 동의를 원칙으로 하는 국내 법제와 어긋날 소지가 있습니다. 또한 서버에 동의 기록이 남지 않아 증빙 요구에 대응할 수단이 없습니다. 06 §8에 이 영향을 적어뒀습니다. 이 PR은 결정된 흐름을 반영한 것이고, 결정 자체의 타당성은 별도 판단이 필요합니다.

🤖 Generated with Claude Code

[TrossYou]

[병합 전 필수]

1. base path — 요약은 /api/core인데 예시 32곳은 /api/core/v1.
   어느 쪽으로 통일할지 확정하고 32곳 일괄 정리 부탁.
   VITE_API_BASE_URL이 여기 달려 있어서 이거 없이는 API 함수 확정 못 함.
2. 토큰 교환 폐기 명시 — PR 설명에 "기존 POST 토큰 교환 폐기, 302 리다이렉트로 대체"
   라고 적어줘. 이전 문서 본 사람이 옛 흐름으로 구현하는 걸 막기 위해.

[§7 합의 3건 — 프론트 의견]

• SameSite: Lax
• 콜백 URL: 성공 /auth/callback, 실패 /auth/callback?error=OAUTH_FAILED
• 로그인 확인: (B) 보조 쿠키. 단 "UI 힌트 전용, 실제 인가는 서버가 매 요청 검증"
  문구를 문서에 넣어줘 (프론트가 이 쿠키를 인가 판단에 쓰는 실수 방지)

[cherry-go-round]

@TrossYou 리뷰 반영했습니다. 3dd26f5

[병합 전 필수] 1 — base path

확인해보니 본문 Endpoint는 이미 37곳 전부 /api/core/v1 이었습니다. v1 없이 /api/core만 쓴 곳은 헤더 한 줄뿐이었고, 그게 "요약과 예시가 다르다"로 보인 원인이었습니다. 일괄 정리할 대상이 없어서 대신 관계를 명시했습니다.

- 서비스 context-path: /api/core   (인프라 고정값)
- API 버전: v1                      (context-path 뒤에 붙는 세그먼트)
- 기본 경로: /api/core/v1           (둘을 합친 값)
  - 클라이언트의 API base URL 환경변수에는 이 값을 넣는다

VITE_API_BASE_URL 에는 /api/core/v1 을 넣으시면 됩니다. 프론트와 API가 same-origin이라 호스트를 붙일 필요도 없습니다.

[병합 전 필수] 2 — 토큰 교환 폐기 명시

PR 본문 최상단에 경고 블록으로 넣었습니다. 기존/변경 후 비교표라 이전 문서를 본 사람도 바로 알아챌 수 있을 겁니다.

§7 합의 3건

항목	결과
SameSite Lax	일치. 확정했습니다
콜백 /auth/callback + ?error=OAUTH_FAILED	일치. 확정했습니다
로그인 확인 (B) 보조 쿠키	B안으로 변경했습니다

로그인 확인은 제가 GET /auth/session으로 잡아뒀던 걸 철회하고 logged_in 쿠키로 바꿨습니다. 요청하신 오용 방지 문구는 08 §1.8에 인용 블록으로 넣었습니다.

UI 힌트 전용이다. 인가 판단에 사용하지 않는다.

실제 인가는 서버가 매 요청 인증 쿠키를 검증해 수행한다. 이 쿠키는 브라우저에 남아 있어도 세션이 이미 무효일 수 있다(예: Refresh 만료, 다른 기기에서 로그아웃). 그 경우 첫 API 호출이 401을 반환하므로, 클라이언트는 재발급을 시도하고 실패하면 로그인 화면으로 유도한다.

이 쿠키의 존재를 근거로 보호 화면을 렌더링하는 것은 무방하다. 이 쿠키의 존재를 근거로 권한이 있다고 판단하는 것은 안 된다.

쿠키 사양은 이렇습니다.

• logged_in=1, Secure, SameSite=Lax, Path=/, Max-Age는 Refresh와 동일(7일), HttpOnly 아님
• 발급·갱신: 로그인 콜백, 재발급 성공 시
• 삭제: 로그아웃, 회원 탈퇴 시

11_인증_설계.md §5.2에 앱 시작 흐름도 이 방식으로 다시 썼습니다 — 쿠키가 있으면 일단 메인을 그리고, 401이 오면 재발급 시도 후 실패 시 로그인 화면으로 정정하는 구조입니다.

---

한 가지만 확인 부탁드립니다. 콜백 복귀 경로 /auth/callback은 프론트에 실제 라우트가 있어야 로그인 직후 화면이 뜹니다. 라우팅 구조에 이미 있는지, 다른 경로가 편한지 알려주시면 서버 설정값만 바꾸면 됩니다.

[TrossYou]

콜백 경로 /auth/callback 그대로 갈게. 프론트에 이 라우트 추가할 예정이야.
서버 설정값 그대로 두면 돼. (실패는 /auth/callback?error=OAUTH_FAILED)

[minyongP]

Important — Refresh 쿠키 Path 제한이 로그아웃·탈퇴를 막습니다

§1.1과 §3.2에서 refresh 쿠키를 이렇게 좁힙니다:

Set-Cookie: refreshToken=…; Path=/api/core/v1/auth/refresh

그런데 §3.4 로그아웃은 POST /api/core/v1/auth/logout, §3.6 탈퇴는 DELETE /api/core/v1/me입니다. 두 경로 모두 Path가 안 맞아 refresh 쿠키가 전송되지 않습니다.

• 쿠키 만료시키는 건 문제없습니다(같은 Path로 Set-Cookie 내리면 됨).
• 문제는 서버 측 무효화입니다. Redis에서 어느 refresh 토큰을 지울지 식별할 근거가 없습니다. Access 쿠키의 subject로 "그 회원의 refresh 전체 무효화"로 우회할 수 있지만, Access가 이미 만료된 상태에서 로그아웃하면 회원 식별조차 불가 → 서버 세션이 살아남습니다(다른 기기 로그아웃·탈퇴 시 특히 문제).

해결안 두 가지 중 하나를 명시하면 됩니다:

1. Refresh 쿠키 Path를 /api/core/v1/auth 로 넓히기 — refresh·logout 모두 포함, 일반 API(/records 등)에는 여전히 안 실림. 가장 단순합니다.
2. 로그아웃·탈퇴는 Access 쿠키로 회원을 식별해 해당 회원의 refresh를 전부 무효화한다고 명기하고, Access 만료 시 동작(쿠키만 정리 + 서버는 TTL 만료에 의존)까지 적기.

---

🟡 Minor 3건

1. §3.3 재발급이 "200 + 본문 없음" — HTTP상 합법이지만 §1.6은 "본문 없는 성공"을 204로 규정합니다. 204로 바꾸면 봉투 예외 규칙과 자연스럽게 맞습니다.
2. §1.7 CSRF 403과 401 응답은 Spring Security 필터가 직접 씁니다 — @RestControllerAdvice를 거치지 않으므로, 문서가 약속한 "오류는 봉투(1.5)"를 지키려면 인증 PR에서 AuthenticationEntryPoint·AccessDeniedHandler·CSRF 실패 핸들러가 직접 ApiResponse.fail(...)을 써야 합니다. (back의 error-handling.md에 이미 명기해뒀습니다 — 문서 결함이 아니라 구현 의무입니다.)
3. §3.2의 Set-Cookie 예시에 HttpOnly; Secure; SameSite=Lax가 생략돼 있습니다("속성은 1.1을 따른다"고 참조하지만, 예시만 복붙하면 놓칠 수 있습니다).

[cherry-go-round]

@minyongP 43ae14e 반영했습니다. Path 문제는 제 실수가 맞습니다 — 지적 감사합니다.

Important — Refresh 쿠키 Path

1번(Path 확대)을 택하되, 탈퇴는 2번 방식으로 나눴습니다. 1번만으로는 /me가 여전히 /auth 밖이라 탈퇴가 해결되지 않아서요.

	경로	Refresh 쿠키	무효화 방식
재발급	/auth/refresh	✅ 전송됨	회전
로그아웃	/auth/logout	✅ 전송됨 (Path 확대로)	해당 세션만
탈퇴	/me	❌ 안 실림	Access로 회원 식별 → 전체 무효화

Set-Cookie: refreshToken=…; HttpOnly; Secure; SameSite=Lax; Path=/api/core/v1/auth

/records 같은 일반 API에는 여전히 안 실립니다.

로그아웃 — Refresh 쿠키로 대상을 특정하므로 지적하신 "Access 만료 상태에서 로그아웃" 문제가 사라집니다. Refresh만 있으면 되니까요. 그리고 해당 세션 하나만 무효화하도록 명시했습니다. 다른 기기 로그인은 유지됩니다. Refresh 쿠키가 없거나 이미 무효한 경우에도 204입니다 — 이미 로그아웃된 상태를 오류로 취급하면 클라이언트가 처리할 게 늘어나기만 합니다.

탈퇴 — Access로 회원을 식별해 그 회원의 Refresh를 전부 무효화합니다. 탈퇴는 모든 기기에서 즉시 끊겨야 하므로 전체 무효화가 오히려 맞는 동작입니다. Access가 만료됐으면 401이고, 클라이언트는 평소처럼 재발급 후 재시도합니다.

Minor

1. 재발급 200 → 204 — 반영했습니다. §1.6의 "본문 없는 성공은 204" 규정과 맞습니다. 11 문서의 흐름도와 봉투 예외 표도 함께 고쳤습니다.

2. CSRF 403·401을 Security 필터가 직접 쓰는 건 — 말씀대로 문서 결함이 아니라 구현 의무라 문서는 그대로 뒀습니다. AuthenticationEntryPoint·AccessDeniedHandler·CSRF 실패 핸들러가 직접 봉투를 써야 한다는 점은 백엔드 인증 구현 계획에도 반영해두겠습니다. 특히 traceId가 null이 되지 않으려면 TraceIdFilter가 Security 필터 체인보다 먼저 실행돼야 하는 것도 같이 챙기겠습니다.

3. Set-Cookie 예시에 속성 생략 — 반영했습니다. 참조만 두면 예시를 복붙할 때 놓친다는 지적이 맞습니다.

Set-Cookie: accessToken=…;  HttpOnly; Secure; SameSite=Lax; Path=/api/core/v1
Set-Cookie: refreshToken=…; HttpOnly; Secure; SameSite=Lax; Path=/api/core/v1/auth
Set-Cookie: logged_in=1;    Secure; SameSite=Lax; Path=/

logged_in만 HttpOnly가 빠져 있다는 게 예시에서 바로 보이게 했습니다.

---

@TrossYou 콜백 경로 확정 감사합니다. /auth/callback 그대로 두고 실패는 ?error=OAUTH_FAILED로 갑니다. 서버 설정값은 변경 없습니다.