Auth H3 Client

Configuration

Complete reference for the Configuration object passed to the configuration() function, covering server connection, HMAC, SSL, storage, sanitization, image upload, OAuth providers, and all top-level options.

The Configuration object is validated against a Zod schema at startup. Passing invalid values throws immediately with a descriptive error. All fields are required unless marked optional.

Pass the configuration object to configuration(...) exactly once when your H3, Nitro, or Nuxt application starts. You can spread one of the shipped templates and override only the fields you need. See Getting Started for setup examples.

`server`

Connection and security settings for the upstream IAM service.

`server.auth_location`

serverOrDNS

string required

Hostname, DNS name, or IP address of the IAM service. Do not include the protocol or port.

port

number required

Port the IAM service listens on.

`server.hmac`

HMAC request signing. A discriminated union on enableHmac.

enableHmac

boolean required

When true, every outbound request to the IAM service is signed with HMAC-SHA256. When false, requests are sent without authentication headers. The clientId and sharedSecret fields are required when enableHmac is true.

clientId

string

Stable identifier for this gateway instance, sent as X-Client-Id. Required when enableHmac is true. Must match the value registered on the IAM service.

sharedSecret

string

HMAC-SHA256 key. Required when enableHmac is true. Must be identical in both the module configuration and the IAM service configuration. Should be at least 32 bytes of random data.

`server.ssl`

Mutual TLS configuration. A discriminated union on enableSSL.

enableSSL

boolean required

When true, all outbound connections use the configured certificate bundle. When false, plain HTTP is used.

mainDirPath

string

Absolute path to the directory containing the certificate files. Required when enableSSL is true.

rootCertsPath

string

Filename of the CA certificate relative to mainDirPath. Required when enableSSL is true.

clientCertsPath

string

Filename of the client certificate relative to mainDirPath. Required when enableSSL is true.

clientKeyPath

string

Filename of the client private key relative to mainDirPath. Required when enableSSL is true.

`server.cryptoCookiesSecret`

cryptoCookiesSecret

string required

HMAC key used to sign cookies, including the CSRF cookie and OAuth state cookies. Must be stable across restarts. Changing this value invalidates all existing signed cookies. Should be at least 32 bytes of random data.

`htmlSanitizer`

Controls the multi-pass HTML sanitization pipeline used by sanitizeInputString and makeSafeString.

IrritationCount

number

Maximum number of URI-decode and entity-decode loop iterations per input string. Higher values catch deeply nested encoding chains but increase CPU cost. Inputs that do not stabilize within this many iterations are rejected and returned as empty strings. Default to 50.

maxAllowedInputLength

number

Maximum input string length in characters before any processing. Inputs exceeding this limit are rejected immediately. Default to 50000.

`imageUploader`

Controls the image validation and conversion pipeline used by validateImage.

allowedBytes

number

Maximum buffer size in bytes. Buffers larger than this value are rejected before any processing. Default to 5000000 (5 MB).

allowedMimes

string[]

MIME types accepted by validateImage. Validated against the actual detected type from the file magic bytes. Default to ["image/png", "image/jpeg", "image/webp"].

allowedExtensions

string[]

File extensions accepted by validateImage. Validated against the extension detected from magic bytes. Default to ["png", "webp", "jpeg", "jpg"].

key

(input: any) => string

Optional function that returns a storage path prefix. The result is combined with a sanitized filename and .webp extension to form the final storage key. When omitted, a UUID is used as the prefix.

`uStorage`

Unstorage configuration for session caching. The storage instance is used by getCachedUserData to cache IAM responses.

storage

Storage required

A valid unstorageStorage instance. The module validates that getItem and setItem are present. Any unstorage driver works: memory, Redis, filesystem, Cloudflare KV, and so on.

cacheOptions.successTtl

number

TTL in seconds for successful auth responses cached by getCachedUserData. Default to 2592000 (30 days). Increasing this reduces load on the IAM service but delays detection of revoked sessions.

cacheOptions.rateLimitTtl

number

TTL in seconds for rate-limit error responses. Prevents hammering the IAM service when a visitor is rate-limited. Default to 10 seconds.

`onSuccessRedirect`

onSuccessRedirect

string (URL) required

Full URL or path to redirect the user to after a successful login or OAuth callback. Must be a valid URL string.

`OAuthProviders`

An optional array of OAuth and OIDC provider configurations. See OAuth and OIDC for the full field reference for each provider kind.

OAuthProviders: [
  {
    kind: 'oidc',
    name: 'google',
    issuer: 'https://accounts.google.com',
    // ...
  },
  {
    kind: 'oauth',
    name: 'github',
    authorizationEndpoint: 'https://github.com/login/oauth/authorize',
    // ...
  }
]

`magicLinkRedirectPath`

magicLinkRedirectPath

string

The path in your frontend application where users land after the bounce handler processes a magic link. The bounce handler redirects to this path with the link parameters as query params. A page at this path should call useMagicLink to complete the flow. Default to '/auth/verify'.

`magicLinkBouncePath`

magicLinkBouncePath

string

The path registered by bounceRouter for handling incoming magic links. The IAM service generates links that land here first. The bounce handler parses the parameters and redirects to magicLinkRedirectPath. Default to '/auth/bounce'.

`enableFireWallBans`

enableFireWallBans

boolean required

When true, botDetectorMiddleware and restartPasswordHandler call banIp to add a UFW firewall rule for flagged IPs. Requires a Linux environment with ufw installed and passwordless sudo for the Node.js process. Set to false on serverless or edge environments.

`logLevel`

logLevel

"debug" | "info" | "warn" | "error" | "fatal" required

Minimum severity level emitted by the pino logger. Use info in production. Use debug in development to see the full authentication pipeline output.

mTLS Configuration

API Reference