@xeplr/auth 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Xeplr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/bin/migrate.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+
+const path = require('path');
+const { up, rollback, status } = require('@xeplr/db').migrator;
+
+/**
+ * xeplr-auth-migrate
+ *
+ * Runs auth migrations bundled with this package.
+ * Reuses xeplr-db's migrator — no duplicated knex logic.
+ *
+ * Usage:
+ *   xeplr-auth-migrate up [--db <database>]
+ *   xeplr-auth-migrate rollback [--db <database>]
+ *   xeplr-auth-migrate status [--db <database>]
+ */
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i].startsWith('--')) {
+      const key = argv[i].slice(2);
+      args[key] = argv[i + 1] || true;
+      i++;
+    } else {
+      args._.push(argv[i]);
+    }
+  }
+  return args;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const command = args._[0];
+
+  // Always use bundled migrations directory
+  const options = {
+    ...args,
+    db: args.db || process.env.DB_AUTH || process.env.DB_NAME,
+    dir: path.join(__dirname, '..', 'migrations')
+  };
+
+  switch (command) {
+    case 'up': {
+      const result = await up(options);
+      if (result.migrations.length === 0) {
+        console.log('Already up to date');
+      } else {
+        console.log(`Batch ${result.batch} ran ${result.migrations.length} migrations:`);
+        result.migrations.forEach(m => console.log(`  - ${m}`));
+      }
+      break;
+    }
+    case 'rollback': {
+      const result = await rollback(options);
+      if (result.migrations.length === 0) {
+        console.log('Nothing to rollback');
+      } else {
+        console.log(`Rolled back ${result.migrations.length} migrations:`);
+        result.migrations.forEach(m => console.log(`  - ${m}`));
+      }
+      break;
+    }
+    case 'status': {
+      const result = await status(options);
+      console.log('Completed migrations:');
+      result.completed.forEach(m => console.log(`  ✓ ${m}`));
+      if (result.pending.length) {
+        console.log('Pending migrations:');
+        result.pending.forEach(m => console.log(`  ○ ${m}`));
+      } else {
+        console.log('No pending migrations');
+      }
+      break;
+    }
+    default:
+      console.log('xeplr-auth-migrate - Auth database migrations');
+      console.log('');
+      console.log('Commands:');
+      console.log('  up [--db <name>]       Run pending migrations');
+      console.log('  rollback [--db <name>]  Rollback last batch');
+      console.log('  status [--db <name>]    Show migration status');
+      console.log('');
+      console.log('Options:');
+      console.log('  --db        Database name (or DB_AUTH env)');
+      console.log('  --host      DB host (default: DB_HOST env or localhost)');
+      console.log('  --user      DB user (default: DB_USER env or root)');
+      console.log('  --password  DB password (default: DB_PASSWORD env)');
+  }
+}
+
+main().catch(err => {
+  console.error(err.message);
+  process.exit(1);
+});

package/bin/server.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+
+/**
+ * Standalone auth server entry point.
+ * Designed to be forked as a child process or run directly.
+ *
+ * Reads config from AUTH_CONFIG env var (JSON) or individual env vars.
+ */
+var auth = require('../index');
+
+var config = {};
+
+if (process.env.AUTH_CONFIG) {
+  try {
+    config = JSON.parse(process.env.AUTH_CONFIG);
+  } catch (e) {
+    console.error('Failed to parse AUTH_CONFIG:', e.message);
+    process.exit(1);
+  }
+}
+
+config.port = config.port || process.env.AUTH_PORT || 19001;
+config.database = config.database || process.env.DB_AUTH || 'architects_auth';
+
+if (process.env.JWT_SECRET) {
+  config.jwt = config.jwt || {};
+  config.jwt.secret = config.jwt.secret || process.env.JWT_SECRET;
+}
+
+auth.start(config);
+
+// Notify parent process (if forked) that auth is ready
+if (process.send) {
+  process.send({ status: 'ready', port: config.port });
+}

package/index.js

