Skip to content
bucker

Signed receipts and the receipt log

Every act Bucker performs on an organization's behalf that is not a code change ends in a signed receipt: a DSSE envelope over an in-toto Statement, signed with the Proof Ledger key. This page is how a customer gets those receipts out and checks them without trusting Bucker's API.

What a receipt says

A receipt is a statement of identifiers, digests, versions and timestamps. It never carries plan text, a reason or any free text. The organization is inside the signed evidence, so a receipt cannot be presented as another tenant's.

Kind Written when
operation_applied a governed operation was applied (an approved or allowed config write)
operation_verified the verifier measured the change's effect
operation_reverted the operation was reverted
deletion_sweep retention removed an organization's rows for a stream and day

Later producers (subject_erasure, flag_change, delivery, survey_launched, change_verdict and the other extension kinds) file through the same writer. All of these are extension kinds: bucker-verify checks their signature and reports the kind as UNVERIFIED_BY_THIS_VERSION, which can never satisfy a tier. The published proof-ledger format (KNOWN_CLAIM_KINDS) is unchanged.

The log

Each organization has one append-only log. Entry seq runs 1, 2, 3 ... with no gaps. Entry n's previousDigest is the SHA-256 (hex) of entry n-1's envelope serialized as canonical JSON (keys sorted at every depth, no whitespace); entry 1's is 64 zeros. Removing, reordering or editing an entry breaks the chain at the first entry after it.

An entry is appended in the same database transaction as the row it signs, under a per-organization advisory lock, so a receipt in the log always describes an act that committed, and two concurrent acts take consecutive numbers. A deletion_sweep commits with the deletion itself. An operation receipt commits with the operation's stored receipt and its proofLedgerEntryIds (the seq of each of its receipts), just after the change is applied: a change is never undone or retried because its receipt could not be signed, so an applied operation with no receipt is possible (the apply answers receiptSigned: false), and it then has no log entry rather than one it did not earn.

What a chain cannot show. Removing entries from the end of the log is invisible to anyone who did not remember the head. Keep the headDigest that verify-log prints and compare it with the next export.

Reading it

GET /orgs/:orgSlug/receipts?after=<seq>&kind=<kind>&limit=<n>   (read on the organization, and every project)
GET /orgs/:orgSlug/receipts/export                              (NDJSON; the whole log)

The list is oldest first and pages by after (the last seq you saw; nextCursor is that value, or null at the end). Both are reads of the caller's own organization. There is no route that writes.

The log is one chain for the whole organization, and its receipts name projects (a deletion sweep lists each project's row count; an operation receipt names what it changed). A chain cannot be filtered without breaking it, so both routes need access to every project in the organization as well as read on the organization: owners and admins have it, a member has it when their teams reach every project, and a token must carry project:read. Anyone narrower gets 403, never a partial log.

The export has one receipt line per entry and one closing head line:

{"type":"receipt","orgId":"...","seq":1,"kind":"operation_applied","digest":"...","previousDigest":"000...0","createdAt":"...","envelope":{...}}
{"type":"head","orgId":"...","seq":1,"digest":"..."}

Verifying offline

curl -H "Authorization: Bearer $TOKEN" https://api.bucker.io/orgs/acme/receipts/export > receipts.ndjson
curl https://api.bucker.io/.well-known/proof-ledger-keys   # obtain the public key independently
bucker-verify verify-log receipts.ndjson --key ledger-key.pem

verify-log checks every signature under the key you supplied, the subject digest of every envelope, that the signed kind is the filed kind and that every receipt names one organization, the sequence and the chain, and the head line. It reports the first break and exits with the tool's usual codes: 0 valid, 2 a signature does not verify, 3 the chain, sequence or head is broken, 4 the file is intact but incomplete (it does not start at seq 1, or has no head line), 6 malformed, 7 no key was given so no signature was checked. It says what it did not check, including that evidence is read and not evaluated.