winx-auth

library3.2.1jsnpmunverified

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.

auth-security web-framework

npm install winx-auth

github ↗package ↗

INSTALL

IMPORT

SIG · WINX-AUTH

winx-auth

auth-securityjavascriptv3.2.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

useAuth

✓ const { login, logout } = useAuth()

✗ import { useAuth } from 'winx-auth'

useAuth is auto-imported by Nuxt via '#imports'; no manual import needed from the package.

auth module

✓ modules: ['winx-auth']

✗ modules: ['winx-auth-module']

Module name is 'winx-auth' as a string in the modules array, not 'auth' or 'winx-auth-module'.

auth config

✓ auth: { enabled: true }

✗ winxAuth: { ... }

Configuration is placed under the 'auth' key in nuxt.config.ts, not under a custom key.

$auth

✓ $auth.login({ code })

✗ $auth.signIn({ code })

The global $auth helper provides login/logout methods; method names are 'login' and 'logout'.

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>

Debug

Known issues

gotchauseAuth() 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.

affects: >=3.0.0

gotchaThe 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.

affects: >=3.0.0

deprecatedThe '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.

affects: <3.0.0

gotchaCookie 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).

affects: >=3.0.0

gotchaThe 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.

affects: >=3.0.0

Errors

Common errors & fixes

Cannot read properties of undefined (reading 'login')

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.

Module 'winx-auth' not found

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'].

Auth middleware redirect loop

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.

Cookie with name 'token.winx' not set

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).

CSRF token mismatch

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.

Upgrade

Version history

3.2.1latest on npm

Audit

Dependencies

nuxtrequiredCore dependency required as the module is built for Nuxt 3

Agent activity

40 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/Winx-Universe/winx-auth ↗

packagehttps://www.npmjs.com/package/winx-auth ↗