sovrium 0.0.2

package/src/infrastructure/auth/better-auth/email-handlers.ts

@@ -0,0 +1,162 @@
+/**
+ * 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 { sendEmail } from '../../email/email-service'
+import { passwordResetEmail, emailVerificationEmail } from '../../email/templates'
+import { logError } from '../../logging'
+import type { Auth, AuthEmailTemplate } from '@/domain/models/app/auth'
+
+/**
+ * Substitute variables in a template string
+ *
+ * Replaces $variable patterns with actual values from the context.
+ * Supported variables: $name, $url, $email, $organizationName, $inviterName
+ */
+const substituteVariables = (
+  template: string,
+  context: Readonly<{
+    name?: string
+    url: string
+    email: string
+    organizationName?: string
+    inviterName?: string
+  }>
+): string => {
+  return template
+    .replace(/\$name/g, context.name ?? 'there')
+    .replace(/\$url/g, context.url)
+    .replace(/\$email/g, context.email)
+    .replace(/\$organizationName/g, context.organizationName ?? 'the organization')
+    .replace(/\$inviterName/g, context.inviterName ?? 'Someone')
+}
+
+/**
+ * Email handler configuration for the factory
+ */
+type EmailHandlerConfig = Readonly<{
+  /** Email type for logging (e.g., 'password reset', 'verification') */
+  emailType: string
+  /** Function to build the action URL from base URL and token */
+  buildUrl: (url: string, token: string) => string
+  /** Function to generate the default template when no custom template is provided */
+  getDefaultTemplate: (params: Readonly<{ userName?: string; actionUrl: string }>) => Readonly<{
+    subject: string
+    html: string
+    text: string
+  }>
+}>
+
+/**
+ * Generic email handler factory - eliminates duplication between email types
+ *
+ * Creates a Better Auth email callback that:
+ * 1. Builds the action URL using the provided strategy
+ * 2. Sends custom template if provided (with variable substitution)
+ * 3. Falls back to default template otherwise
+ * 4. Handles errors silently to prevent user enumeration
+ */
+const createEmailHandler = (config: EmailHandlerConfig, customTemplate?: AuthEmailTemplate) => {
+  return async ({
+    user,
+    url,
+    token,
+  }: Readonly<{
+    user: Readonly<{ email: string; name?: string }>
+    url: string
+    token: string
+  }>) => {
+    const actionUrl = config.buildUrl(url, token)
+    const context = { name: user.name, url: actionUrl, email: user.email }
+
+    try {
+      // Custom template takes precedence - use it entirely (don't mix with defaults)
+      if (customTemplate?.subject) {
+        // eslint-disable-next-line functional/no-expression-statements -- Better Auth email callback requires side effect
+        await sendEmail({
+          to: user.email,
+          subject: substituteVariables(customTemplate.subject, context),
+          html: customTemplate.html ? substituteVariables(customTemplate.html, context) : undefined,
+          text: customTemplate.text ? substituteVariables(customTemplate.text, context) : undefined,
+        })
+      } else {
+        // Use default template
+        const defaultTemplate = config.getDefaultTemplate({
+          userName: user.name,
+          actionUrl,
+        })
+
+        // eslint-disable-next-line functional/no-expression-statements -- Better Auth email callback requires side effect
+        await sendEmail({
+          to: user.email,
+          subject: defaultTemplate.subject,
+          html: defaultTemplate.html,
+          text: defaultTemplate.text,
+        })
+      }
+    } catch (error) {
+      // Don't throw - silent failure prevents user enumeration attacks
+      logError(`[EMAIL] Failed to send ${config.emailType} email to ${user.email}`, error)
+    }
+  }
+}
+
+/**
+ * Create password reset email handler with optional custom templates
+ */
+const createPasswordResetEmailHandler = (customTemplate?: AuthEmailTemplate) =>
+  createEmailHandler(
+    {
+      emailType: 'password reset',
+      buildUrl: (url, token) => `${url}?token=${token}`,
+      getDefaultTemplate: ({ userName, actionUrl }) =>
+        passwordResetEmail({ userName, resetUrl: actionUrl, expiresIn: '1 hour' }),
+    },
+    customTemplate
+  )
+
+/**
+ * Create email verification handler with optional custom templates
+ */
+const createVerificationEmailHandler = (customTemplate?: AuthEmailTemplate) =>
+  createEmailHandler(
+    {
+      emailType: 'verification',
+      // Better Auth sometimes includes token in URL already
+      buildUrl: (url, token) => (url.includes('token=') ? url : `${url}?token=${token}`),
+      getDefaultTemplate: ({ userName, actionUrl }) =>
+        emailVerificationEmail({ userName, verifyUrl: actionUrl, expiresIn: '24 hours' }),
+    },
+    customTemplate
+  )
+
+/**
+ * Create magic link email handler with optional custom templates
+ */
+const createMagicLinkEmailHandler = (customTemplate?: AuthEmailTemplate) =>
+  createEmailHandler(
+    {
+      emailType: 'magic link',
+      buildUrl: (url, token) => `${url}?token=${token}`,
+      getDefaultTemplate: ({ userName, actionUrl }) => ({
+        subject: 'Sign in to your account',
+        html: `<p>Hi ${userName ?? 'there'},</p><p>Click here to sign in: <a href="${actionUrl}">Sign In</a></p><p>This link will expire in 10 minutes.</p>`,
+        text: `Hi ${userName ?? 'there'},\n\nClick here to sign in: ${actionUrl}\n\nThis link will expire in 10 minutes.`,
+      }),
+    },
+    customTemplate
+  )
+
+/**
+ * Create email handlers from auth configuration
+ */
+export const createEmailHandlers = (authConfig?: Auth) => {
+  return {
+    passwordReset: createPasswordResetEmailHandler(authConfig?.emailTemplates?.resetPassword),
+    verification: createVerificationEmailHandler(authConfig?.emailTemplates?.verification),
+    magicLink: createMagicLinkEmailHandler(authConfig?.emailTemplates?.magicLink),
+  }
+}

