0
# Configuration and Options
1

2
OTPLib provides extensive configuration options for customizing token generation, validation, and cryptographic operations. All classes support both instance-level and global configuration.
3

4
## Capabilities
5

6
### Option Management
7

8
All OTP classes provide consistent option management interfaces.
9

10
```typescript { .api }
11
/**
12
 * Get or set instance options
13
 */
14
options: Partial<OptionsType>;
15

16
/**
17
 * Reset options to library defaults
18
 */
19
resetOptions(): void;
20

21
/**
22
 * Get complete options with defaults applied
23
 * @returns Readonly options object with all defaults filled
24
 */
25
allOptions(): Readonly<OptionsType>;
26
```
27

28
**Usage Example:**
29

30
```typescript
31
import { authenticator, totp, hotp } from "otplib";
32

33
// View current options
34
console.log(authenticator.options);
35

36
// Set specific options
37
authenticator.options = { digits: 8 };
38
totp.options = { step: 60, window: 2 };
39
hotp.options = { algorithm: 'sha256' };
40

41
// Get complete configuration
42
const fullConfig = authenticator.allOptions();
43
console.log(fullConfig); // All options with defaults
44

45
// Reset to defaults
46
authenticator.resetOptions();
47
```
48

49
### HOTP Options
50

51
Base options available for HMAC-based one-time passwords.
52

53
```typescript { .api }
54
interface HOTPOptions {
55
  /** HMAC algorithm: 'sha1', 'sha256', or 'sha512' */
56
  algorithm: 'sha1' | 'sha256' | 'sha512';
57
  /** Number of digits in generated tokens (typically 6 or 8) */
58
  digits: number;
59
  /** Encoding of the secret key */
60
  encoding: 'ascii' | 'base64' | 'hex' | 'latin1' | 'utf8';
61
  /** Function to create HMAC digest */
62
  createDigest: CreateDigest;
63
  /** Function to format secret into HMAC key */
64
  createHmacKey: CreateHmacKey;
65
  /** Pre-computed digest for advanced use cases */
66
  digest?: string;
67
}
68

69
// Default HOTP options
70
const defaultHOTPOptions = {
71
  algorithm: 'sha1',
72
  digits: 6,
73
  encoding: 'ascii'
74
};
75
```
76

77
**Usage Examples:**
78

79
```typescript
80
import { hotp } from "otplib";
81

82
// Standard configuration
83
hotp.options = {
84
  algorithm: 'sha1',
85
  digits: 6,
86
  encoding: 'ascii'
87
};
88

89
// High security configuration
90
hotp.options = {
91
  algorithm: 'sha256',
92
  digits: 8,
93
  encoding: 'hex'
94
};
95

96
// Custom digest (advanced)
97
hotp.options = {
98
  digest: 'precomputed-hex-digest'
99
};
100
```
101

102
### TOTP Options
103

104
Time-based options extending HOTP functionality.
105

106
```typescript { .api }
107
interface TOTPOptions extends HOTPOptions {
108
  /** Starting time in milliseconds since JavaScript epoch */
109
  epoch: number;
110
  /** Time step in seconds */
111
  step: number;
112
  /** Time window tolerance: number or [past, future] */
113
  window: number | [number, number];
114
}
115

116
// Default TOTP options
117
const defaultTOTPOptions = {
118
  ...defaultHOTPOptions,
119
  epoch: Date.now(),
120
  step: 30,
121
  window: 0
122
};
123
```
124

125
**Usage Examples:**
126

127
```typescript
128
import { totp } from "otplib";
129

130
// Standard Google Authenticator compatible
131
totp.options = {
132
  algorithm: 'sha1',
133
  digits: 6,
134
  step: 30,
135
  window: 1,
136
  encoding: 'ascii'
137
};
138

139
// Custom time configuration
140
totp.options = {
141
  step: 60,        // 1-minute tokens
142
  window: [2, 1],  // 2 past, 1 future window
143
  epoch: Date.now() // Current time base
144
};
145

146
// High frequency tokens
147
totp.options = {
148
  step: 15,        // 15-second tokens
149
  window: 0        // No tolerance
150
};
151
```
152

