@iicp/web-node 0.1.0 → 0.2.1

package/README.md

@@ -26,6 +26,11 @@ const reply = await client.chat(
 );
 ```
 
+The client prefers short-lived dispatch tickets, falls back only when an older directory
+does not support them, and can enforce strict region and signed-policy-manifest constraints
+before a prompt is sent. Declared prohibited or high-risk public-mesh intents are refused
+locally. Successful routing receipts exclude prompt, response, token, and endpoint content.
+
 When the chosen node advertises an encryption key (`nodeCxKey(node)`), the payload is
 **sealed end-to-end** — the directory, relays, and network see only ciphertext. There is
 no opt-out. A node that does not advertise `cx_public_key`/`public_key` is refused before
@@ -42,6 +47,17 @@ Browser providers advertise a generated `cx_public_key`, decrypt incoming `iicp_
 payloads locally, report task success/failure/latency in heartbeats, and use a relay path
 because browser tabs cannot accept raw inbound TCP.
 
+Startup is intentionally ticketed: the provider registers, requests a short-lived relay
+bind ticket scoped to its worker and selected relay, and presents that ticket when it binds.
+Authentication or validation failures stop serving and clean up the temporary directory
+registration instead of silently falling back to an unsigned bind. Compatibility fallback
+is limited to directories that explicitly report that the ticket service is unavailable.
+
+Provider state includes deterministic recovery diagnostics (`stable`, `tunnel_starting`,
+`route_mismatch`, `operator_action_needed`, or `unavailable`) so a host page can explain
+whether it is directory-listed and relay-bound. Browser lifetime still matters: closing or
+suspending the tab stops the in-browser provider.
+
 Serving requires WebLLM — add it alongside this package:
 
 ```
@@ -57,8 +73,8 @@ TypeScript, and Rust IICP clients and the provider/adapter that decrypts it.
 
 ## CORS reality
 
-Discovery (`GET /api/v1/discover`) works from any `https://` page because `iicp.network`
-sends CORS headers. Routing a task to a discovered node is subject to the browser's CORS
+Public discovery and ticketed dispatch work from approved browser origins because
+`iicp.network` sends CORS headers. Routing a task to a selected node is subject to the browser's CORS
 and mixed-content policy: an `https://` page cannot reach an `http://localhost` model, a
 node without CORS headers, or an IPv6-firewalled node. In **Node** there is no CORS
 restriction and everything works.

package/dist/browserNodeProvider.d.ts

