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.