@markmnl/fmsg-mcp 0.1.3 → 0.2.0

package/dist/wait.js

@@ -1,10 +1,15 @@
-import { compareMessageIds, maxMessageId } from "./client/message-id.js";
-import { openFmsgWebSocket, parseWsEvent } from "./client/ws.js";
+import { setTimeout as delay } from "node:timers/promises";
+import { FmsgHttpError } from "./client/client.js";
+import { compareMessageIds, maxMessageId, minMessageId } from "./client/message-id.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;
@@ -18,76 +23,134 @@ export async function waitForMessage(client, self, options, signal, deps = {}) {
         floor = newest?.id ?? "0";
     }
     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 rootOf = async (id) => {
-        if (rootCache.has(id))
-            return rootCache.get(id);
-        let root = null;
+    const lookupRoot = async (id) => {
         try {
-            root = (await client.getThreadMessages(id, signal)).root_id;
+            return (await client.getThreadMessages(id, retrySignal)).root_id;
         }
-        catch {
-            // Fall back to a bounded pid walk.
-            try {
-                let cur = id;
-                for (let i = 0; i < 100; i++) {
-                    const m = await client.getMessage(cur, signal);
-                    if (!m.pid) {
-                        root = m.id;
-                        break;
-                    }
-                    cur = m.pid;
-                }
-            }
-            catch {
-                root = null;
+        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, retrySignal);
+                if (!m.pid)
+                    return m.id;
+                cur = m.pid;
             }
+            throw error;
         }
+    };
+    /**
+     * Resolve a message's thread root. A lookup can fail transiently (the host's
+     * WebSocket announces a message slightly before it is readable), so retry a
+     * few times; if it still fails, throw rather than guess: a message whose
+     * thread is unknown must never be mistaken for one on another thread.
+     */
+    const rootOf = async (id, attempts = 3) => {
+        const cached = rootCache.get(id);
+        if (cached !== undefined)
+            return cached;
+        const root = await retryRead(() => lookupRoot(id), attempts);
         rootCache.set(id, root);
         return root;
     };
-    const targetRoot = options.threadOf ? await rootOf(options.threadOf) : undefined;
-    if (options.threadOf && targetRoot === null)
-        throw new Error(`could not determine the thread of message ${options.threadOf}`);
+    let targetRoot;
+    if (options.threadOf) {
+        try {
+            targetRoot = await rootOf(options.threadOf, 1);
+        }
+        catch (error) {
+            if (authorizationFailure(error))
+                throw error;
+            throw new Error(`could not determine the thread of message ${options.threadOf}`);
+        }
+    }
     const seen = new Set();
     const batch = [];
     const pending = [];
+    const skipped = [];
+    const unclassified = [];
+    /** Messages whose thread lookup is still running; if the call ends first they count as unclassified. */
+    const inflight = new Map();
     let batchRoot = null;
     let transport = "websocket";
     let note = null;
     let socket;
     let pollTimer;
     let settleTimer;
-    let finished = false;
+    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)
                 return;
             cleanup();
+            for (const [id, from] of inflight)
+                unclassified.push({ id, from, error: "thread lookup did not complete before the call returned" });
+            inflight.clear();
             const ids = batch.map((m) => m.id);
+            // The cursor advances only over messages returned or deliberately skipped,
+            // and never past a message whose thread could not be determined.
+            let afterId = maxMessageId([...ids, skippedMax, floor]);
+            const firstUnknown = unclassified.length ? minMessageId(unclassified.map((u) => u.id)) : undefined;
+            if (firstUnknown !== undefined && compareMessageIds(afterId, firstUnknown) >= 0) {
+                const before = (BigInt(firstUnknown) - 1n).toString();
+                afterId = compareMessageIds(before, floor) > 0 ? before : floor;
+                const held = `cursor held at ${afterId}: could not determine the thread of ${unclassified.map((u) => u.id).join(", ")}; call again to retry`;
+                note = note ? `${note}; ${held}` : held;
+            }
             resolve({
                 status: batch.length ? "message" : "timeout",
-                after_id: batch.length ? maxMessageId(ids) : skippedMax,
+                after_id: afterId,
                 thread_root_id: batchRoot,
                 messages: [...batch].sort((a, b) => compareMessageIds(a.id, b.id)),
                 pending_other_threads: pending,
+                skipped: [...skipped].sort((a, b) => compareMessageIds(a.id, b.id)),
+                unclassified: [...unclassified].sort((a, b) => compareMessageIds(a.id, b.id)),
                 transport,
                 note,
             });
@@ -102,38 +165,56 @@ 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 disqualified = m.from.toLowerCase() === me ||
-                (m.reaction !== null && m.reaction !== undefined) ||
-                m.no_reply === true ||
-                (wantFrom !== undefined && m.from.toLowerCase() !== wantFrom);
-            if (disqualified) {
+            const skip = (reason) => {
+                skipped.push({ id: m.id, reason });
                 if (compareMessageIds(m.id, skippedMax) > 0)
                     skippedMax = m.id;
+            };
+            if (m.from.toLowerCase() === me)
+                return skip("own");
+            if (m.reaction !== null && m.reaction !== undefined)
+                return skip("reaction");
+            if (m.no_reply === true)
+                return skip("no_reply");
+            if (wantFrom !== undefined && m.from.toLowerCase() !== wantFrom)
+                return skip("from_mismatch");
+            let root;
+            inflight.set(m.id, m.from);
+            try {
+                root = await rootOf(m.id);
+            }
+            catch (error) {
+                if (authorizationFailure(error))
+                    return fail(error);
+                if (!finished)
+                    unclassified.push({ id: m.id, from: m.from, error: safeErrorMessage(error) });
                 return;
             }
-            const root = await rootOf(m.id);
+            finally {
+                inflight.delete(m.id);
+            }
             if (finished)
                 return;
-            if (targetRoot !== undefined && root !== targetRoot) {
-                if (compareMessageIds(m.id, skippedMax) > 0)
-                    skippedMax = m.id;
-                return;
-            }
+            if (targetRoot !== undefined && root !== targetRoot)
+                return skip("other_thread");
             if (batch.length === 0) {
                 batchRoot = root;
                 batch.push(m);
@@ -150,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);
             }
@@ -168,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);
+                }
             }
-            socket = ws;
-            const openTimer = setTimeout(() => {
-                if (ws.readyState !== ws.OPEN) {
-                    ws.removeAllListeners();
-                    ws.terminate();
+            finally {
+                inflight.delete(id);
+            }
+        };
+        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();
-            });
-            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");
+                startPolling("WebSocket unavailable; polling instead");
+                reconnect();
             });
-            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,53 @@
+# 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_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 /.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.

package/docs/oauth.md

@@ -0,0 +1,163 @@
+# 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.
+
+## 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.