@reclaimprotocol/agent 0.1.18 → 0.1.21

package/src/mcp/tools/authenticate/authenticate.ts

@@ -9,13 +9,23 @@ import { writeSession } from './session-cache.ts'
 const SCOPE = 'openid profile email'
 const CALLBACK_TIMEOUT_MS = 5 * 60 * 1000
 
-export function authenticateTool(client: ReclaimClient): RegisteredTool {
+export function authenticateTool(
+	client: ReclaimClient,
+	name: 'reclaim_authenticate' | 'authenticate_builder' =
+		'reclaim_authenticate',
+): RegisteredTool {
 	return defineTool<Record<string, never>>(
 		{
-			name: 'reclaim_authenticate',
+			name,
 			description:
-				'Authorize the CLI / MCP to make authenticated API calls. Opens the ' +
-				'browser to the builder sign-in page (standard OAuth 2.0 ' +
+				(name === 'authenticate_builder'
+					? 'Authenticate specifically with Builder. Available regardless '
+						+ 'of '
+						+ 'the selected publishing backend. '
+					: '')
+				+ 'Authorize the CLI / MCP to make authenticated API calls. Opens '
+				+ 'the '
+				+ 'browser to the builder sign-in page (standard OAuth 2.0 ' +
 				'authorization-code + PKCE with a localhost redirect) and waits for ' +
 				'the user to sign in and approve. On success the access token is ' +
 				'cached in ~/.reclaim/config.json and activated for this session.\n\n' +
@@ -223,12 +233,10 @@ async function exchangeCode(
 			client_id: opts.clientId,
 		}).toString(),
 	})
-	assert(
-		res.ok,
-		new Error(`Token exchange failed (${res.status}): ${await res.text()}`),
-	)
+	const body = await res.text()
+	assert(res.ok, new Error(`Token exchange failed (${res.status}): ${body}`))
 
-	const json = (await res.json()) as {
+	const json = JSON.parse(body) as {
 		access_token?: string
 		expires_in?: number
 	}

package/src/mcp/tools/authenticate/builder-access.ts

@@ -0,0 +1,42 @@
+import type { ReclaimClient } from '@reclaimprotocol/client'
+import { defineTool, type RegisteredTool } from '../../server.ts'
+import { authenticateTool } from './authenticate.ts'
+
+/** Legacy-devtools mode needs a distinct Builder login solely for allocating
+ * quota-accounted Popcorn sessions. Builder mode uses its native auth tool. */
+export function buildBuilderAuthenticationTools(
+	client: ReclaimClient,
+): RegisteredTool[] {
+	return [authenticateTool(client, 'authenticate_builder')]
+}
+
+/** Legacy-devtools mode lacks generated Builder API tools, so it needs this
+ * narrow organization-discovery bridge for remote-browser allocation. */
+export function buildBuilderOrganizationTools(
+	client: ReclaimClient,
+): RegisteredTool[] {
+	return [
+		defineTool<{ cursor?: string }>(
+			{
+				name: 'list_builder_organizations',
+				description:
+					'List organizations available to the authenticated Builder user. '
+					+ 'Use an organization id from this result when calling '
+					+ 'attach_browser with mode="builder". Available only in '
+					+ 'legacy-devtools publishing mode; Builder mode uses list_orgs.',
+				inputSchema: {
+					type: 'object',
+					properties: {
+						cursor: { type: 'string', maxLength: 500 },
+					},
+				},
+			},
+			async({ cursor }) => {
+				const { data } = await client.call('ListOrgs', {
+					query: { ...(cursor ? { cursor } : {}) },
+				})
+				return data
+			},
+		),
+	]
+}

package/src/mcp/tools/authenticate/index.ts

@@ -1,4 +1,8 @@
 // Barrel for the credential tool group: local eth proof-owner key (env/PEM)
 // and the org-token-authenticated builder tools. Import from here.
+export {
+	buildBuilderAuthenticationTools,
+	buildBuilderOrganizationTools,
+} from './builder-access.ts'
 export { buildCredentialTools, buildLocalCredentialTools } from './build.ts'
 export { readSession } from './session-cache.ts'

package/src/old/login-cdp.ts

@@ -138,15 +138,14 @@ export async function captureFirebaseTokenViaCdp(opts: {
 
 	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 }
 			}
@@ -173,3 +172,14 @@ export async function captureFirebaseTokenViaCdp(opts: {
 		await handles.close().catch(() => {})
 	}
 }
+
+function runtimeResultValue(value: unknown): unknown {
+	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/src/old/tools/build.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'
 import { authenticateTool } from './authenticate.ts'
@@ -23,14 +24,19 @@ import { verifySdkSetupTool } from './verify-sdk-setup.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 function buildOldBackendTools(
 	client: ReclaimOldClient,
 	sdkClient: ReclaimSdkClient,
+	attachRef?: { current?: AttachState },
 ): RegisteredTool[] {
 	return [
 		authenticateTool(client),
-		createVersionFromCaptureTool(client),
+		createVersionFromCaptureTool(client, attachRef),
 		getMeProvidersTool(client),
 		getProviderInfoTool(sdkClient),
 		updateProviderMetadataTool(client),

package/src/old/tools/publish.ts

@@ -1,5 +1,6 @@
 import { Boom, isBoom } from '@hapi/boom'
 import { defineTool, type RegisteredTool } from '../../mcp/server.ts'
+import type { AttachState } from '../../mcp/tools/agent/attach.ts'
 import { INJECTION_GUIDE } from '../../provider/injection-doc.ts'
 import {
 	countsFor,
@@ -70,9 +71,16 @@ function rethrowOwnershipError(err: unknown, providerId: string): never {
  *     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: ReclaimOldClient,
+	attachRef?: { current?: AttachState },
 ): RegisteredTool {
 	return defineTool<{
 		provider?: ReclaimProvider
@@ -139,7 +147,11 @@ export function createVersionFromCaptureTool(
 				'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: {
@@ -288,7 +300,29 @@ export function createVersionFromCaptureTool(
 							'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: {
@@ -485,6 +519,23 @@ export function createVersionFromCaptureTool(
 				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: unknown) => {
 				if(notes.length && result && typeof result === 'object') {
 					return { ...result, _notes: notes }
@@ -528,9 +579,9 @@ export function createVersionFromCaptureTool(
 						'reads them when adding a version. ' +
 						(followUp
 							? 'They were applied by the follow-up version the tool ' +
-								'created to set disableRequestReplay.'
+							'created to set disableRequestReplay.'
 							: 'Publish once to create the provider, then call this ' +
-								'again WITH the returned providerId to set them.'),
+							'again WITH the returned providerId to set them.'),
 					)
 				}
 

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/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.',
+		)
+	}
+}