sovrium 0.0.2

package/src/presentation/api/client.ts

@@ -0,0 +1,114 @@
+/**
+ * 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 { hc } from 'hono/client'
+import type { ApiType } from '@/infrastructure/server/route-setup/api-routes'
+
+/**
+ * Hono RPC Client Factory
+ *
+ * Creates a fully typed API client for making requests to the Sovrium API.
+ * The client provides:
+ * - Full TypeScript autocomplete for all endpoints
+ * - Type-safe request parameters and response data
+ * - Automatic URL construction
+ * - Native fetch-based implementation
+ *
+ * **Benefits of Hono RPC**:
+ * - Zero code generation - types extracted directly from server routes
+ * - No OpenAPI client generation step required
+ * - Real-time type safety - changes to server routes immediately reflected
+ * - Minimal bundle size - uses native fetch
+ *
+ * @param baseUrl - Base URL of the API server (e.g., 'http://localhost:3000')
+ * @returns Typed RPC client for making API requests
+ *
+ * @example
+ * Basic usage:
+ * ```typescript
+ * import { createApiClient } from '@/presentation/api/client'
+ *
+ * const client = createApiClient('http://localhost:3000')
+ *
+ * // GET /api/health - fully typed!
+ * const res = await client.api.health.$get()
+ * const data = await res.json()
+ * // data is typed as HealthResponse { status: 'ok', timestamp: string, app: { name: string } }
+ * console.log(data.status) // 'ok'
+ * ```
+ *
+ * @example
+ * With error handling:
+ * ```typescript
+ * const client = createApiClient('http://localhost:3000')
+ *
+ * try {
+ *   const res = await client.api.health.$get()
+ *
+ *   if (!res.ok) {
+ *     throw new Error(`HTTP ${res.status}: ${res.statusText}`)
+ *   }
+ *
+ *   const data = await res.json()
+ *   console.log('Health check:', data)
+ * } catch (error) {
+ *   console.error('Health check failed:', error)
+ * }
+ * ```
+ *
+ * @example
+ * Future usage with path parameters (when tables API is implemented):
+ * ```typescript
+ * // GET /api/tables/:id
+ * const res = await client.api.tables[':id'].$get({
+ *   param: { id: '123' }
+ * })
+ * const table = await res.json()
+ *
+ * // POST /api/tables/:id/records
+ * const res = await client.api.tables[':id'].records.$post({
+ *   param: { id: '123' },
+ *   json: { name: 'John', email: 'john@example.com' }
+ * })
+ * const record = await res.json()
+ * ```
+ *
+ * @example
+ * Using in React components with TanStack Query:
+ * ```typescript
+ * import { useQuery } from '@tanstack/react-query'
+ * import { createApiClient } from '@/presentation/api/client'
+ *
+ * const client = createApiClient('http://localhost:3000')
+ *
+ * function HealthStatus() {
+ *   const { data, isLoading, error } = useQuery({
+ *     queryKey: ['health'],
+ *     queryFn: async () => {
+ *       const res = await client.api.health.$get()
+ *       if (!res.ok) throw new Error('Health check failed')
+ *       return res.json()
+ *     }
+ *   })
+ *
+ *   if (isLoading) return <div>Loading...</div>
+ *   if (error) return <div>Error: {error.message}</div>
+ *
+ *   return <div>Status: {data?.status}</div>
+ * }
+ * ```
+ */
+export const createApiClient = (baseUrl: string) => {
+  return hc<ApiType>(baseUrl)
+}
+
+/**
+ * Re-export ApiType for convenience
+ *
+ * Allows consumers to import both the client and type from the same file.
+ */
+export type { ApiType }

package/src/presentation/api/middleware/auth.ts

