tendril v0.1

How it works

How Tendril links two devices

A phone and a laptop want to talk privately, with no account and no server in charge. Each must know the other is the right device, know what the other may do, and find a way to reach it. This page takes those in order, in nine short parts.

Each part starts with the short version. Open The details for the exact mechanism, the numbers and a link to the design docs.

01

The pair is a key, the path is a hint

Most apps tie trust to an account or a network address. Accounts need a server you must trust, and addresses change every time a phone leaves Wi-Fi. Tendril ties trust to the two devices instead. Each one keeps the other's public key and the grants it was given. The route the bytes take, called a path, can change at any time without touching either.

Every connection starts with a handshake, a short exchange in which each device proves it holds its key and both agree on fresh keys for this connection. What follows is an encrypted session.

The handshake is hybrid post-quantum. It mixes a classic key exchange with a newer one built to resist future quantum computers. A hybrid stays secure as long as either one holds.

phone keeps laptop's key laptop keeps phone's key pairing keys and grants, held by both direct p2p relay paths come and go, the pairing stays
  • A new network means a new handshake, never a new pairing.
  • An address can only say where to try. It never grants anything.
The details

Every path is an untrusted byte pipe below the session. TLS, WireGuard, QUIC or a secure WebSocket around it count as plumbing. Only the inner Noise session, Noise_XXhfs_25519+MLKEM768_ChaChaPoly_SHA256, proves who the other device is and carries its grants.

A pairing link can carry endpoint hints (ep). They say where to dial and never grant anything. The key the peer-to-peer path uses for routing is derived from the device's own key and is routing metadata only.

Reconnecting after a network change is up to your app. It dials again, and the pairing and grants carry over unchanged.

02

Each device makes its own keys

Nobody hands a device its identity. No server issues it a certificate and no account holds a password for it. On first run, each device makes its own keys, and the private halves stay on that device.

On the phone

X25519 key
Proves who it is in every handshake
Signing key
Ed25519 and ML-DSA-65 together. Signs grants and revocation lists
public key dev_7a91c04e2b6d3f18the device id
Where the private keys are kept
Desktop and serverFiles only your user account can read
iPhone and MacKeychain
AndroidAndroid Keystore
BrowserWherever your app chooses
Illustrative id. Every device id is worked out the same way from its key.
  • There is no account to steal and no central list of devices.
  • A device id comes from the device's key, so one device cannot claim another's id.
The details

Each device has two long-lived key pairs. An X25519 static key identifies it in every Noise handshake. A signing key, an Ed25519 key and an ML-DSA-65 key used together, signs grants, revocation lists and key rotation records. A signature counts only if both halves verify. Relay mailboxes use Ed25519 alone: the Ed25519 half of this key by default, or a key made fresh each hour with Wire v2.

Keys are made in tendril-core and wiped from memory when they are dropped. The device id is dev_ and the first 8 bytes of the SHA-256 of the static public key, as 16 lowercase hex characters. A host rejects a session whose claimed id does not match the key that proved itself.

On desktops and servers, the state directory is created with mode 0700 and the identity and roster files with 0600. The Apple and Android secure chips do not support these curves or ML-DSA-65, so there the keys are made in the core and stored wrapped by a Keychain or Android Keystore AES key. The Keychain item opens only after first unlock and only on that device, and the Android binding turns off app backups. The Swift and Android test suites do not yet run in CI.

In the browser, your app keeps the identity and roster wherever it chooses. The SDK exports them and takes them back on start. The browser demo seals them under a WebCrypto key that cannot be exported.

03

Pairing, step by step

