@thirdfy/agent-cli 0.4.3 → 0.5.0

package/CHANGELOG.md

@@ -2,7 +2,50 @@
 
 All notable changes to `@thirdfy/agent-cli` are documented here. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## Unreleased
+## [0.5.0] - 2026-10-15
+
+`thirdfy-agent login` signs in with OAuth in the browser (auth.thirdfy.com, the same sign-in the MCP uses), as one agent with read access, plus trade with `--trade`. A minor version because `login` without a token flag now starts that sign-in instead of failing, and `credits balance` / `pricing quote` drop their credit counts for USD. `login email`, token flags and agent API keys work as before.
+
+### Removed
+
+- **The ignored Bitfinex flags of `credentials upsert`** (`--permission-profile`, `--verify-permissions`, `--skip-permissions-probe`, `--bitfinex-base-url`), as 0.4.3's warning announced (THI-86). Passing one is now an unknown-option error. Drop them from scripts.
+
+### Added
+
+- **`thirdfy-agent login` signs in with OAuth** (THI-107, part of THI-104): auth.thirdfy.com, the same sign-in the MCP uses. With no token flag, `login` does this:
+  - opens the browser (`--no-browser` prints the URL);
+  - the owner picks one agent and approves read (plus trade with `--trade`);
+  - the browser returns to a one-time `127.0.0.1` listener;
+  - the CLI is a public client (registered once per server), and uses PKCE S256 and `resource` = the API.
+
+  How the sign-in is used:
+  - **Credential:** it's stored in `auth.oauth` and becomes the agent credential: after `--agent-api-key` and `THIRDFY_AGENT_API_KEY`, before config `agent.apiKey` and before stored owner auth for credits reads.
+  - **Agent:** its agent comes from the API (`GET /api/v1/agent/oauth/session`).
+  - **Requests:** they send `Authorization: Bearer`, refresh before expiry (rotation), and refresh and retry once after a 401.
+  - **Expiry:** a refused refresh is `OAUTH_SESSION_EXPIRED` (`nextAction: reauthenticate`).
+  - **`logout`** revokes the sign-in at the auth server.
+  - **`whoami`** shows `auth.oauth`.
+  - New next actions: `reauthenticate`, `reauthenticate_with_trade`.
+
+  Needs thirdfy/thirdfy-auth#15 (the API as a resource, token introspection) and the API change THI-106. Until both are live, `login` stops at `OAUTH_RESOURCE_NOT_SUPPORTED` and points to `login email`. `login email` and token flags work as before.
+
+### Changed
+
+- **`credits balance` and `pricing quote` show balances in USD, never credits** (THI-123; same rules as thirdfy/thirdfy-mcp#279). Credits are Thirdfy's internal unit, and no price per action or request is stated.
+  - **Kept:** `availableUsd`, the free request counts (`freeDailyLimit`, `freeRequestsRemainingToday`, ...), `wouldBePaidBy` and `displayCurrency`.
+  - **Owner's fallback:** `ownerCreditsFallback` gets `availableUsd`, at the API's own `retailUsdPerCredit` from the same response, rounded to cents.
+  - **Dropped:** every credit count, per-credit rate and per-action price (`balanceCredits`, `balance`, `totalEarned`, `totalSpent`, `creditUsdValue`, `retailUsdPerCredit`, `quote.creditsCost`, `chargedUsd`, ...).
+  - **Text output:** without `--json`, `credits balance` reads `Balance loaded: $4.20 left; 8 of 20 free requests left today; then the owner's balance ($86.22) pays; then top up the balance.` The `note` says the same in USD. `pricing quote` reads `Action checked; would be paid by the owner's balance (owner_credits)`.
+  - **Unchanged:** the owner reports `credits transactions`, `credits usage`, `models list` and `models estimate` (credit ledger lines), as the MCP left its owner-token credits tools.
+  - **Owner ledger:** `totalAvailable` (a credit count) and `currency: 'credits'` are dropped too, and the owner route's free counts (`freeAllowance`, `freeRemainingToday`) are read, so owner auth also prints the free requests left.
+  - Before (0.4.3 and earlier) `credits balance` returned only `balanceCredits` and `ownerCreditsFallback.balanceCredits`, so a model answered in credits.
+- **A proper "signed in" page after `thirdfy-agent login`.** The local listener used to answer the browser with a bare, unbranded page. Like Claude Code, GitHub CLI and Google Cloud CLI, it now:
+  - holds the browser until the CLI has its tokens and knows its agent;
+  - then sends it to the sign-in server's result page, `<issuer>/cli/signed-in`, with the agent, read or trade access, and the API (auth.thirdfy.com 0.5.1+);
+  - on a cancelled or failed sign-in, sends it to `<issuer>/cli/error`.
+
+  A sign-in server without those pages gets a built-in page in the same style.
+- **A sign-in is used only on the API it was issued for**: an api-test sign-in is never sent to production, or the reverse. `whoami` shows `auth.oauth.resource` and `activeForThisApi`.
 
 ## [0.4.3] - 2026-10-14
 

package/README.md

@@ -39,11 +39,11 @@ Run without global install:
 npx @thirdfy/agent-cli --help
 ```
 
-## What's new in v0.4.3
+## What's new in v0.5.0
 
-- **Local signing works again:** ethers now loads, so `doctor self`, OWS sign-and-broadcast, `wallet submit` and the self lane's balance checks run as documented.
-- **A dead RPC is one clear error:** every RPC call is pinned to its chain, so an unreachable RPC no longer prints retry lines into `--json` output or keeps the command running.
-- **Bitfinex support removed from the CLI:** no Bitfinex provider hint, credential permission probe or docs any more. The Thirdfy API still serves the Bitfinex actions for now. `credentials upsert` still works for the other venues, and its old Bitfinex flags are accepted and ignored with a warning.
+- **Sign in with your Thirdfy account:** `thirdfy-agent login` opens your browser at auth.thirdfy.com. You pick one agent and approve read access, and trade access with `thirdfy-agent login --trade`. The CLI then acts as that agent, refreshes the sign-in by itself, and `thirdfy-agent logout` revokes it. Disconnect it any time in Connected apps at auth.thirdfy.com.
+- **Same sign-in as the MCP:** the same consent page and the same Connected apps list as Claude, ChatGPT and Cursor.
+- **Nothing else changes:** `login email`, `--auth-token`, `--owner-session-token` and agent API keys work as before, and an explicit `--agent-api-key` always wins over the sign-in.
 - Older versions: see [CHANGELOG.md](./CHANGELOG.md).
 
 ## Quick start

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thirdfy/agent-cli",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "description": "Thirdfy Agent CLI for onboarding, governance preflight, execute-intent, and status polling.",
   "type": "module",
   "bin": {
@@ -23,7 +23,7 @@
   ],
   "scripts": {
     "test": "node --test test/*/*.test.cjs test/*/*/*.test.cjs",
-    "lint": "node --check ./bin/thirdfy-agent.mjs && node --check ./src/core/*.mjs && node --check ./src/core/execution/*.mjs && node --check ./src/commands/*.mjs && node --check ./src/commands/venues/*.mjs && node --check ./src/commands/onboarding/*.mjs && node --check ./src/commands/account/*.mjs && node --check ./src/commands/signals/*.mjs && node --check ./src/cli/*.mjs && node --check ./src/cli/options/*.mjs && node --check ./src/cli/options/venues/*.mjs && node --check ./src/cli/options/onboarding/*.mjs && node --check ./src/cli/options/account/*.mjs && node --check ./src/runtime/*.mjs && node --check ./src/runtime/execution/*.mjs && node --check ./src/runtime/execution/runners/*.mjs && node --check ./src/runtime/actions/*.mjs && node --check ./src/runtime/validation/*.mjs && node --check ./src/runtime/certification/*.mjs && node --check ./src/runtime/providerHints/*.mjs && node --check ./src/runtime/risk/*.mjs",
+    "lint": "node --check ./bin/thirdfy-agent.mjs && node --check ./src/core/*.mjs && node --check ./src/core/execution/*.mjs && node --check ./src/core/oauth/*.mjs && node --check ./src/commands/*.mjs && node --check ./src/commands/venues/*.mjs && node --check ./src/commands/onboarding/*.mjs && node --check ./src/commands/account/*.mjs && node --check ./src/commands/signals/*.mjs && node --check ./src/cli/*.mjs && node --check ./src/cli/options/*.mjs && node --check ./src/cli/options/venues/*.mjs && node --check ./src/cli/options/onboarding/*.mjs && node --check ./src/cli/options/account/*.mjs && node --check ./src/runtime/*.mjs && node --check ./src/runtime/execution/*.mjs && node --check ./src/runtime/execution/runners/*.mjs && node --check ./src/runtime/actions/*.mjs && node --check ./src/runtime/validation/*.mjs && node --check ./src/runtime/certification/*.mjs && node --check ./src/runtime/providerHints/*.mjs && node --check ./src/runtime/risk/*.mjs",
     "validate:cli-manifest-handlers": "node ./scripts/validate-cli-manifest-handlers.mjs",
     "validate:runtime-boundaries": "node ./scripts/validate-runtime-boundaries.mjs",
     "validate:npm-pack": "node ./scripts/validate-npm-pack.mjs",

package/src/cli/help.mjs

@@ -7,6 +7,7 @@ Core commands:
   thirdfy-agent profile use --profile <name> [--run-mode thirdfy|self|hybrid|agent_wallet] [--custody-mode managed|external] [--json]
   thirdfy-agent profile show [--json]
   thirdfy-agent config set --key <path> --value <value> [--json]
+  thirdfy-agent login [--trade] [--no-browser] [--issuer <url>] [--json]   (OAuth in the browser: one agent)
   thirdfy-agent login [--auth-token <token> | --owner-session-token <token>] [--agent-api-key <key>] [--agent-key <key>] [--run-mode <mode>] [--custody-mode managed|external] [--wallet-address <addr>] [--json]
   thirdfy-agent login email <address> [--code <otp>] [--accept-terms] [--key-name <name>] [--agent-key <key>] [--not-interactive|--ni] [--json]
   thirdfy-agent logout [--all] [--clear-agent-key] [--json]

package/src/cli/manifest.mjs

@@ -47,8 +47,8 @@ export const CLI_MANIFEST = [
   {
     path: ['login'],
     handler: 'commandLogin',
-    options: ['auth', 'bootstrap'],
-    description: 'Login with auth token, owner session, or agent API key',
+    options: ['auth', 'bootstrap', 'oauthLogin'],
+    description: 'Sign in with OAuth in the browser (one agent; --trade for writes), or with an auth token, owner session or agent API key',
   },
   {
     path: ['login', 'email'],
@@ -212,7 +212,7 @@ export const CLI_MANIFEST = [
     handler: 'commandCreditsBalance',
     tier: 'online',
     options: ['auth'],
-    description: 'Credits balance',
+    description: 'Balance in USD, free requests today and who pays next',
   },
   {
     path: ['credits', 'buy'],
@@ -254,7 +254,7 @@ export const CLI_MANIFEST = [
     handler: 'commandPricingQuote',
     tier: 'online',
     options: ['auth', 'execution'],
-    description: 'Quote action-tier credits for a catalog action',
+    description: 'Check who would pay for a catalog action now (never a price)',
   },
   {
     path: ['chat', 'send'],

package/src/cli/options/index.mjs

@@ -6,6 +6,7 @@ import { attachTrackingOptions } from './tracking.mjs';
 import { attachWalletOptions } from './account/wallet.mjs';
 import { attachBootstrapOptions, attachOnboardingHelpOptions } from './onboarding/bootstrap.mjs';
 import { attachCredentialsOptions } from './onboarding/credentials.mjs';
+import { attachOAuthLoginOptions } from './onboarding/oauthLogin.mjs';
 import { attachAnalyticsOptions } from './analytics.mjs';
 import { attachPolymarketOptions } from './venues/polymarket.mjs';
 import { attachHummingbotOptions } from './venues/hummingbot.mjs';
@@ -27,6 +28,7 @@ const BUNDLES = {
   tracking: attachTrackingOptions,
   wallet: attachWalletOptions,
   bootstrap: attachBootstrapOptions,
+  oauthLogin: attachOAuthLoginOptions,
   onboardingHelp: attachOnboardingHelpOptions,
   credentials: attachCredentialsOptions,
   analytics: attachAnalyticsOptions,

package/src/cli/options/onboarding/credentials.mjs

@@ -7,11 +7,5 @@ export function attachCredentialsOptions(cmd) {
     .option('--credential-type <type>', 'credential type')
     .option('--passphrase <value>', 'exchange passphrase')
     .option('--metadata <json>', 'credential metadata JSON')
-    .option('--policy <json>', 'credential policy JSON')
-    // Accepted and ignored since Bitfinex support was removed, so older scripts keep working; the
-    // command says so in meta.warnings. Drop them in the next minor version.
-    .option('--permission-profile <profile>', 'ignored (Bitfinex support was removed)')
-    .option('--verify-permissions', 'ignored (Bitfinex support was removed)')
-    .option('--skip-permissions-probe', 'ignored (Bitfinex support was removed)')
-    .option('--bitfinex-base-url <url>', 'ignored (Bitfinex support was removed)');
+    .option('--policy <json>', 'credential policy JSON');
 }

package/src/cli/options/onboarding/oauthLogin.mjs

@@ -0,0 +1,8 @@
+/** `thirdfy-agent login` with OAuth (auth.thirdfy.com), the default when no token flag is passed. */
+export function attachOAuthLoginOptions(cmd) {
+  return cmd
+    .option('--trade', 'also ask for trade access (writes that move funds); read-only otherwise')
+    .option('--no-browser', 'print the sign-in URL instead of opening the browser')
+    .option('--issuer <url>', 'sign-in server (default: paired with --api-base, https://auth.thirdfy.com)')
+    .option('--login-timeout <seconds>', 'how long to wait for the browser sign-in (default 300)');
+}

package/src/commands/account/credits.mjs

@@ -6,7 +6,8 @@ import { toAvantisSpelling } from '../../core/venueBrand.mjs';
 import {
   formatCreditsEstimateSummary,
   formatCreditsModelsSummary,
-  stripUsdFields,
+  describeWouldBePaidBy,
+  toUsdFirst,
 } from '../../lib/creditsUsdSummary.mjs';
 
 function resolveToolCallsEstimate(flags) {
@@ -146,12 +147,13 @@ export function createCreditsCommands({ printEnvelope, getAuthToken, buildOwnerA
   }
 
   /**
-   * `pricing quote --action <id>`: the credits one catalog action costs, and `wouldBePaidBy`
-   * (agent_credits | free_request | owner_credits | none) when the API can read the balances
+   * `pricing quote --action <id>`: whether one catalog action can run now and who pays for it:
+   * `wouldBePaidBy` (agent_credits | free_request | owner_credits | none) when the API can read the balances
    * (thirdfy-api-v2#887). The ledger follows `resolveCreditsLedger`. Agent: `POST /agent/credits/quote`
    * with the agent's key. Owner (session token or auth token): `/credits/pricing/quote`, for one of the
    * owner's agents with --agent-key. An API without the agent route (404, before #887) is quoted
-   * through the owner route when owner auth is set and --agent-key names the key's agent. Credits only.
+   * through the owner route when owner auth is set and --agent-key names the key's agent. Never a price:
+   * the quote's credit cost and USD figures are dropped (thirdfy-mcp quoteActionPricing, thirdfy-mcp#279).
    */
   async function commandPricingQuote(ctx, flags) {
     const action = requireFlag(flags, 'action', 'Missing --action for pricing quote');
@@ -210,9 +212,9 @@ export function createCreditsCommands({ printEnvelope, getAuthToken, buildOwnerA
       success: true,
       code: 'OK',
       // wouldBePaidBy (agent_credits | free_request | owner_credits | none), when the API sends it.
-      message: response?.wouldBePaidBy ? `Action pricing quote generated; would be paid by ${response.wouldBePaidBy}` : 'Action pricing quote generated',
-      // An action's cost is in credits only, never dollars (thirdfy-mcp quoteActionPricing).
-      data: stripUsdFields(response),
+      message: response?.wouldBePaidBy ? `Action checked; would be paid by ${describeWouldBePaidBy(response.wouldBePaidBy)}` : 'Action checked',
+      // No price per action or request: no credit cost, rate or USD figure (thirdfy-mcp quoteActionPricing).
+      data: toUsdFirst(response),
       meta: {
         apiBase: ctx.apiBase,
         action,

package/src/commands/discovery.mjs

@@ -2,7 +2,7 @@ import { requireFlag, parseJsonFlag } from '../core/args.mjs';
 import { apiGet, apiPost } from '../core/http.mjs';
 import { extractActions, getCachedActionsCatalogSnapshot, resolveCreditsLedger } from '../core/context.mjs';
 import { getEffectiveRunMode } from '../core/runMode.mjs';
-import { creditsFreeQuotaNote, formatCreditsBalanceSummary, stripUsdFields } from '../lib/creditsUsdSummary.mjs';
+import { creditsFreeQuotaNote, formatCreditsBalanceSummary, toUsdFirst } from '../lib/creditsUsdSummary.mjs';
 import { filterActionsByChain } from '../runtime/actions/chainFilter.mjs';
 import { pageActionList, readActionListPaging } from '../runtime/actions/actionList.mjs';
 import {
@@ -186,7 +186,8 @@ async function commandChains(ctx, flags, capabilities) {
  * `credits balance`. Owner auth reads the owner's balance (`/credits/balance`). An explicit
  * --agent-api-key, or no owner auth but an agent key in env or config, reads the agent's own ledger
  * (`/agent/credits/balance`: its credits, free requests today and the owner-credits fallback), as
- * thirdfy-mcp getCreditsBalance. Credits only, never dollars.
+ * thirdfy-mcp getCreditsBalance. In USD, never credits: `availableUsd` (the owner's fallback too, at the
+ * API's `retailUsdPerCredit`), free requests and who pays; no credit count, rate or price (thirdfy-mcp#279).
  */
 async function commandCreditsBalance(ctx, flags, capabilities) {
   const { ledger, agentApiKey } = resolveCreditsLedger(flags);
@@ -203,9 +204,9 @@ async function commandCreditsBalance(ctx, flags, capabilities) {
   printEnvelope({
     success: true,
     code: 'OK',
-    message: flags.json ? 'Credits balance loaded' : `Credits balance loaded: ${summary}`,
-    // Credits only: no USD price per credit (thirdfy-mcp getCreditsBalance).
-    data: { ...stripUsdFields(response), ...(note ? { note } : {}) },
+    message: flags.json ? 'Balance loaded' : `Balance loaded: ${summary}`,
+    // USD-first: balances in USD, no credit count, per-credit rate or price (thirdfy-mcp getCreditsBalance).
+    data: { ...toUsdFirst(response), ...(note ? { note } : {}) },
     meta: {
       apiBase: ctx.apiBase,
       ledger: agentLedger ? 'agent' : 'owner',

package/src/commands/onboarding/bootstrap.mjs

@@ -17,6 +17,9 @@ import {
 } from '../../core/context.mjs';
 import { apiGet, apiPost, requestWithRouteFallback } from '../../core/http.mjs';
 import { isEvmAddress, isSolanaAddress } from '../../core/chainRegistry.mjs';
+import { commandOAuthLogin } from './oauthLogin.mjs';
+import { readOAuthSession } from '../../core/oauth/session.mjs';
+import { revokeToken } from '../../core/oauth/authServer.mjs';
 import { createRequire } from 'module';
 
 const require = createRequire(import.meta.url);
@@ -35,6 +38,7 @@ export function createBootstrapCommands(deps) {
     verifyOwnerWalletChallenge,
     resolveEffectiveUserDid,
     negotiateCapabilities,
+    CLI_VERSION,
     commandAgentRegister,
   } = deps;
 
@@ -232,6 +236,19 @@ async function commandWhoami(ctx, flags) {
         hasOwnerSessionToken: Boolean(auth.ownerSessionToken),
         ownerSessionToken: maskSecret(auth.ownerSessionToken),
         ownerSessionExpiresAt: auth.ownerSessionExpiresAt || null,
+        oauth: readOAuthSession(config)
+          ? {
+              issuer: auth.oauth.issuer || null,
+              // The API this sign-in is for; commands use it only on that API (--api-base).
+              resource: auth.oauth.resource || null,
+              activeForThisApi: String(auth.oauth.resource || '').replace(/\/+$/, '') === String(ctx.apiBase || '').replace(/\/+$/, ''),
+              agentKey: auth.oauth.agentKey || null,
+              scope: auth.oauth.scope || '',
+              canTrade: auth.oauth.canTrade === true,
+              expiresAt: auth.oauth.expiresAt || null,
+              accessToken: maskSecret(auth.oauth.accessToken),
+            }
+          : null,
       },
       agent: {
         hasAgentApiKey: Boolean(agent.apiKey),
@@ -272,6 +289,12 @@ async function commandLogin(ctx, flags) {
   );
   let loginSource = 'token';
 
+  // No token and no wallet-signature inputs: sign in with OAuth in the browser (THI-104).
+  const hasChallengeInputs = Boolean(String(flags.challengeId || '').trim() && String(flags.signature || '').trim());
+  if (!authToken && !ownerSessionToken && !hasChallengeInputs) {
+    return commandOAuthLogin(ctx, flags, { printEnvelope, version: CLI_VERSION });
+  }
+
   if (!authToken && !ownerSessionToken) {
     const challengeId = String(flags.challengeId || '').trim();
     const signature = String(flags.signature || '').trim();
@@ -611,6 +634,17 @@ async function commandLogout(ctx, flags) {
     }
   }
 
+  // An OAuth sign-in is revoked at the auth server (RFC 7009), so its tokens stop working
+  // everywhere, not only on this machine. Best effort: local credentials are cleared either way.
+  const oauthSession = readOAuthSession(current);
+  let oauthRevoked = null;
+  if (oauthSession) {
+    const revoke = (token) =>
+      revokeToken({ revocationEndpoint: oauthSession.revocationEndpoint, clientId: oauthSession.clientId, token }, ctx.timeoutMs || 30_000);
+    const [refresh, access] = await Promise.all([revoke(oauthSession.refreshToken), revoke(oauthSession.accessToken)]);
+    oauthRevoked = Boolean(refresh || access);
+  }
+
   const next = { ...current };
   delete next.auth;
   if (flags.clearAgentKey) {
@@ -626,6 +660,7 @@ async function commandLogout(ctx, flags) {
       revokeAttempted,
       revokeSuccess,
       revokeError,
+      ...(oauthSession ? { oauthRevoked, oauthAgentKey: oauthSession.agentKey || null } : {}),
       configPath: getProfileConfigPath(),
     },
     meta: { apiBase: ctx.apiBase },

package/src/commands/onboarding/credentials.mjs

@@ -5,14 +5,6 @@ import { createCliError } from '../../core/envelope.mjs';
 
 const require = createRequire(import.meta.url);
 const { normalizeCredentialStatus } = require('../../utils/cli/delegationNormalization.cjs');
-/** `credentials upsert` flags of the removed Bitfinex permission probe: accepted, ignored, and named in a warning. */
-const REMOVED_BITFINEX_FLAGS = [
-  ['permissionProfile', '--permission-profile'],
-  ['verifyPermissions', '--verify-permissions'],
-  ['skipPermissionsProbe', '--skip-permissions-probe'],
-  ['bitfinexBaseUrl', '--bitfinex-base-url'],
-];
-
 export function createCredentialsCommands({ printEnvelope, getAuthToken, buildOwnerAuthHeaders }) {
 async function commandCredentialsUpsert(ctx, flags, capabilities) {
   const authToken = getAuthToken(flags, 'Missing --auth-token (or THIRDFY_AUTH_TOKEN) for credentials upsert');
@@ -29,7 +21,6 @@ async function commandCredentialsUpsert(ctx, flags, capabilities) {
   if (flags.policy) payload.policy = parseJsonFlag(flags, 'policy');
   if (flags.agentKey) payload.agentKey = String(flags.agentKey).trim();
   if (flags.chainId) payload.chainId = Number(flags.chainId);
-  const ignoredFlags = REMOVED_BITFINEX_FLAGS.filter(([key]) => flags[key] !== undefined).map(([, flag]) => flag);
   const response = await requestWithRouteFallback(ctx, {
     method: 'POST',
     routes: ['/api/v1/agent/delegation/credentials/upsert', '/api/v1/agent/agent/delegation/credentials/upsert'],
@@ -46,7 +37,6 @@ async function commandCredentialsUpsert(ctx, flags, capabilities) {
     meta: {
       apiBase: ctx.apiBase,
       capabilitiesVersion: capabilities?.contractVersion || null,
-      ...(ignoredFlags.length ? { warnings: [`Ignored ${ignoredFlags.join(', ')}: Bitfinex support was removed. Drop these flags; they will stop being accepted in the next minor version.`] } : {}),
     },
   });
 }

package/src/commands/onboarding/oauthLogin.mjs

@@ -0,0 +1,284 @@
+import { spawn } from 'child_process';
+import { createServer } from 'http';
+import { createCliError } from '../../core/envelope.mjs';
+import { getProfileConfigPath, loadProfileConfig, persistProfileConfig } from '../../core/context.mjs';
+import {
+  buildAuthorizeUrl,
+  discoverAuthServer,
+  exchangeCode,
+  registerCliClient,
+  resolveIssuer,
+} from '../../core/oauth/authServer.mjs';
+import { createPkcePair, createState } from '../../core/oauth/pkce.mjs';
+import { sessionFromTokens, writeOAuthSession } from '../../core/oauth/session.mjs';
+
+/**
+ * `thirdfy-agent login` with OAuth: the owner signs in at auth.thirdfy.com in the browser, picks
+ * one agent, and approves read (always) and trade (`--trade`). The CLI is a public client with a
+ * loopback redirect (RFC 8252): a one-shot listener on 127.0.0.1, PKCE S256, `state`, and
+ * `resource` = the API base. The token acts as that one agent; the API checks it with the auth
+ * server on every request (THI-104).
+ */
+
+const DEFAULT_LOGIN_TIMEOUT_SECONDS = 300;
+
+const escapeHtml = (value) => String(value ?? '').replace(/[&<>"']/g, (char) => `&#${char.charCodeAt(0)};`);
+const shortKey = (key) => (key && key.length > 14 ? `${key.slice(0, 6)}…${key.slice(-4)}` : key || '');
+
+const FALLBACK_ERRORS = {
+  access_denied: ['Sign-in cancelled', 'Nothing was connected. To try again, run <code>thirdfy-agent login</code>.'],
+  state_mismatch: ['This sign-in did not come from your terminal', 'For your safety nothing was connected. Start again from your terminal.'],
+  issuer_mismatch: ['Unexpected sign-in server', 'Nothing was connected. Start again from your terminal.'],
+  exchange_failed: ['The CLI could not finish signing in', 'Nothing was connected. Run <code>thirdfy-agent login</code> to try again.'],
+  failed: ['Sign-in not completed', 'Nothing was connected. Run <code>thirdfy-agent login</code> to try again.'],
+};
+
+/** The built-in result page, for a sign-in server without hosted ones: the same look, no assets. */
+function fallbackPage({ ok, title, body, facts = [] }) {
+  const rows = facts.map(([label, value]) => `<div><dt>${escapeHtml(label)}</dt><dd>${escapeHtml(value)}</dd></div>`).join('');
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><meta name="referrer" content="no-referrer"><title>${escapeHtml(title)} · Thirdfy</title><style>
+:root{color-scheme:dark}*{box-sizing:border-box}body{margin:0;min-height:100vh;display:grid;place-items:center;background:#000;color:#fafafa;font:15px/1.5 Inter,system-ui,-apple-system,"Segoe UI",sans-serif;padding:16px}
+.card{width:100%;max-width:480px;background:#09090b;border:1px solid #27272a;border-radius:16px;padding:28px 24px 24px}
+.brand{font-weight:700;letter-spacing:.18em;font-size:13px;margin-bottom:20px}.status{display:grid;place-items:center;width:52px;height:52px;border-radius:999px;border:1px solid currentColor;margin-bottom:16px;font-size:24px}
+.ok{color:#4ade80;background:rgba(74,222,128,.08)}.err{color:#f87171;background:rgba(248,113,113,.08)}h1{font-size:22px;line-height:1.25;margin:0 0 10px;font-weight:650}p{margin:8px 0;color:#a1a1aa}
+dl{margin:18px 0 0;border:1px solid #27272a;border-radius:12px;overflow:hidden}dl div{display:flex;justify-content:space-between;gap:12px;padding:10px 14px;background:#18181b}dl div+div{border-top:1px solid #27272a}dt{color:#a1a1aa;font-size:14px}dd{margin:0;font-weight:600}
+code{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:13px;color:#fafafa}</style></head><body><main class="card"><div class="brand">THIRDFY</div>
+<div class="status ${ok ? 'ok' : 'err'}" aria-hidden="true">${ok ? '&#10003;' : '&#10005;'}</div><h1>${escapeHtml(title)}</h1><p>${body}</p>${rows ? `<dl>${rows}</dl>` : ''}</main></body></html>`;
+}
+
+/**
+ * The browser's last page. Like Claude Code, GitHub CLI and Google Cloud CLI, the listener sends
+ * the browser to a result page on the sign-in server (`/cli/signed-in`, `/cli/error`) once the CLI
+ * holds its tokens. A server without those pages gets the built-in one.
+ */
+function resultPages(issuer, hosted) {
+  const redirect = (res, location) => res.writeHead(302, { location, 'cache-control': 'no-store' }).end();
+  const html = (res, status, page) => res.writeHead(status, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' }).end(page);
+  return {
+    signedIn(res, { agentKey, canTrade, apiHost }) {
+      if (res.writableEnded) return;
+      if (hosted) {
+        const query = new URLSearchParams({ ...(agentKey ? { agent: agentKey } : {}), access: canTrade ? 'trade' : 'read', ...(apiHost ? { api: apiHost } : {}) });
+        return redirect(res, `${issuer}/cli/signed-in?${query}`);
+      }
+      return html(res, 200, fallbackPage({
+        ok: true,
+        title: "You're signed in to the Thirdfy CLI",
+        body: 'Go back to your terminal to continue. You can close this tab.',
+        facts: [
+          ...(agentKey ? [['Acts as agent', shortKey(agentKey)]] : []),
+          ['Access', canTrade ? 'Read and trade' : 'Read only'],
+          ...(apiHost ? [['API', apiHost]] : []),
+        ],
+      }));
+    },
+    error(res, reason, status = 200) {
+      if (res.writableEnded) return;
+      if (hosted) return redirect(res, `${issuer}/cli/error?reason=${encodeURIComponent(reason)}`);
+      const [title, body] = FALLBACK_ERRORS[reason] || FALLBACK_ERRORS.failed;
+      return html(res, status, fallbackPage({ ok: false, title, body }));
+    },
+  };
+}
+
+/** Whether the sign-in server has the hosted result pages (auth.thirdfy.com 0.5.1+). */
+async function hasHostedResultPages(issuer, timeoutMs) {
+  try {
+    const response = await fetch(`${issuer}/cli/signed-in`, { headers: { accept: 'text/html' }, signal: AbortSignal.timeout(Math.min(timeoutMs, 5000)) });
+    return response.ok && String(response.headers.get('content-type') || '').includes('text/html');
+  } catch {
+    return false;
+  }
+}
+
+function openBrowser(url) {
+  const platform = process.platform;
+  const [command, args] =
+    // Windows: not `cmd /c start`, which splits the URL at every `&` of its query.
+    platform === 'darwin' ? ['open', [url]] : platform === 'win32' ? ['rundll32', ['url.dll,FileProtocolHandler', url]] : ['xdg-open', [url]];
+  try {
+    const child = spawn(command, args, { stdio: 'ignore', detached: true });
+    child.on('error', () => {});
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Listen on 127.0.0.1 (any free port) for one `/callback` that carries our `state`. The browser's
+ * response is held until the CLI has its tokens: `result` resolves with the code and that response.
+ */
+function startLoopbackListener({ state, issuer, timeoutMs, pages }) {
+  let settle;
+  const result = new Promise((resolve, reject) => {
+    settle = { resolve, reject };
+  });
+  const server = createServer((req, res) => {
+    const url = new URL(req.url || '/', 'http://127.0.0.1');
+    if (url.pathname !== '/callback') {
+      res.writeHead(404, { 'content-type': 'text/plain' }).end('Not found');
+      return;
+    }
+    const params = url.searchParams;
+    if (params.get('state') !== state) {
+      pages.error(res, 'state_mismatch', 400);
+      return;
+    }
+    const iss = params.get('iss');
+    if (iss && iss.replace(/\/+$/, '') !== issuer) {
+      pages.error(res, 'issuer_mismatch', 400);
+      settle.reject(createCliError('OAUTH_ISSUER_MISMATCH', `The sign-in answer came from ${iss}, not ${issuer}.`, { blockedStage: 'auth' }));
+      return;
+    }
+    const error = params.get('error');
+    if (error) {
+      pages.error(res, error === 'access_denied' ? 'access_denied' : 'failed');
+      settle.reject(
+        createCliError(error === 'access_denied' ? 'OAUTH_ACCESS_DENIED' : 'OAUTH_AUTHORIZE_FAILED', params.get('error_description') || `Sign-in failed: ${error}`, {
+          blockedStage: 'auth',
+          oauthError: error,
+        }),
+      );
+      return;
+    }
+    const code = params.get('code');
+    if (!code) {
+      pages.error(res, 'failed', 400);
+      return;
+    }
+    settle.resolve({ code, res });
+  });
+  const timer = setTimeout(() => {
+    settle.reject(createCliError('OAUTH_LOGIN_TIMEOUT', `No sign-in arrived within ${Math.round(timeoutMs / 1000)} seconds. Run \`thirdfy-agent login\` again.`, { blockedStage: 'auth' }));
+  }, timeoutMs);
+  timer.unref?.();
+  const ready = new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => resolve(server.address().port));
+  });
+  const close = () => {
+    clearTimeout(timer);
+    server.close();
+    server.closeAllConnections?.();
+  };
+  return { ready, result, close };
+}
+
+/** Which agent the owner picked on the consent page: the token response does not say. */
+async function fetchGrantedAgent(ctx, accessToken) {
+  try {
+    const response = await fetch(`${ctx.apiBase}/api/v1/agent/oauth/session`, {
+      headers: { Authorization: `Bearer ${accessToken}`, accept: 'application/json', 'x-client': 'agent-cli' },
+      signal: AbortSignal.timeout(ctx.timeoutMs || 30_000),
+    });
+    const body = await response.json().catch(() => ({}));
+    if (!response.ok) return { error: body?.error || `HTTP ${response.status}` };
+    const data = body?.data || body;
+    return {
+      agentKey: data?.agentKey ? String(data.agentKey).toLowerCase() : null,
+      ownerDid: data?.ownerDid || null,
+      canTrade: data?.canTrade === true,
+    };
+  } catch (error) {
+    return { error: error?.message || 'network error' };
+  }
+}
+
+export async function commandOAuthLogin(ctx, flags, { printEnvelope, version }) {
+  const timeoutMs = ctx.timeoutMs || 30_000;
+  const resource = ctx.apiBase;
+  const issuer = resolveIssuer(resource, flags);
+  const metadata = await discoverAuthServer(issuer, resource, timeoutMs);
+
+  const config = loadProfileConfig();
+  const knownClients = config.auth?.oauthClients && typeof config.auth.oauthClients === 'object' ? config.auth.oauthClients : {};
+  let clientId = String(knownClients[issuer] || '').trim();
+  if (!clientId) {
+    clientId = await registerCliClient(metadata, { version, timeoutMs });
+    const latest = loadProfileConfig();
+    const auth = latest.auth && typeof latest.auth === 'object' ? latest.auth : {};
+    persistProfileConfig({ ...latest, auth: { ...auth, oauthClients: { ...(auth.oauthClients || {}), [issuer]: clientId } } });
+  }
+
+  const loginSeconds = Number(flags.loginTimeout) > 0 ? Number(flags.loginTimeout) : DEFAULT_LOGIN_TIMEOUT_SECONDS;
+  const state = createState();
+  const pkce = createPkcePair();
+  const pages = resultPages(issuer, await hasHostedResultPages(issuer, timeoutMs));
+  const listener = startLoopbackListener({ state, issuer, timeoutMs: loginSeconds * 1000, pages });
+  let session;
+  let grant;
+  let browserResponse;
+  try {
+    const port = await listener.ready;
+    const redirectUri = `http://127.0.0.1:${port}/callback`;
+    const scope = ['mcp:read', ...(flags.trade ? ['mcp:trade'] : []), 'offline_access'].join(' ');
+    const authorizeUrl = buildAuthorizeUrl(metadata, { clientId, redirectUri, challenge: pkce.challenge, state, scope, resource });
+    const opened = flags.browser === false ? false : openBrowser(authorizeUrl);
+    // stderr: stdout stays a single JSON envelope with --json.
+    process.stderr.write(
+      `${opened ? 'Opening your browser to sign in to Thirdfy.' : 'Open this URL in a browser on this machine to sign in to Thirdfy:'}\n${opened ? 'If it did not open, use: ' : ''}${authorizeUrl}\nWaiting for the sign-in (${loginSeconds}s)...\n`,
+    );
+    const { code, res } = await listener.result;
+    browserResponse = res;
+    try {
+      const tokens = await exchangeCode(metadata, { clientId, code, redirectUri, verifier: pkce.verifier, resource }, timeoutMs);
+      const base = {
+        issuer,
+        clientId,
+        resource,
+        tokenEndpoint: metadata.token_endpoint,
+        revocationEndpoint: metadata.revocation_endpoint || null,
+      };
+      session = sessionFromTokens(base, tokens);
+      grant = await fetchGrantedAgent(ctx, session.accessToken);
+      session = {
+        ...session,
+        agentKey: grant.agentKey || null,
+        ownerDid: grant.ownerDid || null,
+        canTrade: grant.error ? String(session.scope).split(' ').includes('mcp:trade') : grant.canTrade,
+      };
+      writeOAuthSession(session);
+      pages.signedIn(res, { agentKey: session.agentKey, canTrade: session.canTrade, apiHost: new URL(resource).host });
+    } catch (error) {
+      pages.error(res, 'exchange_failed');
+      throw error;
+    }
+  } finally {
+    // Let the browser get its last page before the listener closes its connections.
+    if (browserResponse && !browserResponse.writableFinished) {
+      await new Promise((resolve) => {
+        const timer = setTimeout(resolve, 2000);
+        browserResponse.once('finish', () => {
+          clearTimeout(timer);
+          resolve();
+        });
+      });
+    }
+    listener.close();
+  }
+
+  const warnings = grant.error
+    ? [`Signed in, but ${resource} could not say which agent this sign-in acts as (${grant.error}). The API may not accept OAuth sign-ins yet; use an agent API key or \`login email\` meanwhile.`]
+    : [];
+  printEnvelope({
+    success: true,
+    code: 'LOGIN_OK',
+    message: grant.agentKey ? `Signed in with OAuth as agent ${grant.agentKey}` : 'Signed in with OAuth',
+    data: {
+      auth: 'oauth',
+      issuer,
+      agentKey: session.agentKey,
+      ownerDid: session.ownerDid,
+      scope: session.scope,
+      canTrade: session.canTrade,
+      expiresAt: session.expiresAt,
+      configPath: getProfileConfigPath(),
+      note: session.canTrade
+        ? `This sign-in acts as one agent on ${resource}, with read and trade access. Revoke it any time at ${issuer}/connections or with \`thirdfy-agent logout\`.`
+        : `This sign-in acts as one agent on ${resource}, read-only. For writes, run \`thirdfy-agent login --trade\`. Revoke it at ${issuer}/connections or with \`thirdfy-agent logout\`.`,
+    },
+    meta: { apiBase: ctx.apiBase, ...(warnings.length ? { warnings } : {}) },
+  });
+}