You need: auth composed. That is the whole prerequisite.
The routes worth gating
Protect a route is the gate this one stacks beside, sign in on iOS and Android is where a phone’s session comes from, and error codes has the refusal beside every other auth/ code.
Some routes should not be reachable on a session that has been open all week. Use the gate where a stolen or unattended session would do lasting harm the account holder cannot undo:
| Route | Why |
|---|---|
| Revealing a stored secret | It is shown once, and cannot be taken back |
| Changing who can see something | Access granted to the wrong person stays granted |
| Exporting a person’s data | The data has left |
| Sending money out | The same |
Leave it off ordinary reads and writes. A gate a person meets on every screen trains them to sign in without thinking, and costs them a sign-in for nothing.
It is not a permission check. Who may call the route is still requireAuth(), a role or a scope. This gate adds one question: did this caller sign in recently?
One line on the route
import { requireRecentSignIn } from "@pithy-sh/auth/src/http/recentSignIn";
app.post(
"/things/:id/secret",
describeRoute({ … }),
requireRecentSignIn({ maxAgeSeconds: 300, purpose: "things/secret_revealed" }),
validate("param", ThingParams),
handler,
);| Option | What it is |
|---|---|
maxAgeSeconds | The window, a whole number above zero. Five minutes suits a secret shown once; fifteen suits a settings change. Each route names its own, so two routes can hold two windows |
purpose | What the route protects, as <domain>/<reason> in your app’s own domain. Recorded on every refusal |
Both are checked when the route is declared. A maxAgeSeconds of 0, 2.5 or "300", or a purpose that is not <domain>/<reason>, throws at startup rather than on a request.
A caller with no credential, or one that does not resolve, gets exactly what requireAuth() answers: 401 auth/invalid_token.
What it checks
Every session carries authenticatedAt, the instant its holder signed in. A sign-in stamps it, and nothing else does: /auth/token/rotate carries it forward to the successor unchanged. The gate passes a session whose authenticatedAt is no older than maxAgeSeconds, boundary included.
It refuses a session whose authenticatedAt is older, absent, unreadable or in the future. None of those is evidence of a recent sign-in.
A bearer session and a cookie session are judged by the same rule, and no exemption by client kind can be configured. An on-device biometric check is not proof the Worker can verify, so an exemption for phones would pass any stolen bearer token.
The refusal
| Caller | Status | Code |
|---|---|---|
| No credential, or one that does not resolve | 401 | auth/invalid_token |
Signed in, but not within maxAgeSeconds | 403 | auth/recent_sign_in_required |
{ "error": { "code": "auth/recent_sign_in_required", "status": 403, "message": "Sign in again to continue. Nothing was changed." } }The handler never ran, so nothing was changed, and the message says so. The code is the same on every gated route in every app, so a client writes its handling once. @pithy-sh/i18n carries the message in Spanish, keyed by the code.
Before it throws, the gate records auth/recent_sign_in_refused on the audit trail, outcome denied, severity warning, with the user, the session and your purpose as metadata.purpose. One action covers every gated route, so one filter finds every refusal and the purpose says which route. A run of them against one user is a stolen credential being walked toward something the app protects.
Answering it on the web
A browser holds a cookie session. On a 403 with auth/recent_sign_in_required:
- Keep what the person was doing: the route, its body, the screen they were on.
- Send them through a sign-in: a magic link, a code, or a provider button. Each one sets a new session cookie with a new
authenticatedAt. - Retry the request once.
Do not sign the person out first. The old session still works for every ungated route, and a fresh sign-in replaces it. Do not retry without a sign-in: the answer will be the same.
Answering it on a phone
A native app holds a bearer session through createBearerSession, and rotates it before it expires. A rotation never passes the gate. The successor keeps the original authenticatedAt, so a phone signed in last month is still signed in last month after a thousand rotations. An app that answers the refusal by rotating, or by retrying, loops forever.
On a 403 with auth/recent_sign_in_required:
- Keep what the person was doing.
- Run a sign-in: an email code, or a provider through the redirect handoff. It answers with a new raw session token.
- Hand that token to
session.adopt(token). It is held and stored beforeadoptresolves, and every request after it carries the new session. - Retry the request once.
An on-device biometric prompt may come before step 2, to decide whether to offer the sign-in at all. It never replaces it.
The provider-change gate is the same check
Connecting and disconnecting a sign-in provider (POST /auth/link-social, POST /auth/unlink-account) holds its own gate on the same check, with a fixed fifteen-minute window. It refuses with auth/session_not_fresh and records auth/session_not_fresh on the trail, not these. A client meets that code only on those two routes, and answers it the same way: sign in again, then retry.
For a check outside a route, import the test the gates use:
import { authenticationIsFresh } from "@pithy-sh/auth/src/http/providerFreshness";authenticationIsFresh(authenticatedAt, now) reads the fifteen-minute window, and authenticationIsFresh(authenticatedAt, now, seconds) reads the window you give it.
Check it worked
- A session signed in inside the window reaches the handler
- A session signed in before the window gets 403
auth/recent_sign_in_required, and the trail holds anauth/recent_sign_in_refusedrow with yourpurpose - A rotated session from an old sign-in is still refused
- No credential gets 401
auth/invalid_token - A bad
maxAgeSecondsorpurposestops the Worker at startup