first commit
This commit is contained in:
93
docs/security-stack/security/otp/src/totp/totp.md
Normal file
93
docs/security-stack/security/otp/src/totp/totp.md
Normal file
@@ -0,0 +1,93 @@
|
||||
# `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.
|
||||
Reference in New Issue
Block a user