@reclaimprotocol/agent 0.1.0-dev.1

package/src/mcp/tools/credentials/status.ts

@@ -0,0 +1,82 @@
+import {
+	deriveFromPrivateKey,
+	type ReclaimClient,
+} from '@reclaimprotocol/client'
+import assert from 'node:assert'
+import { findProjectRoot } from '../../../paths.ts'
+import { defineTool, type RegisteredTool } from '../../server.ts'
+import { suggestCredentialForDir } from './cache.ts'
+
+export function statusTool(client: ReclaimClient): RegisteredTool {
+	return defineTool<{ address?: string }>(
+		{
+			name: 'reclaim_status',
+			description:
+				'Report the live mode (SANDBOX | PRODUCTION | REVOKED) ' +
+				'of a Reclaim app credential. Pass `address` — or omit it ' +
+				'to derive the address from RECLAIM_PRIVATE_KEY, falling ' +
+				'back to the best cached credential for this directory. ' +
+				'Useful to confirm a credential is linked to an org ' +
+				'with billing before running a production flow.',
+			inputSchema: {
+				type: 'object',
+				properties: {
+					address: {
+						type: 'string',
+						pattern: '^0x[0-9a-fA-F]{40}$',
+						description:
+							'Lowercase ETH address. Defaults to the address ' +
+							'derived from RECLAIM_PRIVATE_KEY, then the cached ' +
+							'credential suggested for the current directory.',
+					},
+				},
+			},
+		},
+		async(args) => {
+			let address = args.address?.toLowerCase()
+			if(!address && process.env.RECLAIM_PRIVATE_KEY) {
+				address = deriveFromPrivateKey(process.env.RECLAIM_PRIVATE_KEY).address
+			}
+
+			if(!address) {
+				address = suggestCredentialForDir(findProjectRoot(process.cwd()))
+					?.credential.address
+			}
+
+			assert(
+				address,
+				new Error(
+					'No address given, RECLAIM_PRIVATE_KEY is not set, and the ' +
+						'cache is empty. Run issue_credentials or import_credentials ' +
+						'first.',
+				)
+			)
+
+			const credResult = await client
+				.call('GetCredentialByAddress', { params: { address } })
+			const cred = credResult.data
+
+			// A registered credential always carries an `id`; its absence means
+			// the server had no row for this address — a local-only credential.
+			const localOnly = !cred.id
+
+			return {
+				address: cred.address,
+				mode: cred.mode,
+				orgId: cred.orgId,
+				label: cred.label,
+				revokedAt: cred.revokedAt,
+				lastUsedAt: cred.lastUsedAt,
+				...(localOnly ? {
+					note:
+						'Local-only credential — not registered with the server. '
+						+ 'It operates in SANDBOX, which is all you need to publish '
+						+ 'a verification (only an auth token is required — no '
+						+ 'credential link). Linking it to an org with billing (via '
+						+ 'link_credential) is only needed for the upcoming feature '
+						+ 'that runs verifications for your own app’s users.',
+				} : {}),
+			}
+		},
+	)
+}

package/src/mcp-bin.ts

@@ -0,0 +1,7 @@
+import { startMcpServer } from './mcp/start.ts'
+import { LOGGER } from './logger.ts'
+
+startMcpServer().catch((err) => {
+	LOGGER.error({ err }, 'mcp server failed')
+	process.exitCode = 1
+})

package/src/old/client.ts

