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
This commit is contained in:
578
.kiro/specs/user-management/design.md
Normal file
578
.kiro/specs/user-management/design.md
Normal file
@ -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.
|
||||
Reference in New Issue
Block a user