X-Git-Url: https://git.squeep.com/?p=squeep-authentication-module;a=blobdiff_plain;f=lib%2Fauthenticator.js;fp=lib%2Fauthenticator.js;h=7390db5d8803c8271e0cbc32c254e3198d057df0;hp=da6b7180f4c4e8019d6f2bed82063d4ea057ba71;hb=53ef948ea83106e82d55e60d6695a15e94bf725e;hpb=842a3da269de1ab82e9a2a12aae8ed5677f064d8

diff --git a/lib/authenticator.js b/lib/authenticator.js
index da6b718..7390db5 100644
--- a/lib/authenticator.js
+++ b/lib/authenticator.js
@@ -9,52 +9,89 @@ const { name: packageName } = require('../package');
 
 const _fileScope = common.fileScope(__filename);
 
+/**
+ * Wrangles the fiddly bits of authentication.
+ * Handles checking of credentials and otp codes, creating and validating
+ * cookie-based sessions, Basic auth.
+ * Interacts with the authentication database interface.
+ */
+
 class Authenticator {
   /**
    * @typedef {Object} AuthInfo
    * @property {String} identifier
-   * @property {String} credentials
+   * @property {String} credential
    * @property {String=} otpKey
    */
+  /**
+   * @callback DBContextExec
+   * @param {Object} dbCtx
+   * @returns {Promise<any>}
+   */
+  /**
+   * @typedef {Object} AuthDBInterface
+   * @property {(DBContextExec) => Promise<any>} context
+   * @property {(dbCtx: any, identifier: String) => Promise<AuthInfo> } authenticationGet
+   * @property {(dbCtx: any, identifier: String) => Promise<void>} authenticationSuccess
+   * @property {(dbCtx: any, identifier: String, credential: String, otpKey: String=) => Promise<void>} authenticationInsertIdentifier
+   * @property {(dbCtx: any, identifier: String, otpKey: String) => Promise<void>} authenticationUpdateOTPKey
+   * @property {(dbCtx: any, identifier: String, credential: AuthInfo) => Promise<void>} authenticationUpdateCredential
+   */
   /**
    * @param {Console} logger
-   * @param {*} db
-   * @param {(dbCtx: any, identifier: String) => Promise<AuthInfo> } db.authenticationGet
-   * @param {(dbCtx: any, identifier: String) => Promise<void>} db.authenticationSuccess
-   * @param {((dbCtx: any) => Promise<any>) => Promise<void>} db.context
+   * @param {AuthDBInterface} db
    * @param {Object} options
+   * @param {String|String[]} options.encryptionSecret
    * @param {Object} options.authenticator
    * @param {Boolean} options.authenticator.secureAuthOnly
    * @param {String[]} options.authenticator.forbiddenPAMIdentifiers
-   * @param {String[]} options.authenticator.authnEnabled
+   * @param {String[]} options.authenticator.authnEnabled in order of preference for storing new credentials
    * @param {Number=} options.authenticator.inactiveSessionLifespanSeconds
    * @param {String[]=} options.authenticator.loginBlurb
    * @param {String[]=} options.authenticator.indieAuthBlurb
    * @param {String[]=} options.authenticator.userBlurb
+   * @param {String[]=} options.authenticator.otpBlurb
+   * @param {String=} options.dingus
+   * @param {String=} options.dingus.proxyPrefix
    */
   constructor(logger, db, options) {
     this.logger = logger;
     this.db = db;
     this.options = options;
     this.basicRealm = options.authenticator.basicRealm || packageName;
-    this.secureAuthOnly = options.authenticator.secureAuthOnly;
+    this.secureAuthOnly = options.authenticator.secureAuthOnly ?? true;
+    this.proxyPrefix = options.dingus?.proxyPrefix ?? '';
 
+    // First construct map of all available code-supported auth mechanisms.
     this.authn = {
-      DEBUG_ANY: {},
       indieAuth: {},
+      plain: {},
     };
     try {
       this.authn.argon2 = require('argon2');
     } catch (e) { /**/ }
     try {
       this.authn.pam = require('node-linux-pam');
-      this.forbiddenPAMIdentifiers = options.authenticator.forbiddenPAMIdentifiers;
+      this.forbiddenPAMIdentifiers = options.authenticator.forbiddenPAMIdentifiers ?? ['root'];
     } catch (e) { /**/ }
 
-    this.authnEnabled = Object.keys(this.authn).filter((auth) => options.authenticator.authnEnabled.includes(auth));
-    this.logger.debug(_fileScope('constructor'), 'available mechanisms', { authn: this.authnEnabled });
+    // Track which authn methods we can change credentials et cetera.
+    const authnUpdatable = ['plain', 'argon2'];
+
+    // Filter configured mechanisms from available, note the first as which to use for setting new credentials.
+    this.authnEnabled = new Set();
+    this.authnPreferred = undefined; // For updating credentials
+    options.authenticator.authnEnabled.forEach((authn) => {
+      if (authn in this.authn) {
+        this.authnEnabled.add(authn);
+        if (!this.authnPreferred && authnUpdatable.includes(authn)) {
+          this.authnPreferred = authn;
+        }
+      }
+    });
+    this.logger.debug(_fileScope('constructor'), 'available mechanisms', { authn: Array.from(this.authnEnabled), preferred: this.authnPreferred });
 
-    if (this.authnEnabled.length === 0) {
+    if (this.authnEnabled.size === 0) {
       throw new Error('no authentication mechanisms available');
     }
 
@@ -68,61 +105,134 @@ class Authenticator {
 
 
   /**
-   * Check local auth entries.
-   * Sets ctx.authenticatedId if valid.
-   * Sets ctx.otpNeeded if account has otpKey.
+   * Populate the authentication database with a new identifier, the
+   * secured credential, and optionally an OTP key.
+   * @param {*} dbCtx
    * @param {String} identifier
-   * @param {String} credential
-   * @param {Object} ctx
-   * @returns {Promise<Boolean>}
+   * @param {String} credential plaintext
+   * @param {String=} otpKey
+   * @returns {Promise<void>}
    */
-  async isValidIdentifierCredential(identifier, credential, ctx) {
-    const _scope = _fileScope('isValidIdentifierCredential');
-    this.logger.debug(_scope, 'called', { identifier, credential: '*'.repeat((credential || '').length), ctx });
+  async createIdentifier(dbCtx, identifier, credential, otpKey = null) {
+    const _scope = _fileScope('createIdentifier');
+    try {
+      const secureCredential = await this._secureCredential(credential);
+      await this.db.authenticationInsertIdentifier(dbCtx, identifier, secureCredential, otpKey);
+    } catch (e) {
+      this.logger.error(_scope, 'failed', { error: e, identifier });
+      throw e;
+    }
+  }
 
-    let isValid = false;
 
-    if (typeof credential === 'undefined') {
-      return isValid;
+  /**
+   * Update the authentication database with a new secured credential
+   * for an indentifier.
+   * @param {*} dbCtx
+   * @param {*} identifier
+   * @param {*} credential plaintext
+   * @returns {Promise<void>}
+   */
+  async updateCredential(dbCtx, identifier, credential) {
+    const _scope = _fileScope('updateCredential');
+    try {
+      const secureCredential = await this._secureCredential(credential);
+      await this.db.authenticationUpdateCredential(dbCtx, identifier, secureCredential);
+      this.logger.info(_scope, 'success', { identifier });
+    } catch (e) {
+      this.logger.error(_scope, 'failed', { error: e, identifier });
+      throw e;
     }
+  }
 
-    await this.db.context(async (dbCtx) => {
-      const authData = await this.db.authenticationGet(dbCtx, identifier);
-      if (!authData) {
-        this.logger.debug(_scope, 'failed, invalid identifier', { ctx, identifier });
-      } else if (authData.credential.startsWith('$argon2')
-      &&         this.authnEnabled.includes('argon2')) {
-        isValid = await this.authn.argon2.verify(authData.credential, credential);
-      } else if (authData.credential.startsWith('$PAM$')
-      &&         this.authnEnabled.includes('pam')) {
-        isValid = this._isValidPAMIdentifier(identifier, credential);
-      } else {
-        this.logger.error(_scope, 'failed, unknown or unsupported type of stored credential', { identifier, ctx });
-      }
 
-      if (this.authnEnabled.includes('DEBUG_ANY')) {
-        isValid = true;
-      }
+  /**
+   * Encode a plaintext credential in the preferred way to store in database.
+   * @param {String} credential
+   * @param {String=} authn
+   * @returns {Promise<String>}
+   */
+  async _secureCredential(credential, authn = this.authnPreferred) {
+    const _scope = _fileScope('_secureCredential');
+    try {
+      switch (authn) {
+        case 'plain':
+          return '$plain$' + credential;
 
-      if (isValid) {
-        ctx.authenticationId = identifier;
-        ctx.otpNeeded = !!authData?.otpKey;
-        await this.db.authenticationSuccess(dbCtx, identifier);
+        case 'argon2':
+          return await this.authn.argon2.hash(credential, { type: this.authn.argon2.argon2id });
+
+        default:
+          throw new RangeError('Unknown authn');
       }
-    }); // dbCtx
+    } catch (e) {
+      this.logger.error(_scope, 'failed', { error: e, authn });
+      throw e;
+    }
+  }
 
-    return isValid;
+
+  /**
+   * Checks a supplied credential against supplied data.
+   * @param {AuthInfo} authData from database
+   * @param {String} credential plaintext
+   * @returns {Promise<Boolean>}
+   */
+  async _validateAuthDataCredential(authData, credential) {
+    const _scope = _fileScope('_validateAuthDataCredential');
+
+    if (!authData?.credential) {
+      this.logger.debug(_scope, 'failed, no authInfo');
+      return false;
+    }
+    if (authData.credential.startsWith('$argon2')
+    &&  this.authnEnabled.has('argon2')) {
+      return await this._isValidArgon2Identifier(authData, credential);
+    }
+    if (authData.credential.startsWith('$PAM$')
+    &&  this.authnEnabled.has('pam')) {
+      return await this._isValidPAMIdentifier(authData, credential);
+    }
+    if (authData.credential.startsWith('$plain$')
+    &&  this.authnEnabled.has('plain')) {
+      return this.constructor._isValidPlainIdentifier(authData, credential);
+    }
+    this.logger.error(_scope, 'failed, unknown or unsupported type of stored credential', { authData });
+    return false;
+  }
+
+
+  /**
+   * Check argon2.
+   * @param {AuthInfo} authData
+   * @param {String} credential
+   * @returns {Promise<Boolean>}
+   */
+  async _isValidArgon2Identifier(authData, credential) {
+    return await this.authn.argon2.verify(authData.credential, credential);
+  }
+
+
+  /**
+   * Check plaintext.
+   * @param {AuthInfo} authData
+   * @param {String} credential
+   * @returns {Promise<Boolean>}
+   */
+  static _isValidPlainIdentifier(authData, credential) {
+    return authData.credential.substring('$plain$'.length) === credential;
   }
 
 
   /**
    * Check system PAM.
-   * @param {String} identifier
+   * @param {AuthInfo} authData
    * @param {String} credential
    * @returns {Promise<Boolean>}
    */
-  async _isValidPAMIdentifier(identifier, credential) {
+  async _isValidPAMIdentifier(authData, credential) {
     const _scope = _fileScope('_isValidPAMIdentifier');
+    const { identifier } = authData;
     let isValid = false;
     if (this.forbiddenPAMIdentifiers.includes(identifier)) {
       return false;
@@ -140,9 +250,50 @@ class Authenticator {
   }
 
 
+  /**
+   * Check local auth entries.
+   * Sets ctx.authenticatedId if valid.
+   * Sets ctx.otpKey if account has otpKey.
+   * @param {String} identifier
+   * @param {String} credential
+   * @param {Object} ctx
+   * @returns {Promise<Boolean>}
+   */
+  async isValidIdentifierCredential(identifier, credential, ctx) {
+    const _scope = _fileScope('isValidIdentifierCredential');
+    this.logger.debug(_scope, 'called', { identifier, credential: '*'.repeat((credential || '').length), ctx });
+
+    let isValid = false;
+
+    if (typeof credential === 'undefined') {
+      return isValid;
+    }
+
+    await this.db.context(async (dbCtx) => {
+      const authData = await this.db.authenticationGet(dbCtx, identifier);
+      if (!authData) {
+        this.logger.debug(_scope, 'failed, invalid identifier', { ctx, identifier });
+        return;
+      }
+
+      isValid = await this._validateAuthDataCredential(authData, credential);
+
+      if (isValid) {
+        ctx.authenticationId = identifier;
+        if (authData.otpKey) {
+          ctx.otpKey = authData.otpKey;
+        }
+        await this.db.authenticationSuccess(dbCtx, identifier);
+      }
+    }); // dbCtx
+
+    return isValid;
+  }
+
+
   /**
    * 
-   * @param {Object} state
+   * @param {OTPState} state
    * @param {String} state.key
    * @param {Number} state.attempt
    * @param {Number} state.epochMs
@@ -151,8 +302,9 @@ class Authenticator {
    */
   checkOTP(state, otp) {
     const totp = new this.TOTP({
+      keyEncoding: 'base32',
       ...this.options?.authenticator?.otpOptions,
-      ...state,
+      key: state.key,
     });
     const isValid = totp.validate(otp);
     if (isValid) {
@@ -218,40 +370,20 @@ class Authenticator {
   }
 
 
-  /**
-   * 
-   * @param {String} cookieHeader
-   */
-  static _cookieParse(cookieHeader) {
-    const cookie = {};
-    (cookieHeader || '').split(/; */).forEach((field) => {
-      const [ name, value ] = common.splitFirst(field, '=', null).map((x) => x && decodeURIComponent(x.trim()));
-      if (name && !(name in cookie)) {
-        if (value?.startsWith('"') && value.endsWith('"')) {
-          cookie[name] = value.slice(1, -1); // eslint-disable-line security/detect-object-injection
-        } else {
-          cookie[name] = value; // eslint-disable-line security/detect-object-injection
-        }
-      }
-    });
-    return cookie;
-  }
-
-
   /**
    * Attempt to parse a session cookie, and determine if it contains an
    * authenticated user.
-   * Restores ctx.session from cookie data, sets ctx.authenticationId if identifier exists.
+   * Restores ctx.session from cookie data, sets ctx.authenticationId to
+   * identifier or profile for session.
    * @param {Object} ctx
-   * @param {String} cookieHeader
-   * @returns {Boolean}
+   * @param {Object} ctx.cookie
+   * @returns {Promise<Boolean>}
    */
-  async isValidCookieAuth(ctx, cookieHeader) {
+  async isValidCookieAuth(ctx) {
     const _scope = _fileScope('isValidCookieAuth');
-    this.logger.debug(_scope, 'called', { ctx, cookieHeader });
+    this.logger.debug(_scope, 'called', { ctx });
 
-    const cookie = Authenticator._cookieParse(cookieHeader);
-    const cookieValue = cookie[Enum.SessionCookie];
+    const cookieValue = ctx.cookie?.[Enum.SessionCookie];
 
     if (!cookieValue) {
       return false;
@@ -261,7 +393,7 @@ class Authenticator {
       this.logger.debug(_scope, 'unpacked cookie', { ctx });
 
       const hasIdentifier = !!ctx.session.authenticatedIdentifier;
-      const hasProfile = !!ctx.session.authenticatedProfile && this.authnEnabled.includes('indieAuth');
+      const hasProfile = !!ctx.session.authenticatedProfile && this.authnEnabled.has('indieAuth');
       const isValid = hasIdentifier || hasProfile;
       if (isValid) {
         ctx.authenticationId = ctx.session.authenticatedIdentifier || ctx.session.authenticatedProfile;
@@ -269,7 +401,7 @@ class Authenticator {
 
       return isValid;
     } catch (e) {
-      this.logger.debug(_scope, 'could not unpack cookie', { error:e, ctx });
+      this.logger.debug(_scope, 'could not unpack cookie', { error: e, ctx });
       return false;
     }
   }
@@ -277,16 +409,23 @@ class Authenticator {
 
   /**
    * Check for a valid session.
+   * If a valid session cookie is present, refreshes the timeout for it.
+   * If not, and one is required, redirects to the login url.
+   * Convenience wrappers for option combinations:
+   * @see sessionRequired
+   * @see sessionRequiredLocal
+   * @see sessionOptional
+   * @see sessionOptionalLocal
    * @param {http.ClientRequest} req
    * @param {http.ServerResponse} res
    * @param {Object} ctx
    * @param {String} loginPath
-   * @param {Boolean} required
-   * @param {Boolean} profilesAllowed
-   * @returns {Boolean}
+   * @param {Boolean} required redirect to login url if no valid session
+   * @param {Boolean} profilesAllowed if true, an indieauth session is valid, otherwise only identifier/credential
+   * @returns {Promise<Boolean>}
    */
   async sessionCheck(req, res, ctx, loginPath, required = true, profilesAllowed = true) {
-    const _scope = _fileScope('check');
+    const _scope = _fileScope('sessionCheck');
     this.logger.debug(_scope, 'called', { ctx, loginPath, required, profilesAllowed });
 
     if (this.secureAuthOnly
@@ -299,40 +438,30 @@ class Authenticator {
       }
     }
 
-    const sessionCookie = req.getHeader(Enum.Header.Cookie);
-    if (sessionCookie
-    &&  await this.isValidCookieAuth(ctx, sessionCookie)
+    if (await this.isValidCookieAuth(ctx)
     &&  (ctx.session.authenticatedIdentifier
          || (profilesAllowed && ctx.session.authenticatedProfile))) {
       this.logger.debug(_scope, 'valid session cookie', { ctx });
       // Refresh timeout on valid session.
-      const cookieParts = [
-        sessionCookie,
-        'HttpOnly',
-        `Max-Age=${this.cookieLifespan}`,
-        'SameSite=Lax',
-        `Path=${this.options.dingus.proxyPrefix}/`,
-      ];
-      if (this.secureAuthOnly) {
-        cookieParts.push('Secure');
-      }
-      res.setHeader(Enum.Header.SetCookie, cookieParts.join('; '));
+      common.addCookie(res, Enum.SessionCookie, ctx.cookie[Enum.SessionCookie], {
+        httpOnly: true,
+        maxAge: this.cookieLifespan,
+        sameSite: 'Lax',
+        path: `${this.proxyPrefix}/`,
+        secure: this.secureAuthOnly,
+      });
       return true;
     }
 
     if (required) {
       // Clear any existing invalid session
-      const cookieParts = [
-        `${Enum.SessionCookie}=""`,
-        'HttpOnly',
-        'Max-Age=0',
-        'SameSite=Lax',
-        `Path=${this.options.dingus.proxyPrefix}/`,
-      ];
-      if (this.options.authenticator.secureAuthOnly) {
-        cookieParts.push('Secure');
-      }
-      res.setHeader(Enum.Header.SetCookie, cookieParts.join('; '));
+      common.addCookie(res, Enum.SessionCookie, '""', {
+        httpOnly: true,
+        maxAge: 0,
+        sameSite: 'Lax',
+        path: `${this.proxyPrefix}/`,
+        secure: this.secureAuthOnly,
+      });
 
       res.statusCode = 302;
       res.setHeader(Enum.Header.Location, `${loginPath}?r=${encodeURIComponent(req.url)}`);
@@ -349,7 +478,7 @@ class Authenticator {
    * @param {http.ServerResponse} res
    * @param {Object} ctx
    * @param {String} loginPath
-   * @returns {Boolean}
+   * @returns {Promise<Boolean>}
    */
   async sessionRequiredLocal(req, res, ctx, loginPath) {
     return this.sessionCheck(req, res, ctx, loginPath, true, false);
@@ -362,7 +491,7 @@ class Authenticator {
    * @param {http.ServerResponse} res
    * @param {Object} ctx
    * @param {String} loginPath
-   * @returns {Boolean}
+   * @returns {Promise<Boolean>}
    */
   async sessionRequired(req, res, ctx, loginPath) {
     return this.sessionCheck(req, res, ctx, loginPath);
@@ -375,7 +504,7 @@ class Authenticator {
    * @param {http.ServerResponse} res
    * @param {Object} ctx
    * @param {String} loginPath
-   * @returns {Boolean}
+   * @returns {Promise<Boolean>}
    */
   async sessionOptionalLocal(req, res, ctx) {
     return this.sessionCheck(req, res, ctx, undefined, false, false);
@@ -388,7 +517,7 @@ class Authenticator {
    * @param {http.ServerResponse} res
    * @param {Object} ctx
    * @param {String} loginPath
-   * @returns {Boolean}
+   * @returns {Promise<Boolean>}
    */
   async sessionOptional(req, res, ctx) {
     return this.sessionCheck(req, res, ctx, undefined, false);
@@ -397,13 +526,14 @@ class Authenticator {
 
   /**
    * Require auth for an API endpoint.
-   * Check for valid local identifier in Authorization header; optionally
-   * fall back to session cookie if no header provided.
+   * Check for valid local identifier in Authorization header;
+   * optionally fall back to session cookie if no header provided.
    * Prompts for Basic auth if not valid.
    * @param {http.ClientRequest} req
    * @param {http.ServerResponse} res
    * @param {Object} ctx
    * @param {Boolean} sessionAlsoValid
+   * @returns {Promise<Boolean}
    */
   async apiRequiredLocal(req, res, ctx, sessionAlsoValid = true) {
     const _scope = _fileScope('apiRequiredLocal');
@@ -426,6 +556,7 @@ class Authenticator {
     this.requestBasic(res);
   }
 
+
 }
 
 module.exports = Authenticator;