@reclaimprotocol/agent 0.1.0-dev.1

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

@@ -0,0 +1,46 @@
+import { replayProvider } from "../../../proof/replay.js";
+import { defineTool } from "../../server.js";
+export function replayTool(secrets) {
+    return defineTool({
+        name: 'replay_request',
+        description: 'Replay a drafted provider against the live endpoint ' +
+            'using Node fetch (no attestor). ' +
+            'Pre-flight gate before run_proof — ' +
+            'diagnoses CSRF / token-rotation / matcher-too-tight ' +
+            'issues with richer hints than the attestor would produce.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                // `type: 'object'` is required so MCP clients (the LLM)
+                // serialize the value as an object, not a JSON-stringified
+                // string. `properties: {}` is required so zod-from-json-schema
+                // compiles to a passthrough instead of strict-strip — leaving
+                // it off makes the server receive `{}`.
+                provider: { type: 'object', properties: {} },
+                secretParamsRef: { type: 'string' },
+            },
+            required: ['provider'],
+        },
+    }, async ({ provider, secretParamsRef }) => {
+        let resolved = {};
+        if (secretParamsRef !== undefined) {
+            const r = secrets.resolve(secretParamsRef);
+            if (!r) {
+                throw new Error(`unknown secretParamsRef "${secretParamsRef}" — ` +
+                    'the MCP server has restarted or reset_session was called. ' +
+                    'Re-run propose_provider to mint a fresh ref.');
+            }
+            resolved = r;
+        }
+        const result = await replayProvider(provider, resolved);
+        const out = {
+            status: result.status,
+            matchesOriginal: result.matchesOriginal,
+            bodySnippet: result.body.slice(0, 256),
+        };
+        if (result.hints !== undefined) {
+            out.hints = result.hints;
+        }
+        return out;
+    });
+}

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

@@ -0,0 +1,10 @@
+import type { ConfigStore } from '../../../config/store.ts';
+import { type RegisteredTool } from '../../server.ts';
+import type { AttachState } from './attach.ts';
+import type { CaptureStore } from './capture.ts';
+export declare function sessionTools(attachRef: {
+    current?: AttachState;
+    config: ConfigStore;
+}, captures: CaptureStore, secrets: {
+    clear: () => void;
+}): RegisteredTool[];

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

@@ -0,0 +1,29 @@
+import { defineTool } from "../../server.js";
+export function sessionTools(attachRef, captures, secrets) {
+    return [
+        defineTool({
+            name: 'get_session',
+            description: 'Return current attach state, active captures, and persisted config.',
+            inputSchema: { type: 'object', properties: {} },
+        }, async () => ({
+            config: attachRef.config.read()?.browser_agent,
+            attached: Boolean(attachRef.current),
+            port: attachRef.current?.port,
+            captures: [...captures.sessions.keys()],
+            activeTab: captures.activeTab,
+        })),
+        defineTool({
+            name: 'reset_session',
+            description: 'Stop all captures, drop in-memory secrets, and clear capture state.',
+            inputSchema: { type: 'object', properties: {} },
+        }, async () => {
+            for (const s of captures.sessions.values()) {
+                await s.stop().catch(() => { });
+            }
+            captures.sessions.clear();
+            delete captures.activeTab;
+            secrets.clear();
+            return { reset: true };
+        }),
+    ];
+}

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

@@ -0,0 +1,3 @@
+import type { ReclaimClient } from '@reclaimprotocol/client';
+import { type RegisteredTool } from '../../server.ts';
+export declare function authenticateTool(client: ReclaimClient): RegisteredTool;

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

@@ -0,0 +1,108 @@
+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' +
+            'To then link a credential to an org (needed only to use it ' +
+            'for verification in production), use the token with the ' +
+            'generated tools: `list_orgs` → `link_credential` with the ' +
+            "credential's `address` and the target `orgId`.",
+        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/credentials/build.d.ts

