@reclaimprotocol/agent 0.1.35 → 0.1.37

package/lib/mcp/tools/authenticate/issue-org-keypair.js

@@ -0,0 +1,82 @@
+import { deriveFromPrivateKey, generateKeypair } from '@reclaimprotocol/client';
+import assert from 'node:assert';
+import { isAbsolute, relative, resolve } from 'node:path';
+import { defineTool } from "../../server.js";
+import { normalizeEthHex, readDotenvKey, upsertEnvVar } from "./eth-key.js";
+/**
+ * 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 function issueOrgKeypairTool(client) {
+    return defineTool({
+        name: 'issue_org_keypair',
+        description: 'Sets up the organization\'s eth key pair, used for TEE session '
+            + 'binding (`sessions.create({ orgEthPrivateKey })`) and, with '
+            + '`encryptResults`, encrypted result delivery '
+            + '(`results.receive(body, { orgEthPrivateKey })`). Writes the '
+            + 'private key to a server env file in the project (reusing a key '
+            + 'already there) and registers only the public key. Returns the '
+            + 'address, file, and variable; never the key. Returns 409 when the '
+            + 'org already has a different key: ask the developer for that key '
+            + 'rather than replacing it.',
+        inputSchema: {
+            type: 'object',
+            required: ['orgId', 'projectDir'],
+            properties: {
+                orgId: { type: 'string', format: 'uuid' },
+                projectDir: {
+                    type: 'string',
+                    description: 'Absolute path of the app\'s project directory.',
+                },
+                envFile: {
+                    type: 'string',
+                    description: 'Env file to write, relative to `projectDir`. Default `.env`.',
+                },
+                envVar: {
+                    type: 'string',
+                    pattern: '^[A-Za-z_][A-Za-z0-9_]*$',
+                    description: 'Variable name to set. Default `RECLAIM_ORG_ETH_PRIVATE_KEY`.',
+                },
+                encryptResults: {
+                    type: 'boolean',
+                    description: 'Encrypt delivered results to this key. Default false.',
+                },
+            },
+        },
+        annotations: { openWorldHint: true, destructiveHint: false },
+    }, async (args) => {
+        assert(isAbsolute(args.projectDir), new Error('`projectDir` must be an absolute path.'));
+        const envFile = args.envFile || '.env';
+        const envVar = args.envVar || 'RECLAIM_ORG_ETH_PRIVATE_KEY';
+        const envPath = resolve(args.projectDir, envFile);
+        const inside = relative(args.projectDir, envPath);
+        assert(inside && !inside.startsWith('..') && !isAbsolute(inside), new Error('`envFile` must be inside `projectDir`.'));
+        const existing = readDotenvKey(envPath, envVar);
+        const keypair = existing
+            ? deriveFromPrivateKey(normalizeEthHex(existing))
+            : generateKeypair();
+        // Register first: a 409 (the org has another key) must not leave a
+        // key Builder doesn't know in the env file.
+        const canEncryptResult = args.encryptResults ?? false;
+        await client.call('SetOrgKeypair', {
+            params: { orgId: args.orgId },
+            body: {
+                publicKey: keypair.publicKey,
+                canEncryptResult,
+                replace: false,
+            },
+        });
+        const path = upsertEnvVar(args.projectDir, envFile, envVar, keypair.privateKey);
+        return {
+            orgId: args.orgId,
+            address: keypair.address,
+            canEncryptResult,
+            envFile: path,
+            envVar,
+            reused: Boolean(existing),
+        };
+    });
+}

package/lib/mcp/tools/authenticate/oauth-config.d.ts

@@ -0,0 +1,31 @@
+import * as oauth from 'openid-client';
+import type { CachedSession } from './session-cache.ts';
+/**
+ * `offline_access` makes Better Auth's `oauth-provider` issue a refresh token
+ * (it issues one only when the grant carries that scope), so the session can
+ * outlive the 1-hour access token.
+ */
+export declare const SCOPE = "openid profile email offline_access";
+/** Where Better Auth mounts its OAuth endpoints under the Builder origin. */
+export declare function authBaseFor(baseUrl: string): string;
+/**
+ * Request options every openid-client call against Builder's auth server
+ * needs. Pass them to `dynamicClientRegistration` or `discovery`; the
+ * returned `Configuration` keeps them for its later calls.
+ */
+export declare function oauthRequestOptions(authBase: string): {
+    execute?: (typeof oauth.allowInsecureRequests)[] | undefined;
+    algorithm: "oauth2";
+    [customFetch]: typeof customFetchForOauth;
+};
+/**
+ * The session to cache for a token response. A refresh response may omit
+ * `refresh_token` (no rotation), so the caller passes the one it already has.
+ */
+export declare function sessionFromTokens(tokens: oauth.TokenEndpointResponse, client: {
+    clientId: string;
+    authBase: string;
+    refreshToken?: string;
+}): CachedSession;
+declare function customFetchForOauth(url: string, options: oauth.CustomFetchOptions): Promise<Response>;
+export {};

