Secure Chat - Next.js Enterprise-Grade E2EE Messaging

Production-ready, zero-knowledge, end-to-end encrypted messaging. Built with Next.js 15, React 19, TypeScript, Web Crypto API, and PWA.

---

🚀 Key Features (V3 Hardened)

🔐 Maximum Security

• Double Ratchet Protocol: Signal-style encryption offering Forward Secrecy (compromised keys can't read past messages) and Post-Compromise Security (healing).
• Crypto Isolation: All sensitive key operations run in a dedicated Web Worker (public/worker.js), ensuring main thread vulnerabilities (XSS) cannot easily extract keys.
• Trust On First Use (TOFU): Identity Keys are generated once and pinned in IndexedDB.
• JIT Handshake: Just-In-Time Key Exchange allows you to chat immediately by pasting a Peer ID.

� NEW: Progressive Web App (PWA)

• Installable: Full "Add to Home Screen" support as a native-like app.
• Security-First Caching: Custom Service Worker (sw.js) explicitly excludes crypto logic and keys from cache to ensure freshness, while speeding up UI assets.
• Offline Shell: Application loads instantly even offline (though messaging requires network).

✨ Advanced Features

• Remote Edit & Recall: Securely Edit or Delete sent messages. These actions are encrypted and propagated to peers automatically.
• Self-Destruct: "Read Once" (Burn-on-read) and Timer-based expiration support.
• Traffic Analysis Resistance: Messages padded to fixed 256-byte buckets.
• Metadata Protection: Random "Jitter" (0-300ms) obscures typing patterns.

📎 NEW: End-to-End Encrypted Media Sharing

• Client-Side Encryption: All files are encrypted in the browser using AES-256-GCM with unique per-file keys before upload.
• Zero-Knowledge Storage: Server stores only encrypted binary blobs. No filenames, MIME types, or metadata are persisted.
• Secure Key Exchange: Media decryption keys are transmitted only via the existing E2E encrypted channel (Double Ratchet).
• On-Demand Decryption: Receiver downloads encrypted blob and decrypts locally—server never sees plaintext.
• Supported Formats: Images, videos, and any file type (rendered as downloadable attachment).
• Size Limit: 25MB per file.

🛡️ Defense in Depth

• Strict Transport: Enforced HSTS, CSP, and Anti-CSWSH (Origin Verification).
• Audit Logs: Built-in local security event logging at /security/events.
• No Login: Anonymity by default. No email, phone, or serverside database.

---

🛠️ Quick Start

1. Installation

git clone <your-repo-url>
cd securechat
npm install

2. Run Development Server

This starts Next.js (Port 3000) and WebSocket Relay (Port 3001) concurrently.

npm run dev

3. Access

Open http://localhost:3000.

Note: You will see a dedicated WebSocket server running on port 3001. This is the Zero-Knowledge Relay. It blindly passes encrypted packets.

---

🔧 Troubleshooting

"Address in use" (EADDRINUSE)

If the server fails to start because port 3000/3001 is busy:

# Kill stuck processes (Linux/Mac)
fuser -k 3000/tcp 3001/tcp
# Then restart
npm run dev

"Target peer not connected"

This means the Peer ID you are trying to message is offline or invalid (peers are ephemeral).

• Fix: Ask the peer to refresh and share their new ID.

"WebSocket Connection Failed"

Ensure the WebSocket server is running npm run ws:dev (included in npm run dev).

---

🏗️ Architecture

securechat/
├── app/                  
│   ├── page.tsx          # Client Logic (UI)
│   ├── api/
│   │   └── media/        # Encrypted Media API
│   │       ├── upload/   # POST: Accept encrypted blob, return download URL
│   │       └── download/ # GET: Stream encrypted blob to client
│   ├── security/         # Threat Model & Events Log
│   └── layout.tsx        # Security Headers & PWA Register
├── components/           # UI Components (Bubble, Sidebar, MediaContent)
├── hooks/                
│   └── useSecureChat.ts  # Crypto Logic, Protocol Orchestration, Media Handling
├── lib/
│   ├── storage/          
│   │   ├── db.ts         # IndexedDB Wrapper (Identity, Sessions)
│   │   └── mediaStorage.ts # Filesystem Storage for Encrypted Blobs
│   └── crypto/           # Crypto Utils
├── public/
│   ├── worker.js         # ISOLATED Crypto Worker (Keys, File Encryption)
│   ├── sw.js             # Security-First Service Worker
│   └── manifest.json     # PWA Manifest
├── media/                # Encrypted blob storage (gitignored)
├── ws-server.ts          # Relay Server (Port 3001)
└── next.config.js        # Strict CSP

---

🌍 Deployment

1. Environment Variables

Create .env.local for production overrides:

NEXT_PUBLIC_WS_URL=wss://your-domain.com
WS_PORT=3001
MEDIA_STORAGE_PATH=/path/to/persistent/media  # Optional: defaults to ./media

2. Production Build

npm run build
npm start

• Reverse Proxy: You MUST use Nginx/Caddy to terminate TLS (HTTPS) and forward WebSocket Upgrade headers.
• HTTPS: Web Crypto API requires HTTPS (or localhost).
• Media Storage: Ensure MEDIA_STORAGE_PATH points to a persistent, writable directory.

---

🔒 Media Security Model

Layer	Protection
Encryption	AES-256-GCM with unique key per file
Key Exchange	Keys sent via Double Ratchet E2E channel
Storage	Server stores only encrypted blobs
Metadata	No filenames, MIME types, or sizes logged
Decryption	Client-side only, on-demand

---

📜 Credits & License

• Protocol: Based on the Double Ratchet Algorithm by Signal.
• Crypto: Native Web Crypto API (SubtleCrypto).
• License: MIT.