@reclaimprotocol/agent 0.1.22 → 0.1.24

package/lib/proof/debug-response-dump.js

@@ -1,10 +1,10 @@
 // Debug helper (gated by RECLAIM_AGENT_DUMP_RESPONSE): capture the EXACT
 // response bytes the attestor validates a claim against, plus a per-match
 // presence check. A "Response does not contain X" failure means the attestor's
-// server-side re-fetch differs from what the browser (replay) saw — e.g. GitHub
-// embeds nav/userMenu data for browser requests but not for the attestor's raw
-// fetch. Seeing the attestor's actual response is the only way to tell what it
-// really returned.
+// server-side re-fetch differs from what the browser (replay) saw — for
+// example, GitHub embeds nav/userMenu data for browser requests but not for the
+// attestor's raw fetch. Seeing the attestor's actual response is the only way
+// to tell what it really returned.
 //
 // On each getResponseRedactions call it writes the response to
 // `attestor-last-response.html` in the process CWD and logs the byte count +,

package/lib/proof/index.d.ts

@@ -1,5 +1,6 @@
 export type { AttestorClaim, AttestorLogEntry, ProofResult, RunAttestorProofOptions, } from './attestor.ts';
 export { runAttestorProof, tailLogs, warnsAndErrors } from './attestor.ts';
 export { buildHttpParams, ensureAttestorCrypto, type ParsedClaim, parseClaim, resolveAttestorUrl, } from './proof-core.ts';
+export { type HttpParams, type HttpSecretParams, type PopcornProveOptions, popcornProve, popcornValidateExtraction, type ValidateExtractionResult, } from './pod-prover.ts';
 export { ensureZkFiles } from './zk-files.ts';
 export { createClaimOnAttestor } from '@reclaimprotocol/attestor-core';

package/lib/proof/index.js

@@ -1,5 +1,6 @@
 export { runAttestorProof, tailLogs, warnsAndErrors } from "./attestor.js";
 export { buildHttpParams, ensureAttestorCrypto, parseClaim, resolveAttestorUrl, } from "./proof-core.js";
+export { popcornProve, popcornValidateExtraction, } from "./pod-prover.js";
 export { ensureZkFiles } from "./zk-files.js";
 // Re-exported attestor-core claim primitive so the agent is the single
 // integration point with @reclaimprotocol/attestor-core across the builder.

package/lib/proof/page-replay.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Replay a drafted provider's AUTHENTICATED request FROM INSIDE the live
+ * attached browser tab, over CDP `Runtime.evaluate` — so cookies/session are
+ * always the real browser's, for every browser source the MCP can attach to
+ * (local Chrome, remote Popcorn, or a caller-supplied custom CDP endpoint all
+ * funnel through one `AuthoringBackend.sendCdp`). Ports the pattern already
+ * proven in the cloud/Popcorn authoring backend
+ * (`packages/app/src/author/backend.ts` `pageFetch`/`authenticatedFetch`),
+ * adapted to the MCP's single-page `sendCdp(method, params)` (no separate
+ * `pageSession` argument). The ANONYMOUS auth-bound check does NOT go through
+ * the page — see `replayProviderInPage`'s doc comment below for why.
+ */
+import type { ReclaimProvider } from '../provider/schema.ts';
+import { type ReplayResult } from './replay.ts';
+/** Everything this module needs from an `AuthoringBackend` — just the raw CDP
+ *  seam, so callers can pass a minimal object instead of a full backend. */
+export interface PageReplayTarget {
+    sendCdp(method: string, params?: Record<string, unknown>): Promise<unknown>;
+}
+/**
+ * Replay `provider` and judge the response. Without `withoutSecrets`, replays
+ * as the logged-in session — run FROM INSIDE the live tab
+ * (`authenticatedPageFetch`) so cookies are the real browser's, which a
+ * detached call could never reproduce without manually re-deriving them.
+ * WITH `withoutSecrets` (the auth-bound check — "does this still work with
+ * no credentials, that is, is it actually public"), replay instead through the
+ * detached Node-side `replayProvider`: the whole point of that check is to
+ * prove NO secret rides along, and the live page's own global `fetch` can't
+ * give that guarantee — a site (or a script installed via test_user_script)
+ * can wrap `fetch` and re-attach a token from localStorage/a service worker
+ * even under `credentials:'omit'`. A fresh, page-uninvolved fetch has no
+ * such surface.
+ */
+export declare function replayProviderInPage(backend: PageReplayTarget, provider: ReclaimProvider, secrets: Record<string, string>, opts?: {
+    withoutSecrets?: boolean;
+}): Promise<ReplayResult>;

