feat: Add utility for checking outdated password hashes during login flow (#471)

Co-authored-by: Sébastien Chopin <seb@nuxt.com>
Co-authored-by: Sébastien Chopin <atinux@gmail.com>

Author: gapple

README.md

@@ -299,6 +299,17 @@ if (await verifyPassword(hashedPassword, 'user_password')) {
 }
 ```
 
+It also provides a `passwordNeedsRehash` function to check if a password needs to be rehashed. This is useful when the hash settings are changed, such as as increasing the scrypt cost parameters.
+
+```ts
+const needsRehash = await passwordNeedsRehash(hashedPassword)
+
+if (needsRehash) {
+  // Password needs to be rehashed
+  hashedPassword = await hashPassword('user_password')
+}
+```
+
 You can configure the scrypt options in your `nuxt.config.ts`:
 
 ```ts

playground/server/api/login.post.ts

@@ -30,6 +30,10 @@ export default defineEventHandler(async (event) => {
     throw invalidCredentialsError
   }
 
+  if (passwordNeedsReHash(password)) {
+    await db.sql`UPDATE users SET password = ${hashPassword(password)} WHERE id = ${user.id}`
+  }
+
   await setUserSession(event, {
     user: {
       email,

src/runtime/server/utils/password.ts

@@ -42,3 +42,23 @@ export async function hashPassword(password: string) {
 export async function verifyPassword(hashedPassword: string, plainPassword: string) {
   return await getHash().verify(hashedPassword, plainPassword)
 }
+
+/**
+ * Check if the hash value needs a rehash or not. The rehash is required if
+ * configuration settings have changed.
+ * @param hashedPassword - The hashed password to check
+ * @returns `true` if a rehash is needed, `false` otherwise
+ * @example
+ * ```ts
+ * const isValid = await verifyPassword(hashedPassword, plainText)
+ *
+ * // Plain password is valid, and hash needs a rehash
+ * if (isValid && passwordNeedsReHash(hashedPassword)) {
+ *   const newHash = await hashPassword(plainText)
+ * }
+ * ```
+ * @more you can configure the scrypt options in `auth.hash.scrypt`
+ */
+export function passwordNeedsReHash(hashedPassword: string) {
+  return getHash().needsReHash(hashedPassword)
+}