@iicp/client 0.7.37 → 0.7.39

package/dist/cli.js

@@ -2,6 +2,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.applySavedNode = applySavedNode;
+exports.verifyCreditAwards = verifyCreditAwards;
 exports.main = main;
 // SPDX-License-Identifier: Apache-2.0
 /**
@@ -32,9 +33,11 @@ const node_js_1 = require("./node.js");
 const client_js_1 = require("./client.js");
 const node_log_js_1 = require("./node_log.js");
 const cip_policy_js_1 = require("./cip_policy.js");
+const index_js_1 = require("./proxy/index.js");
 const instance_lock_js_1 = require("./instance_lock.js");
-const index_js_1 = require("./backends/index.js");
+const index_js_2 = require("./backends/index.js");
 const identity_js_1 = require("./identity.js");
+const delegation_js_1 = require("./delegation.js");
 function envOr(name, fallback) {
     const v = process.env[name];
     return v ?? fallback;
@@ -58,7 +61,11 @@ function printHelp() {
         `  init                       Interactive wizard — set up operator + first node config\n` +
         `  list                       List node configs saved under ~/.iicp/nodes/\n` +
         `  serve                      Register and serve a node\n` +
-        `  query <prompt>             Discover mesh nodes and submit a chat task\n\n` +
+        `  query <prompt>             Discover mesh nodes and submit a chat task\n` +
+        `  credits                    Show this node's earned / spent / balance credits\n` +
+        `  operator rename <name>     Change your public display_name (signed by your operator key)\n` +
+        `  operator encrypt           Password-encrypt the operator secret at rest ($IICP_OPERATOR_PASSPHRASE)\n` +
+        `  operator decrypt           Remove at-rest encryption of the operator secret\n\n` +
         `Run an IICP provider node backed by an OpenAI-compatible server.\n\n` +
         `serve required (flag or env):\n` +
         `  --model NAME               IICP_BACKEND_MODEL — model name (e.g. qwen2.5:0.5b)\n` +
@@ -407,6 +414,18 @@ async function runServe(opts) {
             allowCoordinator: true,
         });
     }
+    // 2-C: co-host the compat proxy on loopback alongside the node, supervised so a
+    // proxy failure logs but never drops the network-facing node. Forced to 127.0.0.1.
+    if (opts.withProxy) {
+        const pport = envInt("IICP_PROXY_PORT", 9483);
+        const pclient = new client_js_1.IicpClient({
+            directory_url: opts.directoryUrl,
+            region: opts.region,
+        });
+        const pserver = (0, index_js_1.createProxyServer)(pclient);
+        pserver.on("error", (e) => process.stderr.write(`co-hosted proxy error (node continues): ${String(e)}\n`));
+        pserver.listen(pport, "127.0.0.1", () => process.stdout.write(`co-hosted proxy → http://127.0.0.1:${pport} (OpenAI/Ollama/Anthropic compat)\n`));
+    }
     if (opts.node) {
         const saved = (0, identity_js_1.loadNode)(opts.node);
         if (!saved) {
@@ -438,8 +457,8 @@ async function runServe(opts) {
         process.stderr.write("ERROR: --model is required (--backend-url defaults to http://localhost:11434). Set IICP_BACKEND_MODEL, or use --node NAME.\n");
         return 2;
     }
-    if (!index_js_1.BACKEND_TYPES.includes(opts.backendType)) {
-        process.stderr.write(`ERROR: --backend-type must be one of ${JSON.stringify(index_js_1.BACKEND_TYPES)}.\n`);
+    if (!index_js_2.BACKEND_TYPES.includes(opts.backendType)) {
+        process.stderr.write(`ERROR: --backend-type must be one of ${JSON.stringify(index_js_2.BACKEND_TYPES)}.\n`);
         return 2;
     }
     const nodeId = (opts.nodeId || (0, node_crypto_1.randomUUID)()).slice(0, 36);
@@ -540,6 +559,20 @@ async function runServe(opts) {
     }
     const backendFlavor = await detectBackendFlavor(opts.backendUrl, opts.backendApiKey, opts.backendType);
     process.stderr.write(`backend detected: ${backendFlavor}\n`);
+    // #463/#464 — bind the operator identity: issue a delegation FROM the (key-backed) operator
+    // identity for this node and advertise the public display_name. The directory verifies the
+    // delegation (operator_pub == operator_id) and records the operator. Never sends the secret/contact.
+    const _op = (0, identity_js_1.loadOperator)();
+    let _opDelegation;
+    let _opDisplayName;
+    let _opCreatedAt;
+    let _opIntegrityHash;
+    if (_op && (0, identity_js_1.operatorIsKeyBacked)(_op)) {
+        _opDelegation = (0, delegation_js_1.issueDelegation)((0, identity_js_1.operatorSigningKey)(_op), nodeId);
+        _opDisplayName = _op.display_name || undefined;
+        _opCreatedAt = _op.created_at;
+        _opIntegrityHash = _op.operator_integrity_hash || undefined;
+    }
     const node = new node_js_1.IicpNode({
         nodeId,
         endpoint: publicEndpoint,
@@ -550,6 +583,10 @@ async function runServe(opts) {
         directoryUrl: opts.directoryUrl,
         maxConcurrent: opts.maxConcurrent,
         relayWorkerEndpoint: opts.relayWorkerEndpoint || undefined,
+        operatorDelegation: _opDelegation,
+        operatorDisplayName: _opDisplayName,
+        operatorCreatedAt: _opCreatedAt,
+        operatorIntegrityHash: _opIntegrityHash,
     });
     // Apply collected NAT profile (covers both auto-detect and tier-0 IPv6 cases).
     if (natProfile) {
@@ -586,7 +623,7 @@ async function runServe(opts) {
         const t = opts.backendUrl.replace(/\/$/, "");
         return t.endsWith("/v1") ? t : `${t}/v1`;
     })();
-    const handler = (0, index_js_1.getBackendHandler)(opts.backendType, {
+    const handler = (0, index_js_2.getBackendHandler)(opts.backendType, {
         baseUrl: _baseUrl,
         model: opts.model,
         // #5 — Bearer key for auth'd backends (LM Studio, hosted). Empty/undefined = no header.
@@ -654,6 +691,18 @@ async function runServe(opts) {
             "Set IICP_PUBLIC_ENDPOINT=<url> or IICP_RELAY_WORKER_ENDPOINT=<host>:<port> to register.");
         opts.skipRegistration = true;
     }
+    // #457 / ADR-040 — advertise the native IICP binary transport. serve() multiplexes it
+    // onto the SAME socket as HTTP (first-byte detection), so transport_endpoint shares the
+    // endpoint's host:port with the iicp:// scheme. Set from the FINAL endpoint (after NAT
+    // profile application); register() only sends it when registering (skipRegistration gates
+    // the non-routable case) → advertise-when-reachable. Opt out with IICP_DISABLE_NATIVE_TRANSPORT=1.
+    if (!opts.skipRegistration && process.env["IICP_DISABLE_NATIVE_TRANSPORT"] !== "1") {
+        const finalEndpoint = node["_cfg"].endpoint;
+        const nativeEndpoint = finalEndpoint ? (0, node_js_1.deriveNativeEndpoint)(finalEndpoint) : null;
+        if (nativeEndpoint) {
+            node["_cfg"].transportEndpoint = nativeEndpoint;
+        }
+    }
     // #404 — register with bounded backoff retry. On persistent failure, pass an
     // empty token (NOT undefined) so the heartbeat loop still starts and re-registers
     // on the first 401 (#399 path) once the directory is reachable — the self-healing
@@ -666,6 +715,20 @@ async function runServe(opts) {
                 // eslint-disable-next-line no-console
                 console.log(`[iicp-node] registered as ${nodeId} (token=${(token ?? "").slice(0, 8)}…)`);
                 (0, node_log_js_1.writeNodeEvent)(nodeId, "register_ok", `endpoint=${opts.publicEndpoint || `http://localhost:${opts.port}`}`, logDir);
+                // #456 — cache the token in the saved config so `iicp-node credits` can
+                // authenticate later without re-registering (best-effort).
+                if (opts.node && token) {
+                    const saved = (0, identity_js_1.loadNode)(opts.node);
+                    if (saved) {
+                        saved.node_token = token;
+                        try {
+                            (0, identity_js_1.saveNode)(saved);
+                        }
+                        catch {
+                            /* best-effort cache */
+                        }
+                    }
+                }
                 break;
             }
             catch (exc) {
@@ -765,7 +828,8 @@ async function runQuery(argv) {
             intent,
             payload,
         });
