@reclaimprotocol/agent 0.1.0-dev.1

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

@@ -0,0 +1,84 @@
+import { generateKeypair } from '@reclaimprotocol/client';
+import { findProjectRoot } from "../../../paths.js";
+import { defineTool } from "../../server.js";
+import { findCredentialFromCachedBy } from "./cache.js";
+import { persistCredentialLocally } from "./register.js";
+export function issueTool() {
+    return defineTool({
+        name: 'issue_credentials',
+        description: 'Mint a fresh anonymous Reclaim app key-pair (or reuse ' +
+            'a cached one via `reuseCachedAppPk`) and cache it locally. ' +
+            'By default also writes RECLAIM_PRIVATE_KEY to the project ' +
+            '.env (mode 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 it. The key-pair is ' +
+            'generated locally and is NOT registered with the server — ' +
+            'anonymous credentials operate in SANDBOX mode entirely ' +
+            'client-side. PREFER REUSE over generating a new credential ' +
+            'unless the user explicitly asks for a new app identity. To ' +
+            'use a credential for verification in production, link it to ' +
+            'an organization (via link_credential) and add billing.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                reuseCachedAppPk: {
+                    type: 'string',
+                    pattern: '^0x[0-9a-fA-F]{40}$',
+                    description: 'Lowercase ETH address of a cached credential ' +
+                        'to reuse instead of minting a new one.',
+                },
+                label: {
+                    type: 'string',
+                    minLength: 1,
+                    maxLength: 100,
+                    description: 'Human label stored in the local cache.',
+                },
+                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 the credential ' +
+                        'in memory only, without touching .env.',
+                },
+            },
+        },
+    }, async (args) => {
+        const projectDir = findProjectRoot(args.projectDir || process.cwd());
+        let keypair;
+        let reused = false;
+        if (args.reuseCachedAppPk) {
+            const cached = findCredentialFromCachedBy(args.reuseCachedAppPk);
+            if (!cached) {
+                throw new Error(`No cached credential for ${args.reuseCachedAppPk}. ` +
+                    'Call list_cached_credentials first.');
+            }
+            keypair = {
+                address: cached.address,
+                privateKey: cached.privateKey,
+            };
+            reused = true;
+        }
+        else {
+            keypair = generateKeypair();
+        }
+        const writeEnv = args.writeEnv ?? true;
+        const persisted = persistCredentialLocally(keypair, args.label, projectDir, writeEnv);
+        return {
+            reused,
+            ...persisted,
+            note: writeEnv
+                ? 'Private key written to .env (and the local cache); it is ' +
+                    'NOT in this response on purpose. The credential is ' +
+                    'local-only (SANDBOX); link it to an org for production.'
+                : 'Private key cached in memory only (.env untouched). Sign ' +
+                    'proofs with it by passing run_proof({ ownerAddress }). The ' +
+                    'credential is local-only (SANDBOX).',
+        };
+    });
+}

package/lib/mcp/tools/credentials/list-cached.d.ts

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

package/lib/mcp/tools/credentials/list-cached.js

@@ -0,0 +1,55 @@
+import { findProjectRoot } from "../../../paths.js";
+import { defineTool } from "../../server.js";
+import { readCredentialsFromCache, suggestCredentialForDir } from "./cache.js";
+export function listCachedTool() {
+    return defineTool({
+        name: 'list_cached_credentials',
+        description: 'List Reclaim app credentials (ETH key-pairs) cached ' +
+            'locally in ~/.reclaim/config.json. Returns one ' +
+            'row per credential with address, optional label and ' +
+            'orgId, createdAt, createdIn (where it was first created), ' +
+            'and the project directories that have used it. Private keys ' +
+            'are stripped. The response also reports `currentDir` and ' +
+            'flags the best credential for it (`suggested`, plus ' +
+            '`suggestedAddress`/`suggestionReason`) — prefer reusing that ' +
+            'one over minting a new credential. When the cache is empty a ' +
+            '`suggestion` string explains how to create one.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+    }, async () => {
+        const doc = readCredentialsFromCache();
+        const currentDir = findProjectRoot(process.cwd());
+        const suggestion = suggestCredentialForDir(currentDir, doc.credentials);
+        const suggestedAddress = suggestion?.credential.address;
+        const items = doc.credentials.map((c) => ({
+            address: c.address,
+            label: c.label,
+            orgId: c.orgId,
+            createdAt: c.createdAt,
+            createdIn: c.createdIn,
+            projectDirs: c.projectDirs,
+            matchesCurrentDir: c.createdIn === currentDir || c.projectDirs.includes(currentDir),
+            suggested: c.address === suggestedAddress,
+        }));
+        // Promote the single suggested row to the top; stable sort keeps
+        // the rest in insertion (newest-first) order.
+        items.sort((a, b) => Number(b.suggested) - Number(a.suggested));
+        if (items.length === 0) {
+            return {
+                items,
+                currentDir,
+                suggestion: 'No cached credentials. Call issue_credentials to mint a new ' +
+                    'app key-pair, or import_credentials if you already hold a ' +
+                    'private key. Do not invent credentials.',
+            };
+        }
+        return {
+            items,
+            currentDir,
+            suggestedAddress,
+            suggestionReason: suggestion?.reason,
+        };
+    });
+}

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

