@reclaimprotocol/agent 0.1.17 → 0.1.20

package/lib/provider/injection-doc.js

@@ -14,9 +14,10 @@
  * 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 — neither publish tool exposes
- * these as inputs (both only build the standard replay flow), so this is
- * read-the-field-and-recognize-it documentation, not authoring guidance.
+ * 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.
  */
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';

package/lib/provider/schema.d.ts

@@ -11,6 +11,24 @@ export type HttpMethod = HttpParams['method'];
  * jsonPath/xPath belong on the redaction, not here.
  */
 export type ResponseMatch = HttpParams['responseMatches'][number];
+/**
+ * A response match as drafted for PUBLISH: the attestor's match plus
+ * `isOptional` — a backend-side matcher flag (both the old devtools backend
+ * and the builder store it; the attestor's own params have no such field, so
+ * `propose_provider` drafts never set it — only an explicit publish input
+ * does). Default false on both backends.
+ */
+export type DraftResponseMatch = ResponseMatch & {
+    isOptional?: boolean;
+};
+/** How the verification client supplies cookies/auth when replaying a
+ *  request. Both backends accept the same enum (old devtools on
+ *  `requestData`, builder on `RequestSelection`); default `include`. */
+export type WebCredentials = 'omit' | 'same-origin' | 'include';
+/** Old-devtools `urlType` for a requestData entry. The builder backend has
+ *  no such field (templating is implicit in the URL's `{{param}}`
+ *  placeholders), so the builder translator ignores it. */
+export type OldUrlType = 'REGEX' | 'CONSTANT' | 'TEMPLATE';
 /**
  * Selector telling the prover which portion of the response to reveal:
  * `xPath`/`jsonPath` narrows the slice, `regex` (with named groups) matches
@@ -59,8 +77,15 @@ export interface ReclaimProvider {
     method: HttpMethod;
     headers?: Record<string, string>;
     body?: string;
-    responseMatches: ResponseMatch[];
+    responseMatches: DraftResponseMatch[];
     responseRedactions?: ResponseRedaction[];
+    /** How the verification client supplies cookies/auth on replay. Both
+     *  backends default to `include` when unset. */
+    credentials?: WebCredentials;
+    /** Old-devtools-only url type override (`REGEX`/`CONSTANT`/`TEMPLATE`).
+     *  Auto-derived from `{{param}}` placeholders when unset; ignored by the
+     *  builder backend. */
+    urlType?: OldUrlType;
     /** Public param refs (templated into URL/body), populated by draft layer. */
     paramValues?: Record<string, string>;
     /** Redaction mode for the transcript (attestor default: 'key-update'). */

package/lib/provider/secrets.d.ts

@@ -1,5 +1,42 @@
+import type { ReclaimProvider } from './schema.ts';
 export declare function classifyHeader(name: string): boolean;
+/** Drop {@link STRIP_REQUEST_HEADERS} and HTTP/2 pseudo-headers. Call this on
+ *  the RAW captured headers before {@link splitSecrets} — both the draft-time
+ *  authoring flow and the live per-user verification capture need it, so
+ *  neither ends up sending a duplicate `Host` or an invalid `:authority` to
+ *  the attestor via either the public or the secret channel. */
+export declare function stripTransportHeaders(headers: Record<string, string>): Record<string, string>;
 export declare function splitSecrets(headers: Record<string, string>): {
     secrets: Record<string, string>;
     publics: Record<string, string>;
 };
