# مشخصات درس‌نامه: احراز هویت و کنترل دسترسی (Auth & Access)؛ تفکیک نقش‌ها و محافظت از روت‌ها
- **شناسه در سیلابس:** `L11.4`
- **فصل:** فصل ۱۱: امنیت و استفاده مسئولانه (Ch 11)
- **نوع محتوا:** 📘 درس‌نامه متنی
- **زمان تقریبی مطالعه:** ۱۸ دقیقه
- **پیش‌نیازهای مستقیم:** `L11.3` (مدیریت Secretها و کلیدهای API)

---

## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
- [ ] **درک کند (Understand):** تفاوت بنیادین میان «احراز هویت» (Authentication: تو کیستی؟) و «مجوز دسترسی» (Authorization: اجازه انجام چه کاری داری؟) را شرح دهد.
- [ ] **تحلیل/ارزیابی کند (Evaluate):** آسیب‌پذیری مهلک اعتماد به ظاهر رابط کاربری (مخفی کردن دکمه حذف بدون بررسی سرور) را ارزیابی کرده و خطرات حملات IDOR / BOLA را بشناسد.
- [ ] **به‌کار ببندد (Apply):** سامانه کنترل دسترسی مبتنی بر نقش (Role-Based Access Control - RBAC) را در پورتفولیو پیاده کند تا فقط ایمیل اختصاصی ادمین به بخش‌های ویرایش و پنل سئو دسترسی داشته باشد.
- [ ] **ایجاد کند (Create):** یک میدل‌ویر مستحکم در Next.js (`middleware.ts`) به همراه گیت‌های امنیتی در تمام Server Actionها بسازد که درخواست‌های غیرمجاز مستقیم cURL را در نطفه خفه کند.

---

## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)

### آنچه باید پوشش داده شود (In-Scope):
1. **داستان مسافری که کارت سوار شدن داشت اما به کابین خلبان رفت!**
   * چرا صرف لاگین کردن با گیت‌هاب نباید به یک کاربر اجازه حذف پروژه‌های شما را بدهد؟
2. **کالبدشکافی تفاوت AuthN در برابر AuthZ:**
   * Authentication (هویت‌سنجی): کاربر ثابت می‌کند خودش است (ورود با رمز یا OAuth).
   * Authorization (سطح دسترسی): سیستم تصمیم می‌گیرد که آیا این کاربر اجازه حذف، ویرایش یا مشاهده دارد یا خیر.
3. **آسیب‌پذیری کلاسیک: مخفی کردن دکمه در فرانت‌اند بدون گیت سرور:**
   * نوشتن شرط `{isAdmin && <Button>حذف</Button>}` در ظاهر زیباست، اما نفوذگر با یک درخواست ساده شبکه (`fetch` یا cURL) اندپوینت را صدا می‌زند!
4. **پیاده‌سازی دو لایه دفاعی در Next.js:**
   * لایه اول: میدل‌ویر لبه (`middleware.ts`) برای هدایت سریع کاربران عادی از مسیر `/admin/*` به صفحه لاگین.
   * لایه دوم: گارد سرور اکشن (Server Action Guard) در ابتدای تمام توابع ایجاد، ویرایش و حذف پروژه:
     ```typescript
     const { data: { user } } = await supabase.auth.getUser();
     if (!user || user.email !== process.env.ADMIN_EMAIL) {
       throw new Error("دسترسی غیرمجاز: شما ادمین نیستید!");
     }
     ```
5. **معماری نقش‌ها (RBAC) در پروژه پورتفولیو:**
   * نقش `admin`: دسترسی کامل به ویرایش پورتفولیو، تغییرات سئو و مشاهده تراکنش‌ها.
   * نقش `user`: مشاهده وضعیت رزروهای مشاوره خود.
   * نقش `visitor`: مشاهده پروژه‌های عمومی و ارسال پیام در فرم تماس.
