@reclaimprotocol/agent 0.1.18 → 0.1.21

package/lib/old/login-cdp.js

@@ -113,15 +113,14 @@ export async function captureFirebaseTokenViaCdp(opts) {
     const { targetId } = await Target.createTarget({ url: loginUrl });
     try {
         const session = await handles.attachToTab(targetId);
-        const { Runtime } = session;
         const deadline = Date.now() + timeoutMs;
         while (Date.now() < deadline) {
-            const r = await Runtime.evaluate({
+            const result = await session.send('Runtime.evaluate', {
                 expression: EXTRACT_TOKEN_JS,
                 awaitPromise: true,
                 returnByValue: true,
             });
-            const value = r.result?.value;
+            const value = runtimeResultValue(result);
             if (typeof value === 'string' && value.length > 0) {
                 return { token: value, closedBrowser: launchedByUs };
             }
@@ -146,3 +145,12 @@ export async function captureFirebaseTokenViaCdp(opts) {
         await handles.close().catch(() => { });
     }
 }
+function runtimeResultValue(value) {
+    if (typeof value !== 'object' || !value || !('result' in value)) {
+        return undefined;
+    }
+    const result = value.result;
+    return typeof result === 'object' && result && 'value' in result
+        ? result.value
+        : undefined;
+}

package/lib/old/tools/build.d.ts

@@ -1,4 +1,5 @@
 import type { RegisteredTool } from '../../mcp/server.ts';
+import type { AttachState } from '../../mcp/tools/agent/attach.ts';
 import type { ReclaimOldClient } from '../client.ts';
 import type { ReclaimSdkClient } from '../sdk-client.ts';
 /**
@@ -10,5 +11,11 @@ import type { ReclaimSdkClient } from '../sdk-client.ts';
  * `sdkClient` is a SEPARATE, unauthenticated client for the public
  * production SDK backend (`api.reclaimprotocol.org`) — a different host from
  * `client`'s old-devtools dashboard backend (`devapi.reclaimprotocol.org`).
+ *
+ * `attachRef` is the SAME attach state `buildAgentTools` was given (see
+ * `mcp/start.ts`) — passing it lets the publish tool remind the caller about
+ * a still-open browser session after a successful publish.
  */
-export declare function buildOldBackendTools(client: ReclaimOldClient, sdkClient: ReclaimSdkClient): RegisteredTool[];
+export declare function buildOldBackendTools(client: ReclaimOldClient, sdkClient: ReclaimSdkClient, attachRef?: {
+    current?: AttachState;
+}): RegisteredTool[];

package/lib/old/tools/build.js

@@ -19,11 +19,15 @@ import { verifySdkSetupTool } from "./verify-sdk-setup.js";
  * `sdkClient` is a SEPARATE, unauthenticated client for the public
  * production SDK backend (`api.reclaimprotocol.org`) — a different host from
  * `client`'s old-devtools dashboard backend (`devapi.reclaimprotocol.org`).
+ *
+ * `attachRef` is the SAME attach state `buildAgentTools` was given (see
+ * `mcp/start.ts`) — passing it lets the publish tool remind the caller about
+ * a still-open browser session after a successful publish.
  */
-export function buildOldBackendTools(client, sdkClient) {
+export function buildOldBackendTools(client, sdkClient, attachRef) {
     return [
         authenticateTool(client),
-        createVersionFromCaptureTool(client),
+        createVersionFromCaptureTool(client, attachRef),
         getMeProvidersTool(client),
         getProviderInfoTool(sdkClient),
         updateProviderMetadataTool(client),

package/lib/old/tools/publish.d.ts

@@ -1,4 +1,5 @@
 import { type RegisteredTool } from '../../mcp/server.ts';
+import type { AttachState } from '../../mcp/tools/agent/attach.ts';
 import type { ReclaimOldClient } from '../client.ts';
 /**
  * Publish a drafted provider to the OLD devtools backend. Keeps the builder
@@ -12,5 +13,13 @@ import type { ReclaimOldClient } from '../client.ts';
  *     highest existing version).
  *
  * Get a `providerId` from `get_me_providers`.
+ *
+ * `attachRef`, when given, is checked after a successful publish: if a
+ * browser is still attached, a `_notes` entry reminds the caller to confirm
+ * with the developer before closing it (see `dispose_browser`) rather than
+ * closing it unprompted — the developer may still want the session for
+ * further edits.
  */
-export declare function createVersionFromCaptureTool(client: ReclaimOldClient): RegisteredTool;
+export declare function createVersionFromCaptureTool(client: ReclaimOldClient, attachRef?: {
+    current?: AttachState;
+}): RegisteredTool;

package/lib/old/tools/publish.js

@@ -46,8 +46,14 @@ function rethrowOwnershipError(err, providerId) {
  *     highest existing version).
  *
  * Get a `providerId` from `get_me_providers`.
+ *
+ * `attachRef`, when given, is checked after a successful publish: if a
+ * browser is still attached, a `_notes` entry reminds the caller to confirm
+ * with the developer before closing it (see `dispose_browser`) rather than
+ * closing it unprompted — the developer may still want the session for
+ * further edits.
  */
-export function createVersionFromCaptureTool(client) {
+export function createVersionFromCaptureTool(client, attachRef) {
     return defineTool({
         name: 'create_provider_version_from_capture',
         description: 'Publish drafted ReclaimProvider(s) to the devtools backend. ' +
@@ -93,7 +99,11 @@ export function createVersionFromCaptureTool(client) {
             'default include), `urlType` (REGEX/CONSTANT/TEMPLATE, default ' +
             'derived from {{placeholders}}), and `isOptional` on each ' +
             'responseMatch (default false). \n\n' +
-            'Captured requests must be GET/POST. OPRF redactions are supported.',
+            'Captured requests must be GET/POST. OPRF redactions are supported. ' +
+            'On success, if a browser is still attached, the response\'s ' +
+            '`_notes` reminds you to confirm with the developer before ' +
+            'calling `dispose_browser` — never close it unprompted, they ' +
+            'may want it for further edits.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -230,7 +240,29 @@ export function createVersionFromCaptureTool(client) {
                         'the whole payload), template just that part with ' +
                         '`{{paramName}}` and keep the rest as fixed literal text; see ' +
                         'the "bodySniff" section of the customInjection field\'s guide ' +
-                        'for the exact mechanics and a worked example.',
+                        'for the exact mechanics and a worked example. ' +
+                        '⚠️ BEFORE populating this to gate ' +
+                        '`verifyProof(proof, { providerId })`: this whole entry (url, ' +
+                        'method, body, responseMatches, responseRedactions) feeds a ' +
+                        'client-side hash-equality check, and `url` is hashed VERBATIM ' +
+                        '— no regex/template resolution, even with `urlType: REGEX` or ' +
+                        '`TEMPLATE`. If the real captured URL contains ANY per-session ' +
+                        'part (a tracking nonce, CSRF token, cache-busting timestamp), ' +
+                        'no declared spec can EVER hash-match a real proof, no matter ' +
+                        'how correct the rest of this entry is — populating' +
+                        'it for such ' +
+                        'a provider makes verifyProof reject every real proof,' +
+                        'which is ' +
+                        'worse than leaving this field empty. Diff the same endpoint\'s' +
+                        ' captured URL across two separate sessions before wiring this ' +
+                        'up. If provider-hash validation keeps causing problems ' +
+                        '(unstable url, or any other persistent mismatch), the ' +
+                        'fallback on the verifying side is `verifyProof(proof, { ' +
+                        'dangerouslyDisableContentValidation: true })` — trusts only ' +
+                        'the attestor\'s signature, skips the hash-equality check ' +
+                        'entirely; see the "Provider-hash validation" section of the ' +
+                        'customInjection field\'s guide for the full mechanics and ' +
+                        'when to reach for it.',
                     items: {
                         type: 'object',
                         properties: {
@@ -405,6 +437,20 @@ export function createVersionFromCaptureTool(client) {
         // 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)));
+        // A browser session left attached after a successful publish is
+        // easy to forget about — surface it so the caller asks the
+        // developer before closing it (a builder-mode session is
+        // quota-accounted and otherwise just sits until its TTL expires).
+        const attached = attachRef?.current;
+        if (attached) {
+            notes.push(`A "${attached.mode}" browser session is still attached` +
+                (attached.browserSessionId
+                    ? ` (browserSessionId: ${attached.browserSessionId})`
+                    : '') +
+                '. Ask the developer whether they want to keep it open for ' +
+                'further edits — only call dispose_browser once they confirm ' +
+                'they\'re done with it.');
+        }
         const withNotes = (result) => {
             if (notes.length && result && typeof result === 'object') {
                 return { ...result, _notes: notes };

package/lib/provider/draft.d.ts

@@ -37,4 +37,24 @@ export interface DraftResult {
  *  `{{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
+ *  the value in cleartext — but URL `paramValues` are always signed into the
+ *  attestor's context in the clear (attestor-core: "those in URL... will be
+ *  put into context and signed"), so a value that's both hashed in the
+ *  response AND present in the URL is visible there anyway. This isn't a
+ *  privacy nuance the author can weigh (unlike {@link assertPortableMatches}
+ *  bare-literal cases) — it doesn't verify. Throwing here, at draft time,
+ *  surfaces that immediately instead of a confusing later proof failure. */
+export declare function assertNoOprfUrlConflict(url: string, targets: DraftTarget[], effectiveHashes: (OprfMode | undefined)[]): void;
+/** Reject a draft whose URL bakes in a secret header/cookie's value beyond
+ *  what write-redaction can actually hide there. A secret value used in the
+ *  URL is NOT an automatic leak — write-redaction (`key-update`/`zk`) can
+ *  redact it from the attestor's view up to {@link secretUrlCharBudget}
+ *  characters, summed across every secret value that appears in that URL
+ *  (not per-value). Below the budget the header buys real privacy; at or
+ *  over it, the value is effectively visible regardless of hiding the
+ *  header (same class of problem as {@link assertNoOprfUrlConflict} for
+ *  OPRF-hashed targets, which has no such budget at all). */
+export declare function assertNoSecretUrlConflict(url: string, secrets: Record<string, string>, writeRedactionMode?: ReclaimProvider['writeRedactionMode']): void;
 export declare function draftProvider(req: CapturedRequest, targets: DraftTarget[], name: string, hash?: OprfMode): DraftResult;

package/lib/provider/draft.js

@@ -1,5 +1,6 @@
 import { isOprfHashable, OPRF_MAX_BYTES, synthesizeMatcher } from "./matcher.js";
-import { splitSecrets } from "./secrets.js";
+import { normalizeCandidates } from "./normalize.js";
+import { secretUrlCharBudget, splitSecrets, stripTransportHeaders, } from "./secrets.js";
 /** OPRF mode for the auto-hash floor — TEE-native (attestor rejects oprf-raw,
  *  isn't set up for gnark oprf). */
 const DEFAULT_SENSITIVE_HASH = 'oprf-mpc';
@@ -29,49 +30,6 @@ export function defaultSensitiveHash(value) {
         && Buffer.byteLength(value, 'utf8') <= OPRF_MAX_BYTES;
     return hashable ? DEFAULT_SENSITIVE_HASH : undefined;
 }
-/** Request headers that must NOT survive into the provider params. 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 — the attestor already
- *    forces `identity` (uncompressed, so its byte-matching works).
- *  - Host / framing headers the TRANSPORT owns (`host`, `content-length`,
- *    `transfer-encoding`) and HTTP/2 pseudo-headers (`:authority`/`:method`/…,
- *    which CDP surfaces on h2 captures). The attestor derives `Host` from the
- *    URL and sets its own; a baked `Host` produces a DUPLICATE
- *    (`found: h,h`) that fails the receipt check / 400s the origin. A stale
- *    `content-length` breaks a re-serialized body. Pseudo-headers aren't valid
- *    real headers at all. */
-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. Not caught by splitSecrets (no `-token`
-    // suffix), so without this they baked in as PUBLIC headers and went stale at
-    // verify time — the attestor replayed one user's captured CSRF for everyone,
-    // which the origin rejects. A CSRF token is never portable; drop it.
-    'csrf',
-    'x-csrf',
-    'xsrf',
-    'x-xsrf',
-    'x-csrf-token',
-    'xsrf-token',
-]);
-/** True for an HTTP/2 pseudo-header (`:authority`, `:method`, `:path`,
- *  `:scheme`) — never a valid request header the attestor can replay. */
-function isPseudoHeader(name) {
-    return name.startsWith(':');
-}
 /** A header VALUE that is a per-session/request token — a UUID or a long opaque
  *  hex/base64 blob. Such a value is captured-user-specific: baked into the
  *  provider it goes stale and the origin rejects the replay for everyone else.
@@ -84,15 +42,17 @@ function isVolatileHeaderValue(value) {
         || /^[0-9a-f]{16,}$/i.test(v)
         || /^[A-Za-z0-9_-]{32,}$/.test(v);
 }
-/** Drop the headers the attestor manages or that would 304 at proof time
- *  (see {@link STRIP_REQUEST_HEADERS}); keep every other captured header so the
- *  attestor's replay looks like the browser's request. */
+/** Drop a PUBLIC header whose value is per-session/request volatile (see
+ *  {@link isVolatileHeaderValue}) — public headers get frozen into the
+ *  persisted provider, so a volatile one goes stale and fails every other
+ *  user's replay. Secret headers are re-captured fresh per verification
+ *  (never persisted), so this doesn't apply to them; keep every other
+ *  captured public header so the attestor's replay looks like the browser's
+ *  request. */
 function sanitizeRequestHeaders(headers) {
     const out = {};
     for (const [k, v] of Object.entries(headers)) {
-        if (STRIP_REQUEST_HEADERS.has(k.toLowerCase())
-            || isPseudoHeader(k)
-            || isVolatileHeaderValue(v)) {
+        if (isVolatileHeaderValue(v)) {
             continue;
         }
         out[k] = v;
@@ -167,6 +127,63 @@ export function assertPortableMatches(matches, redactions, targets) {
         }
     }
 }
+/** 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
+ *  the value in cleartext — but URL `paramValues` are always signed into the
+ *  attestor's context in the clear (attestor-core: "those in URL... will be
+ *  put into context and signed"), so a value that's both hashed in the
+ *  response AND present in the URL is visible there anyway. This isn't a
+ *  privacy nuance the author can weigh (unlike {@link assertPortableMatches}
+ *  bare-literal cases) — it doesn't verify. Throwing here, at draft time,
+ *  surfaces that immediately instead of a confusing later proof failure. */
+export function assertNoOprfUrlConflict(url, targets, effectiveHashes) {
+    for (const [i, t] of targets.entries()) {
+        const hash = effectiveHashes[i];
+        if (!hash) {
+            continue;
+        }
+        const inUrl = [t.value, ...normalizeCandidates(t.value)]
+            .some((v) => url.includes(v));
+        if (inUrl) {
+            throw new Error(`target "${t.name}" is OPRF-hashed (${hash}) but its value also `
+                + `appears in the request URL ("${url}") — the attestor signs URL `
+                + 'param values into context in the clear, so it would see this '
+                + 'value regardless of the hash. Drop `hash` for this target, or '
+                + "capture a request whose URL doesn't carry the value.");
+        }
+    }
+}
+/** Reject a draft whose URL bakes in a secret header/cookie's value beyond
+ *  what write-redaction can actually hide there. A secret value used in the
+ *  URL is NOT an automatic leak — write-redaction (`key-update`/`zk`) can
+ *  redact it from the attestor's view up to {@link secretUrlCharBudget}
+ *  characters, summed across every secret value that appears in that URL
+ *  (not per-value). Below the budget the header buys real privacy; at or
+ *  over it, the value is effectively visible regardless of hiding the
+ *  header (same class of problem as {@link assertNoOprfUrlConflict} for
+ *  OPRF-hashed targets, which has no such budget at all). */
+export function assertNoSecretUrlConflict(url, secrets, writeRedactionMode) {
+    let redactedChars = 0;
+    const overlapping = [];
+    for (const [name, value] of Object.entries(secrets)) {
+        const inUrl = [value, ...normalizeCandidates(value)]
+            .some((v) => url.includes(v));
+        if (inUrl) {
+            redactedChars += value.length;
+            overlapping.push(name);
+        }
+    }
+    const budget = secretUrlCharBudget(writeRedactionMode);
+    if (redactedChars > budget) {
+        throw new Error(`secret header(s) ${overlapping.map((n) => `"${n}"`).join(', ')} `
+            + `also appear in the request URL ("${url}"), totaling `
+            + `${redactedChars} character(s) to hide — over the ${budget}-`
+            + `character budget write-redaction (${writeRedactionMode
+                ?? 'key-update'}) can actually hide there. Drop the header, `
+            + "shorten/remove the value's overlap with the URL, or switch to "
+            + "'zk' if that raises the budget enough.");
+    }
+}
 /** Derive a `paramValues` key (and capture-group name) from the provider
  *  name's last alphanumeric token. `"GitHub Username"` → `"username"`,
  *  `"x-followers"` → `"followers"`. */
@@ -188,6 +205,7 @@ export function draftProvider(req, targets, name, hash) {
     const matches = [];
     const redactions = [];
     const extractions = [];
+    const effectiveHashes = [];
     let paramValues;
     const seenParams = new Set();
     for (const t of targets) {
@@ -202,6 +220,7 @@ export function draftProvider(req, targets, name, hash) {
         // The model makes the contextual calls (which named fields are sensitive)
         // via an explicit per-target hash; this floor only guarantees the obvious.
         const effectiveHash = t.hash ?? hash ?? defaultSensitiveHash(t.value);
+        effectiveHashes.push(effectiveHash);
         const synthesis = synthesizeMatcher(req.responseBody, req.contentType, t.value, paramName, effectiveHash);
         if (!synthesis) {
             throw new Error(`target value "${t.value}" not found in`
@@ -222,7 +241,12 @@ export function draftProvider(req, targets, name, hash) {
     }
     // Portability gate: never ship a draft that bakes a per-user value literally.
     assertPortableMatches(matches, redactions, targets);
-    const { secrets, publics } = splitSecrets(req.requestHeaders);
+    // OPRF gate: never ship a draft that hashes a value the URL also reveals.
+    assertNoOprfUrlConflict(req.url, targets, effectiveHashes);
+    const { secrets, publics } = splitSecrets(stripTransportHeaders(req.requestHeaders));
+    // Secret-header gate: never ship a draft whose URL reveals the same value a
+    // stripped secret header carries — hiding the header buys nothing then.
+    assertNoSecretUrlConflict(req.url, secrets);
     // Sanitize the public headers before they enter the provider. Two problems
     // a captured browser request carries: (1) `accept-encoding: gzip, …`, which
     // makes the attestor match against compressed bytes (it does no transparent

package/lib/provider/index.d.ts

@@ -3,7 +3,7 @@ export type { DraftResult } from './draft.ts';
 export { detectConcerns } from './constraints.ts';
 export { extractGraphqlOp, looksLikeGraphqlEndpoint } from './graphql.ts';
 export type { CapturedRequest, HttpMethod, OprfMode, ReclaimProvider, RequestConcern, ResponseMatch, ResponseRedaction, SecretParamRef, } from './schema.ts';
-export { classifyHeader, splitSecrets } from './secrets.ts';
+export { assertSecretParamValuesFitUrlBudget, classifyHeader, classifyParamName, secretUrlCharBudget, splitSecretParamValues, splitSecrets, stripTransportHeaders, } from './secrets.ts';
 export { providerToRequestSelection } from './to-version.ts';
 export { hashProviderParams, providers } from '@reclaimprotocol/attestor-core';
 export type { ProviderParams } from '@reclaimprotocol/attestor-core';

package/lib/provider/index.js

@@ -6,7 +6,7 @@
 export { draftProvider } from "./draft.js";
 export { detectConcerns } from "./constraints.js";
 export { extractGraphqlOp, looksLikeGraphqlEndpoint } from "./graphql.js";
-export { classifyHeader, splitSecrets } from "./secrets.js";
+export { assertSecretParamValuesFitUrlBudget, classifyHeader, classifyParamName, secretUrlCharBudget, splitSecretParamValues, splitSecrets, stripTransportHeaders, } from "./secrets.js";
 // Recipe → version `requests[]` (a `RequestSelection`) — the same mapping the
 // MCP publish uses, so the cloud authoring publish stays byte-identical.
 export { providerToRequestSelection } from "./to-version.js";

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

@@ -72,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) {