# Canina Iran — Security Guidelines & Architecture Manual

این مستند حاوی راهنماها، چک‌لیست‌های امنیتی و چارچوب‌های فنی پیاده‌سازی‌شده در پروژه کنینا ایران (NestJS + Next.js) می‌باشد.

---

## ۱. مدیریت نشست و کوکی / CSRF Protection (#SEC-021)

### استراتژی احراز هویت توکن‌ها:
1. **Access Token:**
   - زمان اعتبار: **۱۵ دقیقه (15m)**.
   - امضا شده با کلید اختصاصی `JWT_ACCESS_SECRET`.
   - پس از انقضا، فرانت‌اند به صورت خودکار از طریق Interceptor در `lib/services/api.ts` درخواست `/auth/refresh-token` را ارسال کرده و توکن جدید را دریافت و ریکوئست متوقف‌شده را مجدداً ارسال می‌کند.

2. **Refresh Token:**
   - زمان اعتبار: **۳۰ روز (30d)**.
   - امضا شده با کلید جداگانه `JWT_REFRESH_SECRET`.
   - ذخیره در Redis با کلید `refresh_token:{userId}:{tokenId}`.
   - **Token Rotation:** به ازای هر بار فراخوانی `/auth/refresh-token`، توکن قبلی در ردیس باطل شده و یک جفت توکن کاملاً تازه صادر می‌شود.

3. **حفاظت CSRF در معماری Cookie:**
   - در صورت انتقال Refresh Token به Cookie:
     - باید فلگ‌های `httpOnly: true`, `secure: true`, و `sameSite: 'strict'` یا `'lax'` فعال باشند.
     - برای درخواست‌های جهش‌دهنده وضعیت (POST, PUT, DELETE, PATCH)، هدر اختصاصی `X-Requested-With: XMLHttpRequest` یا الگوی Double Submit Cookie (CSRF Token در هدر `X-CSRF-Token`) پیاده‌سازی می‌شود.
     - در حال حاضر درخواست‌های API از هدر `Authorization: Bearer <token>` استفاده می‌کنند که مرورگرها آن را در درخواست‌های کراس‌سایت (Cross-Site) ناخواسته ارسال نمی‌کنند و در برابر CSRF سنتی ایمن است.

---

## ۲. چک‌لیست بررسی امنیتی کد (Security Code Review Checklist - #SEC-022)

هر توسعه‌دهنده پیش از باز کردن Pull Request یا ادغام کد، باید موارد زیر را بررسی کند:

### الف) ورودی‌ها و اعتبارسنجی (Input Validation)
- [ ] تمام DTOها از `class-validator` استفاده کرده و دارای دکوراتورهای متناسب (`@IsString()`, `@IsNumber()`, `@IsUUID()`, `@IsEmail()`) هستند.
- [ ] هیچ ورودی کاربری مستقیماً به دستورات SQL یا shell متصل نمی‌شود (استفاده الزامی از Prisma پارامتریک).
- [ ] آپلود فایل‌ها دارای اعتبارسنجی جدی پسوند، حجم (`fileSize`) و هدر MIME است (پسوندهای مشکوک نظیر `.svg`، `.html`، `.exe`، `.sh` کاملاً مسدود شوند).

### ب) خروجی‌ها و XSS Prevention
- [ ] هیچ محتوایی که توسط کاربر یا ادمین تایپ شده به طور مستقیم در `dangerouslySetInnerHTML` قرار نمی‌گیرد.
- [ ] در فرانت‌اند برای کامپوننت‌های رندر HTML از `DOMPurify.sanitize()` و در کامپوننت‌های SSR از `sanitize-html` استفاده می‌شود.
- [ ] داده‌های Schema.org و JSON-LD از تابع کمکی `safeJsonLd()` استفاده می‌کنند تا حملات Script Injection مهار شوند.

### ج) کنترل دسترسی (Access Control)
- [ ] تمام روت‌های محافظت‌شده دارای `@UseGuards(JwtAuthGuard, RolesGuard)` هستند.
- [ ] متدهای دسترسی به منابع (مانند جزئیات سفارش‌ها) بررسی می‌کنند که شناسه کاربر متصل با شناسه مالک داده تطابق داشته باشد (`order.userId === req.user.id`).
- [ ] در کنترلرهای ادمین، دسترسی‌های کلیدهای API (`ApiKeysService`) منحصراً نیازمند اسکوپ صریح `admin` باشند و اسکوپ‌های عامیانه و وایلدکارد مثل `*` یا `all` نادیده گرفته شوند.

### د) نرخ مصرف و سهمیه‌بندی (Rate Limiting)
- [ ] روت‌های حساس شامل ورود (`/auth/login`)، ثبت‌نام (`/auth/register`)، ارسال پیامک (`/auth/send-otp`) و پنل مدیریت دارای `@Throttle` اختصاصی با محدودیت‌های سخت‌گیرانه هستند.

---

## ۳. برنامه تست نفوذ دوره‌ای (Penetration Testing Plan - #SEC-023)

1. **فواصل زمانی ممیزی:**
   - تست نفوذ خارجی باید حداقل **سالانه یک‌بار** یا قبل از هر عرضه ماژور (Major Release) توسط یک تیم یا شرکت مستقل امنیت سایبری انجام شود.
2. **حیطه آزمون (Scope):**
   - آزمون جعبه سیاه (Black-box) و خاکستری (Grey-box) روی تمامی آدرس‌های دامنه عمومی، وب‌سرویس‌های RESTful و درگاه‌های پرداخت.
   - ممیزی فرآیندهای مالی (Race condition در افزایش/کاهش موجودی کیف پول و تایید تراکنش‌های زیبال).
   - آزمون نفوذ سرورهای زیرساخت و تنظیمات فایروال WAF و Nginx/Caddy.