mcp-server-framework 1.0.0

package/build/server/lifecycle.js

@@ -0,0 +1,30 @@
+/**
+ * Server Lifecycle Types
+ *
+ * Defines lifecycle hooks and state management for MCP servers.
+ * These types enable clean startup/shutdown handling and event-driven architecture.
+ *
+ * @module server/lifecycle
+ */
+/**
+ * All possible server states as a readonly array.
+ *
+ * @public Exported for consumer validation and iteration.
+ * The {@link ServerState} type is the recommended way to type state values.
+ */
+export const SERVER_STATES = ["created", "starting", "running", "stopping", "stopped", "error"];
+/** Default shutdown timeout in milliseconds (10 seconds). */
+const DEFAULT_SHUTDOWN_TIMEOUT_MS = 10_000;
+/**
+ * Default shutdown configuration values.
+ *
+ * Configurable only via `ServerOptions.shutdown` (programmatic API).
+ * Not exposed as env variable or config file field — shutdown behavior
+ * is typically set per-deployment in code, not per-environment.
+ */
+export const DEFAULT_SHUTDOWN_CONFIG = {
+    timeoutMs: DEFAULT_SHUTDOWN_TIMEOUT_MS,
+    forceExitOnTimeout: true,
+    signals: ["SIGINT", "SIGTERM"],
+};
+//# sourceMappingURL=lifecycle.js.map

package/build/server/lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.js","sourceRoot":"","sources":["../../src/server/lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAkBH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,OAAO,CAAU,CAAC;AAiGzG,6DAA6D;AAC7D,MAAM,2BAA2B,GAAG,MAAM,CAAC;AAE3C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAmB;IACrD,SAAS,EAAE,2BAA2B;IACtC,kBAAkB,EAAE,IAAI;IACxB,OAAO,EAAE,CAAC,QAAQ,EAAE,SAAS,CAAC;CAC/B,CAAC"}

package/build/server/middleware/bearer-auth.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Bearer Auth Middleware
+ *
+ * Wraps the SDK's `requireBearerAuth()` middleware with framework-level
+ * logging, error mapping, and support for both full OAuth providers and
+ * custom token verifiers.
+ *
+ * Follows the factory pattern established by `createRateLimiter()` and
+ * `dnsRebindingProtection`.
+ *
+ * @module server/middleware/bearer-auth
+ */
+import type { RequestHandler } from "express";
+import type { AuthProvider } from "../auth/types.js";
+/**
+ * Options for creating the bearer auth middleware.
+ */
+export interface BearerAuthOptions {
+    /** Authentication provider (full OAuth or token verifier) */
+    readonly provider: AuthProvider;
+    /**
+     * Required OAuth scopes for all requests through this middleware.
+     * Requests without ALL listed scopes are rejected with 403.
+     */
+    readonly requiredScopes?: readonly string[] | undefined;
+    /**
+     * Protected Resource Metadata URL (RFC 9728).
+     * Included in `WWW-Authenticate` headers for 401 responses.
+     */
+    readonly resourceMetadataUrl?: string | undefined;
+}
+/**
+ * Creates a bearer auth middleware that validates access tokens.
+ *
+ * Delegates to the SDK's `requireBearerAuth()` for actual token validation.
+ * Supports both full OAuth providers and custom token verifiers via the
+ * {@link AuthProvider} union type.
+ *
+ * @param options - Bearer auth configuration
+ * @returns Express middleware that sets `req.auth` on success
+ */
+export declare function createBearerAuth(options: BearerAuthOptions): RequestHandler;
+//# sourceMappingURL=bearer-auth.d.ts.map

package/build/server/middleware/bearer-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bearer-auth.d.ts","sourceRoot":"","sources":["../../../src/server/middleware/bearer-auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAG9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAsBrD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAEhC;;;OAGG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IAExD;;;OAGG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACnD;AAMD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,cAAc,CAyC3E"}

package/build/server/middleware/bearer-auth.js

