@reclaimprotocol/agent 0.1.33 → 0.1.35

package/lib/mcp/tools/agent/proof.d.ts

@@ -1,4 +1,5 @@
 import { type ProofResult } from '../../../proof/attestor.ts';
+import { type AttestorCheckResult, type CheckAttestorOptions } from '../../../proof/check-attestor.ts';
 /**
  * The MCP's rich `run_proof` view: persist the full claim to disk, return
  * identifier + extractedParameters + a prettified claim (request dropped, byte
@@ -11,3 +12,14 @@ export declare function shapeRichProofResult(result: ProofResult, opts: {
     hasSecrets: boolean;
     attestorUrl?: string;
 }): Record<string, unknown>;
+export interface ProofDiagnosis {
+    attestor: AttestorCheckResult;
+    likelyCause: string;
+    next: string;
+}
+/**
+ * When an unverified proof failed with a network-like error, runs the
+ * attestor check once and says whether the attestor or the target site is the
+ * likely cause. Returns `undefined` for verified proofs and other errors.
+ */
+export declare function diagnoseNetworkFailure(result: Pick<ProofResult, 'verified' | 'error' | 'errorKind'>, check: (opts: CheckAttestorOptions) => Promise<AttestorCheckResult>, attestorUrl?: string): Promise<ProofDiagnosis | undefined>;

package/lib/mcp/tools/agent/proof.js

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

package/lib/mcp/tools/agent/propose.js

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

package/lib/mcp/tools/agent/publish.d.ts

@@ -1,6 +1,7 @@
 import type { ReclaimClient } from '@reclaimprotocol/client/api';
+import type { KeptScriptRef } from '../../../authoring/index.ts';
 import { type RegisteredTool } from '../../server.ts';
 import type { AttachState } from './attach.ts';
 export declare function createVersionFromCaptureTool(client: ReclaimClient, attachRef?: {
     current?: AttachState;
-}): RegisteredTool;
+}, kept?: KeptScriptRef): RegisteredTool;

package/lib/mcp/tools/agent/publish.js

@@ -165,11 +165,13 @@ const BROWSER_REQUEST_ACTION_SCHEMA = {
     },
     required: ['id', 'origin', 'path', 'method'],
 };
