@markmnl/fmsg-mcp 0.1.3 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+## 0.2.0 (unreleased)
+
+This is the next planned release; publication still happens through a `v0.2.0` GitHub release.
+
+### Breaking changes
+
+- `download_attachment` no longer accepts `save_to` or returns `saved_to`. It is read-only. Enable
+  the separate stdio-only `save_attachment` tool with `FMSG_MCP_DOWNLOAD_DIR` for direct streaming
+  to generated filenames; it never accepts a destination path or overwrites an existing file.
+- Non-loopback HTTP binds require `FMSG_MCP_ALLOWED_HOSTS`. Browser origin entries must include
+  scheme and port. Loopback browser origins work automatically on loopback binds unless an explicit
+  list is set.
+- Upstream API URLs require HTTPS outside loopback unless `FMSG_ALLOW_INSECURE_HTTP=1` explicitly
+  enables a trusted private development network. Authenticated redirects are refused.
+- Text attachments return readable text; images return one image block rather than also duplicating
+  the image in an embedded resource. The default inline budget is 256 KiB; callers can raise it explicitly.
+
+### Fixes and improvements
+
+- Add opt-in, vendor-neutral HTTP OAuth with protected-resource discovery, signed JWT validation,
+  per-tool scopes and authenticated RFC 8693 exchange. Isolate caches per incoming token, cap
+  upstream credentials at five minutes and reconnect waits on expiry. Preserve API-key mode.
+  Deployed IdP and actual hosted-client acceptance remain rollout checks.
+
+- Accept caller-bound `TokenProvider` implementations in the client library alongside API keys.
+  Share renewal across concurrent requests, pin the address, bound acquisition time, and propagate
+  cancellation. Cap early renewal for short-lived tokens and reuse renewal after late 401 responses.
+  This provides the credential lifecycle used by API keys and HTTP OAuth.
+- Retry protected reads when a WebSocket announces a message before it is readable. If retries run
+  out, schedule a delayed inbox catch-up without requiring another push. Fix pre-cancelled waits
+  and preserve request deadlines.
+- Stream attachment bodies with an idle timeout instead of a total download deadline. Repeated saves
+  create numbered files without overwriting. Registry metadata lists the optional download folder.
+- Deduplicate token exchanges and close evicted/invalidated clients once active requests finish.
+  Request identity survives cache eviction and SDK cloning of authentication metadata.
+- Keep each message body fenced separately from its escaped header, and server guidance outside
+  the data. Clarify authorized conversation behavior and restore reversible/idempotent reaction annotations.
+- Bound inline attachment reads and error previews while streaming. Preserve the host's canonical
+  JSON 400/413 policy explanations and per-recipient delivery codes, except selected secret redaction.
+- Surface invalid stdio configuration through discoverable tools with corrective guidance.
+- `FmsgClient.send()` reports `redactions` and the transmitted `topic`; selected credential formats
+  in bodies/topics are replaced once at the client boundary. Attachments remain unchanged.
+- Custom HTTP adapters using `ApiKeyCallerProvider` must call `release(authInfo)` when each verified
+  request finishes; the built-in HTTP adapter handles this automatically.
+
+Messaging permissions and quotas remain in fmsg-webapi. No additional MCP messaging approval flow
+is introduced. See [GitHub releases](https://github.com/markmnl/fmsg-mcp/releases) for earlier notes.

package/README.md

@@ -7,16 +7,19 @@
 An [MCP](https://modelcontextprotocol.io) server that gives any AI agent its own
 [fmsg](https://github.com/markmnl/fmsg) address: send messages, follow threads, react, exchange
 attachments and wait for replies, through a deployed
-[fmsg Web API](https://github.com/markmnl/fmsg-webapi). Works with Claude Code, Claude Desktop,
-Cursor, VS Code, claude.ai remote connectors and any other MCP host.
+[fmsg Web API](https://github.com/markmnl/fmsg-webapi). Connect through stdio in hosts such as
+Claude Code, Claude Desktop, Cursor and VS Code, or through HTTP using API-key headers or configured OAuth.
 
 - **stdio** for local hosts: one address per server process, configured by two environment variables.
 - **Streamable HTTP** for shared or remote deployments: one endpoint serving many users, each
-  authenticated by their own fmsg API key.
+  authenticated by their own fmsg API key or OAuth connection.
 - The fmsg Web API client is exported for reuse: `import { FmsgClient } from "@markmnl/fmsg-mcp/client"`.
 
 ## 1. Get an fmsg address and API key
 
+Connecting to an existing OAuth-enabled endpoint? Add its MCP URL to your host and sign in;
+you can skip the API-key setup below. Operators can enable this with [HTTP OAuth](docs/oauth.md).
+
 You send as an fmsg address, authenticated by an API key (`fmsgk_…`) issued by your fmsg host:
 
 - **No host yet?** Create an account at a public fmsg host such as [fmsg.io](https://fmsg.io) and
@@ -65,18 +68,36 @@ Run one server for many users. Each client sends **its own** fmsg API key as a b
 server exchanges it at the fmsg host and acts as that address. `FMSG_API_KEY` must not be set.
 
 ```sh
-FMSG_API_URL=https://api.example.com npx -y @markmnl/fmsg-mcp --http 0.0.0.0:8765
+FMSG_API_URL=https://api.example.com FMSG_MCP_ALLOWED_HOSTS=mcp.example.com \
+  npx -y @markmnl/fmsg-mcp --http 0.0.0.0:8765
 # or
-docker build -t fmsg-mcp . && docker run -e FMSG_API_URL=https://api.example.com -p 8765:8765 fmsg-mcp
+docker build -t fmsg-mcp .
+docker run -e FMSG_API_URL=https://api.example.com \
+  -e FMSG_MCP_ALLOWED_HOSTS=mcp.example.com -p 8765:8765 fmsg-mcp
 ```
 
-The MCP endpoint is `/mcp`; `/healthz` reports liveness. Point a host at it with
-`Authorization: Bearer fmsgk_...` — for claude.ai, add a custom connector with that URL and header;
-for Claude Code, `claude mcp add --transport http fmsg https://mcp.example.com/mcp --header "Authorization: Bearer fmsgk_..."`.
+The MCP endpoint is `/mcp`; `/healthz` reports liveness. Use a client that supports an explicitly
+configured `Authorization: Bearer fmsgk_...` header. Each caller supplies its own key; a shared
+header means a shared fmsg identity. For browser sign-in without user API keys, configure
+[HTTP OAuth](docs/oauth.md): the operator supplies an issuer, resource URI and exchange client.
+Users add the public MCP URL in a host supporting that issuer's client registration method.
+
+For [Claude Code over HTTP](https://code.claude.com/docs/en/mcp):
+
+```sh
+claude mcp add --transport http fmsg --scope user https://mcp.example.com/mcp \
+  --header "Authorization: Bearer fmsgk_..."
+```
 
 Deploy behind a TLS-terminating reverse proxy and set `FMSG_MCP_ALLOWED_HOSTS` to the public hostname
-when binding to a non-loopback address. `wait_for_message` holds a request open for up to
+when binding to a non-loopback address; startup fails without it. Browser clients on another origin
+also need `FMSG_MCP_ALLOWED_ORIGINS` containing exact origins, such as `https://app.example.com`.
+For loopback binds, loopback browser origins on any port work by default, including MCP Inspector
+at `http://localhost:6274`. Setting an explicit origin list replaces that loopback default.
+Allowed preflights need no credentials; actual MCP requests always require authentication.
+`wait_for_message` holds a request open for up to
 `FMSG_MCP_WAIT_MAX_SECONDS` (230), so give the proxy an idle timeout of at least 240 s.
+See the [TLS reverse-proxy example](docs/http-deployment.md) for a loopback deployment with Caddy.
 
 ## Tools
 
@@ -93,7 +114,8 @@ when binding to a non-loopback address. `wait_for_message` holds a request open
 | `add_recipients` | Add recipients to a sent message |
 | `react` | Set or clear your emoji reaction |
 | `mark_read` | Mark received messages read |
-| `download_attachment` | Fetch an attachment inline (base64, images as image blocks) or, over stdio, save it to disk |
+| `download_attachment` | Fetch a small attachment inline: text as text, images as image blocks, other files as base64 resources |
+| `save_attachment` | Stream an attachment to the configured local folder; stdio only, enabled by `FMSG_MCP_DOWNLOAD_DIR` |
 | `delivery_status` | Per-recipient delivery times and host response codes |
 | `wait_for_message` | Block until the next inbound message (WebSocket push), batched per thread, with thread context |
 
@@ -109,30 +131,52 @@ attach resources; prompts `chat` and `reply` script the wait → reply loop and
 |---|---|---|
 | `FMSG_API_URL` | — | Base URL of the fmsg Web API (required) |
 | `FMSG_API_KEY` | — | `fmsgk_…` key; stdio mode only |
+| `FMSG_MCP_AUTH_MODE` | `api-key` | HTTP authentication: `api-key` or `oauth`; see [OAuth settings](docs/oauth.md#operator-configuration) |
+| `FMSG_ALLOW_INSECURE_HTTP` | disabled | Set to `1` only to permit cleartext API access on a trusted development/private network; loopback HTTP is allowed by default |
 | `FMSG_DEFAULT_DOMAIN` | — | Lets short names resolve: `bob` → `@bob@<domain>` |
 | `FMSG_DIRECTORY` | — | JSON file mapping short names to full addresses |
+| `FMSG_MCP_DOWNLOAD_DIR` | — | Enable `save_attachment` in stdio; folder for new files named from message ID and filename |
 | `FMSG_MCP_WAIT_MAX_SECONDS` | `230` | Cap on one `wait_for_message` call |
-| `FMSG_MCP_DOWNLOAD_DIR` | — | Restrict `download_attachment` `save_to` to this directory (stdio) |
 | `FMSG_MCP_HOST` / `FMSG_MCP_PORT` | `127.0.0.1` / `8765` | HTTP bind address (or `--http host:port`) |
-| `FMSG_MCP_ALLOWED_HOSTS` | loopback names | Comma-separated `Host` header allowlist for HTTP mode |
-| `FMSG_MCP_ALLOWED_ORIGINS` | same as hosts | `Origin` allowlist for browser-based callers |
-| `FMSG_MCP_KEY_CACHE_MAX` / `FMSG_MCP_KEY_CACHE_TTL_SECONDS` | `500` / `1800` | HTTP mode per-key client cache |
+| `FMSG_MCP_ALLOWED_HOSTS` | loopback names | Comma-separated `Host` header allowlist; required for non-loopback binds |
+| `FMSG_MCP_ALLOWED_ORIGINS` | same origin; loopback origins on loopback binds | Comma-separated browser origins including scheme and port; an explicit list replaces the loopback default; hostname-only values are rejected |
+| `FMSG_MCP_KEY_CACHE_MAX` / `FMSG_MCP_KEY_CACHE_TTL_SECONDS` | `500` / `1800` | HTTP client cache bound; TTL applies only to API-key mode |
 
 The API key is exchanged for a short-lived access token that the server renews automatically.
+API URLs must not contain credentials, query strings or fragments. Authenticated requests do not
+follow redirects; configure the final API URL directly.
 
-Over stdio the server also starts with no credentials at all, so hosts and directories can list its tools; every tool call then returns a message naming the missing variables.
+To save attachments directly to disk, add `FMSG_MCP_DOWNLOAD_DIR` to your stdio server's environment,
+for example `/home/you/Downloads/fmsg`. The optional `save_attachment` tool streams files into that
+folder without sending their bytes through model context. It accepts only a message ID and attachment
+filename and creates a new file such as `123-report.pdf`. Repeat saves use `123-report-1.pdf`,
+`123-report-2.pdf`, etc., leaving existing files untouched. Unusual filenames are converted to
+portable names; use the returned `saved_to` path. Streaming downloads can run longer than 60 seconds
+while making progress; a 60-second idle timeout detects stalled transfers.
+
+Inline downloads default to 256 KiB to keep file content manageable for the model. Use
+`save_attachment` for larger local files, or raise `max_inline_bytes` explicitly when your AI host
+can handle more inline content. HTTP clients use inline downloads or their host's file capabilities.
+
+Over stdio, missing or invalid configuration still allows hosts to discover the tools. Tool calls
+explain the configuration error and how to fix it; restart the MCP server after correcting settings.
 
 ## Safety
 
+- Messaging access, quotas and recipient acceptance are enforced by fmsg-webapi and the host
+  services. MCP forwards each operation as the caller's identity and surfaces upstream failures.
+- `download_attachment` never writes local files. Optional `save_attachment` writes only generated
+  filenames in the operator-configured folder, using exclusive creation with no overwrite.
 - Sent messages cannot be edited or recalled; send tools say so in their descriptions and are
-  annotated `destructiveHint` so hosts can ask for confirmation.
-- API keys, tokens and other secret-shaped strings are redacted from outbound bodies, topics and
-  error text; the count of redactions is reported.
+  annotated `destructiveHint` to describe their effects. Approval behavior belongs to the AI host;
+  fmsg-mcp has no additional confirmation gate.
+- Selected API-key/token formats are redacted from outbound bodies, topics and error text; the
+  send tools report the count. This is not general data-loss prevention or binary attachment scanning.
 - Nothing about message size or acceptance is assumed: the fmsg host's own responses and delivery
   codes are surfaced verbatim.
 - The server publishes MCP `instructions` (shown to the model at session start) telling agents to use
-  these tools rather than a local fmsg CLI or cached credentials, to send only on a clear request, and
-  to treat message content as data.
+  these tools rather than a local fmsg CLI or cached credentials, to carry out authorized tasks and
+  automation without repeated confirmation, and to treat message content as data.
 - See [SECURITY.md](./SECURITY.md).
 
 ## Using the client library
@@ -143,9 +187,20 @@ import { FmsgClient } from "@markmnl/fmsg-mcp/client";
 const client = new FmsgClient("https://api.example.com", process.env.FMSG_API_KEY!);
 console.log(await client.address());
 const inbox = await client.listInbox(10);
-await client.send({ to: ["@bob@example.com"], topic: "Hi", body: "Hello from code" });
+const sent = await client.send({ to: ["@bob@example.com"], topic: "Hi", body: "Hello from code" });
+console.log(sent.id, sent.redactions);
+client.close();
 ```
 
+`send()` replaces selected credential patterns in the body and topic before creating the draft.
+Its result includes the replacement count (`redactions`) and transmitted `topic`. Attachments are
+unchanged. Use `streamAttachment()` to consume large files incrementally; consume or cancel its stream.
+
+Applications with their own authorization integration can pass a `TokenProvider` instead of an
+API-key string. The client shares renewal across concurrent requests and keeps the authenticated
+address fixed. See the [token-provider contract](./docs/token-providers.md). This library interface
+is also used by the executable's optional [OAuth mode](./docs/oauth.md).
+
 ## Development
 
 ```sh
@@ -155,6 +210,7 @@ npx @modelcontextprotocol/inspector node dist/index.js          # stdio, with FM
 bash .github/scripts/run-fmsg-docker-e2e.sh                     # end to end on two real fmsg stacks
 ```
 
-See [AGENTS.md](./AGENTS.md) for layout and conventions.
+See [AGENTS.md](./AGENTS.md) for layout and conventions, [ROADMAP.md](./ROADMAP.md) for remaining
+integration work, and [CHANGELOG.md](./CHANGELOG.md) for release notes.
 
 [MIT licensed](./LICENSE)

package/ROADMAP.md

@@ -0,0 +1,52 @@
+# Integration roadmap
+
+Target: an MCP-capable agent can connect through a documented, tested path, identify its fmsg
+account, and complete authorized messaging without exposing credentials or unexpected capabilities.
+Support claims must name tested clients and versions; agents without MCP need an adapter.
+
+## Constraints
+
+- fmsg-webapi and host services own messaging permissions, visibility, quotas and acceptance.
+  MCP binds each operation to its caller and surfaces upstream decisions.
+- Normal stdio setup requires only an HTTPS API URL and key. No second login, duplicate ACLs,
+  recipient policies or per-message confirmation gates. The AI host owns tool approval settings.
+- Keep authorized conversations and automation convenient. Incoming messages do not authorize
+  adding recipients, contacting new parties or disclosing other data.
+- Remove obsolete server API fields directly while there are no external consumers requiring
+  compatibility. Keep protocol compatibility needed by supported MCP hosts.
+
+## Implementation sequence
+
+| Work | Scope and completion criteria |
+|---|---|
+| A — MCP boundaries ([PR #2](https://github.com/markmnl/fmsg-mcp/pull/2)) | Separate read-only downloads from opt-in streamed saving; validate HTTP access; manage caller credentials and cancellation; preserve upstream authorization; frame untrusted content without obscuring server guidance. Regression and real-stack isolation tests cover these boundaries. |
+| B — Receive reliability | Scan backlogs to a safe cursor boundary, including bursts, pending batches, interleaved threads and reconnects. Never advance past unseen work. Bound stream reads, response assembly, concurrent waits and overall deadlines. |
+| C — Action outcomes | Preserve upstream denials and delivery codes. Return a durable reference and recovery guidance when a send may have committed but its response was lost; coordinate idempotency with the upstream API. |
+| D — Painless local integration | Add a non-sending doctor command, separate host recipes and a versioned compatibility matrix. Verify wait defaults, attachment save/upload workflows, independent Python clients, conformance, supported OSes and clean installation of the actual npm tarball. |
+| E — Hosted OAuth | Provider-neutral discovery, account linkage, consent, token refresh and revocation, coordinated with the host/account system. Prove per-user isolation in actual hosted clients. Retain explicit API-key integration. |
+| F — Release trust and operations | Synchronize the existing MCP Registry listing after npm publication; verify the published version. Harden release inputs and gates, reusing D's artifact checks. Add deployment metrics, runbooks, load testing and independent review when supporting shared hosted service. |
+
+Ship A first, then B–D. Plan E with the host/account-system maintainer. Release work in F can proceed
+earlier; hosted-service promises depend on verified OAuth and operational behavior.
+
+E's [HTTP OAuth implementation](docs/oauth.md) includes discovery, incoming JWT validation, tool
+scopes, token exchange, isolated renewal and expiring-socket reconnects. Local signed-token tests
+cover these boundaries. Deployed IdP/Web API and hosted-client acceptance remain open. The Web API
+must enforce delegated scopes and closed owner routes before OAuth is enabled; messaging
+credentials must not inherit owner credential-management privileges.
+
+Release-triggered npm publication, OIDC trusted publishing, provenance generation and version
+synchronization already exist in [publish.yml](.github/workflows/publish.yml). Preserve them.
+[CI](https://github.com/markmnl/fmsg-mcp/actions/workflows/tests.yml) already covers Node 22/24,
+the Docker image and real two-host acceptance. PR checks record validation for each revision.
+
+## Broad-integration release criteria
+
+- Fresh installs on every claimed client/OS reach `whoami` and inbox using the documented setup.
+- Caller isolation and upstream authorization hold across tools, resources, attachments and waits.
+- Backlog/reconnect tests prove no silent cursor loss; cancellation releases work promptly.
+- Tool deadlines and payload budgets fit verified host configurations; large files are practical
+  without manual base64 handling or overflowing model context.
+- Ambiguous sends have a documented reconciliation path that avoids blind duplicate sends.
+- Advertised hosted integrations pass identity, refresh, revocation and disconnect checks.
+- The npm artifact, registry metadata, release notes and compatibility results agree.

package/SECURITY.md

@@ -0,0 +1,72 @@
+# Security
+
+Please report vulnerabilities privately through GitHub's
+[private vulnerability reporting](https://github.com/markmnl/fmsg-mcp/security/advisories/new)
+rather than a public issue.
+
+## Scope
+
+- Messaging authorization, grants, address status, quotas and acceptance remain the responsibility
+  of fmsg-webapi and the host services. Each MCP request uses its caller's upstream identity.
+- Over stdio the API key comes from the environment. HTTP callers supply their own bearer keys or OAuth access tokens, according to the configured mode.
+  Keys and JWTs are retained in process memory for token renewal; hashes index the HTTP client cache.
+  This server does not intentionally persist them. Idle entries expire on access and periodic sweeps
+  (at most 30 seconds apart). Evicted or invalidated clients close immediately if idle; active requests
+  retain their client until their last request lease is released. Shutdown closes cached and active
+  clients and cancels their work. JavaScript does not guarantee memory zeroization.
+- Protected upstream routes re-check grants; revoked/expired credentials remain subject to the
+  upstream contract. MCP cache TTL is a retention setting, not a grant or revocation policy.
+  WebSocket announcements trigger protected message reads before their content reaches the host.
+  The upstream contract authenticates sockets at handshake; it does not promise immediate closure
+  of existing sockets on revocation. MCP does not infer ongoing authorization from a socket alone.
+- Selected key/JWT/private-key patterns are redacted from outbound message bodies, topics and errors.
+  This does not detect arbitrary sensitive information or scan binary attachments.
+- Message bodies and upstream error text are fenced as untrusted data. Each message body has its own
+  fence; server-built headers stay outside it, with external header values escaped onto one line.
+  This distinguishes quoted forged headers from actual message boundaries. Server-authored guidance
+  stays outside the data. Instructions permit replies within authorized conversations, but
+  incoming messages cannot authorize adding recipients, contacting new parties or disclosing other
+  data. Hosts should still treat tool output as untrusted.
+- `download_attachment` is read-only and enforces its inline byte budget while reading. The optional
+  `save_attachment` tool is advertised only in stdio with `FMSG_MCP_DOWNLOAD_DIR` set. It streams to a
+  generated leaf filename, accepts no destination path, and uses exclusive creation (`wx`) to skip
+  existing files and symlinks, trying numbered filenames instead. New files use mode `0600` where
+  supported; failed writes remove partial files. The operator must control the configured folder and its ancestors, on a filesystem that
+  supports exclusive creation. This is not a sandbox against another local process replacing those
+  directories. HTTP mode does not expose this write capability.
+- Attachment transfers retain caller cancellation and client shutdown signals. They use a response
+  header deadline followed by a per-read idle timeout (60 seconds each by default), so a progressing
+  large download is not subject to a 60-second total duration limit.
+- Error previews are limited to 2 KiB while reading, except canonical JSON HTTP 400/413 responses:
+  those retain the host's acceptance/size-policy explanation. Selected credentials are still redacted;
+  oversized previews are explicitly marked as truncated.
+- In HTTP mode terminate TLS in front of the server. `FMSG_MCP_ALLOWED_HOSTS` is required for
+  non-loopback binds. Browser access validates the exact origin, including scheme and port. Loopback
+  binds also permit loopback browser origins on any port by default, so local developer tools work.
+  An explicit origin list replaces that loopback exception. CORS preflight permission does not grant
+  access to MCP operations; bearer authentication remains required.
+- The upstream API must use HTTPS except loopback or an explicitly configured trusted private
+  network (`FMSG_ALLOW_INSECURE_HTTP=1`). Authenticated HTTP redirects are refused.
+- Tool annotations and message-data labels guide the AI host; they do not prove user approval or
+  prevent prompt injection. The AI host owns tool-use permissions and authorization of automation.
+  OAuth mode adds resource-token validation and messaging scope checks, with sign-in/consent at
+  the configured authorization server. fmsg-mcp adds no recipient ACL, approval gate or per-message
+  confirmation requirement. Normal stdio setup needs only an HTTPS API URL and API key; token renewal and cache
+  management run automatically. Guidance permits ongoing work within the user's authorized task or
+  automation, subject to the AI host's own approval settings.
+
+## OAuth boundary
+
+OAuth mode validates the configured issuer, exact MCP audience, EdDSA signature, key ID,
+`at+jwt` type, lifetime and address. Only the configured issuer's discovered JWKS is trusted.
+Incoming tokens are exchanged with confidential-client authentication and are never forwarded
+to the Web API. No `X-FMSG-Act-As` header is sent. The Web API must enforce delegated scopes
+and refuse owner-only routes independently of this server.
+
+Exchanged tokens are cached per incoming token for at most five minutes and never past either
+token's expiry. Existing sockets close and renew within that deadline. Incoming tokens validate
+offline until expiry; immediate revocation is checked at exchange. No local cache makes
+revocation immediate or shortens the lifetime of a copied token at another service. See the
+[OAuth contract and revocation limits](docs/oauth.md#exchange-renewal-and-revocation).
+
+When reporting, please remove API keys, tokens, addresses and message bodies from logs.

package/dist/auth.d.ts

@@ -2,20 +2,28 @@ import { type AuthInfo, type OAuthTokenVerifier } from "@modelcontextprotocol/se
 import type { Config } from "./config.js";
 import type { Caller, CallerProvider } from "./context.js";
 export declare const FMSG_SCOPE = "fmsg";
-/**
- * HTTP mode: each request carries an fmsg API key as its bearer token. The key
- * is exchanged once at the fmsg host, and the resulting client (which renews
- * its own JWT) is cached by the key's hash. Raw keys are never stored or logged.
- */
+/** Per-key clients retain credentials for renewal; upstream decides access. */
 export declare class ApiKeyCallerProvider implements CallerProvider, OAuthTokenVerifier {
     private readonly config;
     private readonly log;
     private readonly entries;
+    private readonly pending;
+    private readonly pendingClients;
+    private readonly leases;
+    private readonly timer;
+    private closed;
     constructor(config: Config, log?: (line: string) => void);
     static cacheKey(apiKey: string): string;
+    private releaseEntry;
+    private drop;
     private evict;
-    /** Bearer verifier for the MCP gate: exchange the key, return the caller's identity. */
+    private createEntry;
     verifyAccessToken(token: string): Promise<AuthInfo>;
+    private entryFor;
     forRequest(authInfo: AuthInfo | undefined): Promise<Caller>;
+    /** The HTTP adapter releases this lease when the response or connection ends. */
+    release(authInfo: AuthInfo): void;
+    invalidate(caller: Caller): void;
+    close(): void;
     get size(): number;
 }

package/dist/auth.js

@@ -1,84 +1,150 @@
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { OAuthError, OAuthErrorCode } from "@modelcontextprotocol/server";
 import { FmsgClient, FmsgHttpError } from "./client/client.js";
+import { safeErrorMessage } from "./client/redact.js";
 export const FMSG_SCOPE = "fmsg";
-/**
- * HTTP mode: each request carries an fmsg API key as its bearer token. The key
- * is exchanged once at the fmsg host, and the resulting client (which renews
- * its own JWT) is cached by the key's hash. Raw keys are never stored or logged.
- */
+/** Per-key clients retain credentials for renewal; upstream decides access. */
 export class ApiKeyCallerProvider {
     config;
     log;
     entries = new Map();
+    pending = new Map();
+    pendingClients = new Set();
+    // An opaque request lease survives SDK cloning and pins the caller across eviction.
+    leases = new Map();
+    timer;
+    closed = false;
     constructor(config, log = () => undefined) {
         this.config = config;
         this.log = log;
+        this.timer = setInterval(() => this.evict(), Math.min(config.http.keyCacheTtlMs, 30_000)).unref();
     }
-    static cacheKey(apiKey) {
-        return createHash("sha256").update(apiKey).digest("hex");
+    static cacheKey(apiKey) { return createHash("sha256").update(apiKey).digest("hex"); }
+    releaseEntry(entry) {
+        if (!entry.active && this.entries.get(entry.key) !== entry)
+            entry.caller.client.close();
+    }
+    drop(entry) {
+        if (this.entries.get(entry.key) === entry)
+            this.entries.delete(entry.key);
+        this.releaseEntry(entry);
     }
     evict() {
         const now = Date.now();
-        for (const [key, entry] of this.entries) {
-            if (now - entry.lastUsed > this.config.http.keyCacheTtlMs)
-                this.entries.delete(key);
+        for (const entry of this.entries.values()) {
+            if (now - entry.lastUsed >= this.config.http.keyCacheTtlMs)
+                this.drop(entry);
         }
         while (this.entries.size > this.config.http.keyCacheMax) {
-            const oldest = [...this.entries.entries()].sort((a, b) => a[1].lastUsed - b[1].lastUsed)[0];
+            const oldest = [...this.entries.values()].sort((a, b) => a.lastUsed - b.lastUsed)[0];
             if (!oldest)
                 break;
-            this.entries.delete(oldest[0]);
+            this.drop(oldest);
+        }
+    }
+    async createEntry(token, key) {
+        const client = new FmsgClient(this.config.apiUrl, token, { allowInsecureHttp: this.config.allowInsecureHttp });
+        this.pendingClients.add(client);
+        try {
+            const address = await client.address();
+            if (this.closed)
+                throw new Error("server is closing");
+            const entry = { key, caller: { client, address, tokenExpiresAt: async () => (await client.getToken()).expiresAtMs }, lastUsed: Date.now(), active: 0 };
+            this.entries.set(key, entry);
+            this.log(safeErrorMessage(`authenticated ${address} (key ${key.slice(0, 8)}…)`));
+            return entry;
+        }
+        catch (error) {
+            client.close();
+            throw error;
+        }
+        finally {
+            this.pendingClients.delete(client);
         }
     }
-    /** Bearer verifier for the MCP gate: exchange the key, return the caller's identity. */
     async verifyAccessToken(token) {
-        if (!token.startsWith("fmsgk_")) {
+        if (this.closed)
+            throw new OAuthError(OAuthErrorCode.ServerError, "server is closing");
+        if (!token.startsWith("fmsgk_"))
             throw new OAuthError(OAuthErrorCode.InvalidToken, "bearer token must be an fmsg API key (fmsgk_...)");
-        }
         const key = ApiKeyCallerProvider.cacheKey(token);
-        let entry = this.entries.get(key);
-        if (!entry) {
-            const client = new FmsgClient(this.config.apiUrl, token);
-            let address;
-            try {
-                address = await client.address();
-            }
-            catch (error) {
-                if (error instanceof FmsgHttpError && (error.status === 401 || error.status === 403 || error.status === 400)) {
-                    this.log(`rejected api key ${key.slice(0, 8)}…: ${error.status} ${error.message}`);
-                    throw new OAuthError(OAuthErrorCode.InvalidToken, `fmsg host rejected the API key: ${error.message}`);
+        this.evict();
+        let entry;
+        try {
+            entry = this.entries.get(key);
+            if (!entry) {
+                let pending = this.pending.get(key);
+                if (!pending) {
+                    if (this.pending.size >= this.config.http.keyCacheMax)
+                        throw new Error("too many concurrent token exchanges");
+                    pending = this.createEntry(token, key);
+                    this.pending.set(key, pending);
+                    void pending.finally(() => this.pending.delete(key)).catch(() => undefined);
                 }
-                this.log(`token exchange failed for ${key.slice(0, 8)}…: ${error instanceof Error ? error.message : String(error)}`);
-                throw new OAuthError(OAuthErrorCode.ServerError, "fmsg host unavailable for token exchange");
+                entry = await pending;
             }
-            entry = {
-                caller: { client, address, tokenExpiresAt: async () => (await client.getToken()).expiresAtMs },
-                lastUsed: Date.now(),
-            };
-            this.entries.set(key, entry);
+            entry.active++;
+            entry.lastUsed = Date.now();
             this.evict();
-            this.log(`authenticated ${address} (key ${key.slice(0, 8)}…)`);
+            const expiresAtMs = await entry.caller.tokenExpiresAt();
+            if (this.closed)
+                throw new Error("server is closing");
+            const lease = randomUUID();
+            this.leases.set(lease, entry);
+            return {
+                token: key, clientId: entry.caller.address, scopes: [FMSG_SCOPE],
+                expiresAt: Math.floor(expiresAtMs / 1000), extra: { cacheKey: key, callerLease: lease },
+            };
+        }
+        catch (error) {
+            if (entry) {
+                entry.active--;
+                this.drop(entry);
+            }
+            this.log(safeErrorMessage(`token exchange failed for ${key.slice(0, 8)}…: ${error instanceof Error ? error.message : String(error)}`));
+            if (error instanceof FmsgHttpError && [400, 401, 403].includes(error.status)) {
+                throw new OAuthError(OAuthErrorCode.InvalidToken, `fmsg host rejected the API key: ${safeErrorMessage(error)}`);
+            }
+            throw new OAuthError(OAuthErrorCode.ServerError, "fmsg host unavailable for token exchange");
         }
-        entry.lastUsed = Date.now();
-        const expiresAtMs = await entry.caller.tokenExpiresAt();
-        return {
-            token: key,
-            clientId: entry.caller.address,
-            scopes: [FMSG_SCOPE],
-            expiresAt: Math.floor(expiresAtMs / 1000),
-            extra: { cacheKey: key },
-        };
+    }
+    entryFor(auth) {
+        const lease = auth?.extra?.callerLease;
+        const entry = typeof lease === "string" ? this.leases.get(lease) : undefined;
+        return entry && auth?.token === entry.key && auth.extra?.cacheKey === entry.key &&
+            auth.clientId === entry.caller.address && auth.scopes.includes(FMSG_SCOPE) ? entry : undefined;
     }
     async forRequest(authInfo) {
-        const key = typeof authInfo?.extra?.cacheKey === "string" ? authInfo.extra.cacheKey : authInfo?.token;
-        const entry = key ? this.entries.get(key) : undefined;
-        if (!entry)
+        const entry = this.entryFor(authInfo);
+        if (this.closed || !entry)
             throw new Error("not authenticated: send your fmsg API key as `Authorization: Bearer fmsgk_...`");
         entry.lastUsed = Date.now();
         return entry.caller;
     }
-    get size() {
-        return this.entries.size;
+    /** The HTTP adapter releases this lease when the response or connection ends. */
+    release(authInfo) {
+        const entry = this.entryFor(authInfo);
+        if (!entry)
+            return;
+        this.leases.delete(authInfo.extra.callerLease);
+        entry.active--;
+        this.releaseEntry(entry);
+    }
+    invalidate(caller) {
+        for (const entry of this.entries.values())
+            if (entry.caller === caller)
+                this.drop(entry);
+    }
+    close() {
+        this.closed = true;
+        clearInterval(this.timer);
+        for (const entry of [...this.entries.values(), ...this.leases.values()])
+            entry.caller.client.close();
+        for (const client of this.pendingClients)
+            client.close();
+        this.entries.clear();
+        this.leases.clear();
+        this.pending.clear();
     }
+    get size() { return this.entries.size; }
 }