@@ -0,0 +1,233 @@
+/**
+ * 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 { logError, logWarning } from '@/infrastructure/logging/logger'
+import type { Session } from '@/application/ports/models/user-session'
+import type { Context, Next } from 'hono'
+
+/**
+ * Minimal Better Auth instance interface
+ *
+ * Typed to the subset of the Better Auth API actually used by the middleware.
+ * Better Auth's full type varies by configuration (plugins, providers)
+ * and uses optional fields (ipAddress?) that conflict with our Session type
+ * (ipAddress: string | null), so getSession returns Promise<unknown>.
+ * The middleware handles extraction with runtime checks and explicit casts.
+ */
+interface BetterAuthLike {
+  readonly api: {
+    readonly getSession: (options: { readonly headers: Headers }) => Promise<unknown>
+  }
+}
+
+/**
+ * Hono context with session attached
+ *
+ * Used by auth middleware to store extracted session for route handlers
+ */
+export type ContextWithSession = Context & {
+  readonly var: {
+    readonly session?: Session
+  }
+}
+
+/**
+ * Extract client IP address from request headers
+ *
+ * Checks common proxy headers in priority order:
+ * 1. X-Forwarded-For (most common)
+ * 2. X-Real-IP (nginx)
+ * 3. CF-Connecting-IP (Cloudflare)
+ * 4. Falls back to direct connection IP
+ */
+function getClientIP(c: Context): string | undefined {
+  const xForwardedFor = c.req.header('x-forwarded-for')
+  if (xForwardedFor) {
+    // X-Forwarded-For can contain multiple IPs, take the first one (client)
+    return xForwardedFor.split(',')[0]?.trim()
+  }
+
+  const xRealIp = c.req.header('x-real-ip')
+  if (xRealIp) {
+    return xRealIp
+  }
+
+  const cfConnectingIp = c.req.header('cf-connecting-ip')
+  if (cfConnectingIp) {
+    return cfConnectingIp
+  }
+
+  // Fallback to undefined if no IP headers found
+  return undefined
+}
+
+/**
+ * Validate session binding to original IP and User-Agent
+ *
+ * When strict mode is enabled, sessions are bound to the IP address and
+ * User-Agent that created them. This prevents session hijacking attacks.
+ *
+ * @param session - Session object from database
+ * @param currentIP - Current request IP address
+ * @param currentUserAgent - Current request User-Agent
+ * @returns true if session is valid, false if binding validation fails
+ */
+function validateSessionBinding(
+  session: Session,
+  currentIP: string | undefined,
+  currentUserAgent: string | undefined
+): boolean {
+  // For now, allow sessions without binding metadata (backward compatibility)
+  // This will be tightened when strict mode is explicitly enabled
+  if (!session.ipAddress && !session.userAgent) {
+    return true
+  }
+
+  // If session has IP binding, validate it matches
+  if (session.ipAddress && currentIP && session.ipAddress !== currentIP) {
+    return false
+  }
+
+  // If session has User-Agent binding, validate it matches
+  if (session.userAgent && currentUserAgent && session.userAgent !== currentUserAgent) {
+    return false
+  }
+
+  return true
+}
+
+/**
+ * Process session result and attach to context if valid
+ *
+ * Validates session binding and logs security warnings for failed validations.
+ */
+function processSessionResult(
+  c: Context,
+  sessionResult: { readonly session?: Session } | null
+): void {
+  if (!sessionResult?.session) {
+    return
+  }
+
+  const currentIP = getClientIP(c)
+  const currentUserAgent = c.req.header('user-agent')
+
+  if (validateSessionBinding(sessionResult.session as Session, currentIP, currentUserAgent)) {
+    c.set('session', sessionResult.session as Session)
+  } else {
+    // Session binding validation failed - log for security monitoring
+    logWarning(
+      `[AUTH] Session binding validation failed: ${JSON.stringify({
+        sessionId: sessionResult.session.id,
+        expectedIP: sessionResult.session.ipAddress,
+        currentIP,
+        expectedUserAgent: sessionResult.session.userAgent,
+        currentUserAgent,
+      })}`
+    )
+  }
+}
+
+/**
+ * Auth middleware for Hono routes
+ *
+ * Extracts Better Auth session from request and attaches to context.
+ * Routes can access session via `c.var.session`.
+ *
+ * **Session Extraction Strategy**:
+ * 1. Check for Authorization header (Bearer token)
+ * 2. Query Better Auth session table to validate token
+ * 3. Validate session binding (IP/User-Agent) if strict mode enabled
+ * 4. Attach session to context if valid
+ * 5. Continue to route handler (session may be undefined for public routes)
+ *
+ * **Session Binding (Strict Mode)**:
+ * When enabled, sessions are bound to the IP address and User-Agent that
+ * created them. Requests from different IP/User-Agent will be rejected.
+ *
+ * **Usage**:
+ * ```typescript
+ * app.use('/api/tables/*', authMiddleware(auth))
+ * app.get('/api/tables/:id', async (c) => {
+ *   const session = c.var.session
+ *   if (!session) return c.json({ error: 'Unauthorized' }, 401)
+ *   // Use session for database queries
+ * })
+ * ```
+ *
+ * @param auth - Better Auth instance with api.getSession method
+ * @returns Hono middleware function
+ */
+export function authMiddleware(auth: BetterAuthLike) {
+  return async (c: Context, next: Next) => {
+    try {
+      const authHeader = c.req.header('authorization')
+
+      if (authHeader?.toLowerCase().startsWith('bearer ')) {
+        const apiKey = authHeader.slice(7)
+        const result = (await auth.api.getSession({
+          headers: new Headers({ authorization: apiKey }),
+        })) as { readonly session?: Session } | null
+        processSessionResult(c, result)
+      } else {
+        const result = (await auth.api.getSession({
+          headers: c.req.raw.headers,
+        })) as { readonly session?: Session } | null
+        processSessionResult(c, result)
+      }
+    } catch (error) {
+      logError('[AUTH] Session extraction failed', error)
+    }
+
+    // eslint-disable-next-line functional/no-expression-statements -- Required for middleware to continue to next handler
+    await next()
+  }
+}
+
+/**
+ * Middleware handler for requiring authentication
+ */
+async function requireAuthHandler(c: ContextWithSession, next: Next) {
+  const { session } = c.var
+
+  if (!session) {
+    return c.json(
+      {
+        success: false,
+        error: 'Unauthorized',
+        message: 'Authentication required',
+        code: 'UNAUTHORIZED',
+      },
+      401
+    )
+  }
+
+  // eslint-disable-next-line functional/no-expression-statements -- Required for middleware to continue to next handler
+  await next()
+}
+
+/**
+ * Require authentication middleware
+ *
+ * Returns 401 if session is not present.
+ * Use this for protected routes that require authentication.
+ *
+ * **Usage**:
+ * ```typescript
+ * app.use('/api/tables/*', authMiddleware(auth))
+ * app.use('/api/tables/*', requireAuth())
+ * app.get('/api/tables/:id', async (c) => {
+ *   const session = c.var.session! // Safe to use non-null assertion
+ *   // Session is guaranteed to exist
+ * })
+ * ```
+ *
+ * @returns Hono middleware function
+ */
+export function requireAuth() {
+  return requireAuthHandler
+}

