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

package/bin/chain-identity.mjs

@@ -3,41 +3,14 @@
  * On-chain identity commands (ClankerIdentity contract).
  */
 
-import {
-  createPublicClient,
-  createWalletClient,
-  defineChain,
-  http,
-} from "viem";
 import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
 import { clankerIdentityAbi } from "../lib/clanker-identity-abi.mjs";
 import { assertSafeBotLabel, writeBotKeyFiles } from "../lib/keys.mjs";
 import { harnessSnippet, writeOperator } from "../lib/profile.mjs";
 import { labelToId } from "../lib/identity-query.mjs";
+import { resolveOperatorSigner } from "../lib/operator-signer.mjs";
 import { resolveOperatorKey } from "../lib/resolve.mjs";
 
-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] } },
-  });
-}
-
-async function walletFromKey(rpc, key) {
-  const account = privateKeyToAccount(key);
-  const transport = http(rpc);
-  const chain = await chainFromRpc(rpc);
-  return {
-    account,
-    public: createPublicClient({ chain, transport }),
-    wallet: createWalletClient({ account, chain, transport }),
-  };
-}
-
 async function waitOk(pub, hash) {
   const receipt = await pub.waitForTransactionReceipt({ hash });
   if (receipt.status !== "success") {
@@ -48,6 +21,7 @@ async function waitOk(pub, hash) {
 
 /**
  * Shared resolve for mutating chain commands (Anvil-guarded).
+ * Prefer resolveOperatorSigner for Privy + local.
  * @param {string[]} argv
  */
 export function resolveForWrite(argv) {
@@ -55,15 +29,15 @@ export function resolveForWrite(argv) {
 }
 
 export async function chainMintOperator(label, argv, opts = {}) {
-  const { key, address, network, keyPointer } = resolveOperatorKey(argv, opts);
-  const { public: pub, wallet } = await walletFromKey(network.rpc, key);
+  const signer = await resolveOperatorSigner(argv, opts);
+  const pub = signer.publicClient;
   const operatorFee = await pub.readContract({
-    address: network.registry,
+    address: signer.network.registry,
     abi: clankerIdentityAbi,
     functionName: "operatorFee",
   });
-  const hash = await wallet.writeContract({
-    address: network.registry,
+  const hash = await signer.writeContract({
+    address: signer.network.registry,
     abi: clankerIdentityAbi,
     functionName: "registerOperator",
     args: [label],
@@ -72,23 +46,27 @@ export async function chainMintOperator(label, argv, opts = {}) {
   await waitOk(pub, hash);
 
   writeOperator(
-    { label, owner: address, key: opts.keyPointer ?? keyPointer },
-    opts.home ?? network.home,
+    {
+      label,
+      owner: signer.address,
+      key: opts.keyPointer ?? signer.keyPointer,
+    },
+    opts.home ?? signer.network.home,
   );
 
   return {
     ok: true,
     label,
     operator_id: labelToId(label),
-    owner: address,
+    owner: signer.address,
     tx: hash,
   };
 }
 
 export async function chainMintBot(botLabel, operatorLabel, argv, opts = {}) {
   assertSafeBotLabel(botLabel);
-  const { key, network } = resolveOperatorKey(argv, opts);
-  const { public: pub, wallet } = await walletFromKey(network.rpc, key);
+  const signer = await resolveOperatorSigner(argv, opts);
+  const pub = signer.publicClient;
   let botPrivateKey;
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i];
@@ -114,12 +92,12 @@ export async function chainMintBot(botLabel, operatorLabel, argv, opts = {}) {
   );
 
   const botFee = await pub.readContract({
-    address: network.registry,
+    address: signer.network.registry,
     abi: clankerIdentityAbi,
     functionName: "botFee",
   });
-  const hash = await wallet.writeContract({
-    address: network.registry,
+  const hash = await signer.writeContract({
+    address: signer.network.registry,
     abi: clankerIdentityAbi,
     functionName: "registerBot",
     args: [operatorIdBytes, botLabel, botAccount.address],
@@ -130,7 +108,7 @@ export async function chainMintBot(botLabel, operatorLabel, argv, opts = {}) {
   const channelsMqtt = harnessSnippet({
     botId: botLabel,
     operatorId: operatorLabel,
-    network,
+    network: signer.network,
   });
 
   return {
@@ -146,11 +124,11 @@ export async function chainMintBot(botLabel, operatorLabel, argv, opts = {}) {
 }
 
 export async function chainRotateBotKey(botLabel, newKey, argv, opts = {}) {
-  const { key, network } = resolveOperatorKey(argv, opts);
-  const { public: pub, wallet } = await walletFromKey(network.rpc, key);
+  const signer = await resolveOperatorSigner(argv, opts);
+  const pub = signer.publicClient;
   const botIdBytes = labelToId(botLabel);
-  const hash = await wallet.writeContract({
-    address: network.registry,
+  const hash = await signer.writeContract({
+    address: signer.network.registry,
     abi: clankerIdentityAbi,
     functionName: "rotateBotKey",
     args: [botIdBytes, newKey],
@@ -160,11 +138,11 @@ export async function chainRotateBotKey(botLabel, newKey, argv, opts = {}) {
 }
 
 export async function chainRevokeBot(botLabel, argv, opts = {}) {
-  const { key, network } = resolveOperatorKey(argv, opts);
-  const { public: pub, wallet } = await walletFromKey(network.rpc, key);
+  const signer = await resolveOperatorSigner(argv, opts);
+  const pub = signer.publicClient;
   const botIdBytes = labelToId(botLabel);
-  const hash = await wallet.writeContract({
-    address: network.registry,
+  const hash = await signer.writeContract({
+    address: signer.network.registry,
     abi: clankerIdentityAbi,
     functionName: "revokeBot",
     args: [botIdBytes],
@@ -174,11 +152,11 @@ export async function chainRevokeBot(botLabel, argv, opts = {}) {
 }
 
 export async function chainProposeOperatorTransfer(label, newOwner, argv, opts = {}) {
-  const { key, network } = resolveOperatorKey(argv, opts);
-  const { public: pub, wallet } = await walletFromKey(network.rpc, key);
+  const signer = await resolveOperatorSigner(argv, opts);
+  const pub = signer.publicClient;
   const id = labelToId(label);
-  const hash = await wallet.writeContract({
-    address: network.registry,
+  const hash = await signer.writeContract({
+    address: signer.network.registry,
     abi: clankerIdentityAbi,
     functionName: "proposeOperatorTransfer",
     args: [id, newOwner],
@@ -188,11 +166,11 @@ export async function chainProposeOperatorTransfer(label, newOwner, argv, opts =
 }
 
 export async function chainAcceptOperatorTransfer(label, argv, opts = {}) {
-  const { key, address, network, keyPointer } = resolveOperatorKey(argv, opts);
-  const { public: pub, wallet } = await walletFromKey(network.rpc, key);
+  const signer = await resolveOperatorSigner(argv, opts);
+  const pub = signer.publicClient;
   const id = labelToId(label);
-  const hash = await wallet.writeContract({
-    address: network.registry,
+  const hash = await signer.writeContract({
+    address: signer.network.registry,
     abi: clankerIdentityAbi,
     functionName: "acceptOperatorTransfer",
     args: [id],
@@ -201,12 +179,12 @@ export async function chainAcceptOperatorTransfer(label, argv, opts = {}) {
   writeOperator(
     {
       label,
-      owner: address,
-      key: opts.keyPointer ?? keyPointer,
+      owner: signer.address,
+      key: opts.keyPointer ?? signer.keyPointer,
     },
-    opts.home ?? network.home,
+    opts.home ?? signer.network.home,
   );
-  return { ok: true, label, owner: address, tx: hash };
+  return { ok: true, label, owner: signer.address, tx: hash };
 }
 
 export { labelToId };

package/bin/clanker.mjs

@@ -24,9 +24,11 @@ import {
   resolvePreferredOperator,
 } from "../lib/identity-query.mjs";
 import { resolveForRead, resolveOperatorKey, resolveReadIdentity } from "../lib/resolve.mjs";
+import { resolveOperatorSigner } from "../lib/operator-signer.mjs";
 import { runSetup } from "../lib/setup.mjs";
 import { runDoctor } from "../lib/doctor.mjs";
 import { runFund } from "../lib/fund.mjs";
+import { runLogin, runLogout } from "../lib/login.mjs";
 import {
   assessMintBudget,
   formatEthTrim,
@@ -171,6 +173,8 @@ function usage() {
 
 Usage:
   clanker setup [--preset sepolia|local] [--operator <label>] [--address 0x…] [--skip-key] [--bot-key path] [--key-file path] [--force]
+  clanker login [--no-open] [--operator <label>] [--json]
+  clanker logout [--json]
   clanker fund [--address 0x…] [--no-open] [--timeout ms] [--json]
   clanker doctor [--json]
   clanker init --preset sepolia|local [--force]
@@ -197,7 +201,7 @@ Profile:
   ~/.clanker/operator.json   label + owner + optional key pointer (never raw hex)
   ~/.clanker/keys/           bot keys (also written to ~/.openclaw/keys/)
 
-Humans: \`clanker setup\` then \`clanker fund\` / \`doctor\` / \`whoami\`.
+Humans: \`clanker login\` (email vault) or \`clanker setup --generate-key\`, then \`fund\` / \`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\`).
@@ -415,7 +419,8 @@ async function main() {
         error: err.message,
         because: "setup could not write a valid local profile",
         try: [
-          "clanker setup --preset sepolia --operator org.you --address 0x… --yes --force",
+          "clanker login",
+          "clanker setup --preset sepolia --operator org.you --yes --force",
           "clanker fund",
           "clanker doctor",
         ],
@@ -424,6 +429,36 @@ async function main() {
     return;
   }
 
+  if (cmd === "login") {
+    try {
+      const { exitCode } = await runLogin(rest);
+      process.exit(exitCode);
+    } catch (err) {
+      exitCliError({
+        error: err.message,
+        because: "login needs Privy CLI access enabled and /authorize approval",
+        try: [
+          "Open the printed URL and Approve",
+          "Privy dashboard: Enable CLI and agent access → Verification URI https://clanker-chain.com/authorize",
+          "clanker setup --generate-key   # local key door instead",
+        ],
+      });
+    }
+  }
+
+  if (cmd === "logout") {
+    try {
+      const { exitCode } = await runLogout(rest);
+      process.exit(exitCode);
+    } catch (err) {
+      exitCliError({
+        error: err.message,
+        because: "logout could not clear the Privy session",
+        try: ["clanker logout"],
+      });
+    }
+  }
+
   if (cmd === "fund") {
     try {
       const { exitCode } = await runFund(rest);
@@ -581,21 +616,21 @@ async function main() {
       let planRows;
       let preview;
       try {
-        preview = resolveOperatorKey(flags);
+        preview = await resolveOperatorSigner(flags);
         planRows = [
           ["action", "registerOperator"],
           ["label", label],
           ["owner", preview.address],
           ["rpc", preview.network.rpc],
           ["registry", preview.network.registry ?? "(none)"],
-          ["key", preview.source],
+          ["signer", preview.source],
         ];
       } catch (err) {
         exitCliError({
           error: err.message,
-          because: "operator mint needs a signing key on this network",
+          because: "operator mint needs a signer on this network",
           try: [
-            "export OPERATOR_PRIVATE_KEY=0x…",
+            "clanker login",
             "clanker operator mint " + label + " --key-file ~/.clanker/op.key --yes",
             "clanker fund",
             "clanker doctor",
@@ -736,14 +771,15 @@ async function main() {
       let preview = null;
       if (!operatorLabel) {
         try {
-          preview = resolveOperatorKey(flags);
+          preview = await resolveOperatorSigner(flags);
           const inferred = await resolveOperatorLabel(flags, preview.address, preview.network);
           operatorLabel = inferred.label;
         } catch (err) {
           exitCliError({
             error: err.message,
-            because: "bot mint needs an operator label or a resolvable signing key",
+            because: "bot mint needs an operator label or a resolvable signer",
             try: [
+              "clanker login",
               `clanker bot mint ${botLabel} <operator_label> --yes`,
               "clanker setup",
             ],
@@ -752,12 +788,13 @@ async function main() {
       }
       if (!preview) {
         try {
-          preview = resolveOperatorKey(flags);
+          preview = await resolveOperatorSigner(flags);
         } catch (err) {
           exitCliError({
             error: err.message,
-            because: "bot mint needs a signing key on this network",
+            because: "bot mint needs a signer on this network",
             try: [
+              "clanker login",
               `clanker bot mint ${botLabel} ${operatorLabel} --key-file ~/.clanker/op.key --yes`,
               "clanker fund",
             ],
@@ -770,6 +807,7 @@ async function main() {
         ["operator", operatorLabel],
         ["owner", preview.address],
         ["registry", preview.network.registry ?? "(none)"],
+        ["signer", preview.source],
       ];
       try {
         if (preview.network.registry) {

package/lib/doctor.mjs

@@ -12,6 +12,7 @@ import {
 } from "./profile.mjs";
 import { detectSetupHints, formatSetupDetectTable } from "./setup-detect.mjs";
 import { publicClientFromRpc } from "./identity-query.mjs";
+import { loadPrivySession } from "./privy-session.mjs";
 import {
   assessMintBudget,
   budgetToJson,
@@ -96,17 +97,24 @@ export async function runDoctorChecks(opts = {}) {
     });
   }
 
+  const privySession = loadPrivySession(home);
+  const hasPrivy =
+    Boolean(operator?.key?.type === "privy" && operator.key.value) ||
+    Boolean(privySession?.accessToken && privySession?.walletId);
   const hasKey =
     Boolean(operator?.key?.type === "keyFile" && operator.key.value) ||
     Boolean(operator?.key?.type === "env" && operator.key.value) ||
-    Boolean(env.OPERATOR_PRIVATE_KEY);
+    Boolean(env.OPERATOR_PRIVATE_KEY) ||
+    hasPrivy;
   checks.push({
     id: "signing",
     ok: true,
     level: hasKey ? "pass" : "warn",
-    message: hasKey
-      ? "signing key pointer available (mint/pair/rotate OK)"
-      : "read-only profile — whoami/bots/fund OK; mint/pair/rotate need a key pointer or the /join owner",
+    message: hasPrivy
+      ? "Privy session available (mint/pair/rotate via email vault)"
+      : hasKey
+        ? "signing key pointer available (mint/pair/rotate OK)"
+        : "read-only profile — whoami/bots/fund OK; mint/pair/rotate need clanker login or a key pointer",
   });
 
   checks.push({
@@ -295,20 +303,20 @@ export async function runDoctor(argv = [], opts = {}) {
   } else {
     console.log(
       c.dim(
-        "Mint/pair/rotate: need a signing key or stay on /join (non-Anvil owner on public RPC)",
+        "Mint/pair/rotate: need clanker login or a signing key (non-Anvil owner on public RPC)",
       ),
     );
   }
 
   if (!report.readyWhoami) {
-    nextHint(["clanker setup"]);
+    nextHint(["clanker setup", "clanker login"]);
   } else if (report.budget && !report.budget.funded && !report.budget.local) {
     nextHint(["clanker fund", "clanker doctor"]);
   } else if (!report.readyMint) {
     nextHint([
+      "clanker login",
       "clanker whoami",
-      "clanker bots",
-      "mint/pair/rotate need --key-file / OPERATOR_PRIVATE_KEY or stay on /join",
+      "mint/pair/rotate need login or --key-file",
     ]);
   } else {
     nextHint(["clanker whoami", "clanker bots"]);

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 };
+}