Auth & RBAC

Authentication & Role-Based Access Control

JWT-based auth with access/refresh tokens, bcrypt password hashing, and role/permission checks. Works with SQLite and MongoDB.

View API Reference

Overview

  • Passwords hashed with bcrypt.
  • Access and Refresh tokens (JWT); refresh tokens persisted and revocable.
  • RBAC via roles and permissions; middleware to guard routes.
  • SQLite and MongoDB supported via a DB abstraction; ObjectId handled where needed.

Quickstart

  1. Set AUTH_JWT_SECRET (required). For Mongo: DATABASE_TYPE=mongodb, MONGO_URI, MONGO_DB_NAME.
  2. Optionally set AUTH_BOOTSTRAP_OWNER_EMAIL and AUTH_BOOTSTRAP_OWNER_PASSWORD to auto-create an Owner.
  3. Start the server; defaults and indexes are seeded automatically.
  4. Use /api/auth/register → /api/auth/login → /api/auth/me to verify.

Environment Variables

  • AUTH_JWT_SECRET (required): JWT signing key for Auth.
  • AUTH_ACCESS_TTL (default 15m): Access token expiry.
  • AUTH_REFRESH_TTL (default 7d): Refresh token expiry.
  • AUTH_BOOTSTRAP_OWNER_EMAIL, AUTH_BOOTSTRAP_OWNER_PASSWORD, AUTH_BOOTSTRAP_OWNER_NAME (optional): Owner bootstrap.
  • ADMIN_TOKEN: For other admin/debug endpoints, not used by Auth JWTs.
  • JWT_SECRET: Used by DownloadService (not Auth); do not confuse with AUTH_JWT_SECRET.

See .env.example for full list and defaults.

Enable Auth as a module (Phase 1)

Enable the pluggable Auth module without changing endpoints:

MODULES_ENABLED=auth
# Optional; default is enabled if unspecified
FEATURE_AUTH=true

All existing AUTH_* variables still apply in module mode.

  • If enabled: module mounts /api/auth/* and seeds defaults in onBootstrap().
  • If not enabled: legacy wiring in src/index.ts mounts routes and seeds on startup.

API Endpoints

POST /api/auth/register – create user, returns user + tokens.

POST /api/auth/login – returns user + tokens, updates last_login_at.

POST /api/auth/refresh – rotate refresh token, returns new pair.

POST /api/auth/logout – revoke provided refresh token.

GET /api/auth/me – requires access token.

Admin/Owner: POST /api/auth/roles/assign, GET /api/auth/roles, GET /api/auth/permissions

Frontend Admin UI

Admin/Owner users can manage users, roles, and permissions from the React admin page.

  • Route: /app/admin/users
  • Page: client/src/pages/ManageUsers.tsx
  • API client: client/src/api/auth-rbac-system/api.ts
  • UI: Shadcn UI components (Select, Input, Button, Card) + React Query
  • Guard: requires authenticated user with admin or owner role

Capabilities

  • Users: list, update email/name/status, delete, and create
  • Permissions: list, create, delete
  • Role permissions: view per-role, assign, unassign

Notes

  • Registration returns tokens; the admin UI ignores them to avoid replacing the current admin session
  • Helper login route: GET /api/auth/client-login accepts HTTP Basic Auth, sets access_token in localStorage, then redirects
  • API wrappers include: createPermission, deletePermission, assignPermissionToRole, getRolePermissions, updateUser, deleteUser, registerUser

Middleware

import { authenticateJWT, requireRole, requirePermission } from "../services/auth";

router.get(
  "/admin/metrics",
  authenticateJWT(),
  requireRole("admin", "owner"),
  requirePermission("view:analytics"),
  (req, res) => res.json({ ok: true })
);

Token Lifecycle

  • Access token: short TTL, includes roles; used on every request.
  • Refresh token: long TTL with jti; persisted, rotated on refresh, revocable.
  • TTLs accept units like m, h, d (e.g., 15m, 7d).

Database Notes

  • MongoDB: avoid SQL literals like CURRENT_TIMESTAMP; use ISO strings in queries.
  • ID coercion handled by the service to support numeric IDs (SQLite) and ObjectId (MongoDB).
  • Indexes ensured for roles, permissions, user_roles, role_permissions, refresh_tokens.