@reclaimprotocol/agent 0.1.5 → 0.1.7

package/src/old/tools/get-provider-info.ts

@@ -0,0 +1,91 @@
+import { isBoom } from '@hapi/boom'
+import { defineTool, type RegisteredTool } from '../../mcp/server.ts'
+import type { ReclaimSdkClient } from '../sdk-client.ts'
+
+/** Best-effort call: resolve to the response, or to an error string instead
+ *  of throwing — one endpoint 404ing (e.g. a bad `versionNumber`) shouldn't
+ *  hide a result the other endpoint DID have. */
+async function attempt(
+	label: string,
+	call: () => Promise<unknown>,
+): Promise<{ ok: true, value: unknown } | { ok: false, error: string }> {
+	try {
+		return { ok: true, value: await call() }
+	} catch(err) {
+		const message = isBoom(err) ? err.message : String(err)
+		return { ok: false, error: `${label}: ${message}` }
+	}
+}
+
+/**
+ * Read provider info from the PUBLIC production SDK backend
+ * (`api.reclaimprotocol.org`) — the service the verification SDK/attestor
+ * itself calls at runtime, NOT the old-devtools dashboard backend
+ * (`get_provider_version_config`, `devapi.reclaimprotocol.org`, requires
+ * auth). Both underlying reads are unauthenticated.
+ *
+ * Fetches BOTH shapes in one call, since they're complementary:
+ *   - `provider`: full provider + providerConfig, `customInjection` included.
+ *   - `configs`: the trimmed runtime recipe the attestor actually consumes —
+ *     `customInjection` deliberately omitted, `isScriptRequestingClaim`
+ *     computed instead.
+ */
+export function getProviderInfoTool(client: ReclaimSdkClient): RegisteredTool {
+	return defineTool<{ providerId: string, versionNumber?: string }>(
+		{
+			name: 'get_provider_info',
+			description:
+				'Read a PUBLISHED provider from the public production SDK backend ' +
+				'(api.reclaimprotocol.org — what the verification SDK/attestor ' +
+				'itself fetches at runtime), for ANY provider, no auth required. ' +
+				'Different from get_provider_version_config, which reads the old ' +
+				'devtools DASHBOARD backend and requires auth. \n\n' +
+				'Returns two complementary reads for the given version (latest ' +
+				'when `versionNumber` is omitted): `provider` (the full provider ' +
+				'+ providerConfig, including `customInjection`) and `configs` (the ' +
+				'trimmed recipe the attestor actually consumes — `customInjection` ' +
+				'is deliberately OMITTED there, replaced by a computed ' +
+				'`isScriptRequestingClaim` flag). One endpoint failing (e.g. an ' +
+				'invalid `versionNumber`) is reported under `errors` without ' +
+				'hiding a result the other endpoint did return.',
+			inputSchema: {
+				type: 'object',
+				properties: {
+					providerId: {
+						type: 'string',
+						description: 'UUID of the provider.',
+					},
+					versionNumber: {
+						type: 'string',
+						description:
+							'Specific version, e.g. "1.0.2". Omit for the ' +
+							"provider's current latest version.",
+					},
+				},
+				required: ['providerId'],
+			},
+		},
+		async({ providerId, versionNumber }) => {
+			const [provider, configs] = await Promise.all([
+				attempt(
+					'provider',
+					() => client.getProvider(providerId, versionNumber),
+				),
+				attempt(
+					'configs',
+					() => client.getProviderConfigs(providerId, versionNumber),
+				),
+			])
+
+			const errors = [provider, configs]
+				.filter((r) => !r.ok)
+				.map((r) => (r as { error: string }).error)
+
+			return {
+				...(provider.ok ? { provider: provider.value } : {}),
+				...(configs.ok ? { configs: configs.value } : {}),
+				...(errors.length ? { errors } : {}),
+			}
+		},
+	)
+}

package/src/old/tools/get-version-config.ts

