attenu-guard 0.1.0

package/dist/cjs/wire.js

@@ -0,0 +1,165 @@
+"use strict";
+/**
+ * wire.ts — the signing and verification backends.
+ *
+ * Anchors and delegation tokens are signed over canonical JSON bytes. Two
+ * backends ship, matching the Python library's `attenu_guard.wire`:
+ *
+ *   `HS256TestSigner`  stdlib HMAC-SHA256, for tests, examples and local dev;
+ *   `Ed25519Signer`    the production signer the Internet-Draft requires, with
+ *                      `Ed25519Verifier` for anyone holding only the public half.
+ *
+ * Everything here is built on Node's own `node:crypto`, so the package keeps
+ * zero runtime dependencies. Ed25519 keys are wrapped in the fixed DER prefixes
+ * below rather than pulled from a library.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Ed25519Verifier = exports.Ed25519Signer = exports.HS256TestSigner = void 0;
+const node_crypto_1 = require("node:crypto");
+/**
+ * stdlib HMAC-SHA256 signer — the default for tests, examples and local dev,
+ * because it needs no key management at all.
+ *
+ * NOT FOR PRODUCTION. HMAC is symmetric: `sign` and `verify` use the identical
+ * secret, so anyone able to verify a bundle is also able to forge one. That
+ * precludes the property the draft is built around — public offline
+ * verification at an untrusted enforcement point — because every verifier would
+ * have to hold the minting secret. Use `Ed25519Signer` in production; this
+ * class exists so the wire format and the interop fixtures can be exercised
+ * with no key distribution.
+ */
+class HS256TestSigner {
+    secret;
+    alg = "HS256";
+    kid;
+    constructor(secret, kid = "test") {
+        this.secret = secret;
+        this.kid = kid;
+    }
+    sign(signingInput) {
+        return (0, node_crypto_1.createHmac)("sha256", this.secret).update(signingInput).digest();
+    }
+    verify(signingInput, sig, _keyId) {
+        // `keyId` is accepted for parity with multi-key signers but not used for
+        // key selection: this signer holds exactly one secret. The comparison is
+        // constant-time to avoid a signature-forgery timing oracle.
+        const expected = this.sign(signingInput);
+        return expected.length === sig.length && (0, node_crypto_1.timingSafeEqual)(expected, sig);
+    }
+}
+exports.HS256TestSigner = HS256TestSigner;
+// Fixed DER wrappers for raw Ed25519 keys (RFC 8410). A raw 32-byte public key
+// becomes a SubjectPublicKeyInfo by prefixing the first; a raw 32-byte private
+// key becomes a PKCS#8 PrivateKeyInfo by prefixing the second.
+const ED25519_SPKI_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
+const ED25519_PKCS8_PREFIX = Buffer.from("302e020100300506032b657004220420", "hex");
+function publicKeyFromRaw(raw) {
+    if (raw.length !== 32) {
+        throw new Error(`an Ed25519 public key is 32 bytes, got ${raw.length}`);
+    }
+    return (0, node_crypto_1.createPublicKey)({
+        key: Buffer.concat([ED25519_SPKI_PREFIX, raw]),
+        format: "der",
+        type: "spki",
+    });
+}
+function privateKeyFromRaw(raw) {
+    if (raw.length !== 32) {
+        throw new Error(`an Ed25519 private key is 32 bytes, got ${raw.length}`);
+    }
+    return (0, node_crypto_1.createPrivateKey)({
+        key: Buffer.concat([ED25519_PKCS8_PREFIX, raw]),
+        format: "der",
+        type: "pkcs8",
+    });
+}
+function rawPublicBytes(key) {
+    const der = key.export({ format: "der", type: "spki" });
+    return Buffer.from(der.subarray(der.length - 32));
+}
+function rawPrivateBytes(key) {
+    const der = key.export({ format: "der", type: "pkcs8" });
+    return Buffer.from(der.subarray(der.length - 32));
+}
+/**
+ * The production signer the draft requires ("Implementations MUST support
+ * Ed25519"); JOSE alg "EdDSA". Public-key, so — unlike `HS256TestSigner` — a
+ * verifier never needs the signing secret, which is exactly what offline
+ * verification at an untrusted edge depends on.
+ */
+class Ed25519Signer {
+    alg = "EdDSA";
+    kid;
+    privateKey;
+    publicKey;
+    constructor(privateKey, kid = "ed25519-1") {
+        if (privateKey === undefined) {
+            const pair = (0, node_crypto_1.generateKeyPairSync)("ed25519");
+            this.privateKey = pair.privateKey;
+            this.publicKey = pair.publicKey;
+        }
+        else {
+            this.privateKey = privateKey;
+            this.publicKey = (0, node_crypto_1.createPublicKey)(privateKey);
+        }
+        this.kid = kid;
+    }
+    /** A signer wrapping a freshly generated keypair. */
+    static generate(kid = "ed25519-1") {
+        return new Ed25519Signer(undefined, kid);
+    }
+    /** Rebuild a signer from the 32 raw bytes `privateBytesRaw` produced. */
+    static fromPrivateBytes(raw, kid = "ed25519-1") {
+        return new Ed25519Signer(privateKeyFromRaw(raw), kid);
+    }
+    sign(signingInput) {
+        return (0, node_crypto_1.sign)(null, signingInput, this.privateKey);
+    }
+    verify(signingInput, sig, _keyId) {
+        try {
+            return (0, node_crypto_1.verify)(null, signingInput, this.publicKey, sig);
+        }
+        catch {
+            return false;
+        }
+    }
+    /** The 32-byte raw public key — a trust anchor to distribute out of band. */
+    publicBytesRaw() {
+        return rawPublicBytes(this.publicKey);
+    }
+    /** The 32-byte raw private key — what a key FILE stores, never a repo. */
+    privateBytesRaw() {
+        return rawPrivateBytes(this.privateKey);
+    }
+}
+exports.Ed25519Signer = Ed25519Signer;
+/**
+ * The public-key-only counterpart of `Ed25519Signer` — what a console, an
+ * auditor or an ingest server holds. It verifies anchors signed by the matching
+ * private key and can never sign: `sign` throws.
+ */
+class Ed25519Verifier {
+    alg = "EdDSA";
+    kid;
+    publicKey;
+    constructor(publicBytesRaw, kid = "ed25519-1") {
+        this.publicKey = publicKeyFromRaw(publicBytesRaw);
+        this.kid = kid;
+    }
+    sign(_signingInput) {
+        throw new Error("Ed25519Verifier holds no private key and cannot sign");
+    }
+    verify(signingInput, sig, _keyId) {
+        try {
+            return (0, node_crypto_1.verify)(null, signingInput, this.publicKey, sig);
+        }
+        catch {
+            return false;
+        }
+    }
+    publicBytesRaw() {
+        return rawPublicBytes(this.publicKey);
+    }
+}
+exports.Ed25519Verifier = Ed25519Verifier;
+//# sourceMappingURL=wire.js.map

