@mostajs/auth

Reusable authentication and RBAC module — NextAuth + Users + Roles + Permissions.

Part of the @mosta suite.

Installation

npm install @mostajs/auth @mostajs/orm bcryptjs next-auth@beta

Quick Start

1. Register schemas

import { registerSchemas } from '@mostajs/orm'
import { UserSchema, RoleSchema, PermissionSchema, PermissionCategorySchema } from '@mostajs/auth'

registerSchemas([UserSchema, RoleSchema, PermissionSchema, PermissionCategorySchema])

2. Create auth handlers

import { createAuthHandlers, createAuthChecks } from '@mostajs/auth'

const ROLE_PERMISSIONS = {
  admin: ['*'],
  editor: ['dashboard:view', 'user:view'],
}

const { handlers, auth, signIn, signOut } = createAuthHandlers(ROLE_PERMISSIONS)
const { checkAuth, checkPermission } = createAuthChecks(auth, ROLE_PERMISSIONS)

export { handlers, auth, checkAuth, checkPermission }

3. Protect API routes

export async function GET(req: Request) {
  const { error, session } = await checkPermission('user:view')
  if (error) return error
  // ...
}

4. Client-side permission guard

import PermissionGuard from '@mostajs/auth/components/PermissionGuard'

<PermissionGuard permissions={['user:delete']}>
  <DeleteButton />
</PermissionGuard>

API Reference

| 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 |

Related Packages

• @mostajs/orm — Multi-dialect ORM (required)
• @mostajs/audit — Audit logging

License

MIT — © 2025 Dr Hamid MADANI [email protected]