Pairing has one job. It must make sure the device on the other end is the one in front of you, and not someone pretending to be it. Tendril does this with a short code, a handshake, and a check a person makes with their own eyes. Here the laptop is the host, the device that waits, and the phone is the joining device.

  1. The laptop shows a code. As text or a QR code. It works once and expires after 15 minutes. It moves by eye or camera, never over the network.

  2. The phone says hello. Its first message carries two keys made for this one connection, a classic one and a post-quantum one. Nothing in it says which phone this is.

  3. The laptop proves who it is. Its reply carries its identity, encrypted. If the phone scanned a QR code, it already knows the laptop's key and checks it now. A decoy is dropped here, before the phone reveals anything about itself.

  4. The phone proves it has the code. It sends its own identity and a code proof, a value only someone with the code can work out, and only for this connection. The code itself is never sent.

  5. The laptop answers and hangs up. It checks the proof, lists the phone as pending, sends one reply and closes the connection. Nothing waits on an open connection while a person decides.

  6. A person compares two strings. Both screens show a 16-character check string worked out from this exact handshake. A person checks they match and confirms. The phone can now open a session, but it has no grants yet.

Illustrative. The code and the check string are examples.

The check string is what stops someone in the middle. To sit between the two devices, they must run one handshake with the phone and another with the laptop. Two handshakes give two different check strings.

phone someone in the middle laptop handshake 1 handshake 2 k7qm 4xrt 3fpa 2wnc p3ze 6hya q2mb tr5d different the strings do not match, so the person cancels
Illustrative. The strings are examples.
  • The code is never sent, not even encrypted.
  • A code proof only works on the connection it was made for, so it cannot be copied onto another.
  • Someone in the middle shows up as two check strings that do not match.
The details

The code. Characters come from a 31-character alphabet with no 0, 1, I, L or O, so nothing is misread: 23456789ABCDEFGHJKMNPQRSTUVWXYZ

FormRandom charactersUsed for
TND-XXXX-XXXX8, about 40 bitsQR codes and the local network
TND-XXXX-XXXX-XXXX12, about 59 bitsTyping across the internet

Hosts reject the short form on remote paths. A code works once and lasts 15 minutes by default, and the host can change that. Every failed attempt counts against all live codes, and a code is burned after 5 failures.

The handshake. Noise_XXhfs_25519+MLKEM768_ChaChaPoly_SHA256, a hybrid post-quantum handshake in three messages. It is the only one Tendril speaks, in both versions of the wire format. There is no fallback, so a peer on an older version without it is turned away.

MessageCarriesSize
1, to the hostTwo one-time public keys, X25519 and ML-KEM-768. Nothing about the device1216 B
2, to the joining deviceThe host's key, its id and its 1984 byte signing key, encrypted1200 B + hello
3, to the hostThe joining device's key, its name and the code proof, encrypted64 B + claim