@@ -0,0 +1,165 @@
+const path = require('path');
+const { getConnection, bindModels, resolveConfig, migrator } = require('@xeplr/db');
+const { createApp } = require('@xeplr/base-apis');
+const authHelper = require('./lib/authHelper');
+const authMiddleware = require('./lib/authMiddleware');
+const authService = require('./lib/authService');
+const accessService = require('./lib/accessService');
+const { accessMiddleware, requireRole } = require('./lib/accessMiddleware');
+const sessionService = require('./lib/sessionService');
+const createAuthRouter = require('./lib/authRouter');
+const createAdminRouter = require('./lib/adminRouter');
+const models = require('./models');
+
+let _initialized = false;
+
+/**
+ * Initialize xeplr-auth.
+ *
+ * @param {object} config
+ * @param {string} config.database - Database name for auth tables
+ * @param {object} [config.db] - DB connection options { host, user, password, port }
+ * @param {object} [config.jwt] - JWT options { secret, expiresIn }
+ * @param {object} [config.email] - Email config { provider, smtp, aws, azure, brevo }
+ * @param {string} [config.resetBaseUrl] - Base URL for password reset links
+ */
+function init(config = {}) {
+  // Setup database connection
+  const dbName = config.database || process.env.DB_AUTH || 'auth';
+  const dbOptions = Object.assign({ connectionName: config.connectionName || 'auth' }, config.db || {});
+  const connection = getConnection(dbName, dbOptions);
+  bindModels(connection);
+
+  // Configure JWT
+  if (config.jwt) {
+    authHelper.configure({
+      jwtSecret: config.jwt.secret,
+      accessTokenExpiresIn: config.jwt.accessTokenExpiresIn || '15m'
+    });
+  }
+
+  // Configure email provider
+  if (config.email) {
+    authService.configureEmail(config.email);
+  }
+
+  _initialized = true;
+
+  return connection;
+}
+
+/**
+ * Get the Express router for auth API endpoints.
+ * Must call init() first.
+ *
+ * @param {object} [options]
+ * @param {string} [options.resetBaseUrl] - Override reset password base URL
+ */
+function router(options = {}) {
+  return createAuthRouter(options);
+}
+
+function adminRouter() {
+  return createAdminRouter();
+}
+
+/**
+ * Start xeplr-auth as a standalone Express API server.
+ * Calls init() internally, then boots Express via xeplr-base-apis.
+ *
+ * @param {object} config
+ * @param {number|string} config.port - Port to listen on (default: AUTH_PORT env or 19001)
+ * @param {string} [config.database] - Database name
+ * @param {object} [config.db] - DB connection options
+ * @param {object} [config.jwt] - JWT options
+ * @param {string} [config.emailServiceUrl] - URL of xeplr-email service
+ * @param {string} [config.resetBaseUrl] - Base URL for reset links
+ * @param {object} [config.corsOptions] - CORS options
+ * @param {Function[]} [config.middleware] - Additional middleware
+ * @returns {http.Server}
+ */
+function start(config = {}) {
+  init(config);
+
+  const port = config.port || process.env.AUTH_PORT || 19001;
+  const authRouter = createAuthRouter({ resetBaseUrl: config.resetBaseUrl });
+  const adminRtr = createAdminRouter();
+
+  return createApp(port, 'xeplr-auth', {
+    corsOptions: config.corsOptions,
+    middleware: config.middleware,
+    routes: { '/auth/api': authRouter, '/auth/api/admin': adminRtr }
+  });
+}
+
+/**
+ * Boot xeplr-auth as a fully independent service.
+ * Resolves DB config, runs migrations/seeds, and starts the server.
+ *
+ * @param {object} config
+ * @param {number|string} config.port - Port to listen on (default: AUTH_PORT env or 19001)
+ * @param {string} config.database - Database name for auth tables
+ * @param {string} [config.connectionName] - Named connection identifier (default: 'auth')
+ * @param {object} [config.db] - DB connection options { host, user, password, port }
+ * @param {object} [config.jwt] - JWT options { secret, accessTokenExpiresIn }
+ * @param {object} [config.email] - Email config { provider, smtp, aws, azure, brevo }
+ * @param {string} [config.resetBaseUrl] - Base URL for reset links
+ * @param {string} [config.migrationsDir] - Additional project-specific migrations directory
+ * @param {string} [config.seedsDir] - Additional project-specific seeds directory
+ * @param {object} [config.corsOptions] - CORS options
+ * @param {Function[]} [config.middleware] - Additional middleware
+ * @returns {Promise<http.Server>}
+ */
+async function boot(config = {}) {
+  var connName = config.connectionName || 'auth';
+  var database = config.database || process.env.DB_AUTH || 'auth';
+  var authPkgDir = path.join(__dirname);
+
+  await resolveConfig(connName);
+
+  // Run migrations
+  var migrationResult = await migrator.up({
+    db: database,
+    dir: path.join(authPkgDir, 'migrations'),
+    extDir: config.migrationsDir || null,
+    type: 'precede',
+    connectionName: connName
+  });
+
+  if (migrationResult.migrations.length > 0) {
+    console.log('[xeplr-auth] ran ' + migrationResult.migrations.length + ' migrations');
+  } else {
+    console.log('[xeplr-auth] migrations up to date');
+  }
+
+  // Run seeds (auth's own seeds always run, project seeds if provided)
+  var seedResult = await migrator.seed({
+    db: database,
+    seedsDir: path.join(authPkgDir, 'seeds'),
+    extSeedsDir: config.seedsDir || null,
+    type: 'precede',
+    connectionName: connName
+  });
+
+  if (seedResult.length > 0) {
+    console.log('[xeplr-auth] ran ' + seedResult.length + ' seeds');
+  }
+
+  return start(Object.assign({ database, connectionName: connName }, config));
+}
+
+module.exports = {
+  init,
+  router,
+  adminRouter,
+  start,
+  boot,
+  authMiddleware,
+  accessMiddleware,
+  requireRole,
+  authHelper,
+  authService,
+  accessService,
+  sessionService,
+  models
+};

