Skip to main content

​
Configuration

The Trailproof constructor accepts options to configure the store, signing, and defaults.

​
Options

OptionTypeDefaultDescription
store"memory" or "jsonl""memory"Storage backend
pathstring—File path for the JSONL store
signing_key / signingKeystring—HMAC-SHA256 signing key
default_tenant_id / defaultTenantIdstring—Default tenant applied to events

​
In-Memory Store (Default)

The simplest configuration. Events are stored in memory and lost on process exit. 
tp = Trailproof()
Good for testing, short-lived processes, and quick prototyping.

​
JSONL File Store

Events are appended to a JSONL file — one JSON object per line. The file survives process restarts. 
tp = Trailproof(store="jsonl", path="events.jsonl")
  • File is created with 0o600 permissions (owner read/write only)
  • On initialization, reads the existing file to recover last_hash and event count
  • Append-only — existing lines are never modified
  • Human-readable with cat, grep, or jq
Use an absolute path or a path relative to your project root. The directory must exist — Trailproof creates the file but not parent directories.

​
HMAC Signing

Add HMAC-SHA256 signatures to prove event provenance. 
tp = Trailproof(signing_key="your-secret-key")
When a signing key is configured, every emitted event gets a signature field in the format hmac-sha256:<hex>. The hash chain works independently of signing — they’re separate integrity layers.

​
Default Tenant

Set a default tenant that’s applied to every event if tenant_id is not provided in the emit() call. 
tp = Trailproof(default_tenant_id="acme-corp")

# tenant_id defaults to "acme-corp"
event = tp.emit(
    event_type="app.action",
    actor_id="user-42",
    payload={"key": "value"},
)
print(event.tenant_id)  # "acme-corp"

​
Combined Configuration

All options can be used together: 
tp = Trailproof(
    store="jsonl",
    path=".trailproof/events.jsonl",
    signing_key="your-secret-key",
    default_tenant_id="acme-corp",
)