sovrium 0.0.2

package/src/presentation/api/routes/tables/field-permission-validation.ts

@@ -0,0 +1,167 @@
+/**
+ * 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'
+
+type AggregateParams = {
+  readonly count?: boolean
+  readonly sum?: readonly string[]
+  readonly avg?: readonly string[]
+  readonly min?: readonly string[]
+  readonly max?: readonly string[]
+}
+
+type FilterStructure =
+  | {
+      readonly and?: readonly {
+        readonly field: string
+        readonly operator: string
+        readonly value: unknown
+      }[]
+    }
+  | undefined
+
+/**
+ * Check if field is sensitive type (email, phone, currency)
+ */
+function isSensitiveFieldType(fieldType: string): boolean {
+  const sensitiveTypes = new Set(['email', 'phone-number', 'currency'])
+  return sensitiveTypes.has(fieldType)
+}
+
+/**
+ * Check if field should be excluded for viewer role
+ */
+function shouldExcludeForViewer(fieldName: string, fieldType: string): boolean {
+  const allowedFieldTypes = new Set(['single-line-text'])
+  const allowedFieldNames = new Set(['name', 'title'])
+
+  // Exclude sensitive field types
+  if (isSensitiveFieldType(fieldType)) {
+    return true
+  }
+
+  // Only allow specific field names or types
+  if (!allowedFieldNames.has(fieldName) && !allowedFieldTypes.has(fieldType)) {
+    return true
+  }
+
+  // For single-line-text, only allow if it's a name/title field
+  if (fieldType === 'single-line-text' && !allowedFieldNames.has(fieldName)) {
+    return true
+  }
+
+  return false
+}
+
+/**
+ * Check if field should be excluded based on default permission rules
+ * Matches logic from field-read-filter.ts
+ */
+export function shouldExcludeFieldByDefault(
+  fieldName: string,
+  userRole: string,
+  table:
+    | { readonly fields: readonly { readonly name: string; readonly type: string }[] }
+    | undefined
+): boolean {
+  // Admin role has full access
+  if (userRole === 'admin') {
+    return false
+  }
+
+  // Find field definition
+  const field = table?.fields.find((f) => f.name === fieldName)
+  if (!field) return false
+
+  // Viewer role: most restrictive access
+  if (userRole === 'viewer') {
+    return shouldExcludeForViewer(fieldName, field.type)
+  }
+
+  // Member role: restrict sensitive financial data
+  if (userRole === 'member') {
+    return fieldName === 'salary' && field.type === 'currency'
+  }
+
+  return false
+}
+
+/**
+ * Validate filter parameter - ensure user has permission to read filter fields
+ */
+export function validateFilterParam(
+  filter: FilterStructure,
+  table:
+    | { readonly fields: readonly { readonly name: string; readonly type: string }[] }
+    | undefined,
+  userRole: string,
+  c: Context
+) {
+  if (!filter) return undefined
+
+  // Extract field names from filter structure
+  const filterFields = filter.and?.map((condition) => condition.field) ?? []
+
+  // Check if user has permission to read each filter field using find instead of for loop
+  const inaccessibleField = filterFields.find((fieldName) =>
+    shouldExcludeFieldByDefault(fieldName, userRole, table)
+  )
+
+  if (inaccessibleField) {
+    return c.json(
+      {
+        success: false,
+        message: `You do not have permission to perform this action. Cannot filter by field '${inaccessibleField}'`,
+        code: 'FORBIDDEN',
+      },
+      403
+    )
+  }
+
+  return undefined
+}
+
+/**
+ * Validate aggregate parameter - ensure user has permission to read aggregated fields
+ */
+export function validateAggregateParam(
+  aggregate: AggregateParams | undefined,
+  table:
+    | { readonly fields: readonly { readonly name: string; readonly type: string }[] }
+    | undefined,
+  userRole: string,
+  c: Context
+) {
+  if (!aggregate) return undefined
+
+  // Extract all field names from aggregate operations
+  const aggregateFields = [
+    ...(aggregate.sum ?? []),
+    ...(aggregate.avg ?? []),
+    ...(aggregate.min ?? []),
+    ...(aggregate.max ?? []),
+  ]
+
+  // Check if user has permission to read each aggregated field using find instead of for loop
+  const inaccessibleField = aggregateFields.find((fieldName) =>
+    shouldExcludeFieldByDefault(fieldName, userRole, table)
+  )
+
+  if (inaccessibleField) {
+    return c.json(
+      {
+        success: false,
+        message: `You do not have permission to perform this action. Cannot aggregate field '${inaccessibleField}'`,
+        code: 'FORBIDDEN',
+      },
+      403
+    )
+  }
+
+  return undefined
+}

