@reclaimprotocol/agent 0.1.1 → 0.1.2

package/lib/mcp/tools/verification/build.d.ts

@@ -3,7 +3,7 @@ import type { RegisteredTool } from '../../server.ts';
  * Builder-mode verification tools: higher-level orchestrations over the
  * generated API surface. `get_verification_result` authenticates with the org
  * token, checks status, pulls the stored payload, and decrypts it locally with
- * the optional X25519 key — a flow the generated raw-API tools can't express
+ * the optional eth key — a flow the generated raw-API tools can't express
  * (the decryption key never leaves the consumer). Diagnosis is left to the
  * agent over the generated tools (`get_verification_session`,
  * `list_verification_events`, `list_verification_deliveries`), whose

package/lib/mcp/tools/verification/build.js

@@ -3,7 +3,7 @@ import { verificationResultTool } from "./result.js";
  * Builder-mode verification tools: higher-level orchestrations over the
  * generated API surface. `get_verification_result` authenticates with the org
  * token, checks status, pulls the stored payload, and decrypts it locally with
- * the optional X25519 key — a flow the generated raw-API tools can't express
+ * the optional eth key — a flow the generated raw-API tools can't express
  * (the decryption key never leaves the consumer). Diagnosis is left to the
  * agent over the generated tools (`get_verification_session`,
  * `list_verification_events`, `list_verification_deliveries`), whose

package/lib/mcp/tools/verification/result.d.ts

@@ -3,10 +3,9 @@ import { type RegisteredTool } from '../../server.ts';
  * `get_verification_result` — check a session's status and, once a result has
  * been submitted, pull the stored payload(s) and verify locally. Auth is the
  * org token; delivery is org-scoped. Each stored payload is either the
