sovrium 0.0.2

package/src/domain/models/app/permissions/index.ts

@@ -0,0 +1,61 @@
+/**
+ * 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.
+ */
+
+/**
+ * Unified Permission Type Registry
+ *
+ * This module provides centralized, reusable permission-related schemas
+ * used across the authentication and authorization system.
+ *
+ * ## Permission Domains
+ *
+ * ### 1. Resource:Action Permissions
+ * Used for API access control (admin plugin, API keys).
+ * Pattern: `{ resource: [actions] }` where actions can include '*' for wildcard.
+ *
+ * ### 2. Role-Based Permissions
+ * Hierarchical roles (owner > admin > member > viewer) with predefined capabilities.
+ *
+ * ### 3. Table/Record Permissions
+ * Application-layer permission checking for data access control.
+ * See `@/domain/models/app/table/permissions/` for table-specific schemas.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import {
+ *   ResourceActionPermissionsSchema,
+ *   StandardRoleSchema,
+ * } from '@/domain/models/app/permissions'
+ * ```
+ */
+
+// Resource:Action pattern for API permissions
+export {
+  ResourceActionPermissionsSchema,
+  ResourceNameSchema,
+  ActionNameSchema,
+  ActionWithWildcardSchema,
+  type ResourceActionPermissions,
+  type ResourceName,
+  type ActionName,
+  type ActionWithWildcard,
+} from './resource-action'
+
+// Role definitions
+export {
+  StandardRoleSchema,
+  AdminLevelRoleSchema,
+  UserLevelRoleSchema,
+  FlexibleRolesSchema,
+  StandardRolesArraySchema,
+  type StandardRole,
+  type AdminLevelRole,
+  type UserLevelRole,
+  type FlexibleRoles,
+  type StandardRolesArray,
+} from './roles'

package/src/domain/models/app/permissions/resource-action.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 { Schema } from 'effect'
+
+/**
+ * Resource Name Schema
+ *
+ * Validates resource names in the resource:action permission pattern.
+ * Must start with a letter and contain only lowercase letters, numbers, underscores, or hyphens.
+ *
+ * @example
+ * Valid: "users", "posts", "api_keys", "user-profiles"
+ * Invalid: "123users", "_posts", "User Posts"
+ */
+export const ResourceNameSchema = Schema.String.pipe(
+  Schema.pattern(/^[a-z][a-z0-9_-]*$/i),
+  Schema.annotations({
+    title: 'Resource Name',
+    description: 'Resource identifier (e.g., "users", "posts", "analytics")',
+    examples: ['users', 'posts', 'api_keys', 'user-profiles'],
+  })
+)
+
+export type ResourceName = Schema.Schema.Type<typeof ResourceNameSchema>
+
+/**
+ * Action Name Schema
+ *
+ * Validates action names in the resource:action permission pattern.
+ * Must start with a letter and contain only lowercase letters, numbers, underscores, or hyphens.
+ *
+ * @example
+ * Valid: "read", "write", "create", "delete", "list_all"
+ * Invalid: "123read", "_write"
+ */
+export const ActionNameSchema = Schema.String.pipe(
+  Schema.pattern(/^[a-z][a-z0-9_-]*$/i),
+  Schema.annotations({
+    title: 'Action Name',
+    description: 'Action identifier (e.g., "read", "write", "create", "delete")',
+    examples: ['read', 'write', 'create', 'update', 'delete', 'list'],
+  })
+)
+
+export type ActionName = Schema.Schema.Type<typeof ActionNameSchema>
+
+/**
+ * Action with Wildcard Schema
+ *
+ * Either a specific action name or "*" for all actions on a resource.
+ */
+export const ActionWithWildcardSchema = Schema.Union(Schema.Literal('*'), ActionNameSchema).pipe(
+  Schema.annotations({
+    title: 'Action',
+    description: 'Action name or "*" for all actions',
+    examples: ['read', 'write', '*'],
+  })
+)
+
+export type ActionWithWildcard = Schema.Schema.Type<typeof ActionWithWildcardSchema>
+
+/**
+ * Resource:Action Permissions Schema (Shared)
+ *
+ * Defines granular permissions using the resource:action pattern.
+ * Each resource maps to an array of allowed actions.
+ *
+ * This schema is shared between:
+ * - Admin plugin (customPermissions)
+ * - API Keys plugin (resourcePermissions)
+ * - Any future permission-based features
+ *
+ * @example
+ * ```typescript
+ * {
+ *   users: ['read', 'list'],
+ *   posts: ['create', 'read', 'update', 'delete'],
+ *   analytics: ['*']  // Wildcard for all actions
+ * }
+ * ```
+ */
+export const ResourceActionPermissionsSchema = Schema.Record({
+  key: ResourceNameSchema.pipe(
+    Schema.annotations({ description: 'Resource name (e.g., "users", "posts")' })
+  ),
+  value: Schema.Array(ActionWithWildcardSchema).pipe(
+    Schema.minItems(1),
+    Schema.annotations({ description: 'Allowed actions for this resource' })
+  ),
+}).pipe(
+  Schema.annotations({
+    title: 'Resource:Action Permissions',
+    description:
+      'Granular permission definitions using resource:action pattern. Shared across admin, API keys, and other permission contexts.',
+    examples: [
+      {
+        users: ['read', 'list'],
+        posts: ['create', 'read', 'update', 'delete'],
+        analytics: ['*'],
+      },
+      {
+        comments: ['create', 'read', 'delete'],
+        media: ['*'],
+      },
+    ],
+  })
+)
+
+export type ResourceActionPermissions = Schema.Schema.Type<typeof ResourceActionPermissionsSchema>

