Add protocol v1: versioned, bounded frames (Hello, Welcome, Intent, IntentResult, environment/organism views, Close) carrying session, epoch and commit watermark, with an explicit little-endian canonical codec, a header-first FrameReader, seeded mutation tests and a libFuzzer target. SessionAdmission enforces world/region scope, grant lifetime and skew, single-use grants, one session per subject, epoch, replay, tick window and per-session rate. Dev identity is a 108-byte HMAC-SHA256 grant (PSA) that cannot be created or verified outside the dev environment. Transport security is TLS 1.3 only via pinned Mbed TLS 4.1.1 LTS with TLS 1.2, DTLS, tickets and PSK compiled out, AEAD suites, ECDHE groups and a pinned dev CA. Opt-in EVO_BUILD_NETWORK, new network CI suite. Sockets and region integration follow in M9.7. ADR-0082 records the decision. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
4.7 KiB
M9 dev session protocol
Decision: ADR-0082. Wire layout: dev-session-v1. Architecture: NETWORK_ARCHITECTURE. Scope: one engineering client and one authoritative dev region. Not the M10 multiplayer transport, not production identity, not a gameplay protocol.
sequenceDiagram
participant C as evo-client
participant T as TLS 1.3 (Mbed TLS)
participant A as SessionAdmission
participant R as Region host (M9.7)
C->>T: handshake, verify pinned dev CA + server name
C->>A: Hello{dev grant}
A->>A: HMAC verify, world/region, lifetime, single use, one subject
A-->>C: Welcome{session, epoch, server tick, commit watermark, limits}
R-->>C: EnvironmentView / OrganismView{session, epoch, tick, watermark, baseline}
C->>A: Intent{session, epoch, sequence, tick, vector}
A-->>C: IntentResult{admitted | rejected reason}
A->>R: admitted intention for scheduling (server decides outcome)
Layers and modules
| Layer | Module | Depends on |
|---|---|---|
| Wire codec, FrameReader | evo_network_protocol (protocol.hpp) |
client presentation values only |
| Session admission | evo_network_protocol (admission.hpp) |
codec, world identity |
| Dev grants (HMAC-SHA256) | evo_network_tls (dev_grant.hpp) |
PSA crypto (Mbed TLS) |
| TLS 1.3 channel | evo_network_tls (tls_channel.hpp) |
Mbed TLS, caller ByteTransport |
| Sockets, server/client adapters | M9.7 | this gate |
Nothing here links into evo_simulation, world stores or the region host yet.
EVO_BUILD_NETWORK is opt-in and requires cmake -P tools/prepare-mbedtls.cmake.
Trust and authority
- The client authors only Hello (an opaque grant) and Intent (sequence, tick and a signed vector of norm <= 1000). It cannot author position, energy, resources, genome, reproduction, death or presentation values.
- Views travel server -> client and are rebuilt through the presentation validators; a client never sends them.
- Every view and Welcome carries epoch and the durable commit watermark. Receipt
of bytes, admission for scheduling, simulation and durable outcome are distinct:
IntentResult::admittedis only the second. - Session ids are server-assigned counters. They identify, they do not authenticate; M9.7 binds each session to its TLS connection.
Admission rules
SessionAdmission is single-owner (the host serializes calls) and bounded:
at most 256 sessions and 65536 remembered grant ids by configuration limits.
Open: verified grant -> world/frame and region must match; lifetime <= configured maximum; not issued beyond clock skew in the future; not expired; grant id not seen before (remembered until its expiry; when the table is full, new grants are refused rather than forgetting live ones); the subject has no active session; capacity available. Reconnect = close + new grant.
Intent (status, first failing rule wins): unknown session; rate (every attempt by
a known session in the current window_ticks counts, accepted or not); epoch
(message and session must match the current ownership epoch; advance_epoch
makes all existing sessions stale); grant expiry; vector bound; sequence strictly
greater than the last admitted; tick in [server_tick, server_tick + window].
Rejected messages never advance the sequence.
Dev-only enforcement
DevGrantKey::import refuses stage and world0. The grant carries the marker
EVO-DEV-ONLY and a dev environment byte under the HMAC. The key is a 32-byte
secret from dev provisioning (M9.7: a dev-namespace Secret), never logged, never
in images. A leaked dev key compromises dev sessions only; rotation is a redeploy.
Failure behaviour
Decoding errors (ProtocolError) mean the peer is malformed: close with
malformed/unsupported_version and drop the connection. TLS errors latch per
channel; peer_verification means the server certificate did not chain to the
pinned CA or name. No error path retries automatically or falls back to plaintext.
Evidence
evo-network-tests (label network): round trips and an explicit little-endian
golden; header/payload rejection cases; byte-by-byte FrameReader reassembly and
early oversized rejection; 30,000-round seeded mutation fuzzing with canonical
re-encoding; dev grant environment refusal, bit-flip tag failures and key misuse;
admission scope/lifetime/reuse/duplicate/capacity rules and every intent status;
TLS 1.3 loopback with suite/version checks, 100 kB transfer, close_notify,
untrusted CA, wrong name, mismatched key, record tampering, transport failure and
plaintext rejection. evo-dev-session-fuzz is the libFuzzer target
(EVO_BUILD_FUZZER, Linux Clang). Results: engineering/VALIDATION.md.