npm package: @loop8id/auth-nuxtjs
Description: Nuxt 3 authentication module for Loop8ID / L8P8 OpenID Connect
Latest version: 1.0.2

# @loop8id/auth-nuxtjs

Nuxt 3 authentication for [Loop8ID](https://auth.l8p8.com) OpenID Connect.

---

## Installation

```bash
npm install @loop8id/auth-nuxtjs @loop8id/auth-node-js
```

---

## Setup

### 1. Create `server/utils/auth.ts`

```ts
import { createNuxtAuth } from '@loop8id/auth-nuxtjs/server';

export const auth = createNuxtAuth({
  clientId:      process.env.L8P8_CLIENT_ID!,
  sessionSecret: process.env.SESSION_SECRET!,
  redirectUri:   `${process.env.NUXT_PUBLIC_APP_URL}/auth/callback`,
});
```

### 2. Create server route handlers

```ts
// server/routes/auth/login.get.ts
import { auth } from '~/server/utils/auth';
export default auth.loginHandler();

// server/routes/auth/callback.get.ts
import { auth } from '~/server/utils/auth';
export default auth.callbackHandler();

// server/routes/auth/logout.get.ts
import { auth } from '~/server/utils/auth';
export default auth.logoutHandler();

// server/api/auth/session.get.ts   ← used by the client composable
import { auth } from '~/server/utils/auth';
export default auth.sessionHandler();
```

### 3. Add server middleware (optional route protection)

```ts
// server/middleware/auth.ts
import { createLoop8ServerMiddleware } from '@loop8id/auth-nuxtjs/server';

export default createLoop8ServerMiddleware({
  sessionSecret:  process.env.SESSION_SECRET!,
  protectedPaths: ['/dashboard', '/settings'],
});
```

### 4. Add the client plugin

```ts
// plugins/loop8auth.client.ts
export { default } from '@loop8id/auth-nuxtjs/plugin';
```

---

## Usage

### In a Server Route / API handler

```ts
// server/api/me.get.ts
import { auth } from '~/server/utils/auth';
import { defineEventHandler } from 'h3';

export default defineEventHandler(async (event) => {
  const user = await auth.requireUser(event); // throws 401 if unauthenticated
  return { user };
});
```

### In a .vue component

```vue
<script setup lang="ts">
import { useLoop8Auth } from '@loop8id/auth-nuxtjs/composables';

const { user, isAuthenticated, isLoading, login, logout } = useLoop8Auth();
</script>

<template>
  <div v-if="isLoading">Loading…</div>
  <div v-else-if="isAuthenticated">
    Hello, {{ user?.name }}
    <button @click="logout()">Logout</button>
  </div>
  <div v-else>
    <button @click="login()">Login</button>
  </div>
</template>
```

### Protect a page client-side

```vue
<!-- pages/dashboard.vue -->
<script setup lang="ts">
import { useRequireAuth } from '@loop8id/auth-nuxtjs/composables';
const user = await useRequireAuth(); // redirects to login if unauthenticated
</script>
```

---

## API — Server

| Export | Description |
|---|---|
| `createNuxtAuth(options)` | Creates auth helper with `{ client, getUser, getSession, isAuthenticated, requireUser, loginHandler, callbackHandler, logoutHandler, sessionHandler }` |
| `createLoop8ServerMiddleware(options)` | Server middleware for route protection |

## API — Composables

| Export | Description |
|---|---|
| `useLoop8Auth(options?)` | Returns `{ user, isAuthenticated, isLoading, login, logout, refresh }` |
| `useLoop8User()` | Returns just the user ref |
| `useRequireAuth(options?)` | Redirects to login if unauthenticated |

---

## Environment Variables

```env
L8P8_CLIENT_ID=your-client-id
SESSION_SECRET=at-least-32-random-characters
NUXT_PUBLIC_APP_URL=http://localhost:3000
```

---

## License

MIT © Loop8ID