- * plaintext signed JWS (when the org has no encryption credential) or a compact
- * JWE (RFC 7516, ECDH-ES+A256GCM over X25519) that we decrypt here with the
- * optional X25519 key (the `reclaim-decrypt.pem` PEM in the project). The
- * Builder only ever relays the payload — decryption, when needed, happens
- * here.
+ * plaintext signed JWS (when the org's encryption is off) or an ECIES
+ * ciphertext that we decrypt here with the optional eth key
+ * (`RECLAIM_DECRYPT_KEY` or the `reclaim-decrypt.key` hex file). The Builder
+ * only ever relays the payload — decryption, when needed, happens here.
  */
 export declare function verificationResultTool(): RegisteredTool;

package/lib/mcp/tools/verification/result.js

@@ -1,5 +1,6 @@
-import { createReclaim, decryptCallback, DEFAULT_BASE_URL, verifyResultFull, } from '@reclaimprotocol/client';
+import { createReclaim, decryptCallback, verifyResultFull, } from '@reclaimprotocol/client';
 import assert from 'node:assert';
+import { apiUrl, orgSecret } from "../../../consts.js";
 import { defineTool } from "../../server.js";
 import { resolveDecryptionKey } from "../authenticate/decrypt-key.js";
 /** Statuses that can carry a submitted (terminal) result. `expired`/`pending`
@@ -11,7 +12,7 @@ const TERMINAL = new Set(['success', 'rejected', 'error']);
  * `RECLAIM_ORG_SECRET`.
  */
 function resolveOrgSecret() {
-    const secret = process.env.RECLAIM_ORG_SECRET?.trim();
+    const secret = orgSecret()?.trim();
     assert(secret, new Error('RECLAIM_ORG_SECRET is not set. Verification reads authenticate with ' +
         'the org secret (rorg_…) — issue one from the dashboard ' +
         '(POST /orgs/{orgId}/token) and export it as RECLAIM_ORG_SECRET.'));
@@ -21,11 +22,10 @@ function resolveOrgSecret() {
  * `get_verification_result` — check a session's status and, once a result has
  * been submitted, pull the stored payload(s) and verify locally. Auth is the
  * org token; delivery is org-scoped. Each stored payload is either the
- * plaintext signed JWS (when the org has no encryption credential) or a compact
- * JWE (RFC 7516, ECDH-ES+A256GCM over X25519) that we decrypt here with the
- * optional X25519 key (the `reclaim-decrypt.pem` PEM in the project). The
- * Builder only ever relays the payload — decryption, when needed, happens
- * here.
+ * plaintext signed JWS (when the org's encryption is off) or an ECIES
+ * ciphertext that we decrypt here with the optional eth key
+ * (`RECLAIM_DECRYPT_KEY` or the `reclaim-decrypt.key` hex file). The Builder
+ * only ever relays the payload — decryption, when needed, happens here.
  */
 export function verificationResultTool() {
     return defineTool({
@@ -34,9 +34,9 @@ export function verificationResultTool() {
             'Authenticates with the org secret (RECLAIM_ORG_SECRET). Fetches the ' +
             'session status; if it is terminal and a result has been submitted, ' +
             'pulls the stored result(s) and verifies them locally. Encrypted ' +
-            'deliveries (compact JWE over X25519) are decrypted with your ' +
-            'optional decryption key (the reclaim-decrypt.pem PEM in the ' +
-            'project); plaintext deliveries are read directly. Returns ' +
+            'deliveries (ECIES over secp256k1) are decrypted with your optional ' +
+            'eth key (RECLAIM_DECRYPT_KEY or reclaim-decrypt.key); plaintext ' +
+            'deliveries are read directly. Returns ' +
             '`ready: false` while the session is still pending or no result has ' +
             'been delivered yet. Use list_verification_events for the full ' +
             'lifecycle log.',
@@ -51,12 +51,12 @@ export function verificationResultTool() {
             },
         },
     }, async (args) => {
-        const orgSecret = resolveOrgSecret();
-        // Optional X25519 decryption key — absent ⇒ plaintext-only.
+        const secret = resolveOrgSecret();
+        // Optional eth decryption key — absent ⇒ plaintext-only.
         const decryptionKey = await resolveDecryptionKey();
         const reclaim = createReclaim({
-            baseUrl: process.env.RECLAIM_API_URL || DEFAULT_BASE_URL,
-            orgSecret,
+            baseUrl: apiUrl(),
+            orgSecret: secret,
         });
         const sessionRes = await reclaim.api('GetVerificationSession', {
             params: { sessionId: args.sessionId },
@@ -110,9 +110,9 @@ export function verificationResultTool() {
                 status,
                 ready: false,
                 note: 'A result was stored, but no payload could be read — it is ' +
-                    'corrupt, or encrypted (JWE) to a key this consumer does not ' +
-                    'hold. Place an X25519 PEM (reclaim-decrypt.pem) in the ' +
-                    'project matching the org credential.',
+                    'corrupt, or encrypted (ECIES) to a key this consumer does not ' +
+                    'hold. Set RECLAIM_DECRYPT_KEY (or reclaim-decrypt.key) to the ' +
+                    'eth private key matching the org keypair.',
             };
         }
         return {

package/lib/old/flag.d.ts

@@ -7,5 +7,8 @@
  * EXPLICITLY by setting `USE_OLD_DEVTOOLS=false`. Anything else — unset,
  * empty, `true`, `1`, a typo — keeps old mode on, so a forgotten env var
  * can never silently route a developer at the half-built builder backend.
+ *
+ * The actual env read lives in `../consts.ts` (the single env-access module);
+ * this widely-imported path re-exports it for back-compat.
  */
-export declare function useOldDevtools(): boolean;
+export { useOldDevtools } from '../consts.ts';

package/lib/old/flag.js

@@ -7,7 +7,8 @@
  * EXPLICITLY by setting `USE_OLD_DEVTOOLS=false`. Anything else — unset,
  * empty, `true`, `1`, a typo — keeps old mode on, so a forgotten env var
  * can never silently route a developer at the half-built builder backend.
+ *
+ * The actual env read lives in `../consts.ts` (the single env-access module);
+ * this widely-imported path re-exports it for back-compat.
  */
-export function useOldDevtools() {
-    return (process.env.USE_OLD_DEVTOOLS ?? '').trim().toLowerCase() !== 'false';
-}
+export { useOldDevtools } from "../consts.js";

package/lib/old/identity.d.ts

@@ -2,16 +2,6 @@ import type { OldIdentity } from './client.ts';
 /** Normalize an eth uid input to `eth:<lowercase-address>`. Accepts a bare
  *  `0x…` address or an already-prefixed `eth:0x…`. */
 export declare function toEthUid(addressOrUid: string): OldIdentity;
-/**
- * Resolve a caller identity from the environment, in priority order:
- *   1. `RECLAIM_OLD_API_TOKEN` — a dashboard Firebase bearer token.
- *   2. `RECLAIM_OLD_ETH_UID`   — an `eth:<addr>` (or bare `0x…`) uid.
- *   3. `RECLAIM_PRIVATE_KEY`   — derive the eth uid from the local app key.
- * Returns undefined when none is set.
- */
-export declare function resolveIdentityFromEnv(): OldIdentity | undefined;
-/** Read the identity persisted by a prior `reclaim_authenticate` call. */
-export declare function loadPersistedIdentity(): OldIdentity | undefined;
 /** Persist the identity so it survives an MCP-server restart. */
 export declare function persistIdentity(identity: OldIdentity): void;
 /**

package/lib/old/identity.js

@@ -1,5 +1,6 @@
 import { deriveFromPrivateKey } from '@reclaimprotocol/client';
 import { ConfigStore } from "../config/store.js";
+import { oldApiToken, oldEthUid, privateKey } from "../consts.js";
 /** Normalize an eth uid input to `eth:<lowercase-address>`. Accepts a bare
  *  `0x…` address or an already-prefixed `eth:0x…`. */
 export function toEthUid(addressOrUid) {
@@ -14,23 +15,23 @@ export function toEthUid(addressOrUid) {
  *   3. `RECLAIM_PRIVATE_KEY`   — derive the eth uid from the local app key.
  * Returns undefined when none is set.
  */
-export function resolveIdentityFromEnv() {
-    const token = process.env.RECLAIM_OLD_API_TOKEN?.trim();
+function resolveIdentityFromEnv() {
+    const token = oldApiToken()?.trim();
     if (token) {
         return { kind: 'bearer', token };
     }
-    const ethUid = process.env.RECLAIM_OLD_ETH_UID?.trim();
+    const ethUid = oldEthUid()?.trim();
     if (ethUid) {
         return toEthUid(ethUid);
     }
-    const privateKey = process.env.RECLAIM_PRIVATE_KEY?.trim();
-    if (privateKey) {
-        return toEthUid(deriveFromPrivateKey(privateKey).address);
+    const key = privateKey()?.trim();
+    if (key) {
+        return toEthUid(deriveFromPrivateKey(key).address);
     }
     return undefined;
 }
 /** Read the identity persisted by a prior `reclaim_authenticate` call. */
-export function loadPersistedIdentity() {
+function loadPersistedIdentity() {
     return new ConfigStore().read()?.old_devtools;
 }
 /** Persist the identity so it survives an MCP-server restart. */

package/lib/old/login-cdp.d.ts

@@ -1,6 +1,3 @@
-/** The devtools dashboard login page. Override per-call or via
- *  `RECLAIM_OLD_LOGIN_URL`. */
-export declare const DEFAULT_LOGIN_URL = "https://dev.reclaimprotocol.org";
 export interface CdpLoginResult {
     token: string;
     /** True when we launched (and then closed) a dedicated Chrome just for

package/lib/old/login-cdp.js

@@ -1,9 +1,7 @@
 import { connectCdp } from "../cdp/client.js";
 import { defaultProfileDir, launchChrome, waitForCdpReady, } from "../cdp/launcher.js";
 import { ConfigStore } from "../config/store.js";
-/** The devtools dashboard login page. Override per-call or via
- *  `RECLAIM_OLD_LOGIN_URL`. */
-export const DEFAULT_LOGIN_URL = 'https://dev.reclaimprotocol.org';
+import { DEFAULT_LOGIN_URL, oldLoginUrl } from "../consts.js";
 /**
  * Read the Firebase ID token the dashboard persisted after login.
  *
@@ -64,7 +62,7 @@ const EXTRACT_TOKEN_JS = `(async () => {
  * disrupt it.
  */
 export async function captureFirebaseTokenViaCdp(opts) {
-    const loginUrl = opts.loginUrl || process.env.RECLAIM_OLD_LOGIN_URL || DEFAULT_LOGIN_URL;
+    const loginUrl = opts.loginUrl || oldLoginUrl() || DEFAULT_LOGIN_URL;
     const timeoutMs = opts.timeoutMs ?? 180_000;
     const pollMs = opts.pollMs ?? 1000;
     const cfg = new ConfigStore().read()?.browser_agent;

package/lib/old/to-register.js

@@ -29,15 +29,12 @@ function requestDataFromProvider(provider) {
         order: i,
     }));
     // Old devtools wants `responseMatches` and `responseRedactions` as PARALLEL
-    // arrays. A drafted provider may instead carry each redaction nested in its
-    // match's `extract` (the builder shape). Prefer the explicit parallel array;
-    // fall back to the nested `extract`s so redactions are never dropped.
-    const nestedRedactions = provider.responseMatches
-        .map((m) => m.extract)
-        .filter((e) => Boolean(e));
-    const sourceRedactions = provider.responseRedactions?.length
-        ? provider.responseRedactions
-        : nestedRedactions;
+    // arrays — same shape the builder uses, so pass them through directly. We do
+    // NOT enforce any match/redaction count relationship here (and never pad —
+    // empty placeholder matches break proof generation): the author keeps full
+    // control. The publish tool surfaces a non-blocking warning when matches <
+    // redactions (see `matchRedactionWarnings`), and the dev decides.
+    const sourceRedactions = provider.responseRedactions ?? [];
     const responseRedactions = sourceRedactions.map((r, i) => {
         const out = { order: i };
         if (r.xPath !== undefined) {

package/lib/old/tools/authenticate.js

@@ -1,3 +1,4 @@
+import { agentDisabled } from "../../consts.js";
 import { defineTool } from "../../mcp/server.js";
 import { persistIdentity, toEthUid } from "../identity.js";
 import { captureFirebaseTokenViaCdp } from "../login-cdp.js";
@@ -108,7 +109,7 @@ export function authenticateTool(client) {
             }
         }
         // CDP browser login (the default headline flow).
-        if (process.env.RECLAIM_AGENT_DISABLED === '1') {
+        if (agentDisabled()) {
             throw new Error('Browser login is unavailable (RECLAIM_AGENT_DISABLED=1). Pass a ' +
                 '`token` (Firebase ID token) or `ethAddress` instead.');
         }

package/lib/old/tools/publish.js

@@ -1,6 +1,32 @@
+import { Boom, isBoom } from '@hapi/boom';
 import { defineTool } from "../../mcp/server.js";
+import { countsFor, matchRedactionWarnings, } from "../../provider/match-redaction-warning.js";
 import { bumpPatchString, extractVersions, providerToConfigBody, providerToRegisterBody, } from "../to-register.js";
 const DEFAULT_VERSION_INFO = 'Updated from MCP browser capture';
+/**
+ * The old backend lets you add a version only to a provider YOU own. A
+ * `providerId` for a public provider (or anyone else's) comes back as
+ * 401/403/404 — the dev's likely intent is to publish their OWN version of that
+ * site, which on this backend means registering a separate copy. Rethrow those
+ * failures with that actionable suggestion; leave other errors (e.g. a 400
+ * version collision) untouched so their real detail surfaces.
+ */
+function rethrowOwnershipError(err, providerId) {
+    const status = isBoom(err) ? err.output.statusCode : undefined;
+    if (status !== 401 && status !== 403 && status !== 404) {
+        throw err;
+    }
+    const base = isBoom(err) ? err.message : String(err);
+    throw new Boom(`${base} — could not add a version to provider ${providerId}. You can ` +
+        'only publish new versions on providers you own. If this is a public ' +
+        "provider (or one you don't own), re-run " +
+        'create_provider_version_from_capture WITHOUT `providerId` to register ' +
+        "your own copy. If it IS yours, confirm you're authenticated " +
+        '(reclaim_authenticate) as the account that created it.', {
+        statusCode: status,
+        data: isBoom(err) ? err.data : { status, detail: base },
+    });
+}
 /**
  * Publish a drafted provider to the OLD devtools backend. Keeps the builder
  * tool NAME (`create_provider_version_from_capture`) so the skill flow is
@@ -25,6 +51,10 @@ export function createVersionFromCaptureTool(client) {
             '1.0.0; re-running creates a duplicate). Pass `providerId` (from ' +
             'get_me_providers) to add a NEW VERSION to that existing provider ' +
             '(the patch is auto-bumped). \n\n' +
+            'You can only add versions to a provider YOU own — the `providerId` ' +
+            'must come from get_me_providers. To publish your own version of a ' +
+            "PUBLIC provider you don't own, omit `providerId` to register your " +
+            'own copy (you cannot edit someone else\'s provider here). \n\n' +
             'Captured requests must be GET/POST. OPRF redactions are supported.',
         inputSchema: {
             type: 'object',
@@ -91,19 +121,38 @@ export function createVersionFromCaptureTool(client) {
         if (args.providerType !== undefined) {
             opts.providerType = args.providerType;
         }
+        // Non-blocking advisory — never alters or blocks the publish; the
+        // author keeps full control. Attaches under `_notes` when relevant.
+        const notes = matchRedactionWarnings([
+            countsFor('Request', args.provider),
+        ]);
+        const withNotes = (result) => {
+            if (notes.length && result && typeof result === 'object') {
+                return { ...result, _notes: notes };
+            }
+            return result;
+        };
         // New provider.
         if (!args.providerId) {
             const body = providerToRegisterBody(args.provider, opts);
-            return client.registerProvider(body);
+            return withNotes(await client.registerProvider(body));
         }
         // New version of an existing provider — pick the next patch above
-        // the highest existing version.
-        const versionsResp = await client.listVersions(args.providerId);
-        const version = bumpPatchString(extractVersions(versionsResp));
-        const versionInfo = args.notes && args.notes.trim().length >= 10
-            ? args.notes.trim()
-            : DEFAULT_VERSION_INFO;
-        const body = providerToConfigBody(args.provider, opts, version, versionInfo);
-        return client.updateProviderConfig(args.providerId, body);
+        // the highest existing version. A provider you don't own (e.g. a
+        // public one) fails here with 401/403/404; surface the register-a-copy
+        // workaround instead of a bare permission error.
+        const providerId = args.providerId;
+        try {
+            const versionsResp = await client.listVersions(providerId);
+            const version = bumpPatchString(extractVersions(versionsResp));
+            const versionInfo = args.notes && args.notes.trim().length >= 10
+                ? args.notes.trim()
+                : DEFAULT_VERSION_INFO;
+            const body = providerToConfigBody(args.provider, opts, version, versionInfo);
+            return withNotes(await client.updateProviderConfig(providerId, body));
+        }
+        catch (err) {
+            rethrowOwnershipError(err, providerId);
+        }
     });
 }

package/lib/paths.js

@@ -1,12 +1,12 @@
 import { existsSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
+import { reclaimHome } from "./consts.js";
 /**
  * Resolve the Reclaim cache directory (`~/.reclaim`). Honours the
  * `RECLAIM_HOME` env var as an override so tests can sandbox writes.
  */
 export function reclaimHomeDirPath() {
-    return process.env.RECLAIM_HOME || join(homedir(), '.reclaim');
+    return reclaimHome();
 }
 /**
  * Walk up from `start` until we find a directory containing one of

package/lib/proof/attestor.js

@@ -7,6 +7,7 @@
 // reveals), never on responseMatches.
 import { bytesToHex } from '@noble/hashes/utils.js';
 import { createClaimOnAttestor, } from '@reclaimprotocol/attestor-core';
+import { agentTraceEnabled } from "../consts.js";
 import { resolveEthKey } from "../mcp/tools/authenticate/eth-key.js";
 import { buildHttpParams, ensureAttestorCrypto, parseClaim, resolveAttestorUrl, } from "./proof-core.js";
 import { ensureZkFiles } from "./zk-files.js";
@@ -136,7 +137,7 @@ export async function runAttestorProof(provider, secrets, opts = {}) {
         // trace/debug entries during ZK setup). Flip RECLAIM_AGENT_TRACE=1 to
         // turn it back on when something's broken; logs flow into the proof
         // response and into the on-disk proof-runs dump.
-        const traceEnabled = process.env['RECLAIM_AGENT_TRACE'] === '1';
+        const traceEnabled = agentTraceEnabled();
         const capture = traceEnabled ? makeCaptureLogger() : undefined;
         const attestorLogs = capture?.entries;
         let claim;

package/lib/proof/proof-core.js

@@ -1,6 +1,7 @@
 import { setCryptoImplementation } from '@reclaimprotocol/tls';
 import { webcryptoCrypto } from '@reclaimprotocol/tls/webcrypto';
-const FALLBACK_ATTESTOR_URL = 'wss://attestor.reclaimprotocol.org:444/ws';
+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
@@ -18,11 +19,14 @@ export function ensureAttestorCrypto() {
  *  default. Resolved per-call so an env change or per-request override takes
  *  effect without restarting. */
 export function resolveAttestorUrl(override) {
-    return (override ?? process.env['RECLAIM_ATTESTOR_URL'] ?? FALLBACK_ATTESTOR_URL);
+    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,
@@ -33,6 +37,13 @@ export function buildHttpParams(provider) {
         ...(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 /

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,15 +1,66 @@
 import type { ReclaimClient } from '@reclaimprotocol/client';
 import type { CreateProviderVersionRequest, ProviderVersionRef } from '@reclaimprotocol/client/openapi';
-import type { ReclaimProvider } from './schema.ts';
+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[];
+}
 /**
  * Derive the version's `requiredContext` JSON Schema from the
- * `{{context.<name>}}` placeholders in the provider's url/body — mechanical,
- * so a published recipe can never reference a context value the Builder
- * doesn't require. Returns undefined when the recipe has none (the field is
- * optional). Authors can refine types/descriptions in the version editor.
+ * `{{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(provider: ReclaimProvider): CreateProviderVersionRequest['requiredContext'];
-export declare function providerToCreateVersionRequest(provider: ReclaimProvider, initialUrl: string, notes?: string, version?: ProviderVersionRef): CreateProviderVersionRequest;
+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`.
+ *
+ * `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 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
@@ -17,3 +68,4 @@ export declare function providerToCreateVersionRequest(provider: ReclaimProvider
  * resetting to 1.0.0 would re-publish a v3 provider as v1.0.0.
  */
 export declare function nextVersion(client: ReclaimClient, providerId: string): Promise<ProviderVersionRef>;
+export {};