Stateless relay v1 and async runtime providers
Design for the stateless WSS ciphertext relay (spec/relay-v1.md), pluggable path providers (local, direct, relay), 6-point provider contract, rate limiting, and atomic persistence.
Tendril keeps the cryptographic trust boundary inside the Sans-I/O core while tendril-relay and tendril-runtime provide stateless ciphertext forwarding and concrete OS transports without modifying security invariants.
Stateless WebSocket relay (tendril-relay)
tendril-relay implements the normative control and bridge rules in spec/relay-v1.md (/v1/relay) and spec/relay-v2.md (/v2/relay) on top of native rustls TLS (wss://<host>/v1/relay and wss://<host>/v2/relay, with ws:// permitted on loopback fixtures):
- Challenge and anti-hijack proofs: Every
/v1/relayand/v2/relayconnection starts with a JSONchallengecontaining a fresh 32-byte CSPRNGnonce, the relay's boundhost, andmax_frame = 65521(plusepochon/v2/relay). On/v1/relay, listeners prove mailbox ownership using the 32-byte Ed25519relay_pubprefix with strict Ed25519 signatures bound to"tendril-relay-reg-v1\0" || host || nonceonregisterand"tendril-relay-accept-v1\0" || host || nonce || conn_idonaccept. On/v2/relay, listeners use hourly epochmailbox_idkeys and sign theepoch-bound"tendril-relay-reg-v2\0"/"tendril-relay-accept-v2\0"inputs defined inspec/relay-v2.md. Unownedacceptattempts fail with"unauthorized"without removing the legitimate pending dial. - Managed relay admission (Tiers 1-3 and Option 1A
--auth-scope): Both/v1/relayand/v2/relaysupport three composable stateless admission tiers (allowlist OR proof, not additive):- Tier 1 (Allowlist):
--allow-mailbox/--allow-mailboxes-fileadmits matching mailbox keys onregisterandacceptwithout an additional HMAC/ticket proof; an empty or comment-only file (0 valid keys) fails closed at startup. Because/v2/relaymailbox keys are hourly-rotatingmailbox_ids (spec/relay-v2.md), Tier 1 is practical primarily for/v1/relay. - Tier 2 (Shared HMAC):
--auth-secret-fileorTENDRIL_RELAY_AUTH_SECRETverifies HMAC-SHA256 proofs overtendril-relay-auth-v1\0. Secret files should use0600permissions;tendril-relayreadsTENDRIL_RELAY_AUTH_SECRETonce at startup rather than stripping process env. - Tier 3 (
RelayTicket):--issuer-pubverifies JCS-canonical Ed25519RelayTicketproofs (tendril-relay-ticket-v1\0,role: register | dial | any,1..=86400sTTL,+-30sclock skew). ARelayTicketis a bearer credential if exposed in untrusted channels or logs unless scoped totarget_puband a short TTL. - Option 1A (
--auth-scope <all|register-only>): Defaults toallwhenever any admission mechanism is active so bothregisteranddialrequire admission (closing/v1/relayand/v2/relaydial freeloading); underall, dial admission validatesauthright after decode before mailbox lookup or epoch skew checks. Passing--auth-scopewith no allowlist, secret, or issuer fails closed, and--auth-scope register-onlywith Tier 1 alone leavesdialopen because Tier 1 is peer-mailbox allowlisting.
- Tier 1 (Allowlist):
- Opaque binary forwarding: Once
readyis emitted to both sides, the relay forwards WebSocket binary frames verbatim. Non-binary frames afterreadyor frames exceeding65521bytes terminate both halves immediately without forwarding. - Bounded resource limits: An LRU-bounded per-IP/prefix (
/64IPv6) token bucket (max_tracked_ips = 4096, with an eviction-overflow throttle) gates incoming connections (using trusted-proxy right-to-leftForwarded/X-Forwarded-Forextraction only for configured proxy CIDRs) alongside active caps (max_total_connections = 4096,max_mailboxes = 1024,max_pending_per_mailbox = 8,max_active_per_ip = 64,max_active_per_mailbox = 64),15 saccept timeout,300 sidle stream timeout, and eager flush with a1 swrite backpressure timeout.
Runtime providers and 6-point contract (tendril-runtime)
All path implementations expose the PathStream, PathListener, and PathDialer traits with zero cryptographic or policy logic inside transports:
| Provider | Transport | Security and Bounds |
|---|---|---|
local |
Unix domain sockets | 0o600 socket file permissions, 1 s write backpressure timeout, 65521 B outer frame ceiling |
direct |
TCP (TCP_NODELAY) |
Optional IP allow-list filter, 1 s write backpressure timeout, 65521 B outer frame ceiling |
relay |
WebSocket (/v1/relay) |
rustls ring TLS provider for wss://, verifies challenge.host and max_frame, signed register and accept, 1 s write timeout |
Every built-in provider passes the 6-point contract suite in crates/tendril-runtime/tests/provider_contract.rs:
1 Band65519 B(MAX_FRAME_LEN) frames round-trip intact.64sequential frames preserve strict FIFO order.- Peer close is observed within
<= 2 s. - Slow-reader
1 sbackpressure terminates blocked writers cleanly without unbounded buffering. - Oversized
65520 Bouter frame bodies and65522 Braw chunks fail closed. - Intercepted wire bytes of a real
Noise_XXhfssession confirm zero plaintext canary leakage.
Pre-auth limits, state store, and policy dialing
PreAuthRateLimiterandInboundRouter: GuardsInboundRouter,SessionDriver::accept, anddrive_pair_responderwith partitioned trusted vs. untrusted (Relay/Broker) half-open quotas, IPv6/64+ unattributed buckets, per-key concurrent half-open limits, LRU eviction-overflow throttling, and RAIIHalfOpenGuardtracking.InboundRouterseparates0x01and0x02inbound handshakes into isolated queues and rate limiters, whileset_pair_enabled(false)disables and clears both v1 and v2 pair queues.StateStore: Opens state directories with0o700permissions (rejecting symlinks), validates0o600regular-file permissions before loading keys/rosters, serializesload_or_generate_identitywith.identity.lockand roster transactions with.roster.lock, and writesidentity.json(Zeroizingwrappers) androster.jsonvia0o600temp-filesync_all+ atomic rename.dial_with_policy_verified&SessionDriver::connect_with_policy: DrivePathPlannerover TokioJoinHandles (local < direct < overlay < p2p < relay < broker), gating candidate activation on NoiseHostHelloverification rather than raw TCP connect so decoy paths cannot blackhole healthy fallback paths.
Connections
Local graphLinked from
- Reference CLI, relay deployment, and conformance peerUsing Tendril“the stateless relay and async runtime”
- Add relay v1 spec, async runtime providers, and CLI demoLogs“stateless relay v1 and async runtime providers”