@reclaimprotocol/agent 0.1.36 → 0.1.37

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 {};