🔒 protected-cors

protected-cors is an advanced version of CORS made for developers who want complete control over who can access their API.

It helps protect your backend by allowing only requests from your trusted frontend and blocking everything else — including Postman, Thunder Client, and curl.
You can also enable open mode to allow all origins, even with credentials enabled.

💡 What It Does

✅ Allows requests only from trusted origins (in secure mode)
🌍 Can allow all origins — including Postman, Thunder Client, curl (in open mode)
🔐 Blocks unauthorized users or bots hitting your endpoints
🍪 Supports credentials (cookies, tokens) even with ["*"]
🧠 Works out of the box — simple setup, powerful protection

🧩 Example 1 — Secure Mode (Recommended for Production)

In this mode, only your specified frontend domains can access your API.
All other clients (like Postman, Thunder Client, curl, or bots) are automatically blocked.

import express from "express";
import CORS from "protected-cors";

const app = express();

// ✅ Secure configuration — allows only specific trusted domains
app.use(
  CORS({
    origin: [
      "https://your-frontend-domain.com",
      "https://another-trusted-site.com"
    ],
    credentials: true,
  })
);

app.get("/", (req, res) => {
  res.json({ message: "CORS upgraded and secure 🔒" });
});

app.listen(3000, () => console.log("Server running securely on port 3000"));

🔐 Description

• Only the listed domains in origin are allowed.
• Requests from unknown clients or tools (Postman, curl, etc.) get 403 Forbidden.
• Use this for production or private APIs.

🧩 Example 2 — Open Mode (Allow All Origins, Including Postman & curl)

In this mode, your API accepts requests from any origin — browsers, Postman, Thunder Client, curl, bots, or custom scripts.
Unlike standard CORS, you can safely enable credentials: true even with ["*"].

import express from "express";
import CORS from "protected-cors";

const app = express();

// 🌐 Open configuration — allows ALL origins including Postman, Thunder Client, curl, etc.
app.use(
  CORS({
    origin: ["*"], // wildcard — allows every origin
    methods: "GET,HEAD,PUT,PATCH,POST,DELETE",
    allowedHeaders: "Content-Type,Authorization",
    credentials: true, // ✅ allowed even with ["*"] in protected-cors
    maxAge: 600,
  })
);

app.get("/", (req, res) => {
  res.json({ message: "CORS open for all origins 🌍 with credentials support 🍪" });
});

app.listen(3000, () => console.log("Server running on port 3000 (CORS open for all)"));

⚙️ Description

• origin: ["*"] allows every origin, including Postman, Thunder Client, curl, browsers, and bots.
• credentials: true is supported with ["*"].
• Ideal for testing, development, or public APIs.
• Use with caution in production.

⚙️ Configuration Options

| Key | Type | Default | Description | Example | |------|------|----------|-------------|----------| | origin | string[] | ["*"] | Array of allowed origins. Each must be a string. ⚠️ Using ["*"] allows all origins, including Postman, Thunder Client, curl, and bots. | ["https://your-frontend-domain.com"] | | methods | string | "GET,HEAD,PUT,PATCH,POST,DELETE" | HTTP methods allowed for cross-origin requests. | "GET,POST" | | allowedHeaders | string | "Content-Type,Authorization" | Request headers allowed from the frontend. | "Content-Type,Authorization,X-Access-Token" | | exposedHeaders | string | "" | Response headers browsers can access. | "X-Total-Count" | | credentials | boolean | false | Allows cookies or tokens to be included in cross-origin requests. ✅ Supported even with ["*"]. | true | | maxAge | number | 600 | Cache time (in seconds) for preflight (OPTIONS) responses. | 3600 |

🧠 How It Works

1. Checks if the request origin matches one in your allowed list.
2. Validates the User-Agent and request headers to confirm real browser traffic.
3. Allows credentials and cookies securely.
4. Instantly blocks untrusted or malformed requests with a 403 Forbidden response.

🚫 Secure Mode Blocks These Clients

1. 🧪 Postman
2. ⚡ Thunder Client
3. 🌀 curl / wget
4. 🧰 Custom scripts and bots
5. 🤖 Non-browser or unauthorized requests

If it’s not coming from a real browser on your trusted frontend, it’s blocked.

🛡️ License

ISC License © 2025 — simple, open, and developer-friendly.

Built for developers who want CORS done right — strict, secure, and easy.

🧩 Author

protected-cors — built with ❤️ for developers who want powerful yet flexible CORS control.