adapt-authoring-auth-local 1.2.0 → 1.3.0

package/.github/workflows/tests.yml

@@ -3,9 +3,11 @@ on: push
 jobs:
   default:
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
     steps:
-      - uses: actions/checkout@master
-      - uses: actions/setup-node@master
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
         with:
           node-version: 'lts/*'
           cache: 'npm'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adapt-authoring-auth-local",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Module which implements username/password (local) authentication",
   "homepage": "https://github.com/adapt-security/adapt-authoring-auth-local",
   "license": "GPL-3.0",

package/tests/LocalAuthModule.spec.js

@@ -45,6 +45,7 @@ let updateCalls = []
 let disavowCalls = []
 let secureRouteCalls = []
 let unsecureRouteCalls = []
+let mailerSendCalls = []
 
 const mockUsers = {
   find: async (query) => usersStore.filter(u => {
@@ -63,7 +64,7 @@ const mockRoles = {
 
 const mockMailer = {
   isEnabled: true,
-  send: async () => {}
+  send: async (opts) => { mailerSendCalls.push(opts) }
 }
 
 const mockServer = {
@@ -106,7 +107,7 @@ const mockApp = {
     return names.map(n => moduleMap[n])
   },
   lang: {
-    translate: (_, key) => `translated:${key}`
+    translate: (_, key) => 'translated:' + key
   }
 }
 
@@ -160,6 +161,7 @@ describe('LocalAuthModule', () => {
     disavowCalls = []
     secureRouteCalls = []
     unsecureRouteCalls = []
+    mailerSendCalls = []
     usersStore.length = 0
     authlocalConfig = {
       failsUntilTemporaryLock: 5,
@@ -193,6 +195,17 @@ describe('LocalAuthModule', () => {
       const result = LocalAuthModule.formatRemainingTime(60)
       assert.ok(result.includes('minute'))
     })
+
+    it('should return a string containing "hour" for 3600 seconds', () => {
+      const result = LocalAuthModule.formatRemainingTime(3600)
+      assert.ok(result.includes('hour'))
+    })
+
+    it('should handle zero seconds', () => {
+      const result = LocalAuthModule.formatRemainingTime(0)
+      assert.equal(typeof result, 'string')
+      assert.ok(result.length > 0)
+    })
   })
 
   describe('#setValues()', () => {
@@ -227,6 +240,22 @@ describe('LocalAuthModule', () => {
       const superRoute = instance.routes.find(r => r.route === '/registersuper')
       assert.equal(superRoute.internal, true)
     })
+
+    it('should define post handlers for all routes', async () => {
+      const instance = new LocalAuthModule()
+      await instance.setValues()
+      for (const route of instance.routes) {
+        assert.equal(typeof route.handlers.post, 'function')
+      }
+    })
+
+    it('should define meta for all routes', async () => {
+      const instance = new LocalAuthModule()
+      await instance.setValues()
+      for (const route of instance.routes) {
+        assert.ok(route.meta)
+      }
+    })
   })
 
   describe('#init()', () => {
@@ -239,13 +268,26 @@ describe('LocalAuthModule', () => {
       assert.ok(secureRouteCalls.some(c => c[0] === '/invite' && c[1] === 'post'))
     })
 
-    it('should secure the validatepass route', async () => {
+    it('should secure the validatepass route with read:me permission', async () => {
+      const instance = new LocalAuthModule()
+      instance.app = mockApp
+      instance.router = { routes: [{ route: '/', meta: null }, { route: '/register', meta: null }] }
+      await instance.setValues()
+      await instance.init()
+      const call = secureRouteCalls.find(c => c[0] === '/validatepass')
+      assert.ok(call)
+      assert.deepEqual(call[2], ['read:me'])
+    })
+
+    it('should secure the invite route with register:users permission', async () => {
       const instance = new LocalAuthModule()
       instance.app = mockApp
       instance.router = { routes: [{ route: '/', meta: null }, { route: '/register', meta: null }] }
       await instance.setValues()
       await instance.init()
-      assert.ok(secureRouteCalls.some(c => c[0] === '/validatepass' && c[1] === 'post'))
+      const call = secureRouteCalls.find(c => c[0] === '/invite')
+      assert.ok(call)
+      assert.deepEqual(call[2], ['register:users'])
     })
 
     it('should unsecure registersuper, changepass, and forgotpass routes', async () => {
@@ -268,6 +310,16 @@ describe('LocalAuthModule', () => {
       await instance.init()
       assert.equal(instance.users, mockUsers)
     })
+
+    it('should set meta on root and register routes', async () => {
+      const instance = new LocalAuthModule()
+      instance.app = mockApp
+      instance.router = { routes: [{ route: '/', meta: null }, { route: '/register', meta: null }] }
+      await instance.setValues()
+      await instance.init()
+      assert.ok(instance.router.routes.find(r => r.route === '/').meta)
+      assert.ok(instance.router.routes.find(r => r.route === '/register').meta)
+    })
   })
 
   describe('#authenticate()', () => {
@@ -313,6 +365,24 @@ describe('LocalAuthModule', () => {
       assert.equal(lastUpdate.data.failedLoginAttempts, 1)
     })
 
+    it('should set lastFailedLoginAttempt on wrong password', async () => {
+      const { default: PasswordUtils } = await import('../lib/PasswordUtils.js')
+      const hash = await PasswordUtils.generate('correctpass')
+      const user = {
+        _id: 'user-1',
+        password: hash,
+        isPermLocked: false,
+        isTempLocked: false,
+        failedLoginAttempts: 0,
+        lastFailedLoginAttempt: null
+      }
+      const req = { body: { password: 'wrongpass' } }
+      await assert.rejects(() => mod.authenticate(user, req, {}))
+      const lastUpdate = updateCalls[updateCalls.length - 1]
+      assert.ok(lastUpdate.data.lastFailedLoginAttempt)
+      assert.ok(!isNaN(Date.parse(lastUpdate.data.lastFailedLoginAttempt)))
+    })
+
     it('should temporarily lock after reaching failsUntilTemporaryLock threshold', async () => {
       const { default: PasswordUtils } = await import('../lib/PasswordUtils.js')
       const hash = await PasswordUtils.generate('correctpass')
@@ -387,6 +457,40 @@ describe('LocalAuthModule', () => {
       const lastUpdate = updateCalls[updateCalls.length - 1]
       assert.equal(lastUpdate.data.failedLoginAttempts, 20)
     })
+
+    it('should not increment failed attempts during temp lock timeout', async () => {
+      const { default: PasswordUtils } = await import('../lib/PasswordUtils.js')
+      const hash = await PasswordUtils.generate('correctpass')
+      const user = {
+        _id: 'user-1',
+        password: hash,
+        isPermLocked: false,
+        isTempLocked: true,
+        failedLoginAttempts: 5,
+        lastFailedLoginAttempt: new Date().toISOString()
+      }
+      const req = { body: { password: 'wrongpass' } }
+      await assert.rejects(() => mod.authenticate(user, req, {}))
+      const lastUpdate = updateCalls[updateCalls.length - 1]
+      assert.equal(lastUpdate.data.failedLoginAttempts, 5)
+    })
+
+    it('should clear lastFailedLoginAttempt on successful login', async () => {
+      const { default: PasswordUtils } = await import('../lib/PasswordUtils.js')
+      const hash = await PasswordUtils.generate('correctpass')
+      const user = {
+        _id: 'user-1',
+        password: hash,
+        isPermLocked: false,
+        isTempLocked: false,
+        failedLoginAttempts: 0,
+        lastFailedLoginAttempt: null
+      }
+      const req = { body: { password: 'correctpass' } }
+      await mod.authenticate(user, req, {})
+      const lastUpdate = updateCalls[updateCalls.length - 1]
+      assert.equal(lastUpdate.data.lastFailedLoginAttempt, undefined)
+    })
   })
 
   describe('#handleLockStatus()', () => {
@@ -413,6 +517,23 @@ describe('LocalAuthModule', () => {
       )
     })
 
+    it('should include remaining time in ACCOUNT_LOCKED_TEMP error data', async () => {
+      const user = {
+        isPermLocked: false,
+        isTempLocked: true,
+        lastFailedLoginAttempt: new Date().toISOString()
+      }
+      await assert.rejects(
+        () => mod.handleLockStatus(user),
+        (err) => {
+          assert.ok(err.data)
+          assert.ok(err.data.remaining)
+          assert.equal(typeof err.data.remaining, 'string')
+          return true
+        }
+      )
+    })
+
     it('should unlock user when temp lock has expired', async () => {
       const user = {
         _id: 'user-1',
@@ -435,6 +556,18 @@ describe('LocalAuthModule', () => {
       await mod.handleLockStatus(user)
       assert.equal(updateCalls.length, 0)
     })
+
+    it('should check permanent lock before temporary lock', async () => {
+      const user = {
+        isPermLocked: true,
+        isTempLocked: true,
+        lastFailedLoginAttempt: new Date().toISOString()
+      }
+      await assert.rejects(
+        () => mod.handleLockStatus(user),
+        (err) => err.name === 'ACCOUNT_LOCKED_PERM'
+      )
+    })
   })
 
   describe('#register()', () => {
@@ -450,6 +583,17 @@ describe('LocalAuthModule', () => {
       assert.ok(result.password)
       assert.ok(result.password.startsWith('$2a$') || result.password.startsWith('$2b$'))
     })
+
+    it('should preserve other data fields in registration', async () => {
+      const result = await mod.register({
+        email: 'new@example.com',
+        password: 'validpassword',
+        firstName: 'Test',
+        lastName: 'User'
+      })
+      assert.equal(result.firstName, 'Test')
+      assert.equal(result.lastName, 'User')
+    })
   })
 
   describe('#registerSuper()', () => {
@@ -460,6 +604,21 @@ describe('LocalAuthModule', () => {
         (err) => err.name === 'SUPER_USER_EXISTS'
       )
     })
+
+    it('should call register with hardcoded firstName and lastName', async () => {
+      const originalRegister = mod.register.bind(mod)
+      let registeredData
+      mod.register = async (data) => {
+        registeredData = data
+        return originalRegister(data)
+      }
+      await mod.registerSuper({ email: 'super@example.com', password: 'validpassword' })
+      mod.register = originalRegister
+      assert.equal(registeredData.firstName, 'Super')
+      assert.equal(registeredData.lastName, 'User')
+      assert.equal(registeredData.email, 'super@example.com')
+      assert.equal(registeredData.password, 'validpassword')
+    })
   })
 
   describe('#setUserEnabled()', () => {
@@ -472,7 +631,7 @@ describe('LocalAuthModule', () => {
       assert.equal(lastUpdate.data.isTempLocked, false)
     })
 
-    // NOTE: There is a bug in setUserEnabled — when disabling (isEnabled=false),
+    // NOTE: There is a bug in setUserEnabled -- when disabling (isEnabled=false),
     // it references user.failedAttempts which doesn't exist on the schema.
     // The schema field is user.failedLoginAttempts. This means
     // failedLoginAttempts will always be set to undefined when disabling.
@@ -483,6 +642,21 @@ describe('LocalAuthModule', () => {
       assert.equal(lastUpdate.data.isPermLocked, true)
       assert.equal(lastUpdate.data.isTempLocked, true)
     })
+
+    it('should use localauthuser schema for user update', async () => {
+      const user = { _id: 'user-1', failedLoginAttempts: 0 }
+      await mod.setUserEnabled(user, true)
+      assert.ok(updateCalls.length > 0)
+    })
+
+    // TODO: Bug - setUserEnabled references user.failedAttempts instead of
+    // user.failedLoginAttempts when disabling. See BUGS.md.
+    it('should preserve failedLoginAttempts when disabling a user', { todo: 'references user.failedAttempts instead of user.failedLoginAttempts' }, async () => {
+      const user = { _id: 'user-1', failedLoginAttempts: 7 }
+      await mod.setUserEnabled(user, false)
+      const lastUpdate = updateCalls[updateCalls.length - 1]
+      assert.equal(lastUpdate.data.failedLoginAttempts, 7)
+    })
   })
 
   describe('#updateUser()', () => {
@@ -498,6 +672,13 @@ describe('LocalAuthModule', () => {
       assert.deepEqual(lastUpdate.query, { email: 'test@example.com' })
     })
 
+    it('should accept an ObjectId-like object as userIdOrQuery', async () => {
+      const fakeObjectId = { constructor: { name: 'ObjectId' }, toString: () => 'abc123' }
+      await mod.updateUser(fakeObjectId, { firstName: 'Updated' })
+      const lastUpdate = updateCalls[updateCalls.length - 1]
+      assert.deepEqual(lastUpdate.query, { _id: fakeObjectId })
+    })
+
     it('should hash password when update includes password', async () => {
       const result = await mod.updateUser('user-id-1', { password: 'newpassword' })
       assert.ok(result)
@@ -509,6 +690,24 @@ describe('LocalAuthModule', () => {
       assert.equal(lastUpdate.data.firstName, 'NoPassword')
       assert.equal(Object.prototype.hasOwnProperty.call(lastUpdate.data, 'password'), false)
     })
+
+    it('should call disavowUser after a password update', async () => {
+      disavowCalls = []
+      await mod.updateUser('user-id-1', { password: 'newpassword' })
+      assert.ok(disavowCalls.length > 0)
+      assert.equal(disavowCalls[0][0].authType, 'local')
+    })
+
+    it('should send email notification after password update when mailer is enabled', async () => {
+      mailerSendCalls = []
+      await mod.updateUser('user-id-1', { password: 'newpassword' })
+      assert.ok(mailerSendCalls.length > 0)
+      assert.equal(mailerSendCalls[0].to, 'test@example.com')
+    })
+
+    it('should pass useDefaults:false and ignoreRequired:true for non-password updates', async () => {
+      await assert.doesNotReject(() => mod.updateUser('user-id-1', { firstName: 'Test' }))
+    })
   })
 
   describe('#createPasswordReset()', () => {
@@ -525,6 +724,23 @@ describe('LocalAuthModule', () => {
         (err) => err.name === 'INVALID_PARAMS'
       )
     })
+
+    it('should throw when email is null', async () => {
+      await assert.rejects(
+        () => mod.createPasswordReset(null),
+        (err) => err.name === 'INVALID_PARAMS'
+      )
+    })
+
+    it('should include email param in INVALID_PARAMS error data', async () => {
+      await assert.rejects(
+        () => mod.createPasswordReset(''),
+        (err) => {
+          assert.deepEqual(err.data.params, ['email'])
+          return true
+        }
+      )
+    })
   })
 
   describe('#inviteHandler()', () => {
@@ -532,7 +748,7 @@ describe('LocalAuthModule', () => {
       let statusSent
       const req = {
         body: { email: 'invite@example.com' },
-        translate: (key) => `translated:${key}`,
+        translate: (key) => 'translated:' + key,
         auth: { user: { _id: { toString: () => 'admin-id' } } }
       }
       const res = {
@@ -550,13 +766,30 @@ describe('LocalAuthModule', () => {
       let nextError
       const req = {
         body: { email: '' },
-        translate: (key) => `translated:${key}`,
+        translate: (key) => 'translated:' + key,
         auth: {}
       }
       const res = { sendStatus: () => {} }
       await mod.inviteHandler(req, res, (err) => { nextError = err })
       assert.ok(nextError)
     })
+
+    it('should pass inviteTokenLifespan to createPasswordReset', async () => {
+      let receivedLifespan
+      const original = mod.createPasswordReset.bind(mod)
+      mod.createPasswordReset = async (email, subject, text, html, lifespan) => {
+        receivedLifespan = lifespan
+      }
+      const req = {
+        body: { email: 'invite@example.com' },
+        translate: (key) => 'translated:' + key,
+        auth: { user: { _id: { toString: () => 'admin-id' } } }
+      }
+      const res = { sendStatus: () => {} }
+      await mod.inviteHandler(req, res, () => {})
+      mod.createPasswordReset = original
+      assert.equal(receivedLifespan, 604800000)
+    })
   })
 
   describe('#registerSuperHandler()', () => {
@@ -588,7 +821,7 @@ describe('LocalAuthModule', () => {
       let responseJson
       const req = {
         body: { email: '' },
-        translate: (key) => `translated:${key}`,
+        translate: (key) => 'translated:' + key,
         auth: {}
       }
       const res = {
@@ -601,6 +834,146 @@ describe('LocalAuthModule', () => {
       assert.equal(responseStatus, 200)
       assert.ok(responseJson.message)
     })
+
+    it('should include translated message in response', async () => {
+      let responseJson
+      const req = {
+        body: { email: 'test@example.com' },
+        translate: (key) => 'translated:' + key,
+        auth: {}
+      }
+      const res = {
+        status: () => ({ json: (data) => { responseJson = data } })
+      }
+      const original = mod.createPasswordReset.bind(mod)
+      mod.createPasswordReset = async () => {}
+      await mod.forgotPasswordHandler(req, res, () => {})
+      mod.createPasswordReset = original
+      assert.equal(responseJson.message, 'translated:app.forgotpasswordmessage')
+    })
+
+    it('should not call next with error (swallows errors to avoid info leaks)', async () => {
+      let nextCalled = false
+      const req = {
+        body: { email: '' },
+        translate: (key) => 'translated:' + key,
+        auth: {}
+      }
+      const res = {
+        status: () => ({ json: () => {} })
+      }
+      await mod.forgotPasswordHandler(req, res, () => { nextCalled = true })
+      assert.equal(nextCalled, false)
+    })
+  })
+
+  describe('#changePasswordHandler()', () => {
+    it('should respond with 204 on successful authenticated password change', async () => {
+      const { default: PasswordUtils } = await import('../lib/PasswordUtils.js')
+      const oldHash = await PasswordUtils.generate('oldpassword')
+      usersStore.push({ email: 'test@example.com', password: oldHash })
+
+      let endCalled = false
+      let statusCode
+      const req = {
+        body: { password: 'newpassword1', oldPassword: 'oldpassword' },
+        auth: {
+          token: { type: 'local', signature: 'sig123' },
+          user: { email: 'test@example.com', _id: { toString: () => 'uid1' } }
+        }
+      }
+      const res = {
+        status: (code) => {
+          statusCode = code
+          return { end: () => { endCalled = true } }
+        }
+      }
+      await mod.changePasswordHandler(req, res, () => {})
+      assert.equal(statusCode, 204)
+      assert.equal(endCalled, true)
+    })
+
+    it('should call next with error on invalid old password', async () => {
+      const { default: PasswordUtils } = await import('../lib/PasswordUtils.js')
+      const oldHash = await PasswordUtils.generate('oldpassword')
+      usersStore.push({ email: 'test@example.com', password: oldHash })
+
+      let nextError
+      const req = {
+        body: { password: 'newpassword1', oldPassword: 'wrongpassword' },
+        auth: {
+          token: { type: 'local', signature: 'sig123' },
+          user: { email: 'test@example.com', _id: { toString: () => 'uid1' } }
+        }
+      }
+      const res = { status: () => ({ end: () => {} }) }
+      await mod.changePasswordHandler(req, res, (err) => { nextError = err })
+      assert.ok(nextError)
+    })
+
+    it('should call next with error when auth token type is not local', async () => {
+      let nextError
+      const req = {
+        body: { password: 'newpassword1' },
+        auth: {
+          token: { type: 'sso', signature: 'sig123' },
+          user: { email: 'test@example.com', _id: { toString: () => 'uid1' } }
+        }
+      }
+      const res = { status: () => ({ end: () => {} }) }
+      await mod.changePasswordHandler(req, res, (err) => { nextError = err })
+      assert.ok(nextError)
+    })
+
+    it('should use reset token path when no auth token present', async () => {
+      let statusCode
+      let endCalled = false
+      const PasswordUtils = (await import('../lib/PasswordUtils.js')).default
+
+      const originalUpdate = mod.updateUser.bind(mod)
+      mod.updateUser = async () => ({ _id: 'uid1' })
+
+      const origDeleteReset = PasswordUtils.deleteReset
+      PasswordUtils.deleteReset = async () => {}
+
+      const origValidate = PasswordUtils.validateReset
+      PasswordUtils.validateReset = async () => ({ email: 'test@example.com' })
+
+      const req = {
+        body: { password: 'newpassword1', token: 'reset-token-123' },
+        auth: {}
+      }
+      const res = {
+        status: (code) => {
+          statusCode = code
+          return { end: () => { endCalled = true } }
+        }
+      }
+      await mod.changePasswordHandler(req, res, () => {})
+      assert.equal(statusCode, 204)
+      assert.equal(endCalled, true)
+
+      // Restore
+      PasswordUtils.validateReset = origValidate
+      PasswordUtils.deleteReset = origDeleteReset
+      mod.updateUser = originalUpdate
+    })
+
+    it('should call next with error when email is missing', async () => {
+      let nextError
+      const PasswordUtils = (await import('../lib/PasswordUtils.js')).default
+      const origValidate = PasswordUtils.validateReset
+      PasswordUtils.validateReset = async () => ({ email: '' })
+
+      const req = {
+        body: { password: 'newpassword1', token: 'reset-token-123' },
+        auth: {}
+      }
+      const res = { status: () => ({ end: () => {} }) }
+      await mod.changePasswordHandler(req, res, (err) => { nextError = err })
+      assert.ok(nextError)
+      PasswordUtils.validateReset = origValidate
+    })
   })
 
   describe('#validatePasswordHandler()', () => {
@@ -608,7 +981,7 @@ describe('LocalAuthModule', () => {
       let responseJson
       const req = {
         body: { password: 'validpassword' },
-        translate: (key) => `translated:${key}`
+        translate: (key) => 'translated:' + key
       }
       const res = {
         json: (data) => { responseJson = data }
@@ -617,12 +990,25 @@ describe('LocalAuthModule', () => {
       assert.ok(responseJson.message)
     })
 
+    it('should return translated success message', async () => {
+      let responseJson
+      const req = {
+        body: { password: 'validpassword' },
+        translate: (key) => 'translated:' + key
+      }
+      const res = {
+        json: (data) => { responseJson = data }
+      }
+      await mod.validatePasswordHandler(req, res, () => {})
+      assert.equal(responseJson.message, 'translated:app.passwordindicatorstrong')
+    })
+
     it('should call sendError for an invalid password', async () => {
       let sentError
       authlocalConfig.minPasswordLength = 20
       const req = {
         body: { password: 'short' },
-        translate: (key) => `translated:${key}`
+        translate: (key) => 'translated:' + key
       }
       const res = {
         sendError: (err) => { sentError = err }
@@ -631,5 +1017,20 @@ describe('LocalAuthModule', () => {
       assert.ok(sentError)
       assert.equal(sentError.name, 'INVALID_PASSWORD')
     })
+
+    it('should translate error messages and join them', async () => {
+      let sentError
+      authlocalConfig.minPasswordLength = 20
+      const req = {
+        body: { password: 'short' },
+        translate: (key) => 'translated:' + key
+      }
+      const res = {
+        sendError: (err) => { sentError = err }
+      }
+      await mod.validatePasswordHandler(req, res, () => {})
+      assert.equal(typeof sentError.data.errors, 'string')
+      assert.ok(sentError.data.errors.includes('translated:'))
+    })
   })
 })

package/tests/PasswordUtils.spec.js

@@ -1,4 +1,4 @@
-import { describe, it, before, beforeEach, after, mock } from 'node:test'
+import { describe, it, before, beforeEach, mock } from 'node:test'
 import assert from 'node:assert/strict'
 import bcrypt from 'bcryptjs'
 import { promisify } from 'util'
@@ -108,6 +108,16 @@ describe('PasswordUtils', () => {
       const result = await PasswordUtils.getConfig('saltRounds', 'minPasswordLength')
       assert.deepEqual(result, { saltRounds: 10, minPasswordLength: 8 })
     })
+
+    it('should return undefined for an unknown config key', async () => {
+      const result = await PasswordUtils.getConfig('nonExistentKey')
+      assert.equal(result, undefined)
+    })
+
+    it('should return an object with undefined values for unknown keys in multi-key mode', async () => {
+      const result = await PasswordUtils.getConfig('saltRounds', 'unknownKey')
+      assert.deepEqual(result, { saltRounds: 10, unknownKey: undefined })
+    })
   })
 
   describe('#compare()', () => {
@@ -149,6 +159,41 @@ describe('PasswordUtils', () => {
         (err) => err.name === 'INVALID_LOGIN_DETAILS'
       )
     })
+
+    it('should throw when plainPassword is null', async () => {
+      await assert.rejects(
+        () => PasswordUtils.compare(null, hash),
+        (err) => err.name === 'INVALID_LOGIN_DETAILS'
+      )
+    })
+
+    it('should throw when hash is null', async () => {
+      await assert.rejects(
+        () => PasswordUtils.compare('password', null),
+        (err) => err.name === 'INVALID_LOGIN_DETAILS'
+      )
+    })
+
+    it('should set INCORRECT_PASSWORD as nested error data on mismatch', async () => {
+      await assert.rejects(
+        () => PasswordUtils.compare('wrongpassword', hash),
+        (err) => {
+          assert.equal(err.data.error.name, 'INCORRECT_PASSWORD')
+          return true
+        }
+      )
+    })
+
+    it('should set INVALID_PARAMS as nested error data when params missing', async () => {
+      await assert.rejects(
+        () => PasswordUtils.compare('', ''),
+        (err) => {
+          assert.equal(err.data.error.name, 'INVALID_PARAMS')
+          assert.deepEqual(err.data.error.data.params, ['plainPassword', 'hash'])
+          return true
+        }
+      )
+    })
   })
 
   describe('#validate()', () => {
@@ -175,6 +220,27 @@ describe('PasswordUtils', () => {
       )
     })
 
+    it('should throw when password is null', async () => {
+      await assert.rejects(
+        () => PasswordUtils.validate(null),
+        (err) => err.name === 'INVALID_PARAMS'
+      )
+    })
+
+    it('should throw when password is undefined', async () => {
+      await assert.rejects(
+        () => PasswordUtils.validate(undefined),
+        (err) => err.name === 'INVALID_PARAMS'
+      )
+    })
+
+    it('should throw when password is a boolean', async () => {
+      await assert.rejects(
+        () => PasswordUtils.validate(true),
+        (err) => err.name === 'INVALID_PARAMS'
+      )
+    })
+
     it('should throw when password is too short', async () => {
       await assert.rejects(
         () => PasswordUtils.validate('short'),
@@ -182,6 +248,23 @@ describe('PasswordUtils', () => {
       )
     })
 
+    it('should include minimum length in INVALID_PASSWORD_LENGTH error data', async () => {
+      await assert.rejects(
+        () => PasswordUtils.validate('short'),
+        (err) => {
+          assert.equal(err.name, 'INVALID_PASSWORD')
+          const lengthErr = err.data.errors.find(e => e.name === 'INVALID_PASSWORD_LENGTH')
+          assert.ok(lengthErr)
+          assert.equal(lengthErr.data.length, 8)
+          return true
+        }
+      )
+    })
+
+    it('should accept a password of exactly minimum length', async () => {
+      await assert.doesNotReject(() => PasswordUtils.validate('12345678'))
+    })
+
     it('should throw when number is required but missing', async () => {
       authlocalConfig.passwordMustHaveNumber = true
       await assert.rejects(
@@ -232,11 +315,11 @@ describe('PasswordUtils', () => {
       )
     })
 
-    it('should accept a password with special character when required', async () => {
+    it('should accept each recognized special character', async () => {
       authlocalConfig.passwordMustHaveSpecial = true
       const specials = ['#', '?', '!', '@', '$', '%', '^', '&', '*', '-']
       for (const ch of specials) {
-        await assert.doesNotReject(() => PasswordUtils.validate(`abcdefg${ch}`))
+        await assert.doesNotReject(() => PasswordUtils.validate('abcdefg' + ch))
       }
     })
 
@@ -262,7 +345,12 @@ describe('PasswordUtils', () => {
       await assert.doesNotReject(() => PasswordUtils.validate('Abcdef1!'))
     })
 
-    // NOTE: The blacklist check in the source has a bug — it uses .some() where
+    it('should accept an empty string when minPasswordLength is zero', async () => {
+      authlocalConfig.minPasswordLength = 0
+      await assert.doesNotReject(() => PasswordUtils.validate(''))
+    })
+
+    // NOTE: The blacklist check in the source has a bug -- it uses .some() where
     // it should use .every(). This means a password containing a blacklisted
     // value can still pass if there are other blacklisted values it doesn't
     // contain. The test below documents the expected (correct) behaviour.
@@ -281,10 +369,15 @@ describe('PasswordUtils', () => {
       await assert.doesNotReject(() => PasswordUtils.validate('securevalue'))
     })
 
-    // BUG: The blacklist check uses .some(p => !(password.includes(p))) where
-    // it should use .every(). With multiple blacklisted values, a password
-    // containing one blacklisted value passes if another blacklisted value is
-    // absent. See PasswordUtils.js line 67.
+    it('should handle an empty blacklist array', async () => {
+      authlocalConfig.blacklistedPasswordValues = []
+      await assert.doesNotReject(() => PasswordUtils.validate('anything1'))
+    })
+
+    // TODO: Bug - blacklist check uses .some() instead of .every()
+    // With multiple blacklisted values, a password containing one blacklisted
+    // value passes if another blacklisted value is absent.
+    // See BUGS.md and PasswordUtils.js line 67.
     it('should throw when password contains any blacklisted value (multiple entries)', { todo: 'blacklist check uses .some() instead of .every()' }, async () => {
       authlocalConfig.blacklistedPasswordValues = ['password', 'qwerty']
       await assert.rejects(
@@ -315,11 +408,25 @@ describe('PasswordUtils', () => {
       )
     })
 
+    it('should throw when plainPassword is null', async () => {
+      await assert.rejects(
+        () => PasswordUtils.generate(null),
+        (err) => err.name === 'INVALID_PARAMS'
+      )
+    })
+
     it('should generate different hashes for the same password (salted)', async () => {
       const hash1 = await PasswordUtils.generate('samepassword')
       const hash2 = await PasswordUtils.generate('samepassword')
       assert.notEqual(hash1, hash2)
     })
+
+    it('should generate a hash verifiable with bcrypt compare', async () => {
+      const password = 'verifyMe123'
+      const hash = await PasswordUtils.generate(password)
+      const isValid = await promisify(bcrypt.compare)(password, hash)
+      assert.equal(isValid, true)
+    })
   })
 
   describe('#getRandomHex()', () => {
@@ -340,6 +447,12 @@ describe('PasswordUtils', () => {
       const hex2 = await PasswordUtils.getRandomHex()
       assert.notEqual(hex1, hex2)
     })
+
+    it('should handle a size of 1', async () => {
+      const hex = await PasswordUtils.getRandomHex(1)
+      assert.equal(hex.length, 2)
+      assert.ok(/^[0-9a-f]+$/.test(hex))
+    })
   })
 
   describe('#createReset()', () => {
@@ -364,6 +477,15 @@ describe('PasswordUtils', () => {
       assert.ok(mockPasswordResetsStore[0].token)
     })
 
+    it('should set expiresAt to a future date based on lifespan', async () => {
+      mockUsersStore.push({ email: 'test@example.com', authType: 'local' })
+      const beforeTime = Date.now()
+      await PasswordUtils.createReset('test@example.com', 86400000)
+      const expiresAt = new Date(mockPasswordResetsStore[0].expiresAt).getTime()
+      assert.ok(expiresAt >= beforeTime + 86400000)
+      assert.ok(expiresAt <= Date.now() + 86400000)
+    })
+
     it('should throw when user is not found', async () => {
       await assert.rejects(
         () => PasswordUtils.createReset('noone@example.com', 86400000),
@@ -371,6 +493,17 @@ describe('PasswordUtils', () => {
       )
     })
 
+    it('should include user email as id in NOT_FOUND error data', async () => {
+      await assert.rejects(
+        () => PasswordUtils.createReset('noone@example.com', 86400000),
+        (err) => {
+          assert.equal(err.data.id, 'noone@example.com')
+          assert.equal(err.data.type, 'user')
+          return true
+        }
+      )
+    })
+
     it('should throw when user is not authenticated with local auth', async () => {
       mockUsersStore.push({ email: 'sso@example.com', authType: 'sso' })
       await assert.rejects(
@@ -396,6 +529,10 @@ describe('PasswordUtils', () => {
       await PasswordUtils.deleteReset('abc123')
       assert.equal(mockPasswordResetsStore.length, 0)
     })
+
+    it('should not error when deleting a non-existent token', async () => {
+      await assert.doesNotReject(() => PasswordUtils.deleteReset('nonexistent'))
+    })
   })
 
   describe('#validateReset()', () => {
@@ -418,6 +555,13 @@ describe('PasswordUtils', () => {
       )
     })
 
+    it('should throw when token is null', async () => {
+      await assert.rejects(
+        () => PasswordUtils.validateReset(null),
+        (err) => err.name === 'INVALID_PARAMS'
+      )
+    })
+
     it('should throw when token is not found', async () => {
       await assert.rejects(
         () => PasswordUtils.validateReset('nonexistent'),
@@ -449,6 +593,24 @@ describe('PasswordUtils', () => {
       )
     })
 
+    // TODO: Bug - validateReset uses token.email instead of tokenData.email
+    // in the NOT_FOUND error data. Since token is a string, token.email is
+    // undefined. See PasswordUtils.js line 167.
+    it('should include correct email in NOT_FOUND error when user is missing', { todo: 'uses token.email (string) instead of tokenData.email' }, async () => {
+      mockPasswordResetsStore.push({
+        token: 'orphan-token',
+        email: 'orphan@example.com',
+        expiresAt: new Date(Date.now() + 86400000).toISOString()
+      })
+      await assert.rejects(
+        () => PasswordUtils.validateReset('orphan-token'),
+        (err) => {
+          assert.equal(err.data.id, 'orphan@example.com')
+          return true
+        }
+      )
+    })
+
     it('should return token data for a valid, non-expired token', async () => {
       const tokenData = {
         token: 'valid-token',
@@ -461,5 +623,16 @@ describe('PasswordUtils', () => {
       assert.equal(result.token, 'valid-token')
       assert.equal(result.email, 'test@example.com')
     })
+
+    it('should accept a token that has not yet expired', async () => {
+      mockPasswordResetsStore.push({
+        token: 'edge-token',
+        email: 'test@example.com',
+        expiresAt: new Date(Date.now() + 1000).toISOString()
+      })
+      mockUsersStore.push({ email: 'test@example.com' })
+      const result = await PasswordUtils.validateReset('edge-token')
+      assert.equal(result.token, 'edge-token')
+    })
   })
 })