@@ -8,6 +8,8 @@ export interface BrowserProviderRuntime {
 export interface BrowserProviderConfig {
     /** Relay node base URL, e.g. "http://127.0.0.1:9484". Required. */
     relayUrl: string;
+    /** Auto-discovered relay node id. Used to audience-scope relay bind tickets. */
+    relayNodeId?: string;
     /** Directory API base. Default: "https://iicp.network/api". */
     directoryUrl?: string;
     /** Model name advertised to the directory (the loaded WebLLM model id). */
@@ -17,9 +19,19 @@ export interface BrowserProviderConfig {
     /** Called after each served task with the running total. */
     onTaskServed?: (total: number) => void;
     onStateChange?: (state: BrowserProviderState) => void;
+    onRecoveryChange?: (diagnostic: BrowserProviderDiagnostic) => void;
 }
 export type BrowserProviderState = "stopped" | "starting" | "serving" | "error";
-export declare const BROWSER_NODE_SDK_VERSION = "0.7.71-browser";
+export type BrowserProviderRecoveryState = "stable" | "tunnel_starting" | "route_mismatch" | "operator_action_needed" | "unavailable";
+export type BrowserProviderRecoveryAction = "none" | "reregister" | "wait_cooldown" | "operator_endpoint_needed";
+export interface BrowserProviderDiagnostic {
+    recovery_state: BrowserProviderRecoveryState;
+    recovery_action: BrowserProviderRecoveryAction;
+    directory_listed: boolean;
+    relay_bound: boolean;
+    tasks_served: number;
+}
+export declare const BROWSER_NODE_SDK_VERSION = "0.7.86-browser";
 /**
  * Coarse region autodetect from the browser's timezone (no network, no
  * geolocation permission). Matches the mesh's region convention
@@ -53,19 +65,26 @@ export declare class BrowserNodeProvider {
     private readonly _cx;
     private _heartbeatTimer;
     private _stopRequested;
+    private _recoveryState;
+    private _recoveryAction;
     /** True when the directory accepted the registration (mesh-discoverable). */
     directoryListed: boolean;
     constructor(runtime: BrowserProviderRuntime, cfg: BrowserProviderConfig);
     get state(): BrowserProviderState;
     get tasksServed(): number;
+    get diagnostic(): BrowserProviderDiagnostic;
     private get directoryBase();
     private get relayBase();
     private log;
     private setState;
-    /** Register → bind → start serving. Throws BrowserProviderError on failure. */
+    private setRecovery;
+    /** Register → obtain bind ticket → bind → serve. */
     start(): Promise<void>;
+    private register;
+    private fetchBindTicket;
     /** Unbind from the relay and deregister from the directory. */
     stop(): Promise<void>;
+    private deregisterQuietly;
     private unbindQuietly;
     private heartbeat;
     private pollLoop;

package/dist/browserNodeProvider.js

@@ -19,7 +19,7 @@
 import { maskTunnelUrl } from "./iicpConsumer.js";
 import { createCxKeyPair, decryptPayload } from "./cxConfidentiality.js";
 const CHAT_INTENT = "urn:iicp:intent:llm:chat:v1";
-export const BROWSER_NODE_SDK_VERSION = "0.7.71-browser";
+export const BROWSER_NODE_SDK_VERSION = "0.7.86-browser";
 /**
  * Coarse region autodetect from the browser's timezone (no network, no
  * geolocation permission). Matches the mesh's region convention
@@ -88,11 +88,18 @@ const MIN_RELAY_REPUTATION = 0.1; // hard floor — drop actively-demoted nodes
 export async function discoverRelay(directoryUrl = "https://iicp.network/api") {
     try {
         const base = directoryUrl.replace(/\/$/, "");
-        const resp = await fetch(`${base}/v1/discover?intent=${CHAT_INTENT}&relay_capable=true&limit=50`);
+        const resp = await fetch(`${base}/v1/dispatch/ticket`, {
+            method: "POST",
+            headers: { Accept: "application/json", "Content-Type": "application/json" },
+            body: JSON.stringify({ intent: CHAT_INTENT, relay_capable: true, limit: 1 }),
+        });
         if (!resp.ok)
             return null;
         const data = await resp.json();
-        const nodes = data?.nodes ?? [];
+        const route = data?.route;
+        const nodes = route && typeof route === "object"
+            ? [{ ...route, node_id: data?.node_id, relay_capable: true }]
+            : [];
         const isLoopback = (ep) => /^http:\/\/(localhost|127\.0\.0\.1)[:/]/.test(ep);
         const usable = nodes
             .filter((n) => n.relay_capable === true &&
@@ -144,6 +151,8 @@ export class BrowserNodeProvider {
     _cx = createCxKeyPair();
     _heartbeatTimer = null;
     _stopRequested = false;
+    _recoveryState = "unavailable";
+    _recoveryAction = "operator_endpoint_needed";
     /** True when the directory accepted the registration (mesh-discoverable). */
     directoryListed = false;
     constructor(runtime, cfg) {
@@ -157,6 +166,15 @@ export class BrowserNodeProvider {
     get tasksServed() {
         return this._tasksServed;
     }
+    get diagnostic() {
+        return {
+            recovery_state: this._recoveryState,
+            recovery_action: this._recoveryAction,
+            directory_listed: this.directoryListed,
+            relay_bound: Boolean(this._sessionToken),
+            tasks_served: this._tasksServed,
+        };
+    }
     get directoryBase() {
         return (this.cfg.directoryUrl ?? "https://iicp.network/api").replace(/\/$/, "");
     }
@@ -170,14 +188,30 @@ export class BrowserNodeProvider {
         this._state = s;
         this.cfg.onStateChange?.(s);
     }
-    /** Register → bind → start serving. Throws BrowserProviderError on failure. */
+    setRecovery(state, action) {
+        this._recoveryState = state;
+        this._recoveryAction = action;
+        this.cfg.onRecoveryChange?.(this.diagnostic);
+    }
+    /** Register → obtain bind ticket → bind → serve. */
     async start() {
         if (this._state === "serving" || this._state === "starting")
             return;
         this._stopRequested = false;
         this.setState("starting");
-        // 1. Bind to the relay FIRST — if no relay is reachable there is no point
-        //    holding a directory registration that consumers can't route to.
+        this.setRecovery("tunnel_starting", "wait_cooldown");
+        const endpoint = `${this.relayBase}/v1/relay-for/${this.nodeId}`;
+        // 1. Register first. Strict relays require a directory-issued bind ticket,
+        // which in turn requires the worker's node token. A failed later bind is
+        // immediately cleaned up so this ordering does not leave stale listings.
+        await this.register(endpoint);
+        // 2. Obtain a short-lived worker/audience-scoped bind ticket. Only an
+        // explicit older-directory response may use the legacy soft-bind path.
+        let bindTicket = "";
+        if (this._nodeToken) {
+            bindTicket = await this.fetchBindTicket();
+        }
+        // 3. Bind to the relay, presenting the ticket whenever one was issued.
         let bindResp;
         try {
             bindResp = await fetch(`${this.relayBase}/v1/relay/bind`, {
@@ -187,23 +221,37 @@ export class BrowserNodeProvider {
                     worker_id: this.nodeId,
                     intent: CHAT_INTENT,
                     models: [this.cfg.model],
+                    ...(bindTicket ? { bind_ticket: bindTicket } : {}),
                 }),
             });
         }
         catch (err) {
+            this.setRecovery("operator_action_needed", "operator_endpoint_needed");
             this.setState("error");
+            await this.deregisterQuietly();
             throw new BrowserProviderError(`relay unreachable at ${maskTunnelUrl(this.relayBase)}: ${err instanceof Error ? err.message : String(err)}`, "bind");
         }
         if (!bindResp.ok) {
             this.setState("error");
             const detail = await bindResp.text().catch(() => "");
+            await this.deregisterQuietly();
             throw new BrowserProviderError(`relay bind failed: HTTP ${bindResp.status} ${detail.slice(0, 200)}`, "bind");
         }
         const bind = await bindResp.json();
         this._sessionToken = bind.session_token;
+        this.setRecovery("route_mismatch", "reregister");
         this.log(`relay bound — worker ${this.nodeId}`);
-        // 2. Register with the directory, advertising the path-scoped relay endpoint.
-        const endpoint = `${this.relayBase}/v1/relay-for/${this.nodeId}`;
+        if (this.directoryListed)
+            this.setRecovery("stable", "none");
+        // 4. Heartbeat (only when directory-listed) + poll loop.
+        if (this.directoryListed) {
+            void this.heartbeat();
+            this._heartbeatTimer = setInterval(() => void this.heartbeat(), HEARTBEAT_MS);
+        }
+        this.setState("serving");
+        void this.pollLoop();
+    }
+    async register(endpoint) {
         try {
             const regResp = await fetch(`${this.directoryBase}/v1/register`, {
                 method: "POST",
@@ -229,7 +277,11 @@ export class BrowserNodeProvider {
                     },
                     sdk_language: "browser",
                     sdk_version: BROWSER_NODE_SDK_VERSION,
-                    backend: "webllm",
+                    // The current directory contract accepts native backend identifiers
+                    // plus "custom". Browser/WebLLM providers are non-native providers,
+                    // so advertise them as custom until the protocol taxonomy grows a
+                    // dedicated browser backend token.
+                    backend: "custom",
                     // IICP-CX S.16: browser providers are privacy-ready too.  The relay
                     // still sees metadata, but not the task payload.
                     cx_public_key: this._cx.publicKey,
@@ -252,18 +304,44 @@ export class BrowserNodeProvider {
             // node is not mesh-discoverable, but consumers that know the relay
             // endpoint can still dispatch — keep serving and say so plainly.
             this.directoryListed = false;
+            this.setRecovery("route_mismatch", "reregister");
             this.log(`directory registration rejected — serving relay-only (not discoverable): ${err instanceof Error ? err.message : String(err)}`);
         }
-        // 3. Heartbeat (only when directory-listed) + poll loop. Fire one
-        // immediately so the directory sees us as available without waiting a
-        // full interval, then keep alive every 30 s while the tab is open and the
-        // model stays loaded.
-        if (this.directoryListed) {
-            void this.heartbeat();
-            this._heartbeatTimer = setInterval(() => void this.heartbeat(), HEARTBEAT_MS);
+    }
+    async fetchBindTicket() {
+        let resp;
+        try {
+            resp = await fetch(`${this.directoryBase}/v1/relay/ticket`, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${this._nodeToken}`,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({ relay_node_id: this.cfg.relayNodeId ?? "*" }),
+            });
         }
-        this.setState("serving");
-        void this.pollLoop();
+        catch (err) {
+            await this.deregisterQuietly();
+            this.setState("error");
+            throw new BrowserProviderError(`relay bind ticket request failed: ${err instanceof Error ? err.message : String(err)}`, "bind");
+        }
+        if (resp.ok) {
+            const body = await resp.json();
+            if (typeof body.ticket !== "string" || !body.ticket) {
+                await this.deregisterQuietly();
+                throw new BrowserProviderError("directory returned no relay bind ticket", "bind");
+            }
+            return body.ticket;
+        }
+        const detail = await resp.text().catch(() => "");
+        const legacy = resp.status === 404 || (resp.status === 503 && detail.includes("not_configured"));
+        if (legacy) {
+            this.log("directory has no relay bind-ticket service — trying legacy soft bind");
+            return "";
+        }
+        await this.deregisterQuietly();
+        this.setState("error");
+        throw new BrowserProviderError(`relay bind ticket refused: HTTP ${resp.status} ${detail.slice(0, 200)}`, "bind");
     }
     /** Unbind from the relay and deregister from the directory. */
     async stop() {
@@ -273,22 +351,26 @@ export class BrowserNodeProvider {
             this._heartbeatTimer = null;
         }
         await this.unbindQuietly();
-        if (this._nodeToken) {
-            try {
-                await fetch(`${this.directoryBase}/v1/register`, {
-                    method: "DELETE",
-                    headers: { Authorization: `Bearer ${this._nodeToken}` },
-                    keepalive: true,
-                });
-                this.log("deregistered from directory");
-            }
-            catch {
-                // best-effort — heartbeat expiry cleans up server-side
-            }
-            this._nodeToken = "";
-        }
+        await this.deregisterQuietly();
         this.setState("stopped");
     }
+    async deregisterQuietly() {
+        if (!this._nodeToken)
+            return;
+        try {
+            await fetch(`${this.directoryBase}/v1/register`, {
+                method: "DELETE",
+                headers: { Authorization: `Bearer ${this._nodeToken}` },
+                keepalive: true,
+            });
+            this.log("deregistered from directory");
+        }
+        catch {
+            // best-effort — heartbeat expiry cleans up server-side
+        }
+        this._nodeToken = "";
+        this.directoryListed = false;
+    }
     async unbindQuietly() {
         if (!this._sessionToken)
             return;
@@ -307,6 +389,8 @@ export class BrowserNodeProvider {
             // best-effort — relay liveness window GCs the session
         }
         this._sessionToken = "";
+        if (!this._stopRequested)
+            this.setRecovery("operator_action_needed", "operator_endpoint_needed");
     }
     async heartbeat() {
         if (!this._nodeToken)
@@ -351,10 +435,12 @@ export class BrowserNodeProvider {
                 this.log(`keep-alive ✓ (model loaded${ok || fail ? `, +${ok} ok / +${fail} fail` : ""})`);
             }
             else {
+                this.setRecovery("route_mismatch", "reregister");
                 this.log(`keep-alive → HTTP ${resp.status}`);
             }
         }
         catch {
+            this.setRecovery("route_mismatch", "reregister");
             this.log("keep-alive failed (transient)");
         }
     }
@@ -376,6 +462,7 @@ export class BrowserNodeProvider {
                 continue; // idle window — poll again
             if (resp.status === 401) {
                 // Session displaced or GC'd — stop serving rather than fight over the id.
+                this.setRecovery("operator_action_needed", "operator_endpoint_needed");
                 this.log("relay session expired — stopping");
                 await this.stop();
                 this.setState("error");
@@ -408,6 +495,7 @@ export class BrowserNodeProvider {
             });
             // OpenAI-shape choices — exactly what SDK consumers' chat() parses.
             result = {
+                generated_by_ai: true,
                 result: {
                     choices: [
                         {

package/dist/iicpConsumer.d.ts

@@ -5,6 +5,21 @@ export interface ClientConfig {
     directory_url?: string;
     /** Per-request timeout (ms). Default 10000. */
     timeout_ms?: number;
+    /**
+     * Optional fail-closed transfer/region policy. When set, discovery and
+     * dispatch keep only nodes whose directory-safe `region` is in this list.
+     * Empty/omitted means normal open-mesh routing.
+     */
+    allowed_regions?: string[];
+    /**
+     * Optional fail-closed node-policy requirement. When set, discovery and
+     * dispatch keep only nodes whose directory-computed policy manifest identity
+     * level is at least this strong. This is a technical accountability signal,
+     * not legal/DPA compliance proof.
+     */
+    required_manifest_identity_level?: RequiredManifestIdentityLevel;
+    /** Ticketed route migration mode. Default: auto. */
+    route_discovery_mode?: "auto" | "ticketed" | "legacy";
 }
 export interface DiscoverOptions {
     region?: string;
@@ -13,7 +28,12 @@ export interface DiscoverOptions {
     limit?: number;
     /** Browser pages should keep only HTTPS/loopback endpoints. Default: true. */
     browser_usable_only?: boolean;
+    /** Optional per-discovery strict region allowlist; overrides client default. */
+    allowed_regions?: string[];
+    /** Optional per-discovery policy-manifest identity requirement; overrides client default. */
+    required_manifest_identity_level?: RequiredManifestIdentityLevel;
 }
+export type RequiredManifestIdentityLevel = "signed_valid" | "operator_bound" | "known_operator";
 /** A discoverable provider node (public discovery view — no tokens/endpoints private). */
 export interface Node {
     node_id: string;
@@ -26,18 +46,24 @@ export interface Node {
     route_evidence?: string;
     routing_hint?: string;
     browser_usable?: boolean;
+    node_policy_manifest?: {
+        manifest_identity_level?: string | null;
+        verification?: {
+            status?: string | null;
+        };
+    } | null;
+    dispatch_ticket_id_prefix?: string;
     [k: string]: unknown;
 }
 export interface ChatMessage {
     role: "system" | "user" | "assistant";
     content: string;
 }
-export declare class IicpError extends Error {
-    readonly code: string;
-    readonly status?: number | undefined;
-    constructor(message: string, code: string, status?: number | undefined);
-}
-/** CIP consumer task envelope — extracted for testability (KAT, parity with @iicp/client). */
+/**
+ * Compatibility helper for callers that need to inspect or test the canonical
+ * plaintext task shape. Production `chat()` remains fail-closed and sends only
+ * an encrypted `iicp_conf` envelope.
+ */
 export interface TaskEnvelope {
     task_id: string;
     intent: string;
@@ -47,28 +73,104 @@ export interface TaskEnvelope {
         model?: string;
     };
 }
-/**
- * Build the CIP consumer task envelope. Pure, deterministic (pass task_id for KAT).
- * Wire-protocol parity with the Node SDK: `POST {endpoint}/v1/task` when the caller
- * deliberately builds a plaintext test envelope. Production chat() below is fail-closed
- * and sends an `iicp_conf` envelope only.
- */
 export declare function cipConsumerEnvelope(messages: ChatMessage[], opts?: {
     intent?: string;
     model?: string;
     task_id?: string;
 }): TaskEnvelope;
+export interface RoutingReceipt {
+    receipt_version: "iicp-routing-receipt-v1";
+    trace_id: string;
+    task_id: string;
+    issued_at: string;
+    status: "attempted" | "ok";
+    intent: string;
+    generated_by_ai: true;
+    dispatch_ticket_id_prefix?: string;
+    selected_node: {
+        node_id_prefix?: string;
+        region?: string;
+        reputation_tier?: string;
+        reputation_score?: number;
+        model?: string;
+    };
+    transport: {
+        endpoint_kind: "https_public" | "https_tunnel" | "http_loopback" | "other" | "unknown";
+        relay_used: boolean;
+    };
+    policy: {
+        cx_required: true;
+        cx_key_status: "present";
+        cx_key_id?: string;
+        plaintext_allowed: false;
+        directory_prompt_free: true;
+        region_policy: "not_configured" | "allowed_regions_strict";
+        allowed_regions?: string[];
+        selected_region_allowed?: boolean;
+        region_policy_decision?: RegionPolicyDecision["reason"];
+        manifest_identity_policy: "not_configured" | "minimum_required";
+        required_manifest_identity_level?: RequiredManifestIdentityLevel;
+        selected_manifest_identity_level?: string;
+    };
+    redaction: {
+        prompt_content: "excluded";
+        response_content: "excluded";
+        node_token: "excluded";
+        endpoint_url: "not_recorded";
+    };
+}
+export interface RegionPolicyDecision {
+    active: boolean;
+    allowed_regions?: string[];
+    selected_region?: string;
+    selected_region_allowed?: boolean;
+    reason: "not_configured" | "allowed" | "missing_region" | "region_not_allowed";
+}
+export interface ManifestIdentityPolicyDecision {
+    active: boolean;
+    required_level?: RequiredManifestIdentityLevel;
+    selected_level?: string;
+    selected_level_allowed?: boolean;
+    reason: "not_configured" | "allowed" | "missing_manifest" | "insufficient_level" | "revoked_or_rotated";
+}
+export declare class IicpError extends Error {
+    readonly code: string;
+    readonly status?: number | undefined;
+    constructor(message: string, code: string, status?: number | undefined);
+}
 /**
  * Build the discover URL. Extracted so the query construction is unit-testable
  * (same discipline as the federation event-log URL regression test).
  */
 export declare function discoverUrl(directoryUrl: string, intent: string, opts?: DiscoverOptions): string;
+export declare function normalizeAllowedRegions(regions?: readonly string[] | null): string[];
+export declare function regionPolicyDecision(node: Node | undefined, allowedRegions?: readonly string[] | null): RegionPolicyDecision;
+export declare function filterNodesByAllowedRegions(nodes: Node[], allowedRegions?: readonly string[] | null): Node[];
+export declare function manifestIdentityPolicyDecision(node: Node | undefined, requiredLevel?: RequiredManifestIdentityLevel | null): ManifestIdentityPolicyDecision;
+export declare function filterNodesByManifestIdentity(nodes: Node[], requiredLevel?: RequiredManifestIdentityLevel | null): Node[];
+export declare function createRedactedRoutingReceipt(args: {
+    taskId: string;
+    intent: string;
+    endpoint?: string;
+    node?: Node;
+    model?: string;
+    cxPublicKey: CxPublicKey;
+    status?: RoutingReceipt["status"];
+    allowedRegions?: readonly string[] | null;
+    requiredManifestIdentityLevel?: RequiredManifestIdentityLevel | null;
+}): RoutingReceipt;
 /** Browser-native, consumer-only IICP client. */
 export declare class IicpBrowserClient {
     private readonly directory;
     private readonly timeout;
+    private readonly allowedRegions;
+    private readonly requiredManifestIdentityLevel?;
+    private readonly routeDiscoveryMode;
     constructor(cfg?: ClientConfig);
+    private effectiveAllowedRegions;
+    private effectiveManifestIdentityLevel;
     private getJson;
+    private ticketedDiscover;
     /** Discover nodes capable of an intent (GET /v1/discover — CORS-enabled on iicp.network). */
     discover(intent: string, opts?: DiscoverOptions): Promise<Node[]>;
     /** Directory mesh stats (GET /v1/stats), incl. mesh_health + active_nodes. */
@@ -85,11 +187,11 @@ export declare class IicpBrowserClient {
      * (`transport_endpoint: iicp://…`) — more efficient, used by the full SDKs. A browser
      * can't open raw TCP, so this client uses the HTTP transport (the discover `endpoint`).
      *
-     * Privacy: IICP-CX is fail-closed in the browser too.  A discovered node must
-     * advertise `cx_public_key` (or the temporary `public_key` alias) before this
-     * helper will send it a task.
-     *
-     * ⚠ Reachability: from an https:// page the browser reaches iicp.network (discover) but
+   * Privacy: IICP-CX is fail-closed in the browser too.  A discovered node must
+   * advertise `cx_public_key` (or the temporary `public_key` alias) before this
+   * helper will send it a task.
+   *
+   * ⚠ Reachability: from an https:// page the browser reaches iicp.network (discover) but
      * NOT http://localhost LLMs (mixed-content; Chrome 129+ flag only), nor a node without
      * CORS, nor an IPv6-firewalled node (today's live nodes are `ipv6_direct_firewall_required`).
      * Pass a reachable `endpoint`. In Node there is no CORS restriction. Returns the node JSON.
@@ -99,6 +201,25 @@ export declare class IicpBrowserClient {
         intent?: string;
         model?: string;
         cxPublicKey?: CxPublicKey | null;
+        node?: Node;
+        allowed_regions?: string[];
+        required_manifest_identity_level?: RequiredManifestIdentityLevel | null;
     }): Promise<Record<string, unknown>>;
+    /**
+     * Same dispatch as `chat()`, but returns a redacted routing receipt. The receipt
+     * deliberately excludes prompt text, response text, node tokens and endpoint URLs.
+     */
+    chatWithReceipt(messages: ChatMessage[], opts: {
+        endpoint: string;
+        intent?: string;
+        model?: string;
+        cxPublicKey?: CxPublicKey | null;
+        node?: Node;
+        allowed_regions?: string[];
+        required_manifest_identity_level?: RequiredManifestIdentityLevel | null;
+    }): Promise<{
+        response: Record<string, unknown>;
+        receipt: RoutingReceipt;
+    }>;
 }
 export declare function maskTunnelUrl(url: string): string;

package/dist/iicpConsumer.js

@@ -1,6 +1,8 @@
 // SPDX-License-Identifier: Apache-2.0
+// Browser-safe consumer used by @iicp/web-node and vendored by iicp.network.
+// Keep both copies aligned when publishing this package.
 //
-// iicpConsumer — the CONSUMER module of @iicp/web-node (discover + encrypted submit).
+// @iicp/web-node — browser-native IICP consumer module.
 //
 // A tiny (zero-runtime-dependency) TypeScript client for the IICP discovery mesh,
 // built on the browser's native fetch / TextEncoder / SubtleCrypto so it embeds
@@ -14,9 +16,36 @@
 //
 // Epic: #446 · Dev: #447 · Research: research/wasm/WASM-1-feasibility.md (#292).
 import { encryptPayload } from "./cxConfidentiality.js";
+const REFUSED_INTENT_RULES = [
+    { category: "prohibited", rule_id: "eu-ai-act-social-scoring", label: "social scoring", fragments: ["social-scoring", "social_scoring", "social:scoring"] },
+    { category: "prohibited", rule_id: "eu-ai-act-criminal-risk", label: "individual criminal risk prediction", fragments: ["criminal-risk", "criminal_risk", "criminal:risk", "predict-crime"] },
+    { category: "prohibited", rule_id: "eu-ai-act-workplace-education-emotion", label: "workplace or education emotion recognition", fragments: ["emotion:workplace", "emotion:education", "workplace-monitoring", "education-monitoring", "worker-monitoring"] },
+    { category: "prohibited", rule_id: "eu-ai-act-protected-trait-biometric", label: "biometric protected-trait classification", fragments: ["protected-trait", "protected_trait", "biometric:protected"] },
+    { category: "prohibited", rule_id: "eu-ai-act-untargeted-face-scraping", label: "untargeted facial image scraping", fragments: ["untargeted-scraping", "untargeted_scraping", "face-scraping", "facial-scraping"] },
+    { category: "prohibited", rule_id: "eu-ai-act-realtime-remote-biometric-id", label: "real-time remote biometric identification", fragments: ["remote-biometric:realtime", "realtime-remote-biometric", "real-time-remote-biometric"] },
+    { category: "prohibited", rule_id: "eu-ai-act-nonconsensual-sexual-deepfake", label: "non-consensual sexual deepfake or CSAM generation", fragments: ["nonconsensual-sexual", "non-consensual-sexual", "child-sexual-abuse", "csam"] },
+    { category: "high_risk", rule_id: "eu-ai-act-employment-workforce", label: "employment or workforce decision", fragments: ["employment:hiring", "employment:screen", "employment:rank", "recruitment:decision", "workforce:decision", "worker-management", "worker:performance", "worker:discipline"] },
+    { category: "high_risk", rule_id: "eu-ai-act-education-admission-grading", label: "education admission or grading decision", fragments: ["education:admission", "education:grading", "education:grade", "student:admission", "student:assess", "exam-grading"] },
+    { category: "high_risk", rule_id: "eu-ai-act-credit-essential-services", label: "credit or essential-services decision", fragments: ["credit-scoring", "credit:score", "credit:decision", "essential-services", "benefits:eligibility", "public-benefit:eligibility"] },
+    { category: "high_risk", rule_id: "eu-ai-act-law-enforcement-border-justice", label: "law enforcement, border, justice or democratic-process decision", fragments: ["law-enforcement", "law_enforcement", "migration:decision", "asylum:decision", "border-control", "justice:decision", "democratic-process", "election:decision"] },
+    { category: "high_risk", rule_id: "eu-ai-act-healthcare-critical-infrastructure", label: "healthcare or critical-infrastructure safety decision", fragments: ["healthcare:decision", "medical:diagnosis", "medical:triage", "clinical:decision", "critical-infrastructure", "grid:stabilize", "hospital:surge-capacity"] },
+    { category: "high_risk", rule_id: "eu-ai-act-physical-world-control", label: "physical-world control", fragments: ["robotics:control", "robotics:fleet", "drone:control", "drone:search", "iot:actuate", "physical-world", "system_control"] },
+];
 /** Intent URN shape — parity with @iicp/client (SDK-02). */
 const INTENT_RE = /^urn:iicp:intent:[a-z0-9_:/-]+$/;
 export const DEFAULT_DIRECTORY_URL = "https://iicp.network";
+export function cipConsumerEnvelope(messages, opts = {}) {
+    const intent = opts.intent ?? "urn:iicp:intent:llm:chat:v1";
+    validateIntent(intent);
+    const taskId = opts.task_id
+        ?? (globalThis.crypto?.randomUUID?.() ?? `task-${Date.now()}-${Math.random().toString(16).slice(2)}`);
+    return {
+        task_id: taskId,
+        intent,
+        constraints: {},
+        payload: { messages, model: opts.model },
+    };
+}
 export class IicpError extends Error {
     code;
     status;
@@ -27,28 +56,17 @@ export class IicpError extends Error {
         this.name = "IicpError";
     }
 }
+class LegacyDiscoveryRequired extends Error {
+}
 function validateIntent(intent) {
     if (!INTENT_RE.test(intent)) {
         throw new IicpError(`invalid intent URN: ${intent}`, "invalid_intent");
     }
-}
-/**
- * Build the CIP consumer task envelope. Pure, deterministic (pass task_id for KAT).
- * Wire-protocol parity with the Node SDK: `POST {endpoint}/v1/task` when the caller
- * deliberately builds a plaintext test envelope. Production chat() below is fail-closed
- * and sends an `iicp_conf` envelope only.
- */
-export function cipConsumerEnvelope(messages, opts = {}) {
-    const intent = opts.intent ?? "urn:iicp:intent:llm:chat:v1";
-    validateIntent(intent);
-    const taskId = opts.task_id ??
-        (globalThis.crypto?.randomUUID?.() ?? `task-${Date.now()}-${Math.random().toString(16).slice(2)}`);
-    return {
-        task_id: taskId,
-        intent,
-        constraints: {},
-        payload: { messages, model: opts.model },
-    };
+    const normalized = intent.trim().toLowerCase();
+    const rule = REFUSED_INTENT_RULES.find((candidate) => candidate.fragments.some((fragment) => normalized.includes(fragment)));
+    if (rule) {
+        throw new IicpError(`intent refused by public-mesh policy: ${rule.label} (${rule.rule_id}) [${rule.category}]`, "intent_policy_refused");
+    }
 }
 /**
  * Build the discover URL. Extracted so the query construction is unit-testable
@@ -80,13 +98,197 @@ function isBrowserUsableEndpoint(endpoint) {
         return false;
     }
 }
+function safeNodePrefix(nodeId) {
+    return typeof nodeId === "string" && nodeId.length > 0 ? `${nodeId.slice(0, 8)}…` : undefined;
+}
+function endpointKind(endpoint) {
+    if (!endpoint)
+        return "unknown";
+    try {
+        const url = new URL(endpoint);
+        const hostname = url.hostname.toLowerCase();
+        if (url.protocol === "https:" && TUNNEL_SUFFIXES.some((suffix) => hostname.endsWith(suffix)))
+            return "https_tunnel";
+        if (url.protocol === "https:")
+            return "https_public";
+        if (url.protocol === "http:" && ["localhost", "127.0.0.1", "::1"].includes(hostname))
+            return "http_loopback";
+    }
+    catch {
+        return "unknown";
+    }
+    return "other";
+}
+export function normalizeAllowedRegions(regions) {
+    if (!regions)
+        return [];
+    return Array.from(new Set(regions
+        .map((region) => region.trim().toLowerCase())
+        .filter((region) => region.length > 0))).sort();
+}
+function normalizeNodeRegion(node) {
+    const region = typeof node?.region === "string" ? node.region.trim().toLowerCase() : "";
+    return region.length > 0 ? region : undefined;
+}
+export function regionPolicyDecision(node, allowedRegions) {
+    const allowed = normalizeAllowedRegions(allowedRegions);
+    if (allowed.length === 0) {
+        return { active: false, reason: "not_configured" };
+    }
+    const selected = normalizeNodeRegion(node);
+    if (!selected) {
+        return {
+            active: true,
+            allowed_regions: allowed,
+            selected_region_allowed: false,
+            reason: "missing_region",
+        };
+    }
+    const ok = allowed.includes(selected);
+    return {
+        active: true,
+        allowed_regions: allowed,
+        selected_region: selected,
+        selected_region_allowed: ok,
+        reason: ok ? "allowed" : "region_not_allowed",
+    };
+}
+export function filterNodesByAllowedRegions(nodes, allowedRegions) {
+    const allowed = normalizeAllowedRegions(allowedRegions);
+    if (allowed.length === 0)
+        return nodes;
+    return nodes.filter((node) => regionPolicyDecision(node, allowed).selected_region_allowed === true);
+}
+const MANIFEST_IDENTITY_RANK = {
+    self_attested: 0,
+    signed_valid: 1,
+    operator_bound: 2,
+    known_operator: 3,
+    rotated: -1,
+    revoked: -1,
+};
+function manifestIdentityLevel(node) {
+    const level = node?.node_policy_manifest?.manifest_identity_level;
+    return typeof level === "string" && level.length > 0 ? level : undefined;
+}
+export function manifestIdentityPolicyDecision(node, requiredLevel) {
+    if (!requiredLevel) {
+        return { active: false, reason: "not_configured" };
+    }
+    const selected = manifestIdentityLevel(node);
+    if (!selected) {
+        return {
+            active: true,
+            required_level: requiredLevel,
+            selected_level_allowed: false,
+            reason: "missing_manifest",
+        };
+    }
+    if (selected === "revoked" || selected === "rotated") {
+        return {
+            active: true,
+            required_level: requiredLevel,
+            selected_level: selected,
+            selected_level_allowed: false,
+            reason: "revoked_or_rotated",
+        };
+    }
+    const ok = (MANIFEST_IDENTITY_RANK[selected] ?? -1) >= MANIFEST_IDENTITY_RANK[requiredLevel];
+    return {
+        active: true,
+        required_level: requiredLevel,
+        selected_level: selected,
+        selected_level_allowed: ok,
+        reason: ok ? "allowed" : "insufficient_level",
+    };
+}
+export function filterNodesByManifestIdentity(nodes, requiredLevel) {
+    if (!requiredLevel)
+        return nodes;
+    return nodes.filter((node) => manifestIdentityPolicyDecision(node, requiredLevel).selected_level_allowed === true);
+}
+function assertAllowedRegionForNode(node, allowedRegions) {
+    const decision = regionPolicyDecision(node, allowedRegions);
+    if (decision.active && decision.selected_region_allowed !== true) {
+        throw new IicpError(decision.reason === "missing_region"
+            ? "IICP strict region policy refused node before task dispatch: node region is missing"
+            : `IICP strict region policy refused node before task dispatch: region ${decision.selected_region ?? "unknown"} is not allowed`, "region_not_allowed");
+    }
+    return decision;
+}
+function assertManifestIdentityForNode(node, requiredLevel) {
+    const decision = manifestIdentityPolicyDecision(node, requiredLevel);
+    if (decision.active && decision.selected_level_allowed !== true) {
+        throw new IicpError(decision.reason === "missing_manifest"
+            ? `IICP strict policy refused node before task dispatch: missing policy manifest identity level ${requiredLevel}`
+            : `IICP strict policy refused node before task dispatch: manifest identity ${decision.selected_level ?? "unknown"} is below ${requiredLevel}`, "manifest_identity_not_allowed");
+    }
+    return decision;
+}
+export function createRedactedRoutingReceipt(args) {
+    const regionDecision = regionPolicyDecision(args.node, args.allowedRegions);
+    const manifestDecision = manifestIdentityPolicyDecision(args.node, args.requiredManifestIdentityLevel);
+    return {
+        receipt_version: "iicp-routing-receipt-v1",
+        trace_id: args.taskId,
+        task_id: args.taskId,
+        issued_at: new Date().toISOString(),
+        status: args.status ?? "attempted",
+        intent: args.intent,
+        generated_by_ai: true,
+        dispatch_ticket_id_prefix: args.node?.dispatch_ticket_id_prefix,
+        selected_node: {
+            node_id_prefix: safeNodePrefix(args.node?.node_id),
+            region: args.node?.region,
+            reputation_tier: typeof args.node?.reputation_tier === "string" ? args.node.reputation_tier : undefined,
+            reputation_score: typeof args.node?.reputation_score === "number" ? args.node.reputation_score : undefined,
+            model: args.model,
+        },
+        transport: {
+            endpoint_kind: endpointKind(args.endpoint),
+            relay_used: args.node?.relay_capable === true || args.node?.routing_hint === "relay",
+        },
+        policy: {
+            cx_required: true,
+            cx_key_status: "present",
+            cx_key_id: args.cxPublicKey.key_id,
+            plaintext_allowed: false,
+            directory_prompt_free: true,
+            region_policy: regionDecision.active ? "allowed_regions_strict" : "not_configured",
+            allowed_regions: regionDecision.allowed_regions,
+            selected_region_allowed: regionDecision.active ? regionDecision.selected_region_allowed : undefined,
+            region_policy_decision: regionDecision.active ? regionDecision.reason : undefined,
+            manifest_identity_policy: manifestDecision.active ? "minimum_required" : "not_configured",
+            required_manifest_identity_level: manifestDecision.required_level,
+            selected_manifest_identity_level: manifestDecision.selected_level,
+        },
+        redaction: {
+            prompt_content: "excluded",
+            response_content: "excluded",
+            node_token: "excluded",
+            endpoint_url: "not_recorded",
+        },
+    };
+}
 /** Browser-native, consumer-only IICP client. */
 export class IicpBrowserClient {
     directory;
     timeout;
+    allowedRegions;
+    requiredManifestIdentityLevel;
+    routeDiscoveryMode;
     constructor(cfg = {}) {
         this.directory = (cfg.directory_url ?? DEFAULT_DIRECTORY_URL).replace(/\/+$/, "");
         this.timeout = cfg.timeout_ms ?? 10_000;
+        this.allowedRegions = normalizeAllowedRegions(cfg.allowed_regions);
+        this.requiredManifestIdentityLevel = cfg.required_manifest_identity_level;
+        this.routeDiscoveryMode = cfg.route_discovery_mode ?? "auto";
+    }
+    effectiveAllowedRegions(override) {
+        return override !== undefined ? normalizeAllowedRegions(override) : this.allowedRegions;
+    }
+    effectiveManifestIdentityLevel(override) {
+        return override !== undefined ? (override ?? undefined) : this.requiredManifestIdentityLevel;
     }
     async getJson(url) {
         const ctrl = new AbortController();
@@ -102,18 +304,87 @@ export class IicpBrowserClient {
             clearTimeout(t);
         }
     }
+    async ticketedDiscover(intent, opts) {
+        const url = `${this.directory}/api/v1/dispatch/ticket`;
+        const excluded = [];
+        const nodes = [];
+        const limit = Math.max(1, Math.min(opts.limit ?? 4, 10));
+        for (let attempt = 0; attempt < limit; attempt += 1) {
+            const ctrl = new AbortController();
+            const timer = setTimeout(() => ctrl.abort(), this.timeout);
+            let response;
+            try {
+                response = await fetch(url, {
+                    method: "POST",
+                    signal: ctrl.signal,
+                    headers: { "Content-Type": "application/json", Accept: "application/json" },
+                    body: JSON.stringify({
+                        intent,
+                        region: opts.region,
+                        min_reputation: opts.min_reputation,
+                        limit,
+                        exclude_node_id_prefixes: excluded,
+                    }),
+                });
+            }
+            finally {
+                clearTimeout(timer);
+            }
+            const body = await response.json().catch(() => ({}));
+            const error = body.error;
+            const errorCode = typeof error?.code === "string" ? error.code : undefined;
+            if (response.status === 201) {
+                const route = body.route;
+                if (!route || typeof body.node_id !== "string") {
+                    throw new IicpError("ticketed route response is malformed", "ticket_malformed");
+                }
+                const node = {
+                    ...route,
+                    node_id: body.node_id,
+                    dispatch_ticket_id_prefix: typeof body.ticket_id_prefix === "string" ? body.ticket_id_prefix : undefined,
+                };
+                nodes.push(node);
+                excluded.push(body.node_id.slice(0, 8));
+                continue;
+            }
+            if (response.status === 404 && errorCode === "no_route_available")
+                break;
+            if ([404, 405, 501].includes(response.status) || (response.status === 503 && errorCode === "not_configured")) {
+                throw new LegacyDiscoveryRequired();
+            }
+            throw new IicpError(`ticketed route request refused (${errorCode ?? response.status})`, "ticket_refused", response.status);
+        }
+        return nodes;
+    }
     /** Discover nodes capable of an intent (GET /v1/discover — CORS-enabled on iicp.network). */
     async discover(intent, opts = {}) {
         validateIntent(intent);
-        const body = await this.getJson(discoverUrl(this.directory, intent, opts));
-        const nodes = Array.isArray(body) ? body : (body.nodes ?? []);
-        if (opts.browser_usable_only === false)
-            return nodes;
-        return nodes.filter((node) => {
+        let nodes;
+        if (this.routeDiscoveryMode === "legacy") {
+            const body = await this.getJson(discoverUrl(this.directory, intent, opts));
+            nodes = Array.isArray(body) ? body : (body.nodes ?? []);
+        }
+        else {
+            try {
+                nodes = await this.ticketedDiscover(intent, opts);
+            }
+            catch (error) {
+                if (!(error instanceof LegacyDiscoveryRequired))
+                    throw error;
+                if (this.routeDiscoveryMode === "ticketed") {
+                    throw new IicpError("directory does not support ticketed dispatch", "ticket_unavailable");
+                }
+                const body = await this.getJson(discoverUrl(this.directory, intent, opts));
+                nodes = Array.isArray(body) ? body : (body.nodes ?? []);
+            }
+        }
+        const browserUsableNodes = opts.browser_usable_only === false ? nodes : nodes.filter((node) => {
             if (typeof node.browser_usable === "boolean")
                 return node.browser_usable;
             return isBrowserUsableEndpoint(String(node.endpoint ?? ""));
         });
+        const regionFiltered = filterNodesByAllowedRegions(browserUsableNodes, this.effectiveAllowedRegions(opts.allowed_regions));
+        return filterNodesByManifestIdentity(regionFiltered, this.effectiveManifestIdentityLevel(opts.required_manifest_identity_level));
     }
     /** Directory mesh stats (GET /v1/stats), incl. mesh_health + active_nodes. */
     async stats() {
@@ -133,16 +404,24 @@ export class IicpBrowserClient {
      * (`transport_endpoint: iicp://…`) — more efficient, used by the full SDKs. A browser
      * can't open raw TCP, so this client uses the HTTP transport (the discover `endpoint`).
      *
-     * Privacy: IICP-CX is fail-closed in the browser too.  A discovered node must
-     * advertise `cx_public_key` (or the temporary `public_key` alias) before this
-     * helper will send it a task.
-     *
-     * ⚠ Reachability: from an https:// page the browser reaches iicp.network (discover) but
+   * Privacy: IICP-CX is fail-closed in the browser too.  A discovered node must
+   * advertise `cx_public_key` (or the temporary `public_key` alias) before this
+   * helper will send it a task.
+   *
+   * ⚠ Reachability: from an https:// page the browser reaches iicp.network (discover) but
      * NOT http://localhost LLMs (mixed-content; Chrome 129+ flag only), nor a node without
      * CORS, nor an IPv6-firewalled node (today's live nodes are `ipv6_direct_firewall_required`).
      * Pass a reachable `endpoint`. In Node there is no CORS restriction. Returns the node JSON.
      */
     async chat(messages, opts) {
+        const routed = await this.chatWithReceipt(messages, opts);
+        return routed.response;
+    }
+    /**
+     * Same dispatch as `chat()`, but returns a redacted routing receipt. The receipt
+     * deliberately excludes prompt text, response text, node tokens and endpoint URLs.
+     */
+    async chatWithReceipt(messages, opts) {
         const intent = opts.intent ?? "urn:iicp:intent:llm:chat:v1";
         validateIntent(intent);
         const taskId = globalThis.crypto?.randomUUID?.() ?? `task-${Date.now()}-${Math.random().toString(16).slice(2)}`;
@@ -152,6 +431,21 @@ export class IicpBrowserClient {
         if (!opts.cxPublicKey) {
             throw new IicpError("IICP-CX confidentiality required: node advertises no cx_public_key/public_key", "cx_required");
         }
+        const allowedRegions = this.effectiveAllowedRegions(opts.allowed_regions);
+        const requiredManifestIdentityLevel = this.effectiveManifestIdentityLevel(opts.required_manifest_identity_level);
+        assertAllowedRegionForNode(opts.node, allowedRegions);
+        assertManifestIdentityForNode(opts.node, requiredManifestIdentityLevel);
+        const receipt = createRedactedRoutingReceipt({
+            taskId,
+            intent,
+            endpoint: opts.endpoint,
+            node: opts.node,
+            model: opts.model,
+            cxPublicKey: opts.cxPublicKey,
+            status: "attempted",
+            allowedRegions,
+            requiredManifestIdentityLevel,
+        });
         const body = {
             task_id: taskId,
             intent,
@@ -170,7 +464,10 @@ export class IicpBrowserClient {
             if (!resp.ok) {
                 throw new IicpError(`task → ${resp.status}`, "node_error", resp.status);
             }
-            return (await resp.json());
+            return {
+                response: (await resp.json()),
+                receipt: { ...receipt, status: "ok", issued_at: new Date().toISOString() },
+            };
         }
         finally {
             clearTimeout(t);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iicp/web-node",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Browser-native IICP node (consume + serve): discovery-mesh client with mandatory E2E encryption (IICP-CX) + WebLLM provider. Zero-config, ESM.",
   "type": "module",
   "main": "dist/index.js",