@reclaimprotocol/agent 0.1.1-dev.1 → 0.1.2

package/lib/proof/index.js

@@ -0,0 +1,6 @@
+export { runAttestorProof, tailLogs, warnsAndErrors } from "./attestor.js";
+export { buildHttpParams, ensureAttestorCrypto, parseClaim, resolveAttestorUrl, } from "./proof-core.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.
+export { createClaimOnAttestor } from '@reclaimprotocol/attestor-core';

package/lib/proof/proof-core.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Shared attestor-claim plumbing used by both proof callers: the agent's MCP
+ * `run_proof` (which resolves the owner key from the credential cache and
+ * captures trace logs) and the app's verification runner (which signs with an
+ * ephemeral per-session key and builds a nested-proof claim). Only those
+ * concerns differ — building the HTTP params, resolving the attestor URL, and
+ * parsing the claim response are identical, so they live here.
+ */
+import type { ProviderParams } from '@reclaimprotocol/attestor-core';
+import type { ReclaimProvider } from '../provider/schema.ts';
+/** One-time crypto backend init for `@reclaimprotocol/tls` (idempotent). The
+ *  package ships with an empty `crypto = {}` and defers the backend to the
+ *  caller; without this the first proof dies inside the TLS client with
+ *  `crypto.randomBytes is not a function`. Shared by every attestor caller —
+ *  the agent MCP `run_proof` tool and the app's verification runner. */
+export declare function ensureAttestorCrypto(): void;
+/** Resolve the attestor websocket URL: explicit override → env → public
+ *  default. Resolved per-call so an env change or per-request override takes
+ *  effect without restarting. */
+export declare function resolveAttestorUrl(override?: string): string;
+/** Map a verification's provider recipe straight to the attestor's HTTP
+ *  params — never synthesized from captured traffic. */
+export declare function buildHttpParams(provider: ReclaimProvider): ProviderParams<'http'>;
+export interface ParsedClaim {
+    /** ProviderClaimData: provider, parameters, context, owner, identifier, … */
+    claimData?: Record<string, unknown>;
+    extractedParameters: Record<string, string>;
+    extractedValue: string;
+    identifier?: string;
+    owner?: string;
+}
+/** Pull claimData + decoded `context.extractedParameters` (plus identifier /
+ *  owner) out of a `createClaimOnAttestor` result. The full result still
+ *  carries signatures the caller may need for nested-proof building. */
+export declare function parseClaim(claim: unknown): ParsedClaim;

package/lib/proof/proof-core.js

@@ -0,0 +1,84 @@
+import { setCryptoImplementation } from '@reclaimprotocol/tls';
+import { webcryptoCrypto } from '@reclaimprotocol/tls/webcrypto';
+import { attestorUrlOverride, FALLBACK_ATTESTOR_URL } from "../consts.js";
+import { normalizeGeoLocation } from "../provider/schema.js";
+let cryptoInitialized = false;
+/** One-time crypto backend init for `@reclaimprotocol/tls` (idempotent). The
+ *  package ships with an empty `crypto = {}` and defers the backend to the
+ *  caller; without this the first proof dies inside the TLS client with
+ *  `crypto.randomBytes is not a function`. Shared by every attestor caller —
+ *  the agent MCP `run_proof` tool and the app's verification runner. */
+export function ensureAttestorCrypto() {
+    if (cryptoInitialized) {
+        return;
+    }
+    setCryptoImplementation(webcryptoCrypto);
+    cryptoInitialized = true;
+}
+/** Resolve the attestor websocket URL: explicit override → env → public
+ *  default. Resolved per-call so an env change or per-request override takes
+ *  effect without restarting. */
+export function resolveAttestorUrl(override) {
+    return (override ?? attestorUrlOverride() ?? FALLBACK_ATTESTOR_URL);
+}
+/** Map a verification's provider recipe straight to the attestor's HTTP
+ *  params — never synthesized from captured traffic. */
+export function buildHttpParams(provider) {
+    // A blank egress is treated as unset: omit it so the local proof uses the
+    // tester's own egress rather than shipping a blank or an unresolved template.
+    const geoLocation = normalizeGeoLocation(provider.geoLocation);
+    return {
+        url: provider.url,
+        method: provider.method,
+        ...(provider.headers !== undefined && { headers: provider.headers }),
+        ...(provider.body !== undefined && { body: provider.body }),
+        responseMatches: provider.responseMatches,
+        responseRedactions: provider.responseRedactions ?? [],
+        ...(provider.paramValues !== undefined && {
+            paramValues: provider.paramValues,
+        }),
+        ...(provider.writeRedactionMode !== undefined && {
+            writeRedactionMode: provider.writeRedactionMode,
+        }),
+        ...(provider.additionalClientOptions !== undefined && {
+            additionalClientOptions: provider.additionalClientOptions,
+        }),
+        ...(geoLocation !== undefined && { geoLocation }),
+    };
+}
+/** Pull claimData + decoded `context.extractedParameters` (plus identifier /
+ *  owner) out of a `createClaimOnAttestor` result. The full result still
+ *  carries signatures the caller may need for nested-proof building. */
+export function parseClaim(claim) {
+    const claimRecord = claim;
+    const claimData = claimRecord['claim'];
+    // claimData.context is a JSON-encoded string carrying
+    // { extractedParameters: {...}, providerHash, ... }.
+    let context = {};
+    const rawContext = claimData?.['context'];
+    if (typeof rawContext === 'string') {
+        try {
+            context = JSON.parse(rawContext);
+        }
+        catch {
+            // Leave context empty if it isn't valid JSON.
+        }
+    }
+    const extractedParameters = context['extractedParameters'] ?? {};
+    const parsed = {
+        extractedParameters,
+        extractedValue: Object.values(extractedParameters)[0] ?? '',
+    };
+    if (claimData) {
+        parsed.claimData = claimData;
+    }
+    const identifier = claimData?.['identifier'];
+    if (typeof identifier === 'string') {
+        parsed.identifier = identifier;
+    }
+    const owner = claimData?.['owner'];
+    if (typeof owner === 'string') {
+        parsed.owner = owner;
+    }
+    return parsed;
+}

package/lib/provider/index.d.ts

@@ -0,0 +1,5 @@
+export { extractGraphqlOp, looksLikeGraphqlEndpoint } from './graphql.ts';
+export type { CapturedRequest, HttpMethod, OprfMode, ReclaimProvider, RequestConcern, ResponseMatch, ResponseRedaction, SecretParamRef, } from './schema.ts';
+export { classifyHeader, splitSecrets } from './secrets.ts';
+export { hashProviderParams, providers } from '@reclaimprotocol/attestor-core';
+export type { ProviderParams } from '@reclaimprotocol/attestor-core';

package/lib/provider/index.js

@@ -0,0 +1,9 @@
+// Provider primitives shared with the app's capture pipeline:
+// the attestor-derived recipe types, secret classification, and the GraphQL
+// op parser. Exposed as `@reclaimprotocol/agent/provider`.
+export { extractGraphqlOp, looksLikeGraphqlEndpoint } from "./graphql.js";
+export { classifyHeader, splitSecrets } from "./secrets.js";
+// Re-exported attestor-core provider primitives (the registry, the param hash,
+// and the param type) so the builder imports them via the agent rather than
+// depending on @reclaimprotocol/attestor-core directly.
+export { hashProviderParams, providers } from '@reclaimprotocol/attestor-core';

package/lib/provider/injection-doc.d.ts

@@ -0,0 +1 @@
+export declare const INJECTION_GUIDE: string;

package/lib/provider/injection-doc.js

@@ -0,0 +1,17 @@
+/**
+ * Guidance for authoring page-injection scripts (`webSettings.jsUserScripts` on
+ * the builder, `customInjection` on old-devtools), surfaced to the authoring
+ * model from the publish tool description. The prose lives in
+ * `skill/injection-api.md` so it can be edited as markdown without touching
+ * code — the same pattern as `mcp/instructions.ts`. The path resolves the same
+ * from `src/provider` (dev) and `lib/provider` (published): both are two levels
+ * below the package root.
+ *
+ * The guide leads with plain browser JavaScript (navigation/interaction via
+ * standard APIs; the client already intercepts page requests) and treats
+ * `window.Reclaim` as a rarely-needed edge-case bridge, pointing at the
+ * authoritative `src/support/env.d.ts` rather than reproducing its surface.
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+export const INJECTION_GUIDE = readFileSync(fileURLToPath(new URL('../../skill/injection-api.md', import.meta.url)), 'utf8').trim();

package/lib/provider/match-redaction-warning.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Non-blocking advisory for a request whose `responseMatches` count is less
+ * than its `responseRedactions` count.
+ *
+ * Some verification clients (notably the InApp SDK) pair the two arrays by
+ * index and may not behave correctly when there are fewer matches than
+ * redactions. This is NOT enforced — the author keeps full control over what
+ * they publish in either old-devtools or builder mode. The tools surface these
+ * strings so the dev can make an informed decision (e.g. add a functional match
+ * per redaction) rather than being blocked.
+ */
+/** One request's match/redaction counts, with a human label for the message. */
+export interface RequestCounts {
+    label: string;
+    matchCount: number;
+    redactionCount: number;
+}
+/** Build advisory warnings for any request with matchCount < redactionCount.
+ *  Returns an empty array when everything is fine. */
+export declare function matchRedactionWarnings(requests: RequestCounts[]): string[];
+/** Counts for a single drafted request shape (provider or injected request). */
+export declare function countsFor(label: string, req: {
+    responseMatches?: unknown[];
+    responseRedactions?: unknown[];
+}): RequestCounts;

