npm - @reclaimprotocol/agent - Versions diffs - 0.1.5 → 0.1.7 - Mend

@reclaimprotocol/agent 0.1.5 → 0.1.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (117) hide show

package/lib/authoring/backend.d.ts +0 -24
package/lib/authoring/find.d.ts +3 -0
package/lib/authoring/find.js +54 -0
package/lib/authoring/index.d.ts +3 -3
package/lib/authoring/index.js +4 -3
package/lib/authoring/propose.d.ts +3 -0
package/lib/authoring/propose.js +109 -0
package/lib/authoring/replay.d.ts +10 -0
package/lib/authoring/replay.js +34 -0
package/lib/authoring/tools.d.ts +13 -6
package/lib/authoring/tools.js +108 -293
package/lib/authoring/util.d.ts +27 -0
package/lib/authoring/util.js +21 -0
package/lib/consts.d.ts +6 -1
package/lib/consts.js +9 -2
package/lib/mcp/server.d.ts +2 -41
package/lib/mcp/server.js +6 -34
package/lib/mcp/start.js +4 -2
package/lib/mcp/tools/agent/analyze.js +3 -3
package/lib/mcp/tools/agent/build.d.ts +4 -4
package/lib/mcp/tools/agent/build.js +13 -15
package/lib/mcp/tools/agent/capture.d.ts +13 -1
package/lib/mcp/tools/agent/capture.js +18 -85
package/lib/mcp/tools/agent/eval.d.ts +5 -2
package/lib/mcp/tools/agent/eval.js +11 -121
package/lib/mcp/tools/agent/find.d.ts +10 -3
package/lib/mcp/tools/agent/find.js +25 -31
package/lib/mcp/tools/agent/proof.d.ts +13 -3
package/lib/mcp/tools/agent/proof.js +81 -132
package/lib/mcp/tools/agent/propose.d.ts +10 -9
package/lib/mcp/tools/agent/propose.js +87 -64
package/lib/mcp/tools/agent/replay.d.ts +10 -3
package/lib/mcp/tools/agent/replay.js +29 -36
package/lib/mcp/tools/agent/session.d.ts +1 -3
package/lib/mcp/tools/agent/session.js +5 -5
package/lib/mcp/tools/agent/shared.d.ts +5 -3
package/lib/mcp/tools/agent/shared.js +29 -19
package/lib/old/client.d.ts +39 -0
package/lib/old/client.js +18 -0
package/lib/old/login-cdp.d.ts +24 -5
package/lib/old/login-cdp.js +29 -15
package/lib/old/sdk-client.d.ts +39 -0
package/lib/old/sdk-client.js +85 -0
package/lib/old/to-register.d.ts +69 -0
package/lib/old/to-register.js +55 -2
package/lib/old/tools/authenticate.js +3 -7
package/lib/old/tools/build.d.ts +6 -1
package/lib/old/tools/build.js +11 -1
package/lib/old/tools/get-provider-info.d.ts +16 -0
package/lib/old/tools/get-provider-info.js +73 -0
package/lib/old/tools/get-version-config.d.ts +17 -0
package/lib/old/tools/get-version-config.js +47 -0
package/lib/old/tools/publish.js +208 -2
package/lib/old/tools/update-provider-metadata.d.ts +16 -0
package/lib/old/tools/update-provider-metadata.js +61 -0
package/lib/proof/attestor.d.ts +6 -3
package/lib/proof/attestor.js +10 -1
package/lib/proof/debug-response-dump.d.ts +4 -0
package/lib/proof/debug-response-dump.js +55 -0
package/lib/proof/patch-domhandler.d.ts +1 -0
package/lib/proof/patch-domhandler.js +59 -0
package/lib/proof/zk-files.js +7 -6
package/lib/provider/dom-xpath.d.ts +17 -0
package/lib/provider/dom-xpath.js +187 -0
package/lib/provider/draft.d.ts +30 -2
package/lib/provider/draft.js +117 -28
package/lib/provider/index.d.ts +4 -0
package/lib/provider/index.js +7 -0
package/lib/provider/injection-doc.js +6 -0
package/lib/provider/matcher.d.ts +17 -20
package/lib/provider/matcher.js +394 -280
package/lib/provider/schema.d.ts +7 -5
package/lib/tools/registry.d.ts +14 -0
package/lib/tools/registry.js +32 -0
package/package.json +9 -1
package/skill/SKILL.builder.md +42 -23
package/skill/SKILL.old.md +6 -2
package/skill/builder-mode.md +1 -1
package/skill/injection-api.md +117 -0
package/src/authoring/backend.ts +98 -0
package/src/authoring/index.ts +20 -0
package/src/authoring/tools.ts +273 -0
package/src/authoring/util.ts +42 -0
package/src/consts.ts +15 -2
package/src/mcp/server.ts +11 -78
package/src/mcp/start.ts +4 -1
package/src/mcp/tools/agent/analyze.ts +3 -3
package/src/mcp/tools/agent/build.ts +13 -21
package/src/mcp/tools/agent/capture.ts +31 -115
package/src/mcp/tools/agent/eval.ts +19 -155
package/src/mcp/tools/agent/find.ts +33 -36
package/src/mcp/tools/agent/proof.ts +87 -160
package/src/mcp/tools/agent/propose.ts +93 -85
package/src/mcp/tools/agent/replay.ts +32 -42
package/src/mcp/tools/agent/session.ts +4 -5
package/src/mcp/tools/agent/shared.ts +152 -0
package/src/old/client.ts +60 -0
package/src/old/login-cdp.ts +29 -23
package/src/old/sdk-client.ts +105 -0
package/src/old/to-register.ts +102 -6
package/src/old/tools/authenticate.ts +3 -11
package/src/old/tools/build.ts +12 -0
package/src/old/tools/get-provider-info.ts +91 -0
package/src/old/tools/get-version-config.ts +56 -0
package/src/old/tools/publish.ts +264 -1
package/src/old/tools/update-provider-metadata.ts +72 -0
package/src/proof/attestor.ts +16 -4
package/src/proof/debug-response-dump.ts +70 -0
package/src/proof/patch-domhandler.ts +68 -0
package/src/proof/zk-files.ts +7 -6
package/src/provider/dom-xpath.ts +225 -0
package/src/provider/draft.ts +168 -35
package/src/provider/index.ts +8 -0
package/src/provider/injection-doc.ts +6 -0
package/src/provider/matcher.ts +477 -357
package/src/provider/schema.ts +7 -5
package/src/tools/registry.ts +92 -0