@@ -0,0 +1,16 @@
+import type { ReclaimClient } from '@reclaimprotocol/client';
+import type { RegisteredTool } from '../../server.ts';
+/**
+ * Local-only credential tools — no backend client needed. These manage app
+ * key-pairs entirely on disk / in the env (mint, import, list, resolve which
+ * key to sign proofs with), so they are useful in BOTH builder and
+ * OLD-devtools mode.
+ */
+export declare function buildLocalCredentialTools(): RegisteredTool[];
+/**
+ * Full builder-mode credential set: the local tools plus the two that talk to
+ * the builder backend (`reclaim_authenticate` device-code flow,
+ * `reclaim_status`). Old mode does NOT use these — it has its own
+ * authenticate and no credential-status analog.
+ */
+export declare function buildCredentialTools(client: ReclaimClient): RegisteredTool[];

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

@@ -0,0 +1,33 @@
+import { authenticateTool } from "./authenticate.js";
+import { importTool } from "./import.js";
+import { issueTool } from "./issue.js";
+import { listCachedTool } from "./list-cached.js";
+import { resolveOwnerKeyTool } from "./resolve-owner-key.js";
+import { statusTool } from "./status.js";
+/**
+ * Local-only credential tools — no backend client needed. These manage app
+ * key-pairs entirely on disk / in the env (mint, import, list, resolve which
+ * key to sign proofs with), so they are useful in BOTH builder and
+ * OLD-devtools mode.
+ */
+export function buildLocalCredentialTools() {
+    return [
+        listCachedTool(),
+        resolveOwnerKeyTool(),
+        issueTool(),
+        importTool(),
+    ];
+}
+/**
+ * Full builder-mode credential set: the local tools plus the two that talk to
+ * the builder backend (`reclaim_authenticate` device-code flow,
+ * `reclaim_status`). Old mode does NOT use these — it has its own
+ * authenticate and no credential-status analog.
+ */
+export function buildCredentialTools(client) {
+    return [
+        authenticateTool(client),
+        statusTool(client),
+        ...buildLocalCredentialTools(),
+    ];
+}

package/lib/mcp/tools/credentials/cache.d.ts

@@ -0,0 +1,70 @@
+export type CachedCredential = {
+    address: string;
+    privateKey: string;
+    label?: string;
+    orgId?: string;
+    createdAt: string;
+    /** Project dir where this credential was first created. */
+    createdIn: string;
+    /** All project dirs this credential has been used in ("used by"). */
+    projectDirs: string[];
+};
+type CacheFile = {
+    version: 1;
+    credentials: CachedCredential[];
+};
+/**
+ * Read the `credentials` section of the unified config. Returns an empty
+ * doc if missing or malformed — we'd rather lose the cache than crash the
+ * CLI on a corrupted file the user can re-create.
+ */
+export declare function readCredentialsFromCache(): CacheFile;
+/**
+ * Persist the `credentials` section, merging into the unified config so
+ * other sections (browser_agent, session) survive untouched. We rewrite
+ * the whole list each save; it's tiny and the alternative (append-only)
+ * loses our ability to deduplicate `projectDirs`.
+ */
+export declare function writeCache(doc: CacheFile): void;
+/**
+ * Upsert a credential entry. If a row already exists for `address`,
+ * we merge the new `projectDirs` into the existing list, refresh
+ * mutable fields, and keep the original `createdAt` / `createdIn`
+ * (backfilling `createdIn` from the new entry when an old row lacks it).
+ */
+export declare function upsertCredential(entry: CachedCredential): CachedCredential;
+/** Look up a cached credential by address. Case-insensitive. */
+export declare function findCredentialFromCachedBy(address: string): CachedCredential | undefined;
+export type SuggestionReason = 'createdIn' | 'usedIn' | 'newest';
+export type CredentialSuggestion = {
+    credential: CachedCredential;
+    reason: SuggestionReason;
+};
+/**
+ * Pick the best cached credential for `dir`. Ranking tiers:
+ *   1. created in `dir`           (reason: 'createdIn')
+ *   2. previously used in `dir`   (reason: 'usedIn')
+ *   3. most recently created      (reason: 'newest')
+ * Within every tier, newest `createdAt` wins; address ascending is the
+ * final deterministic tie-break. Returns undefined only on an empty cache.
+ *
+ * Pass a pre-read `creds` array to avoid a redundant `readCache()` (and to
+ * rank against the same snapshot the caller already holds).
+ */
+export declare function suggestCredentialForDir(dir: string, creds?: CachedCredential[]): CredentialSuggestion | undefined;
+/**
+ * Resolve the private key to sign attestor proofs with (the claim
+ * "owner"). Reuses the app credential rather than a dedicated key — for
+ * build-time test proofs the developer is both the app and the proof
+ * owner, and the owner identity is immaterial to whether the provider's
+ * matching works.
+ *
+ * The owner is chosen up front (see the `resolve_owner_key` tool) and
+ * passed by `address`; this just fetches the matching private key:
+ *   - the `RECLAIM_PRIVATE_KEY` env / project `.env` key, if it derives
+ *     to `address` (the dev pinned it), else
+ *   - the cached credential with that address.
+ * Returns undefined when no key for `address` is known.
+ */
+export declare function resolveOwnerPrivateKey(address: string): string | undefined;
+export {};

