feat(websocket): implement real-time sync with HMAC authentication an…

.env.example

@@ -1,34 +1,190 @@
-# LOCAL DEVELOPMENT AND TESTING ENVIRONMENT VARIABLES
-# This file is ONLY for local development and testing
-# Copy this file to .env and update with your local testing values
+# ================================================================
+# TYPELETS API - ENVIRONMENT CONFIGURATION TEMPLATE
+# ================================================================
+# This file is for LOCAL DEVELOPMENT AND TESTING ONLY
+# Copy this file to `.env` and update with your actual values
+# Production deployments use AWS ECS task definitions, not .env files
 
-# Database connection for local testing
-# For Docker PostgreSQL (recommended for testing):
+# ================================================================
+# REQUIRED CONFIGURATION
+# ================================================================
+
+# Database Connection (REQUIRED)
+# For Docker PostgreSQL (recommended for local development):
 DATABASE_URL=postgresql://postgres:devpassword@localhost:5432/typelets_local
 # For local PostgreSQL installation:
 # DATABASE_URL=postgresql://postgres:your_password@localhost:5432/typelets_local
+# For production (example):
+# DATABASE_URL=postgresql://username:password@hostname:5432/database?sslmode=require
 
-# Clerk authentication for local testing (get from https://dashboard.clerk.com)
+# Clerk Authentication (REQUIRED)
+# Get your secret key from: https://dashboard.clerk.com/
+# For development, use test keys (sk_test_...)
+# For production, use live keys (sk_live_...)
 CLERK_SECRET_KEY=sk_test_your_actual_clerk_secret_key_from_dashboard
 
-# CORS configuration - REQUIRED
-# Comma-separated list of allowed origins
+# CORS Origins (REQUIRED)
+# Comma-separated list of allowed origins (no spaces after commas)
+# Include all frontend domains that will access this API
 CORS_ORIGINS=http://localhost:5173,http://localhost:3000
+# Production example:
+# CORS_ORIGINS=https://app.typelets.com,https://typelets.com
+
+# ================================================================
+# SERVER CONFIGURATION
+# ================================================================
 
-# Optional settings (have sensible defaults)
+# Server Port
 PORT=3000
+
+# Environment
 NODE_ENV=development
 
