@reclaimprotocol/agent 0.1.0 → 0.1.1

package/src/mcp/tools/authenticate/eth-key.ts

@@ -0,0 +1,182 @@
+/**
+ * Eth proof-owner key resolution — the raw secp256k1 private key passed to
+ * attestor-core when the agent creates a local claim. It's a plain 0x-hex
+ * Ethereum private key (no PEM), resolved from, in order:
+ *
+ *   1. `process.env.RECLAIM_PRIVATE_KEY` — a 0x-hex 32-byte scalar.
+ *   2. A `.env` file in the project root — its `RECLAIM_PRIVATE_KEY=0x…` line.
+ *   3. A key file holding the raw 0x-hex scalar, at `RECLAIM_PRIVATE_KEY_FILE`
+ *      (absolute or project-relative).
+ *   4. Absent — the caller offers to generate one or asks the dev for a key.
+ *
+ * Generated/imported keys are written to the project `.env` (mode 0600, and the
+ * file is added to `.gitignore`). NO `~/.reclaim` caching. This is a LOCAL
+ * signing key only — unrelated to org auth (the org secret) or encryption
+ * (the X25519 decrypt key).
+ */
+import { deriveFromPrivateKey } from '@reclaimprotocol/client'
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { isAbsolute, join } from 'node:path'
+import { findProjectRoot } from '../../../paths.ts'
+
+const ENV_VAR = 'RECLAIM_PRIVATE_KEY'
+/** The dotenv file the agent reads from / writes the key to. */
+export const ENV_FILE = '.env'
+
+/** Where the resolved eth key came from. */
+export type EthKeySource = 'env' | 'dotenv' | 'file'
+
+export type ResolvedEthKey = {
+	/** Raw 0x-hex 32-byte scalar. */
+	privateKey: string
+	/** Lowercase eth address derived from the scalar. */
+	address: string
+	source: EthKeySource
+	/** Absolute path the key was read from (for `dotenv` / `file` sources). */
+	path?: string
+}
+
+/** Validate + normalize a raw Ethereum private key to lowercase 0x-hex. */
+export function normalizeEthHex(value: string): string {
+	const v = value.trim().replace(/^['"]|['"]$/g, '')
+	if(!/^(0x)?[0-9a-fA-F]{64}$/.test(v)) {
+		throw new Error(
+			'not a valid Ethereum private key (expected a 32-byte / 64-hex scalar)',
+		)
+	}
+
+	return '0x' + v.replace(/^0x/, '').toLowerCase()
+}
+
+/** Read `RECLAIM_PRIVATE_KEY` from a dotenv file (simple KEY=VALUE parse). */
+function readDotenvKey(path: string): string | undefined {
+	if(!existsSync(path)) {
+		return undefined
+	}
+
+	for(const line of readFileSync(path, 'utf8').split('\n')) {
+		const m = line.match(/^\s*RECLAIM_PRIVATE_KEY\s*=\s*(.+?)\s*$/)
+		if(m) {
+			return m[1]
+		}
+	}
+
+	return undefined
+}
+
+/** The explicit raw-hex key-file path, if `RECLAIM_PRIVATE_KEY_FILE` is set. */
+export function ethKeyFilePath(
+	projectDir = findProjectRoot(process.cwd()),
+): string | undefined {
+	const p = process.env.RECLAIM_PRIVATE_KEY_FILE
+	if(!p) {
+		return undefined
+	}
+
+	return isAbsolute(p) ? p : join(projectDir, p)
+}
+
+function resolved(
+	privateKey: string,
+	source: EthKeySource,
+	path?: string,
+): ResolvedEthKey {
+	return {
+		privateKey,
+		address: deriveFromPrivateKey(privateKey).address,
+		source,
+		...(path ? { path } : {}),
+	}
+}
+
+/**
+ * Resolve the eth proof-owner key without prompting. Returns `undefined` when
+ * no key is configured anywhere — the caller decides whether to generate or
+ * ask for one (see `resolve_owner_key`).
+ */
+export function resolveEthKey(
+	projectDir = findProjectRoot(process.cwd()),
+): ResolvedEthKey | undefined {
+	const env = process.env.RECLAIM_PRIVATE_KEY
+	if(env?.trim()) {
+		return resolved(normalizeEthHex(env), 'env')
+	}
+
+	const envPath = join(projectDir, ENV_FILE)
+	const fromDotenv = readDotenvKey(envPath)
+	if(fromDotenv) {
+		return resolved(normalizeEthHex(fromDotenv), 'dotenv', envPath)
+	}
+
+	const keyFile = ethKeyFilePath(projectDir)
+	if(keyFile && existsSync(keyFile)) {
+		return resolved(
+			normalizeEthHex(readFileSync(keyFile, 'utf8')),
+			'file',
+			keyFile,
+		)
+	}
+
+	return undefined
+}
+
+/**
+ * Resolve the eth proof-owner private key (0x-hex) or throw a clear, actionable
+ * error. Used by the proof flow that can't proceed without a signing key.
+ */
+export function requireEthPrivateKey(
+	projectDir = findProjectRoot(process.cwd()),
+): string {
+	const r = resolveEthKey(projectDir)
+	if(!r) {
+		throw new Error(
+			'No eth proof-owner key found. Set RECLAIM_PRIVATE_KEY (0x-hex), add a '
+				+ `RECLAIM_PRIVATE_KEY=0x… line to ${join(projectDir, ENV_FILE)}, or `
+				+ 'point RECLAIM_PRIVATE_KEY_FILE at a file holding the raw hex. Run '
+				+ 'issue_credentials to generate one, or import_credentials to use a '
+				+ 'key you already hold.',
+		)
+	}
+
+	return r.privateKey
+}
+
+/** Append `entry` to the project `.gitignore` if not already present. */
+function ensureGitignored(projectDir: string, entry: string): void {
+	const path = join(projectDir, '.gitignore')
+	const current = existsSync(path) ? readFileSync(path, 'utf8') : ''
+	if(current.split('\n').some((l) => l.trim() === entry)) {
+		return
+	}
+
+	const prefix = current && !current.endsWith('\n') ? '\n' : ''
+	writeFileSync(path, current + prefix + entry + '\n')
+}
+
+/**
+ * Persist a raw eth private key to the project `.env` as
+ * `RECLAIM_PRIVATE_KEY=0x…` (upsert; mode 0600; `.env` added to `.gitignore`).
+ * Used by `issue_credentials` (generate) and `import_credentials` (supplied
+ * hex). Returns the derived address and the `.env` path.
+ */
+export function writeEthKey(
+	privateKeyHex: string,
+	projectDir = findProjectRoot(process.cwd()),
+): { path: string, address: string } {
+	const hex = normalizeEthHex(privateKeyHex)
+	const envPath = join(projectDir, ENV_FILE)
+	const line = `${ENV_VAR}=${hex}`
+	const existing = existsSync(envPath) ? readFileSync(envPath, 'utf8') : ''
+	const re = new RegExp(`^\\s*${ENV_VAR}\\s*=.*$`, 'm')
+	let next: string
+	if(re.test(existing)) {
+		next = existing.replace(re, line)
+	} else {
+		const prefix = existing && !existing.endsWith('\n') ? '\n' : ''
+		next = existing + prefix + line + '\n'
+	}
+
+	writeFileSync(envPath, next, { mode: 0o600 })
+	ensureGitignored(projectDir, ENV_FILE)
+	return { path: envPath, address: deriveFromPrivateKey(hex).address }
+}

package/src/mcp/tools/authenticate/import.ts

@@ -0,0 +1,73 @@
+import { readFileSync } from 'node:fs'
+import { findProjectRoot } from '../../../paths.ts'
+import { defineTool, type RegisteredTool } from '../../server.ts'
+import { writeEthKey } from './eth-key.ts'
+
+export function importTool(): RegisteredTool {
+	return defineTool<{
+		privateKey?: string
+		keyFile?: string
+		projectDir?: string
+	}>(
+		{
+			name: 'import_credentials',
+			description:
+				'Import an eth proof-owner key the dev already holds and persist it ' +
+				'to the project `.env` as RECLAIM_PRIVATE_KEY=0x… (mode 0600; `.env` ' +
+				'added to .gitignore). Provide EITHER `privateKey` (raw 0x-hex, 64 ' +
+				'chars) OR `keyFile` (path to a file holding the raw 0x-hex key). ' +
+				'The address is derived locally; the private key is never ' +
+				'returned. This is a local signing key only (not registered ' +
+				'with any server, ' +
+				'unrelated to org auth or encryption).',
+			inputSchema: {
+				type: 'object',
+				properties: {
+					privateKey: {
+						type: 'string',
+						pattern: '^0x?[0-9a-fA-F]{64}$',
+						description:
+							'Raw Ethereum private key, 0x-prefixed hex (64 hex chars).',
+					},
+					keyFile: {
+						type: 'string',
+						description:
+							'Path to a file containing the raw 0x-hex private key ' +
+							'(absolute or project-relative).',
+					},
+					projectDir: {
+						type: 'string',
+						description:
+							'Project directory whose `.env` the key is written to. ' +
+							'Defaults to the closest ancestor of cwd containing .git or ' +
+							'package.json.',
+					},
+				},
+			},
+		},
+		async(args) => {
+			if(!args.privateKey && !args.keyFile) {
+				throw new Error('Provide either `privateKey` (0x-hex) or `keyFile`.')
+			}
+
+			if(args.privateKey && args.keyFile) {
+				throw new Error('Provide only one of `privateKey` or `keyFile`.')
+			}
+
+			const projectDir = findProjectRoot(args.projectDir || process.cwd())
+			const privateKeyHex = args.keyFile
+				? readFileSync(args.keyFile, 'utf8')
+				: args.privateKey!
+			const { path, address } = writeEthKey(privateKeyHex, projectDir)
+
+			return {
+				address,
+				path,
+				note:
+					'Eth proof-owner key written to .env as RECLAIM_PRIVATE_KEY ' +
+					'(mode 0600). resolve_owner_key resolves it from .env. Keep .env ' +
+					'secret — it has been added to .gitignore.',
+			}
+		},
+	)
+}

package/src/mcp/tools/authenticate/index.ts

@@ -0,0 +1,4 @@
+// Barrel for the credential tool group: local eth proof-owner key (env/PEM)
+// and the org-token-authenticated builder tools. Import from here.
+export { buildCredentialTools, buildLocalCredentialTools } from './build.ts'
+export { readSession } from './session-cache.ts'

package/src/mcp/tools/authenticate/issue.ts

@@ -0,0 +1,50 @@
+import { generateKeypair } from '@reclaimprotocol/client'
+import { findProjectRoot } from '../../../paths.ts'
+import { defineTool, type RegisteredTool } from '../../server.ts'
+import { writeEthKey } from './eth-key.ts'
+
+export function issueTool(): RegisteredTool {
+	return defineTool<{ projectDir?: string }>(
+		{
+			name: 'issue_credentials',
+			description:
+				'Generate a fresh secp256k1 eth proof-owner key-pair (the key ' +
+				'that signs local claim creation) and write the raw private key to ' +
+				'the project `.env` as RECLAIM_PRIVATE_KEY=0x… (mode 0600; `.env` ' +
+				'added to .gitignore). This is a LOCAL signing key only — it is NOT ' +
+				'registered with any server and is unrelated to org auth (the org ' +
+				'secret) or encryption (the X25519 decrypt key). ALWAYS confirm with ' +
+				'the dev before generating a new key. After writing, run_proof picks ' +
+				'it up automatically via resolve_owner_key. The private key is never ' +
+				'returned in the response.',
+			inputSchema: {
+				type: 'object',
+				properties: {
+					projectDir: {
+						type: 'string',
+						description:
+							'Project directory whose `.env` the key is written to. ' +
+							'Defaults to the closest ancestor of cwd containing .git or ' +
+							'package.json.',
+					},
+				},
+			},
+		},
+		async(args) => {
+			const projectDir = findProjectRoot(args.projectDir || process.cwd())
+			const keypair = generateKeypair()
+			const { path, address } = writeEthKey(keypair.privateKey, projectDir)
+
+			return {
+				address,
+				path,
+				note:
+					'Eth proof-owner key written to .env as RECLAIM_PRIVATE_KEY ' +
+					'(mode 0600); the private key is NOT in this response on purpose. ' +
+					'resolve_owner_key will now resolve it from .env (or set ' +
+					'RECLAIM_PRIVATE_KEY in the environment to override). Keep .env ' +
+					'secret — it has been added to .gitignore.',
+			}
+		},
+	)
+}

package/src/mcp/tools/authenticate/resolve-owner-key.ts

@@ -0,0 +1,60 @@
+import { join } from 'node:path'
+import { findProjectRoot } from '../../../paths.ts'
+import { defineTool, type RegisteredTool } from '../../server.ts'
+import { ENV_FILE, resolveEthKey } from './eth-key.ts'
+
+/**
+ * Decide which eth proof-owner key `run_proof` should sign with, BEFORE
+ * calling it. The key is a raw 0x-hex Ethereum private key, resolved (no
+ * `~/.reclaim` cache) from:
+ *   1. `RECLAIM_PRIVATE_KEY` in the MCP env
+ *   2. a `RECLAIM_PRIVATE_KEY=0x…` line in the project `.env`
+ *   3. a file at `RECLAIM_PRIVATE_KEY_FILE` holding the raw hex
+ *   4. none → ask the dev to generate (issue_credentials) or provide one
+ *      (import_credentials), then call again.
+ * Never returns the private key — only the derived address.
+ */
+export function resolveOwnerKeyTool(): RegisteredTool {
+	return defineTool<Record<string, never>>(
+		{
+			name: 'resolve_owner_key',
+			description:
+				'Resolve which eth proof-owner key run_proof should sign with — ' +
+				'call this BEFORE run_proof. Checks, in order: RECLAIM_PRIVATE_KEY ' +
+				'in the MCP env, a RECLAIM_PRIVATE_KEY=0x… line in the project .env, ' +
+				'then a file at RECLAIM_PRIVATE_KEY_FILE holding the raw hex. ' +
+				'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 generate one ' +
+				'(issue_credentials) or import one they already hold ' +
+				'(import_credentials, accepts 0x-hex or a key-file path), and call ' +
+				'resolve_owner_key again. Never exposes the private key.',
+			inputSchema: { type: 'object', properties: {} },
+		},
+		async() => {
+			const projectDir = findProjectRoot(process.cwd())
+			const resolved = resolveEthKey(projectDir)
+			if(resolved) {
+				return {
+					ready: true,
+					address: resolved.address,
+					source: resolved.source,
+					...(resolved.path ? { path: resolved.path } : {}),
+				}
+			}
+
+			return {
+				ready: false,
+				message:
+					'No eth proof-owner key available — no RECLAIM_PRIVATE_KEY in the ' +
+					`env, no RECLAIM_PRIVATE_KEY in ${join(projectDir, ENV_FILE)}, and ` +
+					'no RECLAIM_PRIVATE_KEY_FILE. Ask the dev to generate one via ' +
+					'issue_credentials, or import one they already hold via ' +
+					'import_credentials (0x-hex or a key-file path). Then call ' +
+					'resolve_owner_key again and pass its address to run_proof as ' +
+					'ownerAddress.',
+			}
+		},
+	)
+}

package/src/mcp/tools/index.ts

@@ -0,0 +1,6 @@
+// Top-level barrel for every MCP tool group. The MCP server (start.ts) and the
+// package entry (src/index.ts) import tool builders from here, never from the
+// individual tool files.
+export * from './agent/index.ts'
+export * from './authenticate/index.ts'
+export * from './verification/index.ts'

package/src/mcp/tools/verification/build.ts

@@ -0,0 +1,16 @@
+import type { RegisteredTool } from '../../server.ts'
+import { verificationResultTool } from './result.ts'
+
+/**
+ * Builder-mode verification tools: higher-level orchestrations over the
+ * generated API surface. `get_verification_result` authenticates with the org
+ * token, checks status, pulls the stored payload, and decrypts it locally with
+ * the optional X25519 key — a flow the generated raw-API tools can't express
+ * (the decryption key never leaves the consumer). Diagnosis is left to the
+ * agent over the generated tools (`get_verification_session`,
+ * `list_verification_events`, `list_verification_deliveries`), whose
+ * descriptions carry the lifecycle and delivery semantics.
+ */
+export function buildVerificationTools(): RegisteredTool[] {
+	return [verificationResultTool()]
+}

package/src/mcp/tools/verification/index.ts

@@ -0,0 +1,2 @@
+// Barrel for the verification tool group (result retrieval + decryption).
+export { buildVerificationTools } from './build.ts'

package/src/mcp/tools/verification/result.ts

@@ -0,0 +1,155 @@
+import {
+	createReclaim,
+	decryptCallback,
+	type DecryptionKey,
+	DEFAULT_BASE_URL,
+	verifyResultFull,
+} from '@reclaimprotocol/client'
+import assert from 'node:assert'
+import { defineTool, type RegisteredTool } from '../../server.ts'
+import { resolveDecryptionKey } from '../authenticate/decrypt-key.ts'
+
+/** Statuses that can carry a submitted (terminal) result. `expired`/`pending`
+ *  never have one. */
+const TERMINAL = new Set(['success', 'rejected', 'error'])
+
+/**
+ * Resolve the org secret used to authenticate verification reads. Auth is a
+ * single per-org bearer secret (`rorg_…`), not an eth signature — read it from
+ * `RECLAIM_ORG_SECRET`.
+ */
+function resolveOrgSecret(): string {
+	const secret = process.env.RECLAIM_ORG_SECRET?.trim()
+	assert(
+		secret,
+		new Error(
+			'RECLAIM_ORG_SECRET is not set. Verification reads authenticate with ' +
+				'the org secret (rorg_…) — issue one from the dashboard ' +
+				'(POST /orgs/{orgId}/token) and export it as RECLAIM_ORG_SECRET.',
+		),
+	)
+	return secret
+}
+
+/**
+ * `get_verification_result` — check a session's status and, once a result has
+ * been submitted, pull the stored payload(s) and verify locally. Auth is the
+ * org token; delivery is org-scoped. Each stored payload is either the
+ * plaintext signed JWS (when the org has no encryption credential) or a compact
+ * JWE (RFC 7516, ECDH-ES+A256GCM over X25519) that we decrypt here with the
+ * optional X25519 key (the `reclaim-decrypt.pem` PEM in the project). The
+ * Builder only ever relays the payload — decryption, when needed, happens
+ * here.
+ */
+export function verificationResultTool(): RegisteredTool {
+	return defineTool<{ sessionId: string }>(
+		{
+			name: 'get_verification_result',
+			description:
+				'Check a verification session and return its result when ready. ' +
+				'Authenticates with the org secret (RECLAIM_ORG_SECRET). Fetches the ' +
+				'session status; if it is terminal and a result has been submitted, ' +
+				'pulls the stored result(s) and verifies them locally. Encrypted ' +
+				'deliveries (compact JWE over X25519) are decrypted with your ' +
+				'optional decryption key (the reclaim-decrypt.pem PEM in the ' +
+				'project); plaintext deliveries are read directly. Returns ' +
+				'`ready: false` while the session is still pending or no result has ' +
+				'been delivered yet. Use list_verification_events for the full ' +
+				'lifecycle log.',
+			inputSchema: {
+				type: 'object',
+				required: ['sessionId'],
+				properties: {
+					sessionId: {
+						type: 'string',
+						description:
+							'The verification session id from create_verification_session.',
+					},
+				},
+			},
+		},
+		async(args) => {
+			const orgSecret = resolveOrgSecret()
+			// Optional X25519 decryption key — absent ⇒ plaintext-only.
+			const decryptionKey: DecryptionKey | undefined =
+				await resolveDecryptionKey()
+
+			const reclaim = createReclaim({
+				baseUrl: process.env.RECLAIM_API_URL || DEFAULT_BASE_URL,
+				orgSecret,
+			})
+
+			const sessionRes = await reclaim.api('GetVerificationSession', {
+				params: { sessionId: args.sessionId },
+			})
+			const status = sessionRes.data.status
+
+			if(!TERMINAL.has(status)) {
+				return { sessionId: args.sessionId, status, ready: false }
+			}
+
+			const resultRes = await reclaim.api('GetVerificationResult', {
+				params: { sessionId: args.sessionId },
+			})
+			const { items } = resultRes.data
+
+			if(!items.length) {
+				return {
+					sessionId: args.sessionId,
+					status,
+					ready: false,
+					note: 'Session is terminal but no result has been submitted yet.',
+				}
+			}
+
+			// Each item's `payload` is a compact JWE (encrypted to the org's
+			// credential) or the plaintext signed JWS, as raw text. `decryptCallback`
+			// branches on the body shape; an encrypted delivery with no key throws
+			// a clear error, which we surface per-subscription rather than skip.
+			const results: unknown[] = []
+			const undecryptable: string[] = []
+			for(const item of items) {
+				let jws
+				try {
+					jws = await decryptCallback(decryptionKey, item.payload)
+				} catch(err) {
+					undecryptable.push(item.subscriptionId)
+					void err
+					continue
+				}
+
+				const outcome = await verifyResultFull(jws, {
+					expectedReclaimSessionId: args.sessionId,
+				})
+				results.push({
+					subscriptionId: item.subscriptionId,
+					valid: outcome.valid,
+					reason: outcome.reason,
+					payload: outcome.payload,
+					proofs: outcome.proofs,
+				})
+			}
+
+			if(!results.length) {
+				return {
+					sessionId: args.sessionId,
+					status,
+					ready: false,
+					note:
+						'A result was stored, but no payload could be read — it is ' +
+						'corrupt, or encrypted (JWE) to a key this consumer does not ' +
+						'hold. Place an X25519 PEM (reclaim-decrypt.pem) in the ' +
+						'project matching the org credential.',
+				}
+			}
+
+			return {
+				sessionId: args.sessionId,
+				status,
+				ready: true,
+				results,
+				...(undecryptable.length ? { undecryptable } : {}),
+			}
+		},
+	)
+}

package/src/old/client.ts

@@ -25,6 +25,9 @@ export interface RegisterProviderBody {
 	description?: string
 	loginUrl: string
 	geoLocation?: string
+	/** Provider-level flag on the old backend (defaults false there; the
+	 *  translator sends `true` to match the builder default). */
+	useProxy?: boolean
 	providerType?: 'PRIVATE' | 'PUBLIC'
 	requestData: unknown[]
 }

package/src/old/instructions.ts

@@ -2,29 +2,14 @@
  * MCP server instructions shown to the LLM when running in OLD-devtools mode
  * (`USE_OLD_DEVTOOLS` unset or not `false`). Describes the REDUCED tool
  * surface — there are no org/credential-link/review flows and no generated
- * API tools here. Must not mention disabled tools.
+ * API tools here. The prose lives in `skill/old-mode.md` (published via the
+ * `files` array); the path resolves identically from `src/old` (dev) and
+ * `lib/old` (published).
  */
-export const OLD_MODE_INSTRUCTIONS =
-	'This server is running against the LEGACY Reclaim devtools backend ' +
-	'(temporary, while the new builder backend is in development), so its ' +
-	'capabilities are intentionally limited.\n\n' +
-	'Provider-authoring flow:\n' +
-	'1. `reclaim_authenticate` — by default opens the dashboard in Chrome, ' +
-	'waits for you to sign in, captures the token automatically, and closes ' +
-	'the tab (or paste a `token` / pass an eth `ethAddress` to skip the ' +
-	'browser). Do this once before publishing or listing.\n' +
-	'2. `attach_chrome` → `start_capture` → drive the page (`navigate`, ' +
-	'`wait_for_page`) → inspect (`list_requests`, `get_request`, ' +
-	'`find_requests_containing`).\n' +
-	'3. `propose_provider` to draft a provider, `replay_request` to ' +
-	'pre-flight, `run_proof` to verify with the attestor. OPRF/`hash` ' +
-	'redactions are optional and supported.\n' +
-	'4. `create_provider_version_from_capture` to publish. With NO ' +
-	'`providerId` it REGISTERS A NEW provider (re-running creates a ' +
-	'duplicate); pass a ' +
-	'`providerId` from `get_me_providers` to add a new version to an existing ' +
-	'provider instead.\n' +
-	'5. `get_me_providers` lists the providers you own (the only ' +
-	'provider-listing tool available in this mode).\n\n' +
-	'Only GET/POST endpoints can be captured into providers here. There is no ' +
-	'organization, credential-linking, or public-review workflow in this mode.'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+export const OLD_MODE_INSTRUCTIONS = readFileSync(
+	fileURLToPath(new URL('../../skill/old-mode.md', import.meta.url)),
+	'utf8',
+).trim()