@iicp/client 0.7.87 → 0.7.88

package/dist/cli.js

@@ -11,6 +11,8 @@ exports.endpointIsLocalOrPrivate = endpointIsLocalOrPrivate;
 exports.directTunnelFallbackReason = directTunnelFallbackReason;
 exports.applySavedNode = applySavedNode;
 exports.verifyCreditAwards = verifyCreditAwards;
+exports.handoffRestartDelay = handoffRestartDelay;
+exports.completeHandoffForNode = completeHandoffForNode;
 exports.main = main;
 // SPDX-License-Identifier: Apache-2.0
 /**
@@ -172,9 +174,10 @@ function printHelp() {
         `  --model NAME               IICP_BACKEND_MODEL — model name (e.g. qwen2.5:0.5b)\n` +
         `  (or --node NAME            load both from ~/.iicp/nodes/<NAME>.json after \`iicp-node init\`)\n\n` +
         `serve optional:\n` +
-        `  --backend-url URL          IICP_BACKEND_URL — Ollama / vLLM / LM Studio (default http://localhost:11434; anthropic → https://api.anthropic.com)\n` +
-        `  --backend-type TYPE        IICP_BACKEND_TYPE — openai_compat | vllm | llamacpp | anthropic (default openai_compat)\n` +
+        `  --backend-url URL          IICP_BACKEND_URL — local backend (MeshLLM → http://localhost:9337/v1)\n` +
+        `  --backend-type TYPE        IICP_BACKEND_TYPE — openai_compat | vllm | llamacpp | meshllm | anthropic (default openai_compat)\n` +
         `  --backend-api-key KEY      IICP_BACKEND_API_KEY — Bearer key for an auth'd backend (LM Studio, hosted); anthropic uses it as x-api-key\n` +
+        `  --experimental             IICP_EXPERIMENTAL — enable an explicitly selected preview backend feature\n` +
         `  --policy-manifest FILE     IICP_POLICY_MANIFEST_FILE — sign and advertise a public node-policy JSON document\n` +
         `  --public-endpoint URL      IICP_PUBLIC_ENDPOINT — externally reachable URL of this node\n` +
         `  --directory-url URL        IICP_DIRECTORY_URL (default https://iicp.network/api)\n` +
@@ -240,8 +243,9 @@ function printServeHelp() {
         `  --node NAME                load ~/.iicp/nodes/<NAME>.json from \`iicp-node init\`\n\n` +
         `Core options:\n` +
         `  --backend-url URL          IICP_BACKEND_URL — Ollama / vLLM / LM Studio (default http://localhost:11434; anthropic → https://api.anthropic.com)\n` +
-        `  --backend-type TYPE        IICP_BACKEND_TYPE — openai_compat | vllm | llamacpp | anthropic\n` +
+        `  --backend-type TYPE        IICP_BACKEND_TYPE — openai_compat | vllm | llamacpp | meshllm | anthropic\n` +
         `  --backend-api-key KEY      IICP_BACKEND_API_KEY — Bearer key for auth'd backends\n` +
+        `  --experimental             IICP_EXPERIMENTAL — enable an explicitly selected preview backend feature\n` +
         `  --policy-manifest FILE     IICP_POLICY_MANIFEST_FILE — sign and advertise a public node-policy JSON document\n` +
         `  --public-endpoint URL      IICP_PUBLIC_ENDPOINT — externally reachable URL of this node\n` +
         `  --directory-url URL        IICP_DIRECTORY_URL (default https://iicp.network/api)\n` +
@@ -363,7 +367,7 @@ async function checkDependencies(backendUrl) {
  * else probe /api/version → ollama, else custom.
  */
 async function detectBackendFlavor(backendUrl, apiKey, backendType) {
-    if (backendType === "anthropic" || backendType === "vllm" || backendType === "llamacpp")
+    if (backendType === "anthropic" || backendType === "vllm" || backendType === "llamacpp" || backendType === "meshllm")
         return backendType;
     const base = backendUrl.replace(/\/$/, "");
     const root = base.endsWith("/v1") ? base.slice(0, -3) : base;
@@ -703,9 +707,16 @@ async function runServe(opts) {
     // so a bare `serve --model x` works without --backend-url. An `anthropic` backend
     // defaults to the Anthropic API, not localhost Ollama. Mirrors Python cli.py ~704.
     if (!opts.backendUrl) {
-        opts.backendUrl =
-            opts.backendType === "anthropic" ? "https://api.anthropic.com" : "http://localhost:11434";
-    }
+        opts.backendUrl = opts.backendType === "anthropic"
+            ? "https://api.anthropic.com"
+            : opts.backendType === "meshllm"
+                ? "http://localhost:9337/v1"
+                : "http://localhost:11434";
+    }
+    // Resolve the public default only after a saved node has had the opportunity
+    // to supply its own directory URL. This preserves saved-node precedence.
+    if (!opts.directoryUrl)
+        opts.directoryUrl = "https://iicp.network/api";
     // Onboarding: if no --model given, auto-select the first model the backend advertises
     // (Ollama /api/tags) so a bare `iicp-node serve` just works (parity with Rust/Python).
     if (!opts.model && opts.backendUrl) {
@@ -724,6 +735,32 @@ async function runServe(opts) {
         catch {
             // best-effort; the required-model check below surfaces a clear error
         }
+        // MeshLLM is OpenAI-compatible rather than Ollama-compatible. Its model
+        // inventory decides routing, so never choose an arbitrary model when several
+        // are available.
+        if (!opts.model) {
+            try {
+                const root = opts.backendUrl.replace(/\/$/, "").replace(/\/v1$/, "");
+                const r = await fetch(`${root}/v1/models`, { signal: AbortSignal.timeout(3000) });
+                if (r.ok) {
+                    const d = (await r.json());
+                    const models = (d.data ?? []).map((m) => m.id).filter((id) => Boolean(id));
+                    if (opts.backendType === "meshllm" && models.length > 1) {
+                        process.stderr.write(`ERROR: MeshLLM advertises multiple models; select one with --model: ${models.join(", ")}\n`);
+                        return 2;
+                    }
+                    if (models.length === 1) {
+                        opts.model = models[0];
+                        process.stderr.write(`[iicp-node] no --model given — auto-selected '${opts.model}' from ${opts.backendUrl}\n`);
+                    }
+                }
+            }
+            catch { /* required-model check below remains authoritative */ }
+        }
+    }
+    if (opts.backendType === "meshllm" && opts.model === "mesh" && !opts.experimental) {
+        process.stderr.write("ERROR: MeshLLM model 'mesh' is experimental; pass --experimental explicitly to enable it.\n");
+        return 2;
     }
     if (!opts.backendUrl || !opts.model) {
         process.stderr.write("ERROR: --model is required (--backend-url defaults to http://localhost:11434). Set IICP_BACKEND_MODEL, or use --node NAME.\n");
@@ -1072,7 +1109,7 @@ async function runServe(opts) {
             catch { /* best-effort */ }
             return [];
         })();
-        const extra = allModels.filter((m) => m !== opts.model);
+        const extra = allModels.filter((m) => m !== opts.model && (opts.backendType !== "meshllm" || opts.experimental || m !== "mesh"));
         if (extra.length > 0) {
             node["_cfg"].capabilities = extra;
             // eslint-disable-next-line no-console
@@ -1082,6 +1119,9 @@ async function runServe(opts) {
     catch {
         // best-effort; no-op on error
     }
+    if (opts.backendType === "meshllm" && !opts.experimental) {
+        node["_cfg"].excludedModels = ["mesh"];
+    }
     // NAT-4 guard: if endpoint is non-routable and no relay configured, skip
     // registration to avoid a confusing 422 from the directory's RoutableEndpoint check.
     const epLocal = endpointIsLocalOrPrivate(publicEndpoint);
@@ -1134,6 +1174,8 @@ async function runServe(opts) {
                         }
                     }
                 }
+                if (opts.node)
+                    completeHandoffForNode(opts.node);
                 break;
             }
             catch (exc) {
@@ -1192,6 +1234,7 @@ async function runServe(opts) {
             },
         });
     }
