Created Encrypted P2P Chat (markdown)
Carter Perez
parent
a3bede0430
commit
ebca8445a3
|
|
@ -0,0 +1,242 @@
|
|||
# Encrypted P2P Chat
|
||||
|
||||
Real-time encrypted messaging application using Signal Protocol encryption with passwordless WebAuthn authentication.
|
||||
|
||||
## Overview
|
||||
|
||||
A secure chat application implementing end-to-end encryption with forward secrecy and break-in recovery. Features passwordless authentication via WebAuthn/Passkeys and real-time messaging through WebSockets and SurrealDB live queries.
|
||||
|
||||
**Status:** Complete | **Difficulty:** Advanced
|
||||
|
||||
## Tech Stack
|
||||
|
||||
### Backend
|
||||
| Technology | Version | Purpose |
|
||||
|------------|---------|---------|
|
||||
| FastAPI | 0.121+ | Async Python web framework |
|
||||
| PostgreSQL | 16 | User auth & credentials |
|
||||
| SurrealDB | 1.0 | Real-time messaging (live queries) |
|
||||
| Redis | 7.1 | Challenge/session storage |
|
||||
| SQLModel | 0.0.27 | SQLAlchemy + Pydantic hybrid |
|
||||
| Alembic | 1.17+ | Async migrations |
|
||||
| PyNaCl | 1.6 | Encryption primitives |
|
||||
| liboqs-python | 0.14 | Post-quantum cryptography |
|
||||
|
||||
### Frontend
|
||||
| Technology | Version | Purpose |
|
||||
|------------|---------|---------|
|
||||
| SolidJS | 1.9 | Fine-grained reactivity |
|
||||
| TypeScript | 5.9 | Type safety |
|
||||
| Vite | 7.2 | Build tool (Node 20.19+) |
|
||||
| Tailwind CSS | v4 | Styling |
|
||||
| @tanstack/solid-query | 5.90 | Server state |
|
||||
| nanostores | 1.1 | Lightweight state |
|
||||
|
||||
### Infrastructure
|
||||
- Docker + Docker Compose
|
||||
- Nginx reverse proxy
|
||||
- Makefile automation
|
||||
|
||||
## Features
|
||||
|
||||
### Authentication
|
||||
- **Passwordless login** with WebAuthn/Passkeys (FIDO2)
|
||||
- Discoverable credentials (device-based)
|
||||
- Multi-device support
|
||||
- Signature counter verification
|
||||
|
||||
### Encryption (Signal Protocol)
|
||||
- **Double Ratchet** for message encryption
|
||||
- **X3DH key exchange** for async messaging
|
||||
- Forward secrecy
|
||||
- Break-in recovery
|
||||
- Out-of-order message handling
|
||||
- Per-message AES-256-GCM
|
||||
|
||||
### Real-Time Messaging
|
||||
- WebSocket connections with management
|
||||
- SurrealDB live queries
|
||||
- Online/offline presence
|
||||
- Typing indicators
|
||||
- Read receipts
|
||||
- Heartbeat keep-alive
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ Frontend (SolidJS) │
|
||||
│ ┌─────────┐ ┌──────────┐ ┌─────────┐ ┌───────────┐ │
|
||||
│ │ Auth │ │ Chat │ │ Rooms │ │ Crypto │ │
|
||||
│ │ WebAuthn│ │ Messages │ │ List │ │ Service │ │
|
||||
│ └────┬────┘ └────┬─────┘ └────┬────┘ └─────┬─────┘ │
|
||||
└───────┼────────────┼─────────────┼─────────────┼───────┘
|
||||
│ │ │ │
|
||||
▼ ▼ ▼ ▼
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ WebSocket + REST API (Nginx) │
|
||||
└─────────────────────────┬───────────────────────────────┘
|
||||
│
|
||||
┌─────────────────────────▼───────────────────────────────┐
|
||||
│ Backend (FastAPI) │
|
||||
│ │
|
||||
│ ┌──────────────────────────────────────────────────┐ │
|
||||
│ │ Services │ │
|
||||
│ │ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │ │
|
||||
│ │ │ Auth │ │ Message │ │ Presence │ │ │
|
||||
│ │ │ WebAuthn │ │ Encrypt │ │ Tracking │ │ │
|
||||
│ │ └──────────┘ └──────────┘ └──────────────┘ │ │
|
||||
│ │ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │ │
|
||||
│ │ │ Prekey │ │WebSocket │ │ Ratchet │ │ │
|
||||
│ │ │ X3DH │ │ Manager │ │ State │ │ │
|
||||
│ │ └──────────┘ └──────────┘ └──────────────┘ │ │
|
||||
│ └──────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌──────────────────────────────────────────────────┐ │
|
||||
│ │ Encryption Core │ │
|
||||
│ │ double_ratchet.py | x3dh_manager.py │ │
|
||||
│ └──────────────────────────────────────────────────┘ │
|
||||
└────────┬──────────────────┬──────────────────┬──────────┘
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||||
│ PostgreSQL │ │ SurrealDB │ │ Redis │
|
||||
│ Users/Creds │ │ Messages │ │ Sessions │
|
||||
│ Keys/Prekeys│ │ Live Queries│ │ Challenges │
|
||||
└─────────────┘ └─────────────┘ └─────────────┘
|
||||
```
|
||||
|
||||
## Key Exchange Flow (X3DH)
|
||||
|
||||
```
|
||||
Alice Bob
|
||||
│ │
|
||||
│ 1. Fetch Bob's prekey bundle │
|
||||
│ ──────────────────────────────────────────────>│
|
||||
│ │
|
||||
│ 2. Bundle: IdentityKey, SignedPrekey, │
|
||||
│ OneTimePrekey, Signature │
|
||||
│ <──────────────────────────────────────────────│
|
||||
│ │
|
||||
│ 3. Verify signature │
|
||||
│ 4. Generate ephemeral keypair │
|
||||
│ 5. Compute shared secrets (DH): │
|
||||
│ DH1 = DH(IK_A, SPK_B) │
|
||||
│ DH2 = DH(EK_A, IK_B) │
|
||||
│ DH3 = DH(EK_A, SPK_B) │
|
||||
│ DH4 = DH(EK_A, OPK_B) │
|
||||
│ 6. Derive root key: HKDF(DH1||DH2||DH3||DH4) │
|
||||
│ 7. Initialize Double Ratchet │
|
||||
│ │
|
||||
│ 8. Send initial message + EK_A public │
|
||||
│ ──────────────────────────────────────────────>│
|
||||
│ │
|
||||
│ 9. Bob computes same secrets │
|
||||
│ 10. Initializes Double Ratchet│
|
||||
│ │
|
||||
```
|
||||
|
||||
## Double Ratchet
|
||||
|
||||
Each message uses a unique key derived from the ratchet state:
|
||||
|
||||
```
|
||||
Root Key ─────┬─────> Chain Key 1 ──> Message Key 1
|
||||
│ ──> Message Key 2
|
||||
│
|
||||
└─────> Chain Key 2 ──> Message Key 3
|
||||
──> Message Key 4
|
||||
```
|
||||
|
||||
- **Symmetric ratchet:** Derives new message keys
|
||||
- **DH ratchet:** Updates root key on each reply
|
||||
- **Forward secrecy:** Old keys deleted after use
|
||||
- **Break-in recovery:** New DH ratchet heals compromise
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
cd PROJECTS/encrypted-p2p-chat
|
||||
|
||||
# Copy environment file
|
||||
cp .env.example .env
|
||||
|
||||
# Start development environment
|
||||
make dev
|
||||
|
||||
# Access at http://localhost:3000
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Key environment variables:
|
||||
|
||||
```bash
|
||||
# PostgreSQL
|
||||
DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/chat
|
||||
|
||||
# SurrealDB
|
||||
SURREAL_URL=ws://localhost:8000/rpc
|
||||
SURREAL_NS=chat
|
||||
SURREAL_DB=messages
|
||||
|
||||
# Redis
|
||||
REDIS_URL=redis://localhost:6379
|
||||
|
||||
# WebAuthn
|
||||
RP_ID=localhost
|
||||
RP_NAME=Encrypted Chat
|
||||
RP_ORIGIN=http://localhost:3000
|
||||
```
|
||||
|
||||
## Database Models
|
||||
|
||||
| Model | Database | Purpose |
|
||||
|-------|----------|---------|
|
||||
| User | PostgreSQL | User accounts |
|
||||
| Credential | PostgreSQL | WebAuthn credentials |
|
||||
| IdentityKey | PostgreSQL | Long-term identity keys |
|
||||
| SignedPrekey | PostgreSQL | Signed prekeys for X3DH |
|
||||
| OneTimePrekey | PostgreSQL | One-time prekeys |
|
||||
| RatchetState | PostgreSQL | Double ratchet state |
|
||||
| SkippedMessageKey | PostgreSQL | Out-of-order handling |
|
||||
| Messages | SurrealDB | Encrypted message storage |
|
||||
|
||||
## Frontend Stores
|
||||
|
||||
| Store | Purpose |
|
||||
|-------|---------|
|
||||
| authStore | Authentication state |
|
||||
| messagesStore | Message state |
|
||||
| roomsStore | Chat room state |
|
||||
| presenceStore | Online/offline status |
|
||||
| typingStore | Typing indicators |
|
||||
| settingsStore | User preferences |
|
||||
|
||||
## Development
|
||||
|
||||
```bash
|
||||
# Backend
|
||||
make backend-lint
|
||||
make backend-test
|
||||
|
||||
# Frontend
|
||||
make frontend-lint
|
||||
make frontend-build
|
||||
|
||||
# Both
|
||||
make lint
|
||||
make test
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- All messages encrypted client-side before transmission
|
||||
- Server never sees plaintext messages
|
||||
- Keys stored securely, old keys deleted
|
||||
- WebAuthn prevents phishing attacks
|
||||
- No passwords to steal or crack
|
||||
|
||||
## Source Code
|
||||
|
||||
[View on GitHub](https://github.com/CarterPerez-dev/Cybersecurity-Projects/tree/main/PROJECTS/encrypted-p2p-chat)
|
||||
Loading…
Reference in New Issue