@bankr/cli 0.3.37 → 0.3.38

package/README.md

@@ -58,6 +58,8 @@ bankr whoami
 bankr logout
 ```
 
+Accounts with two-factor authentication enabled get a browser step during `bankr login email`: the CLI prints (and, when interactive, opens) an approval link on bankr.bot, you verify with your passkey there, and the CLI continues once it sees the approval. The link is valid for five minutes; in a headless run, pass it along to whoever holds the passkey. The approval also covers the rest of that login for five minutes, so if you linger on the key-name prompts past that you'll get a second link. If it expires, or you'd rather skip the hop, generate a key at [bankr.bot/api-keys](https://bankr.bot/api-keys) and use `bankr login --api-key`.
+
 ### Prompts
 
 ```bash
@@ -180,12 +182,13 @@ Credentials are stored in `~/.bankr/config.json`.
 
 Environment variables override stored values:
 
-| Variable        | Description                                                |
-| --------------- | ---------------------------------------------------------- |
-| `BANKR_API_KEY` | API key (overrides stored key)                             |
-| `BANKR_API_URL` | API URL (default: `https://api.bankr.bot`)                 |
-| `BANKR_LLM_KEY` | LLM gateway key (falls back to `BANKR_API_KEY` if not set) |
-| `BANKR_LLM_URL` | LLM gateway URL (default: `https://llm.bankr.bot`)         |
+| Variable        | Description                                                                |
+| --------------- | -------------------------------------------------------------------------- |
+| `BANKR_API_KEY` | API key (overrides stored key)                                             |
+| `BANKR_API_URL` | API URL (default: `https://api.bankr.bot`)                                 |
+| `BANKR_WEB_URL` | Web app URL for browser approval links (default: derived from the API URL) |
+| `BANKR_LLM_KEY` | LLM gateway key (falls back to `BANKR_API_KEY` if not set)                 |
+| `BANKR_LLM_URL` | LLM gateway URL (default: `https://llm.bankr.bot`)                         |
 
 ## API Key
 

package/dist/cli.js

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-import { readFileSync } from "node:fs";
 import { Command } from "commander";
 import { input } from "@inquirer/prompts";
 import { balancesCommand } from "./commands/balances.js";
@@ -9,7 +8,7 @@ import { swapCommand } from "./commands/swap.js";
 import { skillsCommand } from "./commands/capabilities.js";
 import { cancelCommand } from "./commands/cancel.js";
 import { configGetCommand, configSetCommand } from "./commands/config.js";
-import { setConfigPath } from "./lib/config.js";
+import { CLI_VERSION, setConfigPath } from "./lib/config.js";
 import { getErrorMessage } from "./lib/errors.js";
 import { passthroughArgs } from "./lib/passthrough.js";
 import { claudeCommand, creditsCommand, creditsAddCommand, creditsAutoCommand, modelsCommand, opencodeCommand, setupClaudeCodeCommand, setupCursorCommand, setupOpenclawCommand, setupOpenCodeCommand, } from "./commands/llm.js";
