Reference

Classes

Main classes provided by the package

Secure: Configure and apply HTTP security headers for web applications.

Dataclasses

Dataclass definitions

CacheControl: Fluent builder for the Cache-Control HTTP header.
ContentSecurityPolicy: Fluent builder for the Content-Security-Policy HTTP response header.
CrossOriginEmbedderPolicy: Builder for the Cross-Origin-Embedder-Policy (COEP) HTTP response header.
CrossOriginOpenerPolicy: Builder for the Cross-Origin-Opener-Policy (COOP) HTTP response header.
CrossOriginResourcePolicy: Builder for the Cross-Origin-Resource-Policy (CORP) HTTP response header.
CustomHeader: Wrapper for an arbitrary HTTP header.
PermissionsPolicy: Builder for the Permissions-Policy HTTP header.
ReferrerPolicy: Builder for the Referrer-Policy HTTP response header.
Server: Builder for the Server HTTP response header.
StrictTransportSecurity: Builder for the Strict-Transport-Security (HSTS) HTTP response header.
XContentTypeOptions: Builder for the X-Content-Type-Options HTTP header.
XDnsPrefetchControl: Builder for the non-standard X-DNS-Prefetch-Control HTTP header.
XFrameOptions: Builder for the X-Frame-Options HTTP response header.
XPermittedCrossDomainPolicies: Builder for the X-Permitted-Cross-Domain-Policies HTTP response header.

StrictTransportSecurity Methods

Methods for the StrictTransportSecurity class

StrictTransportSecurity.header_value: Return the serialized Strict-Transport-Security header value.
StrictTransportSecurity.clear(): Clear configured directives and reset back to the library default.
StrictTransportSecurity.value(): Set a raw header value (escape hatch), replacing any configured directives.
StrictTransportSecurity.max_age(): Set max-age: how long (in seconds) the browser should remember to use HTTPS only.
StrictTransportSecurity.include_subdomains(): Add includeSubDomains: apply the HSTS policy to all subdomains as well.
StrictTransportSecurity.preload(): Add preload: enable HSTS preload list requirements (requires includeSubDomains and 1y+ max-age).

Secure Methods

Methods for the Secure class

Secure.with_default_headers(): Create a Secure instance with a sensible default set of headers.
Secure.from_preset(): Create a Secure instance using a predefined security preset.
Secure.__str__(): Return a human-readable listing of headers and their effective values.
Secure.__repr__(): Return a detailed representation of the Secure instance.
Secure.validate_and_normalize_headers(): Validate and normalize the current header items and cache an immutable mapping.
Secure.deduplicate_headers(): Deduplicate headers in headers_list according to the chosen policy.
Secure.allowlist_headers(): Enforce a case-insensitive allowlist for header names in headers_list.
Secure.header_items(): Serialize the current headers into (name, value) pairs.
Secure.set_headers(): Apply configured headers synchronously to response.
Secure.set_headers_async(): Apply configured headers asynchronously to response.

CacheControl Methods

Methods for the CacheControl class

CacheControl.value(): Set an explicit header value, replacing all configured directives.
CacheControl.set(): Alias for value().
CacheControl.clear(): Clear all directives and explicit value, returning to the default state.
CacheControl.custom(): Add a custom directive token (non-standard / extra).
CacheControl.immutable(): Indicate the response will not be updated while it is fresh.
CacheControl.max_age(): Set max-age=N (freshness lifetime in responses, acceptable age in requests).
CacheControl.max_stale(): Allow reusing a stale response within seconds, or any stale age when omitted (request).
CacheControl.min_fresh(): Require a stored response to remain fresh for at least seconds (request).
CacheControl.must_revalidate(): Require revalidation with the origin server once a stored response becomes stale (response).
CacheControl.must_understand(): Store the response only if the cache understands the caching requirements for its status code.
CacheControl.no_cache(): Allow storing but require validation with the origin server before each reuse.
CacheControl.no_store(): Instruct caches (private or shared) not to store this response.
CacheControl.no_transform(): Instruct intermediaries not to transform the request or response content.
CacheControl.only_if_cached(): Request an already-cached response; if none is available, a 504 may be returned (request).
CacheControl.private(): Indicate the response may be stored only in a private cache (e.g., a browser cache).
CacheControl.proxy_revalidate(): Like must-revalidate, but for shared caches only (response).
CacheControl.public(): Indicate the response may be stored in a shared cache (response).
CacheControl.s_maxage(): Set s-maxage=N (freshness lifetime in shared caches only).
CacheControl.s_max_age(): Alias for s_maxage().
CacheControl.stale_if_error(): Allow reusing a stale response for seconds when a 500/502/503/504 error is encountered.
CacheControl.stale_while_revalidate(): Allow reusing a stale response for seconds while revalidation happens in the background.

