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