package/lib/proof/page-replay.js

@@ -0,0 +1,76 @@
+import { buildReplayRequest, evaluateReplay, replayProvider } from "./replay.js";
+/** Run `fetch(...)` for `provider`'s (already-templated) request inside the
+ *  attached tab, via `Runtime.evaluate`. `credentials` selects the visitor:
+ *  `'omit'` = anonymous (the auth-bound check), `'include'` = the logged-in
+ *  user (the reproducibility gate). Same-origin only — the tab is already on
+ *  the target site; a cross-origin/CORS failure comes back as `error`. */
+async function pageFetch(backend, provider, credentials, extraSecrets) {
+    const req = buildReplayRequest(provider, extraSecrets);
+    const expression = `(async () => {
+		try {
+			const r = await fetch(${JSON.stringify(req.url)}, {
+				method: ${JSON.stringify(req.method)},
+				headers: ${JSON.stringify(req.headers)},
+				credentials: ${JSON.stringify(credentials)},${req.body !== undefined
+        ? `\n\t\t\t\tbody: ${JSON.stringify(req.body)},`
+        : ''}
+			})
+			return { status: r.status, body: await r.text() }
+		} catch(e) { return { error: String((e && e.message) || e) } }
+	})()`;
+    try {
+        const res = (await backend.sendCdp('Runtime.evaluate', {
+            expression,
+            awaitPromise: true,
+            returnByValue: true,
+        }));
+        if (res.exceptionDetails) {
+            return {
+                error: res.exceptionDetails.exception?.description
+                    ?? res.exceptionDetails.text
+                    ?? 'page fetch evaluation error',
+            };
+        }
+        return res.result?.value ?? { error: 'page fetch returned no value' };
+    }
+    catch (err) {
+        return { error: err instanceof Error ? err.message : String(err) };
+    }
+}
+/** Authenticated re-issue for the reproducibility gate. Cookies ride along
+ *  via `credentials: 'include'` (a `Cookie` header can't be set from
+ *  `fetch()` — it's a forbidden header name), so only NON-cookie secrets
+ *  (Authorization, X-* tokens) are injected explicitly. */
+function authenticatedPageFetch(backend, provider, secrets) {
+    const extra = {};
+    for (const [k, v] of Object.entries(secrets)) {
+        if (k.toLowerCase() !== 'cookie') {
+            extra[k] = v;
+        }
+    }
+    return pageFetch(backend, provider, 'include', extra);
+}
+/**
+ * Replay `provider` and judge the response. Without `withoutSecrets`, replays
+ * as the logged-in session — run FROM INSIDE the live tab
+ * (`authenticatedPageFetch`) so cookies are the real browser's, which a
+ * detached call could never reproduce without manually re-deriving them.
+ * WITH `withoutSecrets` (the auth-bound check — "does this still work with
+ * no credentials, that is, is it actually public"), replay instead through the
+ * detached Node-side `replayProvider`: the whole point of that check is to
+ * prove NO secret rides along, and the live page's own global `fetch` can't
+ * give that guarantee — a site (or a script installed via test_user_script)
+ * can wrap `fetch` and re-attach a token from localStorage/a service worker
+ * even under `credentials:'omit'`. A fresh, page-uninvolved fetch has no
+ * such surface.
+ */
+export async function replayProviderInPage(backend, provider, secrets, opts) {
+    if (opts?.withoutSecrets) {
+        return replayProvider(provider, {});
+    }
+    const result = await authenticatedPageFetch(backend, provider, secrets);
+    if (result.error !== undefined || result.status === undefined) {
+        throw new Error(`in-browser replay failed: ${result.error ?? 'no response'}`);
+    }
+    return evaluateReplay(result.status, result.body ?? '', provider);
+}

