@reclaimprotocol/agent 0.1.11 → 0.1.12

package/lib/old/client.d.ts

@@ -71,6 +71,20 @@ export interface MyProvidersQuery {
     pageSize?: number;
     searchQuery?: string;
 }
+/** `POST /api/applications/issue-credentials` response — a brand-new,
+ *  unassociated (sandboxed) app. `appSecret` is the raw eth private key;
+ *  it's returned once and never stored server-side in recoverable form. */
+export interface IssuedAppCredentials {
+    appId: string;
+    appSecret: string;
+}
+/** `GET /api/applications/link/nonce` response — a one-time, 5-minute-TTL
+ *  challenge the caller signs with the app's private key to prove ownership
+ *  in `linkAppToAccount`. */
+export interface LinkNonce {
+    nonce: string;
+    expiresInSeconds: number;
+}
 /**
  * Minimal REST client for the OLD devtools Express backend (base `/api`).
  * Deliberately NOT a clone of `@reclaimprotocol/client`'s operationId
@@ -110,5 +124,22 @@ export declare class ReclaimOldClient {
      *  `#request`). Attaches the caller identity when one is set; queried
      *  anonymously otherwise. */
     getSessionAnalyticsLogs(sessionId: string): Promise<unknown>;
+    /** Mint a brand-new, unassociated (sandboxed) app — no auth required. Link
+     *  it to an account afterwards with `getLinkNonce` + `linkAppToAccount`, or
+     *  use it as-is within the sandbox session limit. */
+    issueCredentials(): Promise<IssuedAppCredentials>;
+    /** One-time, 5-minute challenge for `linkAppToAccount`. Requires auth —
+     *  the nonce is scoped to the authenticated user's uid. */
+    getLinkNonce(): Promise<LinkNonce>;
+    /** Link an unassociated (`issueCredentials`-minted) app to the
+     *  authenticated account. `signature` must be an EIP-191 signature, made
+     *  with the app's private key, over the exact string
+     *  `` `Link ${appId} to account ${userId} | nonce: ${nonce}` `` — see
+     *  `buildLinkMessage` in the backend's `application.controller.ts`. Fails
+     *  with `APP_ALREADY_LINKED` (400) if the app already belongs to someone. */
+    linkAppToAccount(appId: string, signature: string, nonce: string): Promise<unknown>;
+    /** Public, unauthenticated app status — `isLinked`, sandbox/quota info.
+     *  Works for any appId, owned or not. */
+    getApplicationStatus(appId: string): Promise<unknown>;
     getMyProviders(query?: MyProvidersQuery): Promise<unknown>;
 }

package/lib/old/client.js

@@ -89,6 +89,39 @@ export class ReclaimOldClient {
         }
         return json;
     }
+    /** Mint a brand-new, unassociated (sandboxed) app — no auth required. Link
+     *  it to an account afterwards with `getLinkNonce` + `linkAppToAccount`, or
+     *  use it as-is within the sandbox session limit. */
+    async issueCredentials() {
+        const res = await __classPrivateFieldGet(this, _ReclaimOldClient_instances, "m", _ReclaimOldClient_request).call(this, 'POST', '/applications/issue-credentials');
+        return res.data;
+    }
+    /** One-time, 5-minute challenge for `linkAppToAccount`. Requires auth —
+     *  the nonce is scoped to the authenticated user's uid. */
+    async getLinkNonce() {
+        const res = await __classPrivateFieldGet(this, _ReclaimOldClient_instances, "m", _ReclaimOldClient_request).call(this, 'GET', '/applications/link/nonce', {
+            auth: true,
+        });
+        return res.data;
+    }
+    /** Link an unassociated (`issueCredentials`-minted) app to the
+     *  authenticated account. `signature` must be an EIP-191 signature, made
+     *  with the app's private key, over the exact string
+     *  `` `Link ${appId} to account ${userId} | nonce: ${nonce}` `` — see
+     *  `buildLinkMessage` in the backend's `application.controller.ts`. Fails
+     *  with `APP_ALREADY_LINKED` (400) if the app already belongs to someone. */
+    linkAppToAccount(appId, signature, nonce) {
+        return __classPrivateFieldGet(this, _ReclaimOldClient_instances, "m", _ReclaimOldClient_request).call(this, 'POST', '/applications/link', {
+            body: { appId, signature, nonce },
+            auth: true,
+        });
+    }
+    /** Public, unauthenticated app status — `isLinked`, sandbox/quota info.
+     *  Works for any appId, owned or not. */
+    async getApplicationStatus(appId) {
+        const res = await __classPrivateFieldGet(this, _ReclaimOldClient_instances, "m", _ReclaimOldClient_request).call(this, 'GET', `/applications/status/${encodeURIComponent(appId)}`);
+        return res.data;
+    }
     getMyProviders(query = {}) {
         // Every one of these query params is REQUIRED by the backend
         // validator (missing/invalid → 400), so default them all here.

package/lib/old/tools/build.js

@@ -1,9 +1,15 @@
 import { authenticateTool } from "./authenticate.js";
+import { checkAppStatusTool } from "./check-app-status.js";
 import { getProviderInfoTool } from "./get-provider-info.js";
+import { issueAppCredentialsTool } from "./issue-app-credentials.js";
+import { getJsSdkIntegrationGuideTool } from "./js-sdk-integration-guide.js";
+import { linkAppTool } from "./link-app.js";
 import { getMeProvidersTool } from "./me-providers.js";
 import { createVersionFromCaptureTool } from "./publish.js";
+import { scaffoldDemoServerTool } from "./scaffold-demo-server.js";
 import { sessionAnalyticsLogsTool } from "./session-analytics-logs.js";
 import { updateProviderMetadataTool } from "./update-provider-metadata.js";
+import { verifySdkSetupTool } from "./verify-sdk-setup.js";
 /**
  * The backend-facing tools for OLD-devtools mode. Mirrors
  * `buildCredentialTools` / `buildAgentTools`: returns a flat `RegisteredTool`
@@ -22,5 +28,11 @@ export function buildOldBackendTools(client, sdkClient) {
         getProviderInfoTool(sdkClient),
         updateProviderMetadataTool(client),
         sessionAnalyticsLogsTool(client),
+        issueAppCredentialsTool(client),
+        linkAppTool(client),
+        checkAppStatusTool(client),
+        getJsSdkIntegrationGuideTool(),
+        scaffoldDemoServerTool(),
+        verifySdkSetupTool(client),
     ];
 }

package/lib/old/tools/check-app-status.d.ts

@@ -0,0 +1,8 @@
+import { type RegisteredTool } from '../../mcp/server.ts';
+import type { ReclaimOldClient } from '../client.ts';
+/**
+ * Public, unauthenticated app status lookup — works for any `appId`, owned
+ * or not, linked or sandboxed. Mirrors the backend's
+ * `GET /api/applications/status/:appId`.
+ */
+export declare function checkAppStatusTool(client: ReclaimOldClient): RegisteredTool;

package/lib/old/tools/check-app-status.js

@@ -0,0 +1,27 @@
+import { defineTool } from "../../mcp/server.js";
+/**
+ * Public, unauthenticated app status lookup — works for any `appId`, owned
+ * or not, linked or sandboxed. Mirrors the backend's
+ * `GET /api/applications/status/:appId`.
+ */
+export function checkAppStatusTool(client) {
+    return defineTool({
+        name: 'check_app_status',
+        description: 'Check a Reclaim app\'s link/sandbox status by appId — no ' +
+            'authentication required. Returns whether the app is linked to a ' +
+            'dashboard account (`isLinked`), and for linked apps, remaining ' +
+            'session quota. A 404 means the appId has never been used yet — ' +
+            'it is created lazily on the first ReclaimProofRequest.init() call ' +
+            'or via issue_app_credentials.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                appId: {
+                    type: 'string',
+                    description: 'The eth-address appId to check.',
+                },
+            },
+            required: ['appId'],
+        },
+    }, async ({ appId }) => client.getApplicationStatus(appId));
+}

