Middleware Reference

Every middleware exported by @riavzon/auth is documented here. Middleware functions follow the standard Express (req, res, next) signature unless noted otherwise. When using bootstrapApp(), the global middleware stack is already wired in the correct order. You only need to apply route-level middleware when building custom routes.

For the full middleware stack order applied by bootstrapApp(), see the Service page. For route-level middleware chains per endpoint, see the Routes Reference.

Authentication Guards

These middleware functions enforce token presence and validity on protected routes. They don't verify the token contents themselves -- that responsibility belongs to protectRoute.

requireAccessToken

Extracts the Bearer token from the Authorization header and attaches it to req.token. If the header is missing or malformed, the request is rejected immediately.

Import

import { requireAccessToken } from '@riavzon/auth'

Reads

Sets

Responses on failure

checkForActiveMfa

Checks the anomaly cache for the current refresh token and short-circuits requests that already have an unresolved MFA or re-login requirement. It hashes req.cookies.session, looks up that key in anomaliesCache(), and returns the cached response before the request reaches protectRoute or a sensitive controller.

Import

import { checkForActiveMfa } from '@riavzon/auth'

Reads

Responses on failure

requireRefreshToken

Checks that the session cookie containing the refresh token is present. Rejects the request if the cookie is missing.

Import

import { requireRefreshToken } from '@riavzon/auth'

Responses on failure

Reads

Responses on failure

protectRoute

The primary authentication middleware. Verifies the access token signature, decodes the payload, runs the full anomaly detection pipeline against the session context, and enriches the request with the authenticated user's identity. If anomalies trigger MFA, the middleware sends the challenge email and responds with 202.

Import

import { protectRoute } from '@riavzon/auth'

Reads

Sets

Responses on failure

Anomaly detection

The middleware calls strangeThings() internally, which runs nine checks including cookie binding, IP drift, user-agent drift, and geo anomalies. When anomalies are detected but the session is recoverable, the middleware automatically sends an MFA challenge email to the user and responds with 202 Accepted. The client must then complete the MFA flow before retrying the original request.

See the full Anomaly Detection pipeline for details on each check.

Recommended chain

router.get('/protected',
  requireAccessToken,
  requireRefreshToken,
  getFingerPrint,
  protectRoute,
  yourHandler
)

acceptCookieOnly

A strict input guard for cookie-only endpoints such as token rotation and logout. Rejects any request that carries a body, query string, or Content-Type header. This prevents injection vectors on endpoints that should only read from cookies.

Import

import { acceptCookieOnly } from '@riavzon/auth'

Reads

Responses on failure

Security Middleware

These middleware functions are applied globally by bootstrapApp(). You typically don't need to add them manually unless you're building a custom Express app without bootstrapApp().

helmet

Applies the Helmet security headers to every response. Pre-configured with the service's security policy.

Headers set

headers

Sets standard no-cache response headers on every response. This prevents browsers and proxies from caching sensitive authentication responses.

Headers set

validateIp

Validates that req.ip resolves to a valid IP address using Node's net.isIP(). If the IP is missing or invalid, the request is rejected with 403 Forbidden.

Responses on failure

hmacAuth

Verifies inbound requests using HMAC headers and a shared secret. Only active when service.Hmac is configured. Validates the client identity, timestamp freshness, signature integrity, and request uniqueness (replay protection via nonce cache).

Required headers

Validation steps

1. Checks that all four headers are present
2. Verifies the X-Client-Id matches the configured value
3. Rejects requests with clock skew exceeding the configured threshold (default: 5 minutes)
4. Rejects replayed request IDs using an LRU nonce cache
5. Recomputes the HMAC-SHA256 signature and compares using crypto.timingSafeEqual()

Bypass

• Local GET /health requests (from 127.0.0.1 or ::1) are allowed without HMAC headers

Responses on failure

See the HMAC Authentication page for integration details and client-side signing examples.

validateContentType

A factory function that returns middleware enforcing a specific Content-Type header. If the request's content type does not match the expected value, the request is rejected with 403 Forbidden.

Import

import { validateContentType } from '@riavzon/auth'

Signature

function validateContentType(expected: string): RequestHandler

Parameters

Usage

router.post('/data',
  validateContentType('application/json'),
  express.json(),
  yourHandler
)

