Configuration

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

Options

Option	Type	Default	Description
`store`	`"memory"` or `"jsonl"`	`"memory"`	Storage backend
`path`	`string`	—	File path for the JSONL store
`signing_key` / `signingKey`	`string`	—	HMAC-SHA256 signing key
`default_tenant_id` / `defaultTenantId`	`string`	—	Default tenant applied to events

In-Memory Store (Default)

The simplest configuration. Events are stored in memory and lost on process exit.

tp = Trailproof()

const tp = new 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")

const tp = new 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")

const tp = new Trailproof({ signingKey: "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"

const tp = new Trailproof({ defaultTenantId: "acme-corp" });

const event = tp.emit({
  eventType: "app.action",
  actorId: "user-42",
  payload: { key: "value" },
});
console.log(event.tenantId); // "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",
)

const tp = new Trailproof({
  store: "jsonl",
  path: ".trailproof/events.jsonl",
  signingKey: "your-secret-key",
  defaultTenantId: "acme-corp",
});

​Configuration

​Options

​In-Memory Store (Default)

​JSONL File Store

​HMAC Signing

​Default Tenant

​Combined Configuration

Configuration

Options

In-Memory Store (Default)

JSONL File Store

HMAC Signing

Default Tenant

Combined Configuration