package/lib/provider/match-redaction-warning.js

@@ -0,0 +1,35 @@
+/**
+ * Non-blocking advisory for a request whose `responseMatches` count is less
+ * than its `responseRedactions` count.
+ *
+ * Some verification clients (notably the InApp SDK) pair the two arrays by
+ * index and may not behave correctly when there are fewer matches than
+ * redactions. This is NOT enforced — the author keeps full control over what
+ * they publish in either old-devtools or builder mode. The tools surface these
+ * strings so the dev can make an informed decision (e.g. add a functional match
+ * per redaction) rather than being blocked.
+ */
+/** Build advisory warnings for any request with matchCount < redactionCount.
+ *  Returns an empty array when everything is fine. */
+export function matchRedactionWarnings(requests) {
+    const warnings = [];
+    for (const req of requests) {
+        if (req.matchCount < req.redactionCount) {
+            warnings.push(`${req.label}: ${req.matchCount} response match(es) but ` +
+                `${req.redactionCount} response redaction(s). Some verification ` +
+                'clients (e.g. the InApp SDK) may not work correctly when ' +
+                'responseMatches is shorter than responseRedactions — they pair the ' +
+                'two by index. This is allowed; add a functional match per redaction ' +
+                'if you hit verification issues.');
+        }
+    }
+    return warnings;
+}
+/** Counts for a single drafted request shape (provider or injected request). */
+export function countsFor(label, req) {
+    return {
+        label,
+        matchCount: req.responseMatches?.length ?? 0,
+        redactionCount: req.responseRedactions?.length ?? 0,
+    };
+}

package/lib/provider/schema.d.ts

@@ -61,7 +61,23 @@ export interface ReclaimProvider {
     responseRedactions?: ResponseRedaction[];
     /** Public param refs (templated into URL/body), populated by draft layer. */
     paramValues?: Record<string, string>;
+    /** Redaction mode for the transcript (attestor default: 'key-update'). */
+    writeRedactionMode?: HttpParams['writeRedactionMode'];
+    /** TLS client options applied to the attestor tunnel. */
+    additionalClientOptions?: HttpParams['additionalClientOptions'];
+    /** Proxy egress: 2-letter ISO country or `{{param}}`. Blank/omitted ⇒
+     *  `{{DYNAMIC_GEO}}` on publish (resolved to the verifying user's country).
+     */
+    geoLocation?: HttpParams['geoLocation'];
 }
