@reclaimprotocol/agent 0.1.15 → 0.1.17

package/src/mcp/remap_errors.ts

@@ -2,34 +2,27 @@ import type { Boom } from '@hapi/boom'
 import { isBoom } from '@hapi/boom'
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js'
 import type { ProblemDetails } from '../index.ts'
+import { errorAsToolText } from '../tools/registry.ts'
 
-// Remap all errors here if we return different response based on error.
-// Doing this so we can reuse tool error handler that returns same response
-// across different tools or error.
-// For every other error, let them get thrown so the main try-catch
-// handles them in tool registration.
+// One error shape for every MCP tool. The text comes from errorAsToolText
+// (shared with the cloud loop); Boom problems also attach structuredContent.
 export const remapErrorAsResponse = (
 	err: unknown,
 ): CallToolResult => {
+	const text = errorAsToolText(err)
+
 	// The client throws a Boom-style ProblemError, so the status lives on
 	// `output.statusCode` / `problem.status`, not `status`.
 	if(!isBoom(err) || !err.output?.statusCode) {
 		return {
 			isError: true as const,
-			content: [{ type: 'text' as const, text: (err as Error).message }],
+			content: [{ type: 'text' as const, text }],
 		}
 	}
 
-	const problemError = err as Boom<ProblemDetails>
-
 	return {
 		isError: true as const,
-		structuredContent: problemError.data,
-		content: [
-			{
-				type: 'text' as const,
-				text: `${problemError.message}: ${problemError.data?.detail}`
-			}
-		],
+		structuredContent: (err as Boom<ProblemDetails>).data,
+		content: [{ type: 'text' as const, text }],
 	}
 }

package/src/mcp/start.ts

@@ -1,14 +1,15 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { ReclaimClient } from '@reclaimprotocol/client'
+import { ConfigStore } from '../config/store.ts'
 import {
 	agentDisabled,
 	apiToken,
 	apiUrl,
 	oldApiUrl,
 	oldLogsUrl,
+	resolveOldMode,
 	sdkApiUrl,
-	useOldDevtools,
 } from '../consts.ts'
 import { ReclaimOldClient } from '../old/client.ts'
 import { resolveInitialIdentity } from '../old/identity.ts'
@@ -21,6 +22,7 @@ import {
 	buildAgentTools,
 	buildCredentialTools,
 	buildLocalCredentialTools,
+	buildModeTools,
 	buildVerificationTools,
 	readSession,
 } from './tools/index.ts'
