npm - @reclaimprotocol/agent - Versions diffs - 0.1.4 → 0.1.6 - Mend

@reclaimprotocol/agent 0.1.4 → 0.1.6

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 (126) hide show

package/README.md +5 -5
package/lib/authoring/backend.d.ts +71 -0
package/lib/authoring/backend.js +24 -0
package/lib/authoring/find.d.ts +3 -0
package/lib/authoring/find.js +54 -0
package/lib/authoring/index.d.ts +4 -0
package/lib/authoring/index.js +6 -0
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 +16 -0
package/lib/authoring/tools.js +193 -0
package/lib/authoring/util.d.ts +27 -0
package/lib/authoring/util.js +21 -0
package/lib/cdp/capture-engine.js +1 -1
package/lib/consts.d.ts +6 -1
package/lib/consts.js +9 -2
package/lib/mcp/api/operations.gen.js +46 -18
package/lib/mcp/server.d.ts +2 -25
package/lib/mcp/server.js +4 -17
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/publish.js +2 -2
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 +8 -0
package/lib/mcp/tools/agent/shared.js +125 -0
package/lib/old/client.d.ts +35 -0
package/lib/old/client.js +18 -0
package/lib/old/login-cdp.d.ts +24 -0
package/lib/old/login-cdp.js +28 -3
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 +52 -2
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 +189 -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/proof-core.d.ts +1 -1
package/lib/proof/proof-core.js +1 -1
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 +50 -0
package/lib/tools/registry.js +49 -0
package/package.json +9 -1
package/skill/SKILL.builder.md +55 -32
package/skill/SKILL.old.md +20 -12
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/cdp/capture-engine.ts +1 -1
package/src/consts.ts +15 -2
package/src/mcp/api/operations.gen.ts +46 -18
package/src/mcp/server.ts +9 -39
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/publish.ts +2 -2
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 +56 -0
package/src/old/login-cdp.ts +28 -3
package/src/old/sdk-client.ts +105 -0
package/src/old/to-register.ts +98 -6
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 +244 -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/proof-core.ts +1 -1
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/lib/provider/matcher.js CHANGED Viewed

@@ -1,53 +1,26 @@
+import { elementAnchor } from "./dom-xpath.js";
 import { normalizeCandidates } from "./normalize.js";
-/**
- * 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;
 /**
- * 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, contentType, target, paramName, hash) {
     if (!body.includes(target) &&
@@ -55,78 +28,135 @@ export function synthesizeMatcher(body, contentType, target, paramName, hash) {
         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 = {
-            ...pick.redaction,
-            regex: captureRegex,
-        };
-        if (hash) {
-            redaction.hash = hash;
+        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 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);
     }
-    if (pick) {
-        return makeResult(body, target, paramName, pick.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;
+        }
     }
-    // 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 });
+    // 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) {
+    const head = body.trimStart()[0];
+    if (head !== '{' && head !== '[') {
+        return false;
     }
-    const padded = buildPaddedRegex(body, target);
-    if (padded) {
-        return makeResult(body, target, paramName, { regex: padded });
+    try {
+        JSON.parse(body);
+        return true;
     }
-    return undefined;
+    catch {
+        return false;
+    }
+}
+/** Index of `target` (or an encoding variant) in `text`, with the matched
+ *  variant. `{ idx: -1 }` when absent. */
+function firstIndex(text, target) {
+    for (const value of [target, ...normalizeCandidates(target)]) {
+        const idx = text.indexOf(value);
+        if (idx >= 0) {
+            return { idx, value };
+        }
+    }
+    return { idx: -1, value: target };
 }
