feat(password): reset user password with reset token

Author: adrienZ

README.md

@@ -163,6 +163,30 @@ Don't forget to re-login after verifying the email verification code.
 Registers a new user in the database if they don’t already exist. It handles OAuth authentication by registering the OAuth account, creating a session, and linking the user’s details.
 - **Returns**: A tuple containing the user ID and the created session details.
 
+##### `getSession(sessionId: string)`
+
+Fetches a session by its session ID.
+
+##### `deleteSession(sessionId: string)`
+
+Deletes a session by its session ID.
+
+##### `deleteExpiredSessions(timestamp: number)`
+
+Deletes sessions that have expired before the provided timestamp.
+
+#### `askPasswordReset(userId: string)`
+
+creates a reset password token for a specified user
+
+#### `askForgotPasswordReset(email: string)`
+
+Same as `askPasswordReset` but with email instead of userId.
+
+#### resetPasswordWithResetToken
+
+Resets the password using the reset token.
+
 ##### `setCreateRandomUserId(fn: () => string)`
 
 Sets a custom method for generating random user IDs.
@@ -179,17 +203,9 @@ Sets a custom method for generating random email verification codes.
 
 Sets custom methods for hashing and verifying passwords.
 
-##### `getSession(sessionId: string)`
-
-Fetches a session by its session ID.
-
-##### `deleteSession(sessionId: string)`
-
-Deletes a session by its session ID.
+##### `setCreateResetPasswordTokenHashMethod(fn: (tokenId: string) => Promise<string>)`
 
-##### `deleteExpiredSessions(timestamp: number)`
-
-Deletes sessions that have expired before the provided timestamp.
+Sets custom method for reset password token hashing.
 
 
 ## Hooks
@@ -204,6 +220,8 @@ The hooks property allows you to listen for and respond to events during the aut
 | **"sessions:create"**   | Triggered when a new session is created.    | (session: SlipAuthSession) => void          |
 | **"sessions:delete"**   | Triggered when a session is deleted.        | (session: SlipAuthSession) => void          |
 | **"emailVerificationCode:delete"**   | Triggered when a user email is validated.        | (code: SlipAuthEmailVerificationCode) => void          |
+| **"resetPasswordToken:create"**   | Triggered when a user passsword reset is asked.        | (token: SlipAuthPasswordResetToken) => void          |
+| **"resetPasswordToken:delete"**   | Triggered when a user passsword reset is validated or expired.        | (token: SlipAuthPasswordResetToken) => void          |
 
 ---
 
@@ -217,19 +235,20 @@ The hooks property allows you to listen for and respond to events during the aut
 - [x] Sqlite support
 - [x] Bun-sqlite support
 - [x] LibSQL support
+- [ ] PGlite support
 - [ ] Postgres support
 - [x] Email + Password
-  - [ ] forgot password
-  - [ ] reset password
+  - [x] forgot password
+  - [x] reset password
   - [ ] rate-limit login
   - [ ] rate-limit email verification
   - [ ] rate-limit forgot password
   - [ ] rate-limit reset password
   - [ ] rate limit register
 - [ ] error message strategy (email already taken, etc)
 - [ ] oauth accounts linking
-- [ ] Ihavebeenpwnd plugin
-- [ ] handle sub-adressing
+- [ ] ~~Ihavebeenpwnd plugin~~
+- [ ] handle sub-adressing (register spam)
 - [ ] MFA plugin
 - [ ] CSRF plugin
 - [ ] organization plugin

src/module.ts

