← BACK TO PORTFOLIO

RISALA

رسالة — encrypted internal team messaging that runs on the local network only. Every message arrives, and none of them leaves.

RoleFull-stack Engineer
StackFastify, SQLite, Socket.IO, Preact
ClientsWeb & Electron desktop
CryptoAES-256-GCM, Argon2id

OVERVIEW

رسالة / RISALA is an internal team messaging application that runs on the local network only. Direct and group conversations, images and file sharing, an account per employee — with every message and attachment encrypted at rest.

The premise is one line: every message arrives, and none of them leaves. Team messages stay encrypted inside the organisation's own network and never travel outside it.

THE SEARCH PROBLEM WORTH SOLVING

Encrypting messages at rest is straightforward. Searching them afterwards is where the design gets interesting: decrypting every message on every query does not scale, and storing the words in clear text undoes the encryption entirely.

Instead, each message stores truncated HMAC-SHA256 fingerprints of its words, keyed from the master key — not the words themselves. Someone who holds the database without the key can see which messages share a word, but not what that word is. The index is built for old messages in batches at startup, and rebuilt when the key is rotated.

SECURITY DESIGN

Encryption at Rest
Message text, file names, and attachments are encrypted with AES-256-GCM. Each attachment is split into frames bound to its file id and order, so any edit, swap, or truncation is detected.
Master Key Discipline
Without the key file no message can be read. If the server finds a key that does not open the existing data, it refuses to start rather than generating a new one and mixing the data. A single corrupted record shows “this message could not be read” while the rest of the conversation stays intact.
Accounts & Sessions
Argon2id password hashing, optional TOTP two-factor with backup codes, HttpOnly SameSite=Strict session cookies, a device list the user can revoke, and progressive lockout counted per account and per IP so one password tried against every employee also stops.
Look-alike Names
A display name is rejected when it differs from an existing one only by what cannot be seen: diacritics, tatweel, zero-width and direction marks, letter forms, Persian and Urdu variants, and Cyrillic or Greek letters that imitate Latin ones.
Attachment Handling
Type whitelist, content verified by binary signature rather than extension, EXIF stripped from images, and per-user storage quotas. Archives and Office files are inspected without extraction and rejected if they contain executables, scripts, nested archives, password-protected content, or macros — with or without ClamAV.
Network Boundary
The server rejects any client outside the configured private ranges, and serves HTTPS and WSS using an internal CA certificate.

WHAT IT DOES AS A CHAT APP

  • Search that understands Arabic: ignores diacritics, tatweel, hamza forms, letter variants, and the definite article — across every conversation, grouped by chat, jumping to the exact message.
  • Conversation tools: replies, @mentions that pierce a muted chat, reactions, pinned messages, forwarding to up to ten chats with each file re-encrypted under its own id, and voice messages with a waveform measured once by the sender.
  • Read state: double-check marks in direct chats, “read by N” with names in groups.
  • Notifications: in-app cards that persist until acted on and support replying without opening the chat, plus desktop notifications with an option to hide message text on a shared screen.
  • Admin side: announcements to everyone or a selected group, an announcement mode that makes a group read-only, retention policy, open-registration toggle, and a one-time join code stored only as a fingerprint.

OPERATIONS

One Command to Try
A launcher installs dependencies, builds the UI, creates an admin with a random password, prints the network addresses, and opens the browser — Node.js is the only prerequisite.
Key Rotation
Re-encrypts every message and attachment, resumable if interrupted, with the old key retained until an explicit retire step so pre-rotation backups stay recoverable.
Safe Migrations
A full copy is saved beside the database before any upgrade, and the server refuses to start on a corrupted database or one upgraded by a newer build.
Backup & Restore
Node commands that work on Windows, Linux, macOS, and inside Docker, with key export kept separate from database backups.

WHERE THE MODEL STOPS

Whoever controls the server and its key can read the messages. End-to-end encryption is not enabled in this version, and the README says so rather than letting the word “encrypted” imply more than it delivers. The threat model this design actually covers is a stolen database file or a stolen disk — not a compromised server.

Note: RISALA is a private repository. This page describes the architecture and the security decisions behind it rather than linking to source.