@iicp/web-node 0.2.4 → 0.2.6

package/README.md

@@ -5,6 +5,11 @@ from the network *and* **serve** a model from a browser tab. ESM, built on the p
 native `fetch` / `SubtleCrypto` / WebGPU (and runs in Node ≥18). The browser
 client refuses keyless providers rather than silently sending plaintext.
 
+IICP supplies intent resolution and provider eligibility/selection. MCP, A2A,
+HTTP or another negotiated binding may then execute the selected task. See the
+public [protocol positioning](https://github.com/RobLe3/IICP/blob/main/standards/IICP_PROTOCOL_POSITIONING.md)
+and [adjacent-protocol comparison](https://github.com/RobLe3/IICP/blob/main/standards/PROTOCOL_COMPARISON_2026-08-15.md).
+
 ```
 npm install @iicp/web-node
 ```
@@ -31,11 +36,33 @@ does not support them, and can enforce strict region and signed-policy-manifest
 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.
 
+Restricted trust-domain, federated-private, local-only and custom operating
+modes are not supported by the browser package yet. Passing an explicit
+non-public `operating_mode` to `IicpBrowserClient`, or `operatingMode` to
+`BrowserNodeProvider`, throws `restricted_profile_unsupported` during
+construction, before discovery, registration or relay traffic. The package
+does not persist membership credentials in browser storage and never downgrades
+an explicit private mode to the public directory.
+
 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
 any network send so browser use cannot silently fall back to plaintext.
 
+## Runtime self-description
+
+Browser `chat()` calls add a small IICP runtime identity context by default. It
+tells the selected model that it is being accessed through IICP, identifies the
+active intent and browser package version, and includes a model or capability
+fact only when it comes from the selected node's advertisement. It does not
+expose endpoints, full node identities, candidate sets, scores or credentials,
+and it is not a prompt-injection security boundary.
+
+Set `runtime_identity: { mode: "disabled" }` to preserve the application
+messages without the capsule, or use `mode: "required"` to refuse when a
+supported instruction channel is unavailable. Non-chat operations and the
+plaintext envelope helper remain unchanged.
+
 ## Serve — be a node from the browser
 
 ```ts

package/dist/browserNodeProvider.d.ts

@@ -1,5 +1,6 @@
 import type { ChatMessage } from "./iicpConsumer.js";
 import type { EffectiveCapability } from "./effectiveCapability.js";
+import { type BrowserOperatingMode } from "./operatingMode.js";
 export interface BrowserProviderRuntime {
     chat(messages: ChatMessage[], opts?: {
         temperature?: number;
@@ -7,6 +8,8 @@ export interface BrowserProviderRuntime {
     }): Promise<string>;
 }
 export interface BrowserProviderConfig {
+    /** Explicit operating mode. Browser CUG/local modes currently fail closed. */
+    operatingMode?: BrowserOperatingMode;
     /** 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. */

package/dist/browserNodeProvider.js

@@ -18,6 +18,7 @@
 // consumers route to a browser worker with zero client changes.
 import { maskTunnelUrl } from "./iicpConsumer.js";
 import { createCxKeyPair, decryptPayload } from "./cxConfidentiality.js";
+import { requireSupportedBrowserMode } from "./operatingMode.js";
 import { BROWSER_NODE_SDK_COMPATIBILITY_VERSION, BROWSER_NODE_SDK_VERSION, BROWSER_NODE_VERSION, } from "./version.js";
 const CHAT_INTENT = "urn:iicp:intent:llm:chat:v1";
 export { BROWSER_NODE_SDK_VERSION } from "./version.js";
@@ -172,6 +173,7 @@ export class BrowserNodeProvider {
     constructor(runtime, cfg) {
         this.runtime = runtime;
         this.cfg = cfg;
+        requireSupportedBrowserMode(cfg.operatingMode);
         this.nodeId = `browser-${crypto.randomUUID().slice(0, 8)}`;
     }
     get state() {

package/dist/build-manifest.json

@@ -1,8 +1,8 @@
 {
   "schema": "iicp.browser_build_provenance.v1",
   "package": "@iicp/web-node",
-  "implementation_version": "0.2.4",
+  "implementation_version": "0.2.6",
   "sdk_compatibility_version": "0.7.102",
-  "source_commit": "c26bf228708a5bfad0f8574407ea1a45e4d377c7",
-  "lockfile_sha256": "54183560d240a4f8573274dfab6dda6c297fc1bcbe5ae18b12d5fa5c801f0ffe"
+  "source_commit": "2d839c075c649ca8320af1734845862c8265588f",
+  "lockfile_sha256": "3a86e8b68bd9cee5ab5f99b1975b75db0ed924fe582873b9590f0047bb87eea1"
 }

package/dist/iicpConsumer.d.ts

@@ -1,7 +1,10 @@
 import { type CxPublicKey } from "./cxConfidentiality.js";
 import { type RuntimeIdentityOptions } from "./runtimeIdentity.js";
+import { type BrowserOperatingMode } from "./operatingMode.js";
 export declare const DEFAULT_DIRECTORY_URL = "https://iicp.network";
 export interface ClientConfig {
+    /** Explicit operating mode. Browser CUG/local modes currently fail closed. */
+    operating_mode?: BrowserOperatingMode;
     /** Directory base URL. Default: https://iicp.network (CORS-enabled). */
     directory_url?: string;
     /** Per-request timeout (ms). Default 10000. */
@@ -170,7 +173,6 @@ export declare function createRedactedRoutingReceipt(args: {
     allowedRegions?: readonly string[] | null;
     requiredManifestIdentityLevel?: RequiredManifestIdentityLevel | null;
 }): RoutingReceipt;
-/** Browser-native, consumer-only IICP client. */
 export declare class IicpBrowserClient {
     private readonly directory;
     private readonly timeout;

package/dist/iicpConsumer.js

@@ -17,7 +17,9 @@
 // Epic: #446 · Dev: #447 · Research: research/wasm/WASM-1-feasibility.md (#292).
 import { encryptPayload } from "./cxConfidentiality.js";
 import { verifyDispatchTicket } from "./dispatchTicket.js";
-import { composeRuntimeIdentity } from "./runtimeIdentity.js";
+import { composeRuntimeIdentity, withRuntimeFacts } from "./runtimeIdentity.js";
+import { BROWSER_NODE_VERSION } from "./version.js";
+import { requireSupportedBrowserMode } from "./operatingMode.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"] },
@@ -273,6 +275,41 @@ export function createRedactedRoutingReceipt(args) {
     };
 }
 /** Browser-native, consumer-only IICP client. */
+function selectedAdvertisedModel(node, requestedModel) {
+    if (requestedModel && node?.models?.includes(requestedModel))
+        return requestedModel;
+    return node?.models?.length === 1 ? node.models[0] : undefined;
+}
+function effectiveCapabilityLabels(node, intent, model) {
+    const raw = node?.capabilities;
+    if (!Array.isArray(raw))
+        return [];
+    const variants = raw.filter((candidate) => Boolean(candidate) && typeof candidate === "object" && candidate.intent === intent);
+    const exact = model
+        ? variants.filter((candidate) => Array.isArray(candidate.models) && candidate.models.includes(model))
+        : variants;
+    const selected = exact.length === 1 ? exact[0] : variants.length === 1 ? variants[0] : undefined;
+    if (!selected)
+        return [];
+    const labels = [];
+    for (const value of Array.isArray(selected.input_modalities) ? selected.input_modalities : []) {
+        if (typeof value === "string")
+            labels.push(`input_modality:${value}`);
+    }
+    for (const value of Array.isArray(selected.output_modalities) ? selected.output_modalities : []) {
+        if (typeof value === "string")
+            labels.push(`output_modality:${value}`);
+    }
+    for (const value of Array.isArray(selected.features) ? selected.features : []) {
+        if (typeof value === "string")
+            labels.push(value);
+    }
+    for (const value of Array.isArray(selected.execution_capabilities) ? selected.execution_capabilities : []) {
+        if (typeof value === "string")
+            labels.push(`execution:${value}`);
+    }
+    return [...new Set(labels)].sort();
+}
 export class IicpBrowserClient {
     directory;
     timeout;
@@ -281,6 +318,7 @@ export class IicpBrowserClient {
     routeDiscoveryMode;
     dispatchTicketKey;
     constructor(cfg = {}) {
+        requireSupportedBrowserMode(cfg.operating_mode);
         this.directory = (cfg.directory_url ?? DEFAULT_DIRECTORY_URL).replace(/\/+$/, "");
         this.timeout = cfg.timeout_ms ?? 10_000;
         this.allowedRegions = normalizeAllowedRegions(cfg.allowed_regions);
@@ -444,7 +482,15 @@ export class IicpBrowserClient {
     async chatWithReceipt(messages, opts) {
         const intent = opts.intent ?? "urn:iicp:intent:llm:chat:v1";
         validateIntent(intent);
-        messages = composeRuntimeIdentity(messages, intent, opts.runtime_identity);
+        const selectedModel = selectedAdvertisedModel(opts.node, opts.model);
+        messages = composeRuntimeIdentity(messages, intent, withRuntimeFacts(opts.runtime_identity, {
+            client_name: "@iicp/web-node",
+            client_version: BROWSER_NODE_VERSION,
+            connection_mode: "routed",
+            selected_model: selectedModel,
+            effective_capabilities: effectiveCapabilityLabels(opts.node, intent, selectedModel),
+            selection_reason: "matched_intent_and_constraints",
+        }));
         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.

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export * from "./dispatchTicket.js";
 export * from "./cxConfidentiality.js";
 export * from "./effectiveCapability.js";
 export * from "./runtimeIdentity.js";
+export * from "./operatingMode.js";
 export * from "./browserNodeProvider.js";
 export * from "./webllmRuntime.js";
 export * from "./version.js";

package/dist/index.js

@@ -10,6 +10,7 @@ export * from "./dispatchTicket.js";
 export * from "./cxConfidentiality.js";
 export * from "./effectiveCapability.js";
 export * from "./runtimeIdentity.js";
+export * from "./operatingMode.js";
 export * from "./browserNodeProvider.js";
 export * from "./webllmRuntime.js";
 export * from "./version.js";

package/dist/operatingMode.d.ts

@@ -0,0 +1,4 @@
+export type BrowserOperatingMode = "public" | "private" | "federated_private" | "local_only" | "custom";
+export declare const RESTRICTED_BROWSER_UNSUPPORTED = "restricted_profile_unsupported";
+/** Refuse unsupported modes before discovery, registration or relay work. */
+export declare function requireSupportedBrowserMode(mode?: BrowserOperatingMode): void;

package/dist/operatingMode.js

@@ -0,0 +1,8 @@
+// SPDX-License-Identifier: Apache-2.0
+export const RESTRICTED_BROWSER_UNSUPPORTED = "restricted_profile_unsupported";
+/** Refuse unsupported modes before discovery, registration or relay work. */
+export function requireSupportedBrowserMode(mode = "public") {
+    if (mode !== "public") {
+        throw new Error(RESTRICTED_BROWSER_UNSUPPORTED);
+    }
+}

package/dist/runtimeIdentity.d.ts

@@ -3,17 +3,26 @@ export declare const RUNTIME_IDENTITY_PROFILE_ID = "urn:iicp:profile:runtime-ide
 export declare const RUNTIME_IDENTITY_MARKER = "IICP-RUNTIME-CONTEXT/1";
 export declare const RUNTIME_IDENTITY_CHAT_INTENT = "urn:iicp:intent:llm:chat:v1";
 export declare const RUNTIME_IDENTITY_MAX_BYTES = 2048;
-export type RuntimeIdentityMode = "disabled" | "explicit" | "required";
+export declare const CANONICAL_IICP_EXPLANATION = "IICP is the Intent-based Inter-agent Communication Protocol: a provider-neutral control plane that discovers eligible intelligence services, evaluates them under explicit constraints, selects a provider, and leaves execution to a supported provider mechanism.";
+export declare function isDirectIicpExplainer(prompt: string): boolean;
+export declare function validIicpExplanation(answer: string): boolean;
+export type RuntimeIdentityMode = "auto" | "disabled" | "explicit" | "required";
 export type RuntimeIdentityInstructionChannel = "system" | "unsupported";
+export type RuntimeIdentityConnectionMode = "routed" | "local_browser";
+export type RuntimeIdentitySelectionReason = "matched_intent_and_constraints" | "explicit_model_match" | "fallback_after_unavailable_candidate" | "intentional_exploration" | "local_browser_execution";
 export interface RuntimeIdentityOptions {
     mode?: RuntimeIdentityMode;
     instruction_channel?: RuntimeIdentityInstructionChannel;
     selected_model?: string;
     effective_capabilities?: string[];
-    selection_reason?: "matched_intent_and_constraints";
+    selection_reason?: RuntimeIdentitySelectionReason;
+    client_name?: string;
+    client_version?: string;
+    connection_mode?: RuntimeIdentityConnectionMode;
 }
 export declare class RuntimeIdentityContextUnsupported extends Error {
     constructor();
 }
+export declare function withRuntimeFacts(options: RuntimeIdentityOptions | undefined, facts: Required<Pick<RuntimeIdentityOptions, "client_name" | "client_version" | "connection_mode" | "selection_reason">> & Pick<RuntimeIdentityOptions, "selected_model" | "effective_capabilities">): RuntimeIdentityOptions;
 export declare function renderRuntimeIdentity(intent: string, options: RuntimeIdentityOptions): string;
 export declare function composeRuntimeIdentity(messages: readonly ChatMessage[], intent: string, options?: RuntimeIdentityOptions): ChatMessage[];

package/dist/runtimeIdentity.js

@@ -2,22 +2,79 @@ export const RUNTIME_IDENTITY_PROFILE_ID = "urn:iicp:profile:runtime-identity-co
 export const RUNTIME_IDENTITY_MARKER = "IICP-RUNTIME-CONTEXT/1";
 export const RUNTIME_IDENTITY_CHAT_INTENT = "urn:iicp:intent:llm:chat:v1";
 export const RUNTIME_IDENTITY_MAX_BYTES = 2048;
-const BASE_CAPSULE = "This request reached you through IICP, the Intent-based Inter-agent Communication Protocol. IICP discovers eligible services and routes requests. You are the selected model or service, not IICP. When asked about this connection, use only supplied runtime facts; do not guess missing facts.";
+const MAX_FACT_BYTES = 160;
+const MAX_CAPABILITIES = 32;
+export const CANONICAL_IICP_EXPLANATION = "IICP is the Intent-based Inter-agent Communication Protocol: a provider-neutral control plane that discovers eligible intelligence services, evaluates them under explicit constraints, selects a provider, and leaves execution to a supported provider mechanism.";
+export function isDirectIicpExplainer(prompt) {
+    const value = prompt.trim().toLowerCase().replace(/[.?!]+$/u, "");
+    return ["what is iicp", "what does iicp stand for", "explain iicp", "describe iicp", "what is this"].includes(value);
+}
+export function validIicpExplanation(answer) {
+    const value = answer.toLowerCase();
+    return value.includes("intent-based inter-agent communication protocol")
+        && (value.includes("control plane") || value.includes("discover"))
+        && !value.includes("industrial internet of things computing");
+}
+const BASE_CAPSULE = "This request reached you through IICP, the Intent-based Inter-agent Communication Protocol. IICP is a provider-neutral control plane that turns a requested intent and constraints into discovery, eligibility evaluation and provider selection; execution then uses a supported provider mechanism. You are the selected model or service, not IICP. If asked what IICP is or stands for, use this definition. IICP does not mean Industrial Internet of Things Computing. Use only supplied runtime facts and do not guess missing facts.";
 export class RuntimeIdentityContextUnsupported extends Error {
     constructor() {
         super("required_identity_context_unsupported");
         this.name = "RuntimeIdentityContextUnsupported";
     }
 }
+const selectionText = {
+    matched_intent_and_constraints: "This service matched the requested intent and constraints.",
+    explicit_model_match: "This service matched the requested model and constraints.",
+    fallback_after_unavailable_candidate: "This service was selected after an earlier candidate was unavailable.",
+    intentional_exploration: "This service was selected for an intentional routing exploration.",
+    local_browser_execution: "This model is running locally in the browser.",
+};
+export function withRuntimeFacts(options, facts) {
+    return {
+        ...(options ?? {}),
+        ...facts,
+        selected_model: facts.selected_model,
+        effective_capabilities: [...(facts.effective_capabilities ?? [])],
+    };
+}
+function boundedFact(value, name) {
+    if (!value || /[\u0000-\u001f\u007f]/u.test(value)) {
+        throw new Error(`runtime identity ${name} contains control characters`);
+    }
+    if (new TextEncoder().encode(value).byteLength > MAX_FACT_BYTES) {
+        throw new Error(`runtime identity ${name} exceeds the bounded fact limit`);
+    }
+    return value;
+}
 export function renderRuntimeIdentity(intent, options) {
-    const lines = [`[${RUNTIME_IDENTITY_MARKER}]`, BASE_CAPSULE, "Runtime facts:", `- intent: ${intent}`];
+    const lines = [`[${RUNTIME_IDENTITY_MARKER}]`, BASE_CAPSULE, "Runtime facts:", `- intent: ${boundedFact(intent, "intent")}`];
+    if (options.client_name || options.client_version) {
+        if (!options.client_name || !options.client_version)
+            throw new Error("runtime identity client name and version must be supplied together");
+        lines.push(`- client: ${boundedFact(options.client_name, "client name")} ${boundedFact(options.client_version, "client version")}`);
+    }
+    if (options.connection_mode === "routed") {
+        lines.push("- connection: routed through IICP to an eligible provider.");
+    }
+    else if (options.connection_mode === "local_browser") {
+        lines.push("- connection: This model is running locally in the browser; no remote IICP provider was selected.");
+    }
+    else if (options.connection_mode !== undefined) {
+        throw new Error("runtime identity connection mode is unsupported");
+    }
     if (options.selected_model)
-        lines.push(`- selected model (provider assertion): ${options.selected_model}`);
+        lines.push(`- selected model: ${boundedFact(options.selected_model, "selected model")}`);
+    if ((options.effective_capabilities?.length ?? 0) > MAX_CAPABILITIES) {
+        throw new Error("runtime identity effective capabilities exceed the bounded count");
+    }
     if (options.effective_capabilities?.length) {
-        lines.push(`- effective capabilities: ${options.effective_capabilities.join(", ")}`);
+        lines.push(`- effective capabilities: ${options.effective_capabilities.map((value) => boundedFact(value, "effective capability")).join(", ")}`);
     }
-    if (options.selection_reason === "matched_intent_and_constraints") {
-        lines.push("- selection: This service matched the requested intent and constraints.");
+    if (options.selection_reason) {
+        const selection = selectionText[options.selection_reason];
+        if (!selection)
+            throw new Error("runtime identity selection reason is unsupported");
+        lines.push(`- selection: ${selection}`);
     }
     const rendered = lines.join("\n");
     if (new TextEncoder().encode(rendered).byteLength > RUNTIME_IDENTITY_MAX_BYTES) {
@@ -27,10 +84,20 @@ export function renderRuntimeIdentity(intent, options) {
 }
 export function composeRuntimeIdentity(messages, intent, options) {
     const original = [...messages];
-    const mode = options?.mode ?? "disabled";
-    if (mode === "disabled" || intent !== RUNTIME_IDENTITY_CHAT_INTENT)
+    const resolved = options ?? {};
+    const mode = resolved.mode ?? "auto";
+    if (intent !== RUNTIME_IDENTITY_CHAT_INTENT)
         return original;
-    if (options?.instruction_channel === "unsupported") {
+    if (!["auto", "disabled", "explicit", "required"].includes(mode)) {
+        throw new Error("runtime identity mode is unsupported");
+    }
+    if (mode === "disabled")
+        return original;
+    if (resolved.instruction_channel !== undefined
+        && !["system", "unsupported"].includes(resolved.instruction_channel)) {
+        throw new Error("runtime identity instruction channel is unsupported");
+    }
+    if (resolved.instruction_channel === "unsupported") {
         if (mode === "required")
             throw new RuntimeIdentityContextUnsupported();
         return original;
@@ -43,7 +110,7 @@ export function composeRuntimeIdentity(messages, intent, options) {
         insertion += 1;
     return [
         ...original.slice(0, insertion),
-        { role: "system", content: renderRuntimeIdentity(intent, options ?? {}) },
+        { role: "system", content: renderRuntimeIdentity(intent, resolved) },
         ...original.slice(insertion),
     ];
 }

package/dist/version.d.ts

@@ -1,4 +1,4 @@
-export declare const BROWSER_NODE_VERSION = "0.2.4";
+export declare const BROWSER_NODE_VERSION = "0.2.6";
 export declare const BROWSER_NODE_SDK_COMPATIBILITY_VERSION = "0.7.102";
 /** Backward-compatible registration value for directories that know only sdk_version. */
 export declare const BROWSER_NODE_SDK_VERSION = "0.7.102";

package/dist/version.js

@@ -1,7 +1,7 @@
 // Browser implementation and IICP SDK-compatibility versions are separate axes.
 // Keep package.json synchronized with BROWSER_NODE_VERSION; the quality gate
 // rejects drift. SDK compatibility describes the registration contract only.
-export const BROWSER_NODE_VERSION = "0.2.4";
+export const BROWSER_NODE_VERSION = "0.2.6";
 export const BROWSER_NODE_SDK_COMPATIBILITY_VERSION = "0.7.102";
 /** Backward-compatible registration value for directories that know only sdk_version. */
 export const BROWSER_NODE_SDK_VERSION = BROWSER_NODE_SDK_COMPATIBILITY_VERSION;

package/package.json

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