@reclaimprotocol/agent 0.1.12 → 0.1.13

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@reclaimprotocol/agent",
 	"title": "Reclaim Agent",
-	"version": "0.1.12",
+	"version": "0.1.13",
 	"description": "Reclaim Protocol's tools for agents — Reclaim Protocol lets your app verify **data points** about its users — a follower count, an account balance, an order history. This package gives your AI coding agent the tools to **find, build, test and fix the _data verification providers_** (the recipes that verify a data point) by inspecting and replaying captured requests, checking sessions, evaluate proofs, publishing updates, and much more.",
 	"type": "module",
 	"main": "./lib/index.js",
@@ -41,6 +41,7 @@
 		"src",
 		"scripts",
 		"skill",
+		"samples",
 		"README.md"
 	],
 	"engines": {
@@ -83,12 +84,12 @@
 	"dependencies": {
 		"@hapi/boom": "^9.1.4",
 		"@modelcontextprotocol/sdk": "^1.29.0",
+		"@noble/hashes": "^2.2.0",
 		"@reclaimprotocol/attestor-core": "^5.0.8",
 		"@reclaimprotocol/client": "*",
 		"@reclaimprotocol/tls": "^0.1.3",
 		"chrome-remote-interface": "^0.33.0",
 		"domhandler": "^6.0.0",
-		"ethers": "^6.17.0",
 		"parse5": "^8.0.0",
 		"parse5-htmlparser2-tree-adapter": "^8.0.0",
 		"pino": "^9.14.0",

package/samples/demo-server/.env.example

@@ -0,0 +1,12 @@
+RECLAIM_APP_ID=
+RECLAIM_APP_SECRET=
+PORT=3000
+# REQUIRED for the webhook callback to land — Reclaim's servers can't reach
+# localhost. Pick ONE:
+#   - ngrok (or similar tunnel): run `ngrok http 3000` in a separate
+#     terminal and paste the https://<id>.ngrok-free.app URL it prints here.
+#   - A dev/staging server you can deploy this to quickly: point this at
+#     that server's public URL instead.
+# Without either, only the frontend-side flow (opening requestUrl) works —
+# the webhook never fires.
+PUBLIC_URL=

package/samples/demo-server/README.md

@@ -0,0 +1,24 @@
+# Reclaim demo server
+
+1. `npm install`
+2. Fill in `.env` (copy from `.env.example`) — get `RECLAIM_APP_ID`/
+   `RECLAIM_APP_SECRET` from the `issue_app_credentials` MCP tool, or your
+   existing app.
+3. Set `PUBLIC_URL` in `.env` to a URL Reclaim's servers can reach — pick
+   whichever fits:
+   - **ngrok**: in a separate terminal, run `ngrok http 3000` (install from
+     https://ngrok.com if needed) and copy the
+     `https://<id>.ngrok-free.app` URL it prints.
+   - **A dev/staging server you can deploy to quickly**: if you already have
+     one reachable from the internet, deploy this there and use its URL
+     instead — no local tunnel needed.
+   This step is REQUIRED — `localhost` is never reachable from Reclaim's
+   servers.
+4. `npm start`, then open http://localhost:3000/verify (or your deployed
+   URL's `/verify`) and click "Start verification".
+5. Watch the server logs for the `/webhooks/reclaim` payload once you
+   complete verification.
+
+This demo defaults to providerId `"example"` — a built-in smoke-test
+provider, so you can confirm the whole loop (request → open → callback)
+works before wiring in a real provider.

package/samples/demo-server/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "reclaim-demo-server",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "start": "node server.js"
+  },
+  "dependencies": {
+    "@reclaimprotocol/js-sdk": "^5.8.1",
+    "dotenv": "^16.4.5",
+    "express": "^4.21.2"
+  }
+}

package/samples/demo-server/server.js

@@ -0,0 +1,156 @@
+import express from "express";
+import "dotenv/config";
+import { ReclaimProofRequest, verifyProof } from "@reclaimprotocol/js-sdk";
+import { randomUUID } from "node:crypto";
+
+const app = express();
+const port = process.env.PORT || 3000;
+const providerId = __PROVIDER_ID__;
+// Left unpinned by default — set this if you need to pin a specific version.
+const providerVersion = __PROVIDER_VERSION__;
+
+app.set("trust proxy", true);
+app.use(express.json({ limit: "2mb" }));
+
+app.get("/health", (_req, res) => {
+  res.json({ ok: true });
+});
+
+app.get("/verify", (_req, res) => {
+  res.type("html").send(`<!doctype html>
+    <html lang="en">
+      <head>
+        <meta charset="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <title>Reclaim demo verification</title>
+        <style>
+          body {
+            font-family: system-ui, sans-serif; max-width: 680px;
+            margin: 64px auto; padding: 0 20px; line-height: 1.5;
+          }
+          code { background: #f3f4f6; padding: 2px 6px; border-radius: 4px; }
+          button {
+            background: #111827; border: 0; border-radius: 8px; color: white;
+            cursor: pointer; font: inherit; padding: 12px 18px;
+          }
+          button:disabled { cursor: wait; opacity: 0.7; }
+          pre {
+            background: #f3f4f6; border-radius: 8px; overflow: auto;
+            padding: 12px;
+          }
+        </style>
+      </head>
+      <body>
+        <h1>Reclaim demo verification</h1>
+        <p>Uses provider <code>${providerId}</code>.</p>
+        <button id="start">Start verification</button>
+        <pre id="status">Ready.</pre>
+        <p>Webhook endpoint: <code>/webhooks/reclaim</code></p>
+        <script>
+          const button = document.getElementById("start");
+          const status = document.getElementById("status");
+          button.addEventListener("click", async () => {
+            button.disabled = true;
+            status.textContent = "Creating verification request...";
+            try {
+              const response = await fetch("/api/reclaim/request", {
+                method: "POST",
+              });
+              if (!response.ok) throw new Error(await response.text());
+              const { requestUrl } = await response.json();
+              status.textContent = "Opening Reclaim verification...";
+              window.open(requestUrl, "_blank", "noopener,noreferrer");
+              status.textContent =
+                "Verification opened. Complete it in the Reclaim window.";
+            } catch (error) {
+              status.textContent =
+                error instanceof Error ? error.message : String(error);
+              button.disabled = false;
+            }
+          });
+        </script>
+      </body>
+    </html>`);
+});
+
+app.post("/api/reclaim/request", async (req, res, next) => {
+  try {
+    const appId = process.env.RECLAIM_APP_ID;
+    const appSecret = process.env.RECLAIM_APP_SECRET;
+    if (!appId || !appSecret) {
+      return res.status(500).json({
+        error: "Missing RECLAIM_APP_ID or RECLAIM_APP_SECRET",
+      });
+    }
+
+    const origin =
+      process.env.PUBLIC_URL || `${req.protocol}://${req.get("host")}`;
+    const reclaimProofRequest = await ReclaimProofRequest.init(
+      appId,
+      appSecret,
+      providerId,
+      { providerVersion },
+    );
+    reclaimProofRequest.setAppCallbackUrl(
+      `${origin}/webhooks/reclaim`,
+      true,
+    );
+    reclaimProofRequest.setContext(
+      randomUUID(),
+      JSON.stringify({ createdAt: new Date().toISOString() }),
+    );
+
+    // getRequestUrl() is ASYNC in the current SDK — must be awaited.
+    const requestUrl = await reclaimProofRequest.getRequestUrl();
+
+    res.json({
+      request: reclaimProofRequest.toJsonString(),
+      requestUrl,
+    });
+  } catch (error) {
+    next(error);
+  }
+});
+
+app.post("/webhooks/reclaim", async (req, res, next) => {
+  try {
+    // With jsonProofResponse: true + express.json() above, req.body is
+    // already a parsed Proof/Proof[]. Without either of those, the raw body
+    // is text and must be JSON.parse()'d (and URL-decoded if form-encoded)
+    // before calling verifyProof.
+    const proof = req.body;
+
+    // The second argument is REQUIRED — must include providerId.
+    const result = await verifyProof(proof, { providerId, providerVersion });
+
+    console.log("Received Reclaim verification:");
+    console.log(JSON.stringify(
+      { isVerified: result.isVerified, data: result.data, error: result.error },
+      null,
+      2,
+    ));
+
+    res.status(200).json({ received: true, verified: result.isVerified });
+  } catch (error) {
+    next(error);
+  }
+});
+
+app.use((err, _req, res, _next) => {
+  console.error(err);
+  res.status(500).json({
+    error: err instanceof Error ? err.message : "Internal server error",
+  });
+});
+
+app.listen(port, () => {
+  console.log(`Reclaim demo server listening on http://localhost:${port}`);
+  console.log(`Verify page:      http://localhost:${port}/verify`);
+  console.log(`Webhook endpoint: http://localhost:${port}/webhooks/reclaim`);
+  if (!process.env.PUBLIC_URL) {
+    console.log(
+      "Set PUBLIC_URL (e.g. an ngrok URL) so the webhook is reachable " +
+      "from Reclaim's servers.",
+    );
+  }
+});

package/skill/js-sdk-integration.md

@@ -0,0 +1,119 @@
+# @reclaimprotocol/js-sdk — backend integration guide
+
+Keep `appSecret` on your BACKEND only. Everything below runs server-side;
+the browser only ever sees the `requestUrl`.
+
+## Testing locally, without deploying anything
+
+- **providerId `"example"`**: a canonical built-in smoke-test provider —
+  no need to author/publish your own provider just to confirm the SDK
+  plumbing works end-to-end. Swap in your real providerId once this passes.
+- **A public callback URL**: `setAppCallbackUrl` needs a URL Reclaim's
+  servers can reach over the public internet — `localhost` will never
+  receive the callback. Two ways to get one, pick whichever fits:
+  - **ngrok** (or a similar tunnel): `ngrok http 3000` (or your port)
+    alongside your local server, then set `PUBLIC_URL` to the
+    `https://<id>.ngrok-free.app` URL it prints. Zero-deploy, but the tunnel
+    URL is temporary.
+  - **A dev/staging server you can deploy to quickly**: if you already have
+    one reachable from the internet, just point `PUBLIC_URL` at it instead —
+    skips the extra local tool.
+  Without either, only the frontend-side flow (opening `requestUrl` and
+  reading the result client-side) works — the async webhook never lands.
+- `scaffold_reclaim_demo_server` defaults `providerId` to `"example"`; its
+  README covers both callback-URL options above — use it to get a working
+  local loop before wiring in a real provider.
+
+## 1. Install
+
+```bash
+npm install @reclaimprotocol/js-sdk
+```
+
+## 2. Create a proof request (backend)
+
+```js
+import { ReclaimProofRequest } from "@reclaimprotocol/js-sdk";
+
+const reclaimProofRequest = await ReclaimProofRequest.init(
+  process.env.RECLAIM_APP_ID,
+  process.env.RECLAIM_APP_SECRET,
+  providerId,
+  {
+    // acceptAiProviders: true,   // allow AI-verified providers
+    // useAppClip: true,          // mobile app-clip flow, not a browser popup
+    // providerVersion: "1.0.0",  // pin a specific provider version
+  },
+);
+
+// Deliver the verified proof back to your server asynchronously instead of
+// (or in addition to) reading it from the frontend callback:
+reclaimProofRequest.setAppCallbackUrl(
+  `${process.env.PUBLIC_URL}/webhooks/reclaim`,
+  true, // jsonProofResponse: send the callback body as JSON, not form-encoded
+);
+
+// Optional: attach your own correlation id / metadata, retrievable later.
+reclaimProofRequest.setContext(
+  sessionId,
+  JSON.stringify({ createdAt: Date.now() }),
+);
+
+// IMPORTANT: getRequestUrl() is ASYNC — await it.
+const requestUrl = await reclaimProofRequest.getRequestUrl();
+
+// Hand the requestUrl to the frontend to open in a new tab/window/webview.
+// If you need to rehydrate this request object later (e.g. in the webhook
+// handler, in a different process), persist reclaimProofRequest.toJsonString()
+// (sync) and rehydrate with:
+//   const req = await ReclaimProofRequest.fromJsonString(json); // ASYNC
+```
+
+## 3. Frontend: open the request URL
+
+Fetch `requestUrl` from your backend, then open it (popup/new tab/QR code) —
+never construct it in the browser, since that would require the appSecret
+client-side. Trigger the fetch+open from a real user click (not a page-load
+effect) or some browsers block the popup.
+
+## 4. Verify the callback (backend webhook)
+
+```js
+import { verifyProof } from "@reclaimprotocol/js-sdk";
+
+app.post("/webhooks/reclaim", express.json(), async (req, res) => {
+  // req.body is already a parsed object here because jsonProofResponse was
+  // true above AND express.json() parsed it. If you did NOT set
+  // jsonProofResponse (or aren't using express.json()), the body arrives as
+  // form-encoded/raw text and must be JSON.parse()'d (and decodeURIComponent'd
+  // if form-encoded) into a Proof / Proof[] before calling verifyProof.
+  const proof = req.body;
+
+  // The second argument is REQUIRED — at minimum providerId.
+  const result = await verifyProof(proof, {
+    providerId,
+    // providerVersion,       // optional, pin if you pinned it in init()
+  });
+
+  if (!result.isVerified) {   // NOTE: isVerified, not is_verified
+    console.error("Proof verification failed:", result.error);
+    return res.status(400).json({ verified: false, error: result.error });
+  }
+
+  console.log("Verified data:", result.data, result.publicData);
+  res.status(200).json({ verified: true });
+});
+```
+
+## Gotchas
+
+- `getRequestUrl()` and `ReclaimProofRequest.fromJsonString()` are async —
+  a missing `await` silently hands you a Promise instead of a string/instance.
+- `verifyProof`'s config arg is mandatory; omitting `providerId` throws.
+- Prefer `setContext` over the deprecated `addContext` (same signature).
+- `ReclaimProofRequest.init` needs network access to the Reclaim backend at
+  call time — don't call it at module load / cold-start if your platform pools
+  processes long-term; call it per-request instead.
+- Use `check_app_status` (this MCP server) to confirm your app is linked
+  and not still sandbox-limited before debugging "verification never lands"
+  issues.

package/src/cdp/launcher.ts

@@ -28,42 +28,42 @@ export interface LaunchOptions {
  */
 function browserCandidates(): string[] {
 	switch (platform()) {
-	case 'darwin':
-		return [
-			'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
-			join(
-				homedir(),
-				'Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
-			),
-			'/Applications/Chromium.app/Contents/MacOS/Chromium',
-			'/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
-		]
-	case 'win32': {
-		const appData =
+		case 'darwin':
+			return [
+				'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+				join(
+					homedir(),
+					'Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+				),
+				'/Applications/Chromium.app/Contents/MacOS/Chromium',
+				'/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+			]
+		case 'win32': {
+			const appData =
 				localAppData() ?? join(homedir(), 'AppData', 'Local')
-		return [
+			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(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',
-		]
-	}
+				'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(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',
+			]
+		}
 
-	case 'linux':
-		return [
-			'/usr/bin/google-chrome',
-			'/usr/bin/google-chrome-stable',
-			'/usr/bin/chromium',
-			'/usr/bin/chromium-browser',
-			'/snap/bin/chromium',
-			'/usr/bin/microsoft-edge',
-		]
-	default:
-		return []
+		case 'linux':
+			return [
+				'/usr/bin/google-chrome',
+				'/usr/bin/google-chrome-stable',
+				'/usr/bin/chromium',
+				'/usr/bin/chromium-browser',
+				'/snap/bin/chromium',
+				'/usr/bin/microsoft-edge',
+			]
+		default:
+			return []
 	}
 }
 

package/src/mcp/api/tools.ts

@@ -1,9 +1,8 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import type { ReclaimClient } from '@reclaimprotocol/client'
 import type {
-	ReclaimClient
-} from '@reclaimprotocol/client'
-import type {
-	IOperationArgs, IOperationId
+	IOperationArgs,
+	IOperationId
 } from '@reclaimprotocol/client/openapi'
 import { remapErrorAsResponse } from '../remap_errors.ts'
 import { MCP_TOOLS } from './operations.gen.ts'

package/src/mcp/remap_errors.ts

@@ -29,7 +29,7 @@ export const remapErrorAsResponse = (
 			{
 				type: 'text' as const,
 				text: `${problemError.message}: ${problemError.data?.detail}`
-			 }
+			}
 		],
 	}
 }

