@amirulabu/create-recurring-rabbit-app 0.0.0-alpha

package/templates/default/src/server/auth/config.ts

@@ -0,0 +1,241 @@
+/**
+ * Authentication Configuration Module
+ *
+ * This module configures the server-side authentication system using better-auth.
+ * It handles user authentication, session management, email verification, and
+ * password reset functionality.
+ *
+ * KEY AUTHENTICATION FLOWS:
+ * 1. Email/Password Registration - Users register with email and password, must verify email before access
+ * 2. Email/Password Sign In - Verified users can sign in with credentials
+ * 3. Email Verification - Users receive verification link via email to activate account
+ * 4. Password Reset - Users can request password reset via email link
+ *
+ * SECURITY CONSIDERATIONS:
+ * - Email verification is REQUIRED before account access (prevents fake/bot accounts)
+ * - Sessions expire after 7 days with daily refresh (limits credential exposure window)
+ * - Secret key must be strong and kept in environment variables (never in code)
+ * - Password reset links are single-use and time-limited
+ * - CSRF protection handled by better-auth through same-site cookies
+ * - Session cookies have strict prefix to avoid conflicts with other cookies
+ *
+ * DATABASE PATTERN:
+ * Uses Drizzle ORM adapter with dual database support:
+ * - PostgreSQL: For production (uses DATABASE_URL)
+ * - SQLite: For development/testing (fallback)
+ */
+
+import { betterAuth } from 'better-auth'
+import { drizzleAdapter } from 'better-auth/adapters/drizzle'
+import { tanstackStartCookies } from 'better-auth/tanstack-start'
+import { db } from '@/server/db'
+import { users, sessions, accounts, verifications } from '@/server/db/schema'
+import { env } from '@/lib/env'
+import { sendVerificationEmail, sendPasswordResetEmail } from '@/lib/email'
+
+/**
+ * Main authentication instance configured for the application.
+ *
+ * This instance is exported and used throughout the application to handle
+ * all server-side authentication operations including sign in, sign out,
+ * session verification, and token generation.
+ *
+ * CONFIGURATION DECISIONS:
+ * - Database Adapter: Drizzle ORM allows flexible database switching (PostgreSQL/SQLite)
+ * - Email Verification Required: Prevents spam accounts and ensures users own their email
+ * - Session Duration: 7 days balances user convenience with security
+ * - Cookie Cache: 5-minute cache reduces database hits for session lookups
+ * - Cross-subdomain cookies disabled: Prevents session leakage between subdomains
+ *
+ * @example
+ * ```ts
+ * import { auth } from '@/server/auth/config'
+ *
+ * // Verify session from request
+ * const session = await auth.api.getSession({
+ *   headers: request.headers
+ * })
+ * ```
+ */
+export const auth = betterAuth({
+  /**
+   * Database configuration using Drizzle adapter.
+   *
+   * The adapter bridges better-auth with the application's database schema.
+   * Using 'postgres' provider for production DATABASE_URL, falls back to 'sqlite'.
+   *
+   * SECURITY: Database credentials must be protected via environment variables.
+   */
+  database: drizzleAdapter(db, {
+    provider: env.DATABASE_URL ? 'pg' : 'sqlite',
+    schema: {
+      user: users,
+      session: sessions,
+      account: accounts,
+      verification: verifications,
+    },
+  }),
+  /**
+   * Base URL for the authentication server.
+   *
+   * Used for constructing callback URLs, verification links, and reset password links.
+   * Must match the domain where auth endpoints are hosted.
+   *
+   * SECURITY: Must be HTTPS in production to prevent token interception.
+   */
+  baseURL: env.BETTER_AUTH_URL,
+  /**
+   * Secret key for signing and encrypting tokens.
+   *
+   * Used to sign JWT tokens and encrypt sensitive session data.
+   * This is a critical security value - if compromised, all sessions can be forged.
+   *
+   * SECURITY REQUIREMENTS:
+   * - Must be at least 32 characters long
+   * - Must be cryptographically random
+   * - Must never be committed to version control
+   * - Must be rotated periodically in production
+   */
+  secret: env.BETTER_AUTH_SECRET,
+  /**
+   * Email and password authentication configuration.
+   *
+   * Enables traditional email/password authentication flow with required
+   * email verification for security.
+   *
+   * SECURITY CONSIDERATIONS:
+   * - Email verification prevents fake/throwaway accounts
+   * - Passwords are hashed automatically by better-auth before storage
+   * - Verification and reset links are time-limited by default
+   */
+  emailAndPassword: {
+    enabled: true,
+    /**
+     * Requires email verification before users can sign in.
+     *
+     * This ensures users own the email address they register with and
+     * prevents automated account creation by bots.
+     */
+    requireEmailVerification: true,
+    /**
+     * Sends email verification link to new users.
+     *
+     * @param user - The user object containing email and user ID
+     * @param url - The verification URL that user must click
+     *
+     * SECURITY: URL contains signed token that expires, preventing replay attacks.
+     *
+     * @example
+     * User receives email with link like:
+     * https://example.com/verify?token=abc123...
+     */
+    sendVerificationEmail: async ({
+      user,
+      url,
+    }: {
+      user: { email: string }
+      url: string
+    }) => {
+      await sendVerificationEmail(user.email, url)
+    },
+    /**
+     * Sends password reset email to users who forgot their password.
+     *
+     * @param user - The user object containing email and user ID
+     * @param url - The password reset URL that user must click
+     *
+     * SECURITY:
+     * - Link is single-use and expires automatically
+     * - User must verify email before requesting reset
+     * - Old password is invalidated upon successful reset
+     *
+     * @example
+     * User receives email with link like:
+     * https://example.com/reset-password?token=xyz789...
+     */
+    sendResetPassword: async ({
+      user,
+      url,
+    }: {
+      user: { email: string }
+      url: string
+    }) => {
+      await sendPasswordResetEmail(user.email, url)
+    },
+  },
+  /**
+   * Session configuration controlling authentication persistence.
+   *
+   * SECURITY RATIONALE:
+   * - 7-day expiration: Long enough for user convenience, short enough to limit exposure
+   * - 24-hour update: Refreshes session daily, invalidating old tokens
+   * - Cookie cache: Reduces database load while maintaining security
+   */
+  session: {
+    /**
+     * Session expires after 7 days (604800 seconds).
+     *
+     * SECURITY: Shorter sessions are more secure but require more frequent sign-ins.
+     * 7 days is a reasonable balance for most applications.
+     */
+    expiresIn: 60 * 60 * 24 * 7,
+    /**
+     * Session age update interval (86400 seconds = 24 hours).
+     *
+     * Updates the session expiration time every 24 hours while the user
+     * remains active. This extends the session while keeping it fresh.
+     *
+     * SECURITY: Regular refreshes limit the window for stolen session tokens.
+     */
+    updateAge: 60 * 60 * 24,
+    /**
+     * Cookie cache configuration to reduce database queries.
+     *
+     * Caches session data in cookies for 5 minutes to avoid hitting the
+     * database on every request while maintaining session validity.
+     *
+     * SECURITY:
+     * - Cache duration (5 min) is short enough to be secure
+     * - Falls back to database on cache miss
+     * - Does not store sensitive data in cache
+     */
+    cookieCache: {
+      enabled: true,
+      maxAge: 60 * 5,
+    },
+  },
+  /**
+   * Advanced configuration options for edge cases.
+   */
+  advanced: {
+    /**
+     * Cross-subdomain cookie configuration.
+     *
+     * Disabled for security to prevent session cookie from being accessible
+     * across subdomains. This isolates sessions to specific domains.
+     *
+     * SECURITY: If enabled, a compromised subdomain could hijack session.
+     */
+    crossSubDomainCookies: {
+      enabled: false,
+    },
+    /**
+     * Cookie prefix for all authentication cookies.
+     *
+     * Adds a prefix to all better-auth cookies to prevent conflicts with
+     * other cookies in the same domain.
+     *
+     * SECURITY: Prevents cookie collisions and makes cookies easily identifiable.
+     */
+    cookiePrefix: 'better-auth',
+  },
+  /**
+   * Plugins configuration.
+   *
+   * Extends better-auth functionality with additional features.
+   *
+   * IMPORTANT: tanstackStartCookies plugin must be the LAST plugin in the array
+   * to ensure proper cookie handling for TanStack Start.
+   */
+  plugins: [tanstackStartCookies()],
+})

