@epic-web/totp/index.d.ts

Create and verify cryptographically secure Time-based One-time Passwords (TOTP) using the HMAC-based One-time Password (HOTP) algorithm.

/**
 * Creates a time-based one-time password (TOTP). This handles creating a random
 * secret (base32 encoded), and generating a TOTP for the current time. As a
 * convenience, it also returns the config options used to generate the TOTP.
 *
 * @param {Object} [options] Configuration options for the TOTP.
 * @param {number} [options.period=30] The number of seconds for the OTP to be
 * valid. Defaults to 30.
 * @param {number} [options.digits=6] The length of the OTP. Defaults to 6.
 * @param {HashAlgorithm} [options.algorithm='SHA-1'] The algorithm to use. Defaults to
 * SHA-1.
 * @param {string} [options.charSet='0123456789'] - The character set to use, defaults to the numbers 0-9.
 * @param {string} [options.secret] The secret to use for the TOTP. It should be
 * base32 encoded (you can use https://npm.im/thirty-two). Defaults to a random
 * secret: base32Encode(crypto.getRandomValues(new Uint8Array(10)), 'RFC4648').
 * @returns {Promise<{otp: string, secret: string, period: number, digits: number, algorithm: string, charSet: string}>}
 * The OTP, secret, and config options used to generate the OTP.
 */
export function generateTOTP({ period, digits, algorithm, secret, charSet, }?: {
    period?: number;
    digits?: number;
    algorithm?: HashAlgorithm;
    charSet?: string;
    secret?: string;
}): Promise<{
    otp: string;
    secret: string;
    period: number;
    digits: number;
    algorithm: string;
    charSet: string;
}>;
/**
 * Generates a otpauth:// URI which you can use to generate a QR code or users
 * can manually enter into their password manager.
 *
 * @param {Object} options Configuration options for the TOTP Auth URI.
 * @param {number} options.period The number of seconds for the OTP to be valid.
 * @param {number} options.digits The length of the OTP.
 * @param {HashAlgorithm} options.algorithm The algorithm to use. (Note, we
 * automatically remove the dashes from the algorithm name because the otpauth
 * URI spec requires it.)
 * @param {string} options.secret The secret to use for the TOTP Auth URI.
 * @param {string} options.accountName A way to uniquely identify this Auth URI
 * (in case they have multiple of these).
 * @param {string} options.issuer The issuer to use for the TOTP Auth URI.
 *
 * @returns {string} The OTP Auth URI
 */
export function getTOTPAuthUri({ period, digits, algorithm, secret, accountName, issuer, }: {
    period: number;
    digits: number;
    algorithm: HashAlgorithm;
    secret: string;
    accountName: string;
    issuer: string;
}): string;
/**
 * Verifies a time-based one-time password (TOTP). This handles decoding the
 * secret (base32 encoded), and verifying the OTP for the current time.
 *
 * @param {Object} options The otp, secret, and configuration options for the
 * TOTP.
 * @param {string} options.otp The OTP to verify.
 * @param {string} options.secret The secret to use for the TOTP.
 * @param {number} [options.period] The number of seconds for the OTP to be valid.
 * @param {number} [options.digits] The length of the OTP.
 * @param {HashAlgorithm} [options.algorithm] The algorithm to use.
 * @param {string} [options.charSet] - The character set to use, defaults to the numbers 0-9.
 * @param {number} [options.window] The number of OTPs to check before and after
 * the current OTP. Defaults to 1.
 *
 * @returns {Promise<{delta: number}|null>} an object with "delta" which is the delta
 * between the current OTP and the OTP that was verified, or null if the OTP is
 * invalid.
 */
export function verifyTOTP({ otp, secret, period, digits, algorithm, charSet, window, }: {
    otp: string;
    secret: string;
    period?: number;
    digits?: number;
    algorithm?: HashAlgorithm;
    charSet?: string;
    window?: number;
}): Promise<{
    delta: number;
} | null>;
/**
 * For all available algorithms, refer to the following:
 * https://developer.mozilla.org/en-US/docs/Web/API/HmacImportParams#hash
 */
export type HashAlgorithm = "SHA-1" | "SHA-256" | "SHA-386" | "SHA-512" | (string & {});