package/src/presentation/api/middleware/table.ts

@@ -0,0 +1,155 @@
+/**
+ * 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 { getUserRole } from '@/application/use-cases/tables/user-role'
+import type { ContextWithSession } from './auth'
+import type { Session } from '@/application/ports/models/user-session'
+import type { App } from '@/domain/models/app'
+import type { Context, Next } from 'hono'
+
+// ============================================================================
+// Extended Context Types
+// ============================================================================
+
+/**
+ * Hono context with validated table information attached
+ *
+ * Available after `validateTable()` middleware runs.
+ */
+export type ContextWithValidatedTable = ContextWithSession & {
+  readonly var: {
+    readonly tableName: string
+    readonly tableId: string
+  }
+}
+
+/**
+ * Hono context with user role attached
+ *
+ * Available after `enrichUserRole()` middleware runs.
+ * Requires session to exist (use after `requireAuth()`).
+ */
+export type ContextWithUserRole = ContextWithSession & {
+  readonly var: {
+    readonly userRole: string
+  }
+}
+
+/**
+ * Combined context with session, validated table, and user role
+ *
+ * Available after full middleware chain:
+ * `authMiddleware` → `requireAuth` → `validateTable` → `enrichUserRole`
+ *
+ * **Session is guaranteed to exist** because `requireAuth()` rejects
+ * requests without a valid session.
+ */
+export type ContextWithTableAndRole = Context & {
+  readonly var: {
+    readonly session: Session // Non-optional - guaranteed by requireAuth()
+    readonly tableName: string
+    readonly tableId: string
+    readonly userRole: string
+  }
+}
+
+// ============================================================================
+// Middleware Functions
+// ============================================================================
+
+/**
+ * Middleware to validate table exists and resolve table name
+ *
+ * Extracts :tableId param, validates table exists in app schema,
+ * and attaches resolved table name to context.
+ *
+ * **Context Variables Set**:
+ * - `tableName`: The resolved table name
+ * - `tableId`: The original tableId parameter
+ *
+ * **Usage**:
+ * ```typescript
+ * app.use('/api/tables/:tableId/*', validateTable(app))
+ * app.get('/api/tables/:tableId/records', (c: ContextWithValidatedTable) => {
+ *   const { tableName } = c.var  // Already validated!
+ * })
+ * ```
+ *
+ * @param app - Application configuration containing table definitions
+ * @returns Hono middleware function
+ */
+export function validateTable(app: App) {
+  return async (c: Context, next: Next) => {
+    const tableId = c.req.param('tableId')
+
+    if (!tableId) {
+      return c.json(
+        { success: false, message: 'Table ID parameter required', code: 'VALIDATION_ERROR' },
+        400
+      )
+    }
+
+    const table = app.tables?.find((t) => String(t.id) === tableId || t.name === tableId)
+
+    if (!table) {
+      return c.json({ success: false, message: 'Resource not found', code: 'NOT_FOUND' }, 404)
+    }
+
+    // Attach to context for downstream handlers
+    c.set('tableName', table.name)
+    c.set('tableId', tableId)
+
+    // eslint-disable-next-line functional/no-expression-statements -- Required for middleware to continue
+    await next()
+  }
+}
+
+/**
+ * Middleware to enrich context with user role
+ *
+ * Fetches user role from database and attaches to context.
+ * Requires session to exist (use after `requireAuth()` middleware).
+ *
+ * **Context Variables Set**:
+ * - `userRole`: The user's role in the organization
+ *
+ * **Usage**:
+ * ```typescript
+ * app.use('/api/tables/*', authMiddleware(auth))
+ * app.use('/api/tables/*', requireAuth())
+ * app.use('/api/tables/:tableId/*', enrichUserRole())
+ * app.get('/api/tables/:tableId/records', (c: ContextWithUserRole) => {
+ *   const { userRole } = c.var  // Already fetched!
+ * })
+ * ```
+ *
+ * @param getUserRoleFn - Optional function to resolve user role (for unit tests).
+ *   Defaults to the real getUserRole from application layer.
+ * @returns Hono middleware function
+ */
+export function enrichUserRole(getUserRoleFn?: (userId: string) => Promise<string>) {
+  const resolveRole = getUserRoleFn ?? getUserRole
+
+  return async (c: Context, next: Next) => {
+    const { session } = (c as ContextWithSession).var
+
+    // Defensive check (should not happen if requireAuth() used before)
+    if (!session) {
+      return c.json(
+        { success: false, message: 'Authentication required', code: 'UNAUTHORIZED' },
+        401
+      )
+    }
+
+    const userRole = await resolveRole(session.userId)
+
+    c.set('userRole', userRole)
+
+    // eslint-disable-next-line functional/no-expression-statements -- Required for middleware to continue
+    await next()
+  }
+}

