@reclaimprotocol/agent 0.1.5 → 0.1.7

package/lib/old/tools/get-provider-info.js

@@ -0,0 +1,73 @@
+import { isBoom } from '@hapi/boom';
+import { defineTool } from "../../mcp/server.js";
+/** 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, call) {
+    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) {
+    return defineTool({
+        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.error);
+        return {
+            ...(provider.ok ? { provider: provider.value } : {}),
+            ...(configs.ok ? { configs: configs.value } : {}),
+            ...(errors.length ? { errors } : {}),
+        };
+    });
+}

package/lib/old/tools/get-version-config.d.ts

@@ -0,0 +1,17 @@
+import { 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 declare function getProviderVersionConfigTool(client: ReclaimOldClient): RegisteredTool;

package/lib/old/tools/get-version-config.js

@@ -0,0 +1,47 @@
+import { defineTool } from "../../mcp/server.js";
+/**
+ * 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) {
+    return defineTool({
+        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/lib/old/tools/publish.js

@@ -1,8 +1,56 @@
 import { Boom, isBoom } from '@hapi/boom';
 import { defineTool } from "../../mcp/server.js";
+import { INJECTION_GUIDE } from "../../provider/injection-doc.js";
 import { countsFor, matchRedactionWarnings, } from "../../provider/match-redaction-warning.js";
-import { bumpPatchString, extractVersions, providerToConfigBody, providerToRegisterBody, } from "../to-register.js";
+import { bumpPatchString, extractVersions, injectedRequestDataFrom, providerToConfigBody, providerToRegisterBody, } from "../to-register.js";
 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',
+];
+/** Pull `providerConfig` out of a `get_provider_version_config` /
+ *  `getProviderConfig` response, tolerant of a missing/malformed shape. */
+function extractProviderConfig(resp) {
+    if (resp && typeof resp === 'object') {
+        const cfg = resp.providerConfig;
+        if (cfg && typeof cfg === 'object') {
+            return cfg;
+        }
+    }
+    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(explicit, current, fieldName, carried) {
+    if (explicit !== undefined) {
+        return explicit;
+    }
+    if (current !== undefined && current !== null) {
+        carried.push(fieldName);
+        return current;
+    }
+    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
@@ -60,6 +108,29 @@ export function createVersionFromCaptureTool(client) {
             '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',
@@ -132,6 +203,71 @@ export function createVersionFromCaptureTool(client) {
                     description: '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'],
         },
@@ -158,6 +294,9 @@ export function createVersionFromCaptureTool(client) {
         if (args.providerType !== undefined) {
             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)));
@@ -167,8 +306,39 @@ export function createVersionFromCaptureTool(client) {
             }
             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',
+            ];
+            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));
         }
