@nowarajs/totp 1.1.12 → 1.2.1

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-sx6rwmqe.js

@@ -0,0 +1,11 @@
+// @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 };

package/dist/enums/index.js

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

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

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

package/dist/index.js

@@ -6,7 +6,7 @@ import {
 } from "./chunk-q8z45f9z.js";
 import {
   TOTP_ERROR_KEYS
-} from "./chunk-4z2jb9kh.js";
+} from "./chunk-sx6rwmqe.js";
 
 // source/hotp.ts
 import { webcrypto } from "crypto";
@@ -20,7 +20,7 @@ var hotp = async (secret, counter, {
   return dynamicTruncation(hmacArray, digits);
 };
 // source/otp-auth-uri.ts
-import { BaseError } from "@nowarajs/error";
+import { InternalError } from "@nowarajs/error";
 var buildOtpAuthUri = ({
   secretBase32,
   label,
@@ -45,13 +45,13 @@ var buildOtpAuthUri = ({
 var parseOtpAuthUri = (uri) => {
   const url = new URL(uri);
   if (url.protocol !== "otpauth:")
-    throw new BaseError(TOTP_ERROR_KEYS.INVALID_OTP_AUTH_URI);
+    throw new InternalError(TOTP_ERROR_KEYS.INVALID_OTP_AUTH_URI);
   if (url.hostname !== "totp")
-    throw new BaseError(TOTP_ERROR_KEYS.INVALID_OTP_AUTH_URI);
+    throw new InternalError(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(TOTP_ERROR_KEYS.MISSING_SECRET);
+    throw new InternalError(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";

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

@@ -12,7 +12,7 @@ export declare const buildOtpAuthUri: ({ secretBase32, label, issuer, algorithm,
  *
  * @param uri - OTPAuth URI to parse
  *
- * @throws ({@link BaseError}) - if the URI is invalid or missing required parameters
+ * @throws ({@link InternalError}) - if the URI is invalid or missing required parameters
  *
  * @returns Parsed URI parameters
  */

package/dist/utils/base32.d.ts

@@ -12,7 +12,7 @@ export declare const base32Encode: (input: string | Uint8Array, withPadding?: bo
  *
  * @param base32 - Base32 string to decode
  *
- * @throws ({@link BaseError}) - if invalid Base32 character is found
+ * @throws ({@link InternalError}) - if invalid Base32 character is found
  *
  * @returns Decoded bytes
  */

package/dist/utils/generate-secret-bytes.d.ts

@@ -3,7 +3,7 @@
  *
  * @param length - Number of bytes to generate (default: 20)
  *
- * @throws ({@link BaseError}) if length is not positive
+ * @throws ({@link InternalError}) if length is not positive
  *
  * @returns Uint8Array containing the random bytes
  */

package/dist/utils/index.js

@@ -6,10 +6,10 @@ import {
 } from "../chunk-q8z45f9z.js";
 import {
   TOTP_ERROR_KEYS
-} from "../chunk-4z2jb9kh.js";
+} from "../chunk-sx6rwmqe.js";
 
 // source/utils/base32.ts
-import { BaseError } from "@nowarajs/error";
+import { InternalError } from "@nowarajs/error";
 var BASE32_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
 var base32Encode = (input, withPadding = true) => {
   let result = "";
@@ -41,7 +41,7 @@ var base32Decode = (base32) => {
   for (const char of cleanBase32) {
     const charValue = BASE32_ALPHABET.indexOf(char);
     if (charValue === -1)
-      throw new BaseError(TOTP_ERROR_KEYS.INVALID_BASE32_CHARACTER, `Invalid Base32 character: ${char}`);
+      throw new InternalError(TOTP_ERROR_KEYS.INVALID_BASE32_CHARACTER, `Invalid Base32 character: ${char}`);
     value = value << 5 | charValue;
     bits += 5;
     if (bits >= 8) {
@@ -52,11 +52,11 @@ var base32Decode = (base32) => {
   return new Uint8Array(result);
 };
 // source/utils/generate-secret-bytes.ts
-import { BaseError as BaseError2 } from "@nowarajs/error";
+import { InternalError as InternalError2 } from "@nowarajs/error";
 import { getRandomValues } from "crypto";
 var generateSecretBytes = (length = 20) => {
   if (length <= 0)
-    throw new BaseError2(TOTP_ERROR_KEYS.INVALID_SECRET_LENGTH);
+    throw new InternalError2(TOTP_ERROR_KEYS.INVALID_SECRET_LENGTH);
   return getRandomValues(new Uint8Array(length));
 };
 // source/utils/time-remaining.ts

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nowarajs/totp",
-	"version": "1.1.12",
+	"version": "1.2.1",
 	"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.38.0",
-		"@nowarajs/error": "^1.3.8",
-		"@stylistic/eslint-plugin": "^5.5.0",
-		"@types/bun": "^1.3.0",
-		"eslint": "^9.38.0",
-		"globals": "^16.4.0",
-		"typescript-eslint": "^8.46.2",
+		"@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.8"
+		"@nowarajs/error": "^1.4.0"
 	},
 	"exports": {
 		"./enums": "./dist/enums/index.js",

package/dist/chunk-4z2jb9kh.js

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