@@ -0,0 +1,75 @@
+/**
+ * Bearer Auth Middleware
+ *
+ * Wraps the SDK's `requireBearerAuth()` middleware with framework-level
+ * logging, error mapping, and support for both full OAuth providers and
+ * custom token verifiers.
+ *
+ * Follows the factory pattern established by `createRateLimiter()` and
+ * `dnsRebindingProtection`.
+ *
+ * @module server/middleware/bearer-auth
+ */
+import { requireBearerAuth } from "@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js";
+import { isFullOAuthProvider } from "../auth/types.js";
+import { logger as baseLogger } from "../../logger/index.js";
+import { logSecurityEvent } from "./logging.js";
+// ============================================================================
+// Logger
+// ============================================================================
+const LOG_COMPONENT = "bearer-auth";
+const LogMessages = {
+    CONFIGURED_OAUTH: "Bearer auth configured (full OAuth provider, scopes: %s)",
+    CONFIGURED_VERIFIER: "Bearer auth configured (token verifier, scopes: %s)",
+};
+const logger = baseLogger.child({ component: LOG_COMPONENT });
+// ============================================================================
+// Factory
+// ============================================================================
+/**
+ * Creates a bearer auth middleware that validates access tokens.
+ *
+ * Delegates to the SDK's `requireBearerAuth()` for actual token validation.
+ * Supports both full OAuth providers and custom token verifiers via the
+ * {@link AuthProvider} union type.
+ *
+ * @param options - Bearer auth configuration
+ * @returns Express middleware that sets `req.auth` on success
+ */
+export function createBearerAuth(options) {
+    const { provider, requiredScopes, resourceMetadataUrl } = options;
+    // SDK's requireBearerAuth accepts:
+    // - Full OAuthServerProvider — used as-is
+    // - { verifyAccessToken } — for token-only verification
+    const verifier = isFullOAuthProvider(provider)
+        ? provider
+        : { verifyAccessToken: provider.verifyAccessToken.bind(provider) };
+    const scopeList = requiredScopes ? [...requiredScopes] : undefined;
+    if (isFullOAuthProvider(provider)) {
+        logger.info(LogMessages.CONFIGURED_OAUTH, scopeList?.join(", ") ?? "none");
+    }
+    else {
+        logger.info(LogMessages.CONFIGURED_VERIFIER, scopeList?.join(", ") ?? "none");
+    }
+    const sdkMiddleware = requireBearerAuth({
+        verifier,
+        ...(scopeList && scopeList.length > 0 && { requiredScopes: scopeList }),
+        ...(resourceMetadataUrl && { resourceMetadataUrl }),
+    });
+    // Wrap SDK middleware with security logging for failures
+    const middleware = (req, res, next) => {
+        // Log auth failures after response is sent
+        res.on("finish", () => {
+            if (res.statusCode === 401 || res.statusCode === 403) {
+                logSecurityEvent(`Bearer auth rejected: ${res.statusCode}`, {
+                    method: req.method,
+                    path: req.path,
+                    statusCode: res.statusCode,
+                });
+            }
+        });
+        sdkMiddleware(req, res, next);
+    };
+    return middleware;
+}
+//# sourceMappingURL=bearer-auth.js.map

