@reclaimprotocol/agent 0.1.36 → 0.1.37

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

@@ -3,15 +3,53 @@ import { spawn } from 'node:child_process'
 import { createServer } from 'node:http'
 import * as oauth from 'openid-client'
 import { defineTool, type RegisteredTool } from '../../server.ts'
-import { writeSession } from './session-cache.ts'
+import {
+	authBaseFor,
+	oauthRequestOptions,
+	SCOPE,
+	sessionFromTokens,
+} from './oauth-config.ts'
+import { readSession, writeSession } from './session-cache.ts'
 
-const SCOPE = 'openid profile email'
+type AuthToolName = 'reclaim_authenticate' | 'authenticate_builder'
+
+/** How long a sign-in link stays valid (the loopback listener's lifetime). */
 const CALLBACK_TIMEOUT_MS = 5 * 60 * 1000
+/** Longest single `wait_for_sign_in` call; stays under common 60 s tool
+ *  timeouts. */
+const MAX_WAIT_SECONDS = 55
+const DEFAULT_WAIT_SECONDS = 50
+/** How long a browser launcher gets to fail before it counts as opened. */
+const BROWSER_GRACE_MS = 1500
+
+/** Whether the browser launcher started, and why not when it didn't. */
+export type BrowserLaunch = { opened: boolean, reason?: string }
+
+export type PendingSignIn = {
+	status: 'PENDING'
+	signInUrl: string
+	browserOpened: boolean
+	reason?: string
+	/** ISO timestamp when `signInUrl` stops working. */
+	expiresAt: string
+}
+
+export type SignInOutcome =
+	| { status: 'AUTHENTICATED', expiresAt: string }
+	| { status: 'FAILED', reason: string }
+
+type SignInFlow = {
+	started: Promise<PendingSignIn>
+	completion: Promise<SignInOutcome>
+	outcome?: SignInOutcome
+}
+
+/** The sign-in in progress (or last finished) for each Builder client. */
+const FLOWS = new WeakMap<ReclaimClient, SignInFlow>()
 
 export function authenticateTool(
 	client: ReclaimClient,
-	name: 'reclaim_authenticate' | 'authenticate_builder' =
-		'reclaim_authenticate',
+	name: AuthToolName = 'reclaim_authenticate',
 ): RegisteredTool {
 	return defineTool<Record<string, never>>(
 		{
@@ -25,37 +63,121 @@ export function authenticateTool(
 					+ 'get_me_providers; those need the separate old-devtools login, '
 					+ 'reclaim_authenticate. Check both with get_devtools_mode. '
 					: '')
-				+ '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.',
+				+ 'Starts signing the developer in to Builder (OAuth 2.0 '
+				+ 'authorization code with PKCE, redirecting to a localhost port '
+				+ 'this server opens) and returns at once without waiting for them: '
+				+ '`{ status: "PENDING", signInUrl, browserOpened, reason?, '
+				+ 'expiresAt }`. It tries to open signInUrl in their browser; '
+				+ '`browserOpened` says whether that worked and `reason` why not. '
+				+ 'Always give the developer signInUrl and ask them to open it in a '
+				+ 'browser on this machine. When browserOpened is false, end your '
+				+ 'turn after sharing it — nothing happens until they open it. Then '
+				+ 'call `wait_for_sign_in` to confirm. The link expires after 5 '
+				+ 'minutes; calling again while one is pending returns the same '
+				+ 'link. On success the token is saved in ~/.reclaim/config.json '
+				+ 'with mode 0600, refreshed automatically, and never returned. It '
+				+ '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),
+		async() => startSignIn(client),
 	)
 }
 
-const _customFetchForOauth: oauth.CustomFetch = async(
-	url: string,
-	options: oauth.CustomFetchOptions,
-) => {
-	const res = await fetch(url, options as RequestInit)
-	if(
-		options.method === 'POST' && res.status === 200 &&
-		new URL(url).pathname.endsWith('/oauth2/register')
-	) {
-		return new Response(await res.text(), {
-			status: 201,
-			headers: res.headers,
-		})
+export function waitForSignInTool(
+	client: ReclaimClient,
+	authToolName: AuthToolName = 'reclaim_authenticate',
+): RegisteredTool {
+	return defineTool<{ timeoutSeconds?: number }>(
+		{
+			name: 'wait_for_sign_in',
+			description:
+				`Waits for the Builder sign-in started by \`${authToolName}\` to `
+				+ `finish, for up to timeoutSeconds (default ${DEFAULT_WAIT_SECONDS}`
+				+ `, max ${MAX_WAIT_SECONDS}). Returns status AUTHENTICATED (with `
+				+ 'expiresAt); PENDING (not finished yet: repeats signInUrl — call '
+				+ 'again, or remind the developer to open the link); FAILED (with '
+				+ `reason: call \`${authToolName}\` for a new link); or NOT_STARTED `
+				+ '(no sign-in in progress and no valid session: call '
+				+ `\`${authToolName}\`).`,
+			inputSchema: {
+				type: 'object',
+				properties: {
+					timeoutSeconds: {
+						type: 'integer',
+						minimum: 0,
+						maximum: MAX_WAIT_SECONDS,
+					},
+				},
+			},
+			annotations: { readOnlyHint: true, openWorldHint: false },
+		},
+		async({ timeoutSeconds }) => waitForSignIn(
+			client, (timeoutSeconds ?? DEFAULT_WAIT_SECONDS) * 1000,
+		),
+	)
+}
+
+/**
+ * Start a sign-in and return its link without waiting for the developer. A
+ * sign-in already pending for `client` is returned as is rather than
+ * replaced. The flow finishes in the background: the loopback server keeps
+ * listening until the browser redirects back or the link expires, and on
+ * success caches the session and activates it on `client`.
+ */
+export async function startSignIn(
+	client: ReclaimClient,
+	// Overridable only so tests can intercept the authorize URL instead of
+	// actually spawning a browser; every real caller uses the default.
+	openBrowserFn: (url: string) => Promise<BrowserLaunch> = openBrowser,
+): Promise<PendingSignIn> {
+	const existing = FLOWS.get(client)
+	if(existing && !existing.outcome) {
+		return existing.started
+	}
+
+	const begun = beginSignIn(client, openBrowserFn)
+	const flow: SignInFlow = {
+		started: begun.then(({ pending }) => pending),
+		completion: begun.then(
+			({ completion }) => completion,
+			(err) => ({ status: 'FAILED' as const, reason: failureReason(err) }),
+		),
+	}
+	void flow.completion.then((outcome) => {
+		flow.outcome = outcome
+	})
+	FLOWS.set(client, flow)
+	return flow.started
+}
+
+/**
+ * Wait up to `timeoutMs` for `client`'s sign-in to finish. Reports PENDING
+ * (with the link again) if it's still open when the wait runs out.
+ */
+export async function waitForSignIn(
+	client: ReclaimClient,
+	timeoutMs: number,
+): Promise<PendingSignIn | SignInOutcome | { status: 'NOT_STARTED' }> {
+	const flow = FLOWS.get(client)
+	if(!flow) {
+		const session = readSession()
+		return session
+			? { status: 'AUTHENTICATED', expiresAt: session.expiresAt }
+			: { status: 'NOT_STARTED' }
 	}
 
-	return res
+	let timer: ReturnType<typeof setTimeout> | undefined
+	const outcome = await Promise.race([
+		flow.completion,
+		new Promise<undefined>((resolve) => {
+			timer = setTimeout(() => resolve(undefined), timeoutMs)
+		}),
+	])
+	clearTimeout(timer)
+	return outcome ?? flow.started
 }
 
 /**
@@ -67,36 +189,24 @@ const _customFetchForOauth: oauth.CustomFetch = async(
  * validation (including a denied/failed login surfacing as
  * `AuthorizationResponseError`) — this function only wires those calls
  * together and owns the loopback server (no library spins that up for you).
+ * Resolves once the link is ready; `completion` settles when the flow ends
+ * and never rejects.
  */
-export async function runOAuthLoopback(
+async function beginSignIn(
 	client: ReclaimClient,
-	// Overridable only so tests can intercept the authorize URL instead of
-	// actually spawning a browser; every real caller uses the default.
-	openBrowserFn: (url: string) => void = openBrowser,
-): Promise<unknown> {
-	const authBase = `${client.baseUrl}/auth`
+	openBrowserFn: (url: string) => Promise<BrowserLaunch>,
+) {
+	const authBase = authBaseFor(client.baseUrl)
 	const codeVerifier = oauth.randomPKCECodeVerifier()
 	const codeChallenge = await oauth.calculatePKCECodeChallenge(codeVerifier)
 	const state = oauth.randomState()
 
-	// openid-client/oauth4webapi refuse any non-HTTPS issuer by default
-	// ("only requests to HTTPS are allowed"). Better Auth's own dev default
-	// (`canonicalOrigin()`, packages/app/src/consts.ts) is plain
-	// `http://localhost:4001` — the server side has no HTTPS requirement at
-	// all — so a local `RECLAIM_API_URL=http://localhost:...` would otherwise
-	// always fail here. Loosen it ONLY for loopback hosts, matching what the
-	// server already trusts (`authTrustedOrigins()` defaults to
-	// localhost:4000/4001 outside production); a non-loopback http:// origin
-	// still gets the strict check.
-	const isLoopbackAuthBase =
-		['localhost', '127.0.0.1', '[::1]'].includes(new URL(authBase).hostname)
-
 	// Bind the callback port first: the client is registered for this exact
 	// loopback redirect.
 	const callback = await listenForCallback()
-	let tokens: oauth.TokenEndpointResponse
+	let config: oauth.Configuration
 	try {
-		const config = await oauth.dynamicClientRegistration(
+		config = await oauth.dynamicClientRegistration(
 			new URL(authBase),
 			{
 				client_name: 'Reclaim CLI',
@@ -107,90 +217,83 @@ export async function runOAuthLoopback(
 				scope: SCOPE,
 			},
 			undefined,
-			{
-				// Better Auth exposes its metadata at the RFC 8414 well-known path
-				// (`.well-known/oauth-authorization-server`), not the OIDC one.
-				algorithm: 'oauth2',
-				// RFC 7591 §3.2.1 requires 201 Created on a successful registration;
-				// openid-client enforces that strictly. Better Auth's
-				// `oauth-provider` plugin doesn't conform — confirmed live against
-				// the real server: `POST .../oauth2/register` returns 200 with an
-				// otherwise well-formed body, which openid-client rejects outright
-				// ("unexpected HTTP response status code") before ever looking at
-				// it. `customFetch` set here persists onto the returned
-				// `Configuration` for ALL its future calls too (token exchange
-				// included, which correctly returns 200) — so the URL itself, not
-				// just method+status, must gate the rewrite, or a genuine 200 from
-				// the token endpoint gets corrupted into a 201 and
-				// `authorizationCodeGrant` fails instead (confirmed by hitting
-				// exactly that when this only checked method === 'POST').
-				[oauth.customFetch]: _customFetchForOauth,
-				// Applies to the `Configuration` this call returns, so the later
-				// `buildAuthorizationUrl`/`authorizationCodeGrant` calls below (which
-				// reuse that same `config`) stop enforcing HTTPS too — no separate
-				// opt-in needed for them.
-				...(isLoopbackAuthBase
-					? { execute: [oauth.allowInsecureRequests] }
-					: {}),
-			},
+			oauthRequestOptions(authBase),
 		)
-		openBrowserFn(
-			oauth.buildAuthorizationUrl(config, {
-				redirect_uri: callback.redirectUri,
-				scope: SCOPE,
-				state,
-				code_challenge: codeChallenge,
-				code_challenge_method: 'S256',
-			}).href,
-		)
-		const callbackUrl = await callback.url
-		tokens = await oauth.authorizationCodeGrant(config, callbackUrl, {
-			pkceCodeVerifier: codeVerifier,
-			expectedState: state,
-		})
 	} catch(err) {
-		// A denied or failed authorization surfaces as this error class with
-		// the raw callback params on `.cause` — reword it like the previous
-		// hand-rolled check did (RFC 6749 §4.1.2.1's error/error_description).
-		if(err instanceof oauth.AuthorizationResponseError) {
-			throw new Error(
-				err.cause.get('error_description')
-				?? err.cause.get('error')
-				?? 'Sign-in failed or was cancelled.',
-			)
-		}
-
-		throw err
-	} finally {
 		callback.close()
+		throw err
 	}
 
-	const expiresAt = new Date(
-		Date.now() + (tokens.expires_in ?? 3600) * 1000,
-	).toISOString()
-	writeSession({ token: tokens.access_token, expiresAt })
-	client.setToken(tokens.access_token)
+	const signInUrl = oauth.buildAuthorizationUrl(config, {
+		redirect_uri: callback.redirectUri,
+		scope: SCOPE,
+		state,
+		code_challenge: codeChallenge,
+		code_challenge_method: 'S256',
+	}).href
+	const completion = finish()
+	const launch = await openBrowserFn(signInUrl).catch((err) => ({
+		opened: false,
+		reason: failureReason(err),
+	}))
+	const pending: PendingSignIn = {
+		status: 'PENDING',
+		signInUrl,
+		browserOpened: launch.opened,
+		...(launch.reason ? { reason: launch.reason } : {}),
+		expiresAt: callback.expiresAt,
+	}
+	return { pending, completion }
 
-	return {
-		status: 'AUTHENTICATED',
-		note: 'Access token cached in ~/.reclaim/config.json and active now.',
-		expiresAt,
+	async function finish(): Promise<SignInOutcome> {
+		try {
+			const tokens = await oauth.authorizationCodeGrant(
+				config, await callback.url,
+				{ pkceCodeVerifier: codeVerifier, expectedState: state },
+			)
+			const session = sessionFromTokens(tokens, {
+				clientId: config.clientMetadata().client_id,
+				authBase,
+			})
+			writeSession(session)
+			client.setToken(session.token)
+			return { status: 'AUTHENTICATED', expiresAt: session.expiresAt }
+		} catch(err) {
+			return { status: 'FAILED', reason: failureReason(err) }
+		} finally {
+			callback.close()
+		}
 	}
 }
 
+function failureReason(err: unknown) {
+	// A denied or failed authorization surfaces as this error class with the
+	// raw callback params on `.cause` (RFC 6749 §4.1.2.1's
+	// error/error_description).
+	if(err instanceof oauth.AuthorizationResponseError) {
+		return err.cause.get('error_description')
+			?? err.cause.get('error')
+			?? 'Sign-in failed or was cancelled.'
+	}
+
+	return err instanceof Error ? err.message : String(err)
+}
+
 /**
  * Bind an ephemeral loopback port and start listening for the provider's
  * redirect. Resolves as soon as the port is known — the `url` promise settles
- * later, when the browser hits `/callback` — so the caller can register a
- * client for this exact redirect URI before sending the user off to authorize.
- * The ephemeral port lets any number of CLIs run concurrently. Hands back the
- * RAW callback URL rather than picking `code`/`state` apart itself —
- * `oauth.authorizationCodeGrant` does that validation. Defined below its
- * caller per repo convention.
+ * later, when the browser hits `/callback`, or rejects when the link expires —
+ * so the caller can register a client for this exact redirect URI before
+ * sending the user off to authorize. The ephemeral port lets any number of
+ * CLIs run concurrently. Hands back the RAW callback URL rather than picking
+ * `code`/`state` apart itself — `oauth.authorizationCodeGrant` does that
+ * validation. The server and timer are unref'd: a pending sign-in alone
+ * doesn't keep the process alive.
  */
 async function listenForCallback(): Promise<{
 	redirectUri: string
 	url: Promise<URL>
+	expiresAt: string
 	close: () => void
 }> {
 	let resolveUrl: (url: URL) => void
@@ -201,10 +304,14 @@ async function listenForCallback(): Promise<{
 	})
 
 	const server = createServer()
+	const expiresAt = new Date(Date.now() + CALLBACK_TIMEOUT_MS).toISOString()
 	const timer = setTimeout(
-		() => rejectUrl(new Error('Timed out waiting for sign-in (5 min).')),
+		() => rejectUrl(new Error(
+			'Sign-in link expired (5 min). Call the sign-in tool again for a new '
+			+ 'link.',
+		)),
 		CALLBACK_TIMEOUT_MS,
-	)
+	).unref()
 
 	const port = await new Promise<number>((resolve, reject) => {
 		server.once('error', reject)
@@ -220,11 +327,11 @@ async function listenForCallback(): Promise<{
 	}).catch((err) => {
 		// Bind failed before `close()` (returned below) is ever reachable —
 		// clear the timer ourselves, or it fires 5 minutes later and rejects
-		// the now-unobserved `url` promise (unhandled rejection) while keeping
-		// the process alive in the meantime.
+		// the now-unobserved `url` promise (unhandled rejection).
 		clearTimeout(timer)
 		throw err
 	})
+	server.unref()
 	// Past bind, a socket error fails the pending wait rather than throwing.
 	server.on('error', (err) => rejectUrl(err))
 
@@ -248,6 +355,7 @@ async function listenForCallback(): Promise<{
 	return {
 		redirectUri,
 		url,
+		expiresAt,
 		close: () => {
 			clearTimeout(timer)
 			server.close()
@@ -255,18 +363,55 @@ async function listenForCallback(): Promise<{
 	}
 }
 
-function openBrowser(url: string) {
-	const cmd = process.platform === 'darwin'
-		? 'open'
-		: process.platform === 'win32'
-			? 'cmd'
-			: 'xdg-open'
-	const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url]
-	try {
-		spawn(cmd, args, { stdio: 'ignore', detached: true }).unref()
-	} catch{
-		// Non-fatal: the URL is still logged for the user to open manually.
+/**
+ * Try to open `url` in the system browser. Never writes to stdout (it carries
+ * MCP JSON-RPC); the URL goes to stderr for a developer watching the logs.
+ * On Linux without a display server it doesn't try. Otherwise a launcher
+ * that errors or exits non-zero within a short grace window counts as not
+ * opened.
+ */
+export async function openBrowser(
+	url: string,
+	{ env = process.env, platform = process.platform } = {},
+): Promise<BrowserLaunch> {
+	process.stderr.write(`\nOpen this URL to sign in:\n${url}\n\n`)
+	const hasDisplay = platform === 'darwin' || platform === 'win32'
+		|| !!env.WAYLAND_DISPLAY || !!env.DISPLAY
+	if(!hasDisplay) {
+		return {
+			opened: false,
+			reason: 'no display (WAYLAND_DISPLAY/DISPLAY not set)',
+		}
 	}
 
-	process.stderr.write(`\nOpen this URL to sign in:\n${url}\n\n`)
+	const cmd = platform === 'darwin'
+		? 'open'
+		: platform === 'win32' ? 'cmd' : 'xdg-open'
+	const args = platform === 'win32' ? ['/c', 'start', '', url] : [url]
+	return new Promise((resolve) => {
+		const timer = setTimeout(() => resolve({ opened: true }), BROWSER_GRACE_MS)
+		try {
+			const child = spawn(cmd, args, { stdio: 'ignore', detached: true, env })
+			child.once('error', (err) => done({
+				opened: false,
+				reason: `${cmd} failed: ${err.message}`,
+			}))
+			child.once('exit', (code, signal) => done(
+				code === 0
+					? { opened: true }
+					: {
+						opened: false,
+						reason: `${cmd} exited with ${code ?? signal}`,
+					},
+			))
+			child.unref()
+		} catch(err) {
+			done({ opened: false, reason: `${cmd} failed: ${failureReason(err)}` })
+		}
+
+		function done(launch: BrowserLaunch) {
+			clearTimeout(timer)
+			resolve(launch)
+		}
+	})
 }

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

@@ -1,8 +1,9 @@
 import type { ReclaimClient } from '@reclaimprotocol/client/api'
 import type { RegisteredTool } from '../../server.ts'
-import { authenticateTool } from './authenticate.ts'
+import { authenticateTool, waitForSignInTool } from './authenticate.ts'
 import { importTool } from './import.ts'
 import { issueTool } from './issue.ts'
+import { issueOrgKeypairTool } from './issue-org-keypair.ts'
 import { issueOrgTokenTool } from './issue-org-token.ts'
 import { resolveOwnerKeyTool } from './resolve-owner-key.ts'
 
@@ -22,13 +23,15 @@ export function buildLocalCredentialTools(): RegisteredTool[] {
 
 /**
  * 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.
+ * `reclaim_authenticate` sign-in flow and its `wait_for_sign_in` companion.
+ * Old mode does NOT use the authenticate tool — it has its own.
  */
 export function buildCredentialTools(client: ReclaimClient): RegisteredTool[] {
 	return [
 		authenticateTool(client),
+		waitForSignInTool(client),
 		issueOrgTokenTool(client),
+		issueOrgKeypairTool(client),
 		...buildLocalCredentialTools(),
 	]
 }

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

@@ -1,6 +1,6 @@
 import type { ReclaimClient } from '@reclaimprotocol/client/api'
 import { defineTool, type RegisteredTool } from '../../server.ts'
-import { authenticateTool } from './authenticate.ts'
+import { authenticateTool, waitForSignInTool } from './authenticate.ts'
 
 /** Legacy-devtools mode needs a distinct Builder login for its two
  * Builder-exclusive features: allocating quota-accounted Popcorn sessions
@@ -10,7 +10,10 @@ import { authenticateTool } from './authenticate.ts'
 export function buildBuilderAuthenticationTools(
 	client: ReclaimClient,
 ): RegisteredTool[] {
-	return [authenticateTool(client, 'authenticate_builder')]
+	return [
+		authenticateTool(client, 'authenticate_builder'),
+		waitForSignInTool(client, 'authenticate_builder'),
+	]
 }
 
 /** Legacy-devtools mode lacks generated Builder API tools, so it needs this

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

@@ -7,14 +7,15 @@
  *   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.
+ *   4. Absent — `resolveOrCreateEthKey` generates a local test key; nobody is
+ *      asked.
  *
  * 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 { deriveFromPrivateKey, generateKeypair } from '@reclaimprotocol/client'
 import assert from 'node:assert'
 import {
 	chmodSync,
@@ -37,8 +38,18 @@ 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'
+/** Where the resolved eth key came from. `generated`: created just now
+ *  because none existed. */
+export type EthKeySource = 'env' | 'dotenv' | 'file' | 'generated'
+
+/** Tells the agent to inform the developer once, after the fact. */
+export const GENERATED_KEY_NOTE =
+	'No proof signing key existed, so a local test signing key was created and '
+	+ 'saved to the project .env as RECLAIM_PRIVATE_KEY (mode 0600, '
+	+ 'gitignored). Tell the developer once, in one sentence, that you created '
+	+ 'it; do not ask for approval. It is a local signing key only: not '
+	+ 'registered anywhere and unrelated to org auth. A developer who wants '
+	+ 'their own key can use import_credentials.'
 
 export type ResolvedEthKey = {
 	/** Raw 0x-hex 32-byte scalar. */
@@ -63,14 +74,19 @@ export function normalizeEthHex(value: string): string {
 	return '0x' + v.replace(/^0x/, '').toLowerCase()
 }
 
-/** Read `RECLAIM_PRIVATE_KEY` from a dotenv file (simple KEY=VALUE parse). */
-function readDotenvKey(path: string): string | undefined {
+/** Read `name` (default `RECLAIM_PRIVATE_KEY`) from a dotenv file (simple
+ *  KEY=VALUE parse). */
+export function readDotenvKey(
+	path: string,
+	name = ENV_VAR,
+): string | undefined {
 	if(!existsSync(path)) {
 		return undefined
 	}
 
+	const re = new RegExp(`^\\s*${name}\\s*=\\s*(.+?)\\s*$`)
 	for(const line of readFileSync(path, 'utf8').split('\n')) {
-		const m = line.match(/^\s*RECLAIM_PRIVATE_KEY\s*=\s*(.+?)\s*$/)
+		const m = line.match(re)
 		if(m) {
 			return m[1]
 		}
@@ -135,6 +151,24 @@ export function resolveEthKey(
 	return undefined
 }
 
+/**
+ * Resolve the eth proof-owner key, or generate a local test key and write it
+ * to the project `.env` when none is configured. Never prompts.
+ */
+export function resolveOrCreateEthKey(
+	projectDir = findProjectRoot(process.cwd()),
+): ResolvedEthKey {
+	const existing = resolveEthKey(projectDir)
+	if(existing) {
+		return existing
+	}
+
+	const { path } = writeEthKey(generateKeypair().privateKey, projectDir)
+	const created = resolveEthKey(projectDir)
+	assert(created, `generated key not readable from ${path}`)
+	return { ...created, source: 'generated' }
+}
+
 /** Append `entry` to the project `.gitignore` if not already present. */
 export function ensureGitignored(projectDir: string, entry: string) {
 	const path = join(projectDir, '.gitignore')

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

@@ -5,4 +5,4 @@ export {
 	buildBuilderOrganizationTools,
 } from './builder-access.ts'
 export { buildCredentialTools, buildLocalCredentialTools } from './build.ts'
-export { readSession } from './session-cache.ts'
+export { readSession, sessionRefreshingFetch } from './session-cache.ts'