memory-journal-mcp 6.1.2 → 6.2.1

package/src/auth/scopes.ts

@@ -1,256 +0,0 @@
-/**
- * memory-journal-mcp — OAuth Scopes
- *
- * Scope definitions and enforcement utilities for
- * granular access control.
- *
- * Scope Hierarchy:  full ⊃ admin ⊃ write ⊃ read
- *
- * Note: memory-journal-mcp uses only base scopes (no wildcard patterns).
- */
-
-import type { ToolGroup } from '../types/index.js'
-import { TOOL_GROUPS } from '../filtering/tool-filter.js'
-
-// =============================================================================
-// Scope Constants
-// =============================================================================
-
-/**
- * Standard OAuth scopes for memory-journal-mcp
- */
-export const SCOPES = {
-    /** Read-only access */
-    READ: 'read',
-    /** Read and write access */
-    WRITE: 'write',
-    /** Administrative access */
-    ADMIN: 'admin',
-    /** Unrestricted access to all operations */
-    FULL: 'full',
-} as const
-
-export type StandardScope = (typeof SCOPES)[keyof typeof SCOPES]
-
-/**
- * Base scopes supported by the server
- */
-export const BASE_SCOPES = ['read', 'write', 'admin', 'full'] as const
-
-/**
- * All supported scope patterns for metadata
- */
-export const SUPPORTED_SCOPES = ['read', 'write', 'admin', 'full'] as const
-
-// =============================================================================
-// Scope to Tool Group Mapping
-// =============================================================================
-
-/**
- * Declarative mapping from tool group to required minimum scope.
- * Single source of truth — all other scope-group arrays derive from this.
- */
-export const TOOL_GROUP_SCOPES: Record<ToolGroup, StandardScope> = {
-    core: SCOPES.READ,
-    search: SCOPES.READ,
-    analytics: SCOPES.READ,
-    relationships: SCOPES.READ,
-    export: SCOPES.READ,
-    admin: SCOPES.ADMIN,
-    github: SCOPES.WRITE,
-    backup: SCOPES.ADMIN,
-    team: SCOPES.WRITE,
-    codemode: SCOPES.ADMIN,
-}
-
-/**
- * Get the required scope for a tool group.
- */
-export function getScopeForToolGroup(group: ToolGroup): StandardScope {
-    return TOOL_GROUP_SCOPES[group] ?? SCOPES.READ
-}
-
-// Derived arrays for backward compatibility
-const groupsForScope = (maxScope: StandardScope): ToolGroup[] => {
-    const hierarchy: Record<StandardScope, number> = {
-        read: 0,
-        write: 1,
-        admin: 2,
-        full: 3,
-    }
-    const maxLevel = hierarchy[maxScope]
-    return (Object.entries(TOOL_GROUP_SCOPES) as [ToolGroup, StandardScope][])
-        .filter(([, scope]) => hierarchy[scope] <= maxLevel)
-        .map(([group]) => group)
-}
-
-/**
- * Tool groups accessible with read scope (read-only operations)
- */
-export const READ_SCOPE_GROUPS: ToolGroup[] = groupsForScope(SCOPES.READ)
-
-/**
- * Tool groups accessible with write scope (read + write operations)
- */
-export const WRITE_SCOPE_GROUPS: ToolGroup[] = groupsForScope(SCOPES.WRITE)
-
-/**
- * Tool groups accessible with admin scope (all operations)
- */
-export const ADMIN_SCOPE_GROUPS: ToolGroup[] = groupsForScope(SCOPES.ADMIN)
-
-// =============================================================================
-// Scope Parsing
-// =============================================================================
-
-/**
- * Parse a scope string (space-delimited) into an array
- */
-export function parseScopes(scopeString: string): string[] {
-    return scopeString
-        .split(/\s+/)
-        .map((s) => s.trim())
-        .filter((s) => s.length > 0)
-}
-
-// =============================================================================
-// Scope Validation
-// =============================================================================
-
-/**
- * Check if a scope is valid (matches known scopes)
- */
-export function isValidScope(scope: string): boolean {
-    return (BASE_SCOPES as readonly string[]).includes(scope)
-}
-
-/**
- * Check if granted scopes include the required scope.
- * Respects the scope hierarchy: full ⊃ admin ⊃ write ⊃ read
- */
-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))
-}
-
-/**
- * Check if scopes include admin access
- */
-export function hasAdminScope(scopes: string[]): boolean {
-    return scopes.includes('admin') || scopes.includes('full')
-}
-
-/**
- * Check if scopes include write access
- */
-export function hasWriteScope(scopes: string[]): boolean {
-    return scopes.includes('write') || hasAdminScope(scopes)
-}
-
-/**
- * Check if scopes include read access
- */
-export function hasReadScope(scopes: string[]): boolean {
-    return scopes.includes('read') || hasWriteScope(scopes)
-}
-
-// =============================================================================
-// Tool Group Utilities
-// =============================================================================
-
-/**
- * Get the required minimum scope for a tool group
- */
-export function getRequiredScopeForGroup(group: ToolGroup): string {
-    return TOOL_GROUP_SCOPES[group] ?? SCOPES.READ
-}
-
-/**
- * Get tool groups accessible with given scopes
- */
-export function getAccessibleToolGroups(scopes: string[]): ToolGroup[] {
-    if (scopes.includes(SCOPES.FULL) || hasAdminScope(scopes)) {
-        return [...ADMIN_SCOPE_GROUPS]
-    }
-    if (hasWriteScope(scopes)) {
-        return [...WRITE_SCOPE_GROUPS]
-    }
-    if (hasReadScope(scopes)) {
-        return [...READ_SCOPE_GROUPS]
-    }
-    return []
-}
-
-/**
- * Get all tools accessible with given scopes
- */
-export function getAccessibleTools(scopes: string[]): string[] {
-    const groups = getAccessibleToolGroups(scopes)
-    const allTools: string[] = []
-
-    for (const group of groups) {
-        const groupTools = TOOL_GROUPS[group] ?? []
-        allTools.push(...groupTools)
-    }
-
-    return [...new Set(allTools)]
-}
-
-// =============================================================================
-// Display Utilities
-// =============================================================================
-
-/**
- * Get human-readable display name for a scope
- */
-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:
-            return scope
-    }
-}