package/src/presentation/api/routes/tables/filter-parser.ts

@@ -0,0 +1,75 @@
+/**
+ * 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 { validateFilterFieldPermissions } from '@/presentation/api/utils/filter-field-validator'
+import type { App } from '@/domain/models/app'
+import type { Context } from 'hono'
+
+/**
+ * Filter parameter type matching the expected shape
+ */
+export type FilterParameter =
+  | {
+      readonly and?: readonly {
+        readonly field: string
+        readonly operator: string
+        readonly value: unknown
+      }[]
+    }
+  | undefined
+
+/**
+ * Result of parsing filter parameter
+ */
+export type ParseFilterResult =
+  | { success: true; filter: FilterParameter }
+  | { success: false; error: Response }
+
+/**
+ * Parse and validate filter parameter from query string
+ *
+ * Handles JSON parsing and field-level permission validation
+ * for filter parameters.
+ *
+ * @param config - Configuration object with filter details
+ * @returns ParseFilterResult indicating success with filter or failure with error response
+ */
+export function parseFilterParameter(config: {
+  filterParam: string | undefined
+  app: App
+  tableName: string
+  userRole: string
+  c: Context
+}): ParseFilterResult {
+  const { filterParam, app, tableName, userRole, c } = config
+
+  if (!filterParam) {
+    return { success: true, filter: undefined }
+  }
+
+  try {
+    const filter = JSON.parse(filterParam)
+    const forbiddenFields = validateFilterFieldPermissions(app, tableName, userRole, filter)
+
+    if (forbiddenFields.length > 0) {
+      return {
+        success: false,
+        error: c.json(
+          { error: 'Forbidden', message: `Cannot filter by field: ${forbiddenFields[0]}` },
+          403
+        ),
+      }
+    }
+
+    return { success: true, filter }
+  } catch {
+    return {
+      success: false,
+      error: c.json({ error: 'Bad Request', message: 'Invalid filter parameter' }, 400),
+    }
+  }
+}

package/src/presentation/api/routes/tables/formula-parser.ts

@@ -0,0 +1,118 @@
+/**
+ * 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.
+ */
+
+/**
+ * Map operator symbol to internal operator name
+ */
+function mapOperator(operator: string): string | undefined {
+  const operatorMap: Record<string, string> = {
+    '=': 'equals',
+    '!=': 'notEquals',
+    '<': 'lessThan',
+    '<=': 'lessThanOrEqual',
+    '>': 'greaterThan',
+    '>=': 'greaterThanOrEqual',
+  }
+  return operatorMap[operator]
+}
+
+/**
+ * Parse a single condition from regex match
+ */
+function parseCondition(match: RegExpExecArray):
+  | {
+      readonly field: string
+      readonly operator: string
+      readonly value: unknown
+    }
+  | undefined {
+  const field = match[1]
+  const operator = match[2]
+  const stringValue1 = match[3]
+  const stringValue2 = match[4]
+  const numberValue = match[5]
+
+  // Validate required captures
+  if (!field || !operator) {
+    return undefined
+  }
+
+  // Determine value (string or number)
+  const value = stringValue1 ?? stringValue2 ?? Number(numberValue)
+
+  const mappedOperator = mapOperator(operator)
+  if (!mappedOperator) {
+    return undefined
+  }
+
+  return {
+    field,
+    operator: mappedOperator,
+    value,
+  }
+}
+
+/**
+ * Extract all conditions from formula string
+ */
+function extractConditions(conditions: string): Array<{
+  readonly field: string
+  readonly operator: string
+  readonly value: unknown
+}> {
+  // Regex to match: {field}operator'value' or {field}operatorvalue
+  const conditionRegex = /\{([^}]+)\}\s*([!=<>]+)\s*(?:'([^']*)'|"([^"]*)"|(\d+))/g
+
+  const matches = [...conditions.matchAll(conditionRegex)]
+  const parsedConditions = matches
+    .map(parseCondition)
+    .filter((c): c is NonNullable<typeof c> => c !== undefined)
+
+  return parsedConditions
+}
+
+/**
+ * Parse Airtable-style formula syntax into filter structure
+ *
+ * Supported syntax:
+ * - AND({field}='value', {field}>=value)
+ * - Field references: {fieldName}
+ * - Operators: =, !=, <, <=, >, >=
+ * - String values: 'value' or "value"
+ * - Number values: 123
+ *
+ * @param formula - Airtable-style formula string
+ * @returns Filter structure compatible with existing filter system
+ */
+export function parseFormulaToFilter(formula: string):
+  | {
+      readonly and?: Array<{
+        readonly field: string
+        readonly operator: string
+        readonly value: unknown
+      }>
+    }
+  | undefined {
+  // Match AND(...) pattern
+  const andMatch = formula.match(/^AND\((.*)\)$/i)
+  if (!andMatch) {
+    return undefined
+  }
+
+  const conditions = andMatch[1]
+  if (!conditions) {
+    return undefined
+  }
+
+  const filters = extractConditions(conditions)
+
+  if (filters.length === 0) {
+    return undefined
+  }
+
+  return { and: filters }
+}

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

