@reclaimprotocol/agent 0.1.22 → 0.1.23

package/src/mcp/tools/agent/propose.ts

@@ -23,18 +23,41 @@ export function proposeTool(resolveBackend: ResolveBackend): RegisteredTool {
 				+ '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'],
@@ -54,6 +77,9 @@ export function proposeTool(resolveBackend: ResolveBackend): RegisteredTool {
 			const requestId = String(args.requestId)
 			const providerName = String(args.name)
 			const defaultHash = args.hash as OprfMode | undefined
+			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 : []
@@ -103,7 +129,7 @@ export function proposeTool(resolveBackend: ResolveBackend): RegisteredTool {
 			}
 
 			const { provider, secretRefs, extractions } = draftProvider(
-				captured, targets, providerName, defaultHash,
+				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.

package/src/mcp/tools/agent/publish.ts

@@ -136,7 +136,6 @@ interface PublishArgs {
 	allowedJsRequests?: AllowedJsRequest[]
 	interceptorOptions?: {
 		interceptorType: 'HAWKEYE' | 'MSWJS' | 'CDP'
-		isDocumentRequestReplayEnabled?: boolean
 		interceptorSettings?: string
 	}
 }
@@ -268,17 +267,19 @@ export function createVersionFromCaptureTool(
 						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:

package/src/mcp/tools/agent/shared.ts

@@ -13,7 +13,7 @@ import {
 	extendTool,
 } from '../../../authoring/index.ts'
 import { runAttestorProof } from '../../../proof/attestor.ts'
-import { replayProvider } from '../../../proof/replay.ts'
+import { replayProviderInPage } from '../../../proof/page-replay.ts'
 import type { OprfMode, ReclaimProvider } from '../../../provider/schema.ts'
 import type { RegisteredTool } from '../../server.ts'
 import type { CaptureEntry, CaptureStore } from './capture.ts'
@@ -51,14 +51,18 @@ function withLocalOprfMode(provider: ReclaimProvider): ReclaimProvider {
 }
 
 /** 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: CaptureEntry): AuthoringBackend {
 	const { tabClient, session, drafts } = entry
+	const sendCdp = (method: string, params?: Record<string, unknown>) => {
+		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 = () => {}
 
@@ -79,10 +83,11 @@ function localBackend(entry: CaptureEntry): AuthoringBackend {
 			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,
@@ -127,7 +132,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/src/mcp/tools/authenticate/authenticate.ts

@@ -1,8 +1,7 @@
 import type { ReclaimClient } from '@reclaimprotocol/client'
-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, type RegisteredTool } from '../../server.ts'
 import { writeSession } from './session-cache.ts'
 
@@ -19,9 +18,17 @@ export function authenticateTool(
 			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 '
@@ -39,43 +46,117 @@ export function authenticateTool(
 	)
 }
 
-async function runOAuthLoopback(client: ReclaimClient): Promise<unknown> {
+const _customFetchForOauth: oauth.CustomFetch = async(
+	url: string,
+	options: oauth.CustomFetchOptions,
+) => {
+	const res = await fetch(url, options as RequestInit)
+	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: ReclaimClient,
+	// Overridable only so tests can intercept the authorize URL instead of
+	// actually spawning a browser; every real caller uses the default.
+	openBrowserFn: (url: string) => void = openBrowser,
+): Promise<unknown> {
 	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: { access_token: string, expires_in: number }
+	// loopback redirect.
+	const callback = await listenForCallback()
+	let tokens: oauth.TokenEndpointResponse
 	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,
-			}),
+				code_challenge: codeChallenge,
+				code_challenge_method: 'S256',
+			}).href,
 		)
-		const code = await callback.code
-		token = await exchangeCode(authBase, {
-			code,
-			verifier,
-			redirectUri: callback.redirectUri,
-			clientId,
+		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,
+		Date.now() + (tokens.expires_in ?? 3600) * 1000,
 	).toISOString()
-	writeSession({ token: token.access_token, expiresAt })
-	client.setToken(token.access_token)
+	writeSession({ token: tokens.access_token, expiresAt })
+	client.setToken(tokens.access_token)
 
 	return {
 		status: 'AUTHENTICATED',
@@ -86,57 +167,32 @@ async function runOAuthLoopback(client: ReclaimClient): Promise<unknown> {
 
 /**
  * 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: string): Promise<{
+async function listenForCallback(): Promise<{
 	redirectUri: string
-	code: Promise<string>
+	url: Promise<URL>
 	close: () => void
 }> {
-	let resolveCode: (code: string) => void
-	let rejectCode: (err: Error) => void
-	const code = new Promise<string>((resolve, reject) => {
-		resolveCode = resolve
-		rejectCode = reject
+	let resolveUrl: (url: URL) => void
+	let rejectUrl: (err: Error) => void
+	const url = new Promise<URL>((resolve, reject) => {
+		resolveUrl = resolve
+		rejectUrl = reject
 	})
 
 	const server = createServer()
 	const timer = setTimeout(
-		() => rejectCode(new Error('Timed out waiting for sign-in (5 min).')),
+		() => rejectUrl(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 port = await new Promise<number>((resolve, reject) => {
 		server.once('error', reject)
 		server.listen(0, '127.0.0.1', () => {
@@ -148,13 +204,37 @@ async function listenForCallback(state: string): Promise<{
 
 			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()
@@ -162,99 +242,6 @@ async function listenForCallback(state: string): Promise<{
 	}
 }
 
-function authorizeUrl(
-	authBase: string,
-	opts: {
-		clientId: string
-		redirectUri: string
-		challenge: string
-		state: string
-	},
-): string {
-	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: string,
-	redirectUri: string,
-): Promise<string> {
-	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()) as { client_id?: string }
-	assert(
-		json.client_id,
-		new Error('Client registration returned no client_id.'),
-	)
-
-	return json.client_id
-}
-
-async function exchangeCode(
-	authBase: string,
-	opts: {
-		code: string
-		verifier: string
-		redirectUri: string
-		clientId: string
-	},
-): Promise<{ access_token: string, expires_in: number }> {
-	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) as {
-		access_token?: string
-		expires_in?: number
-	}
-	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: Buffer): string {
-	return buf.toString('base64url')
-}
-
 function openBrowser(url: string) {
 	const cmd = process.platform === 'darwin'
 		? 'open'

package/src/mcp/tools/authenticate/builder-access.ts

@@ -2,8 +2,11 @@ import type { ReclaimClient } from '@reclaimprotocol/client'
 import { defineTool, type RegisteredTool } from '../../server.ts'
 import { authenticateTool } from './authenticate.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 function buildBuilderAuthenticationTools(
 	client: ReclaimClient,
 ): RegisteredTool[] {
@@ -11,7 +14,9 @@ export function buildBuilderAuthenticationTools(
 }
 
 /** 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: ReclaimClient,
 ): RegisteredTool[] {

package/src/mcp/tools/mode/mode.ts

@@ -3,6 +3,20 @@ import { defaultConfigPath } from '../../../config/store.ts'
 import { oldModeSource } from '../../../consts.ts'
 import { defineTool, type RegisteredTool } from '../../server.ts'
 
+/** Whether `config`'s cached builder session token is present and not yet
+ *  expired. Mirrors `readSession`'s check, but against the CALLER's
+ *  `ConfigStore` instance (not always the default `~/.reclaim/config.json`
+ *  path) so this stays test-isolatable and consistent with the rest of this
+ *  tool's config reads. */
+function hasValidBuilderSession(config: ConfigStore): boolean {
+	const session = config.read()?.session
+	if(!session?.token || !session.expiresAt) {
+		return false
+	}
+
+	return new Date(session.expiresAt) > new Date()
+}
+
 /**
  * The `set_devtools_mode` / `get_devtools_mode` tools: persist which backend
  * the MCP server targets (`old` devtools vs the `builder`), and
@@ -65,16 +79,35 @@ export function buildModeTools(
 					+ 'backend). Also reports WHY that mode is in effect (source: '
 					+ 'a USE_OLD_DEVTOOLS env override, the persisted config, or '
 					+ 'the default) and which mode is persisted for the next '
-					+ 'start. Use set_devtools_mode to change it.',
+					+ 'start. Use set_devtools_mode to change it. Also reports '
+					+ 'AUTH status for BOTH auth systems — builderAuthenticated (the '
+					+ 'Builder OAuth login). In BUILDER mode this is the only login '
+					+ 'that exists and covers everything, including org listing '
+					+ '(list_orgs) and remote-browser allocation. In OLD-DEVTOOLS '
+					+ 'mode it is a SEPARATE, additional login (authenticate_builder) '
+					+ 'needed only for two Builder-exclusive features: remote-browser '
+					+ '(Popcorn) allocation and org listing (list_builder_organizations '
+					+ '— old-devtools has no generated org tool of its own). '
+					+ 'oldDevtoolsAuthenticated (the OLD-mode reclaim_authenticate) is '
+					+ 'required separately for create_provider_version_from_capture '
+					+ 'and get_me_providers, and only exists/matters in old-devtools '
+					+ 'mode. Both are presence checks, not '
+					+ 'validity checks — a stale old-devtools token still reports '
+					+ 'true here; a real publish/list call will surface staleness '
+					+ 'with a clear error pointing back at reclaim_authenticate.',
 				inputSchema: { type: 'object', properties: {} },
 			},
 			async() => {
 				const persisted = config.read()?.mode
+				const oldIdentity = config.read()?.old_devtools
 				return {
 					mode: current,
 					source: oldModeSource(persisted),
 					persistedMode: persisted ?? null,
 					configPath: defaultConfigPath(),
+					builderAuthenticated: hasValidBuilderSession(config),
+					oldDevtoolsAuthenticated: !!oldIdentity,
+					oldDevtoolsIdentityKind: oldIdentity?.kind ?? null,
 				}
 			},
 		),

package/src/old/client.ts

@@ -47,6 +47,15 @@ export interface RegisterProviderBody {
 	 *  controller's destructure + its `providerConfig` write, both of which
 	 *  include it alongside `pageTitle`/`userAgent`. */
 	stepsToFollow?: string
+	/** Interception mechanism (`NONE` = standard replay flow, the default;
+	 *  `HAWKEYE`/`MSWJS`/`XHOOK` = JS-context interception; `CDP` = browser-
+	 *  level). Column default is `HAWKEYE` when omitted entirely — unlike
+	 *  `stepsToFollow` etc. above, whether the register endpoint actually
+	 *  PERSISTS this field is UNVERIFIED (no source access to confirm); sent
+	 *  here on the chance it does, but the publish tool always follows up
+	 *  with a config (add-version) call regardless, which is confirmed to
+	 *  persist it. */
+	injectionType?: 'NONE' | 'MSWJS' | 'XHOOK' | 'CDP' | 'HAWKEYE'
 }
 
 export interface UpdateProviderConfigBody {
@@ -353,11 +362,31 @@ export class ReclaimOldClient {
 	}
 
 	#asBoom(res: Response, json: unknown): Boom {
-		const message =
+		const rawMessage =
 			(json && typeof json === 'object' &&
 				typeof (json as { message?: unknown }).message === 'string'
 				? (json as { message: string }).message
 				: undefined) || res.statusText || 'Old devtools request failed'
+		// An identity ALREADY SET (as opposed to `#requireIdentity`'s "never
+		// authenticated" case, which never reaches the backend) plus either a
+		// 401/403 OR a message that itself names token verification means the
+		// backend rejected a token we had — i.e. it's stale/invalid, not merely
+		// absent. The message check matters because this backend does NOT
+		// reliably use 401/403 for it — confirmed live: an actually-expired
+		// Firebase token surfaced as "Error while verifying token" with a
+		// status this narrow check (401/403-only) missed entirely, silently
+		// skipping the enrichment. The backend's own message gives no hint of
+		// the fix, and nothing else distinguishes this from Builder auth, so
+		// append repo-side guidance rather than replacing the raw detail.
+		const staleAuth = !!this.#identity && (
+			res.status === 401 || res.status === 403 ||
+			/verify.{0,20}token|token.{0,20}verif/i.test(rawMessage)
+		)
+		const message = staleAuth
+			? `${rawMessage} — your old-devtools login looks stale or invalid `
+				+ '(this is separate from Builder auth). Re-run reclaim_authenticate '
+				+ 'to refresh it, then retry.'
+			: rawMessage
 		// Shape `data` like a ProblemDetails so remapErrorAsResponse can render
 		// `${message}: ${data.detail}` and expose the raw body as structured.
 		return new Boom(message, {