@iicp/web-node 0.2.3 → 0.2.5

package/LICENSE

@@ -1,3 +1,4 @@
+
                                  Apache License
                            Version 2.0, January 2004
                         http://www.apache.org/licenses/
@@ -32,33 +33,36 @@
       not limited to compiled object code, generated documentation,
       and conversions to other media types.
 
-      "Work" shall mean the work of authorship made available under
-      the License, as indicated by a copyright notice that is included in
-      or attached to the work (an example is provided in the Appendix below).
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
 
       "Derivative Works" shall mean any work, whether in Source or Object
       form, that is based on (or derived from) the Work and for which the
-      editorial revisions, annotations, elaborations, or other transformations
+      editorial revisions, annotations, elaborations, or other modifications
       represent, as a whole, an original work of authorship. For the purposes
       of this License, Derivative Works shall not include works that remain
       separable from, or merely link (or bind by name) to the interfaces of,
-      the Work and its Derivative Works thereof.
-
-      "Contribution" shall mean, as submitted to the Licensor for inclusion
-      in the Work by the copyright owner or by an individual or Legal Entity
-      authorized to submit on behalf of the copyright owner. For the purposes
-      of this definition, "submitted" means any form of electronic, verbal,
-      or written communication sent to the Licensor or its representatives,
-      including but not limited to communication on electronic mailing lists,
-      source code control systems, and issue tracking systems that are managed
-      by, or on behalf of, the Licensor for the purpose of discussing and
-      improving the Work, but excluding communication that is conspicuously
-      marked or otherwise designated in writing by the copyright owner as
-      "Not a Contribution."
-
-      "Contributor" shall mean Licensor and any Legal Entity on behalf of
-      whom a Contribution has been received by the Licensor and incorporated
-      within the Work.
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
 
    2. Grant of Copyright License. Subject to the terms and conditions of
       this License, each Contributor hereby grants to You a perpetual,
@@ -74,21 +78,22 @@
       use, offer to sell, sell, import, and otherwise transfer the Work,
       where such license applies only to those patent claims licensable
       by such Contributor that are necessarily infringed by their
-      Contribution(s) alone or in combination with the Work to which such
-      Contribution(s) was submitted. If You institute patent litigation
-      against any entity (including a cross-claim or counterclaim in a
-      lawsuit) alleging that the Work or a Contribution incorporated within
-      the Work constitutes direct or contributory patent infringement, then
-      any patent licenses granted to You under this License for that Work
-      shall terminate as of the date such litigation is filed.
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
 
    4. Redistribution. You may reproduce and distribute copies of the
       Work or Derivative Works thereof in any medium, with or without
       modifications, and in Source or Object form, provided that You
       meet the following conditions:
 
-      (a) You must give any other recipients of the Work or Derivative
-          Works a copy of this License; and
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
 
       (b) You must cause any modified files to carry prominent notices
           stating that You changed the files; and
@@ -100,25 +105,28 @@
           the Derivative Works; and
 
       (d) If the Work includes a "NOTICE" text file as part of its
-          distribution, You must include a readable copy of the
-          attribution notices contained within such NOTICE file, in
-          at least one of the following places: within a NOTICE text
-          file distributed as part of the Derivative Works; within
-          the Source form or documentation, if provided along with the
-          Derivative Works; or, within a display generated by the
-          Derivative Works, if and wherever such third-party notices
-          normally appear. The contents of the NOTICE file are for
-          informational purposes only and do not modify the License.
-          You may add Your own attribution notices within Derivative
-          Works that You distribute, alongside or as an addendum to
-          the NOTICE text from the Work, provided that such additional
-          attribution notices cannot be construed as modifying the License.
-
-      You may add Your own license statement for Your modifications and
-      may provide additional grant of rights to use, copy, modify, merge,
-      publish, distribute, sublicense, and/or sell copies of the Work,
-      and to permit persons to whom the Work is furnished to do so, subject
-      to Your separate additional terms and conditions.
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
 
    5. Submission of Contributions. Unless You explicitly state otherwise,
       any Contribution intentionally submitted for inclusion in the Work