package/dist/cjs/wire.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire.js","sourceRoot":"","sources":["../../src/wire.ts"],"names":[],"mappings":"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"}

package/dist/esm/adapters/langgraph.d.ts

@@ -0,0 +1,174 @@
+/**
+ * adapters/langgraph.ts — a thin LangGraph.js integration.
+ *
+ * The adapter is built in two layers, the same shape as the Python one:
+ *
+ *   1. The AUTHORIZATION-WRAPPING LOGIC is plain TypeScript. It wraps an
+ *      arbitrary callable so that every call is authorized through a `Guard`
+ *      first, and it does not import, require or reference `@langchain/langgraph`
+ *      at all. That is deliberate: a LangGraph node is, by LangGraph's own
+ *      convention, just a callable — `(state) => partialState` — so wrapping
+ *      "any callable" is enough to wrap a node or a plain tool function alike,
+ *      and it keeps the logic testable with no framework installed.
+ *
+ *   2. The one spot that touches the package itself (`isLangGraphAvailable`)
+ *      imports it lazily. `addGuardedNode` takes an already-constructed graph
+ *      and only calls `.addNode(name, callable)` on it, so it needs no import
+ *      either.
+ *
+ * ## Which hook this uses, and why
+ *
+ * The Python adapter wraps node callables. LangGraph.js has no public
+ * before-tool-call hook: `ToolNode` resolves the tool itself and invokes it at
+ * `dist/prebuilt/tool_node.js:207` (`const output = await tool.invoke(toolCall,
+ * runtime)`), inside a `protected runTool`. So this adapter takes the
+ * TOOL-WRAPPING form: `guardTool` returns a stand-in for a tool object whose
+ * `invoke` authorizes first and calls through only on an allow. The stand-in
+ * keeps the original `name`, `description` and `schema`, which is all `ToolNode`
+ * looks at when it matches a tool call to a tool, so a wrapped tool drops
+ * straight into `new ToolNode([...])` or `createReactAgent({tools})`.
+ *
+ * A denial throws `AuthorityDenied` — the same error `Guard.enforce` throws —
+ * BEFORE the tool body runs, so a poisoned instruction or a runaway plan never
+ * reaches the call it is not authorized to make. A graph can catch it around
+ * `graph.invoke(...)`, or route around it with LangGraph's own error handling;
+ * this adapter does not prescribe which. It guarantees only that the tool body
+ * never executes on a denial.
+ *
+ * ## Delegation
+ *
+ * Handing work to a sub-agent is the delegation moment. `delegateTo` mints the
+ * child `Guard` at the handoff — before the sub-agent's graph is invoked — so
+ * the sub-agent's tools are guarded by an authority that is provably a subset of
+ * the parent's.
+ *
+ *     const researcher = delegateTo(supervisor, {
+ *       agentId: "researcher",
+ *       request: new Authority({ scopes: ["crm.read"], ceilings: [new RowLimit(500)], ttl: 900 }),
+ *       task: "summarise the Q3 pipeline",
+ *     });
+ *     const tools = guardTools(researcher, [crmQuery], { scopes: { crm_query: "crm.read" } });
+ */
+import { type Guard } from "../guard.js";
+import type { Authority } from "../authority.js";
+import type { Context } from "../ceilings.js";
+import type { Decision } from "../reasons.js";
+/** Options shared by every guarded wrapper. */
+export interface GuardOptions {
+    /**
+     * Called with the exact arguments the wrapped callable received; returns the
+     * context for `guard.check`, e.g. `{rows: 5000, egress: "none"}`. Omitted
+     * means an empty context — fine for a scope-only check.
+     */
+    contextFn?: (...args: any[]) => Context;
+    /** The `tool` label recorded on the ledger. Defaults to the callable's name. */
+    tool?: string | null;
+    /** What the caller knows about why this scope would be absent. */
+    disposition?: string | null;
+    /** Marks the call as consuming a metered resource. */
+    metered?: boolean;
+}
+/** A callable node, with the guard and scope it was wrapped with attached. */
+export type GuardedNode<F extends (...args: any[]) => any> = F & {
+    readonly guard: Guard;
+    readonly toolScope: string;
+    readonly unwrapped: F;
+};
+/**
+ * Wrap a callable so every call is authorized through `guard` first.
+ *
+ * On call: the context is `contextFn(...args)` if given, else `{}`; then
+ * `guard.check(toolScope, {context, tool})`. On a denial this throws
+ * `AuthorityDenied` and the wrapped callable is NEVER invoked. Otherwise it
+ * calls through with the original arguments and returns the result unchanged —
+ * including a promise, which is passed along untouched.
+ *
+ * Use the Guard for the SPECIFIC agent this callable belongs to, not the
+ * orchestrator's broader one, so a denial reflects that node's real, narrowed
+ * authority.
+ */
+export declare function guardNode<F extends (...args: any[]) => any>(guard: Guard, toolScope: string, fn: F, options?: GuardOptions): GuardedNode<F>;
+/** The minimum a LangGraph.js graph needs to expose for `addGuardedNode`. */
+export interface GraphLike {
+    addNode(name: string, action: (...args: any[]) => any, ...rest: any[]): unknown;
+}
+/**
+ * Build the guarded wrapper and register it on a graph in one call.
+ *
+ * `graph` is structurally typed: it only needs `.addNode(name, callable)`,
+ * which is `StateGraph`'s real signature — so this helper needs no import of
+ * its own and stays testable against a plain stand-in graph.
+ */
+export declare function addGuardedNode<F extends (...args: any[]) => any>(graph: GraphLike, name: string, guard: Guard, toolScope: string, fn: F, options?: GuardOptions): GuardedNode<F>;
+/** The shape `ToolNode` requires of a tool: a name and an `invoke`. */
+export interface ToolLike {
+    name: string;
+    invoke(input: any, config?: any): any;
+    [key: string]: any;
+}
+export interface GuardToolOptions extends GuardOptions {
+    /** The scope this tool needs. Defaults to the tool's own name. */
+    scope?: string;
+    /**
+     * Called when the guard denies the call, instead of throwing. Return the
+     * value the tool should yield — e.g. a `ToolMessage` explaining the refusal,
+     * so the model can see the denial and re-plan rather than the run aborting.
+     */
+    onDenied?: (decision: Decision, input: any) => any;
+}
+/**
+ * Return a stand-in for `tool` whose `invoke` authorizes through `guard` before
+ * the tool body runs. Everything else — `name`, `description`, `schema`, any
+ * LangChain internals — is forwarded to the original, so `ToolNode` matches and
+ * runs it exactly as it would the unwrapped tool.
+ *
+ * The context function receives the raw invoke arguments. `ToolNode` passes a
+ * tool call object, so the arguments the model proposed are at `input.args`;
+ * a direct `tool.invoke({...})` passes them at the top level. `toolArgs` below
+ * reads either shape.
+ */
+export declare function guardTool<T extends ToolLike>(guard: Guard, tool: T, options?: GuardToolOptions): T;
+/** Marker properties, so a caller can tell a guarded tool from a bare one. */
+export declare const ATTENU_GUARD = "__attenuGuard";
+export declare const ATTENU_SCOPE = "__attenuScope";
+export interface GuardToolsOptions extends GuardOptions {
+    /** Tool name -> scope. A tool absent from the map uses its own name. */
+    scopes?: Record<string, string>;
+    /** Tool name -> context function, overriding the shared `contextFn`. */
+    contexts?: Record<string, (input: any, config?: any) => Context>;
+    onDenied?: (decision: Decision, input: any) => any;
+}
+/**
+ * Guard a whole tool list in one call — what you hand to `new ToolNode([...])`
+ * or `createReactAgent({tools})`.
+ */
+export declare function guardTools<T extends ToolLike>(guard: Guard, tools: readonly T[], options?: GuardToolsOptions): T[];
+/**
+ * The arguments a tool call carries, whichever shape `invoke` was handed.
+ * `ToolNode` passes `{name, args, id, type}`; a direct call passes the args
+ * themselves. Useful inside a `contextFn`.
+ */
+export declare function toolArgs(input: any): Record<string, any>;
+export interface DelegateOptions {
+    agentId: string;
+    request: Authority;
+    task: string;
+}
+/**
+ * Mint the child Guard for a sub-agent handoff. Handing work to a sub-agent IS
+ * the delegation moment: call this before the sub-agent's graph is invoked, so
+ * its tools are guarded by an authority that is provably a subset of the
+ * parent's. A request wider than the parent holds comes back narrowed.
+ *
+ * Throws `AuthorityError` if the handoff is structurally refused — the parent
+ * is revoked or expired, the agent is banned, or the chain's depth or fanout
+ * ceiling would be exceeded.
+ */
+export declare function delegateTo(parent: Guard, options: DelegateOptions): Guard;
+/**
+ * True iff `@langchain/langgraph` is importable here. The import is lazy and
+ * happens only when this is called, so merely importing this adapter — or using
+ * `guardNode` / `guardTool` — never requires LangGraph to be installed.
+ */
+export declare function isLangGraphAvailable(): Promise<boolean>;
+//# sourceMappingURL=langgraph.d.ts.map

