Skip to content
bucker

Witness onboarding

Who this is for: an operator or auditor who wants Bucker's evidence log to be hard for Bucker to rewrite.


Why a witness is the whole point

Every proof-ledger entry is signed, and the log's heads are published as signed checkpoints. A signature proves who wrote the bytes. It proves nothing about history.

An issuer who controls every byte can produce a perfectly consistent log for a verification that never ran. Re-signing a rewritten log costs nothing when you hold the key. That is not a hypothetical about Bucker specifically; it is the reason transparency logs exist as a genre, and it is stated in the specification itself (docs/proof-ledger-spec, §10.2) rather than hidden.

The fix is that somebody who is not us holds a copy of a head. Once a third party has recorded "at tree size 4,182 the root was abc…", we can no longer produce a different history for those 4,182 entries without that party's copy contradicting us. The log stops being a promise and becomes a commitment.

So the honest reading of an un-witnessed log is:

This log proves internal consistency and authorship, and nothing about history.

That sentence is what GET /orgs/:orgSlug/proof-ledger/witnesses returns in its disclosure field when independentlyWitnessed is false, and it is what the Verification screen prints at the top of the witness panel. It is meant to be uncomfortable until you fix it.


What counts as a witness, and what does not

Independent? What it buys you
A WEBHOOK to an endpoint you run (SIEM, notary, your own store), CUSTOMER custody yes (declared) A rewrite is contradicted by a copy we do not hold, plus alerting on your side
An OBJECT_STORE witness, whatever custody it declares no An ordered, durable copy in Bucker's own bucket. Nothing else
A webhook Bucker operates (ISSUER custody) no Durability. Nothing else

A copy the issuer holds cannot corroborate the issuer. The API computes independent rather than storing it as a flag, precisely so nobody can register our own bucket and call the log witnessed, and it computes it from one rule (domain/src/modules/proof-ledger/witness.ts):

export const INDEPENDENT_WITNESS_WHERE = { custody: 'CUSTOMER', kind: 'WEBHOOK' } as const

The same rule decides the independentlyWitnessed headline and the checkpoint publisher's count of organisations publishing with no independent witness. An object-store witness is on the wrong side of it because of where it writes, not because of anything you declared: its only store is Bucker's own bucket, and there is no customer-bucket option to move it out.

Custody is declared, not verified

We cannot verify that a URL is really yours. An endpoint is an endpoint. Every witness response therefore carries custodyUnverified: true, always, and the UI repeats it. What is verifiable is the receipt trail, and — where the witness countersigns — its signature over the exact checkpoint bytes.

Do not read "CUSTOMER custody" as a Bucker attestation. Read it as your claim, recorded with an author and a timestamp.


Onboarding, end to end

1. Choose a transport

WEBHOOK — checkpoints are POSTed to an https: endpoint you run. This is the independent option and the recommended default: the copy lives on your side, where we cannot reach it, and if you countersign (step 4) you sign the exact bytes. Keep what it receives append-only; a head it missed while it was down is retried (step 5).

OBJECT_STORE — checkpoints are written as objects into Bucker's own object store, under

proof-ledger-witness/<orgId>/<witnessId>/<endpoint>/<tree size, zero-padded to 12 digits>.checkpoint.json

so the head at tree size 42 is stored as 000000000042.checkpoint.json. That is also the key an object-store receipt reports (step 5), and the padding is what makes the objects list in tree-size order.

The endpoint is required here too (registration refuses an empty one with a 400), but it is not an address: it only becomes a sub-path beneath that root, which is built from ids the server owns. A value made only of slashes (e.g. "/") gives no sub-path, so the object lands directly under <witnessId>/. What this buys you is a durable, ordered copy: a second write at the same tree size with different bytes is refused rather than overwritten. What it does not buy you is independence. The bytes are in the issuer's bucket, so the API reports independent: false for it whatever custody you declare, and it never turns the independentlyWitnessed headline on. The objects are deleted with your organisation.

There is no option to point an object-store witness at a bucket you own. The config field is stored, but the transport reads no bucket, region or credential from it.

2. Register it

curl -X POST https://api.bucker.io/orgs/<org>/proof-ledger/witnesses \
  -H "authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  -d '{
        "name": "acme-siem",
        "kind": "WEBHOOK",
        "custody": "CUSTOMER",
        "endpoint": "https://siem.acme.example/bucker/checkpoints",
        "secret": "<at least 16 characters, from your own secret store>",
        "expectsCountersignature": false
      }'

Requires admin on the org. The secret is the HMAC key we sign deliveries with (step 3); it is stored sealed and never returned. The endpoint must be an absolute https: URL: a witness that cannot be authenticated is not a witness.

An object-store copy is registered the same way with "kind": "OBJECT_STORE" and a sub-path such as "endpoint": "checkpoints", and is worth having only as what it is — a backup in our bucket beside the webhook, not instead of it. Each confirmed receipt repeats that it is not independent custody. If its config carries an objectLockMode, a confirmed receipt echoes it as your declaration; it records the write, not any retention. A failed receipt carries neither, because it records no stored copy.

3. Verify a delivery signature (webhook only)

Each POST carries:

