Evidence bundles#

An evidence bundle is a zip file containing a range of events from one stream together with everything needed to verify them offline: the events themselves, the signed checkpoints covering them, the public signing keys, and a copy of the standalone verifier. Bundles are created from the Evidence export page in the UI and are the artefact you hand to an auditor.

On the Team plan and above, the same page can run exports on a schedule: choose streams, a monthly or quarterly cadence anchored to a day of the month, and a trailing window, and each run produces ordinary bundles through the same path, then emails your recipients download links - bundles never travel as mail attachments. Links require a Sigilbase sign-in; auditors with granted access download bundles covering their window from the auditor portal instead. Every run lands in your system stream (export.schedule_run), and a failed generation alerts owners (export.failed).

This page is the normative specification of the format. The current format identifier is sigilbase-evidence/1.4. Each version is strictly additive: 1.1 added anchors.json and the optional consistency.json over sigilbase-evidence/1; 1.2 adds the per-event payload_state field and redactions.json, which together declare any payload the tenant has destroyed (hash-preserving redaction); 1.3 adds informational qualified-TSA metadata on anchor records (see Qualified anchoring) and lets Certificates of Evidence covering records in the range travel under certificates/, hash-listed in the manifest; 1.4 adds the optional SigilSign blocks - documents.json, signatures.json, and links.json - each informational-but-verifiable: the verifier cross-checks every stated hash and sequence against the events themselves and fails on contradiction, while unknown fields (including any claim about legal effect or validity) are ignored and can never influence the verdict. The verifier accepts all five. Anything not specified here is not part of the format; consumers must ignore unknown fields rather than reject them.

Range semantics#

Proofs exist at checkpoint granularity, so the requested range is snapped outward to whole checkpoints and clamped to the sealed portion of the stream. The manifest records the actual exported range. A range with no sealed checkpoints cannot be exported.

Bundle contents#

manifest.json#

A single JSON object:

{
  "format": "sigilbase-evidence/1.3",
  "generated_at": "2026-07-09T10:02:11.482910Z",
  "stream": {
    "id": "0197c8e2-4a51-7000-8000-2f9d3b6a1c44",
    "slug": "admin-actions",
    "name": "Admin actions"
  },
  "range": {"from": 1, "to": 4},
  "event_count": 4,
  "signing_keys": [
    {
      "public_key": "2152f8d19b791d24453242e15f2eab6cb7cffa7b6a5ed30097960e069881db12",
      "created_at": "2026-07-01T00:00:00.000000Z",
      "retired_at": null
    }
  ]
}

A bundle cannot establish whose keys it carries: anyone can produce a hash chain, sign it with a key of their own, and list that key here. That is what the verifier's trusted key set is for. The released verifier carries Sigilbase's signing keys compiled into it, matches them on the public key bytes, and reports a bundle signed by any other key as UNCONFIRMED rather than as verified. You can replace that set with --keys, using keys you fetched yourself from GET /api/v1/keys or obtained out of band, and check against those instead.

events.ndjson#

Newline-delimited JSON: one event per line, in sequence order, with a trailing newline. Each line is encoded as canonical JSON (RFC 8785; see payload rules), which makes lines byte-reproducible.

{"action":"role.granted","actor":"user:42","entry_hash":"9b89974c651b484589b61d710f1bc0284e7788bf3ace3e833a46f5729d694c01","occurred_at":"2026-07-09T09:15:00.000000Z","payload":{"granted_by":"user:42","role":"admin"},"payload_hash":"11294bc41a363046cae292e51e14a892de8f459f498fd9dd4381f98a4170550b","prev_hash":"0000000000000000000000000000000000000000000000000000000000000000","received_at":"2026-07-09T09:15:03.412876Z","resource":"user:9f31","seq":1,"v":1}

Each line carries everything its entry preimage commits to, so the verifier recomputes both hashes from the line alone plus the stream id from the manifest. The entry preimage is the canonical JSON object with keys v, stream, seq, occurred_at, received_at, actor, action, resource, payload_hash, prev; Reading and proofs shows one worked byte for byte.

A redacted event is one whose stored payload the stream's owner destroyed after ingestion - the erasure path for personal data recorded by mistake. The preimage commits to payload_hash, not the payload bytes, so a redacted event's entry_hash, the chain through it, the Merkle roots above it, and every signature verify exactly as before the redaction; only the payload_hash recomputation is skipped, because the content it hashed no longer exists. Every redacted line must be matched by an entry in redactions.json - an absent payload that is not declared there fails verification.