@@ -0,0 +1,236 @@
+import { Boom } from '@hapi/boom'
+import { NAME, VERSION } from '../pkg.ts'
+
+/** Default origin of the OLD devtools backend. The client appends the
+ *  `/api` route prefix itself, so this is the bare origin. Override with
+ *  `RECLAIM_OLD_API_URL`. */
+export const DEFAULT_OLD_API_URL = 'https://devapi.reclaimprotocol.org'
+
+/**
+ * Externally-supplied caller identity. We do NOT mint these — the dev
+ * provides one:
+ *   - `bearer`: a Firebase ID token from the devtools dashboard. Attached
+ *     as `Authorization: Bearer …`; `POST /api/users/login` provisions the
+ *     user row on first use.
+ *   - `eth`: an `eth:<lowercase-address>` uid for an already-provisioned
+ *     eth user. Attached as the `x-eth-uid` header (no signature — the
+ *     backend trusts the header for a uid that already exists).
+ */
+export type OldIdentity =
+	| { kind: 'bearer', token: string }
+	| { kind: 'eth', uid: string }
+
+export interface RegisterProviderBody {
+	name: string
+	description?: string
+	loginUrl: string
+	geoLocation?: string
+	providerType?: 'PRIVATE' | 'PUBLIC'
+	requestData: unknown[]
+}
+
+export interface UpdateProviderConfigBody {
+	providerConfig: Record<string, unknown>
+	version: string
+	versionInfo: string
+}
+
+export interface MyProvidersQuery {
+	pageKey?: number
+	pageSize?: number
+	searchQuery?: string
+}
+
+interface RequestOpts {
+	query?: Record<string, string | number | undefined>
+	body?: unknown
+	/** Attach the caller identity header. Throws if no identity is set. */
+	auth?: boolean
+}
+
+/**
+ * Minimal REST client for the OLD devtools Express backend (base `/api`).
+ * Deliberately NOT a clone of `@reclaimprotocol/client`'s operationId
+ * machinery — the old backend has no OpenAPI spec, so this exposes a few
+ * hand-written typed methods for exactly the flows old mode needs:
+ * authenticate, publish (register / update version), and list-own.
+ *
+ * Errors are thrown as `@hapi/boom` so `remapErrorAsResponse` renders them
+ * identically to builder-mode `ProblemError`s.
+ */
+export class ReclaimOldClient {
+	readonly baseUrl: string
+	#identity?: OldIdentity
+	#fetch: typeof fetch
+
+	constructor(opts: {
+		baseUrl?: string
+		identity?: OldIdentity
+		fetch?: typeof fetch
+	} = {}) {
+		this.baseUrl = (opts.baseUrl || DEFAULT_OLD_API_URL).replace(/\/+$/, '')
+		this.#identity = opts.identity
+		this.#fetch = opts.fetch ?? fetch
+	}
+
+	setIdentity(identity: OldIdentity | undefined) {
+		this.#identity = identity
+	}
+
+	getIdentity(): OldIdentity | undefined {
+		return this.#identity
+	}
+
+	/** Validate + provision a bearer identity. The backend creates the user
+	 *  row on first login, which is what makes later authed calls work. */
+	loginWithToken(): Promise<unknown> {
+		return this.#request('POST', '/users/login', { auth: true })
+	}
+
+	registerProvider(body: RegisterProviderBody): Promise<unknown> {
+		return this.#request('POST', '/providers/register', { body, auth: true })
+	}
+
+	updateProviderConfig(
+		providerId: string,
+		body: UpdateProviderConfigBody,
+	): Promise<unknown> {
+		return this.#request(
+			'POST',
+			`/providers/${encodeURIComponent(providerId)}/config`,
+			{ body, auth: true },
+		)
+	}
+
+	listVersions(providerId: string): Promise<unknown> {
+		return this.#request(
+			'GET',
+			`/providers/${encodeURIComponent(providerId)}/versions`,
+			{ auth: true },
+		)
+	}
+
+	getMyProviders(query: MyProvidersQuery = {}): Promise<unknown> {
+		// Every one of these query params is REQUIRED by the backend
+		// validator (missing/invalid → 400), so default them all here.
+		return this.#request('GET', '/providers/user/paginated', {
+			auth: true,
+			query: {
+				pageKey: query.pageKey ?? 0,
+				pageSize: query.pageSize ?? 20,
+				searchQuery: query.searchQuery ?? '',
+				sortByCreatedLatest: 'true',
+				providerType: 'ALL',
+				providerStatus: 'ALL',
+				providerVisibility: 'ALL',
+			},
+		})
+	}
+
+	async #request(
+		method: string,
+		path: string,
+		opts: RequestOpts = {},
+	): Promise<unknown> {
+		let url = `${this.baseUrl}/api${path}`
+		if(opts.query) {
+			const search = new URLSearchParams()
+			for(const [k, v] of Object.entries(opts.query)) {
+				if(v === undefined) {
+					continue
+				}
+
+				search.append(k, String(v))
+			}
+
+			const qs = search.toString()
+			if(qs) {
+				url += `?${qs}`
+			}
+		}
+
+		const headers: Record<string, string> = {
+			Accept: 'application/json',
+			'User-Agent': `${NAME}/${VERSION}`,
+		}
+		if(opts.auth) {
+			headers[this.#authHeaderName()] = this.#authHeaderValue()
+		}
+
+		const init: RequestInit = { method, headers }
+		if(method !== 'GET' && method !== 'HEAD') {
+			init.body = JSON.stringify(opts.body ?? {})
+			headers['Content-Type'] = 'application/json'
+		}
+
+		const res = await this.#fetch(url, init)
+		const json = await this.#parseBody(res)
+
+		// Old API convention: { message, ...data, isSuccess }. Treat a non-2xx
+		// OR an explicit isSuccess:false as an error so a 200-with-failure
+		// body never slips through as success.
+		const failed =
+			!res.ok ||
+			(json !== undefined &&
+				typeof json === 'object' &&
+				(json as { isSuccess?: unknown }).isSuccess === false)
+		if(failed) {
+			throw this.#asBoom(res, json)
+		}
+
+		return json
+	}
+
+	#authHeaderName(): string {
+		const id = this.#requireIdentity()
+		return id.kind === 'bearer' ? 'Authorization' : 'x-eth-uid'
+	}
+
+	#authHeaderValue(): string {
+		const id = this.#requireIdentity()
+		return id.kind === 'bearer' ? `Bearer ${id.token}` : id.uid
+	}
+
+	#requireIdentity(): OldIdentity {
+		if(!this.#identity) {
+			throw new Boom(
+				'Not authenticated against old devtools. Call reclaim_authenticate ' +
+					'with a dashboard token (or eth uid) first.',
+				{ statusCode: 401, data: { status: 401, detail: 'no identity set' } },
+			)
+		}
+
+		return this.#identity
+	}
+
+	async #parseBody(res: Response): Promise<unknown> {
+		if(res.status === 204 || res.headers.get('content-length') === '0') {
+			return undefined
+		}
+
+		try {
+			return await res.json()
+		} catch{
+			return undefined
+		}
+	}
+
+	#asBoom(res: Response, json: unknown): Boom {
+		const message =
+			(json && typeof json === 'object' &&
+				typeof (json as { message?: unknown }).message === 'string'
+				? (json as { message: string }).message
+				: undefined) || res.statusText || 'Old devtools request failed'
+		// Shape `data` like a ProblemDetails so remapErrorAsResponse can render
+		// `${message}: ${data.detail}` and expose the raw body as structured.
+		return new Boom(message, {
+			statusCode: res.ok ? 502 : res.status,
+			data: {
+				status: res.status,
+				title: message,
+				detail: message,
+				body: json,
+			},
+		})
+	}
+}

