sovrium 0.0.2

package/src/presentation/api/utils/context-helpers.ts

@@ -0,0 +1,43 @@
+/**
+ * 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 { Session } from '@/application/ports/models/user-session'
+import type { ContextWithSession } from '@/presentation/api/middleware/auth'
+import type { ContextWithTableAndRole } from '@/presentation/api/middleware/table'
+import type { Context } from 'hono'
+
+/**
+ * Extract session from context (optional session)
+ *
+ * Use for routes with authMiddleware but without requireAuth
+ *
+ * @param c - Hono context (after authMiddleware)
+ * @returns Session if authenticated, undefined otherwise
+ */
+export function getSessionContext(c: Context): Session | undefined {
+  return (c as ContextWithSession).var.session
+}
+
+/**
+ * Extract table context from request
+ *
+ * Use for routes with full middleware chain:
+ * authMiddleware → requireAuth → validateTable → enrichUserRole
+ *
+ * **Session is guaranteed to exist** (requireAuth ensures this)
+ *
+ * @param c - Hono context (after full middleware chain)
+ * @returns Object containing session, tableName, tableId, and userRole
+ */
+export function getTableContext(c: Context): {
+  readonly session: Session
+  readonly tableName: string
+  readonly tableId: string
+  readonly userRole: string
+} {
+  return (c as ContextWithTableAndRole).var
+}

package/src/presentation/api/utils/error-sanitizer.ts

