ui-syncup 0.3.13 → 0.4.0-beta.2

package/src/lib/health-check.ts

@@ -0,0 +1,229 @@
+/**
+ * Health Check Utilities
+ * 
+ * Validates external service connections for deployment health monitoring.
+ * Used by the /api/health endpoint to verify system readiness.
+ * 
+ * @module lib/health-check
+ */
+
+import { db } from './db'
+import { storageClient } from './storage'
+import { authConfig } from './auth-config'
+import { env } from './env'
+import { HeadBucketCommand } from '@aws-sdk/client-s3'
+
+/**
+ * Health check result for a single service
+ */
+export interface ServiceHealthResult {
+  name: string
+  status: 'healthy' | 'unhealthy'
+  message?: string
+  responseTime?: number
+  error?: string
+}
+
+/**
+ * Overall health check result
+ */
+export interface HealthCheckResult {
+  status: 'healthy' | 'degraded' | 'unhealthy'
+  services: ServiceHealthResult[]
+  timestamp: string
+}
+
+/**
+ * Validate database connection
+ * 
+ * Executes a simple query to verify PostgreSQL connectivity
+ * and measure response time.
+ */
+export async function checkDatabase(): Promise<ServiceHealthResult> {
+  const startTime = Date.now()
+  
+  try {
+    // Execute simple query to verify connection
+    await db.execute('SELECT 1 as health_check')
+    
+    const responseTime = Date.now() - startTime
+    
+    return {
+      name: 'database',
+      status: 'healthy',
+      message: 'PostgreSQL connection successful',
+      responseTime,
+    }
+  } catch (error) {
+    const responseTime = Date.now() - startTime
+    
+    return {
+      name: 'database',
+      status: 'unhealthy',
+      message: 'Failed to connect to PostgreSQL',
+      responseTime,
+      error: error instanceof Error ? error.message : 'Unknown error',
+    }
+  }
+}
+
+/**
+ * Validate storage connection
+ * 
+ * Verifies Cloudflare R2 bucket accessibility by checking
+ * if the configured bucket exists and is accessible.
+ */
+export async function checkStorage(): Promise<ServiceHealthResult> {
+  const startTime = Date.now()
+  
+  try {
+    // Check if bucket is accessible using HeadBucket
+    const command = new HeadBucketCommand({
+      Bucket: env.R2_BUCKET_NAME,
+    })
+    
+    // Access the internal S3 client to send the command
+    await storageClient.send(command)
+    
+    const responseTime = Date.now() - startTime
+    
+    return {
+      name: 'storage',
+      status: 'healthy',
+      message: 'Cloudflare R2 bucket accessible',
+      responseTime,
+    }
+  } catch (error) {
+    const responseTime = Date.now() - startTime
+    
+    return {
+      name: 'storage',
+      status: 'unhealthy',
+      message: 'Failed to access Cloudflare R2 bucket',
+      responseTime,
+      error: error instanceof Error ? error.message : 'Unknown error',
+    }
+  }
+}
+
+/**
+ * Validate authentication configuration
+ * 
+ * Verifies that all required OAuth credentials are present
+ * and properly configured. Does not make external API calls.
+ */
+export async function checkAuth(): Promise<ServiceHealthResult> {
+  const startTime = Date.now()
+  
+  try {
+    // Validate OAuth configuration
+    const hasGoogleClientId = !!authConfig.providers.google.clientId
+    const hasGoogleClientSecret = !!authConfig.providers.google.clientSecret
+    const hasGoogleRedirectUri = !!authConfig.providers.google.redirectUri
+    const hasAuthSecret = !!authConfig.session.secret
+    const hasAuthUrl = !!authConfig.session.baseUrl
+    
+    if (!hasGoogleClientId || !hasGoogleClientSecret || !hasGoogleRedirectUri) {
+      throw new Error('Missing Google OAuth credentials')
+    }
+    
+    if (!hasAuthSecret || !hasAuthUrl) {
+      throw new Error('Missing better-auth configuration')
+    }
+    
+    // Validate secret length
+    if (authConfig.session.secret.length < 32) {
+      throw new Error('BETTER_AUTH_SECRET must be at least 32 characters')
+    }
+    
+    const responseTime = Date.now() - startTime
+    
+    return {
+      name: 'auth',
+      status: 'healthy',
+      message: 'Authentication configuration valid',
+      responseTime,
+    }
+  } catch (error) {
+    const responseTime = Date.now() - startTime
+    
+    return {
+      name: 'auth',
+      status: 'unhealthy',
+      message: 'Invalid authentication configuration',
+      responseTime,
+      error: error instanceof Error ? error.message : 'Unknown error',
+    }
+  }
+}
+
+/**
+ * Validate all external services
+ * 
+ * Runs health checks for database, storage, and auth in parallel.
+ * Returns overall health status based on individual service results.
+ * 
+ * @returns Health check result with status for all services
+ * 
+ * @example
+ * ```ts
+ * const health = await validateExternalServices()
+ * 
+ * if (health.status === 'unhealthy') {
+ *   console.error('System unhealthy:', health.services)
+ * }
+ * ```
+ */
+export async function validateExternalServices(): Promise<HealthCheckResult> {
+  // Run all health checks in parallel
+  const results = await Promise.allSettled([
+    checkDatabase(),
+    checkStorage(),
+    checkAuth(),
+  ])
+  
+  // Extract service results
+  const services: ServiceHealthResult[] = results.map((result, index) => {
+    if (result.status === 'fulfilled') {
+      return result.value
+    }
+    
+    // Handle unexpected errors during health check execution
+    const serviceName = ['database', 'storage', 'auth'][index]
+    return {
+      name: serviceName,
+      status: 'unhealthy' as const,
+      message: 'Health check failed to execute',
+      error: result.reason instanceof Error ? result.reason.message : 'Unknown error',
+    }
+  })
+  
+  // Determine overall status
+  const unhealthyCount = services.filter(s => s.status === 'unhealthy').length
+  
+  let overallStatus: 'healthy' | 'degraded' | 'unhealthy'
+  if (unhealthyCount === 0) {
+    overallStatus = 'healthy'
+  } else if (unhealthyCount === services.length) {
+    overallStatus = 'unhealthy'
+  } else {
+    overallStatus = 'degraded'
+  }
+  
+  return {
+    status: overallStatus,
+    services,
+    timestamp: new Date().toISOString(),
+  }
+}
+
+/**
+ * Quick health check (auth only)
+ * 
+ * Performs a fast health check that only validates configuration
+ * without making network calls. Useful for readiness probes.
+ */
+export async function quickHealthCheck(): Promise<ServiceHealthResult> {
+  return checkAuth()
+}
+