+    const handoffTimer = scheduleSupervisedHandoffRestart(opts.node);
     const stop = node.serve(handler, { host: opts.host, port: opts.port, nodeToken: token });
     await new Promise((resolve) => {
         const shutdown = async (sig) => {
@@ -1218,6 +1261,8 @@ async function runServe(opts) {
             }
             tunnelHandle?.close(); // #520 — tear the Quick Tunnel down with the node
             stop();
+            if (handoffTimer)
+                clearTimeout(handoffTimer);
             stopAutoUpdate();
             instanceLock.release(); // #405 — free the pidfile on shutdown
             resolve();
@@ -1985,6 +2030,7 @@ function printOperatorHelp() {
         `Manage your operator identity.\n\n` +
         `subcommands:\n` +
         `  rename <name>              Change your public display_name (signed by your operator key)\n` +
+        `  key <rotate|revoke>         Safely migrate or revoke your cryptographic operator key\n` +
         `  dsr <action>               Export, restrict, or anonymize your directory records\n` +
         `  encrypt                    Password-encrypt the operator secret at rest ($IICP_OPERATOR_PASSPHRASE)\n` +
         `  decrypt                    Remove at-rest encryption of the operator secret\n\n` +
@@ -2110,6 +2156,214 @@ async function runOperatorDsr(argv) {
         process.stdout.write(`Retained records: ${retention}\n`);
     return 0;
 }
+function operatorArtifactPath(kind) {
+    return path.join((0, identity_js_1.configDir)(), `operator-${kind}-${new Date().toISOString().replace(/[-:.]/g, "").replace("Z", "Z")}.json`);
+}
+function writePrivateJsonNew(file, value) {
+    fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`, { encoding: "utf8", flag: "wx", mode: 0o600 });
+    fs.chmodSync(file, 0o600);
+}
+function writeOperatorHandoffMarker(nodeNames) {
+    const stamp = Math.floor(Date.now() / 1000);
+    const marker = path.join((0, identity_js_1.configDir)(), `operator-handoff-pending-${stamp}.json`);
+    writePrivateJsonNew(marker, {
+        schema: "iicp.operator-handoff.v1",
+        action: "rotate",
+        created_at_unix: stamp,
+        grace_seconds: 300,
+        affected_node_names: nodeNames,
+        restart_requested_node_names: [],
+        completed_node_names: [],
+    });
+    return marker;
+}
+function handoffMarkerPaths() {
+    try {
+        return fs.readdirSync((0, identity_js_1.configDir)())
+            .filter((name) => /^operator-handoff-pending-.*\.json$/.test(name))
+            .map((name) => path.join((0, identity_js_1.configDir)(), name));
+    }
+    catch {
+        return [];
+    }
+}
+function readHandoffMarker(file) {
+    try {
+        const body = JSON.parse(fs.readFileSync(file, "utf8"));
+        return body && typeof body === "object" ? body : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Return remaining grace seconds; completed/restarted services never restart twice. */
+function handoffRestartDelay(marker, nodeName, now) {
+    const names = (field) => new Set(Array.isArray(marker[field]) ? marker[field].filter((value) => typeof value === "string") : []);
+    const affected = names("affected_node_names");
+    const requested = names("restart_requested_node_names");
+    const completed = names("completed_node_names");
+    if (!affected.has(nodeName) || requested.has(nodeName) || completed.has(nodeName))
+        return null;
+    const created = marker.created_at_unix;
+    const grace = marker.grace_seconds;
+    if (typeof created !== "number")
+        return null;
+    return Math.max(0, created + (typeof grace === "number" && grace >= 0 ? grace : 300) - now);
+}
+function completeHandoffForNode(nodeName) {
+    for (const file of handoffMarkerPaths()) {
+        const marker = readHandoffMarker(file);
+        if (!marker || !Array.isArray(marker.affected_node_names) || !marker.affected_node_names.includes(nodeName))
+            continue;
+        // A rotation can be written while this process is still completing its
+        // initial registration. Only the successor that claimed a supervised
+        // restart may complete the marker; do not erase an unclaimed handoff.
+        const requested = new Set(marker.restart_requested_node_names ?? []);
+        if (!requested.has(nodeName))
+            continue;
+        const affected = new Set(marker.affected_node_names ?? []);
+        const completed = new Set(marker.completed_node_names ?? []);
+        completed.add(nodeName);
+        try {
+            if ([...affected].every((name) => completed.has(name)))
+                fs.unlinkSync(file);
+            else
+                fs.writeFileSync(file, `${JSON.stringify({ ...marker, completed_node_names: [...completed] }, null, 2)}\n`, { mode: 0o600 });
+        }
+        catch { /* best effort only */ }
+    }
+}
+function scheduleSupervisedHandoffRestart(nodeName) {
+    if (!nodeName || !envBool("IICP_SUPERVISED"))
+        return null;
+    let checking = false;
+    const check = () => {
+        if (checking)
+            return;
+        checking = true;
+        try {
+            for (const file of handoffMarkerPaths()) {
+                const marker = readHandoffMarker(file);
+                if (!marker || handoffRestartDelay(marker, nodeName, Math.floor(Date.now() / 1000)) !== 0)
+                    continue;
+                const requested = new Set(marker.restart_requested_node_names ?? []);
+                requested.add(nodeName);
+                try {
+                    fs.writeFileSync(file, `${JSON.stringify({ ...marker, restart_requested_node_names: [...requested] }, null, 2)}\n`, { mode: 0o600 });
+                    console.error(`[iicp-node] operator handoff grace period complete — exiting with code ${exports.TUNNEL_DEAD_EXIT_CODE} so the supervisor reloads the successor identity.`);
+                    process.exit(exports.TUNNEL_DEAD_EXIT_CODE);
+                }
+                catch { /* retry on the next monitor pass */ }
+            }
+        }
+        finally {
+            checking = false;
+        }
+    };
+    // The marker is written by a separate `operator key rotate` invocation,
+    // so it can appear after `serve` has already started. Re-check redacted
+    // local state rather than assuming startup saw every future handoff.
+    check();
+    return setInterval(check, 15_000);
+}
+async function runOperatorKey(argv) {
+    const { values, positionals } = safeParseArgs({
+        args: argv,
+        options: { "directory-url": { type: "string" }, yes: { type: "boolean" }, help: { type: "boolean", short: "h" } },
+        allowPositionals: true,
+    });
+    if (values.help) {
+        process.stdout.write("usage: iicp-node operator key <rotate|revoke> --yes [--directory-url URL]\n");
+        return 0;
+    }
+    const action = positionals[0];
+    if (action !== "rotate" && action !== "revoke")
+        return 2;
+    if (!values.yes) {
+        process.stderr.write("This changes the cryptographic operator identity used by saved nodes. Re-run with --yes.\n");
+        return 2;
+    }
+    const stored = (0, identity_js_1.loadOperator)();
+    if (!stored || !(0, identity_js_1.operatorIsKeyBacked)(stored)) {
+        process.stderr.write("ERROR: a key-backed local operator identity is required.\n");
+        return 1;
+    }
+    const unlock = (0, identity_js_1.operatorIsEncrypted)(stored) ? await operatorPassphrase("Operator passphrase: ", false) : undefined;
+    let old;
+    try {
+        old = (0, identity_js_1.operatorIsEncrypted)(stored) ? (0, identity_js_1.operatorDecryptAtRest)(stored, unlock ?? "") : stored;
+    }
+    catch (e) {
+        process.stderr.write(`ERROR: ${e instanceof Error ? e.message : String(e)}\n`);
+        return 1;
+    }
+    let successor;
+    let backupPath;
+    try {
+        if (action === "rotate") {
+            const backupPw = unlock ?? process.env["IICP_OPERATOR_BACKUP_PASSPHRASE"] ?? await operatorPassphrase("New backup passphrase: ", true);
+            if (!backupPw)
+                return 1;
+            backupPath = operatorArtifactPath("before-rotation");
+            writePrivateJsonNew(backupPath, (0, identity_js_1.operatorEncryptAtRest)(old, backupPw));
+            successor = (0, identity_js_1.generateOperator)({ display_name: old.display_name, contact: old.contact });
+        }
+        const directoryUrl = values["directory-url"] ?? process.env["IICP_DIRECTORY_URL"] ?? "https://iicp.network/api";
+        const base = `${directoryUrl.replace(/\/+$/, "")}/v1/operator`;
+        const challenge = await fetch(`${base}/challenge`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ operator_pub: old.operator_id }), signal: AbortSignal.timeout(15000) });
+        const challengeBody = await challenge.json();
+        if (!challenge.ok || typeof challengeBody.nonce !== "string")
+            throw new Error(challengeBody.error?.message ?? "directory challenge was incomplete");
+        const ts = Math.floor(Date.now() / 1000);
+        let payload;
+        let response;
+        if (action === "rotate") {
+            if (!successor)
+                throw new Error("successor identity missing");
+            payload = { operator_pub: old.operator_id, new_operator_pub: successor.operator_id, nonce: challengeBody.nonce, ts, reason_class: "operator_rotation" };
+            payload.sig = (0, delegation_js_1.signOperatorSelfService)((0, identity_js_1.operatorSigningKey)(old), "key_rotate", payload);
+            payload.new_key_sig = (0, delegation_js_1.signOperatorSelfService)((0, identity_js_1.operatorSigningKey)(successor), "key_rotate_successor", { operator_pub: old.operator_id, new_operator_pub: successor.operator_id, nonce: challengeBody.nonce, ts, rotation_epoch: null });
+            response = await fetch(`${base}/key/rotate`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(payload), signal: AbortSignal.timeout(15000) });
+        }
+        else {
+            payload = { operator_pub: old.operator_id, nonce: challengeBody.nonce, ts, confirm: true, reason_class: "operator_request" };
+            payload.sig = (0, delegation_js_1.signOperatorSelfService)((0, identity_js_1.operatorSigningKey)(old), "key_revoke", payload);
+            response = await fetch(`${base}/key/revoke`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(payload), signal: AbortSignal.timeout(15000) });
+        }
+        const body = await response.json();
+        if (!response.ok)
+            throw new Error(body.error?.message ?? `HTTP ${response.status}`);
+        const receiptPath = operatorArtifactPath(`${action}-receipt`);
+        writePrivateJsonNew(receiptPath, { schema: "iicp.operator-key-receipt.v1", action, status: body.status, operator_fingerprint: body.operator_fingerprint, linked_nodes: body.linked_nodes, receipt_id_prefix: body.receipt_id_prefix });
+        if (action === "rotate" && successor) {
+            (0, identity_js_1.saveOperator)(successor);
+            let migrated = 0;
+            const nodeNames = [];
+            for (const node of (0, identity_js_1.listNodes)())
+                if (node.operator_id === old.operator_id) {
+                    node.operator_id = successor.operator_id;
+                    nodeNames.push(node.name);
+                    (0, identity_js_1.saveNode)(node);
+                    migrated += 1;
+                }
+            const handoffPath = writeOperatorHandoffMarker(nodeNames);
+            process.stdout.write(`Operator identity migrated; ${migrated} saved node(s) will re-register with the new key.\nEncrypted old-key backup: ${backupPath}\nRedacted receipt: ${receiptPath}\nSupervised handoff marker: ${handoffPath} (one restart pass after 5 minutes).\n`);
+        }
+        else
+            process.stdout.write(`Operator identity revoked; redacted receipt: ${receiptPath}\n`);
+        return 0;
+    }
+    catch (e) {
+        if (backupPath) {
+            try {
+                fs.unlinkSync(backupPath);
+            }
+            catch { }
+        }
+        process.stderr.write(`ERROR: operator key ${action} failed: ${e instanceof Error ? e.message : String(e)}\n`);
+        return 1;
+    }
+}
 function printOperatorEncryptHelp() {
     process.stdout.write(`usage: iicp-node operator encrypt\n\n` +
         `Password-encrypt the operator secret at rest. The command prompts for a passphrase\n` +
@@ -2152,6 +2406,8 @@ async function runOperator(argv) {
     }
     if (sub === "dsr")
         return runOperatorDsr(argv.slice(1));
+    if (sub === "key")
+        return runOperatorKey(argv.slice(1));
     if (sub !== "rename") {
         process.stderr.write(`unknown operator subcommand: ${sub}\n`);
         printOperatorHelp();
@@ -2635,6 +2891,7 @@ async function dispatch(argv) {
             "policy-manifest": { type: "string" },
             "backend-type": { type: "string" },
             "backend-api-key": { type: "string" },
+            experimental: { type: "boolean" },
             model: { type: "string" },
             "public-endpoint": { type: "string" },
             "directory-url": { type: "string" },
@@ -2673,10 +2930,11 @@ async function dispatch(argv) {
         backendType: values["backend-type"] ??
             envOr("IICP_BACKEND_TYPE", "openai_compat"),
         backendApiKey: values["backend-api-key"] ?? envOr("IICP_BACKEND_API_KEY") ?? "",
+        experimental: Boolean(values.experimental) || envBool("IICP_EXPERIMENTAL"),
         model: values.model ?? envOr("IICP_BACKEND_MODEL") ?? "",
         publicEndpoint: values["public-endpoint"] ?? envOr("IICP_PUBLIC_ENDPOINT") ?? "",
         directoryUrl: values["directory-url"] ??
-            envOr("IICP_DIRECTORY_URL", "https://iicp.network/api"),
+            envOr("IICP_DIRECTORY_URL") ?? "",
         region: values.region ?? envOr("IICP_REGION"),
         intent: values.intent ?? envOr("IICP_INTENT", "urn:iicp:intent:llm:chat:v1"),
         maxConcurrent: values["max-concurrent"] !== undefined