@@ -21,6 +21,7 @@ export default defineNuxtModule<ModuleOptions>({
       users: "slip_auth_users",
       oauthAccounts: "slip_auth_oauth_accounts",
       emailVerificationCodes: "slip_auth_email_verification_codes",
+      resetPasswordTokens: "slip_auth_reset_password_tokens",
     },
   },
   async setup(options, nuxt) {

src/runtime/core/core.ts

@@ -1,17 +1,18 @@
 import { createChecker, type supportedConnectors } from "drizzle-schema-checker";
-import { getOAuthAccountsTableSchema, getSessionsTableSchema, getUsersTableSchema, getEmailVerificationCodesTableSchema } from "../database/lib/sqlite/schema.sqlite";
+import { getOAuthAccountsTableSchema, getSessionsTableSchema, getUsersTableSchema, getEmailVerificationCodesTableSchema, getPasswordResetTokensTableSchema } from "../database/lib/sqlite/schema.sqlite";
 import { drizzle as drizzleIntegration } from "db0/integrations/drizzle/index";
 import type { ICreateOrLoginParams, ICreateUserParams, ILoginUserParams, IPasswordHashingMethods, ISlipAuthCoreOptions, SchemasMockValue, SlipAuthUser, tableNames } from "./types";
 import { createSlipHooks } from "./hooks";
 import { UsersRepository } from "./repositories/UsersRepository";
 import { SessionsRepository } from "./repositories/SessionsRepository";
 import { OAuthAccountsRepository } from "./repositories/OAuthAccountsRepository";
 import { EmailVerificationCodesRepository } from "./repositories/EmailVerificationCodesRepository";
+import { ResetPasswordTokensRepository } from "./repositories/ResetPasswordTokensRepository";
 import type { SlipAuthPublicSession } from "../types";
-import { defaultIdGenerationMethod, isValidEmail, defaultEmailVerificationCodeGenerationMethod, defaultHashPasswordMethod, defaultVerifyPasswordMethod } from "./email-and-password-utils";
-import { InvalidEmailOrPasswordError, UnhandledError } from "./errors/SlipAuthError.js";
+import { defaultIdGenerationMethod, isValidEmail, defaultEmailVerificationCodeGenerationMethod, defaultHashPasswordMethod, defaultVerifyPasswordMethod, defaultResetPasswordTokenIdMethod, defaultResetPasswordTokenHashMethod } from "./email-and-password-utils";
+import { InvalidEmailOrPasswordError, InvalidEmailToResetPasswordError, InvalidPasswordToResetError, InvalidUserIdToResetPasswordError, ResetPasswordTokenExpiredError, UnhandledError } from "./errors/SlipAuthError.js";
 import type { Database } from "db0";
-import { isWithinExpirationDate } from "oslo";
+import { createDate, isWithinExpirationDate, TimeSpan } from "oslo";
 
 export class SlipAuthCore {
   readonly #db: Database;
@@ -23,11 +24,13 @@ export class SlipAuthCore {
     sessions: SessionsRepository
     oAuthAccounts: OAuthAccountsRepository
     emailVerificationCodes: EmailVerificationCodesRepository
+    resetPasswordTokens: ResetPasswordTokensRepository
   };
 
   #createRandomUserId: () => string;
   #createRandomSessionId: () => string;
   #createRandomEmailVerificationCode: () => string;
+  #createResetPasswordTokenHashMethod: (tokenId: string) => Promise<string>;
 
   #passwordHashingMethods: IPasswordHashingMethods;
 
@@ -50,19 +53,22 @@ export class SlipAuthCore {
       sessions: getSessionsTableSchema(tableNames),
       oauthAccounts: getOAuthAccountsTableSchema(tableNames),
       emailVerificationCodes: getEmailVerificationCodesTableSchema(tableNames),
+      resetPasswordTokens: getPasswordResetTokensTableSchema(tableNames),
     };
 
     this.#repos = {
       users: new UsersRepository(this.#orm, this.schemas, this.hooks, "users"),
       sessions: new SessionsRepository(this.#orm, this.schemas, this.hooks, "sessions"),
       oAuthAccounts: new OAuthAccountsRepository(this.#orm, this.schemas, this.hooks, "oauthAccounts"),
       emailVerificationCodes: new EmailVerificationCodesRepository(this.#orm, this.schemas, this.hooks, "emailVerificationCodes"),
+      resetPasswordTokens: new ResetPasswordTokensRepository(this.#orm, this.schemas, this.hooks, "resetPasswordTokens"),
     };
 
     this.#createRandomSessionId = defaultIdGenerationMethod;
     this.#createRandomUserId = defaultIdGenerationMethod;
 
     this.#createRandomEmailVerificationCode = defaultEmailVerificationCodeGenerationMethod;
+    this.#createResetPasswordTokenHashMethod = defaultResetPasswordTokenHashMethod;
 
     this.#passwordHashingMethods = {
       hash: defaultHashPasswordMethod,
@@ -87,7 +93,7 @@ export class SlipAuthCore {
       throw new InvalidEmailOrPasswordError("invalid email");
     }
     const password = values.password;
-    if (!password || typeof password !== "string" || password.length < 6) {
+    if (!password || typeof password !== "string") {
       throw new InvalidEmailOrPasswordError("invalid password");
     }
 
@@ -132,7 +138,7 @@ export class SlipAuthCore {
       throw new InvalidEmailOrPasswordError("invalid email");
     }
     const password = values.password;
-    if (!password || typeof password !== "string" || password.length < 6) {
+    if (!password || typeof password !== "string") {
       throw new InvalidEmailOrPasswordError("invalid password");
     }
 
@@ -154,7 +160,7 @@ export class SlipAuthCore {
     }
     catch (error) {
       if (error instanceof Error) {
-        if (error.stack?.startsWith(`SqliteError: UNIQUE constraint failed: ${this.#tableNames.users}.email`)) {
+        if (error.stack?.includes(`UNIQUE constraint failed: ${this.#tableNames.users}.email`)) {
           throw new InvalidEmailOrPasswordError(`email already taken: ${values.email}`);
         }
         throw new UnhandledError();
@@ -248,6 +254,78 @@ export class SlipAuthCore {
     return true;
   }
 
+  /**
+   * The token should be valid for at most few hours. The token should be hashed before storage as it essentially is a password.
+   * SHA-256 can be used here since the token is long and random, unlike user passwords.
+   */
+  public async askPasswordReset(userId: string) {
+    // optionally invalidate all existing tokens
+    // this.#repos.resetPasswordTokens.deleteAllByUserId(userId);
+    const tokenId = defaultResetPasswordTokenIdMethod();
+    const tokenHash = await this.#createResetPasswordTokenHashMethod(tokenId);
+    try {
+      await this.#repos.resetPasswordTokens.insert({
+        token_hash: tokenHash,
+        user_id: userId,
+        expires_at: createDate(new TimeSpan(2, "h")),
+      });
+
+      return tokenId;
+    }
+    catch (error) {
+      if (error instanceof Error && error.message.includes("FOREIGN KEY constraint failed")) {
+        throw new InvalidUserIdToResetPasswordError();
+      }
+
+      throw new UnhandledError();
+    }
+  }
+
+  // TODO: rate limit
+  public async askForgotPasswordReset(emailAddress: string): Promise<string> {
+    const user = await this.#repos.users.findByEmail(emailAddress);
+    if (!user) {
+      // If you want to avoid disclosing valid emails,
+      // this can be a normal 200 response.
+      throw new InvalidEmailToResetPasswordError();
+    }
+    return this.askPasswordReset(user.id);
+  }
+
+  /**
+   * Make sure to set the Referrer-Policy header of the password reset page to strict-origin to protect the token from referrer leakage.
+   * WARNING: WILL UN-LOG THE USER
+   */
+  public async resetPasswordWithResetToken(verificationToken: string, newPassword: string): Promise<true> {
+    if (typeof newPassword !== "string") {
+      throw new InvalidPasswordToResetError();
+    }
+
+    const tokenHash = await this.#createResetPasswordTokenHashMethod(verificationToken);
+    const token = await this.#repos.resetPasswordTokens.findByTokenHash(tokenHash);
+
+    if (!token) {
+      throw new ResetPasswordTokenExpiredError();
+    }
+
+    if (token) {
+      await this.#repos.resetPasswordTokens.deleteByTokenHash(tokenHash);
+    }
+
+    const expirationDate = token.expires_at instanceof Date ? token.expires_at : new Date(token.expires_at);
+    const offset = expirationDate.getTimezoneOffset() * 60000; // Get local time zone offset in milliseconds
+    const localExpirationDate = new Date(expirationDate.getTime() - offset); // Adjust for local time zone
+    if (!isWithinExpirationDate(localExpirationDate)) {
+      throw new ResetPasswordTokenExpiredError();
+    }
+
+    await this.#repos.sessions.deleteAllByUserId(token.user_id);
+    const passwordHash = await this.#passwordHashingMethods.hash(newPassword);
+    await this.#repos.users.updatePasswordByUserId(token.user_id, passwordHash);
+
+    return true;
+  }
+
   public setCreateRandomUserId(fn: () => string) {
     this.#createRandomUserId = fn;
   }
@@ -260,6 +338,10 @@ export class SlipAuthCore {
     this.#createRandomEmailVerificationCode = fn;
   }
 
+  public setCreateResetPasswordTokenHashMethod(fn: (tokenId: string) => Promise<string>) {
+    this.#createResetPasswordTokenHashMethod = fn;
+  }
+
   public setPasswordHashingMethods(fn: () => IPasswordHashingMethods) {
     const methods = fn();
     this.#passwordHashingMethods = methods;

src/runtime/core/email-and-password-utils.ts

@@ -1,6 +1,7 @@
-import { generateRandomString, alphabet } from "oslo/crypto";
+import { generateRandomString, alphabet, sha256 } from "oslo/crypto";
 import type { Options as ArgonOptions } from "@node-rs/argon2";
 import { hash, verify } from "@node-rs/argon2";
+import { encodeHex } from "oslo/encoding";
 
 /**
   https://thecopenhagenbook.com/email-verification#input-validation
@@ -22,6 +23,8 @@ export function isValidEmail(email: string): boolean {
 export const defaultIdGenerationMethod = () => generateRandomString(15, alphabet("a-z", "A-Z", "0-9"));
 
 export const defaultEmailVerificationCodeGenerationMethod = () => generateRandomString(6, alphabet("0-9", "A-Z"));
+export const defaultResetPasswordTokenIdMethod = () => generateRandomString(40, alphabet("0-9", "A-Z"));
+export const defaultResetPasswordTokenHashMethod = async (tokenId: string) => encodeHex(await sha256(new TextEncoder().encode(tokenId)));
 
 const hashOptions: ArgonOptions = {
   // recommended minimum parameters
@@ -31,7 +34,6 @@ const hashOptions: ArgonOptions = {
   parallelism: 1,
 };
 
-// https://thecopenhagenbook.com/password-authentication#argon2id
 export async function defaultHashPasswordMethod(rawPassword: string): Promise<string> {
   return await hash(rawPassword, hashOptions);
 };

src/runtime/core/errors/SlipAuthError.ts

@@ -22,3 +22,26 @@ export class InvalidEmailOrPasswordError extends SlipAuthError {
     this.#debugReason = reason;
   }
 }
+
+export class InvalidEmailToResetPasswordError extends SlipAuthError {
+  override name = "InvalidEmailToResetPasswordError";
+  override message = "InvalidEmailToResetPasswordError";
+  override slipError = SlipAuthErrorsCode.InvalidEmailToResetPassword;
+}
+
+export class InvalidUserIdToResetPasswordError extends SlipAuthError {
+  override name = "InvalidUserIdToResetPasswordError";
+  override message = "InvalidUserIdToResetPasswordError";
+  override slipError = SlipAuthErrorsCode.InvalidUserIdToResetPassword;
+}
+
+export class InvalidPasswordToResetError extends SlipAuthError {
+  override name = "InvalidPasswordToResetError";
+  override message = "InvalidPasswordToResetError";
+  override slipError = SlipAuthErrorsCode.InvalidPasswordToReset;
+}
+export class ResetPasswordTokenExpiredError extends SlipAuthError {
+  override name = "ResetPasswordTokenExpiredError";
+  override message = "ResetPasswordTokenExpiredError";
+  override slipError = SlipAuthErrorsCode.ResetPasswordTokenExpired;
+}

src/runtime/core/errors/SlipAuthErrorsCode.ts

@@ -1,4 +1,8 @@
 export enum SlipAuthErrorsCode {
   Unhandled = "Unhandled",
   InvalidEmailOrPassword = "InvalidEmailOrPassword",
+  InvalidEmailToResetPassword = "InvalidEmailToResetPassword",
+  InvalidUserIdToResetPassword = "InvalidUserIdToResetPassword",
+  InvalidPasswordToReset = "InvalidPasswordToReset",
+  ResetPasswordTokenExpired = "ResetPasswordTokenExpired",
 }

src/runtime/core/hooks.ts

@@ -1,5 +1,5 @@
 import { createHooks, type Hookable, type HookKeys } from "hookable";
-import type { SlipAuthSession, SlipAuthUser, SlipAuthOAuthAccount, SlipAuthEmailVerificationCode, EmailVerificationCodeTableInsert } from "./types";
+import type { SlipAuthSession, SlipAuthUser, SlipAuthOAuthAccount, SlipAuthEmailVerificationCode, EmailVerificationCodeTableInsert, SlipAuthPasswordResetToken } from "./types";
 
 interface ISlipAuthHooksMap {
   // users
@@ -12,6 +12,9 @@ interface ISlipAuthHooksMap {
   // emailVerificationCode
   "emailVerificationCode:create": (emailVerificationCodeValues: EmailVerificationCodeTableInsert) => void
   "emailVerificationCode:delete": (emailVerificationCode: SlipAuthEmailVerificationCode) => void
+  // resetPasswordToken
+  "resetPasswordToken:create": (resetPasswordToken: SlipAuthPasswordResetToken) => void
+  "resetPasswordToken:delete": (resetPasswordToken: SlipAuthPasswordResetToken) => void
 }
 
 export type ISlipAuthHooks = Hookable<ISlipAuthHooksMap, HookKeys<ISlipAuthHooksMap>>;