@xeplr/auth 1.0.0 → 1.0.2

package/bin/migrate.js

@@ -1,20 +1,38 @@
 #!/usr/bin/env node
 
+// Reads process.env ONLY. The consuming app loads its .env (e.g. via dotenv-cli
+// in the npm script) — @xeplr/* packages never read .env files.
+
 const path = require('path');
-const { up, rollback, status } = require('@xeplr/db').migrator;
+const { up, status } = require('@xeplr/db').sqlMigrator;
+const { resolveConfig, migrationsFor } = require('@xeplr/db');
 
 /**
  * xeplr-auth-migrate
  *
- * Runs auth migrations bundled with this package.
- * Reuses xeplr-db's migrator — no duplicated knex logic.
+ * Runs auth's bundled .sql migrations, followed by the consumer app's
+ * EXTENSION migrations dir (schema + data — auth has no separate seed step;
+ * base data lives in migrations so it runs exactly once). Reuses xeplr-db's
+ * sqlMigrator — hand-written .sql files, no down(), ledger-tracked.
+ *
+ * The app points at its extension dir(s) via env: XEPLR_AUTH_MIGRATIONS
+ * (or --extDir). Base migrations run first, then the extension dir(s) — one
+ * shared ledger, tracked by filename.
+ *
+ * XEPLR_AUTH_MIGRATIONS accepts a COMMA-SEPARATED list, not just one path —
+ * this is how several consuming apps' extension migrations (workflow's,
+ * jobs', BI's own) can all land in the SAME target database from a single
+ * controlled run, without any one app's migrations folder having to contain
+ * another's:
+ *   XEPLR_AUTH_MIGRATIONS=/path/to/bi/migrations-auth,/path/to/workflow/migrations-auth
+ * Sibling apps must keep their migration FILENAMES distinct from each
+ * other's — the ledger is keyed by filename alone, not by which directory it
+ * came from.
  *
  * Usage:
- *   xeplr-auth-migrate up [--db <database>]
- *   xeplr-auth-migrate rollback [--db <database>]
- *   xeplr-auth-migrate status [--db <database>]
+ *   xeplr-auth-migrate up [--extDir <dir>[,<dir>...]] [--db <database>]
+ *   xeplr-auth-migrate status [--extDir <dir>[,<dir>...]] [--db <database>]
  */
