Files

T

hamid 3a51305343 backend phase 2: identity — phone-OTP auth, sessions & roles (REST)

- 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>

2026-07-02 02:34:11 +03:30

3.2 KiB

Raw Blame History

1. Actors & Onboarding

← Business Requirements

(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.

3.2 KiB Raw Blame History

1. Actors & Onboarding

(a) Business requirements

(b) Iran-specific considerations

(c) MVP vs DEFERRED

(d) Supporting database entities

3.2 KiB

Raw Blame History