@reclaimprotocol/agent 0.1.0-dev.1

package/src/mcp/tools/credentials/cache.ts

@@ -0,0 +1,161 @@
+import { deriveFromPrivateKey } from '@reclaimprotocol/client'
+import { ConfigStore } from '../../../config/store.ts'
+import { findProjectRoot } from '../../../paths.ts'
+import { readPrivateKeyFromEnvFile } from './env-file.ts'
+
+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[]
+}
+
+const EMPTY: CacheFile = { 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(): CacheFile {
+	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: CacheFile) {
+	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: CachedCredential) {
+	const doc = readCredentialsFromCache()
+	const idx = doc.credentials.findIndex(
+		(c) => c.address === entry.address.toLowerCase(),
+	)
+	const merged: CachedCredential = {
+		...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: string
+): CachedCredential | undefined {
+	const doc = readCredentialsFromCache()
+	const lc = address.toLowerCase()
+	return doc.credentials.find((c) => c.address === lc)
+}
+
+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 function suggestCredentialForDir(
+	dir: string,
+	creds: CachedCredential[] = readCredentialsFromCache().credentials,
+): CredentialSuggestion | undefined {
+	if(creds.length === 0) {
+		return undefined
+	}
+
+	const byNewest = (a: CachedCredential, b: CachedCredential) => {
+		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: string): string | undefined {
+	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/src/mcp/tools/credentials/env-file.ts

@@ -0,0 +1,101 @@
+import {
+	appendFileSync,
+	chmodSync,
+	existsSync,
+	readFileSync,
+	writeFileSync,
+} from 'node:fs'
+import { join } from 'node:path'
+
+const PRIVATE_KEY = 'RECLAIM_PRIVATE_KEY'
+const GITIGNORE_LINE = '.env'
+
+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 function writeAppCredentialsToEnv(
+	projectDir: string,
+	privateKey: string,
+): EnvWriteResult {
+	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: string,
+): string | undefined {
+	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: string[], key: string, value: string) {
+	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: string, line: string): boolean {
+	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/src/mcp/tools/credentials/import.ts

@@ -0,0 +1,72 @@
+import { deriveFromPrivateKey } from '@reclaimprotocol/client'
+import { findProjectRoot } from '../../../paths.ts'
+import { defineTool, type RegisteredTool } from '../../server.ts'
+import { persistCredentialLocally } from './register.ts'
+
+export function importTool(): RegisteredTool {
+	return defineTool<{
+		privateKey: string
+		label?: string
+		projectDir?: string
+		writeEnv?: boolean
+	}>(
+		{
+			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/src/mcp/tools/credentials/issue.ts

@@ -0,0 +1,107 @@
+import { generateKeypair } from '@reclaimprotocol/client'
+import { findProjectRoot } from '../../../paths.ts'
+import { defineTool, type RegisteredTool } from '../../server.ts'
+import { findCredentialFromCachedBy } from './cache.ts'
+import { persistCredentialLocally } from './register.ts'
+
+export function issueTool(): RegisteredTool {
+	return defineTool<{
+		reuseCachedAppPk?: string
+		label?: string
+		projectDir?: string
+		writeEnv?: boolean
+	}>(
+		{
+			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: { address: string, privateKey: string } | undefined
+			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/src/mcp/tools/credentials/list-cached.ts

@@ -0,0 +1,66 @@
+import { findProjectRoot } from '../../../paths.ts'
+import { defineTool, type RegisteredTool } from '../../server.ts'
+import { readCredentialsFromCache, suggestCredentialForDir } from './cache.ts'
+
+export function listCachedTool(): RegisteredTool {
+	return defineTool<Record<string, never>>(
+		{
+			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/src/mcp/tools/credentials/register.ts

@@ -0,0 +1,49 @@
+import type { EthKeypair } from '@reclaimprotocol/client'
+import { type CachedCredential, upsertCredential } from './cache.ts'
+import { type EnvWriteResult, writeAppCredentialsToEnv } 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 function persistCredentialLocally(
+	keypair: EthKeypair,
+	label: string | undefined,
+	projectDir: string,
+	writeEnv = true,
+): PersistedCredential {
+	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/src/mcp/tools/credentials/resolve-owner-key.ts

@@ -0,0 +1,78 @@
+import { deriveFromPrivateKey } from '@reclaimprotocol/client'
+import { findProjectRoot } from '../../../paths.ts'
+import { defineTool, type RegisteredTool } from '../../server.ts'
+import { suggestCredentialForDir } from './cache.ts'
+import { readPrivateKeyFromEnvFile } from './env-file.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 function resolveOwnerKeyTool(): RegisteredTool {
+	return defineTool<Record<string, never>>(
+		{
+			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/src/mcp/tools/credentials/session-cache.ts

@@ -0,0 +1,31 @@
+import { ConfigStore } from '../../../config/store.ts'
+
+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 function writeSession(session: CachedSession) {
+	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(): CachedSession | undefined {
+	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
+}