@clanker-chain/clanker-cli 2026.9.8-2 → 2026.9.10

package/bin/clanker.mjs

@@ -3,6 +3,7 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import os from "node:os";
 import process from "node:process";
 import { getAddress } from "viem";
@@ -97,8 +98,15 @@ function runScript(scriptPath, args = []) {
 }
 
 function findRepoRoot() {
-  const here = dirname(new URL(import.meta.url).pathname);
-  return dirname(dirname(here));
+  let dir = dirname(fileURLToPath(import.meta.url));
+  for (let i = 0; i < 8; i++) {
+    if (existsSync(join(dir, "chain", "foundry.toml"))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  // npm install: package root (no monorepo checkout)
+  return dirname(dirname(fileURLToPath(import.meta.url)));
 }
 
 /** chain up/deploy and check * need the monorepo; npm installs only ship bin/ + lib/. */
@@ -169,6 +177,10 @@ Usage:
   clanker bot status <label> [--json]
   clanker bot revoke <label> [--json] [--yes]
   clanker bot rotate <label> <newKeyAddress> [--json] [--yes]
+  clanker pair add <operator-label> [--yes] [--auth-url URL] [--openclaw-home DIR]
+  clanker pair remove <operator-label> [--auth-url URL] [--openclaw-home DIR]
+  clanker pair list [--auth-url URL]
+  clanker pair status <operator-label> [--auth-url URL]
   clanker init-openclaw
   clanker chain up|deploy|mint-operator|mint-bot|rotate-bot-key|revoke-bot ...
   clanker check mqtt <bot_id> <operator_id>
@@ -180,10 +192,11 @@ Profile:
   ~/.clanker/keys/           bot keys (also written to ~/.openclaw/keys/)
 
 Humans: \`clanker setup\` then \`clanker doctor\` / \`whoami\`.
+Pairing (Policy): both operators run \`clanker pair add\` before DMs deliver on the hub.
 Mutates print a plan and confirm unless --yes or --json.
 whoami is fast by default; pass --with-bots to enrich child bots (or use \`clanker bots\`).
 
-See docs/operator-cli.md.
+See docs/operator-cli.md and docs/trust-model.md.
 `);
 }
 
@@ -441,6 +454,93 @@ async function main() {
     return;
   }
 