@@ -0,0 +1,18 @@
+import type { EthKeypair } from '@reclaimprotocol/client';
+import { type CachedCredential } from './cache.ts';
+import { type EnvWriteResult } from './env-file.ts';
+/** Shape returned by `persistCredentialLocally` — the fields both
+ *  `issue_credentials` and `import_credentials` expose in their MCP
+ *  responses. The env-file fields are present only when the credential
+ *  was persisted to `.env` (`writeEnv: true`); a memory-only credential
+ *  lives in the cache and omits them. */
+export type PersistedCredential = Pick<CachedCredential, 'address' | 'label'> & Partial<EnvWriteResult> & {
+    wroteEnv: boolean;
+};
+/** Local persistence step shared by `issue_credentials` and
+ *  `import_credentials`. Always upserts the credentials cache; when
+ *  `writeEnv` is true (default) it also writes `RECLAIM_PRIVATE_KEY` to
+ *  the project `.env` (0600) and appends `.env` to `.gitignore`. Pass
+ *  `writeEnv: false` to keep the credential in the cache (memory) only,
+ *  without touching the project's `.env`. */
+export declare function persistCredentialLocally(keypair: EthKeypair, label: string | undefined, projectDir: string, writeEnv?: boolean): PersistedCredential;

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

@@ -0,0 +1,30 @@
+import { upsertCredential } from "./cache.js";
+import { writeAppCredentialsToEnv } from "./env-file.js";
+/** Local persistence step shared by `issue_credentials` and
+ *  `import_credentials`. Always upserts the credentials cache; when
+ *  `writeEnv` is true (default) it also writes `RECLAIM_PRIVATE_KEY` to
+ *  the project `.env` (0600) and appends `.env` to `.gitignore`. Pass
+ *  `writeEnv: false` to keep the credential in the cache (memory) only,
+ *  without touching the project's `.env`. */
+export function persistCredentialLocally(keypair, label, projectDir, writeEnv = true) {
+    const cached = upsertCredential({
+        address: keypair.address,
+        privateKey: keypair.privateKey,
+        label,
+        createdAt: new Date().toISOString(),
+        createdIn: projectDir,
+        projectDirs: [projectDir],
+    });
+    if (!writeEnv) {
+        return { address: cached.address, label: cached.label, wroteEnv: false };
+    }
+    const env = writeAppCredentialsToEnv(projectDir, keypair.privateKey);
+    return {
+        address: cached.address,
+        label: cached.label,
+        wroteEnv: true,
+        envPath: env.envPath,
+        gitignorePath: env.gitignorePath,
+        gitignoreAppended: env.gitignoreAppended,
+    };
+}

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

@@ -0,0 +1,12 @@
+import { type RegisteredTool } from '../../server.ts';
+/**
+ * Decide which app credential `run_proof` should sign with, BEFORE
+ * calling it. `run_proof` requires an `ownerAddress` and does no
+ * resolution of its own — this is the single place that "checks memory,
+ * env, etc and offers options".
+ *
+ * Checks, in order: `RECLAIM_PRIVATE_KEY` in the MCP env → the project
+ * `.env` → the best cached credential for this directory. Never returns
+ * the private key — only the address to pass through as `ownerAddress`.
+ */
+export declare function resolveOwnerKeyTool(): RegisteredTool;

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