package/lib/mcp/tools/authenticate/oauth-config.js

@@ -0,0 +1,67 @@
+import * as oauth from 'openid-client';
+/**
+ * `offline_access` makes Better Auth's `oauth-provider` issue a refresh token
+ * (it issues one only when the grant carries that scope), so the session can
+ * outlive the 1-hour access token.
+ */
+export const SCOPE = 'openid profile email offline_access';
+/** Where Better Auth mounts its OAuth endpoints under the Builder origin. */
+export function authBaseFor(baseUrl) {
+    return `${baseUrl}/auth`;
+}
+/**
+ * Request options every openid-client call against Builder's auth server
+ * needs. Pass them to `dynamicClientRegistration` or `discovery`; the
+ * returned `Configuration` keeps them for its later calls.
+ */
+export function oauthRequestOptions(authBase) {
+    // 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);
+    return {
+        // 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 returns 200 with an otherwise well-formed body. `customFetch`
+        // persists onto the returned `Configuration` for ALL its future calls
+        // (token exchange included, which correctly returns 200), so the URL,
+        // not just method+status, gates the rewrite.
+        [oauth.customFetch]: customFetchForOauth,
+        ...(isLoopbackAuthBase ? { execute: [oauth.allowInsecureRequests] } : {}),
+    };
+}
+/**
+ * The session to cache for a token response. A refresh response may omit
+ * `refresh_token` (no rotation), so the caller passes the one it already has.
+ */
+export function sessionFromTokens(tokens, client) {
+    return {
+        token: tokens.access_token,
+        expiresAt: new Date(Date.now() + (tokens.expires_in ?? 3600) * 1000).toISOString(),
+        refreshToken: tokens.refresh_token ?? client.refreshToken,
+        clientId: client.clientId,
+        authBase: client.authBase,
+    };
+}
+async function customFetchForOauth(url, options) {
+    // openid-client hands over a fetch-compatible options bag whose `body`
+    // type is narrower than, but assignable in practice to, `RequestInit`'s.
+    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,
+        });
+    }
+    return res;
+}

package/lib/mcp/tools/authenticate/resolve-owner-key.d.ts

@@ -1,13 +1,12 @@
 import { type RegisteredTool } from '../../server.ts';
 /**
- * Decide which eth proof-owner key `run_proof` should sign with, BEFORE
- * calling it. The key is a raw 0x-hex Ethereum private key, resolved (no
- * `~/.reclaim` cache) from:
+ * Decide which eth proof-owner key `run_proof` signs with. The key is a raw
+ * 0x-hex Ethereum private key, resolved (no `~/.reclaim` cache) from:
  *   1. `RECLAIM_PRIVATE_KEY` in the MCP env
  *   2. a `RECLAIM_PRIVATE_KEY=0x…` line in the project `.env`
  *   3. a file at `RECLAIM_PRIVATE_KEY_FILE` holding the raw hex
- *   4. none → ask the dev to generate (issue_credentials) or provide one
- *      (import_credentials), then call again.
+ *   4. none → a local test key is generated into the project `.env`. Nobody
+ *      is asked; the agent tells the developer afterwards.
  * Never returns the private key — only the derived address.
  */
 export declare function resolveOwnerKeyTool(): RegisteredTool;

package/lib/mcp/tools/authenticate/resolve-owner-key.js

@@ -1,51 +1,55 @@
-import { join } from 'node:path';
 import { findProjectRoot } from "../../../paths.js";
 import { defineTool } from "../../server.js";
