/**
* postgres-mcp - OAuth Scopes
*
* Scope definitions and utilities for PostgreSQL MCP OAuth 2.0.
*/
import type { ToolGroup } from "../types/index.js";
// =============================================================================
// Scope Definitions
// =============================================================================
/**
* Standard OAuth scopes for postgres-mcp
*/
export const SCOPES = {
/** Read-only access to all databases */
READ: "read",
/** Read and write access to all databases */
WRITE: "write",
/** Administrative access (VACUUM, 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}, schema:{name}, table:{schema}:{table}
] as const;
// =============================================================================
// Tool Group to Scope Mapping
// =============================================================================
/**
* Map PostgreSQL tool groups to required minimum scopes
*/
export const TOOL_GROUP_SCOPES: Record<ToolGroup, StandardScope> = {
// Core database operations
core: SCOPES.READ,
transactions: SCOPES.WRITE,
jsonb: SCOPES.READ,
text: SCOPES.READ,
stats: SCOPES.READ,
// Performance and monitoring
performance: SCOPES.READ,
monitoring: SCOPES.READ,
// Administrative operations
admin: SCOPES.ADMIN,
backup: SCOPES.ADMIN,
schema: SCOPES.READ,
partitioning: SCOPES.ADMIN,
// Extensions
vector: SCOPES.READ,
postgis: SCOPES.READ,
cron: SCOPES.ADMIN,
partman: SCOPES.ADMIN,
kcache: SCOPES.READ,
citext: SCOPES.READ,
ltree: SCOPES.READ,
pgcrypto: SCOPES.READ,
// Code Mode (requires admin - can execute arbitrary operations)
codemode: SCOPES.ADMIN,
};
// =============================================================================
// 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 schema-specific scope matches
*/
export function hasSchemaScope(
grantedScopes: string[],
schema: string,
): boolean {
// Full or admin grants all schemas
if (
grantedScopes.includes(SCOPES.FULL) ||
grantedScopes.includes(SCOPES.ADMIN)
) {
return true;
}
// Check for schema:{name} pattern
const schemaScope = `schema:${schema}`;
return grantedScopes.includes(schemaScope);
}
/**
* Check if table-specific scope matches
*/
export function hasTableScope(
grantedScopes: string[],
schema: string,
table: string,
): boolean {
// Full or admin grants all tables
if (
grantedScopes.includes(SCOPES.FULL) ||
grantedScopes.includes(SCOPES.ADMIN)
) {
return true;
}
// Check for schema:{name} scope (grants access to all tables in schema)
if (hasSchemaScope(grantedScopes, schema)) {
return true;
}
// Check for table:{schema}:{table} pattern
const tableScope = `table:${schema}:${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("schema:")) {
return `Schema: ${scope.slice(7)}`;
}
if (scope.startsWith("table:")) {
return `Table: ${scope.slice(6)}`;
}
return scope;
}
}
