@thirdfy/agent-cli 0.4.2 → 0.5.0

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 } : {}) },
+  });
+}

package/src/core/chainRegistry.mjs

@@ -293,6 +293,17 @@ export function resolveChainRpcUrl({ chainId, rpcUrl, env = process.env } = {})
   return getChainInfo(id)?.rpcUrl || '';
 }
 
+/**
+ * An ethers JsonRpcProvider pinned to `chainId` (`staticNetwork`). Without a pinned network, ethers
+ * probes the RPC for its chain and, when the RPC is down, prints a retry line to stdout every second
+ * and keeps the process alive, which breaks `--json` output. Pinned, a dead RPC is one rejected
+ * call. `getNetwork()` then echoes the pin; read the RPC's real chain with `send('eth_chainId', [])`.
+ */
+export function pinnedRpcProvider(ethers, { rpcUrl, chainId }) {
+  const id = positiveChainId(chainId) || DEFAULT_CHAIN_ID;
+  return new ethers.JsonRpcProvider(rpcUrl, id, { staticNetwork: true });
+}
+
 /**
  * Parse a --chain-id value. Returns null when absent, a positive integer when valid,
  * and NaN when present but not a positive integer (the caller rejects it).

package/src/core/constants.mjs

@@ -1,25 +1,6 @@
 export const DEFAULT_API_BASE = 'https://api.thirdfy.com';
 export const DEFAULT_TIMEOUT_MS = 30000;
 export const DEFAULT_CATALOG_CACHE_TTL_MS = 60_000;
-export const DEFAULT_BITFINEX_BASE_URL = 'https://api.bitfinex.com';
-export const BITFINEX_PERMISSION_PROFILES = {
-  funding: {
-    id: 'funding',
-    credentialRef: 'bitfinex:funding-primary',
-    required: {
-      funding: { read: 1, write: 1 },
-      wallets: { read: 1, write: 0 },
-    },
-  },
-  spot: {
-    id: 'spot',
-    credentialRef: 'bitfinex:spot-primary',
-    required: {
-      orders: { read: 1, write: 1 },
-      wallets: { read: 1, write: 0 },
-    },
-  },
-};
 export const RUN_MODES = ['thirdfy', 'self', 'hybrid', 'agent_wallet'];
 export const HYBRID_WALLET_MODES = ['self', 'agent_wallet'];
 export const CUSTODY_MODES = ['managed', 'external'];

package/src/core/context.mjs

@@ -4,6 +4,7 @@ import path from 'path';
 import { DEFAULT_CATALOG_CACHE_TTL_MS, PROFILE_DEFAULTS } from './constants.mjs';
 import { createCliError } from './envelope.mjs';
 import { apiGet } from './http.mjs';
+import { apiBaseFor, oauthSessionForApi, oauthSessionIsAgentCredential } from './oauth/session.mjs';
 import {
   normalizeCustodyMode,
   normalizeProfileName,
@@ -121,21 +122,27 @@ export function extractActions(response) {
 }
 
 /**
- * The agent API key from `--agent-api-key`, then THIRDFY_AGENT_API_KEY, then config `agent.apiKey`;
- * empty when none is set. The same order execution uses, without its missing-key error.
+ * The agent credential from `--agent-api-key`, then THIRDFY_AGENT_API_KEY, then the OAuth sign-in
+ * for this API (`thirdfy-agent login`, its access token), then config `agent.apiKey`; empty when
+ * none is set.
+ * The same order execution uses, without its missing-key error. An OAuth token is sent as
+ * `Authorization: Bearer` (and refreshed) by `src/core/http.mjs`.
  */
 export function findAgentApiKey(flags = {}) {
   const explicit = String(flags.agentApiKey || '').trim();
   if (explicit) return explicit;
   const envKey = String(process.env.THIRDFY_AGENT_API_KEY || '').trim();
   if (envKey) return envKey;
-  return String(loadProfileConfig()?.agent?.apiKey || '').trim();
+  const config = loadProfileConfig();
+  const oauth = oauthSessionForApi(apiBaseFor(flags), config);
+  if (oauth) return oauth.accessToken;
+  return String(config?.agent?.apiKey || '').trim();
 }
 
 /**
  * Whose credits a credits read is about. Same precedence as `wallet profile`: an owner credential
- * passed as a flag (--owner-session-token or --auth-token), then an explicit --agent-api-key, then
- * owner auth from env or config, then an agent key from env or config. Returns `{ ledger, agentApiKey,
+ * passed as a flag (--owner-session-token or --auth-token), then an explicit --agent-api-key or an
+ * OAuth sign-in, then owner auth from env or config, then an agent key from env or config. Returns `{ ledger, agentApiKey,
  * agentApiKeyExplicit }`; `ledger` is `agent` or `owner`.
  */
 export function resolveCreditsLedger(flags = {}) {
@@ -148,7 +155,10 @@ export function resolveCreditsLedger(flags = {}) {
     ).trim(),
   );
   const agentApiKey = findAgentApiKey(flags);
