@reclaimprotocol/agent 0.1.23 → 0.1.25

package/lib/proof/pod-prover.js

@@ -0,0 +1,155 @@
+/**
+ * PopcornPodProver — run the zkTLS proof inside a Popcorn browser session's
+ * OWN TEE pod instead of the in-process attestor SDK (`runAttestorProof`).
+ * POSTs the recipe + captured secrets to the pod's `/reclaim/prove` (the same
+ * attestor TEE+MPC protocol) and re-shapes the response into the shared
+ * {@link ProofResult}, so every caller consumes proof results identically
+ * regardless of which path produced them.
+ *
+ * This is the pod's OWN api for creating a proof from a live session — used
+ * by both the app's server-driven verification runner and the MCP's
+ * `run_proof_via_pod` tool. Proving here (rather than locally) matters
+ * specifically when the session is country-routed: Popcorn allocated the
+ * browser with an exit country, and this is the SAME enclave holding that
+ * browser's TLS session, so the proof reaches the target from the identical
+ * exit IP the browser used — a local attestor SDK proof runs from the
+ * app/agent's OWN network instead.
+ *
+ * Contract (verified against ../popcorn-images oapi.go + ../reclaim-tee):
+ *   POST {apiUrl}/reclaim/prove  body { provider_params_json, config_json? }
+ *   provider_params_json = JSON of { name, params, secretParams, context? }
+ *   → 200 { session_id, claim, signature } (ReclaimProveResult, snake_case):
+ *     claim has provider/parameters/owner/timestamp_s/context/identifier/epoch;
+ *     signature has attestor_address + claim_signature(b64) +
+ *     result_signature(b64). A proof failure/timeout is a 500 whose `message`
+ *     carries the reason.
+ *
+ * The pod API is unauthenticated (gateway/session is the trust boundary); call
+ * it over the same internal host used for CDP. Consumers verify
+ * `claim_signature` only (see `@reclaimprotocol/client`'s `verifyNestedProof`),
+ * so this hands back a {@link AttestorClaim} whose hex `claimSignature` the
+ * shared `wrapProofAsJws` (app-side) turns into the nested result proof.
+ * `result_signature` is unused by any consumer.
+ */
+import { bytesToHex } from '@noble/hashes/utils.js';
+/**
+ * The cloud "replay": validate that a drafted recipe's selectors extract the
+ * expected value from a captured response, inside the TEE — `POST {apiUrl}
+ * /reclaim/validate-extraction`. Reuses the prover's own redaction engine, so
+ * a pass means the selectors won't diverge at proof time. No proof/secrets.
+ */
+export async function popcornValidateExtraction(opts) {
+    const doFetch = opts.fetchImpl ?? fetch;
+    const base = opts.apiUrl.replace(/\/$/, '');
+    try {
+        const res = await doFetch(`${base}/reclaim/validate-extraction`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                responseBody: opts.responseBody,
+                expectedValue: opts.expectedValue,
+                ...(opts.xPath ? { xPath: opts.xPath } : {}),
+                ...(opts.jsonPath ? { jsonPath: opts.jsonPath } : {}),
+                ...(opts.regex ? { regex: opts.regex } : {}),
+            }),
+        });
+        if (!res.ok) {
+            const detail = await res.text().catch(() => '');
+            return { valid: false, error: `${res.status}: ${detail.slice(0, 300)}` };
+        }
+        const body = (await res.json());
+        return body;
+    }
+    catch (err) {
+        const error = err instanceof Error ? err.message : String(err);
+        return { valid: false, error };
+    }
+}
+/** Decode standard base64 (Go `base64.StdEncoding` from Popcorn) to bytes. */
+function b64ToBytes(b64) {
+    return new Uint8Array(Buffer.from(b64, 'base64'));
+}
+/**
+ * Prove a single request through the Popcorn TEE. Returns the shared
+ * {@link ProofResult}; on any failure `verified` is false and `error` carries
+ * the reason (never throws for an expected proof failure).
+ */
+export async function popcornProve(opts) {
+    const { apiUrl, params, secretParams, context } = opts;
+    const doFetch = opts.fetchImpl ?? fetch;
+    const base = apiUrl.replace(/\/$/, '');
+    const providerParamsJson = JSON.stringify({
+        name: 'http',
+        params,
+        secretParams,
+        ...(context ? { context: JSON.stringify(context) } : {}),
+    });
+    const fail = (error) => ({
+        proof: undefined,
+        extractedValue: '',
+        extractedParameters: {},
+        verified: false,
+        error,
+    });
+    let resp;
+    let raw = '';
+    try {
+        const res = await doFetch(`${base}/reclaim/prove`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ provider_params_json: providerParamsJson }),
+        });
+        // Read the body as text first: a proof failure/timeout is a 500 whose
+        // `message` we want to surface verbatim, and on an unexpected 200 shape we
+        // echo the raw body instead of a blind "no claim/signature".
+        raw = await res.text().catch(() => '');
+        if (!res.ok) {
+            return fail(`/reclaim/prove ${res.status}: ${raw.slice(0, 300)}`);
+        }
+        resp = JSON.parse(raw);
+    }
+    catch (err) {
+        return fail(err instanceof Error ? err.message : String(err));
+    }
+    const claim = resp.claim;
+    const sig = resp.signature;
+    if (!claim || !sig?.attestor_address || !sig?.claim_signature) {
+        return fail('popcorn /reclaim/prove returned no claim/signature: '
+            + raw.slice(0, 300));
+    }
+    // claim.context is the JSON string carrying { extractedParameters, ... } —
+    // the same place the in-process path reads them from.
+    let extractedParameters = {};
+    if (typeof claim.context === 'string') {
+        try {
+            const ctx = JSON.parse(claim.context);
+            extractedParameters = ctx.extractedParameters ?? {};
+        }
+        catch {
+            // leave empty if context isn't valid JSON
+        }
+    }
+    const attestorClaim = {
+        claim: {
+            provider: claim.provider ?? '',
+            parameters: claim.parameters ?? '',
+            owner: claim.owner ?? '',
+            timestampS: claim.timestamp_s ?? 0,
+            context: claim.context ?? '',
+            identifier: claim.identifier ?? '',
+            epoch: claim.epoch ?? 0,
+        },
+        attestorAddress: sig.attestor_address,
+        // Consumer-side verification expects hex; Popcorn signs in base64.
+        claimSignature: '0x' + bytesToHex(b64ToBytes(sig.claim_signature)),
+    };
+    return {
+        proof: resp,
+        verified: true,
+        extractedParameters,
+        extractedValue: Object.values(extractedParameters)[0] ?? '',
+        ...(claim.identifier ? { identifier: claim.identifier } : {}),
+        ...(claim.owner ? { owner: claim.owner } : {}),
+        attestorClaim,
+    };
+}

