How to put routes behind an identity check
You will make some or all of a service's routes answer only a verified caller, hand that caller to each handler as a typed field of its context, and decide what a refused request writes to your log.
In @hyperfrontend/server an identity check is a step like any other: a function that answers the request or passes it on. Its position does the work. Where it stands decides which routes it covers, whether a platform's probes and a browser's preflights get past it, and whether a refusal is logged with the request's path or with a route's name.
The examples come from a small service with a public status route, one report route that needs a caller and an admin table that needs one throughout. It checks a bearer token against a secret read from the environment; put your own verification in its place.
1. Write the step that verifies the caller
Type the step as a Step with two type arguments: what it reads from the context, which is nothing (NoContext), and what it adds for everything inside it. Refuse a caller by throwing an httpError with status 401 and a WWW-Authenticate header. Let one through by returning next() with the fields to add:
// identity.ts
import type { NoContext, Step } from '@hyperfrontend/server'
import type { Secret } from '@hyperfrontend/server/environment'
import { createHash, timingSafeEqual } from 'node:crypto'
import { httpError } from '@hyperfrontend/server'
export interface Identified {
readonly subject: string
}
const digest = (text: string): Buffer => createHash('sha256').update(text).digest()
export function bearerIdentity(token: Secret, subject: string): Step<NoContext, Identified> {
// the text leaves the wrapper once, here, and only its digest is kept
const expected = digest(token.reveal())
return (request, _context, next) => {
const header = request.headers.authorization ?? ''
const sent = header.startsWith('Bearer ') ? header.slice(7) : ''
if (!timingSafeEqual(digest(sent), expected)) {
throw httpError(401, 'unauthenticated', { 'WWW-Authenticate': 'Bearer' })
}
return next({ subject })
}
}
The client is sent the status, its reason phrase and the header. The code, unauthenticated here, goes to the request's log line and stays out of the response. A verifier that waits on something, such as a key lookup or a call to an identity provider, makes the step async and changes nothing else.
A Secret prints as [secret] wherever it is written out, and reveal() is the one way to its text. Reveal it once, where the step is built, and keep only what the comparison needs. Here that is a digest, which also gives timingSafeEqual the two inputs of equal length it requires. Hand the revealed text only to code that cannot quote it back in an error message.
2. Build the step where the secret is read
Declare the secret with asSecret in the service's environment, and build the step in the start function of defineService, which receives the values once they have been checked. The first import already names what steps 4 to 6 add to this file:
// service.ts
import { chain, cors, defineService, guard, health, jsonResponse, readiness, route, router, startService } from '@hyperfrontend/server'
import { asPort, asSecret, defineEnvironment, optional, required } from '@hyperfrontend/server/environment'
import { bearerIdentity } from './identity.js'
export const service = defineService({
environment: defineEnvironment({
http: { PORT: optional(asPort(), 8080) },
auth: { API_TOKEN: required(asSecret()) },
}),
start(values, context) {
const requireIdentity = bearerIdentity(values.auth.API_TOKEN, 'operator')
// the routers of steps 4 and 5, then the list of step 6
},
})
A deployment that lacks the token, or carries one shorter than 16 characters, does not start. runService prints the problem without the value and exits with code 78, so the service never runs with its check unset:
fatal cause=environment
- API_TOKEN (auth) is missing; expected a secret of at least 16 characters.
3. Decide what the step stands in front of
The step can stand in front of a whole router or inside one route. The two differ in more than coverage:
| In front of a router | Inside one route | |
|---|---|---|
| Covers | Every route of the table, and every path it has no route for | That route only |
| A path no route knows, asked without credentials | 401 | 404 |
| A refusal is logged with | The request's path | The route's name |
Decide on the last row. The router names a route before the route's handler runs, and from then on the request's event carries that name in place of the path. A step ahead of the router refuses a request no route has claimed yet, so its event carries the path. Two rules follow:
- A token, a signed link or any other capability goes in a header or in the body, never in a path.
- A check whose refusals must stay out of the log by path goes inside the route.
4. Put the step in front of a whole router
Compose the step and the router with chain, inside the start function. It carries what the step adds to the router in the types, so every handler of the table reads the caller from its context as a string:
const admin = chain(
requireIdentity,
router({
'admin.whoami': route('GET', '/admin/whoami', (_request, context) => {
return jsonResponse(200, { subject: context.subject })
}),
})
)
5. Put the step in front of one route
In a table that is otherwise public, wrap the one handler with guard. The handler keeps the params typed from its pattern and gains what the step adds:
const open = router({
status: route('GET', '/status', () => jsonResponse(200, { up: true })),
'reports.read': route(
'GET',
'/reports/:id',
guard(requireIdentity, (request, context) => {
return jsonResponse(200, { report: request.params.id, subject: context.subject })
})
),
})
6. List the steps with the probes and the browser grant ahead
Steps run in the order they are listed, outermost first, so give startService this order:
const fromSite = cors({ origins: ['https://site.example'], headers: ['Authorization'] })
return startService(
{
port: values.http.PORT,
steps: [health(), readiness(), fromSite, open, admin],
},
{ report: context.report }
)
healthandreadinesscome first. A probe carries no credentials, and an identity step ahead of them answers it 401.corscomes ahead of the identity step. A browser's preflight carries noAuthorizationheader, so an identity step ahead ofcorsrefuses every one. In this order the preflight is answered, and a 401 on its way out gains the grant, so the page can read the status.corstells a browser what it may read; the identity step is what decides who may call.- The public table comes ahead of the chained one. A chained step judges every request that reaches it, so list it after the routes that must stay open.
The report function handed on from the runner's context writes one line per request, which is where step 3's choice shows.
7. Hold the wiring to what the types say
The compiler catches two mistakes only under flags that strict turns on:
- Without
strictFunctionTypes, a router whose handlers read the caller can be listed with no identity step in front of it. Each handler then readsundefinedand answers as if it had a caller. - Without
strictNullChecks, a step can callnext(undefined). Nothing is added, and the handlers behind it readundefinedin the same way.
With strict on, both are compile errors (TS2322 on the list of steps, TS2345 on the call) and you are done. Without it, pass next() an object written at the call, as step 1 does, and read the caller through a function that checks it is there:
// identity.ts
export function subjectOf(context: Partial<Identified>): string {
if (typeof context.subject !== 'string') {
throw httpError(500, 'identity-step-missing')
}
return context.subject
}
A handler that returns subjectOf(context) where it would have read context.subject answers 500 when the step is missing, and its log line says why:
request method=GET route=admin.whoami status=500 outcome=sent ms=2 failure=identity-step-missing
Check it worked
Start the service with the token in its environment and ask for a guarded route with no header:
curl -i localhost:8080/reports/7
HTTP/1.1 401 Unauthorized
Content-Type: text/plain; charset=utf-8
Cache-Control: no-store
WWW-Authenticate: Bearer
Vary: Origin
Content-Length: 12
Date: Sun, 22 Nov 2026 17:17:21 GMT
Connection: keep-alive
Keep-Alive: timeout=5
Unauthorized
Then the same route with the header, a route behind the chained step without it, and a probe:
AUTH='Authorization: Bearer correct-horse-battery-staple'
curl -s -w ' %{http_code}\n' -H "$AUTH" localhost:8080/reports/7
curl -s -w ' %{http_code}\n' localhost:8080/admin/whoami
curl -s -w ' %{http_code}\n' localhost:8080/healthz
{"report":"7","subject":"operator"} 200
Unauthorized 401
ok 200
The service's own output has one line for each of the four requests:
started port=8080
request method=GET route=reports.read status=401 outcome=sent ms=5 failure=unauthenticated
request method=GET route=reports.read status=200 outcome=sent ms=1
request method=GET path=/admin/whoami status=401 outcome=sent ms=0 failure=unauthenticated
request method=GET path=/healthz status=200 outcome=sent ms=0
The first refusal names its route and holds no path: it came from inside the route. The second holds the path: it came from the step ahead of the router. Read your own refusals the same way. If one shows a path you would not want kept, move that check into its route.
Reference and background
Next steps
How to run a Node.js service under a supervisor and a proxy
My service runs fine from a terminal, but in production something else starts and stops it: a deploy cuts requests in flight, a missing variable turns into a restart loop, the load balancer answers a 502 now and then, and neither the exit code nor the log tells the platform or me which of those happened.
How to test a service from start to exit code without a process
I want specs for how my service boots, stops and exits, but the only way I know to test that is to spawn it, wait for its port, send it a signal and read its exit code, which is slow and depends on timing, and a service I run inside the test process instead ends the test runner when it exits.