@axtary/ledger

Append-only JSONL action ledger with hash-chain verification for Axtary.

Early 0.x release: the runtime path is real and tested, but the API is not stable yet and may change between minor versions.

npm install @axtary/ledger

What It Does

• Appends Axtary ledger records to local JSONL.
• Maintains a previousLedgerHash -> ledgerHash chain.
• Reads ledger records back in order.
• Verifies hash-chain continuity and record integrity.
• Exports verified records by inclusive date range and decision type.
• Formats verified exports as JSON, raw ledger JSONL, or SIEM-friendly JSONL events.
• Syncs a verified export to an optional hosted endpoint.
• Fails closed on malformed JSONL records.
• Carries trace IDs and sanitized provider evidence for GitHub, Slack, and Linear records when that evidence was present at decision time.

Quickstart

This example runs as-is with Node 20+:

import { evaluatePolicy } from "@axtary/policy";
import { parseNormalizedAction, demoAction } from "@axtary/actionpass";
import { LocalJsonlLedger, verifyLedgerFile } from "@axtary/ledger";

const ledger = new LocalJsonlLedger(".axtary/ledger.jsonl");

// Every decision appends a record chained to the previous record's hash.
const action = parseNormalizedAction(demoAction);
await ledger.appendDecision({ action, decision: evaluatePolicy(action) });

// Verification fails closed on any edited, reordered, or deleted line.
const verification = await verifyLedgerFile(".axtary/ledger.jsonl");
console.log(verification.valid, verification.records.length);

Design Notes

The ledger is local-first. It is not a database, SIEM, or remote audit service. It gives the proxy and adapters a durable local trail that can later be uploaded, exported, or re-verified. Export and sync both verify the full hash chain before returning or sending filtered records. SIEM JSONL events include timestamps, trace IDs, outcomes, provider/resource summaries, policy metadata, reasons, and hashes without expanding protected action payloads or credential-bearing provider responses.

Hosted sync should use signed ledger sync tokens rather than dashboard user sessions. Sync tokens carry a signed kid so hosted verification can rotate keys with AXTARY_LEDGER_SYNC_TOKEN_KID and a JSON AXTARY_LEDGER_SYNC_TOKEN_SECRETS keyring. Hosted retention can be bounded with AXTARY_LEDGER_SYNC_MAX_BATCHES, AXTARY_LEDGER_SYNC_MAX_AGE_DAYS, or stricter limits embedded in the signed sync token.

The hosted sync store now sits behind a persistence adapter. The default adapter is local JSON at .axtary/hosted-ledger-sync.json; set AXTARY_LEDGER_SYNC_STORE=neon plus AXTARY_LEDGER_SYNC_DATABASE_URL to use the Neon/Postgres adapter. Apply migrations/neon/001_hosted_ledger_sync_batches.sql for deployed environments; docs/neon-hosted-sync-runbook.md covers the hosted setup and verification flow. Source file paths can be reduced before storage with AXTARY_LEDGER_SYNC_REDACT_SOURCE_FILE_PATH=basename or redact. Hash-bound ledger record fields are preserved so synced evidence remains verifiable.

Hosted audit search is available through /api/ledger/sync?view=records with optional q, decision, from, to, and limit query parameters. The ledger dashboard exposes those filters for tenant-scoped synced evidence, including record detail inspection, normalized provider resources, GitHub diff/file summaries, Slack channel/message evidence, Linear issue field changes, trace IDs, and batch-id drilldown. SIEM exports remain available through /api/ledger/sync?format=siem-jsonl.

Fail-closed and secret boundaries:

• Ledger export fails if any source record breaks JSON parsing, previous-hash continuity, or record-hash integrity.
• Hosted sync accepts only verified exports through the sync route and keeps provider credentials, sync tokens, dashboard sessions, cookies, and auth headers out of stored batches and browser payloads.
• Provider evidence is extracted from normalized actions, not raw provider HTTP responses. GitHub content payloads record paths and lengths rather than file bodies unless an explicit sanitized diff is supplied.

Concurrent writers should coordinate through a single process or external file lock. The first proxy should own writes for a given ledger file.