@masheev/better-auth 0.0.0-stage → 1.7.5

package/dist/plugins/two-factor/backup-codes/index.mjs

@@ -0,0 +1,341 @@
+import { parseUserOutput } from "../../../db/schema.mjs";
+import { generateRandomString } from "../../../crypto/random.mjs";
+import { symmetricDecrypt, symmetricEncrypt } from "../../../crypto/index.mjs";
+import { sessionMiddleware } from "../../../api/routes/session.mjs";
+import { shouldRequirePassword } from "../../../utils/password.mjs";
+import { PACKAGE_VERSION } from "../../../version.mjs";
+import { TWO_FACTOR_ERROR_CODES } from "../error-code.mjs";
+import { assertTwoFactorNotLocked, recordTwoFactorFailure, resetTwoFactorFailures, verifyTwoFactor } from "../verify-two-factor.mjs";
+import { APIError, BASE_ERROR_CODES } from "@better-auth/core/error";
+import { safeJSONParse } from "@better-auth/core/utils/json";
+import { createAuthEndpoint } from "@better-auth/core/api";
+import * as z from "zod";
+//#region src/plugins/two-factor/backup-codes/index.ts
+function generateBackupCodesFn(options) {
+	return Array.from({ length: options?.amount ?? 10 }).fill(null).map(() => generateRandomString(options?.length ?? 10, "a-z", "0-9", "A-Z")).map((code) => `${code.slice(0, 5)}-${code.slice(5)}`);
+}
+async function encodeBackupCodes(codes, secret, options) {
+	const json = JSON.stringify(codes);
+	if (options?.storeBackupCodes === "encrypted") return symmetricEncrypt({
+		data: json,
+		key: secret
+	});
+	if (typeof options?.storeBackupCodes === "object" && "encrypt" in options?.storeBackupCodes) return options.storeBackupCodes.encrypt(json);
+	return json;
+}
+async function generateBackupCodes(secret, options) {
+	const backupCodes = options?.customBackupCodesGenerate ? options.customBackupCodesGenerate() : generateBackupCodesFn(options);
+	return {
+		backupCodes,
+		encryptedBackupCodes: await encodeBackupCodes(backupCodes, secret, options)
+	};
+}
+async function verifyBackupCode(data, key, options) {
+	const codes = await getBackupCodes(data.backupCodes, key, options);
+	if (!codes) return {
+		status: false,
+		updated: null
+	};
+	return {
+		status: codes.includes(data.code),
+		updated: codes.filter((code) => code !== data.code)
+	};
+}
+async function getBackupCodes(backupCodes, key, options) {
+	if (options?.storeBackupCodes === "encrypted") return safeJSONParse(await symmetricDecrypt({
+		key,
+		data: backupCodes
+	}));
+	if (typeof options?.storeBackupCodes === "object" && "decrypt" in options?.storeBackupCodes) return safeJSONParse(await options?.storeBackupCodes.decrypt(backupCodes));
+	return safeJSONParse(backupCodes);
+}
+const verifyBackupCodeBodySchema = z.object({
+	code: z.string().meta({ description: `A backup code to verify. Eg: "123456"` }),
+	/**
+	* Disable setting the session cookie
+	*/
+	disableSession: z.boolean().meta({ description: "If true, the session cookie will not be set." }).optional(),
+	/**
+	* if true, the device will be trusted
+	* for 30 days. It'll be refreshed on
+	* every sign in request within this time.
+	*/
+	trustDevice: z.boolean().meta({ description: "If true, the device will be trusted for 30 days. It'll be refreshed on every sign in request within this time. Eg: true" }).optional()
+});
+const viewBackupCodesBodySchema = z.object({ userId: z.coerce.string().meta({ description: `The user ID to view all backup codes. Eg: "user-id"` }) });
+const backupCode2fa = (opts) => {
+	const twoFactorTable = "twoFactor";
+	const passwordSchema = z.string().meta({ description: "The users password." });
+	const generateBackupCodesBodySchema = opts.allowPasswordless ? z.object({ password: passwordSchema.optional() }) : z.object({ password: passwordSchema });
+	return {
+		id: "backup_code",
+		version: PACKAGE_VERSION,
+		endpoints: {
+			/**
+			* ### Endpoint
+			*
+			* POST `/two-factor/verify-backup-code`
+			*
+			* ### API Methods
+			*
+			* **server:**
+			* `auth.api.verifyBackupCode`
+			*
+			* **client:**
+			* `authClient.twoFactor.verifyBackupCode`
+			*
+			* @see [Read our docs to learn more.](https://better-auth.com/docs/plugins/2fa#api-method-two-factor-verify-backup-code)
+			*/
+			verifyBackupCode: createAuthEndpoint("/two-factor/verify-backup-code", {
+				method: "POST",
+				body: verifyBackupCodeBodySchema,
+				metadata: { openapi: {
+					description: "Verify a backup code for two-factor authentication",
+					responses: { "200": {
+						description: "Backup code verified successfully",
+						content: { "application/json": { schema: {
+							type: "object",
+							properties: {
+								user: {
+									type: "object",
+									properties: {
+										id: {
+											type: "string",
+											description: "Unique identifier of the user"
+										},
+										email: {
+											type: "string",
+											format: "email",
+											nullable: true,
+											description: "User's email address"
+										},
+										emailVerified: {
+											type: "boolean",
+											nullable: true,
+											description: "Whether the email is verified"
+										},
+										name: {
+											type: "string",
+											nullable: true,
+											description: "User's name"
+										},
+										image: {
+											type: "string",
+											format: "uri",
+											nullable: true,
+											description: "User's profile image URL"
+										},
+										twoFactorEnabled: {
+											type: "boolean",
+											description: "Whether two-factor authentication is enabled for the user"
+										},
+										createdAt: {
+											type: "string",
+											format: "date-time",
+											description: "Timestamp when the user was created"
+										},
+										updatedAt: {
+											type: "string",
+											format: "date-time",
+											description: "Timestamp when the user was last updated"
+										}
+									},
+									required: [
+										"id",
+										"twoFactorEnabled",
+										"createdAt",
+										"updatedAt"
+									],
+									description: "The authenticated user object with two-factor details"
+								},
+								session: {
+									type: "object",
+									properties: {
+										token: {
+											type: "string",
+											description: "Session token"
+										},
+										userId: {
+											type: "string",
+											description: "ID of the user associated with the session"
+										},
+										createdAt: {
+											type: "string",
+											format: "date-time",
+											description: "Timestamp when the session was created"
+										},
+										expiresAt: {
+											type: "string",
+											format: "date-time",
+											description: "Timestamp when the session expires"
+										}
+									},
+									required: [
+										"token",
+										"userId",
+										"createdAt",
+										"expiresAt"
+									],
+									description: "The current session object, included unless disableSession is true"
+								}
+							},
+							required: ["user", "session"]
+						} } }
+					} }
+				} }
+			}, async (ctx) => {
+				const { session, valid, beginAttempt } = await verifyTwoFactor(ctx);
+				const user = session.user;
+				const isSignIn = !session.session;
+				const twoFactor = await ctx.context.adapter.findOne({
+					model: twoFactorTable,
+					where: [{
+						field: "userId",
+						value: user.id
+					}]
+				});
+				if (!twoFactor) throw APIError.from("BAD_REQUEST", TWO_FACTOR_ERROR_CODES.BACKUP_CODES_NOT_ENABLED);
+				if (isSignIn) await assertTwoFactorNotLocked(ctx, twoFactorTable, twoFactor);
+				const attempt = isSignIn ? await beginAttempt(5) : null;
+				let validate;
+				try {
+					validate = await verifyBackupCode({
+						backupCodes: twoFactor.backupCodes,
+						code: ctx.body.code
+					}, ctx.context.secretConfig, opts);
+				} catch (error) {
+					await attempt?.restore();
+					throw error;
+				}
+				if (!validate.status || !validate.updated) {
+					await attempt?.recordFailure();
+					if (isSignIn) await recordTwoFactorFailure(ctx, twoFactorTable, twoFactor);
+					throw APIError.from("UNAUTHORIZED", TWO_FACTOR_ERROR_CODES.INVALID_BACKUP_CODE);
+				}
+				const updatedBackupCodes = await encodeBackupCodes(validate.updated, ctx.context.secretConfig, opts);
+				if (!await ctx.context.adapter.incrementOne({
+					model: twoFactorTable,
+					where: [{
+						field: "id",
+						value: twoFactor.id
+					}, {
+						field: "backupCodes",
+						value: twoFactor.backupCodes
+					}],
+					increment: {},
+					set: { backupCodes: updatedBackupCodes }
+				})) throw APIError.fromStatus("CONFLICT", { message: "Failed to verify backup code. Please try again." });
+				if (isSignIn) await resetTwoFactorFailures(ctx, twoFactorTable, twoFactor);
+				if (!ctx.body.disableSession) return valid(ctx);
+				return ctx.json({
+					token: session.session?.token,
+					user: parseUserOutput(ctx.context.options, session.user)
+				});
+			}),
+			/**
+			* ### Endpoint
+			*
+			* POST `/two-factor/generate-backup-codes`
+			*
+			* ### API Methods
+			*
+			* **server:**
+			* `auth.api.generateBackupCodes`
+			*
+			* **client:**
+			* `authClient.twoFactor.generateBackupCodes`
+			*
+			* @see [Read our docs to learn more.](https://better-auth.com/docs/plugins/2fa#api-method-two-factor-generate-backup-codes)
+			*/
+			generateBackupCodes: createAuthEndpoint("/two-factor/generate-backup-codes", {
+				method: "POST",
+				body: generateBackupCodesBodySchema,
+				use: [sessionMiddleware],
+				metadata: { openapi: {
+					description: "Generate new backup codes for two-factor authentication",
+					responses: { "200": {
+						description: "Backup codes generated successfully",
+						content: { "application/json": { schema: {
+							type: "object",
+							properties: {
+								status: {
+									type: "boolean",
+									description: "Indicates if the backup codes were generated successfully",
+									enum: [true]
+								},
+								backupCodes: {
+									type: "array",
+									items: { type: "string" },
+									description: "Array of generated backup codes in plain text"
+								}
+							},
+							required: ["status", "backupCodes"]
+						} } }
+					} }
+				} }
+			}, async (ctx) => {
+				const user = ctx.context.session.user;
+				if (!user.twoFactorEnabled) throw APIError.from("BAD_REQUEST", TWO_FACTOR_ERROR_CODES.TWO_FACTOR_NOT_ENABLED);
+				if (await shouldRequirePassword(ctx, user.id, opts.allowPasswordless)) {
+					if (!ctx.body.password) throw APIError.from("BAD_REQUEST", BASE_ERROR_CODES.INVALID_PASSWORD);
+					await ctx.context.password.checkPassword(user.id, ctx);
+				}
+				const twoFactor = await ctx.context.adapter.findOne({
+					model: twoFactorTable,
+					where: [{
+						field: "userId",
+						value: user.id
+					}]
+				});
+				if (!twoFactor) throw APIError.from("BAD_REQUEST", TWO_FACTOR_ERROR_CODES.TWO_FACTOR_NOT_ENABLED);
+				const backupCodes = await generateBackupCodes(ctx.context.secretConfig, opts);
+				await ctx.context.adapter.update({
+					model: twoFactorTable,
+					update: { backupCodes: backupCodes.encryptedBackupCodes },
+					where: [{
+						field: "id",
+						value: twoFactor.id
+					}]
+				});
+				return ctx.json({
+					status: true,
+					backupCodes: backupCodes.backupCodes
+				});
+			}),
+			/**
+			* A server-only function that returns a user's decrypted two-factor
+			* backup codes. It is not exposed over HTTP and has no client method;
+			* call it from trusted server code with a `userId` taken from an
+			* authenticated session.
+			*
+			* ### API Methods
+			*
+			* **server:**
+			* `auth.api.viewBackupCodes`
+			*
+			* @see [Read our docs to learn more.](https://better-auth.com/docs/plugins/2fa#api-method-two-factor-view-backup-codes)
+			*/
+			viewBackupCodes: createAuthEndpoint.serverOnly({
+				method: "POST",
+				body: viewBackupCodesBodySchema
+			}, async (ctx) => {
+				const twoFactor = await ctx.context.adapter.findOne({
+					model: twoFactorTable,
+					where: [{
+						field: "userId",
+						value: ctx.body.userId
+					}]
+				});
+				if (!twoFactor) throw APIError.from("BAD_REQUEST", TWO_FACTOR_ERROR_CODES.BACKUP_CODES_NOT_ENABLED);
+				const decryptedBackupCodes = await getBackupCodes(twoFactor.backupCodes, ctx.context.secretConfig, opts);
+				if (!decryptedBackupCodes) throw APIError.from("BAD_REQUEST", TWO_FACTOR_ERROR_CODES.INVALID_BACKUP_CODE);
+				return ctx.json({
+					status: true,
+					backupCodes: decryptedBackupCodes
+				});
+			})
+		}
+	};
+};
+//#endregion
+export { backupCode2fa, generateBackupCodes };

