> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tuturuuu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Secrets vault threat model and delivery

> Threats, mitigations and residual risks for the secrets vault, and the reviewed slices that deliver it.

This page complements the [Secrets vault](https://docs.tuturuuu.com/platform/architecture/secrets-vault.md)
design. Section references point there.

## Threat model

| ID | Threat | Mitigation | Residual |
| - | - | - | - |
| T1 | Database dump | Ciphertext, wraps and signatures only | Metadata |
| T2 | Compromised vault API and database | Pinned `vault_id`, owner-set signatures, invite binding, signed records and descriptors, witness compare-and-append | Denial of service, metadata |
| T3 | API + witness compromise | Signatures still bind every key and value to authorised signers | Stale or forked view for stateless clients |
| T4 | API + share service | Strong identity unaffected | PIN identity: offline Argon2id |
| T5 | Malicious code on the vault origin | Isolated origin, CSP, Trusted Types, no third parties | Inherent to web E2EE |
| T6 | Sibling or descendant origin script | Vault passkeys at `vault.tuturuuu.com`, no descendant hosts, no related origins, host-only session | — |
| T7 | Stolen session or password + TOTP | Strong unlock needs the vault passkey or recovery key; PIN guesses online within one quota | Weak PIN within the quota |
| T8 | Rogue machine approval | Fragment link from the machine's own output, signed transcript, single approval | Owner approving without reading |
| T9 | Server substitutes a recipient key | Recipient binding, wrap digests in signed entries | Trust in the invite delivery channel |
| T10 | Server injects, swaps or rolls back values | Writer records with `auth_seq`, witnessed value heads, fresh checkpoints on read | — |
| T11 | Removed or downgraded principal | Atomic epoch change, write fence, history split by sensitivity, lease revocation, rotation list | Already-seen plaintext |
| T12 | Removed or compromised owner | Revocable owner keys, threshold, witnessed succession, re-genesis beyond threshold | Compromise of `t` owners |
| T13 | Leaked CI credential or OIDC token | CI policy on immutable IDs and SHAs, short lifetimes, atomic `jti`, custodial label | Delivered wraps |
| T14 | Compromised machine during lease | Memory-only, scope, TTL, revocation | Values used during the lease |
| T15 | Workload or Worker secret disclosure | Separate labelled environments, verified install target, RFC 9421 requests, atomic nonces, re-key on custody end | Custodial by design |
| T16 | Key or nonce reuse | One-time HKDF subkeys per encryption, HPKE ephemeral keys | — |
| T17 | Leaks via argv, logs, caches, crash dumps | stdin input, redaction, no plaintext caches, names-only logs | OS memory inspection |
| T18 | Audit tampering | Hash chain, audit head in witness checkpoints | Server-trusted between checkpoints |
| T19 | Library vulnerabilities | Pinned versions, RFC vectors, advisory review per change | — |
| T20 | Identity-provider migration | Constant PRF input, stable `vault_user_id`, vault-owned credentials | — |
| T21 | Database restore or partial write | Witness heads fence stale state; idempotent republication | Lost ciphertext reported by name |

## Delivery slices

Each slice gets an independent security review. Migrations need an exact-SQL
review, a full local reset and the gated production workflow. Slices that
issue grants (4, 6, 10) are admitted only after slice 5's epoch revocation
passes end to end.

| Slice | Content | Depends on |
| - | - | - |
| 1a | `packages/vault-crypto` primitives: canonical encoding, context binding, one-time subkeys, symmetric and HPKE envelopes, signatures, fingerprints, KEK derivation, recovery keys, invite binding, fragment pairing; RFC 5869, 8032 and 9180 vectors and negative tests | Design gates |
| 1b | Version records, owner-set and key-log verification, epoch descriptors, witness snapshot and inclusion-proof verification | 1a, VG-1, VG-4, VG-5, VG-6 |
| 2 | Migration (vault tables, key log, keyrings, audit) and internal-api access layer with routes | 1b |
| 2a | [Witness Worker](https://docs.tuturuuu.com/platform/architecture/secrets-vault-witness.md) with compare-and-append, checkpoints, stop flag and restart tests | 1b |
| 3 | Vault passkey and recovery enrolment, unlock, projects, environments, values, reveal and copy audit, EN and VI | 2, 2a, 3a |
| 3a | Vault origin child session | G4, G9 evidence |
| 5 | Membership, invites, epochs, history split, re-encryption, rotation list | 3 |
| 4 | CLI agent, fragment pairing, `list`, `get`, `set`, `run`, `pull --stdout`, fleet notification | 5 |
| 6 | CI policy, attended and unattended CI | 5 |
| 9 | Reminders Worker, audit page | 2 |
| 10 | Workload principals | 5 |
| 8 | Sync targets | 4, 6 |
| 7 | Share service and MFA unlock tier, after its own protocol review | Step-up proof, 5 |

## Slice gates

Each gate is a requirement that the named slice must meet before it ships. A
focused independent review checks the gate when the slice is built. A gate
that turns out to change the trust anchor, the witness or epoch revocation
reopens the design instead.

| Gate | Slices | Requirement |
| - | - | - |
| VG-1 | 1b, 2a | Witness snapshot: authenticated per-environment map of latest record or tombstone, on-demand attestations without log growth, inclusion proofs, client rejection of superseded values, attestation-bound cache expiry |
| VG-2 | 2a | Witness restore: a restored witness rotates its signing key generation and enters a re-attest state; reads resume only after an owner's client confirms the head against its keyring floor, so a restored witness cannot freshly sign rolled-back state unnoticed |
| VG-3 | 2, 2a, 5 | Staged publication: hash-bound staging before commit, idempotent promotion after crash, no promotion of rejected or stale-epoch payloads, restore fencing; crash and restart tests |
| VG-4 | 1b, 5 | Wrap binding by `(recipient, key_kind, epoch)` with signed same-epoch additions; sensitivity changes and their replacement records commit in one witness transition |
| VG-5 | 1b, 5 | Re-encryption records carry a canonical signed reference to the source record and an explicit admin attestation that the plaintext is unchanged; consumers verify both signatures |
| VG-6 | 1b, 2a | Owner quorum for admin appointment; noncircular genesis encoding; the per-user keyring Durable Object as the single keyring authority with a strong-identity-signed read protocol; independent re-pinning by new invites after compromise |
| VG-7 | 6 | CI: caller `workflow_sha` pins required (no `ref_protected` alternative); exact issuer `https://token.actions.githubusercontent.com`; active `nbf`/`exp`; audience binds the hash of the full canonical job key set; `jti` consumed in the same transaction as the grant or delivery decision under the current policy |
| VG-8 | 10 | Workloads: `Content-Digest` verified against received bytes before acting; `@target-uri` derived from the Worker's configured origin, not request headers; nonces kept for at least twice the accepted skew window; authorisation checked against the witnessed revocation state |
| VG-9 | 3 | Passkey: assertion field allowlist, PRF bytes client-only and discarded after derivation, vault host serves only the vault |
| VG-10 | 1a | Document the random `enc_id` collision bound (128-bit IDs: below 2^-32 after 2^48 encryptions under one key) |
| VG-11 | 4 | The pinned vault origin is a build constant, independent of the CLI `baseUrl`; the fleet login helper matches the vault origin exactly, not by suffix |
| VG-12 | 2a, 7, 9, 10 | Metered Workers: operation-count bounds per request and aggregate, terminal scheduling, a durable stop flag, restart tests and recorded cost evidence |
| VG-13 | 3a | Links to accepted evidence for central-session gates G4 and G9 |
| VG-14 | 7 | Separate protocol review of the MFA unlock tier |
| VG-15 | 2a | Witness admission: bind each submission to a fresh witness challenge and the verified head; persist client revision, sequence and witness-generation floors; commit sensitivity changes atomically with their replacement records; check authority at indexed change points; reject appends that cross an epoch change so the writer reseals and re-signs |
| VG-16 | 3, 4, 6, 10 | Every client path that unwraps an EDK checks it with `assertEdkId` against the verified epoch descriptor before using it; epoch key freshness compares X25519 Diffie-Hellman classes (`dhClass`), not encodings |

## Interim server keys before workload principals

Until workload principals (slice 10) serve server-readable keys, a server key
that must be recoverable is minted by a dedicated dispatch-only workflow with
mandatory escrow. The first is the people registry root wrap key,
`.github/workflows/people-registry-key.yaml` with
`scripts/ci/people-registry-key.mjs`:

* It runs only on `main`, in the `shared-secret-production` environment, which
  requires a reviewer.
* It refuses to run while `.github/escrow/people-registry-wrap-key.recipients`
  lists no age recipient. Recipients are public keys; owners keep identities
  in a synced password manager, and `age-keygen -pq` hybrid keys are preferred.
* It escrows first: the key is age-encrypted in memory, stored in the private
  `tuturuuu-secret-escrow` R2 bucket under `people-registry/<environment>/<kid>.age`
  and read back byte for byte before any Worker receives it. Escrow calls use
  `ESCROW_R2_TOKEN`, a dedicated token limited to that bucket's objects, over
  R2's S3-compatible API with SigV4 (Cloudflare accepts object-scoped tokens
  only there); the Worker writes use the separate Cloudflare Workers token.
* Each kid is its own Worker secret, `PEOPLE_REGISTRY_WRAP_KEY_<kid>`, and
  `PEOPLE_REGISTRY_WRAP_KID` names the current one. A kid is never rewritten,
  so rotation adds a kid and re-wraps workspace keys without losing old ones.
* Targets are the vinext families that serve the registry routes, currently
  `api-core` in production; staging has no vinext family Workers yet.
* A secret write deploys a new version built from the latest upload, so the
  run refuses unless the latest uploaded version serves all traffic. Dispatch
  only in a quiet window agreed with the web lane, never during a family
  rebuild.

Dispatch only when all of these hold:

1. An independent review has approved the workflow at the dispatched commit.
2. At least one owner recipient is committed.
3. The deployed api-core reads `PEOPLE_REGISTRY_WRAP_KID` and
   `PEOPLE_REGISTRY_WRAP_KEY_<kid>` (the per-kid reader in
   `apps/web/src/lib/people-registry/keys.ts`), and the vinext build exposes
   secret bindings to dynamic `process.env` reads.
4. The web lane has agreed a quiet window with no family rebuild in progress.

Restore: an owner downloads the escrow object and runs
`age -d -i <identity> <kid>.age`. When workload principals ship, these keys
move into a server-readable vault environment and the escrow is retired after
a verified restore drill.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.