@xeplr/auth 1.0.0

package/lib/authService.js

@@ -0,0 +1,194 @@
+const crypto = require('crypto');
+const { sendEmail, configureEmail, formatDbDateTime } = require('@xeplr/utils');
+const { normalizeEmail } = require('@xeplr/utils/isomorphic');
+const { generateId, hashPassword, comparePassword } = require('./authHelper');
+const User = require('../models/User');
+const { getUserAccess, clearUserAccess } = require('./accessService');
+const { createSession, destroyAllUserSessions } = require('./sessionService');
+
+let _activationBaseUrl = null;
+
+function configureActivation(baseUrl) {
+  _activationBaseUrl = baseUrl;
+}
+
+async function register({ email, phoneNumber, name, password }) {
+  const normalized = normalizeEmail(email);
+
+  const existing = await User.query().findOne({ normalizedEmail: normalized });
+  if (existing) {
+    throw new Error('Email already registered');
+  }
+
+  const id = generateId();
+  const { hash, salt } = await hashPassword(password);
+  const now = formatDbDateTime();
+  const activationToken = crypto.randomBytes(32).toString('hex');
+
+  const user = await User.query().insert({
+    id,
+    email: email.trim().toLowerCase(),
+    normalizedEmail: normalized,
+    phoneNumber: phoneNumber || null,
+    name: name || null,
+    pwd: hash,
+    pwdSalt: salt,
+    isActive: true,
+    isActivated: false,
+    activationToken,
+    activatedOn: null,
+    activatedBy: null,
+    recordCreatedDate: now,
+    recordModifiedDate: now,
+    recordCreatedBy: id,
+    recordModifiedBy: id
+  });
+
+  // Send activation email
+  const baseUrl = _activationBaseUrl || process.env.ACTIVATION_BASE_URL;
+  if (!baseUrl) {
+    throw new Error('ACTIVATION_BASE_URL is required. Cannot register without email activation.');
+  }
+
+  const activationLink = baseUrl + '/auth/activate?token=' + activationToken;
+  const html = '<h2>Activate your account</h2>'
+    + '<p>Hi ' + (name || 'there') + ',</p>'
+    + '<p>Click below to activate your account:</p>'
+    + '<p><a href="' + activationLink + '">' + activationLink + '</a></p>';
+
+  await sendEmail(email, 'Activate your account', html);
+
+  return {
+    id: user.id,
+    email: user.email,
+    name: user.name,
+    phoneNumber: user.phoneNumber,
+    isActive: user.isActive,
+    isActivated: user.isActivated
+  };
+}
+
+async function activate(token) {
+  const user = await User.query().findOne({ activationToken: token });
+  if (!user) {
+    throw new Error('Invalid activation token');
+  }
+
+  if (user.isActivated) {
+    throw new Error('Account already activated');
+  }
+
+  const now = formatDbDateTime();
+  await User.query().findById(user.id).patch({
+    isActivated: true,
+    activatedOn: now,
+    activationToken: null,
+    recordModifiedDate: now
+  });
+
+  return { id: user.id, email: user.email, name: user.name };
+}
+
+async function login({ email, password }) {
+  const normalized = normalizeEmail(email);
+  const user = await User.query().findOne({ normalizedEmail: normalized });
+  if (!user) {
+    throw new Error('Invalid email or password');
+  }
+
+  if (!user.isActive) {
+    throw new Error('Account is deactivated');
+  }
+
+  const isMatch = await comparePassword(password, user.pwd);
+  if (!isMatch) {
+    throw new Error('Invalid email or password');
+  }
+
+  if (!user.isActivated) {
+    throw new Error('NOT_ACTIVATED');
+  }
+
+  const { accessToken, refreshToken } = await createSession(user);
+
+  await clearUserAccess(user.id);
+  const access = await getUserAccess(user.id);
+
+  return {
+    accessToken,
+    refreshToken,
+    user: {
+      id: user.id,
+      email: user.email,
+      name: user.name,
+      isActivated: user.isActivated
+    },
+    access
+  };
+}
+
+async function forgotPassword({ email }, resetBaseUrl) {
+  const normalized = normalizeEmail(email);
+  const user = await User.query().findOne({ normalizedEmail: normalized });
+  if (!user) {
+    return;
+  }
+
+  const resetToken = crypto.randomBytes(32).toString('hex');
+  const expiryMinutes = parseInt(process.env.RESET_TOKEN_EXPIRY_MINUTES) || 30;
+  const resetTokenExpiry = formatDbDateTime(new Date(Date.now() + expiryMinutes * 60 * 1000));
+
+  await User.query().findById(user.id).patch({
+    resetToken,
+    resetTokenExpiry,
+    recordModifiedDate: formatDbDateTime()
+  });
+
+  const resetLink = `${resetBaseUrl}/auth/reset-password?token=${resetToken}`;
+
+  const html = `
+    <h2>Password Reset</h2>
+    <p>Hi ${user.name || 'there'},</p>
+    <p>You requested a password reset. Click the link below to reset your password:</p>
+    <p><a href="${resetLink}">${resetLink}</a></p>
+    <p>This link expires in ${expiryMinutes} minutes.</p>
+    <p>If you didn't request this, ignore this email.</p>
+  `;
+
+  await sendEmail(user.email, 'Password Reset', html);
+}
+
+async function resetPassword({ token, newPassword }) {
+  const user = await User.query().findOne({ resetToken: token });
+
+  if (!user) {
+    throw new Error('Invalid or expired reset token');
+  }
+
+  if (user.resetTokenExpiry < formatDbDateTime()) {
+    throw new Error('Invalid or expired reset token');
+  }
+
+  const { hash, salt } = await hashPassword(newPassword);
+
+  await User.query().findById(user.id).patch({
+    pwd: hash,
+    pwdSalt: salt,
+    resetToken: null,
+    resetTokenExpiry: null,
+    recordModifiedDate: formatDbDateTime()
+  });
+
+  await destroyAllUserSessions(user.id);
+  await clearUserAccess(user.id);
+}
+
+module.exports = {
+  configureActivation,
+  configureEmail,
+  register,
+  activate,
+  login,
+  forgotPassword,
+  resetPassword
+};

