sovrium 0.0.2

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

@@ -0,0 +1,230 @@
+/**
+ * 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'
+import { AuthEmailTemplatesSchema } from './config'
+import { TwoFactorConfigSchema } from './plugins/two-factor'
+import { DefaultRoleSchema, RolesConfigSchema } from './roles'
+import { AuthStrategiesSchema, type AuthStrategy } from './strategies'
+
+// Re-export all auth-related schemas and types for convenient imports
+export * from './config'
+export * from './methods/email-and-password'
+export * from './methods/magic-link'
+export * from './oauth'
+export * from './plugins/admin'
+export * from './plugins/two-factor'
+export * from './roles'
+export * from './strategies'
+
+/**
+ * Strategy type names
+ */
+type StrategyType = 'emailAndPassword' | 'magicLink' | 'oauth'
+
+/**
+ * Check if a specific strategy type is present in the strategies array
+ */
+export const hasStrategy = (auth: Auth | undefined, strategyType: StrategyType): boolean => {
+  if (!auth?.strategies) return false
+  return auth.strategies.some((s) => s.type === strategyType)
+}
+
+/**
+ * Get a specific strategy configuration by type
+ */
+export const getStrategy = <T extends StrategyType>(
+  auth: Auth | undefined,
+  strategyType: T
+): Extract<AuthStrategy, { readonly type: T }> | undefined => {
+  if (!auth?.strategies) return undefined
+  return auth.strategies.find((s) => s.type === strategyType) as
+    | Extract<AuthStrategy, { readonly type: T }>
+    | undefined
+}
+
+/**
+ * Get all strategy type names that are enabled
+ */
+export const getEnabledStrategies = (auth: Auth | undefined): readonly StrategyType[] => {
+  if (!auth?.strategies) return []
+  return auth.strategies.map((s) => s.type)
+}
+
+// Legacy aliases for backward compatibility during migration
+export const isMethodEnabled = (auth: Auth | undefined, method: StrategyType): boolean =>
+  hasStrategy(auth, method)
+
+export const getEnabledMethods = (auth: Auth | undefined): readonly StrategyType[] =>
+  getEnabledStrategies(auth)
+
+export const hasAnyMethodEnabled = (auth: Auth | undefined): boolean =>
+  (auth?.strategies?.length ?? 0) > 0
+
+/**
+ * Authentication Configuration Schema
+ *
+ * Comprehensive authentication configuration supporting all Better Auth features.
+ * If this config exists, authentication is enabled.
+ * If omitted from the app config, no auth endpoints are available.
+ *
+ * Admin features (user management, role assignment, impersonation) are always
+ * enabled when auth is configured — no separate toggle needed.
+ *
+ * Infrastructure configuration (secrets, URLs, credentials) is handled via
+ * environment variables, not in this schema. See .env.example for details.
+ *
+ * Structure:
+ * - strategies: Array of authentication strategy objects (required, at least one)
+ * - roles: Custom role definitions with hierarchy (optional)
+ * - defaultRole: Role assigned to new users (optional, defaults to 'member')
+ * - twoFactor: TOTP-based two-factor authentication (optional)
+ * - emailTemplates: Custom email templates (optional)
+ *
+ * @example
+ * ```typescript
+ * // Minimal
+ * { strategies: [{ type: 'emailAndPassword' }] }
+ *
+ * // With custom roles and defaultRole
+ * {
+ *   strategies: [{ type: 'emailAndPassword', minPasswordLength: 12 }],
+ *   defaultRole: 'viewer',
+ *   roles: [{ name: 'editor', description: 'Can edit content', level: 30 }]
+ * }
+ *
+ * // Multiple strategies
+ * {
+ *   strategies: [
+ *     { type: 'emailAndPassword' },
+ *     { type: 'oauth', providers: ['google', 'github'] }
+ *   ]
+ * }
+ * ```
+ */
+export const AuthSchema = Schema.Struct({
+  // ============================================================================
+  // Authentication Strategies (required)
+  // ============================================================================
+
+  /**
+   * Array of authentication strategies.
+   * At least one strategy must be defined. No duplicate types allowed.
+   */
+  strategies: AuthStrategiesSchema,
+
+  // ============================================================================
+  // Role Configuration (optional)
+  // ============================================================================
+
+  /**
+   * Custom role definitions (optional)
+   *
+   * Define additional roles beyond the built-in ones (admin, member, viewer).
+   * Empty array means only built-in roles are available.
+   */
+  roles: Schema.optional(RolesConfigSchema),
+
+  /**
+   * Default role for new users (optional)
+   *
+   * Role assigned to users on registration. Defaults to 'member'.
+   * Must reference a built-in role or a custom role name.
+   */
+  defaultRole: Schema.optional(DefaultRoleSchema),
+
+  // ============================================================================
+  // Feature Extensions (optional)
+  // ============================================================================
+
+  /**
+   * Two-factor authentication plugin configuration (optional)
+   *
+   * Enable TOTP-based two-factor authentication. Users can set up 2FA
+   * using authenticator apps. Requires emailAndPassword strategy.
+   */
+  twoFactor: Schema.optional(TwoFactorConfigSchema),
+
+  /**
+   * Email templates for authentication flows (optional)
+   *
+   * Customize the subject and content of emails sent during authentication.
+   * Templates support variable substitution using $variable syntax.
+   */
+  emailTemplates: Schema.optional(AuthEmailTemplatesSchema),
+}).pipe(
+  Schema.filter((config) => {
+    // Validate two-factor requires emailAndPassword strategy
+    if (config.twoFactor) {
+      const hasEmailPassword = config.strategies.some((s) => s.type === 'emailAndPassword')
+      if (!hasEmailPassword) {
+        return 'Two-factor authentication requires emailAndPassword strategy'
+      }
+    }
+
+    // Validate defaultRole references a defined role (if custom role name)
+    if (config.defaultRole && config.roles) {
+      const builtInRoles = ['admin', 'member', 'viewer']
+      const customRoleNames = config.roles.map((r) => r.name)
+      const allValidRoles = [...builtInRoles, ...customRoleNames]
+      if (!allValidRoles.includes(config.defaultRole)) {
+        return `Default role '${config.defaultRole}' is not a built-in role or defined in auth.roles`
+      }
+    }
+
+    return undefined
+  }),
+  Schema.annotations({
+    title: 'Authentication Configuration',
+    description:
+      'Authentication configuration with strategies, roles, and plugins. Admin features are always enabled when auth is configured.',
+    examples: [
+      { strategies: [{ type: 'emailAndPassword' as const }] },
+      {
+        strategies: [{ type: 'emailAndPassword' as const, minPasswordLength: 12 }],
+        defaultRole: 'viewer',
+        roles: [{ name: 'editor', description: 'Can edit content', level: 30 }],
+      },
+      {
+        strategies: [
+          { type: 'emailAndPassword' as const },
+          { type: 'oauth' as const, providers: ['google', 'github'] },
+        ],
+      },
+    ],
+  })
+)
+
+/**
+ * TypeScript type inferred from AuthSchema
+ */
+export type Auth = Schema.Schema.Type<typeof AuthSchema>
+
+/**
+ * Encoded type of AuthSchema (what goes in before validation)
+ */
+export type AuthEncoded = Schema.Schema.Encoded<typeof AuthSchema>
+
+/**
+ * Helper to check if auth is configured with a specific strategy
+ */
+export const hasAuthenticationMethod = (auth: Auth, strategyType: StrategyType): boolean =>
+  hasStrategy(auth, strategyType)
+
+/**
+ * Plugin names that can be checked
+ */
+type PluginName = 'twoFactor'
+
+/**
+ * Helper to check if auth has a specific plugin enabled
+ */
+export const hasPlugin = (auth: Auth, pluginName: PluginName): boolean => {
+  const plugin = auth[pluginName]
+  if (typeof plugin === 'boolean') return plugin
+  return plugin !== undefined
+}

