@frontmcp/auth 1.10.15 → 1.11.0-rc.1

package/browser/cimd/cimd.service.mjs

@@ -0,0 +1,376 @@
+// libs/auth/src/cimd/cimd.service.ts
+import { isRedirectResponse } from "@frontmcp/utils";
+import { createCimdCache } from "./cimd.cache.mjs";
+import {
+  CimdClientIdMismatchError,
+  CimdFetchError,
+  CimdResponseTooLargeError,
+  CimdSecurityError,
+  CimdValidationError,
+  RedirectUriMismatchError
+} from "./cimd.errors.mjs";
+import { noopLogger } from "./cimd.logger.mjs";
+import {
+  cimdCacheConfigSchema,
+  cimdConfigSchema,
+  cimdNetworkConfigSchema,
+  cimdSecurityConfigSchema,
+  clientMetadataDocumentSchema
+} from "./cimd.types.mjs";
+import { assertHostNotSsrf, hasOnlyLocalhostRedirectUris, isCimdClientId, validateClientIdUrl } from "./cimd.validator.mjs";
+var CimdService = class {
+  config;
+  cacheConfig;
+  securityConfig;
+  networkConfig;
+  cacheBackend;
+  logger;
+  /**
+   * Whether CIMD is enabled.
+   */
+  get enabled() {
+    return this.config.enabled;
+  }
+  /**
+   * Create a new CIMD service.
+   *
+   * @param logger - Optional logger. If not provided, logging is disabled.
+   * @param config - Optional configuration.
+   */
+  constructor(logger, config) {
+    this.logger = (logger ?? noopLogger).child("CimdService");
+    this.config = cimdConfigSchema.parse(config ?? {});
+    this.cacheConfig = cimdCacheConfigSchema.parse(this.config.cache ?? {});
+    this.securityConfig = cimdSecurityConfigSchema.parse(this.config.security ?? {});
+    this.networkConfig = cimdNetworkConfigSchema.parse(this.config.network ?? {});
+    this.logger.debug("CimdService initialized", {
+      enabled: this.config.enabled,
+      cacheDefaultTtlMs: this.cacheConfig.defaultTtlMs,
+      networkTimeoutMs: this.networkConfig.timeoutMs
+    });
+    if (this.securityConfig.allowInsecureForTesting) {
+      this.logger.warn(
+        "CIMD allowInsecureForTesting is enabled. HTTP is allowed for localhost CIMD URLs. This should NEVER be enabled in production!"
+      );
+    }
+  }
+  /**
+   * Create the cache now (connecting to Redis with `cache.type: 'redis'`), so a misconfigured or
+   * unreachable cache fails at startup rather than on the first CIMD client.
+   */
+  async initialize() {
+    await this.cache();
+  }
+  /**
+   * The cache `cache.type` selects, created once through the `createCimdCache` factory. A failed
+   * creation is retried on the next use.
+   */
+  cache() {
+    if (!this.cacheBackend) {
+      this.cacheBackend = createCimdCache(this.cacheConfig).catch((error) => {
+        this.cacheBackend = void 0;
+        throw error;
+      });
+    }
+    return this.cacheBackend;
+  }
+  /** Close the cache's connection (Redis with `cache.type: 'redis'`), if one was created. */
+  async dispose() {
+    const backend = this.cacheBackend;
+    this.cacheBackend = void 0;
+    if (!backend) return;
+    const createdBackend = await backend.catch(() => void 0);
+    await createdBackend?.close?.();
+  }
+  /**
+   * Check if a client_id is a CIMD URL.
+   *
+   * @param clientId - The client_id to check
+   * @returns true if this is a CIMD client_id (HTTPS URL with path, or HTTP for localhost when testing)
+   */
+  isCimdClientId(clientId) {
+    return isCimdClientId(clientId, this.securityConfig.allowInsecureForTesting);
+  }
+  /**
+   * Resolve a client_id to its metadata document.
+   *
+   * If the client_id is a CIMD URL, this fetches and validates the metadata document.
+   * Non-CIMD client IDs return a result with isCimdClient: false.
+   *
+   * @param clientId - The client_id to resolve
+   * @returns Resolution result with metadata if available
+   */
+  async resolveClientMetadata(clientId) {
+    if (!this.isCimdClientId(clientId)) {
+      return {
+        isCimdClient: false,
+        fromCache: false
+      };
+    }
+    validateClientIdUrl(clientId, this.securityConfig);
+    const cache = await this.cache();
+    const cached = await cache.get(clientId);
+    if (cached) {
+      this.logger.debug(`Cache hit for CIMD client: ${clientId}`);
+      return {
+        isCimdClient: true,
+        metadata: cached.document,
+        fromCache: true,
+        expiresAt: cached.expiresAt,
+        etag: cached.etag,
+        lastModified: cached.lastModified
+      };
+    }
+    this.logger.info(`Fetching CIMD document: ${clientId}`);
+    const { document, headers } = await this.fetchMetadataDocument(clientId);
+    this.validateDocument(clientId, document);
+    if (this.securityConfig.warnOnLocalhostRedirects && hasOnlyLocalhostRedirectUris(document.redirect_uris)) {
+      this.logger.warn(`CIMD client "${clientId}" has only localhost redirect URIs - this may be a development client`);
+    }
+    await cache.set(clientId, document, headers);
+    const entry = await cache.get(clientId);
+    return {
+      isCimdClient: true,
+      metadata: document,
+      fromCache: false,
+      expiresAt: entry?.expiresAt,
+      etag: entry?.etag,
+      lastModified: entry?.lastModified
+    };
+  }
+  /**
+   * Validate that a redirect_uri is registered for the client.
+   *
+   * @param redirectUri - The redirect_uri from the authorization request
+   * @param metadata - The client's metadata document
+   * @throws RedirectUriMismatchError if the redirect_uri is not registered
+   */
+  validateRedirectUri(redirectUri, metadata) {
+    const normalizedRequestUri = normalizeRedirectUri(redirectUri);
+    const normalizedAllowed = metadata.redirect_uris.map(normalizeRedirectUri);
+    if (!normalizedAllowed.includes(normalizedRequestUri)) {
+      throw new RedirectUriMismatchError(metadata.client_id, redirectUri, metadata.redirect_uris);
+    }
+  }
+  /**
+   * Clear the cache for a specific client or all clients.
+   *
+   * @param clientId - Optional client_id to clear; clears all if not provided
+   */
+  async clearCache(clientId) {
+    const cache = await this.cache();
+    if (clientId) {
+      await cache.delete(clientId);
+      this.logger.debug(`Cache cleared for: ${clientId}`);
+    } else {
+      await cache.clear();
+      this.logger.debug("Cache cleared");
+    }
+  }
+  /**
+   * Get cache statistics.
+   */
+  async getCacheStats() {
+    const cache = await this.cache();
+    return {
+      size: await cache.size()
+    };
+  }
+  /**
+   * Fetch a metadata document from a CIMD URL.
+   *
+   * Following the JwksService.fetchJson() pattern.
+   */
+  async fetchMetadataDocument(clientId) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.networkConfig.timeoutMs);
+    try {
+      const cache = await this.cache();
+      const conditionalHeaders = await cache.getConditionalHeaders(clientId);
+      const originalOrigin = new URL(clientId).origin;
+      const maxRedirects = this.networkConfig.maxRedirects;
+      let currentUrl = clientId;
+      let redirectCount = 0;
+      let isFirstRequest = true;
+      while (true) {
+        if (this.securityConfig.blockPrivateIPs && !this.securityConfig.allowInsecureForTesting) {
+          await assertHostNotSsrf(new URL(currentUrl).hostname, clientId);
+        }
+        const headers = {
+          Accept: "application/json"
+        };
+        if (isFirstRequest && conditionalHeaders) {
+          Object.assign(headers, conditionalHeaders);
+        }
+        const response = await fetch(currentUrl, {
+          method: "GET",
+          headers,
+          signal: controller.signal,
+          redirect: "manual"
+        });
+        if (response.status === 304) {
+          const staleEntry = await cache.getStale(clientId);
+          if (staleEntry) {
+            await cache.revalidate(clientId, response.headers);
+            this.logger.debug(`CIMD document not modified: ${clientId}`);
+            return {
+              document: staleEntry.document,
+              headers: response.headers
+            };
+          }
+          throw new CimdFetchError(clientId, "304 Not Modified but no cached entry", {
+            httpStatus: 304
+          });
+        }
+        if (isRedirectResponse(response)) {
+          const location = response.headers.get("location");
+          if (!location) {
+            throw new CimdFetchError(clientId, "Redirect response missing Location header", {
+              httpStatus: response.status
+            });
+          }
+          const nextUrl = new URL(location, currentUrl).toString();
+          const redirectPolicy = this.networkConfig.redirectPolicy;
+          if (redirectPolicy === "deny") {
+            throw new CimdFetchError(
+              clientId,
+              `CIMD fetch redirected to "${nextUrl}" but redirects are disabled. Host the metadata at the client_id URL or set auth.cimd.network.redirectPolicy to "same-origin" or "allow".`,
+              { httpStatus: response.status }
+            );
+          }
+          if (redirectPolicy === "same-origin") {
+            const nextOrigin = new URL(nextUrl).origin;
+            if (nextOrigin !== originalOrigin) {
+              throw new CimdFetchError(
+                clientId,
+                `CIMD fetch redirected to "${nextUrl}" which is not the same origin as "${originalOrigin}". Host the metadata at the client_id URL or set auth.cimd.network.redirectPolicy to "allow".`,
+                { httpStatus: response.status }
+              );
+            }
+          }
+          validateClientIdUrl(nextUrl, this.securityConfig);
+          redirectCount += 1;
+          if (redirectCount > maxRedirects) {
+            throw new CimdFetchError(
+              clientId,
+              `CIMD fetch exceeded max redirects (${maxRedirects}). Host the metadata at the client_id URL or increase auth.cimd.network.maxRedirects.`
+            );
+          }
+          this.logger.warn(`CIMD redirect ${redirectCount}/${maxRedirects}: ${currentUrl} -> ${nextUrl}`);
+          currentUrl = nextUrl;
+          isFirstRequest = false;
+          continue;
+        }
+        if (!response.ok) {
+          throw new CimdFetchError(clientId, `HTTP ${response.status} ${response.statusText}`, {
+            httpStatus: response.status
+          });
+        }
+        const contentLength = response.headers.get("content-length");
+        if (contentLength) {
+          const length = parseInt(contentLength, 10);
+          if (!isNaN(length) && length > this.networkConfig.maxResponseSizeBytes) {
+            throw new CimdResponseTooLargeError(clientId, this.networkConfig.maxResponseSizeBytes, length);
+          }
+        }
+        const text = await this.readResponseWithLimit(response, this.networkConfig.maxResponseSizeBytes, clientId);
+        let document;
+        try {
+          document = JSON.parse(text);
+        } catch (e) {
+          throw new CimdFetchError(clientId, "Invalid JSON response", {
+            originalError: e instanceof Error ? e : new Error(String(e))
+          });
+        }
+        return { document, headers: response.headers };
+      }
+    } catch (error) {
+      if (error instanceof CimdFetchError || error instanceof CimdResponseTooLargeError || error instanceof CimdSecurityError) {
+        throw error;
+      }
+      if (error instanceof Error && error.name === "AbortError") {
+        throw new CimdFetchError(clientId, "Request timeout", {
+          originalError: error
+        });
+      }
+      throw new CimdFetchError(clientId, error instanceof Error ? error.message : "Unknown error", {
+        originalError: error instanceof Error ? error : void 0
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  /**
+   * Read response body with size limit.
+   */
+  async readResponseWithLimit(response, maxBytes, clientId) {
+    const reader = response.body?.getReader();
+    if (!reader) {
+      const buffer = await response.arrayBuffer();
+      if (buffer.byteLength > maxBytes) {
+        throw new CimdResponseTooLargeError(clientId, maxBytes, buffer.byteLength);
+      }
+      return new TextDecoder().decode(buffer);
+    }
+    const chunks = [];
+    let totalBytes = 0;
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        totalBytes += value.length;
+        if (totalBytes > maxBytes) {
+          throw new CimdResponseTooLargeError(clientId, maxBytes, totalBytes);
+        }
+        chunks.push(value);
+      }
+    } finally {
+      reader.releaseLock();
+    }
+    const combined = new Uint8Array(totalBytes);
+    let offset = 0;
+    for (const chunk of chunks) {
+      combined.set(chunk, offset);
+      offset += chunk.length;
+    }
+    return new TextDecoder().decode(combined);
+  }
+  /**
+   * Validate a fetched document against the schema.
+   *
+   * @param clientId - The URL from which the document was fetched
+   * @param document - The document to validate
+   */
+  validateDocument(clientId, document) {
+    const result = clientMetadataDocumentSchema.safeParse(document);
+    if (!result.success) {
+      const errors = result.error.issues.map((issue) => {
+        const path = issue.path.length > 0 ? `${issue.path.join(".")}: ` : "";
+        return `${path}${issue.message}`;
+      });
+      throw new CimdValidationError(clientId, errors);
+    }
+    if (result.data.client_id !== clientId) {
+      throw new CimdClientIdMismatchError(clientId, result.data.client_id);
+    }
+  }
+};
+var LOOPBACK_HOSTNAMES = /* @__PURE__ */ new Set(["127.0.0.1", "::1", "[::1]", "localhost"]);
+function isLoopbackHostname(hostname) {
+  return LOOPBACK_HOSTNAMES.has(hostname.toLowerCase());
+}
+function normalizeRedirectUri(uri) {
+  try {
+    const url = new URL(uri);
+    const host = isLoopbackHostname(url.hostname) ? url.hostname.toLowerCase() : url.host.toLowerCase();
+    let normalized = `${url.protocol.toLowerCase()}//${host}`;
+    normalized += url.pathname.replace(/\/+$/, "") || "/";
+    if (url.search) normalized += url.search;
+    return normalized;
+  } catch {
+    return uri;
+  }
+}
+export {
+  CimdService
+};

