@nik2208/node-auth 1.0.2 → 1.1.0

package/README.md

@@ -14,6 +14,11 @@ A production-ready, **database-agnostic** JWT authentication library for Node.js
 - 🧩 **Strategy Pattern** – Plug in only the auth methods you need
 - 🛡️ **Middleware** – Express-compatible JWT verification middleware
 - 🚀 **Express Router** – Drop-in `/auth` router with all endpoints
+- 🏷️ **Custom JWT Claims** – Inject project-specific data into tokens via `buildTokenPayload`
+- 📋 **User Metadata** – Optional `IUserMetadataStore` for arbitrary per-user key/value data
+- 🛡️ **Roles & Permissions** – Optional `IRolesPermissionsStore` for RBAC with tenant awareness
+- 📅 **Session Management** – Optional `ISessionStore` for device-aware session listing & revocation
+- 🏢 **Multi-Tenancy** – Optional `ITenantStore` for isolated multi-tenant applications
 
 ## Installation
 
@@ -274,6 +279,11 @@ When you mount `auth.router()`, the following endpoints are available:
 | `GET` | `/auth/me` | Get current user (protected) |
 | `POST` | `/auth/forgot-password` | Send password reset email |
 | `POST` | `/auth/reset-password` | Reset password with token |
+| `POST` | `/auth/change-password` | Change password (authenticated, requires `currentPassword` + `newPassword`) |
+| `POST` | `/auth/send-verification-email` | Send email verification link (authenticated) |
+| `GET` | `/auth/verify-email?token=...` | Verify email address from link |
+| `POST` | `/auth/change-email/request` | Request email change — sends verification to `newEmail` (authenticated) |
+| `POST` | `/auth/change-email/confirm` | Confirm email change with token |
 | `POST` | `/auth/2fa/setup` | Get TOTP secret + QR code (protected) |
 | `POST` | `/auth/2fa/verify-setup` | Verify TOTP code and enable 2FA (protected) |
 | `POST` | `/auth/2fa/verify` | Complete 2FA login |
@@ -551,6 +561,14 @@ interface BaseUser {
   smsCode?: string | null;
   smsCodeExpiry?: Date | null;
   phoneNumber?: string | null;
+  // Email verification
+  isEmailVerified?: boolean;
+  emailVerificationToken?: string | null;
+  emailVerificationTokenExpiry?: Date | null;
+  // Change email
+  pendingEmail?: string | null;
+  emailChangeToken?: string | null;
+  emailChangeTokenExpiry?: Date | null;
 }
 ```
 
@@ -590,7 +608,159 @@ class ApiKeyStrategy extends BaseAuthStrategy<{ apiKey: string }, MyUser> {
 }
 ```
 