package/lib/proof/pod-prover.d.ts

@@ -0,0 +1,47 @@
+import type { ProviderParams } from '@reclaimprotocol/attestor-core';
+import type { ProofResult } from './attestor.ts';
+/** Attestor HTTP provider params — the recipe the agent synthesis produces. */
+export type HttpParams = ProviderParams<'http'>;
+/** Captured secrets for the replay, exactly as `/reclaim/prove` wants them. */
+export interface HttpSecretParams {
+    cookieStr?: string;
+    authorisationHeader?: string;
+    headers?: Record<string, string>;
+    paramValues?: Record<string, string>;
+}
+export interface PopcornProveOptions {
+    /** Pod API base (the session's `apiUrl`). */
+    apiUrl: string;
+    params: HttpParams;
+    secretParams: HttpSecretParams;
+    /** Session context, stringified into the claim context if given. */
+    context?: Record<string, unknown>;
+    fetchImpl?: typeof fetch;
+}
+export interface ValidateExtractionResult {
+    valid: boolean;
+    extractedValue?: string;
+    error?: string;
+    steps?: string[];
+}
+/**
+ * The cloud "replay": validate that a drafted recipe's selectors extract the
+ * expected value from a captured response, inside the TEE — `POST {apiUrl}
+ * /reclaim/validate-extraction`. Reuses the prover's own redaction engine, so
+ * a pass means the selectors won't diverge at proof time. No proof/secrets.
+ */
+export declare function popcornValidateExtraction(opts: {
+    apiUrl: string;
+    responseBody: string;
+    expectedValue: string;
+    xPath?: string;
+    jsonPath?: string;
+    regex?: string;
+    fetchImpl?: typeof fetch;
+}): Promise<ValidateExtractionResult>;
+/**
+ * Prove a single request through the Popcorn TEE. Returns the shared
+ * {@link ProofResult}; on any failure `verified` is false and `error` carries
+ * the reason (never throws for an expected proof failure).
+ */
+export declare function popcornProve(opts: PopcornProveOptions): Promise<ProofResult>;

package/lib/proof/pod-prover.js