-# File upload configuration
-# MAX_FILE_SIZE_MB=50      # Maximum size per file in MB (default: 50)
-# MAX_NOTE_SIZE_MB=1024    # Maximum total attachments per note in MB (default: 1024MB = 1GB)
+# ================================================================
+# SECURITY CONFIGURATION
+# ================================================================
+
+# WebSocket Message Authentication
+# Generate with: openssl rand -hex 32
+# CRITICAL: Use a strong random string (minimum 32 characters) in production
+MESSAGE_AUTH_SECRET=your-very-secure-random-string-here-min-32-chars
+
+# ================================================================
+# RATE LIMITING CONFIGURATION
+# ================================================================
+# Current defaults are development-friendly
+# Adjust these values based on your usage patterns
+
+# HTTP API Rate Limiting
+# HTTP_RATE_LIMIT_WINDOW_MS=900000    # 15 minutes in milliseconds
+# HTTP_RATE_LIMIT_MAX_REQUESTS=1000   # Max requests per window per user/IP
+# HTTP_FILE_RATE_LIMIT_MAX=100        # Max file operations per window
+
+# WebSocket Rate Limiting
+WS_RATE_LIMIT_WINDOW_MS=60000         # Time window: 1 minute (in milliseconds)
+WS_RATE_LIMIT_MAX_MESSAGES=300        # Max messages per window per connection
+WS_MAX_CONNECTIONS_PER_USER=20        # Max concurrent connections per user
+WS_AUTH_TIMEOUT_MS=30000              # Authentication timeout: 30 seconds
+
+# Production Rate Limiting Recommendations:
+# - HTTP: 500-1000 requests per 15 minutes per user
+# - WebSocket: 100-300 messages per minute per connection
+# - File uploads: 50-100 operations per 15 minutes per user
+# - Connections: 10-20 per user depending on multi-device usage
+
+# ================================================================
+# FILE UPLOAD CONFIGURATION
+# ================================================================
+
+# File Size Limits
+MAX_FILE_SIZE_MB=50                   # Maximum size per file (default: 50MB)
+# MAX_NOTE_SIZE_MB=1024               # Maximum total attachments per note (default: 1GB)
+
+# Allowed File Types (handled in code, documented here)
+# Images: JPEG, PNG, GIF, WebP
+# Documents: PDF, Plain Text, Markdown, JSON, CSV
+# Add new types in: src/lib/validation.ts
+
+# ================================================================
+# BILLING & LIMITS CONFIGURATION
+# ================================================================
+
+# Free Tier Limits
+FREE_TIER_STORAGE_GB=1                # Storage limit for free users (default: 1GB)
+FREE_TIER_NOTE_LIMIT=100              # Note count limit for free users (default: 100)
+
+# Usage tracking for billing analytics
+# These limits trigger billing events logged to console
+# Upgrade prompts and enforcement handled in frontend
+
+# ================================================================
+# LOGGING & MONITORING
+# ================================================================
+
+# Debug Logging
+# DEBUG=false                         # Set to true for verbose logging (not recommended in production)
+
+# Application Logging
+# Structured logs are automatically generated for:
+# - Authentication events
+# - Rate limiting violations
+# - Security events (failed auth, suspicious activity)
+# - Billing limit violations
+# - WebSocket connection events
+# - File upload events
+
+# ================================================================
+# DEVELOPMENT HELPERS
+# ================================================================
+
+# Database Development
+# Run with Docker: docker run --name typelets-postgres -e POSTGRES_PASSWORD=devpassword -p 5432:5432 -d postgres:15
+# Connect: psql postgresql://postgres:devpassword@localhost:5432/typelets_local
+
+# Frontend Development URLs
+# Vite dev server: http://localhost:5173
+# Next.js dev server: http://localhost:3000
+# React dev server: http://localhost:3000
+
+# API Testing
+# Health check: GET http://localhost:3000/health
+# WebSocket status: GET http://localhost:3000/websocket/status
+# API documentation: https://github.com/typelets/typelets-api
+
+# ================================================================
+# SECURITY NOTES
+# ================================================================
+
+# 🔒 NEVER commit actual secrets to version control
+# 🔒 Use different secrets for development and production
+# 🔒 Rotate secrets regularly in production
+# 🔒 MESSAGE_AUTH_SECRET is critical for WebSocket security
+# 🔒 CLERK_SECRET_KEY controls all authentication
+# 🔒 DATABASE_URL contains database credentials
+
+# Generate secure secrets:
+# MESSAGE_AUTH_SECRET: openssl rand -hex 32
+# API Keys: Use your service provider's dashboard
+# Database passwords: Use password managers
+
+# ================================================================
+# PRODUCTION DEPLOYMENT NOTES
+# ================================================================
+
+# AWS ECS Deployment:
+# - Environment variables are set in ECS task definitions
+# - Secrets are managed via AWS Secrets Manager
+# - This .env file is NOT used in production
+# - SSL/TLS termination handled by Application Load Balancer
+# - Database connections use IAM authentication or managed secrets
+
+# Docker Production:
+# - Pass environment variables via docker run -e or docker-compose
+# - Mount secrets as files or use Docker secrets
+# - Never build secrets into Docker images
+
+# Kubernetes Deployment:
+# - Use ConfigMaps for non-sensitive configuration
+# - Use Secrets for sensitive data (base64 encoded)
+# - Consider external secret management (HashiCorp Vault, etc.)
+
+# ================================================================
+# TROUBLESHOOTING
+# ================================================================
 
-# Free tier limits for billing
-# FREE_TIER_STORAGE_GB=1   # Storage limit in GB for free tier (default: 1)
-# FREE_TIER_NOTE_LIMIT=100 # Note count limit for free tier (default: 100)
+# Common Issues:
+# 1. "Database connection failed" → Check DATABASE_URL and database status
+# 2. "Authentication failed" → Verify CLERK_SECRET_KEY is correct
+# 3. "CORS error" → Add your frontend URL to CORS_ORIGINS
+# 4. "Too many requests" → Increase rate limits or check for loops
+# 5. "WebSocket connection failed" → Check authentication and rate limits
 
-# Debug logging
-# DEBUG=false  # Set to true to enable debug logging in production
+# Useful Commands:
+# Check database connection: npx drizzle-kit studio
+# Test API endpoints: curl http://localhost:3000/health
+# Monitor logs: tail -f logs/app.log (if file logging enabled)
+# Generate new secrets: openssl rand -hex 32
 
