# totp-auth

> Easy-to-use timebased one time password(TOTP) generator, competible with Google Authenticator.

Latest version **1.1.0** (published 2026-05-05) · ISC license · 0 weekly downloads

## Install

```sh
npm install totp-auth
pnpm add totp-auth
yarn add totp-auth
bun add totp-auth
```

Provides the command `totp-auth`.

## Health

**Score 55/100 (C)** — status: stable.

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

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 1.1.0 |
| Published | 2026-05-05 |
| First published | 2022-09-14 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 8.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Author | Kelvin Ng |
| Maintainers | hoishing |
| Keywords | google authenticator, totp, onetime password |

## Links

- npm: https://www.npmjs.com/package/totp-auth
- Repository: https://github.com/hoishing/totp-auth
- Homepage: https://github.com/hoishing/totp-auth#readme
- Issues: https://github.com/hoishing/totp-auth/issues
- npm.io page: https://npm.io/package/totp-auth

## Dependencies (1)

- [jssha](https://npm.io/package/jssha.md) ^3.2.0

## Alternatives

- [@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
- [escher-request](https://npm.io/package/escher-request.md) — 545 weekly downloads

## Recent versions

- 1.1.0 (latest) — 2026-05-05
- 1.0.11 — 2022-11-24
- 1.0.10 — 2022-10-04
- 1.0.9 — 2022-09-29
- 1.0.8 — 2022-09-28
- 1.0.7 — 2022-09-15
- 1.0.6 — 2022-09-15
- 1.0.5 — 2022-09-15
- 1.0.4 — 2022-09-15
- 1.0.3 — 2022-09-15
- 1.0.2 — 2022-09-15
- 1.0.1 — 2022-09-15
- 1.0.0 — 2022-09-14

## README

# TOTP Auth

[![npm-badge]][npm-totp] ![ts-badge] ![prettier-badge] ![license-badge]

> Easy-to-use timebased one time password(TOTP) generator, compatible with Google Authenticator.

🔗 [source code](https://github.com/hoishing/totp-auth)

[npm-badge]: https://img.shields.io/npm/v/totp-auth
[license-badge]: https://img.shields.io/npm/l/totp-auth
[ts-badge]: https://img.shields.io/badge/%3C%2F%3E-TypeScript-blue
[prettier-badge]: https://img.shields.io/badge/formatter-prettier-yellow

## Installation

```shell
# pnpm
pnpm i totp-auth

# npm
npm i totp-auth
```

## Usage

### CLI

```shell
totp-auth JBSWY3DPEHPK3PXP
# {"passcode":"123456","expire-seconds":17}
```

The CLI accepts the TOTP secret as the first positional argument and writes only JSON to stdout on success. The `expire-seconds` value is the number of seconds remaining before the current passcode rotates.

Invalid or missing secrets return a JSON error on stderr and exit with a non-zero status.

```shell
totp-auth asdf
# {"error":"invalid secret"}
```

### Library

```js
import { createTOTP, countdown } from "totp-auth"
import { setInterval } from "timers/promises"

//secret from service provider
const secret = "abcd1234"

let totp = createTOTP(secret)
let expire = countdown()

// current TOTP and expiring time in seconds
console.log(`TOTP: ${totp}, expire: ${expire}`)

// keep counting down and refresh TOTP every 30 sec
for await (let _ of setInterval(1000)) {
  const cnt = countdown()
  if (cnt >= expire) totp = createTOTP(secret)
  expire = cnt
  console.log(`TOTP: ${totp}, expire: ${expire}`)
}
```

### Error Handling

Not all strings can be secret key, invalid secret key will return a customizable error message.

```js
// invalid secret -> default error message
createTOTP('asdf') // returns "invalid secret" 

// invalid secret w/ custom error message
createTOTP('asdf', undefined, 'bad key') // returns "bad key" 
```

## Technical Details

📥 [npm package download][npm-totp]

### code logic

1. create base32 representation of the credential
1. calculate HMAC hash from the credential with current time
1. shift and trim 6 digit TOTP from the hash above

### Tests

Both `createTOTP` and `countdown` are pure functions. Unit test with [Jest](https://jestjs.io/) are included.

The TOTP output could also simply verified by Google Authenticator output.

## Credits

Algorithm ref: http://jsfiddle.net/russau/ch8PK/
HMAC lib: https://github.com/Caligatio/jsSHA

## FAQ

- How can I extract secret keys from Google Authenticator?
  - use another npm package: https://github.com/krissrex/google-authenticator-exporter
  - use chrome extension: https://authenticator.cc/

## Questions?

Open a [github issue] or ping me on [Twitter ![twitter-icon]][Twitter]

[github issue]: https://github.com/hoishing/totp-auth/issues
[Twitter]: https://twitter.com/intent/tweet?text=https://github.com/hoishing/totp-auth/%20%0D@hoishing
[twitter-icon]: https://api.iconify.design/logos/twitter.svg?width=20
[npm-totp]: https://www.npmjs.com/package/totp-auth

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