6. **کال‌اوت‌های آموزشی و هشدار کوئرا:**
   * کال‌اوت بنفش (`<details class="violet">`): آسیب‌پذیری IDOR (Insecure Direct Object References)؛ وقتی کاربر با تغییر شناسه در آدرس (`/orders/42` به `/orders/43`) سفارش دیگری را می‌بیند!
   * کال‌اوت سبز (`<details class="green">`): سرعت خارق‌العاده Next.js Edge Middleware که قبل از لود شدن کامپوننت، دسترسی را اعتبارسنجی می‌کند.
   * کال‌اوت قرمز (`<details class="red">`): هرگز به متغیرهای کلاینتی برای تشخیص ادمین بودن اعتماد نکنید؛ همه چیز در فرانت‌اند قابل دستکاری در Console است.

### آنچه نباید وارد آن شویم (Out-of-Scope):
- ساختارهای سازمانی پیچیده Multi-tenant با ده‌ها گروه کاربری.
- استانداردهای اداری انطباق SOC2 و HIPAA.

---

## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)

| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
| :--- | :--- | :--- |
| Authentication (AuthN) | احراز هویت | فرآیند راستی‌آزمایی و اثبات هویت ادعاشده توسط یک کاربر در سیستم |
| Authorization (AuthZ) | کنترل و تفویض دسترسی | فرآیند تعیین اینکه کاربر احراز هویت شده مجاز به دسترسی به چه منابعی است |
| RBAC | کنترل دسترسی مبتنی بر نقش | مدل امنیتی که دسترسی‌ها را بر اساس نقش‌های تعریف‌شده (ادمین، کاربر عادی) اعطا می‌کند |
| Middleware Guard | نگهبان لایه میانی | کدی که پیش از رسیدن درخواست به صفحات، توکن و وضعیت دسترسی را بررسی و فیلتر می‌کند |
| IDOR / BOLA | ارجاع مستقیم ناامن به شیء | باگ امنیتی که به کاربر اجازه می‌دهد با دستکاری شناسه عددی، داده‌های دیگران را مشاهده یا ویرایش کند |
| Client-Side Security Fallacy | توهم امنیت در کلاینت | باور غلط مبنی بر اینکه مخفی کردن یک دکمه یا صفحه در مرورگر مانع هک شدن آن می‌شود |

---

## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:

1. **تصویر کاور درس:** `images/cover.png`
   * **موضوع:** گیت بازرسی امنیتی نئونی با دو درب مجزا: یکی تایید چهره (هویت) و دیگری اسکن اثر انگشت اتاق فرمان (دسترسی ادمین).
2. **تفاوت مفهومی هویت در برابر مجوز دسترسی:** `images/authn-vs-authz-diagram.png`
   * **موضوع:** اینفوگرافیک مقایسه‌ای: کارت پرواز (شما مسافر این هواپیمایی هستید) در برابر مجوز ورود به کابین خلبان (فقط کادر پرواز).
3. **جریان محافظت دو لایه از روت‌های پنل مدیریت:** `images/two-layer-route-protection.png`
   * **موضوع:** فلوچارت امنیتی: درخواست کاربر $\rightarrow$ لایه ۱: میدل‌ویر مسیر `/admin` $\rightarrow$ لایه ۲: گارد اعتبارسنجی ادمین داخل Server Action $\rightarrow$ تغییر در دیتابیس.
4. **تله امنیتی پنهان‌سازی ظاهری دکمه‌ها:** `images/client-side-hidden-button-trap.png`
   * **موضوع:** کاریکاتور نفوذگری که از پنجره پشت سرور دکمه حذف را با دستور cURL صدا می‌زند در حالی که در ظاهر سایت دکمه مخفی شده است.

---

## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)