package/src/domain/models/app/auth/methods/email-and-password.ts

@@ -0,0 +1,67 @@
+/**
+ * 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'
+
+/**
+ * Email and Password Authentication Method Configuration
+ *
+ * Traditional credential-based authentication using email and password.
+ * This is the most common authentication method.
+ *
+ * Can be:
+ * - A boolean (true to enable with defaults)
+ * - A configuration object for customization
+ *
+ * Configuration options:
+ * - requireEmailVerification: Require email verification before allowing sign-in
+ * - minPasswordLength: Minimum password length (default: 8, range: 6-128)
+ * - maxPasswordLength: Maximum password length (default: 128)
+ *
+ * @example
+ * ```typescript
+ * // Simple enable (as strategy)
+ * { type: 'emailAndPassword' }
+ *
+ * // With configuration
+ * {
+ *   type: 'emailAndPassword',
+ *   requireEmailVerification: true,
+ *   minPasswordLength: 12
+ * }
+ * ```
+ */
+export const EmailAndPasswordConfigSchema = Schema.Union(
+  Schema.Boolean,
+  Schema.Struct({
+    requireEmailVerification: Schema.optional(
+      Schema.Boolean.pipe(
+        Schema.annotations({ description: 'Require email verification before sign-in' })
+      )
+    ),
+    minPasswordLength: Schema.optional(
+      Schema.Number.pipe(
+        Schema.between(6, 128),
+        Schema.annotations({ description: 'Minimum password length (6-128)' })
+      )
+    ),
+    maxPasswordLength: Schema.optional(
+      Schema.Number.pipe(
+        Schema.between(8, 256),
+        Schema.annotations({ description: 'Maximum password length (8-256)' })
+      )
+    ),
+  })
+).pipe(
+  Schema.annotations({
+    title: 'Email and Password Configuration',
+    description: 'Configuration for email and password authentication',
+    examples: [true, { requireEmailVerification: true }, { minPasswordLength: 12 }],
+  })
+)
+
+export type EmailAndPasswordConfig = Schema.Schema.Type<typeof EmailAndPasswordConfigSchema>

