@clanker-chain/clanker-cli 2026.9.8 → 2026.9.12-1

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/resolve.mjs

@@ -78,6 +78,10 @@ export function keyPointerFromSource(opts) {
   return { type: "env", value: "OPERATOR_PRIVATE_KEY" };
 }
 
+/** Honest error when mint/pair/rotate/transfer have no owner signer. */
+export const OWNER_SIGNER_REQUIRED =
+  "Owner actions need a signing key (--key-file / OPERATOR_PRIVATE_KEY) or the browser door that created this address. A read-only profile can still run whoami, bots, fund, and doctor.";
+
 /**
  * Resolve the operator signing key with Anvil guard.
  *
@@ -133,11 +137,7 @@ export function resolveOperatorKey(argv = [], opts = {}) {
       key = normalizePrivateKey(ANVIL_DEFAULT_PRIVATE_KEY);
       source = "anvil-default (local RPC)";
     } else {
-      throw new Error(
-        "Operator private key required for non-local RPC. Set OPERATOR_PRIVATE_KEY, " +
-          "pass --key / --key-file, or configure ~/.clanker/operator.json key pointer. " +
-          "Anvil account #0 is not used on public networks.",
-      );
+      throw new Error(OWNER_SIGNER_REQUIRED);
     }
   }
 
@@ -216,7 +216,11 @@ export function resolveReadIdentity(argv = [], opts = {}) {
     };
   } catch (err) {
     const msg = err?.message ?? String(err);
-    if (!/private key required|Anvil account #0|Key file not found|Profile keyFile/i.test(msg)) {
+    if (
+      !/private key required|Owner actions need a signing key|Anvil account #0|Key file not found|Profile keyFile/i.test(
+        msg,
+      )
+    ) {
       throw err;
     }
   }