> ## Documentation Index
> Fetch the complete documentation index at: https://trailproof.kyberon.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Constructor options for the Trailproof class

# 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.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  tp = Trailproof()
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  const tp = new Trailproof();
  ```
</CodeGroup>

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.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  tp = Trailproof(store="jsonl", path="events.jsonl")
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  const tp = new Trailproof({ store: "jsonl", path: "events.jsonl" });
  ```
</CodeGroup>

* 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`

<Tip>
  Use an absolute path or a path relative to your project root. The directory must exist -- Trailproof creates the file but not parent directories.
</Tip>

## HMAC Signing

Add HMAC-SHA256 signatures to prove event provenance.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  tp = Trailproof(signing_key="your-secret-key")
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  const tp = new Trailproof({ signingKey: "your-secret-key" });
  ```
</CodeGroup>

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.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  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"
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  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"
  ```
</CodeGroup>

## Combined Configuration

All options can be used together:

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  tp = Trailproof(
      store="jsonl",
      path=".trailproof/events.jsonl",
      signing_key="your-secret-key",
      default_tenant_id="acme-corp",
  )
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  const tp = new Trailproof({
    store: "jsonl",
    path: ".trailproof/events.jsonl",
    signingKey: "your-secret-key",
    defaultTenantId: "acme-corp",
  });
  ```
</CodeGroup>