package/dist/plugins/two-factor/client.d.mts

@@ -0,0 +1,76 @@
+import { BackupCodeOptions, backupCode2fa, encodeBackupCodes, generateBackupCodes, getBackupCodes, verifyBackupCode } from "./backup-codes/index.mjs";
+import { OTPOptions, otp2fa } from "./otp/index.mjs";
+import { TOTPOptions, totp2fa } from "./totp/index.mjs";
+import { TwoFactorOptions, TwoFactorProvider, TwoFactorTable, UserWithTwoFactor } from "./types.mjs";
+import { TWO_FACTOR_ERROR_CODES } from "./error-code.mjs";
+import { twoFactor } from "./index.mjs";
+import * as _$_better_auth_core_utils_error_codes0 from "@better-auth/core/utils/error-codes";
+import * as _$_better_fetch_fetch0 from "@better-fetch/fetch";
+
+//#region src/plugins/two-factor/client.d.ts
+declare const twoFactorClient: (options?: {
+  /**
+   * the page to redirect if a user needs to verify
+   * their two factor
+   *
+   * @warning This causes a full page reload when used.
+   */
+  twoFactorPage?: string;
+  /**
+   * a redirect function to call if a user needs to verify
+   * their two factor
+   *
+   * @param context.twoFactorMethods - The list of
+   * enabled two factor providers (e.g. ["totp", "otp"]).
+   * Use this to determine which 2FA UI to show.
+   */
+  onTwoFactorRedirect?: (context: {
+    /**
+     * The list of enabled two factor providers
+     * for the user (e.g. ["totp", "otp"]).
+     */
+    twoFactorMethods?: string[];
+  }) => void | Promise<void>;
+} | undefined) => {
+  id: "two-factor";
+  version: string;
+  $InferServerPlugin: ReturnType<typeof twoFactor>;
+  atomListeners: {
+    matcher: (path: string) => boolean;
+    signal: "$sessionSignal";
+  }[];
+  pathMethods: {
+    "/two-factor/disable": "POST";
+    "/two-factor/enable": "POST";
+    "/two-factor/send-otp": "POST";
+    "/two-factor/generate-backup-codes": "POST";
+    "/two-factor/get-totp-uri": "POST";
+    "/two-factor/verify-totp": "POST";
+    "/two-factor/verify-otp": "POST";
+    "/two-factor/verify-backup-code": "POST";
+  };
+  fetchPlugins: {
+    id: string;
+    name: string;
+    hooks: {
+      onSuccess(context: _$_better_fetch_fetch0.SuccessContext<any>): Promise<void>;
+    };
+  }[];
+  $ERROR_CODES: {
+    OTP_NOT_ENABLED: _$_better_auth_core_utils_error_codes0.RawError<"OTP_NOT_ENABLED">;
+    OTP_NOT_CONFIGURED: _$_better_auth_core_utils_error_codes0.RawError<"OTP_NOT_CONFIGURED">;
+    OTP_HAS_EXPIRED: _$_better_auth_core_utils_error_codes0.RawError<"OTP_HAS_EXPIRED">;
+    TOTP_NOT_ENABLED: _$_better_auth_core_utils_error_codes0.RawError<"TOTP_NOT_ENABLED">;
+    TOTP_ALREADY_ENABLED: _$_better_auth_core_utils_error_codes0.RawError<"TOTP_ALREADY_ENABLED">;
+    TOTP_NOT_CONFIGURED: _$_better_auth_core_utils_error_codes0.RawError<"TOTP_NOT_CONFIGURED">;
+    TWO_FACTOR_NOT_ENABLED: _$_better_auth_core_utils_error_codes0.RawError<"TWO_FACTOR_NOT_ENABLED">;
+    BACKUP_CODES_NOT_ENABLED: _$_better_auth_core_utils_error_codes0.RawError<"BACKUP_CODES_NOT_ENABLED">;
+    INVALID_BACKUP_CODE: _$_better_auth_core_utils_error_codes0.RawError<"INVALID_BACKUP_CODE">;
+    INVALID_CODE: _$_better_auth_core_utils_error_codes0.RawError<"INVALID_CODE">;
+    TOO_MANY_ATTEMPTS_REQUEST_NEW_CODE: _$_better_auth_core_utils_error_codes0.RawError<"TOO_MANY_ATTEMPTS_REQUEST_NEW_CODE">;
+    ACCOUNT_TEMPORARILY_LOCKED: _$_better_auth_core_utils_error_codes0.RawError<"ACCOUNT_TEMPORARILY_LOCKED">;
+    INVALID_TWO_FACTOR_COOKIE: _$_better_auth_core_utils_error_codes0.RawError<"INVALID_TWO_FACTOR_COOKIE">;
+  };
+};
+//#endregion
+export { twoFactorClient };