checkpoints.json#

A single JSON object with a checkpoints array, ordered by range:

{
  "checkpoints": [
    {
      "v": 1,
      "stream": "0197c8e2-4a51-7000-8000-2f9d3b6a1c44",
      "from": 1,
      "to": 4,
      "root": "4a157629882340d739370041b824b38334a98777cfb805b89de4a7551c27b0d2",
      "prev_checkpoint": "0000000000000000000000000000000000000000000000000000000000000000",
      "created_at": "2026-07-09T09:20:00.000000Z",
      "checkpoint_hash": "1d78a3d9d7fbe21e18cdeaf6acec0eca75ad647a66b057e1e96873b37abbdec9",
      "signature": "fbaeacd76624ef225988cb7b6c9112a25f57b8bab2e081659fa7ff17ca42a00828f5ebf77a613fbd31377e1fd10695e77cf7e63c3585bfd222c7eb1dd6770208",
      "public_key": "2152f8d19b791d24453242e15f2eab6cb7cffa7b6a5ed30097960e069881db12"
    }
  ]
}

anchors.json#

A single JSON object with an anchors array - one entry per RFC 3161 timestamp token stored for a covered checkpoint. The array is empty when no anchors exist (anchoring is a Business/Enterprise capability and is forward-only, so older checkpoints may legitimately have none). An anchor proves, on a third party's authority, that the checkpoint hash existed at anchored_at - evidence not even the Sigilbase operator can forge retroactively.

{
  "anchors": [
    {
      "checkpoint_hash": "1d78a3d9d7fbe21e18cdeaf6acec0eca75ad647a66b057e1e96873b37abbdec9",
      "type": "tsa",
      "provider": "freetsa",
      "token": "MIIWjQYJKoZIhvcNAQcCoIIWfjCCFno...",
      "token_hash": "58ff5f1c2a4a1c565bb2e51e37cc6d0208b1f96e0827b2ba822a9c98ea52f5e4",
      "anchored_at": "2026-07-09T09:21:04.118240Z",
      "ca_pem": "-----BEGIN CERTIFICATE-----\n...",
      "provider_name": "FreeTSA",
      "jurisdiction": null,
      "qualified": false,
      "signer_serial": "1B4F0E9851971998E732078544C96B36C3D01CEE"
    }
  ]
}

The token's message imprint is SHA-256 over the raw 32 bytes of checkpoint_hash.

consistency.json#

Present only when the bundle starts at sequence 1 - the cumulative values below are recomputable (and therefore honest) only from the full log. The cumulative tree at size n is the RFC 6962 tree over entry hashes 1..n; checkpoint_states records it at every checkpoint boundary.

{
  "v": 1,
  "tree_size": 4,
  "root": "d37ee418976dd95753c1c73862b9398fa2a2cf9b4ff0fdfe8b30cd95209614b7",
  "checkpoint_states": [
    {"tree_size": 2, "root": "fac54203e7cc696cf0dfcb42c92a1d9dbaf70ad9e621f4bd8d98662f00e3c125"},
    {"tree_size": 4, "root": "d37ee418976dd95753c1c73862b9398fa2a2cf9b4ff0fdfe8b30cd95209614b7"}
  ],
  "proof": {
    "from_tree_size": 2,
    "to_tree_size": 4,
    "nodes": ["5f083f0a1a33ca076a95279832580db3e0ef4584bdff1f54c8a360f50de3031e"]
  }
}

Record tree_size and root (the verifier also prints them after a passing run). They are what a future export proves itself against: php verify.php --consistency old.zip new.zip, or --consistency new.zip --root <hex> --size <n> with the recorded values. See Reading and proofs for a worked example.

redactions.json#

Always present in a 1.2 bundle, listing every event in the exported range whose payload was redacted - empty when none were. This is the declaration that makes an absent payload legitimate: the verifier fails any bundle where a payload is missing without an entry here.

{
  "redactions": [
    {
      "sequence": 3,
      "redacted_at": "2026-07-12T08:14:09.221004Z",
      "declared_by": {
        "stream": "admin-actions",
        "sequence": 5,
        "entry_hash": "b8c1f9d3d7fbe21e18cdeaf6acec0eca75ad647a66b057e1e96873b37abbde11"
      }
    }
  ]
}

Redaction is deliberately narrow: it destroys payload content and nothing else. It cannot touch sequences, metadata, hashes, checkpoints, or anchors, and it always leaves a payload.redacted event in the ledger - so a bundle can prove content is absent and prove everything around the absence is intact.

