Verify as an auditor

You are the auditor. The operator gives you the stream’s fingerprint through a channel they cannot rewrite later (a signed email, a ticket, a contract annex). You verify the stream against it, keep a checkpoint, then play the attacker: edit one byte of a batch file on disk and watch verification fail with the first broken sequence number. Verifying needs only read access to the stream and the fingerprint, never the operator’s keys.

Prerequisites

• A copy of the stream, or read access to where it lives, and its fingerprint. Step 1 makes one.

• The tenbri CLI to set up the stream and seal a checkpoint, plus jq:

  cargo install tenbri-cli --version 0.1.0-beta.1 --locked

• The tool you verify with:

CLI

The tenbri CLI above is all you need.

Python

Python 3.10 or later.

pip

pip install --pre tenbri

uv

uv add --prerelease allow tenbri

poetry

poetry add --allow-prereleases tenbri

TypeScript

Node 22.18 or later, which runs .ts files directly, in a project with "type": "module" (npm pkg set type=module).

npm

npm install tenbri@next

pnpm

pnpm add tenbri@next

yarn

yarn add tenbri@next

bun

bun add tenbri@next

REST

curl and a tenbrid that serves the stream, with a token for you:

cargo install tenbri-server --version 0.1.0-beta.1 --locked

Steps

1. Set up a stream to audit.

   The operator side: a stream with one intent and its outcome.

   export TENBRI_KEYS=./keys
   tenbri init audit/support
   INTENT_ID=$(tenbri append audit/support <<'EOF' | jq -r .id
   {"kind":"decision","phase":"intent","source":"sdk",
    "principal":{"kind":"agent","id":"support-assistant"},
    "action":{"type":"reply_ticket","target":"zendesk:ticket/4821"}}
   EOF
   )
   tenbri append audit/support <<EOF > /dev/null
   {"kind":"decision","phase":"outcome","source":"sdk","intent":"$INTENT_ID","status":"ok",
    "principal":{"kind":"agent","id":"support-assistant"},
    "action":{"type":"reply_ticket","target":"zendesk:ticket/4821"}}
   EOF

   created stream tnb1:db888dbab715e39d31a8b0c7b6bd418a at audit/support
   stream key fingerprint (pin it): sha256:db888dbab715e39d31a8b0c7b6bd418acfe8482508fd345ffcb6d5da23adb6fe
   keys: ./keys/tnb1-db888dbab715e39d31a8b0c7b6bd418a
   verify with: tenbri verify audit/support --key sha256:db888dbab715e39d31a8b0c7b6bd418acfe8482508fd345ffcb6d5da23adb6fe

   The fingerprint is what the operator sends you. Keep it in PIN:

   export PIN=sha256:db888dbab715e39d31a8b0c7b6bd418acfe8482508fd345ffcb6d5da23adb6fe