@@ -0,0 +1,235 @@
+/**
+ * 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 { logDebug, logError } from '@/infrastructure/logging/logger'
+import type { ContentfulStatusCode } from 'hono/utils/http-status'
+
+/**
+ * Sanitized error codes for client responses
+ *
+ * These codes are safe to expose to clients and map to standard HTTP status codes.
+ */
+export type ErrorCode =
+  | 'UNAUTHORIZED'
+  | 'FORBIDDEN'
+  | 'NOT_FOUND'
+  | 'VALIDATION_ERROR'
+  | 'CONFLICT'
+  | 'RATE_LIMITED'
+  | 'INTERNAL_ERROR'
+  | 'SERVICE_UNAVAILABLE'
+
+/**
+ * Sanitized error response for clients
+ *
+ * This interface ensures that only safe, user-friendly error information
+ * is exposed to clients, preventing information disclosure vulnerabilities.
+ */
+export interface SanitizedError {
+  readonly error: string
+  readonly code: ErrorCode
+  readonly message?: string
+  readonly details?: readonly string[]
+}
+
+/**
+ * Check if error indicates "not found"
+ *
+ * Detects various patterns that indicate a resource was not found,
+ * including access denied cases (which we return as 404 to avoid
+ * leaking existence of protected resources).
+ */
+function isNotFoundError(error: unknown): boolean {
+  const errorMessage =
+    error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase()
+
+  return errorMessage.includes('not found') || errorMessage.includes('access denied')
+}
+
+/**
+ * Error object with dynamic properties
+ */
+interface ErrorObject {
+  readonly toJSON?: () => {
+    readonly cause?: {
+      readonly failure?: {
+        readonly _tag?: string
+        readonly message?: string
+        readonly details?: readonly string[]
+      }
+    }
+  }
+  readonly _tag?: string
+  readonly message?: string
+  readonly details?: readonly string[]
+}
+
+/**
+ * Log error details for debugging (server-side only)
+ */
+function logErrorDetails(error: unknown, requestId: string | undefined): void {
+  logError(`[API Error] requestId=${requestId}`, error)
+  logDebug(`[API Error - error type] ${typeof error}`)
+  logDebug(
+    `[API Error - error own keys] ${error && typeof error === 'object' ? Object.keys(error).join(', ') : 'not an object'}`
+  )
+  logDebug(
+    `[API Error - error all keys] ${error && typeof error === 'object' ? Object.getOwnPropertyNames(error).join(', ') : 'not an object'}`
+  )
+  const errObj = error as ErrorObject
+  logDebug(`[API Error - error _tag] ${errObj._tag}`)
+  logDebug(`[API Error - error message] ${errObj.message}`)
+  logDebug(`[API Error - error details] ${JSON.stringify(errObj.details)}`)
+}
+
+/**
+ * Extract actual error from Effect FiberFailure wrapper
+ */
+function extractActualError(error: unknown): ErrorObject {
+  const errorObj = error as ErrorObject
+
+  // Try to extract the error from FiberFailure via toJSON()
+  if (errorObj && typeof errorObj === 'object' && errorObj.toJSON) {
+    try {
+      const jsonRep = errorObj.toJSON()
+      if (jsonRep?.cause?.failure) {
+        const actualError = jsonRep.cause.failure
+        logDebug(
+          `[API Error - extracted from toJSON cause.failure] _tag=${actualError._tag} message=${actualError.message} details=${JSON.stringify(actualError.details)}`
+        )
+        return actualError
+      }
+    } catch (e) {
+      logDebug(`[API Error - toJSON extraction failed] ${e}`)
+    }
+  }
+
+  return errorObj
+}
+
+/**
+ * Map tagged error to sanitized response
+ */
+function mapTaggedError(errorTag: string, actualError: ErrorObject): SanitizedError | undefined {
+  switch (errorTag) {
+    case 'ForbiddenError':
+    case 'ActivityLogForbiddenError':
+      return {
+        error: 'Forbidden',
+        code: 'FORBIDDEN',
+        message: actualError.message,
+      }
+    case 'ValidationError':
+      return {
+        error: 'Validation Error',
+        code: 'VALIDATION_ERROR',
+        message: actualError.message ?? 'Invalid input data',
+        details: actualError.details,
+      }
+    case 'UniqueConstraintViolationError':
+      return {
+        error: 'Conflict',
+        code: 'CONFLICT',
+        message: 'Resource already exists',
+      }
+    case 'NotFoundError':
+    case 'TableNotFoundError':
+      return {
+        error: 'Not Found',
+        code: 'NOT_FOUND',
+        message: 'Resource not found',
+      }
+    default:
+      return undefined
+  }
+}
+
+/**
+ * Sanitize errors for client responses
+ *
+ * ✅ Removes internal details (file paths, SQL, stack traces, database schemas)
+ * ✅ Maps to generic error codes and user-safe messages
+ * ✅ Logs full error server-side for debugging
+ * ✅ Returns only information safe to expose to clients
+ *
+ * **Security Benefits:**
+ * - Prevents database schema discovery through constraint errors
+ * - Hides internal architecture (file paths, service URLs)
+ * - Conceals SQL query structure
+ * - Protects authorization logic details
+ *
+ * @param error - The error to sanitize
+ * @param requestId - Optional request ID for correlation in logs
+ * @returns Sanitized error safe for client consumption
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await dangerousOperation()
+ * } catch (error) {
+ *   const sanitized = sanitizeError(error, requestId)
+ *   return c.json(sanitized, getStatusCode(sanitized.code))
+ * }
+ * ```
+ */
+export function sanitizeError(error: unknown, requestId?: string): SanitizedError {
+  logErrorDetails(error, requestId)
+
+  const actualError = extractActualError(error)
+  const errorTag = actualError._tag
+
+  // Handle known safe error types
+  if (errorTag) {
+    const sanitized = mapTaggedError(errorTag, actualError)
+    if (sanitized) return sanitized
+  }
+
+  // Check for not-found patterns (includes access denied to avoid leaking existence)
+  if (isNotFoundError(error)) {
+    return {
+      error: 'Not Found',
+      code: 'NOT_FOUND',
+      message: 'Resource not found',
+    }
+  }
+
+  // Generic internal error (no details leaked to prevent information disclosure)
+  return {
+    error: 'Internal Server Error',
+    code: 'INTERNAL_ERROR',
+    message: 'An unexpected error occurred. Please try again later.',
+  }
+}
+
+/**
+ * Get HTTP status code for error code
+ *
+ * Maps sanitized error codes to appropriate HTTP status codes.
+ *
+ * @param code - The error code
+ * @returns HTTP status code
+ */
+export function getStatusCode(code: ErrorCode): ContentfulStatusCode {
+  switch (code) {
+    case 'UNAUTHORIZED':
+      return 401
+    case 'FORBIDDEN':
+      return 403
+    case 'NOT_FOUND':
+      return 404
+    case 'VALIDATION_ERROR':
+      return 400
+    case 'CONFLICT':
+      return 409
+    case 'RATE_LIMITED':
+      return 429
+    case 'INTERNAL_ERROR':
+      return 500
+    case 'SERVICE_UNAVAILABLE':
+      return 503
+  }
+}