ContentSecurityPolicy Methods

Methods for the ContentSecurityPolicy class

ContentSecurityPolicy.value(): Set an exact header value (escape hatch).
ContentSecurityPolicy.set(): Alias for value().
ContentSecurityPolicy.clear(): Clear all configured directives and any raw override.
ContentSecurityPolicy.report_only(): Use the report-only header name (Content-Security-Policy-Report-Only).
ContentSecurityPolicy.enforce(): Use the enforcing header name (Content-Security-Policy).
ContentSecurityPolicy.custom(): Alias for custom_directive().
ContentSecurityPolicy.custom_directive(): Add (or update) a directive.
ContentSecurityPolicy.base_uri(): Set valid sources for the document <base> element.
ContentSecurityPolicy.block_all_mixed_content(): Prevent loading any assets using HTTP when the page is loaded using HTTPS.
ContentSecurityPolicy.child_src(): Set valid sources for web workers and nested browsing contexts.
ContentSecurityPolicy.connect_src(): Set valid sources for script interfaces (for example, XHR, Fetch, WebSocket).
ContentSecurityPolicy.default_src(): Set the fallback policy for all fetch directives.
ContentSecurityPolicy.fenced_frame_src(): Set valid sources for nested browsing contexts loaded into <fencedframe>.
ContentSecurityPolicy.font_src(): Set valid sources for fonts.
ContentSecurityPolicy.form_action(): Restrict the URLs which can be used as the target of form submissions.
ContentSecurityPolicy.frame_ancestors(): Set valid parent sources that may embed the page in a frame.
ContentSecurityPolicy.frame_src(): Set valid sources for nested browsing contexts loaded into frames/iframes.
ContentSecurityPolicy.img_src(): Set valid sources for images and favicons.
ContentSecurityPolicy.manifest_src(): Set valid sources for application manifests.
ContentSecurityPolicy.media_src(): Set valid sources for media (audio, video, track).
ContentSecurityPolicy.object_src(): Set valid sources for plugin-like objects (for example, <object>, <embed>).
ContentSecurityPolicy.prefetch_src(): Set valid sources to be prefetched or prerendered.
ContentSecurityPolicy.report_to(): Configure reporting endpoints via report-to groups.
ContentSecurityPolicy.report_uri(): Configure the legacy reporting endpoint(s) via report-uri.
ContentSecurityPolicy.require_trusted_types_for(): Enforce Trusted Types at specific DOM injection sinks.
ContentSecurityPolicy.sandbox(): Enable a sandbox for the requested resource (similar to <iframe sandbox>).
ContentSecurityPolicy.script_src(): Set valid sources for JavaScript and WebAssembly resources.
ContentSecurityPolicy.script_src_attr(): Set valid sources for inline event handlers.
ContentSecurityPolicy.script_src_elem(): Set valid sources for <script> elements.
ContentSecurityPolicy.style_src(): Set valid sources for stylesheets.
ContentSecurityPolicy.style_src_attr(): Set valid sources for inline styles on individual elements.
ContentSecurityPolicy.style_src_elem(): Set valid sources for <style> and stylesheet <link> elements.
ContentSecurityPolicy.trusted_types(): Specify an allowlist of Trusted Types policies.
ContentSecurityPolicy.upgrade_insecure_requests(): Upgrade insecure HTTP requests to HTTPS.
ContentSecurityPolicy.worker_src(): Set valid sources for Worker, SharedWorker, and ServiceWorker scripts.
ContentSecurityPolicy.keyword(): Return a quoted CSP keyword/source expression (for example, 'self').
ContentSecurityPolicy.nonce(): Create a nonce source expression for inline scripts or styles.

CrossOriginEmbedderPolicy Methods

Methods for the CrossOriginEmbedderPolicy class

CrossOriginEmbedderPolicy.set(): Set a COEP directive.
CrossOriginEmbedderPolicy.value(): Alias for set() to align with other headers.
CrossOriginEmbedderPolicy.clear(): Reset to the library default directive.
CrossOriginEmbedderPolicy.unsafe_none(): Set COEP to unsafe-none.
CrossOriginEmbedderPolicy.require_corp(): Set COEP to require-corp.
CrossOriginEmbedderPolicy.credentialless(): Set COEP to credentialless.

CrossOriginOpenerPolicy Methods

Methods for the CrossOriginOpenerPolicy class

CrossOriginOpenerPolicy.value(): Set a custom value for the Cross-Origin-Opener-Policy header.
CrossOriginOpenerPolicy.custom(): Alias for value().
CrossOriginOpenerPolicy.set(): Backwards-compatible alias for value().
CrossOriginOpenerPolicy.clear(): Reset the Cross-Origin-Opener-Policy header to the library default value.
CrossOriginOpenerPolicy.unsafe_none(): Set the header to 'unsafe-none'.
CrossOriginOpenerPolicy.same_origin_allow_popups(): Set the header to 'same-origin-allow-popups'.
CrossOriginOpenerPolicy.same_origin(): Set the header to 'same-origin'.
CrossOriginOpenerPolicy.noopener_allow_popups(): Set the header to 'noopener-allow-popups'.

