Authenticator app PIN

The 6 digit code of an authenticator app guards every folder of the account. The code changes every 30 seconds, so a PIN that leaks with a link is useless within 90 seconds.

LLM-friendly version (Markdown): https://tmphost.io/docs/pins/authenticator.md

Why an authenticator app

A static PIN is one more secret that can be written down next to the link, and it opens every folder until it changes. An authenticator code is time-based (TOTP): the app and tmphost.io share a secret and both work out the same code for each 30 second step. There is nothing fixed to leak. A code read out, typed into a chat or saved in a ?pin= link stops working on its own within about a minute and a half, and the folder stays shut to anyone who did not get in while it was good.

Set it up

1. Sign in at app.tmphost.io/security.
2. Under Account PIN, pick Authenticator app. A QR code appears.
3. Scan it with an app such as Google Authenticator or 1Password, or type in the key shown next to it. The entry is named tmphost.io.
4. Enter the 6 digit code the app shows, then save. The code proves the app has the secret; without it nothing is saved.

The secret is encrypted at rest and bound to the account, so it can't be moved to another. Folder results now carry "pinMode":"totp".

Through the API, the same two steps with the account's token: ask for a secret, then save it with a current code.

$ curl -sS -X POST -H "Authorization: Bearer $TOKEN" $API/users/me/pin/totp
{"secret":"JBSWY3DPEHPK3PXP...","url":"otpauth://totp/tmphost.io:...","qrCode":"data:image/png;base64,..."}
$ curl -sS -X PUT -H "Authorization: Bearer $TOKEN" \
    -d '{"mode":"totp","secret":"JBSWY3DPEHPK3PXP...","code":"731406"}' $API/users/me/pin
{"mode":"totp","agentPins":false}

Secret and code are examples. A wrong code answers 400 ("the code does not match the authenticator secret").

How codes are checked

• A code is 6 digits and lasts 30 seconds.
• The code just before and just after the current one are accepted too, for clocks that drift a little. So a code is good for about 90 seconds at most.
• Two wrong codes in a minute, per folder and address, answer 429 until the minute is over. Only wrong codes count.

What visitors see

The "Enter PIN" page. They type the code the owner's app shows right now, so the owner reads it to them, sends it, or opens the folder themselves. After that, the browser keeps a cookie for the folder until the folder expires: the code is needed once, not every 30 seconds. More in what visitors see.

Setting up the app again with a new secret locks out everyone who got in with codes of the old one.

What agents see

Results carry "pinMode":"totp" and no pin; the CLI prints "pin: required (your authenticator app's code)". The agent gives the user the URL and says it opens with a code from their authenticator app. Folder PINs don't apply while this mode is on: a request for one answers 409.

When to pick it