@@ -0,0 +1,113 @@
+/**
+ * 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 { validateTable, enrichUserRole } from '@/presentation/api/middleware/table'
+import { chainBatchRoutesMethods } from './batch-routes'
+import { chainRecordRoutesMethods } from './record-routes'
+import { chainTableRoutesMethods } from './table-routes'
+import { chainViewRoutesMethods } from './view-routes'
+import type { App } from '@/domain/models/app'
+import type { Context, Hono, Next } from 'hono'
+
+/**
+ * Guest context middleware handler
+ *
+ * Creates a minimal guest session for apps without auth configuration.
+ */
+async function guestContextHandler(c: Context, next: Next) {
+  // Create a minimal guest session for apps without auth
+  const guestSession = {
+    userId: 'guest',
+    expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000), // 24 hours from now
+    token: '',
+    ipAddress: '',
+    userAgent: '',
+  }
+  c.set('session', guestSession)
+  c.set('userRole', 'guest')
+
+  // eslint-disable-next-line functional/no-expression-statements -- Required for middleware to continue
+  await next()
+}
+
+/**
+ * Middleware to provide guest session and role for apps without authentication
+ *
+ * For apps without auth configuration, this middleware creates a minimal
+ * guest session and sets the userRole to 'guest', allowing routes to function
+ * without actual authentication while maintaining the expected context structure.
+ */
+function provideGuestContext() {
+  return guestContextHandler
+}
+
+/**
+ * Chain table routes onto a Hono app
+ *
+ * **Middleware Chain** (applied before all :tableId routes):
+ * ```
+ * requireAuth() → validateTable() → enrichUserRole() → Handler (if auth configured)
+ * validateTable() → provideGuestContext() → Handler (if no auth)
+ * ```
+ * - `requireAuth`: Ensures session exists (applied in api-routes.ts if auth configured)
+ * - `validateTable`: Validates table exists, attaches tableName + tableId
+ * - `enrichUserRole`: Fetches user role from DB, attaches userRole (if auth configured)
+ * - `provideGuestContext`: Provides guest session and role (if no auth)
+ *
+ * **IMPORTANT**: Hono requires middleware registration for BOTH patterns:
+ * 1. `/api/tables/:tableId` - Exact match (e.g., GET /api/tables/123)
+ * 2. `/api/tables/:tableId/*` - Nested routes (e.g., GET /api/tables/123/records)
+ *
+ * Without both patterns, middleware won't run for all routes.
+ *
+ * **Context Variables Available After Chain** (via `ContextWithTableAndRole`):
+ * - `session`: Session (authenticated user or guest)
+ * - `tableName`: string (resolved table name)
+ * - `tableId`: string (original parameter)
+ * - `userRole`: string (user's role in organization or 'guest')
+ *
+ * Uses method chaining for proper Hono RPC type inference.
+ *
+ * @param honoApp - Hono instance to chain routes onto
+ * @param app - Application configuration containing table metadata
+ * @returns Hono app with table routes chained
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- Hono type inference with middleware requires flexible typing
+export function chainTableRoutes<T extends Hono<any, any, any>>(honoApp: T, app: App) {
+  // Apply middleware for routes with :tableId parameter
+  // Middleware order: validateTable (404 if not found) → enrichUserRole (fetch role if auth configured)
+  // Note: requireAuth() is conditionally applied in api-routes.ts based on app.auth
+  //
+  // Two patterns needed:
+  // - '/api/tables/:tableId' for exact match (e.g., GET /api/tables/:tableId)
+  // - '/api/tables/:tableId/*' for nested routes (e.g., GET /api/tables/:tableId/records)
+  //
+  // enrichUserRole is only applied when auth is configured (app.auth exists)
+  // For apps without auth, provideGuestContext creates a guest session and role
+  const honoWithMiddleware = app.auth
+    ? honoApp
+        .use('/api/tables/:tableId', validateTable(app))
+        .use('/api/tables/:tableId', enrichUserRole())
+        .use('/api/tables/:tableId/*', validateTable(app))
+        .use('/api/tables/:tableId/*', enrichUserRole())
+    : honoApp
+        .use('/api/tables/:tableId', validateTable(app))
+        .use('/api/tables/:tableId', provideGuestContext())
+        .use('/api/tables/:tableId/*', validateTable(app))
+        .use('/api/tables/:tableId/*', provideGuestContext())
+
+  // Route registration order matters for Hono's router.
+  // More specific routes (batch/restore) must be registered BEFORE
+  // parameterized routes (:recordId/restore) to avoid route collisions.
+  return chainViewRoutesMethods(
+    chainRecordRoutesMethods(
+      chainBatchRoutesMethods(chainTableRoutesMethods(honoWithMiddleware, app), app),
+      app
+    ),
+    app
+  )
+}

package/src/presentation/api/routes/tables/list-records-filter.ts

@@ -0,0 +1,54 @@
+/**
+ * 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 { parseFilterParameter } from './filter-parser'
+import { parseFormulaToFilter } from './formula-parser'
+import type { App } from '@/domain/models/app'
+import type { Context } from 'hono'
+
+type FilterStructure =
+  | {
+      readonly and?: readonly {
+        readonly field: string
+        readonly operator: string
+        readonly value: unknown
+      }[]
+    }
+  | undefined
+
+type FilterResult =
+  | { readonly error: false; readonly value: FilterStructure }
+  | { readonly error: true; readonly response?: Response }
+
+/**
+ * Parse filter parameter from request (formula or standard filter)
+ */
+export function parseFilter(
+  c: Context,
+  app: App,
+  tableName: string,
+  userRole: string
+): FilterResult {
+  const filterByFormula = c.req.query('filterByFormula')
+
+  if (filterByFormula) {
+    const parsedFormula = parseFormulaToFilter(filterByFormula)
+    return parsedFormula ? { error: false, value: parsedFormula } : { error: true }
+  }
+
+  const parsedFilterResult = parseFilterParameter({
+    filterParam: c.req.query('filter'),
+    app,
+    tableName,
+    userRole,
+    c,
+  })
+
+  return parsedFilterResult.success
+    ? { error: false, value: parsedFilterResult.filter }
+    : { error: true, response: parsedFilterResult.error }
+}

