CH 3Basic

Identity, Authentication & Authorization (IAM)

Every person on NexusOne gets a permanent NexusOne ID, authenticates via email/password or mobile OTP, and is authorized through a 16-role hierarchy enforced in-memory on every request. Sessions are stateless JWTs with revocation support, passwords are bcrypt-hashed, and every security-relevant event is written to an IAM audit log. This entire chapter is Basic tier — there are no AI-gated features here.

Basic Tier Features

Basic

NexusOne ID & Account Status

Basic

Every user gets a permanent, sequential nexusOneId (NX-000000001…) on creation — globally unique, never reused
accountStatus lifecycle: pending → active → suspended / archived, enforced in both the login controller and the protect middleware
Account locking: loginAttempts + lockUntil block login after repeated failures; admins unlock via PATCH /api/users/:id/unlock

Login Methods

Basic

Email + password login with bcrypt verification, returning a JWT access token and user object
Students can log in with their NexusOne ID or Student NexusOne ID (e.g. NX-STU-000001) instead of email — useful for admin-admitted students who don't have a real email on file
Mobile OTP login (primary for parents/students) — POST /api/auth/otp/request then /api/auth/otp/verify
Google OAuth and Microsoft OAuth are specified but not yet implemented (Planned)

Session & Token Management

Basic

Stateless JWT auth: short-lived access token + refresh token via POST /api/auth/refresh
Logout revokes the token's jti in the RevokedToken collection so it cannot be reused before expiry
"Revoke all sessions" invalidates every existing token at once by bumping passwordChangedAt — the protect middleware rejects any token issued before that timestamp
Web: /dashboard/profile/security page · Mobile: (student)/sessions.tsx screen

Password Security

Basic

bcryptjs hashing at 12 salt rounds; a pre-save guard prevents double-hashing an already-hashed password
Reset tokens are crypto.randomBytes(32), SHA-256 hashed in the database, and expire after 1 hour
changedPasswordAfter() invalidates any JWT issued before the last password change
Own-password change via PATCH /api/auth/change-password

Role-Based Access Control

Basic

11 roles in the User.role enum: platform_admin, super_admin, admin, teacher, student, parent, accountant, librarian, facilities_admin, driver, alumni
authorize(...roles) middleware calls hasRole() against a static ROLE_HIERARCHY object — higher roles automatically satisfy lower-role route requirements, with zero database lookups
belongsToSchool() / requireSchool() / ownerOrAdmin enforce tenant and record-level scoping on top of the role check

IAM Audit Log

Basic

AuditLog captures login success/failure, logout, password changes, account status changes, session revocations, and unlocks
GET /api/auth/audit-log (admin and above) returns a paginated, filterable trail
Web: /dashboard/admin/iam viewer with action-type labels and locked-account management · Mobile: (admin)/iam-security.tsx

Profile & Preferences

Basic

Profile fields: name, phone, address, profile photo (Cloudinary) via PATCH /api/users/me and /api/users/me/photo
Per-user preferences sub-document: language, theme, timezone, and per-channel notification toggles (email/push/whatsapp/sms)
Web: /dashboard/profile and /dashboard/profile/preferences · Mobile: (student)/profile.tsx and (student)/preferences.tsx

Still Planned

Roadmap — Not Yet Implemented

Basic

Google OAuth and Microsoft OAuth login
Platform Admin / Super Admin impersonation (specified, time-limited and audited, but no code path exists yet)
Multi-Factor Authentication (TOTP) and WhatsApp-based identity verification
OpenID Connect / SAML SSO for enterprise schools

API Reference — Chapter 3

Authentication (/api/auth) — all rate-limited via authLimiter, 10 req/15 min

POST/api/auth/register

POST/api/auth/login

Email, NexusOne ID, or Student NexusOne ID + password login — returns JWT access token + user object

POST/api/auth/otp/request

Request a mobile OTP for login

POST/api/auth/otp/verify

Verify OTP and issue a session token

POST/api/auth/forgot-password

Send password reset email (3/hour limiter)

POST/api/auth/reset-password

Reset password via emailed token

POST/api/auth/refresh

Refresh an access token

GET/api/auth/me

Get the current authenticated user

POST/api/auth/logout

Revoke the current token and end the session

PATCH/api/auth/change-password

Change own password

POST/api/auth/revoke-all-sessions

Invalidate every existing token by bumping passwordChangedAt

GET/api/auth/audit-log

IAM audit trail (admin and above)

Profile & Preferences (/api/users)

PATCH/api/users/me

Update own name, phone, address

PATCH/api/users/me/photo

Upload profile photo (Cloudinary)

GET/api/users/me/preferences

Get language, theme, timezone, notification preferences

PATCH/api/users/me/preferences

Update preferences

User & Account Management (/api/users, admin)

GET/api/users

List users in school (admin, super_admin)

GET/api/users/:id

Get a user (owner or admin)

PATCH/api/users/:id

Update a user; admins may also change role/isActive/verification flags

PATCH/api/users/:id/status

Suspend, activate, or archive a user account

PATCH/api/users/:id/unlock

Clear failed-login lock on an account

POST/api/users/invite

Invite a new user by email with a temporary password

DELETE/api/users/:id

Deactivate a user (admin)

Platform Admin — Cross-Tenant User Management

GET/api/platform-admin/users

(via superAdminController) all users across all schools

POST/api/platform-admin/users/:id/schools

Grant a user multi-school access

DELETE/api/platform-admin/users/:id/schools/:schoolId

Revoke a user's access to a school

Frontend Pages

Path	Role	Description	Tier
/login	Public	Email or NX ID + password login with role-based dashboard redirect; links to OTP login and school registration	Basic
/otp-login	Public	Mobile OTP login flow with 6-digit input and resend countdown	Basic
/register	Public	New user account registration	Basic
/forgot-password	Public	Email-based password reset request	Basic
/dashboard/profile	All authenticated roles	NexusOne ID, account details, profile photo	Basic
/dashboard/profile/security	All authenticated roles	Change password, revoke all sessions	Basic
/dashboard/profile/preferences	All authenticated roles	Language, theme, timezone, notification toggles	Basic
/dashboard/admin/iam	Admin	IAM audit log viewer, locked-account management	Basic
/dashboard/admin/users	Admin	User list, role and status management, invites	Basic

Mobile Screens

(auth)/login

Email or NX ID + password login with Face ID / fingerprint biometric unlock

Basic

(auth)/otp-login

Mobile number + 6-digit OTP with resend countdown

Basic

(auth)/forgot-password

Email-based password reset

Basic

(student)/profile

NexusOne ID, account info, edit name, change password (shared across roles)

Basic

(student)/sessions

Active session info, sign out this device, revoke all

Basic

(student)/preferences

Language, theme, timezone, notification toggles

Basic

(admin)/iam-security

Audit log viewer and locked-account management

Basic

← Chapter 2: Business Architecture Chapter 4: Organization, Roles & Permissions →

Back to Docs →