# awesome-lang-auth

> awesome-lang-auth is self-hosted authentication for Node.js, Go, AWS Lambda, Python, Rust and Dart, with Angular, React and Flutter clients: JWT, OAuth2, 2FA.

This file contains all documentation content of https://awesomelangauth.com/ in a single document following the llmstxt.org standard. Links that start with / are relative to https://awesomelangauth.com.

## Node.js Authentication Quickstart

## Getting Started with awesome-node-auth

**node-auth** is a production-ready, database-agnostic JWT authentication and communication bus for Node.js written in TypeScript. It establishes a 360-degree communication and access control layer compatible with any Node.js framework (NestJS, Next.js, Express, Fastify, etc.) and any database through a simple interface pattern.

:::note Before you start
Make sure you have **Node.js 18+** and a package manager (npm / yarn / pnpm) installed.
:::

### Pick a recipe

Choose the authentication strategy that fits your application. You can combine multiple recipes.

| Recipe | Description |
|--------|-------------|
| [Email / Password](/docs/authentication/local) | Classic login with bcrypt hashing |
| [OAuth / Social](/docs/authentication/oauth) | Google, GitHub, custom providers |
| [Magic Link](/docs/authentication/magic-link) | Passwordless email login |
| [SMS OTP](/docs/authentication/sms) | Phone number verification |
| [TOTP 2FA](/docs/authentication/totp) | Google Authenticator-compatible |
| [API Keys](/docs/advanced/api-keys) | Machine-to-machine service tokens |
| [Multi-Tenancy](/docs/advanced/multi-tenancy) | Isolated tenant support |
| [Auth Tools & SSE](/docs/advanced/auth-tools) | Event bus, SSE streams, webhooks, telemetry |
| [Dynamic Email Templates & i18n](/docs/advanced/mailer#dynamic-templates-with-itemplatestore) | Custom email templates with per-language translations via `ITemplateStore` |
| [UI Internationalization (i18n)](/docs/advanced/built-in-ui#internationalization-i18n) | Translate built-in UI pages via `data-i18n` + `ITemplateStore` |

---

### **Step 1**: Install

```bash
npm install @awesome-lang-auth/node
```

---

### **Step 2**: Implement IUserStore

node-auth is database-agnostic. You connect it to your database by implementing the `IUserStore` interface:

```typescript
import { IUserStore, BaseUser } from '@awesome-lang-auth/node';

export class MyUserStore implements IUserStore {
  async findByEmail(email: string): Promise<BaseUser | null> {
    return db.users.findOne({ email });
  }
  async findById(id: string): Promise<BaseUser | null> {
    return db.users.findOne({ id });
  }
  async create(data: Partial<BaseUser>): Promise<BaseUser> {
    return db.users.insert(data);
  }
  async updateRefreshToken(userId: string, token: string | null, expiry: Date | null): Promise<void> {
    await db.users.update({ id: userId }, { refreshToken: token, refreshTokenExpiry: expiry });
  }
  async updateLastLogin(userId: string): Promise<void> {
    await db.users.update({ id: userId }, { lastLogin: new Date() });
  }
  async updatePassword(userId: string, hashedPassword: string): Promise<void> {
    await db.users.update({ id: userId }, { password: hashedPassword });
  }
  async updateResetToken(userId: string, token: string | null, expiry: Date | null): Promise<void> {
    await db.users.update({ id: userId }, { resetToken: token, resetTokenExpiry: expiry });
  }
  // ... implement other methods (2FA, Magic Link, SMS, etc.) as needed
}
```

:::tip
See [Database Integration](/docs/database) for ready-to-use implementations for SQLite, PostgreSQL, MySQL, and MongoDB.
:::

---

### **Step 3**: Configure AuthConfigurator

  

**Express**

```typescript
import express from 'express';
import { AuthConfigurator } from '@awesome-lang-auth/node';
import { MyUserStore } from './my-user-store';

const app = express();
app.use(express.json());

const auth = new AuthConfigurator(
  {
    accessTokenSecret: process.env.ACCESS_TOKEN_SECRET!,
    refreshTokenSecret: process.env.REFRESH_TOKEN_SECRET!,
    accessTokenExpiresIn: '15m',
    refreshTokenExpiresIn: '7d',
  },
  new MyUserStore()
);
```

  
  

**NestJS**

```typescript
// auth.module.ts
import { Module } from '@nestjs/common';
import { AuthConfigurator } from '@awesome-lang-auth/node';
import { MyUserStore } from './my-user-store';

const auth = new AuthConfigurator(
  {
    accessTokenSecret: process.env.ACCESS_TOKEN_SECRET!,
    refreshTokenSecret: process.env.REFRESH_TOKEN_SECRET!,
    accessTokenExpiresIn: '15m',
    refreshTokenExpiresIn: '7d',
  },
  new MyUserStore()
);

@Module({
  providers: [{ provide: 'AUTH', useValue: auth }],
  exports: ['AUTH'],
})
export class AuthModule {}
```

  
  

**Next.js**

```typescript
// lib/auth.ts
import { AuthConfigurator } from '@awesome-lang-auth/node';
import { MyUserStore } from './my-user-store';

export const auth = new AuthConfigurator(
  {
    accessTokenSecret: process.env.ACCESS_TOKEN_SECRET!,
    refreshTokenSecret: process.env.REFRESH_TOKEN_SECRET!,
    accessTokenExpiresIn: '15m',
    refreshTokenExpiresIn: '7d',
  },
  new MyUserStore()
);
```

  

---

### **Step 4**: Mount the router

  

**Express**

```typescript
// Mount all auth endpoints under /auth
app.use('/auth', auth.router());

// Protect routes
app.get('/protected', auth.middleware(), (req, res) => {
  res.json({ user: req.user });
});

app.listen(3000);
```

  
  

**NestJS**

```typescript
// main.ts
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { auth } from './auth';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.use('/auth', auth.router());
  await app.listen(3000);
}
bootstrap();
```

  
  

**Next.js App Router**

```typescript
// See the Next.js integration guide for the full catch-all route handler
// that bridges the App Router request/response to the Express-compatible router.
// https://your-wiki/docs/frameworks/nextjs
import { getAuth } from '@/lib/auth';

// Use auth.router() inside a catch-all API route handler.
// The auth singleton is created in lib/auth.ts:
//   export const auth = new AuthConfigurator(config, userStore);
```

  

---

### Next Steps

- [Installation & Configuration](/docs/installation) – Full config options, CSRF, 2FA
- [Authentication Strategies](/docs/authentication) – All available recipes
- [Database Integration](/docs/database) – IUserStore implementations
- [API Reference](/docs/api-reference) – All endpoints
- [Use the docs with AI assistants](/docs/ai-assistants) – An index of the docs (llms.txt) and every page in one file (llms-full.txt)

---

## Live Node.js Authentication Demos on StackBlitz

## Live Demos

Fully-functional, in-browser demos powered by [StackBlitz WebContainers](https://stackblitz.com).
Each example uses an **in-memory store** so everything works out-of-the-box — no database setup required.
Fill in the `.env.example` values to connect a real database or enable email/SMS features.

---

### Express (Basic)

The simplest integration: Express + `awesome-node-auth` with HttpOnly JWT cookies, bcrypt password hashing, and an admin panel.

| | |
|---|---|
| **Stack** | Node.js · Express · Vanilla HTML/JS |
| **Auth** | Register · Login · Logout · `/auth/me` · Refresh token |
| **Database** | In-memory |
| **Start** | `npm start` |

[![Open in StackBlitz](/img/open_in_stackblitz.svg)](https://stackblitz.com/github/awesome-lang-auth/awesome-node-auth/tree/main/demo/express-vanilla?title=awesome-node-auth%20Express%20Demo&startScript=start)

---

### NestJS Fullstack

NestJS application with `AuthModule.forRoot()`, `JwtAuthGuard`, `@CurrentUser()` decorator, and a static HTML frontend.

| | |
|---|---|
| **Stack** | Node.js · NestJS · TypeScript · ts-node · Vanilla HTML/JS |
| **Auth** | Register · Login · Logout · `/auth/me` · Refresh · Protected endpoint |
| **Database** | In-memory |
| **Start** | `npm start` |

[![Open in StackBlitz](/img/open_in_stackblitz.svg)](https://stackblitz.com/github/awesome-lang-auth/awesome-node-auth/tree/main/demo/nestjs-fullstack?title=awesome-node-auth%20NestJS%20Demo&startScript=start)

---

### Next.js Fullstack (Pages Router)

Full-stack Next.js application with a catch-all `/api/auth/[...auth]` route, Edge Middleware route protection, and a login + dashboard UI.

| | |
|---|---|
| **Stack** | Node.js · Next.js 15 · TypeScript · React |
| **Auth** | Register · Login · Logout · Dashboard (protected) · Middleware redirect |
| **Database** | In-memory |
| **Start** | `npm start` (runs `next dev`) |

[![Open in StackBlitz](/img/open_in_stackblitz.svg)](https://stackblitz.com/github/awesome-lang-auth/awesome-node-auth/tree/main/demo/nextjs-fullstack?title=awesome-node-auth%20Next.js%20Demo&startScript=start)

---

### Angular SSR (with Guards & Interceptors)

Angular 19 application with Server-Side Rendering, a full auth layer, and all production-ready patterns:

- **`AuthService`** — user state, login/logout/refresh via HttpOnly cookies
- **`authInterceptor`** — CSRF header + automatic token-refresh queue (handles concurrent 401s)
- **`authGuard`, `guestGuard`, `roleGuard`** — route protection
- **`APP_INITIALIZER`** — silent session restore on page reload
- **`ssrCookieInterceptor`** — forwards browser cookies to the API server during SSR

| | |
|---|---|
| **Stack** | Node.js · Angular 19 SSR · Express (node-auth API) · TypeScript |
| **Dev mode** | `npm start` → API server (port 3000) + `ng serve` (port 4200) with proxy |
| **Production** | `npm run build && npm run serve:ssr` |
| **Database** | In-memory |

[![Open in StackBlitz](/img/open_in_stackblitz.svg)](https://stackblitz.com/github/awesome-lang-auth/awesome-node-auth/tree/main/demo/angular-ssr?title=awesome-node-auth%20Angular%20SSR%20Demo&startScript=start)

---

### Express + Angular SPA

Separate Express API (node-auth) on port 3000 and Angular SPA on port 4200. Angular proxies `/auth/*` and `/admin/*` to Express during development.

Same auth patterns as the Angular SSR demo (guards, interceptors, `APP_INITIALIZER`) — without SSR complexity. In production, Express serves the compiled Angular build.

| | |
|---|---|
| **Stack** | Node.js · Angular 19 · Express (node-auth API) · TypeScript |
| **Dev mode** | `npm start` → API server (port 3000) + `ng serve` (port 4200) with proxy |
| **Production** | `npm run build && npm run serve:prod` |
| **Database** | In-memory |

[![Open in StackBlitz](/img/open_in_stackblitz.svg)](https://stackblitz.com/github/awesome-lang-auth/awesome-node-auth/tree/main/demo/express-angular-spa?title=awesome-node-auth%20Express%20%2B%20Angular%20SPA&startScript=start)

---

### Using your own database

All demos use `InMemoryUserStore` by default. To connect a real database, replace it with one of the ready-made stores:

| Database | Guide |
|----------|-------|
| SQLite | [docs/database/sqlite](/docs/database/sqlite) |
| MySQL | [docs/database/mysql](/docs/database/mysql) |
| PostgreSQL | [docs/database/postgresql](/docs/database/postgresql) |
| MongoDB | [docs/database/mongodb](/docs/database/mongodb) |

Copy the `.env.example` → `.env` (or `.env.local` for Next.js) and set `ACCESS_TOKEN_SECRET`, `REFRESH_TOKEN_SECRET`, and your database connection string.

:::tip In-memory data resets on restart
The in-memory store is ephemeral — all registered users are lost when the server restarts. This is intentional for the demos. In production, use a persistent database.
:::

### Related

- [Runnable Express authentication demo](/demo) — the same demo as copy-paste code to run locally
- [Node.js authentication quickstart](/docs/intro) — go from the demo to your own app
- [Express authentication](/docs/frameworks/express) — how the demo server is wired
- [Database-agnostic auth with IUserStore](/docs/database) — swap the in-memory store for a real database

---

## Install awesome-node-auth in a Node.js App

## Installation & Configuration

### **Step 1**: Install the package

  

**npm**

```bash
npm install @awesome-lang-auth/node
```

  
  

**yarn**

```bash
yarn add @awesome-lang-auth/node
```

  
  

**pnpm**

```bash
pnpm add @awesome-lang-auth/node
```

  

:::note Package name
The library is published on npm as `@awesome-lang-auth/node`, formerly published as `awesome-node-auth`. Imports use the same name as the package: `import { AuthConfigurator } from '@awesome-lang-auth/node'`.
:::

:::info TypeScript
node-auth is written in TypeScript and ships with its own type declarations — no `@types/` package needed.
:::

---

### **Step 2**: Configure AuthConfigurator

Create an `AuthConfig` object and pass it to `AuthConfigurator` along with your `IUserStore` implementation:

```typescript
import { AuthConfigurator, AuthConfig } from '@awesome-lang-auth/node';
import { MyUserStore } from './my-user-store';

const config: AuthConfig = {
  accessTokenSecret: process.env.ACCESS_TOKEN_SECRET!,
  refreshTokenSecret: process.env.REFRESH_TOKEN_SECRET!,
  accessTokenExpiresIn: '15m',
  refreshTokenExpiresIn: '7d',
};

const auth = new AuthConfigurator(config, new MyUserStore());
```

#### AuthConfig Options

| Option | Type | Required | Default | Description |
|--------|------|----------|---------|-------------|
| `accessTokenSecret` | `string` | ✅ | — | Secret for signing access tokens |
| `refreshTokenSecret` | `string` | ✅ | — | Secret for signing refresh tokens |
| `accessTokenExpiresIn` | `string` | ❌ | `'15m'` | Access token TTL (e.g. `'15m'`) |
| `refreshTokenExpiresIn` | `string` | ❌ | `'7d'` | Refresh token TTL (e.g. `'7d'`) |
| `buildTokenPayload` | `(user) => object` | ❌ | — | Inject custom claims into JWT |
| `csrf.enabled` | `boolean` | ❌ | `false` | Enable CSRF double-submit cookie |
| `emailVerificationMode`| `'none'\|'lazy'\|'strict'` | ❌ | `'none'` | Email verification enforcement mode |
| `requireEmailVerification`| `boolean` | ❌ | `false` | (Deprecated) Use `emailVerificationMode` instead |

---

### **Step 3**: Mount the router

```typescript
import express from 'express';
import rateLimit from 'express-rate-limit';

const app = express();
app.use(express.json());

const limiter = rateLimit({ windowMs: 15 * 60 * 1000, max: 20 });

app.use('/auth', auth.router({
  rateLimiter: limiter,
  onRegister: async (data, config) => {
    return userStore.create(data);
  },
}));

app.listen(3000);
```

---

### Complete Configuration Example

```typescript
import express from 'express';
import rateLimit from 'express-rate-limit';
import { AuthConfigurator, AuthConfig } from '@awesome-lang-auth/node';
import { MyUserStore } from './stores/user-store';
import { MySessionStore } from './stores/session-store';
import { MyRbacStore } from './stores/rbac-store';

const app = express();
app.use(express.json());

const config: AuthConfig = {
  accessTokenSecret: process.env.ACCESS_TOKEN_SECRET!,
  refreshTokenSecret: process.env.REFRESH_TOKEN_SECRET!,
  accessTokenExpiresIn: '15m',
  refreshTokenExpiresIn: '7d',
  emailVerificationMode: 'lazy',
  csrf: { enabled: true },
  buildTokenPayload: async (user) => ({
    tenantId: user.tenantId,
    plan: user.plan,
  }),
};

const userStore = new MyUserStore();
const sessionStore = new MySessionStore();
const rbacStore = new MyRbacStore();

const auth = new AuthConfigurator(config, userStore);

const limiter = rateLimit({ windowMs: 15 * 60 * 1000, max: 20 });

app.use('/auth', auth.router({
  rateLimiter: limiter,
  sessionStore,
  rbacStore,
  onRegister: async (data, config) => {
    return userStore.create(data);
  },
}));

app.listen(3000);
```

### Related

- [Node.js authentication quickstart](/docs/intro) — the shortest path from install to a working login
- [Authentication methods for Node.js](/docs/authentication) — pick email/password, OAuth2, magic link, TOTP or SMS
- [Database-agnostic auth with IUserStore](/docs/database) — wire the library to your own database
- [Framework integrations](/docs/frameworks) — Express, NestJS, Next.js and any other Node HTTP server
- [Auth API endpoints reference](/docs/api-reference/endpoints) — every route the auth router mounts

---

## Authentication Methods for Node.js

## Authentication Strategies

node-auth supports multiple authentication strategies that can be combined:

| Strategy | Description |
|----------|-------------|
| [Local](/docs/authentication/local) | Email/password with bcrypt hashing |
| [OAuth 2.0](/docs/authentication/oauth) | Google, GitHub, or any custom provider |
| [Magic Link](/docs/authentication/magic-link) | Passwordless email authentication |
| [TOTP 2FA](/docs/authentication/totp) | Time-based one-time passwords |
| [SMS OTP](/docs/authentication/sms) | Phone number verification codes |

All strategies are plug-in — only configure what you need.

---

## Email and Password Authentication in Node.js

## Email / Password Recipe

The local strategy provides classic email and password authentication with bcrypt hashing and a full password reset flow.

:::caution Password strength
node-auth does not enforce password complexity by default. Validate password strength in your `onRegister` callback before creating the user.
:::

---

### Register → Login → Refresh → Logout flow

```mermaid
sequenceDiagram
    autonumber
    participant C as Client
    participant S as awesome-node-auth Router
    participant DB as IUserStore

    Note over C,DB: Registration
    C->>S: POST /auth/register {email, password}
    S->>DB: onRegister(data)
    DB-->>S: user {id, email, …}
    S-->>C: 201 {success: true, userId}

    Note over C,DB: Login
    C->>S: POST /auth/login {email, password}
    S->>DB: findByEmail(email)
    DB-->>S: user
    S->>S: bcrypt.compare(password, hash)
    S-->>C: 200 + Set-Cookie: accessToken, refreshToken, csrf-token

    Note over C,DB: Token refresh
    C->>S: POST /auth/refresh (refreshToken cookie)
    S->>DB: find user by refreshToken
    DB-->>S: user
    S->>S: sign new token pair
    S-->>C: 200 + Set-Cookie: new accessToken, new refreshToken, new csrf-token

    Note over C,DB: Logout
    C->>S: POST /auth/logout (accessToken cookie)
    S->>DB: updateRefreshToken(userId, null, null)
    S-->>C: 200 {success: true} + cleared cookies
```

---

### Password Reset flow

```mermaid
sequenceDiagram
    autonumber
    participant C as Client
    participant S as awesome-node-auth Router
    participant DB as IUserStore
    participant E as Email Provider

    C->>S: POST /auth/forgot-password {email}
    S->>DB: findByEmail(email)
    DB-->>S: user
    S->>S: generate reset token (32 random bytes)
    S->>DB: updateResetToken(userId, token, expiry+1h)
    S->>E: sendPasswordReset(email, token, link)
    S-->>C: 200 {success: true}

    Note over C,E: User clicks link in email

    C->>S: POST /auth/reset-password {token, newPassword}
    S->>DB: findByResetToken(token)
    DB-->>S: user (validates expiry)
    S->>S: bcrypt.hash(newPassword)
    S->>DB: updatePassword(userId, hash)
    S->>DB: updateResetToken(userId, null, null)
    S-->>C: 200 {success: true}
```

---

### **Step 1**: Enable LocalStrategy

The local strategy is active by default — no extra configuration needed. Just create your `AuthConfigurator`:

```typescript
import { AuthConfigurator } from '@awesome-lang-auth/node';

const auth = new AuthConfigurator(config, userStore);
```

---

### **Step 2**: Implement IUserStore

Ensure your `IUserStore` implements the methods required for local auth:

```typescript
export class MyUserStore implements IUserStore {
  async findByEmail(email: string) { /* … */ }
  async findById(id: string) { /* … */ }
  async create(data: Partial<BaseUser>) { /* … */ }
  async updateRefreshToken(userId: string, token: string | null, expiry: Date | null) { /* … */ }
  async updatePassword(userId: string, hashedPassword: string) { /* … */ }
  async updateResetToken(userId: string, token: string | null, expiry: Date | null) { /* … */ }
  async findByResetToken(token: string) { /* … */ }
}
```

---

### **Step 3**: Mount the router

  

**Express**

```typescript
app.use('/auth', auth.router({
  onRegister: async (data, config) => {
    // Validate, then persist
    return userStore.create(data);
  },
}));
```

  
  

**NestJS**

```typescript
// In AuthController constructor — see NestJS guide
this.router = auth.router({
  onRegister: async (data) => userStore.create(data),
});
```

  
  

**Next.js**

```typescript
// pages/api/auth/[...auth].ts
export default function handler(req, res) {
  const router = getAuth().router({
    onRegister: async (data) => userStore.create(data),
  });
  req.url = req.url!.replace(/^\/api\/auth/, '') || '/';
  router(req as any, res as any, () => res.status(404).end());
}
```

  

---

### **Step 4**: Test the endpoints

```bash
# Register
curl -X POST http://localhost:3000/auth/register \
  -H 'Content-Type: application/json' \
  -d '{"email":"user@example.com","password":"secret123","firstName":"Jane"}'

# Login
curl -X POST http://localhost:3000/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"user@example.com","password":"secret123"}'
```

---

### Endpoint Reference

| Method | Path | Auth | Description |
|--------|------|:---:|-------------|
| `POST` | `/auth/login` | — | Login with email + password |
| `POST` | `/auth/register` | — | Register new user (requires `onRegister`) |
| `POST` | `/auth/logout` | ✅ | Invalidate refresh token + clear cookies |
| `POST` | `/auth/refresh` | — | Exchange refresh token for new access token |
| `GET`  | `/auth/me` | ✅ | Get current user profile |
| `POST` | `/auth/forgot-password` | — | Send password reset email |
| `POST` | `/auth/reset-password` | — | Reset password with token |
| `POST` | `/auth/change-password` | ✅ | Change password for authenticated user |

### Related

- [Passwordless magic link login](/docs/authentication/magic-link) — the same flow without a password
- [Email verification modes](/docs/advanced/email-verification) — decide how strictly unverified users are blocked
- [Session management and token revocation](/docs/advanced/sessions) — invalidate a login before the token expires
- [Database-agnostic auth with IUserStore](/docs/database) — where the password hash is actually stored

---

## OAuth2 Social Login in Node.js (Google, GitHub)

## OAuth / Social Recipe

node-auth supports Google, GitHub, and any custom OAuth 2.0 provider via `GenericOAuthStrategy`.

---

### OAuth flow

```mermaid
sequenceDiagram
    autonumber
    participant U as User
    participant B as Browser
    participant S as awesome-node-auth Router
    participant P as OAuth Provider (Google/GitHub)
    participant DB as IUserStore

    U->>B: Click "Sign in with Google"
    B->>S: GET /auth/oauth/google
    S->>S: build authorization URL + state param
    S-->>B: 302 redirect to Google OAuth

    B->>P: Authorization request (scope: email, profile)
    P-->>U: Consent screen
    U->>P: Approve
    P-->>B: 302 redirect to callback URL with code + state

    B->>S: GET /auth/oauth/google/callback?code=…&state=…
    S->>P: Exchange code for access_token
    P-->>S: access_token + profile
    S->>DB: findOrCreateUser(profile)
    DB-->>S: user
    S->>S: sign token pair
    S-->>B: 302 redirect to app + Set-Cookie: accessToken, refreshToken, csrf-token
```

:::info Account conflicts
If the OAuth provider email matches an existing local account, awesome-node-auth returns a `409 Conflict`. Use `IPendingLinkStore` to resolve conflicts automatically. See [Account Linking](/docs/advanced/account-linking).
:::

---

### **Step 1**: Configure your OAuth app

Register your application in the provider's developer console and note the **Client ID** and **Client Secret**. Set the callback URL to:

```
https://yourapp.com/auth/oauth/<provider>/callback
```

---

### **Step 2**: Create a strategy

  

**Google**

```typescript
import { GoogleStrategy, AuthConfig } from '@awesome-lang-auth/node';

class MyGoogleStrategy extends GoogleStrategy {
  constructor(config: AuthConfig) {
    super(config);
  }

  async findOrCreateUser(profile: any) {
    // Always use providerAccountId + provider for lookup — never email alone
    // (prevents account-takeover via email spoofing)
    let user = await userStore.findByProviderAccount?.('google', profile.id);
    if (!user) {
      user = await userStore.create({
        email: profile.email,
        firstName: profile.name,
        providerAccountId: profile.id,
        loginProvider: 'google',
        isEmailVerified: true,
      });
    }
    return user;
  }
}

const googleStrategy = new MyGoogleStrategy(config);
```

  
  

**GitHub**

```typescript
import { GithubStrategy, AuthConfig } from '@awesome-lang-auth/node';

class MyGithubStrategy extends GithubStrategy {
  constructor(config: AuthConfig) {
    super(config);
  }

  async findOrCreateUser(profile: any) {
    let user = await userStore.findByProviderAccount?.('github', profile.id);
    if (!user) {
      user = await userStore.create({
        email: profile.email,
        firstName: profile.name,
        providerAccountId: profile.id,
        loginProvider: 'github',
        isEmailVerified: true,
      });
    }
    return user;
  }
}

const githubStrategy = new MyGithubStrategy(config);
```

  
  

**Custom Provider**

```typescript
import { GenericOAuthStrategy } from '@awesome-lang-auth/node';

const discordStrategy = new GenericOAuthStrategy({
  name: 'discord',
  clientId: process.env.DISCORD_CLIENT_ID!,
  clientSecret: process.env.DISCORD_CLIENT_SECRET!,
  authorizationUrl: 'https://discord.com/api/oauth2/authorize',
  tokenUrl: 'https://discord.com/api/oauth2/token',
  userInfoUrl: 'https://discord.com/api/users/@me',
  callbackUrl: 'https://yourapp.com/auth/oauth/discord/callback',
  scope: ['identify', 'email'],
  mapProfile: (raw) => ({
    id: raw.id,
    email: raw.email,
    name: raw.username,
  }),
  findOrCreateUser: async (profile) => {
    return userStore.findOrCreate({ ...profile, loginProvider: 'discord' });
  },
});
```

  

---

### **Step 3**: Mount the router

```typescript
app.use('/auth', auth.router({
  googleStrategy,
  githubStrategy,
  // or for custom providers:
  oauthStrategies: [discordStrategy],
}));
```

---

### **Step 4**: Implement `findByProviderAccount` (recommended)

Add this to your `IUserStore` to enable safe provider-based lookup (avoids email-based account takeover):

```typescript
async findByProviderAccount(provider: string, providerAccountId: string): Promise<BaseUser | null> {
  return db('users').where({ loginProvider: provider, providerAccountId }).first() ?? null;
}
```

---

### OAuth Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/auth/oauth/google` | Redirect to Google OAuth |
| `GET` | `/auth/oauth/google/callback` | Google OAuth callback |
| `GET` | `/auth/oauth/github` | Redirect to GitHub OAuth |
| `GET` | `/auth/oauth/github/callback` | GitHub OAuth callback |
| `GET` | `/auth/oauth/:name` | Redirect to custom provider |
| `GET` | `/auth/oauth/:name/callback` | Custom provider callback |

---

## Passwordless Magic Link Login in Node.js

## Magic Link Recipe

Magic links provide passwordless authentication via email. No password required — users click a link to log in.

:::tip Email verification bonus
The first magic-link login automatically counts as email verification. No separate verification step needed.
:::

---

### Magic Link flow

```mermaid
sequenceDiagram
    autonumber
    participant C as Client
    participant S as awesome-node-auth Router
    participant DB as IUserStore
    participant E as Email Provider

    C->>S: POST /auth/magic-link/send {email}
    S->>DB: findByEmail(email)
    DB-->>S: user
    S->>S: generate secure token (32 bytes)
    S->>DB: updateMagicLinkToken(userId, token, expiry+15m)
    S->>E: sendMagicLink(email, token, link)
    S-->>C: 200 {success: true}

    Note over C,E: User clicks link in email, app extracts token

    C->>S: POST /auth/magic-link/verify {token}
    S->>DB: findByMagicLinkToken(token)
    DB-->>S: user (validates expiry)
    S->>DB: updateMagicLinkToken(userId, null, null)
    S->>DB: updateEmailVerified(userId, true)
    S->>S: sign token pair
    S-->>C: 200 + Set-Cookie: accessToken, refreshToken, csrf-token
```

:::info Bearer mode
For native/mobile clients, add `X-Auth-Strategy: bearer` to `/auth/magic-link/verify` to receive tokens in the response body instead of cookies.
:::

---

### Login mode and 2FA mode

Both endpoints take an optional `mode` in the request body:

| `mode` | `POST /auth/magic-link/send` body | `POST /auth/magic-link/verify` body | What the link does |
|--------|-----------------------------------|-------------------------------------|--------------------|
| `'login'` (default) | `{ email, emailLang? }` | `{ token }` | Passwordless login |
| `'2fa'` | `{ mode: '2fa', tempToken, emailLang? }` | `{ mode: '2fa', token, tempToken }` | Second factor after the password |

:::note Passwordless login and 2FA
In `mode: 'login'`, `POST /auth/magic-link/verify` issues a session directly and does not ask for the second factor, even for accounts with TOTP enabled.

The second-factor flow is `mode: '2fa'`, after the password: `POST /auth/login` answers `{ requiresTwoFactor: true, tempToken, available2faMethods }`, `POST /auth/magic-link/send` with `{ mode: '2fa', tempToken }` emails a link to that user, and `POST /auth/magic-link/verify` with `{ mode: '2fa', token, tempToken }` issues the session.
:::

---

### **Step 1**: Configure AuthConfig

Magic links are enabled by providing a `sendMagicLink` callback (or a `mailer` configuration) in your `AuthConfig`:

```typescript
const config: AuthConfig = {
  // ... secrets
  email: {
    // Option A: Use a custom callback
    sendMagicLink: async (email, token, link, lang) => {
      await mailer.send({
        to: email,
        subject: 'Your login link',
        html: `<a href="${link}">Click to log in</a>`,
      });
    },
    // Option B: Use the built-in HTTP mailer (see Mailer guide)
    // mailer: { endpoint: '...', apiKey: '...' }
  }
};
```

---

### **Step 2**: Mount the router

The magic-link endpoints are active as long as the email configuration is present. No additional strategy needs to be passed to the router:

  

**Express**

```typescript
app.use('/auth', auth.router());
```

  
  

**NestJS**

```typescript
this.router = auth.router();
```

  

---

### **Step 3**: Implement IUserStore methods

Magic link requires these store methods:

```typescript
async updateMagicLinkToken(userId: string, token: string | null, expiry: Date | null): Promise<void>
async findByMagicLinkToken(token: string): Promise<BaseUser | null>
```

---

### **Step 4**: Test the flow

```bash
# Step 1: Request magic link
curl -X POST http://localhost:3000/auth/magic-link/send \
  -H 'Content-Type: application/json' \
  -d '{"email":"user@example.com"}'

# Step 2: Verify (token from email)
curl -X POST http://localhost:3000/auth/magic-link/verify \
  -H 'Content-Type: application/json' \
  -d '{"token":"<token-from-email>"}'
# Cookie mode: { "success": true } + HttpOnly cookies
# Bearer mode: add -H 'X-Auth-Strategy: bearer' → { "success": true, "accessToken": "…", "refreshToken": "…" }
```

---

### Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/auth/magic-link/send` | Generate token + send magic-link email. Body: `{ email }` for login; `{ mode: '2fa', tempToken }` for the second factor |
| `POST` | `/auth/magic-link/verify` | Verify token → issue session tokens. Body: `{ token }` for login; `{ mode: '2fa', token, tempToken }` for the second factor |

### Related

- [Email and password authentication](/docs/authentication/local) — the classic alternative to magic links
- [Built-in HTTP mailer](/docs/advanced/mailer) — how the magic-link email is delivered
- [Email verification modes](/docs/advanced/email-verification) — why the first magic-link click verifies the address
- [TOTP two-factor authentication](/docs/authentication/totp) — the authenticator-app second factor after a password login

---

## TOTP Two-Factor Authentication in Node.js

## TOTP 2FA Recipe

Time-based One-Time Passwords (TOTP) provide Google Authenticator-compatible two-factor authentication. TOTP is built into the auth router — no extra strategy configuration is needed.

:::caution Backup codes
TOTP does not provide built-in backup codes. Consider implementing your own backup code mechanism so users can recover access if they lose their authenticator app.
:::

---

### TOTP enrollment flow

```mermaid
sequenceDiagram
    autonumber
    participant C as Client (authenticated)
    participant S as awesome-node-auth Router
    participant DB as IUserStore
    participant App as Authenticator App

    C->>S: POST /auth/2fa/setup (accessToken cookie)
    S->>S: otplib.authenticator.generateSecret()
    S->>S: build otpauthUrl + QR code data URI
    S-->>C: 200 {secret, otpauthUrl, qrCode}

    C->>App: User scans QR code

    C->>S: POST /auth/2fa/verify-setup {token: "123456", secret}
    S->>S: otplib.authenticator.check(token, secret)
    S->>DB: updateTotpSecret(userId, secret)
    S-->>C: 200 {success: true}
```

---

### 2FA login flow

```mermaid
sequenceDiagram
    autonumber
    participant C as Client
    participant S as awesome-node-auth Router
    participant DB as IUserStore

    C->>S: POST /auth/login {email, password}
    S->>DB: findByEmail(email)
    DB-->>S: user (isTotpEnabled: true)
    S->>S: bcrypt.compare(password, hash) ✓
    S->>S: sign short-lived tempToken
    S-->>C: 200 {requiresTwoFactor: true, tempToken, available2faMethods: ["totp"]}

    Note over C,S: User opens authenticator app for 6-digit code

    C->>S: POST /auth/2fa/verify {tempToken, totpCode: "123456"}
    S->>S: verify tempToken signature
    S->>DB: findById(sub from tempToken)
    DB-->>S: user
    S->>S: otplib.authenticator.check(totpCode, user.totpSecret)
    S->>S: sign full token pair
    S-->>C: 200 + Set-Cookie: accessToken, refreshToken, csrf-token
```

---

### **Step 1**: Mount the router

TOTP endpoints are always available. Just mount the standard auth router:

```typescript
app.use('/auth', auth.router());
```

---

### **Step 2**: User enrolls TOTP

#### Generate secret and QR code

```typescript
// POST /auth/2fa/setup (authenticated)
const { secret, otpauthUrl, qrCode } = await fetch('/auth/2fa/setup', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
}).then(r => r.json());

// Display qrCode (a data: URI) in an <img> tag
// or show `secret` for manual entry in the authenticator app
```

#### Confirm activation

```typescript
// POST /auth/2fa/verify-setup (authenticated)
await fetch('/auth/2fa/verify-setup', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({ token: '123456', secret }),
});
```

---

### **Step 3**: Login with 2FA

```typescript
// Step 1: Initial login → 2FA challenge
const loginRes = await fetch('/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({ email, password }),
}).then(r => r.json());

if (loginRes.requiresTwoFactor) {
  const { tempToken, available2faMethods } = loginRes;
  // Show the TOTP input to the user
}

// Step 2: Submit TOTP code → full session
await fetch('/auth/2fa/verify', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({ tempToken, totpCode: '123456' }),
});
```

:::info Bearer mode
For native/mobile clients add `X-Auth-Strategy: bearer` to `/auth/2fa/verify` to receive tokens in the JSON body.
:::

---

### TOTP Endpoints

| Method | Path | Auth | Description |
|--------|------|:----:|-------------|
| `POST` | `/auth/2fa/setup` | ✅ | Generate TOTP secret + QR code data URI |
| `POST` | `/auth/2fa/verify-setup` | ✅ | Confirm enrollment with a valid TOTP code |
| `POST` | `/auth/2fa/verify` | — (temp token) | Complete 2FA login |
| `POST` | `/auth/2fa/disable` | ✅ | Disable TOTP for the user |

### Related

- [SMS OTP verification and 2FA](/docs/authentication/sms) — the SMS-based second factor
- [Email and password authentication](/docs/authentication/local) — the first factor TOTP protects
- [Session management and token revocation](/docs/advanced/sessions) — revoke sessions when a device is lost
- [Bearer token mode for mobile apps](/docs/advanced/bearer-token) — 2FA from native clients

---

## SMS OTP Verification and 2FA in Node.js

## SMS OTP Recipe

Send one-time passwords via SMS for phone number verification or two-factor authentication.

---

### SMS OTP flow

```mermaid
sequenceDiagram
    autonumber
    participant C as Client
    participant S as awesome-node-auth Router
    participant DB as IUserStore
    participant SMS as SMS Provider

    C->>S: POST /auth/sms/send {userId}
    S->>DB: findById(userId)
    DB-->>S: user (must have phoneNumber)
    S->>S: generate 6-digit OTP code
    S->>DB: updateSmsCode(userId, code, expiry+10m)
    S->>SMS: sendSms(phoneNumber, "Your code: 123456")
    S-->>C: 200 {success: true}

    Note over C,SMS: User reads OTP from SMS

    C->>S: POST /auth/sms/verify {userId, code}
    S->>DB: findById(userId)
    DB-->>S: user
    S->>S: compare code + check expiry
    S->>DB: updateSmsCode(userId, null, null)
    S->>S: sign token pair
    S-->>C: 200 + Set-Cookie: accessToken, refreshToken, csrf-token
```

:::info Bearer mode
For native/mobile clients add `X-Auth-Strategy: bearer` to `/auth/sms/verify` to receive tokens in the JSON body.
:::

---

### Login mode and 2FA mode

Both endpoints take an optional `mode` in the request body:

| `mode` | `POST /auth/sms/send` body | `POST /auth/sms/verify` body | What the code does |
|--------|----------------------------|------------------------------|--------------------|
| `'login'` (default) | `{ userId }` or `{ email }` | `{ userId, code }` | Login with the SMS code alone |
| `'2fa'` | `{ mode: '2fa', tempToken }` | `{ mode: '2fa', tempToken, code }` | Second factor after the password |

:::note SMS login and 2FA
In `mode: 'login'`, `POST /auth/sms/verify` issues a session directly and does not ask for the second factor, even for accounts with TOTP enabled.

The second-factor flow is `mode: '2fa'`, after the password: `POST /auth/login` answers `{ requiresTwoFactor: true, tempToken, available2faMethods }`, `POST /auth/sms/send` with `{ mode: '2fa', tempToken }` texts a code to that user's `phoneNumber`, and `POST /auth/sms/verify` with `{ mode: '2fa', tempToken, code }` issues the session.
:::

---

### **Step 1**: Configure AuthConfig

SMS OTP is enabled by configuring the built-in HTTP SMS gateway in your `AuthConfig.sms` block:

```typescript
const config: AuthConfig = {
  // ... secrets
  sms: {
    endpoint:             'https://sms.yourprovider.com/send',
    apiKey:               process.env.SMS_API_KEY!,
    username:             process.env.SMS_USERNAME!,
    password:             process.env.SMS_PASSWORD!,
    codeExpiresInMinutes: 10,   // default: 10
  },
};
```

The built-in `SmsService` makes a `GET` request to `{endpoint}?username=…&password=…&phone=…&message=…` with an `X-API-Key` header. See [SmsService](#smsservice) below.

---

### **Step 2**: Mount the router

SMS endpoints are active as long as the SMS configuration is present in `AuthConfig`. No strategy needs to be passed to the router:

```typescript
app.use('/auth', auth.router());
```

---

### **Step 3**: Implement IUserStore methods

SMS OTP requires:

```typescript
async updateSmsCode(userId: string, code: string | null, expiry: Date | null): Promise<void>
```

The user record must also have `phoneNumber` set.

---

### **Step 4**: Test the flow

```bash
# Send OTP to user's phone
curl -X POST http://localhost:3000/auth/sms/send \
  -H 'Content-Type: application/json' \
  -d '{"userId":"123"}'

# Verify OTP code
curl -X POST http://localhost:3000/auth/sms/verify \
  -H 'Content-Type: application/json' \
  -d '{"userId":"123","code":"123456"}'
```

---

### SmsService

The `SmsService` is exported and can be used directly in your own code:

```typescript
import { SmsService } from '@awesome-lang-auth/node';

const smsService = new SmsService({
  endpoint:  'https://sms.yourprovider.com/send',
  apiKey:    process.env.SMS_API_KEY!,
  username:  process.env.SMS_USERNAME!,
  password:  process.env.SMS_PASSWORD!,
  codeExpiresInMinutes: 10,
});

// Send a custom SMS
await smsService.sendSms('+39123456789', 'Your verification code: 847261');

// Generate a random OTP code
const code = smsService.generateCode(6);  // '847261'
```

The service makes a `GET` request to `{endpoint}?username={u}&password={p}&phone={phone}&message={msg}` with an `X-API-Key` header.

---

### SMS Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/auth/sms/send` | Generate OTP + send to user's `phoneNumber`. Body: `{ userId }` or `{ email }` for login; `{ mode: '2fa', tempToken }` for the second factor |
| `POST` | `/auth/sms/verify` | Verify OTP → issue session tokens. Body: `{ userId, code }` for login; `{ mode: '2fa', tempToken, code }` for the second factor |

### Related

- [TOTP two-factor authentication](/docs/authentication/totp) — an app-based second factor with no SMS costs
- [Email and password authentication](/docs/authentication/local) — the first factor SMS OTP protects
- [Bearer token mode for mobile apps](/docs/advanced/bearer-token) — phone verification from native clients
- [Flutter authentication client](/docs/frameworks/flutter) — SMS flows in a mobile app

---

## Database-Agnostic Auth: The IUserStore Interface

## Database Integration

node-auth is completely **database-agnostic**. Implement the `IUserStore` interface for your database and pass the instance to `AuthConfigurator`.

:::info Any database
As long as you implement `IUserStore`, awesome-node-auth works with any storage backend — SQL, NoSQL, or even in-memory for tests.
:::

### IUserStore Interface

```typescript
import { IUserStore, BaseUser } from '@awesome-lang-auth/node';

export class MyUserStore implements IUserStore {
  // Core CRUD
  async findByEmail(email: string): Promise<BaseUser | null> { /* ... */ }
  async findById(id: string): Promise<BaseUser | null> { /* ... */ }
  async create(data: Partial<BaseUser>): Promise<BaseUser> { /* ... */ }

  // Token field updates
  async updateRefreshToken(userId: string, token: string | null, expiry: Date | null): Promise<void> { /* ... */ }
  async updateLastLogin(userId: string): Promise<void> { /* ... */ }
  async updateResetToken(userId: string, token: string | null, expiry: Date | null): Promise<void> { /* ... */ }
  async updatePassword(userId: string, hashedPassword: string): Promise<void> { /* ... */ }
  async updateTotpSecret(userId: string, secret: string | null): Promise<void> { /* ... */ }
  async updateMagicLinkToken(userId: string, token: string | null, expiry: Date | null): Promise<void> { /* ... */ }
  async updateSmsCode(userId: string, code: string | null, expiry: Date | null): Promise<void> { /* ... */ }

  // Important optional methods
  async findByResetToken(token: string): Promise<BaseUser | null> { /* ... */ }
  async findByMagicLinkToken(token: string): Promise<BaseUser | null> { /* ... */ }
  async findByProviderAccount(provider: string, providerAccountId: string): Promise<BaseUser | null> { /* ... */ }
  async updateProfile(userId: string, data: { firstName?: string | null; lastName?: string | null }): Promise<void> { /* ... */ }
}
```

### Required Methods by Feature

| Method | Required For |
|--------|-------------|
| `findByEmail` | Login, magic link, password reset |
| `findById` | Token refresh, 2FA, SMS |
| `create` | OAuth strategies, registration |
| `updateRefreshToken` | Login, logout, refresh |
| `updateResetToken` | Password reset flow |
| `updatePassword` | Change/reset password |
| `updateTotpSecret` | TOTP setup |
| `updateMagicLinkToken` | Magic link flow |
| `updateSmsCode` | SMS OTP flow |
| `findByResetToken` | `POST /auth/reset-password` |
| `findByMagicLinkToken` | `POST /auth/magic-link/verify` |
| `findByProviderAccount` | OAuth (recommended) |

### BaseUser

```typescript
interface BaseUser {
  id: string;
  email: string;
  password?: string;
  firstName?: string | null;
  lastName?: string | null;
  role?: string;
  loginProvider?: string | null;
  providerAccountId?: string | null;
  refreshToken?: string | null;
  refreshTokenExpiry?: Date | null;
  lastLogin?: Date | null;
  // ... other fields for 2FA, Magic Link, SMS
}
```

### Available Implementations

  

**In-Memory**

Perfect for testing and prototyping. No setup required.

[View docs →](/docs/database/in-memory)

  
  

**SQLite**

Uses `better-sqlite3`. Great for small apps and local development.

[View docs →](/docs/database/sqlite)

  
  

**MySQL**

Uses `mysql2`. Production-ready relational database.

[View docs →](/docs/database/mysql)

  
  

**MongoDB**

Uses the `mongodb` driver. Flexible document storage.

[View docs →](/docs/database/mongodb)

  
  

**PostgreSQL**

Uses `pg`. Robust SQL with full ACID compliance.

[View docs →](/docs/database/postgresql)

  
  

**PostgREST**

Use `fetch` to talk to a REST API. Write no SQL.

[View docs →](/docs/database/postgrest)

  
  

**PHP-CRUD-API**

Use `fetch` to talk to a REST API. Write no SQL.

[View docs →](/docs/database/php-crud-api)

---

## In-Memory User Store for Tests and Prototypes

## In-Memory Store

The in-memory store is ideal for testing, prototyping, and development. It's included in the `examples/` directory.

### Usage

```typescript
import { InMemoryUserStore } from './examples/in-memory-user-store';

const userStore = new InMemoryUserStore();
const auth = new AuthConfigurator(config, userStore);
```

### Example Implementation

```typescript
import { IUserStore, BaseUser } from '@awesome-lang-auth/node';

export class InMemoryUserStore implements IUserStore {
  private users: BaseUser[] = [];
  private nextId = 1;

  async findByEmail(email: string) {
    return this.users.find(u => u.email === email) ?? null;
  }

  async findById(id: string) {
    return this.users.find(u => u.id === id) ?? null;
  }

  async create(data: Partial<BaseUser>): Promise<BaseUser> {
    const user: BaseUser = {
      id: String(this.nextId++),
      email: data.email!,
      ...data,
    };
    this.users.push(user);
    return user;
  }

  async updateRefreshToken(userId: string, token: string | null, expiry: Date | null) {
    const user = this.users.find(u => u.id === userId);
    if (user) {
      user.refreshToken = token;
      user.refreshTokenExpiry = expiry;
    }
  }

  // ... other methods
}
```

### Related

- [Database-agnostic auth with IUserStore](/docs/database) — the interface this store implements
- [SQLite authentication store](/docs/database/sqlite) — the smallest persistent alternative
- [Live Node.js authentication demos](/docs/live-demo) — demos that run on this store
- [Express authentication](/docs/frameworks/express) — the server used in the runnable demo

---

## SQLite Authentication Store (better-sqlite3)

## SQLite with better-sqlite3

A production-ready SQLite implementation using `better-sqlite3`.

### Install

```bash
npm install better-sqlite3
npm install -D @types/better-sqlite3
```

### Setup

```typescript
import Database from 'better-sqlite3';
import { SqliteUserStore } from './examples/sqlite-user-store.example';

const db = new Database('app.db');
db.pragma('journal_mode = WAL');
db.pragma('foreign_keys = ON');

const userStore = new SqliteUserStore(db); // creates `users` table automatically
const auth = new AuthConfigurator(config, userStore);
```

The `SqliteUserStore` from `examples/sqlite-user-store.example.ts` automatically creates the `users` table on first run.

### Schema

```sql
CREATE TABLE IF NOT EXISTS users (
  id TEXT PRIMARY KEY,
  email TEXT UNIQUE NOT NULL,
  password TEXT,
  name TEXT,
  role TEXT DEFAULT 'user',
  loginProvider TEXT DEFAULT 'local',
  providerAccountId TEXT,
  refreshToken TEXT,
  refreshTokenExpiry TEXT,
  resetToken TEXT,
  resetTokenExpiry TEXT,
  totpSecret TEXT,
  isTotpEnabled INTEGER DEFAULT 0,
  magicLinkToken TEXT,
  magicLinkTokenExpiry TEXT,
  smsCode TEXT,
  smsCodeExpiry TEXT,
  isEmailVerified INTEGER DEFAULT 0,
  phoneNumber TEXT,
  createdAt TEXT DEFAULT CURRENT_TIMESTAMP
);
```

### Related

- [Database-agnostic auth with IUserStore](/docs/database) — the interface this store implements
- [PostgreSQL authentication store](/docs/database/postgresql) — when SQLite stops being enough
- [Extending BaseUser and auth interfaces](/docs/advanced/extending-interfaces) — add your own columns safely
- [Session management and token revocation](/docs/advanced/sessions) — persist sessions alongside users

---

## MySQL and MariaDB Authentication Store (mysql2)

## MySQL / MariaDB with mysql2

### Install

```bash
npm install mysql2
```

### Setup

```typescript
import mysql from 'mysql2/promise';
import { MySqlUserStore } from './examples/mysql-user-store.example';

const pool = mysql.createPool({
  host:     process.env.DB_HOST,
  user:     process.env.DB_USER,
  password: process.env.DB_PASSWORD,
  database: process.env.DB_NAME,
});

const userStore = new MySqlUserStore(pool);
await userStore.init(); // creates the `users` table automatically
const auth = new AuthConfigurator(config, userStore);
```

### Schema

```sql
CREATE TABLE IF NOT EXISTS users (
  id VARCHAR(36) PRIMARY KEY,
  email VARCHAR(255) UNIQUE NOT NULL,
  password VARCHAR(255),
  name VARCHAR(255),
  role VARCHAR(50) DEFAULT 'user',
  loginProvider VARCHAR(50) DEFAULT 'local',
  providerAccountId VARCHAR(255),
  refreshToken TEXT,
  refreshTokenExpiry DATETIME,
  resetToken VARCHAR(255),
  resetTokenExpiry DATETIME,
  totpSecret VARCHAR(255),
  isTotpEnabled TINYINT(1) DEFAULT 0,
  magicLinkToken VARCHAR(255),
  magicLinkTokenExpiry DATETIME,
  smsCode VARCHAR(10),
  smsCodeExpiry DATETIME,
  isEmailVerified TINYINT(1) DEFAULT 0,
  phoneNumber VARCHAR(20),
  createdAt DATETIME DEFAULT CURRENT_TIMESTAMP
);
```

### Related

- [Database-agnostic auth with IUserStore](/docs/database) — the interface this store implements
- [PostgreSQL authentication store](/docs/database/postgresql) — the other SQL adapter
- [Authentication on top of PHP-CRUD-API](/docs/database/php-crud-api) — reach MySQL over REST instead of SQL
- [Extending BaseUser and auth interfaces](/docs/advanced/extending-interfaces) — add your own columns safely

---

## MongoDB Authentication Store for Node.js

## MongoDB

### Install

```bash
npm install mongodb
```

### Setup

```typescript
import { MongoClient } from 'mongodb';
import { MongoDbUserStore } from './examples/mongodb-user-store.example';

const client = new MongoClient(process.env.MONGODB_URI!);
await client.connect();

const userStore = new MongoDbUserStore(client.db('myapp'));
await userStore.init(); // creates indexes automatically
const auth = new AuthConfigurator(config, userStore);
```

### Collection Schema

```typescript
interface UserDocument {
  _id: string;         // same as BaseUser.id
  email: string;
  password?: string;
  name?: string;
  role: string;
  loginProvider: string;
  providerAccountId?: string;
  refreshToken?: string | null;
  refreshTokenExpiry?: Date | null;
  resetToken?: string | null;
  resetTokenExpiry?: Date | null;
  totpSecret?: string | null;
  isTotpEnabled: boolean;
  magicLinkToken?: string | null;
  magicLinkTokenExpiry?: Date | null;
  smsCode?: string | null;
  smsCodeExpiry?: Date | null;
  isEmailVerified: boolean;
  phoneNumber?: string;
  createdAt: Date;
}
```

### Indexes

The `init()` method creates:
- Unique index on `email`
- Index on `refreshToken`
- Index on `resetToken`
- Index on `magicLinkToken`

### Related

- [Database-agnostic auth with IUserStore](/docs/database) — the interface this store implements
- [PostgreSQL authentication store](/docs/database/postgresql) — the SQL counterpart of this adapter
- [User metadata without schema changes](/docs/advanced/user-metadata) — store extra fields per user
- [Extending BaseUser and auth interfaces](/docs/advanced/extending-interfaces) — type-safe custom documents

---

## PostgreSQL Authentication Store (node-postgres)

## PostgreSQL with pg

### Install

```bash
npm install pg
npm install -D @types/pg
```

### Setup

```typescript
import { Pool } from 'pg';
import { IUserStore, BaseUser } from '@awesome-lang-auth/node';

const pool = new Pool({ connectionString: process.env.DATABASE_URL });

export class PgUserStore implements IUserStore {
  async findByEmail(email: string): Promise<BaseUser | null> {
    const { rows } = await pool.query(
      'SELECT * FROM users WHERE email = $1',
      [email]
    );
    return rows[0] ?? null;
  }

  async findById(id: string): Promise<BaseUser | null> {
    const { rows } = await pool.query(
      'SELECT * FROM users WHERE id = $1',
      [id]
    );
    return rows[0] ?? null;
  }

  async create(data: Partial<BaseUser>): Promise<BaseUser> {
    const { rows } = await pool.query(
      `INSERT INTO users (id, email, password, name, role, login_provider)
       VALUES ($1, $2, $3, $4, $5, $6) RETURNING *`,
      [crypto.randomUUID(), data.email, data.password, data.name, data.role ?? 'user', data.loginProvider ?? 'local']
    );
    return rows[0];
  }

  async updateRefreshToken(userId: string, token: string | null, expiry: Date | null): Promise<void> {
    await pool.query(
      'UPDATE users SET refresh_token = $1, refresh_token_expiry = $2 WHERE id = $3',
      [token, expiry, userId]
    );
  }

  // ... implement remaining methods
}
```

### Schema

```sql
CREATE TABLE users (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  email VARCHAR(255) UNIQUE NOT NULL,
  password VARCHAR(255),
  name VARCHAR(255),
  role VARCHAR(50) DEFAULT 'user',
  login_provider VARCHAR(50) DEFAULT 'local',
  provider_account_id VARCHAR(255),
  refresh_token TEXT,
  refresh_token_expiry TIMESTAMPTZ,
  reset_token VARCHAR(255),
  reset_token_expiry TIMESTAMPTZ,
  totp_secret VARCHAR(255),
  is_totp_enabled BOOLEAN DEFAULT false,
  magic_link_token VARCHAR(255),
  magic_link_token_expiry TIMESTAMPTZ,
  sms_code VARCHAR(10),
  sms_code_expiry TIMESTAMPTZ,
  is_email_verified BOOLEAN DEFAULT false,
  phone_number VARCHAR(20),
  created_at TIMESTAMPTZ DEFAULT NOW()
);
```

### Related

- [Database-agnostic auth with IUserStore](/docs/database) — the interface this store implements
- [Authentication on top of PostgREST](/docs/database/postgrest) — same database, no raw SQL
- [MySQL and MariaDB authentication store](/docs/database/mysql) — the other SQL adapter
- [Session management and token revocation](/docs/advanced/sessions) — persist sessions alongside users

---

## Authentication on Top of PostgREST (No Raw SQL)

## PostgREST Integration

You don't need to write raw SQL to use `node-auth`. Because the library is entirely database-agnostic through the `IUserStore` interface, you can implement your storage layer using RESTful APIs like [PostgREST](https://postgrest.org/) (the engine behind Supabase).

This approach allows you to keep your database tightly secured behind PostgREST's API layer while `node-auth` handles the complex JWT flows, session management, and OAuth integrations.

### IUserStore Implementation

Below is a complete example of how to implement the `IUserStore` interface using the native `fetch` API against a PostgREST server.

```typescript
import { IUserStore, BaseUser } from '@awesome-lang-auth/node';

export class PostgRestUserStore implements IUserStore {
  constructor(
    private readonly apiUrl: string,
    private readonly serviceKey: string // API key with bypass-RLS permissions
  ) {}

  private get headers() {
    return {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${this.serviceKey}`,
      'Prefer': 'return=representation'
    };
  }

  // ---- Core CRUD -----------------------------------------------------------

  async findByEmail(email: string): Promise<BaseUser | null> {
    const res = await fetch(`${this.apiUrl}/users?email=eq.${encodeURIComponent(email)}`, {
      method: 'GET',
      headers: this.headers,
    });
    const users = await res.json();
    return users[0] || null;
  }

  async findById(id: string): Promise<BaseUser | null> {
    const res = await fetch(`${this.apiUrl}/users?id=eq.${encodeURIComponent(id)}`, {
      method: 'GET',
      headers: this.headers,
    });
    const users = await res.json();
    return users[0] || null;
  }

  async create(data: Partial<BaseUser>): Promise<BaseUser> {
    const res = await fetch(`${this.apiUrl}/users`, {
      method: 'POST',
      headers: this.headers,
      body: JSON.stringify(data),
    });
    
    if (!res.ok) {
      throw new Error(`Failed to create user: ${await res.text()}`);
    }

    const users = await res.json();
    return users[0];
  }

  // ---- Token field updates ------------------------------------------------

  private async updateField(userId: string, updates: Partial<BaseUser>): Promise<void> {
    const res = await fetch(`${this.apiUrl}/users?id=eq.${encodeURIComponent(userId)}`, {
      method: 'PATCH',
      headers: this.headers,
      body: JSON.stringify(updates),
    });

    if (!res.ok) {
      throw new Error(`Failed to update user: ${await res.text()}`);
    }
  }

  async updateRefreshToken(userId: string, token: string | null, expiry: Date | null): Promise<void> {
    await this.updateField(userId, { refreshToken: token, refreshTokenExpiry: expiry });
  }

  async updateResetToken(userId: string, token: string | null, expiry: Date | null): Promise<void> {
    await this.updateField(userId, { resetToken: token, resetTokenExpiry: expiry });
  }

  async updatePassword(userId: string, hashedPassword: string): Promise<void> {
    await this.updateField(userId, { password: hashedPassword });
  }

  async updateTotpSecret(userId: string, secret: string | null): Promise<void> {
    await this.updateField(userId, { totpSecret: secret, isTotpEnabled: !!secret });
  }

  async updateMagicLinkToken(userId: string, token: string | null, expiry: Date | null): Promise<void> {
    await this.updateField(userId, { magicLinkToken: token, magicLinkTokenExpiry: expiry });
  }

  async updateSmsCode(userId: string, code: string | null, expiry: Date | null): Promise<void> {
    await this.updateField(userId, { smsCode: code, smsCodeExpiry: expiry });
  }

  // ---- Optional finders ---------------------------------------------------

  async findByResetToken(token: string): Promise<BaseUser | null> {
    const res = await fetch(`${this.apiUrl}/users?resetToken=eq.${encodeURIComponent(token)}`, {
      method: 'GET',
      headers: this.headers,
    });
    const users = await res.json();
    return users[0] || null;
  }

  async findByMagicLinkToken(token: string): Promise<BaseUser | null> {
    const res = await fetch(`${this.apiUrl}/users?magicLinkToken=eq.${encodeURIComponent(token)}`, {
      method: 'GET',
      headers: this.headers,
    });
    const users = await res.json();
    return users[0] || null;
  }

  async findByProviderAccount(provider: string, providerAccountId: string): Promise<BaseUser | null> {
    const res = await fetch(`${this.apiUrl}/users?loginProvider=eq.${encodeURIComponent(provider)}&providerAccountId=eq.${encodeURIComponent(providerAccountId)}`, {
      method: 'GET',
      headers: this.headers,
    });
    const users = await res.json();
    return users[0] || null;
  }
}
```

### Setup

1. Make sure your PostgREST instance exposes a `users` table or view that matches the `BaseUser` interface.
2. Initialize the store in your application:

```typescript
import { AuthConfigurator } from '@awesome-lang-auth/node';
import { PostgRestUserStore } from './postgrest-user-store';

const userStore = new PostgRestUserStore(
  'http://localhost:3000', // URL to PostgREST
  process.env.POSTGREST_SERVICE_KEY!
);

const auth = new AuthConfigurator(config, userStore);
```

### Related

- [PostgreSQL authentication store](/docs/database/postgresql) — the direct-SQL alternative
- [Authentication on top of PHP-CRUD-API](/docs/database/php-crud-api) — the same pattern for MySQL and SQL Server
- [Database-agnostic auth with IUserStore](/docs/database) — the interface a REST store implements
- [Extending BaseUser and auth interfaces](/docs/advanced/extending-interfaces) — type your REST payloads

---

## Authentication on Top of PHP-CRUD-API

## PHP-CRUD-API Integration

Just like PostgREST, you don't need to write raw SQL to use `node-auth`. The `IUserStore` interface allows you to implement your storage layer using RESTful APIs like [PHP-CRUD-API](https://github.com/mevdschee/php-crud-api).

This approach allows you to deploy a lightweight, zero-configuration API layer over your MySQL, PostgreSQL, or SQL Server database, while `node-auth` handles the complex authentication, cryptography, and OAuth integrations.

### IUserStore Implementation

Below is a complete example of how to implement the `IUserStore` interface using the native `fetch` API against a PHP-CRUD-API backend.

> **Note:** PHP-CRUD-API uses a query parameter format like `?filter=field,eq,value` for filtering and returns the actual record in the body. Ensure your table structure matches `BaseUser`.

```typescript
import { IUserStore, BaseUser } from '@awesome-lang-auth/node';

export class PhpCrudApiUserStore implements IUserStore {
  constructor(
    private readonly apiUrl: string, // e.g., 'http://localhost/api.php/records/'
  ) {}

  private get headers() {
    return {
      'Content-Type': 'application/json',
      // 'X-API-Key': 'your-secret-key-if-configured'
    };
  }

  // ---- Core CRUD -----------------------------------------------------------

  async findByEmail(email: string): Promise<BaseUser | null> {
    const res = await fetch(`${this.apiUrl}users?filter=email,eq,${encodeURIComponent(email)}`, {
      method: 'GET',
      headers: this.headers,
    });
    const data = await res.json();
    return data.records?.[0] || null;
  }

  async findById(id: string): Promise<BaseUser | null> {
    const res = await fetch(`${this.apiUrl}users/${encodeURIComponent(id)}`, {
      method: 'GET',
      headers: this.headers,
    });
    
    if (res.status === 404) return null;
    return await res.json();
  }

  async create(data: Partial<BaseUser>): Promise<BaseUser> {
    const res = await fetch(`${this.apiUrl}users`, {
      method: 'POST',
      headers: this.headers,
      body: JSON.stringify(data),
    });
    
    if (!res.ok) {
      throw new Error(`Failed to create user: ${await res.text()}`);
    }

    // PHP-CRUD-API returns the ID of the new record (usually an integer, depending on your DB)
    const newId = await res.json();
    
    // Fetch the complete created user to satisfy the interface
    const createdUserRes = await fetch(`${this.apiUrl}users/${newId}`, {
      method: 'GET',
      headers: this.headers
    });
    return await createdUserRes.json();
  }

  // ---- Token field updates ------------------------------------------------

  private async updateField(userId: string, updates: Partial<BaseUser>): Promise<void> {
    const res = await fetch(`${this.apiUrl}users/${encodeURIComponent(userId)}`, {
      method: 'PUT',
      headers: this.headers,
      body: JSON.stringify(updates),
    });

    if (!res.ok) {
      throw new Error(`Failed to update user: ${await res.text()}`);
    }
  }

  async updateRefreshToken(userId: string, token: string | null, expiry: Date | null): Promise<void> {
    await this.updateField(userId, { refreshToken: token, refreshTokenExpiry: expiry });
  }

  async updateResetToken(userId: string, token: string | null, expiry: Date | null): Promise<void> {
    await this.updateField(userId, { resetToken: token, resetTokenExpiry: expiry });
  }

  async updatePassword(userId: string, hashedPassword: string): Promise<void> {
    await this.updateField(userId, { password: hashedPassword });
  }

  async updateTotpSecret(userId: string, secret: string | null): Promise<void> {
    await this.updateField(userId, { totpSecret: secret, isTotpEnabled: !!secret });
  }

  async updateMagicLinkToken(userId: string, token: string | null, expiry: Date | null): Promise<void> {
    await this.updateField(userId, { magicLinkToken: token, magicLinkTokenExpiry: expiry });
  }

  async updateSmsCode(userId: string, code: string | null, expiry: Date | null): Promise<void> {
    await this.updateField(userId, { smsCode: code, smsCodeExpiry: expiry });
  }

  // ---- Optional finders ---------------------------------------------------

  async findByResetToken(token: string): Promise<BaseUser | null> {
    const res = await fetch(`${this.apiUrl}users?filter=resetToken,eq,${encodeURIComponent(token)}`, {
      method: 'GET',
      headers: this.headers,
    });
    const data = await res.json();
    return data.records?.[0] || null;
  }

  async findByMagicLinkToken(token: string): Promise<BaseUser | null> {
    const res = await fetch(`${this.apiUrl}users?filter=magicLinkToken,eq,${encodeURIComponent(token)}`, {
      method: 'GET',
      headers: this.headers,
    });
    const data = await res.json();
    return data.records?.[0] || null;
  }

  async findByProviderAccount(provider: string, providerAccountId: string): Promise<BaseUser | null> {
    const res = await fetch(`${this.apiUrl}users?filter=loginProvider,eq,${encodeURIComponent(provider)}&filter=providerAccountId,eq,${encodeURIComponent(providerAccountId)}`, {
      method: 'GET',
      headers: this.headers,
    });
    const data = await res.json();
    return data.records?.[0] || null;
  }
}
```

### Setup

1. Make sure your PHP-CRUD-API backend is running and exposes a `users` table that matches the `BaseUser` properties.
2. Initialize the store in your Node.js application:

```typescript
import { AuthConfigurator } from '@awesome-lang-auth/node';
import { PhpCrudApiUserStore } from './php-crud-api-user-store';

const userStore = new PhpCrudApiUserStore(
  'http://localhost:8080/api.php/records/'
);

const auth = new AuthConfigurator(config, userStore);
```

### Related

- [Authentication on top of PostgREST](/docs/database/postgrest) — the same pattern for PostgreSQL
- [MySQL and MariaDB authentication store](/docs/database/mysql) — talk to MySQL directly instead
- [Database-agnostic auth with IUserStore](/docs/database) — the interface a REST store implements
- [Extending BaseUser and auth interfaces](/docs/advanced/extending-interfaces) — type your REST payloads

---

## API Reference: Auth, Admin and Tools Routers

## API Reference

**node-auth** is a 360-degree communication and access control layer that exposes its functionality through **three core routers**. You can mount any combination of these routers depending on your application's needs.

### 1. Auth Router (Default: `/auth`)
Handles all user-facing authentication flows (login, registration, password resets, 2FA, OAuth, etc).

### 2. Tools Router (Default: `/tools`)
Handles machine-to-machine communication, telemetry, Server-Sent Events (SSE), and inbound/outgoing dynamic webhooks. See [Tools Router Endpoints](/docs/advanced/swagger#tools-router-endpoints) for the full list.

### 3. Admin Router (Default: `/admin/api`)
Provides a secure REST API (and a built-in UI) for administrative tasks like user management, role assignments, UI webhooks, settings, and session revocation. See [Admin REST API](/docs/advanced/admin#rest-api-reference) for the full list.

---

### Auth Router Endpoints Overview

| Method | Path | Description | Auth Required |
|--------|------|-------------|---------------|
| `POST` | `/auth/login` | Email/password login | ❌ |
| `POST` | `/auth/register` | Register new user (requires `onRegister`) | ❌ |
| `POST` | `/auth/logout` | Log out | ✅ |
| `POST` | `/auth/refresh` | Refresh tokens | ❌ (refresh token) |
| `GET` | `/auth/me` | Get current user profile | ✅ |
| `POST` | `/auth/forgot-password` | Request password reset | ❌ |
| `POST` | `/auth/reset-password` | Reset with token | ❌ |
| `POST` | `/auth/change-password` | Change password | ✅ |
| `POST` | `/auth/send-verification-email` | Send email verification | ✅ |
| `GET` | `/auth/verify-email` | Verify email token | ❌ |
| `POST` | `/auth/change-email/request` | Request email change | ✅ |
| `POST` | `/auth/change-email/confirm` | Confirm email change | ❌ |
| `POST` | `/auth/magic-link/send` | Send magic link | ❌ |
| `POST` | `/auth/magic-link/verify` | Verify magic link | ❌ |
| `POST` | `/auth/sms/send` | Send SMS OTP | ❌ |
| `POST` | `/auth/sms/verify` | Verify SMS OTP | ❌ |
| `POST` | `/auth/2fa/setup` | Get TOTP secret + QR code | ✅ |
| `POST` | `/auth/2fa/verify-setup` | Activate TOTP | ✅ |
| `POST` | `/auth/2fa/verify` | Complete 2FA login | ❌ (temp token) |
| `POST` | `/auth/2fa/disable` | Disable 2FA | ✅ |
| `GET` | `/auth/oauth/:provider` | OAuth redirect | ❌ |
| `GET` | `/auth/oauth/:provider/callback` | OAuth callback | ❌ |
| `POST` | `/auth/sessions/cleanup` | Delete expired sessions | ❌ |
| `GET` | `/auth/linked-accounts` | List linked OAuth accounts | ✅ |
| `DELETE` | `/auth/linked-accounts/:provider/:id` | Unlink OAuth account | ✅ |
| `POST` | `/auth/link-request` | Link new email address | ✅ |
| `POST` | `/auth/link-verify` | Confirm account link | ❌ |
| `DELETE` | `/auth/account` | Delete account | ✅ |

See [Endpoints](/docs/api-reference/endpoints) for full request/response documentation.

### Related

- [Auth API endpoints reference](/docs/api-reference/endpoints) — request and response bodies for every route
- [ITemplateStore: custom emails and UI i18n](/docs/api-reference/template-store) — override transactional emails and UI strings
- [Swagger UI and OpenAPI 3.0 spec](/docs/advanced/swagger) — the machine-readable version of this reference
- [Built-in admin panel](/docs/advanced/admin) — the admin router's own REST API

---

## Auth API Endpoints Reference

## Endpoint Reference

This page documents the endpoints exposed by the **Auth Router** (typically mounted at `/auth`). 
For the other parts of the 360-degree layer, see:
- **Tools Router** (SSE, Webhooks, Telemetry): [Tools Router Endpoints](/docs/advanced/swagger#tools-router-endpoints)
- **Admin Router** (User, Role, and Tenant management): [Admin REST API](/docs/advanced/admin#rest-api-reference)
- **API Keys**: [API Keys Guide](/docs/advanced/api-keys)

:::info Authentication
Protected endpoints require either a valid `accessToken` **HttpOnly cookie** (set automatically on login) or an `Authorization: Bearer <accessToken>` header.
:::

:::info Token delivery
By default, token-issuing endpoints (`/login`, `/refresh`, `/2fa/verify`, `/magic-link/verify`, `/sms/verify`) set **HttpOnly cookies** and return `{ "success": true }`. To receive tokens in the JSON response body instead (for native/mobile clients), add the `X-Auth-Strategy: bearer` request header. See [Bearer Token Mode](/docs/advanced/bearer-token) for details.
:::

---

### Authentication

#### `POST` /auth/login

**Request body:**
```json
{ "email": "user@example.com", "password": "secret" }
```

**Response `200` (cookie mode — default):**
```json
{ "success": true }
```
HttpOnly cookies `accessToken`, `refreshToken` (and `csrf-token` if CSRF is enabled) are set automatically.

**Response `200` (bearer mode — `X-Auth-Strategy: bearer`):**
```json
{ "success": true, "accessToken": "eyJ...", "refreshToken": "eyJ..." }
```

**Response `200` (2FA required):**
```json
{ "requiresTwoFactor": true, "tempToken": "eyJ...", "available2faMethods": ["totp", "sms"] }
```

---

#### `POST` /auth/register

Requires `onRegister` callback in router options.

**Request body:**
```json
{ "email": "user@example.com", "password": "secret", "name": "Jane" }
```

**Response `201`:**
```json
{ "success": true, "userId": "123" }
```

---

#### `POST` /auth/logout

Clears the refresh token server-side. Requires valid access token (cookie or bearer).

**Response `200`:**
```json
{ "success": true }
```

---

#### `POST` /auth/refresh

Uses the refresh token (from HttpOnly cookie or from `refreshToken` in request body) to issue new tokens.

**Response `200` (cookie mode — default):**
```json
{ "success": true }
```
New `accessToken` and `refreshToken` cookies are set automatically.

**Response `200` (bearer mode — `X-Auth-Strategy: bearer`):**
```json
{ "success": true, "accessToken": "eyJ...", "refreshToken": "eyJ..." }
```

---

#### `GET` /auth/me

Returns the current user's full profile. Requires authentication.

**Response `200`:**
```json
{
  "sub": "123",
  "email": "user@example.com",
  "role": "user",
  "loginProvider": "local",
  "isEmailVerified": true,
  "isTotpEnabled": false,
  "metadata": { "theme": "dark" },
  "roles": ["editor"],
  "permissions": ["posts:read", "posts:write"]
}
```

---

### Password Management

#### `POST` /auth/forgot-password

**Request body:**
```json
{ "email": "user@example.com" }
```

#### `POST` /auth/reset-password

**Request body:**
```json
{ "token": "reset-token-from-email", "newPassword": "newpassword123" }
```

#### `POST` /auth/change-password

Requires authentication.

**Request body:**
```json
{ "currentPassword": "old", "newPassword": "new" }
```

---

### Email Verification

#### `POST` /auth/send-verification-email

Sends a verification email to the authenticated user. Requires authentication.

#### `GET` /auth/verify-email?token=...

Verifies the email token from the link. Redirects on success.

---

### Email Change

#### `POST` /auth/change-email/request

Sends a confirmation email to the new address. Requires authentication.

**Request body:**
```json
{ "newEmail": "newemail@example.com" }
```

#### `POST` /auth/change-email/confirm

Confirms the email change using the token from the confirmation email.

**Request body:**
```json
{ "token": "token-from-email" }
```

---

### Magic Link

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/auth/magic-link/send` | Request magic link. Body: `{ email }` for login; `{ tempToken, mode: '2fa' }` for 2FA second factor |
| `POST` | `/auth/magic-link/verify` | Verify token → set session cookies (or return tokens in bearer mode). Body: `{ token, mode?, tempToken? }` |

---

### SMS OTP

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/auth/sms/send` | Send OTP. Body: `{ email }` or `{ userId }` for login; `{ tempToken, mode: '2fa' }` for 2FA |
| `POST` | `/auth/sms/verify` | Verify OTP → set session cookies (or return tokens in bearer mode). Body: `{ userId, code }` for login; `{ tempToken, code, mode: '2fa' }` for 2FA |

---

### TOTP (Two-Factor Authentication)

| Method | Path | Auth | Description |
|--------|------|:----:|-------------|
| `POST` | `/auth/2fa/setup` | ✅ | Generate TOTP secret and QR code data URI |
| `POST` | `/auth/2fa/verify-setup` | ✅ | Confirm TOTP enrollment. Body: `{ token, secret }` |
| `POST` | `/auth/2fa/verify` | — (temp token) | Complete 2FA login. Body: `{ tempToken, totpCode }` |
| `POST` | `/auth/2fa/disable` | ✅ | Disable TOTP for the current user |

---

### OAuth

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/auth/oauth/:provider` | Redirect to provider |
| `GET` | `/auth/oauth/:provider/callback` | Handle OAuth callback |

---

### Sessions

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/auth/sessions/cleanup` | Delete expired sessions (requires `sessionStore.deleteExpiredSessions`) |

Active session listing and per-session revocation are available through the [Admin Panel](/docs/advanced/admin) at `/admin/api/sessions`.

---

### Account Linking

| Method | Path | Auth | Description |
|--------|------|:----:|-------------|
| `GET` | `/auth/linked-accounts` | ✅ | List linked OAuth accounts for the current user |
| `DELETE` | `/auth/linked-accounts/:provider/:id` | ✅ | Unlink an OAuth account |
| `POST` | `/auth/link-request` | ✅ | Request to link a new email address (sends verification email) |
| `POST` | `/auth/link-verify` | ❌ | Complete linking using token from email |

---

### Account

#### `DELETE` /auth/account

Deletes the authenticated user's account and all associated data.

---

## ITemplateStore: Custom Emails and UI i18n

## ITemplateStore

`ITemplateStore` is the optional interface that powers the **dynamic email template** and **UI i18n** systems in awesome-node-auth. Implement it against your database to:

- Override any built-in transactional email (password reset, magic link, welcome, etc.) with custom HTML/text and per-language translations
- Inject page-specific UI translation strings into the built-in login/register pages at render time

---

### Types

#### `MailTemplate`

```typescript
export interface MailTemplate {
  /** Template identifier. Built-in IDs: 'magic-link' | 'password-reset' | 'verify-email' | 'welcome' | 'email-changed' | 'invitation' */
  id: string;

  /** HTML body. Use {{T.key}} for translated strings and {{VAR}} for data variables. Leave empty to use the built-in fallback template. */
  baseHtml: string;

  /** Plain-text fallback body. Same placeholder syntax. Leave empty to use the built-in fallback template. */
  baseText: string;

  /** Per-language translation map: lang → { key: value } */
  translations: Record<string, Record<string, string>>;
}
```

#### `UiTranslation`

```typescript
export interface UiTranslation {
  /** Page identifier. Built-in pages: 'login' | 'register' | 'forgot-password' | 'reset-password' | 'magic-link' | 'verify-email' | '2fa' | 'link-verify' | 'account-conflict' */
  page: string;

  /** Per-language translation map: lang → { data-i18n-key: text } */
  translations: Record<string, Record<string, string>>;
}
```

---

### Interface definition

```typescript
export interface ITemplateStore {
  /** Retrieve a mail template by ID. Returns null if not found (built-in fallback is used). */
  getMailTemplate(id: string): Promise<MailTemplate | null>;

  /** List all stored mail templates. */
  listMailTemplates(): Promise<MailTemplate[]>;

  /** Create or update a mail template. */
  updateMailTemplate(id: string, template: Partial<MailTemplate>): Promise<void>;

  /** Retrieve UI translations for a specific page. Returns null if not found. */
  getUiTranslations(page: string): Promise<UiTranslation | null>;

  /** List all stored UI translation sets. */
  listUiTranslations(): Promise<UiTranslation[]>;

  /** Create or update UI translations for a page. */
  updateUiTranslations(page: string, translations: Record<string, Record<string, string>>): Promise<void>;
}
```

---

### Built-in implementation

`MemoryTemplateStore` is a zero-dependency in-memory implementation ready for development and testing:

```typescript
import { MemoryTemplateStore } from '@awesome-lang-auth/node';

const templateStore = new MemoryTemplateStore();
```

Replace it with a database-backed implementation in production (see [Mailer → Dynamic templates](/docs/advanced/mailer#dynamic-templates-with-itemplatestore)).

---

### Wiring

Pass `templateStore` to **both** `AuthConfigurator` and `createAdminRouter`:

```typescript
import { AuthConfigurator, createAdminRouter, MemoryTemplateStore, buildUiRouter } from '@awesome-lang-auth/node';

const templateStore = new MemoryTemplateStore();

const auth = new AuthConfigurator(
  {
    // ... JWT secrets & mailer config ...
    templateStore,   // ← enables dynamic email templates
  },
  userStore,
);

// (optional) Enable i18n injection into built-in UI pages
app.use('/auth/ui', buildUiRouter({
  authConfig,
  apiPrefix:     '/auth',
  templateStore,
}));

// (optional) Enable the 📧 Email & UI tab in the Admin Panel
app.use('/admin', createAdminRouter(userStore, {
  accessPolicy: 'first-user',
  jwtSecret: process.env.ACCESS_TOKEN_SECRET!,
  templateStore,
}));
```

---

### Interpolation reference

#### Email templates

| Syntax | Source | Example output |
|--------|--------|----------------|
| `{{T.key}}` | `MailTemplate.translations[lang][key]` | `"Reset your password"` |
| `{{link}}` | Reset / magic-link / verify URL | `"https://app.com/reset?token=…"` |
| `{{token}}` | Raw token (rarely needed in template HTML) | `"abc123…"` |
| `{{newEmail}}` | New email address (`email-changed` template) | `"new@example.com"` |
| `{{loginUrl}}` | Login page URL (`welcome` template) | `"https://app.com/login"` |
| `{{tempPassword}}` | Temporary password (`welcome` template, admin-created users) | `"Tmp@1234"` |

A missing key renders as `[key]` to help with debugging.

> **Reset to default:** save a template with empty `baseHtml` and `baseText` (or use the
> "Reset to default" button in the admin panel) and `MailerService` will automatically fall
> back to the built-in template for that ID.

#### UI translations

Each `data-i18n` attribute value on a built-in HTML element is looked up in `UiTranslation.translations[lang]`. The key must exactly match the attribute value:

```html
<h2 data-i18n="title">Sign in</h2>
<!-- resolved by: translations["en"]["title"] → "Sign in" -->
```

---

### Admin REST API

When `templateStore` is provided to `createAdminRouter`, the following endpoints are activated:

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/admin/api/templates/mail` | List all mail templates |
| `POST` | `/admin/api/templates/mail` | Create or update a mail template (body: `{ id, baseHtml, baseText, translations }`) |
| `GET` | `/admin/api/templates/ui` | List all UI translation sets |
| `POST` | `/admin/api/templates/ui` | Create or update UI translations (body: `{ page, translations }`) |

---

## Advanced Authentication Features

## Advanced Features

`awesome-node-auth` provides optional interfaces and hooks for advanced functionality. Every feature is opt-in — only configure what you need.

| Feature | Guide | Description |
|---------|-------|-------------|
| [Sessions](/docs/advanced/sessions) | `ISessionStore` | External persistence for auditing and admin-level revocation |
| [IdP Mode](/docs/advanced/idp-mode) | `IdProviderConfig` | RS256-signed JWTs + JWKS endpoint — act as a central Identity Provider |
| [Roles & Permissions](/docs/advanced/roles-permissions) | `IRolesPermissionsStore` | RBAC — assign roles, permissions, tenant-scoped |
| [Multi-Tenancy](/docs/advanced/multi-tenancy) | `ITenantStore` | Tenant CRUD, user↔tenant association |
| [CSRF Protection](/docs/advanced/csrf) | `AuthConfig.csrf` | Double-submit cookie pattern |
| [User Metadata](/docs/advanced/user-metadata) | `IUserMetadataStore` | Arbitrary per-user key/value data |
| [Account Linking](/docs/advanced/account-linking) | `ILinkedAccountsStore` | Link multiple OAuth providers to one account |
| [Admin Panel](/docs/advanced/admin) | `createAdminRouter()` | Built-in admin dashboard (HTML UI + REST API) |
| [Dynamic Inbound Webhooks](/docs/advanced/webhooks#dynamic-inbound-execution) | `@webhookAction`, `ActionRegistry`, `node:vm` | Govern and execute JS scripts on inbound webhooks via the admin UI; scripts run with the server's privileges, so only trusted operators may write them |
| [Bearer Token](/docs/advanced/bearer-token) | — | Mobile/native clients: token storage, interceptors |
| [Mailer (HTTP)](/docs/advanced/mailer) | `MailerConfig` | Built-in HTTP email transport with bilingual templates |
| [Email Verification](/docs/advanced/email-verification) | `emailVerificationMode` | `none` / `lazy` / `strict` verification enforcement |
| [Change Email](/docs/advanced/change-email) | — | Two-step email address change with confirmation link |
| [Account Deletion](/docs/advanced/account-deletion) | — | `DELETE /auth/account` + tenant cleanup |
| [Custom JWT Claims](/docs/advanced/custom-claims) | `buildTokenPayload` | Embed tenant IDs, permissions, feature flags in JWT |
| [AuthEventBus](/docs/advanced/auth-event-bus) | `AuthEventBus` | Central event bus — subscribe to 26 standardised identity events |
| [API Keys](/docs/advanced/api-keys) | `ApiKeyService`, `IApiKeyStore` | Machine-to-machine API key authentication with bcrypt hashing |
| [AuthTools](/docs/advanced/auth-tools) | `AuthTools` | Unified entry point for telemetry, SSE, and webhooks |
| [SSE](/docs/advanced/sse) | `SseManager` | Real-time Server-Sent Events streaming by topic |
| [Scaling SSE](/docs/advanced/sse-scaling) | Redis pub/sub adapter | Broadcast SSE events across multiple instances or a Kubernetes cluster |
| [Real-time Decorators](/docs/advanced/sse-notify-decorator) | `@sseNotify` | Fire real-time notifications from any service or store method |
| [Webhooks](/docs/advanced/webhooks) | `WebhookSender`, `IWebhookStore` | Outgoing webhooks with HMAC signing and retry |
| [Telemetry](/docs/advanced/telemetry) | `ITelemetryStore` | Persist and query identity events |
| [Swagger / OpenAPI](/docs/advanced/swagger) | `createToolsRouter()` | Auto-generated OpenAPI 3.0 spec + Swagger UI |
| [Browser Client](/docs/advanced/browser-client) | `window.AwesomeNodeAuth` | Zero-config JS client shipped as `auth.js` — CSRF, auto-refresh, guards, all auth methods |
| [Built-in UI](/docs/advanced/built-in-ui) | `buildUiRouter()` | Server-rendered login/register pages — activation, CSS variables, full customization guide |
| [CORS & Dynamic siteUrl](/docs/advanced/cors) | `AuthConfig.cors` | Cross-domain setups and per-caller `siteUrl` resolution for emails and redirects |
| [Extending Interfaces](/docs/advanced/extending-interfaces) | `BaseUser`, `BaseTenant`, `Session` | Add custom fields to the base types with full TypeScript safety |

---

## Built-in Auth UI: Login Pages Without a Frontend

## Built-in UI — Activation & CSS Customization

`awesome-node-auth` ships a **zero-dependency, server-rendered HTML UI** for all authentication flows. No React, no bundler, no build step required — the server injects your theme and configuration at request time.

---

### Pages included

| Page | Path | Description |
|------|------|-------------|
| Login | `{apiPrefix}/ui/login` | Email/password + OAuth + magic link + SMS |
| Register | `{apiPrefix}/ui/register` | New account form (only when `onRegister` is set) |
| Forgot Password | `{apiPrefix}/ui/forgot-password` | Password reset request form |
| Reset Password | `{apiPrefix}/ui/reset-password` | New password form (via email token) |
| Magic Link | `{apiPrefix}/ui/magic-link` | Passwordless email login |
| Verify Email | `{apiPrefix}/ui/verify-email` | Email verification landing page |
| 2FA Challenge | `{apiPrefix}/ui/2fa` | TOTP / SMS one-time password entry |
| Link Verify | `{apiPrefix}/ui/link-verify` | OAuth account-linking confirmation |
| Account Conflict | `{apiPrefix}/ui/account-conflict` | OAuth provider/email conflict resolution |

---

### Step 1 — Install the UI router

`buildUiRouter` is separate from the auth API router. Mount both under the same prefix:

```typescript
import express from 'express';
import { AuthConfigurator, buildUiRouter } from '@awesome-lang-auth/node';
import { MyUserStore } from './my-user-store';

const app = express();
app.use(express.json());

const config: AuthConfig = {
  // ... JWT secrets & expiry
  ui: { loginUrl: '/auth/ui/login' }
};

const userStore = new MyUserStore();
const auth = new AuthConfigurator(config, userStore);

const routerOptions = {
  // onRegister, oauthStrategies, etc.
};

// 1. Mount the REST API router
app.use('/auth', auth.router(routerOptions));

// 2. Mount the UI router at the same prefix + /ui
app.use(
  '/auth/ui',
  buildUiRouter({
    authConfig:     config,
    routerOptions:  routerOptions,  // enables register/OAuth flags
    apiPrefix:      '/auth',
  })
);

app.listen(3000, () => console.log('Running on http://localhost:3000'));
```

The built-in UI is now available at:
- **`http://localhost:3000/auth/ui/login`**
- **`http://localhost:3000/auth/ui/register`**
- etc.

---

### Step 2 — Configure `AuthConfig.ui`

All UI settings live under `authConfig.ui`. Every option is optional.

```typescript
const auth = new AuthConfigurator(
  {
    // ... JWT secrets & expiry ...
    ui: {
      loginUrl:    '/auth/ui/login',
      registerUrl: '/auth/ui/register',  // default
      siteName:    'My App',
      customLogo:  'https://cdn.example.com/logo.png',
      primaryColor:   '#6366f1',  // indigo
      secondaryColor: '#64748b',
      bgColor:     '#f0f4ff',
      cardBg:      '#ffffff',
      bgImage:     'https://cdn.example.com/bg.jpg',
      // Raw CSS injected into every page — override any rule or variable
      customCss: `
        :root { --primary-color: #6366f1; }
        .auth-container { border-radius: 20px; }
      `,
    },
  },
  userStore
);
```

#### `AuthConfig.ui` options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `loginUrl` | `string` | `{apiPrefix}/ui/login` | Login page URL (used for redirects) |
| `registerUrl` | `string` | `{apiPrefix}/ui/register` | Register page URL |
| `siteName` | `string` | `'Awesome Node Auth'` | Page title and `<h1>` heading |
| `customLogo` | `string` | — | URL of a logo image (displayed above the form) |
| `primaryColor` | `string` | `#4a90d9` | Main brand colour (buttons, headings, focus rings) |
| `secondaryColor` | `string` | `#6c757d` | Secondary colour (OAuth buttons, dividers) |
| `bgColor` | `string` | `#f8fafc` | Page background colour |
| `bgImage` | `string` | — | Page background image URL (full-cover) |
| `cardBg` | `string` | `#ffffff` | Form/card background colour |
| `customCss` | `string` | — | Raw CSS injected into every page `<style>` tag |

---

### Step 3 — Dynamic settings via `ISettingsStore`

For **real-time** theme changes without restarting the server (e.g. from an admin panel), implement `ISettingsStore` and pass it to `buildUiRouter`:

```typescript
import { ISettingsStore } from '@awesome-lang-auth/node';

class MongoSettingsStore implements ISettingsStore {
  async getSettings() {
    const doc = await db.collection('settings').findOne({ key: 'ui' });
    return doc ?? {};
  }
  async updateSettings(settings: Partial<AuthSettings>) {
    await db.collection('settings').updateOne(
      { key: 'ui' },
      { $set: { ...settings, key: 'ui' } },
      { upsert: true }
    );
  }
}

app.use('/auth/ui', buildUiRouter({
  authConfig:    config,
  apiPrefix:     '/auth',
  settingsStore: new MongoSettingsStore(),
}));
```

Settings in the store **override** `authConfig.ui`. The built-in admin router's UI settings tab writes to the same `ISettingsStore`, so changes made in the admin panel appear instantly.

---

### Step 4 — Custom logo uploads

To let admins upload a custom logo, pass an `uploadDir` to `buildUiRouter`. Uploaded files are served at `{apiPrefix}/ui/assets/uploads/`:

```typescript
import path from 'path';

app.use('/auth/ui', buildUiRouter({
  authConfig: config,
  apiPrefix:  '/auth',
  uploadDir:  path.resolve(__dirname, 'uploads/logo'),
}));

// Then set logoUrl to the uploaded path:
// logoUrl: '/auth/ui/assets/uploads/logo.png'
```

---

### CSS customization reference

#### How theming works

The UI is styled with CSS custom properties (variables) defined in `:root`. When you set `primaryColor`, `bgColor`, etc. in `AuthConfig.ui` or `ISettingsStore`, the server renders an inline `<style>` block that overrides these variables **before** the stylesheet loads — eliminating any flash of unstyled content.

The `customCss` string is appended after the variable block, letting you override individual rules.

#### Full CSS variable reference

```css
:root {
  /* ── Colours ─────────────────────────────────────────── */
  --primary-color:        #4a90d9;  /* buttons, headings, focus rings */
  --primary-color-hover:  #357abd;  /* button hover state */
  --secondary-color:      #6c757d;  /* OAuth buttons, dividers */
  --secondary-color-hover:#5a6268;  /* OAuth button hover */
  --bg-color:             #f8fafc;  /* page background */
  --bg-image:             none;     /* background image (url("…")) */
  --card-bg:              #ffffff;  /* form card background */
  --text-color:           #1e293b;  /* primary text */
  --text-muted:           #64748b;  /* secondary/label text */
  --error-color:          #ef4444;  /* error alerts */
  --success-color:        #22c55e;  /* success alerts */
  --border-color:         #e2e8f0;  /* input borders, dividers */
  --input-focus:          #4a90d9;  /* input focus ring (same as primary by default) */
}
```

#### Overriding variables only — the minimal approach

```typescript
ui: {
  primaryColor: '#6366f1',  // only changes --primary-color + --input-focus
}
```

#### Full CSS override via `customCss`

```typescript
ui: {
  customCss: `
    /* Override variables */
    :root {
      --primary-color:        #8b5cf6;
      --primary-color-hover:  #7c3aed;
      --bg-color:             #0f0f13;
      --card-bg:              #1a1a2e;
      --text-color:           #e2e8f0;
      --text-muted:           #94a3b8;
      --border-color:         #334155;
    }

    /* Override component rules */
    .auth-container {
      border-radius: 20px;
      box-shadow: 0 25px 50px rgba(0, 0, 0, 0.5);
    }

    h1 { font-size: 28px; }
    h2 { font-size: 14px; letter-spacing: 0.1em; text-transform: uppercase; }

    button[type="submit"] {
      border-radius: 8px;
      letter-spacing: 0.05em;
    }

    input {
      background: var(--card-bg);
      color: var(--text-color);
    }
  `,
}
```

#### Dark mode example

```typescript
ui: {
  bgColor:     '#0f172a',
  cardBg:      '#1e293b',
  customCss: `
    :root {
      --bg-color:     #0f172a;
      --card-bg:      #1e293b;
      --text-color:   #f1f5f9;
      --text-muted:   #94a3b8;
      --border-color: #334155;
    }
    input { background: #0f172a; color: #f1f5f9; }
    label { color: #cbd5e1; }
  `,
}
```

#### CSS class reference

| Selector | Element | Notes |
|----------|---------|-------|
| `.auth-container` | Form card | Controls max-width (400px default), padding, border-radius |
| `.logo` | Logo `<img>` | Hidden if no `logoUrl` is set |
| `.site-name` | `<h1>` | Site name heading (set via `siteName`) |
| `h2` | Sub-heading | "Login", "Register", etc. |
| `.alert` | Alert box | Base styles |
| `.alert-error` | Error alert | Red background |
| `.alert-success` | Success alert | Green background |
| `.form-group` | Field container | `<label>` + `<input>` wrapper |
| `input` | All form inputs | Includes email, password, OTP fields |
| `button[type="submit"]` | Primary action button | Coloured by `--primary-color` |
| `.btn-social` | OAuth buttons | Google, GitHub |
| `.divider` | "or" separator | Between form and OAuth buttons |
| `.footer-links` | Bottom link area | "Forgot password?", "Sign up" |

---

### Step 5 — Custom assets directory

For complete control, replace all built-in HTML pages with your own by pointing `uiAssetsDir` at a local directory. Your directory must contain the same file names as the built-in pages.

```typescript
app.use('/auth/ui', buildUiRouter({
  authConfig:   config,
  apiPrefix:    '/auth',
  uiAssetsDir:  path.resolve(__dirname, 'my-custom-ui'),
}));
```

Your HTML files still benefit from server-side config injection (`window.__AUTH_CONFIG__`, CSS variables) as long as they contain a `</head>` tag.

---

### How `auth.js` activates automatically

Each built-in HTML page includes `<script src="auth.js">`, which:

1. Reads `window.__AUTH_CONFIG__` (injected by the server at render time — zero extra fetch)
2. Intercepts all `fetch()` calls to add `credentials: 'include'` and `X-CSRF-Token`
3. Handles 401/403 responses with transparent token refresh
4. Exposes `window.AwesomeNodeAuth` for optional custom scripting

> See [Browser Client (`auth.js`)](/docs/advanced/browser-client) for the full `window.AwesomeNodeAuth` API.

---

### Enabling features dynamically

The UI hides/shows features based on which strategies and handlers are configured:

| Feature | Shown when |
|---------|-----------|
| Register link | `routerOptions.onRegister` is set |
| Forgot password | `authConfig.email.sendPasswordReset` or `.mailer` is set |
| Magic link | `authConfig.email.sendMagicLink` or `.mailer` is set |
| Google OAuth | `authConfig.oauth.google` is set |
| GitHub OAuth | `authConfig.oauth.github` is set |
| 2FA page | `authConfig.twoFactor` is set |
| Verify email | `authConfig.email.mailer` is set and `emailVerificationMode !== 'none'` |

Pass `routerOptions` to `buildUiRouter` so these flags are computed correctly:

```typescript
const config: AuthConfig = { /* … */ };
const auth = new AuthConfigurator(config, userStore);

const routerOpts = {
  onRegister: async (data) => { /* … */ },
  // …
};

app.use('/auth', auth.router(routerOpts));
app.use('/auth/ui', buildUiRouter({ authConfig: config, routerOptions: routerOpts, apiPrefix: '/auth' }));
```

---

### Redirecting after login

`awesome-node-auth` redirects to `AuthConfig.ui.loginUrl` when an unauthenticated user hits a protected route. After a successful login the default redirect target is `/` (the home page).

Customize both with `AwesomeNodeAuth.init()` in your own JS:

```html
<script src="/auth/ui/auth.js"></script>
<script>
  AwesomeNodeAuth.init({ homeUrl: '/dashboard' });
</script>
```

Or server-side, via the `window.__AUTH_CONFIG__` injection — the `homeUrl` can be baked in by `buildUiRouter` at render time if you extend `getUiConfig`.

---

### Headless Mode — using `auth.js` without the UI pages

When embedding `awesome-node-auth` into an **existing SPA or documentation site** (e.g. Docusaurus, Next.js, Nuxt) you may want the client-side `auth.js` library (token refresh, session-expiry hooks) without the server-side HTML login / register pages.

Enable **headless mode** by setting `ui.headless: true` in your `AuthConfig`:

```typescript
const config: AuthConfig = {
  // ...
  ui: {
    headless: true,
    loginUrl: '/auth/ui/login', // optional — ignored when headless
  },
};
```

#### What changes in headless mode

| Feature | Normal mode | Headless mode (`ui.headless: true`) |
|---------|-------------|-------------------------------------|
| `GET /auth/ui/login` | Returns HTML login page | Returns `404` |
| `GET /auth/ui/register` | Returns HTML register page | Returns `404` |
| `GET /auth/ui/auth.js` | Served ✅ | Served ✅ |
| `GET /auth/ui/auth.css` | Served ✅ | Served ✅ |
| `GET /auth/ui/config` | `{ headless: false, … }` | `{ headless: true, … }` |
| `window.location` redirects | Active | **Disabled** — no-op handlers installed |

#### Loading `auth.js` in a Docusaurus / SPA site

Mount the router in headless mode on your backend, then load `auth.js` from your frontend:

```html
<!-- Load before your SPA bundle so the singleton is available immediately -->
<script src="/auth/ui/auth.js"></script>
<script>
  // headless: true → installs no-op lifecycle handlers so auth.js never
  // redirects window.location away from your SPA pages
  AwesomeNodeAuth.init({
    apiPrefix: '/auth',
    headless: true,
  });
</script>
```

`auth.js` automatically detects the `headless: true` flag from the `/auth/ui/config` response and suppresses all window navigation. You can still register your own handlers:

```javascript
AwesomeNodeAuth.onSessionExpired(() => {
  // show a custom "session expired" toast in your SPA
  myToastService.show('Your session expired — please log in again.');
});
```

#### Cross-domain setup (API on a separate origin)

When the wiki / SPA is served from a different origin than the auth API, pass the full origin via `apiPrefix`:

```typescript
// docusaurus.config.ts — inject auth.js from the API server
headTags: [
  {
    tagName: 'script',
    attributes: { src: 'https://api.myapp.com/auth/ui/auth.js' },
  },
  {
    tagName: 'script',
    attributes: {},
    innerHTML: `
      if (window.AwesomeNodeAuth) {
        window.AwesomeNodeAuth.init({
          apiPrefix: 'https://api.myapp.com/auth',
          headless: true,
        });
      }
    `,
  },
],
```

---

### Angular / Next.js — do I need the built-in UI?

| Client | Recommendation |
|--------|---------------|
| **Vanilla JS / jQuery / plain HTML** | Use the built-in UI — zero setup |
| **Next.js / Nuxt / SvelteKit** | Built-in UI works; or build your own pages and call the REST API |
| **Angular** | Use the dedicated **[@awesome-lang-auth/angular](/docs/frameworks/ng-awesome-node-auth)** library — it provides Guards, Interceptors, and a typed `AuthService`; `auth.js` is **not needed** in Angular projects |

---

:::tip Production checklist
- Set `cookieOptions.secure: true` so `__Host-` / `__Secure-` cookie prefixes are applied (cookie-tossing protection)
- Set `csrf: { enabled: true }` when your frontend makes state-changing requests
- Use `ISettingsStore` if you want runtime theme changes without server restarts
- Pass `uploadDir` to accept logo uploads from the admin panel
:::

---

### Internationalization (i18n)

The built-in UI supports **per-page text overrides** via `ITemplateStore`. When a `templateStore` is configured and a `UiTranslation` entry exists for the current page, the UI router injects the translations into `window.__AUTH_CONFIG__.translations` at render time — no extra HTTP request needed.

#### How it works

```mermaid
sequenceDiagram
    autonumber
    participant Browser
    participant UiRouter as UiRouter (server)
    participant Store as ITemplateStore

    Browser->>UiRouter: GET /auth/ui/login?lang=it
    UiRouter->>Store: getUiTranslations("login")
    Store-->>UiRouter: { page: "login", translations: { it: { title: "Accedi", … } } }
    UiRouter->>UiRouter: inject into window.__AUTH_CONFIG__.translations
    UiRouter-->>Browser: HTML with translations embedded
    Note over Browser: auth.js calls AuthService.applyTranslations()
    Browser->>Browser: querySelectorAll("[data-i18n]") → patch textContent / placeholder
```

#### Activating i18n

Pass a `templateStore` to `buildUiRouter`:

```typescript
import { buildUiRouter, MemoryTemplateStore } from '@awesome-lang-auth/node';

const templateStore = new MemoryTemplateStore();

// Pre-populate translations (or load from DB at startup)
await templateStore.updateUiTranslations('login', {
  en: { title: 'Sign in', emailPlaceholder: 'Email address', submitBtn: 'Log in', forgotLink: 'Forgot password?' },
  it: { title: 'Accedi', emailPlaceholder: 'Indirizzo email', submitBtn: 'Entra', forgotLink: 'Password dimenticata?' },
});

app.use('/auth/ui', buildUiRouter({
  authConfig,
  apiPrefix:     '/auth',
  templateStore,             // ← enables i18n injection
}));
```

The language is resolved from the `?lang=` query parameter first, then from `email.mailer.defaultLang`, and finally falls back to `'en'`.

#### The `data-i18n` attribute

Every translatable element in the built-in HTML pages carries a `data-i18n` attribute:

```html
<h2 data-i18n="title">Sign in</h2>
<input type="email" data-i18n="emailPlaceholder" placeholder="Email address" />
<button type="submit" data-i18n="submitBtn">Log in</button>
<a href="/auth/forgot-password" data-i18n="forgotLink">Forgot password?</a>
```

On page load `auth.js` calls `AuthService.applyTranslations()`, which:

1. Reads `window.__AUTH_CONFIG__.translations` (flat `{ key: value }` map for the current language)
2. Iterates every `[data-i18n]` element
3. Sets `.textContent` for regular elements or `.placeholder` for `<input>` / `<textarea>`

The built-in text remains in place as the default — it is only replaced when a matching translation key exists.

#### Page identifiers

Each UI page maps to a translation entry by its path segment. Use this identifier as the first argument to `templateStore.updateUiTranslations()`:

| Page | `UiTranslation.page` | Example call |
|------|----------------------|--------------|
| Login | `login` | `updateUiTranslations('login', { … })` |
| Register | `register` | `updateUiTranslations('register', { … })` |
| Forgot Password | `forgot-password` | `updateUiTranslations('forgot-password', { … })` |
| Reset Password | `reset-password` | `updateUiTranslations('reset-password', { … })` |
| Magic Link | `magic-link` | `updateUiTranslations('magic-link', { … })` |
| Verify Email | `verify-email` | `updateUiTranslations('verify-email', { … })` |
| 2FA Challenge | `2fa` | `updateUiTranslations('2fa', { … })` |
| Link Verify | `link-verify` | `updateUiTranslations('link-verify', { … })` |
| Account Conflict | `account-conflict` | `updateUiTranslations('account-conflict', { … })` |

#### Managing translations via the Admin UI

Pass the same `templateStore` to `createAdminRouter` to edit translations live through the **📧 Email & UI** tab:

```typescript
app.use('/admin', createAdminRouter(userStore, {
  accessPolicy: 'first-user',
  jwtSecret: process.env.ACCESS_TOKEN_SECRET!,
  templateStore,
}));
```

> See [Admin Panel → Email & UI tab](/docs/advanced/admin#email--ui-templates-tab) and [ITemplateStore API Reference](/docs/api-reference/template-store).

---

## auth.js Browser Client (window.AwesomeNodeAuth)

## Browser Client — `window.AwesomeNodeAuth`

`awesome-node-auth` ships a zero-config browser authentication client as a static asset served at `/auth/ui/auth.js`.

Include it once in your HTML to get a complete, framework-agnostic auth layer — no npm install, no build step, no configuration required.

```html
<!-- Add to <head> — works with Express, NestJS, Next.js, or any server -->
<script src="/auth/ui/auth.js"></script>
```

> Replace `/auth` with your actual `apiPrefix` if different from the default.

---

### What it does automatically

| Capability | Details |
|-----------|---------|
| **CSRF injection** | Intercepts every `fetch()` call directed at the auth backend and adds `X-CSRF-Token` from the CSRF cookie (`__Host-csrf-token`, `__Secure-csrf-token`, or `csrf-token` — checked in that order to support cookie-tossing protection added in v1.3) |
| **Credentials propagation** | Forces `credentials: 'include'` on all requests to the **same origin as the auth backend**. The origin is derived from `apiPrefix`: if it is an absolute URL (e.g. `https://auth.example.com/auth`), only requests to that domain get credentials; if it is a relative path, all same-origin requests qualify. Requests to other origins (e.g. LiteLLM, OpenAI, Stripe) are left untouched, avoiding conflicts with `Access-Control-Allow-Origin: *` |
| **Token auto-refresh** | On any 401 or 403 from a non-auth endpoint, transparently calls `POST /auth/refresh` and retries; on failure, calls logout and redirects |
| **`apiPrefix` auto-detection** | Derives the backend base path from the page URL (e.g. `/auth` at `/auth/ui/login`) — **zero config needed** with built-in UI pages |

---

### Registered globals

| Global | Purpose |
|--------|---------|
| `window.AwesomeNodeAuth` | **Public API** — use from any JS/framework |
| `window.AuthService` | Internal helper used by the built-in HTML pages; available for low-level API calls |

---

### `AwesomeNodeAuth.init(options?)` — optional configuration

`init()` is not required. Call it only if you need to customise paths, lifecycle hooks, or override individual methods.

```javascript
// Zero config — works out of the box with built-in UI pages
// AwesomeNodeAuth.init() is not required

// Custom prefix + login URL
AwesomeNodeAuth.init({
  apiPrefix: '/api/v1/auth',
  loginUrl: '/sign-in',
  homeUrl: '/dashboard',
});

// Lifecycle hooks for SPA routing (no full-page redirect)
AwesomeNodeAuth.init({
  apiPrefix: '/api/auth',
  onSessionExpired: () => router.navigate('/login'),
  onLogout: () => { clearLocalStorage(); router.navigate('/login'); },
  onRefreshFail: () => console.warn('[auth] token refresh failed'),
  onRefreshSuccess: (result) => console.debug('[auth] refreshed', result),
});

// Override an individual auth method (e.g. add audit logging)
// Call AuthService.apiCall directly — calling AwesomeNodeAuth.login() here
// would recurse infinitely since this IS the login override.
AwesomeNodeAuth.init({
  login: async (email, password) => {
    console.log('[audit] login attempt for', email);
    return AuthService.apiCall('/login', 'POST', { email, password });
  },
});
```

#### `init()` options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `apiPrefix` | `string` | Derived from URL | Base path of the auth backend |
| `loginUrl` | `string` | `{apiPrefix}/ui/login` | Login page URL |
| `homeUrl` | `string` | `/` | Redirect target after successful login |
| `siteName` | `string` | `'Awesome Node Auth'` | Site name (used by built-in pages) |
| `headless` | `boolean` | `false` | When `true`, installs no-op `onSessionExpired`, `onLogout`, and `onRefreshFail` handlers immediately. Use when loading `auth.js` from a remote SPA (e.g. Docusaurus) that manages its own navigation — prevents `auth.js` from doing `window.location` redirects. Auto-applied when the backend config also has `ui.headless: true`. |
| `onLogout` | `Function` | Auto-redirect to `loginUrl` | Called after logout instead of redirect |
| `onSessionExpired` | `Function` | Auto-redirect to `loginUrl` | Called when token refresh fails instead of redirect |
| `onRefreshSuccess` | `Function(result)` | — | Called after a successful transparent token refresh |
| `onRefreshFail` | `Function` | Auto-logout | Called when token refresh fails (before logout fallback) |
| `login` | `Function` | Built-in | Override the `login()` implementation |
| `logout` | `Function` | Built-in | Override the `logout()` implementation |
| `register` | `Function` | Built-in | Override the `register()` implementation |
| _(any method)_ | `Function` | Built-in | Any public method can be overridden the same way |

---

### State

```javascript
AwesomeNodeAuth.isAuthenticated()  // → boolean
AwesomeNodeAuth.isInitialized()    // → boolean (true after first checkSession)
AwesomeNodeAuth.getUser()          // → user object or null
AwesomeNodeAuth.config             // → { apiPrefix, loginUrl, homeUrl, features, ui, … }
```

---

### Session & route guards

```javascript
// Verify current session (calls GET /auth/me)
const loggedIn = await AwesomeNodeAuth.checkSession();

// Redirect to login if not authenticated
await AwesomeNodeAuth.guardPage();
await AwesomeNodeAuth.guardPage('/custom-login');   // custom redirect target

// Redirect if user lacks the required role
await AwesomeNodeAuth.guardRole('admin');
await AwesomeNodeAuth.guardRole('editor', '/unauthorized');
```

---

### Auth methods

#### Login & register

```javascript
// Login
const result = await AwesomeNodeAuth.login(email, password);
// result.success           → boolean
// result.error             → string | undefined
// result.requires2fa       → boolean (TOTP/SMS challenge required)
// result.tempToken         → string  (2FA flow token)
// result.availableMethods  → string[] (e.g. ['totp', 'sms'])
// result.requires2FASetup  → boolean (first-time 2FA enrollment required)

// Register
await AwesomeNodeAuth.register(email, password, firstName?, lastName?);

// Logout
await AwesomeNodeAuth.logout();
```

#### Password management

```javascript
await AwesomeNodeAuth.forgotPassword(email);
await AwesomeNodeAuth.resetPassword(token, newPassword);
await AwesomeNodeAuth.changePassword(currentPassword, newPassword);
await AwesomeNodeAuth.setPassword(newPassword);  // OAuth accounts — no current password needed
```

#### Magic link

```javascript
await AwesomeNodeAuth.sendMagicLink(email);
await AwesomeNodeAuth.verifyMagicLink(token);
```

#### TOTP two-factor authentication

```javascript
// Enrolment
const { secret, qrCode } = await AwesomeNodeAuth.setup2fa();
await AwesomeNodeAuth.verify2faSetup(code, secret);

// Login challenge (after login returns requires2fa: true)
await AwesomeNodeAuth.validate2fa(tempToken, totpCode);
```

#### SMS authentication

```javascript
// SMS-only login
await AwesomeNodeAuth.sendSmsLogin(email);
await AwesomeNodeAuth.verifySmsLogin(userId, code);

// SMS as 2FA step
await AwesomeNodeAuth.validateSms(tempToken, code);
```

#### Email verification

```javascript
await AwesomeNodeAuth.resendVerificationEmail();
await AwesomeNodeAuth.verifyEmail(token);
```

#### Email change

```javascript
await AwesomeNodeAuth.requestEmailChange(newEmail);
await AwesomeNodeAuth.confirmEmailChange(token);
```

#### Account linking

```javascript
await AwesomeNodeAuth.requestLinkingEmail(email, provider);
await AwesomeNodeAuth.verifyLinkingToken(token, provider);
await AwesomeNodeAuth.verifyConflictLinkingToken(token);  // OAuth conflict resolution

const accounts = await AwesomeNodeAuth.getLinkedAccounts();  // → LinkedAccount[]
await AwesomeNodeAuth.unlinkAccount(provider, providerAccountId);
```

#### Account deletion

```javascript
await AwesomeNodeAuth.deleteAccount();
```

---

### Framework integration examples

#### Vanilla JS / HTML — no build step required

```html
<script src="/auth/ui/auth.js"></script>
<script>
  // Configure once (optional)
  AwesomeNodeAuth.init({ homeUrl: '/dashboard' });

  document.getElementById('login-form').addEventListener('submit', async (e) => {
    e.preventDefault();
    const result = await AwesomeNodeAuth.login(
      document.getElementById('email').value,
      document.getElementById('password').value,
    );
    if (result.success) {
      window.location.href = AwesomeNodeAuth.config.homeUrl;
    } else {
      showError(result.error);
    }
  });
</script>
```

#### React (without a build step)

```html
<script src="/auth/ui/auth.js"></script>
<script type="module">
  // AwesomeNodeAuth is available globally — use it from any module
  import { useState } from 'https://esm.sh/react';

  export function useAuth() {
    const [user, setUser] = useState(AwesomeNodeAuth.getUser());

    async function login(email, password) {
      const result = await AwesomeNodeAuth.login(email, password);
      if (result.success) setUser(AwesomeNodeAuth.getUser());
      return result;
    }

    return { user, login, logout: AwesomeNodeAuth.logout.bind(AwesomeNodeAuth) };
  }
</script>
```

#### Vue 3 (CDN / no build)

```html
<script src="/auth/ui/auth.js"></script>
<script type="module">
  import { createApp, ref } from 'https://esm.sh/vue';

  createApp({
    setup() {
      const user = ref(AwesomeNodeAuth.getUser());

      async function login(email, password) {
        const result = await AwesomeNodeAuth.login(email, password);
        if (result.success) user.value = AwesomeNodeAuth.getUser();
        return result;
      }

      return { user, login };
    },
  }).mount('#app');
</script>
```

#### Next.js / SSR frameworks

Include `auth.js` in your layout and use the global in any client component:

```html
<!-- app/layout.tsx or _app.tsx — add to <head> -->
<Script src="/auth/ui/auth.js" strategy="beforeInteractive" />
```

```javascript
// In a client component
'use client';

await AwesomeNodeAuth.guardPage();          // redirects if not authenticated
const user = AwesomeNodeAuth.getUser();     // user after the last checkSession
```

#### SPA with client-side routing (React Router, Vue Router, etc.)

Prevent full-page redirects by providing navigation callbacks via `init()`:

```javascript
AwesomeNodeAuth.init({
  onSessionExpired: () => router.push('/login'),
  onLogout: () => {
    clearApplicationState();
    router.push('/login');
  },
});
```

---

### SSR fast-path (`window.__AUTH_CONFIG__`)

When using `buildUiRouter`, the server injects a `window.__AUTH_CONFIG__` script block into every HTML page before it is sent to the browser. `auth.js` reads this at startup and skips the `/auth/ui/config` fetch — eliminating an extra round-trip and preventing a flash of unstyled content.

This is handled automatically; no action is required.

---

### Headless mode — loading `auth.js` from a remote SPA

When your frontend is a separate SPA (e.g. a Docusaurus wiki, Next.js site, or any bundler-split application) that communicates with a remote auth backend, load `auth.js` once in your page `<head>` and enable **headless mode**:

```html
<!-- Docusaurus / Next.js / any SPA -->
<script src="https://auth.example.com/auth/ui/auth.js" crossorigin="anonymous"></script>
<script>
  if (window.AwesomeNodeAuth) {
    window.AwesomeNodeAuth.init({
      apiPrefix: 'https://auth.example.com/auth',
      headless: true,   // ← prevents window.location redirects
    });
  }
</script>
```

In headless mode:

- **No redirects**: `window.location.href` is never changed. Session expiry, logout, and refresh failure are handled silently (no-op) unless you override them with explicit callbacks.
- **Fetch interceptor active**: Token auto-refresh on 401/403 still works. All components in the SPA share the single `window.AwesomeNodeAuth` refresh singleton — eliminating duplicate concurrent refresh calls that would break token rotation.
- **Selective credentials**: `credentials: 'include'` is added to requests whose origin matches the auth backend's origin (derived from `apiPrefix`). When `apiPrefix` is an absolute URL (cross-domain mode, e.g. `https://auth.example.com/auth`), only requests to `auth.example.com` are affected — calls to LiteLLM, OpenAI, Stripe, or any other domain are left completely untouched. When `apiPrefix` is a relative path (same-domain), all same-origin requests get credentials (as expected).

#### How headless mode is activated

There are three activation paths (all idempotent):

| Path | When |
|------|------|
| `AwesomeNodeAuth.init({ headless: true })` | Inline `<script>` block — immediate, before any fetch |
| `window.__AUTH_CONFIG__ = { headless: true, … }` | SSR injection by the server |
| `/auth/ui/config` response has `headless: true` | Dynamic config fetch after `AuthService.init()` |

The server-side complement is `buildUiRouter({ authConfig: { ui: { headless: true } } })`, which:
- Returns 404 for HTML login/register pages (the SPA provides its own auth UI)
- Continues serving `auth.js` and CSS static assets
- Includes `{ headless: true }` in the `/config` JSON response

#### Custom lifecycle callbacks

Override individual handlers without losing headless redirect protection:

```javascript
AwesomeNodeAuth.init({
  headless: true,
  onSessionExpired: () => {
    // e.g. show a login modal instead of a full-page redirect
    showLoginModal();
  },
  onRefreshFail: () => {
    // e.g. display a toast notification
    toast.warning('Your session has expired. Please log in again.');
  },
});
```

---

:::note Angular
Angular has a dedicated library ([`@awesome-lang-auth/angular`](/docs/frameworks/ng-awesome-node-auth)) with Guards, Interceptors, and a typed `AuthService` — use that instead of `auth.js` for Angular projects.
:::

---

## Identity Provider Mode: RS256 JWTs and JWKS

## Identity Provider (IdP) Mode

`awesome-node-auth` can act as a **central Identity Provider** — generating RS256-signed JWTs and exposing a public JWKS endpoint so downstream **Resource Servers** can verify tokens without sharing a secret.

All existing HS256 (cookie / bearer) behaviour is preserved and the two modes can coexist in the same instance.

---

### Overview

```
┌─────────────────────────────┐        ┌─────────────────────────────┐
│   IdP (awesome-node-auth)   │        │   Resource Server (any app) │
│                             │        │                             │
│  POST /auth/login           │──RS256 tokens──►  Protected APIs    │
│  GET  /.well-known/jwks.json│◄──fetch JWKS───  Validate with JWKS │
└─────────────────────────────┘        └─────────────────────────────┘
```

---

### Configuration

```typescript
import { createAuthRouter } from '@awesome-lang-auth/node';

const auth = createAuthRouter({
  // …standard config…
  idProvider: {
    enabled: true,

    // PEM-encoded RSA-2048 private key (inject via environment variable).
    // If omitted, an ephemeral keypair is auto-generated at startup (dev only).
    privateKey: process.env.IDP_PRIVATE_KEY,

    // `iss` claim embedded in every IdP-issued JWT.
    // Resource Servers validate this claim.
    issuer: 'https://auth.myplatform.com',

    // Access token TTL (default: '30d')
    tokenExpiry: '30d',

    // Refresh token TTL (default: '90d', falls back to refreshTokenExpiresIn)
    refreshTokenExpiry: '90d',

    // Path for the JWKS endpoint (default: '/.well-known/jwks.json')
    jwksPath: '/.well-known/jwks.json',
  },
});
```

#### Configuration reference

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `enabled` | `boolean` | `false` | Enable IdP mode. Also activated when `privateKey` is set. |
| `privateKey` | `string` | — | PEM-encoded RSA-2048 private key. Auto-generated if omitted (dev only). |
| `publicKey` | `string` | — | PEM-encoded RSA public key. Auto-derived from `privateKey` if omitted. |
| `issuer` | `string` | — | `iss` claim embedded in every JWT. Omit to suppress the claim. |
| `tokenExpiry` | `string` | `'30d'` | Access token expiry. Overrides `accessTokenExpiresIn`. |
| `refreshTokenExpiry` | `string` | `'90d'` | Refresh token expiry. Falls back to `refreshTokenExpiresIn`. |
| `jwksPath` | `string` | `'/.well-known/jwks.json'` | Path at which the JWKS endpoint is exposed. |
| `jwksCorsOrigins` | `string \| string[]` | `'*'` | CORS origins allowed to fetch the JWKS endpoint. |

---

### Token structure

#### JWT header

In IdP mode every token is signed with **RS256**. The JOSE header carries the `kid` parameter so Resource Servers can select the correct public key from the JWKS document:

```json
{
  "alg": "RS256",
  "kid": "provisioner-key-1"
}
```

:::info kid is a JOSE header parameter
`kid` (Key ID) is defined by [RFC 7515 §4.1.4](https://www.rfc-editor.org/rfc/rfc7515#section-4.1.4) as a **JOSE header parameter**, not a JWT payload claim.
`awesome-node-auth` sets it via the `keyid` option of `jwt.sign()` so it appears in the header — exactly where third-party validators and JWKS libraries expect it.
:::

#### JWT payload (access token)

```typescript
interface AccessTokenPayload {
  sub:   string;             // user ID
  email: string;
  role?: string;
  loginProvider?: string;
  isEmailVerified?: boolean;
  isTotpEnabled?: boolean;
  iss:   string;             // issuer — present when `idProvider.issuer` is set
  iat:   number;             // issued-at  (set by jsonwebtoken)
  exp:   number;             // expiry     (set by jsonwebtoken)
  // …any custom claims from buildTokenPayload
}
```

#### Refresh token

In IdP mode the **refresh token is also RS256-signed** using the same private key, with a longer expiry (`refreshTokenExpiry ?? refreshTokenExpiresIn ?? '90d'`).

Signing the refresh token with RS256 ensures consistent key management and prevents a downgrade scenario where an HS256-signed refresh token could be used to obtain an RS256-signed access token, potentially bypassing issuer validation.

---

### JWKS endpoint

The JWKS endpoint is automatically registered at `idProvider.jwksPath` (default `/.well-known/jwks.json`):

```bash
curl https://auth.myplatform.com/.well-known/jwks.json
```

```json
{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "alg": "RS256",
      "kid": "provisioner-key-1",
      "n": "…",
      "e": "AQAB"
    }
  ]
}
```

---

### Resource Server validation

A downstream service validates incoming tokens against the IdP's JWKS endpoint:

```typescript
import { JwksService, TokenService } from '@awesome-lang-auth/node';

const tokenService = new TokenService();
const jwksClient = JwksService.createRemoteClient(
  'https://auth.myplatform.com/.well-known/jwks.json'
);

// In your auth middleware:
const payload = await tokenService.verifyWithJwks(
  token,
  jwksClient,
  'https://auth.myplatform.com', // expected issuer
);
// payload.sub, payload.email, etc.
```

`verifyWithJwks` reads `kid` from the **JWT header**, fetches the matching key from the JWKS document, and verifies the RS256 signature — including issuer validation when `expectedIssuer` is provided.

---

### Key rotation

1. Generate a new RSA keypair.
2. Update `idProvider.privateKey` (and `publicKey`) in your config.
3. Publish the new key in your JWKS endpoint alongside the old key until all tokens signed with the old key have expired.
4. Remove the old key from the JWKS document.

`JwksService.generateKeypair()` is a convenience helper for step 1:

```typescript
import { JwksService } from '@awesome-lang-auth/node';

const { privateKey, publicKey } = JwksService.generateKeypair();
```

---

### Security checklist

- ✅ Inject `privateKey` via an environment variable — never commit it to source control
- ✅ Always set `idProvider.issuer` and validate it on the Resource Server
- ✅ Use HTTPS in production
- ✅ Keep access token TTL short (`tokenExpiry: '15m'` for sensitive APIs)
- ✅ Rotate keys periodically and overlap old / new keys in the JWKS document during rollover

### Related

- [Custom JWT claims](/docs/advanced/custom-claims) — what resource servers read from the token
- [Session management and token revocation](/docs/advanced/sessions) — revocation with stateless RS256 tokens
- [API keys and service tokens](/docs/advanced/api-keys) — machine credentials next to user tokens
- [Auth API endpoints reference](/docs/api-reference/endpoints) — the JWKS and token routes

---

## Session Management and Token Revocation

## Session Management

By default, **awesome-node-auth** uses stateless JWTs. While this is highly scalable, it means that revoking a user's session from the environment does not take effect until the current Access Token expires.

To enable real-time session control and multi-device management, you can configure an `ISessionStore`.

---

### 1. Enabling Stateful Sessions

To enable session tracking, you must provide an implementation of `ISessionStore` when creating the auth router:

```ts
const auth = new AuthConfigurator(config, userStore);

app.use(auth.router({
  sessionStore: mySessionStore // Your ISessionStore implementation
}));
```

### 2. Validation Modes

You can control how strictly the library verifies sessions via the `session` configuration block in your `AuthConfig`:

```ts
const config: AuthConfig = {
  // ...
  session: {
    /**
     * 'refresh': Check session validity only when issuing a new Access Token. (Default)
     * 'allcalls': Check session validity on every single API request.
     * 'none': Track sessions in the store but do not perform any validity checks.
     */
    checkOn: 'refresh'
  }
};
```

#### `checkOn: 'refresh'` (Hybrid Mode)
This is the **recommended** setting for most applications.
- **Performance**: High. 99% of requests are stateless and fast.
- **Security**: Good. A revoked session will be blocked at the next refresh.
- **Behavior**: When a session is deleted from the store, the user can continue using their current token until it expires, but they will be logged out upon the next refresh attempt.

#### `checkOn: 'allcalls'` (Full Stateful)
Use this for high-security environments where instant revocation is required.
- **Performance**: Lower. Every request requires a call to the `sessionStore`.
- **Security**: Maximum. A revoked session is killed instantly for all subsequent API calls.
- **Requirement**: **Highly recommended to use a low-latency store (Redis or In-Memory)** for this mode to avoid API performance degradation.

#### `checkOn: 'none'` (Tracking Only)
Use this if you want visibility in the Admin UI without any performance overhead or enforcement.
- **Performance**: Same as stateless. No database lookups are performed during authentication.
- **Security**: Stateless. Revoking a session in the Admin UI has no effect until the tokens naturally expire.
- **Behavior**: Sessions are recorded in the `ISessionStore` on login, and `lastActiveAt` is updated in the middleware, allowing you to audit active users without blocking them.

#### How session validation works — sequence diagram

The diagram below illustrates what happens on every API request when a `sessionStore` is configured. The exact behaviour depends on the `checkOn` setting: with `'allcalls'` the store is consulted on every request; with `'refresh'` only when a new Access Token is issued.

```mermaid
sequenceDiagram
    autonumber
    participant Client
    participant Middleware as Auth Middleware
    participant TokenVerify as JWT Verifier
    participant SessionStore

    Client->>Middleware: API Request (Bearer JWT)
    Middleware->>TokenVerify: Verify signature & expiry
    alt Token invalid or expired
        TokenVerify-->>Middleware: Error
        Middleware-->>Client: 401 Unauthorized
    else Token valid — extract sid claim
        TokenVerify-->>Middleware: Decoded payload (userId, sid, …)
        note over Middleware: checkOn = 'allcalls' → always<br/>checkOn = 'refresh' → only on /auth/refresh
        Middleware->>SessionStore: getSession(sid)
        alt Session found
            SessionStore-->>Middleware: SessionInfo (active)
            Middleware->>SessionStore: updateSessionLastActive(sid)
            Middleware-->>Client: 200 OK — req.user populated
        else Session revoked / not found
            SessionStore-->>Middleware: null
            Middleware-->>Client: 401 Unauthorized (session revoked — force logout)
        end
    end
```

> **Key insight:** With `checkOn: 'refresh'` the `SessionStore` lookup only runs during token rotation (typically every 15 minutes), making the hot path completely stateless and Redis-free. With `checkOn: 'allcalls'` every request touches the store — use a low-latency backend (Redis or in-process `Map`) to keep overhead under 1 ms.

---

### 3. High Performance Patterns

Because `awesome-node-auth` uses interfaces for storage, you can mix-and-match technologies to optimize for speed and reliability:

| Storage Layer | Recommended Backend | Rationale |
| :--- | :--- | :--- |
| **Users & Accounts** | MongoDB / MySQL / Postgres | Persistence and data integrity for credentials. |
| **Sessions** | **Redis** / **In-Memory** | High-speed read/write for session lookups. |

#### Example: In-Memory Sessions
If you have a single server and want maximum speed with zero database overhead for session checks, implement `ISessionStore` using a `Map`:

```typescript
import { ISessionStore, SessionInfo } from '@awesome-lang-auth/node';
import crypto from 'node:crypto';

class InMemorySessionStore implements ISessionStore {
  private sessions = new Map<string, SessionInfo>();

  async createSession(info: Omit<SessionInfo, 'sessionHandle'>): Promise<SessionInfo> {
    const sessionHandle = crypto.randomUUID();
    const session = { sessionHandle, ...info };
    this.sessions.set(sessionHandle, session);
    return session;
  }
  async getSession(handle: string) { return this.sessions.get(handle) ?? null; }
  async getSessionsForUser(userId: string) { return [...this.sessions.values()].filter(s => s.userId === userId); }
  async updateSessionLastActive(handle: string) { const s = this.sessions.get(handle); if (s) s.lastActiveAt = new Date(); }
  async revokeSession(handle: string) { this.sessions.delete(handle); }
  async revokeAllSessionsForUser(userId: string) { for (const [h, s] of this.sessions) if (s.userId === userId) this.sessions.delete(h); }
}

const sessionStore = new InMemorySessionStore();

app.use(auth.router({ sessionStore }));
app.use('/api', auth.middleware({ sessionStore }), apiRouter);
```

---

### 4. User-Facing Session Endpoints

When a `sessionStore` is provided the auth router automatically mounts two endpoints that let **logged-in users** inspect and revoke their own devices — no admin access required.

#### `GET /auth/sessions` — list own sessions

Returns the list of active sessions for the currently authenticated user (scoped to the `userId` in their JWT).

```http
GET /auth/sessions
Authorization: Bearer <access_token>   (or cookie)
```

**Response `200 OK`:**

```json
[
  {
    "sessionHandle": "sess_abc123",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X…) Safari/537.36",
    "ipAddress": "203.0.113.42",
    "createdAt": "2026-03-18T10:00:00.000Z",
    "lastActiveAt": "2026-03-18T14:30:00.000Z"
  }
]
```

#### `DELETE /auth/sessions/:handle` — revoke a session

Revokes one specific session by its handle. The requesting user can only revoke their own sessions; attempts to revoke another user's handle are rejected with `403`.

```http
DELETE /auth/sessions/sess_abc123
Authorization: Bearer <access_token>   (or cookie)
```

**Response `204 No Content`** on success.

**Error responses:**

| Status | Meaning |
|--------|---------|
| `401` | Not authenticated |
| `403` | Handle belongs to a different user |
| `404` | Session handle not found |

#### Revoking your own current session

Calling `DELETE /auth/sessions/<currentHandle>` is equivalent to a targeted logout. The JWT remains valid until it expires — call `POST /auth/logout` in addition to also clear the cookie/refresh token.

#### `POST /auth/sessions/cleanup` (cron helper)

Deletes expired sessions from the store. Wire it up to a periodic job:

```typescript
// Node-cron example — run every day at 03:00
import cron from 'node-cron';
cron.schedule('0 3 * * *', async () => {
  await fetch('http://localhost:3000/auth/sessions/cleanup', { method: 'POST' });
});
```

This endpoint is only mounted when `sessionStore` is provided **and** `ISessionStore.deleteExpiredSessions` is implemented.

---

### 5. Admin Panel Integration

When a `sessionStore` is provided, the **Admin Dashboard** automatically unlocks the **Sessions** view. 

Administrators can audit active sessions (User Agent, IP, Last Activity) and **Revoke** any session instantly. If `checkOn: 'allcalls'` is enabled, the user is disconnected immediately. If `checkOn: 'refresh'` is used, they are disconnected at their next token rotation.

---

### 6. Advanced Strategies: Hybrid Caching (L1/L2/L3)

For high-traffic applications, a single database can become a bottleneck when `checkOn: 'allcalls'` is active — every authenticated request translates to a store lookup. A layered caching strategy solves this with no security trade-offs.

| Layer | Technology | Latency | Scope |
| :--- | :--- | :--- | :--- |
| **L1** | In-Process `Map` (short TTL) | < 0.1 ms | Single instance |
| **L2** | Redis | < 1 ms | All instances |
| **L3** | Database (Postgres/MySQL/Mongo) | 1–20 ms | Persistent store |

#### Pattern: Write-Through Redis + Database (L2 + L3)

This strategy gives you **persistence** (database) and **speed** (Redis). Use it as a drop-in `ISessionStore` when deploying with `checkOn: 'allcalls'` and multiple server instances.

```typescript
import type { ISessionStore, SessionInfo } from '@awesome-lang-auth/node';
import type { Redis } from 'ioredis';
import type { Knex } from 'knex';

const SESSION_TTL_SECONDS = 60 * 60 * 24 * 7; // 7 days — match refreshTokenExpiresIn

class HybridSessionStore implements ISessionStore {
  constructor(private redis: Redis, private db: Knex) {}

  async getSession(handle: string): Promise<SessionInfo | null> {
    // 1. L2: fast Redis read
    const cached = await this.redis.get(`sess:${handle}`);
    if (cached) return JSON.parse(cached) as SessionInfo;

    // 2. L3: fallback to database
    const row = await this.db('sessions').where({ session_handle: handle }).first();
    if (!row) return null;

    // Re-warm the cache for subsequent calls
    await this.redis.setex(`sess:${handle}`, SESSION_TTL_SECONDS, JSON.stringify(row));
    return row as SessionInfo;
  }

  async createSession(info: Omit<SessionInfo, 'sessionHandle'>): Promise<SessionInfo> {
    const sessionHandle = crypto.randomUUID();
    const session: SessionInfo = { sessionHandle, ...info };
    // Write-through: persist to both layers atomically
    await this.db('sessions').insert({ session_handle: sessionHandle, ...info });
    await this.redis.setex(`sess:${sessionHandle}`, SESSION_TTL_SECONDS, JSON.stringify(session));
    return session;
  }

  async revokeSession(handle: string): Promise<void> {
    // Remove from both layers simultaneously
    await Promise.all([
      this.redis.del(`sess:${handle}`),
      this.db('sessions').where({ session_handle: handle }).delete(),
    ]);
  }

  async revokeAllSessionsForUser(userId: string): Promise<void> {
    const rows = await this.db('sessions').where({ user_id: userId }).select('session_handle');
    await Promise.all([
      ...rows.map((r: { session_handle: string }) => this.redis.del(`sess:${r.session_handle}`)),
      this.db('sessions').where({ user_id: userId }).delete(),
    ]);
  }

  async getSessionsForUser(userId: string): Promise<SessionInfo[]> {
    return this.db('sessions').where({ user_id: userId }) as Promise<SessionInfo[]>;
  }

  async updateSessionLastActive(handle: string): Promise<void> {
    const now = new Date();
    await Promise.all([
      this.db('sessions').where({ session_handle: handle }).update({ last_active_at: now }),
      this.redis.setex(`sess:${handle}:active`, 30, now.toISOString()), // lightweight Redis key
    ]);
  }
}
```

#### Pattern: L1 In-Process Cache (ultra-low latency)

:::tip Use this with `checkOn: 'allcalls'`
If a single Node.js process handles all requests (or if you can tolerate up to 5 seconds of stale data for revocation), add an in-process **L1 cache** on top of the L2/L3 store to avoid any network round-trip for the vast majority of reads.
:::

```typescript
class L1CachedSessionStore implements ISessionStore {
  private l1 = new Map<string, { session: SessionInfo; expiresAt: number }>();
  private readonly L1_TTL_MS = 5_000; // 5-second TTL: balances speed vs revocation latency

  constructor(private inner: ISessionStore) {}

  async getSession(handle: string): Promise<SessionInfo | null> {
    const hit = this.l1.get(handle);
    if (hit && hit.expiresAt > Date.now()) return hit.session;
    const session = await this.inner.getSession(handle);
    if (session) this.l1.set(handle, { session, expiresAt: Date.now() + this.L1_TTL_MS });
    else this.l1.delete(handle);
    return session;
  }

  async revokeSession(handle: string): Promise<void> {
    this.l1.delete(handle); // Invalidate L1 immediately
    await this.inner.revokeSession(handle);
  }

  // Delegate all other methods to the inner store
  createSession(info: Omit<SessionInfo, 'sessionHandle'>) { return this.inner.createSession(info); }
  getSessionsForUser(userId: string, tenantId?: string) { return this.inner.getSessionsForUser(userId, tenantId); }
  updateSessionLastActive(handle: string) { return this.inner.updateSessionLastActive(handle); }
  revokeAllSessionsForUser(userId: string, tenantId?: string) { return this.inner.revokeAllSessionsForUser(userId, tenantId); }
  getAllSessions?(limit: number, offset: number) { return this.inner.getAllSessions!(limit, offset); }
  deleteExpiredSessions?() { return this.inner.deleteExpiredSessions!(); }
}

// Usage: wrap any store with the L1 cache decorator
const sessionStore = new L1CachedSessionStore(new HybridSessionStore(redis, db));

app.use(auth.router({ sessionStore }));
app.use('/api', auth.middleware({ sessionStore }), apiRouter);
```

### Related

- [Bearer token mode](/docs/advanced/bearer-token) — sessions for native and mobile clients
- [CSRF protection](/docs/advanced/csrf) — protecting cookie-based sessions
- [Built-in admin panel](/docs/advanced/admin) — list and kill sessions from the dashboard
- [Email and password authentication](/docs/authentication/local) — where a session begins

---

## Role-Based Access Control (RBAC) in Node.js

## Roles & Permissions (RBAC)

`IRolesPermissionsStore` provides role-based access control with optional tenant scoping.

### Interface

```typescript
import { IRolesPermissionsStore } from '@awesome-lang-auth/node';

export class MyRbacStore implements IRolesPermissionsStore {
  async addRoleToUser(userId: string, role: string, tenantId?: string): Promise<void> { /* ... */ }
  async removeRoleFromUser(userId: string, role: string, tenantId?: string): Promise<void> { /* ... */ }
  async getRolesForUser(userId: string, tenantId?: string): Promise<string[]> { /* ... */ }

  async createRole(role: string, permissions?: string[]): Promise<void> { /* ... */ }
  async deleteRole(role: string): Promise<void> { /* ... */ }

  async addPermissionToRole(role: string, permission: string): Promise<void> { /* ... */ }
  async removePermissionFromRole(role: string, permission: string): Promise<void> { /* ... */ }
  async getPermissionsForRole(role: string): Promise<string[]> { /* ... */ }

  async getPermissionsForUser(userId: string, tenantId?: string): Promise<string[]> { /* ... */ }
  async userHasPermission(userId: string, permission: string, tenantId?: string): Promise<boolean> { /* ... */ }
}
```

### Usage

```typescript
// Setup
await rbac.createRole('editor', ['posts:read', 'posts:write']);
await rbac.addRoleToUser(userId, 'editor', 'tenant-acme');

// Protect a route
app.delete('/posts/:id', auth.middleware(), async (req, res) => {
  const allowed = await rbac.userHasPermission(req.user!.sub, 'posts:write');
  if (!allowed) return res.status(403).json({ error: 'Forbidden' });
  // ... delete post
});
```

### Embed in JWT

```typescript
buildTokenPayload: async (user) => ({
  roles:       await rbac.getRolesForUser(user.id),
  permissions: await rbac.getPermissionsForUser(user.id),
}),
```

Pass `rbacStore` to `auth.router()` to include roles/permissions in `GET /auth/me`.

### Related

- [Multi-tenant authentication](/docs/advanced/multi-tenancy) — scope roles per organisation
- [Custom JWT claims](/docs/advanced/custom-claims) — put roles in the access token
- [Built-in admin panel](/docs/advanced/admin) — assign roles from the dashboard
- [API keys and service tokens](/docs/advanced/api-keys) — apply the same permissions to machines

---

## Multi-Tenant Authentication for SaaS Apps

## Multi-Tenancy

`ITenantStore` provides multi-tenant support for applications that serve multiple organizations.

### Interface

```typescript
import { ITenantStore, Tenant } from '@awesome-lang-auth/node';

export class MyTenantStore implements ITenantStore {
  async createTenant(data: Omit<Tenant, 'id'>): Promise<Tenant> { /* ... */ }
  async getTenantById(id: string): Promise<Tenant | null> { /* ... */ }
  async getAllTenants(): Promise<Tenant[]> { /* ... */ }
  async updateTenant(id: string, data: Partial<Omit<Tenant, 'id'>>): Promise<void> { /* ... */ }
  async deleteTenant(id: string): Promise<void> { /* ... */ }

  async associateUserWithTenant(userId: string, tenantId: string): Promise<void> { /* ... */ }
  async disassociateUserFromTenant(userId: string, tenantId: string): Promise<void> { /* ... */ }
  async getTenantsForUser(userId: string): Promise<Tenant[]> { /* ... */ }
  async getUsersForTenant(tenantId: string): Promise<string[]> { /* ... */ }
}
```

### Tenant Model

```typescript
interface Tenant {
  id:        string;
  name:      string;
  isActive?: boolean;
  config?:   Record<string, unknown>;
  createdAt?: Date;
}
```

### Usage

```typescript
// Onboarding
const tenant = await tenants.createTenant({ name: 'Acme Corp', isActive: true });
await tenants.associateUserWithTenant(userId, tenant.id);

// Embed tenants in JWT
buildTokenPayload: async (user) => ({
  tenants: (await tenants.getTenantsForUser(user.id)).map(t => t.id),
}),
```

### Related

- [Role-based access control (RBAC)](/docs/advanced/roles-permissions) — tenant-scoped roles and permissions
- [Custom JWT claims](/docs/advanced/custom-claims) — carry the tenant id inside the token
- [Built-in admin panel](/docs/advanced/admin) — manage tenants and memberships
- [Extending BaseUser and auth interfaces](/docs/advanced/extending-interfaces) — add fields to BaseTenant

---

## CORS and Dynamic Caller Resolution

## CORS & Dynamic Caller Resolution

When your authentication backend lives on a different domain than your
front-end (e.g. wiki on `https://app.example.com`, API on
`https://api.example.com`) you need two things to work correctly:

1. **CORS headers** — so the browser allows cross-origin `fetch` requests with
   `credentials: 'include'`.
2. **Dynamic `siteUrl`** — so the post-OAuth redirect and all email links point
   back to the exact front-end origin that started the flow.

Both are configured through the same two options and work with a shared
**allowlist** of trusted origins, preventing open-redirect attacks.

---

### The problem: cross-origin cookies

After a successful OAuth login, awesome-node-auth sets HttpOnly cookies and redirects
the browser to your front-end.  When your front-end JavaScript later calls
`/auth/me` (or any other auth endpoint) it must include those cookies.  Browsers
only send cookies on cross-origin `fetch` requests when **all three** conditions
are met:

| Requirement | Setting |
|-------------|---------|
| Cookie `SameSite` | `None` |
| Cookie `Secure` | `true` (HTTPS required) |
| `fetch` call | `credentials: 'include'` |
| Server response | `Access-Control-Allow-Origin: <exact origin>` + `Access-Control-Allow-Credentials: true` |

node-auth handles the server-side requirements; you only need to configure the
allowed origins.

---

### Configuration

#### 1. Enable CORS in the auth router

Pass the `cors` option to `RouterOptions`:

```typescript
import express from 'express';
import { AuthConfigurator } from '@awesome-lang-auth/node';
import { MyUserStore } from './my-user-store';

const app = express();
app.use(express.json());

const auth = new AuthConfigurator(
  {
    accessTokenSecret:  process.env.ACCESS_TOKEN_SECRET!,
    refreshTokenSecret: process.env.REFRESH_TOKEN_SECRET!,
    cookieOptions: {
      secure:   true,          // required for sameSite: 'none'
      sameSite: 'none',        // required for cross-origin cookies
    },
    email: {
      // Array of allowed front-end origins.
      // The router dynamically picks the one matching the request Origin header.
      // The first entry is the default used for email links (magic link, reset, etc.).
      siteUrl: [
        'https://app.example.com',
        'https://admin.example.com',
      ],
    },
  },
  new MyUserStore()
);

app.use('/auth', auth.router({
  cors: {
    origins: [
      'https://app.example.com',
      'https://admin.example.com',
    ],
  },
  // ... other options
}));
```

:::tip Single origin
When you only have one front-end domain you can still use a string:

```typescript
email: { siteUrl: 'https://app.example.com' }
```

But passing `cors.origins` is still recommended so the auth router
handles preflight `OPTIONS` requests automatically.
:::

---

#### 2. Cookie settings for production

Cross-origin cookies require `Secure: true` which in turn requires HTTPS.
Adjust `cookieOptions` based on the environment:

```typescript
cookieOptions: {
  secure:   process.env.NODE_ENV === 'production',   // HTTPS only
  sameSite: process.env.NODE_ENV === 'production' ? 'none' : 'lax',
},
```

In **development** with a local proxy (API and front-end on the same origin via
`/api` proxy) `sameSite: 'lax'` is fine. In **production** with separate
domains use `sameSite: 'none'` + `secure: true`.

---

#### 3. Front-end fetch calls

Your front-end must include credentials on every request to the auth API:

```typescript
const res = await fetch('https://api.example.com/auth/me', {
  credentials: 'include',   // sends cookies cross-origin
  headers: { 'Content-Type': 'application/json' },
});
```

---

### How dynamic `siteUrl` works

#### For OAuth flows

When a user clicks "Sign in with Google" on `https://app.example.com`:

```mermaid
sequenceDiagram
    participant B as Browser (app.example.com)
    participant API as Auth API (api.example.com)
    participant G as Google

    B->>API: GET /auth/oauth/google<br/>Origin: https://app.example.com
    Note over API: resolves siteUrl from Origin header<br/>encodes it into OAuth state
    API->>G: redirect to Google<br/>state = base64url({n: nonce, o: "https://app.example.com"})
    G->>API: GET /auth/oauth/google/callback?code=…&state=…
    Note over API: decodes state → validates origin<br/>against allowlist → redirectTo
    API->>API: set HttpOnly cookies
    API->>B: 302 → https://app.example.com
    B->>API: GET /auth/me<br/>credentials: include
    API-->>B: { id, email, role, … }
```

The resolved redirect URL is embedded in the OAuth `state` parameter during
the initiation request.  On the callback the library decodes the state,
**validates** the origin against the allowlist, and uses it as the redirect
target.  An origin that is not in the allowlist is silently ignored and the
default (`siteUrl[0]`) is used instead, preventing open-redirect attacks.

#### For email links

For magic links, password-reset links, email-verification links, and similar
email-based flows the **first entry** in the `siteUrl` array (or the string
itself) is always used as the base URL.  These flows are initiated by a form
submission, not a browser navigation, so the request `Origin` is not a
reliable indicator of the target UI.

If you need to support email links for multiple front-ends you can:
- Set `siteUrl[0]` to your primary front-end URL.
- Route from the primary front-end to the secondary one if needed.

---

### `email.siteUrl` — string vs. array

| Type | Behaviour |
|------|-----------|
| `string` (`'https://app.example.com'`) | Used as-is for all email links and OAuth redirects. |
| `string[]` (`['https://app.com', 'https://admin.app.com']`) | OAuth redirects are resolved dynamically from the request `Origin`/`Referer` header; email links use the first entry. |

---

### `RouterOptions.cors`

| Field | Type | Description |
|-------|------|-------------|
| `cors.origins` | `string[]` | Explicit list of allowed front-end origins. When set, the auth router adds `Access-Control-*` headers and handles `OPTIONS` preflight automatically. |

The `cors.origins` list is **merged** with the `email.siteUrl` array when
building the dynamic redirect allowlist, so you only need to specify each
origin once if you set both.

---

### Example: configuration from environment variables

A server can drive both CORS and the dynamic siteUrl from environment variables:

```env
# .env
CORS_ORIGINS=https://wiki.example.com,https://app.example.com
SITE_URL=https://wiki.example.com   # optional: explicit default (used for email links)
```

```typescript
// server.ts
const CORS_ORIGINS = (process.env.CORS_ORIGINS ?? '')
  .split(',').map((o) => o.trim()).filter(Boolean);
const SITE_URL = process.env.SITE_URL ?? '';
const IS_PRODUCTION = process.env.NODE_ENV === 'production';

const allowedSiteUrls = [SITE_URL, ...CORS_ORIGINS].filter(Boolean);

const authConfig: AuthConfig = {
  cookieOptions: {
    // When CORS_ORIGINS are configured (i.e. cross-domain deployment)
    // the server automatically switches to SameSite=None + Secure=true so that
    // HttpOnly cookies are sent from the remote SPA to this server.
    secure:   IS_PRODUCTION || CORS_ORIGINS.length > 0,
    sameSite: (IS_PRODUCTION || CORS_ORIGINS.length > 0) ? 'none' : 'lax',
  },
  email: { siteUrl: allowedSiteUrls },
  // ...
};

app.use('/auth', auth.router({
  cors: { origins: CORS_ORIGINS },
  // ...
}));
```

After OAuth login the browser is automatically redirected back to the front-end
origin that initiated the flow, and subsequent cross-origin `fetch` calls from
that front-end to the API include the auth cookies correctly.

---

### Security considerations

- **Open-redirect protection**: The library never redirects to an origin that
  is not in the configured allowlist.  If an attacker tampers with the OAuth
  `state` parameter to insert a different URL, it is silently discarded.
- **CSRF**: 
  - If your API and front-end share the **same parent domain** (e.g., `api.example.com` and `app.example.com`), you can use `sameSite: 'lax'` and enable `csrf: { enabled: true }`.
  - If they are on **completely different domains** (e.g., `api.com` and `app.com`), you must use `sameSite: 'none'` + `secure: true`. In this case, you **must disable** `csrf` (`enabled: false`) because the double-submit JS pattern cannot read cookies across different domains. You will rely on strict CORS origins for protection.
  See [CSRF Protection](/docs/advanced/csrf).
- **`sameSite: 'none'`** only works over HTTPS.  Never deploy with
  `sameSite: 'none'` and `secure: false` in production.

---

## CSRF Protection for Cookie-Based Auth

## CSRF Protection

node-auth supports the **double-submit cookie pattern** for CSRF protection.

---

### CSRF double-submit flow

```mermaid
sequenceDiagram
    autonumber
    participant B as Browser
    participant JS as JavaScript (app)
    participant S as awesome-node-auth Middleware

    Note over B,S: After login — server sets three cookies
    S-->>B: Set-Cookie: accessToken (HttpOnly, SameSite=Lax)
    S-->>B: Set-Cookie: refreshToken (HttpOnly, SameSite=Lax)
    S-->>B: Set-Cookie: csrf-token (readable by JS, SameSite=Lax)

    Note over JS,S: State-changing request (POST/PUT/DELETE)
    JS->>JS: read csrf-token cookie value
    JS->>S: POST /api/action with Cookie accessToken,csrf-token and X-CSRF-Token headers
    S->>S: compare csrf-token cookie vs X-CSRF-Token header
    alt values match
        S-->>JS: 200 OK
    else mismatch or missing
        S-->>JS: 403 {error: "CSRF token validation failed"}
    end
```

:::info Why this works
An attacker can force the victim's browser to send cookies (CSRF), but cannot read the `csrf-token` cookie value from a different origin due to the Same-Origin Policy. So they cannot set the `X-CSRF-Token` header — the request fails.
:::

---

### Enable CSRF

```typescript
const config: AuthConfig = {
  accessTokenSecret: '…',
  refreshTokenSecret: '…',
  accessTokenExpiresIn: '15m',
  refreshTokenExpiresIn: '7d',
  csrf: {
    enabled: true,
  },
};
```

### Client-Side

#### Vanilla JS / Fetch

```typescript
/**
 * Read the CSRF token from cookies.
 * awesome-node-auth v1.3+ applies cookie-tossing protection: when `secure` is
 * enabled the cookie is named `__Host-csrf-token` (or `__Secure-csrf-token`).
 * Check all three names in priority order to handle dev and production.
 */
function getCsrfToken(): string {
  const get = (name: string) =>
    document.cookie
      .split('; ')
      .find((row) => row.startsWith(`${name}=`))
      ?.split('=')[1] ?? '';
  return get('__Host-csrf-token') || get('__Secure-csrf-token') || get('csrf-token');
}

await fetch('/auth/logout', {
  method: 'POST',
  headers: { 'X-CSRF-Token': getCsrfToken() },
  credentials: 'include',
});
```

#### Angular — handled automatically

The `authInterceptor` in the Angular demo reads the CSRF cookie (checking `__Host-csrf-token`, `__Secure-csrf-token`, and `csrf-token` in priority order) and adds `X-CSRF-Token` automatically on every `POST`/`PUT`/`PATCH`/`DELETE`. See [Angular Integration](/docs/frameworks/angular).

#### Next.js — handled manually

```typescript
// Read the CSRF token, checking prefixed variants first (awesome-node-auth v1.3+)
const csrfToken =
  document.cookie.match(/(?:^|;\s*)__Host-csrf-token=([^;]+)/)?.[1] ??
  document.cookie.match(/(?:^|;\s*)__Secure-csrf-token=([^;]+)/)?.[1] ??
  document.cookie.match(/(?:^|;\s*)csrf-token=([^;]+)/)?.[1] ?? '';
await fetch('/api/auth/logout', {
  method: 'POST',
  headers: { 'X-CSRF-Token': csrfToken },
  credentials: 'include',
});
```

### Cookie details

| Cookie | HttpOnly | Readable by JS | Prefix (`Secure: true`) | Purpose |
|--------|:--------:|:--------------:|:-----------------------:|---------|
| `accessToken` | ✅ | ❌ | `__Host-` / `__Secure-` | Authenticate API requests |
| `refreshToken` | ✅ | ❌ | `__Host-` / `__Secure-` | Obtain new access tokens |
| `csrf-token` | ❌ | ✅ | `__Host-` / `__Secure-` | CSRF double-submit value |

#### Cookie Prefixes (`__Host-` & `__Secure-`)

When `cookieOptions.secure` is enabled, the library automatically applies prefixes to improve security:

- **`__Host-`**: Applied if `Path` is `/` and no `Domain` is specified. This is the most secure option as it prevents any subdomain from overwriting the cookie (Cookie Tossing).
- **`__Secure-`**: Applied if the conditions for `__Host-` are not met but `Secure` is true.

> **`__Host-` and `Path=/`**: The browser specification ([RFC 6265bis](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis)) requires that a `__Host-` cookie **must** have `Path=/`, no `Domain`, and `Secure=true`. The library enforces this automatically: even though the `refreshToken` cookie is normally scoped to `{apiPrefix}/refresh`, when the `__Host-` prefix is applied the path is silently overridden to `/`. This ensures the browser actually stores the cookie rather than silently discarding it. The server-side middleware still validates the token only on the `/refresh` endpoint, so there is no functional security regression.

The built-in client utilities (`auth.js` and `@awesome-lang-auth/angular`) automatically detect these prefixes. If you are using a custom client, ensure you check for all possible names in order of specificity:

```javascript
const csrfToken = 
  getCookie('__Host-csrf-token') || 
  getCookie('__Secure-csrf-token') || 
  getCookie('csrf-token');
```

The `csrf-token` cookie has the **same expiry** as the `accessToken` cookie (default 15 min) and is regenerated on every token refresh.

---

## User Metadata Without Schema Changes

## User Metadata

`IUserMetadataStore` attaches arbitrary key/value metadata to users without changing `BaseUser` or your users table.

### Interface

```typescript
import { IUserMetadataStore } from '@awesome-lang-auth/node';

export class MyUserMetadataStore implements IUserMetadataStore {
  async getMetadata(userId: string): Promise<Record<string, unknown>> {
    const row = await db('user_metadata').where({ userId }).first();
    return row ? JSON.parse(row.data) : {};
  }

  async updateMetadata(userId: string, metadata: Record<string, unknown>): Promise<void> {
    const existing = await this.getMetadata(userId);
    const merged = { ...existing, ...metadata };
    await db('user_metadata')
      .insert({ userId, data: JSON.stringify(merged) })
      .onConflict('userId').merge();
  }

  async clearMetadata(userId: string): Promise<void> {
    await db('user_metadata').where({ userId }).delete();
  }
}
```

### Usage

```typescript
const metaStore = new MyUserMetadataStore();

// Store preferences after login
await metaStore.updateMetadata(userId, { theme: 'dark', lang: 'it' });

// Read them back
const meta = await metaStore.getMetadata(userId);
console.log(meta.theme); // 'dark'
```

Pass `metadataStore` to `auth.router()` to include metadata in `GET /auth/me`.

### Related

- [Extending BaseUser and auth interfaces](/docs/advanced/extending-interfaces) — the typed alternative
- [Custom JWT claims](/docs/advanced/custom-claims) — expose metadata in the access token
- [Database-agnostic auth with IUserStore](/docs/database) — where metadata is persisted
- [Built-in admin panel](/docs/advanced/admin) — view and edit metadata per user

---

## Extending BaseUser and Auth Interfaces in TypeScript

## Extending awesome-node-auth interfaces

This guide explains how to extend the base interfaces provided by `awesome-node-auth` (like `BaseUser`, `BaseTenant`, or `Session`) to include your application's custom fields while maintaining full type-safety and library compatibility.

### The Challenge

Libraries often define "closed" models to ensure internal consistency. However, every application has unique requirements—such as adding a `priviledge` bitmask or `lastLogin` timestamp to the user entity.

In TypeScript, simply extending the class or interface in your code is often not enough if the library's internal functions still expect the original, limited type.

### The Solution: Module Augmentation

TypeScript allows **Declaration Merging**, which lets you "inject" new properties into existing interfaces defined in external modules without modifying the original source code.

#### 1. Create a Declaration File

Create a file named `node-auth.d.ts` (the name doesn't matter, but the `.d.ts` extension does) in your source directory (e.g., `src/types/`).

```typescript
import '@awesome-lang-auth/node';

declare module '@awesome-lang-auth/node' {
  // Augment the BaseUser interface
  interface BaseUser {
    priviledge?: number;
    createdAt?: Date | null;
    updatedAt?: Date | null;
    customMetadata?: Record<string, any>;
  }

  // You can also augment other models
  interface BaseTenant {
    planType?: 'free' | 'pro' | 'enterprise';
  }
}
```

#### 2. Why this is a Best Practice

- **IDE Support**: Your IDE (VS Code, etc.) will immediately show the new fields in autocompletion when working with `BaseUser`.
- **No Type Casting**: You no longer need to use `(user as any).myField`.
- **Library Compatibility**: Any function in `node-auth` that returns or accepts a `BaseUser` will now correctly recognize your custom fields.
- **Single Source of Truth**: You maintain a single `User` entity that traces directly back to the library's foundations.

### Implementation in Stores

When implementing a custom store (e.g., `SqliteUserStore`), you should define a local `User` interface that extends the augmented `BaseUser`:

```typescript
import { BaseUser, IUserStore } from '@awesome-lang-auth/node';

export interface User extends BaseUser {
  // The fields from .d.ts are automatically inherited here
}

export class MyUserStore implements IUserStore {
  async findById(id: string): Promise<User | null> {
    const row = await db.get('SELECT * FROM users WHERE id = ?', id);
    return this.mapRowToUser(row);
  }

  private mapRowToUser(row: any): User {
    return {
      ...row,
      // Map snake_case DB columns to camelCase properties
      firstName: row.first_name,
      priviledge: row.priviledge, // Now type-safe!
    };
  }
}
```

### Summary for the Wiki

Module Augmentation is the standard TypeScript way to extend a library's domain model. It keeps your codebase clean, avoids any hacks, and ensures that your custom database schema and your code's type definitions stay perfectly in sync.

### Related

- [Database-agnostic auth with IUserStore](/docs/database) — the interfaces you implement
- [User metadata without schema changes](/docs/advanced/user-metadata) — extra fields without extending types
- [Custom JWT claims](/docs/advanced/custom-claims) — surface your custom fields in the token
- [Multi-tenant authentication](/docs/advanced/multi-tenancy) — extending BaseTenant

---

## Account Linking Across OAuth Providers

## Account Linking

Account linking lets one user account have **multiple OAuth providers** attached to it — e.g. login with Google *and* GitHub, both resolving to the same user record. awesome-node-auth handles conflict resolution automatically via `IPendingLinkStore`.

---

### OAuth conflict resolution flow

```mermaid
sequenceDiagram
    autonumber
    participant U as User
    participant B as Browser
    participant S as awesome-node-auth Router
    participant DB as IUserStore
    participant LS as ILinkedAccountsStore
    participant PS as IPendingLinkStore
    participant E as Email Provider

    U->>B: Click "Sign in with Google"
    B->>S: GET /auth/oauth/google/callback?code=…
    S->>DB: findByProviderAccount("google", providerAccountId)
    DB-->>S: null (no link found)
    S->>DB: findByEmail(profile.email)
    DB-->>S: user (exists from password signup — CONFLICT)

    S->>PS: stash(email, "google", providerAccountId)
    S-->>B: 409 Conflict {linkToken, email, provider}

    B->>U: "This email is already registered. Verify identity to link accounts."

    Note over U,E: User provides credentials to verify ownership

    B->>S: POST /auth/link-verify {token, loginAfterLinking: true}
    S->>DB: findByAccountLinkToken(token)
    DB-->>S: user
    S->>PS: retrieve(email, "google")
    PS-->>S: {providerAccountId}
    S->>LS: linkAccount(userId, {provider: "google", providerAccountId, email})
    S->>PS: remove(email, "google")
    S->>S: sign token pair (loginAfterLinking)
    S-->>B: 200 + Set-Cookie: accessToken, refreshToken, csrf-token
```

---

### Manual linking flow (authenticated user)

```mermaid
sequenceDiagram
    autonumber
    participant C as Client (authenticated)
    participant S as awesome-node-auth Router
    participant DB as IUserStore
    participant E as Email Provider

    C->>S: POST /auth/link-request {email: "second@example.com"}
    S->>S: generate link token (32 bytes)
    S->>DB: updateAccountLinkToken(userId, email, "email", token, expiry+1h)
    S->>E: sendMagicLink(email, token, link)
    S-->>C: 200 {success: true}

    Note over C,E: User clicks link in email

    C->>S: POST /auth/link-verify {token}
    S->>DB: findByAccountLinkToken(token)
    DB-->>S: user + pendingEmail
    S-->>C: 200 {success: true}
```

### Step 1 — Implement `ILinkedAccountsStore`

```typescript
import { ILinkedAccountsStore, LinkedAccount } from '@awesome-lang-auth/node';

export class MyLinkedAccountsStore implements ILinkedAccountsStore {
  /** Persist a new provider link for the user. */
  async linkAccount(userId: string, account: Omit<LinkedAccount, 'linkedAt'>): Promise<void> {
    await db('linked_accounts').insert({
      userId,
      provider:          account.provider,
      providerAccountId: account.providerAccountId,
      email:             account.email,
      linkedAt:          new Date(),
    });
  }

  /** Remove a specific provider link. */
  async unlinkAccount(userId: string, provider: string, providerAccountId: string): Promise<void> {
    await db('linked_accounts')
      .where({ userId, provider, providerAccountId })
      .delete();
  }

  /** Return all provider links for the user (used by GET /auth/linked-accounts). */
  async getLinkedAccounts(userId: string): Promise<LinkedAccount[]> {
    return db('linked_accounts').where({ userId }).orderBy('linkedAt', 'asc');
  }

  /** Look up a user by provider + providerAccountId (prevents account-takeover). */
  async findUserByProviderAccount(
    provider: string,
    providerAccountId: string,
  ): Promise<{ userId: string } | null> {
    const row = await db('linked_accounts')
      .where({ provider, providerAccountId })
      .first();
    return row ? { userId: row.userId } : null;
  }
}
```

### Step 2 — Implement `IPendingLinkStore` (conflict resolution)

When an OAuth login collides with an existing email, the conflict is stashed here until the user verifies ownership of the existing account.

```typescript
import { IPendingLinkStore, IPendingLink } from '@awesome-lang-auth/node';

export class MyPendingLinkStore implements IPendingLinkStore {
  async createPendingLink(link: IPendingLink): Promise<void> {
    await db('pending_links').insert(link);
  }

  async getPendingLink(token: string): Promise<IPendingLink | null> {
    return db('pending_links').where({ token }).first() ?? null;
  }

  async deletePendingLink(token: string): Promise<void> {
    await db('pending_links').where({ token }).delete();
  }
}
```

The `IPendingLink` shape:

```typescript
interface IPendingLink {
  token:             string;   // random opaque token sent to the user
  userId:            string;   // existing user whose account is being linked
  provider:          string;
  providerAccountId: string;
  email?:            string;
  expiresAt:         Date;
}
```

### Step 3 — Pass stores to the router

```typescript
import { createAuthRouter } from '@awesome-lang-auth/node';

app.use('/auth', createAuthRouter(userStore, config, {
  linkedAccountsStore,
  pendingLinkStore,
  loginAfterLinking: true,   // issue a session automatically after successful linking
}));
```

### Endpoints

| Method | Path | Auth required | Description |
|--------|------|:---:|-------------|
| `GET` | `/auth/linked-accounts` | ✅ | List all linked providers for the current user |
| `DELETE` | `/auth/linked-accounts/:provider/:providerAccountId` | ✅ | Unlink a specific provider |
| `POST` | `/auth/link-request` | ✅ | Request to link a new email address to the current account |
| `POST` | `/auth/link-verify` | ❌ | Verify a pending link token and complete linking |

#### `GET /auth/linked-accounts` — response

```json
[
  {
    "provider": "google",
    "providerAccountId": "1234567890",
    "email": "user@gmail.com",
    "linkedAt": "2024-01-15T10:30:00Z"
  },
  {
    "provider": "github",
    "providerAccountId": "987654",
    "email": "user@github.com",
    "linkedAt": "2024-02-20T14:15:00Z"
  }
]
```

#### `POST /auth/link-verify` — body

```json
{
  "token": "<pending-link-token>"
}
```

On success (with `loginAfterLinking: true`), returns a standard token pair and sets HttpOnly cookies.

### Linking a new email explicitly

A logged-in user can add a second email to their account:

```bash
# 1. Request linking — sends a verification email to the new address
POST /auth/link-request
Authorization: Bearer <access-token>
{ "email": "second@example.com" }

# 2. User clicks the link in the email
POST /auth/link-verify
{ "token": "<token-from-email>" }
```

:::info
The magic-link strategy's `onSendMagicLink` callback is reused for the link-request email, so no extra mailer config is needed.
:::

### Conflict auto-detection during OAuth

When a user tries to OAuth-login and the provider email matches an existing local account:

1. The conflict is detected in `findOrCreateUser` inside your OAuth strategy.
2. A `IPendingLink` record is created automatically.
3. The OAuth callback returns a `409 Conflict` with a `linkToken` field.
4. Your frontend prompts the user: *"This email is already registered. Verify your identity to link accounts."*
5. User completes verification → `POST /auth/link-verify` with the `linkToken`.

:::caution
Always implement `findByProviderAccount` in your `IUserStore` to look up users by provider ID rather than email alone. This prevents account-takeover via email spoofing.
:::

### Related

- [OAuth2 social login](/docs/authentication/oauth) — the providers being linked
- [Email verification modes](/docs/advanced/email-verification) — how conflicting emails are resolved
- [Custom JWT claims](/docs/advanced/custom-claims) — expose the linked providers in the token
- [Built-in admin panel](/docs/advanced/admin) — inspect linked identities per user

---

## Built-in Admin Panel for Users and Sessions

## Admin Panel

`createAdminRouter` mounts a **self-contained admin dashboard** — both a REST API and a built-in vanilla-JS UI — at any path. No external frontend build step required.

  
  
    The built-in Admin Panel — no dependencies, no build step - Control Tab
  

---

  
  
    The built-in Admin Panel — no dependencies, no build step - Api Keys Tab
  

---

### Admin authentication flow (v1.8.2+)

```mermaid
sequenceDiagram
    autonumber
    participant Browser
    participant Guard as Admin Guard (server-side)
    participant AdminApp as Admin Router (Local POST)
    participant Login as App Login Page (Optional)

    Browser->>Guard: GET /admin/
    Guard->>Guard: verify JWT (cookie: accessToken / __Host-accessToken)
    alt No valid session
        alt loginPath is configured
            Guard-->>Browser: 302 → {loginPath}?redirect=/admin
            Browser->>Login: user logs in via app
            Login-->>Browser: issues JWT (cookie)
        else Self-Contained login (default)
            Guard-->>Browser: 200 — Admin Shell with Login Form
            Browser->>AdminApp: POST /admin/login (Email + Password)
            AdminApp->>AdminApp: verify rootUser OR adminSecret OR userStore
            AdminApp-->>Browser: 200 (JWT cookie set)
            AdminApp->>Browser: location.reload()
        end
        Browser->>Guard: GET /admin/ (now authenticated)
    end
    Guard->>Guard: evaluate accessPolicy
    Guard-->>Browser: 200 — Full Admin Dashboard
```

### Setup

**Step 1:** Import and mount the admin router.

```typescript
import express from 'express';
import { AuthConfigurator, createAdminRouter } from '@awesome-lang-auth/node';
import type { AdminOptions, AdminAccessPolicy } from '@awesome-lang-auth/node';

const app = express();
app.use(express.json());

const auth = new AuthConfigurator(config, userStore);
app.use(auth.buildAllRouters({
  admin: {
    // Session-based access control (v1.8.0+)
    accessPolicy: 'first-user', // see Access Policy section below
    sessionStore,         // optional — enables Sessions tab
    rbacStore,            // optional — enables Roles & Permissions tab
    tenantStore,          // optional — enables Tenants tab
    userMetadataStore,    // optional — enables Metadata editor per user
    settingsStore,        // optional — enables Control tab (email policy, 2FA policy)
    linkedAccountsStore,  // optional — shows Linked Accounts in user detail
    templateStore,        // optional — enables 📧 Email & UI templates tab
  },
}));

app.listen(3000);
```

**Step 2:** Open the admin UI in your browser.

```
http://localhost:3000/admin/
```

#### Authentication Fallback
By default, if you are not authenticated, the Admin UI will serve its own **built-in login form** (Email + Password) that speaks directly to your `/auth/login` endpoint. This allows for a zero-configuration admin panel even in headless or API-only projects.

If you prefer to use your own application's login page, you can configure the `loginPath` option (see below).

### Access Policy

The `accessPolicy` option controls who may access the Admin UI and REST API:

| Policy | Description |
|--------|-------------|
| `'first-user'` | Only the first registered user (lowest-index in `listUsers`) is granted access. Ideal for single-owner setups. |
| `'is-admin-flag'` | Only users with `BaseUser.isAdmin === true` are granted access. |
| `'open'` | No restriction — all authenticated users are granted access. Use only behind a VPN or IP allow-list. |
| `(user, rbacStore?) => boolean` | Custom async predicate — return `true` to grant access. |

#### Configuration Options (`AdminOptions`)

| Option | Type | Description |
|--------|------|-------------|
| `accessPolicy` | `AdminAccessPolicy` | **Required.** Defines who can access the panel. |
| `jwtSecret` | `string` | **Required (if not open).** Must match `AuthConfig.accessTokenSecret`. |
| `loginPath` | `string` | *Optional.* Path to redirect unauthenticated browser requests. If omitted, uses the built-in login form. |
| `apiPrefix` | `string` | *Optional.* The base path where the main Auth router is mounted (default: `/auth`). Used to resolve profile links. |
| `cookiePrefix`| `string` | *Optional.* Explicit prefix for auth cookies (e.g., `__Host-` or `__Secure-`). Automatically detected if omitted. |
| `rootUser` | `RootUser` | *Optional.* An emergency `{ email, passwordHash }` (bcrypt) that bypasses the `userStore` for Admin login. |
| `adminSecret`| `string` | *Optional (Legacy).* If set, the login form allows "Bootstrap Mode": leave email blank and log in with just this password. |
| `swagger` | `boolean` | *Optional.* Enable the built-in Swagger UI at `/admin/swagger`. |
| `...stores` | `IStore` | *Optional.* Pass various stores (RBAC, Sessions, etc.) to enable corresponding tabs. |

#### Example: custom predicate using RBAC

```typescript
app.use('/admin', createAdminRouter(userStore, {
  accessPolicy: async (user, rbacStore) => {
    if (!rbacStore) return user.isAdmin === true;
    return user.roles.includes('superadmin');
  },
  jwtSecret: process.env.ACCESS_TOKEN_SECRET!,
  rbacStore,
}));
```

### Two login endpoints, two audiences

- `/auth/ui/login` — end-user login
- `/auth/admin/login` — admin panel login

Link customers to `/auth/ui/login`. The admin login form is only for operators managing the dashboard.

:::tip Migration from `adminSecret`
If you are upgrading from v1.7 or earlier, `adminSecret` has been **removed** in v1.8.0. You must switch to `accessPolicy` + `jwtSecret` as shown in the Setup section above. This change enables more granular security and better integration with your application's session system.
:::

:::caution Production security
Mount the admin panel behind a VPN, IP allowlist, or internal-only network in production. The panel has full read/write access to users, sessions, roles and settings.
:::

### Bootstrap & Root Access

Version 1.8.2 introduces two ways to access the Admin UI without having a pre-existing user in your database:

#### 1. Root User (Recommended)
Pass a bcrypt-hashed password hash to `AdminOptions.rootUser`. This user is "virtual" — they don't exist in your `IUserStore`, but can log in to the Admin UI to perform initial setup.

```typescript
app.use('/admin', createAdminRouter(userStore, {
  accessPolicy: 'first-user',
  jwtSecret: process.env.ACCESS_TOKEN_SECRET!,
  rootUser: {
    email: 'admin@internal.com',
    passwordHash: '$2a$10$xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', // bcrypt hash
  }
}));
```

#### 2. Bootstrap Mode (Password-only)
If `adminSecret` (legacy) is configured, the built-in login form allows you to **leave the email empty** and log in using only the secret as the password. This is useful for first-time setup in environments where no users have been created yet.

Once logged in, you can create your first "real" admin user and then remove the `adminSecret`.

### Dashboard Tabs

Each tab is activated automatically when you pass the corresponding store:

| Store / Option | Unlocks |
|---|---|
| `sessionStore` | Sessions tab |
| `rbacStore` | Roles & Permissions tab |
| `tenantStore` | Tenants tab |
| `userMetadataStore` | Metadata section in user detail |
| `settingsStore` | ⚙️ Control tab |
| `linkedAccountsStore` | Linked Accounts column |
| `apiKeyStore` | 🔑 API Keys tab |
| `webhookStore` | 🔗 Webhooks tab |
| `templateStore` (on `AuthConfig`) | Email & UI tab |
| `uploadDir` + `uploadBaseUrl` | Logo upload in branding |

| Tab | Required store | Features |
|-----|----------------|----------|
| **Users** | `IUserStore.listUsers` | Paginated user table, search by email, delete users, open Manage panel |
| **Manage** (per-user) | — | View profile, reset password, revoke refresh token, toggle email verification, toggle 2FA |
| **Sessions** | `ISessionStore` | All active sessions across all users; revoke by session handle |
| **Roles & Permissions** | `IRolesPermissionsStore` | List roles, create/delete roles, assign permissions |
| **Tenants** | `ITenantStore` | List tenants, create/delete tenants, manage members |
| **Linked Accounts** | `ILinkedAccountsStore` | View OAuth provider links per user |
| **🔗 Webhooks** | `IWebhookStore` | Manage outgoing webhooks **and** inbound dynamic execution configs |
| **⚙️ Control** | `ISettingsStore` | Toggle email verification mode (`none`/`lazy`/`strict`), 2FA policy, and global webhook action enablement |
| **📧 Email & UI** | `ITemplateStore` | Live editor for email templates (HTML/Text + per-language translations) and UI i18n strings |

### Settings Store

The Control tab lets admins change runtime auth policy. Implement `ISettingsStore`:

```typescript
import { ISettingsStore, AuthSettings } from '@awesome-lang-auth/node';

// Simple in-memory implementation (replace with DB in production)
let settings: Partial<AuthSettings> = {};

const settingsStore: ISettingsStore = {
  async getSettings(): Promise<Partial<AuthSettings>> {
    return { ...settings };
  },
  async updateSettings(patch: Partial<AuthSettings>): Promise<void> {
    Object.assign(settings, patch);
  },
};
```

Then pass it to both `AuthConfigurator` and `createAdminRouter`:

```typescript
const auth = new AuthConfigurator(
  { ...config, settingsStore },
  userStore
);

app.use('/admin', createAdminRouter(userStore, {
  accessPolicy: 'first-user',
  jwtSecret: process.env.ACCESS_TOKEN_SECRET!,
  settingsStore,
}));
```

### REST API Reference

All admin endpoints require a valid JWT access token in `Authorization: Bearer <token>`.

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/admin/api/users` | List users (paginated, `?offset=0&limit=20&filter=email`) |
| `GET` | `/admin/api/users/:id` | Get user details |
| `DELETE` | `/admin/api/users/:id` | Delete user and all related data |
| `GET` | `/admin/api/users/:id/metadata` | Get user metadata key/value pairs |
| `PUT` | `/admin/api/users/:id/metadata` | Set/update user metadata |
| `GET` | `/admin/api/users/:id/linked-accounts` | List OAuth provider links for user |
| `GET` | `/admin/api/users/:id/roles` | List roles assigned to user |
| `POST` | `/admin/api/users/:id/roles` | Assign a role to user |
| `DELETE` | `/admin/api/users/:id/roles/:role` | Remove a role from user |
| `GET` | `/admin/api/users/:id/tenants` | List tenants the user belongs to |
| `POST` | `/admin/api/2fa-policy` | Batch-enable or disable 2FA for users |
| `GET` | `/admin/api/sessions` | List all active sessions |
| `DELETE` | `/admin/api/sessions/:handle` | Revoke a session by handle |
| `GET` | `/admin/api/roles` | List all roles |
| `POST` | `/admin/api/roles` | Create a new role |
| `DELETE` | `/admin/api/roles/:name` | Delete a role |
| `GET` | `/admin/api/tenants` | List all tenants |
| `POST` | `/admin/api/tenants` | Create a tenant |
| `DELETE` | `/admin/api/tenants/:id` | Delete a tenant |
| `GET` | `/admin/api/tenants/:id/users` | List users in a tenant |
| `POST` | `/admin/api/tenants/:id/users` | Add a user to a tenant |
| `DELETE` | `/admin/api/tenants/:id/users/:userId` | Remove a user from a tenant |
| `GET` | `/admin/api/settings` | Get current auth settings |
| `PUT` | `/admin/api/settings` | Update auth settings |
| `GET` | `/admin/api/templates/mail` | List all mail templates |
| `POST` | `/admin/api/templates/mail` | Create or update a mail template |
| `GET` | `/admin/api/templates/ui` | List all UI translation sets |
| `POST` | `/admin/api/templates/ui` | Create or update UI translations for a page |
| `GET` | `/admin/api/ping` | Health check |

### Customising `listUsers`

The Users tab requires a `listUsers` method on your `IUserStore`. Add it to your implementation:

```typescript
import { IUserStore, BaseUser } from '@awesome-lang-auth/node';

export class MyUserStore implements IUserStore {
  // ... other methods ...

  async listUsers(limit: number, offset: number): Promise<BaseUser[]> {
    const query = db('users');
    return query.offset(offset).limit(limit);
  }
}
```

---

### 🔗 Webhooks tab

The Webhooks tab is enabled by passing an `IWebhookStore` to `createAdminRouter`. It manages **both outgoing and inbound webhooks** — they are fundamentally different in purpose and configuration.

```typescript
app.use('/admin', createAdminRouter(userStore, {
  accessPolicy: 'first-user',
  jwtSecret: process.env.ACCESS_TOKEN_SECRET!,
  webhookStore: myWebhookStore,   // enables the Webhooks tab
  settingsStore: mySettingsStore, // enables the Control tab (for global action toggles)
}));
```

---

#### Outgoing webhooks (library → external service)

Outgoing webhooks forward `AuthEventBus` events to external HTTP endpoints as HMAC-signed JSON POSTs.

```mermaid
flowchart LR
    Bus["AuthEventBus\nevent fired"] --> Tools["AuthTools"]
    Tools --> Store["IWebhookStore\nfindByEvent()"]
    Store --> Sender["WebhookSender\nHMAC-SHA256"]
    Sender --> Ext["External endpoint\n(Slack, Stripe, etc.)"]
```

In the **Webhooks tab** click **+ Register webhook** and fill in:

| Field | Example | Description |
|-------|---------|-------------|
| URL | `https://hooks.slack.com/...` | Destination endpoint |
| Events | `identity.auth.login.success` or `*` | Events that trigger delivery |
| Secret | `whsec_…` | Optional HMAC signing secret |
| Tenant | *(leave empty)* | Scope to a specific tenant, or global |

Outgoing webhooks are delivered with retry and exponential back-off. See the full [Outgoing Webhooks guide](/docs/advanced/webhooks) for payload format and signature verification.

---

#### Inbound webhooks — dynamic scripts (external service → library)

Inbound webhooks receive HTTP `POST` calls **from** external services (e.g. Stripe, GitHub, Paddle) and execute a **JavaScript script through Node.js `node:vm`**. The functions the script receives in `actions` are governed by the admin — each action must be explicitly enabled globally (Control tab) **and** assigned to the specific webhook.

:::danger Inbound scripts run with the server's privileges
`node:vm` is not a security mechanism, so the script is **not sandboxed**: it runs with the privileges of the server process and can run arbitrary code on the server. Only fully trusted operators may write a webhook script, whether through the webhook store or this admin console. See [awesome-node-auth#10](https://github.com/awesome-lang-auth/awesome-node-auth/issues/10).
:::

```mermaid
sequenceDiagram
    participant Ext as External service<br/>(e.g. Stripe)
    participant Router as POST /tools/webhook/:provider
    participant Store as IWebhookStore
    participant Settings as ISettingsStore
    participant VM as Node.js vm module
    participant Bus as AuthEventBus

    Ext->>Router: POST /tools/webhook/stripe<br/>{ type: "customer.subscription.deleted", … }
    Router->>Store: findByProvider("stripe")
    Store-->>Router: { jsScript, allowedActions }
    Router->>Settings: getSettings()
    Settings-->>Router: { enabledWebhookActions: ["billing.cancel"] }
    Router->>Router: intersect(enabledWebhookActions ∩ allowedActions)
    Router->>VM: run jsScript with { body, actions, result:null }
    VM-->>Router: result = { event, data }
    Router->>Bus: track(event, data)
    Bus-->>Router: event dispatched
    Router-->>Ext: 200 { ok: true }
```

##### Step 1 — Expose service methods as injectable actions

```typescript
import { webhookAction, ActionRegistry } from '@awesome-lang-auth/node';

class BillingService {
  @webhookAction({
    id:          'billing.cancel',
    label:       'Cancel subscription',
    category:    'Billing',
    description: 'Marks a subscription as cancelled in the billing database.',
  })
  async cancel(subscriptionId: string): Promise<void> {
    await db.subscriptions.update({ id: subscriptionId }, { status: 'cancelled' });
  }
}

// Register a bound method — REQUIRED for instance methods
const svc = new BillingService();
ActionRegistry.register({
  id: 'billing.cancel', label: 'Cancel subscription',
  category: 'Billing', description: '',
  fn: svc.cancel.bind(svc),
});
```

##### Step 2 — Globally enable actions (Control tab → Webhook Actions)

The **Control** tab shows every registered `@webhookAction` grouped by category with toggle switches. An action must be enabled here before it can be used by any inbound webhook script.

If an action declares `dependsOn: ['other.action.id']`, its toggle is locked until all dependencies are also enabled.

##### Step 3 — Configure an inbound webhook (Webhooks tab)

Click **+ Register webhook** and switch the type to **Inbound (dynamic)**:

| Field | Example | Description |
|-------|---------|-------------|
| Provider name | `stripe` | Matches `:provider` in `POST /tools/webhook/stripe` |
| Allowed actions | ☑ `billing.cancel` | Subset of globally-enabled actions for this script only |
| JavaScript | see below | Body run through `node:vm` with the server's privileges |

**Example script:**

```js
// Available globals: body (request payload), actions (filtered), result (write to emit an event)
if (body.type === 'customer.subscription.deleted') {
  const subId = body.data.object.id;
  const userId = body.data.object.metadata.userId;

  await actions['billing.cancel'](subId);

  result = {
    event: 'identity.tenant.user.removed',
    data:  { subscriptionId: subId, userId },
  };
}
// If result stays null the webhook is silently acknowledged (HTTP 200, no event emitted)
```

##### Governance rules

| Rule | Behaviour |
|------|-----------|
| Action not in `enabledWebhookActions` | Not passed to the script in `actions`, even if in `allowedActions` |
| Action's `dependsOn` not met | Not passed to the script in `actions` |
| Script throws, or its synchronous part exceeds 5 s | Error logged; HTTP 200 returned (no crash). Asynchronous work is not bounded by the timeout |
| `result` is null | Silently acknowledged; no event emitted |

:::note Action governance is not isolation
Each inbound webhook receives in `actions` only the **intersection** of globally-enabled actions **and** its own `allowedActions` list. This decides which registered actions a script is handed; it does not confine the script, which runs with the server's privileges (see the warning above).
:::

##### Step 4 — Wire stores into the tools router

```typescript
app.use('/tools', createToolsRouter(tools, {
  webhookStore:  myWebhookStore,   // findByProvider() required for inbound
  settingsStore: mySettingsStore,  // reads enabledWebhookActions
}));
```

See the [Webhooks guide → Dynamic inbound execution](/docs/advanced/webhooks#dynamic-inbound-execution) for the full API reference.

---

### Webhook Actions panel (⚙️ Control tab)

When your application registers `@webhookAction`-decorated methods, the **Control** tab shows a **Webhook Actions** sub-panel where you can globally enable or disable each action with a toggle switch.

Actions are grouped by category. If an action declares `dependsOn`, its toggle is disabled until all its dependencies are enabled.

```typescript
import { webhookAction, ActionRegistry } from '@awesome-lang-auth/node';

class BillingService {
  @webhookAction({
    id:          'billing.cancelSubscription',
    label:       'Cancel subscription',
    category:    'Billing',
    description: 'Marks a subscription as cancelled in the billing database.',
  })
  async cancelSubscription(subscriptionId: string): Promise<void> {
    await db.subscriptions.update({ id: subscriptionId }, { status: 'cancelled' });
  }
}

// Register the bound instance so inbound scripts can call it
const billing = new BillingService();
ActionRegistry.register({
  id:          'billing.cancelSubscription',
  label:       'Cancel subscription',
  category:    'Billing',
  description: 'Marks a subscription as cancelled in the billing database.',
  fn:          billing.cancelSubscription.bind(billing),
});
```

Pass both stores to the tools router to enable inbound webhook scripts:

```typescript
app.use('/tools', createToolsRouter(tools, {
  webhookStore:  myWebhookStore,   // provides findByProvider()
  settingsStore: mySettingsStore,  // provides enabledWebhookActions
}));
```

See the [Webhooks](/docs/advanced/webhooks#dynamic-inbound-execution) guide for the full dynamic execution reference.

---

### 📧 Email & UI Templates tab {#email--ui-templates-tab}

The **Email & UI** tab is enabled by passing an `ITemplateStore` to `createAdminRouter`. It provides a full live editor for:

- **Email templates** — HTML body, plain-text body, live preview pane, per-language translation grid, and click-to-insert variable chips
- **UI translations** — per-page `data-i18n` key/value grid used to localise the built-in login/register/forgot-password pages

```typescript
import { MemoryTemplateStore } from '@awesome-lang-auth/node';

const templateStore = new MemoryTemplateStore(); // swap for a DB implementation in production

app.use('/admin', createAdminRouter(userStore, {
  accessPolicy:  'first-user',
  jwtSecret:     process.env.ACCESS_TOKEN_SECRET!,
  templateStore,   // ← enables the 📧 Email & UI tab
}));
```

#### Email template editor

The editor shows a two-panel layout: the left panel contains the editable fields and the right panel renders a **live sandboxed preview** of the template as you type.

| Section | Description |
|---------|-------------|
| **HTML Body** | Full HTML with `{{T.key}}` (translation) and `{{VAR}}` (data) placeholders |
| **Text Body** | Plain-text fallback with the same placeholders |
| **Translations** | Per-language tab + key/value grid — add/remove languages and keys without touching JSON |
| **Variable chips** | Each supported `{{VAR}}` and `{{T.key}}` is shown as a clickable chip that inserts at the caret |

**Supported template IDs** (must match exactly what `MailerService` queries):

| Template ID | Sent when |
|-------------|-----------|
| `magic-link` | User requests a passwordless sign-in link |
| `password-reset` | User requests a password reset |
| `verify-email` | User needs to verify their email address |
| `welcome` | User successfully registers |
| `email-changed` | User changes their email address |
| `invitation` | Admin invites a new user |

**Placeholder syntax:**

| Placeholder | Resolved from |
|-------------|---------------|
| `{{VAR}}` | Data variable passed by `MailerService` (e.g. `link`, `token`, `newEmail`) |
| `{{T.key}}` | Translation string for the active language, falling back to `en` |

**Reset to default:** clicking the "Reset to default" button saves empty `baseHtml`/`baseText`, which causes `MailerService` to fall back to the built-in template automatically.

#### UI translations editor

The UI translations editor lists all built-in pages derived from the actual HTML source files. Select a page to open a per-language key/value grid pre-populated with every `data-i18n` key defined in that page's HTML.

**Pages and their keys:**

| Page | Description |
|------|-------------|
| `login` | Login page |
| `register` | Registration page |
| `forgot-password` | Forgot-password page |
| `reset-password` | Password-reset page |
| `verify-email` | Email-verification landing page |
| `2fa` | Two-factor authentication page |
| `magic-link` | Magic-link request page |
| `link-verify` | Account-link verification landing |
| `account-conflict` | OAuth account-conflict resolution page |

The complete key list for each page is generated from the HTML source by `npm run extract-i18n` (writes `src/ui/assets/ui-i18n-keys.json`).

The language is resolved from the `?lang=` query parameter on the UI page request. See [Built-in UI → Internationalization (i18n)](/docs/advanced/built-in-ui#internationalization-i18n) for the full flow.

> For the full interface definition see [ITemplateStore API Reference](/docs/api-reference/template-store).

---

## Bearer Token Mode for Mobile and Native Apps

## Bearer Token Mode (Native / Mobile Clients)

By default, awesome-node-auth delivers tokens via **HttpOnly cookies** (recommended for web apps).  
For **native mobile clients** (iOS, Android, Flutter, React Native) that cannot use browser cookies, opt into bearer-token delivery by sending `X-Auth-Strategy: bearer`.

:::info Web apps
If you are building a web application (Angular, Next.js, React, Vue…), **do not use bearer mode**. Use `withCredentials: true` and let the browser manage cookies. See the [Angular](/docs/frameworks/angular), [Next.js](/docs/frameworks/nextjs), or [Express](/docs/frameworks/express) guides.
:::

---

### Bearer token flow (mobile client)

```mermaid
sequenceDiagram
    autonumber
    participant App as Mobile App
    participant S as awesome-node-auth Router
    participant KS as Secure Storage (Keychain/Keystore)

    Note over App,KS: Login
    App->>S: POST /auth/login {email, password}<br/>X-Auth-Strategy: bearer
    S-->>App: 200 {success: true, accessToken, refreshToken}
    App->>KS: secureStore("accessToken", accessToken)
    App->>KS: secureStore("refreshToken", refreshToken)

    Note over App,S: Authenticated request
    App->>KS: secureRead("accessToken")
    KS-->>App: accessToken
    App->>S: GET /api/profile<br/>Authorization: Bearer accessToken
    S-->>App: 200 {sub, email, role}

    Note over App,S: Access token expired → refresh
    App->>S: POST /auth/refresh {refreshToken}<br/>X-Auth-Strategy: bearer
    S-->>App: 200 {success: true, accessToken, refreshToken}
    App->>KS: update stored tokens

    Note over App,S: Logout
    App->>S: POST /auth/logout<br/>Authorization: Bearer accessToken
    S-->>App: 200 {success: true}
    App->>KS: clearAll()
```

---

### Opting into bearer mode

Add `X-Auth-Strategy: bearer` to every request that issues tokens:

| Endpoint | With bearer header: response includes |
|----------|---------------------------------------|
| `POST /auth/login` | `{accessToken, refreshToken}` in body |
| `POST /auth/refresh` | `{accessToken, refreshToken}` in body |
| `POST /auth/2fa/verify` | `{accessToken, refreshToken}` in body |
| `POST /auth/magic-link/verify` | `{accessToken, refreshToken}` in body |
| `POST /auth/sms/verify` | `{accessToken, refreshToken}` in body |

---

### Login and token storage

```typescript
const res = await fetch('/auth/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Auth-Strategy': 'bearer',   // ← opts into bearer mode
  },
  body: JSON.stringify({ email, password }),
});

const { accessToken, refreshToken } = await res.json();
// Store securely — use Keychain (iOS), Keystore/EncryptedSharedPreferences (Android),
// flutter_secure_storage (Flutter). Never use localStorage on web.
```

### Authenticated requests

```typescript
async function authFetch(url: string, options: RequestInit = {}) {
  const res = await fetch(url, {
    ...options,
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${currentAccessToken}`,
      ...options.headers,
    },
  });

  if (res.status === 401) {
    const refreshed = await refreshAccessToken();
    if (refreshed) return authFetch(url, options);  // retry once
    redirectToLogin();
  }
  return res;
}
```

### Refreshing the access token

```typescript
async function refreshAccessToken(): Promise<boolean> {
  try {
    const res = await fetch('/auth/refresh', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-Auth-Strategy': 'bearer',
      },
      body: JSON.stringify({ refreshToken: storedRefreshToken }),
    });
    if (!res.ok) return false;
    const { accessToken, refreshToken } = await res.json();
    currentAccessToken = accessToken;
    storedRefreshToken = refreshToken;
    return true;
  } catch {
    return false;
  }
}
```

### Protecting server routes

The `auth.middleware()` accepts both bearer tokens and cookies automatically:

```typescript
app.get('/api/profile', auth.middleware(), (req, res) => {
  res.json(req.user);   // decoded JWT payload
});
```

### Token payload shape

```typescript
interface AccessTokenPayload {
  sub:   string;   // user ID
  email: string;
  role?: string;
  loginProvider?: string;
  isEmailVerified?: boolean;
  isTotpEnabled?: boolean;
  iat:   number;
  exp:   number;
  // …any custom claims from buildTokenPayload
}
```

### Security checklist

- ✅ Access token in **platform secure storage** (Keychain / Keystore / flutter_secure_storage)
- ✅ Refresh token also in secure storage — refresh on every app launch
- ✅ Always send `X-Auth-Strategy: bearer` on login and refresh endpoints
- ✅ HTTPS in production
- ✅ Short access token TTL (15 min default)
- ✅ Retry once on 401 using the stored refresh token, then redirect to login
- ✅ On logout, call `POST /auth/logout` (with `Authorization: Bearer <token>`) to invalidate server-side

---

## Built-in HTTP Mailer for Transactional Email

## Built-in HTTP Mailer

node-auth ships a **built-in HTTP mailer transport** (`MailerService`) that sends transactional emails by posting JSON payloads to any HTTP email relay — Mailgun, SendGrid, Brevo, Postmark, or a custom gateway.

No SMTP setup needed. Point it at your relay's endpoint, set an API key, and every auth email (password reset, magic link, welcome, email verification, email-changed notification) is sent automatically using built-in bilingual (🇬🇧 English / 🇮🇹 Italian) templates.

---

### How it works

```mermaid
sequenceDiagram
    autonumber
    participant S as awesome-node-auth Router
    participant MS as MailerService
    participant R as HTTP Email Relay

    Note over S,R: e.g. POST /auth/forgot-password

    S->>MS: sendPasswordReset(email, token, link, lang)
    MS->>MS: render template (en/it) → {subject, html, text}
    MS->>R: POST {endpoint}<br/>X-API-Key: {apiKey}<br/>Content-Type: application/json<br/>{to, subject, html, text, from, fromName, provider}
    R-->>MS: 200 OK
    MS-->>S: resolved
```

---

### Configuration

```typescript
import { AuthConfigurator } from '@awesome-lang-auth/node';

const auth = new AuthConfigurator({
  accessTokenSecret:  process.env.ACCESS_TOKEN_SECRET!,
  refreshTokenSecret: process.env.REFRESH_TOKEN_SECRET!,

  email: {
    // Single URL (classic, works as before)
    siteUrl: 'https://yourapp.com',

    // — OR — array of allowed front-end origins (dynamic mode).
    // For email links the FIRST entry is used as the base URL.
    // For OAuth redirects the URL is resolved dynamically from the request
    // Origin/Referer header (see CORS & Dynamic siteUrl guide).
    // siteUrl: ['https://app.example.com', 'https://admin.example.com'],

    mailer: {
      endpoint:    process.env.MAILER_ENDPOINT!,   // e.g. https://api.brevo.com/v3/smtp/email
      apiKey:      process.env.MAILER_API_KEY!,
      from:        'no-reply@yourapp.com',
      fromName:    'Your App',             // optional sender display name
      provider:    'brevo',                // optional — forwarded to the relay as-is
      defaultLang: 'en',                   // 'en' (default) | 'it'
    },
  },
}, userStore);
```

#### MailerConfig reference

| Field | Type | Required | Description |
|-------|------|:--------:|-------------|
| `endpoint` | `string` | ✅ | Full URL of the HTTP relay (`POST` target) |
| `apiKey` | `string` | ✅ | Sent as `X-API-Key` header |
| `from` | `string` | ✅ | Sender email address |
| `fromName` | `string` | ❌ | Sender display name |
| `provider` | `string` | ❌ | Forwarded to relay as `provider` field |
| `defaultLang` | `'en' \| 'it'` | ❌ | Default template language (default: `'en'`) |

---

### Request body sent to the relay

```json
{
  "to":       "user@example.com",
  "subject":  "Reset your password",
  "html":     "<p>Click <a href=\"…\">here</a> to reset…</p>",
  "text":     "Click here to reset: https://…",
  "from":     "no-reply@yourapp.com",
  "fromName": "Your App",
  "provider": "brevo"
}
```

The relay receives a standard `POST` with `Content-Type: application/json` and `X-API-Key` header. Adapt to your provider's format in the relay if needed.

---

### Per-request language override

Users can request a specific email language by including `emailLang` in the request body:

```bash
curl -X POST /auth/forgot-password \
  -H 'Content-Type: application/json' \
  -d '{"email":"user@example.com","emailLang":"it"}'
```

Supported values: `'en'`, `'it'`.

---

### Built-in email templates

| Trigger | Method | Template (en) | Template (it) |
|---------|--------|---------------|---------------|
| `POST /auth/forgot-password` | `sendPasswordReset` | "Reset your password" | "Reimposta la tua password" |
| `POST /auth/magic-link/send` | `sendMagicLink` | "Your magic sign-in link" | "Il tuo link di accesso" |
| `POST /auth/register` | `sendWelcome` | "Welcome! Your account has been created" | "Benvenuto! Il tuo account è stato creato" |
| `POST /auth/send-verification-email` | `sendVerificationEmail` | "Verify your email address" | "Verifica il tuo indirizzo email" |
| `POST /auth/change-email/confirm` | `sendEmailChanged` | "Your email address has been updated" | "Il tuo indirizzo email è stato aggiornato" |

---

### Custom callback overrides

If you prefer to send emails yourself (e.g. with a custom template engine), use the callback overrides in `AuthConfig.email`. Callbacks always take priority over the `mailer` transport:

```typescript
const auth = new AuthConfigurator({
  email: {
    siteUrl: 'https://yourapp.com',

    // Override: custom password-reset email
    sendPasswordReset: async (to, token, link, lang) => {
      await myMailer.send({
        to,
        subject: 'Reset your password',
        html: myTemplateEngine.render('password-reset', { link, lang }),
      });
    },

    // Override: custom magic-link email
    sendMagicLink: async (to, token, link, lang) => {
      await myMailer.send({ to, subject: 'Your login link', html: `<a href="${link}">Sign in</a>` });
    },

    // Override: welcome email (e.g. after admin creates user via admin panel)
    sendWelcome: async (to, data, lang) => {
      await myMailer.send({ to, subject: 'Welcome', html: myTemplateEngine.render('welcome', data) });
    },

    // Override: email verification
    sendVerificationEmail: async (to, token, link, lang) => {
      await myMailer.send({ to, subject: 'Verify your email', html: `<a href="${link}">Verify</a>` });
    },

    // Override: email-changed notification
    sendEmailChanged: async (to, newEmail, lang) => {
      await myMailer.send({ to, subject: 'Email updated', html: `Your email is now ${newEmail}` });
    },
  },
}, userStore);
```

---

### Using MailerService standalone

The `MailerService` class is exported and can be used directly in your own services:

```typescript
import { MailerService } from '@awesome-lang-auth/node';

const mailer = new MailerService({
  endpoint:    'https://api.brevo.com/v3/smtp/email',
  apiKey:      process.env.MAILER_API_KEY!,
  from:        'no-reply@yourapp.com',
  defaultLang: 'it',
});

// Send individual emails
await mailer.sendPasswordReset('user@example.com', token, 'https://app.com/reset?token=…');
await mailer.sendMagicLink('user@example.com', token, 'https://app.com/verify?token=…');
await mailer.sendWelcome('user@example.com', { loginUrl: 'https://app.com/login' });
await mailer.sendVerificationEmail('user@example.com', token, 'https://app.com/verify-email?token=…');
await mailer.sendEmailChanged('old@example.com', 'new@example.com');
```

---

### Dynamic `siteUrl` for email links

The `siteUrl` field accepts either a single string or an **array of strings**.
When you have multiple front-end origins (e.g. a public app and an admin panel)
pass an array — the **first entry** is used as the base URL for all email links.

```typescript
email: {
  // First entry is used for all email links (magic link, password reset, etc.)
  siteUrl: ["https://app.example.com", "https://admin.example.com"],
  mailer: { /* … */ },
}
```

For OAuth post-login redirects the URL is resolved **dynamically** from the
`Origin` / `Referer` request header and validated against the same array.
See [CORS & Dynamic siteUrl](/docs/advanced/cors) for the complete guide.

---

### Dynamic templates with `ITemplateStore`

Instead of using the hardcoded bilingual templates, you can override any or all of them at runtime by passing an `ITemplateStore` to `AuthConfigurator`.

When a `templateStore` is provided and a template exists in the store for the requested `templateId`, it is used in place of the built-in fallback. If no custom template is found, the built-in template is used transparently.

#### Setup

```typescript
import { AuthConfigurator, MemoryTemplateStore } from '@awesome-lang-auth/node';
import type { ITemplateStore } from '@awesome-lang-auth/node';

// Use the built-in in-memory store (good for development / testing)
const templateStore: ITemplateStore = new MemoryTemplateStore();

const auth = new AuthConfigurator(
  {
    accessTokenSecret:  process.env.ACCESS_TOKEN_SECRET!,
    refreshTokenSecret: process.env.REFRESH_TOKEN_SECRET!,
    email: {
      siteUrl: 'https://yourapp.com',
      mailer: { endpoint: process.env.MAILER_ENDPOINT!, apiKey: process.env.MAILER_API_KEY!, from: 'noreply@yourapp.com' },
    },
    templateStore,    // ← inject here
  },
  userStore,
);

// Pre-populate a template at startup (or load from DB in production)
await templateStore.updateMailTemplate('magic-link', {
  baseHtml: `<p>{{T.greeting}}</p><p><a href="{{URL}}">{{T.cta}}</a></p>`,
  baseText: `{{T.greeting}}\n{{T.cta}}: {{URL}}`,
  translations: {
    en: { subject: 'Your magic sign-in link', greeting: 'Hello!', cta: 'Click here to sign in' },
    it: { subject: 'Il tuo link di accesso', greeting: 'Ciao!', cta: 'Clicca qui per accedere' },
  },
});
```

Pass the same `templateStore` instance to `createAdminRouter` to manage templates through the Admin UI:

```typescript
app.use('/admin', createAdminRouter(userStore, {
  accessPolicy: 'first-user',
  jwtSecret: process.env.ACCESS_TOKEN_SECRET!,
  templateStore,   // ← enables the 📧 Email & UI tab
}));
```

---

#### Template interpolation syntax

Templates support two interpolation families:

| Syntax | Resolves to | Example |
|--------|-------------|---------|
| `{{T.key}}` | Translation string for the current language | `{{T.subject}}` → `"Reset your password"` |
| `{{KEY}}` | Data variable injected by the sending method | `{{URL}}` → `"https://app.com/reset?token=…"` |

**Available data variables per template ID:**

| Template ID | Data variables |
|-------------|----------------|
| `password-reset` | `{{URL}}` (reset link) |
| `magic-link` | `{{URL}}` (magic link) |
| `welcome` | `{{loginUrl}}` (login page URL) |
| `verify-email` | `{{URL}}` (verification link) |
| `email-changed` | `{{newEmail}}` (new email address) |

Missing variables or translation keys are rendered as `[key]` so you can spot gaps quickly during development.

---

#### Implementing a production `ITemplateStore`

For production, implement `ITemplateStore` against your database (the interface is the same regardless of DB):

```typescript
import type { ITemplateStore, MailTemplate, UiTranslation } from '@awesome-lang-auth/node';

export class MongoTemplateStore implements ITemplateStore {
  constructor(private readonly db: Db) {}

  async getMailTemplate(id: string): Promise<MailTemplate | null> {
    return this.db.collection<MailTemplate>('mail_templates').findOne({ id }) ?? null;
  }
  async listMailTemplates(): Promise<MailTemplate[]> {
    return this.db.collection<MailTemplate>('mail_templates').find().toArray();
  }
  async updateMailTemplate(id: string, tpl: Partial<MailTemplate>): Promise<void> {
    await this.db.collection('mail_templates').updateOne(
      { id },
      { $set: { ...tpl, id } },
      { upsert: true },
    );
  }
  async getUiTranslations(page: string): Promise<UiTranslation | null> {
    return this.db.collection<UiTranslation>('ui_translations').findOne({ page }) ?? null;
  }
  async listUiTranslations(): Promise<UiTranslation[]> {
    return this.db.collection<UiTranslation>('ui_translations').find().toArray();
  }
  async updateUiTranslations(page: string, translations: Record<string, Record<string, string>>): Promise<void> {
    await this.db.collection('ui_translations').updateOne(
      { page },
      { $set: { page, translations } },
      { upsert: true },
    );
  }
}
```

> See [ITemplateStore API Reference](/docs/api-reference/template-store) for the complete interface definition.

---

## Email Verification Modes and Enforcement

## Email Verification

node-auth supports three email-verification enforcement modes:

| Mode | Behaviour |
|------|-----------|
| `'none'` | Email verification is never required (default) |
| `'lazy'` | User may log in until `emailVerificationDeadline` is reached, then login is blocked |
| `'strict'` | Login is blocked immediately if `isEmailVerified !== true` |

---

### Verification flow

```mermaid
sequenceDiagram
    autonumber
    participant C as Client (authenticated)
    participant S as awesome-node-auth Router
    participant DB as IUserStore
    participant E as Email Provider

    C->>S: POST /auth/send-verification-email (accessToken cookie)
    S->>S: generate secure token (32 bytes)
    S->>DB: updateEmailVerificationToken(userId, token, expiry+24h)
    S->>E: sendVerificationEmail(email, token, link)
    S-->>C: 200 {success: true}

    Note over C,E: User clicks verification link in email

    C->>S: GET /auth/verify-email?token={token}
    S->>DB: findByEmailVerificationToken(token)
    DB-->>S: user (validates expiry)
    S->>DB: updateEmailVerified(userId, true)
    S->>DB: updateEmailVerificationToken(userId, null, null)
    S-->>C: 302 redirect to siteUrl or 200 {success: true}
```

---

### Configuration

```typescript
const auth = new AuthConfigurator({
  accessTokenSecret:  process.env.ACCESS_TOKEN_SECRET!,
  refreshTokenSecret: process.env.REFRESH_TOKEN_SECRET!,

  emailVerificationMode: 'lazy',   // 'none' | 'lazy' | 'strict'

  email: {
    siteUrl: 'https://yourapp.com',   // used to build the verification link
    mailer: { /* … see Mailer guide */ },
    // or use the callback override:
    // sendVerificationEmail: async (to, token, link) => { … }
  },
}, userStore);
```

#### Lazy mode: set `emailVerificationDeadline`

In `'lazy'` mode users can log in for a grace period. Set the deadline when creating the user:

```typescript
onRegister: async (data) => {
  const gracePeriodDays = 7;
  const deadline = new Date();
  deadline.setDate(deadline.getDate() + gracePeriodDays);

  return userStore.create({
    email: data.email as string,
    password: await passwordService.hash(data.password as string),
    emailVerificationDeadline: deadline,
  });
},
```

After `emailVerificationDeadline`, `POST /auth/login` returns:

```json
{ "error": "Email verification required", "code": "EMAIL_NOT_VERIFIED" }
```

---

### Implement IUserStore methods

```typescript
// Required for email verification
async updateEmailVerificationToken(userId, token, expiry) { /* … */ }
async updateEmailVerified(userId, isVerified) { /* … */ }
async findByEmailVerificationToken(token) { /* … */ }
```

---

### Endpoints

| Method | Path | Auth | Description |
|--------|------|:---:|-------------|
| `POST` | `/auth/send-verification-email` | ✅ | Generate token + send verification email |
| `GET` | `/auth/verify-email?token={token}` | — | Verify token → mark email as verified |

---

### GET /auth/verify-email redirect

When `email.siteUrl` is configured, the verify endpoint redirects to:

```
{siteUrl}/email-verified?success=true
```

or on failure:

```
{siteUrl}/email-verified?error=INVALID_TOKEN
```

If `siteUrl` is not set, it returns a JSON response `{ "success": true }`.

### Related

- [Built-in HTTP mailer](/docs/advanced/mailer) — how verification emails are delivered
- [Passwordless magic link login](/docs/authentication/magic-link) — logging in also verifies the address
- [Change email flow](/docs/advanced/change-email) — re-verification after an address change
- [Built-in auth UI](/docs/advanced/built-in-ui) — the pages users land on from the email

---

## Change Email Flow with Double Confirmation

## Change Email Flow

Authenticated users can change their email address through a two-step verification flow. The new address must be confirmed by clicking a link sent to it before the change takes effect.

---

### Change email flow

```mermaid
sequenceDiagram
    autonumber
    participant C as Client (authenticated)
    participant S as awesome-node-auth Router
    participant DB as IUserStore
    participant E as Email Provider

    C->>S: POST /auth/change-email/request<br/>{newEmail: "new@example.com"}
    S->>DB: findByEmail(newEmail) — check not already taken
    DB-->>S: null (available)
    S->>S: generate confirmation token (32 bytes)
    S->>DB: updateEmailChangeToken(userId, newEmail, token, expiry+1h)
    S->>E: sendVerificationEmail(newEmail, token, link)
    S-->>C: 200 {success: true}

    Note over C,E: User clicks confirmation link sent to new address

    C->>S: POST /auth/change-email/confirm {token}
    S->>DB: findByEmailChangeToken(token)
    DB-->>S: user (validates expiry + pendingEmail)
    S->>DB: updateEmail(userId, pendingEmail)
    S->>DB: updateEmailChangeToken(userId, null, null, null)
    S->>E: sendEmailChanged(oldEmail, newEmail)
    S-->>C: 200 {success: true}
```

---

### Implement IUserStore methods

```typescript
// Required for the change-email flow
async updateEmailChangeToken(
  userId: string,
  pendingEmail: string | null,
  token: string | null,
  expiry: Date | null,
): Promise<void> { /* … */ }

async updateEmail(userId: string, newEmail: string): Promise<void> { /* … */ }

async findByEmailChangeToken(token: string): Promise<BaseUser | null> { /* … */ }
```

---

### Configuration

```typescript
const auth = new AuthConfigurator({
  email: {
    siteUrl: 'https://yourapp.com',
    mailer: { /* … see Mailer guide */ },
    // Optional override: custom notification email
    sendEmailChanged: async (oldEmail, newEmail, lang) => {
      await myMailer.send({ to: oldEmail, subject: 'Email updated', html: `Your email is now ${newEmail}` });
    },
  },
}, userStore);
```

---

### Endpoints

| Method | Path | Auth | Description |
|--------|------|:---:|-------------|
| `POST` | `/auth/change-email/request` | ✅ | Request email change — sends confirmation to new address |
| `POST` | `/auth/change-email/confirm` | — | Confirm with token → update email in store |

#### `POST /auth/change-email/request`

```json
{ "newEmail": "new@example.com" }
```

Response `200`:
```json
{ "success": true }
```

Errors:
- `409` — email already registered by another user
- `400` — newEmail missing or invalid

#### `POST /auth/change-email/confirm`

```json
{ "token": "<token-from-email>" }
```

Response `200`:
```json
{ "success": true }
```

Errors:
- `400` — token missing, expired, or already used

### Related

- [Email verification modes](/docs/advanced/email-verification) — the verification machinery reused here
- [Built-in HTTP mailer](/docs/advanced/mailer) — how the confirmation email is sent
- [Self-service account deletion](/docs/advanced/account-deletion) — the other self-service operation
- [Auth API endpoints reference](/docs/api-reference/endpoints) — the change-email routes

---

## Self-Service Account Deletion (GDPR)

## Account Deletion

Authenticated users can permanently delete their own account using `DELETE /auth/account`. The library clears the user's session and optionally removes tenant memberships if an `ITenantStore` is provided.

---

### Account deletion flow

```mermaid
sequenceDiagram
    autonumber
    participant C as Client (authenticated)
    participant S as awesome-node-auth Router
    participant DB as IUserStore
    participant TS as ITenantStore (optional)
    participant SS as ISessionStore (optional)

    C->>S: DELETE /auth/account (accessToken cookie)
    S->>S: verifyAccessToken → get userId
    opt ITenantStore provided
        S->>TS: getTenantsForUser(userId)
        TS-->>S: [tenant1, tenant2]
        S->>TS: disassociateUserFromTenant(userId, tenant1)
        S->>TS: disassociateUserFromTenant(userId, tenant2)
    end
    opt ISessionStore provided
        S->>SS: revokeAllSessionsForUser(userId)
    end
    S->>DB: updateRefreshToken(userId, null, null)
    S->>S: clear cookies
    S-->>C: 200 {success: true} + cleared cookies

    Note over C,S: Your app must also delete the user record<br/>from IUserStore (e.g. in a post-hook or middleware)
```

:::caution User record deletion
`DELETE /auth/account` revokes sessions and disassociates tenants, but **does not call `IUserStore.delete`** — that method is not part of the interface. Add a post-hook or route middleware to delete the user record from your database after the endpoint responds.
:::

---

### Usage

Mount the standard auth router — the endpoint is always available:

```typescript
app.use('/auth', auth.router());
```

#### With tenant cleanup

Pass `tenantStore` to also remove the user from all their tenants:

```typescript
app.use('/auth', auth.router({ tenantStore }));
```

#### Client-side

```typescript
// Cookie mode
await fetch('/auth/account', {
  method: 'DELETE',
  credentials: 'include',
});

// Bearer mode
await fetch('/auth/account', {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${accessToken}` },
});
```

---

### Endpoint

| Method | Path | Auth | Description |
|--------|------|:---:|-------------|
| `DELETE` | `/auth/account` | ✅ | Revoke session + optional tenant cleanup |

#### Post-deletion hook example (Express)

```typescript
// Middleware that deletes the user record after /auth/account responds
app.use((req, res, next) => {
  const originalJson = res.json.bind(res);
  res.json = (body: unknown) => {
    if (req.method === 'DELETE' && req.path === '/account' && (body as any)?.success) {
      const userId = (req as any).user?.sub;
      if (userId) userStore.deleteUser(userId).catch(console.error);
    }
    return originalJson(body);
  };
  next();
});
```

### Related

- [Change email flow](/docs/advanced/change-email) — the other self-service account operation
- [Multi-tenant authentication](/docs/advanced/multi-tenancy) — memberships removed on deletion
- [Session management and token revocation](/docs/advanced/sessions) — clearing sessions on delete
- [Auth API endpoints reference](/docs/api-reference/endpoints) — the DELETE /auth/account route

---

## Custom JWT Claims with buildTokenPayload

## Custom JWT Claims (`buildTokenPayload`)

By default, awesome-node-auth embeds these standard claims in every JWT:

```json
{
  "sub": "userId",
  "email": "user@example.com",
  "role": "user",
  "loginProvider": "local",
  "isEmailVerified": true,
  "isTotpEnabled": false,
  "iat": 1700000000,
  "exp": 1700000900
}
```

Use `buildTokenPayload` in `AuthConfig` to merge additional custom claims — tenant IDs, permissions, plan tier, feature flags, or any project-specific data — into **every issued token pair**.

---

### Flow

```mermaid
sequenceDiagram
    autonumber
    participant S as awesome-node-auth Router
    participant DB as IUserStore
    participant BTP as buildTokenPayload callback

    Note over S,BTP: Called on login, refresh, and every token issue

    S->>DB: find user (by credentials, refresh token, or OAuth profile)
    DB-->>S: user {id, email, role, tenantId, permissions, …}
    S->>BTP: buildTokenPayload(user)
    BTP-->>S: {tenantId: "acme", permissions: ["read","write"], plan: "pro"}
    S->>S: merge into base payload: {sub, email, role, …, tenantId, permissions, plan}
    S->>S: jwt.sign(mergedPayload, accessTokenSecret)
    S-->>S: sign refreshToken with same merged payload
```

---

### Configuration

```typescript
import { AuthConfigurator, BaseUser } from '@awesome-lang-auth/node';

// Extend BaseUser with your project-specific fields
interface AppUser extends BaseUser {
  tenantId?: string;
  plan?:     'free' | 'pro' | 'enterprise';
}

const auth = new AuthConfigurator({
  accessTokenSecret:  process.env.ACCESS_TOKEN_SECRET!,
  refreshTokenSecret: process.env.REFRESH_TOKEN_SECRET!,
  accessTokenExpiresIn:  '15m',
  refreshTokenExpiresIn: '7d',

  buildTokenPayload: (user: AppUser) => ({
    tenantId:    user.tenantId,
    plan:        user.plan,
  }),
}, userStore);
```

The returned object is **merged on top** of the standard claims. You cannot override `sub`, `email`, `role`, `iat`, or `exp`.

---

### Reading custom claims server-side

After `auth.middleware()` runs, custom claims are available on `req.user`:

```typescript
app.get('/api/data', auth.middleware(), (req, res) => {
  const { sub, email, tenantId, plan } = req.user as any;
  res.json({ tenantId, plan });
});
```

---

### Reading custom claims client-side (NestJS example)

```typescript
// @CurrentUser() injects req.user which includes all JWT claims
@Get('profile')
@UseGuards(JwtAuthGuard)
getProfile(@CurrentUser() user: { sub: string; email: string; tenantId: string; plan: string }) {
  return user;
}
```

---

### Async buildTokenPayload (loading RBAC from DB)

`buildTokenPayload` can be async. Use it to load permissions at token-issue time:

```typescript
buildTokenPayload: async (user) => {
  const permissions = await rbacStore.getPermissionsForUser(user.id);
  const roles       = await rbacStore.getRolesForUser(user.id);
  return { permissions, roles };
},
```

:::caution Token size
JWT tokens are sent in every request (as cookies). Keep custom claims small — embed IDs and flags, not full objects. A token exceeding ~4 KB may be rejected by some cookie jars.
:::

---

### Common patterns

#### Multi-tenant ID

```typescript
buildTokenPayload: (user) => ({ tenantId: user.tenantId }),
```

#### Role + permissions

```typescript
buildTokenPayload: async (user) => ({
  permissions: await rbacStore.getPermissionsForUser(user.id),
}),
```

#### Feature flags

```typescript
buildTokenPayload: (user) => ({
  features: {
    analytics: user.plan === 'pro' || user.plan === 'enterprise',
    export:    user.plan === 'enterprise',
  },
}),
```

### Related

- [Role-based access control (RBAC)](/docs/advanced/roles-permissions) — the roles you may want in the token
- [Multi-tenant authentication](/docs/advanced/multi-tenancy) — put the tenant id in every claim set
- [Identity provider mode](/docs/advanced/idp-mode) — claims consumed by downstream resource servers
- [Session management and token revocation](/docs/advanced/sessions) — when claims are refreshed

---

## AuthEventBus: Auth Event Names and Payloads

## AuthEventBus & Event Names

`AuthEventBus` is the central event backbone of the tools system. It extends Node's built-in `EventEmitter` and emits standardised `AuthEventPayload` objects so that downstream handlers — telemetry, SSE, webhooks, analytics — can react without coupling to each other.

---

### Architecture

```mermaid
sequenceDiagram
    participant Auth as Auth Router
    participant Bus as AuthEventBus
    participant Tel as Telemetry handler
    participant SSE as SSE handler
    participant WH as Webhook handler

    Auth->>Bus: bus.publish('identity.auth.login.success', payload)
    Bus->>Tel: emit(event, payload)
    Bus->>SSE: emit(event, payload)
    Bus->>WH: emit(event, payload)
    Bus->>Bus: emit('*', payload)
```

---

### Setup

```typescript
import { AuthEventBus } from '@awesome-lang-auth/node';

const bus = new AuthEventBus();
```

Pass `bus` to `AuthConfigurator` to have the auth router publish events automatically:

```typescript
import { AuthConfigurator } from '@awesome-lang-auth/node';

const auth = new AuthConfigurator(config, userStore, { eventBus: bus });
app.use('/auth', auth.router());
```

---

### Publishing events

```typescript
import { AuthEventBus, AuthEventNames } from '@awesome-lang-auth/node';

bus.publish(AuthEventNames.AUTH_LOGIN_SUCCESS, {
  userId: 'user-123',
  tenantId: 'tenant-abc',
  ip: '203.0.113.1',
  userAgent: req.headers['user-agent'],
  data: { method: 'local' },
});
```

---

### Subscribing to events

```typescript
// Specific event
bus.onEvent(AuthEventNames.AUTH_LOGIN_FAILED, (payload) => {
  console.warn('Failed login', payload.userId, payload.ip);
});

// All events via wildcard
bus.onEvent('*', (payload) => {
  metricsCounter.inc({ event: payload.event });
});

// Remove a listener
bus.offEvent(AuthEventNames.AUTH_LOGOUT, myHandler);
```

---

### Event payload

```typescript
interface AuthEventPayload {
  event: string;        // e.g. 'identity.auth.login.success'
  timestamp: string;    // ISO 8601
  data?: unknown;
  userId?: string;
  tenantId?: string;
  sessionId?: string;
  correlationId?: string;
  ip?: string;
  userAgent?: string;
}
```

---

### Full event catalogue (`AuthEventNames`)

| Constant | Event name |
|----------|------------|
| `USER_CREATED` | `identity.user.created` |
| `USER_DELETED` | `identity.user.deleted` |
| `USER_EMAIL_VERIFIED` | `identity.user.email.verified` |
| `USER_PASSWORD_CHANGED` | `identity.user.password.changed` |
| `USER_2FA_ENABLED` | `identity.user.2fa.enabled` |
| `USER_2FA_DISABLED` | `identity.user.2fa.disabled` |
| `USER_LINKED` | `identity.user.linked` |
| `USER_UNLINKED` | `identity.user.unlinked` |
| `SESSION_CREATED` | `identity.session.created` |
| `SESSION_REVOKED` | `identity.session.revoked` |
| `SESSION_EXPIRED` | `identity.session.expired` |
| `SESSION_ROTATED` | `identity.session.rotated` |
| `AUTH_LOGIN_SUCCESS` | `identity.auth.login.success` |
| `AUTH_LOGIN_FAILED` | `identity.auth.login.failed` |
| `AUTH_LOGOUT` | `identity.auth.logout` |
| `AUTH_OAUTH_SUCCESS` | `identity.auth.oauth.success` |
| `AUTH_OAUTH_CONFLICT` | `identity.auth.oauth.conflict` |
| `TENANT_CREATED` | `identity.tenant.created` |
| `TENANT_DELETED` | `identity.tenant.deleted` |
| `TENANT_USER_ADDED` | `identity.tenant.user.added` |
| `TENANT_USER_REMOVED` | `identity.tenant.user.removed` |
| `ROLE_ASSIGNED` | `identity.role.assigned` |
| `ROLE_REVOKED` | `identity.role.revoked` |
| `PERMISSION_GRANTED` | `identity.permission.granted` |
| `PERMISSION_REVOKED` | `identity.permission.revoked` |

---

### API reference

```typescript
class AuthEventBus extends EventEmitter {
  publish(eventName: string, payload: Partial<AuthEventPayload>): void;
  onEvent(eventName: string, handler: (payload: AuthEventPayload) => void): this;
  offEvent(eventName: string, handler: (payload: AuthEventPayload) => void): this;
}
```

### Related

- [AuthTools: telemetry, SSE and webhooks](/docs/advanced/auth-tools) — the entry point that wires the bus
- [Outgoing and inbound webhooks](/docs/advanced/webhooks) — forward bus events to other systems
- [Authentication telemetry and audit trail](/docs/advanced/telemetry) — persist bus events for auditing
- [Server-Sent Events (SSE)](/docs/advanced/sse) — push bus events to the browser

---

## API Keys and Service Tokens (M2M Auth)

## API Keys / Service Tokens

node-auth provides a complete, zero-dependency API key system for machine-to-machine authentication. Raw keys are never stored — only a bcrypt hash is persisted.

Key format: `ak_<48 hex characters>` (~196 bits of entropy).

---

### Authentication flow

```mermaid
sequenceDiagram
    participant Client as Service / Script
    participant MW as createApiKeyMiddleware
    participant Store as IApiKeyStore
    participant Handler as Route handler

    Client->>MW: GET /tools/data<br/>Authorization: ApiKey ak_abc12345…
    MW->>MW: extract prefix (ak_abc12345)
    MW->>Store: findByPrefix('ak_abc12345')
    Store-->>MW: ApiKey record (hash, scopes, isActive, expiresAt)
    MW->>MW: bcrypt.compare(rawKey, keyHash)
    MW->>MW: check isActive, expiresAt, IP allowlist, scopes
    MW->>Store: updateLastUsed(id)
    MW->>Handler: next() — req.apiKey populated
    Handler-->>Client: 200 data
```

---

### Setup

#### 1. Implement `IApiKeyStore`

```typescript
import { IApiKeyStore, ApiKey } from '@awesome-lang-auth/node';

export class MyApiKeyStore implements IApiKeyStore {
  async save(key: ApiKey): Promise<void> {
    await db('api_keys').insert(key);
  }
  async findByPrefix(prefix: string): Promise<ApiKey | null> {
    return db('api_keys').where({ keyPrefix: prefix, isActive: true }).first() ?? null;
  }
  async findById(id: string): Promise<ApiKey | null> {
    return db('api_keys').where({ id }).first() ?? null;
  }
  async revoke(id: string): Promise<void> {
    await db('api_keys').where({ id }).update({ isActive: false });
  }
  async updateLastUsed(id: string): Promise<void> {
    await db('api_keys').where({ id }).update({ lastUsedAt: new Date() });
  }
}
```

#### 2. Create a key with `ApiKeyService`

```typescript
import { ApiKeyService } from '@awesome-lang-auth/node';

const apiKeyService = new ApiKeyService();
const { rawKey, record } = await apiKeyService.createKey(apiKeyStore, {
  name: 'stripe-webhook',
  serviceId: 'tenant-abc',
  scopes: ['tools:read', 'webhooks:receive'],
  expiresAt: new Date('2025-12-31'),
  allowedIps: ['203.0.113.0/24'],
});

// rawKey is shown exactly once — store it securely
console.log('Your key (shown once):', rawKey);
```

#### 3. Protect routes with `createApiKeyMiddleware`

```typescript
import { createApiKeyMiddleware } from '@awesome-lang-auth/node';

app.use(
  '/tools',
  createApiKeyMiddleware(apiKeyStore, {
    requiredScopes: ['tools:read'],
  }),
);

// Access authenticated context in handlers
app.get('/tools/data', (req, res) => {
  console.log(req.apiKey); // { keyId, keyPrefix, name, serviceId, scopes }
  res.json({ ok: true });
});
```

---

### Accepted header formats

```
Authorization: ApiKey ak_abc123…
X-Api-Key: ak_abc123…
```

Both formats are supported. Use whichever fits your client.

---

### `IApiKeyStore` interface

| Method | Required | Description |
|--------|----------|-------------|
| `save(key)` | ✓ | Persist a newly created key record |
| `findByPrefix(prefix)` | ✓ | Look up an active key by its prefix |
| `findById(id)` | ✓ | Look up a key by ID |
| `revoke(id)` | ✓ | Mark a key inactive |
| `updateLastUsed(id)` | ✓ | Record last-used timestamp |
| `listByServiceId(serviceId)` | optional | Return all keys for a service identity |
| `listAll(limit, offset)` | optional | Paginated admin listing |
| `delete(id)` | optional | Permanently delete (prefer `revoke`) |
| `logUsage(entry)` | optional | Per-key access audit log |

---

### `ApiKeyService` methods

```typescript
class ApiKeyService {
  createKey(store: IApiKeyStore, options: CreateApiKeyOptions): Promise<CreatedApiKey>;
  verifyKey(rawKey: string, hash: string): Promise<boolean>;
  extractPrefix(rawKey: string): string;
}

interface CreateApiKeyOptions {
  name: string;
  serviceId?: string;
  scopes?: string[];
  allowedIps?: string[];
  expiresAt?: Date;
  saltRounds?: number;   // default: 10
}

interface CreatedApiKey {
  rawKey: string;      // plaintext key — never stored, shown once
  record: ApiKey;      // persisted record (hash, prefix, metadata)
}
```

---

### `ApiKeyStrategyOptions`

```typescript
interface ApiKeyStrategyOptions {
  requiredScopes?: string[];   // all listed scopes must be present
  checkIp?: boolean;           // enforce allowedIps (default: true)
  onSuccess?: (context: ApiKeyContext) => void | Promise<void>;
}
```

### Related

- [Bearer token mode](/docs/advanced/bearer-token) — the other non-cookie credential
- [Role-based access control (RBAC)](/docs/advanced/roles-permissions) — scope what a key may do
- [Built-in admin panel](/docs/advanced/admin) — issue and revoke keys from the dashboard
- [Authentication telemetry and audit trail](/docs/advanced/telemetry) — record machine-to-machine calls

---

## AuthTools: Telemetry, SSE and Webhooks in One

## AuthTools

`AuthTools` is the unified entry point for the event-driven tools system. It wires `AuthEventBus` to three optional capabilities:

- **Telemetry** — persist every tracked event via `ITelemetryStore`
- **SSE** — stream events to connected browser/server clients in real time
- **Webhooks** — forward events to external HTTP endpoints with HMAC signing, or execute dynamic inbound scripts when external providers call you

> See the dedicated [Webhooks](/docs/advanced/webhooks) page for full details on both outgoing and inbound webhook configurations, including the `@webhookAction` decorator.

All capabilities are opt-in. Unused features have zero runtime overhead.

---

### Quick start

```typescript
import { AuthTools, AuthEventBus, createToolsRouter } from '@awesome-lang-auth/node';

const bus = new AuthEventBus();

const tools = new AuthTools(bus, {
  telemetryStore: myTelemetryStore,    // optional
  webhookStore:   myWebhookStore,      // optional
  sse:            true,                // optional — enables GET /tools/stream
  sseDistributor: myDistributor,       // optional — custom notify() transport wins over internal SSE broadcaster
  sseOptions: { heartbeatIntervalMs: 15_000 },
  webhookVersion: '1',
});

// Mount the tools HTTP router
app.use('/tools', createToolsRouter(tools, {
  authMiddleware: auth.middleware(),
}));
```

---

### Tracking events

`tools.track()` persists an event to the telemetry store (if configured) **and** publishes it on the bus, which triggers any attached SSE streams and webhook deliveries.

```typescript
await tools.track('identity.auth.login.success', { method: 'local' }, {
  userId: 'user-123',
  tenantId: 'tenant-abc',
  sessionId: 'sess-xyz',
  ip: req.ip,
  userAgent: req.headers['user-agent'],
});
```

---

### Sending notifications

`tools.notify()` pushes a real-time event to SSE subscribers and, optionally, sends the notification via **email** or **SMS** (v1.8.0+).

```typescript
// SSE only (default — backward-compatible)
await tools.notify('user:user-123', { message: 'New login from Paris' }, {
  type: 'security-alert',
  userId: 'user-123',
  tenantId: 'tenant-abc',
});

// Email + SSE (requires userStore and emailConfig in AuthToolsOptions)
await tools.notify('user:user-123', { message: 'Your subscription expires in 3 days' }, {
  channels: ['sse', 'email'],
  userId: 'user-123',
  emailSubject: 'Subscription expiring soon',
});

// SMS only
await tools.notify('user:user-123', 'SMS text', {
  channels: ['sms'],
  userId: 'user-123',
});
```

To enable email and SMS channels, pass the corresponding config when creating `AuthTools`:

```typescript
const tools = new AuthTools(bus, {
  sse: true,
  userStore,                                    // needed to look up email / phone
  emailConfig: {
    endpoint: process.env.MAILER_ENDPOINT!,
    apiKey:   process.env.MAILER_KEY!,
    from:     'no-reply@example.com',
  },
  smsConfig: {
    endpoint: process.env.SMS_ENDPOINT!,
    apiKey:   process.env.SMS_KEY!,
    username: process.env.SMS_USERNAME!,
    password: process.env.SMS_PASSWORD!,
  },
});
```

Topics supported out of the box (SSE channel):

| Topic pattern | Description |
|---------------|-------------|
| `global` | Broadcast to all connections |
| `tenant:{tenantId}` | All connections in a tenant |
| `user:{userId}` | A single user |
| `session:{sessionId}` | A single session |
| `custom:{namespace}` | Application-defined channel |

---

### Full event flow

```mermaid
sequenceDiagram
    participant App as Application code
    participant Tools as AuthTools.track()
    participant Bus as AuthEventBus
    participant DB as ITelemetryStore
    participant SSE as SseManager
    participant WH as WebhookSender

    App->>Tools: track(eventName, data, context)
    Tools->>DB: telemetryStore.save(event)
    Tools->>Bus: bus.publish(eventName, payload)
    Bus->>SSE: emit(event, payload)
    SSE-->>Browser: SSE stream data
    Bus->>WH: emit(event, payload)
    WH->>External: POST webhook endpoint
```

---

### `AuthToolsOptions`

```typescript
interface AuthToolsOptions {
  telemetryStore?: ITelemetryStore;
  webhookStore?: IWebhookStore;
  sse?: boolean;                             // default: false
  sseDistributor?: ISseDistributor;          // optional custom notify() distributor
  sseOptions?: { heartbeatIntervalMs?: number; distributor?: ISseDistributor; deduplicate?: boolean };
  webhookVersion?: string;                   // default: '1'
  userStore?: IUserStore;                    // v1.8.0 — required for email/SMS notify channels
  emailConfig?: EmailNotificationConfig;     // v1.8.0 — enables 'email' channel in notify()
  smsConfig?: SmsNotificationConfig;         // v1.8.0 — enables 'sms' channel in notify()
}
```

---

### `AuthTools` API

```typescript
class AuthTools {
  constructor(bus: AuthEventBus, options?: AuthToolsOptions);

  track(eventName: string, data?: unknown, options?: TrackOptions): Promise<void>;
  notify(target: string, data?: unknown, options?: NotifyOptions): void;

  get sseManager(): SseManager | undefined;
  get eventBus(): AuthEventBus;
}
```

---

## Server-Sent Events (SSE) for Real-Time Auth

## Server-Sent Events (SSE)

`SseManager` maintains a registry of open HTTP streams and broadcasts `StreamEvent` objects to all clients subscribed to a matching topic. The server controls which topics a connection may receive — clients cannot self-declare channels.

---

### Connection lifecycle

```mermaid
sequenceDiagram
    participant Browser
    participant Router as Tools Router
    participant SSE as SseManager

    Browser->>Router: GET /tools/stream?topics=user:123
    Router->>Router: authenticate request (authMiddleware)
    Router->>SSE: connect(res, topics, {userId})
    SSE-->>Browser: HTTP 200 text/event-stream
    SSE-->>Browser: : heartbeat (every 30 s)

    Note over Browser,SSE: Event published
    Router->>SSE: broadcast('user:123', streamEvent)
    SSE-->>Browser: data: {"type":"security-alert",…}

    Browser->>Router: connection closed
    Router->>SSE: disconnect(connectionId)
```

---

### Setup

Enable SSE when creating `AuthTools`:

```typescript
const tools = new AuthTools(bus, { sse: true });
```

Mount the tools router (exposes `GET /tools/stream`):

```typescript
app.use('/tools', createToolsRouter(tools, {
  authMiddleware: auth.middleware(),
}));
```

---

### SseManager Configuration

When enabling SSE, you can pass options to customize its behavior:

```typescript
const tools = new AuthTools(bus, { 
  sse: {
    heartbeatIntervalMs: 30000,
    deduplicate: true, // Prevents multiple delivery of the same event ID
  }
});
```

#### Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `heartbeatIntervalMs` | `number` | `30000` | Interval between keep-alive heartbeats. Set to `0` to disable. |
| `deduplicate` | `boolean` | `true` | When `true`, the manager prevents sending the same event ID twice to the same connection. Useful when a user is subscribed to multiple topics that receive the same broadcast. |
| `distributor` | `ISseDistributor` | `undefined` | Required for cross-instance synchronization in scaled environments. |

---

### 1. Setup in your Backend

First, ensure SSE is enabled when creating your `AuthTools` instance, and that the tools router is mounted with your auth middleware.

```typescript
import express from 'express';
import { AuthConfigurator, AuthTools, createToolsRouter } from '@awesome-lang-auth/node';

const app = express();
app.use(express.json());

// Initialize core auth
const auth = new AuthConfigurator(config, userStore);
app.use('/auth', auth.router());

// Enable SSE in the tools configuration
const tools = new AuthTools(bus, { sse: true });

// Mount the tools router, protected by auth.middleware()
app.use('/tools', createToolsRouter(tools, {
  authMiddleware: auth.middleware(),
}));

// Now you can broadcast events from anywhere in your app:
app.post('/api/messages', auth.middleware(), (req, res) => {
  const { recipientId, text } = req.body;
  
  // 🎯 Broadcast a custom event to a specific user via topic
  tools.sseManager?.broadcast(`user:${recipientId}`, {
    type: 'new_message',
    data: { 
      from: req.user.id, 
      text 
    }
  });

  res.sendStatus(200);
});
```

---

### 2. Connecting from the Frontend

When a user logs in, they can connect to the `/tools/stream` endpoint.
Because the router is protected by `auth.middleware()`, the user will **only** receive events that match their own `user:{id}`, their `tenant:{id}`, or `global` topics.

#### Vanilla JavaScript Example

```javascript
// The topics query param tells the server which channels you want to listen to.
// The server will verify you have permission to access them.
const currentUserId = '123';
const evtSource = new EventSource(`/tools/stream?topics=user:${currentUserId}`, { 
  withCredentials: true 
});

// Listen for a specific event type (matches the `type` field in broadcast)
evtSource.addEventListener('new_message', (event) => {
  const payload = JSON.parse(event.data);
  console.log(`New message from ${payload.rawData.from}: ${payload.rawData.text}`);
});

// The library automatically sends ping events every 30s to keep the connection alive
evtSource.addEventListener('ping', () => {
  console.debug('SSE connection is alive');
});

// Handle errors and reconnections
evtSource.onerror = (err) => {
  console.error("SSE Error:", err);
  // Browsers automatically try to reconnect EventSources, 
  // but you can call evtSource.close() to stop it.
};
```

#### React Example

A practical way to consume SSE in a React application using a custom hook:

```tsx
import { useEffect, useState } from 'react';

export function useMessages(userId: string) {
  const [messages, setMessages] = useState([]);

  useEffect(() => {
    if (!userId) return;

    const evtSource = new EventSource(`http://api.myapp.com/tools/stream?topics=user:${userId}`, {
      withCredentials: true, // Crucial if you use cookie-based auth
    });

    evtSource.addEventListener('new_message', (event) => {
      const payload = JSON.parse(event.data);
      setMessages((prev) => [...prev, payload.rawData]);
    });

    return () => {
      evtSource.close(); // Cleanup when unmounting
    };
  }, [userId]);

  return messages;
}

// Usage in a component:
function ChatApp({ currentUser }) {
  const messages = useMessages(currentUser.id);
  
  return (
    <ul>
      {messages.map((msg, i) => <li key={i}>{msg.text}</li>)}
    </ul>
  );
}
```

---

### Proxy Configuration (Nginx / Traefik / Apache) ⚠️

If your Node.js application is running behind a reverse proxy, you must ensure the proxy doesn't buffer the `/tools/stream` endpoint. Otherwise, the proxy will hold onto the events and not send them to the client in real-time.

#### Nginx

Nginx buffers HTTP responses by default. You must explicitly disable it for the SSE endpoint.

**Example Nginx config:**

```nginx
location /tools/stream {
    proxy_pass http://localhost:3000;
    
    # Required for SSE: disable buffering and caching
    proxy_http_version 1.1;
    proxy_set_header Connection '';
    proxy_buffering off;
    proxy_cache off;
    chunked_transfer_encoding off;
    
    # Keep idle connections open longer
    proxy_read_timeout 24h;
}
```

#### Traefik

Traefik natively supports SSE (Server-Sent Events) out of the box and does **not** buffer responses by default. In most setups, **no explicit configuration is needed**.

However, keep these two things in mind:
1. Ensure you haven't globally applied a [`Buffering` middleware](https://doc.traefik.io/traefik/middlewares/http/buffering/) to the router serving `node-auth`.
2. If your SSE connections are dropping prematurely, check if you have an aggressive `readTimeout` set on your Traefik entrypoints or transport configurations.

---

### Topic hierarchy

The server enforces topic access — restrict which topics each user/connection may subscribe to via `authMiddleware`.

| Topic | Description |
|-------|-------------|
| `global` | All connected clients |
| `tenant:{tenantId}` | All clients in a specific tenant |
| `tenant:{tenantId}:role:{role}` | All clients in a tenant with a specific role |
| `tenant:{tenantId}:group:{groupId}` | All clients in a tenant group |
| `user:{userId}` | A specific user |
| `session:{sessionId}` | A specific session |
| `custom:{namespace}` | Any custom namespace |

---

### StreamEvent structure

```typescript
interface StreamEvent<T = unknown> {
  id: string;           // auto-generated UUID
  type: string;         // event type name
  timestamp: string;    // ISO 8601
  topic: string;        // channel this was published to
  data: T;              // the data passed to broadcast (renamed to `rawData` in wire format)
  userId?: string;
  tenantId?: string;
  metadata?: Record<string, unknown>;
}
```

> [!NOTE]
> When the event is serialized to the client over the wire, the `data` field is renamed to `rawData` in the JSON payload to avoid namespace collisions with the event metadata.

---

---

### `SseManager` API

When `sse: true` is passed to `AuthTools`, the manager is available at `tools.sseManager`:

```typescript
class SseManager {
  readonly heartbeatIntervalMs: number;
  readonly deduplicate: boolean;

  connect(
    res: Response,
    topics: string[],
    meta?: { userId?: string; tenantId?: string },
  ): string;  // returns connectionId

  disconnect(connectionId: string): void;

  broadcast<T = unknown>(
    topic: string,
    event: Omit<StreamEvent<T>, 'id' | 'timestamp' | 'topic'> & { id?: string; timestamp?: string },
  ): void;

  get connectionCount(): number;
}
```

### Related

- [Scaling SSE across instances with Redis](/docs/advanced/sse-scaling) — SSE beyond a single process
- [@sseNotify real-time decorator](/docs/advanced/sse-notify-decorator) — emit events without transport code
- [AuthTools: telemetry, SSE and webhooks](/docs/advanced/auth-tools) — the entry point that enables SSE
- [Outgoing and inbound webhooks](/docs/advanced/webhooks) — the server-to-server counterpart

---

## Scaling SSE Across Instances with Redis

## Scaling Server-Sent Events

By default, `SseManager` stores active HTTP connections in the server's local memory. In a distributed environment (e.g., Kubernetes cluster or mult-instance deployment), an event broadcast on **Server A** will not reach a user connected to **Server B**.

To solve this, `node-auth` provides a distribution adapter pattern.

### The Solution: ISseDistributor

You can provide an implementation of the `ISseDistributor` interface to synchronize events across instances.

#### 1. Implement the Distributor (e.g. Redis)

```typescript
import { ISseDistributor } from '@awesome-lang-auth/node';
import { createClient } from 'redis';

export class RedisSseDistributor implements ISseDistributor {
  private pub = createClient();
  private sub = createClient();

  async publish(topic: string, event: any): Promise<void> {
    await this.pub.publish('sse-channel', JSON.stringify({ topic, event }));
  }

  async subscribe(callback: (topic: string, event: any) => void): Promise<void> {
    await this.sub.subscribe('sse-channel', (message) => {
      const { topic, event } = JSON.parse(message);
      callback(topic, event);
    });
  }
}
```

#### 2. Configure AuthTools

Pass the distributor in the `sseOptions`:

```typescript
const tools = new AuthTools(bus, {
  sse: true,
  sseOptions: {
    distributor: new RedisSseDistributor(),
  },
});
```

### How it works

1.  **Broadcast**: When you call `tools.notify('topic', data)`, the manager publishes the event to the distributor instead of just sending it locally.
2.  **Sync**: The distributor sends the message to all instances of your application.
3.  **Local Delivery**: Every instance receives the message via `subscribe()` and forwards it to its own local HTTP connections matching that topic.

This ensures that real-time notifications work seamlessly across your entire cluster.

### Related

- [Server-Sent Events (SSE)](/docs/advanced/sse) — the single-instance basics
- [@sseNotify real-time decorator](/docs/advanced/sse-notify-decorator) — where the events come from
- [AuthTools: telemetry, SSE and webhooks](/docs/advanced/auth-tools) — wiring SSE into the tools system
- [Authentication telemetry and audit trail](/docs/advanced/telemetry) — the other multi-instance concern

---

## @sseNotify: Real-Time Events from Any Method

## Real-time Entity Decorators

The `@sseNotify` decorator provides a declarative way to trigger real-time notifications on any service or store method. It is highly customizable and decouples your business logic from the notification system.

### Basic Usage

Apply the decorator to a method. After the method executes successfully, an SSE broadcast is triggered.

> [!IMPORTANT]
> This decorator uses the **TC39 Stage 3** syntax and requires **TypeScript 5.x+**. For legacy environments or older frameworks, use manual notification via `SseNotifyRegistry.notify()`.

```typescript
import { sseNotify } from '@awesome-lang-auth/node';

class ProductService {
  @sseNotify({
    topic: 'products',
    event: 'product.created',
  })
  async createProduct(data: any) {
    return await db.products.insert(data);
  }
}
```

### Advanced Customization

You can resolve topics, events, and payloads dynamically based on the method arguments and the result.

#### Dynamic Topic & Payload

```typescript
class UserService {
  @sseNotify({
    // Resolve topic from the return value (user object)
    topic: (args, user) => `user:${user.id}`,
    
    // Custom event name
    event: 'profile.updated',
    
    // Transform the payload before sending
    payload: (user) => ({ 
      id: user.id, 
      username: user.username,
      updatedAt: user.updatedAt 
    }),
    
    // Optional tenancy and user context
    tenantId: (user) => user.tenantId,
    userId: (user) => user.id,
  })
  async updateProfile(userId: string, data: any) {
    return await db.users.update(userId, data);
  }
}
```

### How it works

The decorator uses a global `SseNotifyRegistry`. When you initialize `AuthTools` with SSE enabled, it automatically registers its `SseManager` to this registry.

```typescript
// During app boot
const tools = new AuthTools(bus, { sse: true });
// Now all @sseNotify decorators are active!
```

---

### `SseNotifyRegistry` API

The `SseNotifyRegistry` serves as the central dispatcher for SSE notifications. You can use it manually when decorators are not suitable for your environment or logic.

#### Static Methods

| Method | Description |
|--------|-------------|
| `setManager(manager: SseManager \| null)` | Sets the active SSE manager. Typically called automatically by `AuthTools`. |
| `notify(topic, event)` | Directly broadcasts an event to the registry. |
| `executeNotify(options, args, result)` | Executes the notification logic manually, mimicking the decorator behavior. |

#### Manual Notification Example

If you cannot use decorators, you can trigger notifications manually:

```typescript
import { SseNotifyRegistry } from '@awesome-lang-auth/node';

async function updateSystemSetting(config: any) {
  const result = await db.settings.save(config);
  
  // 🎯 Manual notification
  SseNotifyRegistry.notify('settings', {
    type: 'setting.changed',
    data: result,
    tenantId: config.tenantId
  });

  return result;
}
```

---

### Benefits

1.  **Cleaner Code**: No need to manually call `tools.notify()` inside every method.
2.  **Type-Safe**: Use method arguments and result types in your resolver functions.
3.  **Flexible**: Works on any class method, not just database stores.

### Related

- [Server-Sent Events (SSE)](/docs/advanced/sse) — the transport the decorator drives
- [Scaling SSE across instances with Redis](/docs/advanced/sse-scaling) — decorated events across a cluster
- [AuthEventBus event names](/docs/advanced/auth-event-bus) — the bus decorated methods publish to
- [Outgoing and inbound webhooks](/docs/advanced/webhooks) — forward the same events off-box

---

## Outgoing and Inbound Authentication Webhooks

## Webhooks

node-auth supports two complementary webhook directions:

| Direction | Purpose | Config |
|-----------|---------|--------|
| **Outgoing** | Library fires → external service | `IWebhookStore` + `WebhookSender` |
| **Inbound (dynamic)** | External service fires → library executes script | `IWebhookStore.findByProvider` + a script run through `node:vm` |

Both are managed from the **Admin Panel → Webhooks tab**.

---

### Outgoing webhooks

node-auth can forward any `AuthEventBus` event to external HTTP endpoints as a signed JSON POST. Delivery is performed by `WebhookSender` with optional HMAC-SHA256 signing and configurable exponential back-off retry.

---

### Delivery flow

```mermaid
sequenceDiagram
    participant Bus as AuthEventBus
    participant Tools as AuthTools
    participant Store as IWebhookStore
    participant Sender as WebhookSender
    participant Ext as External endpoint

    Bus->>Tools: emit(event, payload)
    Tools->>Store: findByEvent(event, tenantId)
    Store-->>Tools: []WebhookConfig
    loop for each config
        Tools->>Sender: send(config, outgoingEvent)
        Sender->>Ext: POST config.url<br/>X-Webhook-Signature: sha256=…
        alt 2xx response
            Ext-->>Sender: 200 OK
        else non-2xx / network error
            Sender->>Sender: exponential back-off
            Sender->>Ext: retry (up to maxRetries)
        end
    end
```

---

### Setup

#### 1. Implement `IWebhookStore`

```typescript
import { IWebhookStore, WebhookConfig } from '@awesome-lang-auth/node';

export class MyWebhookStore implements IWebhookStore {
  async findByEvent(event: string, tenantId?: string): Promise<WebhookConfig[]> {
    return db('webhooks')
      .where('isActive', true)
      .where((q) =>
        q.where('tenantId', tenantId ?? null).orWhereNull('tenantId'),
      )
      .where((q) =>
        q.whereJsonContains('events', event).orWhereJsonContains('events', '*'),
      );
  }
}
```

#### 2. Pass the store to `AuthTools`

```typescript
const tools = new AuthTools(bus, { webhookStore: myWebhookStore });
```

Webhooks are now dispatched automatically whenever `tools.track()` is called.

---

### Webhook payload

```json
{
  "event": "identity.auth.login.success",
  "version": "1",
  "timestamp": "2024-11-15T10:23:45.678Z",
  "data": { "method": "oauth", "provider": "google" },
  "metadata": {
    "userId": "user-123",
    "tenantId": "tenant-abc",
    "correlationId": "req-xyz"
  }
}
```

---

### Verifying signatures

Every outgoing request includes an `X-Webhook-Signature: sha256=<hex>` header. Verify it on the receiving server using the shared secret:

```typescript
import { WebhookSender } from '@awesome-lang-auth/node';

const sender = new WebhookSender();

app.post('/webhooks/awesome-node-auth', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-webhook-signature'] as string;
  const isValid = sender.verify(req.body.toString(), process.env.WEBHOOK_SECRET!, signature);
  if (!isValid) return res.status(401).json({ error: 'Invalid signature' });

  const event = JSON.parse(req.body.toString());
  console.log('Received event:', event.event);
  res.sendStatus(200);
});
```

---

### `WebhookConfig` fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | `string` | ✓ | Unique registration ID |
| `url` | `string` | ✓ | Endpoint URL |
| `events` | `string[]` | ✓ | Event names (or `['*']` for all) |
| `secret` | `string` | — | HMAC signing secret |
| `isActive` | `boolean` | — | Default `true` |
| `tenantId` | `string` | — | Scope to a tenant; omit for global |
| `maxRetries` | `number` | — | Default `3` |
| `retryDelayMs` | `number` | — | Initial delay in ms; default `1000` |

---

### Request headers

| Header | Description |
|--------|-------------|
| `X-Webhook-Event` | Event name |
| `X-Webhook-Delivery` | UUID per delivery attempt |
| `X-Webhook-Timestamp` | ISO 8601 timestamp |
| `X-Webhook-Signature` | `sha256=<hmac-hex>` (when secret is set) |

---

### Dynamic inbound execution {#dynamic-inbound-execution}

Beyond the static `onWebhook` callback, the tools router supports a **governance-driven execution model** where:

1. Developers expose service methods as injectable actions with `@webhookAction`.
2. Administrators globally enable/disable actions in the **Control → Webhook Actions** panel.
3. Each inbound webhook config in the **Webhooks** tab is assigned a `jsScript` + an `allowedActions` subset.
4. When `POST /tools/webhook/:provider` fires, the script runs through Node.js `node:vm`, and its `actions` object holds only the intersection of globally-enabled **and** per-webhook-allowed actions.

:::danger Inbound scripts run with the server's privileges
`node:vm` is not a security mechanism, so the script is **not sandboxed**: it runs with the privileges of the server process and can run arbitrary code on the server. Only fully trusted operators may write a `jsScript`, whether through the webhook store or the admin console. The `allowedActions` intersection only decides which functions the script receives in `actions`. The 5-second timeout bounds only the synchronous part of the script, not its asynchronous work. See [awesome-node-auth#10](https://github.com/awesome-lang-auth/awesome-node-auth/issues/10).
:::

#### Execution flow

```mermaid
sequenceDiagram
    participant Ext as External service
    participant Router as Tools Router
    participant Store as IWebhookStore
    participant Sett as ISettingsStore
    participant VM as Node.js vm module
    participant Bus as AuthEventBus

    Ext->>Router: POST /tools/webhook/:provider
    Router->>Store: findByProvider(provider)
    Store-->>Router: WebhookConfig { jsScript, allowedActions }
    Router->>Sett: getSettings()
    Sett-->>Router: { enabledWebhookActions }
    Router->>Router: intersect(enabledWebhookActions, allowedActions) → actions{}
    Router->>VM: runInContext(jsScript, { body, actions, result:null })
    VM-->>Router: result = { event, data }
    Router->>Bus: track(event, data)
    Router-->>Ext: 200 { ok: true }
```

#### 1. Register actions with `@webhookAction`

```typescript
import { webhookAction, ActionRegistry } from '@awesome-lang-auth/node';

class SubscriptionService {
  @webhookAction({
    id:          'subscription.cancel',
    label:       'Cancel subscription',
    category:    'Billing',
    description: 'Marks a subscription as cancelled.',
  })
  async cancel(subscriptionId: string): Promise<void> {
    await db.subscriptions.update({ id: subscriptionId }, { status: 'cancelled' });
  }

  @webhookAction({
    id:          'subscription.notifyUser',
    label:       'Notify user',
    category:    'Billing',
    description: 'Sends cancellation email to the user.',
    dependsOn:   ['subscription.cancel'],   // only available when cancel is also enabled
  })
  async notifyUser(userId: string): Promise<void> {
    await mailer.send({ to: userId, subject: 'Subscription cancelled', template: 'sub-cancelled' });
  }
}

// Bind the instance so inbound scripts can call it
const svc = new SubscriptionService();
ActionRegistry.register({ id: 'subscription.cancel',     label: 'Cancel subscription', category: 'Billing', description: '', fn: svc.cancel.bind(svc) });
ActionRegistry.register({ id: 'subscription.notifyUser', label: 'Notify user',          category: 'Billing', description: '', dependsOn: ['subscription.cancel'], fn: svc.notifyUser.bind(svc) });
```

#### 2. Wire stores into the tools router

```typescript
app.use('/tools', createToolsRouter(tools, {
  webhookStore:  myWebhookStore,   // must implement findByProvider()
  settingsStore: mySettingsStore,  // reads enabledWebhookActions
}));
```

#### 3. Create an inbound webhook config via the Admin UI

In the **Webhooks** tab click **+ Register webhook**, switch to **Inbound (dynamic)** and fill in:

| Field | Example | Description |
|-------|---------|-------------|
| Provider name | `stripe` | Matches `:provider` in `POST /tools/webhook/stripe` |
| Events | `*` | (optional) event filter |
| Allowed actions | ☑ Cancel subscription | Subset of globally-enabled actions |
| JavaScript | see below | Script body, run through `node:vm` with the server's privileges |

**Example script:**

```js
// Available globals: body (request payload), actions (filtered functions)
// Set result to emit an internal event, or leave null to silently ack.

if (body.type === 'customer.subscription.deleted') {
  const subId = body.data.object.id;
  const userId = body.data.object.metadata.userId;

  await actions['subscription.cancel'](subId);
  await actions['subscription.notifyUser'](userId);

  result = {
    event: 'identity.tenant.user.removed',
    data:  { subscriptionId: subId, userId },
  };
}
```

#### 4. Governance rules

| Rule | Behaviour |
|------|-----------|
| Action not in `enabledWebhookActions` | Not passed to the script in `actions`, even if in `allowedActions` |
| Action's `dependsOn` not enabled | Not passed to the script in `actions` |
| Script throws at runtime | Error logged, HTTP 200 returned (no crash) |
| Synchronous part of the script exceeds 5 s | Error logged, HTTP 200 returned; asynchronous work is not bounded |
| `result` not set / null | Webhook silently acknowledged, no event emitted |

#### `WebhookConfig` new fields

| Field | Type | Description |
|-------|------|-------------|
| `provider` | `string` | Inbound provider name (matches `:provider` param) |
| `allowedActions` | `string[]` | Action IDs this webhook's script receives in `actions` |
| `jsScript` | `string` | JS body run through `node:vm` with the server's privileges; only trusted operators may write it |

#### `IWebhookStore` new method

```typescript
/** Find the inbound webhook config for a given provider name. */
findByProvider?(provider: string): Promise<WebhookConfig | null>;
```

#### `AuthSettings` new field

```typescript
/** Globally enabled action IDs (toggled in the Admin UI → Control tab). */
enabledWebhookActions?: string[];
```

#### `ToolsRouterOptions` new options

```typescript
/** Provides findByProvider() for dynamic inbound webhook lookup. */
webhookStore?: IWebhookStore;

/** Reads enabledWebhookActions for inbound webhook scripts. */
settingsStore?: ISettingsStore;
```

### Related

- [AuthEventBus event names](/docs/advanced/auth-event-bus) — the events that trigger webhooks
- [AuthTools: telemetry, SSE and webhooks](/docs/advanced/auth-tools) — enabling webhook delivery
- [Server-Sent Events (SSE)](/docs/advanced/sse) — the browser-facing counterpart
- [Authentication telemetry and audit trail](/docs/advanced/telemetry) — auditing what was sent

---

## Authentication Telemetry and Audit Trail

## Telemetry

node-auth's telemetry system persists every identity event to any store you provide. When `ITelemetryStore` is omitted, events still flow through `AuthEventBus` (and fire webhooks/SSE), they just aren't stored.

---

### Event persistence flow

```mermaid
sequenceDiagram
    participant App as Application
    participant Tools as AuthTools.track()
    participant Store as ITelemetryStore
    participant Bus as AuthEventBus

    App->>Tools: track('identity.auth.login.success', data, context)
    Tools->>Tools: build TelemetryEvent (id, timestamp, …)
    Tools->>Store: store.save(event)
    Tools->>Bus: bus.publish(eventName, payload)
```

---

### Setup

#### 1. Implement `ITelemetryStore`

```typescript
import { ITelemetryStore, TelemetryEvent, TelemetryFilter } from '@awesome-lang-auth/node';

export class MyTelemetryStore implements ITelemetryStore {
  async save(event: TelemetryEvent): Promise<void> {
    await db('telemetry').insert(event);
  }

  async query(filter: TelemetryFilter): Promise<TelemetryEvent[]> {
    let q = db('telemetry');
    if (filter.event)     q = q.where('event', filter.event);
    if (filter.userId)    q = q.where('userId', filter.userId);
    if (filter.tenantId)  q = q.where('tenantId', filter.tenantId);
    if (filter.from)      q = q.where('timestamp', '>=', filter.from.toISOString());
    if (filter.to)        q = q.where('timestamp', '<=', filter.to.toISOString());
    return q.limit(filter.limit ?? 100).offset(filter.offset ?? 0);
  }
}
```

#### 2. Pass the store to `AuthTools`

```typescript
const tools = new AuthTools(bus, { telemetryStore: myTelemetryStore });
```

#### 3. Track events

Events are tracked automatically when the auth router uses the same `bus`. You can also track custom events manually:

```typescript
await tools.track('identity.user.password.changed', { method: 'reset-link' }, {
  userId: 'user-123',
  tenantId: 'tenant-abc',
  ip: req.ip,
});
```

---

### Query endpoint

When `ITelemetryStore.query` is implemented and `telemetryStore` is passed to `createToolsRouter`, the `GET /tools/telemetry` endpoint is automatically enabled:

```
GET /tools/telemetry?event=identity.auth.login.success&userId=user-123&limit=50
```

---

### `TelemetryEvent` structure

```typescript
interface TelemetryEvent {
  id: string;           // auto-generated UUID
  event: string;        // e.g. 'identity.auth.login.success'
  timestamp: string;    // ISO 8601
  data?: unknown;
  userId?: string;
  tenantId?: string;
  sessionId?: string;
  correlationId?: string;
  ip?: string;
  userAgent?: string;
}
```

---

### `TelemetryFilter` options

```typescript
interface TelemetryFilter {
  event?: string;
  userId?: string;
  tenantId?: string;
  sessionId?: string;
  from?: Date;
  to?: Date;
  limit?: number;    // default: 100
  offset?: number;   // default: 0
}
```

---

### `ITelemetryStore` interface

| Method | Required | Description |
|--------|----------|-------------|
| `save(event)` | ✓ | Persist a telemetry event |
| `query(filter)` | optional | Enable `GET /tools/telemetry` query endpoint |

### Related

- [AuthEventBus event names](/docs/advanced/auth-event-bus) — the events telemetry persists
- [AuthTools: telemetry, SSE and webhooks](/docs/advanced/auth-tools) — enabling the telemetry store
- [Outgoing and inbound webhooks](/docs/advanced/webhooks) — ship the same events elsewhere
- [Built-in admin panel](/docs/advanced/admin) — browse the audit trail

---

## Swagger UI and OpenAPI 3.0 Spec for Auth

## Swagger / OpenAPI

node-auth ships a built-in OpenAPI 3.0 spec covering every endpoint on the auth router, admin router, and tools router. Swagger UI is served automatically and enabled by default outside production.

---

### Auth router — Swagger UI

Mount the auth router and the spec is available at:

```
GET /auth/docs         — Swagger UI
GET /auth/openapi.json — raw OpenAPI 3.0 spec
```

Enable/disable explicitly:

```typescript
const auth = new AuthConfigurator(config, userStore);
app.use('/auth', auth.router());
// swagger is auto-enabled when NODE_ENV !== 'production'
```

---

### Tools router — Swagger UI

```typescript
import { createToolsRouter } from '@awesome-lang-auth/node';

app.use('/tools', createToolsRouter(tools, {
  swagger: 'auto',         // default — enabled outside production
  swaggerBasePath: '/tools',
}));
```

Endpoints:

```
GET /tools/docs         — Swagger UI
GET /tools/openapi.json — raw OpenAPI 3.0 spec
```

---

### Admin router — Swagger UI

```typescript
import { createAdminRouter } from '@awesome-lang-auth/node';

app.use('/admin', createAdminRouter(userStore, {
  accessPolicy: 'first-user',
  jwtSecret: process.env.ACCESS_TOKEN_SECRET!,
}));
// GET /admin/docs  — Swagger UI (auto-enabled outside production)
```

---

### Disabling in production

The `swagger` option accepts:

| Value | Behaviour |
|-------|-----------|
| `'auto'` (default) | Enabled when `NODE_ENV !== 'production'` |
| `true` | Always enabled |
| `false` | Always disabled |

```typescript
app.use('/tools', createToolsRouter(tools, { swagger: false }));
```

---

### Tools router endpoints

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/tools/track/:eventName` | Track a telemetry event |
| `POST` | `/tools/notify/:target` | Send an SSE notification |
| `GET` | `/tools/stream` | SSE stream endpoint |
| `POST` | `/tools/webhook/:provider` | Receive an inbound webhook |
| `GET` | `/tools/telemetry` | Query persisted telemetry (if store provides `query`) |
| `GET` | `/tools/docs` | Swagger UI |
| `GET` | `/tools/openapi.json` | Raw OpenAPI 3.0 spec |

---

### Using the OpenAPI spec

Import the spec into any API tool — Postman, Insomnia, Stoplight, etc.:

```
https://your-server.example.com/auth/openapi.json
https://your-server.example.com/tools/openapi.json
https://your-server.example.com/admin/openapi.json
```

### Related

- [Auth API endpoints reference](/docs/api-reference/endpoints) — the same routes in prose
- [API reference: auth, admin and tools routers](/docs/api-reference) — what the spec covers
- [Built-in admin panel](/docs/advanced/admin) — the admin routes documented in the spec
- [AuthTools: telemetry, SSE and webhooks](/docs/advanced/auth-tools) — the tools router endpoints

---

## Framework Integrations for Node.js Auth

## Framework Integrations

awesome-node-auth works with any Node.js framework and any client platform. See the `examples/` directory for complete server-side implementations.

### Server-side frameworks

| Framework / Platform | Guide |
|----------------------|-------|
| [Express.js](/docs/frameworks/express) | Minimal setup, drop-in router |
| [NestJS](/docs/frameworks/nestjs) | Module, guard, controller, DI |
| [Next.js](/docs/frameworks/nextjs) | App Router, middleware & SSR |
| [Angular (SSR)](/docs/frameworks/angular) | Standalone + SSR, interceptors, guards (manual wiring) |
| [Python / FastAPI](/docs/frameworks/python) | **Official Python library** — `awesome-python-auth`; all auth flows, CSRF, IdP/RBAC, multi-tenancy |
| [Dart](/docs/frameworks/dart) | **Official Dart backend library** — `awesome-dart-auth` |
| [Go](/docs/frameworks/go) | **Official Go backend library** — `awesome-go-auth` |
| [AWS Lambda](/docs/frameworks/lambda) | **Deployable product (preview)** — `awesome-lambda-auth`; the Go core on Lambda and DynamoDB, in your own AWS account |
| [Rust](/docs/frameworks/rust) | **Official Rust backend library** — `awesome-rust-auth` |
| [Framework-Agnostic](/docs/frameworks/framework-agnostic) | Neutral `AuthRequest`/`AuthResponse` types + adapter pattern |

### Client-side platforms

| Platform | Guide |
|----------|-------|
| [Angular — @awesome-lang-auth/angular](/docs/frameworks/ng-awesome-node-auth) | **Official Angular library** — Guards, Interceptors, session signals, CSRF, SSR-safe |
| [React](/docs/frameworks/react) | **Official React library (early, 0.1.0)** — `@awesome-lang-auth/react`; provider, hooks, route gates, cookie or bearer transport |
| [Vanilla JS / Browser Client](/docs/advanced/browser-client) | Zero-config `window.AwesomeNodeAuth` via `auth.js` — works with any JS framework |
| [Flutter](/docs/frameworks/flutter) | **Official Flutter package** — `awesome_flutter_auth`; web (cookie+CSRF), native (Bearer), WASM |
| [iOS (Swift)](/docs/frameworks/ios) | URLSession, Keychain, SwiftUI |
| [Android (Kotlin)](/docs/frameworks/android) | Retrofit, EncryptedSharedPreferences, Compose |

### Porting & parity status

The official ports and client libraries each track parity against this reference implementation, through a dedicated audit issue or a status table in their own repository. The audits are structured checklists covering the full feature surface (auth strategies, sessions, RBAC, multi-tenancy, IdP, events, admin panel, etc.) plus the documentation and release tasks needed to ship a parity-aligned version.

#### Server-side ports

| Language | Repository | Parity status |
|---|---|---|
| Go | [`awesome-go-auth`](https://github.com/awesome-lang-auth/awesome-go-auth) | [audit #5](https://github.com/awesome-lang-auth/awesome-go-auth/issues/5) |
| AWS Lambda | [`awesome-lambda-auth`](https://github.com/awesome-lang-auth/awesome-lambda-auth) | [PROGRESS.md](https://github.com/awesome-lang-auth/awesome-lambda-auth/blob/main/docs/PROGRESS.md) |
| Rust | [`awesome-rust-auth`](https://github.com/awesome-lang-auth/awesome-rust-auth) | [parity snapshot](https://github.com/awesome-lang-auth/awesome-rust-auth#parity-snapshot-vs-awesome-node-auth) · [audit #13](https://github.com/awesome-lang-auth/awesome-rust-auth/issues/13) |
| Python | [`awesome-python-auth`](https://github.com/awesome-lang-auth/awesome-python-auth) | [audit #10](https://github.com/awesome-lang-auth/awesome-python-auth/issues/10) |
| Dart (server) | [`awesome-dart-auth`](https://github.com/awesome-lang-auth/awesome-dart-auth) | [parity snapshot](https://github.com/awesome-lang-auth/awesome-dart-auth#parity-snapshot-vs-awesome-node-auth) · [audit #13](https://github.com/awesome-lang-auth/awesome-dart-auth/issues/13) |

#### Client libraries

| Framework | Repository | API parity audit |
|---|---|---|
| Angular | [`awesome-angular-auth`](https://github.com/awesome-lang-auth/awesome-angular-auth) | [audit #6](https://github.com/awesome-lang-auth/awesome-angular-auth/issues/6) |
| Flutter / Dart | [`awesome-flutter-auth`](https://github.com/awesome-lang-auth/awesome-flutter-auth) | [audit #19](https://github.com/awesome-lang-auth/awesome-flutter-auth/issues/19) |

---

## Express Authentication with JWT and OAuth2

## Express authentication with awesome-node-auth

Express is the primary target framework for awesome-node-auth. The auth router is Express-compatible out of the box.

▶ **[Open live demo in StackBlitz](https://stackblitz.com/github/awesome-lang-auth/awesome-node-auth/tree/main/demo/express-vanilla?title=awesome-node-auth%20Express%20Demo&startScript=start)**  
Source: [`demo/express-vanilla/`](https://github.com/awesome-lang-auth/awesome-node-auth/tree/main/demo/express-vanilla)

---

### Register → Login → Refresh flow

```mermaid
sequenceDiagram
    autonumber
    participant C as Client (Browser)
    participant S as Express + awesome-node-auth
    participant DB as IUserStore

    C->>S: POST /auth/register {email, password}
    S->>DB: onRegister(data) → create user
    DB-->>S: user {id, email, …}
    S-->>C: 201 {success: true, userId}

    C->>S: POST /auth/login {email, password}
    S->>DB: findByEmail(email)
    DB-->>S: user record
    S->>S: bcrypt.compare(password, hash)
    S-->>C: 200 + Set-Cookie: accessToken (HttpOnly), refreshToken (HttpOnly), csrf-token

    Note over C,S: Later — access token expires

    C->>S: GET /api/profile (expired accessToken cookie)
    S-->>C: 401 Unauthorized

    C->>S: POST /auth/refresh (refreshToken cookie)
    S->>DB: find user by refreshToken
    DB-->>S: user
    S->>S: sign new tokens
    S-->>C: 200 + Set-Cookie: new accessToken, new refreshToken, new csrf-token

    C->>S: GET /api/profile (new accessToken cookie)
    S-->>C: 200 {sub, email, role, …}
```

---

### Basic Setup

```typescript
import express from 'express';
import cookieParser from 'cookie-parser';
import { AuthConfigurator } from '@awesome-lang-auth/node';
import { MyUserStore } from './stores/user-store';

const app = express();
app.use(express.json());
app.use(cookieParser());

const auth = new AuthConfigurator(
  {
    accessTokenSecret: process.env.ACCESS_TOKEN_SECRET!,
    refreshTokenSecret: process.env.REFRESH_TOKEN_SECRET!,
    accessTokenExpiresIn: '15m',
    refreshTokenExpiresIn: '7d',
  },
  new MyUserStore()
);

app.use('/auth', auth.router());

// Protected route
app.get('/api/profile', auth.middleware(), (req, res) => {
  res.json(req.user);
});

app.listen(3000);
```

### With Rate Limiting

```typescript
import rateLimit from 'express-rate-limit';

const limiter = rateLimit({ windowMs: 15 * 60 * 1000, max: 20 });

app.use('/auth', auth.router({ rateLimiter: limiter }));
```

### With All Optional Stores

```typescript
import { MySessionStore } from './stores/session-store';
import { MyRbacStore } from './stores/rbac-store';
import { MyMetadataStore } from './stores/metadata-store';

app.use('/auth', auth.router({
  sessionStore:  new MySessionStore(),
  rbacStore:     new MyRbacStore(),
  metadataStore: new MyMetadataStore(),
  onRegister: async (data) => userStore.create(data),
}));
```

### Related

- [NestJS authentication module](/docs/frameworks/nestjs) — the same library behind Nest's DI
- [Framework-agnostic auth for any Node server](/docs/frameworks/framework-agnostic) — Fastify, Koa, Hono or raw Node
- [Email and password authentication](/docs/authentication/local) — the first recipe to wire up
- [Built-in auth UI](/docs/advanced/built-in-ui) — login pages served by Express itself
- [Auth API endpoints reference](/docs/api-reference/endpoints) — every route the router mounts

---

## NestJS Authentication Module (Guards, JWT)

## NestJS Integration

A complete, production-ready NestJS integration with `AuthModule.forRoot()`, `JwtAuthGuard`, `@CurrentUser()` decorator, and an admin panel.

▶ **[Open live demo in StackBlitz](https://stackblitz.com/github/awesome-lang-auth/awesome-node-auth/tree/main/demo/nestjs-fullstack?title=awesome-node-auth%20NestJS%20Demo&startScript=start)**  
Source: [`demo/nestjs-fullstack/`](https://github.com/awesome-lang-auth/awesome-node-auth/tree/main/demo/nestjs-fullstack)

---

### Auth flow

```mermaid
sequenceDiagram
    autonumber
    participant C as Client
    participant Ctrl as AuthController
    participant Guard as JwtAuthGuard
    participant Auth as AuthConfigurator
    participant DB as IUserStore

    Note over C,DB: Registration
    C->>Ctrl: POST /auth/register {email, password}
    Ctrl->>Auth: router(req)
    Auth->>DB: onRegister → create(data)
    DB-->>Auth: user
    Auth-->>C: 201 {success: true, userId}

    Note over C,DB: Login
    C->>Ctrl: POST /auth/login {email, password}
    Ctrl->>Auth: router(req)
    Auth->>DB: findByEmail(email)
    DB-->>Auth: user
    Auth->>Auth: bcrypt.compare + sign tokens
    Auth-->>C: 200 + Set-Cookie: accessToken, refreshToken, csrf-token

    Note over C,DB: Protected endpoint
    C->>Guard: GET /api/profile (accessToken cookie)
    Guard->>Auth: middleware()(req, res, next)
    Auth->>Auth: verifyAccessToken(cookie)
    Auth-->>Guard: next() sets req.user
    Guard-->>C: 200 {sub, email, role}
```

---

### Step 1 — AuthModule (`forRoot` pattern)

```typescript
import 'reflect-metadata';
import { Module, Global, DynamicModule, Provider } from '@nestjs/common';
import { AuthConfigurator, AuthConfig, IUserStore } from '@awesome-lang-auth/node';

export const AUTH_CONFIGURATOR = 'AUTH_CONFIGURATOR';

@Global()
@Module({})
export class AuthModule {
  static forRoot(options: { config: AuthConfig; userStore: IUserStore }): DynamicModule {
    const configuratorProvider: Provider = {
      provide: AUTH_CONFIGURATOR,
      useFactory: () => new AuthConfigurator(options.config, options.userStore),
    };
    return {
      module: AuthModule,
      providers: [configuratorProvider],
      exports: [AUTH_CONFIGURATOR],
    };
  }
}
```

---

### Step 2 — JwtAuthGuard

```typescript
import { Injectable, CanActivate, ExecutionContext, Inject } from '@nestjs/common';
import { AuthConfigurator } from '@awesome-lang-auth/node';
import { Request, Response } from 'express';

@Injectable()
export class JwtAuthGuard implements CanActivate {
  constructor(@Inject(AUTH_CONFIGURATOR) private readonly auth: AuthConfigurator) {}

  canActivate(context: ExecutionContext): Promise<boolean> {
    const req = context.switchToHttp().getRequest<Request>();
    const res = context.switchToHttp().getResponse<Response>();
    return new Promise<boolean>((resolve, reject) => {
      // NestJS req/res are Express-compatible; bridge via `as any`
      this.auth.middleware()(req as any, res as any, (err?: unknown) => {
        if (err) return reject(err);
        resolve(true);
      });
    });
  }
}
```

---

### Step 3 — @CurrentUser() decorator

```typescript
import { createParamDecorator, ExecutionContext } from '@nestjs/common';
import { Request } from 'express';

export const CurrentUser = createParamDecorator(
  (_data: unknown, ctx: ExecutionContext) =>
    ctx.switchToHttp().getRequest<Request & { user?: any }>().user,
);
```

---

### Step 4 — AuthController

```typescript
import { Controller, All, Req, Res, Next, Inject } from '@nestjs/common';
import { AuthConfigurator, AuthError, PasswordService } from '@awesome-lang-auth/node';
import { Request, Response, NextFunction } from 'express';

@Controller('auth')
export class AuthController {
  private readonly router: ReturnType<AuthConfigurator['router']>;

  constructor(@Inject(AUTH_CONFIGURATOR) auth: AuthConfigurator) {
    this.router = auth.router({
      onRegister: async (data) => {
        const email    = typeof data.email    === 'string' ? data.email.trim()    : '';
        const password = typeof data.password === 'string' ? data.password.trim() : '';
        if (!email || !password)
          throw new AuthError('email and password are required', 'VALIDATION_ERROR', 400);
        const existing = await userStore.findByEmail(email);
        if (existing) throw new AuthError('Email already registered', 'EMAIL_EXISTS', 409);
        const hash = await new PasswordService().hash(password);
        return userStore.create({ email, password: hash, role: 'user' });
      },
    });
  }

  @All('*')
  handle(@Req() req: Request, @Res() res: Response, @Next() next: NextFunction): void {
    // Strip the /auth prefix so the inner router sees paths from /
    req.url = req.url.replace(/^\/auth/, '') || '/';
    // NestJS req/res are Express-compatible; bridge via `as any`
    this.router(req as any, res as any, next);
  }
}
```

---

### Step 5 — Protected route with @CurrentUser()

```typescript
import { Controller, Get, UseGuards } from '@nestjs/common';

@Controller('api')
export class ProfileController {
  @Get('profile')
  @UseGuards(JwtAuthGuard)
  getProfile(@CurrentUser() user: any) {
    return user;   // {sub, email, role, …}
  }
}
```

---

### Step 6 — AppModule & bootstrap

```typescript
import { Module } from '@nestjs/common';
import { NestFactory } from '@nestjs/core';
import { NestExpressApplication } from '@nestjs/platform-express';
import { createAdminRouter } from '@awesome-lang-auth/node';
import * as path from 'path';

const userStore = new MyUserStore();   // your IUserStore implementation

const authConfig = {
  accessTokenSecret:  process.env.ACCESS_TOKEN_SECRET  ?? 'change-me',
  refreshTokenSecret: process.env.REFRESH_TOKEN_SECRET ?? 'change-me',
  accessTokenExpiresIn:  '15m',
  refreshTokenExpiresIn: '7d',
  cookieOptions: {
    secure:   process.env.NODE_ENV === 'production',
    sameSite: 'lax' as const,
  },
};

@Module({
  imports:     [AuthModule.forRoot({ config: authConfig, userStore })],
  providers:   [JwtAuthGuard],
  controllers: [AuthController, ProfileController],
})
class AppModule {}

async function bootstrap() {
  const app = await NestFactory.create<NestExpressApplication>(AppModule);

  app.use(require('cookie-parser')());
  app.enableCors({ origin: true, credentials: true });

  // Admin panel (HTML UI + REST API) at /admin
  app.use('/admin', createAdminRouter(userStore, {
    accessPolicy: 'first-user',
    jwtSecret: process.env.ACCESS_TOKEN_SECRET ?? 'change-me-access-secret',
  }) as any);

  // Serve your frontend static files
  app.useStaticAssets(path.join(__dirname, '..', 'public'));

  await app.listen(Number(process.env.PORT) || 3000);
}

bootstrap();
```

---

### Summary

| Piece | Role |
|-------|------|
| `AuthModule.forRoot()` | Creates `AuthConfigurator` singleton, exports it globally via `AUTH_CONFIGURATOR` token |
| `JwtAuthGuard` | Calls `auth.middleware()` as NestJS `CanActivate` — sets `req.user` on success |
| `@CurrentUser()` | Parameter decorator that extracts `req.user` from the guard |
| `AuthController @All('*')` | Delegates every `/auth/*` request to the awesome-node-auth router |
| `createAdminRouter` | Express router mounted at `/admin` — provides HTML UI and REST API |

### Related

- [Express authentication](/docs/frameworks/express) — the underlying router NestJS wraps
- [Next.js authentication](/docs/frameworks/nextjs) — the same backend behind a Next frontend
- [Custom JWT claims](/docs/advanced/custom-claims) — feed your own claims into Nest guards
- [Auth API endpoints reference](/docs/api-reference/endpoints) — every route the module exposes

---

## Next.js Authentication (Pages Router, JWT)

## Next.js Integration (Pages Router)

A complete working demo is available in the repository — install it and run `npm start` in under a minute.

▶ **[Open live demo in StackBlitz](https://stackblitz.com/github/awesome-lang-auth/awesome-node-auth/tree/main/demo/nextjs-fullstack?title=awesome-node-auth%20Next.js%20Demo&startScript=start)**  
Source: [`demo/nextjs-fullstack/`](https://github.com/awesome-lang-auth/awesome-node-auth/tree/main/demo/nextjs-fullstack)

---

### Auth flow (Pages Router + Edge Middleware)

```mermaid
sequenceDiagram
    autonumber
    participant B as Browser
    participant M as Next.js Edge Middleware
    participant A as /api/auth/[...auth]
    participant R as awesome-node-auth Router
    participant DB as IUserStore

    Note over B,DB: Login
    B->>A: POST /api/auth/login {email, password}
    A->>R: router(req, res) — url rewritten to /login
    R->>DB: findByEmail(email)
    DB-->>R: user
    R->>R: bcrypt.compare + sign tokens
    R-->>B: 200 + Set-Cookie: accessToken (HttpOnly), refreshToken (HttpOnly), csrf-token

    Note over B,M: Navigating to a protected page
    B->>M: GET /dashboard (no accessToken cookie)
    M-->>B: 302 redirect → /login

    B->>M: GET /dashboard (valid accessToken cookie)
    M->>M: verify JWT with Web Crypto API
    M-->>B: Next.js renders /dashboard

    Note over B,DB: Token refresh
    B->>A: POST /api/auth/refresh (refreshToken cookie)
    A->>R: router(req, res) — url rewritten to /refresh
    R->>DB: find user by refreshToken
    DB-->>R: user
    R-->>B: 200 + Set-Cookie: new accessToken, refreshToken, csrf-token
```

---

### Step 1 — Auth singleton (`lib/auth.ts`)

```typescript
import { AuthConfigurator, AuthConfig, IUserStore } from '@awesome-lang-auth/node';
import { MyUserStore } from './user-store';   // your IUserStore implementation

export const authConfig: AuthConfig = {
  accessTokenSecret:  process.env.ACCESS_TOKEN_SECRET!,
  refreshTokenSecret: process.env.REFRESH_TOKEN_SECRET!,
  accessTokenExpiresIn:  '15m',
  refreshTokenExpiresIn: '7d',
  cookieOptions: {
    secure:   process.env.NODE_ENV === 'production',
    sameSite: 'lax',
  },
};

export const userStore: IUserStore = new MyUserStore();

let _auth: AuthConfigurator | undefined;
export function getAuth(): AuthConfigurator {
  if (!_auth) _auth = new AuthConfigurator(authConfig, userStore);
  return _auth;
}
```

---

### Step 2 — Catch-all API route

#### Pages Router (recommended)

The Pages Router is the simplest integration. `bodyParser: false` lets awesome-node-auth's Express middleware parse the body itself:

```typescript
// pages/api/auth/[...auth].ts
import type { NextApiRequest, NextApiResponse } from 'next';
import { getAuth, userStore } from '@/lib/auth';

export const config = { api: { bodyParser: false } };

export default function handler(req: NextApiRequest, res: NextApiResponse) {
  const router = getAuth().router({
    onRegister: async (data) => userStore.create(data),
  });
  // Strip /api/auth prefix so the inner router sees paths starting from /
  req.url = req.url!.replace(/^\/api\/auth/, '') || '/';
  // Next.js req/res are Express-compatible; bridge via `as any`
  router(req as any, res as any, () => res.status(404).end());
}
```

#### Pages Router (admin panel — optional)

```typescript
// pages/api/admin/[...admin].ts
import type { NextApiRequest, NextApiResponse } from 'next';
import { createAdminRouter } from '@awesome-lang-auth/node';
import { userStore } from '@/lib/auth';

const adminRouter = createAdminRouter(userStore, {
  accessPolicy: 'first-user',
  jwtSecret: process.env.ACCESS_TOKEN_SECRET!,
});

export const config = { api: { bodyParser: false } };

export default function handler(req: NextApiRequest, res: NextApiResponse) {
  req.url = req.url!.replace(/^\/api\/admin/, '') || '/';
  // Next.js req/res are Express-compatible; bridge via `as any`
  adminRouter(req as any, res as any, () => res.status(404).end());
}
```

---

### Step 3 — Middleware (route protection)

Next.js Edge Middleware cannot use `jsonwebtoken` (Node.js crypto). Verify the JWT using the Web Crypto API:

```typescript
// middleware.ts  (project root)
import { NextRequest, NextResponse } from 'next/server';

export const config = {
  matcher: ['/dashboard/:path*', '/api/protected/:path*'],
};

export async function middleware(request: NextRequest): Promise<NextResponse> {
  const token = request.cookies.get('accessToken')?.value;

  if (!token) {
    return NextResponse.redirect(new URL('/login', request.url));
  }

  try {
    const [headerB64, payloadB64, signatureB64] = token.split('.');
    const enc  = new TextEncoder();
    const key  = await crypto.subtle.importKey(
      'raw', enc.encode(process.env.ACCESS_TOKEN_SECRET!),
      { name: 'HMAC', hash: 'SHA-256' }, false, ['verify'],
    );
    const sig  = Uint8Array.from(
      atob(signatureB64.replace(/-/g, '+').replace(/_/g, '/')),
      c => c.charCodeAt(0),
    );
    const valid = await crypto.subtle.verify(
      'HMAC', key, sig, enc.encode(`${headerB64}.${payloadB64}`),
    );
    if (!valid) throw new Error('Invalid signature');
    return NextResponse.next();
  } catch {
    return NextResponse.redirect(new URL('/login', request.url));
  }
}
```

---

### Step 4 — Protected API routes (Pages Router)

```typescript
// pages/api/profile.ts
import type { NextApiRequest, NextApiResponse } from 'next';
import { getAuth } from '@/lib/auth';

export default function handler(req: NextApiRequest, res: NextApiResponse) {
  const middleware = getAuth().middleware();
  middleware(req as any, res as any, (err?: unknown) => {
    if (err) return res.status(401).json({ error: 'Unauthorized' });
    res.json({ user: (req as any).user });
  });
}
```

---

### Step 5 — Client-side calls (browser)

node-auth sets tokens as HttpOnly cookies on login. The browser attaches them automatically. Use `credentials: 'include'` on every fetch:

```typescript
// Login
const res = await fetch('/api/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',   // ← sends/receives cookies
  body: JSON.stringify({ email, password }),
});
// { success: true } — tokens are in cookies, not in the body

// Authenticated request (cookie sent automatically)
const profile = await fetch('/api/auth/me', {
  credentials: 'include',
}).then(r => r.json());

// Logout
await fetch('/api/auth/logout', {
  method: 'POST',
  credentials: 'include',
});
```

:::tip CSRF protection
If `csrf.enabled: true` is set in `AuthConfig`, read the `csrf-token` cookie and send it as `X-CSRF-Token` on every `POST`/`PUT`/`PATCH`/`DELETE` request:

```typescript
function getCsrfToken() {
  return document.cookie.match(/(?:^|;\s*)csrf-token=([^;]+)/)?.[1] ?? '';
}

await fetch('/api/auth/logout', {
  method: 'POST',
  headers: { 'X-CSRF-Token': getCsrfToken() },
  credentials: 'include',
});
```
:::

```typescript
import { AuthConfigurator, AuthConfig, IUserStore } from '@awesome-lang-auth/node';
import { MyUserStore } from './user-store';   // your IUserStore implementation

export const authConfig: AuthConfig = {
  accessTokenSecret:  process.env.ACCESS_TOKEN_SECRET!,
  refreshTokenSecret: process.env.REFRESH_TOKEN_SECRET!,
  accessTokenExpiresIn:  '15m',
  refreshTokenExpiresIn: '7d',
  cookieOptions: {
    secure:   process.env.NODE_ENV === 'production',
    sameSite: 'lax',
  },
};

export const userStore: IUserStore = new MyUserStore();

let _auth: AuthConfigurator | undefined;
export function getAuth(): AuthConfigurator {
  if (!_auth) _auth = new AuthConfigurator(authConfig, userStore);
  return _auth;
}
```

---

### Step 2 — Catch-all API route

#### Pages Router (recommended)

The Pages Router is the simplest integration. `bodyParser: false` lets awesome-node-auth's Express middleware parse the body itself:

```typescript
// pages/api/auth/[...auth].ts
import type { NextApiRequest, NextApiResponse } from 'next';
import { getAuth, userStore } from '@/lib/auth';

export const config = { api: { bodyParser: false } };

export default function handler(req: NextApiRequest, res: NextApiResponse) {
  const router = getAuth().router({ onRegister: async (data) => userStore.create(data) });
  // Strip /api/auth prefix so the inner router sees paths starting from /
  req.url = req.url!.replace(/^\/api\/auth/, '') || '/';
  router(req as any, res as any, () => res.status(404).end());
}
```

#### App Router

The App Router request/response model differs from Node.js `http`. Bridging it to an Express router requires a non-trivial adapter. A complete, production-ready implementation is available in:

[`examples/nextjs-integration.example.ts`](https://github.com/awesome-lang-auth/awesome-node-auth/blob/main/examples/nextjs-integration.example.ts)

Copy the `runNodeAuthRouter` function and the `GET`/`POST`/`DELETE` exports from that file into `app/api/auth/[...auth]/route.ts`.

#### Pages Router (admin panel — optional)

```typescript
// pages/api/admin/[...admin].ts
import type { NextApiRequest, NextApiResponse } from 'next';
import { createAdminRouter } from '@awesome-lang-auth/node';
import { userStore, linkedAccountsStore, settingsStore } from '@/lib/auth';

const adminRouter = createAdminRouter(userStore, {
  accessPolicy: 'first-user',
  jwtSecret: process.env.ACCESS_TOKEN_SECRET!,
  linkedAccountsStore,
  settingsStore,
});

export const config = { api: { bodyParser: false } };

export default function handler(req: NextApiRequest, res: NextApiResponse) {
  req.url = req.url!.replace(/^\/api\/admin/, '') || '/';
  adminRouter(req as any, res as any, () => res.status(404).end());
}
```

---

### Step 3 — Middleware (route protection)

Next.js Edge Middleware cannot use `jsonwebtoken` (Node.js crypto). Verify the JWT using the Web Crypto API:

```typescript
// middleware.ts  (project root)
import { NextRequest, NextResponse } from 'next/server';

export const config = {
  matcher: ['/dashboard/:path*', '/api/protected/:path*'],
};

export async function middleware(request: NextRequest): Promise<NextResponse> {
  const token = request.cookies.get('accessToken')?.value;

  if (!token) {
    return NextResponse.redirect(new URL('/login', request.url));
  }

  try {
    const [headerB64, payloadB64, signatureB64] = token.split('.');
    const enc  = new TextEncoder();
    const key  = await crypto.subtle.importKey(
      'raw', enc.encode(process.env.ACCESS_TOKEN_SECRET!),
      { name: 'HMAC', hash: 'SHA-256' }, false, ['verify'],
    );
    const sig  = Uint8Array.from(atob(signatureB64.replace(/-/g, '+').replace(/_/g, '/')), c => c.charCodeAt(0));
    const valid = await crypto.subtle.verify('HMAC', key, sig, enc.encode(`${headerB64}.${payloadB64}`));
    if (!valid) throw new Error('Invalid signature');
    return NextResponse.next();
  } catch {
    return NextResponse.redirect(new URL('/login', request.url));
  }
}
```

---

### Step 4 — Protected Server Component

```typescript
// app/dashboard/page.tsx
import { cookies } from 'next/headers';
import { redirect } from 'next/navigation';
import { TokenService } from '@awesome-lang-auth/node';
import { authConfig } from '@/lib/auth';

export default async function DashboardPage() {
  const cookieStore = cookies();
  const token = cookieStore.get('accessToken')?.value;

  if (!token) redirect('/login');

  const tokenService = new TokenService();
  const payload = tokenService.verifyAccessToken(token, authConfig);

  return <div>Welcome, {payload.email}!</div>;
}
```

---

### Step 5 — Protected API routes (Pages Router)

```typescript
// pages/api/profile.ts
import type { NextApiRequest, NextApiResponse } from 'next';
import { getAuth } from '@/lib/auth';

export default function handler(req: NextApiRequest, res: NextApiResponse) {
  const middleware = getAuth().middleware();
  middleware(req as any, res as any, (err?: unknown) => {
    if (err) return res.status(401).json({ error: 'Unauthorized' });
    res.json({ user: (req as any).user });
  });
}
```

---

### Step 6 — Client-side calls (browser)

node-auth sets tokens as HttpOnly cookies on login. The browser attaches them automatically. Use `credentials: 'include'` on every fetch:

```typescript
// Login
const res = await fetch('/api/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',   // ← sends/receives cookies
  body: JSON.stringify({ email, password }),
});
const data = await res.json();
// data = { success: true } — tokens are in cookies, not in the body

// Authenticated request (cookie is sent automatically)
const profile = await fetch('/api/auth/me', {
  credentials: 'include',
}).then(r => r.json());

// Logout
await fetch('/api/auth/logout', {
  method: 'POST',
  credentials: 'include',
});
```

:::tip CSRF protection
If `csrf.enabled: true` is set in `AuthConfig`, read the `csrf-token` cookie and send it as `X-CSRF-Token` on every `POST`/`PUT`/`PATCH`/`DELETE` request:

```typescript
function getCsrfToken() {
  return document.cookie.match(/(?:^|;\s*)csrf-token=([^;]+)/)?.[1] ?? '';
}

await fetch('/api/auth/logout', {
  method: 'POST',
  headers: { 'X-CSRF-Token': getCsrfToken() },
  credentials: 'include',
});
```
:::

### Related

- [Express authentication](/docs/frameworks/express) — the router behind the API routes
- [NestJS authentication module](/docs/frameworks/nestjs) — a heavier backend for the same frontend
- [auth.js browser client](/docs/advanced/browser-client) — session handling in the browser
- [OAuth2 social login](/docs/authentication/oauth) — add Google and GitHub sign-in

---

## Framework-Agnostic Auth for Any Node HTTP Server

## Framework-Agnostic Usage

awesome-node-auth ships with **framework-neutral HTTP type interfaces** so that
the core library can be wired into any Node.js HTTP framework — Express,
Fastify, Koa, NestJS, Next.js Route Handlers, or a plain `http.Server` — using
the same public API.

:::info Express is still the default
The built-in routers (`createAuthRouter`, `createAdminRouter`, `buildUiRouter`)
are implemented with Express and return Express `Router` objects.  This page
describes the **type-level** framework-agnostic surface that was introduced in
**v1.7** so that non-Express consumers get a clean, typed integration path.
:::

---

### Architecture overview

```
awesome-node-auth
├── src/http-types.ts        Framework-neutral interfaces
│   ├── AuthRequest          Minimal request shape (headers, cookies, body, …)
│   ├── AuthResponse         Minimal response shape (status, json, cookie, …)
│   ├── AuthNextFunction     (err?: unknown) => void
│   ├── AuthRequestHandler   (req, res, next) => void | Promise<void>
│   └── AuthRouter           Route-registration interface
│
└── src/adapters/
    └── express.ts           Express adapter
        ├── re-exports Router, RequestHandler, Request, Response, NextFunction
        └── expressAdapter() — cast AuthRequestHandler → Express RequestHandler
```

The neutral types live in **`src/http-types.ts`** and are exported directly
from the main package entry point:

```typescript
import type {
  AuthRequest,
  AuthResponse,
  AuthNextFunction,
  AuthRequestHandler,
  AuthRouter,
} from '@awesome-lang-auth/node';
```

---

### Express (default — zero changes required)

Existing Express code continues to compile without modification.
`AuthRequestHandler` uses `any` for its parameter types — a deliberate choice
that makes every Express `RequestHandler` directly assignable without a cast.

:::note Why `any` and not `AuthRequest`?
TypeScript enforces *contravariance* on function parameter types
(`strictFunctionTypes`).  If the parameters were typed as `AuthRequest`,
then `(req: Express.Request) => void` would **not** be assignable to
`(req: AuthRequest) => void` — because `Express.Request` is a *subtype* of
`AuthRequest`, and subtype parameters fail contravariant checks.
Using `any` bypasses this check, making Express, Fastify, Koa, and all
third-party middleware directly assignable without an explicit cast.
:::

```typescript
import express from 'express';
import rateLimit from 'express-rate-limit';
import { AuthConfigurator } from '@awesome-lang-auth/node';

const auth = new AuthConfigurator(config, userStore);

// rateLimiter now typed as AuthRequestHandler — Express RequestHandler still works
app.use('/auth', auth.router({
  rateLimiter: rateLimit({ windowMs: 60_000, max: 20 }),
}));
```

---

### Writing framework-neutral middleware

When you write custom middleware that should work across frameworks, target the
neutral `AuthRequestHandler` type.  On Express, pass it through
`expressAdapter()` to get the correct Express typing for `app.use()`:

```typescript
import type { AuthRequestHandler } from '@awesome-lang-auth/node';
import { expressAdapter } from '@awesome-lang-auth/node';

// Typed against the neutral interface
const requestLogger: AuthRequestHandler = (req, res, next) => {
  console.log(`${req.method} ${req.url}`);
  next();
};

// Mount on Express (no cast needed — expressAdapter is a zero-overhead helper)
app.use(expressAdapter(requestLogger));
```

---

### NestJS

In a NestJS application you use `AuthConfigurator` directly inside a service or
guard.  NestJS decorates its own `ExecutionContext`-based request objects, but
the `AuthRequest` interface is broad enough to accommodate them:

```typescript
import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
import type { AuthRequest } from '@awesome-lang-auth/node';

@Injectable()
export class JwtGuard implements CanActivate {
  canActivate(context: ExecutionContext): boolean {
    const req = context.switchToHttp().getRequest<AuthRequest>();
    return !!req.user;
  }
}
```

See the full [NestJS integration guide](/docs/frameworks/nestjs) for a
complete DI-based setup.

---

### Next.js App Router

Next.js App Router uses `NextRequest` / `NextResponse` which do **not** extend
Express types.  Map them onto `AuthRequest` / `AuthResponse` to use
awesome-node-auth's token service directly:

```typescript
// app/api/me/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { TokenService } from '@awesome-lang-auth/node';
import type { AuthRequest } from '@awesome-lang-auth/node';

const tokenService = new TokenService();

export async function GET(request: NextRequest) {
  // Map NextRequest to AuthRequest
  const authReq: AuthRequest = {
    headers: Object.fromEntries(request.headers.entries()),
    cookies: Object.fromEntries(
      request.cookies.getAll().map(({ name, value }) => [name, value])
    ),
    method: request.method,
    url: request.url,
  };

  const token = authReq.cookies?.['accessToken'];
  if (!token) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });

  // Validate token using the framework-neutral service
  const payload = tokenService.verifyAccessToken(token, config.accessTokenSecret);
  return NextResponse.json(payload);
}
```

See the full [Next.js integration guide](/docs/frameworks/nextjs) for a
complete App Router setup including middleware.

---

### Implementing your own adapter

If you are integrating with a framework not listed here, implement the
`AuthRequest` and `AuthResponse` interfaces for your framework's native objects
and pass the resulting handler to your framework's router:

```typescript
import type { AuthRequest, AuthResponse, AuthNextFunction } from '@awesome-lang-auth/node';
import { createAuthMiddleware } from '@awesome-lang-auth/node';

// 1. Create the framework-neutral middleware
const authMiddleware = createAuthMiddleware(config, sessionStore);

// 2. Wrap it for your framework (example: Koa)
koaRouter.use(async (ctx, next) => {
  const req: AuthRequest = {
    headers: ctx.headers as Record<string, string | string[] | undefined>,
    cookies: ctx.cookies ? Object.fromEntries(
      Object.entries(ctx.cookies) as [string, string][]
    ) : undefined,
    method: ctx.method,
    path: ctx.path,
    url: ctx.url,
    ip: ctx.ip,
  };

  const res: AuthResponse = {
    status(code) { ctx.status = code; return this; },
    json(body) { ctx.body = body; return this; },
    send(body) { ctx.body = body; return this; },
    end() { /* handled by Koa */ },
    cookie(name, value, options) { ctx.cookies.set(name, value, options as any); return this; },
    clearCookie(name, options) { ctx.cookies.set(name, '', { maxAge: 0, ...options as any }); return this; },
    redirect(urlOrStatus: string | number, url?: string) {
      ctx.redirect(typeof urlOrStatus === 'string' ? urlOrStatus : url!);
    },
    setHeader(name, value) {
      ctx.set(name, Array.isArray(value) ? value.join(', ') : value);
      return this;
    },
  };

  await new Promise<void>((resolve, reject) => {
    authMiddleware(req, res, (err?: unknown) => (err ? reject(err) : resolve()));
  });

  await next();
});
```

---

### Exported symbols reference

| Symbol | Kind | Description |
|--------|------|-------------|
| `AuthRequest` | `interface` | Minimal request shape (headers, cookies, body, …) |
| `AuthResponse` | `interface` | Minimal response shape (status, json, cookie, …) |
| `AuthNextFunction` | `type` | `(err?: unknown) => void` |
| `AuthRequestHandler` | `type` | `(req, res, next) => void \| Promise<void>` |
| `AuthRouter` | `interface` | Route-registration interface |
| `expressAdapter` | `function` | Cast `AuthRequestHandler` → Express `RequestHandler` |

---

## Angular SSR Authentication — Manual Wiring

:::tip Prefer the official Angular library
**For new projects, use [`@awesome-lang-auth/angular`](/docs/frameworks/ng-awesome-node-auth)** — the official Angular library that provides Guards, Interceptors, reactive session signals, CSRF support, and SSR wiring out of the box with a single `provideAuth()` call.

This page documents the **manual wiring approach** for teams that want full control over the Angular auth layer or need to integrate into an existing codebase.
:::

## Angular Integration — Manual Wiring (SSR)

This guide covers a **production-ready** Angular 17+ standalone application that integrates with awesome-node-auth. It includes:

- Cookie-based auth — awesome-node-auth manages **access token**, **refresh token**, and **CSRF token** automatically via HttpOnly cookies; no manual token storage needed
- HTTP interceptor with **CSRF header** support and **concurrent-refresh queue** (handles multiple simultaneous 401s)
- `authGuard`, `guestGuard`, `roleGuard`, and `canMatchGuard`
- `APP_INITIALIZER` for silent session restore on page reload
- Full **SSR** wiring that forwards browser cookies to the API server

:::info Cookie-based vs Bearer Token
By default, awesome-node-auth sets `accessToken`, `refreshToken`, and `csrf-token` as **HttpOnly cookies** on every login/refresh response. The Angular app does **not** need to read, store, or attach these tokens manually — the browser handles them automatically when `withCredentials: true` is set.

Bearer-token mode (where tokens are returned in the response body and managed manually) is intended for **native/mobile clients**. See the [Bearer Token](/docs/advanced/bearer-token) guide for that approach.
:::

### Project structure

```
src/app/
├── auth/
│   ├── auth.service.ts          # user state + login/logout/refresh
│   ├── auth.interceptor.ts      # CSRF header + handle 401 + refresh queue
│   ├── auth.guard.ts            # authGuard, guestGuard, roleGuard, canMatchGuard
│   ├── auth.initializer.ts      # APP_INITIALIZER – silent restore on reload
│   └── ssr-cookie.interceptor.ts  # SSR: forward browser cookies to API
├── app.config.ts                # browser providers
├── app.config.server.ts         # server-side providers (SSR)
├── app.routes.ts                # full route config
└── pages/
    ├── login/login.component.ts
    └── dashboard/dashboard.component.ts
```

---

### Installation

```bash
# Angular 17+ built-in SSR scaffold
ng new my-app --ssr
cd my-app

# or add SSR to an existing project
ng add @angular/ssr
```

---

### Step 1 — Auth Service

The service owns all user state. Because awesome-node-auth delivers tokens via **HttpOnly cookies**, the Angular app never reads or stores tokens directly — it simply calls the auth endpoints with `withCredentials: true` and fetches user data from `GET /auth/me`.

```typescript
// src/app/auth/auth.service.ts
import { Injectable, inject } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import { BehaviorSubject, Observable, of } from 'rxjs';
import { tap, catchError, map, switchMap } from 'rxjs/operators';

export interface AuthUser {
  sub: string;
  email: string;
  role?: string;
  tenantId?: string;
  /** Additional custom claims added via `config.buildTokenPayload`. */
  [key: string]: unknown;
}

/** Shape returned by GET /auth/sessions (requires ISessionStore on the server). */
export interface SessionInfo {
  sessionHandle: string;
  userId: string;
  userAgent?: string;
  ipAddress?: string;
  createdAt: Date | string;
  lastActiveAt?: Date | string;
  expiresAt?: Date | string;
  [key: string]: unknown;
}

@Injectable({ providedIn: 'root' })
export class AuthService {
  private readonly http = inject(HttpClient);

  private _user$ = new BehaviorSubject<AuthUser | null>(null);

  readonly user$ = this._user$.asObservable();

  get currentUser(): AuthUser | null { return this._user$.value; }
  get isLoggedIn(): boolean          { return this._user$.value !== null; }

  // ── Login ──────────────────────────────────────────────────────────────────
  // awesome-node-auth sets accessToken + refreshToken + csrf-token cookies on success.
  // We then call /auth/me to get the current user's profile.

  login(email: string, password: string): Observable<AuthUser> {
    return this.http
      .post<void>('/auth/login', { email, password }, { withCredentials: true })
      .pipe(switchMap(() => this.fetchCurrentUser()));
  }

  // ── Logout ─────────────────────────────────────────────────────────────────

  logout(): Observable<void> {
    return this.http
      .post<void>('/auth/logout', {}, { withCredentials: true })
      .pipe(
        tap(() => this._user$.next(null)),
        catchError(() => { this._user$.next(null); return of(void 0); }),
      );
  }

  // ── Refresh ────────────────────────────────────────────────────────────────
  // The refreshToken HttpOnly cookie is sent automatically — no manual token
  // handling required.  After a successful refresh, new cookies are set and
  // we re-fetch the user profile.

  refresh(): Observable<AuthUser> {
    return this.http
      .post<void>('/auth/refresh', {}, { withCredentials: true })
      .pipe(switchMap(() => this.fetchCurrentUser()));
  }

  // ── Silent restore (called by APP_INITIALIZER) ─────────────────────────────
  // Tries to silently refresh the session using the stored refresh cookie.
  // Returns true on success, false if no valid session exists.

  tryRestoreSession(): Observable<boolean> {
    return this.refresh().pipe(
      map(() => true),
      catchError(() => of(false)),
    );
  }

  // ── Fetch current user ─────────────────────────────────────────────────────

  fetchCurrentUser(): Observable<AuthUser> {
    return this.http
      .get<AuthUser>('/auth/me', { withCredentials: true })
      .pipe(tap((user) => this._user$.next(user)));
  }

  // ── Active sessions (device management) ───────────────────────────────────
  // Lists all active sessions for the current user ("Manage devices" screen).
  // Requires ISessionStore configured on the server.

  getActiveSessions(): Observable<SessionInfo[]> {
    return this.http
      .get<{ sessions: SessionInfo[] }>('/auth/sessions', { withCredentials: true })
      .pipe(map(res => res.sessions));
  }

  /** Revoke a specific session by handle (removes from store + logs out that device). */
  revokeSession(sessionHandle: string): Observable<void> {
    return this.http
      .delete<void>(`/auth/sessions/${encodeURIComponent(sessionHandle)}`, { withCredentials: true });
  }
}
```

---

### Step 2 — HTTP Interceptor (CSRF + refresh queue)

node-auth uses the **double-submit cookie pattern** for CSRF protection when `csrf.enabled` is `true`. The `csrf-token` cookie is readable by JavaScript (not HttpOnly). In awesome-node-auth v1.3+, the cookie is prefixed with `__Host-` (or `__Secure-`) when `cookieOptions.secure` is `true` to prevent cookie-tossing attacks. The interceptor reads the cookie (checking all three name variants in priority order) and sends it as an `X-CSRF-Token` header on **POST, PUT, PATCH, and DELETE** requests.

A naive interceptor that simply retries on 401 breaks when **multiple requests fire concurrently** — each would trigger its own refresh call, causing race conditions.  
The implementation below uses a **refresh queue**: the first 401 starts a single refresh; all subsequent 401s wait for that same refresh to complete.

```typescript
// src/app/auth/auth.interceptor.ts
import {
  HttpInterceptorFn,
  HttpRequest,
  HttpHandlerFn,
  HttpErrorResponse,
} from '@angular/common/http';
import { inject } from '@angular/core';
import { BehaviorSubject, throwError, Observable } from 'rxjs';
import { catchError, switchMap, filter, take } from 'rxjs/operators';
import { AuthService } from './auth.service';

// Module-level state so the queue survives across calls
let isRefreshing          = false;
const refreshDone$        = new BehaviorSubject<boolean>(false);

export const authInterceptor: HttpInterceptorFn = (
  req: HttpRequest<unknown>,
  next: HttpHandlerFn,
) => {
  const auth = inject(AuthService);

  // Add X-CSRF-Token header to state-changing requests (CSRF double-submit pattern)
  const modified = addCsrfHeader(req);

  return next(modified).pipe(
    catchError((err: HttpErrorResponse) => {
      if (err.status !== 401 || req.url.includes('/auth/refresh')) {
        return throwError(() => err);
      }
      // SESSION_REVOKED is a permanent failure — the server has killed the
      // session, so attempting a refresh would only waste a round-trip and
      // could cause a loop.  Force an immediate local logout instead.
      if ((err.error as { code?: string } | null)?.code === 'SESSION_REVOKED') {
        auth.logout().subscribe();
        return throwError(() => err);
      }
      return handle401(req, next, auth);
    }),
  );
};

// ── CSRF header ───────────────────────────────────────────────────────────────

function addCsrfHeader(req: HttpRequest<unknown>): HttpRequest<unknown> {
  if (!['POST', 'PUT', 'PATCH', 'DELETE'].includes(req.method)) return req;
  const token = getCsrfCookie();
  if (!token) return req;
  return req.clone({ setHeaders: { 'X-CSRF-Token': token } });
}

function getCsrfCookie(): string | null {
  if (typeof document === 'undefined') return null;
  // awesome-node-auth v1.3+ uses __Host- / __Secure- prefixes for cookie-tossing protection.
  // Check all three names in priority order so this works in both dev and production.
  const names = ['__Host-csrf-token', '__Secure-csrf-token', 'csrf-token'];
  for (const name of names) {
    const val = document.cookie
      .split('; ')
      .find((row) => row.startsWith(`${name}=`))
      ?.split('=')[1];
    if (val) return decodeURIComponent(val);
  }
  return null;
}

// ── 401 handler with queue ────────────────────────────────────────────────────

function handle401(
  req: HttpRequest<unknown>,
  next: HttpHandlerFn,
  auth: AuthService,
): Observable<unknown> {
  if (!isRefreshing) {
    isRefreshing = true;
    refreshDone$.next(false);

    return auth.refresh().pipe(
      switchMap(() => {
        isRefreshing = false;
        refreshDone$.next(true);     // unblock queued requests
        return next(addCsrfHeader(req));
      }),
      catchError((refreshErr) => {
        isRefreshing = false;
        refreshDone$.next(false);
        auth.logout().subscribe();
        return throwError(() => refreshErr);
      }),
    );
  }

  // Another refresh is already in-flight — wait for it to complete
  return refreshDone$.pipe(
    filter((done) => done === true),
    take(1),
    switchMap(() => next(addCsrfHeader(req))),
  );
}
```

---

### Step 3 — Guards

#### `authGuard` — require login

```typescript
// src/app/auth/auth.guard.ts
import { inject } from '@angular/core';
import { CanActivateFn, CanMatchFn, Router, UrlTree } from '@angular/router';
import { map, take } from 'rxjs/operators';
import { AuthService } from './auth.service';

/** Redirect unauthenticated users to /login. */
export const authGuard: CanActivateFn = (_route, state) => {
  const auth   = inject(AuthService);
  const router = inject(Router);

  return auth.user$.pipe(
    take(1),
    map((user) =>
      user ? true : router.createUrlTree(['/login'], { queryParams: { returnUrl: state.url } }),
    ),
  );
};

/** Same check for canMatch (lazy-loaded feature modules). */
export const authCanMatch: CanMatchFn = () => {
  const auth   = inject(AuthService);
  const router = inject(Router);

  return auth.user$.pipe(
    take(1),
    map((user): boolean | UrlTree => user ? true : router.createUrlTree(['/login'])),
  );
};
```

#### `guestGuard` — redirect already-logged-in users away from /login

```typescript
/** Redirect authenticated users away from the login page. */
export const guestGuard: CanActivateFn = () => {
  const auth   = inject(AuthService);
  const router = inject(Router);

  return auth.user$.pipe(
    take(1),
    map((user) => user ? router.createUrlTree(['/dashboard']) : true),
  );
};
```

#### `roleGuard` — role-based access control

```typescript
/** Require a specific role. Usage: canActivate: [roleGuard('admin')] */
export function roleGuard(requiredRole: string): CanActivateFn {
  return () => {
    const auth   = inject(AuthService);
    const router = inject(Router);

    return auth.user$.pipe(
      take(1),
      map((user): boolean | UrlTree => {
        if (!user)            return router.createUrlTree(['/login']);
        if (user.role !== requiredRole) return router.createUrlTree(['/403']);
        return true;
      }),
    );
  };
}
```

---

### Step 4 — Route Configuration

```typescript
// src/app/app.routes.ts
import { Routes } from '@angular/router';
import { authGuard, authCanMatch, guestGuard, roleGuard } from './auth/auth.guard';

export const routes: Routes = [
  { path: '', redirectTo: 'dashboard', pathMatch: 'full' },

  // Public — redirect to /dashboard if already logged in
  {
    path: 'login',
    canActivate: [guestGuard],
    loadComponent: () => import('./pages/login/login.component'),
  },
  {
    path: 'register',
    canActivate: [guestGuard],
    loadComponent: () => import('./pages/register/register.component'),
  },

  // Protected — requires authentication
  {
    path: 'dashboard',
    canActivate: [authGuard],
    canMatch:    [authCanMatch],
    loadComponent: () => import('./pages/dashboard/dashboard.component'),
  },

  // Protected — requires admin role
  {
    path: 'admin',
    canActivate: [roleGuard('admin')],
    loadChildren: () => import('./admin/admin.routes').then((m) => m.ADMIN_ROUTES),
  },

  { path: '403', loadComponent: () => import('./pages/forbidden/forbidden.component') },
  { path: '**',  loadComponent: () => import('./pages/not-found/not-found.component') },
];
```

---

### Step 5 — APP_INITIALIZER (silent session restore)

When the user reloads the page, the `AuthService` user state is lost, but the **refresh token HttpOnly cookie** is still in the browser. `APP_INITIALIZER` runs before the app renders, calls `POST /auth/refresh` (which sets fresh cookies server-side), then fetches the user profile so the user stays logged in.

```typescript
// src/app/auth/auth.initializer.ts
import { inject } from '@angular/core';
import { APP_INITIALIZER, EnvironmentProviders, makeEnvironmentProviders } from '@angular/core';
import { isPlatformBrowser } from '@angular/common';
import { PLATFORM_ID } from '@angular/core';
import { AuthService } from './auth.service';

function initializeAuth(auth: AuthService, platformId: object) {
  return () => {
    // Skip on server — the SSR context handles its own auth (see Step 7)
    if (!isPlatformBrowser(platformId)) return Promise.resolve();
    return auth.tryRestoreSession().toPromise();
  };
}

/** Drop this into the `providers` array of `appConfig`. */
export function provideAuthInitializer(): EnvironmentProviders {
  return makeEnvironmentProviders([
    {
      provide: APP_INITIALIZER,
      useFactory: (auth: AuthService, platformId: object) => initializeAuth(auth, platformId),
      deps: [AuthService, PLATFORM_ID],
      multi: true,
    },
  ]);
}
```

---

### Step 6 — App Configuration (browser)

```typescript
// src/app/app.config.ts
import { ApplicationConfig } from '@angular/core';
import { provideRouter, withComponentInputBinding, withViewTransitions } from '@angular/router';
import { provideHttpClient, withInterceptors, withFetch } from '@angular/common/http';
import { authInterceptor } from './auth/auth.interceptor';
import { provideAuthInitializer } from './auth/auth.initializer';
import { routes } from './app.routes';

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes, withComponentInputBinding(), withViewTransitions()),
    provideHttpClient(
      withFetch(),                          // required for SSR — uses native fetch
      withInterceptors([authInterceptor]),
    ),
    provideAuthInitializer(),
  ],
};
```

---

### Step 7 — SSR Wiring

#### `app.config.server.ts`

```typescript
// src/app/app.config.server.ts
import { mergeApplicationConfig, ApplicationConfig } from '@angular/core';
import { provideServerRendering } from '@angular/platform-server';
import { provideHttpClient, withFetch, withInterceptors } from '@angular/common/http';
import { appConfig } from './app.config';
import { ssrCookieInterceptor } from './auth/ssr-cookie.interceptor';
import { authInterceptor } from './auth/auth.interceptor';

const serverConfig: ApplicationConfig = {
  providers: [
    provideServerRendering(),
    // Override HttpClient for SSR: add the cookie-forwarding interceptor
    provideHttpClient(
      withFetch(),
      withInterceptors([ssrCookieInterceptor, authInterceptor]),
    ),
  ],
};

export const config = mergeApplicationConfig(appConfig, serverConfig);
```

#### `src/server.ts` (Express wrapper for SSR)

```typescript
// src/server.ts  (generated by ng add @angular/ssr, shown for reference)
import { APP_BASE_HREF } from '@angular/common';
import { CommonEngine } from '@angular/ssr';
import express from 'express';
import { fileURLToPath } from 'node:url';
import { dirname, join, resolve } from 'node:path';
import bootstrap from './main.server';

export function app(): express.Express {
  const server  = express();
  const __dir   = dirname(fileURLToPath(import.meta.url));
  const browser = resolve(__dir, '../browser');

  server.set('view engine', 'html');
  server.set('views', browser);
  server.use(express.static(browser, { maxAge: '1y' }));

  const engine = new CommonEngine();

  server.get('**', (req, res, next) => {
    engine
      .render({
        bootstrap,
        documentFilePath: join(browser, 'index.html'),
        url: req.originalUrl,
        publicPath: browser,
        providers: [
          { provide: APP_BASE_HREF, useValue: req.baseUrl },
          // Pass the incoming request so the SSR cookie interceptor can forward cookies
          { provide: 'REQUEST',  useValue: req },
          { provide: 'RESPONSE', useValue: res },
        ],
      })
      .then((html) => res.send(html))
      .catch(next);
  });

  return server;
}
```

#### `ssr-cookie.interceptor.ts` — forward browser cookies to the API

During SSR, `withCredentials: true` has no effect because there is no browser cookie jar. Instead, this interceptor reads the `Cookie` header from the incoming Express `Request` and forwards it to every outgoing API call, so the awesome-node-auth server receives the user's auth cookies correctly.

```typescript
// src/app/auth/ssr-cookie.interceptor.ts
import { HttpInterceptorFn } from '@angular/common/http';
import { inject, PLATFORM_ID, InjectionToken } from '@angular/core';
import { isPlatformServer } from '@angular/common';

export const REQUEST = new InjectionToken<{ headers?: { cookie?: string } }>('REQUEST');

export const ssrCookieInterceptor: HttpInterceptorFn = (req, next) => {
  const platformId = inject(PLATFORM_ID);
  const request    = inject(REQUEST, { optional: true });

  if (!isPlatformServer(platformId) || !request) {
    return next(req);
  }

  const cookieHeader = request.headers?.cookie;
  if (!cookieHeader) return next(req);

  // Forward the browser's cookies verbatim so awesome-node-auth can read them server-side
  return next(req.clone({ setHeaders: { Cookie: cookieHeader } }));
};
```

---

### Step 8 — Page Components

#### Login

```typescript
// src/app/pages/login/login.component.ts
import { Component, inject } from '@angular/core';
import { FormBuilder, ReactiveFormsModule, Validators } from '@angular/forms';
import { Router, ActivatedRoute } from '@angular/router';
import { AuthService } from '../../auth/auth.service';
import { NgIf } from '@angular/common';

@Component({
  standalone: true,
  selector: 'app-login',
  imports: [ReactiveFormsModule, NgIf],
  template: `
    <form [formGroup]="form" (ngSubmit)="submit()">
      <input formControlName="email"    type="email"    placeholder="Email"    autocomplete="email" />
      <input formControlName="password" type="password" placeholder="Password" autocomplete="current-password" />
      <p *ngIf="error" class="error">{{ error }}</p>
      <button type="submit" [disabled]="form.invalid || loading">
        {{ loading ? 'Signing in…' : 'Sign in' }}
      </button>
    </form>
  `,
})
export default class LoginComponent {
  private auth  = inject(AuthService);
  private router = inject(Router);
  private route  = inject(ActivatedRoute);
  private fb     = inject(FormBuilder);

  form = this.fb.group({
    email:    ['', [Validators.required, Validators.email]],
    password: ['', Validators.required],
  });

  loading = false;
  error   = '';

  submit() {
    if (this.form.invalid) return;
    this.loading = true;
    this.error   = '';
    const { email, password } = this.form.value;
    this.auth.login(email!, password!).subscribe({
      next: () => {
        const returnUrl = this.route.snapshot.queryParams['returnUrl'] ?? '/dashboard';
        this.router.navigateByUrl(returnUrl);
      },
      error: (e) => {
        this.error   = e.error?.message ?? 'Login failed';
        this.loading = false;
      },
    });
  }
}
```

#### Register

```typescript
// src/app/pages/register/register.component.ts
import { Component, inject } from '@angular/core';
import { FormBuilder, ReactiveFormsModule, Validators } from '@angular/forms';
import { Router } from '@angular/router';
import { HttpClient } from '@angular/common/http';
import { NgIf } from '@angular/common';

@Component({
  standalone: true,
  selector: 'app-register',
  imports: [ReactiveFormsModule, NgIf],
  template: `
    <form [formGroup]="form" (ngSubmit)="submit()">
      <input formControlName="name"     type="text"     placeholder="Full name" />
      <input formControlName="email"    type="email"    placeholder="Email" />
      <input formControlName="password" type="password" placeholder="Password" />
      <p *ngIf="error" class="error">{{ error }}</p>
      <button type="submit" [disabled]="form.invalid || loading">
        {{ loading ? 'Creating account…' : 'Create account' }}
      </button>
    </form>
  `,
})
export default class RegisterComponent {
  private http   = inject(HttpClient);
  private router = inject(Router);
  private fb     = inject(FormBuilder);

  form = this.fb.group({
    name:     ['', Validators.required],
    email:    ['', [Validators.required, Validators.email]],
    password: ['', [Validators.required, Validators.minLength(8)]],
  });

  loading = false;
  error   = '';

  submit() {
    if (this.form.invalid) return;
    this.loading = true;
    this.http.post('/auth/register', this.form.value).subscribe({
      next: () => this.router.navigateByUrl('/login'),
      error: (e) => { this.error = e.error?.message ?? 'Registration failed'; this.loading = false; },
    });
  }
}
```

#### Navbar with logout

```typescript
// src/app/components/navbar/navbar.component.ts
import { Component, inject } from '@angular/core';
import { Router, RouterLink } from '@angular/router';
import { AsyncPipe, NgIf } from '@angular/common';
import { AuthService } from '../../auth/auth.service';

@Component({
  standalone: true,
  selector: 'app-navbar',
  imports: [RouterLink, AsyncPipe, NgIf],
  template: `
    <nav>
      <a routerLink="/">Home</a>
      <ng-container *ngIf="auth.user$ | async as user; else guestLinks">
        <span>{{ user.email }}</span>
        <button (click)="logout()">Logout</button>
      </ng-container>
      <ng-template #guestLinks>
        <a routerLink="/login">Sign in</a>
        <a routerLink="/register">Register</a>
      </ng-template>
    </nav>
  `,
})
export class NavbarComponent {
  readonly auth   = inject(AuthService);
  private  router = inject(Router);

  logout() {
    this.auth.logout().subscribe(() => this.router.navigateByUrl('/login'));
  }
}
```

---

### Step 9 — TOTP / 2FA flow

When the server responds with `{ requiresTwoFactor: true, tempToken, available2faMethods }` on login, store the `tempToken` and show the TOTP input. Then call `/auth/2fa/verify` with the TOTP code.

```typescript
// auth.service.ts — extend login() to handle 2FA
interface TwoFactorChallenge {
  requiresTwoFactor: true;
  tempToken: string;
  available2faMethods: string[];
}

login(email: string, password: string): Observable<AuthUser | TwoFactorChallenge> {
  return this.http
    .post<{ requiresTwoFactor?: boolean; tempToken?: string; available2faMethods?: string[] }>(
      '/auth/login', { email, password }, { withCredentials: true },
    )
    .pipe(
      switchMap((res) => {
        if (res.requiresTwoFactor) {
          return of(res as TwoFactorChallenge);
        }
        // Cookies set by awesome-node-auth — fetch the user profile
        return this.fetchCurrentUser();
      }),
    );
}

verify2FA(tempToken: string, totpCode: string): Observable<AuthUser> {
  return this.http
    .post<void>('/auth/2fa/verify', { tempToken, totpCode }, { withCredentials: true })
    .pipe(switchMap(() => this.fetchCurrentUser()));
}
```

---

### Summary: what each piece does

| File | Role |
|------|------|
| `auth.service.ts` | Single source of truth for user state; no token storage — cookies are managed by the browser |
| `auth.interceptor.ts` | Adds `X-CSRF-Token` header to state-changing requests; handles 401 with a refresh queue |
| `auth.guard.ts` | `authGuard` (login required), `guestGuard` (redirect if logged in), `roleGuard(role)` (RBAC), `authCanMatch` (lazy modules) |
| `auth.initializer.ts` | `APP_INITIALIZER` — silent refresh on page reload |
| `ssr-cookie.interceptor.ts` | SSR only: forwards the browser's `Cookie` header to the API server |
| `app.config.ts` | Registers `provideHttpClient(withFetch(), withInterceptors([...]))` |
| `app.config.server.ts` | Adds `provideServerRendering()` and the SSR cookie interceptor |
| `server.ts` | Express wrapper — injects `REQUEST`/`RESPONSE` tokens so the SSR interceptor can read cookies |

:::tip SSR and absolute URLs
When Angular runs on the server it uses Node.js `fetch` which cannot resolve relative paths like `/auth/login`. Configure a base URL in the server config:
```typescript
// app.config.server.ts — add to providers:
{ provide: 'BASE_URL', useValue: 'http://localhost:4000' }
```
Then prefix all API calls in `AuthService` with this token when `isPlatformServer()` is true.
:::

---

## Angular Auth Library: @awesome-lang-auth/angular

## Angular Integration — `@awesome-lang-auth/angular`

`@awesome-lang-auth/angular` is the official Angular library for frontends backed by `awesome-node-auth`. It provides Guards, Interceptors, reactive session signals, CSRF support, and optional UI theme synchronization — all tree-shakable and SSR-safe.

:::info Why not use auth.js?
`auth.js` (the built-in browser client) uses plain `fetch()` intercept and global `window` APIs that are not compatible with Angular's `HttpClient` pipeline, zone.js change detection, or SSR hydration. Use `@awesome-lang-auth/angular` instead.
:::

---

### Installation

```bash
npm install @awesome-lang-auth/angular
```

:::note Formerly ng-awesome-node-auth
The library was formerly published as `ng-awesome-node-auth`, now deprecated on npm: its last release, 1.10.0, only re-exports `@awesome-lang-auth/angular`. To migrate, install the new package and change the import specifier. The source lives in [awesome-lang-auth/awesome-angular-auth](https://github.com/awesome-lang-auth/awesome-angular-auth).
:::

---

### Quick start

#### 1 — Configure providers (`app.config.ts`)

```typescript
import { ApplicationConfig } from '@angular/core';
import { provideRouter } from '@angular/router';
import { provideHttpClient, withInterceptors, withFetch } from '@angular/common/http';
import { provideAuth, provideAuthUi } from '@awesome-lang-auth/angular';
import { routes } from './app.routes';

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes),
    provideHttpClient(withFetch()),

    // Core auth — adds session management, HTTP interceptor, and CSRF support
    provideAuth({ apiPrefix: '/api/auth' }),

    // Optional — fetches backend feature flags and keeps CSS theme in sync with the admin panel
    provideAuthUi(),
  ],
};
```

#### 2 — Protect routes (`app.routes.ts`)

```typescript
import { Routes } from '@angular/router';
import { authGuard, guestGuard } from '@awesome-lang-auth/angular';

export const routes: Routes = [
  {
    path: 'login',
    loadComponent: () => import('./pages/login/login.component').then(m => m.LoginComponent),
    canActivate: [guestGuard],  // redirect to /dashboard if already authenticated
  },
  {
    path: 'dashboard',
    loadComponent: () => import('./pages/dashboard/dashboard.component').then(m => m.DashboardComponent),
    canActivate: [authGuard],   // redirect to /login if not authenticated
  },
  { path: '', redirectTo: '/dashboard', pathMatch: 'full' },
];
```

#### 3 — Use session signals in components

```typescript
import { Component, inject } from '@angular/core';
import { AuthService } from '@awesome-lang-auth/angular';

@Component({
  selector: 'app-dashboard',
  template: `
    <div *ngIf="auth.isAuthenticated()">
      <p>Welcome, {{ auth.user()?.email }}!</p>
      <button (click)="logout()">Logout</button>
    </div>
  `,
})
export class DashboardComponent {
  auth = inject(AuthService);

  logout() {
    this.auth.logout().subscribe();
  }
}
```

---

### `provideAuth(config)` options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `apiPrefix` | `string` | `'/auth'` | Base URL of the `awesome-node-auth` REST API |

#### What `provideAuth()` does

1. Registers `AuthService` (session signals, login/logout/refresh)
2. Injects the **HTTP interceptor** that:
   - Reads `__Host-csrf-token` → `__Secure-csrf-token` → `csrf-token` in order (cookie-tossing protection)
   - Adds `X-CSRF-Token` header to every `POST` / `PUT` / `PATCH` / `DELETE` request
   - Queues concurrent 401 responses behind a single token-refresh attempt
   - Calls `auth.logout()` when refresh fails

---

### `AuthService` API

```typescript
// Injected via inject(AuthService) or constructor injection

// ── Reactive signals ────────────────────────────────────────────────────
user(): AuthUser | null           // current user or null
isAuthenticated(): boolean        // true when user is logged in
isInitialized(): boolean          // true after the first checkSession() completes

// ── Methods ─────────────────────────────────────────────────────────────
checkSession(): Observable<AuthUser | null>   // GET /auth/me — restores session on page reload
login(email, password): Observable<LoginResult>
logout(): Observable<void>
refreshToken(): Observable<void>   // POST /auth/refresh — usually called automatically by interceptor

// Returned by login() when 2FA is required
interface LoginResult {
  success: boolean;
  requires2fa?: boolean;
  tempToken?: string;
  availableMethods?: string[];
  error?: string;
}
```

#### Session restore on app startup (`APP_INITIALIZER`)

```typescript
import { APP_INITIALIZER, inject } from '@angular/core';
import { AuthService } from '@awesome-lang-auth/angular';
import { firstValueFrom, of } from 'rxjs';
import { catchError } from 'rxjs/operators';

export const authInitializer = {
  provide: APP_INITIALIZER,
  useFactory: () => {
    const auth = inject(AuthService);
    return () => firstValueFrom(auth.checkSession().pipe(catchError(() => of(null))));
  },
  multi: true,
};
```

---

### Guards

| Guard | Behaviour |
|-------|-----------|
| `authGuard` | Redirect to `/login` if not authenticated |
| `guestGuard` | Redirect to `/dashboard` if already authenticated |

Both guards call `checkSession()` if the session has not been initialized yet.

---

### CSRF protection

The built-in interceptor reads the CSRF token **in priority order** to guard against cookie-tossing attacks:

```
__Host-csrf-token  (most secure — requires Secure + Path=/ + no Domain)
__Secure-csrf-token
csrf-token         (plain — development / non-HTTPS)
```

This matches the prefix selection logic in `awesome-node-auth`'s `TokenService`, which applies `__Host-` automatically when `cookieOptions.secure: true` (default in production).

No manual CSRF setup is needed. Enable it on the server:

```typescript
const authConfig: AuthConfig = {
  csrf: { enabled: true },
  cookieOptions: { secure: process.env.NODE_ENV === 'production' },
};
```

---

### `provideAuthUi()` — Theme synchronization

When included, `provideAuthUi()` registers `UiConfigService`, which:

1. Fetches `GET /auth/ui/config` on startup to retrieve backend feature flags and theme
2. Syncs CSS variables (primary colour, background, etc.) with the running Angular app in real time — useful when the admin panel changes the theme

#### Feature flags

```typescript
import { inject } from '@angular/core';
import { UiConfigService } from '@awesome-lang-auth/angular';

@Component({ /* … */ })
export class NavComponent {
  uiConfig = inject(UiConfigService);

  // Feature flags mirror what awesome-node-auth has configured on the backend
  showRegister    = this.uiConfig.hasFeature('register');
  showMagicLink   = this.uiConfig.hasFeature('magicLink');
  showForgotPw    = this.uiConfig.hasFeature('forgotPassword');
  showGoogleLogin = this.uiConfig.hasFeature('google');
  showGithubLogin = this.uiConfig.hasFeature('github');
  show2FA         = this.uiConfig.hasFeature('twoFactor');
}
```

---

### Full example — login component

```typescript
// src/app/pages/login/login.component.ts
import { Component, inject, signal } from '@angular/core';
import { Router } from '@angular/router';
import { FormsModule } from '@angular/forms';
import { AuthService } from '@awesome-lang-auth/angular';

@Component({
  selector: 'app-login',
  standalone: true,
  imports: [FormsModule],
  template: `
    <form (ngSubmit)="submit()">
      <input type="email"    [(ngModel)]="email"    name="email"    required />
      <input type="password" [(ngModel)]="password" name="password" required />
      <button type="submit" [disabled]="loading()">Login</button>
      <p *ngIf="error()">{{ error() }}</p>
    </form>

    <!-- 2FA challenge -->
    <div *ngIf="requires2fa()">
      <input type="text" [(ngModel)]="otpCode" placeholder="Enter OTP" />
      <button (click)="submit2fa()">Confirm</button>
    </div>
  `,
})
export class LoginComponent {
  private auth   = inject(AuthService);
  private router = inject(Router);

  email    = '';
  password = '';
  otpCode  = '';

  loading    = signal(false);
  error      = signal<string | null>(null);
  requires2fa = signal(false);
  tempToken  = signal<string | null>(null);

  submit() {
    this.loading.set(true);
    this.error.set(null);

    this.auth.login(this.email, this.password).subscribe({
      next: (result) => {
        this.loading.set(false);
        if (result.requires2fa) {
          this.requires2fa.set(true);
          this.tempToken.set(result.tempToken ?? null);
        } else if (result.success) {
          this.router.navigate(['/dashboard']);
        } else {
          this.error.set(result.error ?? 'Login failed');
        }
      },
      error: () => {
        this.loading.set(false);
        this.error.set('An unexpected error occurred');
      },
    });
  }

  submit2fa() {
    // POST /auth/2fa/totp/validate { tempToken, code }
    // handled by your own HTTP call or a future AuthService method
  }
}
```

---

### SSR wiring

`@awesome-lang-auth/angular` is SSR-safe. The `AuthService` and `UiConfigService` use Angular's `isPlatformBrowser` checks internally to avoid calling browser-only APIs during server-side rendering.

For SSR apps, forward the browser's cookies to the API server in `app.config.server.ts`:

```typescript
// src/app/auth/ssr-cookie.interceptor.ts
import { inject, PLATFORM_ID } from '@angular/core';
import { isPlatformServer } from '@angular/common';
import { HttpInterceptorFn } from '@angular/common/http';
import { REQUEST } from '@angular/core';

export const ssrCookieInterceptor: HttpInterceptorFn = (req, next) => {
  const platformId = inject(PLATFORM_ID);
  if (!isPlatformServer(platformId)) return next(req);

  const request = inject(REQUEST, { optional: true });
  const cookies  = request?.headers?.get('cookie') ?? '';
  if (!cookies) return next(req);

  return next(req.clone({ setHeaders: { Cookie: cookies } }));
};
```

```typescript
// src/app/app.config.server.ts
import { mergeApplicationConfig, ApplicationConfig } from '@angular/core';
import { provideServerRendering } from '@angular/platform-server';
import { provideServerRoutesConfig } from '@angular/ssr';
import { provideHttpClient, withInterceptors, withFetch } from '@angular/common/http';
import { ssrCookieInterceptor } from './auth/ssr-cookie.interceptor';
import { appConfig } from './app.config';

const serverConfig: ApplicationConfig = {
  providers: [
    provideServerRendering(),
    provideServerRoutesConfig(serverRoutes),
    // Use withInterceptors (functional interceptors — same style as provideAuth())
    provideHttpClient(withFetch(), withInterceptors([ssrCookieInterceptor])),
  ],
};

export const config = mergeApplicationConfig(appConfig, serverConfig);
```

---

### Breaking SSR routing loops

When Angular SSR handles all routes, an unauthenticated hit to `/dashboard` triggers a guard redirect to `/login`. If `/login` is also an Angular route, this can cause redirect loops.

**Solution:** intercept auth paths in the Express server before the Angular engine:

```typescript
// server.ts
const authPages = ['login', 'register', 'forgot-password', 'reset-password', '2fa', 'verify-email'];

authPages.forEach(page => {
  // Redirect Angular routes to the backend-served UI pages
  app.get(`/${page}`, (req, res) => {
    const qs = req.url.includes('?') ? '?' + req.url.split('?')[1] : '';
    res.redirect(`/api/auth/ui/${page}${qs}`);
  });
});
```

> Alternatively, remove those paths from Angular's routes entirely and let `awesome-node-auth`'s built-in UI handle them.

---

### Preventing Angular build hangs

When `ng build` imports your server module for route extraction, your `app.listen()` call would hang the build. Fix:

```typescript
import { isMainModule } from '@angular/ssr/node';

if (isMainModule(import.meta.url)) {
  const port = process.env['PORT'] ?? 4200;
  app.listen(port, () => console.log(`Listening on http://localhost:${port}`));
}
```

---

### Full-stack wiring — reference architecture

```
Browser / SSR
 └─ Angular App
     ├─ provideAuth({ apiPrefix: '/api/auth' })  ← @awesome-lang-auth/angular
     ├─ authGuard / guestGuard
     └─ AuthService.user() / isAuthenticated()

Express Server
 ├─ GET /api/auth/*   ← awesome-node-auth REST API
 ├─ GET /api/auth/ui/*← awesome-node-auth Built-in UI (optional)
 ├─ GET /admin/auth/* ← awesome-node-auth Admin Panel (optional)
 └─ **               ← Angular SSR engine
```

---

### Links

- **npm**: [`@awesome-lang-auth/angular`](https://www.npmjs.com/package/@awesome-lang-auth/angular)
- **GitHub**: [awesome-lang-auth/awesome-angular-auth](https://github.com/awesome-lang-auth/awesome-angular-auth)
- **Backend docs**: [Built-in UI guide](/docs/advanced/built-in-ui) · [Browser Client](/docs/advanced/browser-client)
- **Manual Angular wiring** (without the library): [Angular (manual)](/docs/frameworks/angular)

---

## React Authentication Library: @awesome-lang-auth/react

## React Integration — `@awesome-lang-auth/react`

:::tip Official React library
**For React apps, use [`@awesome-lang-auth/react`](https://www.npmjs.com/package/@awesome-lang-auth/react)**: one provider, one hook, two route gates, and a small typed client that speaks the awesome-node-auth wire protocol directly. Version **0.1.0** is its first release.
:::

The package depends on none of the backends, only on `react`. It is written for the protocol the family's backends serve: awesome-node-auth, awesome-go-auth, awesome-lambda-auth, and the Python, Rust and Dart ports.

- **Cookie on the web, bearer on React Native.** The transport is picked for you and can be overridden.
- **No global patching.** The served `auth.js` replaces `window.fetch`; this package never does. App calls that need the session go through `client.fetch`.
- **React 18 and 19.** State is read with `useSyncExternalStore`.
- **SSR-safe.** Server renders see `isLoading: true`, and the entry carries `'use client'` for the Next.js App Router.
- **Router-agnostic gates.** `<ProtectedRoute>` and `<AnonymousOnly>` render; you decide how to navigate.

---

### Installation

```bash
npm install @awesome-lang-auth/react
```

Peer dependency: `react` 18 or later (`react-dom` is optional, so React Native works too).

---

### Provider and hooks

Put one `AwesomeAuthProvider` at the root. `apiPrefix` is where the backend mounts its auth router: `/auth` by default, or an absolute URL such as `https://api.example.com/auth` when the backend is on another origin.

```tsx
import { useState } from 'react';
import { AwesomeAuthProvider, ProtectedRoute, AnonymousOnly, useAwesomeAuth } from '@awesome-lang-auth/react';

// One provider at the root; each page picks its gate.
export function App() {
  return (
    <AwesomeAuthProvider options={{ apiPrefix: '/auth' }}>
      {location.pathname === '/login' ? (
        <AnonymousOnly redirectTo="/">
          <LoginForm />
        </AnonymousOnly>
      ) : (
        <ProtectedRoute fallback={<Spinner />} redirectTo="/login">
          <Dashboard />
        </ProtectedRoute>
      )}
    </AwesomeAuthProvider>
  );
}

function LoginForm() {
  const { login } = useAwesomeAuth();
  const [step, setStep] = useState<{ tempToken: string } | null>(null);

  async function onSubmit(email: string, password: string) {
    const r = await login(email, password);
    if (r.requires2fa) setStep({ tempToken: r.tempToken! }); // then client.validate2fa(tempToken, code)
    else if (!r.success) alert(r.error);
  }
  // ...
}

function Dashboard() {
  const { user, logout } = useAwesomeAuth();
  return <button onClick={logout}>Sign out {user?.email}</button>;
}
```

| Export | What it gives you |
|--------|-------------------|
| `AwesomeAuthProvider` | The context. Pass `options` (an `apiPrefix`, a `mode`, a `storage`) or a `client` you created yourself |
| `useAwesomeAuth()` | `user`, `isAuthenticated`, `isLoading`, `error`, the actions `login`, `logout`, `refresh`, `checkSession`, and the `client` |
| `useAuthUser()` | Only the user, or `null`. Type your own claims with `useAuthUser<MyUser>()` |
| `useAuthClient()` | The underlying `AwesomeAuthClient` |
| `ProtectedRoute` | Renders its children for a signed-in user; optional `fallback`, `role`, `forbidden`, `redirectTo`, `onUnauthenticated` |
| `AnonymousOnly` | Renders its children for a signed-out visitor; optional `fallback`, `redirectTo`, `onAuthenticated` |

**The user** is the `GET /me` payload. Its id is `sub`, not `id`.

**Login with a second factor.** When the account has 2FA, `login` resolves to `{ success: true, requires2fa: true, tempToken, availableMethods }` and the user stays signed out. Complete it with `validate2fa(tempToken, code)` (TOTP), `send2faSms` + `validateSms`, or `send2faMagicLink`.

**React Router and Next.js.** Pass `onUnauthenticated={() => navigate('/login', { replace: true })}` to drive your router. With the Next.js App Router you can render the provider from the root layout; Server Components import `hasRole`, `SERVER_SNAPSHOT` and the types from `@awesome-lang-auth/react/server`, which has no client boundary.

---

### The client

`AwesomeAuthClient` is framework-free. Create one yourself to share it with non-React code, then hand it to the provider:

```ts
import { AwesomeAuthClient } from '@awesome-lang-auth/react';

export const auth = new AwesomeAuthClient({ apiPrefix: 'https://api.example.com/auth' });

// Authenticated app calls: credentials attached, one refresh-and-retry on 401/403.
const res = await auth.fetch('https://api.example.com/orders');

auth.on('sessionExpired', () => router.navigate('/login'));
```

```tsx
<AwesomeAuthProvider client={auth}>...</AwesomeAuthProvider>
```

Every action method resolves to `{ success, error?, code? }` (plus its payload) and never rejects on an HTTP error. The exceptions are `checkSession()`, which resolves to the user or `null`, `fetch()`, which resolves to a `Response`, and `oauthUrl()`, which returns a string. The client covers sessions, login and registration, passwords, magic link, SMS, TOTP 2FA, email verification and change, account linking and account deletion.

---

### Cookie or bearer

| | `cookie` (web default) | `bearer` (React Native default) |
| --- | --- | --- |
| Tokens | HttpOnly cookies set by the backend | JSON body, kept in a `TokenStorage` |
| Requests | `credentials: 'include'` + `X-CSRF-Token` from the CSRF cookie | `X-Auth-Strategy: bearer` + `Authorization: Bearer` |
| Refresh | `POST /refresh` (cookie) | `POST /refresh` with `{ refreshToken }` |

Credentials, CSRF tokens and bearer tokens are attached **only to requests for the backend's origin**; a `client.fetch` to any other origin goes out untouched. Override the default with `mode`:

```ts
new AwesomeAuthClient({ apiPrefix: 'https://api.example.com/auth', mode: 'bearer', storage });
```

Bearer tokens live in memory by default, so the session ends when the app does. To persist them on React Native, pass a `storage` with `load`, `save` and `clear` (sync or async). On React Native, `apiPrefix` must be an absolute URL.

**Cross-origin setups.**

- **Cookie mode, backend on another site.** The CSRF cookie belongs to the backend host, so the page cannot read it and send it back. Serve both from one parent domain, or disable CSRF.
- **Bearer mode in a browser, backend on another origin.** The CORS preflight must allow the `X-Auth-Strategy` header. awesome-node-auth allows it when you configure `cors.origins`; the awesome-lambda-auth allow-list does not include it at the time of writing, so there use cookie mode from one origin. React Native has no CORS and is unaffected.

---

### Links

- **npm**: [`@awesome-lang-auth/react`](https://www.npmjs.com/package/@awesome-lang-auth/react)
- **GitHub**: [awesome-lang-auth/awesome-react-auth](https://github.com/awesome-lang-auth/awesome-react-auth)

### Related

- [Angular auth library](/docs/frameworks/ng-awesome-node-auth) — the Angular client for the same protocol
- [Browser client (`auth.js`)](/docs/advanced/browser-client) — the served script this package does not patch into `fetch`
- [Bearer token mode for mobile apps](/docs/advanced/bearer-token) — the transport React Native uses
- [Framework integrations](/docs/frameworks) — every supported backend and client

---

## Python FastAPI Authentication: awesome-python-auth

## Python Integration — `awesome-python-auth`

:::tip Official Python library
**For Python backends, use [`awesome-python-auth`](https://pypi.org/project/awesome-python-auth/)** — the official FastAPI library that brings the same auth model as `awesome-node-auth` to Python. Its [parity audit](https://github.com/awesome-lang-auth/awesome-python-auth/issues/10) tracks the details.

It provides:
- All the same auth flows: local, OAuth, magic link, SMS OTP, TOTP 2FA
- Cookie + CSRF support for Angular and Flutter web clients
- Bearer token support for Flutter native / mobile
- `AuthEventBus`, `AuthTools`, SSE, webhooks, telemetry
- IdP mode (RS256/JWKS) and Resource Server validation
- RBAC, multi-tenancy, API keys, admin router, bundled UI
:::

---

### Installation

```bash
pip install awesome-python-auth
```

**Requirements:** Python ≥ 3.11, FastAPI ≥ 0.115.0

---

### Quickstart

```python
import os
from fastapi import FastAPI, Depends
from fastapi.middleware.cors import CORSMiddleware
from awesome_python_auth import (
    AuthConfig, AuthConfigurator, CsrfMiddleware, require_auth,
)
from awesome_python_auth.models import AuthUser, InMemoryUserStore

user_store = InMemoryUserStore()

config = AuthConfig(
    api_prefix="/api/auth",
    access_token_secret=os.environ["JWT_SECRET"],
    cookie_secure=False,  # True in production (HTTPS)
)

app = FastAPI()

app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:4200"],  # your frontend
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*", "X-CSRF-Token", "X-Auth-Strategy"],
)
app.add_middleware(CsrfMiddleware, api_prefix="/api/auth", cookie_secure=False)

configurator = AuthConfigurator(config, user_store)
app.include_router(configurator.router())

@app.get("/api/todos")
async def todos(user: AuthUser = Depends(require_auth)):
    return {"todos": [], "user": user.email}
```

Run with:

```bash
uvicorn main:app --reload
```

---

### Configuration — `AuthConfig`

All options are keyword arguments to the `AuthConfig` dataclass:

```python
from awesome_python_auth import AuthConfig

config = AuthConfig(
    # ── Core ──────────────────────────────────────────────────────────────────
    api_prefix="/api/auth",             # Must match the client's apiPrefix
    access_token_secret="...",          # JWT signing secret (HS256)
    access_token_expires_in=900,        # Seconds — default 15 min
    refresh_token_expires_in=604800,    # Seconds — default 7 days

    # ── Cookies ───────────────────────────────────────────────────────────────
    cookie_secure=True,                 # False for local HTTP dev only
    cookie_same_site="lax",             # "lax" | "strict" | "none"
    cookie_domain=None,                 # Set for subdomain sharing
    cookie_prefix=None,                 # "__Host-" | "__Secure-" | None

    # ── Features ──────────────────────────────────────────────────────────────
    totp_issuer="My App",               # Shown in authenticator apps
    ui_config=None,                     # Dict returned by GET /api/auth/ui/config
    session_check_on="none",            # "none" | "refresh" | "allcalls"

    # ── Email hooks (implement at least one for email-based features) ──────────
    on_forgot_password=None,            # async (user, token) -> None
    on_send_verification_email=None,    # async (user, token) -> None
    on_request_email_change=None,       # async (user, new_email, token) -> None
    on_magic_link_send=None,            # async (email, temp_token, mode) -> None
    on_magic_link_verify=None,          # async (token, mode) -> user_id | None

    # ── SMS hooks ─────────────────────────────────────────────────────────────
    on_sms_send=None,                   # async (email, temp_token, mode) -> None
    on_sms_verify=None,                 # async (user_id, temp_token, code, mode) -> user_id | None

    # ── OAuth hooks ───────────────────────────────────────────────────────────
    on_oauth_start=None,                # async (provider, request) -> redirect_url
    on_oauth_callback=None,             # async (provider, request) -> user_id | dict | StoredUser | None

    # ── Account linking hooks ─────────────────────────────────────────────────
    on_link_request=None,               # async (email, provider, current_user) -> None
    on_link_verify=None,                # async (token, provider, login_after_linking) -> user_id | None

    # ── Registration hook ─────────────────────────────────────────────────────
    on_register=None,                   # async (stored_user) -> StoredUser | None

    # ── Plugin instances (see dedicated sections below) ───────────────────────
    mailer=None,                        # MailerConfig
    tools=None,                         # AuthTools
    api_key_store=None,                 # ApiKeyStore
    roles_permissions_store=None,       # RolesPermissionsStore
    tenant_store=None,                  # TenantStore
    id_provider=None,                   # IdProviderConfig
    resource_server=None,               # ResourceServerConfig
)
```

---

### User Store

Implement `UserStore` to connect your database. All auth endpoints delegate user lookup and persistence to this store.

#### Abstract interface

```python
from awesome_python_auth.models import UserStore, StoredUser, StoredSession
from abc import abstractmethod

class MyUserStore(UserStore):
    # ── Required ──────────────────────────────────────────────────────────────
    async def get_by_email(self, email: str) -> StoredUser | None: ...
    async def get_by_id(self, user_id: str) -> StoredUser | None: ...
    async def create(self, user: StoredUser) -> StoredUser: ...
    async def update(self, user: StoredUser) -> StoredUser: ...
    async def delete(self, user_id: str) -> None: ...

    # ── Sessions (optional — enables device-aware session management) ─────────
    async def create_session(self, session: StoredSession) -> StoredSession: ...
    async def get_sessions_for_user(self, user_id: str) -> list[StoredSession]: ...
    async def get_session_by_handle(self, handle: str) -> StoredSession | None: ...
    async def update_session(self, session: StoredSession) -> None: ...
    async def delete_session(self, handle: str) -> None: ...
    async def delete_sessions_for_user(self, user_id: str) -> None: ...

    # ── Admin (optional — enables user listing in admin panel) ────────────────
    async def list_all_users(self, offset: int = 0, limit: int = 50) -> list[StoredUser]: ...
    async def count_users(self) -> int: ...
    async def list_all_sessions(self, offset: int = 0, limit: int = 50) -> list[StoredSession]: ...
    async def count_active_sessions(self) -> int: ...

    # ── Token finders (optional — enables specific endpoints) ─────────────────
    async def find_by_reset_token(self, token_hash: str) -> StoredUser | None: ...
    async def find_by_verification_token(self, token_hash: str) -> StoredUser | None: ...
    async def find_by_pending_email_token(self, token_hash: str) -> StoredUser | None: ...
```

#### Built-in in-memory store (for development / testing)

```python
from awesome_python_auth.models import InMemoryUserStore

user_store = InMemoryUserStore()
```

#### `StoredUser` fields

| Field | Type | Description |
|-------|------|-------------|
| `id` | `str \| None` | Database ID |
| `email` | `str` | Email address |
| `hashed_password` | `str \| None` | bcrypt hash |
| `first_name` | `str \| None` | First name |
| `last_name` | `str \| None` | Last name |
| `is_email_verified` | `bool` | Email verification status |
| `is_totp_enabled` | `bool` | TOTP 2FA enabled |
| `totp_secret` | `str \| None` | TOTP secret |
| `phone_number` | `str \| None` | Phone number |
| `role` | `str \| None` | Primary role string |
| `roles` | `list[str] \| None` | Role list |
| `permissions` | `list[str] \| None` | Permission list |
| `is_admin` | `bool \| None` | Admin flag |
| `tenant_id` | `str \| None` | Multi-tenancy tenant ID |
| `metadata` | `dict \| None` | Arbitrary key-value metadata |

---

### FastAPI Dependency Functions

Use these as `Depends(...)` in your route functions:

```python
from awesome_python_auth import get_current_user, require_auth, require_roles, require_admin
from awesome_python_auth.models import AuthUser
from fastapi import Depends

# Optional auth — returns None if unauthenticated
@app.get("/public-or-private")
async def example(user: AuthUser | None = Depends(get_current_user)):
    if user:
        return {"hello": user.email}
    return {"hello": "anonymous"}

# Required auth — raises HTTP 401 if unauthenticated
@app.get("/private")
async def private(user: AuthUser = Depends(require_auth)):
    return {"user": user.email}

# Role-based access — raises HTTP 403 if user lacks all listed roles
@app.get("/admin-area")
async def admin_area(user: AuthUser = Depends(require_roles(["admin"]))):
    return {"user": user.email}

# Admin flag — raises HTTP 403 if user.is_admin is not True
@app.get("/super-admin")
async def super_admin(user: AuthUser = Depends(require_admin())):
    return {"admin": True}
```

Token extraction priority: `Authorization: Bearer` header → `access-token` HttpOnly cookie.

---

### CSRF Middleware

Required for **Angular and Flutter web** clients that use the cookie-based auth mode:

```python
from awesome_python_auth import CsrfMiddleware

app.add_middleware(
    CsrfMiddleware,
    api_prefix="/api/auth",     # Must match AuthConfig.api_prefix
    cookie_secure=True,         # False for local HTTP dev only
    cookie_same_site="lax",
)
```

The middleware:
- Sets a `csrf-token` cookie on every response
- Validates the `X-CSRF-Token` request header on all mutating requests (`POST`, `PATCH`, `PUT`, `DELETE`) to endpoints under `api_prefix`

---

### API Endpoints

All endpoints are mounted under `api_prefix` (default `/api/auth`):

#### Account

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| `POST` | `/login` | ❌ | Login with email + password |
| `POST` | `/register` | ❌ | Create a new account |
| `POST` | `/logout` | ✅ | Logout and clear session |
| `POST` | `/refresh` | ❌ | Refresh the access token |
| `GET` | `/me` | ✅ | Return current user |
| `PATCH` | `/profile` | ✅ | Update first/last name |
| `DELETE` | `/account` | ✅ | Delete own account |

#### Password

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/forgot-password` | Request password reset email |
| `POST` | `/reset-password` | Reset password with token |
| `POST` | `/change-password` | Change password (authenticated) |
| `POST` | `/send-verification-email` | Resend verification email |
| `GET` | `/verify-email?token=` | Confirm email address |
| `POST` | `/change-email/request` | Request email change |
| `POST` | `/change-email/confirm` | Confirm email change |

#### TOTP 2FA

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/2fa/setup` | Begin TOTP setup — returns QR + secret |
| `POST` | `/2fa/verify-setup` | Confirm TOTP setup with code |
| `POST` | `/2fa/verify` | Verify TOTP code during login |
| `POST` | `/2fa/disable` | Disable TOTP |

#### Magic Link

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/magic-link/send` | Send magic-link email |
| `POST` | `/magic-link/verify` | Verify magic-link token |

#### SMS / OTP

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/sms/send` | Send SMS OTP |
| `POST` | `/sms/verify` | Verify SMS OTP |
| `POST` | `/add-phone` | Add phone number to account |

#### Sessions

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/sessions` | List all active sessions |
| `DELETE` | `/sessions/{handle}` | Revoke a specific session |

#### OAuth

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/oauth/{provider}` | Start provider OAuth flow |
| `GET` | `/oauth/{provider}/callback` | Complete OAuth callback |

#### Account Linking

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/link-request` | Initiate account linking by email |
| `POST` | `/link-verify` | Verify linking token |
| `GET` | `/linked-accounts` | List linked OAuth providers |
| `DELETE` | `/linked-accounts/{provider}/{id}` | Unlink a provider |

#### Utilities

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/ui/config` | UI feature flags and theme config |
| `GET` | `/tools/stream` | Server-Sent Events stream |

---

### Bearer Token Mode (Flutter native / mobile)

For Flutter native clients (iOS, Android, Desktop), the package sends `X-Auth-Strategy: bearer`. Your server automatically detects this header and returns tokens in the JSON body instead of cookies:

```json
{
  "accessToken": "eyJ...",
  "refreshToken": "eyJ..."
}
```

No extra server configuration is needed — the detection is automatic. Ensure `X-Auth-Strategy` is listed in your CORS `allow_headers`.

---

### Email Hooks

Implement the hooks you need and pass them to `AuthConfig`:

```python
async def send_forgot_password(user, token: str):
    reset_url = f"https://myapp.com/reset-password?token={token}"
    await mailer.send(to=user.email, subject="Password reset", body=reset_url)

async def send_verification_email(user, token: str):
    verify_url = f"https://myapp.com/verify-email?token={token}"
    await mailer.send(to=user.email, subject="Verify your email", body=verify_url)

async def send_magic_link(email: str, temp_token: str, mode: str):
    link_url = f"https://myapp.com/magic-link?token={temp_token}&mode={mode}"
    await mailer.send(to=email, subject="Your magic link", body=link_url)

async def verify_magic_link(token: str, mode: str) -> str | None:
    # Look up the token in your store; return user_id or None
    user = await user_store.find_by_magic_token(token)
    return user.id if user else None

config = AuthConfig(
    on_forgot_password=send_forgot_password,
    on_send_verification_email=send_verification_email,
    on_magic_link_send=send_magic_link,
    on_magic_link_verify=verify_magic_link,
)
```

---

### SMS Hooks

```python
async def send_sms(email: str, temp_token: str, mode: str):
    user = await user_store.get_by_email(email)
    otp = generate_otp()
    await store_otp(user.id, otp, temp_token)
    await sms_client.send(to=user.phone_number, body=f"Your code: {otp}")

async def verify_sms(user_id: str, temp_token: str, code: str, mode: str) -> str | None:
    if await validate_otp(user_id, temp_token, code):
        return user_id
    return None

config = AuthConfig(
    on_sms_send=send_sms,
    on_sms_verify=verify_sms,
)
```

---

### OAuth Hooks

```python
from starlette.requests import Request

async def oauth_start(provider: str, request: Request) -> str:
    # Build and return the OAuth redirect URL for the given provider
    return f"https://{provider}.com/oauth/authorize?client_id=...&redirect_uri=..."

async def oauth_callback(provider: str, request: Request):
    # Exchange the code, find or create the user, return user_id
    code = request.query_params.get("code")
    # ... exchange with provider ...
    user = await user_store.get_by_email(profile_email)
    if not user:
        user = await user_store.create(StoredUser(email=profile_email, ...))
    return user.id

config = AuthConfig(
    on_oauth_start=oauth_start,
    on_oauth_callback=oauth_callback,
)
```

---

### `AuthEventBus`

Subscribe to auth lifecycle events anywhere in your app:

```python
from awesome_python_auth import AuthEventBus, AuthEventNames

bus = AuthEventBus()

# Sync or async handlers are both supported
async def on_login(payload: dict):
    print(f"User logged in: {payload['userId']}")

bus.on_event(AuthEventNames.AUTH_LOGIN_SUCCESS, on_login)
bus.on_event("*", lambda p: print("Event:", p))  # wildcard — receives ALL events

# Unsubscribe
bus.off_event(AuthEventNames.AUTH_LOGIN_SUCCESS, on_login)

# Publish manually
bus.publish(AuthEventNames.USER_CREATED, {"userId": "u1"})
```

Pass `bus` to `AuthTools` so the tools layer can publish events automatically.

#### Event names reference

| Constant | Event string |
|----------|-------------|
| `AUTH_LOGIN_SUCCESS` | `identity.auth.login.success` |
| `AUTH_LOGIN_FAILED` | `identity.auth.login.failed` |
| `AUTH_LOGOUT` | `identity.auth.logout` |
| `AUTH_OAUTH_SUCCESS` | `identity.auth.oauth.success` |
| `AUTH_OAUTH_CONFLICT` | `identity.auth.oauth.conflict` |
| `USER_CREATED` | `identity.user.created` |
| `USER_DELETED` | `identity.user.deleted` |
| `USER_EMAIL_VERIFIED` | `identity.user.email.verified` |
| `USER_PASSWORD_CHANGED` | `identity.user.password.changed` |
| `USER_2FA_ENABLED` | `identity.user.2fa.enabled` |
| `USER_2FA_DISABLED` | `identity.user.2fa.disabled` |
| `USER_LINKED` | `identity.user.linked` |
| `USER_UNLINKED` | `identity.user.unlinked` |
| `SESSION_CREATED` | `identity.session.created` |
| `SESSION_REVOKED` | `identity.session.revoked` |
| `SESSION_EXPIRED` | `identity.session.expired` |
| `SESSION_ROTATED` | `identity.session.rotated` |
| `ROLE_ASSIGNED` | `identity.role.assigned` |
| `ROLE_REVOKED` | `identity.role.revoked` |
| `PERMISSION_GRANTED` | `identity.permission.granted` |
| `PERMISSION_REVOKED` | `identity.permission.revoked` |
| `TENANT_CREATED` | `identity.tenant.created` |
| `TENANT_DELETED` | `identity.tenant.deleted` |
| `TENANT_USER_ADDED` | `identity.tenant.user.added` |
| `TENANT_USER_REMOVED` | `identity.tenant.user.removed` |

---

### `AuthTools` — Multi-Channel Notifications

`AuthTools` wraps SSE, email, and SMS into a single `notify()` call and integrates with `AuthEventBus` for automatic telemetry:

```python
from awesome_python_auth import AuthTools, SseManager
from awesome_python_auth.mailer import MailerConfig
from awesome_python_auth.notification import SmsConfig

sse = SseManager()

tools = AuthTools(
    sse=sse,
    email_config=MailerConfig(
        endpoint="https://mailer.example.com/send",
        api_key=os.environ["MAILER_API_KEY"],
        from_address="no-reply@example.com",
    ),
    sms_config=SmsConfig(
        endpoint="https://sms.example.com/send",
        api_key=os.environ["SMS_API_KEY"],
    ),
    user_store=user_store,   # required for email/sms channels
    event_bus=bus,           # optional — publishes telemetry events
)

config = AuthConfig(tools=tools)

# Mount the tools router for SSE + telemetry endpoints
from awesome_python_auth import build_tools_router
app.include_router(build_tools_router(tools))
```

#### `tools.notify()` — send to one or more channels

```python
# SSE only (default)
await tools.notify("user:123", type="ping", data={"msg": "Hello!"})

# SSE + email
await tools.notify(
    "user:123",
    type="subscription_expiring",
    data={"days_left": 3},
    user_id="123",
    channels=["sse", "email"],
    email_subject="Your subscription expires soon",
)

# All channels: SSE + email + SMS
await tools.notify(
    "user:123",
    type="security_alert",
    data="Unusual login detected",
    user_id="123",
    channels=["sse", "email", "sms"],
    email_subject="Security alert",
    sms_message="Unusual login detected on your account",
)

# Telemetry tracking (also publishes to event bus)
await tools.track(AuthEventNames.AUTH_LOGIN_SUCCESS, user_id="u1")
```

---

### Identity Provider (IdP) Mode

Signs JWTs with **RS256** and exposes `GET /.well-known/jwks.json` for downstream services:

```python
import os
from awesome_python_auth.idp import IdProviderConfig

config = AuthConfig(
    api_prefix="/api/auth",
    access_token_secret=os.environ["JWT_SECRET"],
    id_provider=IdProviderConfig(
        enabled=True,
        private_key=os.environ.get("IDP_PRIVATE_KEY"),  # PEM RSA private key
        issuer="https://auth.myplatform.com",
        token_expiry=2592000,           # 30 days
        refresh_token_expiry=7776000,   # 90 days
        jwks_path="/.well-known/jwks.json",
    ),
)
```

Generate an RSA keypair:

```python
from awesome_python_auth import JwksService

private_key, public_key = JwksService.generate_keypair()
# Store private_key securely in IDP_PRIVATE_KEY env var
```

:::note
If `private_key` is omitted, an ephemeral RSA-2048 keypair is auto-generated at startup. Tokens are invalidated on restart — use only for development.
:::

---

### Resource Server Mode

Validate JWTs issued by a remote IdP via JWKS:

```python
from awesome_python_auth.idp import ResourceServerConfig

config = AuthConfig(
    access_token_secret="not-used-when-resource-server-is-enabled",
    resource_server=ResourceServerConfig(
        enabled=True,
        jwks_url="https://auth.myplatform.com/api/auth/.well-known/jwks.json",
        issuer="https://auth.myplatform.com",  # optional — rejects wrong iss
        jwks_cache_ttl=3600,       # cache JWKS for 1 hour
        jwks_fetch_timeout=5.0,    # seconds
    ),
)
```

The `get_current_user`, `require_auth`, and `require_roles` dependencies switch automatically to JWKS-based RS256 verification when `resource_server.enabled` is `True`.

---

### RBAC — Roles & Permissions

```python
from awesome_python_auth import RolesPermissionsStore, InMemoryRolesPermissionsStore

rbac_store = InMemoryRolesPermissionsStore()

config = AuthConfig(roles_permissions_store=rbac_store)
```

Protect routes with roles:

```python
from awesome_python_auth import require_roles

@app.get("/billing")
async def billing(user = Depends(require_roles(["admin", "billing"]))):
    return {"access": "granted"}
```

---

### Multi-Tenancy

```python
from awesome_python_auth import TenantStore, InMemoryTenantStore

tenant_store = InMemoryTenantStore()
config = AuthConfig(tenant_store=tenant_store)
```

The `user.tenant_id` field in the JWT payload is set during registration/login. Use it to scope all queries:

```python
@app.get("/api/data")
async def data(user: AuthUser = Depends(require_auth)):
    return await db.find(tenant_id=user.tenant_id)
```

---

### M2M API Keys

```python
from awesome_python_auth import ApiKeyService, ApiKeyStore, InMemoryApiKeyStore

api_key_store = InMemoryApiKeyStore()
api_key_service = ApiKeyService(api_key_store)

config = AuthConfig(api_key_store=api_key_store)

# Create a key programmatically
key = await api_key_service.create_key(
    name="ci-bot",
    scopes=["read:users", "write:events"],
)
print(key.raw_key)  # store securely — not recoverable later
```

---

### Admin Router

Mount the built-in Admin UI for user management, sessions, RBAC, tenants, and telemetry:

```python
from awesome_python_auth import build_admin_router

app.include_router(build_admin_router(user_store, config))
# Admin UI available at /admin
```

---

### Built-in UI Router

Mount the bundled authentication SPA (login, register, password reset pages):

```python
from awesome_python_auth import build_ui_router

app.include_router(build_ui_router(config))
# UI available at /api/auth/ui/login, /api/auth/ui/register, etc.
```

---

### Cross-Origin Setup (Flutter web / Angular)

When your frontend is on a different domain, configure `CORSMiddleware` with `allow_credentials=True` and set `cookie_same_site="none"` with `cookie_secure=True`:

```python
app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://myapp.com"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*", "X-CSRF-Token", "X-Auth-Strategy"],
)
app.add_middleware(
    CsrfMiddleware,
    api_prefix="/api/auth",
    cookie_secure=True,
    cookie_same_site="none",  # required for cross-origin cookies
)

config = AuthConfig(
    cookie_secure=True,
    cookie_same_site="none",
)
```

---

### Connecting Flutter clients

The Flutter package (`awesome_flutter_auth`) works with `awesome-python-auth` as a drop-in replacement for the Node.js backend. Set the Flutter client's `apiPrefix` option to match your Python server's `api_prefix`:

```dart
import 'package:awesome_flutter_auth/awesome_flutter_auth.dart';

final auth = AuthClient(
  AuthOptions(
    apiPrefix: 'http://localhost:3000/api/auth',  // matches api_prefix in Python
    headless: true,
  ),
);
```

See the [Flutter integration guide](/docs/frameworks/flutter) for the full client-side setup.

---

### `AuthUser` model

The authenticated user decoded from the JWT:

| Field | Type | Description |
|-------|------|-------------|
| `sub` | `str` | Stable unique user ID (JWT subject) |
| `email` | `str` | Email address |
| `is_email_verified` | `bool` | Email verification status |
| `id` | `str \| None` | Database ID |
| `first_name` | `str \| None` | First name |
| `last_name` | `str \| None` | Last name |
| `name` | `str \| None` | Display name |
| `phone_number` | `str \| None` | Phone number |
| `role` | `str \| None` | Primary role string |
| `login_provider` | `str \| None` | OAuth provider name |
| `is_totp_enabled` | `bool \| None` | TOTP 2FA status |
| `has_password` | `bool \| None` | Whether a password is set |
| `roles` | `list[str] \| None` | List of roles |
| `permissions` | `list[str] \| None` | List of permissions |
| `is_admin` | `bool \| None` | Admin flag |
| `tenant_id` | `str \| None` | Multi-tenancy tenant ID |
| `metadata` | `dict \| None` | Arbitrary key-value metadata |

---

## Dart Backend Authentication: awesome-dart-auth

## Dart Integration — `awesome-dart-auth`

:::tip Official Dart backend library
For Dart backends, use [`awesome-dart-auth`](https://github.com/awesome-lang-auth/awesome-dart-auth).
:::

`awesome-dart-auth` is a server-side library for Shelf and Dart Frog that brings the same auth model as awesome-node-auth to Dart. What it implements today, capability by capability, is tracked in its own [parity snapshot vs awesome-node-auth](https://github.com/awesome-lang-auth/awesome-dart-auth#parity-snapshot-vs-awesome-node-auth).

### Resources

- GitHub repository: [awesome-lang-auth/awesome-dart-auth](https://github.com/awesome-lang-auth/awesome-dart-auth)

### Related

- [Flutter authentication client](/docs/frameworks/flutter) — the client that talks to a Dart backend
- [Python FastAPI authentication](/docs/frameworks/python) — the FastAPI port of the same model
- [Framework integrations](/docs/frameworks) — every supported backend and client
- [Auth API endpoints reference](/docs/api-reference/endpoints) — the contract the ports target

---

## Go Backend Authentication: awesome-go-auth

## Go Integration — `awesome-go-auth`

:::tip Official Go backend library
For Go backends, use [`awesome-go-auth`](https://github.com/awesome-lang-auth/awesome-go-auth).
:::

### Resources

- GitHub repository: [awesome-lang-auth/awesome-go-auth](https://github.com/awesome-lang-auth/awesome-go-auth)

### Related

- [Rust backend authentication](/docs/frameworks/rust) — the other systems-language port
- [Python FastAPI authentication](/docs/frameworks/python) — the FastAPI port of the same model
- [Framework integrations](/docs/frameworks) — every supported backend and client
- [Auth API endpoints reference](/docs/api-reference/endpoints) — the contract the ports target

---

## AWS Lambda Authentication: awesome-lambda-auth

## AWS Lambda — `awesome-lambda-auth`

:::caution Preview
`awesome-lambda-auth` is in **preview**. The stack deploys, and the two official clients, unmodified, register, log in, refresh with CSRF, enrol TOTP, complete a 2FA login and revoke sessions against it. What is wired today and what is still gated is tracked in [docs/PROGRESS.md](https://github.com/awesome-lang-auth/awesome-lambda-auth/blob/main/docs/PROGRESS.md).
:::

### What it is

`awesome-lambda-auth` is the serverless member of the family: an open-source, self-hosted alternative to AWS Cognito, deployed as a stack in your own AWS account. MIT, no per-MAU pricing, no phone-home.

It is **not a language port**. It imports the auth core from [awesome-go-auth](/docs/frameworks/go) unchanged, keeps the wire contract compatible with the reference, and replaces every long-lived-process assumption with a serverless primitive:

| Area | In `awesome-lambda-auth` |
|------|--------------------------|
| Events | API Gateway HTTP API (v2) and REST (v1), Lambda Function URL, ALB |
| Storage | One DynamoDB table with TTL: users, sessions with refresh-token families, single-use tokens, TOTP, linked accounts, pending links |
| Email and SMS | SES for mail, SNS for SMS, or a signed delivery webhook that takes every credential channel instead |
| Secrets | Secrets Manager, then SSM, then the environment |
| Identity provider | OIDC issuer (JWKS, discovery, authorize, token, userinfo) signed by an AWS KMS key or a PEM; session tokens stay HS256 |

It is a **deployable product**, configured by file and environment and extended through webhooks and OIDC, not a library you compile against. There is no package to install: you clone the repository, build the artifact and deploy the stack.

### Configuration

Two sources, layered:

1. A JSON document, from `AWESOME_AUTH_CONFIG_FILE=<path>` or inline in `AWESOME_AUTH_CONFIG_JSON`. Neither set means defaults.
2. `AWESOME_AUTH_*` environment variables, one per knob, on top of the document.

Secrets are never values in the document: a secret knob is a reference to Secrets Manager or SSM, resolved at cold start, and a plaintext secret in the document refuses to start.

Configuration domains that the schema accepts but the binary does not act on yet are **refused at start**, never silently ignored. At the time of writing these are `admin` and `tools`, so the admin console and the tools router are not available on this stack yet. The hosted UI is wired behind `ui.enabled`, which is off by default. Its admin dashboard calls routes this build does not mount, so the project's configuration reference says to leave it off on a deployed stack until the admin surface lands.

What the binary reads is documented in [docs/config-reference.md](https://github.com/awesome-lang-auth/awesome-lambda-auth/blob/main/docs/config-reference.md), and the full schema with every default in [docs/spec/config-schema.md](https://github.com/awesome-lang-auth/awesome-lambda-auth/blob/main/docs/spec/config-schema.md).

### Deploy outline

You need **Docker**, to build the Lambda binary in a pinned Go container, and the **AWS CLI v2** with a named profile that can create IAM roles, Lambda functions, API Gateway APIs, DynamoDB tables, Secrets Manager secrets and an S3 bucket. The SAM CLI is not needed: the template's transform runs server-side in CloudFormation.

```bash
git clone https://github.com/awesome-lang-auth/awesome-lambda-auth
cd awesome-lambda-auth
./scripts/build-lambda.sh                                   # dist/auth-lambda.zip, reproducible
./scripts/deploy.sh --profile <profile> --region <region>   # package + deploy with the AWS CLI, no SAM CLI
```

`--profile` and `--region` are required and have no defaults. The stack is one HTTP API, one Lambda function (`provided.al2023`, arm64) for the whole auth router, one DynamoDB table, a log group with 14-day retention by default, the JWT signing secrets, which AWS generates in Secrets Manager so you never handle their values, and, by default, nine CloudWatch alarms. A CloudFront distribution and a KMS signing key for the identity provider are optional. `scripts/teardown.sh` removes the stack and names what outlives it. The template, its parameters and the IAM policy are documented in [infra/sam/README.md](https://github.com/awesome-lang-auth/awesome-lambda-auth/blob/main/infra/sam/README.md).

To check a deployment, run the contract suite against it:

```bash
AWESOME_AUTH_CONTRACT_BASE_URL=https://<api-id>.execute-api.<region>.amazonaws.com \
AWESOME_AUTH_CONTRACT_REQUIRE=register,csrf,secure-cookies,sessions,totp \
./scripts/toolchain.sh go test -count=1 -v ./test/contract/...
```

`REQUIRE` turns "capability absent" from a skip into a failure, so a deployment that lost a feature cannot pass by skipping it.

### Wire compatibility

- **One contract.** The HTTP contract is extracted from the reference source into [docs/spec/wire-contract.md](https://github.com/awesome-lang-auth/awesome-lambda-auth/blob/main/docs/spec/wire-contract.md), which the stack is forbidden to break.
- **One test suite for both.** The contract suite in `test/contract` is black-box and parametrised on a base URL: it runs against this stack or against the reference Express app.
- **The official clients, unmodified.** `examples/angular-client` and `examples/flutter-client` use the official Angular and Flutter clients as published on npm and pub.dev. The API prefix defaults to `/auth`, as in awesome-node-auth, so the clients keep their usual `apiPrefix`.
- **Browser clients need one origin.** The session cookies are `SameSite=Lax` and the CSRF double-submit needs the page to read the CSRF cookie, so the examples serve the app and rewrite `/auth/*` to the API from the same origin.
- **Rate limiting, on by default.** The reference ships no limiter. This stack allows 10 requests per 60-second window, keyed by account, over the five credential flows, and refuses the rest with `429 RATE_LIMITED` and a `Retry-After`.

Every place where the stack differs from the reference is indexed in [docs/deviations.md](https://github.com/awesome-lang-auth/awesome-lambda-auth/blob/main/docs/deviations.md).

### Resources

- GitHub repository: [awesome-lang-auth/awesome-lambda-auth](https://github.com/awesome-lang-auth/awesome-lambda-auth)
- Status: [docs/PROGRESS.md](https://github.com/awesome-lang-auth/awesome-lambda-auth/blob/main/docs/PROGRESS.md)
- Compared with Cognito: [docs/cognito-comparison.md](https://github.com/awesome-lang-auth/awesome-lambda-auth/blob/main/docs/cognito-comparison.md)

### Related

- [Go backend authentication](/docs/frameworks/go) — the core this stack imports
- [Angular auth library](/docs/frameworks/ng-awesome-node-auth) — the Angular client the examples run unmodified
- [Flutter authentication client](/docs/frameworks/flutter) — the Flutter client the examples run unmodified
- [Framework integrations](/docs/frameworks) — every supported backend and client
- [Auth API endpoints reference](/docs/api-reference/endpoints) — the contract the ports target

---

## Rust Backend Authentication: awesome-rust-auth

## Rust Integration — `awesome-rust-auth`

:::tip Official Rust backend library
For Rust backends, use [`awesome-rust-auth`](https://github.com/awesome-lang-auth/awesome-rust-auth).
:::

`awesome-rust-auth` is a framework-agnostic crate, with adapters for Axum, Actix-web and Warp, that brings the same auth model as awesome-node-auth to Rust. What it implements today, capability by capability, is tracked in its own [parity snapshot vs awesome-node-auth](https://github.com/awesome-lang-auth/awesome-rust-auth#parity-snapshot-vs-awesome-node-auth).

### Resources

- GitHub repository: [awesome-lang-auth/awesome-rust-auth](https://github.com/awesome-lang-auth/awesome-rust-auth)

### Related

- [Go backend authentication](/docs/frameworks/go) — the other systems-language port
- [Python FastAPI authentication](/docs/frameworks/python) — the FastAPI port of the same model
- [Framework integrations](/docs/frameworks) — every supported backend and client
- [Auth API endpoints reference](/docs/api-reference/endpoints) — the contract the ports target

---

## Flutter Authentication Client (and WASM)

## Flutter & WASM Integration

:::tip Use the official Flutter package
**For new projects, use [`awesome_flutter_auth`](https://pub.dev/packages/awesome_flutter_auth)** — the official Flutter/Dart client for awesome-node-auth.

It handles:
- **Cookie + CSRF** automatically on web/WASM
- **Bearer token** automatically on native (iOS, Android, Desktop)
- Concurrent-refresh deduplication, session revocation, reactive state stream
- Zero token-management boilerplate

This page documents the official package. For the raw manual approach (no package), see the [Advanced / Bearer Token](/docs/advanced/bearer-token) guide.
:::

### Platform behaviour

| Platform | Auth mode | Token management | CSRF | WASM |
|----------|-----------|-----------------|------|------|
| Web | Cookie (HttpOnly) | Automatic | Auto-injected | ✅ |
| WASM | Cookie (HttpOnly) | Automatic | Auto-injected | ✅ |
| iOS | Bearer | Pluggable `TokenStorage` | n/a | n/a |
| Android | Bearer | Pluggable `TokenStorage` | n/a | n/a |
| Desktop | Bearer | Pluggable `TokenStorage` | n/a | n/a |

The package detects the platform at runtime — you do not choose the mode.

:::info Python backend
`awesome_flutter_auth` works with both the **Node.js** (`awesome-node-auth`) and the **Python** (`awesome-python-auth`) backends. Set `apiPrefix` to match your server's `api_prefix` (default `/api/auth` in Python vs `/auth` in Node.js). See the [Python / FastAPI guide](/docs/frameworks/python) for server-side setup.
:::

---

### Installation

```yaml
# pubspec.yaml
dependencies:
  awesome_flutter_auth: ^1.10.5
```

```bash
flutter pub get
```

:::note Formerly awesome_node_auth_flutter
The package was formerly published as `awesome_node_auth_flutter`, now discontinued on pub.dev and replaced by `awesome_flutter_auth`. To migrate, change the dependency and the import to `package:awesome_flutter_auth/awesome_flutter_auth.dart`. The source lives in [awesome-lang-auth/awesome-flutter-auth](https://github.com/awesome-lang-auth/awesome-flutter-auth).
:::

---

### Setup

Create an `AuthClient` with `AuthOptions`:

```dart
import 'package:awesome_flutter_auth/awesome_flutter_auth.dart';

final auth = AuthClient(
  AuthOptions(
    apiPrefix: 'http://localhost:3000/auth',
    loginUrl: '/login',         // redirect after logout (headless: false)
    headless: true,             // true → you control routing manually
    initializeOnStartup: true,  // calls checkSession() before first frame
  ),
);
```

`initializeOnStartup: true` calls `checkSession()` automatically during initialization so the reactive state stream emits the current user before your first widget build.

---

### Reactive state — `StreamBuilder`

`auth.state.userStream` is a broadcast stream that **replays the current value** to new subscribers, making it safe to use in `StreamBuilder` without a flash of unauthenticated UI:

```dart
StreamBuilder<AuthUser?>(
  stream: auth.state.userStream,
  builder: (context, snapshot) {
    if (snapshot.connectionState == ConnectionState.waiting) {
      return const CircularProgressIndicator();
    }
    if (snapshot.data != null) {
      return HomeScreen(user: snapshot.data!);
    }
    return const LoginScreen();
  },
);
```

---

### Events

Subscribe to `auth.events` to react to auth lifecycle changes. This is the recommended integration point for GoRouter / AutoRoute redirects:

```dart
auth.events.listen((event) {
  switch (event.type) {
    case AuthEventType.loggedIn:
      router.go('/dashboard');
    case AuthEventType.loggedOut:
      router.go('/login');
    case AuthEventType.sessionExpired:
      router.go('/login');
    case AuthEventType.sessionRevoked:
      router.go('/login');
    case AuthEventType.tokenRefreshed:
      // optional — tokens refreshed silently
      break;
    case AuthEventType.userUpdated:
      // profile changed
      break;
  }
});
```

---

### Login + 2FA flow

```dart
// Simple login
final result = await auth.login(email, password);

if (result.success && !result.requires2fa) {
  // Logged in — auth.state.userStream emits the user automatically
  context.go('/dashboard');
} else if (result.requires2fa) {
  // 2FA required — navigate to the 2FA screen
  context.go('/2fa', extra: result);
} else if (result.requires2FASetup) {
  // 2FA enrollment required
  context.go('/2fa/setup', extra: result);
} else {
  showError(result.error ?? 'Login failed');
}
```

On the 2FA screen, `result.tempToken` and `result.availableMethods` are available to drive the UI.

---

### 2FA — TOTP

```dart
// ── Setup (generate QR code) ──────────────────────────────────────────────
final setup = await auth.setupTotp();
// setup.qrCodeUrl  → display in a QR widget
// setup.secret     → show as text fallback

// ── Verify during enrollment ──────────────────────────────────────────────
await auth.verifyTotp(totpCode);

// ── Validate during login 2FA step ───────────────────────────────────────
final loginResult = await auth.validate2fa(
  result.tempToken!,
  totpCode,
);
```

---

### 2FA — SMS OTP

```dart
// ── SMS login (passwordless) ──────────────────────────────────────────────
await auth.sendSmsLogin(email);

// Verify OTP code sent to the user's phone
final loginResult = await auth.verifySmsLogin(userId, otpCode);

// ── SMS 2FA (second factor during login) ─────────────────────────────────
// 1. First receive result.tempToken from auth.login()
await auth.send2faSms(result.tempToken!);

// 2. User receives OTP on their phone
final loginResult = await auth.validate2fa(
  result.tempToken!,
  otpCode,
  method: 'sms',
);
```

---

### 2FA — Magic Link

```dart
// ── Request magic link ────────────────────────────────────────────────────
await auth.sendMagicLink(email);

// ── Validate token from the link (deep link handler) ─────────────────────
final loginResult = await auth.verifyMagicLink(token);
```

---

### Password

```dart
// Change password (authenticated)
await auth.changePassword(currentPassword, newPassword);

// Request password reset (unauthenticated)
await auth.forgotPassword(email);

// Complete reset with token from email link
await auth.resetPassword(newPassword, resetToken);
```

---

### Email

```dart
// Request email change (authenticated)
await auth.requestEmailChange(newEmail);

// Confirm with token from email link
await auth.confirmEmailChange(confirmationToken);

// Resend verification email
await auth.resendVerificationEmail();

// Verify email address with token from email link
await auth.verifyEmail(verificationToken);
```

---

### Profile

```dart
// Get current user
final user = auth.state.currentUser; // sync, from cache

// Refresh from server
final user = await auth.fetchProfile();

// Update profile fields
await auth.updateProfile({'displayName': 'Alice', 'avatarUrl': '...'});
```

---

### Sessions

```dart
// List active sessions
final sessions = await auth.getActiveSessions();

// Revoke a specific session
await auth.revokeSession(sessionHandle);
```

---

### Account linking

```dart
// Initiate linking by sending an email to the other account
await auth.requestLinkingEmail(otherEmail, provider);

// Confirm the link using the token from the email
await auth.verifyLinkingToken(token, provider);

// List all linked providers
final accounts = await auth.getLinkedAccounts();

// Unlink a specific provider account
await auth.unlinkAccount(provider, providerAccountId);
```

---

### UI Config

Load backend feature flags to drive adaptive UI (e.g., hide magic-link button when the server has it disabled):

```dart
final config = await auth.loadUiConfig();
if (config?.magicLinkEnabled == true) {
  // Show magic-link option in the login screen
}
```

---

### Authenticated HTTP calls

`auth.httpClient` is a pre-configured HTTP client that automatically attaches the correct auth credentials (cookies on web, `Authorization: Bearer` on native) and transparently refreshes tokens on 401 responses:

```dart
// GET with automatic auth — no manual token handling needed
final response = await auth.httpClient.get(
  Uri.parse('https://api.example.com/todos'),
);

// POST with body
final response = await auth.httpClient.post(
  Uri.parse('https://api.example.com/todos'),
  headers: {'Content-Type': 'application/json'},
  body: jsonEncode({'title': 'Buy milk'}),
);
```

---

### Custom `TokenStorage`

On native platforms the package stores tokens in memory by default. For persistence across restarts, provide a `TokenStorage` implementation backed by `flutter_secure_storage`:

:::note
`flutter_secure_storage` is **not** a dependency of `awesome_flutter_auth`. Add it yourself if you need persistent token storage on native.
:::

```yaml
# pubspec.yaml — add only for native persistence
dependencies:
  awesome_flutter_auth: ^1.10.5
  flutter_secure_storage: ^9.0.0
```

```dart
import 'package:flutter_secure_storage/flutter_secure_storage.dart';
import 'package:awesome_flutter_auth/awesome_flutter_auth.dart';

class SecureTokenStorage implements TokenStorage {
  final _storage = const FlutterSecureStorage(
    aOptions: AndroidOptions(encryptedSharedPreferences: true),
    iOptions: IOSOptions(accessibility: KeychainAccessibility.first_unlock),
  );

  @override
  Future<String?> read(String key) => _storage.read(key: key);

  @override
  Future<void> write(String key, String value) =>
      _storage.write(key: key, value: value);

  @override
  Future<void> delete(String key) => _storage.delete(key: key);
}

// Pass to AuthOptions
final auth = AuthClient(
  AuthOptions(
    apiPrefix: 'http://localhost:3000/auth',
    tokenStorage: SecureTokenStorage(),
    headless: true,
  ),
);
```

---

### Comportamento interno — refresh e deduplicazione

- **Deduplicazione concorrente**: se più chiamate API ricevono un 401 contemporaneamente, il package esegue un solo refresh e mette in coda le altre fino al completamento.
- **`SESSION_REVOKED`**: se il server risponde con `{ code: "SESSION_REVOKED" }`, il package emette `AuthEventType.sessionRevoked` e non ritenta il refresh (evita loop infiniti).
- **Endpoint esclusi dal retry**: `/auth/login`, `/auth/register`, `/auth/refresh` non vengono mai ritentati dopo un 401.
- **Web vs nativo**: su web il refresh usa i cookie HttpOnly; su nativo invia il `refreshToken` nel corpo della richiesta.

---

### Headless mode

With `headless: true`, the package does **not** perform any automatic redirects. You control all navigation via the events stream — ideal with GoRouter or AutoRoute:

```dart
// main.dart
final auth = AuthClient(
  AuthOptions(
    apiPrefix: 'http://localhost:3000/auth',
    headless: true,
    initializeOnStartup: false, // call checkSession() manually
  ),
);

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await auth.checkSession(); // restore session before first frame
  runApp(const MyApp());
}

// GoRouter redirect
redirect: (context, state) {
  final isAuth = auth.state.isAuthenticated;
  final isInit = auth.state.isInitialized;
  if (!isInit) return null; // still loading — don't redirect
  if (!isAuth && !publicPaths.contains(state.matchedLocation)) {
    return '/login';
  }
  return null;
},
```

---

### WASM

The package is fully WASM-compatible. Build with:

```bash
flutter build web --wasm
```

The package uses `package:web` and `package:http` exclusively — no `dart:html` or `dart:io` calls — so it compiles to WASM without modifications.

---

### AuthService wrapper (recommended)

For larger apps, wrap `AuthClient` in a singleton service to decouple it from the widget tree:

```dart
// lib/services/auth_service.dart
import 'package:awesome_flutter_auth/awesome_flutter_auth.dart';

class AuthService {
  AuthService._();
  static final AuthService instance = AuthService._();

  final AuthClient client = AuthClient(
    AuthOptions(
      apiPrefix: 'http://localhost:3000/auth',
      headless: true,
    ),
  );

  AuthState get state  => client.state;
  Stream<AuthEvent> get events => client.events;
}
```

```dart
// main.dart
void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await AuthService.instance.client.checkSession();
  runApp(const MyApp());
}
```

---

<details>
<summary>Migration from manual integration (previous approach)</summary>

The previous version of this page documented a manual integration using `flutter_secure_storage`, the `http` package, and the `X-Auth-Strategy: bearer` header. Below is a quick before/after comparison.

| Before (manual) | After (`awesome_flutter_auth`) |
|----------------|-------------------------------------|
| `http` + manual `X-Auth-Strategy: bearer` header | Handled automatically by the package |
| `flutter_secure_storage` for token persistence | Built-in `TokenStorage` interface; bring your own storage |
| Manual 401 retry with refresh | Built-in concurrent deduplication |
| No web/WASM support | Full web + WASM support via cookie mode |
| No reactive state | `auth.state.userStream` — replay stream |
| No event bus | `auth.events` — `AuthEventType` enum |

To migrate:
1. Add `awesome_flutter_auth: ^1.10.5` to `pubspec.yaml`.
2. Remove `http` and the manual `AuthService` if they were only used for auth.
3. Replace all `_bearerHeaders` / `_authedRequest` calls with `AuthClient` methods.
4. If you need persistent tokens on native, implement `TokenStorage` with `flutter_secure_storage` (see [Custom TokenStorage](#custom-tokenstorage) above).

</details>

---

## iOS Swift Authentication with Keychain

## iOS Integration (Swift)

This guide shows how to integrate your awesome-node-auth backend in an iOS app using `URLSession` and Apple's **Keychain** for secure token storage.

### Step 1 — Keychain Helper

Store tokens in the Keychain, which is encrypted by the Secure Enclave and wiped when the app is uninstalled.

```swift
// Sources/Auth/KeychainHelper.swift
import Foundation
import Security

enum KeychainHelper {
    private static let service = Bundle.main.bundleIdentifier ?? "com.myapp"

    static func save(_ value: String, forKey key: String) {
        let data = Data(value.utf8)
        let query: [String: Any] = [
            kSecClass as String:            kSecClassGenericPassword,
            kSecAttrService as String:      service,
            kSecAttrAccount as String:      key,
            kSecValueData as String:        data,
            kSecAttrAccessible as String:   kSecAttrAccessibleAfterFirstUnlock,
        ]
        SecItemDelete(query as CFDictionary)            // remove any existing item
        SecItemAdd(query as CFDictionary, nil)
    }

    static func load(forKey key: String) -> String? {
        let query: [String: Any] = [
            kSecClass as String:            kSecClassGenericPassword,
            kSecAttrService as String:      service,
            kSecAttrAccount as String:      key,
            kSecReturnData as String:       true,
            kSecMatchLimit as String:       kSecMatchLimitOne,
        ]
        var result: AnyObject?
        guard SecItemCopyMatching(query as CFDictionary, &result) == errSecSuccess,
              let data = result as? Data else { return nil }
        return String(data: data, encoding: .utf8)
    }

    static func delete(forKey key: String) {
        let query: [String: Any] = [
            kSecClass as String:       kSecClassGenericPassword,
            kSecAttrService as String: service,
            kSecAttrAccount as String: key,
        ]
        SecItemDelete(query as CFDictionary)
    }
}
```

### Step 2 — Auth Service

:::info Bearer mode required
iOS is a native client and cannot use browser cookies. The `X-Auth-Strategy: bearer` header must be sent on all token-issuing requests (`/auth/login`, `/auth/refresh`, etc.) so the server returns tokens in the JSON body.
:::

```swift
// Sources/Auth/AuthService.swift
import Foundation

struct AuthTokens: Decodable {
    let accessToken:  String
    let refreshToken: String
}

struct JwtUser: Decodable {
    let sub:      String
    let email:    String
    let role:     String
    let tenantId: String?
}

actor AuthService {
    static let shared = AuthService()

    private let baseURL = URL(string: "https://your-api.example.com")!
    private let accessKey  = "access_token"
    private let refreshKey = "refresh_token"

    // MARK: – Token accessors

    var accessToken: String?  { KeychainHelper.load(forKey: accessKey) }
    var refreshToken: String? { KeychainHelper.load(forKey: refreshKey) }

    private func saveTokens(_ tokens: AuthTokens) {
        KeychainHelper.save(tokens.accessToken,  forKey: accessKey)
        KeychainHelper.save(tokens.refreshToken, forKey: refreshKey)
    }

    func clearTokens() {
        KeychainHelper.delete(forKey: accessKey)
        KeychainHelper.delete(forKey: refreshKey)
    }

    // MARK: – Login

    func login(email: String, password: String) async throws -> AuthTokens {
        var request = URLRequest(url: baseURL.appendingPathComponent("/auth/login"))
        request.httpMethod  = "POST"
        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
        request.setValue("bearer", forHTTPHeaderField: "X-Auth-Strategy")
        request.httpBody    = try JSONEncoder().encode(["email": email, "password": password])

        let (data, _) = try await URLSession.shared.data(for: request)
        let tokens = try JSONDecoder().decode(AuthTokens.self, from: data)
        saveTokens(tokens)
        return tokens
    }

    // MARK: – Logout

    func logout() async throws {
        var request = URLRequest(url: baseURL.appendingPathComponent("/auth/logout"))
        request.httpMethod = "POST"
        if let token = accessToken {
            request.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")
        }
        _ = try? await URLSession.shared.data(for: request)
        clearTokens()
    }

    // MARK: – Refresh
    func refresh() async throws -> String {
        guard let rt = refreshToken else { throw AuthError.notAuthenticated }
        var request = URLRequest(url: baseURL.appendingPathComponent("/auth/refresh"))
        request.httpMethod  = "POST"
        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
        request.setValue("bearer", forHTTPHeaderField: "X-Auth-Strategy")
        request.httpBody    = try JSONEncoder().encode(["refreshToken": rt])

        let (data, _) = try await URLSession.shared.data(for: request)
        struct RefreshResponse: Decodable { let accessToken: String; let refreshToken: String }
        let res = try JSONDecoder().decode(RefreshResponse.self, from: data)
        KeychainHelper.save(res.accessToken,  forKey: accessKey)
        KeychainHelper.save(res.refreshToken, forKey: refreshKey)
        return res.accessToken
    }

    // MARK: – Authenticated request helper

    func request(
        path: String,
        method: String = "GET",
        body: Encodable? = nil
    ) async throws -> Data {
        var token = accessToken ?? (try await refresh())

        func makeRequest(with bearerToken: String) throws -> URLRequest {
            var req = URLRequest(url: baseURL.appendingPathComponent(path))
            req.httpMethod = method
            req.setValue("Bearer \(bearerToken)", forHTTPHeaderField: "Authorization")
            req.setValue("application/json", forHTTPHeaderField: "Content-Type")
            if let body {
                req.httpBody = try JSONEncoder().encode(body)
            }
            return req
        }

        let (data, response) = try await URLSession.shared.data(for: makeRequest(with: token))

        if (response as? HTTPURLResponse)?.statusCode == 401 {
            token = try await refresh()   // one refresh attempt
            let (retryData, _) = try await URLSession.shared.data(for: makeRequest(with: token))
            return retryData
        }
        return data
    }

    // MARK: – Profile

    func getProfile() async throws -> JwtUser {
        let data = try await request(path: "/auth/me")
        return try JSONDecoder().decode(JwtUser.self, from: data)
    }
}

enum AuthError: Error {
    case notAuthenticated
    case serverError(Int)
}
```

### Step 3 — SwiftUI Login View

```swift
// Sources/Views/LoginView.swift
import SwiftUI

struct LoginView: View {
    @State private var email    = ""
    @State private var password = ""
    @State private var loading  = false
    @State private var errorMsg: String?
    @EnvironmentObject private var appState: AppState

    var body: some View {
        VStack(spacing: 20) {
            Text("Sign In").font(.largeTitle).bold()

            TextField("Email", text: $email)
                .textContentType(.emailAddress)
                .autocapitalization(.none)
                .textFieldStyle(.roundedBorder)

            SecureField("Password", text: $password)
                .textContentType(.password)
                .textFieldStyle(.roundedBorder)

            if let msg = errorMsg {
                Text(msg).foregroundColor(.red).font(.caption)
            }

            Button(action: login) {
                if loading {
                    ProgressView()
                } else {
                    Text("Sign In").frame(maxWidth: .infinity)
                }
            }
            .buttonStyle(.borderedProminent)
            .disabled(loading || email.isEmpty || password.isEmpty)
        }
        .padding(32)
    }

    private func login() {
        loading  = true
        errorMsg = nil
        Task {
            do {
                _ = try await AuthService.shared.login(email: email, password: password)
                await MainActor.run { appState.isLoggedIn = true }
            } catch {
                await MainActor.run { errorMsg = error.localizedDescription }
            }
            await MainActor.run { loading = false }
        }
    }
}
```

### Step 4 — App State + Root View

```swift
// Sources/AppState.swift
import SwiftUI

@MainActor
final class AppState: ObservableObject {
    @Published var isLoggedIn: Bool

    init() {
        // Restore session on launch — check if access token exists
        isLoggedIn = KeychainHelper.load(forKey: "access_token") != nil
    }
}
```

```swift
// MyApp.swift
import SwiftUI

@main
struct MyApp: App {
    @StateObject private var appState = AppState()

    var body: some Scene {
        WindowGroup {
            if appState.isLoggedIn {
                DashboardView()
                    .environmentObject(appState)
            } else {
                LoginView()
                    .environmentObject(appState)
            }
        }
    }
}
```

### OAuth / Social Login

For OAuth, open the authorization URL in `ASWebAuthenticationSession` and capture the deep-link callback:

```swift
import AuthenticationServices

func loginWithOAuth(provider: String) async throws {
    let authURL = URL(string: "https://your-api.example.com/auth/oauth/\(provider)")!
    let callbackScheme = "myapp"

    return try await withCheckedThrowingContinuation { continuation in
        let session = ASWebAuthenticationSession(
            url: authURL,
            callbackURLScheme: callbackScheme
        ) { callbackURL, error in
            if let error { return continuation.resume(throwing: error) }
            guard let url = callbackURL,
                  let components = URLComponents(url: url, resolvingAgainstBaseURL: false),
                  let accessToken  = components.queryItems?.first(where: { $0.name == "accessToken" })?.value,
                  let refreshToken = components.queryItems?.first(where: { $0.name == "refreshToken" })?.value
            else { return continuation.resume(throwing: AuthError.notAuthenticated) }

            KeychainHelper.save(accessToken,  forKey: "access_token")
            KeychainHelper.save(refreshToken, forKey: "refresh_token")
            continuation.resume()
        }
        session.presentationContextProvider = self as? ASWebAuthenticationPresentationContextProviding
        session.prefersEphemeralWebBrowserSession = false
        session.start()
    }
}
```

Add `myapp` as a URL scheme in `Info.plist` under **URL Types**.

### Security Notes

- ✅ Tokens stored in **Keychain** (`kSecAttrAccessibleAfterFirstUnlock`) — survives app restart but wiped on uninstall
- ✅ Access token kept in memory via `AuthService.accessToken` (reads from Keychain on demand)
- ✅ Auto-refresh on 401 with a single retry
- ✅ App Transport Security (ATS) enforces HTTPS by default

### Related

- [Bearer token mode for mobile apps](/docs/advanced/bearer-token) — why native clients skip cookies
- [Android Kotlin authentication](/docs/frameworks/android) — the same flow on Android
- [Flutter authentication client](/docs/frameworks/flutter) — one codebase for both platforms
- [TOTP two-factor authentication](/docs/authentication/totp) — 2FA from a native app

---

## Android Kotlin Authentication with Retrofit

## Android Integration (Kotlin)

This guide integrates your awesome-node-auth backend in an Android app using **Retrofit** for HTTP, **EncryptedSharedPreferences** (via Jetpack Security) for safe token storage, and **OkHttp** interceptors for automatic token refresh.

### Dependencies

Add to `build.gradle.kts` (app module):

```kotlin
dependencies {
    // Networking
    implementation("com.squareup.retrofit2:retrofit:2.11.0")
    implementation("com.squareup.retrofit2:converter-gson:2.11.0")
    implementation("com.squareup.okhttp3:okhttp:4.12.0")
    implementation("com.squareup.okhttp3:logging-interceptor:4.12.0")

    // Secure storage
    implementation("androidx.security:security-crypto:1.1.0-alpha06")

    // Coroutines
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.8.0")
}
```

### Step 1 — Secure Token Storage

`EncryptedSharedPreferences` encrypts both keys and values using AES-256-GCM backed by the Android Keystore.

```kotlin
// auth/TokenStorage.kt
import android.content.Context
import androidx.security.crypto.EncryptedSharedPreferences
import androidx.security.crypto.MasterKey

object TokenStorage {
    private const val FILE_NAME      = "auth_tokens"
    private const val KEY_ACCESS     = "access_token"
    private const val KEY_REFRESH    = "refresh_token"

    private fun prefs(context: Context) = EncryptedSharedPreferences.create(
        context,
        FILE_NAME,
        MasterKey.Builder(context)
            .setKeyScheme(MasterKey.KeyScheme.AES256_GCM)
            .build(),
        EncryptedSharedPreferences.PrefKeyEncryptionScheme.AES256_SIV,
        EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM,
    )

    fun saveTokens(context: Context, accessToken: String, refreshToken: String) {
        prefs(context).edit()
            .putString(KEY_ACCESS,  accessToken)
            .putString(KEY_REFRESH, refreshToken)
            .apply()
    }

    fun getAccessToken(context: Context): String?  = prefs(context).getString(KEY_ACCESS,  null)
    fun getRefreshToken(context: Context): String? = prefs(context).getString(KEY_REFRESH, null)

    fun clearTokens(context: Context) {
        prefs(context).edit().clear().apply()
    }
}
```

### Step 2 — Retrofit API Interface

```kotlin
// auth/AuthApi.kt
import retrofit2.http.*

data class LoginRequest(val email: String, val password: String)
data class AuthTokens(val accessToken: String, val refreshToken: String)
data class RefreshRequest(val refreshToken: String)
data class RefreshResponse(val accessToken: String)

data class JwtUser(
    val sub:      String,
    val email:    String,
    val role:     String,
    val tenantId: String? = null,
)

interface AuthApi {
    @POST("/auth/login")
    suspend fun login(@Body body: LoginRequest): AuthTokens

    @POST("/auth/logout")
    suspend fun logout()

    @POST("/auth/refresh")
    suspend fun refresh(@Body body: RefreshRequest): RefreshResponse

    @GET("/auth/me")
    suspend fun me(): JwtUser
}
```

### Step 3 — OkHttp Auth Interceptor

:::info Bearer mode required
Android is a native client and cannot use browser cookies. The `X-Auth-Strategy: bearer` header must be sent on all token-issuing requests (`/auth/login`, `/auth/refresh`, etc.) so the server returns tokens in the JSON body.
:::

The interceptor attaches the ****** and retries once on 401:

```kotlin
// auth/AuthInterceptor.kt
import android.content.Context
import okhttp3.Interceptor
import okhttp3.OkHttpClient
import okhttp3.Request
import okhttp3.Response
import retrofit2.Retrofit
import retrofit2.converter.gson.GsonConverterFactory

class AuthInterceptor(private val context: Context) : Interceptor {

    override fun intercept(chain: Interceptor.Chain): Response {
        val accessToken = TokenStorage.getAccessToken(context)
        val request = chain.request().newBuilder()
            .header("X-Auth-Strategy", "bearer")  // opt into bearer-token delivery
            .build()
            .withBearer(accessToken)
        val response = chain.proceed(request)

        if (response.code == 401) {
            response.close()
            val newToken = tryRefresh() ?: return response
            return chain.proceed(chain.request().withBearer(newToken))
        }
        return response
    }

    private fun tryRefresh(): String? {
        val refreshToken = TokenStorage.getRefreshToken(context) ?: return null
        return runCatching {
            // Use a separate OkHttpClient (no interceptor) to avoid recursion
            val bearerClient = OkHttpClient.Builder()
                .addInterceptor { chain ->
                    chain.proceed(
                        chain.request().newBuilder()
                            .header("X-Auth-Strategy", "bearer")
                            .build()
                    )
                }
                .build()
            val retrofit = Retrofit.Builder()
                .baseUrl(BASE_URL)
                .client(bearerClient)
                .addConverterFactory(GsonConverterFactory.create())
                .build()
            val api = retrofit.create(AuthApi::class.java)

            // runBlocking is acceptable here because OkHttp calls run on a background thread
            val res = kotlinx.coroutines.runBlocking {
                api.refresh(RefreshRequest(refreshToken))
            }
            TokenStorage.saveTokens(context, res.accessToken, refreshToken)
            res.accessToken
        }.getOrNull()
    }
}

private fun Request.withBearer(token: String?): Request =
    if (token != null) newBuilder().header("Authorization", "Bearer $token").build()
    else this

const val BASE_URL = "https://your-api.example.com"
```

### Step 4 — Retrofit Client Factory

```kotlin
// auth/AuthClient.kt
import android.content.Context
import okhttp3.OkHttpClient
import okhttp3.logging.HttpLoggingInterceptor
import retrofit2.Retrofit
import retrofit2.converter.gson.GsonConverterFactory

object AuthClient {
    fun create(context: Context): AuthApi {
        val logging = HttpLoggingInterceptor().apply {
            level = HttpLoggingInterceptor.Level.BODY   // remove in release
        }
        val client = OkHttpClient.Builder()
            .addInterceptor(AuthInterceptor(context))
            .addInterceptor(logging)
            .build()

        return Retrofit.Builder()
            .baseUrl(BASE_URL)
            .client(client)
            .addConverterFactory(GsonConverterFactory.create())
            .build()
            .create(AuthApi::class.java)
    }
}
```

### Step 5 — AuthViewModel

```kotlin
// auth/AuthViewModel.kt
import android.app.Application
import androidx.lifecycle.AndroidViewModel
import androidx.lifecycle.viewModelScope
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.launch

sealed class AuthState {
    object Idle        : AuthState()
    object Loading     : AuthState()
    data class Success(val user: JwtUser) : AuthState()
    data class Error(val message: String) : AuthState()
}

class AuthViewModel(app: Application) : AndroidViewModel(app) {
    private val api = AuthClient.create(app)
    private val ctx get() = getApplication<Application>()

    private val _state = MutableStateFlow<AuthState>(AuthState.Idle)
    val state: StateFlow<AuthState> = _state

    val isLoggedIn: Boolean
        get() = TokenStorage.getAccessToken(ctx) != null

    fun login(email: String, password: String) {
        viewModelScope.launch {
            _state.value = AuthState.Loading
            _state.value = runCatching {
                val tokens = api.login(LoginRequest(email, password))
                TokenStorage.saveTokens(ctx, tokens.accessToken, tokens.refreshToken)
                val user = api.me()
                AuthState.Success(user)
            }.getOrElse { AuthState.Error(it.message ?: "Login failed") }
        }
    }

    fun logout() {
        viewModelScope.launch {
            runCatching { api.logout() }
            TokenStorage.clearTokens(ctx)
            _state.value = AuthState.Idle
        }
    }
}
```

### Step 6 — Jetpack Compose Login Screen

```kotlin
// ui/LoginScreen.kt
import androidx.compose.foundation.layout.*
import androidx.compose.material3.*
import androidx.compose.runtime.*
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.text.input.PasswordVisualTransformation
import androidx.compose.ui.unit.dp

@Composable
fun LoginScreen(viewModel: AuthViewModel, onSuccess: () -> Unit) {
    var email    by remember { mutableStateOf("") }
    var password by remember { mutableStateOf("") }
    val state by viewModel.state.collectAsState()

    LaunchedEffect(state) {
        if (state is AuthState.Success) onSuccess()
    }

    Column(
        modifier = Modifier.fillMaxSize().padding(32.dp),
        verticalArrangement = Arrangement.Center,
        horizontalAlignment = Alignment.CenterHorizontally,
    ) {
        Text("Sign In", style = MaterialTheme.typography.headlineLarge)
        Spacer(Modifier.height(24.dp))

        OutlinedTextField(
            value = email, onValueChange = { email = it },
            label = { Text("Email") }, modifier = Modifier.fillMaxWidth(),
        )
        Spacer(Modifier.height(12.dp))

        OutlinedTextField(
            value = password, onValueChange = { password = it },
            label = { Text("Password") },
            visualTransformation = PasswordVisualTransformation(),
            modifier = Modifier.fillMaxWidth(),
        )
        Spacer(Modifier.height(8.dp))

        if (state is AuthState.Error) {
            Text((state as AuthState.Error).message, color = MaterialTheme.colorScheme.error)
            Spacer(Modifier.height(8.dp))
        }

        Button(
            onClick = { viewModel.login(email, password) },
            enabled = state !is AuthState.Loading && email.isNotBlank() && password.isNotBlank(),
            modifier = Modifier.fillMaxWidth(),
        ) {
            if (state is AuthState.Loading) CircularProgressIndicator(Modifier.size(20.dp))
            else Text("Sign In")
        }
    }
}
```

### OAuth / Social Login

Use a [Custom Chrome Tab](https://developer.chrome.com/docs/android/custom-tabs) to open the OAuth URL and capture the deep-link redirect:

```kotlin
// Redirect URI registered in AndroidManifest.xml:
// <data android:scheme="myapp" android:host="oauth-callback" />

val authUri = Uri.parse(
    "$BASE_URL/auth/oauth/$provider?redirect_uri=${Uri.encode("myapp://oauth-callback")}"
)
CustomTabsIntent.Builder().build().launchUrl(context, authUri)

// In your Activity / NavController — handle the deep link:
intent?.data?.let { uri ->
    val accessToken  = uri.getQueryParameter("accessToken")
    val refreshToken = uri.getQueryParameter("refreshToken")
    if (accessToken != null && refreshToken != null) {
        TokenStorage.saveTokens(context, accessToken, refreshToken)
    }
}
```

### Security Notes

- ✅ Tokens stored in **EncryptedSharedPreferences** — backed by the Android Keystore (hardware-backed on modern devices)
- ✅ AES-256-GCM encryption for values, AES-256-SIV for keys
- ✅ Auto-refresh on 401 with a single retry (separate OkHttpClient to avoid recursion)
- ✅ Add `android:usesCleartextTraffic="false"` to `AndroidManifest.xml` — enforces HTTPS
- ✅ Use `BuildConfig.DEBUG` to disable the OkHttp logging interceptor in release builds

### Related

- [Bearer token mode for mobile apps](/docs/advanced/bearer-token) — why native clients skip cookies
- [iOS Swift authentication](/docs/frameworks/ios) — the same flow on iOS
- [Flutter authentication client](/docs/frameworks/flutter) — one codebase for both platforms
- [SMS OTP verification and 2FA](/docs/authentication/sms) — phone verification on mobile

---

## Use the docs with AI assistants

The site publishes its documentation as two plain-text files for AI assistants: `llms.txt` follows the [llms.txt format](https://llmstxt.org), and `llms-full.txt` is a companion file with the full text of every page. Both are generated from the documentation on every build of the site, so they match the pages you read here.

- **`llms.txt`**, at [https://awesomelangauth.com/llms.txt](https://awesomelangauth.com/llms.txt): an index of every documentation page, with its title, its absolute URL and a one-line summary.
- **`llms-full.txt`**, at [https://awesomelangauth.com/llms-full.txt](https://awesomelangauth.com/llms-full.txt): the text of every documentation page in a single Markdown file. Links in it that start with `/` are relative to `https://awesomelangauth.com`.

### Give them to an assistant

- **Paste the URL into the chat.** If the assistant can open web pages, it can read `llms.txt` and then open the pages it lists, or read `llms-full.txt` directly.
- **Paste or attach the file.** Save `llms-full.txt` and add it to the conversation, so the assistant has the documentation even when it cannot open web pages.
- **Add the URL as a documentation source.** In tools that let you add documentation by URL, add one of the two URLs above.

`llms-full.txt` contains every page, so it is large (several hundred kilobytes). If an assistant cannot take it whole, give it `llms.txt` and the pages you need.

### The hosted MCP server

The hosted awesome-node-auth MCP server, which connected AI editors to this documentation through an API key, [is being retired](/docs/mcp-server). `llms.txt` and `llms-full.txt` replace it for AI-assisted setup, with no account and no key.

---

## The hosted MCP server is being retired

The hosted awesome-node-auth MCP server, which connected AI editors to this documentation
through an API key, is being retired. The account area of this site, where those keys were
created, has already been removed.

To give an AI assistant this documentation, use
[llms.txt and llms-full.txt](/docs/ai-assistants) instead: no account and no key.

The library is not affected: awesome-node-auth, its backend ports and its client libraries
work exactly as before, and they are fully documented here:

- **[Getting Started](/docs/intro)** — install awesome-node-auth, mount the auth router,
  choose a store and pick an authentication recipe.
- **[Framework integrations](/docs/frameworks)** — Express, NestJS and Next.js, the Python,
  Dart, Go and Rust backends, and the Angular, Flutter, iOS and Android clients.
- **[Installation & Configuration](/docs/installation)** — the full configuration reference.