package/src/auth/token-validator.ts

@@ -1,293 +0,0 @@
-/**
- * memory-journal-mcp — Token Validator
- *
- * JWT access token validation using JWKS for signature verification.
- * Supports RSA and EC algorithms commonly used with OAuth 2.0.
- */
-
-import * as jose from 'jose'
-import type { TokenValidationResult, TokenClaims, TokenValidatorConfig } from './types.js'
-import {
-    InvalidTokenError,
-    TokenExpiredError,
-    InvalidSignatureError,
-    JwksFetchError,
-    AUTH_ERROR_CODES,
-} from './errors.js'
-import { parseScopes } from './scopes.js'
-import { logger } from '../utils/logger.js'
-
-// =============================================================================
-// Token Validator
-// =============================================================================
-
-/**
- * JWT Token Validator
- *
- * Validates OAuth 2.0 access tokens using JWKS for signature verification.
- */
-export class TokenValidator {
-    /** Resolved configuration with all defaults applied */
-    private readonly jwksUri: string
-    private readonly issuer: string
-    private readonly audience: string
-    private readonly clockTolerance: number
-    private readonly jwksCacheTtl: number
-
-    private jwks: jose.JWTVerifyGetKey | null = null
-    private jwksExpiry = 0
-
-    constructor(config: TokenValidatorConfig) {
-        this.jwksUri = config.jwksUri
-        this.issuer = config.issuer
-        this.audience = config.audience
-        this.clockTolerance = config.clockTolerance ?? 60
-        this.jwksCacheTtl = config.jwksCacheTtl ?? 3600
-
-        const issuerHost = (() => {
-            try {
-                return new URL(this.issuer).hostname
-            } catch {
-                return '[configured]'
-            }
-        })()
-        logger.info(`Token Validator initialized for issuer: ${issuerHost}`, {
-            module: 'AUTH',
-            operation: 'init',
-        })
-    }
-
-    /**
-     * Validate an access token
-     *
-     * @param token - The JWT access token
-     * @returns Validation result with claims or error
-     */
-    async validate(token: string): Promise<TokenValidationResult> {
-        try {
-            // Get or refresh JWKS
-            const jwks = this.getJwks()
-
-            // Verify the token
-            const { payload } = await jose.jwtVerify(token, jwks, {
-                issuer: this.issuer,
-                audience: this.audience,
-                clockTolerance: this.clockTolerance,
-            })
-
-            // Extract and normalize claims
-            const claims = this.extractClaims(payload)
-
-            logger.info(`Token validated for subject: ${claims.sub}`, {
-                module: 'AUTH',
-                operation: 'validate',
-                entityId: claims.sub,
-            })
-
-            return {
-                valid: true,
-                claims,
-            }
-        } catch (error) {
-            return this.handleValidationError(error)
-        }
-    }
-
-    /**
-     * Get or refresh the JWKS
-     */
-    private getJwks(): jose.JWTVerifyGetKey {
-        // Check if JWKS is cached and valid
-        if (this.jwks && Date.now() < this.jwksExpiry) {
-            return this.jwks
-        }
-
-        const jwksHost = (() => {
-            try {
-                return new URL(this.jwksUri).hostname
-            } catch {
-                return '[configured]'
-            }
-        })()
-        logger.info(`Fetching JWKS from: ${jwksHost}`, {
-            module: 'AUTH',
-            operation: 'jwks-fetch',
-        })
-
-        try {
-            // Create JWKS remote key set
-            this.jwks = jose.createRemoteJWKSet(new URL(this.jwksUri), {
-                cooldownDuration: 30000, // 30 seconds between retries
-                cacheMaxAge: this.jwksCacheTtl * 1000,
-            })
-
-            this.jwksExpiry = Date.now() + this.jwksCacheTtl * 1000
-
-            logger.info(`JWKS cached for ${String(this.jwksCacheTtl)}s`, {
-                module: 'AUTH',
-                operation: 'jwks-cache',
-            })
-
-            return this.jwks
-        } catch (error) {
-            const cause = error instanceof Error ? error : new Error(String(error))
-
-            logger.error('Failed to fetch JWKS', {
-                module: 'AUTH',
-                operation: 'jwks-fetch',
-                error: cause.message,
-            })
-
-            throw new JwksFetchError(this.jwksUri, cause)
-        }
-    }
-
-    /**
-     * Extract and normalize token claims
-     */
-    private extractClaims(payload: jose.JWTPayload): TokenClaims {
-        // Get scopes from 'scope' claim (space-delimited) or 'scopes' claim (array)
-        let scopes: string[] = []
-
-        if (typeof payload['scope'] === 'string') {
-            scopes = parseScopes(payload['scope'])
-        } else if (Array.isArray(payload['scopes'])) {
-            scopes = payload['scopes'].filter((s): s is string => typeof s === 'string')
-        } else if (Array.isArray(payload['scope'])) {
-            scopes = payload['scope'].filter((s): s is string => typeof s === 'string')
-        }
-
-        return {
-            sub: payload.sub ?? 'unknown',
-            scopes,
-            exp: payload.exp ?? 0,
-            iat: payload.iat ?? 0,
-            iss: payload.iss,
-            aud: payload.aud,
-            nbf: payload.nbf ?? undefined,
-            jti: payload.jti,
-            client_id: payload['client_id'] as string | undefined,
-            // Include all other claims
-            ...payload,
-        }
-    }
-
-    /**
-     * Handle validation errors and convert to TokenValidationResult
-     */
-    private handleValidationError(error: unknown): TokenValidationResult {
-        // Handle jose-specific errors
-        if (error instanceof jose.errors.JWTExpired) {
-            logger.warning('Token has expired', {
-                module: 'AUTH',
-                operation: 'validate',
-            })
-
-            return {
-                valid: false,
-                error: 'Token has expired',
-                errorCode: AUTH_ERROR_CODES.TOKEN_EXPIRED,
-            }
-        }
-
-        if (error instanceof jose.errors.JWTClaimValidationFailed) {
-            logger.warning(`Token claim validation failed: ${error.message}`, {
-                module: 'AUTH',
-                operation: 'validate',
-            })
-
-            return {
-                valid: false,
-                error: `Token claim validation failed: ${error.message}`,
-                errorCode: AUTH_ERROR_CODES.TOKEN_INVALID,
-            }
-        }
-
-        if (error instanceof jose.errors.JWSSignatureVerificationFailed) {
-            logger.warning('Token signature verification failed', {
-                module: 'AUTH',
-                operation: 'validate',
-            })
-
-            return {
-                valid: false,
-                error: 'Token signature verification failed',
-                errorCode: AUTH_ERROR_CODES.SIGNATURE_INVALID,
-            }
-        }
-
-        if (error instanceof jose.errors.JWKSNoMatchingKey) {
-            logger.warning('No matching key found in JWKS', {
-                module: 'AUTH',
-                operation: 'validate',
-            })
-
-            return {
-                valid: false,
-                error: 'No matching key found in JWKS',
-                errorCode: AUTH_ERROR_CODES.TOKEN_INVALID,
-            }
-        }
-
-        // Handle other errors
-        const message = error instanceof Error ? error.message : String(error)
-
-        logger.error(`Token validation failed: ${message}`, {
-            module: 'AUTH',
-            operation: 'validate',
-        })
-
-        return {
-            valid: false,
-            error: `Token validation failed: ${message}`,
-            errorCode: AUTH_ERROR_CODES.TOKEN_INVALID,
-        }
-    }
-
-    /**
-     * Refresh the JWKS cache
-     */
-    refreshJwks(): void {
-        this.jwks = null
-        this.jwksExpiry = 0
-        this.getJwks()
-        logger.info('JWKS cache refreshed', { module: 'AUTH', operation: 'jwks-refresh' })
-    }
-
-    /**
-     * Clear the JWKS cache
-     */
-    clearCache(): void {
-        this.jwks = null
-        this.jwksExpiry = 0
-        logger.info('Token validator cache cleared', { module: 'AUTH', operation: 'cache-clear' })
-    }
-
-    /**
-     * Convert a validation error to the appropriate OAuth error class
-     */
-    static toOAuthError(
-        result: TokenValidationResult
-    ): InvalidTokenError | TokenExpiredError | InvalidSignatureError {
-        if (result.errorCode === AUTH_ERROR_CODES.TOKEN_EXPIRED) {
-            return new TokenExpiredError()
-        }
-
-        if (result.errorCode === AUTH_ERROR_CODES.SIGNATURE_INVALID) {
-            return new InvalidSignatureError()
-        }
-
-        return new InvalidTokenError(result.error)
-    }
-}
-
-// =============================================================================
-// Factory Function
-// =============================================================================
-
-/**
- * Create a Token Validator instance
- */
-export function createTokenValidator(config: TokenValidatorConfig): TokenValidator {
-    return new TokenValidator(config)
-}

