فهم CORS المعمق: لماذا يرسل المتصفح طلبات OPTIONS وكيف تضبطها بالشكل الصحيح

🌐 CORS: Why Is the Browser Sending an OPTIONS Request?

"مين طلب منك تعمل OPTIONS يا ابني؟" 😅

CORS مش مشكلة في الـAPI — هو جزء من الـbrowser security model.

📚 Table of Contents

• الفكرة في دقيقة
• المشكلة من البداية
• Same-Origin Policy
• يعني إيه Origin؟
• Origin Examples
• CORS
• CORS Request Headers
• Preflight Request
• ليه الـBrowser يعمل Preflight؟
• شكل الـPreflight
• Simple Requests
• Credentials و Cookies
• Access-Control-Allow-Origin: *
• CORS مش Authentication
• CORS مش CSRF Protection
• CORS vs Same-Origin Policy
• Preflight Caching
• Common CORS Errors
• Backend Configuration
• Development vs Production
• Reverse Proxy وSame-Origin Architecture
• Production Checklist
• Common Misconceptions
• الخلاصة
• Further Reading

⚡ الفكرة في دقيقة

ناس كتير تعمل API محترمة جدًا، وفجأة تفتح DevTools تلاقي:

OPTIONS /api/orders
POST /api/orders

وتقول:

"مين طلب منك تعمل OPTIONS قبل الـPOST؟" 😂

الإجابة:

الـBrowser.

لأن الـBrowser بيطبق قواعد أمنية اسمها:

Same-Origin Policy

وCORS هو mechanism يسمح للسيرفر يحدد:

"أنا موافق إن JavaScript جاي من الـOrigin ده يقرأ الـresponse بتاعي."

فالصورة الكبيرة:

JavaScript
    ↓
Cross-Origin Request
    ↓
Browser Security Checks
    ↓
CORS
    ↓
Allow / Block access to response

🚨 المشكلة من البداية

تخيل إنك فاتح:

https://facebook.com

والموقع شغل JavaScript يعمل request على:

https://bank.com

والمستخدم أصلًا عامل Login في البنك.

المتصفح ممكن يكون عنده:

Bank Cookies
Bank Session
Authentication State

لو أي موقع يقدر يقرأ responses من أي موقع تاني بدون قيود:

Malicious Site
      ↓
Browser
      ↓
Bank
      ↓
Private Account Data
      ↓
Attacker

ده يفتح باب خطير جدًا لسرقة بيانات المستخدم.

عشان كده الـBrowser عنده:

Same-Origin Policy

وهي من أهم security boundaries في Web Platform.

🛡️ Same-Origin Policy

Same-Origin Policy بتقول بشكل مبسط:

JavaScript من Origin معين لا يستطيع بحرية قراءة بيانات من Origin مختلف.

MDN تصفها كآلية أمنية أساسية لعزل المستندات والـscripts من origins مختلفة وتقليل احتمالات تسريب البيانات. urlMDN — Same-Origin Policyhttps://developer.mozilla.org/en-US/docs/Web/Security/Defenses/Same-origin_policy

لكن خد بالك:

Cross-Origin لا يعني أن كل network request ممنوع.

الـWeb يسمح بعمليات cross-origin كثيرة، لكن الوصول للبيانات وقراءتها يخضع لقواعد مختلفة حسب نوع الـresource والـAPI.

🌍 يعني إيه Origin؟

الـOrigin يتكون من:

Scheme + Host + Port

وأحيانًا الناس تقول:

Protocol + Domain + Port

لكن الأدق:

scheme + hostname + port

مثال:

https://example.com

• Scheme = https
• Host = example.com
• Port = 443 ضمنيًا

MDN توضح أن الـorigin هو tuple من scheme + hostname + port. urlMDN — Originhttps://developer.mozilla.org/en-US/docs/Glossary/Origin

🔍 Origin Examples

Same Origin

https://example.com/page1
https://example.com/page2

نفس:

scheme
host
port

اختلاف الـpath لا يجعل الـorigins مختلفة.

Different Scheme

