Sans-I/O core state machines and path policy
Pure Sans-I/O design for PairingInitiator, PairingResponder, Roster, SessionMachine, and PathPlanner in tendril-core.
tendril-core implements pairing, session establishment, roster state, capability enforcement, and connection path selection with #![forbid(unsafe_code)], explicit virtual clocks (now_unix, now_ms), and zero async or OS I/O dependencies.
Driver loop
Callers pump raw bytes and explicit timestamps into the state machines and drain typed action slices:
bytes / commands + (now_unix, now_ms) ---> StateMachine ---> Vec<Action>
ResumableFrameReaderbounds buffered bytes atMAX_READ_BUFFER_LEN, decodes the 6-byte cleartext preamble first, and rejects declared outer frame lengths above65519before payload allocation.- Private key scalars (
StaticKeypair,SigningKeypaircovering Ed25519 and ML-DSA-65 seeds), pairing codes, Argon2id outputs, pure-RustNoise_XXhfsDH/KEM/cipher/chaining states (x25519-dalek+fips203), and decoded handshake/transport plaintext buffers usezeroizewrappers and redact secrets fromDebugoutput.
Pairing and roster trust transitions
| Component | Key Rules |
|---|---|
PairingManager |
Unbiased 31-char code sampling, 900 s default TTL, 5 failed claims burn all live codes, single-use burn even when a revoked peer claims a live code, 2-group LAN codes rejected on Remote paths |
PairingUri |
tendril://pair?v=1&... codec validating scheme, version, non-zero static key, 32-byte sh= signing hash pin, strict query parameters, control-character absence, and validated endpoint hints |
PairingInitiator / PairingResponder |
Decouples pair (pending) from host confirm_peer and mint_grant; validates HostHello.signing_pub against optional QR sh= hash or full key pins before emitting msg3 |
Roster |
Indexes peer entries cleanly, matches inbound Session peers strictly on full 32-byte static_pub, enforces non-zero pins (IncompletePin), stores 1984-byte hybrid signing keys, transitions immediately to revoked on trust-root rotation forks, and ingests monotonic signed CRLs |
Sealed session and path planner
SessionMachine: Drives in-tree pure-RustNoise_XXhfs_25519+MLKEM768_ChaChaPoly_SHA256, executes the initiatormsg2HostHello.signing_pub+ static pin/rotation abort gate before disclosing client static keys inmsg3, enforcesMAX_FRAME_LENpre-encryption so oversized plaintexts never advance nonces, checks grants viaauthorize_grantreturning structuredAuditEventrecords, and automatically triggers0x04 REKEYat1_048_576sent frames or15minutes while re-validating grants and CRLs onREKEYand0x03 REVOCATION.PathPlanner: Orders candidates strictly by(provider.rank(), !is_numeric_host, id)acrosslocal < direct < overlay < p2p < relay < broker, staggers Happy Eyeballs probes every250 ms, delays coldp2pprobing (500 ms) so higher rungs race unblocked, holds pinned paths for10 sbefore probing fall-up every30 s, and fails over immediately on active path faults.
Adversarial verification
In-process integration tests in crates/tendril-core/tests/adversarial.rs drive complete pair, confirm, mint, delegate, data, PING/PONG, frame-count and time-based auto-REKEY, key rotation, CRL revocation, and graceful CLOSE flows under 1-byte/odd-chunked I/O, frame drops/reordering/replay, bit-flips, oversized frames, cross-intent splicing, MITM handshake splicing, expired/burned pairing codes, incomplete pins, widened delegations, forged issuers, and trust-root vs. unanchored rotation forks.
Connections
Local graphLinked from
- Add Sans-I/O tendril-core state machines, path planner, and adversarial suiteLogs“Sans-I/O core state machines and path policy”