@@ -0,0 +1,56 @@
+import { defineTool, type RegisteredTool } from '../../mcp/server.ts'
+import type { ReclaimOldClient } from '../client.ts'
+
+/**
+ * Read the full `providerConfig` (loginUrl, customInjection, requestData,
+ * geoLocation, ...) of one provider version on the old devtools backend —
+ * the latest version when `version` is omitted.
+ *
+ * Exists so a dev/agent can see what's CURRENTLY published before adding a
+ * new version with `create_provider_version_from_capture`. That tool always
+ * takes a FULL replacement `providerConfig` (no partial-patch endpoint on
+ * this backend), so a version added without knowing the current
+ * `customInjection` would silently publish it blank — wiping a working
+ * login script instead of preserving it. Read it here first, then pass it
+ * straight through (or omit `customInjection` on publish to have it carried
+ * forward automatically).
+ */
+export function getProviderVersionConfigTool(
+	client: ReclaimOldClient,
+): RegisteredTool {
+	return defineTool<{ providerId: string, version?: string }>(
+		{
+			name: 'get_provider_version_config',
+			description:
+				'Fetch the full providerConfig (loginUrl, customInjection, ' +
+				'requestData, geoLocation, ...) of one version on the old devtools ' +
+				'backend — the latest version when `version` is omitted. Readable ' +
+				'for any non-archived provider, not just ones you own. Use this ' +
+				'BEFORE calling create_provider_version_from_capture with a ' +
+				'`providerId` to see the currently-published customInjection/' +
+				'requestData so you know what you would be changing — that tool ' +
+				'replaces the whole providerConfig, so a field you never see and ' +
+				"never pass comes out blank in the new version, even if it's set " +
+				'today.',
+			inputSchema: {
+				type: 'object',
+				properties: {
+					providerId: {
+						type: 'string',
+						description: 'UUID of the provider (from get_me_providers).',
+					},
+					version: {
+						type: 'string',
+						description:
+							'Specific version to fetch, e.g. "1.0.2". Omit for the ' +
+							"provider's current latest version.",
+					},
+				},
+				required: ['providerId'],
+			},
+		},
+		async({ providerId, version }) => {
+			return client.getProviderConfig(providerId, version)
+		},
+	)
+}

package/src/old/tools/publish.ts

@@ -1,14 +1,18 @@
 import { Boom, isBoom } from '@hapi/boom'
 import { defineTool, type RegisteredTool } from '../../mcp/server.ts'
+import { INJECTION_GUIDE } from '../../provider/injection-doc.ts'
 import {
 	countsFor,
 	matchRedactionWarnings,
 } from '../../provider/match-redaction-warning.ts'
 import type { ReclaimProvider } from '../../provider/schema.ts'
