@reclaimprotocol/agent 0.1.22 → 0.1.23

package/lib/authoring/backend.d.ts

@@ -61,13 +61,15 @@ export interface AuthoringBackend {
      *  the cloud publish step) — that side effect is the backend's, not ours. */
     prove(draft: Draft, opts?: ProveOptions): Promise<unknown>;
     /**
-     * Validate/replay a drafted recipe before proving. With `withoutSecrets` it
-     * is the AUTH-BOUND check: re-issue the request stripped of the captured
-     * secrets (local: a Node re-fetch without them; remote: an anonymous `fetch`
-     * in the Popcorn page, `credentials: 'omit'`) and report whether the values
-     * are STILL extractable — i.e. the endpoint is public. Without it, validate
-     * extraction for the authenticated request. The shape is environment-specific
-     * and passed straight through as the tool's result.
+     * Validate/replay a drafted recipe before proving. Both local and remote
+     * backends re-issue the request FROM INSIDE the live attached page (a
+     * `fetch` run over CDP), never a detached out-of-band call, so replay
+     * always reflects the real browser session. With `withoutSecrets` it is
+     * the AUTH-BOUND check: re-issue anonymously (`credentials: 'omit'`, no
+     * secret headers) and report whether the values are STILL extractable —
+     * i.e. the endpoint is public. Without it, validate extraction for the
+     * authenticated request. The shape is environment-specific and passed
+     * straight through as the tool's result.
      */
     replay(draft: Draft, opts?: {
         withoutSecrets?: boolean;

package/lib/authoring/tools.js

@@ -120,6 +120,97 @@ export function authoringTools(resolveBackend) {
             }
             return { ready: false };
         }),
