PINs for folders

Every folder already lives at an unguessable 8 character URL. A PIN adds a second lock: a visitor who has the link must also enter a 6 digit PIN before they see a single file. There are three ways to set one.

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

01Static PINOne 6 digit PIN the owner picks. It guards every folder of the account, today's and tomorrow's.
02Authenticator appThe code of an app such as Google Authenticator or 1Password, which changes every 30 seconds. Guards every folder.
03Folder PINA random PIN for one folder, made by the agent or the owner and shown once.

Why PINs, on top of unguessable URLs

A folder id is 8 random base36 characters, such as k7q2m9xa in https://k7q2m9xa.file.tmphost.io/. Ids come from a cryptographic random source, not a counter or a clock, so there are about 2.8 trillion of them and nobody can walk from one folder to the next. Nobody finds a folder by guessing.

But an unguessable URL is still a bearer secret: whoever holds the link sees the files. Links travel further than their owners mean them to:

chat logs, agent transcripts and tickets that more people can read than the one the link was for;
link previews and unfurlers in chat apps, and scanners in email, which fetch the URL on their own;
browser history, synced bookmarks, screenshots and screen shares;
an agent that pastes the link into a public issue, a commit message or a log.

A PIN is something the link does not carry. A leaked link alone opens nothing: the visitor gets a page that asks for the PIN. Send the link and the PIN by different routes (the link in the chat, the PIN said out loud, or in another message), and one leak is no longer enough.

PINs are optional. A folder without one works exactly as before.

Three strategies

The owner picks one account PIN mode on the Security page of the web app (app.tmphost.io/security): off, static or authenticator app. An account PIN guards every folder the account owns. While the account PIN is off, any folder can get a PIN of its own.

	Static PIN	Authenticator app	Folder PIN
Guards	Every folder of the account	Every folder of the account	One folder
Who picks it	The owner, on the Security page	The app, a new code every 30 seconds	tmphost.io, at random
Changes	When the owner changes it	Every 30 seconds	When a new one is made for the folder
Who knows it	The owner, and whoever they tell	Whoever holds the owner's app	Whoever got it from the call that made it
Set up by	Web app	Web app, with a QR code	Agent (MCP, CLI, API) or web app
`pinMode`	`static`	`totp`	`folder`
Best for	An owner who shares with the same few people	An owner who opens the files, or reads a code out live	An agent handing one folder to one person

When both could apply, the account PIN wins: a static or authenticator PIN guards every folder, and a request for a folder PIN answers 409 ("the account pin guards this folder"). Turning the account PIN off brings back any folder PINs that were set.

Every PIN is exactly 6 digits. Static and folder PINs are stored only as bcrypt hashes, so tmphost.io can't show them again; the authenticator secret is encrypted at rest and bound to the account.

What visitors see

A visitor of a guarded folder gets an "Enter PIN" page instead of the file, with one 6 digit field. Then:

Once per browser. The right PIN sets an HttpOnly cookie for that folder, valid until the folder expires, and sends the visitor on to the file they asked for. Every other file in the folder opens without asking again.
Or a link with the PIN. https://k7q2m9xa.file.tmphost.io/?pin=482913 opens the folder without the page. tmphost.io sets the cookie and redirects to the same URL without ?pin=, so the PIN does not stay in the address bar or the history.
A new PIN locks everyone out again. The cookie names the PIN it was made for. Changing the static PIN, setting up a new authenticator, or making a new folder PIN voids every cookie for the old one.

Files of a guarded folder are sent with Cache-Control: private, so a shared cache or proxy never hands them to someone without the PIN.

Guessing a PIN

6 digits are a million combinations, so the server limits tries: 2 wrong PINs per minute, per folder and per IP address. The next try in that minute answers 429 with Retry-After: 60 and "Too many wrong PINs. Wait a minute, then try again." Only wrong PINs count; a visitor who types the right one is never slowed down.

At that rate, one address would need about 174 days to try half of all PINs, far longer than a folder lives. An authenticator code is harder still: it is only good for about a minute and a half before the app moves on.

For agents

Folder results carry pinMode when a PIN guards the folder: static, totp or folder. It is missing when the folder is open. The CLI prints the same as a line:

Shell

$ tmphost file get --id k7q2m9xa
...
id:      k7q2m9xa
url:     https://k7q2m9xa.file.tmphost.io/
expires: 2026-10-24 04:15 UTC (in 29m)
pin:     required (your account PIN)

static or totp: the agent never sees the PIN. Give the user the URL and say it needs their account PIN, or their authenticator code.
folder, with pin in the result: this call made the PIN, and it is the only time it is shown. Give it to the user with the URL, in a separate line, so they can pass the two on separately.
Lost a folder PIN? It can't be read back. Make a new one (folder PIN); the old one stops working.

What a PIN does not do

It does not encrypt the files. It decides who the server shows them to.
A ?pin= link carries the PIN. Shared as one piece, it is a single secret again, like the plain URL.
It does not change what belongs on tmphost.io. Files are temporary and meant to be shared; keep secrets and private data out unless the user asks for them to be uploaded.
It guards the public URLs only. The owner's own API, CLI and MCP calls use their sign-in, not the PIN.