@reclaimprotocol/agent 0.1.11 → 0.1.12

package/src/old/tools/js-sdk-integration-guide.ts

@@ -0,0 +1,147 @@
+import { defineTool, type RegisteredTool } from '../../mcp/server.ts'
+
+/**
+ * Verified against `@reclaimprotocol/js-sdk` v5.8.1 source
+ * (`reclaim-js-sdk/src/Reclaim.ts`) — NOT copied unchecked from the archived
+ * `reclaim-mcp-server`'s guide, which predates several of these signatures.
+ * Corrections that matter most, all called out inline below:
+ *   - `getRequestUrl()` and `ReclaimProofRequest.fromJsonString()` are ASYNC.
+ *   - `setContext` is current; `addContext` is deprecated (calls setContext).
+ *   - `verifyProof`'s second arg (`{ providerId, providerVersion? }`) is
+ *     REQUIRED, not optional.
+ *   - The verified result's flag is `isVerified` (camelCase), not
+ *     `is_verified`.
+ *   - A raw webhook body is TEXT — it must be JSON-parsed (and URL-decoded if
+ *     form-encoded) into a `Proof`/`Proof[]` before calling `verifyProof`.
+ */
+const GUIDE = `# @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.
+- **ngrok for the callback URL**: \`setAppCallbackUrl\` needs a URL Reclaim's
+  servers can reach over the public internet — \`localhost\` will never
+  receive the callback. Run \`ngrok http 3000\` (or your port) alongside your
+  local server and set \`PUBLIC_URL\` to the \`https://<id>.ngrok-free.app\`
+  URL it prints. Without this, only the frontend-side flow (opening
+  \`requestUrl\` and polling/reading the result client-side) will work — the
+  async webhook never lands.
+- \`scaffold_reclaim_demo_server\` defaults \`providerId\` to \`"example"\` and
+  its README calls out the ngrok step — 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 instead of 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.
+`
+
+export function getJsSdkIntegrationGuideTool(): RegisteredTool {
+	return defineTool<Record<string, never>>(
+		{
+			name: 'get_js_sdk_integration_guide',
+			description:
+				'Return a verified, copy-pasteable guide for integrating ' +
+				'@reclaimprotocol/js-sdk (backend proof request + callback ' +
+				'verification), checked against the current SDK source rather than ' +
+				'assumed from older docs. Covers testing locally without deploying: ' +
+				'the built-in "example" providerId for a quick smoke test, and using ' +
+				'ngrok to get a callback URL Reclaim\'s servers can actually reach. ' +
+				'Use scaffold_reclaim_demo_server to generate a runnable local demo ' +
+				'instead of copy-pasting by hand.',
+			inputSchema: { type: 'object', properties: {} },
+		},
+		async() => ({ guide: GUIDE }),
+	)
+}

package/src/old/tools/link-app.ts

@@ -0,0 +1,88 @@
+import { Wallet } from 'ethers'
+import { defineTool, type RegisteredTool } from '../../mcp/server.ts'
+import type { ReclaimOldClient } from '../client.ts'
+
+/** Byte-for-byte the same format as the backend's `buildLinkMessage` in
+ *  `application.controller.ts` — MUST stay in lockstep with it. */
+function buildLinkMessage(appId: string, userId: string, nonce: string): string {
+	return `Link ${appId} to account ${userId} | nonce: ${nonce}`
+}
+
+/** The uid the backend binds into the signed message — `req.user.uid` there.
+ *  For a bearer identity this comes back from `POST /users/login`; for an eth
+ *  identity, `OldIdentity.uid` (already `eth:<address>`) IS that uid. */
+async function resolveUserId(client: ReclaimOldClient): Promise<string> {
+	const identity = client.getIdentity()
+	if(!identity) {
+		throw new Error(
+			'Not authenticated against old devtools. Call reclaim_authenticate first.',
+		)
+	}
+
+	if(identity.kind === 'eth') {
+		return identity.uid
+	}
+
+	const res = await client.loginWithToken() as { user?: { uid?: string } }
+	const uid = res?.user?.uid
+	if(!uid) {
+		throw new Error(
+			'Could not resolve your account uid from POST /users/login — ' +
+			'unexpected response shape.',
+		)
+	}
+
+	return uid
+}
+
+/**
+ * Link an unassociated app (minted via `issue_app_credentials`, or any
+ * eth-keypair app you already hold the private key for) to the currently
+ * authenticated dashboard account. Proves ownership by signing a one-time
+ * challenge with the app's private key — the private key itself is only
+ * ever used locally to sign, never sent to the server.
+ */
+export function linkAppTool(client: ReclaimOldClient): RegisteredTool {
+	return defineTool<{ appId: string, appSecret: string }>(
+		{
+			name: 'link_app_to_account',
+			description:
+				'Link an eth-keypair app to your authenticated dashboard account — ' +
+				'use this to keep using an appId/appSecret you already have ' +
+				'(instead of minting a fresh one via issue_app_credentials). ' +
+				'Requires reclaim_authenticate first. Fetches a one-time nonce, ' +
+				'signs `Link <appId> to account <userId> | nonce: <nonce>` locally ' +
+				'with `appSecret` (EIP-191, never transmitted), and submits the ' +
+				'signature. Fails with APP_ALREADY_LINKED if the app is already ' +
+				'linked to a (possibly different) account.',
+			inputSchema: {
+				type: 'object',
+				properties: {
+					appId: {
+						type: 'string',
+						description: 'The eth-address appId to link.',
+					},
+					appSecret: {
+						type: 'string',
+						description:
+							'The app\'s raw eth private key — used only locally to sign ' +
+							'the link challenge, never sent to the server.',
+					},
+				},
+				required: ['appId', 'appSecret'],
+			},
+		},
+		async({ appId, appSecret }) => {
+			const userId = await resolveUserId(client)
+			const { nonce } = await client.getLinkNonce()
+			const message = buildLinkMessage(appId, userId, nonce)
+			const signature = await new Wallet(appSecret).signMessage(message)
+			await client.linkAppToAccount(appId, signature, nonce)
+			return {
+				linked: true,
+				appId,
+				note: 'App linked to your account. Run check_app_status to confirm.',
+			}
+		},
+	)
+}

