Whispr

Secure, end-to-end encrypted communication for a zero-trust backend model.

Whispr is an end-to-end encrypted (E2EE) messaging platform designed on the principle of Zero Trust. The backend serves only as a blind relay, ensuring that even if the server is fully compromised, user conversations remain private and unreadable.

---

What Whispr Is

Whispr is an end-to-end encrypted messaging project designed around a simple assumption: the backend may fail, leak, or be compromised, and user privacy should still hold.

The repository currently contains:

• a client/ Next.js application
• a server/ Express and Socket.IO service
• a Docs/ directory describing the target architecture, security model, and roadmap

Current implemented surfaces:

• /app authenticated single-user chat flow
• /demo dual-client authenticated demo harness

Service-specific setup:

• client/README.md
• server/README.md

Some documentation describes the intended system design beyond what is already implemented in code. That distinction is deliberate and important for contributors.

System Architecture

Whispr uses a decoupled architecture where all cryptographic operations are offloaded to the client.

graph TD
    subgraph "Client A (Sender)"
        SA[Plaintext Message] --> SB[Local Encryption]
        SB --> SC[Encrypted Payload]
    end

    subgraph "Whispr Gateway (Untrusted)"
        GW[Node.js / Socket.IO]
        DB[(PostgreSQL)]
        GW --- DB
    end

    subgraph "Client B (Receiver)"
        RE1[Encrypted Payload] --> RE2[Local Decryption]
        RE2 --> RE3[Plaintext Message]
    end

    SC -- Secure WebSocket --> GW
    GW -- Push Notification / Sync --> RE1

Loading

---

Design Goals

• Client-side encryption and decryption
• Ciphertext-only message storage on the backend
• Secure public key distribution for one-to-one messaging
• Realtime encrypted message delivery
• A design that remains meaningful under backend compromise

---

Current Stack

Layer	Technology
Frontend	Next.js, React, TypeScript, Tailwind CSS
Backend	Node.js, Express, Socket.IO, Zod
Database	In-memory repository adapter today, Postgres adapter planned
Security Direction	Web Crypto API MVP using browser ECDH P-256 + AES-GCM, with stronger primitive upgrades planned

Local Development

Client

cd client
npm install
npm run dev

Server

cd server
npm install
npm start

Server health check:

curl http://localhost:4000/health

Local env setup:

• client/.env.example defines NEXT_PUBLIC_API_URL
• client/.env.example also includes NEXT_PUBLIC_DISABLE_REALTIME for Vercel-hosted polling mode
• server/.env.example defines port, client origin, JWT secret, token TTL, demo tools, storage driver, database URL, and realtime toggle

---

Documentation

The Docs/ folder contains the project design set:

Start with Docs/README.md for the document map and documentation rules.

• Project Overview
• Problem Statement
• Core Features
• System Architecture
• Cryptography and Security Flow
• Threat Model
• Tech Stack
• Database Design
• API Design
• Development Roadmap
• Demo Flow
• Pitch Notes

Contributing

Contributor guidance lives in CONTRIBUTING.md.

Use it for:

• local setup
• development expectations
• validation steps
• pull request standards
• documentation update rules

---

Vision

Most messaging systems rely on backend trust. Whispr is built on a different assumption: the backend may fail, leak, or be compromised. User privacy should still hold.

---

License

Distributed under the MIT License. See LICENSE for more information.