db-mcp 1.0.1

package/dist/auth/middleware.js

@@ -0,0 +1,291 @@
+/**
+ * db-mcp - OAuth Middleware
+ *
+ * Express middleware for OAuth 2.0 authentication and authorization.
+ * Extracts Bearer tokens, validates them, and enforces scope requirements.
+ */
+import { TokenMissingError, InvalidTokenError, InsufficientScopeError, isOAuthError, } from "./errors.js";
+import { scopesGrantToolAccess } from "./scopes.js";
+import { createModuleLogger, ERROR_CODES } from "../utils/logger.js";
+const logger = createModuleLogger("AUTH");
+// =============================================================================
+// Token Extraction
+// =============================================================================
+/**
+ * Extract Bearer token from Authorization header
+ *
+ * @param authHeader - Authorization header value
+ * @returns The token or null if not present/invalid
+ */
+export function extractBearerToken(authHeader) {
+    if (!authHeader) {
+        return null;
+    }
+    // Check for Bearer scheme (case-insensitive)
+    const parts = authHeader.split(" ");
+    const scheme = parts[0];
+    const tokenPart = parts[1];
+    if (parts.length !== 2 || scheme?.toLowerCase() !== "bearer") {
+        return null;
+    }
+    if (tokenPart === undefined) {
+        return null;
+    }
+    const token = tokenPart.trim();
+    return token.length > 0 ? token : null;
+}
+// =============================================================================
+// Path Matching
+// =============================================================================
+/**
+ * Check if a path matches any of the public path patterns
+ *
+ * Supports:
+ * - Exact matches: '/health' matches '/health'
+ * - Wildcard suffix: '/api/*' matches '/api/users', '/api/posts/1'
+ * - Well-known paths are always public
+ */
+function isPublicPath(path, publicPaths) {
+    // Well-known paths are always public (RFC requirement)
+    if (path.startsWith("/.well-known/")) {
+        return true;
+    }
+    for (const pattern of publicPaths) {
+        // Exact match
+        if (pattern === path) {
+            return true;
+        }
+        // Wildcard match
+        if (pattern.endsWith("/*")) {
+            const prefix = pattern.slice(0, -2);
+            if (path === prefix || path.startsWith(prefix + "/")) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+// =============================================================================
+// Main Authentication Middleware
+// =============================================================================
+/**
+ * Create the main authentication middleware
+ *
+ * This middleware:
+ * 1. Skips authentication for public paths (e.g., /.well-known/*)
+ * 2. Extracts Bearer token from Authorization header
+ * 3. Validates the token using the TokenValidator
+ * 4. Attaches validated claims to req.auth
+ * 5. Returns 401 with WWW-Authenticate header on failure
+ */
+export function createAuthMiddleware(config) {
+    const { tokenValidator, resourceServer, publicPaths = [] } = config;
+    return async (req, res, next) => {
+        // Generate request ID for tracing
+        const requestId = crypto.randomUUID();
+        req.requestId = requestId;
+        // Check if path is public
+        if (isPublicPath(req.path, publicPaths)) {
+            logger.info(`Public path accessed: ${req.path}`, {
+                code: "AUTH_PUBLIC_PATH",
+                requestId,
+                path: req.path,
+            });
+            next();
+            return;
+        }
+        // Extract Bearer token
+        const token = extractBearerToken(req.headers.authorization);
+        if (!token) {
+            const error = new TokenMissingError(resourceServer.getResourceUri());
+            logger.warning("No access token provided", {
+                code: ERROR_CODES.AUTH.TOKEN_MISSING.full,
+                requestId,
+                path: req.path,
+            });
+            res.status(error.httpStatus);
+            res.setHeader("WWW-Authenticate", error.wwwAuthenticate ?? "");
+            res.json({
+                error: "unauthorized",
+                error_description: error.message,
+            });
+            return;
+        }
+        // Validate token
+        const result = await tokenValidator.validate(token);
+        if (!result.valid) {
+            // Create error for logging (variable intentionally used only for type check)
+            new InvalidTokenError(result.error);
+            logger.warning(`Token validation failed: ${result.error ?? "Unknown error"}`, {
+                code: result.errorCode ?? ERROR_CODES.AUTH.TOKEN_INVALID.full,
+                requestId,
+                path: req.path,
+            });
+            res.status(401);
+            res.setHeader("WWW-Authenticate", resourceServer.getWWWAuthenticateHeader("invalid_token", result.error));
+            res.json({
+                error: "invalid_token",
+                error_description: result.error,
+            });
+            return;
+        }
+        // Attach claims to request (claims is guaranteed defined when valid is true)
+        const claims = result.claims;
+        if (!claims) {
+            // Should not happen when valid is true, but satisfies TypeScript
+            res.status(500).json({ error: "internal_error" });
+            return;
+        }
+        req.auth = claims;
+        req.accessToken = token;
+        logger.info(`Request authenticated: ${claims.sub}`, {
+            code: "AUTH_SUCCESS",
+            requestId,
+            sub: claims.sub,
+            scopes: claims.scopes.length,
+            path: req.path,
+        });
+        next();
+    };
+}
+// =============================================================================
+// Scope Enforcement Middleware
+// =============================================================================
+/**
+ * Middleware factory that requires a specific scope
+ *
+ * @param scope - Required scope
+ * @returns Express middleware
+ */
+export function requireScope(scope) {
+    return (req, res, next) => {
+        if (!req.auth) {
+            // Should not happen if auth middleware is applied first
+            res.status(401).json({
+                error: "unauthorized",
+                error_description: "Authentication required",
+            });
+            return;
+        }
+        const hasScope = req.auth.scopes.includes(scope) || req.auth.scopes.includes("admin"); // Admin scope grants all
+        if (!hasScope) {
+            const error = new InsufficientScopeError(scope, req.auth.scopes);
+            logger.warning(`Insufficient scope: required ${scope}`, {
+                code: ERROR_CODES.AUTH.SCOPE_DENIED.full,
+                requestId: req.requestId,
+                requiredScope: scope,
+                providedScopes: req.auth.scopes,
+            });
+            res.status(error.httpStatus);
+            res.setHeader("WWW-Authenticate", error.wwwAuthenticate ?? "");
+            res.json({
+                error: "insufficient_scope",
+                error_description: error.message,
+                required_scope: scope,
+            });
+            return;
+        }
+        next();
+    };
+}
+/**
+ * Middleware factory that requires any of the specified scopes
+ *
+ * @param scopes - Array of acceptable scopes (user must have at least one)
+ * @returns Express middleware
+ */
+export function requireAnyScope(scopes) {
+    return (req, res, next) => {
+        if (!req.auth) {
+            res.status(401).json({
+                error: "unauthorized",
+                error_description: "Authentication required",
+            });
+            return;
+        }
+        // Admin scope grants all
+        if (req.auth.scopes.includes("admin")) {
+            next();
+            return;
+        }
+        const hasAnyScope = scopes.some((scope) => req.auth?.scopes.includes(scope));
+        if (!hasAnyScope) {
+            const error = new InsufficientScopeError(scopes, req.auth.scopes);
+            logger.warning(`Insufficient scope: required one of [${scopes.join(", ")}]`, {
+                code: ERROR_CODES.AUTH.SCOPE_DENIED.full,
+                requestId: req.requestId,
+                requiredScopes: scopes,
+                providedScopes: req.auth.scopes,
+            });
+            res.status(error.httpStatus);
+            res.setHeader("WWW-Authenticate", error.wwwAuthenticate ?? "");
+            res.json({
+                error: "insufficient_scope",
+                error_description: error.message,
+                required_scopes: scopes,
+            });
+            return;
+        }
+        next();
+    };
+}
+/**
+ * Middleware factory that requires scope for a specific tool
+ *
+ * @param toolName - Name of the tool being accessed
+ * @returns Express middleware
+ */
+export function requireToolScope(toolName) {
+    return (req, res, next) => {
+        if (!req.auth) {
+            res.status(401).json({
+                error: "unauthorized",
+                error_description: "Authentication required",
+            });
+            return;
+        }
+        const hasAccess = scopesGrantToolAccess(req.auth.scopes, toolName);
+        if (!hasAccess) {
+            const error = new InsufficientScopeError(`Tool access: ${toolName}`, req.auth.scopes);
+            logger.warning(`Insufficient scope for tool: ${toolName}`, {
+                code: ERROR_CODES.AUTH.SCOPE_DENIED.full,
+                requestId: req.requestId,
+                toolName,
+                providedScopes: req.auth.scopes,
+            });
+            res.status(error.httpStatus);
+            res.setHeader("WWW-Authenticate", error.wwwAuthenticate ?? "");
+            res.json({
+                error: "insufficient_scope",
+                error_description: `Access to tool '${toolName}' denied`,
+                tool: toolName,
+            });
+            return;
+        }
+        next();
+    };
+}
+// =============================================================================
+// Error Handler
+// =============================================================================
+/**
+ * Error handler middleware for OAuth errors
+ *
+ * Should be added after all routes to catch OAuth-related errors
+ */
+export function oauthErrorHandler(error, _req, res, next) {
+    if (isOAuthError(error)) {
+        res.status(error.httpStatus);
+        if (error.wwwAuthenticate) {
+            res.setHeader("WWW-Authenticate", error.wwwAuthenticate);
+        }
+        res.json({
+            error: error.code,
+            error_description: error.message,
+        });
+        return;
+    }
+    // Pass to next error handler
+    next(error);
+}
+//# sourceMappingURL=middleware.js.map

package/dist/auth/middleware.js.map

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

package/dist/auth/scopes.d.ts

@@ -0,0 +1,136 @@
+/**
+ * db-mcp - OAuth Scopes
+ *
+ * Scope definitions and enforcement utilities for
+ * granular access control.
+ *
+ * Scope Patterns:
+ *   - read      : Read-only access to all databases
+ *   - write     : Read and write access to all databases
+ *   - admin     : Full administrative access
+ *   - db:{name} : Access to specific database only
+ *   - table:{db}:{table} : Access to specific table only
+ */
+import type { ToolGroup } from "../types/index.js";
+/**
+ * Base scopes supported by the server
+ */
+export declare const BASE_SCOPES: readonly ["read", "write", "admin"];
+/**
+ * Scope patterns (regex patterns for validation)
+ */
+export declare const SCOPE_PATTERNS: {
+    /** Read-only access */
+    readonly READ: "read";
+    /** Read and write access */
+    readonly WRITE: "write";
+    /** Full admin access */
+    readonly ADMIN: "admin";
+    /** Database-specific access pattern */
+    readonly DATABASE: RegExp;
+    /** Table-specific access pattern */
+    readonly TABLE: RegExp;
+};
+/**
+ * All supported scope patterns for metadata
+ */
+export declare const SUPPORTED_SCOPES: readonly ["read", "write", "admin", "db:{database}", "table:{database}:{table}"];
+/**
+ * Tool groups accessible with read scope (read-only operations)
+ */
+export declare const READ_SCOPE_GROUPS: ToolGroup[];
+/**
+ * Tool groups accessible with write scope (read + write operations)
+ */
+export declare const WRITE_SCOPE_GROUPS: ToolGroup[];
+/**
+ * Tool groups accessible with admin scope (all operations)
+ */
+export declare const ADMIN_SCOPE_GROUPS: ToolGroup[];
+/**
+ * Read-only tools within the core group
+ * (used when scope is 'read' to filter write operations)
+ */
+export declare const READ_ONLY_TOOLS: Set<string>;
+/**
+ * Write tools that require 'write' scope
+ */
+export declare const WRITE_TOOLS: Set<string>;
+/**
+ * Admin tools that require 'admin' scope
+ */
+export declare const ADMIN_TOOLS: Set<string>;
+/**
+ * Parse a scope string (space-delimited) into an array
+ */
+export declare function parseScopes(scopeString: string): string[];
+/**
+ * Parse a database-specific scope
+ * @returns The database name or null if not a database scope
+ */
+export declare function parseDatabaseScope(scope: string): string | null;
+/**
+ * Parse a table-specific scope
+ * @returns Object with database and table names, or null if not a table scope
+ */
+export declare function parseTableScope(scope: string): {
+    database: string;
+    table: string;
+} | null;
+/**
+ * Check if a scope is valid (matches known patterns)
+ */
+export declare function isValidScope(scope: string): boolean;
+/**
+ * Check if scopes include admin access
+ */
+export declare function hasAdminScope(scopes: string[]): boolean;
+/**
+ * Check if scopes include write access
+ */
+export declare function hasWriteScope(scopes: string[]): boolean;
+/**
+ * Check if scopes include read access
+ */
+export declare function hasReadScope(scopes: string[]): boolean;
+/**
+ * Check if a scope grants access to a specific tool
+ */
+export declare function scopeGrantsToolAccess(scope: string, toolName: string): boolean;
+/**
+ * Check if any of the scopes grants access to a tool
+ */
+export declare function scopesGrantToolAccess(scopes: string[], toolName: string): boolean;
+/**
+ * Check if a scope grants access to a specific database
+ */
+export declare function scopeGrantsDatabaseAccess(scope: string, databaseName: string): boolean;
+/**
+ * Check if any of the scopes grants access to a database
+ */
+export declare function scopesGrantDatabaseAccess(scopes: string[], databaseName: string): boolean;
+/**
+ * Check if a scope grants access to a specific table
+ */
+export declare function scopeGrantsTableAccess(scope: string, databaseName: string, tableName: string): boolean;
+/**
+ * Check if any of the scopes grants access to a table
+ */
+export declare function scopesGrantTableAccess(scopes: string[], databaseName: string, tableName: string): boolean;
+/**
+ * Get the required minimum scope for a tool group
+ */
+export declare function getRequiredScopeForGroup(group: ToolGroup): string;
+/**
+ * Get the required minimum scope for a tool
+ */
+export declare function getRequiredScopeForTool(toolName: string): string;
+/**
+ * Get tool groups accessible with given scopes
+ */
+export declare function getAccessibleToolGroups(scopes: string[]): ToolGroup[];
+/**
+ * Get all tools accessible with given scopes
+ */
+export declare function getAccessibleTools(scopes: string[]): string[];
+//# sourceMappingURL=scopes.d.ts.map

package/dist/auth/scopes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scopes.d.ts","sourceRoot":"","sources":["../../src/auth/scopes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAOnD;;GAEG;AACH,eAAO,MAAM,WAAW,qCAAsC,CAAC;AAE/D;;GAEG;AACH,eAAO,MAAM,cAAc;IACzB,uBAAuB;;IAEvB,4BAA4B;;IAE5B,wBAAwB;;IAExB,uCAAuC;;IAEvC,oCAAoC;;CAE5B,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,gBAAgB,kFAMnB,CAAC;AAMX;;GAEG;AACH,eAAO,MAAM,iBAAiB,EAAE,SAAS,EAExC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,EAMzC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,EAGzC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,eAAe,aAe1B,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,WAAW,aActB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,WAAW,aAYtB,CAAC;AAMH;;GAEG;AACH,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CAKzD;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG/D;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,GACZ;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAQ5C;AAMD;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAiBnD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAEvD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAEvD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAEtD;AAMD;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,GACf,OAAO,CAsBT;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,EAAE,EAChB,QAAQ,EAAE,MAAM,GACf,OAAO,CAET;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,MAAM,GACnB,OAAO,CAmBT;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,EAAE,EAChB,YAAY,EAAE,MAAM,GACnB,OAAO,CAET;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,GAChB,OAAO,CAmBT;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,EAAE,EAChB,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,GAChB,OAAO,CAIT;AAMD;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAcjE;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAQhE;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,SAAS,EAAE,CAWrE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAmB7D"}