@reclaimprotocol/agent 0.1.35 → 0.1.37

package/lib/mcp/tools/agent/proof.js

@@ -117,6 +117,10 @@ export function shapeRichProofResult(result, opts) {
     if (result.errorKind !== undefined) {
         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
@@ -158,6 +162,74 @@ export function shapeRichProofResult(result, opts) {
     }
     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;
+/**
+ * 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, lastReplay, geoLocation) {
+    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 } : {}),
+        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) {
+    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);
+}
 /**
  * When an unverified proof failed with a network-like error, runs the
  * attestor check once and says whether the attestor or the target site is the

package/lib/mcp/tools/agent/shared.d.ts

@@ -1,9 +1,16 @@
+import { runAttestorProof } from '../../../proof/attestor.ts';
 import { checkAttestor } from '../../../proof/check-attestor.ts';
 import type { RegisteredTool } from '../../server.ts';
 import type { CaptureStore } from './capture.ts';
+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';
+}
 /** The shared authoring tools mapped to the MCP's shape: resolve each call's
  *  local backend from `args.captureId`, and widen the input schema — every tool
  *  takes `captureId`; `run_proof` also gets the credential-aware contract. The
  *  tools are authored plain in `../../../authoring`; this only wraps them with
  *  `extendTool` (handlers untouched — loose arg parse keeps `captureId`). */
-export declare function sharedAuthoringTools(captures: CaptureStore, check?: typeof checkAttestor): RegisteredTool[];
+export declare function sharedAuthoringTools(captures: CaptureStore, check?: typeof checkAttestor, runProof?: typeof runAttestorProof, lookupCountry?: () => Promise<string | undefined>): RegisteredTool[];

package/lib/mcp/tools/agent/shared.js

@@ -1,7 +1,10 @@
 import { authoringTools, extendTool, } from "../../../authoring/index.js";
+import { lookupIpCountry } from "../../../cdp/geo.js";
 import { runAttestorProof } from "../../../proof/attestor.js";
 import { checkAttestor } from "../../../proof/check-attestor.js";
 import { replayProviderInPage } from "../../../proof/page-replay.js";
+import { DYNAMIC_GEO, normalizeGeoLocation, } from "../../../provider/schema.js";
+import { GENERATED_KEY_NOTE, resolveOrCreateEthKey, } from "../authenticate/eth-key.js";
 import { diagnoseNetworkFailure, shapeRichProofResult } from "./proof.js";
 /**
  * OPRF mode this LOCAL (non-TEE) attestor can actually run. Recipes carry
@@ -30,10 +33,31 @@ function withLocalOprfMode(provider) {
         }),
     };
 }
+/** Templates a verification client replaces with the end user's country. */
+const DYNAMIC_GEO_TEMPLATES = new Set([DYNAMIC_GEO, '{{DYNAMIC_GEO_SECRET}}']);
+/**
+ * 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, argument, lookupCountry) {
+    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). */
-function localBackend(entry, kept, check) {
+function localBackend(entry, kept, check, runProof, lookupCountry) {
     const { tabClient, session, drafts } = entry;
     const sendCdp = (method, params) => {
         return tabClient.send(method, params ?? {});
@@ -63,6 +87,15 @@ function localBackend(entry, kept, check) {
             // Replayed FROM INSIDE the attached tab (real cookies/session), not
             // a detached Node fetch — see proof/page-replay.ts.
             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,
@@ -71,19 +104,47 @@ function localBackend(entry, kept, check) {
             };
         },
         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), draft.secrets, {
-                ...(opts?.ownerAddress ? { ownerAddress: opts.ownerAddress } : {}),
+            // 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, {
+                ...(ownerAddress ? { ownerAddress } : {}),
                 ...(opts?.attestorUrl ? { attestorUrl: opts.attestorUrl } : {}),
             });
             const shaped = shapeRichProofResult(result, {
                 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,
+                        },
+                    }
+                    : {}),
+            };
         },
     };
 }
@@ -93,42 +154,60 @@ function localBackend(entry, kept, check) {
 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.',
+            description: '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: [],
 };
 /** The shared authoring tools mapped to the MCP's shape: resolve each call's
  *  local backend from `args.captureId`, and widen the input schema — every tool
  *  takes `captureId`; `run_proof` also gets the credential-aware contract. The
  *  tools are authored plain in `../../../authoring`; this only wraps them with
  *  `extendTool` (handlers untouched — loose arg parse keeps `captureId`). */
