chore: condense all docs and markdown files
This commit is contained in:
@@ -1,34 +1,48 @@
|
||||
# Phone-first Auth Hardening
|
||||
|
||||
This ExecPlan is a living document. It stays synchronized with `docs/PLANS.md` (see the "Queued Next Review Focus" section there) and tracks everything needed to bring the authentication API to a consolidated, phone-first contract with a pre-verified lifecycle and consistent display paths. The remaining work must be test-driven: one sub-flow defines specs/tests, another implements against those specs, and every commit must pass the relevant backend suite.
|
||||
This ExecPlan follows `docs/PLANS.md`.
|
||||
|
||||
## Purpose / Big Picture
|
||||
|
||||
Users must be able to log in via phone OTP without a password, the backend must keep phone numbers as the canonical identifier, and every surface that mentions a person should fall back to the phone number when email is absent. The new contract documents the public login/auth endpoints and ensures that the pre-verification lifecycle is deterministic, rate limits stay sensible, and audits display clear phone-first names. The deliverables include updated documentation, new guards/tests against regressions, and polished serializers/models that no longer assume `user.email` exists.
|
||||
|
||||
## Milestones
|
||||
|
||||
1. Spec & Test Subagent: Formalize and implement the missing specs around pre-verification, OTP purpose safety, rate-limit exposure, and display fallbacks. This milestone produces new pytest modules covering the pre-verification promise, the OTP contract (auth vs verify), and the fallback names used across staff, availability, and reviews. Success is measured by the new tests failing before implementation changes and passing afterward.
|
||||
2. Implementation Subagent: Update serializers, models, and docs to satisfy the specs. This includes reinforcing the user lifecycle (pre-verify), documenting the intended login surface (phone OTP as source-of-truth, register/token deprecated), tuning rate-limit metadata in responses, and ensuring every display path prefers phone numbers. Implementation is validated by rerunning the pytest suite (`python3 -m pytest backend/apps/accounts/tests backend/apps/salons/tests`).
|
||||
Keep phone OTP as canonical login surface, preserve phone-first identity across serializers/admin/UI-facing strings, and lock regression tests around this contract.
|
||||
|
||||
## Progress
|
||||
|
||||
- [x] (2026-03-14 12:00 UTC) Capture the auth gaps in a dedicated ExecPlan and outline the test-first flow for the missing invariants.
|
||||
- [x] (2026-03-14 13:55 UTC) Added specs/tests for display-name fallbacks, phone auth 404 handling, and serializer coverage so the new contract fails before implementation.
|
||||
- [x] (2026-03-14 14:30 UTC) Implemented `User.display_name`, updated serializers/models/admin, documented the canonical phone OTP surfaces, and confirmed the specs pass via `python3 -m pytest backend/apps/accounts/tests backend/apps/salons/tests`.
|
||||
- [x] (2026-03-14 12:00 UTC) Plan created with test-first scope.
|
||||
- [x] (2026-03-14 13:55 UTC) Added tests for display fallback + phone auth error contracts.
|
||||
- [x] (2026-03-14 14:30 UTC) Implemented `User.display_name`, serializer/admin updates, and docs updates.
|
||||
- [ ] Expand tests for OAuth linking policy and remaining phone-first invariants.
|
||||
|
||||
## Surprises & Discoveries
|
||||
|
||||
- Pytest reports `jwt.api_jwt.InsecureKeyLengthWarning` because the test signing key is 8 bytes long.
|
||||
Evidence: the two warnings emitted during `python3 -m pytest backend/apps/accounts/tests backend/apps/salons/tests` (see the console output).
|
||||
- Observation: JWT test key warning appears in suite.
|
||||
Evidence: `InsecureKeyLengthWarning` during accounts/salons pytest runs.
|
||||
|
||||
## Decision Log
|
||||
|
||||
- (2026-03-14 12:00 UTC) Committed to the pre-verified user lifecycle: `PhoneAuthRequestView` creates the user (if missing) before sending an auth OTP, and `PhoneAuthVerifyView` marks `is_phone_verified` true immediately upon successful verification.
|
||||
- (2026-03-14 12:00 UTC) Deferred OAuth linking and non-KSA normalization until after the current auth reliability milestone, per the user request.
|
||||
- (2026-03-14 14:05 UTC) Added `User.display_name` so every read path has a phone-first fallback and reused it in serializers/models to keep staff/review/booking strings readable for phone-only accounts.
|
||||
- (2026-03-14 14:07 UTC) Reordered the Django admin list and add forms to highlight `phone_number` so admin workflows no longer depend on email-centric defaults.
|
||||
- Decision: Pre-create user on phone request; verify on phone verify.
|
||||
Rationale: deterministic onboarding lifecycle.
|
||||
Date/Author: 2026-03-14/Codex
|
||||
- Decision: Add `User.display_name` and reuse everywhere.
|
||||
Rationale: stable fallback for phone-only accounts.
|
||||
Date/Author: 2026-03-14/Codex
|
||||
|
||||
## Outcomes & Retrospective
|
||||
Core phone-first hardening landed and tests pass for implemented scope. Remaining work is mainly policy (OAuth linking/conflict) plus extra invariants coverage.
|
||||
|
||||
- Phone-first auth now pre-creates customers before OTP sends, marks them verified on `/api/auth/phone/verify/`, and treats passwords as deprecated. Serializers and models no longer fall back to `user.email`; they use `User.display_name` so phone-only accounts always show a meaningful label. Django admin and README/risks docs document the canonical login surface, and the targeted pytest bundle passes with the existing JWT warnings noted above.
|
||||
## Context and Orientation
|
||||
- Auth endpoints: `backend/apps/accounts/views.py`
|
||||
- User model/admin: `backend/apps/accounts/models.py`, `backend/apps/accounts/admin.py`
|
||||
- Cross-app display paths: `backend/apps/salons/`, `backend/apps/bookings/`
|
||||
|
||||
## Plan of Work
|
||||
1. Keep adding invariant tests first.
|
||||
2. Finalize OAuth linking/conflict policy and enforce in auth services.
|
||||
3. Update docs/runbooks/risks with final contract.
|
||||
|
||||
## Validation and Acceptance
|
||||
From `backend/`:
|
||||
- `python3 -m pytest backend/apps/accounts/tests backend/apps/salons/tests`
|
||||
Acceptance:
|
||||
- Phone auth endpoints remain canonical and stable.
|
||||
- Display paths show phone-first labels when email absent.
|
||||
- New invariant tests pass.
|
||||
|
||||
## Idempotence and Recovery
|
||||
Auth hardening changes are additive and test-gated. Roll back by app-level revert if a contract regression is detected.
|
||||
|
||||
Reference in New Issue
Block a user