wulf-pulse/tasks/prd-auth-user-management.md

PRD: Authentication & User Management Module

1. Introduction/Overview

Pulse currently has no authentication system, leaving all routes and data publicly accessible. This PRD defines the implementation of a comprehensive authentication and authorization system using Better Auth with a User Management Module for super-admins.

Problem Statement

• No authentication protects the application
• Sensitive admin sections and data are exposed
• No role-based access control (RBAC) exists
• No user management capabilities

Solution

Implement Better Auth with:

• Magic link and Microsoft 365 OAuth authentication
• Role-based access control with custom role creation
• User management module for super-admins
• Session management with security controls
• Two-factor authentication (2FA)
• Audit logging

---

2. Goals

1. Secure all application routes - No unauthenticated access to any part of Pulse
2. Implement RBAC - Protect admin sections and sensitive data based on user roles
3. Enable user management - Super-admins can create, edit, deactivate users and manage roles
4. Support enterprise auth - Magic link and Microsoft 365 SSO
5. Provide security controls - Session timeout, password policies, 2FA, audit logging
6. Match existing UI - Use existing shadcn/ui components for consistency

---

3. User Stories

Authentication

• As a user, I want to sign in with a magic link so I don't need to remember a password
• As a user, I want to sign in with my Microsoft 365 account for seamless enterprise access
• As a user, I want to enable 2FA to secure my account
• As a user, I want to see and manage my active sessions

Authorization

• As an admin, I want certain sections protected so only authorized users can access them
• As a super-admin, I want to define custom roles with specific permissions

User Management

• As a super-admin, I want to invite new users via email
• As a super-admin, I want to view all users and their roles
• As a super-admin, I want to edit user profiles and change their roles
• As a super-admin, I want to deactivate/reactivate users
• As a super-admin, I want to reset a user's password/sessions
• As a super-admin, I want to create and manage custom roles
• As a super-admin, I want to view audit logs of user actions

---

4. Functional Requirements

4.1 Authentication System

ID	Requirement
AUTH-01	System must support magic link authentication via email
AUTH-02	System must support Microsoft 365 OAuth authentication
AUTH-03	System must support two-factor authentication (TOTP)
AUTH-04	System must redirect unauthenticated users to sign-in page
AUTH-05	System must maintain secure sessions with configurable timeout
AUTH-06	System must allow users to view and revoke their active sessions
AUTH-07	Magic links must expire after 5 minutes
AUTH-08	System must support account linking (magic link + Microsoft)

4.2 Authorization & RBAC

