time2fa - GitLite

KO | EN

gitlite — search

#javascript #ai #llm #go #linux #docker #windows #awesome #cli #awesome-list #vue #security #ios #open-source

time2fa

(★ 149)

A comprehensive Node.js package that simplifies the implementation of One-Time Password (OTP).

File Explorer

Download Latest Version (.zip)

- - build.yml
  - publish.yml
- logo.png
- - hmac-based.ts
- - index.ts
- - generate-key.ts
  - time-based.ts
- - constants.ts
  - encode.ts
  - validation-error.ts
- index.ts
- otp.test.ts
.gitignore
.npmrc
build.config.ts
eslint.config.mjs
LICENSE
package-lock.json
package.json
README.md
renovate.json
tsconfig.json

# Installation Guide

1. Get the code

git clone https://github.com/PlanetHoster/time2fa

Downloads the entire project code from GitHub to your computer.

cd time2fa

Moves into the project folder you just downloaded.

2. Node.js

Easy Recommended

Prerequisites

Git Needed to download the project code from GitHub.
Node.js Node.js must be installed to use npm. The LTS version is recommended.

npm i --save time2fa

Type this command into your terminal and run it.

npm run test

Type this command into your terminal and run it.

✅ After running the command, open the address shown in the terminal (usually something like http://localhost:3000) in your browser.

Pulled directly from this repo's README.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[![Build & test](https://github.com/PlanetHoster/time2fa/actions/workflows/build.yml/badge.svg?branch=main&event=push)](https://github.com/PlanetHoster/time2fa/actions/workflows/build.yml) [![npm](https://img.shields.io/npm/v/time2fa?label=time2fa%40npm)](https://www.npmjs.com/package/time2fa)

![Time2fa](https://github.com/PlanetHoster/time2fa/blob/main/doc/logo.png?raw=true)

A comprehensive Node.js package that simplifies the implementation of One-Time Password (OTP) authentication using HMAC-based One-Time Password (HOTP) and Time-based One-Time Password (TOTP) algorithms.

## Features

- Support both HOTP and TOTP algorithms
- Easy-to-use API for generating and verifying OTPs
- Customizable OTP length, counters and time window
- Supports various hashing algorithms (SHA-1, SHA-256, SHA-512)
- Compatible with popular OTP generators like Google Authenticator and Authy

## Installation

Install the package using NPM:

```bash
npm i --save time2fa
```

## Usage/Examples

### TOTP

#### Generate key

```javascript
// Import Totp
import { Totp } from "time2fa";

const key = Totp.generateKey({ issuer: "N0C", user: "johndoe@n0c.com" });

console.log(key);

// GenerateKey {
//   issuer: 'N0C',
//   user: 'johndoe@n0c.com',
//   config: { algo: 'sha1', digits: 6, period: 30, secretSize: 10 },
//   secret: 'ABCDEFGHIJKLMN12',
//   url: 'otpauth://totp/N0C:johndoe%40n0c.com?issuer=N0C&period=30&secret=ABCDEFGHIJKLMN12'
// }
```

#### Validate passcode

```javascript
// Import Totp
import { Totp } from "time2fa";

const valid = Totp.validate({ passcode: "123456", secret: "ABCDEFGHIJKLMN12" });

console.log(valid);

// true || false
```

#### Generate passcodes

```javascript
// Import Totp, and generateConfig for default configuration
import { Totp, generateConfig } from "time2fa";

const config = generateConfig();
const codes = Totp.generatePasscodes({ secret: "ABCDEFGHIJKLMN12" }, config);

console.log(codes);

// [ 123456 ]
```

#### QRCode generation

You must use an external library. For the example below we use [qrcode](https://github.com/soldair/node-qrcode).

```javascript
// Import Totp and qrcode
import { Totp } from "time2fa";
import * as qrcode from "qrcode";

const key = Totp.generateKey({ issuer: "N0C", user: "johndoe@n0c.com" });

console.log(key);

// GenerateKey {
//   issuer: 'N0C',
//   user: 'johndoe@n0c.com',
//   config: { algo: 'sha1', digits: 6, period: 30, secretSize: 10 },
//   secret: 'ABCDEFGHIJKLMN12',
//   url: 'otpauth://totp/N0C:johndoe%40n0c.com?issuer=N0C&period=30&secret=ABCDEFGHIJKLMN12'
// }

qrcode.toDataURL(key.url, (err, url) => {
  console.log(url); // Returns a Data URI containing a representation of the QR Code image.
});
```

### HOTP

#### Generate Passcode

```javascript
// Import Hotp, and generateConfig for default configuration and generateSecret
import { Hotp, generateConfig, generateSecret } from "time2fa";

const config = generateConfig();
const secret = generateSecret();

const code = Hotp.generatePasscode({ secret, counter: 1 }, config);

console.log(code);

// 123456
```

#### Validate passcode

```javascript
// Import Hotp
import { Hotp } from "time2fa";

const valid = Hotp.validate({
  passcode: "123456",
  secret: "ABCDEFGHIJKLMN12",
  counter: 1,
});

console.log(valid);

// true || false
```

### Helpers

#### generateConfig()

Generate default configuration

```javascript
// Import generateConfig
import { generateConfig } from "time2fa";

const config = generateConfig();

console.log(config);

// { algo: 'sha1', digits: 6, period: 30, secretSize: 10 }
```

#### generateSecret()

Only support base32 at the moment

```javascript
// Import generateSecret
import { generateSecret } from "time2fa";

const secret = generateSecret();

console.log(secret);

// ABCDEFGHIJKLMN12
```

#### generateUrl()

```javascript
// Import generateSecret
import { generateUrl } from "time2fa";

const url = generateUrl({
  issuer: "N0C",
  user: "johndoe@n0c.com",
  secret: "ABCDEFGHIJKLMN12",
});

console.log(url);

// otpauth://totp/N0C:johndoe%40n0c.com?issuer=N0C&period=30&secret=ABCDEFGHIJKLMN12
```

#### generateBackupCodes()

Backup code should only be used once

```javascript
// Import generateBackupCodes
import { generateBackupCodes } from "time2fa";

const backupCodes = generateBackupCodes();

console.log(backupCodes);

// [
//   '810550', '236884',
//   '979342', '815504',
//   '835313', '529942',
//   '263100', '882025',
//   '204896', '516248'
// ]
```

## Documentation

### Functions

#### Helpers

generateConfig(config?: [TotpConfig](#TotpConfig)): `ValidTotpConfig`

generateSecret(secretSize: number = DEFAULT_TOTP_SECRET_SIZE): `string`

generateBackupCodes(numCodes = 10, codeLength = DEFAULT_TOTP_DIGITS): `string[]`

generateUrl(options: [UrlOptions](#UrlOptions), config: [ValidTotpConfig](#ValidTotpConfig)): `string`

#### Totp

Totp.generateKey(options: [TotpOptions](#TotpOptions), config?: [TotpConfig](#TotpConfig)): `GenerateKey`

Totp.generatePasscodes(options: [TotpCode](#TotpCode), config: [ValidTotpConfig](#ValidTotpConfig)): `string[]`

Totp.validate(options: [TotpValidateOptions](#TotpValidateOptions), config?: [TotpConfig](#TotpConfig)): `boolean`

#### Hotp

Hotp.generatePasscode(options: [HotpCode](#HotpCode), config: [ValidTotpConfig](#ValidTotpConfig)): `string`

Hotp.validate(options: [HotpValidateOptions](#HotpValidateOptions), config?: [TotpConfig](#TotpConfig)): `boolean`

### Interfaces / Parameters

#### `TotpConfig`

| Parameter    | Type         | default | Description                                   |
| :----------- | :----------- | :------ | --------------------------------------------- |
| `secretSize` | `number`     | 10      | **Optional** - Secret size                    |
| `period`     | `number`     | 30      | **Optional** - Period of time                 |
| `digits`     | `number`     | 6       | **Optional**- Code length                     |
| `algo`       | `Algorithms` | sha1    | **Optional** - 'sha1' \| 'sha256' \| 'sha512' |

#### `ValidTotpConfig`

| Parameter    | Type         | default | Description                                   |
| :----------- | :----------- | :------ | --------------------------------------------- |
| `secretSize` | `number`     | -       | **Required** - Secret size                    |
| `period`     | `number`     | -       | **Required** - Period of time                 |
| `digits`     | `number`     | -       | **Required**- Code length                     |
| `algo`       | `Algorithms` | -       | **Required** - 'sha1' \| 'sha256' \| 'sha512' |

#### `TotpOptions`

| Parameter | Type     | default | Description                |
| :-------- | :------- | :------ | -------------------------- |
| `issuer`  | `string` | -       | **Required** - Issuer name |
| `user`    | `string` | -       | **Required** - Username    |

#### `UrlOptions`

| Parameter | Type     | default | Description                |
| :-------- | :------- | :------ | -------------------------- |
| `issuer`  | `string` | -       | **Required** - Issuer name |
| `user`    | `string` | -       | **Required** - Username    |
| `secret`  | `string` | -       | **Required** - Secret      |

#### `TotpCode`

| Parameter | Type     | default | Description                   |
| :-------- | :------- | :------ | ----------------------------- |
| `secret`  | `string` | -       | **Required** - Secret         |
| `drift`   | `number` | 0       | **Optional** - Time tolerance |

#### `TotpValidateOptions`

| Parameter  | Type     | default | Description                             |
| :--------- | :------- | :------ | --------------------------------------- |
| `passcode` | `string` | -       | **Required** - The passcode to validate |
| `secret`   | `string` | -       | **Required** - Secret                   |
| `drift`    | `number` | 0       | **Optional** - Time tolerance           |

#### `HotpCode`

| Parameter | Type     | default | Description                         |
| :-------- | :------- | :------ | ----------------------------------- |
| `secret`  | `string` | -       | **Required** - Secret               |
| `counter` | `number` | -       | **Required** - Custom counter value |

#### `HotpValidateOptions`

| Parameter  | Type     | default | Description                             |
| :--------- | :------- | :------ | --------------------------------------- |
| `passcode` | `string` | -       | **Required** - The passcode to validate |
| `secret`   | `string` | -       | **Required** - Secret                   |
| `counter`  | `number` | -       | **Required** - Custom counter value     |

## Contributing

All PR's are welcome!

## Running Tests

To run tests, run the following command

```bash
npm run test
```

## License

[MIT](https://choosealicense.com/licenses/mit/)