feat(auth): readSubject 필수화로 토큰 갱신 시 서버 상태 캐시 유지 #3

Closed
donghyeon.kang wants to merge 1 commits from fix/session-subject-required into main
Owner

요약

세션 캐시 처리를 "안전하지만 투박한" 방식에서 식별값 기반 방식으로 바꿉니다.

  • 외부 인증 owner의 readSubject()가 필수가 됩니다(타입 + 부트 시 owner 검사). SessionGateway.getSubject()도 필수가 됩니다.
  • 토큰 갱신처럼 같은 사람·같은 상태의 알림은 캐시를 유지합니다. 사용자가 바뀌거나 로그아웃하면 지금처럼 캐시를 비웁니다.
  • 인증 상태인데 식별값이 null이거나 빈 문자열이면, 안전하게 캐시를 비우고 cache.operation.failed {operation: SCOPE_FENCE, reason: SUBJECT_MISSING} 진단을 남깁니다.
  • 문서: docs/architecture/starter-experience.md에 readSubject 규약(OIDC sub, Supabase session.user.id, Firebase user.uid 같은 값, 토큰 금지)과 마이그레이션 메모를 추가했습니다.

연동 쪽 breaking change

  • 외부 auth owner는 readSubject()를 구현해야 합니다. 없으면 시작할 때 세션이 integration-failed가 됩니다.
  • AuthSessionPort/SessionGateway를 직접 구현하는 코드는 getSubject()를 추가해야 합니다.

검증

  • 변경 전 RED 4건: readSubject 없는 owner가 받아들여짐, subject가 없어도 진단이 없음. 변경 후 모두 통과합니다.
  • 고정 테스트: 같은 subject 토큰 갱신은 캐시 유지, subject 변경과 로그아웃은 fence.
  • 통과한 게이트: check:architecture, check:types:app, check:types:test, lint, unit 2084, component 182, integration, reference-feature, verify:documentation, check:diagnostics, check:ci

🤖 Generated with Claude Code

## 요약 세션 캐시 처리를 "안전하지만 투박한" 방식에서 식별값 기반 방식으로 바꿉니다. - 외부 인증 owner의 `readSubject()`가 **필수**가 됩니다(타입 + 부트 시 owner 검사). `SessionGateway.getSubject()`도 필수가 됩니다. - 토큰 갱신처럼 같은 사람·같은 상태의 알림은 **캐시를 유지**합니다. 사용자가 바뀌거나 로그아웃하면 지금처럼 캐시를 비웁니다. - 인증 상태인데 식별값이 null이거나 빈 문자열이면, 안전하게 캐시를 비우고 `cache.operation.failed {operation: SCOPE_FENCE, reason: SUBJECT_MISSING}` 진단을 남깁니다. - 문서: `docs/architecture/starter-experience.md`에 `readSubject` 규약(OIDC `sub`, Supabase `session.user.id`, Firebase `user.uid` 같은 값, 토큰 금지)과 마이그레이션 메모를 추가했습니다. ## 연동 쪽 breaking change - 외부 auth owner는 `readSubject()`를 구현해야 합니다. 없으면 시작할 때 세션이 `integration-failed`가 됩니다. - `AuthSessionPort`/`SessionGateway`를 직접 구현하는 코드는 `getSubject()`를 추가해야 합니다. ## 검증 - 변경 전 RED 4건: readSubject 없는 owner가 받아들여짐, subject가 없어도 진단이 없음. 변경 후 모두 통과합니다. - 고정 테스트: 같은 subject 토큰 갱신은 캐시 유지, subject 변경과 로그아웃은 fence. - 통과한 게이트: check:architecture, check:types:app, check:types:test, lint, unit 2084, component 182, integration, reference-feature, verify:documentation, check:diagnostics, check:ci 🤖 Generated with [Claude Code](https://claude.com/claude-code)
donghyeon.kang added 1 commit 2026-09-24 07:27:04 +00:00
An external owner without readSubject made every authenticated
notification (every token refresh) abort requests and clear the
server-state cache. readSubject is now a required owner method and
getSubject a required SessionGateway method.

- ExternalSessionOwner.readSubject(): required; the host owner check
  (EXTERNAL_OWNER_METHODS) rejects an owner without it, so the session
  fails closed as integration-failed like any other missing method.
- SessionGateway.getSubject(): required. Anonymous and unavailable
  adapters return null; demo already returned its fixed user.
- Scope runtime: same (state, subject) still skips the fence; a state
  or subject change still fences. An authenticated session with a
  null/empty subject still fences (fail closed) and now records
  cache.operation.failed {operation: SCOPE_FENCE, reason:
  SUBJECT_MISSING} once per fence. Bootstrap passes diagnostics in.
- Docs: starter-experience external owner section and port comments
  describe what readSubject returns, the fail-closed diagnostic and a
  migration note.

RED before the change (vitest tests/unit/server-state-scope-runtime.test.ts
tests/unit/runtime-adapters.test.ts): 4 failed | 31 passed
- fails closed when the owner lacks readSubject:
  expected 'authenticated' to be 'integration-failed'
- fences and reports SUBJECT_MISSING ... null / empty subject, and the
  external owner whose readSubject returns null:
  expected [] to deeply equal [[{ level: 'warn', ... }]]
- type level: an owner literal without readSubject compiled (tsc exit
  0). The new @ts-expect-error pin fails check:types:test with TS2578
  if readSubject becomes optional again.
Pins that stayed green: same-subject token refresh keeps the cache,
subject change fences, sign-out fences, owner missing readState is
rejected.

GREEN: check:architecture, check:types:app, check:types:test, lint,
test:unit (2084), test:component (182), test:reference-feature (59),
test:integration (151), verify:documentation, check:diagnostics,
check:ci all pass.

BREAKING: external auth owners must implement readSubject(); code that
implements AuthSessionPort/SessionGateway directly must implement
getSubject().

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
donghyeon.kang added 1 commit 2026-11-05 10:33:29 +00:00
donghyeon.kang closed this pull request 2026-11-07 08:20:17 +00:00

Pull request closed

Please reopen this pull request to perform a merge.
Sign in to join this conversation.
No Reviewers
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: donghyeon.kang/clean-architecture-frontend-template#3