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>
  • ResumableFrameReader bounds buffered bytes at MAX_READ_BUFFER_LEN, decodes the 6-byte cleartext preamble first, and rejects declared outer frame lengths above 65519 before payload allocation.
  • Private key scalars (StaticKeypair, SigningKeypair covering Ed25519 and ML-DSA-65 seeds), pairing codes, Argon2id outputs, pure-Rust Noise_XXhfs DH/KEM/cipher/chaining states (x25519-dalek + fips203), and decoded handshake/transport plaintext buffers use zeroize wrappers and redact secrets from Debug output.

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-Rust Noise_XXhfs_25519+MLKEM768_ChaChaPoly_SHA256, executes the initiator msg2 HostHello.signing_pub + static pin/rotation abort gate before disclosing client static keys in msg3, enforces MAX_FRAME_LEN pre-encryption so oversized plaintexts never advance nonces, checks grants via authorize_grant returning structured AuditEvent records, and automatically triggers 0x04 REKEY at 1_048_576 sent frames or 15 minutes while re-validating grants and CRLs on REKEY and 0x03 REVOCATION.
  • PathPlanner: Orders candidates strictly by (provider.rank(), !is_numeric_host, id) across local < direct < overlay < p2p < relay < broker, staggers Happy Eyeballs probes every 250 ms, delays cold p2p probing (500 ms) so higher rungs race unblocked, holds pinned paths for 10 s before probing fall-up every 30 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 graph

Linked from