@reclaimprotocol/agent 0.1.39 → 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

@@ -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 } from "../../server.js";
+import { assertNoSymlinks, upsertEnvVar } from "../authenticate/eth-key.js";
 const REPO = 'reclaimprotocol/builder-example';
 /** GitHub tree paths are always `/`-separated, on every OS. */
 const BACKEND_PACKAGE = 'packages/backend/package.json';
@@ -21,19 +23,30 @@ 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'],
@@ -60,10 +73,16 @@ export function exampleAppTool(fetchFn = fetch) {
                     : 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);
@@ -72,28 +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.'));
-        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`, { headers: { Accept: 'application/vnd.github.sha' } });
         assert(res.ok, badGateway(`${REPO} commit lookup: HTTP ${res.status}`));
@@ -184,17 +238,6 @@ async function installFile(root, path, bytes) {
 function isEexist(err) {
     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, path) {
-    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, version) {
     const text = bytes.toString('utf8');
@@ -209,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;

package/lib/mcp/tools/authenticate/issue-org-keypair.js

@@ -1,14 +1,17 @@
+import { conflict } from '@hapi/boom';
 import { deriveFromPrivateKey, generateKeypair } from '@reclaimprotocol/client';
+import { isProblemError } from '@reclaimprotocol/client/api';
 import assert from 'node:assert';
 import { isAbsolute, relative, resolve } from 'node:path';
 import { defineTool } from "../../server.js";
-import { normalizeEthHex, readDotenvKey, upsertEnvVar } from "./eth-key.js";
+import { backupEnvVar, normalizeEthHex, readDotenvKey, removeEnvVar, upsertEnvVar, } from "./eth-key.js";
 /**
  * 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 function issueOrgKeypairTool(client) {
     return defineTool({
@@ -20,8 +23,12 @@ export function issueOrgKeypairTool(client) {
             + 'private key to a server env file in the project (reusing a key '
             + 'already there) and registers only the public key. Returns the '
             + 'address, file, and variable; never the key. Returns 409 when the '
-            + 'org already has a different key: ask the developer for that key '
-            + 'rather than replacing it.',
+            + 'org already has a different key. Set `replace: true` only when '
+            + 'the developer asked to rotate or replace the key: it generates '
+            + 'a new key and swaps it in one step, and apps holding the old '
+            + 'key can no longer decrypt new results. The old key is first '
+            + 'appended to `<envFile>.backup` (gitignored); tell the developer '
+            + 'its path.',
         inputSchema: {
             type: 'object',
             required: ['orgId', 'projectDir'],
@@ -42,11 +49,17 @@ export function issueOrgKeypairTool(client) {
                 },
                 encryptResults: {
                     type: 'boolean',
-                    description: 'Encrypt delivered results to this key. Default false.',
+                    description: 'Encrypt delivered results to this key. Default false, or the '
+                        + 'org\'s current setting with `replace`.',
+                },
+                replace: {
+                    type: 'boolean',
+                    description: 'Rotate: generate a new key and replace the org\'s current '
+                        + 'one. Default false.',
                 },
             },
         },
-        annotations: { openWorldHint: true, destructiveHint: false },
+        annotations: { openWorldHint: true, destructiveHint: true },
     }, async (args) => {
         assert(isAbsolute(args.projectDir), new Error('`projectDir` must be an absolute path.'));
         const envFile = args.envFile || '.env';
@@ -54,22 +67,53 @@ export function issueOrgKeypairTool(client) {
         const envPath = resolve(args.projectDir, envFile);
         const inside = relative(args.projectDir, envPath);
         assert(inside && !inside.startsWith('..') && !isAbsolute(inside), new Error('`envFile` must be inside `projectDir`.'));
-        const existing = readDotenvKey(envPath, envVar);
+        const replace = args.replace ?? false;
+        // Rotation always generates a fresh key: the env file's key may or
+        // may not be the one the org holds, and reuse would be a no-op.
+        const existing = replace ? undefined : readDotenvKey(envPath, envVar);
         const keypair = existing
             ? deriveFromPrivateKey(normalizeEthHex(existing))
             : generateKeypair();
-        // Register first: a 409 (the org has another key) must not leave a
-        // key Builder doesn't know in the env file.
-        const canEncryptResult = args.encryptResults ?? false;
-        await client.call('SetOrgKeypair', {
-            params: { orgId: args.orgId },
-            body: {
-                publicKey: keypair.publicKey,
-                canEncryptResult,
-                replace: false,
-            },
-        });
+        // A rotation keeps the org's current setting unless the caller sets it.
+        const canEncryptResult = args.encryptResults
+            ?? (replace && await currentCanEncryptResult());
+        // Back up and save the key before the org switches to it, so a
+        // failed write can't leave the org on a key no app holds. A failed
+        // registration (for example, a 409) puts the env file back.
+        const old = readDotenvKey(envPath, envVar);
+        const backupFile = old && !existing
+            ? backupEnvVar(args.projectDir, envFile, envVar, 'replaced by issue_org_keypair')
+            : undefined;
         const path = upsertEnvVar(args.projectDir, envFile, envVar, keypair.privateKey);
+        try {
+            await client.call('SetOrgKeypair', {
+                params: { orgId: args.orgId },
+                body: {
+                    publicKey: keypair.publicKey,
+                    canEncryptResult,
+                    replace,
+                },
+            });
+        }
+        catch (err) {
+            if (old) {
+                upsertEnvVar(args.projectDir, envFile, envVar, old);
+            }
+            else {
+                removeEnvVar(args.projectDir, envFile, envVar);
+            }
+            if (!replace && isProblemError(err) && err.output.statusCode === 409) {
+                throw conflict('The org already has a different key. Ask the developer to '
+                    + 'choose: (a) reuse it: they paste its private key into '
+                    + `\`${envFile}\` as \`${envVar}\` themselves, never into the `
+                    + 'chat; (b) rotate it: call `issue_org_keypair` again with '
+                    + '`replace: true`, after which apps holding the old key can no '
+                    + 'longer decrypt new results; (c) turn off result encryption: '
+                    + 'call `update_org_keypair` with `canEncryptResult: false`, '
+                    + 'which keeps the key.');
+            }
+            throw err;
+        }
         return {
             orgId: args.orgId,
             address: keypair.address,
@@ -77,6 +121,27 @@ export function issueOrgKeypairTool(client) {
             envFile: path,
             envVar,
             reused: Boolean(existing),
+            backupFile: backupFile ?? null,
+            ...(replace && !backupFile && !old
+                ? {
+                    note: 'Nothing was backed up: the old private key is not in '
+                        + 'this file. Another app may hold it.',
+                }
+                : {}),
         };
+        async function currentCanEncryptResult() {
+            try {
+                const { data } = await client.call('GetOrgKeypair', {
+                    params: { orgId: args.orgId },
+                });
+                return data.canEncryptResult;
+            }
+            catch (err) {
+                if (isProblemError(err) && err.output.statusCode === 404) {
+                    return false;
+                }
+                throw err;
+            }
+        }
     });
 }

