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
+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;