@reclaimprotocol/agent 0.1.33 → 0.1.35

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 };
+            }
+        }
+    });
+}

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

@@ -1,4 +1,10 @@
 import { type RegisteredTool } from '../../server.ts';
+/**
+ * Resolve the org secret used to authenticate verification reads. Auth is a
+ * single per-org bearer secret (`rorg_…`), not an eth signature: the call's
+ * `orgToken`, else `RECLAIM_ORG_SECRET`.
+ */
+export declare function resolveOrgSecret(orgToken?: string): string;
 /**
  * `get_verification_result` — check a session's status and, once a result has
  * been submitted, pull the stored payload(s) and verify locally. Auth is the

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

@@ -3,6 +3,7 @@ import assert from 'node:assert';
 import { apiUrl, orgSecret } from "../../../consts.js";
 import { defineTool } from "../../server.js";
 import { resolveDecryptionKey } from "../authenticate/decrypt-key.js";
+import { savedOrgKey } from "../authenticate/org-key-store.js";
 /** Statuses that can carry a Builder-managed terminal result. */
 const TERMINAL = new Set([
     'success',
@@ -24,12 +25,11 @@ const RESULT_EVENTS = new Set([
  * single per-org bearer secret (`rorg_…`), not an eth signature: the call's
  * `orgToken`, else `RECLAIM_ORG_SECRET`.
  */
-function resolveOrgSecret(orgToken) {
-    const secret = orgToken?.trim() || orgSecret()?.trim();
+export function resolveOrgSecret(orgToken) {
+    const secret = orgToken?.trim() || orgSecret()?.trim() || savedOrgKey();
     assert(secret, new Error('No organization API key. Verification reads authenticate with the org '
-        + 'secret (rorg_…): pass orgToken (from issue_org_token, or the '
-        + 'app\'s RECLAIM_ORG_SECRET), or export RECLAIM_ORG_SECRET for the '
-        + 'MCP server.'));
+        + 'secret (rorg_…): run issue_org_token to save a key, pass orgToken, '
+        + 'or export RECLAIM_ORG_SECRET for the MCP server.'));
     return secret;
 }
 /**
@@ -49,7 +49,8 @@ export function verificationResultTool() {
             + 'while Builder still holds it: until its callback is delivered, or '
             + '7 days undelivered. The callback is the normal way to get results. '
             + 'Authenticates with the org API key: `orgToken`, else '
-            + '`RECLAIM_ORG_SECRET`. Encrypted deliveries also require '
+            + '`RECLAIM_ORG_SECRET`, else the key saved by `issue_org_token`. '
+            + 'Encrypted deliveries also require '
             + 'the matching ETH decryption key. Returns `ready: false` until a '
             + 'payload is available. Invalid results fail verification and are not '
             + 'returned. Use `list_verification_events` to diagnose '
@@ -68,11 +69,13 @@ export function verificationResultTool() {
                     maxLength: 200,
                     description: 'The organization API key (`rorg_…`): from '
                         + '`issue_org_token`, or the app\'s RECLAIM_ORG_SECRET. '
-                        + 'Defaults to the MCP server\'s RECLAIM_ORG_SECRET. Never echo '
-                        + 'it back to the user.',
+                        + 'Defaults to the MCP server\'s RECLAIM_ORG_SECRET, then the '
+                        + 'key saved by `issue_org_token`. Never echo it back to the '
+                        + 'user.',
                 },
             },
         },
+        annotations: { readOnlyHint: true, openWorldHint: true },
     }, async (args) => {
         const secret = resolveOrgSecret(args.orgToken);
         // Optional eth decryption key — absent ⇒ plaintext-only.

package/lib/proof/check-attestor.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Attestor reachability check. Proves a public request with a throwaway owner
+ * key to show whether the attestor works from this machine, independent of any
+ * developer provider or site.
+ */
+import { createClaimOnAttestor } from '@reclaimprotocol/attestor-core';
+import './patch-domhandler.ts';
+/**
+ * Default time budget for one check. A live run takes about 8 s; a longer
+ * budget risks the MCP client's own tool-call timeout.
+ */
+export declare const CHECK_ATTESTOR_TIMEOUT_MS = 45000;
+/**
+ * Request params for the check: the public CoinGecko price request from the
+ * attestor-core examples. Source:
+ * https://raw.githubusercontent.com/reclaimprotocol/attestor-core/refs/heads/main/example/coin-gecko.json
+ */
+export declare const COIN_GECKO_PARAMS: {
+    url: string;
+    method: "GET";
+    body: string;
+    headers: {
+        'User-Agent': string;
+        'Sec-Fetch-Mode': string;
+        'Sec-Fetch-Site': string;
+    };
+    responseMatches: {
+        invert: boolean;
+        type: "regex";
+        value: string;
+    }[];
+    responseRedactions: {
+        jsonPath: string;
+        regex: string;
+        xPath: string;
+    }[];
+    additionalClientOptions: {};
+};
+export type AttestorCheckErrorKind = 
+/** Socket, connection, DNS, TLS, or timeout failure. */
+'attestor-unreachable'
+/** The attestor answered and rejected or failed the claim. */
+ | 'attestor-error'
+/** Local setup (ZK files) failed before the attestor was contacted. */
+ | 'setup-failed';
+export interface AttestorCheckResult {
+    ok: boolean;
+    attestorUrl: string;
+    durationMs: number;
+    extractedParameters?: Record<string, string>;
+    error?: string;
+    errorKind?: AttestorCheckErrorKind;
+}
+/** Creates the claim on the attestor (`createClaimOnAttestor` by default). */
+export type CreateClaim = (args: Parameters<typeof createClaimOnAttestor>[0]) => Promise<unknown>;
+export interface CheckAttestorOptions {
+    attestorUrl?: string;
+    timeoutMs?: number;
+    /** Replaces the network call in tests. */
+    createClaim?: CreateClaim;
+    /** Replaces the ZK file download in tests. */
+    prepare?: () => Promise<void>;
+}
+/** True when `message` looks like a network failure rather than a rejection. */
+export declare function isNetworkError(message: string | undefined): boolean;
+/** Prove the public CoinGecko request once and classify the outcome. */
+export declare function checkAttestor(opts?: CheckAttestorOptions): Promise<AttestorCheckResult>;