package/src/presentation/api/utils/field-permission-validator.ts

@@ -0,0 +1,53 @@
+/**
+ * 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 { hasPermission } from '@/domain/models/app/table/permissions'
+import type { App } from '@/domain/models/app'
+
+/**
+ * Check if user has permission to write to specific fields
+ *
+ * This implements Better Auth layer field permission validation.
+ * Returns forbidden fields that the user cannot write to.
+ *
+ * @param app - Application configuration
+ * @param tableName - Name of the table
+ * @param userRole - User's role
+ * @param fields - Fields being updated
+ * @returns Array of field names user cannot write to (empty if all allowed)
+ */
+export function validateFieldWritePermissions(
+  app: App,
+  tableName: string,
+  userRole: string,
+  fields: Readonly<Record<string, unknown>>
+): readonly string[] {
+  // Find table definition
+  const table = app.tables?.find((t) => t.name === tableName)
+  if (!table) {
+    return []
+  }
+
+  // Check each field being updated using functional approach
+  const forbiddenFields = Object.keys(fields)
+    .map((fieldName) => {
+      // Check explicit field permissions first
+      const fieldPermission = table.permissions?.fields?.find((fp) => fp.field === fieldName)
+      if (fieldPermission?.write) {
+        if (!hasPermission(fieldPermission.write, userRole)) {
+          return fieldName
+        }
+        return undefined
+      }
+
+      // No explicit field permission configured — field is writable by all roles
+      return undefined
+    })
+    .filter((field): field is string => field !== undefined)
+
+  return forbiddenFields
+}

package/src/presentation/api/utils/filter-field-validator.ts

@@ -0,0 +1,90 @@
+/**
+ * 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 { App } from '@/domain/models/app'
+import type { TablePermission } from '@/domain/models/app/table/permissions'
+
+/**
+ * Filter condition with field reference
+ */
+interface FilterCondition {
+  readonly field: string
+  readonly operator: string
+  readonly value: unknown
+}
+
+/**
+ * Filter structure supporting AND/OR logic
+ */
+interface Filter {
+  readonly and?: readonly FilterCondition[]
+  readonly or?: readonly FilterCondition[]
+}
+
+/**
+ * Validate that user has permission to filter by specified fields
+ *
+ * This prevents users from querying data based on fields they cannot read.
+ * Returns array of field names user cannot filter by.
+ *
+ * @param app - Application configuration
+ * @param tableName - Name of the table
+ * @param userRole - User's role
+ * @param filter - Filter object to validate
+ * @returns Array of field names user cannot filter by (empty if all allowed)
+ */
+export function validateFilterFieldPermissions(
+  app: App,
+  tableName: string,
+  userRole: string,
+  filter: Filter
+): readonly string[] {
+  // Find table definition
+  const table = app.tables?.find((t) => t.name === tableName)
+  if (!table?.permissions?.fields) {
+    return [] // No field permissions defined
+  }
+
+  // Extract all field names from filter conditions using immutable patterns
+  const andFields = filter.and ? filter.and.map((condition) => condition.field) : []
+  const orFields = filter.or ? filter.or.map((condition) => condition.field) : []
+  const fieldNames = [...andFields, ...orFields]
+
+  // Check each field used in filter
+  const forbiddenFields = fieldNames
+    .map((fieldName) => {
+      const fieldPermission = table.permissions?.fields?.find((fp) => fp.field === fieldName)
+      if (!fieldPermission?.read) {
+        return undefined // No read restriction on this field
+      }
+
+      if (!hasReadPermission(fieldPermission.read, userRole)) {
+        return fieldName
+      }
+
+      return undefined
+    })
+    .filter((field): field is string => field !== undefined)
+
+  return forbiddenFields
+}
+
+/**
+ * Check if user's role has read permission
+ */
+function hasReadPermission(permission: TablePermission, userRole: string): boolean {
+  if (permission === 'all') {
+    return true
+  }
+  if (permission === 'authenticated') {
+    return true // User is authenticated (has session)
+  }
+  if (Array.isArray(permission)) {
+    return permission.includes(userRole)
+  }
+  return false
+}

