@reclaimprotocol/agent 0.1.10 → 0.1.12

package/src/provider/dom-xpath.ts

@@ -18,6 +18,104 @@ import '../proof/patch-domhandler.ts'
 const IDENT_ATTRS =
 	['name', 'property', 'itemprop', 'data-testid', 'rel', 'for']
 
+/** What an xPath candidate anchors on — used to weight its base stability. */
+type AnchorKind = 'ident-attr' | 'id' | 'class' | 'positional'
+
+/** One verified xPath option for the target element, tagged with what it
+ *  anchors on so it can be scored for FUTURE stability (see
+ *  {@link anchorStability}) rather than just "first that resolves". */
+interface Candidate {
+	xPath: string
+	kind: AnchorKind
+	/** The identifier the anchor keys on (an id / attr / class value); undefined
+	 *  for a purely positional path. */
+	token?: string
+	/** Ancestor distance from the value element (0 = the element itself or a
+	 *  direct-child anchor); larger = higher up. Tie-break nudge only. */
+	depth: number
+}
+
+/** Base weight by anchor kind: purpose-built test hooks and ids beat classes,
+ *  which beat a positional path. Modulated by {@link tokenQuality}. */
+const TYPE_WEIGHT: Record<AnchorKind, number> = {
+	'ident-attr': 0.95,
+	id: 0.9,
+	class: 0.6,
+	positional: 0.3,
+}
+
+const UUID_RE =
+	/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+/**
+ * How likely an identifier token is to survive a future render, by its SHAPE —
+ * framework-agnostic, so it catches generated ids/classes from any tool (this
+ * year's or next) without naming them. Returns `[0.02, 1]`.
+ *
+ * Volatile shapes (machine-generated): a `:` (React `useId` `:r1:`, Radix), a
+ * UUID, digit-heavy or trailing-digit tokens (`ember123`, `tab-2`), hex/hash
+ * runs (`css-1a2b3c`), or opaque wordless strings. Durable shapes (human
+ * authored): real word segments, kebab/snake of words (`settings-header`,
+ * `primary_email_select`).
+ */
+function tokenQuality(token: string): number {
+	const t = token.trim()
+	if(!t) {
+		return 0.3
+	}
+
+	// Kill signals — these tokens are (almost) always per-render generated.
+	if(t.includes(':') || UUID_RE.test(t)) {
+		return 0.05
+	}
+
+	let q = 1
+	const len = t.length
+	const digits = (t.match(/\d/g) ?? []).length
+	const digitRatio = digits / len
+	// A trailing digit run after letters is the classic generated-id tail.
+	if(/[A-Za-z][-_]?\d+$/.test(t)) {
+		q *= 0.3
+	}
+
+	if(digitRatio > 0.3) {
+		q *= 0.4
+	} else if(digitRatio > 0.15) {
+		q *= 0.7
+	}
+
+	// A pure hex/short-hash run (`1a2b3c`, `deadbeef`) — no semantic content.
+	if(/^[0-9a-f]{6,}$/i.test(t)) {
+		q *= 0.15
+	}
+
+	// A real word — an alpha run ≥3 that ITSELF contains a vowel — is the
+	// strongest durability signal; its absence means the token is opaque /
+	// hash-like (`css-1a2b3c`, `sc-bdfBwQ`). Checking per-segment matters: a
+	// stray vowel elsewhere in a hash must not count as "has a word".
+	const hasWord = (t.match(/[A-Za-z]+/g) ?? [])
+		.some((run) => run.length >= 3 && /[aeiou]/i.test(run))
+	if(!hasWord) {
+		q *= 0.3
+	}
+
+	if(len > 40) {
+		q *= 0.6
+	}
+
+	return Math.max(0.02, Math.min(1, q))
+}
+
+/** Stability score for a candidate: base weight for its kind × the shape
+ *  quality of its identifier, minus a small depth nudge so a nearer/shorter
+ *  anchor wins an otherwise-tie. Positional paths score on kind alone. */
+function anchorStability(c: Candidate): number {
+	const base = TYPE_WEIGHT[c.kind]
+	const quality = c.kind === 'positional' ? 1 : tokenQuality(c.token ?? '')
+	const depthNudge = 1 - Math.min(c.depth, 8) * 0.01
+	return base * quality * depthNudge
+}
+
 export interface DomAnchor {
 	xPath: string
 	/** Byte range of the element in the source html (parse5 source locations),
@@ -61,15 +159,25 @@ export function elementAnchor(
 		return undefined
 	}
 
-	for(const candidate of candidateXPaths(el)) {
-		if(matchesUniquely(doc, candidate, el)) {
-			// `[startIndex, endIndex)` is exactly the slice the attestor reveals for
-			// this xPath (its getNodeRange uses these same parse5 source locations).
-			return { xPath: candidate, start: startIndex, end: endIndex }
-		}
+	// Score EVERY candidate that provably resolves (first-match, uniquely) to the
+	// target, and take the most durable — not merely the first that resolves.
+	// Because each survivor already matches uniquely NOW, the choice only trades
+	// on FUTURE stability; it can never pick a wrong/non-resolving node.
+	const verified = [...candidateXPaths(el)]
+		.map((c, i) => ({ c, i }))
+		.filter(({ c }) => matchesUniquely(doc, c.xPath, el))
+	if(!verified.length) {
+		return undefined
 	}
 
-	return undefined
+	verified.sort((a, b) => {
+		return anchorStability(b.c) - anchorStability(a.c) ||
+			a.c.depth - b.c.depth ||
+			a.i - b.i
+	})
+	// `[startIndex, endIndex)` is exactly the slice the attestor reveals for this
+	// xPath (its getNodeRange uses these same parse5 source locations).
+	return { xPath: verified[0].c.xPath, start: startIndex, end: endIndex }
 }
 
 /** The tightest element that DIRECTLY holds a target. Prefers a COMPLETE-value
@@ -121,34 +229,29 @@ function smallestElement(els: Element[]): Element | undefined {
 		.at(0)
 }
 
-/** Candidate xPaths for `el`, best (most stable / shortest) first. */
-function* candidateXPaths(el: Element): Generator<string> {
+/** Every candidate xPath for `el`, each tagged with what it anchors on. The
+ *  caller verifies + scores them ({@link anchorStability}) rather than trusting
+ *  emission order, so the DURABILITY winner is chosen, not the first that
+ *  resolves. Order here is only the final tie-break. */
+function* candidateXPaths(el: Element): Generator<Candidate> {
 	const tag = el.name
 	const a = el.attribs ?? {}
 	if(a.id) {
-		yield `//${tag}[@id=${xpathLiteral(a.id)}]`
+		yield { xPath: `//${tag}[@id=${xpathLiteral(a.id)}]`, kind: 'id',
+			token: a.id, depth: 0 }
 	}
 
 	for(const name of IDENT_ATTRS) {
 		if(a[name]) {
-			yield `//${tag}[@${name}=${xpathLiteral(a[name])}]`
-		}
-	}
-
-	if(a.class) {
-		const distinctive = a.class
-			.split(/\s+/)
-			.filter(Boolean)
-			.sort((x, y) => y.length - x.length)[0]
-		if(distinctive) {
-			yield `//${tag}[contains(@class, ${xpathLiteral(distinctive)})]`
+			yield { xPath: `//${tag}[@${name}=${xpathLiteral(a[name])}]`,
+				kind: 'ident-attr', token: a[name], depth: 0 }
 		}
 	}
 
 	// A uniquely-identified DIRECT child pins the parent without a positional
-	// path (`//span[span[@id="labels"]]`). Self-verification (firstSelected)
-	// 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.
+	// 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.
 	for(const child of el.children) {
 		if(!isTag(child)) {
 			continue
@@ -156,17 +259,114 @@ function* candidateXPaths(el: Element): Generator<string> {
 
 		const ca = child.attribs ?? {}
 		if(ca.id) {
-			yield `//${tag}[${child.name}[@id=${xpathLiteral(ca.id)}]]`
+			yield { xPath: `//${tag}[${child.name}[@id=${xpathLiteral(ca.id)}]]`,
+				kind: 'id', token: ca.id, depth: 0 }
 		}
 
 		for(const name of IDENT_ATTRS) {
 			if(ca[name]) {
-				yield `//${tag}[${child.name}[@${name}=${xpathLiteral(ca[name])}]]`
+				yield {
+					xPath: `//${tag}[${child.name}[@${name}=${xpathLiteral(ca[name])}]]`,
+					kind: 'ident-attr', token: ca[name], depth: 0,
+				}
+			}
+		}
+	}
+
+	// The value element's own distinctive class.
+	const distinctive = distinctiveClass(a.class)
+	if(distinctive) {
+		yield { xPath: `//${tag}[contains(@class, ${xpathLiteral(distinctive)})]`,
+			kind: 'class', token: distinctive, depth: 0 }
+	}
+
+	// Ancestor-anchored (id/attr, then class), descending positionally to `el`.
+	yield* ancestorAnchoredCandidates(el)
+
+	yield { xPath: absolutePath(el), kind: 'positional', depth: 99 }
+}
+
+/** The longest whitespace-delimited token of a class attribute (the most
+ *  distinctive one), or undefined when there's no class. */
+function distinctiveClass(cls: string | undefined): string | undefined {
+	return (cls ?? '')
+		.split(/\s+/)
+		.filter(Boolean)
+		.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`. */
+function relativeSteps(anc: Element, el: Element): string {
+	const parts: string[] = []
+	let node: Node | null = el
+	while(node && isTag(node) && node !== anc) {
+		const tag = node.name
+		let index = 1
+		for(let sib = node.prev; sib; sib = sib.prev) {
+			if(isTag(sib) && sib.name === tag) {
+				index++
 			}
 		}
+
+		parts.unshift(`/${tag}[${index}]`)
+		node = node.parent
 	}
 
-	yield absolutePath(el)
+	return node === anc ? parts.join('') : ''
+}
+
+/** Ancestors of `el` (nearest first) with their depth, skipping
+ *  `html`/`body`/`head` (≈ the absolute path) and non-ancestors. Capped depth
+ *  keeps paths short. */
+function* anchorAncestors(el: Element): Generator<{
+	tag: string
+	attribs: Record<string, string>
+	rel: string
+	depth: number
+}> {
+	let depth = 1
+	for(
+		let anc: Node | null = el.parent;
+		anc && isTag(anc) && depth <= 10;
+		anc = anc.parent, depth++
+	) {
+		const tag = anc.name
+		if(tag === 'html' || tag === 'body' || tag === 'head') {
+			continue
+		}
+
+		const rel = relativeSteps(anc, el)
+		if(rel) {
+			yield { tag, attribs: anc.attribs ?? {}, rel, depth }
+		}
+	}
+}
+
+/** Ancestor-anchored candidates, descending positionally to `el`
+ *  (`//div[@id="nav"]/ul[1]/li[1]/a[1]`): an id / identifying-attr or a
+ *  distinctive-class anchor per ancestor, tagged with its kind + depth so the
+ *  scorer weighs a stable ancestor id above the value's own utility class. */
+function* ancestorAnchoredCandidates(el: Element): Generator<Candidate> {
+	for(const { tag, attribs, rel, depth } of anchorAncestors(el)) {
+		if(attribs.id) {
+			yield { xPath: `//${tag}[@id=${xpathLiteral(attribs.id)}]${rel}`,
+				kind: 'id', token: attribs.id, depth }
+		}
+
+		for(const name of IDENT_ATTRS) {
+			if(attribs[name]) {
+				const xp = `//${tag}[@${name}=${xpathLiteral(attribs[name])}]${rel}`
+				yield { xPath: xp, kind: 'ident-attr', token: attribs[name], depth }
+			}
+		}
+
+		const dc = distinctiveClass(attribs.class)
+		if(dc) {
+			yield { xPath: `//${tag}[contains(@class, ${xpathLiteral(dc)})]${rel}`,
+				kind: 'class', token: dc, depth }
+		}
+	}
 }
 
 /** Chrome "full XPath"-style absolute path: `/html[1]/body[1]/…/tag[n]`, where

package/src/provider/draft.ts

@@ -1,4 +1,4 @@
-import { synthesizeMatcher } from './matcher.ts'
+import { isOprfHashable, OPRF_MAX_BYTES, synthesizeMatcher } from './matcher.ts'
 import type {
 	CapturedRequest,
 	OprfMode,
@@ -9,6 +9,39 @@ import type {
 } from './schema.ts'
 import { splitSecrets } from './secrets.ts'
 
+/** OPRF mode for the auto-hash floor — TEE-native (attestor rejects oprf-raw,
+ *  isn't set up for gnark oprf). */
+const DEFAULT_SENSITIVE_HASH: OprfMode = 'oprf-mpc'
+
+// The deterministic ANTI-LEAK FLOOR: values whose SHAPE is unambiguously
+// sensitive PII, force-hashed no matter the field name or the model's judgment.
+// Deliberately only FIXED-FORMAT identifiers — OPRF is byte-exact, so a
+// self-mutable value (a display name re-cased) would be grindable and pointless
+// to hash; and a bare number is ambiguous (a private account id vs a PUBLIC
+// user id / follower count that's meant to be proven in the clear). Those
+// contextual calls are the model's, via an explicit per-target `hash`. This
+// floor is universal (not domain-specific) and high-precision.
+const EMAIL_VALUE = /^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$/
+const SSN_VALUE = /^\d{3}-\d{2}-\d{4}$/
+const IBAN_VALUE = /^[A-Z]{2}\d{2}[A-Z0-9]{11,30}$/
+
+function isCanonicalPii(value: string): boolean {
+	return EMAIL_VALUE.test(value)
+		|| SSN_VALUE.test(value) || IBAN_VALUE.test(value)
+}
+
+/** OPRF mode to apply when the caller passed none: the anti-leak floor —
+ *  force-hash a value whose SHAPE is unambiguous PII, but ONLY when it's
+ *  OPRF-hashable AND within the 62-byte MPC-circuit cap (UTF-8). Undefined =
+ *  leave plaintext (a longer value can't be OPRF'd; contextual PII + the proven
+ *  identity are the model's/plaintext call). */
+export function defaultSensitiveHash(value: string): OprfMode | undefined {
+	const hashable = isCanonicalPii(value)
+		&& isOprfHashable(value)
+		&& Buffer.byteLength(value, 'utf8') <= OPRF_MAX_BYTES
+	return hashable ? DEFAULT_SENSITIVE_HASH : undefined
+}
+
 /** One value to extract from the request: the captured `value`, a `name` (its
  *  param / capture-group), and an optional per-target OPRF `hash`. */
 export interface DraftTarget {
@@ -33,7 +66,7 @@ export interface DraftResult {
 	extractions: Extraction[]
 }
 
-/** Request headers that must NOT survive into the provider params. Two kinds:
+/** 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
@@ -41,7 +74,14 @@ export interface DraftResult {
  *  - 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). */
+ *    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',
@@ -50,8 +90,17 @@ const STRIP_REQUEST_HEADERS = new Set([
 	'if-range',
 	'connection',
 	'accept-encoding',
+	'host',
+	'content-length',
+	'transfer-encoding',
 ])
 
+/** 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(':')
+}
+
 /** 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. */
@@ -60,7 +109,7 @@ function sanitizeRequestHeaders(
 ): Record<string, string> {
 	const out: Record<string, string> = {}
 	for(const [k, v] of Object.entries(headers)) {
-		if(STRIP_REQUEST_HEADERS.has(k.toLowerCase())) {
+		if(STRIP_REQUEST_HEADERS.has(k.toLowerCase()) || isPseudoHeader(k)) {
 			continue
 		}
 
@@ -167,12 +216,17 @@ export function draftProvider(
 		}
 
 		seenParams.add(paramName)
+		// 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)
+		// via an explicit per-target hash; this floor only guarantees the obvious.
+		const effectiveHash = t.hash ?? hash ?? defaultSensitiveHash(t.value)
 		const synthesis = synthesizeMatcher(
 			req.responseBody,
 			req.contentType,
 			t.value,
 			paramName,
-			t.hash ?? hash,
+			effectiveHash,
 		)
 		if(!synthesis) {
 			throw new Error(

package/src/provider/matcher.ts

@@ -734,3 +734,10 @@ function inferValueClass(target: string): string | undefined {
 
 	return undefined
 }
+
+/** True when `target` has a character class safe to OPRF-hash. Free-form values
+ *  (names with spaces, arbitrary unicode/punctuation) return false — the caller
+ *  must NOT default them to a hash (it would throw in synthesizeMatcher). */
+export function isOprfHashable(target: string): boolean {
+	return inferValueClass(target) !== undefined
+}

package/src/provider/to-version.ts

@@ -37,6 +37,19 @@ export interface AllowedJsRequest extends DraftRequest {
 	multiple?: boolean
 	/** Fail validation if no request matches this template. Default true. */
 	required?: boolean
+	/** Names of `${var}` placeholders in this template's `responseMatches`/
+	 *  `responseRedactions` that get substituted at verify time from the
+	 *  submitted proof's own witness params (e.g. an index list a
+	 *  `Reclaim.requestClaim` call attached alongside its `{{var}}`
+	 *  extractions). Omit (or leave empty) when the template has no such
+	 *  placeholders — verification then matches it literally as-is. */
+	templateParams?: string[]
+	/** How multiple values for `templateParams` expand into request specs.
+	 *  `'separate'` (default): one independent spec per value, each expected
+	 *  to match its own proof. `'merge'`: all values folded into ONE spec
+	 *  with one `responseMatches`/`responseRedactions` entry per value,
+	 *  matching a single proof that bundles them all into one claim. */
+	templateParamsMode?: 'separate' | 'merge'
 }
 
 /** Optional extras for a create-version body beyond the request list. */

package/src/old/tools/get-version-config.ts

@@ -1,56 +0,0 @@
-import { defineTool, type RegisteredTool } from '../../mcp/server.ts'
-import type { ReclaimOldClient } from '../client.ts'
-
-/**
- * Read the full `providerConfig` (loginUrl, customInjection, requestData,
- * geoLocation, ...) of one provider version on the old devtools backend —
- * the latest version when `version` is omitted.
- *
- * Exists so a dev/agent can see what's CURRENTLY published before adding a
- * new version with `create_provider_version_from_capture`. That tool always
- * takes a FULL replacement `providerConfig` (no partial-patch endpoint on
- * this backend), so a version added without knowing the current
- * `customInjection` would silently publish it blank — wiping a working
- * login script instead of preserving it. Read it here first, then pass it
- * straight through (or omit `customInjection` on publish to have it carried
- * forward automatically).
- */
-export function getProviderVersionConfigTool(
-	client: ReclaimOldClient,
-): RegisteredTool {
-	return defineTool<{ providerId: string, version?: string }>(
-		{
-			name: 'get_provider_version_config',
-			description:
-				'Fetch the full providerConfig (loginUrl, customInjection, ' +
-				'requestData, geoLocation, ...) of one version on the old devtools ' +
-				'backend — the latest version when `version` is omitted. Readable ' +
-				'for any non-archived provider, not just ones you own. Use this ' +
-				'BEFORE calling create_provider_version_from_capture with a ' +
-				'`providerId` to see the currently-published customInjection/' +
-				'requestData so you know what you would be changing — that tool ' +
-				'replaces the whole providerConfig, so a field you never see and ' +
-				"never pass comes out blank in the new version, even if it's set " +
-				'today.',
-			inputSchema: {
-				type: 'object',
-				properties: {
-					providerId: {
-						type: 'string',
-						description: 'UUID of the provider (from get_me_providers).',
-					},
-					version: {
-						type: 'string',
-						description:
-							'Specific version to fetch, e.g. "1.0.2". Omit for the ' +
-							"provider's current latest version.",
-					},
-				},
-				required: ['providerId'],
-			},
-		},
-		async({ providerId, version }) => {
-			return client.getProviderConfig(providerId, version)
-		},
-	)
-}