How the verifier consumes a bundle#

The bundled verify.php is self-contained: no package manager, no network, no imports from Sigilbase. It is developed in the open at github.com/sigilbase/verifier - run the released copy from there, after comparing hashes, if you prefer not to trust the copy inside the bundle. It needs PHP 8.2 or newer and accepts either the zip or an extracted directory:

php verify.php admin-actions-evidence-20260709.zip

It performs, in order:

1. Manifest checks: format id is sigilbase-evidence/1 through /1.5, event_count matches the range and the ndjson line count, sequences are dense and in order.
2. Event recomputation: for every line, recompute payload_hash from the embedded payload and entry_hash from the preimage fields, and compare with the stated values. For a redacted line, the payload_hash recomputation is skipped - the content no longer exists - and the absence must be declared: payload_state says redacted and payload is null. 2a. Declarations (1.5): the absence is then accepted only against a declaration the bundle carries in declarations.ndjson whose entry hash recomputes, whose payload matches its payload hash, whose action matches the kind of absence, whose targets name that exact stream and sequence, and which was sealed in a checkpoint whose signature verifies inside its key's trusted window. A declaration outside the exported range travels with an audit path and its sealing checkpoint in declaration_proofs.json. redactions.json remains as a convenience index and decides nothing. A bundle below format 1.5 that carries an absent payload does not verify, and says to export the range again.
3. Chain walk: each line's prev_hash must equal the previous line's entry_hash.
4. Merkle roots: for each checkpoint, rebuild the RFC 6962 tree over the covered entry hashes and compare with root.
5. Checkpoint chain and signatures: recompute each checkpoint_hash from its preimage, walk the prev_checkpoint chain, and verify each signature against its public_key, which must be listed in the manifest.
6. Anchors (1.1, when present and non-empty): each token must match its token_hash, parse as a CMS timestamp token whose imprint is the checkpoint hash, carry a verifying signature from its embedded timestamping certificate (valid at the token's time), and - when ca_pem is provided - chain to that root through issuers that are each a certificate authority (basicConstraints CA, permitted to sign certificates, valid at the token's time, within any path-length limit); a chain through an ordinary end-entity certificate fails. This step needs PHP's openssl extension; without it the verifier reports the anchors as present but unverified and does not fail for inability to check. Pass --skip-anchors to skip the step silently.
7. Certificates (1.3, when the manifest lists any): each listed file must exist under certificates/ and match its manifest sha256 - a listed-but-missing or altered certificate fails the bundle. Certificates are documents about the evidence; no cryptographic check depends on them.
8. SigilSign blocks (1.4, when present): every fact in documents.json, signatures.json, and links.json is cross-checked against the events - a listed version's published_sequence must be its document.published event carrying the same sha256; each signer's signature.viewed and signature.signed events must reference the same sha256, which is the document's; each link's sequences must resolve to document.linked/document.unlinked events carrying the same sha256. A contradiction fails the bundle. Unknown fields - including any claim about legal effect or validity - are ignored and can never influence the verdict; signatures recorded here are simple electronic signatures and the format asserts nothing about their effect in any jurisdiction.
9. Consistency section (1.1, when present): every recorded cumulative root is recomputed from the events and the embedded proof re-verified.

What the verifier reports#

Five results, because what was proved and who proved it are different questions:

And four exit codes:

Exit 3 is worth understanding before you meet it. It means the bundle is internally sound - nothing in it has been altered - and its origin is not established: it was signed by a key the verifier does not carry, or its timestamps chain only to a root the bundle itself supplied. That is not evidence of tampering and it is not a pass. You will see it on a bundle from a private deployment, on a test bundle, and on a bundle somebody rebuilt and re-signed.

Because every integrity check is a recomputation from the bundle's own bytes, a bundle whose content integrity passes cannot have been altered after export, whoever has held it in the meantime.

Every run prints the verifier's own version and sha256. Compare them with the release notes before relying on what it tells you: a verifier is only as trustworthy as the file you actually ran.

After a passing run over a bundle that starts at sequence 1, the verifier prints the cumulative consistency state (tree_size and root). Record those two values: they let a future export prove it extends this one, via php verify.php --consistency old.zip new.zip or --consistency new.zip --root <hex> --size <n>. --print-hashes adds the sha256 of the bundle file itself, so the record says exactly which bundle produced the root you kept.