package/src/presentation/api/utils/index.ts

@@ -0,0 +1,13 @@
+/**
+ * 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.
+ */
+
+/**
+ * API Utility Exports
+ */
+
+export { runEffect } from './run-effect'
+export { validateRequest } from './validate-request'

package/src/presentation/api/utils/run-effect.ts

@@ -0,0 +1,94 @@
+/**
+ * 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 { errorResponseSchema } from '@/domain/models/api/error'
+import { sanitizeError, getStatusCode } from './error-sanitizer'
+import type { Context } from 'hono'
+import type { ContentfulStatusCode } from 'hono/utils/http-status'
+
+/**
+ * Schema interface for Zod-compatible parsing
+ */
+interface ParseableSchema<T> {
+  readonly parse: (data: unknown) => T
+}
+
+/**
+ * Handle error response generation
+ *
+ * Uses centralized error sanitization to prevent information disclosure.
+ * Removes internal details (file paths, SQL errors, stack traces) from client responses.
+ */
+function handleErrorResponse(c: Context, error: unknown) {
+  // Generate unique request ID for error correlation
+  const requestId = crypto.randomUUID()
+
+  // Sanitize error (removes internal details, logs full error server-side)
+  const sanitized = sanitizeError(error, requestId)
+  const statusCode = getStatusCode(sanitized.code)
+
+  const errorData = {
+    success: false as const,
+    error: sanitized.error,
+    message: sanitized.message ?? sanitized.error,
+    code: sanitized.code,
+    ...(sanitized.details ? { details: sanitized.details } : {}),
+  }
+
+  return c.json(errorResponseSchema.parse(errorData), statusCode)
+}
+
+/**
+ * Run an Effect program and return a Hono JSON response
+ *
+ * This utility handles:
+ * - Running Effect programs as promises
+ * - Validating responses against Zod schemas
+ * - Converting errors to standardized error responses
+ *
+ * @param c - Hono context for response generation
+ * @param program - Effect program to execute
+ * @param schema - Zod schema for response validation
+ * @param successStatus - HTTP status code for successful response (default: 200)
+ * @returns JSON response with validated data or error
+ *
+ * @example
+ * ```typescript
+ * app.get('/api/users', async (c) =>
+ *   runEffect(c, listUsersProgram(), listUsersResponseSchema)
+ * )
+ * app.post('/api/users', async (c) =>
+ *   runEffect(c, createUserProgram(), createUserResponseSchema, 201)
+ * )
+ * ```
+ */
+export async function runEffect<T, S>(
+  c: Context,
+  program: Effect.Effect<T, Error>,
+  schema?: ParseableSchema<S>,
+  successStatus: number = 200
+) {
+  try {
+    // Use Effect.either to preserve tagged error types (_tag property)
+    // Effect.runPromise wraps errors in FiberFailure which strips _tag,
+    // preventing error sanitizer from mapping to correct HTTP status codes.
+    // Effect.either converts failures to Either.Left, preserving the original error.
+    const either = await Effect.runPromise(Effect.either(program))
+
+    if (either._tag === 'Left') {
+      return handleErrorResponse(c, either.left)
+    }
+
+    const validated = schema ? schema.parse(either.right) : either.right
+    return c.json(validated, successStatus as ContentfulStatusCode)
+  } catch (error) {
+    // Catches defects (Effect.die), schema validation errors,
+    // and other unexpected runtime errors
+    return handleErrorResponse(c, error)
+  }
+}