package/src/presentation/api/routes/tables/param-parsers.ts

@@ -0,0 +1,59 @@
+/**
+ * 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'
+
+type AggregateParams = {
+  readonly count?: boolean
+  readonly sum?: readonly string[]
+  readonly avg?: readonly string[]
+  readonly min?: readonly string[]
+  readonly max?: readonly string[]
+}
+
+/**
+ * Parse aggregate JSON parameter
+ */
+export function parseAggregateParam(
+  aggregateParam: string | undefined
+): AggregateParams | undefined {
+  if (!aggregateParam) return undefined
+
+  try {
+    return JSON.parse(aggregateParam) as AggregateParams
+  } catch {
+    // Invalid JSON, ignore aggregation
+    return undefined
+  }
+}
+
+/**
+ * Parse list records query parameters
+ */
+export function parseListRecordsParams(c: Context): {
+  readonly includeDeleted: boolean
+  readonly format: 'display' | undefined
+  readonly timezone: string | undefined
+  readonly sort: string | undefined
+  readonly fields: string | undefined
+  readonly limit: number | undefined
+  readonly offset: number | undefined
+  readonly aggregate: AggregateParams | undefined
+} {
+  const includeDeleted = c.req.query('includeDeleted') === 'true'
+  const format = c.req.query('format') === 'display' ? ('display' as const) : undefined
+  const timezone = c.req.query('timezone')
+  const sort = c.req.query('sort')
+  const fields = c.req.query('fields')
+  const limitParam = c.req.query('limit')
+  const offsetParam = c.req.query('offset')
+  const limit = limitParam ? Number(limitParam) : undefined
+  const offset = offsetParam ? Number(offsetParam) : undefined
+  const aggregate = parseAggregateParam(c.req.query('aggregate'))
+
+  return { includeDeleted, format, timezone, sort, fields, limit, offset, aggregate }
+}