feat(ai): add zero-downtime gateway HMAC key rotation by seonghobae · Pull Request #113 · ContextualWisdomLab/life-os

seonghobae · 2026-08-04T14:53:14Z

Buyer-visible outcome

Private web-to-AI service authentication can rotate HMAC credentials without rejecting valid in-flight requests during a bounded deployment overlap, while compromised or retired keys can still be rejected immediately.

Implemented contract

versioned life-os.ai-context.v2 canonical HMAC input
integrity-protected, case-sensitive x-life-os-context-key-id
one mandatory active signing/verifying key and at most one previous verification-only key
exact identifier selection with no trial verification across unrelated secrets
active-only signing in the web BFF and active-or-previous verification in AI service
fail-closed partial, duplicate, malformed, reused-secret, unknown, and retired key handling
method, exact path, workspace, actor, issuance time, and key identifier binding
bounded canonical Base64URL signature validation and constant-time comparison
credential-free 401 request failures and 503 local-verifier-configuration failures
every proposal and proposal-audit route migrated to the keyed context boundary
server-only environment contract and staged expand/switch/retire/emergency-revocation runbook

Evidence

unit coverage for key configuration, exact selection, overlap, retirement, replay, forgery, identifier substitution, path/method binding, clock boundaries, and canonical encoding
web BFF evidence that only the active key signs and browser credentials never reach AI service
real PostgreSQL HTTP integration evidence that a previous key succeeds during overlap, fails immediately after removal, and the active key remains available
AI-service statement, branch, function, and line coverage held at 100%
current standards review distinguishing final NIST SP 800-57 Part 1 Revision 5 from the 2025 Revision 6 Initial Public Draft, with APA 7 references to NIST, RFC 7515, RFC 8725, and OWASP guidance
CHANGELOG.md, capability evidence, formatting contracts, and runtime documentation updated

Merge gate

Formatting, lint, type checking, complete tests, build, Compose validation, AppGuardrail, Semgrep, Security Scan, Commercial Readiness, CodeRabbit, and every actionable human/security review thread must pass on the exact current head before squash merge.

Closes #112.

Refs #109 and #46.

Summary by CodeRabbit

새 기능
- AI Gateway 인증에 키 식별자 기반 HMAC 키 로테이션을 도입했습니다.
- 활성 키와 이전 키를 제한적으로 중첩 지원해 무중단 교체가 가능합니다.
- 폐기되거나 알 수 없는 키는 즉시 거부됩니다.
문서
- 키 교체, 긴급 폐기, 롤백 절차를 안내하는 운영 문서를 추가했습니다.
보안
- 인증 방식을 HMAC v2로 강화하고, 잘못된 설정은 안전하게 실패하도록 개선했습니다.

coderabbitai · 2026-08-04T14:55:32Z

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 84d91fbb-4b80-4a47-953a-5fa69c3e57f6

📥 Commits

Reviewing files that changed from the base of the PR and between f5cb401 and a35a609.

📒 Files selected for processing (24)

.env.example
CHANGELOG.md
apps/ai-service/migrations/README.md
apps/ai-service/package.json
apps/ai-service/src/ai-gateway-keyring.test.ts
apps/ai-service/src/ai-gateway-keyring.ts
apps/ai-service/src/ai-http-boundary.test.ts
apps/ai-service/src/ai-http-boundary.ts
apps/ai-service/src/main.ts
apps/ai-service/src/no-silent-mutation.integration.test.ts
apps/ai-service/src/proposal-audit-http.integration.test.ts
apps/ai-service/src/quality-coverage.test.ts
apps/web/app/ai-proposal-client-core.ts
apps/web/app/ai-proposal-client.test.ts
apps/web/app/ai-proposal-client.ts
apps/web/app/ai-proposal-identity-stream-regression.test.ts
apps/web/app/ai-proposal-scope-regression.test.ts
apps/web/app/api/ai/proposals/routes.test.ts
docs/operations/ai-gateway-key-rotation.md
docs/research/2026-08-04-ai-gateway-key-rotation-standards.md
docs/superpowers/plans/2026-08-04-ai-gateway-key-rotation.md
docs/superpowers/specs/2026-08-04-ai-gateway-key-rotation-design.md
package.json
product/capabilities.json

📝 Walkthrough

Walkthrough

