@markmnl/fmsg-mcp 0.1.4 → 0.2.1

package/dist/wait.js

@@ -1,10 +1,15 @@
+import { setTimeout as delay } from "node:timers/promises";
+import { FmsgHttpError } from "./client/client.js";
 import { compareMessageIds, maxMessageId, minMessageId } from "./client/message-id.js";
-import { openFmsgWebSocket, parseWsEvent } from "./client/ws.js";
+import { safeErrorMessage } from "./client/redact.js";
+import { openFmsgWebSocket, parseWsEvent, webSocketTokenExpiresAt } from "./client/ws.js";
+import { OAuthRequestError } from "./oauth/errors.js";
 /**
  * Block until the next qualifying inbound message (plus any that arrive on the
  * same thread within the settle window), or until the deadline.
  */
 export async function waitForMessage(client, self, options, signal, deps = {}) {
+    signal?.throwIfAborted();
     const start = Date.now();
     const deadline = start + options.timeoutMs;
     const maxBatch = options.maxBatch ?? 20;
@@ -19,16 +24,35 @@ export async function waitForMessage(client, self, options, signal, deps = {}) {
     }
     let skippedMax = floor;
     let finished = false;
+    const retryStop = new AbortController();
+    const retrySignal = signal ? AbortSignal.any([signal, retryStop.signal]) : retryStop.signal;
+    const authorizationFailure = (error) => error instanceof OAuthRequestError || (error instanceof FmsgHttpError &&
+        ([401, 403].includes(error.status) || error.path === "/fmsg/token"));
+    const retryRead = async (read, attempts = 3) => {
+        for (let attempt = 0;; attempt++) {
+            retrySignal.throwIfAborted();
+            try {
+                return await read();
+            }
+            catch (error) {
+                if (authorizationFailure(error) || attempt + 1 >= attempts)
+                    throw error;
+                await delay(400 * (attempt + 1), undefined, { signal: retrySignal });
+            }
+        }
+    };
     const rootCache = new Map();
     const lookupRoot = async (id) => {
         try {
-            return (await client.getThreadMessages(id, signal)).root_id;
+            return (await client.getThreadMessages(id, retrySignal)).root_id;
         }
         catch (error) {
+            if (authorizationFailure(error))
+                throw error;
             // Fall back to a bounded pid walk; any failure here propagates as "unknown".
             let cur = id;
             for (let i = 0; i < 100; i++) {
-                const m = await client.getMessage(cur, signal);
+                const m = await client.getMessage(cur, retrySignal);
                 if (!m.pid)
                     return m.id;
                 cur = m.pid;
@@ -46,29 +70,18 @@ export async function waitForMessage(client, self, options, signal, deps = {}) {
         const cached = rootCache.get(id);
         if (cached !== undefined)
             return cached;
-        let lastError;
-        for (let i = 0; i < attempts; i++) {
-            if (signal?.aborted || finished)
-                break;
-            try {
-                const root = await lookupRoot(id);
-                rootCache.set(id, root);
-                return root;
-            }
-            catch (error) {
-                lastError = error;
-                if (i + 1 < attempts)
-                    await new Promise((r) => setTimeout(r, 400 * (i + 1)));
-            }
-        }
-        throw lastError instanceof Error ? lastError : new Error(String(lastError));
+        const root = await retryRead(() => lookupRoot(id), attempts);
+        rootCache.set(id, root);
+        return root;
     };
     let targetRoot;
     if (options.threadOf) {
         try {
             targetRoot = await rootOf(options.threadOf, 1);
         }
-        catch {
+        catch (error) {
+            if (authorizationFailure(error))
+                throw error;
             throw new Error(`could not determine the thread of message ${options.threadOf}`);
         }
     }
@@ -85,23 +98,32 @@ export async function waitForMessage(client, self, options, signal, deps = {}) {
     let socket;
     let pollTimer;
     let settleTimer;
+    let recoveryTimer;
+    let openTimer;
+    let expiryTimer;
+    let reconnectTimer;
+    let reconnectDelay = 1000;
+    const disposeSocket = (ws) => {
+        ws.removeAllListeners();
+        // terminate/close during CONNECTING can emit an asynchronous error.
+        ws.on("error", () => undefined);
+        ws.terminate();
+    };
     return new Promise((resolve, reject) => {
         const cleanup = () => {
             finished = true;
+            retryStop.abort();
             clearTimeout(deadlineTimer);
             clearTimeout(settleTimer);
+            clearTimeout(recoveryTimer);
+            clearTimeout(openTimer);
+            clearTimeout(expiryTimer);
+            clearTimeout(reconnectTimer);
             clearInterval(pollTimer);
             clearInterval(tickTimer);
             signal?.removeEventListener("abort", onAbort);
-            if (socket) {
-                socket.removeAllListeners();
-                try {
-                    socket.close();
-                }
-                catch {
-                    /* ignore */
-                }
-            }
+            if (socket)
+                disposeSocket(socket);
         };
         const finish = () => {
             if (finished)
@@ -143,19 +165,22 @@ export async function waitForMessage(client, self, options, signal, deps = {}) {
             note = "cancelled";
             finish();
         };
-        signal?.addEventListener("abort", onAbort, { once: true });
-        if (signal?.aborted)
-            return onAbort();
         const deadlineTimer = setTimeout(() => {
             if (batch.length && settleTimer)
                 note = "the time limit cut the settle window short";
             finish();
         }, Math.max(0, deadline - Date.now()));
         const tickTimer = setInterval(() => options.onTick?.(Date.now() - start), 20_000);
+        signal?.addEventListener("abort", onAbort, { once: true });
+        if (signal?.aborted)
+            return onAbort();
         const consider = async (m) => {
             if (finished || seen.has(m.id))
                 return;
             seen.add(m.id);
+            for (let i = unclassified.length - 1; i >= 0; i--)
+                if (unclassified[i]?.id === m.id)
+                    unclassified.splice(i, 1);
             if (compareMessageIds(m.id, floor) <= 0)
                 return;
             const skip = (reason) => {
@@ -177,8 +202,10 @@ export async function waitForMessage(client, self, options, signal, deps = {}) {
                 root = await rootOf(m.id);
             }
             catch (error) {
+                if (authorizationFailure(error))
+                    return fail(error);
                 if (!finished)
-                    unclassified.push({ id: m.id, from: m.from, error: error instanceof Error ? error.message : String(error) });
+                    unclassified.push({ id: m.id, from: m.from, error: safeErrorMessage(error) });
                 return;
             }
             finally {
@@ -204,8 +231,10 @@ export async function waitForMessage(client, self, options, signal, deps = {}) {
             pending.push({ id: m.id, from: m.from, root_id: root });
         };
         const catchUp = async () => {
+            if (finished)
+                return;
             try {
-                const page = await client.listInbox(100, 0, signal);
+                const page = await client.listInbox(100, 0, retrySignal);
                 for (const m of [...page].reverse())
                     await consider(m);
             }
@@ -222,43 +251,108 @@ export async function waitForMessage(client, self, options, signal, deps = {}) {
             pollTimer = setInterval(() => void catchUp(), pollIntervalMs);
             void catchUp();
         };
-        const open = deps.openSocket ?? openFmsgWebSocket;
-        open(client)
-            .then((ws) => {
-            if (finished) {
-                ws.close();
+        const considerPushed = async (id) => {
+            if (finished || seen.has(id) || inflight.has(id))
                 return;
+            inflight.set(id, "");
+            try {
+                // A socket was authorized at its handshake. Re-read through a protected
+                // route so an old connection cannot bypass upstream grant revocation.
+                const message = await retryRead(() => client.getMessage(id, retrySignal));
+                inflight.delete(id);
+                await consider(message);
+            }
+            catch (error) {
+                if (finished)
+                    return;
+                if (authorizationFailure(error)) {
+                    fail(error);
+                }
+                else {
+                    if (!unclassified.some(item => item.id === id))
+                        unclassified.push({ id, from: "", error: safeErrorMessage(error) });
+                    // Coalesce exhausted reads into one delayed inbox check; a second
+                    // announcement is not required to recover an early push.
+                    recoveryTimer ??= setTimeout(() => {
+                        recoveryTimer = undefined;
+                        void catchUp();
+                    }, 1000);
+                }
+            }
+            finally {
+                inflight.delete(id);
             }
-            socket = ws;
-            const openTimer = setTimeout(() => {
-                if (ws.readyState !== ws.OPEN) {
-                    ws.removeAllListeners();
-                    ws.terminate();
+        };
+        const open = deps.openSocket ?? openFmsgWebSocket;
+        const reconnect = (immediate = false) => {
+            if (finished || reconnectTimer || !client.reconnectOnTokenExpiry)
+                return;
+            reconnectTimer = setTimeout(() => {
+                reconnectTimer = undefined;
+                connect();
+            }, immediate ? 0 : reconnectDelay);
+            if (!immediate)
+                reconnectDelay = Math.min(reconnectDelay * 2, 10_000);
+        };
+        const connect = () => {
+            if (finished)
+                return;
+            open(client, retrySignal).then(ws => {
+                if (finished) {
+                    disposeSocket(ws);
+                    return;
+                }
+                socket = ws;
+                const expiresAt = webSocketTokenExpiresAt(ws);
+                const disconnected = (why) => {
+                    if (socket !== ws)
+                        return;
+                    clearTimeout(openTimer);
+                    clearTimeout(expiryTimer);
                     socket = undefined;
-                    startPolling("WebSocket did not open; polling instead");
+                    disposeSocket(ws);
+                    if (finished)
+                        return;
+                    if (client.reconnectOnTokenExpiry && expiresAt !== undefined && expiresAt <= Date.now() + 1000) {
+                        reconnect(true);
+                    }
+                    else {
+                        startPolling(why);
+                        reconnect();
+                    }
+                };
+                openTimer = setTimeout(() => disconnected("WebSocket did not open; polling instead"), options.wsOpenTimeoutMs ?? 10_000);
+                ws.on("open", () => {
+                    clearTimeout(openTimer);
+                    reconnectDelay = 1000;
+                    clearInterval(pollTimer);
+                    pollTimer = undefined;
+                    transport = "websocket";
+                    note = null;
+                    if (expiresAt !== undefined) {
+                        expiryTimer = setTimeout(() => disconnected("WebSocket credential expired"), Math.max(0, expiresAt - Date.now()));
+                    }
+                    // Keep the original floor, seen set, batch and deadline across renewal.
+                    void catchUp();
+                });
+                ws.on("message", raw => {
+                    const event = parseWsEvent(raw);
+                    if (event?.type === "new_msg" && event.data)
+                        void considerPushed(event.data.id);
+                });
+                ws.on("error", () => disconnected("WebSocket failed; polling instead"));
+                ws.on("close", () => disconnected("WebSocket closed; polling instead"));
+            }).catch(error => {
+                if (finished)
+                    return;
+                if (authorizationFailure(error)) {
+                    fail(error);
+                    return;
                 }
-            }, options.wsOpenTimeoutMs ?? 10_000);
-            ws.on("open", () => {
-                clearTimeout(openTimer);
-                void catchUp();
+                startPolling("WebSocket unavailable; polling instead");
+                reconnect();
             });
-            ws.on("message", (raw) => {
-                const event = parseWsEvent(raw);
-                if (event?.type === "new_msg" && event.data)
-                    void consider(event.data);
-            });
-            ws.on("error", () => {
-                clearTimeout(openTimer);
-                socket = undefined;
-                startPolling("WebSocket failed; polling instead");
-            });
-            ws.on("close", () => {
-                clearTimeout(openTimer);
-                socket = undefined;
-                if (!finished)
-                    startPolling("WebSocket closed; polling instead");
-            });
-        })
-            .catch(() => startPolling("WebSocket unavailable; polling instead"));
+        };
+        connect();
     });
 }

package/docs/http-deployment.md

@@ -0,0 +1,81 @@
+# HTTP deployment behind TLS
+
+This example runs Caddy and fmsg-mcp on the same machine. Replace `mcp.example.com` with your DNS
+name pointing to that machine; Caddy needs access to ports 80/443 for automatic public TLS.
+Keep port 8765 bound to loopback. The command below uses API keys; for OAuth add the
+[OAuth configuration](oauth.md#operator-configuration).
+
+```sh
+FMSG_API_URL=https://api.example.com \
+FMSG_MCP_ALLOWED_HOSTS=mcp.example.com \
+FMSG_MCP_PUBLIC_URL=https://mcp.example.com/mcp \
+FMSG_MCP_ALLOWED_ORIGINS=https://mcp.example.com,https://app.example.com \
+npx -y @markmnl/fmsg-mcp --http 127.0.0.1:8765
+```
+
+`FMSG_API_KEY` must be unset in HTTP mode. Include only browser origins you use. Behind TLS,
+list the public HTTPS origin explicitly: the server sees the proxy's HTTP connection and does
+not trust forwarded headers to establish the request origin.
+
+Save this as `Caddyfile`:
+
+```caddyfile
+mcp.example.com {
+    @fmsg path /mcp /mcp/attachments/* /.well-known/oauth-protected-resource /.well-known/oauth-protected-resource/*
+    handle @fmsg {
+        reverse_proxy 127.0.0.1:8765 {
+            transport http {
+                response_header_timeout 240s
+                read_timeout 240s
+                write_timeout 60s
+            }
+        }
+    }
+    respond 404
+}
+```
+
+Validate with `caddy validate --config Caddyfile --adapter caddyfile`, then run Caddy using your
+service manager. The `/healthz` liveness endpoint remains available locally at
+`http://127.0.0.1:8765/healthz`. The public MCP URL is `https://mcp.example.com/mcp`.
+
+Caddy preserves the Host, Authorization, Origin and MCP headers. It flushes SSE responses
+immediately by default. Keep the default flush setting: `flush_interval -1` disables backend
+cancellation on early disconnect. Do not enable automatic retries for sending requests.
+See [Caddy's streaming and proxy documentation](https://caddyserver.com/docs/caddyfile/directives/reverse_proxy#streaming).
+
+For another proxy, preserve these headers and streaming behavior, propagate disconnects, and
+allow response idle time beyond `FMSG_MCP_WAIT_MAX_SECONDS` with assembly headroom. Validate
+allowed and denied Host/Origin requests, unauthenticated 401 responses, CORS preflight, a read,
+and cancellation through the actual deployed proxy before advertising that deployment.
+
+The metadata routes are public in OAuth mode and must reach the server for MCP authorization
+discovery. In API-key mode they return 404. When OAuth is configured, its resource URL supplies
+the public same-origin value, so explicitly listing that origin is optional.
+
+## Binary attachment downloads
+
+`get_attachment_download_url` returns a resource link such as
+`https://mcp.example.com/mcp/attachments/123/report.pdf`. The host fetches it with an authenticated
+GET, using the same `Authorization: Bearer ...` header as its MCP connection. OAuth requires
+`fmsg:read`; the server exchanges the incoming token for a Web API token as usual. The Web API
+checks visibility on every download, even when a link was obtained earlier.
+
+Set `FMSG_MCP_PUBLIC_URL` to the exact external MCP endpoint when using API keys. OAuth defaults
+to `FMSG_MCP_OAUTH_RESOURCE_URL`; if both are set, they must match. These URLs require HTTPS outside
+loopback and cannot contain credentials, queries or fragments. Request Host and forwarded headers
+never select the download URL. If the proxy exposes MCP under a different public path, map that
+path and its `/attachments/*` suffix to `/mcp` and `/mcp/attachments/*` respectively.
+
+Downloads use the original MIME type, `Content-Disposition: attachment`, Unicode filename encoding,
+`Cache-Control: no-store` and `X-Content-Type-Options: nosniff`. The body streams with backpressure;
+disconnects cancel the upstream request and incomplete transfers abort rather than complete as a
+truncated file. No temporary server files, signed URLs or tokens in query strings are used.
+Range/resume requests are not implemented: GET returns the full file. Treat a failed transfer as
+incomplete and discard its partial local output before retrying.
+
+Host and Origin validation applies to downloads too. Allowed browser clients can preflight GET
+with Authorization and read Content-Disposition. Hosts must attach the connection credential
+themselves; never ask the model to locate or copy tokens. Clients that cannot fetch authenticated
+links can still use `download_attachment` inline. Compatibility of authenticated links with each
+third-party AI host must be tested before advertising support.

package/docs/oauth.md

@@ -0,0 +1,169 @@
+# HTTP OAuth
+
+OAuth is an optional HTTP authentication mode. API-key HTTP and stdio remain available with
+`FMSG_MCP_AUTH_MODE=api-key` (the default). Each endpoint uses one mode; run separate instances
+if you need both. There is no API-key fallback in OAuth mode.
+
+A user adds the public MCP URL to a compatible host, signs in with the configured authorization
+server, and consents to messaging scopes. The host handles authorization-code/PKCE and refresh;
+fmsg-mcp validates its access token and exchanges it for a separate Web API token. Users do not
+need to create an fmsg API key for this connection. The MCP server's exchange secret belongs to
+the operator and is never given to users or AI hosts.
+
+## Operator configuration
+
+Provision an OAuth resource and a confidential exchange client at your authorization server.
+Use the exact same resource URI in its resource registration, MCP configuration and host setup.
+The Web API must support [delegated OAuth claims](https://github.com/markmnl/fmsg-webapi/blob/main/docs/oauth-claims.md),
+with distinct OAuth and owner audiences. Configure the IdP's exchange target to issue that OAuth
+audience and the consented address, with `fmsg:read` and/or `fmsg:write`.
+
+```sh
+export FMSG_API_URL=https://api.example.com
+export FMSG_MCP_AUTH_MODE=oauth
+export FMSG_MCP_OAUTH_RESOURCE_URL=https://mcp.example.com/mcp
+export FMSG_MCP_OAUTH_ISSUER_URL=https://idp.example.com/oauth
+export FMSG_MCP_OAUTH_CLIENT_ID=fmsg-mcp
+export FMSG_MCP_OAUTH_EXCHANGE_AUDIENCE=fmsg-webapi
+export FMSG_MCP_ALLOWED_HOSTS=mcp.example.com
+# Supply FMSG_MCP_OAUTH_CLIENT_SECRET through your service's secret manager.
+# Leave FMSG_API_KEY unset.
+npx -y @markmnl/fmsg-mcp --http 127.0.0.1:8765
+```
+
+| Setting | Required in OAuth mode | Meaning |
+|---|---|---|
+| `FMSG_MCP_OAUTH_RESOURCE_URL` | Yes | Exact public MCP URL, including `/mcp`; also the incoming JWT audience |
+| `FMSG_MCP_OAUTH_ISSUER_URL` | Yes | Exact authorization-server issuer, including any path |
+| `FMSG_MCP_OAUTH_CLIENT_ID` | Yes | This MCP server's confidential token-exchange client ID |
+| `FMSG_MCP_OAUTH_CLIENT_SECRET` | Yes | Its exchange secret; sent only in HTTP Basic authentication |
+| `FMSG_MCP_OAUTH_EXCHANGE_AUDIENCE` | Yes | Actual Web API OAuth audience; must differ from the MCP resource URI |
+| `FMSG_MCP_OAUTH_ADDRESS_CLAIM` | No; `sub` | Incoming JWT claim containing the consented full `@user@domain` address |
+| `FMSG_API_URL` | Yes | Fixed deployed Web API base URL |
+
+Use the actual audience value for `EXCHANGE_AUDIENCE`, even if the IdP also supports target
+aliases: fmsg-mcp checks the returned JWT audience against this value. In the example the Web API
+and IdP target must both use `fmsg-webapi` as their OAuth audience. The outgoing token's `sub`
+must equal the incoming consented address; its issuer/signature are validated by the Web API.
+If your IdP stores a hash of the exchange secret, provision its SHA-256 there and give the original
+secret to this server. Never put the secret in source control or client configuration.
+
+OAuth URLs require HTTPS, with HTTP permitted only on loopback for local testing. Discovery,
+JWKS and exchange requests refuse redirects and have a five-second/64-KiB response budget.
+Configuration is vendor neutral, but authorization servers must implement the token profile below;
+an arbitrary OAuth provider without token exchange is not sufficient.
+
+Use the [TLS deployment recipe](http-deployment.md), including its metadata routes. Browser hosts
+on other origins need `FMSG_MCP_ALLOWED_ORIGINS`. The configured resource origin is accepted as
+same-origin behind a TLS proxy; forwarded headers never select an issuer, resource or token endpoint.
+
+## Discovery and client onboarding
+
+Public [RFC 9728](https://www.rfc-editor.org/rfc/rfc9728.html) metadata is served at
+`/.well-known/oauth-protected-resource` and the resource-specific path
+`/.well-known/oauth-protected-resource/mcp`. Both advertise the exact configured resource,
+authorization server, supported scopes and header bearer authentication. A resource served under
+another public path requires the corresponding metadata path to reach this process too.
+Unauthenticated or invalid-token requests receive `401` with a `WWW-Authenticate: Bearer`
+challenge containing `resource_metadata`.
+
+Authorization-server metadata uses [RFC 8414](https://www.rfc-editor.org/rfc/rfc8414.html):
+issuer `https://idp.example.com/oauth` is discovered at
+`https://idp.example.com/.well-known/oauth-authorization-server/oauth`. A 404 permits the
+OpenID-style discovery fallback below the issuer. The discovered issuer must match exactly.
+Only its `jwks_uri` is used; the server does not guess `/.well-known/jwks.json` or trust JWT
+`jku`/`x5u` headers. Discovery and keys cache for five minutes. An unknown signing key can trigger
+a refresh after a five-second fetch cooldown; publish new keys before using them.
+
+Client registration belongs to the authorization server. If it offers no dynamic registration,
+use pre-registered clients or Client ID Metadata Documents where supported by both server and
+host. Check the intended host's registration support before advertising compatibility. This
+implementation does not add a registration proxy, login UI or consent UI.
+
+The resource URL also supplies the public URL for `get_attachment_download_url`. Its links contain
+no credentials; hosts fetch them using the current MCP bearer token, with `fmsg:read`. The binary
+GET route uses the same token validation and Web API token exchange, and exposes the same metadata
+challenge on authentication failure. See [binary downloads](http-deployment.md#binary-attachment-downloads)
+for reverse-proxy routing and host compatibility requirements.
+
+## Token validation and scopes
+
+Incoming access tokens must be signed EdDSA JWTs with `typ: at+jwt`, a nonempty `kid` in the
+discovered key set, exact `iss`, and exactly one audience equal to the resource URI. Signature,
+`exp` and any `nbf` are checked on every request. `sub` is required, the configured address claim
+must contain a full fmsg address, and `scope` is a space-delimited string. Unrecognized scopes
+grant no messaging capability. Tokens for another audience, including Web API/owner tokens,
+are refused.
+
+| Operations | Required scope |
+|---|---|
+| Identity/address lookup, inbox/sent, message/thread, delivery status, attachment download, wait, resource reads | `fmsg:read` |
+| Send a new message, add recipients, react, mark read | `fmsg:write` |
+| Reply (reads the parent before sending) | `fmsg:read fmsg:write` |
+| Protocol initialization, tool/resource/prompt discovery and prompt templates | Valid incoming token; no messaging scope needed |
+
+Missing scope returns `403` with `error="insufficient_scope"` and the required `scope` in the
+bearer challenge. The SDK then validates tool arguments and dispatches the request. Scopes are
+checked against the actual request body, including resource reads; JSON batches are refused.
+The Web API still decides message visibility, recipients, account grants, quotas and acceptance.
+No duplicate messaging ACLs or per-message approvals are introduced.
+
+## Exchange, renewal and revocation
+
+For protected operations, fmsg-mcp calls the discovered token endpoint with an
+[RFC 8693](https://www.rfc-editor.org/rfc/rfc8693.html) form: token-exchange `grant_type`, incoming
+`subject_token`, access-token `subject_token_type`, configured `audience`, and the granted
+messaging `scope`. HTTP Basic carries the server client ID and secret. The incoming token is
+never sent to the Web API, and `X-FMSG-Act-As` is never set.
+
+The response must contain a separate JWT `access_token`, Bearer `token_type`, access-token
+`issued_token_type`, positive `expires_in`, matching `scope`, and no refresh token. Its audience,
+address, expiry and scopes are checked before use; the trusted token endpoint issues it, and the
+Web API verifies its signature and issuer. Delegated tokens must not reach owner-only routes
+such as sub-account, API-key or push administration, even outside the MCP tool surface.
+
+Each incoming token has its own client and cache, even when two tokens name the same user.
+The cache lifetime is the earliest of `expires_in`, exchanged JWT expiry, incoming JWT expiry
+and five minutes from the exchange request. Renewal normally starts halfway through that lifetime.
+`FMSG_MCP_KEY_CACHE_MAX` bounds retained client entries; idle OAuth entries are evicted after five
+minutes. `FMSG_MCP_KEY_CACHE_TTL_SECONDS` applies only to API-key mode and cannot extend OAuth
+credentials. Active requests retain their own leases through cache eviction. No token is persisted.
+
+Web API `401` retries once after re-exchange; `403` never retries. An expiry timer closes an OAuth
+WebSocket by its cached credential deadline, even if the Web API leaves it open. Waits reconnect,
+catch up, and retain their original cursor, accumulated batch and timeout. Network failures use
+bounded reconnect backoff with polling; cancellation closes sockets and stops exchange work.
+This does not resolve the separate large-backlog/pending-thread cursor work in [ROADMAP.md](../ROADMAP.md).
+
+- `invalid_grant` from exchange means `401`: refresh or reconnect the client connection.
+- `invalid_client` / `invalid_target` means `500` plus a sanitized operator-action log. Monitor this
+  log as an alert; correct the exchange configuration rather than asking users to sign in again.
+- Unavailable discovery/JWKS/exchange means `503`; there is no fallback credential.
+- Web API `403` with `insufficient_scope` is returned as a scope challenge. It may indicate either
+  missing scope or a route permanently closed to delegated tokens; additional consent cannot open
+  owner-only routes.
+
+Authentication is checked before protected responses start. A later authentication failure also
+becomes an HTTP challenge if headers have not been sent. Once a long wait has streamed progress,
+HTTP cannot change its status: it finishes with an MCP authentication error and the next request
+receives the appropriate challenge. Hosts should reconnect/refresh after that error, not repeat sends.
+
+Offline validation cannot instantly detect revocation. With ten-minute incoming and five-minute
+exchanged tokens, discovery operations may accept a revoked incoming token for up to ten minutes;
+new Web API requests stop within five minutes once exchange starts refusing the grant. Longer
+IdP lifetimes extend offline acceptance at the corresponding service. The MCP cache/socket cap
+stays five minutes, but a copied upstream token remains usable directly until its actual expiry.
+Configure upstream lifetimes to meet your intended revocation guarantee.
+
+## Validation and rollout
+
+`test/oauth.test.ts` uses a local authorization server with real Ed25519 signatures and separate
+OAuth/Web API keys. It exercises discovery, invalid claims, scopes, exchange, caller isolation,
+revocation, token expiry and waiting across reconnects. The fake Web API accepts registered token
+fixtures; it is not a substitute for the Web API's JWT authorization tests.
+
+Before enabling a hosted deployment, verify the deployed IdP and Web API audience configuration,
+then exercise sign-in/consent, `whoami`, send/read/reply, refresh, revoked grants, scope denial and
+wait cancellation through the real TLS proxy in each advertised MCP host. No live hosted-client
+or deployed IdP compatibility is claimed by the local tests. API-key integration can keep running
+while these services are prepared.

package/docs/token-providers.md

@@ -0,0 +1,94 @@
+# Web API token providers
+
+`FmsgClient` accepts either the existing `fmsgk_…` API-key string or a `TokenProvider`.
+This is a client-library extension point. The MCP executable uses it for API keys and
+optional [HTTP OAuth](oauth.md), including discovery, JWT validation and RFC 8693 exchange.
+
+Import `TokenProvider`, `TokenProviderRequest` and `AccessToken` from
+`@markmnl/fmsg-mcp/client` (also exported from the package root):
+
+```ts
+interface TokenProvider {
+  getToken(request: {
+    apiUrl: string;
+    signal: AbortSignal;
+    forceRefresh: boolean;
+  }): Promise<{
+    accessToken: string;
+    address: string;
+    expiresAtMs: number;
+  }>;
+  close?(): void;
+}
+```
+
+Supply an implementation as `new FmsgClient(apiUrl, tokenProvider, options)`.
+One provider and client belong to one caller, authorization grant and Web API URL.
+Sharing a provider between clients risks mixing grants or closing another client's credentials.
+
+## Provider responsibilities
+
+- Obtain a fresh **Web API** bearer access token whenever called. `apiUrl` is the
+  normalized, fixed upstream URL; never derive credential destinations from model input.
+  `forceRefresh: true` means the previous token was rejected with 401 or renewal was
+  explicitly requested. It must bypass any provider cache of that rejected token.
+- Return the authenticated fmsg address that the token authorizes, preserving user-name
+  case, and a finite future expiry in milliseconds since the Unix epoch. Use trusted
+  authorization/exchange metadata; do not invent an expiry or infer identity from an
+  unverified incoming token. The generic client does not decode provider tokens.
+- Honour `signal` for all network work. It aborts when renewal times out, the client
+  closes, or all callers waiting for that renewal cancel. Reject on failed/revoked
+  authorization; never fall back to an owner token, API key or another grant.
+- Keep credentials out of errors and logs. `close()` synchronously releases retained
+  credentials/resources; it is called once when the owning client closes. Closing a
+  client is local cleanup, not remote OAuth-grant revocation.
+
+## Client responsibilities
+
+The client caches immutable token snapshots and shares concurrent renewal. It renews
+five minutes before expiry by default, capped at half the remaining lifetime when the
+token is acquired, so a one-minute token is usable without constant re-exchange.
+`refreshMarginMs: 0` disables early renewal, but never permits an expired cached token.
+Each acquisition has the client's `timeoutMs` budget (60 seconds by default).
+
+The first successful acquisition pins the address. A renewal for another address is
+rejected before any request uses that token; changing identities requires a new client.
+This is caller binding, not an additional messaging permission system. The Web API
+still validates the actual credential, identity, scopes, visibility and host limits.
+
+Protected HTTP requests retry once on 401 after renewal. Concurrent or late 401s for
+the same old token reuse an already renewed token; 403 never triggers renewal.
+Failed renewal discards the cache. Provider output must be a bearer token with a valid
+address and expiry; an API key passed back as an access token is rejected.
+
+`getToken(force?, signal?)` and `address(signal?)` support cancellation, as do existing
+request methods that accept a signal. Cancelling one waiter leaves renewal available
+to others; cancelling the last aborts acquisition. Late provider completion cannot
+replace a later token. `close()` aborts outstanding token acquisition and HTTP work.
+
+`openFmsgWebSocket(client, signal?)` obtains its bearer from the same provider/cache.
+The optional signal cancels token acquisition before opening the socket. The caller
+owns the returned WebSocket and must handle its events and close it; long-lived
+connections do not gain automatic token renewal or revocation handling from this helper.
+`wait_for_message` owns its socket and passes cancellation into acquisition. With
+`reconnectOnTokenExpiry: true`, it closes and reopens sockets by the token metadata expiry,
+retaining the original wait deadline and cursor; OAuth mode enables this option.
+
+## OAuth adapter contract
+
+Validate the incoming MCP access token for the configured issuer and MCP audience,
+then use authenticated [RFC 8693 token exchange](https://www.rfc-editor.org/rfc/rfc8693.html)
+to obtain a separate upstream token. [MCP forbids passing the incoming token through
+to the Web API](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization/security-considerations).
+Keep issuer, JWKS/discovery URLs, audiences, address-claim mapping and client credentials
+configurable; no particular identity provider is required by this interface.
+
+The IdP and Web API must agree on scopes and consented-identity binding before hosted
+OAuth is enabled. Exchanged messaging tokens must not acquire owner key-management
+rights or broaden identity via `X-FMSG-Act-As`. The Web API enforces those restrictions;
+the tool list is not an authorization boundary. Browser consent and refresh/revocation endpoints belong to the authorization service and host. Offline JWT validation alone does not
+provide immediate revocation of already issued upstream tokens.
+
+Tests in `test/token-provider.test.ts` use registered opaque token fixtures to exercise
+renewal, cancellation, caller isolation, and HTTP/WebSocket credential delivery. They
+do not establish OAuth conformance, JWT verification, or compatibility with a real IdP.