@reclaimprotocol/agent 0.1.35 → 0.1.37

package/lib/mcp/tools/authenticate/authenticate.js

@@ -2,9 +2,18 @@ import { spawn } from 'node:child_process';
 import { createServer } from 'node:http';
 import * as oauth from 'openid-client';
 import { defineTool } from "../../server.js";
-import { writeSession } from "./session-cache.js";
-const SCOPE = 'openid profile email';
+import { authBaseFor, oauthRequestOptions, SCOPE, sessionFromTokens, } from "./oauth-config.js";
+import { readSession, writeSession } from "./session-cache.js";
+/** 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;
+/** The sign-in in progress (or last finished) for each Builder client. */
+const FLOWS = new WeakMap();
 export function authenticateTool(client, name = 'reclaim_authenticate') {
     return defineTool({
         name,
@@ -16,29 +25,98 @@ export function authenticateTool(client, name = 'reclaim_authenticate') {
                 + '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 = async (url, options) => {
-    const res = await fetch(url, options);
-    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, authToolName = 'reclaim_authenticate') {
+    return defineTool({
+        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, 
+// Overridable only so tests can intercept the authorize URL instead of
+// actually spawning a browser; every real caller uses the default.
+openBrowserFn = openBrowser) {
+    const existing = FLOWS.get(client);
+    if (existing && !existing.outcome) {
+        return existing.started;
+    }
+    const begun = beginSignIn(client, openBrowserFn);
+    const flow = {
+        started: begun.then(({ pending }) => pending),
+        completion: begun.then(({ completion }) => completion, (err) => ({ status: 'FAILED', 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, timeoutMs) {
+    const flow = FLOWS.get(client);
+    if (!flow) {
+        const session = readSession();
+        return session
+            ? { status: 'AUTHENTICATED', expiresAt: session.expiresAt }
+            : { status: 'NOT_STARTED' };
     }
-    return res;
-};
+    let timer;
+    const outcome = await Promise.race([
+        flow.completion,
+        new Promise((resolve) => {
+            timer = setTimeout(() => resolve(undefined), timeoutMs);
+        }),
+    ]);
+    clearTimeout(timer);
+    return outcome ?? flow.started;
+}
 /**
  * Standard OAuth 2.0 Authorization Code + PKCE, native-app style (RFC 8252):
  * dynamically register a public client (RFC 7591 — Better Auth's
@@ -48,108 +126,92 @@ const _customFetchForOauth = async (url, options) => {
  * 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(client, 
-// Overridable only so tests can intercept the authorize URL instead of
-// actually spawning a browser; every real caller uses the default.
-openBrowserFn = openBrowser) {
-    const authBase = `${client.baseUrl}/auth`;
+async function beginSignIn(client, openBrowserFn) {
+    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;
+    let config;
     try {
-        const config = await oauth.dynamicClientRegistration(new URL(authBase), {
+        config = await oauth.dynamicClientRegistration(new URL(authBase), {
             client_name: 'Reclaim CLI',
             redirect_uris: [callback.redirectUri],
             token_endpoint_auth_method: 'none',
             grant_types: ['authorization_code', 'refresh_token'],
             response_types: ['code'],
             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] }
-                : {}),
-        });
-        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,
-        });
+        }, undefined, oauthRequestOptions(authBase));
     }
     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);
-    return {
-        status: 'AUTHENTICATED',
-        note: 'Access token cached in ~/.reclaim/config.json and active now.',
-        expiresAt,
+    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 = {
+        status: 'PENDING',
+        signInUrl,
+        browserOpened: launch.opened,
+        ...(launch.reason ? { reason: launch.reason } : {}),
+        expiresAt: callback.expiresAt,
     };
+    return { pending, completion };
+    async function finish() {
+        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) {
+    // 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() {
     let resolveUrl;
@@ -159,7 +221,9 @@ async function listenForCallback() {
         rejectUrl = reject;
     });
     const server = createServer();
-    const timer = setTimeout(() => rejectUrl(new Error('Timed out waiting for sign-in (5 min).')), CALLBACK_TIMEOUT_MS);
+    const expiresAt = new Date(Date.now() + CALLBACK_TIMEOUT_MS).toISOString();
+    const timer = setTimeout(() => 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((resolve, reject) => {
         server.once('error', reject);
         server.listen(0, '127.0.0.1', () => {
@@ -173,11 +237,11 @@ async function listenForCallback() {
     }).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));
     const redirectUri = `http://127.0.0.1:${port}/callback`;
@@ -196,24 +260,56 @@ async function listenForCallback() {
     return {
         redirectUri,
         url,
+        expiresAt,
         close: () => {
             clearTimeout(timer);
             server.close();
         },
     };
 }
-function openBrowser(url) {
-    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, { env = process.env, platform = process.platform } = {}) {
     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)',
+        };
+    }
+    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) {
+            clearTimeout(timer);
+            resolve(launch);
+        }
+    });
 }

package/lib/mcp/tools/authenticate/build.d.ts

@@ -9,7 +9,7 @@ import type { RegisteredTool } from '../../server.ts';
 export declare 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 declare function buildCredentialTools(client: ReclaimClient): RegisteredTool[];

package/lib/mcp/tools/authenticate/build.js

@@ -1,6 +1,7 @@
-import { authenticateTool } from "./authenticate.js";
+import { authenticateTool, waitForSignInTool } from "./authenticate.js";
 import { importTool } from "./import.js";
 import { issueTool } from "./issue.js";
+import { issueOrgKeypairTool } from "./issue-org-keypair.js";
 import { issueOrgTokenTool } from "./issue-org-token.js";
 import { resolveOwnerKeyTool } from "./resolve-owner-key.js";
 /**
@@ -18,13 +19,15 @@ export function buildLocalCredentialTools() {
 }
 /**
  * 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) {
     return [
         authenticateTool(client),
+        waitForSignInTool(client),
         issueOrgTokenTool(client),
+        issueOrgKeypairTool(client),
         ...buildLocalCredentialTools(),
     ];
 }

package/lib/mcp/tools/authenticate/builder-access.js

@@ -1,12 +1,15 @@
 import { defineTool } from "../../server.js";
-import { authenticateTool } from "./authenticate.js";
+import { authenticateTool, waitForSignInTool } from "./authenticate.js";
 /** Legacy-devtools mode needs a distinct Builder login for its two
  * Builder-exclusive features: allocating quota-accounted Popcorn sessions
  * (see `buildBuilderOrganizationTools` below) and listing Builder
  * organizations. Builder mode needs neither — its native auth tool alone
  * covers both, org listing included (via its generated `list_orgs`). */
 export function buildBuilderAuthenticationTools(client) {
-    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
  * narrow organization-discovery bridge — an org id is required to allocate a

package/lib/mcp/tools/authenticate/eth-key.d.ts

@@ -1,7 +1,10 @@
 /** The dotenv file the agent reads from / writes the key to. */
 export declare 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 declare const GENERATED_KEY_NOTE: string;
 export type ResolvedEthKey = {
     /** Raw 0x-hex 32-byte scalar. */
     privateKey: string;
@@ -13,12 +16,20 @@ export type ResolvedEthKey = {
 };
 /** Validate + normalize a raw Ethereum private key to lowercase 0x-hex. */
 export declare function normalizeEthHex(value: string): string;
+/** Read `name` (default `RECLAIM_PRIVATE_KEY`) from a dotenv file (simple
+ *  KEY=VALUE parse). */
+export declare function readDotenvKey(path: string, name?: string): string | undefined;
 /**
  * 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 declare function resolveEthKey(projectDir?: string): ResolvedEthKey | 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 declare function resolveOrCreateEthKey(projectDir?: string): ResolvedEthKey;
 /** Append `entry` to the project `.gitignore` if not already present. */
 export declare function ensureGitignored(projectDir: string, entry: string): void;
 /**

package/lib/mcp/tools/authenticate/eth-key.js

@@ -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, existsSync, mkdirSync, readFileSync, writeFileSync, } from 'node:fs';
 import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
@@ -23,19 +24,28 @@ import { findProjectRoot } from "../../../paths.js";
 const ENV_VAR = 'RECLAIM_PRIVATE_KEY';
 /** The dotenv file the agent reads from / writes the key to. */
 export const ENV_FILE = '.env';
+/** 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.';
 /** Validate + normalize a raw Ethereum private key to lowercase 0x-hex. */
 export function normalizeEthHex(value) {
     const v = value.trim().replace(/^['"]|['"]$/g, '');
     assert(/^(0x)?[0-9a-fA-F]{64}$/.test(v), 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) {
+/** Read `name` (default `RECLAIM_PRIVATE_KEY`) from a dotenv file (simple
+ *  KEY=VALUE parse). */
+export function readDotenvKey(path, name = ENV_VAR) {
     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];
         }
@@ -79,6 +89,20 @@ export function resolveEthKey(projectDir = findProjectRoot(process.cwd())) {
     }
     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())) {
+    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, entry) {
     const path = join(projectDir, '.gitignore');

package/lib/mcp/tools/authenticate/index.d.ts

@@ -1,3 +1,3 @@
 export { buildBuilderAuthenticationTools, buildBuilderOrganizationTools, } from './builder-access.ts';
 export { buildCredentialTools, buildLocalCredentialTools } from './build.ts';
-export { readSession } from './session-cache.ts';
+export { readSession, sessionRefreshingFetch } from './session-cache.ts';

package/lib/mcp/tools/authenticate/index.js

@@ -2,4 +2,4 @@
 // and the org-token-authenticated builder tools. Import from here.
 export { buildBuilderAuthenticationTools, buildBuilderOrganizationTools, } from "./builder-access.js";
 export { buildCredentialTools, buildLocalCredentialTools } from "./build.js";
-export { readSession } from "./session-cache.js";
+export { readSession, sessionRefreshingFetch } from "./session-cache.js";

package/lib/mcp/tools/authenticate/issue-org-keypair.d.ts

@@ -0,0 +1,10 @@
+import type { ReclaimClient } from '@reclaimprotocol/client/api';
+import { type RegisteredTool } from '../../server.ts';
+/**
+ * Creates the organization's eth key pair for session binding and encrypted
+ * results: writes the private key to the app's server env file and registers
+ * only the public key with Builder, so the private key never passes through
+ * the agent's transcript. Reuses a key the env file already holds, so a
+ * repeat call (for example, to turn on encryption) keeps the same key.
+ */
+export declare function issueOrgKeypairTool(client: ReclaimClient): RegisteredTool;