package/src/infrastructure/auth/better-auth/index.ts

@@ -0,0 +1,16 @@
+/**
+ * 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.
+ */
+
+/**
+ * Better Auth Module
+ *
+ * Provides authentication functionality using Better Auth library.
+ * Re-exports all auth-related services and types.
+ */
+export { auth } from './auth'
+export { Auth, AuthLive, createAuthLayer } from './layer'
+export { AuthError } from '../../errors/auth-error'

package/src/infrastructure/auth/better-auth/layer.ts

@@ -0,0 +1,97 @@
+/**
+ * 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 { Context, Effect, Layer } from 'effect'
+import { AuthError } from '../../errors/auth-error'
+import { createAuthInstance } from './auth'
+import type { auth } from './auth'
+import type { Auth as AuthConfig } from '@/domain/models/app/auth'
+
+// Re-export AuthError for convenience
+export { AuthError }
+
+/**
+ * Auth Effect Context
+ *
+ * Provides authentication service for dependency injection in Effect programs.
+ * Use this in Application layer to access authentication without direct imports.
+ *
+ * Implementation uses Better Auth library internally.
+ *
+ * @example
+ * ```typescript
+ * const protectedProgram = Effect.gen(function* () {
+ *   const authService = yield* Auth
+ *   const session = yield* authService.requireSession(headers)
+ *   return { userId: session.user.id, email: session.user.email }
+ * })
+ * ```
+ */
+export class Auth extends Context.Tag('Auth')<
+  Auth,
+  {
+    readonly api: ReturnType<typeof createAuthInstance>['api']
+    readonly handler: ReturnType<typeof createAuthInstance>['handler']
+    readonly getSession: (
+      headers: Headers
+    ) => Effect.Effect<Awaited<ReturnType<typeof auth.api.getSession>>, AuthError>
+    readonly requireSession: (
+      headers: Headers
+    ) => Effect.Effect<NonNullable<Awaited<ReturnType<typeof auth.api.getSession>>>, AuthError>
+  }
+>() {}
+
+/**
+ * Create an Auth Layer with a specific auth configuration
+ *
+ * This allows us to create an Auth layer with app-specific configuration
+ * (e.g., with admin plugin enabled) instead of using the default instance.
+ *
+ * @param authConfig - Optional auth configuration from app schema
+ * @returns Layer providing Auth service with the specified configuration
+ */
+export const createAuthLayer = (authConfig?: AuthConfig): Layer.Layer<Auth> => {
+  const authInstance = createAuthInstance(authConfig)
+
+  return Layer.succeed(
+    Auth,
+    Auth.of({
+      api: authInstance.api,
+      handler: authInstance.handler,
+
+      getSession: (headers) =>
+        Effect.tryPromise({
+          try: () => authInstance.api.getSession({ headers }),
+          catch: (error) => new AuthError(error),
+        }),
+
+      requireSession: (headers) =>
+        Effect.gen(function* () {
+          const session = yield* Effect.tryPromise({
+            try: () => authInstance.api.getSession({ headers }),
+            catch: (error) => new AuthError(error),
+          })
+
+          if (!session) {
+            return yield* Effect.fail(new AuthError('Unauthorized'))
+          }
+
+          return session
+        }),
+    })
+  )
+}
+
+/**
+ * Live Auth Layer
+ *
+ * Provides the production authentication service with Effect-wrapped methods.
+ * Implementation uses Better Auth library internally with default configuration.
+ *
+ * @deprecated Use createAuthLayer(authConfig) instead for app-specific configuration
+ */
+export const AuthLive = createAuthLayer()

