@arkstack/auth 0.12.6 → 0.12.7

package/dist/index.d.ts

@@ -18,10 +18,25 @@ declare abstract class PersonalAccessToken extends Model {
 }
 //#endregion
 //#region src/Session.d.ts
+/**
+ * Represents an authenticated user session.
+ *
+ * @author 3m1n3nc3
+ */
 declare class Session extends Session$1 {
   private auth;
   constructor(auth: AuthContract, current?: Session$1 | undefined);
+  /**
+   * Destroy the current session
+   *
+   * @returns
+   */
   destroy(): Promise<this>;
+  /**
+   * Get the current auth session token
+   *
+   * @returns
+   */
   token(): Promise<PersonalAccessToken | null>;
 }
 //#endregion
@@ -37,51 +52,277 @@ declare abstract class User extends Model {
 }
 //#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 {
+  /**
+   * 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> | RequestSource<User>): 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> | undefined;
+  /**
+   * Get the currently authenticated user
+   *
+   * @returns The currently authenticated user or null if not authenticated.
+   */
   abstract user(): User | 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>;
+  /**
+   * Attempt to authenticate a user with the given email and password.
+   *
+   * @param email
+   * @param password
+   * @returns
+   */
   abstract attempt(email: string, password: string): Promise<User>;
+  /**
+   * Login a user and create a personal access token
+   *
+   * @param email
+   * @param password
+   * @returns
+   */
   abstract login(email: string, password: string): Promise<PersonalAccessToken>;
+  /**
+   * 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, 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>;
+  /**
+   * 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>;
+  /**
+   * Get the current session's personal access token
+   *
+   * @returns
+   */
   abstract session(): Session;
+  /**
+   * Create a personal access token for a user
+   *
+   * @param user
+   * @returns
+   */
   abstract create(user: User): Promise<PersonalAccessToken>;
+  /**
+   * Authorize a token and return the associated user
+   *
+   * @param token
+   * @returns
+   */
   abstract authorizeToken(token: string): Promise<User>;
 }
 //#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>;
   private configuredSecret?;
   constructor(secret?: string, req?: Request<User> | RequestSource<User>);
+  /**
+   * 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;
+  /**
+   * 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> | RequestSource<User>): 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> | RequestSource<User>): 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> | undefined;
+  /**
+   * Get the currently authenticated user
+   *
+   * @returns The currently authenticated user or null if not authenticated.
+   */
   user(): User | 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 to authenticate a user with the given email and password.
+   *
+   * @param email
+   * @param password
+   * @returns
+   */
   attempt(email: string, password: string): Promise<User>;
+  /**
+   * Login a user and create a personal access token
+   *
+   * @param email
+   * @param password
+   * @returns
+   */
   login(email: string, password: string): Promise<PersonalAccessToken>;
+  /**
+   * 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, 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>;
+  /**
+   * 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>;
+  /**
+   * Get the current session's personal access token
+   *
+   * @returns
+   */
   session(): Session;
+  /**
+   * Create a personal access token for a user
+   *
+   * @param user
+   * @returns
+   */
   create(user: User): 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;
+  /**
+   * Authorize a token and return the associated user
+   *
+   * @param token
+   * @returns
+   */
   authorizeToken(token: string): Promise<User>;
+  /**
+   * Create a JWT token
+   *
+   * @param payload
+   * @returns
+   */
   private createJWT;
+  /**
+   * Verify a JWT token
+   *
+   * @param token
+   * @returns
+   */
   private verifyJWT;
   private getSecret;
+  /**
+   * 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
@@ -110,17 +351,86 @@ type DeviceAgentPayload = {
 //#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;
+  /**
+   * Safely reads the user agent string from the request headers.
+   *
+   * @param req
+   * @returns
+   */
   private static readUserAgent;
+  /**
+   * Safely reads a string value, ensuring it's a non-empty string or returns null.
+   *
+   * @param value
+   * @returns
+   */
   private static readString;
+  /**
+   * Reads a specific device-related header from the request
+   *
+   * @param req
+   * @param headerName
+   * @returns
+   */
   private static readDeviceAgent;
   private static normalizeDeviceType;
+  /**
+   * Detects the client's IP address from the request, considering common headers set by proxies.
+   *
+   * @param req
+   * @returns
+   */
   private static detectIpAddress;
+  /**
+   * Detects the browser from the user agent string.
+   *
+   * @param userAgent
+   * @returns
+   */
   private static detectBrowser;
+  /**
+   * Detects the operating system from the user agent string.
+   *
+   * @param userAgent
+   * @returns
+   */
   private static detectOs;
+  /**
+   * Detects the device type from the user agent string.
+   *
+   * @param userAgent
+   * @returns
+   */
   private static detectDeviceType;
 }
 //#endregion
