@iicp/web-node 0.1.0

package/dist/browserNodeProvider.js

@@ -0,0 +1,455 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Browser node provider glue — issue #452 (the "serve into the mesh" half
+// of the hybrid browser node #449).
+//
+// Pairs the WebLLM runtime (webllmRuntime.ts, #451) with the HTTP long-poll
+// relay transport (#450, iicp-client >= 0.7.56 relay nodes):
+//
+//   1. Register with the directory (CORS is open on /api/v1/*) advertising
+//      endpoint = {relay}/v1/relay-for/{node_id}  (transport_method=turn_relay)
+//   2. Bind to the relay: POST /v1/relay/bind → bearer session token
+//   3. Poll loop: GET /v1/relay/pull (long-poll) → run WebLLM chat() →
+//      POST /v1/relay/result  (OpenAI-shape choices, same as SDK nodes)
+//   4. Heartbeat the directory every 30 s; unbind + deregister on stop.
+//
+// Wire contracts mirror the Python SDK reference (node.py register()/
+// _heartbeat payloads, client.py chat_async() result parsing) so PUBLISHED
+// consumers route to a browser worker with zero client changes.
+import { maskTunnelUrl } from "./iicpConsumer.js";
+import { createCxKeyPair, decryptPayload } from "./cxConfidentiality.js";
+const CHAT_INTENT = "urn:iicp:intent:llm:chat:v1";
+export const BROWSER_NODE_SDK_VERSION = "0.7.71-browser";
+/**
+ * Coarse region autodetect from the browser's timezone (no network, no
+ * geolocation permission). Matches the mesh's region convention
+ * (eu-central / us-east / …) as a SCORING HINT — deliberately coarse;
+ * operators can override via config. "(Browser)" is shown separately on
+ * the nodes page via sdk_language.
+ */
+export function detectRegion() {
+    try {
+        const tz = Intl.DateTimeFormat().resolvedOptions().timeZone ?? "";
+        const continent = tz.split("/")[0];
+        const offset = -new Date().getTimezoneOffset() / 60; // hours east of UTC
+        switch (continent) {
+            case "Europe":
+                return offset <= 0.5 ? "eu-west" : "eu-central";
+            case "America":
+                if (offset <= -7)
+                    return "us-west";
+                if (offset <= -5.5)
+                    return "us-central";
+                if (offset <= -3.5)
+                    return "us-east";
+                return "sa-east";
+            case "Asia":
+                if (offset >= 8.5)
+                    return "ap-northeast";
+                if (offset >= 6.5)
+                    return "ap-east";
+                return "ap-south";
+            case "Australia":
+            case "Pacific":
+                return "ap-southeast";
+            case "Africa":
+                return "af-central";
+            default:
+                return "unknown";
+        }
+    }
+    catch {
+        return "unknown";
+    }
+}
+const HEARTBEAT_MS = 30_000;
+const POLL_ERROR_BACKOFF_MS = 2_000;
+/**
+ * Auto-discover a browser-usable relay from the live directory (WQ-087 — the
+ * web client's "automagical" rung; tabs can't spawn tunnels, so relays carry
+ * them). Client-side filtering remains a hardening guard (not a dependency):
+ * the directory filter is server-side and authoritative when enabled, and query
+ * width is kept at 50 to avoid default-window clipping of relays.
+ * Browser-usable = https endpoint (or loopback
+ * http for local testing — loopback is a trustworthy origin).
+ *
+ * Red-team F3: a malicious relay sees & can inject the tasks a browser serves
+ * through it. Full trust needs relay attestation; as an interim mitigation we
+ * (a) drop relays below a hard floor (actively demoted / bad actors), (b)
+ * PREFER the highest-reputation, non-probationary relay, and (c) return the
+ * relay's node_id + trust state so the UI shows exactly what's being trusted.
+ *
+ * We do NOT hard-block probation: a brand-new relay is always on probation, so
+ * blocking it would mean no relay can ever bootstrap (it can't earn reputation
+ * without being used). Probationary relays sort LAST and are clearly labelled;
+ * the operator consents by clicking "Start serving".
+ */
+const MIN_RELAY_REPUTATION = 0.1; // hard floor — drop actively-demoted nodes only
+export async function discoverRelay(directoryUrl = "https://iicp.network/api") {
+    try {
+        const base = directoryUrl.replace(/\/$/, "");
+        const resp = await fetch(`${base}/v1/discover?intent=${CHAT_INTENT}&relay_capable=true&limit=50`);
+        if (!resp.ok)
+            return null;
+        const data = await resp.json();
+        const nodes = data?.nodes ?? [];
+        const isLoopback = (ep) => /^http:\/\/(localhost|127\.0\.0\.1)[:/]/.test(ep);
+        const usable = nodes
+            .filter((n) => n.relay_capable === true &&
+            typeof n.endpoint === "string" &&
+            (n.browser_usable === true || n.endpoint.startsWith("https://") || isLoopback(n.endpoint)))
+            .map((n) => ({
+            endpoint: n.endpoint.replace(/\/$/, ""),
+            nodeId: n.node_id ?? "relay",
+            reputation: typeof n.reputation_score === "number" ? n.reputation_score : 0,
+            probation: n.probation === true,
+            loopback: isLoopback(n.endpoint),
+        }))
+            // F3: drop only below-the-hard-floor (demoted) relays; keep loopback
+            // (local operator testing, trusted by definition).
+            .filter((r) => r.loopback || r.reputation >= MIN_RELAY_REPUTATION)
+            // Prefer loopback (local) → non-probationary → higher reputation.
+            .sort((a, b) => (b.loopback ? 1 : 0) - (a.loopback ? 1 : 0) ||
+            (a.probation ? 1 : 0) - (b.probation ? 1 : 0) ||
+            b.reputation - a.reputation);
+        const top = usable[0];
+        return top
+            ? { endpoint: top.endpoint, nodeId: top.nodeId, reputation: top.reputation, probation: top.probation }
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+export class BrowserProviderError extends Error {
+    stage;
+    constructor(message, stage) {
+        super(message);
+        this.stage = stage;
+        this.name = "BrowserProviderError";
+    }
+}
+export class BrowserNodeProvider {
+    runtime;
+    cfg;
+    nodeId;
+    _state = "stopped";
+    _nodeToken = "";
+    _sessionToken = "";
+    _tasksServed = 0;
+    // Success/fail since the last heartbeat (reset each beat — mirrors the SDK).
+    _okSinceBeat = 0;
+    _failSinceBeat = 0;
+    _latencyMsSinceBeat = 0;
+    _cx = createCxKeyPair();
+    _heartbeatTimer = null;
+    _stopRequested = false;
+    /** True when the directory accepted the registration (mesh-discoverable). */
+    directoryListed = false;
+    constructor(runtime, cfg) {
+        this.runtime = runtime;
+        this.cfg = cfg;
+        this.nodeId = `browser-${crypto.randomUUID().slice(0, 8)}`;
+    }
+    get state() {
+        return this._state;
+    }
+    get tasksServed() {
+        return this._tasksServed;
+    }
+    get directoryBase() {
+        return (this.cfg.directoryUrl ?? "https://iicp.network/api").replace(/\/$/, "");
+    }
+    get relayBase() {
+        return this.cfg.relayUrl.replace(/\/$/, "");
+    }
+    log(line) {
+        this.cfg.onLog?.(line);
+    }
+    setState(s) {
+        this._state = s;
+        this.cfg.onStateChange?.(s);
+    }
+    /** Register → bind → start serving. Throws BrowserProviderError on failure. */
+    async start() {
+        if (this._state === "serving" || this._state === "starting")
+            return;
+        this._stopRequested = false;
+        this.setState("starting");
+        // 1. Bind to the relay FIRST — if no relay is reachable there is no point
+        //    holding a directory registration that consumers can't route to.
+        let bindResp;
+        try {
+            bindResp = await fetch(`${this.relayBase}/v1/relay/bind`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    worker_id: this.nodeId,
+                    intent: CHAT_INTENT,
+                    models: [this.cfg.model],
+                }),
+            });
+        }
+        catch (err) {
+            this.setState("error");
+            throw new BrowserProviderError(`relay unreachable at ${maskTunnelUrl(this.relayBase)}: ${err instanceof Error ? err.message : String(err)}`, "bind");
+        }
+        if (!bindResp.ok) {
+            this.setState("error");
+            const detail = await bindResp.text().catch(() => "");
+            throw new BrowserProviderError(`relay bind failed: HTTP ${bindResp.status} ${detail.slice(0, 200)}`, "bind");
+        }
+        const bind = await bindResp.json();
+        this._sessionToken = bind.session_token;
+        this.log(`relay bound — worker ${this.nodeId}`);
+        // 2. Register with the directory, advertising the path-scoped relay endpoint.
+        const endpoint = `${this.relayBase}/v1/relay-for/${this.nodeId}`;
+        try {
+            const regResp = await fetch(`${this.directoryBase}/v1/register`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    node_id: this.nodeId,
+                    endpoint,
+                    region: this.cfg.region ?? detectRegion(),
+                    capabilities: [
+                        {
+                            intent: CHAT_INTENT,
+                            models: [this.cfg.model],
+                            max_tokens: 1024,
+                            input_modalities: ["text"],
+                        },
+                    ],
+                    limits: { max_concurrent: 1, tokens_per_min: 6000 },
+                    transport_method: "turn_relay",
+                    exposure_mode: "relay_required",
+                    transport_metadata: {
+                        relay_for: this.nodeId,
+                        relay_transport: "http-poll",
+                    },
+                    sdk_language: "browser",
+                    sdk_version: BROWSER_NODE_SDK_VERSION,
+                    backend: "webllm",
+                    // IICP-CX S.16: browser providers are privacy-ready too.  The relay
+                    // still sees metadata, but not the task payload.
+                    cx_public_key: this._cx.publicKey,
+                }),
+            });
+            if (!regResp.ok) {
+                const detail = await regResp.text().catch(() => "");
+                throw new Error(`HTTP ${regResp.status} ${detail.slice(0, 200)}`);
+            }
+            const reg = await regResp.json();
+            this._nodeToken = reg.node_token ?? reg.token ?? "";
+            if (!this._nodeToken)
+                throw new Error("directory returned no node_token");
+            this.directoryListed = true;
+            this.log(`registered with directory as ${this.nodeId}`);
+        }
+        catch (err) {
+            // Relay-only degradation: a rejected registration (e.g. IICP-E035
+            // loopback-endpoint validation against a local test relay) means the
+            // node is not mesh-discoverable, but consumers that know the relay
+            // endpoint can still dispatch — keep serving and say so plainly.
+            this.directoryListed = false;
+            this.log(`directory registration rejected — serving relay-only (not discoverable): ${err instanceof Error ? err.message : String(err)}`);
+        }
+        // 3. Heartbeat (only when directory-listed) + poll loop. Fire one
+        // immediately so the directory sees us as available without waiting a
+        // full interval, then keep alive every 30 s while the tab is open and the
+        // model stays loaded.
+        if (this.directoryListed) {
+            void this.heartbeat();
+            this._heartbeatTimer = setInterval(() => void this.heartbeat(), HEARTBEAT_MS);
+        }
+        this.setState("serving");
+        void this.pollLoop();
+    }
+    /** Unbind from the relay and deregister from the directory. */
+    async stop() {
+        this._stopRequested = true;
+        if (this._heartbeatTimer) {
+            clearInterval(this._heartbeatTimer);
+            this._heartbeatTimer = null;
+        }
+        await this.unbindQuietly();
+        if (this._nodeToken) {
+            try {
+                await fetch(`${this.directoryBase}/v1/register`, {
+                    method: "DELETE",
+                    headers: { Authorization: `Bearer ${this._nodeToken}` },
+                    keepalive: true,
+                });
+                this.log("deregistered from directory");
+            }
+            catch {
+                // best-effort — heartbeat expiry cleans up server-side
+            }
+            this._nodeToken = "";
+        }
+        this.setState("stopped");
+    }
+    async unbindQuietly() {
+        if (!this._sessionToken)
+            return;
+        try {
+            await fetch(`${this.relayBase}/v1/relay/unbind`, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${this._sessionToken}`,
+                    "Content-Type": "application/json",
+                },
+                body: "{}",
+                keepalive: true,
+            });
+        }
+        catch {
+            // best-effort — relay liveness window GCs the session
+        }
+        this._sessionToken = "";
+    }
+    async heartbeat() {
+        if (!this._nodeToken)
+            return;
+        const ok = this._okSinceBeat;
+        const fail = this._failSinceBeat;
+        const latencyMs = this._latencyMsSinceBeat;
+        this._okSinceBeat = 0;
+        this._failSinceBeat = 0;
+        this._latencyMsSinceBeat = 0;
+        const payload = {
+            node_id: this.nodeId,
+            node_token: this._nodeToken,
+            status: "available",
+            available: true,
+            max_concurrent: 1,
+            // Liveness: the model is loaded and the tab is open. health_models is the
+            // directory's signal that the advertised model is actually servable
+            // (empty here would demote us in discover) — see #494.
+            health_models: [this.cfg.model],
+        };
+        if (ok > 0 || fail > 0) {
+            const total = ok + fail;
+            payload.metrics = {
+                tasks_success: ok,
+                tasks_failed: fail,
+                ...(latencyMs > 0 && total > 0
+                    ? { avg_latency_ms: Math.round((latencyMs / total) * 100) / 100 }
+                    : {}),
+            };
+        }
+        try {
+            const resp = await fetch(`${this.directoryBase}/v1/heartbeat`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${this._nodeToken}`,
+                },
+                body: JSON.stringify(payload),
+            });
+            if (resp.ok) {
+                this.log(`keep-alive ✓ (model loaded${ok || fail ? `, +${ok} ok / +${fail} fail` : ""})`);
+            }
+            else {
+                this.log(`keep-alive → HTTP ${resp.status}`);
+            }
+        }
+        catch {
+            this.log("keep-alive failed (transient)");
+        }
+    }
+    async pollLoop() {
+        while (!this._stopRequested && this._sessionToken) {
+            let resp;
+            try {
+                resp = await fetch(`${this.relayBase}/v1/relay/pull`, {
+                    headers: { Authorization: `Bearer ${this._sessionToken}` },
+                });
+            }
+            catch {
+                if (this._stopRequested)
+                    return;
+                await new Promise((r) => setTimeout(r, POLL_ERROR_BACKOFF_MS));
+                continue;
+            }
+            if (resp.status === 204)
+                continue; // idle window — poll again
+            if (resp.status === 401) {
+                // Session displaced or GC'd — stop serving rather than fight over the id.
+                this.log("relay session expired — stopping");
+                await this.stop();
+                this.setState("error");
+                return;
+            }
+            if (!resp.ok) {
+                await new Promise((r) => setTimeout(r, POLL_ERROR_BACKOFF_MS));
+                continue;
+            }
+            const call = await resp.json();
+            void this.serveCall(call);
+        }
+    }
+    async serveCall(call) {
+        const task = call.task ?? {};
+        const taskId = String(task.task_id ?? call.call_id);
+        const intent = typeof task.intent === "string" ? task.intent : CHAT_INTENT;
+        let result;
+        const started = performance.now();
+        try {
+            let taskPayload = task.payload ?? {};
+            if (task.iicp_conf && typeof task.iicp_conf === "object") {
+                taskPayload = await decryptPayload(task.iicp_conf, this._cx.secretKey, taskId, intent);
+            }
+            const payload = (taskPayload ?? {});
+            const messages = Array.isArray(payload.messages) ? payload.messages : [];
+            const text = await this.runtime.chat(messages, {
+                ...(payload.temperature !== undefined && { temperature: payload.temperature }),
+                ...(payload.max_tokens !== undefined && { max_tokens: payload.max_tokens }),
+            });
+            // OpenAI-shape choices — exactly what SDK consumers' chat() parses.
+            result = {
+                result: {
+                    choices: [
+                        {
+                            message: { role: "assistant", content: text },
+                            finish_reason: "stop",
+                        },
+                    ],
+                    model: this.cfg.model,
+                    usage: { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 },
+                },
+            };
+            this._tasksServed += 1;
+            this._okSinceBeat += 1;
+            this._latencyMsSinceBeat += Math.max(1, Math.round(performance.now() - started));
+            this.cfg.onTaskServed?.(this._tasksServed);
+            this.log(`served task ${String(task.task_id ?? call.call_id)}`);
+        }
+        catch (err) {
+            this._failSinceBeat += 1;
+            this._latencyMsSinceBeat += Math.max(1, Math.round(performance.now() - started));
+            result = {
+                result: {
+                    error: {
+                        code: "IICP-E020",
+                        message: `browser inference failed: ${err instanceof Error ? err.message : String(err)}`,
+                    },
+                },
+            };
+            this.log(`task failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        try {
+            await fetch(`${this.relayBase}/v1/relay/result`, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${this._sessionToken}`,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({ call_id: call.call_id, result }),
+            });
+        }
+        catch {
+            this.log("result delivery failed — consumer will see a timeout");
+        }
+    }
+}

