@reclaimprotocol/agent 0.1.0-dev.1

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

@@ -0,0 +1,111 @@
+import { randomUUID } from 'node:crypto'
+import { draftProvider } from '../../../provider/draft.ts'
+import { OPRF_MAX_BYTES } from '../../../provider/matcher.ts'
+import type { OprfMode } from '../../../provider/schema.ts'
+import { defineTool, type RegisteredTool } from '../../server.ts'
+import type { CaptureStore } from './capture.ts'
+
+export interface SecretStore {
+	put: (values: Record<string, string>) => string
+	resolve: (ref: string) => Record<string, string> | undefined
+	clear: () => void
+}
+
+export function makeSecretStore(): SecretStore {
+	const map = new Map<string, Record<string, string>>()
+	return {
+		put: (values) => {
+			const id = `sref_${randomUUID()}`
+			map.set(id, values)
+			return id
+		},
+		resolve: (ref) => map.get(ref),
+		clear: () => map.clear(),
+	}
+}
+
+export function proposeTool(
+	captures: CaptureStore,
+	secrets: SecretStore,
+): RegisteredTool {
+	return defineTool<{
+		captureId: string
+		requestId: string
+		target: string
+		name: string
+		hash?: OprfMode
+	}>(
+		{
+			name: 'propose_provider',
+			description:
+				'Draft a Reclaim provider JSON from a captured request + ' +
+				'a target value. ' +
+				'Secret header values are stored server-side and replaced with an ' +
+				'opaque secretParamsRef ' +
+				'in the response — raw secret values never appear in tool output. ' +
+				"`hash` is opt-in: when set, the captured value is OPRF'd so " +
+				'the attestor never sees ' +
+				'cleartext. Skill should ask the dev first. `oprf-raw` ' +
+				'is the only variant that runs ' +
+				'without external deps; `oprf` needs gnark (Linux/macOS), ' +
+				'`oprf-mpc` needs a TEE attestor.',
+			inputSchema: {
+				type: 'object',
+				properties: {
+					captureId: { type: 'string' },
+					requestId: { type: 'string' },
+					target: { type: 'string' },
+					name: { type: 'string' },
+					hash: { type: 'string', enum: ['oprf-raw', 'oprf', 'oprf-mpc'] },
+				},
+				required: ['captureId', 'requestId', 'target', 'name'],
+			},
+		},
+		async({ captureId, requestId, target, name, hash }) => {
+			if(hash !== undefined && target.length > OPRF_MAX_BYTES) {
+				throw new Error(
+					`OPRF caps hashed values at ${OPRF_MAX_BYTES} bytes; ` +
+					`got ${target.length}-byte target ` +
+					`"${target}". Try a tighter target ` +
+					'(e.g. just the relevant substring) or call ' +
+						'propose_provider without `hash`.',
+				)
+			}
+
+			const session = captures.sessions.get(captureId)
+			if(!session) {
+				throw new Error(`no capture ${captureId}`)
+			}
+
+			const r = session.requests.get(requestId)
+			if(!r) {
+				throw new Error(`no request ${requestId}`)
+			}
+
+			const body = session.bodies.get(requestId)
+			if(!body.available) {
+				throw new Error(`request body unavailable: ${body.reason}`)
+			}
+
+			const reqWithBody = { ...r, responseBody: body.body }
+			const { provider, secretRefs } = draftProvider(
+				reqWithBody,
+				target,
+				name,
+				hash,
+			)
+
+			// Stash real secret values for later replay/proof.
+			const realSecrets: Record<string, string> = {}
+			for(const ref of secretRefs) {
+				const real = r.requestHeaders[ref.name]
+				if(real !== undefined) {
+					realSecrets[ref.name] = real
+				}
+			}
+
+			const secretParamsRef = secrets.put(realSecrets)
+			return { provider, secretRefs, secretParamsRef }
+		},
+	)
+}

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

