@reclaimprotocol/agent 0.1.0-dev.1

package/lib/provider/schema.d.ts

@@ -0,0 +1,76 @@
+import type { ProviderParams } from '@reclaimprotocol/attestor-core';
+/** The attestor's HTTP provider parameters — the canonical source for the
+ *  request/match/redaction shapes we draft. */
+type HttpParams = ProviderParams<'http'>;
+/** HTTP methods the attestor accepts. */
+export type HttpMethod = HttpParams['method'];
+/**
+ * A pattern the attestor checks against the revealed slice of the response.
+ * The prover selectively reveals portions of the TLS response (via
+ * responseRedactions), so the attestor only ever sees a substring —
+ * jsonPath/xPath belong on the redaction, not here.
+ */
+export type ResponseMatch = HttpParams['responseMatches'][number];
+/**
+ * Selector telling the prover which portion of the response to reveal:
+ * `xPath`/`jsonPath` narrows the slice, `regex` (with named groups) matches
+ * within, and `hash` applies an OPRF so the attestor sees a nullifier
+ * instead of the cleartext value.
+ */
+export type ResponseRedaction = NonNullable<HttpParams['responseRedactions']>[number];
+/**
+ * OPRF mode for hashed redactions. `oprf-raw` is what the dev-loop defaults
+ * to when privacy is requested — the only variant that runs without external
+ * deps (gnark for `oprf`, a TEE for `oprf-mpc`). It is the weakest of the
+ * three (the attestor participates in hashing) and is meant to be swapped
+ * out before production.
+ */
+export type OprfMode = NonNullable<ResponseRedaction['hash']>;
+/** A single captured request + response, as we store it server-side. */
+export interface CapturedRequest {
+    requestId: string;
+    method: string;
+    url: string;
+    status: number;
+    contentType: string;
+    size: number;
+    requestHeaders: Record<string, string>;
+    requestBody?: string;
+    responseHeaders: Record<string, string>;
+    responseBody?: string;
+    /** Parsed GraphQL operationName if request body is a GraphQL query. */
+    graphqlOp?: string;
+    /** ms since epoch when the response finished. */
+    finishedAt: number;
+}
+/**
+ * Reclaim provider JSON shape we draft, then translate to the attestor's HTTP
+ * params (proof/attestor.ts) and the API version request (to-version.ts). The
+ * request fields derive from the attestor's own `HttpProviderParameters`, so
+ * the method enum and match/redaction shapes can't drift from what the
+ * attestor accepts. `body` is narrowed to `string` (the SDK also allows
+ * `Uint8Array`, but we only ever template text bodies).
+ */
+export interface ReclaimProvider {
+    name: string;
+    url: string;
+    method: HttpMethod;
+    headers?: Record<string, string>;
+    body?: string;
+    responseMatches: ResponseMatch[];
+    responseRedactions?: ResponseRedaction[];
+    /** Public param refs (templated into URL/body), populated by draft layer. */
+    paramValues?: Record<string, string>;
+}
+/** A reference to a secret param. Raw value lives only in server memory. */
+export interface SecretParamRef {
+    name: string;
+    source: 'header' | 'cookie' | 'query';
+    redacted: true;
+}
+/** Concerns flagged about a captured request. Informational, never blocking. */
+export interface RequestConcern {
+    code: 'signedRequest' | 'wasmSigned' | 'botChallenge' | 'csrfDependency' | 'shortLivedToken' | 'encryptedBody' | 'graphql';
+    message: string;
+}
+export {};

package/lib/provider/schema.js

@@ -0,0 +1 @@
+export {};

package/lib/provider/secrets.d.ts

@@ -0,0 +1,5 @@
+export declare function classifyHeader(name: string): boolean;
+export declare function splitSecrets(headers: Record<string, string>): {
+    secrets: Record<string, string>;
+    publics: Record<string, string>;
+};

package/lib/provider/secrets.js

@@ -0,0 +1,22 @@
+const SECRET_EXACT = new Set(['cookie', 'authorization', 'proxy-authorization']);
+const SECRET_SUFFIXES = ['-token', '-key', '-secret', '-auth'];
+export function classifyHeader(name) {
+    const lower = name.toLowerCase();
+    if (SECRET_EXACT.has(lower)) {
+        return true;
+    }
+    return SECRET_SUFFIXES.some((s) => lower.endsWith(s));
+}
+export function splitSecrets(headers) {
+    const secrets = {};
+    const publics = {};
+    for (const [k, v] of Object.entries(headers)) {
+        if (classifyHeader(k)) {
+            secrets[k] = v;
+        }
+        else {
+            publics[k] = v;
+        }
+    }
+    return { secrets, publics };
+}

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

