@reclaimprotocol/agent 0.1.1 → 0.1.3

package/src/mcp/server.ts

@@ -1,11 +1,4 @@
-import { Server } from '@modelcontextprotocol/sdk/server/index.js'
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
-import type { Tool } from '@modelcontextprotocol/sdk/types.js'
-import {
-	CallToolRequestSchema,
-	ListToolsRequestSchema,
-} from '@modelcontextprotocol/sdk/types.js'
 import type { JSONSchema } from 'zod/v4/core'
 import { toZod } from './api/to-zod.ts'
 import { remapErrorAsResponse } from './remap_errors.ts'
@@ -79,42 +72,3 @@ export function registerToolList(server: McpServer, tools: RegisteredTool[]) {
 		)
 	}
 }
-
-export class ReclaimMcpServer {
-	#tools = new Map<string, RegisteredTool>()
-	#server: Server
-
-	constructor() {
-		this.#server = new Server(
-			{ name: 'reclaim-agent', version: '0.1.0' },
-			{ capabilities: { tools: {} } },
-		)
-
-		this.#server.setRequestHandler(ListToolsRequestSchema, async() => ({
-			// Double-cast: our `ToolDefinition` carries the same fields as the
-			// SDK's `Tool` but the SDK's type is strict-narrowed and won't
-			// accept ours without going through `unknown`.
-			tools: [...this.#tools.values()].map(
-				(t) => t.definition as unknown as Tool,
-			),
-		}))
-
-		this.#server.setRequestHandler(CallToolRequestSchema, async(req) => {
-			const tool = this.#tools.get(req.params.name)
-			if(!tool) {
-				throw new Error(`unknown tool: ${req.params.name}`)
-			}
-
-			const result = await tool.handler(req.params.arguments ?? {})
-			return { content: [{ type: 'text', text: JSON.stringify(result) }] }
-		})
-	}
-
-	register(tool: RegisteredTool) {
-		this.#tools.set(tool.definition.name, tool)
-	}
-
-	async listen(): Promise<void> {
-		await this.#server.connect(new StdioServerTransport())
-	}
-}

package/src/mcp/start.ts

@@ -1,8 +1,14 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
-import { DEFAULT_BASE_URL, ReclaimClient } from '@reclaimprotocol/client'
-import { DEFAULT_OLD_API_URL, ReclaimOldClient } from '../old/client.ts'
-import { useOldDevtools } from '../old/flag.ts'
+import { ReclaimClient } from '@reclaimprotocol/client'
+import {
+	agentDisabled,
+	apiToken,
+	apiUrl,
+	oldApiUrl,
+	useOldDevtools,
+} from '../consts.ts'
+import { ReclaimOldClient } from '../old/client.ts'
 import { resolveInitialIdentity } from '../old/identity.ts'
 import { OLD_MODE_INSTRUCTIONS } from '../old/instructions.ts'
 import { buildOldBackendTools } from '../old/tools/build.ts'