CrossOriginResourcePolicy Methods

Methods for the CrossOriginResourcePolicy class

CrossOriginResourcePolicy.clear(): Reset this header to the library default value.
CrossOriginResourcePolicy.value(): Set the header value.
CrossOriginResourcePolicy.set(): Backwards-compatible alias for value(...).
CrossOriginResourcePolicy.same_origin(): Restrict resource loading to the same origin.
CrossOriginResourcePolicy.same_site(): Allow resource loading from the same site.
CrossOriginResourcePolicy.cross_origin(): Allow resource loading from any origin.

PermissionsPolicy Methods

Methods for the PermissionsPolicy class

PermissionsPolicy.value(): Set a raw header value (escape hatch).
PermissionsPolicy.set(): Alias for value() (kept for backwards compatibility).
PermissionsPolicy.clear(): Clear all configured directives and any raw override.
PermissionsPolicy.add_directive(): Add or replace a directive.
PermissionsPolicy.directive(): Alias for add_directive().
PermissionsPolicy.accelerometer(): Controls whether the page can use the Accelerometer sensor.
PermissionsPolicy.ambient_light_sensor(): Controls whether the page can use the Ambient Light sensor.
PermissionsPolicy.aria_notify(): Controls whether the page can use ARIA notifications (aria-notify).
PermissionsPolicy.attribution_reporting(): Controls whether the page can use Attribution Reporting.
PermissionsPolicy.autoplay(): Controls whether media is allowed to autoplay.
PermissionsPolicy.bluetooth(): Controls whether the page can use the Web Bluetooth API.
PermissionsPolicy.browsing_topics(): Controls whether the page can use browsing-topics.
PermissionsPolicy.compute_pressure(): Controls whether the page can use the Compute Pressure API.
PermissionsPolicy.cross_origin_isolated(): Controls whether the document can be cross-origin isolated.
PermissionsPolicy.fullscreen(): Controls whether the page can use the Fullscreen API.
PermissionsPolicy.gamepad(): Controls whether the page can use the Gamepad API.
PermissionsPolicy.geolocation(): Controls whether the page can use the Geolocation API.
PermissionsPolicy.gyroscope(): Controls whether the page can use the Gyroscope sensor.
PermissionsPolicy.hid(): Controls whether the page can use the WebHID API.
PermissionsPolicy.identity_credentials_get(): Controls whether the page can use identity credentials (identity-credentials-get).
PermissionsPolicy.idle_detection(): Controls whether the page can use idle detection.
PermissionsPolicy.local_fonts(): Controls whether the page can access local fonts.
PermissionsPolicy.magnetometer(): Controls whether the page can use the Magnetometer sensor.
PermissionsPolicy.microphone(): Controls whether the page can access the microphone.
PermissionsPolicy.on_device_speech_recognition(): Controls whether the page can use on-device speech recognition.
PermissionsPolicy.otp_credentials(): Controls whether the page can use the WebOTP API.
PermissionsPolicy.publickey_credentials_create(): Controls whether the page can create WebAuthn credentials.
PermissionsPolicy.publickey_credentials_get(): Controls whether the page can use WebAuthn credential assertion.
PermissionsPolicy.serial(): Controls whether the page can use the Web Serial API.
PermissionsPolicy.speaker_selection(): Controls whether the page can select audio output devices.
PermissionsPolicy.storage_access(): Controls whether the page can request storage access.
PermissionsPolicy.summarizer(): Controls whether the page can use summarizer.
PermissionsPolicy.translator(): Controls whether the page can use translator.
PermissionsPolicy.language_detector(): Controls whether the page can use language detection.
PermissionsPolicy.usb(): Controls whether the page can use the WebUSB API.
PermissionsPolicy.web_share(): Controls whether the page can use the Web Share API.
PermissionsPolicy.window_management(): Controls whether the page can use window management.
PermissionsPolicy.xr_spatial_tracking(): Controls whether the page can use XR spatial tracking.
PermissionsPolicy.battery(): Legacy/nonstandard: controls whether the page can access battery status.
PermissionsPolicy.camera(): Controls whether the page can access the camera.
PermissionsPolicy.clipboard_read(): Controls whether the page can read from the clipboard.
PermissionsPolicy.clipboard_write(): Controls whether the page can write to the clipboard.
PermissionsPolicy.display_capture(): Controls whether the page can capture the display (screen capture).
PermissionsPolicy.document_domain(): Legacy/nonstandard: controls whether the page can use document.domain.
PermissionsPolicy.encrypted_media(): Legacy/nonstandard: controls whether the page can use encrypted media.
PermissionsPolicy.execution_while_not_rendered(): Legacy/nonstandard: controls whether the page can execute when not rendered.
PermissionsPolicy.execution_while_out_of_viewport(): Legacy/nonstandard: controls whether the page can execute while out of the viewport.
PermissionsPolicy.midi(): Controls whether the page can use the Web MIDI API.
PermissionsPolicy.navigation_override(): Legacy/nonstandard: controls whether the page can override navigation.
PermissionsPolicy.payment(): Controls whether the page can use the Payment Request API.
PermissionsPolicy.picture_in_picture(): Controls whether the page can use Picture-in-Picture.
PermissionsPolicy.screen_wake_lock(): Controls whether the page can use the Screen Wake Lock API.
PermissionsPolicy.sync_xhr(): Legacy/nonstandard: controls whether the page can use synchronous XHR.

