secure v2.0.1 – Middleware, Presets, and Safer Defaults

secure v2.0.1

secure v2.0.1 introduces a cleaner public API, modern preset defaults, first-class ASGI and WSGI middleware, and safer header handling across supported Python web frameworks.

Compared with v1.0.1, v2 keeps the core Secure, with_default_headers(), from_preset(), set_headers(), and set_headers_async() APIs, but changes defaults, adds middleware and normalization helpers, and makes Secure.headers stricter and effectively read-only. Notably, neither v1 nor v2 exposes secure.__version__ as a public attribute, so version checks should use package metadata rather than module attributes.

Highlights

• New preset model with Preset.BALANCED as the recommended default
• First-class SecureASGIMiddleware and SecureWSGIMiddleware
• New header pipeline helpers for allowlisting, deduplication, and normalization
• Expanded header coverage, including:
  • Cross-Origin-Resource-Policy
  • X-DNS-Prefetch-Control
  • X-Permitted-Cross-Domain-Policies
• Clearer migration path for users coming from v1 manual response mutation patterns

Key improvements

Middleware

v2 adds framework-agnostic middleware in secure.middleware:

• SecureASGIMiddleware(app, *, secure=None, multi_ok=None)
• SecureWSGIMiddleware(app, *, secure=None, multi_ok=None)

This gives ASGI and WSGI applications a cleaner integration path than manually mutating each response.

Header pipeline helpers

v2 adds new helpers on Secure:

• allowlist_headers()
• deduplicate_headers()
• validate_and_normalize_headers()
• header_items()

These make it easier to inspect, normalize, and safely emit headers, especially in applications that may need duplicate-aware handling for multi-valued headers.

New public builders and constants

v2 adds:

• CrossOriginResourcePolicy
• XDnsPrefetchControl
• XPermittedCrossDomainPolicies
• MULTI_OK
• COMMA_JOIN_OK
• DEFAULT_ALLOWED_HEADERS

More predictable header state

v2 tracks headers_list mutations correctly. In v1, once .headers had been read, later mutations to headers_list could leave .headers stale because it was backed by a cached property.

Breaking changes

Secure.headers is stricter

In v1, Secure.headers was a cached dict[str, str], and duplicate header names silently collapsed to the last value.

In v2:

• Secure.headers is an immutable mapping
• duplicate header names, case-insensitive, raise ValueError

If your application intentionally or accidentally creates duplicate header names, do not rely on .headers as the source of truth. Use header_items() for ordered inspection, or call deduplicate_headers() before applying headers.

Default headers changed

Secure.with_default_headers() no longer means the same thing it meant in v1.

• In v1, with_default_headers() included Cache-Control: no-store
• In v2, with_default_headers() maps to Preset.BALANCED, which does not include that same default cache behavior

If you relied on the v1 default cache policy, add it explicitly in v2.

Presets changed materially

v1 included Preset.BASIC and Preset.STRICT.

v2 adds Preset.BALANCED, and Secure.with_default_headers() now maps to that new preset.

This also means Preset.BASIC in v2 is not the old BASIC. Compared with v1 BASIC, v2 BASIC adds or changes:

• COOP
• CORP
• CSP
• HSTS with includeSubDomains
• X-DNS-Prefetch-Control
• X-Permitted-Cross-Domain-Policies
• Origin-Agent-Cluster
• X-Download-Options
• X-XSS-Protection

and drops v1 BASIC defaults such as:

• Server
• Cache-Control

Preset.STRICT also changed:

• v1 STRICT used Strict-Transport-Security: max-age=63072000; includeSubDomains; preload
• v2 STRICT removes preload by default
• v2 STRICT changes cache control from no-store to no-store, max-age=0

If you need v1-style HSTS preload behavior, configure it explicitly in v2.

FastAPI integration changed in practice

There is no secure.framework.fastapi helper in either version.

• v1 had no framework module at all
• v2 introduces generic ASGI and WSGI middleware instead

For FastAPI and other ASGI frameworks, the recommended upgrade path is to move from per-response mutation to SecureASGIMiddleware.

Added

• SecureASGIMiddleware
• SecureWSGIMiddleware
• allowlist_headers(...)
• deduplicate_headers(...)
• validate_and_normalize_headers(...)
• header_items()
• CrossOriginResourcePolicy
• XDnsPrefetchControl
• XPermittedCrossDomainPolicies
• MULTI_OK
• COMMA_JOIN_OK
• DEFAULT_ALLOWED_HEADERS

Changed