package/templates/default/src/server/db/index.ts

@@ -0,0 +1,153 @@
+/**
+ * Database Connection Module
+ *
+ * This module provides the database connection instance and connection management.
+ * It abstracts the differences between SQLite (development) and PostgreSQL (production)
+ * through a unified Drizzle ORM interface.
+ *
+ * Database Design Decisions:
+ * - SQLite with WAL mode for development: Better concurrency and performance
+ * - PostgreSQL for production: Enterprise-grade scaling, reliability, and features
+ * - Connection pooling for PostgreSQL with configurable limits
+ * - Singleton pattern: One database connection instance per application lifecycle
+ *
+ * Migration Strategy:
+ * - Use drizzle-kit to generate migration files from schema changes
+ * - Development: `npx drizzle-kit push` for rapid schema changes
+ * - Production: `pnpm db:migrate` for versioned migrations
+ *
+ * Development vs Production:
+ * - Development:
+ *   - SQLite database stored in `data/app.db` by default
+ *   - WAL mode enabled for better read/write concurrency
+ *   - Synchronous mode set to NORMAL for faster writes (less durability)
+ *   - Debug logging function registered for query profiling
+ * - Production:
+ *   - PostgreSQL connection via DATABASE_URL
+ *   - Connection pool with max 20 connections
+ *   - 30-second idle timeout to free unused connections
+ *   - 60-second connection timeout for reliability
+ *
+ * Connection Management:
+ * - Database connection is initialized at module load time
+ * - Use closeDatabaseConnection() for graceful shutdown (testing, server restart)
+ * - Never manually close the connection during normal operation
+ */
+
+import { drizzle } from 'drizzle-orm/better-sqlite3'
+import { drizzle as drizzlePostgres } from 'drizzle-orm/postgres-js'
+import Database from 'better-sqlite3'
+import postgres from 'postgres'
+import { env } from '@/lib/env'
+import * as schema from './schema'
+
+const isProduction = env.NODE_ENV === 'production'
+
+let sqlite: Database.Database | null = null
+let postgresClient: postgres.Sql | null = null
+
+let db: ReturnType<typeof drizzle> | ReturnType<typeof drizzlePostgres>
+
+if (isProduction && env.DATABASE_URL) {
+  postgresClient = postgres(env.DATABASE_URL, {
+    max: 20,
+    idle_timeout: 30,
+    connect_timeout: 60,
+  })
+  db = drizzlePostgres(postgresClient, { schema })
+} else {
+  const dbPath = env.DATABASE_URL ?? 'data/app.db'
+  sqlite = new Database(dbPath)
+  sqlite.pragma('journal_mode = WAL')
+
+  if (env.NODE_ENV === 'development') {
+    sqlite.pragma('synchronous = NORMAL')
+    sqlite.function('profile', () => {
+      console.log('[SQLite] Query executed')
+    })
+  }
+
+  db = drizzle(sqlite, { schema })
+}
+
+/**
+ * Database instance
+ *
+ * Unified Drizzle ORM instance that works with both SQLite and PostgreSQL.
+ * The database type is determined at build time based on NODE_ENV environment variable.
+ * Use this instance to perform all database operations through type-safe
+ * Drizzle query builder.
+ *
+ * Type safety: Uses conditional types to ensure type safety based on the build-time
+ * environment (development: SQLite, production: PostgreSQL). All db.select(), db.insert(),
+ * db.update(), and db.delete() operations are fully typed without union type conflicts.
+ *
+ * @example
+ * import { db } from './db'
+ * import { users } from './db/schema'
+ *
+ * const allUsers = await db.select().from(users)
+ * const newUser = await db.insert(users).values({ email: 'test@example.com', name: 'Test', emailVerified: true }).returning()
+ * const updatedUser = await db.update(users).set({ name: 'Updated' }).where(eq(users.id, 'id')).returning()
+ */
+export { db }
+
+/**
+ * Type guard to check if database is PostgreSQL
+ *
+ * Useful for branching logic when database-specific features are needed.
+ *
+ * @returns true if PostgreSQL, false if SQLite
+ *
+ * @example
+ * if (isPostgres()) {
+ *   // PostgreSQL-specific code
+ * } else {
+ *   // SQLite-specific code
+ * }
+ */
+export function isPostgres(): boolean {
+  return isProduction && env.DATABASE_URL !== undefined
+}
+
+/**
+ * Gracefully closes the database connection
+ *
+ * This function should be called when shutting down the application,
+ * typically in server shutdown handlers or test teardown. It properly
+ * closes both PostgreSQL and SQLite connections, releasing any
+ * held resources.
+ *
+ * Side Effects:
+ * - Closes the PostgreSQL connection pool if in production
+ * - Closes the SQLite database file handle if in development
+ * - Sets the internal connection instances to null
+ *
+ * Usage:
+ * - Application shutdown: Call when server receives termination signal
+ * - Test teardown: Call in afterAll() to clean up test database
+ * - Server restart: Call before reinitializing the connection
+ *
+ * @example
+ * // In server shutdown handler
+ * process.on('SIGTERM', async () => {
+ *   await closeDatabaseConnection()
+ *   process.exit(0)
+ * })
+ *
+ * @example
+ * // In test teardown
+ * afterAll(async () => {
+ *   await closeDatabaseConnection()
+ * })
+ *
+ * @returns {Promise<void>} Resolves when all connections are closed
+ */
+export async function closeDatabaseConnection() {
+  if (postgresClient) {
+    await postgresClient.end()
+  }
+  if (sqlite) {
+    sqlite.close()
+  }
+}

