> ## 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 witness

> Protocol, admission rules, restore handling, budgets and operation of the witness Worker that commits every secrets vault change.

The witness is the commit point of the [Secrets vault](https://docs.tuturuuu.com/platform/architecture/secrets-vault.md#witness).
It lives in `apps/vault-witness`: a Cloudflare Worker with two SQLite Durable
Objects. `VaultWitness` holds one vault's key log, version-record metadata and
snapshot maps, keyed by `vault_id`. `KeyringWitness` is one user's keyring
authority, keyed by `vault_user_id`. Neither stores ciphertext or wraps.

The engines (`vault-engine.ts`, `vault-append.ts`, `keyring-engine.ts`) are
synchronous. Each Durable Object call runs in one `transactionSync`.
Verification uses `@tuturuuu/vault-crypto`, the same code clients use.

## Deployment boundary

The witness deploys from a dedicated Cloudflare account. The vault API holds
no deploy credentials or signing key for it. `cloudflare.config.ts` therefore
names no account, route, `workers.dev` or preview URL. The
`vault-witness-cloudflare.yaml` workflow builds and digests the artifact
without publishing it. The first publication needs release-authority
approval for the account, hostname and secrets.

| Binding | Kind | Value |
| - | - | - |
| `WITNESS_DEPLOYMENT` | text | The deployment name clients pin (`tuturuuu.com`) |
| `WITNESS_SIGNING_KEY` | secret | `<generation>:<base64url Ed25519 seed>` |
| `WITNESS_API_TOKEN` | secret | Bearer token for the vault API, at least 32 characters |
| `WITNESS_STOPPED` | secret | `true` fails every vault and keyring call closed |

## Protocol

Every call is `POST` with `content-type: application/cbor`, a canonical CBOR
body of at most 256 KiB, and `Authorization: Bearer <WITNESS_API_TOKEN>`.
Responses are canonical CBOR: `{ ok: true, ... }`, or `{ ok: false, error }`.
The token only gates and meters access. The witness verifies every change
against signatures the API cannot forge. `GET /v1/health` is public. It
reports the stop state, the active generation and its public key.

| Route | Body | Result |
| - | - | - |
| `/v1/vaults/{vault_id}/init` | `{genesis}` | Creates the vault; idempotent for the same genesis |
| `/v1/vaults/{vault_id}/challenge` | `{}` | A 16-byte challenge, valid for 120 seconds and used once |
| `/v1/vaults/{vault_id}/attest` | `{nonce, proofs: {env, variable_ids} \| null}` | A signed attestation and up to 64 inclusion proofs |
| `/v1/vaults/{vault_id}/append` | `{challenge, base, entry, records}` | Commits one transition |
| `/v1/vaults/{vault_id}/transitions` | `{after, limit}` | Committed transitions, for publication |
| `/v1/vaults/{vault_id}/audit` | `{prev_audit_head, audit_head, event_count}` | Advances the audit head |
| `/v1/vaults/{vault_id}/confirm` | `{confirmation}` | Ends re-attest |
| `/v1/keyrings/{vault_user_id}/put` | `{head}` | Accepts the next keyring head |
| `/v1/keyrings/{vault_user_id}/attest` | `{nonce}` | The current head and a signed keyring attestation |
| `/v1/keyrings/{vault_user_id}/confirm` | `{signature}` | Ends keyring re-attest |

Errors map to HTTP statuses:

* 400: malformed request.
* 401: bad token.
* 404: unknown vault or route.
* 409: stale head, used challenge, conflict or re-attest.
* 413: body too large.
* 415: wrong media type.
* 422: rejected transition or cap reached.
* 429: budget exhausted.
* 503: stopped or misconfigured.

## Admission

An append names a fresh challenge and a `base` of `witness_generation`,
`seq` and `key_log_head`. The witness consumes the challenge first, so a
rejected transition still uses it up. It then requires `base` to equal its
current generation and key-log head exactly. A writer that read state before
any key-log change, including an epoch change, gets `stale_head`. It must
reverify, reseal and re-sign.

A transition is an optional key-log entry plus up to 64 version records, and
it commits atomically or not at all:

1. The entry is checked by replaying the key log with it appended.
2. Each record is checked with `verifyAppend` against the resulting state:
   * authority at `auth_seq` and at every indexed change point since;
   * the current epoch;
   * an exact extension of the variable's current head;
   * for re-encryptions, the source chain from stored records.
3. A record that changes sensitivity commits in the same transition as the
   epoch entry it depends on. A transition cannot name a variable twice.

The client persists its revision, sequence and witness-generation floors in
its keyring. `verifyAttestation` enforces them on every read.

## Snapshots and attestations

Each environment has a Merkle map from `variable_id` to the hash of its
latest record or tombstone (RFC 9162, leaves ordered by `variable_id`). The
witness builds the tree bottom-up and caches it per environment, so one
attestation can carry many proofs. An attestation signs the generation,
revision, key-log head, every environment root (including empty environments
the key log declares), the audit head, the issue time and the client's nonce.
It never appends to the log.

## Publication

The vault API reads `/transitions` after the last revision it stored. Each
transition lists its signed entry and records and the payload hashes it
authorises: record ciphertext hashes, and wrap and history digests from epoch
descriptors. The API promotes only staged payloads with those hashes, keyed
by hash, so a crash and replay is idempotent. Rejected transitions are never
listed, so their payloads expire in staging.

## Restore and key rotation

A witness restored from a backup could sign rolled-back state that a client
without local state would accept. Every restore therefore rotates the signing
generation. On its next call, a Durable Object that finds a newer generation
in `WITNESS_SIGNING_KEY` than the one it stored records the new generation
and enters **re-attest**:

* **Vaults:** attest and every write return `reattest_required` with the
  unsigned head view. An owner's client checks that view against its floors
  and signs a confirmation of the exact view (`signWitnessConfirmation`), and
  `/confirm` ends re-attest.
* **Keyrings:** the user's current identity key signs the pending head
  (`signKeyringConfirmation`).
* **Older generation:** a Durable Object that stored a newer generation than
  the configured key fails closed with `misconfigured`.

Clients pin each generation's public key in their build. Generate several
generations ahead and keep the unused seeds offline. Raise clients'
`minGeneration` once a rotation completes.

Restore runbook:

1. Set `WITNESS_STOPPED=true`.
2. Restore the Durable Object storage.
3. Install the next generation's seed in `WITNESS_SIGNING_KEY` and delete the
   old seed everywhere.
4. Clear the stop fence.
5. Ask an owner of each vault to confirm.

## Keyring authority

The first keyring head (counter 0) names the user's identity key. The witness
accepts it from the API on first use. Each later head extends the previous
head hash under the identity key in force, and may name the next key. A
replayed or forked keyring head is rejected. A client accepts a keyring only
when it hashes to the `keyring_hash` of a fresh keyring attestation at or above
its counter floor.

## Budgets, stop fence and cost

The witness schedules no alarms and makes no outbound calls. Its billable work
is one Durable Object request per call. Each request takes one unit from
durable counters in the object's own storage, before any other work:

| Budget | Per object |
| - | - |
| append and audit | 60 per minute |
| attest | 600 per minute |
| challenge | 120 per minute |
| transitions | 300 per minute |
| init and confirm | 30 per minute |
| all calls | 20,000 per UTC day |

Storage caps per vault:

* 2,048 key-log entries.
* 256 environments.
* 5,000 variables per environment.
* 200,000 stored records.
* 256 open challenges.

Approximate storage operations per call:

* An attest reads the head rows of each environment, once per cold start.
* An append writes up to `3 × records + 4` rows.

Setting `WITNESS_STOPPED=true` is the stop fence. It needs no code deploy.

A cold start replays and verifies the full key log once. The 2,048-entry cap
keeps that replay bounded until incremental key-log verification exists in
`@tuturuuu/vault-crypto`.

## Local verification

* `bun run --cwd apps/vault-witness test`: the engines over `node:sqlite`, and
  the bundled Worker in workerd through Miniflare, with persisted storage for
  the restart and rotation tests.
* `type-check`, `lint` and `format:check`.

Builds run only in CI.


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