@xeplr/auth 1.0.0 → 1.0.1

package/lib/hooks.js

@@ -0,0 +1,50 @@
+// One generic hook dispatcher for the whole library. Every mutating operation
+// in xeplr-auth (register, activate, role CRUD, mapping toggles, master CRUD,
+// ...) fires through here, tagged with an identifier ('user', 'roles', 'apis',
+// 'uiPages', 'uiElements', 'menus', 'userRolesMapping', ...) and a fixed event
+// ('create' | 'update' | 'delete', plus 'login' — not a CRUD event, but kept
+// on 'user' since it's a meaningful lifecycle moment too).
+//
+// The identifiers are internal to the library (see the fire() call sites for
+// the authoritative list) — you don't need a pre-built namespace object to use
+// one, just the string, documented here and at each call site:
+//   require('@xeplr/auth').hooks.on('user', 'create', function(id) { ... });
+//   require('@xeplr/auth').hooks.on('roles', 'create', function(id) { ... });
+//
+// One handler per (identifier, event) — registering again REPLACES the
+// previous one, not an accumulating list. No handler registered = silent
+// no-op. A failing handler is caught + logged, never breaks the operation
+// that fired it.
+//
+// setHooksEnabled(false) is a bulk kill-switch (e.g. for tests) — defaults to
+// enabled (AUTH_ENABLE_HOOKS=false to default it off via env instead).
+//
+// NOTE on process boundaries: auth normally runs as its own service (AUTH_PORT),
+// a separate process from your app's API. A hook registered from the API
+// process is never seen here — register()/login()/etc. run in the auth
+// service's own process. Assign hooks in the SAME script that calls boot():
+// write your own tiny boot file (copy bin/server.js) that does
+//   require('@xeplr/auth').hooks.on('user', 'create', fn);
+//   require('@xeplr/auth').boot();
+// and point your start-auth script at that file instead of the packaged bin.
+
+var _enabled = process.env.AUTH_ENABLE_HOOKS !== 'false';
+var _handlers = {};
+
+function key(identifier, event) { return identifier + ':' + event; }
+
+function setHooksEnabled(enabled) { _enabled = !!enabled; }
+
+function on(identifier, event, fn) {
+  _handlers[key(identifier, event)] = fn;
+}
+
+async function fire(identifier, event, id) {
+  if (!_enabled) return;
+  var fn = _handlers[key(identifier, event)];
+  if (!fn) return;
+  try { await fn(id); }
+  catch (err) { console.error('[xeplr-auth] hook (' + identifier + '.' + event + ') failed:', err.message); }
+}
+
+module.exports = { on, fire, setHooksEnabled };

package/lib/mtMembershipMiddleware.js

@@ -0,0 +1,61 @@
+const { getMtConfig } = require('@xeplr/db');
+const UserTenantsMapping = require('../models/UserTenantsMapping');
+
+var SLOT_KEYS = ['l1', 'l2', 'l3', 'l4'];
+
+/**
+ * Rejects a request whose MT header values don't match a real membership
+ * grant for the caller — mtMiddleware (in @xeplr/db) trusts any header value
+ * to filter/stamp rows, this is what actually checks the caller is allowed to
+ * use it. Mount AFTER authMiddleware (needs req.user.id) and AFTER
+ * @xeplr/db's mtMiddleware() (reads the same headers).
+ *
+ * A header that's simply absent is left alone — the existing fail-closed
+ * query modifier in BaseModel already handles "missing" (empty result set).
+ * This only rejects a PRESENT but unauthorized value (403).
+ *
+ * @param {object} [options]
+ * @param {typeof UserTenantsMapping} [options.userTenantsMapping] - a bound
+ *   model class, e.g. `auth.attach().model('UserTenantsMapping')` when auth
+ *   runs as its own standalone service. Omit if you called auth.init() in
+ *   this same process (Model.knex is already globally bound there).
+ *
+ *   var { mtMembershipMiddleware } = require('@xeplr/auth');
+ *   app.use(mtMiddleware());               // @xeplr/db — sets mtId context
+ *   app.use(mtMembershipMiddleware());     // this — rejects forged values
+ */
+function mtMembershipMiddleware(options) {
+  options = options || {};
+  var Model = options.userTenantsMapping || UserTenantsMapping;
+
+  return async function(req, res, next) {
+    try {
+      var mtConfig = getMtConfig();
+      if (!mtConfig.enabled || !req.user || !req.user.id) return next();
+
+      for (var i = 0; i < SLOT_KEYS.length; i++) {
+        var key = SLOT_KEYS[i];
+        var slot = mtConfig.slots[key];
+        if (!slot) continue;
+
+        var value = req.headers[slot.header];
+        if (!value) continue;
+
+        var grant = await Model.query()
+          .where({ userId: req.user.id, level: key, value: value, isActive: true })
+          .first();
+
+        if (!grant) {
+          return res.status(403).json({ error: 'Not authorized for ' + (slot.name || key) + ' "' + value + '"' });
+        }
+      }
+
+      next();
+    } catch (err) {
+      if (req.log) req.log.error(err.message, { stack: err.stack });
+      res.status(500).json({ error: 'Something went wrong' });
+    }
+  };
+}
+
+module.exports = mtMembershipMiddleware;