package/templates/default/src/server/db/migrate.ts

@@ -0,0 +1,125 @@
+/**
+ * Database Migration Module
+ *
+ * This module handles database schema migrations using Drizzle ORM's migration system.
+ * It provides the runMigrations function to apply pending migrations to the database.
+ *
+ * Database Design Decisions:
+ * - Migrations are SQL files generated by drizzle-kit from schema changes
+ * - Migration files store a journal of applied migrations in the database
+ * - Supports both SQLite (development) and PostgreSQL (production) via unified API
+ *
+ * Migration Strategy:
+ * - Generate migrations: `npx drizzle-kit generate`
+ * - Run migrations: Use this module's runMigrations() function
+ * - For complex multi-statement migrations, use the CLI: `pnpm db:migrate`
+ * - For simple schema changes during development, use: `npx drizzle-kit push`
+ *
+ * Development vs Production:
+ * - Development:
+ *   - SQLite migrations run in a single transaction
+ *   - Multi-statement SQL may fail due to SQLite limitations
+ *   - Use drizzle-kit CLI for complex migrations
+ * - Production:
+ *   - PostgreSQL supports complex multi-statement migrations
+ *   - Migrations are applied atomically with proper transaction handling
+ *   - Migration journal tracks all applied changes for rollback capability
+ *
+ * Migration Folder Structure:
+ * - Located at: `{project_root}/drizzle/migrations`
+ * - Contains SQL migration files and a meta journal file
+ * - Migration files are named with timestamp prefix for ordering
+ */
+
+import { migrate } from 'drizzle-orm/better-sqlite3/migrator'
+import { db } from './index'
+import path from 'path'
+
+/**
+ * Runs all pending database migrations
+ *
+ * This function checks for unapplied migrations in the migrations folder
+ * and applies them to the database in order. It uses Drizzle ORM's migration
+ * system which tracks applied migrations in a __drizzle_migrations table.
+ *
+ * Purpose:
+ * - Initialize the database schema in a new environment
+ * - Apply schema changes when upgrading the application
+ * - Ensure database structure matches the code schema
+ *
+ * Parameters:
+ * - None (uses default migrations folder path)
+ *
+ * Return Value:
+ * - Promise<void>: Resolves when all migrations complete successfully
+ *
+ * Side Effects:
+ * - Creates or modifies database tables and indexes
+ * - Inserts migration records into __drizzle_migrations table
+ * - Logs migration progress to console
+ * - May throw errors for failed migrations
+ *
+ * Error Handling:
+ * - Catches and re-throws migration errors with context
+ * - Special handling for multi-statement SQL errors in SQLite
+ * - Recommends alternative migration approach when push fails
+ *
+ * Example Usage:
+ * ```typescript
+ * import { runMigrations } from './db/migrate'
+ *
+ * async function initializeApp() {
+ *   try {
+ *     await runMigrations()
+ *     console.log('Database is up to date')
+ *   } catch (error) {
+ *     console.error('Migration failed:', error)
+ *     process.exit(1)
+ *   }
+ * }
+ *
+ * initializeApp()
+ * ```
+ *
+ * CLI Usage:
+ * ```bash
+ * # Run migrations via npm script
+ * pnpm db:migrate
+ *
+ * # Or run directly with Node
+ * node -r dotenv/config dist/db/migrate.js
+ * ```
+ *
+ * Notes:
+ * - Migrations run in a transaction (atomic all-or-nothing)
+ * - Already-applied migrations are automatically skipped
+ * - Migration folder path is relative to process.cwd()
+ * - For SQLite, multi-statement migrations require drizzle-kit CLI
+ *
+ * @throws {Error} If migrations folder is not found
+ * @throws {Error} If a migration SQL file is invalid
+ * @throws {Error} If database connection fails
+ * @throws {Error} For multi-statement SQL in SQLite (with helpful message)
+ */
+export async function runMigrations() {
+  const migrationsFolder = path.join(process.cwd(), 'drizzle/migrations')
+
+  console.log('Running database migrations...')
+
+  try {
+    await migrate(db as any, { migrationsFolder })
+    console.log('✓ Migrations completed successfully')
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      error.message.includes('more than one statement')
+    ) {
+      console.error(
+        '⚠ Migration encountered multi-statement SQL. Please use drizzle-kit migrate command.'
+      )
+      console.error('Run: pnpm db:migrate')
+      throw error
+    }
+    throw error
+  }
+}

