Implement M9.6 narrow secure dev-session protocol

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>
This commit is contained in:
dingo
2026-10-01 18:53:55 -04:00
co-authored by Claude Opus 5.5
parent 9bb147de82
commit 8fbe093cc8
39 changed files with 3200 additions and 27 deletions
+8 -1
View File
@@ -416,7 +416,14 @@ M9.7. Evidence in engineering/VALIDATION.md.
controller/ownership fields, identical rendering for identical phenotypes,
alive/dead/removed handling, budgeted detail with explicit truncation, and an
opt-in rectangle-only engineering inspector under ADR-0081. ImGui is not adopted.
Evidence in engineering/VALIDATION.md. Next gate: M9.6.
Evidence in engineering/VALIDATION.md.
**M9.6 status (2026-10-01):** dev session protocol v1 (versioned bounded frames,
session/epoch/commit watermark, explicit little-endian codec), session admission
(scope, single-use grants, one session per subject, epoch, replay, tick window,
rate) and dev-only HMAC grants refused outside `dev`, over a TLS 1.3-only channel
with pinned Mbed TLS 4.1.1 LTS under ADR-0082. Sockets and region integration are
M9.7. Evidence in engineering/VALIDATION.md. Next gate: M9.7.
**Goal:** a native desktop cellular viewer/controller with input, camera, renderer,
readable organism/environment views and a real development-server connection.
+16 -12
View File
@@ -2,19 +2,23 @@
## Current gate — 2026-10-01
M9.5 renders organisms and an engineering debug view
([ADR-0081](adr/0081-organism-presentation.md)). Organism presentations are
derived from M3 phenotypes and contain no controller, owner or level field, so
identical biology renders identically for players and NPCs. Death shows as a
remnant; removal is absence. Rendering is budgeted with explicit truncation; the
opt-in inspector draws biology gauges only. ImGui is not adopted. See
[ORGANISM_RENDERING.md](engineering/ORGANISM_RENDERING.md) and
[VALIDATION.md](engineering/VALIDATION.md). Remote Gitea execution of the
extended client CI stage remains unverified locally.
M9.6 defines the narrow secure dev-session protocol
([ADR-0082](adr/0082-dev-session-transport.md),
[DEV_SESSION_PROTOCOL](networking/DEV_SESSION_PROTOCOL.md)). Versioned bounded
frames carry Hello/Welcome/Intent/IntentResult/views/Close with session, epoch and
commit watermark; decoding is explicit and fuzzed. Session admission enforces
scope, single-use dev grants, one session per subject, epoch, replay, tick window
and rate. Dev grants are HMAC-SHA256 and cannot be created or verified outside
`dev`. The channel is TLS 1.3 only, using pinned Mbed TLS 4.1.1 LTS with TLS 1.2,
PSK and tickets compiled out. Opt-in via `EVO_BUILD_NETWORK`. Remote Gitea
execution of the new `network` CI suite remains unverified locally.
Next: **M9.6**, the narrow secure dev-session protocol. The app still shows a local
in-memory fixture (static organism population, environment water moves); no
ecology runs in the client and no deployment, rule or format changed.
Next: **M9.7**, sockets, server/client session adapters, dev secret provisioning
and a real connection to one authoritative dev region. No deployment, simulation
rule or persistent format changed in M9.6.
M9.5 added biology-derived organism rendering without controller labels
([ADR-0081](adr/0081-organism-presentation.md)).
M9.4 added owned revision-tagged environment presentations and explicit
missing/stale rendering ([ADR-0080](adr/0080-environment-presentation.md)).
+3 -1
View File
@@ -38,4 +38,6 @@ M7.2's [ADR-0059](0059-postgresql-bootstrap.md) accepts a scoped checksum-pinned
source build for the paired PostgreSQL server/client. The general cross-platform
package-manager comparison remains open. M7.4's [ADR-0061](0061-checkpoint-publication.md)
links system OpenSSL 3 libcrypto (already required by libpq TLS) for SHA-256 in the
Linux persistence adapter only.
Linux persistence adapter only. M9.6's [ADR-0082](0082-dev-session-transport.md)
accepts a scoped explicit-source, SHA-256-pinned Mbed TLS 4.1.1 build for the opt-in
dev session protocol (`EVO_BUILD_NETWORK`).
+2
View File
@@ -3,6 +3,8 @@
## Status
Transport proposed; server authority/no custom cryptography locked.
[ADR-0082](0082-dev-session-transport.md) applies this to the M9 dev session only
(TLS 1.3 over a stream with Mbed TLS 4.1.1); the M10 transport remains open.
## Context
+91
View File
@@ -0,0 +1,91 @@
# ADR-0082: Narrow secure dev-session protocol and transport security
## Status
Accepted for M9.6/M9.7 engineering development sessions only. It is a scoped
application of ADR-0017; the M10 realtime transport (QUIC/DATAGRAM vs DTLS plus
owned reliability) remains open. The dev identity is never valid outside `dev`.
## Context
M9 must connect a desktop client to one authoritative dev region. NETWORK_ARCHITECTURE
locks server authority, untrusted clients, no custom cryptography, explicit wire
decoding, short-lived scoped grants, replay windows and rate/byte caps, and requires
the maintained implementation, exact version, license, cipher configuration and
threat review to be named. Production identity (M10.3) does not exist yet; a test
identity must not be able to escape into stage or World0.
## Decision
**Transport security.** TLS 1.3 over a reliable byte stream (TCP in M9.7) with
**Mbed TLS 4.1.1** (LTS branch supported until March 2029; upstream BRANCHES.md and
release notes checked 2026-10-01), used under the Apache-2.0 option of its dual
license. The release tarball (bundling TF-PSA-Crypto) is pinned by SHA-256
`3359a349…375c98c`, matching upstream's published checksum file (same GitHub release
origin, so this proves integrity of what was reviewed, not independent provenance).
`tools/prepare-mbedtls.cmake` prepares it explicitly; `EVO_BUILD_NETWORK` opts in;
static libraries only; headless/server/client builds never evaluate it otherwise.
Owned build restriction (`third_party/mbedtls/evo_mbedtls_config.h`, enforced by a
compile-time check): TLS 1.2, DTLS, renegotiation, session tickets and TLS 1.3 PSK
modes are compiled out. Runtime profile: TLS 1.3 only; suites
TLS_AES_128_GCM_SHA256 and TLS_CHACHA20_POLY1305_SHA256; groups X25519 and
secp256r1; ephemeral key exchange only; no early data or resumption. The client
requires a server certificate chaining to a pinned dev CA and matching the
configured server name; the system trust store is not used. Clients present no
certificate: identity is the dev grant inside the channel.
**Dev identity.** A fixed 108-byte grant: `EVO-DEV-ONLY` marker, version, a dev
environment byte, grant id, subject, world/frame, region, issued/expiry seconds,
and an HMAC-SHA256 tag computed and checked (constant time) by PSA with a 32-byte
non-exportable key. `DevGrantKey::import` refuses any environment but `dev`.
`VerifiedGrant` is constructible only by verification. Admission enforces
world/region scope, maximum lifetime (default one hour), clock skew, single use
(remembered until expiry; fail closed when full) and one session per subject.
Reconnect needs a fresh grant. This is not an account system.
**Protocol v1** (`schemas/view/dev-session-v1.md`, include/evo/network/protocol.hpp):
12-byte header (magic, version, type, zero flags, length <= 256 KiB) and seven
messages: Hello, Welcome (session, world/frame, region, epoch, server tick, commit
watermark, limits), Intent (session, epoch, sequence, tick, bounded vector),
IntentResult, EnvironmentView and OrganismView (session, epoch, server tick, commit
watermark, baseline plus the M9.4/9.5 presentations), Close. Fields are explicit
little-endian; decoders are bounds-checked and views are rebuilt through validated
presentation constructors. Unknown versions, types, flags, required features and
enum values reject. A streaming FrameReader validates headers before buffering
payloads. Admission orders checks: rate (every attempt counts), epoch, expiry,
vector norm <= 1000, strictly increasing sequence, tick window. "Admitted" means
eligible for scheduling, never simulated or durable.
## Alternatives considered
| Option | Disposition |
|---|---|
| System OpenSSL 3 (already linked by the Linux persistence adapter) | Strong option for Linux servers; no equivalent on the Windows client without a separate Perl/NASM build or a second TLS stack (Schannel). One stack on both ends is simpler for this scope. |
| Mbed TLS 3.6.7 LTS | Support ends March 2027, within the expected M9-M10 lifetime. |
| QUIC library (e.g. msquic) | Fits M10's datagram questions; large dependency and its own TLS integration before any realtime measurements exist. Deferred to M10.1. |
| libsodium primitives with an owned handshake | Requires designing key exchange/authentication: rejected by ADR-0017. |
| Plain TCP for dev | Unauthenticated protocol could escape into production; rejected. |
| Protobuf/FlatBuffers codec | Codegen dependency for seven small messages; explicit codec is reviewable and fuzzed. |
No performance comparison was measured; the choice rests on maintenance window,
platform build (CMake, no Perl/Python needed for release tarballs), license and
attack-surface reduction.
## Benefits
Maintained AEAD/ECDHE implementation with a reduced compiled surface; explicit,
fuzzed, canonical codec; replay/rate/epoch admission testable without sockets; dev
identity unusable outside dev by construction.
## Costs
Static crypto library build (~2.7 MB of static archives on MSVC), certificate/key
management for the dev region, TCP head-of-line behaviour (acceptable for one dev
engineering client, not measured for M10).
## Risks
Dev CA/HMAC key leakage allows dev impersonation (dev only; rotate by redeploying
secrets). Session ids identify but do not authenticate; M9.7 must bind a session
to its TLS connection. Rate limits are per message, not per byte; M9.7 adds
connection byte/time limits. Upstream advisories require prompt pin updates (the
July 2026 releases fixed several TLS issues, some in code compiled out here).
## Consequences
M9.7 adds sockets, server/client session adapters, dev secret provisioning and
reconnect semantics. Pin upgrades change version, hash and this ADR together and
rerun the network suite. M10 reopens transport selection with measurements.
+1
View File
@@ -16,6 +16,7 @@ Maintenance statements are shortlist evidence, not measured suitability.
| NATS JetStream | Upstream streams/consumer docs; C-client boundary | Service RAM/disk/fan-out must justify broker | Audit server/client release licenses; proposed |
| prometheus-cpp / Otel C++ | Client vs broad SDK; upstream stability docs | Export overhead/cardinality/size/failure measurement | MIT / Apache-2.0; deferred |
| mp-units | Modern dimensional APIs; test compiler diagnostics | Compile time/binary footprint and conversion clarity | MIT; deferred |
| Mbed TLS 4.1 LTS | Supported to March 2029; CMake build without Perl/Python from release tarballs; PSA crypto API | ~2.7 MB static archives (MSVC Release); TLS 1.2/DTLS/PSK/tickets compiled out | Apache-2.0 OR GPL-2.0-or-later (Apache taken); adopted for M9 dev session only (ADR-0082) |
| SplitMix64 algorithm | Author's published fixed transition; explicit state | Small constant work, 8-byte state; noncryptographic | Reference attribution in ADR0007; proof only |
Every experiment records version/hash, compiler/OS, representative workload,
+1
View File
@@ -93,3 +93,4 @@ design. No unadopted candidate is a link dependency of the proof.
- [ADR-0079: Camera and input intentions](0079-camera-and-input-intentions.md) - local-mm projection, bounded sequence/tick intentions, focus/UI capture and explicit host event ordering.
- [ADR-0080: Environment presentation](0080-environment-presentation.md) - owned revision-tagged environment presentations, ordered freshness and bounded explicit missing/stale rendering.
- [ADR-0081: Organism presentation](0081-organism-presentation.md) - biology-only organism cells without controller labels, budgeted rendering with explicit truncation and an engineering gauge inspector; ImGui deferred.
- [ADR-0082: Dev session transport](0082-dev-session-transport.md) - TLS 1.3-only Mbed TLS 4.1.1 LTS (pinned, compiled-down), dev-only HMAC grants, versioned bounded protocol v1 and session admission for M9.
+3 -1
View File
@@ -1,7 +1,9 @@
# Authoritative network architecture
Status: locked server authority and untrusted clients; transport/reliability are
proposals for M10. M0 has no networking. Steam distribution follows later through
proposals for M10. The scoped M9 dev session (TLS 1.3, protocol v1, dev-only grants)
is specified in [DEV_SESSION_PROTOCOL](../networking/DEV_SESSION_PROTOCOL.md) and
ADR-0082. M0 has no networking. Steam distribution follows later through
an identity-provider adapter; core account IDs are independent of Steam IDs.
```mermaid
+56
View File
@@ -3389,3 +3389,59 @@ Limits: Docker/Gitea execution of the extended `ci-client` stage was not observe
locally. No headless source changed; no full headless suite or TSan rerun. The
fixture population is static presentation data, not ecology. No network, database,
deployment, persistent format or simulation rule changed.
## M9.6 narrow secure dev-session protocol — 2026-10-01
Implemented ADR-0082, DEV_SESSION_PROTOCOL.md and schemas/view/dev-session-v1.md:
protocol v1 codec and FrameReader, SessionAdmission, dev-only HMAC grants and a
TLS 1.3-only channel over caller byte transport, using Mbed TLS 4.1.1 LTS.
Dependency evidence (2026-10-01): upstream BRANCHES.md lists 4.1 as LTS supported
until March 2029 (3.6 until March 2027). `mbedtls-4.1.1.tar.bz2` SHA-256
`3359a349e23db3d5536fcee032ae7b2ecbfc08972fab643089b5cbf2a375c98c` matched the
release's published sha256sum file (same origin). License: Apache-2.0 OR
GPL-2.0-or-later; Apache-2.0 taken, copied to third_party/mbedtls/LICENSE. Release
tarballs need no Python/Perl with programs/tests off. Windows extraction skipped
one symlink inside an unused upstream PQC example directory. MSVC Release static
archives: mbedtls 647 KB, mbedx509 376 KB, tfpsacrypto 1.65 MB; the network test
executable is 584 KB. A compile-time check proves the owned TLS 1.3-only
configuration (TLS 1.2, DTLS, renegotiation, tickets, PSK modes removed) applies.
Executed:
- Windows MSVC 19.44 Release: `tools/windows-check.ps1 -Preset network -Action
check` 1/1; `-Preset client` 5/5 after moving the SDL-free client value targets
to the top-level CMake file.
- Linux GCC 14 Release (`build/network-linux`): network suite passed with no
owned-code warnings; existing client build 7/7.
- Clang 19 Debug ASan/UBSan (`build/network-asan`): network suite passed.
- libFuzzer (`evo-dev-session-fuzz`, ASan/UBSan, empty seed corpus, max_len 8192):
1,272,671 runs in 61 s (cov 685, 158-entry corpus), then 269,854 runs in 31 s
after the analysis fixes; no crash, leak or canonical re-encoding abort.
- Seeded mutation fuzz inside the suite: 30,000 rounds, 8,208 accepted frames, each
re-encoded byte-identically.
- Tests also cover: explicit little-endian Intent golden; truncated, bad magic,
version 0/2, unknown type, flags, oversized, trailing and wrong-type frames;
unsupported required features; grant length bounds; invalid enum bytes; views
failing presentation rules; 257-cell counts; byte-by-byte reassembly and early
oversized-header rejection with latching; dev keys refused in stage/world0,
short/zero keys, every single-bit grant change rejected, foreign key, moved-from
key; admission world/region/lifetime/skew/expiry/reuse/duplicate/capacity/
grant-table rules, every IntentStatus, rate windows and epoch advance; TLS 1.3
loopback (version, suite, frame and 100 kB transfers with 700-byte partial
writes, close_notify), untrusted CA, wrong server name, mismatched private key,
bad PEM, tampered record, transport failure and plaintext rejection.
- clang-tidy 19 (warnings as errors) on the seven network translation units:
passed after restructuring enum decoding to cast only validated bytes, reading
the latched TLS error once, checking a test return value, and annotating
intentional invalid-enum/use-after-move test inputs. Repository clang-format
passed. CI path-selector fixtures passed including the new `network` suite.
- Headless: a fresh GCC 14 Release configure with default options contained no
Mbed TLS or SDL references; `evo-sim` replay of seed 123456 / 8 entities / 1000
ticks gave unchanged `d61ad5bf0c928c76`, `replay_verified=true`.
Limits: the `ci-network` Docker stage and Gitea matrix entry were not executed
locally. No sockets, server integration, secret provisioning or deployment exist
yet (M9.7). TLS interoperability was tested only between Mbed TLS endpoints. No
performance or latency measurement is claimed. Certificates in tests are
throwaway; no dev CA or HMAC key was created or committed.
+93
View File
@@ -0,0 +1,93 @@
# 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` |
| 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::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.