package/src/domain/models/app/permissions/roles.ts

@@ -0,0 +1,120 @@
+/**
+ * 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'
+
+/**
+ * Standard Role Schema
+ *
+ * The three built-in roles used across the authentication system.
+ * These roles have well-defined hierarchies and permissions.
+ *
+ * Role Hierarchy (highest to lowest):
+ * - `admin`: Can manage members and settings
+ * - `member`: Standard access to organization resources
+ * - `viewer`: Read-only access
+ *
+ * @example
+ * ```typescript
+ * defaultRole: 'member'
+ * creatorRole: 'admin'
+ * ```
+ */
+export const StandardRoleSchema = Schema.Literal('admin', 'member', 'viewer').pipe(
+  Schema.annotations({
+    title: 'Standard Role',
+    description: 'Built-in role with predefined permissions. Hierarchy: admin > member > viewer',
+    examples: ['admin', 'member', 'viewer'],
+  })
+)
+
+export type StandardRole = Schema.Schema.Type<typeof StandardRoleSchema>
+
+/**
+ * Admin-Level Role Schema
+ *
+ * Subset of roles with administrative capabilities.
+ * Used for features like role creation/assignment restrictions.
+ */
+export const AdminLevelRoleSchema = Schema.Literal('admin').pipe(
+  Schema.annotations({
+    title: 'Admin-Level Role',
+    description: 'Roles with administrative capabilities (admin)',
+    examples: ['admin'],
+  })
+)
+
+export type AdminLevelRole = Schema.Schema.Type<typeof AdminLevelRoleSchema>
+
+/**
+ * User-Level Role Schema
+ *
+ * Subset of standard roles for default user role assignment.
+ * Used in admin plugin for defaultRole configuration.
+ */
+export const UserLevelRoleSchema = Schema.String.pipe(
+  Schema.filter(
+    (value): value is 'admin' | 'member' | 'viewer' => {
+      return value === 'admin' || value === 'member' || value === 'viewer'
+    },
+    {
+      message: () => 'Invalid role. Must be one of: admin, member, viewer',
+    }
+  ),
+  Schema.annotations({
+    title: 'User-Level Role',
+    description: 'Roles available for default user assignment in admin context',
+    examples: ['admin', 'member', 'viewer'],
+  })
+)
+
+export type UserLevelRole = Schema.Schema.Type<typeof UserLevelRoleSchema>
+
+/**
+ * Flexible Roles Schema
+ *
+ * Array of role names as strings for table permissions.
+ * Allows both standard roles and custom role names.
+ *
+ * Use this when:
+ * - Custom roles are supported (dynamic roles feature)
+ * - Role names come from user configuration
+ * - Flexibility is more important than strict validation
+ *
+ * @example
+ * ```typescript
+ * roles: ['admin', 'editor', 'custom-role']
+ * ```
+ */
+export const FlexibleRolesSchema = Schema.Array(Schema.String).pipe(
+  Schema.minItems(1),
+  Schema.annotations({
+    title: 'Flexible Roles',
+    description:
+      'Array of role names (supports both standard and custom roles). At least one role required.',
+    examples: [['admin'], ['admin', 'member'], ['admin', 'editor', 'custom-role']],
+  })
+)
+
+export type FlexibleRoles = Schema.Schema.Type<typeof FlexibleRolesSchema>
+
+/**
+ * Standard Roles Array Schema
+ *
+ * Array of standard roles only (no custom roles).
+ * Use for strict validation when only built-in roles are allowed.
+ */
+export const StandardRolesArraySchema = Schema.Array(StandardRoleSchema).pipe(
+  Schema.minItems(1),
+  Schema.annotations({
+    title: 'Standard Roles Array',
+    description: 'Array of standard roles only (admin, member, viewer)',
+    examples: [['admin'], ['admin', 'member'], ['admin', 'member', 'viewer']],
+  })
+)
+
+export type StandardRolesArray = Schema.Schema.Type<typeof StandardRolesArraySchema>

