sovrium 0.0.2

package/src/domain/models/app/auth/plugins/two-factor.ts

@@ -0,0 +1,63 @@
+/**
+ * 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'
+
+/**
+ * Two-Factor Authentication Plugin Configuration
+ *
+ * Enables TOTP-based two-factor authentication.
+ * Users can set up 2FA using authenticator apps.
+ *
+ * Configuration options:
+ * - issuer: Name shown in authenticator apps (e.g., "MyApp")
+ * - backupCodes: Generate backup codes for account recovery
+ * - digits: Number of digits in TOTP code (default: 6)
+ * - period: Time period for code rotation in seconds (default: 30)
+ *
+ * @example
+ * ```typescript
+ * // Simple enable
+ * { plugins: { twoFactor: true } }
+ *
+ * // With configuration
+ * { plugins: { twoFactor: { issuer: 'MyApp', backupCodes: true } } }
+ * ```
+ */
+export const TwoFactorConfigSchema = Schema.Union(
+  Schema.Boolean,
+  Schema.Struct({
+    issuer: Schema.optional(
+      Schema.String.pipe(
+        Schema.annotations({ description: 'Issuer name shown in authenticator apps' })
+      )
+    ),
+    backupCodes: Schema.optional(
+      Schema.Boolean.pipe(Schema.annotations({ description: 'Generate backup codes for recovery' }))
+    ),
+    digits: Schema.optional(
+      Schema.Number.pipe(
+        Schema.between(4, 8),
+        Schema.annotations({ description: 'Number of digits in TOTP code (4-8)' })
+      )
+    ),
+    period: Schema.optional(
+      Schema.Number.pipe(
+        Schema.positive(),
+        Schema.annotations({ description: 'Code rotation period in seconds' })
+      )
+    ),
+  })
+).pipe(
+  Schema.annotations({
+    title: 'Two-Factor Authentication Configuration',
+    description: 'TOTP-based two-factor authentication',
+    examples: [true, { issuer: 'MyApp', backupCodes: true }],
+  })
+)
+
+export type TwoFactorConfig = Schema.Schema.Type<typeof TwoFactorConfigSchema>