package/src/old/flag.ts

@@ -0,0 +1,13 @@
+/**
+ * `USE_OLD_DEVTOOLS` — single source of truth for which backend the MCP
+ * server targets.
+ *
+ * Defaults to OLD devtools (the system still in production) while the new
+ * "builder" backend is under development. Builder mode must be opted into
+ * EXPLICITLY by setting `USE_OLD_DEVTOOLS=false`. Anything else — unset,
+ * empty, `true`, `1`, a typo — keeps old mode on, so a forgotten env var
+ * can never silently route a developer at the half-built builder backend.
+ */
+export function useOldDevtools(): boolean {
+	return (process.env.USE_OLD_DEVTOOLS ?? '').trim().toLowerCase() !== 'false'
+}

package/src/old/identity.ts

@@ -0,0 +1,56 @@
+import { deriveFromPrivateKey } from '@reclaimprotocol/client'
+import { ConfigStore } from '../config/store.ts'
+import type { OldIdentity } from './client.ts'
+
+/** Normalize an eth uid input to `eth:<lowercase-address>`. Accepts a bare
+ *  `0x…` address or an already-prefixed `eth:0x…`. */
+export function toEthUid(addressOrUid: string): OldIdentity {
+	const lower = addressOrUid.trim().toLowerCase()
+	const uid = lower.startsWith('eth:') ? lower : `eth:${lower}`
+	return { kind: 'eth', uid }
+}
+
+/**
+ * Resolve a caller identity from the environment, in priority order:
+ *   1. `RECLAIM_OLD_API_TOKEN` — a dashboard Firebase bearer token.
+ *   2. `RECLAIM_OLD_ETH_UID`   — an `eth:<addr>` (or bare `0x…`) uid.
+ *   3. `RECLAIM_PRIVATE_KEY`   — derive the eth uid from the local app key.
+ * Returns undefined when none is set.
+ */
+export function resolveIdentityFromEnv(): OldIdentity | undefined {
+	const token = process.env.RECLAIM_OLD_API_TOKEN?.trim()
+	if(token) {
+		return { kind: 'bearer', token }
+	}
+
+	const ethUid = process.env.RECLAIM_OLD_ETH_UID?.trim()
+	if(ethUid) {
+		return toEthUid(ethUid)
+	}
+
+	const privateKey = process.env.RECLAIM_PRIVATE_KEY?.trim()
+	if(privateKey) {
+		return toEthUid(deriveFromPrivateKey(privateKey).address)
+	}
+
+	return undefined
+}
+
+/** Read the identity persisted by a prior `reclaim_authenticate` call. */
+export function loadPersistedIdentity(): OldIdentity | undefined {
+	return new ConfigStore().read()?.old_devtools
+}
+
+/** Persist the identity so it survives an MCP-server restart. */
+export function persistIdentity(identity: OldIdentity) {
+	new ConfigStore().write({ old_devtools: identity })
+}
+
+/**
+ * The identity the client should start with: an explicit env var wins
+ * (useful for headless / CI), otherwise fall back to whatever the dev
+ * authenticated with last time.
+ */
+export function resolveInitialIdentity(): OldIdentity | undefined {
+	return resolveIdentityFromEnv() ?? loadPersistedIdentity()
+}

