End-to-end encryption
Hubfly space Realtime can relay messages that only your servers and your users' devices can read. Your backend encrypts with master keys that you generate and keep; authorized clients receive the keys they need from your own auth endpoint. The realtime server, history, webhooks, the debug console and the Dashboard see only ciphertext.
How it works
- Master keys are 32 random bytes per key id, created and stored only on your servers. Hubfly space never receives them.
- Channel and user keys are derived from a master key and the channel name (the same construction Pusher uses for encrypted channels). Your auth endpoint hands them only to clients it allows on that channel.
- Direct-message keys are generated by each client. The client's connection id carries the key to your server, so it never passes through Hubfly space.
- Messages are sealed with NaCl
secretbox(XSalsa20-Poly1305). Receivers drop messages that fail to decrypt, arrive in the wrong context, are replayed or are older than 24 hours.
Create and store master keys
Generate a key on your own machine, with the CLI, with OpenSSL, or with the generator in the server's Encryption section, which runs in your browser and makes no request:
hubfly realtime keygen --kid k1 # prints k1:<base64 of 32 random bytes>; nothing is sent
openssl rand -base64 32Store it in your backend environment as HUBFLY_REALTIME_E2E_KEYS: a comma-separated list of kid:base64 entries. The first entry encrypts; the others only decrypt. A bare base64 value means key id k1.
HUBFLY_REALTIME_E2E_KEYS=k1:your-generated-base64-keyNever in the browser
Encrypt a channel
- Set
HUBFLY_REALTIME_E2E_KEYSon your backend.RealtimeServer.fromEnv()(and the Gorealtime.FromEnv()) read it. - Serve your auth endpoint with the server SDK and allow only the users who should read the channel. The SDK adds the channel key to its response.
- Turn encryption on in the client and subscribe to a
private-encrypted-channel:
import { Realtime } from "@hubfly/realtime";
const realtime = new Realtime({
url: "https://chat-1a2b.rt.hubfly.app",
key: "your-app-key",
authEndpoint: "/api/realtime/auth",
e2e: true,
});
realtime.subscribe("private-encrypted-chat")
.bind("message.created", (message) => console.log(message.text));
realtime.on("e2e:error", (error) => console.error(error.reason));
await realtime.connect();Publish from your backend as usual; the SDK encrypts because the channel is encrypted:
import { RealtimeServer } from "@hubfly/realtime/server";
const realtime = RealtimeServer.fromEnv();
await realtime.channel("private-encrypted-chat")
.publish("message.created", { text: "Only authorized clients can read this" });private-encrypted- channels are compatible with pusher-js with-encryption and Pusher server libraries configured with an encryption master key.
What is encrypted
| Messages | Behavior |
|---|---|
private-encrypted-… channels | Payloads are encrypted; event names stay visible. Readable by pusher-js with-encryption. |
| User messages | Encrypted when your server has master keys. Clients need e2e: true and user sign-in. |
| Direct messages | Encrypted when sent to an end-to-end connection id returned by connect(). |
| Other private and presence channels | Encrypted, including event names and presence or sign-in user info, when the server SDK runs with fullE2E: true. pusher-js clients cannot read these events. |
With encryption on, connect() returns a connection id of the form <socket_id>~<key>. Pass it only to your own backend and treat it as a secret. The Dashboard, the SDKs and the CLI strip the key part before any request and refuse to send plaintext to such an id; hubfly realtime send --strip-key sends unencrypted plaintext to the socket id instead.
Encryption policy
Each app has a policy, set in the app settings or with hubfly realtime apps update <server> <app> --encryption <policy>. The server never has your keys: it only checks that payloads look like valid encrypted envelopes.
| Policy | Rule |
|---|---|
off | No checks. |
optional (default) | Payloads on private-encrypted- channels must be encrypted envelopes; everything else may be plaintext. |
required | Every publish, send, client event and console message must be encrypted, and presence and sign-in user info must be sealed or absent. Plaintext is refused (HTTP 403 with reason e2e_required). Run the server SDK with fullE2E: true if you send presence or sign-in user info. |
Rotate keys
- Generate a new key and put it first in
HUBFLY_REALTIME_E2E_KEYSon every backend, keeping the old one after it:k2:new-key,k1:old-key. - New messages use
k2. Hubfly space clients get both keys at their next authorization (or callrealtime.reauthorize()), so they can still read older messages. pusher-js clients read new messages after they re-authorize, for example on reconnect. - Remove the old key once your retained history has expired (at most 24 hours).
What Hubfly space can and cannot see
| Hubfly space cannot | Hubfly space still sees |
|---|---|
|
|
Hubfly space can still drop, delay or reorder messages. Channel names are not hidden.
Where it does not help
- Encryption protects against the realtime service, not against whoever controls your auth endpoint or master keys.
- If your backend runs on Hubfly space hosting, that hosting environment holds your master keys. Apps built with the AI Builder therefore use encryption
off. allowPlaintext(client and server SDK option) is meant for migrations and weakens the forgery protection.private-encrypted-channels refuse plaintext regardless.