package/lib/seed.js

@@ -0,0 +1,74 @@
+var { generateId, hashPassword } = require('./authHelper');
+
+/**
+ * Ensure a Super Admin user exists and is mapped to the "Super Admin" role.
+ *
+ * Brand-neutral: the caller supplies WHO (email/password/name); this owns HOW
+ * (hashing, columns, role mapping). Insert-if-absent, so it is idempotent and
+ * safe to call from a migration on every run. Requires the base auth migrations
+ * (roles + users + userRolesMapping) to have run first.
+ *
+ * @param {import('knex').Knex} knex
+ * @param {{ email:string, password:string, name?:string }} admin
+ * @returns {Promise<{ userId:string, created:boolean, roleAssigned:boolean }>}
+ */
+async function seedSuperAdmin(knex, admin) {
+  if (!admin || !admin.email || !admin.password) {
+    throw new Error('seedSuperAdmin: { email, password } are required');
+  }
+
+  var role = await knex('roles').where({ name: 'Super Admin' }).first();
+  if (!role) {
+    throw new Error('seedSuperAdmin: "Super Admin" role not found — run the base auth migrations first');
+  }
+
+  var now = new Date().toISOString();
+  var normalized = admin.email.toLowerCase();
+  var existing = await knex('users').where({ normalizedEmail: normalized }).first();
+
+  var userId;
+  var created = false;
+  if (existing) {
+    userId = existing.id;
+  } else {
+    userId = generateId();
+    var creds = await hashPassword(admin.password);
+    await knex('users').insert({
+      id: userId,
+      email: admin.email,
+      normalizedEmail: normalized,
+      name: admin.name || admin.email,
+      pwd: creds.hash,
+      pwdSalt: creds.salt,
+      isActive: true,
+      isActivated: true,
+      activatedOn: now,
+      activatedBy: userId,
+      recordCreatedDate: now,
+      recordModifiedDate: now,
+      recordCreatedBy: userId,
+      recordModifiedBy: userId
+    });
+    created = true;
+  }
+
+  var mapped = await knex('userRolesMapping').where({ userId: userId, roleId: role.id }).first();
+  var roleAssigned = false;
+  if (!mapped) {
+    await knex('userRolesMapping').insert({
+      id: generateId(),
+      userId: userId,
+      roleId: role.id,
+      isActive: true,
+      recordCreatedDate: now,
+      recordModifiedDate: now,
+      recordCreatedBy: userId,
+      recordModifiedBy: userId
+    });
+    roleAssigned = true;
+  }
+
+  return { userId: userId, created: created, roleAssigned: roleAssigned };
+}
+
+module.exports = { seedSuperAdmin };

package/lib/sessionService.js

@@ -17,24 +17,24 @@
  */
 
 const { cache } = require('@xeplr/utils');
