refactor: isolate auth module using inversion of control

Create a standalone auth module at ~/auth that encapsulates all
authentication logic, making it independent of the rest of the
application through IoC interfaces.

New auth module structure:
- types.ts: Core types and IoC interfaces (IUserRepository, etc.)
- session.server.ts: Cookie-based session management with HMAC-SHA256
- auth.server.ts: Main AuthService for user authentication
- capabilities.server.ts: CapabilitiesService with helper utilities
- oauth.server.ts: OAuthService and OAuth provider utilities
- guards.server.ts: Auth guards factory and decorators
- repositories.server.ts: Drizzle-based repository implementations
- context.server.ts: Dependency injection/service composition root
- index.server.ts: Server-side public API exports
- index.ts: Client-side public API exports
- client.ts: Client-side auth utilities

The existing utils files now delegate to the new auth module for
backward compatibility. Auth routes updated to use the new module
directly.

Author: claude

src/auth/auth.server.ts

@@ -0,0 +1,163 @@
+/**
+ * Auth Service
+ *
+ * Main authentication service that coordinates session validation
+ * and user retrieval. Uses inversion of control for all dependencies.
+ */
+
+import type {
+  AuthUser,
+  Capability,
+  DbUser,
+  IAuthService,
+  ICapabilitiesRepository,
+  ISessionService,
+  IUserRepository,
+  SessionCookieData,
+} from './types'
+import { AuthError } from './types'
+
+// ============================================================================
+// Auth Service Implementation
+// ============================================================================
+
+export class AuthService implements IAuthService {
+  constructor(
+    private sessionService: ISessionService,
+    private userRepository: IUserRepository,
+    private capabilitiesRepository: ICapabilitiesRepository,
+  ) {}
+
+  /**
+   * Get current user from request
+   * Returns null if not authenticated
+   */
+  async getCurrentUser(request: Request): Promise<AuthUser | null> {
+    const signedCookie = this.sessionService.getSessionCookie(request)
+
+    if (!signedCookie) {
+      return null
+    }
+
+    try {
+      const cookieData = await this.sessionService.verifyCookie(signedCookie)
+
+      if (!cookieData) {
+        console.error(
+          '[AuthService] Session cookie verification failed - invalid signature or expired',
+        )
+        return null
+      }
+
+      const result = await this.validateSession(cookieData)
+      if (!result) {
+        return null
+      }
+
+      return this.mapDbUserToAuthUser(result.user, result.capabilities)
+    } catch (error) {
+      console.error('[AuthService] Failed to get user from session:', {
+        error: error instanceof Error ? error.message : 'Unknown error',
+        stack: error instanceof Error ? error.stack : undefined,
+      })
+      return null
+    }
+  }
+
+  /**
+   * Validate session data against the database
+   */
+  async validateSession(
+    sessionData: SessionCookieData,
+  ): Promise<{ user: DbUser; capabilities: Capability[] } | null> {
+    const user = await this.userRepository.findById(sessionData.userId)
+
+    if (!user) {
+      console.error(
+        `[AuthService] Session cookie references non-existent user ${sessionData.userId}`,
+      )
+      return null
+    }
+
+    // Verify session version matches (for session revocation)
+    if (user.sessionVersion !== sessionData.version) {
+      console.error(
+        `[AuthService] Session version mismatch for user ${user.id} - expected ${user.sessionVersion}, got ${sessionData.version}`,
+      )
+      return null
+    }
+
+    // Get effective capabilities
+    const capabilities =
+      await this.capabilitiesRepository.getEffectiveCapabilities(user.id)
+
+    return { user, capabilities }
+  }
+
+  /**
+   * Map database user to AuthUser type
+   */
+  private mapDbUserToAuthUser(user: DbUser, capabilities: Capability[]): AuthUser {
+    return {
+      userId: user.id,
+      email: user.email,
+      name: user.name,
+      image: user.image,
+      displayUsername: user.displayUsername,
+      capabilities,
+      adsDisabled: user.adsDisabled,
+      interestedInHidingAds: user.interestedInHidingAds,
+    }
+  }
+}
+
+// ============================================================================
+// Auth Guard Functions
+// ============================================================================
+
+/**
+ * Require authentication - throws if not authenticated
+ */
+export async function requireAuthentication(
+  authService: IAuthService,
+  request: Request,
+): Promise<AuthUser> {
+  const user = await authService.getCurrentUser(request)
+  if (!user) {
+    throw new AuthError('Not authenticated', 'NOT_AUTHENTICATED')
+  }
+  return user
+}
+
+/**
+ * Require specific capability - throws if not authorized
+ */
+export async function requireCapability(
+  authService: IAuthService,
+  request: Request,
+  capability: Capability,
+): Promise<AuthUser> {
+  const user = await requireAuthentication(authService, request)
+
+  const hasAccess =
+    user.capabilities.includes('admin') || user.capabilities.includes(capability)
+
+  if (!hasAccess) {
+    throw new AuthError(
+      `Missing required capability: ${capability}`,
+      'MISSING_CAPABILITY',
+    )
+  }
+
+  return user
+}
+
+/**
+ * Require admin capability - throws if not admin
+ */
+export async function requireAdmin(
+  authService: IAuthService,
+  request: Request,
+): Promise<AuthUser> {
+  return requireCapability(authService, request, 'admin')
+}