package/lib/mcp/tools/credentials/cache.js

@@ -0,0 +1,114 @@
+import { deriveFromPrivateKey } from '@reclaimprotocol/client';
+import { ConfigStore } from "../../../config/store.js";
+import { findProjectRoot } from "../../../paths.js";
+import { readPrivateKeyFromEnvFile } from "./env-file.js";
+const EMPTY = { version: 1, credentials: [] };
+/**
+ * Read the `credentials` section of the unified config. Returns an empty
+ * doc if missing or malformed — we'd rather lose the cache than crash the
+ * CLI on a corrupted file the user can re-create.
+ */
+export function readCredentialsFromCache() {
+    const creds = new ConfigStore().read()?.credentials;
+    if (!Array.isArray(creds)) {
+        return { ...EMPTY };
+    }
+    return { version: 1, credentials: creds };
+}
+/**
+ * Persist the `credentials` section, merging into the unified config so
+ * other sections (browser_agent, session) survive untouched. We rewrite
+ * the whole list each save; it's tiny and the alternative (append-only)
+ * loses our ability to deduplicate `projectDirs`.
+ */
+export function writeCache(doc) {
+    new ConfigStore().write({ credentials: doc.credentials });
+}
+/**
+ * Upsert a credential entry. If a row already exists for `address`,
+ * we merge the new `projectDirs` into the existing list, refresh
+ * mutable fields, and keep the original `createdAt` / `createdIn`
+ * (backfilling `createdIn` from the new entry when an old row lacks it).
+ */
+export function upsertCredential(entry) {
+    const doc = readCredentialsFromCache();
+    const idx = doc.credentials.findIndex((c) => c.address === entry.address.toLowerCase());
+    const merged = {
+        ...entry,
+        address: entry.address.toLowerCase(),
+        projectDirs: Array.from(new Set([
+            ...(doc.credentials[idx]?.projectDirs ?? []),
+            ...entry.projectDirs,
+        ])),
+        createdAt: doc.credentials[idx]?.createdAt ?? entry.createdAt,
+        createdIn: doc.credentials[idx]?.createdIn ?? entry.createdIn,
+    };
+    if (idx >= 0) {
+        doc.credentials[idx] = merged;
+    }
+    else {
+        doc.credentials.unshift(merged);
+    }
+    writeCache(doc);
+    return merged;
+}
+/** Look up a cached credential by address. Case-insensitive. */
+export function findCredentialFromCachedBy(address) {
+    const doc = readCredentialsFromCache();
+    const lc = address.toLowerCase();
+    return doc.credentials.find((c) => c.address === lc);
+}
+/**
+ * Pick the best cached credential for `dir`. Ranking tiers:
+ *   1. created in `dir`           (reason: 'createdIn')
+ *   2. previously used in `dir`   (reason: 'usedIn')
+ *   3. most recently created      (reason: 'newest')
+ * Within every tier, newest `createdAt` wins; address ascending is the
+ * final deterministic tie-break. Returns undefined only on an empty cache.
+ *
+ * Pass a pre-read `creds` array to avoid a redundant `readCache()` (and to
+ * rank against the same snapshot the caller already holds).
+ */
+export function suggestCredentialForDir(dir, creds = readCredentialsFromCache().credentials) {
+    if (creds.length === 0) {
+        return undefined;
+    }
+    const byNewest = (a, b) => {
+        return (b.createdAt ?? '').localeCompare(a.createdAt ?? '') ||
+            a.address.localeCompare(b.address);
+    };
+    const createdHere = creds.filter((c) => c.createdIn === dir).sort(byNewest);
+    if (createdHere[0]) {
+        return { credential: createdHere[0], reason: 'createdIn' };
+    }
+    const usedHere = creds
+        .filter((c) => c.projectDirs.includes(dir))
+        .sort(byNewest);
+    if (usedHere[0]) {
+        return { credential: usedHere[0], reason: 'usedIn' };
+    }
+    return { credential: [...creds].sort(byNewest)[0], reason: 'newest' };
+}
+/**
+ * Resolve the private key to sign attestor proofs with (the claim
+ * "owner"). Reuses the app credential rather than a dedicated key — for
+ * build-time test proofs the developer is both the app and the proof
+ * owner, and the owner identity is immaterial to whether the provider's
+ * matching works.
+ *
+ * The owner is chosen up front (see the `resolve_owner_key` tool) and
+ * passed by `address`; this just fetches the matching private key:
+ *   - the `RECLAIM_PRIVATE_KEY` env / project `.env` key, if it derives
+ *     to `address` (the dev pinned it), else
+ *   - the cached credential with that address.
+ * Returns undefined when no key for `address` is known.
+ */
+export function resolveOwnerPrivateKey(address) {
+    const target = address.toLowerCase();
+    const envKey = process.env.RECLAIM_PRIVATE_KEY ??
+        readPrivateKeyFromEnvFile(findProjectRoot(process.cwd()));
+    if (envKey && deriveFromPrivateKey(envKey).address === target) {
+        return envKey;
+    }
+    return findCredentialFromCachedBy(target)?.privateKey;
+}

