@kiryano/etherealotp/README.md

A library for two-factor authentication using Twilio and Speakeasy.

**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:
```bash
npm install @kiryano/etherealotp
```

Or using yarn:
```bash
yarn add @kiryano/etherealotp
```

**Quick Start**
- Here's a quick example to get you started:

```javascript
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));

```

### Generating a QR Code for TOTP Setup

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:

```javascript
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**
```javascript
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.