vibe-coding-college-specs/chapters/11-security-and-best-practices/05-lesson-database-and-file-upload-security/spec.md

مشخصات درس‌نامه: امنیت دیتابیس (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) آموزش داده شود.
• پرامپت ساخت ماژول آپلود امن توسط ایجنت در متن درس گنجانده شود.