ADR-008 API Key 라이프사이클 = 해시 저장 + id 기반 조회 + 즉시 무효화

• 상태: 채택
• 날짜: 2026-07-03
• 근거: PRD FR-3/FR-6/FR-9 / TDD “인터페이스 시그니처”·“상태 전이 표” / AS-IS McpTokenAuthenticationFilter

맥락

Partner API Key의 저장·조회·발급·재발급·폐기·상태 검증 방식을 확정한다. 기존 mcp 토큰 인증 필터가 검증된 패턴을 제공한다.

결정

1. 형식: partner_<keyId>_<random> (256-bit URL-safe random). mcp_<id>_<random> 패턴 답습.
2. 저장: 해시만 저장(PasswordEncoder=BCrypt 재사용). 평문은 발급 시 1회 응답으로만 노출, 재조회 불가.
3. 조회: 요청 키에서 keyId를 파싱 → findById(keyId) → matches(plain, keyHash). 전수 스캔 없음.
4. 재발급: 구 ACTIVE 키 즉시 REVOKED + 신규 ACTIVE 발급(UseCase @Transactional). FR-6.
5. 폐기: ACTIVE → REVOKED. REVOKED 키 인증 시도는 401.
6. 상태 코드: 무효/불일치/REVOKED 키 → 401. 키는 유효하나 파트너 SUSPENDED → 403(신원 확인됨, 접근 거부). FR-9.
7. 즉시 반영: 필터가 요청마다 DB status 확인(캐시 없음) → 폐기 후 즉시 차단(<1분 NFR 충족).

근거

• 해시 저장·평문 1회 노출·prefix 식별은 Stripe/GitHub API Key 관행(TDD 벤치마킹).
• id 파싱 후 PK 조회는 O(1) — 전수 BCrypt 매칭 회피.
• 캐시 미도입은 폐기 즉시성(FR “1분 이내”)을 단순하게 보장. 1000건/일 규모에 DB 확인 비용 무시 가능.

대안 (미채택)

• 평문 저장: 유출 시 즉시 악용 — 금지.
• 전 키 스캔 매칭: BCrypt 비용 O(n) — 미채택.
• 만료 유예(grace) 롤: 지금 규모 불필요 — 즉시 무효화만.
• SUSPENDED도 401: 신원이 확인된 상태이므로 403이 의미상 정확.

영향

• ApiKeyGenerator gateway(random/hash/matches) + PartnerApiKey Rich Entity(revoke/recordUsage/isActive).
• 재발급 API 재호출은 비멱등(매번 신규 키) — 의도적. 롤백: 재발급 실패 시 트랜잭션 롤백으로 구 키 ACTIVE 유지.