How verification works#

This page explains what it means when a Sigilbase evidence bundle passes verification, and just as importantly what it does not mean. It is written for compliance and audit professionals. No cryptography background is assumed, and this page prints cleanly if you want to attach it to an evidence pack.

The problem being solved#

An ordinary audit log is a table in somebody's database. Whoever operates that database (or compromises it) can edit a row, delete a row, or insert a backdated one, and the log will look exactly as if the tampered version had always been there. When you read such a log, you are trusting the operator's honesty and their security, at every moment between the events and your reading.

Sigilbase is built so that you do not have to extend that trust. It cannot prevent someone with enough access from trying to alter history. Instead it guarantees that any alteration is detectable by arithmetic you can run yourself. That property is called tamper-evidence.

Three mechanisms, three contributions#

The chain. Every event is fingerprinted with SHA-256, a standard fingerprint function: any change to the input, however small, yields a completely different fingerprint, and it is not feasible to craft two different inputs with the same one. Each event's fingerprint includes the fingerprint of the event before it. So the latest fingerprint commits to every byte of everything before it: edit any historic event, and every fingerprint after it stops matching. The chain is what makes the past rigid.

The seal. Every few minutes, each stream's new events are gathered and sealed into a checkpoint: a small signed record fixing the exact contents of a numbered range (say events 1 to 4). Inside the checkpoint the events are arranged so that any single event can be proven to belong to the sealed set with a handful of fingerprints, without needing the whole range. The seal is what turns "the data is self-consistent" into "the data existed in exactly this form at sealing time".

The signature. Each checkpoint is signed with Ed25519, a standard digital signature scheme: signatures can only be created by the holder of a private key, and anyone can check them using the matching public key. Sigilbase publishes its public keys openly. The signature is what stops a tampered dataset simply being re-sealed: whoever altered the events cannot produce valid signatures without Sigilbase's private key, and Sigilbase will not sign a rewritten past because contiguity with earlier checkpoints is enforced at sealing.

The anchor (Business and Enterprise plans). The three mechanisms above prove integrity against everyone except one party: an operator holding the signing key could, in principle, rewrite events and re-sign everything. External anchoring closes that last gap by placing checkpoint fingerprints beyond the operator's reach. After sealing, each checkpoint's hash is timestamped by independent timestamping authorities (RFC 3161 — the token is third-party proof the hash existed at that moment), and streams can opt in to a public transparency feed that anyone may mirror. A rewritten history would need new checkpoint hashes, and those would contradict the timestamps and mirrored copies that already exist outside Sigilbase. Anchor tokens travel inside evidence bundles (anchors.json) and the verifier checks them. Additionally, consistency proofs let you confirm that a newer export extends an older one — that this quarter's log is last quarter's log plus new entries, nothing rewritten — without re-checking the whole history; one command compares two bundles or a bundle against a root you recorded earlier.

What passing verification proves#

When you run the verifier over an evidence bundle and it reports PASS, the following have been established, by recomputation from the bundle's own contents rather than by anyone's say-so:

Integrity. No event in the exported range differs by even one byte from what was sealed. Every fingerprint was recomputed from the raw data and matched.
Completeness of the range. Within the exported range no event has been removed, none inserted, and none reordered. The sequence numbers are dense, the chain closes, and every sealed range rebuilds to the same fingerprint that was signed.
Continuity. The checkpoints themselves chain together, so a whole sealed period cannot be quietly dropped from the middle.
Authenticity. Every seal carries a valid signature from a listed signing key. If you have compared those keys against the ones Sigilbase publishes, the bundle is anchored to Sigilbase's identity, not merely internally consistent.

The verifier is a single self-contained file included in every bundle, developed in the open at github.com/sigilbase/verifier — you can run the released copy from there instead of the bundled one, and compare either by hash. It uses no network, imports nothing from Sigilbase, and deliberately reimplements every calculation. You may also have your own specialists (or any third party) rewrite it from the published format specification; independence is the point.

What it does not prove#

Honesty about limits is part of the guarantee, so, plainly:

It does not prove events were true when written. If a system recorded that a backup succeeded when it did not, Sigilbase seals the false statement faithfully. Tamper-evidence starts at the moment of ingestion, not before.
It does not prove the exported range is the whole story. Verification covers the range in the bundle. Whether other relevant streams or periods exist is an audit-scoping question; the stream's checkpoint listing shows the full sealed extent if you need it.
It does not cover the gap before sealing. Events are sealed within minutes of arrival. Until an event's checkpoint exists, the cryptographic guarantee has not yet attached to it. The seal's timestamp tells you exactly when rigidity began.
It does not identify people. actor is whatever the writing system said it was. Sigilbase proves the record of the claim is unaltered, not that the claim's author was who they said.

Verifying in practice#

Ask the team you are auditing for an evidence bundle covering the streams and period in scope. This is a routine export from their Sigilbase account and takes minutes.
On any machine with PHP 8.2 or newer, run php verify.php <bundle.zip> from the bundle. PASS and exit code 0 mean every check held; any failure names the exact event or checkpoint that broke.
To anchor the bundle to Sigilbase rather than to itself, compare the signing keys in manifest.json with the keys published at the instance's /api/v1/keys endpoint, which requires no credentials.

Granted auditor access#

Instead of (or alongside) handing you bundles, the team you are auditing can grant you direct read-only access: a scoped, expiring window onto chosen streams, opened with an emailed sign-in link — no account, no password. You browse events with payloads, checkpoints, verification history, and inclusion proofs, and you can export evidence bundles covering your granted window yourself, then verify them exactly as above. Your page views are recorded to the tenant's own tamper-evident system stream, so the review is itself evidenced, symmetrically. If you have received such a grant, start at For auditors.

A worked numeric example of every calculation, with real values you can recompute by hand, is in Reading and proofs.