package/dist/plugins/two-factor/client.mjs

@@ -0,0 +1,41 @@
+import { PACKAGE_VERSION } from "../../version.mjs";
+import { TWO_FACTOR_ERROR_CODES } from "./error-code.mjs";
+import { isSafeUrlScheme } from "@better-auth/core/utils/url";
+//#region src/plugins/two-factor/client.ts
+const twoFactorClient = (options) => {
+	return {
+		id: "two-factor",
+		version: PACKAGE_VERSION,
+		$InferServerPlugin: {},
+		atomListeners: [{
+			matcher: (path) => path.startsWith("/two-factor/"),
+			signal: "$sessionSignal"
+		}],
+		pathMethods: {
+			"/two-factor/disable": "POST",
+			"/two-factor/enable": "POST",
+			"/two-factor/send-otp": "POST",
+			"/two-factor/generate-backup-codes": "POST",
+			"/two-factor/get-totp-uri": "POST",
+			"/two-factor/verify-totp": "POST",
+			"/two-factor/verify-otp": "POST",
+			"/two-factor/verify-backup-code": "POST"
+		},
+		fetchPlugins: [{
+			id: "two-factor",
+			name: "two-factor",
+			hooks: { async onSuccess(context) {
+				if (context.data?.twoFactorRedirect) {
+					if (options?.onTwoFactorRedirect) {
+						await options.onTwoFactorRedirect({ twoFactorMethods: context.data.twoFactorMethods });
+						return;
+					}
+					if (options?.twoFactorPage && typeof window !== "undefined" && isSafeUrlScheme(options.twoFactorPage)) window.location.href = options.twoFactorPage;
+				}
+			} }
+		}],
+		$ERROR_CODES: TWO_FACTOR_ERROR_CODES
+	};
+};
+//#endregion
+export { twoFactorClient };

