@clanker-chain/clanker-cli 2026.9.8 → 2026.9.12

package/lib/pair.mjs

@@ -0,0 +1,252 @@
+/**
+ * Operator pairing client (Policy layer — docs/trust-model.md).
+ * Signs with the operator owner key; never the bot key.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { privateKeyToAccount } from "viem/accounts";
+import { loadOperator } from "./profile.mjs";
+import { openclawConfigPath } from "./openclaw-wire.mjs";
+import { resolveOperatorKey } from "./resolve.mjs";
+
+/**
+ * @param {string} baseUrl
+ * @param {{ operatorId: string, action: 'add'|'remove'|'list', peerLabel?: string }} opts
+ */
+export async function fetchPairNonce(baseUrl, opts) {
+  const url = new URL("/pair-nonce", baseUrl.replace(/\/$/, ""));
+  url.searchParams.set("operator_id", opts.operatorId);
+  url.searchParams.set("action", opts.action);
+  if (opts.peerLabel) url.searchParams.set("peer_label", opts.peerLabel);
+  const res = await fetch(url.toString());
+  const text = await res.text();
+  let body;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    throw new Error(`pair-nonce: unexpected response: ${text}`);
+  }
+  if (!res.ok || !body.nonce || !body.message) {
+    throw new Error(body.error || `pair-nonce failed: HTTP ${res.status}`);
+  }
+  return /** @type {{ nonce: string, message: string, expires_at?: string }} */ (body);
+}
+
+/**
+ * @param {string} baseUrl
+ * @param {{
+ *   operatorId: string,
+ *   peerLabel: string,
+ *   action: 'add'|'remove',
+ *   nonce: string,
+ *   signature: `0x${string}`,
+ * }} opts
+ */
+export async function postPair(baseUrl, opts) {
+  const res = await fetch(new URL("/pair", baseUrl.replace(/\/$/, "")).toString(), {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({
+      operator_id: opts.operatorId,
+      peer_label: opts.peerLabel,
+      action: opts.action,
+      nonce: opts.nonce,
+      signature: opts.signature,
+    }),
+  });
+  const text = await res.text();
+  let body;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    throw new Error(`pair: unexpected response: ${text}`);
+  }
+  if (!res.ok) {
+    throw new Error(body.error || `pair failed: HTTP ${res.status}`);
+  }
+  return body;
+}
+
+/**
+ * @param {string} baseUrl
+ * @param {{ operatorId: string, nonce: string, signature: `0x${string}` }} opts
+ */
+export async function getPairList(baseUrl, opts) {
+  const url = new URL("/pair", baseUrl.replace(/\/$/, ""));
+  url.searchParams.set("operator_id", opts.operatorId);
+  url.searchParams.set("nonce", opts.nonce);
+  url.searchParams.set("signature", opts.signature);
+  const res = await fetch(url.toString());
+  const text = await res.text();
+  let body;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    throw new Error(`pair list: unexpected response: ${text}`);
+  }
+  if (!res.ok) {
+    throw new Error(body.error || `pair list failed: HTTP ${res.status}`);
+  }
+  return body;
+}
+
+/**
+ * Merge allowOperators + dmPolicy into ~/.openclaw/openclaw.json channels.mqtt.
+ * @param {{ peerLabel: string, action: 'add'|'remove', openclawHome?: string }} opts
+ */
+export function syncAllowOperators(opts) {
+  const openclawHome = opts.openclawHome ?? join(homedir(), ".openclaw");
+  const cfgPath = openclawConfigPath(openclawHome);
+  if (!existsSync(cfgPath)) {
+    return { synced: false, path: cfgPath, reason: "missing_openclaw_json" };
+  }
+  const cfg = JSON.parse(readFileSync(cfgPath, "utf8"));
+  const channels = { ...(cfg.channels ?? {}) };
+  const mqtt = { ...(channels.mqtt && typeof channels.mqtt === "object" ? channels.mqtt : {}) };
+  const prev = Array.isArray(mqtt.allowOperators)
+    ? mqtt.allowOperators.filter((x) => typeof x === "string")
+    : [];
+  let next;
+  if (opts.action === "add") {
+    next = prev.includes(opts.peerLabel) ? prev : [...prev, opts.peerLabel];
+  } else {
+    next = prev.filter((x) => x !== opts.peerLabel);
+  }
+  mqtt.allowOperators = next;
+  if (!mqtt.dmPolicy) mqtt.dmPolicy = "pairing";
+  channels.mqtt = mqtt;
+  cfg.channels = channels;
+  mkdirSync(openclawHome, { recursive: true });
+  writeFileSync(cfgPath, `${JSON.stringify(cfg, null, 2)}\n`, "utf8");
+  return { synced: true, path: cfgPath, allowOperators: next };
+}
+
+/**
+ * Resolve mqtt-auth base URL from network / env / flag.
+ * @param {string[]} argv
+ * @param {{ mqttAuthServiceUrl?: string|null }} network
+ */
+export function resolvePairAuthUrl(argv, network) {
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === "--auth-url" && argv[i + 1]) return argv[i + 1];
+  }
+  if (process.env.MQTT_AUTH_SERVICE_URL) return process.env.MQTT_AUTH_SERVICE_URL;
+  if (network.mqttAuthServiceUrl) return network.mqttAuthServiceUrl;
+  throw new Error(
+    "mqttAuthServiceUrl required for pairing. Set profile via clanker setup, " +
+      "pass --auth-url, or set MQTT_AUTH_SERVICE_URL.",
+  );
+}
+
+/**
+ * Optional OpenClaw home for allowOperators sync (directory containing openclaw.json).
+ * @param {string[]} argv
+ * @returns {string|undefined}
+ */
+export function resolveOpenclawHome(argv) {
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === "--openclaw-home" && argv[i + 1]) return argv[i + 1];
+  }
+  if (process.env.OPENCLAW_HOME) return process.env.OPENCLAW_HOME;
+  return undefined;
+}
+
+/**
+ * @param {string[]} argv
+ * @param {'add'|'remove'|'list'|'status'} action
+ * @param {string|null} peerLabel
+ */
+export async function runPairAction(argv, action, peerLabel) {
+  const resolved = resolveOperatorKey(argv, { requireRegistry: true });
+  const operator =
+    loadOperator(resolved.network.home) ??
+    (resolved.network.operatorLabel
+      ? { label: resolved.network.operatorLabel }
+      : null);
+  const operatorId =
+    argv.includes("--operator") && argv[argv.indexOf("--operator") + 1]
+      ? argv[argv.indexOf("--operator") + 1]
+      : operator?.label;
+  if (!operatorId) {
+    throw new Error(
+      "Operator label required. Run clanker setup / write operator.json, or pass --operator org.you.",
+    );
+  }
+
+  const authUrl = resolvePairAuthUrl(argv, resolved.network);
+  const account = privateKeyToAccount(resolved.key);
+
+  if (action === "list" || action === "status") {
+    const { nonce, message } = await fetchPairNonce(authUrl, {
+      operatorId,
+      action: "list",
+    });
+    const signature = await account.signMessage({ message });
+    const listed = await getPairList(authUrl, {
+      operatorId,
+      nonce,
+      signature,
+    });
+    if (action === "status") {
+      if (!peerLabel) throw new Error("Usage: clanker pair status <operator-label>");
+      // Resolve peer by scanning allows — mutual flag is per peer_operator_id;
+      // we match by requesting add-style peer label via a second pair-nonce is heavy.
+      // Instead: check if any allow entry is mutual when peer label hashes match… we
+      // only have peer_operator_id hex. Re-fetch is unnecessary: call add-path status
+      // by computing whether peer is in allow list via a dedicated pair status using
+      // the peer label through POST-less approach — GET list doesn't include labels.
+      // Best effort: show mutual if we can add then remove? No.
+      // Call /pair-nonce + post with action that doesn't mutate? Use list + ask user.
+      // Simpler: after list, for status we POST nothing — check if peer's keccak is in list.
+      // We need peer id: keccak of peerLabel.
+      const { keccak256, toBytes } = await import("viem");
+      const peerId = keccak256(toBytes(peerLabel)).toLowerCase();
+      const hit = (listed.allows ?? []).find(
+        (a) => String(a.peer_operator_id).toLowerCase() === peerId,
+      );
+      return {
+        action: "status",
+        operatorId,
+        peerLabel,
+        allowed: Boolean(hit),
+        mutual: hit?.mutual === true,
+        authUrl,
+        listed,
+      };
+    }
+    return { action: "list", operatorId, authUrl, listed };
+  }
+
+  if (!peerLabel) {
+    throw new Error(`Usage: clanker pair ${action} <operator-label>`);
+  }
+
+  const { nonce, message } = await fetchPairNonce(authUrl, {
+    operatorId,
+    action,
+    peerLabel,
+  });
+  const signature = await account.signMessage({ message });
+  const result = await postPair(authUrl, {
+    operatorId,
+    peerLabel,
+    action,
+    nonce,
+    signature,
+  });
+  const sync = syncAllowOperators({
+    peerLabel,
+    action,
+    openclawHome: resolveOpenclawHome(argv),
+  });
+  return {
+    action,
+    operatorId,
+    peerLabel,
+    authUrl,
+    result,
+    openclawSync: sync,
+  };
+}

