@reclaimprotocol/agent 0.1.22 → 0.1.24

package/src/old/tools/publish.ts

@@ -1,7 +1,10 @@
 import { Boom, isBoom } from '@hapi/boom'
 import { defineTool, type RegisteredTool } from '../../mcp/server.ts'
 import type { AttachState } from '../../mcp/tools/agent/attach.ts'
-import { INJECTION_GUIDE } from '../../provider/injection-doc.ts'
+import {
+	ALLOWED_REQUESTS_HINT,
+	USER_SCRIPT_HINT,
+} from '../../provider/injection-doc.ts'
 import {
 	countsFor,
 	matchRedactionWarnings,
@@ -35,8 +38,8 @@ function extractProviderId(resp: unknown): string | undefined {
  * `providerId` for a public provider (or anyone else's) comes back as
  * 401/403/404 — the dev's likely intent is to publish their OWN version of that
  * site, which on this backend means registering a separate copy. Rethrow those
- * failures with that actionable suggestion; leave other errors (e.g. a 400
- * version collision) untouched so their real detail surfaces.
+ * failures with that actionable suggestion; leave other errors (for example, a
+ * 400 version collision) untouched so their real detail surfaces.
  */
 function rethrowOwnershipError(err: unknown, providerId: string): never {
 	const status = isBoom(err) ? err.output.statusCode : undefined
@@ -62,7 +65,7 @@ function rethrowOwnershipError(err: unknown, providerId: string): never {
 /**
  * Publish a drafted provider to the OLD devtools backend. Keeps the builder
  * tool NAME (`create_provider_version_from_capture`) so the skill flow is
- * unchanged, but the behaviour differs:
+ * unchanged, but the behavior differs:
  *
  *   - WITHOUT `providerId` → `POST /api/providers/register`: creates a
  *     brand-new provider + version 1.0.0. Re-running creates a DUPLICATE.
@@ -99,59 +102,44 @@ export function createVersionFromCaptureTool(
 		stepsToFollow?: string
 		useIncognitoWebview?: boolean
 		extensionConfig?: unknown
+		injectionType?: 'NONE' | 'MSWJS' | 'XHOOK' | 'CDP' | 'HAWKEYE'
 		disableRequestReplay?: boolean
 	}>(
 		{
 			name: 'create_provider_version_from_capture',
 			description:
-				'Publish drafted ReclaimProvider(s) to the devtools backend. ' +
-				'Pass the `provider` object from propose_provider VERBATIM and the ' +
-				'`initialUrl` the user landed on (the login/landing page, NOT the ' +
-				'API url). \n\n' +
-				'For a MULTI-REQUEST provider, pass `providers: [...]` (each entry a ' +
-				'proven draft from propose_provider) — every entry becomes one ' +
-				'`requestData` entry on the SAME version, and all are verified ' +
-				'together. Pass a single `provider` for the one-request case ' +
-				'(provide exactly one of `provider` / `providers`). \n\n' +
-				'Omit `providerId` to REGISTER A NEW provider (creates it + version ' +
-				'1.0.0; re-running creates a duplicate). Pass `providerId` (from ' +
-				'get_me_providers) to add a NEW VERSION to that existing provider ' +
-				'(the patch is auto-bumped). \n\n' +
-				'You can only add versions to a provider YOU own — the `providerId` ' +
-				'must come from get_me_providers. To publish your own version of a ' +
-				"PUBLIC provider you don't own, omit `providerId` to register your " +
-				'own copy (you cannot edit someone else\'s provider here). \n\n' +
-				'For data gated behind login/navigation, pass `customInjection` — a ' +
-				'page-injection script (the devtools name for the builder\'s ' +
-				'jsUserScripts) that drives the page to where the request fires. \n\n' +
-				'BY DESIGN, this backend only ever CREATES A NEW VERSION (POST) — ' +
-				'there is no partial-patch/edit endpoint, and this tool does NOT ' +
-				'read or carry anything forward from the previous version. Every ' +
-				'new version replaces the WHOLE providerConfig with exactly what ' +
-				'you pass in THIS call. Therefore any field you want present in the ' +
-				'new version MUST be supplied here — `customInjection`, `userAgent`, ' +
-				'`pageTitle`, `allowedInjectedRequestData`, `stepsToFollow`, ' +
-				'`useIncognitoWebview`, `extensionConfig`, and `requestData` (via ' +
-				'`provider`/`providers`). Anything you OMIT is published blank/' +
-				'default in the new version, NOT preserved. To change one field ' +
-				'while keeping the rest, first read the current version with ' +
-				'get_provider_info, then pass the full desired config (the existing ' +
-				'values plus your change) back into this call. ' +
-				'`allowedInjectedRequestData`/`useIncognitoWebview`/' +
-				'`extensionConfig` only take effect on add-version — the register ' +
-				'endpoint (no `providerId`) ignores them. `disableRequestReplay` ' +
-				'is also add-version-only, but when it is true the tool follows ' +
-				'a register up with an add-version call automatically so it takes ' +
-				'effect on new providers too. Per-request fields you may set on ' +
-				'`provider`/`providers`: `credentials` (omit/same-origin/include, ' +
-				'default include), `urlType` (REGEX/CONSTANT/TEMPLATE, default ' +
-				'derived from {{placeholders}}), and `isOptional` on each ' +
-				'responseMatch (default false). \n\n' +
-				'Captured requests must be GET/POST. OPRF redactions are supported. ' +
-					'On success, if a browser is still attached, the response\'s ' +
-					'`_notes` reminds you to confirm with the developer before ' +
-					'calling `dispose_browser` — never close it unprompted, they ' +
-					'may want it for further edits.',
+				'Publish drafted ReclaimProvider(s) to the devtools backend. Needs '
+				+ 'its OWN reclaim_authenticate login — authenticate_builder does NOT '
+				+ 'authorize this call. Pass the `provider` object(s) from '
+				+ 'propose_provider VERBATIM, plus the `initialUrl` the user landed '
+				+ 'on (the login/landing page, NOT the API url). Exactly one of '
+				+ '`provider` (one request) or `providers` (a multi-request '
+				+ 'provider — every entry becomes a parallel requestData entry, all '
+				+ 'verified together). Captured requests must be GET/POST; OPRF '
+				+ 'redactions are supported.\n\n'
+				+ 'Omit `providerId` to REGISTER A NEW provider (creates it + '
+				+ 'version 1.0.0 — re-running creates a DUPLICATE). Pass '
+				+ '`providerId` (from get_me_providers) to add a NEW VERSION to it; '
+				+ 'the patch auto-bumps. You can only version a provider YOU own — '
+				+ 'to publish your own take on one you don\'t own, omit '
+				+ '`providerId` to register your own copy.\n\n'
+				+ 'THIS BACKEND ONLY EVER CREATES A NEW VERSION — there is no '
+				+ 'partial-patch endpoint, and this tool carries NOTHING forward '
+				+ 'from the previous version: every version replaces the WHOLE '
+				+ 'providerConfig with exactly what you pass in THIS call. Any '
+				+ 'field you want to survive must be re-supplied here '
+				+ '(`customInjection`, `userAgent`, `pageTitle`, '
+				+ '`allowedInjectedRequestData`, `stepsToFollow`, '
+				+ '`useIncognitoWebview`, `extensionConfig`, `requestData`); '
+				+ 'anything omitted is published blank. To change one field, read '
+				+ 'the current config with get_provider_info first and pass it back '
+				+ 'with your edit. `allowedInjectedRequestData`/'
+				+ '`useIncognitoWebview`/`extensionConfig` apply on add-version '
+				+ 'only, so a fresh register auto-follows with an add-version call '
+				+ 'that applies them (and disables document replay — see '
+				+ '`disableRequestReplay`).\n\n'
+				+ 'Always read the response\'s `_notes`. '
+				+ 'Full walkthrough: how_it_works({ topic: "publish" }).',
 			inputSchema: {
 				type: 'object',
 				properties: {
@@ -263,15 +251,11 @@ export function createVersionFromCaptureTool(
 					customInjection: {
 						type: 'string',
 						description:
-							'Plain JavaScript injected into the provider page before every ' +
-							'page load — old-devtools\' name for what the builder calls ' +
-							'`webSettings.jsUserScripts`. Use standard browser APIs ' +
-							'(window.location, element.click(), forms) to drive login/' +
-							'navigation so the target request fires — window.Reclaim is ' +
-							'only for rare edge cases, not navigation. The backend rejects ' +
-							'a few deprecated injection APIs (e.g. window.payloadData, ' +
-							'window.ReclaimInjected) with a 400. Guide:\n\n' +
-							INJECTION_GUIDE,
+							USER_SCRIPT_HINT
+							+ ' Old-devtools\' name for what the builder calls '
+							+ 'webSettings.jsUserScripts. The backend rejects a few '
+							+ 'deprecated injection APIs (window.payloadData, '
+							+ 'window.ReclaimInjected) with a 400.',
 					},
 					userAgent: {
 						type: 'object',
@@ -290,39 +274,15 @@ export function createVersionFromCaptureTool(
 					allowedInjectedRequestData: {
 						type: 'array',
 						description:
-							'Extra requests the customInjection script is allowed to ' +
-							'fire (e.g. pagination) — add-version ONLY, the register ' +
-							'endpoint ignores this. Each item has the same shape as ' +
-							'`provider`, plus `multiple`/`required` (default true). ' +
-							'IMPORTANT whenever a claim\'s request HAS a body: set `body` ' +
-							'here (see its own description below) — if only a small part ' +
-							'of the real body varies per user/run (e.g. one id field, not ' +
-							'the whole payload), template just that part with ' +
-							'`{{paramName}}` and keep the rest as fixed literal text; see ' +
-							'the "bodySniff" section of the customInjection field\'s guide ' +
-							'for the exact mechanics and a worked example. ' +
-							'⚠️ BEFORE populating this to gate ' +
-							'`verifyProof(proof, { providerId })`: this whole entry (url, ' +
-							'method, body, responseMatches, responseRedactions) feeds a ' +
-							'client-side hash-equality check, and `url` is hashed VERBATIM ' +
-							'— no regex/template resolution, even with `urlType: REGEX` or ' +
-							'`TEMPLATE`. If the real captured URL contains ANY per-session ' +
-							'part (a tracking nonce, CSRF token, cache-busting timestamp), ' +
-							'no declared spec can EVER hash-match a real proof, no matter ' +
-							'how correct the rest of this entry is — populating' +
-							'it for such ' +
-							'a provider makes verifyProof reject every real proof,' +
-							'which is ' +
-							'worse than leaving this field empty. Diff the same endpoint\'s' +
-							' captured URL across two separate sessions before wiring this ' +
-							'up. If provider-hash validation keeps causing problems ' +
-							'(unstable url, or any other persistent mismatch), the ' +
-							'fallback on the verifying side is `verifyProof(proof, { ' +
-							'dangerouslyDisableContentValidation: true })` — trusts only ' +
-							'the attestor\'s signature, skips the hash-equality check ' +
-							'entirely; see the "Provider-hash validation" section of the ' +
-							'customInjection field\'s guide for the full mechanics and ' +
-							'when to reach for it.',
+							'Extra requests the customInjection user script is allowed to '
+							+ 'fire (for example, pagination) — add-version ONLY, the '
+							+ 'register '
+							+ 'endpoint ignores it. Each item has the same shape as '
+							+ '`provider`, plus `multiple`/`required` (default true). Set '
+							+ '`body` whenever the request has one (see its own description '
+							+ 'below). The builder calls the same concept '
+							+ '`allowedJsRequests`. '
+							+ ALLOWED_REQUESTS_HINT,
 						items: {
 							type: 'object',
 							properties: {
@@ -344,7 +304,8 @@ export function createVersionFromCaptureTool(
 										'body at all (skip only for a genuinely bodyless ' +
 										'request, typically GET). If the real body is FIXED ' +
 										'(identical for every user/run), put that literal body ' +
-										'text here verbatim. If only PART of it varies (e.g. ' +
+										'text here verbatim. If only PART of it varies (for ' +
+										'example, ' +
 										'`{"request":1,"type":"user_info","id":"12345"}` where ' +
 										'only `id` differs per user), template ONLY that part: ' +
 										'`{"request":1,"type":"user_info",' +
@@ -367,7 +328,7 @@ export function createVersionFromCaptureTool(
 										'reproduces the real captured request body ' +
 										'byte-for-byte. Fallback if per-field templating keeps ' +
 										'mismatching (more fields vary than expected, unstable ' +
-										'key order, etc.) and you can\'t pin down every ' +
+										'key order, and so on) and you can\'t pin down every ' +
 										'variable field: template the WHOLE body as one ' +
 										'placeholder instead, `{{REQ_BODY_GRD}}` — the `GRD` ' +
 										'suffix makes it a greedy match (captures everything) ' +
@@ -385,7 +346,7 @@ export function createVersionFromCaptureTool(
 										'`value` must literally appear (or match, if `regex`) ' +
 										'somewhere in the response body for the claim to be ' +
 										'accepted; it commonly embeds one or more ' +
-										'`{{paramName}}` extraction placeholders (e.g. ' +
+										'`{{paramName}}` extraction placeholders (for example, ' +
 										'`"name":"{{name_0}}"`) whose real value is redacted ' +
 										'out and supplied separately as a witness/extracted ' +
 										'param. Use `${var}` (not `{{var}}`) inside this string ' +
@@ -401,7 +362,8 @@ export function createVersionFromCaptureTool(
 										'Each item: `{ jsonPath?: string, xPath?: string, ' +
 										'regex?: string, hash?: string }`. Identifies WHICH ' +
 										'part of the response the matching `{{paramName}}` in ' +
-										'`responseMatches` actually redacts/extracts — e.g. ' +
+										'`responseMatches` actually redacts or extracts — for ' +
+										'example, ' +
 										'`jsonPath: "$.data.items[0].name"` for a JSON response. ' +
 										'Order/count should line up with `responseMatches`\' ' +
 										'placeholders one-to-one for a typical claim.',
@@ -458,14 +420,36 @@ export function createVersionFromCaptureTool(
 							'Free-form JSON passed through to the client. Add-version ' +
 							'ONLY.',
 					},
+					injectionType: {
+						type: 'string',
+						enum: ['NONE', 'MSWJS', 'XHOOK', 'CDP', 'HAWKEYE'],
+						description:
+							'Interception mechanism for this version. Omit to leave it ' +
+							'unset — the devtools backend\'s own column default ' +
+							'(`HAWKEYE`) applies, which is inert and harmless for the ' +
+							'standard capture→replay flow with no interceptor script ' +
+							'installed. Only set `HAWKEYE`/`MSWJS`/`XHOOK` when you are ' +
+							'ALSO supplying a `customInjection` script that calls ' +
+							'`window.reclaimInterceptor.addResponseMiddleware(...)` for ' +
+							'genuine live interception, or set `NONE` explicitly to be ' +
+							'certain none is configured. Builder calls the equivalent ' +
+							'concept `interceptorType` (no `NONE` there — omitting the ' +
+							'whole `interceptorOptions` object is its no-interception ' +
+							'signal instead). What each value actually does: ' +
+							'how_it_works({ topic: "interception" }).',
+					},
 					disableRequestReplay: {
 						type: 'boolean',
 						description:
-							'Skip replaying the main document request (HAWKEYE ' +
-							'provider-level flag). Honored on add-version; for a ' +
-							'provider (no `providerId`) the register endpoint ignores ' +
-							'it, so when true the tool automatically follows the ' +
-							'register up with an add-version call that applies it.',
+							'Whether the page\'s own document/navigation request is ' +
+							'skipped (constructed locally) instead of genuinely replayed ' +
+							'through the interceptor. Defaults to `true` (disabled) when ' +
+							'omitted. Only meaningful for `injectionType` ' +
+							'HAWKEYE/MSWJS/XHOOK — pass `false` to enable real document ' +
+							'replay for those (for example, the target value is embedded ' +
+							'in the page\'s own HTML). Inert when `injectionType` is ' +
+							'`CDP` or ' +
+							'unset.',
 					},
 				},
 				required: ['initialUrl'],
@@ -505,7 +489,13 @@ export function createVersionFromCaptureTool(
 				stepsToFollow: args.stepsToFollow,
 				useIncognitoWebview: args.useIncognitoWebview,
 				extensionConfig: args.extensionConfig,
-				disableRequestReplay: args.disableRequestReplay,
+				// Author-settable, no forced default — the backend's own HAWKEYE
+				// column default applies when omitted, same as before this field
+				// existed at all.
+				injectionType: args.injectionType,
+				// Author-settable; defaults to disabled (see tool description).
+				// Only meaningful for HAWKEYE/MSWJS/XHOOK — inert for CDP.
+				disableRequestReplay: args.disableRequestReplay ?? true,
 				allowedInjectedRequestData: args.allowedInjectedRequestData
 					? injectedRequestDataFrom(
 						args.allowedInjectedRequestData,
@@ -558,12 +548,12 @@ export function createVersionFromCaptureTool(
 					)
 				}
 
-				// disableRequestReplay is honored ONLY on add-version, so a
-				// register can't set it — when true we immediately follow the
-				// register with an add-version call (which also lands any other
-				// register-ignored fields).
-				const followUp = args.disableRequestReplay === true
-
+				// disableRequestReplay is honored ONLY on add-version — so every
+				// register is immediately followed by an add-version call that
+				// actually applies it (whatever value — default or author-set;
+				// which also lands an explicit injectionType, when passed —
+				// unverified whether register persists it — and any other
+				// register-ignored fields the caller passed).
 				const REGISTER_IGNORED_KEYS = [
 					'allowedInjectedRequestData',
 					'useIncognitoWebview',
@@ -576,53 +566,73 @@ export function createVersionFromCaptureTool(
 						`${ignoredOnRegister.join(', ')} ` +
 						`${ignoredOnRegister.length > 1 ? 'are' : 'is'} ` +
 						'ignored on register (no providerId) — the devtools backend only ' +
-						'reads them when adding a version. ' +
-						(followUp
-							? 'They were applied by the follow-up version the tool ' +
-							'created to set disableRequestReplay.'
-							: 'Publish once to create the provider, then call this ' +
-							'again WITH the returned providerId to set them.'),
+						'reads them when adding a version. They were applied by the ' +
+						'automatic follow-up version this tool always creates to apply ' +
+						'disableRequestReplay.',
 					)
 				}
 
 				const body = providerToRegisterBody(providers, opts)
 				const registered = await client.registerProvider(body)
 
-				if(followUp) {
-					const newProviderId = extractProviderId(registered)
-					if(newProviderId) {
+				const newProviderId = extractProviderId(registered)
+				if(newProviderId) {
+					// The provider already exists as of the register call above —
+					// a failure past this point must NOT reject the tool and
+					// discard `registered`/`newProviderId`, or a retry without
+					// `providerId` would register a DUPLICATE provider. Catch and
+					// warn instead, telling the caller to resume WITH this
+					// providerId.
+					try {
 						const versionsResp = await client.listVersions(newProviderId)
 						const followVersion = bumpPatchString(
 							extractVersions(versionsResp),
 						)
 						const configBody = providerToConfigBody(
 							providers,
-							{ ...opts, disableRequestReplay: true },
+							opts,
 							followVersion,
 							DEFAULT_VERSION_INFO,
 						)
 						await client.updateProviderConfig(newProviderId, configBody)
 						notes.push(
-							'disableRequestReplay is ignored by the register endpoint — ' +
-							`applied it via a follow-up version (${followVersion}) on ` +
-							'the new provider, which also lands any register-ignored ' +
-							'fields you passed.',
+							`Created an automatic follow-up version (${followVersion}) to ` +
+							`apply disableRequestReplay (${opts.disableRequestReplay})` +
+							(opts.injectionType !== undefined
+								? ` and set injectionType (${opts.injectionType})`
+								: '') +
+							' — the register endpoint ignores/may ignore those fields, so ' +
+							'every fresh register gets one. It also landed any other ' +
+							'register-ignored fields you passed.',
 						)
-					} else {
+					} catch(err) {
+						const detail = isBoom(err) ? err.message : String(err)
 						notes.push(
-							'Could not apply disableRequestReplay: the register ' +
-							'response did not include the new providerId. Call this ' +
-							'tool again WITH `providerId` and `disableRequestReplay: ' +
-							'true` to set it.',
+							`Provider ${newProviderId} WAS created, but the automatic ` +
+							`follow-up version (to force-disable document replay${
+								opts.injectionType !== undefined
+									? ' and set injectionType'
+									: ''
+							}) failed: ${detail}. Do NOT retry without providerId — that ` +
+							'would register a duplicate. Instead, re-run ' +
+							'create_provider_version_from_capture WITH ' +
+							`providerId: "${newProviderId}" to add the follow-up version.`,
 						)
 					}
+				} else {
+					notes.push(
+						'Could not apply disableRequestReplay: the ' +
+						'register response did not include the new providerId. Call ' +
+						'this tool again WITH `providerId` to create a version that ' +
+						'applies them.',
+					)
 				}
 
 				return withNotes(registered)
 			}
 
 			// New version of an existing provider — pick the next patch above
-			// the highest existing version. A provider you don't own (e.g. a
+			// the highest existing version. A provider you don't own (for example, a
 			// public one) fails here with 401/403/404; surface the register-a-copy
 			// workaround instead of a bare permission error.
 			const providerId = args.providerId

package/src/old/tools/update-provider-metadata.ts

@@ -8,7 +8,7 @@ import type { ReclaimOldClient, UpdateProviderMetadataBody } from '../client.ts'
  * `create_provider_version_from_capture` paths: it does NOT touch
  * `providerConfig`/versions at all, and only the fields you pass here
  * change — everything else on the provider is left untouched (no need to
- * re-supply `requestData`/`customInjection`/etc., and
+ * re-supply `requestData`/`customInjection`, and so on, and
  * no new version is created).
  *
  * The backend 403s if you don't own the provider (and aren't an admin) —

package/src/old/tools/verify-sdk-setup.ts

@@ -122,7 +122,7 @@ export function verifySdkSetupTool(client: ReclaimOldClient): RegisteredTool {
 					: 'PUBLIC_URL not set — fine if you only read the proof from the ' +
 						'frontend flow, but the async webhook callback needs a ' +
 						'publicly-reachable URL or it will never fire. Get one via a ' +
-						'tunnel (e.g. `ngrok http <port>`) or by deploying to a ' +
+						'tunnel (for example, `ngrok http <port>`) or by deploying to a ' +
 						'dev/staging server you already have — ask the user which they ' +
 						'prefer.',
 			})

package/src/proof/attestor.ts

@@ -53,13 +53,13 @@ export interface RunAttestorProofOptions {
 	/** When resolving the key from env/.env/file, the address the caller expects
 	 *  to sign with (sanity check). Ignored when `ownerPrivateKey` is given. */
 	ownerAddress?: string
-	/** Sign with this key directly (e.g. the app/VC's ephemeral per-session key)
-	 *  instead of resolving from env/.env/file. */
+	/** Sign with this key directly (for example, the app or VC's ephemeral
+	 *  per-session key) instead of resolving from env/.env/file. */
 	ownerPrivateKey?: string
 	/** ZK engine for `createClaimOnAttestor`. Defaults to `'stwo'` — a pure-WASM
 	 *  prover that runs everywhere (no native shared library, so it works on
 	 *  Windows where `'gnark'` fails to load its `.dll`). Server-side paths that
-	 *  want gnark's speed pin it explicitly (e.g. the verify runner). */
+	 *  want gnark's speed pin it explicitly (for example, the verify runner). */
 	zkEngine?: 'gnark' | 'snarkjs' | 'stwo'
 	/** Extract the structured {@link AttestorClaim} (claim + attestor signature)
 	 *  onto the result for nested-proof construction. */

package/src/proof/debug-response-dump.ts

@@ -1,10 +1,10 @@
 // Debug helper (gated by RECLAIM_AGENT_DUMP_RESPONSE): capture the EXACT
 // response bytes the attestor validates a claim against, plus a per-match
 // presence check. A "Response does not contain X" failure means the attestor's
-// server-side re-fetch differs from what the browser (replay) saw — e.g. GitHub
-// embeds nav/userMenu data for browser requests but not for the attestor's raw
-// fetch. Seeing the attestor's actual response is the only way to tell what it
-// really returned.
+// server-side re-fetch differs from what the browser (replay) saw — for
+// example, GitHub embeds nav/userMenu data for browser requests but not for the
+// attestor's raw fetch. Seeing the attestor's actual response is the only way
+// to tell what it really returned.
 //
 // On each getResponseRedactions call it writes the response to
 // `attestor-last-response.html` in the process CWD and logs the byte count +,

package/src/proof/index.ts

@@ -15,6 +15,14 @@ export {
 	parseClaim,
 	resolveAttestorUrl,
 } from './proof-core.ts'
+export {
+	type HttpParams,
+	type HttpSecretParams,
+	type PopcornProveOptions,
+	popcornProve,
+	popcornValidateExtraction,
+	type ValidateExtractionResult,
+} from './pod-prover.ts'
 export { ensureZkFiles } from './zk-files.ts'
 // Re-exported attestor-core claim primitive so the agent is the single
 // integration point with @reclaimprotocol/attestor-core across the builder.

package/src/proof/page-replay.ts

@@ -0,0 +1,131 @@
+/**
+ * Replay a drafted provider's AUTHENTICATED request FROM INSIDE the live
+ * attached browser tab, over CDP `Runtime.evaluate` — so cookies/session are
+ * always the real browser's, for every browser source the MCP can attach to
+ * (local Chrome, remote Popcorn, or a caller-supplied custom CDP endpoint all
+ * funnel through one `AuthoringBackend.sendCdp`). Ports the pattern already
+ * proven in the cloud/Popcorn authoring backend
+ * (`packages/app/src/author/backend.ts` `pageFetch`/`authenticatedFetch`),
+ * adapted to the MCP's single-page `sendCdp(method, params)` (no separate
+ * `pageSession` argument). The ANONYMOUS auth-bound check does NOT go through
+ * the page — see `replayProviderInPage`'s doc comment below for why.
+ */
+import type { ReclaimProvider } from '../provider/schema.ts'
+import {
+	buildReplayRequest,
+	evaluateReplay,
+	replayProvider,
+	type ReplayResult
+} from './replay.ts'
+
+/** Everything this module needs from an `AuthoringBackend` — just the raw CDP
+ *  seam, so callers can pass a minimal object instead of a full backend. */
+export interface PageReplayTarget {
+	sendCdp(method: string, params?: Record<string, unknown>): Promise<unknown>
+}
+
+interface PageFetchResult {
+	status?: number
+	body?: string
+	error?: string
+}
+
+/** Run `fetch(...)` for `provider`'s (already-templated) request inside the
+ *  attached tab, via `Runtime.evaluate`. `credentials` selects the visitor:
+ *  `'omit'` = anonymous (the auth-bound check), `'include'` = the logged-in
+ *  user (the reproducibility gate). Same-origin only — the tab is already on
+ *  the target site; a cross-origin/CORS failure comes back as `error`. */
+async function pageFetch(
+	backend: PageReplayTarget,
+	provider: ReclaimProvider,
+	credentials: 'omit' | 'include',
+	extraSecrets: Record<string, string>,
+): Promise<PageFetchResult> {
+	const req = buildReplayRequest(provider, extraSecrets)
+	const expression = `(async () => {
+		try {
+			const r = await fetch(${JSON.stringify(req.url)}, {
+				method: ${JSON.stringify(req.method)},
+				headers: ${JSON.stringify(req.headers)},
+				credentials: ${JSON.stringify(credentials)},${req.body !== undefined
+					? `\n\t\t\t\tbody: ${JSON.stringify(req.body)},`
+					: ''}
+			})
+			return { status: r.status, body: await r.text() }
+		} catch(e) { return { error: String((e && e.message) || e) } }
+	})()`
+	try {
+		const res = (await backend.sendCdp('Runtime.evaluate', {
+			expression,
+			awaitPromise: true,
+			returnByValue: true,
+		})) as {
+			result?: { value?: PageFetchResult }
+			exceptionDetails?: { exception?: { description?: string }, text?: string }
+		}
+		if(res.exceptionDetails) {
+			return {
+				error: res.exceptionDetails.exception?.description
+					?? res.exceptionDetails.text
+					?? 'page fetch evaluation error',
+			}
+		}
+
+		return res.result?.value ?? { error: 'page fetch returned no value' }
+	} catch(err) {
+		return { error: err instanceof Error ? err.message : String(err) }
+	}
+}
+
+/** Authenticated re-issue for the reproducibility gate. Cookies ride along
+ *  via `credentials: 'include'` (a `Cookie` header can't be set from
+ *  `fetch()` — it's a forbidden header name), so only NON-cookie secrets
+ *  (Authorization, X-* tokens) are injected explicitly. */
+function authenticatedPageFetch(
+	backend: PageReplayTarget,
+	provider: ReclaimProvider,
+	secrets: Record<string, string>,
+): Promise<PageFetchResult> {
+	const extra: Record<string, string> = {}
+	for(const [k, v] of Object.entries(secrets)) {
+		if(k.toLowerCase() !== 'cookie') {
+			extra[k] = v
+		}
+	}
+
+	return pageFetch(backend, provider, 'include', extra)
+}
+
+/**
+ * Replay `provider` and judge the response. Without `withoutSecrets`, replays
+ * as the logged-in session — run FROM INSIDE the live tab
+ * (`authenticatedPageFetch`) so cookies are the real browser's, which a
+ * detached call could never reproduce without manually re-deriving them.
+ * WITH `withoutSecrets` (the auth-bound check — "does this still work with
+ * no credentials, that is, is it actually public"), replay instead through the
+ * detached Node-side `replayProvider`: the whole point of that check is to
+ * prove NO secret rides along, and the live page's own global `fetch` can't
+ * give that guarantee — a site (or a script installed via test_user_script)
+ * can wrap `fetch` and re-attach a token from localStorage/a service worker
+ * even under `credentials:'omit'`. A fresh, page-uninvolved fetch has no
+ * such surface.
+ */
+export async function replayProviderInPage(
+	backend: PageReplayTarget,
+	provider: ReclaimProvider,
+	secrets: Record<string, string>,
+	opts?: { withoutSecrets?: boolean },
+): Promise<ReplayResult> {
+	if(opts?.withoutSecrets) {
+		return replayProvider(provider, {})
+	}
+
+	const result = await authenticatedPageFetch(backend, provider, secrets)
+	if(result.error !== undefined || result.status === undefined) {
+		throw new Error(
+			`in-browser replay failed: ${result.error ?? 'no response'}`,
+		)
+	}
+
+	return evaluateReplay(result.status, result.body ?? '', provider)
+}