package/lib/old/tools/issue-app-credentials.d.ts

@@ -0,0 +1,11 @@
+import { type RegisteredTool } from '../../mcp/server.ts';
+import type { ReclaimOldClient } from '../client.ts';
+/**
+ * Mint a brand-new eth-keypair APP (as opposed to authenticating as a
+ * dashboard user). `appId` is the eth address, `appSecret` the raw private
+ * key — this is the pair `@reclaimprotocol/js-sdk`'s `ReclaimProofRequest.init`
+ * expects. No auth required: the app starts unassociated (`creatorUid: null`)
+ * 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 declare function issueAppCredentialsTool(client: ReclaimOldClient): RegisteredTool;

package/lib/old/tools/issue-app-credentials.js

@@ -0,0 +1,35 @@
+import { defineTool } from "../../mcp/server.js";
+/**
+ * Mint a brand-new eth-keypair APP (as opposed to authenticating as a
+ * dashboard user). `appId` is the eth address, `appSecret` the raw private
+ * key — this is the pair `@reclaimprotocol/js-sdk`'s `ReclaimProofRequest.init`
+ * expects. No auth required: the app starts unassociated (`creatorUid: null`)
+ * 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) {
+    return defineTool({
+        name: 'issue_app_credentials',
+        description: 'Mint a new Reclaim APP (eth keypair) on the old devtools backend — ' +
+            'no authentication required. Returns `{ appId, appSecret }`: ' +
+            '`appId` is the eth address, `appSecret` the raw private key. This ' +
+            'is the appId/appSecret pair for @reclaimprotocol/js-sdk ' +
+            '(`ReclaimProofRequest.init(appId, appSecret, providerId)`). The app ' +
+            'starts UNLINKED and sandboxed (100 sessions) — call ' +
+            'link_app_to_account to attach it to your dashboard account and ' +
+            'check_app_status to check its state. Store `appSecret` like a ' +
+            'password (e.g. in a gitignored .env as RECLAIM_APP_SECRET) — it ' +
+            'is returned once and cannot be recovered from the server.',
+        inputSchema: { type: 'object', properties: {} },
+    }, async () => {
+        const { appId, appSecret } = await client.issueCredentials();
+        return {
+            appId,
+            appSecret,
+            note: 'Unlinked, sandboxed app (100 session limit). Set RECLAIM_APP_ID ' +
+                'and RECLAIM_APP_SECRET in your .env (gitignored). Run ' +
+                'link_app_to_account to attach it to your dashboard account and ' +
+                'lift the sandbox limit.',
+        };
+    });
+}

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

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

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

@@ -105,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: {
@@ -243,13 +250,26 @@ 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 });
+        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 });
         }
-        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 = {
             initialUrl: args.initialUrl,
             description: args.description,

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;