-function makeResult(body, target, paramName, redaction) {
+/**
+ * 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, close, target, paramName, valueClass, selector, hash) {
+    const redaction = {
+        ...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 },
     };
 }
-function pickAnchor(body, contentType, target) {
-    if (/json/i.test(contentType)) {
-        const jsonPath = findJsonPath(body, target);
-        if (jsonPath) {
-            return { redaction: { jsonPath } };
-        }
+// ---------------------------------------------------------------------------
+// JSON: "key": value  →  jsonPath redaction + `contains "key":"{{v}}"`
+// ---------------------------------------------------------------------------
+/**
+ * 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, target, paramName, valueClass, hash) {
+    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);
+}
+/**
+ * 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, target) {
+    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 ? '"' : '' };
 }
-// ---------------------------------------------------------------------------
-// JSON helpers
-// ---------------------------------------------------------------------------
 function findJsonPath(body, target) {
     let parsed;
     try {
@@ -173,232 +203,296 @@ function walk(node, path, candidates) {
     }
     return undefined;
 }
+// ---------------------------------------------------------------------------
+// HTML: element  →  xPath redaction + `contains "<tag …>{{v}}</tag>"`
+// ---------------------------------------------------------------------------
 function looksLikeHtml(body) {
     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, target) {
-    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,
-        };
+/**
+ * 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, target, paramName, valueClass, hash) {
+    const anchor = elementAnchor(body, [target, ...normalizeCandidates(target)]);
+    if (!anchor) {
+        return undefined;
     }
-    return undefined;
-}
-function climbForAnchor(body, el) {
-    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;
+    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);
         }
-        cur = parent;
     }
+    return elementResult(anchor.xPath, revealSlice, target, paramName, valueClass, hash);
 }
-function findEnclosingElement(body, valueIdx, valueLen) {
-    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 = {
-            tag: tagName,
-            openStart: tagStart,
-            closeEnd,
-            classes,
-        };
-        if (idMatch?.[1] !== undefined) {
-            el.id = idMatch[1];
-        }
-        return el;
+/**
+ * `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, markup, target, paramName, valueClass, hash) {
+    const { idx, value } = firstIndex(markup, target);
+    if (idx < 0) {
+        return undefined;
     }
-    return undefined;
+    const { left, right } = portableWindow(markup, idx, value.length);
+    const redaction = {
+        xPath,
+        regex: `${escapeRegexFlexWs(left)}(?<${paramName}>${valueClass})`
+            + escapeRegexFlexWs(right),
+    };
+    if (hash) {
+        redaction.hash = hash;
+    }
+    return {
+        match: { type: 'contains', value: `${left}{{${paramName}}}${right}` },
+        redaction,
+        paramValues: { [paramName]: target },
+    };
 }
-function buildXPath(el, body) {
-    if (el.id) {
-        return `//${el.tag}[@id=${xpathLiteral(el.id)}]`;
+/** 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, valueIdx, valueLen) {
+    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);
+}
+/** 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, valueIdx, valueEnd, openTagGt) {
+    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, el) {
-    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, valueIdx, valueEnd, openTagStart) {
+    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;
-    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) {
-    if (!s.includes('"')) {
-        return `"${s}"`;
-    }
-    if (!s.includes("'")) {
-        return `'${s}'`;
-    }
-    const parts = s.split('"').map((p) => `"${p}"`);
-    return `concat(${parts.join(', \'"\', ')})`;
+/** 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) {
+    const attrRe = /\s+([a-zA-Z][\w:-]*)(\s*=\s*("[^"]*"|'[^']*'|[^\s>]*))?/g;
+    let cut = -1;
+    let m;
+    while ((m = attrRe.exec(openTag)) !== null) {
+        if (!STABLE_ATTRS.has(m[1].toLowerCase())) {
+            cut = m.index + m[0].length;
+        }
+    }
+    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) {
+    const match = /^<script\b[^>]*>([\s\S]*)<\/script>\s*$/i.exec(markup);
+    if (!match) {
+        return undefined;
+    }
+    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, target) {
+/** Longest opening/closing HTML tag folded into the match context. */
+const MAX_TAG_BYTES = 256;
+/** Bytes the left context grows per step while searching for uniqueness. */
+const CONTEXT_STEP = 4;
+/**
+ * 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, target, paramName, valueClass, hash) {
+    const regex = buildContentRegex(body, target, paramName, valueClass);
+    if (!regex) {
+        return undefined;
+    }
+    const redaction = { regex };
+    if (hash) {
+        redaction.hash = hash;
+        // 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 },
+        };
+    }
+    // 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 },
+    };
+}
+/**
+ * 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, target, paramName, valueClass) {
     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));
+        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;
+                }
             }
-            if (end === body.length) {
-                start = Math.max(0, body.length - MIN_REVEAL_BYTES);
+            catch {
+                break;
+            }
+            if (from === 0) {
+                break;
             }
         }
-        const isBoundary = (c) => {
-            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) {
-    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-// ---------------------------------------------------------------------------
-// Capture group regex (only used when hash is requested)
-// ---------------------------------------------------------------------------
-function buildCaptureRegex(body, target, paramName, valueClass) {
-    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`). */
+/**
+ * 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, target, paramName) {
     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);
+    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, idx) {
     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);
         }
     }
@@ -410,6 +504,10 @@ function findRightContext(body, endIdx) {
     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);
         }
         if (c === '{' || c === '}' || c === ',' || c === ';' || c === '\n') {
@@ -418,14 +516,30 @@ function findRightContext(body, endIdx) {
     }
     return body.slice(endIdx, stop);
 }
+// ---------------------------------------------------------------------------
+// Shared helpers
+// ---------------------------------------------------------------------------
+function escapeRegex(s) {
+    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) {
+    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) {
     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_-]+';
     }