# 🔐 Dham Seva — Unified Authentication & Identity Ecosystem
## Module Architecture & Security Master Blueprint (`modaul/auth.md`)

> **Executive Overview:**  
> The **Dham Seva Authentication System** provides unified, high-security access for all 5 platform personas:
> 1. **Super Admin / Moderators** (`/admin/login`, `/admin/pin-login`)
> 2. **Devotees & Yatris** (`/auth/login`, `/auth/register`)
> 3. **Sacred Bloggers & Devotee Authors** (`/@username`, `/blogger/login`)
> 4. **Business Vendors & Trust Managers** (`/vendor/register`, `/vendor/login`)
> 5. **Fundraisers & Medical Campaigners** (`/fundraiser/register`, `/fundraiser/login`)

---

## 🛡️ 1. Multi-Tier Security Engine (सुरक्षा प्रोटोकॉल)

1. **Dual OTP Recovery Flow (द्वि-स्तरीय ओटीपी):**
   - ईमेल और मोबाइल दोनों पर एक साथ 6-अंकों का OTP भेजा जाता है।
   - पासवर्ड भूलने या अनधिकृत डिवाइस से लॉगिन करने पर दोनों OTP सत्यापित करना अनिवार्य है।
2. **4-Digit Quick PIN Login (क्विक पिन लॉगिन):**
   - पहली बार लॉगिन के बाद यूजर अपना 4-अंकों का व्यक्तिगत PIN सेट कर सकता है।
   - बार-बार पासवर्ड टाइप करने की आवश्यकता नहीं, केवल PIN से 1 सेकंड में सुरक्षित लॉगिन।
3. **Trusted Device & Progressive Lockout (डिवाइस सुरक्षा व लॉकआउट):**
   - 5 गलत पासवर्ड प्रयासों पर 15 मिनट का प्रोग्रेसिव लॉकआउट।
   - नए ब्राउज़र या अनजानी IP से लॉगिन करने पर ट्रस्टेड डिवाइस ईमेल अलर्ट।
4. **Social Sign-In (Google OAuth 2.0):**
   - 1-क्लिक "Continue with Google" लॉगिन जो सीधे यूजर के जीमेल से प्रोफाइल और ईमेल फेच करता है।

---

## 🔘 2. Inline Account Creation & Live Searchable Dropdowns (एडमिन इनलाइन यूजर निर्माण)

*एडमिन को किसी भी मॉड्यूल (Articles, Business Directory, Crowdfunding) में काम करते समय बाहर नहीं जाना पड़ता:*

### Two-Way User Selection Architecture:
1. **Mode A: `🔘 Link Existing User / Account`**
   - नेटिव हाई-परफॉर्मेंस **लाइव सर्च बॉक्स (Live Search Box)** युक्त ड्रॉपडाउन।
   - नाम, ईमेल, या मोबाइल नंबर टाइप करते ही रियल-टाइम में सेकंड्स में फ़िल्टर।
   - कोई भारी विदेशी लाइब्रेरी (Select2/Choices) नहीं, 100% नेटिव वैनिला JS।
2. **Mode B: `➕ Register New User Account`**
   - सीधे उसी फॉर्म के भीतर नए यूजर का नाम, मोबाइल नंबर, ईमेल और पासवर्ड दर्ज करने की सुविधा।
   - फॉर्म सबमिट होते ही बैकएंड में यूजर अकाउंट बनता है, उचित रोल असाइन होता है, और रिकॉर्ड से स्वतः लिंक हो जाता है।

---

## 🗄️ 3. डेटाबेस फील्ड्स व रोल्स

```sql
-- users table extensions
ALTER TABLE `users`
  ADD COLUMN `role` ENUM('admin', 'devotee', 'author', 'vendor', 'fundraiser') DEFAULT 'devotee',
  ADD COLUMN `quick_pin` VARCHAR(255) NULL,
  ADD COLUMN `pin_enabled` BOOLEAN DEFAULT FALSE,
  ADD COLUMN `two_factor_secret` VARCHAR(255) NULL,
  ADD COLUMN `trusted_devices` JSON NULL,
  ADD COLUMN `mobile_verified_at` TIMESTAMP NULL;
```

---

## 🚀 4. संबंधित कंट्रोलर्स व व्यूज (File Directory)

- **Controllers:**
  - `app/Http/Controllers/Admin/AuthController.php`
  - `app/Http/Controllers/Frontend/Auth/LoginController.php`
  - `app/Http/Controllers/Frontend/Auth/RegisterController.php`
  - `app/Http/Controllers/Frontend/Auth/ForgotPasswordController.php`
- **Views:**
  - `resources/views/admin/auth/login.blade.php`
  - `resources/views/admin/auth/pin-login.blade.php`
  - `resources/views/admin/auth/pin-setup.blade.php`
  - `resources/views/admin/auth/dual-otp-verify.blade.php`
  - `resources/views/admin/auth/trusted-device.blade.php`

---

*स्थिति: 100% पूर्ण, टेस्टेड एवं प्रोडक्शन में कार्यरत।*
