otplib API Documentation / @otplib/totp / VerifyResultValid

Type Alias: VerifyResultValid

VerifyResultValid = object

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

Successful verification result with delta offset

Properties

delta

readonly delta: number

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

The offset from the current time step where the token matched.

• 0: Token matched at current time step (no drift)
• Negative: Token matched in a past time step (client clock behind)
• Positive: Token matched in a future time step (client clock ahead)

---

epoch

readonly epoch: number

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

The exact epoch timestamp (in seconds) of the period start where the token matched.

This provides the precise Unix timestamp for the beginning of the time period in which the token was valid. Useful for logging, debugging, and advanced time drift analysis.

Example

const result = await verify({ secret, token, epochTolerance: 30 });
if (result.valid) {
  console.log(`Token matched at epoch: ${result.epoch}`);
  console.log(`Token was ${result.delta} periods away`);
}

---

timeStep

readonly timeStep: number

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

The time step number (per RFC 6238) used for verification.

Per RFC 6238, time step T = floor((CurrentUnixTime - T0) / X), where X is the period. This is the actual time step counter value, not a Unix timestamp.

This value is always included in successful verifications and can be used for replay attack prevention by passing it as afterTimeStep in subsequent verifications.

Example

const result = await verify({ secret, token, crypto });
if (result.valid) {
  // Save timeStep to prevent reuse
  await db.saveLastTimeStep(userId, result.timeStep);
}

// Later: verify with replay protection
const lastTimeStep = await db.getLastTimeStep(userId);
const result2 = await verify({
  secret,
  token: newToken,
  crypto,
  afterTimeStep: lastTimeStep, // Rejects timeStep <= lastTimeStep
});

---

valid

readonly valid: true

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

Token is valid