package/src/domain/models/app/auth/roles.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 { Schema } from 'effect'
+
+/**
+ * Built-in Role Names
+ *
+ * These roles are always available without configuration.
+ * They cannot be redefined by custom role definitions.
+ *
+ * Hierarchy (highest to lowest):
+ * - admin (80): Can manage members and settings
+ * - member (40): Standard access to organization resources
+ * - viewer (10): Read-only access
+ */
+export const BUILT_IN_ROLES = ['admin', 'member', 'viewer'] as const
+
+export const BUILT_IN_ROLE_LEVELS: Readonly<Record<string, number>> = {
+  admin: 80,
+  member: 40,
+  viewer: 10,
+}
+
+/**
+ * Built-in Role Schema
+ *
+ * The three built-in roles with predefined hierarchy levels.
+ */
+export const BuiltInRoleSchema = Schema.Literal('admin', 'member', 'viewer').pipe(
+  Schema.annotations({
+    title: 'Built-in Role',
+    description: 'Built-in role with predefined hierarchy. Levels: admin=80, member=40, viewer=10',
+    examples: ['admin', 'member', 'viewer'],
+  })
+)
+
+export type BuiltInRole = Schema.Schema.Type<typeof BuiltInRoleSchema>
+
+/**
+ * Role Name Schema
+ *
+ * Validates role naming convention: lowercase, alphanumeric, hyphens allowed.
+ * Must start with a letter.
+ *
+ * @example
+ * ```typescript
+ * 'editor'          // valid
+ * 'content-manager' // valid
+ * 'Editor'          // invalid (uppercase)
+ * '123role'         // invalid (starts with number)
+ * ```
+ */
+export const RoleNameSchema = Schema.String.pipe(
+  Schema.pattern(/^[a-z][a-z0-9-]*$/),
+  Schema.annotations({
+    title: 'Role Name',
+    description: 'Role name: lowercase, alphanumeric, hyphens. Must start with a letter.',
+    examples: ['editor', 'content-manager', 'moderator'],
+  })
+)
+
+export type RoleName = Schema.Schema.Type<typeof RoleNameSchema>
+
+/**
+ * Custom Role Definition Schema
+ *
+ * Defines a custom role with an optional description and hierarchy level.
+ *
+ * @example
+ * ```typescript
+ * { name: 'editor', description: 'Can edit content', level: 30 }
+ * { name: 'moderator' }
+ * ```
+ */
+export const RoleDefinitionSchema = Schema.Struct({
+  name: RoleNameSchema,
+  description: Schema.optional(
+    Schema.String.pipe(
+      Schema.annotations({ description: 'Human-readable description of the role' })
+    )
+  ),
+  level: Schema.optional(
+    Schema.Number.pipe(
+      Schema.annotations({
+        description:
+          'Hierarchy level (higher = more permissions). Built-in: admin=80, member=40, viewer=10',
+      })
+    )
+  ),
+}).pipe(
+  Schema.annotations({
+    title: 'Role Definition',
+    description:
+      'Custom role definition with name, optional description, and optional hierarchy level.',
+    examples: [
+      { name: 'editor', description: 'Can edit content', level: 30 },
+      { name: 'moderator', level: 20 },
+      { name: 'contributor' },
+    ],
+  })
+)
+
+export type RoleDefinition = Schema.Schema.Type<typeof RoleDefinitionSchema>
+
+/**
+ * Roles Config Schema
+ *
+ * Array of custom role definitions. Empty array is valid (only built-in roles).
+ *
+ * Validates:
+ * - Role names are unique
+ * - Custom role names don't conflict with built-in role names
+ *
+ * @example
+ * ```typescript
+ * []  // valid: only built-in roles
+ * [{ name: 'editor', level: 30 }, { name: 'moderator', level: 20 }]
+ * ```
+ */
+export const RolesConfigSchema = Schema.Array(RoleDefinitionSchema).pipe(
+  Schema.filter((roles) => {
+    // Check for duplicate names
+    const names = roles.map((r) => r.name)
+    const uniqueNames = new Set(names)
+    if (uniqueNames.size !== names.length) {
+      const duplicates = names.filter((name, i) => names.indexOf(name) !== i)
+      return `Duplicate role names: ${duplicates.join(', ')}`
+    }
+
+    // Check for conflicts with built-in roles
+    const conflicts = names.filter((name) => (BUILT_IN_ROLES as readonly string[]).includes(name))
+    if (conflicts.length > 0) {
+      return `Custom role names cannot conflict with built-in roles: ${conflicts.join(', ')}`
+    }
+
+    return undefined
+  }),
+  Schema.annotations({
+    title: 'Roles Configuration',
+    description: 'Array of custom role definitions. Built-in roles are always available.',
+    examples: [
+      [],
+      [
+        { name: 'editor', description: 'Can edit content', level: 30 },
+        { name: 'moderator', level: 20 },
+      ],
+    ],
+  })
+)
+
+export type RolesConfig = Schema.Schema.Type<typeof RolesConfigSchema>
+
+/**
+ * Default Role Schema
+ *
+ * Accepts built-in roles and custom role names.
+ * Defaults to 'member' when not specified.
+ *
+ * @example
+ * ```typescript
+ * 'viewer'   // built-in role
+ * 'editor'   // custom role (must be defined in auth.roles)
+ * ```
+ */
+export const DefaultRoleSchema = Schema.String.pipe(
+  Schema.annotations({
+    title: 'Default Role',
+    description:
+      'Role assigned to new users by default. Accepts built-in roles or custom role names. Defaults to member.',
+    examples: ['member', 'viewer', 'editor'],
+  })
+)
+
+export type DefaultRole = Schema.Schema.Type<typeof DefaultRoleSchema>

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

