jamdesk 1.0.0

package/vendored/lib/middleware-helpers.ts

@@ -0,0 +1,519 @@
+/**
+ * Middleware Helpers
+ *
+ * Testable helper functions for the Next.js middleware.
+ * Handles project resolution, security validation, and routing logic.
+ */
+
+import { log } from './logger';
+import {
+  resolveProject,
+  resolveProjectFromHostname,
+  resolveCustomDomain,
+  getProjectConfig,
+  isSubdomain,
+} from './project-resolver';
+import { redis } from './redis';
+import { getForwardedHosts, isJamdeskDomain } from './domain-helpers';
+import { getRedirects, matchRedirect, mergeQueryStrings, isInvalidDestination } from './redirect-matcher';
+import { ASSET_PREFIX } from './docs-types';
+import type { NextRequest } from 'next/server';
+
+/**
+ * Result of project resolution.
+ */
+export interface ProjectResolutionResult {
+  /** Resolved project slug, or null if not found */
+  projectSlug: string | null;
+  /** Whether to host docs at /docs path */
+  hostAtDocs: boolean;
+  /** Error message if resolution failed */
+  error?: string;
+  /** Whether to skip middleware (non-ISR mode) */
+  skip?: boolean;
+  /** Domain verification status */
+  domainStatus?: string;
+}
+
+/**
+ * Security validation result.
+ */
+export interface SecurityResult {
+  /** Whether the request is allowed */
+  allowed: boolean;
+  /** Error message if blocked */
+  error?: string;
+  /** HTTP status code for blocked requests */
+  status?: number;
+}
+
+/**
+ * Redirect check result.
+ */
+export interface RedirectResult {
+  /** Whether a redirect should happen */
+  shouldRedirect: boolean;
+  /** Redirect destination URL */
+  destination?: string;
+  /** HTTP status code (301 or 302) */
+  status?: number;
+}
+
+/**
+ * Handle project resolution from hostname.
+ *
+ * Supports forwarded host headers for custom domain resolution. When a request
+ * arrives at a Jamdesk subdomain with X-Jamdesk-Forwarded-Host set to a custom
+ * domain, the custom domain's config (hostAtDocs) is used instead of the
+ * subdomain's project config. This enables generic Cloudflare Workers that
+ * don't need domain-specific logic.
+ *
+ * @param request - Next.js request object
+ * @returns Resolution result with project slug or error
+ */
+export async function handleProjectResolution(
+  request: NextRequest
+): Promise<ProjectResolutionResult> {
+  const hostname = request.headers.get('host') || '';
+
+  // Skip if not in ISR mode
+  if (process.env.ISR_MODE !== 'true') {
+    return { projectSlug: null, hostAtDocs: true, skip: true };
+  }
+
+  log('info', 'Resolving project from hostname', { hostname });
+
+  // Check if it's a Jamdesk subdomain first (fast path)
+  const isJamdesk = isSubdomain(hostname);
+
+  if (isJamdesk) {
+    const projectSlug = resolveProjectFromHostname(hostname);
+    if (projectSlug) {
+      // Check for forwarded custom domain - use its config for hostAtDocs
+      // This enables generic Cloudflare Workers that pass X-Jamdesk-Forwarded-Host
+      const forwardedHosts = getForwardedHosts(request);
+      const customForwardedHost = forwardedHosts.find(h => !isJamdeskDomain(h));
+
+      if (customForwardedHost) {
+        // Resolve hostAtDocs from custom domain config
+        const customResolution = await resolveCustomDomain(customForwardedHost);
+        log('info', 'Project resolved from subdomain with forwarded custom domain', {
+          hostname,
+          projectSlug,
+          forwardedHost: customForwardedHost,
+          hostAtDocs: customResolution.hostAtDocs,
+        });
+        return {
+          projectSlug,
+          hostAtDocs: customResolution.hostAtDocs,
+        };
+      }
+
+      // No forwarded custom domain - use project config
+      const config = await getProjectConfig(projectSlug);
+      log('info', 'Project resolved from subdomain', { hostname, projectSlug });
+      return { projectSlug, hostAtDocs: config.hostAtDocs };
+    }
+  }
+
+  // Custom domain - resolve via Redis
+  const resolution = await resolveCustomDomain(hostname);
+
+  if (!resolution.projectSlug) {
+    log('warn', 'Project not found for hostname', { hostname });
+    return {
+      projectSlug: null,
+      hostAtDocs: true,
+      error: 'Project not found',
+    };
+  }
+
+  // Check domain verification status
+  if (resolution.domainStatus && resolution.domainStatus !== 'active' && resolution.domainStatus !== 'cached') {
+    log('warn', 'Domain not active', { hostname, status: resolution.domainStatus });
+    return {
+      projectSlug: resolution.projectSlug,
+      hostAtDocs: resolution.hostAtDocs,
+      domainStatus: resolution.domainStatus,
+      error: 'Domain not verified',
+    };
+  }
+
+  log('info', 'Project resolved from custom domain', { hostname, projectSlug: resolution.projectSlug });
+  return {
+    projectSlug: resolution.projectSlug,
+    hostAtDocs: resolution.hostAtDocs,
+    domainStatus: resolution.domainStatus,
+  };
+}
+
+/**
+ * Validate forwarded host headers for security.
+ * Prevents unauthorized proxying of content.
+ *
+ * @param request - Next.js request
+ * @param projectSlug - Expected project slug
+ * @returns Security validation result
+ */
+export async function validateForwardedHost(
+  request: NextRequest,
+  projectSlug: string
+): Promise<SecurityResult> {
+  const hostname = request.headers.get('host') || '';
+  const forwardedHosts = getForwardedHosts(request);
+
+  // No forwarded hosts - allow
+  if (forwardedHosts.length === 0) {
+    return { allowed: true };
+  }
+
+  // Not a Jamdesk subdomain - skip validation
+  if (!isJamdeskDomain(hostname)) {
+    return { allowed: true };
+  }
+
+  // Filter to only custom domains (non-Jamdesk) that need validation
+  const customForwardedHosts = forwardedHosts.filter(h => h && !isJamdeskDomain(h));
+
+  // No custom domains to validate - allow (Jamdesk domains are trusted)
+  if (customForwardedHosts.length === 0) {
+    return { allowed: true };
+  }
+
+  // No Redis - can't validate custom forwarded hosts, fail closed for security
+  if (!redis) {
+    log('error', 'Blocked request - cannot validate forwarded host without Redis', { hostname, forwardedHosts: customForwardedHosts });
+    return {
+      allowed: false,
+      error: 'Service temporarily unavailable',
+      status: 503,
+    };
+  }
+
+  // Validate each custom forwarded host
+  for (const forwardedHost of customForwardedHosts) {
+    try {
+      const [status, mappedProject] = await Promise.all([
+        redis.get<string>(`domainStatus:${forwardedHost}`),
+        redis.get<string>(`domain:${forwardedHost}`),
+      ]);
+
+      // Must be active AND map to the same project
+      if (status !== 'active' || mappedProject !== projectSlug) {
+        log('warn', 'Blocked proxied request - forwarded host not verified', {
+          hostname,
+          projectSlug,
+          forwardedHost,
+          mappedProject: mappedProject || 'not-registered',
+          status: status || 'missing',
+        });
+        return {
+          allowed: false,
+          error: `Domain "${forwardedHost}" is not authorized to serve this content.`,
+          status: 403,
+        };
+      }
+    } catch (error) {
+      log('error', 'Redis lookup failed for forwarded host', { forwardedHost, error });
+      return {
+        allowed: false,
+        error: 'Service temporarily unavailable',
+        status: 503,
+      };
+    }
+  }
+
+  return { allowed: true };
+}
+
+/**
+ * Check for redirects and return redirect info if matched.
+ *
+ * @param projectSlug - Project identifier
+ * @param pathname - Request pathname
+ * @param search - Query string
+ * @returns Redirect result
+ */
+export async function checkRedirects(
+  projectSlug: string,
+  pathname: string,
+  search: string
+): Promise<RedirectResult> {
+  const redirects = await getRedirects(projectSlug);
+  if (!redirects?.length) {
+    return { shouldRedirect: false };
+  }
+
+  const match = matchRedirect(pathname, redirects);
+  if (!match) {
+    return { shouldRedirect: false };
+  }
+
+  const destination = mergeQueryStrings(search, match.destination);
+
+  // Final safety check: skip redirects to protected paths or with wildcards
+  if (isInvalidDestination(destination)) {
+    log('warn', 'Skipping redirect to invalid destination', {
+      projectSlug,
+      pathname,
+      destination,
+    });
+    return { shouldRedirect: false };
+  }
+
+  return {
+    shouldRedirect: true,
+    destination,
+    status: match.permanent ? 301 : 302,
+  };
+}
+
+/**
+ * Internal API routes that should skip middleware processing.
+ *
+ * IMPORTANT: When adding a new API route to app/api/, add it here too!
+ * Otherwise doc pages with similar paths will be incorrectly skipped.
+ *
+ * Note: Documentation pages under /api/* (like /api/overview, /api/users/list)
+ * should NOT be skipped - they need project context from middleware.
+ * Only skip actual internal API endpoints.
+ *
+ * Uses exact match OR prefix-with-slash to avoid false positives:
+ * - /api/og → skipped (exact match)
+ * - /api/og/ → skipped (prefix match)
+ * - /api/ogimage → NOT skipped (could be a doc page)
+ */
+export const INTERNAL_API_ROUTES = [
+  '/api/assets',     // Asset serving from R2 (app/api/assets/[...path])
+  '/api/ev',         // Analytics events (app/api/ev)
+  '/api/isr-health', // Health check endpoint (app/api/isr-health)
+  '/api/mcp',        // MCP endpoint (app/api/mcp/[project])
+  '/api/og',         // OG image generation (app/api/og)
+  '/api/r2',         // R2 content serving (app/api/r2/[project]/[...path])
+  '/api/revalidate', // Cache revalidation (app/api/revalidate)
+];
+
+/**
+ * Check if path is an internal API route.
+ *
+ * @param pathname - Request pathname
+ * @returns true if this is an internal API route that should skip middleware
+ *
+ * @example
+ * isInternalApiRoute('/api/og')           // true (exact match)
+ * isInternalApiRoute('/api/og/')          // true (prefix + slash)
+ * isInternalApiRoute('/api/ogimage')      // false (not a match)
+ * isInternalApiRoute('/api/users/list')   // false (doc page)
+ */
+export function isInternalApiRoute(pathname: string): boolean {
+  return INTERNAL_API_ROUTES.some(route =>
+    pathname === route || pathname.startsWith(route + '/')
+  );
+}
+
+/**
+ * File extensions that should skip middleware.
+ * Note: Image extensions (.png, .jpg, .webp, etc.) are NOT skipped
+ * because they need to be routed through the asset API with project context.
+ */
+const SKIP_EXTENSIONS = [
+  '.css',
+  '.js',
+  '.woff',
+  '.woff2',
+  '.ttf',
+  '.eot',
+  '.map',
+];
+
+/**
+ * Static asset paths bundled with the app (not project-specific).
+ * These are served directly from public/ and don't need middleware processing.
+ */
+const STATIC_ASSET_PREFIXES = [
+  `${ASSET_PREFIX}/branding/`,  // Jamdesk branding assets
+  `${ASSET_PREFIX}/fonts/`,     // Font Awesome web fonts
+] as const;
+
+/**
+ * Check if middleware should run for this path.
+ *
+ * @param pathname - Request pathname (e.g., '/introduction')
+ * @returns true if middleware should process this request
+ */
+export function shouldRunMiddleware(pathname: string): boolean {
+  // Skip Next.js internals
+  if (pathname.startsWith('/_next/')) {
+    return false;
+  }
+
+  // Skip internal API routes (but NOT doc pages under /api/*)
+  if (isInternalApiRoute(pathname)) {
+    return false;
+  }
+
+  // Skip other static paths
+  if (pathname === '/favicon.ico' || pathname.startsWith('/.well-known/')) {
+    return false;
+  }
+
+  // Skip bundled static assets (branding, fonts)
+  // Note: /_jd/images/ is NOT skipped - those are project-specific from R2
+  if (STATIC_ASSET_PREFIXES.some(prefix => pathname.startsWith(prefix))) {
+    return false;
+  }
+
+  // Skip static file extensions
+  if (SKIP_EXTENSIONS.some(ext => pathname.endsWith(ext))) {
+    return false;
+  }
+
+  // Note: /robots.txt, /sitemap.xml, /llms.txt are NOT skipped
+  // They are served from R2 and need project context from middleware
+
+  return true;
+}
+
+/**
+ * Check if this is an MCP request that needs routing.
+ *
+ * @param pathname - Request pathname
+ * @returns true if this is an MCP request
+ */
+export function isMcpRequest(pathname: string): boolean {
+  return pathname === '/_mcp' || pathname === '/docs/_mcp';
+}
+
+/**
+ * Get the MCP API path for a project.
+ *
+ * @param projectSlug - Project identifier
+ * @returns MCP API route path
+ */
+export function getMcpApiPath(projectSlug: string): string {
+  return `/api/mcp/${projectSlug}`;
+}
+
+/**
+ * Check if path needs trailing slash normalization.
+ *
+ * @param pathname - Request pathname
+ * @returns true if trailing slash should be removed
+ */
+export function needsTrailingSlashRedirect(pathname: string): boolean {
+  return (
+    pathname !== '/' &&
+    pathname.endsWith('/') &&
+    !pathname.startsWith('/_next/')
+  );
+}
+
+/**
+ * Handle hostAtDocs routing logic.
+ * Determines if path needs redirect based on hostAtDocs setting.
+ *
+ * @param pathname - Request pathname
+ * @param hostAtDocs - Whether docs are hosted at /docs
+ * @returns Redirect destination or null if no redirect needed
+ */
+export function getHostAtDocsRedirect(
+  pathname: string,
+  hostAtDocs: boolean
+): string | null {
+  if (hostAtDocs) {
+    // hostAtDocs=true: Docs served at /docs/*
+    if (pathname === '/') {
+      return '/docs';
+    }
+    // Check if path is a page (not an asset)
+    const isAsset = pathname.includes('.');
+    if (!isAsset && !pathname.startsWith('/docs')) {
+      return `/docs${pathname}`;
+    }
+  } else {
+    // hostAtDocs=false: Docs served at root
+    // Redirect legacy /docs/* paths
+    if (pathname === '/docs' || pathname === '/docs/') {
+      return '/';
+    }
+    if (pathname.startsWith('/docs/')) {
+      return pathname.replace('/docs/', '/');
+    }
+  }
+  return null;
+}
+
+/**
+ * Build response headers with project context.
+ *
+ * @param projectSlug - Resolved project slug
+ * @param hostAtDocs - Whether docs are hosted at /docs
+ * @param existingHeaders - Existing request headers to clone
+ * @returns New headers with project context added
+ */
+export function buildProjectHeaders(
+  projectSlug: string,
+  existingHeaders: Headers,
+  hostAtDocs = true
+): Headers {
+  const newHeaders = new Headers(existingHeaders);
+  newHeaders.set('x-project-slug', projectSlug);
+  newHeaders.set('x-host-at-docs', hostAtDocs ? 'true' : 'false');
+  return newHeaders;
+}
+
+/**
+ * Asset extensions that need to be routed to the assets API.
+ */
+const ASSET_EXTENSIONS = ['.png', '.jpg', '.jpeg', '.gif', '.svg', '.webp', '.ico', '.pdf'];
+
+/**
+ * Project-specific files that need to be fetched from R2 via assets API.
+ * These files are unique per project and stored in the assets/ directory in R2.
+ *
+ * Note: search-data.json and search-index.orama.json are NOT included here
+ * because they're stored at the project root in R2, not in assets/.
+ * They have dedicated routes (app/search-data.json/route.ts) instead.
+ */
+const PROJECT_SPECIFIC_FILES: string[] = [
+  // Currently empty - search files have dedicated routes
+];
+
+/**
+ * Check if this is an asset request that needs routing to the assets API.
+ *
+ * @param pathname - Request pathname
+ * @returns true if this is an asset that should be served from R2
+ */
+export function isAssetRequest(pathname: string): boolean {
+  // Skip bundled static assets (branding, fonts) - served directly from public/
+  if (STATIC_ASSET_PREFIXES.some(prefix => pathname.startsWith(prefix))) {
+    return false;
+  }
+
+  // Project images under /_jd/images/ are served from R2
+  if (pathname.startsWith(`${ASSET_PREFIX}/images/`)) {
+    return true;
+  }
+
+  // Project-specific files from R2, or files with asset extensions
+  return (
+    PROJECT_SPECIFIC_FILES.includes(pathname) ||
+    ASSET_EXTENSIONS.some(ext => pathname.endsWith(ext))
+  );
+}
+
+/**
+ * Get the assets API path for rewriting.
+ *
+ * Strips the /_jd/ prefix since R2 stores assets without it.
+ *
+ * @param pathname - Original request pathname (e.g., '/_jd/images/logo.png')
+ * @returns Assets API path (e.g., '/api/assets/images/logo.png')
+ */
+export function getAssetsApiPath(pathname: string): string {
+  // Strip asset prefix and leading slash (R2 stores at images/, not _jd/images/)
+  const prefixPattern = new RegExp(`^${ASSET_PREFIX}/`);
+  const assetPath = pathname.replace(prefixPattern, '').replace(/^\//, '');
+  return `/api/assets/${assetPath}`;
+}