@nowarajs/totp 1.2.0 → 1.2.2

package/README.md

@@ -1,41 +1,32 @@
-# 🔐 NowaraJS - TOTP
+# 🔐 NowaraJS TOTP
+
+Let's be honest: there are already packages like `totp-generator` that do this. I built this one mostly for myself—to learn how TOTP/HOTP actually works under the hood, and to have a lightweight alternative I fully understand.
+
+## Why this package?
+
+No grand mission here. I wanted:
+1. **To learn** how RFC 6238/4226 work in practice
+2. **A tiny footprint** without pulling half of npm
+3. **Something I control** for my own projects
+
+If you're looking for battle-tested libraries, check out the established ones. If you want something small and readable, this might be for you.
 
 ## 📌 Table of Contents
 
-- [🔐 NowaraJS - TOTP](#-nowarajs---totp)
-	- [📌 Table of Contents](#-table-of-contents)
-	- [📝 Description](#-description)
-	- [✨ Features](#-features)
-	- [🔧 Installation](#-installation)
-	- [⚙️ Usage](#-usage)
-		- [Basic TOTP Generation](#basic-totp-generation)
-		- [TOTP Verification](#totp-verification)
-		- [HOTP Support](#hotp-support)
-		- [OTPAuth URI Generation](#otpauth-uri-generation)
-		- [Secret Generation](#secret-generation)
-	- [🔑 Advanced Configuration](#-advanced-configuration)
-	- [🛠️ Utilities](#-utilities)
-	- [📚 API Reference](#-api-reference)
-	- [⚖️ License](#-license)
-	- [📧 Contact](#-contact)
-
-## 📝 Description
-
-> A comprehensive Time-based One-Time Password (TOTP) and HMAC-based One-Time Password (HOTP) implementation for TypeScript/JavaScript.
-
-**NowaraJS TOTP** provides a secure and RFC-compliant implementation of TOTP and HOTP algorithms with full support for QR code generation, secret management, and various authentication configurations. Perfect for implementing two-factor authentication (2FA) in your applications.
+- [Features](#-features)
+- [Installation](#-installation)
+- [Usage](#-usage)
+- [API Reference](#-api-reference)
+- [License](#-license)
+- [Contact](#-contact)
 
 ## ✨ Features
 
-- 🔐 **RFC 6238 TOTP**: Full RFC-compliant Time-based One-Time Password implementation
-- 🔑 **RFC 4226 HOTP**: Complete HMAC-based One-Time Password support
-- 📱 **QR Code Support**: Generate OTPAuth URIs for easy mobile app integration
-- 🔒 **Crypto Secure**: Uses Web Crypto API for secure random number generation
-- ⚡ **High Performance**: Optimized for speed with minimal dependencies
-- 🛠️ **Configurable**: Support for different algorithms (SHA-1, SHA-256, SHA-512)
-- 📐 **Flexible Digits**: Support for 6-8 digit codes
-- ⏰ **Time Window**: Configurable time periods and verification windows
-- 🎯 **Base32 Encoding**: Built-in Base32 encoding/decoding utilities
+- 🔐 **RFC Compliant**: Full RFC 6238 (TOTP) and RFC 4226 (HOTP) implementation.
+- 📱 **QR Code Ready**: Generate OTPAuth URIs compatible with Google Authenticator, Authy, etc.
+- 🔒 **Crypto Secure**: Uses Web Crypto API for truly random secret generation.
+- 🛠️ **Flexible**: SHA-1, SHA-256, SHA-512 algorithms with 6-8 digit codes.
+- 📦 **Zero Dependencies**: Pure TypeScript, tiny footprint.
 
 ## 🔧 Installation
 
@@ -45,168 +36,88 @@ bun add @nowarajs/totp @nowarajs/error
 
 ## ⚙️ Usage
 
-### Basic TOTP Generation
+### Generate a TOTP Code
+
+Use this when you need to generate a one-time password for the current time window.
 
 ```ts
 import { totp, generateSecretBytes, base32Encode } from '@nowarajs/totp';
 
-// Generate a secret
-const secret = generateSecretBytes(20); // 20 bytes = 160 bits
-const secretBase32 = base32Encode(secret);
+// Generate a cryptographically secure secret
+const secret = generateSecretBytes(20);
 
-// Generate TOTP code
+// Generate the current TOTP code
 const code = await totp(secret, {
-	algorithm: 'SHA-1',
-	digits: 6,
-	period: 30
+    algorithm: 'SHA-1',
+    digits: 6,
+    period: 30
 });
 
-console.log('TOTP Code:', code); // e.g., "123456"
+console.log('Your code:', code); // e.g., "847263"
 ```
 
-### TOTP Verification
+### Verify a User's Code
+
+Use this to validate the code your user just entered. The `window` option handles clock drift gracefully.
 
 ```ts
 import { verifyTotp } from '@nowarajs/totp';
 
-// Verify a TOTP code
 const isValid = await verifyTotp(secret, userInputCode, {
-	algorithm: 'SHA-1',
-	digits: 6,
-	period: 30,
-	window: 1 // Allow 1 time step before/after current time
+    algorithm: 'SHA-1',
+    digits: 6,
+    period: 30,
+    window: 1 // Accept codes from ±30 seconds
 });
 
-if (isValid) {
-	console.log('✅ Code is valid!');
-} else {
-	console.log('❌ Invalid code');
-}
+if (isValid) console.log('✅ Access granted');
+else console.log('❌ Invalid code');
 ```
 
-### HOTP Support
+### Generate a QR Code URI
 
-```ts
-import { hotp } from '@nowarajs/totp';
-
-// Generate HOTP code with counter
-const counter = 123;
-const hotpCode = await hotp(secret, counter, {
-	algorithm: 'SHA-1',
-	digits: 6
-});
-
-console.log('HOTP Code:', hotpCode);
-```
-
-### OTPAuth URI Generation
+Use this to let users scan a QR code with their authenticator app.
 
 ```ts
-import { buildOtpAuthUri, base32Encode } from '@nowarajs/totp';
+import { buildOtpAuthUri, generateSecretBytes, base32Encode } from '@nowarajs/totp';
 
 const secret = generateSecretBytes(20);
 const secretBase32 = base32Encode(secret);
 
-// Create URI for QR code
 const uri = buildOtpAuthUri({
-	secretBase32,
-	label: 'user@example.com',
-	issuer: 'MyApp',
-	algorithm: 'SHA-1',
-	digits: 6,
-	period: 30
+    secretBase32,
+    label: 'user@example.com',
+    issuer: 'MyApp',
+    algorithm: 'SHA-1',
+    digits: 6,
+    period: 30
 });
 
-console.log('QR Code URI:', uri);
+// Feed this URI to any QR code library
+console.log(uri);
 // otpauth://totp/user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=MyApp
 ```
 
-### Secret Generation
+### HOTP (Counter-Based)
 
-```ts
-import { generateSecretBytes, base32Encode, base32Decode } from '@nowarajs/totp/utils';
-
-// Generate cryptographically secure secret
-const secret = generateSecretBytes(32); // 256 bits for extra security
-
-// Encode for storage/transmission
-const encoded = base32Encode(secret);
-console.log('Base32 Secret:', encoded);
-
-// Decode when needed
-const decoded = base32Decode(encoded);
-console.log('Original bytes match:', secret.every((byte, i) => byte === decoded[i]));
-```
-
-## 🔑 Advanced Configuration
-
-### Custom Algorithm and Settings
+Use this when you need counter-based OTPs instead of time-based ones.
 
 ```ts
-// Use SHA-256 with 8 digits and 60-second period
-const advancedCode = await totp(secret, {
-	algorithm: 'SHA-256',
-	digits: 8,
-	period: 60
-});
+import { hotp } from '@nowarajs/totp';
 
-// Verify with larger time window for clock drift tolerance
-const isValid = await verifyTotp(secret, userCode, {
-	algorithm: 'SHA-256',
-	digits: 8,
-	period: 60,
-	window: 2 // Allow ±2 time steps (±2 minutes)
+const code = await hotp(secret, 123, {
+    algorithm: 'SHA-1',
+    digits: 6
 });
 ```
 
-### Parse Existing OTPAuth URIs
-
-```ts
-import { parseOtpAuthUri } from '@nowarajs/totp';
-
-const uri = 'otpauth://totp/Example:alice@google.com?secret=JBSWY3DPEHPK3PXP&issuer=Example';
-const parsed = parseOtpAuthUri(uri);
-
-console.log(parsed);
-// {
-//   type: 'totp',
-//   label: 'Example:alice@google.com',
-//   secret: 'JBSWY3DPEHPK3PXP',
-//   issuer: 'Example',
-//   algorithm: 'SHA-1',
-//   digits: 6,
-//   period: 30
-// }
-```
-
-## 🛠️ Utilities
-
-The package includes several utility functions available through subpath imports:
-
-```ts
-// Base32 encoding/decoding
-import { base32Encode, base32Decode } from '@nowarajs/totp/utils';
-
-// Secret generation
-import { generateSecretBytes } from '@nowarajs/totp/utils';
-
-// Time utilities
-import { timeRemaining } from '@nowarajs/totp/utils';
-
-// Get seconds until next TOTP generation
-const remaining = timeRemaining(30); // for 30-second period
-console.log(`Next code in ${remaining} seconds`);
-```
-
 ## 📚 API Reference
 
-You can find the complete API reference documentation for `NowaraJS TOTP` at:
-
-- [Reference Documentation](https://nowarajs.github.io/totp/)
+Full docs: [nowarajs.github.io/totp](https://nowarajs.github.io/totp/)
 
 ## ⚖️ License
 
-Distributed under the MIT License. See [LICENSE](./LICENSE) for more information.
+MIT - Feel free to use it.
 
 ## 📧 Contact
 

package/dist/{chunk-q8z45f9z.js → chunk-t1hx3d3e.js}

@@ -1,19 +1,33 @@
 // @bun
+import {
+  TOTP_ERROR_KEYS
+} from "./chunk-zfdfmrcn.js";
+
 // source/utils/create-counter-buffer.ts
 var createCounterBuffer = (counter) => {
   const counterBuffer = new ArrayBuffer(8);
   const counterView = new DataView(counterBuffer);
-  if (typeof counter === "bigint")
-    counterView.setBigUint64(0, counter, false);
-  else
-    counterView.setUint32(4, counter, false);
+  const counterBigInt = typeof counter === "bigint" ? counter : BigInt(Math.floor(counter));
+  counterView.setBigUint64(0, counterBigInt, false);
   return counterBuffer;
 };
 
 // source/utils/dynamic-truncation.ts
+import { InternalError } from "@nowarajs/error";
+var _DIGIT_MODULO = {
+  6: 1e6,
+  8: 1e8
+};
 var dynamicTruncation = (hmacArray, digits) => {
+  if (hmacArray.length < 20)
+    throw new InternalError(TOTP_ERROR_KEYS.INVALID_HMAC_LENGTH, "HMAC must be at least 20 bytes");
+  const modulo = _DIGIT_MODULO[digits];
+  if (modulo === undefined)
+    throw new InternalError(TOTP_ERROR_KEYS.INVALID_DIGITS, "Digits must be 6 or 8");
   const offset = hmacArray[hmacArray.length - 1] & 15;
-  const code = ((hmacArray[offset] & 127) << 24 | (hmacArray[offset + 1] & 255) << 16 | (hmacArray[offset + 2] & 255) << 8 | hmacArray[offset + 3] & 255) % 10 ** digits;
+  if (offset + 4 > hmacArray.length)
+    throw new InternalError(TOTP_ERROR_KEYS.INVALID_HMAC_LENGTH, "HMAC too short for computed offset");
+  const code = ((hmacArray[offset] & 127) << 24 | (hmacArray[offset + 1] & 255) << 16 | (hmacArray[offset + 2] & 255) << 8 | hmacArray[offset + 3] & 255) % modulo;
   return code.toString().padStart(digits, "0");
 };
 

package/dist/chunk-zfdfmrcn.js

@@ -0,0 +1,17 @@
+// @bun
+// source/enums/totp-error-keys.ts
+var TOTP_ERROR_KEYS = {
+  INVALID_ALGORITHM: "nowarajs.totp.error.invalid_algorithm",
+  INVALID_BASE32_CHARACTER: "nowarajs.totp.error.invalid_base32_character",
+  INVALID_DIGITS: "nowarajs.totp.error.invalid_digits",
+  INVALID_HMAC_LENGTH: "nowarajs.totp.error.invalid_hmac_length",
+  INVALID_OTP_AUTH_URI: "nowarajs.totp.error.invalid_otp_auth_uri",
+  INVALID_PERIOD: "nowarajs.totp.error.invalid_period",
+  INVALID_SECRET_LENGTH: "nowarajs.totp.error.invalid_secret_length",
+  INVALID_WINDOW: "nowarajs.totp.error.invalid_window",
+  MISSING_LABEL: "nowarajs.totp.error.missing_label",
+  MISSING_SECRET: "nowarajs.totp.error.missing_secret",
+  WEAK_SECRET: "nowarajs.totp.error.weak_secret"
+};
+
+export { TOTP_ERROR_KEYS };

package/dist/enums/index.js

@@ -1,7 +1,7 @@
 // @bun
 import {
   TOTP_ERROR_KEYS
-} from "../chunk-sx6rwmqe.js";
+} from "../chunk-zfdfmrcn.js";
 export {
   TOTP_ERROR_KEYS
 };

package/dist/enums/totp-error-keys.d.ts

@@ -1,7 +1,13 @@
 export declare const TOTP_ERROR_KEYS: {
     readonly INVALID_ALGORITHM: "nowarajs.totp.error.invalid_algorithm";
     readonly INVALID_BASE32_CHARACTER: "nowarajs.totp.error.invalid_base32_character";
+    readonly INVALID_DIGITS: "nowarajs.totp.error.invalid_digits";
+    readonly INVALID_HMAC_LENGTH: "nowarajs.totp.error.invalid_hmac_length";
     readonly INVALID_OTP_AUTH_URI: "nowarajs.totp.error.invalid_otp_auth_uri";
+    readonly INVALID_PERIOD: "nowarajs.totp.error.invalid_period";
     readonly INVALID_SECRET_LENGTH: "nowarajs.totp.error.invalid_secret_length";
+    readonly INVALID_WINDOW: "nowarajs.totp.error.invalid_window";
+    readonly MISSING_LABEL: "nowarajs.totp.error.missing_label";
     readonly MISSING_SECRET: "nowarajs.totp.error.missing_secret";
+    readonly WEAK_SECRET: "nowarajs.totp.error.weak_secret";
 };

package/dist/hotp.d.ts

@@ -1,11 +1,24 @@
 import type { TotpOptions } from './types/totp-options';
 /**
- * HMAC-based One-Time Password (HOTP) implementation
+ * Clear the CryptoKey cache
  *
- * @param secret - Secret key as bytes
+ * @remarks
+ * Useful for testing or when secrets should be purged from memory.
+ */
+export declare const clearKeyCache: () => void;
+/**
+ * HMAC-based One-Time Password (HOTP) implementation per RFC 4226
+ *
+ * @remarks
+ * Security: Validates minimum secret length (128 bits per RFC 4226).
+ * Performance: Caches CryptoKey objects for repeated calls.
+ *
+ * @param secret - Secret key as bytes (minimum 16 bytes)
  * @param counter - Counter value
  * @param opts - HOTP options
  *
+ * @throws ({@link InternalError}) - if secret is too short
+ *
  * @returns Promise resolving to the HOTP code
  */
 export declare const hotp: (secret: Uint8Array, counter: number | bigint, { algorithm, digits }?: TotpOptions) => Promise<string>;

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export { hotp } from './hotp';
+export { clearKeyCache, hotp } from './hotp';
 export { buildOtpAuthUri, parseOtpAuthUri } from './otp-auth-uri';
 export { totp, verifyTotp } from './totp';

package/dist/index.js

@@ -3,24 +3,51 @@ import {
   createCounterBuffer,
   dynamicTruncation,
   generateHmac
-} from "./chunk-q8z45f9z.js";
+} from "./chunk-t1hx3d3e.js";
 import {
   TOTP_ERROR_KEYS
-} from "./chunk-sx6rwmqe.js";
+} from "./chunk-zfdfmrcn.js";
 
 // source/hotp.ts
 import { webcrypto } from "crypto";
+import { InternalError } from "@nowarajs/error";
+var _keyCache = new Map;
+var _createCacheKey = (secret, algorithm) => {
+  const prefix = secret.slice(0, 8);
+  const suffix = secret.slice(-8);
+  const fingerprint = [...prefix, ...suffix, secret.length].join(",");
+  return `${fingerprint}:${algorithm}`;
+};
+var _getCryptoKey = async (secret, algorithm) => {
+  const cacheKey = _createCacheKey(secret, algorithm);
+  const cached = _keyCache.get(cacheKey);
+  if (cached)
+    return cached;
+  if (_keyCache.size >= 100) {
+    const firstKey = _keyCache.keys().next().value;
+    if (firstKey)
+      _keyCache.delete(firstKey);
+  }
+  const key = await webcrypto.subtle.importKey("raw", secret, { name: "HMAC", hash: algorithm }, false, ["sign"]);
+  _keyCache.set(cacheKey, key);
+  return key;
+};
+var clearKeyCache = () => {
+  _keyCache.clear();
+};
 var hotp = async (secret, counter, {
   algorithm = "SHA-1",
   digits = 6
 } = {}) => {
+  if (secret.length < 16)
+    throw new InternalError(TOTP_ERROR_KEYS.WEAK_SECRET, "Secret must be at least 16 bytes (128 bits)");
   const counterBuffer = createCounterBuffer(counter);
-  const key = await webcrypto.subtle.importKey("raw", secret, { name: "HMAC", hash: algorithm }, false, ["sign"]);
+  const key = await _getCryptoKey(secret, algorithm);
   const hmacArray = await generateHmac(key, counterBuffer);
   return dynamicTruncation(hmacArray, digits);
 };
 // source/otp-auth-uri.ts
-import { InternalError } from "@nowarajs/error";
+import { InternalError as InternalError2 } from "@nowarajs/error";
 var buildOtpAuthUri = ({
   secretBase32,
   label,
@@ -45,18 +72,28 @@ var buildOtpAuthUri = ({
 var parseOtpAuthUri = (uri) => {
   const url = new URL(uri);
   if (url.protocol !== "otpauth:")
-    throw new InternalError(TOTP_ERROR_KEYS.INVALID_OTP_AUTH_URI);
+    throw new InternalError2(TOTP_ERROR_KEYS.INVALID_OTP_AUTH_URI, "Invalid protocol, expected otpauth:");
   if (url.hostname !== "totp")
-    throw new InternalError(TOTP_ERROR_KEYS.INVALID_OTP_AUTH_URI);
+    throw new InternalError2(TOTP_ERROR_KEYS.INVALID_OTP_AUTH_URI, "Invalid type, expected totp");
   const label = decodeURIComponent(url.pathname.slice(1));
+  if (!label)
+    throw new InternalError2(TOTP_ERROR_KEYS.MISSING_LABEL, "Label is required");
   const secretBase32 = url.searchParams.get("secret");
   if (!secretBase32)
-    throw new InternalError(TOTP_ERROR_KEYS.MISSING_SECRET);
+    throw new InternalError2(TOTP_ERROR_KEYS.MISSING_SECRET, "Secret is required");
   const issuerParam = url.searchParams.get("issuer");
   const issuer = issuerParam ? decodeURIComponent(issuerParam) : undefined;
-  const algorithm = url.searchParams.get("algorithm") || "SHA-1";
-  const digits = parseInt(url.searchParams.get("digits") || "6", 10);
+  const algorithmParam = url.searchParams.get("algorithm") || "SHA-1";
+  if (algorithmParam !== "SHA-1" && algorithmParam !== "SHA-256" && algorithmParam !== "SHA-512")
+    throw new InternalError2(TOTP_ERROR_KEYS.INVALID_ALGORITHM, "Algorithm must be SHA-1, SHA-256, or SHA-512");
+  const algorithm = algorithmParam;
+  const digitsParam = parseInt(url.searchParams.get("digits") || "6", 10);
+  if (digitsParam !== 6 && digitsParam !== 8)
+    throw new InternalError2(TOTP_ERROR_KEYS.INVALID_DIGITS, "Digits must be 6 or 8");
+  const digits = digitsParam;
   const period = parseInt(url.searchParams.get("period") || "30", 10);
+  if (!Number.isFinite(period) || period <= 0)
+    throw new InternalError2(TOTP_ERROR_KEYS.INVALID_PERIOD, "Period must be a positive integer");
   const result = {
     secretBase32,
     label,
@@ -68,6 +105,8 @@ var parseOtpAuthUri = (uri) => {
   return result;
 };
 // source/totp.ts
+import { timingSafeEqual } from "crypto";
+import { InternalError as InternalError3 } from "@nowarajs/error";
 var totp = async (secret, {
   algorithm = "SHA-1",
   digits = 6,
@@ -77,6 +116,13 @@ var totp = async (secret, {
   const timeStep = Math.floor(now / 1000 / period);
   return hotp(secret, timeStep, { algorithm, digits });
 };
+var _timingSafeCompare = (a, b) => {
+  if (a.length !== b.length)
+    return false;
+  const bufferA = Buffer.from(a);
+  const bufferB = Buffer.from(b);
+  return timingSafeEqual(bufferA, bufferB);
+};
 var verifyTotp = async (secret, code, {
   algorithm = "SHA-1",
   digits = 6,
@@ -84,19 +130,30 @@ var verifyTotp = async (secret, code, {
   window = 0,
   now = Date.now()
 } = {}) => {
+  if (window < 0 || window > 10)
+    throw new InternalError3(TOTP_ERROR_KEYS.INVALID_WINDOW, "Window must be between 0 and 10");
+  if (!/^\d+$/.test(code) || code.length !== digits)
+    return false;
   const currentTimeStep = Math.floor(now / 1000 / period);
-  for (let i = -window;i <= window; ++i) {
-    const timeStep = currentTimeStep + i;
-    const expectedCode = await hotp(secret, timeStep, { algorithm, digits });
-    if (expectedCode === code)
-      return true;
+  if (window === 0) {
+    const expectedCode = await hotp(secret, currentTimeStep, { algorithm, digits });
+    return _timingSafeCompare(expectedCode, code);
   }
-  return false;
+  const timeSteps = [];
+  for (let i = -window;i <= window; ++i)
+    timeSteps.push(currentTimeStep + i);
+  const expectedCodes = await Promise.all(timeSteps.map((timeStep) => hotp(secret, timeStep, { algorithm, digits })));
+  let isValid = false;
+  for (const expectedCode of expectedCodes)
+    if (_timingSafeCompare(expectedCode, code))
+      isValid = true;
+  return isValid;
 };
 export {
   verifyTotp,
   totp,
   parseOtpAuthUri,
   hotp,
+  clearKeyCache,
   buildOtpAuthUri
 };

package/dist/otp-auth-uri.d.ts

@@ -10,6 +10,13 @@ export declare const buildOtpAuthUri: ({ secretBase32, label, issuer, algorithm,
 /**
  * Parse an OTPAuth URI
  *
+ * @remarks
+ * Security: Validates all parameters to prevent injection or invalid configurations.
+ * - Algorithm must be SHA-1, SHA-256, or SHA-512
+ * - Digits must be 6 or 8
+ * - Period must be a positive integer
+ * - Label is required per otpauth specification
+ *
  * @param uri - OTPAuth URI to parse
  *
  * @throws ({@link InternalError}) - if the URI is invalid or missing required parameters

package/dist/totp.d.ts

@@ -1,9 +1,9 @@
 import type { TotpOptions } from './types/totp-options';
 import type { VerifyOptions } from './types/verify-options';
 /**
- * Time-based One-Time Password (TOTP) implementation
+ * Time-based One-Time Password (TOTP) implementation per RFC 6238
  *
- * @param secret - Secret key as bytes
+ * @param secret - Secret key as bytes (minimum 16 bytes)
  * @param opts - TOTP options including current time
  *
  * @returns Promise resolving to the TOTP code
@@ -14,10 +14,18 @@ export declare const totp: (secret: Uint8Array, { algorithm, digits, period, now
 /**
  * Verify a TOTP code against a secret
  *
- * @param secret - Secret key as bytes
+ * @remarks
+ * Security: Uses constant-time comparison to prevent timing attacks (CWE-208).
+ * Security: Always iterates through all windows to prevent leaking which time step matched.
+ * Security: Validates window size to prevent DoS attacks (CWE-400).
+ * Performance: Parallelizes code generation when window > 0.
+ *
+ * @param secret - Secret key as bytes (minimum 16 bytes)
  * @param code - Code to verify
  * @param opts - Verification options
  *
+ * @throws ({@link InternalError}) - if window is invalid
+ *
  * @returns Promise resolving to true if code is valid
  */
 export declare const verifyTotp: (secret: Uint8Array, code: string, { algorithm, digits, period, window, now }?: VerifyOptions) => Promise<boolean>;

package/dist/types/index.d.ts

@@ -1,3 +1,11 @@
 export type { OtpAuthUri } from './otp-auth-uri';
 export type { TotpOptions } from './totp-options';
 export type { VerifyOptions } from './verify-options';
+/**
+ * Supported hash algorithms for TOTP/HOTP
+ */
+export type HashAlgorithm = 'SHA-1' | 'SHA-256' | 'SHA-512';
+/**
+ * Valid digit counts for OTP codes
+ */
+export type OtpDigits = 6 | 8;

package/dist/types/otp-auth-uri.d.ts

@@ -13,7 +13,7 @@ export interface OtpAuthUri {
     /**
      * Issuer name (app/service name)
      */
-    issuer: string;
+    issuer?: string;
     /**
      * Hash algorithm
      *

package/dist/types/verify-options.d.ts

@@ -6,7 +6,7 @@ export interface VerifyOptions extends TotpOptions {
     /**
      * Time window for verification (±window periods)
      *
-     * @defaultValue 1
+     * @defaultValue 0
      */
     window?: number;
     /**

package/dist/utils/base32.d.ts

@@ -1,6 +1,10 @@
 /**
  * Encode bytes to Base32 string
  *
+ * @remarks
+ * Performance: Uses array.join() instead of string concatenation
+ * to avoid creating intermediate strings in the hot path.
+ *
  * @param input - Bytes or string to encode
  * @param withPadding - Whether to include padding (default: true)
  *
@@ -10,7 +14,12 @@ export declare const base32Encode: (input: string | Uint8Array, withPadding?: bo
 /**
  * Decode Base32 string to bytes
  *
- * @param base32 - Base32 string to decode
+ * @remarks
+ * Security: Case-insensitive decoding per RFC 4648 recommendation.
+ * Performance: Uses Map lookup for O(1) character value retrieval.
+ * Performance: Pre-allocates output array based on input length.
+ *
+ * @param base32 - Base32 string to decode (case-insensitive)
  *
  * @throws ({@link InternalError}) - if invalid Base32 character is found
  *

package/dist/utils/create-counter-buffer.d.ts

@@ -1,8 +1,16 @@
 /**
  * Convert a counter value to an 8-byte big-endian buffer
  *
+ * @remarks
+ * Always uses BigInt internally to support full 64-bit counter values.
+ * This fixes potential integer overflow issues when counter exceeds 2^32-1.
+ *
+ * For TOTP, time steps are calculated as Math.floor(Date.now() / 1000 / period).
+ * Current time steps are ~57 million, well within 32-bit range, but this
+ * ensures correctness for far-future dates and high-precision use cases.
+ *
  * @param counter - Counter value as number or bigint
  *
- * @returns ArrayBuffer containing the counter in big-endian format
+ * @returns ArrayBuffer containing the counter in big-endian format (8 bytes)
  */
 export declare const createCounterBuffer: (counter: number | bigint) => ArrayBuffer;

package/dist/utils/dynamic-truncation.d.ts

@@ -1,9 +1,12 @@
+import type { OtpDigits } from '../types';
 /**
  * Perform dynamic truncation on HMAC result according to RFC 4226
  *
- * @param hmacArray - HMAC result as byte array
- * @param digits - Number of digits in the final code
+ * @param hmacArray - HMAC result as byte array (minimum 20 bytes)
+ * @param digits - Number of digits in the final code (6 or 8)
+ *
+ * @throws ({@link InternalError}) - if HMAC array is too short or digits is invalid
  *
  * @returns Truncated code as string with leading zeros
  */
-export declare const dynamicTruncation: (hmacArray: Uint8Array, digits: number) => string;
+export declare const dynamicTruncation: (hmacArray: Uint8Array, digits: OtpDigits) => string;

package/dist/utils/index.js

@@ -3,53 +3,63 @@ import {
   createCounterBuffer,
   dynamicTruncation,
   generateHmac
-} from "../chunk-q8z45f9z.js";
+} from "../chunk-t1hx3d3e.js";
 import {
   TOTP_ERROR_KEYS
-} from "../chunk-sx6rwmqe.js";
+} from "../chunk-zfdfmrcn.js";
 
 // source/utils/base32.ts
 import { InternalError } from "@nowarajs/error";
 var BASE32_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+var _BASE32_LOOKUP = new Map(Array.from(BASE32_ALPHABET, (char, index) => [char, index]));
 var base32Encode = (input, withPadding = true) => {
-  let result = "";
+  const bytes = input instanceof Uint8Array ? input : new TextEncoder().encode(input);
+  if (bytes.length === 0)
+    return "";
+  const estimatedLength = Math.ceil(bytes.length * 8 / 5);
+  const chars = new Array(estimatedLength);
   let bits = 0;
   let value = 0;
-  const bytes = input instanceof Uint8Array ? input : new TextEncoder().encode(input);
-  for (const byte of bytes) {
-    value = value << 8 | byte;
+  let charIndex = 0;
+  for (let i = 0;i < bytes.length; ++i) {
+    value = value << 8 | bytes[i];
     bits += 8;
     while (bits >= 5) {
-      result += BASE32_ALPHABET[value >>> bits - 5 & 31];
+      chars[charIndex++] = BASE32_ALPHABET[value >>> bits - 5 & 31];
       bits -= 5;
     }
   }
   if (bits > 0)
-    result += BASE32_ALPHABET[value << 5 - bits & 31];
+    chars[charIndex++] = BASE32_ALPHABET[value << 5 - bits & 31];
+  let result = chars.slice(0, charIndex).join("");
   if (withPadding)
     while (result.length % 8 !== 0)
       result += "=";
   return result;
 };
 var base32Decode = (base32) => {
-  const cleanBase32 = base32.replace(/=+$/, "");
-  if (cleanBase32.length === 0)
+  const cleanBase32 = base32.toUpperCase().replace(/=+$/, "");
+  const inputLength = cleanBase32.length;
+  if (inputLength === 0)
     return new Uint8Array(0);
-  const result = [];
+  const outputLength = Math.floor(inputLength * 5 / 8);
+  const result = new Uint8Array(outputLength);
   let bits = 0;
   let value = 0;
-  for (const char of cleanBase32) {
-    const charValue = BASE32_ALPHABET.indexOf(char);
-    if (charValue === -1)
-      throw new InternalError(TOTP_ERROR_KEYS.INVALID_BASE32_CHARACTER, `Invalid Base32 character: ${char}`);
+  let outputIndex = 0;
+  for (let i = 0;i < inputLength; ++i) {
+    const char = cleanBase32[i];
+    const charValue = _BASE32_LOOKUP.get(char);
+    if (charValue === undefined)
+      throw new InternalError(TOTP_ERROR_KEYS.INVALID_BASE32_CHARACTER, "Invalid Base32 character");
     value = value << 5 | charValue;
     bits += 5;
     if (bits >= 8) {
-      result.push(value >>> bits - 8 & 255);
+      result[outputIndex++] = value >>> bits - 8 & 255;
       bits -= 8;
     }
   }
-  return new Uint8Array(result);
+  return result;
 };
 // source/utils/generate-secret-bytes.ts
 import { InternalError as InternalError2 } from "@nowarajs/error";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nowarajs/totp",
-	"version": "1.2.0",
+	"version": "1.2.2",
 	"author": "NowaraJS",
 	"description": "A comprehensive Time-based One-Time Password (TOTP) and HMAC-based One-Time Password (HOTP)",
 	"type": "module",
@@ -22,17 +22,17 @@
 		"test": "bun test --coverage"
 	},
 	"devDependencies": {
-		"@eslint/js": "^9.39.1",
-		"@nowarajs/error": "^1.3.10",
-		"@stylistic/eslint-plugin": "^5.5.0",
-		"@types/bun": "^1.3.2",
-		"eslint": "^9.39.1",
-		"globals": "^16.5.0",
-		"typescript-eslint": "^8.46.4",
+		"@eslint/js": "^9.39.2",
+		"@nowarajs/error": "^1.4.0",
+		"@stylistic/eslint-plugin": "^5.7.0",
+		"@types/bun": "^1.3.5",
+		"eslint": "^9.39.2",
+		"globals": "^17.0.0",
+		"typescript-eslint": "^8.52.0",
 		"typescript": "^5.9.3"
 	},
 	"peerDependencies": {
-		"@nowarajs/error": "^1.3.10"
+		"@nowarajs/error": "^1.4.0"
 	},
 	"exports": {
 		"./enums": "./dist/enums/index.js",

package/dist/chunk-sx6rwmqe.js

@@ -1,11 +0,0 @@
-// @bun
-// source/enums/totp-error-keys.ts
-var TOTP_ERROR_KEYS = {
-  INVALID_ALGORITHM: "nowarajs.totp.error.invalid_algorithm",
-  INVALID_BASE32_CHARACTER: "nowarajs.totp.error.invalid_base32_character",
-  INVALID_OTP_AUTH_URI: "nowarajs.totp.error.invalid_otp_auth_uri",
-  INVALID_SECRET_LENGTH: "nowarajs.totp.error.invalid_secret_length",
-  MISSING_SECRET: "nowarajs.totp.error.missing_secret"
-};
-
-export { TOTP_ERROR_KEYS };