mandat 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+import { Guard, type GuardOptions } from "./guard/guard.ts";
+export * from "./policy/engine.ts";
+export { compileExpr, ExprError } from "./policy/expr.ts";
+export * from "./guard/guard.ts";
+export * from "./guard/pinning.ts";
+export * from "./guard/remote.ts";
+export * from "./mcp/server.ts";
+export { protect } from "./mcp/protect.ts";
+export * from "./sts/sts.ts";
+export * from "./sts/jwt.ts";
+export * from "./sts/revocation.ts";
+export * from "./ledger/ledger.ts";
+export * from "./ledger/redact.ts";
+export * from "./ledger/export.ts";
+export * from "./ledger/report.ts";
+export * from "./approvals/approvals.ts";
+export * from "./scan/findings.ts";
+export { scanRemote } from "./scan/remote.ts";
+export { scanConfigFile, scanServers, scanSource } from "./scan/static.ts";
+export { createControlPlane, type ControlPlane } from "./controlplane/server.ts";
+export { loadConfig, hashApiKey, type ControlPlaneConfig } from "./controlplane/config.ts";
+export { Bridge, type BridgeOptions } from "./bridge.ts";
+export { login, discover, refreshSession, currentIdToken, loadSession, saveSession, clearSession, pkcePair, OidcError, type Session, type LoginOptions, type OidcMetadata } from "./oidc.ts";
+export { exchangeToken, devLogin, McpHttpClient, type ExchangeOptions, type TaskToken } from "./client.ts";
+export interface CreateGuardOptions extends Partial<Pick<GuardOptions, "mode" | "approvalWaitMs" | "pinning" | "redaction" | "source" | "log">> {
+    /** Canonical URL of the protected MCP server (token audience). */
+    resource: string;
+    /** Mandat control plane base URL. */
+    controlPlane: string;
+    /** Control plane API key with the `service` role. */
+    apiKey: string;
+    /** Use a local policy file (hot-reloaded) instead of the control plane's policy. */
+    policyFile?: string;
+    /** Directory for the policy snapshot and optional local ledger copy. Default ".mandat". */
+    dataDir?: string;
+    /** Also keep a local hash-chained copy of this guard's records. */
+    localLedger?: boolean;
+}
+/**
+ * Creates a Guard wired to a Mandat control plane: JWKS + issuer discovered from AS metadata,
+ * revocations polled every 2 s, policy pulled with an offline snapshot, approvals and ledger over HTTP.
+ */
+export declare function createGuard(o: CreateGuardOptions): Promise<Guard>;

package/dist/index.js

@@ -0,0 +1,67 @@
+// Public API of the `mandat` package.
+import { join } from "node:path";
+import { Guard } from "./guard/guard.js";
+import { FilePolicy, HttpLedgerSink, RemoteApprovalBroker, RemotePolicy, RemoteRevocations } from "./guard/remote.js";
+import { FileLedger } from "./ledger/ledger.js";
+export * from "./policy/engine.js";
+export { compileExpr, ExprError } from "./policy/expr.js";
+export * from "./guard/guard.js";
+export * from "./guard/pinning.js";
+export * from "./guard/remote.js";
+export * from "./mcp/server.js";
+export { protect } from "./mcp/protect.js";
+export * from "./sts/sts.js";
+export * from "./sts/jwt.js";
+export * from "./sts/revocation.js";
+export * from "./ledger/ledger.js";
+export * from "./ledger/redact.js";
+export * from "./ledger/export.js";
+export * from "./ledger/report.js";
+export * from "./approvals/approvals.js";
+export * from "./scan/findings.js";
+export { scanRemote } from "./scan/remote.js";
+export { scanConfigFile, scanServers, scanSource } from "./scan/static.js";
+export { createControlPlane } from "./controlplane/server.js";
+export { loadConfig, hashApiKey } from "./controlplane/config.js";
+export { Bridge } from "./bridge.js";
+export { login, discover, refreshSession, currentIdToken, loadSession, saveSession, clearSession, pkcePair, OidcError } from "./oidc.js";
+export { exchangeToken, devLogin, McpHttpClient } from "./client.js";
+/**
+ * Creates a Guard wired to a Mandat control plane: JWKS + issuer discovered from AS metadata,
+ * revocations polled every 2 s, policy pulled with an offline snapshot, approvals and ledger over HTTP.
+ */
+export async function createGuard(o) {
+    const cp = { url: o.controlPlane, apiKey: o.apiKey };
+    const dataDir = o.dataDir ?? ".mandat";
+    const meta = await fetch(`${o.controlPlane.replace(/\/$/, "")}/.well-known/oauth-authorization-server`, { signal: AbortSignal.timeout(5000) })
+        .then((r) => (r.ok ? r.json() : null))
+        .catch(() => null);
+    const issuer = meta?.issuer ?? o.controlPlane.replace(/\/$/, "");
+    const revocations = new RemoteRevocations(cp);
+    await revocations.refresh();
+    let policy;
+    if (o.policyFile) {
+        policy = new FilePolicy(o.policyFile);
+    }
+    else {
+        const rp = new RemotePolicy(cp, { snapshotPath: join(dataDir, "policy.snapshot.json") });
+        await rp.refresh();
+        rp.current(); // throws if neither control plane nor snapshot is available
+        policy = rp;
+    }
+    return new Guard({
+        resource: o.resource,
+        issuer,
+        jwksUri: meta?.jwks_uri,
+        policy,
+        revocations,
+        approvals: new RemoteApprovalBroker(cp),
+        ledger: new HttpLedgerSink(cp, { local: o.localLedger ? new FileLedger(join(dataDir, "guard-ledger.jsonl")) : undefined }),
+        mode: o.mode,
+        approvalWaitMs: o.approvalWaitMs,
+        pinning: o.pinning,
+        redaction: o.redaction,
+        source: o.source,
+        log: o.log,
+    });
+}

