appos 0.4.1-0 → 0.4.3-0

package/dist/exports/auth-By0xx0MI.d.mts

@@ -0,0 +1,759 @@
+import { betterAuth } from "better-auth";
+import { Role, createAccessControl } from "better-auth/plugins/access";
+import { z } from "zod";
+import * as drizzle_orm0 from "drizzle-orm";
+import { AnyRelations, EmptyRelations } from "drizzle-orm";
+import { PgTable } from "drizzle-orm/pg-core";
+import * as drizzle_orm_node_postgres0 from "drizzle-orm/node-postgres";
+import * as pg0 from "pg";
+import pg from "pg";
+import pino, { LoggerOptions } from "pino";
+import { MigrationConfig } from "drizzle-orm/migrator";
+
+//#region src/api/logger.d.ts
+/**
+ * Extended logger options with OpenTelemetry support.
+ */
+interface DefineLoggerOptions extends LoggerOptions {}
+/**
+ * The logger instance type.
+ */
+type Logger = Awaited<ReturnType<typeof defineLogger>>;
+/**
+ * Define the logger instance.
+ *
+ * @param opts - The options.
+ * @returns The logger.
+ */
+declare function defineLogger(opts: DefineLoggerOptions): Promise<pino.Logger<never, boolean>>;
+//#endregion
+//#region src/api/database.d.ts
+type PoolConfig = pg.PoolConfig;
+/**
+ * Extract qualified table names from db object.
+ */
+type QualifiedTableNames<TDb> = { [K in keyof TDb]: TDb[K] extends {
+  _: {
+    fullSchema: infer S;
+  };
+} ? `${K & string}.${keyof S & string}` : never }[keyof TDb];
+/**
+ * The schema used for migrations.
+ */
+declare const migrationsSchema = "public";
+/**
+ * The type of migration (schema or data).
+ */
+type MigrationType = "schema" | "data";
+/**
+ * Get the migration options for a specific database.
+ *
+ * @param name Name of the database to get migration options for
+ * @param type Type of migration (schema or data), defaults to "schema"
+ * @returns Migration configuration for drizzle-orm
+ */
+declare function defineMigrationOpts(name: string, type?: MigrationType): MigrationConfig;
+/**
+ * Options for defining the database.
+ */
+interface DefineDatabaseOptions<TSchema extends Record<string, unknown> = Record<string, never>, TRelations extends AnyRelations = EmptyRelations> {
+  logger: Logger;
+  poolConfig: PoolConfig;
+  relations?: TRelations;
+  schema?: TSchema;
+}
+/**
+ * The database type.
+ */
+type Database = Awaited<ReturnType<typeof defineDatabase>>;
+/**
+ * Generate old and new row JSONB representations for delete/insert/update queries.
+ * Uses PostgreSQL 18's OLD/NEW support in RETURNING clause.
+ *
+ * @param table The table to generate changes for.
+ * @returns Object containing `_table`, `old` and `new` JSONB columns.
+ */
+declare function dbChanges<T extends PgTable>(table: T): {
+  _table: drizzle_orm0.SQL.Aliased<string>;
+  old: drizzle_orm0.SQL.Aliased<({ [Key in keyof T["_"]["columns"] & string]: T["_"]["columns"][Key]["_"]["notNull"] extends true ? T["_"]["columns"][Key]["_"]["data"] : T["_"]["columns"][Key]["_"]["data"] | null } extends infer T_1 ? { [K in keyof T_1]: T_1[K] } : never) | null>;
+  new: drizzle_orm0.SQL.Aliased<({ [Key in keyof T["_"]["columns"] & string]: T["_"]["columns"][Key]["_"]["notNull"] extends true ? T["_"]["columns"][Key]["_"]["data"] : T["_"]["columns"][Key]["_"]["data"] | null } extends infer T_2 ? { [K in keyof T_2]: T_2[K] } : never) | null>;
+};
+/**
+ * Define the database with the provided options.
+ *
+ * Algorithm:
+ * 1. Create a connection pool with sensible defaults
+ * 2. Initialize drizzle ORM with schema and relations
+ *
+ * @param opts The options for defining the database, including pool configuration, relations, and schema.
+ * @template TSchema The schema type for the database.
+ * @template TRelations The relations type for the database.
+ * @returns The defined database instance.
+ */
+declare function defineDatabase<TSchema extends Record<string, unknown> = Record<string, never>, TRelations extends AnyRelations = EmptyRelations>(opts: DefineDatabaseOptions<TSchema, TRelations>): Promise<drizzle_orm_node_postgres0.NodePgDatabase<TSchema, TRelations> & {
+  $client: pg0.Pool;
+}>;
+/**
+ * Options for defining a test database.
+ */
+interface DefineTestDatabaseOptions<TSchema extends Record<string, unknown> = Record<string, never>, TRelations extends AnyRelations = EmptyRelations> {
+  connectionString: string;
+  logger: Logger;
+  name: string;
+  schema: TSchema;
+  relations: TRelations;
+}
+/**
+ * Create a single test database with isolated schema.
+ *
+ * @param connectionString - Database connection string
+ * @param name - Name of the test database
+ * @returns Test database instance and cleanup function
+ */
+declare function defineTestDatabase<TSchema extends Record<string, unknown> = Record<string, never>, TRelations extends AnyRelations = EmptyRelations>(opts: DefineTestDatabaseOptions<TSchema, TRelations>): Promise<{
+  cleanUp: () => Promise<void>;
+  db: drizzle_orm_node_postgres0.NodePgDatabase<TSchema, TRelations> & {
+    $client: pg0.Pool;
+  };
+  dbName: string;
+}>;
+//#endregion
+//#region src/web/client/auth-paths.d.ts
+/**
+ * Configuration for authentication route paths.
+ *
+ * All paths should be absolute (starting with "/").
+ * These paths are used for both route generation and navigation.
+ */
+interface AuthPaths {
+  /**
+   * Path to the login page.
+   *
+   * @default "/login"
+   */
+  login: string;
+  /**
+   * 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"
+   */
+  verifyEmail: string;
+  /**
+   * Path to the forgot password page.
+   *
+   * @default "/forgot-password"
+   */
+  forgotPassword: string;
+  /**
+   * 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"
+   */
+  phoneOtp: string;
+  /**
+   * Path to the email OTP login page.
+   * Only generated when email OTP is enabled in auth config.
+   *
+   * @default "/email-login"
+   */
+  emailOtp: string;
+}
+//#endregion
+//#region src/api/auth.d.ts
+/**
+ * Type for access controller created via createAccessControl().
+ * Used for RBAC on both server and client.
+ */
+type AccessController = ReturnType<typeof createAccessControl>;
+/**
+ * Type for roles created via ac.newRole().
+ */
+type AccessControlRoles = Record<string, Role>;
+/**
+ * Standard audit log actions following OCSF/CADF standards. Zod enum provides
+ * both runtime validation and TypeScript type.
+ *
+ * Actions:
+ * - Data ops: INSERT, UPDATE, DELETE, TRUNCATE, SELECT
+ * - Auth ops: LOGIN, LOGOUT, LOGIN_FAILED, PASSWORD_CHANGE
+ * - Custom: CUSTOM (use customAction field for app-specific events)
+ */
+declare const auditActionSchema: z.ZodEnum<{
+  DELETE: "DELETE";
+  LOGIN: "LOGIN";
+  LOGOUT: "LOGOUT";
+  INSERT: "INSERT";
+  PASSWORD_CHANGE: "PASSWORD_CHANGE";
+  TRUNCATE: "TRUNCATE";
+  UPDATE: "UPDATE";
+}>;
+/**
+ * TypeScript type extracted from Zod enum.
+ */
+type AuditAction = z.infer<typeof auditActionSchema>;
+/**
+ * Type-safe audit log options for defineAuth().
+ *
+ * @template TDb - Database record type for table name inference
+ */
+type AuditLogOptions<TDb> = {
+  /**
+   * Tables to exclude from audit logging.
+   */
+  excludeTables?: QualifiedTableNames<TDb>[];
+  /**
+   * Cron expression for purge schedule.
+   *
+   * @default "0 0 * * *"
+   */
+  purgeCron?: string;
+  /**
+   * Retention period in days. Audit logs older than this are auto-deleted.
+   * @default 90
+   */
+  retentionDays?: number;
+};
+/**
+ * Neutral auth configuration - shared between server and client.
+ * Contains ONLY fields that affect both sides (UI + server features).
+ *
+ * PRESENCE-BASED CONFIG: If a key exists, it's enabled. No redundant `enabled` fields.
+ * Server-only fields (appName, session) are passed via DefineAuthOptions.
+ */
+interface AuthConfig {
+  /**
+   * 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"
+   */
+  basePath?: string;
+  /**
+   * Custom paths for authentication pages.
+   *
+   * @example
+   * ```typescript
+   * paths: {
+   *   login: "/signin",
+   *   signup: "/register",
+   * }
+   * ```
+   */
+  paths?: Partial<AuthPaths>;
+  /**
+   * Authentication methods - if defined, it's enabled.
+   **/
+  methods?: {
+    /**
+     * Email/password auth. If defined, enabled.
+     **/
+    emailPassword?: {
+      requireEmailVerification?: boolean;
+      minPasswordLength?: number;
+      maxPasswordLength?: number;
+    };
+    /**
+     * Magic link auth. If defined, enabled.
+     **/
+    magicLink?: {
+      expiresIn?: number;
+    };
+    /**
+     * Passkey auth. If defined (even as empty object), enabled.
+     **/
+    passkey?: Record<string, never>;
+    /**
+     * Phone OTP auth. If defined, enabled.
+     **/
+    phoneOtp?: {
+      otpLength?: number;
+      expiresIn?: number;
+    };
+    /**
+     * 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;
+  };
+  /**
+   * Plugins - if defined, it's enabled.
+   **/
+  plugins?: {
+    /**
+     * Admin plugin. If defined, enabled. Includes RBAC for both server and client.
+     **/
+    admin?: {
+      defaultRole?: string;
+      adminRoles?: string[];
+      /**
+       * Access controller created via createAccessControl().
+       **/
+      ac: AccessController;
+      /**
+       * Role definitions created via ac.newRole().
+       **/
+      roles: AccessControlRoles;
+    };
+    /**
+     * API key plugin. If defined, enabled.
+     **/
+    apiKey?: {
+      defaultPrefix?: string;
+      defaultKeyLength?: number;
+      rateLimit?: {
+        maxRequests?: number;
+        timeWindow?: number;
+      };
+    };
+    /**
+     * Two-factor plugin. If defined, enabled. Sub-features also presence-based.
+     **/
+    twoFactor?: {
+      issuer?: string;
+      totp?: {
+        digits?: 6 | 8;
+        period?: number;
+      };
+      otp?: boolean;
+      backupCodes?: {
+        amount?: number;
+        length?: number;
+      };
+    };
+    /**
+     * Multi-session plugin. If defined, enabled.
+     **/
+    multiSession?: {
+      /**
+       * Maximum number of active sessions per user.
+       */
+      maximumSessions?: number;
+    };
+    /**
+     * Username plugin. If defined, enabled.
+     **/
+    username?: {
+      minUsernameLength?: number;
+      maxUsernameLength?: number;
+    };
+    /**
+     * Anonymous auth plugin. If defined, enabled.
+     **/
+    anonymous?: {
+      emailDomainName?: string;
+    };
+    /**
+     * SSO plugin. If defined, enabled.
+     **/
+    sso?: {
+      providersLimit?: number;
+      trustEmailVerified?: boolean;
+      domainVerification?: boolean;
+    };
+  };
+  /**
+   * Brand configuration for auth pages.
+   * Controls the logo and app name displayed on authentication screens.
+   */
+  brand?: {
+    /**
+     * 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"
+     */
+    logoAlt?: string;
+    /**
+     * App or brand name displayed next to the logo.
+     *
+     * @default "AppOS"
+     */
+    name?: string;
+  };
+  /**
+   * 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. */
+    customRules?: Record<string, {
+      window: number;
+      max: number;
+    }>;
+  } | false;
+}
+/** Base hook types for reference */
+type EmailHook = (params: {
+  email: string;
+  url: string;
+  token: string;
+}) => Promise<void>;
+type OtpHook = (params: {
+  email: string;
+  otp: string;
+}) => Promise<void>;
+type PhoneOtpHook = (params: {
+  phoneNumber: string;
+  otp: string;
+}) => Promise<void>;
+/**
+ * Conditionally required hooks based on config.
+ */
+type RequiredHooks<T extends AuthConfig> = (T["methods"] extends {
+  emailPassword: {
+    requireEmailVerification: true;
+  };
+} ? {
+  sendVerificationEmail: EmailHook;
+} : {
+  sendVerificationEmail?: EmailHook;
+}) & (T["methods"] extends {
+  emailPassword: object;
+} ? {
+  sendResetPasswordEmail: EmailHook;
+} : {
+  sendResetPasswordEmail?: EmailHook;
+}) & (T["methods"] extends {
+  magicLink: object;
+} ? {
+  sendMagicLink: EmailHook;
+} : {
+  sendMagicLink?: EmailHook;
+}) & (T["methods"] extends {
+  emailOtp: object;
+} ? {
+  sendEmailOTP: OtpHook;
+} : {
+  sendEmailOTP?: OtpHook;
+}) & (T["methods"] extends {
+  phoneOtp: object;
+} ? {
+  sendPhoneOTP: PhoneOtpHook;
+} : {
+  sendPhoneOTP?: PhoneOtpHook;
+}) & (T["plugins"] extends {
+  twoFactor: {
+    otp: true;
+  };
+} ? {
+  send2FAOTP: OtpHook;
+} : {
+  send2FAOTP?: OtpHook;
+});
+/**
+ * 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;
+} ? {
+  google: {
+    clientId: string;
+    clientSecret: string;
+  };
+} : {
+  google?: {
+    clientId: string;
+    clientSecret: string;
+  };
+}) & (T["oauth"] extends {
+  github: true;
+} ? {
+  github: {
+    clientId: string;
+    clientSecret: string;
+  };
+} : {
+  github?: {
+    clientId: string;
+    clientSecret: string;
+  };
+}) & (T["oauth"] extends {
+  apple: true;
+} ? {
+  apple: {
+    clientId: string;
+    clientSecret: string;
+  };
+} : {
+  apple?: {
+    clientId: string;
+    clientSecret: string;
+  };
+}) & (T["oauth"] extends {
+  facebook: true;
+} ? {
+  facebook: {
+    clientId: string;
+    clientSecret: string;
+  };
+} : {
+  facebook?: {
+    clientId: string;
+    clientSecret: string;
+  };
+});
+/**
+ * Check if any OAuth provider is enabled.
+ **/
+type HasOAuthEnabled<T extends AuthConfig> = T["oauth"] extends {
+  google: true;
+} | {
+  github: true;
+} | {
+  apple: true;
+} | {
+  facebook: true;
+} ? true : false;
+/**
+ * Check if passkey is enabled
+ **/
+type HasPasskeyEnabled<T extends AuthConfig> = T["methods"] extends {
+  passkey: object;
+} ? true : false;
+/**
+ * Server-only session configuration.
+ */
+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;
+}
+/**
+ * Server-only passkey configuration (required if passkey is enabled).
+ */
+interface AuthPasskeyConfig {
+  /**
+   * Relying Party ID - domain for passkey (e.g., "example.com" or "localhost").
+   */
+  rpID: string;
+  /**
+   * Origin URL for passkey verification (e.g., "http://localhost:8000").
+   */
+  origin: string;
+}
+/**
+ * Fully type-safe options for defineAuth().
+ *
+ * Server-only fields:
+ * - `appName` - Application name for passkey rpName, TOTP issuer, emails
+ * - `auditLog` - Audit logging configuration
+ * - `session` - Session duration and freshness settings
+ *
+ * Conditional requirements:
+ * - If config has `oauth.google: true`, then `oauth.google` credentials are REQUIRED
+ * - If config has `methods.magicLink` defined, then `hooks.sendMagicLink` is REQUIRED
+ *
+ * @template T - Auth config type
+ * @template TDb - Database record type for type-safe excludeTables
+ */
+type DefineAuthOptions<T extends AuthConfig, TDb = unknown> = {
+  /**
+   * The application name.
+   */
+  appName: string;
+  /**
+   * Audit logging configuration (server-only). Use qualified table names: "dbName.tableName".
+   */
+  auditLog?: AuditLogOptions<TDb>;
+  /**
+   * The neutral auth configuration.
+   */
+  config: T;
+  /**
+   * Full db object (container.db) for type inference.
+   */
+  db: TDb;
+  /**
+   * Primary database for Better Auth storage.
+   */
+  database: Database;
+  /**
+   * Hooks for email sending and OTP delivery.
+   */
+  hooks: RequiredHooks<T>;
+  /**
+   * Secret key for signing tokens and cookies.
+   */
+  secret: string;
+  /**
+   * 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"
+   */
+  errorURL?: string;
+} & (HasOAuthEnabled<T> extends true ? {
+  oauth: RequiredOAuth<T>;
+} : {
+  oauth?: RequiredOAuth<T>;
+}) & (HasPasskeyEnabled<T> extends true ? {
+  passkey: AuthPasskeyConfig;
+} : {
+  passkey?: AuthPasskeyConfig;
+});
+/**
+ * Rate limit rule for a single endpoint.
+ */
+type RateLimitRule = {
+  window: number;
+  max: number;
+};
+/**
+ * Default rate limits for endpoints that trigger costly 3rd party services.
+ * 3 requests per 60 seconds to prevent excessive email/SMS costs.
+ */
+declare const DEFAULT_COSTLY_RATE_LIMITS: {
+  readonly "/send-verification-email": {
+    readonly window: 60;
+    readonly max: 3;
+  };
+  readonly "/request-password-reset": {
+    readonly window: 60;
+    readonly max: 3;
+  };
+  readonly "/sign-in/magic-link": {
+    readonly window: 60;
+    readonly max: 3;
+  };
+  readonly "/email-otp/send-verification-otp": {
+    readonly window: 60;
+    readonly max: 3;
+  };
+  readonly "/two-factor/send-otp": {
+    readonly window: 60;
+    readonly max: 3;
+  };
+  readonly "/phone-number/send-otp": {
+    readonly window: 60;
+    readonly max: 3;
+  };
+};
+/**
+ * Default endpoint paths that have rate limiting applied.
+ */
+type DefaultRateLimitEndpoint = keyof typeof DEFAULT_COSTLY_RATE_LIMITS;
+/**
+ * Creates endpoint-specific rate limit rules by merging user overrides with defaults.
+ * User overrides take precedence over defaults.
+ *
+ * @param overrides - Custom rate limits to override defaults (type-safe for default endpoints).
+ * @returns Merged rate limit rules.
+ *
+ * @see https://www.better-auth.com/docs/concepts/rate-limit
+ *
+ * @example
+ * ```typescript
+ * // Use defaults
+ * defineEndpointRateLimits()
+ *
+ * // Override specific endpoint (type-safe)
+ * defineEndpointRateLimits({
+ *   "/send-verification-email": { window: 120, max: 5 },
+ * })
+ *
+ * // Add custom endpoint
+ * defineEndpointRateLimits({
+ *   "/custom-endpoint": { window: 30, max: 10 },
+ * })
+ * ```
+ */
+declare function defineEndpointRateLimits(overrides?: Partial<Record<DefaultRateLimitEndpoint, RateLimitRule>> & Record<string, RateLimitRule>): Record<string, RateLimitRule>;
+/**
+ * Defines Better Auth instance from neutral config + server dependencies.
+ */
+declare function defineAuth<T extends AuthConfig, TDb extends Record<"primary", Database> & Record<string, Database> = Record<"primary", Database> & Record<string, Database>>(opts: DefineAuthOptions<T, TDb>): ReturnType<typeof betterAuth> & {
+  auditLog?: AuditLogOptions<TDb>;
+  shouldAudit(tableName: QualifiedTableNames<TDb>): boolean;
+};
+/**
+ * The auth instance type.
+ */
+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 };