package/dist/esm/adapters/langgraph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"langgraph.d.ts","sourceRoot":"","sources":["../../../src/adapters/langgraph.ts"],"names":[],"mappings":"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"}

package/dist/esm/adapters/langgraph.js

@@ -0,0 +1,199 @@
+/**
+ * adapters/langgraph.ts — a thin LangGraph.js integration.
+ *
+ * The adapter is built in two layers, the same shape as the Python one:
+ *
+ *   1. The AUTHORIZATION-WRAPPING LOGIC is plain TypeScript. It wraps an
+ *      arbitrary callable so that every call is authorized through a `Guard`
+ *      first, and it does not import, require or reference `@langchain/langgraph`
+ *      at all. That is deliberate: a LangGraph node is, by LangGraph's own
+ *      convention, just a callable — `(state) => partialState` — so wrapping
+ *      "any callable" is enough to wrap a node or a plain tool function alike,
+ *      and it keeps the logic testable with no framework installed.
+ *
+ *   2. The one spot that touches the package itself (`isLangGraphAvailable`)
+ *      imports it lazily. `addGuardedNode` takes an already-constructed graph
+ *      and only calls `.addNode(name, callable)` on it, so it needs no import
+ *      either.
+ *
+ * ## Which hook this uses, and why
+ *
+ * The Python adapter wraps node callables. LangGraph.js has no public
+ * before-tool-call hook: `ToolNode` resolves the tool itself and invokes it at
+ * `dist/prebuilt/tool_node.js:207` (`const output = await tool.invoke(toolCall,
+ * runtime)`), inside a `protected runTool`. So this adapter takes the
+ * TOOL-WRAPPING form: `guardTool` returns a stand-in for a tool object whose
+ * `invoke` authorizes first and calls through only on an allow. The stand-in
+ * keeps the original `name`, `description` and `schema`, which is all `ToolNode`
+ * looks at when it matches a tool call to a tool, so a wrapped tool drops
+ * straight into `new ToolNode([...])` or `createReactAgent({tools})`.
+ *
+ * A denial throws `AuthorityDenied` — the same error `Guard.enforce` throws —
+ * BEFORE the tool body runs, so a poisoned instruction or a runaway plan never
+ * reaches the call it is not authorized to make. A graph can catch it around
+ * `graph.invoke(...)`, or route around it with LangGraph's own error handling;
+ * this adapter does not prescribe which. It guarantees only that the tool body
+ * never executes on a denial.
+ *
+ * ## Delegation
+ *
+ * Handing work to a sub-agent is the delegation moment. `delegateTo` mints the
+ * child `Guard` at the handoff — before the sub-agent's graph is invoked — so
+ * the sub-agent's tools are guarded by an authority that is provably a subset of
+ * the parent's.
+ *
+ *     const researcher = delegateTo(supervisor, {
+ *       agentId: "researcher",
+ *       request: new Authority({ scopes: ["crm.read"], ceilings: [new RowLimit(500)], ttl: 900 }),
+ *       task: "summarise the Q3 pipeline",
+ *     });
+ *     const tools = guardTools(researcher, [crmQuery], { scopes: { crm_query: "crm.read" } });
+ */
+import { AuthorityDenied } from "../guard.js";
+/**
+ * Wrap a callable so every call is authorized through `guard` first.
+ *
+ * On call: the context is `contextFn(...args)` if given, else `{}`; then
+ * `guard.check(toolScope, {context, tool})`. On a denial this throws
+ * `AuthorityDenied` and the wrapped callable is NEVER invoked. Otherwise it
+ * calls through with the original arguments and returns the result unchanged —
+ * including a promise, which is passed along untouched.
+ *
+ * Use the Guard for the SPECIFIC agent this callable belongs to, not the
+ * orchestrator's broader one, so a denial reflects that node's real, narrowed
+ * authority.
+ */
+export function guardNode(guard, toolScope, fn, options = {}) {
+    const resolvedTool = options.tool !== undefined ? options.tool : (fn.name || null);
+    const wrapped = function (...args) {
+        const context = options.contextFn ? options.contextFn(...args) : {};
+        const decision = guard.check(toolScope, {
+            context,
+            tool: resolvedTool,
+            disposition: options.disposition ?? null,
+            metered: options.metered ?? false,
+        });
+        if (!decision.allowed)
+            throw new AuthorityDenied(decision);
+        return fn.apply(this, args);
+    };
+    Object.defineProperties(wrapped, {
+        name: { value: fn.name, configurable: true },
+        guard: { value: guard, enumerable: true },
+        toolScope: { value: toolScope, enumerable: true },
+        unwrapped: { value: fn, enumerable: true },
+    });
+    return wrapped;
+}
+/**
+ * Build the guarded wrapper and register it on a graph in one call.
+ *
+ * `graph` is structurally typed: it only needs `.addNode(name, callable)`,
+ * which is `StateGraph`'s real signature — so this helper needs no import of
+ * its own and stays testable against a plain stand-in graph.
+ */
+export function addGuardedNode(graph, name, guard, toolScope, fn, options = {}) {
+    const node = guardNode(guard, toolScope, fn, options);
+    graph.addNode(name, node);
+    return node;
+}
+/**
+ * Return a stand-in for `tool` whose `invoke` authorizes through `guard` before
+ * the tool body runs. Everything else — `name`, `description`, `schema`, any
+ * LangChain internals — is forwarded to the original, so `ToolNode` matches and
+ * runs it exactly as it would the unwrapped tool.
+ *
+ * The context function receives the raw invoke arguments. `ToolNode` passes a
+ * tool call object, so the arguments the model proposed are at `input.args`;
+ * a direct `tool.invoke({...})` passes them at the top level. `toolArgs` below
+ * reads either shape.
+ */
+export function guardTool(guard, tool, options = {}) {
+    const scope = options.scope ?? tool.name;
+    const label = options.tool !== undefined ? options.tool : tool.name;
+    const guardedInvoke = (input, config) => {
+        const context = options.contextFn ? options.contextFn(input, config) : {};
+        const decision = guard.check(scope, {
+            context,
+            tool: label,
+            disposition: options.disposition ?? null,
+            metered: options.metered ?? false,
+        });
+        if (!decision.allowed) {
+            if (options.onDenied)
+                return options.onDenied(decision, input);
+            throw new AuthorityDenied(decision);
+        }
+        return tool.invoke(input, config);
+    };
+    return new Proxy(tool, {
+        get(target, prop, receiver) {
+            if (prop === "invoke")
+                return guardedInvoke;
+            if (prop === ATTENU_GUARD)
+                return guard;
+            if (prop === ATTENU_SCOPE)
+                return scope;
+            const value = Reflect.get(target, prop, receiver);
+            return typeof value === "function" ? value.bind(target) : value;
+        },
+    });
+}
+/** Marker properties, so a caller can tell a guarded tool from a bare one. */
+export const ATTENU_GUARD = "__attenuGuard";
+export const ATTENU_SCOPE = "__attenuScope";
+/**
+ * Guard a whole tool list in one call — what you hand to `new ToolNode([...])`
+ * or `createReactAgent({tools})`.
+ */
+export function guardTools(guard, tools, options = {}) {
+    return tools.map((t) => guardTool(guard, t, {
+        scope: options.scopes?.[t.name] ?? t.name,
+        contextFn: options.contexts?.[t.name] ?? options.contextFn,
+        disposition: options.disposition ?? null,
+        metered: options.metered ?? false,
+        onDenied: options.onDenied,
+    }));
+}
+/**
+ * The arguments a tool call carries, whichever shape `invoke` was handed.
+ * `ToolNode` passes `{name, args, id, type}`; a direct call passes the args
+ * themselves. Useful inside a `contextFn`.
+ */
+export function toolArgs(input) {
+    if (input !== null && typeof input === "object" && "args" in input && !Array.isArray(input)) {
+        const args = input.args;
+        if (args !== null && typeof args === "object")
+            return args;
+    }
+    return (input ?? {});
+}
+/**
+ * Mint the child Guard for a sub-agent handoff. Handing work to a sub-agent IS
+ * the delegation moment: call this before the sub-agent's graph is invoked, so
+ * its tools are guarded by an authority that is provably a subset of the
+ * parent's. A request wider than the parent holds comes back narrowed.
+ *
+ * Throws `AuthorityError` if the handoff is structurally refused — the parent
+ * is revoked or expired, the agent is banned, or the chain's depth or fanout
+ * ceiling would be exceeded.
+ */
+export function delegateTo(parent, options) {
+    return parent.delegate(options.agentId, options.request, options.task);
+}
+/**
+ * True iff `@langchain/langgraph` is importable here. The import is lazy and
+ * happens only when this is called, so merely importing this adapter — or using
+ * `guardNode` / `guardTool` — never requires LangGraph to be installed.
+ */
+export async function isLangGraphAvailable() {
+    const specifier = "@langchain/langgraph";
+    try {
+        await import(specifier);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=langgraph.js.map

package/dist/esm/adapters/langgraph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"langgraph.js","sourceRoot":"","sources":["../../../src/adapters/langgraph.ts"],"names":[],"mappings":"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"}

package/dist/esm/audit.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Hash-chained audit log — the open, verifiable record of every authority decision.
+ *
+ * Each event is appended as one JSON line whose `hash` covers the event plus the
+ * previous line's hash. Any insertion, deletion or reordering breaks the chain
+ * and is detectable offline by anyone, with no vendor in the loop.
+ *
+ * The schema is versioned and published as `schema/agent-audit.schema.json` in
+ * the Python distribution, so other tools (SIEMs, observability) can ingest it.
+ * The hashes computed here are byte-identical to the Python library's for
+ * identical content — see `canonical.ts` for how that is guaranteed.
+ */
+import { type CJson } from "./canonical.js";
+import type { Signer } from "./wire.js";
+export declare const SCHEMA_VERSION = 1;
+export declare const GENESIS: string;
+/** One line of the ledger. */
+export type LedgerEntry = Record<string, CJson>;
+/** A local destination that receives every entry after the file write. */
+export interface Sink {
+    write(entry: LedgerEntry): void;
+}
+/** A signed external commitment to a chain head. */
+export interface Anchor {
+    v: number;
+    chain_id: string;
+    seq: number;
+    head: string;
+    ts: number | string;
+    kid: string | null;
+    sig: string;
+    /** Set by `exportBundle`; not part of the signed body. */
+    verified?: boolean;
+    [key: string]: CJson | undefined;
+}
+/** `sha256(prev_hash || canonical(event-without-hash))`, as hex. */
+export declare function hashEntry(prevHash: string, payload: LedgerEntry): string;
+export interface AuditLogInit {
+    /** Where to append the `.jsonl` ledger. Omit for an in-memory log. */
+    path?: string | null;
+    /** Local sinks; each gets every entry after the file write. */
+    sinks?: readonly Sink[];
+}
+/** Append-only, hash-chained decision log. */
+export declare class AuditLog {
+    readonly path: string | null;
+    private readonly sinks;
+    private prev;
+    private seq;
+    private readonly _entries;
+    /**
+     * Timestamps are injected by the caller (the `Guard` uses a monotonic
+     * counter) so the log stays deterministic in tests and reproducible in
+     * replay. In production the runtime supplies a trusted timestamp.
+     */
+    constructor(init?: AuditLogInit | string | null);
+    append(event: string, ts: number | string, fields?: LedgerEntry): LedgerEntry;
+    get entries(): LedgerEntry[];
+    get length(): number;
+    [Symbol.iterator](): Iterator<LedgerEntry>;
+    /** `[seq, hash]` of the last entry — the chain head; `[-1, GENESIS]` if empty. */
+    head(): [number, string];
+    private chainIdHint;
+    /**
+     * A signed external COMMITMENT to the chain head. Publish it out of band; a
+     * later `verifyAnchor` then catches a log that was fully rewritten and
+     * re-hashed, which plain `verify` cannot — a consistent rewrite reproduces
+     * its own hashes. The signed head hash is the fixed point.
+     */
+    anchor(signer: Signer, ts?: number | string): Anchor;
+    /** The chain reproduces AND its head matches a SIGNED anchor. */
+    static verifyAnchor(entries: readonly LedgerEntry[], anchor: Record<string, CJson> | null | undefined, signer: Signer): [boolean, string | null];
+    /** Recompute the chain. Returns `[ok, firstBadReason]`. */
+    static verify(entries: readonly LedgerEntry[]): [boolean, string | null];
+    /** Read a `.jsonl` ledger, keeping every number's original literal. */
+    static load(path: string): LedgerEntry[];
+    /** Parse `.jsonl` text into entries. Blank lines are skipped. */
+    static parseLines(text: string): LedgerEntry[];
+}
+/** The first `chain_id` any entry carries, or `"chain"`. */
+export declare function chainIdOf(entries: readonly LedgerEntry[]): string;
+//# sourceMappingURL=audit.d.ts.map

package/dist/esm/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../src/audit.ts"],"names":[],"mappings":"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"}