package/src/domain/models/app/auth/methods/index.ts

@@ -0,0 +1,11 @@
+/**
+ * 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.
+ */
+
+// Export individual method schemas
+// These are used directly in the flattened AuthSchema
+export * from './email-and-password'
+export * from './magic-link'

package/src/domain/models/app/auth/methods/magic-link.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 { Schema } from 'effect'
+
+/**
+ * Magic Link Authentication Method Configuration
+ *
+ * Passwordless authentication via email link.
+ * User receives an email with a one-time link to sign in.
+ *
+ * Can be:
+ * - A boolean (true to enable with defaults)
+ * - A configuration object for customization
+ *
+ * Configuration options:
+ * - expirationMinutes: How long the magic link is valid (default: 15)
+ *
+ * @example
+ * ```typescript
+ * // Simple enable
+ * { magicLink: true }
+ *
+ * // With configuration
+ * {
+ *   magicLink: {
+ *     expirationMinutes: 30
+ *   }
+ * }
+ * ```
+ */
+export const MagicLinkConfigSchema = Schema.Union(
+  Schema.Boolean,
+  Schema.Struct({
+    expirationMinutes: Schema.optional(
+      Schema.Number.pipe(
+        Schema.positive(),
+        Schema.annotations({ description: 'Link expiration time in minutes' })
+      )
+    ),
+  })
+).pipe(
+  Schema.annotations({
+    title: 'Magic Link Configuration',
+    description: 'Configuration for magic link authentication',
+    examples: [true, { expirationMinutes: 30 }],
+  })
+)
+
+export type MagicLinkConfig = Schema.Schema.Type<typeof MagicLinkConfigSchema>

package/src/domain/models/app/auth/oauth/index.ts

@@ -0,0 +1,8 @@
+/**
+ * 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.
+ */
+
+export * from './providers'

