Hubfly spaceDocs
Console

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:

bash
hubfly realtime keygen --kid k1     # prints k1:<base64 of 32 random bytes>; nothing is sent
openssl rand -base64 32

Store 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.

.env (server only)
HUBFLY_REALTIME_E2E_KEYS=k1:your-generated-base64-key

Never in the browser

Do not put master keys in frontend variables or source code. Hubfly space never writes this variable into connected projects; set it yourself on the servers that publish and answer auth requests.

Encrypt a channel

  1. Set HUBFLY_REALTIME_E2E_KEYS on your backend. RealtimeServer.fromEnv() (and the Go realtime.FromEnv()) read it.
  2. 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.
  3. Turn encryption on in the client and subscribe to a private-encrypted- channel:
JavaScript
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:

JavaScript
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

MessagesBehavior
private-encrypted-… channelsPayloads are encrypted; event names stay visible. Readable by pusher-js with-encryption.
User messagesEncrypted when your server has master keys. Clients need e2e: true and user sign-in.
Direct messagesEncrypted when sent to an end-to-end connection id returned by connect().
Other private and presence channelsEncrypted, 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.

PolicyRule
offNo checks.
optional (default)Payloads on private-encrypted- channels must be encrypted envelopes; everything else may be plaintext.
requiredEvery 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

  1. Generate a new key and put it first in HUBFLY_REALTIME_E2E_KEYS on every backend, keeping the old one after it: k2:new-key,k1:old-key.
  2. New messages use k2. Hubfly space clients get both keys at their next authorization (or call realtime.reauthorize()), so they can still read older messages. pusher-js clients read new messages after they re-authorize, for example on reconnect.
  3. Remove the old key once your retained history has expired (at most 24 hours).

What Hubfly space can and cannot see

Hubfly space cannotHubfly space still sees
  • Read encrypted payloads, in transit, in history or in webhooks
  • Read event names of Hubfly space envelopes (full E2E, direct and user messages)
  • Forge messages that Hubfly space clients accept: they drop plaintext in encrypted contexts
  • App ids and keys, channel names, socket and user ids
  • Presence membership, and user info unless sealed
  • Message sizes, counts and timing; IP addresses, origins and client libraries
  • Webhook URLs, and event names on private-encrypted- channels

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.
Something unclear or out of date? Emailsupport@hubfly.spaceBack to top