@reclaimprotocol/agent 0.1.33 → 0.1.35

package/lib/mcp/tools/authenticate/import.js

@@ -5,53 +5,40 @@ import { writeEthKey } from "./eth-key.js";
 export function importTool() {
     return defineTool({
         name: 'import_credentials',
-        description: 'Import an eth proof-owner key the dev already holds and persist it ' +
-            'to the project `.env` as RECLAIM_PRIVATE_KEY=0x… (mode 0600; `.env` ' +
-            'added to .gitignore). Provide EITHER `privateKey` (raw 0x-hex, 64 ' +
-            'chars) OR `keyFile` (path to a file holding the raw 0x-hex key). ' +
-            'The address is derived locally; the private key is never ' +
-            'returned. This is a local signing key only (not registered ' +
-            'with any server, ' +
-            'unrelated to org auth or encryption).',
+        description: 'Imports an eth proof-owner key from a file the developer already '
+            + 'holds. Reads the raw 0x-hex key from `keyFile` and writes it to '
+            + 'the project `.env` as RECLAIM_PRIVATE_KEY (mode 0600; `.env` '
+            + 'added to .gitignore). Returns the derived address and the `.env` '
+            + 'path; never the key. The key is a local signing key only: it is '
+            + 'not registered with any server and is unrelated to org auth or '
+            + 'encryption. To create a new key instead, use `issue_credentials`.',
         inputSchema: {
             type: 'object',
+            required: ['keyFile'],
             properties: {
-                privateKey: {
-                    type: 'string',
-                    pattern: '^0x?[0-9a-fA-F]{64}$',
-                    description: 'Raw Ethereum private key, 0x-prefixed hex (64 hex chars).',
-                },
                 keyFile: {
                     type: 'string',
-                    description: 'Path to a file containing the raw 0x-hex private key ' +
-                        '(absolute or project-relative).',
+                    description: 'Path to a file containing the raw 0x-hex private key '
+                        + '(absolute or relative to the working directory).',
                 },
                 projectDir: {
                     type: 'string',
-                    description: 'Project directory whose `.env` the key is written to. ' +
-                        'Defaults to the closest ancestor of cwd containing .git or ' +
-                        'package.json.',
+                    description: 'Project directory whose `.env` the key is written to. '
+                        + 'Defaults to the closest ancestor of cwd containing .git or '
+                        + 'package.json.',
                 },
             },
         },
+        annotations: { readOnlyHint: false, destructiveHint: false },
     }, async (args) => {
-        if (!args.privateKey && !args.keyFile) {
-            throw new Error('Provide either `privateKey` (0x-hex) or `keyFile`.');
-        }
-        if (args.privateKey && args.keyFile) {
-            throw new Error('Provide only one of `privateKey` or `keyFile`.');
-        }
         const projectDir = findProjectRoot(args.projectDir || process.cwd());
-        const privateKeyHex = args.keyFile
-            ? readFileSync(args.keyFile, 'utf8')
-            : args.privateKey;
-        const { path, address } = writeEthKey(privateKeyHex, projectDir);
+        const { path, address } = writeEthKey(readFileSync(args.keyFile, 'utf8'), projectDir);
         return {
             address,
             path,
-            note: 'Eth proof-owner key written to .env as RECLAIM_PRIVATE_KEY ' +
-                '(mode 0600). resolve_owner_key resolves it from .env. Keep .env ' +
-                'secret — it has been added to .gitignore.',
+            note: 'Eth proof-owner key written to .env as RECLAIM_PRIVATE_KEY '
+                + '(mode 0600). resolve_owner_key resolves it from .env. Keep .env '
+                + 'secret: it has been added to .gitignore.',
         };
     });
 }

package/lib/mcp/tools/authenticate/issue-org-token.d.ts