@@ -28,7 +30,10 @@ import { BUILDER_MODE_INSTRUCTIONS } from './instructions.ts'
 import { registerToolList } from './server.ts'
 
 export async function startMcpServer() {
-	const oldMode = useOldDevtools()
+	// Mode precedence: explicit USE_OLD_DEVTOOLS env → persisted config → old.
+	// The same store instance backs the set_devtools_mode toggle below.
+	const config = new ConfigStore()
+	const oldMode = resolveOldMode(config.read()?.mode)
 
 	const server = new McpServer(
 		{ name: NAME, version: VERSION },
@@ -45,6 +50,10 @@ export async function startMcpServer() {
 	// surface.
 	const agentToolsEnabled = !agentDisabled()
 
+	// Backend-mode toggle — available in both modes and regardless of whether
+	// the agent tools are enabled, so a user can always switch either direction.
+	registerToolList(server, buildModeTools(config, oldMode))
+
 	if(oldMode) {
 		// OLD-devtools mode (the default): the legacy backend is still in
 		// production while builder is built. All auto-generated builder tools

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

@@ -150,11 +150,11 @@ export function shapeRichProofResult(
 
 	// Trim the LLM-visible logs — full stream goes to runLogPath.
 	if(result.attestorLogs !== undefined && result.attestorLogs.length > 0) {
-		out.attestorLogs = result.verified
+		const logs = result.verified
 			? warnsAndErrors(result.attestorLogs)
 			: tailLogs(result.attestorLogs)
-		if((out.attestorLogs as unknown[]).length === 0) {
-			delete out.attestorLogs
+		if(logs.length > 0) {
+			out.attestorLogs = logs
 		}
 	}
 

package/src/mcp/tools/authenticate/authenticate.ts

@@ -1,134 +1,264 @@
 import type { ReclaimClient } from '@reclaimprotocol/client'
-import type { CredentialAttachSession } from '@reclaimprotocol/client/openapi'
+import assert from 'node:assert'
+import { spawn } from 'node:child_process'
+import { createHash, randomBytes } from 'node:crypto'
+import { createServer } from 'node:http'
 import { defineTool, type RegisteredTool } from '../../server.ts'
 import { writeSession } from './session-cache.ts'
 
+const SCOPE = 'openid profile email'
+const CALLBACK_TIMEOUT_MS = 5 * 60 * 1000
+
 export function authenticateTool(client: ReclaimClient): RegisteredTool {
-	return defineTool<{
-		code?: string
-	}>(
+	return defineTool<Record<string, never>>(
 		{
 			name: 'reclaim_authenticate',
 			description:
-				'Authorize the CLI / MCP to make authenticated API calls by having ' +
-				'the user sign in on the dashboard. Two steps:\n\n' +
-				'Step 1 — call with no arguments. Returns a `code` and `attachUrl`. ' +
-				'Tell the user to open the URL, sign in, and authorize.\n\n' +
-				'Step 2 — once the user says they have authorized, call again ' +
-				'with the same `code` from step 1 to check if confirmed. ' +
-				'Returns `LINKED` with a 2-day bearer token when confirmed, ' +
-				'`PENDING` if not yet, or `EXPIRED` if too long has passed.\n\n' +
-				'The token is cached in ~/.reclaim/config.json automatically.\n\n' +
-				'This bearer token authenticates dashboard/org-management calls ' +
-				'(e.g. list_orgs, issuing an org secret). Programmatic verification ' +
-				'calls use a separate org secret (rorg_…, set as RECLAIM_ORG_SECRET).',
-			inputSchema: {
-				type: 'object',
-				properties: {
-					code: {
-						type: 'string',
-						pattern: '^[A-HJ-NP-Z2-9]{5}$',
-						description:
-							'5-character code from a previous step-1 call. ' +
-							'When provided, checks whether the user has ' +
-							'confirmed that session instead of opening a new one.',
-					},
-				},
-			},
-		},
-		async(args) => {
-			// Step 2: check an existing session
-			if(args.code) {
-				return checkSession(client, args.code)
-			}
-
-			// Step 1: open a new auth-only session
-			const sessionResult = (await client.call('CreateAttachSession'))
-			const session = sessionResult.data
-
-			return {
-				status: 'PENDING',
-				code: session.code,
-				attachUrl: session.attachUrl,
-				expiresAt: session.expiresAt,
-				instructions:
-					`Open ${session.attachUrl} in your browser, sign in, and click ` +
-					'"Authorize this device". ' +
-					'Once done, call authenticate again with code: ' +
-					`"${session.code}" to confirm.`,
-			}
+				'Authorize the CLI / MCP to make authenticated API calls. Opens the ' +
+				'browser to the builder sign-in page (standard OAuth 2.0 ' +
+				'authorization-code + PKCE with a localhost redirect) and waits for ' +
+				'the user to sign in and approve. On success the access token is ' +
+				'cached in ~/.reclaim/config.json and activated for this session.\n\n' +
+				'Call with no arguments. This bearer token authenticates ' +
+				'dashboard/org-management calls (e.g. list_orgs, issuing an org ' +
+				'secret). Programmatic verification calls use a separate org secret ' +
+				'(rorg_…, set as RECLAIM_ORG_SECRET).',
+			inputSchema: { type: 'object', properties: {} },
 		},
+		async() => runOAuthLoopback(client),
 	)
 }
 
-async function checkSession(
-	client: ReclaimClient,
-	code: string,
-): Promise<unknown> {
-	let session: CredentialAttachSession
+async function runOAuthLoopback(client: ReclaimClient): 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))
+
+	// 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 }
 	try {
-		const sessionResult = (await client.call('GetAttachSession', {
-			params: { code }
-		}))
-		session = sessionResult.data
-	} catch(err) {
-		const status = (err as { status?: number }).status
-		if(status === 404) {
-			return {
-				status: 'NOT_FOUND',
-				hint:
-					'Session not found — it may have expired (15-min window). ' +
-					'Call authenticate without a code to start a new session.',
-			}
-		}
+		const clientId = await registerClient(authBase, callback.redirectUri)
+		openBrowser(
+			authorizeUrl(authBase, {
+				clientId,
+				redirectUri: callback.redirectUri,
+				challenge,
+				state,
+			}),
+		)
+		const code = await callback.code
+		token = await exchangeCode(authBase, {
+			code,
+			verifier,
+			redirectUri: callback.redirectUri,
+			clientId,
+		})
+	} finally {
+		callback.close()
+	}
 
-		throw new Error(`Failed to check session: ${(err as Error).message}`)
+	const expiresAt = new Date(
+		Date.now() + token.expires_in * 1000,
+	).toISOString()
+	writeSession({ token: token.access_token, expiresAt })
+	client.setToken(token.access_token)
+
+	return {
+		status: 'AUTHENTICATED',
+		note: 'Access token cached in ~/.reclaim/config.json and active now.',
+		expiresAt,
 	}
+}
 
-	if(session.status === 'LINKED') {
-		const token = session.token?.trim()
-		if(token) {
-			writeSession({
-				token,
-				expiresAt: new Date(
-					Date.now() + 2 * 24 * 60 * 60 * 1000
-				).toISOString(),
-			})
-			client.setToken(token)
-			return {
-				status: 'LINKED',
-				token,
-				note: 'Token cached in ~/.reclaim/config.json and active now.',
-			}
+/**
+ * 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
+ * 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.
+ */
+async function listenForCallback(state: string): Promise<{
+	redirectUri: string
+	code: Promise<string>
+	close: () => void
+}> {
+	let resolveCode: (code: string) => void
+	let rejectCode: (err: Error) => void
+	const code = new Promise<string>((resolve, reject) => {
+		resolveCode = resolve
+		rejectCode = 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
 		}
 
-		return {
-			status: 'LINKED_NO_TOKEN',
-			hint:
-				'Session confirmed but no token issued. ' +
-				'Restart the backend (npm run dev) and try again.',
+		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', () => {
+			const addr = server.address()
+			if(!addr || typeof addr === 'string') {
+				reject(new Error('Could not bind a local callback port.'))
+				return
+			}
+
+			resolve(addr.port)
+		})
+	})
+	// Past bind, a socket error fails the pending wait rather than throwing.
+	server.on('error', (err) => rejectCode(err))
+
+	return {
+		redirectUri: `http://127.0.0.1:${port}/callback`,
+		code,
+		close: () => {
+			clearTimeout(timer)
+			server.close()
+		},
 	}
+}
 
-	if(session.status === 'EXPIRED') {
-		return {
-			status: 'EXPIRED',
-			hint:
-				'Session expired (15-min window passed). ' +
-				'Call authenticate without a code to start a new session.',
-		}
+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(),
+	})
+	assert(
+		res.ok,
+		new Error(`Token exchange failed (${res.status}): ${await res.text()}`),
+	)
+
+	const json = (await res.json()) as {
+		access_token?: string
+		expires_in?: number
 	}
+	assert(
+		json.access_token,
+		new Error('Token exchange returned no access_token.'),
+	)
 
-	// Still PENDING
 	return {
-		status: 'PENDING',
-		code: session.code,
-		attachUrl: session.attachUrl,
-		hint:
-			'Session is still waiting. ' +
-			`Make sure you opened ${session.attachUrl}, ` +
-			'signed in, and clicked "Authorize this device". ' +
-			`Call authenticate again with code: "${session.code}"` +
-			' once you have done so.',
+		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'
+		: process.platform === 'win32'
+			? 'cmd'
+			: 'xdg-open'
+	const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url]
+	try {
+		spawn(cmd, args, { stdio: 'ignore', detached: true }).unref()
+	} catch{
+		// Non-fatal: the URL is still logged for the user to open manually.
 	}
+
+	process.stderr.write(`\nOpen this URL to sign in:\n${url}\n\n`)
 }

package/src/mcp/tools/authenticate/eth-key.ts

@@ -15,6 +15,7 @@
  * (the eth decrypt key).
  */
 import { deriveFromPrivateKey } from '@reclaimprotocol/client'
+import assert from 'node:assert'
 import { existsSync, readFileSync, writeFileSync } from 'node:fs'
 import { isAbsolute, join } from 'node:path'
 import { privateKey, privateKeyFile } from '../../../consts.ts'
@@ -40,11 +41,12 @@ export type ResolvedEthKey = {
 /** Validate + normalize a raw Ethereum private key to lowercase 0x-hex. */
 export function normalizeEthHex(value: string): string {
 	const v = value.trim().replace(/^['"]|['"]$/g, '')
-	if(!/^(0x)?[0-9a-fA-F]{64}$/.test(v)) {
-		throw new Error(
+	assert(
+		/^(0x)?[0-9a-fA-F]{64}$/.test(v),
+		new Error(
 			'not a valid Ethereum private key (expected a 32-byte / 64-hex scalar)',
-		)
-	}
+		),
+	)
 
 	return '0x' + v.replace(/^0x/, '').toLowerCase()
 }
@@ -122,7 +124,7 @@ export function resolveEthKey(
 }
 
 /** Append `entry` to the project `.gitignore` if not already present. */
-function ensureGitignored(projectDir: string, entry: string): void {
+function ensureGitignored(projectDir: string, entry: string) {
 	const path = join(projectDir, '.gitignore')
 	const current = existsSync(path) ? readFileSync(path, 'utf8') : ''
 	if(current.split('\n').some((l) => l.trim() === entry)) {

package/src/mcp/tools/index.ts

@@ -3,4 +3,5 @@
 // individual tool files.
 export * from './agent/index.ts'
 export * from './authenticate/index.ts'
+export * from './mode/index.ts'
 export * from './verification/index.ts'

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

@@ -0,0 +1,3 @@
+// Barrel for the mode tool group (backend mode toggle). Import from here, not
+// the individual files.
+export { buildModeTools } from './mode.ts'

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

@@ -0,0 +1,58 @@
+import type { ConfigStore, DevtoolsMode } from '../../../config/store.ts'
+import { defaultConfigPath } from '../../../config/store.ts'
+import { defineTool, type RegisteredTool } from '../../server.ts'
+
+/**
+ * The `set_devtools_mode` tool: persist which backend the MCP server targets
+ * (legacy `old` devtools vs the new `builder`). The choice is written to
+ * `~/.reclaim/config.json` and applied the NEXT time the server starts —
+ * the registered tool set, server instructions, and backend client are all
+ * fixed at connect time, so the switch requires a restart/reconnect. Follows
+ * the `attach_chrome` persist-through-config pattern.
+ *
+ * Registered in BOTH modes (so the user can switch either direction) and
+ * outside `buildAgentTools` (so it survives `RECLAIM_AGENT_DISABLED=1`). An
+ * explicit `USE_OLD_DEVTOOLS` env var still overrides the persisted value —
+ * see `resolveOldMode` in consts.ts.
+ */
+export function buildModeTools(
+	config: ConfigStore,
+	currentOldMode: boolean,
+): RegisteredTool[] {
+	const current: DevtoolsMode = currentOldMode ? 'old' : 'builder'
+	return [
+		defineTool<{ mode: DevtoolsMode }>(
+			{
+				name: 'set_devtools_mode',
+				description:
+					'Choose which backend the MCP server targets: "old" (legacy '
+					+ 'Reclaim devtools) or "builder" (the new builder backend). '
+					+ 'Persists the choice to ~/.reclaim/config.json; it takes effect '
+					+ 'the next time the MCP server starts, so restart/reconnect after '
+					+ 'switching. An explicit USE_OLD_DEVTOOLS env var overrides this.',
+				inputSchema: {
+					type: 'object',
+					properties: {
+						mode: { type: 'string', enum: ['old', 'builder'] },
+					},
+					required: ['mode'],
+				},
+			},
+			async(parsed) => {
+				config.write({ mode: parsed.mode })
+				const restartRequired = parsed.mode !== current
+				return {
+					saved: true,
+					mode: parsed.mode,
+					effectiveNow: current,
+					restartRequired,
+					configPath: defaultConfigPath(),
+					message: restartRequired
+						? 'Saved. Restart / reconnect the MCP server for '
+							+ `"${parsed.mode}" mode to take effect.`
+						: `Already running in "${parsed.mode}" mode; nothing to restart.`,
+				}
+			},
+		),
+	]
+}

package/src/proof/debug-response-dump.ts

@@ -26,7 +26,7 @@ let installed = false
 /** Wrap attestor-core's http `getResponseRedactions` to dump the response it
  *  runs against. Idempotent; no-op unless RECLAIM_AGENT_DUMP_RESPONSE is
  *  set. */
-export function installResponseDump(): void {
+export function installResponseDump() {
 	if(installed || !process.env['RECLAIM_AGENT_DUMP_RESPONSE']) {
 		return
 	}

package/src/proof/proof-core.ts

@@ -20,7 +20,7 @@ let cryptoInitialized = false
  *  caller; without this the first proof dies inside the TLS client with
  *  `crypto.randomBytes is not a function`. Shared by every attestor caller —
  *  the agent MCP `run_proof` tool and the app's verification runner. */
-export function ensureAttestorCrypto(): void {
+export function ensureAttestorCrypto() {
 	if(cryptoInitialized) {
 		return
 	}

package/src/proof/zk-files.ts

@@ -27,7 +27,7 @@ let inFlight: Promise<void> | undefined
  * All output goes to stderr (fd 2): the MCP server speaks JSON-RPC over stdout,
  * so a stray write to fd 1 mid-session would corrupt the protocol.
  */
-export function ensureZkFiles(): Promise<void> {
+export function ensureZkFiles() {
 	inFlight ??= download().catch((err) => {
 		inFlight = undefined
 		throw err
@@ -35,7 +35,7 @@ export function ensureZkFiles(): Promise<void> {
 	return inFlight
 }
 
-async function download(): Promise<void> {
+async function download() {
 	let mainPath: string
 	try {
 		mainPath = require.resolve('@reclaimprotocol/zk-symmetric-crypto')

package/src/provider/dom-xpath.ts

@@ -190,7 +190,7 @@ function findElement(root: Node, targets: string[]): Element | undefined {
 	const complete: Element[] = []
 	const embedded: Element[] = []
 
-	const walk = (node: Node): void => {
+	const walk = (node: Node) => {
 		if(isTag(node)) {
 			const el = node
 			const texts = el.children.filter(isText).map((c) => c.data)

package/src/provider/draft.ts

@@ -160,7 +160,7 @@ export function assertPortableMatches(
 	matches: ResponseMatch[],
 	redactions: ResponseRedaction[],
 	targets: DraftTarget[],
-): void {
+) {
 	// A baked email LOCAL-PART ("jane.doe@…") pins the provider to one user
 	// even when only the domain is captured as a param — the classic result of
 	// proving an email's domain substring. Reject it regardless of the declared
@@ -172,7 +172,7 @@ export function assertPortableMatches(
 		.replace(/\{\{[^}]*\}\}/g, '')
 		.replace(/\(\?<[^>]*>[^)]*\)/g, '')
 		.replace(/\\(.)/g, '$1')
-	const scanEmail = (text: string, where: string): void => {
+	const scanEmail = (text: string, where: string) => {
 		if(EMAIL_LOCAL_BAKED.test(deregex(text))) {
 			throw new Error(
 				`drafted ${where} bakes a per-user email local-part as a literal — `
@@ -203,7 +203,7 @@ export function assertPortableMatches(
 	}
 
 	const stripParams = (s: string): string => s.replace(/\{\{[^}]*\}\}/g, '')
-	const scan = (text: string, where: string, own: string | null): void => {
+	const scan = (text: string, where: string, own: string | null) => {
 		const bare = stripParams(text)
 		for(const v of guarded) {
 			if(bare.includes(v)) {