@reclaimprotocol/agent 0.1.10 → 0.1.12

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.',
+			}
+		},
+	)
+}

package/src/old/tools/verify-sdk-setup.ts

@@ -0,0 +1,158 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { defineTool, type RegisteredTool } from '../../mcp/server.ts'
+import { findProjectRoot } from '../../paths.ts'
+import type { ReclaimOldClient } from '../client.ts'
+
+interface Check {
+	name: string
+	ok: boolean
+	detail: string
+}
+
+function readEnvFile(dir: string): Record<string, string> {
+	const path = join(dir, '.env')
+	if(!existsSync(path)) {
+		return {}
+	}
+
+	const out: Record<string, string> = {}
+	for(const line of readFileSync(path, 'utf8').split('\n')) {
+		const m = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$/)
+		if(m) {
+			out[m[1]] = m[2].replace(/^['"]|['"]$/g, '')
+		}
+	}
+
+	return out
+}
+
+/**
+ * Health-check a project's @reclaimprotocol/js-sdk setup: SDK installed,
+ * RECLAIM_APP_ID/RECLAIM_APP_SECRET present (env or .env), and (if an appId
+ * is found) whether that app is actually linked/has quota, via the real
+ * check_app_status endpoint — not just static file checks.
+ */
+export function verifySdkSetupTool(client: ReclaimOldClient): RegisteredTool {
+	return defineTool<{ projectDir?: string }>(
+		{
+			name: 'verify_reclaim_sdk_setup',
+			description:
+				'Health-check a project\'s @reclaimprotocol/js-sdk integration: SDK ' +
+				'installed, RECLAIM_APP_ID/RECLAIM_APP_SECRET present, and (if an ' +
+				'appId is found) whether that app is actually linked and has quota ' +
+				'left, by calling the real status endpoint.',
+			inputSchema: {
+				type: 'object',
+				properties: {
+					projectDir: {
+						type: 'string',
+						description: 'Project directory (default: detected project root).',
+					},
+				},
+			},
+		},
+		async({ projectDir }) => {
+			const dir = projectDir ?? findProjectRoot(process.cwd())
+			const checks: Check[] = []
+
+			const pkgPath = join(dir, 'package.json')
+			let sdkInPkg = false
+			if(existsSync(pkgPath)) {
+				try {
+					const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
+					sdkInPkg = Boolean(
+						pkg.dependencies?.['@reclaimprotocol/js-sdk'] ||
+						pkg.devDependencies?.['@reclaimprotocol/js-sdk'],
+					)
+				} catch{
+					// malformed package.json — fall through, reported below
+				}
+			}
+
+			const sdkInstalled = existsSync(
+				join(dir, 'node_modules', '@reclaimprotocol', 'js-sdk'),
+			)
+			checks.push({
+				name: 'sdk_dependency',
+				ok: sdkInPkg,
+				detail: sdkInPkg
+					? '@reclaimprotocol/js-sdk is listed in package.json'
+					: '@reclaimprotocol/js-sdk is NOT in package.json — run ' +
+						'`npm install @reclaimprotocol/js-sdk`.',
+			})
+			checks.push({
+				name: 'sdk_installed',
+				ok: sdkInstalled,
+				detail: sdkInstalled
+					? '@reclaimprotocol/js-sdk found in node_modules'
+					: 'Not found in node_modules — run your package manager\'s ' +
+						'install command.',
+			})
+
+			const env = { ...readEnvFile(dir), ...process.env }
+			const appId = env.RECLAIM_APP_ID
+			const appSecret = env.RECLAIM_APP_SECRET
+			checks.push({
+				name: 'app_id',
+				ok: Boolean(appId),
+				detail: appId
+					? `RECLAIM_APP_ID set (${appId})`
+					: 'RECLAIM_APP_ID missing (env or .env) — run ' +
+						'issue_app_credentials or link_app_to_account.',
+			})
+			checks.push({
+				name: 'app_secret',
+				ok: Boolean(appSecret),
+				detail: appSecret
+					? 'RECLAIM_APP_SECRET set'
+					: 'RECLAIM_APP_SECRET missing (env or .env).',
+			})
+
+			// Informational only — PUBLIC_URL is only needed for the async
+			// webhook callback, not the frontend-only flow, so a missing value
+			// doesn't fail the overall check.
+			const publicUrl = env.PUBLIC_URL
+			checks.push({
+				name: 'public_url',
+				ok: true,
+				detail: publicUrl
+					? `PUBLIC_URL set (${publicUrl}) — used as the webhook callback ` +
+						'base for setAppCallbackUrl.'
+					: 'PUBLIC_URL not set — fine if you only read the proof from the ' +
+						'frontend flow, but the async webhook callback needs a ' +
+						'publicly-reachable URL (e.g. from `ngrok http <port>`) or it ' +
+						'will never fire.',
+			})
+
+			if(appId) {
+				try {
+					const status = await client.getApplicationStatus(appId) as {
+						isLinked?: boolean
+						sandboxMode?: boolean
+						available?: boolean
+					}
+					const linked = status?.isLinked === true
+					checks.push({
+						name: 'app_status',
+						ok: status?.available !== false,
+						detail:
+							`isLinked=${linked}, sandboxMode=${status?.sandboxMode}, ` +
+							`available=${status?.available}` +
+							(linked ? '' : ' — run link_app_to_account to lift the sandbox limit.'),
+					})
+				} catch(err) {
+					checks.push({
+						name: 'app_status',
+						ok: false,
+						detail: `Could not reach status endpoint: ${
+							err instanceof Error ? err.message : String(err)
+						}`,
+					})
+				}
+			}
+
+			return { projectDir: dir, checks, ok: checks.every((c) => c.ok) }
+		},
+	)
+}