@orboto/mcp 0.178.0

package/dist/manifest-size.test.js

@@ -0,0 +1,192 @@
+/**
+ * ORB-1521 - manifest-size measurement + regression ratchet (epic
+ * ORB-1517).
+ *
+ * Measures the REAL `tools/list` payload an eager-loading client pays
+ * at connect time - through an actual MCP client over an in-memory
+ * transport, so the numbers include the SDK's zod->JSON-schema
+ * conversion, exactly what Codex/Cursor/Claude Desktop receive.
+ *
+ * The curated assertion is the RATCHET (mirroring the dark-mode / i18n
+ * shrink-only checks): if someone re-registers the tail into the
+ * default manifest - or the curated set quietly balloons - this fails
+ * before a release ships the token bill. Raising CURATED_MAX_CHARS is a
+ * conscious decision to grow the default connect cost, not a formality.
+ */
+import { beforeEach, afterEach, describe, expect, it, vi } from 'vitest';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import { buildOrbotoMcpServer } from './server.js';
+beforeEach(() => {
+    vi.restoreAllMocks();
+    vi.spyOn(globalThis, 'fetch').mockRejectedValue(new Error('offline test'));
+    delete process.env.ORBOTO_MCP_TOOLSET;
+});
+afterEach(() => { vi.restoreAllMocks(); });
+/**
+ * Measured 2026-08-10 (ORB-1521): curated = 28 tools / 37,458 chars
+ * (~9.4k tokens); full = 171 tools / 189,672 chars (~47.4k tokens).
+ * Re-measured 2026-08-28 after the ORB-1741 manifest diet (one-line
+ * descriptions + orboto_help): curated = 29 tools / 27,870 chars
+ * (~7.0k tokens); full = 173 tools / 145,867 chars (~36.5k tokens).
+ * ORB-1694 added the two bulk tools (create + dependencies, schema-heavy
+ * by nature): curated = 31 tools / 33,615 chars - still below the
+ * pre-diet 37,458 baseline. Ceilings keep ~7-10 % headroom for honest
+ * edits - a description essay creeping back in is exactly what these
+ * must catch, so the headroom is deliberately tighter than the old
+ * 20 %. Shrink-only: raising either number is a conscious decision to
+ * grow every session's connect cost.
+ *
+ * ORB-1805, measured 2026-09-01 with the schema diet + the compact
+ * advertised `__truncation` block: minimal = 12 tools / 9,440 chars;
+ * curated = 31 tools / 27,945 chars (was 34,015); full = 175 tools /
+ * 142,366 chars (was 152,348).
+ *
+ * ORB-1669, landed 2026-09-04: every tool carries an MCP `annotations`
+ * block (readOnlyHint / destructiveHint / idempotentHint) - clients use
+ * them for confirmation UX, so they are spec conformance, not payload
+ * fat. Measured cost: minimal +688 chars (12 tools), curated +1,276,
+ * full +9,836 (175 tools, ~56 chars each). FULL_MAX_CHARS and
+ * MINIMAL_MAX_TOKENS were raised by exactly that, deliberately.
+ */
+const CURATED_MAX_CHARS = 30_000;
+const FULL_MAX_CHARS = 155_000;
+/**
+ * ORB-1805 - the estimator the ticket measured the failure with
+ * (`n_keep: 13533 >= n_ctx: 8192` in LM Studio): characters / 3.6. It is
+ * a rough tokenizer stand-in, deliberately the SAME rough number the
+ * ticket, the docs page and these ceilings all use, so the figures a
+ * reader compares are comparable.
+ */
+const CHARS_PER_TOKEN = 3.6;
+const estTokens = (chars) => Math.round(chars / CHARS_PER_TOKEN);
+/**
+ * The minimal tier's whole connect cost - tool schemas AND the
+ * instructions block - must fit a small local model's window with room
+ * left for the conversation. 3,000 was the ticket's number; 3,100 since
+ * ORB-1669 added the annotations block to every tool (+688 chars).
+ */
+const MINIMAL_MAX_TOKENS = 3_100;
+/**
+ * The curated tier is ratcheted on its TOOL SCHEMAS (the instructions
+ * block has its own budget, enforced in instructions-budget.test.ts).
+ *
+ * Why this is not the ticket's aspirational 6,000: measured 2026-09-01,
+ * the curated manifest with EVERY description and title stripped out is
+ * still 17,379 chars (~4,827 tokens) - 31 tools' names, parameter names,
+ * types, enums, plus ~2,700 chars of per-tool `$schema` and `execution`
+ * keys the MCP SDK emits and we do not control. A 6,000-token ceiling
+ * would leave ~4,200 chars for all 31 tools' text combined, i.e. the
+ * one-line summaries and NOTHING else - no "Key (ORB-M3), name, or
+ * UUID", no "YYYY-MM-DD", no "Default: task". Those pay for themselves
+ * in avoided failed calls. The tier that genuinely fits a small window
+ * is `minimal`; curated is the desktop-client default, and this ceiling
+ * holds the 18 % the diet won.
+ */
+const CURATED_SCHEMA_MAX_TOKENS = 8_200;
+async function measuredManifest(toolset) {
+    const server = await buildOrbotoMcpServer({
+        baseUrl: 'https://orboto.example.com',
+        apiKey: 'orb_test',
+        ...(toolset ? { toolset } : {}),
+    });
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+    const client = new Client({ name: 'manifest-measure', version: '0.0.0' });
+    await Promise.all([server.connect(serverTransport), client.connect(clientTransport)]);
+    try {
+        // Walk pagination defensively; the SDK serves all tools in one page
+        // today but the measurement must not silently undercount if that
+        // changes.
+        let cursor;
+        const tools = [];
+        do {
+            const page = await client.listTools(cursor ? { cursor } : {});
+            tools.push(...page.tools);
+            cursor = page.nextCursor;
+        } while (cursor);
+        // `_instructions` verified against @modelcontextprotocol/sdk 1.29.
+        // Assert non-empty at the call sites so an SDK rename fails loudly
+        // instead of scoring the block as free.
+        const instructions = String(server.server._instructions ?? '');
+        return { count: tools.length, chars: JSON.stringify(tools).length, instructionsChars: instructions.length };
+    }
+    finally {
+        await client.close();
+        await server.close();
+    }
+}
+describe('ORB-1521 - eager-load manifest size', () => {
+    it('curated manifest stays under the ratchet ceiling', async () => {
+        const { count, chars } = await measuredManifest();
+        // eslint-disable-next-line no-console
+        console.log(`[manifest-size] curated: ${count} tools, ${chars} chars (~${estTokens(chars)} tokens)`);
+        // 31 = the ORB-1741-dieted set + the two ORB-1694 bulk tools (each
+        // REPLACES dozens of per-call responses, so they earn their slot).
+        expect(count).toBeLessThanOrEqual(32);
+        expect(chars).toBeLessThanOrEqual(CURATED_MAX_CHARS);
+        expect(estTokens(chars)).toBeLessThanOrEqual(CURATED_SCHEMA_MAX_TOKENS);
+    });
+    it('full manifest remains available and an order of magnitude larger', async () => {
+        const curated = await measuredManifest();
+        const full = await measuredManifest('full');
+        // eslint-disable-next-line no-console
+        console.log(`[manifest-size] full: ${full.count} tools, ${full.chars} chars (~${estTokens(full.chars)} tokens)`);
+        expect(full.count).toBeGreaterThan(150);
+        // ORB-1741 - the full manifest is ratcheted too: the diet's savings
+        // live mostly here (per-tool description essays), so this is where
+        // regression would land first.
+        expect(full.chars).toBeLessThanOrEqual(FULL_MAX_CHARS);
+        // The reduction claim the epic makes - keep it honest in CI.
+        expect(full.chars / curated.chars).toBeGreaterThan(3);
+    });
+});
+/**
+ * ORB-1805 - the small-context tier.
+ *
+ * This is the assertion that keeps the tier honest: an 8k local model
+ * pays the WHOLE connect cost (schemas + instructions) before its own
+ * first turn, so both halves are measured together against one ceiling.
+ */
+describe('ORB-1805 - minimal manifest fits a small context window', () => {
+    it('minimal: schemas + instructions stay under 3k estimated tokens', async () => {
+        const { count, chars, instructionsChars } = await measuredManifest('minimal');
+        const total = chars + instructionsChars;
+        // eslint-disable-next-line no-console
+        console.log(`[manifest-size] minimal: ${count} tools, ${chars} chars (~${estTokens(chars)} tokens)`
+            + ` + instructions ${instructionsChars} chars (~${estTokens(instructionsChars)} tokens)`
+            + ` = ~${estTokens(total)} tokens`);
+        expect(count).toBe(12);
+        expect(instructionsChars).toBeGreaterThan(100); // SDK rename guard
+        expect(estTokens(total)).toBeLessThanOrEqual(MINIMAL_MAX_TOKENS);
+    });
+    it('minimal is a strict subset of curated, which is a strict subset of full', async () => {
+        const minimal = await measuredManifest('minimal');
+        const curated = await measuredManifest();
+        const full = await measuredManifest('full');
+        expect(minimal.count).toBeLessThan(curated.count);
+        expect(curated.count).toBeLessThan(full.count);
+        expect(minimal.chars).toBeLessThan(curated.chars);
+    });
+    it('minimal instructions are a CONSTANT - a long workspace rule set cannot grow them', async () => {
+        // The tier ships the head only: no workspace rules block, so a
+        // workspace with a 200-line rule set costs the same as an empty one.
+        // (The rules are not lost - orboto_session_start returns them, on
+        // the caller's budget rather than as a connect-time tax.) Curated,
+        // by contrast, embeds them up to its 4k budget - assert BOTH so this
+        // stays a real difference and not a coincidence of the fixture.
+        const offline = await measuredManifest('minimal');
+        const hugeRules = Array.from({ length: 200 }, (_, i) => `rule ${i}: ${'x'.repeat(60)}`).join('\n');
+        vi.spyOn(globalThis, 'fetch').mockResolvedValue({
+            ok: true,
+            status: 200,
+            headers: new Headers({ 'content-type': 'application/json' }),
+            json: async () => ({ instructions: hugeRules }),
+            text: async () => JSON.stringify({ instructions: hugeRules }),
+        });
+        const loaded = await measuredManifest('minimal');
+        expect(loaded.instructionsChars).toBe(offline.instructionsChars);
+        expect(loaded.instructionsChars).toBeLessThanOrEqual(1_000);
+        const curated = await measuredManifest();
+        expect(curated.instructionsChars).toBeGreaterThan(loaded.instructionsChars);
+    });
+});