package/src/domain/models/app/table/check-constraints.ts

@@ -0,0 +1,105 @@
+/**
+ * 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'
+
+/**
+ * Check Constraint Schema
+ *
+ * Defines a custom CHECK constraint that validates data at the database level.
+ * CHECK constraints allow you to enforce complex business rules beyond basic
+ * field-level validation.
+ *
+ * @example
+ * ```typescript
+ * const constraint = {
+ *   name: 'chk_active_members_have_email',
+ *   check: '(is_active = false) OR (email IS NOT NULL)'
+ * }
+ * ```
+ */
+export const CheckConstraintSchema = Schema.Struct({
+  /**
+   * Constraint name (must be unique within the table)
+   */
+  name: Schema.String.pipe(
+    Schema.minLength(1),
+    Schema.pattern(/^[a-z][a-z0-9_]*$/),
+    Schema.annotations({
+      title: 'Constraint Name',
+      description:
+        'Unique name for the CHECK constraint (lowercase, alphanumeric with underscores)',
+      examples: ['chk_active_members_have_email', 'chk_price_positive', 'chk_end_after_start'],
+    })
+  ),
+
+  /**
+   * SQL check expression
+   */
+  check: Schema.String.pipe(
+    Schema.minLength(1),
+    Schema.annotations({
+      title: 'Check Expression',
+      description: 'PostgreSQL boolean expression that must evaluate to TRUE for valid data',
+      examples: [
+        '(is_active = false) OR (email IS NOT NULL)',
+        'price > 0',
+        'end_date > start_date',
+        "(status = 'completed') OR (completed_at IS NULL)",
+      ],
+    })
+  ),
+})
+
+export type CheckConstraint = Schema.Schema.Type<typeof CheckConstraintSchema>
+
+/**
+ * Check Constraints Schema
+ *
+ * Array of CHECK constraints applied at the table level.
+ *
+ * @example
+ * ```typescript
+ * const constraints = [
+ *   {
+ *     name: 'chk_active_members_have_email',
+ *     check: '(is_active = false) OR (email IS NOT NULL)'
+ *   },
+ *   {
+ *     name: 'chk_price_positive',
+ *     check: 'price > 0'
+ *   }
+ * ]
+ * ```
+ */
+export const CheckConstraintsSchema = Schema.Array(CheckConstraintSchema).pipe(
+  Schema.annotations({
+    title: 'Check Constraints',
+    description:
+      'Table-level CHECK constraints for enforcing complex business rules beyond field-level validation',
+    examples: [
+      [
+        {
+          name: 'chk_active_members_have_email',
+          check: '(is_active = false) OR (email IS NOT NULL)',
+        },
+      ],
+      [
+        {
+          name: 'chk_price_positive',
+          check: 'price > 0',
+        },
+        {
+          name: 'chk_end_after_start',
+          check: 'end_date > start_date',
+        },
+      ],
+    ],
+  })
+)
+
+export type CheckConstraints = Schema.Schema.Type<typeof CheckConstraintsSchema>

