docs
  1. Features
  2. Platform
  3. Security Headers

Security Headers

The Storefront Application V3 sends a set of security headers with the pages and API responses it renders. The headers tell the browser to use HTTPS, to refuse framing, to share less referrer data, and to report every script, style, or connection that falls outside a Content-Security-Policy. The policy ships report-only. Violations are reported and nothing is blocked until you decide to enforce it.

Why it matters

Browsers apply these headers on every page load, so they protect your users in places your own code cannot reach: a page that another site frames to trick a click, a script from an origin you never approved, a file the browser guesses the type of.

A Content-Security-Policy that blocks from the first request would break a live shop. The checkout web component bundles payment provider SDKs, and tags that you load through Google Tag Manager pull in further origins. Neither list can be read from the code, so only reports from a real environment can complete it. That is why the policy starts report-only. The browser tells you what it would block, you add the missing origins, and you enforce one directive at a time.

Framing is the exception. It is enforced from the first request, because clickjacking protection cannot wait for a rollout. The CMS editor can still frame your shop in a preview session, and nothing else can.

Try it

Try it: read the security headers of your own storefront

Run this against a page of a deployed storefront. Replace <your-storefront-url>/<country-path> with the URL of a page, including its country prefix and without a trailing slash. With the default path country selector, a request without the prefix gets a redirect that the runtime answers itself, and that response carries only x-content-type-options.

The output lists the headers from the table below. Header names can appear in lowercase. reporting-endpoints is missing until you set a report URI.

What's included

The table lists what a page response carries with the defaults. The Mode column says whether the browser enforces the header or only reports.

HeaderValueModeWhy
Strict-Transport-Securitymax-age=31536000; includeSubDomainsEnforcedMakes the browser use HTTPS for one year, for the host and its subdomains.
X-Content-Type-OptionsnosniffEnforcedStops the browser from guessing a file type.
Referrer-Policystrict-origin-when-cross-originEnforcedSends only your origin, not the full URL, to other sites.
X-Frame-OptionsDENYEnforcedRefuses framing by any site.
Content-Security-Policyframe-ancestors 'none', plus any directive you list in enforcedDirectivesEnforcedRefuses framing, and holds the directives you have moved out of report-only.
Content-Security-Policy-Report-Onlythe rest of the policyReports onlyShows what enforcing would block.
Permissions-Policycamera, microphone, geolocation, and USB denied. payment allowed for your origin and the Checkout originEnforcedKeeps those browser features off. payment stays on because express checkout needs the Payment Request API.
Cross-Origin-Opener-Policysame-origin-allow-popupsEnforcedKeeps window.opener alive for the PayPal and Klarna popup flows.
Cross-Origin-Resource-Policycross-originEnforcedKeeps responses embeddable, which the CMS editor preview needs.
Reporting-Endpointsyour report URIOnly with a report URITells browsers that support the Reporting API where to send violation reports.

The same call also sends Origin-Agent-Cluster, X-DNS-Prefetch-Control, X-Download-Options, X-Permitted-Cross-Domain-Policies, and X-XSS-Protection with the values Hono's secureHeaders middleware uses by default.

  • Report-only policy: The report-only header holds the full policy, from default-src 'self' to the allowed origins of the checkout web component, Google Tag Manager, Google Analytics, and Usercentrics. See the shipped policy.
  • Violation reports: With a report URI set, both CSP headers send violations to your collector, so a directive you enforce later keeps reporting.
  • Per-country origins: The add-on origin for subscriptions appears in script-src and connect-src only on requests for a country that sets subscriptionEnabled.
  • Content type protection for static assets: A separate middleware sets X-Content-Type-Options on the static files the application serves itself, because those responses carry no other header from this page.

What you can change

Configure

  • Set STOREFRONT_CSP_REPORT_URI to a collector that accepts CSP reports. See Collect violation reports.
  • Set STOREFRONT_COUNTRIES_<COUNTRY_CODE>_SUBSCRIPTION_ENABLED to true for a country to add the subscription add-on origin to its policy. Each country entry in storefront.config.ts reads its own variable.

Extend

Replace

  • Remove app.use(securityHeadersMiddleware) from src/server/index.ts and send the headers from your own middleware or from a proxy. You then own every header in the table, including the framing protection that the CMS preview middleware relies on. nosniffMiddleware is a separate registration and stays.

Constraints and limits