-  const agent = !explicitOwner && (agentApiKeyExplicit || (!storedOwner && Boolean(agentApiKey)));
+  // An OAuth sign-in (`thirdfy-agent login`) is a deliberate choice of one agent: it comes before
+  // owner auth stored in env or config, as an explicit --agent-api-key does.
+  const oauthAgent = oauthSessionIsAgentCredential(flags, process.env, config);
+  const agent = !explicitOwner && (agentApiKeyExplicit || oauthAgent || (!storedOwner && Boolean(agentApiKey)));
   return { ledger: agent ? 'agent' : 'owner', agentApiKey, agentApiKeyExplicit };
 }
 

package/src/core/errorEnvelope.mjs

@@ -20,6 +20,8 @@ export const NEXT_ACTIONS = Object.freeze({
   fund_native_gas: "The execution wallet cannot pay this chain's gas. Fund it with the native coin first.",
   owner_reenable_agent_signer: "The wallet owner removed Thirdfy's signer. The owner must re-enable the agent.",
   use_evm_chain: 'This Thirdfy API does not run that chain family (Solana). Use an EVM chain the API lists in `chains`.',
+  reauthenticate: 'The sign-in expired or was revoked. Sign in again: `thirdfy-agent login`.',
+  reauthenticate_with_trade: 'This sign-in is read-only. Sign in again with trade access: `thirdfy-agent login --trade`.',
 });
 
 /** Credits refusal codes the API sends (HTTP 402). */
@@ -56,6 +58,10 @@ const CLIENT_CODE_FIELDS = Object.freeze({
   SOLANA_NOT_ENABLED: { retryable: false, nextAction: 'use_evm_chain' },
   BROADCAST_FAILED: { retryable: false, nextAction: 'reread_state_before_retry' },
   EFFECT_CHECK_FAILED: { retryable: false, nextAction: 'reread_state_before_retry' },
+  OAUTH_SESSION_EXPIRED: { retryable: false, nextAction: 'reauthenticate' },
+  OAUTH_ACCESS_DENIED: { retryable: false, nextAction: 'reauthenticate' },
+  OAUTH_LOGIN_TIMEOUT: { retryable: true, nextAction: 'retry_later' },
+  OAUTH_DISCOVERY_FAILED: { retryable: true, nextAction: 'retry_later' },
 });
 
 const isRecord = (value) => Boolean(value && typeof value === 'object' && !Array.isArray(value));

package/src/core/http.mjs

@@ -3,6 +3,7 @@ import {
   mergeExecutionContext,
   resolveExecutionContextFromInput,
 } from './execution/executionContext.mjs';
+import { freshOAuthAccessToken, isOAuthAccessToken, readOAuthSession } from './oauth/session.mjs';
 
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
@@ -123,7 +124,21 @@ function mergeExecutionContextHeaders(headers = {}, body = {}) {
   };
 }
 
