@reclaimprotocol/agent 0.1.0-dev.1

package/src/provider/matcher.ts

@@ -0,0 +1,616 @@
+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. */
+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. */
+	paramValues?: Record<string, string>
+}
+
+/**
+ * Build the matcher pieces (responseMatches + responseRedactions +
+ * paramValues) for a target value seen in a captured response.
+ *
+ * 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
+ *
+ * `hash` is opt-in. The skill prompts the dev. Drafting without `hash`
+ * is the default — the value travels in cleartext to the attestor.
+ *
+ * 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.
+ */
+export function synthesizeMatcher(
+	body: string,
+	contentType: string,
+	target: string,
+	paramName: string,
+	hash?: OprfMode,
+): MatcherSynthesis | undefined {
+	if(
+		!body.includes(target) &&
+		!normalizeCandidates(target).some((v) => body.includes(v))
+	) {
+		return undefined
+	}
+
+	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`.',
+		)
+	}
+
+	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
+		}
+
+		return makeResult(body, target, paramName, redaction)
+	}
+
+	if(pick) {
+		return makeResult(body, target, paramName, pick.redaction)
+	}
+
+	// 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 })
+	}
+
+	const padded = buildPaddedRegex(body, target)
+	if(padded) {
+		return makeResult(body, target, paramName, { regex: padded })
+	}
+
+	return undefined
+}
+
+function makeResult(
+	body: string,
+	target: string,
+	paramName: string,
+	redaction: ResponseRedaction,
+): MatcherSynthesis {
+	return {
+		match: {
+			type: 'contains',
+			value: buildContextualTemplate(body, target, paramName),
+		},
+		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
+}
+
+function pickAnchor(
+	body: string,
+	contentType: string,
+	target: string,
+): AnchorPick | undefined {
+	if(/json/i.test(contentType)) {
+		const jsonPath = findJsonPath(body, target)
+		if(jsonPath) {
+			return { redaction: { jsonPath } }
+		}
+	}
+
+	if(/html|xml/i.test(contentType) || looksLikeHtml(body)) {
+		const xPath = synthesizeXPath(body, target)
+		if(xPath) {
+			return {
+				redaction: { xPath: xPath.xPath },
+				elementBytes: xPath.elementBytes,
+			}
+		}
+	}
+
+	return undefined
+}
+
+// ---------------------------------------------------------------------------
+// JSON helpers
+// ---------------------------------------------------------------------------
+
+function findJsonPath(body: string, target: string): string | undefined {
+	let parsed: unknown
+	try {
+		parsed = JSON.parse(body)
+	} catch{
+		return undefined
+	}
+
+	const candidates = normalizeCandidates(target)
+	return walk(parsed, '$', candidates)
+}
+
+function walk(
+	node: unknown,
+	path: string,
+	candidates: string[],
+): string | undefined {
+	if(node === null || node === undefined) {
+		return undefined
+	}
+
+	if(
+		typeof node === 'string' ||
+		typeof node === 'number' ||
+		typeof node === 'boolean'
+	) {
+		const str = String(node)
+		if(candidates.includes(str)) {
+			return path
+		}
+
+		return undefined
+	}
+
+	if(Array.isArray(node)) {
+		for(const [i, element] of node.entries()) {
+			const found = walk(element, `${path}[${i}]`, candidates)
+			if(found) {
+				return found
+			}
+		}
+
+		return undefined
+	}
+
+	if(typeof node === 'object') {
+		for(const [k, v] of Object.entries(node as Record<string, unknown>)) {
+			const childPath = /^[A-Za-z_][A-Za-z0-9_]*$/.test(k)
+				? `${path}.${k}`
+				: `${path}["${k}"]`
+			const found = walk(v, childPath, candidates)
+			if(found) {
+				return found
+			}
+		}
+	}
+
+	return undefined
+}
+
+// ---------------------------------------------------------------------------
+// HTML helpers
+// ---------------------------------------------------------------------------
+
+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(
+	body: string,
+	target: string,
+): { xPath: string, elementBytes: number } | undefined {
+	for(const variant of normalizeCandidates(target)) {
+		const idx = body.indexOf(variant)
+		if(idx < 0) {
+			continue
+		}
+
+		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,
+			)
+			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
+}
+
+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
+		}
+
+		if(parent.closeEnd - parent.openStart > MAX_ANCHOR_CLIMB_BYTES) {
+			return undefined
+		}
+
+		if(parent.id || parent.classes.length > 0) {
+			return parent
+		}
+
+		cur = parent
+	}
+}
+
+function findEnclosingElement(
+	body: 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
+}
+
+function buildXPath(el: EnclosingElement, body: string): string {
+	if(el.id) {
+		return `//${el.tag}[@id=${xpathLiteral(el.id)}]`
+	}
+
+	if(el.classes.length > 0) {
+		const distinctive = [...el.classes].sort((a, b) => b.length - a.length)[0]
+		return `//${el.tag}[contains(@class, ${xpathLiteral(distinctive)})]`
+	}
+
+	return `(//${el.tag})[${tagIndex(body, el)}]`
+}
+
+function tagIndex(body: string, el: EnclosingElement): number {
+	const pattern = new RegExp(`<${el.tag}\\b`, 'gi')
+	let n = 0
+	let m: RegExpExecArray | null
+	while((m = pattern.exec(body)) !== null) {
+		if(m.index > el.openStart) {
+			break
+		}
+
+		n++
+	}
+
+	return n
+}
+
+/** 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}"`
+	}
+
+	if(!s.includes("'")) {
+		return `'${s}'`
+	}
+
+	const parts = s.split('"').map((p) => `"${p}"`)
+	return `concat(${parts.join(', \'"\', ')})`
+}
+
+// ---------------------------------------------------------------------------
+// Padded-regex fallback for non-JSON, non-HTML content
+// ---------------------------------------------------------------------------
+
+function buildPaddedRegex(body: string, target: string): string | undefined {
+	for(const cand of normalizeCandidates(target)) {
+		const idx = body.indexOf(cand)
+		if(idx < 0) {
+			continue
+		}
+
+		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)
+			}
+		}
+
+		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--
+		}
+
+		for(
+			let i = 0;
+			i < STRETCH && end < body.length && !isBoundary(body[end - 1]);
+			i++
+		) {
+			end++
+		}
+
+		const window = body.slice(start, end)
+		if(window.length < MIN_REVEAL_BYTES) {
+			continue
+		}
+
+		return escapeRegex(window)
+	}
+
+	return undefined
+}
+
+function escapeRegex(s: string): string {
+	return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+// ---------------------------------------------------------------------------
+// Capture group regex (only used when hash is requested)
+// ---------------------------------------------------------------------------
+
+function buildCaptureRegex(
+	body: string,
+	target: string,
+	paramName: string,
+	valueClass: string,
+): string {
+	const idx = body.indexOf(target)
+	if(idx < 0) {
+		return `(?<${paramName}>${valueClass})`
+	}
+
+	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)}`
+}
+
+// ---------------------------------------------------------------------------
+// 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`). */
+function buildContextualTemplate(
+	body: string,
+	target: string,
+	paramName: string,
+): string {
+	const idx = body.indexOf(target)
+	if(idx < 0) {
+		return `{{${paramName}}}`
+	}
+
+	const endIdx = idx + target.length
+	const leftCtx = findLeftContext(body, idx)
+	const rightCtx = 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). */
+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--) {
+		const c = body[i]
+		if(c === '>') {
+			return body.slice(i, idx)
+		}
+
+		if(c === '{' || c === '}' || c === ',' || c === ';' || c === '\n') {
+			return body.slice(i + 1, idx)
+		}
+	}
+
+	return body.slice(stop, idx)
+}
+
+function findRightContext(body: string, endIdx: number): string {
+	const MAX_CONTEXT_BYTES = 16
+	const stop = Math.min(body.length, endIdx + MAX_CONTEXT_BYTES)
+	for(let i = endIdx; i < stop; i++) {
+		const c = body[i]
+		if(c === '<') {
+			return body.slice(endIdx, i + 1)
+		}
+
+		if(c === '{' || c === '}' || c === ',' || c === ';' || c === '\n') {
+			return body.slice(endIdx, i)
+		}
+	}
+
+	return body.slice(endIdx, stop)
+}
+
+/** 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. */
+function inferValueClass(target: string): string | undefined {
+	if(/^[0-9]+$/.test(target)) {
+		return '\\d+'
+	}
+
+	if(/^[A-Za-z0-9_-]+$/.test(target)) {
+		return '[A-Za-z0-9_-]+'
+	}
+
+	if(/^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$/.test(target)) {
+		return '[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}'
+	}
+
+	return undefined
+}