package/dist/ledger/export.d.ts

@@ -0,0 +1,27 @@
+import type { ActionRecord } from "./ledger.ts";
+export declare function toOcsf(r: ActionRecord): Record<string, unknown>;
+export declare function describe(r: ActionRecord): string;
+export declare function toOtelSpan(r: ActionRecord): Record<string, unknown>;
+export interface OtlpExporterOptions {
+    /** Base OTLP/HTTP endpoint, e.g. http://localhost:4318 (".../v1/traces" is appended). */
+    endpoint: string;
+    headers?: Record<string, string>;
+    serviceName?: string;
+    batchSize?: number;
+    flushIntervalMs?: number;
+    maxQueue?: number;
+}
+/** Off the critical path: `push` only enqueues; a timer flushes. Failed batches are re-queued with backoff. */
+export declare class OtlpExporter {
+    private queue;
+    private timer;
+    private flushing;
+    private failures;
+    private opts;
+    dropped: number;
+    constructor(opts: OtlpExporterOptions);
+    push(r: ActionRecord): void;
+    flush(): Promise<void>;
+    get backoffActive(): boolean;
+    close(): Promise<void>;
+}

package/dist/ledger/export.js

@@ -0,0 +1,169 @@
+// Ledger -> SIEM / observability formats:
+//   - OCSF 1.x "API Activity" (class 6003) events, type `agent.tool_call` in `metadata.labels`
+//   - OpenTelemetry spans following the GenAI semantic conventions (`execute_tool`) + `mandat.*` attributes,
+//     shipped over OTLP/HTTP JSON. Delivery is asynchronous, batched and retried (at-least-once).
+import { sha256 } from "../util.js";
+const OCSF_VERSION = "1.3.0";
+export function toOcsf(r) {
+    const activity = r.tool?.risk === "read" ? 2 : r.tool?.risk === "destructive" ? 4 : r.tool?.risk === "write" ? 3 : 99;
+    const failed = r.outcome?.status === "error" || r.outcome?.status === "blocked";
+    const severity = r.decision?.final === "deny" ? 3 : r.tool?.risk === "destructive" || r.tool?.risk === "financial" ? 2 : 1;
+    return {
+        class_uid: 6003,
+        class_name: "API Activity",
+        category_uid: 6,
+        category_name: "Application Activity",
+        activity_id: activity,
+        type_uid: 6003 * 100 + activity,
+        time: Date.parse(r.ts),
+        severity_id: severity,
+        status_id: failed ? 2 : 1,
+        status: r.outcome?.status ?? r.decision?.final,
+        status_detail: r.outcome?.error ?? r.decision?.reasons?.join("; "),
+        message: describe(r),
+        metadata: {
+            version: OCSF_VERSION,
+            uid: r.id,
+            correlation_uid: r.task_id ?? undefined,
+            labels: [r.type, ...(r.tags ?? [])],
+            product: { name: "Mandat", vendor_name: "Mandat", version: "0.1.0" },
+            sequence: r.seq,
+        },
+        actor: {
+            user: r.principal ? { uid: r.principal.sub, email_addr: r.principal.email ?? undefined, org: r.principal.tenant ? { uid: r.principal.tenant } : undefined } : undefined,
+            app_name: r.agent?.id,
+            invoked_by: r.actor_chain?.join(" <- "),
+            authorizations: r.decision ? [{ decision: r.decision.final, policy: { uid: r.decision.policy_version, name: r.decision.rules.join(",") } }] : undefined,
+        },
+        api: r.tool ? { operation: r.tool.name, service: { name: r.tool.server ?? "unknown" }, request: { uid: r.id } } : undefined,
+        unmapped: {
+            mandat: {
+                record_hash: r.hash,
+                prev_hash: r.prev_hash,
+                effect: r.decision?.effect,
+                args: r.args,
+                approval: r.approval,
+                session: r.session,
+                token_jti: r.token_jti,
+                agent_version: r.agent?.version,
+                prompt_hash: r.agent?.prompt_hash,
+                details: r.details,
+            },
+        },
+    };
+}
+export function describe(r) {
+    if (r.type === "agent.tool_call") {
+        const who = r.principal?.sub ?? "?";
+        return `${r.agent?.id ?? "?"} on behalf of ${who} called ${r.tool?.name} -> ${r.decision?.final ?? "?"} (${r.decision?.rules.join(",")})`;
+    }
+    return `${r.type}${r.details ? " " + JSON.stringify(r.details) : ""}`;
+}
+function attr(key, v) {
+    if (v === undefined || v === null)
+        return null;
+    if (typeof v === "boolean")
+        return { key, value: { boolValue: v } };
+    if (typeof v === "number")
+        return { key, value: Number.isInteger(v) ? { intValue: String(v) } : { doubleValue: v } };
+    return { key, value: { stringValue: typeof v === "string" ? v : JSON.stringify(v) } };
+}
+export function toOtelSpan(r) {
+    const endNs = BigInt(Date.parse(r.ts)) * 1000000n;
+    const durNs = BigInt(Math.round((r.outcome?.duration_ms ?? 0) * 1e6));
+    const isTool = r.type === "agent.tool_call";
+    const attributes = [
+        attr("gen_ai.operation.name", isTool ? "execute_tool" : r.type),
+        attr("gen_ai.tool.name", r.tool?.name),
+        attr("gen_ai.agent.id", r.agent?.id),
+        attr("gen_ai.agent.name", r.agent?.id),
+        attr("gen_ai.agent.version", r.agent?.version),
+        attr("mcp.server.url", r.tool?.server),
+        attr("enduser.id", r.principal?.sub),
+        attr("mandat.record.id", r.id),
+        attr("mandat.record.hash", r.hash),
+        attr("mandat.record.type", r.type),
+        attr("mandat.decision.effect", r.decision?.effect),
+        attr("mandat.decision.final", r.decision?.final),
+        attr("mandat.decision.rules", r.decision?.rules?.join(",")),
+        attr("mandat.decision.latency_us", r.decision?.latency_us),
+        attr("mandat.policy.version", r.decision?.policy_version),
+        attr("mandat.principal.tenant", r.principal?.tenant),
+        attr("mandat.actor_chain", r.actor_chain?.join(",")),
+        attr("mandat.task.id", r.task_id),
+        attr("mandat.token.jti", r.token_jti),
+        attr("mandat.tool.risk", r.tool?.risk),
+        attr("mandat.session.tainted", r.session?.tainted),
+        attr("mandat.approval.id", r.approval?.id),
+        attr("mandat.approval.status", r.approval?.status),
+        attr("mandat.prompt.hash", r.agent?.prompt_hash),
+    ].filter(Boolean);
+    return {
+        traceId: sha256(r.task_id ?? r.id).slice(0, 32),
+        spanId: sha256(r.id).slice(0, 16),
+        name: isTool ? `execute_tool ${r.tool?.name}` : r.type,
+        kind: isTool ? 3 /* CLIENT */ : 1 /* INTERNAL */,
+        startTimeUnixNano: String(endNs - durNs),
+        endTimeUnixNano: String(endNs),
+        attributes,
+        status: r.outcome?.status === "error" || r.decision?.final === "deny" ? { code: 2, message: r.outcome?.error ?? r.decision?.reasons?.join("; ") } : { code: 1 },
+    };
+}
+/** Off the critical path: `push` only enqueues; a timer flushes. Failed batches are re-queued with backoff. */
+export class OtlpExporter {
+    queue = [];
+    timer;
+    flushing = false;
+    failures = 0;
+    opts;
+    dropped = 0;
+    constructor(opts) {
+        this.opts = { serviceName: "mandat", batchSize: 200, flushIntervalMs: 1000, maxQueue: 50_000, headers: {}, ...opts };
+        this.timer = setInterval(() => void this.flush(), this.opts.flushIntervalMs);
+        this.timer.unref();
+    }
+    push(r) {
+        if (this.queue.length >= this.opts.maxQueue) {
+            this.queue.shift();
+            this.dropped++;
+        }
+        this.queue.push(r);
+    }
+    async flush() {
+        if (this.flushing || !this.queue.length)
+            return;
+        this.flushing = true;
+        try {
+            while (this.queue.length) {
+                const batch = this.queue.slice(0, this.opts.batchSize);
+                const body = {
+                    resourceSpans: [{
+                            resource: { attributes: [attr("service.name", this.opts.serviceName)] },
+                            scopeSpans: [{ scope: { name: "mandat", version: "0.1.0" }, spans: batch.map(toOtelSpan) }],
+                        }],
+                };
+                const res = await fetch(this.opts.endpoint.replace(/\/$/, "") + "/v1/traces", {
+                    method: "POST",
+                    headers: { "content-type": "application/json", ...this.opts.headers },
+                    body: JSON.stringify(body),
+                    signal: AbortSignal.timeout(5000),
+                });
+                if (!res.ok)
+                    throw new Error(`OTLP export failed: ${res.status}`);
+                this.queue.splice(0, batch.length);
+                this.failures = 0;
+            }
+        }
+        catch {
+            this.failures++;
+        }
+        finally {
+            this.flushing = false;
+        }
+    }
+    get backoffActive() { return this.failures > 0; }
+    async close() {
+        clearInterval(this.timer);
+        await this.flush();
+    }
+}