@@ -0,0 +1,191 @@
+/**
+ * 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 { OAuthProviderSchema } from './oauth/providers'
+
+/**
+ * Email and Password Strategy Schema
+ *
+ * Traditional credential-based authentication.
+ *
+ * @example
+ * ```typescript
+ * { type: 'emailAndPassword' }
+ * { type: 'emailAndPassword', minPasswordLength: 12, requireEmailVerification: true }
+ * ```
+ */
+export const EmailAndPasswordStrategySchema = Schema.Struct({
+  type: Schema.Literal('emailAndPassword'),
+  minPasswordLength: Schema.optional(
+    Schema.Number.pipe(
+      Schema.between(6, 128),
+      Schema.annotations({ description: 'Minimum password length (6-128, default: 8)' })
+    )
+  ),
+  maxPasswordLength: Schema.optional(
+    Schema.Number.pipe(
+      Schema.between(8, 256),
+      Schema.annotations({ description: 'Maximum password length (8-256, default: 128)' })
+    )
+  ),
+  requireEmailVerification: Schema.optional(
+    Schema.Boolean.pipe(
+      Schema.annotations({
+        description: 'Require email verification before sign-in (default: false)',
+      })
+    )
+  ),
+  autoSignIn: Schema.optional(
+    Schema.Boolean.pipe(
+      Schema.annotations({ description: 'Auto sign in after signup (default: true)' })
+    )
+  ),
+}).pipe(
+  Schema.annotations({
+    title: 'Email and Password Strategy',
+    description: 'Traditional credential-based authentication strategy',
+    examples: [
+      { type: 'emailAndPassword' as const },
+      { type: 'emailAndPassword' as const, minPasswordLength: 12 },
+    ],
+  })
+)
+
+export type EmailAndPasswordStrategy = Schema.Schema.Type<typeof EmailAndPasswordStrategySchema>
+
+/**
+ * Magic Link Strategy Schema
+ *
+ * Passwordless authentication via email link.
+ *
+ * @example
+ * ```typescript
+ * { type: 'magicLink' }
+ * { type: 'magicLink', expirationMinutes: 30 }
+ * ```
+ */
+export const MagicLinkStrategySchema = Schema.Struct({
+  type: Schema.Literal('magicLink'),
+  expirationMinutes: Schema.optional(
+    Schema.Number.pipe(
+      Schema.positive(),
+      Schema.annotations({ description: 'Link expiration time in minutes (default: 15)' })
+    )
+  ),
+}).pipe(
+  Schema.annotations({
+    title: 'Magic Link Strategy',
+    description: 'Passwordless authentication via email link',
+    examples: [
+      { type: 'magicLink' as const },
+      { type: 'magicLink' as const, expirationMinutes: 30 },
+    ],
+  })
+)
+
+export type MagicLinkStrategy = Schema.Schema.Type<typeof MagicLinkStrategySchema>
+
+/**
+ * OAuth Strategy Schema
+ *
+ * Social login with OAuth providers.
+ * Credentials are loaded from environment variables.
+ *
+ * @example
+ * ```typescript
+ * { type: 'oauth', providers: ['google', 'github'] }
+ * ```
+ */
+export const OAuthStrategySchema = Schema.Struct({
+  type: Schema.Literal('oauth'),
+  providers: Schema.NonEmptyArray(OAuthProviderSchema).pipe(
+    Schema.annotations({
+      description: 'OAuth providers to enable. Credentials loaded from environment variables.',
+    })
+  ),
+}).pipe(
+  Schema.annotations({
+    title: 'OAuth Strategy',
+    description: 'Social login with OAuth providers (google, github, microsoft, slack, gitlab)',
+    examples: [{ type: 'oauth' as const, providers: ['google', 'github'] }],
+  })
+)
+
+export type OAuthStrategy = Schema.Schema.Type<typeof OAuthStrategySchema>
+
+/**
+ * Auth Strategy Schema
+ *
+ * Discriminated union of all supported authentication strategy types.
+ * The `type` field determines which strategy configuration applies.
+ *
+ * @example
+ * ```typescript
+ * { type: 'emailAndPassword', minPasswordLength: 12 }
+ * { type: 'magicLink' }
+ * { type: 'oauth', providers: ['google', 'github'] }
+ * ```
+ */
+export const AuthStrategySchema = Schema.Union(
+  EmailAndPasswordStrategySchema,
+  MagicLinkStrategySchema,
+  OAuthStrategySchema
+).pipe(
+  Schema.annotations({
+    title: 'Auth Strategy',
+    description:
+      'Authentication strategy configuration. Discriminated by `type` field: emailAndPassword, magicLink, or oauth.',
+    examples: [
+      { type: 'emailAndPassword' as const },
+      { type: 'magicLink' as const },
+      { type: 'oauth' as const, providers: ['google', 'github'] },
+    ],
+  })
+)
+
+export type AuthStrategy = Schema.Schema.Type<typeof AuthStrategySchema>
+
+/**
+ * Auth Strategies Array Schema
+ *
+ * Non-empty array of authentication strategies.
+ * At least one strategy must be defined.
+ *
+ * Validates:
+ * - At least one strategy is present
+ * - No duplicate strategy types
+ *
+ * @example
+ * ```typescript
+ * [{ type: 'emailAndPassword' }]
+ * [{ type: 'emailAndPassword', minPasswordLength: 12 }, { type: 'oauth', providers: ['google'] }]
+ * ```
+ */
+export const AuthStrategiesSchema = Schema.NonEmptyArray(AuthStrategySchema).pipe(
+  Schema.filter((strategies) => {
+    const types = strategies.map((s) => s.type)
+    const uniqueTypes = new Set(types)
+    if (uniqueTypes.size !== types.length) {
+      return 'Duplicate strategy types are not allowed. Each strategy type can only appear once.'
+    }
+    return undefined
+  }),
+  Schema.annotations({
+    title: 'Auth Strategies',
+    description: 'Array of authentication strategies. At least one required, no duplicates.',
+    examples: [
+      [{ type: 'emailAndPassword' as const }],
+      [
+        { type: 'emailAndPassword' as const, minPasswordLength: 12 },
+        { type: 'oauth' as const, providers: ['google'] },
+      ],
+    ],
+  })
+)
+
+export type AuthStrategies = Schema.Schema.Type<typeof AuthStrategiesSchema>

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

