[G1-Sync] Manual knowledge update

10_Wiki/Topics/Coding/Security_CSRF_Patterns.md

@@ -0,0 +1,130 @@
+---
+id: security-csrf-patterns
+title: CSRF — Cookie 인증의 함정
+category: Coding
+status: draft
+source_trust_level: B
+verification_status: conceptual
+created_at: 2026-05-09
+updated_at: 2026-05-09
+tags: [security, csrf, cookies, vibe-coding]
+tech_stack: { language: "TypeScript / Express", applicable_to: ["Web"] }
+applied_in: []
+aliases: [Cross-Site Request Forgery, SameSite, double submit, CSRF token]
+---
+
+# CSRF — Cookie 인증의 함정
+
+> Cookie 가 자동 전송되는 점을 노린 공격. **SameSite=Strict/Lax** 가 1차 방어, **CSRF token (double submit)** 이 2차. **Authorization header (JWT in memory)** 사용 시엔 CSRF 자체가 거의 무관.
+
+## 📖 핵심 개념
+공격자: `evil.com` 의 form 이 자동으로 `bank.com/transfer` 로 POST. 사용자 cookie 가 자동 첨부 → 인증 통과.
+
+방어:
+- **SameSite cookie**: 다른 origin 에서 cookie 안 보냄.
+- **CSRF token**: 매 form 마다 고유 token, 서버가 cookie 와 form 두 곳 비교.
+- **Origin / Referer header 검증**: 보조.
+- **JWT in Authorization header (cookie 아님)**: CSRF 자동 면역.
+
+## 💻 코드 패턴
+
+### SameSite cookie (1차 방어)
+```ts
+res.cookie('session', token, {
+  httpOnly: true,
+  secure: true,
+  sameSite: 'strict', // 또는 'lax' (top-level GET 허용)
+  path: '/',
+  maxAge: 7 * 24 * 60 * 60 * 1000,
+});
+```
+
+`Strict`: cross-site 어떤 요청도 cookie 안 감. 외부 링크 클릭으로 들어와도 cookie X (UX 영향).
+`Lax`: top-level GET 만 OK. 폼 POST / iframe 차단.
+`None`: cross-site OK — `Secure` 필수. 거의 안 씀.
+
+### Double submit cookie (CSRF token)
+```ts
+import csrf from 'csurf';
+app.use(csrf({ cookie: true }));
+
+// 페이지 렌더 시
+app.get('/dashboard', (req, res) => {
+  res.render('dashboard', { csrfToken: req.csrfToken() });
+});
+// → form 안에 <input type="hidden" name="_csrf" value="...">
+
+// 모든 POST 가 자동 검증
+app.post('/transfer', (req, res) => {
+  // csurf 가 이미 검증
+  doTransfer(req.body);
+});
+```
+
+### Custom header — SPA
+```ts
+// CSRF token을 cookie + JS-readable form 둘 다.
+// SPA 가 fetch 시 X-CSRF-Token 헤더로 전송.
+res.cookie('csrf_token', token, { httpOnly: false, sameSite: 'strict', secure: true });
+
+// 서버 검증
+app.use((req, res, next) => {
+  if (['POST', 'PUT', 'DELETE', 'PATCH'].includes(req.method)) {
+    const cookie = req.cookies.csrf_token;
+    const header = req.header('x-csrf-token');
+    if (!cookie || cookie !== header) return res.status(403).end();
+  }
+  next();
+});
+
+// 클라이언트
+fetch('/api/x', {
+  method: 'POST',
+  headers: { 'X-CSRF-Token': getCookie('csrf_token') },
+  credentials: 'include',
+});
+```
+
+### Origin / Referer 검증 (보조)
+```ts
+const allowedOrigins = ['https://app.example.com'];
+app.use((req, res, next) => {
+  if (req.method !== 'GET') {
+    const origin = req.header('origin');
+    if (!origin || !allowedOrigins.includes(origin)) return res.status(403).end();
+  }
+  next();
+});
+```
+
+## 🤔 의사결정 기준
+| 인증 방식 | CSRF 위험 |
+|---|---|
+| Cookie (session) | ✅ 위험 — SameSite + token |
+| Authorization: Bearer (memory) | ❌ 거의 무관 (XSS 가 진짜 위험) |
+| Cookie + Authorization 혼용 | 둘 다 점검 |
+| OAuth implicit (deprecated) | 별도 위험 |
+
+| API 종류 | 보호 |
+|---|---|
+| Same-origin SPA + cookie | SameSite + token |
+| Cross-origin SPA + cookie | SameSite=None + Secure + token + Origin 검증 |
+| Mobile app | Bearer token (cookie 아님) |
+| Public read API | CSRF 불필요 |
+
+## ❌ 안티패턴
+- **GET 으로 mutation**: GET 은 CSRF token 검증 안 하는 경우 많음. 항상 POST/PUT/DELETE.
+- **모든 cookie SameSite=None**: cross-site 무방비. 실제 필요한 경우만.
+- **CSRF token 을 GET response 의 body 에**: 다른 origin 이 fetch 못 보는 동안 OK 지만 캐시되면 누설.
+- **token 검증 timing attack**: `===` 대신 constant-time compare.
+- **세션과 token 불일치 무시**: 그냥 통과.
+- **Referer 만 의존**: 일부 브라우저 / 프록시 가 strip.
+- **CSRF token 을 URL query 에**: 로그 / referer 누설.
+
+## 🤖 LLM 활용 힌트
+- Cookie auth = SameSite + double submit token + Origin 검증 3종.
+- Bearer token (memory) 가 SPA 의 더 단순한 답.
+
+## 🔗 관련 문서
+- [[Web_JWT_Patterns]]
+- [[Security_Output_Encoding_XSS]]