@@ -0,0 +1,68 @@
+import { deriveFromPrivateKey } from '@reclaimprotocol/client';
+import { findProjectRoot } from "../../../paths.js";
+import { defineTool } from "../../server.js";
+import { suggestCredentialForDir } from "./cache.js";
+import { readPrivateKeyFromEnvFile } from "./env-file.js";
+/**
+ * Decide which app credential `run_proof` should sign with, BEFORE
+ * calling it. `run_proof` requires an `ownerAddress` and does no
+ * resolution of its own — this is the single place that "checks memory,
+ * env, etc and offers options".
+ *
+ * Checks, in order: `RECLAIM_PRIVATE_KEY` in the MCP env → the project
+ * `.env` → the best cached credential for this directory. Never returns
+ * the private key — only the address to pass through as `ownerAddress`.
+ */
+export function resolveOwnerKeyTool() {
+    return defineTool({
+        name: 'resolve_owner_key',
+        description: 'Resolve which app credential run_proof should sign with — ' +
+            'call this BEFORE run_proof. Checks, in order: ' +
+            'RECLAIM_PRIVATE_KEY in the MCP env, RECLAIM_PRIVATE_KEY in the ' +
+            'project .env, then the best cached credential for this ' +
+            'directory. Returns { ready: true, address, source } when one ' +
+            'is available — pass `address` to run_proof as `ownerAddress`. ' +
+            'Returns { ready: false } when none exists: then ask the dev to ' +
+            'provide a private key (import_credentials) or create one ' +
+            '(issue_credentials) — optionally with writeEnv:false to keep ' +
+            'it in the local cache (memory) only — and call resolve_owner_key ' +
+            'again. Never exposes the private key.',
+        inputSchema: { type: 'object', properties: {} },
+    }, async () => {
+        const dir = findProjectRoot(process.cwd());
+        const envKey = process.env.RECLAIM_PRIVATE_KEY;
+        if (envKey) {
+            return {
+                ready: true,
+                address: deriveFromPrivateKey(envKey).address,
+                source: 'env',
+            };
+        }
+        const dotenvKey = readPrivateKeyFromEnvFile(dir);
+        if (dotenvKey) {
+            return {
+                ready: true,
+                address: deriveFromPrivateKey(dotenvKey).address,
+                source: 'dotenv',
+            };
+        }
+        const suggestion = suggestCredentialForDir(dir);
+        if (suggestion) {
+            return {
+                ready: true,
+                address: suggestion.credential.address,
+                source: 'cache',
+                reason: suggestion.reason,
+            };
+        }
+        return {
+            ready: false,
+            message: 'No app credential available (no RECLAIM_PRIVATE_KEY in env ' +
+                'or .env, and the cache is empty). Ask the dev to provide ' +
+                'their private key via import_credentials, or create one via ' +
+                'issue_credentials (pass writeEnv:false to keep it out of ' +
+                '.env). Then call resolve_owner_key again and pass its ' +
+                'address to run_proof as ownerAddress.',
+        };
+    });
+}

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

@@ -0,0 +1,14 @@
+export type CachedSession = {
+    token: string;
+    /** ISO timestamp when the token expires (2 days from issue). */
+    expiresAt: string;
+    /** Email of the user who authorized (if available). */
+    email?: string;
+};
+/** Persist the auth token to the `session` section of the unified config. */
+export declare function writeSession(session: CachedSession): void;
+/**
+ * Read the cached session, returning it only if the token is still
+ * valid (not yet expired). Returns undefined on any error.
+ */
+export declare function readSession(): CachedSession | undefined;

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

@@ -0,0 +1,19 @@
+import { ConfigStore } from "../../../config/store.js";
+/** Persist the auth token to the `session` section of the unified config. */
+export function writeSession(session) {
+    new ConfigStore().write({ session });
+}
+/**
+ * Read the cached session, returning it only if the token is still
+ * valid (not yet expired). Returns undefined on any error.
+ */
+export function readSession() {
+    const s = new ConfigStore().read()?.session;
+    if (!s?.token || !s.expiresAt) {
+        return undefined;
+    }
+    if (new Date(s.expiresAt) <= new Date()) {
+        return undefined; // expired
+    }
+    return s;
+}

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

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

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