-import { ENV_FILE, resolveEthKey } from "./eth-key.js";
+import { GENERATED_KEY_NOTE, resolveOrCreateEthKey } from "./eth-key.js";
 /**
- * Decide which eth proof-owner key `run_proof` should sign with, BEFORE
- * calling it. The key is a raw 0x-hex Ethereum private key, resolved (no
- * `~/.reclaim` cache) from:
+ * Decide which eth proof-owner key `run_proof` signs with. The key is a raw
+ * 0x-hex Ethereum private key, resolved (no `~/.reclaim` cache) from:
  *   1. `RECLAIM_PRIVATE_KEY` in the MCP env
  *   2. a `RECLAIM_PRIVATE_KEY=0x…` line in the project `.env`
  *   3. a file at `RECLAIM_PRIVATE_KEY_FILE` holding the raw hex
- *   4. none → ask the dev to generate (issue_credentials) or provide one
- *      (import_credentials), then call again.
+ *   4. none → a local test key is generated into the project `.env`. Nobody
+ *      is asked; the agent tells the developer afterwards.
  * Never returns the private key — only the derived address.
  */
 export function resolveOwnerKeyTool() {
     return defineTool({
         name: 'resolve_owner_key',
-        description: 'Finds the eth proof-owner key `run_proof` signs with. Call it '
-            + 'before `run_proof`. Checks RECLAIM_PRIVATE_KEY in the MCP env, a '
-            + 'RECLAIM_PRIVATE_KEY line in the project .env, then the file at '
-            + 'RECLAIM_PRIVATE_KEY_FILE. Returns { ready: true, address, source '
-            + '}: pass `address` to `run_proof` as `ownerAddress`. Returns { '
-            + 'ready: false } when none exists: ask the developer to create one '
-            + 'with `issue_credentials` or import one with `import_credentials` '
-            + '(a key file), then call it again. Never returns the key.',
-        inputSchema: { type: 'object', properties: {} },
-        annotations: { readOnlyHint: true, openWorldHint: false },
-    }, async () => {
-        const projectDir = findProjectRoot(process.cwd());
-        const resolved = resolveEthKey(projectDir);
-        if (resolved) {
-            return {
-                ready: true,
-                address: resolved.address,
-                source: resolved.source,
-                ...(resolved.path ? { path: resolved.path } : {}),
-            };
-        }
+        description: 'Finds the eth proof-owner key `run_proof` signs with, creating a '
+            + 'local test key when none exists. `run_proof` does this itself, '
+            + 'so call it only to show the signing address. Checks '
+            + 'RECLAIM_PRIVATE_KEY in the MCP env, a RECLAIM_PRIVATE_KEY line in '
+            + 'the project .env, then the file at RECLAIM_PRIVATE_KEY_FILE. When '
+            + 'none is set, it writes a new key to the project .env (mode 0600, '
+            + 'added to .gitignore). Returns { ready: true, address, source, '
+            + 'path?, note? }; `source` is `generated` when it created the key, '
+            + 'and `note` then says to tell the developer once, after the fact. '
+            + 'Do not ask the developer for a key. Never returns the key.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                projectDir: {
+                    type: 'string',
+                    description: 'Project directory whose `.env` holds the key. Defaults to '
+                        + 'the closest ancestor of cwd containing .git or '
+                        + 'package.json.',
+                },
+            },
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async (args) => {
+        const projectDir = findProjectRoot(args.projectDir || process.cwd());
+        const key = resolveOrCreateEthKey(projectDir);
         return {
-            ready: false,
-            message: 'No eth proof-owner key available — no RECLAIM_PRIVATE_KEY in the ' +
-                `env, no RECLAIM_PRIVATE_KEY in ${join(projectDir, ENV_FILE)}, and ` +
-                'no RECLAIM_PRIVATE_KEY_FILE. Ask the dev to generate one via ' +
-                'issue_credentials, or import one they already hold via ' +
-                'import_credentials (a key file). Then call ' +
-                'resolve_owner_key again and pass its address to run_proof as ' +
-                'ownerAddress.',
+            ready: true,
+            address: key.address,
+            source: key.source,
+            ...(key.path ? { path: key.path } : {}),
+            ...(key.source === 'generated' ? { note: GENERATED_KEY_NOTE } : {}),
         };
     });
 }

package/lib/mcp/tools/authenticate/session-cache.d.ts

@@ -1,9 +1,15 @@
 export type CachedSession = {
     token: string;
-    /** ISO timestamp when the token expires (2 days from issue). */
+    /** ISO timestamp when the access token expires. */
     expiresAt: string;
     /** Email of the user who authorized (if available). */
     email?: string;
+    /** OAuth refresh token; trades for a new access token near expiry. */
+    refreshToken?: string;
+    /** Public OAuth client the tokens were issued to (refresh needs it). */
+    clientId?: string;
+    /** Auth server base URL that issued the tokens. */
+    authBase?: string;
 };
 /** Persist the auth token to the `session` section of the unified config. */
 export declare function writeSession(session: CachedSession): void;