package/dist/plugins/two-factor/constant.mjs

@@ -0,0 +1,6 @@
+//#region src/plugins/two-factor/constant.ts
+const TWO_FACTOR_COOKIE_NAME = "two_factor";
+const TRUST_DEVICE_COOKIE_NAME = "trust_device";
+const TRUST_DEVICE_COOKIE_MAX_AGE = 720 * 60 * 60;
+//#endregion
+export { TRUST_DEVICE_COOKIE_MAX_AGE, TRUST_DEVICE_COOKIE_NAME, TWO_FACTOR_COOKIE_NAME };

package/dist/plugins/two-factor/error-code.d.mts

@@ -0,0 +1,20 @@
+import * as _$_better_auth_core_utils_error_codes0 from "@better-auth/core/utils/error-codes";
+
+//#region src/plugins/two-factor/error-code.d.ts
+declare const TWO_FACTOR_ERROR_CODES: {
+  OTP_NOT_ENABLED: _$_better_auth_core_utils_error_codes0.RawError<"OTP_NOT_ENABLED">;
+  OTP_NOT_CONFIGURED: _$_better_auth_core_utils_error_codes0.RawError<"OTP_NOT_CONFIGURED">;
+  OTP_HAS_EXPIRED: _$_better_auth_core_utils_error_codes0.RawError<"OTP_HAS_EXPIRED">;
+  TOTP_NOT_ENABLED: _$_better_auth_core_utils_error_codes0.RawError<"TOTP_NOT_ENABLED">;
+  TOTP_ALREADY_ENABLED: _$_better_auth_core_utils_error_codes0.RawError<"TOTP_ALREADY_ENABLED">;
+  TOTP_NOT_CONFIGURED: _$_better_auth_core_utils_error_codes0.RawError<"TOTP_NOT_CONFIGURED">;
+  TWO_FACTOR_NOT_ENABLED: _$_better_auth_core_utils_error_codes0.RawError<"TWO_FACTOR_NOT_ENABLED">;
+  BACKUP_CODES_NOT_ENABLED: _$_better_auth_core_utils_error_codes0.RawError<"BACKUP_CODES_NOT_ENABLED">;
+  INVALID_BACKUP_CODE: _$_better_auth_core_utils_error_codes0.RawError<"INVALID_BACKUP_CODE">;
+  INVALID_CODE: _$_better_auth_core_utils_error_codes0.RawError<"INVALID_CODE">;
+  TOO_MANY_ATTEMPTS_REQUEST_NEW_CODE: _$_better_auth_core_utils_error_codes0.RawError<"TOO_MANY_ATTEMPTS_REQUEST_NEW_CODE">;
+  ACCOUNT_TEMPORARILY_LOCKED: _$_better_auth_core_utils_error_codes0.RawError<"ACCOUNT_TEMPORARILY_LOCKED">;
+  INVALID_TWO_FACTOR_COOKIE: _$_better_auth_core_utils_error_codes0.RawError<"INVALID_TWO_FACTOR_COOKIE">;
+};
+//#endregion
+export { TWO_FACTOR_ERROR_CODES };

