vibe-coding-college-specs/chapters/11-security-and-best-practices/03-lesson-auth-and-access-control/spec.md

مشخصات درس‌نامه: احراز هویت و کنترل دسترسی (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) در ابتدای تمام توابع ایجاد، ویرایش و حذف پروژه:

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

       Add-Content .env.local "`nADMIN_EMAIL=your-secure-email@gmail.com"
       

     • macOS (Terminal):

       echo "ADMIN_EMAIL=your-secure-email@gmail.com" >> .env.local
       

     • Linux (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 به شکل ملموس توضیح داده شود.
• پرامپت ایمن‌سازی اکشن‌ها برای ایجنت به همراه کدهای استاندارد ارائه گردد.