• Secure.with_default_headers() now returns the balanced preset
• header deduplication and normalization are now first-class operations
• response integration is more robust across sync and async styles
• applications with duplicate header names now fail fast instead of silently collapsing values
• framework guidance now emphasizes middleware-based integration for ASGI and WSGI apps

Migration guide (v1 → v2)

1. Review your defaults

   • Do not assume with_default_headers() in v2 matches v1
   • Diff the emitted headers and re-add any defaults you rely on explicitly

2. Audit any code that reads Secure.headers

   • Treat it as read-only in v2
   • If duplicate names are possible, use header_items() or call deduplicate_headers() first

3. Move ASGI and WSGI apps to middleware

   • Replace per-response set_headers_async() or set_headers() calls with SecureASGIMiddleware or SecureWSGIMiddleware
   • Pre-normalize the Secure instance if needed before wiring it into middleware

FastAPI example

Before, v1-style manual response mutation

from fastapi import FastAPI, Request
from secure import Secure

app = FastAPI()
secure_headers = Secure.with_default_headers()

@app.middleware("http")
async def add_security_headers(request: Request, call_next):
    response = await call_next(request)
    await secure_headers.set_headers_async(response)
    return response

After, v2-style ASGI middleware

from fastapi import FastAPI
from secure import Secure
from secure.middleware import SecureASGIMiddleware

app = FastAPI()

secure_headers = (
    Secure.with_default_headers()
    .deduplicate_headers(action="last")
    .validate_and_normalize_headers()
)

app.add_middleware(SecureASGIMiddleware, secure=secure_headers)

Upgrade in 3 steps

1. Replace any assumption that with_default_headers() means the same defaults as v1
2. Audit code that reads Secure.headers and update duplicate-header handling
3. For ASGI and WSGI apps, move from per-response header mutation to middleware with a pre-normalized Secure instance

Summary

v2.0.1 keeps the core Secure API intact while making the library safer and easier to integrate in modern Python web applications. The biggest changes are the new preset model, middleware-first integration for ASGI and WSGI frameworks, and stricter handling of duplicate and normalized headers.

secure v2.0.0rc1

A release-candidate for secure v2.0.0 focused on a cleaner public API, modern presets, first-class ASGI/WSGI middleware, and safer header application/validation across frameworks.

Highlights

• New preset model with a recommended default: Preset.BALANCED
• New ASGI + WSGI middleware for framework-agnostic integration
• New header pipeline helpers for allowlisting, deduping, and validation/normalization
• Expanded header coverage and improved docs, examples, and migration guidance

---

Breaking changes

• Presets redesigned and defaults changed
  • Added Preset.BALANCED, now the recommended default.
  • Secure.with_default_headers() now equals Secure.from_preset(Preset.BALANCED).
  • Preset.BASIC targets Helmet.js default parity.
  • Preset.STRICT no longer enables HSTS preload by default (opt-in separately).
• Secure.headers is now strict about duplicates
  • Duplicate header names (case-insensitive) raise ValueError.
  • Use header_items() for multi-valued emission, or resolve duplicates via deduplicate_headers() / validate_and_normalize_headers().

---

Added

• Middleware
  • SecureASGIMiddleware (intercepts ASGI http.response.start)
  • SecureWSGIMiddleware (wraps WSGI start_response)
  • secure.middleware re-exports both; supports multi_ok for safely appending multi-valued headers (e.g. CSP)
• Header pipeline helpers on Secure
  • allowlist_headers(...) (raise / drop / warn)
  • deduplicate_headers(...) (raise, first, last, concat) with COMMA_JOIN_OK and MULTI_OK
  • validate_and_normalize_headers(...) (RFC 7230 token validation, CR/LF hardening, optional obs-text, immutable normalized override)
• Serialization
  • header_items() for ordered (name, value) output without enforcing uniqueness
• Constants / policies
  • MULTI_OK, COMMA_JOIN_OK, DEFAULT_ALLOWED_HEADERS
  • OnInvalidPolicy, OnUnexpectedPolicy, DeduplicateAction
• Expanded header coverage
  • Cross-Origin-Resource-Policy
  • X-DNS-Prefetch-Control
  • X-Permitted-Cross-Domain-Policies
• Project & CI
  • CODE_OF_CONDUCT.md, CONTRIBUTING.md
  • GitHub Actions for multi-version tests + Ruff

---

Changed

• Docs/README overhaul
  • Middleware usage + multi_ok semantics
  • Clear preset guidance (BALANCED / BASIC / STRICT) and documented default header set
  • New “header pipeline and validation” section (allowlist → dedupe → normalize)
  • New error handling/logging guidance (HeaderSetError, AttributeError, RuntimeError, pipeline ValueError)
  • Supported frameworks list expanded (now includes Dash and Shiny)
  • Attribution to MDN and the OWASP Secure Headers Project
