Security and trust model

Openwake is a record. Its first security property is integrity, the record cannot be quietly altered, and its second is confidentiality for the small amount of private data it holds about customers. Most of the registry is public by design.

What we hold

The ledger

Every snapshot, fact set, change, document change and check is appended to one hash chain:

hash = sha256(prev_hash | kind | ref_id | payload_hash | created_at)
payload_hash = sha256(canonical JSON of the record)
signature = Ed25519(hash)   with OPENWAKE_SIGNING_KEY

• GET /v1/keys: the public key and the exact hash recipe.
• GET /v1/ledger/head: the current chain head.
• GET /v1/ledger/:kind/:ref: the entry for one record: anyone can recompute the hash and verify the signature offline.
• pnpm ledger:verify: walks the whole chain; exits non-zero on the first broken link.
• pnpm ledger:anchor: writes anchors/YYYY-MM-DD.json with the head hash and signature. Commit that file. Public git history is the anchor: even the operator cannot rewrite it without it being visible.

Receipts

check_counterparty returns a self-contained receipt (version: openwake-receipt/1): the exact statement that was recorded (counterparty, data classes, decision, reasons, the fact set it was decided on and that fact set's own ledger entry), the ledger entry that includes it (seq, prev_hash, payload_hash, hash, signature, key_id, created_at), the public anchor that covers it when one exists, and the recipe. The caller stores it as its own evidence of what Openwake said, when.

Verify with nothing but the public key: no call to Openwake:

payload_hash == sha256(canonical(statement))        canonical = keys sorted recursively, no whitespace
hash         == sha256(prev_hash|kind|ref_id|payload_hash|created_at)
Ed25519.verify(signature, hash-as-hex-bytes, public key for key_id)

• pnpm receipt:verify receipt.json public-key.pem: does exactly that, offline, exit 0/1.
• POST /v1/receipts/verify: the same checks plus "is this entry still in the chain". An operator who rewrote history fails there and at the git anchors.

The shape follows the SCITT idea of a signed statement plus a transparency receipt; the content is what makes it Openwake's: the counterparty's cited data practices at decision time.

Keys

pnpm keys:generate prints OPENWAKE_SIGNING_KEY and OPENWAKE_DATA_KEY. Both are required in production; development falls back to ephemeral / fixed dev keys with a loud warning. Rotate the signing key by publishing the new public key alongside the old at /v1/keys (entries carry key_id).

Key rotation

• Signing key: generate a new pair, publish both public keys at /v1/keys (entries carry key_id), then switch OPENWAKE_SIGNING_KEY. Old entries stay verifiable with the old key forever; never re-sign history.
• Data key: sealed values are bound to the key that sealed them. To rotate, open every sealed column with the old key and re-seal with the new one in a migration script, then switch OPENWAKE_DATA_KEY. Losing the data key loses the secrets: back it up in your secret store.
• Import-order note: the db package loads .env from env.ts, imported first by crypto.ts, so keys are present before any signing or sealing regardless of which module a script imports first.

Rules that never change

1. The oracle takes data classes, never data.
2. Facts are quoted or they are not facts.
3. The ledger is append-only; corrections are new entries, never edits.
4. Fail-open: Openwake is advisory. The caller's policy decides what happens when we are unreachable.