@reclaimprotocol/agent 0.1.33 → 0.1.35

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

@@ -7,6 +7,11 @@ import {
 	tailLogs,
 	warnsAndErrors,
 } from '../../../proof/attestor.ts'
+import {
+	type AttestorCheckResult,
+	type CheckAttestorOptions,
+	isNetworkError,
+} from '../../../proof/check-attestor.ts'
 
 function claimsDir(): string {
 	return join(reclaimHomeDirPath(), 'claims')
@@ -192,3 +197,53 @@ export function shapeRichProofResult(
 
 	return out
 }
+
+export interface ProofDiagnosis {
+	attestor: AttestorCheckResult
+	likelyCause: string
+	next: string
+}
+
+/**
+ * When an unverified proof failed with a network-like error, runs the
+ * attestor check once and says whether the attestor or the target site is the
+ * likely cause. Returns `undefined` for verified proofs and other errors.
+ */
+export async function diagnoseNetworkFailure(
+	result: Pick<ProofResult, 'verified' | 'error' | 'errorKind'>,
+	check: (opts: CheckAttestorOptions) => Promise<AttestorCheckResult>,
+	attestorUrl?: string,
+): Promise<ProofDiagnosis | undefined> {
+	if(
+		result.verified
+		|| result.errorKind !== undefined
+		|| !isNetworkError(result.error)
+	) {
+		return undefined
+	}
+
+	const attestor = await check(attestorUrl ? { attestorUrl } : {})
+	if(attestor.ok) {
+		return {
+			attestor,
+			likelyCause:
+				'The attestor works from this machine, so the target site likely '
+				+ 'blocks or drops the attestor\'s network (geo or IP restriction).',
+			next:
+				'If the browser attach mode is "builder", call `run_proof_via_pod`. '
+				+ 'Otherwise tell the developer and suggest asking the Reclaim team. '
+				+ 'Do not retry the same proof.',
+		}
+	}
+
+	return {
+		attestor,
+		likelyCause:
+			'The attestor check also failed, so this machine cannot reach the '
+			+ 'attestor (network, VPN, firewall, or proxy).',
+		next:
+			'Tell the developer. To see the connection details, suggest '
+			+ 'restarting the MCP server with `RECLAIM_AGENT_TRACE=1`. Do not '
+			+ 'retry the same proof.',
+	}
+}

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

@@ -18,9 +18,9 @@ export function proposeTool(resolveBackend: ResolveBackend): RegisteredTool {
 			name: 'propose_provider',
 			description:
 				'Drafts a provider from one authenticated captured request and '
-				+ 'keeps captured secrets server-side. Use `targets` for every value '
-				+ 'available in the same response; the result contains a `draftId` '
-				+ 'and secret-free recipe. Set `shortenNames: false` to preserve an '
+				+ 'keeps captured secrets server-side. Use `targets` for the data '
+				+ 'points the claim needs from that response; returns a `draftId` '
+				+ 'and a secret-free recipe. Set `shortenNames: false` to preserve an '
 				+ 'explicit parameter name, including a hidden `REQ_` or `URL_` '
 				+ 'prefix. For matching and naming guidance, call '
 				+ 'how_it_works({ topic: "draft" }) and topic `params`.',
@@ -63,6 +63,7 @@ export function proposeTool(resolveBackend: ResolveBackend): RegisteredTool {
 				},
 				['requestId', 'name'],
 			),
+			annotations: { openWorldHint: false, destructiveHint: false },
 		},
 		async(args) => {
 			const backend = resolveBackend(args)

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

@@ -5,6 +5,7 @@ import type {
 } from '@reclaimprotocol/client/openapi'
 import assert from 'node:assert'
 import type { JSONSchema } from 'zod/v4/core'
+import type { KeptScriptRef } from '../../../authoring/index.ts'
 import {
 	ALLOWED_REQUESTS_HINT,
 	COOKIE_ATTACHMENT_HINT,
@@ -232,13 +233,16 @@ interface PublishArgs {
 export function createVersionFromCaptureTool(
 	client: ReclaimClient,
 	attachRef?: { current?: AttachState },
+	kept?: KeptScriptRef,
 ): RegisteredTool {
 	return defineTool<PublishArgs>(
 		{
 			name: 'create_provider_version_from_capture',
 			description:
 				'Creates a new immutable provider version after `run_proof` succeeds. '
-				+ 'Pass exactly one `provider` or `providers` value returned by '
+				+ 'Publishes the navigation script kept by `test_user_script` as '
+				+ '`jsUserScripts` unless `jsUserScripts` is passed. Pass exactly '
+				+ 'one `provider` or `providers` value returned by '
 				+ '`propose_provider`; do not rebuild the recipe. The default is a '
 				+ 'patch bump, or use `bump` or an explicitly requested higher '
 				+ '`version`. The new version remains a draft until published or '
@@ -306,6 +310,8 @@ export function createVersionFromCaptureTool(
 					jsUserScripts: {
 						type: 'string',
 						description:
+							'Defaults to the script kept by `test_user_script` with ' +
+							'`keep: true`; pass it only to override. ' +
 							USER_SCRIPT_HINT +
 							' Stored as webSettings.jsUserScripts; the Builder ' +
 							'verification client runs it before every page load ' +
@@ -369,8 +375,10 @@ export function createVersionFromCaptureTool(
 				},
 				required: ['providerId', 'initialUrl'],
 			},
+			annotations: { openWorldHint: true, destructiveHint: false },
 		},
 		async(args) => {
+			const jsUserScripts = args.jsUserScripts ?? kept?.keptScript?.script
 			// Exactly one of `provider` / `providers` — normalize to an array.
 			const hasMany = Array.isArray(args.providers) && args.providers.length > 0
 			const hasOne = !!args.provider
@@ -396,7 +404,7 @@ export function createVersionFromCaptureTool(
 				notes: args.notes,
 				version: ver,
 				requiredContext: args.requiredContext,
-				jsUserScripts: args.jsUserScripts,
+				jsUserScripts,
 				allowedJsRequests: args.allowedJsRequests,
 				browserRequestActions: args.browserRequestActions,
 				interceptorOptions: args.interceptorOptions,
@@ -428,12 +436,12 @@ export function createVersionFromCaptureTool(
 			const attached = attachRef?.current
 			notes.push(...postPublishBrowserNotes(attached, {
 				initialUrl: args.initialUrl,
-				hasUserScript: !!args.jsUserScripts?.trim(),
+				hasUserScript: !!jsUserScripts?.trim(),
 				hasInterceptor: !!args.interceptorOptions,
 			}))
 
 			// Let the developer know how and when the script runs.
-			if(args.jsUserScripts?.trim()) {
+			if(jsUserScripts?.trim()) {
 				notes.push(
 					'jsUserScripts will run in the Builder verification client before ' +
 					'every page load (before navigating to initialUrl), matching ' +

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

@@ -13,13 +13,15 @@ export function replayTool(resolveBackend: ResolveBackend): RegisteredTool {
 		{
 			name: 'replay_request',
 			description:
-				'Validate the drafted recipe before proving — confirm its selectors '
-				+ 'extract the target value. Returns diagnostics; run before '
-				+ 'proving. Set `withoutSecrets: true` for the AUTH-BOUND check: it '
-				+ 're-issues the request with NO secrets/cookies (an anonymous '
-				+ 'visitor). If the values still extract (valid:true), the endpoint '
-				+ 'is PUBLIC and the proof would not bind to the user — reject it '
-				+ 'and find an auth-bound request instead.',
+				'Re-sends the drafted request from inside the attached authoring '
+				+ 'browser (not from this machine) and checks that its selectors '
+				+ 'extract the target data points. Captured secrets stay server-side '
+				+ 'and are not returned. Returns diagnostics. Run it before '
+				+ '`run_proof`. With `withoutSecrets: true`, sends the request with '
+				+ 'no cookies or auth headers, like an anonymous visitor. If the '
+				+ 'values still extract (`valid: true`), the endpoint is public and '
+				+ 'the proof would not bind to the user: choose an auth-bound '
+				+ 'request instead.',
 			inputSchema: objectSchema(
 				{
 					draftId: { type: 'string' },
@@ -27,6 +29,7 @@ export function replayTool(resolveBackend: ResolveBackend): RegisteredTool {
 				},
 				['draftId'],
 			),
+			annotations: { readOnlyHint: true, openWorldHint: true },
 		},
 		async(args) => {
 			const backend = resolveBackend(args)

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

@@ -12,10 +12,13 @@ export function sessionTools(
 			{
 				name: 'get_session',
 				description:
-					'Report the current attach state, the live captureIds, and the '
-					+ 'persisted browser config. Call it to check whether a browser is '
-					+ 'still attached before reattaching, or to recover a captureId.',
+					'Returns the current attach state, the live captureIds, the '
+					+ 'persisted browser config, and the navigation script kept by '
+					+ '`test_user_script`. Call it to check whether a browser is still '
+					+ 'attached before reattaching, or to recover a captureId or the '
+					+ 'kept script.',
 				inputSchema: { type: 'object', properties: {} },
+				annotations: { readOnlyHint: true, openWorldHint: false },
 			},
 			async() => ({
 				config: attachRef.config.read()?.browser_agent,
@@ -27,16 +30,19 @@ export function sessionTools(
 				orgId: attachRef.current?.orgId,
 				captures: [...captures.sessions.keys()],
 				activeTab: captures.activeTab,
+				keptUserScript: captures.keptScript?.script,
 			}),
 		),
 		defineTool<Record<string, never>>(
 			{
 				name: 'dispose_browser',
 				description:
-					'Stop captures, disconnect the current browser, and immediately '
-					+ 'delete a Builder-hosted Popcorn session. Custom CDP sessions '
-					+ 'are disconnected but never deleted by Reclaim.',
+					'Stops captures, disconnects the current browser, and deletes a '
+					+ 'Builder-hosted browser session at once. Clears the kept '
+					+ 'navigation script. Reclaim disconnects a custom CDP browser but '
+					+ 'never deletes it.',
 				inputSchema: { type: 'object', properties: {} },
+				annotations: { destructiveHint: true, openWorldHint: true },
 			},
 			async() => {
 				await resetAll(attachRef, captures)
@@ -47,9 +53,11 @@ export function sessionTools(
 			{
 				name: 'reset_session',
 				description:
-					'Stop all captures and clear capture state — drops every '
-					+ 'session\'s drafts and their in-memory secrets.',
+					'Stops all captures and clears capture state, dropping every '
+					+ 'draft and its in-memory secrets. Also disconnects the browser '
+					+ 'and clears the kept navigation script.',
 				inputSchema: { type: 'object', properties: {} },
+				annotations: { destructiveHint: true, openWorldHint: true },
 			},
 			async() => {
 				await resetAll(attachRef, captures)

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

@@ -12,13 +12,15 @@ import {
 	type AuthoringBackend,
 	authoringTools,
 	extendTool,
+	type KeptScriptRef,
 } from '../../../authoring/index.ts'
 import { runAttestorProof } from '../../../proof/attestor.ts'
+import { checkAttestor } from '../../../proof/check-attestor.ts'
 import { replayProviderInPage } from '../../../proof/page-replay.ts'
 import type { OprfMode, ReclaimProvider } from '../../../provider/schema.ts'
 import type { RegisteredTool } from '../../server.ts'
 import type { CaptureEntry, CaptureStore } from './capture.ts'
-import { shapeRichProofResult } from './proof.ts'
+import { diagnoseNetworkFailure, shapeRichProofResult } from './proof.ts'
 
 /**
  * OPRF mode this LOCAL (non-TEE) attestor can actually run. Recipes carry
@@ -54,13 +56,18 @@ function withLocalOprfMode(provider: ReclaimProvider): ReclaimProvider {
 /** The local backend for one capture: drive its tab over CDP, read its
  *  captured requests, prove via the in-process attestor, replay by re-fetching
  *  FROM INSIDE the tab (real cookies/session — see proof/page-replay.ts). */
-function localBackend(entry: CaptureEntry): AuthoringBackend {
+function localBackend(
+	entry: CaptureEntry,
+	kept: KeptScriptRef,
+	check: typeof checkAttestor,
+): AuthoringBackend {
 	const { tabClient, session, drafts } = entry
 	const sendCdp = (method: string, params?: Record<string, unknown>) => {
 		return tabClient.send(method, params ?? {})
 	}
 
 	return {
+		kept,
 		capture: session,
 		drafts,
 		sendCdp,
@@ -107,11 +114,15 @@ function localBackend(entry: CaptureEntry): AuthoringBackend {
 					...(opts?.attestorUrl ? { attestorUrl: opts.attestorUrl } : {}),
 				},
 			)
-			return shapeRichProofResult(result, {
+			const shaped = shapeRichProofResult(result, {
 				provider: draft.provider,
 				hasSecrets: Object.keys(draft.secrets).length > 0,
 				...(opts?.attestorUrl ? { attestorUrl: opts.attestorUrl } : {}),
 			})
+			const diagnosis = await diagnoseNetworkFailure(
+				result, check, opts?.attestorUrl,
+			)
+			return diagnosis ? { ...shaped, diagnosis } : shaped
 		},
 	}
 }
@@ -121,25 +132,26 @@ function localBackend(entry: CaptureEntry): AuthoringBackend {
  *  of this). */
 const RUN_PROOF_EXTRAS = {
 	description:
-		'Run a full zkTLS proof of the drafted recipe through the Reclaim '
-		+ 'attestor SDK. Use only after replay_request looks right — attestor '
-		+ 'calls are expensive. Writes the full claim to '
-		+ '~/.reclaim/claims/<timestamp>.json and returns identifier + '
-		+ 'extractedParameters + claimPath + a prettified `claim` (request '
-		+ 'dropped, byte arrays as base64). With RECLAIM_AGENT_TRACE=1, also '
-		+ 'writes a per-call diagnostic dump (input provider, sentParams, full '
-		+ 'attestor log stream, result) and returns it as `runLogPath`. '
-		+ '`attestorUrl` overrides the default only when the dev supplies a '
-		+ 'specific alternative — do NOT invent backup URLs. `ownerAddress` '
-		+ '(the credential to sign with) is REQUIRED — call resolve_owner_key '
-		+ 'first. errorKind="missing-owner-key" means that address has no known '
-		+ 'private key; re-run resolve_owner_key or issue/import a credential. '
-		+ 'NOTE: unlike replay_request (which re-issues from inside the live '
-		+ 'attached browser tab), the ATTESTOR calls the target from its OWN '
-		+ 'network/IP, separate from the browser\'s. A request that replayed '
-		+ 'fine can still fail here for geo/IP-bound content (country-locked '
-		+ "pages, IP-allowlisted APIs) — if that happens, it's a property of "
-		+ 'the site, not a bug in the draft.',
+		'Proves the drafted recipe with a full zkTLS proof through the attestor '
+		+ 'SDK. Call it after `replay_request` looks right; attestor calls are '
+		+ 'expensive. Call `resolve_owner_key` first and pass its address as '
+		+ '`ownerAddress`. Writes the full claim to '
+		+ '`~/.reclaim/claims/<timestamp>.json`. Returns `identifier`, '
+		+ '`extractedParameters`, `claimPath`, and a readable `claim` (request '
+		+ 'removed, byte arrays as base64). Set `RECLAIM_AGENT_TRACE=1` to also '
+		+ 'get `runLogPath`, a diagnostic dump with the attestor log stream. '
+		+ 'Set `attestorUrl` only if the developer supplied one; never invent '
+		+ 'backup URLs. If `errorKind` is `missing-owner-key`, the address has '
+		+ 'no known private key: run `resolve_owner_key` again, or issue or '
+		+ 'import a credential. Unlike `replay_request`, which re-sends from '
+		+ 'inside the attached browser tab, the attestor calls the target from '
+		+ 'its own network and IP. A request that replayed can still fail here '
+		+ 'for geo- or IP-bound content, such as country-locked pages or '
+		+ 'IP-allowlisted APIs. That is a property of the site, not a draft '
+		+ 'bug. After a network-like failure ("connection closed", '
+		+ '`ERROR_NETWORK_ERROR`, timeout), the result includes `diagnosis` '
+		+ 'with `attestor` (a `check_attestor` result), `likelyCause`, and '
+		+ '`next`. Follow `next`; do not retry the same proof.',
 	properties: {
 		ownerAddress: {
 			type: 'string',
@@ -163,7 +175,10 @@ const RUN_PROOF_EXTRAS = {
  *  takes `captureId`; `run_proof` also gets the credential-aware contract. The
  *  tools are authored plain in `../../../authoring`; this only wraps them with
  *  `extendTool` (handlers untouched — loose arg parse keeps `captureId`). */
-export function sharedAuthoringTools(captures: CaptureStore): RegisteredTool[] {
+export function sharedAuthoringTools(
+	captures: CaptureStore,
+	check: typeof checkAttestor = checkAttestor,
+): RegisteredTool[] {
 	const resolveBackend = (args: Record<string, unknown>): AuthoringBackend => {
 		const captureId = String(args.captureId)
 		const entry = captures.sessions.get(captureId)
@@ -174,7 +189,7 @@ export function sharedAuthoringTools(captures: CaptureStore): RegisteredTool[] {
 			)
 		}
 
-		return localBackend(entry)
+		return localBackend(entry, captures, check)
 	}
 
 	return authoringTools(resolveBackend).map((tool) => {

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

@@ -0,0 +1,84 @@
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { defineTool, type RegisteredTool } from '../../server.ts'
+
+interface StartIntegrationArgs {
+	goal: string
+	orgId?: string
+	providerIds?: string[]
+}
+
+/**
+ * Returns the plan a coding agent follows to add Reclaim verification to the
+ * developer's app, from sign-in to a tested Verify button. The plan lives in
+ * `skill/start-integration.md`; this tool fills in the inputs.
+ */
+export function startIntegrationTool(): RegisteredTool {
+	return defineTool<StartIntegrationArgs>(
+		{
+			name: 'start_integration',
+			description:
+				'Returns a step-by-step plan for adding Reclaim verification to the '
+				+ 'current codebase: sign in, set up the app (session route, callback, '
+				+ 'Verify button, local event proxy) in parallel with building or '
+				+ 'choosing the provider, then wire the provider and test. Call it '
+				+ 'first when a developer wants their users to prove something, and '
+				+ 'follow the plan to the end. Changes nothing itself.',
+			inputSchema: {
+				type: 'object',
+				required: ['goal'],
+				properties: {
+					goal: {
+						type: 'string',
+						minLength: 1,
+						maxLength: 300,
+						description:
+							'What the developer\'s users prove, for example, "they have '
+							+ 'a GitHub account with 100 followers".',
+					},
+					orgId: {
+						type: 'string',
+						format: 'uuid',
+						description: 'Organization to use. Omit to choose from the list.',
+					},
+					providerIds: {
+						type: 'array',
+						maxItems: 10,
+						items: { type: 'string' },
+						description:
+							'Existing provider IDs to use. Omit to build a new provider.',
+					},
+				},
+			},
+			annotations: { readOnlyHint: true, openWorldHint: false },
+		},
+		async(args) => renderStartIntegration(args),
+	)
+}
+
+/** Fill the plan template. Exported for tests. */
+export function renderStartIntegration(args: StartIntegrationArgs): string {
+	const providerIds = args.providerIds?.length
+		? args.providerIds.map((id) => `\`${id}\``).join(', ')
+		: undefined
+	const values: Record<string, string | undefined> = {
+		goal: args.goal,
+		orgId: args.orgId,
+		providerIds,
+	}
+	const template = readFileSync(
+		fileURLToPath(
+			new URL('../../../../skill/start-integration.md', import.meta.url),
+		),
+		'utf8',
+	)
+	return template
+		// Keep a conditional block only when its input was given (or not given).
+		.replace(
+			/<!-- (if|ifnot):(\w+) -->\n([\s\S]*?)<!-- endif -->\n/g,
+			(_, kind: string, name: string, body: string) => {
+				return (kind === 'if') === Boolean(values[name]) ? body : ''
+			},
+		)
+		.replace(/\{\{(\w+)\}\}/g, (_, name: string) => values[name] ?? '')
+}

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

@@ -25,18 +25,16 @@ export function authenticateTool(
 					+ 'get_me_providers; those need the separate old-devtools login, '
 					+ 'reclaim_authenticate. Check both with get_devtools_mode. '
 					: '')
-				+ 'Authorize the CLI / MCP to make authenticated API calls. Opens '
-				+ 'the '
-				+ 'browser to the builder sign-in page (standard OAuth 2.0 ' +
-				'authorization-code + PKCE with a localhost redirect) and waits for ' +
-				'the user to sign in and approve. On success the access token is ' +
-				'cached in ~/.reclaim/config.json and activated for this session.\n\n' +
-				'Call with no arguments. This bearer token authenticates ' +
-				'dashboard/org-management calls (for example, list_orgs, or ' +
-				'issuing an org secret). Programmatic verification calls use a ' +
-				'separate org secret ' +
-				'(rorg_…, set as RECLAIM_ORG_SECRET).',
+				+ 'Signs the developer in to Builder. Opens the Builder sign-in page '
+				+ 'in their browser (OAuth 2.0 authorization code with PKCE, '
+				+ 'redirecting to a localhost port this server opens) and waits for '
+				+ 'them to approve. Saves the access token in ~/.reclaim/config.json '
+				+ 'with mode 0600 and uses it for this session; the token is never '
+				+ 'returned. The token authorizes organization-management tools such '
+				+ 'as `list_orgs`. Programmatic verification tools use a separate '
+				+ 'organization key; see `issue_org_token`. Call with no arguments.',
 			inputSchema: { type: 'object', properties: {} },
+			annotations: { openWorldHint: true, idempotentHint: true },
 		},
 		async() => runOAuthLoopback(client),
 	)

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

@@ -3,6 +3,7 @@ import type { RegisteredTool } from '../../server.ts'
 import { authenticateTool } from './authenticate.ts'
 import { importTool } from './import.ts'
 import { issueTool } from './issue.ts'
+import { issueOrgTokenTool } from './issue-org-token.ts'
 import { resolveOwnerKeyTool } from './resolve-owner-key.ts'
 
 /**
@@ -27,6 +28,7 @@ export function buildLocalCredentialTools(): RegisteredTool[] {
 export function buildCredentialTools(client: ReclaimClient): RegisteredTool[] {
 	return [
 		authenticateTool(client),
+		issueOrgTokenTool(client),
 		...buildLocalCredentialTools(),
 	]
 }

package/src/mcp/tools/authenticate/builder-access.ts

@@ -35,6 +35,7 @@ export function buildBuilderOrganizationTools(
 						cursor: { type: 'string', maxLength: 500 },
 					},
 				},
+				annotations: { readOnlyHint: true, openWorldHint: true },
 			},
 			async({ cursor }) => {
 				const { data } = await client.call('ListOrgs', {

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

@@ -16,8 +16,20 @@
  */
 import { deriveFromPrivateKey } from '@reclaimprotocol/client'
 import assert from 'node:assert'
-import { existsSync, readFileSync, writeFileSync } from 'node:fs'
-import { isAbsolute, join } from 'node:path'
+import {
+	chmodSync,
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	writeFileSync,
+} from 'node:fs'
+import {
+	dirname,
+	isAbsolute,
+	join,
+	relative,
+	resolve
+} from 'node:path'
 import { privateKey, privateKeyFile } from '../../../consts.ts'
 import { findProjectRoot } from '../../../paths.ts'
 
@@ -124,7 +136,7 @@ export function resolveEthKey(
 }
 
 /** Append `entry` to the project `.gitignore` if not already present. */
-function ensureGitignored(projectDir: string, entry: string) {
+export function ensureGitignored(projectDir: string, entry: string) {
 	const path = join(projectDir, '.gitignore')
 	const current = existsSync(path) ? readFileSync(path, 'utf8') : ''
 	if(current.split('\n').some((l) => l.trim() === entry)) {
@@ -136,29 +148,47 @@ function ensureGitignored(projectDir: string, entry: string) {
 }
 
 /**
- * Persist a raw eth private key to the project `.env` as
- * `RECLAIM_PRIVATE_KEY=0x…` (upsert; mode 0600; `.env` added to `.gitignore`).
- * Used by `issue_credentials` (generate) and `import_credentials` (supplied
- * hex). Returns the derived address and the `.env` path.
+ * Set `name=value` in a dotenv file, replacing an existing line or appending
+ * one. Writes with mode 0600 and adds the file to the project `.gitignore`.
+ * `envFile` is relative to `projectDir`.
  */
-export function writeEthKey(
-	privateKeyHex: string,
-	projectDir = findProjectRoot(process.cwd()),
-): { path: string, address: string } {
-	const hex = normalizeEthHex(privateKeyHex)
-	const envPath = join(projectDir, ENV_FILE)
-	const line = `${ENV_VAR}=${hex}`
+export function upsertEnvVar(
+	projectDir: string,
+	envFile: string,
+	name: string,
+	value: string,
+): string {
+	const envPath = resolve(projectDir, envFile)
+	const line = `${name}=${value}`
 	const existing = existsSync(envPath) ? readFileSync(envPath, 'utf8') : ''
-	const re = new RegExp(`^\\s*${ENV_VAR}\\s*=.*$`, 'm')
+	const re = new RegExp(`^\\s*${name}\\s*=.*$`, 'm')
 	let next: string
 	if(re.test(existing)) {
-		next = existing.replace(re, line)
+		// A function replacer keeps `$` sequences in the value literal.
+		next = existing.replace(re, () => line)
 	} else {
 		const prefix = existing && !existing.endsWith('\n') ? '\n' : ''
 		next = existing + prefix + line + '\n'
 	}
 
+	mkdirSync(dirname(envPath), { recursive: true })
 	writeFileSync(envPath, next, { mode: 0o600 })
-	ensureGitignored(projectDir, ENV_FILE)
-	return { path: envPath, address: deriveFromPrivateKey(hex).address }
+	chmodSync(envPath, 0o600)
+	ensureGitignored(projectDir, relative(projectDir, envPath))
+	return envPath
+}
+
+/**
+ * Persist a raw eth private key to the project `.env` as
+ * `RECLAIM_PRIVATE_KEY=0x…` (upsert; mode 0600; `.env` added to `.gitignore`).
+ * Used by `issue_credentials` (generate) and `import_credentials` (supplied
+ * hex). Returns the derived address and the `.env` path.
+ */
+export function writeEthKey(
+	privateKeyHex: string,
+	projectDir = findProjectRoot(process.cwd()),
+): { path: string, address: string } {
+	const hex = normalizeEthHex(privateKeyHex)
+	const path = upsertEnvVar(projectDir, ENV_FILE, ENV_VAR, hex)
+	return { path, address: deriveFromPrivateKey(hex).address }
 }