@tenuo/core 0.3.2-beta.0 → 0.3.3-beta.0

package/README.md

@@ -16,7 +16,7 @@ npm i @tenuo/core@beta
 ```
 
 ```ts
-import { createTenuo, under } from "@tenuo/core";
+import { AuthorizationDeniedError, createTenuo, under } from "@tenuo/core";
 
 const tenuo = createTenuo({ root: createTenuo.devRoot() });
 const readFile = tenuo.tool(
@@ -26,15 +26,22 @@ const readFile = tenuo.tool(
 const session = tenuo.session({ tools: [readFile] });
 
 await tenuo.withSession(session, async () => {
-  await readFile.execute({ path: "/data/q3.pdf" }); // allowed
-  await readFile.execute({ path: "/etc/passwd" }); // denied — execute does not run
+  console.log(await readFile.execute({ path: "/data/q3.pdf" })); // allowed
+  try {
+    await readFile.execute({ path: "/etc/passwd" }); // denied — execute does not run
+  } catch (error) {
+    if (!(error instanceof AuthorizationDeniedError)) throw error;
+    console.log("denied:", error.code);
+  }
 });
 ```
 
 Host schemas (Zod or otherwise) answer **valid**. Tool `allow` is the host ceiling.
 The session is what this agent may do. Rust AND's both. `allow` is zero-trust:
 every call argument must be named in the policy. `allow: {}` adds no extra
-ceiling. `devRoot()` requires `NODE_ENV=development` or `test`,
+ceiling, and `session({ tools })` refuses such a tool unless the session's own
+`allow` names it (`allow: { read_file: {} }`), because an empty capability in
+a warrant accepts any arguments. Unknown policy and option keys throw. `devRoot()` requires `NODE_ENV=development` or `test`,
 `devRoot({ allowInProduction: true })`, or `TENUO_ALLOW_DEV=1`. Unset
 `NODE_ENV` is not treated as development.
 
@@ -49,6 +56,8 @@ const runtime = createTenuo.runtime({
   trustedRoots: [createTenuo.publicKeyFromEnv("TENUO_ROOT_PUBLIC_KEY")],
   receipts: "collect",
 });
+// TENUO_WARRANT holds session.toWireString() from the issuer: the whole chain
+// as one string. sessionFromWire() also accepts the toWire() array.
 const session = runtime.sessionFromWire(process.env.TENUO_WARRANT!);
 await readFile.execute({ path: "/data/q3.pdf" }, { session });
 const receipts = session.drainReceipts(); // persist, then upload
@@ -59,7 +68,7 @@ read environment variables or invent an origin. Relative `/v1` endpoints need
 `token.resolveEndpoint({ localBase })`. Callers append `/v1/…` to the bare
 origin.
 
-See [Receipt delivery](../../README.md#receipt-delivery) for peek / drain / ack
+See [Receipt delivery](https://github.com/tenuo-ai/tenuo/tree/main/tenuo-ts#receipt-delivery) for peek / drain / ack
 guarantees. This package does not perform HTTP, discovery, or upload.
 
 Delegation to another agent rebinds a narrower child to that agent's key. The
@@ -96,11 +105,13 @@ MCP wire helpers live on `tenuo.mcp` (`attach` / `verify` / `handler`). They do
 not depend on an MCP framework. For the official v2 server, use `@tenuo/mcp`.
 For `@modelcontextprotocol/sdk` v1, copy the recipe in `examples/mcp/host.ts`.
 `verify` / `handler` can take an optional `nonceStore` (`memoryNonceStore()`,
-or an async Redis `checkAndRecord`) to reject an exact replayed PoP; that is
-opt-in. PoP v1 is otherwise replayable in-window, including approval-gated
-calls. Pass `nonceStore` on those tools if an approval must be one-use.
+or an async Redis `checkAndRecord`) to reject an exact replayed PoP and to
+consume the approvals an allowed call carried; that is opt-in. PoP v1 is
+otherwise replayable in-window, including approval-gated calls. For
+in-process tools, pass the same `nonceStore` to `tenuo.tool()` to make
+approvals one-use there.
 `memoryNonceStore({ ttlSeconds })` defaults to 180 seconds; an explicit TTL must
 be positive, finite, and small enough to represent in milliseconds.
 
-See the [workspace README](../../README.md) for the full API, refuse list, and
+See the [workspace README](https://github.com/tenuo-ai/tenuo/tree/main/tenuo-ts) for the full API, refuse list, and
 how to rebuild WASM from this monorepo.

package/dist/api.d.ts

@@ -121,15 +121,38 @@ export type ToolPolicy<TArgs = undefined> = {
     /**
      * Host ceiling. AND'd with the session in Rust.
      * Non-empty maps are zero-trust: every call argument must be named here.
-     * `{}` means no extra ceiling (session/warrant only).
+     * `{}` means no extra ceiling (session/warrant only). Required: a missing
+     * `allow` or an unknown policy key throws. `session({ tools })` refuses a
+     * tool whose `allow` is `{}` unless the session's own `allow` names that
+     * capability explicitly, because an empty capability in a warrant accepts
+     * any arguments.
      */
     readonly allow: [NonNullable<TArgs>] extends [object] ? [KeysOfUnion<NonNullable<TArgs>>] extends [never] ? AllowPolicy : string extends KeysOfUnion<NonNullable<TArgs>> ? AllowPolicy : number extends KeysOfUnion<NonNullable<TArgs>> ? AllowPolicy : symbol extends KeysOfUnion<NonNullable<TArgs>> ? AllowPolicy : {
         readonly [Field in KeysOfUnion<NonNullable<TArgs>>]?: ConstraintExpr;
     } : AllowPolicy;
     readonly capability?: string;
+    /**
+     * Makes approvals one-use for this tool. When a call that carried
+     * `approvals` is allowed, each approval envelope that matches the call is
+     * recorded here before the tool body runs; an envelope the store has
+     * already seen denies with `TENUO_INSUFFICIENT_APPROVALS`. Same
+     * `NonceStore` shape as the MCP verify path; `memoryNonceStore()` works
+     * for one process. The store must remember a key for as long as an
+     * approval can live (one hour by default), so give `memoryNonceStore()` a
+     * matching `ttlSeconds`. A store that throws, rejects, or returns a
+     * non-boolean fails closed with "Replay store unavailable".
+     */
+    readonly nonceStore?: NonceStore;
+    /** Isolated. Called when `nonceStore.checkAndRecord` throws or rejects. */
+    readonly onNonceStoreError?: (error: unknown) => void | Promise<void>;
 };
 /** Compile-time brand only — never assigned at runtime. Do not `in`/`has` this key. */
 declare const protectedBrand: unique symbol;
+/**
+ * Tenuo's per-call options. Other keys pass through to the wrapped tool's own
+ * `execute`, except keys that look like a misspelled Tenuo option
+ * (`sesion`, `approval`, `onReciept`), which throw instead of being ignored.
+ */
 export type ExecuteOptions = {
     readonly session?: Session;
     /** Already-signed approval envelopes (hex, standard base64, or CBOR bytes). */
@@ -308,7 +331,10 @@ export type NarrowOptions = {
      * cannot authorize here. Hand `toWire()` to that agent.
      */
     readonly holder?: PublicKeyHandle;
-    /** Child lifetime. Clamped to what the parent has left. */
+    /**
+     * Child lifetime. A value longer than the parent has left is clamped to the
+     * parent's expiry, not rejected: the child never outlives the parent.
+     */
     readonly ttlSeconds?: number;
     /** The child's holder cannot delegate further. */
     readonly terminal?: boolean;
@@ -319,7 +345,7 @@ export type NarrowOptions = {
     readonly agentId?: string;
     /** Approvers can only be added. */
     readonly addApprovers?: readonly PublicKeyHandle[];
-    /** The threshold can only go up. */
+    /** The threshold can only go up. A value below the parent's throws. */
     readonly minApprovals?: number;
 };
 /** Options for `tenuo.issue()`: an execution session minted from an issuer session. */
@@ -508,6 +534,13 @@ export interface Session {
     readonly [Symbol.toStringTag]: "TenuoSession";
     /** Warrant tokens, root first. Does not include the holder secret. */
     toWire(): readonly string[];
+    /**
+     * The whole chain as one string: a CBOR warrant stack in URL-safe base64,
+     * the same encoding as `PresentedCall.warrant`. Use it where only a single
+     * string fits (an environment variable, a header). `sessionFromWire()`
+     * imports it. Does not include the holder secret.
+     */
+    toWireString(): string;
     /** SHA-256 of `(warrant_id, tool, canonical args)`. App-level idempotency, not PoP. */
     dedupKey(tool: string, args: Readonly<Record<string, unknown>>): string;
     /** Holder public key, depth, ceiling, lifetime, tools. Never the secret. */

package/dist/api.js.map

@@ -1 +1 @@
-{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA;;;;;GAKG","sourcesContent":["/**\n * Frozen public contract for `@tenuo/core`.\n *\n * Names and shapes here are the review surface — do not grow this file with\n * protocol vocabulary (`Warrant`, `mint`, `guard`) as the lead API.\n */\n\n/** Canonical kebab-case codes from Rust `ErrorCode::name()` / `Denial::code()`. */\nexport type ProtocolDenialCode =\n  | \"signature-invalid\"\n  | \"untrusted-root\"\n  | \"chain-broken\"\n  | \"depth-exceeded\"\n  | \"warrant-expired\"\n  | \"tool-not-authorized\"\n  | \"constraint-violation\"\n  | \"pop-signature-invalid\"\n  | \"approval-required\"\n  | \"insufficient-approvals\"\n  | \"warrant-revoked\";\n\n/** Legacy SCREAMING_SNAKE aliases accepted by existing TypeScript callers. */\nexport type LegacyTenuoErrorCode =\n  | \"TENUO_NOT_READY\"\n  | \"TENUO_CONFIGURATION\"\n  | \"TENUO_CONSTRAINT_VIOLATION\"\n  | \"TENUO_TOOL_NOT_AUTHORIZED\"\n  | \"TENUO_WARRANT_EXPIRED\"\n  | \"TENUO_UNTRUSTED_ROOT\"\n  | \"TENUO_INVALID_POP\"\n  | \"TENUO_SIGNATURE_INVALID\"\n  | \"TENUO_CHAIN_INVALID\"\n  | \"TENUO_DEPTH_EXCEEDED\"\n  | \"TENUO_REVOKED\"\n  | \"TENUO_APPROVAL_REQUIRED\"\n  | \"TENUO_INSUFFICIENT_APPROVALS\"\n  | \"TENUO_CANONICALIZATION\"\n  | \"TENUO_NOT_IMPLEMENTED\";\n\nexport type TenuoErrorCode = ProtocolDenialCode | LegacyTenuoErrorCode;\n\n// ---------------------------------------------------------------------------\n// Constraints. Every kind is evaluated in the Rust core; TypeScript only\n// builds the marker object. The set matches the core `Constraint` enum.\n// ---------------------------------------------------------------------------\n\n/** Path-traversal-safe prefix. Core evaluates this; TypeScript does not. */\nexport type UnderConstraint = {\n  readonly kind: \"under\";\n  readonly root: string;\n  /** Default true. */\n  readonly caseSensitive?: boolean;\n  /** Whether the root itself is allowed. Default true. */\n  readonly allowEqual?: boolean;\n};\n\nexport type EmailConstraint = {\n  readonly kind: \"email\";\n  readonly domain: string;\n};\n\nexport type MaxConstraint = {\n  readonly kind: \"max\";\n  readonly value: number;\n};\n\nexport type MinConstraint = {\n  readonly kind: \"min\";\n  readonly value: number;\n};\n\nexport type RangeConstraint = {\n  readonly kind: \"range\";\n  readonly min?: number;\n  readonly max?: number;\n  readonly minExclusive?: boolean;\n  readonly maxExclusive?: boolean;\n};\n\nexport type OneOfConstraint = {\n  readonly kind: \"oneOf\";\n  readonly values: readonly string[];\n};\n\nexport type NotOneOfConstraint = {\n  readonly kind: \"notOneOf\";\n  readonly values: readonly string[];\n};\n\nexport type PatternConstraint = {\n  readonly kind: \"pattern\";\n  readonly pattern: string;\n};\n\nexport type RegexConstraint = {\n  readonly kind: \"regex\";\n  readonly source: string;\n};\n\nexport type ExactConstraint = {\n  readonly kind: \"exact\";\n  readonly value: string | number | boolean;\n};\n\nexport type WildcardConstraint = {\n  readonly kind: \"wildcard\";\n};\n\nexport type CidrConstraint = {\n  readonly kind: \"cidr\";\n  readonly network: string;\n};\n\nexport type UrlPatternConstraint = {\n  readonly kind: \"urlPattern\";\n  readonly pattern: string;\n};\n\nexport type UrlSafeConstraint = {\n  readonly kind: \"urlSafe\";\n  readonly schemes?: readonly string[];\n  readonly allowDomains?: readonly string[];\n  readonly denyDomains?: readonly string[];\n};\n\nexport type ShlexConstraint = {\n  readonly kind: \"shlex\";\n  readonly allow: readonly string[];\n};\n\nexport type ContainsConstraint = {\n  readonly kind: \"contains\";\n  readonly values: readonly (string | number | boolean)[];\n};\n\nexport type SubsetConstraint = {\n  readonly kind: \"subset\";\n  readonly values: readonly (string | number | boolean)[];\n};\n\nexport type AnyOfConstraint = {\n  readonly kind: \"anyOf\";\n  readonly constraints: readonly ConstraintExpr[];\n};\n\nexport type AllConstraint = {\n  readonly kind: \"all\";\n  readonly constraints: readonly ConstraintExpr[];\n};\n\nexport type NotConstraint = {\n  readonly kind: \"not\";\n  readonly constraint: ConstraintExpr;\n};\n\nexport type CelConstraint = {\n  readonly kind: \"cel\";\n  readonly expression: string;\n};\n\nexport type ConstraintExpr =\n  | UnderConstraint\n  | EmailConstraint\n  | MaxConstraint\n  | MinConstraint\n  | RangeConstraint\n  | OneOfConstraint\n  | NotOneOfConstraint\n  | PatternConstraint\n  | RegexConstraint\n  | ExactConstraint\n  | WildcardConstraint\n  | CidrConstraint\n  | UrlPatternConstraint\n  | UrlSafeConstraint\n  | ShlexConstraint\n  | ContainsConstraint\n  | SubsetConstraint\n  | AnyOfConstraint\n  | AllConstraint\n  | NotConstraint\n  | CelConstraint;\n\n/** Per-argument allow policy. Not a Zod schema. */\nexport type AllowPolicy = {\n  readonly [field: string]: ConstraintExpr;\n};\n\n/**\n * Framework tool shape we wrap. No dependency on `ai` / Mastra.\n * `parameters` is host-schema (usually Zod) and is never treated as authority.\n */\nexport type ToolLike<\n  TArgs extends Record<string, unknown> = Record<string, unknown>,\n  TResult = unknown,\n> = {\n  readonly description?: string;\n  readonly parameters?: unknown;\n  execute: (args: TArgs, options?: unknown) => TResult | Promise<TResult>;\n};\n\ntype KeysOfUnion<T> = T extends unknown ? keyof T : never;\n\nexport type ToolPolicy<TArgs = undefined> = {\n  /**\n   * Host ceiling. AND'd with the session in Rust.\n   * Non-empty maps are zero-trust: every call argument must be named here.\n   * `{}` means no extra ceiling (session/warrant only).\n   */\n  readonly allow: [NonNullable<TArgs>] extends [object]\n    ? [KeysOfUnion<NonNullable<TArgs>>] extends [never]\n      ? AllowPolicy\n      : string extends KeysOfUnion<NonNullable<TArgs>>\n        ? AllowPolicy\n        : number extends KeysOfUnion<NonNullable<TArgs>>\n          ? AllowPolicy\n          : symbol extends KeysOfUnion<NonNullable<TArgs>>\n            ? AllowPolicy\n            : { readonly [Field in KeysOfUnion<NonNullable<TArgs>>]?: ConstraintExpr }\n    : AllowPolicy;\n  readonly capability?: string;\n};\n\n/** Compile-time brand only — never assigned at runtime. Do not `in`/`has` this key. */\ndeclare const protectedBrand: unique symbol;\n\nexport type ExecuteOptions = {\n  readonly session?: Session;\n  /** Already-signed approval envelopes (hex, standard base64, or CBOR bytes). */\n  readonly approvals?: readonly (string | Uint8Array)[];\n  /**\n   * Signed evidence of the decision. Not a security hook.\n   * Exceptions (sync or rejected Promise) are isolated and never deny or\n   * fail the tool.\n   */\n  readonly onReceipt?: (receipt: string) => void | Promise<void>;\n  /**\n   * Correlation handle written to the receipt. Use whatever id the host\n   * already has — a JSON-RPC id, a trace or span id — so a receipt can be\n   * matched against your own logs. Not an identity: nothing enforces\n   * uniqueness, and distinguishing repeated calls is the receipt chain's job.\n   */\n  readonly requestId?: string;\n};\n\ntype ExtraExecuteOptions<T extends { execute: (args: never) => unknown }> =\n  T[\"execute\"] extends (args: never, options?: infer O) => unknown\n    ? unknown extends O\n      ? object\n      : Omit<NonNullable<O>, keyof ExecuteOptions>\n    : object;\n\n/** Wrapped tool. `execute` still authorizes; optional `{ session }` overrides ALS. */\nexport type ProtectedTool<T extends { execute: (args: never) => unknown }> = Omit<T, \"execute\"> & {\n  execute: (\n    args: Parameters<T[\"execute\"]>[0],\n    options?: ExecuteOptions & ExtraExecuteOptions<T>,\n  ) => Promise<Awaited<ReturnType<T[\"execute\"]>>>;\n  readonly [protectedBrand]: true;\n};\n\n// ---------------------------------------------------------------------------\n// Approvals\n// ---------------------------------------------------------------------------\n\n/** Per-argument trigger for an approval gate. */\nexport type ArgApprovalGate =\n  /** Every value of this argument fires the gate. */\n  | \"all\"\n  /** Only values satisfying the constraint fire the gate. */\n  | { readonly when: ConstraintExpr }\n  /** Every value except those satisfying the constraint fires the gate. Narrowable across delegation. */\n  | { readonly exempt: ConstraintExpr };\n\n/** Gate on one tool: a message for the approver and optional per-argument triggers. */\nexport type ToolApprovalGate = {\n  readonly message?: string;\n  /** Absent: the whole tool is gated. */\n  readonly args?: { readonly [field: string]: ArgApprovalGate };\n};\n\n/** Approval requirement. Host collects SignedApproval envelopes; Rust decides. */\nexport type RequireApproval = {\n  readonly approvers: readonly PublicKeyHandle[];\n  readonly min: number;\n  /** Whole-tool gates. Defaults to every tool in the session when `gates` is absent too. */\n  readonly tools?: readonly string[];\n  /** Per-tool gates with messages and per-argument triggers. */\n  readonly gates?: { readonly [tool: string]: ToolApprovalGate };\n};\n\n/** What an approval service needs to present a call to a human. Not a signed artifact. */\nexport type ApprovalRequest = {\n  readonly requestId: string;\n  readonly warrantId: string;\n  readonly tool: string;\n  readonly args: Readonly<Record<string, unknown>>;\n  /** Hex SHA-256 committing to warrant id, tool, canonical args, and holder. */\n  readonly requestHash: string;\n  readonly holderPublicKey: string;\n  readonly requiredApprovers: readonly string[];\n  readonly minApprovals: number;\n  /** Unix seconds. An approval cannot outlive the warrant. */\n  readonly warrantExpiresAt: number;\n  readonly createdAt: number;\n  readonly message: string;\n};\n\n/** Holder-signed statement that it is the one asking. Carried in a control-plane request. */\nexport type ApprovalContextAttestation = {\n  readonly version: number;\n  readonly canonicalization: string;\n  readonly warrantId: string;\n  readonly tool: string;\n  readonly requestHash: string;\n  readonly holderKeyHex: string;\n  readonly argsCanonicalCborB64: string;\n  readonly signerKeyHex: string;\n  readonly signatureB64: string;\n};\n\n/** Wire body for a control-plane approval API. Field names are the wire names. */\nexport type ControlPlaneApprovalRequestV1 = {\n  readonly schema_version: 1;\n  readonly request_id_hex: string;\n  readonly warrant_id: string;\n  readonly tool: string;\n  readonly arguments: Readonly<Record<string, unknown>>;\n  readonly request_hash_hex: string;\n  readonly holder_public_key_hex: string;\n  readonly required_approver_keys_hex: readonly string[];\n  readonly min_approvals: number;\n  readonly warrant_expires_at_unix: number;\n  readonly created_at_unix: number;\n  readonly attestation?: Readonly<Record<string, unknown>>;\n  readonly temporal?: Readonly<Record<string, string>>;\n  readonly message?: string;\n};\n\nexport type ControlPlaneApprovalResponseV1 = {\n  readonly status: string;\n  readonly signed_approvals_b64?: readonly string[];\n  readonly error?: string;\n  readonly server_request_id?: string;\n};\n\nexport type SignApprovalOptions = {\n  /** Who approved, in the approver system's own terms. Required. */\n  readonly externalId: string;\n  /** Approval lifetime. Default one hour, always clamped to the warrant's expiry when given. */\n  readonly ttlSeconds?: number;\n  readonly warrantExpiresAt?: number;\n};\n\n/** Decoded approval envelope. Not authorization. */\nexport type ApprovalInfo = {\n  readonly approverPublicKey: string;\n  readonly requestHash: string;\n  readonly externalId: string;\n  readonly approvedAt: number;\n  readonly expiresAt: number;\n  readonly expired: boolean;\n  readonly signatureValid: boolean;\n  readonly error?: string;\n};\n\n// ---------------------------------------------------------------------------\n// Sessions\n// ---------------------------------------------------------------------------\n\nexport type SessionAllow = {\n  readonly [capability: string]: AllowPolicy;\n};\n\n/** Named level or a number 0-255. Delegation can only lower it. */\nexport type Clearance =\n  | number\n  | \"untrusted\"\n  | \"external\"\n  | \"partner\"\n  | \"internal\"\n  | \"privileged\"\n  | \"system\";\n\nexport type SessionInput = {\n  /** Capability map. Optional when `tools` is set. Issuer sessions may omit it. */\n  readonly allow?: SessionAllow;\n  /** Wrapped tools from `tenuo.tool()`. Their `allow` is minted into the session. */\n  readonly tools?: readonly object[];\n  readonly ttlSeconds?: number;\n  readonly requireApproval?: RequireApproval;\n  /**\n   * Issue to another agent's key instead of a fresh local holder. The\n   * returned session cannot authorize here (it has no holder secret); send\n   * `toWire()` to that agent, which imports it with `sessionFromWire()`.\n   */\n  readonly holder?: PublicKeyHandle;\n  /**\n   * How many times this authority may be delegated below the root.\n   * `0` makes the session terminal. Omit for the protocol maximum.\n   * Delegation can lower this ceiling and never raise it.\n   */\n  readonly maxDepth?: number;\n  /**\n   * `\"execution\"` (default) can call tools. `\"issuer\"` cannot call tools; its\n   * holder can mint execution sessions with `tenuo.issue()` for the tools in\n   * `issuableTools`, within `constraintBounds`, without the root key.\n   */\n  readonly kind?: \"execution\" | \"issuer\";\n  readonly clearance?: Clearance;\n  /** Free-form task correlation id. Inherited unchanged through delegation. */\n  readonly sessionId?: string;\n  /** Free-form agent label. Delegation may change it. */\n  readonly agentId?: string;\n  /** Issuer sessions only. */\n  readonly issuableTools?: readonly string[];\n  /** Issuer sessions only: ceiling on the constraints of anything issued, by field. */\n  readonly constraintBounds?: AllowPolicy;\n  /** Issuer sessions only: how deep issued sessions may themselves delegate. */\n  readonly maxIssueDepth?: number;\n};\n\n/** Options for `tenuo.narrow()`. All optional; the default keeps the holder. */\nexport type NarrowOptions = {\n  /**\n   * Bind the child to another agent's key. This is delegation: the current\n   * holder signs, the child belongs to `holder`, and the returned session\n   * cannot authorize here. Hand `toWire()` to that agent.\n   */\n  readonly holder?: PublicKeyHandle;\n  /** Child lifetime. Clamped to what the parent has left. */\n  readonly ttlSeconds?: number;\n  /** The child's holder cannot delegate further. */\n  readonly terminal?: boolean;\n  /** Lower the delegation ceiling. Cannot exceed the parent's. */\n  readonly maxDepth?: number;\n  /** Lower the clearance. Cannot exceed the parent's. */\n  readonly clearance?: Clearance;\n  readonly agentId?: string;\n  /** Approvers can only be added. */\n  readonly addApprovers?: readonly PublicKeyHandle[];\n  /** The threshold can only go up. */\n  readonly minApprovals?: number;\n};\n\n/** Options for `tenuo.issue()`: an execution session minted from an issuer session. */\nexport type IssueInput = {\n  readonly allow: SessionAllow;\n  /** The distinct agent that will use it. Issuer/holder separation is enforced. */\n  readonly holder: PublicKeyHandle;\n  readonly ttlSeconds?: number;\n  readonly maxDepth?: number;\n  readonly clearance?: Clearance;\n  readonly sessionId?: string;\n  readonly agentId?: string;\n  /** Approval policy for the issued execution session. Defaults to gating every issued tool. */\n  readonly requireApproval?: RequireApproval;\n};\n\n/** Public view of a session's leaf. Never includes the holder secret. */\nexport type SessionInfo = {\n  readonly kind: \"execution\" | \"issuer\";\n  /** Hex public key the leaf is bound to. */\n  readonly holderPublicKey: string;\n  /** Hex public key that signed the root of the chain. */\n  readonly rootPublicKey: string;\n  /** 0 for a root session, +1 per delegation. */\n  readonly depth: number;\n  /** Delegation ceiling in force for this leaf. */\n  readonly maxDepth: number;\n  /** True when `depth >= maxDepth`: cannot be narrowed further. */\n  readonly terminal: boolean;\n  /** Unix seconds. */\n  readonly expiresAt: number;\n  readonly tools: readonly string[];\n  /** Warrant ids, root first. */\n  readonly warrantIds: readonly string[];\n  /**\n   * True when this process holds the leaf's holder secret. False for a\n   * session issued or delegated to another agent: `toWire()` works,\n   * `execute` and `narrow` do not.\n   */\n  readonly canAuthorize: boolean;\n  readonly clearance?: number;\n  readonly sessionId?: string;\n  readonly agentId?: string;\n  readonly issuableTools?: readonly string[];\n  readonly maxIssueDepth?: number;\n  readonly requiredApprovers?: readonly string[];\n  readonly minApprovals?: number;\n  readonly approvalGatedTools: readonly string[];\n};\n\n/** One constrained argument in an `explain()` result. */\nexport type ExplainedField = {\n  readonly field: string;\n  /** Core constraint type name, e.g. `\"Subpath\"`, `\"Range\"`. */\n  readonly kind: string;\n  /** The constraint as core serializes it. */\n  readonly constraint: unknown;\n  /** Absent when the argument was not supplied. */\n  readonly value?: unknown;\n  readonly satisfied: boolean;\n  /** Stable machine-readable diagnostic, when the core can identify one. */\n  readonly reasonCode?: string;\n  readonly reason?: string;\n};\n\n/** What a session would decide for `tool(args)`, field by field. No proof-of-possession involved. */\nexport type Explanation = {\n  readonly tool: string;\n  readonly kind: \"execution\" | \"issuer\";\n  readonly outcome: \"allow\" | \"deny\";\n  readonly code?: TenuoErrorCode;\n  readonly field?: string;\n  readonly message?: string;\n  readonly toolGranted: boolean;\n  readonly fields: readonly ExplainedField[];\n  /** Arguments the session does not name. Zero-trust policies reject these. */\n  readonly unknownFields: readonly string[];\n  /** Constrained arguments the call did not supply. */\n  readonly missingFields: readonly string[];\n  readonly expired: boolean;\n  readonly expiresAt: number;\n  readonly chainValid: boolean;\n  readonly chainError?: TenuoErrorCode;\n};\n\nexport type DevRoot = {\n  readonly kind: \"dev-root\";\n  /**\n   * Required when `NODE_ENV` is unset or is not `development` / `test`.\n   * Unset `NODE_ENV` is not treated as development.\n   */\n  readonly allowInProduction?: boolean;\n};\n\n/** A stable issuer secret: this process is a control plane. */\nexport type IssuerKey = {\n  readonly kind: \"issuer-key\";\n  readonly secret: Uint8Array;\n};\n\nexport type PublicKeyHandle = {\n  readonly kind: \"public-key\";\n  readonly source: \"env\" | \"hex\" | \"bytes\";\n  readonly hex: string;\n};\n\nexport type WarrantPart = {\n  readonly payload_hex: string;\n  readonly signature_hex: string;\n};\n\nexport type SessionFromWireInput = {\n  readonly warrant: string | readonly string[] | readonly WarrantPart[];\n  readonly holderKey: Uint8Array;\n};\n\n/** Field-level (`{ path: under(\"/data\") }`) or per-capability (`{ read_file: { path: ... } }`). */\nexport type NarrowInput = AllowPolicy | SessionAllow;\n\nexport type CreateTenuoOptions = {\n  readonly trustedRoots?: readonly PublicKeyHandle[];\n  /**\n   * `devRoot()` for development; an `issuerKey*` for a control plane that\n   * mints with a stable key; a public key for a verifier. An issuer key\n   * trusts itself plus `trustedRoots`.\n   */\n  readonly root?: DevRoot | IssuerKey | PublicKeyHandle;\n  /** Published SignedRevocationList (hex or standard base64). Verified against a trusted root. */\n  readonly revocationList?: string | Uint8Array;\n  /** 32-byte holder seed used to sign verifier receipts. Runtime supplies this. */\n  readonly receiptSigner?: Uint8Array;\n};\n\nexport type ApprovalRequestSummary = {\n  readonly tool: string;\n  readonly required: number;\n  readonly received: number;\n};\n\nexport type Decision =\n  | { readonly outcome: \"allow\"; readonly args: Readonly<Record<string, unknown>> }\n  | { readonly outcome: \"deny\"; readonly code: TenuoErrorCode; readonly field?: string }\n  | { readonly outcome: \"approval_required\"; readonly request: ApprovalRequestSummary };\n\n// ---------------------------------------------------------------------------\n// Revocation and receipts\n// ---------------------------------------------------------------------------\n\nexport type RevocationListInput = {\n  readonly revoke: readonly string[];\n  /** Monotonic; verifiers refuse an older version. Default 1. */\n  readonly version?: number;\n};\n\nexport type RevocationListInfo = {\n  readonly version: number;\n  readonly issuedAt: number;\n  readonly issuerPublicKey: string;\n  readonly revokedIds: readonly string[];\n  readonly signatureValid: boolean;\n};\n\n/** Signature authenticity of a receipt. Not authorization. */\nexport type ReceiptInfo = {\n  readonly authentic: true;\n  /** Hex key the receipt is signed under — resolve against your own authorizer set. */\n  readonly signerKey: string;\n  readonly outcome: \"allow\" | \"deny\";\n  readonly action: string;\n  readonly decisionCode?: string;\n  readonly requestId: string;\n  readonly srlVersion?: number;\n  readonly srlHash?: string;\n  readonly requestHash?: string;\n  readonly policyDefinitionHash?: string;\n  readonly prevReceiptHash?: string;\n  readonly trustedRootsHash?: string;\n};\n\n/** Root-anchored receipt check: the embedded chain against trusted roots at decision time. */\nexport type ReceiptChainInfo = {\n  readonly signerKey: string;\n  readonly outcome: \"allow\" | \"deny\";\n  readonly decisionCode?: string;\n  readonly timestamp: number;\n  readonly chainValid: boolean;\n  readonly chainError?: string;\n  readonly corroboratesDenial?: boolean;\n  readonly rootIssuer?: string;\n  readonly leafHolder?: string;\n};\n\n// ---------------------------------------------------------------------------\n// Presenting authority across any boundary\n// ---------------------------------------------------------------------------\n\n/** Warrant chain plus proof-of-possession for one call. Transport-agnostic. */\nexport type PresentedCall = {\n  readonly warrant: string;\n  readonly signature: string;\n  readonly approvals?: readonly string[];\n};\n\nexport interface Session {\n  readonly [Symbol.toStringTag]: \"TenuoSession\";\n  /** Warrant tokens, root first. Does not include the holder secret. */\n  toWire(): readonly string[];\n  /** SHA-256 of `(warrant_id, tool, canonical args)`. App-level idempotency, not PoP. */\n  dedupKey(tool: string, args: Readonly<Record<string, unknown>>): string;\n  /** Holder public key, depth, ceiling, lifetime, tools. Never the secret. */\n  inspect(): SessionInfo;\n  /**\n   * Receipt helpers below are required for `createTenuo.runtime({ receipts:\n   * \"collect\" })`. Implementers that are not runtime sessions can return\n   * empty snapshots and `0` from acknowledge.\n   */\n  /**\n   * Receipts collected for this session and not yet drained. Empty when the\n   * session was not created by a Runtime with `receipts: \"collect\"`.\n   */\n  peekReceipts(): readonly string[];\n  /**\n   * Snapshot of collected receipts. Same as `peekReceipts`; nothing is removed\n   * until `acknowledgeReceipts`.\n   */\n  drainReceipts(): readonly string[];\n  /** Remove the first `count` pending receipts. */\n  acknowledgeReceipts(count: number): number;\n}\n\nexport interface Tenuo {\n  /**\n   * Wrap any `{ execute }` tool (Vercel AI SDK, Mastra, plain object).\n   * `parameters` / Zod stay on the inner tool and are never treated as authority.\n   */\n  tool<T extends { execute: (args: never) => unknown }>(\n    inner: T,\n    policy: ToolPolicy<Parameters<T[\"execute\"]>[0]>,\n  ): ProtectedTool<T>;\n  session(input: SessionInput): Session;\n  /** Import a warrant minted elsewhere (Rust / Python / another process). */\n  sessionFromWire(input: SessionFromWireInput): Session;\n  withSession<R>(session: Session, fn: () => R): R;\n  /**\n   * Child session with less authority. Without options the same holder keeps\n   * it; with `options.holder` it is delegated to another agent's key. Core\n   * rejects any child that is not within its parent before a token exists.\n   */\n  narrow(session: Session, allow: NarrowInput, options?: NarrowOptions): Session;\n  /**\n   * Mint an execution session from an issuer session, signed by the issuer\n   * session's holder. Core checks tools against `issuableTools`, constraints\n   * against `constraintBounds`, clearance, and issue depth. No root key.\n   */\n  issue(issuer: Session, input: IssueInput): Session;\n  /**\n   * Public key of the local issuer (dev root or issuer key). Other processes\n   * put it in `trustedRoots` to accept warrants this context mints.\n   */\n  issuerPublicKey(): PublicKeyHandle;\n  /** What the session would decide for `tool(args)`, field by field. Never runs the tool. */\n  explain(session: Session, tool: string, args: Readonly<Record<string, unknown>>): Explanation;\n  /** Everything an approval service needs to present `tool(args)` to a human. */\n  approvalRequest(session: Session, tool: string, args: Readonly<Record<string, unknown>>): ApprovalRequest;\n  /** Holder-signed proof that this session is the one asking for `tool(args)`. */\n  attestApprovalRequest(\n    session: Session,\n    tool: string,\n    args: Readonly<Record<string, unknown>>,\n  ): ApprovalContextAttestation;\n  /** Authorize locally, then produce warrant + proof-of-possession for another boundary to verify. */\n  present(\n    session: Session,\n    tool: string,\n    args: Readonly<Record<string, unknown>>,\n    options?: McpAttachOptions,\n  ): PresentedCall;\n  /**\n   * Verify a presented call at any boundary. Resolves with the authorized\n   * arguments; the tool must not run otherwise. `args` is the object already\n   * given to this function. A repeated key in the original JSON is not\n   * visible. Parse that text with `parseStrictJson` while it is still available.\n   */\n  verify(\n    presented: PresentedCall,\n    tool: string,\n    args: Readonly<Record<string, unknown>>,\n    options?: McpVerifyOptions,\n  ): Promise<Readonly<Record<string, unknown>>>;\n  /** Sign a revocation list with this context's issuer key. Load it with `revoke()` where this issuer is trusted. */\n  revocationList(input: RevocationListInput): string;\n  /** Load a published SignedRevocationList. Rust verifies the issuer against trusted roots. */\n  revoke(list: string | Uint8Array): void;\n  /** MCP `_meta.tenuo` attach / verify. No MCP SDK dependency. */\n  readonly mcp: TenuoMcp;\n  ready(): void;\n}\n\n/** Wire envelope Python and TypeScript both read from `params._meta`. */\nexport type TenuoMcpMeta = {\n  readonly tenuo: PresentedCall;\n};\n\nexport type McpAttachOptions = {\n  readonly approvals?: readonly (string | Uint8Array)[];\n  readonly onReceipt?: (receipt: string) => void | Promise<void>;\n  /**\n   * Correlation handle written to the receipt. Use whatever id the host\n   * already has — a JSON-RPC id, a trace or span id — so a receipt can be\n   * matched against your own logs. Not an identity: nothing enforces\n   * uniqueness, and distinguishing repeated calls is the receipt chain's job.\n   */\n  readonly requestId?: string;\n};\n\n/** Host ceiling and optional receipt hook on `mcp.handler()`. */\nexport type McpHandlerPolicy = {\n  readonly allow?: AllowPolicy;\n  readonly onReceipt?: (receipt: string) => void | Promise<void>;\n  readonly nonceStore?: NonceStore;\n  /**\n   * Isolated. Called when `nonceStore.checkAndRecord` throws or rejects.\n   * The client only ever sees \"Replay store unavailable\".\n   */\n  readonly onNonceStoreError?: (error: unknown) => void | Promise<void>;\n};\n\nexport type McpVerifyOptions = {\n  readonly allow?: AllowPolicy;\n  readonly onReceipt?: (receipt: string) => void | Promise<void>;\n  /**\n   * Opt-in exact-PoP replay check. `checkAndRecord` may return a Promise\n   * (Redis). A rejected Promise fails closed. In-memory stores do not work\n   * across processes. PoP v1 is otherwise replayable in-window, including\n   * envelopes that already carry approvals.\n   */\n  readonly nonceStore?: NonceStore;\n  /**\n   * Isolated. Called when `nonceStore.checkAndRecord` throws or rejects.\n   * The client only ever sees \"Replay store unavailable\".\n   */\n  readonly onNonceStoreError?: (error: unknown) => void | Promise<void>;\n  /**\n   * Correlation handle written to the receipt. Use whatever id the host\n   * already has — a JSON-RPC id, a trace or span id — so a receipt can be\n   * matched against your own logs. Not an identity: nothing enforces\n   * uniqueness, and distinguishing repeated calls is the receipt chain's job.\n   */\n  readonly requestId?: string;\n};\n\n/**\n * Returns true if the PoP is fresh and recorded; false if this exact token\n * was already consumed. Async stores (Redis) return `Promise<boolean>`.\n * `verify()` / handlers await the result. Never return a Promise from a\n * store that is only consulted synchronously — that used to fail open.\n */\nexport type NonceStore = {\n  checkAndRecord(popSignature: string): boolean | Promise<boolean>;\n};\n\nexport type McpCallParams = {\n  readonly name: string;\n  readonly arguments: Readonly<Record<string, unknown>>;\n  readonly _meta: TenuoMcpMeta;\n};\n\nexport type McpJsonRpcError = {\n  readonly code: -32602 | -32001 | -32002;\n  readonly message: string;\n  readonly data?: { readonly tenuo?: { readonly code: TenuoErrorCode } };\n};\n\nexport interface TenuoMcp {\n  /** Local authorize, then put warrant + PoP on `_meta.tenuo`. */\n  attach(\n    session: Session,\n    name: string,\n    args: Readonly<Record<string, unknown>>,\n    options?: McpAttachOptions,\n  ): McpCallParams;\n  /**\n   * Server path. Verifies a presented warrant + PoP against the object it was\n   * given. A repeated key in the original JSON is not visible: the host has\n   * already parsed `args`. Parse that text with `parseStrictJson` while it is\n   * still available. The tool handler must not run unless this returns.\n   */\n  verify(\n    name: string,\n    args: Readonly<Record<string, unknown>>,\n    meta: unknown,\n    options?: McpVerifyOptions,\n  ): Promise<Readonly<Record<string, unknown>>>;\n  /** Wrap a handler: verify from `extra._meta` / `extra.meta`, then execute. */\n  handler<TArgs extends Record<string, unknown>, TResult>(\n    name: string,\n    execute: (args: TArgs) => TResult | Promise<TResult>,\n  ): (\n    args: TArgs,\n    extra?: { readonly _meta?: unknown; readonly meta?: unknown },\n  ) => Promise<TResult>;\n  handler<TArgs extends Record<string, unknown>, TResult>(\n    name: string,\n    policy: McpHandlerPolicy,\n    execute: (args: TArgs) => TResult | Promise<TResult>,\n  ): (\n    args: TArgs,\n    extra?: { readonly _meta?: unknown; readonly meta?: unknown },\n  ) => Promise<TResult>;\n  jsonRpcError(error: unknown): McpJsonRpcError;\n}\n"]}
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA;;;;;GAKG","sourcesContent":["/**\n * Frozen public contract for `@tenuo/core`.\n *\n * Names and shapes here are the review surface — do not grow this file with\n * protocol vocabulary (`Warrant`, `mint`, `guard`) as the lead API.\n */\n\n/** Canonical kebab-case codes from Rust `ErrorCode::name()` / `Denial::code()`. */\nexport type ProtocolDenialCode =\n  | \"signature-invalid\"\n  | \"untrusted-root\"\n  | \"chain-broken\"\n  | \"depth-exceeded\"\n  | \"warrant-expired\"\n  | \"tool-not-authorized\"\n  | \"constraint-violation\"\n  | \"pop-signature-invalid\"\n  | \"approval-required\"\n  | \"insufficient-approvals\"\n  | \"warrant-revoked\";\n\n/** Legacy SCREAMING_SNAKE aliases accepted by existing TypeScript callers. */\nexport type LegacyTenuoErrorCode =\n  | \"TENUO_NOT_READY\"\n  | \"TENUO_CONFIGURATION\"\n  | \"TENUO_CONSTRAINT_VIOLATION\"\n  | \"TENUO_TOOL_NOT_AUTHORIZED\"\n  | \"TENUO_WARRANT_EXPIRED\"\n  | \"TENUO_UNTRUSTED_ROOT\"\n  | \"TENUO_INVALID_POP\"\n  | \"TENUO_SIGNATURE_INVALID\"\n  | \"TENUO_CHAIN_INVALID\"\n  | \"TENUO_DEPTH_EXCEEDED\"\n  | \"TENUO_REVOKED\"\n  | \"TENUO_APPROVAL_REQUIRED\"\n  | \"TENUO_INSUFFICIENT_APPROVALS\"\n  | \"TENUO_CANONICALIZATION\"\n  | \"TENUO_NOT_IMPLEMENTED\";\n\nexport type TenuoErrorCode = ProtocolDenialCode | LegacyTenuoErrorCode;\n\n// ---------------------------------------------------------------------------\n// Constraints. Every kind is evaluated in the Rust core; TypeScript only\n// builds the marker object. The set matches the core `Constraint` enum.\n// ---------------------------------------------------------------------------\n\n/** Path-traversal-safe prefix. Core evaluates this; TypeScript does not. */\nexport type UnderConstraint = {\n  readonly kind: \"under\";\n  readonly root: string;\n  /** Default true. */\n  readonly caseSensitive?: boolean;\n  /** Whether the root itself is allowed. Default true. */\n  readonly allowEqual?: boolean;\n};\n\nexport type EmailConstraint = {\n  readonly kind: \"email\";\n  readonly domain: string;\n};\n\nexport type MaxConstraint = {\n  readonly kind: \"max\";\n  readonly value: number;\n};\n\nexport type MinConstraint = {\n  readonly kind: \"min\";\n  readonly value: number;\n};\n\nexport type RangeConstraint = {\n  readonly kind: \"range\";\n  readonly min?: number;\n  readonly max?: number;\n  readonly minExclusive?: boolean;\n  readonly maxExclusive?: boolean;\n};\n\nexport type OneOfConstraint = {\n  readonly kind: \"oneOf\";\n  readonly values: readonly string[];\n};\n\nexport type NotOneOfConstraint = {\n  readonly kind: \"notOneOf\";\n  readonly values: readonly string[];\n};\n\nexport type PatternConstraint = {\n  readonly kind: \"pattern\";\n  readonly pattern: string;\n};\n\nexport type RegexConstraint = {\n  readonly kind: \"regex\";\n  readonly source: string;\n};\n\nexport type ExactConstraint = {\n  readonly kind: \"exact\";\n  readonly value: string | number | boolean;\n};\n\nexport type WildcardConstraint = {\n  readonly kind: \"wildcard\";\n};\n\nexport type CidrConstraint = {\n  readonly kind: \"cidr\";\n  readonly network: string;\n};\n\nexport type UrlPatternConstraint = {\n  readonly kind: \"urlPattern\";\n  readonly pattern: string;\n};\n\nexport type UrlSafeConstraint = {\n  readonly kind: \"urlSafe\";\n  readonly schemes?: readonly string[];\n  readonly allowDomains?: readonly string[];\n  readonly denyDomains?: readonly string[];\n};\n\nexport type ShlexConstraint = {\n  readonly kind: \"shlex\";\n  readonly allow: readonly string[];\n};\n\nexport type ContainsConstraint = {\n  readonly kind: \"contains\";\n  readonly values: readonly (string | number | boolean)[];\n};\n\nexport type SubsetConstraint = {\n  readonly kind: \"subset\";\n  readonly values: readonly (string | number | boolean)[];\n};\n\nexport type AnyOfConstraint = {\n  readonly kind: \"anyOf\";\n  readonly constraints: readonly ConstraintExpr[];\n};\n\nexport type AllConstraint = {\n  readonly kind: \"all\";\n  readonly constraints: readonly ConstraintExpr[];\n};\n\nexport type NotConstraint = {\n  readonly kind: \"not\";\n  readonly constraint: ConstraintExpr;\n};\n\nexport type CelConstraint = {\n  readonly kind: \"cel\";\n  readonly expression: string;\n};\n\nexport type ConstraintExpr =\n  | UnderConstraint\n  | EmailConstraint\n  | MaxConstraint\n  | MinConstraint\n  | RangeConstraint\n  | OneOfConstraint\n  | NotOneOfConstraint\n  | PatternConstraint\n  | RegexConstraint\n  | ExactConstraint\n  | WildcardConstraint\n  | CidrConstraint\n  | UrlPatternConstraint\n  | UrlSafeConstraint\n  | ShlexConstraint\n  | ContainsConstraint\n  | SubsetConstraint\n  | AnyOfConstraint\n  | AllConstraint\n  | NotConstraint\n  | CelConstraint;\n\n/** Per-argument allow policy. Not a Zod schema. */\nexport type AllowPolicy = {\n  readonly [field: string]: ConstraintExpr;\n};\n\n/**\n * Framework tool shape we wrap. No dependency on `ai` / Mastra.\n * `parameters` is host-schema (usually Zod) and is never treated as authority.\n */\nexport type ToolLike<\n  TArgs extends Record<string, unknown> = Record<string, unknown>,\n  TResult = unknown,\n> = {\n  readonly description?: string;\n  readonly parameters?: unknown;\n  execute: (args: TArgs, options?: unknown) => TResult | Promise<TResult>;\n};\n\ntype KeysOfUnion<T> = T extends unknown ? keyof T : never;\n\nexport type ToolPolicy<TArgs = undefined> = {\n  /**\n   * Host ceiling. AND'd with the session in Rust.\n   * Non-empty maps are zero-trust: every call argument must be named here.\n   * `{}` means no extra ceiling (session/warrant only). Required: a missing\n   * `allow` or an unknown policy key throws. `session({ tools })` refuses a\n   * tool whose `allow` is `{}` unless the session's own `allow` names that\n   * capability explicitly, because an empty capability in a warrant accepts\n   * any arguments.\n   */\n  readonly allow: [NonNullable<TArgs>] extends [object]\n    ? [KeysOfUnion<NonNullable<TArgs>>] extends [never]\n      ? AllowPolicy\n      : string extends KeysOfUnion<NonNullable<TArgs>>\n        ? AllowPolicy\n        : number extends KeysOfUnion<NonNullable<TArgs>>\n          ? AllowPolicy\n          : symbol extends KeysOfUnion<NonNullable<TArgs>>\n            ? AllowPolicy\n            : { readonly [Field in KeysOfUnion<NonNullable<TArgs>>]?: ConstraintExpr }\n    : AllowPolicy;\n  readonly capability?: string;\n  /**\n   * Makes approvals one-use for this tool. When a call that carried\n   * `approvals` is allowed, each approval envelope that matches the call is\n   * recorded here before the tool body runs; an envelope the store has\n   * already seen denies with `TENUO_INSUFFICIENT_APPROVALS`. Same\n   * `NonceStore` shape as the MCP verify path; `memoryNonceStore()` works\n   * for one process. The store must remember a key for as long as an\n   * approval can live (one hour by default), so give `memoryNonceStore()` a\n   * matching `ttlSeconds`. A store that throws, rejects, or returns a\n   * non-boolean fails closed with \"Replay store unavailable\".\n   */\n  readonly nonceStore?: NonceStore;\n  /** Isolated. Called when `nonceStore.checkAndRecord` throws or rejects. */\n  readonly onNonceStoreError?: (error: unknown) => void | Promise<void>;\n};\n\n/** Compile-time brand only — never assigned at runtime. Do not `in`/`has` this key. */\ndeclare const protectedBrand: unique symbol;\n\n/**\n * Tenuo's per-call options. Other keys pass through to the wrapped tool's own\n * `execute`, except keys that look like a misspelled Tenuo option\n * (`sesion`, `approval`, `onReciept`), which throw instead of being ignored.\n */\nexport type ExecuteOptions = {\n  readonly session?: Session;\n  /** Already-signed approval envelopes (hex, standard base64, or CBOR bytes). */\n  readonly approvals?: readonly (string | Uint8Array)[];\n  /**\n   * Signed evidence of the decision. Not a security hook.\n   * Exceptions (sync or rejected Promise) are isolated and never deny or\n   * fail the tool.\n   */\n  readonly onReceipt?: (receipt: string) => void | Promise<void>;\n  /**\n   * Correlation handle written to the receipt. Use whatever id the host\n   * already has — a JSON-RPC id, a trace or span id — so a receipt can be\n   * matched against your own logs. Not an identity: nothing enforces\n   * uniqueness, and distinguishing repeated calls is the receipt chain's job.\n   */\n  readonly requestId?: string;\n};\n\ntype ExtraExecuteOptions<T extends { execute: (args: never) => unknown }> =\n  T[\"execute\"] extends (args: never, options?: infer O) => unknown\n    ? unknown extends O\n      ? object\n      : Omit<NonNullable<O>, keyof ExecuteOptions>\n    : object;\n\n/** Wrapped tool. `execute` still authorizes; optional `{ session }` overrides ALS. */\nexport type ProtectedTool<T extends { execute: (args: never) => unknown }> = Omit<T, \"execute\"> & {\n  execute: (\n    args: Parameters<T[\"execute\"]>[0],\n    options?: ExecuteOptions & ExtraExecuteOptions<T>,\n  ) => Promise<Awaited<ReturnType<T[\"execute\"]>>>;\n  readonly [protectedBrand]: true;\n};\n\n// ---------------------------------------------------------------------------\n// Approvals\n// ---------------------------------------------------------------------------\n\n/** Per-argument trigger for an approval gate. */\nexport type ArgApprovalGate =\n  /** Every value of this argument fires the gate. */\n  | \"all\"\n  /** Only values satisfying the constraint fire the gate. */\n  | { readonly when: ConstraintExpr }\n  /** Every value except those satisfying the constraint fires the gate. Narrowable across delegation. */\n  | { readonly exempt: ConstraintExpr };\n\n/** Gate on one tool: a message for the approver and optional per-argument triggers. */\nexport type ToolApprovalGate = {\n  readonly message?: string;\n  /** Absent: the whole tool is gated. */\n  readonly args?: { readonly [field: string]: ArgApprovalGate };\n};\n\n/** Approval requirement. Host collects SignedApproval envelopes; Rust decides. */\nexport type RequireApproval = {\n  readonly approvers: readonly PublicKeyHandle[];\n  readonly min: number;\n  /** Whole-tool gates. Defaults to every tool in the session when `gates` is absent too. */\n  readonly tools?: readonly string[];\n  /** Per-tool gates with messages and per-argument triggers. */\n  readonly gates?: { readonly [tool: string]: ToolApprovalGate };\n};\n\n/** What an approval service needs to present a call to a human. Not a signed artifact. */\nexport type ApprovalRequest = {\n  readonly requestId: string;\n  readonly warrantId: string;\n  readonly tool: string;\n  readonly args: Readonly<Record<string, unknown>>;\n  /** Hex SHA-256 committing to warrant id, tool, canonical args, and holder. */\n  readonly requestHash: string;\n  readonly holderPublicKey: string;\n  readonly requiredApprovers: readonly string[];\n  readonly minApprovals: number;\n  /** Unix seconds. An approval cannot outlive the warrant. */\n  readonly warrantExpiresAt: number;\n  readonly createdAt: number;\n  readonly message: string;\n};\n\n/** Holder-signed statement that it is the one asking. Carried in a control-plane request. */\nexport type ApprovalContextAttestation = {\n  readonly version: number;\n  readonly canonicalization: string;\n  readonly warrantId: string;\n  readonly tool: string;\n  readonly requestHash: string;\n  readonly holderKeyHex: string;\n  readonly argsCanonicalCborB64: string;\n  readonly signerKeyHex: string;\n  readonly signatureB64: string;\n};\n\n/** Wire body for a control-plane approval API. Field names are the wire names. */\nexport type ControlPlaneApprovalRequestV1 = {\n  readonly schema_version: 1;\n  readonly request_id_hex: string;\n  readonly warrant_id: string;\n  readonly tool: string;\n  readonly arguments: Readonly<Record<string, unknown>>;\n  readonly request_hash_hex: string;\n  readonly holder_public_key_hex: string;\n  readonly required_approver_keys_hex: readonly string[];\n  readonly min_approvals: number;\n  readonly warrant_expires_at_unix: number;\n  readonly created_at_unix: number;\n  readonly attestation?: Readonly<Record<string, unknown>>;\n  readonly temporal?: Readonly<Record<string, string>>;\n  readonly message?: string;\n};\n\nexport type ControlPlaneApprovalResponseV1 = {\n  readonly status: string;\n  readonly signed_approvals_b64?: readonly string[];\n  readonly error?: string;\n  readonly server_request_id?: string;\n};\n\nexport type SignApprovalOptions = {\n  /** Who approved, in the approver system's own terms. Required. */\n  readonly externalId: string;\n  /** Approval lifetime. Default one hour, always clamped to the warrant's expiry when given. */\n  readonly ttlSeconds?: number;\n  readonly warrantExpiresAt?: number;\n};\n\n/** Decoded approval envelope. Not authorization. */\nexport type ApprovalInfo = {\n  readonly approverPublicKey: string;\n  readonly requestHash: string;\n  readonly externalId: string;\n  readonly approvedAt: number;\n  readonly expiresAt: number;\n  readonly expired: boolean;\n  readonly signatureValid: boolean;\n  readonly error?: string;\n};\n\n// ---------------------------------------------------------------------------\n// Sessions\n// ---------------------------------------------------------------------------\n\nexport type SessionAllow = {\n  readonly [capability: string]: AllowPolicy;\n};\n\n/** Named level or a number 0-255. Delegation can only lower it. */\nexport type Clearance =\n  | number\n  | \"untrusted\"\n  | \"external\"\n  | \"partner\"\n  | \"internal\"\n  | \"privileged\"\n  | \"system\";\n\nexport type SessionInput = {\n  /** Capability map. Optional when `tools` is set. Issuer sessions may omit it. */\n  readonly allow?: SessionAllow;\n  /** Wrapped tools from `tenuo.tool()`. Their `allow` is minted into the session. */\n  readonly tools?: readonly object[];\n  readonly ttlSeconds?: number;\n  readonly requireApproval?: RequireApproval;\n  /**\n   * Issue to another agent's key instead of a fresh local holder. The\n   * returned session cannot authorize here (it has no holder secret); send\n   * `toWire()` to that agent, which imports it with `sessionFromWire()`.\n   */\n  readonly holder?: PublicKeyHandle;\n  /**\n   * How many times this authority may be delegated below the root.\n   * `0` makes the session terminal. Omit for the protocol maximum.\n   * Delegation can lower this ceiling and never raise it.\n   */\n  readonly maxDepth?: number;\n  /**\n   * `\"execution\"` (default) can call tools. `\"issuer\"` cannot call tools; its\n   * holder can mint execution sessions with `tenuo.issue()` for the tools in\n   * `issuableTools`, within `constraintBounds`, without the root key.\n   */\n  readonly kind?: \"execution\" | \"issuer\";\n  readonly clearance?: Clearance;\n  /** Free-form task correlation id. Inherited unchanged through delegation. */\n  readonly sessionId?: string;\n  /** Free-form agent label. Delegation may change it. */\n  readonly agentId?: string;\n  /** Issuer sessions only. */\n  readonly issuableTools?: readonly string[];\n  /** Issuer sessions only: ceiling on the constraints of anything issued, by field. */\n  readonly constraintBounds?: AllowPolicy;\n  /** Issuer sessions only: how deep issued sessions may themselves delegate. */\n  readonly maxIssueDepth?: number;\n};\n\n/** Options for `tenuo.narrow()`. All optional; the default keeps the holder. */\nexport type NarrowOptions = {\n  /**\n   * Bind the child to another agent's key. This is delegation: the current\n   * holder signs, the child belongs to `holder`, and the returned session\n   * cannot authorize here. Hand `toWire()` to that agent.\n   */\n  readonly holder?: PublicKeyHandle;\n  /**\n   * Child lifetime. A value longer than the parent has left is clamped to the\n   * parent's expiry, not rejected: the child never outlives the parent.\n   */\n  readonly ttlSeconds?: number;\n  /** The child's holder cannot delegate further. */\n  readonly terminal?: boolean;\n  /** Lower the delegation ceiling. Cannot exceed the parent's. */\n  readonly maxDepth?: number;\n  /** Lower the clearance. Cannot exceed the parent's. */\n  readonly clearance?: Clearance;\n  readonly agentId?: string;\n  /** Approvers can only be added. */\n  readonly addApprovers?: readonly PublicKeyHandle[];\n  /** The threshold can only go up. A value below the parent's throws. */\n  readonly minApprovals?: number;\n};\n\n/** Options for `tenuo.issue()`: an execution session minted from an issuer session. */\nexport type IssueInput = {\n  readonly allow: SessionAllow;\n  /** The distinct agent that will use it. Issuer/holder separation is enforced. */\n  readonly holder: PublicKeyHandle;\n  readonly ttlSeconds?: number;\n  readonly maxDepth?: number;\n  readonly clearance?: Clearance;\n  readonly sessionId?: string;\n  readonly agentId?: string;\n  /** Approval policy for the issued execution session. Defaults to gating every issued tool. */\n  readonly requireApproval?: RequireApproval;\n};\n\n/** Public view of a session's leaf. Never includes the holder secret. */\nexport type SessionInfo = {\n  readonly kind: \"execution\" | \"issuer\";\n  /** Hex public key the leaf is bound to. */\n  readonly holderPublicKey: string;\n  /** Hex public key that signed the root of the chain. */\n  readonly rootPublicKey: string;\n  /** 0 for a root session, +1 per delegation. */\n  readonly depth: number;\n  /** Delegation ceiling in force for this leaf. */\n  readonly maxDepth: number;\n  /** True when `depth >= maxDepth`: cannot be narrowed further. */\n  readonly terminal: boolean;\n  /** Unix seconds. */\n  readonly expiresAt: number;\n  readonly tools: readonly string[];\n  /** Warrant ids, root first. */\n  readonly warrantIds: readonly string[];\n  /**\n   * True when this process holds the leaf's holder secret. False for a\n   * session issued or delegated to another agent: `toWire()` works,\n   * `execute` and `narrow` do not.\n   */\n  readonly canAuthorize: boolean;\n  readonly clearance?: number;\n  readonly sessionId?: string;\n  readonly agentId?: string;\n  readonly issuableTools?: readonly string[];\n  readonly maxIssueDepth?: number;\n  readonly requiredApprovers?: readonly string[];\n  readonly minApprovals?: number;\n  readonly approvalGatedTools: readonly string[];\n};\n\n/** One constrained argument in an `explain()` result. */\nexport type ExplainedField = {\n  readonly field: string;\n  /** Core constraint type name, e.g. `\"Subpath\"`, `\"Range\"`. */\n  readonly kind: string;\n  /** The constraint as core serializes it. */\n  readonly constraint: unknown;\n  /** Absent when the argument was not supplied. */\n  readonly value?: unknown;\n  readonly satisfied: boolean;\n  /** Stable machine-readable diagnostic, when the core can identify one. */\n  readonly reasonCode?: string;\n  readonly reason?: string;\n};\n\n/** What a session would decide for `tool(args)`, field by field. No proof-of-possession involved. */\nexport type Explanation = {\n  readonly tool: string;\n  readonly kind: \"execution\" | \"issuer\";\n  readonly outcome: \"allow\" | \"deny\";\n  readonly code?: TenuoErrorCode;\n  readonly field?: string;\n  readonly message?: string;\n  readonly toolGranted: boolean;\n  readonly fields: readonly ExplainedField[];\n  /** Arguments the session does not name. Zero-trust policies reject these. */\n  readonly unknownFields: readonly string[];\n  /** Constrained arguments the call did not supply. */\n  readonly missingFields: readonly string[];\n  readonly expired: boolean;\n  readonly expiresAt: number;\n  readonly chainValid: boolean;\n  readonly chainError?: TenuoErrorCode;\n};\n\nexport type DevRoot = {\n  readonly kind: \"dev-root\";\n  /**\n   * Required when `NODE_ENV` is unset or is not `development` / `test`.\n   * Unset `NODE_ENV` is not treated as development.\n   */\n  readonly allowInProduction?: boolean;\n};\n\n/** A stable issuer secret: this process is a control plane. */\nexport type IssuerKey = {\n  readonly kind: \"issuer-key\";\n  readonly secret: Uint8Array;\n};\n\nexport type PublicKeyHandle = {\n  readonly kind: \"public-key\";\n  readonly source: \"env\" | \"hex\" | \"bytes\";\n  readonly hex: string;\n};\n\nexport type WarrantPart = {\n  readonly payload_hex: string;\n  readonly signature_hex: string;\n};\n\nexport type SessionFromWireInput = {\n  readonly warrant: string | readonly string[] | readonly WarrantPart[];\n  readonly holderKey: Uint8Array;\n};\n\n/** Field-level (`{ path: under(\"/data\") }`) or per-capability (`{ read_file: { path: ... } }`). */\nexport type NarrowInput = AllowPolicy | SessionAllow;\n\nexport type CreateTenuoOptions = {\n  readonly trustedRoots?: readonly PublicKeyHandle[];\n  /**\n   * `devRoot()` for development; an `issuerKey*` for a control plane that\n   * mints with a stable key; a public key for a verifier. An issuer key\n   * trusts itself plus `trustedRoots`.\n   */\n  readonly root?: DevRoot | IssuerKey | PublicKeyHandle;\n  /** Published SignedRevocationList (hex or standard base64). Verified against a trusted root. */\n  readonly revocationList?: string | Uint8Array;\n  /** 32-byte holder seed used to sign verifier receipts. Runtime supplies this. */\n  readonly receiptSigner?: Uint8Array;\n};\n\nexport type ApprovalRequestSummary = {\n  readonly tool: string;\n  readonly required: number;\n  readonly received: number;\n};\n\nexport type Decision =\n  | { readonly outcome: \"allow\"; readonly args: Readonly<Record<string, unknown>> }\n  | { readonly outcome: \"deny\"; readonly code: TenuoErrorCode; readonly field?: string }\n  | { readonly outcome: \"approval_required\"; readonly request: ApprovalRequestSummary };\n\n// ---------------------------------------------------------------------------\n// Revocation and receipts\n// ---------------------------------------------------------------------------\n\nexport type RevocationListInput = {\n  readonly revoke: readonly string[];\n  /** Monotonic; verifiers refuse an older version. Default 1. */\n  readonly version?: number;\n};\n\nexport type RevocationListInfo = {\n  readonly version: number;\n  readonly issuedAt: number;\n  readonly issuerPublicKey: string;\n  readonly revokedIds: readonly string[];\n  readonly signatureValid: boolean;\n};\n\n/** Signature authenticity of a receipt. Not authorization. */\nexport type ReceiptInfo = {\n  readonly authentic: true;\n  /** Hex key the receipt is signed under — resolve against your own authorizer set. */\n  readonly signerKey: string;\n  readonly outcome: \"allow\" | \"deny\";\n  readonly action: string;\n  readonly decisionCode?: string;\n  readonly requestId: string;\n  readonly srlVersion?: number;\n  readonly srlHash?: string;\n  readonly requestHash?: string;\n  readonly policyDefinitionHash?: string;\n  readonly prevReceiptHash?: string;\n  readonly trustedRootsHash?: string;\n};\n\n/** Root-anchored receipt check: the embedded chain against trusted roots at decision time. */\nexport type ReceiptChainInfo = {\n  readonly signerKey: string;\n  readonly outcome: \"allow\" | \"deny\";\n  readonly decisionCode?: string;\n  readonly timestamp: number;\n  readonly chainValid: boolean;\n  readonly chainError?: string;\n  readonly corroboratesDenial?: boolean;\n  readonly rootIssuer?: string;\n  readonly leafHolder?: string;\n};\n\n// ---------------------------------------------------------------------------\n// Presenting authority across any boundary\n// ---------------------------------------------------------------------------\n\n/** Warrant chain plus proof-of-possession for one call. Transport-agnostic. */\nexport type PresentedCall = {\n  readonly warrant: string;\n  readonly signature: string;\n  readonly approvals?: readonly string[];\n};\n\nexport interface Session {\n  readonly [Symbol.toStringTag]: \"TenuoSession\";\n  /** Warrant tokens, root first. Does not include the holder secret. */\n  toWire(): readonly string[];\n  /**\n   * The whole chain as one string: a CBOR warrant stack in URL-safe base64,\n   * the same encoding as `PresentedCall.warrant`. Use it where only a single\n   * string fits (an environment variable, a header). `sessionFromWire()`\n   * imports it. Does not include the holder secret.\n   */\n  toWireString(): string;\n  /** SHA-256 of `(warrant_id, tool, canonical args)`. App-level idempotency, not PoP. */\n  dedupKey(tool: string, args: Readonly<Record<string, unknown>>): string;\n  /** Holder public key, depth, ceiling, lifetime, tools. Never the secret. */\n  inspect(): SessionInfo;\n  /**\n   * Receipt helpers below are required for `createTenuo.runtime({ receipts:\n   * \"collect\" })`. Implementers that are not runtime sessions can return\n   * empty snapshots and `0` from acknowledge.\n   */\n  /**\n   * Receipts collected for this session and not yet drained. Empty when the\n   * session was not created by a Runtime with `receipts: \"collect\"`.\n   */\n  peekReceipts(): readonly string[];\n  /**\n   * Snapshot of collected receipts. Same as `peekReceipts`; nothing is removed\n   * until `acknowledgeReceipts`.\n   */\n  drainReceipts(): readonly string[];\n  /** Remove the first `count` pending receipts. */\n  acknowledgeReceipts(count: number): number;\n}\n\nexport interface Tenuo {\n  /**\n   * Wrap any `{ execute }` tool (Vercel AI SDK, Mastra, plain object).\n   * `parameters` / Zod stay on the inner tool and are never treated as authority.\n   */\n  tool<T extends { execute: (args: never) => unknown }>(\n    inner: T,\n    policy: ToolPolicy<Parameters<T[\"execute\"]>[0]>,\n  ): ProtectedTool<T>;\n  session(input: SessionInput): Session;\n  /** Import a warrant minted elsewhere (Rust / Python / another process). */\n  sessionFromWire(input: SessionFromWireInput): Session;\n  withSession<R>(session: Session, fn: () => R): R;\n  /**\n   * Child session with less authority. Without options the same holder keeps\n   * it; with `options.holder` it is delegated to another agent's key. Core\n   * rejects any child that is not within its parent before a token exists.\n   */\n  narrow(session: Session, allow: NarrowInput, options?: NarrowOptions): Session;\n  /**\n   * Mint an execution session from an issuer session, signed by the issuer\n   * session's holder. Core checks tools against `issuableTools`, constraints\n   * against `constraintBounds`, clearance, and issue depth. No root key.\n   */\n  issue(issuer: Session, input: IssueInput): Session;\n  /**\n   * Public key of the local issuer (dev root or issuer key). Other processes\n   * put it in `trustedRoots` to accept warrants this context mints.\n   */\n  issuerPublicKey(): PublicKeyHandle;\n  /** What the session would decide for `tool(args)`, field by field. Never runs the tool. */\n  explain(session: Session, tool: string, args: Readonly<Record<string, unknown>>): Explanation;\n  /** Everything an approval service needs to present `tool(args)` to a human. */\n  approvalRequest(session: Session, tool: string, args: Readonly<Record<string, unknown>>): ApprovalRequest;\n  /** Holder-signed proof that this session is the one asking for `tool(args)`. */\n  attestApprovalRequest(\n    session: Session,\n    tool: string,\n    args: Readonly<Record<string, unknown>>,\n  ): ApprovalContextAttestation;\n  /** Authorize locally, then produce warrant + proof-of-possession for another boundary to verify. */\n  present(\n    session: Session,\n    tool: string,\n    args: Readonly<Record<string, unknown>>,\n    options?: McpAttachOptions,\n  ): PresentedCall;\n  /**\n   * Verify a presented call at any boundary. Resolves with the authorized\n   * arguments; the tool must not run otherwise. `args` is the object already\n   * given to this function. A repeated key in the original JSON is not\n   * visible. Parse that text with `parseStrictJson` while it is still available.\n   */\n  verify(\n    presented: PresentedCall,\n    tool: string,\n    args: Readonly<Record<string, unknown>>,\n    options?: McpVerifyOptions,\n  ): Promise<Readonly<Record<string, unknown>>>;\n  /** Sign a revocation list with this context's issuer key. Load it with `revoke()` where this issuer is trusted. */\n  revocationList(input: RevocationListInput): string;\n  /** Load a published SignedRevocationList. Rust verifies the issuer against trusted roots. */\n  revoke(list: string | Uint8Array): void;\n  /** MCP `_meta.tenuo` attach / verify. No MCP SDK dependency. */\n  readonly mcp: TenuoMcp;\n  ready(): void;\n}\n\n/** Wire envelope Python and TypeScript both read from `params._meta`. */\nexport type TenuoMcpMeta = {\n  readonly tenuo: PresentedCall;\n};\n\nexport type McpAttachOptions = {\n  readonly approvals?: readonly (string | Uint8Array)[];\n  readonly onReceipt?: (receipt: string) => void | Promise<void>;\n  /**\n   * Correlation handle written to the receipt. Use whatever id the host\n   * already has — a JSON-RPC id, a trace or span id — so a receipt can be\n   * matched against your own logs. Not an identity: nothing enforces\n   * uniqueness, and distinguishing repeated calls is the receipt chain's job.\n   */\n  readonly requestId?: string;\n};\n\n/** Host ceiling and optional receipt hook on `mcp.handler()`. */\nexport type McpHandlerPolicy = {\n  readonly allow?: AllowPolicy;\n  readonly onReceipt?: (receipt: string) => void | Promise<void>;\n  readonly nonceStore?: NonceStore;\n  /**\n   * Isolated. Called when `nonceStore.checkAndRecord` throws or rejects.\n   * The client only ever sees \"Replay store unavailable\".\n   */\n  readonly onNonceStoreError?: (error: unknown) => void | Promise<void>;\n};\n\nexport type McpVerifyOptions = {\n  readonly allow?: AllowPolicy;\n  readonly onReceipt?: (receipt: string) => void | Promise<void>;\n  /**\n   * Opt-in exact-PoP replay check. `checkAndRecord` may return a Promise\n   * (Redis). A rejected Promise fails closed. In-memory stores do not work\n   * across processes. PoP v1 is otherwise replayable in-window, including\n   * envelopes that already carry approvals.\n   */\n  readonly nonceStore?: NonceStore;\n  /**\n   * Isolated. Called when `nonceStore.checkAndRecord` throws or rejects.\n   * The client only ever sees \"Replay store unavailable\".\n   */\n  readonly onNonceStoreError?: (error: unknown) => void | Promise<void>;\n  /**\n   * Correlation handle written to the receipt. Use whatever id the host\n   * already has — a JSON-RPC id, a trace or span id — so a receipt can be\n   * matched against your own logs. Not an identity: nothing enforces\n   * uniqueness, and distinguishing repeated calls is the receipt chain's job.\n   */\n  readonly requestId?: string;\n};\n\n/**\n * Returns true if the PoP is fresh and recorded; false if this exact token\n * was already consumed. Async stores (Redis) return `Promise<boolean>`.\n * `verify()` / handlers await the result. Never return a Promise from a\n * store that is only consulted synchronously — that used to fail open.\n */\nexport type NonceStore = {\n  checkAndRecord(popSignature: string): boolean | Promise<boolean>;\n};\n\nexport type McpCallParams = {\n  readonly name: string;\n  readonly arguments: Readonly<Record<string, unknown>>;\n  readonly _meta: TenuoMcpMeta;\n};\n\nexport type McpJsonRpcError = {\n  readonly code: -32602 | -32001 | -32002;\n  readonly message: string;\n  readonly data?: { readonly tenuo?: { readonly code: TenuoErrorCode } };\n};\n\nexport interface TenuoMcp {\n  /** Local authorize, then put warrant + PoP on `_meta.tenuo`. */\n  attach(\n    session: Session,\n    name: string,\n    args: Readonly<Record<string, unknown>>,\n    options?: McpAttachOptions,\n  ): McpCallParams;\n  /**\n   * Server path. Verifies a presented warrant + PoP against the object it was\n   * given. A repeated key in the original JSON is not visible: the host has\n   * already parsed `args`. Parse that text with `parseStrictJson` while it is\n   * still available. The tool handler must not run unless this returns.\n   */\n  verify(\n    name: string,\n    args: Readonly<Record<string, unknown>>,\n    meta: unknown,\n    options?: McpVerifyOptions,\n  ): Promise<Readonly<Record<string, unknown>>>;\n  /** Wrap a handler: verify from `extra._meta` / `extra.meta`, then execute. */\n  handler<TArgs extends Record<string, unknown>, TResult>(\n    name: string,\n    execute: (args: TArgs) => TResult | Promise<TResult>,\n  ): (\n    args: TArgs,\n    extra?: { readonly _meta?: unknown; readonly meta?: unknown },\n  ) => Promise<TResult>;\n  handler<TArgs extends Record<string, unknown>, TResult>(\n    name: string,\n    policy: McpHandlerPolicy,\n    execute: (args: TArgs) => TResult | Promise<TResult>,\n  ): (\n    args: TArgs,\n    extra?: { readonly _meta?: unknown; readonly meta?: unknown },\n  ) => Promise<TResult>;\n  jsonRpcError(error: unknown): McpJsonRpcError;\n}\n"]}