+/** Total characters write-redaction can hide from the attestor, summed
+ *  ACROSS EVERY secret-classified value used in the URL — not a per-value
+ *  cap. Default mode (`'key-update'`, also what an unset field resolves to)
+ *  caps at 2; `'zk'` at 12. At or under the budget the overlap is genuinely
+ *  hidden; over it, the value (or the combination of values) is effectively
+ *  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). */
+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
+ *  (→ `secretParams.paramValues`) by {@link classifyParamName}. A secret
+ *  value used in the URL is still hidden — up to {@link secretUrlCharBudget}
+ *  characters, summed across every such value in that URL. */
+export declare function splitSecretParamValues(paramValues: Record<string, string>): {
+    secrets: Record<string, string>;
+    publics: Record<string, string>;
+};
+/** Reject a proof attempt whose URL/geoLocation templates SECRET-named
+ *  context param(s) whose ACTUAL values (now known — the consumer supplied
+ *  them at session-create) exceed the write-redaction budget once summed.
+ *  Structural placement (which params end up in the URL) is knowable at
+ *  publish time and isn't rejected there — only the real values decide
+ *  whether it fits, and those only exist once a verification session is
+ *  underway. Checks the placeholder TOKEN (`{{<key>}}`), not a value search —
+ *  the URL/geoLocation explicitly reference the param by name. */
+export declare function assertSecretParamValuesFitUrlBudget(url: string, geoLocation: string | undefined, secretParamValues: Record<string, string>, writeRedactionMode: ReclaimProvider['writeRedactionMode']): void;

package/lib/provider/secrets.js

