@neverinfamous/mysql-mcp 2.1.0

package/src/auth/middleware.ts

@@ -0,0 +1,214 @@
+/**
+ * mysql-mcp - OAuth Middleware
+ * 
+ * Authentication and authorization middleware for HTTP transport.
+ */
+
+import type { TokenClaims } from './types.js';
+import type { TokenValidator } from './TokenValidator.js';
+import { TokenMissingError, InvalidTokenError, InsufficientScopeError } from './errors.js';
+import { hasScope, hasAnyScope, SCOPES } from './scopes.js';
+
+/**
+ * Authenticated request context
+ */
+export interface AuthenticatedContext {
+    /** Whether request is authenticated */
+    authenticated: boolean;
+
+    /** Token claims (if authenticated) */
+    claims?: TokenClaims;
+
+    /** Token scopes (convenience) */
+    scopes: string[];
+}
+
+/**
+ * Auth middleware configuration
+ */
+export interface AuthMiddlewareConfig {
+    /** Token validator instance */
+    tokenValidator: TokenValidator;
+
+    /** Whether to require authentication (default: true) */
+    required?: boolean;
+
+    /** Required scopes (any of these) */
+    requiredScopes?: string[];
+}
+
+/**
+ * Extract bearer token from Authorization header
+ */
+export function extractBearerToken(authHeader: string | undefined): string | null {
+    if (!authHeader) {
+        return null;
+    }
+
+    const parts = authHeader.split(' ');
+    if (parts.length !== 2 || parts[0]?.toLowerCase() !== 'bearer') {
+        return null;
+    }
+
+    return parts[1] ?? null;
+}
+
+/**
+ * Create authentication context from request
+ */
+export async function createAuthContext(
+    authHeader: string | undefined,
+    tokenValidator: TokenValidator
+): Promise<AuthenticatedContext> {
+    const token = extractBearerToken(authHeader);
+
+    if (!token) {
+        return { authenticated: false, scopes: [] };
+    }
+
+    const result = await tokenValidator.validate(token);
+
+    if (!result.valid || !result.claims) {
+        return { authenticated: false, scopes: [] };
+    }
+
+    return {
+        authenticated: true,
+        claims: result.claims,
+        scopes: result.claims.scopes
+    };
+}
+
+/**
+ * Validate authentication and authorization
+ */
+export async function validateAuth(
+    authHeader: string | undefined,
+    config: AuthMiddlewareConfig
+): Promise<AuthenticatedContext> {
+    const token = extractBearerToken(authHeader);
+
+    // Check if token is required
+    if (!token) {
+        if (config.required !== false) {
+            throw new TokenMissingError();
+        }
+        return { authenticated: false, scopes: [] };
+    }
+
+    // Validate the token
+    const result = await config.tokenValidator.validate(token);
+
+    if (!result.valid || !result.claims) {
+        throw new InvalidTokenError(result.error ?? 'Invalid token');
+    }
+
+    const context: AuthenticatedContext = {
+        authenticated: true,
+        claims: result.claims,
+        scopes: result.claims.scopes
+    };
+
+    // Check required scopes
+    if (config.requiredScopes && config.requiredScopes.length > 0) {
+        if (!hasAnyScope(context.scopes, config.requiredScopes)) {
+            throw new InsufficientScopeError(config.requiredScopes);
+        }
+    }
+
+    return context;
+}
+
+/**
+ * Check if context has required scope
+ */
+export function requireScope(context: AuthenticatedContext, scope: string): void {
+    if (!context.authenticated) {
+        throw new TokenMissingError();
+    }
+
+    if (!hasScope(context.scopes, scope)) {
+        throw new InsufficientScopeError([scope]);
+    }
+}
+
+/**
+ * Check if context has any of the required scopes
+ */
+export function requireAnyScope(context: AuthenticatedContext, scopes: string[]): void {
+    if (!context.authenticated) {
+        throw new TokenMissingError();
+    }
+
+    if (!hasAnyScope(context.scopes, scopes)) {
+        throw new InsufficientScopeError(scopes);
+    }
+}
+
+/**
+ * Check if context has scope for a tool operation
+ */
+export function requireToolScope(context: AuthenticatedContext, requiredScopes: string[]): void {
+    if (!context.authenticated) {
+        throw new TokenMissingError();
+    }
+
+    // Map tool required scopes to actual OAuth scopes
+    const mappedScopes = requiredScopes.map(scope => {
+        switch (scope) {
+            case 'read': return SCOPES.READ;
+            case 'write': return SCOPES.WRITE;
+            case 'admin': return SCOPES.ADMIN;
+            default: return scope;
+        }
+    });
+
+    if (!hasAnyScope(context.scopes, mappedScopes)) {
+        throw new InsufficientScopeError(mappedScopes);
+    }
+}
+
+/**
+ * Format OAuth error for HTTP response
+ */
+export function formatOAuthError(error: unknown): { status: number; body: object } {
+    if (error instanceof TokenMissingError) {
+        return {
+            status: 401,
+            body: {
+                error: 'invalid_token',
+                error_description: error.message
+            }
+        };
+    }
+
+    if (error instanceof InvalidTokenError) {
+        return {
+            status: 401,
+            body: {
+                error: 'invalid_token',
+                error_description: error.message
+            }
+        };
+    }
+
+    if (error instanceof InsufficientScopeError) {
+        return {
+            status: 403,
+            body: {
+                error: 'insufficient_scope',
+                error_description: error.message,
+                scope: error.requiredScopes.join(' ')
+            }
+        };
+    }
+
+    // Generic error
+    return {
+        status: 500,
+        body: {
+            error: 'server_error',
+            error_description: 'Internal server error'
+        }
+    };
+}