package/src/old/instructions.ts

@@ -0,0 +1,30 @@
+/**
+ * MCP server instructions shown to the LLM when running in OLD-devtools mode
+ * (`USE_OLD_DEVTOOLS` unset or not `false`). Describes the REDUCED tool
+ * surface — there are no org/credential-link/review flows and no generated
+ * API tools here. Must not mention disabled tools.
+ */
+export const OLD_MODE_INSTRUCTIONS =
+	'This server is running against the LEGACY Reclaim devtools backend ' +
+	'(temporary, while the new builder backend is in development), so its ' +
+	'capabilities are intentionally limited.\n\n' +
+	'Provider-authoring flow:\n' +
+	'1. `reclaim_authenticate` — by default opens the dashboard in Chrome, ' +
+	'waits for you to sign in, captures the token automatically, and closes ' +
+	'the tab (or paste a `token` / pass an eth `ethAddress` to skip the ' +
+	'browser). Do this once before publishing or listing.\n' +
+	'2. `attach_chrome` → `start_capture` → drive the page (`navigate`, ' +
+	'`wait_for_page`) → inspect (`list_requests`, `get_request`, ' +
+	'`find_requests_containing`).\n' +
+	'3. `propose_provider` to draft a provider, `replay_request` to ' +
+	'pre-flight, `run_proof` to verify with the attestor. OPRF/`hash` ' +
+	'redactions are optional and supported.\n' +
+	'4. `create_provider_version_from_capture` to publish. With NO ' +
+	'`providerId` it REGISTERS A NEW provider (re-running creates a ' +
+	'duplicate); pass a ' +
+	'`providerId` from `get_me_providers` to add a new version to an existing ' +
+	'provider instead.\n' +
+	'5. `get_me_providers` lists the providers you own (the only ' +
+	'provider-listing tool available in this mode).\n\n' +
+	'Only GET/POST endpoints can be captured into providers here. There is no ' +
+	'organization, credential-linking, or public-review workflow in this mode.'

package/src/old/login-cdp.ts