src/auth/capabilities.server.ts

@@ -0,0 +1,101 @@
+/**
+ * Capabilities Service
+ *
+ * Handles authorization via capability-based access control.
+ * Uses inversion of control for data access.
+ */
+
+import type { Capability, ICapabilitiesRepository, AuthUser } from './types'
+
+// ============================================================================
+// Capabilities Service
+// ============================================================================
+
+export class CapabilitiesService {
+  constructor(private repository: ICapabilitiesRepository) {}
+
+  /**
+   * Get effective capabilities for a user (direct + role-based)
+   */
+  async getEffectiveCapabilities(userId: string): Promise<Capability[]> {
+    return this.repository.getEffectiveCapabilities(userId)
+  }
+
+  /**
+   * Get effective capabilities for multiple users efficiently
+   */
+  async getBulkEffectiveCapabilities(
+    userIds: string[],
+  ): Promise<Record<string, Capability[]>> {
+    return this.repository.getBulkEffectiveCapabilities(userIds)
+  }
+}
+
+// ============================================================================
+// Capability Checking Utilities
+// ============================================================================
+
+/**
+ * Check if user has a specific capability
+ * Admin users have access to all capabilities
+ */
+export function hasCapability(
+  capabilities: Capability[],
+  requiredCapability: Capability,
+): boolean {
+  return (
+    capabilities.includes('admin') || capabilities.includes(requiredCapability)
+  )
+}
+
+/**
+ * Check if user has all specified capabilities
+ */
+export function hasAllCapabilities(
+  capabilities: Capability[],
+  requiredCapabilities: Capability[],
+): boolean {
+  if (capabilities.includes('admin')) {
+    return true
+  }
+  return requiredCapabilities.every((cap) => capabilities.includes(cap))
+}
+
+/**
+ * Check if user has any of the specified capabilities
+ */
+export function hasAnyCapability(
+  capabilities: Capability[],
+  requiredCapabilities: Capability[],
+): boolean {
+  if (capabilities.includes('admin')) {
+    return true
+  }
+  return requiredCapabilities.some((cap) => capabilities.includes(cap))
+}
+
+/**
+ * Check if user is admin
+ */
+export function isAdmin(capabilities: Capability[]): boolean {
+  return capabilities.includes('admin')
+}
+
+/**
+ * Check if AuthUser has a specific capability
+ */
+export function userHasCapability(
+  user: AuthUser | null | undefined,
+  capability: Capability,
+): boolean {
+  if (!user) return false
+  return hasCapability(user.capabilities, capability)
+}
+
+/**
+ * Check if AuthUser is admin
+ */
+export function userIsAdmin(user: AuthUser | null | undefined): boolean {
+  if (!user) return false
+  return isAdmin(user.capabilities)
+}

src/auth/client.ts

@@ -0,0 +1,71 @@
+/**
+ * Auth Client Module
+ *
+ * Client-side authentication utilities and navigation helpers.
+ * This module is safe to import in browser code.
+ */
+
+import type { OAuthProvider } from './types'
+
+// ============================================================================
+// Auth Client
+// ============================================================================
+
+/**
+ * Client-side auth utilities for OAuth flows
+ */
+export const authClient = {
+  signIn: {
+    /**
+     * Initiate OAuth sign-in with a social provider
+     */
+    social: ({ provider }: { provider: OAuthProvider }) => {
+      window.location.href = `/auth/${provider}/start`
+    },
+  },
+
+  /**
+   * Sign out the current user
+   */
+  signOut: async () => {
+    window.location.href = '/auth/signout'
+  },
+}
+
+// ============================================================================
+// Navigation Helpers
+// ============================================================================
+
+/**
+ * Navigate to sign-in page
+ */
+export function navigateToSignIn(
+  provider?: OAuthProvider,
+  returnTo?: string,
+): void {
+  if (provider) {
+    const url = returnTo
+      ? `/auth/${provider}/start?returnTo=${encodeURIComponent(returnTo)}`
+      : `/auth/${provider}/start`
+    window.location.href = url
+  } else {
+    const url = returnTo
+      ? `/login?returnTo=${encodeURIComponent(returnTo)}`
+      : '/login'
+    window.location.href = url
+  }
+}
+
+/**
+ * Navigate to sign-out
+ */
+export function navigateToSignOut(): void {
+  window.location.href = '/auth/signout'
+}
+
+/**
+ * Get current URL path for return-to parameter
+ */
+export function getCurrentPath(): string {
+  return window.location.pathname + window.location.search
+}