Jadu Auth (Backend)

Central authentication server for Scenarix applications. Handles user registration, login, session management, email verification (OTP), SMS OTP login, password reset, and RBAC (apps, roles, permissions).

Tech Stack

• Runtime: Node.js with TypeScript
• Framework: Express.js v5
• Database: MongoDB (native driver)
• Auth: Better Auth with JWT plugin (EdDSA), session (bearer) and admin plugins
• Validation: Zod
• API docs: OpenAPI 3.0 + Swagger UI

Quick Start

1. Clone and install

cd jadu-auth-be
npm install

1. Environment

Copy .env.example to .env and set at least:

• PORT – server port (default 8084)
• MONGODB_URI_JADU_AUTH – MongoDB connection string
• BETTER_AUTH_SECRET – secret key (32+ characters); never commit
• BETTER_AUTH_URL – base URL of this server (e.g. http://localhost:8084)
• TRUSTED_ORIGINS – comma-separated allowed origins (e.g. frontend URL)

See .env.example for mail (SES/SMTP), SMS OTP (Twilio), email verification, and password reset options.

1. Run

npm run dev

Server: http://localhost:8084
API docs: http://localhost:8084/api-docs

Main Endpoints

Area	Examples
Auth	POST /api/auth/signup, POST /api/auth/login, POST /api/auth/logout, POST /api/auth/refresh, GET /api/auth/me
Password	POST /api/auth/forgot-password, POST /api/auth/reset-password, POST /api/auth/change-password
Email verification	POST /api/auth/send-verification-email, POST /api/auth/verify-email
Sessions	GET /api/auth/sessions, DELETE /api/auth/sessions/:sessionToken
JWKS	GET /.well-known/jwks (for JWT verification by other services)
Admin	GET/PUT /api/admin/users, GET /api/admin/users/:userId (admin role required)
RBAC	GET/POST/PUT/DELETE /api/admin/apps, roles, permissions, user role assignment (admin required)

Full list and request/response shapes: Swagger UI at /api-docs or OpenAPI JSON at /api-docs.json.

Documentation

Backend docs live in docs/:

• docs/ARCHITECTURE.md — Folder map, request flow, stack and env
• docs/CONTRIBUTION.md — Adding routes, auth methods, tests; coverage rules
• docs/TESTS.md — How the integration test infra works

Code style and naming: CONVENTIONS.md.

Project Layout

• src/index.ts – Express app, CORS, Better Auth mount, routes, Swagger
• src/lib/ – auth (Better Auth config), db, jwt helpers, OpenAPI base, verification helper
• src/auth/ – auth router, controller, service, validators, middleware, providers (email/password, session, email verification)
• src/admin/ – admin router, controller, service, middleware, validators
• src/rbac/ – RBAC router, controller, service, types, schemas, validators, OpenAPI
• src/mail/ – mail service, provider (SMTP/SES), template renderer, types
• src/models/ – users, apps, OTP (MongoDB collections)
• src/shared/ – constants, errors, helpers (response, error handler, UUID)

See docs/ARCHITECTURE.md for a detailed folder map and CONVENTIONS.md for naming and request flow.

Scripts

Command	Description
npm run dev	Start with nodemon (ts-node)
npm run build	Compile TypeScript to dist/
npm start	Run dist/index.js
npm run lint	ESLint
npm run setup	Install Lefthook git hooks (pre-push only when be/ is pushed: lint, build, integration tests with 98% coverage). Run from repo root with npm run setup or from be/; config lives at repo root lefthook.yml.

Security Notes

• Use a strong BETTER_AUTH_SECRET (32+ chars) and keep it out of version control.
• In production, set TRUSTED_ORIGINS to your real frontend/backend URLs.
• Session cookie is HttpOnly, and secure in production; access token is short-lived (15 min).
• Forgot-password and send-verification-email responses do not reveal whether an email exists.
• SMS OTP login-init responses do not reveal whether a phone number exists.

A more detailed code and security review is in REVIEW.md.

License

ISC