---
id: web-jwt-patterns
title: JWT 패턴 — 토큰 저장 / 만료 / 회전
category: Coding
status: draft
source_trust_level: B
verification_status: conceptual
created_at: 2026-05-09
updated_at: 2026-05-09
tags: [web, auth, jwt, security, vibe-coding]
tech_stack: { language: "Any backend / browser", applicable_to: ["Web", "Mobile"] }
applied_in: []
aliases: [access token, refresh token, httpOnly cookie, token rotation]
---

# JWT 패턴

> JWT 자체는 무상태 보안 도구일 뿐. 진짜 어려운 건 **어디 저장? 만료? 회전? 무효화?**. 잘못 저장하면 XSS 한 방으로 토큰 털림.

## 📖 핵심 개념
- **Access token**: 짧은 만료 (5~15분), API 호출 권한.
- **Refresh token**: 긴 만료 (1~30일), access 재발급 용. **회전 (rotation) 필수**.
- 저장 위치 트레이드오프:
  - localStorage: XSS 취약. 절대 비추.
  - sessionStorage: 탭 닫으면 사라짐. 사용자 경험 나쁨.
  - **httpOnly + Secure + SameSite cookie**: XSS 차단. 권장.
  - 메모리 (변수): 새로고침에 사라짐. + httpOnly cookie 로 refresh.

## 💻 코드 패턴

### 1. Access in memory + Refresh in httpOnly cookie
```ts
// 로그인 응답
res.cookie('rt', refreshToken, {
  httpOnly: true, secure: true, sameSite: 'strict',
  maxAge: 7 * 24 * 60 * 60 * 1000, path: '/api/auth/refresh',
});
res.json({ accessToken });

// 클라이언트
let access = data.accessToken; // memory only
fetch('/api/me', { headers: { Authorization: `Bearer ${access}` } });
```

### 2. Access 만료 시 자동 refresh
```ts
async function authedFetch(input: RequestInfo, init: RequestInit = {}) {
  let res = await fetch(input, withAuth(init, access));
  if (res.status !== 401) return res;
  // refresh
  const r = await fetch('/api/auth/refresh', { method: 'POST', credentials: 'include' });
  if (!r.ok) throw new Error('session expired');
  access = (await r.json()).accessToken;
  return fetch(input, withAuth(init, access));
}
```

### 3. Refresh token rotation
```ts
// 서버: refresh 호출 시 새 refresh 발급 + 옛 것 무효화
app.post('/api/auth/refresh', async (req, res) => {
  const old = req.cookies.rt;
  const session = await db.sessions.find({ refreshToken: old });
  if (!session || session.revokedAt) return res.status(401).end();

  // 옛 것 invalidate
  await db.sessions.update(session.id, { revokedAt: new Date() });

  // 새 발급
  const newRt = signRefresh({ userId: session.userId });
  await db.sessions.create({ userId: session.userId, refreshToken: newRt });

  res.cookie('rt', newRt, cookieOpts);
  res.json({ accessToken: signAccess({ userId: session.userId }) });
});
```

## 🤔 의사결정 기준
| 환경 | 저장 |
|---|---|
| Web SPA | access in memory + refresh in httpOnly cookie |
| SSR (Next.js) | session cookie + 서버에서 access 발급 |
| Mobile (RN/iOS/Android) | secure storage (Keychain/Keystore) |
| 서버-서버 | 짧은 access, OAuth client credentials |

## ❌ 안티패턴
- **localStorage 에 access token 저장**: XSS 한 방으로 탈취. 사고.
- **Refresh token rotation 안 함**: 한 번 탈취되면 영원히 유효. rotation + reuse detection.
- **JWT signature 만 검증, 만료 안 봄**: 만료 토큰 통과. exp / nbf 모두 검증.
- **JWT payload 에 비밀 정보**: payload 는 base64 — 누구나 디코드. 비밀 X.
- **장시간 access token (24h+)**: 탈취 시 피해 커짐. 짧게 + refresh.
- **로그아웃 시 토큰 무효화 안 함**: stateless 라 어렵지만 refresh 무효화는 DB 레벨로.
- **CSRF 보호 누락 (cookie auth)**: SameSite=strict + CSRF token.

## 🤖 LLM 활용 힌트
- 인증 코드 작성 시 "access in memory + refresh in httpOnly cookie + rotation" 패턴 강제.
- LLM 이 localStorage 사용하려 하면 막기.

## 🔗 관련 문서
- [[Web_CORS_Practical_Guide]]
- [[Idempotent_Operations]]