@@ -0,0 +1,155 @@
+import type { ReclaimClient } from '@reclaimprotocol/client'
+import type { ReclaimProvider } from '../../../provider/schema.ts'
+import {
+	nextVersion,
+	providerToCreateVersionRequest,
+} from '../../../provider/to-version.ts'
+import { defineTool, type RegisteredTool } from '../../server.ts'
+
+export function createVersionFromCaptureTool(
+	client: ReclaimClient,
+): RegisteredTool {
+	return defineTool<{
+		providerId: string
+		provider: ReclaimProvider
+		initialUrl: string
+		notes?: string
+		version?: { major: number, minor: number, patch: number }
+	}>(
+		{
+			name: 'create_provider_version_from_capture',
+			description:
+				'Persist a drafted ReclaimProvider as a verification version. ' +
+				'Call this after run_proof succeeds, passing the `provider` object ' +
+				'from propose_provider VERBATIM. This tool builds the full version ' +
+				'body (the requests[] array, webSettings, etc.) for you — do NOT ' +
+				'hand-construct that shape or call create_provider_version directly. ' +
+				'Omit `version` to have the tool auto-select the next available ' +
+				'version (it lists existing versions and bumps past the highest). ' +
+				'For PRIVATE verifications the version goes live immediately; ' +
+				'for PUBLIC ones call submit_provider_version_for_review afterwards.',
+			inputSchema: {
+				type: 'object',
+				properties: {
+					providerId: {
+						type: 'string',
+						description: 'UUID of the verification to publish the version on.',
+					},
+					provider: {
+						type: 'object',
+						description:
+							'The `provider` object from propose_provider, passed ' +
+							'through verbatim — the tool builds the version body ' +
+							'(the requests[] array etc.) for you.',
+						properties: {
+							name: { type: 'string', description: 'Verification name.' },
+							url: {
+								type: 'string',
+								description:
+									'Exact API URL the attestor replays, with {{param}} ' +
+									'placeholders for any templated values.',
+							},
+							method: {
+								type: 'string',
+								enum: ['GET', 'POST', 'PUT', 'PATCH'],
+							},
+							headers: {
+								type: 'object',
+								description:
+									'Request headers from the capture. Secret headers are ' +
+									'stripped before persistence; the client re-supplies them ' +
+									'at runtime.',
+							},
+							body: {
+								type: 'string',
+								description: 'Request body template, if any.',
+							},
+							responseMatches: {
+								type: 'array',
+								description:
+									'What the attestor checks on the revealed response slice.',
+								items: {
+									type: 'object',
+									properties: {
+										type: { type: 'string', enum: ['regex', 'contains'] },
+										value: { type: 'string' },
+									},
+									required: ['type', 'value'],
+								},
+							},
+							responseRedactions: {
+								type: 'array',
+								description:
+									'Which portions of the response the prover reveals ' +
+									'(xPath / jsonPath / regex; hash to OPRF the value). ' +
+									'Paired with responseMatches by index — the tool folds ' +
+									'each one into the matching entry\'s `extract` in the ' +
+									'persisted version, so keep them aligned 1-to-1.',
+								items: {
+									type: 'object',
+									properties: {
+										xPath: { type: 'string' },
+										jsonPath: { type: 'string' },
+										regex: { type: 'string' },
+										hash: {
+											type: 'string',
+											enum: ['oprf', 'oprf-mpc', 'oprf-raw'],
+										},
+									},
+								},
+							},
+							paramValues: {
+								type: 'object',
+								description:
+									'Real values for the {{param}} placeholders, ' +
+									'e.g. { "username": "Syed" }.',
+							},
+						},
+						required: ['name', 'url', 'method', 'responseMatches'],
+					},
+					initialUrl: {
+						type: 'string',
+						description:
+							'The website URL the user landed on to trigger the request ' +
+							'(e.g. https://github.com/Syed). The URL the verification ' +
+							'flow opens for end-users — NOT the API URL inside the provider.',
+					},
+					notes: {
+						type: 'string',
+						description:
+							'Short change note (e.g. "Initial draft from browser capture").',
+					},
+					version: {
+						type: 'object',
+						description:
+							'Semver to publish as. Omit to auto-pick the next ' +
+							'version above the highest existing one.',
+						properties: {
+							major: { type: 'number', minimum: 0 },
+							minor: { type: 'number', minimum: 0 },
+							patch: { type: 'number', minimum: 0 },
+						},
+						required: ['major', 'minor', 'patch'],
+					},
+				},
+				required: ['providerId', 'provider', 'initialUrl'],
+			},
+		},
+		async(args) => {
+			// Auto-pick the next version if not explicit
+			const ver = args.version ?? (await nextVersion(client, args.providerId))
+
+			const body = providerToCreateVersionRequest(
+				args.provider,
+				args.initialUrl,
+				args.notes,
+				ver,
+			)
+			const result = (await client.call('CreateProviderVersion', {
+				params: { providerId: args.providerId },
+				body,
+			}))
+			return result.data
+		},
+	)
+}

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

