hamid
3a51305343
- six REST endpoints (auth/request_otp, verify_otp, refresh, logout, me, me/select_role) wrapping the existing JWE/TOTP/RBAC engine - usr.UserSessions with refresh-token rotation + stolen-token (replay) detection → revoke-all + 401; logout rotates the security stamp - users extended: gender, national_id (enc, NULL until KYC), shahkar_verified_at (auto-reset on phone change), phone_hash UNIQUE, is_active, deleted_at + soft-delete filter; phone/email/national_id encrypted at rest via IFieldEncryptor value converter - user_roles grant/revoke audit trail + global revoked filter; 7 roles seeded; admin sub-roles never self-assignable (403) - ISmsSender seam (mock logs the OTP code) replaces the TODO log lines - OperationResult/BaseController learned enveloped 401/403 - auth knobs as platform_configs rows (resend/attempts/session TTL) - migration IdentitySessionsAndUserExtensions applied to the dev DB - 24 new tests incl. Baya.Test.Api (WebApplicationFactory over SQLite); 47 total green, zero new build warnings; swagger snapshot + contract (identity-auth.md), handoff, report, mocks-registry updated Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
29 lines
3.2 KiB
Markdown
29 lines
3.2 KiB
Markdown
# 1. Actors & Onboarding
|
|
|
|
[← Business Requirements](index.md)
|
|
|
|
## (a) Business requirements
|
|
- Three actor types: **customer** (the family member / payer), **nurse** (the independent caregiver / seller), and **admin** (Balinyaar back-office staff: support, finance, moderation, super-admin).
|
|
- **Phone number is the primary login credential.** Authentication is **phone-OTP** (one-time code by SMS). Email is optional/secondary (required only for admin accounts).
|
|
- The **patient** (care recipient) is a first-class entity distinct from the customer, because the payer (an adult child, a spouse) is frequently not the patient (an elderly parent, a newborn, a post-surgical adult). A customer may register multiple patients.
|
|
- **KYC timing is role- and risk-staged, not up-front-for-everyone:**
|
|
- A **customer** can register and browse with only a verified phone (OTP). National-ID KYC for customers is anti-fraud only and is **deferred** at launch.
|
|
- A **nurse** must complete the full verification pipeline (Section 2) before any of their service variants become bookable. `national_id` is populated only after the identity step passes.
|
|
- An **admin** is provisioned internally with RBAC roles.
|
|
- Each successful login creates a refresh-token session that can be revoked (logout, stolen-token detection).
|
|
- **As-built decisions (backend-phase-2):** each refresh **rotates** the session (old revoked, new pair issued); a refresh token presented against an already-revoked session is treated as **stolen-token reuse → all of the user's sessions are revoked and the call returns 401**. Logout rotates the security stamp, so every outstanding access token dies (other devices recover by refreshing). OTP request/verify never reveal whether a phone already has an account; one OTP per phone per resend window (`auth_otp_resend_seconds`), and after `auth_otp_max_attempts` wrong codes verification refuses until a fresh OTP. `customer`/`nurse` are the only self-selectable roles (a user may hold both; grants audited via `granted_by`/`granted_at`); any admin sub-role self-assign attempt returns **403** — admin provisioning is internal-only.
|
|
|
|
## (b) Iran-specific considerations
|
|
- Phone-OTP is the dominant Iranian login norm and is also the anchor for **Shahkar** SIM↔national-ID binding (Section 2).
|
|
- Storing `national_id` only post-KYC matches the reality that identity is verified through gated vendor APIs, not collected casually at signup.
|
|
- Cultural reality: the booking flow must let a family member act on behalf of a patient who cannot self-advocate (infant, dementia, post-anesthesia). The customer/patient split is essential, not cosmetic.
|
|
|
|
## (c) MVP vs DEFERRED
|
|
- **MVP:** phone-OTP login; customer/nurse/admin roles; customer→patient (1:N); session management; admin RBAC; nurse onboarding gated on verification.
|
|
- **DEFERRED:** customer national-ID KYC (`customer_profiles.national_id_verified_at` exists but is optional/unused at launch); push notifications; social login; nursing-company (organization) self-onboarding.
|
|
|
|
## (d) Supporting database entities
|
|
`users`, `user_sessions`, `roles`, `user_roles`, `nurse_profiles`, `customer_profiles`, `patients`, `customer_addresses`.
|
|
|
|
> **Related:** Data model — [Identity & Access](../data-model/01-identity-and-access.md).
|