package/lib/mcp/tools/credentials/env-file.d.ts

@@ -0,0 +1,25 @@
+export type EnvWriteResult = {
+    envPath: string;
+    gitignorePath: string;
+    gitignoreAppended: boolean;
+};
+/**
+ * Idempotently set `RECLAIM_PRIVATE_KEY` in the project's `.env`, then
+ * `chmod 0600` it. The private key is the only secret we write — the
+ * ETH address (and public key) are derived from it on demand, so there
+ * is no separate address variable to keep in sync. Existing variables
+ * are replaced in place; other lines are preserved verbatim so we
+ * don't trample on unrelated config the user wrote by hand.
+ *
+ * Also appends `.env` to the project's `.gitignore` if it isn't
+ * already listed.
+ */
+export declare function writeAppCredentialsToEnv(projectDir: string, privateKey: string): EnvWriteResult;
+/**
+ * Read `RECLAIM_PRIVATE_KEY` back out of the project's `.env`, if set.
+ * Read live (not from `process.env`) so a credential written by
+ * `issue_credentials` / `import_credentials` is picked up immediately,
+ * without a Claude Code restart. Returns undefined when the file or the
+ * variable is absent.
+ */
+export declare function readPrivateKeyFromEnvFile(projectDir: string): string | undefined;

package/lib/mcp/tools/credentials/env-file.js