153
### Authenticator Options
154

155
Google Authenticator compatible options with Base32 encoding.
156

157
```typescript { .api }
158
interface AuthenticatorOptions extends TOTPOptions {
159
  /** Function to encode secrets to Base32 */
160
  keyEncoder: KeyEncoder;
161
  /** Function to decode Base32 secrets */
162
  keyDecoder: KeyDecoder;
163
  /** Function to generate random bytes */
164
  createRandomBytes: CreateRandomBytes;
165
}
166

167
// Default Authenticator options
168
const defaultAuthenticatorOptions = {
169
  ...defaultTOTPOptions,
170
  encoding: 'hex' // Different from TOTP default
171
};
172
```
173

174
**Usage Example:**
175

176
```typescript
177
import { authenticator } from "otplib";
178

179
// Standard Google Authenticator
180
authenticator.options = {
181
  algorithm: 'sha1',
182
  digits: 6,
183
  step: 30,
184
  window: 1,
185
  encoding: 'hex'
186
};
187

188
// Custom authenticator setup
189
authenticator.options = {
190
  digits: 8,       // 8-digit tokens
191
  step: 60,        // 1-minute validity
192
  algorithm: 'sha256'
193
};
194
```
195

196
### Time Window Configuration
197

198
Configure time tolerance for network delays and clock skew.
199

200
```typescript { .api }
201
// Window configuration options
202
type WindowOption = number | [number, number];
203

204
// Symmetric window (same past and future tolerance)
205
const symmetricWindow: WindowOption = 1; // ±1 time step
206

207
// Asymmetric window (different past and future tolerance)
208
const asymmetricWindow: WindowOption = [2, 1]; // 2 past, 1 future
209

210
// No tolerance
211
const noWindow: WindowOption = 0;
212
```
213

214
**Usage Examples:**
215

216
```typescript
217
import { totp, authenticator } from "otplib";
218

219
// Allow 1 time step in either direction (±30 seconds by default)
220
totp.options = { window: 1 };
221

222
// Allow more past tolerance than future (common for login systems)
223
totp.options = { window: [3, 1] }; // 90 seconds past, 30 seconds future
224

225
// Strict validation (no time tolerance)
226
authenticator.options = { window: 0 };
227

228
// High tolerance for unreliable networks
229
totp.options = { window: [5, 2] }; // 150 seconds past, 60 seconds future
230
```
231

232
### Algorithm Configuration
233

234
Choose HMAC algorithms based on security requirements.
235

236
```typescript { .api }
237
type HashAlgorithm = 'sha1' | 'sha256' | 'sha512';
238

239
// Algorithm characteristics:
240
// - sha1: Fastest, most compatible, adequate security
241
// - sha256: Balanced security and performance
242
// - sha512: Highest security, slower
243
```
244

245
**Usage Examples:**
246

247
```typescript
248
import { hotp, totp, authenticator } from "otplib";
249

250
// Standard compatibility (Google Authenticator)
251
authenticator.options = { algorithm: 'sha1' };
252

253
// Enhanced security
254
totp.options = { algorithm: 'sha256' };
255

256
// Maximum security
257
hotp.options = { algorithm: 'sha512' };
258
```
259

260
### Encoding Configuration
261

262
Configure how secrets are interpreted and stored.
263

264
```typescript { .api }
265
type KeyEncoding = 'ascii' | 'base64' | 'hex' | 'latin1' | 'utf8';
266

267
// Encoding use cases:
268
// - ascii: Plain text secrets
269
// - hex: Hexadecimal encoded secrets
270
// - base64: Base64 encoded secrets
271
// - utf8: Unicode text secrets
272
// - latin1: Binary data as Latin-1
273
```
274

