@xeplr/auth 1.0.1 → 1.0.2

package/bin/migrate.js

@@ -5,7 +5,7 @@
 
 const path = require('path');
 const { up, status } = require('@xeplr/db').sqlMigrator;
-const { resolveConfig } = require('@xeplr/db');
+const { resolveConfig, migrationsFor } = require('@xeplr/db');
 
 /**
  * xeplr-auth-migrate
@@ -15,14 +15,24 @@ const { resolveConfig } = require('@xeplr/db');
  * 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 ONCE via env: AUTH_EXT_MIGRATIONS_DIR
- * (or --extDir). Base migrations run first, then the app's — one ledger.
+ * 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 [--extDir <dir>] [--db <database>]
- *   xeplr-auth-migrate status [--extDir <dir>] [--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++) {
@@ -42,13 +52,17 @@ async function main() {
   const command = args._[0];
 
   // Bundled auth migrations (base) + the app's extension migrations dir, which
-  // the app configures ONCE via AUTH_EXT_MIGRATIONS_DIR (or --extDir). Base runs
+  // 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.AUTH_DB_NAME,
     dir: path.join(__dirname, '..', 'migrations'),
-    extDir: args.extDir || args['ext-dir'] || process.env.AUTH_EXT_MIGRATIONS_DIR,
+    // 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'
   };
 
@@ -92,10 +106,10 @@ async function main() {
       console.log('xeplr-auth-migrate - Auth database migrations');
       console.log('');
       console.log('Commands:');
-      console.log('  up [--extDir <dir>]     Run base + app extension migrations');
-      console.log('  status [--extDir <dir>] 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: --extDir or AUTH_EXT_MIGRATIONS_DIR env');
+      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 AUTH_DB_NAME env)');

package/bin/server.js

@@ -7,7 +7,7 @@
  *
  * 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 · AUTH_EXT_MIGRATIONS_DIR · email vars · REDIS_*
+ *      AUTH_ACCESS_TOKEN_TTL_MINUTES · XEPLR_AUTH_MIGRATIONS · email vars · REDIS_*
  */
 require('../index').boot().then(function () {
   if (process.send) process.send({ status: 'ready' });

package/index.js

@@ -1,5 +1,12 @@
 const path = require('path');
-const { getConnection, bindModels, resolveConfig, sqlMigrator } = 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');
@@ -107,19 +114,25 @@ async function start(config = {}) {
 // 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
-//   AUTH_EXT_MIGRATIONS_DIR · email vars · REDIS_*
+//   XEPLR_AUTH_MIGRATIONS · email vars · REDIS_*
 async function boot() {
   var connName = 'auth';
   var database = process.env.AUTH_DB_NAME || 'auth';
 
-  await resolveConfig(connName, process.env.AUTH_DB_CONNECTION_INFO_ENCRYPTED);
+  await resolveConfig(connName, authConnection());
 
   // 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(__dirname, 'migrations'),
-    extDir: process.env.AUTH_EXT_MIGRATIONS_DIR || null,
+    // 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
   });
@@ -129,12 +142,18 @@ async function boot() {
 
   // Configure email (via @xeplr/utils, the engine auth uses) + activation links.
   require('@xeplr/utils').configureFromEnv();
-  if (process.env.AUTH_ACTIVATION_BASE_URL) authService.configureActivation(process.env.AUTH_ACTIVATION_BASE_URL);
+  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
+  });
 
   var server = await start({
     database: database,
     connectionName: connName,
-    connection: process.env.AUTH_DB_CONNECTION_INFO_ENCRYPTED,
+    connection: authConnection(),
     port: process.env.AUTH_PORT,
     jwt: {
       secret: process.env.AUTH_JWT_SECRET,
@@ -153,15 +172,19 @@ function banner() {
   var rows = [
     ['port',               process.env.AUTH_PORT || '19001'],
     ['database',           process.env.AUTH_DB_NAME || 'auth'],
-    ['ext migrations',     process.env.AUTH_EXT_MIGRATIONS_DIR || '(none)'],
-    ['activation url',     process.env.AUTH_ACTIVATION_BASE_URL || '(none)'],
+    [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)'],
-    ['connection',         set(process.env.AUTH_DB_CONNECTION_INFO_ENCRYPTED)],
+    // 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']
   ];
@@ -195,10 +218,16 @@ function attach() {
   var _ready = (async function () {
     _conn = await getConnection(
       process.env.AUTH_DB_NAME || 'auth',
-      process.env.AUTH_DB_CONNECTION_INFO_ENCRYPTED,
+      authConnection(),
       { bind: false, connectionName: 'auth' }
     );
-    if (process.env.AUTH_ACTIVATION_BASE_URL) authService.configureActivation(process.env.AUTH_ACTIVATION_BASE_URL);
+    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;
   })();
 
@@ -219,14 +248,41 @@ function attach() {
 var requiredEnv = [
   'ENCRYPTION_KEY',
   'AUTH_JWT_SECRET',
-  'AUTH_ACTIVATION_BASE_URL',
+  // 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())
-  'AUTH_DB_CONNECTION_INFO_ENCRYPTED',   // auth DB login (for attach())
-  'AUTH_EXT_MIGRATIONS_DIR',             // migrations run via migrate:up
+  '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,

package/lib/authRouter.js

@@ -48,7 +48,10 @@ function createAuthRouter(options = {}) {
         return res.status(400).json({ error: 'Activation token is required' });
       }
 
-      var result = await activate(token);
+      // Carried in the activation LINK and handed straight back — see
+      // authService.register. If a workflow is waiting on this person, this is
+      // the key that releases it.
+      var result = await activate(token, { workflowKey: req.query.workflowKey });
       res.json({ message: 'Account activated successfully', user: result });
     } catch (err) {
       logError(req, err);

package/lib/authService.js

@@ -7,13 +7,92 @@ const { getUserAccess, clearUserAccess } = require('./accessService');
 const { createSession, destroyAllUserSessions } = require('./sessionService');
 const hooks = require('./hooks');
 
-let _activationBaseUrl = null;
+// WHERE THE LINKS IN OUR EMAILS POINT.
+//
+// FULLY QUALIFIED, one per link, because these strings do not only end up in a
+// string concatenation here — they are handed to the email/template layer,
+// where the token can travel as a variable but the URL cannot. A template that
+// has to know to append '/auth/activate' to something called a "base" is a
+// template that knows about this package's routing.
+//
+// The old AUTH_ACTIVATION_BASE_URL still works: given an origin, the default
+// path for each link is appended, exactly as before. It served both the
+// activation and the invite page, which is precisely why one fully-qualified
+// value could not replace it.
+var _links = { activationUrl: null, inviteUrl: null, baseUrl: null };
+
+var DEFAULT_PATHS = { activation: '/auth/activate', invite: '/auth/accept-invite' };
+
+// RESUMING A WORKFLOW ON ACTIVATION.
+//
+// A registration can be one step of a longer process — "invite them, wait for
+// them to activate, then grant the roles" — and a workflow step that waits is
+// released by its resumeKey (@xeplr-workflow/api's resumeByKey).
+//
+// INJECTED, not required. This package sits underneath every product here and
+// must not depend on one of them; a host that runs workflows hands the
+// function in at boot, and an install without workflow simply never sets it
+// and never sees the feature. Same shape as configureEmail above.
+var _resumeWorkflowByKey = null;
+
+function configureWorkflowResume(fn) {
+  _resumeWorkflowByKey = typeof fn === 'function' ? fn : null;
+}
+
+/**
+ * Best-effort, and deliberately so.
+ *
+ * The account IS activated by the time this runs. If the workflow cannot be
+ * resumed — no such key, the run already moved on, workflow is down — that is
+ * a problem with the workflow, not with the person who just clicked the link
+ * in their email. Failing the activation over it would lock them out of an
+ * account that is already open.
+ */
+async function resumeWorkflow(workflowKey, output) {
+  if (!workflowKey || !_resumeWorkflowByKey) return null;
+  try {
+    return await _resumeWorkflowByKey(workflowKey, output);
+  } catch (err) {
+    // Through @xeplr/logs, which is what routes an error onto the host's
+    // problem list (see xeplr-bi's errorEvents) — a workflow that silently
+    // never resumed is exactly the kind of thing nobody goes looking for.
+    require('@xeplr/logs').createLogger('auth')
+      .error('could not resume workflow "' + workflowKey + '": ' + err.message);
+    return null;
+  }
+}
 
-function configureActivation(baseUrl) {
-  _activationBaseUrl = baseUrl;
+/**
+ * @param {string|object} config - a legacy origin string, or
+ *   { activationUrl, inviteUrl, baseUrl }.
+ */
+function configureActivation(config) {
+  if (typeof config === 'string') { _links.baseUrl = config; return; }
+  if (!config) return;
+  if (config.activationUrl !== undefined) _links.activationUrl = config.activationUrl;
+  if (config.inviteUrl !== undefined) _links.inviteUrl = config.inviteUrl;
+  if (config.baseUrl !== undefined) _links.baseUrl = config.baseUrl;
 }
 
-async function register({ email, phoneNumber, name, password, knex }) {
+function linkFor(kind) {
+  var explicit = kind === 'activation'
+    ? (_links.activationUrl || process.env.AUTH_ACTIVATION_URL)
+    : (_links.inviteUrl || process.env.AUTH_INVITE_URL);
+  if (explicit) return explicit;
+
+  var base = _links.baseUrl || process.env.AUTH_ACTIVATION_BASE_URL;
+  if (!base) return null;
+  // Trailing slashes are the most common way a hand-edited .env produces a
+  // double slash in a link somebody then reports as broken.
+  return String(base).replace(/\/+$/, '') + DEFAULT_PATHS[kind];
+}
+
+/** Append the token, respecting a URL that already carries a query string. */
+function withToken(url, token) {
+  return url + (url.indexOf('?') === -1 ? '?' : '&') + 'token=' + token;
+}
+
+async function register({ email, phoneNumber, name, password, workflowKey, knex }) {
   const UserM = knex ? User.bindKnex(knex) : User;
   const normalized = normalizeEmail(email);
 
@@ -47,12 +126,17 @@ async function register({ email, phoneNumber, name, password, knex }) {
   });
 
   // Send activation email
-  const baseUrl = _activationBaseUrl || process.env.AUTH_ACTIVATION_BASE_URL;
-  if (!baseUrl) {
-    throw new Error('ACTIVATION_BASE_URL is required. Cannot register without email activation.');
+  const activationUrl = linkFor('activation');
+  if (!activationUrl) {
+    throw new Error('AUTH_ACTIVATION_URL is required (the full address of your activation page, ' +
+      'e.g. http://localhost:19100/auth/activate). Cannot register without email activation.');
   }
 
-  const activationLink = baseUrl + '/auth/activate?token=' + activationToken;
+  // The key rides along in the link so it comes back to us when the user
+  // clicks — there is nowhere else to keep it: activation happens in a
+  // different browser, days later, with no session.
+  var activationLink = withToken(activationUrl, activationToken);
+  if (workflowKey) activationLink += '&workflowKey=' + encodeURIComponent(workflowKey);
   const html = '<h2>Activate your account</h2>'
     + '<p>Hi ' + (name || 'there') + ',</p>'
     + '<p>Click below to activate your account:</p>'
@@ -72,16 +156,29 @@ async function register({ email, phoneNumber, name, password, knex }) {
   };
 }
 
-async function activate(token) {
+async function activate(token, options) {
+  var workflowKey = options && options.workflowKey;
+  var log = require('@xeplr/logs').createLogger('auth');
+
+  // THE TOKEN IS NEVER LOGGED. It is a bearer credential — anyone holding the
+  // string can activate that account — and a log line is the one place it
+  // would sit in plain text long after the token itself was nulled. That a
+  // token arrived, and how it ended, is what is worth recording.
+  log.info('activation: token received' + (workflowKey ? ', workflowKey "' + workflowKey + '"' : ', no workflowKey'));
+
   const user = await User.query().findOne({ activationToken: token });
   if (!user) {
+    log.warn('activation: no user holds that token — expired, already used, or wrong link');
     throw new Error('Invalid activation token');
   }
 
   if (user.isActivated) {
+    log.info('activation: ' + user.email + ' is already activated — nothing to do');
     throw new Error('Account already activated');
   }
 
+  log.info('activation: activating ' + user.email);
+
   const now = formatDbDateTime();
   await User.query().findById(user.id).patch({
     isActivated: true,
@@ -90,8 +187,23 @@ async function activate(token) {
     recordModifiedDate: now
   });
 
+  log.important('activation: ' + user.email + ' activated');
   await hooks.fire('user', 'update', user.id);
 
+  // AFTER the patch, never before: a workflow released by this step may go on
+  // to grant roles or send a welcome mail, and it must not act on an account
+  // that has not actually been activated yet.
+  if (workflowKey) {
+    log.info('activation: resuming workflow "' + workflowKey + '"');
+    var resumed = await resumeWorkflow(workflowKey,
+      { userId: user.id, email: user.email, name: user.name });
+    if (resumed) {
+      log.important('activation: workflow "' + workflowKey + '" resumed (run ' +
+        (resumed.runId || '?') + ', step ' + (resumed.stepKey || '?') + ')');
+    }
+    // The failure path already logged its own reason inside resumeWorkflow.
+  }
+
   return { id: user.id, email: user.email, name: user.name };
 }
 
@@ -194,12 +306,13 @@ async function invite({ email, name, phoneNumber, invitedBy, inviterName, appNam
     recordModifiedBy: inviter
   });
 
-  const baseUrl = _activationBaseUrl || process.env.AUTH_ACTIVATION_BASE_URL;
-  if (!baseUrl) {
-    throw new Error('ACTIVATION_BASE_URL is required to send invite emails.');
+  const inviteUrl = linkFor('invite');
+  if (!inviteUrl) {
+    throw new Error('AUTH_INVITE_URL is required to send invite emails (the full address of your ' +
+      'accept-invite page, e.g. http://localhost:19100/auth/accept-invite).');
   }
 
-  const acceptLink = baseUrl + '/auth/accept-invite?token=' + activationToken;
+  const acceptLink = withToken(inviteUrl, activationToken);
   const app = appName || 'the app';
   const subject = 'You have been invited to ' + app;
   const html = '<h2>You have been invited</h2>'
@@ -494,6 +607,7 @@ async function changePassword(userId, { oldPassword, newPassword }) {
 
 module.exports = {
   configureActivation,
+  configureWorkflowResume,
   configureEmail,
   register,
   activate,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/auth",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Pluggable authentication service: register, login, forgot/reset password, RBAC, multi-tenancy",
   "main": "index.js",
   "files": [