suaveplan/openspec/archive/2026-05-10-enterprise-otp/tasks.md

# Tasks — `@suaveplan/otp` (RFC 4226 / 6238 / 6287 + Key URI + recovery codes)

> Every checkbox MUST reflect work actually done in this change. Do not retroactively tick boxes for work that was already in main when this change opened. Do not tick a box for a test that doesn't exist or doesn't pin the requirement it claims to verify.

## 1. Spec authoring

- [ ] 1.1 Read `../suaveplan/enterprise/otp.md` end-to-end
- [ ] 1.2 Read `openspec/AGENTS.md` Sections 13, 14, 14a
- [ ] 1.3 Read RFC 4226 (HOTP), RFC 6238 (TOTP), RFC 6287 (OCRA), Google Authenticator Key URI Format wiki page
- [ ] 1.4 Draft `proposal.md` from `openspec/templates/proposal.md`
- [ ] 1.5 Fill in `## Source mapping` table — every requirement cites an RFC clause OR appears in the "no source line" table with justification
- [ ] 1.6 Draft `specs/otp/spec.md` from `openspec/templates/spec-delta.md`
- [ ] 1.7 Every requirement in the spec delta carries a `**Verified by:**` line naming concrete `it(...)` titles

## 2. Package scaffold

- [ ] 2.1 `packages/vault/otp/` directory structure (`src/{hotp,totp,uri,base32,ocra,recovery,drift,errors,observability}/`)
- [ ] 2.2 `package.json` — `@suaveplan/otp@0.0.0`, `type: "module"`, `sideEffects: false`, deps via `workspace:^` / `catalog:`
- [ ] 2.3 `tsconfig.json` extends `@suaveplan/typescript-config/library.json`
- [ ] 2.4 `vite.config.ts` for build, `vitest.config.ts` from `@suaveplan/testing/config`
- [ ] 2.5 `README.md` with package description, install snippet, quick-start, `## Modules` table linking every co-located `.md`
- [ ] 2.6 Subpath exports map covers `.`, `./uri`, `./base32`, `./ocra`, `./errors`, `./observability`

## 3. Implementation — HOTP (RFC 4226)

- [ ] 3.1 `src/hotp/hotp.ts` — `hotp(secret, counter, opts?)` with dynamic truncation per §5.3 step 2
- [ ] 3.2 `src/hotp/hotp.types.ts` — `HotpOptions`, `HotpAlgorithm`, `HotpDigits`
- [ ] 3.3 `src/hotp/hotp.schema.ts` — `HotpOptionsSchema` Zod boundary
- [ ] 3.4 8-byte big-endian counter encoding helper in `src/hotp/encode-counter.ts`
- [ ] 3.5 `src/hotp/index.ts` — explicit named re-exports

## 4. Implementation — TOTP (RFC 6238)

- [ ] 4.1 `src/totp/totp.ts` — `totp(secret, opts?)` over `T = floor((now − T0) / period)` with injectable `Clock`
- [ ] 4.2 `src/totp/verify.ts` — `verify(code, secret, opts?)` with `±window` drift; constant-time loop
- [ ] 4.3 `src/totp/verify-many.ts` — `verifyMany(code, secrets[], opts?)` constant-time across the secret list
- [ ] 4.4 `src/totp/totp.types.ts` — `TotpOptions`, `TotpVerifyOptions`, `TotpVerifyResult`, `TotpVerifyManyResult`
- [ ] 4.5 `src/totp/totp.schema.ts` — `TotpOptionsSchema`, `TotpVerifyOptionsSchema` (`window` ∈ [0,10])
- [ ] 4.6 `src/totp/index.ts` — explicit named re-exports

## 5. Implementation — Key URI Format

- [ ] 5.1 `src/uri/parse-uri.ts` — `parseUri(uri)` for `otpauth://totp/...` and `hotp` variant
- [ ] 5.2 `src/uri/format-uri.ts` — `formatUri(opts)` round-trip with percent-encoding of label and issuer
- [ ] 5.3 `src/uri/uri.types.ts` — `OtpUri` discriminated union (`type: "totp" | "hotp"`)
- [ ] 5.4 `src/uri/uri.schema.ts` — `OtpUriSchema` Zod boundary
- [ ] 5.5 `src/uri/index.ts` — explicit named re-exports

## 6. Implementation — Base32 (RFC 4648 §6)

