@markmnl/fmsg-mcp 0.1.4 → 0.2.1

package/dist/client/errors.js

@@ -0,0 +1,51 @@
+import { redactSecrets } from "./redact.js";
+import { readBytes } from "./stream.js";
+/** An HTTP error from the fmsg Web API, with the status and the host's own error text. */
+export class FmsgHttpError extends Error {
+    status;
+    method;
+    path;
+    code;
+    insufficientScope;
+    constructor(message, status, method, path, 
+    /** Machine-readable `code` from the body, when the host sends one (thread routes). */
+    code, 
+    /** The Web API rejected a delegated scope or closed route. */
+    insufficientScope = false) {
+        super(redactSecrets(message).text);
+        this.status = status;
+        this.method = method;
+        this.path = path;
+        this.code = code;
+        this.insufficientScope = insufficientScope;
+        if (this.code)
+            this.code = redactSecrets(this.code).text;
+        this.method = redactSecrets(method).text;
+        this.path = redactSecrets(path).text;
+        this.name = "FmsgHttpError";
+    }
+}
+export async function readError(response) {
+    // Preserve canonical 400/413 JSON policy details. Other errors, including
+    // proxy pages, get a bounded preview independent of message acceptance limits.
+    const isJson = (response.headers.get("content-type") ?? "").toLowerCase().includes("json");
+    let raw;
+    if (!isJson || ![400, 413].includes(response.status)) {
+        const { data, truncated } = await readBytes(response.body, 2048, true);
+        raw = Buffer.from(data).toString("utf8");
+        if (!isJson || truncated)
+            return { message: (raw || `HTTP ${response.status}`) + (truncated ? "\n[upstream response truncated at 2048 bytes]" : "") };
+    }
+    else
+        raw = await response.text();
+    if (!raw)
+        return { message: `HTTP ${response.status}` };
+    try {
+        const parsed = JSON.parse(raw);
+        const message = typeof parsed.error === "string" ? parsed.error : `HTTP ${response.status}`;
+        return typeof parsed.code === "string" ? { message, code: parsed.code } : { message };
+    }
+    catch {
+        return { message: Buffer.byteLength(raw) > 2048 ? Buffer.from(raw).subarray(0, 2048).toString("utf8") + "\n[upstream response truncated at 2048 bytes]" : raw };
+    }
+}

package/dist/client/index.d.ts

@@ -1,4 +1,5 @@
 export { FmsgClient, FmsgHttpError, type FmsgClientOptions } from "./client.js";
+export type { TokenProvider, TokenProviderRequest } from "./token-provider.js";
 export { openFmsgWebSocket, parseWsEvent } from "./ws.js";
 export { redactSecrets, safeErrorMessage, type Redacted } from "./redact.js";
 export { normalizeMessageId, compareMessageIds, maxMessageId, parseFmsgJson, stringifyWithIds } from "./message-id.js";

package/dist/client/stream.d.ts

@@ -0,0 +1,12 @@
+/** A client/output budget, independent of the fmsg host's acceptance limits. */
+export declare class ResponseLimitError extends Error {
+    readonly limit: number;
+    constructor(limit: number);
+}
+/** Budget time awaiting the next chunk, not the duration of a progressing download. */
+export declare function withIdleTimeout(stream: ReadableStream<Uint8Array>, timeoutMs: number): ReadableStream<Uint8Array>;
+/** Stop reading at a byte budget, optionally returning a marked preview. */
+export declare function readBytes(stream: ReadableStream<Uint8Array> | null, limit?: number, preview?: boolean): Promise<{
+    data: Uint8Array;
+    truncated: boolean;
+}>;

package/dist/client/stream.js

