@tenuo/core 0.2.5-beta.0 → 0.3.0-beta.0

package/README.md

@@ -38,18 +38,30 @@ ceiling. `devRoot()` requires `NODE_ENV=development` or `test`,
 `devRoot({ allowInProduction: true })`, or `TENUO_ALLOW_DEV=1`. Unset
 `NODE_ENV` is not treated as development.
 
-Production loads an issued warrant and a trusted root:
+Production loads an issued warrant and a trusted root. Prefer `Runtime` when
+the same holder identity, roots, revocation list, and receipt buffer should
+outlive a single call:
 
 ```ts
-const tenuo = createTenuo({
+const identity = createTenuo.identity(createTenuo.holderKeyFromEnv("TENUO_HOLDER_SECRET"));
+const runtime = createTenuo.runtime({
+  identity,
   trustedRoots: [createTenuo.publicKeyFromEnv("TENUO_ROOT_PUBLIC_KEY")],
+  receipts: "collect",
 });
-const session = tenuo.sessionFromWire({
-  warrant: process.env.TENUO_WARRANT!,
-  holderKey: createTenuo.holderKeyFromEnv("TENUO_HOLDER_SECRET"),
-});
+const session = runtime.sessionFromWire(process.env.TENUO_WARRANT!);
+await readFile.execute({ path: "/data/q3.pdf" }, { session });
+const receipts = session.drainReceipts(); // persist, then upload
 ```
 
+`createTenuo.parseConnectToken(raw)` decodes a `tenuo_ct_…` token. It does not
+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
+guarantees. This package does not perform HTTP, discovery, or upload.
+
 Delegation to another agent rebinds a narrower child to that agent's key. The
 current holder signs; core refuses any child that is not within its parent
 before a token exists; a copied chain fails `TENUO_INVALID_POP` under any other

package/dist/api.d.ts

@@ -4,7 +4,11 @@
  * Names and shapes here are the review surface — do not grow this file with
  * protocol vocabulary (`Warrant`, `mint`, `guard`) as the lead API.
  */
-export type TenuoErrorCode = "TENUO_NOT_READY" | "TENUO_CONFIGURATION" | "TENUO_CONSTRAINT_VIOLATION" | "TENUO_TOOL_NOT_AUTHORIZED" | "TENUO_WARRANT_EXPIRED" | "TENUO_UNTRUSTED_ROOT" | "TENUO_INVALID_POP" | "TENUO_SIGNATURE_INVALID" | "TENUO_CHAIN_INVALID" | "TENUO_DEPTH_EXCEEDED" | "TENUO_REVOKED" | "TENUO_APPROVAL_REQUIRED" | "TENUO_INSUFFICIENT_APPROVALS" | "TENUO_CANONICALIZATION" | "TENUO_NOT_IMPLEMENTED";
+/** Canonical kebab-case codes from Rust `ErrorCode::name()` / `Denial::code()`. */
+export type ProtocolDenialCode = "signature-invalid" | "untrusted-root" | "chain-broken" | "depth-exceeded" | "warrant-expired" | "tool-not-authorized" | "constraint-violation" | "pop-signature-invalid" | "approval-required" | "insufficient-approvals" | "warrant-revoked";
+/** Legacy SCREAMING_SNAKE aliases accepted by existing TypeScript callers. */
+export type LegacyTenuoErrorCode = "TENUO_NOT_READY" | "TENUO_CONFIGURATION" | "TENUO_CONSTRAINT_VIOLATION" | "TENUO_TOOL_NOT_AUTHORIZED" | "TENUO_WARRANT_EXPIRED" | "TENUO_UNTRUSTED_ROOT" | "TENUO_INVALID_POP" | "TENUO_SIGNATURE_INVALID" | "TENUO_CHAIN_INVALID" | "TENUO_DEPTH_EXCEEDED" | "TENUO_REVOKED" | "TENUO_APPROVAL_REQUIRED" | "TENUO_INSUFFICIENT_APPROVALS" | "TENUO_CANONICALIZATION" | "TENUO_NOT_IMPLEMENTED";
+export type TenuoErrorCode = ProtocolDenialCode | LegacyTenuoErrorCode;
 /** Path-traversal-safe prefix. Core evaluates this; TypeScript does not. */
 export type UnderConstraint = {
     readonly kind: "under";
@@ -112,13 +116,16 @@ export type ToolLike<TArgs extends Record<string, unknown> = Record<string, unkn
     readonly parameters?: unknown;
     execute: (args: TArgs, options?: unknown) => TResult | Promise<TResult>;
 };