@@ -34,7 +40,7 @@ export async function startMcpServer() {
 	// backend-independent and registered in both modes. Skipped in hosted
 	// deployments — set RECLAIM_AGENT_DISABLED=1 to register only the API
 	// surface.
-	const agentToolsEnabled = process.env.RECLAIM_AGENT_DISABLED !== '1'
+	const agentToolsEnabled = !agentDisabled()
 
 	if(oldMode) {
 		// OLD-devtools mode (the default): the legacy backend is still in
@@ -42,7 +48,7 @@ export async function startMcpServer() {
 		// are disabled; a small ReclaimOldClient serves authenticate / publish /
 		// get_me_providers instead.
 		const oldClient = new ReclaimOldClient({
-			baseUrl: process.env.RECLAIM_OLD_API_URL || DEFAULT_OLD_API_URL,
+			baseUrl: oldApiUrl(),
 			identity: resolveInitialIdentity(),
 		})
 
@@ -55,9 +61,9 @@ export async function startMcpServer() {
 		// NOTE: registerTools() is intentionally NOT called — generated tools off.
 	} else {
 		const client = new ReclaimClient({
-			baseUrl: process.env.RECLAIM_API_URL || DEFAULT_BASE_URL,
+			baseUrl: apiUrl(),
 			// Priority: explicit env var → cached session token → unauthenticated
-			token: process.env.RECLAIM_API_TOKEN || readSession()?.token,
+			token: apiToken() || readSession()?.token,
 			headers: { 'User-Agent': `${NAME}/${VERSION}` },
 		})
 

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

@@ -1,12 +1,8 @@
 /**
  * Factory entry-point for embedding the reclaim-agent's MCP tools into
- * a host MCP server. Two consumers:
- *
- *   - The agent's own standalone `src/index.ts` (uses `ReclaimMcpServer`,
- *     the low-level wrapper around `@modelcontextprotocol/sdk`'s Server).
- *   - `@reclaimprotocol/client`'s MCP server (uses `McpServer`, the
- *     high-level SDK wrapper). Calls `registerAgentTools` to fold the
- *     agent's 16 tools alongside its auto-generated API tools.
+ * a host MCP server via `registerToolList` (server.ts) on the high-level
+ * `@modelcontextprotocol/sdk` `McpServer`. Folds the agent's tools
+ * alongside the auto-generated API tools.
  *
  * Shared state — Chrome attach state, capture store, secret store — is
  * built once per server and threaded through every tool factory.
@@ -45,8 +41,8 @@ function buildAgentState(): AgentState {
 	}
 }
 
-/** Build the flat list of `RegisteredTool` entries. Useful when the host
- *  uses our internal `ReclaimMcpServer` interface (`.register(tool)`).
+/** Build the flat list of `RegisteredTool` entries, ready for
+ *  `registerToolList`.
  *  Pass `client` to include the builder `create_provider_version_from_capture`;
  *  omit it (e.g. OLD-devtools mode) to register only the backend-independent
  *  capture/proof tools — old mode supplies its own publish tool. */

package/src/mcp/tools/agent/proof.ts

@@ -1,5 +1,6 @@
 import { mkdirSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
+import { agentTraceEnabled } from '../../../consts.ts'
 import { reclaimHomeDirPath } from '../../../paths.ts'
 import {
 	runAttestorProof,
@@ -237,7 +238,7 @@ export function proofTool(secrets: SecretStore): RegisteredTool {
 			// when investigating proof failures and the file at runLogPath
 			// will carry the input provider, sentParams, full attestor log
 			// stream, and result.
-			if(process.env['RECLAIM_AGENT_TRACE'] === '1') {
+			if(agentTraceEnabled()) {
 				const runLogPath = writeProofRunDump({
 					provider,
 					hasSecretParamsRef: secretParamsRef !== undefined,

package/src/mcp/tools/agent/publish.ts

@@ -1,39 +1,158 @@
 import type { ReclaimClient } from '@reclaimprotocol/client'
+import type { JSONSchema } from 'zod/v4/core'
+import { INJECTION_GUIDE } from '../../../provider/injection-doc.ts'
+import {
+	countsFor,
+	matchRedactionWarnings,
+} from '../../../provider/match-redaction-warning.ts'
 import type { ReclaimProvider } from '../../../provider/schema.ts'
+import type { AllowedJsRequest } from '../../../provider/to-version.ts'
 import {
 	nextVersion,
 	providerToCreateVersionRequest,
 } from '../../../provider/to-version.ts'
 import { defineTool, type RegisteredTool } from '../../server.ts'
 
+/** Schemas shared by the top-level `provider`/`providers` and the lighter
+ *  `allowedJsRequests` drafts — keeps the request shape from drifting between
+ *  them. */
+const RESPONSE_MATCHES_SCHEMA: JSONSchema.Schema = {
+	type: 'array',
+	description: 'What the attestor checks on the revealed response slice.',
+	items: {
+		type: 'object',
+		properties: {
+			type: { type: 'string', enum: ['regex', 'contains'] },
+			value: { type: 'string' },
+		},
+		required: ['type', 'value'],
+	},
+}
+
+const RESPONSE_REDACTIONS_SCHEMA: JSONSchema.Schema = {
+	type: 'array',
+	description:
+		'Which portions of the response the prover reveals ' +
+		'(xPath / jsonPath / regex; hash to OPRF the value). Paired with ' +
+		'responseMatches by index — keep them aligned 1-to-1. If you list more ' +
+		'redactions than matches, the tool pads matches with no-op optional ' +
+		'entries so older index-paired claim creators stay happy.',
+	items: {
+		type: 'object',
+		properties: {
+			xPath: { type: 'string' },
+			jsonPath: { type: 'string' },
+			regex: { type: 'string' },
+			hash: { type: 'string', enum: ['oprf', 'oprf-mpc', 'oprf-raw'] },
+		},
+	},
+}
+
+/** Properties every drafted request shares (top-level providers and the
+ *  injected `allowedJsRequests`). */
+const REQUEST_DRAFT_PROPERTIES: Record<string, JSONSchema.Schema> = {
+	url: {
+		type: 'string',
+		description:
+			'Exact API URL the attestor replays, with {{param}} placeholders ' +
+			'for any templated values.',
+	},
+	method: { type: 'string', enum: ['GET', 'POST', 'PUT', 'PATCH'] },
+	body: { type: 'string', description: 'Request body template, if any.' },
+	responseMatches: RESPONSE_MATCHES_SCHEMA,
+	responseRedactions: RESPONSE_REDACTIONS_SCHEMA,
+}
+
+/** A full provider draft (from propose_provider), passed through verbatim. */
+const PROVIDER_SCHEMA: JSONSchema.Schema = {
+	type: 'object',
+	description:
+		'A `provider` object from propose_provider, passed through verbatim — ' +
+		'the tool builds the version body (the requests[] entry etc.) for you.',
+	properties: {
+		name: { type: 'string', description: 'Verification name.' },
+		...REQUEST_DRAFT_PROPERTIES,
+		headers: {
+			type: 'object',
+			description:
+				'Request headers from the capture. Secret headers are stripped ' +
+				'before persistence; the client re-supplies them at runtime.',
+		},
+		paramValues: {
+			type: 'object',
+			description:
+				'Real values for the {{param}} placeholders, e.g. ' +
+				'{ "username": "Syed" }.',
+		},
+	},
+	required: ['name', 'url', 'method', 'responseMatches'],
+}
+
+/** One `allowedJsRequests` template: a request the injection script may fire,
+ *  plus pagination/optionality flags. */
+const ALLOWED_JS_REQUEST_SCHEMA: JSONSchema.Schema = {
+	type: 'object',
+	properties: {
+		...REQUEST_DRAFT_PROPERTIES,
+		multiple: {
+			type: 'boolean',
+			description:
+				'Allow the template to match many requests (e.g. pagination). ' +
+				'Default true.',
+		},
+		required: {
+			type: 'boolean',
+			description:
+				'Fail validation if no request matches this template. Default true.',
+		},
+	},
+	required: ['url', 'method'],
+}
+
+interface PublishArgs {
+	providerId: string
+	/** Single-provider back-compat input; normalized to `[provider]`. */
+	provider?: ReclaimProvider
+	/** Multi-request input — one version carrying every request. */
+	providers?: ReclaimProvider[]
+	initialUrl: string
+	notes?: string
+	version?: { major: number, minor: number, patch: number }
+	jsUserScripts?: string
+	allowedJsRequests?: AllowedJsRequest[]
+}
+
 export function createVersionFromCaptureTool(
 	client: ReclaimClient,
 ): RegisteredTool {
-	return defineTool<{
-		providerId: string
-		provider: ReclaimProvider
-		initialUrl: string
-		notes?: string
-		version?: { major: number, minor: number, patch: number }
-	}>(
+	return defineTool<PublishArgs>(
 		{
 			name: 'create_provider_version_from_capture',
 			description:
-				'Persist a drafted ReclaimProvider as a verification version. ' +
-				'Call this after run_proof succeeds, passing the `provider` object ' +
-				'from propose_provider VERBATIM. This tool builds the full version ' +
+				'Persist drafted ReclaimProvider(s) as a verification version. ' +
+				'Call this after run_proof succeeds, passing the `provider` ' +
+				'object(s) from propose_provider VERBATIM. This tool builds the ' +
 				'body (the requests[] array, webSettings, etc.) for you — do NOT ' +
 				'hand-construct that shape or call create_provider_version directly. ' +
+				'For a MULTI-REQUEST provider, pass `providers: [...]` (each entry a ' +
+				'proven draft) — every entry becomes one request in the version, and ' +
+				'all are required at verification time. Pass a single `provider` ' +
+				'for the one-request case (exactly one of `provider`/`providers`). ' +
+				'For data gated behind login/navigation, supply `jsUserScripts` (a ' +
+				'page-injection script that drives the page to where the request ' +
+				'fires) and/or `allowedJsRequests` (extra requests the script may ' +
+				'fire, e.g. pagination). ' +
 				'Omit `version` to have the tool auto-select the next available ' +
 				'version (it lists existing versions and bumps past the highest). ' +
 				'The version lands on the draft branch — to go live, call ' +
 				'`publish_provider_version` (PRIVATE) or ' +
 				'`submit_provider_version_for_review` (PUBLIC) afterwards. ' +
 				'`requiredContext` is derived from any {{context.<name>}} ' +
-				'placeholders and returned on the created version — when ' +
-				'present, tell the dev verbatim which context fields consumers ' +
-				'MUST send when creating sessions (verification matches those ' +
-				'values exactly; a missing field is a 400 at session create). ' +
+				'placeholders across ALL requests (plus injected requests / script) ' +
+				'and returned on the created version — when present, tell the dev ' +
+				'verbatim which context fields consumers MUST send when creating ' +
+				'sessions (verification matches those values exactly; a missing ' +
+				'field is a 400 at session create). ' +
 				'Refine types/descriptions via `update_provider_version` while ' +
 				'still on draft.',
 			inputSchema: {
@@ -43,77 +162,15 @@ export function createVersionFromCaptureTool(
 						type: 'string',
 						description: 'UUID of the verification to publish the version on.',
 					},
-					provider: {
-						type: 'object',
+					provider: PROVIDER_SCHEMA,
+					providers: {
+						type: 'array',
 						description:
-							'The `provider` object from propose_provider, passed ' +
-							'through verbatim — the tool builds the version body ' +
-							'(the requests[] array etc.) for you.',
-						properties: {
-							name: { type: 'string', description: 'Verification name.' },
-							url: {
-								type: 'string',
-								description:
-									'Exact API URL the attestor replays, with {{param}} ' +
-									'placeholders for any templated values.',
-							},
-							method: {
-								type: 'string',
-								enum: ['GET', 'POST', 'PUT', 'PATCH'],
-							},
-							headers: {
-								type: 'object',
-								description:
-									'Request headers from the capture. Secret headers are ' +
-									'stripped before persistence; the client re-supplies them ' +
-									'at runtime.',
-							},
-							body: {
-								type: 'string',
-								description: 'Request body template, if any.',
-							},
-							responseMatches: {
-								type: 'array',
-								description:
-									'What the attestor checks on the revealed response slice.',
-								items: {
-									type: 'object',
-									properties: {
-										type: { type: 'string', enum: ['regex', 'contains'] },
-										value: { type: 'string' },
-									},
-									required: ['type', 'value'],
-								},
-							},
-							responseRedactions: {
-								type: 'array',
-								description:
-									'Which portions of the response the prover reveals ' +
-									'(xPath / jsonPath / regex; hash to OPRF the value). ' +
-									'Paired with responseMatches by index — the tool folds ' +
-									'each one into the matching entry\'s `extract` in the ' +
-									'persisted version, so keep them aligned 1-to-1.',
-								items: {
-									type: 'object',
-									properties: {
-										xPath: { type: 'string' },
-										jsonPath: { type: 'string' },
-										regex: { type: 'string' },
-										hash: {
-											type: 'string',
-											enum: ['oprf', 'oprf-mpc', 'oprf-raw'],
-										},
-									},
-								},
-							},
-							paramValues: {
-								type: 'object',
-								description:
-									'Real values for the {{param}} placeholders, ' +
-									'e.g. { "username": "Syed" }.',
-							},
-						},
-						required: ['name', 'url', 'method', 'responseMatches'],
+							'Multiple proven drafts → one multi-request version. Each ' +
+							'entry has the same shape as `provider`. Pass this OR ' +
+							'`provider`, not both.',
+						items: PROVIDER_SCHEMA,
+						minItems: 1,
 					},
 					initialUrl: {
 						type: 'string',
@@ -139,25 +196,86 @@ export function createVersionFromCaptureTool(
 						},
 						required: ['major', 'minor', 'patch'],
 					},
+					jsUserScripts: {
+						type: 'string',
+						description:
+							'Plain JavaScript injected into the provider page before every ' +
+							'page load (stored as webSettings.jsUserScripts). Use standard ' +
+							'browser APIs (window.location, element.click(), forms) to ' +
+							'drive login/navigation so the target request fires — the ' +
+							'client already intercepts page requests, and window.Reclaim ' +
+							'is only for rare edge cases, not navigation. The Builder ' +
+							'verification client installs this to run before every page ' +
+							'load (before navigating to initialUrl), matching old-devtool ' +
+							'customInjection; window.Reclaim itself is not yet exposed ' +
+							'there, so prefer plain browser JS. Guide:\n\n' +
+							INJECTION_GUIDE,
+					},
+					allowedJsRequests: {
+						type: 'array',
+						description:
+							'Extra requests the injection script is allowed to fire ' +
+							'(e.g. paginated API calls), as RequestSelectionTemplates. ' +
+							'`multiple`/`required` default to true.',
+						items: ALLOWED_JS_REQUEST_SCHEMA,
+					},
 				},
-				required: ['providerId', 'provider', 'initialUrl'],
+				required: ['providerId', 'initialUrl'],
 			},
 		},
 		async(args) => {
+			// Exactly one of `provider` / `providers` — normalize to an array.
+			const hasMany = Array.isArray(args.providers) && args.providers.length > 0
+			const hasOne = !!args.provider
+			if(hasMany === hasOne) {
+				throw new Error(
+					'Pass exactly one of `provider` (a single draft) or ' +
+					'`providers` (an array of 1+ drafts).',
+				)
+			}
+
+			const providers = hasMany ? args.providers! : [args.provider!]
+
 			// Auto-pick the next version if not explicit
 			const ver = args.version ?? (await nextVersion(client, args.providerId))
 
-			const body = providerToCreateVersionRequest(
-				args.provider,
-				args.initialUrl,
-				args.notes,
-				ver,
-			)
-			const result = (await client.call('CreateProviderVersion', {
+			const body = providerToCreateVersionRequest(providers, args.initialUrl, {
+				notes: args.notes,
+				version: ver,
+				jsUserScripts: args.jsUserScripts,
+				allowedJsRequests: args.allowedJsRequests,
+			})
+			const result = await client.call('CreateProviderVersion', {
 				params: { providerId: args.providerId },
 				body,
-			}))
-			return result.data
+			})
+
+			const created = result.data
+
+			// Aggregate non-blocking advisories for the dev — nothing here blocks
+			// or alters what was published; the author keeps full control.
+			const notes: string[] = []
+
+			// Match/redaction advisory across every request (+ injected requests).
+			const requestCounts = [
+				...providers.map((p, i) => countsFor(`Request ${i + 1}`, p)),
+				...(args.allowedJsRequests ?? []).map(
+					(r, i) => countsFor(`Injected request ${i + 1}`, r),
+				),
+			]
+			notes.push(...matchRedactionWarnings(requestCounts))
+
+			// Let the dev know how/when the script runs (and the window.Reclaim gap).
+			if(args.jsUserScripts?.trim()) {
+				notes.push(
+					'jsUserScripts will run in the Builder verification client before ' +
+					'every page load (before navigating to initialUrl), matching ' +
+					'old-devtool customInjection. window.Reclaim is not yet exposed ' +
+					'there, so prefer plain browser JS for navigation/interaction.',
+				)
+			}
+
+			return notes.length ? { ...created, _notes: notes } : created
 		},
 	)
 }

package/src/mcp/tools/authenticate/decrypt-key.ts

@@ -1,19 +1,15 @@
 /**
- * Optional X25519 decryption key — only needed when testing ENCRYPTED callback
- * payloads in the consumer role. Resolution is file-only (no env var, no path
- * override, no `~/.reclaim` caching):
+ * Optional eth decryption key — only needed when testing ENCRYPTED callback
+ * payloads in the consumer role. The org's results are ECIES-encrypted to its
+ * eth public key; this is the matching eth PRIVATE key (`0x`-hex). Resolution:
  *
- *   1. An X25519 PKCS#8 PEM file named `reclaim-decrypt.pem` in the project
- *      root. Mint it with openssl:
- *
- *        openssl genpkey -algorithm X25519 -out reclaim-decrypt.pem
- *
- *   2. Absent — plaintext-only testing (no decryption key; encrypted
+ *   1. The `RECLAIM_DECRYPT_KEY` env var (a `0x`-prefixed 32-byte hex key), or
+ *   2. A file named `reclaim-decrypt.key` in the project root holding that hex.
+ *   3. Absent — plaintext-only testing (no decryption key; encrypted
  *      deliveries surface a clear error).
  *
- * The PEM *content* is loaded via the client's `loadDecryptionKey` (jose
- * `ECDH-ES`) and passed straight through as `ReclaimConfig.credential` / to
- * `decryptCallback`.
+ * The hex is loaded via the client's `loadDecryptionKey` and passed straight
+ * through as `ReclaimConfig.credential` / to `decryptCallback`.
  */
 import {
 	type DecryptionKey,
@@ -23,34 +19,33 @@ import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { findProjectRoot } from '../../../paths.ts'
 
-/** Default X25519 PEM filename the agent looks for in the project root. */
-export const DEFAULT_DECRYPT_PEM = 'reclaim-decrypt.pem'
-
-/** Resolve the decrypt-PEM path (the default file in the project root). */
-export function decryptPemPath(
-	projectDir = findProjectRoot(process.cwd()),
-): string {
-	return join(projectDir, DEFAULT_DECRYPT_PEM)
-}
+/** Default eth decrypt-key filename the agent looks for in the project root. */
+const DEFAULT_DECRYPT_KEY_FILE = 'reclaim-decrypt.key'
 
 /**
- * Read the raw decryption-key PEM string from the default file, without loading
- * it. Returns `undefined` when the file is absent (plaintext-only).
+ * Read the raw eth decryption-key hex — from `RECLAIM_DECRYPT_KEY` or the
+ * default file — without loading it. Returns `undefined` when neither is
+ * present (plaintext-only).
  */
-export function resolveDecryptKeyInput(
+function resolveDecryptKeyInput(
 	projectDir = findProjectRoot(process.cwd()),
 ): string | undefined {
-	const pemPath = decryptPemPath(projectDir)
-	if(existsSync(pemPath)) {
-		return readFileSync(pemPath, 'utf8')
+	const fromEnv = process.env.RECLAIM_DECRYPT_KEY?.trim()
+	if(fromEnv) {
+		return fromEnv
+	}
+
+	const keyPath = join(projectDir, DEFAULT_DECRYPT_KEY_FILE)
+	if(existsSync(keyPath)) {
+		return readFileSync(keyPath, 'utf8').trim()
 	}
 
 	return undefined
 }
 
 /**
- * Load the optional decryption key. Returns `undefined` when the PEM file is
- * absent (the consumer then handles only plaintext deliveries).
+ * Load the optional decryption key. Returns `undefined` when no key is
+ * configured (the consumer then handles only plaintext deliveries).
  */
 export async function resolveDecryptionKey(
 	projectDir = findProjectRoot(process.cwd()),

package/src/mcp/tools/authenticate/eth-key.ts

@@ -12,11 +12,12 @@
  * Generated/imported keys are written to the project `.env` (mode 0600, and the
  * file is added to `.gitignore`). NO `~/.reclaim` caching. This is a LOCAL
  * signing key only — unrelated to org auth (the org secret) or encryption
- * (the X25519 decrypt key).
+ * (the eth decrypt key).
  */
 import { deriveFromPrivateKey } from '@reclaimprotocol/client'
 import { existsSync, readFileSync, writeFileSync } from 'node:fs'
 import { isAbsolute, join } from 'node:path'
+import { privateKey, privateKeyFile } from '../../../consts.ts'
 import { findProjectRoot } from '../../../paths.ts'
 
 const ENV_VAR = 'RECLAIM_PRIVATE_KEY'
@@ -65,10 +66,10 @@ function readDotenvKey(path: string): string | undefined {
 }
 
 /** The explicit raw-hex key-file path, if `RECLAIM_PRIVATE_KEY_FILE` is set. */
-export function ethKeyFilePath(
+function ethKeyFilePath(
 	projectDir = findProjectRoot(process.cwd()),
 ): string | undefined {
-	const p = process.env.RECLAIM_PRIVATE_KEY_FILE
+	const p = privateKeyFile()
 	if(!p) {
 		return undefined
 	}
@@ -97,7 +98,7 @@ function resolved(
 export function resolveEthKey(
 	projectDir = findProjectRoot(process.cwd()),
 ): ResolvedEthKey | undefined {
-	const env = process.env.RECLAIM_PRIVATE_KEY
+	const env = privateKey()
 	if(env?.trim()) {
 		return resolved(normalizeEthHex(env), 'env')
 	}
@@ -120,27 +121,6 @@ export function resolveEthKey(
 	return undefined
 }
 
-/**
- * Resolve the eth proof-owner private key (0x-hex) or throw a clear, actionable
- * error. Used by the proof flow that can't proceed without a signing key.
- */
-export function requireEthPrivateKey(
-	projectDir = findProjectRoot(process.cwd()),
-): string {
-	const r = resolveEthKey(projectDir)
-	if(!r) {
-		throw new Error(
-			'No eth proof-owner key found. Set RECLAIM_PRIVATE_KEY (0x-hex), add a '
-				+ `RECLAIM_PRIVATE_KEY=0x… line to ${join(projectDir, ENV_FILE)}, or `
-				+ 'point RECLAIM_PRIVATE_KEY_FILE at a file holding the raw hex. Run '
-				+ 'issue_credentials to generate one, or import_credentials to use a '
-				+ 'key you already hold.',
-		)
-	}
-
-	return r.privateKey
-}
-
 /** Append `entry` to the project `.gitignore` if not already present. */
 function ensureGitignored(projectDir: string, entry: string): void {
 	const path = join(projectDir, '.gitignore')

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

@@ -13,7 +13,7 @@ export function issueTool(): RegisteredTool {
 				'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 X25519 decrypt key). ALWAYS confirm with ' +
+				'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.',

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

@@ -5,7 +5,7 @@ import { verificationResultTool } from './result.ts'
  * Builder-mode verification tools: higher-level orchestrations over the
  * generated API surface. `get_verification_result` authenticates with the org
  * token, checks status, pulls the stored payload, and decrypts it locally with
- * the optional X25519 key — a flow the generated raw-API tools can't express
+ * 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
  * agent over the generated tools (`get_verification_session`,
  * `list_verification_events`, `list_verification_deliveries`), whose