http://example.com
https://example.com

❌ Different Origin

لأن:

http ≠ https

Different Host / Subdomain

https://example.com
https://api.example.com

❌ Different Origin

حتى لو نفس الـregistrable domain.

Different Port

https://example.com
https://example.com:5001

❌ Different Origin

لأن الـport مختلف.

Development Example

Frontend:
http://localhost:4200

Backend:
http://localhost:5001

❌ Different Origins

وده سبب شائع جدًا لرسائل CORS أثناء الـdevelopment.

🔄 CORS

CORS اختصار لـ:

Cross-Origin Resource Sharing

وهو mechanism مبني حول HTTP headers وbrowser behavior يسمح للسيرفر بتحديد الـorigins والـmethods والـheaders التي يمكن استخدامها في cross-origin requests.

مثلاً:

Access-Control-Allow-Origin: https://frontend.com

معناه بشكل مبسط:

"الـresponse ده مسموح للـbrowser يشاركه مع JavaScript القادم من https://frontend.com."

MDN توضح أن Access-Control-Allow-Origin يحدد ما إذا كان الـresponse يمكن مشاركته مع origin معين، وأن CORS يعتمد على مجموعة من request/response headers. urlMDN — CORShttps://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS

🧠 CORS لا يعني أن السيرفر "يمنع الطلب"

دي من أهم النقاط في الموضوع.

في بعض الحالات:

Browser
   ↓
Request
   ↓
Server
   ↓
Server processes it
   ↓
Response
   ↓
Browser blocks JS from reading it

يعني ممكن تشوف في Network:

POST /api/orders
200 OK

لكن JavaScript يحصل له:

CORS error

لأن الـbrowser لم يسمح للـfrontend بقراءة الـresponse.

CORS is primarily a browser-enforced cross-origin response sharing mechanism.

لكن الـpreflight مختلف؛ الـbrowser قد يرسل OPTIONS أولًا قبل الـactual request للتحقق من السماح.

📋 CORS Request Headers

الـbrowser قد يرسل:

Origin: https://frontend.com

وفي الـpreflight:

Access-Control-Request-Method: POST
Access-Control-Request-Headers: authorization, content-type

والسيرفر يرد مثلًا:

Access-Control-Allow-Origin: https://frontend.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE
Access-Control-Allow-Headers: Authorization, Content-Type

MDN توضح دور Origin وAccess-Control-Request-Method وAccess-Control-Request-Headers في CORS requests وpreflight. urlMDN — CORS HTTP Headershttps://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS

✈️ Preflight Request

هنا الجزء اللي بيخلي الناس تستغرب:

OPTIONS /api/orders

الـbrowser أحيانًا يعمل Preflight Request قبل الـactual request.

فكر فيها كأن الـbrowser بيقول للسيرفر:

"أنا ناوي أبعت request بالشكل ده.
هل تسمح؟"

مثال:

Browser
   │
   │ OPTIONS /api/orders
   │
   │ "Can I send POST
   │  with Authorization
   │  and JSON?"
   ▼
Server
   │
   │ "Yes"
   ▼
Browser
   │
   │ POST /api/orders
   ▼
Server

🤔 ليه الـBrowser يعمل Preflight؟

لأن بعض cross-origin requests تحتاج أن الـbrowser يتأكد من policy قبل إرسال الـactual request.

أمثلة شائعة تؤدي إلى preflight:

• PUT
• PATCH
• DELETE
• Authorization header
• Custom request headers
• Content-Type: application/json في الحالات التي لا تكون CORS-safelisted

مش مجرد إن method هي PUT أو DELETE لوحدها؛ الـbrowser ينظر إلى مجموعة من خصائص الـrequest.

📡 شكل الـPreflight

مثال:

OPTIONS /api/orders HTTP/1.1
Host: api.example.com
Origin: https://frontend.example.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: authorization, content-type

السيرفر ممكن يرد:

HTTP/1.1 204 No Content

Access-Control-Allow-Origin: https://frontend.example.com
Access-Control-Allow-Methods: POST
Access-Control-Allow-Headers: Authorization, Content-Type
Access-Control-Max-Age: 600

