@markmnl/fmsg-mcp 0.2.3 → 0.2.5

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+- Add `FMSG_DEFAULT_DOMAIN=caller` (case-insensitive): short names resolve on the domain of the
+  address the server acts as for each request, so a deployment serving callers on several domains
+  resolves `bob` to `@bob@example.org` for `@mark@example.org` and `@bob@example.net` for a caller
+  on `example.net`. `whoami`'s `default_domain` and the server instructions show the caller's
+  domain. Over stdio, `resolve_address` first looks up the configured key's address. Directory
+  entries still take precedence; a fixed or unset default domain is unchanged.
+- 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,17 +156,17 @@ 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_DEFAULT_DOMAIN` | — | Lets short names resolve: `bob` → `@bob@<domain>`. `caller` resolves them on the domain of the address the server acts as for each request, so `@mark@example.org` gets `@bob@example.org`; directory entries still take precedence |
 | `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_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/address.d.ts

@@ -8,10 +8,21 @@ export declare function normalizeFmsgAddress(value: string): string | undefined;
 /** Case-insensitive address equality. */
 export declare function sameAddress(a: string, b: string): boolean;
 export declare function isFmsgAddress(value: string): boolean;
+/** Reserved FMSG_DEFAULT_DOMAIN value: short names resolve on the caller's own domain. */
+export declare const CALLER_DOMAIN = "caller";
+/**
+ * The domain short names resolve to: the configured default domain, or with
+ * `caller` the domain of the address the server acts as. Undefined when neither
+ * is known (no default domain, or `caller` before the caller address is known).
+ */
+export declare function effectiveDefaultDomain(defaultDomain: string | undefined, callerAddress?: string): string | undefined;
 export type Resolution = "literal" | "directory" | "default_domain";
 export type AddressResolver = {
+    /** A domain, or CALLER_DOMAIN to use the domain of `callerAddress`. */
     defaultDomain?: string;
     directory?: Record<string, string>;
+    /** The address the server acts as, when known. */
+    callerAddress?: string;
 };
 export type ResolvedAddress = {
     address: string;
@@ -19,7 +30,8 @@ export type ResolvedAddress = {
 };
 /**
  * Resolve a full address or short name: literal `@user@domain` first, then a
- * configured directory entry, then `@name@<default domain>`.
+ * configured directory entry, then `@name@<default domain>` (the caller's own
+ * domain when the default domain is `caller`).
  */
 export declare function resolveAddress(name: string, resolver?: AddressResolver): ResolvedAddress;
 export declare function resolveAddresses(names: string[], resolver?: AddressResolver): string[];

package/dist/address.js

@@ -19,9 +19,23 @@ export function sameAddress(a, b) {
 export function isFmsgAddress(value) {
     return normalizeFmsgAddress(value) !== undefined;
 }
+/** Reserved FMSG_DEFAULT_DOMAIN value: short names resolve on the caller's own domain. */
+export const CALLER_DOMAIN = "caller";
+/**
+ * The domain short names resolve to: the configured default domain, or with
+ * `caller` the domain of the address the server acts as. Undefined when neither
+ * is known (no default domain, or `caller` before the caller address is known).
+ */
+export function effectiveDefaultDomain(defaultDomain, callerAddress) {
+    if (defaultDomain !== CALLER_DOMAIN)
+        return defaultDomain;
+    const match = callerAddress ? ADDRESS.exec(callerAddress.trim()) : null;
+    return match ? match[2].toLowerCase() : undefined;
+}
 /**
  * Resolve a full address or short name: literal `@user@domain` first, then a
- * configured directory entry, then `@name@<default domain>`.
+ * configured directory entry, then `@name@<default domain>` (the caller's own
+ * domain when the default domain is `caller`).
  */
 export function resolveAddress(name, resolver = {}) {
     const trimmed = name.trim();
@@ -41,8 +55,9 @@ export function resolveAddress(name, resolver = {}) {
             return { address, resolution: "directory" };
         }
     }
-    if (resolver.defaultDomain) {
-        const address = normalizeFmsgAddress(`@${trimmed}@${resolver.defaultDomain}`);
+    const domain = effectiveDefaultDomain(resolver.defaultDomain, resolver.callerAddress);
+    if (domain) {
+        const address = normalizeFmsgAddress(`@${trimmed}@${domain}`);
         if (address)
             return { address, resolution: "default_domain" };
     }

package/dist/config.d.ts

@@ -25,6 +25,7 @@ export type Config = {
     allowInsecureHttp?: boolean;
     /** Only set in stdio mode. */
     apiKey?: string;
+    /** Domain for short names, or CALLER_DOMAIN for each caller's own domain. */
     defaultDomain?: string;
     directory?: Record<string, string>;
     /** Trusted local destination; enables save_attachment over stdio only. */

package/dist/config.js

@@ -1,5 +1,5 @@
 import { readFileSync } from "node:fs";
-import { normalizeFmsgAddress } from "./address.js";
+import { CALLER_DOMAIN, normalizeFmsgAddress } from "./address.js";
 import { normalizeApiUrl, normalizeOrigin } from "./client/url.js";
 import { loadOAuthConfig, oauthUrl } from "./oauth/config.js";
 export const DEFAULT_HTTP_PORT = 8765;
@@ -74,7 +74,8 @@ export function loadConfig(env, transport, overrides = {}, options = {}) {
     if (transport === "http" && apiKey) {
         throw new Error("FMSG_API_KEY must not be set in HTTP mode: each client supplies its own bearer credential");
     }
-    const defaultDomain = env.FMSG_DEFAULT_DOMAIN?.trim().replace(/^@/u, "") || undefined;
+    const rawDefaultDomain = env.FMSG_DEFAULT_DOMAIN?.trim().replace(/^@/u, "") || undefined;
+    const defaultDomain = rawDefaultDomain?.toLowerCase() === CALLER_DOMAIN ? CALLER_DOMAIN : rawDefaultDomain;
     const directoryPath = env.FMSG_DIRECTORY?.trim();
     const port = overrides.port ?? intEnv(env, "FMSG_MCP_PORT", DEFAULT_HTTP_PORT, 0);
     if (!Number.isInteger(port) || port < 0 || port > 65535)

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,11 +24,13 @@ 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
-  FMSG_DEFAULT_DOMAIN        lets short names resolve: bob -> @bob@<domain>
+  FMSG_DEFAULT_DOMAIN        lets short names resolve: bob -> @bob@<domain>; caller
+                            uses the domain of each caller's own address
   FMSG_DIRECTORY             JSON file mapping short names to @user@domain
   FMSG_MCP_DOWNLOAD_DIR      enables save_attachment to this local folder (stdio)
   FMSG_MCP_WAIT_MAX_SECONDS  cap on one wait_for_message call (default 230)

package/dist/instructions.d.ts

@@ -1,12 +1,7 @@
-/**
- * Server instructions: returned in the MCP `initialize` result and folded into
- * the model's system prompt by hosts. Three jobs only: precedence over other
- * fmsg access paths, the irreversible-send rule, and the usage facts a model
- * otherwise gets wrong. Per-tool detail lives in the tool descriptions.
- */
 export type InstructionsContext = {
     /** The address this server acts as, when already known (HTTP callers; stdio after a token exchange). */
     address?: string;
+    /** FMSG_DEFAULT_DOMAIN: a domain, or CALLER_DOMAIN for the caller's own domain. */
     defaultDomain?: string;
 };
 export declare function buildInstructions(ctx?: InstructionsContext): string;

package/dist/instructions.js

@@ -1,10 +1,20 @@
+/**
+ * Server instructions: returned in the MCP `initialize` result and folded into
+ * the model's system prompt by hosts. Three jobs only: precedence over other
+ * fmsg access paths, the irreversible-send rule, and the usage facts a model
+ * otherwise gets wrong. Per-tool detail lives in the tool descriptions.
+ */
+import { CALLER_DOMAIN, effectiveDefaultDomain } from "./address.js";
 export function buildInstructions(ctx = {}) {
     const identity = ctx.address
         ? `you are acting as ${ctx.address}`
         : "call whoami to see which";
-    const shortNames = ctx.defaultDomain
-        ? `; short names resolve to @name@${ctx.defaultDomain}`
-        : "";
+    const domain = effectiveDefaultDomain(ctx.defaultDomain, ctx.address);
+    const shortNames = domain
+        ? `; short names resolve to @name@${domain}`
+        : ctx.defaultDomain === CALLER_DOMAIN
+            ? "; short names resolve to @name@<your domain>, the domain of the address you act as"
+            : "";
     return [
         `This server sends and receives fmsg messages as one fmsg address: ${identity}. ` +
             "Use its tools for everything fmsg: inbox, threads, attachments, sending, replying, reactions, " +

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/dist/tools/common.d.ts

@@ -1,5 +1,6 @@
 import type { CallToolResult, McpServer, ServerContext, ToolAnnotations } from "@modelcontextprotocol/server";
 import * as z from "zod/v4";
+import type { AddressResolver } from "../address.js";
 import type { FmsgMessage } from "../client/types.js";
 import type { Config } from "../config.js";
 import { type Caller, type CallerProvider } from "../context.js";
@@ -57,6 +58,8 @@ export type MessageItem = z.infer<typeof messageItem>;
 export declare function toItem(m: FmsgMessage, self: string): MessageItem;
 export declare function deliveryOf(m: FmsgMessage): z.infer<typeof deliveryItem>[];
 export declare function ok(text: string, structured: Record<string, unknown>): CallToolResult;
+/** Short-name resolution for this caller: the configured directory and default domain. */
+export declare function resolverFor(deps: ToolDeps, caller: Caller): AddressResolver;
 /** Resolve the caller and run a tool body, turning any failure into an `isError` result. */
 export declare function withCaller(deps: ToolDeps, ctx: ServerContext, body: (caller: Caller, signal: AbortSignal) => Promise<CallToolResult>): Promise<CallToolResult>;
 export type Register = (server: McpServer, deps: ToolDeps) => void;

package/dist/tools/common.js

@@ -72,6 +72,10 @@ export function deliveryOf(m) {
 export function ok(text, structured) {
     return { content: [{ type: "text", text }], structuredContent: structured };
 }
+/** Short-name resolution for this caller: the configured directory and default domain. */
+export function resolverFor(deps, caller) {
+    return { ...deps.config, callerAddress: caller.address };
+}
 /** Resolve the caller and run a tool body, turning any failure into an `isError` result. */
 export async function withCaller(deps, ctx, body) {
     let caller;

package/dist/tools/identity.js

@@ -1,7 +1,7 @@
 import * as z from "zod/v4";
-import { resolveAddress } from "../address.js";
+import { CALLER_DOMAIN, effectiveDefaultDomain, resolveAddress } from "../address.js";
 import { isoTime } from "../render.js";
-import { READ_ONLY, ok, withCaller } from "./common.js";
+import { READ_ONLY, ok, resolverFor, withCaller } from "./common.js";
 import { toolError } from "../errors.js";
 export const registerIdentityTools = (server, deps) => {
     server.registerTool("whoami", {
@@ -21,12 +21,13 @@ export const registerIdentityTools = (server, deps) => {
         annotations: { ...READ_ONLY, openWorldHint: false },
     }, async (ctx) => withCaller(deps, ctx, async (caller) => {
         const expires = isoTime((await caller.tokenExpiresAt()) / 1000);
+        const defaultDomain = effectiveDefaultDomain(deps.config.defaultDomain, caller.address);
         const structured = {
             address: caller.address,
             api_url: deps.config.apiPublicUrl ?? null,
             token_expires_at: expires,
             transport: deps.config.transport,
-            default_domain: deps.config.defaultDomain ?? null,
+            default_domain: defaultDomain ?? null,
             directory_names: Object.keys(deps.config.directory ?? {}),
         };
         const lines = [
@@ -35,8 +36,8 @@ export const registerIdentityTools = (server, deps) => {
                 : `You are **${caller.address}** (${deps.config.transport}).`,
             `Access token expires ${expires ?? "unknown"} and is renewed automatically.`,
         ];
-        if (deps.config.defaultDomain)
-            lines.push(`Short names resolve to @name@${deps.config.defaultDomain}.`);
+        if (defaultDomain)
+            lines.push(`Short names resolve to @name@${defaultDomain}.`);
         if (structured.directory_names.length)
             lines.push(`Directory names: ${structured.directory_names.join(", ")}.`);
         return ok(lines.join("\n"), structured);
@@ -49,13 +50,19 @@ export const registerIdentityTools = (server, deps) => {
         inputSchema: z.object({ name: z.string().describe("Full fmsg address (@user@domain) or a short name") }),
         outputSchema: z.object({ address: z.string(), resolution: z.enum(["literal", "directory", "default_domain"]) }),
         annotations: { ...READ_ONLY, openWorldHint: false },
-    }, async ({ name }) => {
-        try {
-            const resolved = resolveAddress(name, deps.config);
-            return ok(`${name} → ${resolved.address} (${resolved.resolution})`, resolved);
-        }
-        catch (error) {
-            return toolError(error instanceof Error ? error.message : String(error));
-        }
+    }, async ({ name }, ctx) => {
+        const resolve = (resolver) => {
+            try {
+                const resolved = resolveAddress(name, resolver);
+                return ok(`${name} → ${resolved.address} (${resolved.resolution})`, resolved);
+            }
+            catch (error) {
+                return toolError(error instanceof Error ? error.message : String(error));
+            }
+        };
+        // Only the caller's own domain needs the caller; otherwise resolution is local.
+        if (deps.config.defaultDomain !== CALLER_DOMAIN)
+            return resolve(deps.config);
+        return withCaller(deps, ctx, async (caller) => resolve(resolverFor(deps, caller)));
     });
 };

package/dist/tools/send.js

@@ -2,7 +2,7 @@ import * as z from "zod/v4";
 import { resolveAddresses, sameAddress } from "../address.js";
 import { toolError } from "../errors.js";
 import { isoTime, participantsOf } from "../render.js";
-import { READ_ONLY, SENDS, idSchema, ok, withCaller } from "./common.js";
+import { READ_ONLY, SENDS, idSchema, ok, resolverFor, withCaller } from "./common.js";
 const IMMUTABLE = "fmsg messages are immutable: once sent they cannot be edited or recalled. Send within the user's requested task or authorized automation.";
 const attachmentInput = z.object({
     filename: z.string().regex(/^[A-Za-z0-9._-]+$/u, "letters, digits, dot, underscore, hyphen only"),
@@ -47,7 +47,7 @@ export const registerSendTools = (server, deps) => {
         outputSchema: sentOutput,
         annotations: SENDS,
     }, async ({ to, topic, body, type, important, no_reply, attachments }, ctx) => withCaller(deps, ctx, async (caller, signal) => {
-        const recipients = resolveAddresses(to, deps.config);
+        const recipients = resolveAddresses(to, resolverFor(deps, caller));
         const sent = await caller.client.send({
             to: recipients,
             topic,
@@ -101,7 +101,7 @@ export const registerSendTools = (server, deps) => {
         }
         const warnings = [];
         const to = recipients?.length
-            ? resolveAddresses(recipients, deps.config)
+            ? resolveAddresses(recipients, resolverFor(deps, caller))
             : participantsOf(parent).filter((a) => !sameAddress(a, caller.address));
         if (to.length === 0)
             return toolError(`message ${id} has no other participants to reply to; pass recipients`);
@@ -141,7 +141,7 @@ export const registerSendTools = (server, deps) => {
         outputSchema: z.object({ id: z.string(), added: z.number(), add_to: z.array(z.string()) }),
         annotations: { ...SENDS, idempotentHint: true },
     }, async ({ id, add_to }, ctx) => withCaller(deps, ctx, async (caller, signal) => {
-        const addresses = resolveAddresses(add_to, deps.config);
+        const addresses = resolveAddresses(add_to, resolverFor(deps, caller));
         const result = await caller.client.addRecipients(id, addresses, signal);
         return ok(`Added ${result.added} recipient(s) to message ${id}: ${addresses.join(", ")}`, { ...result, add_to: addresses });
     }));

package/dist/tools/wait.js

@@ -3,7 +3,7 @@ import { resolveAddress } from "../address.js";
 import { assembleThread, renderThread } from "../thread.js";
 import { DATA_NOT_INSTRUCTIONS, fence, headerValue, messageData, messageLine } from "../render.js";
 import { waitForMessage } from "../wait.js";
-import { READ_ONLY, idSchema, messageItem, ok, toItem, withCaller } from "./common.js";
+import { READ_ONLY, idSchema, messageItem, ok, resolverFor, toItem, withCaller } from "./common.js";
 export const registerWaitTools = (server, deps) => {
     const maxWait = deps.config.waitMaxSeconds;
     server.registerTool("wait_for_message", {
@@ -41,7 +41,7 @@ export const registerWaitTools = (server, deps) => {
         const result = await waitForMessage(caller.client, caller.address, {
             ...(after_id !== undefined ? { afterId: after_id } : {}),
             ...(thread_of !== undefined ? { threadOf: thread_of } : {}),
-            ...(from !== undefined ? { from: resolveAddress(from, deps.config).address } : {}),
+            ...(from !== undefined ? { from: resolveAddress(from, resolverFor(deps, caller)).address } : {}),
             timeoutMs: timeout_seconds * 1000,
             settleMs: settle_seconds * 1000,
             onTick: (elapsed) => {

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 \
@@ -15,6 +15,11 @@ 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.
 
+When callers have addresses on several domains, set `FMSG_DEFAULT_DOMAIN=caller` rather than one
+fixed domain: short names then resolve on each caller's own domain, so `bob` is `@bob@example.org`
+for `@mark@example.org` and `@bob@example.net` for a caller on `example.net`. `whoami` and the
+server instructions show that caller's domain. `FMSG_DIRECTORY` entries still take precedence.
+
 If the server reaches the Web API at an internal address instead, for example
 `FMSG_API_URL=http://10.0.0.5:8000` with `FMSG_ALLOW_INSECURE_HTTP=1` on a private network, also set
 `FMSG_API_PUBLIC_URL=https://api.example.com` so `whoami` reports the URL users know. Without it,
@@ -54,8 +59,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.5",
   "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.5",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@markmnl/fmsg-mcp",
-      "version": "0.2.3",
+      "version": "0.2.5",
       "transport": {
         "type": "stdio"
       },