bookmarksite/.kiro/specs/user-management/design.md

User Management - Design Document

Overview

The User Management system transforms the existing client-side bookmark manager into a full-stack web application with multi-user support. The system uses a Node.js/Express backend with PostgreSQL database for data persistence, JWT-based authentication, and maintains the existing frontend while adding user authentication flows. The architecture follows RESTful API principles with proper security measures including password hashing, session management, and data isolation between users.

Architecture

High-Level Architecture

graph TB
    CLIENT[Frontend Client]
    AUTH[Authentication Layer]
    API[REST API Layer]
    BIZ[Business Logic Layer]
    DATA[Data Access Layer]
    DB[(PostgreSQL Database)]
    EMAIL[Email Service]
    
    CLIENT --> AUTH
    AUTH --> API
    API --> BIZ
    BIZ --> DATA
    DATA --> DB
    BIZ --> EMAIL
    
    subgraph "Backend Services"
        AUTH
        API
        BIZ
        DATA
    end
    
    subgraph "External Services"
        EMAIL
        DB
    end

Technology Stack

Backend:

• Node.js with Express.js framework
• PostgreSQL database with pg (node-postgres) driver
• bcrypt for password hashing
• jsonwebtoken for JWT authentication
• nodemailer for email services
• express-rate-limit for API rate limiting
• helmet for security headers

Frontend:

• Existing vanilla JavaScript application
• Fetch API for HTTP requests
• JWT token storage in httpOnly cookies
• Enhanced UI for authentication flows

Application Flow

1. User Registration: Email validation → Password hashing → Database storage → Email verification
2. Authentication: Credential validation → JWT token generation → Session establishment
3. Bookmark Operations: Token validation → User authorization → Database operations → Response
4. Session Management: Token refresh → Expiration handling → Logout cleanup

Components and Interfaces

1. User Authentication Service

Purpose: Handle user registration, login, password management, and session control

Key Methods:

• registerUser(email, password) - Create new user account
• authenticateUser(email, password) - Validate credentials and create session
• generateJWT(userId) - Create authentication token
• validateToken(token) - Verify token validity
• resetPassword(email) - Initiate password reset flow
• changePassword(userId, currentPassword, newPassword) - Update user password

Security Features:

• bcrypt password hashing with salt rounds (12)
• JWT tokens with 24-hour expiration
• Password strength validation
• Rate limiting on authentication endpoints
• Secure cookie configuration

2. User Data Model

interface User {
    id: string;              // UUID primary key
    email: string;           // Unique email address
    password_hash: string;   // bcrypt hashed password
    is_verified: boolean;    // Email verification status
    created_at: Date;        // Account creation timestamp
    updated_at: Date;        // Last profile update
    last_login: Date;        // Last successful login
    verification_token?: string;  // Email verification token
    reset_token?: string;    // Password reset token
    reset_expires?: Date;    // Reset token expiration
}

3. Enhanced Bookmark Data Model

interface Bookmark {
    id: string;              // UUID primary key
    user_id: string;         // Foreign key to users table
    title: string;           // Bookmark title
    url: string;             // Target URL
    folder: string;          // Folder path
    add_date: Date;          // Creation timestamp
    last_modified: Date;     // Last update timestamp
    icon: string;            // Favicon URL or data URI
    status: 'unknown' | 'valid' | 'invalid' | 'testing' | 'duplicate';
    created_at: Date;        // Database creation timestamp
    updated_at: Date;        // Database update timestamp
}

4. Database Schema

Users Table:

CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    email VARCHAR(255) UNIQUE NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    is_verified BOOLEAN DEFAULT FALSE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    last_login TIMESTAMP,
    verification_token VARCHAR(255),
    reset_token VARCHAR(255),
    reset_expires TIMESTAMP
);

CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_users_verification_token ON users(verification_token);
CREATE INDEX idx_users_reset_token ON users(reset_token);

Bookmarks Table:

CREATE TABLE bookmarks (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    title VARCHAR(500) NOT NULL,
    url TEXT NOT NULL,
    folder VARCHAR(255) DEFAULT '',
    add_date TIMESTAMP NOT NULL,
    last_modified TIMESTAMP,
    icon TEXT,
    status VARCHAR(20) DEFAULT 'unknown',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_bookmarks_user_id ON bookmarks(user_id);
CREATE INDEX idx_bookmarks_folder ON bookmarks(user_id, folder);
CREATE INDEX idx_bookmarks_status ON bookmarks(user_id, status);
CREATE INDEX idx_bookmarks_url ON bookmarks(user_id, url);

5. REST API Endpoints

Authentication Endpoints:

• POST /api/auth/register - User registration
• POST /api/auth/login - User login
• POST /api/auth/logout - User logout
• POST /api/auth/refresh - Token refresh
• POST /api/auth/forgot-password - Password reset request
• POST /api/auth/reset-password - Password reset confirmation
• GET /api/auth/verify/:token - Email verification

User Management Endpoints:

• GET /api/user/profile - Get user profile
• PUT /api/user/profile - Update user profile
• POST /api/user/change-password - Change password
• DELETE /api/user/account - Delete user account

Bookmark Endpoints:

• GET /api/bookmarks - Get user's bookmarks (with pagination)
• POST /api/bookmarks - Create new bookmark
• PUT /api/bookmarks/:id - Update bookmark
• DELETE /api/bookmarks/:id - Delete bookmark
• POST /api/bookmarks/import - Import bookmarks
• GET /api/bookmarks/export - Export bookmarks
• POST /api/bookmarks/test-links - Test bookmark links
• POST /api/bookmarks/find-duplicates - Find duplicate bookmarks

6. Middleware Components

Authentication Middleware:

const authenticateToken = (req, res, next) => {
    const token = req.cookies.authToken;
    if (!token) return res.status(401).json({ error: 'Access denied' });
    
    try {
        const verified = jwt.verify(token, process.env.JWT_SECRET);
        req.user = verified;
        next();
    } catch (error) {
        res.status(400).json({ error: 'Invalid token' });
    }
};

Rate Limiting Middleware:

const authLimiter = rateLimit({
    windowMs: 15 * 60 * 1000, // 15 minutes
    max: 5, // 5 attempts per window
    message: 'Too many authentication attempts'
});

Data Models

Session Management

JWT Payload Structure:

interface JWTPayload {
    userId: string;
    email: string;
    iat: number;        // Issued at
    exp: number;        // Expiration
}

Cookie Configuration:

const cookieOptions = {
    httpOnly: true,
    secure: process.env.NODE_ENV === 'production',
    sameSite: 'strict',
    maxAge: 24 * 60 * 60 * 1000 // 24 hours
};

Email Templates

Verification Email:

• Subject: "Verify your Bookmark Manager account"
• Content: Welcome message with verification link
• Link format: ${baseUrl}/verify/${verificationToken}

Password Reset Email:

• Subject: "Reset your Bookmark Manager password"
• Content: Reset instructions with secure link
• Link format: ${baseUrl}/reset-password/${resetToken}
• Expiration: 1 hour

Error Handling

API Error Response Format

interface APIError {
    error: string;           // Error message
    code?: string;          // Error code for client handling
    details?: any;          // Additional error details
    timestamp: string;      // ISO timestamp
}

Error Categories

Authentication Errors (401):

• Invalid credentials
• Token expired
• Token invalid
• Account not verified

Authorization Errors (403):

• Insufficient permissions
• Account suspended
• Resource access denied

Validation Errors (400):

• Invalid email format
• Weak password
• Missing required fields
• Invalid data format

Server Errors (500):

• Database connection failed
• Email service unavailable
• Internal server error

Error Logging Strategy

const logger = {
    error: (message, meta) => {
        console.error({
            timestamp: new Date().toISOString(),
            level: 'error',
            message,
            ...meta
        });
    },
    warn: (message, meta) => {
        console.warn({
            timestamp: new Date().toISOString(),
            level: 'warn',
            message,
            ...meta
        });
    }
};

Testing Strategy

Unit Testing

Authentication Service Tests:

• Password hashing and verification
• JWT token generation and validation
• Email validation logic
• Password strength validation

Database Layer Tests:

• User CRUD operations
• Bookmark CRUD operations
• Data isolation between users
• Query performance with large datasets

API Endpoint Tests:

• Request validation
• Authentication middleware
• Error response formats
• Rate limiting behavior

Integration Testing

Authentication Flow Tests:

1. Registration → Email verification → Login
2. Login → Token refresh → Logout
3. Password reset → New password → Login
4. Failed login attempts → Account lockout

Bookmark Management Tests:

1. Login → Import bookmarks → Verify isolation
2. CRUD operations → Data persistence
3. Link testing → Status updates
4. Export functionality → Data integrity

Security Testing

Authentication Security:

• SQL injection prevention
• XSS protection
• CSRF protection
• Rate limiting effectiveness
• Password brute force protection

Data Security:

• User data isolation
• Sensitive data exposure
• Token security
• Session management

Performance Testing

Load Testing Scenarios:

• Concurrent user registrations
• Simultaneous bookmark operations
• Large bookmark imports
• Database query performance

Scalability Testing:

• Database connection pooling
• Memory usage under load
• Response times with large datasets

User Interface Design

Authentication Pages

Login Page Layout:

┌─────────────────────────────────────┐
│ Bookmark Manager                    │
├─────────────────────────────────────┤
│ ┌─────────────────────────────────┐ │
│ │ Email: [________________]       │ │
│ │ Password: [________________]    │ │
│ │ [ ] Remember me                 │ │
│ │ [Login] [Forgot Password?]      │ │
│ │ Don't have an account? Register │ │
│ └─────────────────────────────────┘ │
└─────────────────────────────────────┘

Registration Page Layout:

┌─────────────────────────────────────┐
│ Create Account                      │
├─────────────────────────────────────┤
│ ┌─────────────────────────────────┐ │
│ │ Email: [________________]       │ │
│ │ Password: [________________]    │ │
│ │ Confirm: [________________]     │ │
│ │ Password Requirements:          │ │
│ │ ✓ 8+ characters                 │ │
│ │ ✓ Uppercase letter              │ │
│ │ ✓ Number                        │ │
│ │ [Create Account]                │ │
│ │ Already have an account? Login  │ │
│ └─────────────────────────────────┘ │
└─────────────────────────────────────┘

Enhanced Main Application

Header with User Menu:

┌─────────────────────────────────────┐
│ Bookmark Manager    [user@email.com]│
│                     [Profile ▼]     │
│                     - Account       │
│                     - Settings      │
│                     - Logout        │
├─────────────────────────────────────┤
│ [Import] [Export] [Add Bookmark]    │
└─────────────────────────────────────┘

Responsive Design Considerations

Mobile Authentication:

• Full-screen login/register forms
• Touch-friendly input fields
• Clear error messaging
• Simplified navigation

Tablet/Desktop:

• Centered authentication forms
• Side-by-side login/register options
• Enhanced user menu
• Consistent with existing bookmark UI

Security Considerations

Password Security

Hashing Strategy:

• bcrypt with 12 salt rounds
• Automatic salt generation
• Timing attack prevention
• Password history (optional)

Password Policy:

• Minimum 8 characters
• At least one uppercase letter
• At least one lowercase letter
• At least one number
• At least one special character
• Common password blacklist

Token Security

JWT Configuration:

• Strong secret key (256-bit)
• Short expiration times (24 hours)
• Secure cookie storage
• Token refresh mechanism
• Blacklist for revoked tokens

API Security

Request Security:

• HTTPS enforcement
• CORS configuration
• Rate limiting per endpoint
• Input validation and sanitization
• SQL injection prevention

Response Security:

• Security headers (helmet.js)
• Error message sanitization
• No sensitive data exposure
• Proper HTTP status codes

Database Security

Connection Security:

• Connection string encryption
• Connection pooling limits
• Query timeout configuration
• Prepared statements only

Data Protection:

• User data isolation
• Soft delete for audit trails
• Regular backup procedures
• Access logging

Performance Optimizations

Database Optimizations

Indexing Strategy:

• Primary keys on all tables
• Foreign key indexes
• Composite indexes for common queries
• Partial indexes for filtered queries

Query Optimization:

• Pagination for large result sets
• Efficient JOIN operations
• Query result caching
• Connection pooling

API Performance

Response Optimization:

• Gzip compression
• JSON response minification
• Conditional requests (ETags)
• Appropriate cache headers

Request Handling:

• Async/await patterns
• Error handling middleware
• Request timeout configuration
• Memory leak prevention

Frontend Integration

Token Management:

• Automatic token refresh
• Graceful authentication failures
• Offline capability considerations
• Local storage cleanup

API Integration:

• Request retry logic
• Loading state management
• Error boundary implementation
• Optimistic updates where appropriate

Deployment Considerations

Environment Configuration

Development Environment:

• Local PostgreSQL instance
• Development JWT secrets
• Debug logging enabled
• CORS allowing localhost

Production Environment:

• Managed database service
• Environment variable secrets
• Production logging configuration
• Strict CORS policy
• HTTPS enforcement

Monitoring and Logging

Application Monitoring:

• Request/response logging
• Error rate monitoring
• Performance metrics
• User activity tracking

Security Monitoring:

• Failed authentication attempts
• Suspicious activity detection
• Rate limit violations
• Token usage patterns

This design document provides a comprehensive blueprint for implementing secure, scalable user management functionality that integrates seamlessly with the existing bookmark manager while maintaining high security standards and excellent user experience.