You need: auth composed. That is the whole prerequisite.
One import, one middleware
Routing and verification is what the middleware resolves, entitlements is the gate that stacks after it, and adding a route is where a handler comes from.
import { requireAuth } from "@pithy-sh/auth";
app.get("/notes", requireAuth(), async (c) => {
const rows = await c.var.db.app
.selectFrom("notes")
.where("authorId", "=", c.var.auth.userId)
.selectAll()
.execute();
return c.json({ notes: rows });
});c.var.auth carries the resolved identity — the user id, and the session and device ids. It is null until a verification strategy sets it, and requireAuth() is what turns that null into a 401 before your handler runs.
So inside the handler it is not null, and you are not writing a check.
Every other capability gates the same way
None of them validates a token. They all read the same identity seam, which is why adding payments or storage later needs no auth wiring from you: the seam is already filled.
That is also what makes the absence coherent. With auth not composed, the seam is null and those routes deny — a defined behavior rather than a crash.
Gating on an entitlement
app.get("/reports", requireAuth(), requireEntitlement("pro"), handler);Identity first, then entitlement. You cannot ask what somebody is entitled to before you know who they are.
requireEntitlement lives in core rather than in the payments package, on purpose: a route should be able to say what it requires without importing the capability that provides it. With no provider composed, the seam denies — a gate with no provider fails closed rather than standing open.
That creates one failure worth knowing about. A Worker gating on entitlements while composing no provider is not broken, it is silently paywalled shut, and the runtime cannot tell that mistake from a legitimately unentitled user. So the CLI answers it instead: pithy doctor and pithy dev compare the gates in your source against what the Worker composes, and say so at startup rather than leaving you a fleet of production 403s.
Name the entitlement key, never a product. pro, not pro_monthly — that is the distinction the whole payments model rests on.
The full stack, in order
app.post(
"/reports",
describeRoute({
summary: "File a report.",
verification: ["bearer", "session"],
responses: { 201: Report },
}),
requireAuth(),
requireEntitlement("pro"),
validate("json", CreateReport),
handler,
);Description, identity, entitlement, request contract, handler. The order is not cosmetic. describeRoute comes first because it only carries what the OpenAPI document reads, and does nothing when it runs.
A validator ahead of a gate turns a 401 into a 400 — and tells an unauthenticated caller which requests were well-formed. On an admin surface that is an oracle rather than a courtesy.
Never parse input inside a handler. A handler takes typed values, so the route signature carries the whole contract and a reader can see what a route accepts without reading its body. validate applies the one failure hook, so a bad request renders as validation/invalid_input through the same error path as everything else — one failure format, whatever failed — and it leaves the schema where the OpenAPI document can read it.
Stacking a humanity check
Turnstile is not a verification strategy. A strategy answers who is this; a humanity check answers is this a human. Different questions, so it stacks on top rather than replacing anything:
app.use("/signup", turnstile());A public signup route that still requires a token is a coherent thing, and it is only expressible because the two are kept apart.
Same-origin, for a cookie session
Where you accept a cookie session, a state-changing route wants the same-origin gate beside the auth one:
app.post("/organizations", describeRoute({ … }), requireAuth(), requireSameOrigin(), validate("json", …), handler);The gate arrives already bound to your Worker’s trusted origins by whichever capability resolved them — you get the decision rather than the material to rebuild it, because handing over the list is how a Worker ends up with two same-origin implementations free to disagree, and the weaker one is then its real policy.
A recent sign-in, for a route that can do lasting harm
Revealing a stored secret, changing who can see something, exporting a person’s data: a route like that should not open on a session that has been signed in all week. requireRecentSignIn gates it on a sign-in within the window the route names:
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);A caller with no credential gets what requireAuth() answers, a 401. One who signed in too long ago gets 403 auth/recent_sign_in_required, and the refusal is audited with your purpose. A rotated session keeps its original sign-in time, so only a fresh sign-in passes. Require a recent sign-in has the window, the refusal, and how a web and a phone client answer it.
Declaring a route public
A route with no strategy is not the same as a route with public. public is a positive declaration that this route is open on purpose, and it reads as one in review.
Nobody wrote a gate here and we decided this needs no gate look identical in code and are completely different facts.
describeRoute({ verification: "public", … }) is where that declaration is written, and it lands in the OpenAPI document as the operation’s x-pithy-verification, so a client author reads the same decision a reviewer does.
What a caller sees
401 — the credential is missing, expired or revoked. Sign in again. A mobile client rotates before its session expires, so a 401 means the session is gone.
403 — the caller is who they say and may not do this. Do not retry. The exception is a refusal for want of a recent sign-in, auth/recent_sign_in_required on a route you gated or auth/session_not_fresh on connecting a sign-in provider: sign in again, then retry once.
A client that treats those the same loops: it signs in or rotates a perfectly good session, gets another 403, and goes round again.
Check it worked
- The route answers for a signed-in caller
- It 401s with no credential, and with an expired one
- With an entitlement gate: it 403s for somebody without the key, and
pithy doctorreports no gap - With a validator: a malformed body gets a 400 carrying the failing field