@better-auth/infra 0.3.7 → 0.4.1

package/dist/types-Ddk4r5x9.d.mts

@@ -0,0 +1,672 @@
+import { BetterAuthPlugin, GenericEndpointContext } from "better-auth";
+import { createFetch } from "@better-fetch/fetch";
+import { APIError as APIError$1, Endpoint, EndpointOptions } from "better-call";
+//#region src/identification.d.ts
+interface IPLocation {
+  lat: number;
+  lng: number;
+  city: string | null;
+  region: string | null;
+  postalCode: string | null;
+  country: {
+    code: string;
+    name: string;
+  } | null;
+  timezone: string | null;
+}
+interface Identification {
+  visitorId: string;
+  requestId: string;
+  timestamp: number;
+  url: string;
+  ip: string | null;
+  location: IPLocation | null;
+  browser: {
+    name: string | null;
+    version: string | null;
+    os: string | null;
+    osVersion: string | null;
+    device: string | null;
+    userAgent: string | null;
+  };
+  confidence: number;
+  incognito: boolean;
+  bot: "notDetected" | "detected" | "unknown";
+}
+//#endregion
+//#region src/sentinel/security.d.ts
+type SecurityAction = "log" | "block" | "challenge";
+interface ThresholdConfig {
+  challenge?: number;
+  block?: number;
+}
+interface SecurityOptions {
+  unknownDeviceNotification?: boolean;
+  credentialStuffing?: {
+    enabled: boolean;
+    action?: SecurityAction;
+    thresholds?: ThresholdConfig;
+    windowSeconds?: number;
+    cooldownSeconds?: number;
+  };
+  impossibleTravel?: {
+    enabled: boolean;
+    maxSpeedKmh?: number;
+    action?: SecurityAction;
+  };
+  geoBlocking?: {
+    allowList?: string[];
+    denyList?: string[];
+    action?: "block" | "challenge";
+  };
+  botBlocking?: boolean | {
+    action: SecurityAction;
+  };
+  suspiciousIpBlocking?: boolean | {
+    action: SecurityAction;
+  };
+  velocity?: {
+    enabled: boolean;
+    thresholds?: ThresholdConfig;
+    maxSignupsPerVisitor?: number;
+    maxPasswordResetsPerIp?: number;
+    maxSignInsPerIp?: number;
+    windowSeconds?: number;
+    action?: SecurityAction;
+  };
+  freeTrialAbuse?: {
+    enabled: boolean;
+    thresholds?: ThresholdConfig;
+    maxAccountsPerVisitor?: number;
+    action?: SecurityAction;
+  };
+  compromisedPassword?: {
+    enabled: boolean;
+    action?: SecurityAction;
+    minBreachCount?: number;
+  };
+  emailValidation?: {
+    enabled?: boolean;
+    strictness?: "low" | "medium" | "high";
+    action?: SecurityAction;
+    domainAllowlist?: string[];
+  };
+  emailNormalization?: {
+    enabled?: boolean;
+  };
+  staleUsers?: {
+    enabled: boolean;
+    staleDays?: number;
+    action?: SecurityAction;
+    notifyUser?: boolean;
+    notifyAdmin?: boolean;
+    adminEmail?: string;
+  };
+  challengeDifficulty?: number;
+}
+interface SecurityVerdict {
+  action: "allow" | "challenge" | "block";
+  challenge?: string;
+  reason?: string;
+  details?: Record<string, unknown>;
+  /** Set when the request included a valid, consumed PoW solution. */
+  powVerified?: boolean;
+}
+interface CredentialStuffingResult {
+  blocked: boolean;
+  challenged?: boolean;
+  challenge?: string;
+  reason?: string;
+  details?: Record<string, unknown>;
+}
+interface ImpossibleTravelResult {
+  isImpossible: boolean;
+  action?: "allow" | "challenge" | "block";
+  challenged?: boolean;
+  challenge?: string;
+  powVerified?: boolean;
+  distance?: number;
+  timeElapsedHours?: number;
+  speedRequired?: number;
+  from?: {
+    city: string | null;
+    country: string | null;
+  } | null;
+  to?: {
+    city: string | null;
+    country: string | null;
+  } | null;
+}
+interface CompromisedPasswordResult {
+  compromised: boolean;
+  breachCount?: number;
+  action?: SecurityAction;
+}
+interface StaleUserResult {
+  isStale: boolean;
+  daysSinceLastActive?: number;
+  staleDays?: number;
+  lastActiveAt?: string | null;
+  action?: SecurityAction;
+  notifyUser?: boolean;
+  notifyAdmin?: boolean;
+}
+interface SecurityEvent {
+  type: SecurityEventType;
+  timestamp: number;
+  userId: string | null;
+  visitorId: string | null;
+  ip: string | null;
+  country: string | null;
+  details: Record<string, unknown>;
+  action: "logged" | "blocked" | "challenged";
+}
+type SecurityEventType = "unknown_device" | "credential_stuffing" | "impossible_travel" | "geo_blocked" | "bot_blocked" | "suspicious_ip_detected" | "velocity_exceeded" | "free_trial_abuse" | "compromised_password" | "stale_account_reactivation";
+//#endregion
+//#region src/sentinel/sentinel.d.ts
+declare const sentinel: (options?: SentinelOptions) => {
+  id: "sentinel";
+  init(ctx: import("better-auth").AuthContext): {
+    options: {
+      emailValidation: {
+        enabled?: boolean;
+        strictness?: "low" | "medium" | "high";
+        action?: SecurityAction;
+        domainAllowlist?: string[];
+      } | undefined;
+      emailNormalization: {
+        enabled?: boolean;
+      } | undefined;
+      databaseHooks: {
+        user: {
+          create: {
+            before(user: {
+              id: string;
+              createdAt: Date;
+              updatedAt: Date;
+              email: string;
+              emailVerified: boolean;
+              name: string;
+              image?: string | null | undefined;
+            } & Record<string, unknown>, ctx: import("better-auth").GenericEndpointContext | null): Promise<{
+              data: {
+                email: string;
+                id: string;
+                createdAt: Date;
+                updatedAt: Date;
+                emailVerified: boolean;
+                name: string;
+                image?: string | null | undefined;
+              };
+            } | undefined>;
+            after(user: {
+              id: string;
+              createdAt: Date;
+              updatedAt: Date;
+              email: string;
+              emailVerified: boolean;
+              name: string;
+              image?: string | null | undefined;
+            } & Record<string, unknown>, ctx: import("better-auth").GenericEndpointContext | null): Promise<void>;
+          };
+          update: {
+            before(user: Partial<{
+              id: string;
+              createdAt: Date;
+              updatedAt: Date;
+              email: string;
+              emailVerified: boolean;
+              name: string;
+              image?: string | null | undefined;
+            }> & Record<string, unknown>, ctx: import("better-auth").GenericEndpointContext | null): Promise<{
+              data: {
+                email: string;
+                id?: string | undefined;
+                createdAt?: Date | undefined;
+                updatedAt?: Date | undefined;
+                emailVerified?: boolean | undefined;
+                name?: string | undefined;
+                image?: string | null | undefined;
+              };
+            } | undefined>;
+          };
+        };
+        session: {
+          create: {
+            before(session: {
+              id: string;
+              createdAt: Date;
+              updatedAt: Date;
+              userId: string;
+              expiresAt: Date;
+              token: string;
+              ipAddress?: string | null | undefined;
+              userAgent?: string | null | undefined;
+            } & Record<string, unknown>, ctx: import("better-auth").GenericEndpointContext | null): Promise<void>;
+            after(session: {
+              id: string;
+              createdAt: Date;
+              updatedAt: Date;
+              userId: string;
+              expiresAt: Date;
+              token: string;
+              ipAddress?: string | null | undefined;
+              userAgent?: string | null | undefined;
+            } & Record<string, unknown>, ctx: import("better-auth").GenericEndpointContext | null): Promise<void>;
+          };
+        };
+      };
+    };
+  };
+  hooks: {
+    before: ({
+      matcher: (context: Pick<import("better-auth").HookEndpointContext, "path">) => boolean;
+      handler: (inputContext: import("better-call").MiddlewareInputContext<import("better-call").MiddlewareOptions>) => Promise<{
+        context: {
+          method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+          path: string;
+          body: any;
+          query: Record<string, any> | undefined;
+          params: Record<string, any> & string;
+          request: Request | undefined;
+          headers: Headers | undefined;
+          setHeader: ((key: string, value: string) => void) & ((key: string, value: string) => void);
+          setStatus: (status: import("better-call").Status) => void;
+          getHeader: ((key: string) => string | null) & ((key: string) => string | null);
+          getCookie: (key: string, prefix?: import("better-call").CookiePrefixOptions) => string | null;
+          getSignedCookie: (key: string, secret: string, prefix?: import("better-call").CookiePrefixOptions) => Promise<string | null | false>;
+          setCookie: (key: string, value: string, options?: import("better-call").CookieOptions) => string;
+          setSignedCookie: (key: string, value: string, secret: string, options?: import("better-call").CookieOptions) => Promise<string>;
+          responseHeaders: Headers;
+          json: (<R extends Record<string, any> | null>(json: R, routerResponse?: {
+            status?: number;
+            headers?: Record<string, string>;
+            response?: Response;
+            body?: Record<string, string>;
+          } | Response) => Promise<R>) & (<R extends Record<string, any> | null>(json: R, routerResponse?: {
+            status?: number;
+            headers?: Record<string, string>;
+            response?: Response;
+          } | Response) => Promise<R>);
+          context: {
+            [x: string]: any;
+          } & {
+            returned?: unknown | undefined;
+            responseHeaders?: Headers | undefined;
+            getPlugin: <ID extends import("better-auth").BetterAuthPluginRegistryIdentifier | import("better-auth").LiteralString, PluginOptions extends never>(pluginId: ID) => (ID extends keyof import("better-auth").BetterAuthPluginRegistry<unknown, unknown> ? import("better-auth").BetterAuthPluginRegistry<import("better-auth").BetterAuthOptions, PluginOptions>[ID] extends {
+              creator: infer C;
+            } ? C extends ((...args: any[]) => infer R) ? R : never : never : BetterAuthPlugin) | null;
+            hasPlugin: <ID extends import("better-auth").BetterAuthPluginRegistryIdentifier | import("better-auth").LiteralString>(pluginId: ID) => ID extends never ? true : boolean;
+            appName: string;
+            baseURL: string;
+            version: string;
+            options: import("better-auth").BetterAuthOptions;
+            trustedOrigins: string[];
+            trustedProviders: string[];
+            isTrustedOrigin: (url: string, settings?: {
+              allowRelativePaths: boolean;
+            }) => boolean;
+            oauthConfig: {
+              skipStateCookieCheck?: boolean | undefined;
+              storeStateStrategy: "database" | "cookie";
+            };
+            newSession: {
+              session: {
+                id: string;
+                createdAt: Date;
+                updatedAt: Date;
+                userId: string;
+                expiresAt: Date;
+                token: string;
+                ipAddress?: string | null | undefined;
+                userAgent?: string | null | undefined;
+              } & Record<string, any>;
+              user: {
+                id: string;
+                createdAt: Date;
+                updatedAt: Date;
+                email: string;
+                emailVerified: boolean;
+                name: string;
+                image?: string | null | undefined;
+              } & Record<string, any>;
+            } | null;
+            session: {
+              session: {
+                id: string;
+                createdAt: Date;
+                updatedAt: Date;
+                userId: string;
+                expiresAt: Date;
+                token: string;
+                ipAddress?: string | null | undefined;
+                userAgent?: string | null | undefined;
+              } & Record<string, any>;
+              user: {
+                id: string;
+                createdAt: Date;
+                updatedAt: Date;
+                email: string;
+                emailVerified: boolean;
+                name: string;
+                image?: string | null | undefined;
+              } & Record<string, any>;
+            } | null;
+            setNewSession: (session: {
+              session: {
+                id: string;
+                createdAt: Date;
+                updatedAt: Date;
+                userId: string;
+                expiresAt: Date;
+                token: string;
+                ipAddress?: string | null | undefined;
+                userAgent?: string | null | undefined;
+              } & Record<string, any>;
+              user: {
+                id: string;
+                createdAt: Date;
+                updatedAt: Date;
+                email: string;
+                emailVerified: boolean;
+                name: string;
+                image?: string | null | undefined;
+              } & Record<string, any>;
+            } | null) => void;
+            socialProviders: import("better-auth").OAuthProvider[];
+            authCookies: import("better-auth").BetterAuthCookies;
+            logger: ReturnType<(options?: import("better-auth").Logger | undefined) => import("better-auth").InternalLogger>;
+            rateLimit: {
+              enabled: boolean;
+              window: number;
+              max: number;
+              storage: "memory" | "database" | "secondary-storage";
+            } & Omit<import("better-auth").BetterAuthRateLimitOptions, "enabled" | "window" | "max" | "storage">;
+            adapter: import("better-auth").DBAdapter<import("better-auth").BetterAuthOptions>;
+            internalAdapter: import("better-auth").InternalAdapter<import("better-auth").BetterAuthOptions>;
+            createAuthCookie: (cookieName: string, overrideAttributes?: Partial<import("better-call").CookieOptions> | undefined) => import("better-auth").BetterAuthCookie;
+            secret: string;
+            secretConfig: string | import("better-auth").SecretConfig;
+            sessionConfig: {
+              updateAge: number;
+              expiresIn: number;
+              freshAge: number;
+              cookieRefreshCache: false | {
+                enabled: true;
+                updateAge: number;
+              };
+            };
+            generateId: (options: {
+              model: import("better-auth").ModelNames;
+              size?: number | undefined;
+            }) => string | false;
+            secondaryStorage: import("better-auth").SecondaryStorage | undefined;
+            password: {
+              hash: (password: string) => Promise<string>;
+              verify: (data: {
+                password: string;
+                hash: string;
+              }) => Promise<boolean>;
+              config: {
+                minPasswordLength: number;
+                maxPasswordLength: number;
+              };
+              checkPassword: (userId: string, ctx: import("better-auth").GenericEndpointContext<import("better-auth").BetterAuthOptions>) => Promise<boolean>;
+            };
+            tables: import("better-auth").BetterAuthDBSchema;
+            runMigrations: () => Promise<void>;
+            publishTelemetry: (event: {
+              type: string;
+              anonymousId?: string | undefined;
+              payload: Record<string, any>;
+            }) => Promise<void>;
+            skipOriginCheck: boolean | string[];
+            skipCSRFCheck: boolean;
+            runInBackground: (promise: Promise<unknown>) => void;
+            runInBackgroundOrAwait: (promise: Promise<unknown> | void) => import("better-auth").Awaitable<unknown>;
+          };
+          redirect: (url: string) => import("better-call").APIError;
+          error: (status: ("OK" | "CREATED" | "ACCEPTED" | "NO_CONTENT" | "MULTIPLE_CHOICES" | "MOVED_PERMANENTLY" | "FOUND" | "SEE_OTHER" | "NOT_MODIFIED" | "TEMPORARY_REDIRECT" | "BAD_REQUEST" | "UNAUTHORIZED" | "PAYMENT_REQUIRED" | "FORBIDDEN" | "NOT_FOUND" | "METHOD_NOT_ALLOWED" | "NOT_ACCEPTABLE" | "PROXY_AUTHENTICATION_REQUIRED" | "REQUEST_TIMEOUT" | "CONFLICT" | "GONE" | "LENGTH_REQUIRED" | "PRECONDITION_FAILED" | "PAYLOAD_TOO_LARGE" | "URI_TOO_LONG" | "UNSUPPORTED_MEDIA_TYPE" | "RANGE_NOT_SATISFIABLE" | "EXPECTATION_FAILED" | "I'M_A_TEAPOT" | "MISDIRECTED_REQUEST" | "UNPROCESSABLE_ENTITY" | "LOCKED" | "FAILED_DEPENDENCY" | "TOO_EARLY" | "UPGRADE_REQUIRED" | "PRECONDITION_REQUIRED" | "TOO_MANY_REQUESTS" | "REQUEST_HEADER_FIELDS_TOO_LARGE" | "UNAVAILABLE_FOR_LEGAL_REASONS" | "INTERNAL_SERVER_ERROR" | "NOT_IMPLEMENTED" | "BAD_GATEWAY" | "SERVICE_UNAVAILABLE" | "GATEWAY_TIMEOUT" | "HTTP_VERSION_NOT_SUPPORTED" | "VARIANT_ALSO_NEGOTIATES" | "INSUFFICIENT_STORAGE" | "LOOP_DETECTED" | "NOT_EXTENDED" | "NETWORK_AUTHENTICATION_REQUIRED") | import("better-call").Status, body?: {
+            message?: string;
+            code?: string;
+          } & Record<string, any>, headers?: HeadersInit) => import("better-call").APIError;
+        };
+      } | undefined>;
+    } | {
+      matcher: (ctx: import("better-auth").HookEndpointContext) => boolean;
+      handler: (inputContext: import("better-call").MiddlewareInputContext<import("better-call").MiddlewareOptions>) => Promise<void>;
+    })[];
+    after: {
+      matcher: (ctx: import("better-auth").HookEndpointContext) => boolean;
+      handler: (inputContext: import("better-call").MiddlewareInputContext<import("better-call").MiddlewareOptions>) => Promise<void>;
+    }[];
+  };
+};
+//#endregion
+//#region src/types.d.ts
+/**
+ * Retry/backoff for identify HTTP calls.
+ */
+interface KvRetryOptions {
+  /**
+   * Max retry index after a thrown failure. `0` = single attempt.
+   * @default 2
+   */
+  attempts?: number;
+  /**
+   * Base delay (ms) before the first retry.
+   * @default 400
+   */
+  baseDelay?: number;
+  /**
+   * Cap for exponential retry delay (ms).
+   * @default 600
+   */
+  maxDelay?: number;
+}
+/**
+ * Resolved {@link KvRetryOptions} with defaults applied.
+ */
+type KvRetryOptionsResolved = Required<KvRetryOptions>;
+/**
+ * Dash API HTTP client options.
+ */
+interface ApiOptions {
+  /**
+   * Timeout for Dash API HTTP requests (milliseconds).
+   * @default 3000
+   */
+  timeout?: number;
+}
+/**
+ * Resolved {@link ApiOptions} with defaults applied.
+ */
+type ApiOptionsResolved = Required<ApiOptions>;
+/**
+ * KV HTTP client options.
+ */
+interface KvOptions {
+  /**
+   * Timeout for KV HTTP requests (milliseconds).
+   * @default 1000
+   */
+  timeout?: number;
+  /**
+   * Retry/backoff for KV identify lookups.
+   * @default { attempts: 2, baseDelay: 400, maxDelay: 600 }
+   */
+  retry?: KvRetryOptions;
+}
+/**
+ * Resolved {@link KvOptions} with defaults applied.
+ */
+interface KvOptionsResolved {
+  timeout: number;
+  retry: KvRetryOptionsResolved;
+}
+/**
+ * Shared connection options used by infra plugins.
+ */
+interface InfraPluginConnectionOptions {
+  /**
+   * The URL of the Better Auth Dash API
+   * @default "https://dash.better-auth.com"
+   */
+  apiUrl?: string;
+  /**
+   * The URL of the KV storage service
+   * @default "https://kv.better-auth.com"
+   */
+  kvUrl?: string;
+  /**
+   * Your Better Auth Dash API key
+   * @default process.env.BETTER_AUTH_API_KEY
+   */
+  apiKey?: string;
+  /**
+   * Dash API HTTP client options.
+   */
+  apiOptions?: ApiOptions;
+  /**
+   * KV HTTP client options.
+   */
+  kvOptions?: KvOptions;
+  /**
+   * Timeout for Dash API HTTP requests (milliseconds).
+   * @default 3000
+   * @deprecated Use `apiOptions.timeout` instead.
+   */
+  apiTimeout?: number;
+  /**
+   * Timeout for KV HTTP requests (milliseconds).
+   * @default 1000
+   * @deprecated Use `kvOptions.timeout` instead.
+   */
+  kvTimeout?: number;
+}
+/**
+ * Configuration options for the dash plugin.
+ */
+interface DashOptions extends InfraPluginConnectionOptions {
+  /**
+   * User activity tracking configuration
+   */
+  activityTracking?: {
+    /**
+     * Whether to enable user activity tracking
+     *
+     * This requires a database schema change to the user table.
+     * @default false
+     */
+    enabled?: boolean;
+    /**
+     * Interval in milliseconds to update lastActiveAt for active users
+     * Set to 0 to disable interval-based tracking
+     * @default 300000 (5 minutes)
+     */
+    updateInterval?: number;
+  };
+  /**
+   * Opt into the 1.7+ managed directory-sync control plane.
+   *
+   * Enable together with `scim({ managedConnections })` when the dashboard
+   * should reserve and manage SCIM connections. This does not replace or
+   * disable legacy pre-1.7 SCIM provider APIs.
+   */
+  managedDirectorySync?: {
+    /**
+     * Whether to enable managed directory-sync reservation tables/APIs.
+     *
+     * Adds `directorySyncConnection` and
+     * `directorySyncMembershipProvenance` via plugin schema.
+     * @default false
+     */
+    enabled?: boolean;
+    /**
+     * Install SSO `resolveUser` / `guardProviderMutation` for directory
+     * pairing. Required only when creating paired directories. Needs
+     * `sso({})` (or richer options) so callbacks can be installed.
+     * @default true
+     */
+    ssoPairing?: boolean;
+    /**
+     * SCIM → organization membership projection.
+     *
+     * When enabled, dash installs SCIM `projection.reconcileUser` so
+     * provisioned users are projected into organization memberships.
+     */
+    membershipProjection?: {
+      /**
+       * Whether to install membership projection.
+       * @default true
+       */
+      enabled?: boolean;
+      /**
+       * Role assigned when projection creates organization memberships.
+       * @default "member"
+       */
+      role?: string;
+    };
+  };
+}
+/**
+ * Configuration options for the sentinel plugin.
+ */
+interface SentinelOptions extends InfraPluginConnectionOptions {
+  /**
+   * Security features configuration
+   */
+  security?: SecurityOptions;
+}
+/**
+ * Internal connection options with required fields resolved.
+ */
+interface InfraPluginConnectionOptionsInternal extends Omit<InfraPluginConnectionOptions, "apiOptions" | "kvOptions" | "apiTimeout" | "kvTimeout"> {
+  apiUrl: string;
+  kvUrl: string;
+  apiKey: string;
+  apiOptions: ApiOptionsResolved;
+  kvOptions: KvOptionsResolved;
+}
+/**
+ * Internal options with required fields resolved
+ */
+interface DashOptionsInternal extends Omit<DashOptions, keyof InfraPluginConnectionOptions>, InfraPluginConnectionOptionsInternal {
+  /**
+   * Shared Dash HTTP client from {@link createAPI}; injected by {@link dash} when wiring endpoints.
+   *
+   * @internal
+   */
+  $api: ReturnType<typeof import("@better-fetch/fetch").createFetch>;
+}
+/**
+ * Resolved dash options from {@link resolveDashOptions} / plugin-stored config; excludes injected `$api`.
+ */
+type DashOptionsResolved = Omit<DashOptionsInternal, "$api">;
+/**
+ * Internal sentinel options with required fields resolved.
+ */
+interface SentinelOptionsInternal extends Omit<SentinelOptions, keyof InfraPluginConnectionOptions>, InfraPluginConnectionOptionsInternal {}
+/**
+ * Location/geo data used across events, audit logs, and request context.
+ */
+interface LocationData {
+  ipAddress?: string | null;
+  city?: string | null;
+  country?: string | null;
+  countryCode?: string | null;
+}
+/** @deprecated Use LocationData instead */
+type LocationDataContext = LocationData;
+type InfraEndpointContext = (GenericEndpointContext & {
+  context: {
+    identification?: Identification | null | undefined;
+    visitorId: string | null;
+    requestId: string | null;
+    ip: string | null;
+    untrustedVisitorId: string | null;
+    location: LocationData | undefined;
+  };
+}) | undefined;
+//#endregion
+export { ImpossibleTravelResult as C, SecurityVerdict as D, SecurityOptions as E, StaleUserResult as O, CredentialStuffingResult as S, SecurityEventType as T, LocationDataContext as _, DashOptionsInternal as a, sentinel as b, EndpointOptions as c, InfraPluginConnectionOptionsInternal as d, KvOptions as f, LocationData as g, KvRetryOptionsResolved as h, DashOptions as i, ThresholdConfig as k, InfraEndpointContext as l, KvRetryOptions as m, ApiOptions as n, DashOptionsResolved as o, KvOptionsResolved as p, ApiOptionsResolved as r, Endpoint as s, APIError$1 as t, InfraPluginConnectionOptions as u, SentinelOptions as v, SecurityEvent as w, CompromisedPasswordResult as x, SentinelOptionsInternal as y };