JSPM

@se-oss/otp

1.0.0
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 1
  • Score
    100M100P100Q27691F
  • License MIT

A simple and lightweight library for generating and verifying one-time passwords (OTP) that are compatible with Google Authenticator. It supports both time-based (TOTP) and counter-based (HOTP) OTPs.

Package Exports

  • @se-oss/otp

Readme

@se-oss/otp

CI NPM Version MIT License Install Size

@se-oss/otp is a simple and lightweight library for generating and verifying one-time passwords (OTP) that are compatible with Google Authenticator. It supports both time-based (TOTP) and counter-based (HOTP) OTPs.


📦 Installation

npm install @se-oss/otp
Install using your favorite package manager

pnpm

pnpm install @se-oss/otp

yarn

yarn add @se-oss/otp

📖 Usage

Generating a New OTP Instance

To get started, you can generate a new OTP instance. This will create a cryptographically secure secret for you.

import { OTP } from '@se-oss/otp';

// Generate a new OTP instance with default options
const otp = OTP.generate();

// You can access the secret to store it for later use
console.log('Generated Secret:', otp.secret);
// e.g., store otp.secret in your database for a user

Loading an Existing Secret

If you have an existing base32 encoded secret, you can create an OTP instance with it.

import { OTP } from '@se-oss/otp';

const existingSecret = 'GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ'; // User's secret from your database

const otp = new OTP({ secret: existingSecret });

TOTP (Time-Based OTP)

TOTP is the most common type of OTP, used by apps like Google Authenticator.

// Assuming 'otp' is an OTP instance from the examples above

// Generate a TOTP code
const code = otp.totp();
console.log('Current TOTP code:', code);

// To verify a code from the user:
const userCode = '123456'; // Code provided by the user
const isValid = otp.totpVerify({ code: userCode });

if (isValid) {
  console.log('✅ Code is valid!');
} else {
  console.log('❌ Code is invalid!');
}

// You can also check a wider window of time (e.g., 2 steps back, 2 steps forward)
const isValidWithWindow = otp.totpVerify({ code: userCode, window: 2 });

HOTP (Counter-Based OTP)

HOTP uses a counter instead of time. The counter must be synchronized between the server and the client.

// Assuming 'otp' is an OTP instance from the examples above

const counter = 1; // This should be stored and incremented on your server

// Generate an HOTP code
const code = otp.hotp({ counter });
console.log(`HOTP code for counter ${counter}:`, code);

// To verify a code from the user:
const userCode = '755224'; // Code provided by the user for counter 1
const isValid = otp.hotpVerify({ code: userCode, counter });

if (isValid) {
  console.log('✅ Code is valid!');
  // IMPORTANT: Increment the counter for this user for the next verification
} else {
  console.log('❌ Code is invalid!');
}

✅ Todo

  • Generate otpauth:// URI for QR code scanning
  • Create dedicated TOTP and HOTP classes
  • Add QR code generation (e.g., as a data URI)
  • Add recovery codes generation
  • Add more detailed documentation and examples

📚 Documentation

For all configuration options, please see the API docs.

📑 References

  • HOTP (HMAC-Based One-Time Password Algorithm): RFC 4226
  • TOTP (Time-Based One-Time Password Algorithm): RFC 6238

🤝 Contributing

Want to contribute? Awesome! To show your support is to star the project, or to raise issues on GitHub

Thanks again for your support, it is much appreciated! 🙏

License

MIT © Shahrad Elahi and contributors.