-export async function apiPost(ctx, route, body, headers = {}) {
+/**
+ * Execute payloads carry the agent credential in the body (`agentApiKey`). An OAuth sign-in never
+ * goes in a body: it moves to the header, where `withOAuthBearer` sends it as `Authorization: Bearer`.
+ */
+function moveOAuthCredentialToHeader(body, headers) {
+  const credential = body.agentApiKey ?? body.agent_api_key;
+  if (!isOAuthAccessToken(credential)) return { body, headers };
+  const { agentApiKey: _a, agent_api_key: _b, ...rest } = body;
+  return { body: rest, headers: { 'x-agent-api-key': credential, ...headers } };
+}
+
+export async function apiPost(ctx, route, rawBody, rawHeaders = {}) {
+  const moved = moveOAuthCredentialToHeader(rawBody && typeof rawBody === 'object' ? rawBody : {}, rawHeaders);
+  const body = moved.body;
+  const headers = moved.headers;
   const normalizedBody = body && typeof body === 'object' ? body : {};
   const mergedBody = mergeExecutionContext(normalizedBody);
   return requestJson(ctx, route, {
@@ -136,7 +151,25 @@ export async function apiPost(ctx, route, body, headers = {}) {
   });
 }
 
-async function requestJsonOnce(ctx, route, init) {
+/**
+ * An OAuth sign-in passed as the agent credential (`findAgentApiKey`) goes as
+ * `Authorization: Bearer`, refreshed first when it is about to expire. Owner auth already in
+ * `Authorization` wins; the OAuth token is then not sent.
+ */
+async function withOAuthBearer(ctx, init) {
+  const headers = { ...(init.headers || {}) };
+  const credential = headers['x-agent-api-key'];
+  if (!isOAuthAccessToken(credential)) return { init, oauth: false };
+  const session = readOAuthSession();
+  const token = session?.accessToken === credential ? (await freshOAuthAccessToken({ timeoutMs: ctx.timeoutMs })) || credential : credential;
+  delete headers['x-agent-api-key'];
+  if (!headers.Authorization && !headers.authorization) headers.Authorization = `Bearer ${token}`;
+  return { init: { ...init, headers }, oauth: true };
+}
+
+async function requestJsonOnce(ctx, route, rawInit) {
+  const { __oauthRetried, ...plainInit } = rawInit;
+  const { init, oauth } = await withOAuthBearer(ctx, plainInit);
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), ctx.timeoutMs);
   try {
@@ -147,6 +180,18 @@ async function requestJsonOnce(ctx, route, init) {
     const text = await response.text();
     const data = text ? safeJsonParse(text) : {};
     rememberResponseHeaders(data, response);
+    // A 401 to an OAuth sign-in: refresh once and send again. Nothing ran on a 401, so this is safe
+    // for writes too. A refresh the auth server refuses is OAUTH_SESSION_EXPIRED.
+    if (response.status === 401 && oauth && !__oauthRetried) {
+      const token = await freshOAuthAccessToken({ timeoutMs: ctx.timeoutMs, force: true });
+      if (token) {
+        return await requestJsonOnce(ctx, route, {
+          ...plainInit,
+          headers: { ...(plainInit.headers || {}), 'x-agent-api-key': token },
+          __oauthRetried: true,
+        });
+      }
+    }
     if (!response.ok) {
       const error = new Error(data?.error || data?.message || `HTTP ${response.status}`);
       error.statusCode = response.status;

package/src/core/oauth/authServer.mjs

@@ -0,0 +1,192 @@
+import { createCliError } from '../envelope.mjs';
+
+/**
+ * The auth.thirdfy.com calls `thirdfy-agent login` makes: metadata (RFC 8414), client registration
+ * (RFC 7591, a public client with a loopback redirect), the authorize URL, the code exchange and
+ * refresh (PKCE S256, `resource` = the API, RFC 8707), and revocation (RFC 7009).
+ */
+
+const KNOWN_ISSUERS = new Map([
+  ['api.thirdfy.com', 'https://auth.thirdfy.com'],
+  ['api-test.thirdfy.com', 'https://auth-test.thirdfy.com'],
+]);
+
+/** Registered once per issuer; any loopback port matches this redirect. */
+export const CLI_REDIRECT_URI = 'http://127.0.0.1/callback';
+export const CLI_CLIENT_NAME = 'Thirdfy Agent CLI';
+
+const trimSlash = (value) => String(value || '').trim().replace(/\/+$/, '');
+
+/** --issuer, then THIRDFY_AUTH_ISSUER, then the issuer paired with a known API base. */
+export function resolveIssuer(apiBase, flags = {}, env = process.env) {
+  const explicit = trimSlash(flags.issuer || env.THIRDFY_AUTH_ISSUER);
+  if (explicit) return explicit;
+  let host = '';
+  try {
+    host = new URL(apiBase).host;
+  } catch {
+    host = '';
+  }
+  const known = KNOWN_ISSUERS.get(host);
+  if (known) return known;
+  throw createCliError(
+    'OAUTH_ISSUER_REQUIRED',
+    `No sign-in server is known for ${apiBase}. Pass --issuer <url> (or set THIRDFY_AUTH_ISSUER), or sign in with \`thirdfy-agent login email <address>\`.`,
+    { blockedStage: 'auth' },
+  );
+}
+
+async function fetchJson(url, init, timeoutMs, failureCode) {
+  let response;
+  try {
+    response = await fetch(url, { ...init, signal: AbortSignal.timeout(timeoutMs) });
+  } catch (error) {
+    throw createCliError(failureCode, `Could not reach ${new URL(url).origin}: ${error?.message || 'network error'}`, {
+      blockedStage: 'auth',
+      retryable: true,
+    });
+  }
+  const text = await response.text();
+  let body = {};
+  try {
+    body = text ? JSON.parse(text) : {};
+  } catch {
+    body = {};
+  }
+  return { response, body };
+}
+
+const oauthError = (code, body, fallback) =>
+  createCliError(code, String(body?.error_description || body?.message || body?.error || fallback), {
+    blockedStage: 'auth',
+    oauthError: body?.error || null,
+  });
+
+/** RFC 8414 metadata, checked for what the CLI needs: the issuer, S256, and the API as a resource. */
+export async function discoverAuthServer(issuer, resource, timeoutMs) {
+  const { response, body } = await fetchJson(
+    `${issuer}/.well-known/oauth-authorization-server`,
+    { headers: { accept: 'application/json' } },
+    timeoutMs,
+    'OAUTH_DISCOVERY_FAILED',
+  );
+  if (!response.ok || trimSlash(body?.issuer) !== issuer || !body?.authorization_endpoint || !body?.token_endpoint) {
+    throw createCliError('OAUTH_DISCOVERY_FAILED', `${issuer} did not answer as a Thirdfy sign-in server (HTTP ${response.status}).`, {
+      blockedStage: 'auth',
+    });
+  }
+  const methods = Array.isArray(body.code_challenge_methods_supported) ? body.code_challenge_methods_supported : [];
+  if (!methods.includes('S256')) {
+    throw createCliError('OAUTH_DISCOVERY_FAILED', `${issuer} does not support PKCE S256.`, { blockedStage: 'auth' });
+  }
+  const resources = Array.isArray(body.protected_resources) ? body.protected_resources.map(trimSlash) : null;
+  if (resources && !resources.includes(trimSlash(resource))) {
+    throw createCliError(
+      'OAUTH_RESOURCE_NOT_SUPPORTED',
+      `${issuer} does not issue sign-ins for ${resource} yet. Use \`thirdfy-agent login email <address>\` for now.`,
+      { blockedStage: 'auth' },
+    );
+  }
+  return body;
+}
+
+/** A public client (no secret) with the loopback redirect, registered once per issuer. */
+export async function registerCliClient(metadata, { version, timeoutMs }) {
+  if (!metadata.registration_endpoint) {
+    throw createCliError('OAUTH_REGISTRATION_UNAVAILABLE', `${metadata.issuer} does not accept client registration.`, {
+      blockedStage: 'auth',
+    });
+  }
+  const { response, body } = await fetchJson(
+    metadata.registration_endpoint,
+    {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', accept: 'application/json' },
+      body: JSON.stringify({
+        client_name: CLI_CLIENT_NAME,
+        redirect_uris: [CLI_REDIRECT_URI],
+        token_endpoint_auth_method: 'none',
+        grant_types: ['authorization_code', 'refresh_token'],
+        response_types: ['code'],
+        client_uri: 'https://www.npmjs.com/package/@thirdfy/agent-cli',
+        software_id: 'thirdfy-agent-cli',
+        ...(version ? { software_version: String(version) } : {}),
+      }),
+    },
+    timeoutMs,
+    'OAUTH_REGISTRATION_FAILED',
+  );
+  if (!response.ok || !body?.client_id) throw oauthError('OAUTH_REGISTRATION_FAILED', body, `Client registration failed (HTTP ${response.status}).`);
+  return String(body.client_id);
+}
+
+export function buildAuthorizeUrl(metadata, { clientId, redirectUri, challenge, state, scope, resource }) {
+  const url = new URL(metadata.authorization_endpoint);
+  url.search = new URLSearchParams({
+    response_type: 'code',
+    client_id: clientId,
+    redirect_uri: redirectUri,
+    code_challenge: challenge,
+    code_challenge_method: 'S256',
+    state,
+    scope,
+    resource,
+  }).toString();
+  return url.toString();
+}
+
+async function tokenRequest(tokenEndpoint, params, timeoutMs, failureCode) {
+  const { response, body } = await fetchJson(
+    tokenEndpoint,
+    {
+      method: 'POST',
+      headers: { 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' },
+      body: new URLSearchParams(params).toString(),
+    },
+    timeoutMs,
+    failureCode,
+  );
+  if (!response.ok || !body?.access_token) {
+    const code = body?.error === 'invalid_grant' ? 'OAUTH_SESSION_EXPIRED' : failureCode;
+    throw oauthError(code, body, `Token request failed (HTTP ${response.status}).`);
+  }
+  return body;
+}
+
+export function exchangeCode(metadata, { clientId, code, redirectUri, verifier, resource }, timeoutMs) {
+  return tokenRequest(
+    metadata.token_endpoint,
+    { grant_type: 'authorization_code', code, redirect_uri: redirectUri, client_id: clientId, code_verifier: verifier, resource },
+    timeoutMs,
+    'OAUTH_CODE_EXCHANGE_FAILED',
+  );
+}
+
+export function refreshTokens({ tokenEndpoint, clientId, refreshToken, resource }, timeoutMs) {
+  return tokenRequest(
+    tokenEndpoint,
+    { grant_type: 'refresh_token', refresh_token: refreshToken, client_id: clientId, ...(resource ? { resource } : {}) },
+    timeoutMs,
+    'OAUTH_REFRESH_FAILED',
+  );
+}
+
+/** RFC 7009: best effort; the answer is 200 even for an unknown token. */
+export async function revokeToken({ revocationEndpoint, clientId, token }, timeoutMs) {
+  if (!revocationEndpoint || !token) return false;
+  try {
+    const { response } = await fetchJson(
+      revocationEndpoint,
+      {
+        method: 'POST',
+        headers: { 'content-type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams({ token, client_id: clientId }).toString(),
+      },
+      timeoutMs,
+      'OAUTH_REVOKE_FAILED',
+    );
+    return response.ok;
+  } catch {
+    return false;
+  }
+}