Files
clean-architecture-backend-…/docs/notification/at-rest-threat-model.md
T
DongHyeonka 5a860e1e6b docs(notification): 알림 운영 문서를 한국어로 옮기고 코드와 맞춘다
문제: `docs/notification`의 살아 있는 문서 10개가 영어였다. 번역하며 대조하니
설정 참조와 위협 모델이 지금 코드와 다른 말을 했다.

고친 것:
- 10개를 번역했다(ADR은 다른 세션 몫이라 두었다). 코드·설정 키·환경 변수·표 구조는
  그대로다.
- 코드에 맞춘 주장:
  - configuration-reference: 바인딩에 없는 `callbacks.trusted-proxies`
    (`APP_NOTIFICATION_PLATFORM_CALLBACK_TRUSTED_PROXIES`)를 지우고 실제 방법
    (`APP_SERVER_FORWARD_HEADERS_STRATEGY=native`, `server.tomcat.remoteip.internal-proxies`)을
    적었다. 근거는 `notification.yml` 주석과 env-keys registry다.
  - at-rest-threat-model: 「facade를 아무도 import하지 않아 JPA 영속성이 없다」는 낡았다.
    지금은 persistence-notification의 `AutoConfiguration.imports`가 facade를 올리고,
    `NotificationPayloadAtRestContractTest`가 그것을 단언한다. 지금 상태를 앞에 쓰고
    결정 당시 분석은 `> 이력` 블록으로 옮겼다. 설정 참조와 YAML이 「교체 순서는 이
    문서에 있다」고 하는데 없어서, `historical-keys`와 `SettingsSecretMaterialProvider`
    대로 짧은 교체 순서를 더했다.
  - module-mapping: plan API 모듈의 leaf `application-core` → `application-notification`,
    「19 leaf」 → registry, relay 조립 `app-bootstrap` → `composition:outbox-relay`, 남은
    provider 패키지는 `ses`·`smtp`뿐.
- `support-matrix.md`: 등급 칸 제목을 `등급`으로, 거부 절을 「## 지원하지 않는 것」으로
  옮겼다. 등급 값(manifest의 키)은 그대로다.
- 테스트: `NotificationEvidenceVerifier`가 `Grade` 대신 `등급` 칸을 읽는다(영어 칸만
  있으면 「등급을 매기는 표가 없다」로 닫힌 채 실패한다). `NotificationReleaseGateTest`는
  거부 절 제목과 전달 보장·읽음 보장·정확히 한 번을 단언하고, 앞 절에는 한국어와 영어
  표현이 모두 없어야 한다. `DEVICE_DELIVERED`·`DELIVERED` 승격 거부 문장도 한국어로 본다.
- 예외 목록에서 알림 language 줄 10개를 지웠다.

버린 대안: 등급 칸 제목을 `Grade`로 두기. 검증기가 읽는 키라서 바꾸지 않아도 됐지만,
한국어 문서에 영어 칸 하나가 남고 그 이유를 문서에 따로 적어야 한다. 검증기의 상수
하나를 바꾸는 쪽이 작다.

위험·한계: 위협 모델은 결정 기록 성격이 섞인 살아 있는 문서다. 결정 당시 글은
`> 이력` 블록에 뜻을 그대로 옮겼다.

검증: 최종 트리 기준(첫 커밋 본문 참고).

검증(desktop, 최종 트리 8295db89):
- `:adapter:outbound:notification:check` rc=0(375개 건너뜀 1 실패 0. `NotificationReleaseGateTest` 3,
  `NotificationEvidenceVerifierTest` 7, `NotificationModeSsotTest` 3, `NotificationPayloadAtRestContractTest` 5),
  `:mainCheck` rc=0(`notificationDocumentContractTest`의 저장소 문서 대조 통과), `testQualityCheck` rc=0.
- RED: 기준 커밋의 옛 문서에 대면 `NotificationReleaseGateTest` 2개와 저장소 문서 대조가 실패한다
  ("support-matrix.md has no table that assigns a grade (a '등급' column …)").
2026-11-07 17:56:34 +09:00

8.0 KiB

저장된 알림 payload — 위협 모델과 결정 (NTF-INT-007)

결론: 템플릿 변수(payload)는 저장소 경계에서 암호화한다(branch (a)). 변수를 「민감하지 않은 값」으로 제한하는 길 (branch (b))은 쓸 수 없다. 변수가 곧 메시지의 내용이기 때문이다.