@@ -0,0 +1,62 @@
+import { deriveFromPrivateKey, } from '@reclaimprotocol/client';
+import assert from 'node:assert';
+import { findProjectRoot } from "../../../paths.js";
+import { defineTool } from "../../server.js";
+import { suggestCredentialForDir } from "./cache.js";
+export function statusTool(client) {
+    return defineTool({
+        name: 'reclaim_status',
+        description: 'Report the live mode (SANDBOX | PRODUCTION | REVOKED) ' +
+            'of a Reclaim app credential. Pass `address` — or omit it ' +
+            'to derive the address from RECLAIM_PRIVATE_KEY, falling ' +
+            'back to the best cached credential for this directory. ' +
+            'Useful to confirm a credential is linked to an org ' +
+            'with billing before running a production flow.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                address: {
+                    type: 'string',
+                    pattern: '^0x[0-9a-fA-F]{40}$',
+                    description: 'Lowercase ETH address. Defaults to the address ' +
+                        'derived from RECLAIM_PRIVATE_KEY, then the cached ' +
+                        'credential suggested for the current directory.',
+                },
+            },
+        },
+    }, async (args) => {
+        let address = args.address?.toLowerCase();
+        if (!address && process.env.RECLAIM_PRIVATE_KEY) {
+            address = deriveFromPrivateKey(process.env.RECLAIM_PRIVATE_KEY).address;
+        }
+        if (!address) {
+            address = suggestCredentialForDir(findProjectRoot(process.cwd()))
+                ?.credential.address;
+        }
+        assert(address, new Error('No address given, RECLAIM_PRIVATE_KEY is not set, and the ' +
+            'cache is empty. Run issue_credentials or import_credentials ' +
+            'first.'));
+        const credResult = await client
+            .call('GetCredentialByAddress', { params: { address } });
+        const cred = credResult.data;
+        // A registered credential always carries an `id`; its absence means
+        // the server had no row for this address — a local-only credential.
+        const localOnly = !cred.id;
+        return {
+            address: cred.address,
+            mode: cred.mode,
+            orgId: cred.orgId,
+            label: cred.label,
+            revokedAt: cred.revokedAt,
+            lastUsedAt: cred.lastUsedAt,
+            ...(localOnly ? {
+                note: 'Local-only credential — not registered with the server. '
+                    + 'It operates in SANDBOX, which is all you need to publish '
+                    + 'a verification (only an auth token is required — no '
+                    + 'credential link). Linking it to an org with billing (via '
+                    + 'link_credential) is only needed for the upcoming feature '
+                    + 'that runs verifications for your own app’s users.',
+            } : {}),
+        };
+    });
+}

package/lib/mcp-bin.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/mcp-bin.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { startMcpServer } from "./mcp/start.js";
+import { LOGGER } from "./logger.js";
+startMcpServer().catch((err) => {
+    LOGGER.error({ err }, 'mcp server failed');
+    process.exitCode = 1;
+});

package/lib/old/client.d.ts

@@ -0,0 +1,67 @@
+/** Default origin of the OLD devtools backend. The client appends the
+ *  `/api` route prefix itself, so this is the bare origin. Override with
+ *  `RECLAIM_OLD_API_URL`. */
+export declare const DEFAULT_OLD_API_URL = "https://devapi.reclaimprotocol.org";
+/**
+ * Externally-supplied caller identity. We do NOT mint these — the dev
+ * provides one:
+ *   - `bearer`: a Firebase ID token from the devtools dashboard. Attached
+ *     as `Authorization: Bearer …`; `POST /api/users/login` provisions the
+ *     user row on first use.
+ *   - `eth`: an `eth:<lowercase-address>` uid for an already-provisioned
+ *     eth user. Attached as the `x-eth-uid` header (no signature — the
+ *     backend trusts the header for a uid that already exists).
+ */
+export type OldIdentity = {
+    kind: 'bearer';
+    token: string;
+} | {
+    kind: 'eth';
+    uid: string;
+};
+export interface RegisterProviderBody {
+    name: string;
+    description?: string;
+    loginUrl: string;
+    geoLocation?: string;
+    providerType?: 'PRIVATE' | 'PUBLIC';
+    requestData: unknown[];
+}
+export interface UpdateProviderConfigBody {
+    providerConfig: Record<string, unknown>;
+    version: string;
+    versionInfo: string;
+}
+export interface MyProvidersQuery {
+    pageKey?: number;
+    pageSize?: number;
+    searchQuery?: string;
+}
+/**
+ * Minimal REST client for the OLD devtools Express backend (base `/api`).
+ * Deliberately NOT a clone of `@reclaimprotocol/client`'s operationId
+ * machinery — the old backend has no OpenAPI spec, so this exposes a few
+ * hand-written typed methods for exactly the flows old mode needs:
+ * authenticate, publish (register / update version), and list-own.
+ *
+ * Errors are thrown as `@hapi/boom` so `remapErrorAsResponse` renders them
+ * identically to builder-mode `ProblemError`s.
+ */
+export declare class ReclaimOldClient {
+    #private;
+    readonly baseUrl: string;
+    constructor(opts?: {
+        baseUrl?: string;
+        identity?: OldIdentity;
+        fetch?: typeof fetch;
+    });
+    setIdentity(identity: OldIdentity | undefined): void;
+    getIdentity(): OldIdentity | undefined;
+    /** Validate + provision a bearer identity. The backend creates the user
+     *  row on first login, which is what makes later authed calls work. */
+    loginWithToken(): Promise<unknown>;
+    registerProvider(body: RegisterProviderBody): Promise<unknown>;
+    updateProviderConfig(providerId: string, body: UpdateProviderConfigBody): Promise<unknown>;
+    listVersions(providerId: string): Promise<unknown>;
+    getMyProviders(query?: MyProvidersQuery): Promise<unknown>;
+}