package/lib/sessionService.js

@@ -0,0 +1,210 @@
+/**
+ * Session service — manages access + refresh token pairs in Redis.
+ *
+ * A "session" = one device/browser login, containing:
+ *   - An access token (short-lived, 15m)
+ *   - A refresh token (long-lived, 7d)
+ *
+ * Redis keys:
+ *   session:{refreshToken}     → { userId, accessToken, createdAt }
+ *   access:{accessToken}       → { userId, refreshToken }   (for whitelist check)
+ *   sessions:user:{userId}     → Sorted Set of refreshTokens (score = createdAt)
+ *
+ * Env vars:
+ *   REFRESH_TOKEN_TTL_DAYS     — refresh token lifetime (default: 7)
+ *   ACCESS_TOKEN_TTL_MINUTES   — access token lifetime (default: 15)
+ *   MAX_SESSIONS_PER_USER      — max concurrent sessions (default: 5)
+ */
+
+const { cache } = require('@xeplr/utils');
+const { generateRefreshToken, generateAccessToken } = 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');
+  return days * 24 * 60 * 60;
+}
+
+function getAccessTTL() {
+  const minutes = parseInt(process.env.ACCESS_TOKEN_TTL_MINUTES || '15');
+  return minutes * 60;
+}
+
+function getMaxSessions() {
+  return parseInt(process.env.MAX_SESSIONS_PER_USER || '5');
+}
+
+/**
+ * Create a new session (access + refresh token pair).
+ * Evicts oldest session(s) if max sessions exceeded.
+ *
+ * @param {object} user - User object (id, email, name)
+ * @returns {{ accessToken, refreshToken }}
+ */
+async function createSession(user) {
+  const accessToken = generateAccessToken(user);
+  const refreshToken = generateRefreshToken();
+  const now = Date.now();
+  const refreshTTL = getRefreshTTL();
+  const accessTTL = getAccessTTL();
+
+  // Store session keyed by refresh token
+  await cache.set(SESSION_PREFIX + refreshToken, {
+    userId: user.id,
+    accessToken,
+    createdAt: now
+  }, refreshTTL);
+
+  // Store access token whitelist entry (for middleware check)
+  await cache.set(ACCESS_PREFIX + accessToken, {
+    userId: user.id,
+    refreshToken
+  }, accessTTL);
+
+  // Track session in user's sorted set
+  const client = cache.getClient();
+  try {
+    await client.zadd(USER_PREFIX + user.id, now, refreshToken);
+    await client.expire(USER_PREFIX + user.id, refreshTTL);
+
+    // Enforce session limit
+    await evictExcessSessions(user.id);
+  } catch (e) {
+    // Silently fail
+  }
+
+  return { accessToken, refreshToken };
+}
+
+/**
+ * Evict oldest sessions if user exceeds MAX_SESSIONS_PER_USER.
+ */
+async function evictExcessSessions(userId) {
+  const client = cache.getClient();
+  const maxSessions = getMaxSessions();
+  const count = await client.zcard(USER_PREFIX + userId);
+
+  if (count <= maxSessions) return;
+
+  const excess = count - maxSessions;
+  const oldRefreshTokens = await client.zrange(USER_PREFIX + userId, 0, excess - 1);
+
+  if (oldRefreshTokens && oldRefreshTokens.length > 0) {
+    const pipeline = client.pipeline();
+
+    for (const rt of oldRefreshTokens) {
+      // Look up the session to find the paired access token
+      const sessionData = await cache.get(SESSION_PREFIX + rt);
+      if (sessionData && sessionData.accessToken) {
+        pipeline.del(ACCESS_PREFIX + sessionData.accessToken);
+      }
+      pipeline.del(SESSION_PREFIX + rt);
+    }
+
+    // Remove from sorted set
+    pipeline.zremrangebyrank(USER_PREFIX + userId, 0, excess - 1);
+    await pipeline.exec();
+  }
+}
+
+/**
+ * Get session data by refresh token.
+ * Returns { userId, accessToken, createdAt } or null.
+ */
+async function getSession(refreshToken) {
+  return await cache.get(SESSION_PREFIX + refreshToken);
+}
+
+/**
+ * Validate an access token against the Redis whitelist.
+ * Returns { userId, refreshToken } if valid, null if revoked/expired.
+ */
+async function validateAccessToken(accessToken) {
+  return await cache.get(ACCESS_PREFIX + accessToken);
+}
+
+/**
+ * Rotate a session — validate old refresh token, create new pair.
+ * Returns { accessToken, refreshToken, userId } or null.
+ */
+async function rotateSession(oldRefreshToken, user) {
+  const session = await cache.get(SESSION_PREFIX + oldRefreshToken);
+  if (!session || !session.userId) return null;
+
+  // Delete old session
+  await destroySession(oldRefreshToken);
+
+  // Create new session (limit check happens inside)
+  const tokens = await createSession(user);
+  return { ...tokens, userId: session.userId };
+}
+
+/**
+ * Destroy a specific session (logout from one device).
+ */
+async function destroySession(refreshToken) {
+  const session = await cache.get(SESSION_PREFIX + refreshToken);
+
+  if (session) {
+    // Delete the access token whitelist entry
+    if (session.accessToken) {
+      await cache.del(ACCESS_PREFIX + session.accessToken);
+    }
+
+    // Remove from user's sorted set
+    if (session.userId) {
+      const client = cache.getClient();
+      try {
+        await client.zrem(USER_PREFIX + session.userId, refreshToken);
+      } catch (e) {
+        // Silently fail
+      }
+    }
+  }
+
+  // Delete the session itself
+  await cache.del(SESSION_PREFIX + refreshToken);
+}
+
+/**
+ * Destroy ALL sessions for a user (password change, force logout all devices).
+ */
+async function destroyAllUserSessions(userId) {
+  const client = cache.getClient();
+  try {
+    const refreshTokens = await client.zrange(USER_PREFIX + userId, 0, -1);
+
+    if (refreshTokens && refreshTokens.length > 0) {
+      const pipeline = client.pipeline();
+
+      for (const rt of refreshTokens) {
+        const session = await cache.get(SESSION_PREFIX + rt);
+        if (session && session.accessToken) {
+          pipeline.del(ACCESS_PREFIX + session.accessToken);
+        }
+        pipeline.del(SESSION_PREFIX + rt);
+      }
+
+      pipeline.del(USER_PREFIX + userId);
+      await pipeline.exec();
+    } else {
+      await client.del(USER_PREFIX + userId);
+    }
+  } catch (e) {
+    // Fallback
+    await cache.delPattern('session:*');
+    await cache.delPattern('access:*');
+  }
+}
+
+module.exports = {
+  createSession,
+  getSession,
+  validateAccessToken,
+  rotateSession,
+  destroySession,
+  destroyAllUserSessions
+};

