sovrium 0.0.2

package/src/infrastructure/server/route-setup/auth-route-utils.ts

@@ -0,0 +1,399 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+/**
+ * Rate limiting state for admin endpoints
+ * Maps IP addresses to request timestamps
+ * In production, this should use Redis or similar distributed storage
+ */
+const adminRateLimitState = new Map<string, number[]>()
+
+/**
+ * Rate limiting configuration constants
+ */
+const RATE_LIMIT_WINDOW_MS = 1000 // 1 second window
+const RATE_LIMIT_MAX_REQUESTS = 10 // Maximum requests per window
+
+/**
+ * Get rate limit window duration in milliseconds from environment variable
+ * Defaults to 60 seconds (production) if not set
+ * Tests should set RATE_LIMIT_WINDOW_SECONDS=5 for faster execution
+ */
+const getRateLimitWindowMs = (): number => {
+  const windowSeconds = process.env.RATE_LIMIT_WINDOW_SECONDS
+  return windowSeconds ? parseInt(windowSeconds, 10) * 1000 : 60 * 1000
+}
+
+/**
+ * Get recent requests within the rate limit window for an IP address
+ * Returns filtered array of timestamps within RATE_LIMIT_WINDOW_MS
+ * Single source of truth for request filtering (DRY principle)
+ */
+export const getRecentRequests = (ip: string): readonly number[] => {
+  const now = Date.now()
+  const requestHistory = adminRateLimitState.get(ip) ?? []
+  return requestHistory.filter((timestamp) => now - timestamp < RATE_LIMIT_WINDOW_MS)
+}
+
+/**
+ * Check rate limit for an IP address
+ * Returns true if rate limit is exceeded, false otherwise
+ */
+export const isRateLimitExceeded = (ip: string): boolean => {
+  return getRecentRequests(ip).length >= RATE_LIMIT_MAX_REQUESTS
+}
+
+/**
+ * Record a request for rate limiting
+ * Updates the request history for the given IP address
+ * Returns the updated request history for testing/debugging
+ */
+export const recordRateLimitRequest = (ip: string): readonly number[] => {
+  const recentRequests = getRecentRequests(ip)
+  const now = Date.now()
+  const updated = [...recentRequests, now]
+  // eslint-disable-next-line functional/no-expression-statements, functional/immutable-data -- Rate limiting requires mutable state
+  adminRateLimitState.set(ip, updated)
+  return updated
+}
+
+/**
+ * Extract IP address from request headers
+ * Returns the client IP from x-forwarded-for or defaults to localhost
+ */
+export const extractClientIp = (forwardedFor: string | undefined): string => {
+  return forwardedFor ? (forwardedFor.split(',')[0]?.trim() ?? '127.0.0.1') : '127.0.0.1'
+}
+
+/**
+ * Rate limiting configuration for authentication endpoints
+ * Security-critical endpoints to prevent brute force attacks
+ */
+interface EndpointRateLimitConfig {
+  readonly windowMs: number
+  readonly maxRequests: number
+}
+
+/**
+ * Get authentication rate limit configurations
+ * Uses configurable window from environment variable
+ */
+const getAuthRateLimitConfigs = (): Record<string, EndpointRateLimitConfig> => {
+  const windowMs = getRateLimitWindowMs()
+
+  return {
+    '/api/auth/sign-in/email': {
+      windowMs,
+      maxRequests: 20, // 20 attempts per window (prevents brute force while allowing legitimate retries)
+    },
+    '/api/auth/sign-up/email': {
+      windowMs,
+      maxRequests: 20, // 20 signups per window (prevents abuse while allowing test scenarios)
+    },
+    '/api/auth/request-password-reset': {
+      windowMs,
+      maxRequests: 10, // 10 attempts per window (prevents enumeration while allowing legitimate use)
+    },
+  }
+}
+
+const AUTH_RATE_LIMIT_CONFIGS: Record<string, EndpointRateLimitConfig> = getAuthRateLimitConfigs()
+
+/**
+ * Rate limiting state for authentication endpoints
+ * Maps endpoint + IP to request timestamps
+ */
+const authRateLimitState = new Map<string, number[]>()
+
+/**
+ * Get rate limit key for endpoint + IP combination
+ */
+const getRateLimitKey = (endpoint: string, ip: string): string => {
+  return `${endpoint}:${ip}`
+}
+
+/**
+ * Get recent requests within the rate limit window for an endpoint + IP
+ */
+export const getAuthRecentRequests = (endpoint: string, ip: string): readonly number[] => {
+  const config = AUTH_RATE_LIMIT_CONFIGS[endpoint]
+  if (!config) return []
+
+  const now = Date.now()
+  const key = getRateLimitKey(endpoint, ip)
+  const requestHistory = authRateLimitState.get(key) ?? []
+  return requestHistory.filter((timestamp) => now - timestamp < config.windowMs)
+}
+
+/**
+ * Check if auth endpoint rate limit is exceeded for an IP
+ */
+export const isAuthRateLimitExceeded = (endpoint: string, ip: string): boolean => {
+  const config = AUTH_RATE_LIMIT_CONFIGS[endpoint]
+  if (!config) return false
+
+  return getAuthRecentRequests(endpoint, ip).length >= config.maxRequests
+}
+
+/**
+ * Record a request for auth endpoint rate limiting
+ */
+export const recordAuthRateLimitRequest = (endpoint: string, ip: string): readonly number[] => {
+  const recentRequests = getAuthRecentRequests(endpoint, ip)
+  const now = Date.now()
+  const key = getRateLimitKey(endpoint, ip)
+  const updated = [...recentRequests, now]
+  // eslint-disable-next-line functional/no-expression-statements, functional/immutable-data -- Rate limiting requires mutable state
+  authRateLimitState.set(key, updated)
+  return updated
+}
+
+/**
+ * Calculate seconds until auth rate limit window resets
+ */
+export const getAuthRateLimitRetryAfter = (endpoint: string, ip: string): number => {
+  const config = AUTH_RATE_LIMIT_CONFIGS[endpoint]
+  if (!config) return 0
+
+  const recentRequests = getAuthRecentRequests(endpoint, ip)
+  if (recentRequests.length === 0) return 0
+
+  const oldestRequest = Math.min(...recentRequests)
+  const resetTime = oldestRequest + config.windowMs
+  const now = Date.now()
+  const retryAfterMs = Math.max(0, resetTime - now)
+
+  return Math.ceil(retryAfterMs / 1000) // Convert to seconds
+}
+
+/**
+ * Rate limiting configuration for table API endpoints
+ * Higher limits than auth endpoints since legitimate usage involves frequent data operations
+ */
+const getTablesRateLimitConfigs = (): Record<string, EndpointRateLimitConfig> => {
+  const windowMs = getRateLimitWindowMs()
+
+  return {
+    // List tables endpoint
+    'GET:/api/tables': {
+      windowMs,
+      maxRequests: 100, // 100 requests per window (frequent polling for table lists)
+    },
+    // Get table records endpoint (read operations)
+    'GET:/api/tables/*': {
+      windowMs,
+      maxRequests: 100, // 100 requests per window (frequent data fetching)
+    },
+    // Create record endpoint (write operations - stricter limits)
+    'POST:/api/tables/*': {
+      windowMs,
+      maxRequests: 50, // 50 requests per window (prevent data flooding)
+    },
+  }
+}
+
+const TABLES_RATE_LIMIT_CONFIGS: Record<string, EndpointRateLimitConfig> =
+  getTablesRateLimitConfigs()
+
+/**
+ * Rate limiting state for table endpoints
+ * Maps method:endpoint + IP to request timestamps
+ */
+const tablesRateLimitState = new Map<string, number[]>()
+
+/**
+ * Get rate limit key for table endpoint (includes HTTP method)
+ */
+const getTablesRateLimitKey = (method: string, path: string, ip: string): string => {
+  // Match exact path or wildcard pattern
+  const configKey = TABLES_RATE_LIMIT_CONFIGS[`${method}:${path}`]
+    ? `${method}:${path}`
+    : `${method}:/api/tables/*`
+
+  return `${configKey}:${ip}`
+}
+
+/**
+ * Get recent requests for table endpoint
+ */
+export const getTablesRecentRequests = (
+  method: string,
+  path: string,
+  ip: string
+): readonly number[] => {
+  const configKey = TABLES_RATE_LIMIT_CONFIGS[`${method}:${path}`]
+    ? `${method}:${path}`
+    : `${method}:/api/tables/*`
+
+  const config = TABLES_RATE_LIMIT_CONFIGS[configKey]
+  if (!config) return []
+
+  const now = Date.now()
+  const key = getTablesRateLimitKey(method, path, ip)
+  const requestHistory = tablesRateLimitState.get(key) ?? []
+  return requestHistory.filter((timestamp) => now - timestamp < config.windowMs)
+}
+
+/**
+ * Check if table endpoint rate limit is exceeded
+ */
+export const isTablesRateLimitExceeded = (method: string, path: string, ip: string): boolean => {
+  const configKey = TABLES_RATE_LIMIT_CONFIGS[`${method}:${path}`]
+    ? `${method}:${path}`
+    : `${method}:/api/tables/*`
+
+  const config = TABLES_RATE_LIMIT_CONFIGS[configKey]
+  if (!config) return false
+
+  return getTablesRecentRequests(method, path, ip).length >= config.maxRequests
+}
+
+/**
+ * Record a request for table endpoint rate limiting
+ */
+export const recordTablesRateLimitRequest = (
+  method: string,
+  path: string,
+  ip: string
+): readonly number[] => {
+  const recentRequests = getTablesRecentRequests(method, path, ip)
+  const now = Date.now()
+  const key = getTablesRateLimitKey(method, path, ip)
+  const updated = [...recentRequests, now]
+  // eslint-disable-next-line functional/no-expression-statements, functional/immutable-data -- Rate limiting requires mutable state
+  tablesRateLimitState.set(key, updated)
+  return updated
+}
+
+/**
+ * Calculate seconds until rate limit window resets
+ */
+export const getTablesRateLimitRetryAfter = (method: string, path: string, ip: string): number => {
+  const recentRequests = getTablesRecentRequests(method, path, ip)
+  if (recentRequests.length === 0) return 0
+
+  const windowMs = getRateLimitWindowMs()
+  const oldestRequest = Math.min(...recentRequests)
+  const resetTime = oldestRequest + windowMs
+  const now = Date.now()
+  const retryAfterMs = Math.max(0, resetTime - now)
+
+  return Math.ceil(retryAfterMs / 1000) // Convert to seconds
+}
+
+/**
+ * Rate limiting configuration for activity API endpoints
+ * Moderate limits since activity logs can be polled frequently for real-time updates
+ */
+const getActivityRateLimitConfigs = (): Record<string, EndpointRateLimitConfig> => {
+  const windowMs = getRateLimitWindowMs()
+
+  return {
+    // List activity endpoint
+    'GET:/api/activity': {
+      windowMs,
+      maxRequests: 60, // 60 requests per window (polling for activity updates)
+    },
+    // Get activity detail endpoint
+    'GET:/api/activity/*': {
+      windowMs,
+      maxRequests: 60, // 60 requests per window (activity log detail fetching)
+    },
+  }
+}
+
+const ACTIVITY_RATE_LIMIT_CONFIGS: Record<string, EndpointRateLimitConfig> =
+  getActivityRateLimitConfigs()
+
+/**
+ * Rate limiting state for activity endpoints
+ * Maps method:endpoint + IP to request timestamps
+ */
+const activityRateLimitState = new Map<string, number[]>()
+
+/**
+ * Get rate limit key for activity endpoint (includes HTTP method)
+ */
+const getActivityRateLimitKey = (method: string, path: string, ip: string): string => {
+  const configKey = ACTIVITY_RATE_LIMIT_CONFIGS[`${method}:${path}`]
+    ? `${method}:${path}`
+    : `${method}:/api/activity/*`
+
+  return `${configKey}:${ip}`
+}
+
+/**
+ * Get recent requests for activity endpoint
+ */
+export const getActivityRecentRequests = (
+  method: string,
+  path: string,
+  ip: string
+): readonly number[] => {
+  const configKey = ACTIVITY_RATE_LIMIT_CONFIGS[`${method}:${path}`]
+    ? `${method}:${path}`
+    : `${method}:/api/activity/*`
+
+  const config = ACTIVITY_RATE_LIMIT_CONFIGS[configKey]
+  if (!config) return []
+
+  const now = Date.now()
+  const key = getActivityRateLimitKey(method, path, ip)
+  const requestHistory = activityRateLimitState.get(key) ?? []
+  return requestHistory.filter((timestamp) => now - timestamp < config.windowMs)
+}
+
+/**
+ * Check if activity endpoint rate limit is exceeded
+ */
+export const isActivityRateLimitExceeded = (method: string, path: string, ip: string): boolean => {
+  const configKey = ACTIVITY_RATE_LIMIT_CONFIGS[`${method}:${path}`]
+    ? `${method}:${path}`
+    : `${method}:/api/activity/*`
+
+  const config = ACTIVITY_RATE_LIMIT_CONFIGS[configKey]
+  if (!config) return false
+
+  return getActivityRecentRequests(method, path, ip).length >= config.maxRequests
+}
+
+/**
+ * Record a request for activity endpoint rate limiting
+ */
+export const recordActivityRateLimitRequest = (
+  method: string,
+  path: string,
+  ip: string
+): readonly number[] => {
+  const recentRequests = getActivityRecentRequests(method, path, ip)
+  const now = Date.now()
+  const key = getActivityRateLimitKey(method, path, ip)
+  const updated = [...recentRequests, now]
+  // eslint-disable-next-line functional/no-expression-statements, functional/immutable-data -- Rate limiting requires mutable state
+  activityRateLimitState.set(key, updated)
+  return updated
+}
+
+/**
+ * Calculate seconds until activity rate limit window resets
+ */
+export const getActivityRateLimitRetryAfter = (
+  method: string,
+  path: string,
+  ip: string
+): number => {
+  const recentRequests = getActivityRecentRequests(method, path, ip)
+  if (recentRequests.length === 0) return 0
+
+  const windowMs = getRateLimitWindowMs()
+  const oldestRequest = Math.min(...recentRequests)
+  const resetTime = oldestRequest + windowMs
+  const now = Date.now()
+  const retryAfterMs = Math.max(0, resetTime - now)
+
+  return Math.ceil(retryAfterMs / 1000) // Convert to seconds
+}

