@casys/mcp-server 0.8.0

package/src/auth/middleware.ts

@@ -0,0 +1,170 @@
+/**
+ * Authentication middleware and utilities.
+ *
+ * Provides Bearer token extraction, 401/403 response factories,
+ * and the auth middleware for the pipeline.
+ *
+ * @module lib/server/auth/middleware
+ */
+
+import type { AuthProvider } from "./provider.js";
+import type { Middleware } from "../middleware/types.js";
+import { isOtelEnabled, recordAuthEvent } from "../observability/otel.js";
+
+/**
+ * Authentication error with structured information
+ * for generating proper HTTP error responses.
+ */
+export class AuthError extends Error {
+  constructor(
+    public readonly code:
+      | "missing_token"
+      | "invalid_token"
+      | "insufficient_scope",
+    public readonly resourceMetadataUrl: string,
+    public readonly requiredScopes?: string[],
+  ) {
+    super(
+      code === "missing_token"
+        ? "Authorization header with Bearer token required"
+        : code === "invalid_token"
+        ? "Invalid or expired token"
+        : `Insufficient scope: requires ${requiredScopes?.join(", ")}`,
+    );
+    this.name = "AuthError";
+  }
+}
+
+/**
+ * Extract Bearer token from Authorization header.
+ *
+ * @param request - HTTP Request
+ * @returns Token string or null if not present/invalid format
+ */
+export function extractBearerToken(request: Request): string | null {
+  const auth = request.headers.get("Authorization");
+  if (!auth?.startsWith("Bearer ")) return null;
+  const token = auth.slice(7).trim();
+  return token.length > 0 ? token : null;
+}
+
+/**
+ * Create a 401 Unauthorized response with WWW-Authenticate header.
+ *
+ * @param resourceMetadataUrl - URL to the Protected Resource Metadata endpoint
+ * @param error - OAuth error code
+ * @param errorDescription - Human-readable error description
+ */
+export function createUnauthorizedResponse(
+  resourceMetadataUrl: string,
+  error?: string,
+  errorDescription?: string,
+): Response {
+  const escape = (s: string) => s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+  const parts = [`Bearer resource_metadata="${escape(resourceMetadataUrl)}"`];
+  if (error) parts.push(`error="${escape(error)}"`);
+  if (errorDescription) {
+    parts.push(`error_description="${escape(errorDescription)}"`);
+  }
+
+  return new Response(
+    JSON.stringify({
+      jsonrpc: "2.0",
+      id: null,
+      error: { code: -32001, message: errorDescription ?? "Unauthorized" },
+    }),
+    {
+      status: 401,
+      headers: {
+        "Content-Type": "application/json",
+        "WWW-Authenticate": parts.join(", "),
+      },
+    },
+  );
+}
+
+/**
+ * Create a 403 Forbidden response for insufficient scopes.
+ *
+ * @param requiredScopes - Scopes that were required but missing
+ */
+export function createForbiddenResponse(requiredScopes: string[]): Response {
+  return new Response(
+    JSON.stringify({
+      jsonrpc: "2.0",
+      id: null,
+      error: {
+        code: -32001,
+        message: `Forbidden: requires scopes ${requiredScopes.join(", ")}`,
+      },
+    }),
+    {
+      status: 403,
+      headers: { "Content-Type": "application/json" },
+    },
+  );
+}
+
+/**
+ * Create an authentication middleware for the MCP pipeline.
+ *
+ * Extracts the Bearer token from the HTTP request, validates it
+ * via the AuthProvider, and injects `authInfo` into the context.
+ *
+ * For STDIO transport (no `ctx.request`), the middleware is skipped
+ * since STDIO is a local transport with no auth needed.
+ *
+ * @param provider - AuthProvider implementation
+ */
+export function createAuthMiddleware(provider: AuthProvider): Middleware {
+  return async (ctx, next) => {
+    // STDIO transport: no request, skip auth
+    if (!ctx.request) {
+      return next();
+    }
+
+    const metadata = provider.getResourceMetadata();
+    const resource = metadata.resource;
+    const base = resource.endsWith("/") ? resource.slice(0, -1) : resource;
+    const metadataUrl = `${base}/.well-known/oauth-protected-resource`;
+
+    const token = extractBearerToken(ctx.request);
+    if (!token) {
+      if (isOtelEnabled()) {
+        recordAuthEvent("reject", {
+          reason: "missing_token",
+          tool: ctx.toolName ?? "",
+        });
+      }
+      throw new AuthError("missing_token", metadataUrl);
+    }
+
+    const authInfo = await provider.verifyToken(token);
+    if (!authInfo) {
+      if (isOtelEnabled()) {
+        recordAuthEvent("reject", {
+          reason: "invalid_token",
+          tool: ctx.toolName ?? "",
+        });
+      }
+      throw new AuthError("invalid_token", metadataUrl);
+    }
+
+    if (isOtelEnabled()) {
+      recordAuthEvent("verify", {
+        subject: authInfo.subject ?? "",
+        tool: ctx.toolName ?? "",
+      });
+    }
+
+    // Deep-freeze authInfo to prevent mutation by downstream middlewares
+    if (authInfo.claims) Object.freeze(authInfo.claims);
+    if (authInfo.scopes) Object.freeze(authInfo.scopes);
+    ctx.authInfo = Object.freeze(authInfo);
+
+    // Propagate resourceMetadataUrl for downstream middlewares (scope-middleware)
+    ctx.resourceMetadataUrl = metadataUrl;
+
+    return next();
+  };
+}