Permanent

  • A report-only policy blocks nothing. The browser logs a violation in the console of the user and sends a report to your collector when you set one. The page works as before.
  • Framing is enforced even though the rest of the policy is not. frameAncestors goes into the enforcing header whether or not you list it in enforcedDirectives. The CMS preview middleware removes X-Frame-Options on a preview request and needs an enforced frame-ancestors to take over.
  • X-Frame-Options and frame-ancestors apply only to nested browsing contexts. A native app WebView that loads your storefront as its top-level document is not framed, so neither header affects it.
  • The health probe carries none of these headers, because it is registered before every other middleware. Responses that the runtime answers itself carry only X-Content-Type-Options, because they are sent before securityHeadersMiddleware runs. That covers trailing-slash redirects, the redirect that adds the country prefix with the path country selector, and the sitemap and robots.txt responses. Static files the application serves itself carry only X-Content-Type-Options too.
  • A request that resolves no country gets the policy without the subscription origins. This covers an /api request without an x-shop-country-id header, and a host that no country matches when you use the domain country selector. No subscription component renders without a country.
  • Permissions-Policy has no report-only stage. A change to it takes effect right away.

Known limitations

  • The report-only policy is incomplete on purpose. The checkout web component bundles the SDKs of Adyen, Klarna, PayPal, and further payment providers, and loads the ones your enabled payment methods need. Only the Klarna SDK host is listed, because express checkout loads it on page view. Expect the other hosts in your first reports. Some payment SDKs also render frames, so reports can name frame-src as well as script-src.
  • Tags that Google Tag Manager loads add origins that the code cannot list. They also show up in your first reports.
  • The consent banner and the checkout web component inject inline <style> blocks. These reports name no origin to add. The Storefront Application V3 does not generate nonces. To enforce style-src, add a nonce or hash of your own, or accept 'unsafe-inline' on styleSrc.
  • The structured data that src/client/components/meta/PageMetaHead.vue renders is an inline <script type="application/ld+json"> block. A JSON-LD block is data that the browser does not execute, so script-src does not apply to it and it needs no nonce. The default scriptSrc has no 'unsafe-inline', nonce, or hash source.
  • The stylesheet of the checkout web component imports the Inter font from Google Fonts. The report names style-src. https://fonts.googleapis.com is left out on purpose, because the storefront self-hosts Inter. Enforcing styleSrc blocks that import.
  • imgSrc and mediaSrc allow any HTTPS origin. CMS media hosts differ per provider and per shop, and images cannot execute, so this keeps the policy usable without weakening the script controls. The report-only policy therefore never reports an image or video origin.

Pitfalls

  • A directive you enforce blocks every origin it does not list. Enforce it before its reports are clean and the missing origin stops working.
  • Redirect-based payment flows such as 3-D Secure and Klarna post a form to another origin. form-action 'self' blocks that post once you enforce formAction. Add the origins that your reports name before you enforce it.
  • Replace payment in Permissions-Policy with a bare payment=() and the express checkout buttons disappear without any report.
  • Change xFrameOptions and frameAncestors together when you allow framing. Change only xFrameOptions and frame-ancestors 'none' still blocks every frame. Change only frameAncestors and a browser without frame-ancestors support still obeys DENY. See Let a partner page or app shell frame your storefront.
  • Register securityHeadersMiddleware before cmsCspMiddleware and the CMS editor iframe stops loading. See How it works.

How it works

The Storefront Application V3 registers the middlewares in src/server/index.ts. The health probe, nosniffMiddleware, static asset serving, and createStorefrontRuntime come first, see Request Lifecycle. The two middlewares that decide the headers come after it, in this registration order:

  1. cmsCspMiddleware in src/server/cms/middleware/csp.ts. It adjusts the CSP headers on CMS preview requests.
  2. securityHeadersMiddleware in src/server/middleware/securityHeaders.ts. It sets the baseline headers.

Both cmsCspMiddleware and securityHeadersMiddleware write headers after the page is produced. Hono unwinds that step in reverse registration order, so the middleware registered last writes first. The baseline therefore writes its headers, and then the CMS middleware changes them. Swap the two and the baseline overwrites the CMS changes.

securityHeadersMiddleware builds the policy on every request from your config and the country of the request. It declares the policy once, as a plain object. buildContentSecurityPolicyOptions from @scayle/storefront splits that object into two headers. A directive you list in enforcedDirectives goes to Content-Security-Policy, and frameAncestors always does. Every other directive goes to Content-Security-Policy-Report-Only. When you set a report URI, the function also adds the reporting directives to both headers. In pnpm dev, it appends the sources Vite needs to script-src, style-src, and connect-src. A production build does not carry them.

Your policy object goes to buildContentSecurityPolicyOptions, which makes an enforcing header with frame-ancestors and a report-only header with the other directives. cmsCspMiddleware adjusts CMS preview requests before the response.

CMS preview requests

Each CMS provider decides from the request whether it is a preview request. For the CMS vendor providers, that is a query parameter that the editor of the vendor adds to the preview URL. The default scayle provider never reports a preview request. On a preview request, cmsCspMiddleware merges the cspConfig of the provider into every CSP header on the response. How a provider detects a preview request is described on the CMS page, and each provider page lists the origins it adds: Contentful, Contentstack, Storyblok, and Amplience.

  • Framing: A frame-ancestors value in cspConfig replaces the baseline 'none' outright, because 'none' cannot be widened by adding an origin. The editor origin and 'self' can then frame the page. The middleware also removes X-Frame-Options, because a browser without frame-ancestors support would otherwise keep obeying DENY.
  • No framing value: A cspConfig without frame-ancestors leaves X-Frame-Options in place. Anyone can append the preview parameter to a URL, so removing the header without a replacement would remove the protection for every request.
  • Other directives: Directives such as script-src and connect-src add their origins to a header only when it declares that directive or default-src. With the default enforcedDirectives, the enforcing header holds only frame-ancestors, so it stays framing-only and the report-only header receives the origins. Once you enforce a directive, preview requests add the provider origins to it in the enforcing header.
  • Inline scripts: The Contentful, Contentstack, and Storyblok configs add 'unsafe-inline' to script-src, because Inertia injects inline scripts for the page data. An enforced script-src therefore allows inline scripts during a preview session.
  • No provider values: A provider with no directives, such as the default scayle provider, leaves the response as the baseline wrote it.
  • Change the origins: Override the cspConfig property on your own subclass of the CMS provider service in src/server/cms/providers/<provider>/service.ts. cmsCspMiddleware reads the property from the service instance that createCMSService returns. Where createCMSService creates the package class directly, return your subclass instead. The export { cspConfig } line in that file does not reach the middleware, so a changed copy there has no effect.

Setup

Collect violation reports

Without a collector, violations appear only in the browser console of your users, where nobody reads them. You cannot finish the rollout without reports, so set a collector first.

  1. Choose an endpoint that accepts CSP reports. You run it or use a reporting service.
  2. Set STOREFRONT_CSP_REPORT_URI to its URL in a production-like environment.
  3. Restart the server.
  4. Load a page and read the response headers as in Try it.

When it worked, the response carries a Reporting-Endpoints header with csp-endpoint="<your URL>". Both CSP headers carry report-to csp-endpoint and report-uri <your URL>. Browsers that support the Reporting API use report-to. MDN marks report-uri as deprecated, but older browser versions only understand it, so both are sent. Without it, you would tune the policy on the traffic of newer browsers alone.

Configuration

Environment variables

VariablePurposeDefaultChange needs
STOREFRONT_CSP_REPORT_URIThe collector that CSP violation reports go to.Unset, reports reach the browser console onlyRestart

Each country entry in storefront.config.ts that reads STOREFRONT_COUNTRIES_<COUNTRY_CODE>_SUBSCRIPTION_ENABLED sets subscriptionEnabled for that country. The value true, in any letter case, adds the subscription add-on origin to the policy for requests of that country. Any other value leaves it out.

See Environment Variables for every variable.

Settings in the security headers file

You edit these in src/server/middleware/securityHeaders.ts.

SettingWhat it does
policy, passed to buildContentSecurityPolicyOptionsThe full policy as one object. Each key is a camelCase directive name such as scriptSrc, with an array of sources.
enforcedDirectivesThe directives that move from the report-only header to the enforcing one. The shipped value is an empty array.
strictTransportSecurityThe HSTS value. It has no preload flag, because preloading commits every subdomain to HTTPS and is slow to undo. Whoever owns the domain makes that call.
xFrameOptions and policy.frameAncestorsThe two framing controls. Change them together.
permissionsPolicyThe browser features the page may use. payment lists your origin and the Checkout origin.

Browsers ignore Strict-Transport-Security over plain HTTP, so local development on http://localhost is not affected.

The shipped policy

The Checkout origin is https://<tenantSpace>.checkout.api.scayle.cloud, built from tenantSpace in your config. The subscription origin is https://<tenantSpace>-subscription.addon.scayle.cloud, and it appears only for a country that sets subscriptionEnabled.

DirectiveAllows
defaultSrc, baseUri, formAction'self'
objectSrc'none'
frameAncestors'none', enforced from the start
scriptSrc'self', the Checkout origin, the checkout CDN, the Klarna SDK host, the subscription origin, Google Tag Manager, and the Usercentrics loader
connectSrc'self', the Checkout origin, the checkout CDN, the subscription origin, Google Tag Manager, Google Analytics hosts, and the Usercentrics API hosts
styleSrc'self' and the checkout CDN
styleSrcAttr'unsafe-inline', for the style attributes that Vue :style bindings produce. A nonce cannot apply to an attribute.
imgSrc'self', data:, and any HTTPS origin
mediaSrc'self' and any HTTPS origin
fontSrc'self', because Inter is self-hosted
frameSrc'self'. The checkout web component and the subscription components are custom elements in your document, not frames.
workerSrc'self' and blob:

Customization guides

Allow a third-party origin

Every origin the storefront loads from has to be in the matching directive before you enforce it. The policy has no environment variable for extra origins, so you add them in code. You end up with a directive that lists your origin, and a report-only policy that stays quiet about it.

  1. Open src/server/middleware/securityHeaders.ts.
  2. Add the origin to each directive its use needs. A script loaded from another host goes into scriptSrc. A call with fetch, XMLHttpRequest, sendBeacon, or a websocket goes into connectSrc. An iframe goes into frameSrc. A webfont goes into fontSrc. A form that posts to another origin goes into formAction.
  3. Keep origins in named constants when the origin appears in more than one directive.

When it worked, loading a page that uses the widget produces no report for that origin. If you use a consent provider other than Usercentrics, add its hosts the same way. See Consent Management.

Enforce the policy

You end up with the directive in the Content-Security-Policy header and out of the report-only one.

  1. Collect violation reports in a production-like environment.
  2. Run real traffic through it. Include checkout, express checkout, a CMS preview session, and every page that renders a third-party widget.
  3. Add the origins your reports name to the matching directives, as in Allow a third-party origin. Add payment provider hosts to scriptSrc, frameSrc, connectSrc, and formAction as your reports require.
  4. Repeat steps 2 and 3 until reports for a directive stop arriving.
  5. List that directive in enforcedDirectives with its camelCase name.
  6. Update the tests in src/server/middleware/securityHeaders.test.ts that read the moved directive from the report-only header. The test that asserts the enforcing header holds only frame-ancestors fails too.
  7. Deploy and watch for breakage. The browser blocks any origin you missed.

When it worked, content-security-policy lists script-src and connect-src next to frame-ancestors, and content-security-policy-report-only does not list them. When every directive is enforced, the report-only header disappears. The reporting directives stay on the enforcing header, so a blocked request still reaches your collector.

Keep styleSrcAttr: ["'unsafe-inline'"] when you enforce styles. Vue :style bindings in components such as SFProgressBar and SFRangeSlider produce style attributes, and a nonce cannot cover an attribute. Inline <style> blocks stay under the stricter styleSrc.

Let a partner page or app shell frame your storefront

You only need this when something embeds your storefront in a real iframe, such as an app shell or a partner page. A native app WebView that loads the storefront as its top-level document is not framed and needs no change. You end up with your storefront framable by the origins you name and by no one else.

  1. Open src/server/middleware/securityHeaders.ts.
  2. Set xFrameOptions to false. Do not delete the line. Without it, Hono's default sends X-Frame-Options: SAMEORIGIN. Browsers that support frame-ancestors ignore it, but browsers without that support still block other origins.
  3. Set frameAncestors in policy to 'self' plus the origins that may embed you.

When it worked, the response has no x-frame-options header and content-security-policy holds frame-ancestors 'self' https://app.example.com.

Name the embedding origins. A frame-ancestors * value lets every site on the web frame your storefront.

Best practices

Enforce one directive at a time

Each enforced directive blocks every origin it does not list. One directive per release shows which change caused a break, and you can move it back by removing it from enforcedDirectives.

Troubleshooting

The CMS editor shows a blank frame

Issue: The preview opens in the CMS editor, and the frame stays empty.

Possible causes: A proxy or CDN in front of the shop sets its own Content-Security-Policy or X-Frame-Options header. The request lacks the preview query parameter of your provider.

Solution:

  1. Request the preview URL, including the query parameter, and read the response headers.
  2. Check that content-security-policy holds a frame-ancestors value that names the editor origin, and that no x-frame-options header remains.
  3. Request the same URL directly from the application, bypassing the proxy, and compare the headers.
  4. If the headers differ, change the proxy or CDN rule.

Prevention: Check the response headers of a preview URL after each change to the proxy or CDN rules.

No violation reports arrive at my collector

Issue: You set a report URI, and the collector receives nothing.

Possible causes: The process did not restart after you set STOREFRONT_CSP_REPORT_URI. No violation happens, because the pages you loaded stay inside the policy. The collector rejects the reports.

Solution:

  1. Read the response headers. Look for a reporting-endpoints header and a report-uri directive in content-security-policy-report-only.
  2. If both are missing, check that the variable is set in the environment of the running process and restart.
  3. Load a page that uses a third-party widget you have not listed. A report for it shows that the path works.
  4. Check the logs of the collector for rejected requests.

Prevention: Test the collector with one known violation after each deployment that changes the policy.

Reference

Architecture

External resources