@reclaimprotocol/agent 0.1.34 → 0.1.36

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,77 @@
+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;
+};
+/** A session whose oldest pending event the app has not accepted. */
+type Blocked = {
+    sessionId: string;
+    event: string;
+    eventId: string;
+    httpStatus?: number;
+    attempts: number;
+    lastError?: string;
+    /** When the first attempt failed, as an ISO timestamp. */
+    since: string;
+};
+export interface ProxyDeps extends CallbackDeps {
+    /** The clock, in milliseconds. Defaults to `Date.now`. */
+    now?: () => number;
+    /** 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.
+ *
+ * Order holds per session. When an event fails, its session is held: its later
+ * events are not sent or acknowledged, and the failed event is retried with
+ * exponential backoff (2 s, 4 s, ... 30 s). Other sessions keep flowing at the
+ * normal poll rate. Held sessions appear in `status().blocked`, and clear when
+ * the app accepts the event.
+ */
+declare class Forwarder {
+    #private;
+    target: Target;
+    listener: ListenerInfo;
+    constructor(client: ReclaimClient, listener: ListenerInfo, target: Target, deps: ProxyDeps);
+    status(): {
+        recent: Recent[];
+        blocked: Blocked[];
+        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,383 @@
+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_held, _Forwarder_host, _Forwarder_running, _Forwarder_loop, _Forwarder_tick, _Forwarder_hold, _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;
+/**
+ * Pages read per poll. A page is `BATCH` events, so a poll can look past up to
+ * 500 pending events. That is enough to reach other sessions behind several
+ * held ones, and still bounds the work of one poll.
+ */
+const MAX_PAGES = 10;
+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.
+ *
+ * Order holds per session. When an event fails, its session is held: its later
+ * events are not sent or acknowledged, and the failed event is retried with
+ * exponential backoff (2 s, 4 s, ... 30 s). Other sessions keep flowing at the
+ * normal poll rate. Held sessions appear in `status().blocked`, and clear when
+ * the app accepts the event.
+ */
+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()
+        /** Held sessions by session id, with the time of their next attempt. */
+        );
+        /** Held sessions by session id, with the time of their next attempt. */
+        _Forwarder_held.set(this, new Map());
+        _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")],
+            blocked: [...__classPrivateFieldGet(this, _Forwarder_held, "f").values()].map((h) => h.blocked),
+        };
+    }
+    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_held = 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 more = await __classPrivateFieldGet(this, _Forwarder_instances, "m", _Forwarder_tick).call(this);
+            backoff = 0;
+            wait = more ? 0 : POLL_MS;
+        }
+        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 = 
+/**
+ * Forwards one poll's worth of pending events. Returns whether to poll again
+ * at once: the page limit was hit with events still unread, and progress was
+ * made (so held sessions alone never cause a busy loop).
+ */
+async function _Forwarder_tick() {
+    const now = (__classPrivateFieldGet(this, _Forwarder_deps, "f").now || Date.now)();
+    // Sessions whose later events are skipped in this poll.
+    const skip = new Set();
+    const seen = new Set();
+    let after;
+    let page = 0;
+    let full = false;
+    let progress = false;
+    do {
+        const { data } = await __classPrivateFieldGet(this, _Forwarder_client, "f").call('ListCallbackEvents', {
+            query: { pending: true, limit: BATCH, ...(after ? { after } : {}) },
+        });
+        const ack = [];
+        for (const item of data.items) {
+            if (__classPrivateFieldGet(this, _Forwarder_abort, "f").signal.aborted) {
+                break;
+            }
+            seen.add(item.sessionId);
+            const held = __classPrivateFieldGet(this, _Forwarder_held, "f").get(item.sessionId);
+            if (skip.has(item.sessionId)
+                || (held && held.retryAt > now && !__classPrivateFieldGet(this, _Forwarder_unacked, "f").has(item.id))) {
+                skip.add(item.sessionId);
+                continue;
+            }
+            if (__classPrivateFieldGet(this, _Forwarder_unacked, "f").has(item.id)) {
+                ack.push(item.id);
+                continue;
+            }
+            const outcome = await __classPrivateFieldGet(this, _Forwarder_instances, "m", _Forwarder_forward).call(this, item);
+            if (outcome.ok) {
+                __classPrivateFieldGet(this, _Forwarder_held, "f").delete(item.sessionId);
+                ack.push(item.id);
+            }
+            else {
+                // Hold the session so its later events don't overtake this one.
+                __classPrivateFieldGet(this, _Forwarder_instances, "m", _Forwarder_hold).call(this, item, outcome, now);
+                skip.add(item.sessionId);
+            }
+        }
+        if (ack.length) {
+            progress = true;
+            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);
+            }
+        }
+        // `next` skips what this page returned, including held events.
+        after = data.next;
+        full = data.items.length >= BATCH;
+        page += 1;
+    } while (full && page < MAX_PAGES && !__classPrivateFieldGet(this, _Forwarder_abort, "f").signal.aborted);
+    if (!full) {
+        // The listing was read to its end: forget sessions with nothing pending.
+        for (const sessionId of __classPrivateFieldGet(this, _Forwarder_held, "f").keys()) {
+            if (!seen.has(sessionId)) {
+                __classPrivateFieldGet(this, _Forwarder_held, "f").delete(sessionId);
+            }
+        }
+    }
+    return full && progress;
+}, _Forwarder_hold = function _Forwarder_hold(item, outcome, now) {
+    const prev = __classPrivateFieldGet(this, _Forwarder_held, "f").get(item.sessionId);
+    const delay = nextBackoff(prev?.delay || 0);
+    __classPrivateFieldGet(this, _Forwarder_held, "f").set(item.sessionId, {
+        blocked: {
+            sessionId: item.sessionId,
+            event: item.event,
+            eventId: item.id,
+            ...(outcome.httpStatus === undefined
+                ? {}
+                : { httpStatus: outcome.httpStatus }),
+            attempts: (prev?.blocked.attempts || 0) + 1,
+            lastError: outcome.error,
+            since: prev?.blocked.since || new Date(now).toISOString(),
+        },
+        retryAt: now + delay,
+        delay,
+    });
+}, _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 { ok: 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 { ok: false, httpStatus: res.status, error: __classPrivateFieldGet(this, _Forwarder_lastError, "f") };
+        }
+        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 { ok: false, error: __classPrivateFieldGet(this, _Forwarder_lastError, "f") || 'Connection failed' };
+};
+/** 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]`) and acknowledges 2xx responses. '
+            + 'Events of one session arrive in order. When the app rejects '
+            + 'an event, including with a redirect, that session is held and '
+            + 'retried with backoff (2 s up to 30 s) while other sessions '
+            + 'keep flowing. 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, '
+            + 'blocked }`. `listener.expiresAt` is the lease end, and '
+            + '`recent` lists the last events with `status` and '
+            + '`httpStatus`. `blocked` lists each held session as '
+            + '`{ sessionId, event, eventId, httpStatus?, attempts, '
+            + 'lastError?, since }`, and is `[]` when none is held. When '
+            + '`blocked` is not empty, check the app\'s response and logs '
+            + 'for that session. The app must return 2xx for a result that '
+            + 'failed verification, and 5xx only for a temporary error. '
+            + 'Fix the app, and the session resumes on the next retry.',
+        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;