@iicp/web-node 0.2.0 → 0.2.2

package/README.md

@@ -47,6 +47,12 @@ 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

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). */
@@ -29,7 +31,7 @@ export interface BrowserProviderDiagnostic {
     relay_bound: boolean;
     tasks_served: number;
 }
-export declare const BROWSER_NODE_SDK_VERSION = "0.7.84-browser";
+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
@@ -76,10 +78,13 @@ export declare class BrowserNodeProvider {
     private log;
     private setState;
     private setRecovery;
-    /** Register → bind → start serving. Throws BrowserProviderError on failure. */
+    /** 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.84-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
@@ -193,15 +193,25 @@ export class BrowserNodeProvider {
         this._recoveryAction = action;
         this.cfg.onRecoveryChange?.(this.diagnostic);
     }
-    /** Register → bind → start serving. Throws BrowserProviderError on failure. */
+    /** Register → obtain bind ticket → bind → serve. */
     async start() {
         if (this._state === "serving" || this._state === "starting")
             return;
         this._stopRequested = false;
         this.setState("starting");
         this.setRecovery("tunnel_starting", "wait_cooldown");
-        // 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.
+        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`, {
@@ -211,25 +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",
@@ -274,7 +296,6 @@ export class BrowserNodeProvider {
             if (!this._nodeToken)
                 throw new Error("directory returned no node_token");
             this.directoryListed = true;
-            this.setRecovery("stable", "none");
             this.log(`registered with directory as ${this.nodeId}`);
         }
         catch (err) {
@@ -286,16 +307,45 @@ export class BrowserNodeProvider {
             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",
+                    // Opaque node tokens need an explicit subject hint; JWT-backed
+                    // clients can be resolved from their claims, but browser providers
+                    // intentionally use the portable opaque registration credential.
+                    "X-Node-Id": this.nodeId,
+                },
+                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() {
@@ -305,22 +355,30 @@ 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}`,
+                    // Opaque registration credentials carry no subject claim.
+                    "X-Node-Id": this.nodeId,
+                },
+                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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iicp/web-node",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "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",