@masheev/better-auth 0.0.0-stage → 1.7.5

package/dist/plugins/test-utils/factories.mjs

@@ -0,0 +1,38 @@
+import { generateRandomString } from "../../crypto/random.mjs";
+//#region src/plugins/test-utils/factories.ts
+function createUserFactory(ctx) {
+	return (overrides = {}) => {
+		const generatedId = ctx.generateId({ model: "user" });
+		const id = overrides.id || (generatedId === false ? generateRandomString(24, "a-z", "A-Z", "0-9") : generatedId);
+		const now = /* @__PURE__ */ new Date();
+		return {
+			id,
+			email: overrides.email || `test-${generateRandomString(8, "a-z", "0-9")}@example.com`,
+			name: overrides.name || "Test User",
+			emailVerified: overrides.emailVerified ?? true,
+			image: overrides.image ?? null,
+			createdAt: overrides.createdAt || now,
+			updatedAt: overrides.updatedAt || now,
+			...overrides
+		};
+	};
+}
+function createOrganizationFactory(ctx) {
+	return (overrides = {}) => {
+		const generatedId = ctx.generateId({ model: "organization" });
+		const id = overrides.id || (generatedId === false ? generateRandomString(24, "a-z", "A-Z", "0-9") : generatedId);
+		const now = /* @__PURE__ */ new Date();
+		const name = overrides.name || "Test Organization";
+		return {
+			id,
+			name,
+			slug: overrides.slug || `${name.toLowerCase().replace(/\s+/g, "-")}-${generateRandomString(4, "a-z", "0-9")}`,
+			logo: overrides.logo ?? null,
+			metadata: overrides.metadata ?? null,
+			createdAt: overrides.createdAt || now,
+			...overrides
+		};
+	};
+}
+//#endregion
+export { createOrganizationFactory, createUserFactory };

package/dist/plugins/test-utils/index.d.mts

@@ -0,0 +1,73 @@
+import { LoginResult, TestAuthOptions, TestCookie, TestHelpers, TestUtilsOptions } from "./types.mjs";
+import * as _$_better_auth_core0 from "@better-auth/core";
+
+//#region src/plugins/test-utils/index.d.ts
+declare module "@better-auth/core" {
+  interface BetterAuthPluginRegistry<AuthOptions, Options> {
+    "test-utils": {
+      creator: typeof testUtils;
+    };
+  }
+}
+/**
+ * Test utilities plugin for Better Auth.
+ *
+ * Provides helpers for integration and E2E testing including:
+ * - User/Organization factories (creates objects without DB writes)
+ * - Database helpers (save, delete)
+ * - Auth helpers (login, getAuthHeaders, getCookies)
+ * - OTP capture (when captureOTP: true)
+ *
+ * This plugin does not register public HTTP routes or API endpoints, but it does
+ * expose privileged helpers on `ctx.test` for creating sessions and mutating data.
+ * Prefer including it in a test-only auth instance such as `auth.test.ts` instead
+ * of a production auth config.
+ *
+ * If you conditionally spread it into `plugins`, TypeScript may stop inferring
+ * `ctx.test` correctly. A separate test-only auth instance keeps the helpers
+ * typed without adding the plugin to your production auth config.
+ *
+ * @example
+ * ```ts
+ * import { betterAuth } from "better-auth";
+ * import { testUtils } from "better-auth/plugins";
+ *
+ * export const testAuth = betterAuth({
+ *   plugins: [
+ *     testUtils({ captureOTP: true }),
+ *   ],
+ * });
+ *
+ * // In tests, access helpers via context:
+ * const ctx = await testAuth.$context;
+ * const test = ctx.test;
+ *
+ * const user = test.createUser({ email: "test@example.com" });
+ * const savedUser = await test.saveUser(user);
+ * const { headers, cookies } = await test.login({ userId: user.id });
+ * ```
+ */
+declare const testUtils: (options?: TestUtilsOptions) => {
+  id: "test-utils";
+  version: string;
+  init(ctx: _$_better_auth_core0.AuthContext): {
+    context: {
+      test: TestHelpers;
+    };
+    options: {
+      databaseHooks: {
+        verification: {
+          create: {
+            after(verification: {
+              identifier: string;
+              value: string;
+            } | null): Promise<void>;
+          };
+        };
+      };
+    } | undefined;
+  };
+  options: TestUtilsOptions;
+};
+//#endregion
+export { testUtils };

package/dist/plugins/test-utils/index.mjs

