@visa/cli 4.1.0-rc.37 → 4.1.0-rc.39

package/README.md

@@ -1,21 +1,19 @@
 # @visa/cli
 
-Visa CLI v4 gives an AI agent a **Visa Verified Agent** identity and a scoped,
-human-capped signer for a Turnkey-managed wallet. Agents discover paid
-x402/MPP services and pay with USDC over MCP (Model Context Protocol); the
-human approves the limits and every payment is checked against on-device policy
-before anything is signed. Larger browser purchases use a separately approved
-VIC credential and card mandate.
-
-The v4 flow has three parts, always in this order:
-
-1. **Identity** — the human enrolls in the browser (email or Google sign-in, card on file, bank verification) and mints a `.visa` name bound to the agent.
-2. **Delegation** — a pairing ceremony gives the runtime a scoped, revocable
-   Turnkey signer with human-approved per-transaction and daily caps. The
-   runtime never receives the human wallet's root key.
-3. **Payment** — `find → inspect → pay` handles x402/MPP purchases with gasless
-   USDC and explicit maxima; `checkout` / `mandate` handles larger VIC browser
-   purchases.
+Visa CLI v4 pairs an AI runtime to a human-approved **Visa agent identity**.
+The pairing ceremony creates one stable agent ID and activates one
+runtime-custodied Ed25519 identity key. It does not silently create a wallet,
+card credential, budget, mailbox, `.visa` name, or TAP listing.
+
+The product flow has three explicit parts:
+
+1. **Identity** — `enroll_agent` (or `visa agent enroll`) opens one browser
+   review for the exact runtime and public-key fingerprint. The private key
+   stays on the runtime device.
+2. **Capabilities** — payment methods, spend grants, email and directory
+   bindings are configured separately, each with its own human-visible terms.
+3. **Use** — when a separately provisioned capability exists, the wallet and
+   VIC commands enforce that capability's own policy and approval boundary.
 
 ## Install
 
@@ -65,27 +63,59 @@ args = ["<npm root -g>/@visa/cli/dist/mcp-server/index.js"]
 
 There is no CLI subcommand for starting the MCP server directly — the MCP server is the bundled `dist/mcp-server/index.js` entrypoint, which `visa-cli connect <client>` registers for you.
 
-## Enroll a Verified Agent
+## Pair an agent identity
+
+From MCP, call **`enroll_agent`** with `{"action":"start"}`. It creates the
+runtime's Ed25519 key locally, verifies the terminal/browser channel, and opens
+the identity-only review. After the human approves, call `enroll_agent` with
+`{"action":"claim"}` to activate and durably store the identity.
+
+```bash
+visa agent enroll          # opens the one human review page
+visa agent enroll-claim    # resumes delivery/activation after approval
+visa agent list
+visa agent show <agent-id>
+```
 
-Enrollment starts from the agent, not the terminal: the agent calls the **`enroll_agent`** MCP tool, which opens the enrollment page in the browser and prints a 6-character confirmation code in the terminal. The human signs in with **email or Google**, chooses the agent's `.visa` name, adds a card, completes the bank's verification step, and types the confirmation code. When the browser reports the credential was sent to the CLI, the agent calls `enroll_agent` with `{"action":"claim"}` to park the credential on the device.
+The advanced `create` → `claim` → `verify` → `resume` commands are the
+split-device choreography of this same v2 ceremony, not a second enrollment
+system. The review shows the runtime, context, stable agent ID, full public-key
+fingerprint, and expiry. It grants identity only; no spend limits or instruments
+are implied.
 
-Only enter a confirmation code you watched your own terminal print. Enrollment
-must begin with `enroll_agent` and present Turnkey email or Google sign-in.
+On macOS and Linux, the private identity key is stored under
+`~/.visa-cli/agents` in an owner-only directory with file mode `0600`. It is
+currently an exportable local file: copying it transfers identity proof, and
+losing it blocks new proofs because same-agent key recovery is not yet
+available. Protocol-v2 identity pairing fails closed on Windows until the CLI
+can apply and verify an owner-only Windows ACL. The pairing link contains no
+credential or private key.
 
-## Connect an agent runtime (pairing)
+## Recover an existing account session
 
-Enrollment mints identity; **pairing is what lets a runtime sign payments.**
+`visa agent login` opens the Turnkey-first web sign-in for an existing v4
+account, then `visa agent login-claim` stores the returned account session in
+the OS keychain. `--wait` keeps the first command polling for the full
+15-minute browser window.
 
 ```bash
-visa agent create                                                # in the human's terminal — prints the pairing id
-visa agent claim <pairing-id> --runtime <name> --context "<one-line purpose>"
-visa agent verify <pairing-id> <code>                            # verifies the channel, opens the authorization page
-visa agent list                                                  # shows the activated runtime
+visa agent login          # sign in and display the terminal confirmation code
+visa agent login-claim    # resume pickup after returning from the browser
 ```
 
