@nowarajs/totp 1.2.1 → 1.2.2

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.1",
+	"version": "1.2.2",
 	"author": "NowaraJS",
 	"description": "A comprehensive Time-based One-Time Password (TOTP) and HMAC-based One-Time Password (HOTP)",
 	"type": "module",

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 };