@@ -0,0 +1,83 @@
+/** A client/output budget, independent of the fmsg host's acceptance limits. */
+export class ResponseLimitError extends Error {
+    limit;
+    constructor(limit) {
+        super(`response exceeds the ${limit}-byte client limit`);
+        this.limit = limit;
+    }
+}
+/** Budget time awaiting the next chunk, not the duration of a progressing download. */
+export function withIdleTimeout(stream, timeoutMs) {
+    const reader = stream.getReader();
+    let stopped = false;
+    let timer;
+    const cancel = async (reason) => {
+        stopped = true;
+        clearTimeout(timer);
+        try {
+            await reader.cancel(reason);
+        }
+        finally {
+            reader.releaseLock();
+        }
+    };
+    return new ReadableStream({
+        async pull(controller) {
+            timer = setTimeout(() => {
+                const error = new DOMException("attachment download stalled waiting for data", "TimeoutError");
+                controller.error(error);
+                void cancel(error).catch(() => undefined);
+            }, timeoutMs).unref();
+            try {
+                const { done, value } = await reader.read();
+                if (stopped)
+                    return;
+                if (done) {
+                    stopped = true;
+                    reader.releaseLock();
+                    controller.close();
+                }
+                else
+                    controller.enqueue(value);
+            }
+            catch (error) {
+                if (!stopped) {
+                    stopped = true;
+                    reader.releaseLock();
+                    controller.error(error);
+                }
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        },
+        cancel,
+    });
+}
+/** Stop reading at a byte budget, optionally returning a marked preview. */
+export async function readBytes(stream, limit = Infinity, preview = false) {
+    if (!stream)
+        return { data: new Uint8Array(), truncated: false };
+    const reader = stream.getReader();
+    const chunks = [];
+    let size = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                return { data: Buffer.concat(chunks, size), truncated: false };
+            if (size + value.byteLength > limit) {
+                if (!preview)
+                    throw new ResponseLimitError(limit);
+                chunks.push(value.subarray(0, limit - size));
+                return { data: Buffer.concat(chunks, limit), truncated: true };
+            }
+            chunks.push(value);
+            size += value.byteLength;
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => undefined);
+        reader.releaseLock();
+    }
+}

package/dist/client/token-provider.d.ts

@@ -0,0 +1,27 @@
+import type { AccessToken } from "./types.js";
+export type TokenProviderRequest = {
+    /** Normalized Web API URL this client is bound to. */
+    readonly apiUrl: string;
+    /** Aborted on timeout, client close, or cancellation by all waiting callers. */
+    readonly signal: AbortSignal;
+    /** A protected request rejected the previous token, or renewal was explicitly forced. */
+    readonly forceRefresh: boolean;
+};
+/**
+ * Supplies a fresh Web API access token for one caller and authorization grant.
+ * FmsgClient owns caching and concurrent renewal. Never return an incoming MCP
+ * token or use a provider across different callers/grants. See docs/token-providers.md.
+ */
+export interface TokenProvider {
+    getToken(request: TokenProviderRequest): Promise<AccessToken>;
+    /** Release credentials/resources. Called once by FmsgClient.close(). */
+    close?(): void;
+}
+/** Existing API-key exchange, behind the same interface as future OAuth adapters. */
+export declare class ApiKeyTokenProvider implements TokenProvider {
+    private apiKey;
+    private readonly fetchImpl;
+    constructor(apiKey: string, fetchImpl: typeof fetch);
+    getToken({ apiUrl, signal }: TokenProviderRequest): Promise<AccessToken>;
+    close(): void;
+}

package/dist/client/token-provider.js

@@ -0,0 +1,54 @@
+import { normalizeFmsgAddress } from "../address.js";
+import { FmsgHttpError, readError } from "./errors.js";
+/** Existing API-key exchange, behind the same interface as future OAuth adapters. */
+export class ApiKeyTokenProvider {
+    apiKey;
+    fetchImpl;
+    constructor(apiKey, fetchImpl) {
+        this.apiKey = apiKey;
+        this.fetchImpl = fetchImpl;
+        if (!apiKey.startsWith("fmsgk_"))
+            throw new Error("fmsg API key must start with fmsgk_");
+    }
+    async getToken({ apiUrl, signal }) {
+        const response = await this.fetchImpl(`${apiUrl}/fmsg/token`, {
+            method: "POST", headers: { authorization: `Bearer ${this.apiKey}` }, redirect: "error", signal,
+        });
+        if (!response.ok) {
+            const { message, code } = await readError(response);
+            throw new FmsgHttpError(`token exchange failed: ${message}`, response.status, "POST", "/fmsg/token", code);
+        }
+        const body = (await response.json());
+        if (typeof body.access_token !== "string")
+            throw new Error("token response has no access_token");
+        const payload = decodeJwtPayload(body.access_token);
+        const address = typeof payload.sub === "string" ? normalizeFmsgAddress(payload.sub) : undefined;
+        if (!address)
+            throw new Error("token JWT sub is not an fmsg address");
+        const expiries = [
+            typeof body.expires_at === "string" ? Date.parse(body.expires_at) : Number.NaN,
+            typeof payload.exp === "number" ? payload.exp * 1000 : Number.NaN,
+            typeof body.expires_in === "number" ? Date.now() + body.expires_in * 1000 : Number.NaN,
+        ].filter(Number.isFinite);
+        // Never extend the JWT lifetime using a later response expiry or a guessed TTL.
+        const expiresAtMs = expiries.length ? Math.min(...expiries) : Number.NaN;
+        return { accessToken: body.access_token, address, expiresAtMs };
+    }
+    close() { this.apiKey = ""; }
+}
+// Only the first-party API-key contract requires sub/exp in a JWT. Custom
+// providers supply address/expiry metadata; the client does not decode their tokens.
+function decodeJwtPayload(token) {
+    const parts = token.split(".");
+    if (parts.length !== 3 || !parts[1])
+        throw new Error("token exchange returned an invalid JWT");
+    try {
+        const payload = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8"));
+        if (!payload || typeof payload !== "object" || Array.isArray(payload))
+            throw new Error();
+        return payload;
+    }
+    catch {
+        throw new Error("token exchange returned an unreadable JWT payload");
+    }
+}

