@agentgrant.cash/cli 1.4.0 → 1.4.2

package/README.md

@@ -21,12 +21,13 @@ npm run build && ./dist/cli/index.js status
 
 | Surface | Routes to | Auth |
 |---|---|---|
-| money: `portfolio`, `price`, `buy`, `sell`, `activity` | Perfolio backend (`GRANTCASH_API_URL`) | Bearer device token (`pfk_`) |
-| agent: `search`, `check`, `fetch`, `transfer`, `revoke` | Agent-mode backend (`GRANTCASH_AGENT_URL`) | `X-API-Key` (`grant_live_`) |
+| money: `portfolio`, `price`, `buy`, `sell`, `activity` | Perfolio backend (`GRANTCASH_API_URL`) | `Authorization: Bearer <accessJwt>` |
+| agent: `search`, `check`, `fetch`, `transfer`, `revoke` | Agent-mode backend (`GRANTCASH_AGENT_URL`) | `Authorization: Bearer <accessJwt>` |
 
-`grant login` runs the money-side device handshake (browser sign-in + limit
-approval) and links the agent key in one step. Credentials for both live in one
-file (`~/.grant-cash/credentials.json`).
+`grant login` runs ONE perfolio device handshake (browser sign-in + limit
+approval) and stores a single credential — the perfolio-signed access JWT plus
+the opaque `pfr_` refresh token, in `~/.grant-cash/credentials.json`. That one
+JWT is sent to BOTH backends; a 401 from either silently refreshes it once.
 
 ## Configuration
 
@@ -42,7 +43,6 @@ command surface, workflow, and error playbook for an AI assistant.
 
 Scaffold of the merged architecture with a working command set across both
 engines. Money side is gold-focused by design; borrow/earn/perps endpoints are a
-one-method-each extension on `MoneyClient`. The unified `login` links the agent
-key via `--agent-key`/`GRANTCASH_AGENT_KEY` today; once the backends share one
-connect (the planned `device/complete` carrying the partner key), a single poll
-will return both credentials and only that step changes.
+one-method-each extension on `MoneyClient`. Unified auth (CONTRACT v1): one
+perfolio login mints one access JWT that both backends verify locally against
+perfolio's JWKS — the CLI holds a single credential and sends it everywhere.

package/dist/cli/commands/auth.js

@@ -1,71 +1,49 @@
-import { buildContext, emit, ui, startDevice, waitForDevice, moneyPollIntervalMs, revokeDevice, listDevices, detectClient, openBrowser, clearCredentials, AppError, generatePkce, startAgentDevice, waitForAgentDevice, agentPollIntervalMs, } from "../../lib/index.js";
+import { buildContext, emit, ui, startDevice, waitForDevice, moneyPollIntervalMs, revokeDevice, listDevices, detectClient, openBrowser, clearCredentials, AppError, } from "../../lib/index.js";
 /**
- * `grant login` — one connect for both engines.
+ * `grant login` — one connect, one credential (unified auth).
  *
- * Runs TWO device handshakes in a single pass so the user thinks about one
- * connect, not two backends:
- *   - MONEY side (Perfolio): `cli/device/*`, sid relayed to the browser via the
- *     connect URL, mints a `pfk_` Bearer token.
- *   - AGENT side (Agent-mode): PKCE S256 `onboard/privy-cli/device/*`, its sid
- *     relayed alongside as `&agentSid=<sid>`, mints a `grant_live_` X-API-Key.
- *
- * The agent sid is generated first so it can be carried on the SAME browser link
- * the user opens; the one logged-in browser session completes both backends. We
- * then poll each backend independently (each with its own secret) and write BOTH
- * credentials to the existing merged file. An explicit `--agent-key`/env key
- * still short-circuits the agent handshake (manual linking).
- *
- * Partial-failure is never silent: if money connects but spending stays
- * pending/expired we report "investing connected, spending pending" plus a retry
- * hint. A `complete` with no apiKey = already provisioned → keep the existing key.
+ * Runs a SINGLE perfolio device handshake: `cli/device/*`, the one-time `sid`
+ * relayed to the browser via the connect URL. The logged-in browser completes it
+ * server-side; the CLI polls until perfolio returns the credential. The result is
+ * the perfolio-signed access JWT (`accessJwt`) plus the opaque `pfr_` refresh
+ * token — that ONE JWT is sent as `Authorization: Bearer` to BOTH backends
+ * (money + agent). The old agent-side `grant_live_` PKCE leg is retired: there is
+ * no second handshake, no `--agent-key`, no separate spending credential.
  */
