@reclaimprotocol/agent 0.1.39 → 0.1.40

package/skill/verification-client-integration.md

@@ -22,26 +22,44 @@ configuration, and callback conventions. Complete the integration in its codebas
 relevant checks. The MCP tools configure Builder resources; your file tools
 edit the app.
 
-If the app depends on `@reclaimprotocol/js-sdk`, ask the developer first:
-keep it (`set_devtools_mode({ mode: "old" })`, then they restart the MCP
-server), or migrate to the session flow below. When migrating, remove
-`@reclaimprotocol/js-sdk` and replace its `ReclaimProofRequest` and
-`verifyProof` calls.
+If `package.json` depends on `@reclaimprotocol/js-sdk`, ask first: "This
+project uses `@reclaimprotocol/js-sdk`. Keep it (I switch this MCP server to
+legacy devtools mode), or migrate to the Builder HTTP API?"
+
+- **Keep:** `set_devtools_mode({ mode: "old" })`, then tell them to restart or
+  reconnect the MCP server. An explicit `USE_OLD_DEVTOOLS` env var overrides
+  it. After the restart, read `get_js_sdk_integration_guide`.
+- **Migrate:** stay in Builder mode, remove `@reclaimprotocol/js-sdk`, and
+  replace its `ReclaimProofRequest` and `verifyProof` calls with the session
+  flow below.
 
 1. `get_devtools_mode` confirms Builder mode. `get_me` or `authenticate` signs
    in the developer. Find the organization with `list_orgs`; call `create_org`
    only when they want a new one.
 2. Receive callbacks. Local development: call
    `proxy_callback_events({ port, path })` to forward the org's events to the
-   app's callback route on localhost; no public URL. Deployed app (required for
-   production): register a
+   app's callback route on localhost; no public URL. The local listener works
+   only while this MCP server runs. It keeps events in order per session and
+   retries a session the app rejects with backoff, so other sessions keep
+   flowing. When its status lists `blocked` sessions, read that session's
+   callback route response and logs, and fix the app. Deployed app (required
+   for production): register a
    public callback URL with `create_org_callback_subscription`, including
    all five session-ending events. If the
    app needs encrypted results or session binding, call `issue_org_keypair`
    (`encryptResults: true` for encrypted results). It writes the private key to
    the backend's env file and registers only the public key. It returns 409
-   when the org already has a different key: ask the developer for that key
-   rather than replacing it.
+   when the org already has a different key. Check `get_org_keypair` first;
+   when the org has a key pair, the app must pass `orgEthPrivateKey` to
+   `results.receive`, with or without encryption: it decrypts results and
+   verifies TEE-bound proofs. Ask the developer to choose: reuse the key (they
+   put its private key in the backend's server env file as
+   `RECLAIM_ORG_ETH_PRIVATE_KEY` themselves, never in chat), rotate it with
+   `issue_org_keypair` and `replace: true` (apps holding the old key stop
+   working with new results; the old key is saved to `<envFile>.backup`, so
+   tell the developer that path), or turn encryption off with
+   `update_org_keypair({ orgId, canEncryptResult: false })`, which keeps the
+   key. Name the exact action when you ask.
 3. Org key: reuse the `RECLAIM_ORG_SECRET` the app already has. Otherwise an
    organization owner calls `issue_org_token`. It writes the key to the
    project's env file (default `.env`, variable `RECLAIM_ORG_SECRET`) and
@@ -254,6 +272,18 @@ Builder snapshots the organization's most recently updated active theme. A
 localized consent block tells supported clients to show consent before the
 first provider. Branding and theme data don't affect proof trust.
 
+## Try a provider without an app
+
+Session creation returns 409 while the org has no callback subscription.
+`read_callback_events` creates the org's pull listener, which satisfies that
+check and holds results for you to read. No tunnel or public URL is needed.
+
+1. Call `read_callback_events`.
+2. `create_verification_session`, then give the developer `verificationUrl`.
+3. Poll `get_verification_session` until it is terminal.
+   `list_verification_events` shows progress.
+4. Call `read_callback_events({ sessionId })` for the verified result.
+
 ## Call the direct Builder API
 
 In `api=2` mode, send the registered client UUID in `x-reclaim-vc-id` on every

package/src/mcp/api/operations.gen.ts

