Files
clean-architecture-backend-…/docs/design/2026-08-02-redis-session-http-boundary-design.md
T
DongHyeonka 74108497d4 docs(records): 기록과 ADR 맨 위에 한국어 머리 블록을 단다
문제: 설계서·계획서·납품 패키지·증거·학습 문서와 ADR이 기록이라는 표시
없이 지금 문서처럼 읽힌다. 상태 칸이 설계서 72개 중 40개, 계획서는
거의 없고, 있어도 Approved·확정·Accepted.처럼 값이 제각각이며 영어다.

고른 방법: docs/design, docs/history, docs/adr, docs/notification/adr의
.md 246개 맨 위에 같은 모양의 머리 블록을 단다. 칸은 상태·작성일·
요약(한국어 한 문장)·현재 정본, 대체됐으면 대체됨이다. 블록은 표시 줄
두 개로 감싸서 빼면 원문 바이트가 그대로 돌아온다(246개 모두 대조함).
- 종류는 폴더가 정하고 둘째 줄에 적는다(plans/evidence는 증거).
- 상태는 원래 상태 줄을 고정 어휘로 바꾼 값이다. 상태 줄이 없는
  설계서와 체크 상자가 다 표시되지 않은 계획서는 「확인 안 함」.
  capability-status.md 제거 표로 지운 것이 확인된 설계서 다섯은 「폐기」,
  2026-07-20 하네스 설계·계획과 production capability platform 설계는
  「대체됨」이다.
- 현재 정본은 구조 정리로 옮겨질 수 있는 src/messaging·src/grpc 대신
  docs/ 쪽 문서나 옮기지 않는 leaf README를 가리킨다.
docs/README.md에 「문서 수명과 언어」「기록 문서의 머리 블록」「문서와
코드를 같은 변경에서 고친다」를 더하고, 파생 서비스 안내에 머리 블록
충돌 가능성을 적었다.

버린 대안: H1 제목 아래에 블록을 두는 안은 보기에는 낫지만 빼는 규칙이
파일마다 달라져 원문 복원이 기계적이지 않다. 「종류」 칸을 따로 두는
안은 폴더와 같은 정보를 두 번 쓰게 한다.

위험·한계: 「확인 안 함」 설계서 38개, 계획서 51개는 지금 유효한지
아무도 판정하지 않았다. 요약은 제목·목표 줄을 보고 쓴 것이라 본문을
끝까지 읽지 않았다. 납품 패키지 셋의 MANIFEST.sha256는 이제 맞지 않는다
(납품 당시 바이트의 해시이고, 블록을 빼면 다시 맞는다). 리뷰 폴더에는
아직 머리 블록을 달지 않았다.

검증: 머리 블록을 뺀 내용과 HEAD 원본 246개 일치, check-work-docs.py
rc=0, --links docs·README.md·CLAUDE.md·AGENTS.md 깨진 링크 0.
2026-11-07 12:23:32 +09:00

5.0 KiB

기록 · 설계서 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.

  • 상태: 채택
  • 작성일: 2026-08-02
  • 요약: Redis 세션과 HTTP 경계에서 브라우저 세션 보안이 유지되고 실패 시 닫히는지 증명하는 설계다.
  • 현재 정본: docs/redis/support-matrix.md

Redis Session HTTP Boundary Design

Date: 2026-08-02 Status: approved by the user's instruction to apply the reviewed P1/P2 work sequentially Scope: composition of inbound browser-session security with the outbound versioned Redis session repository

Context

Inbound-web unit contracts prove CSRF, fixation, hardened cookie settings, and primitive security snapshot behavior with MockHttpSession/in-memory repositories. Cache-redis contracts prove the versioned session repository and Lua semantics against Redis. No test currently crosses the actual Spring Session filter, production SecurityFilterChain, real Redis, and a second application context.

Putting this test in inbound-web would require a forbidden dependency on the outbound Redis leaf. The composition root already depends on both leaves and owns the redisCompositionTest source set, so app-bootstrap is the correct boundary owner.

Decision

Add a tagged redis-session-http integration contract under app-bootstrap's existing redisCompositionTest source set. Ordinary redisCompositionTest excludes the tag. A new explicit redisSessionHttpIntegrationTest task includes only that tag, fails on no discovery or any skip, always reruns, pins UTC, and passes the checked-in Redis image registry path.

The task is deliberately not attached to ordinary local check, because it requires Docker. It is added to the existing release-blocking redis-standalone CI job, which is the Docker-capable Redis lane. Docker availability and container startup are attempted directly; no condition, assumption, or environment flag may convert absence into a skip.

The test loads redis.approved.image from src/gradle/redis-test-images.properties and rejects an unpinned reference. It creates an ephemeral CA/server certificate and a named, least-privilege ACL user, then connects with TLS, full hostname verification, and explicit CA trust. A runtime-generated Redis password and 32-byte HMAC are supplied through caller-owned versioned material; no secret value is checked in, passed on the Redis command line, or logged. Missing Docker or OpenSSL is a hard failure, not a skip.

The custom source set needs the Spring Session API at compile time. App-bootstrap therefore adds spring-session-core only to redisCompositionTestImplementation; the existing version is reused and the lockfile records the new custom compile configuration without changing a dependency version.

HTTP/Session Contract

  1. A state-changing request without CSRF is 403.
  2. Accessing the CSRF endpoint emits the configured Secure, non-HttpOnly CSRF cookie.
  3. Login with matching cookie/header creates only the bounded primitive authentication snapshot.
  4. The session cookie is host-only, Secure, HttpOnly, SameSite=Lax, path /, and session-scoped.
  5. After the first web context closes, a second independent context restores /whoami from the same cookie through real Redis.
  6. Logout force-revokes/tombstones the session; the old cookie is unauthenticated and a previously loaded stale session object cannot save over the tombstone.
  7. If Redis becomes unavailable during session lookup, the request fails closed before the protected controller and the surfaced exception graph contains only the repository's fixed availability message, not endpoint/password/session material.

The RED run exposed two production composition gaps which are part of this boundary:

  • the primitive security-context repository must wrap the response and persist before response commit, otherwise a successful response can commit before the first session is created;
  • the API security chain disables Spring Security's request cache, otherwise an unauthenticated request stores a DefaultSavedRequest framework graph that the primitive session codec correctly rejects.

Architecture

  • Inbound-web remains provider-neutral and has no outbound dependency.
  • Cache-redis keeps Redis keys, Lua, codec, HMAC, and tombstone policy private.
  • App-bootstrap assembles both adapters only for a cross-module composition contract.
  • No production dependency edge or dependency version changes; only a custom-test compile configuration is added to the existing lock entry.

Non-Goals

  • Redis Sentinel/Cluster sessions (production activation explicitly rejects them today);
  • browser-engine proof of SameSite behavior;
  • credential/certificate rotation qualification (the fixture still uses mandatory TLS, full hostname verification, explicit trust, and a named ACL user);
  • attaching Docker work to ordinary check;
  • staging, commit, amend, or push by an agent.