#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. }; // What the destination now owns: the account's control lease and the probe's state after // the committed switch (its generation and position, in micrometres). struct HandoffAdmission { ControlLease lease; std::uint64_t generation{}; std::int64_t x{}, y{}; }; 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