@reclaimprotocol/agent 0.1.0 → 0.1.1

package/lib/mcp/tools/analyze.js

@@ -0,0 +1,26 @@
+import { detectConcerns } from "../../provider/constraints.js";
+import { defineTool } from "../server.js";
+export function analyzeTool(captures) {
+    return defineTool({
+        name: 'analyze_request_constraints',
+        description: 'Flag potential provider-authoring concerns for a captured request.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                captureId: { type: 'string' },
+                requestId: { type: 'string' },
+            },
+            required: ['captureId', 'requestId'],
+        },
+    }, async ({ captureId, requestId }) => {
+        const session = captures.sessions.get(captureId);
+        if (!session) {
+            throw new Error(`no capture ${captureId}`);
+        }
+        const r = session.requests.get(requestId);
+        if (!r) {
+            throw new Error(`no request ${requestId} in capture ${captureId}`);
+        }
+        return { concerns: detectConcerns(r) };
+    });
+}

package/lib/mcp/tools/attach.d.ts

@@ -0,0 +1,11 @@
+import { type CdpHandles } from '../../cdp/client.ts';
+import type { ConfigStore } from '../../config/store.ts';
+import { type RegisteredTool } from '../server.ts';
+export interface AttachState {
+    handles: CdpHandles;
+    port: number;
+}
+export declare function attachTool(state: {
+    current?: AttachState;
+    config: ConfigStore;
+}): RegisteredTool;

package/lib/mcp/tools/attach.js

@@ -0,0 +1,72 @@
+import { connectCdp } from "../../cdp/client.js";
+import { defaultProfileDir, launchChrome, waitForCdpReady, } from "../../cdp/launcher.js";
+import { defaultConfigPath } from "../../config/store.js";
+import { defineTool } from "../server.js";
+export function attachTool(state) {
+    return defineTool({
+        name: 'attach_chrome',
+        description: 'Attach to a Chrome instance via CDP. ' +
+            'Auto-launches a dedicated-profile Chrome ' +
+            'on first call if no attachMode is persisted. ' +
+            'Persists the chosen mode in ~/.reclaim/config.json.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                attachMode: { type: 'string', enum: ['dedicated', 'attach'] },
+                port: { type: 'number' },
+            },
+        },
+    }, async (parsed) => {
+        let cfg = state.config.read();
+        if (parsed.attachMode || parsed.port) {
+            cfg = {
+                attachMode: parsed.attachMode ?? cfg?.attachMode ?? 'dedicated',
+                port: parsed.port ?? cfg?.port ?? 9222,
+            };
+            state.config.write(cfg);
+        }
+        if (!cfg) {
+            return {
+                needsChoice: true,
+                message: 'First-run: choose attach mode. ' +
+                    'Call attach_chrome again with attachMode="dedicated" ' +
+                    '(auto-launch a Chrome profile under ~/.reclaim/chrome-profile) ' +
+                    'or attachMode="attach" ' +
+                    '(connect to a Chrome you launched yourself with ' +
+                    'BOTH --remote-debugging-port=9222 AND ' +
+                    '--user-data-dir=<some-non-default-path>; ' +
+                    'since Chrome 136 the debug-port flag is silently ' +
+                    'ignored if the default profile is in use).',
+                configPath: defaultConfigPath(),
+            };
+        }
+        if (cfg.attachMode === 'dedicated') {
+            try {
+                await waitForCdpReady(cfg.port, 500);
+            }
+            catch {
+                launchChrome({ port: cfg.port, profileDir: defaultProfileDir() });
+                await waitForCdpReady(cfg.port, 10_000);
+            }
+        }
+        else {
+            await waitForCdpReady(cfg.port, 2_000).catch(() => {
+                throw new Error(`attach mode: nothing answering CDP on port ${cfg.port}. ` +
+                    'Chrome must be launched with BOTH ' +
+                    `--remote-debugging-port=${cfg.port} AND ` +
+                    '--user-data-dir=<some-non-default-path>. ' +
+                    'Since Chrome 136 (May 2025), the debug-port flag is ' +
+                    'silently ignored when the default ' +
+                    "user profile is in use — that's why nothing opens the port. " +
+                    'Either re-launch Chrome with ' +
+                    'a custom --user-data-dir, or switch to attachMode="dedicated".');
+            });
+        }
+        if (state.current) {
+            await state.current.handles.close().catch(() => { });
+        }
+        const handles = await connectCdp(cfg.port);
+        state.current = { handles, port: cfg.port };
+        return { attached: true, port: cfg.port, mode: cfg.attachMode };
+    });
+}

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