@@ -0,0 +1,97 @@
+import { PACKAGE_VERSION } from "../../version.mjs";
+import { createGetAuthHeaders, createGetCookies, createLogin } from "./auth-helpers.mjs";
+import { createAddMember, createDeleteOrganization, createDeleteUser, createSaveOrganization, createSaveUser } from "./db-helpers.mjs";
+import { createOrganizationFactory, createUserFactory } from "./factories.mjs";
+import { createOTPStore } from "./otp-sink.mjs";
+//#region src/plugins/test-utils/index.ts
+/**
+* Test utilities plugin for Better Auth.
+*
+* Provides helpers for integration and E2E testing including:
+* - User/Organization factories (creates objects without DB writes)
+* - Database helpers (save, delete)
+* - Auth helpers (login, getAuthHeaders, getCookies)
+* - OTP capture (when captureOTP: true)
+*
+* This plugin does not register public HTTP routes or API endpoints, but it does
+* expose privileged helpers on `ctx.test` for creating sessions and mutating data.
+* Prefer including it in a test-only auth instance such as `auth.test.ts` instead
+* of a production auth config.
+*
+* If you conditionally spread it into `plugins`, TypeScript may stop inferring
+* `ctx.test` correctly. A separate test-only auth instance keeps the helpers
+* typed without adding the plugin to your production auth config.
+*
+* @example
+* ```ts
+* import { betterAuth } from "better-auth";
+* import { testUtils } from "better-auth/plugins";
+*
+* export const testAuth = betterAuth({
+*   plugins: [
+*     testUtils({ captureOTP: true }),
+*   ],
+* });
+*
+* // In tests, access helpers via context:
+* const ctx = await testAuth.$context;
+* const test = ctx.test;
+*
+* const user = test.createUser({ email: "test@example.com" });
+* const savedUser = await test.saveUser(user);
+* const { headers, cookies } = await test.login({ userId: user.id });
+* ```
+*/
+const testUtils = (options = {}) => {
+	return {
+		id: "test-utils",
+		version: PACKAGE_VERSION,
+		init(ctx) {
+			const hasOrgPlugin = ctx.hasPlugin("organization");
+			const helpers = {
+				createUser: createUserFactory(ctx),
+				saveUser: createSaveUser(ctx),
+				deleteUser: createDeleteUser(ctx),
+				login: createLogin(ctx),
+				getAuthHeaders: createGetAuthHeaders(ctx),
+				getCookies: createGetCookies(ctx)
+			};
+			if (hasOrgPlugin) {
+				helpers.createOrganization = createOrganizationFactory(ctx);
+				helpers.saveOrganization = createSaveOrganization(ctx);
+				helpers.deleteOrganization = createDeleteOrganization(ctx);
+				helpers.addMember = createAddMember(ctx);
+			}
+			const otpStore = createOTPStore();
+			if (options.captureOTP) {
+				helpers.getOTP = otpStore.get;
+				helpers.clearOTPs = otpStore.clear;
+			}
+			const databaseHooks = options.captureOTP ? { verification: { create: { async after(verification) {
+				if (verification?.value && verification?.identifier) {
+					const otpPart = verification.value.split(":")[0];
+					if (otpPart) {
+						let identifier = verification.identifier;
+						for (const prefix of [
+							"email-verification-otp-",
+							"sign-in-otp-",
+							"forget-password-otp-",
+							"phone-verification-otp-"
+						]) if (identifier.startsWith(prefix)) {
+							identifier = identifier.slice(prefix.length);
+							break;
+						}
+						otpStore.capture(identifier, otpPart);
+					}
+				}
+			} } } } : null;
+			return {
+				context: { test: helpers },
+				options: databaseHooks ? { databaseHooks } : void 0
+			};
+		},
+		options
+	};
+};
+//#endregion
+export { testUtils };

package/dist/plugins/test-utils/otp-sink.mjs

@@ -0,0 +1,21 @@
+//#region src/plugins/test-utils/otp-sink.ts
+/**
+* Creates an instance-scoped OTP store for capturing OTPs during testing.
+* Each auth instance gets its own store to avoid cross-contamination.
+*/
+function createOTPStore() {
+	const otpStore = /* @__PURE__ */ new Map();
+	return {
+		capture(identifier, otp) {
+			otpStore.set(identifier, otp);
+		},
+		get(identifier) {
+			return otpStore.get(identifier);
+		},
+		clear() {
+			otpStore.clear();
+		}
+	};
+}
+//#endregion
+export { createOTPStore };

