@reclaimprotocol/agent 0.1.22 → 0.1.24

package/src/proof/pod-prover.ts

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

package/src/proof/replay.ts

@@ -9,7 +9,7 @@ export interface ReplayResult {
 
 /** Expand `{{name}}` placeholders from `paramValues`. Matches the attestor
  *  SDK's behavior so replay and proof both hit the same final URL. */
-function expandTemplate(
+export function expandTemplate(
 	s: string,
 	params: Record<string, string> | undefined,
 ): string {
@@ -23,10 +23,22 @@ function expandTemplate(
 	})
 }
 
-export async function replayProvider(
+/** Build the request the wire replay actually sends: `{{name}}` placeholders
+ *  in the URL/headers/body expanded from `provider.paramValues`, secrets
+ *  layered onto the public headers. Shared by every replay transport (Node
+ *  `fetch` here, or a `fetch` run inside the live browser tab) so they all
+ *  send the identical request. */
+export interface ReplayRequest {
+	url: string
+	method: string
+	headers: Record<string, string>
+	body?: string
+}
+
+export function buildReplayRequest(
 	provider: ReclaimProvider,
 	secrets: Record<string, string>,
-): Promise<ReplayResult> {
+): ReplayRequest {
 	const params = provider.paramValues
 	const url = expandTemplate(provider.url, params)
 	const expandedHeaders: Record<string, string> = {}
@@ -35,23 +47,35 @@ export async function replayProvider(
 	}
 
 	const headers = { ...expandedHeaders, ...secrets }
-	const fetchInit: RequestInit = {
+	const body = provider.body !== undefined
+		? expandTemplate(provider.body, params)
+		: undefined
+	return {
+		url,
 		method: provider.method,
 		headers,
-		redirect: 'manual',
-	}
-	if(provider.body !== undefined) {
-		fetchInit.body = expandTemplate(provider.body, params)
+		...(body !== undefined ? { body } : {}),
 	}
+}
 
-	const res = await fetch(url, fetchInit)
-	const body = await res.text()
+/**
+ * Judge a replayed response against `provider`'s matchers — the part of
+ * replay that's identical regardless of HOW the request was sent (detached
+ * Node `fetch` or a live in-browser `fetch`). Separated from the actual
+ * network call so both transports share one evaluation.
+ */
+export function evaluateReplay(
+	status: number,
+	body: string,
+	provider: ReclaimProvider,
+): ReplayResult {
+	const params = provider.paramValues
 	const hints: string[] = []
-	if(res.status === 401 || res.status === 403) {
+	if(status === 401 || status === 403) {
 		hints.push('auth/permission failed')
 	}
 
-	if(res.status >= 500) {
+	if(status >= 500) {
 		hints.push('upstream server error')
 	}
 
@@ -66,18 +90,14 @@ export async function replayProvider(
 			value: expandTemplate(m.value, params),
 		}
 		if(!matchesBody(body, expanded)) {
-			if(res.status >= 200 && res.status < 300) {
+			if(status >= 200 && status < 300) {
 				hints.push(
 					`matcher ${expanded.type} did not match — ` +
 					'value may have changed or matcher is too tight',
 				)
 			}
 
-			const result: ReplayResult = {
-				status: res.status,
-				body,
-				matchesOriginal: false,
-			}
+			const result: ReplayResult = { status, body, matchesOriginal: false }
 			if(hints.length > 0) {
 				result.hints = hints
 			}
@@ -86,7 +106,28 @@ export async function replayProvider(
 		}
 	}
 
-	return { status: res.status, body, matchesOriginal: res.status < 400 }
+	return { status, body, matchesOriginal: status < 400 }
+}
+
+/** Detached Node-side replay: sends the request directly from this process,
+ *  NOT from any attached browser tab — its cookies/secrets are exactly the
+ *  `secrets` passed in, never a real browser session. Used by tests and by
+ *  any caller with no live browser to replay through (the MCP's authoring
+ *  backend instead runs the SAME request inside the attached tab — see
+ *  `proof/page-replay.ts` — so replay reflects real session cookies). */
+export async function replayProvider(
+	provider: ReclaimProvider,
+	secrets: Record<string, string>,
+): Promise<ReplayResult> {
+	const req = buildReplayRequest(provider, secrets)
+	const res = await fetch(req.url, {
+		method: req.method,
+		headers: req.headers,
+		redirect: 'manual',
+		...(req.body !== undefined ? { body: req.body } : {}),
+	})
+	const body = await res.text()
+	return evaluateReplay(res.status, body, provider)
 }
 
 function matchesBody(body: string, m: ResponseMatch): boolean {

package/src/provider/dom-xpath.ts

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

package/src/provider/draft.ts

@@ -57,7 +57,8 @@ export interface DraftTarget {
 
 /** The realized extraction for one target — its value paired with the
  *  redaction that reveals it (absent when matched literally). Lets a consumer
- *  validate each value against its own selector (e.g. the cloud replay). */
+ *  validate each value against its own selector (for example, the cloud
+ *  replay). */
 export interface Extraction {
 	name: string
 	value: string
@@ -110,12 +111,14 @@ function sanitizeRequestHeaders(
  *  match or redaction — either a neighbouring target's value or a target's own
  *  value left un-templated. The matcher builds each target's window
  *  independently and drops the per-user WORDS it can see, but it cannot know a
- *  neighbouring value is itself user-specific (e.g. a name sharing a text node
- *  with an id — a `<b>{{id}}</b>` sitting beside a `<td>{{name}}</td>`).
- *  Cross-checking every value against every match here catches that: a portable
- *  provider contains NO captured value as a literal — each appears only as its
- *  `{{param}}`. Throwing discards the draft so the agent re-captures or
- *  re-proposes rather than shipping a provider pinned to this one user. */
+ *  neighbouring value is itself user-specific (for example, a name sharing a
+ *  text node with an id — a `<b>{{id}}</b>` sitting beside a
+ *  `<td>{{name}}</td>`). Cross-checking every value against every match here
+ *  catches
+ *  that: a portable provider contains NO captured value as a literal — each
+ *  appears only as its `{{param}}`. Throwing discards the draft so the agent
+ *  re-captures or re-proposes rather than shipping a provider pinned to this
+ *  one user. */
 export function assertPortableMatches(
 	matches: ResponseMatch[],
 	redactions: ResponseRedaction[],
@@ -275,12 +278,45 @@ function deriveParamName(providerName: string): string {
 	return last.toLowerCase()
 }
 
+/** A `paramName` doubles as a regex NAMED CAPTURE GROUP (`(?<name>...)`) and a
+ *  `paramValues` object key — both require a plain identifier. Nothing
+ *  downstream validates this: an invalid name builds a syntactically broken
+ *  regex that silently fails to extract at verification time instead of
+ *  erroring here, at draft time, where it's actually fixable. */
+const VALID_PARAM_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/
+
+/** Resolve a target's `paramName`: shortened (the default — last alphanumeric
+ *  token, lowercased) or, with `shorten: false`, the name verbatim — the
+ *  caller's choice, validated so it's still safe as a capture-group
+ *  identifier. */
+function resolveParamName(targetName: string, shorten: boolean): string {
+	if(!shorten) {
+		if(!VALID_PARAM_NAME.test(targetName)) {
+			throw new Error(
+				`target name "${targetName}" isn't safe as a param name with `
+				+ 'shortenNames:false — it becomes a regex capture-group name AND '
+				+ 'a paramValues key, so it must start with a letter/underscore and '
+				+ 'contain only letters, digits, and underscores (we recommend '
+				+ 'lower_snake_case, for example, "employer_name"). Rename it, or drop '
+				+ '`shortenNames: false` to auto-derive a safe one.',
+			)
+		}
+
+		return targetName
+	}
+
+	return deriveParamName(targetName)
+}
+
 export function draftProvider(
 	req: CapturedRequest,
 	targets: DraftTarget[],
 	name: string,
 	hash?: OprfMode,
+	opts?: { shortenNames?: boolean },
 ): DraftResult {
+	const shortenNames = opts?.shortenNames ?? true
+
 	if(!req.responseBody) {
 		throw new Error(`captured request ${req.requestId} has no response body`)
 	}
@@ -297,17 +333,24 @@ export function draftProvider(
 	const extractions: Extraction[] = []
 	const effectiveHashes: (OprfMode | undefined)[] = []
 	let paramValues: Record<string, string> | undefined
-	const seenParams = new Set<string>()
+	const seenParams = new Map<string, string>()
 	for(const t of targets) {
-		const paramName = deriveParamName(t.name)
-		if(seenParams.has(paramName)) {
+		const paramName = resolveParamName(t.name, shortenNames)
+		const priorName = seenParams.get(paramName)
+		if(priorName !== undefined) {
 			throw new Error(
-				`two targets resolve to the same param "${paramName}"; `
-				+ 'give them distinct names',
+				`targets "${priorName}" and "${t.name}" both resolve to the same `
+				+ `param name "${paramName}"`
+				+ (shortenNames
+					? ' (names are shortened to their last alphanumeric token) — '
+						+ 'give them more distinct names, for example '
+						+ '"firstName"/"surname" instead of "first_name"/"last_name"'
+					: ' — give them distinct names, or drop `shortenNames: false` '
+						+ 'to auto-derive distinct ones'),
 			)
 		}
 
-		seenParams.add(paramName)
+		seenParams.set(paramName, t.name)
 		// Precedence: explicit per-target hash → explicit request-wide hash →
 		// the anti-leak floor (force-OPRF values whose SHAPE is unambiguous PII).
 		// The model makes the contextual calls (which named fields are sensitive)

package/src/provider/injection-doc.ts

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

package/src/provider/match-redaction-warning.ts

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