@reclaimprotocol/agent 0.1.34 → 0.1.35

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 {};

package/lib/mcp/tools/verification/proxy-callback-events.js

@@ -0,0 +1,300 @@
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+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 _Forwarder_instances, _Forwarder_client, _Forwarder_deps, _Forwarder_abort, _Forwarder_forwarded, _Forwarder_failed, _Forwarder_lastError, _Forwarder_recent, _Forwarder_unacked, _Forwarder_host, _Forwarder_running, _Forwarder_loop, _Forwarder_tick, _Forwarder_forward, _ForwarderRegistry_forwarders;
+import { badRequest } from '@hapi/boom';
+import assert from 'node:assert';
+import { setTimeout as delay } from 'node:timers/promises';
+import { LOGGER } from "../../../logger.js";
+import { defineTool } from "../../server.js";
+import { ensureListener, orgClient, } from "./callback-listener.js";
+import { resolveOrgSecret } from "./result.js";
+const POLL_MS = 2000;
+const MAX_BACKOFF_MS = 30000;
+const FORWARD_TIMEOUT_MS = 10000;
+const BATCH = 50;
+const RECENT = 10;
+/** Loopback addresses, in the order tried. Dev servers often bind only one. */
+const HOSTS = ['127.0.0.1', '[::1]'];
+/**
+ * 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.
+ */
+class Forwarder {
+    constructor(client, listener, target, deps) {
+        _Forwarder_instances.add(this);
+        _Forwarder_client.set(this, void 0);
+        _Forwarder_deps.set(this, void 0);
+        _Forwarder_abort.set(this, new AbortController());
+        _Forwarder_forwarded.set(this, 0);
+        _Forwarder_failed.set(this, 0);
+        _Forwarder_lastError.set(this, void 0);
+        _Forwarder_recent.set(this, []
+        /** Delivered to the app but not yet acknowledged; never POSTed twice. */
+        );
+        /** Delivered to the app but not yet acknowledged; never POSTed twice. */
+        _Forwarder_unacked.set(this, new Set());
+        _Forwarder_host.set(this, HOSTS[0]);
+        _Forwarder_running.set(this, void 0);
+        __classPrivateFieldSet(this, _Forwarder_client, client, "f");
+        this.listener = listener;
+        this.target = target;
+        __classPrivateFieldSet(this, _Forwarder_deps, deps, "f");
+        __classPrivateFieldSet(this, _Forwarder_running, __classPrivateFieldGet(this, _Forwarder_instances, "m", _Forwarder_loop).call(this), "f");
+    }
+    status() {
+        return {
+            forwarding: !__classPrivateFieldGet(this, _Forwarder_abort, "f").signal.aborted,
+            target: targetUrl(this.target, HOSTS[0]),
+            listener: this.listener,
+            forwarded: __classPrivateFieldGet(this, _Forwarder_forwarded, "f"),
+            failed: __classPrivateFieldGet(this, _Forwarder_failed, "f"),
+            ...(__classPrivateFieldGet(this, _Forwarder_lastError, "f") ? { lastError: __classPrivateFieldGet(this, _Forwarder_lastError, "f") } : {}),
+            recent: [...__classPrivateFieldGet(this, _Forwarder_recent, "f")],
+        };
+    }
+    async stop() {
+        __classPrivateFieldGet(this, _Forwarder_abort, "f").abort();
+        await __classPrivateFieldGet(this, _Forwarder_running, "f");
+    }
+}
+_Forwarder_client = new WeakMap(), _Forwarder_deps = new WeakMap(), _Forwarder_abort = new WeakMap(), _Forwarder_forwarded = new WeakMap(), _Forwarder_failed = new WeakMap(), _Forwarder_lastError = new WeakMap(), _Forwarder_recent = new WeakMap(), _Forwarder_unacked = new WeakMap(), _Forwarder_host = new WeakMap(), _Forwarder_running = new WeakMap(), _Forwarder_instances = new WeakSet(), _Forwarder_loop = async function _Forwarder_loop() {
+    const sleep = __classPrivateFieldGet(this, _Forwarder_deps, "f").sleep || sleepFor;
+    const signal = __classPrivateFieldGet(this, _Forwarder_abort, "f").signal;
+    let backoff = 0;
+    while (!signal.aborted) {
+        let wait = POLL_MS;
+        try {
+            const { ok, count } = await __classPrivateFieldGet(this, _Forwarder_instances, "m", _Forwarder_tick).call(this);
+            backoff = ok ? 0 : nextBackoff(backoff);
+            wait = ok ? (count >= BATCH ? 0 : POLL_MS) : backoff;
+        }
+        catch (err) {
+            __classPrivateFieldSet(this, _Forwarder_lastError, err instanceof Error ? err.message : String(err), "f");
+            LOGGER.warn({ err }, 'callback proxy poll failed');
+            backoff = nextBackoff(backoff);
+            wait = backoff;
+        }
+        if (wait && !signal.aborted) {
+            await sleep(wait, signal);
+        }
+    }
+}, _Forwarder_tick = async function _Forwarder_tick() {
+    const { data } = await __classPrivateFieldGet(this, _Forwarder_client, "f").call('ListCallbackEvents', {
+        query: { pending: true, limit: BATCH },
+    });
+    const ack = [];
+    let ok = true;
+    for (const item of data.items) {
+        if (__classPrivateFieldGet(this, _Forwarder_abort, "f").signal.aborted) {
+            break;
+        }
+        if (__classPrivateFieldGet(this, _Forwarder_unacked, "f").has(item.id) || await __classPrivateFieldGet(this, _Forwarder_instances, "m", _Forwarder_forward).call(this, item)) {
+            ack.push(item.id);
+        }
+        else {
+            // Stop the batch so later events don't overtake the failed one.
+            ok = false;
+            break;
+        }
+    }
+    if (ack.length) {
+        for (const id of ack) {
+            __classPrivateFieldGet(this, _Forwarder_unacked, "f").add(id);
+        }
+        await __classPrivateFieldGet(this, _Forwarder_client, "f").call('AcknowledgeCallbackEvents', {
+            body: { ids: ack },
+        });
+        for (const id of ack) {
+            __classPrivateFieldGet(this, _Forwarder_unacked, "f").delete(id);
+        }
+    }
+    return { ok, count: data.items.length };
+}, _Forwarder_forward = async function _Forwarder_forward(item) {
+    const doFetch = __classPrivateFieldGet(this, _Forwarder_deps, "f").forwardFetch || globalThis.fetch;
+    const record = (status, httpStatus) => {
+        __classPrivateFieldGet(this, _Forwarder_recent, "f").push({
+            id: item.id,
+            sessionId: item.sessionId,
+            event: item.event,
+            status,
+            ...(httpStatus === undefined ? {} : { httpStatus }),
+            at: new Date().toISOString(),
+        });
+        __classPrivateFieldGet(this, _Forwarder_recent, "f").splice(0, __classPrivateFieldGet(this, _Forwarder_recent, "f").length - RECENT);
+    };
+    const hosts = [__classPrivateFieldGet(this, _Forwarder_host, "f"), ...HOSTS.filter((h) => h !== __classPrivateFieldGet(this, _Forwarder_host, "f"))];
+    for (const host of hosts) {
+        try {
+            const res = await doFetch(targetUrl(this.target, host), {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(item.envelope),
+                signal: AbortSignal.timeout(FORWARD_TIMEOUT_MS),
+                // Never follow a redirect: it could re-POST the signed result
+                // to a host outside this machine.
+                redirect: 'manual',
+            });
+            __classPrivateFieldSet(this, _Forwarder_host, host, "f");
+            if (res.ok) {
+                __classPrivateFieldSet(this, _Forwarder_forwarded, __classPrivateFieldGet(this, _Forwarder_forwarded, "f") + 1, "f");
+                record('delivered', res.status);
+                return true;
+            }
+            __classPrivateFieldSet(this, _Forwarder_failed, __classPrivateFieldGet(this, _Forwarder_failed, "f") + 1, "f");
+            const url = targetUrl(this.target, host);
+            __classPrivateFieldSet(this, _Forwarder_lastError, res.status >= 300 && res.status < 400
+                ? `${url} redirected (HTTP ${res.status}). Redirects are not `
+                    + 'followed; call again with the redirect target\'s `path`.'
+                : `${url} returned HTTP ${res.status}`, "f");
+            record('failed', res.status);
+            return false;
+        }
+        catch (err) {
+            __classPrivateFieldSet(this, _Forwarder_lastError, err instanceof Error ? err.message : String(err), "f");
+        }
+    }
+    // No loopback address accepted the connection.
+    __classPrivateFieldSet(this, _Forwarder_failed, __classPrivateFieldGet(this, _Forwarder_failed, "f") + 1, "f");
+    record('failed');
+    return false;
+};
+/** The forwarders of one MCP process, one per org key. */
+export class ForwarderRegistry {
+    constructor() {
+        _ForwarderRegistry_forwarders.set(this, new Map());
+    }
+    get(secret) {
+        return __classPrivateFieldGet(this, _ForwarderRegistry_forwarders, "f").get(secret);
+    }
+    set(secret, forwarder) {
+        __classPrivateFieldGet(this, _ForwarderRegistry_forwarders, "f").set(secret, forwarder);
+    }
+    async stop(secret) {
+        const forwarder = __classPrivateFieldGet(this, _ForwarderRegistry_forwarders, "f").get(secret);
+        __classPrivateFieldGet(this, _ForwarderRegistry_forwarders, "f").delete(secret);
+        await forwarder?.stop();
+        return forwarder;
+    }
+    async stopAll() {
+        const all = [...__classPrivateFieldGet(this, _ForwarderRegistry_forwarders, "f").values()];
+        __classPrivateFieldGet(this, _ForwarderRegistry_forwarders, "f").clear();
+        await Promise.all(all.map((f) => f.stop()));
+    }
+}
+_ForwarderRegistry_forwarders = new WeakMap();
+const defaultRegistry = new ForwarderRegistry();
+/** Stops every forwarder. Called when the MCP server shuts down. */
+export function stopAllForwarders() {
+    return defaultRegistry.stopAll();
+}
+export function proxyCallbackEventsTool(deps = {}) {
+    const registry = deps.registry || defaultRegistry;
+    return defineTool({
+        name: 'proxy_callback_events',
+        description: 'Forwards the events Reclaim sends to the org\'s pull listener '
+            + 'to a local route, like `stripe listen --forward-to`. Call it '
+            + 'when the app\'s callback route runs locally. It POSTs each '
+            + 'envelope as JSON to `http://127.0.0.1:<port><path>` (loopback '
+            + 'only; also tries `[::1]`) in order, acknowledges 2xx '
+            + 'responses, and retries anything else, redirects included, '
+            + 'with backoff. Creates the listener on first use, so it is not '
+            + 'read-only. One forwarder runs per org: call again to read '
+            + 'status, or with another `port` or `path` to retarget. '
+            + '`stop: true` stops forwarding only. Forwarding lasts only '
+            + 'while this MCP server runs; production needs '
+            + '`create_org_callback_subscription`. Returns `{ forwarding, '
+            + 'target, listener, forwarded, failed, lastError?, recent }`; '
+            + '`listener.expiresAt` is the lease end, and `recent` lists the '
+            + 'last events with `status` and `httpStatus`.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                port: {
+                    type: 'integer',
+                    minimum: 1,
+                    maximum: 65535,
+                    description: 'The local port the app listens on.',
+                },
+                path: {
+                    type: 'string',
+                    pattern: '^/[^\\s#\\\\]*$',
+                    maxLength: 500,
+                    description: 'The callback route, starting with `/`. Defaults to `/`.',
+                },
+                stop: {
+                    type: 'boolean',
+                    description: 'Stop forwarding. `port` is not needed.',
+                },
+                orgToken: {
+                    type: 'string',
+                    pattern: '^rorg_',
+                    maxLength: 200,
+                    description: 'The organization API key (`rorg_…`). Defaults to '
+                        + 'the server\'s `RECLAIM_ORG_SECRET`, then the key saved by '
+                        + '`issue_org_token`. Never echo it back to the user.',
+                },
+            },
+        },
+        annotations: {
+            readOnlyHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async (args) => {
+        const secret = resolveOrgSecret(args.orgToken);
+        if (args.stop) {
+            const stopped = await registry.stop(secret);
+            return {
+                ...(stopped?.status() || { forwarding: false }),
+                _notes: 'Forwarding stopped. The listener stays alive until the '
+                    + 'MCP server exits, so `read_callback_events` still works.',
+            };
+        }
+        const existing = registry.get(secret);
+        if (args.port === undefined) {
+            assert(existing, badRequest('Pass `port`, the local port the app listens on.'));
+            existing.listener = await ensureListener(secret, deps);
+            return existing.status();
+        }
+        const target = validateTarget(args.port, args.path ?? '/');
+        if (existing) {
+            existing.target = target;
+            existing.listener = await ensureListener(secret, deps);
+            return existing.status();
+        }
+        const client = orgClient(secret, deps);
+        const listener = await ensureListener(secret, deps);
+        const forwarder = new Forwarder(client, listener, target, deps);
+        registry.set(secret, forwarder);
+        return forwarder.status();
+    });
+}
+/** Rejects anything that is not a path on a loopback port. */
+export function validateTarget(port, path) {
+    assert(Number.isInteger(port) && port >= 1 && port <= 65535, badRequest('`port` must be an integer from 1 to 65535.'));
+    assert(path.length <= 500 && /^\/[^\s#\\]*$/.test(path), badRequest('`path` must start with "/" and contain no host, space, or "#".'));
+    const url = new URL(targetUrl({ port, path }, HOSTS[0]));
+    assert(url.hostname === HOSTS[0] && url.port === String(port), badRequest('`path` must not change the target host.'));
+    return { port, path };
+}
+function targetUrl(target, host) {
+    return `http://${host}:${target.port}${target.path}`;
+}
+async function sleepFor(ms, signal) {
+    await delay(ms, undefined, { signal }).catch(() => undefined);
+}
+function nextBackoff(current) {
+    return Math.min(current ? current * 2 : POLL_MS, MAX_BACKOFF_MS);
+}

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

@@ -0,0 +1,3 @@
+import { type RegisteredTool } from '../../server.ts';
+import { type CallbackDeps } from './callback-listener.ts';
+export declare function readCallbackEventsTool(deps?: CallbackDeps): RegisteredTool;

package/lib/mcp/tools/verification/read-callback-events.js

@@ -0,0 +1,135 @@
+import { decryptCallback, ReclaimVerification } from '@reclaimprotocol/client';
+import { apiUrl } from "../../../consts.js";
+import { defineTool } from "../../server.js";
+import { resolveDecryptionKey } from "../authenticate/decrypt-key.js";
+import { ensureListener, orgClient, } from "./callback-listener.js";
+import { resolveOrgSecret } from "./result.js";
+/** Events whose `data` is the signed result (encrypted or plaintext JWS). */
+const RESULT_EVENTS = new Set([
+    'verification_success',
+    'verification_rejected',
+    'verification_error',
+    'verification_cancelled',
+]);
+export function readCallbackEventsTool(deps = {}) {
+    return defineTool({
+        name: 'read_callback_events',
+        description: 'Reads the events Reclaim sent to the organization\'s pull '
+            + 'listener, and decodes them: each result event is decrypted and '
+            + 'signature-verified into `result`, and each lifecycle event '
+            + 'returns its `eventData`. Call it to try a provider without an '
+            + 'app or to check what Reclaim sent for a session. Creates the '
+            + 'listener on first use, so it is not read-only. Filter with '
+            + '`sessionId`, or pass the previous `next` as `after` to read on. '
+            + 'Items with a lower sequence can appear late, so for a complete '
+            + 'read use `pending: true`. Returns `{ listener, items, next }`. '
+            + 'Encrypted results need the `RECLAIM_DECRYPT_KEY` that matches '
+            + 'the org keypair. To deliver events to your app\'s callback '
+            + 'route, call `proxy_callback_events`.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                sessionId: {
+                    type: 'string',
+                    format: 'uuid',
+                    description: 'Only events of this verification session.',
+                },
+                after: {
+                    type: 'string',
+                    pattern: '^[0-9]{1,19}$',
+                    description: 'The `next` value of a previous call.',
+                },
+                limit: {
+                    type: 'integer',
+                    minimum: 1,
+                    maximum: 100,
+                    description: 'Events to return. Defaults to 50.',
+                },
+                pending: {
+                    type: 'boolean',
+                    description: 'Only events not yet acknowledged. `proxy_callback_events` '
+                        + 'acknowledges the events it delivers.',
+                },
+                orgToken: {
+                    type: 'string',
+                    pattern: '^rorg_',
+                    maxLength: 200,
+                    description: 'The organization API key (`rorg_…`). Defaults to '
+                        + 'the server\'s `RECLAIM_ORG_SECRET`, then the key saved by '
+                        + '`issue_org_token`. Never echo it back to the user.',
+                },
+            },
+        },
+        annotations: {
+            readOnlyHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async (args) => {
+        const secret = resolveOrgSecret(args.orgToken);
+        const client = orgClient(secret, deps);
+        const listener = await ensureListener(secret, deps);
+        const { data } = await client.call('ListCallbackEvents', {
+            query: {
+                after: args.after,
+                limit: args.limit,
+                sessionId: args.sessionId,
+                pending: args.pending,
+            },
+        });
+        const hasResults = data.items.some((e) => RESULT_EVENTS.has(e.event));
+        const key = hasResults ? await resolveDecryptionKey() : undefined;
+        const reclaim = ReclaimVerification.create({
+            baseUrl: apiUrl(),
+            orgSecret: secret,
+            fetch: deps.fetch,
+        });
+        const items = [];
+        for (const item of data.items) {
+            items.push(await decode(item));
+        }
+        return {
+            listener,
+            items,
+            next: data.next,
+            ...(listener.created
+                ? {
+                    _notes: 'Created the pull listener; only sessions created from '
+                        + 'now on are recorded. It works only while this MCP server '
+                        + 'runs.',
+                }
+                : {}),
+        };
+        async function decode(item) {
+            const base = {
+                id: item.id,
+                sessionId: item.sessionId,
+                event: item.event,
+                deliveryStatus: item.deliveryStatus,
+                createdAt: item.createdAt,
+            };
+            try {
+                if (!RESULT_EVENTS.has(item.event)) {
+                    const received = await reclaim.results.receive(item.envelope);
+                    return received.kind === 'event'
+                        ? { ...base, eventData: received.eventData }
+                        : base;
+                }
+                const jws = await decryptCallback(key, item.envelope);
+                const outcome = await reclaim.results.verify(jws, {
+                    reclaimSessionId: item.sessionId,
+                });
+                return {
+                    ...base,
+                    result: { payload: outcome.payload, proofs: outcome.proofs },
+                };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return RESULT_EVENTS.has(item.event)
+                    ? { ...base, resultError: message }
+                    : { ...base, eventError: message };
+            }
+        }
+    });
+}