package/src/infrastructure/server/route-setup/auth-routes.ts

@@ -0,0 +1,245 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import { type Hono } from 'hono'
+import { cors } from 'hono/cors'
+import { createAuthInstance } from '@/infrastructure/auth/better-auth/auth'
+import { logError } from '@/infrastructure/logging/logger'
+import {
+  isRateLimitExceeded,
+  recordRateLimitRequest,
+  extractClientIp,
+  isAuthRateLimitExceeded,
+  recordAuthRateLimitRequest,
+  getAuthRateLimitRetryAfter,
+} from './auth-route-utils'
+import type { App } from '@/domain/models/app'
+
+/**
+ * Apply authentication check middleware for admin endpoints
+ *
+ * This middleware ensures authentication is checked BEFORE parameter validation,
+ * preventing information leakage through error responses (400/404/403 vs 401).
+ *
+ * Without this middleware, Better Auth's admin endpoints validate parameters first,
+ * allowing unauthenticated users to probe for valid user IDs by observing response codes.
+ *
+ * Returns a Hono app with authentication middleware applied
+ */
+const applyAuthCheckMiddleware = (
+  honoApp: Readonly<Hono>,
+  authInstance: Readonly<ReturnType<typeof createAuthInstance>>
+): Readonly<Hono> => {
+  return honoApp.use('/api/auth/admin/*', async (c, next) => {
+    try {
+      // Check if request has a valid session cookie
+      const session = await authInstance.api.getSession({
+        headers: c.req.raw.headers,
+      })
+
+      // Return 401 if no valid session (BEFORE any parameter validation)
+      if (!session) {
+        return c.json(
+          { success: false, message: 'Authentication required', code: 'UNAUTHORIZED' },
+          401
+        )
+      }
+
+      // Session exists - proceed to next handler
+      // eslint-disable-next-line functional/no-expression-statements -- Hono middleware requires calling next()
+      await next()
+    } catch (error) {
+      // If session check fails, return 401 (assume unauthenticated)
+      logError('[Auth Middleware] Session check error', error)
+      return c.json(
+        { success: false, message: 'Authentication required', code: 'UNAUTHORIZED' },
+        401
+      )
+    }
+  })
+}
+
+/**
+ * Apply rate limiting middleware for admin endpoints
+ * Returns a Hono app with rate limiting middleware applied
+ */
+const applyRateLimitMiddleware = (honoApp: Readonly<Hono>): Readonly<Hono> => {
+  return honoApp.use('/api/auth/admin/*', async (c, next) => {
+    const ip = extractClientIp(c.req.header('x-forwarded-for'))
+
+    if (isRateLimitExceeded(ip)) {
+      return c.json(
+        {
+          success: false,
+          message: 'Too many requests. Please try again later.',
+          code: 'RATE_LIMITED',
+        },
+        429
+      )
+    }
+
+    recordRateLimitRequest(ip) // eslint-disable-line functional/no-expression-statements -- Rate limiting state update
+
+    // eslint-disable-next-line functional/no-expression-statements -- Hono middleware requires calling next()
+    await next()
+  })
+}
+
+/**
+ * Apply rate limiting middleware for authentication endpoints
+ *
+ * Protects security-critical authentication endpoints from brute force attacks:
+ * - sign-in: 5 attempts per 60 seconds (prevent credential stuffing)
+ * - sign-up: 5 attempts per 60 seconds (prevent account creation abuse)
+ * - request-password-reset: 3 attempts per 60 seconds (prevent email enumeration)
+ *
+ * Returns a Hono app with rate limiting middleware applied
+ */
+const applyAuthRateLimitMiddleware = (honoApp: Readonly<Hono>): Readonly<Hono> => {
+  const endpoints = [
+    '/api/auth/sign-in/email',
+    '/api/auth/sign-up/email',
+    '/api/auth/request-password-reset',
+  ]
+
+  const result = endpoints.reduce((app, endpoint) => {
+    return app.use(endpoint, async (c, next) => {
+      const ip = extractClientIp(c.req.header('x-forwarded-for'))
+      const { path } = c.req
+
+      if (isAuthRateLimitExceeded(path, ip)) {
+        const retryAfter = getAuthRateLimitRetryAfter(path, ip)
+        return c.json(
+          {
+            success: false,
+            message: 'Too many requests. Please try again later.',
+            code: 'RATE_LIMITED',
+          },
+          429,
+          { 'Retry-After': retryAfter.toString() }
+        )
+      }
+
+      recordAuthRateLimitRequest(path, ip) // eslint-disable-line functional/no-expression-statements -- Rate limiting state update
+
+      // eslint-disable-next-line functional/no-expression-statements -- Hono middleware requires calling next()
+      await next()
+    })
+  }, honoApp)
+
+  return result
+}
+
+/**
+ * Setup CORS middleware for Better Auth endpoints
+ *
+ * Configures CORS to allow:
+ * - All localhost origins for development/testing
+ * - Credentials for cookie-based authentication
+ * - Common headers and methods
+ *
+ * If no auth configuration is provided in the app, middleware is not applied.
+ *
+ * @param honoApp - Hono application instance
+ * @param app - Application configuration with auth settings
+ * @returns Hono app with CORS middleware configured (or unchanged if auth is disabled)
+ */
+export function setupAuthMiddleware(honoApp: Readonly<Hono>, app?: App): Readonly<Hono> {
+  // If no auth config is provided, don't apply CORS middleware
+  if (!app?.auth) {
+    return honoApp
+  }
+
+  return honoApp.use(
+    '/api/auth/*',
+    cors({
+      origin: (origin) => {
+        // Allow all localhost origins for development and testing
+        if (origin.startsWith('http://localhost:') || origin.startsWith('http://127.0.0.1:')) {
+          return origin
+        }
+        // In production, this should be configured with specific allowed origins
+        return origin
+      },
+      allowHeaders: ['Content-Type', 'Authorization'],
+      allowMethods: ['POST', 'GET', 'OPTIONS'],
+      exposeHeaders: ['Content-Length'],
+      maxAge: 600,
+      credentials: true, // Required for cookie-based authentication
+    })
+  )
+}
+
+/**
+ * Setup Better Auth routes with dynamic configuration
+ *
+ * Mounts Better Auth handler at /api/auth/* which provides all authentication endpoints.
+ *
+ * Creates a Better Auth instance dynamically based on the app's auth configuration,
+ * allowing features like requireEmailVerification to be controlled per app.
+ *
+ * IMPORTANT: Better Auth instance is created once per app configuration and reused
+ * across all requests to maintain internal state consistency.
+ *
+ * If no auth configuration is provided, no auth routes are registered and all
+ * /api/auth/* requests will return 404 Not Found.
+ *
+ * Better Auth natively provides:
+ * - Authentication: sign-up, sign-in, sign-out, verify-email, send-verification-email
+ * - Admin Plugin: list-users, get-user, set-role, ban-user, unban-user, impersonate-user, stop-impersonating
+ * - Organization Plugin: create-organization, list-organizations, get-organization, set-active-organization
+ * - Two-Factor: enable, disable, verify
+ * - Magic Link: send, verify
+ *
+ * Native Better Auth handles:
+ * - Banned user rejection (automatic in admin plugin)
+ * - Single-use verification tokens (automatic)
+ * - Admin role validation (via adminRoles/adminUserIds config)
+ * - Organization membership validation (automatic)
+ *
+ * @param honoApp - Hono application instance
+ * @param app - Application configuration with auth settings
+ * @returns Hono app with auth routes configured (or unchanged if auth is disabled)
+ */
+export function setupAuthRoutes(honoApp: Readonly<Hono>, app?: App): Readonly<Hono> {
+  // If no auth config is provided, don't register any auth routes
+  // This causes all /api/auth/* requests to return 404 (not found)
+  if (!app?.auth) {
+    return honoApp
+  }
+
+  // Create Better Auth instance with app-specific configuration (once per app startup)
+  // This instance is reused across all requests to maintain internal state
+  const authInstance = createAuthInstance(app.auth)
+
+  // Apply authentication check middleware (admin features always enabled when auth is configured)
+  // This ensures 401 is returned before any parameter validation, preventing information leakage
+  const appWithAuthCheck = applyAuthCheckMiddleware(honoApp, authInstance)
+
+  // Apply rate limiting middleware to admin routes
+  const appWithAdminRateLimit = applyRateLimitMiddleware(appWithAuthCheck)
+
+  // Apply rate limiting middleware to authentication endpoints (sign-in, sign-up, password reset)
+  const appWithAuthRateLimit = applyAuthRateLimitMiddleware(appWithAdminRateLimit)
+
+  // Mount Better Auth handler for all /api/auth/* routes
+  // Better Auth natively handles:
+  // - Authentication flows (sign-up, sign-in, sign-out, email verification)
+  // - Admin operations (list-users, get-user, set-role, ban-user, impersonation)
+  // - Organization management (create, list, get, set-active, invite members)
+  // - Two-factor authentication (enable, disable, verify)
+  // - Magic link authentication (send, verify)
+  // - Banned user rejection (automatic for admin plugin)
+  // - Single-use verification tokens (automatic)
+  // - Team operations (create-team, add-team-member, etc.) when teams plugin enabled
+  //
+  // IMPORTANT: Better Auth handles its own routing and expects the FULL request path
+  // including the /api/auth prefix. We pass the original request without modification.
+  return appWithAuthRateLimit.on(['POST', 'GET'], '/api/auth/*', async (c) => {
+    return authInstance.handler(c.req.raw)
+  })
+}

