@reclaimprotocol/agent 0.1.17 → 0.1.20

package/src/provider/draft.ts

@@ -1,4 +1,5 @@
 import { isOprfHashable, OPRF_MAX_BYTES, synthesizeMatcher } from './matcher.ts'
+import { normalizeCandidates } from './normalize.ts'
 import type {
 	CapturedRequest,
 	OprfMode,
@@ -7,7 +8,11 @@ import type {
 	ResponseRedaction,
 	SecretParamRef,
 } from './schema.ts'
-import { splitSecrets } from './secrets.ts'
+import {
+	secretUrlCharBudget,
+	splitSecrets,
+	stripTransportHeaders,
+} from './secrets.ts'
 
 /** OPRF mode for the auto-hash floor — TEE-native (attestor rejects oprf-raw,
  *  isn't set up for gnark oprf). */
@@ -66,51 +71,6 @@ export interface DraftResult {
 	extractions: Extraction[]
 }
 
-/** 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: string): boolean {
-	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.
@@ -124,19 +84,19 @@ function isVolatileHeaderValue(value: string): boolean {
 		|| /^[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: Record<string, string>,
 ): Record<string, string> {
 	const out: Record<string, string> = {}
 	for(const [k, v] of Object.entries(headers)) {
-		if(
-			STRIP_REQUEST_HEADERS.has(k.toLowerCase())
-			|| isPseudoHeader(k)
-			|| isVolatileHeaderValue(v)
-		) {
+		if(isVolatileHeaderValue(v)) {
 			continue
 		}
 
@@ -233,6 +193,79 @@ export function assertPortableMatches(
 	}
 }
 
+/** 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: string,
+	targets: DraftTarget[],
+	effectiveHashes: (OprfMode | undefined)[],
+) {
+	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: string,
+	secrets: Record<string, string>,
+	writeRedactionMode?: ReclaimProvider['writeRedactionMode'],
+) {
+	let redactedChars = 0
+	const overlapping: string[] = []
+	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"`. */
@@ -262,6 +295,7 @@ export function draftProvider(
 	const matches: ResponseMatch[] = []
 	const redactions: ResponseRedaction[] = []
 	const extractions: Extraction[] = []
+	const effectiveHashes: (OprfMode | undefined)[] = []
 	let paramValues: Record<string, string> | undefined
 	const seenParams = new Set<string>()
 	for(const t of targets) {
@@ -279,6 +313,7 @@ export function draftProvider(
 		// 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,
@@ -311,8 +346,15 @@ export function draftProvider(
 
 	// 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/src/provider/index.ts

@@ -17,7 +17,15 @@ export type {
 	ResponseRedaction,
 	SecretParamRef,
 } from './schema.ts'
-export { classifyHeader, splitSecrets } from './secrets.ts'
+export {
+	assertSecretParamValuesFitUrlBudget,
+	classifyHeader,
+	classifyParamName,
+	secretUrlCharBudget,
+	splitSecretParamValues,
+	splitSecrets,
+	stripTransportHeaders,
+} from './secrets.ts'
 // 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.ts'

package/src/provider/injection-doc.ts

@@ -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/src/provider/schema.ts

@@ -15,6 +15,25 @@ export type HttpMethod = HttpParams['method']
  */
 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
@@ -67,8 +86,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/src/provider/secrets.ts

@@ -1,14 +1,99 @@
-const SECRET_EXACT = new Set(['cookie', 'authorization', 'proxy-authorization'])
+import type { ReclaimProvider } from './schema.ts'
 
-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: string): boolean {
-	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: string): boolean {
+	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: Record<string, string>,
+): Record<string, string> {
+	const out: Record<string, string> = {}
+	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: Record<string, string>): {
@@ -27,3 +112,83 @@ export function splitSecrets(headers: Record<string, string>): {
 
 	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: ReclaimProvider['writeRedactionMode'],
+): number {
+	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: string): boolean {
+	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: Record<string, string>): {
+	secrets: Record<string, string>
+	publics: Record<string, string>
+} {
+	const secrets: Record<string, string> = {}
+	const publics: Record<string, string> = {}
+	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: string,
+	geoLocation: string | undefined,
+	secretParamValues: Record<string, string>,
+	writeRedactionMode: ReclaimProvider['writeRedactionMode'],
+) {
+	const haystack = `${url}\n${geoLocation ?? ''}`
+	let redactedChars = 0
+	const used: string[] = []
+	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/src/provider/to-version.ts

@@ -4,10 +4,12 @@ import type {
 	ProviderVersionRef,
 } from '@reclaimprotocol/client/openapi'
 import type {
+	DraftResponseMatch,
 	HttpMethod,
+	OldUrlType,
 	ReclaimProvider,
-	ResponseMatch,
 	ResponseRedaction,
+	WebCredentials,
 } from './schema.ts'
 import { DYNAMIC_GEO, normalizeGeoLocation } from './schema.ts'
 
@@ -24,8 +26,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
@@ -60,6 +69,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
+	}
 }
 
 /**
@@ -86,6 +105,13 @@ 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: ReclaimProvider[],
@@ -95,7 +121,11 @@ export function deriveRequiredContext(
 	} = {},
 ): CreateProviderVersionRequest['requiredContext'] {
 	const parts: string[] = []
-	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 ?? '')
 	}
 
@@ -139,14 +169,14 @@ export function providerToRequestSelection(
 	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 }
@@ -177,7 +207,9 @@ export function providerToCreateVersionRequest(
 	initialUrl: string,
 	opts: CreateVersionOptions = {},
 ): CreateProviderVersionRequest {
-	const { notes, version, jsUserScripts, allowedJsRequests } = opts
+	const {
+		notes, version, jsUserScripts, allowedJsRequests, interceptorOptions,
+	} = opts
 	const requiredContext = deriveRequiredContext(providers, {
 		allowedJsRequests,
 		jsUserScripts,
@@ -206,7 +238,21 @@ export function providerToCreateVersionRequest(
 		// 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/lib/authoring/find.d.ts

@@ -1,3 +0,0 @@
-import { type RegisteredTool } from '../tools/registry.ts';
-import { type ResolveBackend } from './util.ts';
-export declare function findTool(resolveBackend: ResolveBackend): RegisteredTool;

package/lib/authoring/find.js

@@ -1,54 +0,0 @@
-/**
- * `find_requests_containing` — search captured responses for any encoding of a
- * value and rank the requests that return it. Authored once as a plain
- * {@link RegisteredTool}; the MCP and cloud loop each pass their own backend
- * resolver (see tools.ts / mcp/tools/agent/shared.ts). Server-side: response
- * bodies stay here, only metadata + a short snippet leave.
- */
-import { normalizeCandidates } from "../provider/normalize.js";
-import { defineTool } from "../tools/registry.js";
-import { objectSchema, publicRequest } from "./util.js";
-export function findTool(resolveBackend) {
-    return defineTool({
-        name: 'find_requests_containing',
-        description: 'Search captured responses for any encoding of `value` (raw, '
-            + 'URL/JSON/HTML-escaped, …). Returns a ranked candidate list with '
-            + 'the matched variant, score, and a short snippet — used to locate '
-            + 'the request that returns a target. Server-side; bodies stay here.',
-        inputSchema: objectSchema({ value: { type: 'string' }, limit: { type: 'number' } }, ['value']),
-    }, async (args) => {
-        const backend = resolveBackend(args);
-        const variants = normalizeCandidates(String(args.value));
-        const ranked = [];
-        for (const r of backend.capture.requests.values()) {
-            if (!r.responseBody) {
-                continue;
-            }
-            let hit;
-            for (const v of variants) {
-                const idx = r.responseBody.indexOf(v);
-                if (idx >= 0) {
-                    const start = Math.max(0, idx - 40);
-                    const end = Math.min(r.responseBody.length, idx + v.length + 40);
-                    hit = { snippet: r.responseBody.slice(start, end), variant: v };
-                    break;
-                }
-            }
-            if (!hit) {
-                continue;
-            }
-            // Prefer JSON responses + smaller bodies (likely API endpoints).
-            const score = (r.contentType.includes('json') ? 10 : 0)
-                + Math.max(0, 5 - Math.log10(Math.max(r.size, 1)));
-            ranked.push({
-                ...publicRequest(r),
-                matchedVariant: hit.variant,
-                snippet: hit.snippet,
-                score,
-            });
-        }
-        ranked.sort((a, b) => b.score - a.score);
-        const limit = Number(args.limit) || 10;
-        return { candidates: ranked.slice(0, limit) };
-    });
-}

package/lib/authoring/propose.d.ts

@@ -1,3 +0,0 @@
-import { type RegisteredTool } from '../tools/registry.ts';
-import { type ResolveBackend } from './util.ts';
-export declare function proposeTool(resolveBackend: ResolveBackend): RegisteredTool;