package/src/infrastructure/auth/better-auth/plugins/admin.ts

@@ -0,0 +1,56 @@
+/**
+ * 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 { admin } from 'better-auth/plugins'
+import type { Auth } from '@/domain/models/app/auth'
+
+/**
+ * Admin plugin configuration extracted from auth config
+ */
+export interface AdminPluginConfig {
+  readonly defaultRole: string
+  readonly firstUserAdmin: boolean
+  readonly impersonation: boolean
+}
+
+/**
+ * Parse admin plugin configuration from auth config
+ *
+ * Admin features are always enabled when auth is configured.
+ * Uses `defaultRole` from auth config (defaults to 'member').
+ */
+export const parseAdminConfig = (authConfig?: Auth): AdminPluginConfig | undefined => {
+  if (!authConfig) return undefined
+
+  return {
+    defaultRole: authConfig.defaultRole ?? 'member',
+    firstUserAdmin: true,
+    impersonation: false,
+  }
+}
+
+/**
+ * Build admin plugin if auth is configured
+ *
+ * The admin plugin provides:
+ * - User management (list, ban, unban, impersonate)
+ * - Role-based access control (admin, member, viewer roles)
+ *
+ * Admin features are always enabled when auth is configured — no separate toggle.
+ */
+export const buildAdminPlugin = (authConfig?: Auth) => {
+  const config = parseAdminConfig(authConfig)
+  if (!config) return []
+
+  return [
+    admin({
+      defaultRole: config.defaultRole,
+      adminRoles: ['admin'],
+      impersonationSessionDuration: config.impersonation ? 60 * 60 : undefined,
+    }),
+  ]
+}

package/src/infrastructure/auth/better-auth/plugins/magic-link.ts

