0
# notp
1

2
Node One Time Password library that provides fast, zero-dependency implementations of HOTP (counter-based) and TOTP (time-based) one time password algorithms. Fully compliant with RFC 4226 and RFC 6238, and compatible with Google Authenticator and other OTP applications.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```javascript
14
const notp = require('notp');
15
```
16

17
For ES modules:
18

19
```javascript
20
import * as notp from 'notp';
21
```
22

23
## Basic Usage
24

25
```javascript
26
const notp = require('notp');
27

28
// Generate TOTP token (most common use case)
29
const secret = 'user_secret_key';
30
const token = notp.totp.gen(secret);
31
console.log('Current TOTP token:', token);
32

33
// Verify TOTP token
34
const userToken = '123456'; // Token from user's authenticator app
35
const verification = notp.totp.verify(userToken, secret);
36
if (verification) {
37
    console.log('Token valid, delta:', verification.delta);
38
} else {
39
    console.log('Token invalid');
40
}
41

42
// Generate HOTP token (counter-based)
43
const counter = 1;
44
const hotpToken = notp.hotp.gen(secret, { counter: counter });
45

46
// Verify HOTP token  
47
const hotpVerification = notp.hotp.verify(hotpToken, secret, { counter: counter });
48
```
49

50
## Capabilities
51

52
### HOTP Generation
53

54
Generate counter-based One Time Passwords following RFC 4226.
55

56
```javascript { .api }
57
/**
58
 * Generate a counter based One Time Password
59
 * @param {string} key - Secret key for OTP generation (should be unique per user)
60
 * @param {Object} opt - Options object
61
 * @param {number} opt.counter - Counter value for HOTP generation (default: 0)
62
 * @returns {string} - 6-digit OTP token
63
 */
64
hotp.gen(key, opt)
65
```
66

67
**Usage Example:**
68

69
```javascript
70
const notp = require('notp');
71

72
// Generate HOTP with counter
73
const secret = 'shared_secret_key';
74
const options = { counter: 5 };
75
const token = notp.hotp.gen(secret, options);
76
console.log('HOTP Token:', token); // e.g., "254676"
77
```
78

79
### HOTP Verification
80

81
Verify counter-based One Time Passwords with configurable drift tolerance.
82

83
```javascript { .api }
84
/**
85
 * Verify a counter based One Time Password
86
 * @param {string} token - The OTP token to verify
87
 * @param {string} key - Secret key used for verification  
88
 * @param {Object} opt - Options object
89
 * @param {number} opt.window - Allowable margin for counter drift (default: 50)
90
 * @param {number} opt.counter - Current counter value (default: 0)
91
 * @returns {Object|null} - Returns {delta: number} on success, null on failure
92
 */
93
hotp.verify(token, key, opt)
94
```
95

96
**Usage Example:**
97

98
```javascript
99
const notp = require('notp');
100

101
const secret = 'shared_secret_key';
102
const userToken = '254676';
103
const options = { 
104
    counter: 5, 
105
    window: 10  // Check 10 positions forward/backward
106
};
107

108
const result = notp.hotp.verify(userToken, secret, options);
109
if (result) {
110
    console.log('Token valid, counter delta:', result.delta);
111
    // Update stored counter based on delta
112
} else {
113
    console.log('Token invalid');
114
}
115
```
116

117
### TOTP Generation
118

119
Generate time-based One Time Passwords following RFC 6238.
120

121
```javascript { .api }
122
/**
123
 * Generate a time based One Time Password
124
 * @param {string} key - Secret key for OTP generation (should be unique per user)
125
 * @param {Object} opt - Options object
126
 * @param {number} opt.time - Time step in seconds (default: 30)
127
 * @param {number} opt._t - Override current time (test environments only)
128
 * @returns {string} - 6-digit OTP token
129
 */
130
totp.gen(key, opt)
131
```
132

133
**Usage Example:**
134

135
```javascript
136
const notp = require('notp');
137

138
// Generate TOTP with default 30-second time step
139
const secret = 'shared_secret_key';
140
const token = notp.totp.gen(secret);
141
console.log('Current TOTP token:', token);
142

143
// Generate TOTP with custom time step
144
const customToken = notp.totp.gen(secret, { time: 60 }); // 60-second intervals
145
console.log('TOTP with 60s intervals:', customToken);
146
```
147

