tendril v0.1

Open source SDK · Apache-2.0

Pair two devices. No account, no server to trust.

A phone that syncs with a laptop. A desktop app you reach from your phone. Every app like this rebuilds pairing, keys, permissions and revocation.

Tendril is those parts, built once in a Rust core. You show a code, a person compares a check string, and the two devices talk directly.

Using an app built on Tendril? What it means for you

laptophost
Scan, or type TND-4F9K-22XQ Single use · 15 minutes
phonejoining
Pair with a device No account. No sign-in.

Example screens. Your app draws its own. Tendril supplies the code, the check string and the result.

Six things every device-to-device app rebuilds.

A socket is the easy part. Apps most often get 02 and 04 wrong.

  1. 01

    Finding each other

    Six ways to connect, from a local socket to a relay. Every path is untrusted. It counts only once the peer proves who it is.

  2. 02

    Knowing it is the right device

    The code is bound to this one handshake. Then a person compares a 16-character check string on both screens. Machines with no screen enroll with a signed, single-use token instead.

  3. 03

    Where keys live

    Files only your user account can read on desktops and servers, wiped from memory after use. Keychain and Android Keystore adapters for mobile.

  4. 04

    Revoking a lost device

    Each device is pending, active or revoked. Signed revocation lists also reach sessions that are already open.

  5. 05

    What the link may do

    Nothing, until a signed grant (a permission) says so. Grants expire. They can be passed on, but only narrower, and at most four times.

  6. 06

    When the network changes

    The pairing belongs to the devices, not the path. A new path needs a new handshake, never a new pairing.

How each one works

Where it fits.

Apps that link devices one person or one team already owns.

See the use cases

Six ways to connect, nearest first.

Every path is untrusted. A path counts only once the other device proves who it is inside the handshake, so a captive portal or a wrong host that answers never wins.

Same network. On one network, the direct path proves the other device first and wins.

The phone and the laptop share a home network. Local does not apply, as they are different machines. The direct path completes the handshake and is in use. Overlay, peer-to-peer, relay and broker are not used.

Across the internet. Away from home, the direct path fails and hole punching through iroh wins.

A phone on mobile data reaches the laptop at home. Local does not apply. On the direct path a wrong host answers and fails the handshake, so it does not count. There is no tailnet. The peer-to-peer path through iroh completes the handshake and is in use.

Strict NAT or firewall. When nothing direct gets through, a relay carries sealed packets it cannot read.

The relay sees
IP addresses, timing, sizes, a mailbox key
It cannot see
Your data, grants, device names, the pairing code

A phone on an office network reaches the laptop at home. The direct path and the peer-to-peer path are blocked, and there is no tailnet. The relay path is in use. The broker path is not used.

Network changes. The phone leaves Wi-Fi, so the devices handshake again on another path and keep their pairing.

A phone on home Wi-Fi uses the direct path to the laptop. The phone moves to mobile data and the direct path drops. The devices handshake again, and the peer-to-peer path is now in use. The pairing is the same, with no new pairing needed.

In a browser. A browser tab joins only as a client and cannot hole punch, so it always goes through a relay.

The relay sees
IP addresses, timing, sizes, a mailbox key
It cannot see
Your data, grants, device names, the pairing code

A browser tab reaches the laptop through the relay path, which is in use. Local, direct, overlay and broker are not available in a browser. With the opt-in p2p build, a tab can also take the p2p path, but only through an iroh relay, as a browser cannot open UDP sockets.

Illustrative. Device names, networks and timing are examples.

Built on other projects, not in place of them.

Tendril does not replace iroh, Noise or the platform keystores. It uses them, and adds the layer every app ends up writing itself, everything between your app and the network.

  1. Your appScreens, and the names of its grants
  2. TendrilPairing · check string · grants · revocation · choosing a path
  3. Built oniroh · Noise · ML-KEM · ML-DSA · Argon2id · Ed25519 · Keychain · Android Keystore

Need only a connection, with your own pairing and permissions? Use iroh directly.

Serve, pair, confirm, grant.

The same steps in every language. Your app owns the screens and the names of its grants. Tendril owns everything with a key in it.

uv add tendril-sdk
import json, tendril

host = tendril.Endpoint("./laptop-state", "laptop")
addr = host.serve_direct("127.0.0.1:0")
code = host.issue_code("lan")                     # show as text or a QR

req = json.loads(host.pair_accept(5000))
host.confirm_peer(req["device_id"], req["sas"])   # after a person compares the check string
grant = host.mint_grant(req["device_id"], ["notes.sync"], ttl_secs=3600)

session = host.accept_session(5000)
session.authorize("notes.sync")                   # True
npm install @tendril-sdk/node
import tendril from "@tendril-sdk/node";

const host = new tendril.Endpoint("./laptop-state", "laptop");
const addr = await host.serveDirect("127.0.0.1:0");
const code = host.issueCode("lan"); // show as text or a QR

const req = JSON.parse(await host.pairAccept(5000));
host.confirmPeer(req.device_id, req.sas); // after a person compares the check string
const grant = host.mintGrant(req.device_id, ["notes.sync"], 3600);

const session = await host.acceptSession(5000);
await session.authorize("notes.sync"); // true
go get github.com/agync/tendril/bindings/go
import tendril "github.com/agync/tendril/bindings/go"

host, err := tendril.NewEndpoint("./laptop-state", "laptop")
if err != nil { return err }
addr, err := host.ServeDirect("127.0.0.1:0")
if err != nil { return err }
code, err := host.IssueCode("lan") // show as text or a QR
if err != nil { return err }

req, err := host.PairAccept(5000)
if err != nil { return err }
// after a person compares the check string
if err := host.ConfirmPeer(req.DeviceID, req.SAS); err != nil { return err }
grant, err := host.MintGrant(req.DeviceID, []string{"notes.sync"}, 3600)
if err != nil { return err }

sess, err := host.AcceptSession(5000)
if err != nil { return err }
ok, err := sess.Authorize("notes.sync") // true
.package(url: "https://github.com/agync/tendril", from: "0.1.0")
import Foundation
import Tendril

let host = try TendrilEndpoint(stateDir: "./laptop-state", hostId: "laptop")
let addr = try host.serveDirect(listenAddr: "127.0.0.1:0")
let code = try host.issueCode(kind: "lan") // show as text or a QR

