What Tendril is
Purpose, scope, non-goals, and explicit design limits.
Tendril is a reusable SDK for establishing private, end-to-end encrypted links between devices without relying on a trusted third party. A single Rust core owns device identity, pairing verification, sealed hybrid post-quantum Noise sessions (Noise_XXhfs_25519+MLKEM768_ChaChaPoly_SHA256, hybrid Ed25519 + ML-DSA-65 signatures), default-deny capability grants, and path selection, while thin bindings expose that core to host languages over pluggable, untrusted path providers.
Design summary
| Concern | Approach |
|---|---|
| Trust boundary | One Rust core owns keys, roster, sessions, grants, and path policy |
| Network paths | Providers are untrusted byte pipes ranked by locality and reliability |
| Authority | Confirmation of identity and minting of capabilities are distinct steps; default deny |
| Packaging | Thin bindings for Rust, Go, Python, TypeScript (Node and Web WASM), Swift, and Kotlin |
| Relay model | Public relay out of the box, with self-hosted and embedded relays on the same protocol |
Scope
In scope:
- Pairwise encrypted links between desktop, phone, browser, and server endpoints
- Human-verified pairing via short code and SAS/fingerprint comparison, plus opt-in machine-to-machine (M2M) single-use token enrollment with trust anchors
- Signed, expiring, revocable capability grants checked on connection and on every authorized action
- Pluggable providers spanning local, direct, overlay, peer-to-peer, relay, and broker paths
Out of scope for v1 (tracked in ADR 0003 for v2):
- Multi-party group encryption and shared group rosters
- Anonymous routing, epoch-blinded relay mailboxes, packet padding, and timing-resistant cover traffic
- Hosted user accounts or mandatory cloud control planes
- Replacing TLS for general public web browsing
Explicit limits and v1 tradeoffs
- Sleeping mobile devices. Operating systems suspend background sockets; pull works when awake, and push is an optional wake signal only.
- Browser platform limits. Web clients run the core in WASM over WebSockets and polling without raw UDP or reliable background links.
- Relay visibility and v1 metadata. Relays cannot read or forge sealed frames, but v1 observes static mailbox
device_idstrings, unpadded ciphertext lengths, and keepalive/rekey timing; operators should use self-hosted relays andserve --redact-logswhere event log confidentiality matters, with wire-level privacy hardening scoped to v2 (ADR 0003). - Offline revocation. A revoked peer cannot learn of its revocation until it attempts to reconnect or rekey.