@@ -1,11 +1,89 @@
-const SECRET_EXACT = new Set(['cookie', 'authorization', 'proxy-authorization']);
-const SECRET_SUFFIXES = ['-token', '-key', '-secret', '-auth'];
+/** Headers safe to reveal to the attestor unredacted — everything else
+ *  (`Cookie`, `Authorization`, any custom header, even ones that look inert
+ *  like `Content-Type`) is secret by default. Allowlist, not a denylist:
+ *  same exact list `reclaim-inapp-sdk` (`_PUBLIC_HEADERS_ALLOW_LIST`,
+ *  `request.dart`) and `reclaim-portal` (`DEFAULT_PUBLIC_HEADERS`,
+ *  `claim-builder.ts`) use for their own `witnessParams`/header split. */
+const PUBLIC_HEADERS = new Set([
+    'user-agent',
+    'accept',
+    'accept-language',
+    'accept-encoding',
+    'sec-fetch-mode',
+    'sec-fetch-site',
+    'sec-fetch-user',
+    'origin',
+    'x-requested-with',
+    'sec-ch-ua',
+    'sec-ch-ua-mobile',
+]);
 export function classifyHeader(name) {
-    const lower = name.toLowerCase();
-    if (SECRET_EXACT.has(lower)) {
-        return true;
+    return !PUBLIC_HEADERS.has(name.toLowerCase());
+}
+/** Headers that must NOT survive into EITHER the public or secret side —
+ *  structural/transport, never a credential. Three kinds:
+ *  - Conditional headers (`if-none-match`/`if-modified-since`/…): a captured
+ *    cached ETag/date makes the origin answer 304/412 when the attestor
+ *    re-issues, and the attestor treats non-2xx as failure. We always want
+ *    the full fresh response.
+ *  - Transfer headers the ATTESTOR sets itself (`connection: close`,
+ *    `accept-encoding: identity`). Passing our own duplicates/collides with
+ *    the request the attestor builds, so leave them out.
+ *  - Host / framing headers the TRANSPORT owns (`host`, `content-length`,
+ *    `transfer-encoding`). The attestor derives `Host` from the URL and sets
+ *    its own; a baked `Host` produces a DUPLICATE that fails the receipt
+ *    check / 400s the origin. A stale `content-length` breaks a
+ *    re-serialized body.
+ *  Must be stripped BEFORE `splitSecrets`, not after: under the allowlist
+ *  classifier these all fall into `secrets` (none are on `PUBLIC_HEADERS`),
+ *  and a header like `Host` — whose value trivially mirrors the URL's
+ *  hostname, by definition — would trip a URL-conflict check on a
+ *  structural, not a privacy, coincidence. */
+const STRIP_REQUEST_HEADERS = new Set([
+    'if-none-match',
+    'if-modified-since',
+    'if-match',
+    'if-unmodified-since',
+    'if-range',
+    'connection',
+    'accept-encoding',
+    'host',
+    'content-length',
+    'transfer-encoding',
+    // Per-session anti-CSRF tokens: never portable (baking one in replays a
+    // single captured user's token for everyone, which the origin rejects).
+    // The allowlist classifier already routes these to `secrets` — a proof
+    // attempt sends the CURRENT user's own captured value, which is correct —
+    // but stripping them here means they never even take that path, and
+    // definitely never survive into a persisted, public recipe.
+    'csrf',
+    'x-csrf',
+    'xsrf',
+    'x-xsrf',
+    'x-csrf-token',
+    'xsrf-token',
+]);
+/** True for an HTTP/2 pseudo-header (`:authority`, `:method`, `:path`,
+ *  `:scheme`, which CDP surfaces on h2 captures) — never a valid request
+ *  header the attestor can replay. Same BEFORE-the-split reasoning as
+ *  {@link STRIP_REQUEST_HEADERS}. */
+function isPseudoHeader(name) {
+    return name.startsWith(':');
+}
+/** Drop {@link STRIP_REQUEST_HEADERS} and HTTP/2 pseudo-headers. Call this on
+ *  the RAW captured headers before {@link splitSecrets} — both the draft-time
+ *  authoring flow and the live per-user verification capture need it, so
+ *  neither ends up sending a duplicate `Host` or an invalid `:authority` to
+ *  the attestor via either the public or the secret channel. */
+export function stripTransportHeaders(headers) {
+    const out = {};
+    for (const [k, v] of Object.entries(headers)) {
+        if (STRIP_REQUEST_HEADERS.has(k.toLowerCase()) || isPseudoHeader(k)) {
+            continue;
+        }
+        out[k] = v;
     }
-    return SECRET_SUFFIXES.some((s) => lower.endsWith(s));
+    return out;
 }
 export function splitSecrets(headers) {
     const secrets = {};
@@ -20,3 +98,66 @@ export function splitSecrets(headers) {
     }
     return { secrets, publics };
 }
+/** Total characters write-redaction can hide from the attestor, summed
+ *  ACROSS EVERY secret-classified value used in the URL — not a per-value
+ *  cap. Default mode (`'key-update'`, also what an unset field resolves to)
+ *  caps at 2; `'zk'` at 12. At or under the budget the overlap is genuinely
+ *  hidden; over it, the value (or the combination of values) is effectively
+ *  still visible to the attestor regardless of secret-marking. */
+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). */
+export function classifyParamName(name) {
+    return name.toUpperCase().includes('SECRET');
+}
+/** Split a `paramValues` map (bare `{{name}}` / `{{context.<name>}}` entries)
+ *  into public (→ `params.paramValues`, revealed to the attestor) and secret
+ *  (→ `secretParams.paramValues`) by {@link classifyParamName}. A secret
+ *  value used in the URL is still hidden — up to {@link secretUrlCharBudget}
+ *  characters, summed across every such value in that URL. */
+export function splitSecretParamValues(paramValues) {
+    const secrets = {};
+    const publics = {};
+    for (const [k, v] of Object.entries(paramValues)) {
+        if (classifyParamName(k)) {
+            secrets[k] = v;
+        }
+        else {
+            publics[k] = v;
+        }
+    }
+    return { secrets, publics };
+}
+/** Reject a proof attempt whose URL/geoLocation templates SECRET-named
+ *  context param(s) whose ACTUAL values (now known — the consumer supplied
+ *  them at session-create) exceed the write-redaction budget once summed.
+ *  Structural placement (which params end up in the URL) is knowable at
+ *  publish time and isn't rejected there — only the real values decide
+ *  whether it fits, and those only exist once a verification session is
+ *  underway. Checks the placeholder TOKEN (`{{<key>}}`), not a value search —
+ *  the URL/geoLocation explicitly reference the param by name. */
+export function assertSecretParamValuesFitUrlBudget(url, geoLocation, secretParamValues, writeRedactionMode) {
+    const haystack = `${url}\n${geoLocation ?? ''}`;
+    let redactedChars = 0;
+    const used = [];
+    for (const [key, value] of Object.entries(secretParamValues)) {
+        if (haystack.includes(`{{${key}}}`)) {
+            redactedChars += value.length;
+            used.push(key);
+        }
+    }
+    const budget = secretUrlCharBudget(writeRedactionMode);
+    if (redactedChars > budget) {
+        throw new Error(`secret context param(s) ${used.map((k) => `"${k}"`).join(', ')} `
+            + `are templated into the URL/geoLocation ("${url}") with a `
+            + `combined value length of ${redactedChars} character(s) — over `
+            + `the ${budget}-character budget write-redaction `
+            + `(${writeRedactionMode ?? 'key-update'}) can actually hide there. `
+            + "Ask the consumer for a shorter value, switch to 'zk' if that "
+            + 'raises the budget enough, or move this param to the body.');
+    }
+}

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

@@ -1,6 +1,6 @@
 import type { ReclaimClient } from '@reclaimprotocol/client';
 import type { CreateProviderVersionRequest, ProviderVersionRef } from '@reclaimprotocol/client/openapi';
-import type { HttpMethod, ReclaimProvider, ResponseMatch, ResponseRedaction } from './schema.ts';
+import type { DraftResponseMatch, HttpMethod, OldUrlType, ReclaimProvider, ResponseRedaction, WebCredentials } from './schema.ts';
 /** One entry of the version's `requests[]` (a `RequestSelection`), derived
  *  from the openapi type so it can't drift from what the server accepts. */
 type RequestSelection = CreateProviderVersionRequest['requests'][number];
@@ -13,8 +13,15 @@ export interface DraftRequest {
     body?: string;
     writeRedactionMode?: ReclaimProvider['writeRedactionMode'];
     additionalClientOptions?: ReclaimProvider['additionalClientOptions'];
-    responseMatches?: ResponseMatch[];
+    responseMatches?: DraftResponseMatch[];
     responseRedactions?: ResponseRedaction[];
+    /** How the verification client supplies cookies/auth on replay. Default
+     *  `include` (both backends). */
+    credentials?: WebCredentials;
+    /** Old-devtools `urlType` override. Ignored by THIS translator (the
+     *  builder backend has no urlType) — read only by the old-devtools
+     *  translator (`old/to-register.ts`). */
+    urlType?: OldUrlType;
 }
 /** A request the page's injection script is allowed to fire, plus the
  *  pagination/optionality flags of `RequestSelectionTemplate`. Reuses the
@@ -47,6 +54,16 @@ export interface CreateVersionOptions {
     jsUserScripts?: string;
     /** Requests the injection script may fire, as `RequestSelectionTemplate`s. */
     allowedJsRequests?: AllowedJsRequest[];
