@prsm/auth 1.0.0

package/types/totp.d.ts

@@ -0,0 +1,72 @@
+export class InvalidOtpLengthError extends Error {
+}
+export class InvalidSecretError extends Error {
+}
+export class InvalidHashFunctionError extends Error {
+}
+export class InvalidSecretStrengthError extends Error {
+}
+export class InvalidIntervalError extends Error {
+}
+export default Otp;
+declare class Otp {
+    static OTP_LENGTH_MIN: number;
+    static OTP_LENGTH_MAX: number;
+    static OTP_LENGTH_DEFAULT: number;
+    static INTERVAL_LENGTH_DEFAULT: number;
+    static EPOCH_DEFAULT: number;
+    static HASH_FUNCTION_SHA_1: number;
+    static HASH_FUNCTION_SHA_256: number;
+    static HASH_FUNCTION_SHA_512: number;
+    static HASH_FUNCTION_DEFAULT: number;
+    static SHARED_SECRET_STRENGTH_LOW: number;
+    static SHARED_SECRET_STRENGTH_MODERATE: number;
+    static SHARED_SECRET_STRENGTH_HIGH: number;
+    /**
+     * Generate a random Base32 shared secret (without padding).
+     * @param {number} [strength] one of the SHARED_SECRET_STRENGTH_* constants, defaults to high (160 bits)
+     * @returns {string}
+     * @throws {InvalidSecretStrengthError}
+     */
+    static createSecret(strength?: number): string;
+    /**
+     * Build an otpauth:// URI for QR-code provisioning in authenticator apps.
+     * @param {string} issuer
+     * @param {string} accountName
+     * @param {string} secret
+     * @returns {string}
+     */
+    static createTotpKeyUriForQrCode(issuer: string, accountName: string, secret: string): string;
+    /**
+     * Generate a TOTP value.
+     * @param {string} secret base32 shared secret, at least 16 chars after sanitization
+     * @param {number} [t] unix time in seconds, defaults to now
+     * @param {number} [otpLength] number of digits (6-8), defaults to 6
+     * @param {number} [t_x] time step in seconds, defaults to 30
+     * @param {number} [t_0] epoch start in seconds, defaults to 0
+     * @param {number} [hashFunction] one of the HASH_FUNCTION_* constants, defaults to SHA-1
+     * @returns {string}
+     * @throws {InvalidOtpLengthError|InvalidIntervalError|InvalidSecretError|InvalidHashFunctionError}
+     */
+    static generateTotp(secret: string, t?: number, otpLength?: number, t_x?: number, t_0?: number, hashFunction?: number): string;
+    /**
+     * Verify a user-supplied TOTP across a drift window using a constant-time compare.
+     * @param {string} secret
+     * @param {string} otpValue
+     * @param {number} [lookBehindSteps] defaults to 2
+     * @param {number} [lookAheadSteps] defaults to lookBehindSteps (symmetric)
+     * @param {number} [t]
+     * @param {number} [otpLength]
+     * @param {number} [t_x]
+     * @param {number} [t_0]
+     * @param {number} [hashFunction]
+     * @returns {boolean}
+     */
+    static verifyTotp(secret: string, otpValue: string, lookBehindSteps?: number, lookAheadSteps?: number, t?: number, otpLength?: number, t_x?: number, t_0?: number, hashFunction?: number): boolean;
+    /**
+     * @param {number} strength
+     * @returns {number}
+     * @throws {InvalidSecretStrengthError}
+     */
+    static determineBitsForSharedSecretStrength(strength: number): number;
+}

package/types/two-factor/index.d.ts

@@ -0,0 +1,3 @@
+export { TwoFactorManager } from "./two-factor-manager.js";
+export { TotpProvider } from "./totp-provider.js";
+export { OtpProvider } from "./otp-provider.js";

package/types/two-factor/otp-provider.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @typedef {import("../types.js").AuthConfig} AuthConfig
+ * @typedef {import("../types.js").TwoFactorToken} TwoFactorToken
+ */
+export class OtpProvider {
+    /**
+     * @param {AuthConfig} config
+     */
+    constructor(config: AuthConfig);
+    config: import("../types.js").AuthConfig;
+    queries: AuthQueries;
+    /**
+     * Generate a numeric one-time password.
+     * @returns {string}
+     */
+    generateOTP(): string;
+    /**
+     * Generate a random opaque selector for an OTP token.
+     * @returns {string}
+     */
+    generateSelector(): string;
+    /**
+     * Create, hash, and store a new OTP for an account and mechanism.
+     * @param {number} accountId
+     * @param {number} mechanism EMAIL or SMS
+     * @returns {Promise<{ otp: string, selector: string }>}
+     */
+    createAndStoreOTP(accountId: number, mechanism: number): Promise<{
+        otp: string;
+        selector: string;
+    }>;
+    /**
+     * Verify an OTP by selector, consuming the token on success.
+     * @param {string} selector
+     * @param {string} inputCode
+     * @returns {Promise<{ isValid: boolean, token?: TwoFactorToken }>}
+     */
+    verifyOTP(selector: string, inputCode: string): Promise<{
+        isValid: boolean;
+        token?: TwoFactorToken;
+    }>;
+    /**
+     * Mask a phone number for display.
+     * @param {string} phone
+     * @returns {string}
+     */
+    maskPhone(phone: string): string;
+    /**
+     * Mask an email address for display.
+     * @param {string} email
+     * @returns {string}
+     */
+    maskEmail(email: string): string;
+}
+export type AuthConfig = import("../types.js").AuthConfig;
+export type TwoFactorToken = import("../types.js").TwoFactorToken;
+import { AuthQueries } from "../queries.js";

