# مشخصات درس‌نامه: امنیت دیتابیس (RLS) و پروتکل امن آپلود فایل در Supabase Storage
- **شناسه در سیلابس:** `L11.6`
- **فصل:** فصل ۱۱: امنیت و استفاده مسئولانه (Ch 11)
- **نوع محتوا:** 📘 درس‌نامه متنی
- **زمان تقریبی مطالعه:** ۱۸ دقیقه
- **پیش‌نیازهای مستقیم:** `L11.5` (اعتبارسنجی همه‌جانبه ورودی‌ها با Zod)

---

## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
- [ ] **درک کند (Understand):** چرا دریافت فایل از کاربر حساس‌ترین و خطرناک‌ترین قابلیت در هر وب‌اپلیکیشن است و چگونه فایل‌های مخرب می‌توانند کل سرور یا کلاینت‌ها را آلوده کنند.
- [ ] **تحلیل/ارزیابی کند (Evaluate):** خطرات امنیتی جعل پسوند فایل، حملات پیمایش مسیر (Path Traversal)، بمب‌های حجمی (Zip Bombs)، و اسکریپت‌های پنهان‌شده در تصاویر SVG را ارزیابی کند.
- [ ] **به‌کار ببندد (Apply):** باکت‌های ذخیره‌سازی ابری در Supabase Storage را با اعمال محدودیت حجم (حداکثر ۵ مگابایت)، لیست سفید پسوندها (MIME Types) و سیاست‌های کنترل دسترسی (Storage RLS) ایمن‌سازی نماید.
- [ ] **ایجاد کند (Create):** یک تابع آپلود تصویر پروژه بسازد که نام فایل را با استفاده از UUID تصادفی بازنویسی کند تا خطر بازنویسی فایل‌های سرور و تزریق مسیر به صفر برسد.

---

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

### آنچه باید پوشش داده شود (In-Scope):
1. **آسیب‌پذیری‌های کشنده در ماژول آپلود فایل:**
   * آپلود بدافزارها و فایل‌های اجرایی تحت نام‌های جعلی (مثلاً `shell.php.png` یا فایلی با اسکریپت اجرایی).
   * خطر پنهان تصاویر SVG: از آنجا که SVG یک کد متنی XML است، می‌تواند تگ‌های `<script>` حاوی XSS ماندگار را در خود پنهان کند!
   * حملات پر کردن دیسک و تحمیل هزینه‌های سنگین ابری با آپلود فایل‌های چندصد مگابایتی.
2. **پروتکل ۴ لایه برای آپلود امن در پروژه پورتفولیو:**
   * لایه ۱: اعتبارسنجی نوع فایل (MIME Type Whitelist): پذیرش انحصاری `image/jpeg`، `image/png`، `image/webp` و `application/pdf`.
   * لایه ۲: محدودسازی سفت‌وسخت حجم (File Size Limit): مسدود کردن فایل‌های بالاتر از ۵ مگابایت در فرانت‌اند و در لایه سرور.
   * لایه ۳: پاک‌سازی نام فایل و جایگزینی با UUID تصادفی: تبدیل `my-resume.pdf` به `f47ac10b-58cc-4372-a567-0e02b2c3d479.pdf` برای جلوگیری از Path Traversal (`../../`).
   * لایه ۴: سیاست‌های امنیتی باکت در Supabase (Storage Policies): خواندن عکس‌ها برای عموم آزاد (`SELECT`)، اما افزودن یا حذف عکس‌ها فقط برای کاربر ادمین احراز هویت شده مجاز است.
3. **بازبینی امنیت دیتابیس (SQL Injection و RLS):**
   * چرا استفاده از متدهای رسمی Supabase SDK شما را به صورت پیش‌فرض در برابر SQL Injection ایمن می‌کند (Parameterized Queries).
   * چک‌لیست نهایی اطمینان از روشن بودن RLS روی تمام جداول دیتابیس (`projects`, `site_settings`, `consultation_bookings`).
4. **جعبه پرامپت طلایی: ساخت ماژول آپلود امن با ایجنت:**
   * پرامپت ایجاد کامپوننت آپلود با پیش‌نمایش، اعتبارسنجی سایز، و ذخیره در باکت Supabase.
5. **کال‌اوت‌های آموزشی و هشدار کوئرا:**
   * کال‌اوت بنفش (`<details class="violet">`): حمله پیمایش دایرکتوری (Path Traversal Attack) و چگونگی نفوذ خرابکاران با نام فایل‌هایی مثل `../../etc/passwd`.
   * کال‌اوت سبز (`<details class="green">`): تبدیل خودکار عکس‌ها به فرمت مدرن WebP با کتابخانه Next.js برای کاهش حجم تا ۷۰٪.
   * کال‌اوت قرمز (`<details class="red">`): خطر آپلود SVG توسط کاربران غریبه؛ هرگز باکت عمومی را بدون اعتبارسنجی به روی فایل‌های SVG باز نگذارید.

### آنچه نباید وارد آن شویم (Out-of-Scope):
- راه‌اندازی آنتی‌ویروس‌های کلاود مانند ClamAV برای اسکن باینری.
- مدیریت دیسک‌های فیزیکی سرورهای خودمیزبان (Self-hosted NFS).

---

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

| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
| :--- | :--- | :--- |
| File Upload Vulnerability | آسیب‌پذیری آپلود فایل | رخنه امنیتی ناشی از دریافت و ذخیره فایل‌های مخرب یا بسیار حجیم بدون اعتبارسنجی |
| MIME Type | شناسه نوع رسانه | استاندارد جهانی مشخص‌کننده ماهیت و قالب فایل در وب (نظیر image/png) |
| Path Traversal | پیمایش غیرمجاز مسیر | حمله دستکاری نام فایل با نمادهای ../ برای دسترسی یا بازنویسی فایل‌های سیستمی سرور |
| Storage Bucket Policy | سیاست امنیتی باکت ذخیره‌سازی | قوانین کنترلی در سطح فضای ابری برای تعیین اینکه چه کسانی اجازه دانلود یا آپلود فایل دارند |
| Parameterized Queries | کوئری‌های پارامتریزه | روش استاندارد اجرای دستورات دیتابیس که داده‌های کاربر را از دستورات SQL جدا و ایمن می‌کند |
| SVG Script Injection | تزریق اسکریپت در فایل SVG | نوعی حمله XSS که از قابلیت اجرای جاوااسکریپت در ساختار برداری وکتور SVG سوءاستفاده می‌کند |

---

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

1. **تصویر کاور درس:** `images/cover.png`
   * **موضوع:** جعبه امنیتی دیجیتال با اسکنر اشعه ایکس که فایل‌های ورودی را اسکن کرده و بدافزارهای درون عکس را متوقف می‌کند.
2. **چرخه ۴ لایه محافظت از آپلود فایل:** `images/four-layer-file-security-flow.png`
   * **موضوع:** فلوچارت لایه‌های دفاعی: انتخاب فایل $\rightarrow$ ۱) بررسی پسوند/MIME $\rightarrow$ ۲) بررسی سایز < 5MB $\rightarrow$ ۳) بازنویسی نام به UUID $\rightarrow$ ۴) اعتبارسنجی RLS باکت.
3. **تنظیمات سیاست‌های باکت در داشبورد Supabase Storage:** `images/supabase-storage-policies-setup.png`
   * **موضوع:** اسکرین‌شات از بخش Storage Policies در سوپابیس با تفکیک دسترسی Public Read و Admin Insert/Delete.
4. **حمله Path Traversal و نحوه خنثی‌سازی آن:** `images/path-traversal-neutralization.png`
   * **موضوع:** اینفوگرافیک مقایسه‌ای: نام فایل مخرب نفوذگر در برابر نام فایل خنثی و تمیزشده با شناسه تصادفی در باکت.

---

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

1. **تیتر اصلی:** `# امنیت دیتابیس (RLS) و پروتکل امن آپلود فایل در Supabase Storage`
2. **مقدمه:** چرا دکمه آپلود فایل، جذاب‌ترین دروازه ورودی برای هکرهاست و چطور آن را مثل یک گاوصندوق امن کنیم؟
3. **جدول کاور درس**
4. **استعاره درب ورودی انبار کالا:**
   * هر کسی اجازه ورود کارتن در بسته بدون برچسب بازرسی به انبار شرکت را ندارد.
5. **خطرات مرگبار آپلود فایل بدون اعتبارسنجی:**
   * بدافزارهای پنهان در عکس، فایل‌های مخرب اجرایی، و داستان جالب اسکریپت‌های مخرب در فایل‌های SVG.
6. **پروتکل ۴ لایه ایمن‌سازی آپلود در پورتفولیوی شخصی:**
   * چک کردن MIME Type، سقف ۵ مگابایت، و بازنویسی نام با UUID.
7. **کدنویسی ماژول آپلود امن `lib/upload.ts`:**
   * تابع بارگذاری امن عکس‌های پروژه و تصویر کاور در باکت `portfolio-assets`.
8. **پیکربندی سیاست‌های باکت در Supabase Storage:**
   * تنظیم مجوز مشاهده همگانی برای تصاویر پروژه‌ها، و انحصار آپلود/حذف فقط برای ادمین لاگین‌شده.
9. **جعبه پرامپت طلایی: ساخت کامپوننت آپلود امن فایل با ایجنت:**
   * پرامپت دقیق:
     > «من می‌خواهم در پنل ادمین پورتفولیو، یک کامپوننت آپلود تصویر برای کاور پروژه‌ها اضافه کنم. این کامپوننت باید: ۱) فقط فایل‌های PNG، JPG و WebP زیر ۵ مگابایت را قبول کند، ۲) نام فایل را با یک UUID تصادفی جایگزین کند، ۳) فایل را مستقیماً در باکت `portfolio-assets` سوپابیس آپلود کند و ۴) آدرس عمومی تصویر را در دیتابیس ذخیره کند.»
10. **باکس نکته Quera (`<details class="violet">`):** ماجرای حمله Path Traversal؛ چرا هرگز نباید به نام اصلی فایل ارسالی کاربر اعتماد کرد.
11. **باکس هشدار Quera (`<details class="red">`):** هرگز اجازه آپلود اسناد اجرایی یا کدهای HTML/SVG را به کاربران احراز هویت نشده ندهید.
12. **باکس رضایت‌بخش Quera (`<details class="green">`):** تست آپلود یک تصویر سنگین یا نامعتبر و مشاهده مسدودسازی هوشمندانه آن با پیام خطای خوانا.
13. **جمع‌بندی درس‌نامه:** ایمن‌سازی کامل پایگاه داده و فایل‌ها؛ ورود به جهان پکیج‌ها و خطرات وابستگی‌های مخرب در درس بعدی.

---

## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
- [ ] آسیب‌پذیری‌های متداول آپلود فایل (جعل نوع فایل، فایل‌های حجیم و خطر SVG) تشریح گردند.
- [ ] پروتکل ۴ مرحله‌ای آپلود امن به همراه کدهای کاربردی ارائه شود.
- [ ] سیاست‌های دسترسی به باکت‌های Supabase Storage (Storage RLS) آموزش داده شود.
- [ ] پرامپت ساخت ماژول آپلود امن توسط ایجنت در متن درس گنجانده شود.