Middleware Reference

Every middleware exported by auth-h3client is documented here. Import them from auth-h3client/v1 or auth-h3client/v2. When using the Nuxt module, all middleware is auto-imported inside the server/ directory and the global chain is wired automatically. For other setups, register the global middlewares and route-level wrappers explicitly as shown in the H3 or Nitro setup.

For the global middleware stack order applied automatically, see Security: Request Lifecycle. For route-level middleware chains per registered endpoint, see the Routes Reference.

Authentication guards

These middleware and wrappers enforce token presence, session validity, and HMAC signature verification before your handler runs.

ensureValidCredentials

The core token rotation middleware. Checks the access token expiry state and rotates both the access and refresh tokens when needed by calling the IAM /auth/user/refresh-session endpoint. Deduplicates concurrent rotation attempts on the same session so that only one rotation call is sent to the IAM service even if multiple requests arrive simultaneously.

On success, sets event.context.accessToken and event.context.session. Returns a 202 MFA response rather than throwing when the session requires step-up verification.

Reads

Sets

Responses on failure

hmacSignatureMiddleware

Generates HMAC-SHA256 signature headers for every outbound request the module sends to the IAM service. Reads the current request method and URL path, computes the signature using the sharedSecret from the configuration, and stores the resulting headers on event.context.authHeaders. serviceToService reads those headers when forwarding requests to the IAM service.

Reads

Sets

CSRF middleware

generateCsrfCookie

Mints a signed __Host-csrf cookie when one is not already present on the request. The token is a 32-byte random hex string, signed with an expiring HMAC payload using cryptoCookiesSecret.

Cookie attributes

Runs automatically in global middleware. Also runs on all GET magic link routes to prepare a fresh cookie for the page that will be rendered.

verifyCsrfCookie

Validates the __Host-csrf cookie signature and expiry, then checks that the X-CSRF-Token request header contains a value that matches the token stored inside the cookie payload. The comparison uses isSameBuffer for timing-safe equality to prevent timing side-channel attacks.

Reads

Responses on failure

See CSRF for the double-submit pattern and executeRequest integration.

Bot detection middleware

isIPValid

Extracts and validates the client IP address from the request headers using net.isIP(). Does not make any network call. Runs as the first step in the global middleware chain.

Reads

Responses on failure

botDetectorMiddleware

Forwards the visitor fingerprint to the IAM service /check endpoint. Returns HTTP 403 when the visitor's bot score exceeds the configured ban threshold. When enableFireWallBans: true, calls banIp to block the IP at the operating system firewall level.

On the first request from a visitor, the middleware calls /check and sets __Host-dr_i_n, a signed host-only cookie. On every subsequent request where both __Host-dr_i_n and canary_id are present and the __Host-dr_i_n signature is valid, the middleware skips calling the IAM service entirely. If the signature verification fails, the request is rejected with 403 and code CANARY_TEMPERING.

Reads

Sets

Responses on failure

See Bot Detection for the full flow and the enableFireWallBans configuration.

OAuth middleware

OAuthTokensValidations

Validates the OAuth provider callback before the success handler runs. Reads the authorization code and state from the request (query string for GET, form body for POST), verifies the signed state cookie, and for OIDC providers verifies the ID token signature against the provider's JWKS endpoint, the nonce, azp, and at_hash claims, and that userinfo.sub matches the ID token subject. On success, sets event.context.provider, event.context.userData, and event.context.accessToken.

Called automatically by useOAuthRoutes as the first middleware in the /oauth/callback/:provider chain. Export it directly when building a custom OAuth callback route.

Reads

Sets

Responses on failure

See OAuth and OIDC for provider configuration and the full OIDC verification sequence.

Request validation middleware

limitBytes(maxBytes)

Factory function. Returns a middleware that reads the raw request body and throws HTTP 403 with code INVALID_CONTENT_TYPE if the byte length exceeds maxBytes. Pass 0 to reject any body entirely. Applied before JSON parsing, so oversized payloads cannot consume memory during deserialization.

Import

import { limitBytes } from 'auth-h3client'

Signature

function limitBytes(maxBytes: number): EventHandler

Usage

await limitBytes(1024)(event)  // Reject bodies over 1 KB
await limitBytes(0)(event)     // Reject any body

Responses on failure