package/src/infrastructure/server/route-setup/openapi-routes.ts

@@ -0,0 +1,45 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import { Scalar } from '@scalar/hono-api-reference'
+import { type Hono } from 'hono'
+import { auth } from '@/infrastructure/auth/better-auth/auth'
+import { getOpenAPIDocument } from '@/infrastructure/server/route-setup/openapi-schema'
+
+/**
+ * Setup OpenAPI documentation routes
+ *
+ * Mounts:
+ * - GET /api/openapi.json - Application API schema
+ * - GET /api/auth/openapi.json - Better Auth API schema
+ * - GET /api/scalar - Unified Scalar API documentation UI
+ *
+ * @param honoApp - Hono application instance
+ * @returns Hono app with OpenAPI routes configured
+ */
+export function setupOpenApiRoutes(honoApp: Readonly<Hono>): Readonly<Hono> {
+  return honoApp
+    .get('/api/openapi.json', (c) => {
+      const openApiDoc = getOpenAPIDocument()
+      return c.json(openApiDoc)
+    })
+    .get('/api/auth/openapi.json', async (c) => {
+      const authOpenApiDoc = await auth.api.generateOpenAPISchema()
+      return c.json(authOpenApiDoc)
+    })
+    .get(
+      '/api/scalar',
+      Scalar({
+        pageTitle: 'Sovrium API Documentation',
+        theme: 'default',
+        sources: [
+          { url: '/api/openapi.json', title: 'API' },
+          { url: '/api/auth/openapi.json', title: 'Auth' },
+        ],
+      })
+    )
+}