nuxt-auth-utils-skilld

name	nuxt-auth-utils-skilld
description	ALWAYS use when writing code importing "nuxt-auth-utils". Consult for debugging, best practices, or modifying nuxt-auth-utils, nuxt auth utils.
metadata	{"version":"0.5.28","generated_by":"Claude Code · Haiku 4.5","generated_at":"2026-03-03T00:00:00.000Z"}

atinux/nuxt-auth-utils nuxt-auth-utils

Version: 0.5.28 (Feb 2026) Deps: @adonisjs/hash@^9.1.1, @nuxt/kit@^4.3.1, defu@^6.1.4, h3@^1.15.4, hookable@^6.0.1, jose@^6.1.3, ofetch@^1.5.1, openid-client@^6.8.2, pathe@^2.0.3, scule@^1.3.0, uncrypto@^0.1.3 Tags: latest: 0.5.29 (Feb 2026)

References: package.json — exports, entry points • README — setup, basic usage • GitHub Issues — bugs, workarounds, edge cases • Releases — changelog, breaking changes, new APIs

Search

Use skilld search instead of grepping .skilld/ directories — hybrid semantic + keyword search across all indexed docs, issues, and releases. If skilld is unavailable, use npx -y skilld search.

skilld search "query" -p nuxt-auth-utils
skilld search "issues:error handling" -p nuxt-auth-utils
skilld search "releases:deprecated" -p nuxt-auth-utils

Filters: docs:, issues:, releases: prefix narrows by source type.

API Changes

This section documents version-specific API changes — prioritize recent major/minor releases.

• BREAKING: oicd renamed to oidc in OAuthProvider type — v0.5.28 corrected typo in provider type name source

• BREAKING: OIDC provider requires PKCE and nonce — v0.5.28 made these mandatory per OAuth specs (previously optional) source

• NEW: aaguid exposed on WebAuthn credentials — v0.5.27 added aaguid property to credentials in onSuccess callback, use to identify authenticator type with community AAGUIDS list source

• NEW: OpenID Connect (OIDC) provider — v0.5.27 added generic OIDC provider via defineOAuthOidcEventHandler, supports .well-known/openid-configuration auto-discovery source

• NEW: loadStrategy: 'none' option — v0.5.26 added ability to completely disable session fetching during SSR (added alongside existing 'client-only' option from v0.5.24) source

• NEW: passwordNeedsRehash() utility — v0.5.26 added server utility to check if password hash needs rehashing when scrypt settings change, call during login flow to trigger re-hash source

• NEW: loadStrategy: 'client-only' option — v0.5.24 added option to fetch session only client-side (not during SSR), useful with prerendered/cached routes source

• NEW: openInPopup(route, { width?, height? }) method on useUserSession — v0.5.11 added popup window OAuth flow with auto-close on success, pass optional size object to control window dimensions source

• NEW: WebSocket authentication support — v0.5.9 added requireUserSession() function for use in WebSocket upgrade handler to authenticate before connection, requires Nitro >= 2.9.7 source

• NEW: Session ID auto-generation — v0.5.12 added generated id field on session object for session tracking source

• BREAKING: WebAuthn dependency update — v0.5.0 updated simplewebauthn to v11, breaking changes in API (see simplewebauthn v11 migration) source

• BREAKING: useWebAuthn composable allowCredentials fix — v0.5.1 changed how allowCredentials and excludeCredentials are processed in useWebAuthn, previously had bugs with options handling source

• NEW: WebAuthn (passkey) support — v0.4.0 added defineWebAuthnRegisterEventHandler, defineWebAuthnAuthenticateEventHandler, useWebAuthn() composable, storeChallenge/getChallenge hooks for challenge management source

• NEW: hashPassword() and verifyPassword() utilities — v0.4.0 added server-side password hashing with scrypt, use in login/register flows for secure password storage source

• BREAKING: OAuth handler renaming — v0.4.0 renamed oauth<Provider>EventHandler to defineOAuth<Provider>EventHandler (e.g., defineOAuthGitHubEventHandler) source

Also changed: OIDC X provider PKCE flow fixed · Shopify Customer Account API provider · Bluesky (AT Protocol) provider · generated session ID available on session · multiple OAuth providers (Okta, Ory, Kick, Gitea, etc.)

nuxt-auth-utils Best Practices

Best Practices

• Refresh the Vue composable after server-side session updates — when calling setUserSession() from server routes or hooks, use useUserSession().fetch() on client to ensure the session state stays synchronized source

• Use loadStrategy to control session loading behavior — choose 'client-only' for hybrid-rendered apps, 'none' to disable auto-loading, or 'server-first' (default) for traditional SSR source

• Extend UserSession type via module augmentation in a declaration file — create auth.d.ts and augment the #auth-utils module to get full type safety for custom session fields source

• Access WebAuthn credential AAGUID in onSuccess to decorate passkeys — use credential.aaguid to look up authenticator metadata from the passkey-authenticator-aaguids list source

• Implement challenge-based WebAuthn flow with storeChallenge and getChallenge — prevents replay attacks by storing single-use challenges in KV store and removing after validation source

• Store sensitive data (tokens, API keys) in the secure field, not user — the secure field is server-only and never sent to the client, while user data is encrypted but queryable source

• OIDC authentication requires both PKCE and nonce parameters — these are mandatory per OAuth spec and cannot be disabled; the provider's discovery endpoint must support them source

• Session data is limited to ~4KB due to cookie size constraints — store only essential identifiers and tokens; use database lookups in the 'fetch' hook to augment session with full user data source

• Implement password hash rotation during login — call passwordNeedsRehash() to detect outdated hashes and re-hash with new cost parameters without breaking existing sessions source

• Use sessionHooks for runtime session augmentation — hook into 'fetch' to enrich session data from your database, and 'clear' to log logout events source