package/lib/accessMiddleware.js

@@ -0,0 +1,79 @@
+const { verifyToken } = require('./authHelper');
+const { getApiRule, userHasApiAccess } = require('./accessService');
+
+/**
+ * Access-aware middleware.
+ * Uses Redis-cached API rules: isPublic → unmapped → role check.
+ *
+ * Usage:
+ *   app.use('/api', accessMiddleware());
+ *
+ * Options:
+ *   apiNameResolver(req) - function that returns the API name to check.
+ *                          Defaults to req.baseUrl + req.path (e.g. "/api/orders")
+ */
+function accessMiddleware(options = {}) {
+  const resolveApiName = options.apiNameResolver || ((req) => {
+    return (req.baseUrl + req.path).replace(/\/+$/, '') || '/';
+  });
+
+  return async function(req, res, next) {
+    const apiName = resolveApiName(req);
+
+    // Single cached lookup for API rule (public flag + role IDs)
+    const rule = await getApiRule(apiName);
+
+    // Not in DB, or marked public, or no role mappings = open
+    if (!rule.exists || rule.isPublic || rule.unmapped) return next();
+
+    // From here, auth is required
+    const authHeader = req.headers.authorization;
+    if (!authHeader || !authHeader.startsWith('Bearer ')) {
+      return res.status(401).json({ error: 'No token provided' });
+    }
+
+    const token = authHeader.split(' ')[1];
+    let decoded;
+    try {
+      decoded = verifyToken(token);
+    } catch (err) {
+      return res.status(401).json({ error: 'Invalid or expired token' });
+    }
+
+    req.user = decoded;
+
+    // Check role-based access (also cached)
+    const hasAccess = await userHasApiAccess(decoded.id, apiName);
+    if (!hasAccess) {
+      return res.status(403).json({ error: 'Access denied' });
+    }
+
+    next();
+  };
+}
+
+/**
+ * Simple role-check middleware (no DB lookup, uses roles from JWT or req.user).
+ * Use after authMiddleware.
+ *
+ * Usage:
+ *   app.use('/admin', authMiddleware, requireRole('admin'));
+ */
+function requireRole(...roles) {
+  return function(req, res, next) {
+    if (!req.user || !req.user.roles) {
+      return res.status(403).json({ error: 'Access denied' });
+    }
+
+    const userRoles = Array.isArray(req.user.roles) ? req.user.roles : [];
+    const hasRole = roles.some(r => userRoles.includes(r));
+
+    if (!hasRole) {
+      return res.status(403).json({ error: 'Access denied' });
+    }
+
+    next();
+  };
+}
+
+module.exports = { accessMiddleware, requireRole };

package/lib/accessService.js