package/src/presentation/api/utils/validate-request.ts

@@ -0,0 +1,89 @@
+/**
+ * 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 { z } from 'zod'
+import { validationErrorResponseSchema } from '@/domain/models/api/error'
+import type { Context, TypedResponse } from 'hono'
+
+/**
+ * Result type for validation - either success with data or error response
+ */
+export type ValidationResult<T> =
+  | { readonly success: true; readonly data: T }
+  | { readonly success: false; readonly response: TypedResponse<unknown> }
+
+/**
+ * Format Zod validation errors into API-friendly format
+ */
+const formatZodErrors = (error: z.ZodError) =>
+  error.issues.map((issue) => ({
+    field: issue.path.join('.'),
+    message: issue.message,
+    code: issue.code,
+  }))
+
+/**
+ * Validate request body against a Zod schema
+ *
+ * Returns validated data on success, or a formatted error response.
+ *
+ * @param c - Hono context
+ * @param schema - Zod schema to validate against
+ * @returns Validation result with data or error response
+ *
+ * @example
+ * ```typescript
+ * app.post('/api/records', async (c) => {
+ *   const result = await validateRequest(c, createRecordRequestSchema)
+ *   if (!result.success) return result.response
+ *   // result.data is fully typed and validated
+ * })
+ * ```
+ */
+export async function validateRequest<T>(
+  c: Context,
+  schema: z.ZodType<T>
+): Promise<ValidationResult<T>> {
+  try {
+    const rawBody = await c.req.json()
+    const data = schema.parse(rawBody)
+    return { success: true, data }
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      // Check if error is about large array size exceeding maximum (Payload Too Large)
+      // Only return 413 for arrays with max >= 1000 (infrastructure limits)
+      // Return 400 for smaller limits (operational/business constraints)
+      const hasLargePayloadError = error.issues.some((issue) => {
+        if (issue.code !== 'too_big') return false
+        if (!('origin' in issue) || (issue as { origin?: string }).origin !== 'array') return false
+        if (!('maximum' in issue)) return false
+        const { maximum } = issue as { maximum?: number }
+        return typeof maximum === 'number' && maximum >= 1000
+      })
+
+      if (hasLargePayloadError) {
+        return { success: false, response: c.json({ error: 'PayloadTooLarge' }, 413) }
+      }
+
+      const errorResponse = validationErrorResponseSchema.parse({
+        success: false,
+        message: 'Validation failed',
+        code: 'VALIDATION_ERROR',
+        errors: formatZodErrors(error),
+      })
+      return { success: false, response: c.json(errorResponse, 400) }
+    }
+    // JSON parse error or unexpected error
+    const errorResponse = validationErrorResponseSchema.parse({
+      success: false,
+      message: 'Invalid JSON body',
+      code: 'VALIDATION_ERROR',
+      errors: [{ field: 'body', message: 'Request body must be valid JSON' }],
+    })
+    return { success: false, response: c.json(errorResponse, 400) }
+  }
+}

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

@@ -0,0 +1,29 @@
+/**
+ * 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.
+ */
+
+/**
+ * Validation Module Exports
+ */
+
+export {
+  ValidationError,
+  PermissionError,
+  ValidationContext,
+  createValidationLayer,
+  formatValidationError,
+  type ValidationResult,
+} from '../middleware/validation'
+
+export {
+  validateReadonlyIdField,
+  validateDefaultFields,
+  validateRequiredFields,
+  filterAllowedFields,
+  validateFieldWritePermissions,
+} from './rules/field-rules'
+
+export { validateRecordCreation, validateRecordUpdate } from './rules/record-rules'