-The browser authorization is the human gate: it shows the runtime and context and sets the **per-transaction and daily spend caps**. If the runtime lost its network response, `visa agent resume <pairing-id>` reprints the code and resumes delivery; `visa agent cancel [pairing-id]` abandons an unapproved request. Pairing credentials are stored on the agent machine with mode `0600`; the pairing link contains no credential.
+This is account-session recovery, not agent pairing. It does not create or
+replace an identity key, delegate a wallet, select a card, set a budget, or
+grant spend authority. The pending PKCE verifier is kept under
+`~/.visa-cli/session-recovery/` in owner-only local state and is pinned to the
+exact web origin that started the flow.
+Session recovery currently fails closed on Windows until the CLI can apply and
+verify an owner-only ACL for this pending verifier.
+
+## Existing wallet capability: caps, then funding
 
-## Caps, then funding — strict order
+These commands apply only to a pre-cutover/test runtime that already has a
+valid, separately provisioned wallet credential. Pairing again cannot create or
+repair that payment capability.
 
 ```bash
 visa wallet limits --per-transaction 0.25 --daily 2.00   # BEFORE any funds arrive
@@ -120,8 +150,8 @@ command.
 
 | Tool | Description |
 |------|-------------|
-| `enroll_agent` | Two-step Verified Agent enrollment: default opens the browser flow with a hand-off challenge; `{"action":"claim"}` stores the enrollment credential on this device |
-| `wallet_status` | Wallet address, network, policy, and pairing state |
+| `enroll_agent` | Two-step identity-only pairing: start opens the exact runtime/key review; `{"action":"claim"}` activates and stores the agent identity |
+| `wallet_status` | Separately provisioned wallet address, network, and policy state |
 | `wallet_policy_set` | Set per-transaction / daily caps (with human approval) |
 | `wallet_discover` | Sweep x402 directories for services, with live re-probing |
 | `wallet_probe` | Fetch a service's live 402 challenge without paying |
@@ -163,7 +193,15 @@ visa pay <listing-id> --max <usd>
 visa activity
 visa receipt <receipt-id>
 
-# Human-approved agent runtime pairing
+# Primary same-machine v2 identity pairing
+visa agent enroll
+visa agent enroll-claim
+
+# Existing-account session recovery (separate from identity pairing)
+visa agent login
+visa agent login-claim
+
+# Advanced split-device form of the same v2 ceremony
 visa agent create
 visa agent claim <pairing-id> --runtime <name> --context "<purpose>"
 visa agent verify <pairing-id> <code>
@@ -200,14 +238,18 @@ visa-cli feedback                   # submit feedback
 
 | Path | Contents |
 |------|----------|
-| `~/.visa-mcp/agent-credential.json` | Verified Agent enrollment credential (mode 0600) |
-| `~/.visa-cli/` | Pairing / delegated signer credentials (mode 0600) |
+| `~/.visa-cli/pairings/` | Pending ceremony verifier or runtime identity key (owner-only mode 0600 on macOS/Linux; v2 pairing currently disabled on Windows) |
+| `~/.visa-cli/agents/` | Activated agent identity, runtime private key, and signed activation credentials (owner-only mode 0600 on macOS/Linux; v2 pairing currently disabled on Windows) |
+| `~/.visa-cli/session-recovery/` | Pending login-only PKCE verifier and pinned web origin (owner-only mode 0600 on macOS/Linux) |
+| `~/.visa-mcp/agent-credential.json` | Legacy checkout-credential compatibility record (mode 0600) |
 | `~/.visa-v4/policy.json` | Wallet spend policy — never edit by hand; use `visa wallet limits` |
 
 ## Troubleshooting
 
-**Wallet commands report pairing is required**
-Payments on a production network require the paired delegated credential — complete enrollment and pairing first. There is no local fallback wallet on mainnet, by design.
+**Wallet commands report that payment setup is required**
+Identity pairing deliberately grants no payment authority. Complete the
+separate wallet/instrument and spend-policy setup when available; pairing again
+will not upgrade an identity into a signer.
 
 **`policy refused` from `pay`**
 A cap or allowlist said no; nothing was signed. Raise caps only via `visa wallet limits` with the human's approval.
@@ -216,7 +258,8 @@ A cap or allowlist said no; nothing was signed. Raise caps only via `visa wallet
 That URL isn't payment-gated — probe the service's actual paid route (`wallet_probe` / `visa find`).
 
 **Pairing ended `expired` or `cancelled`**
-The ceremony timed out — re-run `visa agent create` and claim the new pairing id.
+The ceremony timed out — restart with `visa agent enroll`, then run
+`visa agent enroll-claim` after approving the new browser review.
 
 **Tools don't appear in the AI client**
 Restart the client or reconnect the MCP server (`/mcp` → `visa-cli` → reconnect in Claude Code). Re-run `visa-cli connect <client>` to rewrite the config.

package/dist/checkout-engine/cli-engine.d.ts