@@ -0,0 +1,8 @@
+import type { ReclaimClient } from '@reclaimprotocol/client/api';
+import { type RegisteredTool } from '../../server.ts';
+/**
+ * Issues an organization API key and stores it on disk, so the key never
+ * passes through the agent's transcript. Replaces the generated
+ * `issue_org_token` operation, which returned the key in its response.
+ */
+export declare function issueOrgTokenTool(client: ReclaimClient): RegisteredTool;

package/lib/mcp/tools/authenticate/issue-org-token.js

@@ -0,0 +1,60 @@
+import assert from 'node:assert';
+import { isAbsolute, relative, resolve } from 'node:path';
+import { defineTool } from "../../server.js";
+import { upsertEnvVar } from "./eth-key.js";
+import { saveOrgKey } from "./org-key-store.js";
+/**
+ * Issues an organization API key and stores it on disk, so the key never
+ * passes through the agent's transcript. Replaces the generated
+ * `issue_org_token` operation, which returned the key in its response.
+ */
+export function issueOrgTokenTool(client) {
+    return defineTool({
+        name: 'issue_org_token',
+        description: 'Issues an organization API key (owner only) and writes it to a '
+            + 'server env file in the project, so the app can read it at runtime. '
+            + 'Also saves it on this machine for the org-key tools. Returns the '
+            + 'org, file, variable, and last four characters; never the key. '
+            + 'Replaces an existing variable of the same name in the file. '
+            + 'Adds the file to .gitignore. Use when the app needs a key, or '
+            + 'before `create_verification_session`.',
+        inputSchema: {
+            type: 'object',
+            required: ['orgId', 'projectDir'],
+            properties: {
+                orgId: { type: 'string', format: 'uuid' },
+                projectDir: {
+                    type: 'string',
+                    description: 'Absolute path of the app\'s project directory.',
+                },
+                envFile: {
+                    type: 'string',
+                    description: 'Env file to write, relative to `projectDir`. Default `.env`.',
+                },
+                envVar: {
+                    type: 'string',
+                    pattern: '^[A-Za-z_][A-Za-z0-9_]*$',
+                    description: 'Variable name to set. Default `RECLAIM_ORG_SECRET`.',
+                },
+            },
+        },
+        annotations: { openWorldHint: true, destructiveHint: false },
+    }, async (args) => {
+        assert(isAbsolute(args.projectDir), new Error('`projectDir` must be an absolute path.'));
+        const envFile = args.envFile || '.env';
+        const envVar = args.envVar || 'RECLAIM_ORG_SECRET';
+        const inside = relative(args.projectDir, resolve(args.projectDir, envFile));
+        assert(inside && !inside.startsWith('..') && !isAbsolute(inside), new Error('`envFile` must be inside `projectDir`.'));
+        const { data } = await client.call('IssueOrgToken', {
+            params: { orgId: args.orgId },
+        });
+        const path = upsertEnvVar(args.projectDir, envFile, envVar, data.orgSecret);
+        saveOrgKey(args.orgId, data.orgSecret);
+        return {
+            orgId: args.orgId,
+            envFile: path,
+            envVar,
+            last4: data.last4,
+        };
+    });
+}

package/lib/mcp/tools/authenticate/issue.js

@@ -5,15 +5,14 @@ import { writeEthKey } from "./eth-key.js";
 export function issueTool() {
     return defineTool({
         name: 'issue_credentials',
-        description: 'Generate a fresh secp256k1 eth proof-owner key-pair (the key ' +
-            'that signs local claim creation) and write the raw private key to ' +
-            'the project `.env` as RECLAIM_PRIVATE_KEY=0x… (mode 0600; `.env` ' +
-            'added to .gitignore). This is a LOCAL signing key only — it is NOT ' +
-            'registered with any server and is unrelated to org auth (the org ' +
-            'secret) or encryption (the eth decrypt key). ALWAYS confirm with ' +
-            'the dev before generating a new key. After writing, run_proof picks ' +
-            'it up automatically via resolve_owner_key. The private key is never ' +
-            'returned in the response.',
+        description: 'Generates a new secp256k1 eth proof-owner key and writes the '
+            + 'private key to the project `.env` as RECLAIM_PRIVATE_KEY (mode '
+            + '0600; `.env` added to .gitignore). Returns the address and the '
+            + '`.env` path; never the key. The key is a local signing key only: '
+            + 'it is not registered with any server and is unrelated to org auth '
+            + 'or encryption. Confirm with the developer before replacing an '
+            + 'existing key. `run_proof` then picks it up through '
+            + '`resolve_owner_key`.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -25,6 +24,7 @@ export function issueTool() {
                 },
             },
         },