package/build/server/middleware/bearer-auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bearer-auth.js","sourceRoot":"","sources":["../../../src/server/middleware/bearer-auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,iBAAiB,EAAE,MAAM,gEAAgE,CAAC;AAGnG,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD,+EAA+E;AAC/E,SAAS;AACT,+EAA+E;AAE/E,MAAM,aAAa,GAAG,aAAa,CAAC;AAEpC,MAAM,WAAW,GAAG;IAClB,gBAAgB,EAAE,0DAA0D;IAC5E,mBAAmB,EAAE,qDAAqD;CAClE,CAAC;AAEX,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC,EAAE,SAAS,EAAE,aAAa,EAAE,CAAC,CAAC;AA0B9D,+EAA+E;AAC/E,UAAU;AACV,+EAA+E;AAE/E;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAA0B;IACzD,MAAM,EAAE,QAAQ,EAAE,cAAc,EAAE,mBAAmB,EAAE,GAAG,OAAO,CAAC;IAElE,mCAAmC;IACnC,0CAA0C;IAC1C,wDAAwD;IACxD,MAAM,QAAQ,GAAG,mBAAmB,CAAC,QAAQ,CAAC;QAC5C,CAAC,CAAC,QAAQ;QACV,CAAC,CAAC,EAAE,iBAAiB,EAAE,QAAQ,CAAC,iBAAiB,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;IAErE,MAAM,SAAS,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAEnE,IAAI,mBAAmB,CAAC,QAAQ,CAAC,EAAE,CAAC;QAClC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,gBAAgB,EAAE,SAAS,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,CAAC;IAC7E,CAAC;SAAM,CAAC;QACN,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,mBAAmB,EAAE,SAAS,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,CAAC;IAChF,CAAC;IAED,MAAM,aAAa,GAAG,iBAAiB,CAAC;QACtC,QAAQ;QACR,GAAG,CAAC,SAAS,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,cAAc,EAAE,SAAS,EAAE,CAAC;QACvE,GAAG,CAAC,mBAAmB,IAAI,EAAE,mBAAmB,EAAE,CAAC;KACpD,CAAC,CAAC;IAEH,yDAAyD;IACzD,MAAM,UAAU,GAAmB,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QACpD,2CAA2C;QAC3C,GAAG,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE;YACpB,IAAI,GAAG,CAAC,UAAU,KAAK,GAAG,IAAI,GAAG,CAAC,UAAU,KAAK,GAAG,EAAE,CAAC;gBACrD,gBAAgB,CAAC,yBAAyB,GAAG,CAAC,UAAU,EAAE,EAAE;oBAC1D,MAAM,EAAE,GAAG,CAAC,MAAM;oBAClB,IAAI,EAAE,GAAG,CAAC,IAAI;oBACd,UAAU,EAAE,GAAG,CAAC,UAAU;iBAC3B,CAAC,CAAC;YACL,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,aAAa,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;IAChC,CAAC,CAAC;IAEF,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/build/server/middleware/custom-header-auth.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Custom Header Auth Middleware
+ *
+ * Extracts a token from a configurable request header (e.g. `X-API-Key`)
+ * and validates it via a {@link TokenVerifier}. Sets `req.auth` on success,
+ * matching the same contract as the SDK's bearer auth middleware.
+ *
+ * Use this when your auth model is not OAuth Bearer but a custom header
+ * like `X-API-Key`, `X-Custom-Token`, etc.
+ *
+ * @module server/middleware/custom-header-auth
+ */
+import type { RequestHandler } from "express";
+import type { TokenVerifier } from "../auth/types.js";
+/**
+ * Options for creating the custom header auth middleware.
+ */
+export interface CustomHeaderAuthOptions {
+    /** Header name to extract the token from (e.g. `'X-API-Key'`) */
+    readonly headerName: string;
+    /** Token verifier to validate the extracted header value */
+    readonly verifier: TokenVerifier;
+    /**
+     * Required scopes for all requests through this middleware.
+     * Requests without ALL listed scopes are rejected with 403.
+     */
+    readonly requiredScopes?: readonly string[] | undefined;
+}
+/**
+ * Creates a middleware that extracts a token from a custom header and
+ * validates it via the provided {@link TokenVerifier}.
+ *
+ * On success, sets `req.auth` to the verified {@link AuthInfo} — same
+ * contract as the SDK's bearer auth middleware.
+ *
+ * @param options - Custom header auth configuration
+ * @returns Express middleware
+ */
+export declare function createCustomHeaderAuth(options: CustomHeaderAuthOptions): RequestHandler;
+//# sourceMappingURL=custom-header-auth.d.ts.map

package/build/server/middleware/custom-header-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom-header-auth.d.ts","sourceRoot":"","sources":["../../../src/server/middleware/custom-header-auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAqB,MAAM,SAAS,CAAC;AAEjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAqBtD;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,iEAAiE;IACjE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B,4DAA4D;IAC5D,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IAEjC;;;OAGG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;CACzD;AAMD;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,uBAAuB,GAAG,cAAc,CA6DvF"}

package/build/server/middleware/custom-header-auth.js