package/migrations/0001_users.js

@@ -0,0 +1,22 @@
+exports.up = function(knex) {
+  return knex.schema.createTable('users', function(table) {
+    table.string('id', 25).primary();
+    table.string('email', 255).notNullable();
+    table.string('phoneNumber', 255);
+    table.string('name', 255);
+    table.string('pwd', 255);
+    table.string('pwdSalt', 100);
+    table.boolean('isActive').defaultTo(false);
+    table.boolean('isActivated').defaultTo(false);
+    table.timestamp('activatedOn');
+    table.string('activatedBy', 25);
+    table.timestamp('recordCreatedDate');
+    table.timestamp('recordModifiedDate');
+    table.string('recordCreatedBy', 25);
+    table.string('recordModifiedBy', 25);
+  });
+};
+
+exports.down = function(knex) {
+  return knex.schema.dropTableIfExists('users');
+};

package/migrations/0002_menus.js

@@ -0,0 +1,16 @@
+exports.up = function(knex) {
+  return knex.schema.createTable('menus', function(table) {
+    table.string('id', 25).primary();
+    table.string('name', 255);
+    table.string('menuGroup', 255);
+    table.boolean('isActive').defaultTo(false);
+    table.timestamp('recordCreatedDate');
+    table.timestamp('recordModifiedDate');
+    table.string('recordCreatedBy', 25);
+    table.string('recordModifiedBy', 25);
+  });
+};
+
+exports.down = function(knex) {
+  return knex.schema.dropTableIfExists('menus');
+};

