@axtary/ledger 0.1.0 → 0.2.0

package/dist/index.js

@@ -1,11 +1,20 @@
-import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, open, readFile, rename, rm } from "node:fs/promises";
 import { dirname } from "node:path";
-import { AxtaryDecisionSchema, hashJson, LedgerExecutionOutcomeSchema, LedgerRecordSchema, recordDecision, } from "@axtary/actionpass";
+import { AxtaryDecisionSchema, hashJson, LedgerExecutionOutcomeSchema, LedgerRecordSchema, recordActionPassRevocationEvent, recordDecision, } from "@axtary/actionpass";
+import { decodeProtectedHeader, importJWK, jwtVerify, SignJWT, } from "jose";
+import { lock } from "proper-lockfile";
 import { z } from "zod";
+import { merkleConsistencyProof, merkleInclusionProof, merkleLeafHash, merkleNodeHash, merkleTreeRoot, verifyMerkleConsistency, verifyMerkleInclusion, } from "./merkle.js";
+export { merkleConsistencyProof, merkleInclusionProof, merkleLeafHash, merkleNodeHash, merkleTreeRoot, verifyMerkleConsistency, verifyMerkleInclusion, };
+export { BEHAVIOR_STORE_VERSION, BehaviorStoreSchema, InMemoryBehaviorStore, FileBehaviorStore, deriveBehaviorSignals, recordBehaviorObservation, } from "./behavior.js";
+export { LEDGER_FORENSICS_VERSION, analyzeForensics, reconstructIncident, } from "./forensics.js";
 export const LOCAL_LEDGER_SCHEMA_VERSION = "axtary.local-ledger.v0";
+export const LOCAL_LEDGER_HEAD_SCHEMA_VERSION = "axtary.local-ledger-head.v0";
 export const LEDGER_EXPORT_SCHEMA_VERSION = "axtary.ledger_export.v0";
 export const LEDGER_SYNC_SCHEMA_VERSION = "axtary.ledger_sync.v0";
 export const LEDGER_SIEM_EVENT_SCHEMA_VERSION = "axtary.siem_event.v0";
