@casys/mcp-server 0.2.1

package/src/auth/config.ts

@@ -0,0 +1,229 @@
+/**
+ * Auth configuration loader.
+ *
+ * Loads auth config from YAML file with env var overrides.
+ * Priority: env vars > YAML > (nothing = no auth)
+ *
+ * @module lib/server/auth/config
+ */
+
+import { parse as parseYaml } from "yaml";
+import { env, readTextFile } from "../runtime/runtime.js";
+import type { AuthProvider } from "./provider.js";
+import {
+  createAuth0AuthProvider,
+  createGitHubAuthProvider,
+  createGoogleAuthProvider,
+  createOIDCAuthProvider,
+} from "./presets.js";
+
+/** Supported auth provider names */
+export type AuthProviderName = "github" | "google" | "auth0" | "oidc";
+
+const VALID_PROVIDERS: AuthProviderName[] = [
+  "github",
+  "google",
+  "auth0",
+  "oidc",
+];
+
+/**
+ * Parsed auth configuration (after YAML + env merge).
+ */
+export interface AuthConfig {
+  provider: AuthProviderName;
+  audience: string;
+  resource: string;
+  /** Auth0 tenant domain */
+  domain?: string;
+  /** OIDC issuer */
+  issuer?: string;
+  /** OIDC JWKS URI (optional, derived from issuer if absent) */
+  jwksUri?: string;
+  /** Supported scopes */
+  scopesSupported?: string[];
+}
+
+/**
+ * YAML file schema (top-level has `auth` key).
+ */
+interface ConfigFile {
+  auth?: {
+    provider?: string;
+    audience?: string;
+    resource?: string;
+    domain?: string;
+    issuer?: string;
+    jwksUri?: string;
+    scopesSupported?: string[];
+  };
+}
+
+/**
+ * Load auth configuration from YAML file + env var overrides.
+ *
+ * 1. Reads YAML file (if it exists)
+ * 2. Overlays env vars (MCP_AUTH_* take precedence)
+ * 3. Validates the merged config
+ * 4. Returns null if no auth is configured
+ *
+ * Env var mapping:
+ * - MCP_AUTH_PROVIDER → auth.provider
+ * - MCP_AUTH_AUDIENCE → auth.audience
+ * - MCP_AUTH_RESOURCE → auth.resource
+ * - MCP_AUTH_DOMAIN → auth.domain
+ * - MCP_AUTH_ISSUER → auth.issuer
+ * - MCP_AUTH_JWKS_URI → auth.jwksUri
+ * - MCP_AUTH_SCOPES → auth.scopesSupported (space-separated)
+ *
+ * @param configPath - Path to YAML config file. Defaults to "mcp-server.yaml" in cwd.
+ * @returns AuthConfig or null if no auth configured
+ * @throws Error if config is invalid (fail-fast)
+ */
+export async function loadAuthConfig(
+  configPath?: string,
+): Promise<AuthConfig | null> {
+  // 1. Load YAML (optional - file may not exist)
+  const yamlAuth = await loadYamlAuth(configPath ?? "mcp-server.yaml");
+
+  // 2. Read env vars
+  const envProvider = env("MCP_AUTH_PROVIDER");
+  const envAudience = env("MCP_AUTH_AUDIENCE");
+  const envResource = env("MCP_AUTH_RESOURCE");
+  const envDomain = env("MCP_AUTH_DOMAIN");
+  const envIssuer = env("MCP_AUTH_ISSUER");
+  const envJwksUri = env("MCP_AUTH_JWKS_URI");
+  const envScopes = env("MCP_AUTH_SCOPES");
+
+  // 3. Merge: env overrides YAML
+  const provider = envProvider ?? yamlAuth?.provider;
+
+  // No provider configured anywhere → no auth
+  if (!provider) return null;
+
+  // Validate provider name
+  if (!VALID_PROVIDERS.includes(provider as AuthProviderName)) {
+    throw new Error(
+      `[AuthConfig] Unknown auth provider: "${provider}". ` +
+        `Valid values: ${VALID_PROVIDERS.join(", ")}`,
+    );
+  }
+
+  const audience = envAudience ?? yamlAuth?.audience;
+  const resource = envResource ?? yamlAuth?.resource;
+
+  if (!audience) {
+    throw new Error(
+      `[AuthConfig] "audience" is required when provider="${provider}". ` +
+        "Set auth.audience in YAML or MCP_AUTH_AUDIENCE env var.",
+    );
+  }
+  if (!resource) {
+    throw new Error(
+      `[AuthConfig] "resource" is required when provider="${provider}". ` +
+        "Set auth.resource in YAML or MCP_AUTH_RESOURCE env var.",
+    );
+  }
+
+  const config: AuthConfig = {
+    provider: provider as AuthProviderName,
+    audience,
+    resource,
+    domain: envDomain ?? yamlAuth?.domain,
+    issuer: envIssuer ?? yamlAuth?.issuer,
+    jwksUri: envJwksUri ?? yamlAuth?.jwksUri,
+    scopesSupported: envScopes
+      ? envScopes.split(" ").filter(Boolean)
+      : yamlAuth?.scopesSupported,
+  };
+
+  // Provider-specific validation (fail-fast)
+  if (config.provider === "auth0" && !config.domain) {
+    throw new Error(
+      '[AuthConfig] "domain" is required for auth0 provider. ' +
+        "Set auth.domain in YAML or MCP_AUTH_DOMAIN env var.",
+    );
+  }
+  if (config.provider === "oidc" && !config.issuer) {
+    throw new Error(
+      '[AuthConfig] "issuer" is required for oidc provider. ' +
+        "Set auth.issuer in YAML or MCP_AUTH_ISSUER env var.",
+    );
+  }
+
+  return config;
+}
+
+/**
+ * Create an AuthProvider from a loaded AuthConfig.
+ *
+ * @param config - Validated auth config
+ * @returns AuthProvider instance
+ */
+export function createAuthProviderFromConfig(config: AuthConfig): AuthProvider {
+  const base = {
+    audience: config.audience,
+    resource: config.resource,
+    scopesSupported: config.scopesSupported,
+  };
+
+  switch (config.provider) {
+    case "github":
+      return createGitHubAuthProvider(base);
+    case "google":
+      return createGoogleAuthProvider(base);
+    case "auth0":
+      return createAuth0AuthProvider({ ...base, domain: config.domain! });
+    case "oidc":
+      return createOIDCAuthProvider({
+        ...base,
+        issuer: config.issuer!,
+        jwksUri: config.jwksUri,
+        authorizationServers: [config.issuer!],
+      });
+    default:
+      throw new Error(`[AuthConfig] Unsupported provider: ${config.provider}`);
+  }
+}
+
+/**
+ * Load the auth section from a YAML config file.
+ * Returns null if file doesn't exist (not an error).
+ */
+async function loadYamlAuth(
+  path: string,
+): Promise<ConfigFile["auth"] | null> {
+  // readTextFile returns null if file doesn't exist
+  const text = await readTextFile(path);
+  if (text === null) return null;
+
+  const parsed = parseYaml(text);
+
+  // Validate parsed YAML is an object (not string, array, null, etc.)
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return null;
+  }
+
+  const configFile = parsed as Record<string, unknown>;
+  if (
+    !configFile.auth || typeof configFile.auth !== "object" ||
+    Array.isArray(configFile.auth)
+  ) {
+    return null;
+  }
+
+  const auth = configFile.auth as Record<string, unknown>;
+  return {
+    provider: typeof auth.provider === "string" ? auth.provider : undefined,
+    audience: typeof auth.audience === "string" ? auth.audience : undefined,
+    resource: typeof auth.resource === "string" ? auth.resource : undefined,
+    domain: typeof auth.domain === "string" ? auth.domain : undefined,
+    issuer: typeof auth.issuer === "string" ? auth.issuer : undefined,
+    jwksUri: typeof auth.jwksUri === "string" ? auth.jwksUri : undefined,
+    scopesSupported: Array.isArray(auth.scopesSupported)
+      ? auth.scopesSupported.filter((s: unknown): s is string =>
+        typeof s === "string"
+      )
+      : undefined,
+  };
+}