package/types/two-factor/totp-provider.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @typedef {import("../types.js").AuthConfig} AuthConfig
+ */
+export class TotpProvider {
+    /**
+     * @param {AuthConfig} config
+     */
+    constructor(config: AuthConfig);
+    config: import("../types.js").AuthConfig;
+    /**
+     * Generate a new base32 TOTP shared secret.
+     * @returns {string}
+     */
+    generateSecret(): string;
+    /**
+     * Build an otpauth:// URI for QR-code provisioning.
+     * @param {string} email
+     * @param {string} secret
+     * @returns {string}
+     */
+    generateQRCode(email: string, secret: string): string;
+    /**
+     * Verify a TOTP code against a secret using the configured drift window.
+     * @param {string} secret
+     * @param {string} code
+     * @returns {boolean}
+     */
+    verify(secret: string, code: string): boolean;
+    /**
+     * Generate random alphanumeric backup codes.
+     * @param {number} [count]
+     * @returns {string[]}
+     */
+    generateBackupCodes(count?: number): string[];
+    /**
+     * Hash a set of backup codes for storage.
+     * @param {string[]} codes
+     * @returns {Promise<string[]>}
+     */
+    hashBackupCodes(codes: string[]): Promise<string[]>;
+    /**
+     * Verify an input backup code against hashed codes.
+     * @param {string[]} hashedCodes
+     * @param {string} inputCode
+     * @returns {Promise<{ isValid: boolean, index: number }>}
+     */
+    verifyBackupCode(hashedCodes: string[], inputCode: string): Promise<{
+        isValid: boolean;
+        index: number;
+    }>;
+    /**
+     * Mask an email address for display.
+     * @param {string} email
+     * @returns {string}
+     */
+    maskEmail(email: string): string;
+}
+export type AuthConfig = import("../types.js").AuthConfig;

package/types/two-factor/two-factor-manager.d.ts