- [ ] 6.1 `src/base32/base32.ts` — `base32Encode(bytes, opts?)` and `base32Decode(input)`; `padding=false` default to match Google Authenticator
- [ ] 6.2 `src/base32/index.ts` — explicit named re-exports

## 7. Implementation — OCRA (RFC 6287)

- [ ] 7.1 `src/ocra/ocra.ts` — `ocra(suite, key, params)` per §6 computation
- [ ] 7.2 `src/ocra/suite.ts` — `parseOcraSuite(suite)` per §6.1 grammar
- [ ] 7.3 `src/ocra/verify-ocra.ts` — `verifyOcra(...)` constant-time
- [ ] 7.4 `src/ocra/mutual-auth.ts` — `OcraMutualAuthClient`, `OcraMutualAuthServer` per §7.1
- [ ] 7.5 `src/ocra/ocra.types.ts` — `OcraSuite`, `OcraParams`, `OcraCryptoFunction`, `OcraDataInput`
- [ ] 7.6 `src/ocra/ocra.schema.ts` — `OcraParamsSchema` Zod boundary
- [ ] 7.7 `src/ocra/index.ts` — explicit named re-exports

## 8. Implementation — Recovery codes

- [ ] 8.1 `src/recovery/generate.ts` — `generateRecoveryCodes(count, opts?)` Crockford-base32 grouping, injectable `Rng`
- [ ] 8.2 `src/recovery/hash.ts` — `hashRecoveryCode(code, opts?)` Argon2id via `@suaveplan/crypto-hash`
- [ ] 8.3 `src/recovery/verify.ts` — `verifyRecoveryCode(input, hashedCodes[])` constant-time over the full list
- [ ] 8.4 `src/recovery/recovery.types.ts` — `RecoveryCodeOptions`, `RecoveryVerifyResult`
- [ ] 8.5 `src/recovery/index.ts` — explicit named re-exports

## 9. Implementation — Clock-drift detector

- [ ] 9.1 `src/drift/detect.ts` — `detectDrift(code, secret, opts?)` searches `±maxSteps` outside the verify window
- [ ] 9.2 `src/drift/drift.types.ts` — `DriftDetectOptions`, `DriftResult`
- [ ] 9.3 `src/drift/index.ts` — explicit named re-exports

## 10. Implementation — Errors and observability

- [ ] 10.1 `src/errors/codes.ts` — `OTP_CODES` registry via `defineCodes("OTP", [...])`; `OtpError extends SuaveplanError<OtpErrorCode>`
- [ ] 10.2 `src/errors/index.ts` — explicit named re-exports
- [ ] 10.3 `src/observability/metrics.ts` — histograms and counters wired against `@opentelemetry/api`
- [ ] 10.4 `src/observability/index.ts` — explicit named re-exports

## 11. Root barrel + subpath exports

- [ ] 11.1 `src/index.ts` — explicit named re-exports of HOTP, TOTP, verify, verifyMany, recovery, drift, errors, observability surfaces (no `export *`)
- [ ] 11.2 Verify exports map count matches feature module count (§13 step 8)

## 12. Documentation

- [ ] 12.1 Sibling `.md` for every implementation `.ts` (≥200 words; basic + advanced examples; full API reference; implementation notes)
- [ ] 12.2 README links every co-located `.md` under `## Modules`

## 13. Tests (runner-neutral imports — `@suaveplan/testing/runner` only)

