sovrium 0.0.2

package/src/presentation/api/routes/tables/comment-handlers.ts

@@ -0,0 +1,377 @@
+/**
+ * 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 {
+  createCommentProgram,
+  deleteCommentProgram,
+  getCommentProgram,
+  listCommentsProgram,
+  updateCommentProgram,
+} from '@/application/use-cases/tables/comment-programs'
+import { hasReadPermission } from '@/application/use-cases/tables/permissions/permissions'
+import { getTableContext } from '@/presentation/api/utils/context-helpers'
+import { runTableProgram } from './effect-runner'
+import { handleRouteError } from './error-handlers'
+import { isAuthorizationError } from './utils'
+import type { App } from '@/domain/models/app'
+import type { Context } from 'hono'
+
+/**
+ * Create comment request validation
+ */
+interface CreateCommentBody {
+  readonly content: string
+}
+
+/**
+ * Validate create comment request body
+ */
+function validateCreateCommentBody(body: unknown): CreateCommentBody | undefined {
+  if (typeof body !== 'object' || body === undefined) {
+    return undefined
+  }
+
+  const { content } = body as Record<string, unknown>
+
+  if (typeof content !== 'string') {
+    return undefined
+  }
+
+  if (content.length === 0) {
+    return undefined
+  }
+
+  if (content.length > 10_000) {
+    return undefined
+  }
+
+  return { content }
+}
+
+/**
+ * Handle comment creation errors
+ *
+ * Authorization errors return 404 (prevents resource enumeration),
+ * all other errors are sanitized via the shared route error handler.
+ */
+function handleCommentError(c: Context, error: unknown) {
+  if (isAuthorizationError(error)) {
+    return c.json({ success: false, message: 'Resource not found', code: 'NOT_FOUND' }, 404)
+  }
+  return handleRouteError(c, error)
+}
+
+/**
+ * Handle create comment on a record
+ */
+export async function handleCreateComment(c: Context, app: App) {
+  const { session, userRole } = getTableContext(c)
+  const tableId = c.req.param('tableId')
+  const recordId = c.req.param('recordId')
+
+  // Find table by ID
+  const table = app.tables?.find((t) => String(t.id) === String(tableId))
+  if (!table) {
+    return c.json({ success: false, message: 'Resource not found', code: 'NOT_FOUND' }, 404)
+  }
+
+  // Check read permission (must be able to read the record to comment on it)
+  if (!hasReadPermission(table, userRole, app.tables)) {
+    return c.json(
+      {
+        success: false,
+        message: 'You do not have permission to perform this action',
+        code: 'FORBIDDEN',
+      },
+      403
+    )
+  }
+
+  // Parse and validate request body
+  const body = await c.req.json().catch(() => undefined)
+  const validated = validateCreateCommentBody(body)
+
+  if (!validated) {
+    return c.json(
+      { success: false, message: 'Invalid request body', code: 'VALIDATION_ERROR' },
+      400
+    )
+  }
+
+  // Create comment
+  const program = createCommentProgram({
+    session,
+    tableId,
+    recordId,
+    tableName: table.name,
+    content: validated.content,
+  })
+
+  const result = await runTableProgram(program)
+
+  if (result._tag === 'Left') {
+    return handleCommentError(c, result.left)
+  }
+
+  return c.json(result.right, 201)
+}
+
+/**
+ * Handle delete comment error
+ */
+function handleDeleteCommentError(c: Context, error: unknown) {
+  // Check for authorization errors
+  if (isAuthorizationError(error)) {
+    const errorMessage = error instanceof Error ? error.message : String(error)
+
+    // Forbidden error (user is not author and not admin)
+    if (errorMessage.includes('Forbidden')) {
+      return c.json({ success: false, code: 'FORBIDDEN' }, 403)
+    }
+
+    // Not found error (comment doesn't exist, already deleted, or no record access)
+    return c.json({ success: false, message: 'Resource not found', code: 'NOT_FOUND' }, 404)
+  }
+
+  // All other errors - use shared sanitization
+  return handleRouteError(c, error)
+}
+
+/**
+ * Handle delete comment
+ */
+export async function handleDeleteComment(c: Context, app: App) {
+  const { session } = getTableContext(c)
+  const tableId = c.req.param('tableId')
+  const commentId = c.req.param('commentId')
+
+  // Find table by ID
+  const table = app.tables?.find((t) => String(t.id) === String(tableId))
+  if (!table) {
+    return c.json({ success: false, message: 'Resource not found', code: 'NOT_FOUND' }, 404)
+  }
+
+  // Delete comment
+  const program = deleteCommentProgram({
+    session,
+    commentId,
+    tableName: table.name,
+  })
+
+  const result = await runTableProgram(program)
+
+  if (result._tag === 'Left') {
+    return handleDeleteCommentError(c, result.left)
+  }
+
+  // Return 204 No Content on success
+  // eslint-disable-next-line unicorn/no-null -- Hono's c.body() requires null for 204 No Content
+  return c.body(null, 204)
+}
+
+/**
+ * Handle get comment by ID
+ */
+export async function handleGetComment(c: Context, app: App) {
+  const { session, userRole } = getTableContext(c)
+  const tableId = c.req.param('tableId')
+  const commentId = c.req.param('commentId')
+
+  // Find table by ID
+  const table = app.tables?.find((t) => String(t.id) === String(tableId))
+  if (!table) {
+    return c.json({ success: false, message: 'Resource not found', code: 'NOT_FOUND' }, 404)
+  }
+
+  // Check read permission
+  if (!hasReadPermission(table, userRole, app.tables)) {
+    return c.json(
+      {
+        success: false,
+        message: 'You do not have permission to perform this action',
+        code: 'FORBIDDEN',
+      },
+      403
+    )
+  }
+
+  // Get comment
+  const program = getCommentProgram({
+    session,
+    commentId,
+    tableName: table.name,
+  })
+
+  const result = await runTableProgram(program)
+
+  if (result._tag === 'Left') {
+    return c.json({ success: false, message: 'Resource not found', code: 'NOT_FOUND' }, 404)
+  }
+
+  return c.json(result.right, 200)
+}
+
+/**
+ * Validate update comment request body
+ */
+function validateUpdateCommentBody(body: unknown): CreateCommentBody | undefined {
+  if (typeof body !== 'object' || body === undefined) {
+    return undefined
+  }
+
+  const { content } = body as Record<string, unknown>
+
+  if (typeof content !== 'string') {
+    return undefined
+  }
+
+  if (content.length === 0) {
+    return undefined
+  }
+
+  if (content.length > 10_000) {
+    return undefined
+  }
+
+  return { content }
+}
+
+/**
+ * Handle update comment error
+ */
+function handleUpdateCommentError(c: Context, error: unknown) {
+  // Check for authorization errors
+  if (isAuthorizationError(error)) {
+    const errorMessage = error instanceof Error ? error.message : String(error)
+
+    // Forbidden error (user is not author)
+    if (errorMessage.includes('Forbidden')) {
+      return c.json({ success: false, code: 'FORBIDDEN' }, 403)
+    }
+
+    // Not found error (comment doesn't exist, already deleted, or no record access)
+    return c.json({ success: false, message: 'Resource not found', code: 'NOT_FOUND' }, 404)
+  }
+
+  // Internal server error
+  return c.json(
+    { success: false, message: 'Failed to update comment', code: 'INTERNAL_ERROR' },
+    500
+  )
+}
+
+/**
+ * Handle update comment
+ */
+export async function handleUpdateComment(c: Context, app: App) {
+  const { session } = getTableContext(c)
+  const tableId = c.req.param('tableId')
+  const commentId = c.req.param('commentId')
+
+  // Find table by ID
+  const table = app.tables?.find((t) => String(t.id) === String(tableId))
+  if (!table) {
+    return c.json({ success: false, message: 'Resource not found', code: 'NOT_FOUND' }, 404)
+  }
+
+  // Parse and validate request body
+  const body = await c.req.json().catch(() => undefined)
+  const validated = validateUpdateCommentBody(body)
+
+  if (!validated) {
+    return c.json(
+      { success: false, message: 'Invalid request body', code: 'VALIDATION_ERROR' },
+      400
+    )
+  }
+
+  // Update comment
+  const program = updateCommentProgram({
+    session,
+    commentId,
+    tableName: table.name,
+    content: validated.content,
+  })
+
+  const result = await runTableProgram(program)
+
+  if (result._tag === 'Left') {
+    return handleUpdateCommentError(c, result.left)
+  }
+
+  return c.json(result.right, 200)
+}
+
+/**
+ * Parse sort query parameter (e.g., "createdAt:asc" or "createdAt:desc")
+ */
+function parseSortOrder(sortParam: string | undefined): 'asc' | 'desc' | undefined {
+  if (!sortParam) {
+    return undefined
+  }
+
+  const [field, order] = sortParam.split(':')
+  if (field === 'createdAt' && (order === 'asc' || order === 'desc')) {
+    return order
+  }
+
+  return undefined
+}
+
+/**
+ * Handle list comments for a record
+ */
+export async function handleListComments(c: Context, app: App) {
+  const { session, userRole } = getTableContext(c)
+  const tableId = c.req.param('tableId')
+  const recordId = c.req.param('recordId')
+
+  // Find table by ID
+  const table = app.tables?.find((t) => String(t.id) === String(tableId))
+  if (!table) {
+    return c.json({ success: false, message: 'Resource not found', code: 'NOT_FOUND' }, 404)
+  }
+
+  // Check read permission
+  if (!hasReadPermission(table, userRole, app.tables)) {
+    return c.json(
+      {
+        success: false,
+        message: 'You do not have permission to perform this action',
+        code: 'FORBIDDEN',
+      },
+      403
+    )
+  }
+
+  // Parse query parameters
+  const limitParam = c.req.query('limit')
+  const offsetParam = c.req.query('offset')
+  const sortParam = c.req.query('sort')
+
+  const limit = limitParam ? Number(limitParam) : undefined
+  const offset = offsetParam ? Number(offsetParam) : undefined
+  const sortOrder = parseSortOrder(sortParam)
+
+  // List comments
+  const program = listCommentsProgram({
+    session,
+    recordId,
+    tableName: table.name,
+    limit,
+    offset,
+    sortOrder,
+  })
+
+  const result = await runTableProgram(program)
+
+  if (result._tag === 'Left') {
+    return c.json({ success: false, message: 'Resource not found', code: 'NOT_FOUND' }, 404)
+  }
+
+  return c.json(result.right, 200)
+}

