@reclaimprotocol/agent 0.1.38 → 0.1.40

package/lib/mcp/api/operations.gen.d.ts

@@ -444,6 +444,13 @@ export declare const MCP_TOOLS: {
             openWorldHint: boolean;
         };
     };
+    UpdateOrgKeypair: {
+        description: string;
+        inputSchema: import("zod").ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>;
+        annotations: {
+            openWorldHint: boolean;
+        };
+    };
     UpdateProvider: {
         description: string;
         inputSchema: import("zod").ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>;

package/lib/mcp/api/operations.gen.js

@@ -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.
@@ -5058,7 +5058,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": {
@@ -6578,7 +6578,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": {
@@ -6855,6 +6855,52 @@ 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/lib/mcp/instructions.js

@@ -48,7 +48,8 @@ const TOPIC_SUMMARIES = {
     '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 '
@@ -60,15 +61,16 @@ const TOPIC_SUMMARIES = {
         + '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/lib/mcp/tools/agent/example-app.d.ts

@@ -1,2 +1,6 @@
 import { type RegisteredTool } from '../../server.ts';
-export declare function exampleAppTool(fetchFn?: typeof fetch): RegisteredTool;
+export declare function exampleAppTool(fetchFn?: typeof fetch, isPortFree?: (port: number) => Promise<boolean>): RegisteredTool;
+/** 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 declare function isLoopbackPortFree(port: number): Promise<boolean>;

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

@@ -11,28 +11,42 @@ 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 { mkdir, realpath, rm, writeFile } from 'node:fs/promises';
+import { connect } from 'node:net';
+import { isAbsolute, join, relative, sep } from 'node:path';
 import { defineTool } from "../../server.js";
+import { assertNoSymlinks, upsertEnvVar } from "../authenticate/eth-key.js";
 const REPO = 'reclaimprotocol/builder-example';
-const BACKEND_PACKAGE = join('packages', 'backend', 'package.json');
+/** GitHub tree paths are always `/`-separated, on every OS. */
+const BACKEND_PACKAGE = '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) {
+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 = fetch, isPortFree = isLoopbackPortFree) {
     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 '
+            + '`@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'],
@@ -44,8 +58,9 @@ export function exampleAppTool(fetchFn = fetch) {
             },
         },
         annotations: { openWorldHint: true, destructiveHint: false },
-    }, async ({ projectDir }) => {
-        assert(isAbsolute(projectDir), badRequest('`projectDir` must be an absolute path.'));
+    }, async (args) => {
+        assert(isAbsolute(args.projectDir), badRequest('`projectDir` must be an absolute path.'));
+        const projectDir = await realpath(args.projectDir);
         const commit = await latestCommit();
         const files = await listFiles(commit);
         const clientVersion = await latestClientVersion();
@@ -58,7 +73,16 @@ export function exampleAppTool(fetchFn = fetch) {
                     : bytes,
             };
         }));
-        const conflicts = staged
+        for (const path of [...staged.map((f) => f.path), BACKEND_ENV_FILE]) {
+            assertNoSymlinks(projectDir, path);
+        }
+        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);
@@ -67,41 +91,63 @@ export function exampleAppTool(fetchFn = fetch) {
         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 });
