@eaccess/auth 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,930 @@
+import { Request, Response, NextFunction } from 'express';
+import { Pool } from 'pg';
+
+interface OAuthProviderConfig {
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+}
+interface GitHubProviderConfig extends OAuthProviderConfig {
+}
+interface GoogleProviderConfig extends OAuthProviderConfig {
+}
+interface AzureProviderConfig extends OAuthProviderConfig {
+    tenantId: string;
+}
+interface AuthConfig {
+    db: Pool;
+    createUser?: (userData: OAuthUserData) => string | number | Promise<string | number>;
+    tablePrefix?: string;
+    minPasswordLength?: number;
+    maxPasswordLength?: number;
+    rememberDuration?: string;
+    rememberCookieName?: string;
+    resyncInterval?: string;
+    activityLog?: {
+        enabled?: boolean;
+        maxEntries?: number;
+        actions?: AuthActivityActionType[];
+    };
+    providers?: {
+        github?: GitHubProviderConfig;
+        google?: GoogleProviderConfig;
+        azure?: AzureProviderConfig;
+    };
+    twoFactor?: {
+        enabled?: boolean;
+        requireForOAuth?: boolean;
+        issuer?: string;
+        codeLength?: number;
+        tokenExpiry?: string;
+        totpWindow?: number;
+        backupCodesCount?: number;
+    };
+}
+interface AuthAccount {
+    id: number;
+    user_id: string;
+    email: string;
+    password: string | null;
+    verified: boolean;
+    status: number;
+    rolemask: number;
+    last_login: Date | null;
+    force_logout: number;
+    resettable: boolean;
+    registered: Date;
+}
+interface AuthProvider {
+    id: number;
+    account_id: number;
+    provider: string;
+    provider_id: string;
+    provider_email: string | null;
+    provider_username: string | null;
+    provider_name: string | null;
+    provider_avatar: string | null;
+    created_at: Date;
+    updated_at: Date;
+}
+interface OAuthUserData {
+    id: string;
+    email: string;
+    username?: string;
+    name?: string;
+    avatar?: string;
+}
+interface OAuthProvider {
+    getAuthUrl(state?: string, scopes?: string[]): string;
+    handleCallback(req: Request): Promise<void>;
+    getUserData(req: Request): Promise<OAuthUserData>;
+}
+interface AuthConfirmation {
+    id: number;
+    account_id: number;
+    token: string;
+    email: string;
+    expires: Date;
+}
+interface AuthRemember {
+    id: number;
+    account_id: number;
+    token: string;
+    expires: Date;
+}
+interface AuthReset {
+    id: number;
+    account_id: number;
+    token: string;
+    expires: Date;
+}
+interface AuthActivity {
+    id: number;
+    account_id: number | null;
+    action: string;
+    ip_address: string | null;
+    user_agent: string | null;
+    browser: string | null;
+    os: string | null;
+    device: string | null;
+    success: boolean;
+    metadata: Record<string, any> | null;
+    created_at: Date;
+}
+interface AuthSession {
+    loggedIn: boolean;
+    accountId: number;
+    userId: string;
+    email: string;
+    status: number;
+    rolemask: number;
+    remembered: boolean;
+    lastResync: Date;
+    lastRememberCheck: Date;
+    forceLogout: number;
+    verified: boolean;
+    shouldForceLogout?: boolean;
+    awaitingTwoFactor?: {
+        accountId: number;
+        expiresAt: Date;
+        remember: boolean;
+        availableMechanisms: TwoFactorMechanism[];
+        attemptedMechanisms: TwoFactorMechanism[];
+        originalEmail: string;
+        selectors?: {
+            email?: string;
+            sms?: string;
+        };
+    };
+}
+declare enum TwoFactorMechanism {
+    TOTP = 1,
+    EMAIL = 2,
+    SMS = 3
+}
+interface TwoFactorMethod {
+    id: number;
+    account_id: number;
+    mechanism: TwoFactorMechanism;
+    secret: string | null;
+    backup_codes: string[] | null;
+    verified: boolean;
+    created_at: Date;
+    last_used_at: Date | null;
+}
+interface TwoFactorToken {
+    id: number;
+    account_id: number;
+    mechanism: TwoFactorMechanism;
+    selector: string;
+    token_hash: string;
+    expires_at: Date;
+    created_at: Date;
+}
+interface TwoFactorSetupResult {
+    secret: string;
+    qrCode: string;
+    backupCodes?: string[];
+}
+interface TwoFactorChallenge {
+    totp?: boolean;
+    email?: {
+        otpValue: string;
+        maskedContact: string;
+    };
+    sms?: {
+        otpValue: string;
+        maskedContact: string;
+    };
+    selectors?: {
+        email?: string;
+        sms?: string;
+    };
+}
+declare const AuthStatus: {
+    readonly Normal: 0;
+    readonly Archived: 1;
+    readonly Banned: 2;
+    readonly Locked: 3;
+    readonly PendingReview: 4;
+    readonly Suspended: 5;
+};
+declare const AuthRole: {
+    readonly Admin: 1;
+    readonly Author: 2;
+    readonly Collaborator: 4;
+    readonly Consultant: 8;
+    readonly Consumer: 16;
+    readonly Contributor: 32;
+    readonly Coordinator: 64;
+    readonly Creator: 128;
+    readonly Developer: 256;
+    readonly Director: 512;
+    readonly Editor: 1024;
+    readonly Employee: 2048;
+    readonly Maintainer: 4096;
+    readonly Manager: 8192;
+    readonly Moderator: 16384;
+    readonly Publisher: 32768;
+    readonly Reviewer: 65536;
+    readonly Subscriber: 131072;
+    readonly SuperAdmin: 262144;
+    readonly SuperEditor: 524288;
+    readonly SuperModerator: 1048576;
+    readonly Translator: 2097152;
+};
+declare const AuthActivityAction: {
+    readonly Login: "login";
+    readonly Logout: "logout";
+    readonly FailedLogin: "failed_login";
+    readonly Register: "register";
+    readonly EmailConfirmed: "email_confirmed";
+    readonly PasswordResetRequested: "password_reset_requested";
+    readonly PasswordResetCompleted: "password_reset_completed";
+    readonly PasswordChanged: "password_changed";
+    readonly EmailChanged: "email_changed";
+    readonly RoleChanged: "role_changed";
+    readonly StatusChanged: "status_changed";
+    readonly ForceLogout: "force_logout";
+    readonly OAuthConnected: "oauth_connected";
+    readonly RememberTokenCreated: "remember_token_created";
+    readonly TwoFactorSetup: "two_factor_setup";
+    readonly TwoFactorVerified: "two_factor_verified";
+    readonly TwoFactorFailed: "two_factor_failed";
+    readonly TwoFactorDisabled: "two_factor_disabled";
+    readonly BackupCodeUsed: "backup_code_used";
+};
+type AuthActivityActionType = (typeof AuthActivityAction)[keyof typeof AuthActivityAction];
+type TokenCallback = (token: string) => void;
+declare module "express-session" {
+    interface SessionData {
+        auth?: AuthSession;
+    }
+}
+declare global {
+    namespace Express {
+        interface Request {
+            auth: AuthManager$1;
+            authAdmin: AuthAdminManager;
+        }
+    }
+}
+interface AuthManager$1 {
+    isLoggedIn(): boolean;
+    login(email: string, password: string, remember?: boolean): Promise<void>;
+    completeTwoFactorLogin(): Promise<void>;
+    logout(): Promise<void>;
+    register(email: string, password: string, userId?: string | number, callback?: TokenCallback): Promise<AuthAccount>;
+    getId(): number | null;
+    getEmail(): string | null;
+    getStatus(): number | null;
+    getVerified(): boolean | null;
+    getRoleNames(rolemask?: number): string[];
+    getStatusName(): string | null;
+    hasRole(role: number): Promise<boolean>;
+    isAdmin(): Promise<boolean>;
+    isRemembered(): boolean;
+    changeEmail(newEmail: string, callback: TokenCallback): Promise<void>;
+    confirmEmail(token: string): Promise<string>;
+    confirmEmailAndLogin(token: string, remember?: boolean): Promise<void>;
+    resetPassword(email: string, expiresAfter?: string | number | null, maxOpenRequests?: number | null, callback?: TokenCallback): Promise<void>;
+    confirmResetPassword(token: string, password: string, logout?: boolean): Promise<void>;
+    verifyPassword(password: string): Promise<boolean>;
+    logoutEverywhere(): Promise<void>;
+    logoutEverywhereElse(): Promise<void>;
+    providers: {
+        github?: OAuthProvider;
+        google?: OAuthProvider;
+        azure?: OAuthProvider;
+    };
+    twoFactor: TwoFactorManager$1;
+}
+interface TwoFactorManager$1 {
+    isEnabled(): Promise<boolean>;
+    totpEnabled(): Promise<boolean>;
+    emailEnabled(): Promise<boolean>;
+    smsEnabled(): Promise<boolean>;
+    getEnabledMethods(): Promise<TwoFactorMechanism[]>;
+    setup: {
+        /**
+         * Setup TOTP authentication using an authenticator app.
+         * Generates a secret, QR code for easy setup, and optionally backup codes.
+         *
+         * @param requireVerification - If true, method is created in unverified state and requires calling complete.totp() with a valid code. If false (default), method is immediately enabled and backup codes are generated.
+         * @returns Promise resolving to setup result containing secret (for manual entry), QR code URL (for scanning), and backup codes (if verification not required)
+         * @throws {UserNotLoggedInError} User is not logged in
+         * @throws {TwoFactorAlreadyEnabledError} TOTP is already enabled for this user
+         */
+        totp(requireVerification?: boolean): Promise<TwoFactorSetupResult>;
+        /**
+         * Setup email-based two-factor authentication.
+         * Uses the user's account email or a specified email address for OTP delivery.
+         *
+         * @param email - Email address to use for 2FA. If not provided, uses the current user's account email
+         * @param requireVerification - If true, method is created in unverified state and requires calling complete.email() with a valid code. If false (default), method is immediately enabled
+         * @throws {UserNotLoggedInError} User is not logged in
+         * @throws {TwoFactorAlreadyEnabledError} Email 2FA is already enabled for this user
+         */
+        email(email?: string, requireVerification?: boolean): Promise<void>;
+        /**
+         * Setup SMS-based two-factor authentication.
+         * Uses the provided phone number for OTP delivery via SMS.
+         *
+         * @param phone - Phone number to use for SMS OTP delivery (should include country code, e.g., "+1234567890")
+         * @param requireVerification - If true (default), method is created in unverified state and requires calling complete.sms() with a valid code. If false, method is immediately enabled
+         * @throws {UserNotLoggedInError} User is not logged in
+         * @throws {TwoFactorAlreadyEnabledError} SMS 2FA is already enabled for this user
+         */
+        sms(phone: string, requireVerification?: boolean): Promise<void>;
+    };
+    complete: {
+        /**
+         * Complete TOTP setup by verifying a code from the user's authenticator app.
+         * This is only required if setup.totp() was called with requireVerification: true.
+         * Upon successful verification, the method is enabled and backup codes are generated.
+         *
+         * @param code - The 6-digit TOTP code from the user's authenticator app
+         * @returns Promise resolving to an array of backup codes that should be securely stored by the user
+         * @throws {UserNotLoggedInError} User is not logged in
+         * @throws {TwoFactorNotSetupError} TOTP method was not previously set up or doesn't exist
+         * @throws {TwoFactorAlreadyEnabledError} TOTP method is already verified/enabled
+         * @throws {InvalidTwoFactorCodeError} The provided TOTP code is invalid or expired
+         */
+        totp(code: string): Promise<string[]>;
+        /**
+         * Complete email 2FA setup by verifying an OTP code sent to the user's email.
+         * This is only required if setup.email() was called with requireVerification: true.
+         * Upon successful verification, the email 2FA method is enabled.
+         *
+         * @param code - The OTP code that was sent to the user's email address
+         * @throws {UserNotLoggedInError} User is not logged in
+         * @throws {TwoFactorNotSetupError} Email 2FA method was not previously set up or doesn't exist
+         * @throws {TwoFactorAlreadyEnabledError} Email 2FA method is already verified/enabled
+         * @throws {InvalidTwoFactorCodeError} The provided email OTP code is invalid or expired
+         */
+        email(code: string): Promise<void>;
+        /**
+         * Complete SMS 2FA setup by verifying an OTP code sent to the user's phone.
+         * This is only required if setup.sms() was called with requireVerification: true.
+         * Upon successful verification, the SMS 2FA method is enabled.
+         *
+         * @param code - The OTP code that was sent to the user's phone number via SMS
+         * @throws {UserNotLoggedInError} User is not logged in
+         * @throws {TwoFactorNotSetupError} SMS 2FA method was not previously set up or doesn't exist
+         * @throws {TwoFactorAlreadyEnabledError} SMS 2FA method is already verified/enabled
+         * @throws {InvalidTwoFactorCodeError} The provided SMS OTP code is invalid or expired
+         */
+        sms(code: string): Promise<void>;
+    };
+    verify: {
+        /**
+         * Verifies a TOTP code during the login flow when two-factor authentication is required.
+         * This is used after a login attempt triggers a SecondFactorRequiredError and the user
+         * provides a code from their authenticator app. After successful verification, call
+         * completeTwoFactorLogin() to finish the login process.
+         *
+         * @param code - The 6-digit TOTP code from the user's authenticator app
+         * @throws {UserNotLoggedInError} No active two-factor authentication session
+         * @throws {TwoFactorNotSetupError} TOTP method is not enabled for this user
+         * @throws {InvalidTwoFactorCodeError} The provided TOTP code is invalid or expired
+         */
+        totp(code: string): Promise<void>;
+        /**
+         * Verifies an email OTP code during the login flow when two-factor authentication is required.
+         * This is used after a login attempt triggers a SecondFactorRequiredError and the user
+         * provides the OTP code that was sent to their email. After successful verification, call
+         * completeTwoFactorLogin() to finish the login process.
+         *
+         * @param code - The OTP code that was sent to the user's email address
+         * @throws {UserNotLoggedInError} No active two-factor authentication session
+         * @throws {TwoFactorNotSetupError} Email 2FA method is not enabled for this user
+         * @throws {InvalidTwoFactorCodeError} The provided email OTP code is invalid or expired
+         */
+        email(code: string): Promise<void>;
+        /**
+         * Verifies an SMS OTP code during the login flow when two-factor authentication is required.
+         * This is used after a login attempt triggers a SecondFactorRequiredError and the user
+         * provides the OTP code that was sent to their phone. After successful verification, call
+         * completeTwoFactorLogin() to finish the login process.
+         *
+         * @param code - The OTP code that was sent to the user's phone number via SMS
+         * @throws {UserNotLoggedInError} No active two-factor authentication session
+         * @throws {TwoFactorNotSetupError} SMS 2FA method is not enabled for this user
+         * @throws {InvalidTwoFactorCodeError} The provided SMS OTP code is invalid or expired
+         */
+        sms(code: string): Promise<void>;
+        /**
+         * Verifies a TOTP backup code during the login flow when two-factor authentication is required.
+         * Backup codes are generated when TOTP is first set up and can be used as an alternative to
+         * the authenticator app. Each backup code can only be used once and is automatically removed
+         * after successful verification. After successful verification, call completeTwoFactorLogin()
+         * to finish the login process.
+         *
+         * @param code - A backup code that was generated during TOTP setup (8-character alphanumeric)
+         * @throws {UserNotLoggedInError} No active two-factor authentication session
+         * @throws {TwoFactorNotSetupError} TOTP method is not enabled for this user or no backup codes exist
+         * @throws {InvalidBackupCodeError} The provided backup code is invalid, expired, or already used
+         */
+        backupCode(code: string): Promise<void>;
+        /**
+         * Smart OTP verification that works with both email and SMS codes during the login flow.
+         * This method automatically determines whether the provided code is an email or SMS OTP
+         * by trying to verify it against all available OTP methods. Use this when you want to
+         * provide a single input field for users who may have multiple OTP methods enabled.
+         * After successful verification, call completeTwoFactorLogin() to finish the login process.
+         *
+         * @param code - Either an email or SMS OTP code
+         * @throws {UserNotLoggedInError} No active two-factor authentication session
+         * @throws {TwoFactorNotSetupError} No email or SMS 2FA methods are enabled for this user
+         * @throws {InvalidTwoFactorCodeError} The provided code doesn't match any available OTP methods or is expired
+         */
+        otp(code: string): Promise<void>;
+    };
+    /**
+     * Disable a TwoFactorMechanism for the session user.
+     * @param mechanism - The TwoFactorMechanism to disable for the session user
+     * @throws {UserNotLoggedInError} User is not logged in
+     * @throws {TwoFactorNotSetupError} The specified method is not enabled for this user
+     */
+    disable(mechanism: TwoFactorMechanism): Promise<void>;
+    /**
+     * Generates and stores new TOTP backup codes for the session user, invalidating the old ones in the process.
+     * @returns Promise resolving to an array of new backup codes that should be securely stored by the user
+     * @throws {UserNotLoggedInError} User is not logged in
+     * @throws {TwoFactorNotSetupError} TOTP method is not enabled for this user
+     */
+    generateNewBackupCodes(): Promise<string[]>;
+    /**
+     * Returns either the email or mobile number for the session user depending on the provided TwoFactorMechanism.
+     * @param mechanism - The TwoFactorMechanism for which to return the contact information
+     * @returns Promise resolving to the contact information (email or phone number) or null if not found
+     * @throws {UserNotLoggedInError} User is not logged in (returns null instead of throwing in implementation)
+     */
+    getContact(mechanism: TwoFactorMechanism.EMAIL | TwoFactorMechanism.SMS): Promise<string | null>;
+}
+interface AuthAdminManager {
+    createUser(credentials: {
+        email: string;
+        password: string;
+    }, userId?: string | number, callback?: TokenCallback): Promise<AuthAccount>;
+    loginAsUserBy(identifier: {
+        accountId?: number;
+        email?: string;
+        userId?: string;
+    }): Promise<void>;
+    deleteUserBy(identifier: {
+        accountId?: number;
+        email?: string;
+        userId?: string;
+    }): Promise<void>;
+    addRoleForUserBy(identifier: {
+        accountId?: number;
+        email?: string;
+        userId?: string;
+    }, role: number): Promise<void>;
+    removeRoleForUserBy(identifier: {
+        accountId?: number;
+        email?: string;
+        userId?: string;
+    }, role: number): Promise<void>;
+    hasRoleForUserBy(identifier: {
+        accountId?: number;
+        email?: string;
+        userId?: string;
+    }, role: number): Promise<boolean>;
+    changePasswordForUserBy(identifier: {
+        accountId?: number;
+        email?: string;
+        userId?: string;
+    }, password: string): Promise<void>;
+    setStatusForUserBy(identifier: {
+        accountId?: number;
+        email?: string;
+        userId?: string;
+    }, status: number): Promise<void>;
+    initiatePasswordResetForUserBy(identifier: {
+        accountId?: number;
+        email?: string;
+        userId?: string;
+    }, expiresAfter?: string | number | null, callback?: TokenCallback): Promise<void>;
+    forceLogoutForUserBy(identifier: {
+        accountId?: number;
+        email?: string;
+        userId?: string;
+    }): Promise<void>;
+}
+
+declare function createAuthMiddleware(config: AuthConfig): (req: Request, res: Response, next: NextFunction) => Promise<void>;
+
+declare function createAuthTables(config: AuthConfig): Promise<void>;
+declare function dropAuthTables(config: AuthConfig): Promise<void>;
+declare function cleanupExpiredTokens(config: AuthConfig): Promise<void>;
+declare function getAuthTableStats(config: AuthConfig): Promise<{
+    accounts: number;
+    providers: number;
+    confirmations: number;
+    remembers: number;
+    resets: number;
+    twoFactorMethods: number;
+    twoFactorTokens: number;
+    expiredConfirmations: number;
+    expiredRemembers: number;
+    expiredResets: number;
+    expiredTwoFactorTokens: number;
+}>;
+
+declare class AuthError extends Error {
+    constructor(message: string);
+}
+declare class ConfirmationExpiredError extends AuthError {
+    constructor();
+}
+declare class ConfirmationNotFoundError extends AuthError {
+    constructor();
+}
+declare class EmailNotVerifiedError extends AuthError {
+    constructor();
+}
+declare class EmailTakenError extends AuthError {
+    constructor();
+}
+declare class InvalidEmailError extends AuthError {
+    constructor();
+}
+declare class InvalidPasswordError extends AuthError {
+    constructor();
+}
+declare class InvalidTokenError extends AuthError {
+    constructor();
+}
+declare class ResetDisabledError extends AuthError {
+    constructor();
+}
+declare class ResetExpiredError extends AuthError {
+    constructor();
+}
+declare class ResetNotFoundError extends AuthError {
+    constructor();
+}
+declare class TooManyResetsError extends AuthError {
+    constructor();
+}
+declare class UserInactiveError extends AuthError {
+    constructor();
+}
+declare class UserNotFoundError extends AuthError {
+    constructor();
+}
+declare class UserNotLoggedInError extends AuthError {
+    constructor();
+}
+declare class SecondFactorRequiredError extends AuthError {
+    availableMethods: {
+        totp?: boolean;
+        email?: {
+            otpValue: string;
+            maskedContact: string;
+        };
+        sms?: {
+            otpValue: string;
+            maskedContact: string;
+        };
+    };
+    constructor(availableMethods: SecondFactorRequiredError["availableMethods"]);
+}
+declare class InvalidTwoFactorCodeError extends AuthError {
+    constructor();
+}
+declare class TwoFactorExpiredError extends AuthError {
+    constructor();
+}
+declare class TwoFactorNotSetupError extends AuthError {
+    constructor();
+}
+declare class TwoFactorAlreadyEnabledError extends AuthError {
+    constructor();
+}
+declare class InvalidBackupCodeError extends AuthError {
+    constructor();
+}
+declare class TwoFactorSetupIncompleteError extends AuthError {
+    constructor();
+}
+
+declare const isValidEmail: (email: string) => boolean;
+declare const validateEmail: (email: string) => void;
+
+declare class ActivityLogger {
+    private config;
+    private enabled;
+    private maxEntries;
+    private allowedActions;
+    private tablePrefix;
+    constructor(config: AuthConfig);
+    private get activityTable();
+    private parseUserAgent;
+    private parseUserAgentSimple;
+    private getIpAddress;
+    logActivity(accountId: number | null, action: AuthActivityActionType, req: Request, success?: boolean, metadata?: Record<string, any>): Promise<void>;
+    cleanup(): Promise<void>;
+    getRecentActivity(limit?: number, accountId?: number): Promise<AuthActivity[]>;
+    getActivityStats(): Promise<{
+        totalEntries: number;
+        uniqueUsers: number;
+        recentLogins: number;
+        failedAttempts: number;
+    }>;
+}
+
+declare class TwoFactorManager implements TwoFactorManager$1 {
+    private req;
+    private res;
+    private config;
+    private queries;
+    private activityLogger;
+    private totpProvider;
+    private otpProvider;
+    constructor(req: Request, res: Response, config: AuthConfig);
+    private getAccountId;
+    private getEmail;
+    isEnabled(): Promise<boolean>;
+    totpEnabled(): Promise<boolean>;
+    emailEnabled(): Promise<boolean>;
+    smsEnabled(): Promise<boolean>;
+    getEnabledMethods(): Promise<TwoFactorMechanism[]>;
+    setup: {
+        totp: (requireVerification?: boolean) => Promise<TwoFactorSetupResult>;
+        email: (email?: string, requireVerification?: boolean) => Promise<void>;
+        sms: (phone: string, requireVerification?: boolean) => Promise<void>;
+    };
+    complete: {
+        totp: (code: string) => Promise<string[]>;
+        email: (code: string) => Promise<void>;
+        sms: (code: string) => Promise<void>;
+    };
+    private completeOtpSetup;
+    verify: {
+        totp: (code: string) => Promise<void>;
+        email: (code: string) => Promise<void>;
+        sms: (code: string) => Promise<void>;
+        backupCode: (code: string) => Promise<void>;
+        otp: (code: string) => Promise<void>;
+    };
+    private verifyOtp;
+    disable(mechanism: TwoFactorMechanism): Promise<void>;
+    generateNewBackupCodes(): Promise<string[]>;
+    getContact(mechanism: TwoFactorMechanism.EMAIL | TwoFactorMechanism.SMS): Promise<string | null>;
+    createChallenge(accountId: number): Promise<TwoFactorChallenge>;
+}
+
+declare class TotpProvider {
+    private config;
+    constructor(config: AuthConfig);
+    generateSecret(): string;
+    generateQRCode(email: string, secret: string): string;
+    verify(secret: string, code: string): boolean;
+    generateBackupCodes(count?: number): string[];
+    hashBackupCodes(codes: string[]): string[];
+    verifyBackupCode(hashedCodes: string[], inputCode: string): {
+        isValid: boolean;
+        index: number;
+    };
+    maskEmail(email: string): string;
+}
+
+declare class OtpProvider {
+    private config;
+    private queries;
+    constructor(config: AuthConfig);
+    generateOTP(): string;
+    generateSelector(): string;
+    createAndStoreOTP(accountId: number, mechanism: TwoFactorMechanism.EMAIL | TwoFactorMechanism.SMS): Promise<{
+        otp: string;
+        selector: string;
+    }>;
+    verifyOTP(selector: string, inputCode: string): Promise<{
+        isValid: boolean;
+        token?: TwoFactorToken;
+    }>;
+    maskPhone(phone: string): string;
+    maskEmail(email: string): string;
+}
+
+declare class AuthManager implements AuthManager$1 {
+    private req;
+    private res;
+    private config;
+    private queries;
+    private activityLogger;
+    providers: {
+        github?: OAuthProvider;
+        google?: OAuthProvider;
+        azure?: OAuthProvider;
+    };
+    twoFactor: TwoFactorManager;
+    constructor(req: Request, res: Response, config: AuthConfig);
+    private initializeProviders;
+    private generateAutoUserId;
+    private shouldRequire2FA;
+    private validatePassword;
+    private getRoleMap;
+    private getStatusMap;
+    private getAuthAccount;
+    private setRememberCookie;
+    private getRememberToken;
+    private regenerateSession;
+    resyncSession(force?: boolean): Promise<void>;
+    processRememberDirective(): Promise<void>;
+    private onLoginSuccessful;
+    private createRememberDirective;
+    /**
+     * Check if the current user is logged in.
+     * @returns true if user has an active authenticated session
+     */
+    isLoggedIn(): boolean;
+    /**
+     * Authenticate user with email and password.
+     * Creates a new session and optionally sets a remember token for persistent login.
+     *
+     * @param email - User's email address
+     * @param password - Plain text password
+     * @param remember - If true, sets a persistent cookie for auto-login on future visits
+     * @throws {UserNotFoundError} Account with this email doesn't exist
+     * @throws {InvalidPasswordError} Password is incorrect
+     * @throws {EmailNotVerifiedError} Account exists but email is not verified
+     * @throws {UserInactiveError} Account is banned, locked, or otherwise inactive
+     */
+    login(email: string, password: string, remember?: boolean): Promise<void>;
+    /**
+     * Complete two-factor authentication and log in the user.
+     * This should be called after receiving a SecondFactorRequiredError.
+     */
+    completeTwoFactorLogin(): Promise<void>;
+    /**
+     * Log out the current user.
+     * Clears the session and removes any remember tokens.
+     */
+    logout(): Promise<void>;
+    /**
+     * Register a new account.
+     *
+     * @param email - Email address for the new account
+     * @param password - Plain text password (will be hashed)
+     * @param userId - Optional user ID to link this auth account to. If not provided, a UUID will be generated automatically.
+     * @param callback - If provided, account is created unverified and callback receives confirmation token. Create a URL like /confirm/{token} and call confirmEmail() in that handler. If omitted, account is immediately verified.
+     * @returns The created account record
+     * @throws {EmailTakenError} Email is already registered
+     * @throws {InvalidPasswordError} Password doesn't meet length requirements
+     */
+    register(email: string, password: string, userId?: string | number, callback?: TokenCallback): Promise<AuthAccount>;
+    private createConfirmationToken;
+    /**
+     * Get the current user's account ID.
+     * @returns Account ID if logged in, null otherwise
+     */
+    getId(): number | null;
+    /**
+     * Get the current user's email address.
+     * @returns Email if logged in, null otherwise
+     */
+    getEmail(): string | null;
+    /**
+     * Get the current user's account status.
+     * @returns Status number (0=Normal, 1=Archived, 2=Banned, etc.) if logged in, null otherwise
+     */
+    getStatus(): number | null;
+    /**
+     * Check if the current user's email is verified.
+     * @returns true if verified, false if unverified, null if not logged in
+     */
+    getVerified(): boolean | null;
+    /**
+     * Get human-readable role names for the current user or a specific rolemask.
+     * @param rolemask - Optional specific rolemask to check. If omitted, uses current user's roles
+     * @returns Array of role names (e.g., ['Admin', 'Editor'])
+     */
+    getRoleNames(rolemask?: number): string[];
+    /**
+     * Get human-readable status name for the current user.
+     * @returns Status name (e.g., 'Normal', 'Banned', 'Locked') if logged in, null otherwise
+     */
+    getStatusName(): string | null;
+    /**
+     * Check if the current user has a specific role.
+     * @param role - Role bitmask to check (e.g., AuthRole.Admin)
+     * @returns true if user has the role, false otherwise
+     */
+    hasRole(role: number): Promise<boolean>;
+    /**
+     * Check if the current user has admin privileges.
+     * @returns true if user has Admin role, false otherwise
+     */
+    isAdmin(): Promise<boolean>;
+    /**
+     * Check if the current user was automatically logged in via remember token.
+     * @returns true if auto-logged in from persistent cookie, false if manual login or not logged in
+     */
+    isRemembered(): boolean;
+    /**
+     * Request an email change for the current user.
+     * Sends a confirmation token to verify the new email before changing it.
+     *
+     * @param newEmail - New email address
+     * @param callback - Called with confirmation token. Create a URL like /confirm/{token} and call confirmEmail() in that handler
+     * @throws {UserNotLoggedInError} User is not logged in
+     * @throws {EmailTakenError} New email is already registered
+     * @throws {UserNotFoundError} Current user account not found
+     * @throws {EmailNotVerifiedError} Current account's email is not verified
+     */
+    changeEmail(newEmail: string, callback: TokenCallback): Promise<void>;
+    /**
+     * Confirm an email address using a token from registration or email change.
+     * Updates the account to verified status and changes email if this was from changeEmail.
+     *
+     * @param token - Confirmation token from registration or email change
+     * @returns The confirmed email address
+     * @throws {ConfirmationNotFoundError} Token is invalid or doesn't exist
+     * @throws {ConfirmationExpiredError} Token has expired
+     * @throws {InvalidTokenError} Token format is invalid
+     */
+    confirmEmail(token: string): Promise<string>;
+    /**
+     * Confirm email and automatically log in the user.
+     * Useful for "click to verify and login" flows.
+     *
+     * @param token - Confirmation token from registration
+     * @param remember - Whether to set persistent login cookie
+     * @throws {ConfirmationNotFoundError} Token is invalid or doesn't exist
+     * @throws {ConfirmationExpiredError} Token has expired
+     * @throws {InvalidTokenError} Token format is invalid
+     * @throws {UserNotFoundError} Associated account no longer exists
+     */
+    confirmEmailAndLogin(token: string, remember?: boolean): Promise<void>;
+    /**
+     * Initiate a password reset for a user.
+     * Creates a reset token and calls the callback to send reset email.
+     *
+     * @param email - Email address of account to reset
+     * @param expiresAfter - Token expiration (default: 6h). Accepts ms format like '1h', '30m'
+     * @param maxOpenRequests - Maximum concurrent reset tokens (default: 2)
+     * @param callback - Called with reset token. Create a URL like /reset/{token} and call confirmResetPassword() in that handler
+     * @throws {EmailNotVerifiedError} Account doesn't exist or email not verified
+     * @throws {ResetDisabledError} Account has password reset disabled
+     * @throws {TooManyResetsError} Too many active reset requests
+     */
+    resetPassword(email: string, expiresAfter?: string | number | null, maxOpenRequests?: number | null, callback?: TokenCallback): Promise<void>;
+    /**
+     * Complete a password reset using a reset token.
+     * Changes the password and optionally logs out all sessions.
+     *
+     * @param token - Reset token from resetPassword callback
+     * @param password - New password (will be hashed)
+     * @param logout - Whether to force logout all sessions (default: true)
+     * @throws {ResetNotFoundError} Token is invalid or doesn't exist
+     * @throws {ResetExpiredError} Token has expired
+     * @throws {UserNotFoundError} Associated account no longer exists
+     * @throws {ResetDisabledError} Account has password reset disabled
+     * @throws {InvalidPasswordError} New password doesn't meet requirements
+     * @throws {InvalidTokenError} Token format is invalid
+     */
+    confirmResetPassword(token: string, password: string, logout?: boolean): Promise<void>;
+    /**
+     * Verify if a password matches the current user's password.
+     * Useful for "confirm current password" flows before sensitive operations.
+     *
+     * @param password - Password to verify
+     * @returns true if password matches, false otherwise
+     * @throws {UserNotLoggedInError} User is not logged in
+     * @throws {UserNotFoundError} Current user account not found
+     */
+    verifyPassword(password: string): Promise<boolean>;
+    private forceLogoutForAccountById;
+    /**
+     * Force logout all OTHER sessions while keeping current session active.
+     * Useful for "logout other devices" functionality.
+     */
+    logoutEverywhereElse(): Promise<void>;
+    /**
+     * Force logout ALL sessions including the current one.
+     * Logs out everywhere else, then logs out current session.
+     */
+    logoutEverywhere(): Promise<void>;
+}
+
+declare abstract class BaseOAuthProvider implements OAuthProvider {
+    protected config: OAuthProviderConfig;
+    protected authConfig: AuthConfig;
+    protected authManager: AuthManager;
+    constructor(config: OAuthProviderConfig, authConfig: AuthConfig, authManager: AuthManager);
+    abstract getAuthUrl(state?: string, scopes?: string[]): string;
+    abstract getUserData(req: Request): Promise<OAuthUserData>;
+    handleCallback(req: Request): Promise<void>;
+    protected processOAuthLogin(userData: OAuthUserData, req: Request): Promise<void>;
+    protected abstract getProviderName(): string;
+    protected exchangeCodeForToken(code: string, tokenUrl: string): Promise<string>;
+    protected fetchUserFromAPI(accessToken: string, apiUrl: string): Promise<any>;
+}
+
+declare class GitHubProvider extends BaseOAuthProvider {
+    constructor(config: GitHubProviderConfig, authConfig: AuthConfig, authManager: AuthManager);
+    getAuthUrl(state?: string, scopes?: string[]): string;
+    getUserData(req: Request): Promise<OAuthUserData>;
+    protected getProviderName(): string;
+}
+
+declare class GoogleProvider extends BaseOAuthProvider {
+    constructor(config: GoogleProviderConfig, authConfig: AuthConfig, authManager: AuthManager);
+    getAuthUrl(state?: string, scopes?: string[]): string;
+    getUserData(req: Request): Promise<OAuthUserData>;
+    protected getProviderName(): string;
+}
+
+declare class AzureProvider extends BaseOAuthProvider {
+    constructor(config: AzureProviderConfig, authConfig: AuthConfig, authManager: AuthManager);
+    getAuthUrl(state?: string, scopes?: string[]): string;
+    getUserData(req: Request): Promise<OAuthUserData>;
+    protected getProviderName(): string;
+    protected exchangeCodeForToken(code: string, tokenUrl: string): Promise<string>;
+}
+
+export { ActivityLogger, type AuthAccount, type AuthActivity, AuthActivityAction, type AuthActivityActionType, type AuthAdminManager, type AuthConfig, type AuthConfirmation, AuthError, type AuthManager$1 as AuthManager, type AuthProvider, type AuthRemember, type AuthReset, AuthRole, type AuthSession, AuthStatus, AzureProvider, type AzureProviderConfig, BaseOAuthProvider, ConfirmationExpiredError, ConfirmationNotFoundError, EmailNotVerifiedError, EmailTakenError, GitHubProvider, type GitHubProviderConfig, GoogleProvider, type GoogleProviderConfig, InvalidBackupCodeError, InvalidEmailError, InvalidPasswordError, InvalidTokenError, InvalidTwoFactorCodeError, type OAuthProvider, type OAuthProviderConfig, type OAuthUserData, OtpProvider, ResetDisabledError, ResetExpiredError, ResetNotFoundError, SecondFactorRequiredError, type TokenCallback, TooManyResetsError, TotpProvider, TwoFactorAlreadyEnabledError, type TwoFactorChallenge, TwoFactorExpiredError, TwoFactorManager, TwoFactorMechanism, type TwoFactorMethod, TwoFactorNotSetupError, TwoFactorSetupIncompleteError, type TwoFactorSetupResult, type TwoFactorToken, UserInactiveError, UserNotFoundError, UserNotLoggedInError, cleanupExpiredTokens, createAuthMiddleware, createAuthTables, dropAuthTables, getAuthTableStats, isValidEmail, validateEmail };