x-bucker-timestamp: 2026-08-29T19:00:00.000Z
x-bucker-signature: t=<unix seconds>,v1=<hex>

The signature header is a comma-separated key=value list. Take t and v1 from it and check:

expected = hex(hmac_sha256(secret, t + "." + rawBody))
valid    = constant_time_equals(expected, v1) and abs(now - t) <= your_tolerance

Four things that are easy to get wrong, and that we get asked about:

  • t is the timestamp that was signed — not x-bucker-timestamp. That header is a readable convenience for your logs. It is not covered by the MAC, and signing its contents will fail every delivery.
  • Take the FIRST t= if the value somehow carries two. Last-wins lets anyone who can append to the header shadow the timestamp we actually signed.
  • Sign over the raw body bytes, not a re-serialized parse.
  • Compare in constant time, and reject a t outside your tolerance — 300 seconds is what our own reference verifier uses. The timestamp is inside the signed string specifically so a captured delivery cannot be replayed at your endpoint later.

A future algorithm will arrive as an additional v2= beside v1= in the same header, so a verifier that keeps reading v1 keeps working while one that has migrated can prefer the newer. Ignore keys you do not recognise rather than refusing the delivery.

Changed 2026-09-10. Deliveries previously carried x-bucker-signature: sha256=<hex> over <isoTimestamp>.<body>, with the time in x-bucker-timestamp. The material signed is the same in substance — the timestamp was always inside the MAC — but it is now spelled in unix seconds under t=, and the value is the t=,v1= list above rather than a sha256= prefix. This is the same grammar every other Bucker webhook uses; one name now means one thing. A verifier written against the old shape will reject every delivery rather than accept a forgery.

4. Countersign, if you can

Set expectsCountersignature: true and supply your Ed25519 public key as SPKI PEM. Then answer a delivery with:

{ "countersignature": "<base64 Ed25519 over the exact checkpoint bytes>",
  "algorithm": "Ed25519" }

This is the difference between two very different claims, and the receipt records which one you made:

  • stored — you received a head. A delivery record.
  • attested — you signed that you received these exact bytes. Evidence.

GET /orgs/:orgSlug/proof-ledger/witnesses/:witnessId/receipts reports both counts separately (attestedHeads, storedHeads) rather than adding them together, because adding them together would launder the first into the second.

5. Deliver, and check

# Publish a checkpoint now, then push it to every enabled witness.
curl -X POST .../orgs/<org>/proof-ledger/checkpoints      -H "authorization: Bearer $TOKEN"
curl -X POST .../orgs/<org>/proof-ledger/checkpoints/<id>/deliver -H "authorization: Bearer $TOKEN"

# What came back.
curl .../orgs/<org>/proof-ledger/witnesses/<witnessId>/receipts -H "authorization: Bearer $TOKEN"

A receipt is PENDING, CONFIRMED or FAILED, with attempts and the raw receipt blob (HTTP status and response size for a webhook; object key and byte count for an object store). Delivery retries up to five attempts; a witness that is down does not block issuance, and the backlog is retried by retryPendingDeliveries.

6. Confirm it took

In the app: Verification → Who co-signs our log heads. The panel prints the independentlyWitnessed headline first, then each witness with its custody, whether it countersigns, and its last receipt.

The headline flips to positive only when a witness is a WEBHOOK, is enabled, has CUSTOMER custody, and has actually received a head (deliveredCount > 0). Registering a witness is not witnessing, and an object-store witness never flips it.


What you should do with the copies

Holding checkpoints is only half of it. To actually detect a rewrite:

  1. Keep them. Object Lock, or append-only storage on your side. A copy we could ask you to delete is a copy we control — and a copy in our own bucket, which is all an object-store witness holds, is one we control outright.

  2. Compare them. Periodically fetch GET /orgs/:orgSlug/proof-ledger/consistency-proof?oldSize=<a size you hold> and check that the tree you were shown then is a prefix of the tree we show now. bucker-verify does this offline, with no account and no network:

    npx bucker-verify consistency --old checkpoint-4182.json --new checkpoint-9001.json
  3. Alert on a gap. If deliveries stop, that is a signal. A witness nobody reads is a witness that cannot testify.

Step 2 is the one people skip, and skipping it makes the whole arrangement decorative.


Failure modes worth knowing

A checkpoint at a given tree size is immutable. For an object-store witness, a second write at the same object key with different contents is refused rather than overwritten, and the receipt records the refusal. If you see that error, something is wrong — investigate rather than clearing it.

Retention is not something a registration can turn on. An object-store witness writes into Bucker's bucket whatever its config declares, and its receipt says a write happened, not that retention was enforced. Retention you can rely on is retention on your side of a webhook.

A non-JSON 200 still counts as received. A witness that acknowledges without a parseable body has the head; it simply has not attested to it. The receipt distinguishes the two.

Disabling a witness does not delete its receipts. History is not editable from the witness roster, deliberately.


  • docs/proof-ledger-spec/ — the published format, its versioning policy, and worked examples
  • code/tooling/bucker-verify/README.md — the offline verifier: no account, no network, no runtime dependencies
  • /verify — the same rule set in a browser tab, for a certificate or a share link
  • /transparency — the public miss-rate register and its own Merkle log