@reclaimprotocol/agent 0.1.0-dev.1

package/src/proof/attestor.ts

@@ -0,0 +1,286 @@
+// src/proof/attestor.ts
+//
+// Adapter over @reclaimprotocol/attestor-core's createClaimOnAttestor.
+//
+// responseMatches are the regex/contains checks the attestor runs on the
+// revealed slice; jsonPath/xPath live on responseRedactions (what the prover
+// reveals), never on responseMatches.
+
+import {
+	createClaimOnAttestor, type Logger, type ProviderParams,
+} from '@reclaimprotocol/attestor-core'
+import { resolveOwnerPrivateKey } from '../mcp/tools/credentials/cache.ts'
+import type { ReclaimProvider } from '../provider/schema.ts'
+
+export interface AttestorLogEntry {
+	level: 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal'
+	msg: string
+	ctx?: Record<string, unknown>
+}
+
+export interface ProofResult {
+	proof: unknown
+	extractedValue: string
+	extractedParameters: Record<string, string>
+	identifier?: string
+	owner?: string
+	verified: boolean
+	error?: string
+	/** Set to `'missing-owner-key'` when no credential was available to
+	 *  sign with — distinguishes this recoverable case from other proof
+	 *  errors so the skill can point the dev at `issue_credentials` /
+	 *  `list_cached_credentials` rather than guessing. */
+	errorKind?: 'missing-owner-key'
+	/** Pino-style log entries captured from the attestor SDK during the
+	 *  proof attempt. Full stream on the result; the MCP layer trims it
+	 *  for the LLM-visible response and dumps the whole thing to disk
+	 *  via `runLogPath`. */
+	attestorLogs?: AttestorLogEntry[]
+	/** The exact `params` object passed to `createClaimOnAttestor` for
+	 *  this attempt. Only included on error so the LLM/dev can confirm
+	 *  what the attestor actually saw vs what they thought they sent
+	 *  (catches mutation bugs / template-substitution surprises). Never
+	 *  carries the captured secrets — those live in `secretParams` which
+	 *  is not echoed here. */
+	sentParams?: unknown
+}
+
+/** Trim a captured log stream to the last N entries — for shrinking the
+ *  LLM-visible response while the full stream stays in the on-disk dump. */
+export function tailLogs(
+	entries: AttestorLogEntry[],
+	n = LOG_TAIL_LINES,
+): AttestorLogEntry[] {
+	if(entries.length <= n) {
+		return entries
+	}
+
+	return entries.slice(entries.length - n)
+}
+
+/** Filter to just warn/error/fatal — for the LLM-visible response on
+ *  successful proofs, where chatty trace/info would just waste context. */
+export function warnsAndErrors(
+	entries: AttestorLogEntry[],
+): AttestorLogEntry[] {
+	return entries.filter(
+		(e) => e.level === 'warn' || e.level === 'error' || e.level === 'fatal',
+	)
+}
+
+/** How many log entries to keep from the attestor SDK on an error. The
+ *  early ones describe TLS setup; the late ones (right before the
+ *  throw) usually pinpoint the actual failure. Keeping the tail covers
+ *  the latter; the cap stops a chatty session from blowing the LLM's
+ *  context window. */
+const LOG_TAIL_LINES = 80
+
+/** Build a pino-compatible capturing logger. Each `trace`/`debug`/…
+ *  call records an entry; `child` returns a derived capturer bound to
+ *  the parent's entries array so nested SDK loggers all flow into one
+ *  ordered list. */
+function makeCaptureLogger(): {
+	logger: unknown
+	entries: AttestorLogEntry[]
+	} {
+	const entries: AttestorLogEntry[] = []
+	const make = (baseCtx: Record<string, unknown>): unknown => {
+		const log =
+			(level: AttestorLogEntry['level']) => (...args: unknown[]) => {
+				if(args.length === 0) {
+					return
+				}
+
+				let msg = ''
+				let ctx: Record<string, unknown> | undefined
+
+				if(args[0] instanceof Error) {
+					// pino-style `logger.error(err, 'msg')` — Error objects
+					// don't JSON-serialize on their own, so extract the
+					// useful fields manually.
+					const err = args[0]
+					ctx = {
+						error: { name: err.name, message: err.message, stack: err.stack },
+					}
+					msg = typeof args[1] === 'string' ? args[1] : err.message
+				} else if(typeof args[0] === 'string') {
+					msg = args[0]
+				} else if(args[0] && typeof args[0] === 'object') {
+					ctx = args[0] as Record<string, unknown>
+					msg = typeof args[1] === 'string' ? args[1] : ''
+				}
+
+				const merged =
+					Object.keys(baseCtx).length || ctx
+						? { ...baseCtx, ...(ctx ?? {}) }
+						: undefined
+				const entry: AttestorLogEntry = { level, msg }
+				if(merged) {
+					entry.ctx = merged
+				}
+
+				entries.push(entry)
+			}
+
+		return {
+			trace: log('trace'),
+			debug: log('debug'),
+			info: log('info'),
+			warn: log('warn'),
+			error: log('error'),
+			fatal: log('fatal'),
+			child: (childCtx: Record<string, unknown>) => {
+				return make({ ...baseCtx, ...childCtx })
+			},
+		}
+	}
+
+	return { logger: make({}), entries }
+}
+
+/** Default public attestor websocket URL. Resolved per-call so an env-var
+ *  change or per-request override takes effect without restarting the
+ *  MCP server. */
+const FALLBACK_ATTESTOR_URL = 'wss://attestor.reclaimprotocol.org:444/ws'
+function resolveAttestorUrl(override?: string): string {
+	return (
+		override ?? process.env['RECLAIM_ATTESTOR_URL'] ?? FALLBACK_ATTESTOR_URL
+	)
+}
+
+// ---------------------------------------------------------------------------
+// Main entry point
+// ---------------------------------------------------------------------------
+
+export async function runAttestorProof(
+	provider: ReclaimProvider,
+	secrets: Record<string, string>,
+	attestorUrl?: string,
+	ownerAddress?: string,
+): Promise<ProofResult> {
+	// The owner is chosen up front (resolve_owner_key) and passed as
+	// `ownerAddress`; here we just fetch its private key and sign.
+	const ownerPrivateKey = ownerAddress
+		? resolveOwnerPrivateKey(ownerAddress)
+		: undefined
+	if(!ownerPrivateKey) {
+		return {
+			proof: undefined,
+			extractedValue: '',
+			extractedParameters: {},
+			verified: false,
+			error:
+				`No private key available for ownerAddress "${ownerAddress ?? ''}". ` +
+				'Call resolve_owner_key to pick a credential (or ' +
+				'issue_credentials / import_credentials to set one up), then ' +
+				'retry run_proof with its address as ownerAddress.',
+			errorKind: 'missing-owner-key',
+		}
+	}
+
+	try {
+		const params: ProviderParams<'http'> = {
+			url: provider.url,
+			method: provider.method,
+			...(provider.headers !== undefined && { headers: provider.headers }),
+			...(provider.body !== undefined && { body: provider.body }),
+			responseMatches: provider.responseMatches,
+			responseRedactions: provider.responseRedactions ?? [],
+			...(provider.paramValues !== undefined && {
+				paramValues: provider.paramValues,
+			}),
+		}
+
+		// Diagnostic logger capture is gated behind RECLAIM_AGENT_TRACE so the
+		// happy path doesn't pay the cost (the attestor SDK emits a *lot* of
+		// trace/debug entries during ZK setup). Flip RECLAIM_AGENT_TRACE=1 to
+		// turn it back on when something's broken; logs flow into the proof
+		// response and into the on-disk proof-runs dump.
+		const traceEnabled = process.env['RECLAIM_AGENT_TRACE'] === '1'
+		const capture = traceEnabled ? makeCaptureLogger() : undefined
+		const attestorLogs = capture?.entries
+
+		let claim: unknown
+		try {
+			claim = await createClaimOnAttestor({
+				name: 'http',
+				params,
+				secretParams: {
+					headers: secrets,
+				},
+				ownerPrivateKey,
+				client: { url: resolveAttestorUrl(attestorUrl) },
+				zkEngine: 'snarkjs',
+				...(capture !== undefined && { logger: capture.logger as Logger }),
+			})
+		} catch(err) {
+			const errorResult: ProofResult = {
+				proof: undefined,
+				extractedValue: '',
+				extractedParameters: {},
+				verified: false,
+				error: err instanceof Error ? err.message : String(err),
+				sentParams: params,
+			}
+			if(attestorLogs !== undefined) {
+				errorResult.attestorLogs = attestorLogs
+			}
+
+			return errorResult
+		}
+
+		// ClaimTunnelResponse carries the claim under `.claim`.
+		const claimRecord = claim as Record<string, unknown>
+		const claimData =
+			claimRecord['claim'] as Record<string, unknown> | undefined
+
+		// claimData.context is a JSON-encoded string carrying
+		// { extractedParameters: {...}, providerHash, ... }.
+		let context: Record<string, unknown> = {}
+		const rawContext = claimData?.['context']
+		if(typeof rawContext === 'string') {
+			try {
+				context = JSON.parse(rawContext) as Record<string, unknown>
+			} catch{
+				// Leave context empty if it isn't valid JSON.
+			}
+		}
+
+		const extractedParameters =
+			(context['extractedParameters'] as Record<string, string> | undefined) ??
+			{}
+		const extractedValue = Object.values(extractedParameters)[0] ?? ''
+
+		const result: ProofResult = {
+			proof: claim,
+			extractedValue,
+			extractedParameters,
+			verified: true,
+		}
+		const identifier = claimData?.['identifier']
+		if(typeof identifier === 'string') {
+			result.identifier = identifier
+		}
+
+		const owner = claimData?.['owner']
+		if(typeof owner === 'string') {
+			result.owner = owner
+		}
+
+		// Only set when RECLAIM_AGENT_TRACE=1. Full stream — the MCP layer
+		// trims for the LLM-visible response; the on-disk dump gets it all.
+		if(attestorLogs !== undefined && attestorLogs.length > 0) {
+			result.attestorLogs = attestorLogs
+		}
+
+		return result
+	} catch(err) {
+		return {
+			proof: undefined,
+			extractedValue: '',
+			extractedParameters: {},
+			verified: false,
+			error: err instanceof Error ? err.message : String(err),
+		}
+	}
+}

