@clanker-chain/clanker-cli 2026.9.12 → 2026.9.13

package/lib/privy-client.mjs

@@ -0,0 +1,419 @@
+/**
+ * Privy device-authorization client (no app secret).
+ * https://docs.privy.io/recipes/agent-integrations/agent-authorization
+ */
+
+import { getAddress } from "viem";
+import { PRIVY_AUTH_BASE, resolvePrivyAppId } from "./privy-constants.mjs";
+import {
+  generateAuthorizationSignature,
+  setupHpkeRecipient,
+} from "./privy-hpke.mjs";
+import {
+  clearPrivySession,
+  loadPrivySession,
+  savePrivySession,
+} from "./privy-session.mjs";
+
+/**
+ * @param {string} path
+ * @param {{
+ *   appId: string,
+ *   method?: string,
+ *   body?: object|null,
+ *   accessToken?: string|null,
+ *   grantType?: string|null,
+ *   authorizationSignature?: string|null,
+ *   fetchImpl?: typeof fetch,
+ * }} opts
+ */
+export async function privyFetch(path, opts) {
+  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+  if (!fetchImpl) throw new Error("fetch is not available");
+  const method = opts.method ?? "POST";
+  const headers = {
+    "Content-Type": "application/json",
+    "privy-app-id": opts.appId,
+  };
+  if (opts.accessToken) {
+    headers.Authorization = `Bearer ${opts.accessToken}`;
+  }
+  if (opts.grantType) {
+    headers["privy-grant-type"] = opts.grantType;
+  }
+  if (opts.authorizationSignature) {
+    headers["privy-authorization-signature"] = opts.authorizationSignature;
+  }
+  const res = await fetchImpl(`${PRIVY_AUTH_BASE}${path}`, {
+    method,
+    headers,
+    body: opts.body == null ? undefined : JSON.stringify(opts.body),
+  });
+  const text = await res.text();
+  let json = null;
+  try {
+    json = text ? JSON.parse(text) : null;
+  } catch {
+    json = { raw: text };
+  }
+  return { ok: res.ok, status: res.status, json, text };
+}
+
+/**
+ * Start device authorization.
+ * @param {{ appId?: string, fetchImpl?: typeof fetch }} [opts]
+ */
+export async function requestDeviceAuthorization(opts = {}) {
+  const appId = opts.appId ?? resolvePrivyAppId();
+  const { ok, status, json, text } = await privyFetch(
+    "/api/oauth/v2/device_authorization",
+    { appId, body: {}, fetchImpl: opts.fetchImpl },
+  );
+  if (!ok) {
+    if (status === 403) {
+      throw new Error(
+        "Privy device auth is not enabled. In the Privy dashboard: Authentication → Advanced → Enable CLI and agent access, Verification URI = https://clanker-chain.com/authorize",
+      );
+    }
+    throw new Error(
+      `device_authorization failed (${status}): ${text?.slice(0, 300) || JSON.stringify(json)}`,
+    );
+  }
+  return {
+    appId,
+    deviceCode: json.device_code,
+    userCode: json.user_code,
+    verificationUri: json.verification_uri,
+    verificationUriComplete: json.verification_uri_complete,
+    expiresIn: Number(json.expires_in) || 600,
+    interval: Number(json.interval) || 5,
+  };
+}
+
+/**
+ * Poll until user approves (or deny / expire).
+ * @param {{
+ *   appId: string,
+ *   deviceCode: string,
+ *   interval?: number,
+ *   expiresIn?: number,
+ *   fetchImpl?: typeof fetch,
+ *   sleep?: (ms: number) => Promise<void>,
+ *   now?: () => number,
+ *   onPending?: () => void,
+ * }} opts
+ */
+export async function pollDeviceToken(opts) {
+  const fetchImpl = opts.fetchImpl;
+  const sleep =
+    opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const now = opts.now ?? (() => Date.now());
+  let intervalMs = Math.max(1, (opts.interval ?? 5) * 1000);
+  const deadline = now() + (opts.expiresIn ?? 600) * 1000;
+
+  while (now() < deadline) {
+    await sleep(intervalMs);
+    const { ok, status, json, text } = await privyFetch("/api/oauth/v2/token", {
+      appId: opts.appId,
+      body: {
+        grant_type: "device_code",
+        device_code: opts.deviceCode,
+      },
+      fetchImpl,
+    });
+    if (ok && json?.access_token) {
+      return {
+        accessToken: json.access_token,
+        refreshToken: json.refresh_token,
+        expiresIn: Number(json.expires_in) || 900,
+      };
+    }
+    const err =
+      json?.error ||
+      json?.error_code ||
+      (typeof json === "object" && json?.error?.code) ||
+      "";
+    const errStr = String(err);
+    if (errStr === "authorization_pending" || status === 400) {
+      if (errStr === "slow_down") {
+        intervalMs += 5000;
+      } else if (errStr === "expired_token") {
+        throw new Error("Login timed out — run clanker login again");
+      } else if (errStr === "access_denied") {
+        throw new Error("Login denied in the browser");
+      } else if (errStr && errStr !== "authorization_pending") {
+        // Some responses nest error differently
+        if (/expired/i.test(text || "")) {
+          throw new Error("Login timed out — run clanker login again");
+        }
+        if (/access_denied|denied/i.test(text || "")) {
+          throw new Error("Login denied in the browser");
+        }
+      }
+      opts.onPending?.();
+      continue;
+    }
+    throw new Error(
+      `token poll failed (${status}): ${text?.slice(0, 300) || JSON.stringify(json)}`,
+    );
+  }
+  throw new Error("Login timed out — run clanker login again");
+}
+
+/**
+ * Refresh access token; persists rotated refresh token.
+ * @param {{
+ *   home?: string,
+ *   session?: object,
+ *   appId?: string,
+ *   fetchImpl?: typeof fetch,
+ * }} [opts]
+ */
+export async function refreshPrivySession(opts = {}) {
+  const home = opts.home;
+  const session = opts.session ?? loadPrivySession(home);
+  if (!session?.refreshToken) {
+    throw new Error("Not logged in — run clanker login");
+  }
+  const appId = opts.appId ?? session.appId ?? resolvePrivyAppId();
+  const { ok, status, json, text } = await privyFetch("/api/oauth/v2/token", {
+    appId,
+    body: {
+      grant_type: "refresh_token",
+      refresh_token: session.refreshToken,
+    },
+    fetchImpl: opts.fetchImpl,
+  });
+  if (!ok || !json?.access_token) {
+    clearPrivySession(home);
+    throw new Error(
+      `Session expired — run clanker login again (${status}): ${text?.slice(0, 200) || ""}`,
+    );
+  }
+  const next = {
+    ...session,
+    appId,
+    accessToken: json.access_token,
+    refreshToken: json.refresh_token || session.refreshToken,
+    expiresAt: Date.now() + (Number(json.expires_in) || 900) * 1000,
+  };
+  savePrivySession(next, home);
+  return next;
+}
+
+/**
+ * Exchange access token for ephemeral authorization key + wallet list.
+ * Auth key stays in memory only.
+ * @param {{
+ *   appId: string,
+ *   accessToken: string,
+ *   fetchImpl?: typeof fetch,
+ * }} opts
+ */
+export async function authenticateWallets(opts) {
+  const hpke = await setupHpkeRecipient();
+  const { ok, status, json, text } = await privyFetch(
+    "/api/oauth/v2/wallets/authenticate",
+    {
+      appId: opts.appId,
+      accessToken: opts.accessToken,
+      grantType: "device_code",
+      body: {
+        encryption_type: "HPKE",
+        recipient_public_key: hpke.publicKeySpkiBase64,
+      },
+      fetchImpl: opts.fetchImpl,
+    },
+  );
+  if (!ok) {
+    throw new Error(
+      `wallets/authenticate failed (${status}): ${text?.slice(0, 300) || JSON.stringify(json)}`,
+    );
+  }
+  const enc = json.encrypted_authorization_key;
+  if (!enc?.encapsulated_key || !enc?.ciphertext) {
+    throw new Error("wallets/authenticate missing encrypted_authorization_key");
+  }
+  const decrypted = await hpke.decryptPayload(
+    Buffer.from(enc.encapsulated_key, "base64"),
+    Buffer.from(enc.ciphertext, "base64"),
+  );
+  const authorizationPrivateKey = new TextDecoder().decode(decrypted);
+  const wallets = Array.isArray(json.wallets) ? json.wallets : [];
+  const eth =
+    wallets.find((w) => w.chain_type === "ethereum" || w.chainType === "ethereum") ||
+    wallets[0];
+  if (!eth?.id || !eth?.address) {
+    throw new Error(
+      "No Ethereum wallet on this login — open /join once to create the embedded EOA, then clanker login again",
+    );
+  }
+  return {
+    authorizationPrivateKey,
+    expiresAt: json.expires_at
+      ? Date.parse(json.expires_at)
+      : Date.now() + 14 * 60 * 1000,
+    walletId: String(eth.id),
+    address: getAddress(eth.address),
+    wallets,
+  };
+}
+
+/**
+ * Ensure a valid session with access token (refresh if near expiry).
+ * @param {{ home?: string, fetchImpl?: typeof fetch, skewMs?: number }} [opts]
+ */
+export async function ensurePrivyAccess(opts = {}) {
+  const skewMs = opts.skewMs ?? 60_000;
+  let session = loadPrivySession(opts.home);
+  if (!session) {
+    throw new Error("Not logged in — run clanker login");
+  }
+  if (!session.expiresAt || session.expiresAt < Date.now() + skewMs) {
+    session = await refreshPrivySession({
+      home: opts.home,
+      session,
+      fetchImpl: opts.fetchImpl,
+    });
+  }
+  return session;
+}
+
+/**
+ * Call Privy wallet RPC (personal_sign / eth_sendTransaction) with device grant.
+ * @param {{
+ *   method: string,
+ *   params: object,
+ *   home?: string,
+ *   session?: object,
+ *   fetchImpl?: typeof fetch,
+ *   authCache?: { key: string, expiresAt: number, walletId: string, address: string }|null,
+ * }} opts
+ */
+export async function privyWalletRpc(opts) {
+  let session = opts.session ?? (await ensurePrivyAccess({ home: opts.home, fetchImpl: opts.fetchImpl }));
+  const appId = session.appId ?? resolvePrivyAppId();
+
+  const runOnce = async (sess) => {
+    const auth = await authenticateWallets({
+      appId,
+      accessToken: sess.accessToken,
+      fetchImpl: opts.fetchImpl,
+    });
+    if (
+      sess.walletId &&
+      auth.walletId !== sess.walletId
+    ) {
+      throw new Error(
+        `Privy wallet changed (${auth.walletId} ≠ ${sess.walletId}) — run clanker login again`,
+      );
+    }
+    if (
+      sess.address &&
+      getAddress(auth.address) !== getAddress(sess.address)
+    ) {
+      throw new Error(
+        `Privy address ${auth.address} does not match session ${sess.address}`,
+      );
+    }
+    const walletId = sess.walletId || auth.walletId;
+    const url = `${PRIVY_AUTH_BASE}/api/oauth/v2/wallets/${walletId}/rpc`;
+    const body = {
+      method: opts.method,
+      params: opts.params,
+    };
+    const authorizationSignature = generateAuthorizationSignature({
+      authorizationPrivateKey: auth.authorizationPrivateKey,
+      method: "POST",
+      url,
+      body,
+      appId,
+    });
+    const { ok, status, json, text } = await privyFetch(
+      `/api/oauth/v2/wallets/${walletId}/rpc`,
+      {
+        appId,
+        accessToken: sess.accessToken,
+        grantType: "device_code",
+        authorizationSignature,
+        body,
+        fetchImpl: opts.fetchImpl,
+      },
+    );
+    return { ok, status, json, text, auth };
+  };
+
+  let result = await runOnce(session);
+  if (result.status === 401) {
+    session = await refreshPrivySession({
+      home: opts.home,
+      session,
+      fetchImpl: opts.fetchImpl,
+    });
+    result = await runOnce(session);
+  }
+  if (!result.ok) {
+    throw new Error(
+      `Privy wallet RPC ${opts.method} failed (${result.status}): ${result.text?.slice(0, 400) || JSON.stringify(result.json)}`,
+    );
+  }
+  return {
+    session,
+    address: result.auth.address,
+    walletId: result.auth.walletId,
+    data: result.json?.data ?? result.json,
+    json: result.json,
+  };
+}
+
+/**
+ * personal_sign via Privy.
+ * @param {string} message
+ * @param {{ home?: string, fetchImpl?: typeof fetch }} [opts]
+ * @returns {Promise<`0x${string}`>}
+ */
+export async function privySignMessage(message, opts = {}) {
+  const out = await privyWalletRpc({
+    method: "personal_sign",
+    params: { message, encoding: "utf-8" },
+    home: opts.home,
+    fetchImpl: opts.fetchImpl,
+  });
+  const sig =
+    out.data?.signature ||
+    out.data?.data?.signature ||
+    out.json?.signature ||
+    out.json?.data?.signature;
+  if (!sig || typeof sig !== "string") {
+    throw new Error(
+      `Privy personal_sign returned no signature: ${JSON.stringify(out.json).slice(0, 400)}`,
+    );
+  }
+  return /** @type {`0x${string}`} */ (sig.startsWith("0x") ? sig : `0x${sig}`);
+}
+
+/**
+ * eth_sendTransaction via Privy (Privy broadcasts).
+ * @param {object} transaction — viem-ish { to, data, value, chain_id }
+ * @param {{ home?: string, fetchImpl?: typeof fetch }} [opts]
+ * @returns {Promise<`0x${string}`>}
+ */
+export async function privySendTransaction(transaction, opts = {}) {
+  const out = await privyWalletRpc({
+    method: "eth_sendTransaction",
+    params: { transaction },
+    home: opts.home,
+    fetchImpl: opts.fetchImpl,
+  });
+  const hash =
+    out.data?.hash ||
+    out.data?.data?.hash ||
+    out.json?.hash ||
+    out.json?.data?.hash;
+  if (!hash || typeof hash !== "string") {
+    throw new Error(
+      `Privy eth_sendTransaction returned no hash: ${JSON.stringify(out.json).slice(0, 400)}`,
+    );
+  }
+  return /** @type {`0x${string}`} */ (hash.startsWith("0x") ? hash : `0x${hash}`);
+}

