# `totp/totp`

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs --> - totp.schema — Zod boundary schemas for `TotpOptions…
- [totp.schema](./totp.schema.md) — Zod boundary schemas for `TotpOptions` and `TotpVerifyOptions`. The TOTP schema covers algorithm / digits / period / t0…
- [verify-many](./verify-many.md) — Backup-aware TOTP verify. Used during rotation windows where an old and a new TOTP secret coexist — the user's authenti…
- [verify](./verify.md) — 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](./totp.schema.md) — Zod boundary schemas for `TotpOptions` and `TotpVerifyOptions`. The TOTP schema covers algorithm / digits / period / t0…
- [verify-many](./verify-many.md) — Backup-aware TOTP verify. Used during rotation windows where an old and a new TOTP secret coexist — the user's authenti…
- [verify](./verify.md) — 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](./totp.schema.md) — Zod boundary schemas for `TotpOptions` and `TotpVerifyOptions`. The TOTP schema covers algorithm / digits / period / t0…
- [verify-many](./verify-many.md) — Backup-aware TOTP verify. Used during rotation windows where an old and a new TOTP secret coexist — the user's authenti…
- [verify](./verify.md) — 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](./totp.schema.md) — Zod boundary schemas for `TotpOptions` and `TotpVerifyOptions`. The TOTP schema covers algorithm / digits / period / t0…
- [verify-many](./verify-many.md) — Backup-aware TOTP verify. Used during rotation windows where an old and a new TOTP secret coexist — the user's authenti…
- [verify](./verify.md) — RFC 6238 §5.2 verify with drift window. Checks the supplied code against the current step and `±window` neighbouring st…
- [totp.schema](./totp.schema.md) — Zod boundary schemas for `TotpOptions` and `TotpVerifyOptions`. The TOTP schema covers algorithm / digits / period / t0…
- [verify-many](./verify-many.md) — Backup-aware TOTP verify. Used during rotation windows where an old and a new TOTP secret coexist — the user's authenti…
- [verify](./verify.md) — 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

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

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

## Usage: Advanced Example

```ts
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.