@clanker-chain/clanker-cli 2026.9.12 → 2026.9.13

package/lib/login.mjs

@@ -0,0 +1,200 @@
+/**
+ * `clanker login` / `clanker logout` — Privy device grant for the operator vault.
+ */
+
+import { getAddress } from "viem";
+import { openUrl } from "./fund.mjs";
+import {
+  loadOperator,
+  writeOperator,
+  clankerHome,
+  loadConfig,
+} from "./profile.mjs";
+import {
+  authenticateWallets,
+  pollDeviceToken,
+  requestDeviceAuthorization,
+} from "./privy-client.mjs";
+import {
+  clearPrivySession,
+  loadPrivySession,
+  savePrivySession,
+} from "./privy-session.mjs";
+import { resolvePrivyAppId } from "./privy-constants.mjs";
+import { c, nextHint } from "./ui.mjs";
+
+/**
+ * @param {string[]} argv
+ */
+export function parseLoginFlags(argv) {
+  let noOpen = false;
+  let json = false;
+  let operator = null;
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "--no-open") noOpen = true;
+    else if (a === "--json") json = true;
+    else if (a === "--operator" && argv[i + 1]) operator = argv[++i];
+  }
+  return { noOpen, json, operator };
+}
+
+/**
+ * @param {string[]} argv
+ * @param {{
+ *   home?: string,
+ *   env?: NodeJS.ProcessEnv,
+ *   fetchImpl?: typeof fetch,
+ *   openUrlImpl?: typeof openUrl,
+ *   sleep?: (ms: number) => Promise<void>,
+ *   now?: () => number,
+ * }} [opts]
+ */
+export async function runLogin(argv = [], opts = {}) {
+  const flags = parseLoginFlags(argv);
+  const env = opts.env ?? process.env;
+  const home = opts.home ?? clankerHome(env);
+  const openUrlImpl = opts.openUrlImpl ?? openUrl;
+
+  const device = await requestDeviceAuthorization({
+    appId: resolvePrivyAppId(env),
+    fetchImpl: opts.fetchImpl,
+  });
+
+  const url =
+    device.verificationUriComplete ||
+    `${device.verificationUri}?user_code=${encodeURIComponent(device.userCode)}`;
+
+  if (!flags.json) {
+    console.log(c.bold("clanker login"));
+    console.log("");
+    console.log("Approve CLI access to your operator wallet (email vault).");
+    console.log("");
+    console.log(`Visit:  ${url}`);
+    console.log(`Code:   ${device.userCode}`);
+    console.log("");
+    console.log(c.dim("Waiting for browser approval…"));
+  }
+
+  if (!flags.noOpen) {
+    await openUrlImpl(url);
+  }
+
+  const tokens = await pollDeviceToken({
+    appId: device.appId,
+    deviceCode: device.deviceCode,
+    interval: device.interval,
+    expiresIn: device.expiresIn,
+    fetchImpl: opts.fetchImpl,
+    sleep: opts.sleep,
+    now: opts.now,
+  });
+
+  const auth = await authenticateWallets({
+    appId: device.appId,
+    accessToken: tokens.accessToken,
+    fetchImpl: opts.fetchImpl,
+  });
+
+  const session = {
+    appId: device.appId,
+    accessToken: tokens.accessToken,
+    refreshToken: tokens.refreshToken,
+    expiresAt: Date.now() + tokens.expiresIn * 1000,
+    walletId: auth.walletId,
+    address: auth.address,
+    createdAt: Date.now(),
+  };
+  const stored = savePrivySession(session, home);
+
+  const existing = loadOperator(home);
+  const label = flags.operator || existing?.label || null;
+  if (existing?.owner && getAddress(existing.owner) !== auth.address) {
+    throw new Error(
+      `Logged-in address ${auth.address} does not match operator.json owner ${existing.owner}. ` +
+        `Use a matching login, or clanker setup --force with the new owner.`,
+    );
+  }
+
+  if (label || existing) {
+    writeOperator(
+      {
+        label: label || existing.label,
+        owner: auth.address,
+        key: { type: "privy", value: auth.walletId },
+      },
+      home,
+    );
+  } else if (!loadConfig(home)) {
+    // Login alone is enough for session; setup still needed for network + label.
+  } else {
+    // Config exists but no operator yet — leave operator.json to setup / mint.
+  }
+
+  const payload = {
+    ok: true,
+    address: auth.address,
+    walletId: auth.walletId,
+    storage: stored.storage,
+    label: label || existing?.label || null,
+  };
+
+  if (flags.json) {
+    console.log(JSON.stringify(payload, null, 2));
+  } else {
+    console.log("");
+    console.log(c.green(`Logged in as ${auth.address}`));
+    console.log(c.dim(`wallet:  ${auth.walletId}`));
+    console.log(c.dim(`session: ${stored.storage}`));
+    if (!label && !existing?.label) {
+      nextHint([
+        "clanker setup --preset sepolia --operator org.you --yes   # if no profile yet",
+        "clanker fund",
+        "clanker whoami",
+        "clanker pair add <peer> --yes",
+      ]);
+    } else {
+      nextHint([
+        "clanker fund",
+        "clanker whoami",
+        "clanker pair add <peer> --yes",
+        "clanker operator mint <label> --yes   # if not minted yet",
+      ]);
+    }
+  }
+  return { exitCode: 0, ...payload, session };
+}
+
+/**
+ * @param {string[]} argv
+ * @param {{ home?: string, env?: NodeJS.ProcessEnv }} [opts]
+ */
+export async function runLogout(argv = [], opts = {}) {
+  const json = argv.includes("--json");
+  const home = opts.home ?? clankerHome(opts.env ?? process.env);
+  const had = Boolean(loadPrivySession(home));
+  clearPrivySession(home);
+  const operator = loadOperator(home);
+  if (operator?.key?.type === "privy") {
+    writeOperator(
+      {
+        label: operator.label,
+        owner: operator.owner,
+        key: null,
+      },
+      home,
+    );
+  }
+  if (json) {
+    console.log(JSON.stringify({ ok: true, cleared: had }, null, 2));
+  } else {
+    console.log(c.bold("clanker logout"));
+    console.log(had ? c.green("Cleared Privy CLI session.") : c.dim("No session stored."));
+    console.log(
+      c.dim(
+        "Revoke grants anytime in the Privy dashboard / account settings if needed.",
+      ),
+    );
+  }
+  return { exitCode: 0, cleared: had };
+}