package/src/provider/normalize.ts

@@ -0,0 +1,65 @@
+/** Return all string variants of `value` that might appear in a response
+ *  body. Used by find_requests_containing to do server-side substring search
+ *  without forcing the caller to guess the encoding. */
+export function normalizeCandidates(value: string): string[] {
+	const out = new Set<string>()
+	const trimmed = value.trim()
+	out.add(trimmed)
+
+	const asciiDigits = toAsciiDigits(trimmed)
+	if(asciiDigits !== trimmed) {
+		out.add(asciiDigits)
+	}
+
+	// Comma-grouped numbers: "1,247" -> "1247"
+	const dedup = asciiDigits.replace(/,/g, '')
+	if(dedup !== asciiDigits) {
+		out.add(dedup)
+	}
+
+	// k/M/B-suffixed display numbers: "1.2k" -> integer range
+	const suffixMatch = asciiDigits.match(/^(\d+(?:\.\d+)?)\s*([kKmMbB])$/)
+	if(suffixMatch) {
+		const base = parseFloat(suffixMatch[1])
+		const mult = { k: 1e3, K: 1e3, m: 1e6, M: 1e6, b: 1e9, B: 1e9 }[
+			suffixMatch[2]
+		]!
+		const center = base * mult
+		// Display rounds: "1.2k" came from anything 1150..1249.
+		const window = mult / 10 ** (suffixMatch[1].split('.')[1]?.length ?? 0) / 2
+		for(
+			let n = Math.ceil(center - window);
+			n < Math.ceil(center + window);
+			n++
+		) {
+			out.add(String(n))
+		}
+	}
+
+	// JSON-encoded + percent-encoded variants of every existing candidate.
+	for(const c of [...out]) {
+		out.add(JSON.stringify(c))
+		out.add(encodeURIComponent(c))
+		out.add(encodeURIComponent(JSON.stringify(c)))
+	}
+
+	return [...out]
+}
+
+function toAsciiDigits(s: string): string {
+	return s.replace(/[\p{Nd}]/gu, (ch) => {
+		const code = ch.codePointAt(0)!
+		// Find the zero of this digit's block: digit value = code - blockZero.
+		// Walk back at most 9 codepoints to find it.
+		for(let i = 0; i <= 9; i++) {
+			const candidate = String.fromCodePoint(code - i)
+			if(/^\p{Nd}$/u.test(candidate)) {
+				continue
+			}
+
+			return String(i - 1)
+		}
+
+		return ch
+	})
+}