package/dist/plugins/test-utils/types.d.mts

@@ -0,0 +1,51 @@
+import { Session, User } from "../../types/models.mjs";
+//#region src/plugins/test-utils/types.d.ts
+interface TestUtilsOptions {
+  /** Capture OTPs in memory when created (doesn't prevent sending) */
+  captureOTP?: boolean;
+}
+interface TestCookie {
+  name: string;
+  value: string;
+  domain: string;
+  path: string;
+  httpOnly?: boolean;
+  secure?: boolean;
+  sameSite?: "Lax" | "Strict" | "None";
+  expires?: number;
+}
+interface LoginResult {
+  session: Session;
+  user: User;
+  headers: Headers;
+  cookies: TestCookie[];
+  token: string;
+}
+/** Options for creating a session with the test auth helpers. */
+interface TestAuthOptions {
+  userId: string;
+  /** Additional session fields. Standard session fields are ignored. */
+  session?: Record<string, unknown>;
+}
+interface TestHelpers {
+  createUser(overrides?: Partial<User> & Record<string, unknown>): User;
+  createOrganization?(overrides?: Record<string, unknown>): Record<string, unknown>;
+  saveUser(user: User): Promise<User>;
+  saveOrganization?(org: Record<string, unknown>): Promise<Record<string, unknown>>;
+  addMember?(opts: {
+    userId: string;
+    organizationId: string;
+    role?: string;
+  }): Promise<Record<string, unknown>>;
+  deleteUser(userId: string): Promise<void>;
+  deleteOrganization?(orgId: string): Promise<void>;
+  login(opts: TestAuthOptions): Promise<LoginResult>;
+  getAuthHeaders(opts: TestAuthOptions): Promise<Headers>;
+  getCookies(opts: TestAuthOptions & {
+    domain?: string;
+  }): Promise<TestCookie[]>;
+  getOTP?(identifier: string): string | undefined;
+  clearOTPs?(): void;
+}
+//#endregion
+export { LoginResult, TestAuthOptions, TestCookie, TestHelpers, TestUtilsOptions };

package/dist/plugins/two-factor/backup-codes/index.d.mts

