Winx Auth

3.2.1 verified Sat May 09 auth: no javascript

Nuxt 3 authentication module that provides login, logout, CSRF protection, token management, and global authentication middleware. Version 3.2.1 is the current stable release. It integrates with Nuxt 3's composition API via the `useAuth` composable and supports secure cookie-based tokens with configurable CSRF protection. Key differentiators include built-in CSRF encryption, global middleware options, and automatic token/cookie management with production-like security defaults. Released under the MIT license.

Common errors

error Cannot read properties of undefined (reading 'login') ↓

cause useAuth() returned undefined because it was called outside Nuxt's component context (e.g., in a plain .ts file).

fix

Move the call into a Vue component's <script setup> block or use #imports auto-import.

error Module 'winx-auth' not found ↓

cause Package not installed or not added to modules array correctly.

fix

Run 'npm install winx-auth' (or pnpm/yarn) and ensure nuxt.config.ts has modules: ['winx-auth'].

error Auth middleware redirect loop ↓

cause Global app middleware redirects to login page which itself requires auth, causing infinite loop.

fix

Set enableGlobalAppMiddleware: false or exclude the login route in middleware options using globalMiddlewareOptions.allow404WithoutAuth or custom middleware.

error Cookie with name 'token.winx' not set ↓

cause Login API endpoint returned a token but cookie options (httpOnly, secure) may be misconfigured or the token name changed.

fix

Check that token.name matches what the API expects, and that cookie options are consistent (httpOnly/secure).

error CSRF token mismatch ↓

cause The CSRF cookie and header values do not match, often due to misconfigured encryptSecret or different encryptAlgorithm.

fix

Ensure encryptSecret in nuxt.config matches the secret used to generate the CSRF token on the server side.

Warnings

gotcha useAuth() must be called inside a component's setup function or within Nuxt's auto-import context. Using it outside setup (e.g., in a plain function) may result in errors. ↓

fix Ensure useAuth() is called within <script setup> or directly in a Vue component's setup() function.

gotcha The global middleware enforces authentication on all routes by default. Public pages will be blocked unless configured correctly. ↓

fix Set enableGlobalAppMiddleware: false in auth config, or use allow404WithoutAuth: true to allow 404 pages.

deprecated The 'auth-module' package name was used in older versions. Do not confuse 'winx-auth' with 'auth-module'. ↓

fix Use pnpm add winx-auth (version 3.x) instead of the old package.

gotcha Cookie options httpOnly and secure default to true in production, which may cause issues if testing over HTTP locally. ↓

fix Set secure: false in development or use HTTPS locally (e.g., via mkcert).

gotcha The CSRF encryptSecret should be a secure, randomly generated string. Using a static or weak secret compromises security. ↓

fix Use randomBytes(22).toString('base64') (as shown in default config) or a secure environment variable.

Install

npm install winx-auth

yarn add winx-auth

pnpm add winx-auth

Imports

useAuth
wrong
```
import { useAuth } from 'winx-auth'
```
correct
```
const { login, logout } = useAuth()
```
useAuth is auto-imported by Nuxt via '#imports'; no manual import needed from the package.
auth module
wrong
```
modules: ['winx-auth-module']
```
correct
```
modules: ['winx-auth']
```
Module name is 'winx-auth' as a string in the modules array, not 'auth' or 'winx-auth-module'.
auth config
wrong
```
winxAuth: { ... }
```
correct
```
auth: { enabled: true }
```
Configuration is placed under the 'auth' key in nuxt.config.ts, not under a custom key.
$auth
wrong
```
$auth.signIn({ code })
```
correct
```
$auth.login({ code })
```
The global $auth helper provides login/logout methods; method names are 'login' and 'logout'.

Quickstart

Demonstrates basic setup with Nuxt config and a login page using the useAuth composable.

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['winx-auth'],
  auth: {
    apiUrl: process.env.API_URL || 'http://localhost:8080',
    enableGlobalAppMiddleware: true,
  },
});

// pages/login.vue
<script setup lang="ts">
const code = ref('');
const { login } = useAuth();

const handleLogin = async () => {
  await login({ code: code.value });
};
</script>

<template>
  <input v-model="code" type="text" />
  <button @click="handleLogin">Login</button>
</template>