adapt-authoring-auth-local 1.1.0 → 1.2.0

package/.github/workflows/tests.yml

@@ -0,0 +1,13 @@
+name: Tests
+on: push
+jobs:
+  default:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@master
+      - uses: actions/setup-node@master
+        with:
+          node-version: 'lts/*'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm test

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "adapt-authoring-auth-local",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Module which implements username/password (local) authentication",
   "homepage": "https://github.com/adapt-security/adapt-authoring-auth-local",
   "license": "GPL-3.0",
   "type": "module",
   "main": "index.js",
+  "scripts": {
+    "test": "node --experimental-test-module-mocks --test 'tests/*.spec.js'"
+  },
   "repository": "github:adapt-security/adapt-authoring-auth-local",
   "dependencies": {
     "adapt-authoring-auth": "^1.0.7",

package/tests/LocalAuthModule.spec.js

@@ -0,0 +1,635 @@
+import { describe, it, before, beforeEach, mock } from 'node:test'
+import assert from 'node:assert/strict'
+
+// --- Stub framework dependencies before importing LocalAuthModule ---
+
+const makeError = (name) => {
+  const err = { name, setData: (d) => ({ ...err, data: d }) }
+  return err
+}
+
+const mockErrors = {
+  INVALID_LOGIN_DETAILS: makeError('INVALID_LOGIN_DETAILS'),
+  ACCOUNT_LOCKED_PERM: makeError('ACCOUNT_LOCKED_PERM'),
+  ACCOUNT_LOCKED_TEMP: makeError('ACCOUNT_LOCKED_TEMP'),
+  INVALID_PARAMS: makeError('INVALID_PARAMS'),
+  INVALID_PASSWORD: makeError('INVALID_PASSWORD'),
+  INVALID_PASSWORD_LENGTH: makeError('INVALID_PASSWORD_LENGTH'),
+  INVALID_PASSWORD_NUMBER: makeError('INVALID_PASSWORD_NUMBER'),
+  INVALID_PASSWORD_UPPERCASE: makeError('INVALID_PASSWORD_UPPERCASE'),
+  INVALID_PASSWORD_LOWERCASE: makeError('INVALID_PASSWORD_LOWERCASE'),
+  INVALID_PASSWORD_SPECIAL: makeError('INVALID_PASSWORD_SPECIAL'),
+  BLACKLISTED_PASSWORD_VALUE: makeError('BLACKLISTED_PASSWORD_VALUE'),
+  INCORRECT_PASSWORD: makeError('INCORRECT_PASSWORD'),
+  NOT_FOUND: makeError('NOT_FOUND'),
+  SUPER_USER_EXISTS: makeError('SUPER_USER_EXISTS')
+}
+
+let authlocalConfig = {
+  failsUntilTemporaryLock: 5,
+  failsUntilPermanentLock: 20,
+  temporaryLockDuration: 60000,
+  inviteTokenLifespan: 604800000,
+  resetTokenLifespan: 86400000,
+  saltRounds: 10,
+  minPasswordLength: 8,
+  passwordMustHaveNumber: false,
+  passwordMustHaveUppercase: false,
+  passwordMustHaveLowercase: false,
+  passwordMustHaveSpecial: false,
+  blacklistedPasswordValues: []
+}
+
+const usersStore = []
+let updateCalls = []
+let disavowCalls = []
+let secureRouteCalls = []
+let unsecureRouteCalls = []
+
+const mockUsers = {
+  find: async (query) => usersStore.filter(u => {
+    return Object.entries(query).every(([k, v]) => JSON.stringify(u[k]) === JSON.stringify(v))
+  }),
+  update: async (query, data) => {
+    updateCalls.push({ query, data })
+    return { ...query, ...data }
+  },
+  collectionName: 'users'
+}
+
+const mockRoles = {
+  find: async () => [{ _id: 'role-super-id', shortName: 'superuser' }]
+}
+
+const mockMailer = {
+  isEnabled: true,
+  send: async () => {}
+}
+
+const mockServer = {
+  root: { url: 'http://localhost:5000' }
+}
+
+const mockMongodb = {
+  update: async (collection, query, update) => {
+    return { _id: 'user-id-1', email: 'test@example.com', ...update.$set }
+  },
+  find: async () => [],
+  insert: async (collection, data) => data,
+  delete: async () => {},
+  getCollection: () => ({ deleteMany: async () => {} })
+}
+
+const mockJsonschema = {
+  getSchema: async () => ({
+    validate: async () => true
+  })
+}
+
+const moduleMap = {
+  users: mockUsers,
+  roles: mockRoles,
+  mailer: mockMailer,
+  server: mockServer,
+  mongodb: mockMongodb,
+  jsonschema: mockJsonschema,
+  'auth-local': {
+    getConfig: (key) => authlocalConfig[key],
+    log: () => {}
+  }
+}
+
+const mockApp = {
+  errors: mockErrors,
+  waitForModule: async (...names) => {
+    if (names.length === 1) return moduleMap[names[0]]
+    return names.map(n => moduleMap[n])
+  },
+  lang: {
+    translate: (_, key) => `translated:${key}`
+  }
+}
+
+// Stub adapt-authoring-auth to provide AbstractAuthModule
+mock.module('adapt-authoring-auth', {
+  namedExports: {
+    AbstractAuthModule: class AbstractAuthModule {
+      constructor () {
+        this.app = mockApp
+        this.router = { routes: [{ route: '/', meta: null }, { route: '/register', meta: null }] }
+      }
+
+      getConfig (key) { return authlocalConfig[key] }
+
+      async init () {}
+
+      async register (data) { return { _id: 'new-user-id', ...data } }
+
+      async setUserEnabled () {}
+
+      secureRoute (...args) { secureRouteCalls.push(args) }
+
+      unsecureRoute (...args) { unsecureRouteCalls.push(args) }
+
+      disavowUser (...args) { disavowCalls.push(args) }
+
+      log () {}
+    }
+  }
+})
+
+mock.module('adapt-authoring-core', {
+  namedExports: { App: { instance: mockApp } }
+})
+
+const { default: LocalAuthModule } = await import('../lib/LocalAuthModule.js')
+
+describe('LocalAuthModule', () => {
+  let mod
+
+  before(async () => {
+    mod = new LocalAuthModule()
+    mod.app = mockApp
+    mod.users = mockUsers
+    mod.userSchema = 'localauthuser'
+    mod.type = 'local'
+  })
+
+  beforeEach(() => {
+    updateCalls = []
+    disavowCalls = []
+    secureRouteCalls = []
+    unsecureRouteCalls = []
+    usersStore.length = 0
+    authlocalConfig = {
+      failsUntilTemporaryLock: 5,
+      failsUntilPermanentLock: 20,
+      temporaryLockDuration: 60000,
+      inviteTokenLifespan: 604800000,
+      resetTokenLifespan: 86400000,
+      saltRounds: 10,
+      minPasswordLength: 8,
+      passwordMustHaveNumber: false,
+      passwordMustHaveUppercase: false,
+      passwordMustHaveLowercase: false,
+      passwordMustHaveSpecial: false,
+      blacklistedPasswordValues: []
+    }
+  })
+
+  describe('.formatRemainingTime()', () => {
+    it('should return a human-readable string for remaining seconds', () => {
+      const result = LocalAuthModule.formatRemainingTime(60)
+      assert.equal(typeof result, 'string')
+      assert.ok(result.length > 0)
+    })
+
+    it('should return a string containing "second" for small values', () => {
+      const result = LocalAuthModule.formatRemainingTime(5)
+      assert.ok(result.includes('second'))
+    })
+
+    it('should return a string containing "minute" for 60 seconds', () => {
+      const result = LocalAuthModule.formatRemainingTime(60)
+      assert.ok(result.includes('minute'))
+    })
+  })
+
+  describe('#setValues()', () => {
+    it('should set userSchema to localauthuser', async () => {
+      const instance = new LocalAuthModule()
+      await instance.setValues()
+      assert.equal(instance.userSchema, 'localauthuser')
+    })
+
+    it('should set type to local', async () => {
+      const instance = new LocalAuthModule()
+      await instance.setValues()
+      assert.equal(instance.type, 'local')
+    })
+
+    it('should define 5 routes', async () => {
+      const instance = new LocalAuthModule()
+      await instance.setValues()
+      assert.equal(instance.routes.length, 5)
+    })
+
+    it('should include the expected route paths', async () => {
+      const instance = new LocalAuthModule()
+      await instance.setValues()
+      const paths = instance.routes.map(r => r.route)
+      assert.deepEqual(paths, ['/invite', '/registersuper', '/changepass', '/forgotpass', '/validatepass'])
+    })
+
+    it('should mark registersuper as internal', async () => {
+      const instance = new LocalAuthModule()
+      await instance.setValues()
+      const superRoute = instance.routes.find(r => r.route === '/registersuper')
+      assert.equal(superRoute.internal, true)
+    })
+  })
+
+  describe('#init()', () => {
+    it('should secure the invite route', 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] === '/invite' && c[1] === 'post'))
+    })
+
+    it('should secure the validatepass route', 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'))
+    })
+
+    it('should unsecure registersuper, changepass, and forgotpass 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()
+      const unsecuredPaths = unsecureRouteCalls.map(c => c[0])
+      assert.ok(unsecuredPaths.includes('/registersuper'))
+      assert.ok(unsecuredPaths.includes('/changepass'))
+      assert.ok(unsecuredPaths.includes('/forgotpass'))
+    })
+
+    it('should set the users property', 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.equal(instance.users, mockUsers)
+    })
+  })
+
+  describe('#authenticate()', () => {
+    it('should throw when password is not provided in request body', async () => {
+      const req = { body: {} }
+      await assert.rejects(
+        () => mod.authenticate({}, req, {}),
+        (err) => err.name === 'INVALID_LOGIN_DETAILS'
+      )
+    })
+
+    it('should reset failed attempts on successful authentication', 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: 2,
+        lastFailedLoginAttempt: null
+      }
+      const req = { body: { password: 'correctpass' } }
+      await mod.authenticate(user, req, {})
+      const lastUpdate = updateCalls[updateCalls.length - 1]
+      assert.equal(lastUpdate.data.failedLoginAttempts, 0)
+    })
+
+    it('should increment failed attempts 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.equal(lastUpdate.data.failedLoginAttempts, 1)
+    })
+
+    it('should temporarily lock after reaching failsUntilTemporaryLock threshold', 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: 4, // one more will be 5 (the threshold)
+        lastFailedLoginAttempt: null
+      }
+      const req = { body: { password: 'wrongpass' } }
+      await assert.rejects(
+        () => mod.authenticate(user, req, {}),
+        (err) => err.name === 'ACCOUNT_LOCKED_TEMP'
+      )
+      const lastUpdate = updateCalls[updateCalls.length - 1]
+      assert.equal(lastUpdate.data.isTempLocked, true)
+    })
+
+    it('should permanently lock after reaching failsUntilPermanentLock threshold', 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: 19, // one more will be 20 (the threshold)
+        lastFailedLoginAttempt: null
+      }
+      const req = { body: { password: 'wrongpass' } }
+      await assert.rejects(
+        () => mod.authenticate(user, req, {}),
+        (err) => err.name === 'ACCOUNT_LOCKED_PERM'
+      )
+      const lastUpdate = updateCalls[updateCalls.length - 1]
+      assert.equal(lastUpdate.data.isPermLocked, true)
+    })
+
+    it('should throw ACCOUNT_LOCKED_PERM when user is already permanently locked', async () => {
+      const { default: PasswordUtils } = await import('../lib/PasswordUtils.js')
+      const hash = await PasswordUtils.generate('correctpass')
+      const user = {
+        _id: 'user-1',
+        password: hash,
+        isPermLocked: true,
+        isTempLocked: false,
+        failedLoginAttempts: 20,
+        lastFailedLoginAttempt: new Date().toISOString()
+      }
+      const req = { body: { password: 'correctpass' } }
+      await assert.rejects(
+        () => mod.authenticate(user, req, {}),
+        (err) => err.name === 'ACCOUNT_LOCKED_PERM'
+      )
+    })
+
+    it('should not increment failed attempts when account is permanently locked', async () => {
+      const { default: PasswordUtils } = await import('../lib/PasswordUtils.js')
+      const hash = await PasswordUtils.generate('correctpass')
+      const user = {
+        _id: 'user-1',
+        password: hash,
+        isPermLocked: true,
+        isTempLocked: false,
+        failedLoginAttempts: 20,
+        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, 20)
+    })
+  })
+
+  describe('#handleLockStatus()', () => {
+    it('should throw ACCOUNT_LOCKED_PERM when user is permanently locked', async () => {
+      await assert.rejects(
+        () => mod.handleLockStatus({ isPermLocked: true, isTempLocked: false }),
+        (err) => err.name === 'ACCOUNT_LOCKED_PERM'
+      )
+    })
+
+    it('should throw ACCOUNT_LOCKED_TEMP when user is temp locked and lock has not expired', async () => {
+      const user = {
+        isPermLocked: false,
+        isTempLocked: true,
+        // NOTE: handleLockStatus multiplies temporaryLockDuration by 1000, which
+        // appears to be a bug if the config value is already in ms (isTimeMs: true).
+        // We set lastFailedLoginAttempt to now so the lock is still active with
+        // the doubled value.
+        lastFailedLoginAttempt: new Date().toISOString()
+      }
+      await assert.rejects(
+        () => mod.handleLockStatus(user),
+        (err) => err.name === 'ACCOUNT_LOCKED_TEMP'
+      )
+    })
+
+    it('should unlock user when temp lock has expired', async () => {
+      const user = {
+        _id: 'user-1',
+        isPermLocked: false,
+        isTempLocked: true,
+        // Set to long ago so the lock is expired (even with the * 1000 bug)
+        lastFailedLoginAttempt: new Date(Date.now() - 999999999).toISOString()
+      }
+      await mod.handleLockStatus(user)
+      const lastUpdate = updateCalls[updateCalls.length - 1]
+      assert.equal(lastUpdate.data.isTempLocked, false)
+    })
+
+    it('should not update anything when user is not locked', async () => {
+      const user = {
+        isPermLocked: false,
+        isTempLocked: false,
+        lastFailedLoginAttempt: null
+      }
+      await mod.handleLockStatus(user)
+      assert.equal(updateCalls.length, 0)
+    })
+  })
+
+  describe('#register()', () => {
+    it('should hash the password and call super.register', async () => {
+      const result = await mod.register({ email: 'new@example.com', password: 'validpassword' })
+      assert.equal(result._id, 'new-user-id')
+      assert.equal(result.email, 'new@example.com')
+      assert.ok(result.password.startsWith('$2a$') || result.password.startsWith('$2b$'))
+    })
+
+    it('should auto-generate a password when none is provided', async () => {
+      const result = await mod.register({ email: 'new@example.com' })
+      assert.ok(result.password)
+      assert.ok(result.password.startsWith('$2a$') || result.password.startsWith('$2b$'))
+    })
+  })
+
+  describe('#registerSuper()', () => {
+    it('should throw SUPER_USER_EXISTS when a super user already exists', async () => {
+      usersStore.push({ _id: 'existing-super', roles: ['role-super-id'] })
+      await assert.rejects(
+        () => mod.registerSuper({ email: 'super@example.com', password: 'validpassword' }),
+        (err) => err.name === 'SUPER_USER_EXISTS'
+      )
+    })
+  })
+
+  describe('#setUserEnabled()', () => {
+    it('should reset failed attempts and unlock when enabling a user', async () => {
+      const user = { _id: 'user-1', failedLoginAttempts: 10 }
+      await mod.setUserEnabled(user, true)
+      const lastUpdate = updateCalls[updateCalls.length - 1]
+      assert.equal(lastUpdate.data.failedLoginAttempts, 0)
+      assert.equal(lastUpdate.data.isPermLocked, false)
+      assert.equal(lastUpdate.data.isTempLocked, 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.
+    it('should lock the account when disabling a user', async () => {
+      const user = { _id: 'user-1', failedLoginAttempts: 3, failedAttempts: 3 }
+      await mod.setUserEnabled(user, false)
+      const lastUpdate = updateCalls[updateCalls.length - 1]
+      assert.equal(lastUpdate.data.isPermLocked, true)
+      assert.equal(lastUpdate.data.isTempLocked, true)
+    })
+  })
+
+  describe('#updateUser()', () => {
+    it('should accept a string ID as userIdOrQuery', async () => {
+      await mod.updateUser('user-id-1', { firstName: 'Updated' })
+      const lastUpdate = updateCalls[updateCalls.length - 1]
+      assert.deepEqual(lastUpdate.query, { _id: 'user-id-1' })
+    })
+
+    it('should accept a query object as userIdOrQuery', async () => {
+      await mod.updateUser({ email: 'test@example.com' }, { firstName: 'Updated' })
+      const lastUpdate = updateCalls[updateCalls.length - 1]
+      assert.deepEqual(lastUpdate.query, { email: 'test@example.com' })
+    })
+
+    it('should hash password when update includes password', async () => {
+      const result = await mod.updateUser('user-id-1', { password: 'newpassword' })
+      assert.ok(result)
+    })
+
+    it('should not hash password when update does not include password', async () => {
+      await mod.updateUser('user-id-1', { firstName: 'NoPassword' })
+      const lastUpdate = updateCalls[updateCalls.length - 1]
+      assert.equal(lastUpdate.data.firstName, 'NoPassword')
+      assert.equal(Object.prototype.hasOwnProperty.call(lastUpdate.data, 'password'), false)
+    })
+  })
+
+  describe('#createPasswordReset()', () => {
+    it('should throw when email is not provided', async () => {
+      await assert.rejects(
+        () => mod.createPasswordReset(''),
+        (err) => err.name === 'INVALID_PARAMS'
+      )
+    })
+
+    it('should throw when email is undefined', async () => {
+      await assert.rejects(
+        () => mod.createPasswordReset(undefined),
+        (err) => err.name === 'INVALID_PARAMS'
+      )
+    })
+  })
+
+  describe('#inviteHandler()', () => {
+    it('should respond with 204 on success', async () => {
+      let statusSent
+      const req = {
+        body: { email: 'invite@example.com' },
+        translate: (key) => `translated:${key}`,
+        auth: { user: { _id: { toString: () => 'admin-id' } } }
+      }
+      const res = {
+        sendStatus: (code) => { statusSent = code }
+      }
+      // Stub createPasswordReset to avoid real execution
+      const original = mod.createPasswordReset.bind(mod)
+      mod.createPasswordReset = async () => {}
+      await mod.inviteHandler(req, res, () => {})
+      mod.createPasswordReset = original
+      assert.equal(statusSent, 204)
+    })
+
+    it('should call next with error on failure', async () => {
+      let nextError
+      const req = {
+        body: { email: '' },
+        translate: (key) => `translated:${key}`,
+        auth: {}
+      }
+      const res = { sendStatus: () => {} }
+      await mod.inviteHandler(req, res, (err) => { nextError = err })
+      assert.ok(nextError)
+    })
+  })
+
+  describe('#registerSuperHandler()', () => {
+    it('should respond with 204 on success', async () => {
+      let statusSent
+      const req = { body: { email: 'super@example.com', password: 'validpassword' } }
+      const res = { sendStatus: (code) => { statusSent = code } }
+      // Stub registerSuper
+      const original = mod.registerSuper.bind(mod)
+      mod.registerSuper = async () => {}
+      await mod.registerSuperHandler(req, res, () => {})
+      mod.registerSuper = original
+      assert.equal(statusSent, 204)
+    })
+
+    it('should call next with error on failure', async () => {
+      let nextError
+      const req = { body: { email: 'super@example.com', password: 'validpassword' } }
+      const res = { sendStatus: () => {} }
+      usersStore.push({ _id: 'existing', roles: ['role-super-id'] })
+      await mod.registerSuperHandler(req, res, (err) => { nextError = err })
+      assert.ok(nextError)
+    })
+  })
+
+  describe('#forgotPasswordHandler()', () => {
+    it('should always respond with 200 and a message (even on error)', async () => {
+      let responseStatus
+      let responseJson
+      const req = {
+        body: { email: '' },
+        translate: (key) => `translated:${key}`,
+        auth: {}
+      }
+      const res = {
+        status: (code) => {
+          responseStatus = code
+          return { json: (data) => { responseJson = data } }
+        }
+      }
+      await mod.forgotPasswordHandler(req, res, () => {})
+      assert.equal(responseStatus, 200)
+      assert.ok(responseJson.message)
+    })
+  })
+
+  describe('#validatePasswordHandler()', () => {
+    it('should respond with a success message for a valid password', async () => {
+      let responseJson
+      const req = {
+        body: { password: 'validpassword' },
+        translate: (key) => `translated:${key}`
+      }
+      const res = {
+        json: (data) => { responseJson = data }
+      }
+      await mod.validatePasswordHandler(req, res, () => {})
+      assert.ok(responseJson.message)
+    })
+
+    it('should call sendError for an invalid password', 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.ok(sentError)
+      assert.equal(sentError.name, 'INVALID_PASSWORD')
+    })
+  })
+})

