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