بعدها:

POST /api/orders
Authorization: Bearer ...
Content-Type: application/json
Origin: https://frontend.example.com

MDN تعرض هذا الـflow تحديدًا: preflight OPTIONS يعلن الـmethod والـheaders المقصودة، ثم إذا كانت السياسة تسمح يتم إرسال الطلب الفعلي. urlMDN — CORS Preflighthttps://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS

🟢 Simple Requests

مش كل cross-origin request يعمل Preflight.

فيه Requests تستوفي شروط CORS-safelisted / simple request behavior، مثل بعض:

GET
HEAD
POST

لكن لازم الطلب يلتزم بقيود معينة على:

• Method
• Headers
• Content-Type
• Header values

مثال:

POST /api/contact
Content-Type: application/x-www-form-urlencoded

قد يكون قادرًا على الذهاب بدون preflight.

لكن:

POST /api/orders
Authorization: Bearer ...
Content-Type: application/json

غالبًا يحتاج preflight.

Simple ≠ "CORS doesn't apply".

حتى لو مفيش preflight، الـresponse ما زال يخضع لقواعد CORS قبل أن يستطيع JavaScript قراءته.

🍪 Credentials و Cookies

هنا الموضوع يصبح أكثر حساسية.

لو الـfrontend يستخدم cookies:

fetch("https://api.example.com/profile", {
  credentials: "include"
});

الـserver قد يحتاج:

Access-Control-Allow-Credentials: true

وفي نفس الوقت لا يمكن استخدام:

Access-Control-Allow-Origin: *

مع credentialed CORS request.

لازم تحدد origin صراحة:

Access-Control-Allow-Origin: https://frontend.example.com
Access-Control-Allow-Credentials: true

MDN توضح أن credentialed CORS responses لا يمكنها استخدام * كقيمة لـAccess-Control-Allow-Origin. urlMDN — CORS Credentialshttps://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS

⭐ Access-Control-Allow-Origin: *

دي من أكتر الحاجات اللي developers بيعملوها أثناء development:

Access-Control-Allow-Origin: *

وده ممكن يكون صحيح لو الـAPI public وغير credentialed.

مثال:

Public CDN-style API
      ↓
Anyone can read

لكن لو عندك:

Cookies
Sessions
Credentials
Private user data

مينفعش تستخدم * كبديل عن allowlist.

مثال أفضل:

Access-Control-Allow-Origin: https://frontend.example.com

وإذا كنت تستخدم credentials:

Access-Control-Allow-Credentials: true

MDN توصي باستخدام origin محدد عند الحاجة إلى credentialed access، وعدم استخدام wildcard في هذه الحالة. urlMDN — CORS Configurationhttps://developer.mozilla.org/en-US/docs/Web/Security/Practical_implementation_guides/CORS

🔐 CORS مش Authentication

دي نقطة مهمة جدًا:

CORS
≠
Authentication

CORS لا يقول:

"المستخدم ده مسموح له يدخل الـAPI."

هو يقول بشكل أساسي:

"هل الـbrowser يسمح للJavaScript من origin معين بقراءة الـresponse؟"

Authentication يقول:

Who are you?

Authorization يقول:

What are you allowed to do?

CORS يقول:

Can this browser context share/read this cross-origin response?

🛡️ CORS مش CSRF Protection

دي نقطة مهمة جدًا خصوصًا لو بتستخدم cookies.

CORS
↓
Controls cross-origin browser access to responses

CSRF protection
↓
Protects state-changing actions from unwanted cross-site requests

مثال:

Attacker Website
       ↓
Browser
       ↓
POST /transfer
       ↓
Bank

لو الـbank يعتمد على cookies، لازم CSRF defenses مناسبة.

ما تعتمدش على CORS وحده كـCSRF protection.

🔀 CORS vs Same-Origin Policy

الصورة:

Same-Origin Policy
        │
        │ Default restriction
        ▼