package/src/auth/mod.ts

@@ -0,0 +1,44 @@
+/**
+ * Auth module for ConcurrentMCPServer.
+ *
+ * @module lib/server/auth
+ */
+
+// Types
+export type {
+  AuthInfo,
+  AuthOptions,
+  ProtectedResourceMetadata,
+} from "./types.js";
+
+// Provider base class
+export { AuthProvider } from "./provider.js";
+
+// Middleware and utilities
+export {
+  AuthError,
+  createAuthMiddleware,
+  createForbiddenResponse,
+  createUnauthorizedResponse,
+  extractBearerToken,
+} from "./middleware.js";
+
+// Scope enforcement
+export { createScopeMiddleware } from "./scope-middleware.js";
+
+// JWT Provider
+export { JwtAuthProvider } from "./jwt-provider.js";
+export type { JwtAuthProviderOptions } from "./jwt-provider.js";
+
+// OIDC Presets
+export {
+  createAuth0AuthProvider,
+  createGitHubAuthProvider,
+  createGoogleAuthProvider,
+  createOIDCAuthProvider,
+} from "./presets.js";
+export type { PresetOptions } from "./presets.js";
+
+// Config loader (YAML + env)
+export { createAuthProviderFromConfig, loadAuthConfig } from "./config.js";
+export type { AuthConfig, AuthProviderName } from "./config.js";

package/src/auth/presets.ts

@@ -0,0 +1,129 @@
+/**
+ * OIDC auth provider presets.
+ *
+ * Factory functions for common OIDC providers.
+ * Each preset pre-configures the issuer, JWKS URI, and
+ * authorization server for the provider.
+ *
+ * @module lib/server/auth/presets
+ */
+
+import {
+  JwtAuthProvider,
+  type JwtAuthProviderOptions,
+} from "./jwt-provider.js";
+
+/**
+ * Base options shared by all presets.
+ */
+export interface PresetOptions {
+  /** JWT audience (aud claim) */
+  audience: string;
+  /** Resource identifier for RFC 9728 */
+  resource: string;
+  /** Scopes supported by this server */
+  scopesSupported?: string[];
+}
+
+/**
+ * GitHub Actions OIDC provider.
+ *
+ * Validates tokens issued by GitHub Actions workflows.
+ * Issuer: https://token.actions.githubusercontent.com
+ *
+ * @example
+ * ```typescript
+ * const provider = createGitHubAuthProvider({
+ *   audience: "https://my-mcp.example.com",
+ *   resource: "https://my-mcp.example.com",
+ * });
+ * ```
+ */
+export function createGitHubAuthProvider(
+  options: PresetOptions,
+): JwtAuthProvider {
+  return new JwtAuthProvider({
+    issuer: "https://token.actions.githubusercontent.com",
+    audience: options.audience,
+    resource: options.resource,
+    authorizationServers: ["https://token.actions.githubusercontent.com"],
+    scopesSupported: options.scopesSupported,
+  });
+}
+
+/**
+ * Google OIDC provider.
+ *
+ * Validates tokens issued by Google accounts.
+ * Issuer: https://accounts.google.com
+ *
+ * @example
+ * ```typescript
+ * const provider = createGoogleAuthProvider({
+ *   audience: "https://my-mcp.example.com",
+ *   resource: "https://my-mcp.example.com",
+ * });
+ * ```
+ */
+export function createGoogleAuthProvider(
+  options: PresetOptions,
+): JwtAuthProvider {
+  return new JwtAuthProvider({
+    issuer: "https://accounts.google.com",
+    audience: options.audience,
+    resource: options.resource,
+    authorizationServers: ["https://accounts.google.com"],
+    jwksUri: "https://www.googleapis.com/oauth2/v3/certs",
+    scopesSupported: options.scopesSupported,
+  });
+}
+
+/**
+ * Auth0 OIDC provider.
+ *
+ * Validates tokens issued by an Auth0 tenant.
+ * Issuer: https://{domain}/
+ *
+ * @example
+ * ```typescript
+ * const provider = createAuth0AuthProvider({
+ *   domain: "my-tenant.auth0.com",
+ *   audience: "https://my-mcp.example.com",
+ *   resource: "https://my-mcp.example.com",
+ * });
+ * ```
+ */
+export function createAuth0AuthProvider(
+  options: PresetOptions & { domain: string },
+): JwtAuthProvider {
+  const issuer = `https://${options.domain}/`;
+  return new JwtAuthProvider({
+    issuer,
+    audience: options.audience,
+    resource: options.resource,
+    authorizationServers: [issuer],
+    jwksUri: `${issuer}.well-known/jwks.json`,
+    scopesSupported: options.scopesSupported,
+  });
+}
+
+/**
+ * Generic OIDC provider.
+ *
+ * For any OIDC-compliant provider not covered by presets.
+ *
+ * @example
+ * ```typescript
+ * const provider = createOIDCAuthProvider({
+ *   issuer: "https://my-idp.example.com",
+ *   audience: "https://my-mcp.example.com",
+ *   resource: "https://my-mcp.example.com",
+ *   authorizationServers: ["https://my-idp.example.com"],
+ * });
+ * ```
+ */
+export function createOIDCAuthProvider(
+  options: JwtAuthProviderOptions,
+): JwtAuthProvider {
+  return new JwtAuthProvider(options);
+}