@@ -0,0 +1,90 @@
+/**
+ * Custom Header Auth Middleware
+ *
+ * Extracts a token from a configurable request header (e.g. `X-API-Key`)
+ * and validates it via a {@link TokenVerifier}. Sets `req.auth` on success,
+ * matching the same contract as the SDK's bearer auth middleware.
+ *
+ * Use this when your auth model is not OAuth Bearer but a custom header
+ * like `X-API-Key`, `X-Custom-Token`, etc.
+ *
+ * @module server/middleware/custom-header-auth
+ */
+import { createJsonRpcError, HttpStatus, JsonRpcErrorCode } from "../../errors/index.js";
+import { logger as baseLogger } from "../../logger/index.js";
+import { logSecurityEvent } from "./logging.js";
+// ============================================================================
+// Logger
+// ============================================================================
+const LOG_COMPONENT = "custom-header-auth";
+const LogMessages = {
+    CONFIGURED: "Custom header auth configured (header: %s, scopes: %s)",
+};
+const logger = baseLogger.child({ component: LOG_COMPONENT });
+// ============================================================================
+// Factory
+// ============================================================================
+/**
+ * Creates a middleware that extracts a token from a custom header and
+ * validates it via the provided {@link TokenVerifier}.
+ *
+ * On success, sets `req.auth` to the verified {@link AuthInfo} — same
+ * contract as the SDK's bearer auth middleware.
+ *
+ * @param options - Custom header auth configuration
+ * @returns Express middleware
+ */
+export function createCustomHeaderAuth(options) {
+    const { headerName, verifier, requiredScopes } = options;
+    const headerLower = headerName.toLowerCase();
+    const scopeList = requiredScopes ? [...requiredScopes] : undefined;
+    logger.info(LogMessages.CONFIGURED, headerName, scopeList?.join(", ") ?? "none");
+    const middleware = async (req, res, next) => {
+        const token = req.headers[headerLower];
+        if (!token || typeof token !== "string") {
+            logSecurityEvent(`Custom header auth rejected: 401 (missing ${headerName})`, {
+                method: req.method,
+                path: req.path,
+                statusCode: 401,
+            });
+            res
+                .status(HttpStatus.UNAUTHORIZED)
+                .json(createJsonRpcError(JsonRpcErrorCode.INVALID_REQUEST, `Missing ${headerName} header`));
+            return;
+        }
+        try {
+            const authInfo = await verifier.verifyAccessToken(token);
+            // Scope enforcement
+            if (scopeList && scopeList.length > 0) {
+                const missing = scopeList.filter((s) => !authInfo.scopes.includes(s));
+                if (missing.length > 0) {
+                    logSecurityEvent(`Custom header auth rejected: 403 (missing scopes: ${missing.join(", ")})`, {
+                        method: req.method,
+                        path: req.path,
+                        statusCode: 403,
+                    });
+                    res
+                        .status(HttpStatus.FORBIDDEN)
+                        .json(createJsonRpcError(JsonRpcErrorCode.INVALID_REQUEST, `Missing required scopes: ${missing.join(", ")}`));
+                    return;
+                }
+            }
+            // Set req.auth — same contract as SDK's bearer auth
+            // @express-api — Express Request augmented by SDK types
+            req.auth = authInfo;
+            next();
+        }
+        catch {
+            logSecurityEvent(`Custom header auth rejected: 401 (invalid token)`, {
+                method: req.method,
+                path: req.path,
+                statusCode: 401,
+            });
+            res
+                .status(HttpStatus.UNAUTHORIZED)
+                .json(createJsonRpcError(JsonRpcErrorCode.INVALID_REQUEST, "Invalid or expired token"));
+        }
+    };
+    return middleware;
+}
+//# sourceMappingURL=custom-header-auth.js.map

package/build/server/middleware/custom-header-auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom-header-auth.js","sourceRoot":"","sources":["../../../src/server/middleware/custom-header-auth.ts"],"names":[],"mappings":"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"}

package/build/server/middleware/dns-rebinding.d.ts

@@ -0,0 +1,25 @@
+/**
+ * DNS Rebinding Protection middleware
+ * MCP Spec 2025-06-18 MUST requirement
+ *
+ * SECURITY NOTE: This middleware validates the Host header to prevent
+ * DNS rebinding attacks. For production deployments:
+ * - Always run behind a reverse proxy (nginx, traefik) with proper TLS
+ * - Configure explicit MCP_ALLOWED_HOSTS
+ *
+ * @module server/middleware/dns-rebinding
+ */
+import type { Request, Response, NextFunction } from "express";
+/**
+ * Resets the cached allowed hosts.
+ * Called by the central config reset to maintain cache coherence.
+ *
+ * @internal
+ */
+export declare function resetDnsRebindingCache(): void;
+/**
+ * DNS Rebinding Protection Middleware
+ * Validates Host header to prevent DNS rebinding attacks (MCP Spec MUST)
+ */
+export declare function dnsRebindingProtection(req: Request, res: Response, next: NextFunction): void;
+//# sourceMappingURL=dns-rebinding.d.ts.map