package/src/proof/replay.ts

@@ -0,0 +1,102 @@
+import type { ReclaimProvider, ResponseMatch } from '../provider/schema.ts'
+
+export interface ReplayResult {
+	status: number
+	body: string
+	matchesOriginal: boolean
+	hints?: string[]
+}
+
+/** Expand `{{name}}` placeholders from `paramValues`. Matches the attestor
+ *  SDK's behavior so replay and proof both hit the same final URL. */
+function expandTemplate(
+	s: string,
+	params: Record<string, string> | undefined,
+): string {
+	if(!params) {
+		return s
+	}
+
+	return s.replace(/\{\{([^{}]+)\}\}/g, (match, name) => {
+		const v = params[name]
+		return v !== undefined ? v : match
+	})
+}
+
+export async function replayProvider(
+	provider: ReclaimProvider,
+	secrets: Record<string, string>,
+): Promise<ReplayResult> {
+	const params = provider.paramValues
+	const url = expandTemplate(provider.url, params)
+	const expandedHeaders: Record<string, string> = {}
+	for(const [k, v] of Object.entries(provider.headers ?? {})) {
+		expandedHeaders[k] = expandTemplate(v, params)
+	}
+
+	const headers = { ...expandedHeaders, ...secrets }
+	const fetchInit: RequestInit = {
+		method: provider.method,
+		headers,
+		redirect: 'manual',
+	}
+	if(provider.body !== undefined) {
+		fetchInit.body = expandTemplate(provider.body, params)
+	}
+
+	const res = await fetch(url, fetchInit)
+	const body = await res.text()
+	const hints: string[] = []
+	if(res.status === 401 || res.status === 403) {
+		hints.push('auth/permission failed')
+	}
+
+	if(res.status >= 500) {
+		hints.push('upstream server error')
+	}
+
+	for(const m of provider.responseMatches) {
+		// The attestor substitutes paramValues into responseMatches.value
+		// at proof time (`{{name}}` → the value, or → the OPRF nullifier
+		// when the matching redaction has `hash`). Replay can't OPRF, but
+		// it can do the plain substitution so a paramValues-templated match
+		// is meaningful here.
+		const expanded: ResponseMatch = {
+			...m,
+			value: expandTemplate(m.value, params),
+		}
+		if(!matchesBody(body, expanded)) {
+			if(res.status >= 200 && res.status < 300) {
+				hints.push(
+					`matcher ${expanded.type} did not match — ` +
+					'value may have changed or matcher is too tight',
+				)
+			}
+
+			const result: ReplayResult = {
+				status: res.status,
+				body,
+				matchesOriginal: false,
+			}
+			if(hints.length > 0) {
+				result.hints = hints
+			}
+
+			return result
+		}
+	}
+
+	return { status: res.status, body, matchesOriginal: res.status < 400 }
+}
+
+function matchesBody(body: string, m: ResponseMatch): boolean {
+	if(m.type === 'regex') {
+		return new RegExp(m.value).test(body)
+	}
+
+	if(m.type === 'contains') {
+		return body.includes(m.value)
+	}
+
+	return false
+}

