Keys and how long they last

The short version

Most of these keys you never see. They renew by themselves while a host is online. The ones you handle yourself are your passkey, your recovery words, and the short codes that sign you in from a command line or add a host.

All keys at a glance

Why keys expire and rotate

A key that never changes can be copied once and used for ever, and nobody would notice. A key that ends on its own makes a copied one useless after a short time, with nothing for you to do.

Renewal happens while a host is online and in touch with the server, so a host you use never notices it. Only a host that stays away for longer than a key lasts has to be added again.

Waiting for a key to expire is not the only protection. Removing a host cuts it off at once, even if it is offline, and recovering your account removes every passkey and every CLI sign-in key.

Signing in

These are the keys that get you into Infraternal, and back in when something goes wrong.

Browser sign-in

When you sign in with a passkey, the server gives your browser a session that lasts as long as Browsers Stay Signed In For says. Using Infraternal keeps the server's copy alive: every use starts that time again.

The session lives in the server's database and in that cookie, and nowhere else. While the server is offline nothing renews, and you can sign in again only once it is back. Destructive actions ask for a fresh passkey tap whatever the session says.

Browsers Stay Signed In For

This is how long the session in Browser sign-in lasts.

Passkey

A passkey is a key pair on your device.¹ The private half never leaves your device, and Infraternal never sees it.

A passkey does not expire, and you can have two. It stops working when you remove it, or when a recovery replaces it. Signing in needs the server, so a passkey cannot be used while the server is offline.

Figure pending

Recovery words

The 24 recovery words are your way back in when you lose your passkeys.² They are shown once, when you create your account, and only you hold them: the server keeps a check value, not the words. They do not expire.

Starting a recovery from a device that is not signed in waits 24 hours, so that a stranger with stolen words cannot take over before you notice. Any signed-in device can cancel it, and a device already signed in to the same account skips the wait. After the wait you have until 48 hours after the start to finish.

Re-entering your words while a recovery is pending resumes that request, with the same wait and expiry. Once it expires or is cancelled, starting again creates a new request with a fresh 24-hour wait and 48-hour expiry (unless you are already signed in). Each new request notifies your signed-in devices.

Why the wait counts server uptime, not the clock

The wait and expiry count elapsed server uptime, so a clock correction cannot skip or lengthen the wait. A restart keeps the progress already recorded; the server saves it every 60 seconds and on normal shutdown, so an abrupt restart loses at most about a minute plus the downtime. Storage failures keep recovery waiting rather than crediting time that was not measured. The displayed date is an estimate and can move after a clock correction. The recovery page asks the server every minute, when its countdown reaches zero and when you return to it, and shows "Ready now" only after the server confirms. An upgrade from the older clock-based recovery ends existing requests: re-enter your words to start a fresh wait.

First-owner setup code

When a server starts with no owner yet, it prints a one-time setup code in its log. You use it to create the first account.

The code lasts 24 hours and works once. It is not renewed while the server runs.

CLI sign-in code

infraternal sign-in <server> shows a link and a short code. You approve it in a signed-in browser with a fresh passkey tap.

The code lasts 10 minutes and works once. If you are away from the browser, it simply expires and you start again.

CLI sign-in API key

Approving a CLI sign-in gives that device an API key, kept in a file only your user can read. How long it lasts without use is set by Keys Last.

The server renews a valid key silently when it is used, writing the renewal at most once per hour. The server's current lifetime setting applies on each check, including to existing keys, so shortening it can expire a key on its next use. Lengthening applies at the next successful renewal; it cannot bring an expired key back.

A key that expires needs infraternal sign-in <server> again. Revoking it in the app takes effect immediately; recovery removes all keys. Existing keys receive their first lifetime when the server is upgraded. Nothing renews while the CLI is offline or unused.

Keys Last

Until the control in Settings exists, the server's security settings API field api_key_lifetime_days sets it. It applies to keys on the CLI sign-in API key's rules above.

Adding and trusting hosts

These keys let a host join, and let the server and the host trust each other.

Host join token

Adding a host by SSH gives the host a join token. It works once, for the time Add Link Lasts sets. A host that sends a faulty request does not use it up.

Adding the same host again replaces the token. If the time runs out, add the host again.

Figure pending

Add Link Lasts

up join code

Join Code Lasts

Host certificate

Every host proves who it is to the server with a certificate that lasts 7 days. The Infraternal agent on the host and the server renew it by themselves over their connection once half of the 7 days are gone, so a host that stays connected never sees it expire.

The host keeps the same private key across renewals. The key is stored on the host and never leaves it. If the machine certificate authority is locked when a renewal is due (see the next section), the renewal tries again every hour.

The planned change is that a host can still renew after expiry, for the time Renewal Grace Period sets, by proving it holds its key, unless it was removed.

Renewal Grace Period

Machine CA root

The machine certificate authority (CA) signs every host certificate. Its root lasts 10 years. Its private key is stored encrypted on the server, and after each server restart it stays locked until an administrator unlocks it with their passkey.

While it is locked, running hosts keep working and renewals wait.

Between machines

These keys protect the traffic between your machines, and your SSH logins over the mesh.

WireGuard session keys

Between two mesh nodes, WireGuard makes a new short-lived session key about every 2 minutes, by itself.³ You do nothing.

If two nodes cannot reach each other, they have no session. A new one starts as soon as they can.

WireGuard static key

Each mesh node has a long-lived WireGuard key that other nodes know it by. The decision is to replace it automatically, on the schedule Connection Keys sets, with an overlap of at least 2 minutes in which the old and the new key both work, so no connection drops.

This happens only while the host is online and can reach the server, and a key that may be compromised is replaced at once.

Connection Keys

Node identity key

Each node also has an identity key. The decision is to replace it automatically, on the schedule Machine Identity sets, with the new key signed by the old one, and only while the node is online.

Machine Identity

Mesh SSH person certificate

Connecting to a host over the mesh with SSH will use a short certificate for you.⁴ It is valid for 24 hours by default (an administrator can set 1 to 24 hours), and it renews quietly in the background.

The key behind it is private to you. It is kept in the Secure Enclave or the TPM when your device has one, and otherwise only in memory. Renewal needs the server, so a certificate that runs out while you are offline is replaced when you are back online.

References

1. Web Authentication, W3C Recommendation: how a browser makes and uses a passkey.
2. BIP-39, Mnemonic code for generating deterministic keys: the word list and format the recovery words follow.
3. WireGuard: Next Generation Kernel Network Tunnel, a session key is replaced after 120 seconds.
4. OpenSSH certificates: how a short certificate lets a host trust a key without a list of keys.