package/src/auth/scopes.ts

@@ -0,0 +1,193 @@
+/**
+ * mysql-mcp - OAuth Scopes
+ * 
+ * Scope definitions and utilities for MySQL MCP OAuth 2.0.
+ */
+
+import type { ToolGroup } from '../types/index.js';
+
+// =============================================================================
+// Scope Definitions
+// =============================================================================
+
+/**
+ * Standard OAuth scopes for mysql-mcp
+ */
+export const SCOPES = {
+    /** Read-only access to all databases */
+    READ: 'read',
+
+    /** Read and write access to all databases */
+    WRITE: 'write',
+
+    /** Administrative access (OPTIMIZE, ANALYZE, etc.) */
+    ADMIN: 'admin',
+
+    /** Full access to all operations */
+    FULL: 'full'
+} as const;
+
+export type StandardScope = typeof SCOPES[keyof typeof SCOPES];
+
+/**
+ * All supported scopes including patterns
+ */
+export const ALL_SCOPES = [
+    SCOPES.READ,
+    SCOPES.WRITE,
+    SCOPES.ADMIN,
+    SCOPES.FULL,
+    // Pattern scopes: db:{name}, table:{db}:{table}
+] as const;
+
+// =============================================================================
+// Tool Group to Scope Mapping
+// =============================================================================
+
+/**
+ * Map tool groups to required minimum scopes
+ */
+export const TOOL_GROUP_SCOPES: Record<ToolGroup, StandardScope> = {
+    core: SCOPES.READ,
+    json: SCOPES.READ,
+    text: SCOPES.READ,
+    fulltext: SCOPES.READ,
+    performance: SCOPES.READ,
+    optimization: SCOPES.READ,
+    monitoring: SCOPES.READ,
+    admin: SCOPES.ADMIN,
+    backup: SCOPES.ADMIN,
+    replication: SCOPES.ADMIN,
+    partitioning: SCOPES.ADMIN,
+    transactions: SCOPES.WRITE,
+    router: SCOPES.READ,
+    proxysql: SCOPES.READ,
+    shell: SCOPES.ADMIN,
+    // New tool groups (v2.0.0)
+    schema: SCOPES.READ,
+    events: SCOPES.ADMIN,
+    sysschema: SCOPES.READ,
+    stats: SCOPES.READ,
+    spatial: SCOPES.READ,
+    security: SCOPES.ADMIN,
+    cluster: SCOPES.READ,
+    roles: SCOPES.ADMIN,
+    docstore: SCOPES.WRITE
+};
+
+// =============================================================================
+// Scope Utilities
+// =============================================================================
+
+/**
+ * Parse scope string into array
+ */
+export function parseScopes(scopeString: string | undefined): string[] {
+    if (!scopeString) return [];
+    return scopeString.split(' ').filter(s => s.length > 0);
+}
+
+/**
+ * Check if granted scopes include the required scope
+ */
+export function hasScope(grantedScopes: string[], requiredScope: string): boolean {
+    // Full scope grants everything
+    if (grantedScopes.includes(SCOPES.FULL)) {
+        return true;
+    }
+
+    // Direct match
+    if (grantedScopes.includes(requiredScope)) {
+        return true;
+    }
+
+    // Admin scope includes write and read
+    if (requiredScope === SCOPES.READ || requiredScope === SCOPES.WRITE) {
+        if (grantedScopes.includes(SCOPES.ADMIN)) {
+            return true;
+        }
+    }
+
+    // Write scope includes read
+    if (requiredScope === SCOPES.READ) {
+        if (grantedScopes.includes(SCOPES.WRITE)) {
+            return true;
+        }
+    }
+
+    return false;
+}
+
+/**
+ * Check if granted scopes include any of the required scopes
+ */
+export function hasAnyScope(grantedScopes: string[], requiredScopes: string[]): boolean {
+    return requiredScopes.some(scope => hasScope(grantedScopes, scope));
+}
+
+/**
+ * Check if granted scopes include all of the required scopes
+ */
+export function hasAllScopes(grantedScopes: string[], requiredScopes: string[]): boolean {
+    return requiredScopes.every(scope => hasScope(grantedScopes, scope));
+}
+
+/**
+ * Get the required scope for a tool group
+ */
+export function getScopeForToolGroup(group: ToolGroup): StandardScope {
+    return TOOL_GROUP_SCOPES[group] ?? SCOPES.READ;
+}
+
+/**
+ * Check if database-specific scope matches
+ */
+export function hasDatabaseScope(grantedScopes: string[], database: string): boolean {
+    // Full or admin grants all databases
+    if (grantedScopes.includes(SCOPES.FULL) || grantedScopes.includes(SCOPES.ADMIN)) {
+        return true;
+    }
+
+    // Check for db:{name} pattern
+    const dbScope = `db:${database}`;
+    return grantedScopes.includes(dbScope);
+}
+
+/**
+ * Check if table-specific scope matches
+ */
+export function hasTableScope(grantedScopes: string[], database: string, table: string): boolean {
+    // Full or admin grants all tables
+    if (grantedScopes.includes(SCOPES.FULL) || grantedScopes.includes(SCOPES.ADMIN)) {
+        return true;
+    }
+
+    // Check for db:{name} scope (grants access to all tables in db)
+    if (hasDatabaseScope(grantedScopes, database)) {
+        return true;
+    }
+
+    // Check for table:{db}:{table} pattern
+    const tableScope = `table:${database}:${table}`;
+    return grantedScopes.includes(tableScope);
+}
+
+/**
+ * Get scope display name
+ */
+export function getScopeDisplayName(scope: string): string {
+    switch (scope) {
+        case SCOPES.READ: return 'Read Only';
+        case SCOPES.WRITE: return 'Read/Write';
+        case SCOPES.ADMIN: return 'Administrative';
+        case SCOPES.FULL: return 'Full Access';
+        default:
+            if (scope.startsWith('db:')) {
+                return `Database: ${scope.slice(3)}`;
+            }
+            if (scope.startsWith('table:')) {
+                return `Table: ${scope.slice(6)}`;
+            }
+            return scope;
+    }
+}