-function maskKey(k) {
-    if (!k)
-        return "(none)";
-    return k.length <= 12 ? "****" : `${k.slice(0, 9)}…${k.slice(-4)}`;
+/**
+ * Map a completed perfolio device flow to the stored credential. A fresh login
+ * REPLACES the whole credentials file — no stale agent key is carried over (the
+ * `grant_live_` leg is gone) — so the file holds exactly one perfolio credential.
+ */
+export function loginCredentials(result) {
+    return {
+        money: {
+            accessJwt: result.accessJwt,
+            refreshToken: result.refreshToken,
+            expiresAt: result.expiresAt,
+            email: result.email,
+            walletAddress: result.walletAddress,
+            deviceId: result.deviceId,
+        },
+    };
 }
 export function registerAuth(program) {
     program
         .command("login")
         .description("Connect Grant Cash — your money and your agent, in one step")
         .option("--no-open", "do not auto-open the browser; just print the URL")
-        .option("--agent-key <key>", "link your agent key (grant_live_…) in the same step")
         .option("--timeout <seconds>", "how long to wait for the browser", "300")
         .action(async (opts, cmd) => {
         const ctx = buildContext(cmd);
         const client = detectClient();
         const timeoutMs = Math.max(30, Number(opts.timeout) || 300) * 1000;
-        // An explicit key (flag/env) means "link this, skip the agent handshake".
-        const manualAgentKey = opts.agentKey || process.env.GRANTCASH_AGENT_KEY;
-        const runAgentFlow = !manualAgentKey;
-        // ── start BOTH handshakes (agent first so its sid rides the same link) ──
+        // ── one perfolio handshake ──
         const start = await startDevice(ctx.urls.api, client, client);
-        // Agent side is best-effort to start: if the agent backend is unreachable
-        // we still let the money connect succeed and report spending as pending.
-        let agentPkce;
-        let agentSid;
-        let agentPollMs = 3000;
-        let agentStartError;
-        if (runAgentFlow) {
-            agentPkce = generatePkce();
-            try {
-                const aStart = await startAgentDevice(ctx.urls.agent, agentPkce, client);
-                agentSid = aStart.sid;
-                agentPollMs = agentPollIntervalMs(aStart.pollInterval);
-            }
-            catch (e) {
-                agentStartError = e;
-            }
-        }
         // Open the Grant Cash connect screen (GRANTCASH_APP_URL) carrying the
-        // one-time money sid — NOT the backend's own URL — so sign-in happens in
-        // the Grant Cash UI. The agent sid rides the SAME link as `&agentSid` so a
-        // single logged-in browser completes both backends. The sids are the only
-        // secrets; minting still requires a logged-in browser (and, for the agent,
-        // the PKCE verifier held only in this process), so the link alone is useless.
-        let connectUrl = `${ctx.urls.app.replace(/\/$/, "")}/connect?sid=${encodeURIComponent(start.sid)}&client=${encodeURIComponent(client)}`;
-        if (agentSid)
-            connectUrl += `&agentSid=${encodeURIComponent(agentSid)}`;
+        // one-time sid — NOT the backend's own URL — so sign-in happens in the
+        // Grant Cash UI. The sid is the only secret; minting still requires a
+        // logged-in browser, so the link alone is useless.
+        const connectUrl = `${ctx.urls.app.replace(/\/$/, "")}/connect?sid=${encodeURIComponent(start.sid)}&client=${encodeURIComponent(client)}`;
         if (!ctx.json) {
             process.stdout.write(`\n${ui.title("Connect Grant Cash")}\n` +
                 `Open this link to sign in and approve your limits:\n\n  ${ui.green(connectUrl)}\n\n` +
@@ -74,122 +52,29 @@ export function registerAuth(program) {
         }
         if (opts.open !== false)
             openBrowser(connectUrl);
-        // ── poll BOTH backends (each with its own secret) ──
-        // Money is the primary identity; the agent (spending) side is best-effort.
-        // Both polls run concurrently, but we SETTLE on money: the moment it
-        // connects we stop blocking on the agent poll (a slow/cold spending backend
-        // or a stale agent sid must never leave the terminal "still polling" after
-        // the browser has finished). The browser completes the agent device in
-        // step 1 — BEFORE it mints money in step 3 — so the agent key is almost
-        // always already waiting by the time money lands; a short grace collects it.
-        const moneyP = waitForDevice(ctx.urls.api, start.sid, moneyPollIntervalMs(start.pollInterval), timeoutMs);
-        const agentAbort = new AbortController();
-        const agentP = agentSid && agentPkce
-            ? waitForAgentDevice(ctx.urls.agent, agentSid, agentPkce.verifier, agentPollMs, timeoutMs, fetch, agentAbort.signal)
-            : Promise.resolve({ status: "expired" });
-        const result = await moneyP;
-        // Money is the primary identity — if it didn't complete, the whole login
-        // failed (mirrors the original behavior). Abort the agent poll first so the
-        // process can exit promptly instead of running to the agent timeout.
+        const result = await waitForDevice(ctx.urls.api, start.sid, moneyPollIntervalMs(start.pollInterval), timeoutMs);
         if (result.status !== "complete") {
-            agentAbort.abort();
             throw new AppError(result.status === "denied"
                 ? "Connection was declined in the browser."
                 : "Connection timed out. Run `grant login` again.", { code: result.status === "denied" ? "DENIED" : "EXPIRED", recoverable: true });
         }
-        // Money connected — settle now. Give the agent poll a short grace to also
-        // land, then stop regardless and report whatever we have (a grace timeout
-        // → "spending pending", surfaced with a retry hint below). Aborting after
-        // the race stops the background loop so the CLI exits without hanging.
-        const AGENT_SETTLE_GRACE_MS = 15_000;
-        const agentResult = await Promise.race([
-            agentP.catch(() => ({ status: "pending" })),
-            new Promise((res) => setTimeout(() => res({ status: "pending" }), AGENT_SETTLE_GRACE_MS)),
-        ]);
-        agentAbort.abort();
-        // ── resolve the agent credential ──
-        // Precedence: explicit manual key > freshly minted key > already-provisioned
-        // (complete without apiKey → keep the key already on disk).
-        const existingAgentKey = ctx.creds.agent?.apiKey;
-        let agentKey = manualAgentKey;
-        let agentState;
-        if (manualAgentKey) {
-            agentState = "linked";
-        }
-        else if (agentResult.status === "complete") {
-            if (agentResult.apiKey) {
-                agentKey = agentResult.apiKey; // one-time pickup of the new key
-                agentState = "minted";
-            }
-            else {
-                agentKey = existingAgentKey; // already provisioned — keep what we have
-                agentState = "already";
-            }
-        }
-        else {
-            agentKey = existingAgentKey; // never clobber an existing key on a miss
-            agentState = agentResult.status === "expired" ? "expired" : "pending";
-        }
-        const spendingConnected = Boolean(agentKey);
-        const next = {
-            ...ctx.creds,
-            money: {
-                token: result.result.token,
-                refreshToken: result.result.refreshToken,
-                expiresAt: result.result.expiresAt,
-                email: result.result.email,
-                walletAddress: result.result.walletAddress,
-                deviceId: result.result.deviceId,
-            },
-            ...(agentKey ? { agent: { apiKey: agentKey } } : {}),
-        };
-        ctx.save(next);
-        // Retry hint for the spending side when it didn't land this pass.
-        const retryHint = agentStartError
-            ? "Run `grant login` again to finish spending setup (the spending backend was unreachable)."
-            : "Run `grant login` again to finish spending setup.";
+        ctx.save(loginCredentials(result.result));
         emit(ctx, {
             connected: true,
-            money: { email: result.result.email, wallet: result.result.walletAddress },
-            agent: {
-                connected: spendingConnected,
-                state: agentState,
-                ...(agentState === "pending" || agentState === "expired"
-                    ? { hint: retryHint }
-                    : {}),
-            },
-        }, () => {
-            const moneyLine = `\n  Money:  ${result.result.email || result.result.walletAddress}`;
-            let agentLine;
-            switch (agentState) {
-                case "linked":
-                    agentLine = `\n  Agent:  ${ui.green("linked")}`;
-                    break;
-                case "minted":
-                    agentLine = `\n  Agent:  ${ui.green("connected")}`;
-                    break;
-                case "already":
-                    agentLine = `\n  Agent:  ${ui.green("connected (already set up)")}`;
-                    break;
-                default:
-                    agentLine =
-                        `\n  Agent:  ${ui.amber("spending pending")}` +
-                            `\n${ui.dim("          " + retryHint)}`;
-            }
-            const header = spendingConnected || agentState === "linked"
-                ? ui.green("✓ Connected.")
-                : ui.green("✓ Investing connected.") +
-                    ui.amber(" Spending still pending.");
-            return `\n${header}${moneyLine}${agentLine}\n`;
-        });
+            email: result.result.email,
+            wallet: result.result.walletAddress,
+        }, () => `\n${ui.green("✓ Connected.")}` +
+            `\n  ${result.result.email || result.result.walletAddress}` +
+            `\n${ui.dim("  Money and agent both ready.")}\n`);
     });
     program
         .command("logout")
         .description("Disconnect — revoke this device and clear stored credentials")
         .action(async (_opts, cmd) => {
         const ctx = buildContext(cmd);
-        if (ctx.creds.money?.token) {
-            await revokeDevice(ctx.urls.api, ctx.creds.money.token, ctx.creds.money.deviceId);
+        const jwt = ctx.creds.money?.accessJwt;
+        if (jwt) {
+            await revokeDevice(ctx.urls.api, jwt, ctx.creds.money?.deviceId);
         }
         clearCredentials(ctx.credsPath);
         emit(ctx, { disconnected: true }, () => ui.dim("Disconnected. Credentials cleared."));
@@ -197,35 +82,33 @@ export function registerAuth(program) {
     program
         .command("status")
         .alias("whoami")
-        .description("Show what's connected (money + agent) and where it routes")
+        .description("Show what's connected and where it routes")
         .action(async (_opts, cmd) => {
         const ctx = buildContext(cmd);
         const money = ctx.creds.money;
-        const agent = ctx.creds.agent;
+        const connected = Boolean(money?.accessJwt);
         emit(ctx, {
-            money: {
-                connected: Boolean(money?.token),
-                email: money?.email,
-                wallet: money?.walletAddress,
-            },
-            agent: { connected: Boolean(agent?.apiKey), key: maskKey(agent?.apiKey) },
+            // One credential now drives both engines — `money`/`agent` connectivity
+            // are the same JWT. Kept as separate keys for backward-compatible output.
+            connected,
+            money: { connected, email: money?.email, wallet: money?.walletAddress },
+            agent: { connected },
             routes: { api: ctx.urls.api, fiat: ctx.urls.fiat, agent: ctx.urls.agent },
         }, () => `${ui.title("Grant Cash")}\n` +
-            `  Money:  ${money?.token ? ui.green(money.email || money.walletAddress || "connected") : ui.amber("not connected")}\n` +
-            `  Agent:  ${agent?.apiKey ? ui.green(maskKey(agent.apiKey)) : ui.amber("not connected")}\n` +
+            `  ${connected ? ui.green(money?.email || money?.walletAddress || "connected") : ui.amber("not connected")}\n` +
             ui.dim(`  → money ${ctx.urls.api}\n  → agent ${ctx.urls.agent}`));
     });
-    // ── manage connected agents/devices (money side) ──
+    // ── manage connected agents/devices ──
     const devices = program.command("devices").description("Manage connected agents/devices");
     devices
         .command("list")
         .description("List devices connected to your account")
         .action(async (_opts, cmd) => {
         const ctx = buildContext(cmd);
-        const token = ctx.creds.money?.token;
-        if (!token)
+        const jwt = ctx.creds.money?.accessJwt;
+        if (!jwt)
             throw new AppError("Not connected. Run `grant login` first.", { code: "NOT_CONNECTED" });
-        const list = await listDevices(ctx.urls.api, token);
+        const list = await listDevices(ctx.urls.api, jwt);
         emit(ctx, { devices: list }, () => {
             if (!list.length)
                 return ui.dim("No devices connected.");
@@ -239,10 +122,10 @@ export function registerAuth(program) {
         .description("Revoke a connected device by id")
         .action(async (deviceId, _opts, cmd) => {
         const ctx = buildContext(cmd);
-        const token = ctx.creds.money?.token;
-        if (!token)
+        const jwt = ctx.creds.money?.accessJwt;
+        if (!jwt)
             throw new AppError("Not connected. Run `grant login` first.", { code: "NOT_CONNECTED" });
-        await revokeDevice(ctx.urls.api, token, deviceId);
+        await revokeDevice(ctx.urls.api, jwt, deviceId);
         emit(ctx, { revoked: true, deviceId }, () => ui.green(`✓ Revoked device ${deviceId}.`));
     });
 }

package/dist/cli/commands/meta.js

@@ -43,11 +43,12 @@ export function registerMeta(program) {
         .description("Show resolved routes and connection state")
         .action((_opts, cmd) => {
         const ctx = buildContext(cmd);
-        const key = ctx.creds.agent?.apiKey;
+        // One perfolio JWT drives both engines now — connectivity is the same token.
+        const connected = Boolean(ctx.creds.money?.accessJwt);
         emit(ctx, {
             routes: ctx.urls,
-            money: { connected: Boolean(ctx.creds.money?.token) },
-            agent: { connected: Boolean(key) },
+            money: { connected },
+            agent: { connected },
             credsPath: ctx.credsPath,
         }, () => `${ui.title("Routes")}\n` +
             `  money api   ${ctx.urls.api}\n` +
@@ -55,15 +56,6 @@ export function registerMeta(program) {
             `  agent       ${ctx.urls.agent}\n` +
             ui.dim(`  creds       ${ctx.credsPath}`));
     });
-    config
-        .command("set-agent-key <key>")
-        .description("Link your agent key (grant_live_…)")
-        .action((key, _opts, cmd) => {
-        const ctx = buildContext(cmd);
-        const next = { ...ctx.creds, agent: { apiKey: key } };
-        ctx.save(next);
-        emit(ctx, { linked: true }, () => ui.green("✓ Agent key linked."));
-    });
     program
         .command("install")
         .description("Where to find the skill file + how to connect an assistant")

package/dist/cli/money-helpers.js

@@ -1,5 +1,5 @@
 import pc from "picocolors";
-import { PerfolioClient, AssetResolver, baseUrls, resolveCredsPath, loadCredentials, saveCredentials, openBrowser, waitForSign, resolveDisplayPrefs, DEFAULT_PREFS, resolveCashToUsd, resolveCashTargetToAssetQty, } from "../lib/index.js";
+import { PerfolioClient, AssetResolver, TokenHolder, refreshAccessToken, baseUrls, resolveCredsPath, loadCredentials, saveCredentials, openBrowser, waitForSign, resolveDisplayPrefs, DEFAULT_PREFS, resolveCashToUsd, resolveCashTargetToAssetQty, } from "../lib/index.js";
 import { waitForTx } from "../lib/verify.js";
 /** PerfolioClient needs a `widget` base; derive it from the API origin if unset. */
 function widgetUrl(api) {
@@ -10,18 +10,22 @@ export function buildCtx(cmd) {
     const credsPath = resolveCredsPath(opts.credsFile);
     const creds = loadCredentials(credsPath);
     const urls = baseUrls();
+    // Shared perfolio access JWT + refresh (unified auth). Persist rotated tokens
+    // into the `money` slot so a silent refresh survives across invocations.
+    const auth = new TokenHolder({
+        accessJwt: creds.money?.accessJwt,
+        refreshToken: creds.money?.refreshToken,
+        refresh: (rt) => refreshAccessToken(urls.api, rt),
+        onRefresh: ({ accessJwt, refreshToken, expiresAt }) => saveCredentials({ ...creds, money: { ...(creds.money ?? {}), accessJwt, refreshToken, expiresAt } }, credsPath),
+    });
     const client = new PerfolioClient({
         urls: { api: urls.api, fiat: urls.fiat, app: urls.app, widget: widgetUrl(urls.api) },
-        token: creds.money?.token,
-        refreshToken: creds.money?.refreshToken,
-        // Persist rotated tokens into the `money` slot so a silent refresh survives
-        // across invocations without disturbing the agent credential.
-        onRefresh: (token, refreshToken, expiresAt) => saveCredentials({ ...creds, money: { ...(creds.money ?? {}), token, refreshToken, expiresAt } }, credsPath),
+        auth,
     });
     return { client, creds, credsPath, json: Boolean(opts.json) };
 }
 export function requireAuth(ctx) {
-    if (!ctx.creds.money?.token) {
+    if (!ctx.creds.money?.accessJwt) {
         fail("Not connected. Run `grant login` first.", ctx.json);
     }
     return ctx.creds;

package/dist/lib/agent-client.js

@@ -2,10 +2,12 @@ import { AppError } from "./errors.js";
 /**
  * Agent side — the Agent-mode backend client (pay-per-use services, x402).
  *
- * Auth with a session-bound `X-API-Key` (`grant_live_`). The agent never holds a
- * private key; the backend's delegated, revocable, guardrailed session owns the
- * spend. Errors carry the backend's stable `err.code` + a `recoverable` flag so
- * a driving agent knows whether to retry (see SKILL.md error playbook).
+ * Auth with the shared perfolio access JWT (unified auth): `Authorization: Bearer
+ * <accessJwt>` — the SAME JWT the money client sends. A 401 triggers one shared
+ * refresh via the {@link TokenHolder} (used by both clients), then a single retry.
+ * The agent never holds a private key; the backend's delegated, revocable,
+ * guardrailed session owns the spend. Errors carry the backend's stable `err.code`
+ * + a `recoverable` flag so a driving agent knows whether to retry (see SKILL.md).
  */
 const REQUEST_TIMEOUT_MS = 60_000;
 /**
@@ -20,27 +22,31 @@ const RECOVERABLE_CODES = new Set([
 ]);
 export class AgentClient {
     base;
-    apiKey;
+    auth;
     f;
     constructor(opts) {
         this.base = opts.agent;
-        this.apiKey = opts.apiKey;
+        this.auth = opts.auth;
         this.f = opts.fetchImpl ?? fetch;
     }
     get connected() {
-        return Boolean(this.apiKey);
+        return Boolean(this.auth?.token);
     }
-    async request(method, path, opts = {}) {
+    async request(method, path, opts = {}, retried = false) {
         const headers = { Accept: "application/json" };
         if (opts.body !== undefined)
             headers["Content-Type"] = "application/json";
+        // Capture the token used for THIS request so the 401 path can detect whether
+        // another client already rotated it (then we just retry, no second refresh).
+        let usedToken;
         if (opts.auth) {
-            if (!this.apiKey)
+            usedToken = this.auth?.token;
+            if (!usedToken)
                 throw new AppError("Not connected to your agent yet. Run `grant login`.", {
                     code: "NOT_CONNECTED",
                     recoverable: false,
                 });
-            headers["X-API-Key"] = this.apiKey;
+            headers.Authorization = `Bearer ${usedToken}`;
         }
         if (opts.idempotent)
             headers["Idempotency-Key"] = randomId();
@@ -59,6 +65,12 @@ export class AgentClient {
                 recoverable: true,
             });
         }
+        // Silent refresh: an expired access JWT → shared refresh once, then retry.
+        if (res.status === 401 && opts.auth && !retried && this.auth) {
+            const fresh = await this.auth.refreshIfStale(usedToken);
+            if (fresh)
+                return this.request(method, path, opts, true);
+        }
         const json = (await res.json().catch(() => ({})));
         // A 4xx without the agent error envelope means we never reached the API
         // (wrong/dead base URL, platform edge 404). Point at the misconfig.

package/dist/lib/auth-session.js

@@ -0,0 +1,81 @@
+import { AppError } from "./errors.js";
+export class TokenHolder {
+    accessJwt;
+    refreshToken;
+    doRefresh;
+    onRefresh;
+    /** The in-flight refresh, if any — coalesces concurrent callers (single-flight). */
+    inFlight;
+    constructor(opts) {
+        this.accessJwt = opts.accessJwt;
+        this.refreshToken = opts.refreshToken;
+        this.doRefresh = opts.refresh;
+        this.onRefresh = opts.onRefresh;
+    }
+    /** The current access JWT to send as `Authorization: Bearer`. */
+    get token() {
+        return this.accessJwt;
+    }
+    /**
+     * Refresh only if the caller's token is still the live one. If another client
+     * already rotated the token (current !== usedToken), return the current token
+     * without a second refresh — the caller should just retry with it.
+     */
+    async refreshIfStale(usedToken) {
+        if (this.accessJwt && this.accessJwt !== usedToken)
+            return this.accessJwt;
+        return this.refresh();
+    }
+    /**
+     * Rotate the access JWT via the refresh token. Single-flight: concurrent calls
+     * share one network round-trip. Returns the new JWT, or `undefined` if there is
+     * no refresh token or the refresh failed (the old token is left in place).
+     */
+    refresh() {
+        if (this.inFlight)
+            return this.inFlight;
+        const rt = this.refreshToken;
+        if (!rt)
+            return Promise.resolve(undefined);
+        this.inFlight = (async () => {
+            try {
+                const tokens = await this.doRefresh(rt);
+                this.accessJwt = tokens.accessJwt;
+                this.refreshToken = tokens.refreshToken;
+                this.onRefresh?.(tokens);
+                return tokens.accessJwt;
+            }
+            catch {
+                return undefined;
+            }
+            finally {
+                this.inFlight = undefined;
+            }
+        })();
+        return this.inFlight;
+    }
+}
+/**
+ * `POST {api}/cli/token/refresh` — exchange a `pfr_` refresh token for a fresh
+ * perfolio access JWT. Per CONTRACT v1 the payload is `{ accessJwt, refreshToken,
+ * expiresAt }`; it arrives inside perfolio's standard `{ success, data }` envelope.
+ * The legacy `token` field is accepted as a fallback during the migration window.
+ */
+export async function refreshAccessToken(api, refreshToken, f = fetch) {
+    const res = await f(`${api}/cli/token/refresh`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ refreshToken }),
+    });
+    const j = (await res.json().catch(() => ({})));
+    const data = j.data ?? {};
+    const accessJwt = data.accessJwt ?? data.token;
+    if (!res.ok || j.success === false || !accessJwt) {
+        throw new AppError(j.error || "Refresh failed", { status: res.status, code: "REFRESH_FAILED" });
+    }
+    return {
+        accessJwt,
+        refreshToken: data.refreshToken ?? refreshToken,
+        expiresAt: typeof data.expiresAt === "number" ? data.expiresAt : 0,
+    };
+}

package/dist/lib/client.js

@@ -1,24 +1,19 @@
 import { NoSessionError } from './errors.js';
-import { refreshCliToken } from './device.js';
 /** Per-request network timeout. Generous enough for MEE submit, short enough to not hang. */
 const REQUEST_TIMEOUT_MS = 30_000;
 export class PerfolioClient {
     urls;
-    token;
-    refreshToken;
-    onRefresh;
+    auth;
     f;
     constructor(opts) {
         this.urls = opts.urls;
-        this.token = opts.token;
-        this.refreshToken = opts.refreshToken;
-        this.onRefresh = opts.onRefresh;
+        this.auth = opts.auth;
         this.f = opts.fetchImpl ?? fetch;
     }
-    headers(auth) {
+    headers(token, auth) {
         const h = { 'Content-Type': 'application/json' };
-        if (auth && this.token)
-            h.Authorization = `Bearer ${this.token}`;
+        if (auth && token)
+            h.Authorization = `Bearer ${token}`;
         return h;
     }
     /** fetch with an abort-based timeout + one retry on a transient network failure. */
@@ -44,23 +39,15 @@ export class PerfolioClient {
         }
     }
     async request(base, path, init, auth, retried = false) {
-        const res = await this.fetchWithTimeout(`${base}${path}`, { ...init, headers: this.headers(auth) });
-        // Silent refresh: an expired CLI access token (pfk_) → rotate once and retry.
-        if (res.status === 401 &&
-            auth &&
-            !retried &&
-            this.refreshToken &&
-            this.token?.startsWith('pfk_')) {
-            try {
-                const t = await refreshCliToken(this.urls.api, this.refreshToken, this.f);
-                this.token = t.token;
-                this.refreshToken = t.refreshToken;
-                this.onRefresh?.(t.token, t.refreshToken, t.expiresAt);
+        // Capture the token used for THIS request so the 401 path can detect whether
+        // another client already rotated it (then we just retry, no second refresh).
+        const usedToken = auth ? this.auth?.token : undefined;
+        const res = await this.fetchWithTimeout(`${base}${path}`, { ...init, headers: this.headers(usedToken, auth) });
+        // Silent refresh: an expired access JWT → shared refresh once, then retry.
+        if (res.status === 401 && auth && !retried && this.auth) {
+            const fresh = await this.auth.refreshIfStale(usedToken);
+            if (fresh)
                 return this.request(base, path, init, auth, true);
-            }
-            catch {
-                /* refresh failed — fall through to the normal error below */
-            }
         }
         let json = { success: false };
         try {

package/dist/lib/context.js

@@ -1,6 +1,7 @@
 import { baseUrls, resolveCredsPath, loadCredentials, saveCredentials, } from "./config.js";
 import { MoneyClient } from "./money-client.js";
 import { AgentClient } from "./agent-client.js";
+import { TokenHolder, refreshAccessToken } from "./auth-session.js";
 import { isJsonMode } from "./output.js";
 export function buildContext(cmd) {
     // Global opts live on the root program; optsWithGlobals merges them in.
@@ -13,23 +14,21 @@ export function buildContext(cmd) {
         saveCredentials(next, credsPath);
         ctx.creds = next;
     };
-    const money = new MoneyClient({
-        api: urls.api,
-        fiat: urls.fiat,
-        token: creds.money?.token,
+    // One JWT, one refresh, shared by both backend clients (CONTRACT v1).
+    const auth = new TokenHolder({
+        accessJwt: creds.money?.accessJwt,
         refreshToken: creds.money?.refreshToken,
-        onRefresh: (token, refreshToken, expiresAt) => {
+        refresh: (rt) => refreshAccessToken(urls.api, rt),
+        onRefresh: ({ accessJwt, refreshToken, expiresAt }) => {
             const next = {
                 ...ctx.creds,
-                money: { ...ctx.creds.money, token, refreshToken, expiresAt },
+                money: { ...ctx.creds.money, accessJwt, refreshToken, expiresAt },
             };
             save(next);
         },
     });
-    const agent = new AgentClient({
-        agent: urls.agent,
-        apiKey: creds.agent?.apiKey,
-    });
+    const money = new MoneyClient({ api: urls.api, fiat: urls.fiat, auth });
+    const agent = new AgentClient({ agent: urls.agent, auth });
     const ctx = { urls, creds, credsPath, json, money, agent, save };
     return ctx;
 }

package/dist/lib/index.js

@@ -4,7 +4,7 @@ export * from "./dotenv.js";
 export * from "./errors.js";
 export * from "./output.js";
 export * from "./device.js";
-export * from "./agent-device.js";
+export * from "./auth-session.js";
 export * from "./money-client.js";
 export * from "./agent-client.js";
 export * from "./tx-wait.js";

package/dist/lib/money-client.js

@@ -1,36 +1,31 @@
 import { AppError, NoSessionError } from "./errors.js";
-import { refreshCliToken } from "./device.js";
 /**
  * Money side — the Perfolio backend client (gold, portfolio, cash).
  *
- * Bearer auth with a `pfk_` device token; transparently refreshes once on a 401
- * using the refresh token, then persists the rotated pair via onRefresh. Kept
- * deliberately gold-focused per the product scope; adding borrow/earn/perps
- * endpoints later is a one-line method each.
+ * Bearer auth with the shared perfolio access JWT (unified auth): a 401 triggers
+ * one shared refresh via the {@link TokenHolder} (used by BOTH backend clients),
+ * then the request is retried with the new JWT. Kept deliberately gold-focused per
+ * the product scope; adding borrow/earn/perps endpoints later is a one-line method.
  */
 const REQUEST_TIMEOUT_MS = 30_000;
 export class MoneyClient {
     api;
     fiat;
-    token;
-    refreshToken;
-    onRefresh;
+    auth;
     f;
     constructor(opts) {
         this.api = opts.api;
         this.fiat = opts.fiat;
-        this.token = opts.token;
-        this.refreshToken = opts.refreshToken;
-        this.onRefresh = opts.onRefresh;
+        this.auth = opts.auth;
         this.f = opts.fetchImpl ?? fetch;
     }
     get connected() {
-        return Boolean(this.token);
+        return Boolean(this.auth?.token);
     }
-    headers(auth) {
+    headers(token, auth) {
         const h = { "Content-Type": "application/json" };
-        if (auth && this.token)
-            h.Authorization = `Bearer ${this.token}`;
+        if (auth && token)
+            h.Authorization = `Bearer ${token}`;
         return h;
     }
     async fetchWithTimeout(url, init) {
@@ -53,26 +48,18 @@ export class MoneyClient {
         }
     }
     async request(base, path, init, auth, retried = false) {
+        // Capture the token used for THIS request so the 401 path can detect whether
+        // another client already rotated it (then we just retry, no second refresh).
+        const usedToken = auth ? this.auth?.token : undefined;
         const res = await this.fetchWithTimeout(`${base}${path}`, {
             ...init,
-            headers: this.headers(auth),
+            headers: this.headers(usedToken, auth),
         });
-        // Silent refresh: an expired pfk_ access token → rotate once and retry.
-        if (res.status === 401 &&
-            auth &&
-            !retried &&
-            this.refreshToken &&
-            this.token?.startsWith("pfk_")) {
-            try {
-                const t = await refreshCliToken(this.api, this.refreshToken, this.f);
-                this.token = t.token;
-                this.refreshToken = t.refreshToken;
-                this.onRefresh?.(t.token, t.refreshToken, t.expiresAt);
+        // Silent refresh: an expired access JWT → shared refresh once, then retry.
+        if (res.status === 401 && auth && !retried && this.auth) {
+            const fresh = await this.auth.refreshIfStale(usedToken);
+            if (fresh)
                 return this.request(base, path, init, auth, true);
-            }
-            catch {
-                /* fall through to the normal error */
-            }
         }
         let json = {};
         try {

package/dist/lib/types.js

@@ -1,10 +1,11 @@
 /**
  * Shared types for the merged Grant Cash CLI.
  *
- * Two engines, one identity (one Privy app underneath): the MONEY side
- * (Perfolio backend — gold, portfolio, cash) authenticates with a Bearer
- * device token (`pfk_`), and the AGENT side (Agent-mode backend — pay-per-use
- * services) authenticates with an `X-API-Key` (`grant_live_`). Both credentials
- * live in one file so a single `grant login` connects everything.
+ * One identity, one credential (unified auth): `grant login` runs a single
+ * perfolio device flow and stores the perfolio-signed access JWT (`accessJwt`)
+ * plus the opaque `pfr_` refresh token. That ONE JWT is sent as
+ * `Authorization: Bearer <accessJwt>` to BOTH backends — the MONEY side
+ * (Perfolio — gold, portfolio, cash) and the AGENT side (Agent-mode — pay-per-use
+ * services). The retired `grant_live_` X-API-Key path is gone.
  */
 export {};

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@agentgrant.cash/cli",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "description": "Grant Cash — one CLI for your money (gold) and your agent (pay-per-use services). Routes to the Perfolio backend and the Agent-mode backend behind a single, plain-language surface.",
   "type": "module",
   "bin": {
-    "grant": "./dist/cli/index.js"
+    "grant": "./dist/cli/index.js",
+    "cli": "./dist/cli/index.js"
   },
   "files": [
     "dist",

package/dist/lib/agent-device.js

@@ -1,173 +0,0 @@
-import { createHash, randomBytes } from "node:crypto";
-import { AppError } from "./errors.js";
-/**
- * Generate a PKCE S256 pair. The verifier is 43 base64url chars (32 random
- * bytes), well within RFC 7636's 43–128 range.
- */
-export function generatePkce() {
-    const verifier = base64url(randomBytes(32)); // 32 bytes → 43 base64url chars
-    const challenge = base64url(createHash("sha256").update(verifier).digest());
-    return { verifier, challenge, method: "S256" };
-}
-function base64url(buf) {
-    return buf
-        .toString("base64")
-        .replace(/\+/g, "-")
-        .replace(/\//g, "_")
-        .replace(/=+$/, "");
-}
-const JSON_HEADERS = { "Content-Type": "application/json", Accept: "application/json" };
-/**
- * POST /onboard/privy-cli/device/start — open the agent-side handshake.
- * Sends only the public challenge; keep the returned `sid` paired with the
- * verifier from the same {@link generatePkce} call.
- */
-export async function startAgentDevice(agent, pkce, clientName, f = fetch) {
-    const base = agent.replace(/\/$/, "");
-    let res;
-    try {
-        res = await f(`${base}/onboard/privy-cli/device/start`, {
-            method: "POST",
-            headers: JSON_HEADERS,
-            body: JSON.stringify({
-                clientName,
-                code_challenge: pkce.challenge,
-                code_challenge_method: pkce.method,
-            }),
-        });
-    }
-    catch (e) {
-        throw new AppError(e instanceof Error ? e.message : String(e), {
-            code: "NETWORK",
-            recoverable: true,
-        });
-    }
-    const j = (await res.json().catch(() => ({})));
-    // A 4xx without a recognizable body means we never reached the agent API
-    // (wrong/dead base URL) — point at the misconfig, same as AgentClient.
-    if (res.status >= 400 && res.status < 500 && !j?.sid) {
-        throw new AppError(`No Grant Cash agent API at ${base} (HTTP ${res.status}) — check GRANTCASH_AGENT_URL.`, { status: res.status, code: "BACKEND_UNREACHABLE", recoverable: false });
-    }
-    if (!res.ok || !j?.sid) {
-        throw new AppError(j?.error?.message || `Could not start spending setup (HTTP ${res.status})`, { status: res.status, code: j?.error?.code ?? "AGENT_DEVICE_START_FAILED" });
-    }
-    return {
-        sid: j.sid,
-        pollInterval: typeof j.pollInterval === "number" ? j.pollInterval : 3,
-        expiresIn: typeof j.expiresIn === "number" ? j.expiresIn : 300,
-    };
-}
-/**
- * POST /onboard/privy-cli/device/poll — one poll with the secret verifier.
- *
- * Resolves a single tick:
- *   - 200 { status:"pending" | "complete" | "expired" } → returned as-is
- *     (complete may omit `apiKey` = already provisioned → keep existing key).
- *   - 401 PRIVY_DEVICE_PKCE_FAILED → throw (terminal; the verifier was rejected).
- *   - 429 → throw a RATE_LIMITED AppError carrying `retryInMs` from details so
- *     {@link waitForAgentDevice} can back off instead of hammering.
- */
-export async function pollAgentDevice(agent, sid, verifier, f = fetch) {
-    const base = agent.replace(/\/$/, "");
-    let res;
-    try {
-        res = await f(`${base}/onboard/privy-cli/device/poll`, {
-            method: "POST",
-            headers: JSON_HEADERS,
-            body: JSON.stringify({ sid, code_verifier: verifier }),
-        });
-    }
-    catch (e) {
-        throw new AppError(e instanceof Error ? e.message : String(e), {
-            code: "NETWORK",
-            recoverable: true,
-        });
-    }
-    const j = (await res.json().catch(() => ({})));
-    if (res.status === 429) {
-        const retryInMs = j?.details?.retryInMs;
-        throw new AppError("Too many attempts — backing off.", {
-            status: 429,
-            code: "RATE_LIMITED",
-            recoverable: true,
-            details: retryInMs ? { retryInMs } : undefined,
-        });
-    }
-    if (res.status === 401) {
-        throw new AppError(j?.error?.message || "Spending setup could not be verified (PKCE check failed).", {
-            status: 401,
-            code: j?.error?.code || j?.code || "PRIVY_DEVICE_PKCE_FAILED",
-            recoverable: false,
-        });
-    }
-    if (!res.ok) {
-        throw new AppError(j?.error?.message || `Spending poll failed (HTTP ${res.status})`, {
-            status: res.status,
-            code: j?.error?.code ?? `HTTP_${res.status}`,
-            recoverable: res.status >= 500,
-        });
-    }
-    if (j.status === "complete") {
-        return { status: "complete", apiKey: j.apiKey, sessionStatus: j.sessionStatus };
-    }
-    if (j.status === "expired")
-        return { status: "expired" };
-    return { status: "pending" };
-}
-/**
- * Poll the agent device until a terminal status or the link expires.
- *
- * Never throws on the network/rate-limit path: a transient network blip or a
- * 429 (honoring `details.retryInMs`) just backs off and retries within the
- * window. A 401 PRIVY_DEVICE_PKCE_FAILED is terminal and DOES propagate. On
- * window exhaustion returns `{ status: "expired" }`.
- */
-export async function waitForAgentDevice(agent, sid, verifier, intervalMs, timeoutMs, f = fetch, signal) {
-    // When a signal is supplied, thread it into each fetch AND check it in the
-    // loop guard — so `grant login` can stop waiting on the best-effort spending
-    // side the moment money (the primary identity) settles, instead of letting
-    // this loop keep the process alive until the full timeout.
-    const ff = signal
-        ? ((input, init) => f(input, { ...init, signal }))
-        : f;
-    const start = Date.now();
-    while (!signal?.aborted && Date.now() - start < timeoutMs) {
-        try {
-            const r = await pollAgentDevice(agent, sid, verifier, ff);
-            if (r.status !== "pending")
-                return r;
-            await sleep(intervalMs);
-        }
-        catch (e) {
-            if (signal?.aborted)
-                break;
-            const err = e;
-            // PKCE failure is terminal — surface it.
-            if (err?.code === "PRIVY_DEVICE_PKCE_FAILED")
-                throw err;
-            // Rate-limited: back off by the server hint (or the normal interval).
-            if (err?.code === "RATE_LIMITED") {
-                const retryInMs = err.details?.retryInMs ?? intervalMs;
-                await sleep(Math.max(intervalMs, retryInMs));
-                continue;
-            }
-            // Transient network error: wait one interval and retry within the window.
-            await sleep(intervalMs);
-        }
-    }
-    return { status: "expired" };
-}
-function sleep(ms) {
-    return new Promise((res) => setTimeout(res, ms));
-}
-/**
- * Resolve the agent-side poll interval in MILLISECONDS.
- *
- * The Agent-mode backend (`onboard/privy-cli/device/start`) reports
- * `pollInterval` in SECONDS (e.g. 2), so it is multiplied by 1000. This differs
- * from the money backend, which already reports milliseconds (see
- * `moneyPollIntervalMs` in `device.ts`). Falls back to 3s.
- */
-export function agentPollIntervalMs(pollInterval) {
-    return (typeof pollInterval === "number" && pollInterval > 0 ? pollInterval : 3) * 1000;
-}