Evidence layout and receipt schema — frozen before production's first write

Everything a receipt references must be retrievable by hash for seven years (spec §8), and receipts are verified offline against these artifacts for as long as they exist (§6.4). So the shapes below are frozen from the first production write. A change is a new version (a new receipt_version, a new key prefix, a new content type), never an edit of an existing one.

1. Receipt schema: delegus-receipt-v1#

The receipt is spec §6.2. The engine emits exactly these fields, in this order in the JSON body; the signed payload is the JCS of the body without receipt, so field order never affects verification.

Reason codes, check ids and the two result values are the enums in docs/openapi.json (ReasonCode, ProtocolCheckId, TrustCheckId); the engine's tests assert the document equals the code.

1.1 Receipt schema: delegus-receipt-v2 (v0.3-rc1, frozen at the v0.3 freeze)#

Spec v0.3 §6.2 and §6.4. The same rules as v1 (body order, JCS payload, evaluated_at as the historical clock) with these differences: the matched Capability is never in the receipt in plaintext, and the signing input is at most 4,096 bytes whatever the Grant or the number of dependencies.

2. Evidence store (S3, Object Lock)#

Artifact kinds and their content types:

The private kinds (consumption snapshot, receipt JWS, private record, passkey approval record) share the bucket and the sha256/<hex> key with the public kinds; GET /evidence answers them with the same 404 as an unknown hash, by content type (PRIVATE_CONTENT_TYPES in apps/api/src/service/receipt-evidence.ts). They are read only through the receipt's own routes, by its entitled parties.

Receipts issued before Layer 1 are brought in by the backfill (apps/api/scripts/evidence-backfill.ts): a dry run by default that counts what is missing; --apply writes each missing JWS and private record and records the private record's hash on the row; --extend (with --apply) also raises retention as in §5; --limit N stops after N receipts. It is idempotent: an object already present is counted, not rewritten. It exits 1 when any receipt failed (each failure is listed by receipt_id) and 2 on a usage error, and it refuses --apply against a memory evidence store. The production run is the owner's dispatch.

Grants and Proofs are not stored by Delegus; the receipt pins their hashes and the relying party keeps the bytes (§8 lists what Delegus retains). The checked Action is kept on the receipt's row (action_* columns, migration 013) so an entitled party can read what was decided; a retention job nulls those columns seven years after the decision and leaves everything else. Receipts themselves are stored in Postgres (receipts) by receipt_id, with the full body and JWS; the JWS is the canonical receipt. v0.3 receipts (delegus-receipt-v2) are stored the same way; what opens the commitments they pin is kept privately beside them (§5).

3. Status-list credential#

One Bitstring Status List (131,072 bits) per Principal, published at https://status.<domain>/<principal domain path>/<n> with Cache-Control: max-age=30:

• compact JWS, alg EdDSA, typ vc+jwt, kid did:web:<domain>#status-<n>;
• payload @context ["https://www.w3.org/ns/credentials/v2"], type ["VerifiableCredential","BitstringStatusListCredential"], id = the published URL, issuer = the service DID, validFrom (backdated 60 s for clock skew), credentialSubject { id: "<url>#list", type: "BitstringStatusList", statusPurpose: "revocation", encodedList };
• encodedList is u + base64url(GZIP(bitstring)), bit index most significant bit first; a Grant's statusListIndex is the bit number.

Every re-signed list (each revocation) is a new artifact in the evidence store; receipts pin the one that was evaluated.

4. Keys#

• Receipt keys did:web:<domain>#receipt-<n>, status keys did:web:<domain>#status-<n>, Ed25519 in KMS. Rotation adds <n+1> and keeps <n> published (DELEGUS_RECEIPT_KEYS_RETIRED); a key is never removed from the DID document while any receipt it signed is within retention.
• The service DID document is served by the API at /.well-known/did.json (and, for the DID domain itself, at the same path on that host); the production copy is a static file the website publishes from the same outputs.