package/src/lib/logger.ts

@@ -0,0 +1,204 @@
+/**
+ * Centralized logging utility
+ * Control all console logs from this single file
+ */
+
+import { createHash, randomUUID } from 'crypto'
+
+type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'none'
+
+interface LoggerConfig {
+  level: LogLevel
+  enabled: boolean
+  timestamp: boolean
+  prefix?: string
+}
+
+const config: LoggerConfig = {
+  level: process.env.NODE_ENV === 'production' ? 'error' : 'debug',
+  enabled: process.env.NODE_ENV !== 'production',
+  timestamp: true,
+  prefix: '[App]',
+}
+
+const levels: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+  none: 4,
+}
+
+function shouldLog(level: LogLevel): boolean {
+  if (!config.enabled) return false
+  return levels[level] >= levels[config.level]
+}
+
+function formatMessage(level: LogLevel, ...args: unknown[]): unknown[] {
+  const parts: unknown[] = []
+  
+  if (config.timestamp) {
+    parts.push(`[${new Date().toISOString()}]`)
+  }
+  
+  if (config.prefix) {
+    parts.push(config.prefix)
+  }
+  
+  parts.push(`[${level.toUpperCase()}]`)
+  parts.push(...args)
+  
+  return parts
+}
+
+// Auth event types
+export type AuthEventType =
+  // Authentication events
+  | 'auth.signup.attempt'
+  | 'auth.signup.success'
+  | 'auth.signup.failure'
+  | 'auth.login.attempt'
+  | 'auth.login.success'
+  | 'auth.login.failure'
+  | 'auth.logout.success'
+  | 'auth.verify_email.attempt'
+  | 'auth.verify_email.success'
+  | 'auth.verify_email.failure'
+  | 'auth.reset_password.request'
+  | 'auth.reset_password.success'
+  | 'auth.reset_password.failure'
+  // Dev/Testing events
+  | 'auth.delete_account.success'
+  | 'auth.delete_account.failure'
+  | 'auth.delete_account.error'
+  | 'auth.force_verify.success'
+  | 'auth.force_verify.failure'
+  | 'auth.force_verify.error'
+  | 'auth.list_sessions.success'
+  | 'auth.list_sessions.failure'
+  | 'auth.list_sessions.error'
+  | 'auth.reset_rate_limit.success'
+  | 'auth.reset_rate_limit.failure'
+  | 'auth.reset_rate_limit.error'
+  // Security events
+  | 'auth.rate_limit.exceeded'
+  | 'auth.token.tampered'
+  | 'auth.session.tampered'
+  | 'auth.reauth.required'
+  | 'auth.reauth.failure'
+  | 'auth.resend_verification.rate_limited'
+  | 'auth.resend_verification.attempt'
+  | 'auth.resend_verification.user_not_found'
+  | 'auth.resend_verification.already_verified'
+  | 'auth.resend_verification.success'
+  | 'auth.resend_verification.validation_error'
+  | 'auth.resend_verification.error'
+  // Email events
+  | 'email.queued'
+  | 'email.sent'
+  | 'email.failed'
+  | 'email.retry'
+
+export type AuthEventOutcome = 'success' | 'failure' | 'error'
+
+export interface AuthLogEvent {
+  // Event identification
+  eventId: string
+  eventType: AuthEventType
+  timestamp: string
+  
+  // User context
+  userId?: string
+  email?: string // Hashed for PII protection
+  
+  // Request context
+  ipAddress?: string
+  userAgent?: string
+  requestId?: string
+  
+  // Outcome
+  outcome: AuthEventOutcome
+  errorCode?: string
+  errorMessage?: string
+  
+  // Additional context
+  metadata?: Record<string, unknown>
+}
+
+/**
+ * Hash email address for PII protection in logs
+ */
+function hashEmail(email: string): string {
+  return createHash('sha256').update(email.toLowerCase()).digest('hex').substring(0, 16)
+}
+
+/**
+ * Log authentication event with structured format
+ */
+export function logAuthEvent(
+  eventType: AuthEventType,
+  context: Omit<AuthLogEvent, 'eventId' | 'eventType' | 'timestamp'> & {
+    email?: string // Will be hashed automatically
+  }
+): void {
+  const event: AuthLogEvent = {
+    eventId: randomUUID(),
+    eventType,
+    timestamp: new Date().toISOString(),
+    ...context,
+    // Hash email if provided
+    email: context.email ? hashEmail(context.email) : undefined,
+  }
+  
+  // Determine log level based on outcome
+  const level: LogLevel = 
+    event.outcome === 'error' ? 'error' :
+    event.outcome === 'failure' ? 'warn' :
+    'info'
+  
+  // Log structured event
+  if (shouldLog(level)) {
+    const logFn = level === 'error' ? console.error : level === 'warn' ? console.warn : console.info
+    logFn(JSON.stringify(event))
+  }
+}
+
+export const logger = {
+  debug: (...args: unknown[]) => {
+    if (shouldLog('debug')) {
+      console.log(...formatMessage('debug', ...args))
+    }
+  },
+
+  info: (...args: unknown[]) => {
+    if (shouldLog('info')) {
+      console.info(...formatMessage('info', ...args))
+    }
+  },
+
+  warn: (...args: unknown[]) => {
+    if (shouldLog('warn')) {
+      console.warn(...formatMessage('warn', ...args))
+    }
+  },
+
+  error: (...args: unknown[]) => {
+    if (shouldLog('error')) {
+      console.error(...formatMessage('error', ...args))
+    }
+  },
+
+  // Configure logger at runtime
+  configure: (newConfig: Partial<LoggerConfig>) => {
+    Object.assign(config, newConfig)
+  },
+
+  // Get current config
+  getConfig: () => ({ ...config }),
+  
+  // Auth event logging
+  authEvent: logAuthEvent,
+}
+
+// Convenience exports
+export const { debug, info, warn, error } = logger

