@otplib/v12-adapter 13.0.0

package/dist/index.d.ts

@@ -0,0 +1,427 @@
+import { HashAlgorithm, CryptoPlugin, Base32Plugin } from '@otplib/core';
+export { NobleCryptoPlugin } from '@otplib/plugin-crypto-noble';
+export { ScureBase32Plugin } from '@otplib/plugin-base32-scure';
+
+/**
+ * @otplib/v12-adapter
+ *
+ * v12-compatible type definitions for migration adapter.
+ * These types mirror the v12 API to provide drop-in compatibility.
+ */
+
+/**
+ * v12-style hash algorithms constant
+ */
+declare const HashAlgorithms: {
+    readonly SHA1: "sha1";
+    readonly SHA256: "sha256";
+    readonly SHA512: "sha512";
+};
+type HashAlgorithms = (typeof HashAlgorithms)[keyof typeof HashAlgorithms];
+/**
+ * v12-style key encodings constant
+ */
+declare const KeyEncodings: {
+    readonly ASCII: "ascii";
+    readonly HEX: "hex";
+    readonly BASE32: "base32";
+    readonly BASE64: "base64";
+    readonly LATIN1: "latin1";
+    readonly UTF8: "utf8";
+};
+type KeyEncodings = (typeof KeyEncodings)[keyof typeof KeyEncodings];
+/**
+ * v12-style secret key type (string-based)
+ */
+type SecretKey = string;
+/**
+ * Base32 encoded secret key
+ */
+type Base32SecretKey = string;
+/**
+ * v12-style createDigest function signature
+ */
+type CreateDigest<T = string> = (algorithm: HashAlgorithm, hmacKey: T, counter: T) => T;
+/**
+ * v12-style createHmacKey function signature
+ */
+type CreateHmacKey<T = string> = (algorithm: HashAlgorithm, secret: SecretKey, encoding: KeyEncodings) => T;
+/**
+ * v12-style createRandomBytes function signature
+ */
+type CreateRandomBytes<T = string> = (size: number, encoding: KeyEncodings) => T;
+/**
+ * v12-style keyEncoder function signature
+ */
+type KeyEncoder<T = Base32SecretKey> = (secret: SecretKey, encoding: KeyEncodings) => T;
+/**
+ * v12-style keyDecoder function signature
+ */
+type KeyDecoder<T = SecretKey> = (encodedSecret: Base32SecretKey, encoding: KeyEncodings) => T;
+/**
+ * v12-compatible HOTP options
+ */
+type HOTPOptions<T = string> = {
+    /** Algorithm for HMAC (default: sha1) */
+    algorithm?: HashAlgorithm;
+    /** Creates the digest for token generation */
+    createDigest?: CreateDigest<T>;
+    /** Formats the secret into HMAC key */
+    createHmacKey?: CreateHmacKey<T>;
+    /** Number of digits in token (default: 6) */
+    digits?: number;
+    /** Secret encoding (default: ascii) */
+    encoding?: KeyEncodings;
+    /** Pre-computed digest (use with caution) */
+    digest?: string;
+    /** v13 crypto plugin (internal use) */
+    crypto?: CryptoPlugin;
+    /** v13 base32 plugin (internal use) */
+    base32?: Base32Plugin;
+};
+/**
+ * v12-compatible TOTP options
+ */
+type TOTPOptions<T = string> = HOTPOptions<T> & {
+    /** Starting epoch in milliseconds (default: Date.now()) */
+    epoch?: number;
+    /** Time step in seconds (default: 30) */
+    step?: number;
+    /** Verification window - number of steps or [past, future] */
+    window?: number | [number, number];
+};
+/**
+ * v12-compatible Authenticator options
+ */
+type AuthenticatorOptions<T = string> = TOTPOptions<T> & {
+    /** Encodes secret to Base32 */
+    keyEncoder?: KeyEncoder<T>;
+    /** Decodes Base32 secret */
+    keyDecoder?: KeyDecoder<T>;
+    /** Creates random bytes for secret generation */
+    createRandomBytes?: CreateRandomBytes<T>;
+};
+/**
+ * Resolved HOTP options with guaranteed defaults
+ */
+type ResolvedHOTPOptions = {
+    algorithm: HashAlgorithm;
+    digits: number;
+    encoding: KeyEncodings;
+    crypto: CryptoPlugin;
+    base32: Base32Plugin;
+};
+/**
+ * Resolved TOTP options with guaranteed defaults
+ */
+type ResolvedTOTPOptions = ResolvedHOTPOptions & {
+    epoch: number;
+    step: number;
+    window: number | [number, number];
+};
+/**
+ * Resolved Authenticator options with guaranteed defaults
+ */
+type ResolvedAuthenticatorOptions = ResolvedTOTPOptions & {
+    keyEncoder?: KeyEncoder;
+    keyDecoder?: KeyDecoder;
+};
+
+/**
+ * @otplib/v12-adapter
+ *
+ * v12-compatible HOTP class implementation.
+ * Provides synchronous API wrapper around v13's HOTP implementation.
+ */
+
+/**
+ * Converts a digest to a token of a specified length.
+ * Uses dynamicTruncate and truncateDigits from core.
+ */
+declare function hotpDigestToToken(hexDigest: string, digits: number): string;
+/**
+ * v12-compatible HOTP class
+ *
+ * Provides the same API as otplib v12 HOTP class while using v13's
+ * implementation internally.
+ *
+ * @example
+ * ```typescript
+ * import { HOTP } from '@otplib/v12-adapter';
+ *
+ * const hotp = new HOTP();
+ * const secret = 'JBSWY3DPEHPK3PXP';
+ * const token = hotp.generate(secret, 0);
+ * const isValid = hotp.check(token, secret, 0);
+ * ```
+ */
+declare class HOTP<T extends HOTPOptions = HOTPOptions> {
+    /**
+     * Stored options that can be modified
+     */
+    protected _options: Partial<T>;
+    /**
+     * Default options applied to all operations
+     */
+    protected _defaultOptions: Partial<T>;
+    constructor(defaultOptions?: Partial<T>);
+    /**
+     * Get current options (merged with defaults)
+     */
+    get options(): Partial<T>;
+    /**
+     * Set options (replaces current options)
+     */
+    set options(value: Partial<T>);
+    /**
+     * Creates a new instance with the specified default options
+     */
+    create(defaultOptions?: Partial<T>): HOTP<T>;
+    /**
+     * Returns class options polyfilled with default values
+     */
+    allOptions(): Readonly<ResolvedHOTPOptions>;
+    /**
+     * Reset options to defaults
+     */
+    resetOptions(): this;
+    /**
+     * Generate an HOTP token
+     */
+    generate(secret: SecretKey, counter: number): string;
+    /**
+     * Check if a token is valid for the given secret and counter
+     */
+    check(token: string, secret: SecretKey, counter: number): boolean;
+    /**
+     * Verify a token (object-based API)
+     */
+    verify(opts: {
+        token: string;
+        secret: SecretKey;
+        counter: number;
+    }): boolean;
+    /**
+     * Generate an otpauth:// URI for HOTP
+     */
+    keyuri(accountName: string, issuer: string, secret: SecretKey, counter: number): string;
+}
+
+/**
+ * @otplib/v12-adapter
+ *
+ * v12-compatible TOTP class implementation.
+ * Provides synchronous API wrapper around v13's TOTP implementation.
+ */
+
+/**
+ * v12-compatible TOTP class
+ *
+ * Provides the same API as otplib v12 TOTP class while using v13's
+ * implementation internally.
+ *
+ * @example
+ * ```typescript
+ * import { TOTP } from '@otplib/v12-adapter';
+ *
+ * const totp = new TOTP();
+ * const secret = 'JBSWY3DPEHPK3PXP';
+ * const token = totp.generate(secret);
+ * const isValid = totp.check(token, secret);
+ * ```
+ */
+declare class TOTP<T extends TOTPOptions = TOTPOptions> extends HOTP<T> {
+    constructor(defaultOptions?: Partial<T>);
+    /**
+     * Creates a new TOTP instance with the specified default options
+     */
+    create(defaultOptions?: Partial<T>): TOTP<T>;
+    /**
+     * Returns class options polyfilled with TOTP default values
+     */
+    allOptions(): Readonly<ResolvedTOTPOptions>;
+    /**
+     * Generate a TOTP token
+     *
+     * @param secret - The secret key
+     * @returns The OTP token
+     */
+    generate(secret: SecretKey): string;
+    /**
+     * Check if a token is valid for the given secret
+     *
+     * @param token - The token to verify
+     * @param secret - The secret key
+     * @returns true if valid
+     */
+    check(token: string, secret: SecretKey): boolean;
+    /**
+     * Check token and return the time window delta
+     *
+     * @param token - The token to verify
+     * @param secret - The secret key
+     * @returns Window delta (0 = current, positive = future, negative = past), null if invalid
+     */
+    checkDelta(token: string, secret: SecretKey): number | null;
+    /**
+     * Verify a token (object-based API)
+     *
+     * @param opts - Verification options
+     * @returns true if valid
+     */
+    verify(opts: {
+        token: string;
+        secret: SecretKey;
+    }): boolean;
+    /**
+     * Generate an otpauth:// URI for TOTP
+     *
+     * @param accountName - Account name for the URI
+     * @param issuer - Issuer name
+     * @param secret - The secret key (should be Base32 for QR codes)
+     * @returns The otpauth:// URI
+     */
+    keyuri(accountName: string, issuer: string, secret: SecretKey): string;
+    /**
+     * Get time used in current step (seconds elapsed in current window)
+     *
+     * @returns Seconds used in current step
+     */
+    timeUsed(): number;
+    /**
+     * Get time remaining until next token
+     *
+     * @returns Seconds remaining in current step
+     */
+    timeRemaining(): number;
+}
+
+/**
+ * @otplib/v12-adapter
+ *
+ * v12-compatible Authenticator class implementation.
+ * Provides same API as v12 with Base32 encoding support.
+ */
+
+/**
+ * v12-compatible Authenticator class
+ *
+ * The Authenticator class is a TOTP variant that uses Base32-encoded secrets
+ * by default, making it compatible with Google Authenticator and similar apps.
+ *
+ * @example
+ * ```typescript
+ * import { Authenticator } from '@otplib/v12-adapter';
+ *
+ * const authenticator = new Authenticator();
+ * const secret = authenticator.generateSecret();
+ * const token = authenticator.generate(secret);
+ * const isValid = authenticator.check(token, secret);
+ * const uri = authenticator.keyuri('user@example.com', 'MyApp', secret);
+ * ```
+ */
+declare class Authenticator<T extends AuthenticatorOptions = AuthenticatorOptions> extends TOTP<T> {
+    constructor(defaultOptions?: Partial<T>);
+    /**
+     * Creates a new Authenticator instance with the specified default options
+     */
+    create(defaultOptions?: Partial<T>): Authenticator<T>;
+    /**
+     * Returns class options polyfilled with Authenticator default values
+     */
+    allOptions(): Readonly<ResolvedAuthenticatorOptions>;
+    /**
+     * Generate an OTP token from a Base32 secret
+     *
+     * @param secret - Base32-encoded secret
+     * @returns The OTP token
+     */
+    generate(secret: Base32SecretKey): string;
+    /**
+     * Check if a token is valid for the given Base32 secret
+     *
+     * @param token - The token to verify
+     * @param secret - Base32-encoded secret
+     * @returns true if valid
+     */
+    check(token: string, secret: Base32SecretKey): boolean;
+    /**
+     * Check token and return the time window delta
+     *
+     * @param token - The token to verify
+     * @param secret - Base32-encoded secret
+     * @returns Window delta (0 = current, positive = future, negative = past), null if invalid
+     */
+    checkDelta(token: string, secret: Base32SecretKey): number | null;
+    /**
+     * Verify a token (object-based API)
+     *
+     * @param opts - Verification options
+     * @returns true if valid
+     */
+    verify(opts: {
+        token: string;
+        secret: Base32SecretKey;
+    }): boolean;
+    /**
+     * Encode a raw secret to Base32
+     *
+     * @param secret - Raw secret string
+     * @returns Base32-encoded secret
+     */
+    encode(secret: SecretKey): Base32SecretKey;
+    /**
+     * Decode a Base32 secret to raw string
+     *
+     * @param secret - Base32-encoded secret
+     * @returns Raw secret string
+     */
+    decode(secret: Base32SecretKey): SecretKey;
+    /**
+     * Generate a random Base32-encoded secret
+     *
+     * @param numberOfBytes - Number of bytes for the secret (default: 20)
+     * @returns Base32-encoded secret
+     */
+    generateSecret(numberOfBytes?: number): Base32SecretKey;
+}
+
+/**
+ * Pre-configured HOTP instance
+ *
+ * @example
+ * ```typescript
+ * import { hotp } from '@otplib/v12-adapter';
+ *
+ * const token = hotp.generate('JBSWY3DPEHPK3PXP', 0);
+ * const isValid = hotp.check(token, 'JBSWY3DPEHPK3PXP', 0);
+ * ```
+ */
+declare const hotp: HOTP<HOTPOptions>;
+/**
+ * Pre-configured TOTP instance
+ *
+ * @example
+ * ```typescript
+ * import { totp } from '@otplib/v12-adapter';
+ *
+ * const token = totp.generate('JBSWY3DPEHPK3PXP');
+ * const isValid = totp.check(token, 'JBSWY3DPEHPK3PXP');
+ * ```
+ */
+declare const totp: TOTP<TOTPOptions>;
+/**
+ * Pre-configured Authenticator instance
+ *
+ * @example
+ * ```typescript
+ * import { authenticator } from '@otplib/v12-adapter';
+ *
+ * const secret = authenticator.generateSecret();
+ * const token = authenticator.generate(secret);
+ * const isValid = authenticator.check(token, secret);
+ * ```
+ */
+declare const authenticator: Authenticator<AuthenticatorOptions>;
+
+export { Authenticator, type AuthenticatorOptions, type Base32SecretKey, type CreateDigest, type CreateHmacKey, type CreateRandomBytes, HOTP, type HOTPOptions, HashAlgorithms, type KeyDecoder, type KeyEncoder, KeyEncodings, type SecretKey, TOTP, type TOTPOptions, authenticator, hotp, hotpDigestToToken, totp };