@@ -0,0 +1,127 @@
+/**
+ * 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 { EmailAndPasswordConfig } from './methods/email-and-password'
+import type { MagicLinkConfig } from './methods/magic-link'
+import type { OAuthConfig } from './oauth'
+import type { AdminConfig } from './plugins/admin'
+import type { TwoFactorConfig } from './plugins/two-factor'
+
+/**
+ * Auth Configuration for Validation
+ *
+ * Interface representing the flattened auth configuration structure
+ * used for cross-field validation.
+ */
+export interface AuthConfigForValidation {
+  readonly emailAndPassword?: EmailAndPasswordConfig
+  readonly magicLink?: MagicLinkConfig
+  readonly oauth?: OAuthConfig
+  readonly admin?: AdminConfig
+  readonly twoFactor?: TwoFactorConfig
+}
+
+/**
+ * Validation Result
+ */
+export interface ValidationResult {
+  readonly success: boolean
+  readonly message?: string
+}
+
+/**
+ * Check if a specific authentication method is enabled
+ */
+export const isMethodEnabled = (
+  config: AuthConfigForValidation | undefined,
+  method: 'emailAndPassword' | 'magicLink' | 'oauth'
+): boolean => {
+  if (!config) return false
+  const value = config[method]
+  if (typeof value === 'boolean') return value
+  return value !== undefined
+}
+
+/**
+ * Validation Rules for Auth Configuration
+ *
+ * These rules ensure incompatible features aren't combined
+ * and that required dependencies are met.
+ */
+
+/**
+ * Rule 1: Two-factor authentication requires a primary auth method
+ *
+ * 2FA is a second factor and requires a primary authentication method
+ * like emailAndPassword.
+ */
+export const validateTwoFactorRequiresPrimary = (
+  config: AuthConfigForValidation
+): ValidationResult => {
+  const hasTwoFactor = config.twoFactor
+
+  if (!hasTwoFactor) {
+    return { success: true }
+  }
+
+  const hasEmailAndPassword = isMethodEnabled(config, 'emailAndPassword')
+
+  if (!hasEmailAndPassword) {
+    return {
+      success: false,
+      message: 'Two-factor authentication requires emailAndPassword authentication',
+    }
+  }
+
+  return { success: true }
+}
+
+/**
+ * Rule 2: OAuth requires at least one provider
+ *
+ * If OAuth is configured, it must have at least one provider.
+ * This is already enforced by Schema.NonEmptyArray but we
+ * include it for explicit documentation.
+ */
+export const validateOAuthHasProviders = (config: AuthConfigForValidation): ValidationResult => {
+  if (!config.oauth) {
+    return { success: true }
+  }
+
+  const { providers } = config.oauth
+  if (!providers || providers.length === 0) {
+    return {
+      success: false,
+      message: 'OAuth configuration requires at least one provider',
+    }
+  }
+
+  return { success: true }
+}
+
+/**
+ * Run all validation rules
+ *
+ * Returns the first validation failure or success.
+ */
+export const validateAuthConfig = (config: AuthConfigForValidation): ValidationResult => {
+  const rules = [validateTwoFactorRequiresPrimary, validateOAuthHasProviders]
+
+  return rules.reduce<ValidationResult>((acc, rule) => (acc.success ? rule(config) : acc), {
+    success: true,
+  })
+}
+
+/**
+ * Check if a specific authentication method is enabled (alias)
+ */
+export const hasAuthMethod = (
+  config: AuthConfigForValidation,
+  methodName: 'emailAndPassword' | 'magicLink' | 'oauth'
+): boolean => {
+  return isMethodEnabled(config, methodName)
+}