package/dist/cxConfidentiality.d.ts

@@ -0,0 +1,27 @@
+export interface CxPublicKey {
+    algorithm: string;
+    encoding?: string;
+    key: string;
+    key_id: string;
+}
+export interface CxKeyPair {
+    publicKey: CxPublicKey;
+    secretKey: Uint8Array;
+}
+/** Generate a browser-provider X25519 key pair suitable for directory advertisement. */
+export declare function createCxKeyPair(prefix?: string): CxKeyPair;
+/**
+ * Encrypt a task payload to the node's advertised X25519 key, producing an `iicp_conf`
+ * envelope identical to what the SDKs send and the adapter decrypts (IICP-CX §5):
+ * ephemeral X25519 → HKDF-SHA256(salt=nonce, info="IICP-CX-v1"+task_id+intent) →
+ * AES-256-GCM(aad=task_id+"|"+intent). The caller omits `payload` when `iicp_conf` is present.
+ */
+export declare function encryptPayload(payload: unknown, cx: CxPublicKey, taskId: string, intent: string): Promise<Record<string, unknown>>;
+/**
+ * Decrypt an IICP-CX envelope for a browser provider node.  This is the mirror
+ * of encryptPayload(), used only after the tab explicitly starts serving via a
+ * relay and has advertised its generated cx_public_key to the directory.
+ */
+export declare function decryptPayload(envelope: Record<string, unknown>, secretKey: Uint8Array, taskId: string, intent: string): Promise<unknown>;
+/** Read a node's canonical `cx_public_key`; accept deprecated `public_key` alias during migration. */
+export declare function nodeCxKey(node: Record<string, unknown>): CxPublicKey | null;

