@reclaimprotocol/agent 0.1.1-dev.1 → 0.1.2

package/src/mcp/tools/credentials/env-file.ts

@@ -1,101 +0,0 @@
-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

@@ -1,72 +0,0 @@
-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

@@ -1,107 +0,0 @@
-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

@@ -1,66 +0,0 @@
-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

@@ -1,49 +0,0 @@
-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

@@ -1,78 +0,0 @@
-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/status.ts

@@ -1,82 +0,0 @@
-import {
-	deriveFromPrivateKey,
-	type ReclaimClient,
-} from '@reclaimprotocol/client'
-import assert from 'node:assert'
-import { findProjectRoot } from '../../../paths.ts'
-import { defineTool, type RegisteredTool } from '../../server.ts'
-import { suggestCredentialForDir } from './cache.ts'
-
-export function statusTool(client: ReclaimClient): RegisteredTool {
-	return defineTool<{ address?: string }>(
-		{
-			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/src/types/openapi.ts

@@ -1,7 +0,0 @@
-import type { components } from '@reclaimprotocol/client'
-
-export type CredentialAttachSession =
-	components['schemas']['CredentialAttachSession']
-export type CreateProviderVersionRequest =
-	components['schemas']['CreateProviderVersionRequest']
-export type ProviderVersionRef = components['schemas']['ProviderVersionRef']