Run a non-blocking TLS 1.3 session server inside evo-server's loop: environment views come from the region's own field/terrain stores with an explicitly empty organism presentation; admitted intentions ride the next synthetic input (content unchanged) and return a durable no-effect outcome from the host's final acknowledgement, or not_committed when dropped. Sessions are bound to their connection, epochs close stale sessions, and connections have bounded output, input rate and deadlines. SessionClient and evo-client --connect consume one single-use grant per Hello (refusals before admission keep it), reset to a fresh baseline on every session, keep stale views visible and report in-flight intentions as unknown after loss. evo-dev-session generates dev credentials, grant bundles and runs a restart probe. The dev deployment gains a drill-time, loopback-only listener with an optional Secret, enforced by the policy check, and tools/ops/session-drill.sh. Protocol v1 gains IntentOutcome and the capacity close reason before any deployment. ADR-0083 records the maintainer-confirmed decisions; M8-dev/stage remains not passed and no cluster change was made. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
100 lines
5.2 KiB
Markdown
100 lines
5.2 KiB
Markdown
# M9 dev session protocol
|
|
|
|
Decision: [ADR-0082](../adr/0082-dev-session-transport.md). Wire layout:
|
|
[dev-session-v1](../../schemas/view/dev-session-v1.md). Architecture:
|
|
[NETWORK_ARCHITECTURE](../architecture/NETWORK_ARCHITECTURE.md). Scope: one
|
|
engineering client and one authoritative **dev** region. Not the M10 multiplayer
|
|
transport, not production identity, not a gameplay protocol.
|
|
|
|
```mermaid
|
|
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` |
|
|
| Non-blocking TCP | `evo_network_session` (`tcp.hpp`) | Winsock/POSIX |
|
|
| Session server and client | `evo_network_session` (`session_server.hpp`, `session_client.hpp`) | all of the above |
|
|
| Region integration | `apps/evo-server/session_bridge.hpp` | region host (read-only) |
|
|
|
|
M9.7 ([ADR-0083](../adr/0083-dev-region-sessions.md)) runs the session server in
|
|
`evo-server`'s loop: views from the region's real field/terrain stores (empty organism
|
|
presentation), admitted intentions riding synthetic inputs with durable no-effect
|
|
outcomes, client reconnect with fresh baselines. Operations:
|
|
[DEV_SESSION_OPERATIONS](DEV_SESSION_OPERATIONS.md). Nothing links into `evo_simulation`.
|
|
`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::admitted` is 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.
|