-export function sharedAuthoringTools(captures, check = checkAttestor) {
+export function sharedAuthoringTools(captures, check = checkAttestor, runProof = runAttestorProof, lookupCountry = lookupIpCountry) {
     const resolveBackend = (args) => {
         const captureId = String(args.captureId);
         const entry = captures.sessions.get(captureId);
@@ -136,7 +215,7 @@ export function sharedAuthoringTools(captures, check = checkAttestor) {
             throw new Error(`no capture ${captureId} — call start_capture first `
                 + '(it has been reset or never started).');
         }
-        return localBackend(entry, captures, check);
+        return localBackend(entry, captures, check, runProof, lookupCountry);
     };
     return authoringTools(resolveBackend).map((tool) => {
         if (tool.definition.name === 'run_proof') {

package/lib/mcp/tools/agent/start-integration.d.ts

@@ -6,7 +6,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 declare function startIntegrationTool(): RegisteredTool;

package/lib/mcp/tools/agent/start-integration.js

@@ -3,18 +3,22 @@ import { fileURLToPath } from 'node:url';
 import { defineTool } from "../../server.js";
 /**
  * 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() {
     return defineTool({
         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'],

package/lib/mcp/tools/authenticate/authenticate.d.ts

@@ -1,14 +1,52 @@
 import type { ReclaimClient } from '@reclaimprotocol/client/api';
 import { type RegisteredTool } from '../../server.ts';
-export declare function authenticateTool(client: ReclaimClient, name?: 'reclaim_authenticate' | 'authenticate_builder'): RegisteredTool;
+type AuthToolName = 'reclaim_authenticate' | 'authenticate_builder';
+/** Whether the browser launcher started, and why not when it didn't. */
+export type BrowserLaunch = {
+    opened: boolean;
+    reason?: string;
+};
+export type PendingSignIn = {
+    status: 'PENDING';
+    signInUrl: string;
+    browserOpened: boolean;
+    reason?: string;
+    /** ISO timestamp when `signInUrl` stops working. */
+    expiresAt: string;
+};
+export type SignInOutcome = {
+    status: 'AUTHENTICATED';
+    expiresAt: string;
+} | {
+    status: 'FAILED';
+    reason: string;
+};
+export declare function authenticateTool(client: ReclaimClient, name?: AuthToolName): RegisteredTool;
+export declare function waitForSignInTool(client: ReclaimClient, authToolName?: AuthToolName): RegisteredTool;
 /**
- * Standard OAuth 2.0 Authorization Code + PKCE, native-app style (RFC 8252):
- * dynamically register a public client (RFC 7591 — Better Auth's
- * `oauth-provider` plugin issues no secret for it), send the user to the
- * browser, and catch the redirect on a loopback server. `openid-client`
- * handles PKCE, `state` CSRF protection, and authorization-response
- * validation (including a denied/failed login surfacing as
- * `AuthorizationResponseError`) — this function only wires those calls
- * together and owns the loopback server (no library spins that up for you).
+ * Start a sign-in and return its link without waiting for the developer. A
+ * sign-in already pending for `client` is returned as is rather than
+ * replaced. The flow finishes in the background: the loopback server keeps
+ * listening until the browser redirects back or the link expires, and on
+ * success caches the session and activates it on `client`.
  */
-export declare function runOAuthLoopback(client: ReclaimClient, openBrowserFn?: (url: string) => void): Promise<unknown>;
+export declare function startSignIn(client: ReclaimClient, openBrowserFn?: (url: string) => Promise<BrowserLaunch>): Promise<PendingSignIn>;
+/**
+ * Wait up to `timeoutMs` for `client`'s sign-in to finish. Reports PENDING
+ * (with the link again) if it's still open when the wait runs out.
+ */
+export declare function waitForSignIn(client: ReclaimClient, timeoutMs: number): Promise<PendingSignIn | SignInOutcome | {
+    status: 'NOT_STARTED';
+}>;
+/**
+ * Try to open `url` in the system browser. Never writes to stdout (it carries
+ * MCP JSON-RPC); the URL goes to stderr for a developer watching the logs.
+ * On Linux without a display server it doesn't try. Otherwise a launcher
+ * that errors or exits non-zero within a short grace window counts as not
+ * opened.
+ */
+export declare function openBrowser(url: string, { env, platform }?: {
+    env?: NodeJS.ProcessEnv | undefined;
+    platform?: NodeJS.Platform | undefined;
+}): Promise<BrowserLaunch>;
+export {};