Nuxt Module

The @riavzon/auth-h3client module handles authentication for Nuxt applications. It provides a module that auto-imports client-side composables and server-side utilities, plus optional security middleware.

Requirements

• Node.js 22 or later
• Nuxt 3 and later or a Nitro/H3 application
• A running IAM service reachable from your server

Installation

pnpm add @riavzon/auth-h3client

yarn add @riavzon/auth-h3client

npm install @riavzon/auth-h3client

bun add @riavzon/auth-h3client

Nuxt module setup

Register the module in nuxt.config.ts. This enables the auto-import of all server utilities and client composables, and optionally registers the global security middleware.

export default defineNuxtConfig({
  modules: ['auth-h3client/module'],
  authH3Client: {
    enableMiddleware: true,
    authStatusUrl: '/api/auth/users/authStatus',
    registerApiRoute: {
      path: '/api/auth/api-tokens'
    }
  }
})

Module options

Plugin configuration

The module does not configure the library automatically because the configuration includes non-serializable values such as storage instances and callbacks. You must create a Nitro plugin that calls defineAuthConfiguration.

defineAuthConfiguration initializes the library, starts the HTTP request logger, and registers all authentication routes on the Nitro router in one call. This is the recommended setup for Nuxt applications.

Using a config template

The module ships two config templates that read from environment variables, giving you a working baseline with no manual wiring:

Create a Nitro plugin and spread the template as the base:

import { defineNitroPlugin } from 'nitropack/runtime'
import { useStorage } from 'nitropack/runtime/storage'
import { configDefaults } from 'auth-h3client/server/templates'
import { defineAuthConfiguration } from 'auth-h3client/v1'

export default defineNitroPlugin((nitroApp) => {
  defineAuthConfiguration(nitroApp, {
    ...configDefaults,
    onSuccessRedirect: '/dashboard',
    uStorage: {
      storage: useStorage('cache'),
      cacheOptions: {
        successTtl: 60 * 60 * 24 * 30,
        rateLimitTtl: 10
      }
    }
  })
})

configDefaults reads the following environment variables:

When using configDefaultsWithOAuth, add the following variables:

Manual configuration

If you need full control over every option, pass the full configuration object directly to defineAuthConfiguration without a template. See the Configuration reference for a description of every field.

import { defineNitroPlugin } from 'nitropack/runtime'
import { useStorage } from 'nitropack/runtime/storage'
import { configDefaults } from 'auth-h3client/server/templates'
import { defineAuthConfiguration } from 'auth-h3client/v1'

export default defineNitroPlugin((nitroApp) => {
  defineAuthConfiguration(nitroApp, {
    ...configDefaults,
    // Override individual fields as needed
    onSuccessRedirect: '/dashboard',
    enableFireWallBans: false,
    logLevel: 'info',
    htmlSanitizer: {
      IrritationCount: 50,
      maxAllowedInputLength: 50000
    },
    imageUploader: {
      allowedBytes: 5_000_000,
      allowedMimes: ['image/png', 'image/jpeg', 'image/webp'],
      allowedExtensions: ['png', 'webp', 'jpeg', 'jpg']
    },
    uStorage: {
      storage: useStorage('cache'),
      cacheOptions: {
        successTtl: 60 * 60 * 24 * 30,
        rateLimitTtl: 10
      }
    }
  })
})

See the Configuration reference for a description of every field.

What the module registers

Global middleware

When enableMiddleware is true, the module registers a single server middleware that runs on every request before your route handlers. It skips HEAD requests, the /api/health path, Nuxt internal paths, and requests forwarded from localhost.

For all other requests it runs three operations in order:

1. IP validation: extracts and validates the client IP and visitor fingerprint
2. Bot detection: forwards the fingerprint to the IAM service check endpoint and returns 403 if the visitor is flagged
3. CSRF cookie: mints a signed __Host-csrf cookie if one is not already present

Auth status route

The module registers a GET handler at authStatusUrl (default /api/auth/users/authStatus). This route proxies to the IAM service and returns the current session state. The useAuthData composable fetches this route during SSR and on the client.

Optional API token list route

When registerApiRoute is set, the module registers a GET handler at registerApiRoute.path using getApiListsController. This route returns the authenticated user's API token inventory and strips each token's public_identifier before the response reaches the browser.

Authentication routes

defineAuthConfiguration registers the following routes on the Nitro router:

For the full middleware chain and request/response details for each route, see the Routes Reference.

Auto-imported server utilities

All server utilities from auth-h3client/v1 are auto-imported in your server/ directory. You do not need to import them manually inside any server route or plugin.

Auto-imported client composables

The following composables are auto-imported in your Vue components and pages:

See Client-Side for full details.

Verify the setup

Start your development server and make a request to the auth status endpoint. With no active session the response should be:

curl http://localhost:3000/api/auth/users/authStatus

{
  "authorized": false
}

A __Host-csrf cookie should also be present on the response. If the IAM service is unreachable, the auth status handler returns { "authorized": false } rather than erroring, so check the server logs if you expect a different result.

Create a protected endpoint

Try creating a simple endpoint and querying it in your frontend:

// This will only return successful response in the user its authenticate
export default defineAuthenticatedEventHandler(async (event) => { 
  const user = event.context.authorizedData; 
  return user;
})

<script setup lang="ts">
import { executeRequest } from '@riavzon/auth-h3client/client';

const result = await executeRequest<Data>(
  '/api/protected',
  'GET',
  {},
  {},
  {},
  {
    headers: useRequestHeaders(),
    event: useRequestEvent(),
    fetcher: useRequestFetch(),
  },
)
const data = result.data
</script>

<template> 
  <div> {{ data }} </div>
</template>