package/src/mcp/tools/agent/shared.ts

@@ -14,10 +14,42 @@ import {
 } from '../../../authoring/index.ts'
 import { runAttestorProof } from '../../../proof/attestor.ts'
 import { replayProvider } from '../../../proof/replay.ts'
+import type { OprfMode, ReclaimProvider } from '../../../provider/schema.ts'
 import type { RegisteredTool } from '../../server.ts'
 import type { CaptureEntry, CaptureStore } from './capture.ts'
 import { shapeRichProofResult } from './proof.ts'
 
+/**
+ * OPRF mode this LOCAL (non-TEE) attestor can actually run. Recipes carry
+ * `oprf-mpc` — the canonical/publish mode a TEE expects — but the local dev
+ * attestor can't do MPC. gnark `oprf` (Linux/Mac, needs ZK circuits) is the
+ * strongest it supports; Windows falls back to server-side `oprf-raw` (no
+ * circuits). Proving with the wrong mode fails, which is what pushed the agent
+ * to hand-craft a plaintext workaround.
+ */
+const LOCAL_OPRF_MODE: OprfMode =
+	process.platform === 'win32' ? 'oprf-raw' : 'oprf'
+
+/**
+ * Clone `provider` with every `oprf-mpc` redaction remapped to the mode this
+ * local attestor can run, so the PROOF validates locally. The draft itself is
+ * untouched — it keeps `oprf-mpc`, so the PUBLISHED recipe is always the
+ * TEE-canonical mode regardless of where it was proved.
+ */
+function withLocalOprfMode(provider: ReclaimProvider): ReclaimProvider {
+	const reds = provider.responseRedactions
+	if(!reds?.some((r) => r.hash === 'oprf-mpc')) {
+		return provider
+	}
+
+	return {
+		...provider,
+		responseRedactions: reds.map((r) => {
+			return r.hash === 'oprf-mpc' ? { ...r, hash: LOCAL_OPRF_MODE } : r
+		}),
+	}
+}
+
 /** The local backend for one capture: drive its tab over CDP, read its
  *  captured requests, prove via the in-process attestor, replay by re-fetch. */
 function localBackend(entry: CaptureEntry): AuthoringBackend {
@@ -64,8 +96,10 @@ function localBackend(entry: CaptureEntry): AuthoringBackend {
 			}
 		},
 		prove: async(draft, opts) => {
+			// Prove with the locally-runnable OPRF mode; the draft (→ published
+			// recipe) keeps oprf-mpc.
 			const result = await runAttestorProof(
-				draft.provider,
+				withLocalOprfMode(draft.provider),
 				draft.secrets,
 				{
 					...(opts?.ownerAddress ? { ownerAddress: opts.ownerAddress } : {}),

package/src/mcp/tools/authenticate/authenticate.ts

@@ -1,7 +1,5 @@
 import type { ReclaimClient } from '@reclaimprotocol/client'
-import type {
-	CredentialAttachSession
-} from '@reclaimprotocol/client/openapi'
+import type { CredentialAttachSession } from '@reclaimprotocol/client/openapi'
 import { defineTool, type RegisteredTool } from '../../server.ts'
 import { writeSession } from './session-cache.ts'
 

package/src/mcp/tools/authenticate/decrypt-key.ts

@@ -11,10 +11,7 @@
  * The hex is loaded via the client's `loadDecryptionKey` and passed straight
  * through as `ReclaimConfig.credential` / to `decryptCallback`.
  */
-import {
-	type DecryptionKey,
-	loadDecryptionKey,
-} from '@reclaimprotocol/client'
+import { type DecryptionKey, loadDecryptionKey } from '@reclaimprotocol/client'
 import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { findProjectRoot } from '../../../paths.ts'

package/src/old/tools/issue-app-credentials.ts

@@ -9,7 +9,9 @@ import type { ReclaimOldClient } from '../client.ts'
  * and sandboxed (`sandboxLimit: 100` sessions). Use `link_app_to_account` to
  * attach it to your dashboard account, or `check_app_status` to inspect it.
  */
-export function issueAppCredentialsTool(client: ReclaimOldClient): RegisteredTool {
+export function issueAppCredentialsTool(
+	client: ReclaimOldClient,
+): RegisteredTool {
 	return defineTool<Record<string, never>>(
 		{
 			name: 'issue_app_credentials',