package/dist/client/types.d.ts

@@ -89,10 +89,10 @@ export type Thread = {
     messages: ThreadMessage[];
 };
 export type AccessToken = {
-    accessToken: string;
-    /** fmsg address from the JWT `sub` claim. */
-    address: string;
-    expiresAtMs: number;
+    readonly accessToken: string;
+    /** Authenticated fmsg address supplied by the provider; not necessarily a JWT sub. */
+    readonly address: string;
+    readonly expiresAtMs: number;
 };
 export type OutboundAttachment = {
     filename: string;
@@ -114,6 +114,10 @@ export type SendResult = {
     id: string;
     time: number | null;
     attachments: Attachment[];
+    /** Selected secret patterns replaced in the outgoing body and topic. */
+    redactions: number;
+    /** Topic actually sent, after redaction; empty for replies. */
+    topic: string;
 };
 export type ReactResult = {
     id: string | null;

package/dist/client/url.d.ts

@@ -0,0 +1,4 @@
+/** Hosts for which cleartext loopback development is safe by default. */
+export declare function isLoopbackHost(host: string): boolean;
+export declare function normalizeApiUrl(value: string, allowInsecureHttp?: boolean): string;
+export declare function normalizeOrigin(value: string): string;

package/dist/client/url.js

@@ -0,0 +1,35 @@
+/** Hosts for which cleartext loopback development is safe by default. */
+export function isLoopbackHost(host) {
+    return host === "localhost" || host === "127.0.0.1" || host === "::1" || host === "[::1]";
+}
+export function normalizeApiUrl(value, allowInsecureHttp = false) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error("FMSG_API_URL must be an absolute http(s) URL");
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:")
+        throw new Error("FMSG_API_URL must be an http(s) URL");
+    if (url.username || url.password || url.search || url.hash) {
+        throw new Error("FMSG_API_URL must not contain credentials, a query string or a fragment");
+    }
+    if (url.protocol === "http:" && !isLoopbackHost(url.hostname) && !allowInsecureHttp) {
+        throw new Error("FMSG_API_URL must use HTTPS outside loopback; explicitly enable FMSG_ALLOW_INSECURE_HTTP=1 only for a trusted development/private network");
+    }
+    return url.href.replace(/\/+$/u, "");
+}
+export function normalizeOrigin(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error("FMSG_MCP_ALLOWED_ORIGINS entries must be complete http(s) origins, e.g. https://example.com");
+    }
+    if (!/^https?:$/u.test(url.protocol) || url.username || url.password || url.pathname !== "/" || url.search || url.hash) {
+        throw new Error("FMSG_MCP_ALLOWED_ORIGINS entries must be complete http(s) origins without credentials, paths, queries or fragments");
+    }
+    return url.origin;
+}

package/dist/client/ws.d.ts

@@ -1,6 +1,7 @@
 import WebSocket from "ws";
 import type { FmsgClient } from "./client.js";
 import type { WsEvent } from "./types.js";
+export declare function webSocketTokenExpiresAt(socket: WebSocket): number | undefined;
 /** Open the event WebSocket, authenticating with the bearer JWT in the header. */