package/migrations/0003_apis.js

@@ -0,0 +1,16 @@
+exports.up = function(knex) {
+  return knex.schema.createTable('apis', function(table) {
+    table.string('id', 25).primary();
+    table.string('name', 255);
+    table.string('apiGroup', 255);
+    table.boolean('isActive').defaultTo(false);
+    table.timestamp('recordCreatedDate');
+    table.timestamp('recordModifiedDate');
+    table.string('recordCreatedBy', 25);
+    table.string('recordModifiedBy', 25);
+  });
+};
+
+exports.down = function(knex) {
+  return knex.schema.dropTableIfExists('apis');
+};

package/migrations/0004_uiPages.js

@@ -0,0 +1,16 @@
+exports.up = function(knex) {
+  return knex.schema.createTable('uiPages', function(table) {
+    table.string('id', 25).primary();
+    table.string('name', 255);
+    table.string('uiPagesGroup', 255);
+    table.boolean('isActive').defaultTo(false);
+    table.timestamp('recordCreatedDate');
+    table.timestamp('recordModifiedDate');
+    table.string('recordCreatedBy', 25);
+    table.string('recordModifiedBy', 25);
+  });
+};
+
+exports.down = function(knex) {
+  return knex.schema.dropTableIfExists('uiPages');
+};

package/migrations/0005_uiElements.js

@@ -0,0 +1,16 @@
+exports.up = function(knex) {
+  return knex.schema.createTable('uiElements', function(table) {
+    table.string('id', 25).primary();
+    table.string('name', 255);
+    table.string('uiElementsGroup', 255);
+    table.boolean('isActive').defaultTo(false);
+    table.timestamp('recordCreatedDate');
+    table.timestamp('recordModifiedDate');
+    table.string('recordCreatedBy', 25);
+    table.string('recordModifiedBy', 25);
+  });
+};
+
+exports.down = function(knex) {
+  return knex.schema.dropTableIfExists('uiElements');
+};

package/migrations/0006_roles.js

@@ -0,0 +1,15 @@
+exports.up = function(knex) {
+  return knex.schema.createTable('roles', function(table) {
+    table.string('id', 25).primary();
+    table.string('name', 255);
+    table.boolean('isActive').defaultTo(false);
+    table.timestamp('recordCreatedDate');
+    table.timestamp('recordModifiedDate');
+    table.string('recordCreatedBy', 25);
+    table.string('recordModifiedBy', 25);
+  });
+};
+
+exports.down = function(knex) {
+  return knex.schema.dropTableIfExists('roles');
+};

package/migrations/0007_apisRolesMapping.js

@@ -0,0 +1,16 @@
+exports.up = function(knex) {
+  return knex.schema.createTable('apisRolesMapping', function(table) {
+    table.string('id', 25).primary();
+    table.string('roleId', 25).references('id').inTable('roles');
+    table.string('apiId', 25).references('id').inTable('apis');
+    table.boolean('isActive').defaultTo(false);
+    table.timestamp('recordCreatedDate');
+    table.timestamp('recordModifiedDate');
+    table.string('recordCreatedBy', 25);
+    table.string('recordModifiedBy', 25);
+  });
+};
+
+exports.down = function(knex) {
+  return knex.schema.dropTableIfExists('apisRolesMapping');
+};

package/migrations/0008_uiPagesRolesMapping.js

