appos 0.4.3-0 → 0.5.1-0

package/dist/exports/{auth-By0xx0MI.d.mts → auth-BCOIpGDO.d.mts}

@@ -1,4 +1,5 @@
-import { betterAuth } from "better-auth";
+import { PasskeyOptions } from "@better-auth/passkey";
+import { BetterAuthOptions, betterAuth } from "better-auth";
 import { Role, createAccessControl } from "better-auth/plugins/access";
 import { z } from "zod";
 import * as drizzle_orm0 from "drizzle-orm";
@@ -127,49 +128,49 @@ declare function defineTestDatabase<TSchema extends Record<string, unknown> = Re
  */
 interface AuthPaths {
   /**
-   * Path to the login page.
-   *
-   * @default "/login"
-   */
+       * Path to the login page.
+       *
+       * @default "/login"
+       */
   login: string;
   /**
-   * Path to the signup/registration page.
-   *
-   * @default "/signup"
-   */
+       * Path to the signup/registration page.
+       *
+       * @default "/signup"
+       */
   signup: string;
   /**
-   * Path to the email verification page.
-   * Only used when email verification is enabled.
-   *
-   * @default "/verify-email"
-   */
+       * Path to the email verification page.
+       * Only used when email verification is enabled.
+       *
+       * @default "/verify-email"
+       */
   verifyEmail: string;
   /**
-   * Path to the forgot password page.
-   *
-   * @default "/forgot-password"
-   */
+       * Path to the forgot password page.
+       *
+       * @default "/forgot-password"
+       */
   forgotPassword: string;
   /**
-   * Path to the password reset page.
-   *
-   * @default "/reset-password"
-   */
+       * Path to the password reset page.
+       *
+       * @default "/reset-password"
+       */
   resetPassword: string;
   /**
-   * Path to the phone OTP login page.
-   * Only generated when phone OTP is enabled in auth config.
-   *
-   * @default "/phone-login"
-   */
+       * Path to the phone OTP login page.
+       * Only generated when phone OTP is enabled in auth config.
+       *
+       * @default "/phone-login"
+       */
   phoneOtp: string;
   /**
-   * Path to the email OTP login page.
-   * Only generated when email OTP is enabled in auth config.
-   *
-   * @default "/email-login"
-   */
+       * Path to the email OTP login page.
+       * Only generated when email OTP is enabled in auth config.
+       *
+       * @default "/email-login"
+       */
   emailOtp: string;
 }
 //#endregion
@@ -183,6 +184,20 @@ type AccessController = ReturnType<typeof createAccessControl>;
  * Type for roles created via ac.newRole().
  */
 type AccessControlRoles = Record<string, Role>;