ReferrerPolicy Methods

Methods for the ReferrerPolicy class

ReferrerPolicy.add(): Add one or more policy tokens.
ReferrerPolicy.set(): Alias of add() (appends one or more policy tokens).
ReferrerPolicy.value(): Replace the current policies with value.
ReferrerPolicy.custom(): Escape hatch: same as value().
ReferrerPolicy.fallback(): Replace the current policies with an explicit fallback list.
ReferrerPolicy.clear(): Clear all configured policies.
ReferrerPolicy.no_referrer(): Set the policy to no-referrer (omit the Referer header entirely).
ReferrerPolicy.no_referrer_when_downgrade(): Set the policy to no-referrer-when-downgrade.
ReferrerPolicy.origin(): Set the policy to origin (send only the origin, e.g. https://example.com/).
ReferrerPolicy.origin_when_cross_origin(): Set the policy to origin-when-cross-origin.
ReferrerPolicy.same_origin(): Set the policy to same-origin.
ReferrerPolicy.strict_origin(): Set the policy to strict-origin.
ReferrerPolicy.strict_origin_when_cross_origin(): Set the policy to strict-origin-when-cross-origin (the modern default).
ReferrerPolicy.unsafe_url(): Set the policy to unsafe-url (send origin + path + query for all requests, regardless of security).

XDnsPrefetchControl Methods

Methods for the XDnsPrefetchControl class

XDnsPrefetchControl.clear(): Reset to the library default value (off).
XDnsPrefetchControl.set(): Set a custom value for the X-DNS-Prefetch-Control header.
XDnsPrefetchControl.value(): Alias for set().
XDnsPrefetchControl.custom(): Alias for set() (escape hatch).
XDnsPrefetchControl.on(): Enable DNS prefetching.
XDnsPrefetchControl.off(): Disable DNS prefetching.
XDnsPrefetchControl.allow(): Alias for on().
XDnsPrefetchControl.disable(): Alias for off().

XFrameOptions Methods

Methods for the XFrameOptions class

XFrameOptions.value(): Set a custom header value.
XFrameOptions.set(): Alias for value(...) (backwards-compatible).
XFrameOptions.custom(): Alias for value(...).
XFrameOptions.clear(): Reset the X-Frame-Options header to its default value (SAMEORIGIN).
XFrameOptions.deny(): Set the directive to DENY.
XFrameOptions.sameorigin(): Set the directive to SAMEORIGIN.
XFrameOptions.allow_from(): Set the (obsolete) ALLOW-FROM <origin> directive.

XPermittedCrossDomainPolicies Methods

Methods for the XPermittedCrossDomainPolicies class

XPermittedCrossDomainPolicies.clear(): Reset the header to the default value (none).
XPermittedCrossDomainPolicies.value(): Set a custom header value.
XPermittedCrossDomainPolicies.custom(): Alias for value().
XPermittedCrossDomainPolicies.set(): Backwards-compatible alias for value().
XPermittedCrossDomainPolicies.policy(): Set the header to one of the known directive values.
XPermittedCrossDomainPolicies.none(): Disallow policy files anywhere on the target server, including a master policy file.
XPermittedCrossDomainPolicies.master_only(): Allow cross-domain access to the master policy file defined on the same domain.
XPermittedCrossDomainPolicies.by_content_type(): Allow only policy files served with Content-Type: text/x-cross-domain-policy (HTTP/HTTPS only).
XPermittedCrossDomainPolicies.by_ftp_filename(): Allow only policy files named crossdomain.xml (FTP only).
XPermittedCrossDomainPolicies.all(): Allow all policy files on this target domain.
XPermittedCrossDomainPolicies.none_this_response(): Indicate the current document should not be used as a policy file.

Enumerations

Enumeration types

Preset: Predefined security header presets for Secure.