[로그인인증] 쿠키·헤더 레퍼런스 (A)

본문을 읽다가 속성 하나, 헤더 하나의 정확한 뜻을 다시 찾을 때 보는 표 모음입니다. 개념 설명은 1장과 2장에 있고, 여기서는 규칙과 이 책의 값만 정리합니다. 이 책의 코드와 관련된 값은 모두 부록 C 기준입니다.

브라우저마다, 버전마다 달라지는 세부는 사실처럼 적지 않고 "문서 확인" 으로 남겼습니다. 표에 그렇게 적힌 칸은 MDN 이나 해당 브라우저·라이브러리의 공식 문서에서 지금 쓰는 버전 기준으로 확인하세요.

A.1 Set-Cookie 문법

Set-Cookie: <이름>=<값>[; <속성>[=<값>]]*
Cookie: <이름>=<값>[; <이름>=<값>]*

A.2 쿠키 속성 전체

이 책의 쿠키

부록 C 의 api/src/auth/cookies.ts 와 api/src/lab/lab.controller.ts 가 만드는 쿠키입니다. 아래 Set-Cookie 는 예시 출력이며, 속성의 순서는 Express 가 쓰는 cookie 라이브러리 버전에 따라 다를 수 있습니다. 순서는 의미에 영향을 주지 않습니다.

• refresh_token 의 만료는 Max-Age 가 아니라 Expires 로 나갑니다. 코드가 DB 에 저장한 토큰 만료 시각(expires_at)을 그대로 넘기기 때문입니다. 그 값은 min(발급 + REFRESH_TOKEN_TTL_SEC, session_expires_at) 이라서 보통 14일 뒤지만 세션 상한 30일에 가까워지면 더 짧아집니다.
• Secure 는 COOKIE_SECURE 가 true 일 때만 붙습니다(lab_session 은 예외로 항상 붙음). COOKIE_SECURE 를 끄면 SameSite=None 이 필요한 구성에서 쿠키가 거부되니 주의하세요.
• refresh_token 은 401 응답(REFRESH_TOKEN_INVALID·REFRESH_TOKEN_REUSED)과 로그아웃·전체 로그아웃에서 clearRefreshCookie 로 지워집니다. 설정 때와 같은 refreshOptions 를 쓰므로 Path=/auth; HttpOnly; Secure; SameSite=Strict 가 그대로 붙고, 만료는 과거 시각입니다. 409 REFRESH_TOKEN_ROTATED 에서는 지우지 않습니다.

Set-Cookie: refresh_token=Q0y1ECht…; Path=/auth; Expires=Wed, 07 Oct 2026 03:00:00 GMT; HttpOnly; Secure; SameSite=Strict
Set-Cookie: csrf_token=pX3m…Qk.9f2W…aA; Max-Age=7200; Path=/; Expires=Thu, 24 Sep 2026 05:00:00 GMT; HttpOnly; Secure; SameSite=Strict
Set-Cookie: refresh_token=; Path=/auth; Expires=Thu, 01 Jan 1970 00:00:00 GMT; HttpOnly; Secure; SameSite=Strict

(예시 출력. 세 번째 줄은 삭제)

A.3 __Host- · __Secure- 접두사

쿠키 이름의 접두사로 브라우저에게 추가 조건을 강제하게 하는 장치입니다. 조건을 만족하지 않는 Set-Cookie 는 브라우저가 거부합니다. 공격자가 같은 사이트의 다른 서브도메인이나 HTTP 연결에서 같은 이름의 쿠키를 심는 쿠키 주입에 대비합니다.

http://localhost 에서 접두사 쿠키를 받아들이는지는 브라우저 문서 확인.