Wave 2 Task D6은 두 길을 주고, 하나를 골라 끝까지 구현하라고 요구했다.

  • (a) 암호화 — codec·port, 암호문 envelope, key id, 교체와 이력, 행 마이그레이션, 복호화 실패 계약.
  • (b) 제한 — 이 문서, 그리고 변수 타입이 민감한 값을 담을 수 없음을 보이는 정적 제한.

계획은 「변수 타입을 정말로 민감하지 않은 값으로 제한할 수 있을 때만」 (b)를 권했다. 제한할 수 없다. 이 문서는 그 이유와, 그래서 고른 (a)가 지금 어떻게 들어가 있는지를 적는다.

지금 상태

  • NotificationPayloadProtection이 애플리케이션이 가진 port이고, AesGcmNotificationPayloadProtection이 AES-GCM 구현이다.
  • NotificationRecordMapper가 그것을 필수 생성자 인자로 받아 적용한다. 그래서 payload를 평문으로 둔 채 알림 저장소를 조립할 수 없다.
  • 쓰기 경로는 조립에서 닿는다. NotificationJpaPersistenceFacade는 persistence-notification leaf의 AutoConfiguration.imports가 올린다.
  • 평문 행이 이미 있는 배포는 마이그레이션에서 멈춘다. V10__variables_payload_envelope_guard.sql은 행을 다시 암호화하지 않고, 보호되지 않은 행이 있으면 실패한다.
  • NotificationPayloadAtRestContractTest가 이 문서가 기대는 사실을 모두 단언한다. 하나라도 거짓이 되면 그 테스트가 실패하므로, 결정이 저절로 낡지 않는다.
  • 알림은 Stable이 아니다(docs/notification/support-matrix.md).

무엇이 어디에 저장되나

CanonicalNotificationPlanWriter.request(...)는 encoded.variablesPayload()를 그대로 NotificationRequestRecord에 넣는다. 애플리케이션은 그것을 렌더링해야 하므로 여기서는 평문이 맞다. 「저장된(at rest)」은 행 안을 뜻하므로 envelope는 여기가 아니라 저장소 경계에서 씌운다. notification_request.variables_payload에는 base64 AES-GCM envelope가 들어간다.

제한 가지를 쓸 수 없는 이유

템플릿 변수는 닫힌 대수다. NotificationVariable은 TextValue, NumberValue, BooleanValue, NullValue, ListValue, ObjectValue만 허용한다. 이것이 대신한 Map<String, Object>보다 확실히 낫다. 그러나 TextValue는 8 KiB까지의 아무 UTF-8 문자열을 담고, 그것은 조여야 할 실수가 아니다. 변수는 메시지의 수신자별 내용이다. 비밀번호 재설정 코드, 주문 합계, 배송 주소, 환자의 예약 시각, 알림은 그것을 보내려고 있다.

그래서 「민감하지 않은 값」으로의 제한은 둘 중 하나가 되고, 둘 다 문제보다 나쁘다.

  • 강제할 수 없음 — 메시지 내용을 담으려고 만든 칸에 민감한 데이터를 넣지 말라는 주석. 어떤 타입도 확인하지 않고, 어떤 리뷰어도 위반을 볼 수 없는 정책이다.
  • 강제하지만 쓸모없음 — 자유 텍스트를 거부하는 타입. capability를 제한한다기보다 지운다.

계획의 권고에 붙은 전제가 거짓이다. (b)는 쓸 수 없다.

envelope와 key id를 두는 이유

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

형식을 두는 이유는 key id다. 이 저장소의 콜백 보호는 한때 nonce와 암호문만 저장했다. 그러면 활성 키가 바뀌는 날 앞 키로 쓴 행은 모두 읽을 수 없게 되고, 행 안의 어떤 것도 어느 키가 필요했는지 말하지 못한다. 틈 있는 교체가 아니라 교체가 없는 것이다. SecretMaterialProvider가 이미 keyById를 드러내므로, id를 다시 읽어 바로 그 키를 달라고 하면 교체는 데이터 마이그레이션이 아니라 기본값 변경이 된다. version 바이트는 1바이트이고, 형식을 바꿀 수 있게 해 준다.

