End-to-End Encryption

End-to-end encryption (E2EE) encrypts each client-to-node link separately. The gateway only relays the encrypted traffic and cannot read it, so it is safe to run a gateway on an untrusted or internet-facing host. E2EE is off by default.

Enable

Set e2ee.enabled: true on every node and on each machine where you run the TUI or the CLI. In the mobile app, turn on End-to-end encryption for the connection. A gateway needs no setting, because it only relays the traffic.

# ~/.config/argus/config.yaml
e2ee:
  enabled: true

The same setting is available as ARGUS_E2EE_ENABLED=true. A node with E2EE on refuses to start if it cannot load its encryption key. It never falls back to plaintext.

Two modes

Both modes encrypt every link. They differ in whether Argus also checks which devices may connect.

Mode	What it does	Enable
TOFU / open	Encrypts every link. Trusts any device the first time it connects. No allow-list.	e2ee.enabled: true
Locked	Encrypts every link, and only lets approved devices and nodes connect.	above, plus argus lock init and pinned devices

TOFU (trust on first use) is the default once E2EE is on. Locked mode adds the allow-list, covered below.

Locked mode

In locked mode, only the devices and nodes you approve can connect. Approvals are stored in a trust log: a signed, append-only record that the gateway relays but cannot read or change.

Set up

# create the trust log. list every signer key, including this node's own.
# runs a preview until you pass --confirm:
argus lock init --confirm sigpub:<this-node> [sigpub:<other-node>...]

# authorize or revoke a device (node label, or a devpub: key):
argus lock sign <device>
argus lock revoke-device <device>

# add or remove a signer:
argus lock add-signer sigpub:<key>
argus lock remove-signer sigpub:<key>

# inspect state and history:
argus lock status
argus lock log

lock init needs your own signer key in the list and refuses without it. Run it without --confirm first to preview the signer set and the devices it would authorize. It reads the list of nodes from the gateway, so set gateway.url, or pass --gateway <url> --token <TOKEN>. --gen-disablements N creates N break-glass secrets. The default is 1.

A device that is not authorized yet stays connected to the gateway but opens no node channels. It opens them as soon as lock sign authorizes it, with no restart. A node with argus lock local-disable accepts any device, so an unauthorized device still reaches that node.

Key Formats

Every value you copy between machines is 32 bytes with a prefix that names its kind:

Prefix	What it is	Where it comes from
sigpub:	signer key	argus lock status on the signing node
devpub:	device (identity) key	argus lock status on that device
gen:	genesis hash (the trust root)	argus lock init, or argus lock pin
dis:	disablement secret	argus lock init, shown once
tip:	current chain tip, for audit	argus lock status / argus lock log

Copy keys from argus lock status on the machine itself, never from a label the gateway resolves. A hostile gateway can swap the key behind a label and authorize or revoke the wrong one.

Pin Devices

A pin ties a device to one trust log. Pin every device you rely on.

• Run argus lock pin on the device. It shows a 24-word fingerprint of the genesis the gateway is offering.
• Compare those words against the pin: line of argus lock status on a node already pinned to the right log. A full match proves the gateway offered the real genesis, not a fabricated one. Confirm only then.
• Already know the genesis? argus lock pin gen:<hex> skips the prompt.
• lock.genesis: in the config pins at boot, outranks the pin file, and is the only pin that holds without the gateway's cooperation.
• lock init auto-pins the machine it runs on (its node and its TUI). Pin every other device yourself.

Recover

• Quarantine. A device that sees a locked network but has no matching pin refuses all channels. Recover it with argus lock pin. A node recovers live; a TUI client needs an argus restart.
• Break-glass. argus lock disable <secret> turns off locked mode network-wide. The secret is shown once at lock init; store it offline. It does not release a quarantined device, so use argus lock pin or argus lock local-disable for that.
• Relock. A disabled log is permanent. Run argus lock init again for a fresh trust log, re-pin every device with argus lock pin, and re-authorize each client with argus lock sign devpub:<identity>.
• Unpin. argus lock unpin drops the pin and the local chain. A synced node quarantines at once and its live channels close.
• Pin conflict. If config lock.genesis and the pin file name different roots, argus refuses to start. Run argus lock unpin, or fix lock.genesis.

Detect a Bad Gateway

A compromised gateway cannot read or forge your traffic, but it can hide the trust log or show different nodes different versions of it.

• No quarantine does not mean the network is safe. A gateway can withhold the chain so a device never learns the network is locked. Only a pin you placed yourself is reliable. Pin every device.
• Split view. A gateway can show different nodes different branches of the chain. Argus reads the tip of each node over the authenticated channel. On a mismatch, Argus writes equivocation detected to its log, and the app shows a warning. To check by hand, run lock status on each node and compare the tip: fingerprints. Matching words mean that the nodes share one chain.

Revoke a Signer

If a signer key is compromised, revoke it with a co-signing ceremony that outvotes the compromised signer. This needs at least 3 signers; with fewer, use break-glass plus relock instead.

# start, on a signer node:
argus lock revoke-signer sigpub:<compromised> --replacement sigpub:<successor>

# co-sign, on another signer node:
argus lock revoke-signer --cosign <blob>

# finalize once quorum is reached:
argus lock revoke-signer --finish <blob>

• The chain forks just before the compromised signer's first action. Every entry after that point is erased and must be recreated, including legitimate ones.
• Only signers trusted at the fork point can take part. To include a newer signer, pick a later fork point with --fork-from; this preserves more of the revoked signer's entries.