In version 1, the default, the whole handshake is about 6 KiB. A pairing link or QR code (tendril://pair?...) carries the host's X25519 key and a 32 byte hash of its signing key, which keeps the QR code small. The joining device checks both on message 2 and stops before message 3 if they differ, so its own key is never shown to the wrong host.

The code proof. K = Argon2id(code, salt = first 16 bytes of h) with 64 MiB of memory, 3 passes and 1 lane, where h is the handshake hash after message 2. The proof is HMAC-SHA256(K, "tendril-pair-v1" || h), compared in constant time. Argon2id makes each guess slow and memory hungry. Binding to h ties the proof to this one handshake.

Wire v2 pairing. When both devices turn on Wire v2, the joining device proves it has the code in message 1 instead, with Argon2id at 19 MiB and 2 passes. The host then shows its identity only to a device that has the code. Anyone else gets a decoy reply of the same size, and no code is used up. The check string and the pending step stay the same.

The check string. The first 16 characters of the lowercase base32 SHA-256 of "tendril-sas-v1" || h, in groups of four.

After the reply. The host sends one encrypted reply and closes. The new device stays pending and cannot open a session. Confirming it (pair.confirm) makes it active with no grants. Without a QR code, the joining device also keeps the host pending until a person confirms there. A revoked device cannot pair again with the same key.

Machines with no screen

Say an app runs on a Mac mini at home, and a NAS should back it up. The NAS has no screen. Nobody can read a check string off it, so pairing by eye does not fit. Instead, the Mac mini, as host, mints an enrollment token, a signed permission to join that works once and expires after 15 minutes by default. The NAS must already know the host's keys, so it never trusts whoever answers first.

Hosts refuse all of this until their owner turns it on. A machine that enrolls is active but holds no grants, so granting it something is still a separate step.

  1. The Mac mini mints a token. It is signed by the Mac mini, works once and expires after 15 minutes. It is copied to the NAS as a file.

  2. The NAS checks the host. It already holds the Mac mini's keys, pinned in advance. If message 2 shows other keys, it stops before it says anything about itself.

  3. The NAS proves the token is its own. Message 3 carries the token and a proof signed with the NAS's key over this handshake, so a copied token cannot be used on another connection.

  4. The Mac mini burns the token, then answers. It writes the token to its burn log and saves it before it replies. The NAS is now active, with no grants.

Illustrative. Any machine with no screen enrolls the same way.
  • No check string, and still no trust in whoever answers first.
  • A token works once. A copy is useless after that.
  • An enrolled machine can do nothing until you grant it something.
The details

Off by default. A host accepts enrollment only once its owner turns it on, with tendril serve --allow-enroll in the CLI, or in the SDKs by adding a trust anchor or minting a token for itself.

The enrollment token. A signed grant for one use (uses: 1), marked for machines, with a 16 byte nonce as its id. It may hold only pair.enroll or pair.enroll:<host_id>. It lasts 900 seconds by default and never more than 86,400. The CLI host accepts tokens of up to 900 seconds, as do the hosts in the language bindings. A longer lifetime needs a Rust host that sets its own enrollment policy. The host signs it, or an outside key the host trusts, called a trust anchor (tendril anchor add). The CLI reads it from a file, standard input or an environment variable, never from the command line.

Pinning. The joining machine must be given the host's id, X25519 key and signing key in advance, as the full 1984 bytes or a 32 byte hash. There is no trust on first use.

The proof. In message 3 the machine sends the token, its signing key and enroll_proof, a hybrid signature over "tendril-enroll-v1\0" || h || its static key || the token nonce. That ties the token to this one handshake and this one device.

The burn log. The host records the nonce and saves its roster before it writes the reply. The log holds up to 16,384 unexpired tokens. When it is full, the host refuses new enrollments rather than forget old ones. A revoked machine still burns the token it presents.

The result. The machine joins active, with zero grants. Grants come from pair.mint, as for any device. Session checks reject any grant marked for one use or for machines, so a token can never open a session.

Taking it back. tendril revoke-token revokes an unused token by its nonce, and tendril anchor revoke stops every token an anchor signed.

04

Nothing is allowed until a grant says so

Pairing proves who a device is. It does not decide what that device may do. A paired device can open an encrypted session and nothing else. Each thing it may do is a grant, signed by the host, with an end time. Confirming a device and granting it something are two separate steps, so one never implies the other.

Grantsigned by laptop

For
phone dev_7a91c04e2b6d3f18
May
notes.sync
fs.read:/photos/*
Until
60 minutes from now
The phone asks, the laptop checks
RequestResult
notes.syncallow
fs.read:/photos/2026/beach.jpgallow
fs.write:/photos/2026/beach.jpgdeny not granted
fs.read:/documents/tax.pdfdeny outside /photos/
notes.sync, an hour laterdeny expired
Illustrative. Your app names its own grants.
  • A new device can do nothing until your app grants it something.
  • A grant is an exact name or a prefix. There are no patterns that match more than you meant.
  • Grants end on their own.
The details

Names. A grant names namespace.verb or namespace.verb:resource. A resource may end in one *, which matches any resource with that prefix. There are no wildcards in the middle, no negation and no regular expressions.

Paths. Plain checks treat a resource as an opaque string. For file paths, the Rust core has a path check, authorize_path, that cleans the path first and matches only at / boundaries, so /public/* never covers /public_secrets/key.pem. Apps that guard files should use it.

Checks. A grant is checked when a session opens, on every rekey and on every authorize call. It denies at the first problem, checking in this order: shape, subject, time, revocation, issuer and signature, the chain it was passed down, then the name. It allows 30 seconds of clock difference. In Rust, each check also returns an audit event your app can record. The other bindings return allow or deny.

Signatures. Ed25519 and ML-DSA-65 over RFC 8785 canonical JSON with a fixed prefix, so the same grant always signs to the same bytes. A grant is valid only if both signatures verify.

Passing a grant on. A device whose grant includes pair.mint can grant a narrower one to another device. Every name must be covered by its own grant, the time window must sit inside its own, and the chain can be at most 4 hops long. Revoking a grant also revokes everything passed on from it.

  1. laptoppair.mint, fs.read:/photos/*24 hours
  2. phonefs.read:/photos/2026/*1 hour

05

Taking access back

A phone gets lost. It has to be cut off now, including any session it already has open. The host keeps a roster, a list of every device it knows and the state of each. Revoking a device changes its state and sends a signed revocation list into live sessions.

pending no sessions active sessions, grants revoked nothing confirm revoke a live session list 41 list 42 signed by laptop revokes the phone phone's requests denied
Illustrative. List numbers are examples.
  • Revoking a device also ends what it can do in sessions that are already open.
  • An older list cannot undo a newer one.
  • A revoked device cannot pair again with the same key.
The details

States. Devices paired by a person start pending. A machine enrolled with a token starts active, with no grants. Pending devices cannot open sessions. Active devices can, and hold whatever grants they were given. Revoked devices are refused, and trying to pair again with the same key fails while still burning the code.

Revocation lists. A list names revoked devices and revoked grants, carries a sequence number, and is signed with the host's signing key, Ed25519 and ML-DSA-65 together, over RFC 8785 JSON. A device rejects any list whose number is lower than the highest it has already seen. Lists travel inside a live session as their own frame type.

Rekeying. Every 15 minutes or 220 frames, whichever comes first, a session switches to fresh keys. With Wire v2, each switch comes at a random point between 75 and 100 percent of those limits. The receiving side then checks its active grants again against the latest list.

Key rotation. A host can replace its keys by signing a numbered rotation record with the old key. Peers follow the chain of records one number at a time. Two valid records with the same number mean someone else may hold the key. The peer is then marked revoked, its grants are cleared, and the check returns an error.

Offline devices. Revocation is not instant for a device that is offline. It learns of it only when it reconnects or rekeys.

06

Six paths, nearest first

Two devices may sit on one desk, share one home network, or be on two networks behind firewalls. Tendril has six ways to connect and tries the nearest first. Every path is untrusted. A path counts only once the other device proves who it is in the handshake, so a wrong host that answers on an address never wins.

The phone, away from home, dials the laptop

  1. 01localsame machinenot here
  2. 02directlocal networkno answerDialled at 0 ms.
  3. 03overlayan existing tailnetno tailnet
  4. 04p2phole punching via irohin useWaits, then dialled at 500 ms, and proves the laptop at about 850 ms.
  5. 05relaythrough a relaycancelledDialled at 750 ms, cancelled when p2p wins.
  6. 06brokerWebSocket via a proxynot here
Illustrative. Dial start times follow the defaults. The handshake time is an example.
  • A nearby path gets a head start, so finding a peer across the internet never slows a local connection.
  • When the network changes, the devices handshake again on another path and keep their pairing.

See all six paths at work in five situations in the paths diagram on the home page.

The details
RankPathWhat it is
0localA Unix socket only your user can open, for two apps on one machine
1directTCP on a local network or to a reachable address
2overlayAn existing tailnet
3p2pQUIC with hole punching, through iroh
4relayA WebSocket relay, described below
5brokerA WebSocket through an authenticated reverse proxy

Staggered dialling. Dials start nearest first, 250 ms apart, like Happy Eyeballs, the method browsers use to try two kinds of address side by side. Peer-to-peer starts no sooner than 500 ms after the first other dial, because finding a peer takes longer and should not hold up a nearer path. The first path to finish the handshake wins and the rest are cancelled.

Where this runs. Ranking and racing run in the Rust runtime (dial_with_policy). The other bindings and the CLI dial the one address you give them today.

Peer-to-peer. The p2p path uses iroh. By default it uses the free public relay and discovery servers run by n0, which are rate limited and carry no uptime guarantee. You can point it at any iroh relay instead: one you run, or a hosted one from n0. Tendril takes up to eight relay URLs and can pass them a token, for relays that admit only your devices. You can also turn discovery off. These relays carry only the p2p path. The relay path below is Tendril's own.

07

What a relay can see

Sometimes nothing direct gets through. A strict NAT, a router that shares one public address and turns away incoming connections, or a firewall can block every other path. Then a relay, a server both devices can reach, passes the bytes between them. The session runs end to end through it, so the relay forwards sealed frames it cannot open.

encrypted session, phone to laptop phone office network laptop home network relay laptop's mailbox the relay copies sealed frames across unchanged

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 changes it every hour

A relay cannot see

  • Your data
  • Which grants exist
  • Device names
  • The pairing code
  • A relay cannot read your data or change it without the change being caught.
  • You can use a public relay, run your own or embed one in your app, and move between them without pairing again.
  • A relay you run can admit only your own devices, so strangers cannot use it.
The details

Mailboxes. A relay speaks WebSocket. At /v1/relay, the default, a waiting device registers a mailbox, which is the Ed25519 half of its signing key (32 bytes), and proves it holds the key by signing a fresh challenge from the relay. The key stays the same across sessions and addresses, so a relay can tell when the same device comes back. A device that wants to connect asks for that mailbox. The relay tells the waiting device, and once it accepts, copies each frame across unchanged.

Hourly mailboxes. With Wire v2, devices use /v2/relay. Two paired devices share a secret from their pairing and derive a new mailbox key from it every hour, on a fresh connection each hour, so the relay cannot link one hour's mailbox to the next by its key. It can still link them by IP address.

Who may use it. A relay is open by default. tendril-relay can instead admit only some devices, in one of three ways:

Admit byHow it works
A list of mailbox keysOnly listed keys may wait for connections. Version 1 only, as Wire v2 keys change every hour
A shared secretEach device proves it holds a secret you gave it
A signed ticketSigned by a key you choose, valid for a day at most, and can be limited to dialing one mailbox

With a secret or tickets, the relay checks a device that dials before it says whether the mailbox is online, so a stranger cannot even learn that. Treat a ticket like a password while it is valid.

What it may keep. A relay must not log application data, device names or pairing codes. It does see IP addresses, when devices connect, how many frames they send and how large they are, and the mailbox key.

Moving relays. Moving from a public relay to your own, or to one embedded in your app, changes only the relay hints on the roster. Keys, pairing and grants stay as they are.

08

What Tendril does not protect against

Every security tool has edges. Knowing Tendril's helps you design around them.

Tendril makes sure

  • Each device proves its key to the other on every connection.
  • Each session has its own keys, so a key stolen later does not open past sessions.
  • A recorded session stays closed to a future quantum computer, unless both the classic and the post-quantum exchange break.
  • Data in a session cannot be read, or changed without it being caught.
  • Nothing is allowed unless a valid grant says so.

Tendril does not protect against

A stolen, unlocked device
It can use its grants until you revoke it.
A hostile operating system
Malware on the device sees what your app sees.
Approving the wrong device
If a person confirms without comparing the check string, Tendril cannot tell.
Metadata
Relays, tailnets and networks still see addresses, timing and sizes. Wire v2, which is opt-in, pads sizes and varies keepalive timing, but cannot hide when or how much you send.
Being traced
It is not an anonymity network and does not hide who talks to whom.
Quantum computers, in two places
Relay mailbox proofs use Ed25519 only. The iroh transport under the peer-to-peer path is not post-quantum, though the session inside it is.
Unreviewed code
There has been no third-party audit yet, including of the new post-quantum code.
The details

A revoked device that is offline learns of it only when it reconnects or rekeys. Browser tabs run over WebSockets, through a Tendril relay or, with the opt-in p2p build, an iroh relay. They cannot open UDP sockets or hold a connection while the browser suspends them. Phones suspend background sockets while asleep, so a phone reaches its peer again when it wakes.

Waking a peer. With Wire v2, a device that dials a sleeping peer can first send it a wake hint through a push service the app sets up, such as UnifiedPush, FCM or an APNs gateway. The hint carries only a tag that changes every hour: no data, no names, no keys and no permission. If a hint is lost, nothing breaks: the peer comes back when it next wakes on its own.

What is post-quantum. The session key exchange (X25519 with ML-KEM-768), and the signatures on grants, key rotation, revocation lists and enrollment (Ed25519 with ML-DSA-65). What is not. Relay mailbox proofs, which use Ed25519 alone, and the iroh transport below the peer-to-peer path. Data inside the session is still covered on every path. The Noise code is Tendril's own and is checked against a separate Go implementation. A peer without the hybrid handshake is rejected, so every device must run a current version.

Metadata. Tendril hides your data, not who talks to whom. Wire v2 is an opt-in mode that narrows what the default, version 1 of the wire format, gives away.

What leaksVersion 1, the defaultWire v2, opt-in
Relay mailbox keyThe same every timeNew every hour
Message sizesExactRounded up to fixed steps, 256 bytes to 64 KiB
Keepalives and rekeysOn a fixed scheduleAt random points within a range
A stranger who probes a hostLearns its id and keysGets a decoy reply of the same size

Wire v2 still leaves IP addresses, when devices send and roughly how much in view. Both devices must turn it on. A host with it on still answers version 1 for older peers, so a stranger can still learn its id that way. Two devices that have used Wire v2 refuse to fall back. Padding frames that hide idle time exist, but your app has to send them. tendril serve --redact-logs keeps pairing codes, payloads and token nonces out of the CLI's own logs.

Group encryption, hosted accounts and replacing TLS for the web are out of scope for v1.

09

One core, thin bindings

Security code copied into six languages drifts apart. Tendril keeps every security decision in one Rust core. The bindings for other languages translate types and pass calls through.

  • GoC ABI
  • SwiftC ABI
  • KotlinJNI
  • PythonPyO3
  • Node.jsN-API
  • BrowserWebAssembly
tendril-runtimeSockets, the six paths, state on disk
tendril-coreKeys, pairing, roster, grants, sessions. Every security decision, with no I/O and no unsafe code.
The browser build uses the core directly and brings its own transport.
  • One place to review for every security decision.
  • Every binding checks the same shared test vectors.
The details

The core. tendril-core holds identity, pairing, the roster, grants, the session state machine and path ranking. It does no network or file I/O. The caller feeds it bytes and the time, and it returns actions. tendril-runtime adds sockets, the six paths and state on disk.

Unsafe code. The workspace forbids unsafe Rust. The one exception is the C ABI crate, tendril-ffi, because a C boundary cannot be written without it.

Bindings. Go and Swift link the C ABI, and Kotlin reaches it through a small JNI layer. Python uses PyO3 and Node.js uses N-API. The browser runs the core as WebAssembly. Events are polled, not called back, so nothing re-enters your event loop.

Test vectors. Every binding checks four shared vector files: fingerprints, code proof, key rotation and grants. Rust and Go also check the handshake, machine enrollment and Wire v2 vectors. The Go checker is a separate implementation, with its own Noise code, and shares no code with the Rust core. The Swift and Android suites do not yet run in CI.

Go deeper