Next.js
Send security events from route handlers and server actions, set a request ID in
proxy.ts, add OpenTelemetry in instrumentation.ts, and keep Pino for application logs.
Read the shared guidance first.
Example: examples/asvs-logging/node/nextjs
(Next.js 16, App Router). check.sh builds it, with type checking, in a temporary copy.
Set up
- Copy
node/bower-events.mjsand its type filebower-events.d.mtsintolib/. - Add
lib/bower.ts. Itssecurity()function reads the request headers, adds the client IP, user agent, request ID and active trace ID, and sends the event. It importsserver-only, so it can't end up in a client bundle, where the ingest token would leak. - Set
BOWER_COLLECTOR_URL,BOWER_INGEST_TOKENandTRUSTED_PROXIESin the server environment. Never prefix them withNEXT_PUBLIC_.
Request ID and client IP: proxy.ts
proxy.ts (called middleware.ts
before Next.js 16) gives each request an ID, reusing the traceparent trace ID when there is
one, and passes it on in x-request-id.
Next.js has no reliable peer address in route handlers. The proxy copies the header named in
BOWER_PEER_HEADER (for example x-real-ip) into x-bower-peer, and overwrites any
x-bower-peer the client sent. Set BOWER_PEER_HEADER only when your load balancer or
platform always sets that header itself and drops client copies of it. Unset, nothing is
trusted and events carry no source IP. security() then applies TRUSTED_PROXIES to
X-Forwarded-For as usual.
Route handlers
// app/api/login/route.ts
export const runtime = 'nodejs';
export async function POST(request: Request) {
// ... check the credential with your identity provider ...
if (!ok) {
await security({ eventCategory: 'authentication', eventType: 'authentication_failure',
eventAction: 'authentication.attempt', eventResult: 'failure', eventSeverity: 'low',
reason: 'InvalidCredentials', actor: { username }, route: '/api/login' });
return NextResponse.json({ error: 'invalid credentials' }, { status: 401 });
}
await security({ eventCategory: 'authentication', eventType: 'authentication_success',
eventAction: 'authentication.login', eventResult: 'success',
actor: { userId: user.id, username }, labels: { authMethod: 'password' }, route: '/api/login' });
return new NextResponse(null, { status: 204 });
}
Pass route yourself: Next.js doesn't expose the matched route template to the handler.
Use the file path pattern (/api/invoices/[id]). The full file is
app/api/login/route.ts;
app/api/admin/users/route.ts
shows an authorisation failure.
Server actions
Check permission inside the action, emit the decision, then act.
app/admin/actions.ts
emits authorisation_failure when a member tries to disable a user, and
account_status_changed when an admin does. Use action:<name> as the route.
OpenTelemetry and errors: instrumentation.ts
instrumentation.ts
registers @vercel/otel, so security() can add the active span's trace ID as
request.traceId. Its onRequestError hook sends one application_error event for each
unhandled server error, with the error type and route but no message or stack trace (ASVS
5.0 V16.3.4, V16.5.4).
@vercel/otel 2.x needs its OpenTelemetry peers installed explicitly; the example's
package.json pins a set that resolves together.
Pino
lib/logger.ts uses ISO UTC
timestamps and removes authorisation headers, cookies, passwords and tokens. Add pino to
serverExternalPackages in next.config.mjs.
What was run
check.sh (next build with type checking) passes. The built app was started and sent all
four test requests to a local collector with the ASVS pack: three were accepted, the
malformed body was accepted as input_validation_failure, the client IP came from the
proxy-set header, and no password, CRLF or spoofed header value reached the collector's
redacted output.