package/lib/provider/dom-xpath.js

@@ -137,9 +137,10 @@ export function elementAnchor(html, targets) {
 /** The tightest element that DIRECTLY holds a target. Prefers a COMPLETE-value
  *  occurrence — an attribute whose value IS the target, or a text child that IS
  *  the target — over one where the target is merely embedded in a longer string
- *  (e.g. a userid inside a `1234567+user@…` noreply address). The complete
- *  field is the semantic source and yields a portable anchor; the embedded one
- *  is incidental. Smallest byte span wins within the chosen tier. */
+ *  (for example, a userid inside a `1234567+user@…` noreply address). The
+ *  complete field is the semantic source and yields a portable anchor; the
+ *  embedded one is incidental. Smallest byte span wins within the chosen
+ *  tier. */
 function findElement(root, targets) {
     const complete = [];
     const embedded = [];
@@ -196,8 +197,8 @@ function* candidateXPaths(el) {
     }
     // A uniquely-identified DIRECT child pins the parent without a positional
     // path (`//span[span[@id="labels"]]`). Self-verification discards it when the
-    // child id/attr isn't unique — e.g. GitHub reuses `id="labels"` per email row
-    // — so it never silently matches the wrong node.
+    // child id/attr isn't unique — for example, GitHub reuses `id="labels"` per
+    // email row — so it never silently matches the wrong node.
     for (const child of el.children) {
         if (!isTag(child)) {
             continue;
@@ -234,8 +235,9 @@ function distinctiveClass(cls) {
         .filter(Boolean)
         .sort((x, y) => y.length - x.length)[0];
 }
-/** Positional path from `anc` (exclusive) down to `el` (inclusive), e.g.
- *  `/ul[1]/li[3]/a[1]`; empty string when `anc` is not an ancestor of `el`. */
+/** Positional path from `anc` (exclusive) down to `el` (inclusive), for
+ *  example `/ul[1]/li[3]/a[1]`. Empty string when `anc` is not an ancestor
+ *  of `el`. */
 function relativeSteps(anc, el) {
     const parts = [];
     let node = el;
@@ -311,8 +313,8 @@ function absolutePath(el) {
 }
 /** True when `expression` selects EXACTLY `el` (one match) against `doc`. The
  *  attestor applies the redaction regex to EVERY xPath match and throws if any
- *  fails, so a non-unique selector (e.g. a class shared by sibling rows) is
- *  unusable — it must resolve to the single target element. */
+ *  fails, so a non-unique selector (for example, a class shared by sibling
+ *  rows) is unusable — it must resolve to the single target element. */
 function matchesUniquely(doc, expression, el) {
     try {
         const engine = xpath;

package/lib/provider/draft.d.ts

@@ -14,7 +14,8 @@ export interface DraftTarget {
 }
 /** The realized extraction for one target — its value paired with the
  *  redaction that reveals it (absent when matched literally). Lets a consumer
- *  validate each value against its own selector (e.g. the cloud replay). */
+ *  validate each value against its own selector (for example, the cloud
+ *  replay). */
 export interface Extraction {
     name: string;
     value: string;
@@ -30,12 +31,14 @@ export interface DraftResult {
  *  match or redaction — either a neighbouring target's value or a target's own
  *  value left un-templated. The matcher builds each target's window
  *  independently and drops the per-user WORDS it can see, but it cannot know a
- *  neighbouring value is itself user-specific (e.g. a name sharing a text node
- *  with an id — a `<b>{{id}}</b>` sitting beside a `<td>{{name}}</td>`).
- *  Cross-checking every value against every match here catches that: a portable
- *  provider contains NO captured value as a literal — each appears only as its
- *  `{{param}}`. Throwing discards the draft so the agent re-captures or
- *  re-proposes rather than shipping a provider pinned to this one user. */
+ *  neighbouring value is itself user-specific (for example, a name sharing a
+ *  text node with an id — a `<b>{{id}}</b>` sitting beside a
+ *  `<td>{{name}}</td>`). Cross-checking every value against every match here
+ *  catches
+ *  that: a portable provider contains NO captured value as a literal — each
+ *  appears only as its `{{param}}`. Throwing discards the draft so the agent
+ *  re-captures or re-proposes rather than shipping a provider pinned to this
+ *  one user. */
 export declare function assertPortableMatches(matches: ResponseMatch[], redactions: ResponseRedaction[], targets: DraftTarget[]): void;
 /** Reject a draft that OPRF-hashes a target whose value ALSO appears in the
  *  request URL. The whole point of `hash` is that the attestor never sees

package/lib/provider/draft.js

@@ -63,12 +63,14 @@ function sanitizeRequestHeaders(headers) {
  *  match or redaction — either a neighbouring target's value or a target's own
  *  value left un-templated. The matcher builds each target's window
  *  independently and drops the per-user WORDS it can see, but it cannot know a
- *  neighbouring value is itself user-specific (e.g. a name sharing a text node
- *  with an id — a `<b>{{id}}</b>` sitting beside a `<td>{{name}}</td>`).
- *  Cross-checking every value against every match here catches that: a portable
- *  provider contains NO captured value as a literal — each appears only as its
- *  `{{param}}`. Throwing discards the draft so the agent re-captures or
- *  re-proposes rather than shipping a provider pinned to this one user. */
+ *  neighbouring value is itself user-specific (for example, a name sharing a
+ *  text node with an id — a `<b>{{id}}</b>` sitting beside a
+ *  `<td>{{name}}</td>`). Cross-checking every value against every match here
+ *  catches
+ *  that: a portable provider contains NO captured value as a literal — each
+ *  appears only as its `{{param}}`. Throwing discards the draft so the agent
+ *  re-captures or re-proposes rather than shipping a provider pinned to this
+ *  one user. */
 export function assertPortableMatches(matches, redactions, targets) {
     // A baked email LOCAL-PART ("jane.doe@…") pins the provider to one user
     // even when only the domain is captured as a param — the classic result of
@@ -209,7 +211,7 @@ function resolveParamName(targetName, shorten) {
                 + 'shortenNames:false — it becomes a regex capture-group name AND '
                 + 'a paramValues key, so it must start with a letter/underscore and '
                 + 'contain only letters, digits, and underscores (we recommend '
-                + 'lower_snake_case, e.g. "employer_name"). Rename it, or drop '
+                + 'lower_snake_case, for example, "employer_name"). Rename it, or drop '
                 + '`shortenNames: false` to auto-derive a safe one.');
         }
         return targetName;
@@ -241,8 +243,8 @@ export function draftProvider(req, targets, name, hash, opts) {
                 + `param name "${paramName}"`
                 + (shortenNames
                     ? ' (names are shortened to their last alphanumeric token) — '
-                        + 'give them more distinct names, e.g. "firstName"/"surname" '
-                        + 'instead of "first_name"/"last_name"'
+                        + 'give them more distinct names, for example '
+                        + '"firstName"/"surname" instead of "first_name"/"last_name"'
                     : ' — give them distinct names, or drop `shortenNames: false` '
                         + 'to auto-derive distinct ones'));
         }

package/lib/provider/injection-doc.d.ts

@@ -1 +1,23 @@
-export declare const INJECTION_GUIDE: string;
+/**
+ * Short field hints for the user-script inputs on both publish tools
+ * (`webSettings.jsUserScripts` on the builder, `customInjection` on
+ * old-devtools).
+ *
+ * These used to inline the whole `skill/injection-api.md` guide (~22 KB) into
+ * the tool's input schema. That guide is needed by a small minority of
+ * providers, but an input-schema description is sent to the model on EVERY
+ * request — it was roughly half the old-devtools tool surface on its own. The
+ * prose now lives in `skill/user-script.md`, `skill/interception.md` and
+ * `skill/hash-validation.md`, served on demand as `how_it_works` topics; what
+ * stays here is the pointer plus the one warning that must be seen BEFORE the
+ * field is filled in, since acting on it wrongly is worse than not acting.
+ *
+ * Shared by both publish tools so the two can't drift apart.
+ */
+/** What the script is and where the real guidance lives. */
+export declare const USER_SCRIPT_HINT: string;
+/** Prefixes the `allowedJsRequests` / `allowedInjectedRequestData` field. The
+ *  trap it describes is silent and total — a mis-declared entry makes
+ *  `verifyProof({ providerId })` reject EVERY real proof — so the warning
+ *  itself stays in the schema even though its explanation moved to a topic. */
+export declare const ALLOWED_REQUESTS_HINT: string;

package/lib/provider/injection-doc.js

@@ -1,24 +1,37 @@
 /**
- * Guidance for authoring page-injection scripts (`webSettings.jsUserScripts` on
- * the builder, `customInjection` on old-devtools), surfaced to the authoring
- * model from the publish tool description. The prose lives in
- * `skill/injection-api.md` so it can be edited as markdown without touching
- * code — the same pattern as `mcp/instructions.ts`. The path resolves the same
- * from `src/provider` (dev) and `lib/provider` (published): both are two levels
- * below the package root.
+ * Short field hints for the user-script inputs on both publish tools
+ * (`webSettings.jsUserScripts` on the builder, `customInjection` on
+ * old-devtools).
  *
- * The guide leads with plain browser JavaScript (navigation/interaction via
- * standard APIs; the client already intercepts page requests) and treats
- * `window.Reclaim` as a rarely-needed edge-case bridge, pointing at the
- * authoritative `src/support/env.d.ts` rather than reproducing its surface.
- * It also covers the HAWKEYE-style live-interception path (`injectionType` /
- * `interceptorType`, `disableRequestReplay` / `isDocumentRequestReplayEnabled`)
- * and `bodySniff`, reverse-engineered from the old-devtools Prisma schema,
- * controller code, and dashboard field hints. The replay flag IS settable via
- * the publish tools (`disableRequestReplay` on old-devtools — add-version or
- * the register follow-up; `interceptorOptions` on the builder), so this is
- * recognition + authoring guidance for the remaining internals.
+ * These used to inline the whole `skill/injection-api.md` guide (~22 KB) into
+ * the tool's input schema. That guide is needed by a small minority of
+ * providers, but an input-schema description is sent to the model on EVERY
+ * request — it was roughly half the old-devtools tool surface on its own. The
+ * prose now lives in `skill/user-script.md`, `skill/interception.md` and
+ * `skill/hash-validation.md`, served on demand as `how_it_works` topics; what
+ * stays here is the pointer plus the one warning that must be seen BEFORE the
+ * field is filled in, since acting on it wrongly is worse than not acting.
+ *
+ * Shared by both publish tools so the two can't drift apart.
  */
-import { readFileSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-export const INJECTION_GUIDE = readFileSync(fileURLToPath(new URL('../../skill/injection-api.md', import.meta.url)), 'utf8').trim();
+/** What the script is and where the real guidance lives. */
+export const USER_SCRIPT_HINT = 'Plain JavaScript injected into the provider page before every page load. '
+    + 'Use standard browser APIs (window.location, element.click(), forms) to '
+    + 'drive login/navigation so the target request fires — the client already '
+    + 'intercepts page requests, and window.Reclaim is only for rare edge cases, '
+    + 'not navigation. Full guide: how_it_works({ topic: "user-script" }).';
+/** Prefixes the `allowedJsRequests` / `allowedInjectedRequestData` field. The
+ *  trap it describes is silent and total — a mis-declared entry makes
+ *  `verifyProof({ providerId })` reject EVERY real proof — so the warning
+ *  itself stays in the schema even though its explanation moved to a topic. */
+export const ALLOWED_REQUESTS_HINT = '⚠️ Only populate this if you intend to gate '
+    + '`verifyProof(proof, { providerId })`: each entry feeds a client-side '
+    + 'hash-equality check and its `url` is hashed VERBATIM (no regex/template '
+    + 'resolution, even with urlType REGEX/TEMPLATE). If the real captured URL '
+    + 'carries ANY per-session part (nonce, CSRF token, cache-busting '
+    + 'timestamp), no declared spec can ever hash-match a real proof — '
+    + 'populating it then makes verifyProof reject every real proof, which is '
+    + 'worse than leaving it empty. Diff the same endpoint\'s captured URL '
+    + 'across two sessions first. Mechanics, the body-templating rules and the '
+    + 'dangerouslyDisableContentValidation fallback: '
+    + 'how_it_works({ topic: "hash-validation" }).';

package/lib/provider/match-redaction-warning.d.ts

@@ -6,8 +6,8 @@
  * index and may not behave correctly when there are fewer matches than
  * redactions. This is NOT enforced — the author keeps full control over what
  * they publish in either old-devtools or builder mode. The tools surface these
- * strings so the dev can make an informed decision (e.g. add a functional match
- * per redaction) rather than being blocked.
+ * strings so the dev can make an informed decision (for example, add a
+ * functional match per redaction) rather than being blocked.
  */
 /** One request's match/redaction counts, with a human label for the message. */
 export interface RequestCounts {

package/lib/provider/match-redaction-warning.js

@@ -6,8 +6,8 @@
  * index and may not behave correctly when there are fewer matches than
  * redactions. This is NOT enforced — the author keeps full control over what
  * they publish in either old-devtools or builder mode. The tools surface these
- * strings so the dev can make an informed decision (e.g. add a functional match
- * per redaction) rather than being blocked.
+ * strings so the dev can make an informed decision (for example, add a
+ * functional match per redaction) rather than being blocked.
  */
 /** Build advisory warnings for any request with matchCount < redactionCount.
  *  Returns an empty array when everything is fine. */
@@ -17,7 +17,7 @@ export function matchRedactionWarnings(requests) {
         if (req.matchCount < req.redactionCount) {
             warnings.push(`${req.label}: ${req.matchCount} response match(es) but ` +
                 `${req.redactionCount} response redaction(s). Some verification ` +
-                'clients (e.g. the InApp SDK) may not work correctly when ' +
+                'clients (for example, the InApp SDK) may not work correctly when ' +
                 'responseMatches is shorter than responseRedactions — they pair the ' +
                 'two by index. This is allowed; add a functional match per redaction ' +
                 'if you hit verification issues.');

package/lib/provider/matcher.js

@@ -31,7 +31,7 @@ export function synthesizeMatcher(body, contentType, target, paramName, hash) {
         throw new Error('OPRF hashing requires a target with a known-safe character class '
             + '(digits, slug, or email). '
             + `Got "${target}" which is free-form. Use a tighter target `
-            + '(e.g. just the alphanumeric portion of the value) '
+            + '(for example, just the alphanumeric portion of the value) '
             + 'or call propose_provider without `hash`.');
     }
     const valueClass = inferValueClass(target) ?? '[^"<>\\n]+';
@@ -136,10 +136,10 @@ function lastPathKey(jsonPath) {
  * otherwise). Returns undefined when the value isn't preceded by a JSON key.
  *
  * When `key` is given, anchors the search on occurrences of the KEY (not the
- * value) — so a short/common value elsewhere in the body (e.g. the digit "5"
- * inside `"investment_amount":354.85`) can't be mistaken for this field. Only
- * falls back to a whole-body value search when there's no resolvable key
- * (e.g. `findJsonPath` returned an array-index leaf).
+ * value) — so a short/common value elsewhere in the body (for example, the
+ * digit "5" inside `"investment_amount":354.85`) can't be mistaken for this
+ * field. Only falls back to a whole-body value search when there's no
+ * resolvable key (for example, `findJsonPath` returned an array-index leaf).
  */
 function jsonKeyPrefix(text, target, key) {
     if (key !== undefined) {
@@ -357,9 +357,9 @@ function portableWindow(markup, valueIdx, valueLen) {
 /** Value is element text content. Left anchor: if only punctuation/whitespace
  *  sits between the opening tag and the value, fold the stable opening tag in;
  *  but if WORDS precede the value in the same text node they may be per-user
- *  (e.g. `<li>Full Name ( {{id}} )` — the name), so drop through the last
- *  alphanumeric and keep only the trailing punctuation as the anchor. Right:
- *  include a closing tag, but stop at a sibling. */
+ *  (for example, `<li>Full Name ( {{id}} )` — the name), so drop through the
+ *  last alphanumeric and keep only the trailing punctuation as the anchor.
+ *  Right: include a closing tag, but stop at a sibling. */
 function textWindow(markup, valueIdx, valueEnd, openTagGt) {
     const openTagStart = markup.lastIndexOf('<', openTagGt);
     const openTag = openTagStart >= 0
@@ -495,9 +495,9 @@ function contentMatcher(body, target, paramName, valueClass, hash) {
  * delimiter is kept unless it's whitespace (which the template also drops).
  */
 /** Indices where `cand` occurs in `body` as a WHOLE match of `valueClass` —
- *  i.e. not a substring inside a longer run of the same class (the digit "5"
- *  inside "354.85" is never a whole `\d+` match; "354" and "85" are). Only
- *  meaningful for a structural (non-free-form) class. */
+ * that is, not a substring inside a longer run of the same class (the digit "5"
+ * inside "354.85" is never a whole `\d+` match; "354" and "85" are). Only
+ * meaningful for a structural (non-free-form) class. */
 function wholeTokenIndices(body, cand, valueClass) {
     const indices = [];
     let re;
@@ -645,7 +645,8 @@ function inferValueClass(target) {
     if (/^[0-9]+$/.test(target)) {
         return '\\d+';
     }
-    // Numbers with thousands separators / decimals, e.g. "1,908" or "12,345.6".
+    // Numbers with thousands separators / decimals, for example, "1,908" or
+    // "12,345.6".
     if (/^[0-9][0-9,.]*[0-9]$/.test(target)) {
         return '[0-9,.]+';
     }

package/lib/provider/secrets.d.ts

@@ -18,9 +18,9 @@ export declare function splitSecrets(headers: Record<string, string>): {
  *  still visible to the attestor regardless of secret-marking. */
 export declare function secretUrlCharBudget(writeRedactionMode: ReclaimProvider['writeRedactionMode']): number;
 /** A `paramValues`/context key is secret iff its name contains `SECRET`
- *  (case-insensitive) — e.g. `SECRET_apiKey`, `context.SECRET_apiKey`. Same
- *  naming-convention classifier reclaim-inapp-sdk and reclaim-portal use for
- *  their `witnessParams`/`paramValues` maps (no separate boolean flag). */
+ *  (case-insensitive) — for example, `SECRET_apiKey`, `context.SECRET_apiKey`.
+ *  Same naming-convention classifier reclaim-inapp-sdk and reclaim-portal use
+ *  for their `witnessParams`/`paramValues` maps (no separate boolean flag). */
 export declare function classifyParamName(name: string): boolean;
 /** Split a `paramValues` map (bare `{{name}}` / `{{context.<name>}}` entries)
  *  into public (→ `params.paramValues`, revealed to the attestor) and secret

package/lib/provider/secrets.js

@@ -108,9 +108,9 @@ export function secretUrlCharBudget(writeRedactionMode) {
     return writeRedactionMode === 'zk' ? 12 : 2;
 }
 /** A `paramValues`/context key is secret iff its name contains `SECRET`
- *  (case-insensitive) — e.g. `SECRET_apiKey`, `context.SECRET_apiKey`. Same
- *  naming-convention classifier reclaim-inapp-sdk and reclaim-portal use for
- *  their `witnessParams`/`paramValues` maps (no separate boolean flag). */
+ *  (case-insensitive) — for example, `SECRET_apiKey`, `context.SECRET_apiKey`.
+ *  Same naming-convention classifier reclaim-inapp-sdk and reclaim-portal use
+ *  for their `witnessParams`/`paramValues` maps (no separate boolean flag). */
 export function classifyParamName(name) {
     return name.toUpperCase().includes('SECRET');
 }

package/lib/provider/to-version.d.ts

@@ -27,14 +27,14 @@ export interface DraftRequest {
  *  pagination/optionality flags of `RequestSelectionTemplate`. Reuses the
  *  shared `DraftRequest` shape — no provider `name`/`paramValues` required. */
 export interface AllowedJsRequest extends DraftRequest {
-    /** Allow the template to match many requests (e.g. pagination). Default
-     *  true. */
+    /** Allow the template to match many requests (for example, pagination).
+     *  Default true. */
     multiple?: boolean;
     /** Fail validation if no request matches this template. Default true. */
     required?: boolean;
     /** Names of `${var}` placeholders in this template's `responseMatches`/
      *  `responseRedactions` that get substituted at verify time from the
-     *  submitted proof's own witness params (e.g. an index list a
+     *  submitted proof's own witness params (for example, an index list a
      *  `Reclaim.requestClaim` call attached alongside its `{{var}}`
      *  extractions). Omit (or leave empty) when the template has no such
      *  placeholders — verification then matches it literally as-is. */
@@ -59,12 +59,13 @@ export interface CreateVersionOptions {
      *  is explicitly passed (builder's schema has no `NONE` interceptorType;
      *  omitting `inapp` entirely IS the "no interception" signal, so omitting
      *  this must omit `inapp`, not default it to HAWKEYE). When it IS passed,
-     *  `isDocumentRequestReplayEnabled` is still ALWAYS force-disabled
-     *  regardless of what's passed here — see `providerToCreateVersionRequest`;
-     *  there is no author-facing way to enable it. */
+     *  `isDocumentRequestReplayEnabled` defaults to `false` (disabled) unless
+     *  explicitly overridden here — see `providerToCreateVersionRequest`. Only
+     *  meaningful for `HAWKEYE`/`MSWJS`; inert for `CDP`. */
     interceptorOptions?: {
         interceptorType: 'HAWKEYE' | 'MSWJS' | 'CDP';
         interceptorSettings?: string;
+        isDocumentRequestReplayEnabled?: boolean;
     };
 }
 /**

package/lib/provider/to-version.js

@@ -137,14 +137,14 @@ export function providerToCreateVersionRequest(providers, initialUrl, opts = {})
                 // omitting `interceptorOptions` must omit `inapp` too, or every
                 // standard (non-interception) provider would incorrectly publish
                 // as HAWKEYE. Within that block, `isDocumentRequestReplayEnabled`
-                // is still force-disabled — see `CreateVersionOptions
-                // .interceptorOptions`'s doc comment; there is no way to enable it.
+                // defaults to disabled but is author-overridable — see
+                // `CreateVersionOptions.interceptorOptions`'s doc comment.
                 ...(interceptorOptions
                     ? {
                         inapp: {
                             interceptorOptions: {
                                 interceptorType: interceptorOptions.interceptorType,
-                                isDocumentRequestReplayEnabled: false,
+                                isDocumentRequestReplayEnabled: interceptorOptions.isDocumentRequestReplayEnabled ?? false,
                                 ...(interceptorOptions.interceptorSettings
                                     ? {
                                         interceptorSettings: interceptorOptions.interceptorSettings,

package/lib/tools/registry.d.ts

@@ -30,11 +30,11 @@ export declare function errorAsToolText(err: unknown): string;
 /**
  * Adapt a tool to a host by WIDENING its input schema — add properties, mark
  * some required, optionally override the description — without touching the
- * handler. A host maps whichever shared tools it needs through this (e.g. the
- * MCP adds its `captureId` session handle + the credential-aware `run_proof`
- * contract). Args parse loosely, so the extra fields flow through to the
- * handler (its backend resolver reads them); the base tool stays untouched for
- * hosts that don't need them.
+ * handler. A host maps whichever shared tools it needs through this (for
+ * example, the MCP adds its `captureId` session handle + the credential-aware
+ * `run_proof` contract). Args parse loosely, so the extra fields flow through
+ * to the handler (its backend resolver reads them); the base tool stays
+ * untouched for hosts that don't need them.
  */
 export declare function extendTool(tool: RegisteredTool, extra: {
     description?: string;

package/lib/tools/registry.js

@@ -44,11 +44,11 @@ export function errorAsToolText(err) {
 /**
  * Adapt a tool to a host by WIDENING its input schema — add properties, mark
  * some required, optionally override the description — without touching the
- * handler. A host maps whichever shared tools it needs through this (e.g. the
- * MCP adds its `captureId` session handle + the credential-aware `run_proof`
- * contract). Args parse loosely, so the extra fields flow through to the
- * handler (its backend resolver reads them); the base tool stays untouched for
- * hosts that don't need them.
+ * handler. A host maps whichever shared tools it needs through this (for
+ * example, the MCP adds its `captureId` session handle + the credential-aware
+ * `run_proof` contract). Args parse loosely, so the extra fields flow through
+ * to the handler (its backend resolver reads them); the base tool stays
+ * untouched for hosts that don't need them.
  */
 export function extendTool(tool, extra) {
     const base = tool.definition;

package/package.json

@@ -1,8 +1,8 @@
 {
 	"name": "@reclaimprotocol/agent",
 	"title": "Reclaim Agent",
-	"version": "0.1.23",
-	"description": "Reclaim Protocol's tools for agents — Reclaim Protocol lets your app verify **data points** about its users — a follower count, an account balance, an order history. This package gives your AI coding agent the tools to **find, build, test and fix the _data verification providers_** (the recipes that verify a data point) by inspecting and replaying captured requests, checking sessions, evaluate proofs, publishing updates, and much more.",
+	"version": "0.1.25",
+	"description": "Reclaim Protocol tools for AI coding agents. Reclaim lets your app verify data points about its users, such as a follower count, an account balance, or an order history. This package is the Reclaim MCP server: it gives your agent the tools to find, build, test, and fix data verification providers by capturing and replaying browser requests, drafting provider recipes, running zkTLS proofs, and publishing provider versions.",
 	"type": "module",
 	"main": "./lib/index.js",
 	"types": "./lib/index.d.ts",
@@ -83,7 +83,7 @@
 		"@modelcontextprotocol/sdk": "^1.29.0",
 		"@noble/hashes": "^2.2.0",
 		"@reclaimprotocol/attestor-core": "^5.0.8",
-		"@reclaimprotocol/client": "0.1.23",
+		"@reclaimprotocol/client": "0.1.25",
 		"@reclaimprotocol/tls": "^0.1.3",
 		"chrome-remote-interface": "^0.33.0",
 		"domhandler": "^6.0.0",

package/samples/demo-server/README.md

@@ -6,13 +6,14 @@
    existing app.
 3. Set `PUBLIC_URL` in `.env` to a URL Reclaim's servers can reach — pick
    whichever fits:
-   - **ngrok**: in a separate terminal, run `ngrok http 3000` (install from
-     https://ngrok.com if needed) and copy the
+   - **ngrok**: in a separate terminal, run `ngrok http 3000` (install it
+     from the [ngrok site](https://ngrok.com) if needed) and copy the
      `https://<id>.ngrok-free.app` URL it prints.
-   - **A dev/staging server you can deploy to quickly**: if you already have
-     one reachable from the internet, deploy this there and use its URL
-     instead — no local tunnel needed.
-   This step is REQUIRED — `localhost` is never reachable from Reclaim's
+   - **A development or staging server you can deploy to quickly**: if you
+     already have one reachable from the internet, deploy this there and use
+     its URL instead — no local tunnel needed.
+
+   This step is REQUIRED: `localhost` is never reachable from Reclaim's
    servers.
 4. `npm start`, then open http://localhost:3000/verify (or your deployed
    URL's `/verify`) and click "Start verification".