auth.ts

import jwt from "jsonwebtoken"
import crypto from "node:crypto"

export type AuthTokenPayload = {
	type: "access" | "refresh" | "password-reset"
	userId: string
}

export type AuthUser = {
	id: string
	email: string
	password: string
	verified?: boolean
}

export type AuthSession = {
	userId: string
	refreshTokenHash: string
	expiresAt: Date
	agent?: string
}

export type AuthAdapter<
	AuthAdditionalTokenPayload extends AdditionalAuthTokenPayloadGuardObject = undefined
> = {
	findUser: (
		data: Pick<AuthUser, "email">
	) => Promise<AuthUser | null | undefined>
	updateUser: (
		userId: string,
		data: Partial<Omit<AuthUser, "id">>
	) => Promise<void>
	createUser: (data: Pick<AuthUser, "email" | "password">) => Promise<AuthUser>

	findSession: (
		data: Pick<AuthSession, "refreshTokenHash">
	) => Promise<AuthSession | null | undefined>
	deleteSession: (
		data: Pick<AuthSession, "userId" | "refreshTokenHash">
	) => Promise<void>
	deleteSessions: (data: Pick<AuthSession, "userId">) => Promise<void>
	createSession: (data: AuthSession) => Promise<AuthSession>

	// Optional: validate the email address.
	// If not provided, the email will be validated using a regular expression.
	validateEmail?: (email: string) => Promise<boolean>

	// Optional: rate limit the login and register operations.
	isLoginRateLimited?: (data: {
		ip?: string
		email: string
	}) => Promise<boolean>
	isRegisterRateLimited?: (data: {
		ip?: string
		email: string
	}) => Promise<boolean>
} & (AuthAdditionalTokenPayload extends undefined // If the payload type is provided, the adapter must implement the enrichTokenPayload method.
	? {}
	: {
			enrichTokenPayload: (data: {
				userId: string
			}) => Promise<AuthAdditionalTokenPayload>
	  })

type AdditionalAuthTokenPayloadGuardObject =
	| (object & NeverKeys<AuthTokenPayload>)
	| undefined

// Simplify error handling by returning error as values.
// Functions return a tuple of [result, error].
type ResultTuple<Result, E extends string> = Promise<
	[Result, undefined] | [undefined, E]
>
type ResultTupleErrorExtractor<Fn extends (...args: any[]) => any> =
	Fn extends (...args: any[]) => Promise<[unknown, infer E]>
		? NonNullable<E>
		: never

// Utility type that maps all keys to never.
type NeverKeys<T> = {
	[K in keyof T]?: never
}

/**
 * This file does not require Prisma, but just for reference:
 * Prisma models
 *   |  model User {
 *   |    id           String        @id @default(cuid())
 *   |    email        String        @unique
 *   |    password     String
 *   |    verified     Boolean       @default(false)
 *   |    authSessions AuthSession[]
 *   |  }
 *   |
 *   |  model AuthSession {
 *   |    refreshTokenHash String   @id
 *   |    userId           String
 *   |    user             User     @relation(fields: [userId], references: [id])
 *   |    agent            String
 *   |    expiresAt        DateTime
 *   |    createdAt        DateTime @default(now())
 *   |    updatedAt        DateTime @updatedAt
 *   |  }
 *
 * Flow:
 *   1. User provides their email and password to register.
 *   2. If the user does not exist, a new user is created.
 *   3. A new session is created, including:
 *     - an access token (short-lived), used for authenticated requests
 *     - a refresh token (long-lived), used for refreshing the access token
 *  4. When the user forgets their password, a password reset token is generated and sent to the user's email.
 *     - the password reset token can only be used once to reset the password
 *     - once the password is reset, all the previous user sessions are invalidated
 **/
export class Auth<
	// Additional Auth Token Payload
	AdditionalAuthTokenPayload extends AdditionalAuthTokenPayloadGuardObject = undefined,
	// Combined Additional Token Payload
	CombinedAuthTokenPayload = AdditionalAuthTokenPayload extends undefined
		? AuthTokenPayload
		: AdditionalAuthTokenPayload & AuthTokenPayload