@@ -0,0 +1,31 @@
+/**
+ * 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 { magicLink } from 'better-auth/plugins'
+import { hasStrategy } from '@/domain/models/app/auth'
+import type { Auth } from '@/domain/models/app/auth'
+
+/**
+ * Build magic link plugin if enabled in auth configuration
+ */
+export const buildMagicLinkPlugin = (
+  sendMagicLink: (data: {
+    readonly user: { readonly email: string }
+    readonly url: string
+    readonly token: string
+  }) => Promise<void>,
+  authConfig?: Auth
+) => {
+  return hasStrategy(authConfig, 'magicLink')
+    ? [
+        magicLink({
+          sendMagicLink: async ({ email, token, url }) =>
+            sendMagicLink({ user: { email }, url, token }),
+        }),
+      ]
+    : []
+}

package/src/infrastructure/auth/better-auth/plugins/two-factor.ts

@@ -0,0 +1,19 @@
+/**
+ * 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 { twoFactor } from 'better-auth/plugins'
+import type { Auth } from '@/domain/models/app/auth'
+
+/**
+ * Build two-factor plugin if enabled in auth configuration
+ *
+ * NOTE: modelName option removed - drizzleSchema in auth.ts uses standard model names
+ * and Drizzle pgTable() definitions specify actual database table names
+ */
+export const buildTwoFactorPlugin = (authConfig?: Auth) => {
+  return authConfig?.twoFactor ? [twoFactor()] : []
+}

package/src/infrastructure/auth/better-auth/schema.ts