package/lib/setup.mjs

@@ -33,6 +33,10 @@ import {
   exportFoundryKey,
   resolveFoundryAddress,
 } from "./foundry.mjs";
+import {
+  consumerFundHints,
+  generateOperatorKeyFile,
+} from "./operator-key.mjs";
 import { c, nextHint } from "./ui.mjs";
 import { join } from "node:path";
 
@@ -52,6 +56,7 @@ export function parseSetupFlags(argv) {
   let skipChainCheck = false;
   let foundryAccount = null;
   let exportKey = false;
+  let generateKey = false;
 
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i];
@@ -63,6 +68,7 @@ export function parseSetupFlags(argv) {
     else if (a === "--from-block" && argv[i + 1]) fromBlock = BigInt(argv[++i]);
     else if (a === "--foundry-account" && argv[i + 1]) foundryAccount = argv[++i];
     else if (a === "--export-key") exportKey = true;
+    else if (a === "--generate-key") generateKey = true;
     else if (a === "--force") force = true;
     else if (a === "--yes" || a === "-y") yes = true;
     else if (a === "--skip-key") skipKey = true;
@@ -82,6 +88,7 @@ export function parseSetupFlags(argv) {
     skipChainCheck,
     foundryAccount,
     exportKey,
+    generateKey,
   };
 }
 