package/src/presentation/api/routes/tables/create-record-helpers.ts

@@ -0,0 +1,179 @@
+/**
+ * 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 { Context } from 'hono'
+
+/**
+ * Validate required fields for a single record
+ * Returns array of missing field names
+ */
+export function validateRequiredFieldsForRecord(
+  table:
+    | {
+        readonly name: string
+        readonly fields: ReadonlyArray<{
+          readonly name: string
+          readonly required?: boolean
+        }>
+        readonly primaryKey?: {
+          readonly type: string
+          readonly fields?: ReadonlyArray<string>
+          readonly field?: string
+        }
+      }
+    | undefined,
+  fields: Record<string, unknown>
+): readonly string[] {
+  if (!table) return []
+
+  // Get primary key field names to exclude from validation
+  const primaryKeyFields = new Set(
+    table.primaryKey?.fields ?? (table.primaryKey?.field ? [table.primaryKey.field] : [])
+  )
+
+  // Auto-injected fields that should be excluded from required field validation
+  const autoInjectedFields = new Set<string>([])
+
+  return table.fields
+    .filter(
+      (field) =>
+        field.required &&
+        !(field.name in fields) &&
+        !primaryKeyFields.has(field.name) && // Skip primary key fields
+        !autoInjectedFields.has(field.name) // Skip auto-injected fields
+    )
+    .map((field) => field.name)
+}
+
+/**
+ * Validate required fields for record creation
+ * Returns error response if required fields are missing, undefined otherwise
+ */
+export function validateRequiredFields(
+  table:
+    | {
+        readonly name: string
+        readonly fields: ReadonlyArray<{
+          readonly name: string
+          readonly required?: boolean
+        }>
+        readonly primaryKey?: {
+          readonly type: string
+          readonly fields?: ReadonlyArray<string>
+          readonly field?: string
+        }
+      }
+    | undefined,
+  fields: Record<string, unknown>,
+  c: Context
+) {
+  if (!table) return undefined
+
+  // Get primary key field names to exclude from validation
+  const primaryKeyFields = new Set(
+    table.primaryKey?.fields ?? (table.primaryKey?.field ? [table.primaryKey.field] : [])
+  )
+
+  // Auto-injected fields that should be excluded from required field validation
+  const autoInjectedFields = new Set<string>([])
+
+  const missingRequiredFields = table.fields
+    .filter(
+      (field) =>
+        field.required &&
+        !(field.name in fields) &&
+        !primaryKeyFields.has(field.name) && // Skip primary key fields
+        !autoInjectedFields.has(field.name) // Skip auto-injected fields
+    )
+    .map((field) => field.name)
+
+  if (missingRequiredFields.length > 0) {
+    return c.json(
+      {
+        success: false,
+        message: 'Missing required fields',
+        code: 'VALIDATION_ERROR',
+        details: missingRequiredFields.map((field, index) => ({
+          record: index,
+          field,
+          error: 'Required field is missing',
+        })),
+      },
+      400
+    )
+  }
+
+  return undefined
+}
+
+/**
+ * Check if user is trying to set readonly 'id' field
+ */
+export function checkReadonlyIdField(requestedFields: Record<string, unknown>, c: Context) {
+  if ('id' in requestedFields) {
+    return c.json(
+      {
+        success: false,
+        message: "Cannot write to readonly field 'id'",
+        code: 'FORBIDDEN',
+      },
+      403
+    )
+  }
+  return undefined
+}
+
+/**
+ * Check if user is trying to set fields with default values (system-managed)
+ */
+export function checkDefaultFields(
+  table:
+    | {
+        readonly fields?: ReadonlyArray<{
+          readonly name: string
+          readonly default?: unknown
+        }>
+      }
+    | undefined,
+  requestedFields: Record<string, unknown>,
+  c: Context
+) {
+  const fieldsWithDefaults =
+    table?.fields?.filter((f) => 'default' in f && f.default !== undefined) ?? []
+  const attemptedDefaultField = fieldsWithDefaults.find((f) => f.name in requestedFields)
+
+  if (attemptedDefaultField) {
+    return c.json(
+      {
+        success: false,
+        message: `Cannot write to readonly field '${attemptedDefaultField.name}'`,
+        code: 'FORBIDDEN',
+      },
+      403
+    )
+  }
+  return undefined
+}
+
+/**
+ * Check field-level write permissions and return forbidden field error if needed
+ */
+export function checkFieldWritePermissions(forbiddenFields: readonly string[], c: Context) {
+  if (forbiddenFields.length > 0) {
+    const firstForbiddenField = forbiddenFields[0]
+    return c.json(
+      {
+        success: false,
+        message: `Cannot write to field '${firstForbiddenField}': insufficient permissions`,
+        code: 'FORBIDDEN',
+        field: firstForbiddenField,
+      },
+      403
+    )
+  }
+  return undefined
+}

