SessionMigration

Overview

What it is: Session migration is the process by which two devices maintain their encrypted conversation when one of them changes networks — moving from WiFi to mobile data, switching towers, or changing IP address. The session key is still valid; only the transport path needs to change.

Who's involved: Two trusted peers with an established Ready session. One peer (the migrator) detects the network change. The other peer (the recipient) receives an inbound signal that the migrator has moved.

What success looks like: Both devices are back to SessionStatus.Ready with the same session key and the same PeerSecret they had before the migration. No new handshake has run. No secret has been rotated. Messages queued during the transition deliver automatically.

What failure looks like: Migration pings fail on all paths within the migration window. The session evicts on both sides. Full re-establishment is required — see PeerSessionEstablishment Phase 3b-SessionRecovery. This is recoverable but involves a full handshake and new secret generation.

Why this process exists separately from session establishment

When a peer changes networks, the instinct is to treat it like a new connection — tear down the old session, build a new one, run the full handshake. That is the wrong approach and it is the root cause of the most persistent bugs in this system.

The session key was derived from the relationship key (RK) and committed on both sides. It has not been invalidated. The PeerSecret was committed during the last successful handshake and both sides hold the same value. Running a new handshake generates a new PeerSecret — and if two handshakes run concurrently (which happens when both sides independently try to reconnect), each side commits the result of whichever one arrived last. Those results differ. The secrets diverge. Every subsequent ping from the diverged side fails PeerSecret resolution. The connection is permanently broken until restart.

The asymmetry problem

P2P without a server means the two devices are always in different states during a network transition. This asymmetry must be represented explicitly in the state model — shared states that mean different things depending on which side you are on are the source of guard logic failures.

The migrating device (outbound) knows its network has changed. It knows its key is still valid. It is firing migration pings to find a new transport path to the peer. It should not attempt a new handshake — it is waiting for the peer to acknowledge its new address.

The receiving device (inbound) receives a migration ping from a peer it already has a session with. It knows the peer has moved networks. Its key is still valid. It needs to reach the peer at their new address. It also should not run a handshake — the session is already established.

User Journey

Participants

Full Sequence Diagram

Both direct and relay paths shown. Proposed state values marked with *.

Phase Breakdown

Key Design Decisions

Why session key and PeerSecret are preserved across migration

The session key is derived from the relationship key (RK) and session ID — both stable across network changes. Running a new handshake when the key is still valid risks race conditions and is the root cause of the secret divergence bug. The rule: the session key changes only when the session is evicted (None) or when MaxSessionAgeHours forces rotation.

Why LastSuccessfulSecret is used in migration pings, not PeerSecret

PeerSecret may be a value committed on one side but not yet confirmed on the other. LastSuccessfulSecret completed a full ShareStatus(Ready) exchange — it is guaranteed to be findable in the receiving device's AB.

Why IsTransportOnlyReconnect must be a payload flag, not inferred from state

DC's TryDirectEndpointsAsync cannot infer from session state alone whether a handshake is needed after a successful ping. A ping succeeding at SessionStatus==Confirmed is ambiguous — cold start or migration reconnect. The flag makes intent explicit through the async call chain.

Why ReconnectingOutbound and ReconnectingInbound are separate PeerStatus values

The two roles have different guard requirements. ReconnectingOutbound must block PresenceConnect from firing. ReconnectingInbound must allow ConnectPeerAsync through even when SessionStatus==Ready. Using a single state or reusing Degraded means guard logic cannot differentiate and one invariant will be violated.

SyncActions Used

Policy Keys That Affect This Process

Edge Cases and Failure Modes

Test Plan Anchors

Open Questions