-## Rate Limiting
+## Email Verification
+
+The email-verification flow reuses the same token infrastructure as password reset and is available out of the box once you implement the three optional store methods.
+
+### IUserStore additions
+
+```typescript
+// Required to support /auth/send-verification-email and /auth/verify-email
+updateEmailVerificationToken(userId, token, expiry): Promise<void>
+updateEmailVerified(userId, isVerified): Promise<void>
+findByEmailVerificationToken(token): Promise<U | null>
+```
+
+### AuthConfig email callbacks
+
+```typescript
+email: {
+  // Called when a verification email is needed (takes precedence over mailer)
+  sendVerificationEmail: async (to, token, link, lang?) => { /* ... */ },
+  // Called after a successful email change (notifies the old address)
+  sendEmailChanged: async (to, newEmail, lang?) => { /* ... */ },
+}
+```
+
+### Flow
+
+1. After registration, call `POST /auth/send-verification-email` (authenticated) — the library generates a 24-hour token, calls `updateEmailVerificationToken`, then fires `sendVerificationEmail`.
+2. The user clicks the link in their inbox; the link points to `GET /auth/verify-email?token=<token>` — the library calls `updateEmailVerified(userId, true)` and clears the token.
+
+```typescript
+// Example: send on registration
+app.post('/register', async (req, res) => {
+  const user = await userStore.create({ email: req.body.email, password: hashedPw });
+  // Log them in
+  const tokens = tokenService.generateTokenPair({ sub: user.id, email: user.email }, config);
+  tokenService.setTokenCookies(res, tokens, config);
+  // Trigger verification email (the library does this automatically via the auth router)
+  // or call the endpoint directly:
+  await fetch('/auth/send-verification-email', {
+    method: 'POST',
+    headers: { Cookie: `accessToken=${tokens.accessToken}` },
+  });
+  res.json({ success: true });
+});
+```
+
+## Change Password
+
+`POST /auth/change-password` — **authenticated** — lets users update their password without going through the forgot-password flow.
+
+**Request body:**
+```json
+{ "currentPassword": "OldP@ss1", "newPassword": "NewP@ss2" }
+```
+
+The endpoint verifies `currentPassword` against the stored bcrypt hash before applying the change. It returns `401` if the current password is wrong, or `400` for OAuth accounts that have no password set.
+
+```typescript
+// Client example (fetch)
+await fetch('/auth/change-password', {
+  method: 'POST',
+  credentials: 'include',         // include HttpOnly cookies
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ currentPassword: 'old', newPassword: 'new' }),
+});
+```
+
+No extra `IUserStore` methods are needed — `updatePassword` is already a required method.
+
+## Change Email
+
+The change-email flow sends a confirmation link to the new address before committing the update, preventing account hijacking.
+
+### IUserStore additions
+
+```typescript
+// Required to support /auth/change-email/request and /auth/change-email/confirm
+updateEmailChangeToken(userId, pendingEmail, token, expiry): Promise<void>
+updateEmail(userId, newEmail): Promise<void>
+findByEmailChangeToken(token): Promise<U | null>
+```
+
+### Flow
+
+1. Authenticated user calls `POST /auth/change-email/request` with `{ "newEmail": "new@example.com" }`.  
+   - The library checks the new address is not already in use.  
+   - A 1-hour token is generated, stored via `updateEmailChangeToken`, and a verification email is sent to the **new address**.
+2. User clicks the link; it points to `POST /auth/change-email/confirm` with `{ "token": "..." }`.  
+   - The library calls `updateEmail` (commits the change) and sends an email-changed notification to the **old address** via `sendEmailChanged`.
+
+```typescript
+// 1. Request change
+await fetch('/auth/change-email/request', {
+  method: 'POST',
+  credentials: 'include',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ newEmail: 'new@example.com' }),
+});
+
+// 2. Confirm (called from the link in the email)
+await fetch('/auth/change-email/confirm', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ token: tokenFromLink }),
+});
+```
+
+## Admin Panel
+
+`createAdminRouter` mounts a **self-contained admin panel** — both the REST API and a vanilla-JS UI — at any path you choose. No build step, no external UI dependencies.
+
+```typescript
+import { createAdminRouter } from 'node-auth';
+
+app.use('/admin', createAdminRouter(userStore, {
+  adminSecret: process.env.ADMIN_SECRET!,  // Bearer token required for all admin routes
+  sessionStore,   // optional — enables Sessions tab
+  rbacStore,      // optional — enables Roles & Permissions tab
+  tenantStore,    // optional — enables Tenants tab
+}));
+```
+
+Open `http://localhost:3000/admin/` in your browser, enter the admin secret, and you get a tabbed dashboard:
+
+| Tab | Requires | Features |
+|-----|----------|---------|
+| **Users** | `IUserStore.listUsers` | Paginated user table, delete user |
+| **Sessions** | `ISessionStore.getAllSessions` | All active sessions, revoke by handle |
+| **Roles & Permissions** | `IRolesPermissionsStore.getAllRoles` | List roles with permissions, create/delete roles |
+| **Tenants** | `ITenantStore.getAllTenants` | List tenants, create/delete tenants |
+
+Tabs that are not configured are hidden automatically.
+
+### Admin REST API
+
+All admin API endpoints require `Authorization: Bearer <adminSecret>`.
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/admin/api/ping` | Health check / auth verification |
+| `GET` | `/admin/api/users` | List users (`?limit=&offset=`) |
+| `GET` | `/admin/api/users/:id` | Get single user |
+| `DELETE` | `/admin/api/users/:id` | Delete user (requires `IUserStore.deleteUser`) |
+| `GET` | `/admin/api/sessions` | List all sessions (`?limit=&offset=`) |
+| `DELETE` | `/admin/api/sessions/:handle` | Revoke a session |
+| `GET` | `/admin/api/roles` | List all roles with permissions |
+| `POST` | `/admin/api/roles` | Create a 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 |
+
+> **Security note:** Mount the admin router behind a VPN or IP allow-list in production. The `adminSecret` is a single shared token — treat it like a root password.
 
 Auth routes should be rate-limited in production to prevent brute-force attacks. Pass an optional `rateLimiter` middleware to `createAuthRouter()`:
 
@@ -604,6 +774,273 @@ app.use('/auth', auth.router({ rateLimiter: limiter }));
 
 All sensitive endpoints (login, refresh, password reset, 2FA, magic links, SMS) will be protected.
 
+## Custom JWT Claims
+
+Inject arbitrary project-specific data into both the access and refresh JWTs by providing `buildTokenPayload` in `AuthConfig`. The returned object is **merged** on top of the standard `{ sub, email, role }` claims.
+
+```typescript
+import { AuthConfigurator, AuthConfig } from 'node-auth';
+
+const config: AuthConfig = {
+  accessTokenSecret: '...',
+  refreshTokenSecret: '...',
+  buildTokenPayload: (user) => ({
+    permissions: user.permissions,   // your extended user fields
+    tenantId:    user.tenantId,
+    plan:        user.plan,
+  }),
+};
+
+const auth = new AuthConfigurator(config, userStore);
+```
+
+After login the custom claims are available on `req.user` in any protected route:
+
+```typescript
+app.get('/protected', auth.middleware(), (req, res) => {
+  // req.user.tenantId, req.user.permissions, etc.
+  res.json(req.user);
+});
+```
+
+## User Metadata
+
+`IUserMetadataStore` is an **optional** interface for attaching arbitrary key/value metadata to users without altering `BaseUser` or your users table.
+
+```typescript
+import { IUserMetadataStore } from 'node-auth';
+
+export class MyUserMetadataStore implements IUserMetadataStore {
+  /** Return all metadata for a user; empty object when none exists. */
+  async getMetadata(userId: string): Promise<Record<string, unknown>> {
+    const row = await db('user_metadata').where({ userId }).first();
+    return row ? JSON.parse(row.data) : {};
+  }
+
+  /** Shallow-merge new key/value pairs into the existing metadata. */
+  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();
+  }
+
+  /** Remove all metadata for the user (e.g. on account deletion). */
+  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', onboarded: true });
+
+// Read them back
+const meta = await metaStore.getMetadata(userId);
+console.log(meta.theme); // 'dark'
+```
+
+## Roles & Permissions
+
+`IRolesPermissionsStore` is an **optional** interface for role-based access control (RBAC). It supports both single-tenant and multi-tenant applications via an optional `tenantId` parameter.
+
+```typescript
+import { IRolesPermissionsStore } from 'node-auth';
+
+export class MyRbacStore implements IRolesPermissionsStore {
+  // User ↔ Role
+  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[]> { /* ... */ }
+
+  // Role management
+  async createRole(role: string, permissions?: string[]): Promise<void> { /* ... */ }
+  async deleteRole(role: string): Promise<void> { /* ... */ }
+
+  // Role ↔ Permission
+  async addPermissionToRole(role: string, permission: string): Promise<void> { /* ... */ }
+  async removePermissionFromRole(role: string, permission: string): Promise<void> { /* ... */ }
+  async getPermissionsForRole(role: string): Promise<string[]> { /* ... */ }
+
+  // Convenience
+  async getPermissionsForUser(userId: string, tenantId?: string): Promise<string[]> { /* ... */ }
+  async userHasPermission(userId: string, permission: string, tenantId?: string): Promise<boolean> { /* ... */ }
+}
+```
+
+### Usage
+
+```typescript
+const rbac = new MyRbacStore();
+
+// Create roles with permissions
+await rbac.createRole('editor', ['posts:read', 'posts:write']);
+await rbac.createRole('admin',  ['posts:read', 'posts:write', 'users:manage']);
+
+// Assign a role to a user (optionally scoped to a tenant)
+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', req.user!.tenantId as string | undefined);
+  if (!allowed) return res.status(403).json({ error: 'Forbidden' });
+  // ... delete post
+});
+```
+
+### Combining with `buildTokenPayload`
+
+You can embed roles/permissions directly in the JWT so route guards do not need an async DB call:
+
+```typescript
+buildTokenPayload: async (user) => ({
+  roles:       await rbac.getRolesForUser(user.id),
+  permissions: await rbac.getPermissionsForUser(user.id),
+}),
+```
+
+## Session Management
+
+`ISessionStore` is an **optional** interface for device-aware session management — useful for "active sessions" screens where users can see and revoke individual devices.
+
+```typescript
+import { ISessionStore, SessionInfo } from 'node-auth';
+
+export class MySessionStore implements ISessionStore {
+  async createSession(info: Omit<SessionInfo, 'sessionHandle'>): Promise<SessionInfo> {
+    const sessionHandle = crypto.randomUUID();
+    await db('sessions').insert({ sessionHandle, ...info });
+    return { sessionHandle, ...info };
+  }
+  async getSession(sessionHandle: string): Promise<SessionInfo | null> {
+    return db('sessions').where({ sessionHandle }).first() ?? null;
+  }
+  async getSessionsForUser(userId: string, tenantId?: string): Promise<SessionInfo[]> {
+    return db('sessions').where({ userId, ...(tenantId ? { tenantId } : {}) });
+  }
+  async updateSessionLastActive(sessionHandle: string): Promise<void> {
+    await db('sessions').where({ sessionHandle }).update({ lastActiveAt: new Date() });
+  }
+  async revokeSession(sessionHandle: string): Promise<void> {
+    await db('sessions').where({ sessionHandle }).delete();
+  }
+  async revokeAllSessionsForUser(userId: string, tenantId?: string): Promise<void> {
+    await db('sessions').where({ userId, ...(tenantId ? { tenantId } : {}) }).delete();
+  }
+}
+```
+
+### Usage
+
+```typescript
+const sessions = new MySessionStore();
+
+// Create a session on login (combine with the auth router's login handler)
+const session = await sessions.createSession({
+  userId,
+  createdAt:  new Date(),
+  expiresAt:  new Date(Date.now() + 7 * 24 * 60 * 60 * 1000),
+  userAgent:  req.headers['user-agent'],
+  ipAddress:  req.ip,
+});
+
+// List active sessions for a "Manage devices" page
+app.get('/sessions', auth.middleware(), async (req, res) => {
+  const list = await sessions.getSessionsForUser(req.user!.sub);
+  res.json(list);
+});
+
+// Revoke a specific session
+app.delete('/sessions/:handle', auth.middleware(), async (req, res) => {
+  await sessions.revokeSession(req.params.handle);
+  res.json({ success: true });
+});
+```
+
+### `SessionInfo` model
+
+```typescript
+interface SessionInfo {
+  sessionHandle: string;       // Unique opaque identifier
+  userId:        string;
+  tenantId?:     string;       // Optional tenant scope
+  createdAt:     Date;
+  expiresAt:     Date;
+  lastActiveAt?: Date;         // Bumped on each authenticated request
+  userAgent?:    string;
+  ipAddress?:    string;
+  data?:         Record<string, unknown>; // Any extra device/context data
+}
+```
+
+## Multi-Tenancy
+
+`ITenantStore` is an **optional** interface for applications that serve multiple independent tenants (organisations, workspaces, teams).
+
+```typescript
+import { ITenantStore, Tenant } from 'node-auth';
+
+export class MyTenantStore implements ITenantStore {
+  // Tenant CRUD
+  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> { /* ... */ }
+
+  // User ↔ Tenant membership
+  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[]> { /* ... */ }
+}
+```
+
+### Usage
+
+```typescript
+const tenants = new MyTenantStore();
+
+// Onboarding: create a tenant and assign the first user as owner
+const tenant = await tenants.createTenant({ name: 'Acme Corp', isActive: true });
+await tenants.associateUserWithTenant(userId, tenant.id);
+
+// Inject tenantId into the JWT via buildTokenPayload.
+// For users that belong to a single tenant this works directly.
+// For users with multiple tenants, embed the full list and let the
+// client pass an `X-Tenant-ID` header that is validated per-request.
+buildTokenPayload: async (user) => ({
+  tenants: (await tenants.getTenantsForUser(user.id)).map(t => t.id),
+}),
+
+// Guard: ensure user belongs to the requested tenant
+app.get('/tenants/:id/data', auth.middleware(), async (req, res) => {
+  const userTenants = await tenants.getTenantsForUser(req.user!.sub);
+  if (!userTenants.find(t => t.id === req.params.id)) {
+    return res.status(403).json({ error: 'Forbidden' });
+  }
+  // ... return tenant data
+});
+```
+
+### `Tenant` model
+
+```typescript
+interface Tenant {
+  id:        string;                      // Unique identifier (slug, UUID, etc.)
+  name:      string;
+  isActive?: boolean;                     // Defaults to true
+  config?:   Record<string, unknown>;    // Per-tenant settings (branding, feature flags, etc.)
+  createdAt?: Date;
+}
+```
+
 ## Building
 
 ```bash