@@ -178,6 +348,42 @@ export function createVersionFromCaptureTool(client) {
         // 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 = [];
+            for (const key of PRESERVABLE_KEYS) {
+                const resolved = resolveField(args[key], current?.[key], key, carried);
+                if (resolved !== undefined) {
+                    opts[key] = resolved;
+                }
+            }
+            const freshInjected = args.allowedInjectedRequestData !== undefined
+                ? injectedRequestDataFrom(args.allowedInjectedRequestData)
+                : undefined;
+            const resolvedInjected = resolveField(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 = args.notes && args.notes.trim().length >= 10

package/lib/old/tools/update-provider-metadata.d.ts

@@ -0,0 +1,16 @@
+import { type RegisteredTool } from '../../mcp/server.ts';
+import type { ReclaimOldClient } 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 declare function updateProviderMetadataTool(client: ReclaimOldClient): RegisteredTool;

package/lib/old/tools/update-provider-metadata.js

@@ -0,0 +1,61 @@
+import { defineTool } from "../../mcp/server.js";
+/**
+ * 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) {
+    return defineTool({
+        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/lib/proof/attestor.d.ts

@@ -1,3 +1,4 @@
+import './patch-domhandler.ts';
 import type { ReclaimProvider } from '../provider/schema.ts';
 export interface AttestorLogEntry {
     level: 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
@@ -26,9 +27,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;

package/lib/proof/attestor.js

@@ -7,8 +7,13 @@
 // reveals), never on responseMatches.
 import { bytesToHex } from '@noble/hashes/utils.js';
 import { createClaimOnAttestor, } 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.js";
 import { agentTraceEnabled } from "../consts.js";
 import { resolveEthKey } from "../mcp/tools/authenticate/eth-key.js";
+import { installResponseDump } from "./debug-response-dump.js";
 import { buildHttpParams, ensureAttestorCrypto, parseClaim, resolveAttestorUrl, } from "./proof-core.js";
 import { ensureZkFiles } from "./zk-files.js";
 /** Trim a captured log stream to the last N entries — for shrinking the
@@ -140,6 +145,10 @@ export async function runAttestorProof(provider, secrets, opts = {}) {
         const traceEnabled = agentTraceEnabled();
         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;
         try {
             claim = await createClaimOnAttestor({
@@ -150,7 +159,7 @@ export async function runAttestorProof(provider, secrets, opts = {}) {
                 },
                 ownerPrivateKey,
                 client: { url: resolveAttestorUrl(opts.attestorUrl) },
-                zkEngine: opts.zkEngine ?? 'gnark',
+                zkEngine: opts.zkEngine ?? 'stwo',
                 ...(capture !== undefined && { logger: capture.logger }),
             });
         }

package/lib/proof/debug-response-dump.d.ts

@@ -0,0 +1,4 @@
+/** Wrap attestor-core's http `getResponseRedactions` to dump the response it
+ *  runs against. Idempotent; no-op unless RECLAIM_AGENT_DUMP_RESPONSE is
+ *  set. */
+export declare function installResponseDump(): void;

package/lib/proof/debug-response-dump.js

@@ -0,0 +1,55 @@
+// 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';
+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() {
+    if (installed || !process.env['RECLAIM_AGENT_DUMP_RESPONSE']) {
+        return;
+    }
+    const http = providers['http'];
+    const original = http.getResponseRedactions;
+    if (typeof original !== 'function') {
+        return;
+    }
+    installed = true;
+    http.getResponseRedactions = function (arg) {
+        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);
+    };
+}

package/lib/proof/patch-domhandler.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/proof/patch-domhandler.js

@@ -0,0 +1,59 @@
+// Side-effect module: make `domhandler` nodes DOM-like for the `xpath` engine.
+//
+// WHY THIS EXISTS
+// `@reclaimprotocol/attestor-core`'s published `lib` bundles its own inlined
+// copy of `domhandler` and applies a DOM-compat patch (nodeName / localName +
+// a NamedNodeMap `item()` shim) to THAT copy. But at proof time the HTML tree
+// is built by the *external* `parse5-htmlparser2-tree-adapter`, which uses the
+// separately-installed `domhandler` — a different, UNPATCHED copy. The `xpath`
+// engine then fails `isNodeLike()` on every node (it needs a string `nodeName`)
+// and throws "Context node does not appear to be a valid DOM node", so ALL
+// xPath / xPath+jsonPath response redactions fail during `runAttestorProof`'s
+// receipt validation. (Regex-only redactions escape it — they never touch the
+// parse5/xpath path.) Running attestor-core from source works because there is
+// then a single shared `domhandler`; the bug is only in the bundled `lib`.
+//
+// Rather than fork attestor-core, apply the identical patch to the external
+// `domhandler` the adapter actually uses, so its tree nodes are DOM-like. This
+// mirrors attestor-core's own `patch-parse5-tree`. Idempotent and
+// version-agnostic. Import it before any proving path runs.
+//
+// Remove once attestor-core externalizes `domhandler` in its build (one shared
+// copy → its own patch suffices).
+import { Element, Node } from 'domhandler';
+const PATCH_FLAG = Symbol.for('reclaim.domhandler.domCompatPatched');
+const proto = Node.prototype;
+if (!proto[PATCH_FLAG]) {
+    // `xpath`'s isNodeLike() requires a string `nodeName`; domhandler nodes carry
+    // the tag under `.name`.
+    Object.defineProperty(Node.prototype, 'nodeName', {
+        configurable: true,
+        get() {
+            return this.name;
+        },
+    });
+    Object.defineProperty(Node.prototype, 'localName', {
+        configurable: true,
+        get() {
+            return this.name;
+        },
+    });
+    // Attribute-predicate steps (`[@id=…]`, `contains(@class,…)`) walk the
+    // NamedNodeMap via `.item(i)`; give each returned attribute node the DOM
+    // shape `xpath` expects (nodeType 2 + localName).
+    const attrsGetter = Object.getOwnPropertyDescriptor(Element.prototype, 'attributes')?.get;
+    if (attrsGetter) {
+        Object.defineProperty(Element.prototype, 'attributes', {
+            configurable: true,
+            get() {
+                const attrs = attrsGetter.call(this);
+                attrs.item = (i) => {
+                    const attr = attrs[i];
+                    return { ...attr, nodeType: 2, localName: attr.name };
+                };
+                return attrs;
+            },
+        });
+    }
+    proto[PATCH_FLAG] = true;
+}