@@ -0,0 +1,152 @@
+/**
+ * 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 { relations } from 'drizzle-orm'
+import { text, boolean, timestamp, pgSchema, index } from 'drizzle-orm/pg-core'
+
+// Better Auth schema - isolated from main app schema
+// All auth tables are created in the "auth" PostgreSQL schema
+export const authSchema = pgSchema('auth')
+
+// Better Auth Tables (using native table names in dedicated auth schema)
+// Schema isolation prevents conflicts when users create their own tables
+export const users = authSchema.table('user', {
+  id: text('id').primaryKey(),
+  name: text('name').notNull(),
+  email: text('email').notNull().unique(),
+  emailVerified: boolean('email_verified').notNull().default(false),
+  image: text('image'),
+  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+  updatedAt: timestamp('updated_at', { withTimezone: true })
+    .notNull()
+    .defaultNow()
+    .$onUpdate(() => new Date()),
+  // Admin plugin fields
+  role: text('role'),
+  banned: boolean('banned').default(false),
+  banReason: text('ban_reason'),
+  banExpires: timestamp('ban_expires', { withTimezone: true }),
+  // Two-factor plugin fields
+  twoFactorEnabled: boolean('two_factor_enabled').default(false),
+})
+
+export const sessions = authSchema.table(
+  'session',
+  {
+    id: text('id').primaryKey(),
+    expiresAt: timestamp('expires_at', { withTimezone: true }).notNull(),
+    token: text('token').notNull().unique(),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true })
+      .notNull()
+      .defaultNow()
+      .$onUpdate(() => new Date()),
+    ipAddress: text('ip_address'),
+    userAgent: text('user_agent'),
+    userId: text('user_id')
+      .notNull()
+      .references(() => users.id, { onDelete: 'cascade' }),
+    // Admin plugin fields
+    impersonatedBy: text('impersonated_by'),
+  },
+  (table) => [index('session_userId_idx').on(table.userId)]
+)
+
+export const accounts = authSchema.table(
+  'account',
+  {
+    id: text('id').primaryKey(),
+    accountId: text('account_id').notNull(),
+    providerId: text('provider_id').notNull(),
+    userId: text('user_id')
+      .notNull()
+      .references(() => users.id, { onDelete: 'cascade' }),
+    accessToken: text('access_token'),
+    refreshToken: text('refresh_token'),
+    idToken: text('id_token'),
+    accessTokenExpiresAt: timestamp('access_token_expires_at', { withTimezone: true }),
+    refreshTokenExpiresAt: timestamp('refresh_token_expires_at', { withTimezone: true }),
+    scope: text('scope'),
+    password: text('password'),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true })
+      .notNull()
+      .defaultNow()
+      .$onUpdate(() => new Date()),
+  },
+  (table) => [index('account_userId_idx').on(table.userId)]
+)
+
+export const verifications = authSchema.table(
+  'verification',
+  {
+    id: text('id').primaryKey(),
+    identifier: text('identifier').notNull(),
+    value: text('value').notNull(),
+    expiresAt: timestamp('expires_at', { withTimezone: true }).notNull(),
+    createdAt: timestamp('created_at', { withTimezone: true }).defaultNow().notNull(),
+    updatedAt: timestamp('updated_at', { withTimezone: true })
+      .defaultNow()
+      .notNull()
+      .$onUpdate(() => new Date()),
+  },
+  (table) => [index('verification_identifier_idx').on(table.identifier)]
+)
+
+// Two-factor plugin table
+export const twoFactors = authSchema.table(
+  'two_factor',
+  {
+    id: text('id').primaryKey(),
+    userId: text('user_id')
+      .notNull()
+      .references(() => users.id, { onDelete: 'cascade' }),
+    secret: text('secret').notNull(),
+    backupCodes: text('backup_codes').notNull(),
+  },
+  (table) => [
+    index('twoFactor_secret_idx').on(table.secret),
+    index('twoFactor_userId_idx').on(table.userId),
+  ]
+)
+
+// Drizzle Relations (for type-safe joins)
+export const usersRelations = relations(users, ({ many }) => ({
+  sessions: many(sessions),
+  accounts: many(accounts),
+  twoFactors: many(twoFactors),
+}))
+
+export const sessionsRelations = relations(sessions, ({ one }) => ({
+  user: one(users, {
+    fields: [sessions.userId],
+    references: [users.id],
+  }),
+}))
+
+export const accountsRelations = relations(accounts, ({ one }) => ({
+  user: one(users, {
+    fields: [accounts.userId],
+    references: [users.id],
+  }),
+}))
+
+export const twoFactorsRelations = relations(twoFactors, ({ one }) => ({
+  user: one(users, {
+    fields: [twoFactors.userId],
+    references: [users.id],
+  }),
+}))
+
+// Type inference
+export type User = typeof users.$inferSelect
+export type NewUser = typeof users.$inferInsert
+export type Session = typeof sessions.$inferSelect
+export type Account = typeof accounts.$inferSelect
+export type Verification = typeof verifications.$inferSelect
+export type TwoFactor = typeof twoFactors.$inferSelect
+export type NewTwoFactor = typeof twoFactors.$inferInsert

package/src/infrastructure/auth/index.ts

@@ -0,0 +1,27 @@
+/**
+ * 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.
+ */
+
+/**
+ * Authentication Infrastructure Module
+ *
+ * Provides authentication services and utilities.
+ * Currently uses Better Auth for authentication.
+ *
+ * @example
+ * ```typescript
+ * import { Auth, AuthLive } from '@/infrastructure/auth'
+ *
+ * const program = Effect.gen(function* () {
+ *   const auth = yield* Auth
+ *   const session = yield* auth.requireSession(headers)
+ *   return session.user
+ * }).pipe(Effect.provide(AuthLive))
+ * ```
+ */
+
+export { auth } from './better-auth/auth'
+export { Auth, AuthLive, AuthError } from './better-auth/layer'