package/dist/build-info.json

@@ -1,8 +1,8 @@
 {
   "package": "@tenuo/core",
-  "version": "0.3.2-beta.0",
-  "sourceCommit": "7f27c7d4782f8f19ec15313e09ab95883a1da811",
+  "version": "0.3.3-beta.0",
+  "sourceCommit": "6d0b668f3d4d4da137967624eee5e307462ded54",
   "sourceClean": false,
-  "wasmSha256": "071de0080d616e5519841930f0579e5234a93a9f29724595609744d43b7e9d4a",
+  "wasmSha256": "7fb51e3beda0f2f0cb91863456d22ecc9b139fdfa869e65dead03b315adc3c22",
   "wasmMatchesCommit": false
 }

package/dist/client.js

@@ -3,12 +3,40 @@ import { randomBytes } from "node:crypto";
 import { parseConnectToken } from "./connect.js";
 import { generateIdentity, identityFromKey } from "./identity.js";
 import { createMcp, presentCall, verifyPresented } from "./mcp.js";
+import { consumeApprovals, snapshotApprovals } from "./replay.js";
 import { collectReceipt, emitIsolatedReceipt, inheritSessionCollector } from "./receipts.js";
 import { createRuntime } from "./runtime.js";
 import { AuthorizationDeniedError, ApprovalRequiredError, TenuoConfigurationError, TenuoError } from "./errors.js";
 import { Session, isSession, nativeSession } from "./session.js";
 import { createDevContext, createIssuerContext, createVerifierContext, importSessionFromChain, importSessionFromWire, loadWasm, protocolLimits, publicKeyHexFromHolderKey, } from "./wasm.js";
 const currentSession = new AsyncLocalStorage();