package/src/auth/types.ts

@@ -0,0 +1,303 @@
+/**
+ * mysql-mcp - OAuth Types
+ * 
+ * Type definitions for OAuth 2.0 components including
+ * RFC 9728, RFC 8414, and RFC 7591 compliance.
+ */
+
+// =============================================================================
+// RFC 9728 - Protected Resource Metadata
+// =============================================================================
+
+/**
+ * OAuth 2.0 Protected Resource Metadata (RFC 9728)
+ */
+export interface ProtectedResourceMetadata {
+    /** Resource identifier (canonical URI) */
+    resource: string;
+
+    /** Authorization servers that can issue tokens for this resource */
+    authorization_servers?: string[];
+
+    /** JWKS URI for token verification */
+    jwks_uri?: string;
+
+    /** Scopes supported by this resource */
+    scopes_supported?: string[];
+
+    /** Bearer token presentation methods supported */
+    bearer_methods_supported?: ('header' | 'body' | 'query')[];
+
+    /** Resource signing algorithms supported */
+    resource_signing_alg_values_supported?: string[];
+
+    /** Resource documentation URL */
+    resource_documentation?: string;
+
+    /** Resource policy URI */
+    resource_policy_uri?: string;
+
+    /** Resource terms of service URI */
+    resource_tos_uri?: string;
+}
+
+// =============================================================================
+// RFC 8414 - Authorization Server Metadata
+// =============================================================================
+
+/**
+ * OAuth 2.0 Authorization Server Metadata (RFC 8414)
+ */
+export interface AuthorizationServerMetadata {
+    /** Authorization server issuer identifier */
+    issuer: string;
+
+    /** Authorization endpoint URL */
+    authorization_endpoint?: string;
+
+    /** Token endpoint URL */
+    token_endpoint: string;
+
+    /** JWKS URI */
+    jwks_uri?: string;
+
+    /** Registration endpoint (RFC 7591) */
+    registration_endpoint?: string;
+
+    /** Scopes supported */
+    scopes_supported?: string[];
+
+    /** Response types supported */
+    response_types_supported?: string[];
+
+    /** Grant types supported */
+    grant_types_supported?: string[];
+
+    /** Token endpoint auth methods supported */
+    token_endpoint_auth_methods_supported?: string[];
+
+    /** Code challenge methods supported (PKCE) */
+    code_challenge_methods_supported?: string[];
+}
+
+// =============================================================================
+// RFC 7591 - Dynamic Client Registration
+// =============================================================================
+
+/**
+ * OAuth 2.0 Dynamic Client Registration Request (RFC 7591)
+ */
+export interface ClientRegistrationRequest {
+    /** Redirect URIs */
+    redirect_uris?: string[];
+
+    /** Token endpoint auth method */
+    token_endpoint_auth_method?: string;
+
+    /** Grant types requested */
+    grant_types?: string[];
+
+    /** Response types requested */
+    response_types?: string[];
+
+    /** Client name */
+    client_name?: string;
+
+    /** Client URI */
+    client_uri?: string;
+
+    /** Scopes requested */
+    scope?: string;
+
+    /** JWKS URI for client authentication */
+    jwks_uri?: string;
+
+    /** JWKS document for client authentication */
+    jwks?: JWKSDocument;
+}
+
+/**
+ * OAuth 2.0 Dynamic Client Registration Response (RFC 7591)
+ */
+export interface ClientRegistrationResponse {
+    /** Client identifier */
+    client_id: string;
+
+    /** Client secret (for confidential clients) */
+    client_secret?: string;
+
+    /** Client secret expiration timestamp */
+    client_secret_expires_at?: number;
+
+    /** Registration access token */
+    registration_access_token?: string;
+
+    /** Registration client URI */
+    registration_client_uri?: string;
+
+    /** Client ID issued at timestamp */
+    client_id_issued_at?: number;
+
+    /** All other fields from the request */
+    [key: string]: unknown;
+}
+
+// =============================================================================
+// JWKS Types
+// =============================================================================
+
+/**
+ * JSON Web Key (JWK)
+ */
+export interface JWK {
+    /** Key type (e.g., 'RSA', 'EC') */
+    kty: string;
+
+    /** Key use ('sig' for signature, 'enc' for encryption) */
+    use?: string;
+
+    /** Key operations */
+    key_ops?: string[];
+
+    /** Algorithm */
+    alg?: string;
+
+    /** Key ID */
+    kid?: string;
+
+    // RSA-specific fields
+    /** RSA modulus */
+    n?: string;
+    /** RSA public exponent */
+    e?: string;
+
+    // EC-specific fields
+    /** EC curve */
+    crv?: string;
+    /** EC x coordinate */
+    x?: string;
+    /** EC y coordinate */
+    y?: string;
+}
+
+/**
+ * JSON Web Key Set (JWKS)
+ */
+export interface JWKSDocument {
+    /** Array of JWK keys */
+    keys: JWK[];
+}
+
+// =============================================================================
+// Token Validation Types
+// =============================================================================
+
+/**
+ * Result of token validation
+ */
+export interface TokenValidationResult {
+    /** Whether the token is valid */
+    valid: boolean;
+
+    /** Validated claims (if valid) */
+    claims?: TokenClaims;
+
+    /** Error message (if invalid) */
+    error?: string;
+
+    /** Error code (if invalid) */
+    errorCode?: string;
+}
+
+/**
+ * Validated token claims
+ */
+export interface TokenClaims {
+    /** Subject (user ID) */
+    sub: string;
+
+    /** Granted scopes (parsed from space-delimited string) */
+    scopes: string[];
+
+    /** Token expiration time (Unix timestamp) */
+    exp: number;
+
+    /** Token issued at time (Unix timestamp) */
+    iat: number;
+
+    /** Token issuer */
+    iss?: string | undefined;
+
+    /** Token audience */
+    aud?: string | string[] | undefined;
+
+    /** Not before time (Unix timestamp) */
+    nbf?: number | undefined;
+
+    /** JWT ID */
+    jti?: string | undefined;
+
+    /** Client ID */
+    client_id?: string | undefined;
+
+    /** Additional claims */
+    [key: string]: unknown;
+}
+
+// =============================================================================
+// Configuration Types
+// =============================================================================
+
+/**
+ * Resource server configuration
+ */
+export interface ResourceServerConfig {
+    /** Resource identifier (canonical server URI) */
+    resource: string;
+
+    /** Authorization servers that can issue tokens */
+    authorizationServers: string[];
+
+    /** Scopes supported by this resource */
+    scopesSupported: string[];
+
+    /** Bearer token methods accepted (default: ['header']) */
+    bearerMethodsSupported?: ('header' | 'body' | 'query')[];
+}
+
+/**
+ * Token validator configuration
+ */
+export interface TokenValidatorConfig {
+    /** JWKS URI for key discovery */
+    jwksUri: string;
+
+    /** Expected issuer */
+    issuer: string;
+
+    /** Expected audience */
+    audience: string;
+
+    /** Clock tolerance in seconds (default: 60) */
+    clockTolerance?: number | undefined;
+
+    /** JWKS cache TTL in seconds (default: 3600) */
+    jwksCacheTtl?: number | undefined;
+
+    /** Supported algorithms (default: ['RS256', 'RS384', 'RS512', 'ES256', 'ES384', 'ES512']) */
+    algorithms?: string[] | undefined;
+}
+
+/**
+ * Authorization server discovery configuration
+ */
+export interface AuthServerDiscoveryConfig {
+    /** Authorization server URL (issuer) */
+    authServerUrl: string;
+
+    /** Cache TTL in seconds (default: 3600) */
+    cacheTtl?: number | undefined;
+
+    /** Request timeout in milliseconds (default: 5000) */
+    timeout?: number | undefined;
+}