@fdkey/mcp 0.2.0

package/dist/types.d.ts

@@ -0,0 +1,156 @@
+export type Policy = {
+    type: 'once_per_session';
+} | {
+    type: 'each_call';
+} | {
+    type: 'every_minutes';
+    minutes: number;
+};
+export type PolicyShorthand = 'once_per_session' | 'each_call';
+export interface ProtectEntry {
+    policy: Policy | PolicyShorthand;
+}
+export interface FdkeyConfig {
+    /** Integrator's VPS API key (Bearer token). Required. */
+    apiKey: string;
+    /** Tools that require verification, keyed by tool name. */
+    protect?: Record<string, ProtectEntry>;
+    /** 'easy' | 'medium' | 'hard' — passed to VPS on challenge fetch. Default: 'medium' */
+    difficulty?: 'easy' | 'medium' | 'hard';
+    /** What happens when the agent fails the puzzle. Default: 'block' */
+    onFail?: 'block' | 'allow';
+    /** What happens when the FDKEY VPS is unreachable. Default: 'allow'
+     *  (fail-open) — the protected tool runs as if no verification were
+     *  required, so an FDKEY outage doesn't brick integrator workflows.
+     *  Set to 'block' if your threat model prefers fail-closed. */
+    onVpsError?: 'block' | 'allow';
+    /** When true, blocked-tool errors embed the puzzle data so the agent can submit without a separate fdkey_get_challenge call. Default: false */
+    inlineChallenge?: boolean;
+    /** Skip discovery and use this VPS URL directly (local dev, self-hosted). */
+    vpsUrl?: string;
+    /** Override the Cloudflare CDN discovery URL. */
+    discoveryUrl?: string;
+    /** Arbitrary string-keyed dimensions forwarded to FDKEY on every
+     *  challenge request, stored as `tags` on the session row. Useful for
+     *  multi-tenant setups (`tenant_id`), env labels (`env: prod`), A/B
+     *  experiments, deployment markers, etc.
+     *
+     *  IMPORTANT: tags travel to FDKEY's servers and may end up in our
+     *  analytics database. **Never put end-user PII in here.** Bounded
+     *  server-side at 16 keys, 50 chars/key, 200 chars/value — extra
+     *  fields are rejected with HTTP 400. */
+    tags?: Record<string, string>;
+}
+export interface SessionState {
+    /** True after any successful submit on this connection. Never reset to false. */
+    verified: boolean;
+    /** Timestamp of the most recent successful verification (puzzle solve). */
+    verifiedAt: number | null;
+    /** Timestamp (ms epoch) of the last access. Drives the LRU + TTL
+     *  eviction in the per-server session map so the SDK doesn't leak
+     *  session entries on long-lived shared servers. Touched by every
+     *  call into `getSession(...)`. */
+    lastTouchedAt: number;
+    /** True after a successful submit; consumed (set false) by the next each_call tool call. */
+    freshVerificationAvailable: boolean;
+    /** Internal: the active VPS challenge ID for this connection. Agent never sees this. */
+    pendingChallengeId: string | null;
+    /** Decoded JWT payload from the most recent successful verification. Surfaced to
+     *  integrator tool handlers via getFdkeyContext(). The raw JWT itself is never stored. */
+    lastClaims: Record<string, unknown> | null;
+    /** AI client identification captured from MCP `initialize` handshake.
+     *  Lazy-copied from the closure-scope `latestClientInfo` on the first tool call
+     *  for this session (so it reflects whichever client most recently completed
+     *  initialize on this server instance). Forwarded to the VPS on /v1/challenge. */
+    clientInfo: {
+        name: string;
+        version: string;
+        title?: string;
+        capabilities?: Record<string, unknown>;
+    } | null;
+    /** Negotiated MCP protocol version captured from the initialize request
+     *  params (e.g. "2025-03-26"). Filled by the InitializeRequestSchema
+     *  interceptor in withFdkey(). */
+    protocolVersion: string | null;
+    /** The MCP-Session-Id header value from HTTP Streamable transport, or the
+     *  literal `'stdio'` for stdio transport. Captured from `extra.sessionId` on
+     *  the first tool call. Forwarded to the VPS on /v1/challenge. */
+    mcpSessionId: string | null;
+    /** Inferred MCP transport flavor: stdio if no sessionId on the handler extra,
+     *  http otherwise, unknown if we haven't seen a tool call yet. */
+    transport: 'stdio' | 'http' | 'unknown';
+}
+/** Agent block forwarded to the VPS in the /v1/challenge request body.
+ *  Mirrors the fields stored in `vps_sessions.agent_info.agent`. */
+export interface AgentMeta {
+    client_name?: string;
+    client_version?: string;
+    client_title?: string;
+    client_capabilities?: Record<string, unknown>;
+    protocol_version?: string;
+    mcp_session_id?: string;
+    transport?: 'stdio' | 'http' | 'unknown';
+}
+/** Integrator block forwarded to the VPS — facts about the MCP server +
+ *  SDK version that's calling us. Stored in `vps_sessions.agent_info.integrator`
+ *  alongside the VPS-observed `ip` + `user_agent`. */
+export interface IntegratorMeta {
+    server_name?: string;
+    server_version?: string;
+    sdk_version?: string;
+}
+/** Combined per-challenge metadata bundle. Computed by withFdkey() each time
+ *  a challenge is fetched and passed to VpsClient.fetchChallenge() as a single
+ *  object so the wire format can grow without churning the call signature. */
+export interface ChallengeMeta {
+    agent?: AgentMeta;
+    integrator?: IntegratorMeta;
+    tags?: Record<string, string>;
+}
+/** Returned by `IVpsRouter.getTarget()`. Encapsulates everything a caller
+ *  needs to make a TLS request that lands on the correct VPS in the fleet:
+ *  a stable URL, an optional dispatcher pinned to a chosen IP (Node-only;
+ *  undefined on Workers/Bun/Deno or when StaticRouter is used), and the IP
+ *  itself for failure tracking.
+ *
+ *  `dispatcher` is typed `unknown` so this module — and any module that
+ *  imports it — never touches the undici types. The runtime check happens
+ *  inside vps-client.ts which casts it back when passing to fetch. */
+export interface RoutingTarget {
+    url: string;
+    dispatcher?: unknown;
+    ip?: string;
+}
+export interface IVpsRouter {
+    getTarget(): Promise<RoutingTarget>;
+    recordFailure(ip: string | undefined): void;
+}
+/** A VPS in the fleet, as listed in cdn.fdkey.com/endpoints.json.
+ *  All FDKEY VPSs serve HTTPS for the same hostname (`api.fdkey.com`); the
+ *  SDK pins each connection to a specific IP and presents `api.fdkey.com`
+ *  as the SNI value, so the cert validates regardless of which IP we pick.
+ *  This is the standard SDK-driven multi-region routing pattern (MongoDB
+ *  driver, AWS SDK, etc.) and means adding a VPS = adding an entry here,
+ *  with zero DNS work. */
+export interface VpsEndpoint {
+    /** Public IPv4 of the VPS. */
+    ip: string;
+    /** Region tag for analytics + admin-key env-var derivation. */
+    region: string;
+    /** Selection weight (currently informational; sort uses error+latency). */
+    weight: number;
+    /** Marker for graceful decommissioning. SDK ignores deprecated entries. */
+    deprecated?: boolean;
+}
+export interface WellKnownKey {
+    alg: string;
+    kid: string;
+    public_key_pem: string;
+}
+export interface WellKnownPayload {
+    issuer: string;
+    keys: WellKnownKey[];
+    jwt_default_lifetime_seconds: number;
+}
+export declare function normalisePolicy(p: Policy | PolicyShorthand): Policy;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,6 @@
+export function normalisePolicy(p) {
+    if (typeof p === 'string')
+        return { type: p };
+    return p;
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAmKA,MAAM,UAAU,eAAe,CAAC,CAA2B;IACzD,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;IAC9C,OAAO,CAAC,CAAC;AACX,CAAC"}

package/dist/vps-client.d.ts

@@ -0,0 +1,42 @@
+import type { ChallengeMeta, IVpsRouter } from './types.js';
+export interface ChallengeResponse {
+    challenge_id: string;
+    expires_at: string;
+    expires_in_seconds?: number;
+    difficulty: string;
+    types_served: string[];
+    header?: string;
+    puzzles: Record<string, unknown>;
+    footer?: string;
+}
+export interface SubmitResponse {
+    verified: boolean;
+    jwt?: string;
+    types_passed?: number;
+    types_served?: number;
+    required_to_pass?: number;
+    breakdown?: Record<string, unknown>;
+}
+export declare class VpsHttpError extends Error {
+    readonly status: number;
+    readonly body: {
+        error?: string;
+        message?: string;
+        [k: string]: unknown;
+    };
+    constructor(status: number, body: {
+        error?: string;
+        message?: string;
+        [k: string]: unknown;
+    });
+}
+export declare class VpsClient {
+    private readonly router;
+    private readonly apiKey;
+    private readonly difficulty;
+    constructor(router: IVpsRouter, apiKey: string, difficulty: string);
+    fetchChallenge(meta?: ChallengeMeta): Promise<ChallengeResponse>;
+    submitAnswers(challengeId: string, answers: Record<string, unknown>): Promise<SubmitResponse>;
+    private post;
+}
+//# sourceMappingURL=vps-client.d.ts.map

package/dist/vps-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vps-client.d.ts","sourceRoot":"","sources":["../src/vps-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE5D,MAAM,WAAW,iBAAiB;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,OAAO,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAMD,qBAAa,YAAa,SAAQ,KAAK;aAEnB,MAAM,EAAE,MAAM;aACd,IAAI,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE;gBADhE,MAAM,EAAE,MAAM,EACd,IAAI,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE;CAInF;AAED,qBAAa,SAAS;IAElB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAFV,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM;IAG/B,cAAc,CAAC,IAAI,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAehE,aAAa,CACjB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC,cAAc,CAAC;YAOZ,IAAI;CA0CnB"}

package/dist/vps-client.js

@@ -0,0 +1,90 @@
+function hasValue(obj) {
+    return Object.values(obj).some((v) => v !== undefined && v !== null);
+}
+export class VpsHttpError extends Error {
+    status;
+    body;
+    constructor(status, body) {
+        super(body.error ?? `HTTP ${status}`);
+        this.status = status;
+        this.body = body;
+    }
+}
+export class VpsClient {
+    router;
+    apiKey;
+    difficulty;
+    constructor(router, apiKey, difficulty) {
+        this.router = router;
+        this.apiKey = apiKey;
+        this.difficulty = difficulty;
+    }
+    async fetchChallenge(meta) {
+        const target = await this.router.getTarget();
+        const body = {
+            difficulty: this.difficulty,
+            client_type: 'mcp',
+        };
+        // Only include each block if at least one field inside is populated —
+        // keeps the wire payload clean when the caller has no metadata yet
+        // (e.g. challenge fetched before any tool call has fired oninitialized).
+        if (meta?.agent && hasValue(meta.agent))
+            body.agent = meta.agent;
+        if (meta?.integrator && hasValue(meta.integrator))
+            body.integrator = meta.integrator;
+        if (meta?.tags && Object.keys(meta.tags).length > 0)
+            body.tags = meta.tags;
+        return this.post(target, '/v1/challenge', body);
+    }
+    async submitAnswers(challengeId, answers) {
+        const target = await this.router.getTarget();
+        return this.post(target, '/v1/submit', {
+            challenge_id: challengeId, answers,
+        });
+    }
+    async post(target, path, body) {
+        const fullUrl = `${target.url}${path}`;
+        // Build init separately so we only attach `dispatcher` when present.
+        // Workers/Bun/Deno don't have undici Agent, so dispatcher will be
+        // undefined and the global fetch is invoked with a clean RequestInit.
+        const init = {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${this.apiKey}`,
+            },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(10000),
+        };
+        if (target.dispatcher)
+            init.dispatcher = target.dispatcher;
+        let res;
+        try {
+            res = await fetch(fullUrl, init);
+        }
+        catch (err) {
+            // Network failure / timeout — surface as failure to caller, mark endpoint
+            this.router.recordFailure(target.ip);
+            throw err;
+        }
+        const text = await res.text();
+        let parsed = {};
+        if (text) {
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                parsed = { _raw: text };
+            }
+        }
+        if (!res.ok) {
+            // 4xx = client/state error from VPS — do NOT mark endpoint as failed
+            // 5xx = server error — mark endpoint as failed for failover
+            if (res.status >= 500)
+                this.router.recordFailure(target.ip);
+            throw new VpsHttpError(res.status, parsed);
+        }
+        return parsed;
+    }
+}
+//# sourceMappingURL=vps-client.js.map

package/dist/vps-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vps-client.js","sourceRoot":"","sources":["../src/vps-client.ts"],"names":[],"mappings":"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"}

package/dist/vps-router.d.ts

@@ -0,0 +1,29 @@
+import type { IVpsRouter, RoutingTarget } from './types.js';
+/** Multi-VPS discovery + IP-pinning router. Fetch endpoint list from cdn.fdkey.com, parallel-probe
+ *  each IP via HEAD https://api.fdkey.com/health pinned to that IP, sort
+ *  by (error count ASC, latency ASC), pick winner. Re-probe every hour or
+ *  on `recordFailure(ip)`. */
+export declare class VpsRouter implements IVpsRouter {
+    private readonly discoveryUrl;
+    private endpointCache;
+    private selectedIp;
+    private dispatchers;
+    private latencies;
+    private errorCounts;
+    private nextProbe;
+    constructor(discoveryUrl?: string);
+    getTarget(): Promise<RoutingTarget>;
+    recordFailure(ip: string | undefined): void;
+    /** Build (and cache) an undici Agent that pins all connections to `ip`
+     *  while leaving SNI and cert validation to use the URL's hostname.
+     *  Dispatchers are reused across calls — creating a new one per request
+     *  would defeat the connection-pooling benefits. */
+    private dispatcherFor;
+    private refreshEndpoints;
+    private fetchEndpoints;
+    /** HEAD https://api.fdkey.com/health pinned per-IP. We use a per-call
+     *  ad-hoc dispatcher (not the cached one) so a probe failure doesn't
+     *  leave a soured connection in the pool. */
+    private probeAll;
+}
+//# sourceMappingURL=vps-router.d.ts.map

package/dist/vps-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vps-router.d.ts","sourceRoot":"","sources":["../src/vps-router.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAe,UAAU,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAqCzE;;;8BAG8B;AAC9B,qBAAa,SAAU,YAAW,UAAU;IAC1C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,aAAa,CAAgC;IACrD,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,WAAW,CAA4B;IAC/C,OAAO,CAAC,SAAS,CAA6B;IAC9C,OAAO,CAAC,WAAW,CAA6B;IAChD,OAAO,CAAC,SAAS,CAAK;gBAEV,YAAY,CAAC,EAAE,MAAM;IAI3B,SAAS,IAAI,OAAO,CAAC,aAAa,CAAC;IAYzC,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAQ3C;;;wDAGoD;IACpD,OAAO,CAAC,aAAa;YAuBP,gBAAgB;YAsBhB,cAAc;IAmB5B;;iDAE6C;YAC/B,QAAQ;CAgCvB"}

package/dist/vps-router.js

@@ -0,0 +1,146 @@
+import { Agent, fetch } from 'undici';
+const DEFAULT_DISCOVERY_URL = 'https://cdn.fdkey.com/endpoints.json';
+/** All FDKEY VPSs serve TLS for this hostname. The SDK uses it as the SNI
+ *  value when connecting to any IP from the discovery list — every box in
+ *  the fleet holds a Let's Encrypt cert for this name (acquired via the
+ *  DNS-01 challenge so multiple boxes can share the cert without
+ *  fighting over HTTP-01). */
+const FDKEY_API_HOSTNAME = 'api.fdkey.com';
+const PROBE_INTERVAL_MS = 60 * 60 * 1000; // 1 hour
+const DISCOVERY_CACHE_TTL_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+/** Multi-VPS discovery + IP-pinning router. Fetch endpoint list from cdn.fdkey.com, parallel-probe
+ *  each IP via HEAD https://api.fdkey.com/health pinned to that IP, sort
+ *  by (error count ASC, latency ASC), pick winner. Re-probe every hour or
+ *  on `recordFailure(ip)`. */
+export class VpsRouter {
+    discoveryUrl;
+    endpointCache = null;
+    selectedIp = null;
+    dispatchers = new Map();
+    latencies = new Map();
+    errorCounts = new Map();
+    nextProbe = 0;
+    constructor(discoveryUrl) {
+        this.discoveryUrl = discoveryUrl ?? DEFAULT_DISCOVERY_URL;
+    }
+    async getTarget() {
+        if (!this.selectedIp || Date.now() >= this.nextProbe) {
+            await this.refreshEndpoints();
+        }
+        const ip = this.selectedIp;
+        return {
+            url: `https://${FDKEY_API_HOSTNAME}`,
+            dispatcher: this.dispatcherFor(ip),
+            ip,
+        };
+    }
+    recordFailure(ip) {
+        if (!ip)
+            return;
+        this.errorCounts.set(ip, (this.errorCounts.get(ip) ?? 0) + 1);
+        if (this.selectedIp === ip) {
+            this.selectedIp = null; // force re-selection next call
+        }
+    }
+    /** Build (and cache) an undici Agent that pins all connections to `ip`
+     *  while leaving SNI and cert validation to use the URL's hostname.
+     *  Dispatchers are reused across calls — creating a new one per request
+     *  would defeat the connection-pooling benefits. */
+    dispatcherFor(ip) {
+        let d = this.dispatchers.get(ip);
+        if (d)
+            return d;
+        const lookup = (_host, opts, cb) => {
+            if (opts.all) {
+                cb(null, [{ address: ip, family: 4 }]);
+            }
+            else {
+                cb(null, ip, 4);
+            }
+        };
+        d = new Agent({
+            connect: {
+                // Hand undici a custom resolver: regardless of what hostname is
+                // being requested, return this IP. The TLS handshake still uses
+                // the URL's hostname for SNI + cert verification, which is what
+                // makes the IP-pin trick work.
+                lookup,
+            },
+        });
+        this.dispatchers.set(ip, d);
+        return d;
+    }
+    async refreshEndpoints() {
+        const endpoints = await this.fetchEndpoints();
+        const active = endpoints.filter((e) => !e.deprecated);
+        if (active.length === 0) {
+            throw new Error('fdkey: no active VPS endpoints found in discovery list');
+        }
+        const results = await this.probeAll(active);
+        // Sort by (error_count ASC, latency ASC). Endpoints that didn't respond
+        // to the probe get latency = Infinity and rank last among equal error
+        // counts — but they're still candidates if everything else is dead.
+        results.sort((a, b) => {
+            const ea = this.errorCounts.get(a.ip) ?? 0;
+            const eb = this.errorCounts.get(b.ip) ?? 0;
+            if (ea !== eb)
+                return ea - eb;
+            return (a.latencyMs ?? Infinity) - (b.latencyMs ?? Infinity);
+        });
+        this.selectedIp = results[0].ip;
+        this.nextProbe = Date.now() + PROBE_INTERVAL_MS;
+    }
+    async fetchEndpoints() {
+        if (this.endpointCache &&
+            Date.now() - this.endpointCache.fetchedAt < DISCOVERY_CACHE_TTL_MS) {
+            return this.endpointCache.endpoints;
+        }
+        try {
+            const res = await fetch(this.discoveryUrl, { signal: AbortSignal.timeout(5000) });
+            if (!res.ok)
+                throw new Error(`discovery fetch ${res.status}`);
+            const data = (await res.json());
+            this.endpointCache = { endpoints: data, fetchedAt: Date.now() };
+            return data;
+        }
+        catch (err) {
+            if (this.endpointCache)
+                return this.endpointCache.endpoints; // stale ok
+            throw new Error(`fdkey: cannot reach discovery URL and no cached endpoints: ${err}`);
+        }
+    }
+    /** HEAD https://api.fdkey.com/health pinned per-IP. We use a per-call
+     *  ad-hoc dispatcher (not the cached one) so a probe failure doesn't
+     *  leave a soured connection in the pool. */
+    async probeAll(endpoints) {
+        return Promise.all(endpoints.map(async (e) => {
+            const start = Date.now();
+            try {
+                const probeLookup = (_h, opts, cb) => {
+                    if (opts.all) {
+                        cb(null, [{ address: e.ip, family: 4 }]);
+                    }
+                    else {
+                        cb(null, e.ip, 4);
+                    }
+                };
+                const probeAgent = new Agent({
+                    connect: { lookup: probeLookup },
+                });
+                await fetch(`https://${FDKEY_API_HOSTNAME}/health`, {
+                    method: 'HEAD',
+                    signal: AbortSignal.timeout(3000),
+                    dispatcher: probeAgent,
+                });
+                await probeAgent.close();
+                const latencyMs = Date.now() - start;
+                this.latencies.set(e.ip, latencyMs);
+                return { ip: e.ip, latencyMs };
+            }
+            catch {
+                return { ip: e.ip, latencyMs: null };
+            }
+        }));
+    }
+}
+//# sourceMappingURL=vps-router.js.map

package/dist/vps-router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vps-router.js","sourceRoot":"","sources":["../src/vps-router.ts"],"names":[],"mappings":"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"}

package/dist/well-known.d.ts

@@ -0,0 +1,14 @@
+import { type KeyLike } from 'jose';
+import type { IVpsRouter } from './types.js';
+/** Fetches and caches the public-key list at `${vpsBase}/.well-known/fdkey.json`.
+ *  Goes through the VpsRouter so the request lands on the same IP currently
+ *  serving production traffic (and uses the same dispatcher / SNI / cert
+ *  handling — just like challenge/submit calls). */
+export declare class WellKnownClient {
+    private readonly router;
+    private cache;
+    constructor(router: IVpsRouter);
+    getKey(kid: string): Promise<KeyLike | null>;
+    private refresh;
+}
+//# sourceMappingURL=well-known.d.ts.map

package/dist/well-known.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"well-known.d.ts","sourceRoot":"","sources":["../src/well-known.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,OAAO,EAAE,MAAM,MAAM,CAAC;AAChD,OAAO,KAAK,EAAoB,UAAU,EAAE,MAAM,YAAY,CAAC;AAS/D;;;oDAGoD;AACpD,qBAAa,eAAe;IAGd,OAAO,CAAC,QAAQ,CAAC,MAAM;IAFnC,OAAO,CAAC,KAAK,CAAyB;gBAET,MAAM,EAAE,UAAU;IAEzC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;YAUpC,OAAO;CAmBtB"}

package/dist/well-known.js

@@ -0,0 +1,42 @@
+import { importSPKI } from 'jose';
+const CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
+/** Fetches and caches the public-key list at `${vpsBase}/.well-known/fdkey.json`.
+ *  Goes through the VpsRouter so the request lands on the same IP currently
+ *  serving production traffic (and uses the same dispatcher / SNI / cert
+ *  handling — just like challenge/submit calls). */
+export class WellKnownClient {
+    router;
+    cache = null;
+    constructor(router) {
+        this.router = router;
+    }
+    async getKey(kid) {
+        if (this.cache && Date.now() - this.cache.fetchedAt < CACHE_TTL_MS) {
+            const k = this.cache.keys.get(kid);
+            if (k)
+                return k;
+            // kid not in cache — may have just rotated, refetch once
+        }
+        await this.refresh();
+        return this.cache.keys.get(kid) ?? null;
+    }
+    async refresh() {
+        const target = await this.router.getTarget();
+        const init = {
+            signal: AbortSignal.timeout(5000),
+        };
+        if (target.dispatcher)
+            init.dispatcher = target.dispatcher;
+        const res = await fetch(`${target.url}/.well-known/fdkey.json`, init);
+        if (!res.ok)
+            throw new Error(`fdkey: well-known fetch failed ${res.status}`);
+        const payload = (await res.json());
+        const keys = new Map();
+        for (const k of payload.keys) {
+            const key = await importSPKI(k.public_key_pem, k.alg);
+            keys.set(k.kid, key);
+        }
+        this.cache = { keys, fetchedAt: Date.now() };
+    }
+}
+//# sourceMappingURL=well-known.js.map

package/dist/well-known.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"well-known.js","sourceRoot":"","sources":["../src/well-known.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAgB,MAAM,MAAM,CAAC;AAGhD,MAAM,YAAY,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,SAAS;AAO9C;;;oDAGoD;AACpD,MAAM,OAAO,eAAe;IAGG;IAFrB,KAAK,GAAoB,IAAI,CAAC;IAEtC,YAA6B,MAAkB;QAAlB,WAAM,GAAN,MAAM,CAAY;IAAG,CAAC;IAEnD,KAAK,CAAC,MAAM,CAAC,GAAW;QACtB,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,YAAY,EAAE,CAAC;YACnE,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACnC,IAAI,CAAC;gBAAE,OAAO,CAAC,CAAC;YAChB,yDAAyD;QAC3D,CAAC;QACD,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;QACrB,OAAO,IAAI,CAAC,KAAM,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC;IAC3C,CAAC;IAEO,KAAK,CAAC,OAAO;QACnB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;QAC7C,MAAM,IAAI,GAA2C;YACnD,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC;SAClC,CAAC;QACF,IAAI,MAAM,CAAC,UAAU;YAAE,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC;QAC3D,MAAM,GAAG,GAAG,MAAM,KAAK,CACrB,GAAG,MAAM,CAAC,GAAG,yBAAyB,EACtC,IAAmB,CACpB,CAAC;QACF,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;QAC7E,MAAM,OAAO,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAqB,CAAC;QACvD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAmB,CAAC;QACxC,KAAK,MAAM,CAAC,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;YAC7B,MAAM,GAAG,GAAG,MAAM,UAAU,CAAC,CAAC,CAAC,cAAc,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;YACtD,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACvB,CAAC;QACD,IAAI,CAAC,KAAK,GAAG,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;IAC/C,CAAC;CACF"}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@fdkey/mcp",
+  "version": "0.2.0",
+  "description": "FDKEY verification middleware for MCP servers — gate AI-agent access behind LLM-only puzzles. Runs on Node 18+, Cloudflare Workers, Bun, and Deno.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "prepublishOnly": "tsc"
+  },
+  "peerDependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0"
+  },
+  "dependencies": {
+    "jose": "^5.10.0",
+    "zod": "^3.24.0"
+  },
+  "optionalDependencies": {
+    "undici": "^8.2.0"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@types/node": "^25.6.0",
+    "typescript": "^5.8.0",
+    "undici": "^8.2.0",
+    "vitest": "^2.1.0"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "fdkey",
+    "captcha",
+    "verification",
+    "ai-agent",
+    "anti-bot",
+    "middleware",
+    "cloudflare-workers",
+    "edge"
+  ],
+  "author": "FDKEY",
+  "license": "MIT",
+  "homepage": "https://fdkey.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fdkey/sdks.git",
+    "directory": "typescript"
+  },
+  "bugs": {
+    "url": "https://github.com/fdkey/sdks/issues"
+  },
+  "engines": {
+    "node": ">=18.17"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}