package/src/domain/models/app/auth/oauth/providers.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'
+
+/**
+ * OAuth Provider Schema
+ *
+ * Essential OAuth providers for v1.
+ * Focused on enterprise and developer use cases.
+ *
+ * Providers:
+ * - google: Google Workspace integration
+ * - github: Developer authentication
+ * - microsoft: Enterprise/Azure AD
+ * - slack: Workspace communication
+ * - gitlab: Developer/CI-CD integration
+ *
+ * Credentials are loaded from environment variables:
+ * - {PROVIDER}_CLIENT_ID (e.g., GOOGLE_CLIENT_ID)
+ * - {PROVIDER}_CLIENT_SECRET (e.g., GOOGLE_CLIENT_SECRET)
+ *
+ * @example
+ * ```typescript
+ * const providers = ['google', 'github', 'slack']
+ * ```
+ */
+export const OAuthProviderSchema = Schema.Literal(
+  'google',
+  'github',
+  'microsoft',
+  'slack',
+  'gitlab'
+).pipe(
+  Schema.annotations({
+    title: 'OAuth Provider',
+    description: 'Supported OAuth providers for social login',
+  })
+)
+
+export type OAuthProvider = Schema.Schema.Type<typeof OAuthProviderSchema>
+
+/**
+ * OAuth Configuration Schema
+ *
+ * Simple provider list using environment variables for credentials.
+ * For each provider enabled, the system expects:
+ * - {PROVIDER}_CLIENT_ID environment variable
+ * - {PROVIDER}_CLIENT_SECRET environment variable
+ *
+ * @example
+ * ```typescript
+ * // Enable Google and GitHub OAuth
+ * { providers: ['google', 'github'] }
+ *
+ * // Required environment variables:
+ * // GOOGLE_CLIENT_ID=your-google-client-id
+ * // GOOGLE_CLIENT_SECRET=your-google-client-secret
+ * // GITHUB_CLIENT_ID=your-github-client-id
+ * // GITHUB_CLIENT_SECRET=your-github-client-secret
+ * ```
+ */
+export const OAuthConfigSchema = Schema.Struct({
+  /** List of OAuth providers to enable */
+  providers: Schema.NonEmptyArray(OAuthProviderSchema),
+}).pipe(
+  Schema.annotations({
+    title: 'OAuth Configuration',
+    description:
+      'OAuth social login configuration. Credentials loaded from environment variables ({PROVIDER}_CLIENT_ID, {PROVIDER}_CLIENT_SECRET).',
+    examples: [
+      { providers: ['google'] },
+      { providers: ['google', 'github'] },
+      { providers: ['google', 'github', 'microsoft'] },
+    ],
+  })
+)
+
+export type OAuthConfig = Schema.Schema.Type<typeof OAuthConfigSchema>
+
+/**
+ * Get environment variable names for a provider
+ *
+ * @param provider - OAuth provider name
+ * @returns Object with clientId and clientSecret env var names
+ *
+ * @example
+ * ```typescript
+ * getProviderEnvVars('google')
+ * // Returns: { clientId: 'GOOGLE_CLIENT_ID', clientSecret: 'GOOGLE_CLIENT_SECRET' }
+ * ```
+ */
+export const getProviderEnvVars = (
+  provider: OAuthProvider
+): { readonly clientId: string; readonly clientSecret: string } => {
+  const upper = provider.toUpperCase()
+  return {
+    clientId: `${upper}_CLIENT_ID`,
+    clientSecret: `${upper}_CLIENT_SECRET`,
+  }
+}

package/src/domain/models/app/auth/plugins/admin.ts