5. Private records (v0.3-rc1, delegus-base-v3)#

A v2 receipt pins its matched authority, the ledger key of a budgeted Capability and its CURRENT_AUTHORITY dependency evidence under commitments, and a later action names it only by a fingerprint (spec v0.3 §R). What opens those commitments is kept by Delegus and is private: none of it is published by hash, GET /evidence never serves it, and no route lists or looks up anything by fingerprint or transaction handle.

Openings are 32 bytes from the CSPRNG, fresh for each commitment and never reused; their wire form is unpadded base64url, exactly 43 characters.

Kept on the receipt's row in Postgres (receipts), written in the same insert as the receipt (for a budgeted ALLOW, in the same transaction as the spend):

Consumption snapshots are kept in the evidence store (§2), private by content type.

Who receives what (a receipt's entitled parties are its relying party through its own key, its principal through its own key, a key of an organization that owns that relying party or principal, and Delegus staff through the admin token; relying-party and principal keys are matched by kind, and observer keys are not entitled):

Anyone else, an unknown receipt, and a receipt with nothing to disclose get the same 404 on both /decisions routes. GET /decisions (list), /decisions/export and POST /access/v1/evaluation return no openings.

Retention: consumption snapshots, receipt JWS objects and private records follow the evidence bucket (§2: Object Lock COMPLIANCE, 7 years, in production). The Postgres columns above have no delete or clear path in the API; the action-data retention job nulls only a receipt's action_* columns after seven years and leaves these columns, the receipt and its evidence untouched.

The bucket locks an object for seven years from its first write, but a receipt issued years later may pin an object first stored long before (a DID document or status list that has not changed, a profile document, a trust configuration). So a daily retention-extension job, in the API's maintenance loop, takes the previous UTC day's receipts and raises the retain-until date of every object each one references (its body's did_document_hash, credential_hash, snapshot_hash, trust_config_hash and profile_hash, its own JWS, and its private record) to that day's end + 7 years + 1 day. It only ever moves a date later, so a re-run is safe; the day is marked done (setting evidence_retention:<day>, and an evidence.retention_extended audit event) only when every extension succeeded, and a day with a failure is retried by the next run. The Postgres evidence store has no retention lock and reports unsupported: its objects last as long as their rows. The backfill's --extend applies the same rule to every receipt it scans, by each receipt's own day.

A receipt stored after its day was marked done. The job runs on complete days, but a receipt can be written in the seconds after a day's run marked it done (a request that began before midnight). Its objects keep the date they had from first storage or from an earlier receipt, and its own JWS and private record hold the bucket's default retention from their write; the window is seconds per day, and the backfill's --extend covers any such receipt when it is next run. Accepted.

Orphaned objects. The store is written before the row: a receipt whose evidence landed but whose row (or spend transaction) then failed answers 503, and its JWS (and private record) stay in the locked store with no row naming them. They are content-addressed, private kinds that GET /evidence never serves, and no route reaches them; they cost storage, nothing else. The backfill and the retention job start from rows, so they never touch them.

6. Operational records (not receipt evidence, but shape-frozen)#

• Request log line: { time, level, msg: "request", request_id, method, path (templated), host, status, duration_ms } plus, on verify, rp, principal, grant_id, receipt_id, decision, reason, engine_ms. Never keys, Grants, Proofs or receipt bodies.
• Audit event: { event_id: aud_<ULID>, occurred_at, actor { kind, did, key_id }, action noun.verb, target, request_id, details }; append-only.

7. What changing any of this means#

A new receipt version (delegus-receipt-v3) with its own verifier in core; a new key prefix for any new public artifact kind (a private kind, such as the consumption snapshot, shares the sha256/ prefix and is kept out of GET /evidence by its content type, which a test pins); a new profile or trust-config file with a new hash. Old receipts must keep verifying with the old shapes for their entire retention.