@reclaimprotocol/agent 0.1.36 → 0.1.38

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'],