Cross-Origin Request
        │
        ▼
       CORS
        │
   ┌────┴────┐
   │         │
 Allowed   Blocked

⏱️ Preflight Caching

ممكن الـbrowser يعمل:

OPTIONS /api/orders

مرة، وبعدها يخزن نتيجة الـpreflight لفترة.

السيرفر يقدر يرسل:

Access-Control-Max-Age: 600

يعني:

Preflight result
      ↓
Cache
      ↓
10 minutes

وده يقلل:

OPTIONS
OPTIONS
OPTIONS
OPTIONS

ويحسن الأداء.

لكن الـbrowser ممكن يفرض maximum داخلي أقل من القيمة التي يرسلها السيرفر. MDN توضح أن Access-Control-Max-Age يحدد مدة cache لنتيجة الـpreflight مع وجود حدود داخلية في بعض المتصفحات. urlMDN — Access-Control-Max-Agehttps://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Access-Control-Max-Age

📦 Vary: Origin

لو السيرفر يغير الـresponse حسب الـOrigin:

frontend-a.com → allowed
frontend-b.com → denied

فـcaches الموجودة بين العميل والسيرفر لازم تكون واعية أن الـOrigin جزء من variation.

غالبًا:

Vary: Origin

يكون مهمًا عندما تكون Access-Control-Allow-Origin ديناميكية.

MDN تعرض Vary: Origin ضمن أمثلة CORS، وهو مهم خصوصًا عندما تختلف الـresponses حسب الـOrigin. urlMDN — CORShttps://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS

🧩 Backend Configuration

مثال Express

import cors from "cors";

app.use(
  cors({
    origin: "https://frontend.example.com",
    credentials: true,
    methods: ["GET", "POST", "PUT", "PATCH", "DELETE"],
    allowedHeaders: ["Content-Type", "Authorization"],
  })
);

لكن في Production لا تعمل:

origin: "*"

بشكل أعمى، خصوصًا لو الـAPI تستخدم credentials.

🔒 Dynamic Origin Allowlist

لو عندك أكثر من Frontend:

const allowedOrigins = [
  "https://app.example.com",
  "https://admin.example.com",
];

const corsOptions = {
  origin(origin, callback) {
    if (!origin || allowedOrigins.includes(origin)) {
      callback(null, true);
      return;
    }

    callback(new Error("Origin not allowed"));
  },
};

الفكرة:

Incoming Origin
      ↓
Allowlist
   /       \
Allowed   Denied
   ↓         ↓
CORS OK   CORS Error

لا تعمل reflection عشوائي لأي Origin يرسله العميل، خصوصًا مع credentials.

🧪 Development vs Production

أثناء development:

Frontend
http://localhost:3000

Backend
http://localhost:5000

ممكن تعمل allowlist:

http://localhost:3000

وفي Production:

https://app.example.com

بدل:

Access-Control-Allow-Origin: *

خلي الـconfig environment-specific:

Development
→ localhost origins

Staging
→ staging frontend

Production
→ production frontend

🔄 Reverse Proxy وSame-Origin Architecture

أحيانًا أفضل حل ليس فتح CORS بشكل واسع.

ممكن تخلي الـbrowser يتعامل مع:

https://app.example.com

والـreverse proxy يوجه:

/app
/api

إلى services مختلفة.

مثال:

                    Browser
                       │
                       ▼
              https://app.example.com
                       │
                 ┌─────┴─────┐
                 ▼           ▼
              /app          /api
                 │           │
                 ▼           ▼
            Frontend      Backend

من منظور الـbrowser، ممكن يكون الـAPI والواجهة تحت نفس origin:

https://app.example.com
https://app.example.com/api

وده يقلل CORS complexity في بعض architectures.

🧯 Common CORS Errors

1. Missing Access-Control-Allow-Origin

No 'Access-Control-Allow-Origin'
header is present...

الحل:

Access-Control-Allow-Origin: https://frontend.example.com

2. Method Not Allowed

Preflight:

Access-Control-Request-Method: PATCH

لكن السيرفر:

Access-Control-Allow-Methods: GET, POST