contentType(expected)

Factory function. Returns a middleware that validates the Content-Type request header against the expected value. Throws HTTP 403 if the header is missing or does not match.

Import

import { contentType } from 'auth-h3client'

Signature

function contentType(expected: string): EventHandler

Usage

await contentType('application/json')(event)

Responses on failure

defineByteLimiterHandler(handler, limitBytesTo, method)

Higher-order wrapper that asserts the request method, reads the raw request body exactly once, rejects bodies larger than limitBytesTo, parses JSON into event.context.body, and then calls your handler. The API token management wrapper uses this parser so request-size checks happen before any action runs.

If the request body is empty, the wrapper leaves event.context.body undefined and continues. If Content-Length is present and already exceeds the limit, the request is rejected before the full body is processed.

Parameters

Sets

Responses on failure

export default defineByteLimiterHandler(async (event) => {
  const body = event.context.body
  return { ok: true, body }
}, 2048, 'POST')

Event handler wrappers

Wrappers are higher-order functions that accept your handler and return a new handler with enforcement built in. Import them from auth-h3client/v1 or auth-h3client/v2. When using the Nuxt module, they are auto-imported inside the server/ directory.

defineAuthenticatedEventHandler(handler)

The standard wrapper for protected routes. Runs hmacSignatureMiddleware, then ensureValidCredentials (token rotation), then calls getCachedUserData against the IAM service. Populates event.context.authorizedData with the verified session data. Throws HTTP 401 on failure. Returns HTTP 202 with mfaRequired when the session requires step-up verification.

Sets

Responses on failure

export default defineAuthenticatedEventHandler(async (event) => {
  const { userId, roles } = event.context.authorizedData
  return { userId, roles }
})

defineOptionalAuthenticationEvent(handler)

Attempts authentication using the same internal pipeline as defineAuthenticatedEventHandler. On success, populates event.context.authorizedData. On any auth failure other than a rate limit, sets event.context.authorizedData to undefined and continues to your handler as a guest. HTTP 429 responses are still propagated.

Sets

Responses on failure

export default defineOptionalAuthenticationEvent(async (event) => {
  const user = event.context.authorizedData // undefined for guests
  return user ? { content: 'private', userId: user.userId } : { content: 'public' }
})

defineVerifiedCsrfHandler(handler)

Calls verifyCsrfCookie before running the handler. Does not check authentication. Use this when you need CSRF protection on a route that is accessible to both guests and authenticated users.

Responses on failure

export default defineVerifiedCsrfHandler(async (event) => {
  const body = await readBody(event)
  return { ok: true }
})

defineAuthenticatedEventPostHandlers(handler)

Combines defineAuthenticatedEventHandler, defineVerifiedCsrfHandler, and assertMethod('POST') in that order. The correct choice for any state-changing endpoint that requires authentication.

Responses on failure

export default defineAuthenticatedEventPostHandlers(async (event) => {
  const { userId } = event.context.authorizedData
  await updateSettings(userId, await readBody(event))
  return { ok: true }
})

defineAuthenticatePublicApi(handler, userPrivilege)

Protects a route with API token verification. The wrapper reads X-API-KEY from the incoming request, forwards it to the IAM /api/public/verify endpoint together with the privilege floor defined by userPrivilege, and only then calls your handler.

On success, the wrapper stores the verified token metadata on event.context.apiVerification. On failure, it returns a normalized JSON response instead of throwing.

Reads

Sets

Responses on failure

export default defineAuthenticatePublicApi(async (event) => {
  const token = event.context.apiVerification
  return { ok: true, tokenId: token.tokenId, userId: token.userId }
}, 'demo')

defineApiManagementHandler(handler, allowedPrivilege, updateToNewPrivilege?)

Builds a complete authenticated POST pipeline for API token management routes. It wraps defineAuthenticatedEventPostHandlers(...) with defineByteLimiterHandler(..., 2000, 'POST'), validates event.context.params against the supported actions, and then proxies the request to the IAM API token management endpoints. This means the raw request body is size-checked and parsed into event.context.body before the action-specific logic runs.

Supported actions are new-token, revoke, metadata, rotate, ip-restriction-update, and privilege-update.