2. Verify without a pin, then with it.

   The fingerprint is your trust root. Without it, verification can only say the stream agrees with its own genesis key, which anyone who rewrites the whole stream can also produce. The Python and TypeScript scripts below exit with the CLI’s codes: 0 verified, 1 broken, 3 not pinned.

   CLI

   tenbri verify audit/support; echo "exit $?"
   tenbri verify audit/support --key $PIN; echo "exit $?"

   consistent: 4 entries, stream tnb1:db888dbab715e39d31a8b0c7b6bd418a
   NOT pinned: this only shows the stream agrees with its own genesis key; pass --key <fingerprint>
   exit 3
   verified 4 entries, stream tnb1:db888dbab715e39d31a8b0c7b6bd418a, pinned to sha256:db888dbab715e39d31a8b0c7b6bd418acfe8482508fd345ffcb6d5da23adb6fe
   exit 0

   Python

   report.ok is true only when nothing is broken and the stream was checked against a pinned key.

   verify.py

   import os
   import sys
   
   from tenbri import Tenbri
   
   with Tenbri.open("./audit/support") as log:
       report = log.verify(os.environ.get("PIN"))
   
   print(report)
   if report.broken:
       sys.exit(1)  # the stream does not verify
   if not report.ok:
       sys.exit(3)  # consistent, but not checked against a pinned key

   env -u PIN python verify.py; echo "exit $?"
   python verify.py; echo "exit $?"

   VerifyReport(stream='tnb1:db888dbab715e39d31a8b0c7b6bd418a', entries=4, pinned_key=None, broken=None, checkpoint=None)
   exit 3
   VerifyReport(stream='tnb1:db888dbab715e39d31a8b0c7b6bd418a', entries=4, pinned_key='sha256:db888dbab715e39d31a8b0c7b6bd418acfe8482508fd345ffcb6d5da23adb6fe', broken=None, checkpoint=None)
   exit 0

   TypeScript

   report.ok is true only when nothing is broken and the stream was checked against a pinned key.

   verify.ts

   import { Tenbri } from 'tenbri'
   
   const log = await Tenbri.open('./audit/support')
   const report = await log.verify(process.env.PIN)
   await log.close()
   
   console.log(report)
   if (report.broken) process.exit(1) // the stream does not verify
   if (!report.ok) process.exit(3) // consistent, but not checked against a pinned key

   env -u PIN node verify.ts; echo "exit $?"
   node verify.ts; echo "exit $?"

   {
     ok: false,
     stream: 'tnb1:db888dbab715e39d31a8b0c7b6bd418a',
     entries: 4,
     pinnedKey: null,
     broken: null,
     checkpoint: null
   }
   exit 3
   {
     ok: true,
     stream: 'tnb1:db888dbab715e39d31a8b0c7b6bd418a',
     entries: 4,
     pinnedKey: 'sha256:db888dbab715e39d31a8b0c7b6bd418acfe8482508fd345ffcb6d5da23adb6fe',
     broken: null,
     checkpoint: null
   }
   exit 0

   REST

   tenbrid always verifies against the key pinned in its configuration, so ask for that pin in tenbrid.toml and check that the server’s answer names your fingerprint. The operator makes you a token with tenbrid token and adds its hash:

   tenbrid.toml

   keys = "keys"
   
   [streams.support]
   path = "audit/support"
   key = "sha256:db888dbab715e39d31a8b0c7b6bd418acfe8482508fd345ffcb6d5da23adb6fe"
   
   [[tokens]]
   sha256 = "sha256:3d19cdaba826019fd319346560190e1269ccc88f762fa4dc2cdcfbd7b4b8767b"
   principal = { kind = "person", id = "auditor" }

   tenbrid --config tenbrid.toml

   In another terminal:

   export TENBRI_URL=http://127.0.0.1:7070
   export TOKEN=tnbt_d0ae9132…   # the token tenbrid printed
   curl -s $TENBRI_URL/v1/streams/support/verify -H "Authorization: Bearer $TOKEN"
   curl -s $TENBRI_URL/v1/streams/support/verify -H "Authorization: Bearer $TOKEN" \
     | jq -e --arg pin "$PIN" '.pinned_key == $pin and .broken == null'; echo "exit $?"

   {"stream":"tnb1:db888dbab715e39d31a8b0c7b6bd418a","entries":4,"pinned_key":"sha256:db888dbab715e39d31a8b0c7b6bd418acfe8482508fd345ffcb6d5da23adb6fe"}
   true
   exit 0

3. Keep a checkpoint.

   A checkpoint is a signed note of the stream’s size and Merkle root. The operator seals one; you keep a copy outside the operator’s reach.

   tenbri checkpoint audit/support
   cp audit/support/checkpoints/000000000004.note seen.note
   head -3 seen.note

   checkpoint at size 4: checkpoints/000000000004.note
   tnb1:db888dbab715e39d31a8b0c7b6bd418a
   4
   0SREoiNR1ENpnImgPcXhjwWKjv1yTiX3aR+6YMRp57s=

   The three lines are the origin (the stream id), the size and the root hash. A blank line and the signature line follow.

   CLI

   Next time, verify against the checkpoint you kept. The stream must still hold exactly the entries it covers:

   tenbri verify audit/support --key $PIN --checkpoint seen.note; echo "exit $?"

   matches checkpoint tnb1:db888dbab715e39d31a8b0c7b6bd418a at size 4
   matches its latest checkpoint, at size 4
   verified 4 entries, stream tnb1:db888dbab715e39d31a8b0c7b6bd418a, pinned to sha256:db888dbab715e39d31a8b0c7b6bd418acfe8482508fd345ffcb6d5da23adb6fe
   exit 0

   Python

   verify checks the stream against its latest checkpoint and reports its size. To compare with the copy you kept, use tenbri verify --checkpoint (the CLI tab).

   python verify.py

   VerifyReport(stream='tnb1:db888dbab715e39d31a8b0c7b6bd418a', entries=4, pinned_key='sha256:db888dbab715e39d31a8b0c7b6bd418acfe8482508fd345ffcb6d5da23adb6fe', broken=None, checkpoint=4)

   TypeScript

   verify checks the stream against its latest checkpoint and reports its size. To compare with the copy you kept, use tenbri verify --checkpoint (the CLI tab).

   node verify.ts | grep checkpoint

     checkpoint: 4

