quantumtunnel/docs/design.md

Design notes

Architecture

• chab3.py -- ChaCha20-Blake3 AEAD boxes, counter-nonce channels, CSPRNG.
• handshake.py -- the key-exchange cryptography. A Registration or Resumption object (two fully separate classes; the shared parts are free functions) holds one exchange's per-connection state -- ephemeral root, commitment, exchange secrets, the ad chain (a tiny _Chain class) -- and is disposed by the caller once the exchange completes; its secret fields are a candidate for SecureBuffer backing.
• sansio.py -- the protocol state machine (Session), the key store and its policies, traffic framing.
• ws.py -- SecSocket, a thin asyncio WebSocket pump over a Session.
• exceptions.py -- ProtocolError, in its own module so wrappers and applications can import it without the sans-io machinery.

Driving a session

session() with no message initiates ("alice"), receiving msg1 first responds ("bob"); results are bytes (wire messages to send) or signal objects. A Verification carries the out-of-band comparison digest -- fill .answer, pass it back. Registration gates its tail on the answers: the responder is asked after msg3 (his answer releases msg4), the initiator after msg4 (her answer releases msg5 and finishes her side); a False answer deletes the credential and the held message is never sent. Resumptions never prompt: the stored sas rides on Established and the parties may compare it whenever they wish, then Session.confirm() flags the credential verified or deletes it. Once established, traffic goes through the same dispatch: session(Message) encrypts a frame, session(frame) decrypts one back. Keeping everything on the dispatch -- rather than separate encrypt/decrypt calls -- is what allows in-band protocol messages and their own result patterns later (re-keying, post-close semantics).

Which handshake a session runs is determined by its credential: 32 bytes (bare shared) -> registration, credential-sized -> resumption. The initiator is constructed with its key id; the responder without one, identifying the caller by trying msg1 against every credential in the store -- an AEAD open per candidate, cheap even for many.

The key store

A mutable mapping (a plain dict works) of one credential per peer under an application-chosen id: either the bare 32-byte registration secret (given to both parties out of band; it IS the initial shared, unhashed; the kdf info strings provide all domain separation needed) or the composite written by the first successful registration:

idroot(32) | shared'(32) | peer_m(1184) | peer_x(32) | sas(4) | verified(1)

The rotation to shared' is derived when the exchange completes but only held in memory: the store swap waits for the key change -- the initiator swaps at her comparison answer, the responder when msg5 completes. Until then the registration secret keeps serving new connections, and a drop before the swap loses nothing but the session. Each swap is atomic: True and None swap the composite in (flagged verified / unverified), False deletes the credential instead. An unverified credential is never prompted again.

The swap is also the arbitration point for parallel registrations on the same registration key: only the first swap wins; a later one finds the key gone and fails with "registration key already spent" instead of overwriting. Re-provisioning after a deletion needs a fresh registration secret.

Every store write is a compare-and-swap against the credential the session loaded: with several connections in flight on one store, only the first to reach the atomic key change wins, and a loser's later burn/delete/flag-flip never touches a slot that changed underneath it; the verified-flag flip tolerates a parallel confirmation of the same credential (the flag byte is excluded from the comparison). The store is synchronously accessed, so these checks are atomic by construction, and it is only ever mutated in place; persisting it (after results or errors) is the application's business.

Burns

Invalid data inside an otherwise authentic box (bad kdf tags, a bad commitment reveal, low-order points, malformed bodies) burns the credential on the spot: the sender demonstrably knew the keys and misbehaved. AEAD failures and early disconnects instead change nothing -- they prove no key knowledge -- and the same registration secret can simply be tried again. A burn only touches the slot if it still holds the session's own credential: a parallel connection may have won the slot in the meantime.

Frame kinds

One kind byte heads every traffic box's plaintext. The kind is opaque to the state machine, with a single rule: kind 0 is reserved for in-band protocol messages (none implemented yet -- key rotation and the like will ride there, produced and consumed inside the dispatch); all other values are user types, delivered untouched as Message.kind.

The str/bytes typing is the WebSocket wrapper's business (ws.py): send() picks the kind from the object (str -> TEXT, bytes -> BINARY, a Message passes through), receive() maps it back. Applications wanting their own kinds (protobuf etc.) send/receive Message directly; a future third layer may take this mapping over from the wrapper, so other transports don't reimplement it.

Errors

Everything attributable to the peer, the wire, or protocol-level misuse surfaces as ProtocolError; the application action is always the same -- log and disconnect. The conversion happens at one point, the Session dispatch, which also owns the burn policy: chab3's WireError (unauthentic or truncated box) proves no key knowledge and burns nothing; any other ValueError/struct.error means invalid data inside a validly opened box -- the peer knew the keys and misbehaved, so the credential burns. handshake.py therefore raises no special types; its one exception is the inner boxes, whose WireError it reclassifies to a plain ValueError because an inner box sits inside an already valid outer one. Genuine bugs (TypeError, AttributeError) propagate untouched; chab3 raises WireError (a ValueError) for bad wire data and TypeError only for program bugs (too-small output buffers). A corrupt LOCAL store entry raises KeyError/struct.error from the constructor -- the caller's own data problem.

The WebSocket wrapper

SecSocket duck-types the websockets library connection (send/recv) and FastAPI/Starlette's WebSocket (accept/send_bytes/receive_bytes). The socket knows no protocol state: bytes results are sent, other results go to a handler registered for their type, and a Verification result is passed back to the session once its handler ran (the handler sets .answer, or returns the value). The Established result ends accept()/connect().

The out-of-band verification is just one registered handler:

async def verify(v: Verification) -> bool | None

True confirms, False rejects (the credential is deleted, the handshake fails), None skips (the default when no handler is registered). accept()/connect() return only after the answer: no data flows before it. Resumptions never prompt; the stored digest stays exposed as sock.session.verification for an optional later comparison (sock.session.confirm).

sock = SecSocket(ws, store, "peer-1", ad=b"myapp", handlers={Verification: verify})
await sock.connect()     # client side; accept() on the server side
await sock.send(b"data")
msg = await sock.receive()   # str | bytes | Message