-const { generateRefreshToken, generateAccessToken } = require('./authHelper');
+const { generateRefreshToken, generateAccessToken, getToleranceSeconds } = require('./authHelper');
 
 const SESSION_PREFIX = 'session:';
 const ACCESS_PREFIX = 'access:';
 const USER_PREFIX = 'sessions:user:';
 
 function getRefreshTTL() {
-  const days = parseInt(process.env.REFRESH_TOKEN_TTL_DAYS || '7');
+  const days = parseInt(process.env.AUTH_REFRESH_TOKEN_TTL_DAYS || '7');
   return days * 24 * 60 * 60;
 }
 
 function getAccessTTL() {
-  const minutes = parseInt(process.env.ACCESS_TOKEN_TTL_MINUTES || '15');
+  const minutes = parseInt(process.env.AUTH_ACCESS_TOKEN_TTL_MINUTES || '15');
   return minutes * 60;
 }
 
 function getMaxSessions() {
-  return parseInt(process.env.MAX_SESSIONS_PER_USER || '5');
+  return parseInt(process.env.AUTH_MAX_SESSIONS_PER_USER || '5');
 }
 
 /**
@@ -58,11 +58,13 @@ async function createSession(user) {
     createdAt: now
   }, refreshTTL);
 
-  // Store access token whitelist entry (for middleware check)
+  // Store access token whitelist entry (for middleware check). The entry lives
+  // accessTTL + tolerance so it's still present during the grace window — that's
+  // what lets an expired-but-tolerated token find its live session and slide.
   await cache.set(ACCESS_PREFIX + accessToken, {
     userId: user.id,
     refreshToken
-  }, accessTTL);
+  }, accessTTL + getToleranceSeconds());
 
   // Track session in user's sorted set
   const client = cache.getClient();
@@ -126,6 +128,51 @@ async function validateAccessToken(accessToken) {
   return await cache.get(ACCESS_PREFIX + accessToken);
 }
 
+/**
+ * Slide an access token — the sliding refresh. Given an expired-but-tolerated
+ * access token (already signature-verified + session confirmed live by the
+ * middleware), mint a fresh access token for the SAME session and return it,
+ * so the middleware can hand it back on the response.
+ *
+ * Session-scoped IDEMPOTENT: if the session already slid to a newer token
+ * (a concurrent request beat us to it), hand that SAME token back instead of
+ * minting another — so 100 parallel requests yield ONE new token, not 100.
+ *
+ * The OLD token is deliberately left whitelisted (it expires on its own TTL),
+ * so other in-flight requests still carrying it keep passing during the window.
+ *
+ * NOTE: on a single node the check-then-set is race-free. Under HA/cluster,
+ * wrap the mint in a short Redis lock (or a Lua script) for atomicity.
+ *
+ * @param {string} oldToken   the expired-but-tolerated access token
+ * @param {object} claims     its verified JWT claims { id, email, name, roles }
+ * @returns {Promise<string|null>} the fresh access token, or null if no session
+ */
+async function slideAccessToken(oldToken, claims) {
+  const wl = await cache.get(ACCESS_PREFIX + oldToken);
+  if (!wl || !wl.refreshToken) return null;
+
+  const session = await cache.get(SESSION_PREFIX + wl.refreshToken);
+  if (!session) return null;
+
+  // Already slid by a concurrent request → return the current token (idempotent).
+  if (session.accessToken && session.accessToken !== oldToken) {
+    return session.accessToken;
+  }
+
+  // Mint from the token's own claims — no DB hit. (Roles refresh fully on the
+  // next /refresh or re-login; sliding just extends the active session.)
+  const newToken = generateAccessToken({
+    id: claims.id, email: claims.email, name: claims.name, roles: claims.roles || []
+  });
+  const whitelistTTL = getAccessTTL() + getToleranceSeconds();
+
+  await cache.set(ACCESS_PREFIX + newToken, { userId: wl.userId, refreshToken: wl.refreshToken }, whitelistTTL);
+  await cache.set(SESSION_PREFIX + wl.refreshToken, Object.assign({}, session, { accessToken: newToken }), getRefreshTTL());
+
+  return newToken;
+}
+
 /**
  * Rotate a session — validate old refresh token, create new pair.
  * Returns { accessToken, refreshToken, userId } or null.
@@ -204,6 +251,7 @@ module.exports = {
   createSession,
   getSession,
   validateAccessToken,
+  slideAccessToken,
   rotateSession,
   destroySession,
   destroyAllUserSessions

package/lib/ticketService.js

@@ -0,0 +1,88 @@
+/**
+ * ticketService — one-time-use tickets for out-of-band auth channels
+ * (SSE, WebSocket) where the browser can't attach a normal Authorization
+ * header.
+ *
+ * FLOW
+ *   1. Client makes an AUTHENTICATED POST to /auth/api/sse-ticket
+ *   2. issueTicket({ userId, scopes }) mints a random 24-byte token,
+ *      stores it in Redis with a 30s TTL, returns { ticket, expiresIn }
+ *   3. Client opens EventSource('/events?ticket=<tk>&topics=...')
+ *   4. SSE handler calls consumeTicket(tk) which atomically GETDEL's
+ *      the token. Returns { userId, scopes } on success, null on
+ *      missing / expired / already-consumed.
+ *   5. SSE handler enforces the requested topics are within `scopes`.
+ *
+ * SECURITY PROPERTIES
+ *   · Single-use     — Redis GETDEL is atomic; two concurrent connects
+ *                      with the same URL cannot both succeed
+ *   · Short-lived    — default 30s; only needs to survive the roundtrip
+ *                      from /sse-ticket → EventSource open
+ *   · Bearer-free    — no long-lived token ever appears in a query string
+ *   · Scope-bound    — the ticket carries the exact set of subscribe
+ *                      scopes the user was authorized for at mint time;
+ *                      the SSE handler enforces this per-topic
+ *
+ * STORAGE
+ *   @xeplr/utils cache is Redis-backed via ioredis. We use client.getdel()
+ *   directly (bypassing cache.set's error swallowing) so a Redis outage
+ *   surfaces immediately at ticket mint time — the caller learns "auth
+ *   backend unavailable" instead of "your ticket silently didn't stick
+ *   and the connection is now inexplicably 401".
+ */
+
+const crypto = require('crypto');
+const { cache } = require('@xeplr/utils');
+
+const TICKET_PREFIX = 'ticket:sse:';
+const DEFAULT_TTL   = 30;   // seconds
+
+function newTicketId() {
+  return crypto.randomBytes(24).toString('base64url');
+}
+
+/**
+ * Issue a one-time ticket bound to a user + scope set.
+ *
+ * @param {object} payload      — { userId, scopes: string[], ... }
+ * @param {object} [opts]
+ * @param {number} [opts.ttl]   — seconds (default 30)
+ * @returns {Promise<{ ticket: string, expiresIn: number }>}
+ * @throws                       if Redis is unreachable (fail loud — this
+ *                               is an auth surface, silent failure is a bug)
+ */
+async function issueTicket(payload, opts) {
+  if (!payload || !payload.userId) {
+    throw new Error('ticketService.issueTicket: payload.userId is required');
+  }
+  var ttl = (opts && opts.ttl) || DEFAULT_TTL;
+  var ticket = newTicketId();
+
+  var client = cache.getClient();
+  await client.set(TICKET_PREFIX + ticket, JSON.stringify(payload), 'EX', ttl);
+  return { ticket: ticket, expiresIn: ttl };
+}
+
+/**
+ * Atomically consume a ticket. Returns the payload on success, null if
+ * the ticket doesn't exist / expired / was already consumed.
+ *
+ * Guarantees single-use even under concurrent lookups (Redis GETDEL is
+ * a single atomic op).
+ *
+ * @param {string} ticket
+ * @returns {Promise<object|null>}
+ */
+async function consumeTicket(ticket) {
+  if (!ticket || typeof ticket !== 'string') return null;
+  var client = cache.getClient();
+  var raw = await client.getdel(TICKET_PREFIX + ticket);
+  if (!raw) return null;
+  try { return JSON.parse(raw); }
+  catch (_) { return null; }
+}
+
+module.exports = {
+  issueTicket:   issueTicket,
+  consumeTicket: consumeTicket
+};