package/dist/ledger/ledger.d.ts

@@ -0,0 +1,117 @@
+import type { Effect, Obligation, Risk } from "../policy/engine.ts";
+export declare const GENESIS_HASH: string;
+export type RecordType = "agent.tool_call" | "approval.requested" | "approval.decided" | "token.issued" | "revocation.created" | "revocation.lifted" | "policy.changed" | "tool.drift" | "agent.registered" | "agent.updated";
+export interface ActionRecord {
+    id: string;
+    seq: number;
+    ts: string;
+    type: RecordType;
+    prev_hash: string;
+    hash: string;
+    /** Where the record was produced (guard instance / control plane). */
+    source?: string;
+    principal?: {
+        sub: string;
+        tenant?: string | null;
+        email?: string | null;
+    };
+    agent?: {
+        id: string;
+        version?: string | null;
+        prompt_hash?: string | null;
+    };
+    /** Outermost actor first: [current agent, delegating agent, ...]. The human is `principal`. */
+    actor_chain?: string[];
+    task_id?: string | null;
+    token_jti?: string | null;
+    session?: {
+        id?: string | null;
+        tainted?: boolean;
+        taint_sources?: string[];
+    };
+    tool?: {
+        name: string;
+        server?: string | null;
+        risk?: Risk | null;
+        definition_hash?: string | null;
+    };
+    args?: unknown;
+    decision?: {
+        effect: Effect;
+        final: "allow" | "deny" | "pending";
+        rules: string[];
+        reasons: string[];
+        obligations?: Obligation[];
+        policy_version?: string;
+        latency_us?: number;
+        mode?: "enforce" | "shadow";
+    };
+    approval?: {
+        id: string;
+        status: string;
+        approvers?: string[];
+        required?: number;
+        decided_at?: string | null;
+    };
+    outcome?: {
+        status: "success" | "error" | "blocked" | "pending";
+        error?: string;
+        duration_ms?: number;
+    };
+    tags?: string[];
+    /** Free-form details for non tool-call events (revocations, policy changes, drift). */
+    details?: Record<string, unknown>;
+}
+export type RecordInput = Omit<ActionRecord, "id" | "seq" | "ts" | "prev_hash" | "hash"> & {
+    ts?: string;
+    id?: string;
+};
+export interface LedgerSink {
+    append(rec: RecordInput): ActionRecord | void;
+    /** Deliver buffered records now (asynchronous sinks). */
+    flush?(): Promise<void>;
+    close?(): Promise<void> | void;
+}
+export declare function computeHash(rec: Omit<ActionRecord, "hash">): string;
+export declare class FileLedger implements LedgerSink {
+    readonly path: string;
+    private head;
+    private seq;
+    private listeners;
+    constructor(path: string);
+    get headHash(): string;
+    get length(): number;
+    append(input: RecordInput): ActionRecord;
+    onAppend(fn: (r: ActionRecord) => void): () => void;
+    read(): ActionRecord[];
+}
+/** In-memory sink, handy in tests. */
+export declare class MemoryLedger implements LedgerSink {
+    records: ActionRecord[];
+    append(input: RecordInput): ActionRecord;
+}
+export declare function readLedger(path: string): ActionRecord[];
+export interface VerifyResult {
+    ok: boolean;
+    count: number;
+    head: string;
+    first_ts?: string;
+    last_ts?: string;
+    broken_at?: number;
+    error?: string;
+}
+export declare function verifyRecords(records: Iterable<ActionRecord | string>): VerifyResult;
+export declare function verifyLedger(path: string): VerifyResult;
+export interface LedgerQuery {
+    type?: string;
+    agent?: string;
+    sub?: string;
+    tool?: string;
+    task?: string;
+    effect?: string;
+    since?: string;
+    until?: string;
+    limit?: number;
+    order?: "asc" | "desc";
+}
+export declare function queryRecords(records: ActionRecord[], q: LedgerQuery): ActionRecord[];