@@ -0,0 +1,16 @@
+exports.up = function(knex) {
+  return knex.schema.createTable('uiPagesRolesMapping', function(table) {
+    table.string('id', 25).primary();
+    table.string('roleId', 25).references('id').inTable('roles');
+    table.string('uiPageId', 25).references('id').inTable('uiPages');
+    table.boolean('isActive').defaultTo(false);
+    table.timestamp('recordCreatedDate');
+    table.timestamp('recordModifiedDate');
+    table.string('recordCreatedBy', 25);
+    table.string('recordModifiedBy', 25);
+  });
+};
+
+exports.down = function(knex) {
+  return knex.schema.dropTableIfExists('uiPagesRolesMapping');
+};

package/migrations/0009_uiElementsRolesMapping.js

@@ -0,0 +1,16 @@
+exports.up = function(knex) {
+  return knex.schema.createTable('uiElementsRolesMapping', function(table) {
+    table.string('id', 25).primary();
+    table.string('roleId', 25).references('id').inTable('roles');
+    table.string('uiElementId', 25).references('id').inTable('uiElements');
+    table.boolean('isActive').defaultTo(false);
+    table.timestamp('recordCreatedDate');
+    table.timestamp('recordModifiedDate');
+    table.string('recordCreatedBy', 25);
+    table.string('recordModifiedBy', 25);
+  });
+};
+
+exports.down = function(knex) {
+  return knex.schema.dropTableIfExists('uiElementsRolesMapping');
+};

package/migrations/0010_menuRolesMapping.js

@@ -0,0 +1,16 @@
+exports.up = function(knex) {
+  return knex.schema.createTable('menuRolesMapping', function(table) {
+    table.string('id', 25).primary();
+    table.string('menuId', 25).references('id').inTable('menus');
+    table.string('roleId', 25).references('id').inTable('roles');
+    table.boolean('isActive').defaultTo(false);
+    table.timestamp('recordCreatedDate');
+    table.timestamp('recordModifiedDate');
+    table.string('recordCreatedBy', 25);
+    table.string('recordModifiedBy', 25);
+  });
+};
+
+exports.down = function(knex) {
+  return knex.schema.dropTableIfExists('menuRolesMapping');
+};

package/migrations/0011_userRolesMapping.js

@@ -0,0 +1,16 @@
+exports.up = function(knex) {
+  return knex.schema.createTable('userRolesMapping', function(table) {
+    table.string('id', 25).primary();
+    table.string('userId', 25).references('id').inTable('users');
+    table.string('roleId', 25).references('id').inTable('roles');
+    table.boolean('isActive').defaultTo(false);
+    table.timestamp('recordCreatedDate');
+    table.timestamp('recordModifiedDate');
+    table.string('recordCreatedBy', 25);
+    table.string('recordModifiedBy', 25);
+  });
+};
+
+exports.down = function(knex) {
+  return knex.schema.dropTableIfExists('userRolesMapping');
+};

package/migrations/0012_users_add_reset_token.js

@@ -0,0 +1,13 @@
+exports.up = function(knex) {
+  return knex.schema.alterTable('users', function(table) {
+    table.string('resetToken', 255);
+    table.timestamp('resetTokenExpiry');
+  });
+};
+
+exports.down = function(knex) {
+  return knex.schema.alterTable('users', function(table) {
+    table.dropColumn('resetToken');
+    table.dropColumn('resetTokenExpiry');
+  });
+};

package/migrations/0013_add_isPublic.js

@@ -0,0 +1,27 @@
+exports.up = function(knex) {
+  return Promise.all([
+    knex.schema.alterTable('apis', function(table) {
+      table.boolean('isPublic').defaultTo(false);
+    }),
+    knex.schema.alterTable('uiPages', function(table) {
+      table.boolean('isPublic').defaultTo(false);
+    }),
+    knex.schema.alterTable('menus', function(table) {
+      table.boolean('isPublic').defaultTo(false);
+    })
+  ]);
+};
+
+exports.down = function(knex) {
+  return Promise.all([
+    knex.schema.alterTable('apis', function(table) {
+      table.dropColumn('isPublic');
+    }),
+    knex.schema.alterTable('uiPages', function(table) {
+      table.dropColumn('isPublic');
+    }),
+    knex.schema.alterTable('menus', function(table) {
+      table.dropColumn('isPublic');
+    })
+  ]);
+};

package/migrations/0014_users_add_activation_token.js

@@ -0,0 +1,13 @@
+exports.up = function(knex) {
+  return knex.schema.alterTable('users', function(table) {
+    table.string('activationToken', 255);
+    table.string('normalizedEmail', 255).index();
+  });
+};
+
+exports.down = function(knex) {
+  return knex.schema.alterTable('users', function(table) {
+    table.dropColumn('activationToken');
+    table.dropColumn('normalizedEmail');
+  });
+};