ID	Requirement
RBAC-01	System must implement role-based access control
RBAC-02	System must have default roles: super-admin, admin, user
RBAC-03	Super-admins must be able to create custom roles
RBAC-04	Roles must define permissions for resources (e.g., tickets:read, admin:access)
RBAC-05	/app/admin/* routes must require admin or super-admin role
RBAC-06	User management must require super-admin role
RBAC-07	API routes must validate permissions before returning data

4.3 User Management Module

ID	Requirement
USER-01	Super-admins must be able to view a list of all users
USER-02	Super-admins must be able to invite new users via email
USER-03	Super-admins must be able to edit user profiles (name, email)
USER-04	Super-admins must be able to assign/change user roles
USER-05	Super-admins must be able to deactivate users (soft delete)
USER-06	Super-admins must be able to reactivate deactivated users
USER-07	Super-admins must be able to delete users permanently
USER-08	Super-admins must be able to force password reset / revoke sessions
USER-09	Super-admins must be able to view user session history

4.4 Role Management

ID	Requirement
ROLE-01	Super-admins must be able to view all roles
ROLE-02	Super-admins must be able to create new roles with custom permissions
ROLE-03	Super-admins must be able to edit existing role permissions
ROLE-04	Super-admins must be able to delete custom roles (not default roles)
ROLE-05	System must prevent deletion of roles assigned to users

4.5 Security & Audit

ID	Requirement
SEC-01	Sessions must expire after 1 hour by default (configurable)
SEC-02	Session timeout must be configurable per source IP/subnet (trusted networks can have longer sessions)
SEC-03	Sessions must refresh on activity (sliding expiration)
SEC-04	System must log authentication events (sign-in, sign-out, failed attempts)
SEC-05	System must log user management actions (create, edit, delete, role changes)
SEC-06	Audit logs must be viewable by super-admins
SEC-07	Audit logs must be retained for 120 days by default
SEC-08	System must automatically purge audit logs older than retention period
SEC-09	System must rate-limit authentication attempts

4.6 Microsoft 365 Configuration

ID	Requirement
MS-01	Super-admins must be able to configure Microsoft tenant ID in admin settings
MS-02	System must validate tenant ID format before saving
MS-03	System must support both specific tenant and 'common' (any Microsoft account) modes

4.8 Session Policies (Trusted Networks)

ID	Requirement
NET-01	Super-admins must be able to define trusted networks using CIDR notation
NET-02	Each network policy must have: name, CIDR range, session timeout (seconds)
NET-03	System must validate CIDR notation format before saving
NET-04	System must match client IP against policies in priority order
NET-05	Default policy (1 hour) applies when no CIDR matches
NET-06	Example: 10.0.0.0/8 = 8 hours, 192.168.1.0/24 = 24 hours

4.9 Email Templates

ID	Requirement
EMAIL-01	Super-admins must be able to customize magic link email template
EMAIL-02	Super-admins must be able to customize user invitation email template
EMAIL-03	Templates must support variables: {{name}}, {{link}}, {{expires}}, {{app_name}}
EMAIL-04	System must provide default templates that can be reset
EMAIL-05	Templates must support HTML formatting

4.7 Initial Setup & Bootstrap

ID	Requirement
BOOT-01	System must create a default super-admin account on first run
BOOT-02	Default super-admin credentials must be set via environment variables
BOOT-03	System must force immediate password/auth method change on first login for default account
BOOT-04	Default account must be clearly marked as "setup account" requiring reconfiguration

---

5. Non-Goals (Out of Scope)

• Password-based authentication - Only magic link and Microsoft 365 OAuth
• Self-registration - Users must be invited by super-admins
• Multi-tenancy / Organizations - Single tenant for now
• API key authentication - Not in initial scope
• SAML SSO - Only OAuth (Microsoft 365)
• Email verification for existing users - Users are invited, not self-registered

---

6. Design Considerations

UI Components

Use existing shadcn/ui components from /components/ui/:

• button, input, label, form for auth forms
• card for sign-in/settings cards
• table for user/role lists
• dialog for confirmations
• dropdown-menu for user actions
• badge for role/status display
• tabs for settings sections
• alert-dialog for destructive actions

Pages to Create

Route	Description
/auth/sign-in	Sign-in page (magic link + Microsoft)
/auth/verify	Magic link verification
/auth/2fa	Two-factor verification
/app/admin/users	User management list
/app/admin/users/[id]	User detail/edit page
/app/admin/users/invite	Invite user form
/app/admin/roles	Role management
/app/admin/audit-log	Audit log viewer
/app/admin/settings	App settings (Microsoft tenant, session policies, email templates)
/settings	User settings (profile, sessions, 2FA)

Component Structure

/components/auth/
  ├── sign-in-form.tsx       # Magic link + Microsoft buttons
  ├── magic-link-form.tsx    # Email input for magic link
  ├── two-factor-form.tsx    # TOTP input
  └── session-list.tsx       # Active sessions

/components/admin/users/
  ├── user-table.tsx         # User list with actions
  ├── user-form.tsx          # Create/edit user
  ├── invite-user-form.tsx   # Invite via email
  ├── role-badge.tsx         # Role display
  └── user-actions.tsx       # Dropdown actions

/components/admin/roles/
  ├── role-table.tsx         # Role list
  ├── role-form.tsx          # Create/edit role
  └── permission-picker.tsx  # Permission selection

---

7. Technical Considerations

Dependencies

{
  "better-auth": "^1.x",
  "@daveyplate/better-auth-ui": "^1.x"
}

Database Schema (PostgreSQL)

Better Auth will create these tables:

• user - User accounts
• session - Active sessions
• account - OAuth accounts (Microsoft)
• verification - Magic link tokens

Additional tables:

• role - Custom roles
• permission - Role permissions
• audit_log - Security audit trail
• session_policy - IP/subnet-based session timeout rules (CIDR notation)
• app_settings - Application settings (Microsoft tenant, etc.)
• email_template - Customizable email templates

File Structure

/lib/
  ├── auth.ts                # Better Auth server config
  ├── auth-client.ts         # Better Auth client
  └── permissions.ts         # RBAC definitions

/app/api/auth/[...all]/
  └── route.ts               # Better Auth API handler

/middleware.ts               # Route protection

Environment Variables

# Better Auth
BETTER_AUTH_SECRET=          # Random secret for signing
BETTER_AUTH_URL=             # Base URL (e.g., http://localhost:3000)

# Microsoft OAuth (Tenant ID configurable in admin UI)
MICROSOFT_CLIENT_ID=
MICROSOFT_CLIENT_SECRET=

# SMTP Configuration (for magic links)
SMTP_HOST=                   # SMTP server hostname
SMTP_PORT=587                # SMTP port (587 for TLS, 465 for SSL)
SMTP_USER=                   # SMTP username
SMTP_PASS=                   # SMTP password
SMTP_FROM=                   # From email address
SMTP_SECURE=false            # Use SSL (true for port 465)

# Default Super-Admin (for initial setup)
DEFAULT_ADMIN_EMAIL=         # Email for default super-admin account
DEFAULT_ADMIN_NAME=          # Display name for default super-admin

# Session Configuration
SESSION_TIMEOUT_SECONDS=3600 # Default 1 hour

# Audit Log Retention
AUDIT_LOG_RETENTION_DAYS=120 # Default 120 days

Integration Points

• Integrate with existing PostgreSQL database (pg package)
• Use existing Toaster from sonner for notifications
• Protect existing /app/admin/* routes
• Add user context to existing components via useSession()

---

8. Success Metrics

Metric	Target
All routes protected	100% of routes require authentication
Admin routes secured	/admin/* only accessible to admin/super-admin
User management functional	Super-admins can perform all CRUD operations
Auth methods working	Magic link and Microsoft 365 both functional
2FA adoption	Available and working for all users
Audit logging	All auth and user management events logged

---

9. Resolved Questions

Question	Resolution
Email provider	Pure SMTP - configurable via environment variables
Microsoft tenant	Configurable in admin UI - supports specific tenant or 'common'
Initial super-admin	Default account via env vars, forced reconfiguration on first login
Session duration	1 hour default, configurable per source IP/subnet for trusted networks
Audit log retention	120 days default, automatic purge of older records

10. Resolved Questions (Continued)

Question	Resolution
Trusted network configuration	CIDR notation (e.g., 192.168.1.0/24, 10.0.0.0/8)
Email templates	Customizable by admins in settings

---

11. Implementation Phases

Phase 1: Core Authentication

• Install and configure Better Auth
• Set up magic link authentication
• Set up Microsoft 365 OAuth
• Create sign-in page
• Implement middleware for route protection

Phase 2: RBAC & Permissions

• Define permission structure
• Implement admin plugin with roles
• Protect admin routes
• Add role checking to API routes

Phase 3: User Management

• Create user list page
• Implement invite user flow
• Create user edit page
• Add deactivate/delete functionality

Phase 4: Role Management

• Create role list page
• Implement role creation/editing
• Add permission picker UI

Phase 5: Security Features

• Implement 2FA
• Add session management UI
• Create audit log system
• Add audit log viewer

---

Appendix: Permission Structure

// Suggested permission structure
const permissions = {
  // Ticket permissions
  tickets: ["read", "create", "update", "delete"],
  
  // Configuration items
  configItems: ["read", "create", "update", "delete"],
  
  // Admin sections
  admin: ["access", "sync", "dataBrowser", "analytics"],
  
  // User management (super-admin only)
  users: ["read", "create", "update", "delete", "invite"],
  
  // Role management (super-admin only)
  roles: ["read", "create", "update", "delete"],
  
  // Audit logs
  auditLog: ["read"],
} as const;

// Default roles
const defaultRoles = {
  "super-admin": {
    // All permissions
  },
  "admin": {
    tickets: ["read", "create", "update", "delete"],
    configItems: ["read", "create", "update", "delete"],
    admin: ["access", "sync", "dataBrowser", "analytics"],
  },
  "user": {
    tickets: ["read", "create", "update"],
    configItems: ["read"],
  },
};