@@ -12,3 +18,21 @@ export declare function writeSession(session: CachedSession): void;
  * valid (not yet expired). Returns undefined on any error.
  */
 export declare function readSession(): CachedSession | undefined;
+/** The cached session even when its access token has expired. */
+export declare function readStoredSession(): CachedSession | undefined;
+/**
+ * Wraps `fetch` for the Builder client so a cached sign-in keeps working past
+ * the access token's lifetime. Each request uses the cached session's token,
+ * refreshed via the OAuth refresh grant when it's about to expire or when
+ * Builder answers 401. If no refresh is possible, the 401 tells the agent to
+ * sign in again with `signInTool`. Without a cached session, requests pass
+ * through untouched. Don't install it when `RECLAIM_API_TOKEN` is set: that
+ * token takes precedence and is never refreshed.
+ */
+export declare function sessionRefreshingFetch(signInTool: string, baseFetch?: typeof fetch): typeof fetch;
+/**
+ * Trade the session's refresh token for a new access token and cache the
+ * result. Returns undefined when the session can't be refreshed; a refresh
+ * token the server rejects is dropped so later calls stop retrying it.
+ */
+export declare function refreshSession(session: CachedSession): Promise<CachedSession | undefined>;

package/lib/mcp/tools/authenticate/session-cache.js

@@ -1,4 +1,10 @@
+import { PROBLEM_CONTENT_TYPE } from '@reclaimprotocol/client/api';
+import * as oauth from 'openid-client';
 import { ConfigStore } from "../../../config/store.js";