@@ -0,0 +1,107 @@
+import { defineTool } from "../../server.js";
+import { writeSession } from "./session-cache.js";
+export function authenticateTool(client) {
+    return defineTool({
+        name: 'reclaim_authenticate',
+        description: 'Authorize the CLI / MCP to make authenticated API calls by having ' +
+            'the user sign in on the dashboard. Two steps:\n\n' +
+            'Step 1 — call with no arguments. Returns a `code` and `attachUrl`. ' +
+            'Tell the user to open the URL, sign in, and authorize.\n\n' +
+            'Step 2 — once the user says they have authorized, call again ' +
+            'with the same `code` from step 1 to check if confirmed. ' +
+            'Returns `LINKED` with a 2-day bearer token when confirmed, ' +
+            '`PENDING` if not yet, or `EXPIRED` if too long has passed.\n\n' +
+            'The token is cached in ~/.reclaim/config.json automatically.\n\n' +
+            'This bearer token authenticates dashboard/org-management calls ' +
+            '(e.g. list_orgs, issuing an org secret). Programmatic verification ' +
+            'calls use a separate org secret (rorg_…, set as RECLAIM_ORG_SECRET).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                code: {
+                    type: 'string',
+                    pattern: '^[A-HJ-NP-Z2-9]{5}$',
+                    description: '5-character code from a previous step-1 call. ' +
+                        'When provided, checks whether the user has ' +
+                        'confirmed that session instead of opening a new one.',
+                },
+            },
+        },
+    }, async (args) => {
+        // Step 2: check an existing session
+        if (args.code) {
+            return checkSession(client, args.code);
+        }
+        // Step 1: open a new auth-only session
+        const sessionResult = (await client.call('CreateAttachSession'));
+        const session = sessionResult.data;
+        return {
+            status: 'PENDING',
+            code: session.code,
+            attachUrl: session.attachUrl,
+            expiresAt: session.expiresAt,
+            instructions: `Open ${session.attachUrl} in your browser, sign in, and click ` +
+                '"Authorize this device". ' +
+                'Once done, call authenticate again with code: ' +
+                `"${session.code}" to confirm.`,
+        };
+    });
+}
+async function checkSession(client, code) {
+    let session;
+    try {
+        const sessionResult = (await client.call('GetAttachSession', {
+            params: { code }
+        }));
+        session = sessionResult.data;
+    }
+    catch (err) {
+        const status = err.status;
+        if (status === 404) {
+            return {
+                status: 'NOT_FOUND',
+                hint: 'Session not found — it may have expired (15-min window). ' +
+                    'Call authenticate without a code to start a new session.',
+            };
+        }
+        throw new Error(`Failed to check session: ${err.message}`);
+    }
+    if (session.status === 'LINKED') {
+        const token = session.token?.trim();
+        if (token) {
+            writeSession({
+                token,
+                expiresAt: new Date(Date.now() + 2 * 24 * 60 * 60 * 1000).toISOString(),
+            });
+            client.setToken(token);
+            return {
+                status: 'LINKED',
+                token,
+                note: 'Token cached in ~/.reclaim/config.json and active now.',
+            };
+        }
+        return {
+            status: 'LINKED_NO_TOKEN',
+            hint: 'Session confirmed but no token issued. ' +
+                'Restart the backend (npm run dev) and try again.',
+        };
+    }
+    if (session.status === 'EXPIRED') {
+        return {
+            status: 'EXPIRED',
+            hint: 'Session expired (15-min window passed). ' +
+                'Call authenticate without a code to start a new session.',
+        };
+    }
+    // Still PENDING
+    return {
+        status: 'PENDING',
+        code: session.code,
+        attachUrl: session.attachUrl,
+        hint: 'Session is still waiting. ' +
+            `Make sure you opened ${session.attachUrl}, ` +
+            'signed in, and clicked "Authorize this device". ' +
+            `Call authenticate again with code: "${session.code}"` +
+            ' once you have done so.',
+    };
+}

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

