Add M10.8b signed handoff tickets and ticket admission
Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 1m55s
Foundation / checks (client) (push) Successful in 12m40s
Foundation / checks (postgres) (push) Canceled after 4s
Foundation / checks (network) (push) Successful in 12m53s
Foundation / checks (tsan) (push) Successful in 7m55s
Foundation / checks (checks) (push) Successful in 31m47s
Foundation / postgres-tools (push) Skipped
Foundation / server-image (push) Skipped
Foundation / image (push) Skipped

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 <noreply@anthropic.com>
This commit is contained in:
dingo
2026-10-06 18:32:14 -04:00
co-authored by Claude Opus 5.5
parent 6a645ef7e4
commit 0ce51077b1
18 changed files with 1039 additions and 19 deletions
+3 -3
View File
@@ -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()
+2 -1
View File
@@ -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).
+3 -2
View File
@@ -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
+5 -1
View File
@@ -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
+29
View File
@@ -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).
+41
View File
@@ -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).
+149
View File
@@ -0,0 +1,149 @@
#pragma once
#include "evo/network/session_control.hpp"
#include "evo/network/session_grant.hpp"
#include <array>
#include <cstddef>
#include <cstdint>
#include <expected>
#include <span>
#include <vector>
// 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<std::uint8_t, handoff_ticket_bytes>;
using TransferId = std::array<std::uint8_t, 16>;
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<const std::uint8_t> bytes) noexcept;
// A region's handoff signing key (PSA, non-exportable private part). Move-only.
class HandoffSigningKey {
public:
[[nodiscard]] static std::expected<HandoffSigningKey, HandoffTicketError>
generate(DeploymentEnvironment environment, std::uint32_t key_id);
[[nodiscard]] static std::expected<HandoffSigningKey, HandoffTicketError>
import(DeploymentEnvironment environment, std::uint32_t key_id,
std::span<const std::uint8_t> 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<HandoffTicket, HandoffTicketError>
sign(const TicketClaims& claims) const;
[[nodiscard]] std::expected<GrantPublicKey, HandoffTicketError> 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<HandoffVerifier, HandoffTicketError>
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<void, HandoffTicketError>
add_key(std::uint64_t source_region, std::uint32_t key_id,
std::span<const std::uint8_t> 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<VerifiedHandoffTicket, HandoffTicketError>
verify(std::span<const std::uint8_t> 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<Key> 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<ControlLease, HandoffLedgerError>
admit(const TicketClaims& ticket, std::uint64_t session) = 0;
protected:
HandoffLedger(HandoffLedger&&) = default;
HandoffLedger& operator=(HandoffLedger&&) = default;
};
} // namespace evo::network
+17
View File
@@ -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<OpenedSession, ControlError> 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<void, ControlError>
check_handoff(const VerifiedHandoffTicket& ticket, std::uint64_t now_seconds) const;
[[nodiscard]] std::expected<OpenedSession, ControlError>
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<std::uint64_t, ControlError>
@@ -139,6 +149,12 @@ class SessionControl {
[[nodiscard]] bool forgettable(const Account& account, std::uint64_t now_seconds) const;
[[nodiscard]] std::expected<Account*, ControlError> admit(const VerifiedSessionGrant& grant,
std::uint64_t now_seconds);
[[nodiscard]] std::optional<ControlError> ticket_error(const VerifiedHandoffTicket& ticket,
std::uint64_t now_seconds) const;
struct UsedTicket {
std::array<std::uint8_t, 16> 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<Account> accounts_;
std::vector<UsedTicket> used_tickets_; // At most max_accounts, pruned at expiry.
};
// Durable per-world account control (10.3c, schema v10). The region host implements it
@@ -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 <chrono>
#include <functional>
#include <optional>
#include <utility>
// 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<std::optional<persistence::LeaseGrant>()>;
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<network::ControlLease, network::HandoffLedgerError>
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
+16
View File
@@ -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<HandoffKey> handoff_keys;
network::HandoffLedger* handoff{};
};
// The region host's authority, read once per poll.
struct HostFacts {
+33
View File
@@ -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).
+77
View File
@@ -1,4 +1,5 @@
#include "evo/network/session_control.hpp"
#include "evo/network/handoff_ticket.hpp"
#include <algorithm>
namespace evo::network {
@@ -154,6 +155,82 @@ std::expected<OpenedSession, ControlError> SessionControl::open(const VerifiedSe
return opened;
}
std::optional<ControlError> 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<void, ControlError> 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<std::size_t>(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<OpenedSession, ControlError>
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<std::uint64_t>(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<std::uint64_t, ControlError>
SessionControl::refresh(std::uint64_t session, const VerifiedSessionGrant& grant,
std::uint64_t now_seconds) {
+245
View File
@@ -0,0 +1,245 @@
#include "evo/network/handoff_ticket.hpp"
#include <algorithm>
#include <psa/crypto.h>
#include <utility>
namespace evo::network {
namespace {
constexpr std::array<std::uint8_t, 16> 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<std::uint8_t>(static_cast<std::uint8_t>(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<std::uint8_t>(v >> (8 * i));
}
std::uint64_t get(std::span<const std::uint8_t> 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<std::uint64_t>(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<std::uint32_t, HandoffTicketError> import_key(const psa_key_attributes_t& a,
std::span<const std::uint8_t> 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<const std::uint8_t> bytes) noexcept {
return bytes.size() == handoff_ticket_bytes &&
std::equal(marker.begin(), marker.end(), bytes.begin());
}
std::expected<HandoffSigningKey, HandoffTicketError>
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, HandoffTicketError>
HandoffSigningKey::import(DeploymentEnvironment environment, std::uint32_t key_id,
std::span<const std::uint8_t> 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<HandoffTicket, HandoffTicketError>
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<GrantPublicKey, HandoffTicketError> 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, HandoffTicketError>
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<void, HandoffTicketError>
HandoffVerifier::add_key(std::uint64_t source_region, std::uint32_t key_id,
std::span<const std::uint8_t> 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<VerifiedHandoffTicket, HandoffTicketError>
HandoffVerifier::verify(std::span<const std::uint8_t> 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<std::uint32_t>(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<std::uint32_t>(get(ticket, 88, 4));
c.session_expires_at = static_cast<std::uint32_t>(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
@@ -0,0 +1,70 @@
#include "evo/server/postgres_handoff_ledger.hpp"
#include "evo/persistence/account_control_store.hpp"
#include <string_view>
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<network::ControlLease, HandoffLedgerError>
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
+81 -11
View File
@@ -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<network::quic::Endpoint> e,
network::GrantVerifier v, network::SessionControl s, network::IntentAdmission i,
network::ReplicationServer r)
network::GrantVerifier v, std::optional<network::HandoffVerifier> 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<network::quic::Endpoint> endpoint;
network::GrantVerifier verifier;
std::optional<network::HandoffVerifier> 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<network::ControlLease> 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<network::OpenedSession, ControlError>& opened,
const std::optional<network::ControlLease>& 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<std::unique_ptr<RegionSessions>, 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<network::HandoffVerifier> 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<RegionSessions>{new RegionSessions{
std::make_unique<Impl>(std::move(config), std::move(*endpoint), std::move(*verifier),
std::move(*control), std::move(*intents), std::move(*replication))}};
return std::unique_ptr<RegionSessions>{new RegionSessions{std::make_unique<Impl>(
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,
+90
View File
@@ -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();
+64
View File
@@ -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 <array>
#include <atomic>
#include <chrono>
@@ -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<LeaseGrant> 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));
+81 -1
View File
@@ -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 <algorithm>
@@ -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<void(server::RegionSessionsConfig&)>& 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<ControlLease, HandoffLedgerError> 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<HandoffLedgerError> error;
std::vector<std::pair<TicketClaims, std::uint64_t>> 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;