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 isPOST 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 abase 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:
- The entry is checked by replaying the key log with it appended.
- Each record is checked with
verifyAppendagainst the resulting state:- authority at
auth_seqand 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.
- authority at
- A record that changes sensitivity commits in the same transition as the epoch entry it depends on. A transition cannot name a variable twice.
verifyAttestation enforces them on every read.
Snapshots and attestations
Each environment has a Merkle map fromvariable_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 inWITNESS_SIGNING_KEY than the one it stored records the new generation
and enters re-attest:
- Vaults: attest and every write return
reattest_requiredwith the unsigned head view. An owner’s client checks that view against its floors and signs a confirmation of the exact view (signWitnessConfirmation), and/confirmends 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.
minGeneration once a rotation completes.
Restore runbook:
- Set
WITNESS_STOPPED=true. - Restore the Durable Object storage.
- Install the next generation’s seed in
WITNESS_SIGNING_KEYand delete the old seed everywhere. - Clear the stop fence.
- 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 thekeyring_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.
- An attest reads the head rows of each environment, once per cold start.
- An append writes up to
3 × records + 4rows.
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 overnode:sqlite, and the bundled Worker in workerd through Miniflare, with persisted storage for the restart and rotation tests.type-check,lintandformat:check.