From 0ce51077b19f0fa8a0f5b44a19863bde1badd5d0 Mon Sep 17 00:00:00 2001 From: dingo Date: Tue, 6 Oct 2026 18:32:14 -0400 Subject: [PATCH] Add M10.8b signed handoff tickets and ticket admission ADR-0096. A source region's handoff key signs a 160-byte ticket for one probe transfer, account and destination; it rides the Hello grant slot and is verified against neighbour keys bound to their regions. SessionControl admits a ticket once per region, superseding like a grant, with the session ending at the client's original grant expiry. RegionSessions makes the destination's durable step first: PostgresHandoffLedger stages and commits the transfer and moves the account's control, idempotently. Co-Authored-By: Claude Opus 5.5 --- CMakeLists.txt | 6 +- cmake/Network.cmake | 3 +- docs/ROADMAP.md | 5 +- docs/STATUS.md | 6 +- docs/adr/0096-m10-probe-handoff.md | 29 +++ docs/engineering/VALIDATION.md | 41 +++ include/evo/network/handoff_ticket.hpp | 149 +++++++++++ include/evo/network/session_control.hpp | 17 ++ .../evo/server/postgres_handoff_ledger.hpp | 33 +++ include/evo/server/region_sessions.hpp | 16 ++ schemas/network/handoff-ticket-v1.md | 33 +++ src/network/protocol/session_control.cpp | 77 ++++++ src/network/tls/handoff_ticket.cpp | 245 ++++++++++++++++++ .../session/postgres_handoff_ledger.cpp | 70 +++++ src/server/session/region_sessions.cpp | 92 ++++++- tests/network_control.cpp | 90 +++++++ tests/probe_handoff_store_tests.cpp | 64 +++++ tests/quic_sessions.cpp | 82 +++++- 18 files changed, 1039 insertions(+), 19 deletions(-) create mode 100644 include/evo/network/handoff_ticket.hpp create mode 100644 include/evo/server/postgres_handoff_ledger.hpp create mode 100644 schemas/network/handoff-ticket-v1.md create mode 100644 src/network/tls/handoff_ticket.cpp create mode 100644 src/server/session/postgres_handoff_ledger.cpp diff --git a/CMakeLists.txt b/CMakeLists.txt index 470b551..6bb5138 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -234,10 +234,10 @@ if(EVO_BUILD_POSTGRES) endif() evo_owned_target(evo-server) if(EVO_BUILD_NETWORK) - # M10.3c durable account control and M10.4b durable action records for region sessions - # (ADR-0091 schema v10, ADR-0092 schema v11). + # M10.3c durable account control, M10.4b durable action records and M10.8b ticket + # handoffs for region sessions (ADR-0091 schema v10, ADR-0092 v11, ADR-0096 v12). add_library(evo_control_ledger_postgres STATIC src/server/session/postgres_control_ledger.cpp - src/server/session/postgres_action_ledger.cpp) + src/server/session/postgres_action_ledger.cpp src/server/session/postgres_handoff_ledger.cpp) target_link_libraries(evo_control_ledger_postgres PUBLIC evo::postgres evo_network_protocol) evo_owned_target(evo_control_ledger_postgres) endif() diff --git a/cmake/Network.cmake b/cmake/Network.cmake index 3e698c1..bf47ae5 100644 --- a/cmake/Network.cmake +++ b/cmake/Network.cmake @@ -44,7 +44,8 @@ evo_owned_target(evo_client_prediction) # Mbed TLS adapters: dev grants (HMAC-SHA256 via PSA) and the TLS 1.3 channel. # M10.3 session grants (ECDSA P-256 via PSA) share the adapter (ADR-0091). add_library(evo_network_tls STATIC src/network/tls/dev_grant.cpp src/network/tls/channel.cpp - src/network/tls/dev_credentials.cpp src/network/tls/session_grant.cpp) + src/network/tls/dev_credentials.cpp src/network/tls/session_grant.cpp + src/network/tls/handoff_ticket.cpp) target_link_libraries(evo_network_tls PUBLIC evo_network_protocol PRIVATE mbedtls) evo_owned_target(evo_network_tls) # M10.3 backend identity adapter: providers, account directory, grant issuer (library only). diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index aed0d8e..4ea6cd5 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -535,8 +535,9 @@ traces done (networking/M10_PREDICTION_TRACES.md). 10.7 split (ADR-0095): 10.7a remote-marker interpolation and fractional prediction done; 10.7b client wiring, stale loss view and two-client interpolation traces done. 10.8 split (ADR-0096, the persistence handoff ADR; EXPERIMENT durable probe records): 10.8a schema v12 probe records and the -transfer state machine with a PostgreSQL fault matrix done; 10.8b handoff tickets, 10.8c -region wiring and 10.8d two-process kill tests follow. 10.9 planned. +transfer state machine with a PostgreSQL fault matrix done; 10.8b signed handoff tickets and +ticket admission (durable stage, commit and control move) done; 10.8c region wiring and 10.8d +two-process kill tests follow. 10.9 planned. **Entry:** M9 client/session evidence and M7/M8 dev/stage durability. Read NETWORK_ARCHITECTURE, PERSISTENCE_ARCHITECTURE and ADR-0017. The M9 transport is diff --git a/docs/STATUS.md b/docs/STATUS.md index d7ad962..8283a6c 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -72,7 +72,11 @@ within about 0.1 m of the true path, and outages show stale. M10.7 is complete. A PostgreSQL fault matrix covers restarts at each transition, stale epochs, aborts, partitions and commit/abort races, checking a unique owner and the conserved test inventory. -Deploying v12 needs a rebuilt migrations image. Next: 10.8b handoff tickets. +Deploying v12 needs a rebuilt migrations image. M10.8b adds signed handoff tickets. A source +region's key signs one transfer for one account and destination; the ticket rides the Hello +grant slot and is verified against the neighbour keys registered here. The destination then +durably stages and commits the transfer and takes the account's control before admitting +the session. Next: 10.8c region wiring (edge crossing, ghost, client switch). ## Previous gate - 2026-10-02 diff --git a/docs/adr/0096-m10-probe-handoff.md b/docs/adr/0096-m10-probe-handoff.md index c6703c3..1d86a6e 100644 --- a/docs/adr/0096-m10-probe-handoff.md +++ b/docs/adr/0096-m10-probe-handoff.md @@ -114,3 +114,32 @@ controllable before M11. The dev migrations image must be rebuilt (the v10 lesson). - A probe's durable position can lag its in-memory position by up to a session: presentation-only state, never biological. + +## M10.8b tickets and ticket admission (2026-10-06) +- **Ticket** ([handoff-ticket-v1](../../schemas/network/handoff-ticket-v1.md)): 160 bytes, + the same as a grant, so it rides the `Hello` grant slot with no protocol change. Fields: + - an "EVO-HANDOFF" marker, version, environment and key id; + - the transfer id, account, world, frame, source and destination; + - the ticket expiry (at most 120 s ahead) and the session expiry, copied from the + client's grant at the source so a crossing never extends a session; + - an ECDSA P-256 signature. + + Each region has its own handoff key (`HandoffSigningKey`). A destination registers its + neighbours' public keys, each bound to its source region (`HandoffVerifier`, at most + 32), and accepts a ticket only if the signing key belongs to the claimed source, the world + and destination are its own, and the times hold. Grants and tickets never verify as each + other. +- **Admission.** `RegionSessions` routes a Hello by the ticket marker. A ticket is verified, + then `SessionControl::check_handoff` runs: single use per region, the attempt counted, + supersedes like a grant, serials untouched. Then the host's `HandoffLedger` makes it + durable, and only then does the local `open_handoff` run. The session expiry is the + ticket's, capped at the maximum grant lifetime from now. Renewal and release use the + ControlLedger under the generation the handoff returned. A handoff ledger without a + control ledger is a configuration error. +- **PostgreSQL** (`PostgresHandoffLedger`): stage (under the current lease, again after a + restart), commit, then `handoff_account_control`, all idempotent, so a retried login + converges. Unknown, aborted, foreign-account, foreign-source or foreign-region transfers + are refused (`unauthenticated`); a fenced lease gives `shutdown`; undecided gives + `capacity`. +- Not yet: the source side (freeze at the edge, prepare, release control, offer the ticket), + the client switch, keys in evo-server and the dev tool (10.8c). diff --git a/docs/engineering/VALIDATION.md b/docs/engineering/VALIDATION.md index 104cff4..ab5923c 100644 --- a/docs/engineering/VALIDATION.md +++ b/docs/engineering/VALIDATION.md @@ -4726,3 +4726,44 @@ run's races ended 11 commits, 13 aborts. Not done: - tickets (10.8b), region wiring (10.8c) and two-process kills (10.8d); - deploying v12 (needs a rebuilt migrations image; a maintainer step). + +## 2026-10-06 — M10.8b handoff tickets and admission (ADR-0096) + +Implemented: +- `HandoffSigningKey`, `HandoffVerifier`, `VerifiedHandoffTicket` and `HandoffLedger` + (`include/evo/network/handoff_ticket.hpp`; schema `network/handoff-ticket-v1`); +- `SessionControl::check_handoff` and `open_handoff`; +- `RegionSessions` ticket admission (marker routing, neighbour keys, durable step first, + shared session-opening tail); +- `PostgresHandoffLedger` (stage, commit, `handoff_account_control`). + +Tests: +- `network_control`: + - tickets round-trip; a flipped byte every 7 bytes is refused; + - wrong source key, scope (world and destination), expiry, lifetime over 120 s, a session + already ended, wrong environment, unknown key and invalid claims are all refused; + - grants and tickets never verify as each other; + - control: a ticket supersedes a grant session, replay is refused, the session expiry is + capped, and later grants still open. +- `quic_sessions` (loopback QUIC): + - no keys: refused; + - a handoff ledger without a control ledger: configuration error; + - an admitted ticket: the durable step for the session Welcome names, the ticket's session + expiry, renewal under the handoff's generation; + - replay, another destination, and a refused or undecided durable step: refused + (unauthenticated, wrong_scope, capacity). +- `probe_handoff_store_tests` (PostgreSQL): the ledger admits and moves ownership and + control; a retry converges; another account, an unknown or aborted transfer, and no lease + are refused. + +Executed: +- **Linux GCC 14:** `postgres-check.sh` with QUIC: 21 suites (race run: 16 commits, 8 + aborts); preset `quic`: 4/4; `evo-network-tests` and `evo-quic-session-tests`. +- **Linux Clang 19:** ASan/UBSan `evo-network-tests`; clang-tidy 19 on the ticket, + session-control, region-sessions, ledger and test sources; clang-format 19. +- **Windows MSVC 19.44:** preset `quic`: 4/4; `client-network`: 14/14 (built before the + formatting pass, which changed whitespace only). + +Not done: +- the source side and the client switch (10.8c); +- two-process kill tests (10.8d). diff --git a/include/evo/network/handoff_ticket.hpp b/include/evo/network/handoff_ticket.hpp new file mode 100644 index 0000000..5d6dbf2 --- /dev/null +++ b/include/evo/network/handoff_ticket.hpp @@ -0,0 +1,149 @@ +#pragma once +#include "evo/network/session_control.hpp" +#include "evo/network/session_grant.hpp" +#include +#include +#include +#include +#include +#include + +// M10.8b handoff tickets v1 (ADR-0096, schemas/network/handoff-ticket-v1.md): a fixed +// 160-byte record ("EVO-HANDOFF" marker, version, environment, key id, claims) signed by the +// SOURCE region with its own handoff key (ECDSA P-256/SHA-256, Mbed TLS PSA), naming one +// committed-to-be transfer, its account and its one destination. It travels in the Hello +// grant slot: the marker only routes it to this verifier, and nothing in it is trusted +// before its signature verifies against a key registered for the claimed source region. +// Region handoff keys never sign grants and the grant issuer never signs tickets (distinct +// markers). Ticket bytes and keys have no log form. +namespace evo::network { +inline constexpr std::size_t handoff_ticket_bytes = 160; +inline constexpr std::uint64_t max_ticket_lifetime = 120; // Seconds a ticket may be valid. +using HandoffTicket = std::array; +using TransferId = std::array; +struct TicketClaims { + TransferId transfer{}; + AccountId account; + world::WorldIdentity world; + std::uint64_t source{}, destination{}; + // Server clock, seconds (u32 on the wire, valid to 2106): when the ticket stops being + // accepted, and when the session it opens must end (the client's grant expiry at the + // source, so a crossing never extends a session). + std::uint32_t expires_at{}, session_expires_at{}; +}; +enum class HandoffTicketError : std::uint8_t { + invalid_key, + duplicate_key, + too_many_keys, + invalid_claims, + malformed, + wrong_marker, + unsupported_version, + wrong_environment, + unknown_key, + wrong_source, // Signed by a key registered for another region than the claimed source. + wrong_scope, // Another world or another destination than this region. + expired, // Ticket or session expiry passed, or a lifetime beyond the maximum. + bad_signature, + crypto +}; +// Marker check only (unauthenticated): routes a Hello to ticket verification. +[[nodiscard]] bool looks_like_handoff_ticket(std::span bytes) noexcept; + +// A region's handoff signing key (PSA, non-exportable private part). Move-only. +class HandoffSigningKey { + public: + [[nodiscard]] static std::expected + generate(DeploymentEnvironment environment, std::uint32_t key_id); + [[nodiscard]] static std::expected + import(DeploymentEnvironment environment, std::uint32_t key_id, + std::span private_key); + HandoffSigningKey(HandoffSigningKey&& other) noexcept; + HandoffSigningKey& operator=(HandoffSigningKey&& other) noexcept; + HandoffSigningKey(const HandoffSigningKey&) = delete; + HandoffSigningKey& operator=(const HandoffSigningKey&) = delete; + ~HandoffSigningKey(); + // Structural checks only (nonzero ids and scope, source != destination, ordered times). + [[nodiscard]] std::expected + sign(const TicketClaims& claims) const; + [[nodiscard]] std::expected public_key() const; + + private: + HandoffSigningKey(DeploymentEnvironment environment, std::uint32_t key_id, std::uint32_t key) + : environment_{environment}, key_id_{key_id}, key_{key} {} + DeploymentEnvironment environment_; + std::uint32_t key_id_; + std::uint32_t key_; // PSA key id; zero when moved-from. +}; + +class HandoffVerifier; +// Only HandoffVerifier::verify constructs this, after signature, source, scope and times. +class VerifiedHandoffTicket { + public: + [[nodiscard]] const TicketClaims& claims() const noexcept { + return claims_; + } + + private: + friend class HandoffVerifier; + explicit VerifiedHandoffTicket(const TicketClaims& claims) : claims_{claims} {} + TicketClaims claims_; +}; + +// Destination-side verifier: this region's world and id, and the handoff public keys of the +// regions it may receive from (up to 32, each bound to one source region). +class HandoffVerifier { + public: + static constexpr std::size_t max_keys = 32; + [[nodiscard]] static std::expected + create(DeploymentEnvironment environment, world::WorldIdentity world, std::uint64_t region); + HandoffVerifier(HandoffVerifier&& other) noexcept; + HandoffVerifier& operator=(HandoffVerifier&& other) noexcept; + HandoffVerifier(const HandoffVerifier&) = delete; + HandoffVerifier& operator=(const HandoffVerifier&) = delete; + ~HandoffVerifier(); + [[nodiscard]] std::expected + add_key(std::uint64_t source_region, std::uint32_t key_id, + std::span public_key); + // Signature first; then marker, version, environment, the key's region equal to the + // claimed source, this world and region as destination, and the times at `now_seconds`. + [[nodiscard]] std::expected + verify(std::span ticket, std::uint64_t now_seconds) const; + + private: + struct Key { + std::uint64_t region{}; + std::uint32_t key_id{}, key{}; + }; + HandoffVerifier(DeploymentEnvironment environment, world::WorldIdentity world, + std::uint64_t region) + : environment_{environment}, world_{world}, region_{region} {} + void destroy() noexcept; + DeploymentEnvironment environment_; + world::WorldIdentity world_; + std::uint64_t region_; + std::vector keys_; +}; +// The destination's durable side of a ticket login (ADR-0096): stage and commit the ticket's +// transfer under this region's lease, then take the account's durable control for +// `session` (handoff_account_control). The region host implements it over PostgreSQL; +// tests use fakes. Renewal and release then go through the ControlLedger. +enum class HandoffLedgerError : std::uint8_t { + refused, // The transfer is unknown, aborted, or not this region's: never admit. + fenced, // This region's lease is not current. + unavailable // Not decided (database unreachable, timeout, unknown outcome): retry later. +}; +class HandoffLedger { + public: + HandoffLedger() = default; + HandoffLedger(const HandoffLedger&) = delete; + HandoffLedger& operator=(const HandoffLedger&) = delete; + virtual ~HandoffLedger() = default; + [[nodiscard]] virtual std::expected + admit(const TicketClaims& ticket, std::uint64_t session) = 0; + + protected: + HandoffLedger(HandoffLedger&&) = default; + HandoffLedger& operator=(HandoffLedger&&) = default; +}; +} // namespace evo::network diff --git a/include/evo/network/session_control.hpp b/include/evo/network/session_control.hpp index ddff2fa..1866a3a 100644 --- a/include/evo/network/session_control.hpp +++ b/include/evo/network/session_control.hpp @@ -37,6 +37,7 @@ struct GrantClaims { std::uint64_t region{}, issued_at{}, expires_at{}; // Server clock, seconds. }; class GrantVerifier; +class VerifiedHandoffTicket; // M10.8b, handoff_ticket.hpp. // Only GrantVerifier::verify constructs this, after the signature and environment checked. class VerifiedSessionGrant { public: @@ -107,6 +108,15 @@ class SessionControl { // session is closed first and reported as superseded. Control is never shared. [[nodiscard]] std::expected open(const VerifiedSessionGrant& grant, std::uint64_t now_seconds); + // M10.8b (ADR-0096): a verified handoff ticket opens a session here, the destination, + // for its account. A ticket is single-use per region (its transfer is remembered until + // the ticket expires), counts as an attempt like a grant, supersedes like a grant, and + // the session ends at the ticket's session expiry, capped at the maximum grant lifetime + // from now: a crossing never extends a session. Serials are unchanged. + [[nodiscard]] std::expected + check_handoff(const VerifiedHandoffTicket& ticket, std::uint64_t now_seconds) const; + [[nodiscard]] std::expected + open_handoff(const VerifiedHandoffTicket& ticket, std::uint64_t now_seconds); // In-session renewal with a newer grant for the same account: extends the expiry // without a reconnect or new baseline. [[nodiscard]] std::expected @@ -139,6 +149,12 @@ class SessionControl { [[nodiscard]] bool forgettable(const Account& account, std::uint64_t now_seconds) const; [[nodiscard]] std::expected admit(const VerifiedSessionGrant& grant, std::uint64_t now_seconds); + [[nodiscard]] std::optional ticket_error(const VerifiedHandoffTicket& ticket, + std::uint64_t now_seconds) const; + struct UsedTicket { + std::array transfer{}; + std::uint64_t until{}; + }; void accept(Account& account, const GrantClaims& claims); void forget_idle(std::uint64_t now_seconds); ControlConfig config_; @@ -146,6 +162,7 @@ class SessionControl { std::uint64_t region_window_start_{}; std::uint32_t region_attempts_{}; std::vector accounts_; + std::vector used_tickets_; // At most max_accounts, pruned at expiry. }; // Durable per-world account control (10.3c, schema v10). The region host implements it diff --git a/include/evo/server/postgres_handoff_ledger.hpp b/include/evo/server/postgres_handoff_ledger.hpp new file mode 100644 index 0000000..39ecad9 --- /dev/null +++ b/include/evo/server/postgres_handoff_ledger.hpp @@ -0,0 +1,33 @@ +#pragma once +#include "evo/network/handoff_ticket.hpp" +#include "evo/persistence/probe_store.hpp" +#include "evo/server/pg_slot.hpp" +#include +#include +#include +#include + +// M10.8b destination side of a ticket login over PostgreSQL (ADR-0096, schema v12). Linux +// only; owned by the region host's thread, on its own connection slot. For a verified ticket: +// stage its transfer under the host's current lease (again after a restart), commit it (the +// authority switch), then take the account's durable control for the session. Every step is +// idempotent, so a retried ticket login after an undecided outcome converges. A transfer that +// is unknown, aborted, for another account or another region is refused. +namespace evo::server { +class PostgresHandoffLedger final : public network::HandoffLedger { + public: + using LeaseSource = std::function()>; + PostgresHandoffLedger(PgSlot& db, persistence::RegionKey key, LeaseSource lease, + std::chrono::milliseconds duration = std::chrono::milliseconds{20000}, + std::chrono::milliseconds timeout = std::chrono::milliseconds{2000}) + : db_{&db}, key_{key}, lease_{std::move(lease)}, duration_{duration}, timeout_{timeout} {} + [[nodiscard]] std::expected + admit(const network::TicketClaims& ticket, std::uint64_t session) override; + + private: + PgSlot* db_; + persistence::RegionKey key_; + LeaseSource lease_; + std::chrono::milliseconds duration_, timeout_; +}; +} // namespace evo::server diff --git a/include/evo/server/region_sessions.hpp b/include/evo/server/region_sessions.hpp index 103363c..63a09ac 100644 --- a/include/evo/server/region_sessions.hpp +++ b/include/evo/server/region_sessions.hpp @@ -1,4 +1,5 @@ #pragma once +#include "evo/network/handoff_ticket.hpp" #include "evo/network/intent_admission.hpp" #include "evo/network/probe_motion.hpp" #include "evo/network/quic_transport.hpp" @@ -33,6 +34,10 @@ // M10.6 (ADR-0094, EXPERIMENT): once the host sets a motion area, every established session // has a probe marker; admitted intentions schedule its movement, each poll advances markers // to the simulated tick, and snapshots carry them. A new epoch starts without markers. +// M10.8b (ADR-0096): a Hello may carry a handoff ticket instead of a grant (same slot, +// another marker). A ticket verified against a neighbour's key for this region opens a +// session for its account after the HandoffLedger durably staged and committed its transfer +// and moved the account's control here. // With a ControlLedger, control is durable and unique per world: a session that loses its // durable control (another region accepted a newer grant) closes with `superseded`, and // one whose control cannot be renewed in time closes with `shutdown`. @@ -41,6 +46,12 @@ struct IssuerKey { std::uint32_t key_id{}; network::GrantPublicKey public_key{}; }; +// A neighbouring region's handoff public key (ADR-0096): tickets it signs are accepted here. +struct HandoffKey { + std::uint64_t source_region{}; + std::uint32_t key_id{}; + network::GrantPublicKey public_key{}; +}; struct RegionSessionsConfig { network::quic::ServerConfig transport; network::ControlConfig control; // `epoch` is the initial ownership epoch. @@ -57,6 +68,11 @@ struct RegionSessionsConfig { // Durable action records (10.4b), owned by the host; null keeps outcomes in memory only. network::ActionLedger* actions{}; network::ReplicationLimits replication{}; // max_sessions follows control.max_sessions. + // M10.8b handoff tickets (ADR-0096): neighbours' keys, and the durable side owned by the + // host. Without keys every ticket is refused (unauthenticated). With a ControlLedger a + // ticket also needs a HandoffLedger (control must move durably with the transfer). + std::vector handoff_keys; + network::HandoffLedger* handoff{}; }; // The region host's authority, read once per poll. struct HostFacts { diff --git a/schemas/network/handoff-ticket-v1.md b/schemas/network/handoff-ticket-v1.md new file mode 100644 index 0000000..35931ba --- /dev/null +++ b/schemas/network/handoff-ticket-v1.md @@ -0,0 +1,33 @@ +# Handoff ticket, version 1 + +ADR-0096 (M10.8b). A region signs a ticket for one probe transfer with its handoff key; the +destination region admits the account's client with it instead of a grant. It travels in the +160-byte grant slot of `Hello` (session protocol v3); its marker routes it to ticket +verification. Implemented by `HandoffSigningKey` and `HandoffVerifier` +(include/evo/network/handoff_ticket.hpp). Integers little-endian. + +| Offset | Size | Field | Rule | +|---|---|---|---| +| 0 | 16 | marker | `EVO-HANDOFF` followed by five zero bytes | +| 16 | 2 | version | 1 | +| 18 | 1 | environment | 1 dev, 2 stage, 3 world0; must equal the verifier's | +| 19 | 1 | reserved | 0 | +| 20 | 4 | key id | Selects the source region's key (bound to that region) | +| 24 | 16 | transfer id | Nonzero; the probe transfer (schema v12) | +| 40 | 16 | account | Valid account id | +| 56 | 8 | world | Nonzero, equal to the destination's | +| 64 | 8 | frame | Nonzero, equal to the destination's | +| 72 | 8 | source region | Nonzero; equal to the region the key is registered for | +| 80 | 8 | destination region | Nonzero, not the source; equal to the verifying region | +| 88 | 4 | expires_at | Seconds (server clock); accepted while now < expires_at <= now + 120 | +| 92 | 4 | session_expires_at | Seconds; the opened session ends then (capped at now + the maximum grant lifetime) | +| 96 | 64 | signature | ECDSA P-256 / SHA-256 over bytes [0, 96), raw r and s | + +Rules: +- The signature is verified first; no other byte is trusted before it. +- Within a region a ticket is single-use: its transfer id is remembered until the ticket + expires. +- The destination's durable side stages and commits the transfer, then moves the account's + control. It refuses a transfer that is unknown, aborted, for another account, from another + source or for another region. +- Grants and tickets never verify as each other (different markers and keys). diff --git a/src/network/protocol/session_control.cpp b/src/network/protocol/session_control.cpp index f942f8d..193d23d 100644 --- a/src/network/protocol/session_control.cpp +++ b/src/network/protocol/session_control.cpp @@ -1,4 +1,5 @@ #include "evo/network/session_control.hpp" +#include "evo/network/handoff_ticket.hpp" #include namespace evo::network { @@ -154,6 +155,82 @@ std::expected SessionControl::open(const VerifiedSe return opened; } +std::optional SessionControl::ticket_error(const VerifiedHandoffTicket& ticket, + std::uint64_t now_seconds) const { + const auto& c = ticket.claims(); + if (c.world != config_.world) + return ControlError::wrong_world; + if (c.destination != config_.region) + return ControlError::wrong_region; + if (now_seconds >= c.expires_at || now_seconds >= c.session_expires_at) + return ControlError::expired; + if (std::ranges::any_of(used_tickets_, [&](const UsedTicket& u) { + return u.transfer == c.transfer && u.until > now_seconds; + })) + return ControlError::stale_grant; // A replayed ticket. + return std::nullopt; +} + +std::expected SessionControl::check_handoff(const VerifiedHandoffTicket& ticket, + std::uint64_t now_seconds) const { + if (const auto e = ticket_error(ticket, now_seconds)) + return std::unexpected(*e); + const auto& c = ticket.claims(); + const auto found = + std::ranges::find_if(accounts_, [&](const Account& a) { return a.id == c.account; }); + if (found == accounts_.end()) { + const auto kept = std::ranges::count_if( + accounts_, [&](const Account& a) { return !forgettable(a, now_seconds); }); + if (static_cast(kept) >= config_.max_accounts) + return std::unexpected(ControlError::accounts_full); + } else if (!window_over(found->window_start, now_seconds, config_.attempt_window) && + found->attempts >= config_.max_account_attempts) { + return std::unexpected(ControlError::rate_limited); + } + if ((found == accounts_.end() || found->session == 0) && sessions() >= config_.max_sessions) + return std::unexpected(ControlError::sessions_full); + return {}; +} + +std::expected +SessionControl::open_handoff(const VerifiedHandoffTicket& ticket, std::uint64_t now_seconds) { + std::erase_if(used_tickets_, [&](const UsedTicket& u) { return u.until <= now_seconds; }); + if (const auto e = ticket_error(ticket, now_seconds)) + return std::unexpected(*e); + const auto& c = ticket.claims(); + if (used_tickets_.size() >= config_.max_accounts) + return std::unexpected(ControlError::accounts_full); // Fail closed: never forget early. + forget_idle(now_seconds); + auto found = + std::ranges::find_if(accounts_, [&](const Account& a) { return a.id == c.account; }); + if (found == accounts_.end()) { + if (accounts_.size() >= config_.max_accounts) + return std::unexpected(ControlError::accounts_full); + accounts_.push_back({c.account, 0, 0, 0, 0, now_seconds, 0}); + found = std::prev(accounts_.end()); + } + auto& a = *found; + if (window_over(a.window_start, now_seconds, config_.attempt_window)) { + a.window_start = now_seconds; + a.attempts = 0; + } + if (a.attempts >= config_.max_account_attempts) + return std::unexpected(ControlError::rate_limited); + ++a.attempts; + if (a.session == 0 && sessions() >= config_.max_sessions) + return std::unexpected(ControlError::sessions_full); + used_tickets_.push_back({c.transfer, c.expires_at}); + OpenedSession opened; + opened.superseded = a.session; + a.session = next_session_++; + a.session_expires_at = + std::min(c.session_expires_at, now_seconds + config_.max_grant_lifetime); + opened.session = a.session; + opened.epoch = config_.epoch; + opened.expires_at = a.session_expires_at; + return opened; +} + std::expected SessionControl::refresh(std::uint64_t session, const VerifiedSessionGrant& grant, std::uint64_t now_seconds) { diff --git a/src/network/tls/handoff_ticket.cpp b/src/network/tls/handoff_ticket.cpp new file mode 100644 index 0000000..d804663 --- /dev/null +++ b/src/network/tls/handoff_ticket.cpp @@ -0,0 +1,245 @@ +#include "evo/network/handoff_ticket.hpp" +#include +#include +#include + +namespace evo::network { +namespace { +constexpr std::array marker{'E', 'V', 'O', '-', 'H', 'A', 'N', 'D', + 'O', 'F', 'F', 0, 0, 0, 0, 0}; +constexpr std::uint16_t ticket_version = 1; +constexpr std::size_t signed_end = 96; // The signature covers bytes [0, 96). +constexpr std::size_t signature_bytes = handoff_ticket_bytes - signed_end; +constexpr psa_algorithm_t algorithm = PSA_ALG_ECDSA(PSA_ALG_SHA_256); +static_assert(signature_bytes == PSA_ECDSA_SIGNATURE_SIZE(256)); +static_assert(handoff_ticket_bytes == session_grant_bytes, "tickets use the Hello grant slot"); + +std::uint8_t environment_byte(DeploymentEnvironment e) { + return static_cast(static_cast(e) + 1); +} +void put(HandoffTicket& out, std::size_t at, std::uint64_t v, std::size_t count) { + for (std::size_t i = 0; i < count; ++i) + out.at(at + i) = static_cast(v >> (8 * i)); +} +std::uint64_t get(std::span in, std::size_t at, std::size_t count) { + std::uint64_t v = 0; + for (std::size_t i = 0; i < count; ++i) + v |= static_cast(in[at + i]) << (8 * i); + return v; +} +bool structurally_valid(const TicketClaims& c) { + return std::ranges::any_of(c.transfer, [](std::uint8_t b) { return b != 0; }) && + c.account.valid() && c.world.world != 0 && c.world.frame != 0 && c.source != 0 && + c.destination != 0 && c.source != c.destination && c.expires_at != 0 && + c.session_expires_at != 0; +} +std::expected import_key(const psa_key_attributes_t& a, + std::span bytes) { + mbedtls_svc_key_id_t key = PSA_KEY_ID_NULL; + if (psa_import_key(&a, bytes.data(), bytes.size(), &key) != PSA_SUCCESS) + return std::unexpected(HandoffTicketError::invalid_key); + return key; +} +psa_key_attributes_t pair_attributes() { + psa_key_attributes_t a = PSA_KEY_ATTRIBUTES_INIT; + psa_set_key_type(&a, PSA_KEY_TYPE_ECC_KEY_PAIR(PSA_ECC_FAMILY_SECP_R1)); + psa_set_key_bits(&a, 256); + psa_set_key_usage_flags(&a, PSA_KEY_USAGE_SIGN_MESSAGE); + psa_set_key_algorithm(&a, algorithm); + return a; +} +} // namespace + +bool looks_like_handoff_ticket(std::span bytes) noexcept { + return bytes.size() == handoff_ticket_bytes && + std::equal(marker.begin(), marker.end(), bytes.begin()); +} + +std::expected +HandoffSigningKey::generate(DeploymentEnvironment environment, std::uint32_t key_id) { + if (key_id == 0) + return std::unexpected(HandoffTicketError::invalid_key); + if (psa_crypto_init() != PSA_SUCCESS) + return std::unexpected(HandoffTicketError::crypto); + auto a = pair_attributes(); + mbedtls_svc_key_id_t key = PSA_KEY_ID_NULL; + const auto status = psa_generate_key(&a, &key); + psa_reset_key_attributes(&a); + if (status != PSA_SUCCESS) + return std::unexpected(HandoffTicketError::crypto); + return HandoffSigningKey{environment, key_id, key}; +} + +std::expected +HandoffSigningKey::import(DeploymentEnvironment environment, std::uint32_t key_id, + std::span private_key) { + if (key_id == 0 || private_key.size() != grant_private_key_bytes) + return std::unexpected(HandoffTicketError::invalid_key); + if (psa_crypto_init() != PSA_SUCCESS) + return std::unexpected(HandoffTicketError::crypto); + auto a = pair_attributes(); + auto key = import_key(a, private_key); + psa_reset_key_attributes(&a); + if (!key) + return std::unexpected(key.error()); + return HandoffSigningKey{environment, key_id, *key}; +} + +HandoffSigningKey::HandoffSigningKey(HandoffSigningKey&& other) noexcept + : environment_{other.environment_}, key_id_{other.key_id_}, + key_{std::exchange(other.key_, PSA_KEY_ID_NULL)} {} + +HandoffSigningKey& HandoffSigningKey::operator=(HandoffSigningKey&& other) noexcept { + if (this != &other) { + if (key_ != PSA_KEY_ID_NULL) + (void)psa_destroy_key(key_); + environment_ = other.environment_; + key_id_ = other.key_id_; + key_ = std::exchange(other.key_, PSA_KEY_ID_NULL); + } + return *this; +} + +HandoffSigningKey::~HandoffSigningKey() { + if (key_ != PSA_KEY_ID_NULL) + (void)psa_destroy_key(key_); +} + +std::expected +HandoffSigningKey::sign(const TicketClaims& claims) const { + if (key_ == PSA_KEY_ID_NULL) + return std::unexpected(HandoffTicketError::invalid_key); + if (!structurally_valid(claims)) + return std::unexpected(HandoffTicketError::invalid_claims); + HandoffTicket out{}; + std::ranges::copy(marker, out.begin()); + put(out, 16, ticket_version, 2); + out.at(18) = environment_byte(environment_); + out.at(19) = 0; + put(out, 20, key_id_, 4); + std::ranges::copy(claims.transfer, out.begin() + 24); + std::ranges::copy(claims.account.bytes, out.begin() + 40); + put(out, 56, claims.world.world, 8); + put(out, 64, claims.world.frame, 8); + put(out, 72, claims.source, 8); + put(out, 80, claims.destination, 8); + put(out, 88, claims.expires_at, 4); + put(out, 92, claims.session_expires_at, 4); + std::size_t length = 0; + if (psa_sign_message(key_, algorithm, out.data(), signed_end, out.data() + signed_end, + signature_bytes, &length) != PSA_SUCCESS || + length != signature_bytes) + return std::unexpected(HandoffTicketError::crypto); + return out; +} + +std::expected HandoffSigningKey::public_key() const { + if (key_ == PSA_KEY_ID_NULL) + return std::unexpected(HandoffTicketError::invalid_key); + GrantPublicKey out{}; + std::size_t length = 0; + if (psa_export_public_key(key_, out.data(), out.size(), &length) != PSA_SUCCESS || + length != out.size()) + return std::unexpected(HandoffTicketError::crypto); + return out; +} + +std::expected +HandoffVerifier::create(DeploymentEnvironment environment, world::WorldIdentity world, + std::uint64_t region) { + if (world.world == 0 || world.frame == 0 || region == 0) + return std::unexpected(HandoffTicketError::invalid_claims); + if (psa_crypto_init() != PSA_SUCCESS) + return std::unexpected(HandoffTicketError::crypto); + return HandoffVerifier{environment, world, region}; +} + +HandoffVerifier::HandoffVerifier(HandoffVerifier&& other) noexcept + : environment_{other.environment_}, world_{other.world_}, region_{other.region_}, + keys_{std::exchange(other.keys_, {})} {} + +HandoffVerifier& HandoffVerifier::operator=(HandoffVerifier&& other) noexcept { + if (this != &other) { + destroy(); + environment_ = other.environment_; + world_ = other.world_; + region_ = other.region_; + keys_ = std::exchange(other.keys_, {}); + } + return *this; +} + +HandoffVerifier::~HandoffVerifier() { + destroy(); +} + +void HandoffVerifier::destroy() noexcept { + for (const auto& k : keys_) + (void)psa_destroy_key(k.key); + keys_.clear(); +} + +std::expected +HandoffVerifier::add_key(std::uint64_t source_region, std::uint32_t key_id, + std::span public_key) { + if (source_region == 0 || source_region == region_ || key_id == 0 || + public_key.size() != grant_public_key_bytes) + return std::unexpected(HandoffTicketError::invalid_key); + if (std::ranges::any_of(keys_, [&](const Key& k) { return k.key_id == key_id; })) + return std::unexpected(HandoffTicketError::duplicate_key); + if (keys_.size() >= max_keys) + return std::unexpected(HandoffTicketError::too_many_keys); + psa_key_attributes_t a = PSA_KEY_ATTRIBUTES_INIT; + psa_set_key_type(&a, PSA_KEY_TYPE_ECC_PUBLIC_KEY(PSA_ECC_FAMILY_SECP_R1)); + psa_set_key_bits(&a, 256); + psa_set_key_usage_flags(&a, PSA_KEY_USAGE_VERIFY_MESSAGE); + psa_set_key_algorithm(&a, algorithm); + auto key = import_key(a, public_key); + psa_reset_key_attributes(&a); + if (!key) + return std::unexpected(key.error()); + keys_.push_back({source_region, key_id, *key}); + return {}; +} + +std::expected +HandoffVerifier::verify(std::span ticket, std::uint64_t now_seconds) const { + if (ticket.size() != handoff_ticket_bytes) + return std::unexpected(HandoffTicketError::malformed); + // The key id only selects which key must verify; it is itself signed. + const auto key_id = static_cast(get(ticket, 20, 4)); + const auto key = std::ranges::find_if(keys_, [&](const Key& k) { return k.key_id == key_id; }); + if (key == keys_.end()) + return std::unexpected(HandoffTicketError::unknown_key); + const auto status = psa_verify_message(key->key, algorithm, ticket.data(), signed_end, + ticket.data() + signed_end, signature_bytes); + if (status == PSA_ERROR_INVALID_SIGNATURE) + return std::unexpected(HandoffTicketError::bad_signature); + if (status != PSA_SUCCESS) + return std::unexpected(HandoffTicketError::crypto); + if (!std::equal(marker.begin(), marker.end(), ticket.begin())) + return std::unexpected(HandoffTicketError::wrong_marker); + if (get(ticket, 16, 2) != ticket_version || ticket[19] != 0) + return std::unexpected(HandoffTicketError::unsupported_version); + if (ticket[18] != environment_byte(environment_)) + return std::unexpected(HandoffTicketError::wrong_environment); + TicketClaims c; + std::copy_n(ticket.begin() + 24, c.transfer.size(), c.transfer.begin()); + std::copy_n(ticket.begin() + 40, c.account.bytes.size(), c.account.bytes.begin()); + c.world = {get(ticket, 56, 8), get(ticket, 64, 8)}; + c.source = get(ticket, 72, 8); + c.destination = get(ticket, 80, 8); + c.expires_at = static_cast(get(ticket, 88, 4)); + c.session_expires_at = static_cast(get(ticket, 92, 4)); + if (!structurally_valid(c)) + return std::unexpected(HandoffTicketError::invalid_claims); + if (c.source != key->region) + return std::unexpected(HandoffTicketError::wrong_source); + if (c.world.world != world_.world || c.world.frame != world_.frame || c.destination != region_) + return std::unexpected(HandoffTicketError::wrong_scope); + if (now_seconds >= c.expires_at || now_seconds >= c.session_expires_at || + c.expires_at - now_seconds > max_ticket_lifetime) + return std::unexpected(HandoffTicketError::expired); + return VerifiedHandoffTicket{c}; +} +} // namespace evo::network diff --git a/src/server/session/postgres_handoff_ledger.cpp b/src/server/session/postgres_handoff_ledger.cpp new file mode 100644 index 0000000..d463cbf --- /dev/null +++ b/src/server/session/postgres_handoff_ledger.cpp @@ -0,0 +1,70 @@ +#include "evo/server/postgres_handoff_ledger.hpp" +#include "evo/persistence/account_control_store.hpp" +#include + +namespace evo::server { +namespace { +using network::HandoffLedgerError; +using persistence::ProbeStoreError; + +// The region lease itself fenced (EVL02/EVL06) versus this transfer not being ours (EVL13). +bool lease_fenced(const persistence::PgFailure& f) { + const std::string_view state(f.sqlstate.data(), 5); + return state == "EVL02" || state == "EVL06"; +} +HandoffLedgerError ledger_error(const persistence::ProbeStoreFailure& f) { + switch (f.kind) { + case ProbeStoreError::fenced: + return lease_fenced(f.cause) ? HandoffLedgerError::fenced : HandoffLedgerError::refused; + case ProbeStoreError::unknown_transfer: + case ProbeStoreError::not_staged: + case ProbeStoreError::invalid: + case ProbeStoreError::exhausted: + return HandoffLedgerError::refused; + default: + return HandoffLedgerError::unavailable; + } +} +} // namespace + +std::expected +PostgresHandoffLedger::admit(const network::TicketClaims& ticket, std::uint64_t session) { + const auto lease = lease_(); + if (!lease) + return std::unexpected(HandoffLedgerError::fenced); + auto* db = db_->get(); + if (!db) + return std::unexpected(HandoffLedgerError::unavailable); + const auto fail = [&](const persistence::ProbeStoreFailure& f) { + if (f.kind == ProbeStoreError::store || f.kind == ProbeStoreError::unknown) + db_->broken(); // Unknown connection state: reconnect next time. + return std::unexpected(ledger_error(f)); + }; + const auto staged = + persistence::stage_probe_transfer(*db, key_, *lease, ticket.transfer, timeout_); + if (!staged) + return fail(staged.error()); + if (staged->account != ticket.account.bytes || staged->source != ticket.source || + staged->destination != key_.region || staged->state == persistence::TransferState::aborted) + return std::unexpected(HandoffLedgerError::refused); + const auto committed = + persistence::commit_probe_transfer(*db, key_, *lease, ticket.transfer, timeout_); + if (!committed) + return fail(committed.error()); + if (committed->state != persistence::TransferState::committed) + return std::unexpected(HandoffLedgerError::refused); // Aborted meanwhile. + const auto control = persistence::handoff_account_control( + *db, key_, *lease, ticket.account.bytes, ticket.transfer, session, duration_, timeout_); + if (!control) { + const auto kind = control.error().kind; + if (kind == persistence::ControlStoreError::store || + kind == persistence::ControlStoreError::unknown) { + db_->broken(); + return std::unexpected(HandoffLedgerError::unavailable); + } + return std::unexpected(lease_fenced(control.error().cause) ? HandoffLedgerError::fenced + : HandoffLedgerError::refused); + } + return network::ControlLease{control->generation, control->wait, control->granted}; +} +} // namespace evo::server diff --git a/src/server/session/region_sessions.cpp b/src/server/session/region_sessions.cpp index 709a166..e7ef3b7 100644 --- a/src/server/session/region_sessions.cpp +++ b/src/server/session/region_sessions.cpp @@ -38,6 +38,27 @@ SessionCloseReason reason_for(network::ControlLedgerError e) { return SessionCloseReason::capacity; // Not decided: the client may retry later. } } +SessionCloseReason reason_for(network::HandoffTicketError e) { + switch (e) { + case network::HandoffTicketError::wrong_environment: + case network::HandoffTicketError::wrong_scope: + return SessionCloseReason::wrong_scope; + case network::HandoffTicketError::expired: + return SessionCloseReason::expired; + default: + return SessionCloseReason::unauthenticated; + } +} +SessionCloseReason reason_for(network::HandoffLedgerError e) { + switch (e) { + case network::HandoffLedgerError::refused: + return SessionCloseReason::unauthenticated; + case network::HandoffLedgerError::fenced: + return SessionCloseReason::shutdown; + default: + return SessionCloseReason::capacity; + } +} SessionCloseReason reason_for(SessionGrantError e) { return e == SessionGrantError::wrong_environment ? SessionCloseReason::wrong_scope : SessionCloseReason::unauthenticated; @@ -62,15 +83,16 @@ struct RegionSessions::Impl { }; Impl(RegionSessionsConfig c, std::unique_ptr e, - network::GrantVerifier v, network::SessionControl s, network::IntentAdmission i, - network::ReplicationServer r) + network::GrantVerifier v, std::optional h, + network::SessionControl s, network::IntentAdmission i, network::ReplicationServer r) : config{std::move(c)}, endpoint{std::move(e)}, verifier{std::move(v)}, - control{std::move(s)}, intents{std::move(i)}, replication{std::move(r)}, - markers{config.control.max_sessions} {} + tickets{std::move(h)}, control{std::move(s)}, intents{std::move(i)}, + replication{std::move(r)}, markers{config.control.max_sessions} {} RegionSessionsConfig config; std::unique_ptr endpoint; network::GrantVerifier verifier; + std::optional tickets; // Handoff keys configured. network::SessionControl control; network::IntentAdmission intents; network::ReplicationServer replication; @@ -137,6 +159,8 @@ struct RegionSessions::Impl { return close(c, SessionCloseReason::protocol, now); if (!control.attempt(now_seconds)) // Region-wide, before signature work. return close(c, SessionCloseReason::rate_limited, now); + if (network::looks_like_handoff_ticket(m.grant)) + return ticket_hello(c, m, now_seconds, now); const auto grant = verifier.verify(m.grant); if (!grant) return close(c, reason_for(grant.error()), now); @@ -154,12 +178,47 @@ struct RegionSessions::Impl { return close(c, reason_for(claimed.error()), now); lease = *claimed; } - const auto opened = control.open(*grant, now_seconds); + admitted(c, control.open(*grant, now_seconds), lease, promised, claims.account, now_seconds, + now); + } + + // M10.8b: a Hello carrying a handoff ticket (ADR-0096). Verified, checked locally, then + // made durable (stage, commit, control) before the local admission. + void ticket_hello(Connection& c, const network::SessionHello& m, std::uint64_t now_seconds, + Clock::time_point now) { + if (!tickets) + return close(c, SessionCloseReason::unauthenticated, now); + const auto ticket = tickets->verify(m.grant, now_seconds); + if (!ticket) + return close(c, reason_for(ticket.error()), now); + const auto& claims = ticket->claims(); + c.account = network::log_label(claims.account); + if (const auto checked = control.check_handoff(*ticket, now_seconds); !checked) + return close(c, reason_for(checked.error()), now); + std::optional lease; + const auto promised = control.next_session(); + if (config.handoff) { + auto moved = config.handoff->admit(claims, promised); + if (!moved) + return close(c, reason_for(moved.error()), now); + lease = *moved; + } else if (config.ledger) { + return close(c, SessionCloseReason::capacity, now); // Misconfigured: fail closed. + } + admitted(c, control.open_handoff(*ticket, now_seconds), lease, promised, claims.account, + now_seconds, now); + } + + // Common to grants and tickets: the local admission's result after any durable claim. + void admitted(Connection& c, const std::expected& opened, + const std::optional& lease, std::uint64_t promised, + const network::AccountId& account, std::uint64_t now_seconds, + Clock::time_point now) { if (!opened || opened->session != promised) { if (opened) (void)control.close(opened->session).has_value(); if (lease) - config.ledger->release(claims.account, lease->generation); + config.ledger->release(account, lease->generation); return close(c, opened ? SessionCloseReason::capacity : reason_for(opened.error()), now); } @@ -167,7 +226,7 @@ struct RegionSessions::Impl { if (auto* old = by_session(opened->superseded)) close(*old, SessionCloseReason::superseded, now); c.session = opened->session; - c.account_id = claims.account; + c.account_id = account; c.welcome.session = opened->session; c.welcome.epoch = opened->epoch; c.welcome.world = config.control.world.world; @@ -334,7 +393,7 @@ RegionSessions::~RegionSessions() = default; std::expected, RegionSessionsError> RegionSessions::create(RegionSessionsConfig config) { // Connections beyond sessions are headroom for logins and closes still flushing. - if (config.issuer_keys.empty() || + if (config.issuer_keys.empty() || (config.handoff != nullptr && config.ledger == nullptr) || config.transport.limits.max_connections < config.control.max_sessions || config.hello_deadline.count() <= 0 || config.close_flush.count() <= 0 || config.renew_interval.count() <= 0 || config.safety_margin.count() <= 0) @@ -348,6 +407,17 @@ RegionSessions::create(RegionSessionsConfig config) { for (const auto& k : config.issuer_keys) if (!verifier->add_key(k.key_id, k.public_key)) return std::unexpected(RegionSessionsError::keys); + std::optional tickets; + if (!config.handoff_keys.empty()) { + auto made = network::HandoffVerifier::create(config.control.environment, + config.control.world, config.control.region); + if (!made) + return std::unexpected(RegionSessionsError::keys); + for (const auto& k : config.handoff_keys) + if (!made->add_key(k.source_region, k.key_id, k.public_key)) + return std::unexpected(RegionSessionsError::keys); + tickets.emplace(std::move(*made)); + } config.intents.max_sessions = config.control.max_sessions; auto intents = network::IntentAdmission::create(config.intents); if (!intents) @@ -360,9 +430,9 @@ RegionSessions::create(RegionSessionsConfig config) { auto endpoint = network::quic::Endpoint::serve(config.transport); if (!endpoint) return std::unexpected(RegionSessionsError::transport); - return std::unique_ptr{new RegionSessions{ - std::make_unique(std::move(config), std::move(*endpoint), std::move(*verifier), - std::move(*control), std::move(*intents), std::move(*replication))}}; + return std::unique_ptr{new RegionSessions{std::make_unique( + std::move(config), std::move(*endpoint), std::move(*verifier), std::move(tickets), + std::move(*control), std::move(*intents), std::move(*replication))}}; } void RegionSessions::poll(const HostFacts& facts, std::uint64_t now_seconds, diff --git a/tests/network_control.cpp b/tests/network_control.cpp index 3248200..b9c5fb4 100644 --- a/tests/network_control.cpp +++ b/tests/network_control.cpp @@ -1,5 +1,6 @@ #include "evo/identity/identity.hpp" #include "evo/network/dev_grant.hpp" +#include "evo/network/handoff_ticket.hpp" #include "evo/network/intent_admission.hpp" #include "evo/network/session_control.hpp" #include "evo/network/session_grant.hpp" @@ -619,10 +620,99 @@ void intent_admission() { } } // namespace +// M10.8b handoff tickets (ADR-0096): signed by the source region's handoff key, verified +// by the destination against keys bound to source regions; then admitted by SessionControl. +TicketClaims ticket(const AccountId& who, std::uint8_t transfer, std::uint64_t source = 4, + std::uint32_t expires = now + 30, std::uint32_t session = now + 200) { + TicketClaims c; + c.transfer.fill(transfer); + c.account = who; + c.world = world_id; + c.source = source; + c.destination = region; + c.expires_at = expires; + c.session_expires_at = session; + return c; +} +void handoff_tickets() { + const auto alice = account(1), bob = account(2); + auto source = *HandoffSigningKey::generate(DeploymentEnvironment::dev, 41); + auto other = *HandoffSigningKey::generate(DeploymentEnvironment::dev, 42); + auto verifier = *HandoffVerifier::create(DeploymentEnvironment::dev, world_id, region); + CHECK(verifier.add_key(4, 41, *source.public_key())); + CHECK(verifier.add_key(5, 42, *other.public_key())); + CHECK(refused(verifier.add_key(6, 41, *other.public_key()), HandoffTicketError::duplicate_key)); + CHECK(refused(verifier.add_key(region, 43, *other.public_key()), + HandoffTicketError::invalid_key)); // Never its own region. + const auto good = source.sign(ticket(alice, 0x71)); + CHECK(good && looks_like_handoff_ticket(*good)); + const auto v = verifier.verify(*good, now); + CHECK(v && v->claims().account == alice && v->claims().source == 4 && + v->claims().destination == region && v->claims().transfer[0] == 0x71 && + v->claims().session_expires_at == now + 200); + // Every signed byte matters; the signature too. + for (std::size_t at = 0; at < handoff_ticket_bytes; at += 7) { + auto bad = *good; + bad.at(at) ^= 0x10; + CHECK(!verifier.verify(bad, now)); + } + // A key may only sign for its own region; scope, environment and times are checked. + CHECK(refused(verifier.verify(*other.sign(ticket(alice, 0x72, 4)), now), + HandoffTicketError::wrong_source)); + auto elsewhere = ticket(alice, 0x73); + elsewhere.destination = 12; + CHECK(refused(verifier.verify(*source.sign(elsewhere), now), HandoffTicketError::wrong_scope)); + elsewhere = ticket(alice, 0x73); + elsewhere.world = {7, 4}; + CHECK(refused(verifier.verify(*source.sign(elsewhere), now), HandoffTicketError::wrong_scope)); + CHECK(refused(verifier.verify(*good, now + 30), HandoffTicketError::expired)); + CHECK(refused(verifier.verify(*source.sign(ticket(alice, 0x74, 4, now + 121)), now), + HandoffTicketError::expired)); // Longer than the maximum lifetime. + CHECK(refused(verifier.verify(*source.sign(ticket(alice, 0x75, 4, now + 30, now)), now), + HandoffTicketError::expired)); // The session would already have ended. + auto stage_key = *HandoffSigningKey::generate(DeploymentEnvironment::stage, 44); + CHECK(verifier.add_key(6, 44, *stage_key.public_key())); + CHECK(refused(verifier.verify(*stage_key.sign(ticket(alice, 0x76, 6)), now), + HandoffTicketError::wrong_environment)); + auto unknown = *HandoffSigningKey::generate(DeploymentEnvironment::dev, 99); + CHECK(refused(verifier.verify(*unknown.sign(ticket(alice, 0x77)), now), + HandoffTicketError::unknown_key)); + CHECK(refused(source.sign(ticket(alice, 0x78, region)), HandoffTicketError::invalid_claims)); + CHECK(refused(source.sign(ticket(AccountId{}, 0x78)), HandoffTicketError::invalid_claims)); + // Tickets and grants never verify as each other. + Keys dev{DeploymentEnvironment::dev}; + CHECK(!dev.verifier.verify(*good)); + const auto grant = dev.signer.sign(claims(alice, 1)); + CHECK(grant && !looks_like_handoff_ticket(*grant) && !verifier.verify(*grant, now)); + + // SessionControl: a ticket opens a session for its account, once; it supersedes a grant + // session; the session ends at the ticket's session expiry, capped at the maximum + // grant lifetime from now. + auto c = config(); + c.max_account_attempts = 16; + auto control = *SessionControl::create(c); + const auto by_grant = control.open(dev.verified(claims(alice, 3)), now); + CHECK(by_grant); + CHECK(control.check_handoff(*v, now)); + const auto opened = control.open_handoff(*v, now); + CHECK(opened && opened->superseded == by_grant->session && opened->expires_at == now + 200 && + control.holder(alice) == opened->session); + CHECK(refused(control.check_handoff(*v, now + 1), ControlError::stale_grant)); // Replay. + CHECK(refused(control.open_handoff(*v, now + 1), ControlError::stale_grant)); + const auto long_session = + verifier.verify(*source.sign(ticket(bob, 0x79, 4, now + 30, now + 4000)), now); + CHECK(long_session); + const auto capped = control.open_handoff(*long_session, now); + CHECK(capped && capped->expires_at == now + c.max_grant_lifetime); + // A later grant for the account still opens normally (serials are untouched). + CHECK(control.open(dev.verified(claims(alice, 4)), now + 2)); +} + void control_tests() { grants(); identity_adapter(); control_rules(); + handoff_tickets(); session_codec(); intent_admission(); durable_actions(); diff --git a/tests/probe_handoff_store_tests.cpp b/tests/probe_handoff_store_tests.cpp index 66f8b40..b642df9 100644 --- a/tests/probe_handoff_store_tests.cpp +++ b/tests/probe_handoff_store_tests.cpp @@ -8,6 +8,9 @@ #include "evo/persistence/probe_store.hpp" #include "evo/persistence/region_checkpoint.hpp" #include "evo/persistence/region_lease_store.hpp" +#ifdef EVO_POSTGRES_SESSIONS +#include "evo/server/postgres_handoff_ledger.hpp" +#endif #include #include #include @@ -364,6 +367,64 @@ void control_handoff(World& w) { CHECK(release_account_control(db, w.b, w.lb, eve, 3, 5s).value_or(false)); invariants(*w.admin, w.probes); } +#ifdef EVO_POSTGRES_SESSIONS +// The session layer's HandoffLedger over these functions: stage, commit and control in one +// admission; idempotent on retry; refused for aborted, foreign or unknown transfers. +void handoff_ledger(World& w) { + auto& db = *w.db; + const auto frank = id(0x47); + w.open(w.a, w.la, frank); + ++w.probes; + CHECK(claim_account_control(db, w.a, w.la, frank, 1, 31, 20000ms, 5s)); + const auto t = id(0x76, 1); + CHECK(state_of(prepare_probe_transfer(db, w.a, w.la, frank, 1, t, 2, 3, 4, -7, 5s)) == + TransferState::prepared); + CHECK(release_account_control(db, w.a, w.la, frank, 1, 5s).value_or(false)); + std::optional current = w.lb; + evo::server::PgSlot slot{PgOptions{env("PGHOST"), + {}, + env("PGPORT"), + env("PGDATABASE"), + env("EVO_PG_RUNTIME_USER"), + {}, + {}}, + 5s}; + evo::server::PostgresHandoffLedger ledger{slot, w.b, [&] { return current; }}; + evo::network::TicketClaims ticket; + ticket.transfer = t; + ticket.account.bytes = frank; + ticket.source = 1; + ticket.destination = 2; + const auto admitted = ledger.admit(ticket, 41); + CHECK(admitted && admitted->generation == 2 && admitted->wait == 0ms); + const auto r = w.open(w.b, w.lb, frank); + CHECK(r.region == 2 && r.generation == 2 && r.x == 3 && !r.transfer); + // A retried login after an undecided outcome converges (control moves on again). + const auto again = ledger.admit(ticket, 42); + CHECK(again && again->generation == 3); + // Refusals: another account, an unknown transfer, an aborted transfer; no lease. + auto wrong = ticket; + wrong.account.bytes = id(0x48); + CHECK(!ledger.admit(wrong, 43) && + ledger.admit(wrong, 43).error() == evo::network::HandoffLedgerError::refused); + auto unknown = ticket; + unknown.transfer = id(0x76, 9); + CHECK(ledger.admit(unknown, 44).error() == evo::network::HandoffLedgerError::refused); + const auto t2 = id(0x76, 2); + CHECK(state_of(prepare_probe_transfer(db, w.b, w.lb, frank, 2, t2, 1, 3, 4, -7, 5s)) == + TransferState::prepared); + CHECK(state_of(abort_probe_transfer(db, w.b, w.lb, t2, 5s)) == TransferState::aborted); + auto aborted = ticket; + aborted.transfer = t2; + aborted.source = 2; + evo::server::PostgresHandoffLedger at_a{slot, w.a, [&] { return std::optional{w.la}; }}; + CHECK(at_a.admit(aborted, 45).error() == evo::network::HandoffLedgerError::refused); + current.reset(); + CHECK(ledger.admit(ticket, 46).error() == evo::network::HandoffLedgerError::fenced); + CHECK(release_account_control(db, w.b, w.lb, frank, 3, 5s).value_or(false)); + invariants(*w.admin, w.probes); +} +#endif } // namespace void run_probe_handoff_store_tests() { @@ -372,6 +433,9 @@ void run_probe_handoff_store_tests() { restarts(w); aborts_and_races(w); control_handoff(w); +#ifdef EVO_POSTGRES_SESSIONS + handoff_ledger(w); +#endif CHECK(release_region_lease(*w.db, w.a, w.la, 5s)); CHECK(release_region_lease(*w.db, w.b, w.lb, 5s)); CHECK(release_region_lease(*w.db, w.c, w.lc, 5s)); diff --git a/tests/quic_sessions.cpp b/tests/quic_sessions.cpp index 29d87ed..5dadd6e 100644 --- a/tests/quic_sessions.cpp +++ b/tests/quic_sessions.cpp @@ -4,6 +4,7 @@ // grants is injected; deadlines use the real monotonic clock. #include "evo/client/region_session.hpp" #include "evo/network/dev_credentials.hpp" +#include "evo/network/handoff_ticket.hpp" #include "evo/network/session_grant.hpp" #include "evo/server/region_sessions.hpp" #include @@ -105,7 +106,8 @@ struct Issuer { struct Harness { explicit Harness(const Files& f, std::size_t max_sessions = 4, - std::uint32_t region_attempts = 64, ControlLedger* ledger = nullptr) + std::uint32_t region_attempts = 64, ControlLedger* ledger = nullptr, + const std::function& tweak = {}) : files{f} { server::RegionSessionsConfig c; c.transport.certificate_pem_file = f.certificate.string(); @@ -123,6 +125,8 @@ struct Harness { c.ledger = ledger; c.renew_interval = std::chrono::milliseconds{100}; c.safety_margin = std::chrono::milliseconds{50}; + if (tweak) + tweak(c); auto made = RegionSessions::create(std::move(c)); CHECK(made.has_value()); server = std::move(*made); @@ -546,6 +550,81 @@ void snapshots_over_quic(const Files& f) { CHECK(a->state() == RegionSessionState::established); } +// M10.8b: a Hello carrying a handoff ticket (ADR-0096) instead of a grant. +struct FakeHandoff final : HandoffLedger { + std::expected admit(const TicketClaims& ticket, + std::uint64_t session) override { + if (error) + return std::unexpected(*error); + admitted.emplace_back(ticket, session); + return ControlLease{100 + admitted.size(), {}, std::chrono::milliseconds{20000}}; + } + std::optional error; + std::vector> admitted; +}; +void ticket_login(const Files& f) { + auto source = *HandoffSigningKey::generate(DeploymentEnvironment::dev, 41); + const auto ticket = [&](const AccountId& who, std::uint8_t transfer, + std::uint64_t destination = region) { + TicketClaims c; + c.transfer.fill(transfer); + c.account = who; + c.world = world_id; + c.source = 4; + c.destination = destination; + c.expires_at = start + 30; + c.session_expires_at = start + 90; + const auto t = source.sign(c); + CHECK(t.has_value()); + return *t; + }; + const auto alice = account(1); + // A region without handoff keys refuses every ticket. + { + Harness plain{f}; + CHECK(refused_with(plain, ticket(alice, 0x61), Reason::unauthenticated)); + } + // A handoff ledger needs the control ledger (control renews through it). + { + FakeHandoff handoff; + server::RegionSessionsConfig c; + c.transport.certificate_pem_file = f.certificate.string(); + c.transport.key_pem_file = f.key.string(); + c.control.environment = DeploymentEnvironment::dev; + c.control.world = world_id; + c.control.region = region; + c.control.epoch = 5; + c.issuer_keys.push_back({1, *Issuer{}.key.public_key()}); + c.handoff = &handoff; + CHECK(!RegionSessions::create(std::move(c))); + } + FakeLedger ledger; + FakeHandoff handoff; + Harness h{f, 4, 64, &ledger, [&](server::RegionSessionsConfig& c) { + c.handoff_keys.push_back({4, 41, *source.public_key()}); + c.handoff = &handoff; + }}; + // Admitted: the durable side ran first, for the session Welcome then names; the + // session ends at the ticket's session expiry. + auto a = h.connect(ticket(alice, 0x62)); + CHECK(h.settled(*a) && a->state() == RegionSessionState::established); + const auto& w = must(a->welcome()); + CHECK(handoff.admitted.size() == 1 && handoff.admitted[0].second == w.session && + handoff.admitted[0].first.account == alice && w.expires_at == start + 90); + CHECK(h.server->holder(alice) == w.session && ledger.claims.empty()); + // Control renews through the control ledger under the handoff's generation. + CHECK(h.until([&] { return !ledger.renewed.empty(); })); + CHECK(ledger.renewed.front() == 101); + // Replay, another destination, and a refused durable step are all refused. + CHECK(refused_with(h, ticket(alice, 0x62), Reason::stale_grant)); + CHECK(refused_with(h, ticket(alice, 0x63, 12), Reason::wrong_scope)); + handoff.error = HandoffLedgerError::refused; + CHECK(refused_with(h, ticket(account(2), 0x64), Reason::unauthenticated)); + handoff.error = HandoffLedgerError::unavailable; + CHECK(refused_with(h, ticket(account(3), 0x65), Reason::capacity)); + CHECK(a->state() == RegionSessionState::established && handoff.admitted.size() == 1); +} + void durable_control(const Files& f) { FakeLedger ledger; Harness h{f, 4, 64, &ledger}; @@ -622,6 +701,7 @@ int main() try { durable_control(files); intentions_and_actions(files); snapshots_over_quic(files); + ticket_login(files); std::filesystem::remove_all(files.dir); std::puts("quic session tests passed"); return 0;