> {
	// The secret used to sign the JWT tokens
	private readonly jwtSecret: string

	// The expiration time for each type of token.
	// See constructor for defaults.
	private readonly refreshTokenExpiresInMs: number
	private readonly accessTokenExpiresInMs: number
	private readonly passwordResetTokenExpiresInMs: number

	// We use an adapter model
	private readonly adapter: AuthAdapter<AdditionalAuthTokenPayload>

	// Whether to log debug information.
	private readonly isDebugLoggingEnabled: boolean

	constructor(config: {
		jwtSecret: string
		refreshTokenExpiresInMs?: number
		accessTokenExpiresInMs?: number
		passwordResetTokenExpiresInMs?: number
		adapter: AuthAdapter<AdditionalAuthTokenPayload>
		isDebugLoggingEnabled?: boolean
	}) {
		this.jwtSecret = config.jwtSecret

		this.refreshTokenExpiresInMs =
			config.refreshTokenExpiresInMs || 14 * 24 * 60 * 60 * 1000 // default to 14 days
		this.accessTokenExpiresInMs =
			config.accessTokenExpiresInMs || 60 * 60 * 1000 // default to 1 hour
		this.passwordResetTokenExpiresInMs =
			config.passwordResetTokenExpiresInMs || 10 * 60 * 1000 // default to 10 minutes

		this.adapter = config.adapter

		this.isDebugLoggingEnabled = config.isDebugLoggingEnabled ?? false
	}

	/**
	 * Register a new user with the given email and password.
	 */
	async register({
		email,
		password,
		ip
	}: {
		email: string
		password: string
		ip?: string
	}): ResultTuple<
		{
			userId: string
			session: AuthSession
			accessToken: string
			refreshToken: string
		},
		| "INVALID_EMAIL"
		| "TOO_MANY_REQUESTS"
		| "USER_ALREADY_EXISTS"
		| "FAILED_TO_CREATE_SESSION"
		| ResultTupleErrorExtractor<typeof this.enrichTokenPayload>
	> {
		const DEBUG_TAG = "Register"

		this.logDebug("info", DEBUG_TAG, "Registering new user", { email })

		const [isEmailValid, maybeErrorCheckEmailValidity] =
			await this.checkEmailValidity(email)
		if (!isEmailValid || maybeErrorCheckEmailValidity) {
			return [undefined, maybeErrorCheckEmailValidity ?? "INVALID_EMAIL"]
		}

		if (this.adapter.isRegisterRateLimited) {
			const [isRateLimited, maybeErrorIsRateLimited] =
				await this.wrapPromiseToResultTuple(
					this.adapter.isRegisterRateLimited({ ip, email }),
					"TOO_MANY_REQUESTS"
				)
			if (isRateLimited || maybeErrorIsRateLimited) {
				this.logDebug("error", DEBUG_TAG, "Rate limited", { ip, email })
				return [undefined, maybeErrorIsRateLimited ?? "TOO_MANY_REQUESTS"]
			}
		}

		const [user, maybeErrorFindUser] = await this.wrapPromiseToResultTuple(
			this.adapter.findUser({ email }),
			"USER_ALREADY_EXISTS"
		)
		if (user || maybeErrorFindUser) {
			this.logDebug("error", DEBUG_TAG, `User "${email}" already exists`)
			return [undefined, maybeErrorFindUser ?? "USER_ALREADY_EXISTS"]
		}

		const hashedPassword = this.scrypt(password)

		const [newUser, maybeErrorCreateUser] = await this.wrapPromiseToResultTuple(
			this.adapter.createUser({ email, password: hashedPassword }),
			"USER_ALREADY_EXISTS"
		)
		if (!newUser || maybeErrorCreateUser) {
			this.logDebug("error", DEBUG_TAG, "Failed to create user", {
				email,
				error: maybeErrorCreateUser
			})
			return [undefined, maybeErrorCreateUser ?? "USER_ALREADY_EXISTS"]
		}

		const userId = newUser.id

		const [enrichedPayload, enrichedPayloadError] =
			await this.enrichTokenPayload({ userId })
		if (enrichedPayloadError) {
			return [undefined, enrichedPayloadError]
		}

		const refreshToken = this.generateRefreshToken({
			...enrichedPayload,
			userId
		} as CombinedAuthTokenPayload)
		const accessToken = this.generateAccessToken({
			...enrichedPayload,
			userId
		} as CombinedAuthTokenPayload)

		const refreshTokenHash = this.sha256(refreshToken)
		const expiresAt = new Date(Date.now() + this.refreshTokenExpiresInMs)

		const [session, maybeErrorCreateSession] =
			await this.wrapPromiseToResultTuple(
				this.adapter.createSession({
					userId,
					refreshTokenHash,
					expiresAt
				}),
				"FAILED_TO_CREATE_SESSION"
			)
		if (!session || maybeErrorCreateSession) {
			this.logDebug("error", DEBUG_TAG, "Failed to create session", {
				userId,
				error: maybeErrorCreateSession
			})
			return [undefined, maybeErrorCreateSession ?? "FAILED_TO_CREATE_SESSION"]
		}

		this.logDebug("info", DEBUG_TAG, "User registered successfully", { userId })

		return [{ userId, session, accessToken, refreshToken }, undefined]
	}

	/**
	 * Sign in a user with the given email and password.
	 */
	async login({
		email,
		password,
		ip
	}: {
		email: string
		password: string
		ip?: string
	}): ResultTuple<
		{
			userId: string
			session: AuthSession
			accessToken: string
			refreshToken: string
		},
		| "INVALID_EMAIL"
		| "TOO_MANY_REQUESTS"
		| "INVALID_CREDENTIALS"
		| "FAILED_TO_CREATE_SESSION"
		| ResultTupleErrorExtractor<typeof this.verifyPassword>
		| ResultTupleErrorExtractor<typeof this.enrichTokenPayload>
	> {
		const DEBUG_TAG = "Login"

		this.logDebug("info", DEBUG_TAG, "Logging in user", { email })

		const [isEmailValid, maybeErrorCheckEmailValidity] =
			await this.checkEmailValidity(email)
		if (!isEmailValid || maybeErrorCheckEmailValidity) {
			return [undefined, maybeErrorCheckEmailValidity ?? "INVALID_CREDENTIALS"]
		}

		if (this.adapter.isLoginRateLimited) {
			const [isRateLimited, maybeErrorIsRateLimited] =
				await this.wrapPromiseToResultTuple(
					this.adapter.isLoginRateLimited({ ip, email }),
					"TOO_MANY_REQUESTS"
				)
			if (isRateLimited || maybeErrorIsRateLimited) {
				this.logDebug("error", DEBUG_TAG, "Rate limited", { ip, email })
				return [undefined, maybeErrorIsRateLimited ?? "TOO_MANY_REQUESTS"]
			}
		}

		const [user, maybeErrorFindUser] = await this.wrapPromiseToResultTuple(
			this.adapter.findUser({ email }),
			"INVALID_CREDENTIALS"
		)
		if (!user || maybeErrorFindUser) {
			this.logDebug("error", DEBUG_TAG, `User "${email}" not found`)
			return [undefined, maybeErrorFindUser ?? "INVALID_CREDENTIALS"]
		}

		const [isPasswordValid, maybeErrorVerifyPassword] =
			await this.verifyPassword(password, user.password)
		if (!isPasswordValid || maybeErrorVerifyPassword) {
			return [undefined, maybeErrorVerifyPassword ?? "INVALID_CREDENTIALS"]
		}

		const userId = user.id

		const [enrichedPayload, enrichedPayloadError] =
			await this.enrichTokenPayload({ userId })
		if (enrichedPayloadError) {
			return [undefined, enrichedPayloadError]
		}

		const refreshToken = this.generateRefreshToken({
			...enrichedPayload,
			userId
		} as CombinedAuthTokenPayload)
		const accessToken = this.generateAccessToken({
			...enrichedPayload,
			userId
		} as CombinedAuthTokenPayload)

		const [session, maybeErrorCreateSession] =
			await this.wrapPromiseToResultTuple(
				this.adapter.createSession({
					userId,
					refreshTokenHash: this.sha256(refreshToken),
					expiresAt: new Date(Date.now() + this.refreshTokenExpiresInMs)
				}),
				"FAILED_TO_CREATE_SESSION"
			)
		if (!session || maybeErrorCreateSession) {
			this.logDebug("error", DEBUG_TAG, "Failed to create session", {
				userId,
				error: maybeErrorCreateSession
			})
			return [undefined, maybeErrorCreateSession ?? "FAILED_TO_CREATE_SESSION"]
		}

		this.logDebug("info", DEBUG_TAG, "User logged in successfully", { userId })

		return [{ userId, session, accessToken, refreshToken }, undefined]
	}

	/**
	 * Get a password reset token for the user.
	 * Make sure to always return the same API response to avoid leaking information:
	 *  - an attacker might be able to check if an email address exists in the database.
	 */
	async forgotPassword({
		email
	}: {
		email: string
	}): ResultTuple<
		{ passwordResetToken: string },
		| "INVALID_EMAIL"
		| "USER_NOT_FOUND"
		| ResultTupleErrorExtractor<typeof this.enrichTokenPayload>
	> {
		const DEBUG_TAG = "ForgotPassword"

		this.logDebug("info", DEBUG_TAG, "Forgot password")

		const [isEmailValid, maybeErrorCheckEmailValidity] =
			await this.checkEmailValidity(email)
		if (!isEmailValid || maybeErrorCheckEmailValidity) {
			return [undefined, maybeErrorCheckEmailValidity ?? "INVALID_EMAIL"]
		}

		const [user, maybeErrorFindUser] = await this.wrapPromiseToResultTuple(
			this.adapter.findUser({ email }),
			"USER_NOT_FOUND"
		)
		if (!user || maybeErrorFindUser) {
			this.logDebug("error", DEBUG_TAG, `User "${email}" not found`)
			return [undefined, maybeErrorFindUser ?? "USER_NOT_FOUND"]
		}

		const [enrichedPayload, enrichedPayloadError] =
			await this.enrichTokenPayload({ userId: user.id })
		if (enrichedPayloadError) {
			return [undefined, enrichedPayloadError]
		}

		const passwordResetToken = this.generatePasswordResetToken({
			...enrichedPayload,
			userId: user.id
		} as CombinedAuthTokenPayload)

		this.logDebug(
			"info",
			DEBUG_TAG,
			"Password reset token generated successfully",
			{ userId: user.id }
		)

		return [{ passwordResetToken }, undefined]
	}

	/**
	 * Reset the password for the user.
	 * Requires the password reset token generated by the `forgotPassword` method.
	 */
	async resetPassword({
		passwordResetToken,
		newPassword,
		closePreviousSessions = true
	}: {
		passwordResetToken: string
		newPassword: string
		closePreviousSessions?: boolean
	}): ResultTuple<
		undefined,
		| "FAILED_TO_UPDATE_USER"
		| "FAILED_TO_DELETE_SESSIONS"
		| ResultTupleErrorExtractor<typeof this.getTokenPayload>
	> {
		const DEBUG_TAG = "ResetPassword"

		this.logDebug("info", DEBUG_TAG, "Resetting password")

		const [tokenPayload, errorTokenPayload] = await this.getTokenPayload(
			passwordResetToken,
			"password-reset"
		)
		if (errorTokenPayload) {
			return [undefined, errorTokenPayload]
		}

		const userId = tokenPayload?.["userId"]
		if (!userId) {
			this.logDebug("error", DEBUG_TAG, "Invalid token (no user ID)")
			return [undefined, "INVALID_TOKEN"]
		}

		const [, maybeErrorUpdateUser] = await this.wrapPromiseToResultTuple(
			this.adapter.updateUser(userId, {
				password: this.scrypt(newPassword)
			}),
			"FAILED_TO_UPDATE_USER"
		)
		if (maybeErrorUpdateUser) {
			this.logDebug("error", DEBUG_TAG, "Failed to update password", {
				userId,
				error: maybeErrorUpdateUser
			})
		} else {
			this.logDebug("info", DEBUG_TAG, "Password updated successfully", {
				userId
			})
		}

		if (closePreviousSessions) {
			const [, maybeErrorDeleteSessions] = await this.wrapPromiseToResultTuple(
				this.adapter.deleteSessions({ userId }),
				"FAILED_TO_DELETE_SESSIONS"
			)
			if (maybeErrorDeleteSessions) {
				this.logDebug("error", DEBUG_TAG, "Failed to close previous sessions", {
					userId,
					error: maybeErrorDeleteSessions
				})
			} else {
				this.logDebug(
					"info",
					DEBUG_TAG,
					"Previous sessions closed successfully",
					{ userId }
				)
			}
		}

		return [undefined, undefined]
	}

	/**
	 * Logout the user.
	 *
	 * `refreshToken` is required to make sure the operation is done by the owner of the session.
	 * `refreshTokenHash` is optional to allow the client to logout from a specific session. If not provided, the current session will be closed.
	 */
	async closeSession({
		refreshToken,
		refreshTokenHash
	}: {
		refreshToken: string
		refreshTokenHash?: string
	}): ResultTuple<
		void,
		"SESSION_NOT_FOUND" | ResultTupleErrorExtractor<typeof this.getTokenPayload>
	> {
		const DEBUG_TAG = "CloseSession"

		this.logDebug("info", DEBUG_TAG, "Closing session")

		const [tokenPayload, errorTokenPayload] = await this.getTokenPayload(
			refreshToken,
			"refresh"
		)
		if (errorTokenPayload) {
			return [undefined, errorTokenPayload]
		}

		const userId = tokenPayload?.["userId"]
		if (!userId) {
			return [undefined, "INVALID_TOKEN"]
		}

		const actualRefreshTokenHash = refreshTokenHash ?? this.sha256(refreshToken)

		const [, maybeErrorDeleteSession] = await this.wrapPromiseToResultTuple(
			this.adapter.deleteSession({
				refreshTokenHash: actualRefreshTokenHash,
				userId
			}),
			"SESSION_NOT_FOUND"
		)
		if (maybeErrorDeleteSession) {
			return [undefined, maybeErrorDeleteSession]
		}

		this.logDebug("info", DEBUG_TAG, "Session closed successfully", {
			userId
		})

		return [undefined, undefined]
	}

	/**
	 * Since access tokens are short-lived, they need to be refreshed before they expire.
	 */
	async refreshAccessToken({
		refreshToken
	}: {
		refreshToken: string
	}): ResultTuple<
		{ accessToken: string },
		| "SESSION_NOT_FOUND"
		| "SESSION_EXPIRED"
		| ResultTupleErrorExtractor<typeof this.getTokenPayload>
		| ResultTupleErrorExtractor<typeof this.enrichTokenPayload>
	> {
		const DEBUG_TAG = "RefreshAccessToken"

		this.logDebug("info", DEBUG_TAG, "Refreshing access token")

		const [tokenPayload, errorTokenPayload] = await this.getTokenPayload(
			refreshToken,
			"refresh"
		)
		if (errorTokenPayload) {
			return [undefined, errorTokenPayload]
		}

		const userId = tokenPayload?.["userId"]
		if (!userId) {
			return [undefined, "INVALID_TOKEN"]
		}

		const refreshTokenHash = this.sha256(refreshToken)

		const [session, maybeErrorSession] = await this.wrapPromiseToResultTuple(
			this.adapter.findSession({ refreshTokenHash }),
			"SESSION_NOT_FOUND"
		)
		if (!session || maybeErrorSession) {
			this.logDebug(
				"error",
				DEBUG_TAG,
				"Session doesn't exist or is blacklisted"
			)
			return [undefined, maybeErrorSession ?? "SESSION_NOT_FOUND"]
		}

		// Should never happen since the expiration is handled when decoding the token.
		// Check the expiration here as well in case the expiration has been changed in the database
		if (session.expiresAt < new Date()) {
			this.logDebug("error", DEBUG_TAG, "Session expired")
			return [undefined, "SESSION_EXPIRED"]
		}

		const [enrichedPayload, enrichedPayloadError] =
			await this.enrichTokenPayload({ userId })
		if (enrichedPayloadError) {
			return [undefined, enrichedPayloadError]
		}

		const accessToken = this.generateAccessToken({
			...enrichedPayload,
			userId
		} as CombinedAuthTokenPayload)

		this.logDebug("info", DEBUG_TAG, "Access token refreshed successfully", {
			userId
		})

		return [{ accessToken }, undefined]
	}

	generateRefreshToken(
		payload: Omit<CombinedAuthTokenPayload, "type">
	): string {
		const expiresInSeconds = Math.floor(this.refreshTokenExpiresInMs / 1000)

		return jwt.sign({ ...payload, type: "refresh" }, this.jwtSecret, {
			expiresIn: expiresInSeconds
		})
	}

	generateAccessToken(payload: Omit<CombinedAuthTokenPayload, "type">): string {
		const expiresInSeconds = Math.floor(this.accessTokenExpiresInMs / 1000)

		return jwt.sign({ ...payload, type: "access" }, this.jwtSecret, {
			expiresIn: expiresInSeconds
		})
	}

	generatePasswordResetToken(
		payload: Omit<CombinedAuthTokenPayload, "type">
	): string {
		const expiresInSeconds = Math.floor(
			this.passwordResetTokenExpiresInMs / 1000
		)

		return jwt.sign({ ...payload, type: "password-reset" }, this.jwtSecret, {
			expiresIn: expiresInSeconds
		})
	}

	async getTokenPayload(
		token: string,
		typeOrTypes: AuthTokenPayload["type"] | Array<AuthTokenPayload["type"]>
	): ResultTuple<
		CombinedAuthTokenPayload,
		"INVALID_TOKEN" | "INVALID_TOKEN_TYPE"
	> {
		let tokenPayload: CombinedAuthTokenPayload
		try {
			tokenPayload = jwt.verify(
				token,
				this.jwtSecret
			) as CombinedAuthTokenPayload
		} catch {
			return [undefined, "INVALID_TOKEN"]
		}

		const tokenPayloadType = tokenPayload?.["type"]
		if (!tokenPayloadType) {
			return [undefined, "INVALID_TOKEN"]
		}

		if (Array.isArray(typeOrTypes)) {
			const types = typeOrTypes
			if (!types.includes(tokenPayloadType)) {
				return [undefined, "INVALID_TOKEN_TYPE"]
			}
		} else {
			const type = typeOrTypes
			if (tokenPayloadType !== type) {
				return [undefined, "INVALID_TOKEN_TYPE"]
			}
		}

		return [tokenPayload, undefined]
	}

	private async enrichTokenPayload<
		O = AdditionalAuthTokenPayload extends undefined
			? undefined
			: AdditionalAuthTokenPayload
	>(payload: {
		userId: string
	}): ResultTuple<O, "FAILED_TO_ENRICH_TOKEN_PAYLOAD"> {
		const DEBUG_TAG = "EnrichTokenPayload"

		if (!("enrichTokenPayload" in this.adapter)) {
			return [undefined as O, undefined]
		}

		const [enrichedPayload, errorEnrichTokenPayload] =
			await this.wrapPromiseToResultTuple(
				this.adapter.enrichTokenPayload({ userId: payload.userId }),
				"FAILED_TO_ENRICH_TOKEN_PAYLOAD"
			)
		if (errorEnrichTokenPayload) {
			this.logDebug("error", DEBUG_TAG, "Failed to enrich token payload", {
				userId: payload.userId,
				error: errorEnrichTokenPayload
			})
			return [undefined, errorEnrichTokenPayload]
		}

		// Make sure the basic token payload fields don't get overridden by the enriched payload.
		delete enrichedPayload?.["type"]
		delete enrichedPayload?.["userId"]

		return [enrichedPayload as O, undefined]
	}

	private async checkEmailValidity(
		email: string
	): ResultTuple<boolean, "INVALID_EMAIL"> {
		const DEBUG_TAG = "CheckEmailValidity"

		if (this.adapter.validateEmail) {
			const [isValid, maybeError] = await this.wrapPromiseToResultTuple(
				this.adapter.validateEmail(email),
				"INVALID_EMAIL"
			)
			if (!isValid || maybeError) {
				this.logDebug("error", DEBUG_TAG, "Invalid email", {
					email,
					error: maybeError
				})
				return [undefined, maybeError ?? "INVALID_EMAIL"]
			}
		}

		const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
		const isValid = emailRegex.test(email)

		if (!isValid) {
			this.logDebug("error", DEBUG_TAG, "Invalid email format")
			return [undefined, "INVALID_EMAIL"]
		}

		return [true, undefined]
	}

	// For token hashing
	private sha256(input: string): string {
		return crypto.createHash("sha256").update(input).digest("hex")
	}

	// For password hashing
	private scrypt(input: string): string {
		const salt = crypto.randomBytes(16).toString("hex")

		const hash = crypto.scryptSync(input, salt, 64).toString("hex")

		// store: algorithm + salt + hash
		return `scrypt$${salt}$${hash}`
	}

	// Compare password hashes in a secure way.
	private async verifyPassword(
		password: string,
		hashedPassword: string
	): ResultTuple<boolean, "INVALID_PASSWORD"> {
		const DEBUG_TAG = "VerifyPassword"

		const parts = hashedPassword.split("$")
		if (parts.length !== 3 || parts[0] !== "scrypt") {
			this.logDebug("error", DEBUG_TAG, "Invalid password format")
			return [undefined, "INVALID_PASSWORD"]
		}

		const [, salt, originalHash] = parts
		if (
			!salt ||
			!originalHash ||
			!/^[0-9a-f]+$/i.test(salt) ||
			!/^[0-9a-f]+$/i.test(originalHash)
		) {
			this.logDebug("error", DEBUG_TAG, "Invalid password")
			return [undefined, "INVALID_PASSWORD"]
		}

		try {
			const hash = crypto.scryptSync(password, salt, 64).toString("hex")
			const hashBuf = Buffer.from(hash, "hex")
			const originalBuf = Buffer.from(originalHash, "hex")

			if (hashBuf.length !== originalBuf.length) {
				this.logDebug("error", DEBUG_TAG, "Invalid password hash length")
				return [undefined, "INVALID_PASSWORD"]
			}

			return [crypto.timingSafeEqual(hashBuf, originalBuf), undefined]
		} catch (error) {
			this.logDebug("error", DEBUG_TAG, "Invalid password hash", { error })
			return [undefined, "INVALID_PASSWORD"]
		}
	}

	// Log debug information if debugging is enabled.
	private logDebug(
		level: "info" | "error",
		tag: string,
		...args: unknown[]
	): void {
		if (!this.isDebugLoggingEnabled) {
			return
		}

		console[level](`[${tag}]`, ...args)
	}

	// Tiny helper to wrap a promise to return a ResultTuple.
	private async wrapPromiseToResultTuple<R, E extends string>(
		promise: Promise<R>,
		error: E
	): ResultTuple<R, E> {
		try {
			const result = await promise
			return [result, undefined]
		} catch (e) {
			return [undefined, error]
		}
	}
}