package/dist/plugins/two-factor/error-code.mjs

@@ -0,0 +1,19 @@
+import { defineErrorCodes } from "@better-auth/core/utils/error-codes";
+//#region src/plugins/two-factor/error-code.ts
+const TWO_FACTOR_ERROR_CODES = defineErrorCodes({
+	OTP_NOT_ENABLED: "OTP not enabled",
+	OTP_NOT_CONFIGURED: "OTP is not available",
+	OTP_HAS_EXPIRED: "OTP has expired",
+	TOTP_NOT_ENABLED: "TOTP not enabled",
+	TOTP_ALREADY_ENABLED: "TOTP is already enabled",
+	TOTP_NOT_CONFIGURED: "TOTP is not available",
+	TWO_FACTOR_NOT_ENABLED: "Two factor isn't enabled",
+	BACKUP_CODES_NOT_ENABLED: "Backup codes aren't enabled",
+	INVALID_BACKUP_CODE: "Invalid backup code",
+	INVALID_CODE: "Invalid code",
+	TOO_MANY_ATTEMPTS_REQUEST_NEW_CODE: "Too many attempts. Please request a new code.",
+	ACCOUNT_TEMPORARILY_LOCKED: "Too many failed verification attempts. Your account is temporarily locked. Please try again later.",
+	INVALID_TWO_FACTOR_COOKIE: "Invalid two factor cookie"
+});
+//#endregion
+export { TWO_FACTOR_ERROR_CODES };