+/** Egress placeholder resolved to the verifying user's country at
+ *  verification time — the default when a provider declares no explicit egress.
+ */
+export declare const DYNAMIC_GEO = "{{DYNAMIC_GEO}}";
+/** `geoLocation` must never be blank. Trims the input and treats an empty
+ *  string as unset so callers apply their own default (publish → `DYNAMIC_GEO`;
+ *  a local proof omits it and uses the tester's egress). */
+export declare function normalizeGeoLocation(value: string | undefined): string | undefined;
 /** A reference to a secret param. Raw value lives only in server memory. */
 export interface SecretParamRef {
     name: string;

package/lib/provider/schema.js

@@ -1 +1,11 @@
-export {};
+/** Egress placeholder resolved to the verifying user's country at
+ *  verification time — the default when a provider declares no explicit egress.
+ */
+export const DYNAMIC_GEO = '{{DYNAMIC_GEO}}';
+/** `geoLocation` must never be blank. Trims the input and treats an empty
+ *  string as unset so callers apply their own default (publish → `DYNAMIC_GEO`;
+ *  a local proof omits it and uses the tester's egress). */
+export function normalizeGeoLocation(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : undefined;
+}

package/lib/provider/to-version.d.ts

@@ -1,22 +1,71 @@
 import type { ReclaimClient } from '@reclaimprotocol/client';
-import type { CreateProviderVersionRequest as CreateVersionBody, ProviderVersionRef as VersionRef } from '../types/openapi.ts';
-import type { ReclaimProvider } from './schema.ts';
+import type { CreateProviderVersionRequest, ProviderVersionRef } from '@reclaimprotocol/client/openapi';
+import type { HttpMethod, ReclaimProvider, ResponseMatch, ResponseRedaction } from './schema.ts';
+/** One entry of the version's `requests[]` (a `RequestSelection`), derived
+ *  from the openapi type so it can't drift from what the server accepts. */
+type RequestSelection = CreateProviderVersionRequest['requests'][number];
+/** The subset of a draft a request selection is built from — the only fields
+ *  `providerToRequestSelection` reads. A full `ReclaimProvider` satisfies it,
+ *  as does a lighter injected-request draft (no `name`/`paramValues`). */
+export interface DraftRequest {
+    url: string;
+    method: HttpMethod;
+    body?: string;
+    writeRedactionMode?: ReclaimProvider['writeRedactionMode'];
+    additionalClientOptions?: ReclaimProvider['additionalClientOptions'];
+    responseMatches?: ResponseMatch[];
+    responseRedactions?: ResponseRedaction[];
+}
+/** A request the page's injection script is allowed to fire, plus the
+ *  pagination/optionality flags of `RequestSelectionTemplate`. Reuses the
+ *  shared `DraftRequest` shape — no provider `name`/`paramValues` required. */
+export interface AllowedJsRequest extends DraftRequest {
+    /** Allow the template to match many requests (e.g. pagination). Default
+     *  true. */
+    multiple?: boolean;
+    /** Fail validation if no request matches this template. Default true. */
+    required?: boolean;
+}
+/** Optional extras for a create-version body beyond the request list. */
+export interface CreateVersionOptions {
+    notes?: string;
+    version?: ProviderVersionRef;
+    /** JS injected before every page load (`webSettings.jsUserScripts`). */
+    jsUserScripts?: string;
+    /** Requests the injection script may fire, as `RequestSelectionTemplate`s. */
+    allowedJsRequests?: AllowedJsRequest[];
+}
 /**
- * Translate a drafted ReclaimProvider into the body for
- * POST /providers/{providerId}/versions.
- *
- * `initialUrl` is the landing page the user navigated to during
- * capture — distinct from `provider.url` which is the specific
- * API URL the attestor replays.
+ * Derive the version's `requiredContext` JSON Schema from the
+ * `{{context.<name>}}` placeholders across EVERY request's url/body (plus any
+ * injected requests and the injection script) — mechanical, so a published
+ * recipe can never reference a context value the Builder doesn't require.
+ * Returns undefined when nothing references context (the field is optional).
+ * Authors can refine types/descriptions in the version editor.
+ */
+export declare function deriveRequiredContext(providers: ReclaimProvider[], injection?: {
+    allowedJsRequests?: AllowedJsRequest[];
+    jsUserScripts?: string;
+}): CreateProviderVersionRequest['requiredContext'];
+/**
+ * Translate one drafted request into a `RequestSelection`. Shared by the
+ * top-level `requests` and by `allowedJsRequests`.
  *
- * Secrets are NOT persisted — the verification client re-supplies
- * them at runtime via `credentials: 'include'`.
+ * `responseMatches`/`responseRedactions` are INDEPENDENT parallel arrays,
+ * isomorphic to the attestor's `ProviderParams<'http'>` (no nested fold).
+ * `responseRedactions` decide which portions of the response are revealed;
+ * `responseMatches` then run against the union of the revealed content. Neither
+ * depends on the other's length or order, so both pass through untouched.
+ * (The old-devtools translator has its own opt-in index-pairing concern; the
+ * builder deliberately does not.)
  */
-export declare function providerToCreateVersionRequest(provider: ReclaimProvider, initialUrl: string, notes?: string, version?: VersionRef): CreateVersionBody;
+export declare function providerToRequestSelection(provider: DraftRequest): RequestSelection;
+export declare function providerToCreateVersionRequest(providers: ReclaimProvider[], initialUrl: string, opts?: CreateVersionOptions): CreateProviderVersionRequest;
 /**
  * Fetch the current versions for a provider and return the next version above
  * the highest existing one (bumping the patch number), or 1.0.0 when the
  * provider has no versions yet. A failed lookup propagates — silently
  * resetting to 1.0.0 would re-publish a v3 provider as v1.0.0.
  */
-export declare function nextVersion(client: ReclaimClient, providerId: string): Promise<VersionRef>;
+export declare function nextVersion(client: ReclaimClient, providerId: string): Promise<ProviderVersionRef>;
+export {};

package/lib/provider/to-version.js

@@ -1,3 +1,4 @@
+import { DYNAMIC_GEO, normalizeGeoLocation } from "./schema.js";
 /**
  * Translate a drafted ReclaimProvider into the body for
  * POST /providers/{providerId}/versions.
@@ -9,34 +10,118 @@
  * Secrets are NOT persisted — the verification client re-supplies
  * them at runtime via `credentials: 'include'`.
  */
-export function providerToCreateVersionRequest(provider, initialUrl, notes, version) {
-    // Inline responseRedactions into matches[*].extract (1-to-1 by index).
-    const matches = (provider.responseMatches ?? []).map((match, i) => {
-        const redaction = provider.responseRedactions?.[i];
-        return {
-            type: match.type,
-            value: match.value,
-            isOptional: false,
-            ...(redaction ? { extract: redaction } : {}),
-        };
+/** `{{context.<name>}}` placeholders in a request URL/body: values the
+ *  CONSUMER supplies at verification time via the session `context`. Bare
+ *  `{{name}}` placeholders (extraction params) are not consumer-supplied
+ *  and are ignored. */
+const CONTEXT_PARAM_RE = /\{\{context\.([A-Za-z_][A-Za-z0-9_]*)\}\}/g;
+/**
+ * Derive the version's `requiredContext` JSON Schema from the
+ * `{{context.<name>}}` placeholders across EVERY request's url/body (plus any
+ * injected requests and the injection script) — mechanical, so a published
+ * recipe can never reference a context value the Builder doesn't require.
+ * Returns undefined when nothing references context (the field is optional).
+ * Authors can refine types/descriptions in the version editor.
+ */
+export function deriveRequiredContext(providers, injection = {}) {
+    const parts = [];
+    for (const p of [...providers, ...(injection.allowedJsRequests ?? [])]) {
+        parts.push(p.url, p.body ?? '');
+    }
+    if (injection.jsUserScripts) {
+        parts.push(injection.jsUserScripts);
+    }
+    const haystack = parts.join('\n');
+    const names = new Set();
+    for (const m of haystack.matchAll(CONTEXT_PARAM_RE)) {
+        names.add(m[1]);
+    }
+    if (!names.size) {
+        return undefined;
+    }
+    const properties = {};
+    for (const name of names) {
+        properties[name] = { type: 'string' };
+    }
+    return { type: 'object', required: [...names], properties };
+}
+/**
+ * Translate one drafted request into a `RequestSelection`. Shared by the
+ * top-level `requests` and by `allowedJsRequests`.
+ *
+ * `responseMatches`/`responseRedactions` are INDEPENDENT parallel arrays,
+ * isomorphic to the attestor's `ProviderParams<'http'>` (no nested fold).
+ * `responseRedactions` decide which portions of the response are revealed;
+ * `responseMatches` then run against the union of the revealed content. Neither
+ * depends on the other's length or order, so both pass through untouched.
+ * (The old-devtools translator has its own opt-in index-pairing concern; the
+ * builder deliberately does not.)
+ */
+export function providerToRequestSelection(provider) {
+    const responseMatches = (provider.responseMatches ?? []).map((match) => ({
+        type: match.type,
+        value: match.value,
+        isOptional: false,
+    }));
+    const responseRedactions = provider.responseRedactions ?? [];
+    return {
+        url: provider.url,
+        method: provider.method,
+        credentials: 'include',
+        ...(provider.body ? { requestBodyTemplate: provider.body } : {}),
+        ...(provider.writeRedactionMode
+            ? { writeRedactionMode: provider.writeRedactionMode }
+            : {}),
+        ...(provider.additionalClientOptions
+            ? { additionalClientOptions: provider.additionalClientOptions }
+            : {}),
+        ...(responseMatches.length > 0 ? { responseMatches } : {}),
+        ...(responseRedactions.length > 0 ? { responseRedactions } : {}),
+    };
+}
+/** First provider that declares an explicit (non-default) egress wins; if none
+ *  do, fall back to DYNAMIC_GEO (resolved to the verifying user's country). */
+function pickGeoLocation(providers) {
+    for (const provider of providers) {
+        const geo = normalizeGeoLocation(provider.geoLocation);
+        if (geo) {
+            return geo;
+        }
+    }
+    return DYNAMIC_GEO;
+}
+export function providerToCreateVersionRequest(providers, initialUrl, opts = {}) {
+    const { notes, version, jsUserScripts, allowedJsRequests } = opts;
+    const requiredContext = deriveRequiredContext(providers, {
+        allowedJsRequests,
+        jsUserScripts,
     });
+    // Each injected request carries its template flags (default true/true per
+    // RequestSelectionTemplate) on top of the shared request shape.
+    const allowedJs = (allowedJsRequests ?? []).map((req) => ({
+        ...providerToRequestSelection(req),
+        multiple: req.multiple ?? true,
+        required: req.required ?? true,
+    }));
+    const script = jsUserScripts?.trim();
     return {
         version: version ?? { major: 1, minor: 0, patch: 0 },
         initialUrl,
-        requests: [
-            {
-                url: provider.url,
-                method: provider.method,
-                credentials: 'include',
-                ...(provider.body ? { requestBodyTemplate: provider.body } : {}),
-                ...(matches.length > 0 ? { matches } : {}),
-            },
-        ],
-        allowedJsRequests: [],
-        webSettings: { geoLocation: '{{DYNAMIC_GEO}}' },
-        ...(provider.paramValues
-            ? { requiredParameters: provider.paramValues }
-            : {}),
+        // Every drafted provider becomes one request — the recipe runs them all.
+        requests: providers.map(providerToRequestSelection),
+        allowedJsRequests: allowedJs,
+        // Mirror the builder openapi defaults explicitly — the server does not
+        // apply schema defaults to request bodies.
+        webSettings: {
+            geoLocation: pickGeoLocation(providers),
+            clientOptions: { portal: { useProxy: true } },
+            // Only set when non-empty; an empty string would store a no-op script.
+            ...(script ? { jsUserScripts: script } : {}),
+        },
+        // Derived from `{{context.<name>}}` placeholders only — a captured
+        // provider's `paramValues` are extracted response parameters, not
+        // consumer context, and never become requiredContext.
+        ...(requiredContext ? { requiredContext } : {}),
         ...(notes ? { notes } : {}),
     };
 }

package/lib/provider/verification-checks.d.ts

@@ -0,0 +1,12 @@
+import type { ReclaimProvider } from './schema.ts';
+/**
+ * Advisory pre-publish lint for a drafted provider — never a gate. Surfaces
+ * only what the AUTHOR must decide; everything testable is tested by the
+ * verification client itself (CDP capture sees all traffic — navigations,
+ * XHRs, fetches — and `checkCandidate` in packages/app src/verify/run.ts
+ * selects the captured request that satisfies the recipe, skipping the
+ * rest). Interpolation and matching are plain text and work for any
+ * captured content; extract selectors apply client-side in spec order
+ * xPath → jsonPath → regex, each to the prior selection.
+ */
+export declare function verificationWarnings(provider: ReclaimProvider): string[];

package/lib/provider/verification-checks.js

@@ -0,0 +1,30 @@
+/**
+ * Advisory pre-publish lint for a drafted provider — never a gate. Surfaces
+ * only what the AUTHOR must decide; everything testable is tested by the
+ * verification client itself (CDP capture sees all traffic — navigations,
+ * XHRs, fetches — and `checkCandidate` in packages/app src/verify/run.ts
+ * selects the captured request that satisfies the recipe, skipping the
+ * rest). Interpolation and matching are plain text and work for any
+ * captured content; extract selectors apply client-side in spec order
+ * xPath → jsonPath → regex, each to the prior selection.
+ */
+export function verificationWarnings(provider) {
+    const out = [];
+    // Untemplated user-specific URL parts: any captured param value baked
+    // literally into the URL makes the provider user-specific. Only the dev
+    // can decide: consumer-supplied → {{context.<name>}} (declared in
+    // requiredContext; consumers then send the exact value and the VC matches
+    // only that value), bare {{<name>}} (resolved from the end-user's own
+    // traffic), or re-capture a non-user-specific endpoint.
+    for (const [name, value] of Object.entries(provider.paramValues ?? {})) {
+        if (value.length >= 3 && provider.url.includes(value)) {
+            out.push(`The URL contains the captured value "${value}" (param ` +
+                `"${name}") as a literal. Decide with the dev: if consumers ` +
+                'supply it, replace with {{context.' + name + '}} (published ' +
+                'requiredContext will require it; verification matches only ' +
+                'the supplied value). Leaving it literal pins the provider ' +
+                'to this user.');
+        }
+    }
+    return out;
+}