package/lib/privy-constants.mjs

@@ -0,0 +1,20 @@
+/**
+ * Public Privy app id for device-authorization (no app secret).
+ * Override with PRIVY_APP_ID. Same production app as /join + /authorize.
+ */
+
+/** Production clanker-chain.com Privy app (public). */
+export const DEFAULT_PRIVY_APP_ID = "cmtyejsb100ok0ckz9ldfvakw";
+
+export const PRIVY_AUTH_BASE = "https://auth.privy.io";
+
+/**
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+export function resolvePrivyAppId(env = process.env) {
+  const id = (env.PRIVY_APP_ID || DEFAULT_PRIVY_APP_ID || "").trim();
+  if (!id) {
+    throw new Error("PRIVY_APP_ID is empty");
+  }
+  return id;
+}

package/lib/privy-hpke.mjs

@@ -0,0 +1,101 @@
+/**
+ * HPKE recipient helpers for Privy device-grant wallet authenticate.
+ * Ported from @privy-io/node cryptography (DhkemP256 + ChaCha20Poly1305).
+ */
+
+import { Chacha20Poly1305 } from "@hpke/chacha20poly1305";
+import { CipherSuite, DhkemP256HkdfSha256, HkdfSha256 } from "@hpke/core";
+import { p256 } from "@noble/curves/nist.js";
+import { sha256 } from "@noble/hashes/sha2.js";
+import canonicalize from "canonicalize";
+
+/**
+ * @returns {Promise<{
+ *   publicKeySpkiBase64: string,
+ *   decryptPayload: (encapsulatedKey: Uint8Array, ciphertext: Uint8Array) => Promise<Uint8Array>,
+ * }>}
+ */
+export async function setupHpkeRecipient() {
+  const suite = new CipherSuite({
+    kem: new DhkemP256HkdfSha256(),
+    kdf: new HkdfSha256(),
+    aead: new Chacha20Poly1305(),
+  });
+
+  const keypair = await suite.kem.generateKeyPair();
+  const subtle = globalThis.crypto?.subtle;
+  if (!subtle) {
+    throw new Error("crypto.subtle required for Privy HPKE (Node 20+)");
+  }
+  const publicKeySpki = new Uint8Array(
+    await subtle.exportKey("spki", keypair.publicKey),
+  );
+
+  return {
+    publicKeySpkiBase64: Buffer.from(publicKeySpki).toString("base64"),
+    decryptPayload: async (encapsulatedKey, ciphertext) => {
+      const recipient = await suite.createRecipientContext({
+        recipientKey: keypair.privateKey,
+        enc: encapsulatedKey,
+      });
+      return new Uint8Array(await recipient.open(ciphertext));
+    },
+  };
+}
+
+/**
+ * Import Privy authorization private key (base64 PKCS8, optional wallet-auth: prefix).
+ * @param {string} privateKey
+ * @returns {Uint8Array} raw 32-byte scalar for noble P-256
+ */
+export function importPkcs8PrivateKey(privateKey) {
+  const stripped = String(privateKey)
+    .replace(/^wallet-auth:/, "")
+    .replace(/^wallet-api:/, "")
+    .trim();
+  const pkcs8Bytes = Buffer.from(stripped, "base64");
+  const marker = Buffer.from([0x04, 0x20]);
+  const start = pkcs8Bytes.indexOf(marker);
+  if (start === -1) {
+    throw new Error("Invalid Privy authorization private key");
+  }
+  return pkcs8Bytes.subarray(start + 2, start + 34);
+}
+
+/**
+ * Build + sign Privy authorization signature (P-256 ECDSA over RFC 8785 canonical JSON).
+ * @param {{
+ *   authorizationPrivateKey: string,
+ *   method: 'POST'|'PUT'|'PATCH'|'DELETE',
+ *   url: string,
+ *   body: object,
+ *   appId: string,
+ * }} opts
+ * @returns {string} base64 DER signature
+ */
+export function generateAuthorizationSignature(opts) {
+  const payload = {
+    version: 1,
+    method: opts.method,
+    url: opts.url,
+    body: opts.body,
+    headers: {
+      "privy-app-id": opts.appId,
+    },
+  };
+  if (
+    typeof payload.body === "object" &&
+    payload.body !== null &&
+    Object.keys(payload.body).length === 0
+  ) {
+    payload.body = "";
+  }
+  const serialized = canonicalize(payload);
+  if (!serialized) {
+    throw new Error("Failed to canonicalize Privy authorization payload");
+  }
+  const bytes = new TextEncoder().encode(serialized);
+  const sk = importPkcs8PrivateKey(opts.authorizationPrivateKey);
+  const signature = p256.sign(sha256(bytes), sk).toBytes("der");
+  return Buffer.from(signature).toString("base64");
+}