+        defineTool({
+            name: 'test_user_script',
+            description: 'Dry-run a USER SCRIPT — the same thing as the `jsUserScripts` / '
+                + '`customInjection` field on a published provider: plain browser '
+                + 'JS that runs before every page load, used to drive navigation '
+                + 'for data gated behind login/routing — in the LIVE attached tab, '
+                + 'BEFORE publishing. Installs `script` via CDP so it runs on the '
+                + 'next navigation exactly like the real field would, then reports '
+                + 'whether it ran and any errors it threw. Catches bugs (e.g. a '
+                + 'listener registered with setTimeout that never fires because the '
+                + "page was already past 'load' by the time it ran) before they "
+                + 'surface in a real end-user session instead of after. If '
+                + '`navigateUrl` is given, navigates there after installing, then '
+                + 'removes the script again once the result is read (self-cleaning '
+                + '— safe to call repeatedly). Without `navigateUrl` the script is '
+                + 'left installed for you to navigate yourself (any way you like) '
+                + 'then re-call this tool, or read '
+                + '`window.__reclaimUserScriptResult` via eval_in_page — in that '
+                + 'manual mode it is NOT auto-removed and keeps running on every '
+                + 'later navigation until a follow-up call with `navigateUrl` '
+                + 'removes it, so avoid stacking several manual-mode calls in a '
+                + 'row.',
+            inputSchema: objectSchema({
+                script: { type: 'string' },
+                navigateUrl: { type: 'string' },
+                timeoutMs: { type: 'number' },
+            }, ['script']),
+        }, async (args) => {
+            const backend = resolveBackend(args);
+            const script = String(args.script);
+            // The user's script is spliced in as a STRING and compiled at
+            // runtime via `new Function`, not as raw top-level source: a
+            // syntax error in it would otherwise fail to parse the entire
+            // wrapper (result init, error listener, and try/catch included),
+            // so the tool would report ran:false / errors:[] instead of the
+            // actual SyntaxError.
+            const wrapped = `
+					window.__reclaimUserScriptResult = { ran: false, errors: [] };
+					window.addEventListener('error', function(e) {
+						window.__reclaimUserScriptResult.errors.push(String(e.message));
+					});
+					try {
+						(new Function(${JSON.stringify(script)}))();
+						window.__reclaimUserScriptResult.ran = true;
+					} catch(e) {
+						window.__reclaimUserScriptResult.errors.push(
+							String((e && e.message) || e),
+						);
+					}
+				`;
+            const installed = (await backend.sendCdp('Page.addScriptToEvaluateOnNewDocument', { source: wrapped }));
+            if (typeof args.navigateUrl !== 'string') {
+                return {
+                    installed: true,
+                    note: 'Installed for the NEXT navigation only — it did not run on '
+                        + 'the current page, and stays installed (runs on every later '
+                        + 'navigation too) until a follow-up call with navigateUrl '
+                        + 'removes it. Navigate now (e.g. the navigate tool), then read '
+                        + 'window.__reclaimUserScriptResult via eval_in_page, or call '
+                        + 'test_user_script again with navigateUrl.',
+                };
+            }
+            try {
+                const timeoutMs = Number(args.timeoutMs) || 30000;
+                await backend.sendCdp('Page.enable');
+                const load = backend.waitForEvent('Page.loadEventFired', timeoutMs);
+                const nav = (await backend.sendCdp('Page.navigate', { url: String(args.navigateUrl) }));
+                if (nav.errorText) {
+                    return { installed: true, navigated: false, error: nav.errorText };
+                }
+                await load;
+                const { value, error } = await evalInPage(backend, 'window.__reclaimUserScriptResult');
+                if (error) {
+                    return { installed: true, navigated: true, error };
+                }
+                const result = value;
+                return {
+                    installed: true,
+                    navigated: true,
+                    ran: result?.ran ?? false,
+                    errors: result?.errors ?? [],
+                };
+            }
+            finally {
+                // One-shot test: remove it so it doesn't keep running (and
+                // potentially redirecting the tab) on every later navigation.
+                if (installed.identifier) {
+                    await backend.sendCdp('Page.removeScriptToEvaluateOnNewDocument', { identifier: installed.identifier });
+                }
+            }
+        }),
         defineTool({
             name: 'get_cookies',
             description: 'List the NAMES of cookies currently set for the page (values are '
@@ -236,7 +327,13 @@ export function authoringTools(resolveBackend) {
         defineTool({
             name: 'run_proof',
             description: 'Prove the drafted recipe (zkTLS). Only call after replay_request '
-                + 'looks right. Returns the proof result.',
+                + 'looks right. Returns the proof result. NOTE: unlike '
+                + 'replay_request (which re-issues from inside the live attached '
+                + 'browser tab), the ATTESTOR calls the target from its OWN '
+                + 'network/IP, separate from the browser\'s. A request that '
+                + 'replayed fine can still fail here for geo/IP-bound content '
+                + '(country-locked pages, IP-allowlisted APIs) — if that happens, '
+                + 'it\'s a property of the site, not a bug in the draft.',
             inputSchema: objectSchema({ draftId: { type: 'string' } }, ['draftId']),
         }, 
         // The backend shapes its own result: the cloud returns a lean,

package/lib/mcp/tools/agent/propose.js

@@ -19,17 +19,38 @@ export function proposeTool(resolveBackend) {
             + 'one match + redaction per target. Returns a draftId + recipe '
             + '(never secrets). Prefer a SINGLE request holding ALL values. '
             + 'Single-value shorthand: `target` + `name`. Per-target `hash` '
-            + 'OPRF-hashes that value.',
+            + 'OPRF-hashes that value. BY DEFAULT each `name` is shortened to '
+            + 'its last alphanumeric token, lowercased, to form the param key '
+            + '(e.g. "employer_name" → "name") — pick names that stay distinct '
+            + 'after shortening ("firstName"/"surname", not "first_name"/'
+            + '"last_name"). Pass `shortenNames: false` to use each `name` '
+            + 'VERBATIM as the param key instead — it becomes both a regex '
+            + 'capture-group name and a paramValues key, so it must be a plain '
+            + 'identifier (letters/digits/underscore, not starting with a '
+            + 'digit); we recommend lower_snake_case (e.g. "employer_name"), '
+            + 'but you choose the exact name.',
         inputSchema: objectSchema({
             requestId: { type: 'string' },
             name: { type: 'string' },
+            shortenNames: {
+                type: 'boolean',
+                description: 'Default true: shorten each target `name` to its last '
+                    + 'alphanumeric token, lowercased, to form the param key. '
+                    + 'Set false to use `name` verbatim instead (must be a plain '
+                    + 'identifier — lower_snake_case recommended).',
+            },
             targets: {
                 type: 'array',
                 items: {
                     type: 'object',
                     properties: {
                         value: { type: 'string' },
-                        name: { type: 'string' },
+                        name: {
+                            type: 'string',
+                            description: 'The param key, or the source of one — see '
+                                + '`shortenNames`. Must stay distinct from other targets\' '
+                                + 'names after whichever treatment applies.',
+                        },
                         hash: {
                             type: 'string',
                             enum: ['oprf-raw', 'oprf', 'oprf-mpc'],
@@ -46,6 +67,9 @@ export function proposeTool(resolveBackend) {
         const requestId = String(args.requestId);
         const providerName = String(args.name);
         const defaultHash = args.hash;
+        const shortenNames = typeof args.shortenNames === 'boolean'
+            ? args.shortenNames
+            : true;
         // Explicit multi-value `targets`, else the single `target` shorthand.
         const raw = Array.isArray(args.targets) ? args.targets : [];
         const targets = raw.length
@@ -85,7 +109,7 @@ export function proposeTool(resolveBackend) {
         if (!captured.responseBody) {
             throw new Error(`request body unavailable for ${requestId}`);
         }
-        const { provider, secretRefs, extractions } = draftProvider(captured, targets, providerName, defaultHash);
+        const { provider, secretRefs, extractions } = draftProvider(captured, targets, providerName, defaultHash, { shortenNames });
         // Materialize the real secret header values for later replay/prove;
         // they stay in the server-side draft, never in this result.
         const secrets = {};

package/lib/mcp/tools/agent/publish.js

@@ -212,17 +212,19 @@ export function createVersionFromCaptureTool(client, attachRef) {
                 interceptorOptions: {
                     type: 'object',
                     description: 'In-app interception settings, stored as ' +
-                        'webSettings.clientOptions.inapp.interceptorOptions. ' +
-                        '`isDocumentRequestReplayEnabled` is the INVERSE of ' +
-                        'old-devtools\' `disableRequestReplay`: true replays the ' +
-                        'main document request via the attestor (default false).',
+                        'webSettings.clientOptions.inapp.interceptorOptions — only ' +
+                        'needed for a genuine live-interception provider (a real ' +
+                        'HAWKEYE/MSWJS script, not the standard capture→replay flow). ' +
+                        'Document replay (webSettings.clientOptions.inapp' +
+                        '.interceptorOptions.isDocumentRequestReplayEnabled) is ' +
+                        'ALWAYS published disabled regardless of this field — there ' +
+                        'is no way to enable it here.',
                     properties: {
                         interceptorType: {
                             type: 'string',
                             enum: ['HAWKEYE', 'MSWJS', 'CDP'],
                             description: 'How traffic interception is implemented.',
                         },
-                        isDocumentRequestReplayEnabled: { type: 'boolean' },
                         interceptorSettings: {
                             type: 'string',
                             description: 'Free-form JSON config for the chosen interceptor.',

package/lib/mcp/tools/agent/shared.js

@@ -9,7 +9,7 @@
  */
 import { authoringTools, extendTool, } from "../../../authoring/index.js";
 import { runAttestorProof } from "../../../proof/attestor.js";
-import { replayProvider } from "../../../proof/replay.js";
+import { replayProviderInPage } from "../../../proof/page-replay.js";
 import { shapeRichProofResult } from "./proof.js";
 /**
  * OPRF mode this LOCAL (non-TEE) attestor can actually run. Recipes carry
@@ -39,13 +39,17 @@ function withLocalOprfMode(provider) {
     };
 }
 /** The local backend for one capture: drive its tab over CDP, read its
- *  captured requests, prove via the in-process attestor, replay by re-fetch. */
+ *  captured requests, prove via the in-process attestor, replay by re-fetching
+ *  FROM INSIDE the tab (real cookies/session — see proof/page-replay.ts). */
 function localBackend(entry) {
     const { tabClient, session, drafts } = entry;
+    const sendCdp = (method, params) => {
+        return tabClient.send(method, params ?? {});
+    };
     return {
         capture: session,
         drafts,
-        sendCdp: (method, params) => tabClient.send(method, params ?? {}),
+        sendCdp,
         waitForEvent: (method, timeoutMs) => new Promise((resolve) => {
             let stopListening = () => { };
             const onEvent = () => {
@@ -63,10 +67,9 @@ function localBackend(entry) {
             stopListening = tabClient.subscribeOnce(method, onEvent);
         }),
         replay: async (draft, opts) => {
-            // Auth-bound check: re-fetch with the secrets dropped. replayProvider
-            // already does a live Node fetch, so empty secrets == anonymous.
-            const secrets = opts?.withoutSecrets ? {} : draft.secrets;
-            const result = await replayProvider(draft.provider, secrets);
+            // Replayed FROM INSIDE the attached tab (real cookies/session), not
+            // a detached Node fetch — see proof/page-replay.ts.
+            const result = await replayProviderInPage({ sendCdp }, draft.provider, draft.secrets, opts);
             return {
                 status: result.status,
                 matchesOriginal: result.matchesOriginal,
@@ -105,7 +108,13 @@ const RUN_PROOF_EXTRAS = {
         + 'specific alternative — do NOT invent backup URLs. `ownerAddress` '
         + '(the credential to sign with) is REQUIRED — call resolve_owner_key '
         + 'first. errorKind="missing-owner-key" means that address has no known '
-        + 'private key; re-run resolve_owner_key or issue/import a credential.',
+        + 'private key; re-run resolve_owner_key or issue/import a credential. '
+        + 'NOTE: unlike replay_request (which re-issues from inside the live '
+        + 'attached browser tab), the ATTESTOR calls the target from its OWN '
+        + 'network/IP, separate from the browser\'s. A request that replayed '
+        + 'fine can still fail here for geo/IP-bound content (country-locked '
+        + "pages, IP-allowlisted APIs) — if that happens, it's a property of "
+        + 'the site, not a bug in the draft.',
     properties: {
         ownerAddress: {
             type: 'string',

package/lib/mcp/tools/authenticate/authenticate.d.ts

@@ -1,3 +1,14 @@
 import type { ReclaimClient } from '@reclaimprotocol/client';
 import { type RegisteredTool } from '../../server.ts';
 export declare function authenticateTool(client: ReclaimClient, name?: 'reclaim_authenticate' | 'authenticate_builder'): RegisteredTool;
+/**
+ * Standard OAuth 2.0 Authorization Code + PKCE, native-app style (RFC 8252):
+ * dynamically register a public client (RFC 7591 — Better Auth's
+ * `oauth-provider` plugin issues no secret for it), send the user to the
+ * browser, and catch the redirect on a loopback server. `openid-client`
+ * handles PKCE, `state` CSRF protection, and authorization-response
+ * validation (including a denied/failed login surfacing as
+ * `AuthorizationResponseError`) — this function only wires those calls
+ * together and owns the loopback server (no library spins that up for you).
+ */
+export declare function runOAuthLoopback(client: ReclaimClient, openBrowserFn?: (url: string) => void): Promise<unknown>;

package/lib/mcp/tools/authenticate/authenticate.js

@@ -1,7 +1,6 @@
-import assert from 'node:assert';
 import { spawn } from 'node:child_process';
-import { createHash, randomBytes } from 'node:crypto';
 import { createServer } from 'node:http';
+import * as oauth from 'openid-client';
 import { defineTool } from "../../server.js";
 import { writeSession } from "./session-cache.js";
 const SCOPE = 'openid profile email';
@@ -10,9 +9,17 @@ export function authenticateTool(client, name = 'reclaim_authenticate') {
     return defineTool({
         name,
         description: (name === 'authenticate_builder'
-            ? 'Authenticate specifically with Builder. Available regardless '
-                + 'of '
-                + 'the selected publishing backend. '
+            ? 'This tool only exists in OLD-DEVTOOLS mode — Builder mode has '
+                + 'no separate version of it; its own reclaim_authenticate '
+                + 'already covers everything below. In old-devtools mode, this '
+                + 'authenticates with Builder for exactly two Builder-exclusive '
+                + 'features: allocating a Popcorn remote browser (attach_browser '
+                + 'mode="builder") and listing Builder organizations '
+                + '(list_builder_organizations — old-devtools has no generated '
+                + 'org tool of its own). It does NOT authorize '
+                + 'create_provider_version_from_capture or get_me_providers, '
+                + 'which need their OWN, separate login via the old-devtools '
+                + 'reclaim_authenticate tool. Check both with get_devtools_mode. '
             : '')
             + 'Authorize the CLI / MCP to make authenticated API calls. Opens '
             + 'the '
@@ -27,38 +34,96 @@ export function authenticateTool(client, name = 'reclaim_authenticate') {
         inputSchema: { type: 'object', properties: {} },
     }, async () => runOAuthLoopback(client));
 }
-async function runOAuthLoopback(client) {
+const _customFetchForOauth = async (url, options) => {
+    const res = await fetch(url, options);
+    if (options.method === 'POST' && res.status === 200 &&
+        new URL(url).pathname.endsWith('/oauth2/register')) {
+        return new Response(await res.text(), {
+            status: 201,
+            headers: res.headers,
+        });
+    }
+    return res;
+};
+/**
+ * Standard OAuth 2.0 Authorization Code + PKCE, native-app style (RFC 8252):
+ * dynamically register a public client (RFC 7591 — Better Auth's
+ * `oauth-provider` plugin issues no secret for it), send the user to the
+ * browser, and catch the redirect on a loopback server. `openid-client`
+ * handles PKCE, `state` CSRF protection, and authorization-response
+ * validation (including a denied/failed login surfacing as
+ * `AuthorizationResponseError`) — this function only wires those calls
+ * together and owns the loopback server (no library spins that up for you).
+ */
+export async function runOAuthLoopback(client, 
+// Overridable only so tests can intercept the authorize URL instead of
+// actually spawning a browser; every real caller uses the default.
+openBrowserFn = openBrowser) {
     const authBase = `${client.baseUrl}/auth`;
-    const verifier = base64url(randomBytes(32));
-    const challenge = base64url(createHash('sha256').update(verifier).digest());
-    const state = base64url(randomBytes(16));
+    const codeVerifier = oauth.randomPKCECodeVerifier();
+    const codeChallenge = await oauth.calculatePKCECodeChallenge(codeVerifier);
+    const state = oauth.randomState();
     // Bind the callback port first: the client is registered for this exact
-    // loopback redirect, and the same client_id has to be presented again at the
-    // token endpoint (public clients authenticate by client_id alone).
-    const callback = await listenForCallback(state);
-    let token;
+    // loopback redirect.
+    const callback = await listenForCallback();
+    let tokens;
     try {
-        const clientId = await registerClient(authBase, callback.redirectUri);
-        openBrowser(authorizeUrl(authBase, {
-            clientId,
-            redirectUri: callback.redirectUri,
-            challenge,
+        const config = await oauth.dynamicClientRegistration(new URL(authBase), {
+            client_name: 'Reclaim CLI',
+            redirect_uris: [callback.redirectUri],
+            token_endpoint_auth_method: 'none',
+            grant_types: ['authorization_code', 'refresh_token'],
+            response_types: ['code'],
+            scope: SCOPE,
+        }, undefined, {
+            // Better Auth exposes its metadata at the RFC 8414 well-known path
+            // (`.well-known/oauth-authorization-server`), not the OIDC one.
+            algorithm: 'oauth2',
+            // RFC 7591 §3.2.1 requires 201 Created on a successful registration;
+            // openid-client enforces that strictly. Better Auth's
+            // `oauth-provider` plugin doesn't conform — confirmed live against
+            // the real server: `POST .../oauth2/register` returns 200 with an
+            // otherwise well-formed body, which openid-client rejects outright
+            // ("unexpected HTTP response status code") before ever looking at
+            // it. `customFetch` set here persists onto the returned
+            // `Configuration` for ALL its future calls too (token exchange
+            // included, which correctly returns 200) — so the URL itself, not
+            // just method+status, must gate the rewrite, or a genuine 200 from
+            // the token endpoint gets corrupted into a 201 and
+            // `authorizationCodeGrant` fails instead (confirmed by hitting
+            // exactly that when this only checked method === 'POST').
+            [oauth.customFetch]: _customFetchForOauth,
+        });
+        openBrowserFn(oauth.buildAuthorizationUrl(config, {
+            redirect_uri: callback.redirectUri,
+            scope: SCOPE,
             state,
-        }));
-        const code = await callback.code;
-        token = await exchangeCode(authBase, {
-            code,
-            verifier,
-            redirectUri: callback.redirectUri,
-            clientId,
+            code_challenge: codeChallenge,
+            code_challenge_method: 'S256',
+        }).href);
+        const callbackUrl = await callback.url;
+        tokens = await oauth.authorizationCodeGrant(config, callbackUrl, {
+            pkceCodeVerifier: codeVerifier,
+            expectedState: state,
         });
     }
+    catch (err) {
+        // A denied or failed authorization surfaces as this error class with
+        // the raw callback params on `.cause` — reword it like the previous
+        // hand-rolled check did (RFC 6749 §4.1.2.1's error/error_description).
+        if (err instanceof oauth.AuthorizationResponseError) {
+            throw new Error(err.cause.get('error_description')
+                ?? err.cause.get('error')
+                ?? 'Sign-in failed or was cancelled.');
+        }
+        throw err;
+    }
     finally {
         callback.close();
     }
-    const expiresAt = new Date(Date.now() + token.expires_in * 1000).toISOString();
-    writeSession({ token: token.access_token, expiresAt });
-    client.setToken(token.access_token);
+    const expiresAt = new Date(Date.now() + (tokens.expires_in ?? 3600) * 1000).toISOString();
+    writeSession({ token: tokens.access_token, expiresAt });
+    client.setToken(tokens.access_token);
     return {
         status: 'AUTHENTICATED',
         note: 'Access token cached in ~/.reclaim/config.json and active now.',
@@ -67,42 +132,23 @@ async function runOAuthLoopback(client) {
 }
 /**
  * Bind an ephemeral loopback port and start listening for the provider's
- * redirect. Resolves as soon as the port is known — the `code` promise settles
+ * redirect. Resolves as soon as the port is known — the `url` promise settles
  * later, when the browser hits `/callback` — so the caller can register a
  * client for this exact redirect URI before sending the user off to authorize.
- * The ephemeral port lets any number of CLIs run concurrently. Defined below
- * its caller per repo convention.
+ * The ephemeral port lets any number of CLIs run concurrently. Hands back the
+ * RAW callback URL rather than picking `code`/`state` apart itself —
+ * `oauth.authorizationCodeGrant` does that validation. Defined below its
+ * caller per repo convention.
  */
-async function listenForCallback(state) {
-    let resolveCode;
-    let rejectCode;
-    const code = new Promise((resolve, reject) => {
-        resolveCode = resolve;
-        rejectCode = reject;
+async function listenForCallback() {
+    let resolveUrl;
+    let rejectUrl;
+    const url = new Promise((resolve, reject) => {
+        resolveUrl = resolve;
+        rejectUrl = reject;
     });
     const server = createServer();
-    const timer = setTimeout(() => rejectCode(new Error('Timed out waiting for sign-in (5 min).')), CALLBACK_TIMEOUT_MS);
-    server.on('request', (req, res) => {
-        const url = new URL(req.url ?? '/', 'http://127.0.0.1');
-        if (url.pathname !== '/callback') {
-            res.writeHead(404).end();
-            return;
-        }
-        res.writeHead(200, { 'content-type': 'text/html' });
-        res.end('<!doctype html><meta charset=utf-8><body style="font:16px '
-            + 'system-ui;padding:3rem;text-align:center">Signed in. You can '
-            + 'close this tab and return to your terminal.</body>');
-        const authCode = url.searchParams.get('code');
-        if (!authCode || url.searchParams.get('state') !== state) {
-            // A denied or failed authorization comes back as `error`/
-            // `error_description` (RFC 6749 §4.1.2.1) — surface it verbatim.
-            const err = url.searchParams.get('error_description')
-                ?? url.searchParams.get('error');
-            rejectCode(new Error(err ?? 'Sign-in failed or was cancelled.'));
-            return;
-        }
-        resolveCode(authCode);
-    });
+    const timer = setTimeout(() => rejectUrl(new Error('Timed out waiting for sign-in (5 min).')), CALLBACK_TIMEOUT_MS);
     const port = await new Promise((resolve, reject) => {
         server.once('error', reject);
         server.listen(0, '127.0.0.1', () => {
@@ -113,75 +159,38 @@ async function listenForCallback(state) {
             }
             resolve(addr.port);
         });
+    }).catch((err) => {
+        // Bind failed before `close()` (returned below) is ever reachable —
+        // clear the timer ourselves, or it fires 5 minutes later and rejects
+        // the now-unobserved `url` promise (unhandled rejection) while keeping
+        // the process alive in the meantime.
+        clearTimeout(timer);
+        throw err;
     });
     // Past bind, a socket error fails the pending wait rather than throwing.
-    server.on('error', (err) => rejectCode(err));
+    server.on('error', (err) => rejectUrl(err));
+    const redirectUri = `http://127.0.0.1:${port}/callback`;
+    server.on('request', (req, res) => {
+        const reqUrl = new URL(req.url ?? '/', redirectUri);
+        if (reqUrl.pathname !== '/callback') {
+            res.writeHead(404).end();
+            return;
+        }
+        res.writeHead(200, { 'content-type': 'text/html' });
+        res.end('<!doctype html><meta charset=utf-8><body style="font:16px '
+            + 'system-ui;padding:3rem;text-align:center">Signed in. You can '
+            + 'close this tab and return to your terminal.</body>');
+        resolveUrl(reqUrl);
+    });
     return {
-        redirectUri: `http://127.0.0.1:${port}/callback`,
-        code,
+        redirectUri,
+        url,
         close: () => {
             clearTimeout(timer);
             server.close();
         },
     };
 }
-function authorizeUrl(authBase, opts) {
-    return `${authBase}/oauth2/authorize?`
-        + new URLSearchParams({
-            response_type: 'code',
-            client_id: opts.clientId,
-            redirect_uri: opts.redirectUri,
-            scope: SCOPE,
-            state: opts.state,
-            code_challenge: opts.challenge,
-            code_challenge_method: 'S256',
-        }).toString();
-}
-/** Dynamic client registration (RFC 7591) for a public PKCE client. */
-async function registerClient(authBase, redirectUri) {
-    const res = await fetch(`${authBase}/oauth2/register`, {
-        method: 'POST',
-        headers: { 'content-type': 'application/json' },
-        body: JSON.stringify({
-            client_name: 'Reclaim CLI',
-            redirect_uris: [redirectUri],
-            token_endpoint_auth_method: 'none',
-            grant_types: ['authorization_code', 'refresh_token'],
-            response_types: ['code'],
-            scope: SCOPE,
-        }),
-    });
-    assert(res.ok, new Error(`Client registration failed (${res.status}).`));
-    const json = (await res.json());
-    assert(json.client_id, new Error('Client registration returned no client_id.'));
-    return json.client_id;
-}
-async function exchangeCode(authBase, opts) {
-    const res = await fetch(`${authBase}/oauth2/token`, {
-        method: 'POST',
-        headers: { 'content-type': 'application/x-www-form-urlencoded' },
-        body: new URLSearchParams({
-            grant_type: 'authorization_code',
-            code: opts.code,
-            redirect_uri: opts.redirectUri,
-            code_verifier: opts.verifier,
-            // Required even though this is a public client with no secret: it's
-            // how the token endpoint identifies the client (RFC 6749 §4.1.3).
-            client_id: opts.clientId,
-        }).toString(),
-    });
-    const body = await res.text();
-    assert(res.ok, new Error(`Token exchange failed (${res.status}): ${body}`));
-    const json = JSON.parse(body);
-    assert(json.access_token, new Error('Token exchange returned no access_token.'));
-    return {
-        access_token: json.access_token,
-        expires_in: json.expires_in ?? 3600,
-    };
-}
-function base64url(buf) {
-    return buf.toString('base64url');
-}
 function openBrowser(url) {
     const cmd = process.platform === 'darwin'
         ? 'open'

package/lib/mcp/tools/authenticate/builder-access.d.ts

@@ -1,8 +1,13 @@
 import type { ReclaimClient } from '@reclaimprotocol/client';
 import { type RegisteredTool } from '../../server.ts';
-/** Legacy-devtools mode needs a distinct Builder login solely for allocating
- * quota-accounted Popcorn sessions. Builder mode uses its native auth tool. */
+/** Legacy-devtools mode needs a distinct Builder login for its two
+ * Builder-exclusive features: allocating quota-accounted Popcorn sessions
+ * (see `buildBuilderOrganizationTools` below) and listing Builder
+ * organizations. Builder mode needs neither — its native auth tool alone
+ * covers both, org listing included (via its generated `list_orgs`). */
 export declare function buildBuilderAuthenticationTools(client: ReclaimClient): RegisteredTool[];
 /** Legacy-devtools mode lacks generated Builder API tools, so it needs this
- * narrow organization-discovery bridge for remote-browser allocation. */
+ * narrow organization-discovery bridge — an org id is required to allocate a
+ * remote-browser (Popcorn) session. Builder mode's own `list_orgs` already
+ * covers this under its native auth. */
 export declare function buildBuilderOrganizationTools(client: ReclaimClient): RegisteredTool[];

package/lib/mcp/tools/authenticate/builder-access.js

@@ -1,12 +1,17 @@
 import { defineTool } from "../../server.js";
 import { authenticateTool } from "./authenticate.js";
-/** Legacy-devtools mode needs a distinct Builder login solely for allocating
- * quota-accounted Popcorn sessions. Builder mode uses its native auth tool. */
+/** Legacy-devtools mode needs a distinct Builder login for its two
+ * Builder-exclusive features: allocating quota-accounted Popcorn sessions
+ * (see `buildBuilderOrganizationTools` below) and listing Builder
+ * organizations. Builder mode needs neither — its native auth tool alone
+ * covers both, org listing included (via its generated `list_orgs`). */
 export function buildBuilderAuthenticationTools(client) {
     return [authenticateTool(client, 'authenticate_builder')];
 }
 /** Legacy-devtools mode lacks generated Builder API tools, so it needs this
- * narrow organization-discovery bridge for remote-browser allocation. */
+ * narrow organization-discovery bridge — an org id is required to allocate a
+ * remote-browser (Popcorn) session. Builder mode's own `list_orgs` already
+ * covers this under its native auth. */
 export function buildBuilderOrganizationTools(client) {
     return [
         defineTool({