@neverinfamous/mysql-mcp 2.1.0

package/src/auth/__tests__/middleware.test.ts

@@ -0,0 +1,276 @@
+/**
+ * mysql-mcp - Middleware Unit Tests
+ * 
+ * Tests for OAuth middleware utilities.
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import {
+    extractBearerToken,
+    formatOAuthError,
+    validateAuth,
+    createAuthContext,
+    requireScope,
+    requireAnyScope,
+    requireToolScope,
+    type AuthenticatedContext
+} from '../middleware.js';
+import { TokenMissingError, InvalidTokenError, InsufficientScopeError } from '../errors.js';
+import type { TokenValidator } from '../TokenValidator.js';
+
+// Create mock token validator
+function createMockTokenValidator(overrides: Partial<TokenValidator> = {}): TokenValidator {
+    return {
+        validate: vi.fn().mockResolvedValue({ valid: true, claims: { sub: 'user1', scopes: ['read', 'write'], exp: 0, iat: 0 } }),
+        invalidateCache: vi.fn(),
+        ...overrides
+    } as unknown as TokenValidator;
+}
+
+describe('extractBearerToken', () => {
+    it('should extract token from valid Bearer header', () => {
+        expect(extractBearerToken('Bearer abc123')).toBe('abc123');
+    });
+
+    it('should return null for undefined header', () => {
+        expect(extractBearerToken(undefined)).toBeNull();
+    });
+
+    it('should return null for empty header', () => {
+        expect(extractBearerToken('')).toBeNull();
+    });
+
+    it('should return null for non-Bearer auth', () => {
+        expect(extractBearerToken('Basic abc123')).toBeNull();
+    });
+
+    it('should return null for malformed Bearer header', () => {
+        expect(extractBearerToken('Bearer')).toBeNull();
+    });
+
+    it('should return empty string for Bearer with trailing space only', () => {
+        // Note: 'Bearer ' (with trailing space) splits to ['bearer', ''] which returns ''
+        expect(extractBearerToken('Bearer ')).toBe('');
+    });
+
+    it('should be case-insensitive for Bearer keyword', () => {
+        expect(extractBearerToken('bearer abc123')).toBe('abc123');
+        expect(extractBearerToken('BEARER abc123')).toBe('abc123');
+    });
+});
+
+describe('formatOAuthError', () => {
+    it('should format TokenMissingError as 401', () => {
+        const result = formatOAuthError(new TokenMissingError());
+        expect(result.status).toBe(401);
+        expect(result.body).toHaveProperty('error', 'invalid_token');
+    });
+
+    it('should format InvalidTokenError as 401', () => {
+        const result = formatOAuthError(new InvalidTokenError('Token expired'));
+        expect(result.status).toBe(401);
+        expect(result.body).toHaveProperty('error', 'invalid_token');
+    });
+
+    it('should format InsufficientScopeError as 403', () => {
+        const result = formatOAuthError(new InsufficientScopeError(['admin', 'write']));
+        expect(result.status).toBe(403);
+        expect(result.body).toHaveProperty('error', 'insufficient_scope');
+        expect(result.body).toHaveProperty('scope', 'admin write');
+    });
+
+    it('should format unknown errors as 500', () => {
+        const result = formatOAuthError(new Error('Something went wrong'));
+        expect(result.status).toBe(500);
+        expect(result.body).toHaveProperty('error', 'server_error');
+    });
+});
+
+describe('createAuthContext', () => {
+    let mockValidator: TokenValidator;
+
+    beforeEach(() => {
+        mockValidator = createMockTokenValidator();
+    });
+
+    it('should return unauthenticated context when no token', async () => {
+        const context = await createAuthContext(undefined, mockValidator);
+        expect(context.authenticated).toBe(false);
+        expect(context.scopes).toEqual([]);
+    });
+
+    it('should return authenticated context for valid token', async () => {
+        const context = await createAuthContext('Bearer validtoken', mockValidator);
+        expect(context.authenticated).toBe(true);
+        expect(context.scopes).toEqual(['read', 'write']);
+        expect(context.claims).toBeDefined();
+    });
+
+    it('should return unauthenticated context for invalid token', async () => {
+        const invalidValidator = createMockTokenValidator({
+            validate: vi.fn().mockResolvedValue({ valid: false, error: 'Invalid token' })
+        });
+
+        const context = await createAuthContext('Bearer invalidtoken', invalidValidator);
+        expect(context.authenticated).toBe(false);
+        expect(context.scopes).toEqual([]);
+    });
+});
+
+describe('validateAuth', () => {
+    let mockValidator: TokenValidator;
+
+    beforeEach(() => {
+        mockValidator = createMockTokenValidator();
+    });
+
+    it('should throw TokenMissingError when no token and required', async () => {
+        await expect(validateAuth(undefined, {
+            tokenValidator: mockValidator,
+            required: true
+        })).rejects.toThrow(TokenMissingError);
+    });
+
+    it('should return unauthenticated context when no token and not required', async () => {
+        const context = await validateAuth(undefined, {
+            tokenValidator: mockValidator,
+            required: false
+        });
+        expect(context.authenticated).toBe(false);
+    });
+
+    it('should throw InvalidTokenError for invalid token', async () => {
+        const invalidValidator = createMockTokenValidator({
+            validate: vi.fn().mockResolvedValue({ valid: false, error: 'Token expired' })
+        });
+
+        await expect(validateAuth('Bearer expired', {
+            tokenValidator: invalidValidator
+        })).rejects.toThrow(InvalidTokenError);
+    });
+
+    it('should return authenticated context for valid token', async () => {
+        const context = await validateAuth('Bearer validtoken', {
+            tokenValidator: mockValidator
+        });
+        expect(context.authenticated).toBe(true);
+        expect(context.scopes).toEqual(['read', 'write']);
+    });
+
+    it('should throw InsufficientScopeError when missing required scope', async () => {
+        await expect(validateAuth('Bearer validtoken', {
+            tokenValidator: mockValidator,
+            requiredScopes: ['admin']  // User has read, write but not admin
+        })).rejects.toThrow(InsufficientScopeError);
+    });
+
+    it('should pass when user has any of required scopes', async () => {
+        const context = await validateAuth('Bearer validtoken', {
+            tokenValidator: mockValidator,
+            requiredScopes: ['read', 'admin']  // User has read
+        });
+        expect(context.authenticated).toBe(true);
+    });
+});
+
+describe('requireScope', () => {
+    it('should throw TokenMissingError when not authenticated', () => {
+        const context: AuthenticatedContext = { authenticated: false, scopes: [] };
+        expect(() => requireScope(context, 'read')).toThrow(TokenMissingError);
+    });
+
+    it('should throw InsufficientScopeError when scope missing', () => {
+        const context: AuthenticatedContext = {
+            authenticated: true,
+            scopes: ['read'],
+            claims: { sub: 'user1', scopes: ['read'], exp: 0, iat: 0 }
+        };
+        expect(() => requireScope(context, 'admin')).toThrow(InsufficientScopeError);
+    });
+
+    it('should pass when scope is present', () => {
+        const context: AuthenticatedContext = {
+            authenticated: true,
+            scopes: ['read', 'write'],
+            claims: { sub: 'user1', scopes: ['read', 'write'], exp: 0, iat: 0 }
+        };
+        expect(() => requireScope(context, 'read')).not.toThrow();
+    });
+});
+
+describe('requireAnyScope', () => {
+    it('should throw TokenMissingError when not authenticated', () => {
+        const context: AuthenticatedContext = { authenticated: false, scopes: [] };
+        expect(() => requireAnyScope(context, ['read', 'write'])).toThrow(TokenMissingError);
+    });
+
+    it('should throw InsufficientScopeError when none of scopes present', () => {
+        const context: AuthenticatedContext = {
+            authenticated: true,
+            scopes: ['read'],
+            claims: { sub: 'user1', scopes: ['read'], exp: 0, iat: 0 }
+        };
+        expect(() => requireAnyScope(context, ['admin', 'superadmin'])).toThrow(InsufficientScopeError);
+    });
+
+    it('should pass when any scope present', () => {
+        const context: AuthenticatedContext = {
+            authenticated: true,
+            scopes: ['read', 'write'],
+            claims: { sub: 'user1', scopes: ['read', 'write'], exp: 0, iat: 0 }
+        };
+        expect(() => requireAnyScope(context, ['write', 'admin'])).not.toThrow();
+    });
+});
+
+describe('requireToolScope', () => {
+    it('should throw TokenMissingError when not authenticated', () => {
+        const context: AuthenticatedContext = { authenticated: false, scopes: [] };
+        expect(() => requireToolScope(context, ['read'])).toThrow(TokenMissingError);
+    });
+
+    it('should map read scope and pass', () => {
+        const context: AuthenticatedContext = {
+            authenticated: true,
+            scopes: ['read'],  // hasScope checks for 'read' directly
+            claims: { sub: 'user1', scopes: ['read'], exp: 0, iat: 0 }
+        };
+        expect(() => requireToolScope(context, ['read'])).not.toThrow();
+    });
+
+    it('should map write scope and pass', () => {
+        const context: AuthenticatedContext = {
+            authenticated: true,
+            scopes: ['write'],
+            claims: { sub: 'user1', scopes: ['write'], exp: 0, iat: 0 }
+        };
+        expect(() => requireToolScope(context, ['write'])).not.toThrow();
+    });
+
+    it('should map admin scope and pass', () => {
+        const context: AuthenticatedContext = {
+            authenticated: true,
+            scopes: ['admin'],
+            claims: { sub: 'user1', scopes: ['admin'], exp: 0, iat: 0 }
+        };
+        expect(() => requireToolScope(context, ['admin'])).not.toThrow();
+    });
+
+    it('should throw InsufficientScopeError when mapped scope missing', () => {
+        const context: AuthenticatedContext = {
+            authenticated: true,
+            scopes: ['read'],
+            claims: { sub: 'user1', scopes: ['read'], exp: 0, iat: 0 }
+        };
+        expect(() => requireToolScope(context, ['admin'])).toThrow(InsufficientScopeError);
+    });
+
+    it('should pass when user has admin scope and read is required', () => {
+        const context: AuthenticatedContext = {
+            authenticated: true,
+            scopes: ['admin'],  // admin includes read and write scopes
+            claims: { sub: 'user1', scopes: ['admin'], exp: 0, iat: 0 }
+        };
+        expect(() => requireToolScope(context, ['read'])).not.toThrow();
+    });
+});

package/src/auth/__tests__/scopes.test.ts

@@ -0,0 +1,164 @@
+/**
+ * mysql-mcp - Scopes Unit Tests
+ * 
+ * Tests for OAuth scope utilities.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+    SCOPES,
+    parseScopes,
+    hasScope,
+    hasAnyScope,
+    hasAllScopes,
+    getScopeForToolGroup,
+    hasDatabaseScope,
+    hasTableScope,
+    getScopeDisplayName
+} from '../scopes.js';
+
+describe('parseScopes', () => {
+    it('should parse space-delimited scope string', () => {
+        expect(parseScopes('read write admin')).toEqual(['read', 'write', 'admin']);
+    });
+
+    it('should return empty array for undefined', () => {
+        expect(parseScopes(undefined)).toEqual([]);
+    });
+
+    it('should return empty array for empty string', () => {
+        expect(parseScopes('')).toEqual([]);
+    });
+
+    it('should handle single scope', () => {
+        expect(parseScopes('read')).toEqual(['read']);
+    });
+});
+
+describe('hasScope', () => {
+    it('should return true for direct match', () => {
+        expect(hasScope(['read', 'write'], 'read')).toBe(true);
+    });
+
+    it('should return false when scope not present', () => {
+        expect(hasScope(['read'], 'write')).toBe(false);
+    });
+
+    it('should grant all scopes when full is present', () => {
+        expect(hasScope(['full'], 'read')).toBe(true);
+        expect(hasScope(['full'], 'write')).toBe(true);
+        expect(hasScope(['full'], 'admin')).toBe(true);
+    });
+
+    it('should grant read and write when admin is present', () => {
+        expect(hasScope(['admin'], 'read')).toBe(true);
+        expect(hasScope(['admin'], 'write')).toBe(true);
+    });
+
+    it('should grant read when write is present', () => {
+        expect(hasScope(['write'], 'read')).toBe(true);
+    });
+
+    it('should not grant write when only read is present', () => {
+        expect(hasScope(['read'], 'write')).toBe(false);
+    });
+});
+
+describe('hasAnyScope', () => {
+    it('should return true if any scope matches', () => {
+        expect(hasAnyScope(['read'], ['read', 'write'])).toBe(true);
+    });
+
+    it('should return false if no scopes match', () => {
+        expect(hasAnyScope(['read'], ['write', 'admin'])).toBe(false);
+    });
+});
+
+describe('hasAllScopes', () => {
+    it('should return true if all scopes match', () => {
+        expect(hasAllScopes(['read', 'write', 'admin'], ['read', 'write'])).toBe(true);
+    });
+
+    it('should return false if not all scopes match', () => {
+        expect(hasAllScopes(['read'], ['read', 'write'])).toBe(false);
+    });
+});
+
+describe('getScopeForToolGroup', () => {
+    it('should return read for query tools', () => {
+        expect(getScopeForToolGroup('core')).toBe(SCOPES.READ);
+        expect(getScopeForToolGroup('json')).toBe(SCOPES.READ);
+        expect(getScopeForToolGroup('text')).toBe(SCOPES.READ);
+    });
+
+    it('should return write for transaction tools', () => {
+        expect(getScopeForToolGroup('transactions')).toBe(SCOPES.WRITE);
+    });
+
+    it('should return admin for admin tools', () => {
+        expect(getScopeForToolGroup('admin')).toBe(SCOPES.ADMIN);
+        expect(getScopeForToolGroup('backup')).toBe(SCOPES.ADMIN);
+        expect(getScopeForToolGroup('shell')).toBe(SCOPES.ADMIN);
+    });
+});
+
+describe('hasDatabaseScope', () => {
+    it('should return true for full scope', () => {
+        expect(hasDatabaseScope(['full'], 'mydb')).toBe(true);
+    });
+
+    it('should return true for admin scope', () => {
+        expect(hasDatabaseScope(['admin'], 'mydb')).toBe(true);
+    });
+
+    it('should return true for matching db: pattern', () => {
+        expect(hasDatabaseScope(['db:mydb'], 'mydb')).toBe(true);
+    });
+
+    it('should return false for non-matching db: pattern', () => {
+        expect(hasDatabaseScope(['db:otherdb'], 'mydb')).toBe(false);
+    });
+});
+
+describe('hasTableScope', () => {
+    it('should return true for full scope', () => {
+        expect(hasTableScope(['full'], 'mydb', 'users')).toBe(true);
+    });
+
+    it('should return true for admin scope', () => {
+        expect(hasTableScope(['admin'], 'mydb', 'users')).toBe(true);
+    });
+
+    it('should return true for matching database scope', () => {
+        expect(hasTableScope(['db:mydb'], 'mydb', 'users')).toBe(true);
+    });
+
+    it('should return true for matching table: pattern', () => {
+        expect(hasTableScope(['table:mydb:users'], 'mydb', 'users')).toBe(true);
+    });
+
+    it('should return false for non-matching table: pattern', () => {
+        expect(hasTableScope(['table:mydb:products'], 'mydb', 'users')).toBe(false);
+    });
+});
+
+describe('getScopeDisplayName', () => {
+    it('should return display names for standard scopes', () => {
+        expect(getScopeDisplayName('read')).toBe('Read Only');
+        expect(getScopeDisplayName('write')).toBe('Read/Write');
+        expect(getScopeDisplayName('admin')).toBe('Administrative');
+        expect(getScopeDisplayName('full')).toBe('Full Access');
+    });
+
+    it('should format db: scopes', () => {
+        expect(getScopeDisplayName('db:mydb')).toBe('Database: mydb');
+    });
+
+    it('should format table: scopes', () => {
+        expect(getScopeDisplayName('table:mydb:users')).toBe('Table: mydb:users');
+    });
+
+    it('should return unknown scopes as-is', () => {
+        expect(getScopeDisplayName('custom_scope')).toBe('custom_scope');
+    });
+});

package/src/auth/errors.ts

@@ -0,0 +1,116 @@
+/**
+ * mysql-mcp - OAuth Errors
+ * 
+ * Error classes for OAuth 2.0 authentication and authorization.
+ */
+
+/**
+ * Base OAuth error class
+ */
+export class OAuthError extends Error {
+    public readonly code: string;
+    public readonly httpStatus: number;
+
+    constructor(message: string, code: string, httpStatus = 401) {
+        super(message);
+        this.name = 'OAuthError';
+        this.code = code;
+        this.httpStatus = httpStatus;
+        Object.setPrototypeOf(this, OAuthError.prototype);
+    }
+}
+
+/**
+ * Token missing from request
+ */
+export class TokenMissingError extends OAuthError {
+    constructor(message = 'No bearer token provided') {
+        super(message, 'TOKEN_MISSING', 401);
+        this.name = 'TokenMissingError';
+        Object.setPrototypeOf(this, TokenMissingError.prototype);
+    }
+}
+
+/**
+ * Token is invalid (malformed, wrong signature, etc.)
+ */
+export class InvalidTokenError extends OAuthError {
+    constructor(message = 'Invalid access token') {
+        super(message, 'INVALID_TOKEN', 401);
+        this.name = 'InvalidTokenError';
+        Object.setPrototypeOf(this, InvalidTokenError.prototype);
+    }
+}
+
+/**
+ * Token has expired
+ */
+export class TokenExpiredError extends OAuthError {
+    constructor(message = 'Access token has expired') {
+        super(message, 'TOKEN_EXPIRED', 401);
+        this.name = 'TokenExpiredError';
+        Object.setPrototypeOf(this, TokenExpiredError.prototype);
+    }
+}
+
+/**
+ * Token signature is invalid
+ */
+export class InvalidSignatureError extends OAuthError {
+    constructor(message = 'Invalid token signature') {
+        super(message, 'INVALID_SIGNATURE', 401);
+        this.name = 'InvalidSignatureError';
+        Object.setPrototypeOf(this, InvalidSignatureError.prototype);
+    }
+}
+
+/**
+ * Token lacks required scope
+ */
+export class InsufficientScopeError extends OAuthError {
+    public readonly requiredScopes: string[];
+
+    constructor(requiredScopes: string[], message?: string) {
+        super(
+            message ?? `Insufficient scope. Required: ${requiredScopes.join(', ')}`,
+            'INSUFFICIENT_SCOPE',
+            403
+        );
+        this.name = 'InsufficientScopeError';
+        this.requiredScopes = requiredScopes;
+        Object.setPrototypeOf(this, InsufficientScopeError.prototype);
+    }
+}
+
+/**
+ * Authorization server discovery failed
+ */
+export class AuthServerDiscoveryError extends OAuthError {
+    constructor(message = 'Failed to discover authorization server metadata') {
+        super(message, 'DISCOVERY_FAILED', 500);
+        this.name = 'AuthServerDiscoveryError';
+        Object.setPrototypeOf(this, AuthServerDiscoveryError.prototype);
+    }
+}
+
+/**
+ * JWKS fetch failed
+ */
+export class JwksFetchError extends OAuthError {
+    constructor(message = 'Failed to fetch JWKS') {
+        super(message, 'JWKS_FETCH_FAILED', 500);
+        this.name = 'JwksFetchError';
+        Object.setPrototypeOf(this, JwksFetchError.prototype);
+    }
+}
+
+/**
+ * Client registration failed
+ */
+export class ClientRegistrationError extends OAuthError {
+    constructor(message = 'Client registration failed') {
+        super(message, 'REGISTRATION_FAILED', 400);
+        this.name = 'ClientRegistrationError';
+        Object.setPrototypeOf(this, ClientRegistrationError.prototype);
+    }
+}

package/src/auth/index.ts

@@ -0,0 +1,30 @@
+/**
+ * mysql-mcp - Auth Module Public Exports
+ * 
+ * OAuth 2.0 authentication and authorization components.
+ */
+
+// Types
+export type * from './types.js';
+export * from './errors.js';
+
+// Scopes
+export * from './scopes.js';
+
+// Core classes
+export { OAuthResourceServer, createOAuthResourceServer } from './OAuthResourceServer.js';
+export { AuthorizationServerDiscovery, createAuthServerDiscovery } from './AuthorizationServerDiscovery.js';
+export { TokenValidator, createTokenValidator } from './TokenValidator.js';
+
+// Middleware
+export {
+    extractBearerToken,
+    createAuthContext,
+    validateAuth,
+    requireScope,
+    requireAnyScope,
+    requireToolScope,
+    formatOAuthError,
+    type AuthenticatedContext,
+    type AuthMiddlewareConfig
+} from './middleware.js';