suaveplan/openspec/changes/complete-react-auth/tasks.md

Tasks — complete-react-auth

Change ID: complete-react-auth Package: @suaveplan/react-auth Target path: packages/auth/react-auth/

Pre-flight: @suaveplan/types, @suaveplan/error, @suaveplan/events, @suaveplan/logger, @suaveplan/i18n, @suaveplan/webauthn, @suaveplan/oauth-client, @suaveplan/srp, @suaveplan/otp, @suaveplan/hibp, @suaveplan/password-strength, @suaveplan/password-generator, @suaveplan/react-ui — all ✅ on Verdaccio.

---

0. Pre-flight (non-negotiable)

• 0.1 Confirm clean working tree (git status reports nothing) and no in-flight worktrees with uncommitted work (git worktree list then git status in each)
• 0.2 If any worktrees exist under .claude/worktrees/, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (git worktree remove) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
• 0.3 Confirm the package set in MANIFEST.md matches find packages -maxdepth 3 -name package.json count. Drift here means a prior change archived without regenerating the manifest.

1. Scaffold

• Create directory tree per design.md § File layout.
• Write package.json at 0.1.0, "sideEffects": false, react ^19.0.0 peer, every internal dep as workspace:^, every external dep via catalog.
• Write tsconfig.json (extends @suaveplan/typescript-config/browser-react.json), vitest.config.ts (forks pool, fileParallelism false, istanbul 100/100/100/100), playwright.config.ts via @suaveplan/testing-e2e factory.
• Write README.md at package root — overview, install, quick-start (provider + sign-in form), Modules section linking every co-located .md.

2. Types + schemas + errors

• src/types/auth-user.ts, auth-state.ts, auth-backend.ts, session.ts, idle-config.ts, permission-resolver.ts — each with sibling .md (≥ 200 words).
• src/schemas/schemas.ts — Zod schemas for every hook option bag (SignInOptions, SignUpOptions, UsePasskeyAutofillOptions, UseOAuthSignInOptions, …). Sibling .md, schemas.test.ts.
• src/errors/errors.ts — defineCodes("REACT_AUTH", [...]) for the 29 codes in design.md § Error code namespace. Export ReactAuthError. Sibling .md, errors.test.ts covering: every code reachable from a production path; translation helpers preserve cause.

3. Utilities

• src/utils/compose-signals.ts (+ .md, .test.ts) — AbortController composition (any abort → composed abort).
• src/utils/is-ssr.ts (+ .md, .test.ts).
• src/utils/announce.ts (+ .md, .test.ts) — ARIA live-region helper (creates a single shared aria-live="polite" node on first call).

4. Session — storage, broadcast, idle, refresh, forced-logout

• src/session/storage/memory/memory.ts (+ .md, .test.ts).
• src/session/storage/local/local.ts (+ .md, .test.ts).
• src/session/storage/session/session.ts (+ .md, .test.ts).
• src/session/broadcast-channel.ts (+ .md, .test.ts) — typed envelope, factory injection, SSR no-op.
• src/session/auto-refresh.ts (+ .md, .test.ts) — schedule via injected Clock; cancels on every state update.
• src/session/idle-timer.ts (+ .md, .test.ts) — pointer/key/visibility listeners; debounced; onWarn/onTimeout.
• src/session/forced-logout.ts (+ .md, .test.ts) — broadcasts + clears storage synchronously.

5. Provider + context

• src/auth-provider/auth-context.ts (+ .md, .test.ts).
• src/auth-provider/use-auth-context.ts (+ .md, .test.ts) — throws REACT_AUTH.CONTEXT_MISSING outside provider.
• src/auth-provider/load-persisted-session.ts (+ .md, .test.ts).
• src/auth-provider/auth-provider.tsx (+ .md, .test.tsx, .stories.tsx) — wires backend + storage + broadcast + idle + auto-refresh; deterministic SSR render; effect-only DOM access.

6. Lifecycle hooks

• src/hooks/use-auth/ (+ .md, .test.ts).
• src/hooks/use-user/ (+ .md, .test.ts).
• src/hooks/use-is-authenticated/ (+ .md, .test.ts).
• src/hooks/use-session/ (+ .md, .test.ts).
• src/hooks/use-sign-in/ (+ .md, .test.ts) — supports password, SRP, passkey result handoff.
• src/hooks/use-sign-up/ (+ .md, .test.ts).
• src/hooks/use-sign-out/ (+ .md, .test.ts) — broadcasts signed-out.
• src/hooks/use-refresh-token/ (+ .md, .test.ts).