package/src/presentation/api/middleware/validation.ts

@@ -0,0 +1,88 @@
+/**
+ * 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 { Context, Layer } from 'effect'
+import type { App } from '@/domain/models/app'
+import type { Effect } from 'effect'
+import type { Context as HonoContext } from 'hono'
+
+/**
+ * Validation error types
+ */
+export class ValidationError {
+  readonly _tag = 'ValidationError'
+  constructor(
+    readonly message: string,
+    readonly field?: string
+  ) {}
+}
+
+export class PermissionError {
+  readonly _tag = 'PermissionError'
+  constructor(
+    readonly message: string,
+    readonly field?: string
+  ) {}
+}
+
+/**
+ * Validation context - provides app configuration and request context
+ */
+export class ValidationContext extends Context.Tag('ValidationContext')<
+  ValidationContext,
+  {
+    readonly app: App
+    readonly tableName: string
+    readonly userRole: string
+  }
+>() {}
+
+/**
+ * Validation result type
+ */
+export type ValidationResult<T> = Effect.Effect<T, ValidationError | PermissionError, never>
+
+/**
+ * Create a validation layer from app, tableName, and userRole
+ */
+export function createValidationLayer(app: App, tableName: string, userRole: string) {
+  return Layer.succeed(ValidationContext, {
+    app,
+    tableName,
+    userRole,
+  })
+}
+
+/**
+ * Validation error response helper
+ */
+export function formatValidationError(
+  error: ValidationError | PermissionError,
+  c: HonoContext
+): Response {
+  if (error._tag === 'ValidationError') {
+    return c.json(
+      {
+        success: false,
+        message: error.message,
+        code: 'VALIDATION_ERROR',
+        ...(error.field ? { field: error.field } : {}),
+      },
+      400
+    )
+  }
+
+  return c.json(
+    {
+      success: false,
+      message: error.message,
+      code: 'FORBIDDEN',
+      ...(error.field ? { field: error.field } : {}),
+    },
+    403
+  )
+}