package/src/old/tools/publish.ts

@@ -148,8 +148,15 @@ export function createVersionFromCaptureTool(
 							'Multiple proven drafts → one multi-request version (each ' +
 							'becomes a parallel `requestData` entry, all verified ' +
 							'together). Each item has the same shape as `provider`. Pass ' +
-							'this OR `provider`, not both.',
-						minItems: 1,
+							'this OR `provider`, not both. May be omitted (or empty) ' +
+							'together with `provider` ONLY when adding a version to an ' +
+							'EXISTING provider (`providerId` set) — this publishes with ' +
+							'zero `requestData` entries, for a pure customInjection/' +
+							'HAWKEYE provider that relies entirely on ' +
+							'`allowedInjectedRequestData` for validation instead of a ' +
+							'static requestData stub. Registering a brand-new provider ' +
+							'always needs at least one draft (its name comes from the ' +
+							'first one).',
 						items: {
 							type: 'object',
 							properties: {
@@ -301,17 +308,34 @@ export function createVersionFromCaptureTool(
 		async(args) => {
 			// Exactly one of `provider` / `providers` — normalize to an array so a
 			// multi-request capture publishes every request, not just the first.
+			// Omitting both is allowed too, but ONLY when adding a version to an
+			// EXISTING provider (`providerId` set): that publishes with zero
+			// `requestData` entries, which only makes sense for a pure
+			// customInjection/HAWKEYE provider whose claims are validated entirely
+			// via `allowedInjectedRequestData` instead of a static requestData stub.
+			// Registering a brand-new provider (no `providerId`) still needs at
+			// least one draft — its name comes from the first one.
 			const hasMany = Array.isArray(args.providers) && args.providers.length > 0
 			const hasOne = !!args.provider
-			if(hasMany === hasOne) {
+			if(hasMany && hasOne) {
 				throw new Boom(
-					'Pass exactly one of `provider` (a single draft) or `providers` ' +
-					'(an array of 1+ drafts).',
+					'Pass at most one of `provider` (a single draft) or `providers` ' +
+					'(an array of 1+ drafts) — not both.',
 					{ statusCode: 400 },
 				)
 			}
 
-			const providers = hasMany ? args.providers! : [args.provider!]
+			if(!hasMany && !hasOne && !args.providerId) {
+				throw new Boom(
+					'Pass at least one of `provider`/`providers` when registering a ' +
+					'new provider (its name comes from the first draft). Omitting ' +
+					'both is only allowed when adding a version to an EXISTING ' +
+					'provider via `providerId`.',
+					{ statusCode: 400 },
+				)
+			}
+
+			const providers = hasMany ? args.providers! : (hasOne ? [args.provider!] : [])
 
 			const opts: OldProviderOpts = {
 				initialUrl: args.initialUrl,

package/src/old/tools/scaffold-demo-server.ts

@@ -0,0 +1,265 @@
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { isAbsolute, join } from 'node:path'
+import { defineTool, type RegisteredTool } from '../../mcp/server.ts'
+import { findProjectRoot } from '../../paths.ts'
+
+/** Corrected against `@reclaimprotocol/js-sdk` v5.8.1 (`Reclaim.ts`): awaits
+ *  `getRequestUrl()`, uses `setContext` (not deprecated `addContext`), JSON-
+ *  parses the raw webhook body before `verifyProof`, passes the required
+ *  `{ providerId, providerVersion }` config, and reads `result.isVerified`
+ *  (not `is_verified`). `providerVersion` is left unpinned (`undefined`) by
+ *  default — the built-in "example" providerId isn't versioned, so pinning
+ *  one is only meaningful once you swap in your own provider. */
+function serverJs(providerId: string, providerVersion: string | undefined): string {
+	return `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 = ${JSON.stringify(providerId)};
+// Left unpinned by default — set this if you need to pin a specific version.
+const providerVersion = ${providerVersion ? JSON.stringify(providerVersion) : 'undefined'};
+
+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.");
+  }
+});
+`
+}
+
+const PACKAGE_JSON = (name: string) => JSON.stringify(
+	{
+		name,
+		private: true,
+		type: 'module',
+		scripts: { start: 'node server.js' },
+		dependencies: {
+			'@reclaimprotocol/js-sdk': '^5.8.1',
+			dotenv: '^16.4.5',
+			express: '^4.21.2',
+		},
+	},
+	null,
+	2,
+) + '\n'
+
+const ENV_EXAMPLE = `RECLAIM_APP_ID=
+RECLAIM_APP_SECRET=
+PORT=3000
+# REQUIRED for the webhook callback to land — Reclaim's servers can't reach
+# localhost. Run: ngrok http 3000 (in a separate terminal) and paste the
+# https://<id>.ngrok-free.app URL it prints here. Without this, only the
+# frontend-side flow works (opening requestUrl) — the webhook never fires.
+PUBLIC_URL=
+`
+
+const README = `# 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. 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 into \`PUBLIC_URL\` in \`.env\`. This is REQUIRED — Reclaim's
+   servers must reach your webhook over the public internet, and
+   \`localhost\` is not reachable from there.
+4. \`npm start\`, then open http://localhost:3000/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.
+`
+
+/**
+ * Scaffold a small, runnable Express demo that exercises the full
+ * @reclaimprotocol/js-sdk flow end-to-end: request a proof (backend), open it
+ * (frontend), and verify the async webhook callback (backend). Corrected
+ * against the CURRENT SDK API (see js-sdk-integration-guide) rather than
+ * older examples that predate several signature changes.
+ */
+const DEFAULT_PROVIDER_ID = 'example'
+
+export function scaffoldDemoServerTool(): RegisteredTool {
+	return defineTool<{
+		targetDir: string
+		providerId?: string
+		providerVersion?: string
+	}>(
+		{
+			name: 'scaffold_reclaim_demo_server',
+			description:
+				'Write a small runnable Express demo (server.js, package.json, ' +
+				'.env.example, README.md) that requests a Reclaim proof and ' +
+				'verifies the async webhook callback, using the CURRENT ' +
+				'@reclaimprotocol/js-sdk API. Defaults `providerId` to the built-in ' +
+				'"example" smoke-test provider so you can confirm the whole loop ' +
+				'without authoring one first, and requires ngrok (or similar) to ' +
+				'expose the local server so the webhook callback can reach it — ' +
+				'the generated README walks through that step. Use ' +
+				'get_js_sdk_integration_guide for the annotated write-up of the ' +
+				'same flow.',
+			inputSchema: {
+				type: 'object',
+				properties: {
+					targetDir: {
+						type: 'string',
+						description:
+							'Directory to write the demo into (created if missing). ' +
+							'Relative paths resolve against the project root.',
+					},
+					providerId: {
+						type: 'string',
+						description:
+							'Provider id the demo requests a proof for (default ' +
+							'"example", a built-in smoke-test provider — good for ' +
+							'confirming the flow works before wiring in a real one).',
+					},
+					providerVersion: {
+						type: 'string',
+						description:
+							'Provider version to pin (default: unpinned — "example" ' +
+							'isn\'t versioned, so only set this once you swap in your ' +
+							'own provider).',
+					},
+				},
+				required: ['targetDir'],
+			},
+		},
+		async({ targetDir, providerId, providerVersion }) => {
+			const dir = isAbsolute(targetDir)
+				? targetDir
+				: join(findProjectRoot(process.cwd()), targetDir)
+			mkdirSync(dir, { recursive: true })
+
+			const id = providerId ?? DEFAULT_PROVIDER_ID
+			writeFileSync(join(dir, 'server.js'), serverJs(id, providerVersion))
+			writeFileSync(join(dir, 'package.json'), PACKAGE_JSON('reclaim-demo-server'))
+			writeFileSync(join(dir, '.env.example'), ENV_EXAMPLE)
+			writeFileSync(join(dir, 'README.md'), README)
+
+			return {
+				dir,
+				providerId: id,
+				files: ['server.js', 'package.json', '.env.example', 'README.md'],
+				next: 'cd into the directory, npm install, copy .env.example to .env ' +
+					'and fill it in (including PUBLIC_URL from ngrok), then npm start.',
+			}
+		},
+	)
+}