• Presets behavior
  • BASIC adds Origin-Agent-Cluster, X-Download-Options, X-XSS-Protection: 0 for Helmet-parity
• Response integration
  • More robust sync/async detection
  • Supports response.headers.set(...) (Werkzeug-style)
  • Failures while applying headers are wrapped in HeaderSetError
• Packaging/tooling
  • pyproject.toml modernized (metadata cleanup, setuptools floor bump, Ruff configuration)

---

Testing

• Expanded unit and contract tests, including improved coverage for sync/async response integration paths.

---

Upgrade notes

• If you were relying on the previous with_default_headers() behavior, review the new presets and choose:
  • Preset.BALANCED (default, recommended)
  • Preset.BASIC (Helmet-parity compatibility)
  • Preset.STRICT (hardened; no preload by default)
• If your app needs multi-valued headers, prefer header_items() and/or configure middleware multi_ok.

See the migration guide: docs/migration.md.

What's Changed

• feat: CI for unit tests + explicit Python 3.13 & 3.14 support by @BoboTiG in #39
• secure v2.0.0rc1: presets redesign, ASGI/WSGI middleware, and header updates by @cak in #40

New Contributors

• @BoboTiG made their first contribution in #39

Full Changelog: v1.0.1...v2.0.0rc1

v1.0.1 - Performance Improvements for Secure.set_headers

This release focuses on improving the performance of the Secure.set_headers method by reducing redundant type checks. The changes optimize the efficiency when setting multiple headers, especially in frameworks that support both synchronous and asynchronous methods.

Key updates in v1.0.1:

• Performance Improvement: Reduced redundant type checks in Secure.set_headers and Secure.set_headers_async. This optimizes the process by checking the response type once before looping through headers, enhancing performance for applications with multiple headers. #26
• New Tests: Added comprehensive tests to validate async and sync behavior for setting headers, ensuring compatibility across different frameworks.

Special Thanks

A big thank you to @davidwtbuxton for raising the issue and helping us improve the project.

How to Upgrade

To upgrade to v1.0.1, simply run:

pip install --upgrade secure

v1.0.0 – Full Redesign and Modernization of secure.py

We’re excited to announce the release of secure.py v1.0.0! This is a major update that completely redesigns the library with modern Python support and significant improvements in usability, security, and performance.

What's New:

• Full API Overhaul: The entire library has been redesigned for Python 3.10+ with a more Pythonic API, leveraging type hints and modern language features like union operators (|) and cached_property.

• Improved Framework Support: Enhanced integration for popular web frameworks like FastAPI, Flask, Django, Sanic, Starlette, and more, with improved support for asynchronous frameworks.

• Middleware Examples: We've added middleware-based integration examples for supported frameworks, making it easier to apply security headers across your application.

• Enhanced Security Defaults: Updated default security headers for stronger protection, including refined Content-Security-Policy (CSP) configurations with nonce and strict-dynamic directives.

• Better Type Annotations: The entire codebase now includes better type hints and annotations for an improved developer experience.

Breaking Changes:

• API Redesign: The library has undergone a full API redesign, and some previous methods have been deprecated or refactored. Be sure to review the documentation before upgrading.

• Python 3.10+ Required: This release drops support for older versions of Python. Ensure you are running Python 3.10 or later before upgrading.

Additional Updates:

• Server Header Handling: Improved handling for overriding Server headers in Uvicorn-based frameworks, with examples on how to prevent default Uvicorn headers.
• Expanded Documentation: Updated and more comprehensive documentation with examples for middleware and asynchronous header application.

We look forward to your feedback! 🚀

v0.3.0

Breaking Changes

Changelog:

• Full redesign of Secure API
• Removal of cookie support
• Add type hints
• Add support for FastAPI
• Change Feature-Policy to Permissions-Policy (#10)

v0.2.1

Merry Christmas! 🎅

• Add support for Masonite
• Remove trailing semicolon from Feature Policy
• Rename Feature.Values.All to Feature.Values.All_ (shadowed built-in name 'all')
• Modify hug implementation for SecureHeaders and SecureCookie
• Upper-case SameSite Enum (SameSite.LAX / SameSite.STRICT)
• Add SecureHeaders and SecureCookie docstrings

v0.2.0

• Add policy builder SecurePolicies (policies.py)
• Add Expires header for legacy browser support
• Add max-age directive to Cache-control header
• Rename XXS argument to XXP
• Use native Flask set-cookie