AI 게이트웨이 인증이 단일 시크릿에서 keyId 기반 v2 HMAC 키링으로 변경되었습니다. 웹 게이트웨이는 활성 키로 서명하고, AI 서비스는 활성 키 또는 이전 키를 선택해 검증합니다. 키 회전 운영 문서와 테스트도 갱신되었습니다.

Changes

AI 게이트웨이 키 로테이션

Layer / File(s)	Summary
키 계약과 키링 검증 `apps/ai-service/src/ai-gateway-keyring.ts`, `apps/ai-service/src/ai-gateway-keyring.test.ts`, `apps/ai-service/migrations/README.md`, `docs/research/...`, `docs/superpowers/specs/...`	활성 키와 선택적 이전 키를 정의했습니다. 키 식별자와 시크릿의 형식·길이를 검증합니다. 중복, 재사용, 불완전한 설정을 거부합니다.
웹 게이트웨이 서명 흐름 `apps/web/app/ai-proposal-client-core.ts`, `apps/web/app/ai-proposal-client.ts`, `apps/web/app/*test.ts`, `apps/web/app/api/ai/proposals/routes.test.ts`	웹 게이트웨이가 활성 키를 로드합니다. `life-os.ai-context.v2` 서명 입력과 `x-life-os-context-key-id` 헤더를 생성합니다.
AI 서비스 검증과 컨트롤러 연결 `apps/ai-service/src/ai-http-boundary.ts`, `apps/ai-service/src/main.ts`, `apps/ai-service/src/*test.ts`	AI 서비스가 keyId로 검증 키를 선택합니다. 설정 오류는 503으로, 알 수 없거나 폐기된 키는 401로 처리합니다. 제안 및 감사 엔드포인트가 keyId를 전달합니다.
운영 절차와 릴리스 증거 `docs/operations/ai-gateway-key-rotation.md`, `CHANGELOG.md`, `package.json`, `apps/ai-service/package.json`, `product/capabilities.json`	키 교체·폐기 절차와 보안 표준을 문서화했습니다. 포맷 검사 대상과 capability evidence를 갱신했습니다.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant WebBFF
  participant AiService
  participant AiGatewayKeyring
  participant AiProposalController
  WebBFF->>WebBFF: 활성 키로 v2 HMAC 생성
  WebBFF->>AiService: keyId 헤더와 서명된 컨텍스트 전송
  AiService->>AiGatewayKeyring: keyId로 검증 키 선택
  AiGatewayKeyring-->>AiService: 활성 또는 이전 키 반환
  AiService->>AiProposalController: 검증된 컨텍스트 전달
  AiProposalController-->>WebBFF: 제안 또는 감사 응답 반환

✨ Finishing Touches 💡 1

⚔️ Resolve merge conflicts 💡

Resolve merge conflict in branch feat/ai-gateway-key-rotation

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch feat/ai-gateway-key-rotation

_{Comment @coderabbitai help to get the list of available commands.}

seonghobae · 2026-08-04T15:09:14Z

@coderabbitai review

coderabbitai · 2026-08-04T15:09:19Z

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

seonghobae · 2026-08-04T23:57:13Z

@coderabbitai review

coderabbitai · 2026-08-04T23:57:20Z

⚠️ Action not completed

Review rate limited.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

seonghobae · 2026-08-04T23:57:59Z

@coderabbitai review

coderabbitai · 2026-08-04T23:58:04Z

⚠️ Action not completed

Review rate limited.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

seonghobae · 2026-08-04T23:59:36Z

@coderabbitai review

coderabbitai · 2026-08-04T23:59:43Z

⚠️ Action not completed

Review rate limited.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

seonghobae · 2026-08-06T10:21:40Z

@coderabbitai review

coderabbitai · 2026-08-06T10:22:55Z

⚠️ Action not completed

Pull request is closed.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

seonghobae added 7 commits August 4, 2026 23:50

feat(ai): add bounded gateway keyring configuration

ed27081

test(ai): cover gateway keyring rotation contracts

7b9ae10

docs(ai): record gateway key rotation standards

473c54e

docs(ai): add staged gateway key rotation runbook

0eecc5a

docs(ai): design bounded gateway key rotation

38cdf79

docs(ai): plan zero-downtime gateway key rotation slice

cbf00e9

style(ai): format keyring test table

0487757

github-actions Bot mentioned this pull request Aug 4, 2026

