Module session 

Directional session keys, AAD-bound frames, replay protection, and deadlines for IPC connections (WBS-509/510/511, TD-ROB-16).

Wire design (v1):

• Handshake — the CLIENT sends the first frame (the same 4-byte length-prefixed framing as everything else): a JSON SessionHello { v: 1, cr: <hex 32B client random> }. The server replies SessionAccept { v: 1, sr: <hex 32B server random> }.
• Key schedule (WBS-509) — HKDF-SHA256 with the daemon auth token as IKM and client_random || server_random as salt yields two DIRECTIONAL 32-byte keys (c2s, s2c); the client encrypts with c2s, the server with s2c, so a frame replayed into the opposite direction (reflection) fails authentication.
• Frames (WBS-510) — nonce 4 zero bytes || u64 BE counter and AAD SPIS || proto(u16 LE) || direction(u8) || counter(u64 LE): the ciphertext is bound to the protocol, the direction, and the counter.
• Replay (WBS-511) — each direction’s counter must be STRICTLY increasing; a duplicate or lower counter is refused before delivery.
• Deadlines — every frame read is bounded by SESSION_READ_DEADLINE (stalled peers cannot wedge the other side); frame bounds stay at MAX_MESSAGE_SIZE.

Compatibility: legacy (pre-session) clients speaking plaintext envelopes are accepted in PLAIN mode when the server negotiates (the first frame is not a SessionHello); plain mode is the ADR-007 migration window and is removed in 1.0. New clients ALWAYS negotiate.

Structs

SessionAccept

Handshake frame (server → client).

SessionCrypto

Session crypto for ONE connection endpoint: seals in the endpoint’s send direction, opens in the peer’s.

SessionHello

Handshake frame (client → server).

Enums

Direction

Which direction frames flow in. Directional keys (WBS-509): the client encrypts with c2s, the server with s2c.

Constants

SESSION_PROTO_VERSION

Session protocol version.

SESSION_READ_DEADLINE

Bound on every frame read (deadlines, WBS-511).

Functions

client_random_of

derive_directional_keys

Derive the two directional keys (WBS-509). token is the daemon auth token (32 random bytes, hex); the session randoms bind the keys to one specific session.

is_session_hello

True when the first plaintext frame is a SessionHello (server-side negotiation detection). A plaintext envelope frame is NOT a hello.

new_accept

Fresh server accept + its random.

new_hello

Fresh client hello + its random (kept by the client for key derivation).

parse_accept

parse_hello

server_random_of