package/build/server/middleware/dns-rebinding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dns-rebinding.d.ts","sourceRoot":"","sources":["../../../src/server/middleware/dns-rebinding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAuD/D;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,GAAG,IAAI,CA0B5F"}

package/build/server/middleware/dns-rebinding.js

@@ -0,0 +1,94 @@
+/**
+ * DNS Rebinding Protection middleware
+ * MCP Spec 2025-06-18 MUST requirement
+ *
+ * SECURITY NOTE: This middleware validates the Host header to prevent
+ * DNS rebinding attacks. For production deployments:
+ * - Always run behind a reverse proxy (nginx, traefik) with proper TLS
+ * - Configure explicit MCP_ALLOWED_HOSTS
+ *
+ * @module server/middleware/dns-rebinding
+ */
+import { getFrameworkConfig, registerCacheReset } from "../../config/index.js";
+import { isLocalHost } from "../../utils/string-helpers.js";
+import { createJsonRpcError, HttpStatus, JsonRpcErrorCode, TransportErrorMessage } from "../../errors/index.js";
+import { logSecurityEvent, sanitizeForLog } from "./logging.js";
+// ============================================================================
+// Security Configuration
+// ============================================================================
+/**
+ * Creates allowed hosts list for DNS rebinding protection.
+ *
+ * Returns the configured allowed hosts or defaults to localhost variants.
+ * The returned list is used by middleware to validate Host headers.
+ *
+ * @param config - Framework environment configuration
+ * @returns Array of allowed host strings (e.g., ['localhost:3000', '127.0.0.1:3000'])
+ */
+function createAllowedHosts(config) {
+    const port = config.MCP_PORT;
+    // prettier-ignore
+    const defaults = [
+        'localhost',
+        '127.0.0.1',
+        '[::1]',
+        `localhost:${port}`,
+        `127.0.0.1:${port}`,
+        `[::1]:${port}`,
+    ];
+    if (config.MCP_ALLOWED_HOSTS && config.MCP_ALLOWED_HOSTS.length > 0) {
+        // Normalize to lowercase — RFC 7230: Host header is case-insensitive
+        return config.MCP_ALLOWED_HOSTS.map((h) => h.toLowerCase());
+    }
+    return defaults;
+}
+/** Cached derived value (lazy initialization) */
+let cachedAllowedHosts;
+// Self-register for central cache reset
+registerCacheReset(resetDnsRebindingCache);
+/**
+ * Gets or creates cached allowed hosts list.
+ */
+function getAllowedHosts() {
+    if (!cachedAllowedHosts) {
+        cachedAllowedHosts = createAllowedHosts(getFrameworkConfig());
+    }
+    return cachedAllowedHosts;
+}
+/**
+ * Resets the cached allowed hosts.
+ * Called by the central config reset to maintain cache coherence.
+ *
+ * @internal
+ */
+export function resetDnsRebindingCache() {
+    cachedAllowedHosts = undefined;
+}
+/**
+ * DNS Rebinding Protection Middleware
+ * Validates Host header to prevent DNS rebinding attacks (MCP Spec MUST)
+ */
+export function dnsRebindingProtection(req, res, next) {
+    const config = getFrameworkConfig();
+    const host = req.headers.host;
+    const allowedHosts = getAllowedHosts();
+    // Validate Host header (MUST for all configurations)
+    // We allow localhost/127.0.0.1 on ANY port to support Docker port mapping ONLY if no custom hosts are defined
+    // Normalize to lowercase — RFC 7230: Host header is case-insensitive
+    const cleanHost = host ? host.trim().toLowerCase() : "";
+    // If MCP_ALLOWED_HOSTS is set, we strictly enforce that list (no implicit localhost bypass).
+    // If not set, we allow defaults AND any localhost port (to support Docker port mapping).
+    const strictMode = !!config.MCP_ALLOWED_HOSTS;
+    const isAllowed = strictMode
+        ? allowedHosts.includes(cleanHost)
+        : isLocalHost(cleanHost) || allowedHosts.includes(cleanHost);
+    if (!host || !isAllowed) {
+        logSecurityEvent(`DNS Rebinding attempt blocked: Host=${sanitizeForLog(host)}`);
+        res
+            .status(HttpStatus.FORBIDDEN)
+            .json(createJsonRpcError(JsonRpcErrorCode.SERVER_ERROR, TransportErrorMessage.DNS_REBINDING_BLOCKED));
+        return;
+    }
+    next();
+}
+//# sourceMappingURL=dns-rebinding.js.map

