@markmnl/fmsg-mcp 0.2.3 → 0.2.4

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+- Add HTTP `FMSG_MCP_AUTH_MODE=oauth+api-key`, serving OAuth and API-key callers on one endpoint.
+  `Bearer fmsgk_...` requests use API-key authentication; all others, including unauthenticated
+  requests, use OAuth with its discovery challenge and scope checks. Providers and caches stay
+  separate. Rejected API keys are also challenged with the protected-resource metadata URL.
+  `api-key` and `oauth` modes are unchanged. `HttpServerHandle.providers` exposes both providers.
 - Add optional `FMSG_API_PUBLIC_URL`: the Web API URL `whoami` reports to users, while requests
   keep using `FMSG_API_URL`. It defaults to `FMSG_API_URL`, except that HTTP mode no longer
   reports a cleartext (internal or loopback) upstream URL. `whoami`'s `api_url` is therefore

package/README.md

@@ -103,6 +103,7 @@ configured `Authorization: Bearer fmsgk_...` header. Each caller supplies its ow
 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.
+`FMSG_MCP_AUTH_MODE=oauth+api-key` accepts both OAuth and API-key callers on the same URL.
 
 For [Claude Code over HTTP](https://code.claude.com/docs/en/mcp):
 
@@ -155,8 +156,8 @@ 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_API_PUBLIC_URL` | `FMSG_API_URL` (HTTP mode: only if HTTPS) | Web API URL reported to users by `whoami`; never used for requests. Set it when the server reaches the Web API at an internal address. Without it, HTTP mode reports no URL for a cleartext `FMSG_API_URL`. Validated like `FMSG_API_URL` |
-| `FMSG_MCP_AUTH_MODE` | `api-key` | HTTP authentication: `api-key` or `oauth`; see [OAuth settings](docs/oauth.md#operator-configuration) |
-| `FMSG_MCP_PUBLIC_URL` | OAuth resource URL, otherwise unset | Public MCP endpoint, including `/mcp`; enables the HTTP download-link tool. HTTPS required except loopback; in OAuth mode must equal `FMSG_MCP_OAUTH_RESOURCE_URL` |
+| `FMSG_MCP_AUTH_MODE` | `api-key` | HTTP authentication: `api-key`, `oauth`, or `oauth+api-key` to accept both on one endpoint; see [OAuth settings](docs/oauth.md#operator-configuration) and [combined mode](docs/oauth.md#combined-oauth-and-api-key-mode) |
+| `FMSG_MCP_PUBLIC_URL` | OAuth resource URL, otherwise unset | Public MCP endpoint, including `/mcp`; enables the HTTP download-link tool. HTTPS required except loopback; when OAuth is enabled must equal `FMSG_MCP_OAUTH_RESOURCE_URL` |
 | `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 |
@@ -165,7 +166,7 @@ attach resources; prompts `chat` and `reply` script the wait → reply loop and
 | `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; 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 |
+| `FMSG_MCP_KEY_CACHE_MAX` / `FMSG_MCP_KEY_CACHE_TTL_SECONDS` | `500` / `1800` | HTTP client cache bound; TTL applies only to API-key callers |
 
 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

package/SECURITY.md

@@ -8,7 +8,7 @@ rather than a public issue.
 
 - 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.
+- 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. Combined `oauth+api-key` mode routes `fmsgk_` keys to API-key authentication and all other credentials to OAuth, with separate caches.
   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

package/dist/http.d.ts

@@ -10,6 +10,12 @@ export declare function sendWebResponse(res: ServerResponse, response: Response,
 export type HttpServerHandle = {
     server: Server;
     close: () => Promise<void>;
+    /** The OAuth provider when OAuth is configured, otherwise the API-key provider. */
     provider: ApiKeyCallerProvider | OAuthCallerProvider;
+    /** Each configured provider; both are set in combined `oauth+api-key` mode. */
+    providers: {
+        apiKey?: ApiKeyCallerProvider;
+        oauth?: OAuthCallerProvider;
+    };
 };
 export declare function createHttpServer(config: Config, log?: (line: string) => void): HttpServerHandle;

package/dist/http.js

@@ -15,6 +15,8 @@ import { isLoopbackHost, normalizeOrigin } from "./client/url.js";
 export const MCP_PATH = "/mcp";
 const CORS_METHODS = ["POST", "GET", "DELETE"];
 const CORS_HEADERS = ["authorization", "content-type", "accept", "mcp-protocol-version", "mcp-method", "mcp-name", "mcp-session-id", "last-event-id"];
+// Combined mode routes only fmsg API keys to API-key authentication; everything else is OAuth.
+const API_KEY_BEARER = /^Bearer fmsgk_/iu;
 /** Convert a Node request into a web-standard Request for the MCP handler. */
 export function toWebRequest(req, signal) {
     const host = req.headers.host ?? "localhost";
@@ -105,17 +107,20 @@ export function createHttpServer(config, log = (l) => console.error(l)) {
         throw new Error("FMSG_MCP_ALLOWED_HOSTS must contain explicit hostnames without wildcards, schemes or paths");
     const allowedOrigins = config.http.allowedOrigins.map(normalizeOrigin);
     const safeLog = (line) => log(safeErrorMessage(line));
-    const provider = config.oauth ? new OAuthCallerProvider(config, safeLog) : new ApiKeyCallerProvider(config, safeLog);
+    // Combined mode keeps separate providers and MCP handlers, so a caller is only
+    // ever resolved by the provider that authenticated it.
+    const oauthProvider = config.oauth ? new OAuthCallerProvider(config, safeLog) : undefined;
+    const apiKeyProvider = !config.oauth || config.oauth.acceptApiKeys ? new ApiKeyCallerProvider(config, safeLog) : undefined;
     const resource = config.oauth ? new URL(config.oauth.resourceUrl) : undefined;
     const publicOrigin = downloadBaseUrl(config) ? new URL(downloadBaseUrl(config)).origin : undefined;
     const metadataPath = resource ? `/.well-known/oauth-protected-resource${resource.pathname === "/" ? "" : resource.pathname}` : undefined;
     const metadataUrl = resource ? `${resource.origin}${metadataPath}` : "";
-    const handler = createMcpHandler(({ authInfo }) => createFmsgMcpServer(provider, config, authInfo ? {
-        address: config.oauth ? String(authInfo.extra?.address ?? "") : authInfo.clientId,
-    } : {}), { onerror: (error) => safeLog(`MCP transport failed: ${error instanceof Error ? error.message : String(error)}`) });
+    const mcpHandler = (provider, address) => createMcpHandler(({ authInfo }) => createFmsgMcpServer(provider, config, authInfo ? { address: address(authInfo) } : {}), { onerror: (error) => safeLog(`MCP transport failed: ${error instanceof Error ? error.message : String(error)}`) });
+    const oauthHandler = oauthProvider && mcpHandler(oauthProvider, (authInfo) => String(authInfo.extra?.address ?? ""));
+    const apiKeyHandler = apiKeyProvider && mcpHandler(apiKeyProvider, (authInfo) => authInfo.clientId);
     const active = new Set();
     const server = createServer((req, res) => {
-        let authenticated;
+        let release;
         const controller = new AbortController();
         active.add(controller);
         const abort = () => controller.abort();
@@ -196,7 +201,7 @@ export function createHttpServer(config, log = (l) => console.error(l)) {
                     return sendWebResponse(res, new Response("invalid attachment download path", { status: 400 }));
                 }
             }
-            const serveDownload = async (auth) => {
+            const serveDownload = async (provider, auth) => {
                 let caller;
                 try {
                     caller = await provider.forRequest(auth);
@@ -232,17 +237,20 @@ export function createHttpServer(config, log = (l) => console.error(l)) {
                         }
                     }
                     const status = rejectedAuth ? 401 : error instanceof FmsgHttpError && error.status >= 400 && error.status <= 599 ? error.status : 502;
+                    const challenge = `Bearer error="invalid_token"${resource ? `, resource_metadata=${JSON.stringify(metadataUrl)}` : ""}`;
                     return sendWebResponse(res, Response.json({ error: describeError(error) }, {
-                        status, headers: status === 401 ? { "www-authenticate": 'Bearer error="invalid_token"' } : {},
+                        status, headers: status === 401 ? { "www-authenticate": challenge } : {},
                     }));
                 }
             };
-            if (provider instanceof OAuthCallerProvider) {
+            const authorization = request.headers.get("authorization") ?? "";
+            if (oauthProvider && oauthHandler && !(apiKeyProvider && API_KEY_BEARER.test(authorization))) {
                 try {
-                    const bearer = /^Bearer ([A-Za-z0-9._~+\/-]+=*)$/iu.exec(request.headers.get("authorization") ?? "");
+                    const bearer = /^Bearer ([A-Za-z0-9._~+\/-]+=*)$/iu.exec(authorization);
                     if (!bearer)
                         throw invalidToken();
-                    authenticated = await provider.verifyAccessToken(bearer[1]);
+                    const authenticated = await oauthProvider.verifyAccessToken(bearer[1]);
+                    release = () => oauthProvider.release(authenticated);
                     let parsedBody;
                     if (request.method === "POST") {
                         try {
@@ -258,16 +266,16 @@ export function createHttpServer(config, log = (l) => console.error(l)) {
                     if (scopes.some(scope => !authenticated.scopes.includes(scope)))
                         throw insufficientScope(scopes);
                     if (download)
-                        return await serveDownload(authenticated);
+                        return await serveDownload(oauthProvider, authenticated);
                     // Discover/list operations only need the incoming JWT. Resolve an
                     // exchanged credential before starting any protected tool response.
                     if (scopes.length) {
-                        const caller = await provider.forRequest(authenticated);
+                        const caller = await oauthProvider.forRequest(authenticated);
                         await caller.client.getToken(false, controller.signal);
                     }
                     const state = { scopes };
                     return await oauthRequestState.run(state, async () => {
-                        const response = await handler.fetch(request, { authInfo: authenticated, parsedBody });
+                        const response = await oauthHandler.fetch(request, { authInfo: authenticated, parsedBody });
                         await sendWebResponse(res, response, () => state.error ? oauthErrorResponse(state.error, metadataUrl) : undefined);
                     });
                 }
@@ -277,21 +285,27 @@ export function createHttpServer(config, log = (l) => console.error(l)) {
                     throw error;
                 }
             }
+            if (!apiKeyProvider || !apiKeyHandler)
+                throw new Error("no authentication provider configured");
             // Capture the lease before middleware's expiry/scope checks, so finally also
             // releases requests rejected after the upstream identity was verified.
             const gate = requireBearerAuth({
                 verifier: { verifyAccessToken: async (token) => {
-                        authenticated = await provider.verifyAccessToken(token);
+                        const authenticated = await apiKeyProvider.verifyAccessToken(token);
+                        release = () => apiKeyProvider.release(authenticated);
                         return authenticated;
                     } },
-                requiredScopes: [FMSG_SCOPE],
+                // In combined mode, challenge with the OAuth metadata so hosts can discover
+                // sign-in. The internal API-key scope is omitted there: it is always granted
+                // and is not an authorization-server scope a host could request.
+                ...(resource ? { resourceMetadataUrl: metadataUrl } : { requiredScopes: [FMSG_SCOPE] }),
             });
             const auth = await gate(request);
             if (auth instanceof Response)
                 return sendWebResponse(res, auth);
             if (download)
-                return serveDownload(auth);
-            return sendWebResponse(res, await handler.fetch(request, { authInfo: auth }));
+                return serveDownload(apiKeyProvider, auth);
+            return sendWebResponse(res, await apiKeyHandler.fetch(request, { authInfo: auth }));
         })().catch((error) => {
             safeLog(`request failed: ${error instanceof Error ? error.message : String(error)}`);
             if (res.destroyed)
@@ -303,8 +317,7 @@ export function createHttpServer(config, log = (l) => console.error(l)) {
             res.writeHead(500, { "content-type": "text/plain" });
             res.end("internal error");
         }).finally(() => {
-            if (authenticated)
-                provider.release(authenticated);
+            release?.();
             active.delete(controller);
             req.off("aborted", abort);
             res.off("close", abort);
@@ -317,8 +330,9 @@ export function createHttpServer(config, log = (l) => console.error(l)) {
     const close = async () => {
         for (const controller of active)
             controller.abort();
-        provider.close();
-        await handler.close();
+        oauthProvider?.close();
+        apiKeyProvider?.close();
+        await Promise.all([oauthHandler?.close(), apiKeyHandler?.close()]);
         await new Promise((resolve) => {
             server.close(() => resolve());
             // Aborted fetches may open replacement sockets without a request, so
@@ -326,5 +340,5 @@ export function createHttpServer(config, log = (l) => console.error(l)) {
             server.closeAllConnections();
         });
     };
-    return { server, close, provider };
+    return { server, close, provider: (oauthProvider ?? apiKeyProvider), providers: { apiKey: apiKeyProvider, oauth: oauthProvider } };
 }

package/dist/index.js

@@ -24,7 +24,8 @@ Options (HTTP mode):
 Environment:
   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 (default) or oauth (HTTP only)
+  FMSG_MCP_AUTH_MODE         api-key (default), oauth, or oauth+api-key to accept
+                            both on one endpoint (HTTP only)
   FMSG_MCP_OAUTH_*           OAuth resource/issuer URLs, client ID/secret and exchange
                             audience; see docs/oauth.md for required settings
   FMSG_ALLOW_INSECURE_HTTP   1 to allow a trusted private HTTP API outside loopback

package/dist/oauth/config.d.ts

@@ -5,6 +5,8 @@ export type OAuthConfig = {
     clientSecret: string;
     exchangeAudience: string;
     addressClaim: string;
+    /** Combined mode: `fmsgk_` bearer keys use API-key authentication on the same endpoint. */
+    acceptApiKeys?: boolean;
 };
 /** Preserve exact issuer/resource identifiers while checking their transport and shape. */
 export declare function oauthUrl(value: string, label: string, allowQuery?: boolean): string;

package/dist/oauth/config.js

@@ -16,12 +16,13 @@ export function oauthUrl(value, label, allowQuery = false) {
 }
 export function loadOAuthConfig(env, transport) {
     const mode = env.FMSG_MCP_AUTH_MODE ?? "api-key";
-    if (mode !== "api-key" && mode !== "oauth")
-        throw new Error("FMSG_MCP_AUTH_MODE must be api-key or oauth");
+    if (mode !== "api-key" && mode !== "oauth" && mode !== "oauth+api-key") {
+        throw new Error("FMSG_MCP_AUTH_MODE must be api-key, oauth or oauth+api-key");
+    }
     const configured = Object.keys(env).some(key => key.startsWith("FMSG_MCP_OAUTH_") && env[key]);
     if (mode === "api-key") {
         if (configured)
-            throw new Error("Set FMSG_MCP_AUTH_MODE=oauth to use FMSG_MCP_OAUTH_* settings");
+            throw new Error("Set FMSG_MCP_AUTH_MODE=oauth or oauth+api-key to use FMSG_MCP_OAUTH_* settings");
         return undefined;
     }
     if (transport !== "http")
@@ -42,5 +43,6 @@ export function loadOAuthConfig(env, transport) {
         resourceUrl, issuerUrl, exchangeAudience,
         clientId: required("CLIENT_ID"), clientSecret: required("CLIENT_SECRET"),
         addressClaim: env.FMSG_MCP_OAUTH_ADDRESS_CLAIM?.trim() || "sub",
+        ...(mode === "oauth+api-key" ? { acceptApiKeys: true } : {}),
     };
 }

package/docs/http-deployment.md

@@ -2,8 +2,8 @@
 
 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).
+Keep port 8765 bound to loopback. The command below uses API keys; for OAuth, or OAuth and API
+keys on the same endpoint, add the [OAuth configuration](oauth.md#operator-configuration).
 
 ```sh
 FMSG_API_URL=https://api.example.com \
@@ -54,8 +54,8 @@ allow response idle time beyond `FMSG_MCP_WAIT_MAX_SECONDS` with assembly headro
 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 metadata routes are public in `oauth` and `oauth+api-key` modes 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

package/docs/oauth.md

@@ -1,8 +1,9 @@
 # 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.
+`FMSG_MCP_AUTH_MODE=api-key` (the default). `FMSG_MCP_AUTH_MODE=oauth` accepts only OAuth access
+tokens; there is no API-key fallback. `FMSG_MCP_AUTH_MODE=oauth+api-key` serves both kinds of
+caller on one endpoint; see [combined mode](#combined-oauth-and-api-key-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;
@@ -57,6 +58,26 @@ Use the [TLS deployment recipe](http-deployment.md), including its metadata rout
 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.
 
+## Combined OAuth and API-key mode
+
+`FMSG_MCP_AUTH_MODE=oauth+api-key` (HTTP only) accepts OAuth and API-key callers at the same
+public MCP URL. It requires the complete OAuth configuration above. Each request is routed by its
+`Authorization` header:
+
+- `Bearer fmsgk_...` is handled exactly as in API-key mode. The key is exchanged at the Web API
+  and is never sent to the authorization server. OAuth scopes do not apply; the Web API decides
+  access as for any API-key caller.
+- Any other bearer token, or a missing or malformed header, is handled exactly as in OAuth mode,
+  including scope checks. Unauthenticated requests receive the OAuth `401` challenge with
+  `resource_metadata`, so hosts can discover sign-in.
+
+The two kinds of caller use separate providers and caches: a request is only ever served by the
+mechanism that authenticated it, and a JWT is never treated as an API key. Protected-resource
+metadata is served as in OAuth mode, and attachment downloads accept either credential. A rejected
+API key returns `401` with `error="invalid_token"` and the same `resource_metadata`, without a
+`scope` parameter, so a host can offer sign-in instead. API-key callers need a host that sends a
+configured `Authorization` header; hosts that only support MCP authorization sign in with OAuth.
+
 ## Discovery and client onboarding
 
 Public [RFC 9728](https://www.rfc-editor.org/rfc/rfc9728.html) metadata is served at
@@ -126,7 +147,7 @@ Each incoming token has its own client and cache, even when two tokens name the
 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
+minutes. `FMSG_MCP_KEY_CACHE_TTL_SECONDS` applies only to API-key callers 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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@markmnl/fmsg-mcp",
   "mcpName": "io.github.markmnl/fmsg-mcp",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "MCP server for fmsg: send and receive federated messages from any AI agent via a deployed fmsg Web API",
   "type": "module",
   "license": "MIT",

package/server.json

@@ -8,13 +8,13 @@
     "url": "https://github.com/markmnl/fmsg-mcp",
     "source": "github"
   },
-  "version": "0.2.3",
+  "version": "0.2.4",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@markmnl/fmsg-mcp",
-      "version": "0.2.3",
+      "version": "0.2.4",
       "transport": {
         "type": "stdio"
       },