Skip to content

Conversation

@typelets
Copy link
Owner

Real-time WebSocket Sync + Folder Move Fix

Summary

Implements complete WebSocket real-time sync with HMAC authentication and fixes critical folder move sync bug.

Key Changes

  • Real-time sync for notes/folders across devices
  • HMAC-SHA256 authentication for message security
  • Fixed folder move sync - folderId changes now broadcast properly
  • Rate limiting (300 msg/min) and connection limits (20/user)
  • Security enhancements - removed JWT logging, added security headers
  • TypeScript fixes - iterator compatibility and postgres imports

Architecture

src/websocket/
├── auth/handler.ts # JWT + HMAC auth
├── handlers/notes.ts # Note sync (+ folder move fix)
├── middleware/ # Rate limiting & connections
└── index.ts # WebSocket manager

Critical Bug Fix

Before: Moving notes between folders didn't sync to other devices
After: Folder moves broadcast instantly via WebSocket

Root Cause: folderId missing from allowed update fields
Fix: Added to allowedFields array in note handler

WebSocket Protocol

  • Auth: JWT → HMAC session secret → signed messages
  • Sync: Real-time note/folder updates to all user devices
  • Security: Nonce replay protection, rate limiting, timeouts

Environment Variables

Variable Default Description
WS_RATE_LIMIT_MAX_MESSAGES 300 Messages per minute
WS_MAX_CONNECTIONS_PER_USER 20 Max connections per user
WS_AUTH_TIMEOUT_MS 30000 Auth timeout (30s)

Documentation

  • ✅ New WEBSOCKET_INTEGRATION.md with complete protocol spec
  • ✅ Updated README.md, SECURITY.md, CHANGELOG.md
  • ✅ Current project structure and WebSocket features documented

Testing

Multi-device sync now works for:

  • Note content changes ✅
  • Folder moves ✅ (newly fixed)
  • Note/folder creation/deletion ✅

Impact

  • Bundle: +0.6kb (+0.7%)

…d fix folder moves

  - Add complete WebSocket implementation for real-time note/folder synchronization
    - JWT authentication with 30-second timeout
    - Rate limiting (300 msg/min) and connection limits (20/user)
    - Connection management with automatic cleanup
    - Nonce-based replay attack prevention

  - Fix critical folder move sync issue
    - Add 'folderId' to allowed fields in note updates
    - Enable real-time sync of note folder changes across devices
    - Add comprehensive error logging for debugging

  - Enhance security infrastructure
    - Add security headers middleware (CSP, HSTS, XSS protection)
    - Implement enhanced rate limiting middleware

  - Fix TypeScript compilation issues
    - Resolve Map iterator compatibility with ES2022 target
    - Fix postgres module import issues
    - Add downlevelIteration support for future compatibility

  - Update comprehensive documentation
    - Add WEBSOCKET_INTEGRATION.md with complete protocol specification
    - Update README.md with current project structure and WebSocket features
    - Update SECURITY.md with latest security features and recommendations
@typelets typelets self-assigned this Sep 15, 2025
@typelets typelets merged commit 62ba36c into main Sep 15, 2025
4 checks passed
@github-actions
Copy link

🎉 This PR is included in version 1.1.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants