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_id strings, unpadded ciphertext lengths, and keepalive/rekey timing; operators should use self-hosted relays and serve --redact-logs where 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.

Connections

Local graph

Linked from