@yutons/notp/dist/index.d.ts

one-time password generator for javascript

/**
 * HMAC 算法类型枚举
 */
declare const AlgorithmValues: {
    readonly SHA1: "sha1";
    readonly SHA256: "sha256";
    readonly SHA512: "sha512";
    readonly SM3: "sm3";
};
type Algorithm = typeof AlgorithmValues[keyof typeof AlgorithmValues];
declare const Algorithm: {
    readonly SHA1: "sha1";
    readonly SHA256: "sha256";
    readonly SHA512: "sha512";
    readonly SM3: "sm3";
};
/**
 * 默认配置
 */
declare class Default {
    static readonly ALGORITHM: Algorithm;
    static readonly PERIOD = 30;
    static readonly DIGITS = 6;
    static readonly WINDOW = 0;
    /**
     * 运行时支持的算法列表（自动从 enum 生成）
     */
    static SUPPORTED_ALGORITHMS: readonly Algorithm[];
    /**
     * 类型守卫：检查字符串是否为支持的算法
     */
    static isSupportedAlgorithm(value: string): value is Algorithm;
}

/**
 * HOTP (HMAC-based One-Time Password) 算法实现
 * 使用时间戳作为计数器
 * 遵循 RFC 4226 标准
 * 兼容浏览器环境
 */
declare class HOTP {
    private _secret;
    private _counter;
    private _digits;
    private _algorithm;
    /**
     * 构造函数
     * @param secret - 共享密钥 (通常为 Base32 编码)
     * @param counter - 计数器初始值
     * @param digits - 生成的一次性密码的位数，默认为 6
     * @param algorithm - HMAC 哈希算法，默认为 'sha1'
     */
    constructor(secret: string, counter?: number, digits?: number, algorithm?: Algorithm);
    get secret(): string;
    set secret(value: string);
    get counter(): number;
    set counter(value: number);
    get digits(): number;
    set digits(value: number);
    get algorithm(): Algorithm;
    set algorithm(value: Algorithm);
    /**
     * 生成指定计数器值的一次性密码
     * @param counter - 指定的计数器值 (可选，如果不提供则使用实例的 counter)
     * @returns 生成的一次性密码 (字符串)
     */
    generate(counter?: number): string;
    /**
     * 验证提供的 OTP 是否与指定计数器值生成的 OTP 匹配
     * @param otp - 要验证的 OTP (字符串)
     * @param counter - 用于生成预期 OTP 的计数器值
     * @returns 验证结果 (true 或 false)
     */
    verify(otp: string, counter: number): boolean;
    /**
     * 将整数转换为 8 字节的 Uint8Array (大端序)
     */
    private intTo8Bytes;
    /**
     * 将 Uint8Array 转为十六进制字符串
     */
    private bytesToHex;
    /**
     * 将十六进制字符串转为 Uint8Array
     */
    private hexToBytes;
    next(): string;
    getConfiguration(): {
        secret: string;
        counter: number;
        digits: number;
        algorithm: 'sha1' | 'sha256' | 'sha512' | 'sm3';
    };
}

/**
 * TOTP (Time-based One-Time Password) 算法实现
 * 基于 HOTP，使用时间戳作为计数器
 * 遵循 RFC 6238 标准
 */
declare class TOTP {
    private _hotp;
    private _period;
    private _timestamp;
    private _algorithm;
    /**
     * 构造函数
     * @param secret - 共享密钥 (通常为 Base32 编码)
     * @param period - 时间步长（周期），单位为秒，默认为 30 秒
     * @param digits - 生成的一次性密码的位数，默认为 6
     * @param algorithm - HMAC 哈希算法，默认为 'sha1'
     */
    constructor(secret: string, period?: number, digits?: number, algorithm?: Algorithm);
    /**
     * 获取当前共享密钥
     */
    get secret(): string;
    /**
     * 设置共享密钥
     * @param value - 新的共享密钥
     */
    set secret(value: string);
    /**
     * 获取当前时间步长（周期）
     */
    get period(): number;
    /**
     * 设置时间步长（周期）
     * @param value - 新的周期（秒）
     */
    set period(value: number);
    /**
     * 获取生成密码的位数
     */
    get digits(): number;
    /**
     * 设置生成密码的位数
     * @param value - 新的位数 (通常为 6, 7, 8)
     */
    set digits(value: number);
    /**
     * 获取当前使用的哈希算法
     */
    get algorithm(): Algorithm;
    /**
     * 设置哈希算法
     * @param value - 新的算法 ('sha1', 'sha256', 'sha512', 'sm3')
     */
    set algorithm(value: Algorithm);
    /**
     * 获取当前用于计算的模拟时间戳（毫秒）
     * 返回 null 表示使用系统当前时间
     */
    get timestamp(): number | null;
    /**
     * 设置用于计算的模拟时间戳（毫秒）
     * 设置为 null 时，将使用系统当前时间
     * @param value - 模拟的时间戳（毫秒），或 null
     */
    set timestamp(value: number | null);
    /**
     * 计算基于当前时间（或模拟时间）的计数器值
     * @returns 计数器值
     */
    private getTimeCounter;
    /**
     * 生成当前时间窗口的一次性密码
     * @returns 生成的一次性密码 (字符串)
     */
    generate(): string;
    /**
     * 验证提供的 OTP 是否有效
     * 为了容忍客户端和服务器之间的时间偏差，通常会检查当前时间窗口前后几个窗口
     * @param otp - 要验证的 OTP (字符串)
     * @param window - 允许的时间窗口偏差（向前和向后），默认为 1
     *                 例如 window=1 会检查 T-1, T, T+1 三个时间窗口
     * @returns 验证结果 (true 或 false)
     */
    verify(otp: string, window?: number): boolean;
    /**
     * 获取当前时间窗口的剩余有效时间（秒）
     * @returns 剩余有效时间（秒），如果为负数表示已过期
     */
    timeRemaining(): number;
    /**
     * 获取当前时间窗口的开始时间（Unix 时间戳，秒）
     * @returns 当前时间窗口的开始时间
     */
    currentPeriodStart(): number;
    /**
     * 获取当前配置的摘要信息
     */
    getConfiguration(): {
        secret: string;
        period: number;
        digits: number;
        algorithm: 'sha1' | 'sha256' | 'sha512' | 'sm3';
        timestamp: number | null;
    };
}

/**
 * Base32 编码、解码、生成随机密钥
 */
declare class Base32 {
    static readonly BASE32_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
    /**
     * 生成Base32随机密钥
     * @param length 密钥长度（字节），默认为20字节
     * @returns Base32编码的密钥字符串
     */
    static generate(length?: number): string;
    /**
     * Base32编码
     * @param bytes 需要编码的字节数组
     * @return Base32编码的字符串
     */
    static encode(bytes: Uint8Array<any>): string;
    /**
     * Base32解码
     * @param secret Base32编码的字符串
     * @returns 解码后的字节数组
     */
    static decode(secret: string): Uint8Array<any>;
}

declare const notp: {
    Algorithm: {
        readonly SHA1: "sha1";
        readonly SHA256: "sha256";
        readonly SHA512: "sha512";
        readonly SM3: "sm3";
    };
    Default: typeof Default;
    Base32: typeof Base32;
    HOTP: typeof HOTP;
    TOTP: typeof TOTP;
};

export { notp as default };