4. Tamper with one byte.

   Each batch file holds consecutive entries, one canonical JSON line each. Here every append made its own batch, so entry 3 (the intent) is alone in 000000000003.jsonl.

   ls audit/support/batches

   000000000001.jsonl
   000000000002.jsonl
   000000000003.jsonl
   000000000004.jsonl

   Change the ticket number in the intent from 4821 to 4822, one byte:

   perl -pi -e 's#ticket/4821#ticket/4822#' audit/support/batches/000000000003.jsonl

5. Verify again.

   CLI

   tenbri verify audit/support --key $PIN --checkpoint seen.note; echo "exit $?"

   broken at seq 3: bad_signature: the signature does not verify
   2 entries verified before it, stream tnb1:db888dbab715e39d31a8b0c7b6bd418a
   exit 1

   Reads that check the stream refuse it too. --verify makes query read the stream itself rather than trust a query index built earlier:

   tenbri query audit/support --action reply_ticket --key $PIN --verify; echo "exit $?"

   tenbri: the stream does not verify: broken at seq 3: bad_signature: the signature does not verify
   exit 1

   Python

   python verify.py; echo "exit $?"

   VerifyReport(stream='tnb1:db888dbab715e39d31a8b0c7b6bd418a', entries=2, pinned_key='sha256:db888dbab715e39d31a8b0c7b6bd418acfe8482508fd345ffcb6d5da23adb6fe', broken=Broken(seq=3, code='bad_signature', message='the signature does not verify'), checkpoint=None)
   exit 1

   A stream opened with key=PIN refuses reads the same way: log.query(...) raises tenbri.errors.StreamBrokenError: the stream does not verify: broken at seq 3: bad_signature: the signature does not verify.

   TypeScript

   node verify.ts; echo "exit $?"

   {
     ok: false,
     stream: 'tnb1:db888dbab715e39d31a8b0c7b6bd418a',
     entries: 2,
     pinnedKey: 'sha256:db888dbab715e39d31a8b0c7b6bd418acfe8482508fd345ffcb6d5da23adb6fe',
     broken: {
       code: 'bad_signature',
       message: 'the signature does not verify',
       seq: 3
     },
     checkpoint: null
   }
   exit 1

   A stream opened with { key: PIN } refuses reads the same way: log.query(...) rejects with StreamBrokenError: the stream does not verify: broken at seq 3: bad_signature: the signature does not verify.

   REST

   /verify reads the whole stream from storage again:

   curl -s $TENBRI_URL/v1/streams/support/verify -H "Authorization: Bearer $TOKEN"
   curl -s $TENBRI_URL/v1/streams/support/verify -H "Authorization: Bearer $TOKEN" \
     | jq -e --arg pin "$PIN" '.pinned_key == $pin and .broken == null'; echo "exit $?"

   {"stream":"tnb1:db888dbab715e39d31a8b0c7b6bd418a","entries":2,"pinned_key":"sha256:db888dbab715e39d31a8b0c7b6bd418acfe8482508fd345ffcb6d5da23adb6fe","broken":{"seq":3,"code":"bad_signature","message":"the signature does not verify"}}
   false
   exit 1

   Caution

   GET /entries answers from the entries tenbrid read and verified when they were written, so after an edit on disk it still returns the original, verified entries. Call /verify to check what storage holds now.

What happened

The edit changed the bytes the session key signed, so the signature on entry 3 no longer verifies and every verifier reports the first broken entry. A stream signed with another genesis key fails your pin with untrusted_root. An operator who holds the keys could still truncate or re-sign a rewritten stream; the checkpoint you kept catches that for the entries it covers (truncated, fork), which a pin alone cannot.

Related

• Integrity
• Keys
• Errors
• CLI reference
• API reference