Integrity and Signing

Outcome. Detect changed, removed, reordered, or forked records in an append-only history.

Prerequisites. Stable row IDs and observed and recorded timestamps.

Packages. briefcase-ai, @briefcase-ai/runtime

Languages. Python, TypeScript

When you’d reach for this

Use an integrity chain when a record hash is not enough and you also need to prove the order and continuity of a history.

Install

Python

pip install "briefcase-ai[integrity]==4.4.0"

TypeScript

npm install @briefcase-ai/runtime@4.4.0

Python chains and canonical JSON need only the standard library. The Python integrity extra adds PyNaCl for Ed25519 signing.

Append and verify a chain

Python

from datetime import datetime, timezone
from briefcase.integrity import (
    HashChainAppender, InMemoryHashChainStore, verify_chain_segment,
)

store = InMemoryHashChainStore()
appender = HashChainAppender(store)
now = datetime.now(timezone.utc)
entry = appender.append_row(
    table="decisions", row_id="decision-1", entity_id="tenant-1",
    observed_at=now, recorded_at=now, payload={"approved": True},
)
ok, reason = verify_chain_segment([entry])
print(entry.hash, ok, reason)

TypeScript

import {
  GENESIS_PRIOR_HASH, HashChainAppender, verifyChainSegment,
  type HashChainEntry, type HashChainStore,
} from '@briefcase-ai/runtime/integrity';

const entries: HashChainEntry[] = [];
const store: HashChainStore = {
  lastEntryHash: () => entries.at(-1)?.hash ?? GENESIS_PRIOR_HASH,
  append: (entry) => { entries.push(entry); },
};
const appender = new HashChainAppender(store);
await appender.appendRow({
  table: 'decisions', rowId: 'decision-1', entityId: 'tenant-1',
  observedAt: new Date(), recordedAt: new Date(), payload: { approved: true },
});
console.log(verifyChainSegment(entries));

Every entry covers the hash specification version, row and entity identity, timestamps, payload hash, superseded row, and prior entry hash. Use expected_prior or expectedPrior to verify a window cut from the middle of a larger chain.

Concurrent writers

Stores use compare-and-swap append semantics. HashChainAppender rereads the tail and retries a ChainConflictError with bounded jitter, up to 32 attempts by default. JsonlHashChainStore also uses POSIX flock, making threads and processes on one POSIX host safe; Windows remains thread-safe only.

Canonical JSON and signatures

canonical_json rejects non-finite numbers and unsupported values, sorts object keys, and emits UTF-8 bytes. canonical_json_compat preserves hashes produced by older bitemporal records and examiner bundles. Python also exposes sign_json, verify_json_signature, digest signing, public JWK export, and RFC 7638 JWK thumbprints.

Limits

• A hash chain proves continuity only from a trusted prior hash or anchored head. Store that anchor outside the history being checked.
• The JSONL store coordinates writers on one host, not across network filesystems.
• TypeScript 4.4 includes hashing and chains, but not local signing helpers or bundled stores.

API reference

briefcase.integrity has the full appender, store, canonicalization, and signing signatures. The TypeScript Runtime API covers the /integrity subpath and the hash spec both languages share.

Where this fits

Integrity is the proof half of the Replay & Verify act: replay shows a decision still behaves the same, a chain shows the history was not rewritten underneath it.

Previous · Replay & Verify: Deterministic Replay Re-run a stored decision before you prove its record is intact.

Next · Replay & Verify: Audit Bundles Seal selected evidence into a portable, verifiable artifact.