package/src/presentation/api/routes/activity/get-activity-by-id-handler.ts

@@ -0,0 +1,77 @@
+/**
+ * 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 { Effect } from 'effect'
+import { GetActivityById } from '@/application/use-cases/activity/programs'
+import { DatabaseLive } from '@/infrastructure/database'
+import type { Context } from 'hono'
+
+/**
+ * GET /api/activity/:activityId handler
+ *
+ * Fetches activity log details by ID with user metadata.
+ *
+ * **Authentication**: Requires authenticated session
+ * **Authorization**: All authenticated users can view activity logs
+ *
+ * **Response Structure**:
+ * - 200: Activity details with user metadata
+ * - 400: Invalid activity ID format
+ * - 401: Unauthorized (no session)
+ * - 404: Activity not found
+ *
+ * @param c - Hono context
+ * @returns JSON response with activity details or error
+ */
+export async function getActivityByIdHandler(c: Context) {
+  const activityId = c.req.param('activityId')
+
+  const program = GetActivityById(activityId).pipe(Effect.provide(DatabaseLive))
+
+  const result = await Effect.runPromise(program.pipe(Effect.either))
+
+  if (result._tag === 'Left') {
+    const error = result.left
+
+    // Handle specific error types
+    if (error._tag === 'InvalidActivityIdError') {
+      return c.json(
+        {
+          success: false,
+          message: 'Invalid activity ID format',
+          code: 'INVALID_ACTIVITY_ID',
+        },
+        400
+      )
+    }
+
+    if (error._tag === 'ActivityNotFoundError') {
+      return c.json(
+        {
+          success: false,
+          message: 'Activity not found',
+          code: 'ACTIVITY_NOT_FOUND',
+        },
+        404
+      )
+    }
+
+    // Database error
+    return c.json(
+      {
+        success: false,
+        message: 'Failed to fetch activity',
+        code: 'DATABASE_ERROR',
+      },
+      500
+    )
+  }
+
+  const activity = result.right
+
+  return c.json(activity, 200)
+}

package/src/presentation/api/routes/activity/index.ts

@@ -0,0 +1,28 @@
+/**
+ * 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 { getActivityByIdHandler } from './get-activity-by-id-handler'
+import type { Hono } from 'hono'
+
+/**
+ * Chain activity routes onto a Hono app
+ *
+ * **Authentication Middleware** (applied in api-routes.ts):
+ * - All activity endpoints require authentication
+ * - Middleware chain: requireAuth() → Handler
+ * - Authentication is ALWAYS required, even when app.auth is not configured
+ *
+ * **Routes**:
+ * - GET /api/activity/:activityId - Get activity log details
+ *
+ * @param honoApp - Hono instance to chain routes onto
+ * @returns Hono app with activity routes chained
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- Hono type inference with middleware requires flexible typing
+export function chainActivityRoutes<T extends Hono<any, any, any>>(honoApp: T) {
+  return honoApp.get('/api/activity/:activityId', getActivityByIdHandler)
+}