package/src/auth/jwt-provider.ts

@@ -0,0 +1,175 @@
+/**
+ * JWT Auth Provider using JWKS for token validation.
+ *
+ * Validates JWT tokens against a remote JWKS endpoint,
+ * checking issuer, audience, and expiration.
+ *
+ * @module lib/server/auth/jwt-provider
+ */
+
+import { createRemoteJWKSet, jwtVerify } from "jose";
+import { AuthProvider } from "./provider.js";
+import type { AuthInfo, ProtectedResourceMetadata } from "./types.js";
+import { isOtelEnabled, recordAuthEvent } from "../observability/otel.js";
+
+/**
+ * Configuration for JwtAuthProvider.
+ */
+export interface JwtAuthProviderOptions {
+  /** JWT issuer (iss claim) */
+  issuer: string;
+  /** JWT audience (aud claim) */
+  audience: string;
+  /** JWKS URI for signature validation. Defaults to {issuer}/.well-known/jwks.json */
+  jwksUri?: string;
+  /** Resource identifier for RFC 9728 */
+  resource: string;
+  /** Authorization servers that issue valid tokens */
+  authorizationServers: string[];
+  /** Scopes supported by this server */
+  scopesSupported?: string[];
+}
+
+/**
+ * JWT Auth Provider with JWKS validation.
+ *
+ * @example
+ * ```typescript
+ * const provider = new JwtAuthProvider({
+ *   issuer: "https://accounts.google.com",
+ *   audience: "https://my-mcp.example.com",
+ *   resource: "https://my-mcp.example.com",
+ *   authorizationServers: ["https://accounts.google.com"],
+ * });
+ * ```
+ */
+/**
+ * Cached auth result with expiration
+ */
+interface CachedAuth {
+  authInfo: AuthInfo;
+  expiresAt: number; // ms timestamp
+}
+
+export class JwtAuthProvider extends AuthProvider {
+  private jwks: ReturnType<typeof createRemoteJWKSet>;
+  private options: JwtAuthProviderOptions;
+
+  // Token verification cache: hash(token) → AuthInfo with TTL
+  // Prevents redundant JWKS fetches (network round-trip per tool call)
+  private tokenCache = new Map<string, CachedAuth>();
+  private static readonly MAX_CACHE_SIZE = 1000;
+  private static readonly DEFAULT_CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+
+  constructor(options: JwtAuthProviderOptions) {
+    super();
+
+    if (!options.issuer) {
+      throw new Error("[JwtAuthProvider] issuer is required");
+    }
+    if (!options.audience) {
+      throw new Error("[JwtAuthProvider] audience is required");
+    }
+    if (!options.resource) {
+      throw new Error("[JwtAuthProvider] resource is required");
+    }
+    if (!options.authorizationServers?.length) {
+      throw new Error(
+        "[JwtAuthProvider] at least one authorizationServer is required",
+      );
+    }
+
+    this.options = options;
+    const jwksUri = options.jwksUri ??
+      `${options.issuer}/.well-known/jwks.json`;
+    this.jwks = createRemoteJWKSet(new URL(jwksUri));
+  }
+
+  async verifyToken(token: string): Promise<AuthInfo | null> {
+    // Check cache first (avoids JWKS network round-trip)
+    const cacheKey = await this.hashToken(token);
+    const cached = this.tokenCache.get(cacheKey);
+    if (cached && Date.now() < cached.expiresAt) {
+      if (isOtelEnabled()) {
+        recordAuthEvent("cache_hit", {
+          subject: cached.authInfo.subject ?? "",
+        });
+      }
+      return cached.authInfo;
+    }
+    // Evict expired entry if present
+    if (cached) this.tokenCache.delete(cacheKey);
+
+    try {
+      const { payload } = await jwtVerify(token, this.jwks, {
+        issuer: this.options.issuer,
+        audience: this.options.audience,
+      });
+
+      const authInfo: AuthInfo = {
+        subject: payload.sub ?? "unknown",
+        clientId: (payload.azp as string | undefined) ??
+          (payload.client_id as string | undefined),
+        scopes: this.extractScopes(payload),
+        claims: payload as Record<string, unknown>,
+        expiresAt: payload.exp,
+      };
+
+      // Cache with TTL = min(token remaining lifetime, 5 minutes)
+      const tokenExpiresMs = payload.exp ? payload.exp * 1000 : Infinity;
+      const cacheTtl = Math.min(
+        tokenExpiresMs - Date.now(),
+        JwtAuthProvider.DEFAULT_CACHE_TTL_MS,
+      );
+      if (cacheTtl > 0) {
+        // Evict oldest entries if cache is full
+        if (this.tokenCache.size >= JwtAuthProvider.MAX_CACHE_SIZE) {
+          const oldestKey = this.tokenCache.keys().next().value;
+          if (oldestKey) this.tokenCache.delete(oldestKey);
+        }
+        this.tokenCache.set(cacheKey, {
+          authInfo: Object.freeze(authInfo) as AuthInfo,
+          expiresAt: Date.now() + cacheTtl,
+        });
+      }
+
+      return authInfo;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Hash a token for cache key (avoids storing raw tokens in memory)
+   */
+  private async hashToken(token: string): Promise<string> {
+    const data = new TextEncoder().encode(token);
+    const hash = await crypto.subtle.digest("SHA-256", data);
+    return Array.from(new Uint8Array(hash)).map((b) =>
+      b.toString(16).padStart(2, "0")
+    ).join("");
+  }
+
+  getResourceMetadata(): ProtectedResourceMetadata {
+    return {
+      resource: this.options.resource,
+      authorization_servers: this.options.authorizationServers,
+      scopes_supported: this.options.scopesSupported,
+      bearer_methods_supported: ["header"],
+    };
+  }
+
+  /**
+   * Extract scopes from JWT payload.
+   * Supports: "scope" claim (space-separated string) and "scp" claim (array).
+   */
+  private extractScopes(payload: Record<string, unknown>): string[] {
+    if (typeof payload.scope === "string") {
+      return payload.scope.split(" ").filter(Boolean);
+    }
+    if (Array.isArray(payload.scp)) {
+      return payload.scp.filter((s): s is string => typeof s === "string");
+    }
+    return [];
+  }
+}

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";