Add comprehensive database setup and user management system

- Implement PostgreSQL database schema with users and bookmarks tables - Add database connection pooling with retry logic and error handling - Create migration system with automatic schema initialization - Add database CLI tools for management (init, status, validate, etc.) - Include comprehensive error handling and diagnostics - Add development seed data and testing utilities - Implement health monitoring and connection pool statistics - Create detailed documentation and troubleshooting guide Database features: - Users table with authentication fields and email verification - Bookmarks table with user association and metadata - Proper indexes for performance optimization - Automatic timestamp triggers - Transaction support with rollback handling - Connection pooling (20 max connections, 30s idle timeout) - Graceful shutdown handling CLI commands available: - npm run db:init - Initialize database - npm run db:status - Check database status - npm run db:validate - Validate schema - npm run db:test - Run database tests - npm run db:diagnostics - Full diagnostics
2025-07-19 23:21:50 +02:00
commit 0abee5b794
66 changed files with 45023 additions and 0 deletions
--- a/.kiro/specs/user-management/design.md
+++ b/.kiro/specs/user-management/design.md
@ -0,0 +1,578 @@
+# 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
+
+```mermaid
+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
+
+```typescript
+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
+
+```typescript
+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**:
+```sql
+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**:
+```sql
+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**:
+```javascript
+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**:
+```javascript
+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**:
+```typescript
+interface JWTPayload {
+    userId: string;
+    email: string;
+    iat: number;        // Issued at
+    exp: number;        // Expiration
+}
+```
+
+**Cookie Configuration**:
+```javascript
+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
+
+```typescript
+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
+
+```javascript
+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.
--- a/.kiro/specs/user-management/requirements.md
+++ b/.kiro/specs/user-management/requirements.md
--- a/.kiro/specs/user-management/tasks.md
+++ b/.kiro/specs/user-management/tasks.md
@ -0,0 +1,93 @@
+# User Management - Implementation Plan
+
+- [x] 1. Set up backend project structure and dependencies
+  - Create Node.js project with Express.js framework
+  - Install required dependencies: express, pg, bcrypt, jsonwebtoken, nodemailer, helmet, express-rate-limit
+  - Configure project structure with controllers, models, middleware, and routes directories
+  - Set up environment configuration with dotenv
+  - _Requirements: 7.1, 7.2_
+
+- [x] 2. Create database schema and connection setup
+  - Write SQL migration scripts for users and bookmarks tables with proper indexes
+  - Implement database connection module with PostgreSQL connection pooling
+  - Create database initialization script with table creation and seed data
+  - Add database connection error handling and retry logic
+  - _Requirements: 7.1, 7.2, 7.5_
+
+- [ ] 3. Implement user authentication service
+  - Create User model with bcrypt password hashing functionality
+  - Implement user registration with email validation and password strength checking
+  - Build login authentication with credential validation and JWT token generation
+  - Add password reset functionality with secure token generation and email sending
+  - _Requirements: 1.2, 1.3, 2.2, 2.3, 3.1, 3.2, 3.3_
+
+- [ ] 4. Build authentication middleware and security
+  - Create JWT token validation middleware for protected routes
+  - Implement rate limiting middleware for authentication endpoints
+  - Add security headers middleware using helmet.js
+  - Create user authorization middleware for bookmark operations
+  - _Requirements: 8.1, 8.2, 8.3, 8.6_
+
+- [ ] 5. Create user management API endpoints
+  - Implement POST /api/auth/register endpoint with validation and email verification
+  - Build POST /api/auth/login endpoint with credential validation and session creation
+  - Create POST /api/auth/logout endpoint with session cleanup
+  - Add GET /api/user/profile and PUT /api/user/profile endpoints for profile management
+  - Implement POST /api/user/change-password endpoint with current password verification
+  - _Requirements: 1.1, 1.5, 2.1, 2.3, 4.1, 4.2, 4.5_
+
+- [ ] 6. Implement bookmark data isolation and API endpoints
+  - Create Bookmark model with user association and CRUD operations
+  - Build GET /api/bookmarks endpoint with user filtering and pagination
+  - Implement POST /api/bookmarks endpoint with user association
+  - Create PUT /api/bookmarks/:id and DELETE /api/bookmarks/:id endpoints with ownership validation
+  - Add bookmark import/export endpoints with user data isolation
+  - _Requirements: 5.1, 5.2, 5.3, 5.4, 5.6_
+
+- [ ] 7. Build email service integration
+  - Create email service module with nodemailer configuration
+  - Implement email verification functionality with secure token generation
+  - Build password reset email functionality with time-limited tokens
+  - Create email templates for verification and password reset
+  - Add email sending error handling and retry logic
+  - _Requirements: 1.5, 1.7, 3.1, 3.7_
+
+- [ ] 8. Create frontend authentication pages
+  - Build login page with email/password form and validation
+  - Create registration page with email, password, and confirmation fields
+  - Implement password reset request page with email input
+  - Add password reset confirmation page with new password form
+  - Create email verification success/error pages
+  - _Requirements: 1.1, 2.1, 3.2, 4.1_
+
+- [ ] 9. Integrate authentication with existing frontend
+  - Modify existing bookmark manager to check authentication status on load
+  - Add user menu to header with profile and logout options
+  - Implement automatic token refresh and session management
+  - Update all bookmark API calls to include authentication headers
+  - Add authentication error handling and redirect to login
+  - _Requirements: 2.3, 2.6, 6.1, 6.3, 6.7_
+
+- [ ] 10. Implement data migration functionality
+  - Create migration endpoint to import localStorage bookmarks to user account
+  - Build frontend migration UI with merge/replace options
+  - Add validation for imported bookmark data format
+  - Implement conflict resolution for duplicate bookmarks during migration
+  - Create post-migration cleanup of localStorage data
+  - _Requirements: 9.1, 9.2, 9.3, 9.5, 9.6_
+
+- [ ] 11. Add comprehensive error handling and logging
+  - Implement centralized error handling middleware for API endpoints
+  - Create logging service with different log levels and rotation
+  - Add authentication failure logging for security monitoring
+  - Implement database error handling with appropriate user messages
+  - Create client-side error boundaries for authentication failures
+  - _Requirements: 10.1, 10.2, 10.3, 10.4_
+
+- [ ] 12. Create comprehensive test suite
+  - Write unit tests for authentication service functions (password hashing, token generation)
+  - Create integration tests for user registration and login flows
+  - Build API endpoint tests for all authentication and bookmark endpoints
+  - Implement database isolation tests to verify user data separation
+  - Add security tests for SQL injection prevention and XSS protection
+  - _Requirements: 1.2, 2.2, 5.1, 8.4, 8.5_