Responses on failure

Verification Middleware

These middleware functions handle magic link and MFA verification on specific routes. They are used in the magic link route chains and are also exported for custom route composition.

verifyMFA

Verifies a one-time MFA code submitted via email. On success, issues new access and refresh tokens and calls next(). On failure, responds with the appropriate error status.

Import

import { verifyMFA } from '@riavzon/auth'

Reads

Responses

See MFA for the full adaptive MFA flow.

verifyNewPassword

Handles the password reset completion step after a user clicks the magic link. Validates the new password against the Zod schema, checks for data breach exposure, hashes the password, and updates it in the database.

Import

import { verifyNewPassword } from '@riavzon/auth'

Reads

Responses

Rate limiting

This middleware applies per-IP and per-composite-key (ip_visitor) rate limiting with consecutive failure tracking. See Rate Limiting for details.

customMfaFlowsVerification

Verifies custom MFA magic links used for sensitive actions such as account deletion, payment confirmation, or email changes. Validates the temporary JWT token, checks the random hash using crypto.timingSafeEqual(), enforces single-use semantics, and populates req.link on success.

Import

import { customMfaFlowsVerification } from '@riavzon/auth'

Reads

Sets

Behavior by HTTP method

Responses on failure

Rate limiting

Applies per-IP rate limiting with consecutive failure tracking. See Rate Limiting.

See also: Magic Links for the full custom MFA flow documentation.

Request Enrichment

getFingerPrint

Collects device, browser, geo, and network information from the incoming request and attaches it to req.fingerPrint. Uses @riavzon/bot-detector for User-Agent parsing and IP geolocation.

Import

import { getFingerPrint } from '@riavzon/auth'

Sets

Error behavior

If fingerprinting fails (for example, malformed User-Agent or geolocation service unavailable), the middleware logs the error and calls next() without setting req.fingerPrint. Downstream middleware should handle a potentially undefined fingerprint gracefully.

See Fingerprinting for how fingerprint data is used in anomaly detection.

Error Handling

These middleware functions are registered at the end of the middleware stack by bootstrapApp(). They catch unmatched routes and unhandled errors.

notFoundHandler

Returns a standardized JSON 404 response for any request that doesn't match a registered route. Registered after all route handlers.

Response

finalUnHandledErrors

The last-resort Express error handler. Catches any unhandled error that propagates through the middleware stack, logs it, and returns a normalized JSON error response.

Error handler signature

(err: any, req: Request, res: Response, next: NextFunction) => void

Status code logic

• Uses the existing res.statusCode if it is greater than 415
• Defaults to 500 otherwise

Response

Logging

httpLogger

A pino-http middleware that logs every HTTP request and response. Writes structured JSON logs to auth-logs/http.log. Automatically redacts the Authorization header and session cookie values in log output.

Features

• Generates a unique X-Request-Id header for each request (or uses the existing one)
• Redacts req.headers.authorization and req.cookies.session in logs
• Skips logging for static asset requests (.css, .js, .png, etc.) and .well-known/ paths
• Logs IP address, User-Agent, full URL, and cookies as structured context
• Auto-selects log level based on response status: info for 2xx/3xx, warn for 4xx, error for 5xx

Internal Link Verification

The following middleware functions handle magic link verification for built-in flows (MFA and password reset). They are not exported individually but are used internally by the magic link route handlers.

linkMfaVerification

Verifies MFA magic links. On GET, previews the link status and allows a configurable number of views. On POST, consumes the link (single-use) and populates req.link for the downstream verifyMFA handler.

Validation pipeline

1. Validates query parameters (token, random, reason, visitor) against a Zod schema
2. Applies per-IP rate limiting with consecutive failure tracking
3. Verifies the temporary JWT signature and expiry
4. Checks visitor identity match between URL and token payload
5. Verifies the random hash using crypto.timingSafeEqual()
6. Enforces configurable GET/POST usage limits per JTI

linkPasswordVerification

Verifies password reset magic links. Follows the same validation pipeline as linkMfaVerification but uses separate rate limiter instances and threshold configuration (magic_links.thresholds.linkPasswordVerification).

Middleware Stack Order

When bootstrapApp() wires the Express app, middleware is applied in this exact order: