chore: auth gaps docs

backend/README.md

@@ -4,8 +4,8 @@
 - Authentica OTP integration is implemented; Moyasar capture/refund are TODOs.
 - External calls (OTP, notifications, payment gateway) run synchronously in request/response paths, increasing latency risk.
 - Cross-app coupling (bookings ↔ notifications ↔ accounts/payments) will get harder to evolve without clearer service boundaries.
-- Phone-first auth works, but `USERNAME_FIELD` is email; align identifier strategy to avoid future auth confusion.
+- Phone-first auth is in place with `USERNAME_FIELD = "phone_number"`, but endpoint/admin/domain alignment is still incomplete and needs hardening.
 
 ## Near-Term Focus
 - finalize otp testing
-- work on authentication and complete it
+- work on authentication and complete it

docs/PLANS.md

@@ -6,6 +6,17 @@ This document describes the requirements for an execution plan ("ExecPlan"), a d
 
 The current execution plan is `docs/execplans/booking-notifications.md`. It focuses on booking lifecycle notifications (confirmation/cancellation) as the next Phase 1 reliability milestone. Keep it updated in line with the requirements below.
 
+## Queued Next Review Focus
+
+After the active booking notifications plan, the next reliability review track is phone-first authentication hardening. Keep these points visible when planning the next ExecPlan update:
+
+- Enforce phone as first-class identifier at model/DB boundaries (normalized E.164, nullability/uniqueness policy).
+- Consolidate auth contract (phone OTP vs password endpoints) and document intended public login surface.
+- Enforce OTP purpose boundaries (`auth` vs `verify`) in verification flows.
+- Align Django admin and cross-app display/audit behavior for phone-only users.
+- Define OAuth linking policy and conflict handling (phone/email collisions, account merge rules).
+- Add/expand tests for phone-first invariants and abuse controls (IP/device throttling strategy review).
+
 ## How to use ExecPlans and PLANS.md
 
 When authoring an executable specification (ExecPlan), follow PLANS.md _to the letter_. If it is not in your context, refresh your memory by reading the entire PLANS.md file. Be thorough in reading (and re-reading) source material to produce an accurate specification. When creating a spec, start from the skeleton and flesh it out as you do your research.

docs/risks.md

@@ -8,6 +8,18 @@ This file tracks known gaps and risks to address in future iterations.
 - Authentica OTP provider is implemented (SMS + WhatsApp via Authentica OTP).
 - Social login is a placeholder.
 - `USERNAME_FIELD` is now `"phone_number"`; `REQUIRED_FIELDS = []`; `create_superuser` accepts `phone_number`. Admin and `createsuperuser` work correctly for phone-only users.
+- API currently exposes mixed auth paths (`/accounts/register/`, `/accounts/token/`, and phone OTP login), creating unclear source-of-truth for identity/auth policy.
+- OTP purpose isolation is enforced at verification endpoint boundaries (`/otp/verify` accepts only `verify`, `/phone/verify` accepts only `auth`).
+- Django admin user configuration remains email-centric (ordering/add form defaults), increasing operational friction for phone-only accounts.
+- Multiple serializers/model `__str__` paths in non-auth apps still fallback to `user.email`; phone-only users may get poor display/audit clarity.
+
+## Next Auth Review Points
+- Enforce normalized E.164 phone format at model/DB boundary (constraints, indexing, uniqueness behavior with nullable fields).
+- Add DB-level non-null + format guardrails for `accounts_user.phone_number` to complement service-level normalization.
+- Decide user lifecycle for phone auth (create user before OTP verify vs provisional/pre-user state).
+- Expand abuse prevention beyond per-phone cooldown (IP throttling, device fingerprint, risk signals).
+- Define OAuth account-linking policy (phone/email conflicts, merge rules, trust source).
+- Add explicit tests for phone-first invariants (null-phone rejection if required, token endpoint behavior, OTP purpose isolation, verified-phone guards).
 
 ## Booking Integrity
 - Availability checks and overlap prevention are now enforced for staff bookings.