package/build/server/middleware/dns-rebinding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dns-rebinding.js","sourceRoot":"","sources":["../../../src/server/middleware/dns-rebinding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAA2B,MAAM,uBAAuB,CAAC;AACxG,OAAO,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,UAAU,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAChH,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEhE,+EAA+E;AAC/E,yBAAyB;AACzB,+EAA+E;AAE/E;;;;;;;;GAQG;AACH,SAAS,kBAAkB,CAAC,MAA0B;IACpD,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC;IAC7B,kBAAkB;IAClB,MAAM,QAAQ,GAAG;QACf,WAAW;QACX,WAAW;QACX,OAAO;QACP,aAAa,IAAI,EAAE;QACnB,aAAa,IAAI,EAAE;QACnB,SAAS,IAAI,EAAE;KAChB,CAAC;IAEF,IAAI,MAAM,CAAC,iBAAiB,IAAI,MAAM,CAAC,iBAAiB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpE,qEAAqE;QACrE,OAAO,MAAM,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;IAC9D,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,iDAAiD;AACjD,IAAI,kBAAwC,CAAC;AAE7C,wCAAwC;AACxC,kBAAkB,CAAC,sBAAsB,CAAC,CAAC;AAE3C;;GAEG;AACH,SAAS,eAAe;IACtB,IAAI,CAAC,kBAAkB,EAAE,CAAC;QACxB,kBAAkB,GAAG,kBAAkB,CAAC,kBAAkB,EAAE,CAAC,CAAC;IAChE,CAAC;IACD,OAAO,kBAAkB,CAAC;AAC5B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB;IACpC,kBAAkB,GAAG,SAAS,CAAC;AACjC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,GAAY,EAAE,GAAa,EAAE,IAAkB;IACpF,MAAM,MAAM,GAAG,kBAAkB,EAAE,CAAC;IACpC,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC;IAC9B,MAAM,YAAY,GAAG,eAAe,EAAE,CAAC;IAEvC,qDAAqD;IACrD,8GAA8G;IAC9G,qEAAqE;IACrE,MAAM,SAAS,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAExD,6FAA6F;IAC7F,yFAAyF;IACzF,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,CAAC,iBAAiB,CAAC;IAC9C,MAAM,SAAS,GAAG,UAAU;QAC1B,CAAC,CAAC,YAAY,CAAC,QAAQ,CAAC,SAAS,CAAC;QAClC,CAAC,CAAC,WAAW,CAAC,SAAS,CAAC,IAAI,YAAY,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;IAE/D,IAAI,CAAC,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;QACxB,gBAAgB,CAAC,uCAAuC,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAChF,GAAG;aACA,MAAM,CAAC,UAAU,CAAC,SAAS,CAAC;aAC5B,IAAI,CAAC,kBAAkB,CAAC,gBAAgB,CAAC,YAAY,EAAE,qBAAqB,CAAC,qBAAqB,CAAC,CAAC,CAAC;QACxG,OAAO;IACT,CAAC;IAED,IAAI,EAAE,CAAC;AACT,CAAC"}