package/src/auth/provider.ts

@@ -0,0 +1,47 @@
+/**
+ * AuthProvider abstract class.
+ *
+ * Abstract class (not interface) for DI compatibility with diod tokens.
+ * Implement this to provide custom token validation (API keys, opaque tokens, etc.)
+ *
+ * @module lib/server/auth/provider
+ */
+
+import type { AuthInfo, ProtectedResourceMetadata } from "./types.js";
+
+/**
+ * Base class for authentication providers.
+ *
+ * @example
+ * ```typescript
+ * class ApiKeyProvider extends AuthProvider {
+ *   async verifyToken(token: string): Promise<AuthInfo | null> {
+ *     const user = await db.findByApiKey(token);
+ *     if (!user) return null;
+ *     return { subject: user.id, scopes: user.scopes };
+ *   }
+ *
+ *   getResourceMetadata(): ProtectedResourceMetadata {
+ *     return {
+ *       resource: "https://my-mcp.example.com",
+ *       authorization_servers: ["https://auth.example.com"],
+ *       bearer_methods_supported: ["header"],
+ *     };
+ *   }
+ * }
+ * ```
+ */
+export abstract class AuthProvider {
+  /**
+   * Validate a token and extract auth information.
+   *
+   * @param token - The raw Bearer token string
+   * @returns AuthInfo if valid, null if invalid/expired
+   */
+  abstract verifyToken(token: string): Promise<AuthInfo | null>;
+
+  /**
+   * Return RFC 9728 Protected Resource Metadata for this provider.
+   */
+  abstract getResourceMetadata(): ProtectedResourceMetadata;
+}

package/src/auth/scope-middleware.ts