package/lib/old/client.js

@@ -0,0 +1,146 @@
+import { Boom } from '@hapi/boom';
+import { NAME, VERSION } from "../pkg.js";
+/** Default origin of the OLD devtools backend. The client appends the
+ *  `/api` route prefix itself, so this is the bare origin. Override with
+ *  `RECLAIM_OLD_API_URL`. */
+export const DEFAULT_OLD_API_URL = 'https://devapi.reclaimprotocol.org';
+/**
+ * Minimal REST client for the OLD devtools Express backend (base `/api`).
+ * Deliberately NOT a clone of `@reclaimprotocol/client`'s operationId
+ * machinery — the old backend has no OpenAPI spec, so this exposes a few
+ * hand-written typed methods for exactly the flows old mode needs:
+ * authenticate, publish (register / update version), and list-own.
+ *
+ * Errors are thrown as `@hapi/boom` so `remapErrorAsResponse` renders them
+ * identically to builder-mode `ProblemError`s.
+ */
+export class ReclaimOldClient {
+    baseUrl;
+    #identity;
+    #fetch;
+    constructor(opts = {}) {
+        this.baseUrl = (opts.baseUrl || DEFAULT_OLD_API_URL).replace(/\/+$/, '');
+        this.#identity = opts.identity;
+        this.#fetch = opts.fetch ?? fetch;
+    }
+    setIdentity(identity) {
+        this.#identity = identity;
+    }
+    getIdentity() {
+        return this.#identity;
+    }
+    /** Validate + provision a bearer identity. The backend creates the user
+     *  row on first login, which is what makes later authed calls work. */
+    loginWithToken() {
+        return this.#request('POST', '/users/login', { auth: true });
+    }
+    registerProvider(body) {
+        return this.#request('POST', '/providers/register', { body, auth: true });
+    }
+    updateProviderConfig(providerId, body) {
+        return this.#request('POST', `/providers/${encodeURIComponent(providerId)}/config`, { body, auth: true });
+    }
+    listVersions(providerId) {
+        return this.#request('GET', `/providers/${encodeURIComponent(providerId)}/versions`, { auth: true });
+    }
+    getMyProviders(query = {}) {
+        // Every one of these query params is REQUIRED by the backend
+        // validator (missing/invalid → 400), so default them all here.
+        return this.#request('GET', '/providers/user/paginated', {
+            auth: true,
+            query: {
+                pageKey: query.pageKey ?? 0,
+                pageSize: query.pageSize ?? 20,
+                searchQuery: query.searchQuery ?? '',
+                sortByCreatedLatest: 'true',
+                providerType: 'ALL',
+                providerStatus: 'ALL',
+                providerVisibility: 'ALL',
+            },
+        });
+    }
+    async #request(method, path, opts = {}) {
+        let url = `${this.baseUrl}/api${path}`;
+        if (opts.query) {
+            const search = new URLSearchParams();
+            for (const [k, v] of Object.entries(opts.query)) {
+                if (v === undefined) {
+                    continue;
+                }
+                search.append(k, String(v));
+            }
+            const qs = search.toString();
+            if (qs) {
+                url += `?${qs}`;
+            }
+        }
+        const headers = {
+            Accept: 'application/json',
+            'User-Agent': `${NAME}/${VERSION}`,
+        };
+        if (opts.auth) {
+            headers[this.#authHeaderName()] = this.#authHeaderValue();
+        }
+        const init = { method, headers };
+        if (method !== 'GET' && method !== 'HEAD') {
+            init.body = JSON.stringify(opts.body ?? {});
+            headers['Content-Type'] = 'application/json';
+        }
+        const res = await this.#fetch(url, init);
+        const json = await this.#parseBody(res);
+        // Old API convention: { message, ...data, isSuccess }. Treat a non-2xx
+        // OR an explicit isSuccess:false as an error so a 200-with-failure
+        // body never slips through as success.
+        const failed = !res.ok ||
+            (json !== undefined &&
+                typeof json === 'object' &&
+                json.isSuccess === false);
+        if (failed) {
+            throw this.#asBoom(res, json);
+        }
+        return json;
+    }
+    #authHeaderName() {
+        const id = this.#requireIdentity();
+        return id.kind === 'bearer' ? 'Authorization' : 'x-eth-uid';
+    }
+    #authHeaderValue() {
+        const id = this.#requireIdentity();
+        return id.kind === 'bearer' ? `Bearer ${id.token}` : id.uid;
+    }
+    #requireIdentity() {
+        if (!this.#identity) {
+            throw new Boom('Not authenticated against old devtools. Call reclaim_authenticate ' +
+                'with a dashboard token (or eth uid) first.', { statusCode: 401, data: { status: 401, detail: 'no identity set' } });
+        }
+        return this.#identity;
+    }
+    async #parseBody(res) {
+        if (res.status === 204 || res.headers.get('content-length') === '0') {
+            return undefined;
+        }
+        try {
+            return await res.json();
+        }
+        catch {
+            return undefined;
+        }
+    }
+    #asBoom(res, json) {
+        const message = (json && typeof json === 'object' &&
+            typeof json.message === 'string'
+            ? json.message
+            : undefined) || res.statusText || 'Old devtools request failed';
+        // Shape `data` like a ProblemDetails so remapErrorAsResponse can render
+        // `${message}: ${data.detail}` and expose the raw body as structured.
+        return new Boom(message, {
+            statusCode: res.ok ? 502 : res.status,
+            data: {
+                status: res.status,
+                title: message,
+                detail: message,
+                body: json,
+            },
+        });
+    }
+}