148
### TOTP Verification
149

150
Verify time-based One Time Passwords with configurable time drift tolerance.
151

152
```javascript { .api }
153
/**
154
 * Verify a time based One Time Password
155
 * @param {string} token - The OTP token to verify
156
 * @param {string} key - Secret key used for verification
157
 * @param {Object} opt - Options object
158
 * @param {number} opt.window - Allowable margin for time drift (default: 6)
159
 * @param {number} opt.time - Time step in seconds (default: 30)
160
 * @param {number} opt._t - Override current time (test environments only)
161
 * @returns {Object|null} - Returns {delta: number} on success, null on failure
162
 */
163
totp.verify(token, key, opt)
164
```
165

166
**Usage Example:**
167

168
```javascript
169
const notp = require('notp');
170

171
const secret = 'shared_secret_key';
172
const userToken = '123456'; // From user's authenticator app
173
const options = { 
174
    window: 2,  // Check 2 time steps forward/backward
175
    time: 30    // 30-second time steps
176
};
177

178
const result = notp.totp.verify(userToken, secret, options);
179
if (result) {
180
    console.log('Token valid, time delta:', result.delta);
181
} else {
182
    console.log('Token invalid or expired');
183
}
184
```
185

186
## Types
187

188
### HOTP Module
189

190
```javascript { .api }
191
/**
192
 * HOTP (counter-based OTP) module
193
 */
194
const hotp = {
195
    gen: function(key, opt),
196
    verify: function(token, key, opt)
197
};
198
```
199

200
### TOTP Module
201

202
```javascript { .api }
203
/**
204
 * TOTP (time-based OTP) module  
205
 */
206
const totp = {
207
    gen: function(key, opt),
208
    verify: function(token, key, opt)
209
};
210
```
211

212
### Options Objects
213

214
```javascript { .api }
215
/**
216
 * HOTP options
217
 */
218
interface HOTPOptions {
219
    counter?: number;  // Counter value (default: 0)
220
    window?: number;   // Verification window (default: 50)
221
}
222

223
/**
224
 * TOTP options
225
 */
226
interface TOTPOptions {
227
    time?: number;     // Time step in seconds (default: 30)
228
    window?: number;   // Verification window (default: 6)
229
    _t?: number;       // Time override (test only)
230
}
231

232
/**
233
 * Verification result
234
 */
235
interface VerificationResult {
236
    delta: number;     // Counter/time step difference
237
}
238
```
239

240
## Google Authenticator Integration
241

242
For Google Authenticator compatibility, secret keys must be base32 encoded. The notp library does not provide base32 encoding - use the separate `thirty-two` package:
243

244
```javascript
245
const notp = require('notp');
246
const base32 = require('thirty-two');
247

248
// Encode secret for Google Authenticator
249
const secret = 'user_secret_key';
250
const encoded = base32.encode(secret);
251
const googleSecret = encoded.toString().replace(/=/g, ''); // Remove padding
252

253
// Generate QR code URI
254
const uri = `otpauth://totp/MyApp:user@example.com?secret=${googleSecret}&issuer=MyApp`;
255

256
// Generate token (same as normal usage)
257
const token = notp.totp.gen(secret);
258
```
259

260
## Error Handling
261

262
The library throws errors in specific cases:
263

264
- **Time Override Error**: Attempting to use `_t` option outside test environment (`NODE_ENV !== 'test'`)
265
- **Invalid Parameters**: Functions return null for invalid tokens rather than throwing exceptions
266

267
```javascript
268
// Error handling example
269
try {
270
    const token = notp.totp.gen(secret, { _t: Date.now() }); // Throws in production
271
} catch (error) {
272
    console.error('Cannot override time in non-test environment');
273
}
274

275
// Verification returns null on failure
276
const result = notp.totp.verify('invalid', secret);
277
if (result === null) {
278
    console.log('Verification failed');
279
}
280
```
281

282
## Security Considerations
283

284
- **Secret Keys**: Keep secret keys secure and unique per user
285
- **Token Lifetime**: TOTP tokens are time-sensitive (default 30 seconds)
286
- **Window Size**: Balance security vs usability when setting verification windows
287
- **Counter Management**: For HOTP, applications must track and increment counters
288
- **Replay Protection**: Implement additional measures to prevent token reuse