← Home

Transparency — a journal a root cannot quietly rewrite

The audit log is append-only. Inside our SQLite file, with a trigger that refuses UPDATE. That stops accidents. It does not stop whoever holds root on this machine — and "trust us, the log is intact" is exactly the sentence an audit exists to make unnecessary.

BIP-F-45 folds the journal into a Merkle root and publishes it outside the database. Once a root has left the machine, rewriting an event changes the root, and the lie is visible to anyone with the anchor — no access to this server required.

events (append order, row ids)
   │  leaf = H("L" + canonical({id, ts, type, page_id, source_id, device_id, fingerprint, data}))
   ▼
  L1  L2  L3  L4  L5  L6  L7
   └─┬─┘  └─┬─┘  └─┬─┘   │
    N1      N2     N3    │        unpaired node is PROMOTED, never duplicated
   └───┬────┘   └───┬────┘        (duplicating would give two different logs
       N4          N5             the same root)
   └───────┬────────┘
          ROOT  ──▶ GET /v1/transparency/root
                 ──▶ data/transparency-anchor.txt   (outside the DB)

What is committed

Both the content and the position of every event. The leaf carries the row id, because the journal is a sequence, not a set (BIP-F-12). So all four tampering shapes move the root:

Tampering Caught because
edit one event its leaf changes
delete one event every later leaf shifts position
insert an event same, plus the count changes
swap two events two leaves land on two positions

The layout is named, bipeur-merkle-v1, and travels with every proof: a verifier must know which tree to rebuild.

The three endpoints

# 1. The root over the journal as it stands. Public on purpose: a public claim
#    needs a public check.
curl -s https://…/v1/transparency/root
# → {"algorithm":"bipeur-merkle-v1","root":"9f…","events":412,"last_id":412}

# 2. The inclusion path of one event. An outsider folds it back onto the root.
curl -s "https://…/v1/transparency/proof?event_id=97"
# → {"algorithm":…,"root":"9f…","proof":{"leaf":"{\"id\":97,…}","index":96,
#    "total":412,"path":[{"position":"right","hash":"…"},…]},"event":{…}}

# 3. Publish the root now: appends `transparency.checkpoint` and anchors it.
#    Authenticated — publishing is an operator act.
curl -s -X POST -H "authorization: Bearer $TOKEN" https://…/v1/transparency/checkpoint

Verification, from the outside, is thirty lines and no database:

leaf = H("L" + canonical(proof.leaf))          # the leaf the endpoint returned
for step in proof.path:                        # fold the path up
    leaf = H("N" + step.hash + leaf) if step.position == "left" else H("N" + leaf + step.hash)
assert leaf == published_root                  # the root from the ANCHOR, not from us

Compare against the anchor, never against /v1/transparency/root: the server that is lying would hand you the root that makes the lie check out.

The anchor

BIPEUR_ANCHOR_PATH (unset by default). One line per published root, append-only, plain text:

1763121600000 9f4c… 412 412
1763125200000 a71e… 514 514

ts root events last_id — enough to verify a proof, nothing that leaks a payload (BIP-N-03). Copy it anywhere that outlives this machine: a git commit in the deployment repo, a CI artifact, a second host. An anchor that stays on this disk proves nothing: whoever rewrote the log would rewrite the file too. Without the variable, the root is still computed and served, but nothing leaves the database, and no outsider could catch a rewrite — the honest default is to set it.

When a root is published

Every hundred events, on the maintenance pass. The baseline is read back from the last transparency.checkpoint record — how many events it committed to — not from count % 100, which would fire on a multiple and miss every other growth. A checkpoint commits to the journal as it was before the checkpoint event itself, so the act of anchoring can never hide the anchor.

Retention (BIP-F-08) prunes events older than BIPEUR_RETENTION_DAYS. Pruning moves the root: the anchor keeps the history, so an old proof still checks against the old root. Pruning is a policy, not a rewrite — and it is itself an audited event.

What it is not

Not a public ledger, not a blockchain, not a notary service. Nobody is charged, nothing is broadcast, and no third party must cooperate. It is one hash per hundred events, written where the operator cannot quietly un-write it — enough for a customer, an auditor or a judge to check, years later, that the pages they were told about are the pages that were logged.