package/lib/tokenDecision.js

@@ -0,0 +1,45 @@
+// Pure token decision — NO I/O, NO side effects. This is the heart of the
+// tolerance-refresh scheme, deliberately isolated so its edges are covered by
+// tests instead of discovered in production. The middleware does the I/O
+// (verify signature, look up the session) and hands the facts to decide().
+//
+//   decide({ exp, now, toleranceSeconds, sessionLive, signatureValid })
+//     → { action, reason }
+//
+//   action:
+//     'ok'     → token is valid; serve normally
+//     'slide'  → token expired but within tolerance; serve AND issue a fresh
+//                token (attach it to the response) — the sliding refresh
+//     'reject' → do not serve (401)
+//
+//   inputs (all plain values — that's the point):
+//     exp              token expiry, UNIX seconds (JWT `exp`)
+//     now              current time, UNIX seconds
+//     toleranceSeconds grace past expiry during which an expired token is still
+//                      honored + refreshed. 0 = strict (reject on expiry).
+//     sessionLive      is the session still valid server-side (NOT logged
+//                      out / revoked)?  A revoke is NEVER graced.
+//     signatureValid   did the JWT signature verify?
+//
+// Order matters: signature → revocation → expiry. A bad signature or a revoked
+// session is rejected regardless of the clock; only a validly-signed, live
+// session gets the tolerance grace.
+
+function decide(input) {
+  input = input || {};
+  var exp = input.exp;
+  var now = input.now;
+  var tolerance = input.toleranceSeconds || 0;
+
+  if (!input.signatureValid) return { action: 'reject', reason: 'bad-signature' };
+  if (!input.sessionLive)    return { action: 'reject', reason: 'revoked' };        // never grace a revoke
+  if (typeof exp !== 'number' || typeof now !== 'number') {
+    return { action: 'reject', reason: 'no-expiry' };
+  }
+
+  if (now <= exp)                 return { action: 'ok',    reason: 'valid' };
+  if (now <= exp + tolerance)     return { action: 'slide', reason: 'within-tolerance' };
+  return { action: 'reject', reason: 'expired' };
+}
+
+module.exports = { decide };