+    /** In-app interception options, mapped verbatim to
+     *  `webSettings.clientOptions.inapp.interceptorOptions`. `interceptorType`
+     *  is required by the backend whenever the object is present.
+     *  `isDocumentRequestReplayEnabled` is the INVERSE of old-devtools'
+     *  `disableRequestReplay` (default false). */
+    interceptorOptions?: {
+        interceptorType: 'HAWKEYE' | 'MSWJS' | 'CDP';
+        isDocumentRequestReplayEnabled?: boolean;
+        interceptorSettings?: string;
+    };
 }
 /**
  * Derive the version's `requiredContext` JSON Schema from the
@@ -55,6 +72,13 @@ export interface CreateVersionOptions {
  * recipe can never reference a context value the Builder doesn't require.
  * Returns undefined when nothing references context (the field is optional).
  * Authors can refine types/descriptions in the version editor.
+ *
+ * A SECRET-named context param (see `classifyParamName`) is NOT rejected here
+ * even when it's templated into the URL/geoLocation — write-redaction can
+ * still hide it there, up to `secretUrlCharBudget` characters (summed across
+ * every such value in that URL). Whether it actually fits is only knowable
+ * once a real value exists, so that check runs at verification time
+ * (`verify/run.ts`), against the consumer's actual supplied value — not here.
  */
 export declare function deriveRequiredContext(providers: ReclaimProvider[], injection?: {
     allowedJsRequests?: AllowedJsRequest[];

package/lib/provider/to-version.js

@@ -22,10 +22,20 @@ const CONTEXT_PARAM_RE = /\{\{context\.([A-Za-z_][A-Za-z0-9_]*)\}\}/g;
  * recipe can never reference a context value the Builder doesn't require.
  * Returns undefined when nothing references context (the field is optional).
  * Authors can refine types/descriptions in the version editor.
+ *
+ * A SECRET-named context param (see `classifyParamName`) is NOT rejected here
+ * even when it's templated into the URL/geoLocation — write-redaction can
+ * still hide it there, up to `secretUrlCharBudget` characters (summed across
+ * every such value in that URL). Whether it actually fits is only knowable
+ * once a real value exists, so that check runs at verification time
+ * (`verify/run.ts`), against the consumer's actual supplied value — not here.
  */
 export function deriveRequiredContext(providers, injection = {}) {
     const parts = [];
-    for (const p of [...providers, ...(injection.allowedJsRequests ?? [])]) {
+    for (const p of providers) {
+        parts.push(p.url, p.body ?? '');
+    }
+    for (const p of injection.allowedJsRequests ?? []) {
         parts.push(p.url, p.body ?? '');
     }
     if (injection.jsUserScripts) {
@@ -61,13 +71,13 @@ export function providerToRequestSelection(provider) {
     const responseMatches = (provider.responseMatches ?? []).map((match) => ({
         type: match.type,
         value: match.value,
-        isOptional: false,
+        isOptional: match.isOptional ?? false,
     }));
     const responseRedactions = provider.responseRedactions ?? [];
     return {
         url: provider.url,
         method: provider.method,
-        credentials: 'include',
+        credentials: provider.credentials ?? 'include',
         ...(provider.body ? { requestBodyTemplate: provider.body } : {}),
         ...(provider.writeRedactionMode
             ? { writeRedactionMode: provider.writeRedactionMode }
@@ -91,7 +101,7 @@ function pickGeoLocation(providers) {
     return DYNAMIC_GEO;
 }
 export function providerToCreateVersionRequest(providers, initialUrl, opts = {}) {
-    const { notes, version, jsUserScripts, allowedJsRequests } = opts;
+    const { notes, version, jsUserScripts, allowedJsRequests, interceptorOptions, } = opts;
     const requiredContext = deriveRequiredContext(providers, {
         allowedJsRequests,
         jsUserScripts,
@@ -118,7 +128,21 @@ export function providerToCreateVersionRequest(providers, initialUrl, opts = {})
         // apply schema defaults to request bodies.
         webSettings: {
             geoLocation: pickGeoLocation(providers),
-            clientOptions: { portal: { useProxy: true } },
+            clientOptions: {
+                portal: { useProxy: true },
+                ...(interceptorOptions
+                    ? {
+                        inapp: {
+                            interceptorOptions: {
+                                // openapi `default: false` — the generated type
+                                // requires the key even when the author omits it.
+                                isDocumentRequestReplayEnabled: false,
+                                ...interceptorOptions,
+                            },
+                        },
+                    }
+                    : {}),
+            },
             // Only set when non-empty; an empty string would store a no-op script.
             ...(script ? { jsUserScripts: script } : {}),
         },

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@reclaimprotocol/agent",
 	"title": "Reclaim Agent",
-	"version": "0.1.17",
+	"version": "0.1.20",
 	"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.",
 	"type": "module",
 	"main": "./lib/index.js",
@@ -83,7 +83,7 @@
 		"@modelcontextprotocol/sdk": "^1.29.0",
 		"@noble/hashes": "^2.2.0",
 		"@reclaimprotocol/attestor-core": "^5.0.8",
-		"@reclaimprotocol/client": "0.1.17",
+		"@reclaimprotocol/client": "0.1.20",
 		"@reclaimprotocol/tls": "^0.1.3",
 		"chrome-remote-interface": "^0.33.0",
 		"domhandler": "^6.0.0",