sovrium 0.0.2

package/src/domain/models/app/table/permissions/permission-evaluator.ts

@@ -0,0 +1,372 @@
+/**
+ * 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 { TablePermissions, TableFieldPermissions } from '.'
+
+/**
+ * Check if user has permission based on permission configuration.
+ *
+ * Permission format (3-format system):
+ * - `'all'` — Everyone (including unauthenticated)
+ * - `'authenticated'` — Any logged-in user
+ * - `string[]` — Specific role names
+ */
+export function hasPermission(permission: unknown, userRole: string): boolean {
+  if (!permission) return false
+  if (permission === 'all') return true
+  if (permission === 'authenticated') return true
+  if (Array.isArray(permission)) return permission.includes(userRole)
+  return false
+}
+
+/**
+ * Check if user role has admin privileges
+ */
+export function isAdminRole(userRole: string): boolean {
+  return userRole === 'admin'
+}
+
+/**
+ * Check permission with admin override
+ */
+export function checkPermissionWithAdminOverride(
+  isAdmin: boolean,
+  permission: unknown,
+  userRole: string
+): boolean {
+  return isAdmin || hasPermission(permission, userRole)
+}
+
+/**
+ * Evaluate table-level permissions for a user
+ */
+export function evaluateTablePermissions(
+  tablePermissions: TablePermissions | undefined,
+  userRole: string,
+  isAdmin: boolean
+): Readonly<{ read: boolean; create: boolean; update: boolean; delete: boolean }> {
+  return {
+    read: checkPermissionWithAdminOverride(isAdmin, tablePermissions?.read, userRole),
+    create: checkPermissionWithAdminOverride(isAdmin, tablePermissions?.create, userRole),
+    update: checkPermissionWithAdminOverride(isAdmin, tablePermissions?.update, userRole),
+    // eslint-disable-next-line drizzle/enforce-delete-with-where -- This is accessing a property, not a Drizzle delete operation
+    delete: checkPermissionWithAdminOverride(isAdmin, tablePermissions?.delete, userRole),
+  }
+}
+
+/**
+ * Evaluate field-level permissions for a user
+ */
+export function evaluateFieldPermissions(
+  fieldPerms: TableFieldPermissions | undefined,
+  userRole: string,
+  isAdmin: boolean
+): Record<string, { read: boolean; write: boolean }> {
+  const fields = fieldPerms ?? []
+  return Object.fromEntries(
+    fields.map((fieldPerm) => [
+      fieldPerm.field,
+      {
+        read: checkPermissionWithAdminOverride(isAdmin, fieldPerm.read, userRole),
+        write: checkPermissionWithAdminOverride(isAdmin, fieldPerm.write, userRole),
+      },
+    ])
+  )
+}
+
+/**
+ * Check if user has role-based create permission for a table
+ * Returns true if permission granted, false if denied
+ *
+ * Permission logic:
+ * - Viewers: denied by default (tables must explicitly grant viewer create access)
+ * - Other roles: allowed by default (unless table restricts with role-based permissions)
+ *
+ * Supports permission inheritance via the `inherit` field.
+ */
+export function hasCreatePermission(
+  table:
+    | Readonly<{
+        name: string
+        permissions?: Readonly<{
+          create?: unknown
+          inherit?: string
+          override?: { create?: unknown }
+        }>
+      }>
+    | undefined,
+  userRole: string,
+  allTables?: readonly Readonly<{ name: string; permissions?: TablePermissions }>[]
+): boolean {
+  const effectivePerms = getEffectivePermissions(table, allTables) as
+    | Readonly<{ create?: unknown }>
+    | undefined
+
+  if (inheritanceFailed(table, allTables, effectivePerms)) return false
+  if (userRole === 'viewer') return false
+
+  const createPermission = effectivePerms?.create
+  if (!createPermission || !Array.isArray(createPermission)) return true
+  return createPermission.includes(userRole)
+}
+
+/**
+ * Check if user has delete permission for the table
+ *
+ * Supports permission inheritance via the `inherit` field.
+ */
+export function hasDeletePermission(
+  table:
+    | Readonly<{
+        name: string
+        permissions?: Readonly<{
+          delete?: unknown
+          inherit?: string
+          override?: { delete?: unknown }
+        }>
+      }>
+    | undefined,
+  userRole: string,
+  allTables?: readonly Readonly<{ name: string; permissions?: TablePermissions }>[]
+): boolean {
+  const effectivePerms = getEffectivePermissions(table, allTables) as
+    | Readonly<{ delete?: unknown }>
+    | undefined
+
+  if (inheritanceFailed(table, allTables, effectivePerms)) return false
+
+  // eslint-disable-next-line drizzle/enforce-delete-with-where -- This is not a Drizzle delete operation, it's accessing a property
+  const deletePermission = effectivePerms?.delete
+
+  if (userRole === 'viewer') {
+    return Array.isArray(deletePermission) && deletePermission.includes(userRole)
+  }
+
+  if (!deletePermission || !Array.isArray(deletePermission)) return true
+  return deletePermission.includes(userRole)
+}
+
+/**
+ * Check if user has update permission for a table
+ * Returns true if permission granted, false if denied
+ *
+ * Note: When no explicit permissions are defined:
+ * - Admins and members: allowed by default
+ * - Viewers: denied by default (tables must explicitly grant viewer update access)
+ *
+ * Supports permission inheritance via the `inherit` field.
+ */
+export function hasUpdatePermission(
+  table:
+    | Readonly<{
+        name: string
+        permissions?: Readonly<{
+          update?: unknown
+          inherit?: string
+          override?: { update?: unknown }
+        }>
+      }>
+    | undefined,
+  userRole: string,
+  allTables?: readonly Readonly<{ name: string; permissions?: TablePermissions }>[]
+): boolean {
+  const effectivePerms = getEffectivePermissions(table, allTables) as
+    | Readonly<{ update?: unknown }>
+    | undefined
+
+  if (inheritanceFailed(table, allTables, effectivePerms)) return false
+
+  const updatePermission = effectivePerms?.update
+
+  if (Array.isArray(updatePermission)) {
+    return updatePermission.includes(userRole)
+  }
+
+  if (userRole === 'viewer') return false
+
+  return true
+}
+
+/**
+ * Resolve effective permissions considering inheritance
+ */
+function getEffectivePermissions(
+  table: Readonly<{ name: string; permissions?: unknown }> | undefined,
+  allTables: readonly Readonly<{ name: string; permissions?: unknown }>[] | undefined
+): unknown {
+  if (!allTables || !table) return table?.permissions
+
+  const tableWithInheritance = table as Readonly<{
+    name: string
+    permissions?: Readonly<{ inherit?: string }>
+  }>
+
+  if (!tableWithInheritance.permissions?.inherit) {
+    return table.permissions
+  }
+
+  try {
+    return resolveInheritedPermissions(
+      table as Readonly<{ name: string; permissions?: TablePermissions }>,
+      allTables as readonly Readonly<{ name: string; permissions?: TablePermissions }>[]
+    )
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Check if inheritance resolution failed
+ */
+function inheritanceFailed(
+  table: Readonly<{ permissions?: Readonly<{ inherit?: string }> }> | undefined,
+  allTables: readonly unknown[] | undefined,
+  effectivePermissions: unknown
+): boolean {
+  return Boolean(allTables && table?.permissions?.inherit && !effectivePermissions)
+}
+
+/**
+ * Check if circular inheritance exists
+ */
+function hasCircularInheritance(tableName: string, visited: ReadonlySet<string>): boolean {
+  return visited.has(tableName)
+}
+
+/**
+ * Find parent table by name
+ */
+function findParentTable(
+  parentName: string | undefined,
+  allTables: readonly Readonly<{ name: string; permissions?: TablePermissions }>[]
+): Readonly<{ name: string; permissions?: TablePermissions }> | undefined {
+  if (!parentName) return undefined
+  return allTables.find((t) => t.name === parentName)
+}
+
+/**
+ * Merge a single permission property with override support
+ */
+function mergePermission<T>(
+  overrideValue: T | undefined,
+  currentValue: T | undefined,
+  parentValue: T | undefined
+): T | undefined {
+  return overrideValue ?? currentValue ?? parentValue
+}
+
+/**
+ * Merge parent and current permissions with override support
+ */
+function mergePermissions(
+  permissions: TablePermissions,
+  parentPermissions: TablePermissions
+): TablePermissions {
+  const { override, read, comment, create, update, delete: deletePerms, fields } = permissions
+
+  return {
+    read: mergePermission(override?.read, read, parentPermissions.read),
+    comment: mergePermission(override?.comment, comment, parentPermissions.comment),
+    create: mergePermission(override?.create, create, parentPermissions.create),
+    update: mergePermission(override?.update, update, parentPermissions.update),
+    // eslint-disable-next-line drizzle/enforce-delete-with-where -- This is accessing a property, not a Drizzle delete operation
+    delete: mergePermission(override?.delete, deletePerms, parentPermissions.delete),
+    fields: fields ?? parentPermissions.fields,
+  }
+}
+
+/**
+ * Resolve inherited permissions for a table
+ *
+ * Recursively resolves permissions by following the inheritance chain.
+ * Handles circular inheritance detection and merges override permissions.
+ *
+ * @param table - The table to resolve permissions for
+ * @param allTables - All tables in the app (for parent lookup)
+ * @param visited - Set of visited table names (for circular detection)
+ * @returns Resolved permissions or undefined if inheritance chain is invalid
+ * @throws Error if circular inheritance detected or parent table not found
+ */
+export function resolveInheritedPermissions(
+  table: Readonly<{ name: string; permissions?: TablePermissions }> | undefined,
+  allTables: readonly Readonly<{ name: string; permissions?: TablePermissions }>[],
+  visited: ReadonlySet<string> = new Set()
+): TablePermissions | undefined {
+  if (!table?.permissions) return undefined
+
+  const { permissions } = table
+
+  // If no inheritance, return current permissions
+  if (!permissions.inherit) {
+    return permissions
+  }
+
+  // Circular inheritance detection
+  if (hasCircularInheritance(table.name, visited)) {
+    // Return undefined to indicate error (caught by callers)
+    return undefined
+  }
+
+  // Find parent table
+  const parentTable = findParentTable(permissions.inherit, allTables)
+  if (!parentTable) {
+    // Return undefined to indicate error (caught by callers)
+    return undefined
+  }
+
+  // Recursively resolve parent permissions
+  const parentPermissions = resolveInheritedPermissions(
+    parentTable,
+    allTables,
+    new Set([...visited, table.name])
+  )
+
+  if (!parentPermissions) return permissions
+
+  // Merge parent permissions with current permissions (current takes precedence)
+  return mergePermissions(permissions, parentPermissions)
+}
+
+/**
+ * Check if user has read permission for a table
+ * Returns true if permission granted, false if denied
+ *
+ * Note: When no explicit permissions are defined:
+ * - Admins and members: allowed by default
+ * - Viewers: denied by default (tables must explicitly grant viewer access)
+ *
+ * Supports permission inheritance via the `inherit` field.
+ */
+export function hasReadPermission(
+  table:
+    | Readonly<{
+        name: string
+        permissions?: Readonly<{ read?: unknown; inherit?: string; override?: { read?: unknown } }>
+      }>
+    | undefined,
+  userRole: string,
+  allTables?: readonly Readonly<{ name: string; permissions?: TablePermissions }>[]
+): boolean {
+  const effectivePerms = getEffectivePermissions(table, allTables) as
+    | Readonly<{ read?: unknown }>
+    | undefined
+
+  if (inheritanceFailed(table, allTables, effectivePerms)) return false
+
+  const readPermission = effectivePerms?.read
+
+  if (Array.isArray(readPermission)) {
+    return readPermission.includes(userRole)
+  }
+
+  if (readPermission === 'all') return true
+  if (readPermission === 'authenticated') return true
+
+  if (userRole === 'viewer') return false
+
+  return true
+}

package/src/domain/models/app/table/permissions/permission.ts

@@ -0,0 +1,49 @@
+/**
+ * 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 { Schema } from 'effect'
+
+/**
+ * Table Permission Schema
+ *
+ * Simplified permission value for a single CRUD operation.
+ * Accepts one of 3 formats:
+ *
+ * - `'all'` — Everyone (including unauthenticated users)
+ * - `'authenticated'` — Any logged-in user
+ * - `['admin', 'editor']` — Specific role names (array)
+ *
+ * @example
+ * ```yaml
+ * permissions:
+ *   read: all
+ *   comment: authenticated
+ *   create: ['admin', 'editor']
+ *   update: ['admin', 'editor']
+ *   delete: ['admin']
+ * ```
+ */
+export const TablePermissionSchema = Schema.Union(
+  Schema.Literal('all'),
+  Schema.Literal('authenticated'),
+  Schema.Array(Schema.String).pipe(
+    Schema.minItems(1),
+    Schema.annotations({
+      description: 'Array of role names that have access (e.g., admin, editor). At least one role.',
+      examples: [['admin'], ['admin', 'editor'], ['admin', 'member', 'viewer']],
+    })
+  )
+).pipe(
+  Schema.annotations({
+    title: 'Table Permission',
+    description:
+      "Permission value for a single operation. 'all' (everyone), 'authenticated' (logged-in users), or role array ['admin', 'editor'].",
+    examples: ['all', 'authenticated', ['admin'], ['admin', 'editor']],
+  })
+)
+
+export type TablePermission = Schema.Schema.Type<typeof TablePermissionSchema>

package/src/domain/models/app/table/primary-key.ts

@@ -0,0 +1,62 @@
+/**
+ * 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 { Schema } from 'effect'
+
+/**
+ * Primary Key
+ *
+ * Primary key configuration for the table. The primary key uniquely identifies each row and is automatically indexed.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   "type": "auto-increment",
+ *   "field": "id"
+ * }
+ * ```
+ */
+export const PrimaryKeySchema = Schema.Struct({
+  type: Schema.String.pipe(
+    Schema.minLength(1),
+    Schema.annotations({
+      description:
+        "Primary key generation strategy. 'auto-increment' uses sequential integers (1, 2, 3...), 'uuid' generates random unique identifiers, 'composite' uses multiple fields together.",
+    })
+  ),
+  field: Schema.optional(
+    Schema.String.pipe(
+      Schema.pattern(/^[a-z][a-z0-9_]*$/, {
+        message: () =>
+          "Field name for single-column primary key. Only used with 'auto-increment' or 'uuid' type.",
+      }),
+      Schema.annotations({
+        description:
+          "Field name for single-column primary key. Only used with 'auto-increment' or 'uuid' type.",
+        examples: ['id', 'user_id', 'product_id'],
+      })
+    )
+  ),
+  fields: Schema.optional(
+    Schema.Array(
+      Schema.String.pipe(Schema.minLength(1, { message: () => 'This field is required' }))
+    )
+  ),
+}).pipe(
+  Schema.annotations({
+    title: 'Primary Key',
+    description:
+      'Primary key configuration for the table. The primary key uniquely identifies each row and is automatically indexed.',
+    examples: [
+      { type: 'auto-increment', field: 'id' },
+      { type: 'uuid', field: 'id' },
+      { type: 'composite', fields: ['tenant_id', 'user_id'] },
+    ],
+  })
+)
+
+export type PrimaryKey = Schema.Schema.Type<typeof PrimaryKeySchema>

package/src/domain/models/app/table/table-formula-validation.ts

@@ -0,0 +1,168 @@
+/**
+ * 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 { detectCycles } from './cycle-detection'
+import { FORMULA_KEYWORDS } from './formula-keywords'
+
+/**
+ * Special field references that are always available in formulas.
+ * These are system-managed fields that exist on all tables.
+ */
+export const SPECIAL_FIELDS = new Set([
+  'id',
+  'created_at',
+  'updated_at',
+  'deleted_at',
+]) as ReadonlySet<string>
+
+/**
+ * Validate formula syntax to detect common syntax errors.
+ * Checks for patterns that would cause SQL syntax errors.
+ *
+ * @param formula - The formula expression to validate
+ * @returns Error message if invalid, undefined if valid
+ */
+const validateFormulaSyntax = (formula: string): string | undefined => {
+  // Remove string literals and regex patterns to avoid false positives
+  // String literals: 'text' or "text"
+  // Regex patterns: text ~ 'pattern' or text ~ '^pattern$'
+  const withoutLiterals = formula
+    .replace(/'[^']*'/g, '') // Remove single-quoted strings
+    .replace(/"[^"]*"/g, '') // Remove double-quoted strings
+
+  // Check for consecutive operators (e.g., "* *", "+ +", "- -")
+  // Only check outside of string literals and regex patterns
+  const consecutiveOperatorPattern = /[+\-*/%]\s*[+\-*/%]/
+  if (consecutiveOperatorPattern.test(withoutLiterals)) {
+    return 'Invalid formula syntax: consecutive operators detected'
+  }
+
+  // Check for unmatched parentheses
+  const openParens = (formula.match(/\(/g) || []).length
+  const closeParens = (formula.match(/\)/g) || []).length
+  if (openParens !== closeParens) {
+    return 'Invalid formula syntax: unmatched parentheses'
+  }
+
+  // Check for empty parentheses
+  if (/\(\s*\)/.test(formula)) {
+    return 'Invalid formula syntax: empty parentheses'
+  }
+
+  return undefined
+}
+
+/**
+ * Extract potential field references from a formula expression.
+ * This is a simplified parser that extracts identifiers (words) from the formula,
+ * excluding string literals (content within quotes).
+ * It doesn't handle complex syntax but catches common field reference patterns.
+ *
+ * @param formula - The formula expression to parse
+ * @returns Array of field names referenced in the formula
+ */
+export const extractFieldReferences = (formula: string): ReadonlyArray<string> => {
+  // Remove single-quoted and double-quoted string literals to avoid treating
+  // literal values as field names (e.g., 'World' in STRPOS(text, 'World'))
+  const withoutStringLiterals = formula
+    .replace(/'[^']*'/g, '') // Remove single-quoted strings
+    .replace(/"[^"]*"/g, '') // Remove double-quoted strings
+
+  // Match word characters (field names) - exclude function names and operators
+  // This regex matches identifiers that could be field names
+  const identifierPattern = /\b([a-z_][a-z0-9_]*)\b/gi
+  const matches = withoutStringLiterals.match(identifierPattern) || []
+
+  return matches
+    .map((match) => match.toLowerCase())
+    .filter((identifier) => !FORMULA_KEYWORDS.has(identifier))
+}
+
+/**
+ * Detect circular dependencies in formula fields using depth-first search.
+ * A circular dependency exists when a formula field references itself directly or indirectly
+ * through a chain of other formula fields.
+ *
+ * @param fields - Array of fields to validate
+ * @returns Array of field names involved in circular dependencies, or empty array if none found
+ */
+const detectCircularDependencies = (
+  fields: ReadonlyArray<{ readonly name: string; readonly type: string; readonly formula?: string }>
+): ReadonlyArray<string> => {
+  // Build dependency graph: field name -> fields it references
+  const dependencyGraph: ReadonlyMap<string, ReadonlyArray<string>> = new Map(
+    fields
+      .filter(
+        (field): field is typeof field & { formula: string } =>
+          'formula' in field && typeof field.formula === 'string'
+      )
+      .map((field) => [field.name, extractFieldReferences(field.formula)] as const)
+  )
+
+  // Use shared cycle detection utility
+  return detectCycles(dependencyGraph)
+}
+
+/**
+ * Validate formula fields in a table (syntax, field references, circular dependencies).
+ *
+ * @param fields - Array of fields to validate
+ * @returns Error object if invalid, undefined if valid
+ */
+export const validateFormulaFields = (
+  fields: ReadonlyArray<{ readonly name: string; readonly type: string; readonly formula?: string }>
+): { readonly message: string; readonly path: ReadonlyArray<string> } | undefined => {
+  const fieldNames = new Set(fields.map((field) => field.name))
+  const formulaFields = fields.filter(
+    (field): field is typeof field & { readonly formula: string } =>
+      field.type === 'formula' && typeof field.formula === 'string'
+  )
+
+  // Validate formula syntax first (before checking field references)
+  const syntaxError = formulaFields
+    .map((formulaField) => ({
+      field: formulaField,
+      error: validateFormulaSyntax(formulaField.formula),
+    }))
+    .find((result) => result.error !== undefined)
+
+  if (syntaxError?.error) {
+    return {
+      message: syntaxError.error,
+      path: ['fields'],
+    }
+  }
+
+  // Find the first invalid field reference across all formula fields
+  const invalidReference = formulaFields
+    .flatMap((formulaField) => {
+      const referencedFields = extractFieldReferences(formulaField.formula)
+      const invalidField = referencedFields.find(
+        (refField) => !fieldNames.has(refField) && !SPECIAL_FIELDS.has(refField)
+      )
+      return invalidField ? [{ formulaField, invalidField }] : []
+    })
+    .at(0)
+
+  if (invalidReference) {
+    return {
+      message: `Invalid field reference: field '${invalidReference.invalidField}' not found in formula '${invalidReference.formulaField.formula}'`,
+      path: ['fields'],
+    }
+  }
+
+  // Detect circular dependencies in formula fields
+  const circularFields = detectCircularDependencies(fields)
+  if (circularFields.length > 0) {
+    return {
+      message: `Circular dependency detected in formula fields: ${circularFields.join(' -> ')}`,
+      path: ['fields'],
+    }
+  }
+
+  return undefined
+}

package/src/domain/models/app/table/table-indexes-validation.ts

@@ -0,0 +1,38 @@
+/**
+ * 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.
+ */
+
+/**
+ * Validate that all index fields exist in the table.
+ *
+ * @param indexes - Array of index definitions
+ * @param fieldNames - Set of valid field names
+ * @returns Validation error object if invalid, undefined if valid
+ */
+export const validateIndexes = (
+  indexes: ReadonlyArray<{
+    readonly name: string
+    readonly fields: ReadonlyArray<string>
+  }>,
+  fieldNames: ReadonlySet<string>
+): { readonly message: string; readonly path: ReadonlyArray<string> } | undefined => {
+  const invalidIndex = indexes
+    .flatMap((index) =>
+      index.fields
+        .filter((fieldName) => !fieldNames.has(fieldName))
+        .map((fieldName) => ({ indexName: index.name, fieldName }))
+    )
+    .at(0)
+
+  if (invalidIndex) {
+    return {
+      message: `Index "${invalidIndex.indexName}" references non-existent column "${invalidIndex.fieldName}"`,
+      path: ['indexes'],
+    }
+  }
+
+  return undefined
+}