@otp-lib/core

> TOTP (Time-based) and HOTP (HMAC-based) One-Time Password library


About

@otp-lib/core is designed to build strict, compliant implementation of One-Time Passwords (OTP) algorithms.

Built on top of the native Web Crypto API, it ensures cryptographic security and performance across all modern JavaScript environments (Node.js, Deno, Bun, Browsers, Cloudflare Workers).

Features

* Secure : Uses the native Web Crypto API (crypto.subtle) for cryptographic operations.
* Isomorphic : Works in Node.js, Bun, Deno, Browsers, and Cloudflare Workers.
* Type-Safe : Written in strict TypeScript with full type definitions included.
* Zero Dependencies : No external overhead. Lightweight and fast.
* Compliant : Strict implementations of the IETF standards :
* RFC 4226 : HMAC-Based One-Time Password (HOTP).
* RFC 6238 : Time-Based One-Time Password (TOTP).
* RFC 4648 : Base32 and Base64 Data Encodings.

Install

$3

``bash
npm install @otp-lib/core
`

$3

`bash
bun add @otp-lib/core
`

$3

`bash
deno install npm:@otp-lib/core
`

$3

For modern browsers, you can import the ECMAScript Module (ESM) directly from unpkg.

`html

`

$3

For legacy usage without a bundler, you can use the minified script from unpkg.

`html



`

Quick Start

$3

`typescript
import { Secret } from "@otp-lib/core";

// Generate a random cryptographically secure secret (20 bytes)
const secret = Secret.create();

// OR import from an existing string (e.g., from your configuration)
const secretFromBase32 = Secret.fromBase32("JBSWY3DPEHPK3PXP");
const secretFromHex = Secret.fromHex("48656c6c6f21deadbeef");

// Export for storage or display
console.log(secret.toBase32()); // "JBSWY3DPEHPK3PXP"
console.log(secret.toHex()); // "4865..."
`

$3

Implements the HMAC-Based algorithm where codes are generated from an incrementing counter.

`typescript
import { HOTP, Secret } from "@otp-lib/core";

const secret = Secret.create();
const hotp = new HOTP({
secret,
counter: 0, // Current counter state
lookAhead: 3 // Allow validating 3 steps ahead (resync)
});

// Generate
const token = await hotp.generate();

// Verify and Resync
// verifyDelta returns the difference if valid, or null if invalid
const delta = await hotp.verifyDelta("123456");

if(delta !== null) {
// Success! Update your database with the new counter
const newCounter = hotp.getCounter() + delta + 1;
// saveToDb(newCounter);
}
`

$3

Implements the Time-Based algorithm where codes are generated based on the current system time.

`typescript
import { TOTP, Secret } from "@otp-lib/core";

const secret = Secret.fromBase32("JBSWY3DPEHPK3PXP");
const totp = new TOTP({ secret });

// Generate a token
const token = await totp.generate();
console.log(token); // e.g. "123456"

// Verify a token
// Returns true if the token is valid within the current window
const isValid = await totp.verify("123456");
`

References

$3

> HOTP and TOTP accept the following OTP options.

| Option | Type | Default | Description |
| ------ | ---- | ------- | ----------- |
| algorithm | HashAlgorithms | SHA-1 | The HMAC hashing algorithm (SHA-1, SHA-256, SHA-384, SHA-512). |
| digits | number | 6 | The length of the generated code. |
| secret | Secret | Secret.create() | The shared secret key instance. |

$3

> Extends OTP Options.

| Option | Type | Default | Description |
| ------ | ---- | ------- | ----------- |
| lookAhead | number | 0 | The number of future codes to check during validation (Resynchronization window). |
| counter | number | 0 | The initial counter value. |

$3

> Extends OTP Options.

| Option | Type | Default | Description |
| ------ | ---- | ------- | ----------- |
| window | number \|
[number, number] | [0, 0] | The validation window to tolerate clock drift or latency.
• Number : Symmetric window (e.g., 1 = ±1 step).
• Tuple : [past, future] steps (e.g., [1, 0]` allows 1 step back, 0 forward). |
| period | number | 30 | The time step in seconds. |

License

MIT © Unknown-Robot