@reclaimprotocol/agent 0.1.36 → 0.1.37

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

@@ -36,7 +36,10 @@ export function podProofTools(
 				+ 'instead of `run_proof` when the attach mode is "builder": the '
 				+ 'proof then reaches the target from the browser\'s own exit IP and '
 				+ 'country. Needs no `ownerAddress`; the pod signs with its own TEE '
-				+ 'key.',
+				+ 'key. It matches the browser\'s exit IP and country, not '
+				+ 'necessarily its TLS fingerprint, so it is not a way past bot '
+				+ 'protection: if `run_proof` reported '
+				+ '`blocked-non-browser-client`, expect the same here.',
 			inputSchema: {
 				type: 'object',
 				properties: {
@@ -78,6 +81,7 @@ export function podProofTools(
 			return shapeRichProofResult(result, {
 				provider: draft.provider,
 				hasSecrets: Object.keys(draft.secrets).length > 0,
+				...(draft.lastReplay ? { lastReplay: draft.lastReplay } : {}),
 			})
 		},
 	)

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

@@ -109,7 +109,15 @@ function isLikelyByteArray(v: unknown[]): boolean {
  */
 export function shapeRichProofResult(
 	result: ProofResult,
-	opts: { provider: unknown, hasSecrets: boolean, attestorUrl?: string },
+	opts: {
+		provider: unknown
+		hasSecrets: boolean
+		attestorUrl?: string
+		/** The draft's latest authenticated in-browser replay, when tracked. */
+		lastReplay?: { status: number, ok: boolean }
+		/** Where the attestor's request went out from. */
+		egress?: { geoLocation?: string }
+	},
 ): Record<string, unknown> {
 	// Persist the full claim to disk for the dev to inspect/share.
 	let claimPath: string | undefined
@@ -153,6 +161,13 @@ export function shapeRichProofResult(
 		out.errorKind = result.errorKind
 	}
 
+	const blocked = diagnoseBlockedClient(
+		result, opts.lastReplay, opts.egress?.geoLocation,
+	)
+	if(blocked !== undefined) {
+		out.diagnosis = blocked
+	}
+
 	// Trim the LLM-visible logs — full stream goes to runLogPath.
 	if(result.attestorLogs !== undefined && result.attestorLogs.length > 0) {
 		const logs = result.verified
@@ -198,6 +213,100 @@ export function shapeRichProofResult(
 	return out
 }
 
+/** HTTP statuses a site's bot protection answers non-browser clients with. */
+const BLOCKING_STATUSES = new Set([403, 406, 429, 503])
+
+/** Markers of a bot-protection / challenge page rather than real content. */
+const CHALLENGE_BODY = new RegExp([
+	'captcha', 'challenge', 'cf-chl', 'cf-ray', 'just a moment',
+	'access denied', 'request unsuccessful', '_incapsula_', 'px-captcha',
+	'perimeterx', 'datadome', 'akamai', 'bot detection', 'enable javascript',
+	'are you a robot', 'unusual traffic',
+].join('|'), 'i')
+
+/** Below this, a response the browser rendered with the value in it is
+ *  likely a shell or challenge page served to a non-browser client. */
+const TINY_BODY_BYTES = 4096
+
+export interface BlockedClientDiagnosis {
+	kind: 'blocked-non-browser-client'
+	/** HTTP status the attestor's request got, when the error carries one. */
+	status?: number
+	/** Set when the same draft's in-browser replay succeeded. */
+	replayedInBrowser?: true
+	likelyCause: string
+	next: string
+}
+
+/**
+ * Says when a failed proof looks like the site blocking non-browser clients:
+ * the attestor's request got 403/406/429/503, or a tiny or challenge-looking
+ * page where the browser got the real one. Returns undefined for verified
+ * proofs and other failures. The raw `error` stays on the result.
+ */
+export function diagnoseBlockedClient(
+	result: Pick<ProofResult, 'verified' | 'error'>,
+	lastReplay?: { status: number, ok: boolean },
+	geoLocation?: string,
+): BlockedClientDiagnosis | undefined {
+	if(result.verified || !result.error) {
+		return undefined
+	}
+
+	const replayedInBrowser = lastReplay?.ok === true
+	const statusMatch = new RegExp(
+		'Expected status 2xx, got (\\d{3})|Provider returned error (\\d{3})',
+	).exec(result.error)
+	const status = Number(statusMatch?.[1] ?? statusMatch?.[2]) || undefined
+	const blockedStatus = status !== undefined && BLOCKING_STATUSES.has(status)
+	if(!blockedStatus && !(replayedInBrowser && challengeBody(result.error))) {
+		return undefined
+	}
+
+	return {
+		kind: 'blocked-non-browser-client',
+		...(status !== undefined ? { status } : {}),
+		...(replayedInBrowser ? { replayedInBrowser: true as const } : {}),
+		likelyCause:
+			(replayedInBrowser
+				? 'The same request succeeded from inside the browser, but '
+				: '')
+			+ 'the site answered the attestor'
+			+ (geoLocation
+				? `, whose request went out from ${geoLocation}, with `
+				: ', whose request went out from its own network, with ')
+			+ (blockedStatus ? `HTTP ${status}` : 'a challenge or shell page')
+			+ '. The site blocks traffic from that country, or non-browser '
+			+ 'clients (bot protection or TLS fingerprinting). Copying headers or '
+			+ 'cookies will not help.',
+		next:
+			'If the site serves one country (for example, a US airline), retry '
+			+ 'run_proof once with `geoLocation` set to that country. If that '
+			+ 'verifies, pin it with update_draft({ geoLocation }) so the '
+			+ 'published version goes out from there too. Otherwise, try a '
+			+ 'different endpoint that returns the value, such as a JSON API the '
+			+ 'page calls (find_requests_containing), then propose and prove '
+			+ 'that. If none works, stop and report to the developer that this '
+			+ 'site blocks the attestor. Do not tweak headers.',
+	}
+}
+
+/** True when an attestor error embeds a response element (base64, from a
+ *  regex redaction that didn't match) that is tiny or a challenge page. */
+function challengeBody(error: string): boolean {
+	const b64 = /does not match found element '([A-Za-z0-9+/=]*)/.exec(error)?.[1]
+	if(b64 === undefined) {
+		return false
+	}
+
+	// "Tiny" only means something for a whole document; an xPath-selected
+	// element is small by design.
+	const text = Buffer.from(b64, 'base64').toString('utf8')
+	const tinyDocument = Buffer.byteLength(text) < TINY_BODY_BYTES
+		&& /<!doctype|<html/i.test(text)
+	return tinyDocument || CHALLENGE_BODY.test(text)
+}
+
 export interface ProofDiagnosis {
 	attestor: AttestorCheckResult
 	likelyCause: string

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

@@ -14,11 +14,21 @@ import {
 	extendTool,
 	type KeptScriptRef,
 } from '../../../authoring/index.ts'
+import { lookupIpCountry } from '../../../cdp/geo.ts'
 import { runAttestorProof } from '../../../proof/attestor.ts'
 import { checkAttestor } from '../../../proof/check-attestor.ts'
 import { replayProviderInPage } from '../../../proof/page-replay.ts'
-import type { OprfMode, ReclaimProvider } from '../../../provider/schema.ts'
+import {
+	DYNAMIC_GEO,
+	normalizeGeoLocation,
+	type OprfMode,
+	type ReclaimProvider,
+} from '../../../provider/schema.ts'
 import type { RegisteredTool } from '../../server.ts'
+import {
+	GENERATED_KEY_NOTE,
+	resolveOrCreateEthKey,
+} from '../authenticate/eth-key.ts'
 import type { CaptureEntry, CaptureStore } from './capture.ts'
 import { diagnoseNetworkFailure, shapeRichProofResult } from './proof.ts'
 
@@ -53,6 +63,42 @@ function withLocalOprfMode(provider: ReclaimProvider): ReclaimProvider {
 	}
 }
 
+/** Templates a verification client replaces with the end user's country. */
+const DYNAMIC_GEO_TEMPLATES = new Set([DYNAMIC_GEO, '{{DYNAMIC_GEO_SECRET}}'])
+
+export interface ProofEgress {
+	/** ISO country (or param template) the attestor's request goes out from;
+	 *  absent when it goes out from the attestor's own network. */
+	geoLocation?: string
+	source: 'argument' | 'draft' | 'developer-ip' | 'none'
+}
+
+/**
+ * Where a local proof's request goes out from, resolved the way a
+ * verification client does it: the `geoLocation` argument, else the draft's
+ * fixed country, else (unset or `{{DYNAMIC_GEO}}`) the developer's own IP
+ * country, which is what `{{DYNAMIC_GEO}}` becomes when they verify.
+ */
+async function resolveProofEgress(
+	provider: ReclaimProvider,
+	argument: string | undefined,
+	lookupCountry: () => Promise<string | undefined>,
+): Promise<ProofEgress> {
+	if(argument) {
+		return { geoLocation: argument.toUpperCase(), source: 'argument' }
+	}
+
+	const fixed = normalizeGeoLocation(provider.geoLocation)
+	if(fixed && !DYNAMIC_GEO_TEMPLATES.has(fixed)) {
+		return { geoLocation: fixed, source: 'draft' }
+	}
+
+	const country = await lookupCountry()
+	return country
+		? { geoLocation: country, source: 'developer-ip' }
+		: { source: 'none' }
+}
+
 /** The local backend for one capture: drive its tab over CDP, read its
  *  captured requests, prove via the in-process attestor, replay by re-fetching
  *  FROM INSIDE the tab (real cookies/session — see proof/page-replay.ts). */
@@ -60,6 +106,8 @@ function localBackend(
 	entry: CaptureEntry,
 	kept: KeptScriptRef,
 	check: typeof checkAttestor,
+	runProof: typeof runAttestorProof,
+	lookupCountry: () => Promise<string | undefined>,
 ): AuthoringBackend {
 	const { tabClient, session, drafts } = entry
 	const sendCdp = (method: string, params?: Record<string, unknown>) => {
@@ -96,6 +144,16 @@ function localBackend(
 			const result = await replayProviderInPage(
 				{ sendCdp }, draft.provider, draft.secrets, opts,
 			)
+			// Remember the authenticated replay so a failed proof can tell "the
+			// site blocks non-browser clients" from a broken recipe.
+			if(!opts?.withoutSecrets) {
+				draft.lastReplay = {
+					status: result.status,
+					ok: result.status >= 200 && result.status < 300
+						&& result.matchesOriginal,
+				}
+			}
+
 			return {
 				status: result.status,
 				matchesOriginal: result.matchesOriginal,
@@ -104,13 +162,29 @@ function localBackend(
 			}
 		},
 		prove: async(draft, opts) => {
-			// Prove with the locally-runnable OPRF mode; the draft (→ published
-			// recipe) keeps oprf-mpc.
-			const result = await runAttestorProof(
-				withLocalOprfMode(draft.provider),
+			// No ownerAddress: resolve the configured key, or create a local test
+			// key, so a proof never stops to ask the developer for one.
+			const ownerKey = opts?.ownerAddress
+				? undefined
+				: resolveOrCreateEthKey()
+			const ownerAddress = opts?.ownerAddress ?? ownerKey?.address
+			const egress = await resolveProofEgress(
+				draft.provider, opts?.geoLocation, lookupCountry,
+			)
+			// Prove with the locally-runnable OPRF mode and the resolved egress;
+			// the draft (→ published recipe) keeps oprf-mpc and its template.
+			const { geoLocation: _template, ...provider } = withLocalOprfMode(
+				draft.provider,
+			)
+			void _template
+			const result = await runProof(
+				{
+					...provider,
+					...(egress.geoLocation ? { geoLocation: egress.geoLocation } : {}),
+				},
 				draft.secrets,
 				{
-					...(opts?.ownerAddress ? { ownerAddress: opts.ownerAddress } : {}),
+					...(ownerAddress ? { ownerAddress } : {}),
 					...(opts?.attestorUrl ? { attestorUrl: opts.attestorUrl } : {}),
 				},
 			)
@@ -118,11 +192,27 @@ function localBackend(
 				provider: draft.provider,
 				hasSecrets: Object.keys(draft.secrets).length > 0,
 				...(opts?.attestorUrl ? { attestorUrl: opts.attestorUrl } : {}),
+				...(draft.lastReplay ? { lastReplay: draft.lastReplay } : {}),
+				egress,
 			})
 			const diagnosis = await diagnoseNetworkFailure(
 				result, check, opts?.attestorUrl,
 			)
-			return diagnosis ? { ...shaped, diagnosis } : shaped
+			return {
+				...shaped,
+				egress,
+				...(diagnosis ? { diagnosis } : {}),
+				...(ownerKey?.source === 'generated'
+					? {
+						ownerKey: {
+							address: ownerKey.address,
+							source: ownerKey.source,
+							path: ownerKey.path,
+							note: GENERATED_KEY_NOTE,
+						},
+					}
+					: {}),
+			}
 		},
 	}
 }
@@ -134,36 +224,55 @@ const RUN_PROOF_EXTRAS = {
 	description:
 		'Proves the drafted recipe with a full zkTLS proof through the attestor '
 		+ 'SDK. Call it after `replay_request` looks right; attestor calls are '
-		+ 'expensive. Call `resolve_owner_key` first and pass its address as '
-		+ '`ownerAddress`. Writes the full claim to '
+		+ 'expensive. It signs with the configured proof-owner key and creates '
+		+ 'a local test key in the project `.env` when none exists; then the '
+		+ 'result has `ownerKey` with a `note`: tell the developer once, after '
+		+ 'the fact. Do not ask for a key first. Writes the full claim to '
 		+ '`~/.reclaim/claims/<timestamp>.json`. Returns `identifier`, '
 		+ '`extractedParameters`, `claimPath`, and a readable `claim` (request '
 		+ 'removed, byte arrays as base64). Set `RECLAIM_AGENT_TRACE=1` to also '
 		+ 'get `runLogPath`, a diagnostic dump with the attestor log stream. '
 		+ 'Set `attestorUrl` only if the developer supplied one; never invent '
-		+ 'backup URLs. If `errorKind` is `missing-owner-key`, the address has '
-		+ 'no known private key: run `resolve_owner_key` again, or issue or '
-		+ 'import a credential. Unlike `replay_request`, which re-sends from '
+		+ 'backup URLs. If `errorKind` is `missing-owner-key`, the '
+		+ '`ownerAddress` you passed has no known private key: retry without '
+		+ '`ownerAddress`. Unlike `replay_request`, which re-sends from '
 		+ 'inside the attached browser tab, the attestor calls the target from '
 		+ 'its own network and IP. A request that replayed can still fail here '
 		+ 'for geo- or IP-bound content, such as country-locked pages or '
 		+ 'IP-allowlisted APIs. That is a property of the site, not a draft '
-		+ 'bug. After a network-like failure ("connection closed", '
+		+ 'bug. The request goes out from `egress.geoLocation` in the result: '
+		+ 'the `geoLocation` argument, else the draft\'s fixed country, else '
+		+ 'your own IP country. After a network-like failure ("connection closed", '
 		+ '`ERROR_NETWORK_ERROR`, timeout), the result includes `diagnosis` '
 		+ 'with `attestor` (a `check_attestor` result), `likelyCause`, and '
-		+ '`next`. Follow `next`; do not retry the same proof.',
+		+ '`next`. Follow `next`; do not retry the same proof. When the '
+		+ 'attestor gets HTTP 403/406/429/503 or a challenge page, `diagnosis` '
+		+ 'has `kind: "blocked-non-browser-client"`: the site blocks '
+		+ 'non-browser clients or traffic from that country, and copying '
+		+ 'headers or cookies will not help. Follow its `next`. Run '
+		+ '`check_matchers` first to rule out the recipe offline.',
 	properties: {
 		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.',
+				'Optional ETH address the resolved signing key must match. Omit '
+				+ 'it: run_proof resolves (or creates) the key itself. The '
+				+ 'private key is resolved locally (env / .env / key file), '
+				+ 'never passed here.',
 		},
 		attestorUrl: { type: 'string' },
+		geoLocation: {
+			type: 'string',
+			pattern: '^[A-Za-z]{2}$',
+			description:
+				'ISO country the attestor\'s request goes out from, for example '
+				+ '`US`. Omit it to use the draft\'s fixed country, or else your '
+				+ 'own IP country, as `{{DYNAMIC_GEO}}` resolves for you when you '
+				+ 'verify.',
+		},
 	},
-	required: ['ownerAddress'],
+	required: [],
 } satisfies {
 	description: string
 	properties: JSONSchema.ObjectSchema['properties']
@@ -178,6 +287,8 @@ const RUN_PROOF_EXTRAS = {
 export function sharedAuthoringTools(
 	captures: CaptureStore,
 	check: typeof checkAttestor = checkAttestor,
+	runProof: typeof runAttestorProof = runAttestorProof,
+	lookupCountry: () => Promise<string | undefined> = lookupIpCountry,
 ): RegisteredTool[] {
 	const resolveBackend = (args: Record<string, unknown>): AuthoringBackend => {
 		const captureId = String(args.captureId)
@@ -189,7 +300,7 @@ export function sharedAuthoringTools(
 			)
 		}
 
-		return localBackend(entry, captures, check)
+		return localBackend(entry, captures, check, runProof, lookupCountry)
 	}
 
 	return authoringTools(resolveBackend).map((tool) => {

package/src/mcp/tools/agent/start-integration.ts

@@ -10,7 +10,8 @@ interface StartIntegrationArgs {
 
 /**
  * Returns the plan a coding agent follows to add Reclaim verification to the
- * developer's app, from sign-in to a tested Verify button. The plan lives in
+ * developer's app, from sign-in and a working proof to a tested Verify
+ * button. The plan lives in
  * `skill/start-integration.md`; this tool fills in the inputs.
  */
 export function startIntegrationTool(): RegisteredTool {
@@ -19,11 +20,14 @@ export function startIntegrationTool(): RegisteredTool {
 			name: 'start_integration',
 			description:
 				'Returns a step-by-step plan for adding Reclaim verification to the '
-				+ 'current codebase: sign in, set up the app (session route, callback, '
-				+ 'Verify button, local event proxy) in parallel with building or '
-				+ 'choosing the provider, then wire the provider and test. Call it '
-				+ 'first when a developer wants their users to prove something, and '
-				+ 'follow the plan to the end. Changes nothing itself.',
+				+ 'current codebase: sign in to Builder, attach the browser, capture, '
+				+ 'and prove the provider first, then set up the app (session route, '
+				+ 'callback, Verify button, local event proxy) after the proof or '
+				+ 'while waiting on the developer, bootstrapping from the '
+				+ 'builder-example repository when there is no app yet, then wire '
+				+ 'the provider and test. '
+				+ 'Call it first when a developer wants their users to prove '
+				+ 'something, and follow the plan to the end. Changes nothing itself.',
 			inputSchema: {
 				type: 'object',
 				required: ['goal'],