+export const LEDGER_OTEL_EXPORT_SCHEMA_VERSION = "axtary.otel_trace_export.v0";
 export const LedgerAppendResultSchema = z.object({
     record: LedgerRecordSchema,
     lineNumber: z.number().int().positive(),
@@ -60,7 +69,18 @@ export const LedgerSiemEventSchema = z.object({
         }),
         provider: z
             .object({
-            name: z.enum(["github", "slack", "linear", "docs", "mcp", "aws", "gcp", "jira"]),
+            name: z.enum([
+                "github",
+                "slack",
+                "linear",
+                "docs",
+                "drive",
+                "mcp",
+                "aws",
+                "gcp",
+                "jira",
+                "postgres",
+            ]),
             tool: z.string().min(1),
             operation: z.string().min(1),
             resourceKind: z.string().min(1),
@@ -78,58 +98,81 @@ export const LedgerSyncResultSchema = z.object({
     lastLedgerHash: z.string().regex(/^sha256:[a-f0-9]{64}$/).nullable(),
     response: z.unknown().nullable(),
 });
+const LedgerHeadStateSchema = z.object({
+    schemaVersion: z.literal(LOCAL_LEDGER_HEAD_SCHEMA_VERSION),
+    fileSize: z.number().int().nonnegative(),
+    lineNumber: z.number().int().nonnegative(),
+    lastLedgerHash: z.string().regex(/^sha256:[a-f0-9]{64}$/).nullable(),
+});
 export class LocalJsonlLedger {
     filePath;
-    constructor(filePath) {
+    headPath;
+    options;
+    constructor(filePath, options = {}) {
         this.filePath = filePath;
+        this.headPath = `${filePath}.head.json`;
+        this.options = options;
     }
     async appendDecision(input) {
-        const records = await this.readRecords();
-        const previousLedgerHash = records.at(-1)?.ledgerHash ?? null;
-        const record = recordDecision({
-            action: input.action,
-            decision: input.decision,
-            actionPassId: input.actionPassId ?? null,
-            previousLedgerHash,
-            occurredAt: input.occurredAt,
+        const result = await this.withAppendLock(async (head) => {
+            const record = recordDecision({
+                action: input.action,
+                decision: input.decision,
+                actionPassId: input.actionPassId ?? null,
+                delegation: input.delegation,
+                budget: input.budget,
+                previousLedgerHash: head.lastLedgerHash,
+                occurredAt: input.occurredAt,
+            });
+            return this.appendLocked(record, head);
         });
-        return this.appendRecord(record);
+        await this.exportTelemetry(result.record);
+        return result;
     }
     async appendExecutionOutcome(input) {
-        const records = await this.readRecords();
-        const previousLedgerHash = records.at(-1)?.ledgerHash ?? null;
-        const executionOutcome = LedgerExecutionOutcomeSchema.parse(input.executionOutcome);
-        const record = recordDecision({
-            action: input.action,
-            decision: input.decision,
-            actionPassId: input.actionPassId ?? null,
-            previousLedgerHash,
-            occurredAt: input.occurredAt,
-            traceId: input.traceId,
-            executionOutcome,
-            correlationId: input.correlationId,
+        const result = await this.withAppendLock(async (head) => {
+            const executionOutcome = LedgerExecutionOutcomeSchema.parse(input.executionOutcome);
+            const record = recordDecision({
+                action: input.action,
+                decision: input.decision,
+                actionPassId: input.actionPassId ?? null,
+                delegation: input.delegation,
+                budget: input.budget,
+                previousLedgerHash: head.lastLedgerHash,
+                occurredAt: input.occurredAt,
+                traceId: input.traceId,
+                executionOutcome,
+                correlationId: input.correlationId,
+            });
+            return this.appendLocked(record, head);
         });
-        return this.appendRecord(record);
+        await this.exportTelemetry(result.record);
+        return result;
+    }
+    async appendRevocation(input) {
+        const result = await this.withAppendLock(async (head) => {
+            const record = recordActionPassRevocationEvent({
+                revokedRecord: input.revokedRecord,
+                revokedBy: input.revokedBy,
+                reason: input.reason,
+                occurredAt: input.occurredAt,
+                previousLedgerHash: head.lastLedgerHash,
+            });
+            return this.appendLocked(record, head);
+        });
+        await this.exportTelemetry(result.record);
+        return result;
     }
     async appendRecord(recordInput) {
-        const records = await this.readRecords();
-        const previousRecord = records.at(-1) ?? null;
         const record = LedgerRecordSchema.parse(recordInput);
-        if (record.previousLedgerHash !== (previousRecord?.ledgerHash ?? null)) {
-            throw new Error("ledger_previous_hash_mismatch");
-        }
-        assertRecordHash(record);
-        await mkdir(dirname(this.filePath), { recursive: true });
-        const nextContent = [...records, record]
-            .map((entry) => JSON.stringify(entry))
-            .join("\n");
-        const tmpPath = `${this.filePath}.${process.pid}.${Date.now()}.tmp`;
-        await writeFile(tmpPath, `${nextContent}\n`, { encoding: "utf8", flag: "wx" });
-        await rename(tmpPath, this.filePath);
-        return LedgerAppendResultSchema.parse({
-            record,
-            lineNumber: records.length + 1,
+        const result = await this.withAppendLock(async (head) => {
+            if (record.previousLedgerHash !== head.lastLedgerHash) {
+                throw new Error("ledger_previous_hash_mismatch");
+            }
+            return this.appendLocked(record, head);
         });
+        await this.exportTelemetry(result.record);
+        return result;
     }
     async readRecords() {
         const text = await readLedgerFile(this.filePath);
@@ -187,10 +230,133 @@ export class LocalJsonlLedger {
             lastLedgerHash: records.at(-1)?.ledgerHash ?? null,
         };
     }
+    async withAppendLock(operation) {
+        await mkdir(dirname(this.filePath), { recursive: true });
+        let compromisedReason = null;
+        const lockOptions = this.options.lock ?? {};
+        const release = await lock(this.filePath, {
+            realpath: false,
+            stale: lockOptions.staleMs ?? 10_000,
+            update: lockOptions.updateMs ?? 5_000,
+            retries: {
+                retries: lockOptions.retries ?? 100,
+                factor: 1.2,
+                minTimeout: lockOptions.minTimeoutMs ?? 10,
+                maxTimeout: lockOptions.maxTimeoutMs ?? 100,
+            },
+            onCompromised: (error) => {
+                compromisedReason = error.message;
+            },
+        });
+        try {
+            if (compromisedReason !== null) {
+                throw new Error(`ledger_lock_compromised:${compromisedReason}`);
+            }
+            const head = await loadLedgerHead(this.filePath, this.headPath);
+            const result = await operation(head);
+            if (compromisedReason !== null) {
+                throw new Error(`ledger_lock_compromised:${compromisedReason}`);
+            }
+            return result;
+        }
+        finally {
+            await release();
+        }
+    }
+    async appendLocked(recordInput, head) {
+        const record = LedgerRecordSchema.parse(recordInput);
+        if (record.previousLedgerHash !== head.lastLedgerHash) {
+            throw new Error("ledger_previous_hash_mismatch");
+        }
+        assertRecordHash(record);
+        const line = Buffer.from(`${JSON.stringify(record)}\n`, "utf8");
+        const handle = await open(this.filePath, "a+", 0o600);
+        let nextSize;
+        try {
+            await handle.chmod(0o600);
+            const before = await handle.stat();
+            if (before.size !== head.fileSize) {
+                throw new Error("ledger_concurrent_write_detected");
+            }
+            await writeAll(handle, line);
+            await handle.sync();
+            const after = await handle.stat();
+            nextSize = after.size;
+            if (nextSize !== before.size + line.byteLength) {
+                throw new Error("ledger_concurrent_write_detected");
+            }
+        }
+        finally {
+            await handle.close();
+        }
+        const nextHead = LedgerHeadStateSchema.parse({
+            schemaVersion: LOCAL_LEDGER_HEAD_SCHEMA_VERSION,
+            fileSize: nextSize,
+            lineNumber: head.lineNumber + 1,
+            lastLedgerHash: record.ledgerHash,
+        });
+        await persistLedgerHead(this.headPath, nextHead);
+        await syncDirectory(dirname(this.filePath));
+        return LedgerAppendResultSchema.parse({
+            record,
+            lineNumber: nextHead.lineNumber,
+        });
+    }
+    async exportTelemetry(record) {
+        await this.options.telemetry?.exportRecord(record);
+    }
+}
+export class OtlpHttpTraceExporter {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async exportRecord(record) {
+        await exportLedgerRecordsToOtlp({
+            ...this.options,
+            records: [record],
+        });
+    }
 }
 export async function readLedgerRecords(filePath) {
     return new LocalJsonlLedger(filePath).readRecords();
 }
+/**
+ * Revoke a pass through the single honest path used by both the CLI and the
+ * dashboard: first write the durable trust-store revocation (the enforcement
+ * authority the proxy/adapters/MCP check), then append a tamper-evident
+ * revocation event to the hash-chained ledger bound to the most recent record
+ * naming that pass. Enforcement is written first so a later audit-append
+ * failure still leaves the pass actually revoked. When no ledger record names
+ * the pass (e.g. it never ran locally), the revocation is still authoritative
+ * and `ledgerEvent` is null — never faked.
+ */
+export async function revokeActionPassWithLedgerEvent(input) {
+    const revocation = await input.trustStore.revokeActionPass({
+        passId: input.passId,
+        revokedBy: input.revokedBy,
+        reason: input.reason,
+        revokedAt: input.occurredAt,
+    });
+    const records = await input.ledger.readRecords();
+    const revokedRecord = [...records]
+        .reverse()
+        .find((record) => record.actionPassId === input.passId);
+    let ledgerEvent = null;
+    if (revokedRecord) {
+        ledgerEvent = await input.ledger.appendRevocation({
+            revokedRecord,
+            revokedBy: input.revokedBy,
+            reason: input.reason,
+            occurredAt: input.occurredAt,
+        });
+    }
+    return {
+        revocation,
+        ledgerEvent,
+        revokedRecordId: revokedRecord?.id ?? null,
+    };
+}
 export async function verifyLedgerFile(filePath) {
     return new LocalJsonlLedger(filePath).verify();
 }
@@ -226,6 +392,42 @@ export async function exportLedgerRecords(input) {
         records,
     });
 }
+export async function exportLedgerRecordsToOtlp(input) {
+    if (input.records.length === 0) {
+        throw new Error("otel_export_requires_records");
+    }
+    const fetchImpl = input.fetch ?? globalThis.fetch;
+    if (!fetchImpl) {
+        throw new Error("otel_export_fetch_required");
+    }
+    const records = input.records.map((record) => LedgerRecordSchema.parse(record));
+    const body = buildOtlpTraceRequest({
+        records,
+        serviceName: input.serviceName,
+        serviceVersion: input.serviceVersion,
+    });
+    const response = await fetchWithTimeout(fetchImpl, input.endpoint, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            accept: "application/json",
+            ...(input.headers ?? {}),
+        },
+        body: JSON.stringify(body),
+    }, input.timeoutMs);
+    await response.text();
+    if (!response.ok) {
+        throw new Error(`otel_export_failed:${response.status}`);
+    }
+    return {
+        schemaVersion: LEDGER_OTEL_EXPORT_SCHEMA_VERSION,
+        endpoint: input.endpoint,
+        exportedAt: new Date().toISOString(),
+        records: records.length,
+        spans: records.length,
+        status: response.status,
+    };
+}
 export async function syncLedgerExport(input) {
     const fetchImpl = input.fetch ?? globalThis.fetch;
     if (!fetchImpl) {
@@ -274,6 +476,518 @@ export function formatLedgerExport(input) {
 export function computeLedgerHash(record) {
     return hashJson(record);
 }
+/** Recompute a record's `ledgerHash` from its own content (spec §9.1 step 2). */
+function recomputeRecordLedgerHash(record) {
+    const { ledgerHash, ...recordWithoutHash } = record;
+    void ledgerHash;
+    return computeLedgerHash(recordWithoutHash);
+}
+// ---------------------------------------------------------------------------
+// Ledger attestation (axtary.ledger_attestation.v0)
+//
+// A detached, signed attestation over a ledger export: a JWS whose claims pin
+// the SHA-256 digest of the canonical (JCS) export plus the chain head/tail and
+// record count. An independent verifier needs only this artifact, the export,
+// and the issuer's public key (plus a JOSE library) to confirm the export was
+// signed by the issuer and has not been altered by a single byte — with no
+// Axtary internals. See spec/actionpass-v0.md §9.
+// ---------------------------------------------------------------------------
+export const LEDGER_ATTESTATION_VERSION = "axtary.ledger_attestation.v0";
+const LEDGER_ATTESTATION_TYP = "axtary-ledger-attestation+jwt";
+const LEDGER_ATTESTATION_ALGORITHMS = ["ES256", "EdDSA"];
+const SHA256_HASH = z.string().regex(/^sha256:[a-f0-9]{64}$/);
+export const LedgerAttestationClaimsSchema = z.object({
+    lav: z.literal(LEDGER_ATTESTATION_VERSION),
+    iss: z.string().min(1),
+    iat: z.number().int().positive(),
+    tenant: z.string().min(1).optional(),
+    exportDigest: SHA256_HASH,
+    recordCount: z.number().int().nonnegative(),
+    firstLedgerHash: SHA256_HASH.nullable(),
+    segmentHead: SHA256_HASH.nullable(),
+    sourceLastLedgerHash: SHA256_HASH.nullable(),
+    range: LedgerExportFilterSchema,
+    // RFC 6962 signed tree head (optional; older v0 attestations omit these and
+    // older verifiers ignore them — the exportDigest still binds the full export).
+    // `treeSize` equals `recordCount`; `merkleRoot` is the MTH over the per-record
+    // `ledgerHash` leaves, enabling inclusion/consistency proofs (spec §9.4).
+    merkleRoot: SHA256_HASH.optional(),
+    treeSize: z.number().int().nonnegative().optional(),
+});
+/** SHA-256 digest of the canonical (JCS) ledger export — the content binding. */
+export function computeLedgerExportDigest(exportInput) {
+    return hashJson(LedgerExportSchema.parse(exportInput));
+}
+/**
+ * RFC 6962 leaves for an export: one leaf per record, committing to that
+ * record's `ledgerHash`. Because a verifier recomputes each `ledgerHash` from
+ * record content (spec §9.1), binding leaves to `ledgerHash` transitively binds
+ * the full record content — a one-byte rewrite changes the leaf and the root.
+ */
+export function ledgerExportLeafHashes(exportInput) {
+    const exported = LedgerExportSchema.parse(exportInput);
+    return exported.records.map((record) => merkleLeafHash(Buffer.from(record.ledgerHash, "utf8")));
+}
+/** Merkle Tree Hash (RFC 6962) over the export's record leaves, as `sha256:hex`. */
+export function computeLedgerExportMerkleRoot(exportInput) {
+    const root = merkleTreeRoot(ledgerExportLeafHashes(exportInput));
+    return `sha256:${root.toString("hex")}`;
+}
+function hexFromSha256(value) {
+    return Buffer.from(value.replace(/^sha256:/, ""), "hex");
+}
+export async function attestLedgerExport(input) {
+    const exported = LedgerExportSchema.parse(input.export);
+    const now = input.now ?? new Date();
+    const claims = LedgerAttestationClaimsSchema.parse({
+        lav: LEDGER_ATTESTATION_VERSION,
+        iss: input.issuer,
+        iat: Math.floor(now.getTime() / 1000),
+        tenant: input.tenant,
+        exportDigest: hashJson(exported),
+        recordCount: exported.records.length,
+        firstLedgerHash: exported.records[0]?.ledgerHash ?? null,
+        segmentHead: exported.records.at(-1)?.ledgerHash ?? null,
+        sourceLastLedgerHash: exported.source.lastLedgerHash,
+        range: exported.filters,
+        merkleRoot: computeLedgerExportMerkleRoot(exported),
+        treeSize: exported.records.length,
+    });
+    const token = await new SignJWT(claims)
+        .setProtectedHeader({
+        alg: input.algorithm ?? "ES256",
+        typ: LEDGER_ATTESTATION_TYP,
+        kid: input.keyId,
+    })
+        .sign(input.signingKey);
+    return { schemaVersion: LEDGER_ATTESTATION_VERSION, token, claims };
+}
+/**
+ * Standalone verifier: confirm a ledger export carries a valid issuer signature
+ * and has not been altered. Needs only the export, the attestation token, and
+ * the issuer public key — re-derivable from the spec alone.
+ */
+export async function verifyLedgerAttestation(input) {
+    try {
+        const exported = LedgerExportSchema.parse(input.export);
+        const token = typeof input.attestation === "string"
+            ? input.attestation
+            : input.attestation.token;
+        const algorithms = input.algorithms ?? LEDGER_ATTESTATION_ALGORITHMS;
+        const header = decodeProtectedHeader(token);
+        if (header.typ !== LEDGER_ATTESTATION_TYP) {
+            return { valid: false, reason: "attestation_type_mismatch" };
+        }
+        const verificationKey = await resolveAttestationKey(input, header.kid, algorithms);
+        const { payload } = await jwtVerify(token, verificationKey, {
+            issuer: input.issuer,
+            algorithms,
+            typ: LEDGER_ATTESTATION_TYP,
+            currentDate: input.currentDate,
+        });
+        const claims = LedgerAttestationClaimsSchema.parse(payload);
+        const chainError = verifyExportRecordChain(exported);
+        if (chainError) {
+            return { valid: false, reason: chainError };
+        }
+        if (hashJson(exported) !== claims.exportDigest) {
+            return { valid: false, reason: "export_digest_mismatch" };
+        }
+        if (claims.recordCount !== exported.records.length) {
+            return { valid: false, reason: "export_record_count_mismatch" };
+        }
+        return { valid: true, claims, recomputedDigest: claims.exportDigest };
+    }
+    catch (error) {
+        return {
+            valid: false,
+            reason: error instanceof Error ? error.message : "attestation_verification_failed",
+        };
+    }
+}
+export function buildOtlpTraceRequest(input) {
+    return {
+        resourceSpans: [
+            {
+                resource: {
+                    attributes: otlpAttributes({
+                        "service.name": input.serviceName ?? "axtary-local",
+                        "service.version": input.serviceVersion ?? "0.2.0",
+                        "axtary.exporter": "ledger-otlp",
+                    }),
+                },
+                scopeSpans: [
+                    {
+                        scope: {
+                            name: "@axtary/ledger",
+                            version: "0.2.0",
+                        },
+                        spans: input.records.map(ledgerRecordToOtlpSpan),
+                    },
+                ],
+            },
+        ],
+    };
+}
+function ledgerRecordToOtlpSpan(record) {
+    const startedAt = dateToUnixNanos(record.occurredAt);
+    const endedAt = startedAt + BigInt(1_000_000);
+    const toolName = record.auditContext?.tool ?? record.providerEvidence?.tool ?? "unknown";
+    const status = otlpSpanStatus(record);
+    return {
+        traceId: traceIdForRecord(record),
+        spanId: spanIdForRecord(record),
+        name: `execute_tool ${toolName}`,
+        kind: "SPAN_KIND_INTERNAL",
+        startTimeUnixNano: startedAt.toString(),
+        endTimeUnixNano: endedAt.toString(),
+        attributes: otlpAttributes({
+            "gen_ai.operation.name": "execute_tool",
+            "gen_ai.tool.name": toolName,
+            "gen_ai.tool.type": "function",
+            "axtary.schema_version": record.schemaVersion,
+            "axtary.ledger.record_id": record.id,
+            "axtary.ledger.hash": record.ledgerHash,
+            "axtary.ledger.previous_hash": record.previousLedgerHash,
+            "axtary.action.hash": record.actionHash,
+            "axtary.action.payload_hash": record.payloadHash,
+            "axtary.action.pass_id": record.actionPassId,
+            "axtary.trace.id": record.traceId ?? null,
+            "axtary.correlation_id": record.correlationId ?? null,
+            "axtary.decision": record.decision,
+            "axtary.decision.reasons": record.reasons,
+            "axtary.policy.native_rule": record.policy.nativeRule,
+            "axtary.policy.version": record.policy.version,
+            "axtary.audit.tenant": record.auditContext?.tenant ?? null,
+            "axtary.audit.agent_id": record.auditContext?.agentId ?? null,
+            "axtary.audit.human_owner": record.auditContext?.humanOwner ?? null,
+            "axtary.audit.task_id": record.auditContext?.taskId ?? null,
+            "axtary.audit.resource": record.auditContext?.resource ?? null,
+            "axtary.execution.status": record.executionOutcome?.status ?? null,
+            "axtary.execution.result_id": record.executionOutcome?.resultId ?? null,
+            "axtary.execution.failure_reason": record.executionOutcome?.failureReason ?? null,
+        }),
+        ...(status ? { status } : {}),
+    };
+}
+function otlpSpanStatus(record) {
+    if (record.decision === "deny" ||
+        record.decision === "step_up" ||
+        record.executionOutcome?.status === "failed") {
+        return {
+            code: "STATUS_CODE_ERROR",
+            message: record.executionOutcome?.failureReason ??
+                record.reasons[0] ??
+                record.decision,
+        };
+    }
+    if (record.executionOutcome?.status === "succeeded") {
+        return { code: "STATUS_CODE_OK" };
+    }
+    return null;
+}
+function otlpAttributes(values) {
+    const attributes = [];
+    for (const [key, value] of Object.entries(values)) {
+        const otlpValue = toOtlpAnyValue(value);
+        if (otlpValue) {
+            attributes.push({ key, value: otlpValue });
+        }
+    }
+    return attributes;
+}
+function toOtlpAnyValue(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (Array.isArray(value)) {
+        return { arrayValue: { values: value.map((entry) => ({ stringValue: entry })) } };
+    }
+    if (typeof value === "boolean")
+        return { boolValue: value };
+    if (typeof value === "number")
+        return { intValue: Math.trunc(value).toString() };
+    return { stringValue: value };
+}
+function traceIdForRecord(record) {
+    const source = record.traceId ?? record.correlationId ?? record.id;
+    return hexBytes(`trace:${source}`, 16);
+}
+function spanIdForRecord(record) {
+    return hexBytes(`span:${record.id}`, 8);
+}
+function hexBytes(input, bytes) {
+    const hex = createHash("sha256").update(input).digest("hex").slice(0, bytes * 2);
+    return /^0+$/.test(hex) ? `1${hex.slice(1)}` : hex;
+}
+function dateToUnixNanos(isoDate) {
+    return BigInt(new Date(isoDate).getTime()) * BigInt(1_000_000);
+}
+/**
+ * Re-verify the exported records from the records alone: every record's own hash
+ * must recompute, and — for a full (unfiltered) export — `previousLedgerHash` must
+ * chain. Filtered exports are not contiguous, so only the per-record hash is
+ * asserted; reorder/truncation is still caught by the signed export digest.
+ */
+function verifyExportRecordChain(exported) {
+    const isFull = exported.filters.from === null &&
+        exported.filters.to === null &&
+        exported.filters.decisions === null;
+    let previous = null;
+    for (let index = 0; index < exported.records.length; index += 1) {
+        const record = exported.records[index];
+        try {
+            assertRecordHash(record);
+        }
+        catch {
+            return `ledger_record_hash_mismatch:${index + 1}`;
+        }
+        if (isFull) {
+            if (record.previousLedgerHash !== previous) {
+                return `ledger_previous_hash_mismatch:${index + 1}`;
+            }
+            previous = record.ledgerHash;
+        }
+    }
+    return null;
+}
+async function resolveAttestationKey(input, keyId, algorithms) {
+    let key;
+    if (input.verificationKeys) {
+        key =
+            typeof input.verificationKeys === "function"
+                ? await input.verificationKeys(keyId)
+                : keyId
+                    ? input.verificationKeys[keyId]
+                    : undefined;
+        if (!key) {
+            throw new Error(keyId ? `verification_key_not_found:${keyId}` : "verification_key_id_required");
+        }
+    }
+    else {
+        if (!input.verificationKey) {
+            throw new Error("verification_key_required");
+        }
+        key = input.verificationKey;
+    }
+    return normalizeVerificationKey(key, algorithms);
+}
+async function normalizeVerificationKey(key, algorithms) {
+    if (isJwk(key)) {
+        const imported = await importJWK(key, key.alg ?? algorithms[0] ?? "ES256");
+        return imported;
+    }
+    return key;
+}
+function isJwk(key) {
+    return (typeof key === "object" &&
+        key !== null &&
+        !(key instanceof Uint8Array) &&
+        "kty" in key);
+}
+// ---------------------------------------------------------------------------
+// Attestation bundle: a self-contained artifact (export + token + public key)
+// that a third party can verify with nothing but a JOSE library and §3/§9 of
+// the spec. This is what `axtary attest-ledger` emits and `verify-export` reads.
+// ---------------------------------------------------------------------------
+export const LEDGER_ATTESTATION_BUNDLE_VERSION = "axtary.ledger_attestation_bundle.v0";
+export const LedgerAttestationBundleSchema = z.object({
+    schemaVersion: z.literal(LEDGER_ATTESTATION_BUNDLE_VERSION),
+    export: LedgerExportSchema,
+    attestation: z.object({
+        token: z.string().min(1),
+        claims: LedgerAttestationClaimsSchema,
+    }),
+    publicJwk: z.record(z.string(), z.unknown()),
+    keyId: z.string().min(1).nullable(),
+});
+/** Bundle an export, its attestation, and the public key into one artifact. */
+export function buildLedgerAttestationBundle(input) {
+    return LedgerAttestationBundleSchema.parse({
+        schemaVersion: LEDGER_ATTESTATION_BUNDLE_VERSION,
+        export: input.export,
+        attestation: {
+            token: input.attestation.token,
+            claims: input.attestation.claims,
+        },
+        publicJwk: input.publicJwk,
+        keyId: input.keyId ?? null,
+    });
+}
+/** Verify a self-contained attestation bundle (export + token + embedded public key). */
+export async function verifyLedgerAttestationBundle(bundleInput, options = {}) {
+    let bundle;
+    try {
+        bundle = LedgerAttestationBundleSchema.parse(bundleInput);
+    }
+    catch (error) {
+        return {
+            valid: false,
+            reason: error instanceof Error ? `invalid_bundle:${error.message}` : "invalid_bundle",
+        };
+    }
+    return verifyLedgerAttestation({
+        export: bundle.export,
+        attestation: bundle.attestation.token,
+        verificationKey: bundle.publicJwk,
+        issuer: options.issuer,
+        algorithms: options.algorithms,
+        currentDate: options.currentDate,
+    });
+}
+// ---------------------------------------------------------------------------
+// RFC 6962 transparency-log proofs (spec/actionpass-v0.md §9.4)
+//
+// Inclusion and consistency proof artifacts over the export's Merkle tree. They
+// are not signed themselves; trust flows from the signed tree head (the
+// attestation's `merkleRoot`/`treeSize`). A verifier binds a proof to a signed
+// head by passing the attestation's `merkleRoot` as the expected root.
+// ---------------------------------------------------------------------------
+const HEX_NODE = z.string().regex(/^[a-f0-9]{64}$/);
+export const LEDGER_INCLUSION_PROOF_VERSION = "axtary.ledger_inclusion_proof.v0";
+export const LedgerInclusionProofSchema = z.object({
+    schemaVersion: z.literal(LEDGER_INCLUSION_PROOF_VERSION),
+    recordId: z.string().min(1),
+    ledgerHash: SHA256_HASH,
+    leafIndex: z.number().int().nonnegative(),
+    treeSize: z.number().int().positive(),
+    merkleRoot: SHA256_HASH,
+    auditPath: z.array(HEX_NODE),
+});
+export const LEDGER_CONSISTENCY_PROOF_VERSION = "axtary.ledger_consistency_proof.v0";
+export const LedgerConsistencyProofSchema = z.object({
+    schemaVersion: z.literal(LEDGER_CONSISTENCY_PROOF_VERSION),
+    firstSize: z.number().int().positive(),
+    secondSize: z.number().int().positive(),
+    firstRoot: SHA256_HASH,
+    secondRoot: SHA256_HASH,
+    proof: z.array(HEX_NODE),
+});
+/** Build an inclusion proof for one record (by id or 0-based index). */
+export function proveLedgerInclusion(input) {
+    const exported = LedgerExportSchema.parse(input.export);
+    if (exported.records.length === 0) {
+        throw new Error("ledger_inclusion_empty_export");
+    }
+    const index = input.index ??
+        exported.records.findIndex((record) => record.id === input.recordId);
+    if (index < 0 || index >= exported.records.length) {
+        throw new Error("ledger_inclusion_record_not_found");
+    }
+    const record = exported.records[index];
+    const leaves = ledgerExportLeafHashes(exported);
+    const auditPath = merkleInclusionProof(leaves, index);
+    const root = merkleTreeRoot(leaves);
+    return LedgerInclusionProofSchema.parse({
+        schemaVersion: LEDGER_INCLUSION_PROOF_VERSION,
+        recordId: record.id,
+        ledgerHash: record.ledgerHash,
+        leafIndex: index,
+        treeSize: exported.records.length,
+        merkleRoot: `sha256:${root.toString("hex")}`,
+        auditPath: auditPath.map((node) => node.toString("hex")),
+    });
+}
+/**
+ * Verify an inclusion proof against a Merkle root. Pass `expectedRoot` (e.g. a
+ * signed attestation's `merkleRoot`) to bind the proof to a signed tree head.
+ * Pass `record` to additionally recompute the leaf from record content so a
+ * proof cannot smuggle a `ledgerHash` that does not match the record.
+ */
+export function verifyLedgerInclusionProof(input) {
+    let proof;
+    try {
+        proof = LedgerInclusionProofSchema.parse(input.proof);
+    }
+    catch (error) {
+        return {
+            valid: false,
+            reason: error instanceof Error ? `invalid_proof:${error.message}` : "invalid_proof",
+        };
+    }
+    if (proof.leafIndex >= proof.treeSize) {
+        return { valid: false, reason: "leaf_index_out_of_range" };
+    }
+    if (input.expectedRoot && input.expectedRoot !== proof.merkleRoot) {
+        return { valid: false, reason: "merkle_root_mismatch" };
+    }
+    if (input.record) {
+        if (recomputeRecordLedgerHash(input.record) !== proof.ledgerHash) {
+            return { valid: false, reason: "ledger_record_hash_mismatch" };
+        }
+        if (input.record.id !== proof.recordId) {
+            return { valid: false, reason: "record_id_mismatch" };
+        }
+    }
+    const ok = verifyMerkleInclusion({
+        leafHash: merkleLeafHash(Buffer.from(proof.ledgerHash, "utf8")),
+        index: proof.leafIndex,
+        treeSize: proof.treeSize,
+        proof: proof.auditPath.map((node) => Buffer.from(node, "hex")),
+        root: hexFromSha256(proof.merkleRoot),
+    });
+    return ok ? { valid: true } : { valid: false, reason: "merkle_inclusion_invalid" };
+}
+/**
+ * Build a consistency proof showing the `second` export append-only-extends the
+ * `first`. Roots are computed from each export independently; if `first` is not
+ * a genuine prefix, verification fails (the honest, fail-closed outcome).
+ */
+export function proveLedgerConsistency(input) {
+    const first = LedgerExportSchema.parse(input.first);
+    const second = LedgerExportSchema.parse(input.second);
+    const firstSize = first.records.length;
+    const secondSize = second.records.length;
+    if (firstSize === 0) {
+        throw new Error("ledger_consistency_empty_first");
+    }
+    if (firstSize > secondSize) {
+        throw new Error("ledger_consistency_first_larger");
+    }
+    const firstLeaves = ledgerExportLeafHashes(first);
+    const secondLeaves = ledgerExportLeafHashes(second);
+    const proof = merkleConsistencyProof(secondLeaves, firstSize);
+    return LedgerConsistencyProofSchema.parse({
+        schemaVersion: LEDGER_CONSISTENCY_PROOF_VERSION,
+        firstSize,
+        secondSize,
+        firstRoot: `sha256:${merkleTreeRoot(firstLeaves).toString("hex")}`,
+        secondRoot: `sha256:${merkleTreeRoot(secondLeaves).toString("hex")}`,
+        proof: proof.map((node) => node.toString("hex")),
+    });
+}
+/**
+ * Verify a consistency proof. Pass `firstExpectedRoot`/`secondExpectedRoot`
+ * (the two signed heads' `merkleRoot`s) to bind the proof to signed tree heads.
+ */
+export function verifyLedgerConsistencyProof(input) {
+    let proof;
+    try {
+        proof = LedgerConsistencyProofSchema.parse(input.proof);
+    }
+    catch (error) {
+        return {
+            valid: false,
+            reason: error instanceof Error ? `invalid_proof:${error.message}` : "invalid_proof",
+        };
+    }
+    if (proof.firstSize > proof.secondSize) {
+        return { valid: false, reason: "first_size_exceeds_second" };
+    }
+    if (input.firstExpectedRoot && input.firstExpectedRoot !== proof.firstRoot) {
+        return { valid: false, reason: "first_root_mismatch" };
+    }
+    if (input.secondExpectedRoot && input.secondExpectedRoot !== proof.secondRoot) {
+        return { valid: false, reason: "second_root_mismatch" };
+    }
+    const ok = verifyMerkleConsistency({
+        firstSize: proof.firstSize,
+        secondSize: proof.secondSize,
+        firstRoot: hexFromSha256(proof.firstRoot),
+        secondRoot: hexFromSha256(proof.secondRoot),
+        proof: proof.proof.map((node) => Buffer.from(node, "hex")),
+    });
+    return ok ? { valid: true } : { valid: false, reason: "merkle_consistency_invalid" };
+}
 function toSiemEvent(record, exported) {
     return {
         "@timestamp": record.occurredAt,
@@ -368,6 +1082,175 @@ function assertRecordHash(record) {
         throw new Error("ledger_hash_mismatch");
     }
 }
+async function loadLedgerHead(filePath, headPath) {
+    const handle = await open(filePath, "a+", 0o600);
+    try {
+        const stats = await handle.stat();
+        const persisted = await readLedgerHead(headPath);
+        if (stats.size === 0) {
+            if (persisted && persisted.fileSize > 0) {
+                throw new Error("ledger_truncated");
+            }
+            return LedgerHeadStateSchema.parse({
+                schemaVersion: LOCAL_LEDGER_HEAD_SCHEMA_VERSION,
+                fileSize: 0,
+                lineNumber: 0,
+                lastLedgerHash: null,
+            });
+        }
+        if (persisted && stats.size < persisted.fileSize) {
+            throw new Error("ledger_truncated");
+        }
+        if (persisted && persisted.fileSize === stats.size) {
+            const tail = await readLastLedgerRecord(handle, stats.size, persisted.lineNumber);
+            assertRecordHash(tail);
+            if (tail.ledgerHash !== persisted.lastLedgerHash) {
+                throw new Error("ledger_head_hash_mismatch");
+            }
+            return persisted;
+        }
+    }
+    finally {
+        await handle.close();
+    }
+    return recoverLedgerHead(filePath);
+}
+async function readLedgerHead(headPath) {
+    try {
+        return LedgerHeadStateSchema.parse(JSON.parse(await readFile(headPath, "utf8")));
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+}
+async function recoverLedgerHead(filePath) {
+    const text = await readLedgerFile(filePath);
+    const lines = text.split("\n").filter((line) => line.trim().length > 0);
+    let previousLedgerHash = null;
+    for (let index = 0; index < lines.length; index += 1) {
+        const record = parseLedgerLine(lines[index], index + 1);
+        if (record.previousLedgerHash !== previousLedgerHash) {
+            throw new Error(`ledger_previous_hash_mismatch:${index + 1}`);
+        }
+        assertRecordHash(record);
+        previousLedgerHash = record.ledgerHash;
+    }
+    const stats = await open(filePath, "r").then(async (handle) => {
+        try {
+            return await handle.stat();
+        }
+        finally {
+            await handle.close();
+        }
+    });
+    return LedgerHeadStateSchema.parse({
+        schemaVersion: LOCAL_LEDGER_HEAD_SCHEMA_VERSION,
+        fileSize: stats.size,
+        lineNumber: lines.length,
+        lastLedgerHash: previousLedgerHash,
+    });
+}
+async function readLastLedgerRecord(handle, fileSize, lineNumber) {
+    const chunkSize = 64 * 1024;
+    let cursor = fileSize;
+    let suffix = Buffer.alloc(0);
+    let trimmedEnd = fileSize;
+    while (cursor > 0) {
+        const length = Math.min(chunkSize, cursor);
+        const position = cursor - length;
+        const chunk = Buffer.allocUnsafe(length);
+        const { bytesRead } = await handle.read(chunk, 0, length, position);
+        const bytes = chunk.subarray(0, bytesRead);
+        if (trimmedEnd === fileSize) {
+            let index = bytes.length - 1;
+            while (index >= 0 && (bytes[index] === 0x0a || bytes[index] === 0x0d)) {
+                index -= 1;
+                trimmedEnd -= 1;
+            }
+            suffix = Buffer.concat([bytes.subarray(index + 1, bytes.length), suffix]);
+            if (index < 0) {
+                cursor = position;
+                continue;
+            }
+            const content = bytes.subarray(0, index + 1);
+            const newline = content.lastIndexOf(0x0a);
+            if (newline >= 0) {
+                const line = Buffer.concat([content.subarray(newline + 1), suffix])
+                    .toString("utf8")
+                    .trim();
+                return parseLedgerLine(line, lineNumber);
+            }
+            suffix = Buffer.concat([content, suffix]);
+        }
+        else {
+            const newline = bytes.lastIndexOf(0x0a);
+            if (newline >= 0) {
+                const line = Buffer.concat([bytes.subarray(newline + 1), suffix])
+                    .toString("utf8")
+                    .trim();
+                return parseLedgerLine(line, lineNumber);
+            }
+            suffix = Buffer.concat([bytes, suffix]);
+        }
+        cursor = position;
+    }
+    const line = suffix.toString("utf8").trim();
+    if (!line) {
+        throw new Error("ledger_tail_missing");
+    }
+    return parseLedgerLine(line, lineNumber);
+}
+async function writeAll(handle, data) {
+    let offset = 0;
+    while (offset < data.byteLength) {
+        const { bytesWritten } = await handle.write(data, offset, data.byteLength - offset);
+        if (bytesWritten < 1) {
+            throw new Error("ledger_append_incomplete");
+        }
+        offset += bytesWritten;
+    }
+}
+async function persistLedgerHead(headPath, head) {
+    const tmpPath = `${headPath}.${process.pid}.${randomUUID()}.tmp`;
+    let renamed = false;
+    try {
+        const handle = await open(tmpPath, "wx", 0o600);
+        try {
+            await writeAll(handle, Buffer.from(`${JSON.stringify(head)}\n`, "utf8"));
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await rename(tmpPath, headPath);
+        renamed = true;
+    }
+    finally {
+        if (!renamed) {
+            await rm(tmpPath, { force: true });
+        }
+    }
+}
+async function syncDirectory(directory) {
+    const handle = await open(directory, "r");
+    try {
+        await handle.sync();
+    }
+    catch (error) {
+        if (process.platform === "win32" &&
+            isNodeError(error) &&
+            ["EISDIR", "EINVAL", "ENOTSUP", "EPERM"].includes(error.code ?? "")) {
+            return;
+        }
+        throw error;
+    }
+    finally {
+        await handle.close();
+    }
+}
 async function readLedgerFile(filePath) {
     try {
         return await readFile(filePath, "utf8");