package/lib/operator-key.mjs

@@ -10,9 +10,8 @@ import { defaultOperatorKeyPath } from "./foundry.mjs";
 
 export { defaultOperatorKeyPath };
 
-/** Coinbase Developer Platform faucet UI (Base Sepolia). */
-export const BASE_SEPOLIA_FAUCET_URL =
-  "https://portal.cdp.coinbase.com/products/faucet";
+/** Coinbase Developer Platform portal (Faucets live in-nav; deep link /products/faucet 404s). */
+export const BASE_SEPOLIA_FAUCET_URL = "https://portal.cdp.coinbase.com/";
 
 /** Backup Base Sepolia faucet (amounts not guaranteed). */
 export const ALCHEMY_BASE_SEPOLIA_FAUCET_URL =

package/lib/operator-signer.mjs

@@ -0,0 +1,284 @@
+/**
+ * Pluggable operator signer: local hex key or Privy device-grant vault.
+ */
+
+import {
+  createPublicClient,
+  createWalletClient,
+  defineChain,
+  encodeFunctionData,
+  getAddress,
+  http,
+} from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import {
+  isAnvilDefaultKey,
+  OWNER_SIGNER_REQUIRED,
+  parseKeyFlags,
+  resolveOperatorKey,
+} from "./resolve.mjs";
+import {
+  ANVIL_DEFAULT_PRIVATE_KEY,
+  isLocalRpc,
+  loadOperator,
+  resolveNetwork,
+} from "./profile.mjs";
+import { loadPrivySession } from "./privy-session.mjs";
+import { privySendTransaction, privySignMessage } from "./privy-client.mjs";
+import { existsSync, readFileSync } from "node:fs";
+import { normalizePrivateKey } from "./resolve.mjs";
+
+export { OWNER_SIGNER_REQUIRED };
+
+/**
+ * @typedef {{
+ *   address: `0x${string}`,
+ *   source: string,
+ *   keyPointer: { type: string, value: string }|null,
+ *   network: object,
+ *   kind: 'local'|'privy',
+ *   key?: `0x${string}`,
+ *   signMessage: (args: { message: string }) => Promise<`0x${string}`>,
+ *   writeContract: (args: object) => Promise<`0x${string}`>,
+ *   publicClient: import('viem').PublicClient,
+ * }} OperatorSigner
+ */
+
+async function chainFromRpc(rpc) {
+  const publicClient = createPublicClient({ transport: http(rpc) });
+  const id = await publicClient.getChainId();
+  return defineChain({
+    id,
+    name: `clanker-chain-${id}`,
+    nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
+    rpcUrls: { default: { http: [rpc] } },
+  });
+}
+
+/**
+ * @param {string} rpc
+ * @param {`0x${string}`} key
+ */
+async function localSignerFromKey(rpc, key, meta) {
+  const account = privateKeyToAccount(key);
+  const transport = http(rpc);
+  const chain = await chainFromRpc(rpc);
+  const publicClient = createPublicClient({ chain, transport });
+  const wallet = createWalletClient({ account, chain, transport });
+  return {
+    ...meta,
+    kind: "local",
+    key,
+    address: account.address,
+    publicClient,
+    signMessage: async ({ message }) => account.signMessage({ message }),
+    writeContract: async (args) => wallet.writeContract(args),
+  };
+}
+
+/**
+ * @param {string} rpc
+ * @param {{ address: string, walletId: string, home?: string, fetchImpl?: typeof fetch }} privy
+ * @param {object} meta
+ */
+async function privySignerFromSession(rpc, privy, meta) {
+  const transport = http(rpc);
+  const chain = await chainFromRpc(rpc);
+  const publicClient = createPublicClient({ chain, transport });
+  const address = getAddress(privy.address);
+
+  return {
+    ...meta,
+    kind: "privy",
+    address,
+    publicClient,
+    signMessage: async ({ message }) =>
+      privySignMessage(message, {
+        home: privy.home,
+        fetchImpl: privy.fetchImpl,
+      }),
+    writeContract: async (args) => {
+      const data = encodeFunctionData({
+        abi: args.abi,
+        functionName: args.functionName,
+        args: args.args,
+      });
+      const value =
+        args.value == null
+          ? undefined
+          : typeof args.value === "bigint"
+            ? `0x${args.value.toString(16)}`
+            : args.value;
+      const chainId = chain.id;
+      return privySendTransaction(
+        {
+          to: args.address,
+          data,
+          value,
+          chain_id: chainId,
+        },
+        { home: privy.home, fetchImpl: privy.fetchImpl },
+      );
+    },
+  };
+}
+
+/**
+ * Resolve an operator signer (local key or Privy session).
+ *
+ * Precedence for local: --key > --key-file > OPERATOR_PRIVATE_KEY > profile keyFile/env.
+ * Else if profile key.type === privy or a Privy session exists → Privy vault.
+ * Else Anvil on local RPC only.
+ *
+ * @param {string[]} argv
+ * @param {{
+ *   home?: string,
+ *   env?: NodeJS.ProcessEnv,
+ *   rpc?: string,
+ *   requireRegistry?: boolean,
+ *   fetchImpl?: typeof fetch,
+ * }} [opts]
+ * @returns {Promise<OperatorSigner>}
+ */
+export async function resolveOperatorSigner(argv = [], opts = {}) {
+  const env = opts.env ?? process.env;
+  const network = resolveNetwork(argv, { home: opts.home, env });
+  const rpc = opts.rpc ?? network.rpc;
+  const home = opts.home ?? network.home;
+  const operator = loadOperator(home);
+  const requireRegistry = opts.requireRegistry !== false;
+  const flags = parseKeyFlags(argv);
+  const local = isLocalRpc(rpc);
+
+  if (requireRegistry && (!network.registry || !/^0x[0-9a-fA-F]{40}$/.test(network.registry))) {
+    throw new Error(
+      "REGISTRY_ADDRESS or --registry is required (0x + 40 hex). " +
+        "Run `clanker init --preset sepolia` or set registry after `clanker chain deploy`.",
+    );
+  }
+
+  // Explicit local key paths first.
+  let key = null;
+  let source = null;
+  let keyFilePath = null;
+  if (flags.key) {
+    key = normalizePrivateKey(flags.key);
+    source = "--key";
+  } else if (flags.keyFile || network.keyFile) {
+    const path = flags.keyFile || network.keyFile;
+    if (!existsSync(path)) throw new Error(`Key file not found: ${path}`);
+    key = normalizePrivateKey(readFileSync(path, "utf8").split(/\r?\n/)[0]);
+    keyFilePath = path;
+    source = `--key-file ${path}`;
+  } else if (env.OPERATOR_PRIVATE_KEY) {
+    key = normalizePrivateKey(env.OPERATOR_PRIVATE_KEY);
+    source = "OPERATOR_PRIVATE_KEY";
+  } else if (operator?.key?.type === "keyFile" && operator.key.value) {
+    const path = operator.key.value;
+    if (!existsSync(path)) throw new Error(`Profile keyFile not found: ${path}`);
+    key = normalizePrivateKey(readFileSync(path, "utf8").split(/\r?\n/)[0]);
+    keyFilePath = path;
+    source = `profile keyFile ${path}`;
+  } else if (operator?.key?.type === "env" && operator.key.value && env[operator.key.value]) {
+    key = normalizePrivateKey(env[operator.key.value]);
+    source = `profile env ${operator.key.value}`;
+  }
+
+  if (key) {
+    if (!local && isAnvilDefaultKey(key)) {
+      throw new Error(
+        "Refusing Anvil account #0 key on a non-local RPC. " +
+          "Use clanker login, or a real OPERATOR_PRIVATE_KEY / --key-file.",
+      );
+    }
+    const keyPointer =
+      keyFilePath
+        ? { type: "keyFile", value: keyFilePath }
+        : source === "OPERATOR_PRIVATE_KEY" || source?.startsWith("profile env")
+          ? { type: "env", value: "OPERATOR_PRIVATE_KEY" }
+          : { type: "env", value: "OPERATOR_PRIVATE_KEY" };
+    const signer = await localSignerFromKey(rpc, key, {
+      source,
+      keyPointer,
+      network: { ...network, rpc },
+    });
+    if (
+      operator?.owner &&
+      getAddress(operator.owner) !== getAddress(signer.address)
+    ) {
+      throw new Error(
+        `Signing address ${signer.address} does not match operator.json owner ${operator.owner}`,
+      );
+    }
+    return signer;
+  }
+
+  // Privy vault.
+  const session = loadPrivySession(home);
+  const wantsPrivy =
+    operator?.key?.type === "privy" || Boolean(session?.accessToken);
+
+  if (wantsPrivy) {
+    if (!session?.accessToken || !session?.address || !session?.walletId) {
+      throw new Error(
+        "Privy session missing — run clanker login (or use --key-file / OPERATOR_PRIVATE_KEY).",
+      );
+    }
+    if (
+      operator?.key?.type === "privy" &&
+      operator.key.value &&
+      operator.key.value !== session.walletId
+    ) {
+      throw new Error(
+        `Privy wallet ${session.walletId} does not match operator.json ${operator.key.value} — run clanker login again`,
+      );
+    }
+    if (
+      operator?.owner &&
+      getAddress(operator.owner) !== getAddress(session.address)
+    ) {
+      throw new Error(
+        `Privy address ${session.address} does not match operator.json owner ${operator.owner}`,
+      );
+    }
+    return privySignerFromSession(
+      rpc,
+      {
+        address: session.address,
+        walletId: session.walletId,
+        home,
+        fetchImpl: opts.fetchImpl,
+      },
+      {
+        source: "privy session",
+        keyPointer: { type: "privy", value: session.walletId },
+        network: { ...network, rpc },
+      },
+    );
+  }
+
+  if (local) {
+    return localSignerFromKey(
+      rpc,
+      normalizePrivateKey(ANVIL_DEFAULT_PRIVATE_KEY),
+      {
+        source: "anvil-default (local RPC)",
+        keyPointer: { type: "env", value: "OPERATOR_PRIVATE_KEY" },
+        network: { ...network, rpc },
+      },
+    );
+  }
+
+  throw new Error(
+    "Owner actions need clanker login (email vault), or a signing key (--key-file / OPERATOR_PRIVATE_KEY). " +
+      "A read-only profile can still run whoami, bots, fund, and doctor.",
+  );
+}
+
+/**
+ * Back-compat: local hex only (used by forge deploy etc.).
+ * Prefer resolveOperatorSigner for pair/mint.
+ */
+export function resolveOperatorKeyLocal(argv, opts) {
+  return resolveOperatorKey(argv, opts);
+}

