tendril v0.1

For people using an app

Your app uses Tendril

An app on your devices says it is secured by Tendril. Here is what that means for your data, in plain words, including what it cannot promise.

  1. 01What it does
  2. 02What you will see
  3. 03What you control
  4. 04What it cannot promise
  5. 05How to check

01

What it does for you

Your devices talk to each other, not to an account in someone's cloud. What passes between them is sealed, so only those two devices can read it.

laptop runs the app phone with you sealed directly, when it can relay only if needed passes it along, cannot read it
Illustrative. A laptop and a phone stand in for your devices.
  • No account

    Tendril pairs your devices with a code, not a sign-in.

  • Nobody in between reads it

    Not your network, not a relay, not the app's maker.

  • Keys stay on your devices

    They are made there. The maker's servers never hold them.

The details

The seal. Each connection starts with a handshake, Noise_XXhfs_25519+MLKEM768_ChaChaPoly_SHA256, that proves each device holds the keys it paired with, then encrypts everything after it. A path counts only once that proof succeeds.

Paths. On the same network the devices connect directly. Away from home they can try hole punching through iroh, and if nothing direct gets through, a relay forwards sealed frames. A relay can be the maker's, a public one, or one you run.

Keys. Each device makes its own keys. On desktops they sit in files only your user account can read. On phones they are sealed with a key from the Keychain or the Android Keystore, stay on that phone, and are not restored to another device from a backup. The Swift and Android test suites do not yet run in CI.

02

What you will see

Pairing happens once per device and takes three steps.

  1. 01

    Type or scan a code

    The laptop shows a code. Scan it with your phone, or type it. It works once, for 15 minutes.

    laptop
    TND-4F9K-22XQ
    phone
    Scan, or type
  2. 02

    Compare a short string

    Both screens show the same 16 characters. Confirm only if every one matches.

    laptop
    k7qm 4xrt
    3fpa 2wnc
    They match
    phone
    k7qm 4xrt
    3fpa 2wnc
    They match
  3. 03

    See your devices

    The laptop now lists your phone. The app can show you this list, and what each device may do.

    laptop
    Your devices
    phone
    active
    May
    sync notes
    Remove
    phone
    Paired with laptop Notes are syncing.
Example screens. Each app draws its own.

Why compare? If the strings differ, someone is between your devices. Cancel, and that device gets no access.

The details

The code. It is bound to this one handshake and never crosses the network itself. The QR code also carries the laptop's key, so the phone turns away an impostor before it says anything. Pairing across the internet uses a longer code, TND-XXXX-XXXX-XXXX.

The string. Both devices work it out from the handshake they just ran. A device in the middle would have run a different handshake with each side, so the two screens would not match.

After pairing. The new device can open a sealed connection and nothing else, until the app grants it something.

03

What you control

The laptop keeps the list of your devices and decides what each may do. A new device can do nothing until the app allows it.

phoneon the laptop's list

State
active
May
sync notes
Until
30 days from now
The phone asks, the laptop checks
The phone asks toResult
Sync notesallowed
Read your photosrefused never allowed
Anything, once you remove the phonerefused removed
Illustrative. Each app names what its devices may do.
  • Permissions can run out on their own, for example after an evening.
  • Lost a phone? Remove it on the laptop. Its next request is refused, even mid-connection, and it cannot connect again.
  • Remove it soon. Until you do, an unlocked phone can still do what it was allowed.
The details

The list. The device that runs the app keeps a roster: every device it has paired, whether each is pending, active or removed, and its grants. A grant is a signed permission with an end time.

Checks. The app asks Tendril before it acts on a request. The answer is no unless an active device holds a grant that covers it.

Removing. A removed device is marked revoked and its grants are cleared, so its next request is denied, even in a connection that is already open. It cannot open a new one, or pair again with the same key. A phone that is offline learns of it when it next connects.

04

What it cannot promise

Tendril protects what you send. These four things it does not, or not yet.

Who talks to whom
Networks and relays still see your devices' addresses, when they connect and how much they send. They cannot see what.
New code
Tendril is new. Its code has had no outside security review yet.
Future quantum computers
The link uses two kinds of encryption together, a long-standing one and a newer one designed to resist quantum computers. It stays secure as long as either one holds.
The app itself
The app on your devices still sees your data, as it must to show it to you. Tendril protects the link, not the app. Ask the app's maker what it does with your data.
The details

Metadata. By default, a relay sees the same mailbox key each time a device waits for connections, so it can link that device's sessions, and exact message sizes and regular keepalives show patterns. An app can turn on Wire v2, which changes that key every hour, rounds message sizes up to fixed steps and varies the timing of keepalives. Even then, networks see when your devices talk and roughly how much.

Hybrid post-quantum. The handshake pairs X25519 with ML-KEM-768, and signatures pair Ed25519 with ML-DSA-65. Two parts are not covered: relay mailbox proofs use Ed25519 only, and the iroh transport under the peer-to-peer path is classic. Your data inside the session is covered on every path.

Waking a phone. An app can wake a sleeping phone through a push service such as Apple's or Google's. The push carries only a tag that changes every hour, never your data, device names or keys. The push service still sees that your phone was woken, and when.

Review. The algorithms are standard. The Noise code that runs the handshake is Tendril's own, checked against a separate Go version, and not yet audited.

05

Why you can check

You do not have to take this page's word for it. You, or someone you trust, can check each claim.

  • The sourceOpen source under Apache-2.0. Anyone can read it.
  • The specThe rules every device follows, written down in public.
  • How it worksThe design in nine parts, with the details.
  • Report a problemFound a security issue? Tell us privately.

Every claim on this site is checked against the code before it goes up.