@@ -0,0 +1,58 @@
+import { replayProvider } from '../../../proof/replay.ts'
+import type { ReclaimProvider } from '../../../provider/schema.ts'
+import { defineTool, type RegisteredTool } from '../../server.ts'
+import type { SecretStore } from './propose.ts'
+
+export function replayTool(secrets: SecretStore): RegisteredTool {
+	return defineTool<{ provider: unknown, secretParamsRef?: string }>(
+		{
+			name: 'replay_request',
+			description:
+				'Replay a drafted provider against the live endpoint ' +
+				'using Node fetch (no attestor). ' +
+				'Pre-flight gate before run_proof — ' +
+				'diagnoses CSRF / token-rotation / matcher-too-tight ' +
+				'issues with richer hints than the attestor would produce.',
+			inputSchema: {
+				type: 'object',
+				properties: {
+					// `type: 'object'` is required so MCP clients (the LLM)
+					// serialize the value as an object, not a JSON-stringified
+					// string. `properties: {}` is required so zod-from-json-schema
+					// compiles to a passthrough instead of strict-strip — leaving
+					// it off makes the server receive `{}`.
+					provider: { type: 'object', properties: {} },
+					secretParamsRef: { type: 'string' },
+				},
+				required: ['provider'],
+			},
+		},
+		async({ provider, secretParamsRef }) => {
+			let resolved: Record<string, string> = {}
+			if(secretParamsRef !== undefined) {
+				const r = secrets.resolve(secretParamsRef)
+				if(!r) {
+					throw new Error(
+						`unknown secretParamsRef "${secretParamsRef}" — ` +
+						'the MCP server has restarted or reset_session was called. ' +
+						'Re-run propose_provider to mint a fresh ref.',
+					)
+				}
+
+				resolved = r
+			}
+
+			const result = await replayProvider(provider as ReclaimProvider, resolved)
+			const out: Record<string, unknown> = {
+				status: result.status,
+				matchesOriginal: result.matchesOriginal,
+				bodySnippet: result.body.slice(0, 256),
+			}
+			if(result.hints !== undefined) {
+				out.hints = result.hints
+			}
+
+			return out
+		},
+	)
+}

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

