Reference / Protocol overview

Protocol overview

A short tour of how lwis moves a capture, for the curious and for auditors. The normative details live in the repository's design documents and in crates/lwis-core/API.md.

Planes

• Signal plane: small sealed messages over ntfy topics (fixed size, authenticated, replay-protected).
• Blob plane: encrypted images, either as ntfy attachments or uploaded with presigned URLs to object storage through the drop API.
• Doorbells: encrypted, fixed-size Web Push messages (RFC 8291) that only tell a device to check for messages.

Pairing a device with a machine

1. The machine shows a pairing link: its keys, the planes to use and a one-time topic.
2. The device and the machine run a commit–reveal exchange, so neither side can choose its values after seeing the other's.
3. Both derive the same 6-digit code; the user confirms it on both screens.
4. They derive session keys, which are rotated regularly (rekey), and topics for each direction.

A capture is sealed with a fresh key, uploaded, and its key is sent inside a sealed signal message. The machine fetches, decrypts and delivers it to the chosen agent session, then the blob is deleted.

Identities and contacts

• An identity is a root key (I), a card-signing key (C), a separate recovery key (RK, backed by the 24-word kit) and per-device endpoint keys with 30-day certificates.
• A card is a sealed, signed description of your endpoints, stored at an unguessable location; the card link carries the key to open it.
• Following someone starts with an X3DH-style first message to their signed prekey. It mixes four Diffie–Hellman results, including one between the two endpoint keys, so a stolen prekey alone can't impersonate a sender. The sender's identity is encrypted in that first message.
• Sessions then use per-message keys (a hash ratchet in each direction), with a periodic Diffie–Hellman rekey.
• Safety numbers (60 digits, or 8 emoji words) let two people verify each other's keys.

Group sends

One encrypted object, uploaded once, with its readers committed at upload time. Each reader gets its own sealed message with the key and a signed download ticket (good for a few download attempts). The object is deleted a few minutes after every reader has fetched it.

Device links

A browser linked to your phone gets its own endpoint key and a certificate from the phone; it never holds the identity keys. Linking uses the same commit–reveal and 6-digit code as pairing.

Cryptography

X25519, Ed25519, HKDF-SHA-256, AES-256-GCM, SHA-256 and SHA-512, P-256 (Web Push doorbells and VAPID), BLAKE2b (for minisign), Argon2id (the registration proof of work; share links use a lighter SHA-256 one). See How lwis protects you for what this does and doesn't protect.