EtherealOTP
EtherealOTP is a lightweight, easy-to-use library for integrating Two-Factor Authentication (2FA) into your Node.js applications using TOTP (Time-based One-Time Passwords) and the Twilio SMS service.
Features
- Easy generation and verification of TOTP tokens. Seamlessly send TOTP tokens via SMS using Twilio. Straightforward setup and minimal configuration.
Installation
- Install EtherealOTP using npm:
npm install @kiryano/etherealotpOr using yarn:
yarn add @kiryano/etherealotpQuick Start
- Here's a quick example to get you started:
const { TwoFactorAuth } = require('@kiryano/etherealotp');
const config = {
accountSid: 'your_twilio_account_sid',
authToken: 'your_twilio_auth_token',
fromNumber: 'your_twilio_phone_number'
};
const tfa = new TwoFactorAuth(config);
// Generate a new TOTP secret for a user
const newUserSecret = tfa.generateSecret();
console.log('User Secret:', newUserSecret.base32);
// Generate a TOTP token
const newToken = tfa.generateToken(newUserSecret.base32);
console.log('Token:', newToken);
// Send OTP via SMS
tfa.sendSmsOTP('+18085976569', `Your verification code is: ${newToken}`)
.then(message => console.log('SMS sent successfully!', message))
.catch(err => console.error('Failed to send SMS:', err));The EtherealOTP library supports generating QR codes for user accounts identified by either an email address or a phone number. This QR code can be scanned with TOTP applications like Google Authenticator or Authy to easily set up two-factor authentication.
Here is how you can generate a QR code URL for the TOTP secret:
const { TwoFactorAuth } = require('@kiryano/etherealotp');
const tfa = new TwoFactorAuth({
accountSid: 'your_twilio_account_sid',
authToken: 'your_twilio_auth_token',
fromNumber: 'your_twilio_phone_number'
});
// Generate a new TOTP secret for the user
const userSecret = tfa.generateSecret();
console.log('User Secret:', userSecret.base32);
// Specify your application's name and the user's identifier
const issuer = 'YourAppName';
const identifier = 'user@example.com'; // or '+12345678901' for phone
const identifierType = 'email'; // Change to 'phone' if using a phone number
// Generate QR Code URL for the TOTP secret
tfa.generateQRCodeURL(issuer, identifier, identifierType, userSecret.base32)
.then(qrCodeURL => {
console.log('QR Code URL:', qrCodeURL);
// Here you can send the QR Code URL to the front end to be displayed as an image
})
.catch(error => {
console.error('Error generating QR code:', error);
});Documentation
generateSecret()
Generates a new TOTP secret.
Returns: An object containing the secret in various formats.
generateToken(secret)
Generates a TOTP token from a user's secret.
Parameters:
secret (String): The user's TOTP secret in base32 format.
Returns: A string representing the TOTP token.
verifyToken(token, secret)
Verifies a TOTP token against the user's secret.
Parameters:
token (String): The TOTP token to verify.
secret (String): The user's TOTP secret in base32 format.
Returns: true if the token is valid, otherwise false.
sendSmsOTP(phoneNumber, message)
Sends an SMS containing the TOTP token or any message using Twilio.
Parameters:
phoneNumber (String): The recipient's phone number.
message (String): The message to be sent.
Returns: A promise that resolves with the message details if successful.Contributing
- Contributions are welcome! Please read the contributing guide for more information.
License EtherealOTP is MIT licensed.