package/lib/mcp/tools/authenticate/issue-org-token.js

@@ -1,7 +1,7 @@
 import assert from 'node:assert';
 import { isAbsolute, relative, resolve } from 'node:path';
 import { defineTool } from "../../server.js";
-import { upsertEnvVar } from "./eth-key.js";
+import { backupEnvVar, readDotenvKey, upsertEnvVar } from "./eth-key.js";
 import { saveOrgKey } from "./org-key-store.js";
 /**
  * Issues an organization API key and stores it on disk, so the key never
@@ -15,7 +15,9 @@ export function issueOrgTokenTool(client) {
             + 'server env file in the project, so the app can read it at runtime. '
             + 'Also saves it on this machine for the org-key tools. Returns the '
             + 'org, file, variable, and last four characters; never the key. '
-            + 'Replaces an existing variable of the same name in the file. '
+            + 'Replaces an existing variable of the same name in the file, first '
+            + 'appending the old value to `<envFile>.backup` (gitignored); tell '
+            + 'the developer its path. '
             + 'Adds the file to .gitignore. Use when the app needs a key, or '
             + 'before `create_verification_session`.',
         inputSchema: {
@@ -48,6 +50,10 @@ export function issueOrgTokenTool(client) {
         const { data } = await client.call('IssueOrgToken', {
             params: { orgId: args.orgId },
         });
+        const old = readDotenvKey(resolve(args.projectDir, envFile), envVar);
+        const backupFile = old && old !== data.orgSecret
+            ? backupEnvVar(args.projectDir, envFile, envVar, 'replaced by issue_org_token')
+            : undefined;
         const path = upsertEnvVar(args.projectDir, envFile, envVar, data.orgSecret);
         saveOrgKey(args.orgId, data.orgSecret);
         return {
@@ -55,6 +61,7 @@ export function issueOrgTokenTool(client) {
             envFile: path,
             envVar,
             last4: data.last4,
+            backupFile: backupFile ?? null,
         };
     });
 }