package/dist/ledger/ledger.js

@@ -0,0 +1,139 @@
+// Append-only, hash-chained audit ledger ("Action Records").
+//
+//   hash_n = sha256( hash_{n-1} || "\n" || canonical_json(record_n without `hash`) )
+//
+// Any edit, deletion or reordering of a past line breaks every later hash; `verifyLedger`
+// pinpoints the first broken record. One JSON object per line (JSONL).
+import { appendFileSync, closeSync, existsSync, fstatSync, mkdirSync, openSync, readFileSync, readSync } from "node:fs";
+import { dirname } from "node:path";
+import { canonicalJson, randomId, sha256 } from "../util.js";
+export const GENESIS_HASH = "0".repeat(64);
+export function computeHash(rec) {
+    return sha256(rec.prev_hash + "\n" + canonicalJson(rec));
+}
+export class FileLedger {
+    path;
+    head = GENESIS_HASH;
+    seq = 0;
+    listeners = new Set();
+    constructor(path) {
+        this.path = path;
+        mkdirSync(dirname(path), { recursive: true });
+        const last = readLastLine(path);
+        if (last) {
+            const rec = JSON.parse(last);
+            this.head = rec.hash;
+            this.seq = rec.seq;
+        }
+    }
+    get headHash() { return this.head; }
+    get length() { return this.seq; }
+    append(input) {
+        const base = { ...input, id: input.id ?? randomId("rec_"), seq: this.seq + 1, ts: input.ts ?? new Date().toISOString(), prev_hash: this.head };
+        const clean = JSON.parse(JSON.stringify(base)); // drop undefined
+        const rec = { ...clean, hash: computeHash(clean) };
+        appendFileSync(this.path, JSON.stringify(rec) + "\n");
+        this.head = rec.hash;
+        this.seq = rec.seq;
+        for (const l of this.listeners) {
+            try {
+                l(rec);
+            }
+            catch { /* listener errors never break the ledger */ }
+        }
+        return rec;
+    }
+    onAppend(fn) {
+        this.listeners.add(fn);
+        return () => this.listeners.delete(fn);
+    }
+    read() {
+        return readLedger(this.path);
+    }
+}
+/** In-memory sink, handy in tests. */
+export class MemoryLedger {
+    records = [];
+    append(input) {
+        const prev = this.records.at(-1);
+        const base = { ...input, id: input.id ?? randomId("rec_"), seq: (prev?.seq ?? 0) + 1, ts: input.ts ?? new Date().toISOString(), prev_hash: prev?.hash ?? GENESIS_HASH };
+        const clean = JSON.parse(JSON.stringify(base));
+        const rec = { ...clean, hash: computeHash(clean) };
+        this.records.push(rec);
+        return rec;
+    }
+}
+export function readLedger(path) {
+    if (!existsSync(path))
+        return [];
+    return readFileSync(path, "utf8").split("\n").filter(Boolean).map((l) => JSON.parse(l));
+}
+export function verifyRecords(records) {
+    let prev = GENESIS_HASH;
+    let count = 0;
+    let first_ts;
+    let last_ts;
+    for (const item of records) {
+        count++;
+        let rec;
+        try {
+            rec = typeof item === "string" ? JSON.parse(item) : item;
+        }
+        catch {
+            return { ok: false, count, head: prev, broken_at: count, error: `Line ${count} is not valid JSON` };
+        }
+        const { hash, ...rest } = rec;
+        if (rec.seq !== count)
+            return { ok: false, count, head: prev, broken_at: count, error: `Record ${count} has seq ${rec.seq} (records missing or reordered)` };
+        if (rec.prev_hash !== prev)
+            return { ok: false, count, head: prev, broken_at: count, error: `Record ${count} prev_hash does not match previous record (chain broken)` };
+        if (computeHash(rest) !== hash)
+            return { ok: false, count, head: prev, broken_at: count, error: `Record ${count} content does not match its hash (tampered)` };
+        prev = hash;
+        first_ts ??= rec.ts;
+        last_ts = rec.ts;
+    }
+    return { ok: true, count, head: prev, first_ts, last_ts };
+}
+export function verifyLedger(path) {
+    if (!existsSync(path))
+        return { ok: true, count: 0, head: GENESIS_HASH };
+    return verifyRecords(readFileSync(path, "utf8").split("\n").filter(Boolean));
+}
+export function queryRecords(records, q) {
+    let out = records.filter((r) => (!q.type || r.type === q.type || (q.type.endsWith("*") && r.type.startsWith(q.type.slice(0, -1)))) &&
+        (!q.agent || r.agent?.id === q.agent || r.actor_chain?.includes(q.agent)) &&
+        (!q.sub || r.principal?.sub === q.sub) &&
+        (!q.tool || r.tool?.name === q.tool) &&
+        (!q.task || r.task_id === q.task) &&
+        (!q.effect || r.decision?.effect === q.effect || r.decision?.final === q.effect) &&
+        (!q.since || r.ts >= q.since) &&
+        (!q.until || r.ts <= q.until));
+    if (q.order !== "asc")
+        out = out.reverse();
+    return q.limit ? out.slice(0, q.limit) : out;
+}
+function readLastLine(path) {
+    if (!existsSync(path))
+        return null;
+    const fd = openSync(path, "r");
+    try {
+        const size = fstatSync(fd).size;
+        if (size === 0)
+            return null;
+        let chunk = 64 * 1024;
+        for (;;) {
+            const start = Math.max(0, size - chunk);
+            const buf = Buffer.alloc(size - start);
+            readSync(fd, buf, 0, buf.length, start);
+            const text = buf.toString("utf8").replace(/\n+$/, "");
+            const idx = text.lastIndexOf("\n");
+            if (idx >= 0 || start === 0)
+                return text.slice(idx + 1) || null;
+            chunk *= 4;
+        }
+    }
+    finally {
+        closeSync(fd);
+    }
+}