-        if (resp.status === "completed" && resp.result) {
+        // Spec terminal success status is "success" (was "completed"); accept both.
+        if ((resp.status === "success" || resp.status === "completed") && resp.result) {
             const res = resp.result;
             const content = typeof res["content"] === "string"
                 ? res["content"]
@@ -787,6 +851,490 @@ async function runQuery(argv) {
         return 1;
     }
 }
+/** SPKI DER prefix for an Ed25519 public key (12 bytes); + 32 raw key bytes = a parseable SPKI key. */
+const ED25519_SPKI_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
+/** #458 hash-chain genesis root: SHA256_hex("iicp:dir:event-log:genesis:v1"). The prev_hash
+ *  of a genesis/legacy event; bound into the signing input the directory verifies against. */
+const EVENT_LOG_GENESIS_ROOT = "c44802bedf3e63b5a3f1634c5d19263634f92f26dd15401b09b06dd53a80cf9d";
+function isLNum(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v) && "__num" in v;
+}
+/** Minimal recursive-descent JSON parse that preserves number literals verbatim. */
+function losslessParse(text) {
+    let i = 0;
+    const ws = () => {
+        while (i < text.length && (text[i] === " " || text[i] === "\t" || text[i] === "\n" || text[i] === "\r"))
+            i++;
+    };
+    const parseStr = () => {
+        i++; // opening quote
+        let s = "";
+        while (text[i] !== '"') {
+            const ch = text[i];
+            if (ch === "\\") {
+                const e = text[++i];
+                if (e === "u") {
+                    s += String.fromCharCode(parseInt(text.slice(i + 1, i + 5), 16));
+                    i += 5;
+                }
+                else {
+                    const map = {
+                        '"': '"', "\\": "\\", "/": "/", b: "\b", f: "\f", n: "\n", r: "\r", t: "\t",
+                    };
+                    s += map[e] ?? e;
+                    i++;
+                }
+            }
+            else {
+                s += ch;
+                i++;
+            }
+        }
+        i++; // closing quote
+        return s;
+    };
+    const parseVal = () => {
+        ws();
+        const c = text[i];
+        if (c === "{") {
+            const o = {};
+            i++;
+            ws();
+            if (text[i] === "}") {
+                i++;
+                return o;
+            }
+            for (;;) {
+                ws();
+                const key = parseStr();
+                ws();
+                i++; // ':'
+                o[key] = parseVal();
+                ws();
+                if (text[i] === ",") {
+                    i++;
+                    continue;
+                }
+                i++; // '}'
+                break;
+            }
+            return o;
+        }
+        if (c === "[") {
+            const a = [];
+            i++;
+            ws();
+            if (text[i] === "]") {
+                i++;
+                return a;
+            }
+            for (;;) {
+                a.push(parseVal());
+                ws();
+                if (text[i] === ",") {
+                    i++;
+                    continue;
+                }
+                i++; // ']'
+                break;
+            }
+            return a;
+        }
+        if (c === '"')
+            return parseStr();
+        if (c === "t") {
+            i += 4;
+            return true;
+        }
+        if (c === "f") {
+            i += 5;
+            return false;
+        }
+        if (c === "n") {
+            i += 4;
+            return null;
+        }
+        const start = i;
+        while (i < text.length && "+-0123456789.eE".includes(text[i]))
+            i++;
+        return { __num: text.slice(start, i) };
+    };
+    return parseVal();
+}
+/**
+ * Canonical JSON byte-for-byte matching the directory (`federation.rs` / PHP `json_encode`):
+ * recursive lexicographic key-sort, no whitespace, `/` and non-ASCII unescaped (JS
+ * `JSON.stringify` already matches for strings), numbers emitted as their source literal.
+ */
+function canonicalJson(node) {
+    if (node === null || typeof node === "boolean" || typeof node === "string")
+        return JSON.stringify(node);
+    if (isLNum(node))
+        return node.__num;
+    if (Array.isArray(node))
+        return "[" + node.map(canonicalJson).join(",") + "]";
+    const keys = Object.keys(node).sort();
+    return "{" + keys.map((k) => JSON.stringify(k) + ":" + canonicalJson(node[k])).join(",") + "}";
+}
+/**
+ * #456 --verify: cryptographically confirm this node's CREDIT_AWARD income against the
+ * directory's signed event log (defends against a lying directory). Resolves the directory's
+ * Ed25519 key from /.well-known/did.json and re-derives + verifies each award signature.
+ * Free-tier CREDIT_ALLOCATION is unsigned by design, so it is not counted here (no cry-wolf).
+ */
+async function verifyCreditAwards(directoryUrl, nodeId) {
+    const origin = new URL(directoryUrl).origin; // did.json lives at the host root, not under /api
+    const didResp = await fetch(`${origin}/.well-known/did.json`, { signal: AbortSignal.timeout(20000) });
+    const did = (await didResp.json());
+    const x = did.verificationMethod?.[0]?.publicKeyJwk?.x;
+    if (!x)
+        throw new Error("directory did.json has no Ed25519 verification key");
+    const raw = Buffer.from(x, "base64url");
+    if (raw.length !== 32)
+        throw new Error(`bad Ed25519 key length ${raw.length}`);
+    const pubKey = (0, node_crypto_1.createPublicKey)({
+        key: Buffer.concat([ED25519_SPKI_PREFIX, raw]),
+        format: "der",
+        type: "spki",
+    });
+    const base = directoryUrl.replace(/\/+$/, "");
+    let sum = 0;
+    let verified = 0;
+    let failed = 0;
+    let since = 0;
+    for (;;) {
+        const url = `${base}/v1/events?event_types=CREDIT_AWARD&since_seq=${since}&limit=500`;
+        const resp = await fetch(url, { signal: AbortSignal.timeout(20000) });
+        const tree = losslessParse(await resp.text());
+        const events = tree["events"] ?? [];
+        if (events.length === 0)
+            break;
+        let maxSeq = since;
+        for (const evRaw of events) {
+            const ev = evRaw;
+            const seqNode = ev["seq"];
+            const seq = isLNum(seqNode) ? Number(seqNode.__num) : 0;
+            maxSeq = Math.max(maxSeq, seq);
+            if (ev["event_type"] !== "CREDIT_AWARD" || ev["node_id"] !== nodeId)
+                continue;
+            const sig = ev["sig"];
+            if (typeof sig !== "string")
+                continue;
+            const payload = ev["payload"];
+            const payloadHash = (0, node_crypto_1.createHash)("sha256").update(canonicalJson(payload)).digest("hex");
+            const eventId = typeof ev["event_id"] === "string" ? ev["event_id"] : "";
+            const tsNode = ev["ts_ms"];
+            const tsMs = isLNum(tsNode) ? Number(tsNode.__num) : 0;
+            // #458: prev_hash (tamper-evident chain) is bound into the signing input; the directory
+            // serves it per event, defaulting to GENESIS_ROOT for a genesis/legacy event.
+            const prevHash = typeof ev["prev_hash"] === "string" ? ev["prev_hash"] : EVENT_LOG_GENESIS_ROOT;
+            const msg = (0, node_crypto_1.createHash)("sha256")
+                .update(`${eventId}:CREDIT_AWARD:${seq}:${tsMs}:${payloadHash}:${prevHash}`)
+                .digest();
+            const sigBuf = Buffer.from(sig, "hex");
+            if (sigBuf.length === 64 && (0, node_crypto_1.verify)(null, msg, pubKey, sigBuf)) {
+                verified++;
+                const amt = typeof payload === "object" && payload !== null && !Array.isArray(payload)
+                    ? payload["amount"]
+                    : undefined;
+                if (amt !== undefined && isLNum(amt))
+                    sum += Number(amt.__num);
+            }
+            else {
+                failed++;
+            }
+        }
+        if (events.length < 500 || maxSeq <= since)
+            break;
+        since = maxSeq;
+    }
+    return { sum, verified, failed };
+}
+/**
+ * `iicp-node credits` (#456) — earned / spent / balance from the directory's
+ * reconcile-checked GET /v1/credits/summary. Figures come authenticated from the
+ * directory (not the local config), so editing the saved file cannot inflate them;
+ * `reconciles` flags a ledger that does not add up.
+ */
+async function runCredits(argv) {
+    const { values } = (0, node_util_1.parseArgs)({
+        args: argv,
+        options: {
+            node: { type: "string" },
+            "node-id": { type: "string" },
+            token: { type: "string" },
+            "directory-url": { type: "string" },
+            json: { type: "boolean" },
+            verify: { type: "boolean" },
+        },
+        allowPositionals: false,
+    });
+    const nodeName = values["node"];
+    let directoryUrl = values["directory-url"];
+    let nodeId = values["node-id"];
+    let token = values["token"] ?? process.env["IICP_NODE_TOKEN"];
+    if (nodeName) {
+        const saved = (0, identity_js_1.loadNode)(nodeName);
+        if (!saved) {
+            process.stderr.write(`ERROR: no saved config at ~/.iicp/nodes/${nodeName}.json — run \`iicp-node init\` / \`serve\` first.\n`);
+            return 1;
+        }
+        directoryUrl = directoryUrl ?? saved.directory_url;
+        nodeId = nodeId ?? saved.node_id;
+        token = token ?? saved.node_token;
+    }
+    directoryUrl = directoryUrl ?? process.env["IICP_DIRECTORY_URL"] ?? "https://iicp.network/api";
+    if (!nodeId) {
+        process.stderr.write("ERROR: node_id required (use --node NAME or --node-id ID)\n");
+        return 1;
+    }
+    if (!token) {
+        process.stderr.write("ERROR: no node_token — run `iicp-node serve` once (it caches the token), or pass --token / $IICP_NODE_TOKEN\n");
+        return 1;
+    }
+    const url = `${directoryUrl.replace(/\/+$/, "")}/v1/credits/summary`;
+    let resp;
+    try {
+        resp = await fetch(url, {
+            headers: { Authorization: `Bearer ${token}`, "X-Node-Id": nodeId },
+            signal: AbortSignal.timeout(15000),
+        });
+    }
+    catch (e) {
+        process.stderr.write(`ERROR: request failed: ${e instanceof Error ? e.message : String(e)}\n`);
+        return 1;
+    }
+    let body;
+    try {
+        body = (await resp.json());
+    }
+    catch {
+        process.stderr.write(`ERROR: bad response (HTTP ${resp.status})\n`);
+        return 1;
+    }
+    if (!resp.ok) {
+        const err = body["error"];
+        process.stderr.write(`ERROR: HTTP ${resp.status}: ${err?.message ?? "request rejected"}\n`);
+        return 1;
+    }
+    if (values["json"]) {
+        process.stdout.write(JSON.stringify(body, null, 2) + "\n");
+        return 0;
+    }
+    const earned = Number(body["total_earned"] ?? 0);
+    const spent = Number(body["total_spent"] ?? 0);
+    const balance = Number(body["balance"] ?? 0);
+    const tx = Number(body["tx_count"] ?? 0);
+    const reconciles = Boolean(body["reconciles"]);
+    const tpc = Number(body["tokens_per_credit"] ?? 1000);
+    const pad = (n) => n.toFixed(3).padStart(12);
+    const check = reconciles ? "✓ reconciles" : "✗ DOES NOT RECONCILE";
+    process.stdout.write(`IICP credits — ${nodeName ?? nodeId}\n`);
+    process.stdout.write(`  Earned (income) ${pad(earned)}\n`);
+    process.stdout.write(`  Spent           ${pad(spent)}\n`);
+    process.stdout.write("  ─────────────────────────────\n");
+    process.stdout.write(`  Balance         ${pad(balance)}   ${check}   (≈ ${Math.trunc(balance * tpc)} tokens)\n`);
+    process.stdout.write(`  ${tx} transactions · \`iicp-node credits --json\` for raw\n`);
+    if (!reconciles) {
+        process.stderr.write("[iicp-node] WARNING: balance != earned − spent — the ledger does not reconcile; do not trust these figures.\n");
+    }
+    if (values["verify"]) {
+        process.stdout.write("  ── cryptographic verification (signed CREDIT_AWARD log) ──\n");
+        let v;
+        try {
+            v = await verifyCreditAwards(directoryUrl, nodeId);
+        }
+        catch (e) {
+            process.stderr.write(`[iicp-node] --verify failed: ${e instanceof Error ? e.message : String(e)}\n`);
+            return 1;
+        }
+        if (v.failed > 0) {
+            process.stderr.write(`[iicp-node] ✗ ${v.failed} award event(s) FAILED Ed25519 verification — ` +
+                "tampered or inconsistent event log. Do NOT trust these figures.\n");
+            return 1;
+        }
+        process.stdout.write(`  ✓ ${v.verified} award(s) cryptographically verified · ${v.sum.toFixed(3)} credits ` +
+            "(Ed25519, signed by the directory)\n");
+        const freeTier = earned - v.sum;
+        if (freeTier > 0.0001) {
+            process.stdout.write(`  · ${freeTier.toFixed(3)} credits are free-tier allocation ` +
+                "(directory-granted, not signed task awards)\n");
+        }
+    }
+    return 0;
+}
+/**
+ * Resolve a passphrase: $IICP_OPERATOR_PASSPHRASE if set (headless/CI), else an interactive
+ * readline prompt (this command is operator-run, so a prompt is fine here — only `serve` must
+ * stay non-interactive). For `confirm`, the prompt is asked twice and must match.
+ */
+async function operatorPassphrase(prompt, confirm) {
+    const env = process.env["IICP_OPERATOR_PASSPHRASE"];
+    if (env)
+        return env;
+    const { createInterface } = await import("node:readline/promises");
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const pw = (await rl.question(prompt)).trim();
+        if (confirm && pw !== (await rl.question("Confirm passphrase: ")).trim()) {
+            process.stderr.write("ERROR: passphrases do not match.\n");
+            return null;
+        }
+        return pw || null;
+    }
+    finally {
+        rl.close();
+    }
+}
+/** `iicp-node operator encrypt` (#460) — seal the operator secret at rest under a passphrase. */
+async function runOperatorEncrypt() {
+    const op = (0, identity_js_1.loadOperator)();
+    if (!op) {
+        process.stderr.write("ERROR: no operator identity — run `iicp-node init` first.\n");
+        return 1;
+    }
+    if ((0, identity_js_1.operatorIsEncrypted)(op)) {
+        process.stdout.write("Operator secret is already encrypted at rest.\n");
+        return 0;
+    }
+    if (!(0, identity_js_1.operatorIsKeyBacked)(op)) {
+        process.stderr.write("ERROR: legacy keyless operator identity has nothing to encrypt (#464).\n");
+        return 1;
+    }
+    const pw = await operatorPassphrase("New operator passphrase: ", true);
+    if (!pw) {
+        process.stderr.write("ERROR: a non-empty passphrase is required.\n");
+        return 1;
+    }
+    (0, identity_js_1.saveOperator)((0, identity_js_1.operatorEncryptAtRest)(op, pw));
+    process.stdout.write("Operator secret encrypted at rest (AES-256-GCM / PBKDF2). Set $IICP_OPERATOR_PASSPHRASE " +
+        "to unlock it headlessly during `serve`.\n");
+    return 0;
+}
+/** `iicp-node operator decrypt` (#460) — restore the plaintext secret at rest. */
+async function runOperatorDecrypt() {
+    const op = (0, identity_js_1.loadOperator)();
+    if (!op) {
+        process.stderr.write("ERROR: no operator identity — run `iicp-node init` first.\n");
+        return 1;
+    }
+    if (!(0, identity_js_1.operatorIsEncrypted)(op)) {
+        process.stdout.write("Operator secret is already stored in plaintext.\n");
+        return 0;
+    }
+    const pw = await operatorPassphrase("Operator passphrase: ", false);
+    if (!pw) {
+        process.stderr.write("ERROR: a passphrase is required to decrypt.\n");
+        return 1;
+    }
+    try {
+        (0, identity_js_1.saveOperator)((0, identity_js_1.operatorDecryptAtRest)(op, pw));
+    }
+    catch (e) {
+        process.stderr.write(`ERROR: ${e instanceof Error ? e.message : String(e)}\n`);
+        return 1;
+    }
+    process.stdout.write("Operator secret decrypted (now stored in plaintext at rest).\n");
+    return 0;
+}
+/**
+ * `iicp-node operator rename <name>` (#460) — change the public, mutable display_name over
+ * the immutable operator_id. The operator signs the canonical rename bytes with their own
+ * key, so the directory authenticates the change by signature alone (no node token); one
+ * signed call updates the single operator record, reflected on every node + the leaderboard.
+ * Updates the local operator.json on success. Never sends the secret/contact.
+ */
+async function runOperator(argv) {
+    const sub = argv[0];
+    if (sub === "encrypt")
+        return runOperatorEncrypt();
+    if (sub === "decrypt")
+        return runOperatorDecrypt();
+    if (sub !== "rename") {
+        process.stderr.write(`unknown operator subcommand: ${sub ?? "(none)"}\n`);
+        return 2;
+    }
+    const { values, positionals } = (0, node_util_1.parseArgs)({
+        args: argv.slice(1),
+        options: { "directory-url": { type: "string" } },
+        allowPositionals: true,
+    });
+    const name = positionals[0];
+    // eslint-disable-next-line no-control-regex
+    if (!name || name.length > 64 || /[\u0000-\u001f\u007f]/.test(name)) {
+        process.stderr.write("ERROR: display name must be 1-64 chars with no control characters.\n");
+        return 1;
+    }
+    const op = (0, identity_js_1.loadOperator)();
+    if (!op) {
+        process.stderr.write("ERROR: no operator identity — run `iicp-node init` first.\n");
+        return 1;
+    }
+    if (!(0, identity_js_1.operatorIsKeyBacked)(op)) {
+        process.stderr.write("ERROR: legacy keyless operator identity (operator_id is a UUID, not a key) — " +
+            "cannot sign a rename. Regenerate with a key-backed identity (#464).\n");
+        return 1;
+    }
+    const directoryUrl = values["directory-url"] ??
+        process.env["IICP_DIRECTORY_URL"] ??
+        "https://iicp.network/api";
+    const ts = Math.floor(Date.now() / 1000);
+    const sig = (0, delegation_js_1.signRename)((0, identity_js_1.operatorSigningKey)(op), name, op.operator_id, ts);
+    const url = `${directoryUrl.replace(/\/+$/, "")}/v1/operator/rename`;
+    let resp;
+    try {
+        resp = await fetch(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ operator_pub: op.operator_id, display_name: name, ts, sig }),
+            signal: AbortSignal.timeout(15000),
+        });
+    }
+    catch (e) {
+        process.stderr.write(`ERROR: request failed: ${e instanceof Error ? e.message : String(e)}\n`);
+        return 1;
+    }
+    let body;
+    try {
+        body = (await resp.json());
+    }
+    catch {
+        body = {};
+    }
+    if (!resp.ok) {
+        const err = body["error"];
+        process.stderr.write(`ERROR: HTTP ${resp.status}: ${err?.message ?? "request rejected"}\n`);
+        return 1;
+    }
+    // Persist the new name locally so the next `serve` re-asserts it at register.
+    op.display_name = body["display_name"] ?? name;
+    (0, identity_js_1.saveOperator)(op);
+    process.stdout.write(`Renamed operator display_name to ${JSON.stringify(op.display_name)}.\n`);
+    return 0;
+}
+// ── proxy (ADR-050) — local compat gateway; consumer, loopback, no registration ──
+async function runProxyCmd(argv) {
+    const { values } = (0, node_util_1.parseArgs)({
+        args: argv,
+        allowPositionals: false,
+        options: {
+            port: { type: "string" },
+            host: { type: "string" },
+            "directory-url": { type: "string" },
+            region: { type: "string" },
+            token: { type: "string" },
+        },
+    });
+    const port = values.port !== undefined ? parseInt(values.port, 10) : envInt("IICP_PROXY_PORT", 9483);
+    const host = values.host ?? envOr("IICP_PROXY_HOST", "127.0.0.1");
+    return (0, index_js_1.runProxy)({
+        host,
+        port,
+        directoryUrl: values["directory-url"] ?? envOr("IICP_DIRECTORY_URL", "https://iicp.network/api"),
+        region: values.region ?? envOr("IICP_PROXY_PREFERRED_REGION"),
+        token: values.token ?? envOr("IICP_NODE_TOKEN"),
+    });
+}
 async function main(argv = process.argv.slice(2)) {
     if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
         printHelp();
@@ -803,6 +1351,12 @@ async function main(argv = process.argv.slice(2)) {
         return runList();
     if (cmd === "query")
         return runQuery(argv.slice(1));
+    if (cmd === "credits")
+        return runCredits(argv.slice(1));
+    if (cmd === "operator")
+        return runOperator(argv.slice(1));
+    if (cmd === "proxy")
+        return runProxyCmd(argv.slice(1));
     if (cmd !== "serve") {
         process.stderr.write(`unknown command: ${cmd}\n`);
         printHelp();
@@ -830,6 +1384,7 @@ async function main(argv = process.argv.slice(2)) {
             "external-ip-probe-url": { type: "string" },
             "relay-worker-endpoint": { type: "string" },
             "log-dir": { type: "string" },
+            "with-proxy": { type: "boolean" },
             help: { type: "boolean", short: "h" },
         },
         allowPositionals: false,
@@ -870,6 +1425,7 @@ async function main(argv = process.argv.slice(2)) {
             ?? "https://api.ipify.org",
         relayWorkerEndpoint: values["relay-worker-endpoint"] ?? envOr("IICP_RELAY_WORKER_ENDPOINT") ?? "",
         logDir: values["log-dir"] ?? envOr("IICP_LOG_DIR"),
+        withProxy: Boolean(values["with-proxy"]) || envBool("IICP_WITH_PROXY"),
     };
     return runServe(opts);
 }