header는 앞에 붙이기만 하는 것이 아니라 AAD로 넘긴다. 그러지 않으면 공격자가 key id를 고쳐 envelope를 자기가 고른 키로 돌릴 수 있다.

복호화에 실패하면 빈 값을 돌려주지 않고 NotificationPayloadUnreadableException을 던진다. 빈 payload를 받은 호출자는 모든 변수를 빈 값으로 렌더링해 실제 사람에게 "Hello , your code is "를 보낸다. 실패를 보고하는 대신 실패를 배달하는 것이다. 세 원인(모르는 키, 틀린 키, 고쳐진 암호문)은 한 메시지로 합친다. 셋을 구별해 주면 공격자에게 셋 중 무엇을 해냈는지 알려 주기 때문이다.

키 교체 순서

설정 키는 app.notification.platform.secrets 아래에 있다(notification.yml).

  1. 새 키 값과 새 key id를 같은 배포에서 바꾼다(예: APP_NOTIFICATION_PLATFORM_PAYLOAD_ENCRYPTION_KEY와 APP_NOTIFICATION_PLATFORM_PAYLOAD_ENCRYPTION_KEY_ID). 고정된 id는 교체를 앞 키와 구별할 수 없게 한다.
  2. 같은 배포에서 밀려난 키 값을 historical-keys.<목적>.<옛 id> 아래에 둔다(예: historical-keys.PAYLOAD_ENCRYPTION.payload-2026-01). 목적은 id에서 알아낼 수 없고, id로 키를 푸는 쪽은 목적이 다른 키를 거부한다. 그러니 다른 목적 아래 둔 옛 키는 풀리기는 해도 거부된다.
  3. 옛 키로 쓴 행이 남아 있는 동안 옛 키를 그대로 둔다. SettingsSecretMaterialProvider.keyById는 모르는 id를 현재 키로 대신하지 않고 거부한다. 대신하면 이력의 모든 행이 읽을 때 인증 tag 실패가 된다.

결정의 이력

이력: 결정 당시(Wave 2) NotificationJpaPersistenceFacade는 아무도 import하지 않았다. 조립 루트의 component scan은 설계상 persistence 패키지를 빼고, 어떤 설정도 facade를 import하지 않아서, 알림 capability에는 JPA 영속성이 아예 없었다. 결함은 코드에는 있고 런타임에는 숨어 있었다. 그래서 처음에는 「envelope는 그 wiring과 함께 들어간다」고 정했다. 아무 배포도 만들지 않는 행을 위해 키 교체와 행 마이그레이션을 설계하는 것은 테이블보다 마이그레이션을 먼저 짓는 일이었다.

해 보고 배운 정정이 하나 있다. SMTP assembler를 등록하려고 facade를 먼저 wiring하자, NotificationPayloadAtRestContractTest의 「쓰기 경로가 어느 조립에서도 닿지 않는다」 단언이 실패했다. 그 단언은 바로 그것을 잡으려고 있었다. Wave는 런타임 경로에 알려진 보안 발견을 둔 채 wiring을 잇는 것을 막았으므로 wiring을 되돌리고 envelope를 먼저 지었다. 맞는 순서는 envelope를 wiring 전이나 함께, 뒤에는 절대 아니다이다.

결정 당시 PAYLOAD_ENCRYPTION secret을 쓰는 곳은 원본 콜백 본문을 보호하는 AesGcmCallbackPayloadProtection 하나뿐이었고 받기 경로에는 없었다. 그래서 INGEST_ONLY에서 그것을 요구하는 것은 고침이 아니었다. 아무것도 보호하지 않는 키를 배포에 요구하고, 그것이 다룬다고 보이는 payload는 평문으로 남는다. 저장소에는 이미 그런 꼴의 결함이 하나 있었다. app.graphql.cursor.key-ids(2026-09-25에 키를 지움)는 운영이 그것 없이는 뜨지 않으면서, 어떤 코드도 그것으로 cursor에 서명하지 않았다(GQL-INT-003). 지금은 AesGcmNotificationPayloadProtection 하나가 같은 envelope로 받은 payload와 보관하는 콜백을 모두 덮고, NotificationSecretRequirements가 이 목적을 모든 설정에서 요구한다.

결정 당시 결론은 이랬다. 알림은 색인의 범위 경계에 따라 (a)가 끝날 때까지 Stable로 올리지 않는다. 알림 Compose lane 셋은 막지 않는 lane으로 둔다.