@reclaimprotocol/agent 0.1.4 → 0.1.6

package/lib/old/tools/publish.js

@@ -1,8 +1,46 @@
 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 (see
+ *  `resolveInjectedRequests`) 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. */
+function resolveField(explicit, current, fieldName, carried) {
+    if (explicit !== undefined) {
+        return explicit;
+    }
+    if (current !== undefined) {
+        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 +98,23 @@ 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). 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 before deciding what to change. ' +
+            '`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 +187,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. Add-version ONLY.',
+                },
+                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 +278,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 +290,36 @@ 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;
+            }
             const body = providerToRegisterBody(providers, opts);
             return withNotes(await client.registerProvider(body));
         }
@@ -178,6 +329,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;
+}

package/lib/proof/proof-core.d.ts

@@ -18,7 +18,7 @@ export declare function ensureAttestorCrypto(): void;
  *  default. Resolved per-call so an env change or per-request override takes
  *  effect without restarting. */
 export declare function resolveAttestorUrl(override?: string): string;
-/** Map a verification's provider recipe straight to the attestor's HTTP
+/** Map a provider's recipe straight to the attestor's HTTP
  *  params — never synthesized from captured traffic. */
 export declare function buildHttpParams(provider: ReclaimProvider): ProviderParams<'http'>;
 export interface ParsedClaim {

package/lib/proof/proof-core.js

@@ -21,7 +21,7 @@ export function ensureAttestorCrypto() {
 export function resolveAttestorUrl(override) {
     return (override ?? attestorUrlOverride() ?? FALLBACK_ATTESTOR_URL);
 }
-/** Map a verification's provider recipe straight to the attestor's HTTP
+/** Map a provider's recipe straight to the attestor's HTTP
  *  params — never synthesized from captured traffic. */
 export function buildHttpParams(provider) {
     // A blank egress is treated as unset: omit it so the local proof uses the

package/lib/proof/zk-files.js

@@ -1,6 +1,7 @@
 // Lazy download of the @reclaimprotocol/zk-symmetric-crypto circuit resources
-// that the snarkjs proof engine needs. These are ~280MB and are NOT fetched in
-// a `postinstall` (that blocked the MCP server's first launch past the connect
+// the proof engines need (the downloader fetches every engine — stwo, snarkjs,
+// gnark — as one bundle). These are ~280MB and are NOT fetched in a
+// `postinstall` (that blocked the MCP server's first launch past the connect
 // timeout — see the install notes). Instead we fetch them on the first proof,
 // once, so the server starts immediately and only `run_proof` pays the cost.
 import { spawn } from 'node:child_process';
@@ -38,12 +39,12 @@ async function download() {
         return;
     }
     // mainPath is <pkg>/lib/index.js → resources live at <pkg>/resources, the
-    // downloader at <pkg>/lib/scripts/download-files.js. We only use the snarkjs
-    // engine (createClaimOnAttestor zkEngine: 'snarkjs'), so its presence is the
-    // signal that the circuits are ready.
+    // downloader at <pkg>/lib/scripts/download-files.js. Proofs default to the
+    // stwo (WASM) engine, so its resource dir being present is the signal that
+    // the circuits are ready (the downloader fetches all engines together).
     const libDir = dirname(mainPath);
     const pkgDir = dirname(libDir);
-    if (existsSync(join(pkgDir, 'resources', 'snarkjs'))) {
+    if (existsSync(join(pkgDir, 'resources', 'stwo'))) {
         return;
     }
     const downloadScript = join(libDir, 'scripts', 'download-files.js');

package/lib/provider/dom-xpath.d.ts

@@ -0,0 +1,17 @@
+import '../proof/patch-domhandler.ts';
+export interface DomAnchor {
+    xPath: string;
+    /** Byte range of the element in the source html (parse5 source locations),
+     *  matching the slice the attestor reveals for this xPath. */
+    start: number;
+    end: number;
+}
+/**
+ * A verified xPath to the tightest element containing one of `targets`, or
+ * undefined if the value isn't present in the parsed tree. Prefers a short
+ * stable selector (unique id → identifying attr → class), falling back to an
+ * absolute child-indexed path (`/html[1]/body[1]/…/option[1]`). Every candidate
+ * is checked with the real `xpath` engine and only returned if it resolves,
+ * first-match, to that exact element.
+ */
+export declare function elementAnchor(html: string, targets: string[]): DomAnchor | undefined;