How login works

What happens behind each tap: the three ways to run keel serve, pairing, passkey and code sign-in, sessions, and how to end them.

This page explains what Keel does at each step of using it from your phone, in plain words and pictures. You don’t need it to use Keel; it’s here for when you want to know why something works the way it does.

Three ways to run keel serve

• keel serve listens only on your own computer (127.0.0.1). Nothing else can reach it, so there is no login. This is how Keel has always worked.
• keel serve --public-url https://<name> is for a tunnel in front of Keel. Login turns on for every request, even from your own computer, because the tunnel makes the same port reachable from the internet.
• keel serve --host 0.0.0.0 listens on your network. Keel refuses to start until there is HTTPS (--cert and --key, or --public-url) and at least one login (a passkey or codes).

The parts

What	Where	What’s in it
Passkeys	~/.keel/auth/passkeys.json	Each phone’s public key, its name, the address it belongs to, when it was last used. No secrets.
Sessions	~/.keel/auth/sessions.json	Who is signed in, for what, until when. Only a hash of each cookie, never the cookie itself.
Pairing links	~/.keel/auth/pairings.json	Only a hash of each one-time link.
Codes on or off	~/.keel/auth/totp.json	When codes were turned on, and the last code used.
The code key	macOS Keychain or the Linux keyring	The secret your authenticator app also has.

The folder and its files can only be read by you. None of it is synced to other devices: a passkey belongs to one computer’s address.

The phone can only sign in. Adding a phone, removing one, turning codes on or off, and ending sessions all happen in your own terminal with keel auth. Someone who gets hold of the browser can’t add a login of their own.

Pairing a phone

• The link’s secret sits after the # in the address, so it is never sent in a request. The tunnel and any logs never see it, and the page removes it from the address bar.
• The link works once and for 10 minutes. Pressing Ctrl+C in the terminal cancels it at once.
• Face ID makes a new key pair on the phone. The private half never leaves the phone; Keel only stores the public half, which can check signatures but can’t make them.
• Pairing also signs the phone in to Goals, so it’s ready to use.

Signing in with a passkey

• Each challenge is random, works once and lasts 5 minutes, so a recorded sign-in can’t be replayed.
• The phone only offers the passkey at the address it was made for. A look-alike site gets nothing, which is why passkeys can’t be phished.
• Keel checks that Face ID (or the screen lock) was used, not just that the phone was unlocked.
• After 10 failed attempts in a minute, Keel answers “Too many tries” until the minute is up.

Codes from an authenticator app

Codes are optional. They help in a browser without passkeys, and at local addresses (localhost, 192.168.x.x) where passkeys can’t work.

Turning codes on, in your terminal

Signing in with a code

• Your app and Keel share one secret key and the clock. Every 30 seconds both work out the same six digits; nothing is sent between them.
• A code is accepted for 30 seconds either side of its time, in case the phone’s clock is a little off.
• Each code works once, even if Keel restarts in between.
• A code sign-in always lasts 12 hours, also for Goals, because a code is easier to copy than a passkey.
• Running keel serve reads the key from the Keychain at each code sign-in, so turning codes on needs no restart.

Every request

• The page itself always loads, so you can see the sign-in screen. Your data only comes through the API, which needs a session.
• The session lives in a cookie the page’s scripts can’t read (HttpOnly), that is only sent over HTTPS (Secure), and that other sites can’t use to send commands.
• A browser terminal session also opens Goals, but not the other way round.
• Opening Goals without a session takes you to the sign-in page, and back to the same Goals page afterwards. So does a session that ends while Goals is open.

How long a sign-in lasts

The browser terminal can run every command, so it asks again twice a day. Goals only shows your goals, so it stays signed in for 30 days while you use it.

The right address

A passkey is tied to the name it was made for. Opened at another address, the sign-in page says where passkeys work and links there, or shows the code box when codes are on.

Ending access

An ended session stops working at once. A page that is already open finds out on its next command and shows Your session ended.

Removing a passkey only ends the sessions that passkey started. A browser that signed in with a code stays signed in, which is why the lost-phone steps also end every session:

What login doesn’t protect

Login keeps other people out of keel serve. It doesn’t encrypt your data on the disk: anyone who can use your unlocked computer can read Keel’s files, as before. Lock your computer, and keep your tunnel name to yourself.

For the full reasoning, see ADR 0002 in the repository.