# 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.