@@ -0,0 +1,188 @@
+const { cache } = require('@xeplr/utils');
+const User = require('../models/User');
+const Api = require('../models/Api');
+const UiPage = require('../models/UiPage');
+const Menu = require('../models/Menu');
+const UiElement = require('../models/UiElement');
+
+// Cache TTLs (seconds)
+const USER_ACCESS_TTL = 300;    // 5 min — user's full access object
+const API_RULES_TTL = 600;      // 10 min — api public/role data (changes rarely)
+
+// Cache key helpers
+const userAccessKey = (userId) => `access:user:${userId}`;
+const apiRulesKey = (apiName) => `access:api:${encodeURIComponent(apiName)}`;
+const publicItemsKey = 'access:public';
+
+/**
+ * Fetch the full access object for a user.
+ * Cached in Redis. Use clearUserAccess() to invalidate.
+ */
+async function getUserAccess(userId) {
+  // Check cache first
+  const cached = await cache.get(userAccessKey(userId));
+  if (cached) return cached;
+
+  const user = await User.query()
+    .findById(userId)
+    .withGraphFetched('roles.[apis, uiPages, uiElements, menus]');
+
+  if (!user || !user.roles) {
+    const empty = { roles: [], pages: [], apis: [], menus: [], elements: [] };
+    await cache.set(userAccessKey(userId), empty, USER_ACCESS_TTL);
+    return empty;
+  }
+
+  const roleNames = new Set();
+  const pages = new Set();
+  const apis = new Set();
+  const menus = new Set();
+  const elements = new Set();
+
+  for (const role of user.roles) {
+    roleNames.add(role.name);
+
+    if (role.apis) {
+      for (const api of role.apis) apis.add(api.name);
+    }
+    if (role.uiPages) {
+      for (const page of role.uiPages) pages.add(page.name);
+    }
+    if (role.menus) {
+      for (const menu of role.menus) menus.add(menu.name);
+    }
+    if (role.uiElements) {
+      for (const el of role.uiElements) elements.add(el.name);
+    }
+  }
+
+  // Add public items
+  const publicItems = await getPublicItems();
+  for (const api of publicItems.apis) apis.add(api);
+  for (const page of publicItems.pages) pages.add(page);
+  for (const menu of publicItems.menus) menus.add(menu);
+
+  const access = {
+    roles: [...roleNames],
+    pages: [...pages],
+    apis: [...apis],
+    menus: [...menus],
+    elements: [...elements]
+  };
+
+  await cache.set(userAccessKey(userId), access, USER_ACCESS_TTL);
+  return access;
+}
+
+/**
+ * Get all public items (cached separately, shared across users).
+ */
+async function getPublicItems() {
+  const cached = await cache.get(publicItemsKey);
+  if (cached) return cached;
+
+  const [publicApis, publicPages, publicMenus] = await Promise.all([
+    Api.query().where({ isPublic: 1 }),
+    UiPage.query().where({ isPublic: 1 }),
+    Menu.query().where({ isPublic: 1 })
+  ]);
+
+  const result = {
+    apis: publicApis.map(a => a.name),
+    pages: publicPages.map(p => p.name),
+    menus: publicMenus.map(m => m.name)
+  };
+
+  await cache.set(publicItemsKey, result, API_RULES_TTL);
+  return result;
+}
+
+/**
+ * Get cached API rule (public flag + role IDs).
+ * Avoids repeated DB lookups in middleware.
+ */
+async function getApiRule(apiName) {
+  const cacheKey = apiRulesKey(apiName);
+  const cached = await cache.get(cacheKey);
+  if (cached) return cached;
+
+  const api = await Api.query()
+    .findOne({ name: apiName })
+    .withGraphFetched('roles');
+
+  if (!api) {
+    // Not registered = open
+    const rule = { exists: false, isPublic: true, roleIds: [] };
+    await cache.set(cacheKey, rule, API_RULES_TTL);
+    return rule;
+  }
+
+  const roleIds = (api.roles || []).map(r => r.id);
+  const rule = {
+    exists: true,
+    isPublic: !!api.isPublic,
+    unmapped: roleIds.length === 0,
+    roleIds
+  };
+
+  await cache.set(cacheKey, rule, API_RULES_TTL);
+  return rule;
+}
+
+/**
+ * Check if a user has access to a specific API.
+ * Uses cached API rules and cached user roles.
+ */
+async function userHasApiAccess(userId, apiName) {
+  const rule = await getApiRule(apiName);
+
+  // Not registered in DB, or marked public, or no role mappings = open
+  if (!rule.exists || rule.isPublic || rule.unmapped) return true;
+
+  // Get user's role IDs (from user access cache)
+  const userRoleCacheKey = `access:userRoles:${userId}`;
+  let userRoleIds = await cache.get(userRoleCacheKey);
+
+  if (!userRoleIds) {
+    const user = await User.query()
+      .findById(userId)
+      .withGraphFetched('roles');
+
+    userRoleIds = (user && user.roles) ? user.roles.map(r => r.id) : [];
+    await cache.set(userRoleCacheKey, userRoleIds, USER_ACCESS_TTL);
+  }
+
+  const userRoleSet = new Set(userRoleIds);
+  return rule.roleIds.some(id => userRoleSet.has(id));
+}
+
+/**
+ * Clear all cached access data for a user.
+ * Call this on login so the user gets fresh permissions.
+ */
+async function clearUserAccess(userId) {
+  await Promise.all([
+    cache.del(userAccessKey(userId)),
+    cache.del(`access:userRoles:${userId}`)
+  ]);
+}
+
+/**
+ * Clear all cached API rules and public items.
+ * Call this when you modify role mappings, isPublic flags, etc.
+ */
+async function clearAccessRules() {
+  await Promise.all([
+    cache.del(publicItemsKey),
+    cache.delPattern('access:api:*')
+  ]);
+}
+
+module.exports = {
+  getUserAccess,
+  userHasApiAccess,
+  clearUserAccess,
+  clearAccessRules,
+  getApiRule,
+  getPublicItems
+};