-export type ToolPolicy = {
+type KeysOfUnion<T> = T extends unknown ? keyof T : never;
+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).
      */
-    readonly allow: AllowPolicy;
+    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;
 };
 /** Compile-time brand only — never assigned at runtime. Do not `in`/`has` this key. */
@@ -430,6 +437,8 @@ export type CreateTenuoOptions = {
     readonly root?: DevRoot | IssuerKey | PublicKeyHandle;
     /** Published SignedRevocationList (hex or standard base64). Verified against a trusted root. */
     readonly revocationList?: string | Uint8Array;
+    /** 32-byte holder seed used to sign verifier receipts. Runtime supplies this. */
+    readonly receiptSigner?: Uint8Array;
 };
 export type ApprovalRequestSummary = {
     readonly tool: string;
@@ -501,6 +510,23 @@ export interface Session {
     dedupKey(tool: string, args: Readonly<Record<string, unknown>>): string;
     /** Holder public key, depth, ceiling, lifetime, tools. Never the secret. */
     inspect(): SessionInfo;
+    /**
+     * Receipt helpers below are required for `createTenuo.runtime({ receipts:
+     * "collect" })`. Implementers that are not runtime sessions can return
+     * empty snapshots and `0` from acknowledge.
+     */
+    /**
+     * Receipts collected for this session and not yet drained. Empty when the
+     * session was not created by a Runtime with `receipts: "collect"`.
+     */
+    peekReceipts(): readonly string[];
+    /**
+     * Snapshot of collected receipts. Same as `peekReceipts`; nothing is removed
+     * until `acknowledgeReceipts`.
+     */
+    drainReceipts(): readonly string[];
+    /** Remove the first `count` pending receipts. */
+    acknowledgeReceipts(count: number): number;
 }
 export interface Tenuo {
     /**
@@ -509,7 +535,7 @@ export interface Tenuo {
      */
     tool<T extends {
         execute: (args: never) => unknown;
-    }>(inner: T, policy: ToolPolicy): ProtectedTool<T>;
+    }>(inner: T, policy: ToolPolicy<Parameters<T["execute"]>[0]>): ProtectedTool<T>;
     session(input: SessionInput): Session;
     /** Import a warrant minted elsewhere (Rust / Python / another process). */
     sessionFromWire(input: SessionFromWireInput): Session;
@@ -641,4 +667,3 @@ export interface TenuoMcp {
     jsonRpcError(error: unknown): McpJsonRpcError;
 }
 export {};
-//# sourceMappingURL=api.d.ts.map

package/dist/api.js.map

@@ -1 +1 @@
-{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}
+{"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  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  /** Verify a presented call at any boundary. Resolves with the authorized arguments; the tool must not run otherwise. */\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. Tool handler must not\n   * 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/client.d.ts

@@ -1,4 +1,7 @@
 import type { ApprovalContextAttestation, ApprovalInfo, ApprovalRequest, ControlPlaneApprovalRequestV1, ControlPlaneApprovalResponseV1, CreateTenuoOptions, DevRoot, IssuerKey, PublicKeyHandle, ReceiptChainInfo, ReceiptInfo, RevocationListInfo, RevocationListInput, SignApprovalOptions, Tenuo } from "./api.ts";
+import { parseConnectToken } from "./connect.ts";
+import { generateIdentity, identityFromKey } from "./identity.ts";
+import { createRuntime } from "./runtime.ts";
 export declare function devRoot(options?: {
     readonly allowInProduction?: boolean;
 }): DevRoot;
@@ -65,5 +68,8 @@ export declare const createTenuo: ((options?: CreateTenuoOptions) => Tenuo) & {
     verifyReceiptChain: typeof verifyReceiptChain;
     controlPlaneApprovalRequestV1: typeof controlPlaneApprovalRequestV1;
     signedApprovalsFromResponseV1: typeof signedApprovalsFromResponseV1;
+    parseConnectToken: typeof parseConnectToken;
+    identity: typeof identityFromKey;
+    generateIdentity: typeof generateIdentity;
+    runtime: (options: Parameters<typeof createRuntime>[1]) => ReturnType<typeof createRuntime>;
 };
-//# sourceMappingURL=client.d.ts.map

package/dist/client.js

@@ -1,6 +1,10 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { randomBytes } from "node:crypto";
+import { parseConnectToken } from "./connect.js";
+import { generateIdentity, identityFromKey } from "./identity.js";
 import { createMcp, presentCall, verifyPresented } from "./mcp.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";
@@ -207,18 +211,18 @@ class TenuoClient {
     decide;
     constructor(options) {
         if (options.root?.kind === "dev-root") {
-            this.context = createDevContext();
+            this.context = createDevContext(options.receiptSigner);
             this.canMint = true;
         }
         else if (options.root?.kind === "issuer-key") {
             if (!(options.root.secret instanceof Uint8Array) || options.root.secret.length !== 32) {
                 throw new TenuoConfigurationError("root: issuer key must be a 32-byte secret");
             }
-            this.context = createIssuerContext(options.root.secret, rootHexes(options));
+            this.context = createIssuerContext(options.root.secret, rootHexes(options), options.receiptSigner);
             this.canMint = true;
         }
         else {
-            this.context = createVerifierContext(rootHexes(options));
+            this.context = createVerifierContext(rootHexes(options), undefined, options.receiptSigner);
             this.canMint = false;
         }
         if (options.revocationList !== undefined) {
@@ -227,7 +231,7 @@ class TenuoClient {
         this.decide = (decision, tool, native, args) => {
             this.applyDecision(decision, tool, native, args);
         };
-        this.mcp = createMcp(this.context, this.decide);
+        this.mcp = createMcp(this.context, this.decide, this);
     }
     applyDecision(decision, tool, native, args) {
         if (decision.outcome === "allow") {
@@ -257,7 +261,7 @@ class TenuoClient {
             const session = resolveSession(callOptions);
             const native = nativeSession(session);
             const decision = this.context.authorize(native, capability, args, approvalsFrom(callOptions), policy.allow, requestIdFrom(callOptions));
-            emitReceipt(callOptions, decision.receipt);
+            emitReceipt(callOptions, decision.receipt, session, this);
             if (decision.outcome === "allow") {
                 return original(plainArgs(decision.args), forwardExecuteOptions(callOptions));
             }
@@ -398,7 +402,9 @@ class TenuoClient {
         }
         const native = options === undefined ? undefined : narrowOptionsJson(options);
         try {
-            return new Session(this.context.narrow(nativeSession(session), allow, native));
+            const child = new Session(this.context.narrow(nativeSession(session), allow, native));
+            inheritSessionCollector(session, child);
+            return child;
         }
         catch (error) {
             throw chainError(error);
@@ -493,10 +499,11 @@ class TenuoClient {
         if (!isSession(session)) {
             throw new TenuoConfigurationError("present() requires a Tenuo Session, not a plain object");
         }
-        return presentCall(this.context, this.decide, session, tool, args, options, "present()").presented;
+        return presentCall(this.context, this.decide, session, tool, args, options, "present()", this)
+            .presented;
     }
     verify(presented, tool, args, options) {
-        return verifyPresented(this.context, this.decide, presented, tool, args, options, "verify()");
+        return verifyPresented(this.context, this.decide, presented, tool, args, options, "verify()", this);
     }
     revocationList(input) {
         if (!this.canMint) {
@@ -715,7 +722,8 @@ function normalizeWireBytes(value) {
     }
     return bytesToHex(value);
 }
-function emitReceipt(callOptions, receipt) {
+function emitReceipt(callOptions, receipt, session, host) {
+    collectReceipt(receipt, session, host);
     if (receipt === undefined || callOptions === null || typeof callOptions !== "object") {
         return;
     }
@@ -726,15 +734,7 @@ function emitReceipt(callOptions, receipt) {
     if (typeof onReceipt !== "function") {
         return;
     }
-    try {
-        const result = onReceipt(receipt);
-        if (result !== null && typeof result === "object" && "then" in result && typeof result.then === "function") {
-            void Promise.resolve(result).catch(() => undefined);
-        }
-    }
-    catch {
-        // Receipt hooks must not deny or fail the tool.
-    }
+    emitIsolatedReceipt(onReceipt, receipt);
 }
 function requestIdFrom(callOptions) {
     if (callOptions !== null && typeof callOptions === "object" && "requestId" in callOptions) {
@@ -1039,5 +1039,9 @@ export const createTenuo = Object.assign(createTenuoImpl, {
     verifyReceiptChain,
     controlPlaneApprovalRequestV1,
     signedApprovalsFromResponseV1,
+    parseConnectToken,
+    identity: identityFromKey,
+    generateIdentity,
+    runtime: (options) => createRuntime(createTenuoImpl, options),
 });
 //# sourceMappingURL=client.js.map