+  if (cmd === "pair") {
+    const [sub, ...pairRest] = rest;
+    if (!sub || !["add", "remove", "list", "status"].includes(sub)) {
+      console.error("Usage: clanker pair add|remove|list|status [operator-label]");
+      process.exit(1);
+    }
+
+    let peerLabel = null;
+    for (let i = 0; i < pairRest.length; i += 1) {
+      const a = pairRest[i];
+      if (a.startsWith("--")) {
+        if (a !== "--json" && a !== "--yes" && pairRest[i + 1] && !pairRest[i + 1].startsWith("--")) {
+          i += 1; // skip flag value
+        }
+        continue;
+      }
+      peerLabel = a;
+      break;
+    }
+
+    const { runPairAction } = await import("../lib/pair.mjs");
+    try {
+      if (sub === "add") {
+        const planRows = [
+          ["action", "pair add (Policy)"],
+          ["peer", peerLabel ?? "(missing)"],
+          ["note", "One-way allow; peer must pair you for bidirectional DMs"],
+        ];
+        const ok = await confirmPlan(pairRest, planRows, `Allow operator ${peerLabel}?`);
+        if (!ok) process.exit(0);
+      }
+      const out = await runPairAction(pairRest, sub, peerLabel);
+      if (hasFlag(pairRest, "--json")) {
+        console.log(JSON.stringify(out, null, 2));
+      } else if (sub === "list") {
+        console.log(`Operator: ${out.operatorId}`);
+        console.log(`Auth: ${out.authUrl}`);
+        const allows = out.listed?.allows ?? [];
+        if (!allows.length) {
+          console.log("(no allows)");
+        } else {
+          for (const a of allows) {
+            console.log(
+              `  ${a.peer_operator_id}  ${a.mutual ? "mutual" : "pending (one-way)"}`,
+            );
+          }
+        }
+      } else if (sub === "status") {
+        console.log(`peer:    ${out.peerLabel}`);
+        console.log(`allowed: ${out.allowed}`);
+        console.log(`mutual:  ${out.mutual}`);
+        if (out.allowed && !out.mutual) {
+          console.log("Waiting for peer to run: clanker pair add <your-operator>");
+        }
+      } else {
+        console.log(
+          `${sub} ${out.peerLabel}: ${out.result?.mutual ? "mutual" : "one-way / pending"}`,
+        );
+        if (out.openclawSync?.synced) {
+          console.log(`Synced allowOperators → ${out.openclawSync.path}`);
+          console.log(
+            "Restart (or reload) the OpenClaw gateway so channels.mqtt.allowOperators is picked up.",
+          );
+        } else if (out.openclawSync?.reason === "missing_openclaw_json") {
+          console.log(
+            `Hub Policy updated, but no openclaw.json at ${out.openclawSync.path} — ` +
+              "client allowOperators was not synced. Create OpenClaw config or set allowOperators manually.",
+          );
+        }
+        if (sub === "add" && !out.result?.mutual) {
+          nextHint(`Ask ${out.peerLabel} to run: clanker pair add ${out.operatorId}`);
+        }
+      }
+    } catch (err) {
+      exitCliError({
+        error: err.message,
+        because: "pairing needs operator key + mqtt-auth /pair endpoints",
+        try: [
+          "clanker doctor",
+          "clanker pair add org.peer --auth-url http://127.0.0.1:9090 --yes",
+          "See docs/trust-model.md",
+        ],
+      });
+    }
+    return;
+  }
+
   if (cmd === "operator") {
     const [sub, ...opArgv] = rest;
     const {
@@ -935,7 +1035,7 @@ async function main() {
     nextHint([
       "clanker bot mint <label>",
       "Then channels.mqtt.botId / operatorId / privateKeyFile update automatically",
-      "See docs/operator-cli.md and docs/closed-beta-invite.md",
+      "See docs/operator-cli.md and docs/public-testnet-hub.md",
     ]);
     process.exit(0);
   }

package/lib/identity-query.mjs

@@ -13,7 +13,7 @@ import {
 } from "viem";
 import { clankerIdentityAbi } from "./clanker-identity-abi.mjs";
 
-/** Match identity-service EVM_LOG_CHUNK_BLOCKS — public RPCs reject wide ranges. */
+/** Public RPC eth_getLogs chunk size — wide ranges are often rejected. */
 export const LOG_CHUNK_BLOCKS = 2000n;
 
 export function labelToId(label) {

package/lib/openclaw-wire.mjs

@@ -8,7 +8,7 @@ import { join } from "node:path";
 import { harnessSnippet } from "./profile.mjs";
 
 /** Current published OpenClaw plugin pins for closed-beta invite. */
-export const OPENCLAW_PLUGIN_PIN = "2026.7.29";
+export const OPENCLAW_PLUGIN_PIN = "2026.9.10";
 
 /**
  * @param {string} [openclawHome]
@@ -99,7 +99,7 @@ export function hubConnectChecklist(opts) {
     `openclaw plugins install @clanker-chain/mqtt-tools@${pin}`,
     "Enable plugin ids mqtt + mqtt-tools (already set in openclaw.json if we wired it)",
     `CONNECT broker: ${opts.channelsMqtt?.brokerUrl ?? "mqtts://mqtt.clanker-chain.com:8883"}`,
-    `Ask hub operator to allow bot_id "${opts.botId}" in france dmPolicy / allowFrom`,
+    "Both operators: clanker pair add <peer-operator>  (Policy — required before DMs deliver)",
     "DM openclaw.france.prod-1 to smoke the mesh",
   ];
 }

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clanker-chain/clanker-cli",
-  "version": "2026.9.8-2",
+  "version": "2026.9.10",
   "description": "CLI for wiring clanker-chain identity and MQTT into OpenClaw and other agentic stacks.",
   "type": "module",
   "bin": {