package/src/presentation/api/routes/tables/effect-runner.ts

@@ -0,0 +1,58 @@
+/**
+ * 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 { TableLive } from '@/infrastructure/database/table-live-layers'
+
+/**
+ * Run an Effect program with TableLive layer
+ *
+ * This utility consolidates the common pattern of providing TableLive, converting to Either,
+ * and running as Promise. It's used by all table-related route handlers.
+ *
+ * TableLive provides: TableRepository, BatchRepository, CommentRepository, ActivityRepository
+ *
+ * @param program - The Effect program to run (may require repository services from TableLive)
+ * @returns Promise resolving to Either (Left for errors, Right for success)
+ *
+ * @example
+ * const result = await runTableProgram(createCommentProgram({ session, tableId, content }))
+ * if (result._tag === 'Left') {
+ *   return handleError(c, result.left)
+ * }
+ * return c.json(result.right, 201)
+ */
+export async function runTableProgram<A, E, R>(
+  program: Effect.Effect<A, E, R>
+): Promise<
+  { readonly _tag: 'Left'; readonly left: E } | { readonly _tag: 'Right'; readonly right: A }
+> {
+  // Type assertion: TableLive provides all required repositories, so remaining requirements are never
+  const provided = Effect.provide(program, TableLive) as Effect.Effect<A, E, never>
+  return Effect.runPromise(Effect.either(provided))
+}
+
+/**
+ * Provide TableLive layer to an Effect program
+ *
+ * This is a simpler utility for cases where the program will be passed to runEffect
+ * (which handles the Either conversion and error handling itself).
+ *
+ * TableLive provides: TableRepository, BatchRepository, CommentRepository, ActivityRepository
+ *
+ * @param program - The Effect program to provide TableLive to (may require repository services from TableLive)
+ * @returns Effect program with TableLive provided (requirements resolved)
+ *
+ * @example
+ * return runEffect(c, provideTableLive(batchCreateProgram({ ... })), responseSchema, 201)
+ */
+export function provideTableLive<A, E, R>(
+  program: Effect.Effect<A, E, R>
+): Effect.Effect<A, E, never> {
+  // Type assertion: TableLive provides all required repositories, so remaining requirements are never
+  return Effect.provide(program, TableLive) as Effect.Effect<A, E, never>
+}