@@ -0,0 +1,46 @@
+import type { ConfigStore } from '../../../config/store.ts'
+import { defineTool, type RegisteredTool } from '../../server.ts'
+import type { AttachState } from './attach.ts'
+import type { CaptureStore } from './capture.ts'
+
+export function sessionTools(
+	attachRef: { current?: AttachState, config: ConfigStore },
+	captures: CaptureStore,
+	secrets: { clear: () => void },
+): RegisteredTool[] {
+	return [
+		defineTool<Record<string, never>>(
+			{
+				name: 'get_session',
+				description:
+					'Return current attach state, active captures, and persisted config.',
+				inputSchema: { type: 'object', properties: {} },
+			},
+			async() => ({
+				config: attachRef.config.read()?.browser_agent,
+				attached: Boolean(attachRef.current),
+				port: attachRef.current?.port,
+				captures: [...captures.sessions.keys()],
+				activeTab: captures.activeTab,
+			}),
+		),
+		defineTool<Record<string, never>>(
+			{
+				name: 'reset_session',
+				description:
+					'Stop all captures, drop in-memory secrets, and clear capture state.',
+				inputSchema: { type: 'object', properties: {} },
+			},
+			async() => {
+				for(const s of captures.sessions.values()) {
+					await s.stop().catch(() => {})
+				}
+
+				captures.sessions.clear()
+				delete captures.activeTab
+				secrets.clear()
+				return { reset: true }
+			},
+		),
+	]
+}

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

@@ -0,0 +1,135 @@
+import type { ReclaimClient } from '@reclaimprotocol/client'
+import type {
+	CredentialAttachSession as Session
+} from '../../../types/openapi.ts'
+import { defineTool, type RegisteredTool } from '../../server.ts'
+import { writeSession } from './session-cache.ts'
+
+export function authenticateTool(client: ReclaimClient): RegisteredTool {
+	return defineTool<{
+		code?: string
+	}>(
+		{
+			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' +
+				'To then link a credential to an org (needed only to use it ' +
+				'for verification in production), use the token with the ' +
+				'generated tools: `list_orgs` → `link_credential` with the ' +
+				"credential's `address` and the target `orgId`.",
+			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.`,
+			}
+		},
+	)
+}
+
+async function checkSession(
+	client: ReclaimClient,
+	code: string,
+): Promise<unknown> {
+	let session: Session
+	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.',
+			}
+		}
+
+		throw new Error(`Failed to check session: ${(err as Error).message}`)
+	}
+
+	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.',
+			}
+		}
+
+		return {
+			status: 'LINKED_NO_TOKEN',
+			hint:
+				'Session confirmed but no token issued. ' +
+				'Restart the backend (npm run dev) and try again.',
+		}
+	}
+
+	if(session.status === 'EXPIRED') {
+		return {
+			status: 'EXPIRED',
+			hint:
+				'Session expired (15-min window passed). ' +
+				'Call authenticate without a code to start a new session.',
+		}
+	}
+
+	// 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.',
+	}
+}

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

@@ -0,0 +1,37 @@
+import type { ReclaimClient } from '@reclaimprotocol/client'
+import type { RegisteredTool } from '../../server.ts'
+import { authenticateTool } from './authenticate.ts'
+import { importTool } from './import.ts'
+import { issueTool } from './issue.ts'
+import { listCachedTool } from './list-cached.ts'
+import { resolveOwnerKeyTool } from './resolve-owner-key.ts'
+import { statusTool } from './status.ts'
+
+/**
+ * Local-only credential tools — no backend client needed. These manage app
+ * key-pairs entirely on disk / in the env (mint, import, list, resolve which
+ * key to sign proofs with), so they are useful in BOTH builder and
+ * OLD-devtools mode.
+ */
+export function buildLocalCredentialTools(): RegisteredTool[] {
+	return [
+		listCachedTool(),
+		resolveOwnerKeyTool(),
+		issueTool(),
+		importTool(),
+	]
+}
+
+/**
+ * Full builder-mode credential set: the local tools plus the two that talk to
+ * the builder backend (`reclaim_authenticate` device-code flow,
+ * `reclaim_status`). Old mode does NOT use these — it has its own
+ * authenticate and no credential-status analog.
+ */
+export function buildCredentialTools(client: ReclaimClient): RegisteredTool[] {
+	return [
+		authenticateTool(client),
+		statusTool(client),
+		...buildLocalCredentialTools(),
+	]
+}