@arkstack/auth 0.5.2 → 0.5.3

package/dist/index.d.ts

@@ -1,85 +1,321 @@
 /// <reference path="./app.d.ts" />
 import { Exception } from "@arkstack/common";
-import { Request, RequestSource, Response, ResponseSource } from "@arkstack/http";
+import { Request, RequestSource, Response, ResponseSource, Session } from "@arkstack/http";
+import * as _$otpauth from "otpauth";
 import { Model } from "@arkstack/database";
+import { User as User$1 } from "@app/models/User";
 
 //#region src/Contracts/PersonalAccessToken.d.ts
 declare abstract class PersonalAccessToken extends Model {
-  id: number;
+  [key: string]: any;
   name: string;
   token: string;
   abilities: string[];
-  userId: number;
+  userId: never;
   createdAt: Date;
   expiresAt: Date | null;
   lastUsedAt: Date | null;
   deviceInfo: Record<string, unknown> | null;
 }
 //#endregion
-//#region src/CurrentSession.d.ts
-declare class CurrentSession {
+//#region src/AuthSession.d.ts
+/**
+ * Represents an authenticated user session.
+ *
+ * @author 3m1n3nc3
+ */
+declare class AuthSession extends Session {
   private auth;
-  constructor(auth: AuthContract);
-  destroy(): Promise<void>;
+  constructor(auth: AuthContract, current?: Session | undefined);
+  /**
+   * Destroy the current session
+   *
+   * @returns
+   */
+  destroy(): Promise<this>;
+  /**
+   * Get the current auth session token
+   *
+   * @returns
+   */
   token(): Promise<PersonalAccessToken | null>;
 }
 //#endregion
-//#region src/Contracts/User.d.ts
-declare abstract class User extends Model {
-  id: number;
-  email: string;
-  name: string;
-  password: string;
-  createdAt: Date;
-  updatedAt: Date;
-  protected static table?: string | undefined;
-}
-//#endregion
 //#region src/Contracts/AuthContract.d.ts
+/**
+ * The Auth class provides methods for user authentication, including verifying
+ * credentials, logging in, logging out, and managing personal access tokens.
+ *
+ * @author Legacy (3m1n3nc3)
+ */
 declare abstract class AuthContract {
-  abstract setRequest(req: Request<User> | RequestSource<User>): this;
-  abstract getRequest(): Request<User> | undefined;
-  abstract user(): User | null;
+  /**
+   * Set the current HTTP request instance being processed.
+   *
+   * @param req   The HTTP request instance to be set.
+   * @returns     The Auth instance itself for method chaining.
+   */
+  abstract setRequest(req: Request<User$1> | RequestSource<User$1>): this;
+  /**
+   * Get the current HTTP request instance being processed, which may contain
+   * user information and other request-specific data relevant to authentication operations.
+   *
+   * @returns The current HTTP request instance or undefined if not set.
+   */
+  abstract getRequest(): Request<User$1> | undefined;
+  /**
+   * Get the currently authenticated user
+   *
+   * @returns The currently authenticated user or null if not authenticated.
+   */
+  abstract user(): User$1 | null;
+  /**
+   * Verify user credentials
+   *
+   * @param email     The email address of the user.
+   * @param password  The password of the user.
+   * @returns         A boolean indicating whether the credentials are valid.
+   */
   abstract verify(email: string, password: string): Promise<boolean>;
-  abstract attempt(email: string, password: string): Promise<User>;
+  /**
+   * Attempt to authenticate a user with the given email and password.
+   *
+   * @param email
+   * @param password
+   * @returns
+   */
+  abstract attempt(email: string, password: string): Promise<User$1>;
+  /**
+   * Login a user and create a personal access token
+   *
+   * @param email
+   * @param password
+   * @returns
+   */
   abstract login(email: string, password: string): Promise<PersonalAccessToken>;
-  abstract createTemporaryToken(user: User, purpose: string, expiresIn?: string): Promise<string>;
-  abstract authorizeTemporaryToken(token: string, purpose: string): Promise<User>;
+  /**
+   * Create a temporary token for a user with a specific purpose, such as
+   * two-factor authentication.
+   *
+   * @param user
+   * @param purpose
+   * @param expiresIn
+   * @returns
+   */
+  abstract createTemporaryToken(user: User$1, purpose: string, expiresIn?: string): Promise<string>;
+  /**
+   * Authorize a temporary token and return the associated user if the token is
+   * valid and matches the expected purpose.
+   *
+   * @param token
+   * @param purpose
+   * @returns
+   */
+  abstract authorizeTemporaryToken(token: string, purpose: string): Promise<User$1>;
+  /**
+   * Logout the currently authenticated user and delete all their personal access tokens
+   *
+   * @param token
+   * @returns
+   */
   abstract logout(token?: string | PersonalAccessToken): Promise<void>;
+  /**
+   * Check if the user is authenticated
+   *
+   * @returns
+   */
   abstract check(): Promise<boolean>;
-  abstract currentSession(): CurrentSession;
-  abstract create(user: User): Promise<PersonalAccessToken>;
-  abstract authorizeToken(token: string): Promise<User>;
+  /**
+   * Get the current session's personal access token
+   *
+   * @returns
+   */
+  abstract session(): AuthSession;
+  /**
+   * Create a personal access token for a user
+   *
+   * @param user
+   * @returns
+   */
+  abstract create(user: User$1): Promise<PersonalAccessToken>;
+  /**
+   * Authorize a token and return the associated user
+   *
+   * @param token
+   * @returns
+   */
+  abstract authorizeToken(token: string): Promise<User$1>;
 }
 //#endregion
 //#region src/Auth.d.ts
+/**
+ * The Auth class provides methods for user authentication, including verifying
+ * credentials, logging in, logging out, and managing personal access tokens.
+ *
+ * @author Legacy (3m1n3nc3)
+ */
 declare class Auth extends AuthContract {
   #private;
-  protected static req?: Request<User>;
+  protected static req?: Request<User$1>;
   private configuredSecret?;
-  constructor(secret?: string, req?: Request<User> | RequestSource<User>);
+  constructor(secret?: string, req?: Request<User$1> | RequestSource<User$1>);
+  /**
+   * Create a new instance of the Auth class with an optional secret for JWT
+   * signing and verification.
+   *
+   * @param secret    The secret key used for signing and verifying JWTs.
+   * @returns         A new instance of the Auth class.
+   */
   static make(secret?: string): Auth;
-  static setRequest(req: Request<User> | RequestSource<User>): typeof Auth;
-  setRequest(req: Request<User> | RequestSource<User>): this;
-  getRequest(): Request<User> | undefined;
-  user(): User | null;
+  /**
+   * Set the current HTTP request instance being processed.
+   *
+   * @param req   The HTTP request instance to be set.
+   * @returns     The Auth class itself for method chaining.
+   */
+  static setRequest(req: Request<User$1> | RequestSource<User$1>): typeof Auth;
+  /**
+   * Set the current HTTP request instance being processed.
+   *
+   * @param req   The HTTP request instance to be set.
+   * @returns     The Auth instance itself for method chaining.
+   */
+  setRequest(req: Request<User$1> | RequestSource<User$1>): this;
+  /**
+   * Get the current HTTP request instance being processed, which may contain
+   * user information and other request-specific data relevant to authentication operations.
+   *
+   * @returns The current HTTP request instance or undefined if not set.
+   */
+  getRequest(): Request<User$1> | undefined;
+  /**
+   * Get the currently authenticated user
+   *
+   * @returns The currently authenticated user or null if not authenticated.
+   */
+  user(): User$1 | null;
+  /**
+   * Verify user credentials
+   *
+   * @param email     The email address of the user.
+   * @param password  The password of the user.
+   * @returns         A boolean indicating whether the credentials are valid.
+   */
   verify(email: string, password: string): Promise<boolean>;
-  attempt(email: string, password: string): Promise<User>;
+  /**
+   * Attempt to authenticate a user with the given email and password.
+   *
+   * @param email
+   * @param password
+   * @returns
+   */
+  attempt(email: string, password: string): Promise<User$1>;
+  /**
+   * Login a user and create a personal access token
+   *
+   * @param email
+   * @param password
+   * @returns
+   */
   login(email: string, password: string): Promise<PersonalAccessToken>;
-  createTemporaryToken(user: User, purpose: string, expiresIn?: string): Promise<string>;
-  authorizeTemporaryToken(token: string, purpose: string): Promise<User>;
+  /**
+   * Create a temporary token for a user with a specific purpose, such as
+   * two-factor authentication.
+   *
+   * @param user
+   * @param purpose
+   * @param expiresIn
+   * @returns
+   */
+  createTemporaryToken(user: User$1, purpose: string, expiresIn?: string): Promise<string>;
+  /**
+   * Authorize a temporary token and return the associated user if the token is
+   * valid and matches the expected purpose.
+   *
+   * @param token
+   * @param purpose
+   * @returns
+   */
+  authorizeTemporaryToken(token: string, purpose: string): Promise<User$1>;
+  /**
+   * Logout the currently authenticated user and delete all their personal access tokens
+   *
+   * @param token
+   * @returns
+   */
   logout(token?: string | PersonalAccessToken): Promise<void>;
+  /**
+   * Check if the user is authenticated
+   *
+   * @returns
+   */
   check(): Promise<boolean>;
-  currentSession(): CurrentSession;
-  create(user: User): Promise<PersonalAccessToken>;
+  /**
+   * Get the current session's personal access token
+   *
+   * @returns
+   */
+  session(): AuthSession;
+  /**
+   * Create a personal access token for a user
+   *
+   * @param user
+   * @returns
+   */
+  create(user: User$1): Promise<PersonalAccessToken>;
+  /**
+   * Create or replace the personal access token for the same user and device
+   * while keeping a single active session record for that device.
+   *
+   * @param user The authenticated user.
+   * @param token The new bearer token to persist.
+   * @param deviceInfo The current request's device information.
+   */
   private upsertDeviceToken;
-  authorizeToken(token: string): Promise<User>;
+  /**
+   * Authorize a token and return the associated user
+   *
+   * @param token
+   * @returns
+   */
+  authorizeToken(token: string): Promise<User$1>;
+  /**
+   * Create a JWT token
+   *
+   * @param payload
+   * @returns
+   */
   private createJWT;
+  /**
+   * Verify a JWT token
+   *
+   * @param token
+   * @returns
+   */
   private verifyJWT;
   private getSecret;
+  private setAuthenticated;
+  /**
+   * Update the last used timestamp and device information of a personal
+   * access token to keep the session active and reflect the latest device details.
+   *
+   * @param pat The personal access token to update.
+   * @returns A promise that resolves when the update is complete.
+   */
   private touchSession;
 }
 //#endregion
+//#region src/utils.d.ts
+/**
+ * Create a new instance of the Auth class with an optional secret for JWT
+ * signing and verification.
+ *
+ * @param secret — The secret key used for signing and verifying JWTs.
+ *
+ * @returns — A new instance of the Auth class.
+ */
+declare const auth: (secret?: string | undefined) => Auth;
+//#endregion
 //#region src/types/Session.d.ts
 interface SessionDeviceInfo extends Record<string, unknown> {
   browser: string | null;
@@ -93,7 +329,7 @@ interface SessionDeviceInfo extends Record<string, unknown> {
   ipAddress: string | null;
   userAgent: string | null;
 }
-type AuthAgentPayload = {
+type DeviceAgentPayload = {
   deviceName?: string;
   manufacturer?: string;
   model?: string;
@@ -106,398 +342,268 @@ type AuthAgentPayload = {
 //#region src/SessionDevice.d.ts
 declare class SessionDevice {
   private static readonly uniqueIdentityFields;
+  /**
+   * Extracts device information from the incoming request to build a SessionDeviceInfo object.
+   *
+   * @param req The incoming HTTP request object.
+   * @returns A SessionDeviceInfo object containing information about the client's device.
+   */
   static fromRequest(req?: Request): SessionDeviceInfo;
+  /**
+   * Generates a human-readable display name for the device based on available information.
+   *
+   * @param deviceInfo A record containing device information.
+   * @returns A string representing the display name of the device.
+   */
   static getDisplayName(deviceInfo?: Record<string, unknown> | null): string;
+  /**
+   * Builds a stable device key for matching previously issued sessions to the
+   * current request device.
+   *
+   * @param deviceInfo A record containing device information.
+   * @returns A normalized device key or null when there is not enough signal.
+   */
   static getUniqueKey(deviceInfo?: Record<string, unknown> | null): string | null;
+  /**
+   * Determines whether two device payloads represent the same device.
+   *
+   * @param left The first device payload.
+   * @param right The second device payload.
+   * @returns True when both payloads resolve to the same device key.
+   */
   static matches(left?: Record<string, unknown> | null, right?: Record<string, unknown> | null): boolean;
-  private static readUserAgent;
-  private static readString;
-  private static readAuthAgent;
-  private static normalizeDeviceType;
-  private static detectIpAddress;
-  private static detectBrowser;
-  private static detectOs;
-  private static detectDeviceType;
-}
-//#endregion
-//#region ../../node_modules/.pnpm/otpauth@9.5.1/node_modules/otpauth/dist/otpauth.d.ts
-/**
- * OTP secret key.
- */
-declare class Secret {
   /**
-   * Converts a Latin-1 string to a Secret object.
-   * @param {string} str Latin-1 string.
-   * @returns {Secret} Secret object.
+   * Safely reads the user agent string from the request headers.
+   *
+   * @param req
+   * @returns
    */
-  static fromLatin1(str: string): Secret;
+  private static readUserAgent;
   /**
-   * Converts an UTF-8 string to a Secret object.
-   * @param {string} str UTF-8 string.
-   * @returns {Secret} Secret object.
+   * Safely reads a string value, ensuring it's a non-empty string or returns null.
+   *
+   * @param value
+   * @returns
    */
-  static fromUTF8(str: string): Secret;
+  private static readString;
   /**
-   * Converts a base32 string to a Secret object.
-   * @param {string} str Base32 string.
-   * @returns {Secret} Secret object.
+   * Reads a specific device-related header from the request
+   *
+   * @param req
+   * @param headerName
+   * @returns
    */
-  static fromBase32(str: string): Secret;
+  private static readDeviceAgent;
+  private static normalizeDeviceType;
   /**
-   * Converts a hexadecimal string to a Secret object.
-   * @param {string} str Hexadecimal string.
-   * @returns {Secret} Secret object.
+   * Detects the client's IP address from the request, considering common headers set by proxies.
+   *
+   * @param req
+   * @returns
    */
-  static fromHex(str: string): Secret;
+  private static detectIpAddress;
   /**
-   * Creates a secret key object.
-   * @param {Object} [config] Configuration options.
-   * @param {ArrayBufferLike} [config.buffer] Secret key buffer.
-   * @param {number} [config.size=20] Number of random bytes to generate, ignored if 'buffer' is provided.
+   * Detects the browser from the user agent string.
+   *
+   * @param userAgent
+   * @returns
    */
-  constructor({
-    buffer,
-    size
-  }?: {
-    buffer?: ArrayBufferLike | undefined;
-    size?: number | undefined;
-  });
+  private static detectBrowser;
   /**
-   * Secret key.
-   * @type {Uint8Array}
-   * @readonly
+   * Detects the operating system from the user agent string.
+   *
+   * @param userAgent
+   * @returns
    */
-  readonly bytes: Uint8Array;
+  private static detectOs;
   /**
-   * Secret key buffer.
-   * @deprecated For backward compatibility, the "bytes" property should be used instead.
-   * @type {ArrayBufferLike}
+   * Detects the device type from the user agent string.
+   *
+   * @param userAgent
+   * @returns
    */
-  get buffer(): ArrayBufferLike;
+  private static detectDeviceType;
+}
+//#endregion
+//#region src/types/TwoFactor.d.ts
+type TwoFactorMethod = 'authenticator' | 'sms';
+type SmsCodePurpose = 'setup' | 'login';
+type TwoFactorSetup = {
+  secret: string;
+  otpauthUrl: string;
+};
+type TwoFactorStatus = {
+  enabled: boolean;
+  enabledAt: string | null;
+  method: TwoFactorMethod | null;
+  recoveryCodesRemaining: number;
+};
+type IssuedSmsCode = {
+  code: string;
+  expiresAt: Date;
+  purpose: SmsCodePurpose;
+};
+//#endregion
+//#region src/TwoFactor.d.ts
+declare class TwoFactor {
+  static smsCodeTtlMinutes: number;
+  private static getModel;
+  private static getRecord;
+  private static upsert;
+  static normalizeMethod(method?: string | null): TwoFactorMethod | null;
+  static maskPhone(phone?: string | null): string | null;
   /**
-   * Latin-1 string representation of secret key.
-   * @type {string}
+   * Build the account label used inside the OTP URI.
+   *
+   * @param user
+   * @returns
    */
-  get latin1(): string;
+  static getLabel(user: User$1): string;
   /**
-   * UTF-8 string representation of secret key.
-   * @type {string}
+   * Create the per-user TOTP instance for setup and verification.
+   *
+   * @param user
+   * @param secret
+   * @returns
    */
-  get utf8(): string;
+  static getTotp(user: User$1, secret: string): _$otpauth.TOTP;
   /**
-   * Base32 string representation of secret key.
-   * @type {string}
+   * Generate a new shared secret for authenticator-based 2FA.
+   *
+   * @returns The generated secret in base32 format.
    */
-  get base32(): string;
+  static generateSecret(size?: number): string;
   /**
-   * Hexadecimal string representation of secret key.
-   * @type {string}
+   * Build the setup payload returned to the client.
+   *
+   * @param user The user for whom the setup is being created.
+   * @param secret Optional existing secret to use for the setup.
+   * @returns An object containing the secret and the OTPAuth URL.
    */
-  get hex(): string;
-}
-/**
- * HOTP: An HMAC-based One-time Password Algorithm.
- * @see [RFC 4226](https://datatracker.ietf.org/doc/html/rfc4226)
- */
-/**
- * TOTP: Time-Based One-Time Password Algorithm.
- * @see [RFC 6238](https://datatracker.ietf.org/doc/html/rfc6238)
- */
-declare class TOTP {
-  /**
-   * Default configuration.
-   * @type {{
-   *   issuer: string,
-   *   label: string,
-   *   issuerInLabel: boolean,
-   *   algorithm: string,
-   *   digits: number,
-   *   period: number
-   *   window: number
-   * }}
-   */
-  static get defaults(): {
-    issuer: string;
-    label: string;
-    issuerInLabel: boolean;
-    algorithm: string;
-    digits: number;
-    period: number;
-    window: number;
-  };
+  static createSetup(user: User$1, secret?: string): TwoFactorSetup;
   /**
-   * Calculates the counter. i.e. the number of periods since timestamp 0.
-   * @param {Object} [config] Configuration options.
-   * @param {number} [config.period=30] Token time-step duration.
-   * @param {number} [config.timestamp=Date.now] Timestamp value in milliseconds.
-   * @returns {number} Counter.
-   */
-  static counter({
-    period,
-    timestamp
-  }?: {
-    period?: number | undefined;
-    timestamp?: number | undefined;
-  }): number;
-  /**
-   * Calculates the remaining time in milliseconds until the next token is generated.
-   * @param {Object} [config] Configuration options.
-   * @param {number} [config.period=30] Token time-step duration.
-   * @param {number} [config.timestamp=Date.now] Timestamp value in milliseconds.
-   * @returns {number} counter.
-   */
-  static remaining({
-    period,
-    timestamp
-  }?: {
-    period?: number | undefined;
-    timestamp?: number | undefined;
-  }): number;
-  /**
-   * Generates a TOTP token.
-   * @param {Object} config Configuration options.
-   * @param {Secret} config.secret Secret key.
-   * @param {string} [config.algorithm='SHA1'] HMAC hashing algorithm.
-   * @param {number} [config.digits=6] Token length.
-   * @param {number} [config.period=30] Token time-step duration.
-   * @param {number} [config.timestamp=Date.now] Timestamp value in milliseconds.
-   * @param {(algorithm: string, key: Uint8Array, message: Uint8Array) => Uint8Array} [config.hmac] Custom HMAC function.
-   * @returns {string} Token.
-   */
-  static generate({
-    secret,
-    algorithm,
-    digits,
-    period,
-    timestamp,
-    hmac
-  }: {
-    secret: Secret;
-    algorithm?: string | undefined;
-    digits?: number | undefined;
-    period?: number | undefined;
-    timestamp?: number | undefined;
-    hmac?: ((algorithm: string, key: Uint8Array, message: Uint8Array) => Uint8Array) | undefined;
-  }): string;
-  /**
-   * Validates a TOTP token.
-   * @param {Object} config Configuration options.
-   * @param {string} config.token Token value.
-   * @param {Secret} config.secret Secret key.
-   * @param {string} [config.algorithm='SHA1'] HMAC hashing algorithm.
-   * @param {number} [config.digits=6] Token length.
-   * @param {number} [config.period=30] Token time-step duration.
-   * @param {number} [config.timestamp=Date.now] Timestamp value in milliseconds.
-   * @param {number} [config.window=1] Window of counter values to test.
-   * @param {(algorithm: string, key: Uint8Array, message: Uint8Array) => Uint8Array} [config.hmac] Custom HMAC function.
-   * @returns {number|null} Token delta or null if it is not found in the search window, in which case it should be considered invalid.
-   */
-  static validate({
-    token,
-    secret,
-    algorithm,
-    digits,
-    period,
-    timestamp,
-    window,
-    hmac
-  }: {
-    token: string;
-    secret: Secret;
-    algorithm?: string | undefined;
-    digits?: number | undefined;
-    period?: number | undefined;
-    timestamp?: number | undefined;
-    window?: number | undefined;
-    hmac?: ((algorithm: string, key: Uint8Array, message: Uint8Array) => Uint8Array) | undefined;
-  }): number | null;
-  /**
-   * Creates a TOTP object.
-   * @param {Object} [config] Configuration options.
-   * @param {string} [config.issuer=''] Account provider.
-   * @param {string} [config.label='OTPAuth'] Account label.
-   * @param {boolean} [config.issuerInLabel=true] Include issuer prefix in label.
-   * @param {Secret|string} [config.secret=Secret] Secret key.
-   * @param {string} [config.algorithm='SHA1'] HMAC hashing algorithm.
-   * @param {number} [config.digits=6] Token length.
-   * @param {number} [config.period=30] Token time-step duration.
-   * @param {(algorithm: string, key: Uint8Array, message: Uint8Array) => Uint8Array} [config.hmac] Custom HMAC function.
-   */
-  constructor({
-    issuer,
-    label,
-    issuerInLabel,
-    secret,
-    algorithm,
-    digits,
-    period,
-    hmac
-  }?: {
-    issuer?: string | undefined;
-    label?: string | undefined;
-    issuerInLabel?: boolean | undefined;
-    secret?: string | Secret | undefined;
-    algorithm?: string | undefined;
-    digits?: number | undefined;
-    period?: number | undefined;
-    hmac?: ((algorithm: string, key: Uint8Array, message: Uint8Array) => Uint8Array) | undefined;
-  });
+   * Verify a 6-digit authenticator code for a user.
+   *
+   * @param user The user for whom the code is being verified.
+   * @param secret The secret used to generate the code.
+   * @param code The 6-digit code to verify.
+   * @returns  True if the code is valid, false otherwise.
+   */
+  static verifyCode(user: User$1, secret: string, code: string): boolean;
+  static getMethod(userId: User$1['id']): Promise<TwoFactorMethod | null>;
+  static setMethod(userId: User$1['id'], method: TwoFactorMethod): Promise<void>;
   /**
-   * Account provider.
-   * @type {string}
+   * Read the setup secret stored for a user.
+   *
+   * @param userId The ID of the user.
+   * @returns The stored secret, or null if not found.
    */
-  issuer: string;
+  static getSecret(userId: User$1['id']): Promise<string | null>;
   /**
-   * Account label.
-   * @type {string}
+   * Store the setup secret for a user.
+   *
+   * @param userId The ID of the user.
+   * @param secret The secret to store.
    */
-  label: string;
+  static setSecret(userId: User$1['id'], secret: string): Promise<void>;
+  static clearSecret(userId: User$1['id']): Promise<void>;
   /**
-   * Include issuer prefix in label.
-   * @type {boolean}
+   * Read the timestamp indicating whether 2FA is enabled.
+   *
+   * @param userId The ID of the user.
+   * @returns The timestamp when 2FA was enabled, or null if not enabled.
    */
-  issuerInLabel: boolean;
+  static getEnabledAt(userId: User$1['id']): Promise<string | null>;
   /**
-   * Secret key.
-   * @type {Secret}
+   * Persist the timestamp marking 2FA as enabled.
+   *
+   * @param userId The ID of the user.
+   * @param enabledAt The timestamp to store.
    */
-  secret: Secret;
+  static setEnabledAt(userId: User$1['id'], enabledAt?: string | Date): Promise<void>;
   /**
-   * HMAC hashing algorithm.
-   * @type {string}
+   * Remove all persisted 2FA state for a user.
+   *
+   * @param userId The ID of the user.
    */
-  algorithm: string;
+  static clear(userId: User$1['id']): Promise<void>;
   /**
-   * Token length.
-   * @type {number}
+   * Generate one-time recovery codes shown when 2FA is enabled.
+   *
+   * @returns An array of recovery codes.
    */
-  digits: number;
+  static generateBackupCodes(count?: number): string[];
   /**
-   * Token time-step duration.
-   * @type {number}
+   * Hash recovery codes before persisting them.
+   *
+   * @param codes An array of recovery codes to hash.
+   * @returns An array of hashed recovery codes.
    */
-  period: number;
+  static hashBackupCodes(codes: string[]): Promise<string[]>;
   /**
-   * Custom HMAC function.
-   * @type {((algorithm: string, key: Uint8Array, message: Uint8Array) => Uint8Array)|undefined}
+   * Read stored recovery-code hashes for a user.
+   *
+   * @param userId The ID of the user.
+   * @returns An array of recovery-code hashes.
    */
-  hmac: ((algorithm: string, key: Uint8Array, message: Uint8Array) => Uint8Array) | undefined;
+  static readRecoveryCodeHashes(userId: User$1['id']): Promise<string[]>;
   /**
-   * Calculates the counter. i.e. the number of periods since timestamp 0.
-   * @param {Object} [config] Configuration options.
-   * @param {number} [config.timestamp=Date.now] Timestamp value in milliseconds.
-   * @returns {number} Counter.
+   * Persist recovery-code hashes on the user's dedicated 2FA record.
+   *
+   * @param userId
+   * @param hashes
    */
-  counter({
-    timestamp
-  }?: {
-    timestamp?: number | undefined;
-  }): number;
+  static writeRecoveryCodeHashes(userId: User$1['id'], hashes: string[]): Promise<void>;
   /**
-   * Calculates the remaining time in milliseconds until the next token is generated.
-   * @param {Object} [config] Configuration options.
-   * @param {number} [config.timestamp=Date.now] Timestamp value in milliseconds.
-   * @returns {number} counter.
+   * Consume a valid recovery code and invalidate it immediately.
+   *
+   * @param userId The ID of the user.
+   * @param recoveryCode The recovery code to consume.
+   * @returns True if the recovery code was valid and consumed, false otherwise.
    */
-  remaining({
-    timestamp
-  }?: {
-    timestamp?: number | undefined;
-  }): number;
+  static consumeRecoveryCode(userId: User$1['id'], recoveryCode: string): Promise<boolean>;
   /**
-   * Generates a TOTP token.
-   * @param {Object} [config] Configuration options.
-   * @param {number} [config.timestamp=Date.now] Timestamp value in milliseconds.
-   * @returns {string} Token.
+   * Return the public 2FA status payload for a user.
+   *
+   * @param userId The ID of the user.
+   * @returns An object containing the 2FA status and recovery codes remaining.
    */
-  generate({
-    timestamp
-  }?: {
-    timestamp?: number | undefined;
-  }): string;
+  static readStatus(userId: User$1['id']): Promise<TwoFactorStatus>;
+  static createSmsCode(): string;
   /**
-   * Validates a TOTP token.
-   * @param {Object} config Configuration options.
-   * @param {string} config.token Token value.
-   * @param {number} [config.timestamp=Date.now] Timestamp value in milliseconds.
-   * @param {number} [config.window=1] Window of counter values to test.
-   * @returns {number|null} Token delta or null if it is not found in the search window, in which case it should be considered invalid.
+   * Issue a new SMS code for the given user and send it via SMS for the specified purpose.
+   *
+   * @param user
+   * @param purpose
    */
-  validate({
-    token,
-    timestamp,
-    window
-  }: {
-    token: string;
-    timestamp?: number | undefined;
-    window?: number | undefined;
-  }): number | null;
+  static issueSmsCode(user: User$1, purpose: SmsCodePurpose): Promise<IssuedSmsCode>;
+  static clearSmsCode(userId: User$1['id']): Promise<void>;
   /**
-   * Returns a Google Authenticator key URI.
-   * @returns {string} URI.
+   * Verify a submitted SMS code for a user and purpose, consuming the code if valid.
+   *
+   * @param userId
+   * @param code
+   * @param purpose
+   * @returns
    */
-  toString(): string;
+  static verifySmsCode(userId: User$1['id'], code: string, purpose: SmsCodePurpose): Promise<boolean>;
 }
-/**
- * HOTP/TOTP object/string conversion.
- * @see [Key URI Format](https://github.com/google/google-authenticator/wiki/Key-Uri-Format)
- */
-//#endregion
-//#region src/types/TwoFactor.d.ts
-type TwoFactorMethod = 'authenticator' | 'sms';
-type SmsCodePurpose = 'setup' | 'login';
-type TwoFactorSetup = {
-  secret: string;
-  otpauthUrl: string;
-};
-type TwoFactorStatus = {
-  enabled: boolean;
-  enabledAt: string | null;
-  method: TwoFactorMethod | null;
-  recoveryCodesRemaining: number;
-};
-type IssuedSmsCode = {
-  code: string;
-  expiresAt: Date;
-  purpose: SmsCodePurpose;
-};
 //#endregion
-//#region src/TwoFactor.d.ts
-declare class TwoFactor {
-  private static getModel;
-  private static getRecord;
-  private static upsert;
-  static normalizeMethod(method?: string | null): TwoFactorMethod | null;
-  static maskPhone(phone?: string | null): string | null;
-  static getLabel(user: User): string;
-  static getTotp(user: User, secret: string): TOTP;
-  static generateSecret(size?: number): string;
-  static createSetup(user: User, secret?: string): TwoFactorSetup;
-  static verifyCode(user: User, secret: string, code: string): boolean;
-  static getMethod(userId: User['id']): Promise<TwoFactorMethod | null>;
-  static setMethod(userId: User['id'], method: TwoFactorMethod): Promise<void>;
-  static getSecret(userId: User['id']): Promise<string | null>;
-  static setSecret(userId: User['id'], secret: string): Promise<void>;
-  static clearSecret(userId: User['id']): Promise<void>;
-  static getEnabledAt(userId: User['id']): Promise<string | null>;
-  static setEnabledAt(userId: User['id'], enabledAt?: string | Date): Promise<void>;
-  static clear(userId: User['id']): Promise<void>;
-  static generateBackupCodes(count?: number): string[];
-  static hashBackupCodes(codes: string[]): Promise<string[]>;
-  static readRecoveryCodeHashes(userId: User['id']): Promise<string[]>;
-  static writeRecoveryCodeHashes(userId: User['id'], hashes: string[]): Promise<void>;
-  static consumeRecoveryCode(userId: User['id'], recoveryCode: string): Promise<boolean>;
-  static readStatus(userId: User['id']): Promise<TwoFactorStatus>;
-  static createSmsCode(): string;
-  static issueSmsCode(user: User, purpose: SmsCodePurpose): Promise<IssuedSmsCode>;
-  static clearSmsCode(userId: User['id']): Promise<void>;
-  static verifySmsCode(userId: User['id'], code: string, purpose: SmsCodePurpose): Promise<boolean>;
+//#region src/Contracts/User.d.ts
+declare abstract class User extends Model {
+  [key: string]: any;
+  email: string;
+  name: string;
+  password: string;
+  createdAt: Date;
+  updatedAt: Date;
+  protected static table?: string | undefined;
 }
 //#endregion
 //#region src/Contracts/UserTwoFactor.d.ts
 declare abstract class UserTwoFactor extends Model {
-  id: number | string;
-  userId: User['id'];
+  [key: string]: any;
+  userId: User$1['id'];
   method: TwoFactorMethod | null;
   secretCiphertext: string | null;
   smsCodeHash: string | null;
@@ -527,5 +633,4 @@ declare class AuthenticationException extends Exception {
   errors(): Record<string, any> | undefined;
 }
 //#endregion
-export { Auth, AuthAgentPayload, AuthContract, AuthenticationException, CurrentSession, IssuedSmsCode, PersonalAccessToken, SessionDevice, SessionDeviceInfo, SmsCodePurpose, TwoFactor, TwoFactorMethod, TwoFactorSetup, TwoFactorStatus, User, UserTwoFactor };
-//# sourceMappingURL=index.d.ts.map
+export { Auth, AuthContract, AuthSession, AuthenticationException, DeviceAgentPayload, IssuedSmsCode, PersonalAccessToken, SessionDevice, SessionDeviceInfo, SmsCodePurpose, TwoFactor, TwoFactorMethod, TwoFactorSetup, TwoFactorStatus, User, UserTwoFactor, auth };