@reclaimprotocol/agent 0.1.10 → 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

@@ -12,7 +12,6 @@ import {
 	bumpPatchString,
 	extractVersions,
 	injectedRequestDataFrom,
-	type OldInjectedRequestData,
 	type OldProviderOpts,
 	providerToConfigBody,
 	providerToRegisterBody,
@@ -20,66 +19,6 @@ import {
 
 const DEFAULT_VERSION_INFO = 'Updated from MCP browser capture'
 
-/** Fields with no partial-patch equivalent on this backend: a version always
- *  replaces the WHOLE `providerConfig`, so omitting one of these on
- *  add-version must carry forward the current value rather than publish it
- *  blank. `allowedInjectedRequestData` is handled alongside these (further
- *  down, inline) since it needs translation when freshly authored, unlike
- *  these — which pass through unchanged either way. */
-const PRESERVABLE_KEYS = [
-	'customInjection',
-	'userAgent',
-	'pageTitle',
-	'stepsToFollow',
-	'useIncognitoWebview',
-	'extensionConfig',
-] as const
-
-/** Pull `providerConfig` out of a `get_provider_version_config` /
- *  `getProviderConfig` response, tolerant of a missing/malformed shape. */
-function extractProviderConfig(
-	resp: unknown,
-): Record<string, unknown> | undefined {
-	if(resp && typeof resp === 'object') {
-		const cfg = (resp as { providerConfig?: unknown }).providerConfig
-		if(cfg && typeof cfg === 'object') {
-			return cfg as Record<string, unknown>
-		}
-	}
-
-	return undefined
-}
-
-/** Prefer the caller's explicit value; otherwise fall back to `current`'s
- *  value (if any) and record `fieldName` as carried forward.
- *
- *  `current === null` is treated the SAME as `undefined` (nothing to carry),
- *  not as a real value to preserve. These are all optional fields with no
- *  Prisma default — a version where one was never set reads back as
- *  `null`, not a missing key, because Prisma normalizes an absent optional
- *  field to `null` on read. Carrying that `null` "forward" would falsely
- *  claim the field was preserved when really nothing was ever there — it
- *  most likely means an EARLIER version already lost it (e.g. published
- *  before this field had carry-forward support at all), not that this call
- *  is doing anything wrong. */
-function resolveField<T>(
-	explicit: T | undefined,
-	current: unknown,
-	fieldName: string,
-	carried: string[],
-): T | undefined {
-	if(explicit !== undefined) {
-		return explicit
-	}
-
-	if(current !== undefined && current !== null) {
-		carried.push(fieldName)
-		return current as T
-	}
-
-	return undefined
-}
-
 /**
  * The old backend lets you add a version only to a provider YOU own. A
  * `providerId` for a public provider (or anyone else's) comes back as
@@ -166,23 +105,19 @@ export function createVersionFromCaptureTool(
 				'For data gated behind login/navigation, pass `customInjection` — a ' +
 				'page-injection script (old-devtools\' name for the builder\'s ' +
 				'jsUserScripts) that drives the page to where the request fires. \n\n' +
-				'This backend has NO partial-patch endpoint — adding a version ' +
-				'always replaces the WHOLE providerConfig. When `providerId` is ' +
-				'set, any of `customInjection`, `userAgent`, `pageTitle`, ' +
-				'`allowedInjectedRequestData`, `stepsToFollow`, ' +
-				'`useIncognitoWebview`, `extensionConfig` that you OMIT is carried ' +
-				'forward unchanged from the currently-published version (so ' +
-				're-publishing requestData never wipes a working login script or ' +
-				'other config someone set via the dashboard). This can only carry ' +
-				'forward what the CURRENT version actually has — if an earlier ' +
-				'version already lost a field (e.g. published before this tool ' +
-				'carried it forward at all), there is nothing left to preserve and ' +
-				'the result legitimately comes back empty/null for that field; ' +
-				'that is not this call failing to carry it forward. Pass an ' +
-				'explicit value (`""`, `[]`, `false`, ...) to intentionally clear ' +
-				'one of them instead, or call get_provider_version_config FIRST ' +
-				'to see exactly what is live today, rather than assuming this ' +
-				'call recovered something that may already be gone. ' +
+				'BY DESIGN, this backend only ever CREATES A NEW VERSION (POST) — ' +
+				'there is no partial-patch/edit endpoint, and this tool does NOT ' +
+				'read or carry anything forward from the previous version. Every ' +
+				'new version replaces the WHOLE providerConfig with exactly what ' +
+				'you pass in THIS call. Therefore any field you want present in the ' +
+				'new version MUST be supplied here — `customInjection`, `userAgent`, ' +
+				'`pageTitle`, `allowedInjectedRequestData`, `stepsToFollow`, ' +
+				'`useIncognitoWebview`, `extensionConfig`, and `requestData` (via ' +
+				'`provider`/`providers`). Anything you OMIT is published blank/' +
+				'default in the new version, NOT preserved. To change one field ' +
+				'while keeping the rest, first read the current version with ' +
+				'get_provider_info, then pass the full desired config (the existing ' +
+				'values plus your change) back into this call. ' +
 				'`allowedInjectedRequestData`/`useIncognitoWebview`/' +
 				'`extensionConfig` only take effect on add-version — the register ' +
 				'endpoint (no `providerId`) ignores them. \n\n' +
@@ -213,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: {
@@ -316,6 +258,28 @@ export function createVersionFromCaptureTool(
 									description:
 										'Fail validation if none match. Default true.',
 								},
+								templateParams: {
+									type: 'array',
+									items: { type: 'string' },
+									description:
+										'Names of `${var}` placeholders used in this ' +
+										'template\'s `responseMatches`/`responseRedactions` ' +
+										'that should be substituted at verify time from the ' +
+										'submitted proof\'s own witness params. Omit (or ' +
+										'leave empty) if the template has no such ' +
+										'placeholders.',
+								},
+								templateParamsMode: {
+									type: 'string',
+									enum: ['separate', 'merge'],
+									description:
+										'How multiple values for `templateParams` expand ' +
+										'into request specs. `separate` (default): one ' +
+										'independent spec per value, each matching its own ' +
+										'proof. `merge`: fold all values into ONE spec with ' +
+										'one match/redaction entry per value, matching a ' +
+										'single proof that bundles them all into one claim.',
+								},
 							},
 							required: ['url', 'method'],
 						},
@@ -344,37 +308,52 @@ 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!]
-
-			const opts: OldProviderOpts = { initialUrl: args.initialUrl }
-			if(args.description !== undefined) {
-				opts.description = args.description
-			}
-
-			if(args.geoLocation !== undefined) {
-				opts.geoLocation = args.geoLocation
-			}
-
-			if(args.useProxy !== undefined) {
-				opts.useProxy = args.useProxy
+			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 },
+				)
 			}
 
-			if(args.providerType !== undefined) {
-				opts.providerType = args.providerType
-			}
+			const providers = hasMany ? args.providers! : (hasOne ? [args.provider!] : [])
 
-			if(args.customInjection !== undefined) {
-				opts.customInjection = args.customInjection
+			const opts: OldProviderOpts = {
+				initialUrl: args.initialUrl,
+				description: args.description,
+				geoLocation: args.geoLocation,
+				useProxy: args.useProxy,
+				providerType: args.providerType,
+				customInjection: args.customInjection,
+				userAgent: args.userAgent,
+				pageTitle: args.pageTitle,
+				stepsToFollow: args.stepsToFollow,
+				useIncognitoWebview: args.useIncognitoWebview,
+				extensionConfig: args.extensionConfig,
+				allowedInjectedRequestData: args.allowedInjectedRequestData
+					? injectedRequestDataFrom(
+						args.allowedInjectedRequestData,
+					)
+					: undefined
 			}
 
 			// Non-blocking advisory per request — never alters or blocks the
@@ -414,27 +393,15 @@ export function createVersionFromCaptureTool(
 					.filter((k) => args[k] !== undefined)
 				if(ignoredOnRegister.length) {
 					notes.push(
-						`${ignoredOnRegister.join(', ')} ${
-							ignoredOnRegister.length > 1 ? 'are' : 'is'
-						} ignored on register (no providerId) — the old backend only ` +
+						`${ignoredOnRegister.join(', ')} ` +
+						`${ignoredOnRegister.length > 1 ? 'are' : 'is'} ` +
+						'ignored on register (no providerId) — the old backend only ' +
 						'reads them when adding a version. Publish once to create ' +
 						'the provider, then call this again WITH the returned ' +
 						'providerId to set them.',
 					)
 				}
 
-				if(args.userAgent !== undefined) {
-					opts.userAgent = args.userAgent
-				}
-
-				if(args.pageTitle !== undefined) {
-					opts.pageTitle = args.pageTitle
-				}
-
-				if(args.stepsToFollow !== undefined) {
-					opts.stepsToFollow = args.stepsToFollow
-				}
-
 				const body = providerToRegisterBody(providers, opts)
 				return withNotes(await client.registerProvider(body))
 			}
@@ -445,48 +412,12 @@ export function createVersionFromCaptureTool(
 			// workaround instead of a bare permission error.
 			const providerId = args.providerId
 			try {
-				// This backend has no partial-patch endpoint — a version always
-				// replaces the WHOLE providerConfig. Anything the caller didn't
-				// pass at all is carried forward from the currently-published
-				// version instead of going out blank. Pass an explicit empty
-				// value ("", [], false) to intentionally clear one.
-				const needsCurrent = PRESERVABLE_KEYS.some((k) => args[k] === undefined)
-					|| args.allowedInjectedRequestData === undefined
-				const current = needsCurrent
-					? extractProviderConfig(await client.getProviderConfig(providerId))
-					: undefined
-
-				const carried: string[] = []
-				for(const key of PRESERVABLE_KEYS) {
-					const resolved = resolveField(args[key], current?.[key], key, carried)
-					if(resolved !== undefined) {
-						(opts as unknown as Record<string, unknown>)[key] = resolved
-					}
-				}
-
-				const freshInjected = args.allowedInjectedRequestData !== undefined
-					? injectedRequestDataFrom(args.allowedInjectedRequestData)
-					: undefined
-				const resolvedInjected = resolveField<OldInjectedRequestData[]>(
-					freshInjected,
-					current?.allowedInjectedRequestData,
-					'allowedInjectedRequestData',
-					carried,
-				)
-				if(resolvedInjected !== undefined) {
-					opts.allowedInjectedRequestData = resolvedInjected
-				}
-
-				if(carried.length) {
-					notes.push(
-						'Not passed, carried forward unchanged from the current ' +
-						`published version: ${carried.join(', ')}. Pass an explicit ` +
-						'value ("", [], false, ...) to override any of them, or ' +
-						'call get_provider_version_config first to see what is ' +
-						'live today.',
-					)
-				}
-
+				// By design this always POSTs a brand-new version and publishes
+				// EXACTLY the config assembled above — nothing is read back or
+				// carried forward. Any field the caller omitted is already absent
+				// from `opts` and will be blank/default in the new version. To
+				// preserve existing fields, the caller must have read them via
+				// get_provider_info and passed them back in.
 				if(args.customInjection !== undefined && opts.customInjection?.trim()) {
 					notes.push(
 						'customInjection will run in the verification client before ' +
@@ -495,6 +426,15 @@ export function createVersionFromCaptureTool(
 					)
 				}
 
+				notes.push(
+					'A NEW version was created with only the fields passed in this ' +
+					'call — nothing was carried forward from the previous version. ' +
+					'If you intended to keep other fields (customInjection, ' +
+					'userAgent, allowedInjectedRequestData, ...), read the prior ' +
+					'version with get_provider_info and re-publish with them ' +
+					'included.',
+				)
+
 				const versionsResp = await client.listVersions(providerId)
 				const version = bumpPatchString(extractVersions(versionsResp))
 				const versionInfo =