End-to-End Encryption

"The Mothership knows who, when, and how much. In federated mode, it never knows what."

Overview

Peer-to-peer traffic in Aura is protected by TLS 1.3 with peer-certificate pinning. In the default configuration, the Mothership acts as a directory and token issuer — it introduces peers to each other but does not relay the data that flows between them. In federated (directory-only) mode, the architecture is strengthened further: peer connections terminate directly between peers, using peer-held keys, with the Mothership blind to plaintext content. This document specifies the modes, the key material, and the configuration knobs that govern them.

End-to-end here means from one peer's Aura daemon to another peer's Aura daemon. It does not extend from your text editor into the peer process (endpoint security is below our trust boundary), nor does it extend across unrelated protocols (your chat messages are not encrypted by Aura).

Threat Scope

Encryption protects against:

Passive network eavesdroppers at any intermediate hop (ISPs, transit carriers, compromised Wi-Fi, cloud network fabrics).
Active on-path attackers attempting to substitute traffic. Peer-certificate pinning catches this even against adversaries who hold a CA.
A curious Mothership operator in federated mode. A Mothership with directory-only mode enabled cannot decrypt peer traffic, even if compelled to.

It does not protect against:

A compromised peer. The remote end of the tunnel sees plaintext by design.
Off-protocol leakage — screen sharing, backups of the working directory, clipboard sync.
Traffic analysis. TLS hides content, not metadata. An observer still learns that peer A is talking to peer B, roughly how much data flowed, and when.

Mechanism

Mode 1: relay (default)

In relay mode, peers connect to the Mothership over TLS and exchange function-body deltas through it. The Mothership:

Authenticates each peer via its issued JWT (see cryptographic design).
Verifies each sync payload's signature against the author peer's public key.
Stores the payload in its append-only logic-node store.
Forwards the payload to any other peer that subscribes.

Because the Mothership terminates TLS on both sides, it can read plaintext. This is the simplest architecture and the usual choice for teams operating their own Mothership — if you control the Mothership, the plaintext visibility is not a concern.

Mode 2: directory-only (federated)

In directory-only mode, the Mothership retains its role as identity and token issuer but drops out of the data path. Peers still register with the Mothership; peers still receive JWTs; but when peer A wants to send a function body to peer B, they open a direct TLS connection to each other.

Direct-peer connection setup:

Peer A queries the Mothership directory for peer B's advertised endpoint and public key fingerprint.
Peer A opens a TLS 1.3 connection directly to peer B's listen address.
The TLS handshake performs mutual authentication: A presents its peer cert, B presents its own. Each verifies the other's cert against the fingerprint obtained from the directory.
Data flows end-to-end. The Mothership sees none of it.

The Mothership still sees that peer A requested peer B's directory entry, and still sees summary statistics if peers periodically report them (disable-able). It does not see function bodies, intent free-text, or any payload.

TLS parameters

All connections — peer-to-Mothership and peer-to-peer — use TLS 1.3 with the AEAD-only cipher suite subset:

TLS_AES_256_GCM_SHA384
TLS_CHACHA20_POLY1305_SHA256
TLS_AES_128_GCM_SHA256

Key exchange is X25519 ECDHE; RSA key exchange is not offered. Forward secrecy is guaranteed by the handshake. Session resumption uses PSK tickets with a rotation interval of 24 hours.

Peer-certificate pinning

Each peer holds an Ed25519 identity key and, derived from it, an X509 certificate used in TLS. At join time, the Mothership records the peer's certificate fingerprint in the directory. On every subsequent connection, peers verify that the presented certificate matches the fingerprint. A mismatch is a hard failure with no fallback — there is no "trust on first use except this time" mode.

Pinning defeats the usual CA-based attack: an adversary who briefly holds a certificate from a public CA cannot substitute their certificate for a legitimate peer's, because the fingerprint in the directory does not match.

Rotation of a peer's certificate is handled via the Mothership: the peer uses its existing identity to request a new cert, the Mothership updates the directory, and all other peers receive the new fingerprint on next sync. During the overlap window both certs verify.

Encrypted-at-rest on the Mothership

In relay mode, the Mothership stores function bodies in its logic-node cache. By default this cache is on the host filesystem without application-layer encryption — we assume the Mothership operator has configured full-disk encryption and secured physical access. For deployments where even the Mothership operator should not be able to read the cache, enable application-layer encryption:

[mothership.storage]
encrypt_at_rest = true
# Keys derived from this seed; rotate by rotating the seed and re-encrypting
key_derivation_seed = "env:AURA_STORAGE_SEED"

