@reclaimprotocol/agent 0.1.1 → 0.1.3

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 {};

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.
@@ -16,13 +17,21 @@
 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 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 function deriveRequiredContext(provider) {
-    const haystack = `${provider.url}\n${provider.body ?? ''}`;
+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]);
@@ -36,36 +45,78 @@ export function deriveRequiredContext(provider) {
     }
     return { type: 'object', required: [...names], properties };
 }
-export function providerToCreateVersionRequest(provider, initialUrl, notes, version) {
-    const requiredContext = deriveRequiredContext(provider);
-    // 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 } : {}),
-        };
+/**
+ * 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: [],
+        // 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: '{{DYNAMIC_GEO}}',
+            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

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@reclaimprotocol/agent",
 	"title": "Reclaim Agent",
-	"version": "0.1.1",
+	"version": "0.1.3",
 	"description": "Reclaim Protocol agent — SDK, CLI, and MCP server in one package. SDK + CLI talk to the builder backend; MCP server adds Chrome CDP capture, provider synthesis, replay, and zkTLS proof.",
 	"type": "module",
 	"main": "./lib/index.js",

package/skill/builder-mode.md

@@ -2,8 +2,14 @@ This server targets the Reclaim BUILDER backend. It exposes three tool layers: g
 
 **Authentication:** try `get_me` first. On 401, `authenticate({})` opens a device-pairing session — give the user the `attachUrl`, then poll `authenticate({ code })` until LINKED. Tokens are cached ~2 days.
 
-**Provider-authoring flow:** `attach_chrome` → `start_capture` → drive the page (`navigate`, `wait_for_page`) → inspect (`list_requests`, `get_request`, `find_requests_containing`) → `propose_provider` → `replay_request` → `run_proof` → `create_provider_version_from_capture` (lands on the draft branch) → `publish_provider_version` (PRIVATE) or `submit_provider_version_for_review` (PUBLIC).
+**Provider-authoring flow:** `attach_chrome` → `start_capture` → drive the page (`navigate`, `wait_for_page`) → inspect (`list_requests`, `get_request`, `find_requests_containing`) → `propose_provider` → `replay_request` → `run_proof` → resolve a `providerId` (**Reuse before create**, below) → `create_provider_version_from_capture` (lands on the draft branch) → `publish_provider_version` (PRIVATE) or `submit_provider_version_for_review` (PUBLIC).
+
+**Reuse before create (avoid duplicates):** `create_provider_version_from_capture` requires a `providerId`. Before minting a new one with `create_provider`, search your existing providers with `providers` (by domain / data point) — a site you've already built will be there. If one matches, pass its `providerId` so the capture lands as a NEW VERSION on that provider. Only `create_provider` (then use its returned id) when none exists. Re-running the flow against `create_provider` each time is what stacks duplicate providers in "My providers".
+
+**Multiple requests & login-gated data:** one version can carry many requests — `propose_provider` + `run_proof` each target request individually, then publish them together via `create_provider_version_from_capture({ providers: [draftA, draftB, …] })` (every entry is required at verification; the single-`provider` form still works for the one-request case). For data gated behind login/navigation, supply `jsUserScripts` — plain page JavaScript if needed that drives login/waits for user to login/waits for user to do multifactor auth/navigation with standard browser APIs (`window.location`, clicking elements, submitting forms) so the target request fires (page requests are intercepted automatically; `window.Reclaim` is only for rare edge cases) — and/or `allowedJsRequests` (extra requests the script may fire, e.g. pagination). NOTE: the builder verification client installs `jsUserScripts` to run before every page load (before navigating to `initialUrl`), matching the old-devtool `customInjection`; `window.Reclaim` itself is not yet exposed there, so prefer plain browser JS.
 
 **Templating:** bare `{{name}}` placeholders are provider params (values extracted from the response by the attestor). Values the CONSUMER must supply at verification time (e.g. a username in the URL path) are templated `{{context.<name>}}` and declared on the version as `requiredContext` — a JSON Schema set via `update_provider_version` while the version is on draft. The Builder validates every session-create's `context` against it (400 on mismatch; extra context fields are always allowed). `requiredContext` is optional — skip it when the recipe has no `{{context.*}}` placeholders. At verification time, requests are matched by exact origin+path: `{{context.<name>}}` segments match the consumer-sent value only, bare `{{name}}` values are extracted from the live traffic (plain-text alignment — works for JSON, XML, HTML, form-encoded, any text). Extract selectors apply client-side in spec order xPath → jsonPath → regex, each to the prior selection, so only the first selector constrains the full response; responses that cannot satisfy it (or miss a required match) are skipped. `propose_provider` returns advisory `verificationWarnings` for author-only decisions — surface them to the dev before publishing.
 
-**Verification sessions:** consumers authenticate with a per-org token (`rorg_…`, issued in the dashboard via `POST /orgs/{orgId}/token`) and create sessions via `POST /verifications/sessions`. Results are JWE-encrypted (ECDH-ES + A256GCM over X25519) to the org's single encryption credential — set via `PUT /orgs/{orgId}/credential` with an X25519 public JWK — and delivered to the org's callback subscriptions (plaintext when no credential is set). Use the org/session tools (`get_verification_session`, `list_verification_events`, `list_org_verification_sessions`) to troubleshoot.
+**Discover & resolve (find providers for the user's app):** when a dev wants to add verification but doesn't know which providers to use, run the same flow the Discover UI does. Ask which website their users prove data from, then `discover_data_points({ domain })` to list what's verifiable there. Confirm the data points with the dev, then `discover_resolve({ domain, dataPoints })` → the smallest provider set (`providers`, greedy combine), the `requiredContext` inputs to collect from the dev, and any `uncovered` points (author those with the provider-authoring flow above, then re-resolve). Create the session with `create_verification_session({ providers: [{ providerId }, …], context, verificationClientUrl })`, passing EVERY resolved provider id and the collected context. `merge.mergeable` only signals the set could collapse into one provider — you still pass them all; the Builder runs them in one session.
+
+**Verification sessions:** consumers authenticate with a per-org token (`rorg_…`, issued in the dashboard via `POST /orgs/{orgId}/token`) and create sessions via `POST /verifications/sessions`. Results are ECIES-encrypted (secp256k1 + AES-256-GCM) to the org's eth public key when its `canEncryptResult` is enabled — set via `PUT /orgs/{orgId}/keypair` with an eth public key — and delivered to the org's callback subscriptions (plaintext otherwise). Use the org/session tools (`get_verification_session`, `list_verification_events`, `list_org_verification_sessions`) to troubleshoot.

package/skill/injection-api.md

@@ -0,0 +1,42 @@
+# Page injection: `jsUserScripts` / `customInjection`
+
+A provider can inject **plain JavaScript** that runs in the page before every
+page load. Builder stores it as `webSettings.jsUserScripts`; old-devtools stores
+it as `customInjection` (identical semantics). It is ordinary browser
+JavaScript — its job is to drive the page so the target API request(s) fire
+during a verification.
+
+## What the script is for
+
+The verification client already **intercepts the page's network requests
+automatically** — the script does NOT necessarily ned to capture, forward, or "claim" them.
+Its primary job is to get the page into the state where those requests happen, using
+standard browser APIs:
+
+- **Navigate** with `window.location.href = '…'` / `location.assign(…)` / the
+  history API.
+- **Interact**: select an element and `.click()` it, submit a form, dispatch
+  events.
+- **Wait**: poll the DOM until login/mfa completes or content loads, then trigger
+  the next step.
+
+Write it like any page script. It runs before EVERY page load, so keep it
+idempotent, cheap, and guarded against running at the wrong time.
+
+## `window.Reclaim` — rarely needed, use sparingly
+
+`window.Reclaim` is an OPTIONAL bridge for a few edge cases only. Most providers
+never touch it. In particular it does **not** do navigation — use the standard
+browser APIs above for that, in plain `jsUserScripts` / `customInjection`.
+
+Do not reach for `window.Reclaim` by default. Only use it when an edge case
+genuinely requires it. Its full, authoritative API (every method, with exact
+signatures and semantics) is documented in 
+`https://github.com/reclaimprotocol/provider-web-script-dev/blob/main/src/support/env.d.ts` — consult that file rather
+than guessing.
+
+> Both backends run the script: the Builder verification client installs
+> `jsUserScripts` to run before every page load (before navigating to the
+> provider's `initialUrl`), and old-devtools runs `customInjection` the same
+> way. (`window.Reclaim` itself is still only forwarded/available in the cases
+> noted above.)

package/skill/old-mode.md

@@ -4,10 +4,12 @@ This server is running against the LEGACY Reclaim devtools backend (temporary, w
 
 1. `reclaim_authenticate` — by default opens the dashboard in Chrome, waits for you to sign in, captures the token automatically, and closes the tab (or paste a `token` / pass an eth `ethAddress` to skip the browser). Do this once before publishing or listing.
 2. `attach_chrome` → `start_capture` → drive the page (`navigate`, `wait_for_page`) → inspect (`list_requests`, `get_request`, `find_requests_containing`).
-3. `propose_provider` to draft a provider, `replay_request` to pre-flight, `run_proof` to verify with the attestor. OPRF/`hash` redactions are optional and supported.
-4. `create_provider_version_from_capture` to publish. With NO `providerId` it REGISTERS A NEW provider (re-running creates a duplicate); pass a `providerId` from `get_me_providers` to add a new version to an existing provider instead.
+3. `propose_provider` to draft a provider, `replay_request` to pre-flight, `run_proof` to verify with the attestor. OPRF/`hash` redactions are optional and supported. When the data spans MULTIPLE requests (e.g. a landing call + a details call), propose + `run_proof` EACH request to get one proven draft per request.
+4. `create_provider_version_from_capture` to publish. With NO `providerId` it REGISTERS A NEW provider (re-running creates a duplicate); pass a `providerId` from `get_me_providers` to add a new version to an existing provider instead. For a MULTI-REQUEST provider, pass `providers: [draftA, draftB, …]` (every proven draft) so EACH becomes a parallel `requestData` entry on the one version — passing a single `provider` saves only that one request.
 5. `get_me_providers` lists the providers you own (the only provider-listing tool available in this mode).
 
+**Editing / new versions (ownership):** you can only add a version to a provider **you own** — the `providerId` must come from `get_me_providers`. Trying to version a public provider you don't own fails with a permission error; that is expected. To publish your own version of such a site, re-run `create_provider_version_from_capture` **without** `providerId` to register your own copy (a separate provider you own). If versioning a provider you *do* own fails, confirm you authenticated as the account that created it.
+
 Only GET/POST endpoints can be captured into providers here. There is no organization, credential-linking, or public-review workflow in this mode.
 
 **Templating:** bare `{{name}}` placeholders are provider params (values extracted from the response). Values the CONSUMER must supply at verification time (e.g. a username in the URL path) use the `{{context_<name>}}` form — this backend does not support the dotted `{{context.<name>}}` interpolation the new builder uses.

package/src/cdp/launcher.ts

@@ -2,6 +2,7 @@ import { type ChildProcess, spawn } from 'node:child_process'
 import { existsSync, mkdirSync } from 'node:fs'
 import { homedir, platform } from 'node:os'
 import { join } from 'node:path'
+import { chromePath, localAppData } from '../consts.ts'
 import { reclaimHomeDirPath } from '../paths.ts'
 
 export interface LaunchOptions {
@@ -38,14 +39,14 @@ function browserCandidates(): string[] {
 			'/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
 		]
 	case 'win32': {
-		const localAppData =
-				process.env['LOCALAPPDATA'] ?? join(homedir(), 'AppData', 'Local')
+		const appData =
+				localAppData() ?? join(homedir(), 'AppData', 'Local')
 		return [
 			// System-wide Chrome
 			'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
 			'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
 			// Per-user Chrome ("Install for me only")
-			join(localAppData, 'Google', 'Chrome', 'Application', 'chrome.exe'),
+			join(appData, 'Google', 'Chrome', 'Application', 'chrome.exe'),
 			// Edge — Chromium-based, preinstalled on Win 10/11
 			'C:\\Program Files\\Microsoft\\Edge\\Application\\msedge.exe',
 			'C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe',
@@ -87,7 +88,7 @@ export function findChromeBinary(): string {
 }
 
 export function launchChrome(opts: LaunchOptions): ChildProcess {
-	const binary = process.env.RECLAIM_AGENT_CHROME_PATH ?? findChromeBinary()
+	const binary = chromePath() ?? findChromeBinary()
 	if(!existsSync(opts.profileDir)) {
 		mkdirSync(opts.profileDir, { recursive: true })
 	}

package/src/consts.ts

@@ -0,0 +1,164 @@
+/**
+ * Centralized environment access for `@reclaimprotocol/agent`.
+ *
+ * This is the ONLY non-test source file under `src/` that reads
+ * `process.env`. Every other module imports a getter from here instead of
+ * touching `process.env` directly.
+ *
+ * Almost everything is exposed as a LAZY GETTER FUNCTION rather than an eager
+ * `const`, on purpose: several tests mutate env at runtime (mcp-credentials
+ * sets/deletes RECLAIM_PRIVATE_KEY / RECLAIM_PRIVATE_KEY_FILE / RECLAIM_HOME;
+ * old-devtools sets/deletes USE_OLD_DEVTOOLS), and most of these vars are read
+ * at call time anyway. An eager const captured at import time would freeze the
+ * value and break those tests. The one eager const that's safe is `LOG_LEVEL`,
+ * which is read once at logger construction.
+ *
+ * Each var's default/fallback literal is co-located with its getter.
+ */
+import { DEFAULT_BASE_URL } from '@reclaimprotocol/client'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { DEFAULT_OLD_API_URL } from './old/client.ts'
+
+// ---------------------------------------------------------------------------
+// Default / fallback literals (used only as env fallbacks).
+// ---------------------------------------------------------------------------
+
+/** Public attestor websocket URL — fallback for `RECLAIM_ATTESTOR_URL`. */
+export const FALLBACK_ATTESTOR_URL = 'wss://attestor.reclaimprotocol.org:444/ws'
+
+/** The devtools dashboard login page — fallback for `RECLAIM_OLD_LOGIN_URL`. */
+export const DEFAULT_LOGIN_URL = 'https://dev.reclaimprotocol.org'
+
+// Re-export the two non-env-fallback defaults so callers can keep importing
+// their URL defaults from a single place if they wish.
+export { DEFAULT_BASE_URL, DEFAULT_OLD_API_URL }
+
+// ---------------------------------------------------------------------------
+// Logging.
+// ---------------------------------------------------------------------------
+
+/** Pino log level. Read once at logger construction, so an eager const is
+ *  safe (no test mutates LOG_LEVEL at runtime). */
+export const LOG_LEVEL = process.env.LOG_LEVEL || 'info'
+
+// ---------------------------------------------------------------------------
+// Paths.
+// ---------------------------------------------------------------------------
+
+/** Reclaim cache directory (`~/.reclaim`). `RECLAIM_HOME` overrides it so
+ *  tests can sandbox writes. */
+export function reclaimHome(): string {
+	return process.env.RECLAIM_HOME || join(homedir(), '.reclaim')
+}
+
+// ---------------------------------------------------------------------------
+// Mode flag.
+// ---------------------------------------------------------------------------
+
+/**
+ * `USE_OLD_DEVTOOLS` — single source of truth for which backend the MCP
+ * server targets. Defaults to OLD devtools while the builder backend is under
+ * development. Builder mode must be opted into EXPLICITLY with
+ * `USE_OLD_DEVTOOLS=false`; anything else keeps old mode on.
+ */
+export function useOldDevtools(): boolean {
+	return (process.env.USE_OLD_DEVTOOLS ?? '').trim().toLowerCase() !== 'false'
+}
+
+// ---------------------------------------------------------------------------
+// Chrome / CDP launcher.
+// ---------------------------------------------------------------------------
+
+/** `%LOCALAPPDATA%` on Windows, used to probe a per-user Chrome install. */
+export function localAppData(): string | undefined {
+	return process.env['LOCALAPPDATA']
+}
+
+/** Explicit Chrome/Edge/Chromium binary path override. */
+export function chromePath(): string | undefined {
+	return process.env.RECLAIM_AGENT_CHROME_PATH
+}
+
+// ---------------------------------------------------------------------------
+// MCP server / API clients.
+// ---------------------------------------------------------------------------
+
+/** Agent tools (Chrome CDP capture, synthesis, proof) are disabled in hosted
+ *  deployments by setting `RECLAIM_AGENT_DISABLED=1`. Shared by mcp/start and
+ *  the old-mode authenticate tool. */
+export function agentDisabled(): boolean {
+	return process.env.RECLAIM_AGENT_DISABLED === '1'
+}
+
+/** Old-devtools backend base URL. */
+export function oldApiUrl(): string {
+	return process.env.RECLAIM_OLD_API_URL || DEFAULT_OLD_API_URL
+}
+
+/** Builder backend base URL. Shared by mcp/start and the verification tool. */
+export function apiUrl(): string {
+	return process.env.RECLAIM_API_URL || DEFAULT_BASE_URL
+}
+
+/** Explicit builder API token (overrides the cached session token). */
+export function apiToken(): string | undefined {
+	return process.env.RECLAIM_API_TOKEN
+}
+
+// ---------------------------------------------------------------------------
+// Proof tracing.
+// ---------------------------------------------------------------------------
+
+/** Diagnostic trace capture (`RECLAIM_AGENT_TRACE=1`). Shared by the attestor
+ *  logger capture and the proof-run dump. */
+export function agentTraceEnabled(): boolean {
+	return process.env['RECLAIM_AGENT_TRACE'] === '1'
+}
+
+/** Attestor websocket URL override (`RECLAIM_ATTESTOR_URL`). */
+export function attestorUrlOverride(): string | undefined {
+	return process.env['RECLAIM_ATTESTOR_URL']
+}
+
+// ---------------------------------------------------------------------------
+// Eth proof-owner key resolution.
+// ---------------------------------------------------------------------------
+
+/** Raw 0x-hex Ethereum private key (`RECLAIM_PRIVATE_KEY`). */
+export function privateKey(): string | undefined {
+	return process.env.RECLAIM_PRIVATE_KEY
+}
+
+/** Path to a raw-hex key file (`RECLAIM_PRIVATE_KEY_FILE`). */
+export function privateKeyFile(): string | undefined {
+	return process.env.RECLAIM_PRIVATE_KEY_FILE
+}
+
+// ---------------------------------------------------------------------------
+// Verification reads.
+// ---------------------------------------------------------------------------
+
+/** Per-org bearer secret (`rorg_…`) used to authenticate verification reads. */
+export function orgSecret(): string | undefined {
+	return process.env.RECLAIM_ORG_SECRET
+}
+
+// ---------------------------------------------------------------------------
+// Old-devtools identity / login.
+// ---------------------------------------------------------------------------
+
+/** Dashboard Firebase bearer token for the old backend. */
+export function oldApiToken(): string | undefined {
+	return process.env.RECLAIM_OLD_API_TOKEN
+}
+
+/** An `eth:<addr>` (or bare `0x…`) uid for the old backend. */
+export function oldEthUid(): string | undefined {
+	return process.env.RECLAIM_OLD_ETH_UID
+}
+
+/** Override for the old-devtools dashboard login URL. */
+export function oldLoginUrl(): string | undefined {
+	return process.env.RECLAIM_OLD_LOGIN_URL
+}

package/src/logger.ts

@@ -1,8 +1,9 @@
 import pino, { stdTimeFunctions } from 'pino'
+import { LOG_LEVEL } from './consts.ts'
 
 export const LOGGER = pino({
 	name: '@reclaimprotocol/agent',
 	timestamp: stdTimeFunctions.isoTime,
 	base: { hostname: undefined, pid: undefined },
 })
-LOGGER.level = process.env.LOG_LEVEL || 'info'
+LOGGER.level = LOG_LEVEL