@@ -0,0 +1,15 @@
+import type { ReclaimClient } from '@reclaimprotocol/client';
+import type { RegisteredTool } from '../../server.ts';
+/**
+ * Local-only key tools — no backend client needed. These manage the eth
+ * proof-owner key entirely on disk (as a secp256k1 PEM) or via env: generate,
+ * import, and resolve which key to sign proofs with. No `~/.reclaim` caching;
+ * useful in BOTH builder and OLD-devtools mode.
+ */
+export 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.
+ */
+export declare function buildCredentialTools(client: ReclaimClient): RegisteredTool[];

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

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

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

@@ -0,0 +1,32 @@
+/**
+ * Optional X25519 decryption key — only needed when testing ENCRYPTED callback
+ * payloads in the consumer role. Resolution is file-only (no env var, no path
+ * override, no `~/.reclaim` caching):
+ *
+ *   1. An X25519 PKCS#8 PEM file named `reclaim-decrypt.pem` in the project
+ *      root. Mint it with openssl:
+ *
+ *        openssl genpkey -algorithm X25519 -out reclaim-decrypt.pem
+ *
+ *   2. Absent — plaintext-only testing (no decryption key; encrypted
+ *      deliveries surface a clear error).
+ *
+ * The PEM *content* is loaded via the client's `loadDecryptionKey` (jose
+ * `ECDH-ES`) and passed straight through as `ReclaimConfig.credential` / to
+ * `decryptCallback`.
+ */
+import { type DecryptionKey } from '@reclaimprotocol/client';
+/** Default X25519 PEM filename the agent looks for in the project root. */
+export declare const DEFAULT_DECRYPT_PEM = "reclaim-decrypt.pem";
+/** Resolve the decrypt-PEM path (the default file in the project root). */
+export declare function decryptPemPath(projectDir?: string): string;
+/**
+ * Read the raw decryption-key PEM string from the default file, without loading
+ * it. Returns `undefined` when the file is absent (plaintext-only).
+ */
+export declare function resolveDecryptKeyInput(projectDir?: string): string | undefined;
+/**
+ * Load the optional decryption key. Returns `undefined` when the PEM file is
+ * absent (the consumer then handles only plaintext deliveries).
+ */
+export declare function resolveDecryptionKey(projectDir?: string): Promise<DecryptionKey | undefined>;

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

@@ -0,0 +1,49 @@
+/**
+ * Optional X25519 decryption key — only needed when testing ENCRYPTED callback
+ * payloads in the consumer role. Resolution is file-only (no env var, no path
+ * override, no `~/.reclaim` caching):
+ *
+ *   1. An X25519 PKCS#8 PEM file named `reclaim-decrypt.pem` in the project
+ *      root. Mint it with openssl:
+ *
+ *        openssl genpkey -algorithm X25519 -out reclaim-decrypt.pem
+ *
+ *   2. Absent — plaintext-only testing (no decryption key; encrypted
+ *      deliveries surface a clear error).
+ *
+ * The PEM *content* is loaded via the client's `loadDecryptionKey` (jose
+ * `ECDH-ES`) and passed straight through as `ReclaimConfig.credential` / to
+ * `decryptCallback`.
+ */
+import { loadDecryptionKey, } from '@reclaimprotocol/client';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { findProjectRoot } from "../../../paths.js";
+/** Default X25519 PEM filename the agent looks for in the project root. */
+export const DEFAULT_DECRYPT_PEM = 'reclaim-decrypt.pem';
+/** Resolve the decrypt-PEM path (the default file in the project root). */
+export function decryptPemPath(projectDir = findProjectRoot(process.cwd())) {
+    return join(projectDir, DEFAULT_DECRYPT_PEM);
+}
+/**
+ * Read the raw decryption-key PEM string from the default file, without loading
+ * it. Returns `undefined` when the file is absent (plaintext-only).
+ */
+export function resolveDecryptKeyInput(projectDir = findProjectRoot(process.cwd())) {
+    const pemPath = decryptPemPath(projectDir);
+    if (existsSync(pemPath)) {
+        return readFileSync(pemPath, 'utf8');
+    }
+    return undefined;
+}
+/**
+ * Load the optional decryption key. Returns `undefined` when the PEM file is
+ * absent (the consumer then handles only plaintext deliveries).
+ */
+export async function resolveDecryptionKey(projectDir = findProjectRoot(process.cwd())) {
+    const input = resolveDecryptKeyInput(projectDir);
+    if (input === undefined) {
+        return undefined;
+    }
+    return loadDecryptionKey(input);
+}

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

