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

209 lines
13 KiB
Markdown
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
- [x] 1.0 Setup Better Auth Core Infrastructure
- [x] 1.1 Install Better Auth dependencies (`better-auth`, `@better-auth/cli`)
- [x] 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)
- [x] 1.3 Create database migration for Better Auth core tables (user, session, account, verification)
- [x] 1.4 Create `lib/auth.ts` with Better Auth server configuration
- [x] 1.5 Create `lib/auth-client.ts` with Better Auth client for React
- [x] 1.6 Create `app/api/auth/[...all]/route.ts` API route handler
- [x] 1.7 Create `middleware.ts` for route protection (redirect unauthenticated users to /auth/sign-in)
- [x] 1.8 Create `lib/services/email.ts` SMTP email service using environment variables
- [x] 1.9 Update `app/layout.tsx` to wrap app with auth session provider
- [x] 2.0 Implement Authentication Methods (Magic Link & Microsoft 365)
- [x] 2.1 Configure magic link plugin in `lib/auth.ts` with sendMagicLink callback using SMTP service
- [x] 2.2 Configure Microsoft OAuth provider in `lib/auth.ts` with client ID/secret from env
- [x] 2.3 Create `app/auth/layout.tsx` - minimal layout without main navigation
- [x] 2.4 Create `app/auth/sign-in/page.tsx` - sign-in page container
- [x] 2.5 Create `components/auth/magic-link-form.tsx` - email input with submit
- [x] 2.6 Create `components/auth/microsoft-button.tsx` - Microsoft 365 OAuth button
- [x] 2.7 Create `components/auth/sign-in-form.tsx` - combined form with both methods
- [x] 2.8 Create `app/auth/verify/page.tsx` - magic link verification handler
- [x] 2.9 Implement "check your email" success state in magic link form
- [x] 2.10 Add error handling for failed auth attempts with toast notifications
- [x] 3.0 Implement RBAC & Permission System
- [x] 3.1 Create database migration for role and permission tables
- [x] 3.2 Create `lib/permissions.ts` with permission definitions (tickets, configItems, admin, users, roles, auditLog)
- [x] 3.3 Define default roles (super-admin, admin, user) with their permissions
- [x] 3.4 Configure Better Auth admin plugin with access control in `lib/auth.ts`
- [x] 3.5 Update `lib/auth-client.ts` with admin client plugin
- [x] 3.6 Create helper function `hasPermission(user, resource, action)` for checking permissions
- [x] 3.7 Update `middleware.ts` to check roles for `/admin/*` routes (require admin or super-admin)
- [x] 3.8 Create API middleware helper for permission checking in route handlers
- [x] 3.9 Seed default roles into database on first run
- [x] 4.0 Build User Management Module
- [x] 4.1 Create `app/api/admin/users/route.ts` - GET (list users), POST (create user)
- [x] 4.2 Create `app/api/admin/users/[id]/route.ts` - GET, PATCH, DELETE single user
- [x] 4.3 Create `app/api/admin/users/invite/route.ts` - POST to send invitation email
- [x] 4.4 Create `components/admin/users/role-badge.tsx` - badge component for role display
- [x] 4.5 Create `components/admin/users/user-table.tsx` - table with columns: name, email, role, status, actions
- [x] 4.6 Create `components/admin/users/user-actions.tsx` - dropdown with edit, deactivate, delete, revoke sessions
- [x] 4.7 Create `app/admin/users/page.tsx` - user list page with search/filter
- [x] 4.8 Create `components/admin/users/user-form.tsx` - form for editing user (name, email, role)
- [x] 4.9 Create `app/admin/users/[id]/page.tsx` - user detail page with edit form and session history
- [x] 4.10 Create `components/admin/users/invite-user-form.tsx` - email input with role selection
- [x] 4.11 Create `app/admin/users/invite/page.tsx` - invite user page
- [x] 4.12 Create `components/admin/users/user-sessions.tsx` - table of user's sessions with revoke
- [x] 4.13 Implement soft delete (deactivate) and reactivate functionality
- [x] 4.14 Implement permanent delete with confirmation dialog
- [x] 4.15 Add super-admin role check to all user management routes
- [x] 5.0 Build Role Management Module
- [x] 5.1 Create `app/api/admin/roles/route.ts` - GET (list roles), POST (create role)
- [x] 5.2 Create `app/api/admin/roles/[id]/route.ts` - GET, PATCH, DELETE single role
- [x] 5.3 Create `components/admin/roles/permission-picker.tsx` - checkbox grid for selecting permissions
- [x] 5.4 Create `components/admin/roles/role-table.tsx` - table with columns: name, permissions count, users count, actions
- [x] 5.5 Create `app/admin/roles/page.tsx` - role list page
- [x] 5.6 Create `components/admin/roles/role-form.tsx` - form with name input and permission picker
- [x] 5.7 Create `app/admin/roles/new/page.tsx` - create new role page
- [x] 5.8 Create `app/admin/roles/[id]/page.tsx` - edit role page
- [x] 5.9 Prevent deletion of default roles (super-admin, admin, user)
- [x] 5.10 Prevent deletion of roles that are assigned to users (show error)
- [x] 5.11 Add super-admin role check to all role management routes
- [x] 6.0 Implement Admin Settings (Microsoft Tenant, Session Policies, Email Templates)
- [x] 6.1 Create database migration for app_settings table
- [x] 6.2 Create database migration for session_policy table (name, cidr, timeout_seconds, priority)
- [x] 6.3 Create database migration for email_template table (type, subject, body_html)
- [x] 6.4 Create `app/api/admin/settings/route.ts` - GET/PATCH app settings
- [x] 6.5 Create `app/api/admin/settings/session-policies/route.ts` - CRUD for session policies
- [x] 6.6 Create `app/api/admin/settings/email-templates/route.ts` - GET/PATCH email templates
- [x] 6.7 Create `components/admin/settings/microsoft-config.tsx` - tenant ID input with validation
- [x] 6.8 Create `components/admin/settings/session-policies.tsx` - table with add/edit/delete for CIDR policies
- [x] 6.9 Implement CIDR notation validation (e.g., `192.168.1.0/24`)
- [x] 6.10 Create `components/admin/settings/email-templates.tsx` - template editor with variable hints
- [x] 6.11 Create `app/admin/settings/page.tsx` - settings page with tabs (Microsoft, Sessions, Email)
- [x] 6.12 Seed default email templates (magic_link, invitation) on first run
- [x] 6.13 Update auth config to dynamically load Microsoft tenant from app_settings
- [x] 6.14 Update session creation to check CIDR policies and set appropriate timeout
- [x] 7.0 Implement Security Features (2FA, Session Management, Audit Logging)
- [x] 7.1 Configure two-factor plugin in `lib/auth.ts`
- [x] 7.2 Update `lib/auth-client.ts` with two-factor client plugin
- [x] 7.3 Create `components/auth/two-factor-form.tsx` - TOTP code input
- [x] 7.4 Create `app/auth/2fa/page.tsx` - 2FA verification page
- [x] 7.5 Create `components/settings/two-factor-setup.tsx` - QR code display and verification
- [x] 7.6 Create `components/settings/active-sessions.tsx` - current user's sessions with revoke
- [x] 7.7 Create `app/settings/page.tsx` - user settings with profile tab
- [x] 7.8 Create `app/settings/security/page.tsx` - security settings (2FA toggle, sessions)
- [x] 7.9 Create database migration for audit_log table (timestamp, user_id, action, resource, details, ip_address)
- [x] 7.10 Create `lib/services/audit.ts` - audit logging service with log() function
- [x] 7.11 Add audit logging to auth events (sign-in, sign-out, failed attempts)
- [x] 7.12 Add audit logging to user management actions (create, edit, delete, role change)
- [x] 7.13 Add audit logging to role management actions
- [x] 7.14 Create `app/api/admin/audit-log/route.ts` - GET with pagination and filters
- [x] 7.15 Create `components/admin/audit/audit-log-table.tsx` - table with filters (date range, user, action)
- [x] 7.16 Create `app/admin/audit-log/page.tsx` - audit log viewer page
- [x] 7.17 Implement audit log retention (delete records older than AUDIT_LOG_RETENTION_DAYS)
- [x] 7.18 Create scheduled job or API endpoint to purge old audit logs
- [x] 7.19 Implement rate limiting on auth endpoints (sign-in, magic-link)
- [x] 8.0 Implement Bootstrap & Initial Setup Flow
- [x] 8.1 Create bootstrap check function to detect if any users exist
- [x] 8.2 Create seed script to create default super-admin from DEFAULT_ADMIN_EMAIL and DEFAULT_ADMIN_NAME env vars
- [x] 8.3 Add `requires_setup` flag to user table for accounts needing reconfiguration
- [x] 8.4 Create setup detection in middleware - redirect setup accounts to `/auth/setup`
- [x] 8.5 Create `app/auth/setup/page.tsx` - forced setup page for default account
- [x] 8.6 Create `components/auth/setup-form.tsx` - form to link Microsoft account or set up magic link
- [x] 8.7 Clear `requires_setup` flag after successful setup completion
- [x] 8.8 Display warning banner for setup accounts until reconfigured
- [x] 8.9 Run bootstrap/seed on application startup if no users exist
- [x] 8.10 Add documentation for initial setup process in README
Reference in a new issue View git blame Copy permalink