feat(book): write proteus chapter

Author: coriolinus

cc-book/modules/ROOT/pages/proteus.adoc

@@ -1,16 +1,139 @@
 = Proteus
 
-// What the Signal Protocol is (double ratchet, forward secrecy, break-in recovery)
-// Why Wire built Proteus: a Signal-compatible implementation for the Wire protocol
-// The prekey model: how a recipient's prekeys allow a sender to open a session without them being online
-// One-to-one only: each conversation is a bilateral session; group messaging is n*(n-1) sessions
-// Why that doesn't scale: O(n²) messages per group update, no forward secrecy for large groups
-// Why Proteus is being deprecated in favor of MLS
-
-// == CoreCrypto's Proteus Interface
-
-// ProteusCentral and what it owns (identity, session cache)
-// Session lifecycle: proteus_session_from_prekey vs. proteus_session_from_message
-// Encrypt/decrypt, fingerprints, last-resort prekey
-// How Proteus state lives inside the same TransactionContext as MLS
-// Migration note: pointing users toward the CC9→CC10 migration guide
+Proteus is Wire's implementation of the https://signal.org/docs/[Signal Protocol]: a double-ratchet scheme providing forward secrecy and break-in recovery for one-to-one encrypted sessions.
+
+Proteus is intrinsically a direct protocol: every message is individually encrypted for each recipient.
+Groups in Proteus are a fiction managed collaboratively between the backend and the client; they do not exist at the protocol level.
+Encrypting a message for a group of _n_ clients requires sending _n_ individually encrypted copies.
+This effect is compounded by the fact that a logical user in the sense of a human is very likely to have multiple clients in terms of individual devices.
+This O(n²) overhead is manageable for small groups, but becomes expensive as they scale, and it was the primary motivation for adopting MLS.
+
+Proteus remains supported for backwards compatibility, but has not received direct development work in some time.
+Its implementaion is already feature-gated for easy removal, and is intended to be removed as soon as we can confirm that a sufficiency of clients have upgraded their conversations to MLS.
+
+== Initialization
+
+Before any Proteus operation, the Proteus subsystem must be explicitly initialized within a transaction:
+
+[source]
+----
+transaction_context.proteusInit()
+----
+
+This loads the device's Proteus identity from the keystore, creating it if it does not yet exist.
+All other Proteus methods will return an error if called before `proteusInit()` has succeeded.
+
+== Identity and Fingerprints
+
+A Proteus identity is a long-lived Ed25519 keypair tied to the device.
+CoreCrypto exposes three fingerprint accessors, each returning a lowercase hex string:
+
+`proteusFingerprint()`::
+  The local device's public key.
+  Remains stable for the lifetime of the keystore.
+
+`proteusFingerprintLocal(sessionId)`::
+  The local public key as seen from within a specific session.
+  Equivalent to `proteusFingerprint()` but scoped to a session for API symmetry.
+
+`proteusFingerprintRemote(sessionId)`::
+  The remote peer's public key within a session.
+  Can be used to verify the peer's identity out-of-band.
+
+`proteusFingerprintPrekeybundle(prekey)`::
+  Extracts the public key fingerprint from a serialized prekey bundle without opening a session.
+  Useful for verifying a peer's identity before establishing a session.
+
+== Prekeys
+
+Prekeys are the mechanism that allows a sender to open a Proteus session with a recipient who is offline.
+The recipient publishes a set of one-time prekey bundles to the delivery service in advance; the sender fetches one and uses it to bootstrap the session.
+
+CoreCrypto provides two ways to generate prekeys:
+
+`proteusNewPrekey(id)`::
+  Generates a prekey with an explicit numeric ID (a `u16`).
+  Use this when your app manages the prekey ID space itself.
+
+`proteusNewPrekeyAuto()`::
+  Generates a prekey with an automatically incremented ID and returns both the ID and the serialized bundle.
+  Prefer this unless you have a specific reason to control IDs manually.
+
+Both return a CBOR-serialized prekey bundle ready to upload to the delivery service.
+
+=== The Last Resort Prekey
+
+Proteus reserves prekey ID 65535 (`u16::MAX`) as a last resort prekey.
+Unlike one-time prekeys, the last resort prekey is never consumed — it stays in the keystore indefinitely so that a sender can always open a session even when all one-time prekeys have been exhausted.
+
+[source]
+----
+prekey = transaction_context.proteusLastResortPrekey()
+----
+
+The constant `proteusLastResortPrekeyId()` returns `65535` and can be used to exclude this ID when generating ordinary prekeys.
+
+== Sessions
+
+A Proteus session represents an established encrypted channel with one remote client, identified by a caller-supplied `sessionId` string.
+Session state is cached in memory and persisted to the keystore.
+
+There are two ways to establish a new session, depending on which side initiates:
+
+`proteusSessionFromPrekey(sessionId, prekey)`::
+  Used by the *sender* to initiate a session.
+  Takes the remote client's serialized prekey bundle (fetched from the delivery service) and creates a local session ready to encrypt.
+
+`proteusSessionFromMessage(sessionId, envelope)`::
+  Used by the *recipient* upon receiving the first message.
+  Decrypts the initial envelope, establishes the session, and returns the plaintext in a single step.
+
+Once established, a session can be checked for existence with `proteusSessionExists(sessionId)` and explicitly removed with `proteusSessionDelete(sessionId)`.
+Manual saves via `proteusSessionSave(sessionId)` are available but not normally required — sessions are persisted automatically when encrypting or decrypting.
+
+== Encrypting and Decrypting
+
+With a session established, encryption and decryption are straightforward:
+
+[source]
+----
+ciphertext = transaction_context.proteusEncrypt(sessionId, plaintext)
+plaintext  = transaction_context.proteusDecrypt(sessionId, ciphertext)
+----
+
+=== Batched Encryption
+
+Because a group message in Proteus requires one encrypted copy per recipient client, CoreCrypto provides a batched variant to reduce FFI round-trips:
+
+[source]
+----
+map = transaction_context.proteusEncryptBatched(sessionIds, plaintext)
+// map: { sessionId -> ciphertext }
+----
+
+This is more efficient than calling `proteusEncrypt` in a loop and should be preferred whenever sending to multiple sessions simultaneously.
+
+=== Safe Decrypt
+
+`proteusDecryptSafe(sessionId, ciphertext)` is a convenience wrapper that handles the common case where you do not know in advance whether the session already exists.
+It opens the session from the message envelope if necessary, then decrypts, in a single call.
+For high-volume decryption to an existing session, the plain `proteusDecrypt` call is slightly more efficient.
+
+== Error Handling
+
+Proteus errors are surfaced as a `ProteusError` with the following variants:
+
+`SessionNotFound`::
+  The requested session ID does not exist in the keystore or in-memory cache.
+
+`DuplicateMessage`::
+  The ciphertext has already been decrypted.
+  The double-ratchet discards keys after use, so replaying a message is always an error.
+
+`RemoteIdentityChanged`::
+  The remote peer's identity key no longer matches what was recorded when the session was established.
+  This typically indicates a device reset or, in the worst case, a key compromise.
+
+`Other { error_code }`::
+  A lower-level Proteus error that does not map to one of the above categories.
+  The numeric `error_code` corresponds to the https://github.com/wireapp/proteus/blob/develop/crates/proteus-traits/src/lib.rs[proteus-traits error table].