7. Password hooks + components

• src/hooks/use-change-password/ (+ .md, .test.ts).
• src/hooks/use-password-reset/ (+ .md, .test.ts) — request + confirm.
• src/components/password-strength-meter/ (+ .md, .test.tsx, .stories.tsx) — wraps password-strength.assessReactive; cancels on unmount.
• src/components/hibp-pwned-indicator/ (+ .md, .test.tsx, .stories.tsx) — debounced ≥ 500 ms; SSR no-op; injected HibpClient.
• src/components/password-input/ (+ .md, .test.tsx, .stories.tsx) — show/hide, label association, aria-describedby, optional strength + HIBP slots.
• src/components/password-generator-button/ (+ .md, .test.tsx, .stories.tsx) — popover via @suaveplan/react-ui <Popover>; passphrase/chars/pin modes.

8. Passkey hooks + components

• src/hooks/use-register-passkey/ (+ .md, .test.ts).
• src/hooks/use-authenticate-with-passkey/ (+ .md, .test.ts) — modal mediation.
• src/hooks/use-passkey-autofill/ (+ .md, .test.tsx) — folded from superseded autofill change; SSR-safe; isConditionalMediationAvailable feature-detect; composed AbortController; stable abort.
• src/components/passkey-autofill-field/ (+ .md, .test.tsx, .stories.tsx) — <input autocomplete="username webauthn"> wrapper; blur cancels when no credential delivered.
• src/components/passkey-list/ (+ .md, .test.tsx, .stories.tsx) — lists from backend.listPasskeys; per-row revoke with accessible confirm dialog.

9. OAuth

• src/oauth/provider-registry.ts (+ .md, .test.ts) — register / get / has / list / unregister; descriptor includes label key + icon slot + scopes.
• src/oauth/popup.ts (+ .md, .test.ts) — centred-window helper; postMessage origin check; popup-blocked detection.
• src/oauth/redirect.ts (+ .md, .test.ts) — sessionStorage return-state persist; window.location.assign.
• src/oauth/handle-callback.ts (+ .md, .test.ts) — parses query, validates state, exchanges code, dispatches result; idempotent on remount.
• src/hooks/use-oauth-sign-in/ (+ .md, .test.ts) — popup + redirect modes; PKCE via @suaveplan/oauth-client.
• src/components/oauth-provider-button/ (+ .md, .test.tsx, .stories.tsx).

10. MFA

• src/hooks/use-enroll-totp/ (+ .md, .test.ts) — begin + finish.
• src/hooks/use-verify-totp/ (+ .md, .test.ts).
• src/hooks/use-enroll-webauthn-second-factor/ (+ .md, .test.ts) — wraps register with authenticatorSelection.authenticatorAttachment.
• src/hooks/use-recovery-codes/ (+ .md, .test.ts) — generate + verify.
• src/components/totp-enrollment-panel/ (+ .md, .test.tsx, .stories.tsx) — orchestrates secret display → caller-provided QR slot → code entry → recovery-codes reveal.
• src/components/recovery-codes-panel/ (+ .md, .test.tsx, .stories.tsx) — copy / download / acknowledge before dismiss.

11. Verification flows

• src/hooks/use-email-verification/ (+ .md, .test.ts).
• src/hooks/use-phone-verification/ (+ .md, .test.ts).
• src/components/email-verification-view/ (+ .md, .test.tsx, .stories.tsx) — resend cooldown timer.
• src/components/phone-verification-view/ (+ .md, .test.tsx, .stories.tsx) — inputMode="numeric", autocomplete="one-time-code".

12. Guards

• src/hooks/use-permission/ (+ .md, .test.ts).
• src/hooks/use-auth-guard/ (+ .md, .test.ts).
• src/components/auth-guard/ (+ .md, .test.tsx, .stories.tsx) — withAuth HOC alongside component.
• src/components/permission-gate/ (+ .md, .test.tsx, .stories.tsx).

13. Error boundary