@@ -0,0 +1,155 @@
+/**
+ * PopcornPodProver — run the zkTLS proof inside a Popcorn browser session's
+ * OWN TEE pod instead of the in-process attestor SDK (`runAttestorProof`).
+ * POSTs the recipe + captured secrets to the pod's `/reclaim/prove` (the same
+ * attestor TEE+MPC protocol) and re-shapes the response into the shared
+ * {@link ProofResult}, so every caller consumes proof results identically
+ * regardless of which path produced them.
+ *
+ * This is the pod's OWN api for creating a proof from a live session — used
+ * by both the app's server-driven verification runner and the MCP's
+ * `run_proof_via_pod` tool. Proving here (rather than locally) matters
+ * specifically when the session is country-routed: Popcorn allocated the
+ * browser with an exit country, and this is the SAME enclave holding that
+ * browser's TLS session, so the proof reaches the target from the identical
+ * exit IP the browser used — a local attestor SDK proof runs from the
+ * app/agent's OWN network instead.
+ *
+ * Contract (verified against ../popcorn-images oapi.go + ../reclaim-tee):
+ *   POST {apiUrl}/reclaim/prove  body { provider_params_json, config_json? }
+ *   provider_params_json = JSON of { name, params, secretParams, context? }
+ *   → 200 { session_id, claim, signature } (ReclaimProveResult, snake_case):
+ *     claim has provider/parameters/owner/timestamp_s/context/identifier/epoch;
+ *     signature has attestor_address + claim_signature(b64) +
+ *     result_signature(b64). A proof failure/timeout is a 500 whose `message`
+ *     carries the reason.
+ *
+ * The pod API is unauthenticated (gateway/session is the trust boundary); call
+ * it over the same internal host used for CDP. Consumers verify
+ * `claim_signature` only (see `@reclaimprotocol/client`'s `verifyNestedProof`),
+ * so this hands back a {@link AttestorClaim} whose hex `claimSignature` the
+ * shared `wrapProofAsJws` (app-side) turns into the nested result proof.
+ * `result_signature` is unused by any consumer.
+ */
+import { bytesToHex } from '@noble/hashes/utils.js';
+/**
+ * The cloud "replay": validate that a drafted recipe's selectors extract the
+ * expected value from a captured response, inside the TEE — `POST {apiUrl}
+ * /reclaim/validate-extraction`. Reuses the prover's own redaction engine, so
+ * a pass means the selectors won't diverge at proof time. No proof/secrets.
+ */
+export async function popcornValidateExtraction(opts) {
+    const doFetch = opts.fetchImpl ?? fetch;
+    const base = opts.apiUrl.replace(/\/$/, '');
+    try {
+        const res = await doFetch(`${base}/reclaim/validate-extraction`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                responseBody: opts.responseBody,
+                expectedValue: opts.expectedValue,
+                ...(opts.xPath ? { xPath: opts.xPath } : {}),
+                ...(opts.jsonPath ? { jsonPath: opts.jsonPath } : {}),
+                ...(opts.regex ? { regex: opts.regex } : {}),
+            }),
+        });
+        if (!res.ok) {
+            const detail = await res.text().catch(() => '');
+            return { valid: false, error: `${res.status}: ${detail.slice(0, 300)}` };
+        }
+        const body = (await res.json());
+        return body;
+    }
+    catch (err) {
+        const error = err instanceof Error ? err.message : String(err);
+        return { valid: false, error };
+    }
+}
+/** Decode standard base64 (Go `base64.StdEncoding` from Popcorn) to bytes. */
+function b64ToBytes(b64) {
+    return new Uint8Array(Buffer.from(b64, 'base64'));
+}
+/**
+ * Prove a single request through the Popcorn TEE. Returns the shared
+ * {@link ProofResult}; on any failure `verified` is false and `error` carries
+ * the reason (never throws for an expected proof failure).
+ */
+export async function popcornProve(opts) {
+    const { apiUrl, params, secretParams, context } = opts;
+    const doFetch = opts.fetchImpl ?? fetch;
+    const base = apiUrl.replace(/\/$/, '');
+    const providerParamsJson = JSON.stringify({
+        name: 'http',
+        params,
+        secretParams,
+        ...(context ? { context: JSON.stringify(context) } : {}),
+    });
+    const fail = (error) => ({
+        proof: undefined,
+        extractedValue: '',
+        extractedParameters: {},
+        verified: false,
+        error,
+    });
+    let resp;
+    let raw = '';
+    try {
+        const res = await doFetch(`${base}/reclaim/prove`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ provider_params_json: providerParamsJson }),
+        });
+        // Read the body as text first: a proof failure/timeout is a 500 whose
+        // `message` we want to surface verbatim, and on an unexpected 200 shape we
+        // echo the raw body instead of a blind "no claim/signature".
+        raw = await res.text().catch(() => '');
+        if (!res.ok) {
+            return fail(`/reclaim/prove ${res.status}: ${raw.slice(0, 300)}`);
+        }
+        resp = JSON.parse(raw);
+    }
+    catch (err) {
+        return fail(err instanceof Error ? err.message : String(err));
+    }
+    const claim = resp.claim;
+    const sig = resp.signature;
+    if (!claim || !sig?.attestor_address || !sig?.claim_signature) {
+        return fail('popcorn /reclaim/prove returned no claim/signature: '
+            + raw.slice(0, 300));
+    }
+    // claim.context is the JSON string carrying { extractedParameters, ... } —
+    // the same place the in-process path reads them from.
+    let extractedParameters = {};
+    if (typeof claim.context === 'string') {
+        try {
+            const ctx = JSON.parse(claim.context);
+            extractedParameters = ctx.extractedParameters ?? {};
+        }
+        catch {
+            // leave empty if context isn't valid JSON
+        }
+    }
+    const attestorClaim = {
+        claim: {
+            provider: claim.provider ?? '',
+            parameters: claim.parameters ?? '',
+            owner: claim.owner ?? '',
+            timestampS: claim.timestamp_s ?? 0,
+            context: claim.context ?? '',
+            identifier: claim.identifier ?? '',
+            epoch: claim.epoch ?? 0,
+        },
+        attestorAddress: sig.attestor_address,
+        // Consumer-side verification expects hex; Popcorn signs in base64.
+        claimSignature: '0x' + bytesToHex(b64ToBytes(sig.claim_signature)),
+    };
+    return {
+        proof: resp,
+        verified: true,
+        extractedParameters,
+        extractedValue: Object.values(extractedParameters)[0] ?? '',
+        ...(claim.identifier ? { identifier: claim.identifier } : {}),
+        ...(claim.owner ? { owner: claim.owner } : {}),
+        attestorClaim,
+    };
+}

