https://github.com/peterbud/nuxt-aegis

Nuxt module for authentication with JWT token generation and session management.
https://github.com/peterbud/nuxt-aegis

authentication dx impersonation jwt nuxt nuxt-module oauth vue

Last synced: about 2 months ago
JSON representation

Nuxt module for authentication with JWT token generation and session management.

Host: GitHub
URL: https://github.com/peterbud/nuxt-aegis
Owner: peterbud
Created: 2025-10-07T14:28:46.000Z (8 months ago)
Default Branch: main
Last Pushed: 2026-02-07T12:01:22.000Z (4 months ago)
Last Synced: 2026-02-07T20:10:06.630Z (4 months ago)
Topics: authentication, dx, impersonation, jwt, nuxt, nuxt-module, oauth, vue
Language: TypeScript
Homepage: https://peterbud.github.io/nuxt-aegis/
Size: 1.05 MB
Stars: 0
Watchers: 0
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Security: docs/security/best-practices.md

Awesome Lists containing this project

README

          # Nuxt Aegis

[![Build](https://github.com/peterbud/nuxt-aegis/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/peterbud/nuxt-aegis/actions/workflows/ci.yml)

[![npm version][npm-version-src]][npm-version-href]

[![npm downloads][npm-downloads-src]][npm-downloads-href]

[![License][license-src]][license-href]

[![Nuxt][nuxt-src]][nuxt-href]

**OAuth-based authentication with JWT token management for Nuxt 3/4**

> [!WARNING]

> **Experimental Module**: Nuxt Aegis is currently in active development and should be considered as work in progress. It is **not recommended for production use** at this time. APIs and features may change without notice.

Nuxt Aegis is a a Nuxt module that orchestrates the authentication flow between external identity providers (Google, GitHub, Auth0, etc.) and your application. It handles the complexity of OAuth 2.0, JWT token generation, and automatic token refresh, letting you focus on your application logic.

## Why Nuxt Aegis?

Unlike cookie-based solutions that lock your API to the browser, Nuxt Aegis uses **industry-standard JWT bearer tokens**. This means your API is ready for:

- 📱 Mobile applications

- 🖥️ CLI tools

- 🌐 Third-party integrations

- ⚡ Universal access across platforms

### How It Works

1. **Authentication (Identity) Provider** (e.g., Google) authenticates the user.

2. **Nuxt Aegis** verifies the identity retrieves the user information, and issues it's own application specific JWT.

3. **Your App** receives the JWT token and uses it for authorization.

You get full control over user data persistence while Aegis handles the security lifecycle.

## ✨ Key Features

- 🔐 **OAuth 2.0 & OpenID Connect** - Built-in support for Google, GitHub, Auth0, and Microsoft Entra ID.

- 🔑 **Password Authentication** - Secure username/password flow with magic link verification.

- 🎫 **JWT Management** - Automatic token generation, validation, and signing (HS256/RS256).

- 🔄 **Auto-Refresh** - Seamless background token refresh with secure HTTP-only cookies.

- 🛡️ **Route Protection** - Declarative middleware for both server API routes and client-side pages.

- 🧪 **Mock Provider** - Built-in testing provider to simulate auth flows without external services.

- 🎨 **Custom Claims** - Easily inject application-specific data (roles, permissions or similar) into tokens.

- 🎭 **Impersonation** - Support for user impersonation with full audit logging

- ⚙️ **SSR Friendly** - Works seamlessly with Nuxt's server-side rendering.

- 🥽 **Type Safe** - Written in TypeScript with full type definitions for a great developer experience.

## 🚀 Quick Start

### 1. Install

```bash

npx nuxi module add @peterbud/nuxt-aegis

```

### 2. Configure

Add the module and provider configuration to `nuxt.config.ts`:

```typescript

export default defineNuxtConfig({

  modules: ['@peterbud/nuxt-aegis'],

  

  nuxtAegis: {

    token: {

      secret: process.env.NUXT_AEGIS_TOKEN_SECRET!,

    },

    providers: {

      google: {

        clientId: process.env.GOOGLE_CLIENT_ID!,

        clientSecret: process.env.GOOGLE_CLIENT_SECRET!,

      },

    },

  },

})

```

### 3. Create Auth Route

Create a server route handler to initialize the provider:

```typescript

// server/routes/auth/google.get.ts

export default defineOAuthGoogleEventHandler({

  onUserInfo: (providerUserInfo, _tokens, _event) => {

    return {

      id: providerUserInfo.sub as string,

      email: providerUserInfo.email,

      name: providerUserInfo.name,

    }

  },

})

```

### 4. Use in Components

Access authentication state anywhere in your app:

```vue

const { user, isLoggedIn, login, logout } = useAuth()

  


    Welcome, {{ user?.name }}!

    Logout

  

  

    Login with Google

  

```

## 📖 Documentation

Ready to dive deeper? Check out the full documentation:

- **[Getting Started](https://peterbud.github.io/nuxt-aegis/getting-started/installation)** - Installation and setup guides.

- **[Architecture](https://peterbud.github.io/nuxt-aegis/architecture/)** - Overview of the system architecture.

- **[Providers](https://peterbud.github.io/nuxt-aegis/providers/)** - Configure Google, GitHub, Auth0, Password, and Mock providers.

- **[Configuration](https://peterbud.github.io/nuxt-aegis/configuration/)** - Detailed configuration options.

- **[Route Protection](https://peterbud.github.io/nuxt-aegis/guides/route-protection)** - Learn how to protect your pages and API routes.

- **[Custom Claims](https://peterbud.github.io/nuxt-aegis/guides/custom-claims)** - Add custom data to your JWTs.

- **[API Reference](https://peterbud.github.io/nuxt-aegis/api/)** - Detailed API documentation.

## Contributing

Contributions are welcome! Please see the [Requirements Specification](/specs/requirements.md) for detailed technical requirements.

Local development

```bash

# Install dependencies

pnpm install

# Start development server

pnpm dev

# Run tests

pnpm test

# Lint & type check

pnpm lint

```

If you want to report a bug, please make sure you have a minimal reproduction of the issue. You can use the [minimal example](https://stackblitz.com/github/peterbud/nuxt-aegis/tree/main/examples/minimal?title=Nuxt-Aegis%20Minimal%20Example) to create a reproduction.

## License

[MIT License](./LICENSE)

## Acknowledgments

- Built with [Nuxt Module Builder](https://github.com/nuxt/module-builder)

- JWT handling powered by [jose](https://github.com/panva/jose)

- Heavily inspired by the [nuxt-auth-utils](https://github.com/atinux/nuxt-auth-utils) and  Nuxt community

Made with ❤️ for the Nuxt community

[npm-version-src]: https://img.shields.io/npm/v/nuxt-aegis/latest.svg\?style\=flat\&colorA\=020420\&colorB\=00DC82

[npm-version-href]: https://npmjs.com/package/@peterbud/nuxt-aegis

[npm-downloads-src]: https://img.shields.io/npm/dm/nuxt-aegis.svg\?style\=flat\&colorA\=020420\&colorB\=00DC82

[npm-downloads-href]: https://npm.chart.dev/@peterbud/nuxt-aegis

[license-src]: https://img.shields.io/npm/l/nuxt-aegis.svg\?style\=flat\&colorA\=020420\&colorB\=00DC82

[license-href]: https://npmjs.com/package/@peterbud/nuxt-aegis

[nuxt-src]: https://img.shields.io/badge/Nuxt-020420\?logo\=nuxt.js

[nuxt-href]: https://nuxt.com

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/peterbud/nuxt-aegis

Awesome Lists containing this project

README

Welcome, {{ user?.name }}!