@@ -0,0 +1,38 @@
+/** 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';
+export type ResolvedEthKey = {
+    /** Raw 0x-hex 32-byte scalar. */
+    privateKey: string;
+    /** Lowercase eth address derived from the scalar. */
+    address: string;
+    source: EthKeySource;
+    /** Absolute path the key was read from (for `dotenv` / `file` sources). */
+    path?: string;
+};
+/** Validate + normalize a raw Ethereum private key to lowercase 0x-hex. */
+export declare function normalizeEthHex(value: string): string;
+/** The explicit raw-hex key-file path, if `RECLAIM_PRIVATE_KEY_FILE` is set. */
+export declare function ethKeyFilePath(projectDir?: 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 private key (0x-hex) or throw a clear, actionable
+ * error. Used by the proof flow that can't proceed without a signing key.
+ */
+export declare function requireEthPrivateKey(projectDir?: string): string;
+/**
+ * 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 declare function writeEthKey(privateKeyHex: string, projectDir?: string): {
+    path: string;
+    address: string;
+};

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

@@ -0,0 +1,130 @@
+/**
+ * Eth proof-owner key resolution — the raw secp256k1 private key passed to
+ * attestor-core when the agent creates a local claim. It's a plain 0x-hex
+ * Ethereum private key (no PEM), resolved from, in order:
+ *
+ *   1. `process.env.RECLAIM_PRIVATE_KEY` — a 0x-hex 32-byte scalar.
+ *   2. A `.env` file in the project root — its `RECLAIM_PRIVATE_KEY=0x…` line.
+ *   3. A key file holding the raw 0x-hex scalar, at `RECLAIM_PRIVATE_KEY_FILE`
+ *      (absolute or project-relative).
+ *   4. Absent — the caller offers to generate one or asks the dev for a key.
+ *
+ * Generated/imported keys are written to the project `.env` (mode 0600, and the
+ * file is added to `.gitignore`). NO `~/.reclaim` caching. This is a LOCAL
+ * signing key only — unrelated to org auth (the org secret) or encryption
+ * (the X25519 decrypt key).
+ */
+import { deriveFromPrivateKey } from '@reclaimprotocol/client';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+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';
+/** Validate + normalize a raw Ethereum private key to lowercase 0x-hex. */
+export function normalizeEthHex(value) {
+    const v = value.trim().replace(/^['"]|['"]$/g, '');
+    if (!/^(0x)?[0-9a-fA-F]{64}$/.test(v)) {
+        throw new Error('not a valid Ethereum private key (expected a 32-byte / 64-hex scalar)');
+    }
+    return '0x' + v.replace(/^0x/, '').toLowerCase();
+}
+/** Read `RECLAIM_PRIVATE_KEY` from a dotenv file (simple KEY=VALUE parse). */
+function readDotenvKey(path) {
+    if (!existsSync(path)) {
+        return undefined;
+    }
+    for (const line of readFileSync(path, 'utf8').split('\n')) {
+        const m = line.match(/^\s*RECLAIM_PRIVATE_KEY\s*=\s*(.+?)\s*$/);
+        if (m) {
+            return m[1];
+        }
+    }
+    return undefined;
+}
+/** The explicit raw-hex key-file path, if `RECLAIM_PRIVATE_KEY_FILE` is set. */
+export function ethKeyFilePath(projectDir = findProjectRoot(process.cwd())) {
+    const p = process.env.RECLAIM_PRIVATE_KEY_FILE;
+    if (!p) {
+        return undefined;
+    }
+    return isAbsolute(p) ? p : join(projectDir, p);
+}
+function resolved(privateKey, source, path) {
+    return {
+        privateKey,
+        address: deriveFromPrivateKey(privateKey).address,
+        source,
+        ...(path ? { path } : {}),
+    };
+}
+/**
+ * Resolve the eth proof-owner key without prompting. Returns `undefined` when
+ * no key is configured anywhere — the caller decides whether to generate or
+ * ask for one (see `resolve_owner_key`).
+ */
+export function resolveEthKey(projectDir = findProjectRoot(process.cwd())) {
+    const env = process.env.RECLAIM_PRIVATE_KEY;
+    if (env?.trim()) {
+        return resolved(normalizeEthHex(env), 'env');
+    }
+    const envPath = join(projectDir, ENV_FILE);
+    const fromDotenv = readDotenvKey(envPath);
+    if (fromDotenv) {
+        return resolved(normalizeEthHex(fromDotenv), 'dotenv', envPath);
+    }
+    const keyFile = ethKeyFilePath(projectDir);
+    if (keyFile && existsSync(keyFile)) {
+        return resolved(normalizeEthHex(readFileSync(keyFile, 'utf8')), 'file', keyFile);
+    }
+    return undefined;
+}
+/**
+ * Resolve the eth proof-owner private key (0x-hex) or throw a clear, actionable
+ * error. Used by the proof flow that can't proceed without a signing key.
+ */
+export function requireEthPrivateKey(projectDir = findProjectRoot(process.cwd())) {
+    const r = resolveEthKey(projectDir);
+    if (!r) {
+        throw new Error('No eth proof-owner key found. Set RECLAIM_PRIVATE_KEY (0x-hex), add a '
+            + `RECLAIM_PRIVATE_KEY=0x… line to ${join(projectDir, ENV_FILE)}, or `
+            + 'point RECLAIM_PRIVATE_KEY_FILE at a file holding the raw hex. Run '
+            + 'issue_credentials to generate one, or import_credentials to use a '
+            + 'key you already hold.');
+    }
+    return r.privateKey;
+}
+/** Append `entry` to the project `.gitignore` if not already present. */
+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)) {
+        return;
+    }
+    const prefix = current && !current.endsWith('\n') ? '\n' : '';
+    writeFileSync(path, current + prefix + entry + '\n');
+}
+/**
+ * Persist a raw eth private key to the project `.env` as
+ * `RECLAIM_PRIVATE_KEY=0x…` (upsert; mode 0600; `.env` added to `.gitignore`).
+ * Used by `issue_credentials` (generate) and `import_credentials` (supplied
+ * hex). Returns the derived address and the `.env` path.
+ */
+export function writeEthKey(privateKeyHex, projectDir = findProjectRoot(process.cwd())) {
+    const hex = normalizeEthHex(privateKeyHex);
+    const envPath = join(projectDir, ENV_FILE);
+    const line = `${ENV_VAR}=${hex}`;
+    const existing = existsSync(envPath) ? readFileSync(envPath, 'utf8') : '';
+    const re = new RegExp(`^\\s*${ENV_VAR}\\s*=.*$`, 'm');
+    let next;
+    if (re.test(existing)) {
+        next = existing.replace(re, line);
+    }
+    else {
+        const prefix = existing && !existing.endsWith('\n') ? '\n' : '';
+        next = existing + prefix + line + '\n';
+    }
+    writeFileSync(envPath, next, { mode: 0o600 });
+    ensureGitignored(projectDir, ENV_FILE);
+    return { path: envPath, address: deriveFromPrivateKey(hex).address };
+}

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

