@dollhousemcp/mcp-server/dist/web/middleware/authMiddleware.d.ts

DollhouseMCP - A Model Context Protocol (MCP) server that enables dynamic AI persona management from markdown files, allowing Claude and other compatible AI assistants to activate and switch between different behavioral personas.

/**
 * Express middleware for console Bearer token authentication (#1780).
 *
 * Checks the `Authorization: Bearer <token>` header on requests to protected
 * endpoints, with a `?token=<token>` query parameter fallback for SSE streams
 * (EventSource cannot set custom headers).
 *
 * Behavior is gated on the `DOLLHOUSE_WEB_AUTH_ENABLED` env var. When the flag
 * is false (the default during Phase 1 rollout) the middleware is a no-op —
 * requests pass through unconditionally. When true, every protected request
 * must carry a valid token or receive a 401.
 *
 * Phase 1 design notes:
 * - Every valid token is treated as admin-scoped. Scope enforcement is a
 *   stubbed hook (`authorizeScope`) that always returns true. Phase 2 swaps
 *   in real scope checks without touching any route handler.
 * - Element boundaries and tenant filtering are similarly stubbed for Phase 3.
 * - The middleware attaches the matched token entry to `res.locals.tokenEntry`
 *   so downstream handlers can inspect it (audit logs, scope decisions, etc.).
 *
 * @since v2.1.0 — Issue #1780
 */
import type { RequestHandler } from 'express';
import type { ConsoleTokenStore } from '../console/consoleToken.js';
/**
 * Options for the auth middleware factory.
 */
export interface AuthMiddlewareOptions {
    /** The token store holding valid tokens. */
    store: ConsoleTokenStore;
    /** Whether auth is enforced. When false, middleware is a no-op. */
    enabled: boolean;
    /**
     * Path prefixes that are never protected. A request whose URL path starts
     * with any of these strings will skip auth and be passed through to the
     * next handler. Used to exempt health checks, version info, client detection,
     * and similar public metadata endpoints.
     *
     * Paths are compared against `req.path` (the route-relative path), so include
     * the full pathname starting with `/` — e.g. `/api/health`, `/api/setup/version`.
     */
    publicPathPrefixes?: string[];
    /** Optional label for log messages (e.g. "api" or "sse"). */
    label?: string;
}
/**
 * Create the core authentication middleware.
 *
 * The returned handler enforces Bearer token auth on every request it sees.
 * Mount it with `app.use(createAuthMiddleware(...))` before protected routers,
 * or attach it to individual routes that need protection.
 *
 * When `enabled: false`, the handler immediately calls `next()` — allowing
 * the infrastructure to land with the default-off feature flag without
 * breaking existing traffic.
 *
 * Phase 3 hardening (tracked in #1789): Add 401 rate limiting to prevent
 * DoS from floods of bad-token requests. Brute-forcing a 256-bit token is
 * infeasible, but an attacker flooding /api with wrong tokens could saturate
 * the verify path. A sliding-window limiter keyed on the requesting IP is
 * the right shape.
 */
export declare function createAuthMiddleware(options: AuthMiddlewareOptions): RequestHandler;
//# sourceMappingURL=authMiddleware.d.ts.map