@@ -0,0 +1,291 @@
+import { SecretConfig } from "../../../crypto/index.mjs";
+import { UserWithTwoFactor } from "../types.mjs";
+import * as _$better_call0 from "better-call";
+import * as z from "zod";
+
+//#region src/plugins/two-factor/backup-codes/index.d.ts
+interface BackupCodeOptions {
+  /**
+   * The amount of backup codes to generate
+   *
+   * @default 10
+   */
+  amount?: number | undefined;
+  /**
+   * The length of the backup codes
+   *
+   * @default 10
+   */
+  length?: number | undefined;
+  /**
+   * An optional custom function to generate backup codes
+   */
+  customBackupCodesGenerate?: (() => string[]) | undefined;
+  /**
+   * How to store the backup codes in the database, whether encrypted or plain.
+   */
+  storeBackupCodes?: ("plain" | "encrypted" | {
+    encrypt: (token: string) => Promise<string>;
+    decrypt: (token: string) => Promise<string>;
+  }) | undefined;
+  /**
+   * Allow generating backup codes without a password when the user does not
+   * have a credential account.
+   * When enabled, password is still required if a credential account exists.
+   * @default false
+   */
+  allowPasswordless?: boolean | undefined;
+}
+declare function encodeBackupCodes(codes: string[], secret: string | SecretConfig, options?: BackupCodeOptions | undefined): Promise<string>;
+declare function generateBackupCodes(secret: string | SecretConfig, options?: BackupCodeOptions | undefined): Promise<{
+  backupCodes: string[];
+  encryptedBackupCodes: string;
+}>;
+declare function verifyBackupCode(data: {
+  backupCodes: string;
+  code: string;
+}, key: string | SecretConfig, options?: BackupCodeOptions | undefined): Promise<{
+  status: boolean;
+  updated: null;
+} | {
+  status: boolean;
+  updated: string[];
+}>;
+declare function getBackupCodes(backupCodes: string, key: string | SecretConfig, options?: BackupCodeOptions | undefined): Promise<string[] | null>;
+declare const backupCode2fa: (opts: BackupCodeOptions) => {
+  id: "backup_code";
+  version: string;
+  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: _$better_call0.StrictEndpoint<"/two-factor/verify-backup-code", {
+      method: "POST";
+      body: z.ZodObject<{
+        code: z.ZodString;
+        disableSession: z.ZodOptional<z.ZodBoolean>;
+        trustDevice: z.ZodOptional<z.ZodBoolean>;
+      }, z.core.$strip>;
+      metadata: {
+        openapi: {
+          description: string;
+          responses: {
+            "200": {
+              description: string;
+              content: {
+                "application/json": {
+                  schema: {
+                    type: "object";
+                    properties: {
+                      user: {
+                        type: string;
+                        properties: {
+                          id: {
+                            type: string;
+                            description: string;
+                          };
+                          email: {
+                            type: string;
+                            format: string;
+                            nullable: boolean;
+                            description: string;
+                          };
+                          emailVerified: {
+                            type: string;
+                            nullable: boolean;
+                            description: string;
+                          };
+                          name: {
+                            type: string;
+                            nullable: boolean;
+                            description: string;
+                          };
+                          image: {
+                            type: string;
+                            format: string;
+                            nullable: boolean;
+                            description: string;
+                          };
+                          twoFactorEnabled: {
+                            type: string;
+                            description: string;
+                          };
+                          createdAt: {
+                            type: string;
+                            format: string;
+                            description: string;
+                          };
+                          updatedAt: {
+                            type: string;
+                            format: string;
+                            description: string;
+                          };
+                        };
+                        required: string[];
+                        description: string;
+                      };
+                      session: {
+                        type: string;
+                        properties: {
+                          token: {
+                            type: string;
+                            description: string;
+                          };
+                          userId: {
+                            type: string;
+                            description: string;
+                          };
+                          createdAt: {
+                            type: string;
+                            format: string;
+                            description: string;
+                          };
+                          expiresAt: {
+                            type: string;
+                            format: string;
+                            description: string;
+                          };
+                        };
+                        required: string[];
+                        description: string;
+                      };
+                    };
+                    required: string[];
+                  };
+                };
+              };
+            };
+          };
+        };
+      };
+    }, {
+      token: string | undefined;
+      user: (Record<string, any> & {
+        id: string;
+        createdAt: Date;
+        updatedAt: Date;
+        email: string;
+        emailVerified: boolean;
+        name: string;
+        image?: string | null | undefined;
+      }) | UserWithTwoFactor;
+    }>;
+    /**
+     * ### 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: _$better_call0.StrictEndpoint<"/two-factor/generate-backup-codes", {
+      method: "POST";
+      body: z.ZodObject<{
+        password: z.ZodOptional<z.ZodString>;
+      }, z.core.$strip> | z.ZodObject<{
+        password: z.ZodString;
+      }, z.core.$strip>;
+      use: _$better_call0.Middleware<_$better_call0.MiddlewareOptions, (inputContext: _$better_call0.MiddlewareInputContext<_$better_call0.MiddlewareOptions>) => Promise<{
+        session: {
+          session: Record<string, any> & {
+            id: string;
+            createdAt: Date;
+            updatedAt: Date;
+            userId: string;
+            expiresAt: Date;
+            token: string;
+            ipAddress?: string | null | undefined;
+            userAgent?: string | null | undefined;
+          };
+          user: Record<string, any> & {
+            id: string;
+            createdAt: Date;
+            updatedAt: Date;
+            email: string;
+            emailVerified: boolean;
+            name: string;
+            image?: string | null | undefined;
+          };
+        };
+      }>>[];
+      metadata: {
+        openapi: {
+          description: string;
+          responses: {
+            "200": {
+              description: string;
+              content: {
+                "application/json": {
+                  schema: {
+                    type: "object";
+                    properties: {
+                      status: {
+                        type: string;
+                        description: string;
+                        enum: boolean[];
+                      };
+                      backupCodes: {
+                        type: string;
+                        items: {
+                          type: string;
+                        };
+                        description: string;
+                      };
+                    };
+                    required: string[];
+                  };
+                };
+              };
+            };
+          };
+        };
+      };
+    }, {
+      status: boolean;
+      backupCodes: string[];
+    }>;
+    /**
+     * 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: _$better_call0.StrictEndpoint<string, {
+      method: "POST";
+      body: z.ZodObject<{
+        userId: z.ZodCoercedString<unknown>;
+      }, z.core.$strip>;
+    }, {
+      status: boolean;
+      backupCodes: string[];
+    }>;
+  };
+};
+//#endregion
+export { BackupCodeOptions, backupCode2fa, encodeBackupCodes, generateBackupCodes, getBackupCodes, verifyBackupCode };