LifeOS commercial readiness #21

Open

seonghobae and others added 5 commits August 4, 2026 23:57

ci: format AI gateway keyring evidence

c296dff

style(ai): format gateway keyring evidence

eee4a3b

ci: remove temporary keyring formatter

573c354

docs(ai): document gateway key error constructors

bdf4959

test(ai): handle empty rejected key material safely

3f0154d

seonghobae added 7 commits August 5, 2026 07:55

fix(ai): reject reused gateway rotation material

901ed7a

test(ai): cover duplicate gateway key material

120db48

feat(ai): verify versioned keyed gateway context

8176aa9

refactor(ai): fail closed on gateway key errors

dcefa96

test(ai): cover active overlap and retired gateway keys

99524dd

feat(ai): require keyed context on every controller

c91b683

ci(ai): wire and verify gateway key rotation

0840806

github-advanced-security Bot found potential problems Aug 4, 2026

View reviewed changes

Comment thread .github/workflows/complete-ai-key-rotation.yml Fixed

ci(ai): repair key rotation helper action pin

4c456c6

github-advanced-security Bot found potential problems Aug 4, 2026

View reviewed changes

Comment thread .github/workflows/fix-ai-key-rotation-helper.yml Fixed

ci(ai): execute key rotation codemod with valid action pins

99c8229

github-advanced-security Bot found potential problems Aug 4, 2026

View reviewed changes

Comment thread .github/workflows/run-ai-key-rotation-codemod.yml Fixed

seonghobae and others added 2 commits August 5, 2026 08:21

fix(ci): defer malformed integration codemod segment

b5e273b

feat(ai): wire versioned keyed gateway context

e8f3648

github-actions Bot and others added 2 commits August 4, 2026 23:27

fix(ai): pass explicit signing key in web evidence

9b5904e

test(ai): wire PostgreSQL key rotation lifecycle evidence

7926cdf

github-advanced-security Bot found potential problems Aug 4, 2026

View reviewed changes

Comment thread .github/workflows/run-ai-key-rotation-codemod.yml Fixed

seonghobae and others added 10 commits August 5, 2026 08:35

fix(ci): match wrapped gateway secret restoration

400be9e

test(ai): prove zero-downtime gateway key rotation

ca4c18d

docs(ai): finalize rotation standards and release evidence

321a93f

chore(ai): add temporary rotation evidence finalizer

56ca9c2

fix(ci): run rotation finalizer from a valid workflow

6ed34cb

docs(ai): finalize gateway key rotation evidence

83c61fe

chore(ai): remove completed key rotation helper workflow

75b823d

chore(ai): remove completed key rotation fixer workflow

a2ce614

chore(ai): remove completed key rotation verification workflow

8c6d85d

chore(ai): remove completed rotation evidence finalizer

a35a609

seonghobae changed the title ~~feat(ai): add bounded gateway key rotation foundation~~ feat(ai): add zero-downtime gateway HMAC key rotation Aug 4, 2026

seonghobae marked this pull request as ready for review August 4, 2026 23:55

seonghobae merged commit a9bd88c into main Aug 5, 2026
34 checks passed

Uh oh!

Conversation

seonghobae commented Aug 4, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Buyer-visible outcome

Implemented contract

Evidence

Merge gate

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Aug 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review failed

Walkthrough

Changes

Sequence Diagram(s)

Uh oh!

seonghobae commented Aug 4, 2026

Uh oh!

coderabbitai Bot commented Aug 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

seonghobae commented Aug 4, 2026

Uh oh!

coderabbitai Bot commented Aug 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

seonghobae commented Aug 4, 2026

Uh oh!

coderabbitai Bot commented Aug 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

seonghobae commented Aug 4, 2026

Uh oh!

coderabbitai Bot commented Aug 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

seonghobae commented Aug 6, 2026

Uh oh!

coderabbitai Bot commented Aug 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

seonghobae commented Aug 4, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Aug 4, 2026 •

edited

Loading

coderabbitai Bot commented Aug 4, 2026 •

edited

Loading

coderabbitai Bot commented Aug 4, 2026 •

edited

Loading

coderabbitai Bot commented Aug 4, 2026 •

edited

Loading

coderabbitai Bot commented Aug 4, 2026 •

edited

Loading

coderabbitai Bot commented Aug 6, 2026 •

edited

Loading