@reclaimprotocol/agent 0.1.1-dev.1 → 0.1.2

package/lib/mcp/api/to-zod.d.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+import type { JSONSchema } from 'zod/v4/core';
+/**
+ * JSON Schema → zod for the generated MCP tool inputs.
+ *
+ * The generator (`packages/app/scripts/mcp-tools-gen.ts`) inlines `$ref`s it
+ * walks through `properties`/`items`, but it does NOT recurse into `allOf` /
+ * `anyOf` / `oneOf`. So a schema composed with `allOf` (e.g.
+ * `RequestSelectionTemplate =
+ * allOf[ RequestSelection, { multiple, required } ]`,
+ * surfaced by the proof tools' `allowedJsRequests`) can carry a dangling
+ * `#/components/schemas/…` `$ref` that points outside the standalone schema
+ * object handed to `z.fromJSONSchema`. zod then throws `Reference not found`
+ * at module-load time, taking down every tool.
+ *
+ * We pre-process here (rather than hand-editing the generated file, which
+ * regen would clobber): flatten `allOf` compositions into a single object
+ * schema and neutralize any remaining unresolvable `#/components/schemas/…`
+ * `$ref` to a permissive `{}`. The schemas affected are deep proof-tool inputs
+ * the model rarely hand-builds, so loosening leaf validation there is
+ * acceptable; the common tool inputs (uuids, version patterns, contexts) keep
+ * their full constraints.
+ */
+export declare function toZod(schema: JSONSchema.Schema): z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;

package/lib/mcp/api/to-zod.js

@@ -0,0 +1,94 @@
+import { z } from 'zod';
+/**
+ * JSON Schema → zod for the generated MCP tool inputs.
+ *
+ * The generator (`packages/app/scripts/mcp-tools-gen.ts`) inlines `$ref`s it
+ * walks through `properties`/`items`, but it does NOT recurse into `allOf` /
+ * `anyOf` / `oneOf`. So a schema composed with `allOf` (e.g.
+ * `RequestSelectionTemplate =
+ * allOf[ RequestSelection, { multiple, required } ]`,
+ * surfaced by the proof tools' `allowedJsRequests`) can carry a dangling
+ * `#/components/schemas/…` `$ref` that points outside the standalone schema
+ * object handed to `z.fromJSONSchema`. zod then throws `Reference not found`
+ * at module-load time, taking down every tool.
+ *
+ * We pre-process here (rather than hand-editing the generated file, which
+ * regen would clobber): flatten `allOf` compositions into a single object
+ * schema and neutralize any remaining unresolvable `#/components/schemas/…`
+ * `$ref` to a permissive `{}`. The schemas affected are deep proof-tool inputs
+ * the model rarely hand-builds, so loosening leaf validation there is
+ * acceptable; the common tool inputs (uuids, version patterns, contexts) keep
+ * their full constraints.
+ */
+export function toZod(schema) {
+    return z.fromJSONSchema(sanitize(schema));
+}
+/** True for a `$ref` that can't be resolved in a standalone schema object. */
+function isDanglingComponentRef(node) {
+    return (typeof node.$ref === 'string' &&
+        (node.$ref).startsWith('#/components/'));
+}
+/**
+ * Recursively (a) merge `allOf` members into their parent so composition
+ * resolves locally, and (b) replace any dangling `#/components/…` `$ref` with
+ * a permissive empty schema. Pure — returns a fresh tree, never mutates input.
+ */
+function sanitize(input) {
+    if (Array.isArray(input)) {
+        return input.map(sanitize);
+    }
+    if (input === null || typeof input !== 'object') {
+        return input;
+    }
+    const node = input;
+    if (isDanglingComponentRef(node)) {
+        // Drop the ref; keep any sibling keys (rare) sanitized.
+        const { $ref: _ref, ...rest } = node;
+        void _ref;
+        return sanitizeEntries(rest);
+    }
+    // Flatten allOf into the parent object. Each member is sanitized first so
+    // its own refs/allOf collapse; object members merge their `properties`,
+    // `required`, and scalar keys upward.
+    if (Array.isArray(node.allOf)) {
+        const { allOf, ...rest } = node;
+        let merged = sanitizeEntries(rest);
+        for (const member of allOf) {
+            merged = mergeObjectSchemas(merged, sanitize(member));
+        }
+        return merged;
+    }
+    return sanitizeEntries(node);
+}
+/** Sanitize every value of an object schema's keys. */
+function sanitizeEntries(node) {
+    const out = {};
+    for (const [k, v] of Object.entries(node)) {
+        out[k] = sanitize(v);
+    }
+    return out;
+}
+/**
+ * Merge two (already-sanitized) object schemas for `allOf` flattening: union
+ * `properties`, union `required`, and let later members win on scalar keys.
+ * Both sides are expected to be object-shaped; non-object members fall back to
+ * a plain key spread (the rare case).
+ */
+function mergeObjectSchemas(a, b) {
+    const out = { ...a, ...b };
+    const aProps = a.properties;
+    const bProps = b.properties;
+    if (aProps || bProps) {
+        out.properties = { ...aProps, ...bProps };
+    }
+    const aReq = Array.isArray(a.required) ? a.required : [];
+    const bReq = Array.isArray(b.required) ? b.required : [];
+    if (aReq.length || bReq.length) {
+        out.required = Array.from(new Set([...aReq, ...bReq]));
+    }
+    // `type` should stay `object` after merging two object schemas.
+    if (a.type === 'object' || b.type === 'object' || out.properties) {
+        out.type = 'object';
+    }
+    return out;
+}