@@ -137,10 +145,10 @@
       agreed to in writing, Licensor provides the Work (and each
       Contributor provides its Contributions) on an "AS IS" BASIS,
       WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-      implied, including, without limitation, any conditions of title,
-      non-infringement, merchantability, or fitness for a particular
-      purpose. You are solely responsible for determining the
-      appropriateness of using or reproducing the Work and assume any
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
       risks associated with Your exercise of permissions under this License.
 
    8. Limitation of Liability. In no event and under no legal theory,
@@ -148,24 +156,38 @@
       unless required by applicable law (such as deliberate and grossly
       negligent acts) or agreed to in writing, shall any Contributor be
       liable to You for damages, including any direct, indirect, special,
-      incidental, or exemplary damages of any character arising as a
+      incidental, or consequential damages of any character arising as a
       result of this License or out of the use or inability to use the
       Work (including but not limited to damages for loss of goodwill,
-      work stoppage, computer failure or malfunction, or all other
-      commercial damages or losses), even if such Contributor has been
-      advised of the possibility of such damages.
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
 
    9. Accepting Warranty or Additional Liability. While redistributing
       the Work or Derivative Works thereof, You may choose to offer,
       and charge a fee for, acceptance of support, warranty, indemnity,
       or other liability obligations and/or rights consistent with this
-      License. However, in accepting such obligations, You may offer only
-      conditions fully consistent with this License to any recipient of
-      the Work.
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
 
    END OF TERMS AND CONDITIONS
 