@@ -2,7 +2,7 @@ import { type Browser } from 'playwright-core';
 import { prepareCheckout as realPrepareCheckout, submitApprovedCheckout as realSubmitApprovedCheckout, type PreparedCheckoutSessionStore } from './executor.js';
 import { runHostedApproval as realRunHostedApproval } from './hosted-approval.js';
 import { type VgsCheckoutTarget } from './vgs-live-instrument.js';
-import { serverFetchCryptogram } from './vgs-gateway/server-mint-client.js';
+import { serverFetchCryptogram, serverPostConfirmation } from './vgs-gateway/server-mint-client.js';
 import { type CardMandateFacts } from './mandate/card-mandate.js';
 import { MandateLedger } from './mandate/mandate-ledger.js';
 import { writeReceipt as realWriteReceipt } from './receipt.js';
@@ -61,20 +61,13 @@ export type CliReceiptFacts = {
     remainingMinor: number | null;
 };
 export type CliStartMandateInput = {
-    /** The merchant URL for a merchant-scoped mandate. Optional (and ignored) when
-     * `anyMerchant` is set — a budget mandate is not tied to a merchant. */
-    url?: string;
+    /** Optional local card-capability selector (legacy name or exact request-key JKT). */
+    agentRef?: string;
     ceiling: string;
     currency: string;
     credentialPath: string;
     contact: Contact;
     approvalBaseUrl: string;
-    merchantName?: string;
-    merchantCountryCode?: string;
-    /** ISO 8601 mandate expiry; defaults to now + 24h. */
-    expiresAt?: string;
-    /** Max draws the ceiling intent may fulfil. */
-    maxDraws?: number;
     /**
      * Per-purchase cap (decimal string, > 0 and <= ceiling). Registered with the
      * approval context so the operator reads it as a worst-case term, and carried
@@ -86,12 +79,6 @@ export type CliStartMandateInput = {
      * "written by the agent" block — provenance for the human, never trusted.
      */
     intent?: string;
-    /**
-     * BUDGET mode: create a mandate spendable at ANY merchant (no merchant lock),
-     * bounded by the ceiling + per-transaction limit. The passkey approval shows
-     * "spend budget mandate" so the owner consents to the broader scope.
-     */
-    anyMerchant?: boolean;
 };
 export type CliMandateFacts = CardMandateFacts & {
     merchantHost: string;
@@ -99,8 +86,8 @@ export type CliMandateFacts = CardMandateFacts & {
      * True when the mandate minted its ceiling intent but the #5942 register
      * handshake failed, so `findCovering` will SKIP it and no tap-free draw is
      * possible. The mandate exists but is not usable — the caller must surface
-     * this (not report a plain success). Absent/false → registered (or no
-     * delegated binding was present, so register was intentionally not attempted).
+     * this (not report a plain success). Absent/false means registration succeeded;
+     * mandate-start now refuses before approval when no capability can register.
      */
     registerFailed?: boolean;
 };
@@ -128,7 +115,7 @@ export interface CardDrawVerdictCapability {
     authBaseUrl: string;
 }
 export interface CardDrawVerdictSeam {
-    loadCapability: () => CardDrawVerdictCapability | null;
+    loadCapability: (agentRef?: string) => CardDrawVerdictCapability | null;
     fetchVerdict: (input: {
         authBaseUrl: string;
         agentKey: unknown;
@@ -141,7 +128,7 @@ export interface CardDrawVerdictSeam {
     }>;
 }
 export interface CardMandateRegisterSeam {
-    loadCapability: () => {
+    loadCapability: (agentRef?: string) => {
         agentKey: unknown;
         agentJkt: string;
         authBaseUrl: string;
@@ -185,18 +172,18 @@ export type CliEngineDeps = {
      * markUnhonored path with no network.
      */
     serverFetchCryptogram?: typeof serverFetchCryptogram;
+    /** Injectable confirmation transport; defaults to verify-web. */
+    serverPostConfirmation?: typeof serverPostConfirmation;
     /**
      * #5923 delegated card-draw verdict seam (see {@link CardDrawVerdictSeam}).
-     * Injected by the CLI when the agent holds a mode='card' delegated binding;
-     * when absent the covering-mandate draw keeps using the bearer mint token (the
-     * shipped #5917 flow, unchanged).
+     * Injected by the CLI when the runtime holds separately provisioned card
+     * authority. When absent, a covering-mandate draw fails before cryptogram mint.
      */
     cardDrawVerdict?: CardDrawVerdictSeam;
     /**
      * #5942 delegated card-mandate register seam (see {@link CardMandateRegisterSeam}).
-     * Injected by the CLI when the agent holds a mode='card' delegated binding;
-     * when absent mandate-start skips the register (best-effort — the bearer path
-     * still works, only the delegated draw needs the register row).
+     * Required by mandate-start. When absent, the ceremony is refused before
+     * passkey approval because a budget token cannot act as draw authority.
      */
     cardMandateRegister?: CardMandateRegisterSeam;
 };