@mostajs/auth 2.0.2 → 2.1.0

package/README.md

@@ -1,87 +1,64 @@
 # @mostajs/auth
 
-> Reusable authentication and RBAC module — NextAuth + Users + Roles + Permissions.
+> NextAuth authentication with RBAC — delegates user management to @mostajs/rbac.
+> Author: Dr Hamid MADANI drmdh@msn.com
 
-[![npm version](https://img.shields.io/npm/v/@mostajs/auth.svg)](https://www.npmjs.com/package/@mostajs/auth)
-[![license](https://img.shields.io/npm/l/@mostajs/auth.svg)](LICENSE)
-
-Part of the [@mosta suite](https://mostajs.dev).
-
----
-
-## Installation
+## Install
 
 ```bash
-npm install @mostajs/auth @mostajs/orm bcryptjs next-auth@beta
+npm install @mostajs/auth @mostajs/rbac next-auth@5.0.0-beta.25
 ```
 
-## Quick Start
-
-### 1. Register schemas
-
-```typescript
-import { registerSchemas } from '@mostajs/orm'
-import { UserSchema, RoleSchema, PermissionSchema, PermissionCategorySchema } from '@mostajs/auth'
-
-registerSchemas([UserSchema, RoleSchema, PermissionSchema, PermissionCategorySchema])
-```
+## How to Use
 
-### 2. Create auth handlers
+### 1. Create Auth Handlers
 
 ```typescript
-import { createAuthHandlers, createAuthChecks } from '@mostajs/auth'
+// src/lib/auth.ts
+import { createAuthHandlers } from '@mostajs/auth/server'
 
 const ROLE_PERMISSIONS = {
   admin: ['*'],
-  editor: ['dashboard:view', 'user:view'],
+  agent: ['client:view', 'ticket:create'],
 }
 
-const { handlers, auth, signIn, signOut } = createAuthHandlers(ROLE_PERMISSIONS)
-const { checkAuth, checkPermission } = createAuthChecks(auth, ROLE_PERMISSIONS)
+const { handlers, auth, signIn, signOut } = createAuthHandlers(ROLE_PERMISSIONS, {
+  pages: { signIn: '/login', error: '/login' },
+})
 
-export { handlers, auth, checkAuth, checkPermission }
+export { handlers, auth, signIn, signOut }
 ```
 
-### 3. Protect API routes
+### 2. Auth Checks in API Routes
 
 ```typescript
-export async function GET(req: Request) {
-  const { error, session } = await checkPermission('user:view')
-  if (error) return error
-  // ...
-}
-```
-
-### 4. Client-side permission guard
+import { createAuthChecks } from '@mostajs/auth/server'
+import { auth } from '@/lib/auth'
 
-```tsx
-import PermissionGuard from '@mostajs/auth/components/PermissionGuard'
+const { checkAuth, checkPermission } = createAuthChecks(auth, ROLE_PERMISSIONS)
 
-<PermissionGuard permissions={['user:delete']}>
-  <DeleteButton />
-</PermissionGuard>
+// In API route:
+const { error } = await checkPermission('client:view')
+if (error) return error
 ```
 
-## API Reference
+### 3. Middleware
 
-| Export | Description |
-|--------|-------------|
-| `createAuthHandlers()` | NextAuth configuration factory |
-| `createAuthChecks()` | Server-side `checkAuth()` / `checkPermission()` |
-| `createAuthMiddleware()` | Next.js middleware for route protection |
-| `seedRBAC()` | Idempotent seed of categories, permissions, roles |
-| `hashPassword()` / `comparePassword()` | bcryptjs wrappers |
-| `hasPermission()` / `getPermissionsForRole()` | Client-safe permission helpers |
-| `usePermissions()` | React hook for permission checking |
-| `PermissionGuard` | Conditional render component |
-| `SessionProvider` | NextAuth session wrapper |
-| `UserRepository` / `RoleRepository` / `PermissionRepository` | Database repositories |
+```typescript
+import { createAuthMiddleware } from '@mostajs/auth/server'
+export default createAuthMiddleware({ publicPaths: ['/login'], protectedPrefixes: ['/dashboard'] })
+```
 
-## Related Packages
+### 4. Create Admin (delegates to rbac)
 
-- [@mostajs/orm](https://www.npmjs.com/package/@mostajs/orm) — Multi-dialect ORM (required)
-- [@mostajs/audit](https://www.npmjs.com/package/@mostajs/audit) — Audit logging
+```typescript
+import { createAdmin } from '@mostajs/auth/server'
+await createAdmin({ email: 'admin@test.com', password: 'Admin123!', firstName: 'Admin', lastName: 'Test' })
+```
 
-## License
+### 5. Client Components
 
-MIT — © 2025 Dr Hamid MADANI <drmdh@msn.com>
+```typescript
+import { usePermissions } from '@mostajs/auth'
+import { PermissionGuard, SessionProvider } from '@mostajs/auth'
+```

package/dist/index.d.ts

@@ -5,3 +5,8 @@ export { default as PermissionGuard } from './components/PermissionGuard';
 export { default as SessionProvider } from './components/SessionProvider';
 export type { UserDTO, RoleDTO, PermissionDTO, PermissionCategoryDTO, PermissionDefinition, RoleDefinition, CategoryDefinition, } from '@mostajs/rbac';
 export type { MostaAuthConfig } from './types/index';
+export type { RegistrationConfig } from './lib/registration';
+export type { VerificationConfig } from './lib/email-verification';
+export type { PasswordResetConfig } from './lib/password-reset';
+export type { ApiKeyProviderConfig } from './lib/apikey-provider';
+export type { SessionEnrichmentConfig } from './lib/session-enrichment';

package/dist/lib/apikey-provider.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Creates a NextAuth credentials provider that authenticates via API key
+ * instead of email/password. Used for programmatic access.
+ */
+export interface ApiKeyProviderConfig {
+    /** Function to resolve API key (from @mostajs/api-keys) */
+    resolveApiKey: (rawKey: string) => Promise<any | null>;
+    /** Function to load account by ID */
+    loadAccount: (accountId: string) => Promise<any | null>;
+    /** Function to get permissions for account */
+    getPermissions?: (account: any) => Promise<string[]>;
+}
+export declare function createApiKeyProvider(config: ApiKeyProviderConfig): {
+    id: string;
+    name: string;
+    type: "credentials";
+    credentials: {
+        apiKey: {
+            label: string;
+            type: string;
+        };
+    };
+    authorize(credentials: any): Promise<{
+        id: any;
+        email: any;
+        name: any;
+        role: any;
+        roles: any[];
+        permissions: string[];
+        apiKeyId: any;
+    } | null>;
+};

package/dist/lib/apikey-provider.js

@@ -0,0 +1,34 @@
+// @mostajs/auth — API key authentication provider for NextAuth
+// Author: Dr Hamid MADANI drmdh@msn.com
+export function createApiKeyProvider(config) {
+    return {
+        id: 'api-key',
+        name: 'API Key',
+        type: 'credentials',
+        credentials: {
+            apiKey: { label: 'API Key', type: 'text' },
+        },
+        async authorize(credentials) {
+            if (!credentials?.apiKey)
+                return null;
+            const apiKey = await config.resolveApiKey(credentials.apiKey);
+            if (!apiKey)
+                return null;
+            const account = await config.loadAccount(apiKey.accountId);
+            if (!account || account.banned)
+                return null;
+            const permissions = config.getPermissions
+                ? await config.getPermissions(account)
+                : [];
+            return {
+                id: account.id ?? account._id,
+                email: account.email,
+                name: account.name,
+                role: account.role ?? 'user',
+                roles: [account.role ?? 'user'],
+                permissions,
+                apiKeyId: apiKey.id ?? apiKey._id,
+            };
+        },
+    };
+}

package/dist/lib/email-verification.d.ts

@@ -0,0 +1,24 @@
+export interface VerificationConfig {
+    /** Function to update account with verify token */
+    updateAccount: (id: string, data: any) => Promise<void>;
+    /** Function to find account by verify token */
+    findByVerifyToken: (token: string) => Promise<any | null>;
+    /** Function to send verification email */
+    sendEmail?: (to: string, token: string, verifyUrl: string) => Promise<void>;
+    /** Base URL for verify link */
+    verifyBaseUrl: string;
+    /** Token expiry in hours (default 24) */
+    tokenExpiryHours?: number;
+}
+export declare function generateVerifyToken(): string;
+export declare function createVerificationHandlers(config: VerificationConfig): {
+    sendVerification: (accountId: string, email: string) => Promise<{
+        token: string;
+        url: string;
+    }>;
+    verifyEmail: (token: string) => Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    generateVerifyToken: typeof generateVerifyToken;
+};

package/dist/lib/email-verification.js

@@ -0,0 +1,38 @@
+// @mostajs/auth — Email verification
+// Author: Dr Hamid MADANI drmdh@msn.com
+import crypto from 'node:crypto';
+export function generateVerifyToken() {
+    return crypto.randomBytes(32).toString('hex');
+}
+export function createVerificationHandlers(config) {
+    /** POST /auth/send-verification — Send verification email */
+    async function sendVerification(accountId, email) {
+        const token = generateVerifyToken();
+        const expiresAt = new Date(Date.now() + (config.tokenExpiryHours ?? 24) * 3600000).toISOString();
+        await config.updateAccount(accountId, { verifyToken: token, verifyTokenExpiresAt: expiresAt });
+        const url = `${config.verifyBaseUrl}?token=${token}`;
+        if (config.sendEmail) {
+            await config.sendEmail(email, token, url);
+        }
+        return { token, url };
+    }
+    /** GET /auth/verify?token=xxx — Verify email */
+    async function verifyEmail(token) {
+        if (!token)
+            return { ok: false, error: 'Token required' };
+        const account = await config.findByVerifyToken(token);
+        if (!account)
+            return { ok: false, error: 'Invalid or expired token' };
+        // Check expiry
+        if (account.verifyTokenExpiresAt && new Date(account.verifyTokenExpiresAt) < new Date()) {
+            return { ok: false, error: 'Token expired' };
+        }
+        await config.updateAccount(account.id ?? account._id, {
+            verified: true,
+            verifyToken: null,
+            verifyTokenExpiresAt: null,
+        });
+        return { ok: true };
+    }
+    return { sendVerification, verifyEmail, generateVerifyToken };
+}

package/dist/lib/password-reset.d.ts

@@ -0,0 +1,26 @@
+export interface PasswordResetConfig {
+    /** Find account by email */
+    findByEmail: (email: string) => Promise<any | null>;
+    /** Find account by reset token */
+    findByResetToken: (token: string) => Promise<any | null>;
+    /** Update account data */
+    updateAccount: (id: string, data: any) => Promise<void>;
+    /** Send reset email */
+    sendEmail?: (to: string, token: string, resetUrl: string) => Promise<void>;
+    /** Base URL for reset link */
+    resetBaseUrl: string;
+    /** Token expiry in hours (default 1) */
+    tokenExpiryHours?: number;
+}
+export declare function generateResetToken(): string;
+export declare function createPasswordResetHandlers(config: PasswordResetConfig): {
+    forgotPassword: (email: string) => Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    resetPassword: (token: string, newPassword: string) => Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    generateResetToken: typeof generateResetToken;
+};

package/dist/lib/password-reset.js

@@ -0,0 +1,49 @@
+// @mostajs/auth — Password reset
+// Author: Dr Hamid MADANI drmdh@msn.com
+import crypto from 'node:crypto';
+import { hashPassword } from './password.js';
+export function generateResetToken() {
+    return crypto.randomBytes(32).toString('hex');
+}
+export function createPasswordResetHandlers(config) {
+    /** POST /auth/forgot-password — Request password reset */
+    async function forgotPassword(email) {
+        const account = await config.findByEmail(email);
+        if (!account) {
+            // Don't reveal if email exists
+            return { ok: true };
+        }
+        const token = generateResetToken();
+        const expiresAt = new Date(Date.now() + (config.tokenExpiryHours ?? 1) * 3600000).toISOString();
+        await config.updateAccount(account.id ?? account._id, {
+            resetToken: token,
+            resetTokenExpiresAt: expiresAt,
+        });
+        const url = `${config.resetBaseUrl}?token=${token}`;
+        if (config.sendEmail) {
+            await config.sendEmail(email, token, url);
+        }
+        return { ok: true };
+    }
+    /** POST /auth/reset-password — Reset password with token */
+    async function resetPassword(token, newPassword) {
+        if (!token || !newPassword)
+            return { ok: false, error: 'Token and new password required' };
+        if (newPassword.length < 8)
+            return { ok: false, error: 'Password must be at least 8 characters' };
+        const account = await config.findByResetToken(token);
+        if (!account)
+            return { ok: false, error: 'Invalid or expired token' };
+        if (account.resetTokenExpiresAt && new Date(account.resetTokenExpiresAt) < new Date()) {
+            return { ok: false, error: 'Token expired' };
+        }
+        const hashed = await hashPassword(newPassword);
+        await config.updateAccount(account.id ?? account._id, {
+            password: hashed,
+            resetToken: null,
+            resetTokenExpiresAt: null,
+        });
+        return { ok: true };
+    }
+    return { forgotPassword, resetPassword, generateResetToken };
+}

package/dist/lib/registration.d.ts

@@ -0,0 +1,18 @@
+export interface RegistrationConfig {
+    /** Function to create account in DB (returns created account) */
+    createAccount: (data: {
+        email: string;
+        name: string;
+        password: string;
+        role?: string;
+    }) => Promise<any>;
+    /** Function to check if email already exists */
+    findByEmail: (email: string) => Promise<any | null>;
+    /** Default role for new users */
+    defaultRole?: string;
+    /** Default plan slug for new subscription */
+    defaultPlan?: string;
+    /** Called after successful registration */
+    onRegistered?: (account: any) => Promise<void>;
+}
+export declare function createRegistrationHandler(config: RegistrationConfig): (req: Request) => Promise<Response>;

package/dist/lib/registration.js

@@ -0,0 +1,30 @@
+// @mostajs/auth — Registration handler
+// Author: Dr Hamid MADANI drmdh@msn.com
+import { hashPassword } from './password.js';
+export function createRegistrationHandler(config) {
+    return async function POST(req) {
+        const body = await req.json();
+        if (!body.email || !body.name || !body.password) {
+            return Response.json({ error: 'email, name, and password are required' }, { status: 400 });
+        }
+        if (body.password.length < 8) {
+            return Response.json({ error: 'Password must be at least 8 characters' }, { status: 400 });
+        }
+        // Check duplicate
+        const existing = await config.findByEmail(body.email);
+        if (existing) {
+            return Response.json({ error: 'Email already registered' }, { status: 409 });
+        }
+        const hashed = await hashPassword(body.password);
+        const account = await config.createAccount({
+            email: body.email,
+            name: body.name,
+            password: hashed,
+            role: config.defaultRole ?? 'user',
+        });
+        if (config.onRegistered) {
+            await config.onRegistered(account);
+        }
+        return Response.json({ ok: true, id: account.id ?? account._id }, { status: 201 });
+    };
+}

package/dist/lib/session-enrichment.d.ts

@@ -0,0 +1,16 @@
+export interface SessionEnrichmentConfig {
+    /** Load subscription for account */
+    loadSubscription?: (accountId: string) => Promise<any | null>;
+    /** Load plan by ID */
+    loadPlan?: (planId: string) => Promise<any | null>;
+}
+/**
+ * Enrich a JWT token with plan and subscription data.
+ * Call this in the NextAuth jwt callback.
+ */
+export declare function enrichTokenWithPlan(token: any, config: SessionEnrichmentConfig): Promise<any>;
+/**
+ * Copy plan data from token to session.
+ * Call this in the NextAuth session callback.
+ */
+export declare function enrichSessionWithPlan(session: any, token: any): any;

package/dist/lib/session-enrichment.js

@@ -0,0 +1,47 @@
+// @mostajs/auth — Session enrichment with plan/subscription data
+// Author: Dr Hamid MADANI drmdh@msn.com
+/**
+ * Enrich a JWT token with plan and subscription data.
+ * Call this in the NextAuth jwt callback.
+ */
+export async function enrichTokenWithPlan(token, config) {
+    if (!config.loadSubscription || !config.loadPlan)
+        return token;
+    if (!token.sub)
+        return token;
+    try {
+        const sub = await config.loadSubscription(token.sub);
+        if (sub) {
+            token.subscriptionStatus = sub.status;
+            token.subscriptionId = sub.id ?? sub._id;
+            const planId = sub.plan ?? sub.planId;
+            if (planId) {
+                const plan = await config.loadPlan(planId);
+                if (plan) {
+                    token.planSlug = plan.slug;
+                    token.planName = plan.name;
+                    token.planLimits = typeof plan.limits === 'string' ? JSON.parse(plan.limits) : plan.limits;
+                }
+            }
+        }
+    }
+    catch {
+        // Don't break auth if plan loading fails
+    }
+    return token;
+}
+/**
+ * Copy plan data from token to session.
+ * Call this in the NextAuth session callback.
+ */
+export function enrichSessionWithPlan(session, token) {
+    if (token.planSlug)
+        session.user.planSlug = token.planSlug;
+    if (token.planName)
+        session.user.planName = token.planName;
+    if (token.planLimits)
+        session.user.planLimits = token.planLimits;
+    if (token.subscriptionStatus)
+        session.user.subscriptionStatus = token.subscriptionStatus;
+    return session;
+}

package/dist/server.d.ts

@@ -10,3 +10,13 @@ export { createAdmin } from '@mostajs/rbac/lib/create-admin';
 export type { CreateAdminOptions, CreateAdminResult } from '@mostajs/rbac/lib/create-admin';
 export { getSchemas, moduleInfo } from '@mostajs/rbac/lib/module-info';
 export { UserRepository, RoleRepository, PermissionRepository, PermissionCategoryRepository } from '@mostajs/rbac/server';
+export { createRegistrationHandler } from './lib/registration';
+export type { RegistrationConfig } from './lib/registration';
+export { createVerificationHandlers, generateVerifyToken } from './lib/email-verification';
+export type { VerificationConfig } from './lib/email-verification';
+export { createPasswordResetHandlers, generateResetToken } from './lib/password-reset';
+export type { PasswordResetConfig } from './lib/password-reset';
+export { createApiKeyProvider } from './lib/apikey-provider';
+export type { ApiKeyProviderConfig } from './lib/apikey-provider';
+export { enrichTokenWithPlan, enrichSessionWithPlan } from './lib/session-enrichment';
+export type { SessionEnrichmentConfig } from './lib/session-enrichment';

package/dist/server.js

@@ -17,3 +17,13 @@ export { createAdmin } from '@mostajs/rbac/lib/create-admin';
 export { getSchemas, moduleInfo } from '@mostajs/rbac/lib/module-info';
 // Repositories (re-export from rbac/server)
 export { UserRepository, RoleRepository, PermissionRepository, PermissionCategoryRepository } from '@mostajs/rbac/server';
+// Registration
+export { createRegistrationHandler } from './lib/registration';
+// Email verification
+export { createVerificationHandlers, generateVerifyToken } from './lib/email-verification';
+// Password reset
+export { createPasswordResetHandlers, generateResetToken } from './lib/password-reset';
+// API key provider
+export { createApiKeyProvider } from './lib/apikey-provider';
+// Session enrichment
+export { enrichTokenWithPlan, enrichSessionWithPlan } from './lib/session-enrichment';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mostajs/auth",
-  "version": "2.0.2",
+  "version": "2.1.0",
   "description": "Authentication — NextAuth, password hashing, session management",
   "author": "Dr Hamid MADANI <drmdh@msn.com>",
   "license": "MIT",
@@ -62,6 +62,31 @@
       "types": "./dist/register.d.ts",
       "import": "./dist/register.js",
       "default": "./dist/register.js"
+    },
+    "./lib/registration": {
+      "types": "./dist/lib/registration.d.ts",
+      "import": "./dist/lib/registration.js",
+      "default": "./dist/lib/registration.js"
+    },
+    "./lib/email-verification": {
+      "types": "./dist/lib/email-verification.d.ts",
+      "import": "./dist/lib/email-verification.js",
+      "default": "./dist/lib/email-verification.js"
+    },
+    "./lib/password-reset": {
+      "types": "./dist/lib/password-reset.d.ts",
+      "import": "./dist/lib/password-reset.js",
+      "default": "./dist/lib/password-reset.js"
+    },
+    "./lib/apikey-provider": {
+      "types": "./dist/lib/apikey-provider.d.ts",
+      "import": "./dist/lib/apikey-provider.js",
+      "default": "./dist/lib/apikey-provider.js"
+    },
+    "./lib/session-enrichment": {
+      "types": "./dist/lib/session-enrichment.d.ts",
+      "import": "./dist/lib/session-enrichment.js",
+      "default": "./dist/lib/session-enrichment.js"
     }
   },
   "files": [