پیاده‌سازی امن Refresh Token در فرانت‌اند

---
name: "refresh-token-in-frontend"
description: "چرخه تمدید Access Token را با Cookie از نوع HttpOnly، صف Retry، Rotation، پشتیبانی SSR و Logout امن در برنامه مرورگری طراحی و بازبینی کن."
---

# پیاده‌سازی امن Refresh Token در فرانت‌اند

این Skill را برای طراحی، پیاده‌سازی یا بازبینی چرخه تمدید Access Token کوتاه‌عمر در برنامه مرورگری به کار ببر.

## مدل امنیتی لازم

- Refresh Token را در Cookie با `Secure`، `HttpOnly` و Scope محدود نگه دار.
- Access Token را کوتاه‌عمر و در صورت امکان در حافظه برنامه نگه دار.
- در Production از HTTPS استفاده کن.
- Rotation و تشخیص استفاده مجدد Refresh Token را در Backend اجرا کن.
- Authorization را مسئولیت Server بدان؛ Guard فرانت‌اند فقط UX را بهبود می‌دهد.

## ابتدا قرارداد را مشخص کن

Endpointهای Login، Refresh، Logout و Session، ویژگی Cookie، دفاع CSRF، شکل پاسخ Access Token، رفتار Expiration و مدل CSR یا SSR را بررسی کن. کمبود تضمین Server را با راه‌حل ساختگی Client پنهان نکن.

## روند Client

1. در صورت وجود Access Token، آن را همراه Request محافظت‌شده بفرست.
2. در خطای Authentication واجد شرایط، حداکثر یک Request تمدید فعال بساز.
3. Requestهای شکست‌خورده هم‌زمان را پشت همان عملیات صف کن.
4. پس از موفقیت، Token حافظه را به‌روز و هر Request اصلی را فقط یک بار Retry کن.
5. Request تکرارشده را علامت بزن تا Loop ساخته نشود.
6. در شکست Refresh، Session محلی را پاک، Requestهای صف را Reject و کاربر را وارد روند خروج کن.
7. در Logout، Endpoint ابطال Session و پاک‌کردن Cookie را صدا بزن و سپس State سمت Client را پاک کن.

## حالت‌های حساس

- خود Request تمدید را دوباره وارد Interceptor تمدید نکن.
- `401` انقضای Authentication را از `403` نبود Permission جدا کن و به قرارداد API تکیه کن.
- Logout حین Refresh و کارهای قدیمی را مدیریت کن.
- Request غیر Idempotent را بدون تضمین قابلیت بازپخش Retry نکن.
- در SSR، Credential را از مرز Server خارج و داخل Props یا Log سریال‌شده افشا نکن.

Request عادی، یک Token منقضی، چند خطای هم‌زمان، شکست Refresh، Rotation، Logout حین Refresh، جلوگیری از Loop، Reload و رفتار SSR را تست کن. تضمین‌های Backend و بخش‌های تأییدشده Frontend را جدا گزارش کن.