+import type { AllowedJsRequest } from '../../provider/to-version.ts'
 import type { ReclaimOldClient } from '../client.ts'
 import {
 	bumpPatchString,
 	extractVersions,
+	injectedRequestDataFrom,
+	type OldInjectedRequestData,
 	type OldProviderOpts,
 	providerToConfigBody,
 	providerToRegisterBody,
@@ -16,6 +20,66 @@ import {
 
 const DEFAULT_VERSION_INFO = 'Updated from MCP browser capture'
 
+/** Fields with no partial-patch equivalent on this backend: a version always
+ *  replaces the WHOLE `providerConfig`, so omitting one of these on
+ *  add-version must carry forward the current value rather than publish it
+ *  blank. `allowedInjectedRequestData` is handled alongside these (further
+ *  down, inline) since it needs translation when freshly authored, unlike
+ *  these — which pass through unchanged either way. */
+const PRESERVABLE_KEYS = [
+	'customInjection',
+	'userAgent',
+	'pageTitle',
+	'stepsToFollow',
+	'useIncognitoWebview',
+	'extensionConfig',
+] as const
+
+/** Pull `providerConfig` out of a `get_provider_version_config` /
+ *  `getProviderConfig` response, tolerant of a missing/malformed shape. */
+function extractProviderConfig(
+	resp: unknown,
+): Record<string, unknown> | undefined {
+	if(resp && typeof resp === 'object') {
+		const cfg = (resp as { providerConfig?: unknown }).providerConfig
+		if(cfg && typeof cfg === 'object') {
+			return cfg as Record<string, unknown>
+		}
+	}
+
+	return undefined
+}
+
+/** Prefer the caller's explicit value; otherwise fall back to `current`'s
+ *  value (if any) and record `fieldName` as carried forward.
+ *
+ *  `current === null` is treated the SAME as `undefined` (nothing to carry),
+ *  not as a real value to preserve. These are all optional fields with no
+ *  Prisma default — a version where one was never set reads back as
+ *  `null`, not a missing key, because Prisma normalizes an absent optional
+ *  field to `null` on read. Carrying that `null` "forward" would falsely
+ *  claim the field was preserved when really nothing was ever there — it
+ *  most likely means an EARLIER version already lost it (e.g. published
+ *  before this field had carry-forward support at all), not that this call
+ *  is doing anything wrong. */
+function resolveField<T>(
+	explicit: T | undefined,
+	current: unknown,
+	fieldName: string,
+	carried: string[],
+): T | undefined {
+	if(explicit !== undefined) {
+		return explicit
+	}
+
+	if(current !== undefined && current !== null) {
+		carried.push(fieldName)
+		return current as T
+	}
+
+	return undefined
+}
+
 /**
  * The old backend lets you add a version only to a provider YOU own. A
  * `providerId` for a public provider (or anyone else's) comes back as
@@ -71,6 +135,13 @@ export function createVersionFromCaptureTool(
 		useProxy?: boolean
 		providerType?: 'PRIVATE' | 'PUBLIC'
 		notes?: string
+		customInjection?: string
+		userAgent?: { ios?: string, android?: string }
+		pageTitle?: string
+		allowedInjectedRequestData?: AllowedJsRequest[]
+		stepsToFollow?: string
+		useIncognitoWebview?: boolean
+		extensionConfig?: unknown
 	}>(
 		{
 			name: 'create_provider_version_from_capture',
@@ -92,6 +163,29 @@ export function createVersionFromCaptureTool(
 				'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 (old-devtools\' name for the builder\'s ' +
+				'jsUserScripts) that drives the page to where the request fires. \n\n' +
+				'This backend has NO partial-patch endpoint — adding a version ' +
+				'always replaces the WHOLE providerConfig. When `providerId` is ' +
+				'set, any of `customInjection`, `userAgent`, `pageTitle`, ' +
+				'`allowedInjectedRequestData`, `stepsToFollow`, ' +
+				'`useIncognitoWebview`, `extensionConfig` that you OMIT is carried ' +
+				'forward unchanged from the currently-published version (so ' +
+				're-publishing requestData never wipes a working login script or ' +
+				'other config someone set via the dashboard). This can only carry ' +
+				'forward what the CURRENT version actually has — if an earlier ' +
+				'version already lost a field (e.g. published before this tool ' +
+				'carried it forward at all), there is nothing left to preserve and ' +
+				'the result legitimately comes back empty/null for that field; ' +
+				'that is not this call failing to carry it forward. Pass an ' +
+				'explicit value (`""`, `[]`, `false`, ...) to intentionally clear ' +
+				'one of them instead, or call get_provider_version_config FIRST ' +
+				'to see exactly what is live today, rather than assuming this ' +
+				'call recovered something that may already be gone. ' +
+				'`allowedInjectedRequestData`/`useIncognitoWebview`/' +
+				'`extensionConfig` only take effect on add-version — the register ' +
+				'endpoint (no `providerId`) ignores them. \n\n' +
 				'Captured requests must be GET/POST. OPRF redactions are supported.',
 			inputSchema: {
 				type: 'object',
@@ -171,6 +265,78 @@ export function createVersionFromCaptureTool(
 							'Change note for the new version (update only; must be ≥10 ' +
 							'chars or a default is used).',
 					},
+					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,
+					},
+					userAgent: {
+						type: 'object',
+						description:
+							'Per-platform user-agent override for the verification ' +
+							'webview. Accepted on register too.',
+						properties: {
+							ios: { type: 'string' },
+							android: { type: 'string' },
+						},
+					},
+					pageTitle: {
+						type: 'string',
+						description: 'Page title metadata. Accepted on register too.',
+					},
+					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).',
+						items: {
+							type: 'object',
+							properties: {
+								url: { type: 'string' },
+								method: { type: 'string' },
+								body: { type: 'string' },
+								responseMatches: { type: 'array' },
+								responseRedactions: { type: 'array' },
+								multiple: {
+									type: 'boolean',
+									description: 'Allow matching many requests. Default true.',
+								},
+								required: {
+									type: 'boolean',
+									description:
+										'Fail validation if none match. Default true.',
+								},
+							},
+							required: ['url', 'method'],
+						},
+					},
+					stepsToFollow: {
+						type: 'string',
+						description:
+							'Free-text setup/manual-verification steps shown to the ' +
+							'dev/verifier. Accepted on register too.',
+					},
+					useIncognitoWebview: {
+						type: 'boolean',
+						description:
+							'Run the verification webview in incognito mode. ' +
+							'Add-version ONLY.',
+					},
+					extensionConfig: {
+						description:
+							'Free-form JSON passed through to the client. Add-version ' +
+							'ONLY.',
+					},
 				},
 				required: ['initialUrl'],
 			},
@@ -207,11 +373,16 @@ export function createVersionFromCaptureTool(
 				opts.providerType = args.providerType
 			}
 
+			if(args.customInjection !== undefined) {
+				opts.customInjection = args.customInjection
+			}
+
 			// Non-blocking advisory per request — never alters or blocks the
 			// publish; the author keeps full control. Attaches under `_notes`.
 			const notes = matchRedactionWarnings(
 				providers.map((p, i) => countsFor(`Request ${i + 1}`, p)),
 			)
+
 			const withNotes = (result: unknown) => {
 				if(notes.length && result && typeof result === 'object') {
 					return { ...result, _notes: notes }
@@ -220,8 +391,50 @@ export function createVersionFromCaptureTool(
 				return result
 			}
 
-			// New provider.
+			// New provider — no prior version to carry anything forward from.
+			// `allowedInjectedRequestData` / `useIncognitoWebview` /
+			// `extensionConfig` are accepted on the schema but the register
+			// controller never reads them from the body — warn rather than
+			// silently drop, so a dev doesn't think they took effect.
 			if(!args.providerId) {
+				if(opts.customInjection?.trim()) {
+					notes.push(
+						'customInjection will run in the verification client before ' +
+						'every page load (before navigating to initialUrl), matching ' +
+						'the builder\'s jsUserScripts.',
+					)
+				}
+
+				const REGISTER_IGNORED_KEYS = [
+					'allowedInjectedRequestData',
+					'useIncognitoWebview',
+					'extensionConfig',
+				] as const
+				const ignoredOnRegister = REGISTER_IGNORED_KEYS
+					.filter((k) => args[k] !== undefined)
+				if(ignoredOnRegister.length) {
+					notes.push(
+						`${ignoredOnRegister.join(', ')} ${
+							ignoredOnRegister.length > 1 ? 'are' : 'is'
+						} ignored on register (no providerId) — the old backend only ` +
+						'reads them when adding a version. Publish once to create ' +
+						'the provider, then call this again WITH the returned ' +
+						'providerId to set them.',
+					)
+				}
+
+				if(args.userAgent !== undefined) {
+					opts.userAgent = args.userAgent
+				}
+
+				if(args.pageTitle !== undefined) {
+					opts.pageTitle = args.pageTitle
+				}
+
+				if(args.stepsToFollow !== undefined) {
+					opts.stepsToFollow = args.stepsToFollow
+				}
+
 				const body = providerToRegisterBody(providers, opts)
 				return withNotes(await client.registerProvider(body))
 			}
@@ -232,6 +445,56 @@ export function createVersionFromCaptureTool(
 			// workaround instead of a bare permission error.
 			const providerId = args.providerId
 			try {
+				// This backend has no partial-patch endpoint — a version always
+				// replaces the WHOLE providerConfig. Anything the caller didn't
+				// pass at all is carried forward from the currently-published
+				// version instead of going out blank. Pass an explicit empty
+				// value ("", [], false) to intentionally clear one.
+				const needsCurrent = PRESERVABLE_KEYS.some((k) => args[k] === undefined)
+					|| args.allowedInjectedRequestData === undefined
+				const current = needsCurrent
+					? extractProviderConfig(await client.getProviderConfig(providerId))
+					: undefined
+
+				const carried: string[] = []
+				for(const key of PRESERVABLE_KEYS) {
+					const resolved = resolveField(args[key], current?.[key], key, carried)
+					if(resolved !== undefined) {
+						(opts as unknown as Record<string, unknown>)[key] = resolved
+					}
+				}
+
+				const freshInjected = args.allowedInjectedRequestData !== undefined
+					? injectedRequestDataFrom(args.allowedInjectedRequestData)
+					: undefined
+				const resolvedInjected = resolveField<OldInjectedRequestData[]>(
+					freshInjected,
+					current?.allowedInjectedRequestData,
+					'allowedInjectedRequestData',
+					carried,
+				)
+				if(resolvedInjected !== undefined) {
+					opts.allowedInjectedRequestData = resolvedInjected
+				}
+
+				if(carried.length) {
+					notes.push(
+						'Not passed, carried forward unchanged from the current ' +
+						`published version: ${carried.join(', ')}. Pass an explicit ` +
+						'value ("", [], false, ...) to override any of them, or ' +
+						'call get_provider_version_config first to see what is ' +
+						'live today.',
+					)
+				}
+
+				if(args.customInjection !== undefined && opts.customInjection?.trim()) {
+					notes.push(
+						'customInjection will run in the verification client before ' +
+						'every page load (before navigating to initialUrl), matching ' +
+						'the builder\'s jsUserScripts.',
+					)
+				}
+
 				const versionsResp = await client.listVersions(providerId)
 				const version = bumpPatchString(extractVersions(versionsResp))
 				const versionInfo =

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

@@ -0,0 +1,72 @@
+import { defineTool, type RegisteredTool } from '../../mcp/server.ts'
+import type { ReclaimOldClient, UpdateProviderMetadataBody } from '../client.ts'
+
+/**
+ * Edit provider-level metadata on the old devtools backend
+ * (`POST /api/providers/:providerId`) — a genuine PARTIAL update on the
+ * PROVIDER document itself, distinct from both
+ * `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
+ * no new version is created).
+ *
+ * The backend 403s if you don't own the provider (and aren't an admin) —
+ * surfaced verbatim, same as any other auth failure from this client.
+ */
+export function updateProviderMetadataTool(
+	client: ReclaimOldClient,
+): RegisteredTool {
+	return defineTool<UpdateProviderMetadataBody & { providerId: string }>(
+		{
+			name: 'update_provider_metadata',
+			description:
+				'Rename, redescribe, retag, flip providerType (PRIVATE/PUBLIC), or ' +
+				'toggle isActive on a provider YOU own — WITHOUT creating a new ' +
+				'version. Only the fields you pass change; everything else ' +
+				'(requestData, customInjection, versions, ...) is untouched. Pass ' +
+				'at least one of the optional fields. Get a `providerId` from ' +
+				'get_me_providers.',
+			inputSchema: {
+				type: 'object',
+				properties: {
+					providerId: {
+						type: 'string',
+						description: 'UUID of the provider to update.',
+					},
+					name: { type: 'string', description: 'New provider name.' },
+					description: {
+						type: 'string',
+						description: 'New provider description.',
+					},
+					providerType: {
+						type: 'string',
+						enum: ['PRIVATE', 'PUBLIC'],
+						description: 'Change PRIVATE/PUBLIC visibility.',
+					},
+					tags: {
+						type: 'array',
+						items: { type: 'string' },
+						description: 'Replace the provider\'s tag list.',
+					},
+					isActive: {
+						type: 'boolean',
+						description: 'Whether the provider is active.',
+					},
+				},
+				required: ['providerId'],
+			},
+		},
+		async({ providerId, ...body }) => {
+			const hasAnyField = Object.values(body).some((v) => v !== undefined)
+			if(!hasAnyField) {
+				throw new Error(
+					'Pass at least one of: name, description, providerType, tags, ' +
+					'isActive.',
+				)
+			}
+
+			return client.updateProviderMetadata(providerId, body)
+		},
+	)
+}

package/src/proof/attestor.ts

@@ -10,9 +10,14 @@ import { bytesToHex } from '@noble/hashes/utils.js'
 import {
 	createClaimOnAttestor, type Logger,
 } from '@reclaimprotocol/attestor-core'
+// Side-effect: make external domhandler nodes DOM-like so attestor-core's
+// bundled `xpath` accepts them (see patch-domhandler.ts). Must load before any
+// proof runs its response-redaction extraction.
+import './patch-domhandler.ts'
 import { agentTraceEnabled } from '../consts.ts'
 import { resolveEthKey } from '../mcp/tools/authenticate/eth-key.ts'
 import type { ReclaimProvider } from '../provider/schema.ts'
+import { installResponseDump } from './debug-response-dump.ts'
 import {
 	buildHttpParams, ensureAttestorCrypto, parseClaim, resolveAttestorUrl,
 } from './proof-core.ts'
@@ -47,9 +52,11 @@ export interface RunAttestorProofOptions {
 	/** Sign with this key directly (e.g. the app/VC's ephemeral per-session key)
 	 *  instead of resolving from env/.env/file. */
 	ownerPrivateKey?: string
-	/** ZK engine for `createClaimOnAttestor`. Defaults to `'gnark'`; the app's
-	 *  server-side verification runner uses `'snarkjs'`. */
-	zkEngine?: 'gnark' | 'snarkjs'
+	/** 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). */
+	zkEngine?: 'gnark' | 'snarkjs' | 'stwo'
 	/** Extract the structured {@link AttestorClaim} (claim + attestor signature)
 	 *  onto the result for nested-proof construction. */
 	includeAttestorClaim?: boolean
@@ -249,6 +256,11 @@ export async function runAttestorProof(
 		const capture = traceEnabled ? makeCaptureLogger() : undefined
 		const attestorLogs = capture?.entries
 
+		// Debug (RECLAIM_AGENT_DUMP_RESPONSE): dump the exact response the
+		// attestor validates against, so "Response does not contain X" is
+		// diagnosable against the attestor's real server-side fetch.
+		installResponseDump()
+
 		let claim: unknown
 		try {
 			claim = await createClaimOnAttestor({
@@ -259,7 +271,7 @@ export async function runAttestorProof(
 				},
 				ownerPrivateKey,
 				client: { url: resolveAttestorUrl(opts.attestorUrl) },
-				zkEngine: opts.zkEngine ?? 'gnark',
+				zkEngine: opts.zkEngine ?? 'stwo',
 				...(capture !== undefined && { logger: capture.logger as Logger }),
 			})
 		} catch(err) {

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

@@ -0,0 +1,70 @@
+// 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.
+//
+// On each getResponseRedactions call it writes the response to
+// `attestor-last-response.html` in the process CWD and logs the byte count +,
+// for every responseMatch (paramValues substituted), whether it's present.
+import { providers } from '@reclaimprotocol/attestor-core'
+import { writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+interface RedactionArg {
+	response: Uint8Array
+	params: {
+		responseMatches?: Array<{ value?: string }>
+		paramValues?: Record<string, string>
+	}
+}
+
+let installed = false
+
+/** Wrap attestor-core's http `getResponseRedactions` to dump the response it
+ *  runs against. Idempotent; no-op unless RECLAIM_AGENT_DUMP_RESPONSE is
+ *  set. */
+export function installResponseDump(): void {
+	if(installed || !process.env['RECLAIM_AGENT_DUMP_RESPONSE']) {
+		return
+	}
+
+	const http = providers['http'] as unknown as {
+		getResponseRedactions?: (arg: RedactionArg) => unknown
+	}
+	const original = http.getResponseRedactions
+	if(typeof original !== 'function') {
+		return
+	}
+
+	installed = true
+	http.getResponseRedactions = function(this: unknown, arg: RedactionArg) {
+		try {
+			const bytes = Buffer.from(arg.response)
+			const text = bytes.toString('utf8')
+			const paramValues = arg.params.paramValues ?? {}
+			const matches = (arg.params.responseMatches ?? []).map((m) => {
+				let value = m.value ?? ''
+				for(const [key, val] of Object.entries(paramValues)) {
+					value = value.split(`{{${key}}}`).join(val)
+				}
+
+				return { value, present: text.includes(value) }
+			})
+			const path = join(process.cwd(), 'attestor-last-response.html')
+			writeFileSync(path, text)
+			process.stderr.write(`${JSON.stringify({
+				tag: 'attestor-response-dump',
+				bytes: bytes.length,
+				path,
+				matches,
+			})}\n`)
+		} catch{
+			// diagnostic only — never break proving
+		}
+
+		return original.call(this, arg)
+	}
+}