-   Copyright 2026 Rob Lemumin
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

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
 ```
@@ -36,6 +41,20 @@ When the chosen node advertises an encryption key (`nodeCxKey(node)`), the paylo
 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,4 +1,5 @@
 import type { ChatMessage } from "./iicpConsumer.js";
+import type { EffectiveCapability } from "./effectiveCapability.js";
 export interface BrowserProviderRuntime {
     chat(messages: ChatMessage[], opts?: {
         temperature?: number;
@@ -14,6 +15,9 @@ export interface BrowserProviderConfig {
     directoryUrl?: string;
     /** Model name advertised to the directory (the loaded WebLLM model id). */
     model: string;
+    /** Complete service-path variants. When present, these replace the legacy
+     * text-only browser advertisement without merging fields across variants. */
+    effectiveCapabilities?: EffectiveCapability[];
     region?: string;
     onLog?: (line: string) => void;
     /** Called after each served task with the running total. */
@@ -32,6 +36,10 @@ export interface BrowserProviderDiagnostic {
     tasks_served: number;
 }
 export { BROWSER_NODE_SDK_VERSION } from "./version.js";
+/** Resolve the exact variants sent to the directory. Explicit effective
+ * capabilities take precedence; the historical browser default is preserved
+ * for callers that do not opt in. */
+export declare function advertisedBrowserCapabilities(explicit: readonly EffectiveCapability[], model: string): EffectiveCapability[];
 /**
  * Coarse region autodetect from the browser's timezone (no network, no
  * geolocation permission). Matches the mesh's region convention

package/dist/browserNodeProvider.js

@@ -21,6 +21,19 @@ import { createCxKeyPair, decryptPayload } from "./cxConfidentiality.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";
+/** Resolve the exact variants sent to the directory. Explicit effective
+ * capabilities take precedence; the historical browser default is preserved
+ * for callers that do not opt in. */
+export function advertisedBrowserCapabilities(explicit, model) {
+    return explicit.length > 0
+        ? explicit.map((capability) => ({ ...capability }))
+        : [{
+                intent: CHAT_INTENT,
+                models: [model],
+                max_tokens: 1024,
+                input_modalities: ["text"],
+            }];
+}
 /**
  * Coarse region autodetect from the browser's timezone (no network, no
  * geolocation permission). Matches the mesh's region convention
@@ -261,14 +274,7 @@ export class BrowserNodeProvider {
                     node_id: this.nodeId,
                     endpoint,
                     region: this.cfg.region ?? detectRegion(),
-                    capabilities: [
-                        {
-                            intent: CHAT_INTENT,
-                            models: [this.cfg.model],
-                            max_tokens: 1024,
-                            input_modalities: ["text"],
-                        },
-                    ],
+                    capabilities: advertisedBrowserCapabilities(this.cfg.effectiveCapabilities ?? [], this.cfg.model),
                     limits: { max_concurrent: 1, tokens_per_min: 6000 },
                     transport_method: "turn_relay",
                     exposure_mode: "relay_required",

package/dist/build-manifest.json

@@ -1,8 +1,8 @@
 {
   "schema": "iicp.browser_build_provenance.v1",
   "package": "@iicp/web-node",
-  "implementation_version": "0.2.3",
-  "sdk_compatibility_version": "0.7.101",
-  "source_commit": "1d1e5612e237894735e05526d36dfebeec3ee53e",
-  "lockfile_sha256": "1dea1f6057741f225d03d4b96cd9f963bc70623cc126e2d65f80984fb8f8c85c"
+  "implementation_version": "0.2.5",
+  "sdk_compatibility_version": "0.7.102",
+  "source_commit": "6f28256d0d67cf08beddadbc762dbd339786fcd8",
+  "lockfile_sha256": "1a398bdcc85e5a650a394aac26851a04c44bd3e6ec9c8c1c359d4d3015338a7e"
 }

package/dist/dispatchTicket.d.ts

@@ -0,0 +1,12 @@
+export interface DispatchTicketClaims {
+    v: number;
+    typ: string;
+    iss: string;
+    aud: string;
+    jti: string;
+    node_id: string;
+    intent: string;
+    iat: number;
+    exp: number;
+}
+export declare function verifyDispatchTicket(token: string, keyHex: string, issuer: string, nodeId: string, intent: string, nowSec?: number): DispatchTicketClaims | null;

package/dist/dispatchTicket.js

@@ -0,0 +1,14 @@
+import { ed25519 } from "@noble/curves/ed25519.js";
+import { hexToBytes } from "@noble/hashes/utils.js";
+const DOMAIN = "iicp:dispatch-route-ticket:v1\n";
+function b64(value) { const text = value.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat((4 - value.length % 4) % 4); const raw = atob(text); return Uint8Array.from(raw, c => c.charCodeAt(0)); }
+export function verifyDispatchTicket(token, keyHex, issuer, nodeId, intent, nowSec = Math.floor(Date.now() / 1000)) { const [payload, sig, ...extra] = token.split("."); if (!payload || !sig || extra.length || sig.length !== 128)
+    return null; try {
+    if (!ed25519.verify(hexToBytes(sig), new TextEncoder().encode(DOMAIN + payload), hexToBytes(keyHex)))
+        return null;
+    const c = JSON.parse(new TextDecoder().decode(b64(payload)));
+    return c.v === 1 && c.typ === "dispatch-route-ticket" && c.iss === issuer && c.aud === "iicp.directory.dispatch" && c.node_id === nodeId && c.intent === intent && c.exp > nowSec && /^[0-9a-f]{24}$/.test(c.jti) ? c : null;
+}
+catch {
+    return null;
+} }

package/dist/effectiveCapability.d.ts

@@ -0,0 +1,76 @@
+/** Binding-neutral effective-capability profile primitives.
+ *
+ * These helpers classify complete service-path variants. They do not perform
+ * discovery, policy authorization, final route validation, or dispatch.
+ */
+export declare const EFFECTIVE_CAPABILITY_PROFILE_ID = "urn:iicp:profile:effective-capability:v1";
+export declare const EFFECTIVE_CAPABILITY_SCHEMA_VERSION = "1.0.0";
+export declare const EFFECTIVE_CAPABILITY_REFUSAL: {
+    readonly requiredUnknown: "required_capability_unknown";
+    readonly requiredUnsupported: "required_capability_unsupported";
+    readonly requiredStale: "required_capability_stale";
+    readonly limitUnsatisfied: "capability_limit_unsatisfied";
+    readonly policyDenied: "capability_policy_denied";
+};
+export interface CapabilityLimit {
+    value: number;
+    unit: "tokens" | "items" | "bytes" | "milliseconds" | "dimensions";
+}
+export interface CapabilityClaimProvenance {
+    source: "heuristic_fallback" | "operator_assertion" | "provider_metadata" | "runtime_introspection" | "conformance_probe";
+    observed_at?: string;
+    valid_until?: string;
+    evidence_ref?: string;
+}
+export interface CapabilityExtension {
+    required: boolean;
+    value: unknown;
+}
+/** One complete variant; fields from different variants must never be unioned. */
+export interface EffectiveCapability {
+    intent: string;
+    version?: string;
+    phase?: number;
+    variant_id?: string;
+    models?: string[];
+    max_tokens?: number;
+    input_modalities?: string[];
+    output_modalities?: string[];
+    features?: string[];
+    execution_capabilities?: string[];
+    limits?: Record<string, CapabilityLimit>;
+    supported_profiles?: string[];
+    claim_provenance?: CapabilityClaimProvenance;
+    extensions?: Record<string, CapabilityExtension>;
+}
+export interface CapabilityRequirement {
+    class: string;
+    id: string;
+}
+export interface CapabilityLimitRequirement {
+    id: string;
+    operator: "gte" | "lte" | "eq" | string;
+    value: number;
+    unit: string;
+}
+export interface CapabilityRequirements {
+    intent: string;
+    requires?: CapabilityRequirement[];
+    prefers?: CapabilityRequirement[];
+    limits?: CapabilityLimitRequirement[];
+}
+export interface EffectiveCapabilityMatch {
+    eligible: boolean;
+    variant_ids: Array<string | undefined>;
+    preference_unavailable: boolean;
+    refusal?: string;
+    preserved_extensions: string[];
+}
+export declare function parseEffectiveCapability(raw: unknown): EffectiveCapability;
+export declare function parseEffectiveCapabilityAdvertisement(raw: unknown): EffectiveCapability[];
+export declare function resolveEffectiveCapabilities(options: {
+    explicit?: readonly EffectiveCapability[];
+    introspected?: readonly EffectiveCapability[];
+    heuristic?: readonly EffectiveCapability[];
+}): EffectiveCapability[];
+export declare function matchEffectiveCapabilities(capabilities: readonly EffectiveCapability[], request: CapabilityRequirements, vocabulary: Readonly<Record<string, readonly string[]>>, evaluatedAt: Date, policyDenials?: readonly CapabilityRequirement[]): EffectiveCapabilityMatch;

package/dist/effectiveCapability.js

@@ -0,0 +1,200 @@
+/** Binding-neutral effective-capability profile primitives.
+ *
+ * These helpers classify complete service-path variants. They do not perform
+ * discovery, policy authorization, final route validation, or dispatch.
+ */
+export const EFFECTIVE_CAPABILITY_PROFILE_ID = "urn:iicp:profile:effective-capability:v1";
+export const EFFECTIVE_CAPABILITY_SCHEMA_VERSION = "1.0.0";
+export const EFFECTIVE_CAPABILITY_REFUSAL = {
+    requiredUnknown: "required_capability_unknown",
+    requiredUnsupported: "required_capability_unsupported",
+    requiredStale: "required_capability_stale",
+    limitUnsatisfied: "capability_limit_unsatisfied",
+    policyDenied: "capability_policy_denied",
+};
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function assertExactKeys(value, allowed, label) {
+    const unknown = Object.keys(value).filter((key) => !allowed.has(key));
+    if (unknown.length > 0)
+        throw new Error(`${label} has unknown field(s): ${unknown.sort().join(", ")}`);
+}
+function stringSet(value, label) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || item.length === 0)) {
+        throw new Error(`${label} must be an array of non-empty strings`);
+    }
+    const result = value;
+    if (new Set(result).size !== result.length)
+        throw new Error(`${label} must not contain duplicates`);
+    return [...result];
+}
+function parseTimestamp(value) {
+    const parsed = Date.parse(value);
+    if (!Number.isFinite(parsed))
+        throw new Error("capability timestamp must be RFC 3339");
+    return parsed;
+}
+export function parseEffectiveCapability(raw) {
+    if (!isRecord(raw))
+        throw new Error("effective capability must be an object");
+    assertExactKeys(raw, new Set([
+        "intent", "version", "phase", "variant_id", "models", "max_tokens",
+        "input_modalities", "output_modalities", "features", "execution_capabilities",
+        "limits", "supported_profiles", "claim_provenance", "extensions",
+    ]), "effective capability");
+    if (typeof raw.intent !== "string" || raw.intent.length === 0)
+        throw new Error("intent is required");
+    if (raw.phase !== undefined && (!Number.isInteger(raw.phase) || raw.phase < 1)) {
+        throw new Error("phase must be a positive integer");
+    }
+    if (raw.max_tokens !== undefined && (!Number.isInteger(raw.max_tokens) || raw.max_tokens < 1)) {
+        throw new Error("max_tokens must be a positive integer");
+    }
+    let limits;
+    if (raw.limits !== undefined) {
+        if (!isRecord(raw.limits))
+            throw new Error("limits must be an object");
+        limits = {};
+        for (const [id, rawLimit] of Object.entries(raw.limits)) {
+            if (!isRecord(rawLimit) || Object.keys(rawLimit).sort().join(",") !== "unit,value") {
+                throw new Error("each limit requires only value and unit");
+            }
+            if (typeof rawLimit.value !== "number" || !Number.isFinite(rawLimit.value) || rawLimit.value < 0) {
+                throw new Error("limit value must be a non-negative number");
+            }
+            if (!["tokens", "items", "bytes", "milliseconds", "dimensions"].includes(String(rawLimit.unit))) {
+                throw new Error("limit unit is unsupported");
+            }
+            limits[id] = { value: rawLimit.value, unit: rawLimit.unit };
+        }
+    }
+    let claim_provenance;
+    if (raw.claim_provenance !== undefined) {
+        if (!isRecord(raw.claim_provenance))
+            throw new Error("claim_provenance must be an object");
+        const source = raw.claim_provenance.source;
+        const sources = ["heuristic_fallback", "operator_assertion", "provider_metadata", "runtime_introspection", "conformance_probe"];
+        if (typeof source !== "string" || !sources.includes(source))
+            throw new Error("claim_provenance source is unsupported");
+        for (const key of ["observed_at", "valid_until"]) {
+            const value = raw.claim_provenance[key];
+            if (value !== undefined) {
+                if (typeof value !== "string")
+                    throw new Error(`${key} must be a string`);
+                parseTimestamp(value);
+            }
+        }
+        claim_provenance = {
+            source: source,
+            ...(typeof raw.claim_provenance.observed_at === "string" ? { observed_at: raw.claim_provenance.observed_at } : {}),
+            ...(typeof raw.claim_provenance.valid_until === "string" ? { valid_until: raw.claim_provenance.valid_until } : {}),
+            ...(typeof raw.claim_provenance.evidence_ref === "string" ? { evidence_ref: raw.claim_provenance.evidence_ref } : {}),
+        };
+    }
+    let extensions;
+    if (raw.extensions !== undefined) {
+        if (!isRecord(raw.extensions))
+            throw new Error("extensions must be an object");
+        extensions = {};
+        for (const [id, rawExtension] of Object.entries(raw.extensions)) {
+            if (!isRecord(rawExtension) || Object.keys(rawExtension).sort().join(",") !== "required,value" || typeof rawExtension.required !== "boolean") {
+                throw new Error("each extension requires boolean required and value");
+            }
+            extensions[id] = { required: rawExtension.required, value: rawExtension.value };
+        }
+    }
+    return {
+        intent: raw.intent,
+        ...(typeof raw.version === "string" ? { version: raw.version } : {}),
+        ...(typeof raw.phase === "number" ? { phase: raw.phase } : {}),
+        ...(typeof raw.variant_id === "string" ? { variant_id: raw.variant_id } : {}),
+        ...(stringSet(raw.models, "models") ? { models: stringSet(raw.models, "models") } : {}),
+        ...(typeof raw.max_tokens === "number" ? { max_tokens: raw.max_tokens } : {}),
+        ...(stringSet(raw.input_modalities, "input_modalities") ? { input_modalities: stringSet(raw.input_modalities, "input_modalities") } : {}),
+        ...(stringSet(raw.output_modalities, "output_modalities") ? { output_modalities: stringSet(raw.output_modalities, "output_modalities") } : {}),
+        ...(stringSet(raw.features, "features") ? { features: stringSet(raw.features, "features") } : {}),
+        ...(stringSet(raw.execution_capabilities, "execution_capabilities") ? { execution_capabilities: stringSet(raw.execution_capabilities, "execution_capabilities") } : {}),
+        ...(limits ? { limits } : {}),
+        ...(stringSet(raw.supported_profiles, "supported_profiles") ? { supported_profiles: stringSet(raw.supported_profiles, "supported_profiles") } : {}),
+        ...(claim_provenance ? { claim_provenance } : {}),
+        ...(extensions ? { extensions } : {}),
+    };
+}
+export function parseEffectiveCapabilityAdvertisement(raw) {
+    if (!isRecord(raw))
+        throw new Error("advertisement must be an object");
+    if (Object.keys(raw).sort().join(",") !== "capabilities,schema_version") {
+        throw new Error("advertisement requires only schema_version and capabilities");
+    }
+    if (raw.schema_version !== EFFECTIVE_CAPABILITY_SCHEMA_VERSION)
+        throw new Error("unsupported schema_version");
+    if (!Array.isArray(raw.capabilities) || raw.capabilities.length === 0)
+        throw new Error("capabilities must be a non-empty array");
+    const parsed = raw.capabilities.map(parseEffectiveCapability);
+    const identities = parsed.map((item) => `${item.intent}\u0000${item.variant_id ?? ""}`);
+    if (new Set(identities).size !== identities.length)
+        throw new Error("effective capability variants must be unique");
+    return parsed;
+}
+export function resolveEffectiveCapabilities(options) {
+    if (options.explicit?.length)
+        return [...options.explicit];
+    if (options.introspected?.length)
+        return [...options.introspected];
+    const heuristic = options.heuristic ?? [];
+    if (heuristic.some((item) => item.claim_provenance?.source !== "heuristic_fallback")) {
+        throw new Error("heuristic capability evidence must be labelled heuristic_fallback");
+    }
+    return [...heuristic];
+}
+function values(candidate, capabilityClass) {
+    switch (capabilityClass) {
+        case "input_modality": return candidate.input_modalities;
+        case "output_modality": return candidate.output_modalities;
+        case "feature": return candidate.features;
+        case "execution_capability": return candidate.execution_capabilities;
+        case "profile": return candidate.supported_profiles;
+        default: return undefined;
+    }
+}
+function refusal(code) {
+    return { eligible: false, variant_ids: [], preference_unavailable: false, refusal: code, preserved_extensions: [] };
+}
+export function matchEffectiveCapabilities(capabilities, request, vocabulary, evaluatedAt, policyDenials = []) {
+    for (const requirement of request.requires ?? []) {
+        if (!vocabulary[requirement.class]?.includes(requirement.id))
+            return refusal(EFFECTIVE_CAPABILITY_REFUSAL.requiredUnknown);
+        if (policyDenials.some((denial) => denial.class === requirement.class && denial.id === requirement.id)) {
+            return refusal(EFFECTIVE_CAPABILITY_REFUSAL.policyDenied);
+        }
+    }
+    let candidates = capabilities.filter((candidate) => candidate.intent === request.intent && (request.requires ?? []).every((required) => values(candidate, required.class)?.includes(required.id)));
+    if (candidates.length === 0)
+        return refusal(EFFECTIVE_CAPABILITY_REFUSAL.requiredUnsupported);
+    candidates = candidates.filter((candidate) => !candidate.claim_provenance?.valid_until || parseTimestamp(candidate.claim_provenance.valid_until) >= evaluatedAt.getTime());
+    if (candidates.length === 0)
+        return refusal(EFFECTIVE_CAPABILITY_REFUSAL.requiredStale);
+    candidates = candidates.filter((candidate) => (request.limits ?? []).every((required) => {
+        const actual = candidate.limits?.[required.id];
+        if (!actual || actual.unit !== required.unit)
+            return false;
+        if (required.operator === "gte")
+            return actual.value >= required.value;
+        if (required.operator === "lte")
+            return actual.value <= required.value;
+        return required.operator === "eq" && actual.value === required.value;
+    }));
+    if (candidates.length === 0)
+        return refusal(EFFECTIVE_CAPABILITY_REFUSAL.limitUnsatisfied);
+    const preferenceUnavailable = (request.prefers ?? []).some((preferred) => !vocabulary[preferred.class]?.includes(preferred.id)
+        || !candidates.some((candidate) => values(candidate, preferred.class)?.includes(preferred.id)));
+    return {
+        eligible: true,
+        variant_ids: candidates.map((candidate) => candidate.variant_id),
+        preference_unavailable: preferenceUnavailable,
+        preserved_extensions: [...new Set(candidates.flatMap((candidate) => Object.keys(candidate.extensions ?? {})))].sort(),
+    };
+}

package/dist/iicpConsumer.d.ts

@@ -1,4 +1,5 @@
 import { type CxPublicKey } from "./cxConfidentiality.js";
+import { type RuntimeIdentityOptions } from "./runtimeIdentity.js";
 export declare const DEFAULT_DIRECTORY_URL = "https://iicp.network";
 export interface ClientConfig {
     /** Directory base URL. Default: https://iicp.network (CORS-enabled). */
@@ -56,9 +57,19 @@ export interface Node {
     [k: string]: unknown;
 }
 export interface ChatMessage {
-    role: "system" | "user" | "assistant";
+    role: "system" | "developer" | "user" | "assistant";
     content: string;
 }
+export interface BrowserChatOptions {
+    endpoint: string;
+    intent?: string;
+    model?: string;
+    cxPublicKey?: CxPublicKey | null;
+    node?: Node;
+    allowed_regions?: string[];
+    required_manifest_identity_level?: RequiredManifestIdentityLevel | null;
+    runtime_identity?: RuntimeIdentityOptions;
+}
 /**
  * Compatibility helper for callers that need to inspect or test the canonical
  * plaintext task shape. Production `chat()` remains fail-closed and sends only
@@ -159,13 +170,13 @@ 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;
     private readonly allowedRegions;
     private readonly requiredManifestIdentityLevel?;
     private readonly routeDiscoveryMode;
+    private dispatchTicketKey?;
     constructor(cfg?: ClientConfig);
     private effectiveAllowedRegions;
     private effectiveManifestIdentityLevel;
@@ -196,28 +207,12 @@ export declare class IicpBrowserClient {
      * 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;
-        node?: Node;
-        allowed_regions?: string[];
-        required_manifest_identity_level?: RequiredManifestIdentityLevel | null;
-    }): Promise<Record<string, unknown>>;
+    chat(messages: ChatMessage[], opts: BrowserChatOptions): 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<{
+    chatWithReceipt(messages: ChatMessage[], opts: BrowserChatOptions): Promise<{
         response: Record<string, unknown>;
         receipt: RoutingReceipt;
     }>;

package/dist/iicpConsumer.js

@@ -16,6 +16,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, withRuntimeFacts } from "./runtimeIdentity.js";
+import { BROWSER_NODE_VERSION } from "./version.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"] },
@@ -271,12 +274,48 @@ 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;
     allowedRegions;
     requiredManifestIdentityLevel;
     routeDiscoveryMode;
+    dispatchTicketKey;
     constructor(cfg = {}) {
         this.directory = (cfg.directory_url ?? DEFAULT_DIRECTORY_URL).replace(/\/+$/, "");
         this.timeout = cfg.timeout_ms ?? 10_000;
@@ -338,6 +377,23 @@ export class IicpBrowserClient {
                 if (!route || typeof body.node_id !== "string") {
                     throw new IicpError("ticketed route response is malformed", "ticket_malformed");
                 }
+                if (!this.dispatchTicketKey) {
+                    const keyResponse = await fetch(`${this.directory}/api/v1/directory-key`, {
+                        headers: { Accept: "application/json" },
+                        signal: AbortSignal.timeout(this.timeout),
+                    });
+                    const keyBody = await keyResponse.json().catch(() => ({}));
+                    if (keyResponse.status === 200 && typeof keyBody.public_key === "string") {
+                        this.dispatchTicketKey = keyBody.public_key;
+                    }
+                }
+                const issuer = this.directory.replace(/\/api$/, "");
+                const claims = typeof body.ticket === "string" && this.dispatchTicketKey
+                    ? verifyDispatchTicket(body.ticket, this.dispatchTicketKey, issuer, body.node_id, intent)
+                    : null;
+                if (!claims) {
+                    throw new IicpError("directory returned an unverifiable dispatch ticket", "ticket_unverified");
+                }
                 const node = {
                     ...route,
                     node_id: body.node_id,
@@ -424,6 +480,15 @@ export class IicpBrowserClient {
     async chatWithReceipt(messages, opts) {
         const intent = opts.intent ?? "urn:iicp:intent:llm:chat:v1";
         validateIntent(intent);
+        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

@@ -1,5 +1,8 @@
 export * from "./iicpConsumer.js";
+export * from "./dispatchTicket.js";
 export * from "./cxConfidentiality.js";
+export * from "./effectiveCapability.js";
+export * from "./runtimeIdentity.js";
 export * from "./browserNodeProvider.js";
 export * from "./webllmRuntime.js";
 export * from "./version.js";

package/dist/index.js

@@ -6,7 +6,10 @@
 // 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 "./dispatchTicket.js";
 export * from "./cxConfidentiality.js";
+export * from "./effectiveCapability.js";
+export * from "./runtimeIdentity.js";
 export * from "./browserNodeProvider.js";
 export * from "./webllmRuntime.js";
 export * from "./version.js";

package/dist/runtimeIdentity.d.ts

@@ -0,0 +1,25 @@
+import type { ChatMessage } from "./iicpConsumer.js";
+export declare const RUNTIME_IDENTITY_PROFILE_ID = "urn:iicp:profile:runtime-identity-context:v0";
+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 = "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?: 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

@@ -0,0 +1,105 @@
+export const RUNTIME_IDENTITY_PROFILE_ID = "urn:iicp:profile:runtime-identity-context:v0";
+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 MAX_FACT_BYTES = 160;
+const MAX_CAPABILITIES = 32;
+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.";
+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: ${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: ${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.map((value) => boundedFact(value, "effective capability")).join(", ")}`);
+    }
+    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) {
+        throw new Error("runtime identity context exceeds the 2048-byte limit");
+    }
+    return rendered;
+}
+export function composeRuntimeIdentity(messages, intent, options) {
+    const original = [...messages];
+    const resolved = options ?? {};
+    const mode = resolved.mode ?? "auto";
+    if (intent !== RUNTIME_IDENTITY_CHAT_INTENT)
+        return original;
+    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;
+    }
+    if (original.some((message) => (message.role === "system" || message.role === "developer")
+        && message.content.includes(RUNTIME_IDENTITY_MARKER)))
+        return original;
+    let insertion = 0;
+    while (insertion < original.length && ["system", "developer"].includes(original[insertion].role))
+        insertion += 1;
+    return [
+        ...original.slice(0, insertion),
+        { 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.3";
-export declare const BROWSER_NODE_SDK_COMPATIBILITY_VERSION = "0.7.101";
+export declare const BROWSER_NODE_VERSION = "0.2.5";
+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.101";
+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.3";
-export const BROWSER_NODE_SDK_COMPATIBILITY_VERSION = "0.7.101";
+export const BROWSER_NODE_VERSION = "0.2.5";
+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.3",
+  "version": "0.2.5",
   "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",