❌ PATCH غير مسموح.

3. Header Not Allowed

الـbrowser يقول:

Access-Control-Request-Headers: authorization

والسيرفر لا يسمح:

Access-Control-Allow-Headers

❌

الحل:

Access-Control-Allow-Headers: Authorization

4. Credentials + *

مثلاً:

Access-Control-Allow-Origin: *
Access-Control-Allow-Credentials: true

❌ غير صحيح لهذا السيناريو.

استخدم origin محدد.

5. OPTIONS يرجع 404

OPTIONS /api/orders
        ↓
404

الـbackend أو proxy لم يتعامل مع preflight بشكل صحيح.

لازم تتأكد من:

• CORS middleware
• Routing
• Reverse proxy
• Gateway
• Load balancer
• Firewall

6. CORS Error رغم 200 OK

ممكن تشوف:

POST /api/orders
200 OK

لكن JavaScript يقول:

CORS error

لأن:

Server response
      ↓
Browser checks CORS
      ↓
Not allowed
      ↓
JS cannot access response

وده سبب مشهور جدًا للـconfusion.

🧠 Debugging CORS

لما تشوف CORS error:

1. افتح Network

ابحث عن:

OPTIONS

لو موجود:

OPTIONS
 ↓
Status?
 ↓
Response Headers?

2. راجع Request Headers

Origin
Access-Control-Request-Method
Access-Control-Request-Headers

3. راجع Response Headers

Access-Control-Allow-Origin
Access-Control-Allow-Methods
Access-Control-Allow-Headers
Access-Control-Allow-Credentials
Access-Control-Max-Age
Vary

4. اسأل السؤال الصحيح

مش:

"ليه API بتدي CORS error؟"

لكن:

"هل الـbrowser سمح للfrontend بقراءة الـresponse؟ وهل الـpreflight policy تطابق الـactual request؟"

🏗️ CORS Flow كامل

