@fdkey/mcp 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+All notable changes to `@fdkey/mcp` will be documented in this file.
+
+## 0.2.0 — 2026-05-09
+
+### Added
+
+- **Cloudflare Workers / Bun / Deno support** on the default routing path.
+  The single-VPS `StaticRouter` now uses the runtime's global `fetch` and
+  imports zero Node-only dependencies. Multi-VPS routing (set via
+  `discoveryUrl`) still uses `undici` for IP-pinning and is lazy-loaded
+  via dynamic `import()`, so Workers bundles never pull undici unless the
+  integrator explicitly opts in. `undici` moved from `dependencies` to
+  `optionalDependencies`.
+- **`score` and `tier` as first-class fields on `FdkeyContext`.**
+  Previously available only inside `FdkeyContext.claims`. The wire shape
+  reserves `score` as a 0..1 float for forward-compat with graduated
+  capability scoring (today the value is binary 1.0/0.0).
+- **Bounded session store** — sessions now evict on a 1h idle TTL with a
+  hard 10k LRU cap (~2 MB max). Long-lived shared MCP servers no longer
+  leak per-session memory.
+- **Actionable error message** when `discoveryUrl` is set but `undici`
+  is not installed.
+- Internal `index.test.ts` covering: lazy-router contract, score/tier
+  shape, SDK_VERSION sync, and SessionStore eviction semantics.
+
+### Changed
+
+- `withFdkey()` no longer reaches into a static `import './vps-router.js'`.
+  The default URL is now `https://api.fdkey.com` when neither `vpsUrl`
+  nor `discoveryUrl` is set.
+- `getFdkeyContext()` reads via `store.peek()` — querying context no
+  longer extends a session's lifetime.
+
+### Migration from 0.1.0
+
+No public API breaks. If you currently relied on `FdkeyContext.claims.score`
+you can keep doing that, or migrate to the first-class `ctx.score` /
+`ctx.tier` fields. If you use multi-VPS routing (`discoveryUrl`), make
+sure `undici` is in your dependencies — it's no longer pulled in by
+default.
+
+## 0.1.0 — 2026-04-XX
+
+Initial pre-publish release. MCP middleware: tool injection, policy gating,
+Ed25519 JWT verify, IP-pinned multi-VPS routing.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FDKEY
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,201 @@
+# @fdkey/mcp
+
+> **FDKEY verification middleware for MCP servers.** Gate AI-agent access to
+> your tools behind LLM-only puzzles. Drop-in for any
+> [Model Context Protocol](https://modelcontextprotocol.io) server.
+
+## What it does
+
+- Injects two MCP tools into your server: `fdkey_get_challenge` and
+  `fdkey_submit_challenge`.
+- Wraps the tools you want to protect — they return
+  `fdkey_verification_required` until the connecting agent has solved a
+  challenge.
+- Talks to `https://api.fdkey.com` for challenge issuance and scoring.
+- Verifies the Ed25519 JWT response **offline** using the public key from
+  `https://api.fdkey.com/.well-known/fdkey.json`.
+
+The agent never handles a token. The connection itself becomes verified —
+verification state lives server-side in the integrator's process, keyed by
+the MCP session id. Every agent verifies for itself; verification doesn't
+transfer between agents.
+
+## Runtime support
+
+| Runtime              | Default (single-VPS) | `discoveryUrl` set (multi-VPS) |
+| -------------------- | :------------------: | :----------------------------: |
+| Node 18+             | ✅                    | ✅                              |
+| Cloudflare Workers   | ✅                    | ❌ (requires `undici`, Node-only) |
+| Bun                  | ✅                    | ✅                              |
+| Deno                 | ✅                    | ⚠️ untested                     |
+
+By default the SDK runs on the global `fetch` and pulls in zero
+Node-only dependencies — works on edge runtimes out of the box. The
+multi-VPS routing path (set via `discoveryUrl`) is lazy-loaded and
+requires `undici` (declared as an `optionalDependency`).
+
+## Install
+
+```bash
+npm install @fdkey/mcp
+```
+
+You also need the official MCP server SDK (`@modelcontextprotocol/sdk`) — it's
+declared as a `peerDependency`, so install your own version:
+
+```bash
+npm install @modelcontextprotocol/sdk
+```
+
+Get an API key at [app.fdkey.com](https://app.fdkey.com).
+
+## Usage
+
+```ts
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { withFdkey } from '@fdkey/mcp';
+
+const server = new McpServer({ name: 'my-server', version: '1.0.0' });
+
+// Wrap the server. `protect` lists tool names that require verification.
+withFdkey(server, {
+  apiKey: process.env.FDKEY_API_KEY!,
+  protect: {
+    sensitive_action: { policy: 'each_call' },
+    register: { policy: 'once_per_session' },
+  },
+});
+
+// Register your tools as normal.
+server.registerTool('sensitive_action', {
+  description: 'Does something that needs verification',
+  inputSchema: { /* ... */ },
+}, async (args, extra) => {
+  // Reaches here only if the agent has solved a challenge first.
+  return { content: [{ type: 'text', text: 'verified' }] };
+});
+
+// Serve over your transport of choice (stdio, HTTP, etc.)
+```
+
+## Policies
+
+Per-tool gating policy — passed as `{ policy: ... }` in the `protect` map:
+
+- `'each_call'` — verification required for every invocation. Use for
+  irreversible actions (payments, deletes).
+- `'once_per_session'` — verification required once per connection. Use
+  for account creation, signup-style flows.
+- `{ type: 'every_minutes', minutes: N }` — verification good for N
+  minutes after the puzzle was solved. Use as a middle ground when
+  "every call" is too aggressive but "once forever" is too loose. Note
+  the timer does NOT extend on calls — it expires `minutes` after the
+  puzzle solve, regardless of activity.
+
+```ts
+protect: {
+  delete_account:    { policy: 'each_call' },
+  register:          { policy: 'once_per_session' },
+  refresh_dashboard: { policy: { type: 'every_minutes', minutes: 15 } },
+}
+```
+
+## Configuration reference
+
+```ts
+withFdkey(server, {
+  apiKey: 'fdk_...',                          // required
+  protect: { ... },                           // tool name → policy (above)
+  vpsUrl?: 'https://api.fdkey.com',           // override for self-hosted
+  discoveryUrl?: 'https://...endpoints.json', // multi-VPS routing (Node only; lazy-loaded)
+  difficulty?: 'easy' | 'medium' | 'hard',    // default 'medium'
+  onFail?: 'block' | 'allow',                 // default 'block' — what happens when puzzle is failed
+  onVpsError?: 'block' | 'allow',             // default 'allow' (see below)
+  inlineChallenge?: boolean,                  // default false — embed puzzle JSON in blocked-tool errors
+                                              //   so the agent can submit without a separate
+                                              //   `fdkey_get_challenge` round-trip
+  tags?: { env: 'prod', region: 'eu' },       // free-form non-PII labels forwarded to FDKEY for analytics
+});
+```
+
+### Failure-mode defaults
+
+`onVpsError: 'allow'` is the default — if the FDKEY scoring service is
+unreachable, the protected tool falls through to your handler instead of
+blocking. We chose this so an FDKEY outage doesn't brick your workflow
+in the worst case (think: we shut down, your DNS can't resolve api.fdkey.com,
+etc.). FDKEY is verification, not gating — your service still serves traffic
+when our service is down.
+
+If your threat model is the opposite — you'd rather drop traffic than admit
+unverified callers during an outage — set `onVpsError: 'block'` and you
+get HTTP-503-style errors instead.
+
+## What FDKEY sees
+
+- The MCP `clientInfo` your agent reports (name, version, protocol version,
+  transport).
+- Challenge IDs, scores, timestamps.
+- Your integrator-supplied `tags`.
+
+## Security notes
+
+- **JWT `aud` is not validated by the SDK.** The audience claim binds the
+  JWT to the integrator's `vps_users.id`, which the SDK doesn't know at
+  verify time. The VPS already binds `aud` to the API key that requested
+  the challenge — defense in depth — but in principle, a JWT issued for
+  one FDKEY-protected service could be replayed against a different
+  one within the JWT lifetime (~5 min default). Keep the JWT lifetime
+  short on the VPS side if your threat model includes cross-integrator
+  replay.
+
+## What FDKEY does NOT see
+
+- Your prompts.
+- Tool inputs or outputs.
+- Your end users' identities or PII.
+- Anything about the agent beyond the MCP `clientInfo` it self-reports.
+
+## Reading verification context
+
+```ts
+import { getFdkeyContext, type FdkeyContext } from '@fdkey/mcp';
+
+server.registerTool('whoami', { /*...*/ }, async (args, extra) => {
+  const ctx = getFdkeyContext(server, extra);
+  if (ctx?.verified) {
+    return {
+      content: [{
+        type: 'text',
+        text: `Verified at ${ctx.verifiedAt} (score=${ctx.score}, tier=${ctx.tier})`,
+      }],
+    };
+  }
+  return { content: [{ type: 'text', text: 'Not verified yet' }] };
+});
+```
+
+`FdkeyContext` shape:
+
+```ts
+interface FdkeyContext {
+  verified: boolean;          // true once the agent has solved a challenge
+  verifiedAt: number | null;  // ms epoch of the most recent successful verify
+  score: number | null;       // 0..1 capability score (today binary 1.0/0.0)
+  tier: string | null;        // VPS-issued tier label (e.g. "free", "gold")
+  claims: Record<string, unknown> | null;  // raw decoded JWT, for power users
+}
+```
+
+`score` is reserved as a 0..1 float for graduated capability scoring (combined T1 correctness + T3 tau + future T4-T6 frequency); today the value is effectively binary. The field shape will not change when the internal scoring grows.
+
+## Links
+
+- Marketing + docs: <https://fdkey.com>
+- Dashboard (sign up + manage keys): <https://app.fdkey.com>
+- Source: <https://github.com/fdkey/sdks>
+- Issues: <https://github.com/fdkey/sdks/issues>
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/guard.d.ts

@@ -0,0 +1,17 @@
+import type { Policy, SessionState } from './types.js';
+export declare function newSession(): SessionState;
+/**
+ * Decides whether a protected tool call passes given the current policy and session state.
+ *
+ *   once_per_session: pass if the session has ever been verified.
+ *   each_call:        pass only if there is an unconsumed fresh verification ticket.
+ *   every_minutes: N: pass if (now - verifiedAt) < N minutes — the timer does NOT
+ *                     extend on calls; it expires N minutes after the puzzle was solved.
+ */
+export declare function canCall(policy: Policy, _toolName: string, session: SessionState): boolean;
+/** Called only when fdkey_submit_challenge succeeds. Replenishes session state. */
+export declare function markVerified(session: SessionState): void;
+/** Called after a protected tool call completes. Consumes the fresh-verification
+ *  ticket for each_call policies. once_per_session and every_minutes do nothing. */
+export declare function consumePolicy(policy: Policy, session: SessionState): void;
+//# sourceMappingURL=guard.d.ts.map

package/dist/guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../src/guard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEvD,wBAAgB,UAAU,IAAI,YAAY,CAazC;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAWzF;AAED,mFAAmF;AACnF,wBAAgB,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,CAIxD;AAED;oFACoF;AACpF,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,IAAI,CAIzE"}

package/dist/guard.js

@@ -0,0 +1,49 @@
+export function newSession() {
+    return {
+        verified: false,
+        verifiedAt: null,
+        lastTouchedAt: Date.now(),
+        freshVerificationAvailable: false,
+        pendingChallengeId: null,
+        lastClaims: null,
+        clientInfo: null,
+        protocolVersion: null,
+        mcpSessionId: null,
+        transport: 'unknown',
+    };
+}
+/**
+ * Decides whether a protected tool call passes given the current policy and session state.
+ *
+ *   once_per_session: pass if the session has ever been verified.
+ *   each_call:        pass only if there is an unconsumed fresh verification ticket.
+ *   every_minutes: N: pass if (now - verifiedAt) < N minutes — the timer does NOT
+ *                     extend on calls; it expires N minutes after the puzzle was solved.
+ */
+export function canCall(policy, _toolName, session) {
+    switch (policy.type) {
+        case 'once_per_session':
+            return session.verified;
+        case 'each_call':
+            return session.verified && session.freshVerificationAvailable;
+        case 'every_minutes': {
+            if (session.verifiedAt === null)
+                return false;
+            return Date.now() - session.verifiedAt < policy.minutes * 60 * 1000;
+        }
+    }
+}
+/** Called only when fdkey_submit_challenge succeeds. Replenishes session state. */
+export function markVerified(session) {
+    session.verified = true;
+    session.verifiedAt = Date.now();
+    session.freshVerificationAvailable = true;
+}
+/** Called after a protected tool call completes. Consumes the fresh-verification
+ *  ticket for each_call policies. once_per_session and every_minutes do nothing. */
+export function consumePolicy(policy, session) {
+    if (policy.type === 'each_call') {
+        session.freshVerificationAvailable = false;
+    }
+}
+//# sourceMappingURL=guard.js.map

package/dist/guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.js","sourceRoot":"","sources":["../src/guard.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,UAAU;IACxB,OAAO;QACL,QAAQ,EAAE,KAAK;QACf,UAAU,EAAE,IAAI;QAChB,aAAa,EAAE,IAAI,CAAC,GAAG,EAAE;QACzB,0BAA0B,EAAE,KAAK;QACjC,kBAAkB,EAAE,IAAI;QACxB,UAAU,EAAE,IAAI;QAChB,UAAU,EAAE,IAAI;QAChB,eAAe,EAAE,IAAI;QACrB,YAAY,EAAE,IAAI;QAClB,SAAS,EAAE,SAAS;KACrB,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,OAAO,CAAC,MAAc,EAAE,SAAiB,EAAE,OAAqB;IAC9E,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,KAAK,kBAAkB;YACrB,OAAO,OAAO,CAAC,QAAQ,CAAC;QAC1B,KAAK,WAAW;YACd,OAAO,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,0BAA0B,CAAC;QAChE,KAAK,eAAe,CAAC,CAAC,CAAC;YACrB,IAAI,OAAO,CAAC,UAAU,KAAK,IAAI;gBAAE,OAAO,KAAK,CAAC;YAC9C,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,UAAU,GAAG,MAAM,CAAC,OAAO,GAAG,EAAE,GAAG,IAAI,CAAC;QACtE,CAAC;IACH,CAAC;AACH,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,YAAY,CAAC,OAAqB;IAChD,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IACxB,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAChC,OAAO,CAAC,0BAA0B,GAAG,IAAI,CAAC;AAC5C,CAAC;AAED;oFACoF;AACpF,MAAM,UAAU,aAAa,CAAC,MAAc,EAAE,OAAqB;IACjE,IAAI,MAAM,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;QAChC,OAAO,CAAC,0BAA0B,GAAG,KAAK,CAAC;IAC7C,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,64 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { FdkeyConfig, IVpsRouter, RoutingTarget } from './types.js';
+export type { FdkeyConfig, Policy, AgentMeta, IntegratorMeta, ChallengeMeta } from './types.js';
+/** @internal Test-only export. Not part of the supported public API;
+ *  may change or disappear without notice. Used by `index.test.ts` to
+ *  verify the lazy-import contract directly. */
+export { LazyVpsRouter as __LazyVpsRouterForTesting };
+/** Read-only context surfaced to integrator tool handlers. */
+export interface FdkeyContext {
+    verified: boolean;
+    verifiedAt: number | null;
+    /** Capability score from the most recent verification, in [0, 1].
+     *  Today this is effectively binary (1.0 = passed, 0.0 = failed); the
+     *  type signature reserves the float so future capability scoring
+     *  (combined T1 correctness + T3 tau + T4-T6 frequency) can land
+     *  without an API change. Null until first successful verify. */
+    score: number | null;
+    /** VPS-issued tier label from the most recent verification (e.g.
+     *  capability bucket the agent fell into). Null until first verify. */
+    tier: string | null;
+    /** Decoded JWT payload from the most recent verification. Includes
+     *  `score`, `tier`, `puzzle_summary`, etc. Null until first successful verify. */
+    claims: Record<string, unknown> | null;
+}
+/** Lazy wrapper around the multi-VPS `VpsRouter`. Defers `await import('./vps-router.js')`
+ *  until the first `getTarget()` call so Workers/Bun/Deno builds — which never hit this
+ *  path unless `discoveryUrl` is set — don't pull undici into the bundle.
+ *
+ *  If `undici` is not installed (it's an `optionalDependency`), the dynamic
+ *  import will fail. We catch that and rethrow with a clear, actionable
+ *  error so the integrator doesn't have to debug a `Cannot find module
+ *  'undici'` stack trace. */
+declare class LazyVpsRouter implements IVpsRouter {
+    private readonly discoveryUrl;
+    private inner;
+    constructor(discoveryUrl: string | undefined);
+    getTarget(): Promise<RoutingTarget>;
+    recordFailure(ip: string | undefined): void;
+}
+/** Read the current FDKEY context for a given session. Pass either the `extra`
+ *  argument from a tool handler or a session ID string. Returns null if the server
+ *  was not wrapped with withFdkey() or the session doesn't exist yet.
+ *
+ *  Reads use `store.peek()` which does NOT slide the LRU position — querying
+ *  the context shouldn't extend a session's lifetime; only actual tool calls
+ *  do that. */
+export declare function getFdkeyContext(server: McpServer, extraOrSessionId: {
+    sessionId?: string;
+} | string | undefined): FdkeyContext | null;
+/**
+ * Wraps an MCP server with FDKEY verification middleware.
+ *
+ * @example
+ * const server = withFdkey(new McpServer({ name: 'my-server', version: '1.0.0' }), {
+ *   apiKey: process.env.FDKEY_API_KEY!,
+ *   protect: {
+ *     login:    { policy: 'each_call' },
+ *     register: { policy: 'once_per_session' },
+ *   },
+ * });
+ * server.registerTool('login', { inputSchema: { username: z.string() } }, async (args) => { ... });
+ */
+export declare function withFdkey(server: McpServer, config: FdkeyConfig): McpServer;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EACV,WAAW,EAKX,UAAU,EACV,aAAa,EACd,MAAM,YAAY,CAAC;AAQpB,YAAY,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhG;;gDAEgD;AAChD,OAAO,EAAE,aAAa,IAAI,yBAAyB,EAAE,CAAC;AAWtD,8DAA8D;AAC9D,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B;;;;qEAIiE;IACjE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB;2EACuE;IACvE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB;sFACkF;IAClF,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CACxC;AAED;;;;;;;6BAO6B;AAC7B,cAAM,aAAc,YAAW,UAAU;IAE3B,OAAO,CAAC,QAAQ,CAAC,YAAY;IADzC,OAAO,CAAC,KAAK,CAA2B;gBACX,YAAY,EAAE,MAAM,GAAG,SAAS;IACvD,SAAS,IAAI,OAAO,CAAC,aAAa,CAAC;IA4BzC,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;CAG5C;AAMD;;;;;;eAMe;AACf,wBAAgB,eAAe,CAC7B,MAAM,EAAE,SAAS,EACjB,gBAAgB,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,GAAG,SAAS,GAC5D,YAAY,GAAG,IAAI,CAgBrB;AA+CD;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,GAAG,SAAS,CA+U3E"}