package/dist/mcp-instrument.js

@@ -0,0 +1,24 @@
+/**
+ * ORB-1180 - defensive secret-redaction on anything we persist to the
+ * admin MCP panel. The API error body is workspace error text (no
+ * secrets), but the non-API error path is `err.message` from arbitrary
+ * code and could carry a token / Authorization header / creds-in-URL.
+ * Strip the obvious shapes before the log row is written.
+ */
+export function redactSecrets(text) {
+    return text
+        .replace(/orb_[A-Za-z0-9_-]{8,}/g, 'orb_[redacted]')
+        .replace(/Bearer\s+[A-Za-z0-9._~+/=-]+/gi, 'Bearer [redacted]')
+        .replace(/eyJ[A-Za-z0-9._-]{10,}/g, '[redacted-jwt]')
+        .replace(/(https?:\/\/)[^/\s:@]+:[^/\s@]+@/gi, '$1[redacted]@');
+}
+export async function postLogEntry(client, entry) {
+    try {
+        await client.post('/admin/mcp/instrument', entry);
+    }
+    catch {
+        // Swallow - instrumentation must never fail the tool call. If the
+        // workspace is mid-restart or rate-limited, we'd rather lose a
+        // few rows than break user-visible behaviour.
+    }
+}

package/dist/oauth-bootstrap.js

