# otp-io

> 🕖 Typed library to work 2fa via Google Authenticator/Time-based TOTP/Hmac-based HOTP

Latest version **1.2.7** (published 2024-12-31) · MIT license · 0 weekly downloads

## Install

```sh
npm install otp-io
pnpm add otp-io
yarn add otp-io
bun add otp-io
```

## Health

**Score 40/100 (D)** — status: maintenance-mode.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.2.7 |
| Published | 2024-12-31 |
| First published | 2023-02-19 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=14 |
| Dependencies | 0 |
| Unpacked size | 71.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 16 |
| Author | Alexander G |
| Maintainers | alexxandergrib |
| Keywords | 2fa, otp, hotp, topt, google authenticator, authenticator, one time password, one-time-password, authentication, 2 factor, node, browser, frontend, backend |

## Links

- npm: https://www.npmjs.com/package/otp-io
- Repository: https://github.com/AlexXanderGrib/otp
- Homepage: https://github.com/AlexXanderGrib/otp#readme
- Issues: https://github.com/AlexXanderGrib/otp/issues
- npm.io page: https://npm.io/package/otp-io

## Alternatives

- [@clerk/clerk-expo](https://npm.io/package/@clerk/clerk-expo.md) — 133.6K weekly downloads
- [@pothos/plugin-authz](https://npm.io/package/@pothos/plugin-authz.md) — 12.4K weekly downloads
- [@bounded-sh/client](https://npm.io/package/@bounded-sh/client.md) — 3.2K weekly downloads
- [@luigi-project/plugin-auth-oauth2](https://npm.io/package/@luigi-project/plugin-auth-oauth2.md) — 2.3K weekly downloads
- [@nocobase/plugin-verification](https://npm.io/package/@nocobase/plugin-verification.md) — 2.0K weekly downloads

## Recent versions

- 1.2.7 (latest) — 2024-12-31
- 1.2.6 — 2023-07-11
- 1.2.5 — 2023-07-11
- 1.2.4 — 2023-07-11
- 1.2.3 — 2023-07-11
- 1.2.2 — 2023-07-11
- 1.2.1 — 2023-07-11
- 1.2.0 — 2023-07-11
- 1.1.1 — 2023-02-26
- 1.1.0 — 2023-02-26
- 1.0.2 — 2023-02-19
- 1.0.1 — 2023-02-19
- 1.0.0 — 2023-02-19

## README

# OTP io

> Typed library to work 2fa via Google Authenticator/Time-based TOTP/Hmac-based HOTP

[![Test Status](https://github.com/AlexXanderGrib/otp/actions/workflows/test.yml/badge.svg)](https://github.com/AlexXanderGrib/otp)
[![Downloads](https://img.shields.io/npm/dt/otp-io.svg)](https://npmjs.com/package/otp-io)
[![last commit](https://img.shields.io/github/last-commit/AlexXanderGrib/otp.svg)](https://github.com/AlexXanderGrib/otp)
[![codecov](https://img.shields.io/codecov/c/github/AlexXanderGrib/otp/main.svg)](https://codecov.io/gh/AlexXanderGrib/otp)
[![GitHub](https://img.shields.io/github/stars/AlexXanderGrib/otp.svg)](https://github.com/AlexXanderGrib/otp)
[![otp-io](https://snyk.io/advisor/npm-package/otp-io/badge.svg)](https://snyk.io/advisor/npm-package/otp-io)
[![Known Vulnerabilities](https://snyk.io/test/npm/otp-io/badge.svg)](https://snyk.io/test/npm/otp-io)
[![Quality](https://img.shields.io/npms-io/quality-score/otp-io.svg?label=quality%20%28npms.io%29&)](https://npms.io/search?q=otp-io)
[![npm](https://img.shields.io/npm/v/otp-io.svg)](https://npmjs.com/package/otp-io)
[![license MIT](https://img.shields.io/npm/l/otp-io.svg)](https://github.com/AlexXanderGrib/otp/blob/main/LICENSE.txt)
[![Size](https://img.shields.io/bundlephobia/minzip/otp-io)](https://bundlephobia.com/package/otp-io)

[Example](#how-it-works) • [API Reference](./docs/api/README.md)

## Why use this lib?

- **Small.** Tree-shakable, 0 dependencies
- **Tested.** Compatibility with [Google Authenticator](https://github.com/google/google-authenticator/wiki/Key-Uri-Format) and with [RFC4226 (HOTP)](https://www.ietf.org/rfc/rfc4226.txt) and [RFC6238 (TOTP)](https://www.ietf.org/rfc/rfc6238.txt)

## Install

- `npm`
  ```bash
  npm i otp-io
  ```
- `Yarn`
  ```bash
  yarn add otp-io
  ```

## What is this?

- `HOTP` - HMAC-based One Time Password generation method. Uses incrementing with each login `counter` and `secret` to generate unique 6-8 digit codes.
- `TOTP` - Time-based, uses `current time` modulo `period` (seconds) as counter in `HOTP`,
- `Google Authenticator` - uses simplified version of `TOTP` to generate codes. Differences:
  - Only `SHA-1` hash support
  - Only 6 digit codes
  - Keys should not be padded
  - TOTP period is 30 seconds

Google Authenticator limits are defaults for this library.

## How it works?

```typescript
// 1. Import library - use totp (code changes with time)
import { totp, generateKey, getKeyUri } from "otp-io";
// 2. Import crypto adapter. 
// Specify `crypto-node` or `crypto-web` if node/bundler cannot 
// detect correct version
import { hmac, randomBytes } from "otp-io/crypto";

// 3. Get key from somewhere. Or generate it
const secret = generateKey(randomBytes, /* bytes: */ 20); // 5-20 good for Google Authenticator

// 4. Get key import url
const url = getKeyUri({
  type: "totp",
  secret,
  name: "User's Username",
  issuer: "Your Site Name"
});

// 5. Show it to user as QR code - send it back to client
// Get 6-digit code back from him, as confirmation of saving secret key

const input = "...";

const code = await totp(hmac, { secret });

if (code === input) {
  // 6. Done. User configured your key
}
```

## Api Reference

[API Reference](./docs/api/modules.md)

---
_Source: https://npm.io/package/otp-io · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._