package/dist/cxConfidentiality.js

@@ -0,0 +1,117 @@
+// IICP-CX S.16 Tier-1 confidentiality — BROWSER CX-Consumer (mandatory, no opt-out).
+// Byte-compatible with the node/adapter decrypt: X25519 (@noble/curves) +
+// HKDF-SHA256 (@noble/hashes) + AES-256-GCM (WebCrypto, universally available).
+// The browser SDK can't use Node-crypto; this is the WebCrypto/noble equivalent.
+import { x25519 } from "@noble/curves/ed25519.js";
+import { hkdf } from "@noble/hashes/hkdf.js";
+import { sha256 } from "@noble/hashes/sha2.js";
+function b64urlEncode(b) {
+    let bin = "";
+    for (let i = 0; i < b.length; i++)
+        bin += String.fromCharCode(b[i]);
+    return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function b64urlDecode(s) {
+    let t = s.replace(/-/g, "+").replace(/_/g, "/");
+    while (t.length % 4)
+        t += "=";
+    const bin = atob(t);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+function constantTimeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}
+function cxInfo(taskId, intent) {
+    return new TextEncoder().encode(`IICP-CX-v1${taskId}${intent}`);
+}
+function cxAad(taskId, intent) {
+    return new TextEncoder().encode(`${taskId}|${intent}`);
+}
+/** Generate a browser-provider X25519 key pair suitable for directory advertisement. */
+export function createCxKeyPair(prefix = "cx-browser") {
+    const secretKey = x25519.utils.randomSecretKey();
+    const publicKeyBytes = x25519.getPublicKey(secretKey);
+    const fingerprint = b64urlEncode(sha256(publicKeyBytes)).slice(0, 12);
+    return {
+        secretKey,
+        publicKey: {
+            algorithm: "X25519",
+            encoding: "base64url",
+            key: b64urlEncode(publicKeyBytes),
+            key_id: `${prefix}-${fingerprint}`,
+        },
+    };
+}
+/**
+ * Encrypt a task payload to the node's advertised X25519 key, producing an `iicp_conf`
+ * envelope identical to what the SDKs send and the adapter decrypts (IICP-CX §5):
+ * ephemeral X25519 → HKDF-SHA256(salt=nonce, info="IICP-CX-v1"+task_id+intent) →
+ * AES-256-GCM(aad=task_id+"|"+intent). The caller omits `payload` when `iicp_conf` is present.
+ */
+export async function encryptPayload(payload, cx, taskId, intent) {
+    if (cx.algorithm !== "X25519") {
+        throw new Error(`Unsupported cx_public_key algorithm: ${cx.algorithm}`);
+    }
+    const nodePub = b64urlDecode(cx.key);
+    const ephemPriv = x25519.utils.randomSecretKey();
+    const ephemPub = x25519.getPublicKey(ephemPriv);
+    const shared = x25519.getSharedSecret(ephemPriv, nodePub);
+    const nonce = crypto.getRandomValues(new Uint8Array(12));
+    const info = cxInfo(taskId, intent);
+    const keyBytes = hkdf(sha256, shared, nonce, info, 32);
+    const aad = cxAad(taskId, intent);
+    const plaintext = new TextEncoder().encode(JSON.stringify(payload));
+    const key = await crypto.subtle.importKey("raw", new Uint8Array(keyBytes), "AES-GCM", false, ["encrypt"]);
+    const ct = new Uint8Array(await crypto.subtle.encrypt({ name: "AES-GCM", iv: new Uint8Array(nonce), additionalData: new Uint8Array(aad) }, key, new Uint8Array(plaintext)));
+    return {
+        version: 1,
+        recipient_key_id: cx.key_id,
+        kem_ciphertext: b64urlEncode(ephemPub),
+        encrypted_body: b64urlEncode(ct), // WebCrypto AES-GCM output = ciphertext || 16-byte tag
+        nonce: b64urlEncode(nonce),
+        aad: b64urlEncode(aad),
+        plaintext_size: plaintext.length,
+    };
+}
+/**
+ * Decrypt an IICP-CX envelope for a browser provider node.  This is the mirror
+ * of encryptPayload(), used only after the tab explicitly starts serving via a
+ * relay and has advertised its generated cx_public_key to the directory.
+ */
+export async function decryptPayload(envelope, secretKey, taskId, intent) {
+    if (envelope.version !== 1) {
+        throw new Error(`Unsupported iicp_conf version: ${String(envelope.version)}`);
+    }
+    const kem = envelope.kem_ciphertext;
+    const encryptedBody = envelope.encrypted_body;
+    const nonceRaw = envelope.nonce;
+    if (typeof kem !== "string" || typeof encryptedBody !== "string" || typeof nonceRaw !== "string") {
+        throw new Error("Malformed iicp_conf envelope");
+    }
+    const aad = cxAad(taskId, intent);
+    if (typeof envelope.aad === "string" && !constantTimeEqual(envelope.aad, b64urlEncode(aad))) {
+        throw new Error("iicp_conf AAD does not match task identity");
+    }
+    const shared = x25519.getSharedSecret(secretKey, b64urlDecode(kem));
+    const nonce = b64urlDecode(nonceRaw);
+    const keyBytes = hkdf(sha256, shared, nonce, cxInfo(taskId, intent), 32);
+    const key = await crypto.subtle.importKey("raw", new Uint8Array(keyBytes), "AES-GCM", false, ["decrypt"]);
+    const plaintext = await crypto.subtle.decrypt({ name: "AES-GCM", iv: new Uint8Array(nonce), additionalData: new Uint8Array(aad) }, key, new Uint8Array(b64urlDecode(encryptedBody)));
+    return JSON.parse(new TextDecoder().decode(plaintext));
+}
+/** Read a node's canonical `cx_public_key`; accept deprecated `public_key` alias during migration. */
+export function nodeCxKey(node) {
+    const raw = (node["cx_public_key"] ?? node["public_key"]);
+    if (raw && typeof raw === "object" && raw["algorithm"] === "X25519" && typeof raw["key"] === "string") {
+        return { algorithm: "X25519", key: String(raw["key"]), key_id: String(raw["key_id"] ?? "cx-1") };
+    }
+    return null;
+}