@reclaimprotocol/agent 0.1.5 → 0.1.7

package/src/mcp/tools/agent/proof.ts

@@ -3,13 +3,10 @@ import { join } from 'node:path'
 import { agentTraceEnabled } from '../../../consts.ts'
 import { reclaimHomeDirPath } from '../../../paths.ts'
 import {
-	runAttestorProof,
+	type ProofResult,
 	tailLogs,
 	warnsAndErrors,
 } from '../../../proof/attestor.ts'
-import type { ReclaimProvider } from '../../../provider/schema.ts'
-import { defineTool, type RegisteredTool } from '../../server.ts'
-import type { SecretStore } from './propose.ts'
 
 function claimsDir(): string {
 	return join(reclaimHomeDirPath(), 'claims')
@@ -98,170 +95,100 @@ function isLikelyByteArray(v: unknown[]): boolean {
 	return true
 }
 
-export function proofTool(secrets: SecretStore): RegisteredTool {
-	return defineTool<{
-		provider: unknown
-		secretParamsRef?: string
-		attestorUrl?: string
-		ownerAddress?: string
-	}>(
-		{
-			name: 'run_proof',
-			description:
-				'Run a full zkTLS proof through the Reclaim attestor SDK. ' +
-				'Use only after replay_request ' +
-				'returns matchesOriginal=true — attestor calls are expensive. ' +
-				'Writes the full claim to ' +
-				'~/.reclaim/claims/<timestamp>.json and ' +
-				'returns identifier + extractedParameters + ' +
-				'claimPath + a prettified `claim` field ' +
-				'(request dropped, byte arrays as base64) suitable ' +
-				'for displaying directly to the dev. ' +
-				'When the MCP server is started with ' +
-				'`RECLAIM_AGENT_TRACE=1`, ALSO writes ' +
-				'a per-call diagnostic dump (input provider, ' +
-				'sentParams the SDK saw post-substitution, ' +
-				'FULL attestor log stream, result) to ' +
-				'~/.reclaim/proof-runs/<timestamp>.json and ' +
-				'returns the path as `runLogPath`. ' +
-				'`attestorUrl` overrides the default attestor URL only when the dev ' +
-				'supplies a specific ' +
-				'alternative — do NOT invent backup URLs ' +
-				'(there is one live public attestor right now; ' +
-				'surface real errors to the dev instead of guessing). ' +
-				'`ownerAddress` (the credential to sign with) is REQUIRED — ' +
-				'call resolve_owner_key first to obtain it, then pass it here. ' +
-				'errorKind="missing-owner-key" means that address has no known ' +
-				'private key; re-run resolve_owner_key or issue/import a credential.',
-			inputSchema: {
-				type: 'object',
-				properties: {
-					provider: { type: 'object', properties: {} },
-					secretParamsRef: { type: 'string' },
-					attestorUrl: { type: 'string' },
-					ownerAddress: {
-						type: 'string',
-						pattern: '^0x[0-9a-fA-F]{40}$',
-						description:
-							'ETH address of the credential to sign the claim with. ' +
-							'Get it from resolve_owner_key first. The private key is ' +
-							'resolved locally (cache / env / .env) — never passed here.',
-					},
-				},
-				required: ['provider', 'ownerAddress'],
-			},
-		},
-		async({ provider, secretParamsRef, attestorUrl, ownerAddress }) => {
-			let resolved: Record<string, string> = {}
-			if(secretParamsRef !== undefined) {
-				const r = secrets.resolve(secretParamsRef)
-				if(!r) {
-					throw new Error(
-						`unknown secretParamsRef "${secretParamsRef}" — ` +
-						'the MCP server has restarted or reset_session was called. ' +
-							'Re-run propose_provider to mint a fresh ref.',
-					)
-				}
-
-				resolved = r
-			}
-
-			const result = await runAttestorProof(
-				provider as ReclaimProvider,
-				resolved,
-				{ attestorUrl, ownerAddress },
-			)
-
-			// Persist the full claim to disk for the dev to inspect/share.
-			let claimPath: string | undefined
-			if(result.proof !== undefined && result.proof !== null) {
-				try {
-					mkdirSync(claimsDir(), { recursive: true })
-					claimPath = join(claimsDir(), `${Date.now()}.json`)
-					writeFileSync(
-						claimPath,
-						JSON.stringify(result.proof, null, 2),
-						'utf8',
-					)
-				} catch{
-					// Persistence is best-effort; don't fail the proof for it.
-					claimPath = undefined
-				}
-			}
+/**
+ * The MCP's rich `run_proof` view: persist the full claim to disk, return
+ * identifier + extractedParameters + a prettified claim (request dropped, byte
+ * arrays as base64) + trimmed logs, and — under `RECLAIM_AGENT_TRACE=1` — a
+ * forensic run dump. This is the developer-facing shape; the cloud backend
+ * projects the same {@link ProofResult} to a lean summary instead.
+ */
+export function shapeRichProofResult(
+	result: ProofResult,
+	opts: { provider: unknown, hasSecrets: boolean, attestorUrl?: string },
+): Record<string, unknown> {
+	// Persist the full claim to disk for the dev to inspect/share.
+	let claimPath: string | undefined
+	if(result.proof !== undefined && result.proof !== null) {
+		try {
+			mkdirSync(claimsDir(), { recursive: true })
+			claimPath = join(claimsDir(), `${Date.now()}.json`)
+			writeFileSync(claimPath, JSON.stringify(result.proof, null, 2), 'utf8')
+		} catch{
+			// Persistence is best-effort; don't fail the proof for it.
+			claimPath = undefined
+		}
+	}
 
-			const out: Record<string, unknown> = {
-				verified: result.verified,
-				extractedValue: result.extractedValue,
-				extractedParameters: result.extractedParameters,
-			}
-			if(result.identifier !== undefined) {
-				out.identifier = result.identifier
-			}
+	const out: Record<string, unknown> = {
+		verified: result.verified,
+		extractedValue: result.extractedValue,
+		extractedParameters: result.extractedParameters,
+	}
+	if(result.identifier !== undefined) {
+		out.identifier = result.identifier
+	}
 
-			if(result.owner !== undefined) {
-				out.owner = result.owner
-			}
+	if(result.owner !== undefined) {
+		out.owner = result.owner
+	}
 
-			if(claimPath !== undefined) {
-				out.claimPath = claimPath
-			}
+	if(claimPath !== undefined) {
+		out.claimPath = claimPath
+	}
 
-			if(result.proof !== undefined && result.proof !== null) {
-				out.claim = prettifyClaim(result.proof)
-			}
+	if(result.proof !== undefined && result.proof !== null) {
+		out.claim = prettifyClaim(result.proof)
+	}
 
-			if(result.error !== undefined) {
-				out.error = result.error
-			}
+	if(result.error !== undefined) {
+		out.error = result.error
+	}
 
-			if(result.errorKind !== undefined) {
-				out.errorKind = result.errorKind
-			}
+	if(result.errorKind !== undefined) {
+		out.errorKind = result.errorKind
+	}
 
-			// Trim the LLM-visible logs — full stream goes to runLogPath.
-			if(result.attestorLogs !== undefined && result.attestorLogs.length > 0) {
-				out.attestorLogs = result.verified
-					? warnsAndErrors(result.attestorLogs)
-					: tailLogs(result.attestorLogs)
-				if((out.attestorLogs as unknown[]).length === 0) {
-					delete out.attestorLogs
-				}
-			}
+	// Trim the LLM-visible logs — full stream goes to runLogPath.
+	if(result.attestorLogs !== undefined && result.attestorLogs.length > 0) {
+		out.attestorLogs = result.verified
+			? warnsAndErrors(result.attestorLogs)
+			: tailLogs(result.attestorLogs)
+		if((out.attestorLogs as unknown[]).length === 0) {
+			delete out.attestorLogs
+		}
+	}
 
-			if(result.sentParams !== undefined) {
-				out.sentParams = result.sentParams
-			}
+	if(result.sentParams !== undefined) {
+		out.sentParams = result.sentParams
+	}
 
-			// Persist a diagnostic dump for forensics — gated behind
-			// RECLAIM_AGENT_TRACE=1 (matches the attestor logger capture).
-			// Off by default since happy-path runs don't need it; turn on
-			// when investigating proof failures and the file at runLogPath
-			// will carry the input provider, sentParams, full attestor log
-			// stream, and result.
-			if(agentTraceEnabled()) {
-				const runLogPath = writeProofRunDump({
-					provider,
-					hasSecretParamsRef: secretParamsRef !== undefined,
-					attestorUrl,
-					result: {
-						verified: result.verified,
-						error: result.error,
-						errorKind: result.errorKind,
-						extractedValue: result.extractedValue,
-						extractedParameters: result.extractedParameters,
-						identifier: result.identifier,
-						owner: result.owner,
-						sentParams: result.sentParams,
-						attestorLogs: result.attestorLogs,
-						claimPath,
-					},
-				})
-				if(runLogPath !== undefined) {
-					out.runLogPath = runLogPath
-				}
-			}
+	// Persist a diagnostic dump for forensics — gated behind
+	// RECLAIM_AGENT_TRACE=1 (matches the attestor logger capture). Off by
+	// default since happy-path runs don't need it; turn on when investigating
+	// proof failures and the file at runLogPath will carry the input provider,
+	// sentParams, full attestor log stream, and result.
+	if(agentTraceEnabled()) {
+		const runLogPath = writeProofRunDump({
+			provider: opts.provider,
+			hasSecretParamsRef: opts.hasSecrets,
+			attestorUrl: opts.attestorUrl,
+			result: {
+				verified: result.verified,
+				error: result.error,
+				errorKind: result.errorKind,
+				extractedValue: result.extractedValue,
+				extractedParameters: result.extractedParameters,
+				identifier: result.identifier,
+				owner: result.owner,
+				sentParams: result.sentParams,
+				attestorLogs: result.attestorLogs,
+				claimPath,
+			},
+		})
+		if(runLogPath !== undefined) {
+			out.runLogPath = runLogPath
+		}
+	}
 
-			return out
-		},
-	)
+	return out
 }

package/src/mcp/tools/agent/propose.ts

@@ -1,120 +1,128 @@
-import { randomUUID } from 'node:crypto'
-import { draftProvider } from '../../../provider/draft.ts'
+/**
+ * `propose_provider` — draft a provider (recipe + captured secrets) from ONE
+ * captured request, one match + redaction per target value. Authored once as a
+ * plain {@link RegisteredTool}; hosts pass their own backend resolver. The
+ * draft (recipe + real secret header values) is held server-side under an
+ * opaque `draftId`; the result carries only the secret-free provider.
+ */
+import { objectSchema, type ResolveBackend } from '../../../authoring/util.ts'
+import { draftProvider, type DraftTarget } from '../../../provider/draft.ts'
 import { OPRF_MAX_BYTES } from '../../../provider/matcher.ts'
 import type { OprfMode } from '../../../provider/schema.ts'
 import { verificationWarnings } from '../../../provider/verification-checks.ts'
-import { defineTool, type RegisteredTool } from '../../server.ts'
-import type { CaptureStore } from './capture.ts'
+import { defineTool, type RegisteredTool } from '../../../tools/registry.ts'
 
-export interface SecretStore {
-	put: (values: Record<string, string>) => string
-	resolve: (ref: string) => Record<string, string> | undefined
-	clear: () => void
-}
-
-export function makeSecretStore(): SecretStore {
-	const map = new Map<string, Record<string, string>>()
-	return {
-		put: (values) => {
-			const id = `sref_${randomUUID()}`
-			map.set(id, values)
-			return id
-		},
-		resolve: (ref) => map.get(ref),
-		clear: () => map.clear(),
-	}
-}
-
-export function proposeTool(
-	captures: CaptureStore,
-	secrets: SecretStore,
-): RegisteredTool {
-	return defineTool<{
-		captureId: string
-		requestId: string
-		target: string
-		name: string
-		hash?: OprfMode
-	}>(
+export function proposeTool(resolveBackend: ResolveBackend): RegisteredTool {
+	return defineTool<Record<string, unknown>>(
 		{
 			name: 'propose_provider',
 			description:
-				'Draft a Reclaim provider JSON from a captured request + ' +
-				'a target value. ' +
-				'Secret header values are stored server-side and replaced with an ' +
-				'opaque secretParamsRef ' +
-				'in the response — raw secret values never appear in tool output. ' +
-				"`hash` is opt-in: when set, the captured value is OPRF'd so " +
-				'the attestor never sees ' +
-				'cleartext. Skill should ask the dev first. `oprf-raw` ' +
-				'is the only variant that runs ' +
-				'without external deps; `oprf` needs gnark (Linux/macOS), ' +
-				'`oprf-mpc` needs a TEE attestor. ' +
-				'The response may include `verificationWarnings` — advisory ' +
-				'author-only decisions (e.g. a user-specific URL part needing ' +
-				'the {{context.<name>}}-vs-bare call). Surface each to the ' +
-				'dev verbatim and resolve before publishing.',
-			inputSchema: {
-				type: 'object',
-				properties: {
-					captureId: { type: 'string' },
+				'Draft a provider from ONE captured request. Pass `targets` (an '
+				+ 'array): one entry per value to extract, each with its `value` '
+				+ '(verbatim) and a distinct `name` (its param). The provider gets '
+				+ 'one match + redaction per target. Returns a draftId + recipe '
+				+ '(never secrets). Prefer a SINGLE request holding ALL values. '
+				+ 'Single-value shorthand: `target` + `name`. Per-target `hash` '
+				+ 'OPRF-hashes that value.',
+			inputSchema: objectSchema(
+				{
 					requestId: { type: 'string' },
-					target: { type: 'string' },
 					name: { type: 'string' },
+					targets: {
+						type: 'array',
+						items: {
+							type: 'object',
+							properties: {
+								value: { type: 'string' },
+								name: { type: 'string' },
+								hash: {
+									type: 'string',
+									enum: ['oprf-raw', 'oprf', 'oprf-mpc'],
+								},
+							},
+							required: ['value', 'name'],
+						},
+					},
+					target: { type: 'string' },
 					hash: { type: 'string', enum: ['oprf-raw', 'oprf', 'oprf-mpc'] },
 				},
-				required: ['captureId', 'requestId', 'target', 'name'],
-			},
+				['requestId', 'name'],
+			),
 		},
-		async({ captureId, requestId, target, name, hash }) => {
-			if(hash !== undefined && target.length > OPRF_MAX_BYTES) {
+		async(args) => {
+			const backend = resolveBackend(args)
+			const requestId = String(args.requestId)
+			const providerName = String(args.name)
+			const defaultHash = args.hash as OprfMode | undefined
+
+			// Explicit multi-value `targets`, else the single `target` shorthand.
+			const raw = Array.isArray(args.targets) ? args.targets : []
+			const targets: DraftTarget[] = raw.length
+				? raw.map((t) => {
+					const o = t as Record<string, unknown>
+					return {
+						value: String(o.value),
+						name: String(o.name),
+						...(typeof o.hash === 'string'
+							? { hash: o.hash as OprfMode }
+							: {}),
+					}
+				})
+				: typeof args.target === 'string'
+					? [{
+						value: args.target,
+						name: providerName,
+						...(defaultHash ? { hash: defaultHash } : {}),
+					}]
+					: []
+			if(targets.length === 0) {
 				throw new Error(
-					`OPRF caps hashed values at ${OPRF_MAX_BYTES} bytes; ` +
-					`got ${target.length}-byte target ` +
-					`"${target}". Try a tighter target ` +
-					'(e.g. just the relevant substring) or call ' +
-						'propose_provider without `hash`.',
+					'propose_provider needs a `target` value or a non-empty '
+					+ '`targets` array',
 				)
 			}
 
-			const session = captures.sessions.get(captureId)
-			if(!session) {
-				throw new Error(`no capture ${captureId}`)
+			for(const t of targets) {
+				if((t.hash ?? defaultHash) !== undefined
+					&& t.value.length > OPRF_MAX_BYTES) {
+					throw new Error(
+						`OPRF caps hashed values at ${OPRF_MAX_BYTES} bytes; got `
+						+ `${t.value.length}-byte "${t.value}". Use a tighter `
+						+ 'target or drop `hash`.',
+					)
+				}
 			}
 
-			const r = session.requests.get(requestId)
-			if(!r) {
-				throw new Error(`no request ${requestId}`)
+			const captured = backend.capture.requests.get(requestId)
+			if(!captured) {
+				throw new Error(`no captured request ${requestId}`)
 			}
 
-			const body = session.bodies.get(requestId)
-			if(!body.available) {
-				throw new Error(`request body unavailable: ${body.reason}`)
+			if(!captured.responseBody) {
+				throw new Error(`request body unavailable for ${requestId}`)
 			}
 
-			const reqWithBody = { ...r, responseBody: body.body }
-			const { provider, secretRefs } = draftProvider(
-				reqWithBody,
-				target,
-				name,
-				hash,
+			const { provider, secretRefs, extractions } = draftProvider(
+				captured, targets, providerName, defaultHash,
 			)
-
-			// Stash real secret values for later replay/proof.
-			const realSecrets: Record<string, string> = {}
+			// Materialize the real secret header values for later replay/prove;
+			// they stay in the server-side draft, never in this result.
+			const secrets: Record<string, string> = {}
 			for(const ref of secretRefs) {
-				const real = r.requestHeaders[ref.name]
+				const real = captured.requestHeaders[ref.name]
 				if(real !== undefined) {
-					realSecrets[ref.name] = real
+					secrets[ref.name] = real
 				}
 			}
 
-			const secretParamsRef = secrets.put(realSecrets)
+			const draftId = backend.drafts.put({
+				provider, secretRefs, secrets, requestId, extractions,
+			})
 			const warnings = verificationWarnings(provider)
 			return {
+				draftId,
 				provider,
 				secretRefs,
-				secretParamsRef,
 				...(warnings.length ? { verificationWarnings: warnings } : {}),
 			}
 		},

package/src/mcp/tools/agent/replay.ts

@@ -1,53 +1,43 @@
-import { replayProvider } from '../../../proof/replay.ts'
-import type { ReclaimProvider } from '../../../provider/schema.ts'
-import { defineTool, type RegisteredTool } from '../../server.ts'
-import type { SecretStore } from './propose.ts'
+/**
+ * `replay_request` — validate a drafted recipe before proving: confirm its
+ * selectors extract the target(s), and (with `withoutSecrets`) that the
+ * endpoint is auth-bound. Authored once as a plain {@link RegisteredTool}; the
+ * backend does the actual replay (MCP re-runs locally, cloud re-issues in the
+ * TEE pod).
+ */
+import { objectSchema, type ResolveBackend } from '../../../authoring/util.ts'
+import { defineTool, type RegisteredTool } from '../../../tools/registry.ts'
 
-export function replayTool(secrets: SecretStore): RegisteredTool {
-	return defineTool<{ provider: unknown, secretParamsRef?: string }>(
+export function replayTool(resolveBackend: ResolveBackend): RegisteredTool {
+	return defineTool<Record<string, unknown>>(
 		{
 			name: 'replay_request',
 			description:
-				'Replay a drafted provider against the live endpoint ' +
-				'using Node fetch (no attestor). ' +
-				'Pre-flight gate before run_proof — ' +
-				'diagnoses CSRF / token-rotation / matcher-too-tight ' +
-				'issues with richer hints than the attestor would produce.',
-			inputSchema: {
-				type: 'object',
-				properties: {
-					provider: { type: 'object', properties: {} },
-					secretParamsRef: { type: 'string' },
+				'Validate the drafted recipe before proving — confirm its selectors '
+				+ 'extract the target value. Returns diagnostics; run before '
+				+ 'proving. Set `withoutSecrets: true` for the AUTH-BOUND check: it '
+				+ 're-issues the request with NO secrets/cookies (an anonymous '
+				+ 'visitor). If the values still extract (valid:true), the endpoint '
+				+ 'is PUBLIC and the proof would not bind to the user — reject it '
+				+ 'and find an auth-bound request instead.',
+			inputSchema: objectSchema(
+				{
+					draftId: { type: 'string' },
+					withoutSecrets: { type: 'boolean' },
 				},
-				required: ['provider'],
-			},
+				['draftId'],
+			),
 		},
-		async({ provider, secretParamsRef }) => {
-			let resolved: Record<string, string> = {}
-			if(secretParamsRef !== undefined) {
-				const r = secrets.resolve(secretParamsRef)
-				if(!r) {
-					throw new Error(
-						`unknown secretParamsRef "${secretParamsRef}" — ` +
-						'the MCP server has restarted or reset_session was called. ' +
-						'Re-run propose_provider to mint a fresh ref.',
-					)
-				}
-
-				resolved = r
-			}
-
-			const result = await replayProvider(provider as ReclaimProvider, resolved)
-			const out: Record<string, unknown> = {
-				status: result.status,
-				matchesOriginal: result.matchesOriginal,
-				bodySnippet: result.body.slice(0, 256),
-			}
-			if(result.hints !== undefined) {
-				out.hints = result.hints
+		async(args) => {
+			const backend = resolveBackend(args)
+			const draft = backend.drafts.get(String(args.draftId))
+			if(!draft) {
+				throw new Error(`no draft ${String(args.draftId)}`)
 			}
 
-			return out
+			return backend.replay(draft, {
+				withoutSecrets: Boolean(args.withoutSecrets),
+			})
 		},
 	)
 }

package/src/mcp/tools/agent/session.ts

@@ -6,7 +6,6 @@ import type { CaptureStore } from './capture.ts'
 export function sessionTools(
 	attachRef: { current?: AttachState, config: ConfigStore },
 	captures: CaptureStore,
-	secrets: { clear: () => void },
 ): RegisteredTool[] {
 	return [
 		defineTool<Record<string, never>>(
@@ -28,17 +27,17 @@ export function sessionTools(
 			{
 				name: 'reset_session',
 				description:
-					'Stop all captures, drop in-memory secrets, and clear capture state.',
+					'Stop all captures and clear capture state — drops every '
+					+ 'session\'s drafts and their in-memory secrets.',
 				inputSchema: { type: 'object', properties: {} },
 			},
 			async() => {
-				for(const s of captures.sessions.values()) {
-					await s.stop().catch(() => {})
+				for(const entry of captures.sessions.values()) {
+					await entry.session.stop().catch(() => {})
 				}
 
 				captures.sessions.clear()
 				delete captures.activeTab
-				secrets.clear()
 				return { reset: true }
 			},
 		),