I Built Hush Relay: A Self-Hosted Encrypted Messenger Using Vanilla JavaScript and One PHP File
No phone numbers. No registration. No centralized messaging provider. No frontend build pipeline. Just a browser, encryption, and a lightweight relay you can host yourself.
GitHub: https://github.com/altrudev/Hush-Relay
License: GNU AGPL-3.0-or-later
Status: Open source, experimental, seeking independent security review
Why I Built This
We have become accustomed to messaging applications requiring an entire ecosystem just to exchange a message.
Accounts, phone numbers, centralized infrastructure, dedicated mobile applications, notification services, identity providers, and increasingly complicated deployment environments.
Many of those components solve legitimate engineering problems. But I wanted to explore a different question:
How much infrastructure do two people actually need to exchange encrypted messages?
Could a messaging system work without depending on a centrally operated service?
Could the server be simple enough for someone to inspect and host on inexpensive hardware?
Could the client run directly in a browser without a complicated framework or build process?
Those questions became Hush Relay.
It's an experimental, self-hostable, end-to-end encrypted messaging application built primarily with vanilla JavaScript, the browser's native WebCrypto API, and a single PHP relay file.
The objective wasn't to create another massive communication platform.
It was to investigate how much complexity could be eliminated while retaining meaningful privacy protections.
The Architecture: Keep the Server Simple
Hush Relay separates the application into two components.
1. The Browser Application
The client handles identity generation, encryption, decryption, contact management, message verification, account recovery, and device migration.
It's built with HTML, JavaScript, WebCrypto, and a service worker.
There is no React, Angular, or Vue dependency.
There is no npm-based frontend build pipeline.
You can serve the application as ordinary static files alongside its PHP endpoint.
It also functions as an installable Progressive Web App (PWA).
2. The PHP Relay
The relay is intentionally limited in responsibility.
It accepts encrypted message envelopes, stores them temporarily, delivers them to the appropriate mailbox, and removes acknowledged or expired messages.
It does not receive plaintext messages or the cryptographic keys needed to decrypt them.
The simplified architecture looks like this:
DEVICE A
┌──────────────────┐
│ Browser / PWA │
│ │
│ Identity Keys │
│ Double Ratchet │
│ WebCrypto │
└────────┬─────────┘
│
│ Encrypted envelope
▼
┌──────────────────┐
│ PHP RELAY │
│ │
│ Encrypted Mailbox│
│ Storage & Routing│
│ │
│ No plaintext │
└────────┬─────────┘
│
│ Encrypted envelope
▼
┌──────────────────┐
│ Browser / PWA │
│ │
│ Local Decryption │
│ Message Display │
└──────────────────┘
DEVICE B
The relay is a mailbox, not a trusted participant in the encryption process.
There is an important distinction here: the server is not designed to know message contents, but it can still observe network metadata.
That limitation is discussed later.
No Accounts, No Phone Numbers
Instead of creating an account through a central identity service, Hush Relay generates a cryptographic identity locally.
Your identity is based on a key pair created on your device.
Contacts can be exchanged using QR codes or invitation links.
The invitation contains the information needed to establish communication, including the public key, mailbox identifier, and relay address.
A user can verify a contact's identity by comparing safety numbers.
There is no central phone-number directory or mandatory registration service.
The system also supports communication between people using different relay servers.
That was an important architectural objective: two users shouldn't necessarily have to depend on the same infrastructure provider to communicate.
Encryption Without External Cryptographic Libraries
Hush Relay uses the browser's native WebCrypto API.
The implementation uses established cryptographic primitives, including:
- ECDH P-256 for key agreement
- HKDF-SHA-256 for key derivation
- HMAC-SHA-256 for message-key derivation
- AES-256-GCM for authenticated encryption
- PBKDF2-SHA-256 for recovery-key derivation
The messaging protocol uses a Signal-style Double Ratchet construction.
Each message is encrypted, and the ratchet advances key material as the conversation progresses.
The system also wraps messages in an additional encrypted envelope using a fresh ephemeral key.
This outer encryption layer is intended to conceal sender-identifying information from the relay.
Messages are padded into predefined size buckets to reduce the precision of message-length observations.
However, using well-established cryptographic primitives does not automatically make a new protocol secure.
Hush Relay implements its own protocol construction rather than using the complete, independently reviewed Signal protocol implementation.
Its current design also lacks a prekey mechanism, which limits the forward-secrecy guarantees of initial messages.
Those differences matter, and they're documented in the repository.
Read the protocol specification.
Self-Hosting Shouldn't Require a Data Center
One of my design goals was to make deployment accessible.
Hush Relay's PHP-based version can run on ordinary shared hosting, a Raspberry Pi, an inexpensive VPS, or an Android device running Termux.
You can experiment with it locally using:
git clone https://github.com/altrudev/Hush-Relay.git
cd Hush-Relay
./scripts/serve.sh
Then open:
http://localhost:8080
For a quick test, open the application in two separate browser contexts, create identities, exchange an invitation, and try sending messages.
The local development server requires PHP 7.4 or newer.
For public deployment, you need HTTPS and a stable relay address.
The encrypted-message storage directory should be kept outside the publicly accessible web root.
The repository includes deployment instructions for shared hosting, VPS environments, Android/Termux, and IPFS-based distribution of the static client.
What About Account Recovery?
One problem with decentralized identity systems is that losing a device can mean losing access to your identity.
Hush Relay explores two mechanisms for addressing this.
Recovery words: The application generates six randomly selected recovery words. They are used to derive encryption material for an account backup stored on the relay.
The relay stores the encrypted backup without possessing the recovery words required to decrypt it.
Device migration: Users can transfer an account between devices using a QR-based process and a 12-digit comparison code.
The current implementation supports one active device per account.
Device migration transfers account information rather than preserving an entire synchronized conversation history.
These approaches involve trade-offs, particularly around recovery-secret entropy, device compromise, and the handling of existing sessions.
They're areas where independent review would be especially valuable.
What the Relay Still Knows
End-to-end encryption protects message contents when correctly implemented.
It doesn't automatically eliminate metadata.
A Hush Relay operator can potentially observe IP addresses, connection timing, recipient mailbox identifiers, message-size buckets, and whether messages are waiting for collection.
There is also a fundamental challenge with browser-delivered cryptographic applications.
The server delivering the JavaScript can potentially modify the application itself.
A compromised or malicious application host could deliver altered code that undermines client-side encryption.
Self-hosting, reviewing the served source, or using content-addressed distribution through IPFS can reduce certain aspects of this risk, but they don't make the problem disappear.
Other current limitations include the absence of push notifications, local-only message history, one active device per account, and known protocol limitations involving early-session forward secrecy and key-compromise impersonation.
I think it's important to document these limitations rather than hide them behind marketing claims.
Security Reviews and the Work Still Needed
During development, Hush Relay underwent two rounds of internal adversarial review.
Those reviews identified 20 security and reliability issues that were subsequently addressed with regression tests.
Findings included problems involving data-directory exposure, replay handling, relay abuse limits, invitation handling, recovery behavior, and proxy-related rate limiting.
The repository contains the findings, mitigation descriptions, and relevant tests.
However, internal testing is not equivalent to an independent cryptographic audit.
Hush Relay has not been independently audited and should not currently be trusted for high-risk or safety-critical communications.
Anyone whose safety depends on secure messaging should use an established, independently reviewed solution rather than this experimental implementation.
Security documentation and audit log
Why Open Source?
I believe communication infrastructure deserves transparency.
People should be able to inspect the systems carrying their messages, understand the trust assumptions, and decide where their information is stored.
They should also be able to operate infrastructure themselves without relying entirely on the decisions of a commercial provider.
Hush Relay is published under the GNU Affero General Public License v3.0 or later.
The intent is to keep the original project open and ensure that applicable source-sharing obligations extend to modified versions provided over networks.
Bundled third-party components retain their respective licenses.
The repository includes the source, protocol specification, deployment instructions, security documentation, and testing framework.
Where I'd Like Technical Feedback
I'm particularly interested in feedback from developers experienced in applied cryptography, distributed systems, browser security, and self-hosted infrastructure.
Some questions I'm exploring:
1. Protocol design: What weaknesses or unnecessary complexity do you see in the current key agreement and ratchet implementation?
2. Relay trust: How far can sender privacy and metadata minimization realistically be improved while retaining such a lightweight relay?
3. Recovery: What would you change about the recovery-word and device-migration mechanisms?
4. Hosting: What deployment and operational risks are most likely to be overlooked by someone running this on shared hosting or a small VPS?
5. Verification: Which additional independent tests would provide the most meaningful evidence of correctness?
I'm interested in reproducible findings, adversarial testing, and concrete architectural improvements.
Security vulnerabilities should be reported privately through the repository's GitHub Security tab rather than disclosed in public comments before they can be addressed.
Final Thoughts
Hush Relay started with a relatively simple engineering question:
What if encrypted communication didn't require a complicated infrastructure stack?
The result is a small, self-hostable messaging experiment that can operate using technologies already available on common web servers and browsers.
It is not a finished answer to secure messaging.
It's a working exploration of the trade-offs between simplicity, decentralization, deployment accessibility, and cryptographic assurance.
There is still substantial work to do, particularly around independent security evaluation.
But that's also why I decided to publish the source and invite technical scrutiny.
If you're interested in privacy engineering, minimal infrastructure, cryptographic protocols, or self-hosted applications, I'd welcome your feedback.
GitHub: https://github.com/altrudev/Hush-Relay
Project: Hush Relay
Developer: Val Rukhaylo / Altru.dev
License: AGPL-3.0-or-later
Build something useful. Understand what it does. Test what it claims.
Top comments (0)