@reclaimprotocol/agent 0.1.10 → 0.1.12

package/lib/old/tools/scaffold-demo-server.js

@@ -0,0 +1,242 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import { defineTool } from "../../mcp/server.js";
+import { findProjectRoot } from "../../paths.js";
+/** Corrected against `@reclaimprotocol/js-sdk` v5.8.1 (`Reclaim.ts`): awaits
+ *  `getRequestUrl()`, uses `setContext` (not deprecated `addContext`), JSON-
+ *  parses the raw webhook body before `verifyProof`, passes the required
+ *  `{ providerId, providerVersion }` config, and reads `result.isVerified`
+ *  (not `is_verified`). `providerVersion` is left unpinned (`undefined`) by
+ *  default — the built-in "example" providerId isn't versioned, so pinning
+ *  one is only meaningful once you swap in your own provider. */
+function serverJs(providerId, providerVersion) {
+    return `import express from "express";
+import "dotenv/config";
+import { ReclaimProofRequest, verifyProof } from "@reclaimprotocol/js-sdk";
+import { randomUUID } from "node:crypto";
+
+const app = express();
+const port = process.env.PORT || 3000;
+const providerId = ${JSON.stringify(providerId)};
+// Left unpinned by default — set this if you need to pin a specific version.
+const providerVersion = ${providerVersion ? JSON.stringify(providerVersion) : 'undefined'};
+
+app.set("trust proxy", true);
+app.use(express.json({ limit: "2mb" }));
+
+app.get("/health", (_req, res) => {
+  res.json({ ok: true });
+});
+
+app.get("/verify", (_req, res) => {
+  res.type("html").send(\`<!doctype html>
+    <html lang="en">
+      <head>
+        <meta charset="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <title>Reclaim demo verification</title>
+        <style>
+          body { font-family: system-ui, sans-serif; max-width: 680px; margin: 64px auto; padding: 0 20px; line-height: 1.5; }
+          code { background: #f3f4f6; padding: 2px 6px; border-radius: 4px; }
+          button { background: #111827; border: 0; border-radius: 8px; color: white; cursor: pointer; font: inherit; padding: 12px 18px; }
+          button:disabled { cursor: wait; opacity: 0.7; }
+          pre { background: #f3f4f6; border-radius: 8px; overflow: auto; padding: 12px; }
+        </style>
+      </head>
+      <body>
+        <h1>Reclaim demo verification</h1>
+        <p>Uses provider <code>\${providerId}</code>.</p>
+        <button id="start">Start verification</button>
+        <pre id="status">Ready.</pre>
+        <p>Webhook endpoint: <code>/webhooks/reclaim</code></p>
+        <script>
+          const button = document.getElementById("start");
+          const status = document.getElementById("status");
+          button.addEventListener("click", async () => {
+            button.disabled = true;
+            status.textContent = "Creating verification request...";
+            try {
+              const response = await fetch("/api/reclaim/request", { method: "POST" });
+              if (!response.ok) throw new Error(await response.text());
+              const { requestUrl } = await response.json();
+              status.textContent = "Opening Reclaim verification...";
+              window.open(requestUrl, "_blank", "noopener,noreferrer");
+              status.textContent = "Verification opened. Complete it in the Reclaim window.";
+            } catch (error) {
+              status.textContent = error instanceof Error ? error.message : String(error);
+              button.disabled = false;
+            }
+          });
+        </script>
+      </body>
+    </html>\`);
+});
+
+app.post("/api/reclaim/request", async (req, res, next) => {
+  try {
+    const appId = process.env.RECLAIM_APP_ID;
+    const appSecret = process.env.RECLAIM_APP_SECRET;
+    if (!appId || !appSecret) {
+      return res.status(500).json({ error: "Missing RECLAIM_APP_ID or RECLAIM_APP_SECRET" });
+    }
+
+    const origin = process.env.PUBLIC_URL || \`\${req.protocol}://\${req.get("host")}\`;
+    const reclaimProofRequest = await ReclaimProofRequest.init(appId, appSecret, providerId, {
+      providerVersion,
+    });
+    reclaimProofRequest.setAppCallbackUrl(\`\${origin}/webhooks/reclaim\`, true);
+    reclaimProofRequest.setContext(
+      randomUUID(),
+      JSON.stringify({ createdAt: new Date().toISOString() }),
+    );
+
+    // getRequestUrl() is ASYNC in the current SDK — must be awaited.
+    const requestUrl = await reclaimProofRequest.getRequestUrl();
+
+    res.json({
+      request: reclaimProofRequest.toJsonString(),
+      requestUrl,
+    });
+  } catch (error) {
+    next(error);
+  }
+});
+
+app.post("/webhooks/reclaim", async (req, res, next) => {
+  try {
+    // With jsonProofResponse: true + express.json() above, req.body is
+    // already a parsed Proof/Proof[]. Without either of those, the raw body
+    // is text and must be JSON.parse()'d (and URL-decoded if form-encoded)
+    // before calling verifyProof.
+    const proof = req.body;
+
+    // The second argument is REQUIRED — must include providerId.
+    const result = await verifyProof(proof, { providerId, providerVersion });
+
+    console.log("Received Reclaim verification:");
+    console.log(JSON.stringify({ isVerified: result.isVerified, data: result.data, error: result.error }, null, 2));
+
+    res.status(200).json({ received: true, verified: result.isVerified });
+  } catch (error) {
+    next(error);
+  }
+});
+
+app.use((err, _req, res, _next) => {
+  console.error(err);
+  res.status(500).json({ error: err instanceof Error ? err.message : "Internal server error" });
+});
+
+app.listen(port, () => {
+  console.log(\`Reclaim demo server listening on http://localhost:\${port}\`);
+  console.log(\`Verify page:      http://localhost:\${port}/verify\`);
+  console.log(\`Webhook endpoint: http://localhost:\${port}/webhooks/reclaim\`);
+  if (!process.env.PUBLIC_URL) {
+    console.log("Set PUBLIC_URL (e.g. an ngrok URL) so the webhook is reachable from Reclaim's servers.");
+  }
+});
+`;
+}
+const PACKAGE_JSON = (name) => JSON.stringify({
+    name,
+    private: true,
+    type: 'module',
+    scripts: { start: 'node server.js' },
+    dependencies: {
+        '@reclaimprotocol/js-sdk': '^5.8.1',
+        dotenv: '^16.4.5',
+        express: '^4.21.2',
+    },
+}, null, 2) + '\n';
+const ENV_EXAMPLE = `RECLAIM_APP_ID=
+RECLAIM_APP_SECRET=
+PORT=3000
+# REQUIRED for the webhook callback to land — Reclaim's servers can't reach
+# localhost. Run: ngrok http 3000 (in a separate terminal) and paste the
+# https://<id>.ngrok-free.app URL it prints here. Without this, only the
+# frontend-side flow works (opening requestUrl) — the webhook never fires.
+PUBLIC_URL=
+`;
+const README = `# Reclaim demo server
+
+1. \`npm install\`
+2. Fill in \`.env\` (copy from \`.env.example\`) — get \`RECLAIM_APP_ID\`/
+   \`RECLAIM_APP_SECRET\` from the \`issue_app_credentials\` MCP tool, or your
+   existing app.
+3. In a separate terminal, run \`ngrok http 3000\` (install from
+   https://ngrok.com if needed) and copy the \`https://<id>.ngrok-free.app\`
+   URL it prints into \`PUBLIC_URL\` in \`.env\`. This is REQUIRED — Reclaim's
+   servers must reach your webhook over the public internet, and
+   \`localhost\` is not reachable from there.
+4. \`npm start\`, then open http://localhost:3000/verify and click "Start
+   verification".
+5. Watch the server logs for the \`/webhooks/reclaim\` payload once you
+   complete verification.
+
+This demo defaults to providerId \`"example"\` — a built-in smoke-test
+provider, so you can confirm the whole loop (request → open → callback)
+works before wiring in a real provider.
+`;
+/**
+ * Scaffold a small, runnable Express demo that exercises the full
+ * @reclaimprotocol/js-sdk flow end-to-end: request a proof (backend), open it
+ * (frontend), and verify the async webhook callback (backend). Corrected
+ * against the CURRENT SDK API (see js-sdk-integration-guide) rather than
+ * older examples that predate several signature changes.
+ */
+const DEFAULT_PROVIDER_ID = 'example';
+export function scaffoldDemoServerTool() {
+    return defineTool({
+        name: 'scaffold_reclaim_demo_server',
+        description: 'Write a small runnable Express demo (server.js, package.json, ' +
+            '.env.example, README.md) that requests a Reclaim proof and ' +
+            'verifies the async webhook callback, using the CURRENT ' +
+            '@reclaimprotocol/js-sdk API. Defaults `providerId` to the built-in ' +
+            '"example" smoke-test provider so you can confirm the whole loop ' +
+            'without authoring one first, and requires ngrok (or similar) to ' +
+            'expose the local server so the webhook callback can reach it — ' +
+            'the generated README walks through that step. Use ' +
+            'get_js_sdk_integration_guide for the annotated write-up of the ' +
+            'same flow.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                targetDir: {
+                    type: 'string',
+                    description: 'Directory to write the demo into (created if missing). ' +
+                        'Relative paths resolve against the project root.',
+                },
+                providerId: {
+                    type: 'string',
+                    description: 'Provider id the demo requests a proof for (default ' +
+                        '"example", a built-in smoke-test provider — good for ' +
+                        'confirming the flow works before wiring in a real one).',
+                },
+                providerVersion: {
+                    type: 'string',
+                    description: 'Provider version to pin (default: unpinned — "example" ' +
+                        'isn\'t versioned, so only set this once you swap in your ' +
+                        'own provider).',
+                },
+            },
+            required: ['targetDir'],
+        },
+    }, async ({ targetDir, providerId, providerVersion }) => {
+        const dir = isAbsolute(targetDir)
+            ? targetDir
+            : join(findProjectRoot(process.cwd()), targetDir);
+        mkdirSync(dir, { recursive: true });
+        const id = providerId ?? DEFAULT_PROVIDER_ID;
+        writeFileSync(join(dir, 'server.js'), serverJs(id, providerVersion));
+        writeFileSync(join(dir, 'package.json'), PACKAGE_JSON('reclaim-demo-server'));
+        writeFileSync(join(dir, '.env.example'), ENV_EXAMPLE);
+        writeFileSync(join(dir, 'README.md'), README);
+        return {
+            dir,
+            providerId: id,
+            files: ['server.js', 'package.json', '.env.example', 'README.md'],
+            next: 'cd into the directory, npm install, copy .env.example to .env ' +
+                'and fill it in (including PUBLIC_URL from ngrok), then npm start.',
+        };
+    });
+}