package/lib/proof/replay.d.ts

@@ -5,4 +5,32 @@ export interface ReplayResult {
     matchesOriginal: boolean;
     hints?: string[];
 }
+/** Expand `{{name}}` placeholders from `paramValues`. Matches the attestor
+ *  SDK's behavior so replay and proof both hit the same final URL. */
+export declare function expandTemplate(s: string, params: Record<string, string> | undefined): string;
+/** Build the request the wire replay actually sends: `{{name}}` placeholders
+ *  in the URL/headers/body expanded from `provider.paramValues`, secrets
+ *  layered onto the public headers. Shared by every replay transport (Node
+ *  `fetch` here, or a `fetch` run inside the live browser tab) so they all
+ *  send the identical request. */
+export interface ReplayRequest {
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+}
+export declare function buildReplayRequest(provider: ReclaimProvider, secrets: Record<string, string>): ReplayRequest;
+/**
+ * Judge a replayed response against `provider`'s matchers — the part of
+ * replay that's identical regardless of HOW the request was sent (detached
+ * Node `fetch` or a live in-browser `fetch`). Separated from the actual
+ * network call so both transports share one evaluation.
+ */
+export declare function evaluateReplay(status: number, body: string, provider: ReclaimProvider): ReplayResult;
+/** Detached Node-side replay: sends the request directly from this process,
+ *  NOT from any attached browser tab — its cookies/secrets are exactly the
+ *  `secrets` passed in, never a real browser session. Used by tests and by
+ *  any caller with no live browser to replay through (the MCP's authoring
+ *  backend instead runs the SAME request inside the attached tab — see
+ *  `proof/page-replay.ts` — so replay reflects real session cookies). */
 export declare function replayProvider(provider: ReclaimProvider, secrets: Record<string, string>): Promise<ReplayResult>;

package/lib/proof/replay.js

@@ -1,6 +1,6 @@
 /** Expand `{{name}}` placeholders from `paramValues`. Matches the attestor
  *  SDK's behavior so replay and proof both hit the same final URL. */
-function expandTemplate(s, params) {
+export function expandTemplate(s, params) {
     if (!params) {
         return s;
     }
@@ -9,7 +9,7 @@ function expandTemplate(s, params) {
         return v !== undefined ? v : match;
     });
 }
