`totp/totp`

(no submodules)

- totp.schema — Zod boundary schemas for `TotpOptions…

totp.schema — Zod boundary schemas for TotpOptions and TotpVerifyOptions. The TOTP schema covers algorithm / digits / period / t0…
verify-many — Backup-aware TOTP verify. Used during rotation windows where an old and a new TOTP secret coexist — the user's authenti…
verify — RFC 6238 §5.2 verify with drift window. Checks the supplied code against the current step and ±window neighbouring st…
totp.schema — Zod boundary schemas for `TotpOptions…
totp.schema — Zod boundary schemas for TotpOptions and TotpVerifyOptions. The TOTP schema covers algorithm / digits / period / t0…
verify-many — Backup-aware TOTP verify. Used during rotation windows where an old and a new TOTP secret coexist — the user's authenti…
verify — RFC 6238 §5.2 verify with drift window. Checks the supplied code against the current step and ±window neighbouring st…
totp.schema — Zod boundary schemas for `TotpOptions…
totp.schema — Zod boundary schemas for TotpOptions and TotpVerifyOptions. The TOTP schema covers algorithm / digits / period / t0…
verify-many — Backup-aware TOTP verify. Used during rotation windows where an old and a new TOTP secret coexist — the user's authenti…
verify — RFC 6238 §5.2 verify with drift window. Checks the supplied code against the current step and ±window neighbouring st…
totp.schema — Zod boundary schemas for `TotpOptions…
totp.schema — Zod boundary schemas for TotpOptions and TotpVerifyOptions. The TOTP schema covers algorithm / digits / period / t0…
verify-many — Backup-aware TOTP verify. Used during rotation windows where an old and a new TOTP secret coexist — the user's authenti…
verify — RFC 6238 §5.2 verify with drift window. Checks the supplied code against the current step and ±window neighbouring st…
totp.schema — Zod boundary schemas for TotpOptions and TotpVerifyOptions. The TOTP schema covers algorithm / digits / period / t0…
verify-many — Backup-aware TOTP verify. Used during rotation windows where an old and a new TOTP secret coexist — the user's authenti…
verify — RFC 6238 §5.2 verify with drift window. Checks the supplied code against the current step and ±window neighbouring st…

Purpose

RFC 6238 TOTP — time-based one-time password. Computes T = floor((now − T0) / period) per §4 and delegates to HOTP. Time is read via the injected Clock exclusively — the package never reads Date.now() at module scope, so deterministic tests and replay-style test fixtures can swap in a frozen clock without monkey-patching globals.

Features

Defaults: SHA-1, digits=6, period=30, T0=0.
Algorithm widening per RFC 6238 §1.2 (SHA-256 / SHA-512).
Injectable Clock (@suaveplan/types).
Strict-mode Zod boundary; mismatched fields are mapped to specific codes.
Period validated > 0 (Zod .positive()); failure surfaces as OTP.INVALID_PERIOD.

Usage: Basic Example

import { totp } from "@suaveplan/otp";

const code = totp(secret); // current step from system clock, 6 digits, SHA-1.

Usage: Advanced Example

import { totp } from "@suaveplan/otp";

const fixed: () => number = () => 1_111_111_109_000;
const code = totp(secret, {
  algorithm: "SHA256",
  digits: 8,
  period: 30,
  clock: fixed,
});
// Reproduces RFC 6238 Appendix B vector at T=1111111109.

API Reference

totp(secret: Uint8Array, opts?: TotpOptions): string — primary API.
computeTimeStep(clock, period, t0): bigint — exposed so verify and the drift detector share the same time-step formula.
resolveTotpOptions(opts?): TotpDefaults — fills defaults; useful when forwarding options through wrapper packages.

Implementation Notes

resolveTotpOptions extracts only the known TotpOptions subset before calling Zod so callers can forward extended option bags (e.g. verify with window, drift with maxSteps) without strict-mode rejection. The top-level totp() parses with the strict schema so unknown keys surface as INVALID_OPTIONS at the public boundary.

Time is converted to seconds before integer division (floor(now/1000)) so a clock that returns sub-millisecond resolution still produces a stable step within each period-second window. The BigInt step value is threaded through to HOTP without truncation so step values past Number.MAX_SAFE_INTEGER (which would happen far in the future, around year 285,427,621 at period=30) round-trip cleanly. Callers who need fixed-clock determinism in tests should pass a clock that returns whole milliseconds.

4.9 KiB Raw Blame History Unescape Escape

totp/totp