@reclaimprotocol/agent 0.1.37 → 0.1.38

package/README.md

@@ -134,7 +134,7 @@ The MCP server targets one of two backends. An explicit `USE_OLD_DEVTOOLS` setti
   - `get_me_providers` — list the providers you own (the only provider-listing tool in this mode).
   - `session_analytics_logs` — the milestone events for a verification session, which show how far it got.
   - `session_logs` — the log entries the in-app SDK emitted during that session, each with its event type, log level, and logger name. Filter by event type, level, or substring, page with `limit` and `offset`, or set `saveTo` to write every matching entry to an NDJSON file. The backend searches only the last 3 days unless you pass `startTime` and `endTime`, and it deletes entries after 30 days.
-- **Builder (default).** Registers the auto-generated HTTP-API tools, including `create_org`, `issue_org_token`, and `create_org_callback_subscription`, plus authentication/credential tools, `get_verification_result`, `read_callback_events` (read the org's pull-listener events), `proxy_callback_events` (forward them to a localhost callback route; the pull listener lives only while the MCP server runs), and `check_attestor`. `issue_credentials` creates a local proof-owner key; `issue_org_token` issues the organization's API secret; `issue_org_keypair` creates the organization's key pair for session binding and encrypted results, writing the private key to the app's env file.
+- **Builder (default).** Registers the auto-generated HTTP-API tools, including `create_org`, `issue_org_token`, and `create_org_callback_subscription`, plus authentication/credential tools, `get_verification_result`, `read_callback_events` (read the org's pull-listener events), `proxy_callback_events` (forward them to a localhost callback route; the pull listener lives only while the MCP server runs), and `check_attestor`. `issue_credentials` creates a local proof-owner key; `issue_org_token` issues the organization's API secret; `create_example_app` writes the builder-example app into a workspace that has none; `issue_org_keypair` creates the organization's key pair for session binding and encrypted results, writing the private key to the app's env file.
 
 Relevant env vars: `RECLAIM_OLD_API_URL` (default `https://devapi.reclaimprotocol.org`), `RECLAIM_OLD_API_TOKEN` / `RECLAIM_OLD_ETH_UID` (headless identity), `RECLAIM_OLD_LOGIN_URL` (default `https://dev.reclaimprotocol.org`); builder mode uses `RECLAIM_API_URL` / `RECLAIM_API_TOKEN`.
 

package/lib/mcp/tools/agent/build.js

@@ -17,6 +17,7 @@ import { captureTools, resetCaptures } from "./capture.js";
 import { checkAttestorTool } from "./check-attestor.js";
 import { draftTools } from "./draft-tools.js";
 import { listTabsTool } from "./eval.js";
+import { exampleAppTool } from "./example-app.js";
 import { howItWorksTool } from "./how-it-works.js";
 import { liveViewTools } from "./live-view.js";
 import { podProofTools } from "./pod-proof.js";
@@ -81,6 +82,7 @@ export function buildAgentTools(client, builderClient = client, externalState) {
     }
     if (client) {
         tools.push(startIntegrationTool());
+        tools.push(exampleAppTool());
         tools.push(createVersionFromCaptureTool(client, state.attach, state.captures));
     }
     return tools;

package/lib/mcp/tools/agent/example-app.d.ts

@@ -0,0 +1,2 @@
+import { type RegisteredTool } from '../../server.ts';
+export declare function exampleAppTool(fetchFn?: typeof fetch): RegisteredTool;

package/lib/mcp/tools/agent/example-app.js

@@ -0,0 +1,167 @@
+/**
+ * `create_example_app` — write reclaimprotocol/builder-example into the
+ * developer's workspace, so a project with no app starts from a ready-to-run
+ * backend and frontend instead of agent-written code. The MCP server fetches
+ * the files itself (each checked against its git blob hash) and writes them at
+ * the workspace root: the coding agent's later `npm install` and `npm run dev`
+ * then run in the workspace it started in, not in a clone. The backend's
+ * `@reclaimprotocol/client` is set to the latest published version.
+ */
+import { badGateway, badRequest, conflict } from '@hapi/boom';
+import assert from 'node:assert';
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { mkdir, mkdtemp, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join } from 'node:path';
+import { defineTool } from "../../server.js";
+const REPO = 'reclaimprotocol/builder-example';
+const BACKEND_PACKAGE = join('packages', 'backend', 'package.json');
+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 = 10000000;
+export function exampleAppTool(fetchFn = fetch) {
+    return defineTool({
+        name: 'create_example_app',
+        description: 'Writes the Reclaim example app (reclaimprotocol/builder-example: '
+            + '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 '
+            + '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.',
+        inputSchema: {
+            type: 'object',
+            required: ['projectDir'],
+            properties: {
+                projectDir: {
+                    type: 'string',
+                    description: 'Absolute path of the workspace root you were started in.',
+                },
+            },
+        },
+        annotations: { openWorldHint: true, destructiveHint: false },
+    }, async ({ projectDir }) => {
+        assert(isAbsolute(projectDir), badRequest('`projectDir` must be an absolute path.'));
+        const commit = await latestCommit();
+        const files = await listFiles(commit);
+        const clientVersion = await latestClientVersion();
+        const staged = await Promise.all(files.map(async (file) => {
+            const bytes = await download(commit, file);
+            return {
+                path: file.path,
+                bytes: file.path === BACKEND_PACKAGE
+                    ? withClientVersion(bytes, clientVersion)
+                    : bytes,
+            };
+        }));
+        const conflicts = staged
+            .filter(({ path, bytes }) => {
+            const dest = join(projectDir, path);
+            return existsSync(dest) && !readFileSync(dest).equals(bytes);
+        })
+            .map(({ path }) => path);
+        assert(!conflicts.length, conflict('These files already exist with different content: '
+            + `${conflicts.join(', ')}. Ask the developer whether to use `
+            + 'another directory or move them.'));
+        // Stage inside projectDir, so the moves below stay on one filesystem.
+        const tmp = await mkdtemp(join(projectDir, '.reclaim-example-'));
+        try {
+            for (const { path, bytes } of staged) {
+                await mkdir(dirname(join(tmp, path)), { recursive: true });
+                await writeFile(join(tmp, path), bytes);
+            }
+            for (const { path } of staged) {
+                const dest = join(projectDir, path);
+                await mkdir(dirname(dest), { recursive: true });
+                await rename(join(tmp, path), dest);
+            }
+        }
+        finally {
+            await rm(tmp, { recursive: true, force: true });
+        }
+        return {
+            projectDir,
+            repository: `https://github.com/${REPO}`,
+            commit,
+            files: staged.length,
+            clientVersion,
+            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: '
+                    + '"/reclaim/callback" }).',
+                'Put the provider in packages/backend/config.json and restart '
+                    + 'the backend.',
+            ],
+        };
+    });
+    async function latestCommit() {
+        const res = await fetchFn(`https://api.github.com/repos/${REPO}/commits/main`, { headers: { Accept: 'application/vnd.github.sha' } });
+        assert(res.ok, badGateway(`${REPO} commit lookup: HTTP ${res.status}`));
+        const text = await res.text();
+        const commit = text.trim();
+        assert(/^[0-9a-f]{40}$/.test(commit), badGateway('invalid commit SHA'));
+        return commit;
+    }
+    async function listFiles(commit) {
+        const res = await fetchFn(`https://api.github.com/repos/${REPO}/git/trees/${commit}?recursive=1`, { headers: { Accept: 'application/vnd.github+json' } });
+        assert(res.ok, badGateway(`${REPO} file listing: HTTP ${res.status}`));
+        const tree = await res.json();
+        assert(typeof tree === 'object' && tree !== null && 'tree' in tree
+            && Array.isArray(tree.tree) && !('truncated' in tree && tree.truncated), badGateway(`unexpected ${REPO} file listing`));
+        const files = tree.tree
+            .filter((e) => {
+            return typeof e === 'object' && e !== null && 'type' in e
+                && e.type === 'blob';
+        })
+            .map((entry) => {
+            assert(typeof entry === 'object' && entry !== null
+                && 'path' in entry && typeof entry.path === 'string'
+                && entry.path.split('/').every((s) => /^[\w@.-]+$/.test(s)
+                    && s !== '.' && s !== '..' && s !== '.git')
+                && 'sha' in entry && typeof entry.sha === 'string'
+                && 'size' in entry && typeof entry.size === 'number', badGateway(`unexpected entry in the ${REPO} file listing`));
+            return { path: entry.path, sha: entry.sha, size: entry.size };
+        });
+        assert(files.length > 0 && files.length <= MAX_FILES
+            && files.reduce((n, f) => n + f.size, 0) <= MAX_BYTES, badGateway(`unexpected ${REPO} size`));
+        return files;
+    }
+    async function download(commit, file) {
+        const res = await fetchFn(`https://raw.githubusercontent.com/${REPO}/${commit}/${file.path}`);
+        assert(res.ok, badGateway(`${file.path}: HTTP ${res.status}`));
+        const bytes = Buffer.from(await res.arrayBuffer());
+        assert(gitBlobSha(bytes) === file.sha, badGateway(`${file.path} failed its integrity check`));
+        return bytes;
+    }
+    async function latestClientVersion() {
+        const res = await fetchFn(`https://registry.npmjs.org/${CLIENT_PACKAGE.replace('/', '%2f')}/latest`);
+        assert(res.ok, badGateway(`npm ${CLIENT_PACKAGE}: HTTP ${res.status}`));
+        const body = await res.json();
+        assert(typeof body === 'object' && body !== null && 'version' in body
+            && typeof body.version === 'string'
+            && /^\d+\.\d+\.\d+$/.test(body.version), badGateway(`npm ${CLIENT_PACKAGE}: no version`));
+        return body.version;
+    }
+}
+/** The backend's package.json with the client range set to `^version`. */
+function withClientVersion(bytes, version) {
+    const text = bytes.toString('utf8');
+    const next = text.replace(/("@reclaimprotocol\/client"\s*:\s*")[^"]*(")/, (_, open, close) => `${open}^${version}${close}`);
+    assert(next !== text || text.includes(`"^${version}"`), badGateway(`${BACKEND_PACKAGE} has no ${CLIENT_PACKAGE} dependency`));
+    return Buffer.from(next);
+}
+/** Git's blob object id: sha1 of `blob <size>\0<content>`. */
+function gitBlobSha(bytes) {
+    return createHash('sha1')
+        .update(`blob ${bytes.length}\0`)
+        .update(bytes)
+        .digest('hex');
+}

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@reclaimprotocol/agent",
 	"title": "Reclaim Agent",
-	"version": "0.1.37",
+	"version": "0.1.38",
 	"description": "Reclaim Protocol tools for AI coding agents. Reclaim lets your app verify data points about its users, such as a follower count, an account balance, or an order history. This package is the Reclaim MCP server: it gives your agent the tools to find, build, test, and fix data verification providers by capturing and replaying browser requests, drafting provider recipes, running zkTLS proofs, and publishing provider versions.",
 	"type": "module",
 	"main": "./lib/index.js",
@@ -84,7 +84,7 @@
 		"@noble/hashes": "^2.2.0",
 		"@puppeteer/browsers": "3.2.4",
 		"@reclaimprotocol/attestor-core": "^5.1.6",
-		"@reclaimprotocol/client": "0.1.37",
+		"@reclaimprotocol/client": "0.1.38",
 		"@reclaimprotocol/tls": "^0.1.3",
 		"chrome-remote-interface": "^0.33.0",
 		"domhandler": "^6.0.0",

package/skill/start-integration.md

@@ -46,7 +46,7 @@ Build a new organization-private provider for exactly "{{goal}}". Do not search
 
 Setup does not need the provider. Start it after step 2 has a working proof, or while you wait on the developer during step 2 (for example, while they sign in to the site). Don't let it delay a step that needs the developer.
 
-**Delegation.** If you can run subagents, hand this step to one subagent as soon as you are signed in, and keep working on step 2: step 2 needs the developer at the browser, step 3 does not. Give the subagent a self-contained brief:
+**Delegation.** When the workspace already has an app and you can run subagents, hand this step to one subagent as soon as you are signed in, and keep working on step 2: step 2 needs the developer at the browser, step 3 does not. Give the subagent a self-contained brief:
 
 ```
 Goal: let this app's users prove "{{goal}}" with Reclaim.
@@ -61,10 +61,12 @@ Without subagents, do step 2 first, and fill waits for the developer with this s
 
 **No app yet?** If the workspace has no app to add verification to (it is empty, or has no backend or frontend), don't write one. Bootstrap from [builder-example](https://github.com/reclaimprotocol/builder-example), a ready-to-run Fastify backend and Vite frontend that already create sessions, verify callbacks, poll status, and render every UI state:
 
-- [ ] Clone it: `git clone --depth 1 https://github.com/reclaimprotocol/builder-example <dir>` (use the workspace itself when it is empty), then delete the clone's `.git` directory so the code becomes the developer's own.
-- [ ] Call `issue_org_token` with the clone's absolute path as `projectDir` and `envFile: "packages/backend/.env"`.
+Do this yourself, not in a subagent.
+
+- [ ] Call `create_example_app` with the workspace root you were started in as `projectDir`. It writes the example there and sets its backend to the latest `@reclaimprotocol/client`. Don't clone the repository or create a subdirectory: commands you run inside a clone count as running external code, and permission checks may block them.
+- [ ] Call `issue_org_token` with the same `projectDir` and `envFile: "packages/backend/.env"`.
 - [ ] Only when the developer asks for session binding or encrypted results: call `issue_org_keypair` with the same `projectDir` and `envFile` (add `encryptResults: true` for encrypted results). It writes `RECLAIM_ORG_ETH_PRIVATE_KEY` and registers the public key. Then pass `orgEthPrivateKey: process.env.RECLAIM_ORG_ETH_PRIVATE_KEY` to `reclaim.sessions.create` in `packages/backend/src/routes/verifications.ts` (binding) and to `reclaim.results.receive` in `packages/backend/src/routes/callback.ts` (decryption and TEE proof checks), and add an empty `RECLAIM_ORG_ETH_PRIVATE_KEY=` line to `packages/backend/example.env`.
-- [ ] From the clone's root, run `npm install`, then `npm install @reclaimprotocol/client@latest -w packages/backend` so the backend uses the latest client rather than the version in the example's lockfile. Then run `npm run dev`. The backend listens on port 3000; the app opens at <http://localhost:5173>.
+- [ ] From the workspace root, run `npm install`, then `npm run dev`. The backend listens on port 3000; the app opens at <http://localhost:5173>. If a permission check blocks either command, don't work around it: end your turn, say which command was blocked and that it installs and runs the Reclaim example app, and ask the developer to approve it.
 - [ ] Call `proxy_callback_events({ port: 3000, path: "/reclaim/callback" })`.
 - [ ] Skip the rest of this step. In step 4, the provider goes in `packages/backend/config.json`: replace the example entry with `{ "id": "<provider ID>", "name": "<what it proves>" }`, then restart the backend, because it reads the file at startup.
 

package/skill/verification-client-integration.md

@@ -14,10 +14,10 @@ proof works, or while you wait on the developer. When you need the developer
 to answer or act, end your turn with the question and every link they need;
 don't ask through a background or asynchronous question tool.
 
-When the workspace has no app yet, bootstrap from
-[builder-example](https://github.com/reclaimprotocol/builder-example) as the
-`start_integration` plan describes, instead of writing a new backend and
-frontend. Otherwise, inspect the app's frontend, backend, package manager,
+When the workspace has no app yet, call `create_example_app` to write
+[builder-example](https://github.com/reclaimprotocol/builder-example) into the
+workspace root, as the `start_integration` plan describes, instead of writing a
+new backend and frontend or cloning the repository. Otherwise, inspect the app's frontend, backend, package manager,
 configuration, and callback conventions. Complete the integration in its codebase and run its
 relevant checks. The MCP tools configure Builder resources; your file tools
 edit the app.

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

@@ -20,6 +20,7 @@ import { type CaptureStore, captureTools, resetCaptures } from './capture.ts'
 import { checkAttestorTool } from './check-attestor.ts'
 import { draftTools } from './draft-tools.ts'
 import { listTabsTool } from './eval.ts'
+import { exampleAppTool } from './example-app.ts'
 import { howItWorksTool } from './how-it-works.ts'
 import { liveViewTools } from './live-view.ts'
 import { podProofTools } from './pod-proof.ts'
@@ -101,6 +102,7 @@ export function buildAgentTools(
 
 	if(client) {
 		tools.push(startIntegrationTool())
+		tools.push(exampleAppTool())
 		tools.push(createVersionFromCaptureTool(
 			client, state.attach, state.captures,
 		))

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

@@ -0,0 +1,227 @@
+/**
+ * `create_example_app` — write reclaimprotocol/builder-example into the
+ * developer's workspace, so a project with no app starts from a ready-to-run
+ * backend and frontend instead of agent-written code. The MCP server fetches
+ * the files itself (each checked against its git blob hash) and writes them at
+ * the workspace root: the coding agent's later `npm install` and `npm run dev`
+ * then run in the workspace it started in, not in a clone. The backend's
+ * `@reclaimprotocol/client` is set to the latest published version.
+ */
+import { badGateway, badRequest, conflict } from '@hapi/boom'
+import assert from 'node:assert'
+import { createHash } from 'node:crypto'
+import { existsSync, readFileSync } from 'node:fs'
+import {
+	mkdir,
+	mkdtemp,
+	rename,
+	rm,
+	writeFile
+} from 'node:fs/promises'
+import { dirname, isAbsolute, join } from 'node:path'
+import { defineTool, type RegisteredTool } from '../../server.ts'
+
+const REPO = 'reclaimprotocol/builder-example'
+const BACKEND_PACKAGE = join('packages', 'backend', 'package.json')
+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
+
+export function exampleAppTool(fetchFn: typeof fetch = fetch): RegisteredTool {
+	return defineTool<{ projectDir: string }>(
+		{
+			name: 'create_example_app',
+			description:
+				'Writes the Reclaim example app (reclaimprotocol/builder-example: '
+				+ '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 '
+				+ '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.',
+			inputSchema: {
+				type: 'object',
+				required: ['projectDir'],
+				properties: {
+					projectDir: {
+						type: 'string',
+						description:
+							'Absolute path of the workspace root you were started in.',
+					},
+				},
+			},
+			annotations: { openWorldHint: true, destructiveHint: false },
+		},
+		async({ projectDir }) => {
+			assert(
+				isAbsolute(projectDir),
+				badRequest('`projectDir` must be an absolute path.'),
+			)
+			const commit = await latestCommit()
+			const files = await listFiles(commit)
+			const clientVersion = await latestClientVersion()
+			const staged = await Promise.all(files.map(async(file) => {
+				const bytes = await download(commit, file)
+				return {
+					path: file.path,
+					bytes: file.path === BACKEND_PACKAGE
+						? withClientVersion(bytes, clientVersion)
+						: bytes,
+				}
+			}))
+			const conflicts = staged
+				.filter(({ path, bytes }) => {
+					const dest = join(projectDir, path)
+					return existsSync(dest) && !readFileSync(dest).equals(bytes)
+				})
+				.map(({ path }) => path)
+			assert(
+				!conflicts.length,
+				conflict(
+					'These files already exist with different content: '
+					+ `${conflicts.join(', ')}. Ask the developer whether to use `
+					+ 'another directory or move them.',
+				),
+			)
+
+			// Stage inside projectDir, so the moves below stay on one filesystem.
+			const tmp = await mkdtemp(join(projectDir, '.reclaim-example-'))
+			try {
+				for(const { path, bytes } of staged) {
+					await mkdir(dirname(join(tmp, path)), { recursive: true })
+					await writeFile(join(tmp, path), bytes)
+				}
+
+				for(const { path } of staged) {
+					const dest = join(projectDir, path)
+					await mkdir(dirname(dest), { recursive: true })
+					await rename(join(tmp, path), dest)
+				}
+			} finally {
+				await rm(tmp, { recursive: true, force: true })
+			}
+
+			return {
+				projectDir,
+				repository: `https://github.com/${REPO}`,
+				commit,
+				files: staged.length,
+				clientVersion,
+				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: '
+					+ '"/reclaim/callback" }).',
+					'Put the provider in packages/backend/config.json and restart '
+					+ 'the backend.',
+				],
+			}
+		},
+	)
+
+	async function latestCommit() {
+		const res = await fetchFn(
+			`https://api.github.com/repos/${REPO}/commits/main`,
+			{ headers: { Accept: 'application/vnd.github.sha' } },
+		)
+		assert(res.ok, badGateway(`${REPO} commit lookup: HTTP ${res.status}`))
+		const text = await res.text()
+		const commit = text.trim()
+		assert(/^[0-9a-f]{40}$/.test(commit), badGateway('invalid commit SHA'))
+		return commit
+	}
+
+	async function listFiles(commit: string) {
+		const res = await fetchFn(
+			`https://api.github.com/repos/${REPO}/git/trees/${commit}?recursive=1`,
+			{ headers: { Accept: 'application/vnd.github+json' } },
+		)
+		assert(res.ok, badGateway(`${REPO} file listing: HTTP ${res.status}`))
+		const tree: unknown = await res.json()
+		assert(
+			typeof tree === 'object' && tree !== null && 'tree' in tree
+			&& Array.isArray(tree.tree) && !('truncated' in tree && tree.truncated),
+			badGateway(`unexpected ${REPO} file listing`),
+		)
+		const files = tree.tree
+			.filter((e: unknown) => {
+				return typeof e === 'object' && e !== null && 'type' in e
+					&& e.type === 'blob'
+			})
+			.map((entry: unknown) => {
+				assert(
+					typeof entry === 'object' && entry !== null
+					&& 'path' in entry && typeof entry.path === 'string'
+					&& entry.path.split('/').every((s) => /^[\w@.-]+$/.test(s)
+						&& s !== '.' && s !== '..' && s !== '.git')
+					&& 'sha' in entry && typeof entry.sha === 'string'
+					&& 'size' in entry && typeof entry.size === 'number',
+					badGateway(`unexpected entry in the ${REPO} file listing`),
+				)
+				return { path: entry.path, sha: entry.sha, size: entry.size }
+			})
+		assert(
+			files.length > 0 && files.length <= MAX_FILES
+			&& files.reduce((n, f) => n + f.size, 0) <= MAX_BYTES,
+			badGateway(`unexpected ${REPO} size`),
+		)
+		return files
+	}
+
+	async function download(commit: string, file: { path: string, sha: string }) {
+		const res = await fetchFn(
+			`https://raw.githubusercontent.com/${REPO}/${commit}/${file.path}`,
+		)
+		assert(res.ok, badGateway(`${file.path}: HTTP ${res.status}`))
+		const bytes = Buffer.from(await res.arrayBuffer())
+		assert(
+			gitBlobSha(bytes) === file.sha,
+			badGateway(`${file.path} failed its integrity check`),
+		)
+		return bytes
+	}
+
+	async function latestClientVersion() {
+		const res = await fetchFn(
+			`https://registry.npmjs.org/${CLIENT_PACKAGE.replace('/', '%2f')}/latest`,
+		)
+		assert(res.ok, badGateway(`npm ${CLIENT_PACKAGE}: HTTP ${res.status}`))
+		const body: unknown = await res.json()
+		assert(
+			typeof body === 'object' && body !== null && 'version' in body
+			&& typeof body.version === 'string'
+			&& /^\d+\.\d+\.\d+$/.test(body.version),
+			badGateway(`npm ${CLIENT_PACKAGE}: no version`),
+		)
+		return body.version
+	}
+}
+
+/** The backend's package.json with the client range set to `^version`. */
+function withClientVersion(bytes: Buffer, version: string) {
+	const text = bytes.toString('utf8')
+	const next = text.replace(
+		/("@reclaimprotocol\/client"\s*:\s*")[^"]*(")/,
+		(_, open: string, close: string) => `${open}^${version}${close}`,
+	)
+	assert(
+		next !== text || text.includes(`"^${version}"`),
+		badGateway(`${BACKEND_PACKAGE} has no ${CLIENT_PACKAGE} dependency`),
+	)
+	return Buffer.from(next)
+}
+
+/** Git's blob object id: sha1 of `blob <size>\0<content>`. */
+function gitBlobSha(bytes: Buffer) {
+	return createHash('sha1')
+		.update(`blob ${bytes.length}\0`)
+		.update(bytes)
+		.digest('hex')
+}