The seed is read from an environment variable supplied at Mothership start, never stored on disk in cleartext. Without the seed, the cache is inaccessible. This is useful for Mothership deployments on infrastructure where the host admin differs from the Aura admin.

In directory-only mode, this setting is moot — the Mothership holds no function bodies to encrypt.

Listen endpoints and NAT

Peer-to-peer connections require that peers can reach each other on the network. For LAN-local deployments this is trivial. For distributed teams across NATs, peers publish listen endpoints that are routable via the corporate VPN; the Mothership directory records them.

Aura does not currently implement a TURN-style relay for NAT traversal in directory-only mode. Peers behind symmetric NAT without a routable path must either join via VPN or fall back to relay mode for those specific connections. A configurable hybrid — directory-only when direct connectivity is available, relay as fallback — is planned but not shipped.

Agent channel encryption

MCP agent traffic (from an AI coding agent's MCP client to the local Aura daemon) runs over localhost and is not encrypted in transit — there is no wire for an adversary to tap. Authentication is enforced via the agent's capability token (see agent permissions). If an MCP client runs on a different host than the Aura daemon (uncommon), the connection is promoted to TLS automatically.

Configuration

Default (relay) mode is the [mothership] section without any federation flag:

[mothership]
bind = "10.0.5.3:7443"
advertised_host = "aura.internal.example.com"

Directory-only federation:

[mothership]
bind = "10.0.5.3:7443"
advertised_host = "aura.internal.example.com"

[federation]
mode = "directory-only"
# Peers must publish a reachable endpoint; block peers that don't
require_direct_endpoint = true

[peer]
# Each peer publishes its listen endpoint to the directory
advertised_endpoint = "10.0.7.14:7444"

To verify at runtime that end-to-end encryption is in force:

aura sync status --verbose

Sample output in directory-only mode:

federation mode: directory-only
mothership:      10.0.5.3:7443 (reachable, TLS OK)
peers:
  peer-5f3a (alice):  direct TLS to 10.0.7.14:7444  [pinned]  OK
  peer-9b21 (bob):    direct TLS to 10.0.7.22:7444  [pinned]  OK
  peer-1a8e (carol):  FAILED (no direct path; peer relay fallback disabled)

mothership-plaintext-access: NO

The final line — mothership-plaintext-access: NO — is the compliance-relevant summary a regulator or auditor will ask for.

Limitations

TLS hides content, not metadata. An observer of encrypted traffic learns connection patterns, volumes, and timing. For projects where metadata is sensitive (e.g., a team's existence is itself confidential), route over a VPN or overlay network with traffic-shaping properties.
NAT traversal in directory-only mode is limited. Peers on restrictive networks may need to fall back to relay or to a VPN-provided routable path.
Pinning is only as good as the directory. If an attacker compromises the Mothership, they can inject a rogue fingerprint into the directory and future peers will pin to it. Protect the Mothership accordingly; see incident response.
Perfect forward secrecy depends on TLS 1.3 being honored. We refuse pre-TLS 1.3 connections by policy, but a misconfigured build from a fork could weaken this. aura self-verify detects toolchain mismatches that might accompany such a modification.
Directory-only mode trades a small amount of functional convenience for a meaningful security gain. In relay mode, the Mothership can serve as a durability anchor (it keeps a copy even if peers go offline). In directory-only mode, peer-to-peer delivery is required; if both the source peer and the recipient are offline simultaneously, the transfer waits.
Legal compelability differs from technical visibility. A jurisdiction's authorities may compel a Mothership operator to produce the directory even if they cannot compel production of plaintext they do not hold. The directory reveals who is on the team and when they connected; it does not reveal what they shared. Deployments with strong anti-correlation requirements should consider whether even the directory should be hardened further (short log retention on the Mothership, directory queries served without logging).
Performance characteristics differ between modes. Relay mode amortizes fan-out through the Mothership: a push from one peer to ten others costs the source peer one upload. Directory-only mode requires the source to open ten tunnels and push ten times. For teams below ~25 active peers this is rarely noticeable; beyond that, bandwidth planning should account for the difference.

Gotcha: TLS 1.3 with pinning is a strong guarantee provided the pin is bound to the right thing. A deployment that pins against a CA rather than the peer fingerprint regresses to standard WebPKI trust and loses the directory-backed protection. Verify your configuration with aura sync status --verbose and ensure each peer line reads [pinned], not [ca-trusted].