@@ -0,0 +1,71 @@
+import { appendFileSync, chmodSync, existsSync, readFileSync, writeFileSync, } from 'node:fs';
+import { join } from 'node:path';
+const PRIVATE_KEY = 'RECLAIM_PRIVATE_KEY';
+const GITIGNORE_LINE = '.env';
+/**
+ * Idempotently set `RECLAIM_PRIVATE_KEY` in the project's `.env`, then
+ * `chmod 0600` it. The private key is the only secret we write — the
+ * ETH address (and public key) are derived from it on demand, so there
+ * is no separate address variable to keep in sync. Existing variables
+ * are replaced in place; other lines are preserved verbatim so we
+ * don't trample on unrelated config the user wrote by hand.
+ *
+ * Also appends `.env` to the project's `.gitignore` if it isn't
+ * already listed.
+ */
+export function writeAppCredentialsToEnv(projectDir, privateKey) {
+    const envPath = join(projectDir, '.env');
+    const lines = existsSync(envPath)
+        ? readFileSync(envPath, 'utf8').split('\n')
+        : [];
+    setOrInsert(lines, PRIVATE_KEY, privateKey);
+    const body = lines.join('\n').replace(/\n+$/, '') + '\n';
+    writeFileSync(envPath, body, { mode: 0o600 });
+    chmodSync(envPath, 0o600);
+    const gitignorePath = join(projectDir, '.gitignore');
+    const gitignoreAppended = ensureLine(gitignorePath, GITIGNORE_LINE);
+    return { envPath, gitignorePath, gitignoreAppended };
+}
+/**
+ * Read `RECLAIM_PRIVATE_KEY` back out of the project's `.env`, if set.
+ * Read live (not from `process.env`) so a credential written by
+ * `issue_credentials` / `import_credentials` is picked up immediately,
+ * without a Claude Code restart. Returns undefined when the file or the
+ * variable is absent.
+ */
+export function readPrivateKeyFromEnvFile(projectDir) {
+    const envPath = join(projectDir, '.env');
+    if (!existsSync(envPath)) {
+        return undefined;
+    }
+    const prefix = `${PRIVATE_KEY}=`;
+    const line = readFileSync(envPath, 'utf8')
+        .split('\n')
+        .find((l) => l.startsWith(prefix));
+    const value = line?.slice(prefix.length).trim();
+    return value || undefined;
+}
+function setOrInsert(lines, key, value) {
+    const prefix = `${key}=`;
+    const idx = lines.findIndex((l) => l.startsWith(prefix));
+    const next = `${key}=${value}`;
+    if (idx >= 0) {
+        lines[idx] = next;
+        return;
+    }
+    lines.push(next);
+}
+function ensureLine(path, line) {
+    if (!existsSync(path)) {
+        writeFileSync(path, line + '\n', { mode: 0o644 });
+        return true;
+    }
+    const body = readFileSync(path, 'utf8');
+    const present = body.split('\n').some((l) => l.trim() === line);
+    if (present) {
+        return false;
+    }
+    const suffix = body.endsWith('\n') ? '' : '\n';
+    appendFileSync(path, suffix + line + '\n');
+    return true;
+}

package/lib/mcp/tools/credentials/import.d.ts

@@ -0,0 +1,2 @@
+import { type RegisteredTool } from '../../server.ts';
+export declare function importTool(): RegisteredTool;

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

@@ -0,0 +1,52 @@
+import { deriveFromPrivateKey } from '@reclaimprotocol/client';
+import { findProjectRoot } from "../../../paths.js";
+import { defineTool } from "../../server.js";
+import { persistCredentialLocally } from "./register.js";
+export function importTool() {
+    return defineTool({
+        name: 'import_credentials',
+        description: 'Import an existing Reclaim app credential the user ' +
+            'already holds elsewhere. Provide the private key ' +
+            '(0x-prefixed hex, 64 chars); we derive the address ' +
+            'locally and cache it. By default also writes ' +
+            'RECLAIM_PRIVATE_KEY to the project .env (0600) and appends ' +
+            '.env to .gitignore; pass `writeEnv: false` to keep it in ' +
+            'the local cache (memory) only and leave .env untouched. ' +
+            'ALWAYS ask the dev whether to save to .env before writing. ' +
+            'The credential stays local-only (SANDBOX); link it to an ' +
+            'org to use it in production.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                privateKey: {
+                    type: 'string',
+                    pattern: '^0x[0-9a-fA-F]{64}$',
+                    description: '0x-prefixed hex private key (64 hex chars / 32 bytes).',
+                },
+                label: {
+                    type: 'string',
+                    minLength: 1,
+                    maxLength: 100,
+                },
+                projectDir: {
+                    type: 'string',
+                    description: 'Project directory to write .env into. Defaults ' +
+                        'to the closest ancestor of cwd containing ' +
+                        '.git or package.json.',
+                },
+                writeEnv: {
+                    type: 'boolean',
+                    description: 'Write RECLAIM_PRIVATE_KEY to the project .env ' +
+                        '(default true). Set false to cache in memory only, ' +
+                        'without touching .env.',
+                },
+            },
+            required: ['privateKey'],
+        },
+    }, async (args) => {
+        const keypair = deriveFromPrivateKey(args.privateKey);
+        const projectDir = findProjectRoot(args.projectDir || process.cwd());
+        const persisted = persistCredentialLocally(keypair, args.label, projectDir, args.writeEnv ?? true);
+        return { ...persisted };
+    });
+}

package/lib/mcp/tools/credentials/issue.d.ts

@@ -0,0 +1,2 @@
+import { type RegisteredTool } from '../../server.ts';
+export declare function issueTool(): RegisteredTool;