otplib API Documentation / @otplib/totp / TOTPVerifyOptions

Type Alias: TOTPVerifyOptions

TOTPVerifyOptions = TOTPGenerateOptions & object

Defined in: totp/src/types.ts:74

Required options for TOTP verification

Requires secret, token, and crypto for verification.

Type Declaration

epochTolerance?

readonly optional epochTolerance: number | [number, number]

Time tolerance in seconds (default: 0 = current period only)

Accepts tokens that were or will be valid within the specified tolerance of the current time. This aligns with RFC 6238's transmission delay concept.

See

RFC 6238 Section 5.2

• Number: symmetric tolerance (same for past and future) epochTolerance: 5 checks [epoch - 5, epoch + 5]

• Tuple [past, future]: asymmetric tolerance epochTolerance: [5, 0] checks [epoch - 5, epoch] (RFC-compliant, past only) epochTolerance: [5, 10] checks [epoch - 5, epoch + 10]

Examples

// RFC-compliant (transmission delay only, past tokens)
epochTolerance: [5, 0]

// High security (banking, critical systems)
epochTolerance: 5  // or [5, 5] symmetric

// Standard (most 2FA implementations)
epochTolerance: 30

// Lenient (poor network, user-friendly)
epochTolerance: 60

With period=30 and epochTolerance=[5, 0] (RFC-compliant):

Period N-1         | Period N (current)  | Period N+1
[token A valid]    | [token B valid]     | [token C valid]
                   |                     |
At epoch in period N:
- If 0-5 sec into period:  A valid, B valid
- If 6-29 sec into period: B valid only
(Future tokens never accepted)

token

readonly token: string

The OTP token to verify