For every action except new-token, the wrapper first calls /api/manage/list-metadata to resolve the token's public_identifier. This means the client submits only tokenId, and the wrapper maps that token ID to publicIdentifier and name before it calls IAM.

allowedPrivilege controls the privilege that will be assigned to newly created tokens. updateToNewPrivilege is optional, but it must be provided if you want the privilege-update action to succeed.

Accepted request bodies

The wrapper schema requires prefix on new-token and validates ip-restriction-update with an optional ipv4 array. The client request body never supplies privilege or newPrivilege. Your application decides those values through the allowedPrivilege and updateToNewPrivilege arguments.

On new-token, IAM returns rawPublicId in addition to the raw key. The wrapper removes rawPublicId before it populates event.context.newApiToken.

Sets

Responses on failure

export default defineApiManagementHandler(async (event) => {
  const action = event.context.params?.action

  if (action === 'new-token') {
    return { ok: true, data: event.context.newApiToken }
  }

  if (action === 'metadata') {
    return { ok: true, data: event.context.extensiveMetadata }
  }

  return { ok: true }
}, 'demo', 'protected')

defineVerifiedMagicLinkGetHandler(handler)

Validates incoming magic link query parameters before running the handler. Enforces GET method, checks that the canary_id, session, and __Secure-a cookies are present, validates the query string against VerificationLinkSchema (visitor, token, random, reason), and calls the IAM service to verify the link. Populates event.context.link and event.context.reason on success.

Sets

Responses on failure

export default defineVerifiedMagicLinkGetHandler(async (event) => {
  const { reason } = event.context
  return { ok: true, reason }
})

defineMfaCodeVerifierHandler(handler)

Validates an MFA code submission after a magic link is verified. Enforces POST method, verifies the CSRF cookie, limits the request body to 8 MB, validates link query parameters against VerificationLinkSchema, reads event.context.body.code (a 7-digit numeric string), and sends the code to the IAM service for verification. On success, new tokens are issued and applied to the response cookies, and event.context.limitedMetaData is populated with the verified session metadata before your handler runs.

Reads

Sets

Responses on failure

export default defineMfaCodeVerifierHandler(async (event) => {
  // Code verified, new tokens already applied to the response
  return { ok: true }
})

defineDeduplicatedEventHandler(handler)

Wraps a handler with request-level deduplication using lockAsyncAction. Concurrent requests with the same session identity are coalesced so that only one execution runs at a time. Results are cached briefly to serve requests that arrive after the first completes.

The built-in login, logout, signup, password reset, and MFA handlers already use this wrapper internally.

export default defineDeduplicatedEventHandler(async (event) => {
  await processCheckout(event)
  return { ok: true }
})

Setup

defineAuthConfiguration(nitro, config) v1 only

One-call Nitro plugin setup function. Validates and freezes the configuration, registers httpLogger, mounts all four route registrars (useAuthRoutes, useOAuthRoutes, bounceRouter, magicLinksRouter with 'api' prefix) on nitro.router, and logs a startup confirmation. Use this inside a Nitro plugin to wire everything in a single call instead of registering each piece manually.

import { defineAuthConfiguration } from 'auth-h3client/v1'

export default defineNitroPlugin((nitro) => {
  defineAuthConfiguration(nitro, {
    server: { auth_location: 'https://iam.example.com' },
    // ...
  })
})

Parameters

Error utilities

throwHttpError(log, event, code, status, title, message)

Logs an error with structured context and throws an H3 error with the given status, title, and message. Use this inside custom handlers to produce consistent JSON error responses.

Import

import { throwHttpError } from 'auth-h3client'

Parameters

throwHttpError(log, event, 'FORBIDDEN', 403, 'Forbidden', 'Access denied')

notFoundHandler

Returns a 404 JSON response. Used as a fallback inside handlers that receive an invalid magic link or an unknown route.

Logging middleware

httpLogger()

Returns an H3 middleware function that logs every request and response as structured JSON using pino. Register it on your H3 app or Nitro instance during startup, or rely on the Nuxt module to register it automatically. See Logging for v1 and v2 registration examples.

Features

• Assigns a unique X-Request-Id header per request (or passes through an existing one)
• Selects log level by response status: info for 2xx/3xx, warn for 4xx, error for 5xx
• Skips logging for static asset paths

See Logging for configuring the logger level.

Wrapper quick reference