@iicp/web-node 0.1.0

package/dist/iicpConsumer.d.ts

@@ -0,0 +1,104 @@
+import { type CxPublicKey } from "./cxConfidentiality.js";
+export declare const DEFAULT_DIRECTORY_URL = "https://iicp.network";
+export interface ClientConfig {
+    /** Directory base URL. Default: https://iicp.network (CORS-enabled). */
+    directory_url?: string;
+    /** Per-request timeout (ms). Default 10000. */
+    timeout_ms?: number;
+}
+export interface DiscoverOptions {
+    region?: string;
+    min_reputation?: number;
+    /** Max nodes to return (directory caps at 50). */
+    limit?: number;
+    /** Browser pages should keep only HTTPS/loopback endpoints. Default: true. */
+    browser_usable_only?: boolean;
+}
+/** A discoverable provider node (public discovery view — no tokens/endpoints private). */
+export interface Node {
+    node_id: string;
+    endpoint: string;
+    region?: string;
+    reputation_score?: number;
+    reputation_tier?: string;
+    models?: string[];
+    directory_observed_reachable?: boolean | null;
+    route_evidence?: string;
+    routing_hint?: string;
+    browser_usable?: boolean;
+    [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). */
+export interface TaskEnvelope {
+    task_id: string;
+    intent: string;
+    constraints: Record<string, unknown>;
+    payload: {
+        messages: ChatMessage[];
+        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;
+/**
+ * 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;
+/** Browser-native, consumer-only IICP client. */
+export declare class IicpBrowserClient {
+    private readonly directory;
+    private readonly timeout;
+    constructor(cfg?: ClientConfig);
+    private getJson;
+    /** 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. */
+    stats(): Promise<Record<string, unknown>>;
+    /** Public node registry listing (GET /v1/registry/nodes). */
+    registry(): Promise<Record<string, unknown>>;
+    /**
+     * Route a chat to a node over the node's **HTTP transport**: `POST {endpoint}/v1/task`
+     * with the real task body `{ task_id, intent, payload, constraints }` (SDK-01/02 — same
+     * shape the @iicp/client Node SDK sends; the node replies `{ task_id, result, status,
+     * metrics }`). `payload` for llm:chat is `{ messages, model }`.
+     *
+     * Transport note: nodes also expose the **native IICP binary protocol on port 9484**
+     * (`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
+     * 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.
+     */
+    chat(messages: ChatMessage[], opts: {
+        endpoint: string;
+        intent?: string;
+        model?: string;
+        cxPublicKey?: CxPublicKey | null;
+    }): Promise<Record<string, unknown>>;
+}
+export declare function maskTunnelUrl(url: string): string;

package/dist/iicpConsumer.js

@@ -0,0 +1,201 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// iicpConsumer — the CONSUMER module of @iicp/web-node (discover + encrypted submit).
+//
+// A tiny (zero-runtime-dependency) TypeScript client for the IICP discovery mesh,
+// built on the browser's native fetch / TextEncoder / SubtleCrypto so it embeds
+// directly into a web page (and also runs in Node ≥18). It is the CONSUMER subset
+// of the protocol only — it never registers as a provider and carries no TCP / NAT /
+// relay machinery (that lives in the full @iicp/client Node SDK).
+//
+// Discovery (GET {directory}/v1/discover) works from any https:// page because
+// iicp.network sends CORS headers. Task routing to a discovered node, or to a local
+// LLM, is subject to browser CORS / mixed-content policy — see README "CORS reality".
+//
+// Epic: #446 · Dev: #447 · Research: research/wasm/WASM-1-feasibility.md (#292).
+import { encryptPayload } from "./cxConfidentiality.js";
+/** 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 class IicpError extends Error {
+    code;
+    status;
+    constructor(message, code, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.name = "IicpError";
+    }
+}
+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 },
+    };
+}
+/**
+ * Build the discover URL. Extracted so the query construction is unit-testable
+ * (same discipline as the federation event-log URL regression test).
+ */
+export function discoverUrl(directoryUrl, intent, opts = {}) {
+    const params = new URLSearchParams({ intent });
+    if (opts.region)
+        params.set("region", opts.region);
+    if (opts.min_reputation != null)
+        params.set("min_reputation", String(opts.min_reputation));
+    if (opts.limit != null)
+        params.set("limit", String(opts.limit));
+    // /api/v1 — the directory API prefix (verified against prod iicp.network 2026-06-04:
+    // /api/v1/discover → JSON {nodes,count,query_ms}; a bare /v1/discover hits the website's
+    // static HTML fallback, not the directory). Same /api/v1 lesson as the federation work.
+    return `${directoryUrl.replace(/\/+$/, "")}/api/v1/discover?${params}`;
+}
+function isBrowserUsableEndpoint(endpoint) {
+    try {
+        const url = new URL(endpoint);
+        if (url.protocol === "https:")
+            return true;
+        if (url.protocol !== "http:")
+            return false;
+        return ["localhost", "127.0.0.1", "::1"].includes(url.hostname.toLowerCase());
+    }
+    catch {
+        return false;
+    }
+}
+/** Browser-native, consumer-only IICP client. */
+export class IicpBrowserClient {
+    directory;
+    timeout;
+    constructor(cfg = {}) {
+        this.directory = (cfg.directory_url ?? DEFAULT_DIRECTORY_URL).replace(/\/+$/, "");
+        this.timeout = cfg.timeout_ms ?? 10_000;
+    }
+    async getJson(url) {
+        const ctrl = new AbortController();
+        const t = setTimeout(() => ctrl.abort(), this.timeout);
+        try {
+            const resp = await fetch(url, { signal: ctrl.signal, headers: { Accept: "application/json" } });
+            if (!resp.ok) {
+                throw new IicpError(`GET ${url} → ${resp.status}`, "http_error", resp.status);
+            }
+            return (await resp.json());
+        }
+        finally {
+            clearTimeout(t);
+        }
+    }
+    /** 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) => {
+            if (typeof node.browser_usable === "boolean")
+                return node.browser_usable;
+            return isBrowserUsableEndpoint(String(node.endpoint ?? ""));
+        });
+    }
+    /** Directory mesh stats (GET /v1/stats), incl. mesh_health + active_nodes. */
+    async stats() {
+        return this.getJson(`${this.directory}/api/v1/stats`);
+    }
+    /** Public node registry listing (GET /v1/registry/nodes). */
+    async registry() {
+        return this.getJson(`${this.directory}/api/v1/registry/nodes`);
+    }
+    /**
+     * Route a chat to a node over the node's **HTTP transport**: `POST {endpoint}/v1/task`
+     * with the real task body `{ task_id, intent, payload, constraints }` (SDK-01/02 — same
+     * shape the @iicp/client Node SDK sends; the node replies `{ task_id, result, status,
+     * metrics }`). `payload` for llm:chat is `{ messages, model }`.
+     *
+     * Transport note: nodes also expose the **native IICP binary protocol on port 9484**
+     * (`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
+     * 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 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)}`;
+        const payload = { messages, model: opts.model };
+        // IICP-CX S.16: encryption is MANDATORY (privacy-first #360) — no opt-out.
+        // Refuse keyless nodes instead of silently regressing to plaintext.
+        if (!opts.cxPublicKey) {
+            throw new IicpError("IICP-CX confidentiality required: node advertises no cx_public_key/public_key", "cx_required");
+        }
+        const body = {
+            task_id: taskId,
+            intent,
+            constraints: {},
+            iicp_conf: await encryptPayload(payload, opts.cxPublicKey, taskId, intent),
+        };
+        const ctrl = new AbortController();
+        const t = setTimeout(() => ctrl.abort(), this.timeout);
+        try {
+            const resp = await fetch(`${opts.endpoint.replace(/\/+$/, "")}/v1/task`, {
+                method: "POST",
+                signal: ctrl.signal,
+                headers: { "Content-Type": "application/json", Accept: "application/json" },
+                body: JSON.stringify(body),
+            });
+            if (!resp.ok) {
+                throw new IicpError(`task → ${resp.status}`, "node_error", resp.status);
+            }
+            return (await resp.json());
+        }
+        finally {
+            clearTimeout(t);
+        }
+    }
+}
+/**
+ * Mask the high-entropy random subdomain of an ephemeral tunnel endpoint for
+ * display (#privacy — maintainer 2026-06-12: keep tunnel DNS names private,
+ * like node UUIDs are shown only as prefixes). The random label of a
+ * *.trycloudflare.com (or other known tunnel-provider) host is a capability
+ * secret — anyone who learns it has a direct line to the operator's machine.
+ * Routing code keeps the real URL; only human-facing surfaces mask it.
+ * Operator-chosen public domains (e.g. iicp.shaal.dev) are left intact.
+ */
+const TUNNEL_SUFFIXES = [".trycloudflare.com", ".ngrok.io", ".ngrok-free.app", ".loca.lt"];
+export function maskTunnelUrl(url) {
+    try {
+        const u = new URL(url);
+        const suffix = TUNNEL_SUFFIXES.find((s) => u.hostname.endsWith(s));
+        if (!suffix)
+            return url;
+        return `${u.protocol}//****${suffix}${u.pathname === "/" ? "" : u.pathname}`;
+    }
+    catch {
+        return url;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./iicpConsumer.js";
+export * from "./cxConfidentiality.js";
+export * from "./browserNodeProvider.js";
+export * from "./webllmRuntime.js";

package/dist/index.js

@@ -0,0 +1,11 @@
+// @iicp/web-node — browser-native IICP node (consume AND serve), ESM, zero-config.
+//
+// The full browser node: a discovery-mesh CONSUMER (IicpBrowserClient) with MANDATORY
+// end-to-end encryption (IICP-CX S.16 — WebCrypto X25519 + AES-256-GCM, no opt-out), a
+// browser PROVIDER (BrowserNodeProvider — serve a model via WebLLM behind a relay), and
+// the WebLLM runtime helpers. Discovery + consume work from any https:// page; serving
+// needs a relay (see README). Parity with the Python/TS/Rust SDKs on the wire.
+export * from "./iicpConsumer.js";
+export * from "./cxConfidentiality.js";
+export * from "./browserNodeProvider.js";
+export * from "./webllmRuntime.js";

package/dist/webllmRuntime.d.ts

@@ -0,0 +1,140 @@
+import type { ChatMessage } from "./iicpConsumer.js";
+export type { ChatMessage };
+export interface WebLLMProgress {
+    /** Human-readable status description (e.g. "Loading model 23%"). */
+    text: string;
+    /** 0–1 fraction. 1 = fully loaded and ready. */
+    progress: number;
+}
+export type ProgressCallback = (p: WebLLMProgress) => void;
+/**
+ * Supported model IDs for UI display. Lineup (maintainer 2026-06-12): the two
+ * lightest variants run fine on ANY computer ("CPU" tier — integrated
+ * graphics, no dedicated card needed), plus one quality model that wants a
+ * dedicated GPU. tier drives the CPU/GPU badge on the picker.
+ * (Technically WebLLM always executes via WebGPU; the tier expresses the
+ * hardware a model needs to run WELL — tooltips carry that nuance.)
+ */
+export declare const WEBLLM_MODELS: {
+    readonly "Qwen2.5-0.5B-Instruct-q4f32_1-MLC": {
+        readonly label: "Qwen 2.5 0.5B";
+        readonly sizeMB: 350;
+        readonly tier: "cpu";
+        readonly description: "Lightest — runs on any computer, no graphics card needed";
+    };
+    readonly "Llama-3.2-1B-Instruct-q4f32_1-MLC": {
+        readonly label: "Llama 3.2 1B";
+        readonly sizeMB: 500;
+        readonly tier: "cpu";
+        readonly description: "Light and capable — fine on laptops with integrated graphics";
+    };
+    readonly "Llama-3.2-3B-Instruct-q4f32_1-MLC": {
+        readonly label: "Llama 3.2 3B";
+        readonly sizeMB: 1500;
+        readonly tier: "gpu";
+        readonly description: "Best quality — needs a dedicated graphics card (~4 GB VRAM)";
+    };
+};
+export type WebLLMModelId = keyof typeof WEBLLM_MODELS;
+export declare const DEFAULT_MODEL: WebLLMModelId;
+/**
+ * Coarse device-capability assessment for steering the model picker (#517 D4).
+ * Phones/tablets and low-memory machines frequently OOM loading even a 1B model,
+ * so the UI should nudge toward the lightest model or the WebGPU-free mesh path
+ * rather than letting a newcomer pick a model their device can't run.
+ *
+ * Signals: `navigator.deviceMemory` (GB, Chromium-only, coarse) + a UA mobile
+ * check. Best-effort — absence of a signal is treated as "ok".
+ */
+export type DeviceClass = "mobile" | "low" | "ok";
+export interface DeviceAssessment {
+    deviceClass: DeviceClass;
+    deviceMemoryGB: number | null;
+    /** Whether the GPU-tier (largest) model is likely to fail on this device. */
+    gpuModelRisky: boolean;
+    /** Plain-language steer, empty when the device looks capable. */
+    note: string;
+}
+export declare function assessDevice(): DeviceAssessment;
+export interface WebGPUCheckResult {
+    supported: boolean;
+    /** Present when unsupported — human-readable reason. */
+    reason?: string;
+}
+/**
+ * Detect WebGPU availability. Safe to call server-side (returns unsupported).
+ * Chrome 113+, Firefox nightly, Safari Technology Preview.
+ */
+export declare function detectWebGPU(): WebGPUCheckResult;
+/**
+ * Async WebGPU probe — the REAL availability signal. `detectWebGPU()` only
+ * checks that `navigator.gpu` exists, which some browsers expose while still
+ * being unable to run a model (e.g. Firefox surfaces `navigator.gpu` but has no
+ * usable adapter unless `dom.webgpu.enabled` is set, producing a false-positive
+ * "WebGPU available" badge — #518). This calls `requestAdapter()` to confirm a
+ * usable GPU, so UI that gates on it reflects reality, not just API presence.
+ */
+export declare function probeWebGPU(): Promise<WebGPUCheckResult>;
+/**
+ * Classify a load-failure message as out-of-memory (#517 D4). OOM is the most
+ * common real-device failure (phones / integrated GPUs); detecting it lets the
+ * UI steer to a smaller model or the mesh instead of a generic error. Matches
+ * the strings WebGPU/WebLLM/browsers surface for memory exhaustion.
+ */
+export declare function isOutOfMemoryError(message: string): boolean;
+export declare class WebLLMError extends Error {
+    readonly code: "webgpu_unavailable" | "not_loaded" | "load_failed" | "out_of_memory" | "inference_failed" | "bad_response";
+    constructor(message: string, code: "webgpu_unavailable" | "not_loaded" | "load_failed" | "out_of_memory" | "inference_failed" | "bad_response");
+}
+/**
+ * In-browser LLM runtime wrapping @mlc-ai/web-llm.
+ *
+ * Lifecycle: construct → canRun() check → load() → chat() → unload()
+ *
+ * Model weights are downloaded once and cached in IndexedDB by the WebLLM
+ * engine (automatic, per-origin). Subsequent loads skip the download.
+ *
+ * @example
+ * ```ts
+ * const rt = new WebLLMRuntime();
+ * if (!rt.canRun()) return; // WebGPU unavailable
+ * await rt.load('Llama-3.2-1B-Instruct-q4f32_1-MLC', p => setProgress(p));
+ * const reply = await rt.chat([{ role: 'user', content: 'Hello' }]);
+ * ```
+ */
+export declare class WebLLMRuntime {
+    private _engine;
+    private _modelId;
+    /** True if WebGPU is available in this browser/environment. */
+    canRun(): boolean;
+    /** True if a model is currently loaded and ready for inference. */
+    isLoaded(): boolean;
+    /** Currently loaded model ID, or null if not loaded. */
+    get modelId(): WebLLMModelId | null;
+    /**
+     * Load a model. First call downloads weights (~300–1500 MB) and caches them
+     * in IndexedDB. Subsequent calls with the same model skip the download.
+     *
+     * @param model  Model ID from WEBLLM_MODELS (default: Llama 3.2 1B q4)
+     * @param onProgress  Optional progress callback (text, 0–1 fraction)
+     * @throws WebLLMError  If WebGPU is unavailable or model load fails
+     */
+    load(model?: WebLLMModelId, onProgress?: ProgressCallback): Promise<void>;
+    /**
+     * CIP-compatible chat inference. Returns the assistant reply text.
+     * Provider glue (#452) calls this to satisfy llm:chat intent tasks.
+     * The model is fixed at load() time — pass a different modelId to load() to switch.
+     *
+     * @param messages  Chat history (system/user/assistant turns)
+     * @throws WebLLMError  If no model is loaded or inference fails
+     */
+    chat(messages: ChatMessage[], opts?: {
+        temperature?: number;
+        max_tokens?: number;
+    }): Promise<string>;
+    /**
+     * Unload the model and release GPU memory.
+     * Safe to call when not loaded (no-op).
+     */
+    unload(): Promise<void>;
+}