+/**
+ * Array of all supported captcha providers.
+ * Use with z.enum() for config validation.
+ *
+ * @example
+ * ```ts
+ * CAPTCHA_PROVIDER: z.enum(captchaProviders).optional(),
+ * ```
+ */
+declare const captchaProviders: readonly ["cloudflare-turnstile", "google-recaptcha", "hcaptcha", "captchafox"];
+/**
+ * Captcha provider type.
+ */
+type CaptchaProvider = (typeof captchaProviders)[number];
 /**
  * Standard audit log actions following OCSF/CADF standards. Zod enum provides
  * both runtime validation and TypeScript type.
@@ -212,19 +227,19 @@ type AuditAction = z.infer<typeof auditActionSchema>;
  */
 type AuditLogOptions<TDb> = {
   /**
-   * Tables to exclude from audit logging.
-   */
+       * Tables to exclude from audit logging.
+       */
   excludeTables?: QualifiedTableNames<TDb>[];
   /**
-   * Cron expression for purge schedule.
-   *
-   * @default "0 0 * * *"
-   */
+       * Cron expression for purge schedule.
+       *
+       * @default "0 0 * * *"
+       */
   purgeCron?: string;
   /**
-   * Retention period in days. Audit logs older than this are auto-deleted.
-   * @default 90
-   */
+       * Retention period in days. Audit logs older than this are auto-deleted.
+       * @default 90
+       */
   retentionDays?: number;
 };
 /**
@@ -236,98 +251,98 @@ type AuditLogOptions<TDb> = {
  */
 interface AuthConfig {
   /**
-   * Base URL where auth server is hosted.
-   *
-   * @default "" (same origin - client uses relative URLs)
-   * @example "http://localhost:8000" for cross-origin
-   */
+       * Base URL where auth server is hosted.
+       *
+       * @default "" (same origin - client uses relative URLs)
+       * @example "http://localhost:8000" for cross-origin
+       */
   baseURL?: string;
   /**
-   * Base path for auth routes.
-   *
-   * @default "/auth"
-   */
+       * Base path for auth routes.
+       *
+       * @default "/auth"
+       */
   basePath?: string;
   /**
-   * Custom paths for authentication pages.
-   *
-   * @example
-   * ```typescript
-   * paths: {
-   *   login: "/signin",
-   *   signup: "/register",
-   * }
-   * ```
-   */
+       * Custom paths for authentication pages.
+       *
+       * @example
+       * ```typescript
+       * paths: {
+       *   login: "/signin",
+       *   signup: "/register",
+       * }
+       * ```
+       */
   paths?: Partial<AuthPaths>;
   /**
-   * Authentication methods - if defined, it's enabled.
-   **/
+       * Authentication methods - if defined, it's enabled.
+       **/
   methods?: {
     /**
-     * Email/password auth. If defined, enabled.
-     **/
+             * Email/password auth. If defined, enabled.
+             **/
     emailPassword?: {
       requireEmailVerification?: boolean;
       minPasswordLength?: number;
       maxPasswordLength?: number;
     };
     /**
-     * Magic link auth. If defined, enabled.
-     **/
+             * Magic link auth. If defined, enabled.
+             **/
     magicLink?: {
       expiresIn?: number;
     };
     /**
-     * Passkey auth. If defined (even as empty object), enabled.
-     **/
+             * Passkey auth. If defined (even as empty object), enabled.
+             **/
     passkey?: Record<string, never>;
     /**
-     * Phone OTP auth. If defined, enabled.
-     **/
+             * Phone OTP auth. If defined, enabled.
+             **/
     phoneOtp?: {
       otpLength?: number;
       expiresIn?: number;
     };
     /**
-     * Email OTP auth. If defined, enabled.
-     **/
+             * Email OTP auth. If defined, enabled.
+             **/
     emailOtp?: {
       otpLength?: number;
       expiresIn?: number;
     };
+    /**
+             * OAuth providers - true = enabled, undefined/false = disabled.
+             **/
+    oauth?: {
+      google?: boolean;
+      github?: boolean;
+      apple?: boolean;
+      facebook?: boolean;
+    };
   };
   /**
-   * OAuth providers - true = enabled, undefined/false = disabled.
-   **/
-  oauth?: {
-    google?: boolean;
-    github?: boolean;
-    apple?: boolean;
-    facebook?: boolean;
-  };
-  /**
-   * Plugins - if defined, it's enabled.
-   **/
+       * Plugins - if defined, it's enabled.
+       **/
   plugins?: {
     /**
-     * Admin plugin. If defined, enabled. Includes RBAC for both server and client.
-     **/
+             * Admin plugin. If defined, enabled. Includes RBAC for both server and client.
+             **/
     admin?: {
       defaultRole?: string;
       adminRoles?: string[];
       /**
-       * Access controller created via createAccessControl().
-       **/
+                   * Access controller created via createAccessControl().
+                   **/
       ac: AccessController;
       /**
-       * Role definitions created via ac.newRole().
-       **/
+                   * Role definitions created via ac.newRole().
+                   **/
       roles: AccessControlRoles;
     };
     /**
-     * API key plugin. If defined, enabled.
-     **/
+             * API key plugin. If defined, enabled.
+             **/
     apiKey?: {
       defaultPrefix?: string;
       defaultKeyLength?: number;
@@ -337,8 +352,8 @@ interface AuthConfig {
       };
     };
     /**
-     * Two-factor plugin. If defined, enabled. Sub-features also presence-based.
-     **/
+             * Two-factor plugin. If defined, enabled. Sub-features also presence-based.
+             **/
     twoFactor?: {
       issuer?: string;
       totp?: {
@@ -352,94 +367,159 @@ interface AuthConfig {
       };
     };
     /**
-     * Multi-session plugin. If defined, enabled.
-     **/
+             * Multi-session plugin. If defined, enabled.
+             **/
     multiSession?: {
       /**
-       * Maximum number of active sessions per user.
-       */
+                   * Maximum number of active sessions per user.
+                   */
       maximumSessions?: number;
     };
     /**
-     * Username plugin. If defined, enabled.
-     **/
+             * Username plugin. If defined, enabled.
+             **/
     username?: {
       minUsernameLength?: number;
       maxUsernameLength?: number;
     };
     /**
-     * Anonymous auth plugin. If defined, enabled.
-     **/
+             * Anonymous auth plugin. If defined, enabled.
+             **/
     anonymous?: {
       emailDomainName?: string;
     };
     /**
-     * SSO plugin. If defined, enabled.
-     **/
+             * SSO plugin. If defined, enabled.
+             **/
     sso?: {
       providersLimit?: number;
       trustEmailVerified?: boolean;
       domainVerification?: boolean;
     };
+    /**
+             * Last used login method plugin. If defined, enabled.
+             * Tracks the most recent authentication method used by each user.
+             **/
+    lastUsedMethod?: {
+      /**
+                   * Persist last used method to database for cross-device access.
+                   *
+                   * @default false (cookie-only storage)
+                   */
+      storeInDatabase?: boolean;
+    };
+    /**
+             * Captcha plugin. If defined, enabled.
+             * Protects auth endpoints from bots and abuse.
+             **/
+    captcha?: {
+      /**
+                   * Captcha provider to use.
+                   * For Google reCAPTCHA: v2 vs v3 is determined by server-side minScore config.
+                   */
+      provider: "cloudflare-turnstile" | "google-recaptcha" | "hcaptcha" | "captchafox";
+      /**
+                   * Public site key for the captcha widget (safe to expose in client).
+                   */
+      siteKey: string;
+      /**
+                   * Endpoints to protect with captcha validation.
+                   * Uses substring matching via `request.url.includes(endpoint)`.
+                   *
+                   * @default ["/sign-up/email", "/sign-in/email", "/request-password-reset"]
+                   *
+                   * @example
+                   * ```typescript
+                   * // Protect high-risk endpoints (recommended)
+                   * endpoints: [
+                   *   "/sign-up/email",
+                   *   "/sign-in/email",
+                   *   "/sign-in/magic-link",
+                   *   "/request-password-reset",
+                   *   "/email-otp/send-verification-otp",
+                   *   "/send-verification-email",
+                   *   "/phone-number/send-otp",
+                   * ]
+                   * ```
+                   */
+      endpoints?: string[];
+    };
   };
   /**
-   * Brand configuration for auth pages.
-   * Controls the logo and app name displayed on authentication screens.
-   */
+       * Brand configuration for auth pages.
+       * Controls the logo, app name, layout, and legal URLs displayed on authentication screens.
+       */
   brand?: {
     /**
-     * Logo URL or path relative to the public folder.
-     *
-     * @default "/logo.png"
-     */
+             * Logo URL or path relative to the public folder.
+             *
+             * @default "/logo.png"
+             */
     logo?: string;
     /**
-     * Alt text for the logo image.
-     *
-     * @default App name or "Logo"
-     */
+             * Alt text for the logo image.
+             *
+             * @default App name or "Logo"
+             */
     logoAlt?: string;
     /**
-     * App or brand name displayed next to the logo.
-     *
-     * @default "AppOS"
-     */
+             * App or brand name displayed next to the logo.
+             *
+             * @default "AppOS"
+             */
     name?: string;
+    /**
+             * URL to the privacy policy page.
+             *
+             * @default "/legal/privacy-policy"
+             */
+    privacyUrl?: string;
+    /**
+             * URL to the terms of service page.
+             *
+             * @default "/legal/terms"
+             */
+    termsUrl?: string;
+    /**
+             * Layout variant for auth pages.
+             * - "centered": Card centered on page (default)
+             * - "split": Two-column layout with branding on left
+             * - "minimal": Simple centered layout without trust signals
+             *
+             * @default "centered"
+             */
+    layoutVariant?: "centered" | "split" | "minimal";
   };
   /**
-   * Rate limiting configuration for auth endpoints.
-   * Uses database storage for horizontal scaling support.
-   * Set to false to disable.
-   *
-   * @default { enabled: true, window: 60, max: 100 }
-   *
-   * @example
-   * ```typescript
-   * // Default - enabled with sensible defaults
-   * rateLimit: undefined
-   *
-   * // Custom limits
-   * rateLimit: { window: 30, max: 50 }
-   *
-   * // Override specific endpoint limits
-   * rateLimit: {
-   *   customRules: {
-   *     "/send-verification-email": { window: 60, max: 10 },
-   *   },
-   * }
-   *
-   * // Disable completely
-   * rateLimit: false
-   * ```
-   */
+       * Rate limiting configuration for auth endpoints.
+       * Uses database storage for horizontal scaling support.
+       * Set to false to disable.
+       *
+       * @default { enabled: true, window: 60, max: 100 }
+       *
+       * @example
+       * ```typescript
+       * // Default - enabled with sensible defaults
+       * rateLimit: undefined
+       *
+       * // Custom limits
+       * rateLimit: { window: 30, max: 50 }
+       *
+       * // Override specific endpoint limits
+       * rateLimit: {
+       *   customRules: {
+       *     "/send-verification-email": { window: 60, max: 10 },
+       *   },
+       * }
+       *
+       * // Disable completely
+       * rateLimit: false
+       * ```
+       */
   rateLimit?: {
-    /** Enable rate limiting. @default true */
-    enabled?: boolean;
-    /** Time window in seconds. @default 60 */
-    window?: number;
-    /** Max requests per window. @default 100 */
-    max?: number;
-    /** Custom rate limits per endpoint. Merged with defaults. */
+    /** Enable rate limiting. @default true */enabled?: boolean; /** Time window in seconds. @default 60 */
+    window?: number; /** Max requests per window. @default 100 */
+    max?: number; /** Custom rate limits per endpoint. Merged with defaults. */
     customRules?: Record<string, {
       window: number;
       max: number;
@@ -508,8 +588,10 @@ type RequiredHooks<T extends AuthConfig> = (T["methods"] extends {
  * Conditionally required OAuth credentials based on config.
  * If an OAuth provider is enabled in config, its credentials are REQUIRED.
  */
-type RequiredOAuth<T extends AuthConfig> = (T["oauth"] extends {
-  google: true;
+type RequiredOAuth<T extends AuthConfig> = (T["methods"] extends {
+  oauth: {
+    google: true;
+  };
 } ? {
   google: {
     clientId: string;
@@ -520,8 +602,10 @@ type RequiredOAuth<T extends AuthConfig> = (T["oauth"] extends {
     clientId: string;
     clientSecret: string;
   };
-}) & (T["oauth"] extends {
-  github: true;
+}) & (T["methods"] extends {
+  oauth: {
+    github: true;
+  };
 } ? {
   github: {
     clientId: string;
@@ -532,8 +616,10 @@ type RequiredOAuth<T extends AuthConfig> = (T["oauth"] extends {
     clientId: string;
     clientSecret: string;
   };
-}) & (T["oauth"] extends {
-  apple: true;
+}) & (T["methods"] extends {
+  oauth: {
+    apple: true;
+  };
 } ? {
   apple: {
     clientId: string;
@@ -544,8 +630,10 @@ type RequiredOAuth<T extends AuthConfig> = (T["oauth"] extends {
     clientId: string;
     clientSecret: string;
   };
-}) & (T["oauth"] extends {
-  facebook: true;
+}) & (T["methods"] extends {
+  oauth: {
+    facebook: true;
+  };
 } ? {
   facebook: {
     clientId: string;
@@ -560,14 +648,22 @@ type RequiredOAuth<T extends AuthConfig> = (T["oauth"] extends {
 /**
  * Check if any OAuth provider is enabled.
  **/
-type HasOAuthEnabled<T extends AuthConfig> = T["oauth"] extends {
-  google: true;
+type HasOAuthEnabled<T extends AuthConfig> = T["methods"] extends {
+  oauth: {
+    google: true;
+  };
 } | {
-  github: true;
+  oauth: {
+    github: true;
+  };
 } | {
-  apple: true;
+  oauth: {
+    apple: true;
+  };
 } | {
-  facebook: true;
+  oauth: {
+    facebook: true;
+  };
 } ? true : false;
 /**
  * Check if passkey is enabled
@@ -575,41 +671,52 @@ type HasOAuthEnabled<T extends AuthConfig> = T["oauth"] extends {
 type HasPasskeyEnabled<T extends AuthConfig> = T["methods"] extends {
   passkey: object;
 } ? true : false;
+/**
+ * Check if captcha is enabled
+ **/
+type HasCaptchaEnabled<T extends AuthConfig> = T["plugins"] extends {
+  captcha: object;
+} ? true : false;
+/**
+ * Helper type to extract Better Auth's session options.
+ */
+type BetterAuthSessionOptions = NonNullable<BetterAuthOptions["session"]>;
 /**
  * Server-only session configuration.
+ * Derived from Better Auth's BetterAuthOptions['session'] for type safety.
  */
-interface AuthSessionConfig {
-  /**
-   * Session duration in seconds.
-   *
-   * @default 604800 (7 days)
-   */
-  expiresIn?: number;
-  /**
-   * How often to update session in seconds.
-   *
-   * @default 86400 (1 day)
-   */
-  updateAge?: number;
-  /**
-   * Session freshness in seconds for sensitive ops.
-   *
-   * @default 86400 (1 day)
-   */
-  freshAge?: number;
-}
+type AuthSessionConfig = Pick<BetterAuthSessionOptions, "expiresIn" | "updateAge" | "freshAge">;
 /**
  * Server-only passkey configuration (required if passkey is enabled).
+ * Derived from Better Auth's PasskeyOptions with rpID made required
+ * and origin narrowed to string (appos doesn't support array origins).
  */
-interface AuthPasskeyConfig {
-  /**
-   * Relying Party ID - domain for passkey (e.g., "example.com" or "localhost").
-   */
-  rpID: string;
+type AuthPasskeyConfig = Required<Pick<PasskeyOptions, "rpID">> & {
   /**
-   * Origin URL for passkey verification (e.g., "http://localhost:8000").
-   */
+       * Origin URL for passkey verification (e.g., "http://localhost:8000").
+       * Unlike Better Auth which supports string | string[] | null, appos
+       * requires a single origin string for simplicity.
+       */
   origin: string;
+};
+/**
+ * Server-only captcha configuration (required if captcha is enabled).
+ * These fields align with Better Auth's captcha plugin options.
+ */
+interface AuthCaptchaConfig {
+  /**
+       * Secret key for server-side captcha validation.
+       * Keep this secret - never expose in client code.
+       */
+  secretKey: string;
+  /**
+       * Minimum score threshold for Google reCAPTCHA v3.
+       * Scores range from 0.0 (bot) to 1.0 (human).
+       * Only applicable when using Google reCAPTCHA.
+       *
+       * @default 0.5
+       */
+  minScore?: number;
 }
 /**
  * Fully type-safe options for defineAuth().
@@ -628,45 +735,45 @@ interface AuthPasskeyConfig {
  */
 type DefineAuthOptions<T extends AuthConfig, TDb = unknown> = {
   /**
-   * The application name.
-   */
+       * The application name.
+       */
   appName: string;
   /**
-   * Audit logging configuration (server-only). Use qualified table names: "dbName.tableName".
-   */
+       * Audit logging configuration (server-only). Use qualified table names: "dbName.tableName".
+       */
   auditLog?: AuditLogOptions<TDb>;
   /**
-   * The neutral auth configuration.
-   */
+       * The neutral auth configuration.
+       */
   config: T;
   /**
-   * Full db object (container.db) for type inference.
-   */
+       * Full db object (container.db) for type inference.
+       */
   db: TDb;
   /**
-   * Primary database for Better Auth storage.
-   */
+       * Primary database for Better Auth storage.
+       */
   database: Database;
   /**
-   * Hooks for email sending and OTP delivery.
-   */
+       * Hooks for email sending and OTP delivery.
+       */
   hooks: RequiredHooks<T>;
   /**
-   * Secret key for signing tokens and cookies.
-   */
+       * Secret key for signing tokens and cookies.
+       */
   secret: string;
   /**
-   * Session configuration.
-   */
+       * Session configuration.
+       */
   session?: AuthSessionConfig;
   /**
-   * URL to redirect users when auth errors occur (e.g., OAuth failures).
-   *
-   * Better Auth automatically appends `?error=...&error_description=...`
-   * query params to this URL when redirecting.
-   *
-   * @default "/login"
-   */
+       * URL to redirect users when auth errors occur (e.g., OAuth failures).
+       *
+       * Better Auth automatically appends `?error=...&error_description=...`
+       * query params to this URL when redirecting.
+       *
+       * @default "/login"
+       */
   errorURL?: string;
 } & (HasOAuthEnabled<T> extends true ? {
   oauth: RequiredOAuth<T>;
@@ -676,6 +783,10 @@ type DefineAuthOptions<T extends AuthConfig, TDb = unknown> = {
   passkey: AuthPasskeyConfig;
 } : {
   passkey?: AuthPasskeyConfig;
+}) & (HasCaptchaEnabled<T> extends true ? {
+  captcha: AuthCaptchaConfig;
+} : {
+  captcha?: AuthCaptchaConfig;
 });
 /**
  * Rate limit rule for a single endpoint.
@@ -756,4 +867,4 @@ declare function defineAuth<T extends AuthConfig, TDb extends Record<"primary",
  */
 type Auth$1<TDb extends Record<"primary", Database> & Record<string, Database> = Record<"primary", Database> & Record<string, Database>> = ReturnType<typeof defineAuth<AuthConfig, TDb>>;
 //#endregion
-export { defineTestDatabase as C, defineLogger as D, Logger as E, defineMigrationOpts as S, DefineLoggerOptions as T, DefineTestDatabaseOptions as _, AuthConfig as a, dbChanges as b, DefineAuthOptions as c, createAccessControl as d, defineAuth as f, DefineDatabaseOptions as g, Database as h, Auth$1 as i, Role as l, AuthPaths as m, AccessController as n, AuthPasskeyConfig as o, defineEndpointRateLimits as p, AuditAction as r, AuthSessionConfig as s, AccessControlRoles as t, auditActionSchema as u, MigrationType as v, migrationsSchema as w, defineDatabase as x, QualifiedTableNames as y };
+export { defineLogger as A, dbChanges as C, migrationsSchema as D, defineTestDatabase as E, DefineLoggerOptions as O, QualifiedTableNames as S, defineMigrationOpts as T, AuthPaths as _, AuthCaptchaConfig as a, DefineTestDatabaseOptions as b, AuthSessionConfig as c, Role as d, auditActionSchema as f, defineEndpointRateLimits as g, defineAuth as h, Auth$1 as i, Logger as k, CaptchaProvider as l, createAccessControl as m, AccessController as n, AuthConfig as o, captchaProviders as p, AuditAction as r, AuthPasskeyConfig as s, AccessControlRoles as t, DefineAuthOptions as u, Database as v, defineDatabase as w, MigrationType as x, DefineDatabaseOptions as y };