1. **تیتر اصلی:** `# احراز هویت و کنترل دسترسی (Auth & Access)؛ تفکیک نقش‌ها و محافظت از روت‌ها`
2. **مقدمه:** چرا هر کاربری که وارد سایت می‌شود نباید بتواند پروژه‌های شما را پاک کند و تفاوت حیاتی کیستی و دسترسی چیست؟
3. **جدول کاور درس**
4. **استعاره مهمان هتل و کلید مستر مدیر:**
   * همه مسافران هتل کلید دارند، اما فقط مدیر می‌تواند درب انبار و گاوصندوق را باز کند.
5. **توهم خطرناک امنیت در فرانت‌اند (Security through Obscurity):**
   * چرا مخفی کردن لینک `/admin` در منو، امنیتی در حد قرار دادن کلید خانه زیر پادری است!
6. **پیاده‌سازی سپر دفاعی اول: میدل‌ویر Next.js (`middleware.ts`):**
   * کد تمیز خواندن سشن سوپابیس و فیلتر کردن روت‌های حساس.
7. **پیاده‌سازی سپر دفاعی دوم: گیت‌های احراز هویت داخل Server Actions:**
   * نوشتن تابع کمکی `verifyAdminSession()` و فراخوانی آن در ابتدای تمام عملیات‌های جهش داده (Mutations).
8. **جعبه پرامپت طلایی: امن‌سازی تمام روت‌ها و اکشن‌ها با ایجنت:**
   * پرامپت دقیق:
     > «تمام Server Actionها و Route Handlerهای پروژه پورتفولیو را بازبینی کن. مطمئن شو که در ابتدای هر تابعی که داده‌ای را در دیتابیس تغییر می‌دهد، هویت کاربر بررسی شود و تنها در صورتی که ایمیل کاربر با `ADMIN_EMAIL` مطابقت داشته باشد اجازه ادامه داده شود. در غیر این صورت یک خطای ۴۰۱ یا ۴۰۳ استاندارد صادر کن.»
9. **دستورات چندسکویی برای تعریف ایمیل ادمین در متغیرهای محیطی:**
   * منوی کشویی سه‌گانه برای ویندوز، مک و لینوکس:
     - Windows (PowerShell):
       ```powershell
       Add-Content .env.local "`nADMIN_EMAIL=your-secure-email@gmail.com"
       ```
     - macOS (Terminal):
       ```bash
       echo "ADMIN_EMAIL=your-secure-email@gmail.com" >> .env.local
       ```
     - Linux (Bash):
       ```bash
       echo "ADMIN_EMAIL=your-secure-email@gmail.com" >> .env.local
       ```
10. **باکس نکته Quera (`<details class="violet">`):** ماجرای باگ وحشتناک IDOR؛ چطور بررسی نکردن مالکیت رکوردها به هکرها اجازه دیدن فاکتورهای سایرین را می‌دهد.
11. **باکس هشدار Quera (`<details class="red">`):** هرگز از `localStorage` برای ذخیره کردن نقش کاربر (`role: admin`) استفاده نکنید؛ هر کاربر می‌تواند با کلید F12 این مقدار را تغییر دهد!
12. **باکس رضایت‌بخش Quera (`<details class="green">`):** امتحان لاگین با یک اکانت دیگر و مشاهده پیام مسدود شدن دسترسی در پنل ادمین.
13. **جمع‌بندی درس‌نامه:** مجهز شدن به سیستم دفاعی ضد نفوذ دسترسی؛ ورود به حوزه اعتبارسنجی ورودی‌ها با Zod و مقابله با حملات XSS در درس بعدی.

---

## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
- [ ] تفاوت مفهومی و کاربردی Authentication و Authorization تبیین گردد.
- [ ] استراتژی دو لایه محافظت (میدل‌ویر + گیت سرور اکشن) پیاده‌سازی و تشریح شود.
- [ ] باگ امنیتی پنهان‌سازی ظاهری دکمه‌ها و خطر IDOR به شکل ملموس توضیح داده شود.
- [ ] پرامپت ایمن‌سازی اکشن‌ها برای ایجنت به همراه کدهای استاندارد ارائه گردد.