package/lib/privy-session.mjs

@@ -0,0 +1,151 @@
+/**
+ * Persist Privy OAuth tokens (never operator hex, never ephemeral auth keys).
+ * Prefer macOS Keychain; fall back to mode-0600 ~/.clanker/privy-session.json.
+ */
+
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { clankerHome } from "./profile.mjs";
+
+const KEYCHAIN_SERVICE = "clanker-privy-session";
+const KEYCHAIN_ACCOUNT = "default";
+
+/**
+ * @param {string} [home]
+ */
+export function privySessionPath(home = clankerHome()) {
+  return join(home, "privy-session.json");
+}
+
+/**
+ * @typedef {{
+ *   appId: string,
+ *   accessToken: string,
+ *   refreshToken: string,
+ *   expiresAt: number,
+ *   walletId: string,
+ *   address: string,
+ *   createdAt: number,
+ * }} PrivySession
+ */
+
+/**
+ * @param {string} [home]
+ * @returns {PrivySession|null}
+ */
+export function loadPrivySession(home = clankerHome()) {
+  const fromKeychain = loadFromKeychain();
+  if (fromKeychain) return fromKeychain;
+  const path = privySessionPath(home);
+  if (!existsSync(path)) return null;
+  try {
+    const raw = JSON.parse(readFileSync(path, "utf8"));
+    if (!raw?.accessToken || !raw?.refreshToken || !raw?.walletId || !raw?.address) {
+      return null;
+    }
+    return raw;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {PrivySession} session
+ * @param {string} [home]
+ */
+export function savePrivySession(session, home = clankerHome()) {
+  const payload = JSON.stringify(session);
+  if (saveToKeychain(payload)) {
+    // Prefer keychain; remove file copy if present.
+    const path = privySessionPath(home);
+    if (existsSync(path)) {
+      try {
+        rmSync(path);
+      } catch {
+        /* ignore */
+      }
+    }
+    return { storage: "keychain" };
+  }
+  mkdirSync(home, { recursive: true });
+  const path = privySessionPath(home);
+  writeFileSync(path, `${JSON.stringify(session, null, 2)}\n`, { mode: 0o600 });
+  return { storage: "file", path };
+}
+
+/**
+ * @param {string} [home]
+ */
+export function clearPrivySession(home = clankerHome()) {
+  clearKeychain();
+  const path = privySessionPath(home);
+  if (existsSync(path)) {
+    rmSync(path);
+  }
+}
+
+/**
+ * @returns {PrivySession|null}
+ */
+function loadFromKeychain() {
+  if (process.platform !== "darwin") return null;
+  const out = spawnSync(
+    "security",
+    [
+      "find-generic-password",
+      "-s",
+      KEYCHAIN_SERVICE,
+      "-a",
+      KEYCHAIN_ACCOUNT,
+      "-w",
+    ],
+    { encoding: "utf8" },
+  );
+  if (out.status !== 0) return null;
+  try {
+    const raw = JSON.parse(String(out.stdout || "").trim());
+    if (!raw?.accessToken || !raw?.refreshToken) return null;
+    return raw;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {string} payload
+ */
+function saveToKeychain(payload) {
+  if (process.platform !== "darwin") return false;
+  clearKeychain();
+  const out = spawnSync(
+    "security",
+    [
+      "add-generic-password",
+      "-s",
+      KEYCHAIN_SERVICE,
+      "-a",
+      KEYCHAIN_ACCOUNT,
+      "-w",
+      payload,
+      "-U",
+    ],
+    { encoding: "utf8" },
+  );
+  return out.status === 0;
+}
+
+function clearKeychain() {
+  if (process.platform !== "darwin") return;
+  spawnSync(
+    "security",
+    [
+      "delete-generic-password",
+      "-s",
+      KEYCHAIN_SERVICE,
+      "-a",
+      KEYCHAIN_ACCOUNT,
+    ],
+    { encoding: "utf8", stdio: "ignore" },
+  );
+}

package/lib/profile.mjs

@@ -127,7 +127,7 @@ export function loadOperator(home = clankerHome()) {
 /**
  * Write operator profile (label + owner + optional key pointer). Never stores hex keys.
  * Omit `key` (or pass null) for a read-only profile; mint/revoke still need a pointer later.
- * @param {{ label: string, owner: string, key?: { type: 'env'|'keyFile', value?: string }|null }} op
+ * @param {{ label: string, owner: string, key?: { type: 'env'|'keyFile'|'privy', value?: string }|null }} op
  * @param {string} [home]
  */
 export function writeOperator(op, home = clankerHome()) {