@@ -0,0 +1,153 @@
+import { connectCdp } from '../cdp/client.ts'
+import {
+	defaultProfileDir,
+	launchChrome,
+	waitForCdpReady,
+} from '../cdp/launcher.ts'
+import { ConfigStore } from '../config/store.ts'
+
+/** The devtools dashboard login page. Override per-call or via
+ *  `RECLAIM_OLD_LOGIN_URL`. */
+export const DEFAULT_LOGIN_URL = 'https://dev.reclaimprotocol.org'
+
+/**
+ * Read the Firebase ID token the dashboard persisted after login.
+ *
+ * The frontend uses `browserLocalPersistence`, which the Firebase JS SDK
+ * implements on `localStorage` under a `firebase:authUser:<apiKey>:[DEFAULT]`
+ * key whose JSON value carries `stsTokenManager.accessToken`. We scan for any
+ * such key (so we never hard-code the project apiKey) and fall back to the
+ * IndexedDB persistence layout (`firebaseLocalStorageDb` /
+ * `firebaseLocalStorage`) in case a build switches persistence. Returns the
+ * token string, or null when the user has not finished logging in yet.
+ *
+ * Evaluated in-page with `awaitPromise` so the async IndexedDB branch resolves.
+ */
+const EXTRACT_TOKEN_JS = `(async () => {
+	try {
+		for (let i = 0; i < localStorage.length; i++) {
+			const k = localStorage.key(i)
+			if (k && k.indexOf('firebase:authUser:') === 0) {
+				const v = JSON.parse(localStorage.getItem(k) || 'null')
+				const t = v && v.stsTokenManager && v.stsTokenManager.accessToken
+				if (t) return t
+			}
+		}
+	} catch (e) {}
+	try {
+		return await new Promise((resolve) => {
+			const req = indexedDB.open('firebaseLocalStorageDb')
+			req.onerror = () => resolve(null)
+			req.onsuccess = () => {
+				try {
+					const db = req.result
+					if (!db.objectStoreNames.contains('firebaseLocalStorage')) {
+						resolve(null); return
+					}
+					const store = db
+						.transaction('firebaseLocalStorage', 'readonly')
+						.objectStore('firebaseLocalStorage')
+					const all = store.getAll()
+					all.onerror = () => resolve(null)
+					all.onsuccess = () => {
+						for (const row of (all.result || [])) {
+							const m = row && row.value && row.value.stsTokenManager
+							if (m && m.accessToken) { resolve(m.accessToken); return }
+						}
+						resolve(null)
+					}
+				} catch (e) { resolve(null) }
+			}
+		})
+	} catch (e) { return null }
+})()`
+
+export interface CdpLoginResult {
+	token: string
+	/** True when we launched (and then closed) a dedicated Chrome just for
+	 *  login; false when we attached to an already-running browser and only
+	 *  closed the tab we opened. */
+	closedBrowser: boolean
+}
+
+/**
+ * Open the dashboard login page in Chrome via CDP, wait for the developer to
+ * finish signing in, read the resulting Firebase ID token from page storage,
+ * then clean up. If we had to launch a dedicated Chrome for this, we close the
+ * whole browser afterwards; if we attached to a Chrome that was already up
+ * (e.g. the capture flow's), we only close the tab we opened so we don't
+ * disrupt it.
+ */
+export async function captureFirebaseTokenViaCdp(opts: {
+	loginUrl?: string
+	timeoutMs?: number
+	pollMs?: number
+}): Promise<CdpLoginResult> {
+	const loginUrl =
+		opts.loginUrl || process.env.RECLAIM_OLD_LOGIN_URL || DEFAULT_LOGIN_URL
+	const timeoutMs = opts.timeoutMs ?? 180_000
+	const pollMs = opts.pollMs ?? 1000
+
+	const cfg = new ConfigStore().read()?.browser_agent
+	const mode = cfg?.attachMode ?? 'dedicated'
+	const port = cfg?.port ?? 9222
+
+	// Ensure something is answering CDP. In dedicated mode we may launch it.
+	let launchedByUs = false
+	try {
+		await waitForCdpReady(port, 500)
+	} catch{
+		if(mode !== 'dedicated') {
+			throw new Error(
+				`attach mode: nothing answering CDP on port ${port}. Launch Chrome ` +
+				`with --remote-debugging-port=${port} AND a non-default ` +
+				'--user-data-dir, or switch to dedicated mode (attach_chrome).',
+			)
+		}
+
+		launchChrome({ port, profileDir: defaultProfileDir() })
+		await waitForCdpReady(port, 10_000)
+		launchedByUs = true
+	}
+
+	const handles = await connectCdp(port)
+	const { Target } = handles.browser
+	const { targetId } = await Target.createTarget({ url: loginUrl })
+
+	try {
+		const session = await handles.attachToTab(targetId)
+		const { Runtime } = session
+		const deadline = Date.now() + timeoutMs
+		while(Date.now() < deadline) {
+			const r = await Runtime.evaluate({
+				expression: EXTRACT_TOKEN_JS,
+				awaitPromise: true,
+				returnByValue: true,
+			})
+			const value = r.result?.value
+			if(typeof value === 'string' && value.length > 0) {
+				return { token: value, closedBrowser: launchedByUs }
+			}
+
+			await new Promise((resolve) => setTimeout(resolve, pollMs))
+		}
+
+		throw new Error(
+			'Timed out waiting for login. Finish signing in at the opened ' +
+			'page, or re-run reclaim_authenticate with a longer timeoutMs.',
+		)
+	} finally {
+		// Best-effort cleanup — never mask the real result/error.
+		try {
+			if(launchedByUs) {
+				await handles.browser.Browser.close()
+			} else {
+				await handles.browser.Target.closeTarget({ targetId })
+			}
+		} catch{
+			// ignore
+		}
+
+		await handles.close().catch(() => {})
+	}
+}