@@ -0,0 +1,57 @@
+import { readFileSync } from 'node:fs';
+import { findProjectRoot } from "../../../paths.js";
+import { defineTool } from "../../server.js";
+import { writeEthKey } from "./eth-key.js";
+export function importTool() {
+    return defineTool({
+        name: 'import_credentials',
+        description: 'Import an eth proof-owner key the dev already holds and persist it ' +
+            'to the project `.env` as RECLAIM_PRIVATE_KEY=0x… (mode 0600; `.env` ' +
+            'added to .gitignore). Provide EITHER `privateKey` (raw 0x-hex, 64 ' +
+            'chars) OR `keyFile` (path to a file holding the raw 0x-hex key). ' +
+            'The address is derived locally; the private key is never ' +
+            'returned. This is a local signing key only (not registered ' +
+            'with any server, ' +
+            'unrelated to org auth or encryption).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                privateKey: {
+                    type: 'string',
+                    pattern: '^0x?[0-9a-fA-F]{64}$',
+                    description: 'Raw Ethereum private key, 0x-prefixed hex (64 hex chars).',
+                },
+                keyFile: {
+                    type: 'string',
+                    description: 'Path to a file containing the raw 0x-hex private key ' +
+                        '(absolute or project-relative).',
+                },
+                projectDir: {
+                    type: 'string',
+                    description: 'Project directory whose `.env` the key is written to. ' +
+                        'Defaults to the closest ancestor of cwd containing .git or ' +
+                        'package.json.',
+                },
+            },
+        },
+    }, async (args) => {
+        if (!args.privateKey && !args.keyFile) {
+            throw new Error('Provide either `privateKey` (0x-hex) or `keyFile`.');
+        }
+        if (args.privateKey && args.keyFile) {
+            throw new Error('Provide only one of `privateKey` or `keyFile`.');
+        }
+        const projectDir = findProjectRoot(args.projectDir || process.cwd());
+        const privateKeyHex = args.keyFile
+            ? readFileSync(args.keyFile, 'utf8')
+            : args.privateKey;
+        const { path, address } = writeEthKey(privateKeyHex, projectDir);
+        return {
+            address,
+            path,
+            note: 'Eth proof-owner key written to .env as RECLAIM_PRIVATE_KEY ' +
+                '(mode 0600). resolve_owner_key resolves it from .env. Keep .env ' +
+                'secret — it has been added to .gitignore.',
+        };
+    });
+}

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