package/lib/mcp/api/tools.js

@@ -21,7 +21,7 @@ export function registerTools(server, client) {
         // bug to surface, not silently shadow.
         server.registerTool(toSnakeCase(opId), shape, async (args) => {
             try {
-                const result = (await client.call(opId, args));
+                const result = await client.call(opId, args);
                 return {
                     content: [{
                             type: 'text', text: JSON.stringify(result.data, null, 2)

package/lib/mcp/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 → credentials}/authenticate.js

@@ -1,4 +1,4 @@
-import { defineTool } from "../../server.js";
+import { defineTool } from "../server.js";
 import { writeSession } from "./session-cache.js";
 export function authenticateTool(client) {
     return defineTool({
@@ -11,7 +11,7 @@ export function authenticateTool(client) {
             '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' +
+            'The token is cached in ~/.reclaim/session.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 ' +
@@ -78,7 +78,7 @@ async function checkSession(client, code) {
             return {
                 status: 'LINKED',
                 token,
-                note: 'Token cached in ~/.reclaim/config.json and active now.',
+                note: 'Token cached in ~/.reclaim/session.json and active now.',
             };
         }
         return {

package/lib/mcp/credentials/build.d.ts

@@ -0,0 +1,5 @@
+import type { ReclaimClient } from '@reclaimprotocol/client';
+import type { RegisteredTool } from '../server.ts';
+/** Credential lifecycle tools — build the flat list of RegisteredTool
+ *  entries. Mirrors buildAgentTools() in mcp/register.ts. */
+export declare function buildCredentialTools(client: ReclaimClient): RegisteredTool[];

package/lib/mcp/credentials/build.js

@@ -0,0 +1,18 @@
+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";
+/** Credential lifecycle tools — build the flat list of RegisteredTool
+ *  entries. Mirrors buildAgentTools() in mcp/register.ts. */
+export function buildCredentialTools(client) {
+    return [
+        authenticateTool(client),
+        listCachedTool(),
+        resolveOwnerKeyTool(),
+        issueTool(),
+        importTool(),
+        statusTool(client),
+    ];
+}

package/lib/mcp/{tools/credentials → credentials}/cache.d.ts

@@ -14,16 +14,16 @@ type CacheFile = {
     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.
+ * Read the cache file. Returns an empty doc if missing. Surface-level
+ * shape errors fall back to empty — we'd rather lose the cache than
+ * crash the CLI on a corrupted file the user can re-create.
  */
-export declare function readCredentialsFromCache(): CacheFile;
+export declare function readCache(): 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`.
+ * Write the cache file with strict permissions. The directory gets
+ * `0700` and the file `0600` — same posture as `~/.ssh`. We rewrite
+ * the whole doc each save; the file is tiny and the alternative
+ * (append-only) loses our ability to deduplicate `projectDirs`.
  */
 export declare function writeCache(doc: CacheFile): void;
 /**
@@ -34,7 +34,7 @@ export declare function writeCache(doc: CacheFile): void;
  */
 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 declare function findCached(address: string): CachedCredential | undefined;
 export type SuggestionReason = 'createdIn' | 'usedIn' | 'newest';
 export type CredentialSuggestion = {
     credential: CachedCredential;

package/lib/mcp/{tools/credentials → credentials}/cache.js

@@ -1,28 +1,45 @@
 import { deriveFromPrivateKey } from '@reclaimprotocol/client';
-import { ConfigStore } from "../../../config/store.js";
-import { findProjectRoot } from "../../../paths.js";
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from 'node:fs';
+import { credentialsCachePath, findProjectRoot, reclaimHomeDirPath } 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.
+ * Read the cache file. Returns an empty doc if missing. Surface-level
+ * shape errors fall back to empty — 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)) {
+export function readCache() {
+    const path = credentialsCachePath();
+    if (!existsSync(path)) {
+        return { ...EMPTY };
+    }
+    try {
+        const raw = readFileSync(path, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed.version !== 1 || !Array.isArray(parsed.credentials)) {
+            return { ...EMPTY };
+        }
+        return parsed;
+    }
+    catch {
         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`.
+ * Write the cache file with strict permissions. The directory gets
+ * `0700` and the file `0600` — same posture as `~/.ssh`. We rewrite
+ * the whole doc each save; the file is tiny and the alternative
+ * (append-only) loses our ability to deduplicate `projectDirs`.
  */
 export function writeCache(doc) {
-    new ConfigStore().write({ credentials: doc.credentials });
+    const dir = reclaimHomeDirPath();
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    chmodSync(dir, 0o700);
+    const path = credentialsCachePath();
+    writeFileSync(path, JSON.stringify(doc, null, 2) + '\n', { mode: 0o600 });
+    chmodSync(path, 0o600);
 }
 /**
  * Upsert a credential entry. If a row already exists for `address`,
@@ -31,7 +48,7 @@ export function writeCache(doc) {
  * (backfilling `createdIn` from the new entry when an old row lacks it).
  */
 export function upsertCredential(entry) {
-    const doc = readCredentialsFromCache();
+    const doc = readCache();
     const idx = doc.credentials.findIndex((c) => c.address === entry.address.toLowerCase());
     const merged = {
         ...entry,
@@ -53,8 +70,8 @@ export function upsertCredential(entry) {
     return merged;
 }
 /** Look up a cached credential by address. Case-insensitive. */
-export function findCredentialFromCachedBy(address) {
-    const doc = readCredentialsFromCache();
+export function findCached(address) {
+    const doc = readCache();
     const lc = address.toLowerCase();
     return doc.credentials.find((c) => c.address === lc);
 }
@@ -69,7 +86,7 @@ export function findCredentialFromCachedBy(address) {
  * 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) {
+export function suggestCredentialForDir(dir, creds = readCache().credentials) {
     if (creds.length === 0) {
         return undefined;
     }
@@ -110,5 +127,5 @@ export function resolveOwnerPrivateKey(address) {
     if (envKey && deriveFromPrivateKey(envKey).address === target) {
         return envKey;
     }
-    return findCredentialFromCachedBy(target)?.privateKey;
+    return findCached(target)?.privateKey;
 }

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

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

package/lib/mcp/{tools/credentials → credentials}/import.js

@@ -1,6 +1,6 @@
 import { deriveFromPrivateKey } from '@reclaimprotocol/client';
-import { findProjectRoot } from "../../../paths.js";
-import { defineTool } from "../../server.js";
+import { findProjectRoot } from "../../paths.js";
+import { defineTool } from "../server.js";
 import { persistCredentialLocally } from "./register.js";
 export function importTool() {
     return defineTool({

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

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

package/lib/mcp/{tools/credentials → credentials}/issue.js

@@ -1,7 +1,7 @@
 import { generateKeypair } from '@reclaimprotocol/client';
-import { findProjectRoot } from "../../../paths.js";
-import { defineTool } from "../../server.js";
-import { findCredentialFromCachedBy } from "./cache.js";
+import { findProjectRoot } from "../../paths.js";
+import { defineTool } from "../server.js";
+import { findCached } from "./cache.js";
 import { persistCredentialLocally } from "./register.js";
 export function issueTool() {
     return defineTool({
@@ -53,7 +53,7 @@ export function issueTool() {
         let keypair;
         let reused = false;
         if (args.reuseCachedAppPk) {
-            const cached = findCredentialFromCachedBy(args.reuseCachedAppPk);
+            const cached = findCached(args.reuseCachedAppPk);
             if (!cached) {
                 throw new Error(`No cached credential for ${args.reuseCachedAppPk}. ` +
                     'Call list_cached_credentials first.');

package/lib/mcp/credentials/keypair.d.ts

@@ -0,0 +1,17 @@
+export type EthKeypair = {
+    address: string;
+    publicKey: string;
+    privateKey: string;
+};
+/**
+ * Generate a fresh secp256k1 key-pair and derive its lowercase
+ * Ethereum address (keccak-256 of the uncompressed pubkey minus the
+ * `0x04` prefix, last 20 bytes).
+ */
+export declare function generateKeypair(): EthKeypair;
+/**
+ * Recover the address + uncompressed public key from a hex-encoded
+ * private key. Used by `importCredentials` to derive the public
+ * surface the server needs from a key the user already holds.
+ */
+export declare function deriveFromPrivateKey(privateKey: string): EthKeypair;

package/lib/mcp/credentials/keypair.js

@@ -0,0 +1,48 @@
+import { keccak_256 } from '@noble/hashes/sha3.js';
+import * as secp from '@noble/secp256k1';
+/**
+ * Generate a fresh secp256k1 key-pair and derive its lowercase
+ * Ethereum address (keccak-256 of the uncompressed pubkey minus the
+ * `0x04` prefix, last 20 bytes).
+ */
+export function generateKeypair() {
+    const priv = secp.utils.randomSecretKey();
+    const pub = secp.getPublicKey(priv, false);
+    return {
+        address: '0x' + bytesToHex(keccak_256(pub.slice(1))).slice(-40),
+        publicKey: '0x' + bytesToHex(pub),
+        privateKey: '0x' + bytesToHex(priv),
+    };
+}
+/**
+ * Recover the address + uncompressed public key from a hex-encoded
+ * private key. Used by `importCredentials` to derive the public
+ * surface the server needs from a key the user already holds.
+ */
+export function deriveFromPrivateKey(privateKey) {
+    const hex = privateKey.replace(/^0x/, '');
+    const priv = hexToBytes(hex);
+    const pub = secp.getPublicKey(priv, false);
+    return {
+        address: '0x' + bytesToHex(keccak_256(pub.slice(1))).slice(-40),
+        publicKey: '0x' + bytesToHex(pub),
+        privateKey: '0x' + hex,
+    };
+}
+function bytesToHex(bytes) {
+    let out = '';
+    for (const b of bytes) {
+        out += b.toString(16).padStart(2, '0');
+    }
+    return out;
+}
+function hexToBytes(hex) {
+    if (hex.length % 2 !== 0) {
+        throw new Error('private key hex must have even length');
+    }
+    const out = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < out.length; i++) {
+        out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    }
+    return out;
+}

package/lib/mcp/credentials/link.d.ts

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

package/lib/mcp/credentials/link.js

@@ -0,0 +1,107 @@
+import { defineTool } from "../server.js";
+import { patchCached } from "./cache.js";
+import { writeSession } from "./session-cache.js";
+export function linkTool(client) {
+    return defineTool({
+        name: 'link_credential_via_dashboard',
+        description: 'Pair a Reclaim app credential to an organization via the dashboard. '
+            + 'Two steps:\n\n'
+            + 'Step 1 — call with the credential `address`. Returns a `code` '
+            + 'and `attachUrl`. Tell the user to open the URL, sign in, pick '
+            + 'an organization, and click "Confirm link".\n\n'
+            + 'Step 2 — once the user has confirmed, call again with the same '
+            + '`code` from step 1 to check the result. Returns `LINKED` with '
+            + 'the linked `orgId` when done, `PENDING` if not yet.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                address: {
+                    type: 'string',
+                    pattern: '^0x[0-9a-fA-F]{40}$',
+                    description: 'Lowercase ETH address. Defaults to '
+                        + 'process.env.RECLAIM_APP_PK.',
+                },
+                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.',
+                },
+            },
+        },
+    }, async (args) => {
+        // Step 2: check an existing session
+        if (args.code) {
+            const address = (args.address || process.env.RECLAIM_APP_PK || '').toLowerCase();
+            let session;
+            try {
+                session = await client.call('GetAttachSession', {
+                    params: { code: args.code },
+                    query: {}, body: {},
+                });
+            }
+            catch (err) {
+                const msg = err.message;
+                if (msg.includes('404') || msg.includes('Not Found')) {
+                    return {
+                        status: 'NOT_FOUND',
+                        hint: 'Session not found or expired. '
+                            + 'Call link_credential_via_dashboard with just the address to start over.',
+                    };
+                }
+                throw new Error(`Failed to check session: ${msg}`);
+            }
+            if (session.status === 'LINKED') {
+                if (session.linkedOrgId && address) {
+                    patchCached(address, { orgId: session.linkedOrgId });
+                }
+                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',
+                    address,
+                    ...(session.linkedOrgId ? { orgId: session.linkedOrgId } : {}),
+                    ...(token ? { token } : {}),
+                };
+            }
+            if (session.status === 'EXPIRED') {
+                return {
+                    status: 'EXPIRED',
+                    hint: 'Session expired. Call link_credential_via_dashboard with the address to start over.',
+                };
+            }
+            // Still PENDING
+            return {
+                status: 'PENDING',
+                code: session.code,
+                attachUrl: session.attachUrl,
+                hint: `Still waiting. Open ${session.attachUrl}, sign in, pick an org, and confirm. `
+                    + `Then call link_credential_via_dashboard with code: "${session.code}" again.`,
+            };
+        }
+        // Step 1: open a new session
+        const address = (args.address || process.env.RECLAIM_APP_PK || '').toLowerCase();
+        if (!address) {
+            throw new Error('No address provided and RECLAIM_APP_PK is not set.');
+        }
+        const session = await client.call('CreateAttachSession', {
+            params: {}, query: {},
+            body: { address },
+        });
+        return {
+            status: 'PENDING',
+            code: session.code,
+            attachUrl: session.attachUrl,
+            expiresAt: session.expiresAt,
+            instructions: `Open ${session.attachUrl} in your browser, sign in, and pick an organization. `
+                + `Once done, call link_credential_via_dashboard again with code: "${session.code}" to confirm.`,
+        };
+    });
+}

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

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

package/lib/mcp/{tools/credentials → credentials}/list-cached.js

@@ -1,11 +1,11 @@
-import { findProjectRoot } from "../../../paths.js";
-import { defineTool } from "../../server.js";
-import { readCredentialsFromCache, suggestCredentialForDir } from "./cache.js";
+import { findProjectRoot } from "../../paths.js";
+import { defineTool } from "../server.js";
+import { readCache, 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 ' +
+            'locally in ~/.reclaim/credentials.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 ' +
@@ -19,7 +19,7 @@ export function listCachedTool() {
             properties: {},
         },
     }, async () => {
-        const doc = readCredentialsFromCache();
+        const doc = readCache();
         const currentDir = findProjectRoot(process.cwd());
         const suggestion = suggestCredentialForDir(currentDir, doc.credentials);
         const suggestedAddress = suggestion?.credential.address;

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

@@ -0,0 +1,23 @@
+export type OwnerKey = {
+    privateKey: string;
+    address: string;
+    publicKey: string;
+    /** ISO timestamp when the key was generated. */
+    createdAt: string;
+};
+export declare function ownerKeyPath(): string;
+/** Read the saved owner key, or undefined if absent/unreadable. */
+export declare function readOwnerKey(): OwnerKey | undefined;
+/** Persist the owner key to ~/.reclaim/owner-key.json (0600). */
+export declare function writeOwnerKey(key: OwnerKey): void;
+/**
+ * Resolve the owner private key for proof generation. Priority:
+ * explicit `RECLAIM_AGENT_OWNER_PRIVATE_KEY` env var → saved
+ * ~/.reclaim/owner-key.json → undefined. Mirrors the token-resolution
+ * order used for the auth session.
+ */
+export declare function resolveOwnerPrivateKey(): string | undefined;
+/** True when the env var is set and therefore shadows any saved file. */
+export declare function ownerKeyEnvOverrideActive(): boolean;
+/** Generate a fresh owner key, persist it, and return it. */
+export declare function generateOwnerKey(): OwnerKey;

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

@@ -0,0 +1,58 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from 'node:fs';
+import { join } from 'node:path';
+import { generateKeypair } from "./keypair.js";
+import { reclaimHome } from "./paths.js";
+const ENV_VAR = 'RECLAIM_AGENT_OWNER_PRIVATE_KEY';
+export function ownerKeyPath() {
+    return join(reclaimHome(), 'owner-key.json');
+}
+/** Read the saved owner key, or undefined if absent/unreadable. */
+export function readOwnerKey() {
+    const path = ownerKeyPath();
+    if (!existsSync(path)) {
+        return undefined;
+    }
+    try {
+        const k = JSON.parse(readFileSync(path, 'utf8'));
+        return k.privateKey ? k : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Persist the owner key to ~/.reclaim/owner-key.json (0600). */
+export function writeOwnerKey(key) {
+    const dir = reclaimHome();
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    chmodSync(dir, 0o700);
+    const path = ownerKeyPath();
+    writeFileSync(path, JSON.stringify(key, null, 2) + '\n', { mode: 0o600 });
+    chmodSync(path, 0o600);
+}
+/**
+ * Resolve the owner private key for proof generation. Priority:
+ * explicit `RECLAIM_AGENT_OWNER_PRIVATE_KEY` env var → saved
+ * ~/.reclaim/owner-key.json → undefined. Mirrors the token-resolution
+ * order used for the auth session.
+ */
+export function resolveOwnerPrivateKey() {
+    return process.env[ENV_VAR] || readOwnerKey()?.privateKey;
+}
+/** True when the env var is set and therefore shadows any saved file. */
+export function ownerKeyEnvOverrideActive() {
+    return Boolean(process.env[ENV_VAR]);
+}
+/** Generate a fresh owner key, persist it, and return it. */
+export function generateOwnerKey() {
+    const kp = generateKeypair();
+    const key = {
+        privateKey: kp.privateKey,
+        address: kp.address,
+        publicKey: kp.publicKey,
+        createdAt: new Date().toISOString(),
+    };
+    writeOwnerKey(key);
+    return key;
+}