- [ ] 13.1 `src/hotp/hotp.test.ts` — RFC 4226 Appendix D 10 vectors, SHA-256/512 widening, `bigint` past 2^53, digits 6/7/8
- [ ] 13.2 `src/totp/totp.test.ts` — RFC 6238 Appendix B 6 vectors across SHA-1/256/512 at digits=8
- [ ] 13.3 `src/totp/verify.test.ts` — window 0 / 1 / 10 / >10; `delta` semantics
- [ ] 13.4 `src/totp/verify-many.test.ts` — multi-secret happy path + miss path
- [ ] 13.5 `src/totp/constant-time.test.ts` — every windowed step and every secret evaluated regardless of early match
- [ ] 13.6 `src/uri/parse-uri.test.ts` — every documented parameter; `hotp` variant; malformed paths
- [ ] 13.7 `src/uri/format-uri.test.ts` — label / issuer percent-encoding; `:` in label rejected
- [ ] 13.8 `src/uri/round-trip.property.test.ts` — fast-check property test
- [ ] 13.9 `src/base32/base32.test.ts` — RFC 4648 §6 vectors; padded + unpadded; case-insensitivity; invalid alphabet
- [ ] 13.10 `src/ocra/ocra.test.ts` — RFC 6287 Appendix C.1–C.3 vectors
- [ ] 13.11 `src/ocra/suite.test.ts` — every §6.1 grammar branch
- [ ] 13.12 `src/ocra/mutual-auth.test.ts` — three-message §7.1 round-trip
- [ ] 13.13 `src/recovery/generate.test.ts` — Crockford-base32 grouping; deterministic with injected `Rng`
- [ ] 13.14 `src/recovery/verify.test.ts` — Argon2id round-trip; constant-time over the full set
- [ ] 13.15 `src/drift/detect.test.ts` — drift outside the verify window
- [ ] 13.16 `src/errors/codes.spec-conformance.test.ts` — every `OTP_CODES` entry thrown by at least one production path
- [ ] 13.17 `src/observability/metrics.spec-conformance.test.ts` — every histogram and counter emitted; assertions against an in-memory `MeterProvider`
- [ ] 13.18 `src/index.test.ts` — every documented subpath resolves
- [ ] 13.19 Every `it(...)` carries `{ timeout: 5000 }` (or 30000 for genuinely async)
- [ ] 13.20 Runner-neutral imports — CLAUDE.md §11 grep clean

## 14. Pre-archive verification (the 5-gate triple)

- [ ] 14.1 `bun run check` — Biome 0 errors / 0 warnings / 0 info across the whole monorepo
- [ ] 14.2 `bunx turbo lint typecheck test --filter=@suaveplan/otp` — green
- [ ] 14.3 `bunx turbo test:coverage --filter=@suaveplan/otp` — 100/100/100/100
- [ ] 14.4 `bun scripts/openspec-conformance.ts @suaveplan/otp` — exit 0, no `error` findings
- [ ] 14.5 `bunx turbo build --filter=@suaveplan/otp` — green

## 15. Pre-archive 7-row checklist (AGENTS.md Section 13)

- [ ] 15.1 Generics threaded; `expectTypeOf` assertions on every literal-type claim (`HotpAlgorithm`, `HotpDigits`, `OtpUri.type`)
- [ ] 15.2 Zod schemas wired at every declared boundary (`HotpOptionsSchema`, `TotpOptionsSchema`, `TotpVerifyOptionsSchema`, `OtpUriSchema`, `OcraParamsSchema`)
- [ ] 15.3 Every error code in `OTP_CODES` thrown by at least one production path
- [ ] 15.4 Strict-mode behaviors tested both on and off (window cap, base32 padding, label `:` rejection)
- [ ] 15.5 OTel histograms and counters emitted from production paths and asserted with a real in-memory `MeterProvider`
- [ ] 15.6 Lifecycle dedup — N/A (pure functions; no shared mutable state)
- [ ] 15.7 No retroactive tick — every box above reflects work done in this change

## 16. Benchmarks (mitata, `src/__benchmarks__/`)

- [ ] 16.1 `totp_generate.bench.ts`
- [ ] 16.2 `totp_verify_window_1.bench.ts`
- [ ] 16.3 `totp_verify_window_10.bench.ts`
- [ ] 16.4 `parse_uri.bench.ts`
- [ ] 16.5 `format_uri.bench.ts`
- [ ] 16.6 Baseline numbers published in README

## 17. Root-doc refresh + markdownlint (AGENTS.md §13b)

- [ ] 17.1 `bun scripts/folder-reorg/generate-manifest.ts` — refresh `MANIFEST.md`
- [ ] 17.2 `bun scripts/generate-missing.ts` — refresh `MISSING.yml`
- [ ] 17.3 `STATUS.md` — move `@suaveplan/otp` from `Pending` to `Completed`
- [ ] 17.4 `SUMMARY.md` — add per-package paragraph
- [ ] 17.5 `CLAUDE.md` — add package listing under "Vaulted" / vault-orchestration section
- [ ] 17.6 `bunx markdownlint-cli2 --fix` — auto-fix; re-stage
- [ ] 17.7 `bunx markdownlint-cli2` — second pass exit 0

## 18. Archive

- [ ] 18.1 Fold spec delta into `openspec/specs/otp/spec.md` (canonical, status ACTIVE)
- [ ] 18.2 Move `openspec/changes/enterprise-otp/` → `openspec/archive/<yyyy-mm-dd>-enterprise-otp/`