@@ -0,0 +1,2 @@
+export { buildCredentialTools, buildLocalCredentialTools } from './build.ts';
+export { readSession } from './session-cache.ts';

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

@@ -0,0 +1,4 @@
+// Barrel for the credential tool group: local eth proof-owner key (env/PEM)
+// and the org-token-authenticated builder tools. Import from here.
+export { buildCredentialTools, buildLocalCredentialTools } from "./build.js";
+export { readSession } from "./session-cache.js";

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

@@ -0,0 +1,42 @@
+import { generateKeypair } from '@reclaimprotocol/client';
+import { findProjectRoot } from "../../../paths.js";
+import { defineTool } from "../../server.js";
+import { writeEthKey } from "./eth-key.js";
+export function issueTool() {
+    return defineTool({
+        name: 'issue_credentials',
+        description: 'Generate a fresh secp256k1 eth proof-owner key-pair (the key ' +
+            'that signs local claim creation) and write the raw private key to ' +
+            'the project `.env` as RECLAIM_PRIVATE_KEY=0x… (mode 0600; `.env` ' +
+            'added to .gitignore). This is a LOCAL signing key only — it is NOT ' +
+            'registered with any server and is unrelated to org auth (the org ' +
+            'secret) or encryption (the X25519 decrypt key). ALWAYS confirm with ' +
+            'the dev before generating a new key. After writing, run_proof picks ' +
+            'it up automatically via resolve_owner_key. The private key is never ' +
+            'returned in the response.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                projectDir: {
+                    type: 'string',
+                    description: 'Project directory whose `.env` the key is written to. ' +
+                        'Defaults to the closest ancestor of cwd containing .git or ' +
+                        'package.json.',
+                },
+            },
+        },
+    }, async (args) => {
+        const projectDir = findProjectRoot(args.projectDir || process.cwd());
+        const keypair = generateKeypair();
+        const { path, address } = writeEthKey(keypair.privateKey, projectDir);
+        return {
+            address,
+            path,
+            note: 'Eth proof-owner key written to .env as RECLAIM_PRIVATE_KEY ' +
+                '(mode 0600); the private key is NOT in this response on purpose. ' +
+                'resolve_owner_key will now resolve it from .env (or set ' +
+                'RECLAIM_PRIVATE_KEY in the environment to override). Keep .env ' +
+                'secret — it has been added to .gitignore.',
+        };
+    });
+}

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

@@ -0,0 +1,13 @@
+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:
+ *   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.
+ * Never returns the private key — only the derived address.
+ */
+export declare function resolveOwnerKeyTool(): RegisteredTool;