package/src/provider/constraints.ts

@@ -0,0 +1,150 @@
+import { looksLikeGraphqlEndpoint } from './graphql.ts'
+import type { CapturedRequest, RequestConcern } from './schema.ts'
+
+const SIGNATURE_HEADERS = [
+	'x-signature',
+	'x-amz-signature',
+	'x-hub-signature',
+	'x-hmac',
+	'signature',
+	'x-request-signature',
+]
+
+const CSRF_HEADERS = [
+	'x-csrf-token',
+	'x-xsrf-token',
+	'csrf-token',
+	'xsrf-token',
+]
+
+export function detectConcerns(req: CapturedRequest): RequestConcern[] {
+	const concerns: RequestConcern[] = []
+	const reqHeadersLower = lowerKeys(req.requestHeaders)
+	const respHeadersLower = lowerKeys(req.responseHeaders)
+
+	// Signed requests
+	for(const h of SIGNATURE_HEADERS) {
+		if(reqHeadersLower[h]) {
+			concerns.push({
+				code: 'signedRequest',
+				message: `Request includes a "${h}" header — ` +
+					'providers will break when the signing scheme rotates.',
+			})
+			break
+		}
+	}
+
+	// Bot challenge
+	const cfMitigated = respHeadersLower['cf-mitigated']
+	const server = respHeadersLower['server'] ?? ''
+	if(
+		(req.status === 403 || req.status === 503) &&
+		(cfMitigated === 'challenge' || /cloudflare/i.test(server))
+	) {
+		concerns.push({
+			code: 'botChallenge',
+			message:
+				'Response looks like a bot-mitigation challenge (Cloudflare). ' +
+				'Capture again after solving the challenge in the browser.',
+		})
+	}
+
+	// GraphQL
+	if(looksLikeGraphqlEndpoint(req.url)) {
+		concerns.push({
+			code: 'graphql',
+			message:
+				'Endpoint is GraphQL — ' +
+				'match on operationName + variables, not URL path.',
+		})
+	}
+
+	// CSRF dependency
+	for(const h of CSRF_HEADERS) {
+		if(reqHeadersLower[h]) {
+			concerns.push({
+				code: 'csrfDependency',
+				message: `Request includes a "${h}" header — ` +
+					'a prior request fetched this token. ' +
+					'Replay will fail unless the token is still valid; ' +
+					'expect to re-capture for proof.',
+			})
+			break
+		}
+	}
+
+	// Short-lived token (JWT exp < 30 min from finishedAt)
+	const auth = reqHeadersLower['authorization']
+	if(auth) {
+		const jwtMatch = auth.match(
+			/^[Bb]earer\s+([A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+)/,
+		)
+		if(jwtMatch) {
+			const exp = jwtExpSeconds(jwtMatch[1])
+			const issuedAtMs = req.finishedAt || Date.now()
+			if(exp && exp * 1000 - issuedAtMs < 30 * 60 * 1000) {
+				concerns.push({
+					code: 'shortLivedToken',
+					message:
+						'Authorization is a JWT expiring in under 30 minutes — ' +
+						'provider may stop working soon. Re-capture closer to proof time.',
+				})
+			}
+		}
+	}
+
+	// Encrypted / binary body
+	if(looksBinary(req.contentType, req.responseBody)) {
+		concerns.push({
+			code: 'encryptedBody',
+			message: `Response content-type "${req.contentType}" is binary/opaque —` +
+				' Reclaim providers need plain-text (JSON/HTML) responses.',
+		})
+	}
+
+	return concerns
+}
+
+function lowerKeys(h: Record<string, string>): Record<string, string> {
+	return Object.fromEntries(
+		Object.entries(h).map(([k, v]) => [k.toLowerCase(), v]),
+	)
+}
+
+function jwtExpSeconds(jwt: string): number | undefined {
+	const parts = jwt.split('.')
+	if(parts.length !== 3) {
+		return undefined
+	}
+
+	try {
+		const decoded = JSON.parse(
+			Buffer.from(parts[1], 'base64url').toString('utf8'),
+		)
+		return typeof decoded.exp === 'number' ? decoded.exp : undefined
+	} catch{
+		return undefined
+	}
+}
+
+function looksBinary(contentType: string, body: string | undefined): boolean {
+	if(!body) {
+		return false
+	}
+
+	if(/octet-stream|protobuf|msgpack|cbor/i.test(contentType)) {
+		return true
+	}
+
+	// Heuristic: significant control-char density in first 256 bytes.
+	const sample = body.slice(0, 256)
+	let ctrl = 0
+	for(const ch of sample) {
+		const code = ch.charCodeAt(0)
+		if(code < 9 || (code > 13 && code < 32)) {
+			ctrl++
+		}
+	}
+
+	return ctrl / sample.length > 0.1
+}

package/src/provider/draft.ts

@@ -0,0 +1,105 @@
+import { synthesizeMatcher } from './matcher.ts'
+import type {
+	CapturedRequest,
+	OprfMode,
+	ReclaimProvider,
+	SecretParamRef,
+} from './schema.ts'
+import { splitSecrets } from './secrets.ts'
+
+export interface DraftResult {
+	provider: ReclaimProvider
+	secretRefs: SecretParamRef[]
+}
+
+/** Replace any existing `accept-encoding` (case-insensitive) with a
+ *  canonical `Accept-Encoding: identity`. Strips browser-captured
+ *  encodings like `gzip, deflate, br, zstd` that would otherwise make
+ *  the attestor match against compressed response bytes. */
+function withIdentityEncoding(
+	headers: Record<string, string>,
+): Record<string, string> {
+	const out: Record<string, string> = {}
+	for(const [k, v] of Object.entries(headers)) {
+		if(k.toLowerCase() === 'accept-encoding') {
+			continue
+		}
+
+		out[k] = v
+	}
+
+	out['Accept-Encoding'] = 'identity'
+	return out
+}
+
+/** Derive a `paramValues` key (and capture-group name) from the provider
+ *  name's last alphanumeric token. `"GitHub Username"` → `"username"`,
+ *  `"x-followers"` → `"followers"`. */
+function deriveParamName(providerName: string): string {
+	const tokens = providerName.split(/[^A-Za-z0-9]+/).filter(Boolean)
+	const last = tokens[tokens.length - 1] ?? 'value'
+	return last.toLowerCase()
+}
+
+export function draftProvider(
+	req: CapturedRequest,
+	target: string,
+	name: string,
+	hash?: OprfMode,
+): DraftResult {
+	if(!req.responseBody) {
+		throw new Error(`captured request ${req.requestId} has no response body`)
+	}
+
+	const paramName = deriveParamName(name)
+	const synthesis = synthesizeMatcher(
+		req.responseBody,
+		req.contentType,
+		target,
+		paramName,
+		hash,
+	)
+	if(!synthesis) {
+		throw new Error(
+			`target value "${target}" not found in` +
+			` response body for request ${req.requestId}`,
+		)
+	}
+
+	const { secrets, publics } = splitSecrets(req.requestHeaders)
+	// Force the server to respond uncompressed. Captured browser requests
+	// usually carry `accept-encoding: gzip, deflate, br, zstd`; the attestor
+	// matches against the raw response bytes (no transparent decompression
+	// in the TLS replay path), so gzip/br/zstd payloads make every
+	// xPath/jsonPath/regex redaction miss against unparseable bytes.
+	// Replacing here also benefits `replay_request` — Node's `fetch` does
+	// auto-decompress, but pinning the encoding keeps replay and proof
+	// looking at the same body shape end-to-end.
+	const headersForProvider = withIdentityEncoding(publics)
+	const secretRefs: SecretParamRef[] = Object.keys(secrets).map((name) => ({
+		name,
+		source: name.toLowerCase() === 'cookie' ? 'cookie' : 'header',
+		redacted: true,
+	}))
+
+	const provider: ReclaimProvider = {
+		name,
+		url: req.url,
+		method: req.method as ReclaimProvider['method'],
+		headers: headersForProvider,
+		responseMatches: [synthesis.match],
+	}
+	if(synthesis.redaction) {
+		provider.responseRedactions = [synthesis.redaction]
+	}
+
+	if(synthesis.paramValues) {
+		provider.paramValues = synthesis.paramValues
+	}
+
+	if(req.requestBody) {
+		provider.body = req.requestBody
+	}
+
+	return { provider, secretRefs }
+}

package/src/provider/graphql.ts

@@ -0,0 +1,42 @@
+export function looksLikeGraphqlEndpoint(url: string): boolean {
+	try {
+		const u = new URL(url)
+		return u.pathname.includes('/graphql')
+	} catch{
+		return false
+	}
+}
+
+export function extractGraphqlOp(body: string | undefined): string | undefined {
+	if(!body) {
+		return undefined
+	}
+
+	let parsed: unknown
+	try {
+		parsed = JSON.parse(body)
+	} catch{
+		return undefined
+	}
+
+	if(typeof parsed !== 'object' || parsed === null) {
+		return undefined
+	}
+
+	const obj = parsed as Record<string, unknown>
+
+	if(typeof obj.operationName === 'string' && obj.operationName.length > 0) {
+		return obj.operationName
+	}
+
+	if(typeof obj.query === 'string') {
+		const m = obj.query.match(
+			/^\s*(?:query|mutation|subscription)\s+([A-Za-z_][A-Za-z0-9_]*)/,
+		)
+		if(m) {
+			return m[1]
+		}
+	}
+
+	return undefined
+}