attenu-guard 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+All notable changes to this package are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this package
+follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] — 2026-08-28
+
+First release: the TypeScript implementation of attenu-guard.
+
+### Added
+
+- **Offline verifier.** `verifyBundle` checks integrity, monotonicity
+  (child ⊆ parent) and containment from an evidence bundle alone, with the
+  signed anchor verified when a key is supplied. HS256 and Ed25519 anchors are
+  both read. `AuditLog.verify` checks a raw `.jsonl` ledger's hash chain.
+  `delegationGraph` and `denials` fold a bundle into the reviewer's view.
+- **Core enforcement.** `Authority` (scopes with `family.*` wildcards, typed
+  ceilings, TTL), `Guard.issue`, `delegate` (the meet: scopes intersect,
+  ceilings take the tighter bound, TTL the shorter; a request wider than the
+  parent comes back narrowed), `check` returning a `Decision`, `enforce`
+  throwing `AuthorityDenied`, `wouldAllow` and `wouldDelegate` as pure dry-runs,
+  chain depth and fanout ceilings, cascade `revoke` and principal-scoped
+  `revokeAgent`, strike policy, and a hash-chained audit log.
+- **Ceilings:** `RowLimit`, `SpendCap`, `CallLimit` (optionally scoped, and
+  self-metering), `EgressRank`, `Allow`, `Deny`, `Prefix`, plus
+  `registerCeiling` for custom ones. An unrecognised constraint type denies
+  rather than going unenforced.
+- **Evidence custody.** `exportBundle` with task redaction and a strict mode
+  that refuses to carry any field outside the published ledger allow-list.
+- **LangGraph.js adapter** (`attenu-guard/adapters/langgraph`): `guardTool`,
+  `guardTools`, `guardNode`, `addGuardedNode`, `delegateTo`, `toolArgs`. The
+  adapter never imports the framework.
+- **CLI:** `attenu-guard verify <file> [--hs256-key HEX | --pubkey HEX] [--kid KID]`,
+  matching the Python CLI's output lines and exit codes.
+- **Cross-language fixtures.** `tools/gen_fixtures.py` generates
+  `test/fixtures/` from the Python package; the suite reproduces every vector,
+  and a further test has the Python CLI verify a ledger and bundle written here.
+
+### Notes
+
+- Zero runtime dependencies. ESM and CommonJS builds, types included, Node 18+.
+- Canonical JSON is byte-identical to Python's
+  `json.dumps(obj, sort_keys=True, separators=(",", ":"))`, including ASCII
+  escaping and number formatting. Documents that will be re-hashed are parsed
+  with number literals preserved.

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Attenu
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,200 @@
+# attenu-guard (TypeScript)
+
+Permissions for multi-agent systems, enforced at the point of the call.
+
+A sub-agent holds a subset of what its parent holds. Every tool call is checked
+against the calling agent's own permissions, every handoff narrows them, and
+every decision lands in a hash-chained log that anyone can verify offline —
+without this library, its authors, or a network.
+
+This is the TypeScript implementation. It writes the same ledger and the same
+evidence bundle as the [Python library](https://github.com/attenu-io/attenu-guard),
+and reads either one's output.
+
+- Zero runtime dependencies — Node's own `crypto`, nothing else
+- ESM and CommonJS builds, types included
+- Node 20 and above (the LangGraph.js adapter depends on `langsmith`, which needs the global WebCrypto that Node 19 introduced; Node 18 is end-of-life)
+
+## Install
+
+```
+npm install attenu-guard
+```
+
+## Verify a run you did not produce
+
+You have a bundle exported from an agent run, and the public half of the key
+that anchored it. You do not need an account, a network, or the system that
+produced it.
+
+```
+npx attenu-guard verify run.bundle.json --pubkey <hex>
+```
+
+```
+integrity=True monotonicity=True containment=True anchor=verified nodes=3 actions_checked=2
+OK
+```
+
+Three things were checked from the file alone:
+
+- **integrity** — every entry hashes to the next, and the head matches the signed
+  anchor. Nothing was inserted, removed, or rewritten afterwards.
+- **monotonicity** — every delegated agent's permissions are a subset of its
+  parent's, all the way down.
+- **containment** — every allowed action fell inside what the acting agent held
+  at the time.
+
+Those are different findings. A broken chain says the record was edited. A
+broken monotonicity check says the record is honest and the delegation was not —
+which points at a different person. The same checks are available in code:
+
+```ts
+import { parseBundle, verifyBundle, Ed25519Verifier } from "attenu-guard";
+import { readFileSync } from "node:fs";
+
+const bundle = parseBundle(readFileSync("run.bundle.json", "utf8"));
+const report = verifyBundle(bundle, new Ed25519Verifier(Buffer.from(pubkeyHex, "hex")));
+
+report.ok;       // false if any check failed
+report.checks;   // { integrity, monotonicity, containment, anchor }
+report.failures; // one line per finding
+```
+
+Pass `null` instead of a key and the chain, subset and containment checks still
+run; the anchor is reported as `not checked`, and `ok` then means *consistent*
+rather than *verified* — a consistent full rewrite by someone holding the signing
+key cannot be excluded without the key.
+
+## Guard a delegation chain
+
+```ts
+import { Authority, Guard, RowLimit, EgressRank } from "attenu-guard";
+
+const orchestrator = Guard.issue("orchestrator", new Authority({
+  scopes: ["crm.*", "mail.send"],
+  ceilings: [new RowLimit(100_000), new EgressRank("any")],
+  ttl: 3600,
+}));
+
+// The handoff is where permissions narrow. A request wider than the parent
+// holds comes back narrowed — `fs.write` was never the orchestrator's to give.
+const summarizer = orchestrator.delegate("summarizer", new Authority({
+  scopes: ["crm.read", "fs.write"],
+  ceilings: [new RowLimit(5_000), new EgressRank("none")],
+  ttl: 900,
+}), "summarise the Q3 pipeline");
+
+summarizer.authority.scopes;            // Set { "crm.read" }
+summarizer.isNarrowerThan(orchestrator); // true, by construction
+
+const decision = summarizer.check("crm.read", { context: { rows: 4200 } });
+if (!decision.allowed) console.log(decision.explain());
+
+summarizer.enforce("crm.export", { context: { egress: "any" } }); // throws AuthorityDenied
+```
+
+`check` returns a `Decision` and never throws — a denial is an outcome to reason
+about, not a bug. `enforce` throws `AuthorityDenied` where a denial should stop
+the caller. `wouldAllow` runs the same evaluation and writes nothing, so a
+planner can ask without leaving a record of an attempt.
+
+Beyond scopes, a chain has ceilings no single-agent permission model expresses:
+row and spend caps, an ordered egress rank, per-scope call limits that meter
+themselves, membership and prefix bounds, a TTL, and depth and fanout limits on
+the tree. `revoke` cascades to a whole subtree; `revokeAgent` bans a principal
+chain-wide, so a framework that hands off to it again cannot mint it fresh
+permissions. A constraint type this build does not recognise denies rather than
+going unenforced.
+
+Export the evidence when the run is done:
+
+```ts
+import { exportBundle, Ed25519Signer } from "attenu-guard";
+
+const signer = Ed25519Signer.generate();
+const bundle = exportBundle(orchestrator.auditLog(), signer);
+// Publish the bundle; distribute signer.publicBytesRaw() out of band.
+```
+
+## LangGraph.js
+
+```ts
+import { ToolNode } from "@langchain/langgraph/prebuilt";
+import { delegateTo, guardTools, toolArgs } from "attenu-guard/adapters/langgraph";
+
+const researcher = delegateTo(supervisor, {
+  agentId: "researcher",
+  request: new Authority({ scopes: ["crm.read"], ceilings: [new RowLimit(500)], ttl: 900 }),
+  task: "summarise the pipeline",
+});
+
+const node = new ToolNode(guardTools(researcher, [crmQuery, wireMoney], {
+  scopes: { crm_query: "crm.read", wire_money: "payments.send" },
+  contexts: { crm_query: (input) => ({ rows: toolArgs(input).limit }) },
+  onDenied: (decision) => `Denied by attenu-guard: ${decision.explain()}`,
+}));
+```
+
+`wire_money` is refused: the researcher does not hold `payments.send`, and the
+supervisor could not have granted it either. The tool body never runs. With
+`onDenied` the model sees the refusal and can re-plan; leave it out and the call
+throws `AuthorityDenied` instead.
+
+**Which hook this uses.** LangGraph.js exposes no public before-tool-call hook —
+`ToolNode` resolves the tool itself and calls `tool.invoke(toolCall, runtime)`
+inside a `protected runTool`. So the adapter takes the tool-wrapping form:
+`guardTool` returns a stand-in whose `invoke` authorizes first and forwards
+everything else — `name`, `description`, `schema` — to the original, which is
+all `ToolNode` matches on. `guardNode` wraps any node callable the same way, and
+`addGuardedNode` registers one on a graph. LangGraph is never imported by the
+adapter; it is a devDependency here, used to test against the real `ToolNode`.
+
+## Cross-language interoperability
+
+Same bundle format as the Python library, verified by cross-language fixtures.
+`tools/gen_fixtures.py` generates `test/fixtures/` from the Python package —
+canonical-form vectors, entry-hash vectors, `meet` and subsumption cases, a raw
+ledger, and one bundle per tamper mode with the report Python produces for each.
+The suite reproduces all of it, and a separate test writes a ledger and bundle
+here and has the Python CLI verify them, so both directions are covered.
+
+Getting this right needs more than `JSON.stringify`: Python sorts keys, escapes
+every non-ASCII code point, and distinguishes `100` from `100.0`. A document
+that will be re-hashed is therefore read with a parser that keeps each number's
+original literal. See `src/canonical.ts`.
+
+## What it does not do
+
+- It does not decide what permissions a task needs. You state them; this library
+  enforces that a child never exceeds its parent and records what happened.
+- It does not sandbox anything. A tool called around the guard is not guarded.
+- The in-process integrity seal catches bugs and casual mutation, not code
+  running in the same process. Tamper-evidence comes from the signed bundle.
+- `HS256TestSigner` is for tests and local development. It is symmetric, so
+  anyone who can verify can also forge. Use `Ed25519Signer` in production.
+
+## Development
+
+```
+npm install
+npm run build
+npm test
+```
+
+`npm test` builds first. The Python-CLI interoperability test skips unless a
+Python `attenu-guard` is reachable:
+
+```
+ATTENU_GUARD_PY=path/to/venv/bin/attenu-guard npm test
+```
+
+Regenerate the fixtures with `npm run fixtures` (needs the Python package and
+`cryptography` importable).
+
+Publishing runs on a `v*` tag through npm trusted publishing, which needs a
+one-time trusted-publisher configuration on the npm side for this package.
+
+## Licence
+
+Apache-2.0. Security reports: see [SECURITY.md](SECURITY.md).

package/SECURITY.md

@@ -0,0 +1,34 @@
+# Security policy
+
+## Reporting a vulnerability
+
+Report privately — please do not open a public issue.
+
+- **Preferred:** a [private security advisory](https://github.com/attenu-io/attenu-guard-ts/security/advisories/new)
+  on this repository.
+- **Email:** security@attenu.io
+
+Please include the version, a description of the issue, and the smallest
+reproduction you can manage. We aim to acknowledge within three working days
+and to keep you informed while a fix is prepared. We will credit you in the
+advisory unless you would rather we did not.
+
+## Supported versions
+
+The most recent minor release receives security fixes.
+
+## Scope
+
+In scope: anything that lets a delegated agent hold permissions its parent did
+not hold, lets a denied action through, or lets a tampered ledger or evidence
+bundle verify as intact.
+
+Out of scope, because they are documented properties rather than defects:
+
+- `HS256TestSigner` is symmetric and is not for production. Anyone able to
+  verify with it can also forge. Use `Ed25519Signer`.
+- The in-process integrity seal catches bugs and casual mutation. Code running
+  in the same process can read the chain secret; tamper-evidence for a third
+  party comes from the signed evidence bundle.
+- A tool invoked around the guard rather than through it is not guarded. This
+  library authorizes calls; it does not sandbox them.

package/bin/attenu-guard.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+"use strict";
+const { main } = require("../dist/cjs/cli.js");
+process.exitCode = main(process.argv.slice(2));

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

@@ -0,0 +1 @@
+{"version":3,"file":"langgraph.d.ts","sourceRoot":"","sources":["../../../src/adapters/langgraph.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAEH,OAAO,EAAmB,KAAK,KAAK,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,+CAA+C;AAC/C,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,SAAS,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC;IACxC,gFAAgF;IAChF,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,sDAAsD;IACtD,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,8EAA8E;AAC9E,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,IAAI,CAAC,GAAG;IAC/D,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC;CACvB,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EACzD,KAAK,EAAE,KAAK,EACZ,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,CAAC,EACL,OAAO,GAAE,YAAiB,GACzB,WAAW,CAAC,CAAC,CAAC,CAsBhB;AAED,6EAA6E;AAC7E,MAAM,WAAW,SAAS;IACxB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC;CACjF;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EAC9D,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,KAAK,EACZ,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,CAAC,EACL,OAAO,GAAE,YAAiB,GACzB,WAAW,CAAC,CAAC,CAAC,CAIhB;AAED,uEAAuE;AACvE,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,KAAK,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,GAAG,GAAG,GAAG,CAAC;IACtC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED,MAAM,WAAW,gBAAiB,SAAQ,YAAY;IACpD,kEAAkE;IAClE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,KAAK,GAAG,CAAC;CACpD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,QAAQ,EAC1C,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,CAAC,EACP,OAAO,GAAE,gBAAqB,GAC7B,CAAC,CA4BH;AAED,8EAA8E;AAC9E,eAAO,MAAM,YAAY,kBAAkB,CAAC;AAC5C,eAAO,MAAM,YAAY,kBAAkB,CAAC;AAE5C,MAAM,WAAW,iBAAkB,SAAQ,YAAY;IACrD,wEAAwE;IACxE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,CAAC;IACjE,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,KAAK,GAAG,CAAC;CACpD;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,QAAQ,EAC3C,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,OAAO,GAAE,iBAAsB,GAC9B,CAAC,EAAE,CAUL;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAMxD;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,SAAS,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,eAAe,GAAG,KAAK,CAEzE;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,OAAO,CAAC,CAQ7D"}