+        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`, { headers: { Accept: 'application/vnd.github.sha' } });
         assert(res.ok, badGateway(`${REPO} commit lookup: HTTP ${res.status}`));
@@ -142,7 +188,7 @@ export function exampleAppTool(fetchFn = fetch) {
         return bytes;
     }
     async function latestClientVersion() {
-        const res = await fetchFn(`https://registry.npmjs.org/${CLIENT_PACKAGE.replace('/', '%2f')}/latest`);
+        const res = await fetchFn(`https://registry.npmjs.org/${encodeURIComponent(CLIENT_PACKAGE)}/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
@@ -151,6 +197,47 @@ export function exampleAppTool(fetchFn = fetch) {
         return body.version;
     }
 }
+/**
+ * Write one file under `root` without following a symlink out of it or
+ * replacing anything: each parent is created one level at a time and must be
+ * a real directory, the file is created exclusively (`wx` fails on any path
+ * that appeared since the conflict scan, symlinks included), and its real
+ * path is checked to still be inside `root` afterwards. A file already there
+ * with the same bytes (a re-run) is left as is.
+ */
+async function installFile(root, path, bytes) {
+    const parts = path.split('/');
+    let dir = root;
+    for (const part of parts.slice(0, -1)) {
+        dir = join(dir, part);
+        await mkdir(dir).catch((err) => {
+            if (!isEexist(err)) {
+                throw err;
+            }
+        });
+        assertNoSymlinks(root, relative(root, dir));
+    }
+    const dest = join(dir, parts.at(-1));
+    try {
+        await writeFile(dest, bytes, { flag: 'wx' });
+    }
+    catch (err) {
+        if (!isEexist(err)) {
+            throw err;
+        }
+        assertNoSymlinks(root, path);
+        assert(readFileSync(dest).equals(bytes), conflict(`${path} appeared with different content; nothing replaced`));
+        return;
+    }
+    const real = await realpath(dest);
+    if (!real.startsWith(root + sep)) {
+        await rm(dest, { force: true });
+        throw badRequest(`${path} resolved outside the workspace; removed it`);
+    }
+}
+function isEexist(err) {
+    return err instanceof Error && 'code' in err && err.code === 'EEXIST';
+}
 /** The backend's package.json with the client range set to `^version`. */
 function withClientVersion(bytes, version) {
     const text = bytes.toString('utf8');
@@ -165,3 +252,23 @@ function gitBlobSha(bytes) {
         .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) {
+    const results = await Promise.all(LOOPBACK_HOSTS.map((host) => {
+        return new Promise((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/lib/mcp/tools/authenticate/eth-key.d.ts

@@ -38,6 +38,17 @@ export declare function ensureGitignored(projectDir: string, entry: string): voi
  * `envFile` is relative to `projectDir`.
  */
 export declare function upsertEnvVar(projectDir: string, envFile: string, name: string, value: string): string;
+/** Remove the `name=` line from a dotenv file, if there is one. */
+export declare function removeEnvVar(projectDir: string, envFile: string, name: string): void;
+/**
+ * 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 declare function backupEnvVar(projectDir: string, envFile: string, name: string, reason: string): string | undefined;
 /**
  * Persist a raw eth private key to the project `.env` as
  * `RECLAIM_PRIVATE_KEY=0x…` (upsert; mode 0600; `.env` added to `.gitignore`).
@@ -48,3 +59,7 @@ export declare function writeEthKey(privateKeyHex: string, projectDir?: string):
     path: string;
     address: string;
 };
+/** 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 declare function assertNoSymlinks(root: string, path: string): void;

package/lib/mcp/tools/authenticate/eth-key.js

@@ -15,10 +15,11 @@
  * 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, existsSync, mkdirSync, readFileSync, writeFileSync, } from 'node:fs';
-import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { closeSync, constants, existsSync, fchmodSync, lstatSync, mkdirSync, openSync, readFileSync, writeFileSync, } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { privateKey, privateKeyFile } from "../../../consts.js";
 import { findProjectRoot } from "../../../paths.js";
 const ENV_VAR = 'RECLAIM_PRIVATE_KEY';
@@ -111,7 +112,7 @@ export function ensureGitignored(projectDir, entry) {
         return;
     }
     const prefix = current && !current.endsWith('\n') ? '\n' : '';
-    writeFileSync(path, current + prefix + entry + '\n');
+    writeInside(projectDir, path, current + prefix + entry + '\n');
 }
 /**
  * Set `name=value` in a dotenv file, replacing an existing line or appending
@@ -132,12 +133,41 @@ export function upsertEnvVar(projectDir, envFile, name, value) {
         const prefix = existing && !existing.endsWith('\n') ? '\n' : '';
         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, envFile, name) {
+    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, envFile, name, reason) {
+    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`).
@@ -149,3 +179,39 @@ export function writeEthKey(privateKeyHex, projectDir = findProjectRoot(process.
     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, path) {
+    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, path, data, { 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);
+    }
+}

package/lib/mcp/tools/authenticate/issue-org-keypair.d.ts

@@ -1,10 +1,11 @@
-import type { ReclaimClient } from '@reclaimprotocol/client/api';
+import { type ReclaimClient } from '@reclaimprotocol/client/api';
 import { type RegisteredTool } from '../../server.ts';
 /**
  * Creates the organization's eth key pair for session binding and encrypted
  * results: writes the private key to the app's server env file and registers
  * only the public key with Builder, so the private key never passes through
  * the agent's transcript. Reuses a key the env file already holds, so a
- * repeat call (for example, to turn on encryption) keeps the same key.
+ * repeat call (for example, to turn on encryption) keeps the same key. With
+ * `replace`, always generates a fresh key and rotates the org's key to it.
  */
 export declare function issueOrgKeypairTool(client: ReclaimClient): RegisteredTool;