attenu-guard 0.1.0

package/dist/cjs/adapters/langgraph.js

@@ -0,0 +1,242 @@
+"use strict";
+/**
+ * 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" } });
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ATTENU_SCOPE = exports.ATTENU_GUARD = void 0;
+exports.guardNode = guardNode;
+exports.addGuardedNode = addGuardedNode;
+exports.guardTool = guardTool;
+exports.guardTools = guardTools;
+exports.toolArgs = toolArgs;
+exports.delegateTo = delegateTo;
+exports.isLangGraphAvailable = isLangGraphAvailable;
+const guard_js_1 = require("../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.
+ */
+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 guard_js_1.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.
+ */
+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.
+ */
+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 guard_js_1.AuthorityDenied(decision);
+        }
+        return tool.invoke(input, config);
+    };
+    return new Proxy(tool, {
+        get(target, prop, receiver) {
+            if (prop === "invoke")
+                return guardedInvoke;
+            if (prop === exports.ATTENU_GUARD)
+                return guard;
+            if (prop === exports.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. */
+exports.ATTENU_GUARD = "__attenuGuard";
+exports.ATTENU_SCOPE = "__attenuScope";
+/**
+ * Guard a whole tool list in one call — what you hand to `new ToolNode([...])`
+ * or `createReactAgent({tools})`.
+ */
+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`.
+ */
+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.
+ */
+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.
+ */
+async function isLangGraphAvailable() {
+    const specifier = "@langchain/langgraph";
+    try {
+        await Promise.resolve(`${specifier}`).then(s => __importStar(require(s)));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=langgraph.js.map

package/dist/cjs/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/cjs/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/cjs/audit.d.ts.map

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

package/dist/cjs/audit.js

@@ -0,0 +1,195 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuditLog = exports.GENESIS = exports.SCHEMA_VERSION = void 0;
+exports.hashEntry = hashEntry;
+exports.chainIdOf = chainIdOf;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const canonical_js_1 = require("./canonical.js");
+exports.SCHEMA_VERSION = 1;
+exports.GENESIS = "0".repeat(64);
+/** `sha256(prev_hash || canonical(event-without-hash))`, as hex. */
+function hashEntry(prevHash, payload) {
+    const h = (0, node_crypto_1.createHash)("sha256");
+    h.update(Buffer.from(prevHash, "utf8"));
+    h.update((0, canonical_js_1.canonicalBytes)(payload));
+    return h.digest("hex");
+}
+function asNumber(value) {
+    const plain = (0, canonical_js_1.toPlain)(value);
+    return typeof plain === "number" ? plain : undefined;
+}
+function withoutHash(entry) {
+    const out = {};
+    for (const [k, v] of Object.entries(entry)) {
+        if (k !== "hash")
+            out[k] = v;
+    }
+    return out;
+}
+/** Append-only, hash-chained decision log. */
+class AuditLog {
+    path;
+    sinks;
+    prev = exports.GENESIS;
+    seq = 0;
+    _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 = {}) {
+        const opts = typeof init === "string" || init === null ? { path: init } : init;
+        this.path = opts.path ?? null;
+        this.sinks = opts.sinks ?? [];
+        if (this.path) {
+            (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(this.path), { recursive: true });
+            (0, node_fs_1.writeFileSync)(this.path, ""); // fresh log
+        }
+    }
+    append(event, ts, fields = {}) {
+        const payload = {
+            v: exports.SCHEMA_VERSION,
+            seq: this.seq,
+            ts,
+            event,
+            ...fields,
+            prev_hash: this.prev,
+        };
+        payload["hash"] = hashEntry(this.prev, payload);
+        this.prev = payload["hash"];
+        this.seq += 1;
+        this._entries.push(payload);
+        if (this.path) {
+            // Python writes the ledger with `json.dumps(payload, sort_keys=True)` —
+            // its DEFAULT separators, not the compact pair the hash is taken over.
+            (0, node_fs_1.appendFileSync)(this.path, (0, canonical_js_1.pyJsonDumps)(payload) + "\n");
+        }
+        for (const sink of this.sinks)
+            sink.write(payload);
+        return payload;
+    }
+    get entries() {
+        return this._entries.slice();
+    }
+    get length() {
+        return this._entries.length;
+    }
+    [Symbol.iterator]() {
+        return this.entries[Symbol.iterator]();
+    }
+    // ---- verification -----------------------------------------------------
+    /** `[seq, hash]` of the last entry — the chain head; `[-1, GENESIS]` if empty. */
+    head() {
+        if (this._entries.length === 0)
+            return [-1, exports.GENESIS];
+        const last = this._entries[this._entries.length - 1];
+        return [asNumber(last["seq"]), last["hash"]];
+    }
+    chainIdHint() {
+        return chainIdOf(this._entries);
+    }
+    /**
+     * 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, ts = 0) {
+        const [seq, head] = this.head();
+        const body = { v: exports.SCHEMA_VERSION, chain_id: this.chainIdHint(), seq, head, ts };
+        return {
+            ...body,
+            kid: signer.kid ?? null,
+            sig: signer.sign((0, canonical_js_1.canonicalBytes)(body)).toString("hex"),
+        };
+    }
+    /** The chain reproduces AND its head matches a SIGNED anchor. */
+    static verifyAnchor(entries, anchor, signer) {
+        const a = anchor ?? {};
+        const body = {};
+        for (const k of ["v", "chain_id", "seq", "head", "ts"])
+            body[k] = a[k] ?? null;
+        const sigHex = (0, canonical_js_1.toPlain)(a["sig"]) ?? "";
+        if (typeof sigHex !== "string" || !/^(?:[0-9a-fA-F]{2})*$/.test(sigHex)) {
+            return [false, "anchor signature not hex"];
+        }
+        const sig = Buffer.from(sigHex, "hex");
+        const kid = (0, canonical_js_1.toPlain)(a["kid"]);
+        if (!signer.verify((0, canonical_js_1.canonicalBytes)(body), sig, kid)) {
+            return [false, "anchor signature invalid"];
+        }
+        const [ok, err] = AuditLog.verify(entries);
+        if (!ok)
+            return [false, err];
+        if (entries.length === 0)
+            return [asNumber(a["seq"]) === -1, null];
+        const last = entries[entries.length - 1];
+        if (last["hash"] !== (0, canonical_js_1.toPlain)(a["head"]) || asNumber(last["seq"]) !== asNumber(a["seq"])) {
+            return [false, "anchor head does not match the ledger head (ledger rewritten?)"];
+        }
+        return [true, null];
+    }
+    /** Recompute the chain. Returns `[ok, firstBadReason]`. */
+    static verify(entries) {
+        let prev = exports.GENESIS;
+        let expectedSeq = 0;
+        for (const e of entries) {
+            const seq = asNumber(e["seq"]);
+            if (seq !== expectedSeq) {
+                return [false, `seq gap at ${expectedSeq} (got ${formatSeq(e["seq"])})`];
+            }
+            const stored = e["hash"];
+            const payload = withoutHash(e);
+            if ((0, canonical_js_1.toPlain)(payload["prev_hash"]) !== prev) {
+                return [false, `prev_hash mismatch at seq ${expectedSeq}`];
+            }
+            if (hashEntry(prev, payload) !== stored) {
+                return [false, `hash mismatch at seq ${expectedSeq}`];
+            }
+            prev = stored;
+            expectedSeq += 1;
+        }
+        return [true, null];
+    }
+    /** Read a `.jsonl` ledger, keeping every number's original literal. */
+    static load(path) {
+        return AuditLog.parseLines((0, node_fs_1.readFileSync)(path, "utf8"));
+    }
+    /** Parse `.jsonl` text into entries. Blank lines are skipped. */
+    static parseLines(text) {
+        return text
+            .split(/\r?\n/)
+            .filter((line) => line.trim() !== "")
+            .map((line) => (0, canonical_js_1.parseJson)(line));
+    }
+}
+exports.AuditLog = AuditLog;
+function formatSeq(value) {
+    const plain = (0, canonical_js_1.toPlain)(value);
+    return plain === undefined || plain === null ? "None" : String(plain);
+}
+/** The first `chain_id` any entry carries, or `"chain"`. */
+function chainIdOf(entries) {
+    for (const e of entries) {
+        const id = (0, canonical_js_1.toPlain)(e["chain_id"]);
+        if (typeof id === "string" && id)
+            return id;
+    }
+    return "chain";
+}
+//# sourceMappingURL=audit.js.map

package/dist/cjs/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../../src/audit.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;;AAyCH,8BAKC;AAmLD,8BAMC;AArOD,6CAAyC;AACzC,qCAAiF;AACjF,yCAAoC;AAEpC,iDAMwB;AAGX,QAAA,cAAc,GAAG,CAAC,CAAC;AACnB,QAAA,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AAwBtC,oEAAoE;AACpE,SAAgB,SAAS,CAAC,QAAgB,EAAE,OAAoB;IAC9D,MAAM,CAAC,GAAG,IAAA,wBAAU,EAAC,QAAQ,CAAC,CAAC;IAC/B,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC;IACxC,CAAC,CAAC,MAAM,CAAC,IAAA,6BAAc,EAAC,OAAO,CAAC,CAAC,CAAC;IAClC,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACzB,CAAC;AAED,SAAS,QAAQ,CAAC,KAAwB;IACxC,MAAM,KAAK,GAAG,IAAA,sBAAO,EAAC,KAAK,CAAC,CAAC;IAC7B,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACvD,CAAC;AAED,SAAS,WAAW,CAAC,KAAkB;IACrC,MAAM,GAAG,GAAgB,EAAE,CAAC;IAC5B,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC3C,IAAI,CAAC,KAAK,MAAM;YAAE,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAC/B,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AASD,8CAA8C;AAC9C,MAAa,QAAQ;IACV,IAAI,CAAgB;IACZ,KAAK,CAAkB;IAChC,IAAI,GAAG,eAAO,CAAC;IACf,GAAG,GAAG,CAAC,CAAC;IACC,QAAQ,GAAkB,EAAE,CAAC;IAE9C;;;;OAIG;IACH,YAAY,OAAqC,EAAE;QACjD,MAAM,IAAI,GAAiB,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;QAC7F,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC;QAC9B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;QAC9B,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YACd,IAAA,mBAAS,EAAC,IAAA,mBAAO,EAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YACnD,IAAA,uBAAa,EAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY;QAC5C,CAAC;IACH,CAAC;IAED,MAAM,CAAC,KAAa,EAAE,EAAmB,EAAE,SAAsB,EAAE;QACjE,MAAM,OAAO,GAAgB;YAC3B,CAAC,EAAE,sBAAc;YACjB,GAAG,EAAE,IAAI,CAAC,GAAG;YACb,EAAE;YACF,KAAK;YACL,GAAG,MAAM;YACT,SAAS,EAAE,IAAI,CAAC,IAAI;SACrB,CAAC;QACF,OAAO,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAChD,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,MAAM,CAAW,CAAC;QACtC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;QACd,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC5B,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YACd,wEAAwE;YACxE,uEAAuE;YACvE,IAAA,wBAAc,EAAC,IAAI,CAAC,IAAI,EAAE,IAAA,0BAAW,EAAC,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;QACzD,CAAC;QACD,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK;YAAE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACnD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;IAC/B,CAAC;IAED,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;IAC9B,CAAC;IAED,CAAC,MAAM,CAAC,QAAQ,CAAC;QACf,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;IACzC,CAAC;IAED,0EAA0E;IAE1E,kFAAkF;IAClF,IAAI;QACF,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,CAAC,CAAC,CAAC,EAAE,eAAO,CAAC,CAAC;QACrD,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC;QACtD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAE,EAAE,IAAI,CAAC,MAAM,CAAW,CAAC,CAAC;IAC1D,CAAC;IAEO,WAAW;QACjB,OAAO,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAClC,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,MAAc,EAAE,KAAsB,CAAC;QAC5C,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QAChC,MAAM,IAAI,GAAG,EAAE,CAAC,EAAE,sBAAc,EAAE,QAAQ,EAAE,IAAI,CAAC,WAAW,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;QAChF,OAAO;YACL,GAAG,IAAI;YACP,GAAG,EAAE,MAAM,CAAC,GAAG,IAAI,IAAI;YACvB,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,IAAA,6BAAc,EAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC;SACvD,CAAC;IACJ,CAAC;IAED,iEAAiE;IACjE,MAAM,CAAC,YAAY,CACjB,OAA+B,EAC/B,MAAgD,EAChD,MAAc;QAEd,MAAM,CAAC,GAAG,MAAM,IAAI,EAAE,CAAC;QACvB,MAAM,IAAI,GAA0B,EAAE,CAAC;QACvC,KAAK,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC;YAAE,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;QAC/E,MAAM,MAAM,GAAI,IAAA,sBAAO,EAAC,CAAC,CAAC,KAAK,CAAC,CAAY,IAAI,EAAE,CAAC;QACnD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,uBAAuB,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YACxE,OAAO,CAAC,KAAK,EAAE,0BAA0B,CAAC,CAAC;QAC7C,CAAC;QACD,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QACvC,MAAM,GAAG,GAAG,IAAA,sBAAO,EAAC,CAAC,CAAC,KAAK,CAAC,CAAkB,CAAC;QAC/C,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAA,6BAAc,EAAC,IAAI,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC;YACnD,OAAO,CAAC,KAAK,EAAE,0BAA0B,CAAC,CAAC;QAC7C,CAAC;QACD,MAAM,CAAC,EAAE,EAAE,GAAG,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC3C,IAAI,CAAC,EAAE;YAAE,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAC7B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;QACnE,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC;QAC1C,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,IAAA,sBAAO,EAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;YACxF,OAAO,CAAC,KAAK,EAAE,gEAAgE,CAAC,CAAC;QACnF,CAAC;QACD,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACtB,CAAC;IAED,2DAA2D;IAC3D,MAAM,CAAC,MAAM,CAAC,OAA+B;QAC3C,IAAI,IAAI,GAAG,eAAO,CAAC;QACnB,IAAI,WAAW,GAAG,CAAC,CAAC;QACpB,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;YACxB,MAAM,GAAG,GAAG,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;YAC/B,IAAI,GAAG,KAAK,WAAW,EAAE,CAAC;gBACxB,OAAO,CAAC,KAAK,EAAE,cAAc,WAAW,SAAS,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC;YAC3E,CAAC;YACD,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC;YACzB,MAAM,OAAO,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;YAC/B,IAAI,IAAA,sBAAO,EAAC,OAAO,CAAC,WAAW,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;gBAC3C,OAAO,CAAC,KAAK,EAAE,6BAA6B,WAAW,EAAE,CAAC,CAAC;YAC7D,CAAC;YACD,IAAI,SAAS,CAAC,IAAI,EAAE,OAAO,CAAC,KAAK,MAAM,EAAE,CAAC;gBACxC,OAAO,CAAC,KAAK,EAAE,wBAAwB,WAAW,EAAE,CAAC,CAAC;YACxD,CAAC;YACD,IAAI,GAAG,MAAgB,CAAC;YACxB,WAAW,IAAI,CAAC,CAAC;QACnB,CAAC;QACD,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACtB,CAAC;IAED,uEAAuE;IACvE,MAAM,CAAC,IAAI,CAAC,IAAY;QACtB,OAAO,QAAQ,CAAC,UAAU,CAAC,IAAA,sBAAY,EAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;IACzD,CAAC;IAED,iEAAiE;IACjE,MAAM,CAAC,UAAU,CAAC,IAAY;QAC5B,OAAO,IAAI;aACR,KAAK,CAAC,OAAO,CAAC;aACd,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC;aACpC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAA,wBAAS,EAAC,IAAI,CAAgB,CAAC,CAAC;IACnD,CAAC;CACF;AApJD,4BAoJC;AAED,SAAS,SAAS,CAAC,KAAwB;IACzC,MAAM,KAAK,GAAG,IAAA,sBAAO,EAAC,KAAK,CAAC,CAAC;IAC7B,OAAO,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACxE,CAAC;AAED,4DAA4D;AAC5D,SAAgB,SAAS,CAAC,OAA+B;IACvD,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,MAAM,EAAE,GAAG,IAAA,sBAAO,EAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC;QAClC,IAAI,OAAO,EAAE,KAAK,QAAQ,IAAI,EAAE;YAAE,OAAO,EAAE,CAAC;IAC9C,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/cjs/authority.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Authority — the core value object.
+ *
+ * An Authority is an immutable capability: a set of scopes plus typed `Ceiling`
+ * bounds and a TTL. The single most important operation is `meet`: the greatest
+ * authority that is within BOTH a parent's authority and a requested one. A
+ * child of a delegation can never hold more than the meet — attenuation is a
+ * lattice operation, enforced in code, not a convention.
+ *
+ * The guarantee everything else rests on:
+ *
+ *     meet(parent, requested) <= parent   for ALL requested.
+ *
+ * There is no code path by which a derived child authority can exceed its
+ * parent. That is what makes model-proposed authority safe to accept: the
+ * proposal is only ever an input to `meet`, and `meet` can only shrink.
+ *
+ * `isNarrowerThan` is exactly the wire protocol's subsumption relation
+ * (draft-asor-wimse-agent-delegation-chain-00), so a chain that verifies offline
+ * is one the library would have permitted, and the reverse.
+ */
+import { type CJson, type Json } from "./canonical.js";
+import { type Ceiling, type Context } from "./ceilings.js";
+import { Decision } from "./reasons.js";
+/**
+ * Raised for STRUCTURAL failures — bad input or invalid chain state, such as
+ * delegating from a revoked or expired node, or a depth/fanout overflow.
+ * Deliberately distinct from a policy denial: a denial is a normal outcome,
+ * expressed as a `Decision`. A structural error means the caller did something
+ * invalid; a denial means the caller asked for something the authority model
+ * legitimately refuses.
+ */
+export declare class AuthorityError extends Error {
+    readonly reason: string;
+    readonly detail: Record<string, Json>;
+    constructor(message: string, reason: string, detail?: Record<string, Json>);
+}
+export interface AuthorityInit {
+    scopes?: Iterable<string>;
+    ceilings?: Iterable<Ceiling>;
+    /** Seconds this authority remains valid from issuance; `null` is unbounded. */
+    ttl?: number | null;
+}
+/** The wire form of an Authority. */
+export interface AuthorityWire {
+    scopes: string[];
+    constraints: Record<string, Json>[];
+    ttl: number | null;
+    [key: string]: CJson;
+}
+export declare class Authority {
+    /**
+     * Permission strings, e.g. `crm.read`. Scopes support one level of prefix
+     * wildcard: `crm.*` covers `crm.read` and `crm.write`. A child requesting
+     * `crm.read` under a parent holding `crm.*` is allowed; the reverse is not.
+     */
+    readonly scopes: ReadonlySet<string>;
+    /**
+     * At most one ceiling per `key` (last one wins), sorted by key for a
+     * deterministic wire form and integrity seal. A dimension with no ceiling is
+     * unbounded on that dimension unless a parent in the chain bounds it —
+     * attenuation can only add or tighten bounds, never remove one.
+     */
+    readonly ceilings: readonly Ceiling[];
+    /** Seconds from issuance. `null` is unbounded (discouraged). */
+    readonly ttl: number | null;
+    constructor(init?: AuthorityInit);
+    private byKey;
+    /** The ceiling bound to `key`, or `undefined`. */
+    ceiling(key: string): Ceiling | undefined;
+    /** Does a held scope cover a requested scope? Supports one `x.*` wildcard. */
+    static scopeCovers(held: string, requested: string): boolean;
+    coversScope(requested: string): boolean;
+    /**
+     * The greatest authority within BOTH `this` and `other` — the attenuation.
+     * This is the only way a child authority is constructed. It is commutative
+     * and can only ever shrink relative to either input.
+     */
+    meet(other: Authority): Authority;
+    /**
+     * `this <= other`: is `this` provably no more powerful than `other` in every
+     * dimension? True iff:
+     *
+     *   1. every scope of `this` is covered by `other` (wildcard-aware);
+     *   2. for every ceiling in `other` there is a ceiling of the same key in
+     *      `this` that `other`'s ceiling subsumes. A ceiling present in `other`
+     *      and ABSENT here means `this` is unbounded on that dimension, i.e. more
+     *      powerful, so the relation is false. This holds for any ceiling key,
+     *      including ones outside the built-in registry, which is what makes the
+     *      relation sound for custom ceilings too;
+     *   3. `this.ttl` is not null and (`other.ttl` is null or `this.ttl <= other.ttl`).
+     *
+     * This is exactly the wire subsumption relation: the library relation and the
+     * token relation are the same relation.
+     */
+    isNarrowerThan(other: Authority): boolean;
+    /**
+     * Is `scope` permitted under this authority, given a request context such as
+     * `{rows: 5000, egress: "none"}`?
+     *
+     * Checks scope coverage AND every ceiling this authority holds, collecting
+     * every failing reason — not just the first — so a single evaluation can
+     * explain everything wrong with a request. A ceiling whose context field is
+     * absent is not asserting anything on this call and is treated as satisfied.
+     */
+    permits(scope: string, ctx?: Context | null): Decision;
+    withTtl(ttl: number): Authority;
+    toWire(): AuthorityWire;
+    static fromWire(wire: CJson): Authority;
+    /** A stable, human-readable one-liner. */
+    describe(): string;
+    toString(): string;
+}
+//# sourceMappingURL=authority.d.ts.map

package/dist/cjs/authority.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authority.d.ts","sourceRoot":"","sources":["../../src/authority.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAA6C,KAAK,KAAK,EAAE,KAAK,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAClG,OAAO,EAAgD,KAAK,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,eAAe,CAAC;AACzG,OAAO,EAAE,QAAQ,EAAsB,MAAM,cAAc,CAAC;AAE5D;;;;;;;GAOG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;gBAE1B,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAM;CAM/E;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC1B,QAAQ,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC7B,+EAA+E;IAC/E,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED,qCAAqC;AACrC,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,CAAC;IACpC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAGnB,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC;CACtB;AAED,qBAAa,SAAS;IACpB;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAErC;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IAEtC,gEAAgE;IAChE,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;gBAEhB,IAAI,GAAE,aAAkB;IAUpC,OAAO,CAAC,KAAK;IAMb,kDAAkD;IAClD,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS;IAMzC,8EAA8E;IAC9E,MAAM,CAAC,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO;IAM5D,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IASvC;;;;OAIG;IACH,IAAI,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS;IAsCjC;;;;;;;;;;;;;;;OAeG;IACH,cAAc,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO;IAkBzC;;;;;;;;OAQG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,GAAE,OAAO,GAAG,IAAW,GAAG,QAAQ;IA0B5D,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS;IAM/B,MAAM,IAAI,aAAa;IAQvB,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,GAAG,SAAS;IAYvC,0CAA0C;IAC1C,QAAQ,IAAI,MAAM;IAMlB,QAAQ,IAAI,MAAM;CAGnB"}