@@ -0,0 +1,191 @@
+/**
+ * @typedef {import("express").Request} Request
+ * @typedef {import("express").Response} Response
+ * @typedef {import("../types.js").AuthConfig} AuthConfig
+ * @typedef {import("../types.js").TwoFactorSetupResult} TwoFactorSetupResult
+ * @typedef {import("../types.js").TwoFactorChallenge} TwoFactorChallenge
+ */
+export class TwoFactorManager {
+    /**
+     * @param {Request} req
+     * @param {Response} res
+     * @param {AuthConfig} config
+     */
+    constructor(req: Request, res: Response, config: AuthConfig);
+    req: import("express").Request<import("express-serve-static-core").ParamsDictionary, any, any, import("qs").ParsedQs, Record<string, any>>;
+    res: import("express").Response<any, Record<string, any>>;
+    config: import("../types.js").AuthConfig;
+    queries: AuthQueries;
+    activityLogger: ActivityLogger;
+    totpProvider: TotpProvider;
+    otpProvider: OtpProvider;
+    setup: {
+        /**
+         * Begin TOTP setup, optionally deferring verification.
+         * @param {boolean} [requireVerification]
+         * @returns {Promise<TwoFactorSetupResult>}
+         * @throws {UserNotLoggedInError|TwoFactorAlreadyEnabledError}
+         */
+        totp: (requireVerification?: boolean) => Promise<TwoFactorSetupResult>;
+        /**
+         * Begin email 2FA setup, optionally deferring verification.
+         * @param {string} [email]
+         * @param {boolean} [requireVerification]
+         * @returns {Promise<void>}
+         * @throws {UserNotLoggedInError|TwoFactorAlreadyEnabledError}
+         */
+        email: (email?: string, requireVerification?: boolean) => Promise<void>;
+        /**
+         * Begin SMS 2FA setup, optionally deferring verification.
+         * @param {string} phone
+         * @param {boolean} [requireVerification]
+         * @returns {Promise<void>}
+         * @throws {UserNotLoggedInError|TwoFactorAlreadyEnabledError}
+         */
+        sms: (phone: string, requireVerification?: boolean) => Promise<void>;
+    };
+    complete: {
+        /**
+         * Complete TOTP setup by verifying a code, returning backup codes.
+         * @param {string} code
+         * @returns {Promise<string[]>}
+         * @throws {UserNotLoggedInError|TwoFactorNotSetupError|TwoFactorAlreadyEnabledError|InvalidTwoFactorCodeError}
+         */
+        totp: (code: string) => Promise<string[]>;
+        /**
+         * Complete email 2FA setup with a verification code.
+         * @param {string} code
+         * @returns {Promise<void>}
+         */
+        email: (code: string) => Promise<void>;
+        /**
+         * Complete SMS 2FA setup with a verification code.
+         * @param {string} code
+         * @returns {Promise<void>}
+         */
+        sms: (code: string) => Promise<void>;
+    };
+    verify: {
+        /**
+         * Verify a TOTP code during the login flow.
+         * @param {string} code
+         * @returns {Promise<void>}
+         * @throws {UserNotLoggedInError|TwoFactorNotSetupError|InvalidTwoFactorCodeError}
+         */
+        totp: (code: string) => Promise<void>;
+        /**
+         * Verify an email OTP during the login flow.
+         * @param {string} code
+         * @returns {Promise<void>}
+         */
+        email: (code: string) => Promise<void>;
+        /**
+         * Verify an SMS OTP during the login flow.
+         * @param {string} code
+         * @returns {Promise<void>}
+         */
+        sms: (code: string) => Promise<void>;
+        /**
+         * Verify a backup code during the login flow, consuming it on success.
+         * @param {string} code
+         * @returns {Promise<void>}
+         * @throws {UserNotLoggedInError|TwoFactorNotSetupError|InvalidBackupCodeError}
+         */
+        backupCode: (code: string) => Promise<void>;
+        /**
+         * Verify an OTP against any available email/SMS mechanism during login.
+         * @param {string} code
+         * @returns {Promise<void>}
+         * @throws {UserNotLoggedInError|TwoFactorNotSetupError|InvalidTwoFactorCodeError}
+         */
+        otp: (code: string) => Promise<void>;
+    };
+    /**
+     * @returns {number | null}
+     */
+    getAccountId(): number | null;
+    /**
+     * @returns {string | null}
+     */
+    getEmail(): string | null;
+    /**
+     * Whether the current account has any verified 2FA method.
+     * @returns {Promise<boolean>}
+     */
+    isEnabled(): Promise<boolean>;
+    /**
+     * Whether the current account has TOTP enabled.
+     * @returns {Promise<boolean>}
+     */
+    totpEnabled(): Promise<boolean>;
+    /**
+     * Whether the current account has email 2FA enabled.
+     * @returns {Promise<boolean>}
+     */
+    emailEnabled(): Promise<boolean>;
+    /**
+     * Whether the current account has SMS 2FA enabled.
+     * @returns {Promise<boolean>}
+     */
+    smsEnabled(): Promise<boolean>;
+    /**
+     * List the verified 2FA mechanisms for the current account.
+     * @returns {Promise<number[]>}
+     */
+    getEnabledMethods(): Promise<number[]>;
+    /**
+     * Mark an OTP-based (email/SMS) method as verified to complete its setup.
+     * @param {number} mechanism EMAIL or SMS
+     * @param {string} code
+     * @returns {Promise<void>}
+     * @throws {UserNotLoggedInError|TwoFactorNotSetupError|TwoFactorAlreadyEnabledError}
+     */
+    completeOtpSetup(mechanism: number, code: string): Promise<void>;
+    /**
+     * Verify an email/SMS OTP using the selector stored during login.
+     * @param {number} mechanism EMAIL or SMS
+     * @param {string} code
+     * @returns {Promise<void>}
+     * @throws {UserNotLoggedInError|TwoFactorNotSetupError|InvalidTwoFactorCodeError}
+     */
+    verifyOtp(mechanism: number, code: string): Promise<void>;
+    /**
+     * Disable a 2FA mechanism for the current account.
+     * @param {number} mechanism
+     * @returns {Promise<void>}
+     * @throws {UserNotLoggedInError|TwoFactorNotSetupError}
+     */
+    disable(mechanism: number): Promise<void>;
+    /**
+     * Regenerate and store new backup codes for the TOTP method.
+     * @returns {Promise<string[]>}
+     * @throws {UserNotLoggedInError|TwoFactorNotSetupError}
+     */
+    generateNewBackupCodes(): Promise<string[]>;
+    /**
+     * Get the stored contact (email/phone) for an OTP mechanism.
+     * @param {number} mechanism EMAIL or SMS
+     * @returns {Promise<string | null>}
+     */
+    getContact(mechanism: number): Promise<string | null>;
+    /**
+     * Build the otpauth:// URI for the current account's TOTP secret.
+     * @returns {Promise<string | null>}
+     */
+    getTotpUri(): Promise<string | null>;
+    /**
+     * Build a 2FA challenge for an account, issuing OTPs for email/SMS methods.
+     * @param {number} accountId
+     * @returns {Promise<TwoFactorChallenge>}
+     */
+    createChallenge(accountId: number): Promise<TwoFactorChallenge>;
+}
+export type Request = import("express").Request;
+export type Response = import("express").Response;
+export type AuthConfig = import("../types.js").AuthConfig;
+export type TwoFactorSetupResult = import("../types.js").TwoFactorSetupResult;
+export type TwoFactorChallenge = import("../types.js").TwoFactorChallenge;
+import { AuthQueries } from "../queries.js";
+import { ActivityLogger } from "../activity-logger.js";
+import { TotpProvider } from "./totp-provider.js";
+import { OtpProvider } from "./otp-provider.js";