-# IMPORTANT: This .env file is for LOCAL TESTING ONLY
-# Production uses AWS ECS task definitions, not .env files
+# Support:
+# Documentation: https://github.com/typelets/typelets-api
+# Issues: https://github.com/typelets/typelets-api/issues

CHANGELOG.md

@@ -49,6 +49,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **Real-time WebSocket Sync**: Complete WebSocket implementation for real-time note and folder synchronization
+  - JWT authentication for WebSocket connections
+  - Optional HMAC-SHA256 message authentication for enhanced security
+  - Rate limiting (300 messages/min) and connection limits (20 per user)
+  - Connection management with automatic cleanup
+  - Note and folder sync across multiple devices/sessions
+  - Support for note folder moves via WebSocket
+- **Security Enhancements**:
+  - Comprehensive security headers middleware (CSP, HSTS, XSS protection)
+  - Enhanced rate limiting middleware
+  - Production-ready security configuration
+- **TypeScript Improvements**: Fixed iterator compatibility and module import issues
+- **Documentation**: Complete WebSocket integration documentation and updated security policy
+
+### Fixed
+
+- WebSocket note sync issue where `folderId` changes weren't being broadcast
+- TypeScript compilation issues with Map iterators and postgres module imports
+- Memory leak prevention in nonce storage with automatic cleanup
+
+### Previous Releases
+
 - Initial open source release
 - TypeScript API with Hono framework
 - PostgreSQL database with Drizzle ORM

README.md