package/src/infrastructure/css/cache/css-cache-service.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 { Effect, Ref, pipe } from 'effect'
+import type { Theme } from '@/domain/models/app/theme'
+
+/**
+ * Compiled CSS result with metadata
+ */
+export interface CompiledCSS {
+  readonly css: string
+  readonly timestamp: number
+}
+
+/**
+ * In-memory cache for compiled CSS using Effect.Ref
+ * Stores multiple themes keyed by normalized theme hash
+ * Avoids recompiling on every request for better performance
+ * Uses functional state management to avoid mutations
+ */
+const cssCache = Ref.unsafeMake<Map<string, CompiledCSS>>(new Map())
+
+/**
+ * Recursively sort object keys for consistent JSON serialization
+ * This ensures the same theme always produces the same cache key
+ * regardless of property insertion order
+ */
+const sortObjectKeys = (obj: unknown): unknown => {
+  if (obj === null || typeof obj !== 'object') {
+    return obj
+  }
+
+  if (Array.isArray(obj)) {
+    return obj.map(sortObjectKeys)
+  }
+
+  const record = obj as Record<string, unknown>
+  const sortedKeys = Object.keys(record).toSorted()
+
+  return sortedKeys.reduce<Record<string, unknown>>(
+    (acc, key) => ({ ...acc, [key]: sortObjectKeys(record[key]) }),
+    {}
+  )
+}
+
+/**
+ * Normalize theme for consistent cache key generation
+ * Sorts object keys recursively to ensure property order independence
+ *
+ * @param theme - Optional theme configuration
+ * @returns Normalized theme (or undefined if no theme)
+ */
+export const normalizeTheme = (theme?: Theme): Theme | undefined => {
+  if (!theme) return undefined
+  return sortObjectKeys(theme) as Theme
+}
+
+/**
+ * Create theme cache key from app theme
+ * Returns consistent hash for same theme content regardless of property order
+ *
+ * @param theme - Optional theme configuration
+ * @returns Cache key string (JSON stringified normalized theme)
+ *
+ * @example
+ * // These produce the same cache key:
+ * getThemeCacheKey({ colors: { primary: '#ff5733' }, fonts: { sans: 'Inter' } })
+ * getThemeCacheKey({ fonts: { sans: 'Inter' }, colors: { primary: '#ff5733' } })
+ */
+export const getThemeCacheKey = (theme?: Theme): string => {
+  const normalized = normalizeTheme(theme)
+  return JSON.stringify(normalized ?? {})
+}
+
+/**
+ * Get cached CSS if available
+ *
+ * @param cacheKey - Cache key for the theme
+ * @returns Effect that yields cached CSS or undefined
+ */
+export const getCachedCSS = (cacheKey: string): Effect.Effect<CompiledCSS | undefined, never> =>
+  pipe(
+    Ref.get(cssCache),
+    Effect.map((cache) => cache.get(cacheKey))
+  )
+
+/**
+ * Store compiled CSS in cache
+ *
+ * @param cacheKey - Cache key for the theme
+ * @param compiled - Compiled CSS result
+ * @returns Effect that updates the cache
+ */
+export const setCachedCSS = (cacheKey: string, compiled: CompiledCSS): Effect.Effect<void, never> =>
+  Ref.update(cssCache, (currentCache) => new Map([...currentCache, [cacheKey, compiled]]))
+
+/**
+ * Clear all cached CSS (useful for testing or hot reload)
+ *
+ * @returns Effect that clears the cache
+ */
+export const clearCSSCache = (): Effect.Effect<void, never> => Ref.set(cssCache, new Map())
+
+/**
+ * Get or compute cached CSS
+ * This is a convenience function that combines getCachedCSS and setCachedCSS
+ * with a computation function for cleaner usage
+ *
+ * @param cacheKey - Cache key for the theme
+ * @param compute - Effect that computes the CSS if not cached
+ * @returns Effect that yields cached or newly computed CSS
+ */
+export const getOrComputeCachedCSS = <E>(
+  cacheKey: string,
+  compute: Effect.Effect<CompiledCSS, E>
+): Effect.Effect<CompiledCSS, E> =>
+  Effect.gen(function* () {
+    const cached = yield* getCachedCSS(cacheKey)
+    if (cached !== undefined) {
+      return cached
+    }
+
+    const compiled = yield* compute
+    yield* setCachedCSS(cacheKey, compiled)
+    return compiled
+  })