package/lib/old/tools/verify-sdk-setup.d.ts

@@ -0,0 +1,9 @@
+import { type RegisteredTool } from '../../mcp/server.ts';
+import type { ReclaimOldClient } from '../client.ts';
+/**
+ * Health-check a project's @reclaimprotocol/js-sdk setup: SDK installed,
+ * RECLAIM_APP_ID/RECLAIM_APP_SECRET present (env or .env), and (if an appId
+ * is found) whether that app is actually linked/has quota, via the real
+ * check_app_status endpoint — not just static file checks.
+ */
+export declare function verifySdkSetupTool(client: ReclaimOldClient): RegisteredTool;

package/lib/old/tools/verify-sdk-setup.js

@@ -0,0 +1,128 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { defineTool } from "../../mcp/server.js";
+import { findProjectRoot } from "../../paths.js";
+function readEnvFile(dir) {
+    const path = join(dir, '.env');
+    if (!existsSync(path)) {
+        return {};
+    }
+    const out = {};
+    for (const line of readFileSync(path, 'utf8').split('\n')) {
+        const m = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$/);
+        if (m) {
+            out[m[1]] = m[2].replace(/^['"]|['"]$/g, '');
+        }
+    }
+    return out;
+}
+/**
+ * Health-check a project's @reclaimprotocol/js-sdk setup: SDK installed,
+ * RECLAIM_APP_ID/RECLAIM_APP_SECRET present (env or .env), and (if an appId
+ * is found) whether that app is actually linked/has quota, via the real
+ * check_app_status endpoint — not just static file checks.
+ */
+export function verifySdkSetupTool(client) {
+    return defineTool({
+        name: 'verify_reclaim_sdk_setup',
+        description: 'Health-check a project\'s @reclaimprotocol/js-sdk integration: SDK ' +
+            'installed, RECLAIM_APP_ID/RECLAIM_APP_SECRET present, and (if an ' +
+            'appId is found) whether that app is actually linked and has quota ' +
+            'left, by calling the real status endpoint.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                projectDir: {
+                    type: 'string',
+                    description: 'Project directory (default: detected project root).',
+                },
+            },
+        },
+    }, async ({ projectDir }) => {
+        const dir = projectDir ?? findProjectRoot(process.cwd());
+        const checks = [];
+        const pkgPath = join(dir, 'package.json');
+        let sdkInPkg = false;
+        if (existsSync(pkgPath)) {
+            try {
+                const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+                sdkInPkg = Boolean(pkg.dependencies?.['@reclaimprotocol/js-sdk'] ||
+                    pkg.devDependencies?.['@reclaimprotocol/js-sdk']);
+            }
+            catch {
+                // malformed package.json — fall through, reported below
+            }
+        }
+        const sdkInstalled = existsSync(join(dir, 'node_modules', '@reclaimprotocol', 'js-sdk'));
+        checks.push({
+            name: 'sdk_dependency',
+            ok: sdkInPkg,
+            detail: sdkInPkg
+                ? '@reclaimprotocol/js-sdk is listed in package.json'
+                : '@reclaimprotocol/js-sdk is NOT in package.json — run ' +
+                    '`npm install @reclaimprotocol/js-sdk`.',
+        });
+        checks.push({
+            name: 'sdk_installed',
+            ok: sdkInstalled,
+            detail: sdkInstalled
+                ? '@reclaimprotocol/js-sdk found in node_modules'
+                : 'Not found in node_modules — run your package manager\'s ' +
+                    'install command.',
+        });
+        const env = { ...readEnvFile(dir), ...process.env };
+        const appId = env.RECLAIM_APP_ID;
+        const appSecret = env.RECLAIM_APP_SECRET;
+        checks.push({
+            name: 'app_id',
+            ok: Boolean(appId),
+            detail: appId
+                ? `RECLAIM_APP_ID set (${appId})`
+                : 'RECLAIM_APP_ID missing (env or .env) — run ' +
+                    'issue_app_credentials or link_app_to_account.',
+        });
+        checks.push({
+            name: 'app_secret',
+            ok: Boolean(appSecret),
+            detail: appSecret
+                ? 'RECLAIM_APP_SECRET set'
+                : 'RECLAIM_APP_SECRET missing (env or .env).',
+        });
+        // Informational only — PUBLIC_URL is only needed for the async
+        // webhook callback, not the frontend-only flow, so a missing value
+        // doesn't fail the overall check.
+        const publicUrl = env.PUBLIC_URL;
+        checks.push({
+            name: 'public_url',
+            ok: true,
+            detail: publicUrl
+                ? `PUBLIC_URL set (${publicUrl}) — used as the webhook callback ` +
+                    'base for setAppCallbackUrl.'
+                : 'PUBLIC_URL not set — fine if you only read the proof from the ' +
+                    'frontend flow, but the async webhook callback needs a ' +
+                    'publicly-reachable URL (e.g. from `ngrok http <port>`) or it ' +
+                    'will never fire.',
+        });
+        if (appId) {
+            try {
+                const status = await client.getApplicationStatus(appId);
+                const linked = status?.isLinked === true;
+                checks.push({
+                    name: 'app_status',
+                    ok: status?.available !== false,
+                    detail: `isLinked=${linked}, sandboxMode=${status?.sandboxMode}, ` +
+                        `available=${status?.available}` +
+                        (linked ? '' : ' — run link_app_to_account to lift the sandbox limit.'),
+                });
+            }
+            catch (err) {
+                checks.push({
+                    name: 'app_status',
+                    ok: false,
+                    detail: `Could not reach status endpoint: ${err instanceof Error ? err.message : String(err)}`,
+                });
+            }
+        }
+        return { projectDir: dir, checks, ok: checks.every((c) => c.ok) };
+    });
+}