@@ -0,0 +1,59 @@
+/**
+ * Scope enforcement middleware.
+ *
+ * Verifies that the authenticated user has the required scopes
+ * for the tool being called. Placed after the auth middleware.
+ *
+ * @module lib/server/auth/scope-middleware
+ */
+
+import type { AuthInfo } from "./types.js";
+import { AuthError } from "./middleware.js";
+import type { Middleware } from "../middleware/types.js";
+
+/**
+ * Create a scope enforcement middleware.
+ *
+ * Checks `requiredScopes` for the called tool against `ctx.authInfo.scopes`.
+ * If auth is not configured (no authInfo), the middleware passes through.
+ * If the tool has no requiredScopes, the middleware passes through.
+ *
+ * @param toolScopes - Map of tool name to required scopes
+ */
+export function createScopeMiddleware(
+  toolScopes: Map<string, string[]>,
+): Middleware {
+  // deno-lint-ignore require-await
+  return async (ctx, next) => {
+    const requiredScopes = toolScopes.get(ctx.toolName);
+
+    // No scopes required for this tool
+    if (!requiredScopes?.length) return next();
+
+    // No auth configured: STDIO (no request) is fine, HTTP without authInfo is a misconfiguration
+    const authInfo = ctx.authInfo as AuthInfo | undefined;
+    if (!authInfo) {
+      if (!ctx.request) return next(); // STDIO: local transport, no auth needed
+      // HTTP request with required scopes but no authInfo = auth middleware is missing
+      throw new Error(
+        `[ScopeMiddleware] Tool "${ctx.toolName}" requires scopes [${
+          requiredScopes.join(", ")
+        }] ` +
+          "but no authInfo found on HTTP request. Ensure auth middleware is configured in the pipeline.",
+      );
+    }
+
+    const hasAll = requiredScopes.every((s) => authInfo.scopes.includes(s));
+    if (!hasAll) {
+      const missingScopes = requiredScopes.filter((s) =>
+        !authInfo.scopes.includes(s)
+      );
+      // resourceMetadataUrl is not critical for 403 responses (only used in 401),
+      // but we populate it from context if available for consistency
+      const metadataUrl = (ctx.resourceMetadataUrl as string | undefined) ?? "";
+      throw new AuthError("insufficient_scope", metadataUrl, missingScopes);
+    }
+
+    return next();
+  };
+}

package/src/auth/types.ts

@@ -0,0 +1,69 @@
+/**
+ * Authentication types for ConcurrentMCPServer.
+ *
+ * Types follow RFC 9728 (OAuth Protected Resource Metadata)
+ * and MCP Auth spec (draft 2025-11-25).
+ *
+ * @module lib/server/auth/types
+ */
+
+/**
+ * Information extracted from a validated token.
+ * Frozen (Object.freeze) before being passed to tool handlers.
+ */
+export interface AuthInfo {
+  /** User ID (sub claim from JWT) */
+  subject: string;
+
+  /** OAuth client ID (optional - azp or client_id claim) */
+  clientId?: string;
+
+  /** Granted scopes */
+  scopes: string[];
+
+  /** Additional JWT claims */
+  claims?: Record<string, unknown>;
+
+  /** Token expiration timestamp (Unix epoch seconds) */
+  expiresAt?: number;
+}
+
+/**
+ * Auth configuration for the server.
+ */
+export interface AuthOptions {
+  /** Authorization servers that issue valid tokens */
+  authorizationServers: string[];
+
+  /** Resource identifier for this MCP server (used in WWW-Authenticate header) */
+  resource: string;
+
+  /** Scopes supported by this server */
+  scopesSupported?: string[];
+
+  /** Custom auth provider (overrides default JWT validation) */
+  provider: AuthProvider;
+}
+
+// Forward reference - actual class is in provider.ts
+import type { AuthProvider } from "./provider.js";
+
+/**
+ * RFC 9728 Protected Resource Metadata.
+ * Returned by /.well-known/oauth-protected-resource
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc9728
+ */
+export interface ProtectedResourceMetadata {
+  /** Resource identifier (URL of this MCP server) */
+  resource: string;
+
+  /** Authorization servers that can issue valid tokens */
+  authorization_servers: string[];
+
+  /** Scopes this resource supports */
+  scopes_supported?: string[];
+
+  /** How bearer tokens can be presented (always ["header"]) */
+  bearer_methods_supported: string[];
+}

package/src/concurrency/rate-limiter.ts