package/migrations/0001_extensions.sql

@@ -0,0 +1,9 @@
+-- 0001_extensions.sql
+-- pgcrypto gives us gen_random_bytes() for id generation (see 0006's
+-- encode(gen_random_bytes(12),'hex') — matches the app's own generateId()
+-- shape) and crypt()/gen_salt('bf') — real bcrypt-compatible hashes, usable
+-- from plain SQL for any app-level super-admin bootstrap migration (see
+-- lib/seed.js's seedSuperAdmin, or roll your own like this). Node's `bcrypt`
+-- package can compare() against these hashes directly (same algorithm family).
+
+CREATE EXTENSION IF NOT EXISTS pgcrypto;

package/migrations/0002_users.sql

@@ -0,0 +1,31 @@
+-- 0002_users.sql
+
+CREATE TABLE "users" (
+  "id" varchar(25) PRIMARY KEY,
+  "email" varchar(255) NOT NULL,
+  "normalizedEmail" varchar(255),
+  "phoneNumber" varchar(255),
+  "phoneVerified" boolean DEFAULT false,
+  "phoneVerifiedOn" timestamp,
+  "name" varchar(255),
+  "pwd" varchar(255),
+  "pwdSalt" varchar(100),
+  "profilePicUrl" varchar(500),
+  "isActive" boolean DEFAULT false,
+  "isActivated" boolean DEFAULT false,
+  "activatedOn" timestamp,
+  "activatedBy" varchar(25),
+  "resetToken" varchar(255),
+  "resetTokenExpiry" timestamp,
+  "activationToken" varchar(255),
+  "mtId1" varchar(25),
+  "mtId2" varchar(25),
+  "mtId3" varchar(25),
+  "mtId4" varchar(25),
+  "recordCreatedDate" timestamp,
+  "recordModifiedDate" timestamp,
+  "recordCreatedBy" varchar(25),
+  "recordModifiedBy" varchar(25)
+);
+
+CREATE INDEX "users_normalizedEmail_index" ON "users" ("normalizedEmail");

package/migrations/0003_catalog_tables.sql

@@ -0,0 +1,82 @@
+-- 0003_catalog_tables.sql
+-- roles + the four access-catalog tables (apis/uiPages/uiElements/menus),
+-- each independently role-mappable and each with an isPublic escape hatch
+-- (accessService.getPublicItems() unions isPublic:true rows into every
+-- authenticated user's access regardless of role).
+
+CREATE TABLE "roles" (
+  "id" varchar(25) PRIMARY KEY,
+  "name" varchar(255),
+  "isActive" boolean DEFAULT false,
+  "mtId1" varchar(25),
+  "mtId2" varchar(25),
+  "mtId3" varchar(25),
+  "mtId4" varchar(25),
+  "recordCreatedDate" timestamp,
+  "recordModifiedDate" timestamp,
+  "recordCreatedBy" varchar(25),
+  "recordModifiedBy" varchar(25)
+);
+
+CREATE TABLE "apis" (
+  "id" varchar(25) PRIMARY KEY,
+  "name" varchar(255),
+  "apiGroup" varchar(255),
+  "isPublic" boolean DEFAULT false,
+  "isActive" boolean DEFAULT false,
+  "mtId1" varchar(25),
+  "mtId2" varchar(25),
+  "mtId3" varchar(25),
+  "mtId4" varchar(25),
+  "recordCreatedDate" timestamp,
+  "recordModifiedDate" timestamp,
+  "recordCreatedBy" varchar(25),
+  "recordModifiedBy" varchar(25)
+);
+
+CREATE TABLE "uiPages" (
+  "id" varchar(25) PRIMARY KEY,
+  "name" varchar(255),
+  "uiPagesGroup" varchar(255),
+  "isPublic" boolean DEFAULT false,
+  "isActive" boolean DEFAULT false,
+  "mtId1" varchar(25),
+  "mtId2" varchar(25),
+  "mtId3" varchar(25),
+  "mtId4" varchar(25),
+  "recordCreatedDate" timestamp,
+  "recordModifiedDate" timestamp,
+  "recordCreatedBy" varchar(25),
+  "recordModifiedBy" varchar(25)
+);
+
+CREATE TABLE "uiElements" (
+  "id" varchar(25) PRIMARY KEY,
+  "name" varchar(255),
+  "uiElementsGroup" varchar(255),
+  "isActive" boolean DEFAULT false,
+  "mtId1" varchar(25),
+  "mtId2" varchar(25),
+  "mtId3" varchar(25),
+  "mtId4" varchar(25),
+  "recordCreatedDate" timestamp,
+  "recordModifiedDate" timestamp,
+  "recordCreatedBy" varchar(25),
+  "recordModifiedBy" varchar(25)
+);
+
+CREATE TABLE "menus" (
+  "id" varchar(25) PRIMARY KEY,
+  "name" varchar(255),
+  "menuGroup" varchar(255),
+  "isPublic" boolean DEFAULT false,
+  "isActive" boolean DEFAULT false,
+  "mtId1" varchar(25),
+  "mtId2" varchar(25),
+  "mtId3" varchar(25),
+  "mtId4" varchar(25),
+  "recordCreatedDate" timestamp,
+  "recordModifiedDate" timestamp,
+  "recordCreatedBy" varchar(25),
+  "recordModifiedBy" varchar(25)
+);

package/migrations/0004_role_mappings.sql

@@ -0,0 +1,78 @@
+-- 0004_role_mappings.sql
+-- Join tables: which roles can see which api/page/element/menu, and which
+-- users hold which roles.
+
+CREATE TABLE "apisRolesMapping" (
+  "id" varchar(25) PRIMARY KEY,
+  "roleId" varchar(25) REFERENCES "roles"("id"),
+  "apiId" varchar(25) REFERENCES "apis"("id"),
+  "isActive" boolean DEFAULT false,
+  "mtId1" varchar(25),
+  "mtId2" varchar(25),
+  "mtId3" varchar(25),
+  "mtId4" varchar(25),
+  "recordCreatedDate" timestamp,
+  "recordModifiedDate" timestamp,
+  "recordCreatedBy" varchar(25),
+  "recordModifiedBy" varchar(25)
+);
+
+CREATE TABLE "uiPagesRolesMapping" (
+  "id" varchar(25) PRIMARY KEY,
+  "roleId" varchar(25) REFERENCES "roles"("id"),
+  "uiPageId" varchar(25) REFERENCES "uiPages"("id"),
+  "isActive" boolean DEFAULT false,
+  "mtId1" varchar(25),
+  "mtId2" varchar(25),
+  "mtId3" varchar(25),
+  "mtId4" varchar(25),
+  "recordCreatedDate" timestamp,
+  "recordModifiedDate" timestamp,
+  "recordCreatedBy" varchar(25),
+  "recordModifiedBy" varchar(25)
+);
+
+CREATE TABLE "uiElementsRolesMapping" (
+  "id" varchar(25) PRIMARY KEY,
+  "roleId" varchar(25) REFERENCES "roles"("id"),
+  "uiElementId" varchar(25) REFERENCES "uiElements"("id"),
+  "isActive" boolean DEFAULT false,
+  "mtId1" varchar(25),
+  "mtId2" varchar(25),
+  "mtId3" varchar(25),
+  "mtId4" varchar(25),
+  "recordCreatedDate" timestamp,
+  "recordModifiedDate" timestamp,
+  "recordCreatedBy" varchar(25),
+  "recordModifiedBy" varchar(25)
+);
+
+CREATE TABLE "menuRolesMapping" (
+  "id" varchar(25) PRIMARY KEY,
+  "menuId" varchar(25) REFERENCES "menus"("id"),
+  "roleId" varchar(25) REFERENCES "roles"("id"),
+  "isActive" boolean DEFAULT false,
+  "mtId1" varchar(25),
+  "mtId2" varchar(25),
+  "mtId3" varchar(25),
+  "mtId4" varchar(25),
+  "recordCreatedDate" timestamp,
+  "recordModifiedDate" timestamp,
+  "recordCreatedBy" varchar(25),
+  "recordModifiedBy" varchar(25)
+);
+
+CREATE TABLE "userRolesMapping" (
+  "id" varchar(25) PRIMARY KEY,
+  "userId" varchar(25) REFERENCES "users"("id"),
+  "roleId" varchar(25) REFERENCES "roles"("id"),
+  "isActive" boolean DEFAULT false,
+  "mtId1" varchar(25),
+  "mtId2" varchar(25),
+  "mtId3" varchar(25),
+  "mtId4" varchar(25),
+  "recordCreatedDate" timestamp,
+  "recordModifiedDate" timestamp,
+  "recordCreatedBy" varchar(25),
+  "recordModifiedBy" varchar(25)
+);

package/migrations/0005_user_tenants_mapping.sql

@@ -0,0 +1,39 @@
+-- 0005_user_tenants_mapping.sql
+-- Row-per-level membership registry. `level` is the generic MT slot (l1-l4,
+-- matching mtId1-4) — not the app-defined name (companyId/workspaceId/...);
+-- that name<->slot mapping lives only in the app's own registerMTs() config
+-- (see @xeplr/db's BaseModel.registerMTs). `value` is the app's own id at
+-- that level — auth doesn't own or validate a tenant tree, it just records
+-- "this user is a member at this level with this value".
+--
+-- This table is deliberately NOT multiTenant-filtered by BaseModel (see
+-- UserTenantsMapping.js's `multiTenant: false`) — it must be queryable before
+-- any active scope exists (chicken-and-egg: you need this table to find out
+-- which company to activate in the first place).
+
+CREATE TABLE "userTenantsMapping" (
+  "id" varchar(25) PRIMARY KEY,
+  "userId" varchar(25) NOT NULL REFERENCES "users"("id"),
+  "level" varchar(2) NOT NULL CHECK ("level" IN ('l1', 'l2', 'l3', 'l4')),
+  "value" varchar(255) NOT NULL,
+  "roleId" varchar(25) REFERENCES "roles"("id"),
+  "isActive" boolean DEFAULT true,
+  "mtId1" varchar(25),
+  "mtId2" varchar(25),
+  "mtId3" varchar(25),
+  "mtId4" varchar(25),
+  "recordCreatedDate" timestamp,
+  "recordModifiedDate" timestamp,
+  "recordCreatedBy" varchar(25),
+  "recordModifiedBy" varchar(25),
+  UNIQUE ("userId", "level", "value")
+);
+
+-- Enforcement lookup (mtMembershipMiddleware): "does this user have a grant
+-- at level X with value Y?"
+CREATE INDEX "userTenantsMapping_userId_level_value_index"
+  ON "userTenantsMapping" ("userId", "level", "value");
+
+-- "Who has access to this company/workspace?" lookups.
+CREATE INDEX "userTenantsMapping_level_value_index"
+  ON "userTenantsMapping" ("level", "value");