Files
clean-architecture-backend-…/docs/notification/at-rest-threat-model.md
T
donghyeon-kaandClaude Opus 5.5 27f23add08 review-followup Wave 3: 설정 prefix app.* 통일(P20), Wave 3 종료
- 결정 16: `ca-skeleton.*`·`backend.graphql` 등 → `app.*`(APP_* env 키 이름 유지), selector 키 상수 하나(`CapabilitySelectors`),
  바인딩만 되던 `streaming-idle` 삭제
- `StrictSettingsBinder`가 env 오타까지 거부 — 모든 capability(graphql·websocket·mongo는 edge 제약으로 파일만 strict),
  httpclient 리플렉션 `HttpClientEnvironmentKeys` 삭제
- persistence-jpa가 `APP_DATASOURCE_PASSWORD` secret 요구를 기여(bootstrap이 JPA 스위치를 읽지 않음), Redis ACL fixture에서 pub/sub 권한 제거
- 결함 수정: SMTP 설정 env 이름 충돌(P20-new-1), `bindExcept`가 system env까지 filter(P20-new-2), graphql 빈 deployment-mode 메시지(P20-new-6)
- 통합: P30과 충돌 11건(P30의 명시적 bean 구조 유지), P30 코드의 옛 키를 app.*로, persistence-jpa 포맷
- 현황표: 소유자 결정 36(persistence-jpa 설정은 플랫폼 키만 app.persistence-jpa.*로, 공유 기능 트리 예외), 재개 문서에 일시 정지 상태

Wave 3 종료 검증: check · ci verifyDependencyLocks --warning-mode=fail(714 task) · mainCheck · architectureCheck
verifyPublicPathSnapshot :app-bootstrap:verifyEnvKeys configContractCheck · :app-bootstrap:integrationTest
:sample-portfolio:integrationTest :sample-portfolio:systemTest · integrationCheck · -p build-logic test ·
-p optional-platforms ci · :app-bootstrap:qualificationBootJar releaseCheck 통과

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-29 17:01:54 +09:00

6.9 KiB

Notification payload at rest — threat model and decision (NTF-INT-007)

Wave 2 Task D6 offers two branches and requires that one be chosen and implemented fully:

  • (a) encryption — a codec/port, ciphertext envelope, key id, rotation and history, row migration, and a decryption-failure contract;
  • (b) restriction — this document plus a static restriction proving the variable types cannot carry sensitive values.

The plan recommends (b) "if and only if the variable types can genuinely be restricted to non-sensitive values". They cannot. This document records why, what that leaves, and when the remaining branch lands.

What is stored, and where

CanonicalNotificationPlanWriter.request(...) puts encoded.variablesPayload() into NotificationRequestRecord verbatim. JpaNotificationRequestStore writes that record to notification_request.variables_payload with no transformation. There is no encryption anywhere on this path.

Why the restriction branch is unavailable

Template variables are a closed algebra — NotificationVariable permits TextValue, NumberValue, BooleanValue, NullValue, ListValue, ObjectValue — which is a real improvement over the Map<String, Object> it replaced. But TextValue holds an arbitrary UTF-8 string of up to 8 KiB, and that is not an oversight to be tightened: the variables are the recipient-specific content of the message. A password-reset code, an order total, a delivery address, a patient's appointment time — those are what a notification is for.

A restriction to "non-sensitive values" would therefore be one of two things, and both are worse than the problem:

  • unenforceable — a comment saying callers should not put sensitive data in a field designed to carry the message's content, which is a policy no type checks and no reviewer can see violated;
  • enforced and useless — a type that refuses free text, which does not restrict the capability so much as delete it.

The precondition on the plan's recommendation is false. Branch (b) is not available.

Status: branch (a) implemented at the storage boundary. NotificationPayloadProtection is the application-owned port, AesGcmNotificationPayloadProtection the AES-GCM implementation, and NotificationRecordMapper applies it — as a required constructor argument, so a composition cannot assemble the notification stores while leaving the payload in plaintext. What remains before the facade can be imported is the row migration for any deployment that already has plaintext rows, and the local-notification-* lanes. The analysis below is kept as written, because it is what the decision rests on.

Decision: branch (a), landing with the persistence wiring

Encryption is therefore the required branch. Its scope is unchanged from the plan: a codec behind an application port, a ciphertext envelope carrying its key id, key rotation with history so an old row stays readable, a migration for existing rows, and an explicit contract for what a decryption failure does to a request.

It lands in the change unit that makes the write path reachable, and not before. The reason is a fact the spec did not have: NotificationJpaPersistenceFacade, which assembles JpaNotificationRequestStore, is imported by nothing. The composition root's component scan excludes the persistence package by design, and no configuration imports the facade — so the notification capability has no JPA persistence at all, and no deployment currently writes this payload anywhere. The defect is real in the code and latent in the runtime.

Designing key rotation and a row migration for rows that no deployment produces would be building the migration before the table. Worse, it would settle the envelope's shape before the store that has to read it is wired, which is the order that produces an envelope the store cannot use.

One correction, learned by trying it. This section said the envelope "lands with the wiring". Wiring the facade first — to register the SMTP assembler — made NotificationPayloadAtRestContractTest fail on the case asserting the write path is reachable from no composition, which is exactly what that case is for. The wave forbids connecting wiring over a known security finding on a runtime path, so the wiring was reverted and the envelope built first. The honest ordering is envelope before or with the wiring, never after, and the contract test now enforces it by failing on the wiring alone.

The envelope, and why it has a key id

byte     version        always 1
byte     keyIdLength    1..255 UTF-8 bytes
byte[]   keyId
byte[12] nonce
byte[]   ciphertext + GCM tag

The key id is the reason there is a format at all. This repository's callback protection stores nonce and ciphertext and nothing else, so the day the active key changes, every row written under the previous one becomes unreadable and nothing in the row can say which key it needed — that is not a rotation story with a gap in it, it is the absence of one. SecretMaterialProvider already exposes keyById, so reading the id back and asking for that specific key makes rotation a change of default rather than a data migration. The version byte costs one byte and is what allows the format to change at all.

The header is passed as AAD, not merely prefixed: without that, the key id is attacker-editable and an envelope could be redirected at a key of the attacker's choosing.

A failed decryption throws NotificationPayloadUnreadableException rather than returning empty. A caller handed an empty payload renders every variable as nothing and sends "Hello , your code is " to a real person — the failure delivered instead of reported. All three causes (unknown key, wrong key, modified ciphertext) collapse into one message, because telling them apart tells an attacker which of the three they achieved.

What must not be done instead

Requiring PAYLOAD_ENCRYPTION in INGEST_ONLY is not a fix. That secret is consumed by exactly one thing — AesGcmCallbackPayloadProtection, which protects raw callback bodies — and by nothing on the accept path. Demanding it would make a deployment supply a key that protects nothing while the payload it appears to be about stays in plaintext. The repository already has one defect of that exact shape: app.graphql.cursor.key-ids (key removed 2026-09-25), which production refuses to start without and which no code signs a cursor with (GQL-INT-003). Adding a second would make the pattern a habit.

Consequence

Notification is not promoted to Stable, per the index's scope boundaries, until branch (a) is complete. The three notification Compose lanes stay non-blocking. NotificationPayloadAtRestContractTest holds every fact this decision rests on, so the decision expires automatically if any of them stops being true — in particular, the assertion that no encryption sits on the accept path fails the moment somebody adds one, which is the change this document is waiting for.