@markmnl/fmsg-mcp 0.1.4 → 0.2.1

package/dist/auth.js

@@ -1,84 +1,150 @@
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { OAuthError, OAuthErrorCode } from "@modelcontextprotocol/server";
 import { FmsgClient, FmsgHttpError } from "./client/client.js";
+import { safeErrorMessage } from "./client/redact.js";
 export const FMSG_SCOPE = "fmsg";
-/**
- * HTTP mode: each request carries an fmsg API key as its bearer token. The key
- * is exchanged once at the fmsg host, and the resulting client (which renews
- * its own JWT) is cached by the key's hash. Raw keys are never stored or logged.
- */
+/** Per-key clients retain credentials for renewal; upstream decides access. */
 export class ApiKeyCallerProvider {
     config;
     log;
     entries = new Map();
+    pending = new Map();
+    pendingClients = new Set();
+    // An opaque request lease survives SDK cloning and pins the caller across eviction.
+    leases = new Map();
+    timer;
+    closed = false;
     constructor(config, log = () => undefined) {
         this.config = config;
         this.log = log;
+        this.timer = setInterval(() => this.evict(), Math.min(config.http.keyCacheTtlMs, 30_000)).unref();
     }
-    static cacheKey(apiKey) {
-        return createHash("sha256").update(apiKey).digest("hex");
+    static cacheKey(apiKey) { return createHash("sha256").update(apiKey).digest("hex"); }
+    releaseEntry(entry) {
+        if (!entry.active && this.entries.get(entry.key) !== entry)
+            entry.caller.client.close();
+    }
+    drop(entry) {
+        if (this.entries.get(entry.key) === entry)
+            this.entries.delete(entry.key);
+        this.releaseEntry(entry);
     }
     evict() {
         const now = Date.now();
-        for (const [key, entry] of this.entries) {
-            if (now - entry.lastUsed > this.config.http.keyCacheTtlMs)
-                this.entries.delete(key);
+        for (const entry of this.entries.values()) {
+            if (now - entry.lastUsed >= this.config.http.keyCacheTtlMs)
+                this.drop(entry);
         }
         while (this.entries.size > this.config.http.keyCacheMax) {
-            const oldest = [...this.entries.entries()].sort((a, b) => a[1].lastUsed - b[1].lastUsed)[0];
+            const oldest = [...this.entries.values()].sort((a, b) => a.lastUsed - b.lastUsed)[0];
             if (!oldest)
                 break;
-            this.entries.delete(oldest[0]);
+            this.drop(oldest);
+        }
+    }
+    async createEntry(token, key) {
+        const client = new FmsgClient(this.config.apiUrl, token, { allowInsecureHttp: this.config.allowInsecureHttp });
+        this.pendingClients.add(client);
+        try {
+            const address = await client.address();
+            if (this.closed)
+                throw new Error("server is closing");
+            const entry = { key, caller: { client, address, tokenExpiresAt: async () => (await client.getToken()).expiresAtMs }, lastUsed: Date.now(), active: 0 };
+            this.entries.set(key, entry);
+            this.log(safeErrorMessage(`authenticated ${address} (key ${key.slice(0, 8)}…)`));
+            return entry;
+        }
+        catch (error) {
+            client.close();
+            throw error;
+        }
+        finally {
+            this.pendingClients.delete(client);
         }
     }
-    /** Bearer verifier for the MCP gate: exchange the key, return the caller's identity. */
     async verifyAccessToken(token) {
-        if (!token.startsWith("fmsgk_")) {
+        if (this.closed)
+            throw new OAuthError(OAuthErrorCode.ServerError, "server is closing");
+        if (!token.startsWith("fmsgk_"))
             throw new OAuthError(OAuthErrorCode.InvalidToken, "bearer token must be an fmsg API key (fmsgk_...)");
-        }
         const key = ApiKeyCallerProvider.cacheKey(token);
-        let entry = this.entries.get(key);
-        if (!entry) {
-            const client = new FmsgClient(this.config.apiUrl, token);
-            let address;
-            try {
-                address = await client.address();
-            }
-            catch (error) {
-                if (error instanceof FmsgHttpError && (error.status === 401 || error.status === 403 || error.status === 400)) {
-                    this.log(`rejected api key ${key.slice(0, 8)}…: ${error.status} ${error.message}`);
-                    throw new OAuthError(OAuthErrorCode.InvalidToken, `fmsg host rejected the API key: ${error.message}`);
+        this.evict();
+        let entry;
+        try {
+            entry = this.entries.get(key);
+            if (!entry) {
+                let pending = this.pending.get(key);
+                if (!pending) {
+                    if (this.pending.size >= this.config.http.keyCacheMax)
+                        throw new Error("too many concurrent token exchanges");
+                    pending = this.createEntry(token, key);
+                    this.pending.set(key, pending);
+                    void pending.finally(() => this.pending.delete(key)).catch(() => undefined);
                 }
-                this.log(`token exchange failed for ${key.slice(0, 8)}…: ${error instanceof Error ? error.message : String(error)}`);
-                throw new OAuthError(OAuthErrorCode.ServerError, "fmsg host unavailable for token exchange");
+                entry = await pending;
             }
-            entry = {
-                caller: { client, address, tokenExpiresAt: async () => (await client.getToken()).expiresAtMs },
-                lastUsed: Date.now(),
-            };
-            this.entries.set(key, entry);
+            entry.active++;
+            entry.lastUsed = Date.now();
             this.evict();
-            this.log(`authenticated ${address} (key ${key.slice(0, 8)}…)`);
+            const expiresAtMs = await entry.caller.tokenExpiresAt();
+            if (this.closed)
+                throw new Error("server is closing");
+            const lease = randomUUID();
+            this.leases.set(lease, entry);
+            return {
+                token: key, clientId: entry.caller.address, scopes: [FMSG_SCOPE],
+                expiresAt: Math.floor(expiresAtMs / 1000), extra: { cacheKey: key, callerLease: lease },
+            };
+        }
+        catch (error) {
+            if (entry) {
+                entry.active--;
+                this.drop(entry);
+            }
+            this.log(safeErrorMessage(`token exchange failed for ${key.slice(0, 8)}…: ${error instanceof Error ? error.message : String(error)}`));
+            if (error instanceof FmsgHttpError && [400, 401, 403].includes(error.status)) {
+                throw new OAuthError(OAuthErrorCode.InvalidToken, `fmsg host rejected the API key: ${safeErrorMessage(error)}`);
+            }
+            throw new OAuthError(OAuthErrorCode.ServerError, "fmsg host unavailable for token exchange");
         }
-        entry.lastUsed = Date.now();
-        const expiresAtMs = await entry.caller.tokenExpiresAt();
-        return {
-            token: key,
-            clientId: entry.caller.address,
-            scopes: [FMSG_SCOPE],
-            expiresAt: Math.floor(expiresAtMs / 1000),
-            extra: { cacheKey: key },
-        };
+    }
+    entryFor(auth) {
+        const lease = auth?.extra?.callerLease;
+        const entry = typeof lease === "string" ? this.leases.get(lease) : undefined;
+        return entry && auth?.token === entry.key && auth.extra?.cacheKey === entry.key &&
+            auth.clientId === entry.caller.address && auth.scopes.includes(FMSG_SCOPE) ? entry : undefined;
     }
     async forRequest(authInfo) {
-        const key = typeof authInfo?.extra?.cacheKey === "string" ? authInfo.extra.cacheKey : authInfo?.token;
-        const entry = key ? this.entries.get(key) : undefined;
-        if (!entry)
+        const entry = this.entryFor(authInfo);
+        if (this.closed || !entry)
             throw new Error("not authenticated: send your fmsg API key as `Authorization: Bearer fmsgk_...`");
         entry.lastUsed = Date.now();
         return entry.caller;
     }
-    get size() {
-        return this.entries.size;
+    /** The HTTP adapter releases this lease when the response or connection ends. */
+    release(authInfo) {
+        const entry = this.entryFor(authInfo);
+        if (!entry)
+            return;
+        this.leases.delete(authInfo.extra.callerLease);
+        entry.active--;
+        this.releaseEntry(entry);
+    }
+    invalidate(caller) {
+        for (const entry of this.entries.values())
+            if (entry.caller === caller)
+                this.drop(entry);
+    }
+    close() {
+        this.closed = true;
+        clearInterval(this.timer);
+        for (const entry of [...this.entries.values(), ...this.leases.values()])
+            entry.caller.client.close();
+        for (const client of this.pendingClients)
+            client.close();
+        this.entries.clear();
+        this.leases.clear();
+        this.pending.clear();
     }
+    get size() { return this.entries.size; }
 }

package/dist/client/client.d.ts

@@ -1,39 +1,40 @@
+import { type TokenProvider } from "./token-provider.js";
 import type { AccessToken, Attachment, FmsgMessage, ReactResult, SendInput, SendResult, Thread } from "./types.js";
+export { FmsgHttpError } from "./errors.js";
 export type FetchLike = typeof fetch;
 export type FmsgClientOptions = {
     fetch?: FetchLike;
-    /** Refresh the access token this long before it expires (default 5 minutes). */
+    /** Refresh margin (default 5 minutes), capped at half the token's remaining lifetime on acquisition. */
     refreshMarginMs?: number;
-    /** Per-request timeout (default 60 s). */
+    /** Per-request timeout; attachment streams use separate header/idle budgets (default 60 s). */
     timeoutMs?: number;
+    /** Allow HTTP outside loopback only on an explicitly trusted network. */
+    allowInsecureHttp?: boolean;
+    /** Renew event sockets when their bearer expires (delegated OAuth clients). */
+    reconnectOnTokenExpiry?: boolean;
 };
-/** An HTTP error from the fmsg Web API, with the status and the host's own error text. */
-export declare class FmsgHttpError extends Error {
-    readonly status: number;
-    readonly method: string;
-    readonly path: string;
-    /** Machine-readable `code` from the body, when the host sends one (thread routes). */
-    readonly code?: string | undefined;
-    constructor(message: string, status: number, method: string, path: string, 
-    /** Machine-readable `code` from the body, when the host sends one (thread routes). */
-    code?: string | undefined);
-}
 /**
- * Client for the fmsg Web API (FMSG-003). Exchanges an `fmsgk_` API key for a
- * short-lived JWT, refreshes it ahead of expiry, and retries once on 401.
+ * Client for the fmsg Web API (FMSG-003). Accepts an API key or a caller-bound
+ * token provider, renews tokens ahead of expiry, and retries once on 401.
  */
 export declare class FmsgClient {
-    private readonly apiKey;
     private readonly options;
     readonly apiUrl: string;
     private token?;
-    private tokenPromise?;
-    constructor(apiUrl: string, apiKey: string, options?: FmsgClientOptions);
+    private renewal?;
+    private provider?;
+    private boundAddress?;
+    private refreshAtMs;
+    private readonly lifetime;
+    constructor(apiUrl: string, credentials: string | TokenProvider, options?: FmsgClientOptions);
     private get fetchImpl();
-    /** The address this client acts as (from the JWT `sub`), exchanging the key if needed. */
-    address(): Promise<string>;
-    getToken(force?: boolean): Promise<AccessToken>;
-    private exchangeToken;
+    get reconnectOnTokenExpiry(): boolean;
+    /** The provider's authenticated address, pinned for this client's lifetime. */
+    address(signal?: AbortSignal): Promise<string>;
+    getToken(force?: boolean, signal?: AbortSignal): Promise<AccessToken>;
+    private startRenewal;
+    /** Release credentials and cancel outstanding work when the client is no longer used. */
+    close(): void;
     private request;
     private json;
     listInbox(limit?: number, offset?: number, signal?: AbortSignal): Promise<FmsgMessage[]>;
@@ -67,10 +68,15 @@ export declare class FmsgClient {
         added: number;
     }>;
     react(id: string, emoji: string | null, signal?: AbortSignal): Promise<ReactResult>;
-    downloadAttachment(id: string, filename: string, signal?: AbortSignal): Promise<{
+    downloadAttachment(id: string, filename: string, signal?: AbortSignal, maxBytes?: number): Promise<{
         data: Uint8Array;
         contentType?: string;
     }>;
+    /** Caller must consume or cancel the stream. Progress resets the idle budget; cancellation remains active. */
+    streamAttachment(id: string, filename: string, signal?: AbortSignal): Promise<{
+        stream: ReadableStream<Uint8Array>;
+        contentType?: string;
+    }>;
     deleteMessage(id: string, signal?: AbortSignal): Promise<void>;
     private createDraft;
     uploadAttachment(draftId: string, attachment: {
@@ -78,6 +84,10 @@ export declare class FmsgClient {
         data: Uint8Array;
         contentType?: string;
     }, signal?: AbortSignal): Promise<Attachment>;
-    /** Draft → attach → send. The draft is deleted if any step after creation fails. */
+    /**
+     * Draft → attach → send. Selected secret patterns in body/topic are replaced;
+     * the result reports their count and the sent topic. Attachments are unchanged.
+     * The draft is deleted if any step after creation fails.
+     */
     send(input: SendInput): Promise<SendResult>;
 }

package/dist/client/client.js

@@ -1,130 +1,152 @@
 import { normalizeFmsgAddress } from "../address.js";
 import { normalizeMessageId, parseFmsgJson, stringifyWithIds } from "./message-id.js";
 import { redactSecrets } from "./redact.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;
-    constructor(message, status, method, path, 
-    /** Machine-readable `code` from the body, when the host sends one (thread routes). */
-    code) {
-        super(message);
-        this.status = status;
-        this.method = method;
-        this.path = path;
-        this.code = code;
-        this.name = "FmsgHttpError";
-    }
-}
-function decodeJwtPayload(token) {
-    const parts = token.split(".");
-    if (parts.length !== 3 || !parts[1])
-        throw new Error("token exchange returned an invalid JWT");
-    try {
-        return JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8"));
-    }
-    catch {
-        throw new Error("token exchange returned an unreadable JWT payload");
-    }
-}
-async function readError(response) {
-    const raw = await response.text().catch(() => "");
-    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: raw.slice(0, 300) };
-    }
-}
+import { normalizeApiUrl } from "./url.js";
+import { readBytes, withIdleTimeout } from "./stream.js";
+import { FmsgHttpError, readError } from "./errors.js";
+import { ApiKeyTokenProvider } from "./token-provider.js";
+export { FmsgHttpError } from "./errors.js";
 function withId(message, id) {
     return { ...message, id, terminal: message.terminal === true, reaction: message.reaction ?? null, reactions: message.reactions ?? [] };
 }
+/** Detach one waiter without cancelling work another caller still needs. */
+function withAbort(promise, signal) {
+    if (!signal)
+        return promise;
+    return new Promise((resolve, reject) => {
+        const onAbort = () => { signal.removeEventListener("abort", onAbort); reject(signal.reason); };
+        signal.addEventListener("abort", onAbort, { once: true });
+        if (signal.aborted)
+            onAbort();
+        // Always observe the operation, including a provider that ignores cancellation.
+        promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", onAbort));
+    });
+}
 /**
- * Client for the fmsg Web API (FMSG-003). Exchanges an `fmsgk_` API key for a
- * short-lived JWT, refreshes it ahead of expiry, and retries once on 401.
+ * Client for the fmsg Web API (FMSG-003). Accepts an API key or a caller-bound
+ * token provider, renews tokens ahead of expiry, and retries once on 401.
  */
 export class FmsgClient {
-    apiKey;
     options;
     apiUrl;
     token;
-    tokenPromise;
-    constructor(apiUrl, apiKey, options = {}) {
-        this.apiKey = apiKey;
+    renewal;
+    provider;
+    boundAddress;
+    refreshAtMs = 0;
+    lifetime = new AbortController();
+    constructor(apiUrl, credentials, options = {}) {
         this.options = options;
-        this.apiUrl = apiUrl.replace(/\/+$/u, "");
-        if (!/^https?:\/\//u.test(this.apiUrl))
-            throw new Error("FMSG_API_URL must be an http(s) URL");
-        if (!apiKey.startsWith("fmsgk_"))
-            throw new Error("fmsg API key must start with fmsgk_");
+        this.apiUrl = normalizeApiUrl(apiUrl, options.allowInsecureHttp);
+        if (options.refreshMarginMs !== undefined && (!Number.isFinite(options.refreshMarginMs) || options.refreshMarginMs < 0)) {
+            throw new Error("refreshMarginMs must be a finite non-negative number");
+        }
+        this.provider = typeof credentials === "string" ? new ApiKeyTokenProvider(credentials, this.fetchImpl) : credentials;
+        if (!this.provider || typeof this.provider.getToken !== "function")
+            throw new Error("a token provider must implement getToken");
     }
     get fetchImpl() {
         return this.options.fetch ?? fetch;
     }
-    /** The address this client acts as (from the JWT `sub`), exchanging the key if needed. */
-    async address() {
-        return (await this.getToken()).address;
+    get reconnectOnTokenExpiry() { return this.options.reconnectOnTokenExpiry === true; }
+    /** The provider's authenticated address, pinned for this client's lifetime. */
+    async address(signal) {
+        return (await this.getToken(false, signal)).address;
     }
-    async getToken(force = false) {
-        const margin = this.options.refreshMarginMs ?? 300_000;
-        if (!force && this.token && this.token.expiresAtMs - margin > Date.now())
+    async getToken(force = false, signal) {
+        signal?.throwIfAborted();
+        this.lifetime.signal.throwIfAborted();
+        if (!this.renewal && !force && this.token && this.refreshAtMs > Date.now())
             return this.token;
-        if (!force && this.tokenPromise)
-            return this.tokenPromise;
-        this.tokenPromise = this.exchangeToken();
+        const renewal = this.renewal ?? this.startRenewal(force);
+        renewal.waiters++;
         try {
-            this.token = await this.tokenPromise;
-            return this.token;
+            return await withAbort(renewal.promise, signal);
         }
         finally {
-            this.tokenPromise = undefined;
+            renewal.waiters--;
+            if (!renewal.waiters && this.renewal === renewal) {
+                this.renewal = undefined;
+                renewal.abort.abort();
+            }
         }
     }
-    async exchangeToken() {
-        const response = await this.fetchImpl(`${this.apiUrl}/fmsg/token`, {
-            method: "POST",
-            headers: { authorization: `Bearer ${this.apiKey}` },
-            signal: AbortSignal.timeout(this.options.timeoutMs ?? 60_000),
+    startRenewal(forceRefresh) {
+        const provider = this.provider;
+        const renewal = { promise: undefined, abort: new AbortController(), waiters: 0 };
+        this.renewal = renewal;
+        this.token = undefined;
+        const signal = AbortSignal.any([this.lifetime.signal, renewal.abort.signal]);
+        const timer = setTimeout(() => renewal.abort.abort(new DOMException("token renewal timed out", "TimeoutError")), this.options.timeoutMs ?? 60_000).unref();
+        const acquiring = Promise.resolve().then(() => {
+            signal.throwIfAborted();
+            return provider.getToken({ apiUrl: this.apiUrl, signal, forceRefresh });
         });
-        if (!response.ok) {
-            const { message } = await readError(response);
-            throw new FmsgHttpError(`token exchange failed: ${redactSecrets(message).text}`, response.status, "POST", "/fmsg/token");
-        }
-        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 fromResponse = typeof body.expires_at === "string" ? Date.parse(body.expires_at) : Number.NaN;
-        const fromJwt = typeof payload.exp === "number" ? payload.exp * 1000 : Number.NaN;
-        const fromIn = typeof body.expires_in === "number" ? Date.now() + body.expires_in * 1000 : Number.NaN;
-        const expiresAtMs = [fromResponse, fromJwt, fromIn].find(Number.isFinite) ?? Date.now() + 3_600_000;
-        return { accessToken: body.access_token, address, expiresAtMs };
+        renewal.promise = withAbort(acquiring, signal).then(value => {
+            signal.throwIfAborted();
+            const address = typeof value?.address === "string" ? normalizeFmsgAddress(value.address) : undefined;
+            if (!address)
+                throw new Error("token provider returned an invalid fmsg address");
+            if (typeof value.accessToken !== "string" || !/^[A-Za-z0-9._~+\/-]+=*$/u.test(value.accessToken) || value.accessToken.startsWith("fmsgk_")) {
+                throw new Error("token provider must return a Web API bearer access token");
+            }
+            const now = Date.now();
+            if (!Number.isFinite(value.expiresAtMs) || value.expiresAtMs <= now)
+                throw new Error("token provider returned an invalid or expired token lifetime");
+            if (this.boundAddress !== undefined && address !== this.boundAddress)
+                throw new Error("token provider changed the authenticated address; create a new client for a different identity");
+            this.boundAddress = address;
+            const token = Object.freeze({ accessToken: value.accessToken, address, expiresAtMs: value.expiresAtMs });
+            this.refreshAtMs = token.expiresAtMs - Math.min(this.options.refreshMarginMs ?? 300_000, (token.expiresAtMs - now) / 2);
+            this.token = token;
+            return token;
+        }).finally(() => {
+            clearTimeout(timer);
+            if (this.renewal === renewal)
+                this.renewal = undefined;
+        });
+        return renewal;
     }
-    async request(path, init = {}, retry401 = true) {
-        const token = await this.getToken();
+    /** Release credentials and cancel outstanding work when the client is no longer used. */
+    close() {
+        if (this.lifetime.signal.aborted)
+            return;
+        this.lifetime.abort();
+        this.token = undefined;
+        const provider = this.provider;
+        this.provider = undefined;
+        provider?.close?.();
+    }
+    async request(path, init = {}, retry401 = true, streaming = false) {
+        init.signal?.throwIfAborted();
+        const token = await this.getToken(false, init.signal ?? undefined);
         const headers = new Headers(init.headers);
         headers.set("authorization", `Bearer ${token.accessToken}`);
-        const signal = init.signal ?? AbortSignal.timeout(this.options.timeoutMs ?? 60_000);
-        const response = await this.fetchImpl(`${this.apiUrl}${path}`, { ...init, headers, signal });
-        if (response.status === 401 && retry401) {
-            await this.getToken(true);
-            return this.request(path, init, false);
+        const headerDeadline = new AbortController();
+        const headerTimer = streaming ? setTimeout(() => headerDeadline.abort(new DOMException("attachment response headers timed out", "TimeoutError")), this.options.timeoutMs ?? 60_000).unref() : undefined;
+        const timeout = streaming ? headerDeadline.signal : AbortSignal.timeout(this.options.timeoutMs ?? 60_000);
+        const signal = AbortSignal.any([this.lifetime.signal, timeout, ...(init.signal ? [init.signal] : [])]);
+        try {
+            signal.throwIfAborted();
+            const response = await this.fetchImpl(`${this.apiUrl}${path}`, { ...init, headers, signal, redirect: "error" });
+            if (response.status === 401 && retry401) {
+                await response.body?.cancel();
+                // A slower 401 may refer to a token another request already renewed.
+                if (!this.token || this.token === token || this.token.expiresAtMs <= Date.now()) {
+                    await this.getToken(true, init.signal ?? undefined);
+                }
+                return this.request(path, init, false, streaming);
+            }
+            if (!response.ok) {
+                const { message, code } = await readError(response);
+                const method = init.method ?? "GET";
+                throw new FmsgHttpError(message, response.status, method, path, code, response.status === 403 && /\bBearer\b.*\berror="insufficient_scope"/iu.test(response.headers.get("www-authenticate") ?? ""));
+            }
+            return response;
         }
-        if (!response.ok) {
-            const { message, code } = await readError(response);
-            const method = init.method ?? "GET";
-            throw new FmsgHttpError(redactSecrets(message).text, response.status, method, path, code);
+        finally {
+            clearTimeout(headerTimer);
         }
-        return response;
     }
     async json(path, init) {
         const response = await this.request(path, init);
@@ -195,8 +217,14 @@ export class FmsgClient {
     }
     /** Download by a `download` path returned from thread/messages (`/fmsg/...`). */
     async downloadPath(path, signal) {
-        if (!path.startsWith("/fmsg/") || path.includes("://"))
-            throw new Error(`refusing to download non-fmsg path ${path}`);
+        // Paths come from upstream message data. Reject normalization tricks and
+        // routes outside the documented body/attachment download endpoints.
+        if (!/^\/fmsg\/[0-9]+\/(?:data|attach\/[^/?#\\]+)$/u.test(path) || /[\u0000-\u0020\\]/u.test(path)) {
+            throw new Error("refusing an invalid fmsg download path");
+        }
+        const normalized = new URL(path, "https://example.com");
+        if (normalized.pathname !== path || normalized.search || normalized.hash)
+            throw new Error("refusing an invalid fmsg download path");
         const response = await this.request(path, { signal });
         const contentType = response.headers.get("content-type") ?? undefined;
         return { data: new Uint8Array(await response.arrayBuffer()), ...(contentType ? { contentType } : {}) };
@@ -232,11 +260,22 @@ export class FmsgClient {
             time: result.time ?? null,
         };
     }
-    async downloadAttachment(id, filename, signal) {
+    async downloadAttachment(id, filename, signal, maxBytes) {
+        const { stream, contentType } = await this.streamAttachment(id, filename, signal);
+        const { data } = await readBytes(stream, maxBytes);
+        return { data, ...(contentType ? { contentType } : {}) };
+    }
+    /** Caller must consume or cancel the stream. Progress resets the idle budget; cancellation remains active. */
+    async streamAttachment(id, filename, signal) {
         const mid = normalizeMessageId(id);
-        const response = await this.request(`/fmsg/${encodeURIComponent(mid)}/attach/${encodeURIComponent(filename)}`, { signal });
+        if (!filename || filename === "." || filename === ".." || /[/\\\u0000]/u.test(filename)) {
+            throw new Error("use an attachment filename without directory components");
+        }
+        const response = await this.request(`/fmsg/${encodeURIComponent(mid)}/attach/${encodeURIComponent(filename)}`, { signal }, true, true);
         const contentType = response.headers.get("content-type") ?? undefined;
-        return { data: new Uint8Array(await response.arrayBuffer()), ...(contentType ? { contentType } : {}) };
+        if (!response.body)
+            throw new Error("attachment response has no body");
+        return { stream: withIdleTimeout(response.body, this.options.timeoutMs ?? 60_000), ...(contentType ? { contentType } : {}) };
     }
     async deleteMessage(id, signal) {
         const mid = normalizeMessageId(id);
@@ -278,14 +317,20 @@ export class FmsgClient {
         const result = parseFmsgJson(await response.text());
         return { filename: result.filename ?? attachment.filename, size: result.size ?? attachment.data.byteLength };
     }
-    /** Draft → attach → send. The draft is deleted if any step after creation fails. */
+    /**
+     * Draft → attach → send. Selected secret patterns in body/topic are replaced;
+     * the result reports their count and the sent topic. Attachments are unchanged.
+     * The draft is deleted if any step after creation fails.
+     */
     async send(input) {
         if (input.to.length === 0)
             throw new Error("at least one recipient is required");
         if (input.pid && input.topic)
             throw new Error("a reply (pid) cannot carry a topic");
-        const from = await this.address();
-        const draftId = await this.createDraft(input, from);
+        const from = await this.address(input.signal);
+        const body = redactSecrets(input.body);
+        const topic = redactSecrets(input.pid ? "" : (input.topic ?? ""));
+        const draftId = await this.createDraft({ ...input, body: body.text, topic: topic.text }, from);
         try {
             const attachments = [];
             for (const attachment of input.attachments ?? []) {
@@ -300,6 +345,8 @@ export class FmsgClient {
                 id: result.id === undefined || result.id === null ? draftId : normalizeMessageId(result.id),
                 time: result.time ?? null,
                 attachments,
+                redactions: body.count + topic.count,
+                topic: topic.text,
             };
         }
         catch (error) {

package/dist/client/errors.d.ts

@@ -0,0 +1,19 @@
+/** An HTTP error from the fmsg Web API, with the status and the host's own error text. */
+export declare class FmsgHttpError extends Error {
+    readonly status: number;
+    readonly method: string;
+    readonly path: string;
+    /** Machine-readable `code` from the body, when the host sends one (thread routes). */
+    readonly code?: string | undefined;
+    /** The Web API rejected a delegated scope or closed route. */
+    readonly insufficientScope: boolean;
+    constructor(message: string, status: number, method: string, path: string, 
+    /** Machine-readable `code` from the body, when the host sends one (thread routes). */
+    code?: string | undefined, 
+    /** The Web API rejected a delegated scope or closed route. */
+    insufficientScope?: boolean);
+}
+export declare function readError(response: Response): Promise<{
+    message: string;
+    code?: string;
+}>;