witness-log (Python)

Python bindings for witness-log-core and witness-log-network, built with PyO3/maturin. Same wire format as the Rust crates and the same guarantees: see the root README.md and THREAT_MODEL.md before using this for anything real. Ships type stubs (py.typed).

Install

pip install witness-log

abi3 wheels for Linux x86_64/aarch64 (glibc and musl), macOS x86_64/arm64 and Windows x86_64, Python ≥ 3.9; the same files with SHA256SUMS are on the GitHub release. To build from source: pip install maturin && maturin build --release in this directory.

Quickstart: an agent loop

import witness_log

log = witness_log.open("agent.jsonl")        # create, or resume if it exists

@witness_log.step(log)                       # one line per tool
def transfer_funds(amount_usd: int) -> dict:
    return {"status": "ok", "tx_id": "tx_7ac31"}

transfer_funds(250)                          # two leaves: intent, then result
log.sync()                                   # fsync when you need durability

pii = log.append_memory(b"contact: alice@example.com")
log.forget(pii)        # right-to-be-forgotten: the salt is erased from agent.jsonl.salts
                       # and a marker leaf appended; every earlier proof is unchanged.

dossier = log.to_dossier_json()              # the bundle anyone can verify offline
report = witness_log.verify_dossier_json(dossier, 0.66, log.identity_pubkey_hex())
log.close()

witness_log.open(path, identity_seed=None) creates path with a new identity (or identity_seed, 32 bytes you keep) and resumes it on every later run. The journal is two files, agent.jsonl and agent.jsonl.salts, both 0600; the first line of the journal holds the identity private key, so protect and back up both like key material. A process killed while holding the journal leaves agent.jsonl.lock; on Linux resume clears it when the recorded PID is gone, elsewhere call JournaledLog.force_unlock(path) once you are sure nothing else has it open.

Any dossier produced here verifies with the Rust CLI unmodified:

witness-log verify dossier.json --identity <hex> --directory witnesses.json

That cross-language round trip is what the wire format (spec/SPEC.md) and conformance corpus (/corpus/) exist to guarantee.

Getting WITNESSED

A dossier with no independent cosignatures verifies as unanchored (or consistent_unwitnessed with a directory). To reach witnessed, at least two witnesses with distinct operator_org values in the verifier's directory must cosign the head:

w = witness_log.Witnesser(log, "trusted.json", "agent.jsonl")   # background thread
w.request()                         # never blocks, never raises
if w.flush(timeout=30):             # bounded wait for the current head
    report = witness_log.verify_dossier_json(w.dossier(), 0.66, log.identity_pubkey_hex(),
                                             open("trusted.json").read())
print(w.status())                   # witnessed_size, cosignatures, last_error (structured)

Witnesser follows 409 resyncs, honours Retry-After, backs off when witnesses are down, keeps its state in <journal>.witnesses.json (the CLI's file and format) and refuses to submit a journal that contradicts a head witnesses already cosigned. await w.aflush() in asyncio code; witness_log.submit_round(...) for one synchronous round. The protocol primitives underneath are add_checkpoint_body(old_size) and dossier_from_responses(...) (and their _at(size, ...) forms).

Console scripts

Identity from the environment

Set WITNESS_LOG_IDENTITY_SEED_ENV to the name of an environment variable that holds the identity seed as 64 hex characters, and every witness_log.open() without a seed argument (the package, the MCP server, the proxy, the hook daemon) seals the journal: the header holds only the public key and the seed stays in your secrets manager. Without it the default is still an unsealed journal, which is a key file: 0600, back it up like one, and move to the environment variable before anything leaves a laptop.

export AGENT_KEY=$(python -c 'import os; print(os.urandom(32).hex())')
export WITNESS_LOG_IDENTITY_SEED_ENV=AGENT_KEY

Disclosure

A leaf commits to SHA256(bucket_pad(payload) || salt || index) (SPEC §8). log.disclose(i) returns {"index", "leaf", "payload_hash", "salt"} and, when the journal was opened with store_payloads=True, "payload"; a third party checks it with witness_log.verify_disclosure(leaf, payload, salt_hex) or recomputes witness_log.payload_hash(payload, salt, index). After forget(i) there is nothing to disclose. store_payloads=True keeps payloads in <journal>.payloads (0600), which forget(i) zero-overwrites and rewrites.

Extras

Running a witness

WitnessService.new(key_name, seed, state_path, open_enrollment=True) is a witness you can mount in any web framework: hand it the body of each POST /add-checkpoint and send back what it returns. Create its state once with WitnessService.create_state(path); the state file is bound to the witness key and persisted before any cosignature leaves the process. examples/live-network/py_witness.py is a complete 60-line server.

API surface

Everything is typed in python/witness_log/_core.pyi.

Errors: WitnessLogError (base), SignatureError, ContinuityError, MalformedError; I/O failures raise OSError; bad arguments raise ValueError/TypeError. Payloads are bytes.

This crate is intentionally thin: it does not reimplement any serialization logic; every JSON shape here is the Rust crates' own serde output, so it stays in lockstep with spec/SPEC.md by construction.