Security

Run locally. Encrypt the rest.

Helmora keeps agent execution on your machine. When the managed relay is used, app-to-bridge protocol payloads are encrypted at the endpoints; the relay sees routing metadata and ciphertext.

How your data flows

01 / Local-first

Bridge runs on your machine

The bridge, agent credentials, workspaces, and agent-owned history stay on your machine. Same-machine loopback or an operator-authenticated TLS/SSH tunnel can speak directly to the bridge without a relay round-trip; the bridge does not expose plaintext protocol traffic on the LAN.

02 / Optional relay

Relay only when you want it

To reach a paired bridge from another network without running your own tunnel, the app can use Helmora's managed relay. A supported self-hosted relay is not currently offered.

03 / E2EE

End-to-end encryption

Relay payloads use an X3DH-established, per-device Double Ratchet with AES-256-GCM message protection. The relay forwards the opaque encrypted envelope.

04 / Explicit boundary

Know what remains visible

The relay is proprietary and its source is not published. It can observe account/device routing identifiers, timing, connection state, and frame sizes, but endpoint payload keys do not live there.

What the relay cannot do.

  • Decrypt frames. The keys live on the client and the bridge — never on the relay.
  • Read prompt or message contents from a valid encrypted envelope.
  • Accept a user envelope without a non-empty ciphertext field. Relay-owned presence and reachability controls are the documented exception.
  • Route a frame outside the authenticated user's device map. The signed connection identity must also match the envelope's from field.

Cryptography specifics.

Pre-alpha. This describes the implementation in the current repository, not a completed independent security assessment.

Session establishment: The app verifies the bridge's Ed25519-signed X25519 prekey against the authenticated bridge device record, then uses X3DH to establish a per-device session. The opening frame carries the X3DH preamble.

Ongoing messages: A Double Ratchet derives per-message keys. AES-256-GCM authenticates each payload and its identity/channel binding. Ratchet state is sealed locally on both endpoints and legacy shared-secret frames are rejected.

Implementation: Runtime-neutral TypeScript primitives use Web Crypto where available and a Hermes-compatible cryptographic backend on native. Helmora does not claim libsignal interoperability.

Limit: The account service is the trusted identity directory and also stores operational metadata in plaintext: device and agent records, session titles and status lines (including folder names and todo text), and notification titles and bodies for push delivery. The relay still sees routing metadata, timing, and size, and message padding is not implemented. Optional voice transcription is a separate, JWT-authenticated call that sends captured audio through the relay to the transcription provider you select — it is not inside the encrypted envelope path.

Trust model

  • Trust your own machine. The bridge has access to your local agents, file system, and API keys. Treat it like any other developer tool.
  • Don't entrust payload plaintext to the relay. Endpoint encryption is designed so the relay does not need message keys.
  • Don't trust the network. Cellular, hotel wifi, coworking — frames are encrypted before they leave the device.
  • Trust the account directory deliberately. It authenticates device records and serves public prekeys. A missing or changed bridge identity pin fails closed and requires repair or re-pairing.