@@ -0,0 +1,190 @@
+/**
+ * Rate Limiter
+ *
+ * Sliding window rate limiter for per-client request throttling.
+ * Prevents server overload by limiting requests per time window.
+ *
+ * @module lib/server/rate-limiter
+ */
+
+/**
+ * Sliding window rate limiter
+ *
+ * Features:
+ * - Per-key rate limiting (client ID, IP, etc.)
+ * - Sliding window for smooth rate enforcement
+ * - Automatic cleanup of old timestamps
+ * - Backoff waiting when limit exceeded
+ *
+ * @example
+ * ```typescript
+ * const limiter = new RateLimiter({ maxRequests: 100, windowMs: 60000 });
+ *
+ * if (await limiter.checkLimit("client-123")) {
+ *   // Execute request
+ * } else {
+ *   // Rate limited
+ * }
+ * ```
+ */
+export class RateLimiter {
+  private requestCounts = new Map<string, number[]>();
+  private readonly windowMs: number;
+  private readonly maxRequests: number;
+  private operationsSinceLastPurge = 0;
+  private static readonly PURGE_EVERY_N_OPS = 1000;
+
+  constructor(options: { maxRequests: number; windowMs: number }) {
+    this.maxRequests = options.maxRequests;
+    this.windowMs = options.windowMs;
+  }
+
+  /**
+   * Check if request is allowed for the given key
+   *
+   * @param key - Identifier (client ID, IP, etc.)
+   * @returns true if allowed, false if rate limited
+   */
+  checkLimit(key: string): boolean {
+    const now = Date.now();
+    const requests = this.requestCounts.get(key) || [];
+
+    // Remove old requests outside the sliding window
+    const validRequests = requests.filter((time) => now - time < this.windowMs);
+
+    if (validRequests.length === 0) {
+      // No active requests for this key — remove from map to prevent unbounded growth
+      this.requestCounts.delete(key);
+    }
+
+    if (validRequests.length >= this.maxRequests) {
+      // Update with cleaned list
+      this.requestCounts.set(key, validRequests);
+      return false;
+    }
+
+    // Add current request timestamp
+    validRequests.push(now);
+    this.requestCounts.set(key, validRequests);
+
+    // Periodic full purge to catch keys that haven't been checked recently
+    this.operationsSinceLastPurge++;
+    if (this.operationsSinceLastPurge >= RateLimiter.PURGE_EVERY_N_OPS) {
+      this.purgeExpiredKeys();
+    }
+
+    return true;
+  }
+
+  /**
+   * Remove all keys with no active requests in the current window.
+   * Called automatically every PURGE_EVERY_N_OPS operations.
+   */
+  purgeExpiredKeys(): number {
+    const now = Date.now();
+    let purged = 0;
+    for (const [key, requests] of this.requestCounts) {
+      const active = requests.filter((time) => now - time < this.windowMs);
+      if (active.length === 0) {
+        this.requestCounts.delete(key);
+        purged++;
+      } else {
+        this.requestCounts.set(key, active);
+      }
+    }
+    this.operationsSinceLastPurge = 0;
+    return purged;
+  }
+
+  /**
+   * Wait until request slot is available (with exponential backoff)
+   *
+   * @param key - Identifier (client ID, IP, etc.)
+   * @throws Error if max wait time exceeded (defaults to windowMs)
+   */
+  async waitForSlot(key: string): Promise<void> {
+    let retries = 0;
+    const baseDelay = 100;
+    const maxWaitMs = this.windowMs;
+    const startTime = Date.now();
+
+    while (!this.checkLimit(key)) {
+      if (Date.now() - startTime >= maxWaitMs) {
+        throw new Error(
+          `Rate limit wait timeout: waited ${maxWaitMs}ms for key "${key}"`,
+        );
+      }
+      // Exponential backoff: 100ms, 200ms, 400ms, 800ms, cap at 1000ms
+      const delay = Math.min(baseDelay * Math.pow(2, retries), 1000);
+      await new Promise((resolve) => setTimeout(resolve, delay));
+      retries++;
+    }
+  }
+
+  /**
+   * Get current request count for a key
+   */
+  getCurrentCount(key: string): number {
+    const now = Date.now();
+    const requests = this.requestCounts.get(key) || [];
+    return requests.filter((time) => now - time < this.windowMs).length;
+  }
+
+  /**
+   * Get remaining requests for a key
+   */
+  getRemainingRequests(key: string): number {
+    return Math.max(0, this.maxRequests - this.getCurrentCount(key));
+  }
+
+  /**
+   * Get time until next slot is available (in ms)
+   * Returns 0 if a slot is available now
+   */
+  getTimeUntilSlot(key: string): number {
+    const now = Date.now();
+    const requests = this.requestCounts.get(key) || [];
+    const validRequests = requests.filter((time) => now - time < this.windowMs);
+
+    if (validRequests.length < this.maxRequests) {
+      return 0;
+    }
+
+    // Find oldest request in window - when it expires, a slot opens
+    const oldest = Math.min(...validRequests);
+    return Math.max(0, oldest + this.windowMs - now);
+  }
+
+  /**
+   * Clear rate limit history for a key
+   */
+  clear(key: string): void {
+    this.requestCounts.delete(key);
+  }
+
+  /**
+   * Clear all rate limit history
+   */
+  clearAll(): void {
+    this.requestCounts.clear();
+  }
+
+  /**
+   * Get metrics for monitoring
+   */
+  getMetrics(): { keys: number; totalRequests: number } {
+    let totalRequests = 0;
+    const now = Date.now();
+
+    for (const requests of this.requestCounts.values()) {
+      totalRequests += requests.filter((time) =>
+        now - time < this.windowMs
+      ).length;
+    }
+
+    return {
+      keys: this.requestCounts.size,
+      totalRequests,
+    };
+  }
+}