package/src/provider/matcher.ts CHANGED Viewed

@@ -1,34 +1,7 @@
+import { elementAnchor } from './dom-xpath.ts'
 import { normalizeCandidates } from './normalize.ts'
 import type { OprfMode, ResponseMatch, ResponseRedaction } from './schema.ts'
-/**
- * Minimum bytes per response redaction. The Reclaim zkTLS protocol uses
- * AES-CTR; revealing fewer than one AES block (16 bytes) opens the slice
- * to brute-force guessing. Matters only for the text/plain padded-regex
- * fallback — xPath / jsonPath redactions reveal a whole TLS record, which
- * is always larger.
- */
-const MIN_REVEAL_BYTES = 16
-/**
- * Budget for climbing past the smallest enclosing element in search of an
- * ancestor with an `id` or `class` anchor. Capped so we don't end up
- * pointing at `<body>` or `<html>` (which would defeat redaction by
- * revealing most of the page).
- */
-const MAX_ANCHOR_CLIMB_BYTES = 512
-/**
- * Hard cap on how many bytes the redaction is allowed to reveal. When
- * the picked xPath/jsonPath element exceeds this, the redaction is
- * extended with a `regex` that narrows to the surrounding key/value
- * pattern — so the attestor only ZKs ~50-100 bytes instead of multi-KB
- * blobs. Without this, a perfectly anchorable element like
- * `<script id="client-env">{...7KB of state...}</script>` would push
- * the attestor through many MB of ZK work and OOM Node.
- */
-const MAX_REVEAL_BYTES = 512
 /** Reclaim attestor caps OPRF-hashed values at 62 bytes (TOPRF marker
  *  encoding). Surfaces as a clean error here rather than a confusing
  *  attestor-side failure at proof time. */