+import { LOGGER } from "../../../logger.js";
+import { oauthRequestOptions, sessionFromTokens } from "./oauth-config.js";
+/** Refresh this long before the access token actually expires. */
+const EXPIRY_MARGIN_MS = 60 * 1000;
 /** Persist the auth token to the `session` section of the unified config. */
 export function writeSession(session) {
     new ConfigStore().write({ session });
@@ -8,12 +14,97 @@ export function writeSession(session) {
  * valid (not yet expired). Returns undefined on any error.
  */
 export function readSession() {
+    const s = readStoredSession();
+    if (!s || new Date(s.expiresAt) <= new Date()) {
+        return undefined;
+    }
+    return s;
+}
+/** The cached session even when its access token has expired. */
+export function readStoredSession() {
     const s = new ConfigStore().read()?.session;
-    if (!s?.token || !s.expiresAt) {
+    return s?.token && s.expiresAt ? s : undefined;
+}
+/**
+ * Wraps `fetch` for the Builder client so a cached sign-in keeps working past
+ * the access token's lifetime. Each request uses the cached session's token,
+ * refreshed via the OAuth refresh grant when it's about to expire or when
+ * Builder answers 401. If no refresh is possible, the 401 tells the agent to
+ * sign in again with `signInTool`. Without a cached session, requests pass
+ * through untouched. Don't install it when `RECLAIM_API_TOKEN` is set: that
+ * token takes precedence and is never refreshed.
+ */
+export function sessionRefreshingFetch(signInTool, baseFetch = fetch) {
+    // One refresh at a time: Better Auth rotates refresh tokens and revokes
+    // the whole family when a used one is replayed.
+    let refreshing;
+    return async (input, init) => {
+        let session = readStoredSession();
+        if (!session) {
+            return baseFetch(input, init);
+        }
+        const expiring = new Date(session.expiresAt).getTime() - Date.now() < EXPIRY_MARGIN_MS;
+        const triedRefresh = expiring && !!session.refreshToken;
+        if (triedRefresh) {
+            session = await refreshOnce(session) ?? session;
+        }
+        const res = await baseFetch(input, withBearer(init, session.token));
+        if (res.status !== 401) {
+            return res;
+        }
+        const next = triedRefresh ? undefined : await refreshOnce(session);
+        if (next) {
+            return baseFetch(input, withBearer(init, next.token));
+        }
+        return sessionExpiredResponse(signInTool);
+    };
+    function refreshOnce(session) {
+        refreshing ?? (refreshing = refreshSession(session)
+            .finally(() => {
+            refreshing = undefined;
+        }));
+        return refreshing;
+    }
+}
+/**
+ * Trade the session's refresh token for a new access token and cache the
+ * result. Returns undefined when the session can't be refreshed; a refresh
+ * token the server rejects is dropped so later calls stop retrying it.
+ */
+export async function refreshSession(session) {
+    const { refreshToken, clientId, authBase } = session;
+    if (!refreshToken || !clientId || !authBase) {
         return undefined;
     }
-    if (new Date(s.expiresAt) <= new Date()) {
-        return undefined; // expired
+    try {
+        const config = await oauth.discovery(new URL(authBase), clientId, undefined, oauth.None(), oauthRequestOptions(authBase));
+        const tokens = await oauth.refreshTokenGrant(config, refreshToken);
+        const next = {
+            ...sessionFromTokens(tokens, { clientId, authBase, refreshToken }),
+            email: session.email,
+        };
+        writeSession(next);
+        return next;
     }
-    return s;
+    catch (err) {
+        LOGGER.warn({ err }, 'builder session refresh failed');
+        if (err instanceof oauth.ResponseBodyError) {
+            writeSession({ ...session, refreshToken: undefined });
+        }
+        return undefined;
+    }
+}
+function withBearer(init, token) {
+    const headers = new Headers(init?.headers);
+    headers.set('Authorization', `Bearer ${token}`);
+    return { ...init, headers };
+}
+function sessionExpiredResponse(signInTool) {
+    return new Response(JSON.stringify({
+        type: 'about:blank',
+        title: 'Unauthorized',
+        status: 401,
+        detail: 'Your Builder sign-in expired and could not be refreshed. '
+            + `Call ${signInTool} to sign in again, then retry.`,
+    }), { status: 401, headers: { 'content-type': PROBLEM_CONTENT_TYPE } });
 }

package/lib/mcp/tools/mode/mode.js

@@ -1,17 +1,17 @@
 import { defaultConfigPath } from "../../../config/store.js";
 import { oldModeSource } from "../../../consts.js";
 import { defineTool } from "../../server.js";
-/** Whether `config`'s cached builder session token is present and not yet
- *  expired. Mirrors `readSession`'s check, but against the CALLER's
- *  `ConfigStore` instance (not always the default `~/.reclaim/config.json`
- *  path) so this stays test-isolatable and consistent with the rest of this
- *  tool's config reads. */
+/** Whether `config`'s cached builder session token is present and either
+ *  not yet expired or refreshable. Mirrors `readSession`'s check, but against
+ *  the CALLER's `ConfigStore` instance (not always the default
+ *  `~/.reclaim/config.json` path) so this stays test-isolatable and
+ *  consistent with the rest of this tool's config reads. */
 function hasValidBuilderSession(config) {
     const session = config.read()?.session;
     if (!session?.token || !session.expiresAt) {
         return false;
     }
-    return new Date(session.expiresAt) > new Date();
+    return !!session.refreshToken || new Date(session.expiresAt) > new Date();
 }
 /**
  * The `set_devtools_mode` / `get_devtools_mode` tools: persist which backend

package/lib/mcp/tools/verification/proxy-callback-events.d.ts

@@ -13,7 +13,20 @@ type Recent = {
     httpStatus?: number;
     at: string;
 };
+/** A session whose oldest pending event the app has not accepted. */
+type Blocked = {
+    sessionId: string;
+    event: string;
+    eventId: string;
+    httpStatus?: number;
+    attempts: number;
+    lastError?: string;
+    /** When the first attempt failed, as an ISO timestamp. */
+    since: string;
+};
 export interface ProxyDeps extends CallbackDeps {
+    /** The clock, in milliseconds. Defaults to `Date.now`. */
+    now?: () => number;
     /** Delivers an event to the app. Defaults to global `fetch`. */
     forwardFetch?: typeof globalThis.fetch;
     /** Waits between polls. Resolves early, without error, on abort. */
@@ -23,9 +36,13 @@ export interface ProxyDeps extends CallbackDeps {
 /**
  * Polls the org's pending pull events and POSTs each envelope to a local
  * route, like `stripe listen --forward-to`. 2xx responses are acknowledged;
- * anything else (redirects included) stays pending and is retried with
- * exponential backoff. After a failure the batch stops, so events reach the
- * app in order.
+ * anything else (redirects included) stays pending.
+ *
+ * Order holds per session. When an event fails, its session is held: its later
+ * events are not sent or acknowledged, and the failed event is retried with
+ * exponential backoff (2 s, 4 s, ... 30 s). Other sessions keep flowing at the
+ * normal poll rate. Held sessions appear in `status().blocked`, and clear when
+ * the app accepts the event.
  */
 declare class Forwarder {
     #private;
@@ -34,6 +51,7 @@ declare class Forwarder {
     constructor(client: ReclaimClient, listener: ListenerInfo, target: Target, deps: ProxyDeps);
     status(): {
         recent: Recent[];
+        blocked: Blocked[];
         lastError?: string | undefined;
         forwarding: boolean;
         target: string;