0
# OTPLib
1

2
OTPLib is a comprehensive JavaScript One-Time Password (OTP) library implementing both HOTP (RFC 4226) and TOTP (RFC 6238) algorithms. It provides secure authentication solutions compatible with Google Authenticator and other standard authenticator applications, supporting both Node.js and browser environments with full TypeScript definitions.
3

4
## Package Information
5

6
- **Package Name**: otplib
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install otplib`
10

11
## Core Imports
12

13
```typescript
14
import { authenticator, totp, hotp } from "otplib";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { authenticator, totp, hotp } = require("otplib");
21
```
22

23
For browser environments:
24

25
```html
26
<script src="https://unpkg.com/@otplib/preset-browser@^12.0.0/buffer.js"></script>
27
<script src="https://unpkg.com/@otplib/preset-browser@^12.0.0/index.js"></script>
28
<script>
29
  // window.otplib.authenticator, window.otplib.hotp, window.otplib.totp
30
</script>
31
```
32

33
## Basic Usage
34

35
```typescript
36
import { authenticator, totp, hotp } from "otplib";
37

38
// Authenticator (TOTP with Base32 secrets - Google Authenticator compatible)
39
const secret = authenticator.generateSecret();
40
const token = authenticator.generate(secret);
41
const isValid = authenticator.check(token, secret);
42

43
// TOTP (Time-based)
44
const totpToken = totp.generate("your-secret-key");
45
const isTotpValid = totp.check(totpToken, "your-secret-key");
46

47
// HOTP (Counter-based)
48
const hotpToken = hotp.generate("your-secret-key", 0);
49
const isHotpValid = hotp.check(hotpToken, "your-secret-key", 0);
50
```
51

52
## Architecture
53

54
OTPLib is built with a modular architecture:
55

56
- **Core Classes**: Base HOTP, TOTP, and Authenticator implementations with full customization options
57
- **Preset Packages**: Pre-configured instances optimized for different environments (Node.js, browser, v11 compatibility)
58
- **Plugin System**: Pluggable crypto and base32 libraries for different platforms
59
- **Type Safety**: Full TypeScript support with generic types preserving option configurations
60
- **RFC Compliance**: Tested against RFC 4226 and RFC 6238 test vectors
61

62
## Capabilities
63

64
### Authenticator (Google Authenticator Compatible)
65

66
TOTP-based authenticator with Base32 secret encoding, fully compatible with Google Authenticator and similar apps. Handles secret generation, QR code URI creation, and token verification.
67

68
```typescript { .api }
69
class Authenticator {
70
  generate(secret: string): string;
71
  check(token: string, secret: string): boolean;
72
  verify(opts: { token: string; secret: string }): boolean;
73
  generateSecret(numberOfBytes?: number): string;
74
  keyuri(accountName: string, issuer: string, secret: string): string;
75
}
76

77
const authenticator: Authenticator;
78
```
79

80
[Authenticator](./authenticator.md)
81

82
### TOTP (Time-based One-Time Password)
83

84
Time-based OTP implementation following RFC 6238. Generates tokens based on current time with configurable time steps and validation windows.
85

86
```typescript { .api }
87
class TOTP {
88
  generate(secret: string): string;
89
  check(token: string, secret: string): boolean;
90
  verify(opts: { token: string; secret: string }): boolean;
91
  checkDelta(token: string, secret: string): number | null;
92
  timeRemaining(): number;
93
  timeUsed(): number;
94
  keyuri(accountName: string, issuer: string, secret: string): string;
95
}
96

97
const totp: TOTP;
98
```
99

100
[TOTP](./totp.md)
101

102
### HOTP (HMAC-based One-Time Password)
103

104
Counter-based OTP implementation following RFC 4226. Generates tokens using an incrementing counter value with configurable digits and algorithms.
105

106
```typescript { .api }
107
class HOTP {
108
  generate(secret: string, counter: number): string;
109
  check(token: string, secret: string, counter: number): boolean;
110
  verify(opts: { token: string; secret: string; counter: number }): boolean;
111
  keyuri(accountName: string, issuer: string, secret: string, counter: number): string;
112
}
113

114
const hotp: HOTP;
115
```
116

117
[HOTP](./hotp.md)
118

119
### Configuration and Options
120

121
Comprehensive configuration system allowing customization of algorithms, token length, time windows, encoding, and crypto implementations.
122

123
```typescript { .api }
124
interface HOTPOptions {
125
  algorithm: 'sha1' | 'sha256' | 'sha512';
126
  digits: number;
127
  encoding: 'ascii' | 'base64' | 'hex' | 'latin1' | 'utf8';
128
}
129

130
interface TOTPOptions extends HOTPOptions {
131
  epoch: number;
132
  step: number;
133
  window: number | [number, number];
134
}
135

136
interface AuthenticatorOptions extends TOTPOptions {
137
  // Additional Base32 encoding/decoding options
138
}
139
```
140

141
[Configuration](./configuration.md)
142

143
### Environment Presets
144

145
Different preset packages optimized for specific environments with appropriate crypto and base32 implementations.
146

147
```typescript { .api }
148
// Node.js (default)
149
import { authenticator, totp, hotp } from "otplib";
150

151
// Browser
152
import { authenticator, totp, hotp } from "@otplib/preset-browser";
153

154
// v11 Compatibility
155
import { authenticator, totp, hotp } from "@otplib/preset-v11";
156
```
157

158
[Environment Presets](./presets.md)
159

160
## Types
161

162
```typescript { .api }
163
type SecretKey = string;
164
type Base32SecretKey = string;
165
type HexString = string;
166

167
enum HashAlgorithms {
168
  SHA1 = 'sha1',
169
  SHA256 = 'sha256',
170
  SHA512 = 'sha512'
171
}
172

173
enum KeyEncodings {
174
  ASCII = 'ascii',
175
  BASE64 = 'base64',
176
  HEX = 'hex',
177
  LATIN1 = 'latin1',
178
  UTF8 = 'utf8'
179
}
180

181
interface OTPOptions {
182
  [key: string]: unknown;
183
}
184
```