package/build/server/middleware/index.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Transport Middleware
+ *
+ * Collection of Express middleware for MCP transport security and validation.
+ * These middleware handle concerns that the SDK transport does NOT validate.
+ *
+ * ## Middleware Stack
+ *
+ * The following middleware are applied in the default Express pipeline:
+ *
+ * - **DNS Rebinding Protection** - Validates Host header (MCP MUST, not in SDK)
+ * - **Rate Limiting** - Prevents abuse and DoS attacks (not in SDK)
+ * - **Protocol Version** - Early rejection of unsupported protocol versions
+ *
+ * Content-Type, Accept header, and JSON-RPC validation are handled internally
+ * by the SDK's `StreamableHTTPServerTransport`.
+ *
+ * ## Default Middleware Stack Order
+ *
+ * ```typescript
+ * app.use('/mcp', dnsRebindingProtection);  // 1. Security (Express level)
+ * app.use('/mcp', createRateLimiter());     // 2. Rate limiting (Express level)
+ * app.use('/mcp', validateProtocolVersion); // 3. Protocol version (early reject)
+ * // SDK handles: Content-Type, Accept, JSON-RPC
+ * ```
+ *
+ * @see https://modelcontextprotocol.io/specification/2025-03-26/basic/transports
+ *
+ * @module server/middleware
+ */
+/**
+ * DNS Rebinding Protection (MCP MUST, not handled by SDK)
+ * Validates Host header to prevent DNS rebinding attacks
+ */
+export { dnsRebindingProtection } from "./dns-rebinding.js";
+/**
+ * Rate Limiting (not handled by SDK)
+ * Prevents abuse and DoS attacks
+ */
+export { createRateLimiter } from "./rate-limit.js";
+export type { RateLimiterOptions } from "./rate-limit.js";
+/**
+ * Protocol Version Validation
+ * Early rejection of unsupported protocol versions before reaching the SDK
+ */
+export { validateProtocolVersion } from "./protocol-version.js";
+/**
+ * Trust Proxy Resolution
+ * Validates and resolves trust proxy values with DNS hostname support
+ */
+export { resolveTrustProxy, TRUST_PROXY_KEYWORDS } from "./trust-proxy.js";
+/**
+ * Bearer Auth Middleware
+ * Validates access tokens via OAuth provider or custom token verifier
+ */
+export { createBearerAuth } from "./bearer-auth.js";
+export type { BearerAuthOptions } from "./bearer-auth.js";
+/**
+ * Custom Header Auth Middleware
+ * Extracts and validates tokens from custom headers (e.g. X-API-Key)
+ */
+export { createCustomHeaderAuth } from "./custom-header-auth.js";
+export type { CustomHeaderAuthOptions } from "./custom-header-auth.js";
+/**
+ * Sanitizes a string for logging to prevent log injection attacks.
+ * Replaces newlines and other control characters.
+ */
+export { sanitizeForLog, logSecurityEvent } from "./logging.js";
+//# sourceMappingURL=index.d.ts.map

package/build/server/middleware/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/server/middleware/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;;;GAGG;AACH,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAE5D;;;GAGG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,YAAY,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAE1D;;;GAGG;AACH,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAEhE;;;GAGG;AACH,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAI3E;;;GAGG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,YAAY,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE1D;;;GAGG;AACH,OAAO,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AACjE,YAAY,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAIvE;;;GAGG;AACH,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC"}

package/build/server/middleware/index.js

@@ -0,0 +1,68 @@
+/**
+ * Transport Middleware
+ *
+ * Collection of Express middleware for MCP transport security and validation.
+ * These middleware handle concerns that the SDK transport does NOT validate.
+ *
+ * ## Middleware Stack
+ *
+ * The following middleware are applied in the default Express pipeline:
+ *
+ * - **DNS Rebinding Protection** - Validates Host header (MCP MUST, not in SDK)
+ * - **Rate Limiting** - Prevents abuse and DoS attacks (not in SDK)
+ * - **Protocol Version** - Early rejection of unsupported protocol versions
+ *
+ * Content-Type, Accept header, and JSON-RPC validation are handled internally
+ * by the SDK's `StreamableHTTPServerTransport`.
+ *
+ * ## Default Middleware Stack Order
+ *
+ * ```typescript
+ * app.use('/mcp', dnsRebindingProtection);  // 1. Security (Express level)
+ * app.use('/mcp', createRateLimiter());     // 2. Rate limiting (Express level)
+ * app.use('/mcp', validateProtocolVersion); // 3. Protocol version (early reject)
+ * // SDK handles: Content-Type, Accept, JSON-RPC
+ * ```
+ *
+ * @see https://modelcontextprotocol.io/specification/2025-03-26/basic/transports
+ *
+ * @module server/middleware
+ */
+/**
+ * DNS Rebinding Protection (MCP MUST, not handled by SDK)
+ * Validates Host header to prevent DNS rebinding attacks
+ */
+export { dnsRebindingProtection } from "./dns-rebinding.js";
+/**
+ * Rate Limiting (not handled by SDK)
+ * Prevents abuse and DoS attacks
+ */
+export { createRateLimiter } from "./rate-limit.js";
+/**
+ * Protocol Version Validation
+ * Early rejection of unsupported protocol versions before reaching the SDK
+ */
+export { validateProtocolVersion } from "./protocol-version.js";
+/**
+ * Trust Proxy Resolution
+ * Validates and resolves trust proxy values with DNS hostname support
+ */
+export { resolveTrustProxy, TRUST_PROXY_KEYWORDS } from "./trust-proxy.js";
+// ===== Authentication Middleware =====
+/**
+ * Bearer Auth Middleware
+ * Validates access tokens via OAuth provider or custom token verifier
+ */
+export { createBearerAuth } from "./bearer-auth.js";
+/**
+ * Custom Header Auth Middleware
+ * Extracts and validates tokens from custom headers (e.g. X-API-Key)
+ */
+export { createCustomHeaderAuth } from "./custom-header-auth.js";
+// ===== Security Logging Utilities =====
+/**
+ * Sanitizes a string for logging to prevent log injection attacks.
+ * Replaces newlines and other control characters.
+ */
+export { sanitizeForLog, logSecurityEvent } from "./logging.js";
+//# sourceMappingURL=index.js.map

