Security

Web Elements are built on a security-first architecture. Every card number, CVV, and expiration date is captured inside a secure iframe hosted on Basis Theory's domain -- your application never handles raw card data. This page describes the additional protections that ship with the SDK.

---

Content Security Policy (CSP)

How element iframes are protected

Every element iframe ships with a strict, hash-based Content Security Policy baked in at build time. This is a <meta> tag inside the iframe HTML -- not an HTTP header -- so it cannot be stripped by a proxy or CDN misconfiguration.

The policy follows a deny-by-default model:

default-src 'none';
script-src 'sha384-<hash>';
style-src 'unsafe-inline';

Directive	Purpose
default-src 'none'	Blocks everything not explicitly allowed -- no images, fonts, frames, or outbound connections.
script-src 'sha384-...'	Allows only the exact inline script produced by the build. If even one byte is modified, the browser refuses to execute it.
style-src 'unsafe-inline'	Required for runtime theme CSS variables applied by the theming system.

Because element iframes communicate exclusively through postMessage and BroadcastChannel (no outbound HTTP), they have no connect-src directive at all. The coordinator iframe -- which sends tokenization requests to the Basis Theory API -- is the only iframe with a connect-src, and it is locked to https://*.basistheory.com.

Hash-based CSP is stronger than nonce-based CSP for static assets. Nonces are designed for server-rendered pages where each response generates a fresh value. Element iframes are static CDN files, so a nonce would be identical for every user. SHA-384 hashes are the correct primitive here: the browser blocks execution if the script content changes by even a single byte.

CSP on your page

If your application enforces its own Content Security Policy, you need to allow Basis Theory domains so the SDK can load and the iframes can communicate:

<meta http-equiv="Content-Security-Policy"
  content="frame-src https://*.basistheory.com;
           script-src https://*.basistheory.com;
           connect-src https://*.basistheory.com" />

For full details on required CSP directives, Trusted Types, and common errors, see the troubleshooting guide.

---

Subresource Integrity (SRI)

What it protects

Subresource Integrity lets the browser verify that a script fetched from a CDN has not been tampered with. When you add an integrity attribute to a <script> tag, the browser computes a hash of the downloaded file and compares it to the expected value. If they do not match, the script is blocked.

Web Elements enforces SRI at two levels:

1. Full SDK loaded by the loader -- The loader automatically verifies the SDK using a SHA-384 hash embedded at build time. No action is required from you.
2. Loader script tag -- You can optionally verify the loader itself by adding an integrity attribute to your <script> tag.

Using SRI with the CDN script tag

Every release publishes an sri.json manifest alongside the SDK bundles on the CDN. This manifest contains SHA-384 hashes for all published assets.

Step 1. Fetch the SRI manifest for your version:

https://js.basistheory.com/{version}/web-elements/sri.json

The manifest has this structure:

{
  "version": "1.0",
  "versions": {
    "0.x.y": {
      "es":     { "hash": "sha384-...", "url": "https://js.basistheory.com/0.x.y/web-elements/basis-theory-sdk.es.js", "size": 12345 },
      "umd":    { "hash": "sha384-...", "url": "https://js.basistheory.com/0.x.y/web-elements/basis-theory-sdk.umd.js", "size": 12345 },
      "loader": { "hash": "sha384-...", "url": "https://js.basistheory.com/0.x.y/web-elements/basis-theory.js", "size": 1234 }
    }
  }
}

Step 2. Add the integrity and crossorigin attributes to your script tag using the loader hash:

<script
  src="https://js.basistheory.com/{version}/web-elements/basis-theory.js"
  integrity="sha384-oqVuAfXRKap7fdgcCY5uykM6..."
  crossorigin="anonymous"
></script>

The crossorigin="anonymous" attribute is required when using SRI with CDN-hosted scripts. Without it, the browser will not perform the integrity check.

What happens automatically

When the loader fetches the full SDK at runtime, it sets the integrity attribute on the dynamically created <script> tag using the hash that was baked in at build time. If the SDK file has been modified on the CDN, the browser refuses to execute it. This happens transparently -- no configuration is needed on your end.

When SRI is skipped

SRI verification is automatically skipped in two cases:

• Local development -- When using a local dev server, the SRI hash is empty and integrity checking is not applied.
• npm module imports -- When you install the SDK via npm and bundle it with your application's build tool, your bundler handles integrity through its own mechanism.

SRI is most valuable when loading the SDK from the CDN via a <script> tag, where a compromised CDN or man-in-the-middle attack could serve a modified file.

---

Iframe sandbox

Element iframes use the sandbox attribute with minimal permissions:

sandbox="allow-scripts allow-same-origin"

This explicitly blocks:

• Top-level navigation (the iframe cannot redirect your page)
• Form submission to arbitrary origins
• Popup windows
• Pointer lock and other device APIs

---

Summary

Protection	Scope	Action required
Hash-based CSP	Element iframes	None -- applied automatically at build time.
SRI (SDK)	Loader loading full SDK	None -- enforced automatically.
SRI (loader)	Your <script> tag	Optional -- add integrity attribute from sri.json.
Iframe sandbox	Element iframes	None -- applied automatically.
CSP on your page	Your application	Recommended -- allow *.basistheory.com in frame-src, script-src, and connect-src.