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
+528
View File
@@ -0,0 +1,528 @@
#include "evo/network/protocol.hpp"
#include <algorithm>
#include <bit>
#include <utility>
namespace evo::network {
namespace {
constexpr std::uint8_t last_type = static_cast<std::uint8_t>(MessageType::close);
constexpr std::uint8_t last_status = static_cast<std::uint8_t>(IntentStatus::rate_limited);
constexpr std::uint8_t last_reason = static_cast<std::uint8_t>(CloseReason::server_shutdown);
constexpr std::uint8_t last_presence = static_cast<std::uint8_t>(client::FieldPresence::present);
constexpr std::uint8_t last_moisture = static_cast<std::uint8_t>(world::MoistureStatus::available);
constexpr std::uint8_t last_state = static_cast<std::uint8_t>(client::OrganismState::dead);
class Writer {
public:
void u8(std::uint8_t v) {
bytes_.push_back(v);
}
void u16(std::uint16_t v) {
put(v, 2);
}
void u32(std::uint32_t v) {
put(v, 4);
}
void u64(std::uint64_t v) {
put(v, 8);
}
void i16(std::int16_t v) {
u16(std::bit_cast<std::uint16_t>(v));
}
void i64(std::int64_t v) {
u64(std::bit_cast<std::uint64_t>(v));
}
void raw(std::span<const std::uint8_t> v) {
bytes_.insert(bytes_.end(), v.begin(), v.end());
}
[[nodiscard]] std::vector<std::uint8_t> take() {
return std::move(bytes_);
}
private:
void put(std::uint64_t v, int count) {
for (int i = 0; i < count; ++i)
bytes_.push_back(static_cast<std::uint8_t>(v >> (8 * i)));
}
std::vector<std::uint8_t> bytes_;
};
// Bounds-checked little-endian reader; the first failure is sticky.
class Reader {
public:
explicit Reader(std::span<const std::uint8_t> bytes) : bytes_{bytes} {}
std::uint8_t u8() {
return static_cast<std::uint8_t>(get(1));
}
std::uint16_t u16() {
return static_cast<std::uint16_t>(get(2));
}
std::uint32_t u32() {
return static_cast<std::uint32_t>(get(4));
}
std::uint64_t u64() {
return get(8);
}
std::int16_t i16() {
return std::bit_cast<std::int16_t>(u16());
}
std::int64_t i64() {
return std::bit_cast<std::int64_t>(u64());
}
std::span<const std::uint8_t> raw(std::size_t count) {
if (!ok_ || bytes_.size() - at_ < count) {
ok_ = false;
return {};
}
const auto out = bytes_.subspan(at_, count);
at_ += count;
return out;
}
// Rejects a value outside [0, last] without consuming further input.
std::uint8_t bounded(std::uint8_t last) {
const auto v = u8();
if (v > last)
invalid_ = true;
return v;
}
void invalid() {
invalid_ = true;
}
[[nodiscard]] std::expected<void, ProtocolError> finish() const {
if (!ok_)
return std::unexpected(ProtocolError::truncated);
if (invalid_)
return std::unexpected(ProtocolError::invalid_value);
if (at_ != bytes_.size())
return std::unexpected(ProtocolError::trailing_bytes);
return {};
}
[[nodiscard]] bool ok() const noexcept {
return ok_ && !invalid_;
}
private:
std::uint64_t get(std::size_t count) {
if (!ok_ || bytes_.size() - at_ < count) {
ok_ = false;
return 0;
}
std::uint64_t v = 0;
for (std::size_t i = 0; i < count; ++i)
v |= static_cast<std::uint64_t>(bytes_[at_ + i]) << (8 * i);
at_ += count;
return v;
}
std::span<const std::uint8_t> bytes_;
std::size_t at_{};
bool ok_{true}, invalid_{};
};
// Casts only on the validated path; an out-of-range byte flags the reader invalid
// and yields the enum's zero value, which the decoder then discards.
template <typename E> E enumerator(Reader& r, std::uint8_t last) {
const auto v = r.bounded(last);
return v <= last ? static_cast<E>(v) : E{};
}
struct Header {
MessageType type;
std::uint32_t length;
};
std::expected<Header, ProtocolError> parse_header(std::span<const std::uint8_t> bytes) {
Reader r{bytes.first(frame_header_bytes)};
const auto magic = r.u32();
const auto version = r.u16();
const auto type = r.u8();
const auto flags = r.u8();
const auto length = r.u32();
if (magic != frame_magic)
return std::unexpected(ProtocolError::bad_magic);
if (version != protocol_version)
return std::unexpected(ProtocolError::unsupported_version);
if (type == 0 || type > last_type)
return std::unexpected(ProtocolError::unknown_type);
if (flags != 0)
return std::unexpected(ProtocolError::reserved_flags);
if (length > max_frame_payload)
return std::unexpected(ProtocolError::oversized);
return Header{static_cast<MessageType>(type), length};
}
std::vector<std::uint8_t> framed(MessageType type, Writer& payload) {
const auto bytes = payload.take();
return encode_frame(type, bytes);
}
std::expected<Reader, ProtocolError> open(FrameView frame, MessageType type) {
if (frame.type != type)
return std::unexpected(ProtocolError::wrong_type);
return Reader{frame.payload};
}
void write(Writer& w, const ViewHeader& h) {
w.u64(h.session);
w.u64(h.epoch);
w.u64(h.server_tick);
w.u64(h.commit_watermark);
w.u64(h.baseline);
}
ViewHeader read_view_header(Reader& r) {
ViewHeader h;
h.session = r.u64();
h.epoch = r.u64();
h.server_tick = r.u64();
h.commit_watermark = r.u64();
h.baseline = r.u64();
return h;
}
} // namespace
std::vector<std::uint8_t> encode_frame(MessageType type, std::span<const std::uint8_t> payload) {
Writer w;
w.u32(frame_magic);
w.u16(protocol_version);
w.u8(static_cast<std::uint8_t>(type));
w.u8(0);
w.u32(static_cast<std::uint32_t>(payload.size()));
w.raw(payload);
return w.take();
}
std::expected<FrameView, ProtocolError> decode_frame(std::span<const std::uint8_t> bytes) {
if (bytes.size() < frame_header_bytes)
return std::unexpected(ProtocolError::truncated);
const auto header = parse_header(bytes);
if (!header)
return std::unexpected(header.error());
const auto total = frame_header_bytes + header->length;
if (bytes.size() < total)
return std::unexpected(ProtocolError::truncated);
if (bytes.size() > total)
return std::unexpected(ProtocolError::trailing_bytes);
return FrameView{header->type, bytes.subspan(frame_header_bytes)};
}
std::expected<std::size_t, ProtocolError> FrameReader::feed(std::span<const std::uint8_t> bytes) {
if (error_)
return std::unexpected(*error_);
std::size_t taken = 0;
while (taken < bytes.size() && buffer_.size() < expected_) {
const auto count = std::min(expected_ - buffer_.size(), bytes.size() - taken);
buffer_.insert(buffer_.end(), bytes.begin() + static_cast<std::ptrdiff_t>(taken),
bytes.begin() + static_cast<std::ptrdiff_t>(taken + count));
taken += count;
if (buffer_.size() == frame_header_bytes && expected_ == frame_header_bytes) {
const auto header = parse_header(buffer_);
if (!header) {
error_ = header.error();
buffer_.clear();
return std::unexpected(*error_);
}
expected_ = frame_header_bytes + header->length;
if (header->length == 0)
break;
}
}
return taken;
}
std::optional<OwnedFrame> FrameReader::take() {
if (error_ || buffer_.size() < frame_header_bytes || buffer_.size() != expected_)
return std::nullopt;
OwnedFrame frame{static_cast<MessageType>(buffer_[6]),
{buffer_.begin() + frame_header_bytes, buffer_.end()}};
buffer_.clear();
expected_ = frame_header_bytes;
return frame;
}
std::expected<std::vector<std::uint8_t>, ProtocolError> encode(const Hello& m) {
if (m.grant.empty() || m.grant.size() > max_grant_bytes)
return std::unexpected(ProtocolError::invalid_value);
Writer w;
w.u32(m.required_features);
w.u16(static_cast<std::uint16_t>(m.grant.size()));
w.raw(m.grant);
return framed(MessageType::hello, w);
}
std::vector<std::uint8_t> encode(const Welcome& m) {
Writer w;
for (const auto v : {m.session, m.world, m.frame, m.region, m.epoch, m.server_tick,
m.commit_watermark, m.grant_expires_at})
w.u64(v);
w.u32(m.intent_window);
w.u32(m.window_ticks);
w.u32(m.max_intents_per_window);
return framed(MessageType::welcome, w);
}
std::vector<std::uint8_t> encode(const IntentMessage& m) {
Writer w;
w.u64(m.session);
w.u64(m.epoch);
w.u64(m.sequence);
w.u64(m.tick);
w.i16(m.move_x);
w.i16(m.move_y);
return framed(MessageType::intent, w);
}
std::vector<std::uint8_t> encode(const IntentResult& m) {
Writer w;
w.u64(m.sequence);
w.u8(static_cast<std::uint8_t>(m.status));
w.u64(m.server_tick);
return framed(MessageType::intent_result, w);
}
std::vector<std::uint8_t> encode(CloseReason reason) {
Writer w;
w.u8(static_cast<std::uint8_t>(reason));
return framed(MessageType::close, w);
}
std::vector<std::uint8_t> encode(const ViewHeader& header,
const client::EnvironmentPresentation& view) {
Writer w;
write(w, header);
const auto revision = view.revision();
w.u64(revision.identity.world);
w.u64(revision.identity.frame);
w.u64(revision.tick);
w.u64(revision.field_revision);
w.u32(view.requested_mask());
w.i64(view.slice_z());
w.u16(static_cast<std::uint16_t>(view.cells().size()));
for (const auto& c : view.cells()) {
w.i64(c.voxel.x);
w.i64(c.voxel.y);
w.u64(c.chunk_revision);
for (const auto v : {c.habitat.x, c.habitat.y, c.habitat.z, c.habitat.width,
c.habitat.height, c.habitat.depth})
w.u32(static_cast<std::uint32_t>(v.value)); // Validated <= 1e6 um.
w.u64(c.volume.value);
w.u16(c.substrate.value);
w.u16(c.terrain_material.value);
w.u16(c.terrain_fill);
for (std::size_t k = 0; k < world::field_count; ++k) {
w.u8(static_cast<std::uint8_t>(c.presence.at(k)));
if (c.presence.at(k) == client::FieldPresence::present)
w.u64(c.quantity.at(k));
}
w.u8(static_cast<std::uint8_t>(c.moisture_status));
if (c.moisture_status == world::MoistureStatus::available) {
w.u64(c.moisture.numerator);
w.u64(c.moisture.denominator);
}
}
return framed(MessageType::environment_view, w);
}
std::vector<std::uint8_t> encode(const ViewHeader& header,
const client::OrganismPresentation& view) {
Writer w;
write(w, header);
const auto revision = view.revision();
w.u64(revision.identity.world);
w.u64(revision.identity.frame);
w.u64(revision.tick);
w.u64(revision.revision);
w.i64(view.slice_z());
w.u16(static_cast<std::uint16_t>(view.cells().size()));
for (const auto& c : view.cells()) {
const auto& p = c.phenotype;
w.u64(c.id);
w.i64(c.voxel.x);
w.i64(c.voxel.y);
w.u32(static_cast<std::uint32_t>(c.x.value)); // Validated < 1e6 um.
w.u32(static_cast<std::uint32_t>(c.y.value));
w.u64(p.structural_mass);
w.u64(p.membrane_mass);
w.u64(p.total_mass);
w.u32(p.extent);
w.u64(p.surface);
w.u64(p.maintenance);
w.u32(p.movement_speed);
w.u64(p.ingestion_rate);
w.u32(p.conversion_per_thousand);
w.u32(p.thermal_shortfall);
w.u32(c.growth.realized_per_thousand);
w.u32(c.growth.damage_per_thousand);
w.u8(static_cast<std::uint8_t>(c.state));
}
return framed(MessageType::organism_view, w);
}
std::expected<Hello, ProtocolError> decode_hello(FrameView frame) {
auto r = open(frame, MessageType::hello);
if (!r)
return std::unexpected(r.error());
Hello m;
m.required_features = r->u32();
const auto length = r->u16();
if (length == 0 || length > max_grant_bytes)
r->invalid();
const auto grant = r->raw(r->ok() ? length : 0);
if (auto done = r->finish(); !done)
return std::unexpected(done.error());
if (m.required_features != 0)
return std::unexpected(ProtocolError::unsupported_feature);
m.grant.assign(grant.begin(), grant.end());
return m;
}
std::expected<Welcome, ProtocolError> decode_welcome(FrameView frame) {
auto r = open(frame, MessageType::welcome);
if (!r)
return std::unexpected(r.error());
Welcome m;
m.session = r->u64();
m.world = r->u64();
m.frame = r->u64();
m.region = r->u64();
m.epoch = r->u64();
m.server_tick = r->u64();
m.commit_watermark = r->u64();
m.grant_expires_at = r->u64();
m.intent_window = r->u32();
m.window_ticks = r->u32();
m.max_intents_per_window = r->u32();
if (auto done = r->finish(); !done)
return std::unexpected(done.error());
if (m.session == 0 || m.window_ticks == 0 || m.max_intents_per_window == 0)
return std::unexpected(ProtocolError::invalid_value);
return m;
}
std::expected<IntentMessage, ProtocolError> decode_intent(FrameView frame) {
auto r = open(frame, MessageType::intent);
if (!r)
return std::unexpected(r.error());
IntentMessage m;
m.session = r->u64();
m.epoch = r->u64();
m.sequence = r->u64();
m.tick = r->u64();
m.move_x = r->i16();
m.move_y = r->i16();
if (auto done = r->finish(); !done)
return std::unexpected(done.error());
return m; // Range/semantics belong to admission, which reports a status.
}
std::expected<IntentResult, ProtocolError> decode_intent_result(FrameView frame) {
auto r = open(frame, MessageType::intent_result);
if (!r)
return std::unexpected(r.error());
IntentResult m;
m.sequence = r->u64();
m.status = enumerator<IntentStatus>(*r, last_status);
m.server_tick = r->u64();
if (auto done = r->finish(); !done)
return std::unexpected(done.error());
return m;
}
std::expected<CloseReason, ProtocolError> decode_close(FrameView frame) {
auto r = open(frame, MessageType::close);
if (!r)
return std::unexpected(r.error());
const auto reason = enumerator<CloseReason>(*r, last_reason);
if (auto done = r->finish(); !done)
return std::unexpected(done.error());
return reason;
}
std::expected<std::pair<ViewHeader, client::EnvironmentPresentation>, ProtocolError>
decode_environment_view(FrameView frame) {
auto r = open(frame, MessageType::environment_view);
if (!r)
return std::unexpected(r.error());
const auto header = read_view_header(*r);
client::EnvironmentRevision revision;
revision.identity.world = r->u64();
revision.identity.frame = r->u64();
revision.tick = r->u64();
revision.field_revision = r->u64();
const auto mask = r->u32();
const auto slice = r->i64();
const auto count = r->u16();
if (count > client::max_environment_cells)
r->invalid();
std::vector<client::EnvironmentCell> cells;
for (std::uint16_t i = 0; r->ok() && i < count; ++i) {
client::EnvironmentCell c;
c.voxel = {r->i64(), r->i64(), slice};
c.chunk_revision = r->u64();
c.habitat = {{r->u32()}, {r->u32()}, {r->u32()}, {r->u32()}, {r->u32()}, {r->u32()}};
c.volume = {r->u64()};
c.substrate = {r->u16()};
c.terrain_material = {r->u16()};
c.terrain_fill = r->u16();
for (std::size_t k = 0; k < world::field_count; ++k) {
c.presence.at(k) = enumerator<client::FieldPresence>(*r, last_presence);
if (c.presence.at(k) == client::FieldPresence::present)
c.quantity.at(k) = r->u64();
}
c.moisture_status = enumerator<world::MoistureStatus>(*r, last_moisture);
if (c.moisture_status == world::MoistureStatus::available)
c.moisture = {r->u64(), r->u64()};
cells.push_back(c);
}
if (auto done = r->finish(); !done)
return std::unexpected(done.error());
auto view = client::EnvironmentPresentation::create(revision, mask, slice, cells);
if (!view)
return std::unexpected(ProtocolError::invalid_value);
return std::pair{header, std::move(*view)};
}
std::expected<std::pair<ViewHeader, client::OrganismPresentation>, ProtocolError>
decode_organism_view(FrameView frame) {
auto r = open(frame, MessageType::organism_view);
if (!r)
return std::unexpected(r.error());
const auto header = read_view_header(*r);
client::OrganismRevision revision;
revision.identity.world = r->u64();
revision.identity.frame = r->u64();
revision.tick = r->u64();
revision.revision = r->u64();
const auto slice = r->i64();
const auto count = r->u16();
if (count > client::max_organism_cells)
r->invalid();
std::vector<client::OrganismCell> cells;
for (std::uint16_t i = 0; r->ok() && i < count; ++i) {
client::OrganismCell c;
c.id = r->u64();
c.voxel = {r->i64(), r->i64(), slice};
c.x = {r->u32()};
c.y = {r->u32()};
auto& p = c.phenotype;
p.structural_mass = r->u64();
p.membrane_mass = r->u64();
p.total_mass = r->u64();
p.extent = r->u32();
p.surface = r->u64();
p.maintenance = r->u64();
p.movement_speed = r->u32();
p.ingestion_rate = r->u64();
p.conversion_per_thousand = r->u32();
p.thermal_shortfall = r->u32();
c.growth.realized_per_thousand = r->u32();
c.growth.damage_per_thousand = r->u32();
c.state = enumerator<client::OrganismState>(*r, last_state);
cells.push_back(c);
}
if (auto done = r->finish(); !done)
return std::unexpected(done.error());
auto view = client::OrganismPresentation::create(revision, slice, cells);
if (!view)
return std::unexpected(ProtocolError::invalid_value);
return std::pair{header, std::move(*view)};
}
IntentMessage make_intent(std::uint64_t session, std::uint64_t epoch,
const client::Intention& intention) noexcept {
return {session, epoch, intention.sequence, intention.tick, intention.move_x, intention.move_y};
}
} // namespace evo::network