@@ -151,28 +461,140 @@ declare class TwoFactor {
   private static upsert;
   static normalizeMethod(method?: string | null): TwoFactorMethod | null;
   static maskPhone(phone?: string | null): string | null;
+  /**
+   * Build the account label used inside the OTP URI.
+   *
+   * @param user
+   * @returns
+   */
   static getLabel(user: User): string;
+  /**
+   * Create the per-user TOTP instance for setup and verification.
+   *
+   * @param user
+   * @param secret
+   * @returns
+   */
   static getTotp(user: User, secret: string): _$otpauth.TOTP;
+  /**
+   * Generate a new shared secret for authenticator-based 2FA.
+   *
+   * @returns The generated secret in base32 format.
+   */
   static generateSecret(size?: number): 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.
+   */
   static createSetup(user: User, secret?: string): TwoFactorSetup;
+  /**
+   * 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, secret: string, code: string): boolean;
   static getMethod(userId: User['id']): Promise<TwoFactorMethod | null>;
   static setMethod(userId: User['id'], method: TwoFactorMethod): Promise<void>;
+  /**
+   * Read the setup secret stored for a user.
+   *
+   * @param userId The ID of the user.
+   * @returns The stored secret, or null if not found.
+   */
   static getSecret(userId: User['id']): Promise<string | null>;
+  /**
+   * Store the setup secret for a user.
+   *
+   * @param userId The ID of the user.
+   * @param secret The secret to store.
+   */
   static setSecret(userId: User['id'], secret: string): Promise<void>;
   static clearSecret(userId: User['id']): Promise<void>;
+  /**
+   * 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.
+   */
   static getEnabledAt(userId: User['id']): Promise<string | null>;
+  /**
+   * Persist the timestamp marking 2FA as enabled.
+   *
+   * @param userId The ID of the user.
+   * @param enabledAt The timestamp to store.
+   */
   static setEnabledAt(userId: User['id'], enabledAt?: string | Date): Promise<void>;
+  /**
+   * Remove all persisted 2FA state for a user.
+   *
+   * @param userId The ID of the user.
+   */
   static clear(userId: User['id']): Promise<void>;
+  /**
+   * Generate one-time recovery codes shown when 2FA is enabled.
+   *
+   * @returns An array of recovery codes.
+   */
   static generateBackupCodes(count?: number): string[];
+  /**
+   * Hash recovery codes before persisting them.
+   *
+   * @param codes An array of recovery codes to hash.
+   * @returns An array of hashed recovery codes.
+   */
   static hashBackupCodes(codes: string[]): Promise<string[]>;
+  /**
+   * Read stored recovery-code hashes for a user.
+   *
+   * @param userId The ID of the user.
+   * @returns An array of recovery-code hashes.
+   */
   static readRecoveryCodeHashes(userId: User['id']): Promise<string[]>;
+  /**
+   * Persist recovery-code hashes on the user's dedicated 2FA record.
+   *
+   * @param userId
+   * @param hashes
+   */
   static writeRecoveryCodeHashes(userId: User['id'], hashes: string[]): Promise<void>;
+  /**
+   * 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.
+   */
   static consumeRecoveryCode(userId: User['id'], recoveryCode: string): Promise<boolean>;
+  /**
+   * 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.
+   */
   static readStatus(userId: User['id']): Promise<TwoFactorStatus>;
   static createSmsCode(): string;
+  /**
+   * Issue a new SMS code for the given user and send it via SMS for the specified purpose.
+   *
+   * @param user
+   * @param purpose
+   */
   static issueSmsCode(user: User, purpose: SmsCodePurpose): Promise<IssuedSmsCode>;
   static clearSmsCode(userId: User['id']): Promise<void>;
+  /**
+   * Verify a submitted SMS code for a user and purpose, consuming the code if valid.
+   *
+   * @param userId
+   * @param code
+   * @param purpose
+   * @returns
+   */
   static verifySmsCode(userId: User['id'], code: string, purpose: SmsCodePurpose): Promise<boolean>;
 }
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkstack/auth",
-  "version": "0.12.6",
+  "version": "0.12.7",
   "type": "module",
   "description": "Authentication module for Arkstack, providing core authentication and identity features.",
   "homepage": "https://arkstack.toneflix.net/guide/auth",
@@ -38,12 +38,12 @@
     "jose": "^6.2.3",
     "otpauth": "^9.5.1",
     "ua-parser-js": "^2.0.9",
-    "@arkstack/common": "^0.12.6",
-    "@arkstack/http": "^0.12.6"
+    "@arkstack/http": "^0.12.7",
+    "@arkstack/common": "^0.12.7"
   },
   "peerDependencies": {
     "@h3ravel/support": "^0.15.11",
-    "@arkstack/database": "^0.12.6"
+    "@arkstack/database": "^0.12.7"
   },
   "scripts": {
     "build": "tsdown --config-loader unrun",