package/src/domain/models/app/table/cycle-detection.ts

@@ -0,0 +1,124 @@
+/**
+ * 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.
+ */
+
+/**
+ * Shared cycle detection utilities using depth-first search (DFS)
+ * Used for detecting circular dependencies in both formula fields and table relationships
+ */
+
+/**
+ * State tracked during DFS traversal
+ */
+type DFSState = {
+  readonly visited: ReadonlySet<string>
+  readonly recursionStack: ReadonlySet<string>
+  readonly cycleNodes: ReadonlyArray<string>
+}
+
+/**
+ * Result of cycle detection
+ */
+type CycleResult = {
+  readonly found: boolean
+  readonly state: DFSState
+}
+
+/**
+ * Detect cycles in a dependency graph using depth-first search (DFS)
+ *
+ * @param dependencyGraph - Map of node name to array of nodes it depends on
+ * @returns Array of node names involved in circular dependencies, or empty array if none found
+ *
+ * @example
+ * ```typescript
+ * const graph = new Map([
+ *   ['A', ['B']],
+ *   ['B', ['C']],
+ *   ['C', ['A']], // Circular: A -> B -> C -> A
+ * ])
+ * detectCycles(graph) // ['A', 'B', 'C']
+ * ```
+ */
+export const detectCycles = (
+  dependencyGraph: ReadonlyMap<string, ReadonlyArray<string>>
+): ReadonlyArray<string> => {
+  const hasCycle = (node: string, state: DFSState): CycleResult => {
+    if (state.recursionStack.has(node)) {
+      // Cycle detected - add to result
+      return {
+        found: true,
+        state: {
+          ...state,
+          cycleNodes: [...state.cycleNodes, node],
+        },
+      }
+    }
+
+    if (state.visited.has(node)) {
+      // Already processed this node
+      return { found: false, state }
+    }
+
+    const newState: DFSState = {
+      visited: new Set([...state.visited, node]),
+      recursionStack: new Set([...state.recursionStack, node]),
+      cycleNodes: state.cycleNodes,
+    }
+
+    const dependencies = dependencyGraph.get(node) || []
+    const result = dependencies.reduce<CycleResult>(
+      (acc, dep) => {
+        if (acc.found || !dependencyGraph.has(dep)) {
+          return acc
+        }
+        const depResult = hasCycle(dep, acc.state)
+        if (depResult.found) {
+          // Propagate cycle detection
+          const cycleNodes = depResult.state.cycleNodes.includes(node)
+            ? depResult.state.cycleNodes
+            : [...depResult.state.cycleNodes, node]
+          return {
+            found: true,
+            state: {
+              ...depResult.state,
+              cycleNodes,
+            },
+          }
+        }
+        return depResult
+      },
+      { found: false, state: newState }
+    )
+
+    // Remove from recursion stack after processing (immutable way)
+    const finalState: DFSState = {
+      ...result.state,
+      recursionStack: new Set([...result.state.recursionStack].filter((n) => n !== node)),
+    }
+
+    return { found: result.found, state: finalState }
+  }
+
+  // Check all nodes for cycles
+  const initialState: DFSState = {
+    visited: new Set(),
+    recursionStack: new Set(),
+    cycleNodes: [],
+  }
+
+  const result = [...dependencyGraph.keys()].reduce<CycleResult>(
+    (acc, nodeName) => {
+      if (acc.found || acc.state.visited.has(nodeName)) {
+        return acc
+      }
+      return hasCycle(nodeName, acc.state)
+    },
+    { found: false, state: initialState }
+  )
+
+  return result.state.cycleNodes
+}

package/src/domain/models/app/table/database-identifier.ts