+        annotations: { destructiveHint: false },
     }, async (args) => {
         const projectDir = findProjectRoot(args.projectDir || process.cwd());
         const keypair = generateKeypair();

package/lib/mcp/tools/authenticate/org-key-store.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Save an organization API key (`rorg_…`) in the local config (mode 0600), so
+ * the org-key tools can use it without the key passing through a transcript.
+ */
+export declare function saveOrgKey(orgId: string, secret: string): void;
+/**
+ * The saved key for `orgId`, or the most recently saved key when no org is
+ * given. Returns `undefined` when none is saved.
+ */
+export declare function savedOrgKey(orgId?: string): string | undefined;

package/lib/mcp/tools/authenticate/org-key-store.js

@@ -0,0 +1,23 @@
+import { ConfigStore } from "../../../config/store.js";
+/**
+ * Save an organization API key (`rorg_…`) in the local config (mode 0600), so
+ * the org-key tools can use it without the key passing through a transcript.
+ */
+export function saveOrgKey(orgId, secret) {
+    const saved = new ConfigStore().read()?.org_keys;
+    new ConfigStore().write({
+        org_keys: {
+            byOrg: { ...saved?.byOrg, [orgId]: secret },
+            recent: orgId,
+        },
+    });
+}
+/**
+ * The saved key for `orgId`, or the most recently saved key when no org is
+ * given. Returns `undefined` when none is saved.
+ */
+export function savedOrgKey(orgId) {
+    const saved = new ConfigStore().read()?.org_keys;
+    const id = orgId || saved?.recent;
+    return id ? saved?.byOrg[id] : undefined;
+}

package/lib/mcp/tools/authenticate/resolve-owner-key.js

@@ -16,18 +16,16 @@ import { ENV_FILE, resolveEthKey } from "./eth-key.js";
 export function resolveOwnerKeyTool() {
     return defineTool({
         name: 'resolve_owner_key',
-        description: 'Resolve which eth proof-owner key run_proof should sign with — ' +
-            'call this BEFORE run_proof. Checks, in order: RECLAIM_PRIVATE_KEY ' +
-            'in the MCP env, a RECLAIM_PRIVATE_KEY=0x… line in the project .env, ' +
-            'then a file at RECLAIM_PRIVATE_KEY_FILE holding the raw hex. ' +
-            'Returns { ready: true, address, source } when one is ' +
-            'available — pass `address` to run_proof as `ownerAddress`. ' +
-            'Returns { ready: false } ' +
-            'when none exists: then ask the dev to generate one ' +
-            '(issue_credentials) or import one they already hold ' +
-            '(import_credentials, accepts 0x-hex or a key-file path), and call ' +
-            'resolve_owner_key again. Never exposes the private key.',
+        description: 'Finds the eth proof-owner key `run_proof` signs with. Call it '
+            + 'before `run_proof`. Checks RECLAIM_PRIVATE_KEY in the MCP env, a '
+            + 'RECLAIM_PRIVATE_KEY line in the project .env, then the file at '
+            + 'RECLAIM_PRIVATE_KEY_FILE. Returns { ready: true, address, source '
+            + '}: pass `address` to `run_proof` as `ownerAddress`. Returns { '
+            + 'ready: false } when none exists: ask the developer to create one '
+            + 'with `issue_credentials` or import one with `import_credentials` '
+            + '(a key file), then call it again. Never returns the key.',
         inputSchema: { type: 'object', properties: {} },
+        annotations: { readOnlyHint: true, openWorldHint: false },
     }, async () => {
         const projectDir = findProjectRoot(process.cwd());
         const resolved = resolveEthKey(projectDir);
@@ -45,7 +43,7 @@ export function resolveOwnerKeyTool() {
                 `env, no RECLAIM_PRIVATE_KEY in ${join(projectDir, ENV_FILE)}, and ` +
                 'no RECLAIM_PRIVATE_KEY_FILE. Ask the dev to generate one via ' +
                 'issue_credentials, or import one they already hold via ' +
-                'import_credentials (0x-hex or a key-file path). Then call ' +
+                'import_credentials (a key file). Then call ' +
                 'resolve_owner_key again and pass its address to run_proof as ' +
                 'ownerAddress.',
         };

package/lib/mcp/tools/mode/mode.js

@@ -44,6 +44,7 @@ export function buildModeTools(config, currentOldMode) {
                 },
                 required: ['mode'],
             },
+            annotations: { openWorldHint: false, idempotentHint: true },
         }, async (parsed) => {
             config.write({ mode: parsed.mode });
             const restartRequired = parsed.mode !== current;
@@ -71,6 +72,7 @@ export function buildModeTools(config, currentOldMode) {
                 + 'the staleness with an error naming the tool to re-run. Which '
                 + 'login authorizes what: how_it_works({ topic: "auth" }).',
             inputSchema: { type: 'object', properties: {} },
+            annotations: { readOnlyHint: true, openWorldHint: false },
         }, async () => {
             const persisted = config.read()?.mode;
             const oldIdentity = config.read()?.old_devtools;

package/lib/mcp/tools/verification/build.d.ts

@@ -4,7 +4,9 @@ import type { RegisteredTool } from '../../server.ts';
  * generated API surface. `get_verification_result` authenticates with the org
  * token, checks status, pulls the stored payload, and decrypts it locally with
  * the optional eth key — a flow the generated raw-API tools can't express
- * (the decryption key never leaves the consumer). Diagnosis is left to the
+ * (the decryption key never leaves the consumer). `read_callback_events` and
+ * `proxy_callback_events` read and forward the org's pull-listener events.
+ * Diagnosis is left to the
  * agent over the generated tools (`get_verification_session`,
  * `list_verification_events`, `list_verification_deliveries`), whose
  * descriptions carry the lifecycle and delivery semantics.

package/lib/mcp/tools/verification/build.js

@@ -1,14 +1,22 @@
+import { proxyCallbackEventsTool } from "./proxy-callback-events.js";
+import { readCallbackEventsTool } from "./read-callback-events.js";
 import { verificationResultTool } from "./result.js";
 /**
  * Builder-mode verification tools: higher-level orchestrations over the
  * generated API surface. `get_verification_result` authenticates with the org
  * token, checks status, pulls the stored payload, and decrypts it locally with
  * the optional eth key — a flow the generated raw-API tools can't express
- * (the decryption key never leaves the consumer). Diagnosis is left to the
+ * (the decryption key never leaves the consumer). `read_callback_events` and
+ * `proxy_callback_events` read and forward the org's pull-listener events.
+ * Diagnosis is left to the
  * agent over the generated tools (`get_verification_session`,
  * `list_verification_events`, `list_verification_deliveries`), whose
  * descriptions carry the lifecycle and delivery semantics.
  */
 export function buildVerificationTools() {
-    return [verificationResultTool()];
+    return [
+        verificationResultTool(),
+        readCallbackEventsTool(),
+        proxyCallbackEventsTool(),
+    ];
 }

package/lib/mcp/tools/verification/callback-listener.d.ts

@@ -0,0 +1,51 @@
+import { ReclaimClient } from '@reclaimprotocol/client/api';
+import type { IOperationResponse } from '@reclaimprotocol/client/openapi';
+/** Runtime seams. Production passes none; tests pass a stub `fetch`. */
+export interface CallbackDeps {
+    fetch?: typeof globalThis.fetch;
+    /** Waits between heartbeats and polls. Resolves, without error, on abort. */
+    sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
+    keeper?: ListenerKeeper;
+}
+/**
+ * Events the org's pull listener subscribes to: the five session-ending
+ * events (the first four carry the signed result; `session_expired` has no
+ * result) plus the lifecycle milestones an app developer checks while testing.
+ * High-volume diagnostics (`network_request_observed`, `provider_script_log`,
+ * `user_interaction_*`) are left out, so a forwarded session sends the app at
+ * most 11 requests instead of dozens.
+ */
+export declare const LISTENER_EVENTS: readonly ["verification_success", "verification_rejected", "verification_error", "verification_cancelled", "session_expired", "session_pending", "verification_client_opened", "authenticated", "verification_proofs_completed", "verification_result_submitting", "verification_result_submission_failed"];
+export type ListenerInfo = {
+    subscriptionId: string;
+    created: boolean;
+    /** When the lease lapses unless the heartbeat renews it. */
+    expiresAt: string;
+};
+export type CallbackEvent = IOperationResponse<'ListCallbackEvents'>['items'][number];
+/**
+ * A client that presents the organization's API key. With a `signal`, every
+ * request aborts when it does.
+ */
+export declare function orgClient(secret: string, deps?: CallbackDeps, signal?: AbortSignal): ReclaimClient;
+/**
+ * Keeps each org's pull listener alive while this MCP process runs. Creating
+ * the subscription is the heartbeat: it renews a lease, and the listener
+ * stops receiving events when the lease lapses. {@link release} ends the
+ * lease at shutdown.
+ */
+export declare class ListenerKeeper {
+    #private;
+    /** Creates or renews the listener and starts its heartbeat (once). */
+    ensure(secret: string, deps?: CallbackDeps): Promise<ListenerInfo>;
+    /** Ends every lease and stops the heartbeats, within a short timeout. */
+    release(): Promise<void>;
+}
+/** Releases every listener this process keeps alive. Runs at MCP shutdown. */
+export declare function releaseAllListeners(): Promise<void>;
+/**
+ * Create the org's pull listener and keep it alive until shutdown. An org has
+ * one, so a second call returns the existing subscription (HTTP 200).
+ */
+export declare function ensureListener(secret: string, deps?: CallbackDeps): Promise<ListenerInfo>;
+export declare function sleepFor(ms: number, signal: AbortSignal): Promise<void>;

package/lib/mcp/tools/verification/callback-listener.js

@@ -0,0 +1,163 @@
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _ListenerKeeper_instances, _ListenerKeeper_entries, _ListenerKeeper_beat;
+import { badGateway } from '@hapi/boom';
+import { ReclaimClient } from '@reclaimprotocol/client/api';
+import assert from 'node:assert';
+import { setTimeout as delay } from 'node:timers/promises';
+import { apiUrl } from "../../../consts.js";
+import { LOGGER } from "../../../logger.js";
+import { NAME, VERSION } from "../../../pkg.js";
+/**
+ * Events the org's pull listener subscribes to: the five session-ending
+ * events (the first four carry the signed result; `session_expired` has no
+ * result) plus the lifecycle milestones an app developer checks while testing.
+ * High-volume diagnostics (`network_request_observed`, `provider_script_log`,
+ * `user_interaction_*`) are left out, so a forwarded session sends the app at
+ * most 11 requests instead of dozens.
+ */
+export const LISTENER_EVENTS = [
+    'verification_success',
+    'verification_rejected',
+    'verification_error',
+    'verification_cancelled',
+    'session_expired',
+    'session_pending',
+    'verification_client_opened',
+    'authenticated',
+    'verification_proofs_completed',
+    'verification_result_submitting',
+    'verification_result_submission_failed',
+];
+/**
+ * A client that presents the organization's API key. With a `signal`, every
+ * request aborts when it does.
+ */
+export function orgClient(secret, deps = {}, signal) {
+    const base = deps.fetch || globalThis.fetch;
+    return new ReclaimClient({
+        baseUrl: apiUrl(),
+        token: secret,
+        fetch: signal
+            ? (input, init) => base(input, { ...init, signal })
+            : deps.fetch,
+        headers: { 'User-Agent': `${NAME}/${VERSION}` },
+    });
+}
+/** Renewal interval. The backend lease lasts 90 seconds. */
+const HEARTBEAT_MS = 30000;
+/** Upper bound for releasing all listeners at shutdown. */
+const RELEASE_TIMEOUT_MS = 3000;
+/**
+ * Keeps each org's pull listener alive while this MCP process runs. Creating
+ * the subscription is the heartbeat: it renews a lease, and the listener
+ * stops receiving events when the lease lapses. {@link release} ends the
+ * lease at shutdown.
+ */
+export class ListenerKeeper {
+    constructor() {
+        _ListenerKeeper_instances.add(this);
+        _ListenerKeeper_entries.set(this, new Map()
+        /** Creates or renews the listener and starts its heartbeat (once). */
+        );
+    }
+    /** Creates or renews the listener and starts its heartbeat (once). */
+    async ensure(secret, deps = {}) {
+        const existing = __classPrivateFieldGet(this, _ListenerKeeper_entries, "f").get(secret);
+        if (existing) {
+            const wasSettled = existing.settled;
+            const first = await existing.ready;
+            // Callers that arrived during creation share its result.
+            return wasSettled ? await renew(existing.client) : first;
+        }
+        const abort = new AbortController();
+        const client = orgClient(secret, deps, abort.signal);
+        const sleep = deps.sleep || sleepFor;
+        const entry = {
+            client,
+            releaseClient: orgClient(secret, deps),
+            abort,
+            settled: false,
+            ready: renew(client).then((info) => {
+                entry.settled = true;
+                void __classPrivateFieldGet(this, _ListenerKeeper_instances, "m", _ListenerKeeper_beat).call(this, entry, sleep);
+                return info;
+            }, (err) => {
+                if (__classPrivateFieldGet(this, _ListenerKeeper_entries, "f").get(secret) === entry) {
+                    __classPrivateFieldGet(this, _ListenerKeeper_entries, "f").delete(secret);
+                }
+                abort.abort();
+                throw err;
+            }),
+        };
+        __classPrivateFieldGet(this, _ListenerKeeper_entries, "f").set(secret, entry);
+        return await entry.ready;
+    }
+    /** Ends every lease and stops the heartbeats, within a short timeout. */
+    async release() {
+        const entries = [...__classPrivateFieldGet(this, _ListenerKeeper_entries, "f").values()];
+        __classPrivateFieldGet(this, _ListenerKeeper_entries, "f").clear();
+        const timeout = AbortSignal.timeout(RELEASE_TIMEOUT_MS);
+        await Promise.all(entries.map(async ({ releaseClient, abort }) => {
+            abort.abort();
+            try {
+                await Promise.race([
+                    releaseClient.call('ReleaseCallbackListener', {}),
+                    new Promise((_, reject) => {
+                        timeout.addEventListener('abort', () => reject(timeout.reason));
+                    }),
+                ]);
+            }
+            catch (err) {
+                LOGGER.warn({ err }, 'releasing the callback listener failed');
+            }
+        }));
+    }
+}
+_ListenerKeeper_entries = new WeakMap(), _ListenerKeeper_instances = new WeakSet(), _ListenerKeeper_beat = async function _ListenerKeeper_beat(entry, sleep) {
+    const { signal } = entry.abort;
+    while (!signal.aborted) {
+        await sleep(HEARTBEAT_MS, signal);
+        if (signal.aborted) {
+            return;
+        }
+        try {
+            await renew(entry.client);
+        }
+        catch (err) {
+            if (signal.aborted) {
+                return;
+            }
+            LOGGER.warn({ err }, 'callback listener heartbeat failed; retrying');
+        }
+    }
+};
+const defaultKeeper = new ListenerKeeper();
+/** Releases every listener this process keeps alive. Runs at MCP shutdown. */
+export function releaseAllListeners() {
+    return defaultKeeper.release();
+}
+/**
+ * Create the org's pull listener and keep it alive until shutdown. An org has
+ * one, so a second call returns the existing subscription (HTTP 200).
+ */
+export function ensureListener(secret, deps = {}) {
+    return (deps.keeper || defaultKeeper).ensure(secret, deps);
+}
+async function renew(client) {
+    const { data, response } = await client.call('CreateCallbackSubscription', {
+        body: { deliveryMode: 'pull', events: [...LISTENER_EVENTS] },
+    });
+    assert(data.listenerExpiresAt, badGateway('Builder returned a pull listener without a lease.'));
+    return {
+        subscriptionId: data.id,
+        created: response.status === 201,
+        expiresAt: data.listenerExpiresAt,
+    };
+}
+export async function sleepFor(ms, signal) {
+    await delay(ms, undefined, { signal }).catch(() => undefined);
+}

package/lib/mcp/tools/verification/index.d.ts

@@ -1 +1,3 @@
 export { buildVerificationTools } from './build.ts';
+export { stopAllForwarders } from './proxy-callback-events.ts';
+export { releaseAllListeners } from './callback-listener.ts';

package/lib/mcp/tools/verification/index.js

@@ -1,2 +1,4 @@
 // Barrel for the verification tool group (result retrieval + decryption).
 export { buildVerificationTools } from "./build.js";
+export { stopAllForwarders } from "./proxy-callback-events.js";
+export { releaseAllListeners } from "./callback-listener.js";

package/lib/mcp/tools/verification/proxy-callback-events.d.ts

@@ -0,0 +1,59 @@
+import type { ReclaimClient } from '@reclaimprotocol/client/api';
+import { type RegisteredTool } from '../../server.ts';
+import { type CallbackDeps, type ListenerInfo } from './callback-listener.ts';
+interface Target {
+    port: number;
+    path: string;
+}
+type Recent = {
+    id: string;
+    sessionId: string;
+    event: string;
+    status: 'delivered' | 'failed';
+    httpStatus?: number;
+    at: string;
+};
+export interface ProxyDeps extends CallbackDeps {
+    /** Delivers an event to the app. Defaults to global `fetch`. */
+    forwardFetch?: typeof globalThis.fetch;
+    /** Waits between polls. Resolves early, without error, on abort. */
+    sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
+    registry?: ForwarderRegistry;
+}
+/**
+ * Polls the org's pending pull events and POSTs each envelope to a local
+ * route, like `stripe listen --forward-to`. 2xx responses are acknowledged;
+ * anything else (redirects included) stays pending and is retried with
+ * exponential backoff. After a failure the batch stops, so events reach the
+ * app in order.
+ */
+declare class Forwarder {
+    #private;
+    target: Target;
+    listener: ListenerInfo;
+    constructor(client: ReclaimClient, listener: ListenerInfo, target: Target, deps: ProxyDeps);
+    status(): {
+        recent: Recent[];
+        lastError?: string | undefined;
+        forwarding: boolean;
+        target: string;
+        listener: ListenerInfo;
+        forwarded: number;
+        failed: number;
+    };
+    stop(): Promise<void>;
+}
+/** The forwarders of one MCP process, one per org key. */
+export declare class ForwarderRegistry {
+    #private;
+    get(secret: string): Forwarder | undefined;
+    set(secret: string, forwarder: Forwarder): void;
+    stop(secret: string): Promise<Forwarder | undefined>;
+    stopAll(): Promise<void>;
+}
+/** Stops every forwarder. Called when the MCP server shuts down. */
+export declare function stopAllForwarders(): Promise<void>;
+export declare function proxyCallbackEventsTool(deps?: ProxyDeps): RegisteredTool;
+/** Rejects anything that is not a path on a loopback port. */
+export declare function validateTarget(port: number, path: string): Target;
+export {};