@reclaimprotocol/agent 0.1.1-dev.1 → 0.1.2

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

@@ -1,33 +1,160 @@
 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). ' +
-				'For PRIVATE verifications the version goes live immediately; ' +
-				'for PUBLIC ones call submit_provider_version_for_review afterwards.',
+				'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 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: {
 				type: 'object',
 				properties: {
@@ -35,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',
@@ -131,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/agent/replay.ts

@@ -16,11 +16,6 @@ export function replayTool(secrets: SecretStore): RegisteredTool {
 			inputSchema: {
 				type: 'object',
 				properties: {
-					// `type: 'object'` is required so MCP clients (the LLM)
-					// serialize the value as an object, not a JSON-stringified
-					// string. `properties: {}` is required so zod-from-json-schema
-					// compiles to a passthrough instead of strict-strip — leaving
-					// it off makes the server receive `{}`.
 					provider: { type: 'object', properties: {} },
 					secretParamsRef: { type: 'string' },
 				},

package/src/mcp/tools/{credentials → authenticate}/authenticate.ts

@@ -1,7 +1,7 @@
 import type { ReclaimClient } from '@reclaimprotocol/client'
 import type {
-	CredentialAttachSession as Session
-} from '../../../types/openapi.ts'
+	CredentialAttachSession
+} from '@reclaimprotocol/client/openapi'
 import { defineTool, type RegisteredTool } from '../../server.ts'
 import { writeSession } from './session-cache.ts'
 
@@ -21,10 +21,9 @@ export function authenticateTool(client: ReclaimClient): RegisteredTool {
 				'Returns `LINKED` with a 2-day bearer token when confirmed, ' +
 				'`PENDING` if not yet, or `EXPIRED` if too long has passed.\n\n' +
 				'The token is cached in ~/.reclaim/config.json automatically.\n\n' +
-				'To then link a credential to an org (needed only to use it ' +
-				'for verification in production), use the token with the ' +
-				'generated tools: `list_orgs` → `link_credential` with the ' +
-				"credential's `address` and the target `orgId`.",
+				'This bearer token authenticates dashboard/org-management calls ' +
+				'(e.g. list_orgs, issuing an org secret). Programmatic verification ' +
+				'calls use a separate org secret (rorg_…, set as RECLAIM_ORG_SECRET).',
 			inputSchema: {
 				type: 'object',
 				properties: {
@@ -68,7 +67,7 @@ async function checkSession(
 	client: ReclaimClient,
 	code: string,
 ): Promise<unknown> {
-	let session: Session
+	let session: CredentialAttachSession
 	try {
 		const sessionResult = (await client.call('GetAttachSession', {
 			params: { code }
@@ -93,7 +92,9 @@ async function checkSession(
 		if(token) {
 			writeSession({
 				token,
-				expiresAt: new Date(Date.now() + 2 * 24 * 60 * 60 * 1000).toISOString(),
+				expiresAt: new Date(
+					Date.now() + 2 * 24 * 60 * 60 * 1000
+				).toISOString(),
 			})
 			client.setToken(token)
 			return {

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

@@ -0,0 +1,32 @@
+import type { ReclaimClient } from '@reclaimprotocol/client'
+import type { RegisteredTool } from '../../server.ts'
+import { authenticateTool } from './authenticate.ts'
+import { importTool } from './import.ts'
+import { issueTool } from './issue.ts'
+import { resolveOwnerKeyTool } from './resolve-owner-key.ts'
+
+/**
+ * Local-only key tools — no backend client needed. These manage the eth
+ * proof-owner key entirely on disk (as a secp256k1 PEM) or via env: generate,
+ * import, and resolve which key to sign proofs with. No `~/.reclaim` caching;
+ * useful in BOTH builder and OLD-devtools mode.
+ */
+export function buildLocalCredentialTools(): RegisteredTool[] {
+	return [
+		resolveOwnerKeyTool(),
+		issueTool(),
+		importTool(),
+	]
+}
+
+/**
+ * Full builder-mode credential set: the local key tools plus the backend
+ * `reclaim_authenticate` device-code flow. Old mode does NOT use the
+ * authenticate tool — it has its own.
+ */
+export function buildCredentialTools(client: ReclaimClient): RegisteredTool[] {
+	return [
+		authenticateTool(client),
+		...buildLocalCredentialTools(),
+	]
+}

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

@@ -0,0 +1,59 @@
+/**
+ * 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. 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 hex is loaded via the client's `loadDecryptionKey` and passed straight
+ * through as `ReclaimConfig.credential` / to `decryptCallback`.
+ */
+import {
+	type DecryptionKey,
+	loadDecryptionKey,
+} from '@reclaimprotocol/client'
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { findProjectRoot } from '../../../paths.ts'
+
+/** Default eth decrypt-key filename the agent looks for in the project root. */
+const DEFAULT_DECRYPT_KEY_FILE = 'reclaim-decrypt.key'
+
+/**
+ * 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).
+ */
+function resolveDecryptKeyInput(
+	projectDir = findProjectRoot(process.cwd()),
+): string | undefined {
+	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 no key is
+ * configured (the consumer then handles only plaintext deliveries).
+ */
+export async function resolveDecryptionKey(
+	projectDir = findProjectRoot(process.cwd()),
+): Promise<DecryptionKey | undefined> {
+	const input = resolveDecryptKeyInput(projectDir)
+	if(input === undefined) {
+		return undefined
+	}
+
+	return loadDecryptionKey(input)
+}

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

@@ -0,0 +1,162 @@
+/**
+ * Eth proof-owner key resolution — the raw secp256k1 private key passed to
+ * attestor-core when the agent creates a local claim. It's a plain 0x-hex
+ * Ethereum private key (no PEM), resolved from, in order:
+ *
+ *   1. `process.env.RECLAIM_PRIVATE_KEY` — a 0x-hex 32-byte scalar.
+ *   2. A `.env` file in the project root — its `RECLAIM_PRIVATE_KEY=0x…` line.
+ *   3. A key file holding the raw 0x-hex scalar, at `RECLAIM_PRIVATE_KEY_FILE`
+ *      (absolute or project-relative).
+ *   4. Absent — the caller offers to generate one or asks the dev for a key.
+ *
+ * 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 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'
+/** The dotenv file the agent reads from / writes the key to. */
+export const ENV_FILE = '.env'
+
+/** Where the resolved eth key came from. */
+export type EthKeySource = 'env' | 'dotenv' | 'file'
+
+export type ResolvedEthKey = {
+	/** Raw 0x-hex 32-byte scalar. */
+	privateKey: string
+	/** Lowercase eth address derived from the scalar. */
+	address: string
+	source: EthKeySource
+	/** Absolute path the key was read from (for `dotenv` / `file` sources). */
+	path?: string
+}
+
+/** Validate + normalize a raw Ethereum private key to lowercase 0x-hex. */
+export function normalizeEthHex(value: string): string {
+	const v = value.trim().replace(/^['"]|['"]$/g, '')
+	if(!/^(0x)?[0-9a-fA-F]{64}$/.test(v)) {
+		throw new Error(
+			'not a valid Ethereum private key (expected a 32-byte / 64-hex scalar)',
+		)
+	}
+
+	return '0x' + v.replace(/^0x/, '').toLowerCase()
+}
+
+/** Read `RECLAIM_PRIVATE_KEY` from a dotenv file (simple KEY=VALUE parse). */
+function readDotenvKey(path: string): string | undefined {
+	if(!existsSync(path)) {
+		return undefined
+	}
+
+	for(const line of readFileSync(path, 'utf8').split('\n')) {
+		const m = line.match(/^\s*RECLAIM_PRIVATE_KEY\s*=\s*(.+?)\s*$/)
+		if(m) {
+			return m[1]
+		}
+	}
+
+	return undefined
+}
+
+/** The explicit raw-hex key-file path, if `RECLAIM_PRIVATE_KEY_FILE` is set. */
+function ethKeyFilePath(
+	projectDir = findProjectRoot(process.cwd()),
+): string | undefined {
+	const p = privateKeyFile()
+	if(!p) {
+		return undefined
+	}
+
+	return isAbsolute(p) ? p : join(projectDir, p)
+}
+
+function resolved(
+	privateKey: string,
+	source: EthKeySource,
+	path?: string,
+): ResolvedEthKey {
+	return {
+		privateKey,
+		address: deriveFromPrivateKey(privateKey).address,
+		source,
+		...(path ? { path } : {}),
+	}
+}
+
+/**
+ * Resolve the eth proof-owner key without prompting. Returns `undefined` when
+ * no key is configured anywhere — the caller decides whether to generate or
+ * ask for one (see `resolve_owner_key`).
+ */
+export function resolveEthKey(
+	projectDir = findProjectRoot(process.cwd()),
+): ResolvedEthKey | undefined {
+	const env = privateKey()
+	if(env?.trim()) {
+		return resolved(normalizeEthHex(env), 'env')
+	}
+
+	const envPath = join(projectDir, ENV_FILE)
+	const fromDotenv = readDotenvKey(envPath)
+	if(fromDotenv) {
+		return resolved(normalizeEthHex(fromDotenv), 'dotenv', envPath)
+	}
+
+	const keyFile = ethKeyFilePath(projectDir)
+	if(keyFile && existsSync(keyFile)) {
+		return resolved(
+			normalizeEthHex(readFileSync(keyFile, 'utf8')),
+			'file',
+			keyFile,
+		)
+	}
+
+	return undefined
+}
+
+/** Append `entry` to the project `.gitignore` if not already present. */
+function ensureGitignored(projectDir: string, entry: string): void {
+	const path = join(projectDir, '.gitignore')
+	const current = existsSync(path) ? readFileSync(path, 'utf8') : ''
+	if(current.split('\n').some((l) => l.trim() === entry)) {
+		return
+	}
+
+	const prefix = current && !current.endsWith('\n') ? '\n' : ''
+	writeFileSync(path, current + prefix + entry + '\n')
+}
+
+/**
+ * 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 envPath = join(projectDir, ENV_FILE)
+	const line = `${ENV_VAR}=${hex}`
+	const existing = existsSync(envPath) ? readFileSync(envPath, 'utf8') : ''
+	const re = new RegExp(`^\\s*${ENV_VAR}\\s*=.*$`, 'm')
+	let next: string
+	if(re.test(existing)) {
+		next = existing.replace(re, line)
+	} else {
+		const prefix = existing && !existing.endsWith('\n') ? '\n' : ''
+		next = existing + prefix + line + '\n'
+	}
+
+	writeFileSync(envPath, next, { mode: 0o600 })
+	ensureGitignored(projectDir, ENV_FILE)
+	return { path: envPath, address: deriveFromPrivateKey(hex).address }
+}