@@ -0,0 +1,153 @@
+/**
+ * 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'
+
+/**
+ * Reserved SQL keywords that cannot be used as table or column names
+ * Based on PostgreSQL reserved keywords list
+ * @see https://www.postgresql.org/docs/current/sql-keywords-appendix.html
+ */
+const SQL_RESERVED_KEYWORDS = new Set([
+  'select',
+  'insert',
+  'update',
+  'delete',
+  'from',
+  'where',
+  'join',
+  'inner',
+  'outer',
+  'left',
+  'right',
+  'full',
+  'cross',
+  'on',
+  'as',
+  'table',
+  'create',
+  'alter',
+  'drop',
+  'truncate',
+  'add',
+  'column',
+  'constraint',
+  'primary',
+  'foreign',
+  'key',
+  'references',
+  'unique',
+  'index',
+  'view',
+  'database',
+  'schema',
+  'grant',
+  'revoke',
+  'transaction',
+  'commit',
+  'rollback',
+  'union',
+  'intersect',
+  'except',
+  'group',
+  'having',
+  'order',
+  'limit',
+  'offset',
+  'distinct',
+  'all',
+  'any',
+  'some',
+  'exists',
+  'in',
+  'between',
+  'like',
+  'ilike',
+  'and',
+  'or',
+  'not',
+  'null',
+  'is',
+  'true',
+  'false',
+  'case',
+  'when',
+  'then',
+  'else',
+  'end',
+  'cast',
+  'default',
+  'check',
+  'user',
+  'current_user',
+  'session_user',
+  'current_date',
+  'current_time',
+  'current_timestamp',
+])
+
+/**
+ * Database Identifier Validation (Strict - for field names and column names)
+ *
+ * Shared validation schema for PostgreSQL identifiers (column names, field names, etc.)
+ * Must follow database naming conventions: start with a letter, contain only lowercase
+ * letters, numbers, and underscores, maximum 63 characters (PostgreSQL limit).
+ *
+ * This schema is used for field names and column names which must be strict.
+ *
+ * @example
+ * ```typescript
+ * 'users'
+ * 'email_address'
+ * 'created_at'
+ * ```
+ */
+export const createDatabaseIdentifierSchema = (identifierType: 'table' | 'field' | 'column') =>
+  identifierType === 'table'
+    ? // Table names: Allow user-friendly format (will be sanitized for database)
+      Schema.String.pipe(
+        Schema.minLength(1, { message: () => 'This field is required' }),
+        Schema.maxLength(63, { message: () => 'Maximum length is 63 characters' }),
+        Schema.filter((name) => {
+          const trimmed = name.trim()
+          if (/^\d/.test(trimmed)) {
+            return `Invalid table name '${name}': name must start with a letter`
+          }
+          if (!/^[a-zA-Z][a-zA-Z0-9_\s-]*$/.test(trimmed)) {
+            return `Invalid table name '${name}': name must start with a letter and contain only letters, numbers, underscores, hyphens, or spaces`
+          }
+          return true
+        }),
+        Schema.filter((name) => {
+          const sanitized = name
+            .toLowerCase()
+            .replace(/[^a-z0-9_]/g, '_')
+            .replace(/_+/g, '_')
+            .replace(/^_+|_+$/g, '')
+          const isReserved = SQL_RESERVED_KEYWORDS.has(sanitized)
+          return (
+            !isReserved ||
+            `Table name '${name}' resolves to reserved SQL keyword '${sanitized}'. Reserved keywords like SELECT, INSERT, UPDATE, DELETE, etc. are restricted to prevent SQL syntax conflicts. Choose a different name.`
+          )
+        })
+      )
+    : // Field/column names: Strict database pattern
+      Schema.String.pipe(
+        Schema.minLength(1, { message: () => 'This field is required' }),
+        Schema.maxLength(63, { message: () => 'Maximum length is 63 characters' }),
+        Schema.pattern(/^[a-z][a-z0-9_]*$/, {
+          message: () =>
+            `Invalid ${identifierType} name pattern. Must follow database naming conventions: start with a letter, contain only lowercase letters, numbers, and underscores, maximum 63 characters (PostgreSQL limit). This name is used in SQL queries, API endpoints, and code generation. Choose descriptive names that clearly indicate the purpose (e.g., "email_address" not "ea").`,
+        }),
+        Schema.filter((name) => {
+          const isReserved = SQL_RESERVED_KEYWORDS.has(name.toLowerCase())
+          return (
+            !isReserved ||
+            `Cannot use reserved SQL keyword '${name}' as ${identifierType} name. Reserved keywords like SELECT, INSERT, UPDATE, DELETE, etc. are restricted to prevent SQL syntax conflicts. Choose a descriptive alternative name (e.g., 'user_record' instead of 'user', 'selection' instead of 'select').`
+          )
+        })
+      )