@@ -0,0 +1,130 @@
+/**
+ * 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'
+import {
+  ResourceActionPermissionsSchema,
+  UserLevelRoleSchema,
+} from '@/domain/models/app/permissions'
+
+/**
+ * Role Management Configuration
+ *
+ * Controls admin role assignment and revocation capabilities.
+ * Presence of this config enables role management features.
+ */
+export const RoleManagementSchema = Schema.Struct({
+  assignAdmin: Schema.optional(
+    Schema.Boolean.pipe(
+      Schema.annotations({ description: 'Allow admins to grant admin role to users' })
+    )
+  ),
+  revokeAdmin: Schema.optional(
+    Schema.Boolean.pipe(
+      Schema.annotations({ description: 'Allow admins to revoke admin role from users' })
+    )
+  ),
+  preventSelfRevocation: Schema.optional(
+    Schema.Boolean.pipe(
+      Schema.annotations({ description: 'Prevent admins from revoking their own admin role' })
+    )
+  ),
+}).pipe(
+  Schema.annotations({
+    title: 'Role Management',
+    description: 'Admin role assignment and revocation capabilities',
+    examples: [{ assignAdmin: true, revokeAdmin: true, preventSelfRevocation: true }],
+  })
+)
+
+export type RoleManagement = Schema.Schema.Type<typeof RoleManagementSchema>
+
+/**
+ * Admin Plugin Configuration
+ *
+ * Enables administrative features for user management.
+ * Includes capabilities for managing roles, impersonating users,
+ * and custom permissions.
+ *
+ * Configuration options:
+ * - impersonation: Allow admins to impersonate other users
+ * - userManagement: Enable user CRUD operations
+ * - firstUserAdmin: Make first registered user an admin
+ * - defaultRole: Default role for new users
+ * - customPermissions: Granular resource:action permissions
+ * - roleManagement: Admin role assignment/revocation
+ *
+ * Default admin user is configured via environment variables:
+ * - ADMIN_EMAIL: Admin email address
+ * - ADMIN_PASSWORD: Admin password
+ * - ADMIN_NAME: Admin display name (optional)
+ *
+ * @example
+ * ```typescript
+ * // Simple enable
+ * { plugins: { admin: true } }
+ *
+ * // With configuration
+ * { plugins: { admin: { impersonation: true, firstUserAdmin: true } } }
+ *
+ * // With custom permissions
+ * { plugins: { admin: {
+ *   customPermissions: {
+ *     posts: ['create', 'read', 'update', 'delete'],
+ *     analytics: ['read']
+ *   }
+ * } } }
+ * ```
+ */
+export const AdminConfigSchema = Schema.Union(
+  Schema.Boolean,
+  Schema.Struct({
+    // ========== Existing Fields ==========
+    impersonation: Schema.optional(
+      Schema.Boolean.pipe(Schema.annotations({ description: 'Allow admin impersonation of users' }))
+    ),
+    userManagement: Schema.optional(
+      Schema.Boolean.pipe(Schema.annotations({ description: 'Enable user management features' }))
+    ),
+
+    // ========== Admin Options ==========
+    firstUserAdmin: Schema.optional(
+      Schema.Boolean.pipe(
+        Schema.annotations({ description: 'Automatically make the first registered user an admin' })
+      )
+    ),
+    defaultRole: Schema.optional(
+      UserLevelRoleSchema.pipe(
+        Schema.annotations({
+          description: 'Default role assigned to new users',
+          message: () => 'Invalid default role. Must be one of: admin, member, viewer',
+        })
+      )
+    ),
+
+    // ========== Advanced Features ==========
+    customPermissions: Schema.optional(ResourceActionPermissionsSchema),
+    roleManagement: Schema.optional(RoleManagementSchema),
+  })
+).pipe(
+  Schema.annotations({
+    title: 'Admin Plugin Configuration',
+    description:
+      'Administrative features for user management. Default admin user configured via ADMIN_EMAIL, ADMIN_PASSWORD, ADMIN_NAME environment variables.',
+    examples: [
+      true,
+      { impersonation: true },
+      { impersonation: true, userManagement: true, firstUserAdmin: true },
+      {
+        customPermissions: { posts: ['create', 'read', 'update', 'delete'] },
+        roleManagement: { assignAdmin: true, revokeAdmin: true },
+      },
+    ],
+  })
+)
+
+export type AdminConfig = Schema.Schema.Type<typeof AdminConfigSchema>

package/src/domain/models/app/auth/plugins/index.ts

@@ -0,0 +1,74 @@
+/**
+ * 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'
+import { AdminConfigSchema } from './admin'
+import { TwoFactorConfigSchema } from './two-factor'
+
+// Export individual plugin schemas
+export * from './admin'
+export * from './two-factor'
+
+/**
+ * Unified Plugins Configuration Schema
+ *
+ * All authentication plugins in a single configuration object.
+ * Each plugin is optional and can be:
+ * - A boolean (true to enable with defaults)
+ * - A configuration object for customization
+ *
+ * Plugin categories:
+ * - Admin: admin
+ * - Security: twoFactor
+ *
+ * @example
+ * ```typescript
+ * // Simple plugins
+ * {
+ *   plugins: {
+ *     admin: true,
+ *     twoFactor: true
+ *   }
+ * }
+ *
+ * // Configured plugins
+ * {
+ *   plugins: {
+ *     admin: { impersonation: true },
+ *     twoFactor: { issuer: 'MyApp', backupCodes: true }
+ *   }
+ * }
+ * ```
+ */
+export const PluginsConfigSchema = Schema.Struct({
+  // Admin features
+  admin: Schema.optional(AdminConfigSchema),
+
+  // Security plugins
+  twoFactor: Schema.optional(TwoFactorConfigSchema),
+}).pipe(
+  Schema.annotations({
+    title: 'Plugins Configuration',
+    description: 'All authentication plugins configuration',
+    examples: [{ admin: true }, { twoFactor: { issuer: 'MyApp' } }],
+  })
+)
+
+export type PluginsConfig = Schema.Schema.Type<typeof PluginsConfigSchema>
+
+/**
+ * Helper to check if a plugin is enabled
+ */
+export const isPluginEnabled = (
+  plugins: PluginsConfig | undefined,
+  plugin: keyof PluginsConfig
+): boolean => {
+  if (!plugins) return false
+  const value = plugins[plugin]
+  if (typeof value === 'boolean') return value
+  return value !== undefined
+}