Module pair_session 

Staged pair session for MCP.

Splits the magic-wormhole pair flow (cli::pair_orchestrate) into discrete stages so an MCP server can drive it across multiple JSON-RPC tool calls.

State machine:

    pair_session_open
           │
           ▼
   ┌─Opened ─────────┐
   │  (peer not in)  │  pair_session_try_sas (idempotent poll)
   └─────────────────┘
           │ peer's SPAKE2 msg arrives
           ▼
    SasReady (sas + aead_key cached)
           │ user types digits → pair_session_confirm_sas
           ▼
    Confirmed
           │ pair_session_finalize
           ▼
    Finalized (peer pinned, relay coords saved)

 Aborted = SAS mismatch / TTL expired / peer aborted (terminal, removed from store)

Concurrency: each session is keyed by its relay pair_id (unique per pairing). Sessions are independent — pairing with N peers concurrently creates N sessions in the store, each with its own pair_id at the relay and its own Mutex<PairSessionState>. No cross-session locking.

Structs

PairSessionState

One in-flight pair session held in the MCP server process.

Constants

SESSION_TTL

Session evicted after this much wall time. 10min covers human-pace OOB code-phrase sharing (voice/text) plus AEAD bootstrap exchange comfortably, matches the relay pair-slot TTL ceiling, and forces a fresh pair_initiate if a session has been abandoned.

Functions

derive_code_hash

Insert a fresh session, returning the public session_id. SHA-256 hex of the domain-tagged code phrase. Both the host and guest derive the same value from the shared code, and the relay uses it as the pair-slot lookup key.

init_self_idempotent

MCP-callable init: idempotent if already inited under the same handle, errors on different-handle conflict, accepts optional –relay binding.

pair_session_confirm_sas

Stage 3. Validate the user-typed digits against the cached SAS.

pair_session_finalize

Stage 4. Seal+exchange bootstrap, AEAD-open peer’s, pin peer.

pair_session_open

Stage 1. Open a pair session at the relay.

pair_session_try_sas

Stage 2. Try to advance a session to SAS-ready. Single non-blocking poll of the relay. Idempotent: re-calling after SAS is cached returns the same digits without further network I/O.

pair_session_wait_for_sas

Stage 2 helper. Bounded loop wrapping try_sas. Used both by CLI (long timeout, blocking) and MCP (short timeout, fall through to async poll).

restore_pair_session

Reconstruct a PairSessionState from persisted fields without any network I/O. The caller (typically the daemon’s cleanup_on_startup) has already recovered seed, code, code_hash, pair_id, slot info, and role from the on-disk pending-pair file; this builds an in-memory state that can resume pair_session_try_sas from where the prior daemon left off.

store_get

Look up a session by id. Returns None if missing or evicted.

store_insert

store_remove

Remove a session. Used after finalize, abort, or TTL eviction.

store_sweep_expired

Sweep expired sessions. Called opportunistically before each public op.