이 책의 선택. refresh_token 은 접두사를 쓰지 않습니다. __Host- 는 Path=/ 를 강제하므로 Path=/auth 로 좁힐 수 없고, 이 책은 리프레시 쿠키가 /auth/* 밖의 요청에 실리지 않는 쪽을 택했습니다. csrf_token 은 이미 Path=/·호스트 전용이라 __Host-csrf_token 으로 바꿀 수 있는 조건을 갖췄지만, 부록 C 의 코드는 csrf_token 이라는 이름을 씁니다. 쿠키 주입은 CSRF 토큰의 HMAC 서명이 막습니다(9장). 운영에서 접두사를 쓸지는 14장에서 다룹니다.

A.4 사이트 판정 요약

주소 쌍별 판정 표는 1장 1.6절에 있습니다.

A.5 SameSite 동작 매트릭스

"같은 사이트" · "다른 사이트" 는 요청을 시작한 페이지와 요청 대상의 사이트를 비교한 것입니다. ✅ 는 쿠키가 실림, ❌ 는 실리지 않음입니다. 이 책의 로컬 구성으로 바꿔 읽으면 "같은 사이트" 는 localhost:5173·localhost:5174 → localhost:4000, "다른 사이트" 는 127.0.0.1:5174 → localhost:4000 입니다.

※ 다른 사이트 문맥의 None 쿠키, 곧 서드파티 쿠키는 브라우저의 차단 정책(시크릿 모드, 사용자 설정, 브라우저별 기본값)에 따라 실리지 않을 수 있습니다. 브라우저와 버전마다 다르므로 해당 브라우저 문서 확인.

보충 규칙:

• SameSite 를 생략한 쿠키: Chrome 은 Lax 로 취급하고, 심긴 지 2분이 안 된 쿠키는 다른 사이트의 최상위 POST 에도 예외적으로 싣는다고 알려져 있습니다. 정확한 조건과 다른 브라우저의 동작은 문서 확인. 이 책의 쿠키는 모두 SameSite 를 명시합니다.
• Lax 의 "안전한 메서드" 는 GET·HEAD 등 서버 상태를 바꾸지 않는다고 약속된 메서드입니다. 서버가 GET 으로 상태를 바꾸면 Lax 가 아무것도 막지 못합니다.
• Strict 와 첫 방문: 다른 사이트의 링크로 들어온 첫 문서 요청에는 Strict 쿠키가 없습니다. 이 책은 리프레시 쿠키를 문서 요청이 아니라 뜬 페이지의 fetch 에서만 쓰므로 영향이 없습니다.
• iframe 과 리다이렉트: 요청이 iframe 안에서 시작되었거나 리다이렉트를 거친 경우 "요청을 시작한 사이트" 를 어떻게 계산하는지(상위 프레임까지 보는지, 리다이렉트 경로를 보는지)는 브라우저 문서 확인.
• None 은 Secure 가 필수입니다. 빠지면 쿠키 자체가 거부됩니다. 부록 C 의 lab_session 이 secure: true 를 고정한 이유입니다.

A.6 CORS 헤더

요청 헤더 (브라우저가 붙임, JS 가 바꿀 수 없음)

응답 헤더 (서버가 붙임)

이 값들은 부록 C api/src/main.ts 의 app.enableCors({ origin: config.webOrigins, credentials: true, methods: [...], allowedHeaders: [...] }) 에서 나옵니다. 허용 목록 밖의 출처가 보낸 사전 요청은 Access-Control-Allow-Origin 없이 응답되고, 브라우저가 본 요청을 보내지 않습니다(13장 S18).

$ curl -si -X OPTIONS http://localhost:4000/auth/refresh \
    -H 'Origin: http://localhost:5173' \
    -H 'Access-Control-Request-Method: POST' \
    -H 'Access-Control-Request-Headers: content-type,x-csrf-token'
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: http://localhost:5173
Vary: Origin
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET,POST,PATCH,DELETE
Access-Control-Allow-Headers: Content-Type,Authorization,X-CSRF-Token
…

(예시 출력. helmet 이 붙이는 헤더는 … 로 줄였습니다)

credentials 를 쓸 때의 제약

simple request 조건 — 사전 요청 없이 곧장 가는 요청

아래를 모두 만족하면 사전 요청 없이 본 요청이 서버에 도착합니다. 하나라도 어기면 사전 요청이 먼저 갑니다.

이 책의 요청을 대입하면:

참고: 브라우저가 붙이는 그 밖의 요청 헤더

A.7 이 앱의 보안 헤더 (helmet)

부록 C 의 main.ts 는 app.use(helmet()) 으로 helmet 의 기본 설정을 켭니다. helmet 8 이 기본으로 붙이거나 지우는 주요 헤더와 그 목적입니다. 정확한 기본값은 버전마다 바뀔 수 있으므로 값 열은 helmet 문서로 확인하세요. 여기 적은 값은 이해를 돕기 위한 대표값입니다.

helmet 이 붙이지 않고 앱이 직접 붙이는 헤더도 하나 있습니다.

⚠️ helmet 의 기본 CSP 는 API 가 직접 내려주는 HTML(Swagger UI /docs)에도 적용됩니다. Swagger UI 가 CSP 때문에 제대로 뜨지 않는다면 helmet 과 @nestjs/swagger 문서에서 두 설정의 조합을 확인하세요.

A.8 JWT 레퍼런스

header

등록 클레임 (RFC 7519) 과 이 책의 클레임

검증 측(verifyAccessToken)이 확인하는 것: 서명(secret), 알고리즘(algorithms: ['HS256']), exp, iss(issuer), aud(audience). 하나라도 실패하면 JwtAuthGuard 가 401 ACCESS_TOKEN_INVALID 로 바꿉니다.

A.9 HTTP 상태 코드와 에러 코드

에러 응답은 { statusCode, code, message } 모양입니다(ErrorResponseDto). FE 는 message 가 아니라 code 로 분기합니다. 코드 목록은 부록 C 의 api/src/common/errors.ts 의 ErrorCode 가 기준입니다.

성공 응답

에러 코드

검사 순서

한 요청이 여러 조건에 동시에 걸리면 먼저 검사한 쪽의 에러가 나갑니다. NestJS 는 가드를 파이프(DTO 검증)보다 먼저 실행하고, 가드는 @UseGuards 에 적은 순서대로 실행합니다.

💡 AppError 로 던지지 않은 에러, 예를 들어 없는 경로(404)나 JSON 문법이 깨진 본문(400), 예상하지 못한 서버 오류(500)는 NestJS 기본 모양으로 나가며 code 필드가 없습니다. FE 는 code 가 없는 에러도 처리할 수 있어야 합니다.

A.10 이 책의 API 가 쓰는 헤더 한눈에