sequenceDiagram
    participant B as Browser
    participant F as Frontend
    participant API as API Server

    F->>B: fetch(https://api.example.com/orders)

    B->>API: OPTIONS /orders
    Note right of B: Origin: https://app.example.com<br/>Request-Method: POST<br/>Request-Headers: Authorization, Content-Type

    API-->>B: 204 No Content
    Note left of API: Allow-Origin: https://app.example.com<br/>Allow-Methods: POST<br/>Allow-Headers: Authorization, Content-Type

    B->>API: POST /orders
    API-->>B: 201 Created

    B-->>F: Response available to JS

🚫 ماذا يحدث عند الرفض؟

sequenceDiagram
    participant B as Browser
    participant F as Frontend
    participant API as API Server

    F->>B: fetch cross-origin
    B->>API: OPTIONS /orders
    API-->>B: CORS policy does not allow origin
    B-->>F: Browser blocks access

النقطة المهمة:

CORS decision
      ↓
Browser enforcement
      ↓
JavaScript access

🔐 CORS + Authentication

لو عندك:

Frontend
https://app.example.com

API
https://api.example.com

وAuthentication باستخدام cookie:

fetch("https://api.example.com/me", {
  credentials: "include",
});

لازم الـserver والـcookie policy يكونوا متوافقين:

CORS
+
Cookie SameSite
+
Secure
+
CSRF protection
+
HTTPS

مش مجرد:

Access-Control-Allow-Origin

🧱 Production Checklist

CORS

• افهم الـOrigin الحقيقي للـFrontend
• لا تستخدم * بشكل أعمى
• استخدم explicit allowlist في الـproduction
• اسمح بالـmethods المطلوبة فقط
• اسمح بالـheaders المطلوبة فقط
• تعامل مع OPTIONS
• راجع Access-Control-Allow-Credentials
• استخدم Access-Control-Max-Age عند الحاجة
• أضف Vary: Origin عند dynamic origin responses
• اختبر الـpreflight
• اختبر الـactual request
• اختبر credentialed requests
• اختبر denied origins

Security

• لا تعتمد على CORS كـauthentication
• لا تعتمد على CORS كـCSRF protection
• استخدم HTTPS
• راجع Cookie SameSite
• راجع Cookie Secure
• راجع HttpOnly عند استخدام cookies
• طبق authorization على الـAPI نفسها
• لا تثق في Origin كبديل عن authentication/authorization

Performance

• راقب عدد الـpreflight requests
• استخدم Access-Control-Max-Age عندما يناسب الـarchitecture
• تجنب custom headers غير الضرورية
• قلل cross-origin calls عند الإمكان
• استخدم same-origin reverse proxy architecture عندما يكون مناسبًا

❌ Common Misconceptions

"OPTIONS request دي من الـFrontend"

مش بالضرورة.

الـbrowser نفسه ممكن ينشئ الـpreflight.

"كل POST يعمل OPTIONS"

لا.

الـpreflight يعتمد على خصائص الـrequest، وليس method وحدها.

"GET عمره ما يعمل Preflight"

مش قاعدة عامة بهذا الشكل.

الـpreflight يعتمد على request characteristics؛ الـsimple/safelisted behavior له شروط محددة.

"CORS يمنع السيرفر من تنفيذ الطلب"

ليس بالضرورة.

في بعض السيناريوهات، الـactual request قد يصل للسيرفر، لكن الـbrowser يمنع JavaScript من قراءة الـresponse.

"CORS يحمي الـAPI من Postman"

لا.

Postman وغيره ليسوا خاضعين لنفس browser CORS enforcement.

CORS أساسًا browser security mechanism.

"لو حطيت Access-Control-Allow-Origin: * يبقى API public وآمنة"

لا.

أنت فقط سمحت للـbrowser بمشاركة responses مع أي origin في السيناريوهات التي ينطبق عليها wildcard.

Authentication وAuthorization شيء آخر.

"CORS وCSRF نفس الحاجة"

لا.

CORS
→ Cross-origin response sharing policy

CSRF
→ Unwanted state-changing requests

🧭 الصورة الكبيرة

                   WEB SECURITY
                        │
          ┌─────────────┴─────────────┐
          ▼                           ▼
 Same-Origin Policy                Other Controls
          │                           │
          ▼                           ├── CSP
        CORS                          ├── CSRF defenses
          │                           ├── Cookies
          │                           ├── HTTPS
          │                           └── Authentication
          ▼
 Cross-Origin Access

CORS جزء من منظومة أكبر.

مش الـsecurity system كله.

🎯 الخلاصة

الـBrowser مش "بيعمل request زيادة من نفسه" بدون سبب.

هو بيطبق security policy.

لما يشوف cross-origin request يحتاج preflight:

OPTIONS
   ↓
"هل مسموح لي أبعت الطلب ده؟"
   ↓
Server responds with CORS policy
   ↓
Browser decides
   ↓
Actual request

والـOrigin بيتحدد بواسطة:

Scheme
+
Host
+
Port

والـCORS headers تحدد مثلًا:

Allowed Origin
Allowed Methods
Allowed Headers
Credentials
Preflight Cache

لكن أهم 4 حاجات تفتكرهم:

1. CORS ≠ Authentication

2. CORS ≠ CSRF Protection

3. Preflight ≠ Actual Request

4. CORS is primarily enforced by the Browser

وفي الـproduction:

متتعاملش مع CORS كـ"error عايز أسكته".

تعامل معاه كجزء من:

Browser Security
+
API Architecture
+
Authentication
+
CSRF Model
+
Performance

وساعتها لما تشوف:

OPTIONS /api/orders

مش هتقول:

"مين طلب منك تعمل كده؟" 😂

هتقول:

"آه، الـBrowser بيعمل Preflight عشان يتأكد إن الـCORS policy تسمح بالـrequest."

📚 Further Reading

• MDN — CORS
• MDN — Same-Origin Policy
• MDN — Origin
• MDN — CORS Configuration
• MDN — Access-Control-Max-Age
• Fetch Standard — CORS Protocol

🌐 CORS is not a random browser error.

It's the browser enforcing a security boundary.