-
 function parseArgs(argv) {
   const args = { _: [] };
   for (let i = 0; i < argv.length; i++) {
@@ -33,30 +51,37 @@ async function main() {
   const args = parseArgs(process.argv.slice(2));
   const command = args._[0];
 
-  // Always use bundled migrations directory
+  // Bundled auth migrations (base) + the app's extension migrations dir, which
+  // the app configures ONCE via XEPLR_AUTH_MIGRATIONS (or --extDir). Base runs
+  // first, then the extension — one shared ledger.
   const options = {
     ...args,
-    db: args.db || process.env.DB_AUTH || process.env.DB_NAME,
-    dir: path.join(__dirname, '..', 'migrations')
+    db: args.db || process.env.AUTH_DB_NAME,
+    dir: path.join(__dirname, '..', 'migrations'),
+    // Same convention as every other entry point and every other library —
+    // splitting and existence-checking live in @xeplr/db's
+    // resolveDirectories(), not here. This CLI having had its own parseExtDir
+    // while boot() had none is exactly how the two diverged.
+    extDir: args.extDir || args['ext-dir'] || migrationsFor('auth'),
+    connectionName: args['connection-name'] || args.connectionName || 'auth'
   };
 
+  if (['up', 'status'].indexOf(command) !== -1) {
+    // App tells us which secret to use (decoupled from the connection name):
+    //   --connection <encrypted> | --connection-env <ENV_NAME>. Omit → legacy
+    //   <connectionName>_CONNECTION fallback inside resolveConfig.
+    var connSource = args.connection ||
+      (args['connection-env'] && process.env[args['connection-env']]) || undefined;
+    await resolveConfig(options.connectionName, connSource);
+  }
+
   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:`);
+        console.log(`Ran ${result.migrations.length} migrations:`);
         result.migrations.forEach(m => console.log(`  - ${m}`));
       }
       break;
@@ -71,21 +96,29 @@ async function main() {
       } else {
         console.log('No pending migrations');
       }
+      if (result.drift.length) {
+        console.log('WARNING - applied migrations edited after the fact (checksum mismatch):');
+        result.drift.forEach(m => console.log(`  ! ${m}`));
+      }
       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('  up [--extDir <dir>[,<dir>...]]     Run base + app extension migrations');
+      console.log('  status [--extDir <dir>[,<dir>...]] Show migration status');
+      console.log('');
+      console.log('  App extension dir(s): --extDir or XEPLR_AUTH_MIGRATIONS env (comma-separated for more than one)');
       console.log('');
       console.log('Options:');
-      console.log('  --db        Database name (or DB_AUTH env)');
+      console.log('  --db        Database name (or AUTH_DB_NAME 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)');
+      console.log('');
+      console.log('Migrations are hand-written .sql files (see migrations/), applied once,');
+      console.log('no down(). 0007_seed_super_admin.sql requires SUPER_ADMIN_PASSWORD in env.');
   }
 }
 

package/bin/server.js

@@ -1,35 +1,17 @@
 #!/usr/bin/env node
 
 /**
- * Standalone auth server entry point.
- * Designed to be forked as a child process or run directly.
+ * Standalone auth service. Reads AUTH_* env — the LAUNCHER provides it; this bin
+ * reads process.env only and loads no .env of its own. The consuming app does:
+ *   "start-auth": "dotenv -e development.env -- xeplr-auth-server"
  *
- * Reads config from AUTH_CONFIG env var (JSON) or individual env vars.
+ * env: ENCRYPTION_KEY · AUTH_DB_CONNECTION_INFO_ENCRYPTED · AUTH_DB_NAME ·
+ *      AUTH_JWT_SECRET · AUTH_PORT · AUTH_ACTIVATION_BASE_URL ·
+ *      AUTH_ACCESS_TOKEN_TTL_MINUTES · XEPLR_AUTH_MIGRATIONS · email vars · REDIS_*
  */
-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 });
-}
+require('../index').boot().then(function () {
+  if (process.send) process.send({ status: 'ready' });
+}).catch(function (err) {
+  console.error('[auth] startup failed:', err.stack || err.message);
+  process.exit(1);
+});

package/index.js

@@ -1,12 +1,23 @@
 const path = require('path');
-const { getConnection, bindModels, resolveConfig, migrator } = require('@xeplr/db');
+const { getConnection, bindModels, resolveConfig, sqlMigrator, resolveDbConnection, describeDbConnection, migrationsFor, migrationsVar } = require('@xeplr/db');
+
+// The connection comes from XEPLR_DB_CONNECTION unless this service overrides
+// it with AUTH_DB_CONNECTION_INFO_ENCRYPTED — one server, one credential, with
+// an escape hatch. AUTH_DB_NAME is untouched: which DATABASE is a separate
+// question from where the server is, and auth keeps its own.
+var AUTH_CONN_VAR = 'AUTH_DB_CONNECTION_INFO_ENCRYPTED';
+function authConnection() { return resolveDbConnection(AUTH_CONN_VAR); }
 const { createApp } = require('@xeplr/base-apis');
 const authHelper = require('./lib/authHelper');
+const { seedSuperAdmin } = require('./lib/seed');
 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 ticketService = require('./lib/ticketService');
+const hooks = require('./lib/hooks');
+const mtMembershipMiddleware = require('./lib/mtMembershipMiddleware');
 const createAuthRouter = require('./lib/authRouter');
 const createAdminRouter = require('./lib/adminRouter');
 const models = require('./models');
@@ -23,12 +34,12 @@ let _initialized = false;
  * @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);
+async function init(config = {}) {
+  // One call: decrypt the app-supplied connection, connect, and bind the models.
+  const dbName = config.database || process.env.AUTH_DB_NAME || 'auth';
+  const connection = await getConnection(dbName, config.connection || config.db, {
+    connectionName: config.connectionName || 'auth'
+  });
 
   // Configure JWT
   if (config.jwt) {
@@ -78,8 +89,8 @@ function adminRouter() {
  * @param {Function[]} [config.middleware] - Additional middleware
  * @returns {http.Server}
  */
-function start(config = {}) {
-  init(config);
+async function start(config = {}) {
+  await init(config);
 
   const port = config.port || process.env.AUTH_PORT || 19001;
   const authRouter = createAuthRouter({ resetBaseUrl: config.resetBaseUrl });
@@ -93,63 +104,188 @@ function start(config = {}) {
 }
 
 /**
- * Boot xeplr-auth as a fully independent service.
- * Resolves DB config, runs migrations/seeds, and starts the server.
+ * Boot xeplr-auth as a fully independent service. ENV-DRIVEN — no config; there
+ * is always one auth system, so it reads everything from AUTH_* env. Resolves the
+ * connection, self-migrates, configures email/jwt/activation, 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);
+// Boot the auth service. ENV-DRIVEN, no config — there is always a single auth
+// system, so it reads its whole setup from AUTH_* env (see requiredEnv + README):
+//   connection AUTH_DB_CONNECTION_INFO_ENCRYPTED · db AUTH_DB_NAME · AUTH_JWT_SECRET
+//   AUTH_PORT · AUTH_ACTIVATION_BASE_URL · AUTH_ACCESS_TOKEN_TTL_MINUTES
+//   XEPLR_AUTH_MIGRATIONS · email vars · REDIS_*
+async function boot() {
+  var connName = 'auth';
+  var database = process.env.AUTH_DB_NAME || 'auth';
 
-  await resolveConfig(connName);
+  await resolveConfig(connName, authConnection());
 
-  // Run migrations
-  var migrationResult = await migrator.up({
+  // Self-migrate: auth's own .sql migrations (schema + base data), then the
+  // app's extension dir. Idempotent — same as `xeplr-auth-migrate up`.
+  var migrationResult = await sqlMigrator.up({
     db: database,
-    dir: path.join(authPkgDir, 'migrations'),
-    extDir: config.migrationsDir || null,
+    dir: path.join(__dirname, 'migrations'),
+    // The SHARED convention, not this library's own reading of the variable.
+    // Passing process.env.XEPLR_AUTH_MIGRATIONS straight through is what
+    // broke here: a comma-separated list became one nonexistent directory and
+    // this entry point silently applied none of BI's, workflow's or jobs'
+    // migrations, while the xeplr-auth-migrate CLI — which had its own
+    // splitting — applied all of them. Same variable, two behaviours.
+    extDir: migrationsFor('auth'),
     type: 'precede',
     connectionName: connName
   });
+  console.log(migrationResult.migrations.length
+    ? '[xeplr-auth] ran ' + migrationResult.migrations.length + ' migrations'
+    : '[xeplr-auth] migrations up to date');
 
-  if (migrationResult.migrations.length > 0) {
-    console.log('[xeplr-auth] ran ' + migrationResult.migrations.length + ' migrations');
-  } else {
-    console.log('[xeplr-auth] migrations up to date');
-  }
+  // Configure email (via @xeplr/utils, the engine auth uses) + activation links.
+  require('@xeplr/utils').configureFromEnv();
+  authService.configureActivation({
+    // Fully qualified, one per link — the token is the only thing appended.
+    // AUTH_ACTIVATION_BASE_URL still works as an origin; see configureActivation.
+    activationUrl: process.env.AUTH_ACTIVATION_URL || null,
+    inviteUrl: process.env.AUTH_INVITE_URL || null,
+    baseUrl: process.env.AUTH_ACTIVATION_BASE_URL || null
+  });
 
-  // 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
+  var server = await start({
+    database: database,
+    connectionName: connName,
+    connection: authConnection(),
+    port: process.env.AUTH_PORT,
+    jwt: {
+      secret: process.env.AUTH_JWT_SECRET,
+      accessTokenExpiresIn: (process.env.AUTH_ACCESS_TOKEN_TTL_MINUTES || '15') + 'm'
+    }
   });
 
-  if (seedResult.length > 0) {
-    console.log('[xeplr-auth] ran ' + seedResult.length + ' seeds');
-  }
+  banner();
+  return server;
+}
 
-  return start(Object.assign({ database, connectionName: connName }, config));
+// Startup summary — the EFFECTIVE config (defaults resolved) so you can see what
+// the service is actually running with. Secrets are masked, never printed.
+function banner() {
+  var set = function (v) { return v ? '✓ set' : '✗ MISSING'; };
+  var rows = [
+    ['port',               process.env.AUTH_PORT || '19001'],
+    ['database',           process.env.AUTH_DB_NAME || 'auth'],
+    [migrationsVar('auth'), migrationsFor('auth') || '(none)'],
+    ['activation url',     process.env.AUTH_ACTIVATION_URL || process.env.AUTH_ACTIVATION_BASE_URL || '(none)'],
+    ['invite url',         process.env.AUTH_INVITE_URL || '(derived)'],
+    ['access token ttl',   (process.env.AUTH_ACCESS_TOKEN_TTL_MINUTES || '15') + 'm'],
+    ['refresh token ttl',  (process.env.AUTH_REFRESH_TOKEN_TTL_DAYS || '7') + 'd'],
+    ['slide tolerance',    (process.env.AUTH_ACCESS_TOKEN_TOLERANCE_SECONDS || '0') + 's'],
+    ['max sessions/user',  process.env.AUTH_MAX_SESSIONS_PER_USER || '5'],
+    ['redis',              (process.env.REDIS_HOST || 'localhost') + ':' + (process.env.REDIS_PORT || '6379')],
+    ['email',              process.env.EMAIL_PROVIDER || '(not configured)'],
+    // Names the VARIABLE it resolved through, not just "set" — with a shared
+    // default and a per-service override, "which server am I on" is otherwise
+    // a guess.
+    ['connection',         describeDbConnection(AUTH_CONN_VAR) || '✗ NOT CONFIGURED'],
+    ['encryption key',     set(process.env.ENCRYPTION_KEY)],
+    ['jwt secret',         process.env.AUTH_JWT_SECRET ? '✓ set' : '✗ INSECURE DEFAULT']
+  ];
+  var lines = rows.map(function (r) { return r[0].padEnd(19) + String(r[1]); });
+  var title = 'xeplr-auth · running';
+  var inner = Math.max.apply(null, [title.length].concat(lines.map(function (l) { return l.length; }))) + 2;
+  var bar = '─'.repeat(inner);
+  console.log('\n┌' + bar + '┐');
+  console.log('│ ' + title.padEnd(inner - 1) + '│');
+  console.log('├' + bar + '┤');
+  lines.forEach(function (l) { console.log('│ ' + l.padEnd(inner - 1) + '│'); });
+  console.log('└' + bar + '┘\n');
 }
 
+/**
+ * Attach to the auth database from ANOTHER process (e.g. the api service), so it
+ * can act on auth tables — invite users, assign roles. ENV-DRIVEN
+ * (AUTH_DB_NAME + AUTH_DB_CONNECTION_INFO_ENCRYPTED). Opens a SECONDARY connection
+ * (bind:false, so it never hijacks the api's global model binding) and hands back
+ * model/service accessors.
+ *
+ *   const auth = require('@xeplr/auth').attach();
+ *   await auth.ready();
+ *   await auth.model('User').query()...      // auth-package model bound to the auth DB
+ *   auth.service.invite(...)                  // authService
+ *
+ * @returns {{ ready: () => Promise, conn: () => Knex, model: (name:string) => Model, service: object }}
+ */
+function attach() {
+  var _conn = null;
+  var _ready = (async function () {
+    _conn = await getConnection(
+      process.env.AUTH_DB_NAME || 'auth',
+      authConnection(),
+      { bind: false, connectionName: 'auth' }
+    );
+    authService.configureActivation({
+    // Fully qualified, one per link — the token is the only thing appended.
+    // AUTH_ACTIVATION_BASE_URL still works as an origin; see configureActivation.
+    activationUrl: process.env.AUTH_ACTIVATION_URL || null,
+    inviteUrl: process.env.AUTH_INVITE_URL || null,
+    baseUrl: process.env.AUTH_ACTIVATION_BASE_URL || null
+  });
+    return _conn;
+  })();
+
+  function conn() {
+    if (!_conn) throw new Error('auth.attach(): connection not ready — await ready() first');
+    return _conn;
+  }
+  function model(name) {
+    var M = models[name];
+    if (!M) throw new Error('auth.attach(): unknown auth model "' + name + '"');
+    return M.bindKnex(conn());
+  }
+  return { ready: function () { return _ready; }, conn: conn, model: model, service: authService };
+}
+
+// Env vars this library needs — apps spread this into their env.required.js so
+// the names live here (change once, every app picks it up), not re-listed per app.
+var requiredEnv = [
+  'ENCRYPTION_KEY',
+  'AUTH_JWT_SECRET',
+  // NOT listed literally: the activation link can be given either as
+  // AUTH_ACTIVATION_URL (fully qualified, preferred) or as the older
+  // AUTH_ACTIVATION_BASE_URL (an origin). checkEnv takes a list of names and
+  // demands every one, which would refuse to boot an install that configured
+  // the new form. The getter below asks for whichever is actually in use.
+  'AUTH_PORT',
+  'AUTH_DB_NAME',                        // auth db (api reaches it via attach())
+  'XEPLR_AUTH_MIGRATIONS',             // migrations run via migrate:up
+];
+
+// Read at ACCESS time so it reflects the .env the app has already loaded — the
+// same reason @xeplr/email's requiredEnv is a getter. Names the form the
+// install is actually using, and asks for the new one when neither is set.
+Object.defineProperty(requiredEnv, 'activationLinkVar', {
+  enumerable: false,
+  get: function () {
+    return process.env.AUTH_ACTIVATION_BASE_URL && !process.env.AUTH_ACTIVATION_URL
+      ? 'AUTH_ACTIVATION_BASE_URL'
+      : 'AUTH_ACTIVATION_URL';
+  }
+});
+
+// NOT in requiredEnv, deliberately: AUTH_DB_CONNECTION_INFO_ENCRYPTED is now an
+// OVERRIDE. The connection normally comes from the shared XEPLR_DB_CONNECTION,
+// so demanding the auth-specific name would fail a correctly configured
+// install. Missing-ness is caught at the point of use by resolveDbConnection,
+// which names both variables.
+//
+// AUTH_DB_NAME stays required and stays auth's own — the DATABASE is a
+// different question from the SERVER, and services do not share one.
+
 module.exports = {
+  // Hand in @xeplr-workflow/api's resumeByKey to release a step that is
+  // waiting for someone to activate. Omitted, activation just activates.
+  configureWorkflowResume: authService.configureWorkflowResume,
+  requiredEnv,
   init,
+  attach,
   router,
   adminRouter,
   start,
@@ -157,9 +293,13 @@ module.exports = {
   authMiddleware,
   accessMiddleware,
   requireRole,
+  mtMembershipMiddleware,
   authHelper,
+  seedSuperAdmin,
   authService,
   accessService,
   sessionService,
+  ticketService,
+  hooks,
   models
 };