package/build/server/middleware/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/server/middleware/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;;;GAGG;AACH,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAE5D;;;GAGG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAGpD;;;GAGG;AACH,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAEhE;;;GAGG;AACH,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAE3E,wCAAwC;AAExC;;;GAGG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAGpD;;;GAGG;AACH,OAAO,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAGjE,yCAAyC;AAEzC;;;GAGG;AACH,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC"}

package/build/server/middleware/logging.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Security logging utilities for transport middleware
+ *
+ * @module server/middleware/logging
+ */
+/**
+ * Truncates and trims untrusted input for safe inclusion in log messages.
+ *
+ * Does NOT apply CWE-117 escaping here — the Logger pipeline applies
+ * InjectionGuard.sanitize() automatically. Pre-sanitizing would cause
+ * double-escaping (e.g., backslashes being re-escaped).
+ */
+export declare function sanitizeForLog(input: string | undefined | null): string;
+/**
+ * Logs security events with consistent formatting.
+ *
+ * @param event - Security event description
+ * @param details - Optional context for the event
+ */
+export declare function logSecurityEvent(event: string, details?: unknown): void;
+//# sourceMappingURL=logging.d.ts.map

package/build/server/middleware/logging.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logging.d.ts","sourceRoot":"","sources":["../../../src/server/middleware/logging.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAcH;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,CAGvE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAEvE"}

package/build/server/middleware/logging.js

@@ -0,0 +1,36 @@
+/**
+ * Security logging utilities for transport middleware
+ *
+ * @module server/middleware/logging
+ */
+import { logger as baseLogger } from "../../logger/index.js";
+import { TRANSPORT_LOG_COMPONENTS } from "../transport/constants.js";
+const logger = baseLogger.child({
+    component: TRANSPORT_LOG_COMPONENTS.SECURITY,
+});
+/** @internal Log messages for transport logging utilities */
+const LogMessages = {
+    SECURITY_EVENT: "Security: %s",
+};
+/**
+ * Truncates and trims untrusted input for safe inclusion in log messages.
+ *
+ * Does NOT apply CWE-117 escaping here — the Logger pipeline applies
+ * InjectionGuard.sanitize() automatically. Pre-sanitizing would cause
+ * double-escaping (e.g., backslashes being re-escaped).
+ */
+export function sanitizeForLog(input) {
+    if (!input)
+        return "";
+    return input.trim().slice(0, 200);
+}
+/**
+ * Logs security events with consistent formatting.
+ *
+ * @param event - Security event description
+ * @param details - Optional context for the event
+ */
+export function logSecurityEvent(event, details) {
+    logger.warn(LogMessages.SECURITY_EVENT, event, details || "");
+}
+//# sourceMappingURL=logging.js.map

package/build/server/middleware/logging.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logging.js","sourceRoot":"","sources":["../../../src/server/middleware/logging.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAErE,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC;IAC9B,SAAS,EAAE,wBAAwB,CAAC,QAAQ;CAC7C,CAAC,CAAC;AAEH,6DAA6D;AAC7D,MAAM,WAAW,GAAG;IAClB,cAAc,EAAE,cAAc;CACtB,CAAC;AAEX;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,KAAgC;IAC7D,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,CAAC;IACtB,OAAO,KAAK,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AACpC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAa,EAAE,OAAiB;IAC/D,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,cAAc,EAAE,KAAK,EAAE,OAAO,IAAI,EAAE,CAAC,CAAC;AAChE,CAAC"}