+const TOOL_POLICY_KEYS = ["allow", "capability", "nonceStore", "onNonceStoreError"];
+const EXECUTE_OPTION_KEYS = ["session", "approvals", "onReceipt", "requestId"];
+const SESSION_INPUT_KEYS = [
+    "allow",
+    "tools",
+    "ttlSeconds",
+    "requireApproval",
+    "holder",
+    "maxDepth",
+    "kind",
+    "clearance",
+    "sessionId",
+    "agentId",
+    "issuableTools",
+    "constraintBounds",
+    "maxIssueDepth",
+];
+const ISSUE_INPUT_KEYS = [
+    "allow",
+    "holder",
+    "ttlSeconds",
+    "maxDepth",
+    "clearance",
+    "sessionId",
+    "agentId",
+    "requireApproval",
+];
 const toolPolicies = new WeakMap();
 const wrappedInners = new WeakSet();
 const CLEARANCE_NAMES = new Set(["untrusted", "external", "partner", "internal", "privileged", "system"]);
@@ -226,7 +254,12 @@ class TenuoClient {
             this.canMint = false;
         }
         if (options.revocationList !== undefined) {
-            this.context.loadRevocationList(normalizeWireBytes(options.revocationList));
+            try {
+                this.context.loadRevocationList(normalizeWireBytes(options.revocationList));
+            }
+            catch (error) {
+                throw revocationLoadError(error);
+            }
         }
         this.decide = (decision, tool, native, args) => {
             this.applyDecision(decision, tool, native, args);
@@ -255,14 +288,20 @@ class TenuoClient {
         if (toolPolicies.has(inner) || wrappedInners.has(inner)) {
             throw new TenuoConfigurationError("tenuo.tool() already wrapped this tool");
         }
+        const { nonceStore, onNonceStoreError } = validateToolPolicy(policy);
         const capability = capabilityName(inner, policy);
         const original = inner.execute;
         const execute = async (args, callOptions) => {
+            assertExecuteOptions(callOptions);
             const session = resolveSession(callOptions);
             const native = nativeSession(session);
-            const decision = this.context.authorize(native, capability, args, approvalsFrom(callOptions), policy.allow, requestIdFrom(callOptions));
+            const approvals = snapshotApprovals(approvalsFrom(callOptions));
+            const decision = this.context.authorize(native, capability, args, approvals, policy.allow, requestIdFrom(callOptions));
             emitReceipt(callOptions, decision.receipt, session, this);
             if (decision.outcome === "allow") {
+                if (nonceStore !== undefined) {
+                    await consumeApprovals(nonceStore, approvals, this.requestHash(native, capability, decision.args), capability, onNonceStoreError);
+                }
                 return original(plainArgs(decision.args), forwardExecuteOptions(callOptions));
             }
             this.applyDecision(decision, capability, native, plainArgs(args));
@@ -275,7 +314,20 @@ class TenuoClient {
         toolPolicies.set(wrapped, { capability, allow: { ...policy.allow } });
         return wrapped;
     }
+    /** The approval request hash for this call; approvals are bound to it. */
+    requestHash(native, tool, args) {
+        try {
+            return this.context.approvalRequest(native, tool, plainArgs(args)).request_hash;
+        }
+        catch (error) {
+            throw new TenuoConfigurationError(`could not bind approvals to this call: ${errorMessage(error)}`);
+        }
+    }
     session(input) {
+        if (input === null || typeof input !== "object") {
+            throw new TenuoConfigurationError("tenuo.session() requires an options object");
+        }
+        assertKnownInputKeys(input, SESSION_INPUT_KEYS, "tenuo.session()");
         const allow = collectSessionAllow(input);
         const kind = input.kind ?? "execution";
         if (kind !== "execution" && kind !== "issuer") {
@@ -289,7 +341,7 @@ class TenuoClient {
         }
         const options = { kind, allow };
         if (input.ttlSeconds !== undefined) {
-            options.ttlSeconds = requireTtl(input.ttlSeconds, "session().ttlSeconds");
+            options.ttlSeconds = requireTtl(input.ttlSeconds, "session().ttlSeconds", 1);
         }
         if (input.holder !== undefined) {
             options.holder = requirePublicKey(input.holder, "session().holder").hex;
@@ -332,6 +384,7 @@ class TenuoClient {
         if (input === null || typeof input !== "object" || input.allow === undefined || Object.keys(input.allow).length === 0) {
             throw new TenuoConfigurationError("issue() requires at least one capability in allow");
         }
+        assertKnownInputKeys(input, ISSUE_INPUT_KEYS, "issue()");
         const options = {
             allow: input.allow,
             holder: requirePublicKey(input.holder, "issue().holder").hex,
@@ -374,6 +427,10 @@ class TenuoClient {
         if (typeof input.warrant === "string" && input.warrant.trim().length === 0) {
             throw new TenuoConfigurationError("sessionFromWire() requires a warrant");
         }
+        // Warrant strings are hex or base64; none of these characters occur in one.
+        if (typeof input.warrant === "string" && /^\[|[\s,.;]/.test(input.warrant.trim())) {
+            throw new TenuoConfigurationError("sessionFromWire() got a string that looks like several warrant tokens joined together. Pass the array from session.toWire(), or the single string from session.toWireString().");
+        }
         try {
             if (typeof input.warrant === "string") {
                 return new Session(importSessionFromWire(input.warrant, input.holderKey));
@@ -401,6 +458,12 @@ class TenuoClient {
             throw new TenuoConfigurationError("narrow() requires a Tenuo Session, not a plain object");
         }
         const native = options === undefined ? undefined : narrowOptionsJson(options);
+        if (native?.minApprovals !== undefined) {
+            const parentMin = session.inspect().minApprovals;
+            if (parentMin !== undefined && native.minApprovals < parentMin) {
+                throw new TenuoConfigurationError(`narrow().minApprovals ${native.minApprovals} is below the parent's ${parentMin}. The approval threshold can only go up.`);
+            }
+        }
         try {
             const child = new Session(this.context.narrow(nativeSession(session), allow, native));
             inheritSessionCollector(session, child);
@@ -521,7 +584,12 @@ class TenuoClient {
         }
     }
     revoke(list) {
-        this.context.loadRevocationList(normalizeWireBytes(list));
+        try {
+            this.context.loadRevocationList(normalizeWireBytes(list));
+        }
+        catch (error) {
+            throw revocationLoadError(error);
+        }
     }
     ready() {
         loadWasm();
@@ -533,6 +601,100 @@ function requireLabel(value, name) {
     }
     return value;
 }
+function validateToolPolicy(policy) {
+    if (policy === null || typeof policy !== "object" || Array.isArray(policy)) {
+        throw new TenuoConfigurationError("tenuo.tool() requires a policy object: { allow, capability? }");
+    }
+    assertKnownInputKeys(policy, TOOL_POLICY_KEYS, "tenuo.tool() policy");
+    const record = policy;
+    if (record.allow === undefined) {
+        throw new TenuoConfigurationError("tenuo.tool() policy requires allow: name each argument with a constraint, or pass {} for no host ceiling");
+    }
+    if (record.allow === null || typeof record.allow !== "object" || Array.isArray(record.allow)) {
+        throw new TenuoConfigurationError("tenuo.tool() policy.allow must be an object of per-argument constraints");
+    }
+    const out = {};
+    if (record.nonceStore !== undefined) {
+        const store = record.nonceStore;
+        if (store === null || typeof store !== "object" || typeof store.checkAndRecord !== "function") {
+            throw new TenuoConfigurationError("tenuo.tool() policy.nonceStore must implement checkAndRecord()");
+        }
+        out.nonceStore = record.nonceStore;
+    }
+    if (record.onNonceStoreError !== undefined) {
+        if (typeof record.onNonceStoreError !== "function") {
+            throw new TenuoConfigurationError("tenuo.tool() policy.onNonceStoreError must be a function");
+        }
+        out.onNonceStoreError = record.onNonceStoreError;
+    }
+    return out;
+}
+function assertKnownInputKeys(value, known, label) {
+    for (const key of Object.keys(value)) {
+        if (!known.includes(key)) {
+            throw new TenuoConfigurationError(`${label}: unknown key '${key}' (expected ${known.join(", ")})`);
+        }
+    }
+}
+/**
+ * Execute options are shared with the wrapped tool, so unknown keys pass
+ * through. A key that is a near miss of a Tenuo option is a typo that would
+ * otherwise drop that option silently (`sesion` falls back to the ambient
+ * session), so it throws.
+ */
+function assertExecuteOptions(callOptions) {
+    if (callOptions === null || typeof callOptions !== "object") {
+        return;
+    }
+    for (const key of Object.keys(callOptions)) {
+        if (EXECUTE_OPTION_KEYS.includes(key)) {
+            continue;
+        }
+        const lower = key.toLowerCase();
+        for (const known of EXECUTE_OPTION_KEYS) {
+            const target = known.toLowerCase();
+            const limit = known.length <= 7 ? 1 : 2;
+            if (lower === target || editDistance(lower, target) <= limit) {
+                throw new TenuoConfigurationError(`execute() options: unknown key '${key}'. Did you mean '${known}'? Tenuo options are ${EXECUTE_OPTION_KEYS.join(", ")}.`);
+            }
+        }
+    }
+}
+/** Optimal string alignment distance (adjacent transpositions count once). */
+function editDistance(a, b) {
+    if (Math.abs(a.length - b.length) > 2) {
+        return 3;
+    }
+    const d = Array.from({ length: a.length + 1 }, (_, i) => Array.from({ length: b.length + 1 }, (_, j) => (i === 0 ? j : j === 0 ? i : 0)));
+    for (let i = 1; i <= a.length; i += 1) {
+        for (let j = 1; j <= b.length; j += 1) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            let best = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + cost);
+            if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+                best = Math.min(best, d[i - 2][j - 2] + 1);
+            }
+            d[i][j] = best;
+        }
+    }
+    return d[a.length][b.length];
+}
+function revocationLoadError(error) {
+    if (error instanceof TenuoError) {
+        return error;
+    }
+    // Strip the prefix the core adds so the code reflects the actual cause.
+    const message = errorMessage(error).replace(/^TENUO_[A-Z_]+:\s*/, "");
+    if (/rollback/i.test(message)) {
+        return new TenuoConfigurationError(message);
+    }
+    if (/issuer does not match|untrusted|not trusted/i.test(message)) {
+        return new TenuoConfigurationError(message, "TENUO_UNTRUSTED_ROOT");
+    }
+    if (/signature/i.test(message)) {
+        return new TenuoConfigurationError(message, "TENUO_SIGNATURE_INVALID");
+    }
+    return new TenuoConfigurationError(message);
+}
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
@@ -781,6 +943,9 @@ function collectSessionAllow(input) {
         if (policy === undefined) {
             throw new TenuoConfigurationError("session({ tools }) requires tools from tenuo.tool()");
         }
+        if (Object.keys(policy.allow).length === 0 && !Object.prototype.hasOwnProperty.call(input.allow ?? {}, policy.capability)) {
+            throw new TenuoConfigurationError(`session({ tools }): ${policy.capability} has allow: {}, which would put a capability that accepts any arguments in the warrant. Name its arguments in tenuo.tool({ allow }), or opt in explicitly with session({ tools, allow: { ${policy.capability}: {} } }).`);
+        }
         const existing = allow[policy.capability];
         if (existing !== undefined && !sameAllow(existing, policy.allow)) {
             throw new TenuoConfigurationError(`session() allow and tools disagree on ${policy.capability}`);
@@ -835,10 +1000,9 @@ export function signApproval(request, approverSecret, options) {
 }
 /** Decode an approval envelope. Not authorization: the call path still decides. */
 export function inspectApproval(envelope) {
-    const text = typeof envelope === "string" ? envelope : Buffer.from(envelope).toString("base64");
     let raw;
     try {
-        raw = loadWasm().sdkInspectApproval(text);
+        raw = loadWasm().sdkInspectApproval(envelope);
     }
     catch (error) {
         throw new TenuoConfigurationError(errorMessage(error));