feat: self-describing password hashes (iterations$hex)

Store PBKDF2 iteration count alongside the hash to eliminate the
linear fallback chain that tried current then legacy iterations on
every login attempt. A wrong password now costs exactly one PBKDF2
computation regardless of how many iteration baselines have existed.

Future iteration bumps (via PBKDF2_ITERATIONS env var) require zero
code changes — users at older iterations silently upgrade on login.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: aberoham

lib/user/mysql.js

@@ -39,7 +39,7 @@ class UserRepoMySQL extends UserBase {
       if (await this.validPassword(authTry.password, u.password, authTry.username, u.pass_salt)) {
         if (this._needsUpgrade) {
           const salt = this.generateSalt()
-          const hash = await this.hashAuthPbkdf2(authTry.password, salt)
+          const hash = await this.hashForStorage(authTry.password, salt)
           await Mysql.execute(
             ...Mysql.update('nt_user', `nt_user_id=${u.id}`, {
               password: hash,
@@ -75,7 +75,7 @@ class UserRepoMySQL extends UserBase {
 
     if (args.password) {
       if (!args.pass_salt) args.pass_salt = this.generateSalt()
-      args.password = await this.hashAuthPbkdf2(args.password, args.pass_salt)
+      args.password = await this.hashForStorage(args.password, args.pass_salt)
     }
 
     const userId = await Mysql.execute(...Mysql.insert(`nt_user`, mapToDbColumn(args, userDbMap)))

lib/user/test.js

@@ -82,23 +82,31 @@ describe('user', function () {
       assert.equal(r, true)
     })
 
-    it('auths valid pbkdb2 password', async () => {
-      const r = await User.validPassword(
-        'YouGuessedIt!',
-        '050cfa70c3582be0d5bfae25138a8486dc2e6790f39bc0c4e111223ba6034432',
-        'unit-test',
-        '(ICzAm2.QfCa6.MN',
-      )
+    it('auths valid self-describing PBKDF2 password', async () => {
+      const salt = '(ICzAm2.QfCa6.MN'
+      const hash = await User.hashForStorage('YouGuessedIt!', salt)
+      const r = await User.validPassword('YouGuessedIt!', hash, 'unit-test', salt)
       assert.equal(r, true)
     })
 
-    it('rejects invalid pbkdb2 password', async () => {
-      const r = await User.validPassword(
-        'YouMissedIt!',
-        '050cfa70c3582be0d5bfae25138a8486dc2e6790f39bc0c4e111223ba6034432',
-        'unit-test',
-        '(ICzAm2.QfCa6.MN',
-      )
+    it('rejects invalid self-describing PBKDF2 password', async () => {
+      const salt = '(ICzAm2.QfCa6.MN'
+      const hash = await User.hashForStorage('YouGuessedIt!', salt)
+      const r = await User.validPassword('YouMissedIt!', hash, 'unit-test', salt)
+      assert.equal(r, false)
+    })
+
+    it('auths valid legacy PBKDF2-5000 password', async () => {
+      const salt = '(ICzAm2.QfCa6.MN'
+      const hash = await User.hashAuthPbkdf2('YouGuessedIt!', salt, 5000)
+      const r = await User.validPassword('YouGuessedIt!', hash, 'unit-test', salt)
+      assert.equal(r, true)
+    })
+
+    it('rejects invalid legacy PBKDF2-5000 password', async () => {
+      const salt = '(ICzAm2.QfCa6.MN'
+      const hash = await User.hashAuthPbkdf2('YouGuessedIt!', salt, 5000)
+      const r = await User.validPassword('YouMissedIt!', hash, 'unit-test', salt)
       assert.equal(r, false)
     })
 
@@ -188,7 +196,7 @@ describe('user', function () {
     before(cleanup)
     after(cleanup)
 
-    it('upgrades plain text password to PBKDF2 on login', async () => {
+    it('upgrades plain text password to self-describing PBKDF2 on login', async () => {
       await cleanup()
       await insertUser(testPass, null)
 
@@ -198,14 +206,15 @@ describe('user', function () {
       const row = await getDbPassword()
       assert.ok(row.pass_salt, 'pass_salt should be set after upgrade')
       assert.notEqual(row.password, testPass, 'password should be hashed')
+      assert.ok(row.password.includes('$'), 'password should be in self-describing format')
 
       // verify round-trip: can still log in with the upgraded hash
       const again = await User.authenticate(authCreds)
       assert.ok(again, 'login should succeed after upgrade')
       await cleanup()
     })
 
-    it('upgrades SHA1 password to PBKDF2 on login', async () => {
+    it('upgrades SHA1 password to self-describing PBKDF2 on login', async () => {
       // authenticate() passes the full authTry.username (including @group) to
       // validPassword(), so the HMAC key must match that full string
       const sha1Hash = crypto
@@ -221,13 +230,14 @@ describe('user', function () {
       const row = await getDbPassword()
       assert.ok(row.pass_salt, 'pass_salt should be set after upgrade')
       assert.notEqual(row.password, sha1Hash, 'password should be re-hashed')
+      assert.ok(row.password.includes('$'), 'password should be in self-describing format')
 
       const again = await User.authenticate(authCreds)
       assert.ok(again, 'login should succeed after upgrade')
       await cleanup()
     })
 
-    it('upgrades PBKDF2-5000 to current iterations on login', async () => {
+    it('upgrades PBKDF2-5000 to self-describing format on login', async () => {
       const legacySalt = User.generateSalt()
       const legacyHash = await User.hashAuthPbkdf2(testPass, legacySalt, 5000)
       await cleanup()
@@ -239,15 +249,16 @@ describe('user', function () {
       const row = await getDbPassword()
       assert.notEqual(row.password, legacyHash, 'password should be re-hashed')
       assert.notEqual(row.pass_salt, legacySalt, 'salt should be regenerated')
+      assert.ok(row.password.includes('$'), 'password should be in self-describing format')
 
       const again = await User.authenticate(authCreds)
       assert.ok(again, 'login should succeed after upgrade')
       await cleanup()
     })
 
-    it('does not re-hash password already at current iterations', async () => {
+    it('does not re-hash password already in self-describing format', async () => {
       const salt = User.generateSalt()
-      const hash = await User.hashAuthPbkdf2(testPass, salt)
+      const hash = await User.hashForStorage(testPass, salt)
       await cleanup()
       await insertUser(hash, salt)
 

lib/user/toml.js

@@ -86,7 +86,7 @@ class UserRepoTOML extends UserBase {
     args = JSON.parse(JSON.stringify(args))
     if (args.password) {
       if (!args.pass_salt) args.pass_salt = this.generateSalt()
-      args.password = await this.hashAuthPbkdf2(args.password, args.pass_salt)
+      args.password = await this.hashForStorage(args.password, args.pass_salt)
     }
 
     const users = await this._load()

lib/user/userBase.js

@@ -72,6 +72,11 @@ class UserBase {
     })
   }
 
+  async hashForStorage(pass, salt, iterations = PBKDF2_ITERATIONS) {
+    const hex = await this.hashAuthPbkdf2(pass, salt, iterations)
+    return `${iterations}$${hex}`
+  }
+
   async validPassword(passTry, passDb, username, salt) {
     this._needsUpgrade = false
 
@@ -81,10 +86,20 @@ class UserBase {
     }
 
     if (salt) {
-      const hashed = await this.hashAuthPbkdf2(passTry, salt)
-      if (this.debug) console.log(`hashed: (${hashed === passDb}) ${hashed}`)
-      if (hashed === passDb) return true
-      // fall back to NicTool 2 legacy iteration count
+      // Self-describing format: "iterations$hexHash" — single hash, no fallback
+      if (passDb.includes('$')) {
+        const [storedItersStr, storedHashHex] = passDb.split('$')
+        const storedIters = parseInt(storedItersStr, 10)
+        const hashed = await this.hashAuthPbkdf2(passTry, salt, storedIters)
+        if (this.debug) console.log(`self-describing: (${hashed === storedHashHex}) ${hashed}`)
+        if (hashed === storedHashHex) {
+          if (storedIters < PBKDF2_ITERATIONS) this._needsUpgrade = true
+          return true
+        }
+        return false
+      }
+
+      // Raw hex (legacy NicTool 2 format, implicitly 5000 iterations)
       const legacy = await this.hashAuthPbkdf2(passTry, salt, LEGACY_ITERATIONS)
       if (this.debug) console.log(`legacy: (${legacy === passDb}) ${legacy}`)
       if (legacy === passDb) {

routes/user.js

@@ -136,7 +136,7 @@ function UserRoutes(server) {
 
         if (args.password) {
           args.pass_salt = User.generateSalt()
-          args.password = await User.hashAuthPbkdf2(args.password, args.pass_salt)
+          args.password = await User.hashForStorage(args.password, args.pass_salt)
         }
 
         await User.put(args)