HTTP OPTIONS와 CORS Preflight 심층 리서치

OPTIONS /api/users HTTP/1.1     # 특정 리소스
OPTIONS * HTTP/1.1              # 서버 전체 (asterisk-form)

HTTP/1.1 204 No Content
Allow: OPTIONS, GET, HEAD, POST

<img src="https://bank.example/transfer?to=evil&amt=1000">
<form method="POST" action="https://bank.example/transfer">  <!-- CSRF -->
<script src="https://other.example/data.js">

L4  TCP 3-way handshake     SYN → SYN/ACK → ACK            (1 RTT)
L5  TLS 1.3 handshake       ClientHello → ServerHello...   (1 RTT)
──────────────── 여기까지가 "커넥션 핸드셰이크" ────────────────
L7  CORS preflight          OPTIONS → 204                  (1 RTT)  ← 열린 커넥션 위에서
L7  실제 요청                POST → 200                     (1 RTT)  ← 같은 커넥션 재사용

preflight 필요 ⟺
      request의 unsafe-request flag가 set
   OR method가 CORS-safelisted method가 아님
   OR CORS-unsafe request-header names가 비어있지 않음

accept-charset, accept-encoding, access-control-request-headers,
access-control-request-method, connection, content-length, cookie, cookie2,
date, dnt, expect, host, keep-alive, origin, referer, set-cookie, te,
trailer, transfer-encoding, upgrade, via
+ "proxy-" 로 시작하는 모든 헤더
+ "sec-" 로 시작하는 모든 헤더

method            = OPTIONS
URL               = 원 요청과 동일 (쿼리스트링 포함)
Origin            = initiator origin (tainted면 빈 origin)
Access-Control-Request-Method  = 원 요청 method
Access-Control-Request-Headers = CorsUnsafeNotForbiddenRequestHeaderNames()
                                 → safelist/forbidden 제외, 중복 제거,
                                   바이트 소문자화, **사전순 정렬** 후 콤마 조인
Sec-Fetch-Mode    = cors
credentials_mode  = kOmit      ← 쿠키/인증정보 절대 미포함
redirect          = error      ← "Preflight should not allow any redirect"

# ❌ Authorization 쓰는 요청은 통과 못 함
Access-Control-Allow-Headers: *

# ✅
Access-Control-Allow-Headers: *, Authorization

케이스 H: DELETE 요청, 서버는 Access-Control-Allow-Methods: POST, OPTIONS 만 응답

서버 로그:  OPTIONS /method-denied   ACRM=DELETE
            (끝. DELETE는 로그에 없음)
JS 결과:    TypeError: Failed to fetch

케이스 I: preflight는 정상, 실제 응답에만 Access-Control-Allow-Origin 누락

서버 로그:  OPTIONS /actual-missing-acao   → 204 (CORS 헤더 정상)
            POST    /actual-missing-acao   → 200 (ACAO 없음)   ← 실행됨!
JS 결과:    TypeError: Failed to fetch

F. /cached (Max-Age: 100) 로 POST json 3회
  OPTIONS /cached   ← 1회만
  POST    /cached
  POST    /cached
  POST    /cached

G. /uncached (Max-Age: 0) 로 POST json 3회
  OPTIONS /uncached
  POST    /uncached
  OPTIONS /uncached   ← 매번 다시
  POST    /uncached
  OPTIONS /uncached
  POST    /uncached

J. /cached 에 이번엔 Authorization 헤더까지 붙여 POST
  POST    /cached     ← preflight 없음!

Cache-Control: public, max-age=86400
Vary: Origin, Access-Control-Request-Method, Access-Control-Request-Headers

서버가 본 것:             ["OPTIONS /x", "POST /x"]
서비스 워커 fetch 이벤트:  [{ method: "POST", mode: "cors" }]   ← OPTIONS 없음

Cache-Control, Content-Language, Content-Length,
Content-Type, Expires, Last-Modified, Pragma

Access-Control-Expose-Headers: X-Total-Count, X-RateLimit-Remaining, Location

# 요청
Access-Control-Request-Private-Network: true
# 응답
Access-Control-Allow-Private-Network: true

// ⚠️ OPTIONS만 처리하면 실제 POST 응답에서 막힌다
export async function OPTIONS() {
  return new Response(null, { status: 204, headers: { /* ... */ } })
}

// app/api/_lib/cors.ts
const ALLOWED_ORIGINS = new Set([
  'https://xxx.github.io',
  ...(process.env.NODE_ENV === 'development' ? ['http://localhost:3000'] : []),
])

export function corsHeaders(req: Request): Headers {
  const h = new Headers()
  const origin = req.headers.get('origin')

  h.set('Vary', 'Origin')  // 오리진 에코백 시 필수

  if (origin && ALLOWED_ORIGINS.has(origin)) {
    h.set('Access-Control-Allow-Origin', origin)
    h.set('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS')
    h.set('Access-Control-Allow-Headers', 'Content-Type, Authorization')
    h.set('Access-Control-Expose-Headers', 'X-Total-Count')
    h.set('Access-Control-Max-Age', '86400')
    // 쿠키 인증을 쓸 때만
    // h.set('Access-Control-Allow-Credentials', 'true')
  }
  return h
}

// app/api/items/route.ts
import { corsHeaders } from '../_lib/cors'

export async function OPTIONS(req: Request) {
  return new Response(null, { status: 204, headers: corsHeaders(req) })
}

export async function POST(req: Request) {
  const body = await req.json()
  const res = Response.json({ ok: true })
  corsHeaders(req).forEach((v, k) => res.headers.set(k, v))  // ← 실제 응답에도
  return res
}

// middleware.ts — preflight에는 쿠키도 Authorization도 없다
export function middleware(req: NextRequest) {
  if (req.method === 'OPTIONS') return NextResponse.next()
  // ... 인증 로직
}

app.enableCors({
  origin: ['https://xxx.github.io'],
  methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
  allowedHeaders: ['Content-Type', 'Authorization'],
  exposedHeaders: ['X-Total-Count'],
  maxAge: 86400,
  credentials: true,
  preflightContinue: false,
  optionsSuccessStatus: 204,
})

CORS 에러 발생
  │
  ├─ 서버 로그에 OPTIONS가 찍혔나?
  │    ├─ 안 찍힘 → 요청이 서버까지 못 감
  │    │            · 앞단 프록시/WAF가 OPTIONS 차단
  │    │            · 3xx 리다이렉트로 죽음
  │    │            · 애초에 preflight 대상이 아니었음(다른 원인)
  │    │
  │    └─ 찍힘 → 응답 코드는?
  │         ├─ 401/403 → 인증 미들웨어가 OPTIONS를 막고 있음 (최빈)
  │         ├─ 405     → 프레임워크에 OPTIONS 핸들러 없음
  │         ├─ 3xx     → 리다이렉트. preflight는 절대 안 따라감
  │         └─ 2xx     → 헤더 내용 확인
  │                      · Allow-Methods에 실제 메서드 있나?
  │                      · Allow-Headers가 ACRH를 전부 커버하나?
  │                        (Authorization은 * 로 커버 안 됨)
  │                      · Allow-Origin이 Origin과 정확히 일치하나?
  │                        (스킴/포트/트레일링 슬래시까지)
  │
  └─ OPTIONS는 204인데 다음 요청에서 실패
       → 실제 메서드 응답에 CORS 헤더 누락 (§8)
       → credentials인데 Allow-Credentials 없거나 Allow-Origin이 *