@@ -33,7 +32,6 @@ import { filesListCommand, filesUploadCommand, filesDownloadCommand, filesMkdirC
 import { clubStatusCommand, clubSignupCommand, clubCancelCommand, } from "./commands/club.js";
 import * as output from "./lib/output.js";
 import { checkForUpdate } from "./lib/updateCheck.js";
-const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf-8"));
 /**
  * Read prompt text from stdin (piped) or interactively.
  * Bypasses shell expansion so dollar signs and special characters are preserved.
@@ -81,7 +79,7 @@ function colorizeHelp(text) {
 program
     .name("bankr")
     .description("Bankr AI agent CLI\n\n  Docs:   https://docs.bankr.bot\n  Skills: https://docs.bankr.bot/skills/overview")
-    .version(pkg.version, "-v, --version", "Show CLI version")
+    .version(CLI_VERSION, "-v, --version", "Show CLI version")
     .helpOption("-h, --help", "Display help")
     .helpCommand(false)
     .option("--config <path>", "Path to config file (default: ~/.bankr/config.json)")
@@ -1084,7 +1082,7 @@ async function main() {
         }
         output.fatal(getErrorMessage(err));
     }
-    await checkForUpdate(pkg.version);
+    await checkForUpdate(CLI_VERSION);
 }
 main();
 //# sourceMappingURL=cli.js.map

package/dist/commands/login.d.ts

@@ -1,3 +1,20 @@
+/**
+ * Thrown when a login-gated call answers with the MFA step-up envelope. A
+ * passkey ceremony can't run in a terminal, so the email flow can't recover;
+ * the caller turns this into the browser-key guidance instead of the server's
+ * fallback text.
+ */
+export declare class MfaStepUpError extends Error {
+    readonly context: string;
+    constructor(context: string);
+}
+/** Keyed on `code`, never on message text, so a server wording change can't
+ * silently turn this back into the opaque failure. */
+export declare function mfaStepUpErrorFrom(body: unknown): MfaStepUpError | null;
+/** The web app that fronts an API URL: `BANKR_WEB_URL` when set (local dev,
+ * staging), bankr.bot for the official API, else the API host with its
+ * `api.`/`api-` prefix dropped. */
+export declare function deriveWebOrigin(apiUrl: string): string;
 /**
  * Both Privy credentials minted by the OTP exchange. The identity token alone
  * authenticates, but only the ACCESS token carries the session `sid` claim —
@@ -24,6 +41,26 @@ export declare function resolveKeyPermissionOverrides(opts: {
     readOnly?: boolean;
     agentApiEnabled?: boolean;
 };
+declare const CHALLENGE_STATUSES: readonly ["pending", "verified", "expired", "abandoned", "failed"];
+export type ChallengeStatus = (typeof CHALLENGE_STATUSES)[number];
+/**
+ * One poll's outcome from its HTTP status. Only a definitive refusal ends the
+ * wait: the gate (401, an API without this route yet), another wallet's token
+ * (403) or a gone challenge (404). Anything else — 429, 5xx, a dropped
+ * connection — is a blip, so the wait keeps polling as if still pending.
+ */
+export declare function pollOutcome(httpStatus: number, body: unknown): ChallengeStatus;
+/**
+ * Poll until the challenge leaves `pending` or the deadline passes: once at
+ * once, then every 2s for the first 30s, then every 5s. Pure over its
+ * collaborators so the loop is unit-testable without a network.
+ */
+export declare function waitForChallengeApproval(deps: {
+    poll: () => Promise<ChallengeStatus>;
+    sleep: (ms: number) => Promise<void>;
+    deadlineMs: number;
+    now?: () => number;
+}): Promise<ChallengeStatus>;
 export declare function loginCommand(opts: {
     apiUrl?: string;
     apiKey?: string;

package/dist/commands/login.js

@@ -8,12 +8,50 @@ import { getErrorMessage } from "../lib/errors.js";
 const DEFAULT_DASHBOARD_URL = "https://bankr.bot/api-keys";
 const MAX_OTP_ATTEMPTS = 3;
 const INVALID_CODE_STATUSES = [400, 401, 422];
+/** The `code` the API's MFA gates send on every step-up 401 envelope
+ * (`sendStepUpRequired` in packages/api/src/middleware/mfaGate.ts). Duplicated
+ * here because the CLI can't import `@bankr/*` packages. */
+const MFA_STEP_UP_CODE = "MFA_STEP_UP_REQUIRED";
+/**
+ * Thrown when a login-gated call answers with the MFA step-up envelope. A
+ * passkey ceremony can't run in a terminal, so the email flow can't recover;
+ * the caller turns this into the browser-key guidance instead of the server's
+ * fallback text.
+ */
+export class MfaStepUpError extends Error {
+    constructor(context) {
+        super("MFA step-up required");
+        this.context = context;
+        this.name = "MfaStepUpError";
+    }
+}
+/** Keyed on `code`, never on message text, so a server wording change can't
+ * silently turn this back into the opaque failure. */
+export function mfaStepUpErrorFrom(body) {
+    if (!body || typeof body !== "object")
+        return null;
+    const { code, context } = body;
+    if (code !== MFA_STEP_UP_CODE)
+        return null;
+    return new MfaStepUpError(typeof context === "string" ? context : "unknown");
+}
+/** The web app that fronts an API URL: `BANKR_WEB_URL` when set (local dev,
+ * staging), bankr.bot for the official API, else the API host with its
+ * `api.`/`api-` prefix dropped. */
+export function deriveWebOrigin(apiUrl) {
+    const override = process.env.BANKR_WEB_URL?.trim();
+    if (override)
+        return override.replace(/\/+$/, "");
+    if (apiUrl === DEFAULT_API_URL)
+        return "https://bankr.bot";
+    // Anchored to the host's start so a host merely containing "api." is intact.
+    return apiUrl.replace(/\/+$/, "").replace(/^(https?:\/\/)api[.-]/, "$1");
+}
 function deriveDashboardUrl(apiUrl) {
     if (apiUrl === DEFAULT_API_URL) {
         return DEFAULT_DASHBOARD_URL;
     }
-    return (apiUrl.replace(/\/+$/, "").replace("api.", "").replace("api-", "") +
-        "/api-keys");
+    return `${deriveWebOrigin(apiUrl)}/api-keys`;
 }
 async function fetchPrivyConfig(apiUrl) {
     const res = await fetch(`${apiUrl}/cli/config`, {
@@ -100,7 +138,10 @@ async function callGenerateWallet(apiUrl, tokens) {
     });
     const body = (await res.json());
     if (!res.ok) {
-        throw new Error(body.message || body.error || `Wallet generation failed (${res.status})`);
+        throw (mfaStepUpErrorFrom(body) ??
+            new Error(body.message ||
+                body.error ||
+                `Wallet generation failed (${res.status})`));
     }
     return body;
 }
@@ -111,7 +152,8 @@ async function callAcceptTerms(apiUrl, tokens) {
     });
     if (!res.ok) {
         const body = (await res.json().catch(() => ({})));
-        throw new Error(body.message || body.error || `Accept terms failed (${res.status})`);
+        throw (mfaStepUpErrorFrom(body) ??
+            new Error(body.message || body.error || `Accept terms failed (${res.status})`));
     }
 }
 async function callGenerateApiKey(apiUrl, tokens, opts) {
@@ -122,10 +164,115 @@ async function callGenerateApiKey(apiUrl, tokens, opts) {
     });
     const body = (await res.json());
     if (!res.ok) {
-        throw new Error(body.message || body.error || `API key generation failed (${res.status})`);
+        throw (mfaStepUpErrorFrom(body) ??
+            new Error(body.message ||
+                body.error ||
+                `API key generation failed (${res.status})`));
     }
     return body;
 }
+// ── Out-of-band MFA approval ─────────────────────────────────────────
+// Mirrors `MFA_CHALLENGE_STATUSES` in @bankr/shared (the CLI can't import it).
+const CHALLENGE_STATUSES = [
+    "pending",
+    "verified",
+    "expired",
+    "abandoned",
+    "failed",
+];
+/** Narrow the status poll body; anything unrecognised reads as `failed`. */
+function parseChallengeStatus(body) {
+    const status = body?.status;
+    return CHALLENGE_STATUSES.includes(status)
+        ? status
+        : "failed";
+}
+/**
+ * One poll's outcome from its HTTP status. Only a definitive refusal ends the
+ * wait: the gate (401, an API without this route yet), another wallet's token
+ * (403) or a gone challenge (404). Anything else — 429, 5xx, a dropped
+ * connection — is a blip, so the wait keeps polling as if still pending.
+ */
+export function pollOutcome(httpStatus, body) {
+    if (httpStatus >= 200 && httpStatus < 300)
+        return parseChallengeStatus(body);
+    return [401, 403, 404].includes(httpStatus) ? "failed" : "pending";
+}
+/** Poll cadence: 2s while an approval is likely imminent, then 5s. */
+const POLL_FAST_MS = 2000;
+const POLL_SLOW_MS = 5000;
+const POLL_FAST_WINDOW_MS = 30000;
+/**
+ * Poll until the challenge leaves `pending` or the deadline passes: once at
+ * once, then every 2s for the first 30s, then every 5s. Pure over its
+ * collaborators so the loop is unit-testable without a network.
+ */
+export async function waitForChallengeApproval(deps) {
+    const now = deps.now ?? Date.now;
+    const startedAt = now();
+    for (;;) {
+        const status = await deps.poll();
+        if (status !== "pending")
+            return status;
+        if (now() >= deps.deadlineMs)
+            return "expired";
+        await deps.sleep(now() - startedAt < POLL_FAST_WINDOW_MS ? POLL_FAST_MS : POLL_SLOW_MS);
+    }
+}
+async function createMfaChallenge(apiUrl, tokens, context) {
+    const res = await fetch(`${apiUrl}/user/mfa/challenge`, {
+        method: "POST",
+        headers: authHeaders(tokens),
+        body: JSON.stringify({ context }),
+    });
+    if (!res.ok) {
+        throw new Error(`Couldn't start passkey approval (${res.status})`);
+    }
+    return (await res.json());
+}
+async function readMfaChallengeStatus(apiUrl, tokens, token) {
+    try {
+        const res = await fetch(`${apiUrl}/user/mfa/challenge/${token}`, {
+            headers: authHeaders(tokens),
+        });
+        return pollOutcome(res.status, await res.json().catch(() => null));
+    }
+    catch {
+        return "pending";
+    }
+}
+/** Mirrors the server's challenge TTL; the deadline is kept on the local clock
+ * so a skewed machine can't expire the wait early (the poll reports a real
+ * server-side expiry as `expired` regardless). */
+const CHALLENGE_TTL_MS = 5 * 60 * 1000;
+/**
+ * The browser hop for an MFA-enabled account: create a challenge for THIS
+ * session, hand the user the confirm link, and wait for their passkey on the
+ * web to mint the grants. Resolves true once approved.
+ */
+async function approveInBrowser(apiUrl, tokens) {
+    const { token } = await createMfaChallenge(apiUrl, tokens, "api-key:generate");
+    const url = `${deriveWebOrigin(apiUrl)}/mfa/confirm/${token}`;
+    output.blank();
+    output.warn("Two-factor authentication is enabled on this account.");
+    output.info("Approve this login with your passkey:");
+    output.brandBold(`  ${url}`);
+    if (!output.isNonInteractive()) {
+        await open(url).catch(() => undefined);
+    }
+    const spin = output.spinner("Waiting for approval in your browser...");
+    const status = await waitForChallengeApproval({
+        poll: () => readMfaChallengeStatus(apiUrl, tokens, token),
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+        deadlineMs: Date.now() + CHALLENGE_TTL_MS,
+    });
+    if (status === "verified") {
+        spin.succeed("Approved");
+        return true;
+    }
+    spin.fail(`Approval ${status}`);
+    return false;
+}
 // ── OTP verification helpers ─────────────────────────────────────────
 async function fetchPrivyConfigOrFail(apiUrl) {
     const config = await fetchPrivyConfig(apiUrl).catch(() => null);
@@ -220,20 +367,57 @@ async function authenticateWithEmail(apiUrl, providedEmail, providedCode) {
     }
     output.fatal("Verification failed. Please try again.");
 }
+/**
+ * Run a login-gated call; on the MFA step-up envelope, take the browser
+ * approval hop once and retry. A second refusal, or an approval that expires
+ * or fails, exits with the browser-key guidance.
+ */
+async function runGatedStep(apiUrl, tokens, label, run) {
+    for (const retry of [false, true]) {
+        const spin = output.spinner(label);
+        try {
+            const result = await run();
+            spin.stop();
+            return result;
+        }
+        catch (err) {
+            spin.stop();
+            if (!(err instanceof MfaStepUpError) || retry) {
+                return failLoginStep(`${label} failed`, err, apiUrl);
+            }
+        }
+        const approved = await approveInBrowser(apiUrl, tokens).catch((err) => {
+            output.error(getErrorMessage(err));
+            return false;
+        });
+        if (!approved)
+            return exitWithApiKeyGuidance(apiUrl);
+    }
+    throw new Error("unreachable");
+}
+/** Exit with the generic epilogue, or the browser-key path on a step-up
+ * refusal the approval hop didn't clear. */
+function failLoginStep(label, err, apiUrl) {
+    if (!(err instanceof MfaStepUpError)) {
+        return output.fatal(`${label}: ${getErrorMessage(err)}`);
+    }
+    return exitWithApiKeyGuidance(apiUrl);
+}
+/** The remediation is the point of this message, so every line stays on
+ * stderr with the headline: a scripted caller capturing stderr sees all of it. */
+function exitWithApiKeyGuidance(apiUrl) {
+    output.error("Two-factor authentication is enabled on this account.");
+    output.errorDetail("  The passkey approval didn't complete.");
+    output.errorDetail(`  Generate an API key at ${deriveDashboardUrl(apiUrl)} instead (verify with your passkey there), then run:`);
+    output.errorDetail("    bankr login --api-key bk_YOUR_KEY");
+    process.exit(1);
+}
 // ── Email login flow ────────────────────────────────────────────────
 async function emailLoginFlow(apiUrl, opts) {
     // Step 1: Authenticate via email OTP
     const { tokens } = await authenticateWithEmail(apiUrl, opts.email, opts.code);
     // Step 2: Generate/resolve wallet
-    const walletSpin = output.spinner("Setting up wallet...");
-    let wallet;
-    try {
-        wallet = await callGenerateWallet(apiUrl, tokens);
-        walletSpin.stop();
-    }
-    catch (err) {
-        output.failWith(walletSpin, "Wallet setup failed", err);
-    }
+    const wallet = await runGatedStep(apiUrl, tokens, "Setting up wallet...", () => callGenerateWallet(apiUrl, tokens));
     // Show wallet info
     output.blank();
     if (wallet.isNewUser) {
@@ -264,14 +448,8 @@ async function emailLoginFlow(apiUrl, opts) {
         if (!accepted) {
             output.fatal("Terms must be accepted to continue.");
         }
-        const termsSpin = output.spinner("Accepting terms...");
-        try {
-            await callAcceptTerms(apiUrl, tokens);
-            termsSpin.succeed("Terms accepted");
-        }
-        catch (err) {
-            output.failWith(termsSpin, "Failed to accept terms", err);
-        }
+        await runGatedStep(apiUrl, tokens, "Accepting terms...", () => callAcceptTerms(apiUrl, tokens));
+        output.success("Terms accepted");
     }
     // Step 4: Generate API key
     output.blank();
@@ -301,23 +479,15 @@ async function emailLoginFlow(apiUrl, opts) {
                 default: false,
                 theme: output.bankrTheme,
             }));
-    const keySpin = output.spinner("Generating API key...");
-    let apiKeyResult;
-    try {
-        apiKeyResult = await callGenerateApiKey(apiUrl, tokens, {
-            name: keyName.trim(),
-            walletApiEnabled: enableWallet,
-            ...overrides,
-            tokenLaunchApiEnabled: enableTokenLaunch,
-            llmGatewayEnabled: enableLlm,
-            allowedIps: opts.allowedIps,
-            allowedRecipients: opts.allowedRecipients,
-        });
-        keySpin.stop();
-    }
-    catch (err) {
-        output.failWith(keySpin, "Failed to generate API key", err);
-    }
+    const apiKeyResult = await runGatedStep(apiUrl, tokens, "Generating API key...", () => callGenerateApiKey(apiUrl, tokens, {
+        name: keyName.trim(),
+        walletApiEnabled: enableWallet,
+        ...overrides,
+        tokenLaunchApiEnabled: enableTokenLaunch,
+        llmGatewayEnabled: enableLlm,
+        allowedIps: opts.allowedIps,
+        allowedRecipients: opts.allowedRecipients,
+    }));
     // Show result
     output.blank();
     const features = [

package/dist/commands/update.js

@@ -1,7 +1,7 @@
-import { readFileSync } from "node:fs";
 import { execSync } from "node:child_process";
 import * as output from "../lib/output.js";
 import { getErrorMessage } from "../lib/errors.js";
+import { CLI_VERSION } from "../lib/config.js";
 const PACKAGE_NAME = "@bankr/cli";
 /**
  * Compare two semver version strings.
@@ -31,8 +31,7 @@ async function fetchLatestVersion() {
     return data.version;
 }
 function getCurrentVersion() {
-    const pkg = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf-8"));
-    return pkg.version;
+    return CLI_VERSION;
 }
 /**
  * Detect which package manager installed the CLI globally.

package/dist/lib/config.d.ts

@@ -11,7 +11,8 @@ export declare function setConfigPath(path: string): void;
 export declare function getConfigPath(): string;
 export declare const DEFAULT_API_URL = "https://api.bankr.bot";
 export declare const DEFAULT_LLM_URL = "https://llm.bankr.bot";
-export declare const CLI_USER_AGENT = "bankr-cli/0.1";
+export declare const CLI_VERSION: string;
+export declare const CLI_USER_AGENT: string;
 export declare function readConfig(): BankrConfig;
 export declare function writeConfig(config: BankrConfig): void;
 export declare function clearConfig(): void;

package/dist/lib/config.js

@@ -1,5 +1,5 @@
 import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync, } from "fs";
-import { homedir } from "os";
+import { homedir, platform, release } from "os";
 import { dirname, join } from "path";
 let configPathOverride;
 const DEFAULT_CONFIG_FILE = join(homedir(), ".bankr", "config.json");
@@ -11,7 +11,23 @@ export function getConfigPath() {
 }
 export const DEFAULT_API_URL = "https://api.bankr.bot";
 export const DEFAULT_LLM_URL = "https://llm.bankr.bot";
-export const CLI_USER_AGENT = "bankr-cli/0.1";
+export const CLI_VERSION = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf-8")).version;
+/** Browser-style platform token so the API's shared user-agent parser (which
+ * clamps to known families) names the OS on an out-of-band approval screen
+ * as "Bankr CLI · macOS". Never the hostname or username. */
+function platformToken() {
+    switch (platform()) {
+        case "darwin":
+            return "Macintosh";
+        case "win32":
+            return "Windows NT";
+        case "linux":
+            return "Linux";
+        default:
+            return platform();
+    }
+}
+export const CLI_USER_AGENT = `bankr-cli/${CLI_VERSION} (${platformToken()}; ${platform()} ${release()})`;
 function ensureConfigDir() {
     const configDir = dirname(getConfigPath());
     if (!existsSync(configDir)) {

package/dist/lib/output.d.ts

@@ -22,6 +22,8 @@ export declare function brand(msg: string): void;
 export declare function brandBold(msg: string): void;
 export declare function success(msg: string): void;
 export declare function error(msg: string): void;
+/** Dim follow-up line for an error, on stderr so it stays with the headline. */
+export declare function errorDetail(msg: string): void;
 /** Collapses the error-then-exit epilogue every command repeats. */
 export declare function fatal(message: string): never;
 /** Same epilogue, for the spinner-driven variant that reports a caught error. */

package/dist/lib/output.js

@@ -40,6 +40,10 @@ export function success(msg) {
 export function error(msg) {
     console.error(chalk.red(`✗ ${msg}`));
 }
+/** Dim follow-up line for an error, on stderr so it stays with the headline. */
+export function errorDetail(msg) {
+    console.error(chalk.dim(msg));
+}
 /** Collapses the error-then-exit epilogue every command repeats. */
 export function fatal(message) {
     error(message);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bankr/cli",
-  "version": "0.3.37",
+  "version": "0.3.38",
   "description": "Official CLI for the Bankr AI agent platform",
   "type": "module",
   "bin": {