package/dist/ledger/redact.d.ts

@@ -0,0 +1,13 @@
+export interface RedactionOptions {
+    /** Extra key names (case-insensitive substrings) whose values are always removed. */
+    keys?: string[];
+    /** Built-in string patterns to mask. Default: all. */
+    patterns?: Array<"email" | "card" | "phone" | "iban" | "jwt" | "secret">;
+    /** Explicit arg paths to replace with a hash ("customer.email"). */
+    fields?: string[];
+    /** Metadata-only mode: drop all values, keep keys + a hash per value. */
+    metadataOnly?: boolean;
+}
+export declare function hashValue(v: unknown): string;
+export declare function redactString(s: string, patterns: RedactionOptions["patterns"]): string;
+export declare function redact(value: unknown, opts?: RedactionOptions): unknown;

package/dist/ledger/redact.js

@@ -0,0 +1,73 @@
+// PII / secret redaction applied to tool arguments BEFORE they reach any log, ledger or approval message.
+import { sha256 } from "../util.js";
+// Substring match on key names, plus short names that only match exactly (so "pinned" stays visible).
+const SECRET_KEYS = ["password", "passwd", "secret", "token", "apikey", "api_key", "api-key", "authorization", "cookie", "private_key"];
+const SECRET_KEYS_EXACT = ["pin", "cvv", "cvc", "ssn"];
+const PATTERNS = {
+    jwt: { re: /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g, fn: () => "[JWT]" },
+    secret: { re: /\b(?:sk|pk|rk|xox[abpr]|ghp|gho|github_pat|AKIA)[-_A-Za-z0-9]{12,}\b/g, fn: () => "[SECRET]" },
+    email: { re: /\b([A-Za-z0-9._%+-])[A-Za-z0-9._%+-]*@([A-Za-z0-9.-]+\.[A-Za-z]{2,})\b/g, fn: (_, first, dom) => `${first}***@${dom}` },
+    iban: { re: /\b[A-Z]{2}\d{2}(?:\s?[A-Z0-9]{4}){2,7}(?:\s?[A-Z0-9]{1,4})?\b/g, fn: () => "[IBAN]" },
+    card: {
+        re: /\b(?:\d[ -]?){13,19}\b/g,
+        fn: (m) => {
+            const d = m.replace(/\D/g, "");
+            return luhn(d) ? `[CARD ****${d.slice(-4)}]` : m;
+        },
+    },
+    phone: { re: /(?<![\w.])\+\d[\d\s().-]{8,16}\d\b/g, fn: () => "[PHONE]" },
+};
+function luhn(d) {
+    if (d.length < 13 || d.length > 19)
+        return false;
+    let sum = 0;
+    for (let i = 0; i < d.length; i++) {
+        let n = Number(d[d.length - 1 - i]);
+        if (i % 2 === 1) {
+            n *= 2;
+            if (n > 9)
+                n -= 9;
+        }
+        sum += n;
+    }
+    return sum % 10 === 0;
+}
+export function hashValue(v) {
+    return "sha256:" + sha256(JSON.stringify(v) ?? "null").slice(0, 16);
+}
+export function redactString(s, patterns) {
+    let out = s;
+    for (const name of patterns ?? Object.keys(PATTERNS)) {
+        const p = PATTERNS[name];
+        out = out.replace(p.re, p.fn);
+    }
+    return out;
+}
+export function redact(value, opts = {}) {
+    const keys = [...SECRET_KEYS, ...(opts.keys ?? [])].map((k) => k.toLowerCase());
+    const fields = new Set(opts.fields ?? []);
+    const walk = (v, path, depth) => {
+        if (fields.has(path))
+            return `[REDACTED ${hashValue(v)}]`;
+        if (depth > 12)
+            return "[TRUNCATED]";
+        if (opts.metadataOnly && (v === null || typeof v !== "object"))
+            return v === null ? null : `[${typeof v} ${hashValue(v)}]`;
+        if (typeof v === "string")
+            return redactString(v.length > 4000 ? v.slice(0, 4000) + "…[truncated]" : v, opts.patterns);
+        if (Array.isArray(v))
+            return v.slice(0, 200).map((x, i) => walk(x, path ? `${path}.${i}` : String(i), depth + 1));
+        if (v && typeof v === "object") {
+            const out = {};
+            for (const [k, x] of Object.entries(v)) {
+                const p = path ? `${path}.${k}` : k;
+                const lk = k.toLowerCase();
+                const secret = keys.some((s) => lk.includes(s)) || SECRET_KEYS_EXACT.includes(lk);
+                out[k] = secret && !fields.has(p) ? "[REDACTED]" : walk(x, p, depth + 1);
+            }
+            return out;
+        }
+        return v;
+    };
+    return walk(value, "", 0);
+}