Session protocol core
Creates and expires invitations, approves exact device keys, owns MLS group state, rejects replay, and manages local encrypted state.
Architecture
The clients keep the keys. Each support service gets one narrow job.
Clients own the session keys and decide membership. Identity providers supply evidence, mailboxes hold bounded ciphertext, and transports carry opaque envelopes. Opaque framing is content-agnostic; it does not itself prove encryption. Replacing one service should not change the authority of another.
Three services support the conversation without owning it.
Each boundary exposes only the authority needed for one job, even when a provider or transport changes.
Admission
Checks whether one exact device key may be considered. The prototype supports private capability invitations; other evidence types come later.
may approve one KeyPackageRendezvous mailbox
Temporarily stores bounded ciphertext in mailboxes addressed by separate secret capabilities.
may retain ciphertextEnvelope delivery
Moves opaque envelopes. The memory adapter supports deterministic adverse tests, while the Iroh adapter provides experimental connected FastV1 delivery. Offline, durable, Private, and production profiles come later.
may move opaque bytesA join request passes through five guarded steps.
Each step owns the exact value it checked. A later caller cannot swap the device key or treat successful delivery as proof of membership.
- 1.0 · parse
Reject bad input before it reaches state.
Oversized, malformed, non-canonical, unknown-version, expired, or context-mismatched objects stop here.
Ownersession-protocol - 2.0 · verify
Tie the proof to one invitation and one device.
The verifier owns the exact parsed KeyPackage and checks its invitation, challenge, replay context, credential identity, leaf key, version, and ciphersuite.
Owneradmission-capability - 3.0 · decide
Show Alice enough evidence to approve or reject.
The approval view cannot add a member. The provider keeps the proof, replay reservation, and exact one-shot MLS input.
Seamsession-admission - 4.0 · commit
Add the approved device once.
The MLS adapter consumes the approved value, creates Add and Welcome, advances the group, and later protects messages, updates, and removal.
Ownersession-crypto-mls - 5.0 · deliver
Retry delivery without adding the device twice.
The SQLCipher laboratory commits the MLS snapshot, replay state, consumed invitation, decision, and encrypted Welcome outbox as one transaction, then reloads that authorization state after restart. Production key custody and stale-snapshot rollback resistance remain open.
Stateimplemented laboratory
Each mailbox key grants one action.
Deposit, receive, acknowledge, and rotate use separate capabilities. Knowing a delivery identifier never grants permission to delete it.
How the Rust code maps to those jobs.
Each crate implements a narrow protocol or storage boundary. The names below describe tested laboratory components, not a finished security product.
- Wire + lifecycle
session-protocol·session-core- implemented in memory
- Admission
session-admission·admission-capability·session-crypto-hpke- capability profile only
- Group security
session-crypto·session-crypto-mls- two-party lifecycle
- Delivery
session-transport·transport-memory·transport-iroh- experimental connected FastV1
- Transactions + storage
session-inviter-transaction·session-storage·storage-sqlcipher- durable authorization laboratory
- Headless composition
sessionctl- retained integration evidence
Use the architecture document for exact contracts.
This page provides the mental model. The repository document defines the detailed invariants, object contracts, and current evidence boundary.
Open architecture ↗