@@ -1,5 +1,5 @@
 // AUTO-GENERATED by packages/app/scripts/mcp-tools-gen.ts
-// from packages/app/openapi.yaml (spec v0.1.0, source sha256:96339e8dff91).
+// from packages/app/openapi.yaml (spec v0.1.0, source sha256:ecdb0ee6d82e).
 // The hash catches drift the version misses (a spec can change without a
 // version bump) — do not remove it as "redundant" with the version.
 // Run `npm run openapi:gen --workspace=packages/app` to regenerate. Do not edit by hand.
@@ -5116,7 +5116,7 @@ export const MCP_TOOLS = {
 		annotations: {"destructiveHint":true,"idempotentHint":true,"openWorldHint":false},
 	},
 	"DeleteOrgKeypair": {
-		description: "Clear the organization's encryption keypair\n\nRemoves the organization's result encryption public key. Results are then delivered unencrypted until you set a new key. Run it only when the developer asks.",
+		description: "Clear the organization's encryption keypair\n\nRemoves the organization's result encryption public key. Results are then delivered unencrypted until you set a new key. Run it only when the developer asks. To rotate the key, use `issue_org_keypair` with `replace: true` instead of deleting first.",
 		inputSchema: toZod({
 			"type": "object",
 			"properties": {
@@ -6700,7 +6700,7 @@ export const MCP_TOOLS = {
 		annotations: {"destructiveHint":true,"idempotentHint":true,"openWorldHint":false},
 	},
 	"SetOrgKeypair": {
-		description: "Set (or rotate) the organization's encryption keypair\n\nRegisters the organization's result encryption public key and turns on encrypted result delivery. Send only the public key; the private key stays with the developer. If the organization already has a different key, the call returns 409 unless you pass replace: true. Pass it only when the developer asked to rotate the key, because results encrypted to the old key can no longer be decrypted. Setting the same key again succeeds.",
+		description: "Set (or rotate) the organization's encryption keypair\n\nRegisters the organization's result encryption public key and turns on encrypted result delivery. Send only the public key; the private key stays with the developer. If the organization already has a different key, the call returns 409 unless you pass replace: true. Pass it only when the developer asked to rotate the key, because results encrypted to the old key can no longer be decrypted. Setting the same key again succeeds. To generate and store the private key in the project, use `issue_org_keypair` instead.",
 		inputSchema: toZod({
 			"type": "object",
 			"properties": {
@@ -6985,6 +6985,54 @@ export const MCP_TOOLS = {
 		}),
 		annotations: {"openWorldHint":false},
 	},
+	"UpdateOrgKeypair": {
+		description: "Turn result encryption on or off\n\nTurns result encryption on or off for the organization's existing key pair without changing the key. Use it when the developer asks to turn encryption on or off. When on, the app's callback needs `orgEthPrivateKey` to decrypt results. Returns 404 when the organization has no key pair; create one with `issue_org_keypair`.",
+		inputSchema: toZod({
+			"type": "object",
+			"properties": {
+				"params": {
+					"type": "object",
+					"properties": {
+						"orgId": {
+							"type": "string",
+							"format": "uuid"
+						}
+					},
+					"required": [
+						"orgId"
+					],
+					"additionalProperties": false
+				},
+				"query": {
+					"type": "object",
+					"properties": {
+
+					}
+				},
+				"body": {
+					"type": "object",
+					"additionalProperties": false,
+					"description": "Body for `PATCH /orgs/{orgId}/keypair`.",
+					"required": [
+						"canEncryptResult"
+					],
+					"properties": {
+						"canEncryptResult": {
+							"type": "boolean",
+							"description": "Set to true to encrypt results to the organization's public key. Set to false to deliver results as plaintext."
+						}
+					}
+				}
+			},
+			"required": [
+				"params",
+				"query",
+				"body"
+			],
+			"additionalProperties": false
+		}),
+		annotations: {"openWorldHint":false},
+	},
 	"UpdateProvider": {
 		description: "Update a provider\n\nUpdates a provider's metadata, such as title, description, or tags. Partial update — pass only the fields to change. Requires active membership. To change the recipe (initialUrl or requests), cut a new version with create_provider_version instead.",
 		inputSchema: toZod({

package/src/mcp/instructions.ts

@@ -59,7 +59,8 @@ const TOPIC_SUMMARIES: Record<string, string> = {
 	'overview': 'Terminology, your stance, and the authoring checklist.',
 	'contributions': 'Contributing a public provider as a volunteer: the '
 		+ 'candidate-and-review workflow and the extra rules it adds.',
-	'auth': 'Signing in to the backend, and which token authorizes what.',
+	'auth': 'Signing in to the backend, which token authorizes what, and '
+		+ 'the backend mode (Builder or legacy devtools).',
 	'devtools-migration': 'Importing a public legacy provider with the same '
 		+ 'UUID.',
 	'browser': 'The default local browser, the opt-in modes (attach, the '
@@ -71,15 +72,16 @@ const TOPIC_SUMMARIES: Record<string, string> = {
 		+ 'drafted shape.',
 	'params': 'Extracted vs consumer-supplied vs secret params, the URL '
 		+ 'character budget, and runtime resolution.',
-	'prove': 'replay_request, the mandatory auth-bound check, run_proof, and '
-		+ 'diagnosing failures.',
+	'prove': 'replay_request, the mandatory auth-bound check, run_proof '
+		+ '(including the egress country), and diagnosing failures.',
 	'publish': 'Creating a provider, provider versions, multi-request '
 		+ 'providers, and going live.',
-	'discover': 'Reusing existing providers: finding, resolving, and '
-		+ 'creating a verification session.',
-	'integration': 'After start_integration: org key, callback (local '
-		+ 'proxy_callback_events or deployed webhook), frontend and backend '
-		+ 'over the HTTP session API; `api=2` and result verification.',
+	'discover': 'Reusing existing providers: finding, resolving, copying one '
+		+ 'that needs changes, and creating a verification session.',
+	'integration': 'After start_integration: org key and keypair, callback '
+		+ '(local proxy_callback_events or deployed webhook), frontend and '
+		+ 'backend over the HTTP session API, js-sdk projects, trying a '
+		+ 'session without an app; `api=2` and result verification.',
 	'user-script': 'The navigation script (jsUserScripts): sign-in redirect, '
 		+ 'multi-page walk, test_user_script with keep.',
 	'interception': 'injectionType / interceptorType, live interception, the '

package/src/mcp/tools/agent/example-app.ts

@@ -10,10 +10,12 @@
 import { badGateway, badRequest, conflict } from '@hapi/boom'
 import assert from 'node:assert'
 import { createHash } from 'node:crypto'
-import { existsSync, lstatSync, readFileSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
 import { mkdir, realpath, rm, writeFile } from 'node:fs/promises'
+import { connect } from 'node:net'
 import { isAbsolute, join, relative, sep } from 'node:path'
 import { defineTool, type RegisteredTool } from '../../server.ts'
+import { assertNoSymlinks, upsertEnvVar } from '../authenticate/eth-key.ts'
 
 const REPO = 'reclaimprotocol/builder-example'
 /** GitHub tree paths are always `/`-separated, on every OS. */
@@ -22,8 +24,20 @@ const CLIENT_PACKAGE = '@reclaimprotocol/client'
 /** The example is ~50 small files; anything far past that isn't it. */
 const MAX_FILES = 500
 const MAX_BYTES = 10_000_000
+const BACKEND_ENV_FILE = 'packages/backend/.env'
+const DEFAULT_BACKEND_PORT = 3000
+/** Ports probed for the backend: 3000, then 3001 through 3020. */
+const BACKEND_PORT_TRIES = 21
+const LOOPBACK_HOSTS = ['127.0.0.1', '::1']
+const PROBE_TIMEOUT_MS = 500
+/** Files a workspace may already have. An existing copy is kept, not a
+ *  conflict. The env-file tools add their own entries to `.gitignore`. */
+const KEEP_EXISTING = new Set(['AGENTS.md', '.gitignore'])
 
-export function exampleAppTool(fetchFn: typeof fetch = fetch): RegisteredTool {
+export function exampleAppTool(
+	fetchFn: typeof fetch = fetch,
+	isPortFree: (port: number) => Promise<boolean> = isLoopbackPortFree,
+): RegisteredTool {
 	return defineTool<{ projectDir: string }>(
 		{
 			name: 'create_example_app',
@@ -32,12 +46,14 @@ export function exampleAppTool(fetchFn: typeof fetch = fetch): RegisteredTool {
 				+ 'a Fastify backend and a Vite frontend that create sessions, '
 				+ 'verify callbacks, and render every verification state) into '
 				+ '`projectDir`, and sets its backend to the latest '
-				+ '`@reclaimprotocol/client`. Use it when the workspace has no app '
+				+ '`@reclaimprotocol/client`. It picks a free backend port (3000, else '
+				+ 'the next free one, written to `packages/backend/.env`). Use it '
+				+ 'when the workspace has no app '
 				+ 'yet, with the workspace root you were started in as '
 				+ '`projectDir`; don\'t clone the repository yourself. Refuses '
 				+ 'when a file it would write already exists with different '
-				+ 'content. Returns the commit, file count, client version, and '
-				+ 'next steps.',
+				+ 'content. Returns the commit, file count, client version, '
+				+ '`backendPort`, and next steps.',
 			inputSchema: {
 				type: 'object',
 				required: ['projectDir'],
@@ -69,11 +85,17 @@ export function exampleAppTool(fetchFn: typeof fetch = fetch): RegisteredTool {
 						: bytes,
 				}
 			}))
-			for(const { path } of staged) {
+			for(const path of [...staged.map((f) => f.path), BACKEND_ENV_FILE]) {
 				assertNoSymlinks(projectDir, path)
 			}
 
-			const conflicts = staged
+			const kept = staged
+				.filter(({ path }) => {
+					return KEEP_EXISTING.has(path) && existsSync(join(projectDir, path))
+				})
+				.map(({ path }) => path)
+			const toWrite = staged.filter(({ path }) => !kept.includes(path))
+			const conflicts = toWrite
 				.filter(({ path, bytes }) => {
 					const dest = join(projectDir, path)
 					return existsSync(dest) && !readFileSync(dest).equals(bytes)
@@ -88,31 +110,72 @@ export function exampleAppTool(fetchFn: typeof fetch = fetch): RegisteredTool {
 				),
 			)
 
-			for(const { path, bytes } of staged) {
+			for(const { path, bytes } of toWrite) {
 				await installFile(projectDir, path, bytes)
 			}
 
+			const backendPort = await findBackendPort()
+			// Always written, so a re-run never leaves a stale port behind.
+			upsertEnvVar(projectDir, BACKEND_ENV_FILE, 'PORT', String(backendPort))
+
+			const dev = backendPort === DEFAULT_BACKEND_PORT
+				? 'npm run dev'
+				: `API_URL=http://localhost:${backendPort} npm run dev`
+
 			return {
 				projectDir,
 				repository: `https://github.com/${REPO}`,
 				commit,
-				files: staged.length,
+				files: toWrite.length,
+				kept,
 				clientVersion,
+				backendPort,
 				next: [
 					'Call issue_org_token with this projectDir and envFile '
 					+ '"packages/backend/.env".',
-					'Run `npm install`, then `npm run dev`, from projectDir. The '
-					+ 'backend listens on port 3000; the app opens at '
-					+ 'http://localhost:5173.',
-					'Call proxy_callback_events({ port: 3000, path: '
+					'Run `npm install` from projectDir, then start the dev '
+					+ `server with \`${dev}\`. The backend listens on port `
+					+ `${backendPort}`
+					+ (backendPort === DEFAULT_BACKEND_PORT
+						? '.'
+						: ` (port ${DEFAULT_BACKEND_PORT} is in use; the frontend `
+						+ 'proxy needs `API_URL`).'),
+					'Run the dev server in the background and send its output to a '
+					+ 'log file in projectDir, for example `npm run dev > '
+					+ 'reclaim-dev.log 2>&1`, so callback errors stay readable even '
+					+ 'when a shell output filter buffers output.',
+					'Give the developer the frontend URL Vite prints in that log. '
+					+ 'Don\'t assume port 5173: Vite moves to the next free port '
+					+ 'when it is taken.',
+					`Call proxy_callback_events({ port: ${backendPort}, path: `
 					+ '"/reclaim/callback" }).',
+					'If get_org_keypair shows `canEncryptResult: true`, the '
+					+ 'callback needs `orgEthPrivateKey`; see the plan.',
 					'Put the provider in packages/backend/config.json and restart '
 					+ 'the backend.',
+					'The backend stores verifications in memory: restarting it '
+					+ 'drops sessions in progress, so start a new verification '
+					+ 'after any restart.',
 				],
 			}
 		},
 	)
 
+	async function findBackendPort() {
+		for(let i = 0; i < BACKEND_PORT_TRIES; i++) {
+			const port = DEFAULT_BACKEND_PORT + i
+			if(await isPortFree(port)) {
+				return port
+			}
+		}
+
+		throw conflict(
+			`No free port from ${DEFAULT_BACKEND_PORT} to `
+			+ `${DEFAULT_BACKEND_PORT + BACKEND_PORT_TRIES - 1}. Ask the developer `
+			+ 'to stop another dev server.',
+		)
+	}
+
 	async function latestCommit() {
 		const res = await fetchFn(
 			`https://api.github.com/repos/${REPO}/commits/main`,
@@ -239,23 +302,6 @@ function isEexist(err: unknown) {
 	return err instanceof Error && 'code' in err && err.code === 'EEXIST'
 }
 
-/** Throws when `path`, or any of its existing parents under `root`, is a
- *  symlink: writing through one would land outside the workspace. */
-function assertNoSymlinks(root: string, path: string) {
-	let current = root
-	for(const part of path.split(/[\\/]/)) {
-		current += sep + part
-		const stat = lstatSync(current, { throwIfNoEntry: false })
-		assert(
-			!stat?.isSymbolicLink(),
-			badRequest(
-				`${current} is a symlink; the example app is only written to `
-				+ 'real directories inside the workspace',
-			),
-		)
-	}
-}
-
 /** The backend's package.json with the client range set to `^version`. */
 function withClientVersion(bytes: Buffer, version: string) {
 	const text = bytes.toString('utf8')
@@ -277,3 +323,24 @@ function gitBlobSha(bytes: Buffer) {
 		.update(bytes)
 		.digest('hex')
 }
+
+/** True when nothing accepts connections on `port` at 127.0.0.1 or ::1.
+ *  Connecting, rather than binding, also catches servers bound to `0.0.0.0`:
+ *  macOS lets a loopback bind succeed alongside them. Exported for tests. */
+export async function isLoopbackPortFree(port: number) {
+	const results = await Promise.all(LOOPBACK_HOSTS.map((host) => {
+		return new Promise<boolean>((resolve) => {
+			const socket = connect({ port, host, timeout: PROBE_TIMEOUT_MS })
+			socket.once('connect', () => {
+				socket.destroy()
+				resolve(false)
+			})
+			socket.once('timeout', () => {
+				socket.destroy()
+				resolve(true)
+			})
+			socket.once('error', () => resolve(true))
+		})
+	}))
+	return results.every(Boolean)
+}

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

@@ -15,12 +15,17 @@
  * signing key only — unrelated to org auth (the org secret) or encryption
  * (the eth decrypt key).
  */
+import { badRequest } from '@hapi/boom'
 import { deriveFromPrivateKey, generateKeypair } from '@reclaimprotocol/client'
 import assert from 'node:assert'
 import {
-	chmodSync,
+	closeSync,
+	constants,
 	existsSync,
+	fchmodSync,
+	lstatSync,
 	mkdirSync,
+	openSync,
 	readFileSync,
 	writeFileSync,
 } from 'node:fs'
@@ -29,7 +34,8 @@ import {
 	isAbsolute,
 	join,
 	relative,
-	resolve
+	resolve,
+	sep
 } from 'node:path'
 import { privateKey, privateKeyFile } from '../../../consts.ts'
 import { findProjectRoot } from '../../../paths.ts'
@@ -178,7 +184,7 @@ export function ensureGitignored(projectDir: string, entry: string) {
 	}
 
 	const prefix = current && !current.endsWith('\n') ? '\n' : ''
-	writeFileSync(path, current + prefix + entry + '\n')
+	writeInside(projectDir, path, current + prefix + entry + '\n')
 }
 
 /**
@@ -205,13 +211,60 @@ export function upsertEnvVar(
 		next = existing + prefix + line + '\n'
 	}
 
-	mkdirSync(dirname(envPath), { recursive: true })
-	writeFileSync(envPath, next, { mode: 0o600 })
-	chmodSync(envPath, 0o600)
+	writeInside(projectDir, envPath, next, { secret: true })
 	ensureGitignored(projectDir, relative(projectDir, envPath))
 	return envPath
 }
 
+/** Remove the `name=` line from a dotenv file, if there is one. */
+export function removeEnvVar(
+	projectDir: string,
+	envFile: string,
+	name: string,
+) {
+	const envPath = resolve(projectDir, envFile)
+	if(!existsSync(envPath)) {
+		return
+	}
+
+	const existing = readFileSync(envPath, 'utf8')
+	const re = new RegExp(`^\\s*${name}\\s*=.*(\\n|$)`, 'm')
+	writeInside(projectDir, envPath, existing.replace(re, ''), { secret: true })
+}
+
+/**
+ * Before `name` is overwritten, append its current value to
+ * `<envFile>.backup` (same directory) as a timestamped comment plus the
+ * `NAME=value` line. Appends, so repeated rotations keep history. Writes with
+ * mode 0600 and adds the backup to `.gitignore`. Returns the backup's absolute
+ * path, or `undefined` when the env file holds no value for `name`. Never
+ * returns or logs the value.
+ */
+export function backupEnvVar(
+	projectDir: string,
+	envFile: string,
+	name: string,
+	reason: string,
+): string | undefined {
+	const envPath = resolve(projectDir, envFile)
+	assertNoSymlinks(projectDir, relative(projectDir, envPath))
+	const value = readDotenvKey(envPath, name)
+	if(!value) {
+		return undefined
+	}
+
+	const backupPath = `${envPath}.backup`
+	const stamp = new Date().toISOString()
+	writeInside(
+		projectDir,
+		backupPath,
+		`# ${stamp} ${reason}\n${name}=${value}\n`,
+		{ secret: true, append: true },
+	)
+	ensureGitignored(projectDir, relative(projectDir, backupPath))
+	return backupPath
+}
+
 /**
  * Persist a raw eth private key to the project `.env` as
  * `RECLAIM_PRIVATE_KEY=0x…` (upsert; mode 0600; `.env` added to `.gitignore`).
@@ -226,3 +279,58 @@ export function writeEthKey(
 	const path = upsertEnvVar(projectDir, ENV_FILE, ENV_VAR, hex)
 	return { path, address: deriveFromPrivateKey(hex).address }
 }
+
+/** Throws when `path` (relative to `root`), or any of its existing parents
+ *  under `root`, is a symlink: writing through one could land outside the
+ *  project. */
+export function assertNoSymlinks(root: string, path: string) {
+	assert(
+		path && !path.startsWith('..') && !isAbsolute(path),
+		badRequest(`${path} is not inside ${root}`),
+	)
+	let current = root
+	for(const part of path.split(/[\\/]/)) {
+		current += sep + part
+		const stat = lstatSync(current, { throwIfNoEntry: false })
+		assert(
+			!stat?.isSymbolicLink(),
+			badRequest(
+				`${current} is a symlink; Reclaim tools only write to real files `
+				+ 'and directories inside the project',
+			),
+		)
+	}
+}
+
+/**
+ * Write `data` to `path` inside `projectDir` without following a symlink: the
+ * file and its parents must be real, and the open uses `O_NOFOLLOW`, so a
+ * symlink that appears after the check still fails. `secret` writes with
+ * mode 0600; `append` adds to the file instead of replacing it.
+ */
+function writeInside(
+	projectDir: string,
+	path: string,
+	data: string,
+	{ secret = false, append = false } = {},
+) {
+	const rel = relative(projectDir, path)
+	assertNoSymlinks(projectDir, rel)
+	mkdirSync(dirname(path), { recursive: true })
+	assertNoSymlinks(projectDir, rel)
+	const fd = openSync(
+		path,
+		constants.O_WRONLY | constants.O_CREAT | constants.O_NOFOLLOW
+			| (append ? constants.O_APPEND : constants.O_TRUNC),
+		secret ? 0o600 : 0o666,
+	)
+	try {
+		if(secret) {
+			fchmodSync(fd, 0o600)
+		}
+
+		writeFileSync(fd, data)
+	} finally {
+		closeSync(fd)
+	}
+}