package/src/presentation/api/routes/tables/error-handlers.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 { sanitizeError, getStatusCode } from '@/presentation/api/utils/error-sanitizer'
+import type { Context } from 'hono'
+
+/**
+ * Shared route error handler
+ *
+ * Uses centralized error sanitization to prevent information disclosure.
+ * Automatically detects not-found/authorization errors and returns appropriate status codes.
+ *
+ * @param c - Hono context
+ * @param error - The error to handle
+ * @returns JSON response with sanitized error details
+ */
+export function handleRouteError(c: Context, error: unknown): Response {
+  const requestId = crypto.randomUUID()
+  const sanitized = sanitizeError(error, requestId)
+  const statusCode = getStatusCode(sanitized.code)
+
+  return c.json(
+    {
+      success: false,
+      message: sanitized.message,
+      code: sanitized.code,
+    },
+    statusCode
+  )
+}
+
+/**
+ * Handle errors from record restore operations
+ *
+ * Adds restore-specific "Record is not deleted" check, then delegates
+ * to the shared route error handler.
+ */
+export function handleRestoreRecordError(c: Context, error: unknown): Response {
+  // Check for "Record is not deleted" error (safe to expose)
+  const errorMessage = error instanceof Error ? error.message : String(error)
+  if (errorMessage === 'Record is not deleted') {
+    return c.json(
+      { success: false, message: 'Record is not deleted', code: 'VALIDATION_ERROR' },
+      400
+    )
+  }
+
+  return handleRouteError(c, error)
+}