chore(docs): record the two-tier key custody model and its operating rules

[yordis]

• Enterprise customers require an independent operational veto over key use, and the custody model that delivers it existed only implicitly across ADR#0023 and ADR#0030.
• Naming exactly two custody tiers and excluding platform boot keys from the business key path keeps provider choice out of the product model and keeps cold start free of circular key dependencies.
• AWS-developer-guide-style reference pages and runbooks were chosen over further ADRs so implementation and tenant onboarding can proceed while undecided values stay explicitly open.

Related

• chore(docs): add glossary and cross-link canonical terms #490 -- related: established the glossary conventions the new terms extend

[cursor]

PR Summary

Low Risk
Documentation-only; no application or infrastructure code changes. Content describes future security behavior and should be reviewed for accuracy against ADRs, not for deployment risk.

Overview
Adds ADR#0033, which names exactly two customer-facing custody tiers (managed key vs customer managed key), treats tier as who owns backend registration (not which KMS vendor), and forbids boot-path keys (OpenBao unseal, a2a-auth-callout signing, etc.) from living behind SecretStore / KeyManagement.

New architecture pages distill ADR#0023/#30/#33 into reference material: custody chains, KeyManagement envelope operations and failure taxonomy, platform vs observed key states, and SecretStore-only secret management. Glossary entries define the two tier terms; VitePress gains Architecture + How-to sidebar sections.

Five how-to runbooks cover BYO AWS KMS, Google Cloud KMS, and OpenBao, backend migration (rewrap flow), and handling unusable keys / compromise vs rewrap. Pages state the design is not implemented yet and call out open decisions (envelope cipher suite, console/API shapes).

^{Reviewed by Cursor Bugbot for commit a71b23c. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Warning

Review limit reached

@yordis, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 48 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 0c86fb94-b7df-423f-90c0-ef3b49f54e41

📥 Commits

Reviewing files that changed from the base of the PR and between 61a9fd4 and a71b23c.

📒 Files selected for processing (10)

• docs/adr/0033-two-tier-key-custody-product-model.md
• docs/architecture/key-custody.md
• docs/architecture/key-management.md
• docs/architecture/key-states.md
• docs/architecture/secret-management.md
• docs/how-to/bring-your-own-aws-kms-key.md
• docs/how-to/bring-your-own-google-cloud-kms-key.md
• docs/how-to/bring-your-own-openbao.md
• docs/how-to/handle-unusable-keys.md
• docs/how-to/migrate-key-backends.md

Walkthrough

The documentation site adds a two-tier key custody ADR, architecture pages for custody, key management, key states, and secrets, glossary terms, provider onboarding guides, unusable-key handling, and backend migration procedures.

Changes

Key Custody Documentation

Layer / File(s)	Summary
Product model and terminology docs/adr/0033-two-tier-key-custody-product-model.md, docs/adr/index.md, docs/glossary/*, docs/.vitepress/config.mts	Defines managed and customer-managed custody tiers, cold-start boundaries, glossary terms, ADR indexing, and architecture navigation.
Custody and key-management architecture docs/architecture/key-custody.md, docs/architecture/key-management.md	Documents custody chains, service boundaries, key contracts, migration semantics, failure categories, and prohibited runtime behavior.
Key states and secret management docs/architecture/key-states.md, docs/architecture/secret-management.md	Defines key lifecycle operations, provider enforcement, crypto-shredding, SecretStore behavior, caching, auditing, and failure handling.
Provider onboarding and key operations docs/how-to/*	Adds procedures for AWS KMS, Google Cloud KMS, OpenBao, unusable keys, and explicit backend migration.

Estimated code review effort: 2 (Simple) | ~15 minutes

Possibly related PRs

• TrogonStack/trogonai#479: Establishes the OpenBao secrets-service and SecretStore/KeyManagement direction expanded by these architecture documents.
• TrogonStack/trogonai#487: Covers related customer-controlled key custody architecture aligned with the new two-tier model.

Poem

I’m a rabbit with keys in a row,
Through OpenBao’s soft glow they go.
Managed or yours,
With guarded doors,
New docs make the custody flow!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main docs change: documenting the two-tier key custody model and its operating rules.
Description check	✅ Passed	The description matches the PR: two custody tiers, boot-key separation, and using docs/runbooks while leaving open items open.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch yordis/openbao-key-ms-integration

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 5

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/adr/0033-two-tier-key-custody-product-model.md`:
- Around line 111-118: The ADR’s custody model incorrectly presents
customer-managed backends as dependent on managed keys. Update the
dependency-chain diagram and accompanying explanation to show `SecretStore →
KeyManagement → {platform OpenBao | customer backend}` as alternatives, then
describe adoption order separately without implying a linear dependency or
routing customer operations through the managed tier.
- Around line 102-108: Replace every bare ADR citation with the appropriate
relative Markdown link, preserving the existing citation text and surrounding
content. Update all affected references in
docs/adr/0033-two-tier-key-custody-product-model.md lines 102-108,
docs/how-to/bring-your-own-openbao.md lines 17-18,
docs/how-to/handle-unusable-keys.md lines 17-20, and
docs/how-to/migrate-key-backends.md lines 21-26, including any additional bare
ADR references elsewhere within those pages.

In `@docs/architecture/key-custody.md`:
- Line 78: Replace every bare ADR reference with its corresponding relative
markdown link to satisfy lint-adr-refs: update ADR#0030 in
docs/architecture/key-custody.md (78-78); ADR#0023, ADR#0030, and ADR#0033 in
docs/architecture/key-management.md (276-281); ADR#0023 and any other bare ADR
references in docs/architecture/key-states.md (16-16) and
docs/architecture/secret-management.md (9-9); and all ADR#0030 and ADR#0033
references in docs/how-to/bring-your-own-aws-kms-key.md (22-130) and
docs/how-to/bring-your-own-google-cloud-kms-key.md (23-137), using each ADR’s
corresponding destination document.

In `@docs/how-to/bring-your-own-openbao.md`:
- Around line 75-81: Update the OpenBao Transit ACL guidance in the
authentication-role and token-update sections to explicitly list the concrete
encrypt/decrypt endpoints and their required capabilities. Specify use-only
permissions for authentication and update-only permissions on encrypt paths,
excluding create, restore, deletion, and key-administration capabilities, so
readers can implement the policy without inferring paths or granting excess
access.

In `@docs/how-to/migrate-key-backends.md`:
- Around line 73-87: Update the migration procedure around the default wrapping
key and “Verifying completion” section to require a concurrency-safe cutover:
atomically switch the tenant default to the new key and mark the old KeyRef as
draining, or explicitly quiesce writers that can still select the old key before
the final reference scan. Retire the old KeyRef only after the
cutover/quiescence and a scan confirming no envelopes reference it.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 36b4fa50-a7b6-4cc6-95a2-3103ebc48817

📥 Commits

Reviewing files that changed from the base of the PR and between aeb2c87 and 61a9fd4.

📒 Files selected for processing (15)

• docs/.vitepress/config.mts
• docs/adr/0033-two-tier-key-custody-product-model.md
• docs/adr/index.md
• docs/architecture/key-custody.md
• docs/architecture/key-management.md
• docs/architecture/key-states.md
• docs/architecture/secret-management.md
• docs/glossary/customer-managed-key.md
• docs/glossary/index.md
• docs/glossary/managed-key.md
• docs/how-to/bring-your-own-aws-kms-key.md
• docs/how-to/bring-your-own-google-cloud-kms-key.md
• docs/how-to/bring-your-own-openbao.md
• docs/how-to/handle-unusable-keys.md
• docs/how-to/migrate-key-backends.md