lorentz/wulf-pulse
1
0
Fork 0
Code Issues 1 Pull requests Projects Releases Packages Wiki Activity Actions
wulf-pulse/tasks/tasks-prd-auth-user-management.md
root 9f912aed24 feat: add authentication, user management, and admin features 
Added comprehensive authentication and authorization system:

Authentication System:
- Better Auth integration with session management
- Login/logout pages and API routes
- Middleware for route protection
- Auth utilities and client libraries

User Management:
- User list, detail, and invite pages
- User API endpoints (CRUD operations)
- Session management for users
- Profile settings page

Role-Based Access Control:
- Role management pages (list, create, edit)
- Permission system with granular controls
- Role assignment to users
- Role API endpoints

Admin Features:
- Audit log page for tracking system events
- Admin settings page
- Audit service for logging user actions

Additional Features:
- Quotes management pages and components
- SalesBldr API integration
- Email service for notifications

Configuration & Documentation:
- Updated docker-compose.yml
- MCP server configuration (mcp.json)
- CVE-2025-55182 security review documentation
- Standards guide and PRD documents
- Re-enabling authentication documentation

Database Migrations:
- 012: Auth tables (users, sessions, accounts, verifications)
- 013: Role tables (roles, permissions, role_permissions, user_roles)
- 014: Admin settings table

UI Updates:
- Updated dashboard layout
- Enhanced app layout with auth integration
2026-01-31 12:43:14 -05:00

13 KiB
Raw Blame History

Tasks: Authentication & User Management Module

Relevant Files

Core Auth Infrastructure

  • lib/auth.ts - Better Auth server configuration with plugins
  • lib/auth-client.ts - Better Auth client for React components
  • lib/auth-utils.ts - Server-side auth utilities and permission checking
  • lib/permissions.ts - RBAC permission definitions and access control
  • lib/bootstrap.ts - Bootstrap and initial setup functions
  • lib/services/email.ts - SMTP email service for magic links
  • lib/services/audit.ts - Audit logging service
  • app/api/auth/[...all]/route.ts - Better Auth API route handler
  • middleware.ts - Route protection middleware

Database Migrations

  • migrations/012_create_auth_tables.sql - Better Auth core tables (user, session, account, verification, two_factor)
  • migrations/013_create_role_tables.sql - Role and permission tables with default roles
  • migrations/014_create_admin_settings.sql - App settings, session policies, email templates, and audit log tables

Auth Pages

  • app/auth/sign-in/page.tsx - Sign-in page with magic link and Microsoft options
  • app/auth/verify/page.tsx - Magic link verification page
  • app/auth/2fa/page.tsx - Two-factor authentication verification page
  • app/auth/setup/page.tsx - Initial account setup page
  • app/auth/layout.tsx - Auth pages layout (no navigation)

Auth Components

  • components/auth/auth-provider.tsx - Auth context provider for React
  • components/auth/sign-in-form.tsx - Combined sign-in form with both auth methods
  • components/auth/magic-link-form.tsx - Email input for magic link
  • components/auth/microsoft-button.tsx - Microsoft 365 OAuth button
  • components/auth/two-factor-form.tsx - TOTP code input form

User Management Pages

  • app/admin/users/page.tsx - User list page
  • app/admin/users/[id]/page.tsx - User detail/edit page
  • app/admin/users/invite/page.tsx - Invite user page

User Management Components

  • components/admin/users/user-table.tsx - User list table with actions
  • components/admin/users/user-form.tsx - Create/edit user form
  • components/admin/users/invite-user-form.tsx - Invite user via email form
  • components/admin/users/role-badge.tsx - Role display badge
  • components/admin/users/user-actions.tsx - User action dropdown menu
  • components/admin/users/user-sessions.tsx - User session history

Role Management Pages

  • app/admin/roles/page.tsx - Role list page
  • app/admin/roles/[id]/page.tsx - Role detail/edit page
  • app/admin/roles/new/page.tsx - Create new role page

Role Management Components

  • components/admin/roles/role-table.tsx - Role list table
  • components/admin/roles/role-form.tsx - Create/edit role form
  • components/admin/roles/permission-picker.tsx - Permission selection UI

Admin Settings Pages

  • app/admin/settings/page.tsx - Admin settings page with tabs
  • app/admin/audit-log/page.tsx - Audit log viewer page

Admin Settings Components

  • components/admin/settings/microsoft-config.tsx - Microsoft tenant configuration
  • components/admin/settings/session-policies.tsx - CIDR session policy management
  • components/admin/settings/email-templates.tsx - Email template editor
  • components/admin/audit/audit-log-table.tsx - Audit log table with filters

User Settings Pages

  • app/settings/page.tsx - User settings page
  • app/settings/security/page.tsx - Security settings (2FA, sessions)

User Settings Components

  • components/settings/profile-form.tsx - User profile edit form
  • components/settings/two-factor-setup.tsx - 2FA setup wizard
  • components/settings/active-sessions.tsx - Current user's active sessions