package/lib/provider/dom-xpath.js

@@ -15,6 +15,76 @@ import "../proof/patch-domhandler.js";
 /** Identifying attributes stable enough to anchor an xPath on (value-bearing
  *  attrs like `content`/`href`/`value` are excluded). */
 const IDENT_ATTRS = ['name', 'property', 'itemprop', 'data-testid', 'rel', 'for'];
+/** 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 = {
+    '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) {
+    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) {
+    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;
+}
 /**
  * A verified xPath to the tightest element containing one of `targets`, or
  * undefined if the value isn't present in the parsed tree. Prefers a short
@@ -45,14 +115,24 @@ export function elementAnchor(html, targets) {
     if (startIndex === null || endIndex === null) {
         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
  *  occurrence — an attribute whose value IS the target, or a text child that IS
@@ -97,46 +177,119 @@ function smallestElement(els) {
         .sort((a, b) => elementSpan(a) - elementSpan(b))
         .at(0);
 }
-/** Candidate xPaths for `el`, best (most stable / shortest) first. */
+/** 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) {
     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;
         }
         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,
+                };
             }
         }
     }
-    yield absolutePath(el);
+    // 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) {
+    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, el) {
+    const parts = [];
+    let node = 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;
+    }
+    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) {
+    let depth = 1;
+    for (let anc = 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) {
+    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
  *  n is the element's 1-based position among same-tag siblings. */

package/lib/provider/draft.d.ts

@@ -1,4 +1,10 @@
 import type { CapturedRequest, OprfMode, ReclaimProvider, ResponseMatch, ResponseRedaction, SecretParamRef } from './schema.ts';
+/** 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 declare function defaultSensitiveHash(value: string): OprfMode | 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 {