@reclaimprotocol/agent 0.1.10 → 0.1.12

package/lib/old/tools/js-sdk-integration-guide.js

@@ -0,0 +1,141 @@
+import { defineTool } from "../../mcp/server.js";
+/**
+ * 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() {
+    return defineTool({
+        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/lib/old/tools/link-app.d.ts

@@ -0,0 +1,10 @@
+import { type RegisteredTool } from '../../mcp/server.ts';
+import type { ReclaimOldClient } from '../client.ts';
+/**
+ * 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 declare function linkAppTool(client: ReclaimOldClient): RegisteredTool;

package/lib/old/tools/link-app.js

@@ -0,0 +1,72 @@
+import { Wallet } from 'ethers';
+import { defineTool } from "../../mcp/server.js";
+/** Byte-for-byte the same format as the backend's `buildLinkMessage` in
+ *  `application.controller.ts` — MUST stay in lockstep with it. */
+function buildLinkMessage(appId, userId, nonce) {
+    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) {
+    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();
+    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) {
+    return defineTool({
+        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/lib/old/tools/publish.js

@@ -4,53 +4,6 @@ import { INJECTION_GUIDE } from "../../provider/injection-doc.js";
 import { countsFor, matchRedactionWarnings, } from "../../provider/match-redaction-warning.js";
 import { bumpPatchString, extractVersions, injectedRequestDataFrom, providerToConfigBody, providerToRegisterBody, } from "../to-register.js";
 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',
-];
-/** Pull `providerConfig` out of a `get_provider_version_config` /
- *  `getProviderConfig` response, tolerant of a missing/malformed shape. */
-function extractProviderConfig(resp) {
-    if (resp && typeof resp === 'object') {
-        const cfg = resp.providerConfig;
-        if (cfg && typeof cfg === 'object') {
-            return cfg;
-        }
-    }
-    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(explicit, current, fieldName, carried) {
-    if (explicit !== undefined) {
-        return explicit;
-    }
-    if (current !== undefined && current !== null) {
-        carried.push(fieldName);
-        return current;
-    }
-    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
@@ -111,23 +64,19 @@ export function createVersionFromCaptureTool(client) {
             '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' +
@@ -156,8 +105,15 @@ export function createVersionFromCaptureTool(client) {
                     description: '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: {
@@ -250,6 +206,26 @@ export function createVersionFromCaptureTool(client) {
                                 type: 'boolean',
                                 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'],
                     },
@@ -274,29 +250,42 @@ export function createVersionFromCaptureTool(client) {
     }, 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) {
-            throw new Boom('Pass exactly one of `provider` (a single draft) or `providers` ' +
-                '(an array of 1+ drafts).', { statusCode: 400 });
-        }
-        const providers = hasMany ? args.providers : [args.provider];
-        const opts = { initialUrl: args.initialUrl };
-        if (args.description !== undefined) {
-            opts.description = args.description;
-        }
-        if (args.geoLocation !== undefined) {
-            opts.geoLocation = args.geoLocation;
+        if (hasMany && hasOne) {
+            throw new Boom('Pass at most one of `provider` (a single draft) or `providers` ' +
+                '(an array of 1+ drafts) — not both.', { statusCode: 400 });
         }
-        if (args.useProxy !== undefined) {
-            opts.useProxy = args.useProxy;
-        }
-        if (args.providerType !== undefined) {
-            opts.providerType = args.providerType;
-        }
-        if (args.customInjection !== undefined) {
-            opts.customInjection = args.customInjection;
+        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 = {
+            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
         // publish; the author keeps full control. Attaches under `_notes`.
         const notes = matchRedactionWarnings(providers.map((p, i) => countsFor(`Request ${i + 1}`, p)));
@@ -325,20 +314,13 @@ export function createVersionFromCaptureTool(client) {
             const ignoredOnRegister = REGISTER_IGNORED_KEYS
                 .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 ` +
+                notes.push(`${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));
         }
@@ -348,42 +330,23 @@ export function createVersionFromCaptureTool(client) {
         // 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 = [];
-            for (const key of PRESERVABLE_KEYS) {
-                const resolved = resolveField(args[key], current?.[key], key, carried);
-                if (resolved !== undefined) {
-                    opts[key] = resolved;
-                }
-            }
-            const freshInjected = args.allowedInjectedRequestData !== undefined
-                ? injectedRequestDataFrom(args.allowedInjectedRequestData)
-                : undefined;
-            const resolvedInjected = resolveField(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 ' +
                     'every page load (before navigating to initialUrl), matching ' +
                     'the builder\'s jsUserScripts.');
             }
+            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 = args.notes && args.notes.trim().length >= 10

package/lib/old/tools/scaffold-demo-server.d.ts

@@ -0,0 +1,2 @@
+import { type RegisteredTool } from '../../mcp/server.ts';
+export declare function scaffoldDemoServerTool(): RegisteredTool;