Skip to main content
The witness is the commit point of the Secrets vault. 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.

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. 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: 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.