@@ -18,6 +18,7 @@ The backend API for the [Typelets Application](https://github.com/typelets/typel
 - 📎 **File Attachments** with encrypted storage
 - 🏷️ **Tags & Search** for easy note discovery
 - 🗑️ **Trash & Archive** functionality
+- 🔄 **Real-time Sync** via WebSockets for multi-device support
 - ⚡ **Fast & Type-Safe** with TypeScript and Hono
 - 🐘 **PostgreSQL** with Drizzle ORM
 
@@ -91,6 +92,8 @@ pnpm run dev
 
 🎉 **Your API is now running at `http://localhost:3000`**
 
+**WebSocket connection available at: `ws://localhost:3000`**
+
 The development server will automatically restart when you make changes to any TypeScript files.
 
 ### Why This Setup?
@@ -156,6 +159,7 @@ If you prefer to install PostgreSQL locally instead of Docker:
 
 - `GET /` - API information and health status
 - `GET /health` - Health check endpoint
+- `GET /websocket/status` - WebSocket server status and statistics
 
 ### Authentication
 
@@ -195,6 +199,30 @@ All `/api/*` endpoints require authentication via Bearer token in the Authorizat
 - `GET /api/files/:id` - Get file details
 - `DELETE /api/files/:id` - Delete file attachment
 
+### WebSocket Real-time Sync
+
+The API provides real-time synchronization via WebSocket connection at `ws://localhost:3000` (or your configured port).
+
+**Connection Flow:**
+1. Connect to WebSocket endpoint
+2. Send authentication message with Clerk JWT token
+3. Join/leave specific notes for real-time updates
+4. Receive real-time sync messages for notes and folders
+
+**Message Types:**
+- `auth` - Authenticate with JWT token
+- `ping`/`pong` - Heartbeat messages
+- `join_note`/`leave_note` - Subscribe/unsubscribe from note updates
+- `note_update` - Real-time note content changes and folder moves
+- `note_created`/`note_deleted` - Note lifecycle events
+- `folder_created`/`folder_updated`/`folder_deleted` - Folder events
+
+**Security Features:**
+- JWT authentication required for all operations
+- Authorization checks ensure users only access their own notes/folders
+- Rate limiting (configurable, default: 300 messages per minute per connection)
+- Connection limits (configurable, default: 20 connections per user)
+
 ## Database Schema
 
 The application uses the following main tables:
@@ -211,22 +239,28 @@ The application uses the following main tables:
 - **Input Validation**: Comprehensive Zod schemas for all inputs
 - **SQL Injection Protection**: Parameterized queries via Drizzle ORM
 - **CORS Configuration**: Configurable allowed origins
-- **Rate Limiting**: Configurable file size limits (default: 50MB per file, 1GB total per note)
+- **File Size Limits**: Configurable limits (default: 50MB per file, 1GB total per note)
+- **WebSocket Security**: JWT authentication, rate limiting, and connection limits
+- **Real-time Authorization**: Database-level ownership validation for all WebSocket operations
 
 ## Environment Variables
 
-| Variable              | Description                                  | Required | Default     |
-| --------------------- | -------------------------------------------- | -------- | ----------- |
-| `DATABASE_URL`        | PostgreSQL connection string                 | Yes      | -           |
-| `CLERK_SECRET_KEY`    | Clerk secret key for JWT verification        | Yes      | -           |
-| `CORS_ORIGINS`        | Comma-separated list of allowed CORS origins | Yes      | -           |
-| `PORT`                | Server port                                  | No       | 3000        |
-| `NODE_ENV`            | Environment (development/production)         | No       | development |
-| `MAX_FILE_SIZE_MB`    | Maximum size per file in MB                  | No       | 50          |
-| `MAX_NOTE_SIZE_MB`    | Maximum total attachments per note in MB     | No       | 1024 (1GB)  |
-| `FREE_TIER_STORAGE_GB`| Free tier storage limit in GB               | No       | 1           |
-| `FREE_TIER_NOTE_LIMIT`| Free tier note count limit                  | No       | 100         |
-| `DEBUG`               | Enable debug logging in production           | No       | false       |
+| Variable                     | Description                                  | Required | Default     |
+| ---------------------------- | -------------------------------------------- | -------- | ----------- |
+| `DATABASE_URL`               | PostgreSQL connection string                 | Yes      | -           |
+| `CLERK_SECRET_KEY`           | Clerk secret key for JWT verification        | Yes      | -           |
+| `CORS_ORIGINS`               | Comma-separated list of allowed CORS origins | Yes      | -           |
+| `PORT`                       | Server port                                  | No       | 3000        |
+| `NODE_ENV`                   | Environment (development/production)         | No       | development |
+| `MAX_FILE_SIZE_MB`           | Maximum size per file in MB                  | No       | 50          |
+| `MAX_NOTE_SIZE_MB`           | Maximum total attachments per note in MB     | No       | 1024 (1GB)  |
+| `FREE_TIER_STORAGE_GB`       | Free tier storage limit in GB               | No       | 1           |
+| `FREE_TIER_NOTE_LIMIT`       | Free tier note count limit                  | No       | 100         |
+| `DEBUG`                      | Enable debug logging in production           | No       | false       |
+| `WS_RATE_LIMIT_WINDOW_MS`    | WebSocket rate limit window in milliseconds  | No       | 60000 (1 min) |
+| `WS_RATE_LIMIT_MAX_MESSAGES` | Max WebSocket messages per window            | No       | 300         |
+| `WS_MAX_CONNECTIONS_PER_USER`| Max WebSocket connections per user          | No       | 20          |
+| `WS_AUTH_TIMEOUT_MS`         | WebSocket authentication timeout in milliseconds | No   | 30000 (30 sec) |
 
 ## Development
 
@@ -240,15 +274,29 @@ src/
 ├── lib/
 │   └── validation.ts   # Zod validation schemas
 ├── middleware/
-│   └── auth.ts        # Authentication middleware
+│   ├── auth.ts         # Authentication middleware
+│   ├── rate-limit.ts   # Rate limiting middleware
+│   └── security.ts     # Security headers middleware
 ├── routes/
-│   ├── files.ts       # File attachment routes
-│   ├── folders.ts     # Folder management routes
-│   ├── notes.ts       # Note management routes
-│   └── users.ts       # User profile routes
+│   ├── files.ts        # File attachment routes
+│   ├── folders.ts      # Folder management routes
+│   ├── notes.ts        # Note management routes
+│   └── users.ts        # User profile routes
 ├── types/
-│   └── index.ts       # TypeScript type definitions
-└── server.ts          # Application entry point
+│   └── index.ts        # TypeScript type definitions
+├── websocket/
+│   ├── auth/
+│   │   └── handler.ts  # JWT authentication and HMAC verification
+│   ├── handlers/
+│   │   ├── base.ts     # Base handler for resource operations
+│   │   ├── notes.ts    # Note sync operations
+│   │   └── folders.ts  # Folder sync operations
+│   ├── middleware/
+│   │   ├── connection-manager.ts  # Connection tracking and cleanup
+│   │   └── rate-limiter.ts        # WebSocket rate limiting
+│   ├── types.ts        # WebSocket message types
+│   └── index.ts        # Main WebSocket server manager
+└── server.ts           # Application entry point
 ```
 
 ### Type Safety