-export function createVersionFromCaptureTool(client, attachRef) {
+export function createVersionFromCaptureTool(client, attachRef, kept) {
     return defineTool({
         name: 'create_provider_version_from_capture',
         description: 'Creates a new immutable provider version after `run_proof` succeeds. '
-            + 'Pass exactly one `provider` or `providers` value returned by '
+            + 'Publishes the navigation script kept by `test_user_script` as '
+            + '`jsUserScripts` unless `jsUserScripts` is passed. Pass exactly '
+            + 'one `provider` or `providers` value returned by '
             + '`propose_provider`; do not rebuild the recipe. The default is a '
             + 'patch bump, or use `bump` or an explicitly requested higher '
             + '`version`. The new version remains a draft until published or '
@@ -230,7 +232,9 @@ export function createVersionFromCaptureTool(client, attachRef) {
                 },
                 jsUserScripts: {
                     type: 'string',
-                    description: USER_SCRIPT_HINT +
+                    description: 'Defaults to the script kept by `test_user_script` with ' +
+                        '`keep: true`; pass it only to override. ' +
+                        USER_SCRIPT_HINT +
                         ' Stored as webSettings.jsUserScripts; the Builder ' +
                         'verification client runs it before every page load ' +
                         '(including before navigating to initialUrl), matching ' +
@@ -288,7 +292,9 @@ export function createVersionFromCaptureTool(client, attachRef) {
             },
             required: ['providerId', 'initialUrl'],
         },
+        annotations: { openWorldHint: true, destructiveHint: false },
     }, async (args) => {
+        const jsUserScripts = args.jsUserScripts ?? kept?.keptScript?.script;
         // Exactly one of `provider` / `providers` — normalize to an array.
         const hasMany = Array.isArray(args.providers) && args.providers.length > 0;
         const hasOne = !!args.provider;
@@ -306,7 +312,7 @@ export function createVersionFromCaptureTool(client, attachRef) {
             notes: args.notes,
             version: ver,
             requiredContext: args.requiredContext,
-            jsUserScripts: args.jsUserScripts,
+            jsUserScripts,
             allowedJsRequests: args.allowedJsRequests,
             browserRequestActions: args.browserRequestActions,
             interceptorOptions: args.interceptorOptions,
@@ -332,11 +338,11 @@ export function createVersionFromCaptureTool(client, attachRef) {
         const attached = attachRef?.current;
         notes.push(...postPublishBrowserNotes(attached, {
             initialUrl: args.initialUrl,
-            hasUserScript: !!args.jsUserScripts?.trim(),
+            hasUserScript: !!jsUserScripts?.trim(),
             hasInterceptor: !!args.interceptorOptions,
         }));
         // Let the developer know how and when the script runs.
-        if (args.jsUserScripts?.trim()) {
+        if (jsUserScripts?.trim()) {
             notes.push('jsUserScripts will run in the Builder verification client before ' +
                 'every page load (before navigating to initialUrl), matching ' +
                 'old-devtool customInjection. window.Reclaim is available for ' +

package/lib/mcp/tools/agent/replay.js

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

package/lib/mcp/tools/agent/session.js

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

package/lib/mcp/tools/agent/shared.d.ts

@@ -1,3 +1,4 @@
+import { checkAttestor } from '../../../proof/check-attestor.ts';
 import type { RegisteredTool } from '../../server.ts';
 import type { CaptureStore } from './capture.ts';
 /** The shared authoring tools mapped to the MCP's shape: resolve each call's
@@ -5,4 +6,4 @@ import type { CaptureStore } from './capture.ts';
  *  takes `captureId`; `run_proof` also gets the credential-aware contract. The
  *  tools are authored plain in `../../../authoring`; this only wraps them with
  *  `extendTool` (handlers untouched — loose arg parse keeps `captureId`). */
-export declare function sharedAuthoringTools(captures: CaptureStore): RegisteredTool[];
+export declare function sharedAuthoringTools(captures: CaptureStore, check?: typeof checkAttestor): RegisteredTool[];

package/lib/mcp/tools/agent/shared.js

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

package/lib/mcp/tools/agent/start-integration.d.ts

@@ -0,0 +1,15 @@
+import { type RegisteredTool } from '../../server.ts';
+interface StartIntegrationArgs {
+    goal: string;
+    orgId?: string;
+    providerIds?: string[];
+}
+/**
+ * Returns the plan a coding agent follows to add Reclaim verification to the
+ * developer's app, from sign-in to a tested Verify button. The plan lives in
+ * `skill/start-integration.md`; this tool fills in the inputs.
+ */
+export declare function startIntegrationTool(): RegisteredTool;
+/** Fill the plan template. Exported for tests. */
+export declare function renderStartIntegration(args: StartIntegrationArgs): string;
+export {};

package/lib/mcp/tools/agent/start-integration.js

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

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

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

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

@@ -1,6 +1,7 @@
 import { authenticateTool } from "./authenticate.js";
 import { importTool } from "./import.js";
 import { issueTool } from "./issue.js";
+import { issueOrgTokenTool } from "./issue-org-token.js";
 import { resolveOwnerKeyTool } from "./resolve-owner-key.js";
 /**
  * Local-only key tools — no backend client needed. These manage the eth
@@ -23,6 +24,7 @@ export function buildLocalCredentialTools() {
 export function buildCredentialTools(client) {
     return [
         authenticateTool(client),
+        issueOrgTokenTool(client),
         ...buildLocalCredentialTools(),
     ];
 }

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

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

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

@@ -19,6 +19,14 @@ export declare function normalizeEthHex(value: string): string;
  * ask for one (see `resolve_owner_key`).
  */
 export declare function resolveEthKey(projectDir?: string): ResolvedEthKey | undefined;
+/** Append `entry` to the project `.gitignore` if not already present. */
+export declare function ensureGitignored(projectDir: string, entry: string): void;
+/**
+ * Set `name=value` in a dotenv file, replacing an existing line or appending
+ * one. Writes with mode 0600 and adds the file to the project `.gitignore`.
+ * `envFile` is relative to `projectDir`.
+ */
+export declare function upsertEnvVar(projectDir: string, envFile: string, name: string, value: string): string;
 /**
  * Persist a raw eth private key to the project `.env` as
  * `RECLAIM_PRIVATE_KEY=0x…` (upsert; mode 0600; `.env` added to `.gitignore`).

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

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