package/browser/cimd/cimd.types.mjs

@@ -0,0 +1,228 @@
+// libs/auth/src/cimd/cimd.types.ts
+import { internalZ as z } from "@frontmcp/lazy-zod";
+var clientMetadataDocumentSchema = z.object({
+  // REQUIRED per CIMD spec
+  /**
+   * Client identifier - MUST match the URL from which this document was fetched.
+   */
+  client_id: z.string().url(),
+  /**
+   * Human-readable name of the client.
+   */
+  client_name: z.string().min(1),
+  /**
+   * Array of redirect URIs for authorization responses.
+   * At least one is required.
+   */
+  redirect_uris: z.array(z.string().url()).min(1),
+  // OPTIONAL per RFC 7591
+  /**
+   * Token endpoint authentication method.
+   * @default 'none'
+   */
+  token_endpoint_auth_method: z.enum(["none", "client_secret_basic", "client_secret_post", "private_key_jwt"]).default("none"),
+  /**
+   * OAuth grant types the client can use.
+   * @default ['authorization_code']
+   */
+  grant_types: z.array(z.string()).default(["authorization_code"]),
+  /**
+   * OAuth response types the client can request.
+   * @default ['code']
+   */
+  response_types: z.array(z.string()).default(["code"]),
+  /**
+   * URL of the client's home page.
+   */
+  client_uri: z.string().url().optional(),
+  /**
+   * URL of the client's logo image.
+   */
+  logo_uri: z.string().url().optional(),
+  /**
+   * URL of the client's JWKS (for private_key_jwt).
+   */
+  jwks_uri: z.string().url().optional(),
+  /**
+   * Inline JWKS (for private_key_jwt).
+   */
+  jwks: z.object({
+    keys: z.array(z.record(z.string(), z.unknown()))
+  }).optional(),
+  /**
+   * URL of the client's terms of service.
+   */
+  tos_uri: z.string().url().optional(),
+  /**
+   * URL of the client's privacy policy.
+   */
+  policy_uri: z.string().url().optional(),
+  /**
+   * Requested OAuth scopes.
+   */
+  scope: z.string().optional(),
+  /**
+   * Array of contact emails for the client.
+   */
+  contacts: z.array(z.string().email()).optional(),
+  /**
+   * Software statement (signed JWT).
+   */
+  software_statement: z.string().optional(),
+  /**
+   * Unique identifier for the client software.
+   */
+  software_id: z.string().optional(),
+  /**
+   * Version of the client software.
+   */
+  software_version: z.string().optional()
+});
+var cimdRedisCacheConfigSchema = z.object({
+  /**
+   * Redis connection URL.
+   * e.g., "redis://user:pass@host:6379/0"
+   */
+  url: z.string().optional(),
+  /**
+   * Redis host.
+   */
+  host: z.string().optional(),
+  /**
+   * Redis port.
+   * @default 6379
+   */
+  port: z.number().optional(),
+  /**
+   * Redis password.
+   */
+  password: z.string().optional(),
+  /**
+   * Redis database number.
+   * @default 0
+   */
+  db: z.number().optional(),
+  /**
+   * Enable TLS for Redis connection.
+   * @default false
+   */
+  tls: z.boolean().optional(),
+  /**
+   * Key prefix for CIMD cache entries.
+   * @default 'cimd:'
+   */
+  keyPrefix: z.string().default("cimd:")
+});
+var cimdCacheConfigSchema = z.object({
+  /**
+   * Cache storage type.
+   * - 'memory': In-memory cache (default, suitable for dev/single-instance)
+   * - 'redis': Redis-backed cache (for production/distributed deployments)
+   * @default 'memory'
+   */
+  type: z.enum(["memory", "redis"]).default("memory"),
+  /**
+   * Default TTL for cached metadata documents.
+   * @default 3600000 (1 hour)
+   */
+  defaultTtlMs: z.number().min(0).default(36e5),
+  /**
+   * Maximum TTL (even if server suggests longer).
+   * @default 86400000 (24 hours)
+   */
+  maxTtlMs: z.number().min(0).default(864e5),
+  /**
+   * Minimum TTL (even if server suggests shorter).
+   * @default 60000 (1 minute)
+   */
+  minTtlMs: z.number().min(0).default(6e4),
+  /**
+   * Redis configuration (required when type is 'redis').
+   */
+  redis: cimdRedisCacheConfigSchema.optional()
+});
+var cimdSecurityConfigSchema = z.object({
+  /**
+   * Block fetching from private/internal IP addresses (SSRF protection).
+   * @default true
+   */
+  blockPrivateIPs: z.boolean().default(true),
+  /**
+   * Explicit list of allowed domains.
+   * If set, only these domains can host CIMD documents.
+   */
+  allowedDomains: z.array(z.string()).optional(),
+  /**
+   * Explicit list of blocked domains.
+   * These domains cannot host CIMD documents.
+   */
+  blockedDomains: z.array(z.string()).optional(),
+  /**
+   * Warn when a client has only localhost redirect URIs.
+   * @default true
+   */
+  warnOnLocalhostRedirects: z.boolean().default(true),
+  /**
+   * Allow HTTP (instead of HTTPS) for localhost CIMD URLs.
+   *
+   * **WARNING: This is for testing purposes only. Never enable in production!**
+   *
+   * When enabled, permits HTTP URLs for localhost CIMD client IDs during testing.
+   * The CIMD spec requires HTTPS, but e2e test servers typically use HTTP.
+   *
+   * @default false
+   */
+  allowInsecureForTesting: z.boolean().default(false)
+});
+var cimdNetworkConfigSchema = z.object({
+  /**
+   * Request timeout in milliseconds.
+   * @default 5000 (5 seconds)
+   */
+  timeoutMs: z.number().min(100).default(5e3),
+  /**
+   * Maximum response body size in bytes.
+   * @default 65536 (64KB)
+   */
+  maxResponseSizeBytes: z.number().min(1024).default(65536),
+  /**
+   * Redirect handling policy for CIMD fetches.
+   * - 'deny': reject redirects (default, safest)
+   * - 'same-origin': allow redirects only to the same origin
+   * - 'allow': allow redirects to any origin
+   * @default 'deny'
+   */
+  redirectPolicy: z.enum(["deny", "same-origin", "allow"]).default("deny"),
+  /**
+   * Maximum number of redirects to follow when redirects are allowed.
+   * @default 5
+   */
+  maxRedirects: z.number().int().min(0).default(5)
+});
+var cimdConfigSchema = z.object({
+  /**
+   * Enable CIMD support.
+   * @default true
+   */
+  enabled: z.boolean().default(true),
+  /**
+   * Cache configuration.
+   */
+  cache: cimdCacheConfigSchema.optional(),
+  /**
+   * Security configuration.
+   */
+  security: cimdSecurityConfigSchema.optional(),
+  /**
+   * Network configuration.
+   */
+  network: cimdNetworkConfigSchema.optional()
+});
+export {
+  cimdCacheConfigSchema,
+  cimdConfigSchema,
+  cimdNetworkConfigSchema,
+  cimdRedisCacheConfigSchema,
+  cimdSecurityConfigSchema,
+  clientMetadataDocumentSchema
+};