package/lib/old/flag.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `USE_OLD_DEVTOOLS` — single source of truth for which backend the MCP
+ * server targets.
+ *
+ * Defaults to OLD devtools (the system still in production) while the new
+ * "builder" backend is under development. Builder mode must be opted into
+ * EXPLICITLY by setting `USE_OLD_DEVTOOLS=false`. Anything else — unset,
+ * empty, `true`, `1`, a typo — keeps old mode on, so a forgotten env var
+ * can never silently route a developer at the half-built builder backend.
+ */
+export declare function useOldDevtools(): boolean;

package/lib/old/flag.js

@@ -0,0 +1,13 @@
+/**
+ * `USE_OLD_DEVTOOLS` — single source of truth for which backend the MCP
+ * server targets.
+ *
+ * Defaults to OLD devtools (the system still in production) while the new
+ * "builder" backend is under development. Builder mode must be opted into
+ * EXPLICITLY by setting `USE_OLD_DEVTOOLS=false`. Anything else — unset,
+ * empty, `true`, `1`, a typo — keeps old mode on, so a forgotten env var
+ * can never silently route a developer at the half-built builder backend.
+ */
+export function useOldDevtools() {
+    return (process.env.USE_OLD_DEVTOOLS ?? '').trim().toLowerCase() !== 'false';
+}

package/lib/old/identity.d.ts

@@ -0,0 +1,22 @@
+import type { OldIdentity } from './client.ts';
+/** Normalize an eth uid input to `eth:<lowercase-address>`. Accepts a bare
+ *  `0x…` address or an already-prefixed `eth:0x…`. */
+export declare function toEthUid(addressOrUid: string): OldIdentity;
+/**
+ * Resolve a caller identity from the environment, in priority order:
+ *   1. `RECLAIM_OLD_API_TOKEN` — a dashboard Firebase bearer token.
+ *   2. `RECLAIM_OLD_ETH_UID`   — an `eth:<addr>` (or bare `0x…`) uid.
+ *   3. `RECLAIM_PRIVATE_KEY`   — derive the eth uid from the local app key.
+ * Returns undefined when none is set.
+ */
+export declare function resolveIdentityFromEnv(): OldIdentity | undefined;
+/** Read the identity persisted by a prior `reclaim_authenticate` call. */
+export declare function loadPersistedIdentity(): OldIdentity | undefined;
+/** Persist the identity so it survives an MCP-server restart. */
+export declare function persistIdentity(identity: OldIdentity): void;
+/**
+ * The identity the client should start with: an explicit env var wins
+ * (useful for headless / CI), otherwise fall back to whatever the dev
+ * authenticated with last time.
+ */
+export declare function resolveInitialIdentity(): OldIdentity | undefined;