package/tests/PasswordUtils.spec.js

@@ -0,0 +1,465 @@
+import { describe, it, before, beforeEach, after, mock } from 'node:test'
+import assert from 'node:assert/strict'
+import bcrypt from 'bcryptjs'
+import { promisify } from 'util'
+
+// --- Stub App.instance before importing PasswordUtils ---
+
+const mockErrors = {
+  INVALID_LOGIN_DETAILS: { setData: (d) => ({ ...mockErrors.INVALID_LOGIN_DETAILS, data: d, name: 'INVALID_LOGIN_DETAILS' }), name: 'INVALID_LOGIN_DETAILS' },
+  INVALID_PARAMS: { setData: (d) => ({ ...mockErrors.INVALID_PARAMS, data: d, name: 'INVALID_PARAMS' }), name: 'INVALID_PARAMS' },
+  INVALID_PASSWORD: { setData: (d) => ({ ...mockErrors.INVALID_PASSWORD, data: d, name: 'INVALID_PASSWORD' }), name: 'INVALID_PASSWORD' },
+  INVALID_PASSWORD_LENGTH: { setData: (d) => ({ ...mockErrors.INVALID_PASSWORD_LENGTH, data: d, name: 'INVALID_PASSWORD_LENGTH' }), name: 'INVALID_PASSWORD_LENGTH' },
+  INVALID_PASSWORD_NUMBER: { setData: (d) => ({ ...mockErrors.INVALID_PASSWORD_NUMBER, data: d, name: 'INVALID_PASSWORD_NUMBER' }), name: 'INVALID_PASSWORD_NUMBER' },
+  INVALID_PASSWORD_UPPERCASE: { setData: (d) => ({ ...mockErrors.INVALID_PASSWORD_UPPERCASE, data: d, name: 'INVALID_PASSWORD_UPPERCASE' }), name: 'INVALID_PASSWORD_UPPERCASE' },
+  INVALID_PASSWORD_LOWERCASE: { setData: (d) => ({ ...mockErrors.INVALID_PASSWORD_LOWERCASE, data: d, name: 'INVALID_PASSWORD_LOWERCASE' }), name: 'INVALID_PASSWORD_LOWERCASE' },
+  INVALID_PASSWORD_SPECIAL: { setData: (d) => ({ ...mockErrors.INVALID_PASSWORD_SPECIAL, data: d, name: 'INVALID_PASSWORD_SPECIAL' }), name: 'INVALID_PASSWORD_SPECIAL' },
+  BLACKLISTED_PASSWORD_VALUE: { setData: (d) => ({ ...mockErrors.BLACKLISTED_PASSWORD_VALUE, data: d, name: 'BLACKLISTED_PASSWORD_VALUE' }), name: 'BLACKLISTED_PASSWORD_VALUE' },
+  INCORRECT_PASSWORD: { name: 'INCORRECT_PASSWORD' },
+  NOT_FOUND: { setData: (d) => ({ ...mockErrors.NOT_FOUND, data: d, name: 'NOT_FOUND' }), name: 'NOT_FOUND' },
+  AUTH_TOKEN_INVALID: { name: 'AUTH_TOKEN_INVALID' },
+  AUTH_TOKEN_EXPIRED: { name: 'AUTH_TOKEN_EXPIRED' },
+  ACCOUNT_NOT_LOCALAUTHD: { name: 'ACCOUNT_NOT_LOCALAUTHD' }
+}
+
+let authlocalConfig = {
+  saltRounds: 10,
+  minPasswordLength: 8,
+  passwordMustHaveNumber: false,
+  passwordMustHaveUppercase: false,
+  passwordMustHaveLowercase: false,
+  passwordMustHaveSpecial: false,
+  blacklistedPasswordValues: [],
+  resetTokenLifespan: 86400000
+}
+
+const mockPasswordResetsStore = []
+const mockUsersStore = []
+
+const mockAuthlocal = {
+  getConfig: (key) => authlocalConfig[key],
+  log: () => {}
+}
+
+const mockJsonschema = {
+  getSchema: async () => ({
+    validate: async () => true
+  })
+}
+
+const mockMongodbCollection = {
+  deleteMany: async () => {}
+}
+
+const mockMongodb = {
+  find: async (collection, query) => {
+    if (collection === 'passwordresets') {
+      return mockPasswordResetsStore.filter(r => r.token === query.token)
+    }
+    return []
+  },
+  insert: async (collection, data) => {
+    mockPasswordResetsStore.push(data)
+    return data
+  },
+  delete: async (collection, query) => {
+    const idx = mockPasswordResetsStore.findIndex(r => r.token === query.token)
+    if (idx !== -1) mockPasswordResetsStore.splice(idx, 1)
+  },
+  getCollection: () => mockMongodbCollection
+}
+
+const mockUsers = {
+  find: async (query) => {
+    return mockUsersStore.filter(u => u.email === query.email)
+  }
+}
+
+const moduleMap = {
+  'auth-local': mockAuthlocal,
+  jsonschema: mockJsonschema,
+  mongodb: mockMongodb,
+  users: mockUsers
+}
+
+const mockApp = {
+  errors: mockErrors,
+  waitForModule: async (...names) => {
+    if (names.length === 1) return moduleMap[names[0]]
+    return names.map(n => moduleMap[n])
+  }
+}
+
+// Register the mock for adapt-authoring-core before importing PasswordUtils
+mock.module('adapt-authoring-core', {
+  namedExports: { App: { instance: mockApp } }
+})
+
+const { default: PasswordUtils } = await import('../lib/PasswordUtils.js')
+
+describe('PasswordUtils', () => {
+  describe('#getConfig()', () => {
+    it('should return a single config value when one key is passed', async () => {
+      const result = await PasswordUtils.getConfig('saltRounds')
+      assert.equal(result, 10)
+    })
+
+    it('should return an object of config values when multiple keys are passed', async () => {
+      const result = await PasswordUtils.getConfig('saltRounds', 'minPasswordLength')
+      assert.deepEqual(result, { saltRounds: 10, minPasswordLength: 8 })
+    })
+  })
+
+  describe('#compare()', () => {
+    let hash
+
+    before(async () => {
+      const salt = await promisify(bcrypt.genSalt)(10)
+      hash = await promisify(bcrypt.hash)('correctpassword', salt)
+    })
+
+    it('should resolve without error when password matches hash', async () => {
+      await assert.doesNotReject(() => PasswordUtils.compare('correctpassword', hash))
+    })
+
+    it('should throw when password does not match hash', async () => {
+      await assert.rejects(
+        () => PasswordUtils.compare('wrongpassword', hash),
+        (err) => err.name === 'INVALID_LOGIN_DETAILS'
+      )
+    })
+
+    it('should throw when plainPassword is empty', async () => {
+      await assert.rejects(
+        () => PasswordUtils.compare('', hash),
+        (err) => err.name === 'INVALID_LOGIN_DETAILS'
+      )
+    })
+
+    it('should throw when hash is empty', async () => {
+      await assert.rejects(
+        () => PasswordUtils.compare('password', ''),
+        (err) => err.name === 'INVALID_LOGIN_DETAILS'
+      )
+    })
+
+    it('should throw when both arguments are missing', async () => {
+      await assert.rejects(
+        () => PasswordUtils.compare(undefined, undefined),
+        (err) => err.name === 'INVALID_LOGIN_DETAILS'
+      )
+    })
+  })
+
+  describe('#validate()', () => {
+    beforeEach(() => {
+      authlocalConfig = {
+        ...authlocalConfig,
+        minPasswordLength: 8,
+        passwordMustHaveNumber: false,
+        passwordMustHaveUppercase: false,
+        passwordMustHaveLowercase: false,
+        passwordMustHaveSpecial: false,
+        blacklistedPasswordValues: []
+      }
+    })
+
+    it('should resolve for a valid password meeting minimum length', async () => {
+      await assert.doesNotReject(() => PasswordUtils.validate('abcdefgh'))
+    })
+
+    it('should throw when password is not a string', async () => {
+      await assert.rejects(
+        () => PasswordUtils.validate(12345678),
+        (err) => err.name === 'INVALID_PARAMS'
+      )
+    })
+
+    it('should throw when password is too short', async () => {
+      await assert.rejects(
+        () => PasswordUtils.validate('short'),
+        (err) => err.name === 'INVALID_PASSWORD'
+      )
+    })
+
+    it('should throw when number is required but missing', async () => {
+      authlocalConfig.passwordMustHaveNumber = true
+      await assert.rejects(
+        () => PasswordUtils.validate('abcdefgh'),
+        (err) => {
+          assert.equal(err.name, 'INVALID_PASSWORD')
+          return true
+        }
+      )
+    })
+
+    it('should accept a password with a number when required', async () => {
+      authlocalConfig.passwordMustHaveNumber = true
+      await assert.doesNotReject(() => PasswordUtils.validate('abcdefg1'))
+    })
+
+    it('should throw when uppercase is required but missing', async () => {
+      authlocalConfig.passwordMustHaveUppercase = true
+      await assert.rejects(
+        () => PasswordUtils.validate('abcdefgh'),
+        (err) => err.name === 'INVALID_PASSWORD'
+      )
+    })
+
+    it('should accept a password with uppercase when required', async () => {
+      authlocalConfig.passwordMustHaveUppercase = true
+      await assert.doesNotReject(() => PasswordUtils.validate('Abcdefgh'))
+    })
+
+    it('should throw when lowercase is required but missing', async () => {
+      authlocalConfig.passwordMustHaveLowercase = true
+      await assert.rejects(
+        () => PasswordUtils.validate('ABCDEFGH'),
+        (err) => err.name === 'INVALID_PASSWORD'
+      )
+    })
+
+    it('should accept a password with lowercase when required', async () => {
+      authlocalConfig.passwordMustHaveLowercase = true
+      await assert.doesNotReject(() => PasswordUtils.validate('abcdefgh'))
+    })
+
+    it('should throw when special character is required but missing', async () => {
+      authlocalConfig.passwordMustHaveSpecial = true
+      await assert.rejects(
+        () => PasswordUtils.validate('abcdefgh'),
+        (err) => err.name === 'INVALID_PASSWORD'
+      )
+    })
+
+    it('should accept a password with special character when required', async () => {
+      authlocalConfig.passwordMustHaveSpecial = true
+      const specials = ['#', '?', '!', '@', '$', '%', '^', '&', '*', '-']
+      for (const ch of specials) {
+        await assert.doesNotReject(() => PasswordUtils.validate(`abcdefg${ch}`))
+      }
+    })
+
+    it('should collect multiple validation errors', async () => {
+      authlocalConfig.passwordMustHaveNumber = true
+      authlocalConfig.passwordMustHaveUppercase = true
+      authlocalConfig.passwordMustHaveSpecial = true
+      await assert.rejects(
+        () => PasswordUtils.validate('abcdefgh'),
+        (err) => {
+          assert.equal(err.name, 'INVALID_PASSWORD')
+          assert.ok(err.data.errors.length >= 3)
+          return true
+        }
+      )
+    })
+
+    it('should pass all complexity rules simultaneously', async () => {
+      authlocalConfig.passwordMustHaveNumber = true
+      authlocalConfig.passwordMustHaveUppercase = true
+      authlocalConfig.passwordMustHaveLowercase = true
+      authlocalConfig.passwordMustHaveSpecial = true
+      await assert.doesNotReject(() => PasswordUtils.validate('Abcdef1!'))
+    })
+
+    // 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.
+    // See PasswordUtils.js line 67.
+    it('should throw when password contains a blacklisted value', async () => {
+      authlocalConfig.blacklistedPasswordValues = ['password']
+      // With only one blacklisted entry, .some() and .every() behave identically
+      await assert.rejects(
+        () => PasswordUtils.validate('password123'),
+        (err) => err.name === 'INVALID_PASSWORD'
+      )
+    })
+
+    it('should accept a password not containing blacklisted values', async () => {
+      authlocalConfig.blacklistedPasswordValues = ['password']
+      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 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(
+        () => PasswordUtils.validate('password123'),
+        (err) => err.name === 'INVALID_PASSWORD'
+      )
+    })
+  })
+
+  describe('#generate()', () => {
+    it('should return a bcrypt hash for a valid password', async () => {
+      const hash = await PasswordUtils.generate('validpassword')
+      assert.equal(typeof hash, 'string')
+      assert.ok(hash.startsWith('$2a$') || hash.startsWith('$2b$'))
+    })
+
+    it('should throw when plainPassword is empty', async () => {
+      await assert.rejects(
+        () => PasswordUtils.generate(''),
+        (err) => err.name === 'INVALID_PARAMS'
+      )
+    })
+
+    it('should throw when plainPassword is undefined', async () => {
+      await assert.rejects(
+        () => PasswordUtils.generate(undefined),
+        (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)
+    })
+  })
+
+  describe('#getRandomHex()', () => {
+    it('should return a hex string of default length (64 chars for 32 bytes)', async () => {
+      const hex = await PasswordUtils.getRandomHex()
+      assert.equal(typeof hex, 'string')
+      assert.equal(hex.length, 64)
+      assert.ok(/^[0-9a-f]+$/.test(hex))
+    })
+
+    it('should return a hex string of specified length', async () => {
+      const hex = await PasswordUtils.getRandomHex(16)
+      assert.equal(hex.length, 32)
+    })
+
+    it('should return unique values on subsequent calls', async () => {
+      const hex1 = await PasswordUtils.getRandomHex()
+      const hex2 = await PasswordUtils.getRandomHex()
+      assert.notEqual(hex1, hex2)
+    })
+  })
+
+  describe('#createReset()', () => {
+    beforeEach(() => {
+      mockPasswordResetsStore.length = 0
+      mockUsersStore.length = 0
+    })
+
+    it('should create a reset token for a valid local auth user', async () => {
+      mockUsersStore.push({ email: 'test@example.com', authType: 'local' })
+      const token = await PasswordUtils.createReset('test@example.com', 86400000)
+      assert.equal(typeof token, 'string')
+      assert.ok(token.length > 0)
+    })
+
+    it('should store the reset data in the collection', async () => {
+      mockUsersStore.push({ email: 'test@example.com', authType: 'local' })
+      await PasswordUtils.createReset('test@example.com', 86400000)
+      assert.equal(mockPasswordResetsStore.length, 1)
+      assert.equal(mockPasswordResetsStore[0].email, 'test@example.com')
+      assert.ok(mockPasswordResetsStore[0].expiresAt)
+      assert.ok(mockPasswordResetsStore[0].token)
+    })
+
+    it('should throw when user is not found', async () => {
+      await assert.rejects(
+        () => PasswordUtils.createReset('noone@example.com', 86400000),
+        (err) => err.name === 'NOT_FOUND'
+      )
+    })
+
+    it('should throw when user is not authenticated with local auth', async () => {
+      mockUsersStore.push({ email: 'sso@example.com', authType: 'sso' })
+      await assert.rejects(
+        () => PasswordUtils.createReset('sso@example.com', 86400000),
+        (err) => err.name === 'ACCOUNT_NOT_LOCALAUTHD'
+      )
+    })
+
+    it('should use default resetTokenLifespan when lifespan is not provided', async () => {
+      mockUsersStore.push({ email: 'test@example.com', authType: 'local' })
+      const token = await PasswordUtils.createReset('test@example.com')
+      assert.equal(typeof token, 'string')
+    })
+  })
+
+  describe('#deleteReset()', () => {
+    beforeEach(() => {
+      mockPasswordResetsStore.length = 0
+    })
+
+    it('should remove the reset token from the store', async () => {
+      mockPasswordResetsStore.push({ token: 'abc123', email: 'test@example.com' })
+      await PasswordUtils.deleteReset('abc123')
+      assert.equal(mockPasswordResetsStore.length, 0)
+    })
+  })
+
+  describe('#validateReset()', () => {
+    beforeEach(() => {
+      mockPasswordResetsStore.length = 0
+      mockUsersStore.length = 0
+    })
+
+    it('should throw when token is empty', async () => {
+      await assert.rejects(
+        () => PasswordUtils.validateReset(''),
+        (err) => err.name === 'INVALID_PARAMS'
+      )
+    })
+
+    it('should throw when token is undefined', async () => {
+      await assert.rejects(
+        () => PasswordUtils.validateReset(undefined),
+        (err) => err.name === 'INVALID_PARAMS'
+      )
+    })
+
+    it('should throw when token is not found', async () => {
+      await assert.rejects(
+        () => PasswordUtils.validateReset('nonexistent'),
+        (err) => err.name === 'AUTH_TOKEN_INVALID'
+      )
+    })
+
+    it('should throw when token is expired', async () => {
+      mockPasswordResetsStore.push({
+        token: 'expired-token',
+        email: 'test@example.com',
+        expiresAt: new Date(Date.now() - 1000).toISOString()
+      })
+      await assert.rejects(
+        () => PasswordUtils.validateReset('expired-token'),
+        (err) => err.name === 'AUTH_TOKEN_EXPIRED'
+      )
+    })
+
+    it('should throw when user associated with token is not found', async () => {
+      mockPasswordResetsStore.push({
+        token: 'valid-token',
+        email: 'deleted@example.com',
+        expiresAt: new Date(Date.now() + 86400000).toISOString()
+      })
+      await assert.rejects(
+        () => PasswordUtils.validateReset('valid-token'),
+        (err) => err.name === 'NOT_FOUND'
+      )
+    })
+
+    it('should return token data for a valid, non-expired token', async () => {
+      const tokenData = {
+        token: 'valid-token',
+        email: 'test@example.com',
+        expiresAt: new Date(Date.now() + 86400000).toISOString()
+      }
+      mockPasswordResetsStore.push(tokenData)
+      mockUsersStore.push({ email: 'test@example.com' })
+      const result = await PasswordUtils.validateReset('valid-token')
+      assert.equal(result.token, 'valid-token')
+      assert.equal(result.email, 'test@example.com')
+    })
+  })
+})