API Routes

  • app/api/admin/users/route.ts - User CRUD API
  • app/api/admin/users/[id]/route.ts - Single user API
  • app/api/admin/users/invite/route.ts - User invitation API
  • app/api/admin/roles/route.ts - Role CRUD API
  • app/api/admin/roles/[id]/route.ts - Single role API
  • app/api/admin/settings/route.ts - App settings API
  • app/api/admin/settings/session-policies/route.ts - Session policies API
  • app/api/admin/settings/email-templates/route.ts - Email templates API
  • app/api/admin/audit-log/route.ts - Audit log API
  • app/api/settings/profile/route.ts - User profile API

Notes

  • Unit tests should typically be placed alongside the code files they are testing (e.g., MyComponent.tsx and MyComponent.test.tsx in the same directory).
  • Use npx jest [optional/path/to/test/file] to run tests. Running without a path executes all tests found by the Jest configuration.
  • Better Auth handles most auth logic internally; focus tests on custom business logic.
  • Use existing shadcn/ui components from /components/ui/ for consistency.

Tasks

  • 1.0 Setup Better Auth Core Infrastructure

    • 1.1 Install Better Auth dependencies (better-auth, @better-auth/cli)
    • 1.2 Add required environment variables to .env and .env.local (BETTER_AUTH_SECRET, BETTER_AUTH_URL, SMTP_, DEFAULT_ADMIN_, SESSION_TIMEOUT_SECONDS, AUDIT_LOG_RETENTION_DAYS)
    • 1.3 Create database migration for Better Auth core tables (user, session, account, verification)
    • 1.4 Create lib/auth.ts with Better Auth server configuration
    • 1.5 Create lib/auth-client.ts with Better Auth client for React
    • 1.6 Create app/api/auth/[...all]/route.ts API route handler
    • 1.7 Create middleware.ts for route protection (redirect unauthenticated users to /auth/sign-in)
    • 1.8 Create lib/services/email.ts SMTP email service using environment variables
    • 1.9 Update app/layout.tsx to wrap app with auth session provider

  • 2.0 Implement Authentication Methods (Magic Link & Microsoft 365)

    • 2.1 Configure magic link plugin in lib/auth.ts with sendMagicLink callback using SMTP service
    • 2.2 Configure Microsoft OAuth provider in lib/auth.ts with client ID/secret from env
    • 2.3 Create app/auth/layout.tsx - minimal layout without main navigation
    • 2.4 Create app/auth/sign-in/page.tsx - sign-in page container
    • 2.5 Create components/auth/magic-link-form.tsx - email input with submit
    • 2.6 Create components/auth/microsoft-button.tsx - Microsoft 365 OAuth button
    • 2.7 Create components/auth/sign-in-form.tsx - combined form with both methods
    • 2.8 Create app/auth/verify/page.tsx - magic link verification handler
    • 2.9 Implement "check your email" success state in magic link form
    • 2.10 Add error handling for failed auth attempts with toast notifications

  • 3.0 Implement RBAC & Permission System

    • 3.1 Create database migration for role and permission tables
    • 3.2 Create lib/permissions.ts with permission definitions (tickets, configItems, admin, users, roles, auditLog)
    • 3.3 Define default roles (super-admin, admin, user) with their permissions
    • 3.4 Configure Better Auth admin plugin with access control in lib/auth.ts
    • 3.5 Update lib/auth-client.ts with admin client plugin
    • 3.6 Create helper function hasPermission(user, resource, action) for checking permissions
    • 3.7 Update middleware.ts to check roles for /admin/* routes (require admin or super-admin)
    • 3.8 Create API middleware helper for permission checking in route handlers
    • 3.9 Seed default roles into database on first run

  • 4.0 Build User Management Module

    • 4.1 Create app/api/admin/users/route.ts - GET (list users), POST (create user)
    • 4.2 Create app/api/admin/users/[id]/route.ts - GET, PATCH, DELETE single user
    • 4.3 Create app/api/admin/users/invite/route.ts - POST to send invitation email
    • 4.4 Create components/admin/users/role-badge.tsx - badge component for role display
    • 4.5 Create components/admin/users/user-table.tsx - table with columns: name, email, role, status, actions
    • 4.6 Create components/admin/users/user-actions.tsx - dropdown with edit, deactivate, delete, revoke sessions
    • 4.7 Create app/admin/users/page.tsx - user list page with search/filter
    • 4.8 Create components/admin/users/user-form.tsx - form for editing user (name, email, role)
    • 4.9 Create app/admin/users/[id]/page.tsx - user detail page with edit form and session history
    • 4.10 Create components/admin/users/invite-user-form.tsx - email input with role selection
    • 4.11 Create app/admin/users/invite/page.tsx - invite user page
    • 4.12 Create components/admin/users/user-sessions.tsx - table of user's sessions with revoke
    • 4.13 Implement soft delete (deactivate) and reactivate functionality
    • 4.14 Implement permanent delete with confirmation dialog
    • 4.15 Add super-admin role check to all user management routes

  • 5.0 Build Role Management Module

    • 5.1 Create app/api/admin/roles/route.ts - GET (list roles), POST (create role)
    • 5.2 Create app/api/admin/roles/[id]/route.ts - GET, PATCH, DELETE single role
    • 5.3 Create components/admin/roles/permission-picker.tsx - checkbox grid for selecting permissions
    • 5.4 Create components/admin/roles/role-table.tsx - table with columns: name, permissions count, users count, actions
    • 5.5 Create app/admin/roles/page.tsx - role list page
    • 5.6 Create components/admin/roles/role-form.tsx - form with name input and permission picker
    • 5.7 Create app/admin/roles/new/page.tsx - create new role page
    • 5.8 Create app/admin/roles/[id]/page.tsx - edit role page
    • 5.9 Prevent deletion of default roles (super-admin, admin, user)
    • 5.10 Prevent deletion of roles that are assigned to users (show error)
    • 5.11 Add super-admin role check to all role management routes

  • 6.0 Implement Admin Settings (Microsoft Tenant, Session Policies, Email Templates)

    • 6.1 Create database migration for app_settings table
    • 6.2 Create database migration for session_policy table (name, cidr, timeout_seconds, priority)
    • 6.3 Create database migration for email_template table (type, subject, body_html)
    • 6.4 Create app/api/admin/settings/route.ts - GET/PATCH app settings
    • 6.5 Create app/api/admin/settings/session-policies/route.ts - CRUD for session policies
    • 6.6 Create app/api/admin/settings/email-templates/route.ts - GET/PATCH email templates
    • 6.7 Create components/admin/settings/microsoft-config.tsx - tenant ID input with validation
    • 6.8 Create components/admin/settings/session-policies.tsx - table with add/edit/delete for CIDR policies
    • 6.9 Implement CIDR notation validation (e.g., 192.168.1.0/24)
    • 6.10 Create components/admin/settings/email-templates.tsx - template editor with variable hints
    • 6.11 Create app/admin/settings/page.tsx - settings page with tabs (Microsoft, Sessions, Email)
    • 6.12 Seed default email templates (magic_link, invitation) on first run
    • 6.13 Update auth config to dynamically load Microsoft tenant from app_settings
    • 6.14 Update session creation to check CIDR policies and set appropriate timeout

  • 7.0 Implement Security Features (2FA, Session Management, Audit Logging)

    • 7.1 Configure two-factor plugin in lib/auth.ts
    • 7.2 Update lib/auth-client.ts with two-factor client plugin
    • 7.3 Create components/auth/two-factor-form.tsx - TOTP code input
    • 7.4 Create app/auth/2fa/page.tsx - 2FA verification page
    • 7.5 Create components/settings/two-factor-setup.tsx - QR code display and verification
    • 7.6 Create components/settings/active-sessions.tsx - current user's sessions with revoke
    • 7.7 Create app/settings/page.tsx - user settings with profile tab
    • 7.8 Create app/settings/security/page.tsx - security settings (2FA toggle, sessions)
    • 7.9 Create database migration for audit_log table (timestamp, user_id, action, resource, details, ip_address)
    • 7.10 Create lib/services/audit.ts - audit logging service with log() function
    • 7.11 Add audit logging to auth events (sign-in, sign-out, failed attempts)
    • 7.12 Add audit logging to user management actions (create, edit, delete, role change)
    • 7.13 Add audit logging to role management actions
    • 7.14 Create app/api/admin/audit-log/route.ts - GET with pagination and filters
    • 7.15 Create components/admin/audit/audit-log-table.tsx - table with filters (date range, user, action)
    • 7.16 Create app/admin/audit-log/page.tsx - audit log viewer page
    • 7.17 Implement audit log retention (delete records older than AUDIT_LOG_RETENTION_DAYS)
    • 7.18 Create scheduled job or API endpoint to purge old audit logs
    • 7.19 Implement rate limiting on auth endpoints (sign-in, magic-link)

  • 8.0 Implement Bootstrap & Initial Setup Flow

    • 8.1 Create bootstrap check function to detect if any users exist
    • 8.2 Create seed script to create default super-admin from DEFAULT_ADMIN_EMAIL and DEFAULT_ADMIN_NAME env vars
    • 8.3 Add requires_setup flag to user table for accounts needing reconfiguration
    • 8.4 Create setup detection in middleware - redirect setup accounts to /auth/setup
    • 8.5 Create app/auth/setup/page.tsx - forced setup page for default account
    • 8.6 Create components/auth/setup-form.tsx - form to link Microsoft account or set up magic link
    • 8.7 Clear requires_setup flag after successful setup completion
    • 8.8 Display warning banner for setup accounts until reconfigured
    • 8.9 Run bootstrap/seed on application startup if no users exist
    • 8.10 Add documentation for initial setup process in README