275
**Usage Examples:**
276

277
```typescript
278
import { totp } from "otplib";
279

280
// Plain text secrets
281
totp.options = { encoding: 'ascii' };
282
const token1 = totp.generate("my-secret-key");
283

284
// Hex-encoded secrets
285
totp.options = { encoding: 'hex' };
286
const token2 = totp.generate("6d792d7365637265742d6b6579");
287

288
// Base64-encoded secrets
289
totp.options = { encoding: 'base64' };
290
const token3 = totp.generate("bXktc2VjcmV0LWtleQ==");
291
```
292

293
### Instance Creation with Custom Defaults
294

295
Create new instances with pre-configured defaults.
296

297
```typescript { .api }
298
/**
299
 * Create new instance with custom default options
300
 * @param defaultOptions - Options to use as defaults
301
 * @returns New instance with custom defaults
302
 */
303
create(defaultOptions?: Partial<OptionsType>): InstanceType;
304
```
305

306
**Usage Example:**
307

308
```typescript
309
import { totp, hotp, authenticator } from "otplib";
310

311
// Create high-security TOTP instance
312
const secureTOTP = totp.create({
313
  algorithm: 'sha256',
314
  digits: 8,
315
  step: 15,
316
  window: 0
317
});
318

319
// Create legacy HOTP instance
320
const legacyHOTP = hotp.create({
321
  algorithm: 'sha1',
322
  digits: 6,
323
  encoding: 'ascii'
324
});
325

326
// Create custom authenticator
327
const customAuth = authenticator.create({
328
  digits: 8,
329
  step: 60
330
});
331

332
// Original instances unchanged
333
console.log(totp.allOptions().digits); // Still 6
334
console.log(secureTOTP.allOptions().digits); // 8
335
```
336

337
## Configuration Presets
338

339
### Google Authenticator Compatible
340

341
```typescript
342
import { authenticator } from "otplib";
343

344
authenticator.options = {
345
  algorithm: 'sha1',
346
  digits: 6,
347
  step: 30,
348
  window: 1,
349
  encoding: 'hex'
350
};
351
```
352

353
### High Security Configuration
354

355
```typescript
356
import { totp } from "otplib";
357

358
totp.options = {
359
  algorithm: 'sha256',
360
  digits: 8,
361
  step: 15,      // Shorter validity
362
  window: 0,     // No time tolerance
363
  encoding: 'hex'
364
};
365
```
366

367
### Network Tolerant Configuration
368

369
```typescript
370
import { authenticator } from "otplib";
371

372
authenticator.options = {
373
  window: [5, 2],  // Large time tolerance
374
  step: 30
375
};
376
```
377

378
### Corporate Security Configuration
379

380
```typescript
381
import { totp } from "otplib";
382

383
totp.options = {
384
  algorithm: 'sha512',
385
  digits: 8,
386
  step: 60,       // 1-minute tokens
387
  window: [1, 0], // Only allow past tokens
388
  encoding: 'base64'
389
};
390
```
391

392
## Types
393

394
```typescript { .api }
395
interface CreateDigest {
396
  (algorithm: string, key: string, data: string): string;
397
}
398

399
interface CreateHmacKey {
400
  (algorithm: string, secret: string, encoding: string): string;
401
}
402

403
interface CreateRandomBytes {
404
  (size: number, encoding: string): string;
405
}
406

407
interface KeyEncoder {
408
  (secret: string, encoding: string): string;
409
}
410

411
interface KeyDecoder {
412
  (secret: string, encoding: string): string;
413
}
414

415
enum HashAlgorithms {
416
  SHA1 = 'sha1',
417
  SHA256 = 'sha256',
418
  SHA512 = 'sha512'
419
}
420

421
enum KeyEncodings {
422
  ASCII = 'ascii',
423
  BASE64 = 'base64',
424
  HEX = 'hex',
425
  LATIN1 = 'latin1',
426
  UTF8 = 'utf8'
427
}
428
```