@reclaimprotocol/agent 0.1.33 → 0.1.35

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

@@ -5,68 +5,53 @@ import { writeEthKey } from './eth-key.ts'
 
 export function importTool(): RegisteredTool {
 	return defineTool<{
-		privateKey?: string
-		keyFile?: string
+		keyFile: string
 		projectDir?: string
 	}>(
 		{
 			name: 'import_credentials',
 			description:
-				'Import an eth proof-owner key the dev already holds and persist it ' +
-				'to the project `.env` as RECLAIM_PRIVATE_KEY=0x… (mode 0600; `.env` ' +
-				'added to .gitignore). Provide EITHER `privateKey` (raw 0x-hex, 64 ' +
-				'chars) OR `keyFile` (path to a file holding the raw 0x-hex key). ' +
-				'The address is derived locally; the private key is never ' +
-				'returned. This is a local signing key only (not registered ' +
-				'with any server, ' +
-				'unrelated to org auth or encryption).',
+				'Imports an eth proof-owner key from a file the developer already '
+				+ 'holds. Reads the raw 0x-hex key from `keyFile` and writes it to '
+				+ 'the project `.env` as RECLAIM_PRIVATE_KEY (mode 0600; `.env` '
+				+ 'added to .gitignore). Returns the derived address and the `.env` '
+				+ 'path; never the key. The key is a local signing key only: it is '
+				+ 'not registered with any server and is unrelated to org auth or '
+				+ 'encryption. To create a new key instead, use `issue_credentials`.',
 			inputSchema: {
 				type: 'object',
+				required: ['keyFile'],
 				properties: {
-					privateKey: {
-						type: 'string',
-						pattern: '^0x?[0-9a-fA-F]{64}$',
-						description:
-							'Raw Ethereum private key, 0x-prefixed hex (64 hex chars).',
-					},
 					keyFile: {
 						type: 'string',
 						description:
-							'Path to a file containing the raw 0x-hex private key ' +
-							'(absolute or project-relative).',
+							'Path to a file containing the raw 0x-hex private key '
+							+ '(absolute or relative to the working directory).',
 					},
 					projectDir: {
 						type: 'string',
 						description:
-							'Project directory whose `.env` the key is written to. ' +
-							'Defaults to the closest ancestor of cwd containing .git or ' +
-							'package.json.',
+							'Project directory whose `.env` the key is written to. '
+							+ 'Defaults to the closest ancestor of cwd containing .git or '
+							+ 'package.json.',
 					},
 				},
 			},
+			annotations: { readOnlyHint: false, destructiveHint: false },
 		},
 		async(args) => {
-			if(!args.privateKey && !args.keyFile) {
-				throw new Error('Provide either `privateKey` (0x-hex) or `keyFile`.')
-			}
-
-			if(args.privateKey && args.keyFile) {
-				throw new Error('Provide only one of `privateKey` or `keyFile`.')
-			}
-
 			const projectDir = findProjectRoot(args.projectDir || process.cwd())
-			const privateKeyHex = args.keyFile
-				? readFileSync(args.keyFile, 'utf8')
-				: args.privateKey!
-			const { path, address } = writeEthKey(privateKeyHex, projectDir)
+			const { path, address } = writeEthKey(
+				readFileSync(args.keyFile, 'utf8'), projectDir,
+			)
 
 			return {
 				address,
 				path,
 				note:
-					'Eth proof-owner key written to .env as RECLAIM_PRIVATE_KEY ' +
-					'(mode 0600). resolve_owner_key resolves it from .env. Keep .env ' +
-					'secret — it has been added to .gitignore.',
+					'Eth proof-owner key written to .env as RECLAIM_PRIVATE_KEY '
+					+ '(mode 0600). resolve_owner_key resolves it from .env. Keep .env '
+					+ 'secret: it has been added to .gitignore.',
 			}
 		},
 	)

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

@@ -0,0 +1,84 @@
+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 { saveOrgKey } from './org-key-store.ts'
+
+/**
+ * Issues an organization API key and stores it on disk, so the key never
+ * passes through the agent's transcript. Replaces the generated
+ * `issue_org_token` operation, which returned the key in its response.
+ */
+export function issueOrgTokenTool(client: ReclaimClient): RegisteredTool {
+	return defineTool<{
+		orgId: string
+		projectDir: string
+		envFile?: string
+		envVar?: string
+	}>(
+		{
+			name: 'issue_org_token',
+			description:
+				'Issues an organization API key (owner only) and writes it to a '
+				+ '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. '
+				+ 'Adds the file to .gitignore. Use when the app needs a key, or '
+				+ 'before `create_verification_session`.',
+			inputSchema: {
+				type: 'object',
+				required: ['orgId', 'projectDir'],
+				properties: {
+					orgId: { type: 'string', format: 'uuid' },
+					projectDir: {
+						type: 'string',
+						description: 'Absolute path of the app\'s project directory.',
+					},
+					envFile: {
+						type: 'string',
+						description:
+							'Env file to write, relative to `projectDir`. Default `.env`.',
+					},
+					envVar: {
+						type: 'string',
+						pattern: '^[A-Za-z_][A-Za-z0-9_]*$',
+						description:
+							'Variable name to set. Default `RECLAIM_ORG_SECRET`.',
+					},
+				},
+			},
+			annotations: { openWorldHint: true, destructiveHint: false },
+		},
+		async(args) => {
+			assert(
+				isAbsolute(args.projectDir),
+				new Error('`projectDir` must be an absolute path.'),
+			)
+			const envFile = args.envFile || '.env'
+			const envVar = args.envVar || 'RECLAIM_ORG_SECRET'
+			const inside = relative(
+				args.projectDir, resolve(args.projectDir, envFile),
+			)
+			assert(
+				inside && !inside.startsWith('..') && !isAbsolute(inside),
+				new Error('`envFile` must be inside `projectDir`.'),
+			)
+
+			const { data } = await client.call('IssueOrgToken', {
+				params: { orgId: args.orgId },
+			})
+			const path = upsertEnvVar(
+				args.projectDir, envFile, envVar, data.orgSecret,
+			)
+			saveOrgKey(args.orgId, data.orgSecret)
+			return {
+				orgId: args.orgId,
+				envFile: path,
+				envVar,
+				last4: data.last4,
+			}
+		},
+	)
+}

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

@@ -8,15 +8,14 @@ export function issueTool(): RegisteredTool {
 		{
 			name: 'issue_credentials',
 			description:
-				'Generate a fresh secp256k1 eth proof-owner key-pair (the key ' +
-				'that signs local claim creation) and write the raw private key to ' +
-				'the project `.env` as RECLAIM_PRIVATE_KEY=0x… (mode 0600; `.env` ' +
-				'added to .gitignore). This is a LOCAL signing key only — it is NOT ' +
-				'registered with any server and is unrelated to org auth (the org ' +
-				'secret) or encryption (the eth decrypt key). ALWAYS confirm with ' +
-				'the dev before generating a new key. After writing, run_proof picks ' +
-				'it up automatically via resolve_owner_key. The private key is never ' +
-				'returned in the response.',
+				'Generates a new secp256k1 eth proof-owner key and writes the '
+				+ 'private key to the project `.env` as RECLAIM_PRIVATE_KEY (mode '
+				+ '0600; `.env` added to .gitignore). Returns the address and the '
+				+ '`.env` path; never the key. The key is a local signing key only: '
+				+ 'it is not registered with any server and is unrelated to org auth '
+				+ 'or encryption. Confirm with the developer before replacing an '
+				+ 'existing key. `run_proof` then picks it up through '
+				+ '`resolve_owner_key`.',
 			inputSchema: {
 				type: 'object',
 				properties: {
@@ -29,6 +28,7 @@ export function issueTool(): RegisteredTool {
 					},
 				},
 			},
+			annotations: { destructiveHint: false },
 		},
 		async(args) => {
 			const projectDir = findProjectRoot(args.projectDir || process.cwd())

package/src/mcp/tools/authenticate/org-key-store.ts

@@ -0,0 +1,25 @@
+import { ConfigStore } from '../../../config/store.ts'
+
+/**
+ * Save an organization API key (`rorg_…`) in the local config (mode 0600), so
+ * the org-key tools can use it without the key passing through a transcript.
+ */
+export function saveOrgKey(orgId: string, secret: string) {
+	const saved = new ConfigStore().read()?.org_keys
+	new ConfigStore().write({
+		org_keys: {
+			byOrg: { ...saved?.byOrg, [orgId]: secret },
+			recent: orgId,
+		},
+	})
+}
+
+/**
+ * The saved key for `orgId`, or the most recently saved key when no org is
+ * given. Returns `undefined` when none is saved.
+ */
+export function savedOrgKey(orgId?: string): string | undefined {
+	const saved = new ConfigStore().read()?.org_keys
+	const id = orgId || saved?.recent
+	return id ? saved?.byOrg[id] : undefined
+}

package/src/mcp/tools/authenticate/resolve-owner-key.ts

@@ -19,18 +19,16 @@ export function resolveOwnerKeyTool(): RegisteredTool {
 		{
 			name: 'resolve_owner_key',
 			description:
-				'Resolve which eth proof-owner key run_proof should sign with — ' +
-				'call this BEFORE run_proof. Checks, in order: RECLAIM_PRIVATE_KEY ' +
-				'in the MCP env, a RECLAIM_PRIVATE_KEY=0x… line in the project .env, ' +
-				'then a file at RECLAIM_PRIVATE_KEY_FILE holding the raw hex. ' +
-				'Returns { ready: true, address, source } when one is ' +
-				'available — pass `address` to run_proof as `ownerAddress`. ' +
-				'Returns { ready: false } ' +
-				'when none exists: then ask the dev to generate one ' +
-				'(issue_credentials) or import one they already hold ' +
-				'(import_credentials, accepts 0x-hex or a key-file path), and call ' +
-				'resolve_owner_key again. Never exposes the private key.',
+				'Finds the eth proof-owner key `run_proof` signs with. Call it '
+				+ 'before `run_proof`. Checks RECLAIM_PRIVATE_KEY in the MCP env, a '
+				+ 'RECLAIM_PRIVATE_KEY line in the project .env, then the file at '
+				+ 'RECLAIM_PRIVATE_KEY_FILE. Returns { ready: true, address, source '
+				+ '}: pass `address` to `run_proof` as `ownerAddress`. Returns { '
+				+ 'ready: false } when none exists: ask the developer to create one '
+				+ 'with `issue_credentials` or import one with `import_credentials` '
+				+ '(a key file), then call it again. Never returns the key.',
 			inputSchema: { type: 'object', properties: {} },
+			annotations: { readOnlyHint: true, openWorldHint: false },
 		},
 		async() => {
 			const projectDir = findProjectRoot(process.cwd())
@@ -51,7 +49,7 @@ export function resolveOwnerKeyTool(): RegisteredTool {
 					`env, no RECLAIM_PRIVATE_KEY in ${join(projectDir, ENV_FILE)}, and ` +
 					'no RECLAIM_PRIVATE_KEY_FILE. Ask the dev to generate one via ' +
 					'issue_credentials, or import one they already hold via ' +
-					'import_credentials (0x-hex or a key-file path). Then call ' +
+					'import_credentials (a key file). Then call ' +
 					'resolve_owner_key again and pass its address to run_proof as ' +
 					'ownerAddress.',
 			}

package/src/mcp/tools/mode/mode.ts

@@ -53,6 +53,7 @@ export function buildModeTools(
 					},
 					required: ['mode'],
 				},
+				annotations: { openWorldHint: false, idempotentHint: true },
 			},
 			async(parsed) => {
 				config.write({ mode: parsed.mode })
@@ -84,6 +85,7 @@ export function buildModeTools(
 					+ 'the staleness with an error naming the tool to re-run. Which '
 					+ 'login authorizes what: how_it_works({ topic: "auth" }).',
 				inputSchema: { type: 'object', properties: {} },
+				annotations: { readOnlyHint: true, openWorldHint: false },
 			},
 			async() => {
 				const persisted = config.read()?.mode

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

@@ -1,4 +1,6 @@
 import type { RegisteredTool } from '../../server.ts'
+import { proxyCallbackEventsTool } from './proxy-callback-events.ts'
+import { readCallbackEventsTool } from './read-callback-events.ts'
 import { verificationResultTool } from './result.ts'
 
 /**
@@ -6,11 +8,17 @@ import { verificationResultTool } from './result.ts'
  * generated API surface. `get_verification_result` authenticates with the org
  * token, checks status, pulls the stored payload, and decrypts it locally with
  * the optional eth key — a flow the generated raw-API tools can't express
- * (the decryption key never leaves the consumer). Diagnosis is left to the
+ * (the decryption key never leaves the consumer). `read_callback_events` and
+ * `proxy_callback_events` read and forward the org's pull-listener events.
+ * Diagnosis is left to the
  * agent over the generated tools (`get_verification_session`,
  * `list_verification_events`, `list_verification_deliveries`), whose
  * descriptions carry the lifecycle and delivery semantics.
  */
 export function buildVerificationTools(): RegisteredTool[] {
-	return [verificationResultTool()]
+	return [
+		verificationResultTool(),
+		readCallbackEventsTool(),
+		proxyCallbackEventsTool(),
+	]
 }

package/src/mcp/tools/verification/callback-listener.ts

@@ -0,0 +1,203 @@
+import { badGateway } from '@hapi/boom'
+import { ReclaimClient } from '@reclaimprotocol/client/api'
+import type { IOperationResponse } from '@reclaimprotocol/client/openapi'
+import assert from 'node:assert'
+import { setTimeout as delay } from 'node:timers/promises'
+import { apiUrl } from '../../../consts.ts'
+import { LOGGER } from '../../../logger.ts'
+import { NAME, VERSION } from '../../../pkg.ts'
+
+/** Runtime seams. Production passes none; tests pass a stub `fetch`. */
+export interface CallbackDeps {
+	fetch?: typeof globalThis.fetch
+	/** Waits between heartbeats and polls. Resolves, without error, on abort. */
+	sleep?: (ms: number, signal: AbortSignal) => Promise<void>
+	keeper?: ListenerKeeper
+}
+
+/**
+ * Events the org's pull listener subscribes to: the five session-ending
+ * events (the first four carry the signed result; `session_expired` has no
+ * result) plus the lifecycle milestones an app developer checks while testing.
+ * High-volume diagnostics (`network_request_observed`, `provider_script_log`,
+ * `user_interaction_*`) are left out, so a forwarded session sends the app at
+ * most 11 requests instead of dozens.
+ */
+export const LISTENER_EVENTS = [
+	'verification_success',
+	'verification_rejected',
+	'verification_error',
+	'verification_cancelled',
+	'session_expired',
+	'session_pending',
+	'verification_client_opened',
+	'authenticated',
+	'verification_proofs_completed',
+	'verification_result_submitting',
+	'verification_result_submission_failed',
+] as const
+
+export type ListenerInfo = {
+	subscriptionId: string
+	created: boolean
+	/** When the lease lapses unless the heartbeat renews it. */
+	expiresAt: string
+}
+
+export type CallbackEvent
+	= IOperationResponse<'ListCallbackEvents'>['items'][number]
+
+/**
+ * A client that presents the organization's API key. With a `signal`, every
+ * request aborts when it does.
+ */
+export function orgClient(
+	secret: string,
+	deps: CallbackDeps = {},
+	signal?: AbortSignal,
+) {
+	const base = deps.fetch || globalThis.fetch
+	return new ReclaimClient({
+		baseUrl: apiUrl(),
+		token: secret,
+		fetch: signal
+			? (input, init) => base(input, { ...init, signal })
+			: deps.fetch,
+		headers: { 'User-Agent': `${NAME}/${VERSION}` },
+	})
+}
+
+/** Renewal interval. The backend lease lasts 90 seconds. */
+const HEARTBEAT_MS = 30_000
+/** Upper bound for releasing all listeners at shutdown. */
+const RELEASE_TIMEOUT_MS = 3_000
+
+type Entry = {
+	/** Aborts with the entry, so a renew in flight cannot outlive a release. */
+	client: ReclaimClient
+	/** Not bound to the abort signal: it must still send the release. */
+	releaseClient: ReclaimClient
+	abort: AbortController
+	/** The first lease; concurrent callers share it. */
+	ready: Promise<ListenerInfo>
+	settled: boolean
+}
+
+/**
+ * Keeps each org's pull listener alive while this MCP process runs. Creating
+ * the subscription is the heartbeat: it renews a lease, and the listener
+ * stops receiving events when the lease lapses. {@link release} ends the
+ * lease at shutdown.
+ */
+export class ListenerKeeper {
+	#entries = new Map<string, Entry>()
+
+	/** Creates or renews the listener and starts its heartbeat (once). */
+	async ensure(secret: string, deps: CallbackDeps = {}): Promise<ListenerInfo> {
+		const existing = this.#entries.get(secret)
+		if(existing) {
+			const wasSettled = existing.settled
+			const first = await existing.ready
+			// Callers that arrived during creation share its result.
+			return wasSettled ? await renew(existing.client) : first
+		}
+
+		const abort = new AbortController()
+		const client = orgClient(secret, deps, abort.signal)
+		const sleep = deps.sleep || sleepFor
+		const entry: Entry = {
+			client,
+			releaseClient: orgClient(secret, deps),
+			abort,
+			settled: false,
+			ready: renew(client).then((info) => {
+				entry.settled = true
+				void this.#beat(entry, sleep)
+				return info
+			}, (err: unknown) => {
+				if(this.#entries.get(secret) === entry) {
+					this.#entries.delete(secret)
+				}
+
+				abort.abort()
+				throw err
+			}),
+		}
+		this.#entries.set(secret, entry)
+		return await entry.ready
+	}
+
+	/** Ends every lease and stops the heartbeats, within a short timeout. */
+	async release() {
+		const entries = [...this.#entries.values()]
+		this.#entries.clear()
+		const timeout = AbortSignal.timeout(RELEASE_TIMEOUT_MS)
+		await Promise.all(entries.map(async({ releaseClient, abort }) => {
+			abort.abort()
+			try {
+				await Promise.race([
+					releaseClient.call('ReleaseCallbackListener', {}),
+					new Promise((_, reject) => {
+						timeout.addEventListener('abort', () => reject(timeout.reason))
+					}),
+				])
+			} catch(err) {
+				LOGGER.warn({ err }, 'releasing the callback listener failed')
+			}
+		}))
+	}
+
+	async #beat(entry: Entry, sleep: NonNullable<CallbackDeps['sleep']>) {
+		const { signal } = entry.abort
+		while(!signal.aborted) {
+			await sleep(HEARTBEAT_MS, signal)
+			if(signal.aborted) {
+				return
+			}
+
+			try {
+				await renew(entry.client)
+			} catch(err) {
+				if(signal.aborted) {
+					return
+				}
+
+				LOGGER.warn({ err }, 'callback listener heartbeat failed; retrying')
+			}
+		}
+	}
+}
+
+const defaultKeeper = new ListenerKeeper()
+
+/** Releases every listener this process keeps alive. Runs at MCP shutdown. */
+export function releaseAllListeners() {
+	return defaultKeeper.release()
+}
+
+/**
+ * Create the org's pull listener and keep it alive until shutdown. An org has
+ * one, so a second call returns the existing subscription (HTTP 200).
+ */
+export function ensureListener(secret: string, deps: CallbackDeps = {}) {
+	return (deps.keeper || defaultKeeper).ensure(secret, deps)
+}
+
+async function renew(client: ReclaimClient): Promise<ListenerInfo> {
+	const { data, response } = await client.call('CreateCallbackSubscription', {
+		body: { deliveryMode: 'pull', events: [...LISTENER_EVENTS] },
+	})
+	assert(
+		data.listenerExpiresAt,
+		badGateway('Builder returned a pull listener without a lease.'),
+	)
+	return {
+		subscriptionId: data.id,
+		created: response.status === 201,
+		expiresAt: data.listenerExpiresAt,
+	}
+}
+
+export async function sleepFor(ms: number, signal: AbortSignal) {
+	await delay(ms, undefined, { signal }).catch(() => undefined)
+}

package/src/mcp/tools/verification/index.ts

@@ -1,2 +1,4 @@
 // Barrel for the verification tool group (result retrieval + decryption).
 export { buildVerificationTools } from './build.ts'
+export { stopAllForwarders } from './proxy-callback-events.ts'
+export { releaseAllListeners } from './callback-listener.ts'