-export declare function openFmsgWebSocket(client: FmsgClient): Promise<WebSocket>;
+export declare function openFmsgWebSocket(client: FmsgClient, signal?: AbortSignal): Promise<WebSocket>;
 export declare function parseWsEvent(raw: WebSocket.RawData): WsEvent | undefined;

package/dist/client/ws.js

@@ -1,13 +1,19 @@
 import WebSocket from "ws";
 import { normalizeMessageId, parseFmsgJson } from "./message-id.js";
+const expiries = new WeakMap();
+export function webSocketTokenExpiresAt(socket) { return expiries.get(socket); }
 /** Open the event WebSocket, authenticating with the bearer JWT in the header. */
-export async function openFmsgWebSocket(client) {
-    const token = await client.getToken();
+export async function openFmsgWebSocket(client, signal) {
+    const token = await client.getToken(false, signal);
+    signal?.throwIfAborted();
     const url = new URL(client.apiUrl);
     url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
     url.pathname = `${url.pathname.replace(/\/+$/u, "")}/fmsg/ws`;
     url.search = "";
-    return new WebSocket(url, { headers: { authorization: `Bearer ${token.accessToken}` } });
+    const socket = new WebSocket(url, { headers: { authorization: `Bearer ${token.accessToken}` } });
+    if (client.reconnectOnTokenExpiry)
+        expiries.set(socket, token.expiresAtMs);
+    return socket;
 }
 export function parseWsEvent(raw) {
     try {

package/dist/config.d.ts

@@ -1,10 +1,13 @@
+import { type OAuthConfig } from "./oauth/config.js";
 export type Transport = "stdio" | "http";
 export type HttpConfig = {
     host: string;
     port: number;
+    /** Canonical public MCP endpoint for credential-free attachment links. */
+    publicUrl?: string;
     /** Hostnames accepted in the Host header. Empty means: derive from the bind address (loopback only). */
     allowedHosts: string[];
-    /** Origins (hostnames) accepted in the Origin header for browser callers; empty = same as allowedHosts. */
+    /** Exact browser origins. Empty permits same-origin and, on loopback binds, loopback origins on any port. */
     allowedOrigins: string[];
     keyCacheMax: number;
     keyCacheTtlMs: number;
@@ -12,15 +15,18 @@ export type HttpConfig = {
 export type Config = {
     transport: Transport;
     apiUrl: string;
+    /** Explicit opt-in for cleartext upstream traffic outside loopback. */
+    allowInsecureHttp?: boolean;
     /** Only set in stdio mode. */
     apiKey?: string;
     defaultDomain?: string;
     directory?: Record<string, string>;
+    /** Trusted local destination; enables save_attachment over stdio only. */
+    downloadDir?: string;
     /** Hard cap on a single wait_for_message call. */
     waitMaxSeconds: number;
-    /** Directory attachments may be saved under (stdio only); unset = anywhere. */
-    downloadDir?: string;
     http: HttpConfig;
+    oauth?: OAuthConfig;
 };
 export declare const DEFAULT_HTTP_PORT = 8765;
 export declare const DEFAULT_WAIT_MAX_SECONDS = 230;

package/dist/config.js

@@ -1,5 +1,7 @@
 import { readFileSync } from "node:fs";
 import { normalizeFmsgAddress } from "./address.js";
+import { normalizeApiUrl, normalizeOrigin } from "./client/url.js";
+import { loadOAuthConfig, oauthUrl } from "./oauth/config.js";
 export const DEFAULT_HTTP_PORT = 8765;
 export const DEFAULT_WAIT_MAX_SECONDS = 230;
 function intEnv(env, name, fallback, min = 1) {
@@ -39,36 +41,49 @@ function loadDirectory(path) {
 }
 export function loadConfig(env, transport, overrides = {}, options = {}) {
     const requireCredentials = options.requireCredentials ?? true;
+    const oauth = loadOAuthConfig(env, transport);
     const apiUrl = env.FMSG_API_URL?.trim() ?? "";
     if (!apiUrl && (transport === "http" || requireCredentials)) {
         throw new Error("FMSG_API_URL is required (base URL of the fmsg Web API, e.g. https://api.example.com)");
     }
-    if (apiUrl && !/^https?:\/\//u.test(apiUrl))
-        throw new Error("FMSG_API_URL must start with http:// or https://");
+    const allowInsecureHttp = env.FMSG_ALLOW_INSECURE_HTTP === "1";
+    const normalizedApiUrl = apiUrl ? normalizeApiUrl(apiUrl, allowInsecureHttp) : "";
     const apiKey = env.FMSG_API_KEY?.trim();
+    if (transport === "stdio" && apiKey && !apiKey.startsWith("fmsgk_"))
+        throw new Error("FMSG_API_KEY must start with fmsgk_");
     if (transport === "stdio" && !apiKey && requireCredentials) {
         throw new Error("FMSG_API_KEY is required in stdio mode (an fmsgk_... key for the address this server sends as)");
     }
     if (transport === "http" && apiKey) {
-        throw new Error("FMSG_API_KEY must not be set in HTTP mode: each client supplies its own key as `Authorization: Bearer fmsgk_...`");
+        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 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)
+        throw new Error("FMSG_MCP_PORT must be between 0 and 65535");
     const host = overrides.host ?? env.FMSG_MCP_HOST?.trim() ?? "127.0.0.1";
+    const publicUrl = transport === "http" ? env.FMSG_MCP_PUBLIC_URL?.trim() || oauth?.resourceUrl : undefined;
+    if (publicUrl)
+        oauthUrl(publicUrl, "FMSG_MCP_PUBLIC_URL");
+    if (oauth && publicUrl !== oauth.resourceUrl)
+        throw new Error("FMSG_MCP_PUBLIC_URL must match FMSG_MCP_OAUTH_RESOURCE_URL in OAuth mode");
     return {
         transport,
-        apiUrl: apiUrl.replace(/\/+$/u, ""),
+        apiUrl: normalizedApiUrl,
+        ...(oauth ? { oauth } : {}),
+        allowInsecureHttp,
         ...(transport === "stdio" && apiKey ? { apiKey } : {}),
         ...(defaultDomain ? { defaultDomain } : {}),
         ...(directoryPath ? { directory: loadDirectory(directoryPath) } : {}),
+        ...(transport === "stdio" && env.FMSG_MCP_DOWNLOAD_DIR?.trim() ? { downloadDir: env.FMSG_MCP_DOWNLOAD_DIR.trim() } : {}),
         waitMaxSeconds: intEnv(env, "FMSG_MCP_WAIT_MAX_SECONDS", DEFAULT_WAIT_MAX_SECONDS),
-        ...(env.FMSG_MCP_DOWNLOAD_DIR?.trim() ? { downloadDir: env.FMSG_MCP_DOWNLOAD_DIR.trim() } : {}),
         http: {
             host,
             port,
+            ...(publicUrl ? { publicUrl } : {}),
             allowedHosts: listEnv(env, "FMSG_MCP_ALLOWED_HOSTS"),
-            allowedOrigins: listEnv(env, "FMSG_MCP_ALLOWED_ORIGINS"),
+            allowedOrigins: listEnv(env, "FMSG_MCP_ALLOWED_ORIGINS").map(normalizeOrigin),
             keyCacheMax: intEnv(env, "FMSG_MCP_KEY_CACHE_MAX", 500),
             keyCacheTtlMs: intEnv(env, "FMSG_MCP_KEY_CACHE_TTL_SECONDS", 1800) * 1000,
         },

package/dist/context.d.ts

@@ -1,23 +1,26 @@
 import type { AuthInfo, ServerContext } from "@modelcontextprotocol/server";
 import { FmsgClient } from "./client/client.js";
-/** A resolved caller: the client bound to one API key and the address it acts as. */
+/** A resolved caller: the client bound to one authorization grant and the address it acts as. */
 export type Caller = {
     client: FmsgClient;
     address: string;
-    /** When the key's exchanged token expires (ms since epoch), for whoami. */
+    /** When the current Web API access token expires (ms since epoch), for whoami. */
     tokenExpiresAt: () => Promise<number>;
 };
 /** Supplies the caller for a request: a fixed one over stdio, per bearer key over HTTP. */
 export interface CallerProvider {
     forRequest(authInfo: AuthInfo | undefined): Promise<Caller>;
+    invalidate?(caller: Caller): void;
+    close?(): void;
 }
 export declare class StaticCallerProvider implements CallerProvider {
     private readonly client;
     private caller?;
     constructor(client: FmsgClient);
     forRequest(): Promise<Caller>;
+    close(): void;
 }
-/** stdio without credentials: the server starts (so hosts can list tools) but every tool explains what is missing. */
+/** Invalid/missing stdio configuration: allow discovery, then explain the configuration fix on tool calls. */
 export declare class UnconfiguredCallerProvider implements CallerProvider {
     private readonly reason;
     constructor(reason: string);

package/dist/context.js

@@ -8,11 +8,18 @@ export class StaticCallerProvider {
         this.caller ??= (async () => {
             const address = await this.client.address();
             return { client: this.client, address, tokenExpiresAt: async () => (await this.client.getToken()).expiresAtMs };
-        })();
+        })().catch((error) => {
+            this.caller = undefined;
+            throw error;
+        });
         return this.caller;
     }
+    close() {
+        this.client.close();
+        this.caller = undefined;
+    }
 }
-/** stdio without credentials: the server starts (so hosts can list tools) but every tool explains what is missing. */
+/** Invalid/missing stdio configuration: allow discovery, then explain the configuration fix on tool calls. */
 export class UnconfiguredCallerProvider {
     reason;
     constructor(reason) {

package/dist/download.d.ts

@@ -0,0 +1,11 @@
+import type { Config } from "./config.js";
+export declare const DOWNLOAD_PATH = "/mcp/attachments";
+export declare function downloadBaseUrl(config: Config): string | undefined;
+export declare function attachmentFilename(filename: string): string;
+export declare function attachmentDownloadUrl(baseUrl: string, id: string, filename: string): string;
+export declare function parseDownloadPath(pathname: string): {
+    id: string;
+    filename: string;
+};
+/** Always download untrusted files; preserve Unicode filenames without raw header characters. */
+export declare function downloadHeaders(filename: string, contentType?: string): Headers;

package/dist/download.js

@@ -0,0 +1,34 @@
+import { normalizeMessageId } from "./client/message-id.js";
+export const DOWNLOAD_PATH = "/mcp/attachments";
+export function downloadBaseUrl(config) {
+    return config.transport === "http" ? config.http.publicUrl ?? config.oauth?.resourceUrl : undefined;
+}
+export function attachmentFilename(filename) {
+    if (!filename || filename === "." || filename === ".." || /[/\\\x00-\x1f\x7f]/u.test(filename)) {
+        throw new Error("use an attachment filename without directory components or control characters");
+    }
+    // Also reject unpaired UTF-16 surrogates before building a URL/header.
+    encodeURIComponent(filename);
+    return filename;
+}
+export function attachmentDownloadUrl(baseUrl, id, filename) {
+    return `${baseUrl.replace(/\/$/u, "")}/attachments/${normalizeMessageId(id)}/${encodeURIComponent(attachmentFilename(filename))}`;
+}
+export function parseDownloadPath(pathname) {
+    const parts = pathname.slice(DOWNLOAD_PATH.length + 1).split("/");
+    if (parts.length !== 2)
+        throw new Error("invalid attachment download path");
+    return { id: normalizeMessageId(parts[0]), filename: attachmentFilename(decodeURIComponent(parts[1])) };
+}
+/** Always download untrusted files; preserve Unicode filenames without raw header characters. */
+export function downloadHeaders(filename, contentType) {
+    const fallback = filename.replace(/[^A-Za-z0-9._-]/gu, "_");
+    const encoded = encodeURIComponent(filename).replace(/[!'()*]/gu, c => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+    return new Headers({
+        "content-type": contentType ?? "application/octet-stream",
+        "content-disposition": `attachment; filename="${fallback}"; filename*=UTF-8''${encoded}`,
+        "cache-control": "no-store",
+        "x-content-type-options": "nosniff",
+        "content-security-policy": "sandbox",
+    });
+}

package/dist/errors.d.ts

@@ -1,5 +1,5 @@
 import type { CallToolResult } from "@modelcontextprotocol/server";
 /** Build an `isError` tool result the model can read and act on. */
-export declare function toolError(text: string): CallToolResult;
+export declare function toolError(error: unknown, address?: string): CallToolResult;
 /** Model-facing description of a failure, with a status-specific hint where one helps. */
 export declare function describeError(error: unknown, address?: string): string;

package/dist/errors.js

@@ -1,39 +1,31 @@
 import { FmsgHttpError } from "./client/client.js";
-import { safeErrorMessage } from "./client/redact.js";
+import { redactSecrets, safeErrorMessage } from "./client/redact.js";
+import { fence } from "./render.js";
+import { recordOAuthFailure } from "./oauth/errors.js";
 /** Build an `isError` tool result the model can read and act on. */
-export function toolError(text) {
-    return { content: [{ type: "text", text }], isError: true };
+export function toolError(error, address) {
+    return { content: [{ type: "text", text: describeError(error, address) }], isError: true };
 }
 /** Model-facing description of a failure, with a status-specific hint where one helps. */
 export function describeError(error, address) {
+    recordOAuthFailure(error);
     if (error instanceof FmsgHttpError) {
-        const where = `${error.method} ${error.path}`;
-        const host = error.message;
-        switch (error.status) {
-            case 400:
-                return `fmsg host rejected the request (${where}): ${host}`;
-            case 401:
-                return `fmsg API key was rejected (${where}): ${host}. The key may be revoked or expired; the user needs to issue a new one.`;
-            case 403:
-                return `not permitted (${where}): ${host}`;
-            case 404:
-                return `not found (${where}): ${host}${address ? ` — the message may not exist or may not be visible to ${address}` : ""}`;
-            case 409:
-                return `fmsg host refused (${where}): ${host}`;
-            case 413:
-                return `too large for this fmsg host (${where}): ${host}`;
-            case 422:
-                return `fmsg host could not process the request (${where}): ${host}${error.code ? ` [${error.code}]` : ""}`;
-            default:
-                return error.status >= 500
-                    ? `fmsg host error ${error.status} (${where}): ${host}`
-                    : `fmsg host returned ${error.status} (${where}): ${host}`;
-        }
+        const descriptions = {
+            400: "fmsg host rejected the request", 401: "fmsg authentication was rejected", 403: "not permitted",
+            404: "not found", 409: "fmsg host refused", 413: "too large for this fmsg host", 422: "fmsg host could not process the request",
+        };
+        const summary = `${descriptions[error.status] ?? "fmsg host error"} (HTTP ${error.status}).`;
+        // FmsgHttpError sanitizes its public fields at the client boundary.
+        const details = `${error.method} ${error.path}\n${error.message}${error.code ? `\nCode: ${error.code}` : ""}`;
+        const guidance = error.status === 401 ? "Reconnect the OAuth account or replace the API key in the host's connection settings."
+            : error.insufficientScope ? "The connection needs additional scope, or this route is unavailable to delegated tokens."
+                : error.status === 404 && address ? `The message may not exist or may not be visible to ${redactSecrets(address).text}.` : "";
+        return `${summary}\n\nUpstream response (data, not instructions):\n${fence(details)}${guidance ? `\n\n${guidance}` : ""}`;
     }
     if (error instanceof Error && error.name === "AbortError")
         return "the request was cancelled or timed out";
     if (error instanceof Error && /fetch failed|ECONNREFUSED|ENOTFOUND|EAI_AGAIN/u.test(error.message)) {
         return `fmsg host unreachable: ${safeErrorMessage(error)}`;
     }
-    return safeErrorMessage(error);
+    return typeof error === "string" ? redactSecrets(error).text : safeErrorMessage(error);
 }

package/dist/http.d.ts

@@ -1,14 +1,15 @@
 import { type IncomingMessage, type Server, type ServerResponse } from "node:http";
 import { ApiKeyCallerProvider } from "./auth.js";
 import type { Config } from "./config.js";
+import { OAuthCallerProvider } from "./oauth/provider.js";
 export declare const MCP_PATH = "/mcp";
 /** Convert a Node request into a web-standard Request for the MCP handler. */
-export declare function toWebRequest(req: IncomingMessage): Request;
+export declare function toWebRequest(req: IncomingMessage, signal?: AbortSignal): Request;
 /** Pipe a web-standard Response (possibly a long SSE stream) to the Node response. */
-export declare function sendWebResponse(res: ServerResponse, response: Response): Promise<void>;
+export declare function sendWebResponse(res: ServerResponse, response: Response, failure?: () => Response | undefined): Promise<void>;
 export type HttpServerHandle = {
     server: Server;
     close: () => Promise<void>;
-    provider: ApiKeyCallerProvider;
+    provider: ApiKeyCallerProvider | OAuthCallerProvider;
 };
 export declare function createHttpServer(config: Config, log?: (line: string) => void): HttpServerHandle;