package/lib/pair.mjs

@@ -6,10 +6,9 @@
 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";
+import { resolveOperatorSigner } from "./operator-signer.mjs";
 
 /**
  * @param {string} baseUrl
@@ -159,11 +158,11 @@ export function resolveOpenclawHome(argv) {
  * @param {string|null} peerLabel
  */
 export async function runPairAction(argv, action, peerLabel) {
-  const resolved = resolveOperatorKey(argv, { requireRegistry: true });
+  const signer = await resolveOperatorSigner(argv, { requireRegistry: true });
   const operator =
-    loadOperator(resolved.network.home) ??
-    (resolved.network.operatorLabel
-      ? { label: resolved.network.operatorLabel }
+    loadOperator(signer.network.home) ??
+    (signer.network.operatorLabel
+      ? { label: signer.network.operatorLabel }
       : null);
   const operatorId =
     argv.includes("--operator") && argv[argv.indexOf("--operator") + 1]
@@ -175,15 +174,14 @@ export async function runPairAction(argv, action, peerLabel) {
     );
   }
 
-  const authUrl = resolvePairAuthUrl(argv, resolved.network);
-  const account = privateKeyToAccount(resolved.key);
+  const authUrl = resolvePairAuthUrl(argv, signer.network);
 
   if (action === "list" || action === "status") {
     const { nonce, message } = await fetchPairNonce(authUrl, {
       operatorId,
       action: "list",
     });
-    const signature = await account.signMessage({ message });
+    const signature = await signer.signMessage({ message });
     const listed = await getPairList(authUrl, {
       operatorId,
       nonce,
@@ -191,16 +189,6 @@ export async function runPairAction(argv, action, peerLabel) {
     });
     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(
@@ -228,7 +216,7 @@ export async function runPairAction(argv, action, peerLabel) {
     action,
     peerLabel,
   });
-  const signature = await account.signMessage({ message });
+  const signature = await signer.signMessage({ message });
   const result = await postPair(authUrl, {
     operatorId,
     peerLabel,