@@ -37,33 +10,30 @@ export const OPRF_MAX_BYTES = 62
 export interface MatcherSynthesis {
 	match: ResponseMatch
 	redaction?: ResponseRedaction
-	/** Always set: the `{{paramName}}` template in `match.value` resolves
-	 *  to this at proof time. The original captured value is carried here
-	 *  so the prover can replay/proof against their actual data without
-	 *  baking it into the provider. */
+	/** The captured value, keyed by `paramName`. NOT baked into the shipped
+	 *  recipe — the caller uses it for the author's own proof; each verifying
+	 *  user's value is re-extracted live (see verify/run.ts `extractBareParams`).
+	 */
 	paramValues?: Record<string, string>
 }
 /**
- * Build the matcher pieces (responseMatches + responseRedactions +
- * paramValues) for a target value seen in a captured response.
+ * Build the matcher pieces (one responseMatch + one responseRedaction) for a
+ * target value seen in a captured response. The design, in one line:
  *
- * All outputs share the same shape:
- *   - responseMatches: a single `contains` whose value is the surrounding
- *     structural context with the target replaced by `{{paramName}}`
- *   - paramValues: `{ [paramName]: target }` — the prover's real value
- *   - responseRedactions: one entry that narrows the revealed slice
- *     (xPath / jsonPath / regex), and — when `hash` is requested — also
- *     carries a `regex` with a named capture group + a `hash` field for
- *     OPRF
+ *   the REDACTION selects with xPath/jsonPath and names the value with a
+ *   capture group; the MATCH is a `contains` of the surrounding structure with
+ *   the value replaced by `{{paramName}}`.
  *
- * `hash` is opt-in. The skill prompts the dev. Drafting without `hash`
- * is the default — the value travels in cleartext to the attestor.
+ * The match is what the attestor enforces (against the prover's revealed
+ * bytes), so it must anchor the value in context the prover can't relocate — a
+ * JSON key (`"login":"{{v}}"`) or the value's HTML element (`<span …>{{v}}`).
+ * The redaction's regex only extracts/narrows; xPath/jsonPath do the selecting.
  *
- * Throws when `hash` is set but the target has no safe character class
- * (unicode, punctuation, spaces — anything that doesn't fit a digit /
- * slug / email regex). Drafting OPRF for a value we can't capture
- * reliably would yield a broken provider.
+ * `hash` (OPRF) is opt-in — enable it only when the request asks to protect
+ * PII. It rides the `contains {{v}}` path: the redaction carries `hash`, match
+ * keeps `{{v}}`, and the attestor substitutes the nullifier from paramValues at
+ * proof time. Throws when `hash` is set on a free-form value (no safe class).
  */
 export function synthesizeMatcher(
 	body: string,
@@ -81,116 +51,181 @@ export function synthesizeMatcher(
 	if(hash && !inferValueClass(target)) {
 		throw new Error(
-			'OPRF hashing requires a target with a known-safe character class ' +
-			'(digits, slug, or email). ' +
-			`Got "${target}" which is free-form. Use a tighter target` +
-			'(e.g. just the alphanumeric portion of the value)' +
-			' or call propose_provider without `hash`.',
+			'OPRF hashing requires a target with a known-safe character class '
+			+ '(digits, slug, or email). '
+			+ `Got "${target}" which is free-form. Use a tighter target `
+			+ '(e.g. just the alphanumeric portion of the value) '
+			+ 'or call propose_provider without `hash`.',
 		)
 	}
-	const pick = pickAnchor(body, contentType, target)
-	// Two reasons to extend the redaction with a `regex` narrow:
-	//   (a) hash is set — the regex carries the named capture group we OPRF
-	//   (b) the picked element is too big to reveal whole — we narrow the
-	//       slice to just the value's surrounding key/value pattern
-	const isOversized =
-		pick?.elementBytes !== undefined && pick.elementBytes > MAX_REVEAL_BYTES
-	const needsRegex = hash !== undefined || isOversized
-	if(pick && needsRegex) {
-		// Free-form values can use a permissive class when only narrowing;
-		// `hash` already had the strict check above.
-		const valueClass = inferValueClass(target) ?? '[^"<>]+'
-		const captureRegex = buildCaptureRegex(body, target, paramName, valueClass)
-		const redaction: ResponseRedaction = {
-			...pick.redaction,
-			regex: captureRegex,
-		}
-		if(hash) {
-			redaction.hash = hash
+	const valueClass = inferValueClass(target) ?? '[^"<>\\n]+'
+	// JSON body → the value lives in a `"key": value` pair. jsonPath pins the
+	// exact property; the `contains` match anchors on the key.
+	if(/json/i.test(contentType) || isJsonBody(body)) {
+		const r = jsonMatcher(body, target, paramName, valueClass, hash)
+		if(r) {
+			return r
 		}
+	}
-		return makeResult(body, target, paramName, redaction)
+	// HTML/XML → the value lives in an element. xPath selects it (an id/class
+	// ancestor, else the value's own tag); the `contains` match is the element
+	// markup with the value swapped for the placeholder. A `<script>` holding
+	// JSON routes through jsonPath instead.
+	if(/html|xml/i.test(contentType) || looksLikeHtml(body)) {
+		const r = htmlMatcher(body, target, paramName, valueClass, hash)
+		if(r) {
+			return r
+		}
 	}
-	if(pick) {
-		return makeResult(body, target, paramName, pick.redaction)
+	// No JSON key and no stable xPath anchor: a content-anchored regex, matched
+	// by CONTENT so it reproduces regardless of DOM position at proof time (a
+	// positional `(//tag)[N]` resolves to the wrong node at proof — see 9fd7770).
+	return contentMatcher(body, target, paramName, valueClass, hash)
+}
+/** True when `body` is a JSON document (starts `{`/`[` and parses). */
+function isJsonBody(body: string): boolean {
+	const head = body.trimStart()[0]
+	if(head !== '{' && head !== '[') {
+		return false
 	}
-	// No structural anchor — fall back to a regex-only redaction.
-	if(hash) {
-		const captureRegex = buildCaptureRegex(
-			body,
-			target,
-			paramName,
-			inferValueClass(target)!,
-		)
-		return makeResult(body, target, paramName, { regex: captureRegex, hash })
+	try {
+		JSON.parse(body)
+		return true
+	} catch{
+		return false
 	}
+}
-	const padded = buildPaddedRegex(body, target)
-	if(padded) {
-		return makeResult(body, target, paramName, { regex: padded })
+/** Index of `target` (or an encoding variant) in `text`, with the matched
+ *  variant. `{ idx: -1 }` when absent. */
+function firstIndex(
+	text: string,
+	target: string,
+): { idx: number, value: string } {
+	for(const value of [target, ...normalizeCandidates(target)]) {
+		const idx = text.indexOf(value)
+		if(idx >= 0) {
+			return { idx, value }
+		}
 	}
-	return undefined
+	return { idx: -1, value: target }
 }
-function makeResult(
-	body: string,
+/**
+ * Assemble the result for a value that sits after a literal `prefix` and
+ * before a `close` delimiter — the shared shape for JSON `"key":"…"` and
+ * JSON-in-HTML. The redaction pairs the selector with a capture regex
+ * (whitespace in the prefix flexed); the match `contains` `prefix{{v}}close`.
+ */
+function keyValueResult(
+	prefix: string,
+	close: string,
 	target: string,
 	paramName: string,
-	redaction: ResponseRedaction,
+	valueClass: string,
+	selector: { jsonPath?: string, xPath?: string },
+	hash?: OprfMode,
 ): MatcherSynthesis {
+	const redaction: ResponseRedaction = {
+		...selector,
+		regex:
+			`${escapeRegexFlexWs(prefix)}(?<${paramName}>${valueClass})`
+			+ escapeRegex(close),
+	}
+	if(hash) {
+		redaction.hash = hash
+	}
 	return {
-		match: {
-			type: 'contains',
-			value: buildContextualTemplate(body, target, paramName),
-		},
+		match: { type: 'contains', value: `${prefix}{{${paramName}}}${close}` },
 		redaction,
 		paramValues: { [paramName]: target },
 	}
 }
-/** Pick the structural anchor for the redaction (jsonPath or xPath).
- *  Carries `elementBytes` for HTML so the caller can decide whether the
- *  picked element is too large to reveal whole. JSON leaves are always
- *  primitives (see `walk()`), so size isn't tracked there. */
-interface AnchorPick {
-	redaction: ResponseRedaction
-	elementBytes?: number
-}
+// ---------------------------------------------------------------------------
+// JSON: "key": value  →  jsonPath redaction + `contains "key":"{{v}}"`
+// ---------------------------------------------------------------------------
-function pickAnchor(
+/**
+ * Matcher for a value inside a JSON `"key": value` pair. jsonPath pins the
+ * exact property (so the redaction extracts THIS one, not a same-named key
+ * elsewhere); the `contains` match anchors on `"key":`.
+ */
+function jsonMatcher(
 	body: string,
-	contentType: string,
 	target: string,
-): AnchorPick | undefined {
-	if(/json/i.test(contentType)) {
-		const jsonPath = findJsonPath(body, target)
-		if(jsonPath) {
-			return { redaction: { jsonPath } }
-		}
+	paramName: string,
+	valueClass: string,
+	hash?: OprfMode,
+): MatcherSynthesis | undefined {
+	const jsonPath = findJsonPath(body, target)
+	if(!jsonPath) {
+		return undefined
 	}
-	if(/html|xml/i.test(contentType) || looksLikeHtml(body)) {
-		const xPath = synthesizeXPath(body, target)
-		if(xPath) {
-			return {
-				redaction: { xPath: xPath.xPath },
-				elementBytes: xPath.elementBytes,
-			}
-		}
+	const anchor = jsonKeyPrefix(body, target)
+	if(!anchor) {
+		return undefined
 	}
-	return undefined
+	return keyValueResult(
+		anchor.prefix, anchor.close, target, paramName, valueClass,
+		{ jsonPath }, hash,
+	)
 }
-// ---------------------------------------------------------------------------
-// JSON helpers
-// ---------------------------------------------------------------------------
+/**
+ * The literal `"key":"` (or `"key":` for a raw number/bool) immediately before
+ * `target` in `text`, plus the closing quote (`"` for a string value, `''`
+ * otherwise). Returns undefined when the value isn't preceded by a JSON key.
+ */
+function jsonKeyPrefix(
+	text: string,
+	target: string,
+): { prefix: string, close: string } | undefined {
+	const { idx } = firstIndex(text, target)
+	if(idx < 0) {
+		return undefined
+	}
+	let i = idx - 1
+	const quoted = text[i] === '"'
+	if(quoted) {
+		i--
+	}
+	while(i >= 0 && /\s/.test(text[i] ?? '')) {
+		i--
+	}
+	if(text[i] !== ':') {
+		return undefined
+	}
+	i--
+	while(i >= 0 && /\s/.test(text[i] ?? '')) {
+		i--
+	}
+	if(text[i] !== '"') {
+		return undefined
+	}
+	const keyStart = text.lastIndexOf('"', i - 1)
+	if(keyStart < 0) {
+		return undefined
+	}
+	return { prefix: text.slice(keyStart, idx), close: quoted ? '"' : '' }
+}
 function findJsonPath(body: string, target: string): string | undefined {
 	let parsed: unknown
@@ -253,295 +288,338 @@ function walk(
 }
 // ---------------------------------------------------------------------------
-// HTML helpers
+// HTML: element  →  xPath redaction + `contains "<tag …>{{v}}</tag>"`
 // ---------------------------------------------------------------------------
-interface EnclosingElement {
-	tag: string
-	openStart: number
-	closeEnd: number
-	id?: string
-	classes: string[]
-}
 function looksLikeHtml(body: string): boolean {
 	return /<[a-zA-Z][a-zA-Z0-9-]*[\s>]/.test(body.slice(0, 2000))
 }
-/** Find the best xPath anchor for `target` in HTML-shaped `body`.
- *  Preference order:
- *    1. id/class on the smallest enclosing element
- *    2. id/class on the nearest ancestor within MAX_ANCHOR_CLIMB_BYTES
- *    3. positional `(//tag)[N]` on the smallest enclosing element */
-function synthesizeXPath(
+/**
+ * Matcher for a value inside an HTML element. The element and a verified xPath
+ * come from a real parse5 parse (see dom-xpath.ts), then either:
+ *  - `<script>` JSON: dig the value out with jsonPath (`"key":"{{v}}"` match);
+ *  - regular element: `contains` the element markup with the value → `{{v}}`.
+ */
+function htmlMatcher(
 	body: string,
 	target: string,
-): { xPath: string, elementBytes: number } | undefined {
-	for(const variant of normalizeCandidates(target)) {
-		const idx = body.indexOf(variant)
-		if(idx < 0) {
-			continue
-		}
+	paramName: string,
+	valueClass: string,
+	hash?: OprfMode,
+): MatcherSynthesis | undefined {
+	const anchor = elementAnchor(body, [target, ...normalizeCandidates(target)])
+	if(!anchor) {
+		return undefined
+	}
-		let el = findEnclosingElement(body, idx, variant.length)
-		while(el && el.closeEnd - el.openStart < MIN_REVEAL_BYTES) {
-			const outer = findEnclosingElement(
-				body,
-				el.openStart,
-				el.closeEnd - el.openStart,
+	const revealSlice = body.slice(anchor.start, anchor.end)
+	// JSON embedded in a <script>: xPath selects the script, jsonPath digs out
+	// the value, the regex captures it — immune to a same-named key elsewhere.
+	const scriptJson = scriptJsonContent(revealSlice)
+	if(scriptJson) {
+		const jsonPath = findJsonPath(scriptJson, target)
+		const kp = jsonPath ? jsonKeyPrefix(scriptJson, target) : undefined
+		if(jsonPath && kp) {
+			return keyValueResult(
+				kp.prefix, kp.close, target, paramName, valueClass,
+				{ xPath: anchor.xPath, jsonPath }, hash,
 			)
-			if(!outer || outer.openStart >= el.openStart) {
-				break
-			}
-			el = outer
-		}
-		if(!el) {
-			continue
-		}
-		const anchored = climbForAnchor(body, el)
-		const final = anchored ?? el
-		return {
-			xPath: buildXPath(final, body),
-			elementBytes: final.closeEnd - final.openStart,
 		}
 	}
-	return undefined
+	return elementResult(
+		anchor.xPath, revealSlice, target, paramName, valueClass, hash,
+	)
 }
-function climbForAnchor(
-	body: string,
-	el: EnclosingElement,
-): EnclosingElement | undefined {
-	if(el.id || el.classes.length > 0) {
-		return el
-	}
-	let cur = el
-	while(true) {
-		const parent = findEnclosingElement(
-			body,
-			cur.openStart,
-			cur.closeEnd - cur.openStart,
-		)
-		if(!parent || parent.openStart >= cur.openStart) {
-			return undefined
-		}
+/**
+ * `contains` a PORTABLE window of the element around the value, with the value
+ * swapped for `{{paramName}}`. "Portable" = it anchors only on stable structure
+ * (allow-listed attributes + tag boundaries) and excludes per-user / volatile
+ * bytes (`href`/`value`/`id`/`data-*` attribute values, sibling elements), so a
+ * published provider reproduces for ANY user, not just the author. The
+ * redaction reveals + captures the value over the same window (xPath + regex,
+ * whitespace flexed); `contains` is required for extractBareParams + OPRF.
+ */
+function elementResult(
+	xPath: string,
+	markup: string,
+	target: string,
+	paramName: string,
+	valueClass: string,
+	hash?: OprfMode,
+): MatcherSynthesis | undefined {
+	const { idx, value } = firstIndex(markup, target)
+	if(idx < 0) {
+		return undefined
+	}
-		if(parent.closeEnd - parent.openStart > MAX_ANCHOR_CLIMB_BYTES) {
-			return undefined
-		}
+	const { left, right } = portableWindow(markup, idx, value.length)
-		if(parent.id || parent.classes.length > 0) {
-			return parent
-		}
+	const redaction: ResponseRedaction = {
+		xPath,
+		regex:
+			`${escapeRegexFlexWs(left)}(?<${paramName}>${valueClass})`
+			+ escapeRegexFlexWs(right),
+	}
+	if(hash) {
+		redaction.hash = hash
+	}
-		cur = parent
+	return {
+		match: { type: 'contains', value: `${left}{{${paramName}}}${right}` },
+		redaction,
+		paramValues: { [paramName]: target },
 	}
 }
-function findEnclosingElement(
-	body: string,
+/** Attribute NAMES safe to bake into a match — stable across users. Everything
+ *  else (`href`, `src`, `value`, `id`, `data-*`, `style`, `content`, nonces, …)
+ *  carries per-user / per-render data and is excluded from the anchor. */
+const STABLE_ATTRS = new Set([
+	'class', 'type', 'rel', 'role', 'name', 'property', 'itemprop', 'for',
+	'scope', 'lang', 'dir', 'selected', 'checked', 'disabled', 'readonly',
+	'required', 'multiple', 'open', 'headers',
+])
+/** A portable literal window `{ left, right }` around the value in `markup`:
+ *  anchored on stable structure, stripped of volatile/per-user bytes. */
+function portableWindow(
+	markup: string,
 	valueIdx: number,
 	valueLen: number,
-): EnclosingElement | undefined {
-	let i = valueIdx - 1
-	while(i >= 0) {
-		if(body[i] !== '>') {
-			i--
-			continue
-		}
-		const tagEnd = i
-		const tagStart = body.lastIndexOf('<', tagEnd)
-		if(tagStart < 0) {
-			return undefined
-		}
-		const openTag = body.slice(tagStart, tagEnd + 1)
-		if(
-			openTag.startsWith('</') ||
-			openTag.startsWith('<!') ||
-			openTag.startsWith('<?') ||
-			openTag.trimEnd().endsWith('/>')
-		) {
-			i = tagStart - 1
-			continue
-		}
-		const tagNameMatch = openTag.match(/^<([a-zA-Z][a-zA-Z0-9-]*)/)
-		if(!tagNameMatch) {
-			i = tagStart - 1
-			continue
-		}
-		const tagName = tagNameMatch[1].toLowerCase()
-		const closePattern = new RegExp(`</${tagName}\\s*>`, 'i')
-		const afterValue = body.slice(valueIdx + valueLen)
-		const closeMatch = afterValue.match(closePattern)
-		if(closeMatch?.index === undefined) {
-			i = tagStart - 1
-			continue
-		}
-		const closeEnd =
-			valueIdx + valueLen + closeMatch.index + closeMatch[0].length
-		const idMatch = openTag.match(/\bid\s*=\s*["']([^"']+)["']/)
-		const classMatch = openTag.match(/\bclass\s*=\s*["']([^"']+)["']/)
-		const classes = classMatch ? classMatch[1].split(/\s+/).filter(Boolean) : []
-		const el: EnclosingElement = {
-			tag: tagName,
-			openStart: tagStart,
-			closeEnd,
-			classes,
-		}
-		if(idMatch?.[1] !== undefined) {
-			el.id = idMatch[1]
-		}
-		return el
-	}
-	return undefined
+): { left: string, right: string } {
+	const valueEnd = valueIdx + valueLen
+	const lastLt = markup.lastIndexOf('<', valueIdx - 1)
+	const lastGt = markup.lastIndexOf('>', valueIdx - 1)
+	// A `<` with no `>` after it before the value ⇒ value sits in an attribute.
+	return lastLt > lastGt
+		? attributeWindow(markup, valueIdx, valueEnd, lastLt)
+		: textWindow(markup, valueIdx, valueEnd, lastGt)
 }
-function buildXPath(el: EnclosingElement, body: string): string {
-	if(el.id) {
-		return `//${el.tag}[@id=${xpathLiteral(el.id)}]`
+/** Value is element text content. Left anchor: if only punctuation/whitespace
+ *  sits between the opening tag and the value, fold the stable opening tag in;
+ *  but if WORDS precede the value in the same text node they may be per-user
+ *  (e.g. `<li>Full Name ( {{id}} )` — the name), so drop through the last
+ *  alphanumeric and keep only the trailing punctuation as the anchor. Right:
+ *  include a closing tag, but stop at a sibling. */
+function textWindow(
+	markup: string,
+	valueIdx: number,
+	valueEnd: number,
+	openTagGt: number,
+): { left: string, right: string } {
+	const openTagStart = markup.lastIndexOf('<', openTagGt)
+	const openTag = openTagStart >= 0
+		? markup.slice(openTagStart, openTagGt + 1)
+		: ''
+	const between = markup.slice(openTagGt + 1, valueIdx)
+	const left = /[A-Za-z0-9]/.test(between)
+		// Words before the value could be per-user — anchor on the punctuation
+		// after the last one (drops the words AND the tag they'd drag in).
+		? between.replace(/[\s\S]*[A-Za-z0-9]/, '')
+		// Only punctuation/whitespace — safe to fold the stable opening tag.
+		: stableOpeningTail(openTag) + between
+	const nextLt = markup.indexOf('<', valueEnd)
+	const inter = nextLt < 0
+		? markup.slice(valueEnd)
+		: markup.slice(valueEnd, nextLt)
+	// Trailing words after the value may be per-user too — keep only the
+	// punctuation up to the first alphanumeric, and drop the closing tag with
+	// them (contains is contiguous, so it can't be reached past a word).
+	if(/[A-Za-z0-9]/.test(inter)) {
+		return { left, right: inter.replace(/[A-Za-z0-9][\s\S]*/, '') }
 	}
-	if(el.classes.length > 0) {
-		const distinctive = [...el.classes].sort((a, b) => b.length - a.length)[0]
-		return `//${el.tag}[contains(@class, ${xpathLiteral(distinctive)})]`
+	// Punctuation/whitespace only: fold the stable closing tag if present.
+	if(nextLt >= 0 && markup.startsWith('</', nextLt)) {
+		const close = markup.indexOf('>', nextLt)
+		const end = close < 0 ? nextLt : close + 1
+		return { left, right: markup.slice(valueEnd, end) }
 	}
-	return `(//${el.tag})[${tagIndex(body, el)}]`
+	// Sibling opening tag (or end of markup) — stop at it.
+	return { left, right: inter }
 }
-function tagIndex(body: string, el: EnclosingElement): number {
-	const pattern = new RegExp(`<${el.tag}\\b`, 'gi')
-	let n = 0
+/** Value is an attribute value: anchor on the nearest STABLE identifying
+ *  attribute (`name`/`property`/…) plus the value attribute's `name="`. */
+function attributeWindow(
+	markup: string,
+	valueIdx: number,
+	valueEnd: number,
+	openTagStart: number,
+): { left: string, right: string } {
+	const gt = markup.indexOf('>', valueEnd)
+	const openTag = markup.slice(openTagStart, gt < 0 ? markup.length : gt + 1)
+	const rel = valueIdx - openTagStart
+	const attrRe = /\s+([a-zA-Z][\w:-]*)(\s*=\s*("[^"]*"|'[^']*'|[^\s>]*))?/g
+	let anchorStart = -1
+	let valueAttrStart = -1
 	let m: RegExpExecArray | null
-	while((m = pattern.exec(body)) !== null) {
-		if(m.index > el.openStart) {
+	while((m = attrRe.exec(openTag)) !== null) {
+		const start = m.index
+		if(start < rel && rel < start + m[0].length) {
+			valueAttrStart = start
 			break
 		}
-		n++
+		if(STABLE_ATTRS.has(m[1].toLowerCase())) {
+			anchorStart = start
+		}
 	}
-	return n
+	const from = anchorStart >= 0 ? anchorStart : valueAttrStart
+	const left = from >= 0 ? openTag.slice(from, rel).replace(/^\s+/, '') : ''
+	const quote = markup[valueEnd]
+	return { left, right: quote === '"' || quote === "'" ? quote : '' }
 }
-/** Quote a string as an XPath 1.0 string literal. XPath 1.0 literals have no
- *  escape mechanism, so a value containing both quote characters must be
- *  assembled with concat(). Backslashes are not special and pass through. */
-function xpathLiteral(s: string): string {
-	if(!s.includes('"')) {
-		return `"${s}"`
+/** The portable suffix of an opening tag (ending at `>`): the trailing run of
+ *  allow-listed attributes. Everything up to and including the last volatile
+ *  attribute is dropped, so `<a href="/user" class="x">` → `class="x">`. */
+function stableOpeningTail(openTag: string): string {
+	const attrRe = /\s+([a-zA-Z][\w:-]*)(\s*=\s*("[^"]*"|'[^']*'|[^\s>]*))?/g
+	let cut = -1
+	let m: RegExpExecArray | null
+	while((m = attrRe.exec(openTag)) !== null) {
+		if(!STABLE_ATTRS.has(m[1].toLowerCase())) {
+			cut = m.index + m[0].length
+		}
 	}
-	if(!s.includes("'")) {
-		return `'${s}'`
+	return (cut < 0 ? openTag : openTag.slice(cut)).replace(/^\s+/, '')
+}
+/** If `markup` is a single `<script>…</script>` element, return its text
+ *  content (the JSON body the attestor exposes when a jsonPath is paired with
+ *  the script's xPath); otherwise undefined. */
+function scriptJsonContent(markup: string): string | undefined {
+	const match = /^<script\b[^>]*>([\s\S]*)<\/script>\s*$/i.exec(markup)
+	if(!match) {
+		return undefined
 	}
-	const parts = s.split('"').map((p) => `"${p}"`)
-	return `concat(${parts.join(', \'"\', ')})`
+	const content = match[1].trim()
+	return content.length > 0 ? content : undefined
 }
 // ---------------------------------------------------------------------------
-// Padded-regex fallback for non-JSON, non-HTML content
+// Content-anchored fallback (no stable structural anchor)
 // ---------------------------------------------------------------------------
-function buildPaddedRegex(body: string, target: string): string | undefined {
-	for(const cand of normalizeCandidates(target)) {
-		const idx = body.indexOf(cand)
-		if(idx < 0) {
-			continue
-		}
+/** Longest opening/closing HTML tag folded into the match context. */
+const MAX_TAG_BYTES = 256
-		let start = idx
-		let end = idx + cand.length
-		const need = MIN_REVEAL_BYTES - cand.length
-		if(need > 0) {
-			const leftPad = Math.floor(need / 2)
-			const rightPad = need - leftPad
-			start = Math.max(0, idx - leftPad)
-			end = Math.min(body.length, idx + cand.length + rightPad)
-			if(start === 0) {
-				end = Math.min(body.length, idx + cand.length + need - (idx - 0))
-			}
-			if(end === body.length) {
-				start = Math.max(0, body.length - MIN_REVEAL_BYTES)
-			}
-		}
+/** Bytes the left context grows per step while searching for uniqueness. */
+const CONTEXT_STEP = 4
-		const isBoundary = (c: string): boolean => {
-			return c === '<' || c === '>' || c === '"' || c === '}' || c === '{'
-		}
-		const STRETCH = 8
-		for(let i = 0; i < STRETCH && start > 0 && !isBoundary(body[start]); i++) {
-			start--
-		}
+/**
+ * Matcher for a value with no JSON key and no stable xPath anchor: a
+ * content-anchored regex redaction (position-independent) paired with a match
+ * carrying surrounding literal context, so it is never a bare — hence
+ * spoofable — `{{value}}`. When there is genuinely no literal context, the
+ * value-isolating regex itself becomes the (regex-type) match.
+ */
+function contentMatcher(
+	body: string,
+	target: string,
+	paramName: string,
+	valueClass: string,
+	hash?: OprfMode,
+): MatcherSynthesis | undefined {
+	const regex = buildContentRegex(body, target, paramName, valueClass)
+	if(!regex) {
+		return undefined
+	}
-		for(
-			let i = 0;
-			i < STRETCH && end < body.length && !isBoundary(body[end - 1]);
-			i++
-		) {
-			end++
-		}
+	const redaction: ResponseRedaction = { regex }
+	if(hash) {
+		redaction.hash = hash
-		const window = body.slice(start, end)
-		if(window.length < MIN_REVEAL_BYTES) {
-			continue
+		// OPRF needs a `contains {{v}}` match — the attestor substitutes the
+		// nullifier into it (a regex match can't express that). Anchor on the
+		// surrounding literal context so it's never a bare, spoofable `{{v}}`.
+		return {
+			match: {
+				type: 'contains',
+				value: buildContextualTemplate(body, target, paramName),
+			},
+			redaction,
+			paramValues: { [paramName]: target },
 		}
-		return escapeRegex(window)
 	}
-	return undefined
-}
-function escapeRegex(s: string): string {
-	return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+	// The value-isolating regex IS the match: grown to uniquely capture THIS
+	// occurrence, so it's position-independent, self-extracting (the attestor
+	// reads its named group — verification's `extractBareParams` can't grab a
+	// same-shaped earlier occurrence, as a `contains "key":"{{v}}"` would), and
+	// never a bare, spoofable `{{v}}`.
+	return {
+		match: { type: 'regex', value: regex },
+		redaction,
+		paramValues: { [paramName]: target },
+	}
 }
-// ---------------------------------------------------------------------------
-// Capture group regex (only used when hash is requested)
-// ---------------------------------------------------------------------------
-function buildCaptureRegex(
+/**
+ * A value-isolating regex around the first occurrence of `target`, matched by
+ * CONTENT so it reproduces regardless of DOM position: leading literal context
+ * (grown until the first whole-body match captures THIS occurrence) + a
+ * `(?<paramName>valueClass)` group + any trailing delimiter. The revealed span
+ * must CONTAIN the match template (buildContextualTemplate), so the trailing
+ * delimiter is kept unless it's whitespace (which the template also drops).
+ */
+function buildContentRegex(
 	body: string,
 	target: string,
 	paramName: string,
 	valueClass: string,
-): string {
-	const idx = body.indexOf(target)
-	if(idx < 0) {
-		return `(?<${paramName}>${valueClass})`
+): string | undefined {
+	for(const cand of normalizeCandidates(target)) {
+		const idx = body.indexOf(cand)
+		if(idx < 0) {
+			continue
+		}
+		const endIdx = idx + cand.length
+		const rawRight = findRightContext(body, endIdx)
+		const right = /^\s/.test(rawRight) ? '' : escapeRegexFlexWs(rawRight)
+		const baseStart = idx - findLeftContext(body, idx).length
+		for(let start = baseStart; ; start -= CONTEXT_STEP) {
+			const from = Math.max(0, start)
+			const before = escapeRegexFlexWs(body.slice(from, idx))
+			const re = `${before}(?<${paramName}>${valueClass})${right}`
+			try {
+				if(new RegExp(re).exec(body)?.groups?.[paramName] === cand) {
+					return re
+				}
+			} catch{
+				break
+			}
+			if(from === 0) {
+				break
+			}
+		}
 	}
-	const endIdx = idx + target.length
-	const leftCtx = findLeftContext(body, idx)
-	const rightCtx = findRightContext(body, endIdx)
-	// eslint-disable-next-line @stylistic/max-len
-	return `${escapeRegex(leftCtx)}(?<${paramName}>${valueClass})${escapeRegex(rightCtx)}`
+	return undefined
 }
-// ---------------------------------------------------------------------------
-// responseMatches template (literal `contains`, paramValues-substituted)
-// ---------------------------------------------------------------------------
-/** Build the literal substring template for `responseMatches.value` —
- *  the surrounding structural context with the target replaced by
- *  `{{paramName}}`. The attestor substitutes paramValues at proof time
- *  (or the OPRF nullifier, when the matching redaction has `hash`). */
+/**
+ * The literal `contains` template: surrounding structural context with the
+ * value replaced by `{{paramName}}`. Whitespace-adjacent context is dropped (a
+ * literal contains can't flex whitespace); stable context (a JSON key, an HTML
+ * opening tag) is kept so the match anchors on it.
+ */
 function buildContextualTemplate(
 	body: string,
 	target: string,
@@ -553,24 +631,41 @@ function buildContextualTemplate(
 	}
 	const endIdx = idx + target.length
-	const leftCtx = findLeftContext(body, idx)
-	const rightCtx = findRightContext(body, endIdx)
+	const leftCtx = /\s$/.test(findLeftContext(body, idx))
+		? '' : findLeftContext(body, idx)
+	const rightCtx = /^\s/.test(findRightContext(body, endIdx))
+		? '' : findRightContext(body, endIdx)
 	return `${leftCtx}{{${paramName}}}${rightCtx}`
 }
-/** Walk left up to 32 bytes, stopping at the first structural delimiter.
- *  `>` is included (closing of an HTML tag is useful context); `{`, `}`,
- *  `,`, `;`, `\n` are excluded (would over-specify the template). */
+/**
+ * Walk left up to 32 bytes to the nearest meaningful anchor, stopping at the
+ * first structural delimiter. On an HTML tag boundary (`>`) fold in the whole
+ * opening tag — its class/id is the anchor; `>{{value}}<` alone would let a
+ * prover surface the value from any element. A leading run of volatile
+ * whitespace is skipped first so the anchor lands on the tag, not on `\s*`.
+ */
 function findLeftContext(body: string, idx: number): string {
 	const MAX_CONTEXT_BYTES = 32
 	const stop = Math.max(0, idx - MAX_CONTEXT_BYTES)
-	for(let i = idx - 1; i >= stop; i--) {
+	let scan = idx - 1
+	while(scan >= stop && /\s/.test(body[scan] ?? '')) {
+		scan--
+	}
+	for(let i = scan; i >= stop; i--) {
 		const c = body[i]
 		if(c === '>') {
+			const tagStart = body.lastIndexOf('<', i)
+			if(tagStart >= 0 && i - tagStart <= MAX_TAG_BYTES
+				&& body[tagStart + 1] !== '/') {
+				return body.slice(tagStart, idx)
+			}
 			return body.slice(i, idx)
 		}
-		if(c === '{' || c === '}' || c === ',' || c === ';' || c === '\n') {
+		if(c === '{' || c === '}' || c === ',' || c === ';') {
 			return body.slice(i + 1, idx)
 		}
 	}
@@ -584,6 +679,11 @@ function findRightContext(body: string, endIdx: number): string {
 	for(let i = endIdx; i < stop; i++) {
 		const c = body[i]
 		if(c === '<') {
+			const tagEnd = body.indexOf('>', i)
+			if(tagEnd >= 0 && tagEnd - i <= MAX_TAG_BYTES) {
+				return body.slice(endIdx, tagEnd + 1)
+			}
 			return body.slice(endIdx, i + 1)
 		}
@@ -595,15 +695,35 @@ function findRightContext(body: string, endIdx: number): string {
 	return body.slice(endIdx, stop)
 }
+// ---------------------------------------------------------------------------
+// Shared helpers
+// ---------------------------------------------------------------------------
+function escapeRegex(s: string): string {
+	return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+/** Escape `s` as a regex literal but match any run of whitespace flexibly
+ *  (`\s*`): HTML varies inter-token whitespace, so literal whitespace baked
+ *  into a redaction's capture regex would make it miss at proof time. */
+function escapeRegexFlexWs(s: string): string {
+	return s.split(/\s+/).map(escapeRegex).join('\\s*')
+}
 /** Derive a regex character class from the target's shape. Returns
  *  `undefined` for free-form values — those can't be OPRF'd because we
  *  can't write a regex capture that reliably matches arbitrary unicode /
- *  punctuation. Caller should refuse the hash request. */
+ *  punctuation. Caller refuses the hash request. */
 function inferValueClass(target: string): string | undefined {
 	if(/^[0-9]+$/.test(target)) {
 		return '\\d+'
 	}
+	// Numbers with thousands separators / decimals, e.g. "1,908" or "12,345.6".
+	if(/^[0-9][0-9,.]*[0-9]$/.test(target)) {
+		return '[0-9,.]+'
+	}
 	if(/^[A-Za-z0-9_-]+$/.test(target)) {
 		return '[A-Za-z0-9_-]+'
 	}