package/templates/default/src/server/db/schema.ts

@@ -0,0 +1,170 @@
+/**
+ * Database Schema Module
+ *
+ * This module defines the complete database schema for the application using Drizzle ORM.
+ * It uses SQLite as the default database, with PostgreSQL support for production environments.
+ *
+ * Database Design Decisions:
+ * - Uses cuid2 for generating unique, non-sequential IDs that are more secure than auto-increment
+ * - Stores timestamps as integers (Unix milliseconds) for SQLite compatibility
+ * - Implements cascade deletion to maintain referential integrity
+ * - Follows authentication best practices with separate accounts, sessions, and verification tables
+ *
+ * Migration Strategy:
+ * - Schema changes should be made using drizzle-kit generate to create migration files
+ * - Use `pnpm db:migrate` for complex migrations with multiple SQL statements
+ * - Use `npx drizzle-kit push` for simple schema changes during development
+ *
+ * Development vs Production:
+ * - Development: SQLite with WAL mode for better concurrency
+ * - Production: PostgreSQL for better scaling and reliability
+ * - All tables use integer timestamp mode which works seamlessly with both databases
+ */
+
+import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core'
+import { createId } from '@paralleldrive/cuid2'
+
+/**
+ * Users table
+ *
+ * Core user identity and profile information. This table stores the primary user
+ * record and serves as the parent for all related authentication and session data.
+ *
+ * Relationships:
+ * - One-to-many with sessions: A user can have multiple active sessions
+ * - One-to-many with accounts: A user can link multiple OAuth providers
+ *
+ * Key Constraints:
+ * - email: Unique constraint ensures no duplicate email addresses
+ * - emailVerified: Defaults to false, requires explicit verification
+ *
+ * Indexes:
+ * - Primary key: id (cuid2 string)
+ * - Unique index: email
+ *
+ * Cascade Behavior:
+ * - Deleting a user cascades to related sessions and accounts via ON DELETE CASCADE
+ */
+export const users = sqliteTable('users', {
+  id: text('id')
+    .primaryKey()
+    .$defaultFn(() => createId()),
+  email: text('email').unique().notNull(),
+  name: text('name').notNull(),
+  emailVerified: integer('email_verified', { mode: 'boolean' }).default(false),
+  image: text('image'),
+  createdAt: integer('created_at', { mode: 'timestamp' }).$defaultFn(
+    () => new Date()
+  ),
+  updatedAt: integer('updated_at', { mode: 'timestamp' }).$onUpdateFn(
+    () => new Date()
+  ),
+})
+
+/**
+ * Sessions table
+ *
+ * Manages active user sessions for authentication. Each session represents a logged-in
+ * user across a specific device or browser.
+ *
+ * Relationships:
+ * - Many-to-one with users: Each session belongs to exactly one user
+ *
+ * Key Constraints:
+ * - userId: Foreign key to users table with cascade delete
+ * - expiresAt: Required timestamp for session expiration
+ *
+ * Indexes:
+ * - Primary key: id (session token)
+ * - Foreign key index: user_id for efficient lookups
+ *
+ * Cascade Behavior:
+ * - Deleting the associated user automatically removes all sessions
+ */
+export const sessions = sqliteTable('sessions', {
+  id: text('id').primaryKey(),
+  userId: text('user_id')
+    .notNull()
+    .references(() => users.id, { onDelete: 'cascade' }),
+  expiresAt: integer('expires_at', { mode: 'timestamp' }).notNull(),
+  createdAt: integer('created_at', { mode: 'timestamp' }).$defaultFn(
+    () => new Date()
+  ),
+})
+
+/**
+ * Accounts table
+ *
+ * Stores OAuth provider connections for each user. Supports linking multiple
+ * authentication providers (Google, GitHub, etc.) to a single user account.
+ *
+ * Relationships:
+ * - Many-to-one with users: Multiple accounts can belong to one user
+ *
+ * Key Constraints:
+ * - userId: Foreign key to users table with cascade delete
+ * - accountId: Unique identifier from the OAuth provider
+ * - providerId: OAuth provider name (e.g., 'google', 'github')
+ *
+ * Indexes:
+ * - Primary key: id (cuid2 string)
+ * - Foreign key index: user_id
+ * - Composite unique: (account_id, provider_id) prevents duplicate provider links
+ *
+ * Cascade Behavior:
+ * - Deleting the associated user removes all OAuth provider connections
+ */
+export const accounts = sqliteTable('accounts', {
+  id: text('id')
+    .primaryKey()
+    .$defaultFn(() => createId()),
+  userId: text('user_id')
+    .notNull()
+    .references(() => users.id, { onDelete: 'cascade' }),
+  accountId: text('account_id').notNull(),
+  providerId: text('provider_id').notNull(),
+  accessToken: text('access_token'),
+  refreshToken: text('refresh_token'),
+  expiresAt: integer('expires_at', { mode: 'timestamp' }),
+  createdAt: integer('created_at', { mode: 'timestamp' }).$defaultFn(
+    () => new Date()
+  ),
+})
+
+/**
+ * Verifications table
+ *
+ * Stores temporary verification codes for email verification, password reset,
+ * and other one-time authentication flows.
+ *
+ * Relationships:
+ * - No foreign key relationships - standalone table
+ *
+ * Key Constraints:
+ * - identifier: Email address or phone number being verified
+ * - value: Verification code or token
+ * - expiresAt: Required timestamp for code expiration
+ *
+ * Indexes:
+ * - Primary key: id (cuid2 string)
+ * - Non-unique index: identifier for efficient lookup by email/phone
+ *
+ * Cascade Behavior:
+ * - No cascade behavior - records must be manually expired or deleted
+ *
+ * Usage:
+ * - Records are typically created with a short expiry (e.g., 15-30 minutes)
+ * - After successful verification, records should be deleted to prevent reuse
+ * - Expired records can be cleaned up via a scheduled job
+ */
+export const verifications = sqliteTable('verifications', {
+  id: text('id')
+    .primaryKey()
+    .$defaultFn(() => createId()),
+  identifier: text('identifier').notNull(),
+  value: text('value').notNull(),
+  expiresAt: integer('expires_at', { mode: 'timestamp' }).notNull(),
+  createdAt: integer('created_at', { mode: 'timestamp' }).$defaultFn(
+    () => new Date()
+  ),
+})