package/src/auth/transport-agnostic.ts

@@ -1,164 +0,0 @@
-/**
- * memory-journal-mcp — Transport-Agnostic Auth
- *
- * Authentication utilities that work across any transport layer
- * (Express, Streamable HTTP, or future transports).
- * Split from middleware.ts to keep files under ~500 lines.
- */
-
-import type { TokenClaims } from './types.js'
-import type { TokenValidator } from './token-validator.js'
-import { TokenMissingError, InvalidTokenError, InsufficientScopeError } from './errors.js'
-import { hasScope as checkScope } from './scopes.js'
-
-/**
- * Extract a Bearer token from an Authorization header.
- * Local copy to avoid circular dependency with middleware.ts.
- */
-function extractBearerToken(authHeader: string | undefined): string | null {
-    if (!authHeader) return null
-    const parts = authHeader.split(' ')
-    const scheme = parts[0]
-    const tokenPart = parts[1]
-    if (parts.length !== 2 || scheme?.toLowerCase() !== 'bearer') return null
-    if (tokenPart === undefined) return null
-    const token = tokenPart.trim()
-    return token.length > 0 ? token : null
-}
-
-// =============================================================================
-// Transport-Agnostic Auth Context
-// =============================================================================
-
-/**
- * Transport-agnostic authenticated request context.
- * Usable by Express middleware, Streamable HTTP, or any future transport.
- */
-export interface AuthenticatedContext {
-    /** Whether request is authenticated */
-    authenticated: boolean
-
-    /** Token claims (if authenticated) */
-    claims?: TokenClaims
-
-    /** Token scopes (convenience) */
-    scopes: string[]
-}
-
-/**
- * Create authentication context from an Authorization header.
- * Does not throw — returns unauthenticated context when token is missing/invalid.
- */
-export async function createAuthenticatedContext(
-    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.
- * Throws OAuth errors when token missing, invalid, or insufficient scope.
- */
-export async function validateAuth(
-    authHeader: string | undefined,
-    tokenValidator: TokenValidator,
-    options: { required?: boolean; requiredScopes?: string[] } = {}
-): Promise<AuthenticatedContext> {
-    const { required = true, requiredScopes } = options
-    const token = extractBearerToken(authHeader)
-
-    if (!token) {
-        if (required) {
-            throw new TokenMissingError()
-        }
-        return { authenticated: false, scopes: [] }
-    }
-
-    const result = await 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,
-    }
-
-    if (requiredScopes && requiredScopes.length > 0) {
-        const hasRequired = requiredScopes.some((scope) => checkScope(context.scopes, scope))
-        if (!hasRequired) {
-            throw new InsufficientScopeError(requiredScopes, context.scopes)
-        }
-    }
-
-    return context
-}
-
-/**
- * Format an OAuth error for HTTP response.
- * Transport-agnostic — returns status and body without Express dependency.
- */
-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) {
-        const required = error.details?.['requiredScope'] as string[] | undefined
-        return {
-            status: 403,
-            body: {
-                error: 'insufficient_scope',
-                error_description: error.message,
-                scope: required ? required.join(' ') : undefined,
-            },
-        }
-    }
-
-    // Generic error
-    return {
-        status: 500,
-        body: {
-            error: 'server_error',
-            error_description: 'Internal server error',
-        },
-    }
-}