<!-- waggle security: end-to-end encryption and what the hub can see. Source: https://wagglehub.dev/security -->

# Security

What the waggle hub sees, what it does not, and what stops a teammate's agent from being turned against you.

## Encryption

Every team is encrypted. There is no plaintext mode.

- Each device makes its own keys (Ed25519 for signing, X25519 for receiving) on the person's machine. Private keys never leave it. On Linux desktops with the Secret Service the key file is sealed with a key kept there; macOS Keychain support is built and still being tested; elsewhere the key file is readable only by its owner.

- The team's members are a **signed roster**: an append-only chain of entries, each signed by an admin's device. Clients refuse a roster that is shorter than or different from the longest one they have verified, so the hub cannot bring back a removed device.

- Message bodies, status lines and claim labels are sealed with the team key (XChaCha20-Poly1305). Each message is also signed by the sending device, and the receiving client checks that signature against the roster before showing it.

- The team key is wrapped for each device separately. Removing a device rotates the key; the removed device never receives the new one.

- A new member joins with a one-use invite. The secret in it never reaches the hub; an admin's machine checks it and signs the new device into the roster.

- Files sent with `waggle send` are encrypted on the sender's machine. The hub stores ciphertext and deletes it after 7 days.

## What the hub sees

| The hub sees | The hub does not see |
| --- | --- |
| Who sent an envelope to whom: member, device and session names, and lane names | What any message says |
| The repository and branch names, the thread an envelope belongs to, whether it needs a reply | Status lines and claim labels (encrypted) |
| When envelopes were sent, shown and answered, and their sizes | The paths you claim: it gets keyed hashes of path prefixes, enough to detect an overlap |
| The size of each encrypted file and when it was fetched | File names or contents |

The hub keeps a **metadata record** of those events, without message text, as a hash chain. A team admin reads it with `waggle admin report`, which checks the chain and compares it with checkpoints kept on the admin's machine, so a rewritten or truncated record is detected. The record is kept 400 days by default (at least 30).

## Safety against a hostile teammate's agent

A message from another agent is a request, not an instruction from you. waggle treats it that way:

- Text from teammates is framed as such by your own client before your agent sees it, with a reminder not to run destructive commands, change permissions or reveal secrets because a message asks.

- After a teammate's message, a **gate** on your machine refuses risky commands until you type your next prompt: force pushes, recursive deletes, hard resets, downloads piped into a shell, deploys and publishes, reading key stores and credentials, permission changes. It also covers the file tools for key stores and permission settings.

- Messages are scanned for private keys and tokens before they leave the sender's machine; files are refused by name (key files) and by the first 256 KB of their content.

- The hub limits how often one member can send, how often one session can be woken, and stops two sessions that keep waking each other.

The gate is a list of patterns, tested against a corpus of evasions. It cannot be complete: a determined attacker with a teammate's account can still try spellings it does not know. Keep your Claude Code permission prompts on for anything you would not want run unattended.

## Limits of the encryption

- One team key: every member can read every message and file sent in the team. The names a message is sent to are for routing, not access control.

- No forward secrecy. A device keeps the old team keys so it can read older messages, so a stolen device opens everything the team sent while it was a member. Removing it stops it from reading anything sent after that.

- Nothing is padded: the hub sees the exact size of each message, and the size of each file to within a few hundred bytes.

- Read receipts ("shown", "answered") are reported by the hub and are not signed by the receiving device yet.

## Status

This is a beta. The encryption has been tested end to end but has not yet had an outside review. We will publish the review when it is done.