@@ -203,7 +210,7 @@ export async function runSetupNonInteractive(argv, opts = {}) {
   if (!flags.preset || !PRESETS[flags.preset]) {
     throw new Error(
       "Non-interactive setup requires --preset sepolia|local (stdin is not a TTY). " +
-        "Also pass --operator <label> and --address 0x…",
+        "Also pass --operator <label> and --generate-key (or --address / --key-file)",
     );
   }
   if (!flags.operator) {
@@ -218,6 +225,23 @@ export async function runSetupNonInteractive(argv, opts = {}) {
     inheritStdio: false,
   };
 
+  if (flags.generateKey) {
+    if (flags.skipKey) {
+      throw new Error("Cannot combine --generate-key with --skip-key");
+    }
+    const dest = keyFile || defaultOperatorKeyPath(home);
+    const created = generateOperatorKeyFile(dest, {
+      force: flags.force,
+    });
+    keyFile = created.path;
+    if (address && getAddress(address) !== getAddress(created.address)) {
+      throw new Error(
+        `Generated key address ${created.address} does not match --address ${getAddress(address)}`,
+      );
+    }
+    address = created.address;
+  }
+
   if (flags.foundryAccount) {
     if (!address) {
       address = resolveFoundryAddress(flags.foundryAccount, castOpts);
@@ -238,7 +262,7 @@ export async function runSetupNonInteractive(argv, opts = {}) {
   if (!address && env.OPERATOR_PRIVATE_KEY) address = addressFromEnv(env);
   if (!address) {
     throw new Error(
-      "Non-interactive setup requires --address 0x…, --key-file, OPERATOR_PRIVATE_KEY, or --foundry-account",
+      "Non-interactive setup requires --generate-key, --address 0x…, --key-file, OPERATOR_PRIVATE_KEY, or --foundry-account",
     );
   }
 
@@ -305,9 +329,13 @@ export async function runSetupInteractive(argv, opts = {}) {
   });
 
   clack.intro(c.bold("clanker setup"));
-  clack.log.step("Creates ~/.clanker/config.json (network) and operator.json (identity).");
+  clack.log.step(
+    "Sets up your operator identity (org account) and network for OpenClaw bots.",
+  );
   clack.log.message(
-    c.dim("whoami works from owner without a key; mint/revoke need a key pointer later."),
+    c.dim(
+      "New here? Create a key file — no wallet app or Foundry required. Mint needs a little test ETH later.",
+    ),
   );
   clack.log.message(c.dim(`Profile: ${home}`));
   console.log("");
@@ -366,6 +394,28 @@ export async function runSetupInteractive(argv, opts = {}) {
 
   let address = flags.address ?? null;
   let foundryAccountUsed = null;
+  let generatedKeyFile = null;
+  if (!address && flags.generateKey) {
+    const dest = flags.keyFile || defaultOperatorKeyPath(home);
+    let forceGen = flags.force;
+    if (existsSync(dest) && !forceGen) {
+      forceGen = cancelIf(
+        await clack.confirm({
+          message: `Overwrite existing ${dest}?`,
+          initialValue: false,
+        }),
+      );
+      if (!forceGen) {
+        clack.cancel("Aborted.");
+        process.exit(0);
+      }
+    }
+    const created = generateOperatorKeyFile(dest, { force: true });
+    generatedKeyFile = created.path;
+    address = created.address;
+    clack.log.success(`Created operator key at ${created.path}`);
+    clack.log.info(`Your operator address: ${created.address}`);
+  }
   if (!address && flags.keyFile) {
     address = addressFromKeyFile(flags.keyFile);
     clack.log.info(`Address from --key-file: ${address}`);
@@ -388,23 +438,95 @@ export async function runSetupInteractive(argv, opts = {}) {
     );
     if (useOp) address = hints.operator.owner;
   }
-  if (!address && hints.foundryAccounts.length) {
+  if (!address) {
     const options = [
-      ...hints.foundryAccounts.map((n) => ({
-        value: n,
-        label: n,
-        hint: "resolve via cast wallet address",
-      })),
-      { value: "__paste__", label: "Paste an address…", hint: "0x…" },
+      {
+        value: "__generate__",
+        label: "Create a new operator key for me",
+        hint: "writes ~/.clanker/op.key (recommended)",
+      },
+      {
+        value: "__keyfile__",
+        label: "Use an existing key file…",
+        hint: "path to a 0x private key file",
+      },
     ];
+    if (hints.foundryAccounts.length) {
+      for (const n of hints.foundryAccounts) {
+        options.push({
+          value: n,
+          label: `Foundry: ${n}`,
+          hint: "advanced — cast wallet",
+        });
+      }
+    } else {
+      options.push({
+        value: "__foundry_missing__",
+        label: "Foundry account…",
+        hint: "advanced — install Foundry first",
+      });
+    }
+    options.push({
+      value: "__paste__",
+      label: "Paste an address…",
+      hint: "read-only unless you add a key later",
+    });
+
     const pick = cancelIf(
       await clack.select({
-        message: "Operator owner source",
+        message: "How do you want to set your operator identity?",
         options,
-        initialValue: hints.foundryAccounts[0],
+        initialValue: "__generate__",
       }),
     );
-    if (pick === "__paste__") {
+
+    if (pick === "__generate__") {
+      const dest = defaultOperatorKeyPath(home);
+      let forceGen = flags.force;
+      if (existsSync(dest) && !forceGen) {
+        forceGen = cancelIf(
+          await clack.confirm({
+            message: `Overwrite existing ${dest}?`,
+            initialValue: false,
+          }),
+        );
+        if (!forceGen) {
+          clack.cancel("Aborted.");
+          process.exit(0);
+        }
+      }
+      const created = generateOperatorKeyFile(dest, { force: true });
+      generatedKeyFile = created.path;
+      address = created.address;
+      clack.log.success(`Created operator key at ${created.path}`);
+      clack.log.info(`Your operator address: ${created.address}`);
+    } else if (pick === "__keyfile__") {
+      const path = cancelIf(
+        await clack.text({
+          message: "Path to operator key file",
+          placeholder: join(home, "op.key"),
+          validate: (v) =>
+            v && String(v).trim() && existsSync(String(v).trim())
+              ? undefined
+              : "File not found",
+        }),
+      );
+      generatedKeyFile = String(path).trim();
+      address = addressFromKeyFile(generatedKeyFile);
+      clack.log.info(`Address from key file: ${address}`);
+    } else if (pick === "__foundry_missing__") {
+      clack.log.warn(
+        "Foundry (cast) is not available. Install https://book.getfoundry.sh/ or choose Create a new operator key.",
+      );
+      address = cancelIf(
+        await clack.text({
+          message: "Operator owner address",
+          placeholder: "0x…",
+          validate: (v) =>
+            /^0x[0-9a-fA-F]{40}$/.test(v || "") ? undefined : "Need 0x + 40 hex",
+        }),
+      );
+    } else if (pick === "__paste__") {
       address = cancelIf(
         await clack.text({
           message: "Operator owner address",
@@ -436,16 +558,6 @@ export async function runSetupInteractive(argv, opts = {}) {
       }
     }
   }
-  if (!address) {
-    address = cancelIf(
-      await clack.text({
-        message: "Operator owner address",
-        placeholder: "0x…",
-        validate: (v) =>
-          /^0x[0-9a-fA-F]{40}$/.test(v || "") ? undefined : "Need 0x + 40 hex",
-      }),
-    );
-  }
   address = getAddress(address);
 
   let label = flags.operator || hints.operator?.label || null;
@@ -483,7 +595,7 @@ export async function runSetupInteractive(argv, opts = {}) {
     throw err;
   }
 
-  let keyFile = flags.keyFile;
+  let keyFile = flags.keyFile || generatedKeyFile;
   let keyEnv = flags.keyEnv;
   let skipKey = flags.skipKey;
   if (!skipKey && !keyFile && !keyEnv) {
@@ -579,7 +691,16 @@ export async function runSetupInteractive(argv, opts = {}) {
   if (!key) {
     nextHint([
       "clanker whoami",
-      "clanker setup --key-file ~/.clanker/op.key --force   # when you need mint",
+      "clanker setup — choose Create a new operator key when you need mint",
+    ]);
+  } else if (preset === "sepolia" && generatedKeyFile) {
+    nextHint(consumerFundHints({ address, label }));
+  } else if (preset === "sepolia") {
+    nextHint([
+      "clanker fund",
+      "clanker doctor",
+      "clanker whoami",
+      `clanker bot mint <label>`,
     ]);
   } else {
     nextHint(["clanker whoami", `clanker bot mint <label>`]);
@@ -593,23 +714,20 @@ export async function runSetupInteractive(argv, opts = {}) {
 export async function runSetup(argv, opts = {}) {
   const flags = parseSetupFlags(argv);
   const isTTY = opts.isTTY ?? Boolean(input.isTTY);
+  const hasIdentitySource = Boolean(
+    flags.address ||
+      flags.keyFile ||
+      flags.generateKey ||
+      flags.foundryAccount ||
+      opts.env?.OPERATOR_PRIVATE_KEY ||
+      process.env.OPERATOR_PRIVATE_KEY,
+  );
 
-  if (
-    !isTTY ||
-    (flags.yes && flags.preset && flags.operator && (flags.address || flags.keyFile))
-  ) {
+  if (!isTTY || (flags.yes && flags.preset && flags.operator && hasIdentitySource)) {
     if (!isTTY && !(flags.preset && flags.operator)) {
       return runSetupNonInteractive(argv, opts);
     }
-    if (
-      flags.yes &&
-      flags.preset &&
-      flags.operator &&
-      (flags.address ||
-        flags.keyFile ||
-        opts.env?.OPERATOR_PRIVATE_KEY ||
-        process.env.OPERATOR_PRIVATE_KEY)
-    ) {
+    if (flags.yes && flags.preset && flags.operator && hasIdentitySource) {
       return runSetupNonInteractive(argv, opts);
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clanker-chain/clanker-cli",
-  "version": "2026.9.8",
+  "version": "2026.9.12",
   "description": "CLI for wiring clanker-chain identity and MQTT into OpenClaw and other agentic stacks.",
   "type": "module",
   "bin": {
@@ -25,6 +25,9 @@
   "dependencies": {
     "@clack/prompts": "^1.8.0",
     "picocolors": "^1.1.1",
-    "viem": "^2.21.0"
+    "viem": "^2.56.3"
+  },
+  "overrides": {
+    "ws": "^8.21.0"
   }
 }