@@ -0,0 +1,22 @@
+import type { ReclaimClient } from '@reclaimprotocol/client';
+import type { CreateProviderVersionRequest as CreateVersionBody, ProviderVersionRef as VersionRef } from '../types/openapi.ts';
+import type { ReclaimProvider } from './schema.ts';
+/**
+ * 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.
+ *
+ * Secrets are NOT persisted — the verification client re-supplies
+ * them at runtime via `credentials: 'include'`.
+ */
+export declare function providerToCreateVersionRequest(provider: ReclaimProvider, initialUrl: string, notes?: string, version?: VersionRef): CreateVersionBody;
+/**
+ * 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>;

package/lib/provider/to-version.js

@@ -0,0 +1,68 @@
+/**
+ * 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.
+ *
+ * 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 } : {}),
+        };
+    });
+    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 }
+            : {}),
+        ...(notes ? { notes } : {}),
+    };
+}
+/**
+ * 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 async function nextVersion(client, providerId) {
+    const list = (await client.call('ListProviderVersions', {
+        params: { providerId },
+        query: {},
+    }));
+    if (!list.items?.length) {
+        return { major: 1, minor: 0, patch: 0 };
+    }
+    // Find the highest version and bump its patch
+    let hi = list.items[0].version;
+    for (const item of list.items) {
+        const v = item.version;
+        if (v.major > hi.major ||
+            (v.major === hi.major && v.minor > hi.minor) ||
+            (v.major === hi.major && v.minor === hi.minor && v.patch > hi.patch)) {
+            hi = v;
+        }
+    }
+    return { major: hi.major, minor: hi.minor, patch: hi.patch + 1 };
+}

package/lib/types/openapi.d.ts

@@ -0,0 +1,4 @@
+import type { components } from '@reclaimprotocol/client';
+export type CredentialAttachSession = components['schemas']['CredentialAttachSession'];
+export type CreateProviderVersionRequest = components['schemas']['CreateProviderVersionRequest'];
+export type ProviderVersionRef = components['schemas']['ProviderVersionRef'];

package/lib/types/openapi.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,88 @@
+{
+	"name": "@reclaimprotocol/agent",
+	"title": "Reclaim Agent",
+	"version": "0.1.0-dev.1",
+	"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",
+	"types": "./lib/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./lib/index.d.ts",
+			"import": "./lib/index.js"
+		},
+		"./mcp/register": {
+			"types": "./lib/mcp/register.d.ts",
+			"import": "./lib/mcp/register.js"
+		},
+		"./skill": "./skill/SKILL.md"
+	},
+	"bin": {
+		"reclaim": "./lib/cli.js",
+		"reclaim-mcp-server": "./lib/mcp-bin.js"
+	},
+	"files": [
+		"lib",
+		"src",
+		"scripts",
+		"skill",
+		"README.md"
+	],
+	"engines": {
+		"node": ">=22.18"
+	},
+	"repository": {
+		"url": "https://github.com/reclaimprotocol/builder",
+		"type": "git"
+	},
+	"websiteUrl": "https://docs.reclaimprotocol.org",
+	"scripts": {
+		"build": "tsc && node scripts/prepend-shebang.ts && chmod 755 lib/cli.js lib/mcp-bin.js",
+		"openapi:typegen": "node ../app/scripts/mcp-tools-gen.ts",
+		"prepublishOnly": "npm run build",
+		"dev": "tsc --watch",
+		"test": "node --test tests/*.test.ts",
+		"start:cli": "node lib/cli.js",
+		"start:mcp": "node lib/mcp-bin.js",
+		"inspect": "npx @modelcontextprotocol/inspector node lib/mcp-bin.js",
+		"download:zk-files": "node scripts/download-zk-files.ts",
+		"postinstall": "node scripts/download-zk-files.ts"
+	},
+	"keywords": [
+		"mcp",
+		"model-context-protocol",
+		"sdk",
+		"cli",
+		"ai",
+		"agent",
+		"chrome-devtools-protocol",
+		"reclaimprotocol",
+		"zktls",
+		"provider-authoring",
+		"zero-knowledge"
+	],
+	"author": {
+		"name": "Reclaim Protocol",
+		"email": "support@reclaimprotocol.org"
+	},
+	"license": "MIT",
+	"dependencies": {
+		"@hapi/boom": "^9.1.4",
+		"@modelcontextprotocol/sdk": "^1.29.0",
+		"@noble/hashes": "^2.2.0",
+		"@noble/secp256k1": "^3.1.0",
+		"@reclaimprotocol/attestor-core": "^5.0.6",
+		"@reclaimprotocol/client": "*",
+		"chrome-remote-interface": "^0.33.0",
+		"pino": "^9.14.0",
+		"zod": "^3.25.76",
+		"zod-from-json-schema": "^0.1.0"
+	},
+	"devDependencies": {
+		"@types/chrome-remote-interface": "^0.31.0",
+		"@types/node": "^24.0.0",
+		"openapi-typescript": "^7.13.0",
+		"typescript": "^5.9.0",
+		"yaml": "^2.6.0"
+	}
+}

package/scripts/download-zk-files.ts

@@ -0,0 +1,42 @@
+// Download the @reclaimprotocol/zk-symmetric-crypto circuit resources that
+// @reclaimprotocol/attestor-core needs at proof time. Runs as the agent's
+// `postinstall` and as `npm run download:zk-files`.
+//
+// Resolves the package via Node's algorithm (`createRequire().resolve`)
+// rather than a literal `node_modules/...` path: the package is commonly
+// hoisted to the workspace root, where a literal relative path from
+// packages/agent (npm's cwd for a workspace postinstall) would miss.
+
+import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+
+const require = createRequire(import.meta.url)
+
+let mainPath: string
+try {
+	mainPath = require.resolve('@reclaimprotocol/zk-symmetric-crypto')
+} catch{
+	// Dependency not installed (e.g. a consumer that only wants the SDK
+	// surface). Nothing to download; don't fail the install.
+	process.exit(0)
+}
+
+// mainPath is <pkg>/lib/index.js → its scripts live at <pkg>/lib/scripts.
+const downloadScript = join(dirname(mainPath), 'scripts', 'download-files.js')
+
+if(!existsSync(downloadScript)) {
+	console.warn(
+		`[reclaim-agent] zk download script not found at ${downloadScript}; ` +
+		'skipping. Run `npm run download:zk-files` once the package is installed.',
+	)
+	process.exit(0)
+}
+
+const child = spawn(process.execPath, [downloadScript], { stdio: 'inherit' })
+child.on('exit', (code) => process.exit(code ?? 0))
+child.on('error', (err) => {
+	console.warn(`[reclaim-agent] zk download failed: ${err.message}`)
+	process.exit(0)
+})

package/scripts/prepend-shebang.ts

@@ -0,0 +1,17 @@
+import { readFile, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const SHEBANG = '#!/usr/bin/env node\n'
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..')
+const BIN_FILES = ['cli.js', 'mcp-bin.js']
+
+for(const file of BIN_FILES) {
+	const path = join(ROOT, 'lib', file)
+	const content = await readFile(path, 'utf8')
+	if(content.startsWith('#!')) {
+		continue
+	}
+
+	await writeFile(path, SHEBANG + content)
+}

package/skill/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: reclaim-provider
+description: Activate when the developer asks how to verify a value from a website (e.g. "create a provider for X", "verify my GitHub username", "prove my X follower count"). Drives the reclaim-agent MCP server to capture browser traffic, draft a Reclaim provider JSON, replay it, and run an end-to-end zkTLS proof.
+---
+
+# Authoring a Reclaim Provider / Verification
+
+> **Terminology note:** "provider" and "verification" refer to the same
+> thing. The API and tool parameters use **provider** / **providerId**
+> (the technical term). Conversations with developers prefer
+> **verification** (the user-facing term). Either is acceptable — never
+> correct the developer for using one or the other.
+
+You drive the browser through the capture → draft → replay → prove loop using the `reclaim-agent` MCP server. **Your default stance is driver, not orchestrator.** Only pause to ask the dev for things that genuinely require a human: typing credentials, completing 2FA, solving a captcha, confirming an ambiguous value. Navigation, reloads, DOM inspection, request capture — all yours.
+
+## Modes
+
+This MCP server targets one of two backends. Detect which from the tools available to you:
+
+- **Old devtools (the default).** `get_me_providers` is present; the generated API tools (`get_me`, `create_verification`, `list_orgs`, …) are absent.
+- **Builder.** The generated API tools are present; `get_me_providers` is absent.
+
+Only **authentication** (below) and **publishing** (the final step) differ between modes. The capture → draft → replay → prove loop in between is identical, and OPRF is optional and supported in both.
+
+## Getting authenticated
+
+### Old devtools mode
+
+Call `reclaim_authenticate({})` with no arguments. It opens the Reclaim dashboard in Chrome, waits for the dev to sign in, reads the token from the page automatically, and closes the tab — a still-valid cached identity is reused first, so it's often instant. Tell the dev once: _"A browser window is opening the Reclaim dashboard — please sign in and I'll continue automatically."_
+
+- Force a fresh login (ignore the cached identity): `reclaim_authenticate({ useBrowser: true })`.
+- Skip the browser: `reclaim_authenticate({ token: "<firebase-id-token>" })`, or `reclaim_authenticate({ ethAddress: "0x..." })` for an already-provisioned eth user.
+- Tokens are short-lived (~1h). If a later call returns 401, call `reclaim_authenticate({})` again.
+
+### Builder mode
+
+**Check first:** try `get_me`. If it returns the user's profile, you're authenticated — proceed to the loop.
+
+**On 401:** call `authenticate({})` to start a device-pairing session:
+
+1. It returns immediately with a `code` and `attachUrl` — it does NOT poll.
+2. Tell the user: _"Open `<attachUrl>`, sign in, and click 'Authorize this device'."_
+3. After they confirm, call `authenticate({ code: "<code>" })`: `LINKED` → proceed; `PENDING` → wait and call again; `EXPIRED` → start a new session.
+
+The 2-day token is cached in `~/.reclaim/config.json` and reused on later runs (`RECLAIM_API_TOKEN` in the server env overrides it). To link an ETH credential to an org: `list_orgs` (ask which), then `link_credential({ address: "0x...", orgId })` — only needed to use the credential in production.
+
+## The loop
+
+1. **Attach.** Call `attach_chrome`. If it returns `needsChoice: true`, ask the dev:
+   - `dedicated` — agent auto-launches Chrome with a dedicated profile under `~/.reclaim/chrome-profile`. Easiest path; works out of the box.
+   - `attach` — connect to a Chrome the dev is already running. **Important Chrome 136+ gotcha:** the dev's Chrome must be launched with BOTH `--remote-debugging-port=9222` AND `--user-data-dir=<some-non-default-path>`. Since Chrome 136 (May 2025), the debug-port flag is silently ignored when the default user profile is in use. If `attach` fails, tell them this verbatim and offer to switch to `dedicated`.
+
+   Re-call with the chosen `attachMode`.
+
+2. **Pick a tab and open the site yourself.** Call `list_tabs`. If there's already a tab on the right origin, use it. Otherwise pick any tab (the first one is usually fine) and call `navigate(tabId, url)` to send it to the site you've inferred from the dev's request (e.g. "GitHub username" → `https://github.com`). Don't ask the dev to navigate.
+
+3. **Check login state, wait if needed.** Use `eval_in_page(tabId, ...)` to evaluate a site-specific check.
+
+   **Combine a positive signal (logged-in-only element present) with a negative signal (login button absent), AND them together.** Single signals are too prone to false positives — most notably, `<meta>` tags often exist on every page regardless of login state; only their `.content` attribute is populated. The check `!!document.querySelector('meta[name="user-login"]')` returns true even when logged out — DO NOT use existence-only checks on meta tags or other persistent-but-empty elements.
+
+   Examples (always verify against the live page if these break — sites change selectors):
+   - GitHub: `(document.querySelector('meta[name="user-login"]')?.content?.length || 0) > 0 && !document.querySelector('a.HeaderMenu-link[href="/login"]')`
+   - X / Twitter: `!!document.querySelector('[data-testid="AppTabBar_Profile_Link"]') && !document.querySelector('[data-testid="loginButton"]')`
+   - Generic shape: `<element-present-only-when-logged-in> && !<login-button-present-only-when-logged-out>`
+
+   If the result is truthy, skip to step 4.
+
+   If falsy: **navigate to the site's login URL yourself first**, so the dev lands directly on the login form instead of having to find it. Common patterns: `https://<host>/login`, `https://<host>/signin`, `https://<host>/i/flow/login` (Twitter/X). Pick the one you know works for the site. Call `navigate(tabId, "<login-url>")`. Then tell the dev once: "I've opened the login page on `<site>` — please log in (with 2FA if needed). I'll detect when you're done." Then call `wait_for_page(tabId, expression="<same composite expression>", timeoutMs=180000)`. The MCP polls every second and returns when the expression goes truthy. **Do not** instruct the dev to "tell me when you're done" — just wait via the tool.
+
+   **Self-check before trusting the result:** if your detector says "already logged in" on a freshly-launched Chrome profile (cookies-clean), the detector is wrong. Brand-new profile means brand-new cookie jar — there's no way to be already authenticated. If you see that contradiction, your check is matching something that's present regardless of login (a meta tag, a generic class). Rewrite the expression and re-evaluate.
+
+4. **Navigate to the page that displays the value.** Use what you know about the site to construct the URL. If you need the dev's username, eval it (e.g. on GitHub: `document.querySelector('meta[name="user-login"]')?.content`). Then `navigate(tabId, url)`. Don't ask the dev to navigate.
+
+5. **Start capture, then trigger the request.** Call `start_capture(tabId)` first. Then issue a reload so the relevant API call fires while capture is live: `eval_in_page(tabId, "location.reload()")`. For some pages you may need to click a specific element or call a SPA route — use `eval_in_page` to do that programmatically rather than asking the dev to click.
+
+6. **Identify the value from the DOM.** `eval_in_page` to read the displayed value (e.g. the logged-in username from `meta[name="user-login"]`'s `content` attribute). If the value is unambiguous, proceed without asking. Only confirm with the dev when there are multiple plausible interpretations (e.g. the page shows both a display name "John Doe" and a handle "@jdoe" and you need to pick which to prove).
+
+7. **Find the request.** Call `find_requests_containing(captureId, value)`. For each top candidate (limit ≤ 5), call `analyze_request_constraints` and surface its `concerns` to the dev verbatim. Skip candidates flagged `signedRequest` or `botChallenge` unless none others are available. Concerns flagged `csrfDependency`, `shortLivedToken`, or `graphql` are informational — surface them and proceed.
+
+   **Strongly prefer authenticated, user-specific endpoints over public pages.** A proof against a public endpoint (e.g. `https://github.com/<username>`) attests only that "this URL returned this value at this time" — anyone in the world could fetch the same URL and prove the same thing. The proof says nothing about who the prover _is_. To prove a fact about the dev, the captured request needs to be one whose **response varies with authentication** — typically an API endpoint that returns the logged-in user's data (e.g. `GET https://api.github.com/user`, `https://twitter.com/i/api/.../UserByScreenName?...&forCurrentUser=true`).
+
+   When ranking candidates from `find_requests_containing`, prefer ones that:
+   - Have `Cookie`, `Authorization`, or other secret headers (analyze_request_constraints will surface these via `splitSecrets`).
+   - Have URL paths suggesting authenticated data: `/me`, `/user`, `/settings`, `/api/...`, `/graphql` with viewer queries.
+   - Return JSON keyed to the dev's identity (login/username/id fields next to the target value).
+
+   If the only candidates are public-page HTML responses, tell the dev: "The value appears on a public page, so a proof against this endpoint won't bind to your identity — anyone could prove the same fact. I can still build it if you just want to attest the value, but for an identity-bound proof we need to capture an authenticated request. Want to keep digging, or proceed anyway?" Then wait for their call.
+
+8. **Decide whether to OPRF the value** (privacy from the attestor). Before calling `propose_provider`, decide if the captured value should be hashed end-to-end so the attestor never sees it in cleartext. Four options:
+   - **No hash** (default). Value travels via `paramValues` + `{{name}}` template; attestor sees the cleartext substring. Simplest, fewest moving parts. Right call for non-sensitive values (public IPs from `ifconfig.me`, public usernames the dev is happy to expose, public repo names).
+   - **`oprf-raw`**. Server-side OPRF. **The only variant that runs on Windows / without external deps.** Use this when the dev wants any privacy and you're in a normal dev loop. Privacy is the weakest of the three (attestor still participates in hashing) — surface that honestly.
+   - **`oprf`**. Client-side ZK OPRF via gnark. Strongest privacy. Requires gnark install (Linux/macOS in practice). Don't suggest this on Windows.
+   - **`oprf-mpc`**. TEE-based MPC OPRF. Requires a TEE attestor deployment. Niche; only suggest if the dev brings it up.
+
+   **Default skip-the-question heuristic.** If the value is obviously non-sensitive (public IP, public username, public repo name, public follower/star counts on sites where the captured endpoint is auth-bound), default to **no hash** and proceed without asking. If the value is or could be sensitive (email, real name, private ID, anything the dev wouldn't post publicly), surface the choice verbatim:
+
+   > "Do you want this value kept private from the attestor via OPRF?
+   >
+   > - **No** (default) — value visible to attestor
+   > - **`oprf-raw`** — works on Windows / without extra deps; weakest of the OPRF variants
+   > - **`oprf`** — gnark/ZK; strongest privacy but requires Linux/macOS + gnark install
+   > - **`oprf-mpc`** — TEE-based; requires a TEE attestor"
+
+   **Hard constraint:** OPRF-hashed values are capped at **62 bytes**. If the value is longer and the dev picks any hash, surface that and propose either a tighter `target` (e.g. just the email local-part) or no hash. `propose_provider` will return a clean error if you try anyway.
+
+9. **Draft.** Call `propose_provider(captureId, requestId, target, name, hash?)`. Pass `hash` only if the dev opted in. Inspect the returned provider:
+   - Is the right header marked secret? (cookies, Authorization, X-\* tokens)
+   - Is `responseMatches[0].value` a `contains` with a `{{name}}` template (matching the captured value's structural context)?
+   - Is `paramValues[name]` set to the original captured value?
+   - Does `responseRedactions[0]` carry an `xPath` or `jsonPath` anchor? (And if `hash` was requested, also a `regex` with a named capture and a `hash: oprf-…` field?)
+
+   **Canonical drafted shape** (no hash):
+
+   ```json
+   {
+   	"responseMatches": [
+   		{ "type": "contains", "value": "\"login\":\"{{username}}\"" }
+   	],
+   	"responseRedactions": [{ "xPath": "//script[@id=\"client-env\"]" }],
+   	"paramValues": { "username": "Scratch-net" }
+   }
+   ```
+
+   **Canonical drafted shape** (with `hash: 'oprf-raw'`):
+
+   ```json
+   {
+   	"responseMatches": [
+   		{ "type": "contains", "value": "\"login\":\"{{username}}\"" }
+   	],
+   	"responseRedactions": [
+   		{
+   			"xPath": "//script[@id=\"client-env\"]",
+   			"regex": "\"login\":\"(?<username>[A-Za-z0-9_-]+)\"",
+   			"hash": "oprf-raw"
+   		}
+   	],
+   	"paramValues": { "username": "Scratch-net" }
+   }
+   ```
+
+   **Do NOT rewrite the shape.** The synthesizer's output is the canonical Reclaim shape — `contains` template + paramValues + xPath/jsonPath redaction (optionally + regex+hash). Specifically:
+   - Do not replace the `contains` template with a hand-crafted regex.
+   - Do not hand-write a named-capture regex unless `hash` was requested AND the synthesizer's output doesn't already have one. (It will, for any digit/slug/email-shaped target.)
+   - Do not remove `paramValues` — that's how the template resolves at proof time.
+   - The redaction's xPath/jsonPath is what the prover reveals; the match's template is what the attestor verifies post-substitution. They serve different purposes — don't conflate them.
+
+   Permitted edits: narrowing the `contains` template, picking a more distinctive xPath class/id if the synthesizer's pick is too generic, fixing the `name` field, adding/removing secret headers. If you're tempted to rewrite the provider from scratch, call `propose_provider` again with different inputs instead.
+
+10. **Parameterize user-specific URL segments** so the provider isn't user-specific at the URL level. The matcher already populates `paramValues` with the _captured value_ (e.g. `{username: "Scratch-net"}` for a username target). If the URL ALSO contains user-identifying segments, add those as additional paramValues entries:
+
+- Path segments that identify the dev (username, user-id, slug) → replace with `{{name}}`. E.g. `https://github.com/Scratch-net/repos` → `https://github.com/{{username}}/repos`, with `paramValues: { ..., username: "Scratch-net" }` (extending the matcher's existing entry, not replacing it).
+- Query parameters with user-specific values → same treatment.
+- Generic segments (`/api/v3`, `/users`, `/repos`) stay literal.
+- If the URL has no user-identifying segments (e.g. `/settings/profile`), leave it untouched — the matcher already handled the value via paramValues.
+
+11. **Replay.** Call `replay_request(provider, secretParamsRef)`. Three outcomes:
+
+- `matchesOriginal: true` → proceed.
+- `matchesOriginal: false` with `hints` mentioning auth/csrf → re-trigger the action yourself: navigate or reload via the tools, then loop to step 5. Don't ask the dev to redo it manually.
+- `matchesOriginal: false` with stable diff (timestamps etc.) → tighten the matcher and retry.
+
+**After replay succeeds, run an authentication-bound check.** Call `replay_request(provider)` _without_ the `secretParamsRef` (omit it). This sends the request stripped of all secret headers — the same shape an unauthenticated visitor would send.
+
+- If `matchesOriginal: false` (e.g. 401/403, or the value differs) → the endpoint is auth-bound. Good. The proof will actually mean "the holder of these secrets saw this value."
+- If `matchesOriginal: true` with the same value → the endpoint is fully public. Tell the dev verbatim: "I verified this endpoint returns the same value with no authentication — the proof won't prove your identity, only that this URL returned the value. Anyone could generate the same proof. Want to keep digging for an auth-bound endpoint, or proceed anyway?" Wait for their decision before continuing.
+
+12. **Prove.** Call `run_proof(provider, secretParamsRef)`. On `verified: true`, the full claim has been written to `~/.reclaim/claims/<timestamp>.json` and the tool returns `{verified, extractedValue, extractedParameters, identifier, owner, claimPath, claim}`. The `claim` field is a display-ready version of the proof — its huge `request` payload has been stripped and all byte arrays converted to base64, so it renders cleanly. **Show it to the dev as a fenced JSON code block at the end** along with the provider JSON. That's the final result. On `verified: false`, diagnose using the returned error and iterate.
+
+    **Missing signing credential (`errorKind: "missing-owner-key"`)** — the dev hasn't set up a credential yet. Tell them what's happening, then drive the bootstrap yourself: call `list_cached_credentials` to see if anything's already cached; if not, ask once _"shall I mint a fresh credential via `issue_credentials`? Persisted to `~/.reclaim/config.json` for this and future sessions."_; on yes, call `issue_credentials` and retry the same `run_proof` call. **No restart needed** — the credential is read live from the cache on each `run_proof`, and the existing `secretParamsRef` from `propose_provider` is still valid.
+
+    **On any `verified: false` response, the result includes (inline):**
+    - `error` — the SDK's thrown error message verbatim
+    - `sentParams` — the exact `params` object the SDK saw, post-template substitution (lets you spot mutation / substitution surprises)
+
+    **Deeper tracing (opt-in).** If the dev launches Claude Code with `RECLAIM_AGENT_TRACE=1` in the MCP server's env, `run_proof` ALSO captures the SDK's full pino log stream into `result.attestorLogs` and persists a per-call dump to `~/.reclaim/proof-runs/<timestamp>.json` (surfaced as `runLogPath`). Off by default because the trace stream is verbose. Suggest turning it on when investigating a recurring proof failure.
+
+    **The attestor is reliable. If it errors, the cause is in the provider, the network, or the prover-side code — not "the attestor can't handle this site".** Do not invent failure modes like "HTML is too large", "TLS records are chunked", "the attestor matches against gzipped bytes" (it doesn't if the provider has `Accept-Encoding: identity`, which `propose_provider` always sets), or "xPath doesn't work on this DOM". These are wrong and they waste the dev's time. Instead:
+    1. Show the `error` field to the dev verbatim.
+    2. If `sentParams` differs from what you expected — e.g. `{{name}}` substituted to the wrong value, headers got mutated, redactions look different from `propose_provider`'s output — surface that.
+    3. Only then propose a hypothesis, and tie it to that evidence. If the diagnosis is unclear, suggest the dev set `RECLAIM_AGENT_TRACE=1` and rerun for full attestor logs.
+
+    **Do not auto-retry with a different `attestorUrl`.** There is one live public attestor right now; backup hostnames (`attestor-2.*`, etc.) **do not exist**. `attestorUrl` is only for when the dev explicitly supplies a private/staging URL.
+
+    **Missing ZK circuit files:** if the error says "ZK circuit resources are missing" and points at a `circuit.wasm` path, the npm postinstall didn't run (commonly because the dev used `npm install --ignore-scripts` or a corp policy disabled it). Tell the dev to run `npm run download:zk-files` from the project root and then retry `run_proof` — no need to redo capture or propose. The MCP server doesn't need a restart either; the next `run_proof` call will see the files.
+
+13. **Publish the proved provider.** This is the step that differs by mode (see [Modes](#modes)). In both, `provider` is the exact JSON from step 9 with the step-10 URL parameterisation applied, and `initialUrl` is the page where the user logs in / the value is displayed (e.g. `https://github.com/Syed`) — **not** the API endpoint URL inside the provider.
+
+    **Old devtools mode** — call `create_provider_version_from_capture`:
+    - **New verification:** omit `providerId`. It registers a new provider (version 1.0.0). Pass `provider`, `initialUrl`, and optionally `description`, `geoLocation`, `providerType` (`PRIVATE` default | `PUBLIC`).
+    - **New version of an existing verification:** pass its `providerId` — the patch is auto-bumped above the highest existing version. Pass `notes` (≥10 chars) as the change note.
+    - `get_me_providers({ searchQuery? })` lists the verifications you own — use it to find a `providerId` or to confirm the result. It's the only provider-listing tool in this mode.
+    - There's no separate "create-then-version" step and no org / public-review workflow here.
+
+    **Builder mode:**
+    1. **Create the verification if it doesn't exist:** `create_verification(orgId, domain, slug, title, description)` — find `orgId` via `list_orgs`. `domain` e.g. `github.com`; `slug` e.g. `github-username`; `title` e.g. "GitHub Username". Starts PRIVATE with an empty seed version. Skip if the dev already has a `providerId`.
+    2. **Persist the version:** `create_provider_version_from_capture(providerId, provider, initialUrl, notes)` — `notes` e.g. `"Initial draft from browser capture"`. PRIVATE → live immediately; PUBLIC → lands on the `draft` branch.
+    3. **For PUBLIC verifications:** `submit_provider_version_for_review(providerId, version)` (the semver returned above). Tell the dev it's awaiting admin review.
+
+    When done, tell the developer the version is live (PRIVATE) or submitted for review (PUBLIC), and that they can integrate using the `providerId`.
+
+## Concerns the developer should see verbatim
+
+When `analyze_request_constraints` returns concerns, repeat each `message` to the dev exactly. Don't paraphrase, don't omit. These are the dev's signal that a provider is or isn't worth pursuing.
+
+## Things to never do
+
+- Never echo a raw `Authorization`, `Cookie`, or `X-*-Token` value back to the dev or write one to any file. The MCP guarantees these don't appear in tool responses — keep that guarantee.
+- Never call `run_proof` before `replay_request` succeeds. Attestor calls are expensive.
+- Never pretend a proof succeeded when `verified: false` came back. Show the error and iterate.
+- **Never hand-craft `responseMatches` or `responseRedactions`.** If you find yourself typing a regex by hand, OR writing `(?<name>...)`-style patterns by hand, OR copying the captured value literally into the match — stop. The synthesizer in `propose_provider` already produces the canonical shape: `contains` template + paramValues for the match, xPath/jsonPath (optionally + regex+hash when `hash` is passed) for the redaction. The named-capture regex in the redaction is the synthesizer's job, not yours.
+- Never write a literal value into `responseMatches.value` — the synthesizer always emits `{{name}}` templates with paramValues. A literal value bakes the original user into the provider.
+- Never pass `hash` to `propose_provider` for a free-form (unicode / spaces / punctuation) target — the synthesizer will error, and the right move is either to use a tighter `target` or accept cleartext (no `hash`).
+- Never accept "the synthesizer's xPath looks too narrow, let me write a regex" — the xPath is fine, the attestor will reveal the whole matched element which is naturally ≥16 bytes.
+
+## Common first-time issues — surface these proactively
+
+If `attach_chrome` errors, times out, or `waitForCdpReady` reports the port isn't answering, walk through these in order before retrying:
+
+- **Browser binary not found.** If the error lists candidate paths it tried (Program Files Chrome, LOCALAPPDATA Chrome, Edge), every one missed. Either the dev has Chrome installed somewhere unusual, or doesn't have Chrome/Edge at all. Walk them through setting `RECLAIM_AGENT_CHROME_PATH` to the actual binary path:
+  ```powershell
+  setx RECLAIM_AGENT_CHROME_PATH "C:\path\to\chrome.exe"
+  ```
+  `setx` (not `$env:`) writes to the user-level Windows env, so future shells and future Claude Code launches inherit it. **Then fully restart Claude Code** — MCP servers snapshot env vars at launch, so the running reclaim-agent has the old empty value. After restart, the new MCP process picks up the env. On macOS/Linux: `export RECLAIM_AGENT_CHROME_PATH=/path/to/chrome` in the shell, then restart Claude Code from that same shell so the var propagates.
+- **Pre-existing `chrome.exe` processes hijack the new launch (Windows).** If any Chrome is already running, a new launch with `--remote-debugging-port` gets delegated to the existing process group and the debug port silently doesn't open. Tell the dev to kill all `chrome.exe` first (`taskkill /F /IM chrome.exe` in cmd/PowerShell, or via Task Manager), then retry. Affects both `attach` and `dedicated` modes when the existing instance was launched with the same profile dir.
+- **Chrome 136+ silently disables remote debugging on the default user profile.** Already noted in step 1, but worth raising again here: the only fix is a non-default `--user-data-dir`. `dedicated` mode is always safe; `attach` mode needs the dev to have launched with both flags.
+
+**Credential for signing the proof.** `run_proof` requires an `ownerAddress` — the app credential whose key signs the claim. It does **no** resolution itself; get the address from `resolve_owner_key` first. The private key is resolved locally (cache → env → `.env`) and never enters the conversation.
+
+1. **Call `resolve_owner_key`.** It checks `RECLAIM_PRIVATE_KEY` (MCP env) → the project `.env` → the best cached credential for this directory.
+   - `{ ready: true, address }` → call `run_proof({ provider, ownerAddress: address, … })`. No prompts.
+   - `{ ready: false }` → no credential exists yet. Ask the dev once how to set one up:
+     - **Provide their own key** → `import_credentials({ privateKey: "0x…" })`.
+     - **Create a new one** → `issue_credentials({})`. (Fine default for test proofs — owner identity doesn't matter.)
+     - **Persist or memory-only?** Writing the key to `.env` is opt-in — **never write `.env` without asking.** Pass `writeEnv: false` to keep it in the local cache (memory) only. Either way it's cached, so `resolve_owner_key` finds it next.
+   - Then call `resolve_owner_key` again and `run_proof` with the returned address.
+2. All fully local — no network, no server registration. `list_cached_credentials` shows what's cached if the dev wants to pick a specific one.
+- **Advanced:** setting `RECLAIM_PRIVATE_KEY` directly in the MCP server's env also works, but env vars are snapshotted at Claude Code startup, so that route needs a full restart (which invalidates every `secretParamsRef`). The cache/`.env` flow above avoids that — prefer it.
+- **Multiple MCP config files exist on Windows.** `~/.claude.json` takes precedence over `~/.claude/mcp.json`. When advising config edits, point them at the right file or tell them to use `claude mcp list` / `claude mcp add --scope user` rather than editing JSON by hand.
+
+If `replay_request` or `run_proof` errors with `unknown secretParamsRef`:
+
+- **The ref is bound to the MCP server process.** Anything that restarts the server (Claude Code restart, `reset_session`, machine reboot) invalidates every previously-issued ref. The fix is always: re-run `start_capture` → interact → `propose_provider` to mint a fresh ref. Don't ask the dev to "re-enter the value" — walk them back through capture.
+- **Exception:** if the drafted provider has empty `secretRefs: []` (no secret headers were captured), you can call `replay_request` and `run_proof` without `secretParamsRef` at all — both tools accept it as optional in that case.
+
+## Out of scope (v0)
+
+If the dev needs a provider for a flow that requires multiple sequential requests (CSRF preflight, refresh-token chains), tell them: "multi-request providers are v1. For now, we can produce a single-request provider for the target value — let's see if one exists in this capture."