package/src/lib/oauth-errors.ts

@@ -0,0 +1,138 @@
+/**
+ * OAuth Error Mapping Utility
+ *
+ * Maps OAuth error codes to user-friendly messages.
+ * Used for displaying meaningful error messages when OAuth flows fail.
+ *
+ * @module lib/oauth-errors
+ */
+
+/**
+ * Standard OAuth error codes and their user-friendly messages
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2.1
+ */
+export const OAUTH_ERROR_MESSAGES: Record<string, string> = {
+  // Standard OAuth 2.0 errors
+  access_denied: "You cancelled the sign-in. Please try again if you'd like to continue.",
+  invalid_request: "Something went wrong with the sign-in request. Please try again.",
+  server_error: "The sign-in service is temporarily unavailable. Please try again later.",
+  temporarily_unavailable: "The sign-in service is temporarily unavailable. Please try again later.",
+  unauthorized_client: "This application is not authorized for this sign-in method.",
+  unsupported_response_type: "Something went wrong with the sign-in configuration.",
+  invalid_scope: "Something went wrong with the sign-in permissions.",
+  
+  // Custom/extended errors
+  invalid_state: "Your session has expired. Please try signing in again.",
+  account_exists: "This account is already linked to another user.",
+  oauth_error: "An error occurred during sign-in. Please try again.",
+  
+  // Provider-specific errors
+  consent_required: "Please grant the required permissions to sign in.",
+  login_required: "Please sign in to your account first.",
+  interaction_required: "Additional interaction is required to complete sign-in.",
+} as const;
+
+/**
+ * Default error message for unknown error codes
+ */
+export const DEFAULT_ERROR_MESSAGE = "An error occurred during sign-in. Please try again.";
+
+/**
+ * Maps an OAuth error code to a user-friendly message
+ *
+ * @param errorCode - The OAuth error code from the callback
+ * @returns A user-friendly error message
+ *
+ * @example
+ * ```ts
+ * const message = mapOAuthError("access_denied");
+ * // "You cancelled the sign-in. Please try again if you'd like to continue."
+ *
+ * const unknown = mapOAuthError("some_unknown_error");
+ * // "An error occurred during sign-in. Please try again."
+ * ```
+ */
+export function mapOAuthError(errorCode: string | null | undefined): string {
+  if (!errorCode) {
+    return DEFAULT_ERROR_MESSAGE;
+  }
+
+  // Normalize the error code (lowercase, trim)
+  const normalizedCode = errorCode.toLowerCase().trim();
+
+  return OAUTH_ERROR_MESSAGES[normalizedCode] || DEFAULT_ERROR_MESSAGE;
+}
+
+/**
+ * Parses OAuth error parameters from a URL
+ *
+ * @param url - The URL to parse (can be full URL or just search params)
+ * @returns Object with error code and description if present
+ *
+ * @example
+ * ```ts
+ * const result = parseOAuthErrorFromURL("/sign-in?error=access_denied&error_description=User+cancelled");
+ * // { error: "access_denied", errorDescription: "User cancelled" }
+ * ```
+ */
+export function parseOAuthErrorFromURL(url: string): {
+  error: string | null;
+  errorDescription: string | null;
+} {
+  try {
+    // Handle both full URLs and just search params
+    const searchParams = url.includes("?")
+      ? new URLSearchParams(url.split("?")[1])
+      : new URLSearchParams(url);
+
+    return {
+      error: searchParams.get("error"),
+      errorDescription: searchParams.get("error_description"),
+    };
+  } catch {
+    return { error: null, errorDescription: null };
+  }
+}
+
+/**
+ * Gets a display-ready error message from URL parameters
+ *
+ * @param url - The URL containing error parameters
+ * @returns User-friendly error message or null if no error
+ *
+ * @example
+ * ```ts
+ * const message = getOAuthErrorFromURL("?error=access_denied");
+ * // "You cancelled the sign-in. Please try again if you'd like to continue."
+ * ```
+ */
+export function getOAuthErrorFromURL(url: string): string | null {
+  const { error } = parseOAuthErrorFromURL(url);
+  if (!error) return null;
+  return mapOAuthError(error);
+}
+
+/**
+ * Checks if an error code represents a user-initiated cancellation
+ *
+ * @param errorCode - The OAuth error code
+ * @returns True if the user cancelled the flow
+ */
+export function isUserCancellation(errorCode: string | null | undefined): boolean {
+  if (!errorCode) return false;
+  const normalized = errorCode.toLowerCase().trim();
+  return normalized === "access_denied" || normalized === "consent_required";
+}
+
+/**
+ * Checks if an error code represents a server/temporary error
+ *
+ * @param errorCode - The OAuth error code
+ * @returns True if the error is temporary and retry may help
+ */
+export function isTemporaryError(errorCode: string | null | undefined): boolean {
+  if (!errorCode) return false;
+  const normalized = errorCode.toLowerCase().trim();
+  return normalized === "server_error" || normalized === "temporarily_unavailable";
+}