let json = Data(try host.pairAccept(timeoutMs: 5000).utf8)
let req = try JSONSerialization.jsonObject(with: json) as! [String: Any]
let device = req["device_id"] as! String
try host.confirmPeer(peerId: device, sas: req["sas"] as? String) // after a person compares the check string
let grant = try host.mintGrant(peerId: device, capsJson: #"["notes.sync"]"#, ttlSecs: 3600)

let session = try host.acceptSession(timeoutMs: 5000)
let ok = try session.authorize("notes.sync") // true
implementation("dev.agync:tendril-android:0.1.0")
import dev.tendril.TendrilEndpoint
import org.json.JSONObject

val host = TendrilEndpoint.create(stateDir = "./laptop-state", hostId = "laptop")
val addr = host.serveDirect("127.0.0.1:0")
val code = host.issueCode("lan") // show as text or a QR

val req = JSONObject(host.pairAccept(5000))
val device = req.getString("device_id")
host.confirmPeer(device, req.getString("sas")) // after a person compares the check string
val grant = host.mintGrant(device, """["notes.sync"]""", 3600)

val session = host.acceptSession(5000)
session.authorize("notes.sync") // true
cargo add tendril-runtime tendril-core
// tendril-runtime is the async layer the other bindings wrap; it is lower level.
let store = StateStore::open_or_create("./laptop-state")?;
let identity = store.load_or_generate_identity(Some("laptop"))?;
let roster = Mutex::new(store.load_roster()?);
let pairing = Mutex::new(PairingManager::new(PairingConfig::default()));
let router = InboundRouter::new();

let listener = DirectListener::bind("127.0.0.1:0".parse()?, None).await?;
router.spawn_listener(&Handle::current(), Box::new(listener));
let code = pairing.lock().unwrap().issue_code(PairingCodeKind::Lan2Group, now())?;

let (mut stream, guard) = router.recv_pair(wait).await?.ok_or("closed")?;
let kind = pairing_path_kind_for_provider(stream.provider_id());
let res = drive_pair_responder_with_options(stream.as_mut(), &identity, &pairing, &roster,
    kind, now(), Some(router.rate_limiter()), Some(guard), DEFAULT_PRE_AUTH_TIMEOUT).await?;
let PairOutcome::ResponderPending { device_id, pairing_sas, .. } = res.outcome else { bail!() };

// after a person compares the check string
roster.lock().unwrap().confirm_peer(&device_id, Some(&pairing_sas))?;
let grant = roster.lock().unwrap().mint_grant(&identity, &device_id,
    vec!["notes.sync".into()], now(), now() + 3600, random_bytes::<16>()?)?;
store.save_roster(&roster.lock().unwrap())?;
cargo install tendril-cli
tendril --state-dir ./laptop-state init --host-id laptop
tendril --state-dir ./laptop-state serve --listen 127.0.0.1:0 --issue-code lan

# on the host, after a person compares the check string
tendril --state-dir ./laptop-state confirm <device_id> --sas "<check string>"
tendril --state-dir ./laptop-state mint <device_id> --cap notes.sync --ttl-secs 3600

Enroll a servermachine to machine, no check string

# on the Mac mini, accept machines and mint one single-use token
tendril --state-dir ./mac-mini-state serve --listen 0.0.0.0:7000 --allow-enroll
tendril --state-dir ./mac-mini-state enroll-token --target-host mac-mini --out ./token.json

# on the NAS, with the Mac mini's keys from init pinned in advance
tendril --state-dir ./nas-state enroll --endpoint 192.168.1.20:7000 --host-id mac-mini \
  --host-static-pub "<static_pub>" --host-signing-pub "<signing_pub_hash>" \
  --token-file ./token.json

# on the Mac mini, the NAS joined with no grants
tendril --state-dir ./mac-mini-state mint <device_id> --cap backup.write

Events are polled, not called back, so nothing re-enters your event loop. In the browser, Tendril joins as a client through a relay.

What we borrow, and what we own.

The algorithms are standard and used unchanged. The new parts are named, so review effort can go there. There has been no third-party audit yet.

Borrowed, proven elsewhere

Key exchange
X25519 and ML-KEM-768 (NIST FIPS 203)
Signatures
Ed25519 and ML-DSA-65 (NIST FIPS 204), used together. Both must verify
Signed bytes
Canonical JSON (RFC 8785)
Code proof
Argon2id: 64 MiB and 3 passes, or 19 MiB and 2 passes in Wire v2 pairing
Peer-to-peer path
QUIC and hole punching, via iroh

New, and ours

Hybrid handshake
Noise_XXhfs_25519+MLKEM768_ChaChaPoly_SHA256, in our own Noise code. Checked against a separate Go version
Code proof
Works only on the connection it was made for
Confirm, then grant
Approving a device and granting it anything are separate steps
Grants
Default deny. Exact names or a prefix, no patterns
Revocation
Signed lists that only move forward, pushed into live sessions
Wire v2
An opt-in privacy mode: hourly mailbox keys, padded sizes, and a decoy reply for strangers who probe a host

A relay cannot see

  • Your data
  • Which grants exist
  • Device names
  • The pairing code

A relay can see

  • IP addresses
  • When devices connect, and how much they send
  • The key a waiting device uses as its mailbox. By default it never changes, so a relay can link that device's sessions

Wire v2, an opt-in mode, changes the mailbox key every hour, rounds sizes up to fixed steps and varies the timing of keepalives. Addresses, and when devices send, stay visible. What it hides

Read the pairing designWhy the handshake is hybrid

One core, thin bindings.

Every security decision is made in one Rust core that forbids unsafe code. Bindings translate types and nothing else.

All bindings check the same shared test vectors.

Rust
tendril-core, tendril-runtime
Go
cgo
Python
PyO3
Node.js
N-API
Browser
WebAssembly
Swift
iOS, macOS
Kotlin
Android, JNI

Pair two devices on your own machine.

Found a security problem? Report it privately on GitHub.