@@ -621,16 +1058,47 @@ npm run test:coverage
 
 ```
 src/
-├── interfaces/          # IUserStore, ITokenStore, IAuthStrategy
-├── models/              # BaseUser, TokenPair, AuthConfig, AuthError
+├── interfaces/          # IUserStore, ITokenStore, IAuthStrategy,
+│                        # IUserMetadataStore, IRolesPermissionsStore,
+│                        # ISessionStore, ITenantStore
+├── models/              # BaseUser, TokenPair, AuthConfig, AuthError,
+│                        # SessionInfo, Tenant
 ├── abstract/            # BaseAuthStrategy, BaseOAuthStrategy
 ├── strategies/          # Local, Google, GitHub, MagicLink, SMS, TOTP
-├── services/            # TokenService, PasswordService, SmsService
+├── services/            # TokenService, PasswordService, SmsService, MailerService
 ├── middleware/          # createAuthMiddleware()
-├── router/              # createAuthRouter() – full Express router
+├── router/              # createAuthRouter() – auth endpoints
+│                        # createAdminRouter() – admin panel UI + REST API
 └── auth-configurator.ts # Main entry point
 ```
 
+## Comparison with SuperTokens
+
+The table below maps SuperTokens recipes to node-auth equivalents so you can evaluate feature coverage for your project.
+
+| SuperTokens Feature | node-auth equivalent | Notes |
+|---------------------|---------------------|-------|
+| EmailPassword recipe | `LocalStrategy` + `POST /auth/login` | Full email/password auth with bcrypt |
+| ThirdParty / OAuth | `GoogleStrategy`, `GithubStrategy` | Extend abstract strategies for any provider |
+| Passwordless (magic link) | `MagicLinkStrategy` | Email token via built-in mailer or callback |
+| Passwordless (OTP via SMS) | `SmsStrategy` | SMS code via configurable HTTP endpoint |
+| TOTP 2FA | `TotpStrategy` | Authenticator-app compatible; QR code included |
+| Session management | `ISessionStore` _(optional)_ | Device-aware sessions; list & revoke |
+| User Roles | `IRolesPermissionsStore` _(optional)_ | Full RBAC with tenant scoping |
+| User Metadata | `IUserMetadataStore` _(optional)_ | Arbitrary key/value store per user |
+| Multi-tenancy | `ITenantStore` _(optional)_ | Tenant CRUD + user membership |
+| Custom JWT claims | `buildTokenPayload` callback | Inject any data into access & refresh tokens |
+| Database agnostic | `IUserStore` interface | One interface, any DB |
+| Rate limiting | `rateLimiter` option in `router()` | Pass any Express middleware |
+| Email verification | `POST /send-verification-email` + `GET /verify-email` | Token-based, 24 h expiry, built-in templates |
+| Change password | `POST /change-password` | Authenticated; verifies current password |
+| Change email | `POST /change-email/request` + `POST /change-email/confirm` | Verification to new address, notification to old |
+| Admin dashboard UI | `createAdminRouter()` | Self-contained UI + REST API, Bearer-token protected |
+| Account linking | _(not built-in)_ | Link OAuth profiles in your `IUserStore.create` |
+| Attack protection | _(not built-in)_ | Use `rateLimiter` + external WAF |
+
+> **Roadmap ideas:** account-linking helpers, email-verification enforcement middleware, SCIM provisioning.
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nik2208/node-auth",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Database-agnostic JWT authentication library for Node.js",
   "main": "dist/index.js",
   "scripts": {