@@ -0,0 +1,413 @@
+/**
+ * ORB-943 - OAuth bootstrap for the stdio local-proxy.
+ *
+ * The stdio proxy (`@orboto/mcp` spawned by Claude Desktop / Cursor) was
+ * PAT-only: the operator had to paste a long-lived `orb_*` key into the
+ * client config. This module gives the stdio proxy the SAME short-lived,
+ * SSO-backed OAuth path the HTTP transport already offers - a browser-assisted
+ * loopback flow (RFC 8252) so a desktop user connects without ever pasting a
+ * token. The PAT stays the documented fallback for headless service accounts
+ * (see index.ts).
+ *
+ * Design:
+ *   - No new API surface. This reuses the shipped provider-side OAuth stack
+ *     (discovery + DCR + PKCE + rotating refresh) exactly as an HTTP MCP client
+ *     would: discover -> register -> authorize-in-browser -> exchange -> use
+ *     the access token as the REST Bearer (the api's `authenticate` decorator
+ *     already accepts OAuth access tokens alongside `orb_*` keys).
+ *   - The refresh token is cached on disk (0600) keyed by the instance origin,
+ *     so a subsequent boot refreshes silently instead of re-opening a browser.
+ *   - The pure pieces (PKCE, request building, response parsing, the cache
+ *     round-trip, the token-provider refresh math) are exported so they unit
+ *     test without a browser or a live server. The loopback listener + browser
+ *     open is the thin I/O shell.
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import { createServer } from 'node:http';
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { VERSION } from './version.js';
+/** The single required capability scope + offline_access so the AS mints a
+ *  refresh token we can cache (without it the connection dies after the 1h
+ *  access-token TTL and forces a browser re-auth). Mirrors the HTTP client. */
+export const BOOTSTRAP_SCOPE = 'mcp offline_access';
+/** Skew applied when deciding whether a cached access token is still usable.
+ *  A token within this window of expiry is treated as expired so we refresh
+ *  proactively rather than racing a mid-request 401. */
+export const EXPIRY_SKEW_MS = 60_000;
+/** Generate a PKCE verifier + S256 challenge. Verifier is 32 random bytes
+ *  base64url (43 chars), well within the RFC's 43-128 range. */
+export function generatePkce() {
+    const verifier = randomBytes(32).toString('base64url');
+    const challenge = createHash('sha256').update(verifier).digest('base64url');
+    return { verifier, challenge, method: 'S256' };
+}
+/** Random opaque state to bind the browser round-trip against CSRF. */
+export function generateState() {
+    return randomBytes(16).toString('base64url');
+}
+// ---------------------------------------------------------------------------
+// Origin derivation + discovery
+// ---------------------------------------------------------------------------
+/**
+ * The OAuth authorization server lives at the instance ORIGIN, while the stdio
+ * proxy is configured with the REST base (`<origin>/api`). Strip a trailing
+ * `/api` (single-host reverse-proxy layout, ORB-938) to recover the origin the
+ * well-known metadata is served from. A base that is already the bare origin is
+ * returned unchanged.
+ */
+export function deriveOrigin(apiBaseUrl) {
+    const trimmed = apiBaseUrl.replace(/\/+$/, '');
+    return trimmed.replace(/\/api$/, '');
+}
+/** Fetch + validate the RFC 8414 authorization-server metadata. */
+export async function discoverAuthServer(origin, fetchImpl = fetch) {
+    const url = `${origin.replace(/\/+$/, '')}/.well-known/oauth-authorization-server`;
+    const res = await fetchImpl(url, { headers: { Accept: 'application/json' } });
+    if (!res.ok) {
+        throw new Error(`OAuth discovery failed: ${res.status} from ${url}`);
+    }
+    const meta = (await res.json());
+    if (!meta.authorization_endpoint || !meta.token_endpoint || !meta.registration_endpoint || !meta.issuer) {
+        throw new Error(`OAuth discovery returned incomplete metadata from ${url}`);
+    }
+    return meta;
+}
+// ---------------------------------------------------------------------------
+// Dynamic Client Registration (RFC 7591)
+// ---------------------------------------------------------------------------
+/** Register a public client for the loopback redirect. Returns the client_id. */
+export async function registerLoopbackClient(registrationEndpoint, redirectUri, fetchImpl = fetch) {
+    const res = await fetchImpl(registrationEndpoint, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+        body: JSON.stringify({
+            client_name: `orboto-mcp stdio proxy ${VERSION}`,
+            redirect_uris: [redirectUri],
+            grant_types: ['authorization_code', 'refresh_token'],
+            response_types: ['code'],
+            token_endpoint_auth_method: 'none',
+        }),
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throw new Error(`OAuth client registration failed: ${res.status} ${body}`);
+    }
+    const json = (await res.json());
+    if (!json.client_id)
+        throw new Error('OAuth client registration returned no client_id');
+    return json.client_id;
+}
+// ---------------------------------------------------------------------------
+// Authorize URL + token exchange
+// ---------------------------------------------------------------------------
+export function buildAuthorizeUrl(authorizationEndpoint, params) {
+    const u = new URL(authorizationEndpoint);
+    u.searchParams.set('response_type', 'code');
+    u.searchParams.set('client_id', params.clientId);
+    u.searchParams.set('redirect_uri', params.redirectUri);
+    u.searchParams.set('scope', params.scope);
+    u.searchParams.set('code_challenge', params.challenge);
+    u.searchParams.set('code_challenge_method', 'S256');
+    u.searchParams.set('state', params.state);
+    return u.toString();
+}
+function parseTokenResponse(json) {
+    const t = json;
+    if (!t.access_token)
+        throw new Error('OAuth token response missing access_token');
+    const expiresInMs = (typeof t.expires_in === 'number' ? t.expires_in : 3600) * 1000;
+    return {
+        accessToken: t.access_token,
+        refreshToken: t.refresh_token ?? null,
+        expiresAt: Date.now() + expiresInMs,
+        scope: t.scope ?? BOOTSTRAP_SCOPE,
+    };
+}
+export async function exchangeAuthCode(tokenEndpoint, params, fetchImpl = fetch) {
+    const res = await fetchImpl(tokenEndpoint, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+        body: JSON.stringify({
+            grant_type: 'authorization_code',
+            code: params.code,
+            redirect_uri: params.redirectUri,
+            client_id: params.clientId,
+            code_verifier: params.verifier,
+        }),
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throw new Error(`OAuth code exchange failed: ${res.status} ${body}`);
+    }
+    return parseTokenResponse(await res.json());
+}
+export async function refreshTokens(tokenEndpoint, params, fetchImpl = fetch) {
+    const res = await fetchImpl(tokenEndpoint, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+        body: JSON.stringify({
+            grant_type: 'refresh_token',
+            refresh_token: params.refreshToken,
+            client_id: params.clientId,
+        }),
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throw new Error(`OAuth token refresh failed: ${res.status} ${body}`);
+    }
+    return parseTokenResponse(await res.json());
+}
+// ---------------------------------------------------------------------------
+// Token cache (0600, keyed by origin)
+// ---------------------------------------------------------------------------
+/** Cache file path. Honours ORBOTO_MCP_TOKEN_CACHE for tests / custom homes. */
+export function tokenCachePath() {
+    const override = process.env.ORBOTO_MCP_TOKEN_CACHE;
+    if (override)
+        return override;
+    const base = process.env.XDG_CONFIG_HOME || join(homedir(), '.config');
+    return join(base, 'orboto', 'mcp-oauth.json');
+}
+function readCacheFile(path) {
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+export function loadCachedGrant(origin, path = tokenCachePath()) {
+    const file = readCacheFile(path);
+    return file[origin] ?? null;
+}
+export function saveCachedGrant(origin, grant, path = tokenCachePath()) {
+    const file = readCacheFile(path);
+    file[origin] = grant;
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(file, null, 2), { mode: 0o600 });
+    // writeFileSync's mode only applies on create; force 0600 on an existing file
+    // too so a cache written before this code shipped is tightened.
+    try {
+        chmodSync(path, 0o600);
+    }
+    catch { /* best-effort on platforms without chmod */ }
+}
+export function clearCachedGrant(origin, path = tokenCachePath()) {
+    const file = readCacheFile(path);
+    if (!(origin in file))
+        return;
+    delete file[origin];
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(file, null, 2), { mode: 0o600 });
+    try {
+        chmodSync(path, 0o600);
+    }
+    catch { /* best-effort */ }
+}
+/**
+ * Build a token provider around an initial token set + a refresh closure.
+ * Kept pure (no I/O of its own beyond the injected refresh fn) so the
+ * refresh-on-expiry logic unit tests deterministically with a fake clock.
+ */
+export function createTokenProvider(initial, refresh, onRefreshed, now = Date.now) {
+    let current = initial;
+    let inflight = null;
+    async function doRefresh() {
+        if (!current.refreshToken) {
+            throw new Error('OAuth session expired and no refresh token is available - reconnect the client.');
+        }
+        const next = await refresh(current.refreshToken);
+        // The AS rotates the refresh token; if a response omits it (shouldn't with
+        // offline_access) keep the prior one so the chain isn't lost.
+        current = { ...next, refreshToken: next.refreshToken ?? current.refreshToken };
+        onRefreshed?.(current);
+        return current.accessToken;
+    }
+    return {
+        async getAccessToken() {
+            if (now() < current.expiresAt - EXPIRY_SKEW_MS)
+                return current.accessToken;
+            if (!inflight)
+                inflight = doRefresh().finally(() => { inflight = null; });
+            return inflight;
+        },
+        async forceRefresh() {
+            if (!inflight)
+                inflight = doRefresh().finally(() => { inflight = null; });
+            return inflight;
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Interactive loopback flow (the I/O shell)
+// ---------------------------------------------------------------------------
+/** Open a URL in the user's default browser. Returns false if no opener is
+ *  available (headless) so the caller can print the URL for manual paste. */
+export async function openInBrowser(url) {
+    if (process.env.ORBOTO_MCP_NO_BROWSER === '1')
+        return false;
+    const platform = process.platform;
+    const cmd = platform === 'darwin' ? 'open' : platform === 'win32' ? 'cmd' : 'xdg-open';
+    const args = platform === 'win32' ? ['/c', 'start', '""', url] : [url];
+    try {
+        const { spawn } = await import('node:child_process');
+        const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Run the full browser-assisted loopback authorization once: spin an ephemeral
+ * loopback listener, open the consent URL, wait for the redirect carrying the
+ * code, exchange it. Returns the fresh token set + the client_id used (so the
+ * caller can persist the grant). Logs go to stderr (stdout is the JSON-RPC
+ * channel in stdio mode).
+ */
+export async function runLoopbackAuthorization(opts) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const log = opts.log ?? ((m) => process.stderr.write(`${m}\n`));
+    const open = opts.openBrowser ?? openInBrowser;
+    const scope = opts.scope ?? BOOTSTRAP_SCOPE;
+    const pkce = generatePkce();
+    const state = generateState();
+    return await new Promise((resolve, reject) => {
+        const server = createServer();
+        let settled = false;
+        const timeout = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            server.close();
+            reject(new Error('OAuth authorization timed out waiting for the browser redirect.'));
+        }, opts.timeoutMs ?? 5 * 60_000);
+        server.on('request', async (req, res) => {
+            try {
+                const reqUrl = new URL(req.url ?? '/', 'http://127.0.0.1');
+                if (reqUrl.pathname !== '/callback') {
+                    res.writeHead(404).end('Not found');
+                    return;
+                }
+                const code = reqUrl.searchParams.get('code');
+                const returnedState = reqUrl.searchParams.get('state');
+                const err = reqUrl.searchParams.get('error');
+                if (err)
+                    throw new Error(`Authorization denied: ${err}`);
+                if (!code)
+                    throw new Error('Authorization callback missing code');
+                if (returnedState !== state)
+                    throw new Error('Authorization state mismatch (possible CSRF)');
+                const addr = server.address();
+                const port = typeof addr === 'object' && addr ? addr.port : 0;
+                const redirectUri = `http://127.0.0.1:${port}/callback`;
+                const clientId = server._orbotoClientId;
+                const tokens = await exchangeAuthCode(opts.meta.token_endpoint, { clientId, code, redirectUri, verifier: pkce.verifier }, fetchImpl);
+                res.writeHead(200, { 'Content-Type': 'text/html' }).end('<!doctype html><meta charset="utf-8"><title>orboto</title>' +
+                    '<body style="font-family:system-ui;padding:3rem;text-align:center">' +
+                    '<h2>Connected to orboto</h2><p>You can close this tab and return to your AI client.</p></body>');
+                if (!settled) {
+                    settled = true;
+                    clearTimeout(timeout);
+                    server.close();
+                    resolve({ tokens, clientId });
+                }
+            }
+            catch (e) {
+                res.writeHead(400, { 'Content-Type': 'text/plain' }).end(e.message);
+                if (!settled) {
+                    settled = true;
+                    clearTimeout(timeout);
+                    server.close();
+                    reject(e);
+                }
+            }
+        });
+        server.on('error', (e) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            reject(e);
+        });
+        // Bind to an ephemeral loopback port, THEN register the client at that exact
+        // redirect_uri (the api allows any loopback port at authorize time per RFC
+        // 8252, but DCR still needs a concrete uri).
+        server.listen(0, '127.0.0.1', async () => {
+            try {
+                const addr = server.address();
+                const port = typeof addr === 'object' && addr ? addr.port : 0;
+                const redirectUri = `http://127.0.0.1:${port}/callback`;
+                const clientId = await registerLoopbackClient(opts.meta.registration_endpoint, redirectUri, fetchImpl);
+                server._orbotoClientId = clientId;
+                const authorizeUrl = buildAuthorizeUrl(opts.meta.authorization_endpoint, {
+                    clientId, redirectUri, challenge: pkce.challenge, state, scope,
+                });
+                const opened = await open(authorizeUrl);
+                if (opened) {
+                    log(`[orboto-mcp] opened your browser to authorize. If it did not open, visit:\n${authorizeUrl}`);
+                }
+                else {
+                    log(`[orboto-mcp] open this URL in a browser to authorize:\n${authorizeUrl}`);
+                }
+            }
+            catch (e) {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timeout);
+                server.close();
+                reject(e);
+            }
+        });
+    });
+}
+// ---------------------------------------------------------------------------
+// Top-level bootstrap: cache -> refresh -> interactive, returns a provider
+// ---------------------------------------------------------------------------
+/**
+ * Resolve an OAuth token provider for the stdio proxy. Order:
+ *   1. A cached grant whose refresh token still works -> silent refresh.
+ *   2. Otherwise run the interactive browser-assisted loopback flow once.
+ * Either way the resulting grant is persisted (0600) so the next boot is
+ * silent. The returned provider auto-refreshes and re-persists on rotation.
+ */
+export async function bootstrapOAuth(opts) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const log = opts.log ?? ((m) => process.stderr.write(`${m}\n`));
+    const origin = deriveOrigin(opts.apiBaseUrl);
+    const cachePath = opts.cachePath ?? tokenCachePath();
+    const persist = (clientId, tokenEndpoint, tokens) => {
+        if (tokens.refreshToken) {
+            saveCachedGrant(origin, {
+                clientId, tokenEndpoint, refreshToken: tokens.refreshToken, scope: tokens.scope,
+            }, cachePath);
+        }
+    };
+    const cached = loadCachedGrant(origin, cachePath);
+    if (cached) {
+        try {
+            const tokens = await refreshTokens(cached.tokenEndpoint, {
+                clientId: cached.clientId, refreshToken: cached.refreshToken,
+            }, fetchImpl);
+            persist(cached.clientId, cached.tokenEndpoint, tokens);
+            log('[orboto-mcp] reconnected via cached OAuth session (no browser needed)');
+            return createTokenProvider(tokens, (rt) => refreshTokens(cached.tokenEndpoint, { clientId: cached.clientId, refreshToken: rt }, fetchImpl), (next) => persist(cached.clientId, cached.tokenEndpoint, next));
+        }
+        catch (e) {
+            // A revoked / expired refresh token drops us back to interactive.
+            log(`[orboto-mcp] cached OAuth session no longer valid (${e.message}); re-authorizing`);
+            clearCachedGrant(origin, cachePath);
+        }
+    }
+    const meta = await discoverAuthServer(origin, fetchImpl);
+    const { tokens, clientId } = await runLoopbackAuthorization({
+        meta, log, openBrowser: opts.openBrowser, fetchImpl,
+    });
+    persist(clientId, meta.token_endpoint, tokens);
+    log('[orboto-mcp] OAuth authorization complete');
+    return createTokenProvider(tokens, (rt) => refreshTokens(meta.token_endpoint, { clientId, refreshToken: rt }, fetchImpl), (next) => persist(clientId, meta.token_endpoint, next));
+}