@nowarajs/totp 1.1.2

package/CHANGELOG.md

@@ -0,0 +1,75 @@
+
+## v1.1.2
+
+[compare changes](https://github.com/NowaraJS/totp/compare/v1.1.1...v1.1.2)
+
+### 🦉 Chore
+
+- **🦉:** [Update package.json with correct name and description] ([e007586](https://github.com/NowaraJS/totp/commit/e007586))
+
+### ❤️ Contributors
+
+- Komiroko <komiriko@pm.me>
+
+## v1.1.1
+
+[compare changes](https://github.com/NowaraJS/totp/compare/v1.1.0...v1.1.1)
+
+### 📖 Documentation
+
+- **📖:** [Update README with comprehensive TOTP features and usage] ([e8f8369](https://github.com/NowaraJS/totp/commit/e8f8369))
+
+### ❤️ Contributors
+
+- Komiroko <komiriko@pm.me>
+
+## v1.1.0
+
+
+### 🚀 Enhancements
+
+- **🚀:** [Add Base32 encoding and decoding utilities] ([580be95](https://github.com/NowaraJS/totp/commit/580be95))
+- **🚀:** [Add TOTP error keys enumeration] ([cd31d9d](https://github.com/NowaraJS/totp/commit/cd31d9d))
+- **🚀:** [Add createCounterBuffer utility for big-endian conversion] ([6effcbf](https://github.com/NowaraJS/totp/commit/6effcbf))
+- **🚀:** [Add dynamic truncation utility for HMAC results] ([8b9d226](https://github.com/NowaraJS/totp/commit/8b9d226))
+- **🚀:** [Add generateHmac utility for HMAC generation] ## Features - Introduced a new utility function `generateHmac` for generating HMACs. ([86a62ee](https://github.com/NowaraJS/totp/commit/86a62ee))
+- **🚀:** [Add generateSecretBytes utility for TOTP secret generation] ([f0fa3b4](https://github.com/NowaraJS/totp/commit/f0fa3b4))
+- **🚀:** [Add timeRemaining utility for TOTP code calculation] ([38c2591](https://github.com/NowaraJS/totp/commit/38c2591))
+- **🚀:** [Implement HMAC-based One-Time Password (HOTP) functionality] ([57cc8db](https://github.com/NowaraJS/totp/commit/57cc8db))
+- **🚀:** [Add OTPAuth URI building and parsing functionality] ([3c3108c](https://github.com/NowaraJS/totp/commit/3c3108c))
+- **🚀:** [Add TOTP implementation and verification functionality] ([e9ca7da](https://github.com/NowaraJS/totp/commit/e9ca7da))
+
+### 📖 Documentation
+
+- **📖:** [Update copilot instructions for clarity and structure] ([57ca1ea](https://github.com/NowaraJS/totp/commit/57ca1ea))
+
+### 📦 Build
+
+- **📦:** [Update devDependencies and exports in package.json] ([2e32770](https://github.com/NowaraJS/totp/commit/2e32770))
+- **📦:** [Refactor entrypoints in builder.ts for clarity] ([7e241b4](https://github.com/NowaraJS/totp/commit/7e241b4))
+- **📦:** [Clean and add entrypoints] ([6a82236](https://github.com/NowaraJS/totp/commit/6a82236))
+
+### 🦉 Chore
+
+- **🦉:** [Remove unused utility files and related tests] ## Chores - Deleted `exampleKeyError.ts`, `foo.ts`, and their corresponding test files. ## Description This commit removes unused utility files and their associated tests to clean up the codebase and reduce clutter. These files are no longer needed and their removal helps maintain a more manageable project structure. ([62c6231](https://github.com/NowaraJS/totp/commit/62c6231))
+
+### 🧪 Tests
+
+- **🧪:** [Add unit tests for Base32 encoding and decoding] ([7292a8d](https://github.com/NowaraJS/totp/commit/7292a8d))
+- **🧪:** [Add unit tests for createCounterBuffer utility] ([b13eea0](https://github.com/NowaraJS/totp/commit/b13eea0))
+- **🧪:** [Add unit tests for dynamic truncation utility] ([9dfb41c](https://github.com/NowaraJS/totp/commit/9dfb41c))
+- **🧪:** [Add unit tests for generateHmac utility] ([67aa60b](https://github.com/NowaraJS/totp/commit/67aa60b))
+- **🧪:** [Add unit tests for generateSecretBytes utility] ([52f2ec6](https://github.com/NowaraJS/totp/commit/52f2ec6))
+- **🧪:** [Add unit tests for timeRemaining utility] ## Tests - Introduced unit tests for the timeRemaining utility function. ## Description This commit adds a test suite for the timeRemaining function, ensuring that it correctly calculates the remaining time until the next TOTP code based on a specified period. The test checks that the remaining time is less than the period, validating the function's expected behavior. ([ae820e8](https://github.com/NowaraJS/totp/commit/ae820e8))
+- **🧪:** [Add unit tests for HOTP code generation] ([932fb33](https://github.com/NowaraJS/totp/commit/932fb33))
+- **🧪:** [Add unit tests for OTP Auth URI building and parsing] ## Tests - Implemented unit tests for `buildOtpAuthUri` to ensure it constructs a valid OTP Auth URI. - Added tests for `parseOtpAuthUri` to validate parsing of a valid OTP Auth URI and error handling for invalid cases. ([6160cbd](https://github.com/NowaraJS/totp/commit/6160cbd))
+- **🧪:** [Add unit tests for TOTP generation and verification] ## Tests - Added tests for TOTP code generation to ensure it produces a valid 6-digit code. - Implemented tests for TOTP code verification, including both valid and invalid scenarios. ## Description This commit introduces unit tests for the TOTP functionality, validating both the generation of TOTP codes and their verification. The tests check that generated codes are of the correct length and format, and that the verification function correctly identifies valid and invalid codes. ([445a954](https://github.com/NowaraJS/totp/commit/445a954))
+
+### 🤖 CI
+
+- **🤖:** [Enhance CI workflows with additional MSSQL secrets] ([b96813c](https://github.com/NowaraJS/totp/commit/b96813c))
+
+### ❤️ Contributors
+
+- Komiroko <komiriko@pm.me>
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 [Project Name]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,216 @@
+# 🔐 NowaraJS - TOTP
+
+## 📌 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
+
+- 🔐 **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
+- 🧪 **Type Safe**: Full TypeScript support with comprehensive type definitions
+
+## 🔧 Installation
+
+```bash
+bun add @nowarajs/totp @nowarajs/error
+```
+
+## ⚙️ Usage
+
+### Basic TOTP Generation
+
+```ts
+import { totp, generateSecretBytes, base32Encode } from '@nowarajs/totp';
+
+// Generate a secret
+const secret = generateSecretBytes(20); // 20 bytes = 160 bits
+const secretBase32 = base32Encode(secret);
+
+// Generate TOTP code
+const code = await totp(secret, {
+	algorithm: 'SHA-1',
+	digits: 6,
+	period: 30
+});
+
+console.log('TOTP Code:', code); // e.g., "123456"
+```
+
+### TOTP Verification
+
+```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
+});
+
+if (isValid) {
+	console.log('✅ Code is valid!');
+} else {
+	console.log('❌ Invalid code');
+}
+```
+
+### HOTP Support
+
+```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
+
+```ts
+import { buildOtpAuthUri, 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
+});
+
+console.log('QR Code URI:', uri);
+// otpauth://totp/user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=MyApp
+```
+
+### Secret Generation
+
+```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
+
+```ts
+// Use SHA-256 with 8 digits and 60-second period
+const advancedCode = await totp(secret, {
+	algorithm: 'SHA-256',
+	digits: 8,
+	period: 60
+});
+
+// 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)
+});
+```
+
+### 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/)
+
+## ⚖️ License
+
+Distributed under the MIT License. See [LICENSE](./LICENSE) for more information.
+
+## 📧 Contact
+
+- GitHub: [NowaraJS](https://github.com/NowaraJS)
+- Package: [@nowarajs/totp](https://www.npmjs.com/package/@nowarajs/totp)
+

package/dist/chunk-4qsch0ea.js

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

package/dist/chunk-hhdy89hc.js

@@ -0,0 +1,26 @@
+// source/utils/createCounterBuffer.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);
+  return counterBuffer;
+};
+
+// source/utils/dynamicTruncation.ts
+var dynamicTruncation = (hmacArray, digits) => {
+  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;
+  return code.toString().padStart(digits, "0");
+};
+
+// source/utils/generateHmac.ts
+import { webcrypto } from "crypto";
+var generateHmac = async (key, data) => {
+  const hmac = await webcrypto.subtle.sign("HMAC", key, data);
+  return new Uint8Array(hmac);
+};
+
+export { createCounterBuffer, dynamicTruncation, generateHmac };

package/dist/enums/index.d.ts

@@ -0,0 +1 @@
+export { TOTP_ERROR_KEYS } from './totpErrorKeys';

package/dist/enums/index.js

@@ -0,0 +1,7 @@
+// @bun
+import {
+  TOTP_ERROR_KEYS
+} from "../chunk-4qsch0ea.js";
+export {
+  TOTP_ERROR_KEYS
+};

package/dist/enums/totpErrorKeys.d.ts

@@ -0,0 +1,7 @@
+export declare const TOTP_ERROR_KEYS: {
+    readonly INVALID_BASE32_CHARACTER: "totp.error.invalid_base32_character";
+    readonly INVALID_SECRET_LENGTH: "totp.error.invalid_secret_length";
+    readonly INVALID_ALGORITHM: "totp.error.invalid_algorithm";
+    readonly INVALID_OTP_AUTH_URI: "totp.error.invalid_otp_auth_uri";
+    readonly MISSING_SECRET: "totp.error.missing_secret";
+};

package/dist/hotp.d.ts

@@ -0,0 +1,11 @@
+import type { TotpOptions } from './types/totpOptions';
+/**
+ * HMAC-based One-Time Password (HOTP) implementation
+ *
+ * @param secret - Secret key as bytes
+ * @param counter - Counter value
+ * @param opts - HOTP options
+ *
+ * @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

@@ -0,0 +1,3 @@
+export { hotp } from './hotp';
+export { buildOtpAuthUri, parseOtpAuthUri } from './otpAuthUri';
+export { totp, verifyTotp } from './totp';

package/dist/index.js

@@ -0,0 +1,108 @@
+// @bun
+import {
+  createCounterBuffer,
+  dynamicTruncation,
+  generateHmac
+} from "./chunk-hhdy89hc.js";
+import {
+  TOTP_ERROR_KEYS
+} from "./chunk-4qsch0ea.js";
+
+// source/hotp.ts
+import { webcrypto } from "crypto";
+var hotp = async (secret, counter, {
+  algorithm = "SHA-1",
+  digits = 6
+} = {}) => {
+  const counterBuffer = createCounterBuffer(counter);
+  const key = await webcrypto.subtle.importKey("raw", secret, { name: "HMAC", hash: algorithm }, false, ["sign"]);
+  const hmacArray = await generateHmac(key, counterBuffer);
+  return dynamicTruncation(hmacArray, digits);
+};
+// source/otpAuthUri.ts
+import { BaseError } from "@nowarajs/error";
+var buildOtpAuthUri = ({
+  secretBase32,
+  label,
+  issuer,
+  algorithm = "SHA-1",
+  digits = 6,
+  period = 30
+}) => {
+  const encodedLabel = encodeURIComponent(label);
+  const encodedIssuer = issuer ? encodeURIComponent(issuer) : undefined;
+  let uri = `otpauth://totp/${encodedLabel}?secret=${secretBase32}`;
+  if (encodedIssuer)
+    uri += `&issuer=${encodedIssuer}`;
+  if (algorithm !== "SHA-1")
+    uri += `&algorithm=${algorithm}`;
+  if (digits !== 6)
+    uri += `&digits=${digits}`;
+  if (period !== 30)
+    uri += `&period=${period}`;
+  return uri;
+};
+var parseOtpAuthUri = (uri) => {
+  const url = new URL(uri);
+  if (url.protocol !== "otpauth:")
+    throw new BaseError({
+      message: TOTP_ERROR_KEYS.INVALID_OTP_AUTH_URI
+    });
+  if (url.hostname !== "totp")
+    throw new BaseError({
+      message: TOTP_ERROR_KEYS.INVALID_OTP_AUTH_URI
+    });
+  const label = decodeURIComponent(url.pathname.slice(1));
+  const secretBase32 = url.searchParams.get("secret");
+  if (!secretBase32)
+    throw new BaseError({
+      message: TOTP_ERROR_KEYS.MISSING_SECRET
+    });
+  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 period = parseInt(url.searchParams.get("period") || "30", 10);
+  const result = {
+    secretBase32,
+    label,
+    algorithm,
+    digits,
+    period,
+    ...issuer && { issuer }
+  };
+  return result;
+};
+// source/totp.ts
+var totp = async (secret, {
+  algorithm = "SHA-1",
+  digits = 6,
+  period = 30,
+  now = Date.now()
+} = {}) => {
+  const timeStep = Math.floor(now / 1000 / period);
+  return hotp(secret, timeStep, { algorithm, digits });
+};
+var verifyTotp = async (secret, code, {
+  algorithm = "SHA-1",
+  digits = 6,
+  period = 30,
+  window = 0,
+  now = Date.now()
+} = {}) => {
+  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;
+  }
+  return false;
+};
+export {
+  verifyTotp,
+  totp,
+  parseOtpAuthUri,
+  hotp,
+  buildOtpAuthUri
+};

package/dist/otpAuthUri.d.ts

@@ -0,0 +1,21 @@
+import type { OtpAuthUri } from './types/otpAuthUri';
+/**
+ * Build an OTPAuth URI for QR code generation
+ *
+ * @param params - URI parameters
+ *
+ * @returns OTPAuth URI string
+ */
+export declare const buildOtpAuthUri: ({ secretBase32, label, issuer, algorithm, digits, period }: OtpAuthUri) => string;
+/**
+ * Parse an OTPAuth URI
+ *
+ * @param uri - OTPAuth URI to parse
+ *
+ * @throws ({@link BaseError}) - if the URI is invalid or missing required parameters
+ *
+ * @returns Parsed URI parameters
+ */
+export declare const parseOtpAuthUri: (uri: string) => Required<Omit<OtpAuthUri, "issuer">> & {
+    issuer?: string;
+};

package/dist/totp.d.ts

@@ -0,0 +1,23 @@
+import type { TotpOptions } from './types/totpOptions';
+import type { VerifyOptions } from './types/verifyOptions';
+/**
+ * Time-based One-Time Password (TOTP) implementation
+ *
+ * @param secret - Secret key as bytes
+ * @param opts - TOTP options including current time
+ *
+ * @returns Promise resolving to the TOTP code
+ */
+export declare const totp: (secret: Uint8Array, { algorithm, digits, period, now }?: TotpOptions & {
+    now?: number;
+}) => Promise<string>;
+/**
+ * Verify a TOTP code against a secret
+ *
+ * @param secret - Secret key as bytes
+ * @param code - Code to verify
+ * @param opts - Verification options
+ *
+ * @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

@@ -0,0 +1,3 @@
+export type { OtpAuthUri } from './otpAuthUri';
+export type { TotpOptions } from './totpOptions';
+export type { VerifyOptions } from './verifyOptions';

package/dist/types/index.js

@@ -0,0 +1 @@
+// @bun

package/dist/types/otpAuthUri.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Complete OTPAuth URI data structure
+ */
+export interface OtpAuthUri {
+    /**
+     * Base32 encoded secret
+     */
+    secretBase32: string;
+    /**
+     * Label for the account (usually email or username)
+     */
+    label: string;
+    /**
+     * Issuer name (app/service name)
+     */
+    issuer: string;
+    /**
+     * Hash algorithm
+     *
+     * @defaultValue 'SHA-1'
+     */
+    algorithm?: 'SHA-1' | 'SHA-256' | 'SHA-512';
+    /**
+     * Number of digits
+     *
+     * @defaultValue 6
+     */
+    digits?: 6 | 8;
+    /**
+     * Time period in seconds
+     *
+     * @defaultValue 30
+     */
+    period?: number;
+}

package/dist/types/totpOptions.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Options for TOTP/HOTP generation
+ */
+export interface TotpOptions {
+    /**
+     * Hash algorithm to use
+     *
+     * @defaultValue SHA-1
+     */
+    algorithm?: 'SHA-1' | 'SHA-256' | 'SHA-512';
+    /**
+     * Number of digits in the code
+     *
+     * @defaultValue 6
+     */
+    digits?: 6 | 8;
+    /**
+     * Time step in seconds for TOTP
+     *
+     * @defaultValue 30
+     */
+    period?: number;
+}

package/dist/types/verifyOptions.d.ts

@@ -0,0 +1,18 @@
+import type { TotpOptions } from './totpOptions';
+/**
+ * Options for TOTP verification
+ */
+export interface VerifyOptions extends TotpOptions {
+    /**
+     * Time window for verification (±window periods)
+     *
+     * @defaultValue 1
+     */
+    window?: number;
+    /**
+     * Current timestamp in milliseconds
+     *
+     * @defaultValue Date.now()
+     */
+    now?: number;
+}

package/dist/utils/base32.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Encode bytes to Base32 string
+ *
+ * @param input - Bytes or string to encode
+ * @param withPadding - Whether to include padding (default: true)
+ *
+ * @returns Base32 encoded string
+ */
+export declare const base32Encode: (input: string | Uint8Array, withPadding?: boolean) => string;
+/**
+ * Decode Base32 string to bytes
+ *
+ * @param base32 - Base32 string to decode
+ *
+ * @throws ({@link BaseError}) - if invalid Base32 character is found
+ *
+ * @returns Decoded bytes
+ */
+export declare const base32Decode: (base32: string) => Uint8Array;

package/dist/utils/createCounterBuffer.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Convert a counter value to an 8-byte big-endian buffer
+ *
+ * @param counter - Counter value as number or bigint
+ *
+ * @returns ArrayBuffer containing the counter in big-endian format
+ */
+export declare const createCounterBuffer: (counter: number | bigint) => ArrayBuffer;

package/dist/utils/dynamicTruncation.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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
+ *
+ * @returns Truncated code as string with leading zeros
+ */
+export declare const dynamicTruncation: (hmacArray: Uint8Array, digits: number) => string;

package/dist/utils/generateHmac.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Generate HMAC for given data using a crypto key
+ *
+ * @param key - Crypto key for HMAC
+ * @param data - Data to sign
+ *
+ * @returns Promise resolving to HMAC as Uint8Array
+ */
+export declare const generateHmac: (key: CryptoKey, data: ArrayBuffer) => Promise<Uint8Array>;

package/dist/utils/generateSecretBytes.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Generate cryptographically secure random bytes for TOTP secret
+ *
+ * @param length - Number of bytes to generate (default: 20)
+ *
+ * @throws ({@link BaseError}) if length is not positive
+ *
+ * @returns Uint8Array containing the random bytes
+ */
+export declare const generateSecretBytes: (length?: number) => Uint8Array;

package/dist/utils/index.d.ts

@@ -0,0 +1,6 @@
+export { base32Decode, base32Encode } from './base32';
+export { createCounterBuffer } from './createCounterBuffer';
+export { dynamicTruncation } from './dynamicTruncation';
+export { generateHmac } from './generateHmac';
+export { generateSecretBytes } from './generateSecretBytes';
+export { timeRemaining } from './timeRemaining';

package/dist/utils/index.js

@@ -0,0 +1,80 @@
+// @bun
+import {
+  createCounterBuffer,
+  dynamicTruncation,
+  generateHmac
+} from "../chunk-hhdy89hc.js";
+import {
+  TOTP_ERROR_KEYS
+} from "../chunk-4qsch0ea.js";
+
+// source/utils/base32.ts
+import { BaseError } from "@nowarajs/error";
+var BASE32_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+var base32Encode = (input, withPadding = true) => {
+  let result = "";
+  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;
+    bits += 8;
+    while (bits >= 5) {
+      result += BASE32_ALPHABET[value >>> bits - 5 & 31];
+      bits -= 5;
+    }
+  }
+  if (bits > 0)
+    result += BASE32_ALPHABET[value << 5 - bits & 31];
+  if (withPadding)
+    while (result.length % 8 !== 0)
+      result += "=";
+  return result;
+};
+var base32Decode = (base32) => {
+  const cleanBase32 = base32.replace(/=+$/, "");
+  if (cleanBase32.length === 0)
+    return new Uint8Array(0);
+  const result = [];
+  let bits = 0;
+  let value = 0;
+  for (const char of cleanBase32) {
+    const charValue = BASE32_ALPHABET.indexOf(char);
+    if (charValue === -1)
+      throw new BaseError({
+        message: TOTP_ERROR_KEYS.INVALID_BASE32_CHARACTER,
+        cause: `Invalid Base32 character: ${char}`
+      });
+    value = value << 5 | charValue;
+    bits += 5;
+    if (bits >= 8) {
+      result.push(value >>> bits - 8 & 255);
+      bits -= 8;
+    }
+  }
+  return new Uint8Array(result);
+};
+// source/utils/generateSecretBytes.ts
+import { BaseError as BaseError2 } from "@nowarajs/error";
+import { getRandomValues } from "crypto";
+var generateSecretBytes = (length = 20) => {
+  if (length <= 0)
+    throw new BaseError2({
+      message: TOTP_ERROR_KEYS.INVALID_SECRET_LENGTH
+    });
+  return getRandomValues(new Uint8Array(length));
+};
+// source/utils/timeRemaining.ts
+var timeRemaining = (period = 30, now = Date.now()) => {
+  const elapsed = Math.floor(now / 1000) % period;
+  return period - elapsed;
+};
+export {
+  timeRemaining,
+  generateSecretBytes,
+  generateHmac,
+  dynamicTruncation,
+  createCounterBuffer,
+  base32Encode,
+  base32Decode
+};

package/dist/utils/timeRemaining.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Calculate remaining time until next TOTP code
+ *
+ * @param period - Time period in seconds (default: 30)
+ * @param now - Current timestamp in milliseconds (default: Date.now())
+ *
+ * @returns Seconds remaining until next code
+ */
+export declare const timeRemaining: (period?: number, now?: number) => number;

package/package.json

@@ -0,0 +1,94 @@
+{
+	"name": "@nowarajs/totp",
+	"version": "1.1.2",
+	"author": "Komiriko",
+	"description": "A comprehensive Time-based One-Time Password (TOTP) and HMAC-based One-Time Password (HOTP)",
+	"type": "module",
+	"license": "MIT",
+	"keywords": [
+		"bun",
+		"nowarajs",
+		"totp",
+		"hotp"
+	],
+	"scripts": {
+		"build": "bun builder.ts",
+		"dev": "bun --watch sandbox/index.ts",
+		"docs": "bunx typedoc --tsconfig tsconfig.build.json",
+		"fix-lint": "eslint --fix ./source",
+		"lint": "eslint ./source",
+		"test:integration": "bun test $(find test/integration -name '*.spec.ts')",
+		"test:unit": "bun test --coverage $(find test/unit -name '*.spec.ts')",
+		"test": "bun test --coverage"
+	},
+	"devDependencies": {
+		"@eslint/js": "^9.33.0",
+		"@stylistic/eslint-plugin": "^5.2.3",
+		"@types/bun": "^1.2.20",
+		"eslint": "^9.33.0",
+		"globals": "^16.3.0",
+		"typescript-eslint": "^8.39.1",
+		"typescript": "^5.9.2"
+	},
+	"exports": {
+		"./enums": "./dist/enums/index.js",
+		"./types": "./dist/types/index.js",
+		"./utils": "./dist/utils/index.js",
+		".": "./dist/index.js"
+	},
+	"changelog": {
+		"types": {
+			"feat": {
+				"title": "🚀 Enhancements",
+				"semver": "minor"
+			},
+			"perf": {
+				"title": "⚡ Performance",
+				"semver": "patch"
+			},
+			"fix": {
+				"title": "🔧 Fixes",
+				"semver": "patch"
+			},
+			"refactor": {
+				"title": "🧹 Refactors",
+				"semver": "patch"
+			},
+			"docs": {
+				"title": "📖 Documentation",
+				"semver": "patch"
+			},
+			"build": {
+				"title": "📦 Build",
+				"semver": "patch"
+			},
+			"types": {
+				"title": "🌊 Types",
+				"semver": "patch"
+			},
+			"chore": {
+				"title": "🦉 Chore"
+			},
+			"examples": {
+				"title": "🏀 Examples"
+			},
+			"test": {
+				"title": "🧪 Tests"
+			},
+			"style": {
+				"title": "🎨 Styles"
+			},
+			"ci": {
+				"title": "🤖 CI"
+			}
+		},
+		"templates": {
+			"commitMessage": "chore(🦉): v{{newVersion}}",
+			"tagMessage": "v{{newVersion}}",
+			"tagBody": "v{{newVersion}}"
+		}
+	},
+	"peerDependencies": {
+		"@nowarajs/error": "^1.1.6"
+	}
+}