nuxt-auth-utils

Nuxt Auth Utils is compatible with Nitro WebSockets. To protect WebSocket connections, use requireUserSession(request) within the upgrade handler to verify authentication before allowing the connection to upgrade. You can then use requireUserSession(peer) within the open handler to access the user session.

// server/routes/ws.ts
export default defineWebSocketHandler({
  async upgrade(request) {
    // Make sure the user is authenticated before upgrading the WebSocket connection
    await requireUserSession(request)
  },
  async open(peer) {
    const { user } = await requireUserSession(peer)

    peer.send(`Hello, ${user.name}!`)
  },
  message(peer, message) {
    peer.send(`Echo: ${message}`)
  },
})

To add authentication to your Nuxt project, use the nuxi module add command.

Note: This module requires a Nuxt server running (it uses server API routes) and is not compatible with nuxt generate. However, you can still use Hybrid Rendering to pre-render pages or disable SSR.

npx nuxi@latest module add auth-utils

When performing Server-Side Rendering (SSR), you must ensure authenticated requests include credentials. If you are using useAsyncData, use useRequestFetch() instead of a standard $fetch. If you are using useFetch, it will automatically use useRequestFetch during SSR.

<script setup lang="ts">
// When using useAsyncData
const { data } = await useAsyncData('team', () => useRequestFetch()('/api/protected-endpoint'))

// useFetch will automatically use useRequestFetch during SSR
const { data } = await useFetch('/api/protected-endpoint')
</script>

To use OAuth with the AT Protocol (e.g., Bluesky), follow these steps:

1. Install the required peer dependencies:

   npx nypm i @atproto/oauth-client-node @atproto/api

2. Enable it in your nuxt.config.ts:

   export default defineNuxtConfig({
     auth: {
       atproto: true
     }
   })

// nuxt.config.ts
export default defineNuxtConfig({
  auth: {
    atproto: true
  }
})

In hybrid rendering scenarios (like prerendering or caching via routeRules), the user session cannot be accessed during prerendering because it is stored in a secure cookie. You can control how the session is loaded using the loadStrategy option in nuxt.config.ts:

• client-only: The session is fetched only on the client-side after hydration. You can still manually fetch it on the server using useUserSession().fetch().
• none: Disables automatic session loading. You must manually fetch the session using useUserSession().fetch().

Note: If caching routes with routeRules, ensure you are using Nitro >= 2.9.7 to support client-side session fetching.

Nuxt Auth Utils requires a NUXT_SESSION_PASSWORD environment variable in your .env file to secure and seal cookie sessions. The password must be at least 32 characters long.

If you are running Nuxt in development and haven't set this variable, Nuxt Auth Utils will generate one for you automatically.

# .env
NUXT_SESSION_PASSWORD=password-with-at-least-32-characters

You can configure session behavior by overriding runtimeConfig.session in your nuxt.config.ts. This leverages h3 useSession options.

Default values:

• name: 'nuxt-session'
• password: process.env.NUXT_SESSION_PASSWORD
• cookie.sameSite: 'lax'

export default defineNuxtConfig({
  modules: ['nuxt-auth-utils'],
  runtimeConfig: {
    session: {
      maxAge: 60 * 60 * 24 * 7 // 1 week
    }
  }
})

You can use sessionHooks within a Nitro plugin to extend session data during fetch or perform actions when a session is cleared.

• sessionHooks.hook('fetch', ...): Triggered when a session is fetched (e.g., during SSR or via useUserSession().fetch()). Use this to augment the session with database data.
• sessionHooks.hook('clear', ...): Triggered when a session is cleared (e.g., via clearUserSession(event) or useUserSession().clear()).

// server/plugins/session.ts
export default defineNitroPlugin(() => {
  sessionHooks.hook('fetch', async (session, event) => {
    // Extend User Session by calling your database
  })

  sessionHooks.hook('clear', async (session, event) => {
    // Log that user logged out
  })
})

When calling setUserSession or replaceUserSession on the server, you can pass a third argument to override session configuration (like maxAge) for that specific session.

await setUserSession(event, { ... } , {
  maxAge: 60 * 60 * 24 * 7 // 1 week
})