-export async function replayProvider(provider, secrets) {
+export function buildReplayRequest(provider, secrets) {
     const params = provider.paramValues;
     const url = expandTemplate(provider.url, params);
     const expandedHeaders = {};
@@ -17,21 +17,29 @@ export async function replayProvider(provider, secrets) {
         expandedHeaders[k] = expandTemplate(v, params);
     }
     const headers = { ...expandedHeaders, ...secrets };
-    const fetchInit = {
+    const body = provider.body !== undefined
+        ? expandTemplate(provider.body, params)
+        : undefined;
+    return {
+        url,
         method: provider.method,
         headers,
-        redirect: 'manual',
+        ...(body !== undefined ? { body } : {}),
     };
-    if (provider.body !== undefined) {
-        fetchInit.body = expandTemplate(provider.body, params);
-    }
-    const res = await fetch(url, fetchInit);
-    const body = await res.text();
+}
+/**
+ * Judge a replayed response against `provider`'s matchers — the part of
+ * replay that's identical regardless of HOW the request was sent (detached
+ * Node `fetch` or a live in-browser `fetch`). Separated from the actual
+ * network call so both transports share one evaluation.
+ */
+export function evaluateReplay(status, body, provider) {
+    const params = provider.paramValues;
     const hints = [];
-    if (res.status === 401 || res.status === 403) {
+    if (status === 401 || status === 403) {
         hints.push('auth/permission failed');
     }
-    if (res.status >= 500) {
+    if (status >= 500) {
         hints.push('upstream server error');
     }
     for (const m of provider.responseMatches) {
@@ -45,22 +53,35 @@ export async function replayProvider(provider, secrets) {
             value: expandTemplate(m.value, params),
         };
         if (!matchesBody(body, expanded)) {
-            if (res.status >= 200 && res.status < 300) {
+            if (status >= 200 && status < 300) {
                 hints.push(`matcher ${expanded.type} did not match — ` +
                     'value may have changed or matcher is too tight');
             }
-            const result = {
-                status: res.status,
-                body,
-                matchesOriginal: false,
-            };
+            const result = { status, body, matchesOriginal: false };
             if (hints.length > 0) {
                 result.hints = hints;
             }
             return result;
         }
     }
-    return { status: res.status, body, matchesOriginal: res.status < 400 };
+    return { status, body, matchesOriginal: status < 400 };
+}
+/** Detached Node-side replay: sends the request directly from this process,
+ *  NOT from any attached browser tab — its cookies/secrets are exactly the
+ *  `secrets` passed in, never a real browser session. Used by tests and by
+ *  any caller with no live browser to replay through (the MCP's authoring
+ *  backend instead runs the SAME request inside the attached tab — see
+ *  `proof/page-replay.ts` — so replay reflects real session cookies). */
+export async function replayProvider(provider, secrets) {
+    const req = buildReplayRequest(provider, secrets);
+    const res = await fetch(req.url, {
+        method: req.method,
+        headers: req.headers,
+        redirect: 'manual',
+        ...(req.body !== undefined ? { body: req.body } : {}),
+    });
+    const body = await res.text();
+    return evaluateReplay(res.status, body, provider);
 }
 function matchesBody(body, m) {
     if (m.type === 'regex') {

package/lib/provider/dom-xpath.js

@@ -137,9 +137,10 @@ export function elementAnchor(html, targets) {
 /** 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
  *  the target — over one where the target is merely embedded in a longer string
- *  (e.g. a userid inside a `1234567+user@…` noreply address). The complete
- *  field is the semantic source and yields a portable anchor; the embedded one
- *  is incidental. Smallest byte span wins within the chosen tier. */
+ *  (for example, a userid inside a `1234567+user@…` noreply address). The
+ *  complete field is the semantic source and yields a portable anchor; the
+ *  embedded one is incidental. Smallest byte span wins within the chosen
+ *  tier. */
 function findElement(root, targets) {
     const complete = [];
     const embedded = [];
@@ -196,8 +197,8 @@ function* candidateXPaths(el) {
     }
     // A uniquely-identified DIRECT child pins the parent without a positional
     // 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.
+    // child id/attr isn't unique — for example, 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;
@@ -234,8 +235,9 @@ function distinctiveClass(cls) {
         .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`. */
+/** Positional path from `anc` (exclusive) down to `el` (inclusive), for
+ *  example `/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;
@@ -311,8 +313,8 @@ function absolutePath(el) {
 }
 /** True when `expression` selects EXACTLY `el` (one match) against `doc`. The
  *  attestor applies the redaction regex to EVERY xPath match and throws if any
- *  fails, so a non-unique selector (e.g. a class shared by sibling rows) is
- *  unusable — it must resolve to the single target element. */
+ *  fails, so a non-unique selector (for example, a class shared by sibling
+ *  rows) is unusable — it must resolve to the single target element. */
 function matchesUniquely(doc, expression, el) {
     try {
         const engine = xpath;

package/lib/provider/draft.d.ts

@@ -14,7 +14,8 @@ export interface DraftTarget {
 }
 /** The realized extraction for one target — its value paired with the
  *  redaction that reveals it (absent when matched literally). Lets a consumer
- *  validate each value against its own selector (e.g. the cloud replay). */
+ *  validate each value against its own selector (for example, the cloud
+ *  replay). */
 export interface Extraction {
     name: string;
     value: string;
@@ -30,12 +31,14 @@ export interface DraftResult {
  *  match or redaction — either a neighbouring target's value or a target's own
  *  value left un-templated. The matcher builds each target's window
  *  independently and drops the per-user WORDS it can see, but it cannot know a
- *  neighbouring value is itself user-specific (e.g. a name sharing a text node
- *  with an id — a `<b>{{id}}</b>` sitting beside a `<td>{{name}}</td>`).
- *  Cross-checking every value against every match here catches that: a portable
- *  provider contains NO captured value as a literal — each appears only as its
- *  `{{param}}`. Throwing discards the draft so the agent re-captures or
- *  re-proposes rather than shipping a provider pinned to this one user. */
+ *  neighbouring value is itself user-specific (for example, a name sharing a
+ *  text node with an id — a `<b>{{id}}</b>` sitting beside a
+ *  `<td>{{name}}</td>`). Cross-checking every value against every match here
+ *  catches
+ *  that: a portable provider contains NO captured value as a literal — each
+ *  appears only as its `{{param}}`. Throwing discards the draft so the agent
+ *  re-captures or re-proposes rather than shipping a provider pinned to this
+ *  one user. */
 export declare function assertPortableMatches(matches: ResponseMatch[], redactions: ResponseRedaction[], targets: DraftTarget[]): void;
 /** Reject a draft that OPRF-hashes a target whose value ALSO appears in the
  *  request URL. The whole point of `hash` is that the attestor never sees
@@ -57,4 +60,6 @@ export declare function assertNoOprfUrlConflict(url: string, targets: DraftTarge
  *  header (same class of problem as {@link assertNoOprfUrlConflict} for
  *  OPRF-hashed targets, which has no such budget at all). */
 export declare function assertNoSecretUrlConflict(url: string, secrets: Record<string, string>, writeRedactionMode?: ReclaimProvider['writeRedactionMode']): void;
-export declare function draftProvider(req: CapturedRequest, targets: DraftTarget[], name: string, hash?: OprfMode): DraftResult;
+export declare function draftProvider(req: CapturedRequest, targets: DraftTarget[], name: string, hash?: OprfMode, opts?: {
+    shortenNames?: boolean;
+}): DraftResult;

package/lib/provider/draft.js

@@ -63,12 +63,14 @@ function sanitizeRequestHeaders(headers) {
  *  match or redaction — either a neighbouring target's value or a target's own
  *  value left un-templated. The matcher builds each target's window
  *  independently and drops the per-user WORDS it can see, but it cannot know a
- *  neighbouring value is itself user-specific (e.g. a name sharing a text node
- *  with an id — a `<b>{{id}}</b>` sitting beside a `<td>{{name}}</td>`).
- *  Cross-checking every value against every match here catches that: a portable
- *  provider contains NO captured value as a literal — each appears only as its
- *  `{{param}}`. Throwing discards the draft so the agent re-captures or
- *  re-proposes rather than shipping a provider pinned to this one user. */
+ *  neighbouring value is itself user-specific (for example, a name sharing a
+ *  text node with an id — a `<b>{{id}}</b>` sitting beside a
+ *  `<td>{{name}}</td>`). Cross-checking every value against every match here
+ *  catches
+ *  that: a portable provider contains NO captured value as a literal — each
+ *  appears only as its `{{param}}`. Throwing discards the draft so the agent
+ *  re-captures or re-proposes rather than shipping a provider pinned to this
+ *  one user. */
 export function assertPortableMatches(matches, redactions, targets) {
     // A baked email LOCAL-PART ("jane.doe@…") pins the provider to one user
     // even when only the domain is captured as a param — the classic result of
@@ -192,7 +194,32 @@ function deriveParamName(providerName) {
     const last = tokens[tokens.length - 1] ?? 'value';
     return last.toLowerCase();
 }
-export function draftProvider(req, targets, name, hash) {
+/** A `paramName` doubles as a regex NAMED CAPTURE GROUP (`(?<name>...)`) and a
+ *  `paramValues` object key — both require a plain identifier. Nothing
+ *  downstream validates this: an invalid name builds a syntactically broken
+ *  regex that silently fails to extract at verification time instead of
+ *  erroring here, at draft time, where it's actually fixable. */
+const VALID_PARAM_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Resolve a target's `paramName`: shortened (the default — last alphanumeric
+ *  token, lowercased) or, with `shorten: false`, the name verbatim — the
+ *  caller's choice, validated so it's still safe as a capture-group
+ *  identifier. */
+function resolveParamName(targetName, shorten) {
+    if (!shorten) {
+        if (!VALID_PARAM_NAME.test(targetName)) {
+            throw new Error(`target name "${targetName}" isn't safe as a param name with `
+                + 'shortenNames:false — it becomes a regex capture-group name AND '
+                + 'a paramValues key, so it must start with a letter/underscore and '
+                + 'contain only letters, digits, and underscores (we recommend '
+                + 'lower_snake_case, for example, "employer_name"). Rename it, or drop '
+                + '`shortenNames: false` to auto-derive a safe one.');
+        }
+        return targetName;
+    }
+    return deriveParamName(targetName);
+}
+export function draftProvider(req, targets, name, hash, opts) {
+    const shortenNames = opts?.shortenNames ?? true;
     if (!req.responseBody) {
         throw new Error(`captured request ${req.requestId} has no response body`);
     }
@@ -207,14 +234,21 @@ export function draftProvider(req, targets, name, hash) {
     const extractions = [];
     const effectiveHashes = [];
     let paramValues;
-    const seenParams = new Set();
+    const seenParams = new Map();
     for (const t of targets) {
-        const paramName = deriveParamName(t.name);
-        if (seenParams.has(paramName)) {
-            throw new Error(`two targets resolve to the same param "${paramName}"; `
-                + 'give them distinct names');
+        const paramName = resolveParamName(t.name, shortenNames);
+        const priorName = seenParams.get(paramName);
+        if (priorName !== undefined) {
+            throw new Error(`targets "${priorName}" and "${t.name}" both resolve to the same `
+                + `param name "${paramName}"`
+                + (shortenNames
+                    ? ' (names are shortened to their last alphanumeric token) — '
+                        + 'give them more distinct names, for example '
+                        + '"firstName"/"surname" instead of "first_name"/"last_name"'
+                    : ' — give them distinct names, or drop `shortenNames: false` '
+                        + 'to auto-derive distinct ones'));
         }
-        seenParams.add(paramName);
+        seenParams.set(paramName, t.name);
         // 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)