/**
* 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;
}
}