• src/components/auth-error-boundary/ (+ .md, .test.tsx, .stories.tsx) — catches SuaveplanError whose code starts REACT_AUTH.; renders i18n-keyed fallback; re-throws everything else.

14. i18n

• src/i18n/en-gb/index.ts (+ .md) — canonical catalogue with every react-auth.* key used in the package.
• src/i18n/cy-gb/index.ts (+ .md) — full Welsh translation.
• src/i18n/zh-cn/index.ts (+ .md) — full Simplified Chinese translation.
• src/i18n/parity.test.ts — asserts every locale has the same key set as en-GB; fails CI on drift.
• src/i18n/no-hardcoded-strings.test.ts — scans components/**/*.tsx for hardcoded user-visible strings; allowlist limited to test fixtures.

15. Index + subpath exports

• src/index.ts — explicit named re-exports (rule 6a); namespace re-exports for errors and schemas.
• package.json exports map — one entry per subpath per proposal.md.
• Type-only re-exports separated via export { type X }.

16. Playwright E2E

• e2e/fixtures/app.tsx — minimal test app wiring an in-memory AuthBackend.
• e2e/password-sign-in.spec.ts, sign-up.spec.ts, password-reset.spec.ts, change-password.spec.ts.
• e2e/passkey-register.spec.ts, passkey-autofill.spec.ts, passkey-modal-authenticate.spec.ts (virtual-authenticator via Playwright CDP).
• e2e/oauth-popup.spec.ts, oauth-redirect.spec.ts — stubbed authorization endpoint.
• e2e/totp-enroll-verify.spec.ts, recovery-codes.spec.ts.
• e2e/email-verification.spec.ts, phone-verification.spec.ts.
• e2e/multi-tab-sync.spec.ts — two browser contexts share the same backend; sign-out in tab A propagates to tab B.
• e2e/idle-timeout.spec.ts — idle config fires onTimeout after configured ms; user is forced out.
• e2e/error-boundary.spec.ts — triggers a BACKEND_ERROR; verifies the boundary fallback renders.
• e2e/rtl-locale.spec.ts — renders with an RTL locale (e.g. ar) via the parent app; verifies dir="rtl" propagates.
• e2e/accessibility.spec.ts — @axe-core/playwright sweep across every canonical page; zero serious / critical violations.

17. Spec reconciliation (CLAUDE.md §13 step 0)

• Open specs/react-auth/spec.md. Walk every ### Requirement and #### Scenario. For each **Verified by:** path, confirm the test file exists and the test name matches verbatim.
• Confirm every error code in defineCodes("REACT_AUTH", …) is reached from a real production path (not just a registry entry).

18. Pre-publish gates

• bunx turbo lint typecheck test --filter=@suaveplan/react-auth — green.
• bunx turbo test:coverage --filter=@suaveplan/react-auth — 100/100/100/100.
• bunx turbo build --filter=@suaveplan/react-auth — green.
• Banned-pattern scan zero (@deprecated|TODO|FIXME|ts-ignore|ts-expect-error|\.skip|\.only|console\.log).
• Barrel-shape scan zero (export * only in src/index.ts namespace forms).
• Test-runner import scan zero (from "vitest" / from "bun:test" outside the exempt allowlist).
• Missing-.md scan zero.
• Bare-version scan zero.
• Subpath export count matches feature-module count.
• React version check: find . -path "*/node_modules/react/package.json" returns a single version.

19. Root-doc refresh

• bun scripts/folder-reorg/generate-manifest.ts (refresh MANIFEST.md).
• bun scripts/generate-missing.ts (refresh MISSING.yml).
• Edit STATUS.md — move @suaveplan/react-auth from – to ✅; add summary paragraph.
• Edit SUMMARY.md — add per-package paragraph (features, deps, decisions).
• bunx markdownlint-cli2 --fix — touched files.

20. Supersede existing change folders

• mv openspec/changes/enterprise-react-auth openspec/changes/_superseded-narrow-deferrals-2026-05-17/enterprise-react-auth — fold under the existing supersede bucket.

21. Fold spec delta + archive

• Fold specs/react-auth/spec.md into openspec/specs/react-auth/spec.md (canonical home).
• mv openspec/changes/complete-react-auth openspec/archive/<yyyy-mm-dd>-complete-react-auth/.
• bun scripts/publish.ts --package @suaveplan/react-auth.