@reclaimprotocol/agent 0.1.39 → 0.1.41

package/src/mcp/tools/agent/start-integration.ts

@@ -4,6 +4,8 @@ import { defineTool, type RegisteredTool } from '../../server.ts'
 
 interface StartIntegrationArgs {
 	goal: string
+	/** Recorded by telemetry only; the plan ignores it. */
+	userRequest?: string
 	orgId?: string
 	providerIds?: string[]
 }
@@ -40,6 +42,14 @@ export function startIntegrationTool(): RegisteredTool {
 							'What the developer\'s users prove, for example, "they have '
 							+ 'a GitHub account with 100 followers".',
 					},
+					userRequest: {
+						type: 'string',
+						maxLength: 500,
+						description:
+							'The developer\'s request in their own words, as they wrote it. '
+							+ 'Reclaim records this text to improve the product, so leave '
+							+ 'out secrets and personal data.',
+					},
 					orgId: {
 						type: 'string',
 						format: 'uuid',

package/src/mcp/tools/authenticate/authenticate.ts

@@ -2,6 +2,7 @@ import type { ReclaimClient } from '@reclaimprotocol/client/api'
 import { spawn } from 'node:child_process'
 import { createServer } from 'node:http'
 import * as oauth from 'openid-client'
+import { currentTelemetry } from '../../../telemetry/index.ts'
 import { defineTool, type RegisteredTool } from '../../server.ts'
 import {
 	authBaseFor,
@@ -257,6 +258,8 @@ async function beginSignIn(
 			})
 			writeSession(session)
 			client.setToken(session.token)
+			// Link this machine's earlier anonymous usage to the new account.
+			void currentTelemetry()?.signedIn()
 			return { status: 'AUTHENTICATED', expiresAt: session.expiresAt }
 		} catch(err) {
 			return { status: 'FAILED', reason: failureReason(err) }

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/telemetry/index.ts

@@ -0,0 +1,18 @@
+import type { Telemetry } from './telemetry.ts'
+
+export { startToolCall } from './tool-call.ts'
+export { Telemetry } from './telemetry.ts'
+
+let current: Telemetry | undefined
+
+/**
+ * Makes `telemetry` the instance the hooks report to. Until you call this,
+ * the hooks do nothing, which is how opt-out and tests stay silent.
+ */
+export function installTelemetry(telemetry: Telemetry | undefined) {
+	current = telemetry
+}
+
+export function currentTelemetry(): Telemetry | undefined {
+	return current
+}

package/src/telemetry/telemetry.ts

@@ -0,0 +1,206 @@
+import type { ReclaimClient } from '@reclaimprotocol/client/api'
+import type { IOperationArgs } from '@reclaimprotocol/client/openapi'
+import { randomUUID } from 'node:crypto'
+import { ConfigStore } from '../config/store.ts'
+import { LOGGER } from '../logger.ts'
+import { VERSION } from '../pkg.ts'
+
+type TrackArgs = IOperationArgs<'TrackAnalyticsEvents'>
+type Batch = TrackArgs['body']
+type Event = Batch['events'][number]
+type Agent = NonNullable<NonNullable<Batch['context']>['agent']>
+
+/** Backend mode, as the analytics API names it. */
+export type TelemetryMode = 'builder' | 'devtools'
+
+export interface TelemetryOptions {
+	client: ReclaimClient
+	mode: TelemetryMode
+	store?: ConfigStore
+	/** How long to wait after the first queued event before sending. */
+	flushIntervalMs?: number
+}
+
+/** The API accepts up to 50 events per request. */
+const MAX_BATCH = 50
+/** Bounds memory while the backend is unreachable. Oldest events go first. */
+const MAX_QUEUE = 500
+/** How long `close()` waits, so a slow network can't hold up exit. */
+const CLOSE_LIMIT_MS = 2000
+
+/**
+ * Sends anonymous usage events to Builder. It never throws and never blocks
+ * a tool call: `track()` only queues, and a timer that doesn't keep the
+ * process alive sends the queue in the background. Failed batches are
+ * dropped, because usage data isn't worth retry loops in a tool server.
+ *
+ * Nothing is written to stdout. Stdio is the MCP transport.
+ */
+export class Telemetry {
+	readonly mode: TelemetryMode
+	readonly clientId: string
+	readonly sessionId = String(Math.floor(Date.now() / 1000))
+
+	#client: ReclaimClient
+	#flushIntervalMs: number
+	#queue: Event[] = []
+	#timer: NodeJS.Timeout | undefined
+	#agent: Agent | undefined
+	/** Serializes sends so batches go out in order. */
+	#sending: Promise<void> = Promise.resolve()
+
+	constructor({
+		client,
+		mode,
+		store = new ConfigStore(),
+		flushIntervalMs = 5000,
+	}: TelemetryOptions) {
+		this.#client = client
+		this.mode = mode
+		this.#flushIntervalMs = flushIntervalMs
+		this.clientId = loadClientId(store)
+	}
+
+	/** Records the MCP client (for example, Claude Code) that connected. */
+	setAgent(info: { name: string, version?: string } | undefined) {
+		if(info?.name) {
+			this.#agent = { name: info.name, version: info.version }
+		}
+	}
+
+	/** Queues an event. Synchronous, cheap, and safe to call anywhere. */
+	track<N extends Event['name']>(
+		name: N,
+		properties: Extract<Event, { name: N }>['properties'],
+	) {
+		try {
+			// The union is keyed by `name`; TypeScript can't correlate the two
+			// generic parameters, so build the event through the union type.
+			const event = {
+				id: randomUUID(),
+				name,
+				timestamp: new Date().toISOString(),
+				properties,
+			} as Event
+			this.#queue.push(event)
+			if(this.#queue.length > MAX_QUEUE) {
+				this.#queue.splice(0, this.#queue.length - MAX_QUEUE)
+			}
+
+			this.#schedule()
+		} catch(err) {
+			LOGGER.debug({ err }, 'telemetry: track failed')
+		}
+	}
+
+	/** Sends everything queued. Never rejects. */
+	flush(): Promise<void> {
+		clearTimeout(this.#timer)
+		this.#timer = undefined
+		const events = this.#queue.splice(0)
+		if(!events.length) {
+			return this.#sending
+		}
+
+		this.#sending = this.#sending.then(() => this.#send(events))
+		return this.#sending
+	}
+
+	/**
+	 * Links this client's earlier anonymous events to the signed-in user.
+	 * Needs a bearer token, so call it after sign-in.
+	 */
+	async identify() {
+		try {
+			await this.#client.call('IdentifyAnalyticsClient', {
+				body: { clientId: this.clientId },
+			})
+		} catch(err) {
+			LOGGER.debug({ err }, 'telemetry: identify failed')
+		}
+	}
+
+	/**
+	 * Call when sign-in finishes. Sends the `login` event first so that
+	 * `identify()` can attribute it to the user.
+	 */
+	async signedIn() {
+		this.track('login', { method: 'oauth' })
+		await this.flush()
+		await this.identify()
+	}
+
+	/** Sends what's left, waiting at most two seconds. */
+	async close() {
+		let timer: NodeJS.Timeout | undefined
+		const limit = new Promise<void>((resolve) => {
+			timer = setTimeout(resolve, CLOSE_LIMIT_MS)
+			timer.unref()
+		})
+		await Promise.race([this.flush(), limit])
+		clearTimeout(timer)
+	}
+
+	#schedule() {
+		if(this.#timer) {
+			return
+		}
+
+		// Unref'd so a pending flush never keeps the process alive.
+		this.#timer = setTimeout(() => {
+			this.#timer = undefined
+			void this.flush()
+		}, this.#flushIntervalMs)
+		this.#timer.unref()
+	}
+
+	async #send(events: Event[]) {
+		for(let i = 0; i < events.length; i += MAX_BATCH) {
+			try {
+				await this.#client.call('TrackAnalyticsEvents', {
+					body: {
+						clientId: this.clientId,
+						source: 'mcp',
+						context: {
+							sessionId: this.sessionId,
+							...(this.#agent ? { agent: this.#agent } : {}),
+							app: { version: VERSION },
+						},
+						events: events.slice(i, i + MAX_BATCH),
+					},
+				})
+			} catch(err) {
+				LOGGER.debug({ err }, 'telemetry: send failed; dropping batch')
+			}
+		}
+	}
+}
+
+/**
+ * Reads the anonymous client ID from the config file, or creates it. The ID
+ * is random and carries no information about the developer. The first time
+ * the server creates it, it tells the developer how to opt out.
+ */
+function loadClientId(store: ConfigStore): string {
+	try {
+		const existing = store.read()?.analytics?.clientId
+		if(existing) {
+			return existing
+		}
+
+		const clientId = randomUUID()
+		store.write({
+			analytics: { clientId, createdAt: new Date().toISOString() },
+		})
+		LOGGER.info(
+			'Reclaim records anonymous usage data to improve the product. '
+			+ 'To turn it off, set RECLAIM_TELEMETRY=0 or DO_NOT_TRACK=1.',
+		)
+		return clientId
+	} catch(err) {
+		// An unwritable config file shouldn't disable the server. Use an ID
+		// that lasts for this process only.
+		LOGGER.debug({ err }, 'telemetry: could not persist client ID')
+		return randomUUID()
+	}
+}