@reclaimprotocol/agent 0.1.38 → 0.1.40

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

@@ -11,24 +11,33 @@ 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, type RegisteredTool } from '../../server.ts'
+import { assertNoSymlinks, upsertEnvVar } from '../authenticate/eth-key.ts'
 
 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 = 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',
@@ -37,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'],
@@ -56,11 +67,12 @@ export function exampleAppTool(fetchFn: typeof fetch = fetch): RegisteredTool {
 			},
 			annotations: { openWorldHint: true, destructiveHint: false },
 		},
-		async({ projectDir }) => {
+		async(args) => {
 			assert(
-				isAbsolute(projectDir),
+				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()
@@ -73,7 +85,17 @@ export function exampleAppTool(fetchFn: typeof fetch = fetch): RegisteredTool {
 						: 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)
@@ -88,44 +110,72 @@ export function exampleAppTool(fetchFn: typeof fetch = fetch): RegisteredTool {
 				),
 			)
 
-			// 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`,
@@ -190,7 +240,7 @@ export function exampleAppTool(fetchFn: typeof fetch = fetch): RegisteredTool {
 
 	async function latestClientVersion() {
 		const res = await fetchFn(
-			`https://registry.npmjs.org/${CLIENT_PACKAGE.replace('/', '%2f')}/latest`,
+			`https://registry.npmjs.org/${encodeURIComponent(CLIENT_PACKAGE)}/latest`,
 		)
 		assert(res.ok, badGateway(`npm ${CLIENT_PACKAGE}: HTTP ${res.status}`))
 		const body: unknown = await res.json()
@@ -204,6 +254,54 @@ export function exampleAppTool(fetchFn: typeof fetch = fetch): RegisteredTool {
 	}
 }
 
+/**
+ * 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: string, path: string, bytes: Buffer) {
+	const parts = path.split('/')
+	let dir = root
+	for(const part of parts.slice(0, -1)) {
+		dir = join(dir, part)
+		await mkdir(dir).catch((err: unknown) => {
+			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: unknown) {
+	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: Buffer, version: string) {
 	const text = bytes.toString('utf8')
@@ -225,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)
+	}
+}

package/src/mcp/tools/authenticate/issue-org-keypair.ts

@@ -1,16 +1,24 @@
+import { conflict } from '@hapi/boom'
 import { deriveFromPrivateKey, generateKeypair } from '@reclaimprotocol/client'
-import type { ReclaimClient } from '@reclaimprotocol/client/api'
+import { isProblemError, type ReclaimClient } from '@reclaimprotocol/client/api'
 import assert from 'node:assert'
 import { isAbsolute, relative, resolve } from 'node:path'
 import { defineTool, type RegisteredTool } from '../../server.ts'
-import { normalizeEthHex, readDotenvKey, upsertEnvVar } from './eth-key.ts'
+import {
+	backupEnvVar,
+	normalizeEthHex,
+	readDotenvKey,
+	removeEnvVar,
+	upsertEnvVar,
+} from './eth-key.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 function issueOrgKeypairTool(client: ReclaimClient): RegisteredTool {
 	return defineTool<{
@@ -19,6 +27,7 @@ export function issueOrgKeypairTool(client: ReclaimClient): RegisteredTool {
 		envFile?: string
 		envVar?: string
 		encryptResults?: boolean
+		replace?: boolean
 	}>(
 		{
 			name: 'issue_org_keypair',
@@ -30,8 +39,12 @@ export function issueOrgKeypairTool(client: ReclaimClient): RegisteredTool {
 				+ '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'],
@@ -55,11 +68,18 @@ export function issueOrgKeypairTool(client: ReclaimClient): RegisteredTool {
 					encryptResults: {
 						type: 'boolean',
 						description:
-							'Encrypt delivered results to this key. Default false.',
+							'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(
@@ -75,24 +95,60 @@ export function issueOrgKeypairTool(client: ReclaimClient): RegisteredTool {
 				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,
@@ -100,6 +156,28 @@ export function issueOrgKeypairTool(client: ReclaimClient): RegisteredTool {
 				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/src/mcp/tools/authenticate/issue-org-token.ts

@@ -2,7 +2,7 @@ import type { ReclaimClient } from '@reclaimprotocol/client/api'
 import assert from 'node:assert'
 import { isAbsolute, relative, resolve } from 'node:path'
 import { defineTool, type RegisteredTool } from '../../server.ts'
-import { upsertEnvVar } from './eth-key.ts'
+import { backupEnvVar, readDotenvKey, upsertEnvVar } from './eth-key.ts'
 import { saveOrgKey } from './org-key-store.ts'
 
 /**
@@ -24,7 +24,9 @@ export function issueOrgTokenTool(client: ReclaimClient): RegisteredTool {
 				+ '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: {
@@ -69,6 +71,14 @@ export function issueOrgTokenTool(client: ReclaimClient): RegisteredTool {
 			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,
 			)
@@ -78,6 +88,7 @@ export function issueOrgTokenTool(client: ReclaimClient): RegisteredTool {
 				envFile: path,
 				envVar,
 				last4: data.last4,
+				backupFile: backupFile ?? null,
 			}
 		},
 	)

package/src/provider/draft.ts

@@ -132,10 +132,11 @@ export function assertPortableMatches(
 	// proving an email's domain substring. Reject it regardless of the declared
 	// targets (the local part is usually not itself a target, so the value scan
 	// below wouldn't catch it). Strip params + named groups + regex escapes
-	// first, then look for `localpart@` as a surviving literal.
+	// first, then look for `localpart@` as a surviving literal. A placeholder
+	// never contains a brace, and `[^{}]` keeps the scan linear on `{{{{…`.
 	const EMAIL_LOCAL_BAKED = /[A-Za-z0-9._%+-]{3,}@/
 	const deregex = (s: string): string => s
-		.replace(/\{\{[^}]*\}\}/g, '')
+		.replace(/\{\{[^{}]*\}\}/g, '')
 		.replace(/\(\?<[^>]*>[^)]*\)/g, '')
 		.replace(/\\(.)/g, '$1')
 	const scanEmail = (text: string, where: string) => {
@@ -168,7 +169,7 @@ export function assertPortableMatches(
 		return
 	}
 
-	const stripParams = (s: string): string => s.replace(/\{\{[^}]*\}\}/g, '')
+	const stripParams = (s: string): string => s.replace(/\{\{[^{}]*\}\}/g, '')
 	const scan = (text: string, where: string, own: string | null) => {
 		const bare = stripParams(text)
 		for(const v of guarded) {

package/src/provider/matcher.ts

@@ -789,7 +789,7 @@ function stableOpeningTail(openTag: string): string {
  *  content (the JSON body the attestor exposes when a jsonPath is paired with
  *  the script's xPath); otherwise undefined. */
 function scriptJsonContent(markup: string): string | undefined {
-	const match = /^<script\b[^>]*>([\s\S]*)<\/script>\s*$/i.exec(markup)
+	const match = /^<script\b[^>]*>([\s\S]*)<\/script\b[^>]*>\s*$/i.exec(markup)
 	if(!match) {
 		return undefined
 	}