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

package/dist/client.js

@@ -1,11 +1,17 @@
 import { AsyncLocalStorage } from "node:async_hooks";
-import { createMcp } from "./mcp.js";
+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, createVerifierContext, importSessionFromChain, importSessionFromWire, loadWasm, } from "./wasm.js";
+import { createDevContext, createIssuerContext, createVerifierContext, importSessionFromChain, importSessionFromWire, loadWasm, protocolLimits, publicKeyHexFromHolderKey, } from "./wasm.js";
 const currentSession = new AsyncLocalStorage();
 const toolPolicies = new WeakMap();
 const wrappedInners = new WeakSet();
+const CLEARANCE_NAMES = new Set(["untrusted", "external", "partner", "internal", "privileged", "system"]);
 function nodeEnv() {
     if (typeof process === "undefined") {
         return undefined;
@@ -45,18 +51,21 @@ function normalizeHex(value) {
     }
     return hex;
 }
-export function publicKeyFromEnv(name) {
+function envValue(name, what) {
     if (name.length === 0) {
-        throw new TenuoConfigurationError("publicKeyFromEnv() requires an environment variable name");
+        throw new TenuoConfigurationError(`${what} requires an environment variable name`);
     }
     if (typeof process === "undefined") {
-        throw new TenuoConfigurationError(`Environment variable ${name} is not available. Tenuo fails closed without a trusted root.`);
+        throw new TenuoConfigurationError(`Environment variable ${name} is not available. Tenuo fails closed without a ${what}.`);
     }
     const value = process.env[name];
     if (value === undefined || value.length === 0) {
-        throw new TenuoConfigurationError(`Environment variable ${name} is not set or empty. Tenuo fails closed without a trusted root.`);
+        throw new TenuoConfigurationError(`Environment variable ${name} is not set or empty. Tenuo fails closed without a ${what}.`);
     }
-    return { kind: "public-key", source: "env", hex: normalizeHex(value) };
+    return value;
+}
+export function publicKeyFromEnv(name) {
+    return { kind: "public-key", source: "env", hex: normalizeHex(envValue(name, "trusted root")) };
 }
 export function publicKeyFromHex(hex) {
     return { kind: "public-key", source: "hex", hex: normalizeHex(hex) };
@@ -65,13 +74,12 @@ export function publicKeyFromBytes(bytes) {
     if (bytes.length !== 32) {
         throw new TenuoConfigurationError("publicKeyFromBytes() requires a 32-byte public key");
     }
-    const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
-    return { kind: "public-key", source: "bytes", hex };
+    return { kind: "public-key", source: "bytes", hex: bytesToHex(bytes) };
 }
-function normalizeSecretHex(value) {
+function normalizeSecretHex(value, what) {
     const hex = value.trim().toLowerCase().replace(/^0x/, "");
     if (!/^[0-9a-f]{64}$/.test(hex)) {
-        throw new TenuoConfigurationError("Holder key must be a 32-byte hex secret (64 hex characters)");
+        throw new TenuoConfigurationError(`${what} must be a 32-byte hex secret (64 hex characters)`);
     }
     return hex;
 }
@@ -82,21 +90,90 @@ function hexToBytes(hex) {
     }
     return bytes;
 }
+function bytesToHex(bytes) {
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
 export function holderKeyFromEnv(name) {
-    if (name.length === 0) {
-        throw new TenuoConfigurationError("holderKeyFromEnv() requires an environment variable name");
+    return hexToBytes(normalizeSecretHex(envValue(name, "holder key"), "Holder key"));
+}
+export function holderKeyFromHex(hex) {
+    return hexToBytes(normalizeSecretHex(hex, "Holder key"));
+}
+/**
+ * A fresh 32-byte Ed25519 secret. One per agent, kept in that agent's
+ * process; only its public key (see `publicKeyFromHolderKey`) travels.
+ */
+export function generateHolderKey() {
+    return new Uint8Array(randomBytes(32));
+}
+/** Same shape as a holder key. Named separately so a control plane's key reads as one. */
+export function generateIssuerKey() {
+    return generateHolderKey();
+}
+/** The public half of a holder or issuer secret. */
+export function publicKeyFromHolderKey(holderKey) {
+    if (!(holderKey instanceof Uint8Array) || holderKey.length !== 32) {
+        throw new TenuoConfigurationError("publicKeyFromHolderKey() requires a 32-byte holder key");
     }
-    if (typeof process === "undefined") {
-        throw new TenuoConfigurationError(`Environment variable ${name} is not available. Tenuo fails closed without a holder key.`);
+    loadWasm();
+    return { kind: "public-key", source: "bytes", hex: publicKeyHexFromHolderKey(holderKey) };
+}
+const MAX_WASM_U32 = 0xffff_ffff;
+function requireUint32(value, name, minimum = 0) {
+    if (!Number.isInteger(value) || value < minimum || value > MAX_WASM_U32) {
+        throw new TenuoConfigurationError(`${name} must be an integer between ${minimum} and ${MAX_WASM_U32}`);
     }
-    const value = process.env[name];
-    if (value === undefined || value.length === 0) {
-        throw new TenuoConfigurationError(`Environment variable ${name} is not set or empty. Tenuo fails closed without a holder key.`);
+    return value;
+}
+/** Stable control-plane key from the environment. This process becomes an issuer. */
+export function issuerKeyFromEnv(name) {
+    return { kind: "issuer-key", secret: hexToBytes(normalizeSecretHex(envValue(name, "issuer key"), "Issuer key")) };
+}
+export function issuerKeyFromHex(hex) {
+    return { kind: "issuer-key", secret: hexToBytes(normalizeSecretHex(hex, "Issuer key")) };
+}
+export function issuerKeyFromBytes(secret) {
+    if (!(secret instanceof Uint8Array) || secret.length !== 32) {
+        throw new TenuoConfigurationError("issuerKeyFromBytes() requires a 32-byte secret");
     }
-    return hexToBytes(normalizeSecretHex(value));
+    return { kind: "issuer-key", secret: new Uint8Array(secret) };
 }
-export function holderKeyFromHex(hex) {
-    return hexToBytes(normalizeSecretHex(hex));
+function requireDepth(value, name) {
+    requireUint32(value, name);
+    const maximum = protocolLimits().max_delegation_depth;
+    if (value > maximum) {
+        throw new TenuoConfigurationError(`${name} ${value} exceeds the protocol maximum of ${maximum}`);
+    }
+    return value;
+}
+function requireTtl(value, name, minimum = 0) {
+    requireUint32(value, name, minimum);
+    const maximum = protocolLimits().max_warrant_ttl_seconds;
+    if (value > maximum) {
+        throw new TenuoConfigurationError(`${name} ${value} exceeds the protocol maximum of ${maximum}`);
+    }
+    return value;
+}
+function requirePublicKey(value, name) {
+    if (value === null ||
+        typeof value !== "object" ||
+        value.kind !== "public-key" ||
+        typeof value.hex !== "string") {
+        throw new TenuoConfigurationError(`${name} must be a public key handle (createTenuo.publicKeyFromHolderKey / publicKeyFromHex / publicKeyFromEnv)`);
+    }
+    return value;
+}
+function clearanceJson(value, name) {
+    if (typeof value === "number") {
+        if (!Number.isInteger(value) || value < 0 || value > 255) {
+            throw new TenuoConfigurationError(`${name} must be an integer 0-255 or a level name`);
+        }
+        return value;
+    }
+    if (typeof value === "string" && CLEARANCE_NAMES.has(value)) {
+        return value;
+    }
+    throw new TenuoConfigurationError(`${name} must be one of ${[...CLEARANCE_NAMES].join(", ")} or an integer 0-255`);
 }
 function rootHexes(options) {
     const handles = [];
@@ -131,19 +208,48 @@ class TenuoClient {
     context;
     canMint;
     mcp;
+    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), 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) {
             this.context.loadRevocationList(normalizeWireBytes(options.revocationList));
         }
-        this.mcp = createMcp(this.context, (decision, tool) => applyDecision(decision, tool));
+        this.decide = (decision, tool, native, args) => {
+            this.applyDecision(decision, tool, native, args);
+        };
+        this.mcp = createMcp(this.context, this.decide, this);
+    }
+    applyDecision(decision, tool, native, args) {
+        if (decision.outcome === "allow") {
+            return;
+        }
+        if (decision.outcome === "approval_required") {
+            let request;
+            if (native !== undefined && args !== undefined) {
+                try {
+                    request = approvalRequestFromWasm(this.context.approvalRequest(native, tool, args));
+                }
+                catch {
+                    request = undefined;
+                }
+            }
+            throw new ApprovalRequiredError(decision.tool ?? tool, decision.required ?? 1, decision.received ?? 0, decision.message, request);
+        }
+        throw new AuthorizationDeniedError(decision.code ?? "TENUO_TOOL_NOT_AUTHORIZED", explainDeny(decision.message ?? "Authorization denied", decision.field), decision.field);
     }
     tool(inner, policy) {
         if (toolPolicies.has(inner) || wrappedInners.has(inner)) {
@@ -153,15 +259,14 @@ class TenuoClient {
         const original = inner.execute;
         const execute = async (args, callOptions) => {
             const session = resolveSession(callOptions);
-            const decision = this.context.authorize(nativeSession(session), capability, args, approvalsFrom(callOptions), policy.allow, requestIdFrom(callOptions));
-            emitReceipt(callOptions, decision.receipt);
+            const native = nativeSession(session);
+            const decision = this.context.authorize(native, capability, args, approvalsFrom(callOptions), policy.allow, requestIdFrom(callOptions));
+            emitReceipt(callOptions, decision.receipt, session, this);
             if (decision.outcome === "allow") {
                 return original(plainArgs(decision.args), forwardExecuteOptions(callOptions));
             }
-            if (decision.outcome === "approval_required") {
-                throw new ApprovalRequiredError(decision.tool ?? capability, decision.required ?? 1, decision.received ?? 0, decision.message);
-            }
-            throw new AuthorizationDeniedError(decision.code ?? "TENUO_TOOL_NOT_AUTHORIZED", explainDeny(decision.message ?? "Authorization denied", decision.field), decision.field);
+            this.applyDecision(decision, capability, native, plainArgs(args));
+            throw new TenuoConfigurationError("unreachable: decision was neither allow nor deny");
         };
         const wrapped = Object.assign(Object.create(Object.getPrototypeOf(inner)), inner, {
             execute,
@@ -172,23 +277,95 @@ class TenuoClient {
     }
     session(input) {
         const allow = collectSessionAllow(input);
-        if (Object.keys(allow).length === 0) {
+        const kind = input.kind ?? "execution";
+        if (kind !== "execution" && kind !== "issuer") {
+            throw new TenuoConfigurationError('session().kind must be "execution" or "issuer"');
+        }
+        if (Object.keys(allow).length === 0 && kind === "execution") {
             throw new TenuoConfigurationError("tenuo.session() requires tools from tenuo.tool() or at least one capability in allow");
         }
         if (!this.canMint) {
-            throw new TenuoConfigurationError("session() mints a warrant and needs a local issuer. Use createTenuo({ root: createTenuo.devRoot() }).");
+            throw new TenuoConfigurationError("session() mints a warrant and needs a local issuer. Use createTenuo({ root: createTenuo.devRoot() }) or an issuer key.");
+        }
+        const options = { kind, allow };
+        if (input.ttlSeconds !== undefined) {
+            options.ttlSeconds = requireTtl(input.ttlSeconds, "session().ttlSeconds");
+        }
+        if (input.holder !== undefined) {
+            options.holder = requirePublicKey(input.holder, "session().holder").hex;
+        }
+        if (input.maxDepth !== undefined) {
+            options.maxDepth = requireDepth(input.maxDepth, "session().maxDepth");
+        }
+        if (input.clearance !== undefined) {
+            options.clearance = clearanceJson(input.clearance, "session().clearance");
+        }
+        if (input.sessionId !== undefined) {
+            options.sessionId = requireLabel(input.sessionId, "session().sessionId");
+        }
+        if (input.agentId !== undefined) {
+            options.agentId = requireLabel(input.agentId, "session().agentId");
         }
-        const ttl = input.ttlSeconds ?? 0;
         if (input.requireApproval !== undefined) {
-            if (input.requireApproval.approvers.length === 0) {
-                throw new TenuoConfigurationError("requireApproval.approvers must not be empty");
-            }
-            if (input.requireApproval.min < 1) {
-                throw new TenuoConfigurationError("requireApproval.min must be at least 1");
-            }
+            options.requireApproval = requireApprovalJson(input.requireApproval);
+        }
+        if (input.issuableTools !== undefined) {
+            options.issuableTools = [...input.issuableTools];
+        }
+        if (input.constraintBounds !== undefined) {
+            options.constraintBounds = input.constraintBounds;
+        }
+        if (input.maxIssueDepth !== undefined) {
+            options.maxIssueDepth = requireDepth(input.maxIssueDepth, "session().maxIssueDepth");
+        }
+        try {
+            return new Session(this.context.mintExtended(options));
+        }
+        catch (error) {
+            throw new TenuoConfigurationError(errorMessage(error));
+        }
+    }
+    issue(issuer, input) {
+        if (!isSession(issuer)) {
+            throw new TenuoConfigurationError("issue() requires a Tenuo Session, not a plain object");
+        }
+        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");
+        }
+        const options = {
+            allow: input.allow,
+            holder: requirePublicKey(input.holder, "issue().holder").hex,
+        };
+        if (input.ttlSeconds !== undefined) {
+            options.ttlSeconds = requireTtl(input.ttlSeconds, "issue().ttlSeconds", 1);
+        }
+        if (input.maxDepth !== undefined) {
+            options.maxDepth = requireDepth(input.maxDepth, "issue().maxDepth");
+        }
+        if (input.clearance !== undefined) {
+            options.clearance = clearanceJson(input.clearance, "issue().clearance");
+        }
+        if (input.sessionId !== undefined) {
+            options.sessionId = requireLabel(input.sessionId, "issue().sessionId");
+        }
+        if (input.agentId !== undefined) {
+            options.agentId = requireLabel(input.agentId, "issue().agentId");
+        }
+        if (input.requireApproval !== undefined) {
+            options.requireApproval = requireApprovalJson(input.requireApproval);
+        }
+        try {
+            return new Session(this.context.issue(nativeSession(issuer), options));
+        }
+        catch (error) {
+            throw chainError(error);
         }
-        const native = this.context.mint(allow, ttl, requireApprovalJson(input.requireApproval));
-        return new Session(native);
+    }
+    issuerPublicKey() {
+        if (!this.canMint) {
+            throw new TenuoConfigurationError("issuerPublicKey() needs a local issuer. This context verifies against trustedRoots and does not mint.");
+        }
+        return { kind: "public-key", source: "bytes", hex: this.context.issuerPublicKey() };
     }
     sessionFromWire(input) {
         if (!(input.holderKey instanceof Uint8Array) || input.holderKey.length !== 32) {
@@ -216,22 +393,128 @@ class TenuoClient {
         }
         return currentSession.run(session, fn);
     }
-    narrow(session, allow) {
+    narrow(session, allow, options) {
         if (Object.keys(allow).length === 0) {
             throw new TenuoConfigurationError("tenuo.narrow() requires a non-empty allow policy");
         }
         if (!isSession(session)) {
             throw new TenuoConfigurationError("narrow() requires a Tenuo Session, not a plain object");
         }
+        const native = options === undefined ? undefined : narrowOptionsJson(options);
         try {
-            return new Session(this.context.narrow(nativeSession(session), allow));
+            const child = new Session(this.context.narrow(nativeSession(session), allow, native));
+            inheritSessionCollector(session, child);
+            return child;
         }
         catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            if (message.startsWith("TENUO_CHAIN_INVALID")) {
-                throw new AuthorizationDeniedError("TENUO_CHAIN_INVALID", message);
-            }
-            throw new TenuoConfigurationError(message);
+            throw chainError(error);
+        }
+    }
+    explain(session, tool, args) {
+        if (!isSession(session)) {
+            throw new TenuoConfigurationError("explain() requires a Tenuo Session, not a plain object");
+        }
+        let raw;
+        try {
+            raw = this.context.explain(nativeSession(session), tool, args);
+        }
+        catch (error) {
+            throw new TenuoConfigurationError(errorMessage(error));
+        }
+        const out = {
+            tool: raw.tool,
+            kind: raw.kind,
+            outcome: raw.outcome,
+            toolGranted: raw.tool_granted,
+            fields: raw.fields.map((f) => {
+                const field = {
+                    field: f.field,
+                    kind: f.kind,
+                    constraint: f.constraint,
+                    satisfied: f.satisfied,
+                };
+                if (f.value !== undefined) {
+                    field.value = f.value;
+                }
+                if (f.reason !== undefined) {
+                    field.reason = f.reason;
+                }
+                return field;
+            }),
+            unknownFields: [...raw.unknown_fields],
+            missingFields: [...raw.missing_fields],
+            expired: raw.expired,
+            expiresAt: raw.expires_at,
+            chainValid: raw.chain_valid,
+        };
+        if (raw.code !== undefined) {
+            out.code = raw.code;
+        }
+        if (raw.field !== undefined) {
+            out.field = raw.field;
+        }
+        if (raw.message !== undefined) {
+            out.message = raw.message;
+        }
+        if (raw.chain_error !== undefined) {
+            out.chainError = raw.chain_error;
+        }
+        return out;
+    }
+    approvalRequest(session, tool, args) {
+        if (!isSession(session)) {
+            throw new TenuoConfigurationError("approvalRequest() requires a Tenuo Session, not a plain object");
+        }
+        try {
+            return approvalRequestFromWasm(this.context.approvalRequest(nativeSession(session), tool, args));
+        }
+        catch (error) {
+            throw new TenuoConfigurationError(errorMessage(error));
+        }
+    }
+    attestApprovalRequest(session, tool, args) {
+        if (!isSession(session)) {
+            throw new TenuoConfigurationError("attestApprovalRequest() requires a Tenuo Session, not a plain object");
+        }
+        let raw;
+        try {
+            raw = this.context.approvalContextAttestation(nativeSession(session), tool, args);
+        }
+        catch (error) {
+            throw new TenuoConfigurationError(errorMessage(error));
+        }
+        return {
+            version: raw.version,
+            canonicalization: raw.canonicalization,
+            warrantId: raw.warrant_id,
+            tool: raw.tool,
+            requestHash: raw.request_hash,
+            holderKeyHex: raw.holder_key_hex,
+            argsCanonicalCborB64: raw.args_canonical_cbor_b64,
+            signerKeyHex: raw.signer_key_hex,
+            signatureB64: raw.signature_b64,
+        };
+    }
+    present(session, tool, args, options) {
+        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()", this)
+            .presented;
+    }
+    verify(presented, tool, args, options) {
+        return verifyPresented(this.context, this.decide, presented, tool, args, options, "verify()", this);
+    }
+    revocationList(input) {
+        if (!this.canMint) {
+            throw new TenuoConfigurationError("revocationList() needs a local issuer key. Use createTenuo.signRevocationList() with an explicit secret, or an issuer-key root.");
+        }
+        const { ids, version } = revocationInput(input);
+        try {
+            return this.context.signRevocationListVersioned(ids, version);
+        }
+        catch (error) {
+            throw new TenuoConfigurationError(errorMessage(error));
         }
     }
     revoke(list) {
@@ -241,6 +524,54 @@ class TenuoClient {
         loadWasm();
     }
 }
+function requireLabel(value, name) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new TenuoConfigurationError(`${name} must be a non-empty string`);
+    }
+    return value;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** Map a prefixed core message from narrow()/issue() to the matching error class. */
+function chainError(error) {
+    if (error instanceof TenuoError) {
+        return error;
+    }
+    const message = explainChainFailure(errorMessage(error));
+    for (const code of ["TENUO_CHAIN_INVALID", "TENUO_DEPTH_EXCEEDED", "TENUO_WARRANT_EXPIRED"]) {
+        if (message.startsWith(code)) {
+            return new AuthorizationDeniedError(code, message);
+        }
+    }
+    return new TenuoConfigurationError(message);
+}
+function explainChainFailure(message) {
+    const tool = /tool '([^']+)' not in parent's tools/.exec(message)?.[1];
+    if (tool !== undefined) {
+        return `${message}. narrow() cannot add '${tool}': remove it or delegate from a parent that grants it.`;
+    }
+    if (message.includes("parent's allowed set") ||
+        message.includes("range expanded") ||
+        message.includes("would expand permissions") ||
+        message.includes("clearance cannot increase")) {
+        return `${message}. narrow() only accepts a child policy that is equal to or stricter than its parent.`;
+    }
+    return message;
+}
+function revocationInput(input) {
+    if (input === null || typeof input !== "object" || !Array.isArray(input.revoke)) {
+        throw new TenuoConfigurationError("revocation list input must be { revoke: string[], version? }");
+    }
+    const ids = input.revoke.filter((id) => typeof id === "string" && id.length > 0);
+    if (ids.length === 0 || ids.length !== input.revoke.length) {
+        throw new TenuoConfigurationError("revoke must be a non-empty array of warrant ids");
+    }
+    if (input.version !== undefined && (!Number.isInteger(input.version) || input.version < 1)) {
+        throw new TenuoConfigurationError("revocation list version must be a positive integer");
+    }
+    return { ids, version: input.version };
+}
 function plainArgs(value) {
     if (value instanceof Map) {
         return Object.fromEntries(value);
@@ -251,33 +582,105 @@ function plainArgs(value) {
     return {};
 }
 function requireApprovalJson(require) {
-    if (require === undefined) {
-        return undefined;
+    if (require === null || typeof require !== "object") {
+        throw new TenuoConfigurationError("requireApproval must be an object");
+    }
+    if (!Array.isArray(require.approvers) || require.approvers.length === 0) {
+        throw new TenuoConfigurationError("requireApproval.approvers must not be empty");
+    }
+    if (!Number.isInteger(require.min) || require.min < 1) {
+        throw new TenuoConfigurationError("requireApproval.min must be at least 1");
     }
     const payload = {
-        approvers: require.approvers.map((approver) => approver.hex),
+        approvers: require.approvers.map((approver, i) => requirePublicKey(approver, `requireApproval.approvers[${i}]`).hex),
         min: require.min,
     };
     if (require.tools !== undefined) {
         payload.tools = [...require.tools];
     }
+    if (require.gates !== undefined) {
+        const gates = {};
+        for (const [tool, gate] of Object.entries(require.gates)) {
+            const out = {};
+            if (gate.message !== undefined) {
+                out.message = gate.message;
+            }
+            if (gate.args !== undefined) {
+                out.args = { ...gate.args };
+            }
+            gates[tool] = out;
+        }
+        payload.gates = gates;
+    }
     return payload;
 }
-function applyDecision(decision, tool) {
-    if (decision.outcome === "allow") {
-        return;
+function narrowOptionsJson(options) {
+    if (options === null || typeof options !== "object") {
+        throw new TenuoConfigurationError("narrow() options must be an object");
+    }
+    const known = ["holder", "ttlSeconds", "terminal", "maxDepth", "clearance", "agentId", "addApprovers", "minApprovals"];
+    for (const key of Object.keys(options)) {
+        if (!known.includes(key)) {
+            throw new TenuoConfigurationError(`narrow() options: unknown key '${key}' (expected ${known.join(", ")})`);
+        }
+    }
+    const out = {};
+    if (options.holder !== undefined) {
+        out.holder = requirePublicKey(options.holder, "narrow().holder").hex;
+    }
+    if (options.ttlSeconds !== undefined) {
+        out.ttlSeconds = requireTtl(options.ttlSeconds, "narrow().ttlSeconds", 1);
+    }
+    if (options.terminal !== undefined) {
+        if (typeof options.terminal !== "boolean") {
+            throw new TenuoConfigurationError("narrow().terminal must be a boolean");
+        }
+        out.terminal = options.terminal;
+    }
+    if (options.maxDepth !== undefined) {
+        out.maxDepth = requireDepth(options.maxDepth, "narrow().maxDepth");
+    }
+    if (out.terminal === true && out.maxDepth !== undefined) {
+        throw new TenuoConfigurationError("narrow() options: pass terminal or maxDepth, not both");
     }
-    if (decision.outcome === "approval_required") {
-        throw new ApprovalRequiredError(decision.tool ?? tool, decision.required ?? 1, decision.received ?? 0, decision.message);
+    if (options.clearance !== undefined) {
+        out.clearance = clearanceJson(options.clearance, "narrow().clearance");
     }
-    throw new AuthorizationDeniedError(decision.code ?? "TENUO_TOOL_NOT_AUTHORIZED", explainDeny(decision.message ?? "Authorization denied", decision.field), decision.field);
+    if (options.agentId !== undefined) {
+        out.agentId = requireLabel(options.agentId, "narrow().agentId");
+    }
+    if (options.addApprovers !== undefined) {
+        out.addApprovers = options.addApprovers.map((a, i) => requirePublicKey(a, `narrow().addApprovers[${i}]`).hex);
+    }
+    if (options.minApprovals !== undefined) {
+        if (!Number.isInteger(options.minApprovals) || options.minApprovals < 1) {
+            throw new TenuoConfigurationError("narrow().minApprovals must be at least 1");
+        }
+        out.minApprovals = options.minApprovals;
+    }
+    return out;
+}
+function approvalRequestFromWasm(raw) {
+    return {
+        requestId: raw.request_id,
+        warrantId: raw.warrant_id,
+        tool: raw.tool,
+        args: { ...raw.args },
+        requestHash: raw.request_hash,
+        holderPublicKey: raw.holder_public_key,
+        requiredApprovers: [...raw.required_approvers],
+        minApprovals: raw.min_approvals,
+        warrantExpiresAt: raw.warrant_expires_at,
+        createdAt: raw.created_at,
+        message: raw.message,
+    };
 }
 function explainDeny(message, field) {
     if (!message.includes("unknown field not allowed")) {
         return message;
     }
     const named = field !== undefined && field.length > 0 ? `'${field}'` : "this argument";
-    return `${message}. Zero-trust: name ${named} in allow (e.g. ${named}: pattern("*")), or drop it from the call. Empty allow: {} adds no extra ceiling.`;
+    return `${message}. Zero-trust: name ${named} in allow (for example ${named}: pattern("*")), or remove it from the call; constrained policies reject omitted fields.`;
 }
 function forwardExecuteOptions(callOptions) {
     if (callOptions === null || typeof callOptions !== "object") {
@@ -296,7 +699,7 @@ function forwardExecuteOptions(callOptions) {
     return Object.keys(rest).length === 0 ? undefined : rest;
 }
 function importWireError(error) {
-    const message = error instanceof Error ? error.message : String(error);
+    const message = errorMessage(error);
     if (message.startsWith("TENUO_CHAIN_INVALID") || message.includes("invalid warrant")) {
         return new TenuoError("TENUO_CHAIN_INVALID", message);
     }
@@ -306,15 +709,21 @@ function importWireError(error) {
     if (message.startsWith("TENUO_UNTRUSTED_ROOT")) {
         return new TenuoError("TENUO_UNTRUSTED_ROOT", message);
     }
+    if (message.startsWith("TENUO_INVALID_POP")) {
+        // The warrant is fine; the key is not the one it was issued to.
+        const separator = /[.!?]$/.test(message.trim()) ? "" : ".";
+        return new AuthorizationDeniedError("TENUO_INVALID_POP", `${message}${separator} If this followed narrow(), set { holder: receiverPublicKey } for the agent that imports the child.`);
+    }
     return new TenuoConfigurationError(message);
 }
 function normalizeWireBytes(value) {
     if (typeof value === "string") {
         return value;
     }
-    return Array.from(value, (byte) => byte.toString(16).padStart(2, "0")).join("");
+    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;
     }
@@ -325,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) {
@@ -396,6 +797,217 @@ function sortedAllow(allow) {
     }
     return out;
 }
+// ---------------------------------------------------------------------------
+// Static helpers: approvals, revocation, receipts, control-plane wire shapes
+// ---------------------------------------------------------------------------
+function requestHashOf(request) {
+    const hash = typeof request === "string" ? request : request.requestHash;
+    const hex = hash.trim().toLowerCase();
+    if (!/^[0-9a-f]{64}$/.test(hex)) {
+        throw new TenuoConfigurationError("signApproval() needs an ApprovalRequest or a 64-hex request hash");
+    }
+    return hex;
+}
+/** Sign an approval as an approver. The approver never needs the warrant or the holder key. */
+export function signApproval(request, approverSecret, options) {
+    if (!(approverSecret instanceof Uint8Array) || approverSecret.length !== 32) {
+        throw new TenuoConfigurationError("signApproval() requires a 32-byte approver secret");
+    }
+    if (options === null || typeof options !== "object" || typeof options.externalId !== "string" || options.externalId.trim().length === 0) {
+        throw new TenuoConfigurationError("signApproval() requires options.externalId: who approved");
+    }
+    if (options.ttlSeconds !== undefined && (!Number.isInteger(options.ttlSeconds) || options.ttlSeconds < 1)) {
+        throw new TenuoConfigurationError("signApproval().ttlSeconds must be a positive integer");
+    }
+    const warrantExpiresAt = options.warrantExpiresAt ?? (typeof request === "object" ? request.warrantExpiresAt : undefined);
+    try {
+        return loadWasm().sdkSignApprovalForRequest(requestHashOf(request), approverSecret, options.externalId, options.ttlSeconds, warrantExpiresAt);
+    }
+    catch (error) {
+        throw new TenuoConfigurationError(errorMessage(error));
+    }
+}
+/** 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);
+    }
+    catch (error) {
+        throw new TenuoConfigurationError(errorMessage(error));
+    }
+    const out = {
+        approverPublicKey: raw.approver_public_key,
+        requestHash: raw.request_hash,
+        externalId: raw.external_id,
+        approvedAt: raw.approved_at,
+        expiresAt: raw.expires_at,
+        expired: raw.expired,
+        signatureValid: raw.signature_valid,
+    };
+    if (raw.error !== undefined) {
+        out.error = raw.error;
+    }
+    return out;
+}
+/** Sign a revocation list with an explicit issuer secret. */
+export function signRevocationList(input, issuerSecret) {
+    if (!(issuerSecret instanceof Uint8Array) || issuerSecret.length !== 32) {
+        throw new TenuoConfigurationError("signRevocationList() requires a 32-byte issuer secret");
+    }
+    const { ids, version } = revocationInput(input);
+    try {
+        return loadWasm().sdkSignRevocationListVersioned(ids, version, issuerSecret);
+    }
+    catch (error) {
+        throw new TenuoConfigurationError(errorMessage(error));
+    }
+}
+export function inspectRevocationList(wire) {
+    let raw;
+    try {
+        raw = loadWasm().sdkInspectRevocationList(normalizeWireBytes(wire));
+    }
+    catch (error) {
+        throw new TenuoConfigurationError(errorMessage(error));
+    }
+    return {
+        version: raw.version,
+        issuedAt: raw.issued_at,
+        issuerPublicKey: raw.issuer_public_key,
+        revokedIds: [...raw.revoked_ids],
+        signatureValid: raw.signature_valid,
+    };
+}
+/** Signature authenticity of a receipt. Not authorization. */
+export function verifyReceipt(wire) {
+    let raw;
+    try {
+        raw = loadWasm().sdkVerifyReceipt(normalizeWireBytes(wire));
+    }
+    catch (error) {
+        throw new TenuoConfigurationError(errorMessage(error));
+    }
+    const out = {
+        authentic: true,
+        signerKey: raw.signer_key,
+        outcome: raw.outcome,
+        action: raw.action,
+        requestId: raw.request_id,
+    };
+    if (raw.decision_code !== undefined)
+        out.decisionCode = raw.decision_code;
+    if (raw.srl_version !== undefined)
+        out.srlVersion = raw.srl_version;
+    if (raw.srl_hash !== undefined)
+        out.srlHash = raw.srl_hash;
+    if (raw.request_hash !== undefined)
+        out.requestHash = raw.request_hash;
+    if (raw.policy_definition_hash !== undefined)
+        out.policyDefinitionHash = raw.policy_definition_hash;
+    if (raw.prev_receipt_hash !== undefined)
+        out.prevReceiptHash = raw.prev_receipt_hash;
+    if (raw.trusted_roots_hash !== undefined)
+        out.trustedRootsHash = raw.trusted_roots_hash;
+    return out;
+}
+/**
+ * Root-anchored receipt check: the embedded warrant chain against `roots`
+ * at the receipt's own decision instant. Needs no trust in the signer.
+ */
+export function verifyReceiptChain(wire, roots) {
+    if (!Array.isArray(roots) || roots.length === 0) {
+        throw new TenuoConfigurationError("verifyReceiptChain() requires at least one trusted root");
+    }
+    let raw;
+    try {
+        raw = loadWasm().sdkVerifyReceiptChain(normalizeWireBytes(wire), roots.map((r, i) => requirePublicKey(r, `roots[${i}]`).hex));
+    }
+    catch (error) {
+        throw new TenuoConfigurationError(errorMessage(error));
+    }
+    const out = {
+        signerKey: raw.signer_key,
+        outcome: raw.outcome,
+        timestamp: raw.timestamp,
+        chainValid: raw.chain_valid,
+    };
+    if (raw.decision_code !== undefined)
+        out.decisionCode = raw.decision_code;
+    if (raw.chain_error !== undefined)
+        out.chainError = raw.chain_error;
+    if (raw.corroborates_denial !== undefined)
+        out.corroboratesDenial = raw.corroborates_denial;
+    if (raw.root_issuer !== undefined)
+        out.rootIssuer = raw.root_issuer;
+    if (raw.leaf_holder !== undefined)
+        out.leafHolder = raw.leaf_holder;
+    return out;
+}
+/**
+ * The v1 JSON body a control plane's approval API accepts. Same shape the
+ * Python SDK produces, so one approval service serves both.
+ */
+export function controlPlaneApprovalRequestV1(request, options) {
+    if (request === null || typeof request !== "object" || typeof request.requestHash !== "string") {
+        throw new TenuoConfigurationError("controlPlaneApprovalRequestV1() needs an ApprovalRequest from tenuo.approvalRequest()");
+    }
+    const body = {
+        schema_version: 1,
+        request_id_hex: request.requestId,
+        warrant_id: request.warrantId,
+        tool: request.tool,
+        arguments: { ...request.args },
+        request_hash_hex: request.requestHash,
+        holder_public_key_hex: request.holderPublicKey,
+        required_approver_keys_hex: [...request.requiredApprovers],
+        min_approvals: Math.max(1, request.minApprovals),
+        warrant_expires_at_unix: request.warrantExpiresAt,
+        created_at_unix: request.createdAt,
+    };
+    if (options?.attestation !== undefined) {
+        const a = options.attestation;
+        body.attestation = {
+            version: a.version,
+            canonicalization: a.canonicalization,
+            warrant_id: a.warrantId,
+            tool: a.tool,
+            request_hash: a.requestHash,
+            holder_key_hex: a.holderKeyHex,
+            args_canonical_cbor_b64: a.argsCanonicalCborB64,
+            signer_key_hex: a.signerKeyHex,
+            signature_b64: a.signatureB64,
+            // Python readers look for these two names.
+            signer_key: a.signerKeyHex,
+            signature: a.signatureB64,
+        };
+    }
+    if (options?.temporal !== undefined && Object.keys(options.temporal).length > 0) {
+        body.temporal = { ...options.temporal };
+    }
+    if (request.message.length > 0) {
+        body.message = request.message;
+    }
+    return body;
+}
+/** Approval envelopes from a v1 response, ready for `{ approvals }` on the call. Empty unless status is a success. */
+export function signedApprovalsFromResponseV1(response) {
+    if (response === null || typeof response !== "object" || typeof response.status !== "string") {
+        throw new TenuoConfigurationError("approval response must be an object with a status");
+    }
+    if (response.status !== "approved") {
+        return [];
+    }
+    const list = response.signed_approvals_b64;
+    if (list === undefined || list === null) {
+        return [];
+    }
+    if (!Array.isArray(list) || list.some((item) => typeof item !== "string" || item.length === 0)) {
+        throw new TenuoConfigurationError("signed_approvals_b64 must be an array of base64 strings");
+    }
+    return [...list];
+}
 function createTenuoImpl(options = {}) {
     if (!hasTrustAnchor(options)) {
         throw new TenuoConfigurationError("createTenuo() requires trustedRoots or root: createTenuo.devRoot(). An empty trust set is not a configuration.");
@@ -413,5 +1025,23 @@ export const createTenuo = Object.assign(createTenuoImpl, {
     publicKeyFromBytes,
     holderKeyFromEnv,
     holderKeyFromHex,
+    generateHolderKey,
+    generateIssuerKey,
+    publicKeyFromHolderKey,
+    issuerKeyFromEnv,
+    issuerKeyFromHex,
+    issuerKeyFromBytes,
+    signApproval,
+    inspectApproval,
+    signRevocationList,
+    inspectRevocationList,
+    verifyReceipt,
+    verifyReceiptChain,
+    controlPlaneApprovalRequestV1,
+    signedApprovalsFromResponseV1,
+    parseConnectToken,
+    identity: identityFromKey,
+    generateIdentity,
+    runtime: (options) => createRuntime(createTenuoImpl, options),
 });
 //# sourceMappingURL=client.js.map