[ { "path": ".github/workflows/tests.yml", "content": "name: Unit Tests\n\non:\n pull_request:\n\npermissions:\n contents: read\n\njobs:\n tests:\n runs-on: ubuntu-latest\n strategy:\n fail-fast: false\n matrix:\n python:\n - \"3.10\"\n - \"3.11\"\n - \"3.12\"\n - \"3.13\"\n - \"3.14-dev\"\n\n steps:\n - uses: actions/checkout@v4\n\n - name: Set up Python\n uses: actions/setup-python@v5\n with:\n python-version: ${{ matrix.python }}\n\n - name: Install toolchain\n run: pip install ruff==0.13.2 pytest\n\n - name: Install package\n run: pip install -e .\n\n - name: Unit tests\n run: python -m pytest\n\n - name: Lint\n run: ruff check secure tests\n" }, { "path": ".gitignore", "content": "# Byte-compiled / optimized / DLL files\n__pycache__/\n*.py[cod]\n*$py.class\n\n# C extensions\n*.so\n\n# Distribution / packaging\n.Python\nbuild/\ndevelop-eggs/\ndist/\ndownloads/\neggs/\n.eggs/\nlib/\nlib64/\nparts/\nsdist/\nvar/\nwheels/\nshare/python-wheels/\n*.egg-info/\n.installed.cfg\n*.egg\nMANIFEST\n\n# PyInstaller\n# Usually these files are written by a python script from a template\n# before PyInstaller builds the exe, so as to inject date/other infos into it.\n*.manifest\n*.spec\n\n# Installer logs\npip-log.txt\npip-delete-this-directory.txt\n\n# Unit test / coverage reports\nhtmlcov/\n.tox/\n.nox/\n.coverage\n.coverage.*\n.cache\nnosetests.xml\ncoverage.xml\n*.cover\n*.py,cover\n.hypothesis/\n.pytest_cache/\ncover/\n\n# Translations\n*.mo\n*.pot\n\n# Django stuff:\n*.log\nlocal_settings.py\ndb.sqlite3\ndb.sqlite3-journal\n\n# Flask stuff:\ninstance/\n.webassets-cache\n\n# Scrapy stuff:\n.scrapy\n\n# Sphinx documentation\ndocs/_build/\n\n# PyBuilder\n.pybuilder/\ntarget/\n\n# Jupyter Notebook\n.ipynb_checkpoints\n\n# IPython\nprofile_default/\nipython_config.py\n\n# pyenv\n# For a library or package, you might want to ignore these files since the code is\n# intended to run in multiple environments; otherwise, check them in:\n# .python-version\n\n# pipenv\n# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.\n# However, in case of collaboration, if having platform-specific dependencies or dependencies\n# having no cross-platform support, pipenv may install dependencies that don't work, or not\n# install all needed dependencies.\n#Pipfile.lock\n\n# poetry\n# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.\n# This is especially recommended for binary packages to ensure reproducibility, and is more\n# commonly ignored for libraries.\n# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control\n#poetry.lock\n\n# pdm\n# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.\n#pdm.lock\n# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it\n# in version control.\n# https://pdm.fming.dev/latest/usage/project/#working-with-version-control\n.pdm.toml\n.pdm-python\n.pdm-build/\n\n# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm\n__pypackages__/\n\n# Celery stuff\ncelerybeat-schedule\ncelerybeat.pid\n\n# SageMath parsed files\n*.sage.py\n\n# Environments\n.env\n.venv\nenv/\nvenv/\nENV/\nenv.bak/\nvenv.bak/\n\n# Spyder project settings\n.spyderproject\n.spyproject\n\n# Rope project settings\n.ropeproject\n\n# mkdocs documentation\n/site\n\n# mypy\n.mypy_cache/\n.dmypy.json\ndmypy.json\n\n# Pyre type checker\n.pyre/\n\n# pytype static type analyzer\n.pytype/\n\n# Cython debug symbols\ncython_debug/\n\n# PyCharm\n# JetBrains specific template is maintained in a separate JetBrains.gitignore that can\n# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore\n# and can be added to the global gitignore or merged into this file. For a more nuclear\n# option (not recommended) you can uncomment the following to ignore the entire idea folder.\n#.idea/\n.idea\n\n.DS_Store" }, { "path": "CHANGELOG.md", "content": "# Changelog\n\nAll notable changes to this project will be documented in this file.\n\nThe format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),\nand this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).\n\n## [Unreleased]\n\n- Placeholder for upcoming changes.\n\n## [2.0.1] - 2026-04-21\n\nThis is the first stable v2 release. Version `2.0.0` was burned and should be skipped when tagging or publishing.\n\nv2 focuses on a cleaner public API, a redesigned preset model, first-class ASGI/WSGI middleware, and stricter, safer header handling.\n\n### Breaking Changes\n\n- `Secure.headers` is now strict and read-only\n - v1: `headers` was a cached `dict[str, str]` and silently collapsed duplicate names\n - v2: duplicate header names (case-insensitive) raise `ValueError`\n - use `header_items()` for multi-valued output or `deduplicate_headers()` to resolve duplicates\n\n- Default headers have changed\n - `Secure.with_default_headers()` now maps to `Preset.BALANCED`\n - v1 default included `Cache-Control: no-store`; v2 does not\n - applications relying on v1 defaults should explicitly configure required headers\n\n- Presets redesigned\n - new `Preset.BALANCED` (recommended default)\n - `Preset.BASIC` updated for Helmet.js parity and no longer matches v1 BASIC\n - `Preset.STRICT` no longer enables HSTS preload by default\n - cache behavior and header composition differ across presets compared to v1\n\n- FastAPI / ASGI integration model changed in practice\n - v1 relied on per-response mutation (`set_headers` / `set_headers_async`)\n - v2 introduces middleware-based integration as the recommended approach\n\n### Added\n\n- Middleware\n - `SecureASGIMiddleware`\n - `SecureWSGIMiddleware`\n - `secure.middleware` module\n\n- Header pipeline helpers\n - `allowlist_headers(...)`\n - `deduplicate_headers(...)`\n - `validate_and_normalize_headers(...)`\n - `header_items()` for ordered `(name, value)` output\n\n- New header builders and constants\n - `CrossOriginResourcePolicy`\n - `XDnsPrefetchControl`\n - `XPermittedCrossDomainPolicies`\n - `MULTI_OK`, `COMMA_JOIN_OK`, `DEFAULT_ALLOWED_HEADERS`\n - policy enums: `OnInvalidPolicy`, `OnUnexpectedPolicy`, `DeduplicateAction`\n\n### Changed\n\n- `Secure.with_default_headers()` now returns the balanced preset\n- Header handling is stricter and fails fast on invalid or duplicate configurations\n- Header normalization and validation are first-class operations\n- Response integration is more robust across sync and async frameworks\n- `headers_list` mutations are now reflected correctly (no stale cached state)\n- Documentation updated to emphasize middleware usage and preset selection\n\n### Migration Notes\n\n- Do not assume v1 defaults\n - compare emitted headers and explicitly configure any required behavior\n\n- Audit any usage of `Secure.headers`\n - treat as read-only in v2\n - use `header_items()` or `deduplicate_headers()` when duplicates are possible\n\n- Move to middleware for ASGI/WSGI apps\n - replace per-response `set_headers_async()` calls with `SecureASGIMiddleware` or `SecureWSGIMiddleware`\n\n- Explicitly configure behavior that changed\n - add `Cache-Control` if you relied on v1 defaults\n - add HSTS preload manually if required\n\n### Notes\n\n- Neither v1 nor v2 exposes `secure.__version__`; use package metadata for version checks\n\n## [1.0.1] - 2024-10-18\n\n### Fixed\n\n- Improved performance of `Secure.set_headers` by reducing redundant type checks. ([#26](https://github.com/TypeError/secure/issues/26))\n\n## [1.0.0] - 2024-09-27\n\n### Breaking Changes\n\n- Full redesign of the `secure.py` library with modern Python (3.10+) support.\n- Major API overhaul for improved usability and Pythonic design.\n\n### Added\n\n- Enhanced support for FastAPI and asynchronous frameworks.\n- Added type hints and better type annotations for a smoother developer experience.\n- Refined default security headers for improved protection across web frameworks.\n- Support for modern Python features such as the union operator (`|`) and `cached_property`.\n\n## [0.3.0] - 2021-04-27\n\n### Breaking Changes\n\n- Full redesign of Secure API.\n- Removal of cookie support.\n\n### Added\n\n- Added type hints for better developer experience.\n- Added support for FastAPI.\n\n### Changed\n\n- Replaced Feature-Policy with Permissions-Policy (#10).\n\n## [0.2.1] - 2018-12-24\n\n### Added\n\n- Added support for Masonite framework.\n- Added docstrings for `SecureHeaders` and `SecureCookie`.\n\n### Changed\n\n- Upper-cased SameSite enum to `SameSite.LAX` / `SameSite.STRICT`.\n- Modified hug implementation for SecureHeaders and SecureCookie.\n- Renamed `Feature.Values.All` to `Feature.Values.All_` to avoid conflict with the built-in `all`.\n\n### Fixed\n\n- Removed trailing semicolon from Feature Policy.\n\n## [0.2.0] - 2018-12-16\n\n### Added\n\n- Added policy builder `SecurePolicies` in `policies.py`.\n- Added `Expires` header for legacy browser support.\n- Added `max-age` directive to `Cache-Control` header.\n\n### Changed\n\n- Renamed `XXS` argument to `XXP`.\n- Modified `set-cookie` to use Flask's native method.\n" }, { "path": "CODE_OF_CONDUCT.md", "content": "# Code of Conduct\n\nThis Code of Conduct applies to all `secure` community spaces.\n\n## Our Pledge\n\nWe’re committed to a welcoming, safe, equitable community for everyone. Treat others with respect and assume good faith.\n\n## Expected Behavior\n\n- Be kind, constructive, and professional.\n- Respect different viewpoints and experiences.\n- Take responsibility for your actions and help repair harm.\n- Give and accept feedback gracefully.\n\n## Unacceptable Behavior\n\n- Harassment, threats, or hate/discrimination.\n- Personal attacks, sexualized behavior, or stereotyping.\n- Sharing someone’s private information without consent.\n- Impersonation, misleading identity, or evasions of enforcement.\n- Spam/promotional content outside community norms.\n\n## Reporting\n\nReport issues to **caleb@typeerror.com**. Maintainers will review reports promptly and handle them as confidentially as possible.\n\n## Enforcement\n\nMaintainers may take action appropriate to the situation, including warnings, temporary limits, suspension, or a permanent ban.\n\n## Scope\n\nApplies in project spaces (issues, PRs, discussions, chats) and when representing the project publicly.\n\n## Attribution\n\nAdapted from the Contributor Covenant v3.0: https://www.contributor-covenant.org/version/3/0/\n" }, { "path": "CONTRIBUTING.md", "content": "# Contributing\n\nThanks for helping make `secure` better. The following guidance keeps contributions aligned with the project’s release-quality standards.\n\n## Development environment\n\n1. Create a virtual environment and activate it:\n ```bash\n python -m venv .venv\n source .venv/bin/activate\n ```\n2. Install the package in editable mode so local changes are picked up automatically:\n ```bash\n pip install -e .\n ```\n3. Install the tooling used by the project:\n ```bash\n pip install pytest ruff\n ```\n _Optional:_ `uv` is the package manager used by the project for releases; you can use `uv run pytest` and `uv add ...` to manage dependencies, but it is not required for local development.\n\n## Running tests, linting, and formatting\n\n- **Run unit tests:** `pytest`\n- **Run the linter:** `ruff check`\n- **Apply formatting / fix issues:** `ruff format`\n\nRun these commands before opening a pull request. If you rely on a different Python version, keep it within the supported range (Python 3.10+).\n\n## Adding a header document\n\n1. Add a new guide under `docs/headers/` named after the header (for example, `docs/headers/example_header.md`).\n2. Mirror the structure of the existing header docs:\n - Start with a **Purpose** section that explains the header’s intent.\n - Describe the **Default behavior** and mention how the builder models that default.\n - Show a **Using with `Secure`** example and describe the builder API with method names.\n - Include **Resources** / **Attribution** and any security caveats.\n3. Link the new document from `docs/README.md` (under the Security Headers list) so readers can discover it easily.\n4. Ensure code snippets use the public API (`from secure import ...`), reference the appropriate response types, and avoid framework-specific terminology unless a callout is necessary.\n\n## Adding a framework example\n\n1. Update `docs/frameworks.md`:\n - Add the framework to the table of contents.\n - Include a short intro describing the framework’s model (WSGI vs ASGI, sync vs async).\n - Provide at least one working example showing how to wire `Secure` (middleware, hooks, or response-level helpers).\n - Mention the correct response type (`Response`, `JSONResponse`, etc.) or highlight that you are working with the framework’s default response object.\n2. If the framework needs extra instructions (e.g., disabling Uvicorn’s `Server` header), document them in the same section.\n3. Keep the tone focused on security headers rather than broader framework guidance.\n\n## Commit conventions\n\n- Keep commit messages short (<72 characters) and in the imperative (e.g., `docs: clarify defaults`).\n- Prefix doc-only changes with `docs:` so reviewers immediately know the scope.\n- Reference any related issue or PR in the description when applicable.\n- Run linting/tests before committing to minimize follow-up work.\n\n## Pull request checklist\n\n- [ ] I have run `pytest` locally (or a representative suite) and addressed any failures.\n- [ ] I have run `ruff check` and `ruff format` (when formatting attr).\n- [ ] Documentation updates describe the new behavior (new header docs, framework guidance, etc.).\n- [ ] If applicable, I have updated the release notes/CHANGELOG entry for new user-visible behavior.\n- [ ] My changes follow the project’s security and contribution guidelines (this document).\n" }, { "path": "LICENSE", "content": "MIT License\n\nCopyright (c) 2018-2024 Caleb Kinney\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n" }, { "path": "README.md", "content": "# secure\n\n[![PyPI Version](https://img.shields.io/pypi/v/secure.svg)](https://pypi.org/project/secure/) [![Python Versions](https://img.shields.io/pypi/pyversions/secure.svg)](https://pypi.org/project/secure/) [![License](https://img.shields.io/pypi/l/secure.svg)](https://github.com/TypeError/secure/blob/main/LICENSE)\n\nDefine HTTP security headers once. Apply them consistently across Python web apps.\n\n`secure` provides a small, dependency-free API for configuring modern security headers across common Python web frameworks through ASGI middleware, WSGI middleware, or framework response hooks.\n\nUse it when you want to avoid copy-pasted header strings spread across handlers, hooks, and middleware.\n\n

\n \"secure\n

\n\nQuick links: [Quick start](#quick-start) · [Headers](#what-headers-are-applied-by-default) · [Middleware](#middleware)\n\n---\n\n## Why use `secure`\n\nSetting headers manually is fine for one endpoint. It gets harder to review when values are copied across routes, response hooks, reverse-proxy settings, and different framework integrations.\n\n`secure` helps you:\n\n- Keep one `Secure` policy object instead of scattered header strings\n- Apply the same policy through ASGI middleware, WSGI middleware, or response hooks\n- Start with practical presets, then customize headers for your application\n- Use builders for complex headers such as Content Security Policy and Permissions Policy\n- Make duplicate handling, header overwrites, and validation explicit\n\nThe defaults are a reasonable starting point, not a substitute for application-specific review. Content Security Policy in particular should be adjusted for the scripts, styles, assets, and third-party services your app actually uses.\n\n---\n\n## Installation\n\n```bash\nuv add secure\n# or\npip install secure\n```\n\n---\n\n## Quick start\n\n### FastAPI / ASGI middleware\n\nUse middleware when you can attach `secure` once and cover the whole application.\n\n```python\nfrom fastapi import FastAPI\nfrom secure import Secure\nfrom secure.middleware import SecureASGIMiddleware\n\napp = FastAPI()\nsecure_headers = Secure.with_default_headers()\n\napp.add_middleware(SecureASGIMiddleware, secure=secure_headers)\n```\n\n### Response hooks and handlers\n\nUse the same policy object in framework hooks, middleware callbacks, or handlers that expose a response object with headers support.\n\n```python\nfrom secure import Secure\n\nsecure_headers = Secure.with_default_headers()\n\nsecure_headers.set_headers(response)\n# or\nawait secure_headers.set_headers_async(response)\n```\n\n`Secure.with_default_headers()` maps to `Preset.BALANCED`, a practical default designed to be customized.\n\n---\n\n## What headers are applied by default\n\n```http\nCross-Origin-Opener-Policy: same-origin\nCross-Origin-Resource-Policy: same-origin\nContent-Security-Policy: default-src 'self'; base-uri 'self'; font-src 'self' https: data:; form-action 'self'; frame-ancestors 'self'; img-src 'self' data:; object-src 'none'; script-src 'self'; script-src-attr 'none'; style-src 'self' https: 'unsafe-inline'; upgrade-insecure-requests\nStrict-Transport-Security: max-age=31536000; includeSubDomains\nPermissions-Policy: geolocation=(), microphone=(), camera=()\nReferrer-Policy: strict-origin-when-cross-origin\nX-Content-Type-Options: nosniff\nX-Frame-Options: SAMEORIGIN\n```\n\nThis preset reflects modern browser guidance from MDN and OWASP. It reduces cross-origin risk, prevents MIME sniffing, and provides a conservative Content Security Policy you can extend.\n\nThe default CSP avoids unsafe script execution by default, but CSP is context-sensitive. Interactive apps, dashboards, CDNs, analytics, embedded content, or other third-party integrations may require additional configuration.\n\n---\n\n## Presets\n\n```python\nfrom secure import Preset, Secure\n\nSecure.from_preset(Preset.BALANCED)\nSecure.from_preset(Preset.BASIC)\nSecure.from_preset(Preset.STRICT)\n```\n\n- **BALANCED**: practical default for many applications\n- **BASIC**: Helmet-style compatibility\n- **STRICT**: tighter CSP and isolation\n\nStart with BALANCED, review the generated headers, and move stricter only when needed.\n\n---\n\n## Middleware\n\n`secure` provides both ASGI and WSGI middleware.\n\n- Overwrites headers by default\n- Allows controlled duplication via `multi_ok`\n- Only modifies HTTP responses in ASGI apps\n\n### ASGI\n\n```python\nfrom secure import Secure\nfrom secure.middleware import SecureASGIMiddleware\n\nsecure_headers = Secure.with_default_headers()\napp = SecureASGIMiddleware(app, secure=secure_headers)\n```\n\n### WSGI\n\n```python\nfrom secure import Secure\nfrom secure.middleware import SecureWSGIMiddleware\n\nsecure_headers = Secure.with_default_headers()\napp = SecureWSGIMiddleware(app, secure=secure_headers)\n```\n\n### Django example\n\n```python\nfrom secure import Secure\n\nclass SecureHeadersMiddleware:\n def __init__(self, get_response):\n self.get_response = get_response\n self.secure = Secure.with_default_headers()\n\n def __call__(self, request):\n response = self.get_response(request)\n self.secure.set_headers(response)\n return response\n```\n\n---\n\n## Framework integration examples\n\nThese examples show common integration paths. See the full [framework integration guide](https://github.com/TypeError/secure/tree/main/docs/frameworks.md) for additional frameworks and notes about first-class middleware versus minimal fallback examples.\n\n### FastAPI\n\n```python\nfrom secure.middleware import SecureASGIMiddleware\n\napp.add_middleware(SecureASGIMiddleware, secure=secure_headers)\n```\n\n### Flask\n\n```python\n@app.after_request\ndef add_security_headers(response):\n secure_headers.set_headers(response)\n return response\n```\n\n### Shiny for Python\n\n```python\nfrom shiny import App\nfrom secure.middleware import SecureASGIMiddleware\n\napp = SecureASGIMiddleware(App(), secure=secure_headers)\n```\n\nInteractive apps often need CSP configuration for their script, style, and asset loading patterns.\n\n---\n\n## Policy builders\n\n### Content Security Policy\n\n```python\nfrom secure.headers import ContentSecurityPolicy\n\ncsp = (\n ContentSecurityPolicy()\n .default_src(\"'self'\")\n .script_src(\"'self'\", \"cdn.example.com\")\n)\n```\n\n### Permissions Policy\n\n```python\nfrom secure.headers import PermissionsPolicy\n\npermissions = (\n PermissionsPolicy()\n .geolocation(\"'self'\")\n .camera(\"'none'\")\n)\n```\n\n---\n\n## Header pipeline and validation\n\nUse the optional pipeline when you need stricter control:\n\n```python\nsecure_headers = (\n Secure.with_default_headers()\n .allowlist_headers(...)\n .deduplicate_headers(...)\n .validate_and_normalize_headers(...)\n)\n```\n\nThis makes header allowlists, deduplication, normalization, and validation explicit instead of leaving those choices spread across application code.\n\n---\n\n## Requirements\n\n- Python 3.10+\n- No external dependencies\n\n---\n\n## Documentation\n\nRead the full [documentation](https://github.com/TypeError/secure/tree/main/docs).\n\n---\n\n## Learn more\n\n- [MDN HTTP Headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers)\n- [OWASP Secure Headers Project](https://owasp.org/www-project-secure-headers/)\n\n---\n\n## License\n\nMIT License\n\n---\n\n## Contributing\n\nIssues and pull requests are welcome.\n\n---\n\n## Acknowledgements\n\nBuilt using guidance from MDN and OWASP secure headers recommendations.\n" }, { "path": "docs/README.md", "content": "# Documentation\n\nUse this index when you know what you need. For a first pass, start with the [top-level README](../README.md), then continue with [Usage](./usage.md).\n\nThe recommended default throughout the docs is `Secure.with_default_headers()`, which maps to `Preset.BALANCED`.\n\n## Start here\n\n- [Installation](./installation.md)\n- [Usage](./usage.md)\n- [Framework integration](./frameworks.md)\n- [Migration notes](./migration.md)\n\n## Reference\n\n- [Configuration](./configuration.md)\n- [Security considerations](./security_considerations.md)\n\n## Header builders\n\n- [Cache-Control](./headers/cache_control.md)\n- [Content-Security-Policy](./headers/content_security_policy.md)\n- [Cross-Origin-Embedder-Policy](./headers/cross_origin_embedder_policy.md)\n- [Cross-Origin-Opener-Policy](./headers/cross_origin_opener_policy.md)\n- [Cross-Origin-Resource-Policy](./headers/cross-origin-resource-policy.md)\n- [Custom Header](./headers/custom_header.md)\n- [Permissions-Policy](./headers/permissions_policy.md)\n- [Referrer-Policy](./headers/referrer_policy.md)\n- [Server](./headers/server.md)\n- [Strict-Transport-Security](./headers/strict_transport_security.md)\n- [X-Content-Type-Options](./headers/x_content_type_options.md)\n- [X-DNS-Prefetch-Control](./headers/dns_prefetch_control.md)\n- [X-Frame-Options](./headers/x_frame_options.md)\n- [X-Permitted-Cross-Domain-Policies](./headers/x-permitted-cross-domain-policies.md)\n" }, { "path": "docs/configuration.md", "content": "# Configuration Guide\n\nThis guide covers the parts of `secure` you are most likely to customize after the quick start. Keep `Secure` as the public entry point and pass it the builders you need.\n\n## Default configuration\n\n`Secure.with_default_headers()` uses `Preset.BALANCED`, which provides a modern baseline while keeping the header set lean:\n\n- **Cross-Origin-Opener-Policy:** `same-origin`\n- **Cross-Origin-Resource-Policy:** `same-origin`\n- **Content-Security-Policy:** `default-src 'self'; base-uri 'self'; font-src 'self' https: data:; form-action 'self'; frame-ancestors 'self'; img-src 'self' data:; object-src 'none'; script-src 'self'; script-src-attr 'none'; style-src 'self' https: 'unsafe-inline'; upgrade-insecure-requests`\n- **Strict-Transport-Security:** `max-age=31536000; includeSubDomains`\n- **Permissions-Policy:** `geolocation=(), microphone=(), camera=()`\n- **Referrer-Policy:** `strict-origin-when-cross-origin`\n- **Server:** empty string\n- **X-Content-Type-Options:** `nosniff`\n- **X-Frame-Options:** `SAMEORIGIN`\n\nBalanced intentionally skips `Cache-Control` and the compatibility headers (`X-Permitted-Cross-Domain-Policies`, `X-DNS-Prefetch-Control`, `Origin-Agent-Cluster`, `X-Download-Options`, `X-XSS-Protection`). Add them explicitly when your deployment still depends on them.\n\n`Preset.BALANCED` is the recommended default. `Preset.BASIC` is the compatibility-oriented option that most closely matches Helmet-style defaults. `Preset.STRICT` is available when you want tighter CSP and stronger isolation. It is not the default.\n\nThe balanced CSP includes `'unsafe-inline'` in `style-src` for compatibility. It does not allow inline scripts by default. If your app needs a looser CSP, treat that as an app-specific adjustment and test it against real behavior.\n\n## Customizing individual builders\n\nAll public header builders are re-exported from `secure`, so most applications can stay on the package-level API.\n\n### `X-Frame-Options`\n\nIf you want to allow framing only from the same origin, use:\n\n```python\nfrom secure import Secure, XFrameOptions\n\nsecure_headers = Secure(xfo=XFrameOptions().sameorigin())\n```\n\nThis protects against clickjacking while still allowing same-origin embedding.\n\n### `Strict-Transport-Security`\n\nTo enforce HTTPS for all subdomains and opt into preload when you are ready, configure HSTS explicitly:\n\n```python\nfrom secure import Secure, StrictTransportSecurity\n\nsecure_headers = Secure(\n hsts=StrictTransportSecurity().max_age(63072000).include_subdomains().preload()\n)\n```\n\nThis enforces HTTPS for two years, applies the rule to subdomains, and opts into the preload list.\n\n## Adding custom headers\n\nUse `CustomHeader` for application-specific response headers that do not have a dedicated builder:\n\n```python\nfrom secure import CustomHeader, Secure\n\ncustom_header = CustomHeader(\"X-Custom-Header\", \"CustomValue\")\nsecure_headers = Secure(custom=[custom_header])\n```\n\n## Starting from a preset\n\nEvery `Secure` instance exposes its configured builders through `headers_list`, so you can replace or extend a preset after construction:\n\n```python\nfrom secure import Preset, Secure, StrictTransportSecurity\n\nsecure_headers = Secure.from_preset(Preset.BALANCED)\n\nsecure_headers.headers_list = [\n header\n for header in secure_headers.headers_list\n if header.header_name != \"Strict-Transport-Security\"\n]\nsecure_headers.headers_list.append(\n StrictTransportSecurity().max_age(63072000).include_subdomains()\n)\n```\n\nThis replaces the preset HSTS builder while leaving the rest of the preset untouched.\nIf you need the compatibility profile instead, start from `Preset.BASIC`.\n\n## Middleware behavior\n\nThe ASGI and WSGI middleware classes use the same `Secure` instance you would use in hooks or handlers:\n\n- Existing header values are overwritten by default for configured header names.\n- Pass `multi_ok` when a header name should be preserved and appended instead.\n- `SecureASGIMiddleware` only changes HTTP responses. WebSocket scopes pass through unchanged.\n\n## Validation and normalization\n\nIf you need stronger guarantees before emission, `Secure` also exposes optional pipeline helpers:\n\n- `allowlist_headers(...)` filters or rejects unexpected header names in the current `headers_list`.\n- `deduplicate_headers(...)` resolves duplicate header names in `headers_list` before you build a single-valued mapping.\n- `validate_and_normalize_headers(...)` validates and normalizes the current `header_items()`, then caches the single-valued mapping used by `.headers`, `set_headers()`, and `set_headers_async()`.\n\nIf you intentionally emit duplicate headers such as multiple `Content-Security-Policy` values, use `header_items()` instead of `.headers`.\n\nFor per-header builder details, see the docs under [headers](./headers).\n" }, { "path": "docs/frameworks.md", "content": "# Framework Integration\n\n`secure` keeps the same `Secure` object across frameworks. What changes is how you attach it.\n\nSome sections below are first-class integrations with clear framework-level hooks or middleware. Others are intentionally minimal fallback examples where support is thinner or framework APIs vary by version.\n\n## How to choose an integration style\n\n- Use `set_headers()` when the response object is synchronous and you are already inside a response hook, middleware callback, or view.\n- Use `set_headers_async()` in async middleware, hooks, or handlers when you want one helper that works safely across async response objects.\n- Use `SecureWSGIMiddleware` when you want app-wide coverage and can wrap a WSGI application directly.\n- Use `SecureASGIMiddleware` when you want app-wide coverage in an ASGI stack such as FastAPI, Starlette, or Shiny.\n\nPrefer middleware when your framework makes it easy and you want app-wide coverage. Use per-response setters when you are integrating into an existing hook, view, or minimal handler path.\n\n## Middleware behavior\n\n`SecureASGIMiddleware` and `SecureWSGIMiddleware` share the same core behavior:\n\n- Configured header names are overwritten by default so stale values do not accumulate.\n- Pass `multi_ok` when a header should be preserved and `secure` should append its own value instead.\n- The default `secure.MULTI_OK` setting allows controlled duplication for headers such as `Content-Security-Policy`.\n- `SecureASGIMiddleware` only modifies HTTP responses. WebSocket and other non-HTTP scopes pass through unchanged.\n\nExample:\n\n```python\nfrom secure import Secure\nfrom secure.middleware import SecureASGIMiddleware\n\nsecure_headers = Secure.with_default_headers()\nsecured_app = SecureASGIMiddleware(app, secure=secure_headers, multi_ok={\"content-security-policy\"})\n```\n\n## Uvicorn `Server` header\n\nUvicorn adds `Server: uvicorn` by default. If you want `secure` to control the `Server` header, disable Uvicorn's default header with `--no-server-header` or `server_header=False`.\n\n```python\nimport uvicorn\n\nuvicorn.run(app, host=\"0.0.0.0\", port=8000, server_header=False)\n```\n\n## Table of contents\n\n- [aiohttp](#aiohttp)\n- [Bottle](#bottle)\n- [CherryPy](#cherrypy)\n- [Dash](#dash)\n- [Django](#django)\n- [Falcon](#falcon)\n- [FastAPI](#fastapi)\n- [Flask](#flask)\n- [Masonite](#masonite)\n- [Morepath](#morepath)\n- [Pyramid](#pyramid)\n- [Quart](#quart)\n- [Responder](#responder)\n- [Sanic](#sanic)\n- [Shiny](#shiny)\n- [Starlette](#starlette)\n- [Tornado](#tornado)\n- [TurboGears](#turbogears)\n- [Custom frameworks](#custom-frameworks)\n\n## aiohttp\n\nAsync framework with first-class middleware support.\n\n### Recommended: middleware with `set_headers_async()`\n\n```python\nfrom aiohttp import web\nfrom secure import Secure\n\nsecure_headers = Secure.with_default_headers()\n\n\n@web.middleware\nasync def add_security_headers(request, handler):\n response = await handler(request)\n await secure_headers.set_headers_async(response)\n return response\n\n\napp = web.Application(middlewares=[add_security_headers])\n```\n\n### Alternative: set headers in a single handler\n\n```python\nfrom aiohttp import web\nfrom secure import Secure\n\nsecure_headers = Secure.with_default_headers()\n\n\nasync def home(request):\n response = web.Response(text=\"Hello, world\")\n await secure_headers.set_headers_async(response)\n return response\n```\n\n## Bottle\n\nSmall WSGI framework with request hooks.\n\n### Recommended: `after_request` hook with `set_headers()`\n\n```python\nfrom bottle import Bottle, response\nfrom secure import Secure\n\napp = Bottle()\nsecure_headers = Secure.with_default_headers()\n\n\n@app.hook(\"after_request\")\ndef add_security_headers():\n secure_headers.set_headers(response)\n```\n\n### Fallback: set headers in a route\n\n```python\nfrom bottle import Bottle, response\nfrom secure import Secure\n\napp = Bottle()\nsecure_headers = Secure.with_default_headers()\n\n\n@app.route(\"/\")\ndef home():\n secure_headers.set_headers(response)\n return \"Hello, world\"\n```\n\n## CherryPy\n\nMinimal fallback example. CherryPy exposes the response object in the handler, so handler-level mutation is the practical integration point.\n\n### Minimal fallback: set headers in the exposed method\n\n```python\nimport cherrypy\nfrom secure import Secure\n\nsecure_headers = Secure.with_default_headers()\n\n\nclass App:\n @cherrypy.expose\n def index(self):\n secure_headers.set_headers(cherrypy.response)\n return b\"Hello, world\"\n\n\ncherrypy.quickstart(App())\n```\n\n## Dash\n\nDash runs on top of Flask, so the usual Flask integration patterns apply.\n\n### Recommended: Flask `after_request` on `app.server`\n\n```python\nimport dash\nfrom dash import html\nfrom secure import Secure\n\napp = dash.Dash(__name__)\nserver = app.server\nsecure_headers = Secure.with_default_headers()\n\napp.layout = html.Div(\"Hello Dash!\")\n\n\n@server.after_request\ndef add_security_headers(response):\n secure_headers.set_headers(response)\n return response\n```\n\n### Alternative: `SecureWSGIMiddleware`\n\n```python\nimport dash\nfrom dash import html\nfrom secure import Secure\nfrom secure.middleware import SecureWSGIMiddleware\n\napp = dash.Dash(__name__)\nserver = app.server\nsecure_headers = Secure.with_default_headers()\n\napp.layout = html.Div(\"Hello Dash!\")\nserver.wsgi_app = SecureWSGIMiddleware(server.wsgi_app, secure=secure_headers)\n```\n\n## Django\n\nDjango is usually best integrated through Django middleware rather than raw WSGI wrapping.\n\n### Recommended: Django middleware class\n\nRegister the middleware class in your Django `MIDDLEWARE` setting.\n\n```python\nfrom secure import Secure\n\n\nclass SecureHeadersMiddleware:\n def __init__(self, get_response):\n self.get_response = get_response\n self.secure = Secure.with_default_headers()\n\n def __call__(self, request):\n response = self.get_response(request)\n self.secure.set_headers(response)\n return response\n```\n\n### Fallback: set headers in a view\n\n```python\nfrom django.http import HttpResponse\nfrom secure import Secure\n\nsecure_headers = Secure.with_default_headers()\n\n\ndef home(request):\n response = HttpResponse(\"Hello, world\")\n secure_headers.set_headers(response)\n return response\n```\n\n## Falcon\n\nFalcon exposes a clean response middleware hook.\n\n### Recommended: Falcon middleware\n\n```python\nimport falcon\nfrom secure import Secure\n\nsecure_headers = Secure.with_default_headers()\n\n\nclass SecureMiddleware:\n def process_response(self, req, resp, resource, req_succeeded):\n secure_headers.set_headers(resp)\n\n\napp = falcon.App(middleware=[SecureMiddleware()])\n```\n\n### Fallback: set headers in the resource\n\n```python\nimport falcon\nfrom secure import Secure\n\nsecure_headers = Secure.with_default_headers()\n\n\nclass HelloWorldResource:\n def on_get(self, req, resp):\n resp.text = \"Hello, world\"\n secure_headers.set_headers(resp)\n\n\napp = falcon.App()\napp.add_route(\"/\", HelloWorldResource())\n```\n\n## FastAPI\n\nASGI framework. Middleware is the clearest default.\n\n### Recommended: `SecureASGIMiddleware`\n\n```python\nfrom fastapi import FastAPI\nfrom secure import Secure\nfrom secure.middleware import SecureASGIMiddleware\n\napp = FastAPI()\nsecure_headers = Secure.with_default_headers()\n\napp.add_middleware(SecureASGIMiddleware, secure=secure_headers)\n```\n\n### Alternative: `@app.middleware(\"http\")`\n\n```python\nfrom fastapi import FastAPI\nfrom secure import Secure\n\napp = FastAPI()\nsecure_headers = Secure.with_default_headers()\n\n\n@app.middleware(\"http\")\nasync def add_security_headers(request, call_next):\n response = await call_next(request)\n await secure_headers.set_headers_async(response)\n return response\n```\n\n### Fallback: set headers in one route\n\n```python\nfrom fastapi import FastAPI, Response\nfrom secure import Secure\n\napp = FastAPI()\nsecure_headers = Secure.with_default_headers()\n\n\n@app.get(\"/\")\ndef home(response: Response):\n secure_headers.set_headers(response)\n return {\"hello\": \"world\"}\n```\n\n## Flask\n\nWSGI framework with a straightforward response hook.\n\n### Recommended: `after_request`\n\n```python\nfrom flask import Flask\nfrom secure import Secure\n\napp = Flask(__name__)\nsecure_headers = Secure.with_default_headers()\n\n\n@app.after_request\ndef add_security_headers(response):\n secure_headers.set_headers(response)\n return response\n```\n\n### Alternative: `SecureWSGIMiddleware`\n\n```python\nfrom flask import Flask\nfrom secure import Secure\nfrom secure.middleware import SecureWSGIMiddleware\n\napp = Flask(__name__)\nsecure_headers = Secure.with_default_headers()\n\napp.wsgi_app = SecureWSGIMiddleware(app.wsgi_app, secure=secure_headers)\n```\n\n## Masonite\n\nMinimal fallback example. Masonite routing and response APIs vary by version, so apply `Secure` to the response object you actually return.\n\n### Minimal fallback: apply to the response you return\n\n```python\nfrom secure import Secure\n\nsecure_headers = Secure.with_default_headers()\n\n\ndef home(response):\n rendered = response.json({\"hello\": \"world\"})\n secure_headers.set_headers(rendered)\n return rendered\n```\n\n## Morepath\n\nMinimal fallback example. Morepath does not expose a conventional middleware layer for this, so view-level mutation is the practical integration point.\n\n### Minimal fallback: set headers in the view\n\n```python\nimport morepath\nfrom secure import Secure\n\nsecure_headers = Secure.with_default_headers()\n\n\nclass App(morepath.App):\n pass\n\n\n@App.path(path=\"\")\nclass Root:\n pass\n\n\n@App.view(model=Root)\ndef home(self, request):\n response = morepath.Response(\"Hello, world\")\n secure_headers.set_headers(response)\n return response\n```\n\n## Pyramid\n\nPyramid applications commonly use tweens for cross-cutting response changes.\n\n### Recommended: tween\n\nRegister the tween in your `Configurator` with `config.add_tween(\"yourpackage.security.add_security_headers\")`.\n\n```python\nfrom secure import Secure\n\nsecure_headers = Secure.with_default_headers()\n\n\ndef add_security_headers(handler, registry):\n def tween(request):\n response = handler(request)\n secure_headers.set_headers(response)\n return response\n\n return tween\n```\n\n### Fallback: set headers in a view\n\n```python\nfrom pyramid.response import Response\nfrom secure import Secure\n\nsecure_headers = Secure.with_default_headers()\n\n\ndef home(request):\n response = Response(\"Hello, world\")\n secure_headers.set_headers(response)\n return response\n```\n\n## Quart\n\nAsync Flask-compatible framework.\n\n### Recommended: `after_request` with `set_headers_async()`\n\n```python\nfrom quart import Quart\nfrom secure import Secure\n\napp = Quart(__name__)\nsecure_headers = Secure.with_default_headers()\n\n\n@app.after_request\nasync def add_security_headers(response):\n await secure_headers.set_headers_async(response)\n return response\n```\n\n### Fallback: set headers in a route\n\n```python\nfrom quart import Quart, Response\nfrom secure import Secure\n\napp = Quart(__name__)\nsecure_headers = Secure.with_default_headers()\n\n\n@app.route(\"/\")\nasync def home():\n response = Response(\"Hello, world\")\n await secure_headers.set_headers_async(response)\n return response\n```\n\n## Responder\n\nMinimal fallback example. Route handlers typically own the response, so route-level mutation is the practical integration point.\n\n### Minimal fallback: set headers in the route\n\n```python\nimport responder\nfrom secure import Secure\n\napi = responder.API()\nsecure_headers = Secure.with_default_headers()\n\n\n@api.route(\"/\")\nasync def home(req, resp):\n resp.text = \"Hello, world\"\n await secure_headers.set_headers_async(resp)\n```\n\n## Sanic\n\nSanic exposes response middleware for app-wide coverage.\n\n### Recommended: response middleware with `set_headers_async()`\n\n```python\nfrom sanic import Sanic\nfrom secure import Secure\n\napp = Sanic(\"secure-app\")\nsecure_headers = Secure.with_default_headers()\n\n\n@app.middleware(\"response\")\nasync def add_security_headers(request, response):\n await secure_headers.set_headers_async(response)\n return response\n```\n\nUse route-level setters when you only need a small integration or do not want extra app wiring in tests.\n\n### Fallback: set headers in a route\n\n```python\nfrom sanic import Sanic, response\nfrom secure import Secure\n\napp = Sanic(\"secure-app\")\nsecure_headers = Secure.with_default_headers()\n\n\n@app.get(\"/\")\nasync def home(request):\n resp = response.text(\"Hello, world\")\n await secure_headers.set_headers_async(resp)\n return resp\n```\n\n## Shiny\n\nShiny applications are ASGI apps, so ASGI middleware is the cleanest and most direct path.\n\n### Recommended: `SecureASGIMiddleware`\n\n```python\nfrom secure import Secure\nfrom secure.middleware import SecureASGIMiddleware\nfrom shiny import App, ui\n\nsecure_headers = Secure.with_default_headers()\n\napp_ui = ui.page_fluid(\"Hello Shiny!\")\n\n\ndef server(input, output, session):\n pass\n\n\napp = App(app_ui, server)\napp = SecureASGIMiddleware(app, secure=secure_headers)\n```\n\nIf your Shiny app loads external assets or opens additional browser connections, you may need to extend CSP directives such as `connect-src`, `script-src`, or `style-src`. Start from the balanced preset and test the running app before relaxing the policy.\n\n## Starlette\n\nASGI framework. Use ASGI middleware unless you only need route-level control.\n\n### Recommended: `SecureASGIMiddleware`\n\n```python\nfrom secure import Secure\nfrom secure.middleware import SecureASGIMiddleware\nfrom starlette.applications import Starlette\nfrom starlette.responses import PlainTextResponse\nfrom starlette.routing import Route\n\nsecure_headers = Secure.with_default_headers()\n\n\nasync def home(request):\n return PlainTextResponse(\"Hello, world\")\n\n\napp = Starlette(routes=[Route(\"/\", home)])\napp.add_middleware(SecureASGIMiddleware, secure=secure_headers)\n```\n\n### Alternative: set headers in an endpoint\n\n```python\nfrom secure import Secure\nfrom starlette.applications import Starlette\nfrom starlette.responses import Response\nfrom starlette.routing import Route\n\nsecure_headers = Secure.with_default_headers()\n\n\nasync def home(request):\n response = Response(\"Hello, world\")\n await secure_headers.set_headers_async(response)\n return response\n\n\napp = Starlette(routes=[Route(\"/\", home)])\n```\n\n## Tornado\n\nMinimal fallback example. Tornado usually applies headers inside request handlers, so handler-level mutation is the practical integration point.\n\n### Minimal fallback: set headers in the handler\n\n```python\nimport tornado.web\nfrom secure import Secure\n\nsecure_headers = Secure.with_default_headers()\n\n\nclass MainHandler(tornado.web.RequestHandler):\n def get(self):\n self.write(\"Hello, world\")\n secure_headers.set_headers(self)\n\n\napp = tornado.web.Application([(r\"/\", MainHandler)])\n```\n\n## TurboGears\n\nMinimal fallback example. If you do not already have a framework-level hook in place, controller-level mutation is the practical integration point.\n\n### Minimal fallback: set headers in the controller\n\n```python\nfrom tg import Response, TGController, expose\nfrom secure import Secure\n\nsecure_headers = Secure.with_default_headers()\n\n\nclass RootController(TGController):\n @expose()\n def index(self):\n response = Response(\"Hello, world\")\n secure_headers.set_headers(response)\n return response\n\n\nroot = RootController()\n```\n\n## Custom frameworks\n\nIf your framework is not listed here, the integration rule is still simple: configure one `Secure` instance, then apply it to the response as late as possible before it is sent.\n\n### Recommended: use the response object's setter or headers mapping\n\n```python\nfrom secure import Secure\n\nsecure_headers = Secure.with_default_headers()\n\n\ndef add_security_headers(response):\n secure_headers.set_headers(response)\n return response\n```\n\n### Fallback: emit header pairs manually\n\n```python\nfrom secure import Secure\n\nsecure_headers = Secure.with_default_headers()\n\nfor name, value in secure_headers.header_items():\n response.headers[name] = value\n```\n" }, { "path": "docs/headers/cache_control.md", "content": "# Cache-Control\n\n## What it does\n\n`Cache-Control` is a comma-separated list of **directives** that control caching behavior for both **requests** and **responses**. Used correctly, it helps prevent sensitive data from being cached and improves performance for cacheable assets.\n\n## Minimal example\n\n```python\nfrom secure import CacheControl, Secure\n\nsecure_headers = Secure(\n cache=CacheControl().no_store().max_age(0)\n)\n```\n\n## Resulting header\n\n```http\nCache-Control: no-store, max-age=0\n```\n\n## Practical note\n\nUse `no-store` for sensitive pages such as sign-in or account settings. `no-cache` is different. It allows storage but requires revalidation before reuse.\n\n## Default behavior\n\nIf you create `CacheControl()` and do not add directives, it returns the library default value:\n\n- **Default header value:** `no-store, max-age=0`\n\nThis is a secure baseline intended to prevent storage of sensitive responses.\n\n## Using with `Secure`\n\nIf you do not configure any directives, the default value is emitted.\n`Preset.STRICT` includes `Cache-Control: no-store, max-age=0`; `Preset.BASIC` and `Preset.BALANCED` leave caching unchanged unless you add this builder.\n\n## Common recipes\n\n### 1) Prevent storing (recommended for sensitive responses)\n\n```python\nfrom secure import CacheControl\n\ncc = CacheControl() # default: no-store, max-age=0\nprint(cc.header_name) # Cache-Control\nprint(cc.header_value) # no-store, max-age=0\n```\n\n### 2) Always revalidate (useful for dynamic HTML)\n\n```python\ncc = CacheControl().no_cache()\nprint(cc.header_value) # no-cache\n```\n\n> Note: `no-cache` does **not** mean “do not store.” It means “store, but revalidate before reuse.”\n\n### 3) Cache-busted static assets (long-lived)\n\nIf your assets are fingerprinted (e.g., `/app.4f3c1.js`), you can cache them aggressively:\n\n```python\ncc = CacheControl().public().max_age(31536000).immutable()\nprint(cc.header_value) # public, max-age=31536000, immutable\n```\n\n### 4) Shared caches (CDNs/proxies) vs browser caches\n\n```python\ncc = CacheControl().s_maxage(604800).max_age(60)\nprint(cc.header_value) # s-maxage=604800, max-age=60\n```\n\n`s-maxage` applies to shared caches and overrides `max-age` for them.\n\n### 5) Stale content during revalidation / on error\n\n```python\ncc = (\n CacheControl()\n .max_age(604800)\n .stale_while_revalidate(86400)\n .stale_if_error(86400)\n)\nprint(cc.header_value) # max-age=604800, stale-while-revalidate=86400, stale-if-error=86400\n```\n\n## Builder API\n\n### Boolean directives (no value)\n\n- `.no_store()`, `.no_cache()`, `.no_transform()`\n- `.public()`, `.private()`\n- `.must_revalidate()`, `.proxy_revalidate()`\n- `.immutable()`\n- `.must_understand()` (recommended to pair with `.no_store()` for safe fallback)\n\n### Parameterized directives (integer seconds)\n\n- `.max_age(seconds)`\n- `.s_maxage(seconds)`\n- `.min_fresh(seconds)` (request)\n- `.stale_while_revalidate(seconds)`\n- `.stale_if_error(seconds)`\n\n### Request directives\n\n- `.only_if_cached()`\n- `.max_stale(seconds=None)` (if omitted, accepts staleness of any age)\n\n## Escape hatches\n\n### `.value(\"...\")`\n\nSet an explicit header value (replaces all configured directives):\n\n```python\ncc = CacheControl().value(\"no-store, max-age=0\")\nprint(cc.header_value) # no-store, max-age=0\n```\n\n### `.custom(\"token\")`\n\nAdd a **non-standard / non-MDN** directive token (for niche proxies/CDNs):\n\n```python\ncc = CacheControl().custom(\"x-cache-mode=aggressive\")\nprint(cc.header_value) # x-cache-mode=aggressive\n```\n\n### `.clear()`\n\nReset to the default (no directives configured; default value will be returned).\n\n## Deterministic output & overwrites\n\n- Directives are rendered as a **stable**, comma-separated list.\n- Repeating a parameterized directive overwrites the previous value (e.g., calling `.max_age(60)` then `.max_age(0)` results in `max-age=0`).\n- The builder rejects obvious header-splitting primitives (CR/LF) in `.value(...)` and `.custom(...)`.\n\n## Attribution\n\nThis library implements security recommendations and behavior described by:\n\n- [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Cache-Control) (licensed under [CC-BY-SA 2.5](https://creativecommons.org/licenses/by-sa/2.5/))\n- [OWASP Secure Headers Project](https://owasp.org/www-project-secure-headers/#cache-control) (licensed under [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/))\n" }, { "path": "docs/headers/content_security_policy.md", "content": "# Content-Security-Policy (CSP)\n\n## What it does\n\nThe `Content-Security-Policy` (CSP) response header helps mitigate cross-site scripting (XSS), data injection, and related attacks by restricting where content can be loaded from (scripts, styles, images, fonts, connections, frames, etc.).\n\nCSP is expressed as a list of **directives** separated by semicolons:\n\n```http\nContent-Security-Policy: default-src 'self'; script-src 'self'; object-src 'none'\n```\n\n## Minimal example\n\n```python\nfrom secure import ContentSecurityPolicy, Secure\n\ncsp = (\n ContentSecurityPolicy()\n .default_src(\"'self'\")\n .object_src(\"'none'\")\n .base_uri(\"'self'\")\n)\n\nsecure_headers = Secure(csp=csp)\n```\n\n## Resulting header\n\n```http\nContent-Security-Policy: default-src 'self'; object-src 'none'; base-uri 'self'\n```\n\n## Practical note\n\nDo not treat `'unsafe-inline'` as a default starting point for scripts. Use it only as an app-specific compatibility adjustment and test the real app before and after any CSP change.\n\n## Library defaults\n\nIf you create a `ContentSecurityPolicy()` and do not configure any directives, it returns the library default:\n\n```text\ndefault-src 'self'; script-src 'self'; style-src 'self'; object-src 'none'; base-uri 'self'; frame-ancestors 'self'; form-action 'self'\n```\n\nThis matches the builder default.\nThe built-in presets use explicit CSP builders rather than this bare builder default. `Preset.BASIC` and `Preset.BALANCED` add `font-src`, `img-src`, `script-src-attr`, `style-src`, and `upgrade-insecure-requests`.\n\n## Best-practice baseline\n\nA common “safe baseline” CSP includes:\n\n- `default-src 'self'`\n- `object-src 'none'`\n- `base-uri 'self'`\n- `frame-ancestors 'self'` (or `'none'` if you never want to be framed)\n- `form-action 'self'`\n- optionally `upgrade-insecure-requests`\n\n> CSP is powerful but can break applications if rolled out too aggressively. Start with a report-only policy, review violations, then enforce.\n\n---\n\n## Configuration with `Secure`\n\nOnce you configure `csp`, apply it in your framework integration:\n\n```python\n# Flask example\nfrom flask import Flask, Response\n\napp = Flask(__name__)\nsecure_headers = Secure(csp=csp)\n\n@app.after_request\ndef add_security_headers(response: Response) -> Response:\n secure_headers.set_headers(response)\n return response\n```\n\n### Report-only mode\n\nTo observe violations without enforcing (recommended for rollout):\n\n```python\ncsp_report_only = (\n ContentSecurityPolicy()\n .report_only()\n .default_src(\"'self'\")\n .script_src(\"'self'\")\n)\n\nsecure_headers = Secure(csp=csp_report_only)\n```\n\nUse `.enforce()` to switch back to the enforcing header name.\n\n---\n\n## Fluent directive methods\n\nCommon methods include:\n\n- Fetch directives: `default_src`, `script_src`, `style_src`, `img_src`, `font_src`, `connect_src`, `media_src`, `frame_src`, `worker_src`, `manifest_src`, `fenced_frame_src`, `object_src`\n- Navigation / embedding: `base_uri`, `form_action`, `frame_ancestors`\n- Policy controls: `sandbox`, `upgrade_insecure_requests`\n- Reporting: `report_to`, `report_uri` _(deprecated in MDN)_\n\n### Deterministic output and deduplication\n\n- Each directive name appears at most once.\n- Tokens passed to a directive are deduplicated (first-seen order preserved).\n- Serialization is deterministic and uses `\"; \"` between directives.\n\n---\n\n## Helper utilities\n\n### Keywords\n\nUse `keyword()` to safely produce quoted CSP keywords like `'self'` and `'none'`:\n\n```python\nContentSecurityPolicy.keyword(\"self\") # \"'self'\"\nContentSecurityPolicy.keyword(\"none\") # \"'none'\"\n```\n\n### Nonces\n\nUse `nonce()` to produce a CSP nonce source expression:\n\n```python\nnonce_value = \"abc123==\" # base64 / url-safe base64\nContentSecurityPolicy.nonce(nonce_value) # \"'nonce-abc123=='\"\n```\n\n---\n\n## Escape hatches\n\n### Set an exact policy string\n\nIf you need full control (or want to carry over an existing CSP string), use `.value(...)`:\n\n```python\ncsp = ContentSecurityPolicy().value(\n \"default-src 'self'; script-src 'self' https://cdn.example; object-src 'none'\"\n)\n```\n\n`.set(...)` is an alias for `.value(...)`.\n\n### Clear configuration\n\n```python\ncsp = ContentSecurityPolicy().default_src(ContentSecurityPolicy.keyword(\"self\"))\ncsp.clear() # resets back to library default behavior\n```\n\n### Custom directives\n\nIf you need a directive not covered by a helper method:\n\n```python\ncsp = (\n ContentSecurityPolicy()\n .custom_directive(\"default-src\", \"'self'\")\n .custom_directive(\"script-src\", \"'self'\")\n)\n\n# `.custom(...)` is an alias\n```\n\n---\n\n## Nonce + `strict-dynamic` example (recommended pattern)\n\nWhen you use nonces, the nonce must be generated **per response** and also placed in your HTML script tag(s).\nA common pattern is to generate the nonce in request context, then build CSP using it.\n\n### Framework-agnostic CSP construction\n\n```python\nimport secrets\nfrom secure import ContentSecurityPolicy\n\nnonce = secrets.token_urlsafe(16)\n\ncsp = (\n ContentSecurityPolicy()\n .default_src(\"'self'\")\n .script_src(\n ContentSecurityPolicy.nonce(nonce),\n ContentSecurityPolicy.keyword(\"strict-dynamic\"),\n )\n .object_src(\"'none'\")\n)\n\nprint(csp.header_value)\n# default-src 'self'; script-src 'nonce-...' 'strict-dynamic'; object-src 'none'\n```\n\n### Flask pattern (nonce shared via `g`)\n\n```python\nimport secrets\nfrom flask import Flask, Response, g\n\nfrom secure import ContentSecurityPolicy, Secure\n\napp = Flask(__name__)\n\n@app.before_request\ndef set_nonce() -> None:\n g.csp_nonce = secrets.token_urlsafe(16)\n\n@app.after_request\ndef add_security_headers(response: Response) -> Response:\n csp = (\n ContentSecurityPolicy()\n .default_src(\"'self'\")\n .script_src(\n ContentSecurityPolicy.nonce(g.csp_nonce),\n ContentSecurityPolicy.keyword(\"strict-dynamic\"),\n )\n .style_src(\"'self'\")\n .object_src(\"'none'\")\n )\n Secure(csp=csp).set_headers(response)\n return response\n```\n\nIn your HTML rendering, use the same nonce:\n\n```html\n\n```\n\n---\n\n## Reporting notes (MDN)\n\n- `report-to` is the modern mechanism.\n- `report-uri` is deprecated in MDN; some browsers that support `report-to` may ignore `report-uri`.\n- If you need broad compatibility during migration, you may specify both.\n\n---\n\n## References\n\n- [MDN: Content-Security-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy)\n- [MDN: CSP guide](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP)\n- [OWASP Secure Headers Project](https://owasp.org/www-project-secure-headers/#content-security-policy)\n\n## Attribution\n\nThis library implements security recommendations and reference material from:\n\n- MDN Web Docs (licensed under CC-BY-SA 2.5)\n- OWASP Secure Headers Project (licensed under CC-BY-SA 4.0)\n" }, { "path": "docs/headers/cross-origin-resource-policy.md", "content": "# Cross-Origin-Resource-Policy (CORP)\n\n## What it does\n\nThe `Cross-Origin-Resource-Policy` (CORP) response header lets a **resource owner** declare what sites/origins are allowed to load that resource.\n\nThis header is commonly used to reduce cross-origin data leaks by controlling who can load your resources (images, scripts, etc.) and by blocking certain cross-origin/cross-site `no-cors` requests when the policy is more restrictive.\n\n## Minimal example\n\n```python\nfrom secure import CrossOriginResourcePolicy, Secure\n\nsecure_headers = Secure(\n corp=CrossOriginResourcePolicy().same_origin()\n)\n```\n\n## Resulting header\n\n```http\nCross-Origin-Resource-Policy: same-origin\n```\n\n## Practical note\n\n`same-origin` is a good default for sensitive resources. If you serve shared assets across subdomains, test `same-site` carefully before widening the policy further.\n\n## Best Practices\n\n- **`same-origin`**: Strong default for sensitive resources; only allow loads from the same origin.\n- **`same-site`**: Useful when you need to share resources across subdomains on the same “site” but not with unrelated sites.\n- **`cross-origin`**: Most permissive; allow any origin to load the resource (use intentionally, not by accident).\n\n## Configuration with `Secure`\n\nThe `CrossOriginResourcePolicy` class provides a fluent API for setting CORP directives and integrates cleanly with `Secure(...)`.\n\n> Library default: if you do not change it, the library’s default value is `same-origin`.\n> Presets: `Preset.BASIC` and `Preset.BALANCED` include `same-origin`; `Preset.STRICT` does not add CORP by default.\n\n### Methods Available\n\n- **`same_origin()`**: Set `Cross-Origin-Resource-Policy: same-origin`\n- **`same_site()`**: Set `Cross-Origin-Resource-Policy: same-site`\n- **`cross_origin()`**: Set `Cross-Origin-Resource-Policy: cross-origin`\n- **`value(value)`**: Set an explicit value (escape hatch; canonicalizes known directives)\n- **`clear()`**: Reset to the library default value\n- **`set(value)`**: Backwards-compatible alias for `value(...)`\n\n## Example Usage\n\nTo restrict resource loading to the same origin:\n\n```python\ncorp = CrossOriginResourcePolicy().same_origin()\nprint(corp.header_name) # Output: 'Cross-Origin-Resource-Policy'\nprint(corp.header_value) # Output: 'same-origin'\n```\n\nTo allow resource loading from the same site (useful for subdomains):\n\n```python\ncorp = CrossOriginResourcePolicy().same_site()\nprint(corp.header_value) # Output: 'same-site'\n```\n\n## **Attribution**\n\nThis library implements security recommendations from trusted sources:\n\n- [MDN Web Docs: `Cross-Origin-Resource-Policy`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Cross-Origin-Resource-Policy) (licensed under [CC-BY-SA 2.5](https://creativecommons.org/licenses/by-sa/2.5/))\n- [OWASP Secure Headers Project: Cross-Origin-Resource-Policy](https://owasp.org/www-project-secure-headers/#cross-origin-resource-policy) (licensed under [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/))\n" }, { "path": "docs/headers/cross_origin_embedder_policy.md", "content": "# Cross-Origin-Embedder-Policy (COEP)\n\n## What it does\n\nThe **`Cross-Origin-Embedder-Policy`** response header configures the current document’s policy for **loading and embedding cross-origin resources**.\n\nAt a high level, COEP lets you:\n\n- keep the default behavior (`unsafe-none`),\n- require explicit opt-in via **CORP** (`Cross-Origin-Resource-Policy`) and/or **CORS** (`require-corp`), or\n- allow some cross-origin loading while **stripping credentials** (`credentialless`).\n\n## Minimal example\n\n```python\nfrom secure import CrossOriginEmbedderPolicy, CrossOriginOpenerPolicy, Secure\n\nsecure_headers = Secure(\n coep=CrossOriginEmbedderPolicy().require_corp(),\n coop=CrossOriginOpenerPolicy().same_origin(),\n)\n```\n\n## Resulting header\n\n```http\nCross-Origin-Embedder-Policy: require-corp\n```\n\n## Practical note\n\nCOEP is most useful when you are intentionally working toward cross-origin isolation. It can break third-party assets that do not send compatible CORP or CORS headers, so test the full app before enabling it broadly.\n\n## Directive values\n\nCOEP is a **single-value** header (choose one):\n\n| Value | Meaning |\n| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `unsafe-none` | Allows cross-origin resources **without** explicit permission via CORP or CORS. _(This is the browser default if the header is not sent.)_ |\n| `require-corp` | Blocks cross-origin resource loading unless the resource is permitted via **CORP** (for `no-cors` requests) or via **CORS** (for `cors` requests). |\n| `credentialless` | Allows `no-cors` cross-origin resource loading **without** CORP opt-in, but sends requests **without credentials** (cookies omitted and ignored). For other request modes, behavior matches `require-corp`. |\n\n## Library default vs browser default\n\n- **Browser behavior when the header is absent:** `unsafe-none`.\n- **This library’s builder default:** `require-corp` (a stricter, security-forward default).\n\nIf you want “no-op” behavior, you must explicitly choose it:\n\n```python\nfrom secure import CrossOriginEmbedderPolicy\n\ncoep = CrossOriginEmbedderPolicy().unsafe_none()\n```\n\n## Cross-origin isolation (COOP + COEP)\n\nSome powerful browser features require your document to be **cross-origin isolated**. To enable this, you generally need:\n\n- `Cross-Origin-Embedder-Policy: require-corp` **or** `credentialless`, and\n- `Cross-Origin-Opener-Policy: same-origin`.\n\n## Usage with `Secure`\n\nYou can inspect the emitted header pairs with `secure_headers.header_items()` if you need to confirm the final output.\n\n`Preset.STRICT` includes COEP by default; `Preset.BASIC` and `Preset.BALANCED` do not.\n\n## Header builder API\n\n```python\nfrom secure import CrossOriginEmbedderPolicy\n\ncoep = (\n CrossOriginEmbedderPolicy()\n .credentialless() # or .require_corp() / .unsafe_none()\n)\n\nprint(coep.header_name) # \"Cross-Origin-Embedder-Policy\"\nprint(coep.header_value) # \"credentialless\"\n```\n\n### Methods\n\n- `unsafe_none()`: set the value to `unsafe-none`\n- `require_corp()`: set the value to `require-corp`\n- `credentialless()`: set the value to `credentialless`\n- `set(value)`: set a custom value\n- `clear()`: reset to the library default (`require-corp`)\n\n## Notes / gotchas\n\n- `require-corp` can break embedding third-party resources unless they opt-in via CORP or are requested in `cors` mode.\n- `credentialless` can be a pragmatic alternative for some `no-cors` resources, but it comes with the tradeoff of **no cookies/credentials**.\n\n## Attribution\n\nThis library implements security recommendations and definitions from trusted sources:\n\n- [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Cross-Origin-Embedder-Policy) (CC-BY-SA 2.5)\n- [OWASP Secure Headers Project](https://owasp.org/www-project-secure-headers/#cross-origin-embedder-policy) (CC-BY-SA 4.0)\n" }, { "path": "docs/headers/cross_origin_opener_policy.md", "content": "# Cross-Origin-Opener-Policy\n\n## What it does\n\nThe `Cross-Origin-Opener-Policy` (COOP) response header controls whether documents opened via `Window.open()` (or navigations) share the same **browsing context group (BCG)** as their opener. When a document is opened into a new BCG, references between the opener and the opened document are severed, which helps mitigate cross-origin attacks often referred to as **XS-Leaks**.\n\n## Minimal example\n\n```python\nfrom secure import CrossOriginOpenerPolicy, Secure\n\nsecure_headers = Secure(\n coop=CrossOriginOpenerPolicy().same_origin()\n)\n```\n\n## Resulting header\n\n```http\nCross-Origin-Opener-Policy: same-origin\n```\n\n## Practical note\n\n`same-origin` is a strong default, but popup-based flows such as OAuth or payment providers sometimes need `same-origin-allow-popups`. Test those flows before tightening COOP.\n\n## Defaults\n\n- **Browser/spec behavior:** If the header is **absent**, the effective behavior is equivalent to `unsafe-none` (opt-out).\n- **Library default:** This library’s builder defaults to `same-origin` (a secure default), and the built-in presets also configure COOP as `same-origin`.\n\n## Best Practices\n\n- **`same-origin`**: Strong isolation; commonly used for cross-origin isolation (often paired with COEP).\n- **`same-origin-allow-popups`**: Like `same-origin`, but relaxes behavior for integrations that open trusted popups/tabs that opt out (e.g., OAuth/payment flows).\n- **`noopener-allow-popups`**: Always isolates into a new BCG (except when opened by a same-origin document that also uses `noopener-allow-popups`). Useful when you need to isolate **same-origin** apps from each other (e.g., `/chat` vs `/passwords`) while still allowing popups.\n- **`unsafe-none`**: Opts out of COOP isolation.\n\n## Configuration with `Secure`\n\nUse the `CrossOriginOpenerPolicy` builder and pass it into `Secure(...)`.\n\n## Methods Available\n\nDirective helpers (recommended):\n\n- `same_origin()`\n- `same_origin_allow_popups()`\n- `noopener_allow_popups()`\n- `unsafe_none()`\n\nEscape hatches:\n\n- `value(\"...\")` / `custom(\"...\")`: Set a raw value (rejects CR/LF).\n- `set(\"...\")`: Backwards-compatible alias for `value(...)`.\n- `clear()`: Reset back to the library default (`same-origin`).\n\n## Example Usage\n\n```python\nfrom secure import CrossOriginOpenerPolicy, Secure\n\ncoop = CrossOriginOpenerPolicy().same_origin()\nprint(coop.header_name) # 'Cross-Origin-Opener-Policy'\nprint(coop.header_value) # 'same-origin'\n\nsecure_headers = Secure(coop=coop)\n```\n\n## Notes\n\n- For **cross-origin isolation** (e.g., `SharedArrayBuffer`), COOP is typically paired with **COEP** (often `require-corp`), and your app must satisfy other isolation requirements.\n\n## Attribution\n\nThis library implements security recommendations from trusted sources:\n\n- [MDN Web Docs: Cross-Origin-Opener-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Cross-Origin-Opener-Policy) (licensed under [CC-BY-SA 2.5](https://creativecommons.org/licenses/by-sa/2.5/))\n- [OWASP Secure Headers Project](https://owasp.org/www-project-secure-headers/#cross-origin-opener-policy) (licensed under [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/))\n" }, { "path": "docs/headers/custom_header.md", "content": "# CustomHeader Class\n\n## What it does\n\nThe `CustomHeader` class lets you create arbitrary HTTP response headers when `secure` does not provide a dedicated builder.\n\n## Minimal example\n\n```python\nfrom secure import CustomHeader, Secure\n\ncustom_header = CustomHeader(\"X-Custom-Header\", \"CustomValue\")\nsecure_headers = Secure(custom=[custom_header])\n```\n\n## Resulting header\n\n```http\nX-Custom-Header: CustomValue\n```\n\n## Practical note\n\nUse `CustomHeader` for app-specific or infrastructure-specific headers. If you later call `allowlist_headers(...)`, remember to allow the custom name explicitly when needed.\n\n## Best Practices\n\n- Prefer standard header names when they exist; use custom names only for application- or infrastructure-specific behavior.\n- If you use `allowlist_headers(...)`, remember that custom names may need to be added through `allow_extra=...`.\n\n## Configuration with `Secure`\n\nUse `CustomHeader` when you need a header without a dedicated builder. You can set the name and value directly, then update the value later if needed.\n\n### Methods Available\n\n- **`set(value)` / `value(value)`**: Updates the value of the custom header.\n- **`header_value`**: Property that retrieves the current value of the custom header.\n\n## Example Usage\n\nTo define a custom header and use it in a secure configuration:\n\n```python\nfrom secure import CustomHeader\n\ncustom_header = CustomHeader(\"X-Custom-Header\", \"CustomValue\")\nprint(custom_header.header_name) # Output: 'X-Custom-Header'\nprint(custom_header.header_value) # Output: 'CustomValue'\n\n# Update the value\ncustom_header.set(\"NewValue\")\nprint(custom_header.header_value) # Output: 'NewValue'\n```\n\n## **Resources**\n\n- [MDN Web Docs: HTTP Headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers)\n\n## **Attribution**\n\nThis library implements security recommendations from trusted sources:\n\n- [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers) (licensed under [CC-BY-SA 2.5](https://creativecommons.org/licenses/by-sa/2.5/))\n- [OWASP Secure Headers Project](https://owasp.org/www-project-secure-headers/) (licensed under [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/))\n" }, { "path": "docs/headers/dns_prefetch_control.md", "content": "# X-DNS-Prefetch-Control\n\n## What it does\n\n`X-DNS-Prefetch-Control` controls **DNS prefetching**, where browsers may proactively resolve domain names for links and referenced subresources (images, CSS, JS, etc.) in the background to reduce perceived latency.\n\n## Minimal example\n\n```python\nfrom secure import Secure, XDnsPrefetchControl\n\nsecure_headers = Secure(\n xdfc=XDnsPrefetchControl().off()\n)\n```\n\n## Resulting header\n\n```http\nX-DNS-Prefetch-Control: off\n```\n\n## Practical note\n\nWhen this header is absent, supporting browsers commonly behave as if DNS prefetching is on. Add the header only when you want to state a clear preference.\n\n## Default behavior\n\nIf you create `XDnsPrefetchControl()` and do not set a directive, it returns the library default value:\n\n- **Default header value:** `off`\n\n> Note (MDN behavior): In browsers that support DNS prefetching, if this header is **not present**, the effective behavior is typically **`on`**. This library’s default is **privacy-first** when you choose to emit the header.\n\n## Using with `Secure`\n\nIf you don’t configure anything, the default value is emitted.\n`Preset.BASIC` includes `X-DNS-Prefetch-Control: off`; `Preset.BALANCED` and `Preset.STRICT` leave it out unless you add it explicitly.\n\n## Common recipes\n\n### 1) Disable DNS prefetching (recommended when you don’t control outbound links)\n\n```python\nfrom secure import XDnsPrefetchControl\n\nxdfc = XDnsPrefetchControl() # default: off\nprint(xdfc.header_name) # X-DNS-Prefetch-Control\nprint(xdfc.header_value) # off\n```\n\n### 2) Enable DNS prefetching\n\n```python\nxdfc = XDnsPrefetchControl().on()\nprint(xdfc.header_value) # on\n```\n\n### 3) Backwards-compatible builder names\n\nIf you prefer the older API vocabulary:\n\n```python\nxdfc = XDnsPrefetchControl().allow() # == .on()\nxdfc = XDnsPrefetchControl().disable() # == .off()\n```\n\n## Builder API\n\n### Canonical directives\n\n- `.on()`\n Enables DNS prefetching (commonly the effective behavior when the header is absent in supporting browsers).\n\n- `.off()`\n Disables DNS prefetching (useful to reduce information leakage to third-party domains).\n\n### Backwards-compatible aliases\n\n- `.allow()` → same as `.on()`\n- `.disable()` → same as `.off()`\n\n## Escape hatches\n\n### `.value(\"...\")` / `.set(\"...\")`\n\nSet an explicit header value (replaces the current value):\n\n```python\nxdfc = XDnsPrefetchControl().value(\"off\")\nprint(xdfc.header_value) # off\n```\n\nIf you pass `ON` / `Off` (any casing), the builder normalizes to `on` / `off` for stable output.\n\n### `.custom(\"token\")`\n\nSet a **non-standard / non-MDN** token (escape hatch):\n\n```python\nxdfc = XDnsPrefetchControl().custom(\"off\")\nprint(xdfc.header_value) # off\n```\n\n(For this header, non-`on`/`off` values are unusual, but the escape hatch exists for consistency across the library.)\n\n### `.clear()`\n\nReset to the library default:\n\n```python\nxdfc = XDnsPrefetchControl().on().clear()\nprint(xdfc.header_value) # off\n```\n\n## Deterministic output & overwrites\n\n- Output is always a **single token** (`on` or `off`) when using `.on()` / `.off()` (stable and deterministic).\n- Setting the value multiple times overwrites the previous value (last call wins).\n- `.set(...)`, `.value(...)`, and `.custom(...)` reject CR/LF; `Secure.validate_and_normalize_headers(...)` performs the broader normalization pass.\n\n## Compatibility notes\n\n- This header is **non-standard**.\n- Browser behavior differs across engines and versions; treat this as a best-effort control rather than a guaranteed security boundary.\n\n## Attribution\n\nThis library implements security recommendations and behavior described by:\n\n- [MDN Web Docs: X-DNS-Prefetch-Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/X-DNS-Prefetch-Control) (licensed under [CC-BY-SA 2.5](https://creativecommons.org/licenses/by-sa/2.5/))\n- [OWASP Secure Headers Project: X-DNS-Prefetch-Control](https://owasp.org/www-project-secure-headers/#x-dns-prefetch-control) (licensed under [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/))\n" }, { "path": "docs/headers/permissions_policy.md", "content": "# Permissions-Policy\n\n## What it does\n\nThe `Permissions-Policy` HTTP response header lets you enable or disable access to selected browser features and powerful APIs in the current document and in nested browsing contexts (iframes). It replaces the deprecated `Feature-Policy` header.\n\nIn this library, `PermissionsPolicy` is a fluent builder for producing a single `Permissions-Policy` header value, suitable for applying via `Secure`.\n\n## Minimal example\n\n```python\nfrom secure import PermissionsPolicy, Secure\n\nsecure_headers = Secure(\n permissions=PermissionsPolicy()\n .geolocation()\n .microphone()\n .camera()\n)\n```\n\n## Resulting header\n\n```http\nPermissions-Policy: geolocation=(), microphone=(), camera=()\n```\n\n## Practical note\n\nBrowser support varies by feature. Keep the policy restrictive, then test the specific features your app actually needs in real browsers.\n\n## Best practices\n\n- Start restrictive: disable features you don’t need to reduce attack surface and protect privacy.\n- Enable selectively: allow features only where required, and only for trusted origins.\n- Validate in real browsers: support varies by feature and browser; test the behaviors you rely on.\n\n## Configuration with `Secure`\n\n`Preset.BALANCED` and `Preset.STRICT` include `geolocation=(), microphone=(), camera=()` by default; `Preset.BASIC` does not add `Permissions-Policy`.\n\n## Allowlist syntax\n\n`PermissionsPolicy` uses MDN-style allowlist syntax for each directive:\n\n- **No tokens** → `()` (feature disabled)\n- **`\"*\"`** → `*` (feature allowed everywhere; must be used alone)\n- **`\"self\"` / `\"src\"`** → tokens for same-origin / iframe source origin\n- **Origins** → pass a URL (e.g. `\"https://a.example.com\"`); it is emitted as a double-quoted origin in the header value\n\nExamples:\n\n```python\npolicy = (\n PermissionsPolicy()\n .geolocation(\"*\") # geolocation=*\n .camera(\"self\", \"https://a.example.com\") # camera=(self \"https://a.example.com\")\n .microphone() # microphone=()\n)\nprint(policy.header_value)\n```\n\n## Methods\n\nCommon methods you’ll use:\n\n- **`geolocation(*allowlist)`**, **`camera(*allowlist)`**, **`microphone(*allowlist)`**, etc.: configure specific directives.\n- **`add_directive(directive, *allowlist)`** (alias: **`directive(...)`**): set any directive by name (future-proof when browsers add new ones).\n- **`value(raw)`** (alias: **`set(raw)`**): set a complete prebuilt header value (escape hatch; bypasses directive building).\n- **`clear()`**: remove all configured directives and any raw override.\n\n## Example usage\n\n```python\nfrom secure import PermissionsPolicy, Secure\n\npermissions_policy = (\n PermissionsPolicy()\n .geolocation() # disabled\n .camera(\"self\", \"https://a.example.com\")\n .microphone(\"self\")\n)\n\nprint(permissions_policy.header_name) # 'Permissions-Policy'\nprint(permissions_policy.header_value) # 'geolocation=(), camera=(self \"https://a.example.com\"), microphone=(self)'\n\nsecure_headers = Secure(permissions=permissions_policy)\n```\n\n## Resources\n\n- [MDN Web Docs: Permissions-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy)\n- [OWASP Secure Headers Project: Permissions-Policy](https://owasp.org/www-project-secure-headers/#permissions-policy)\n\n## Attribution\n\nThis library implements security recommendations from trusted sources:\n\n- MDN Web Docs (licensed under CC-BY-SA 2.5)\n- OWASP Secure Headers Project (licensed under CC-BY-SA 4.0)\n" }, { "path": "docs/headers/referrer_policy.md", "content": "# Referrer-Policy\n\n## What it does\n\nThe `Referrer-Policy` response header controls how much referrer information (sent via the `Referer` header) is included with outgoing requests. It is primarily a privacy and data-minimization control, with important security implications when navigating across origins or downgrading from HTTPS to HTTP.\n\n> Note: `Referer` is intentionally misspelled in HTTP. `Referrer-Policy` does **not** share that misspelling.\n\n## Minimal example\n\n```python\nfrom secure import ReferrerPolicy, Secure\n\nsecure_headers = Secure(\n referrer=ReferrerPolicy().strict_origin_when_cross_origin()\n)\n```\n\n## Resulting header\n\n```http\nReferrer-Policy: strict-origin-when-cross-origin\n```\n\n## Practical note\n\n`strict-origin-when-cross-origin` is the recommended default because it preserves same-origin behavior while avoiding full URL leakage across origins. Move to `no-referrer` only when you want the strictest privacy posture.\n\n## Default behavior\n\n**Default header value:** `strict-origin-when-cross-origin`\n\nThis matches modern browser defaults: if no policy is specified (or the provided value is invalid), the effective policy is `strict-origin-when-cross-origin`.\n\n## Best practices (recommended choices)\n\n- **`strict-origin-when-cross-origin` (recommended default)** \n Sends the full referrer (origin + path + query) for same-origin requests; sends **origin only** for cross-origin HTTPS→HTTPS; sends **no `Referer`** when downgrading (HTTPS→HTTP).\n- **`no-referrer` (max privacy)** \n Omits the `Referer` header entirely for all requests.\n- **`same-origin` (strict privacy across sites)** \n Sends referrer only for same-origin requests; omits it for cross-origin requests.\n- **Avoid `unsafe-url`** unless you fully understand the impact (it can leak sensitive URL data across origins and to insecure destinations).\n\n## Configuration with `Secure`\n\n```python\nfrom secure import ReferrerPolicy, Secure\n\nsecure_headers = Secure(\n referrer=ReferrerPolicy() # uses the default: strict-origin-when-cross-origin\n)\n```\n\n`Preset.BALANCED` uses `strict-origin-when-cross-origin`; `Preset.BASIC` and `Preset.STRICT` use `no-referrer`.\n\n### Set a single explicit policy\n\nUse `value(...)` (or `custom(...)`) when you want to **replace** any configured policies and set exactly one value:\n\n```python\nfrom secure import ReferrerPolicy, Secure\n\nsecure_headers = Secure(\n referrer=ReferrerPolicy().value(\"no-referrer\")\n)\n```\n\nYou can also use the fluent directive helpers:\n\n```python\nsecure_headers = Secure(\n referrer=ReferrerPolicy().no_referrer()\n)\n```\n\n### Specify a fallback policy list (HTTP header only)\n\nBrowsers support a **comma-separated list** in the `Referrer-Policy` HTTP header. The desired (most modern) policy should be listed **last**.\n\n```python\nfrom secure import ReferrerPolicy\n\nrp = ReferrerPolicy().fallback(\"no-referrer\", \"strict-origin-when-cross-origin\")\nprint(rp.header_name) # Referrer-Policy\nprint(rp.header_value) # no-referrer, strict-origin-when-cross-origin\n```\n\nYou can build the same list with `.add(...)`:\n\n```python\nrp = (\n ReferrerPolicy()\n .clear()\n .add(\"no-referrer\")\n .add(\"strict-origin-when-cross-origin\")\n)\n```\n\n> Note: the fallback _list_ behavior is supported in the HTTP header, but not in the HTML `referrerpolicy` attribute.\n\n## API reference (ReferrerPolicy)\n\n### Core builder methods\n\n- `value(\"...\")` / `custom(\"...\")`\n Replace all configured policies with the provided value (supports comma-separated lists).\n- `add(\"...\")` / `set(\"...\")`\n Append one or more policy tokens (supports comma-separated lists). Duplicate tokens are ignored.\n- `fallback(*policies)`\n Replace the current policies with an explicit ordered fallback list.\n- `clear()`\n Clear configured policies (returns to default behavior unless you add values afterward).\n\n### Directive helpers (MDN policies)\n\nEach of these appends the corresponding token (same behavior as `add(\"token\")`):\n\n- `no_referrer()` → `no-referrer`\n Omits the `Referer` header entirely.\n- `no_referrer_when_downgrade()` → `no-referrer-when-downgrade`\n Sends full referrer for same-or-more secure requests; omits referrer on downgrade (HTTPS→HTTP).\n- `origin()` → `origin`\n Sends only the origin (scheme + host + port).\n- `origin_when_cross_origin()` → `origin-when-cross-origin`\n Same-origin: full referrer; cross-origin and downgrade: origin only.\n- `same_origin()` → `same-origin`\n Same-origin: full referrer; cross-origin: omit referrer.\n- `strict_origin()` → `strict-origin`\n Sends only origin for same-security requests; omits on downgrade (HTTPS→HTTP).\n- `strict_origin_when_cross_origin()` → `strict-origin-when-cross-origin`\n Same-origin: full referrer; cross-origin HTTPS→HTTPS: origin only; downgrade: omit.\n- `unsafe_url()` → `unsafe-url`\n Sends origin + path + query for all requests (generally discouraged; may leak sensitive data).\n\n## Example usage\n\n```python\nfrom secure import ReferrerPolicy\n\nreferrer_policy = ReferrerPolicy().strict_origin_when_cross_origin()\nprint(referrer_policy.header_name) # 'Referrer-Policy'\nprint(referrer_policy.header_value) # 'strict-origin-when-cross-origin'\n```\n\n## Resources\n\n- MDN Web Docs: Referrer-Policy\n [https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Referrer-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Referrer-Policy)\n- OWASP Secure Headers Project: Referrer-Policy\n [https://owasp.org/www-project-secure-headers/#referrer-policy](https://owasp.org/www-project-secure-headers/#referrer-policy)\n\n## Attribution\n\nThis library implements security recommendations from trusted sources:\n\n- MDN Web Docs (licensed under CC-BY-SA 2.5)\n [https://developer.mozilla.org/en-US/docs/MDN/Community/Roles_teams#contributor](https://developer.mozilla.org/en-US/docs/MDN/Community/Roles_teams#contributor)\n [https://creativecommons.org/licenses/by-sa/2.5/](https://creativecommons.org/licenses/by-sa/2.5/)\n- OWASP Secure Headers Project (licensed under CC-BY-SA 4.0)\n [https://creativecommons.org/licenses/by-sa/4.0/](https://creativecommons.org/licenses/by-sa/4.0/)\n" }, { "path": "docs/headers/server.md", "content": "# Server Header\n\n## What it does\n\nThe `Server` header can reveal details about the software handling the request. In `secure`, the builder defaults to an empty string so your application can avoid adding identifying detail when the surrounding stack allows it.\n\n## Minimal example\n\n```python\nfrom secure import Secure, Server\n\nsecure_headers = Secure(\n server=Server().set(\"\")\n)\n```\n\n## Resulting header\n\n```http\nServer:\n```\n\n## Practical note\n\nApplication code can only control this header if the surrounding stack does not re-add its own value. Check your ASGI server, WSGI server, proxy, or CDN settings too.\n\n## Best Practices\n\n- **Set an empty value or custom string**: Use an empty or generic value when you want `secure` to control the header.\n- **Avoid exposing server information**: Avoid leaving the default server response, which may expose sensitive version information.\n- **Check upstream defaults**: Proxies, ASGI servers, and framework middleware may still add their own `Server` header unless you disable that behavior.\n\n## Configuration with `Secure`\n\nUse `Server` to control the `Server` header value. Its default value is an empty string.\n\n### Methods Available\n\n- **`set(value)`**: Set a custom value for the `Server` header.\n- **`clear()`**: Clear any custom value and revert the header to its default secure value (an empty string).\n\n## Example Usage\n\nTo set up the `Server` header and hide the server information:\n\n```python\nfrom secure import Server\n\nserver_header = Server().set(\"\")\nprint(server_header.header_name) # Output: 'Server'\nprint(server_header.header_value) # Output: ''\n```\n\nThen pass it into `Secure`:\n\n```python\nfrom secure import Secure\n\nsecure_headers = Secure(server=server_header)\n```\n\n### Special Considerations for Frameworks\n\nSome frameworks like Uvicorn automatically inject a `Server` header. If you're using Uvicorn and need to override or remove this header, refer to the [framework integration guide](../frameworks.md) for specific instructions on how to disable Uvicorn's default `Server` header.\n\n## **Resources**\n\n- [MDN Web Docs: Server Header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Server)\n- [OWASP Secure Headers Project: Server Header](https://owasp.org/www-project-secure-headers/#server-header)\n\n## **Attribution**\n\nThis library implements security recommendations from trusted sources:\n\n- [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Server) (licensed under [CC-BY-SA 2.5](https://creativecommons.org/licenses/by-sa/2.5/))\n- [OWASP Secure Headers Project](https://owasp.org/www-project-secure-headers/#server-header) (licensed under [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/))\n" }, { "path": "docs/headers/strict_transport_security.md", "content": "# Strict-Transport-Security (HSTS)\n\n## What it does\n\nThe `Strict-Transport-Security` (HSTS) header tells browsers that a host **must only be accessed over HTTPS**. Once a browser has received this header, it will automatically upgrade future HTTP navigations to HTTPS for the configured duration, helping prevent man-in-the-middle and downgrade attacks.\n\n> Important: Browsers **ignore** `Strict-Transport-Security` if it is delivered over **insecure HTTP**. You must send it over HTTPS only.\n\n## Minimal example\n\n```python\nfrom secure import Secure, StrictTransportSecurity\n\nsecure_headers = Secure(\n hsts=StrictTransportSecurity().max_age(31536000).include_subdomains()\n)\n```\n\n## Resulting header\n\n```http\nStrict-Transport-Security: max-age=31536000; includeSubDomains\n```\n\n## Practical note\n\nDo not enable `includeSubDomains` until every subdomain is HTTPS-ready. Treat `preload()` as a deliberate rollout step because removal is slow once a domain is on the preload list.\n\n## Default behavior\n\nIf you do not configure any directives, this library emits the default header value:\n\n- **Default header value:** `max-age=31536000` (one year)\n\n## Best practices\n\n- **Use a long `max-age`**: One year (`31536000` seconds) is a common baseline.\n- **Include subdomains (carefully)**: Add `includeSubDomains` only if _all_ subdomains are HTTPS-ready.\n- **Only use `preload` when you mean it**:\n - `preload` is intended for submitting your domain to the HSTS preload list.\n - When using `preload`, the library enforces MDN’s requirements:\n - `max-age` must be **at least 31536000**\n - `includeSubDomains` must be present\n\n## Configuration with `Secure`\n\nUse `StrictTransportSecurity` for fluent, chainable configuration.\n\n`Preset.BASIC` and `Preset.BALANCED` use one year with `includeSubDomains`; `Preset.STRICT` uses two years with `includeSubDomains`.\n\n### Preload configuration\n\nIf you opt into preload, the library ensures preload requirements are satisfied:\n\n```python\nfrom secure import StrictTransportSecurity\n\nhsts = (\n StrictTransportSecurity()\n .max_age(31536000)\n .include_subdomains()\n .preload()\n)\n\nprint(hsts.header_name) # 'Strict-Transport-Security'\nprint(hsts.header_value) # 'max-age=31536000; includeSubDomains; preload'\n```\n\nIf `preload()` is enabled with a `max-age` less than `31536000`, the header builder will raise a `ValueError`.\n\n## Methods available\n\n- **`max_age(seconds)`**\n Set `max-age`: how long (in seconds) the browser should remember to only use HTTPS for this host.\n\n- **`include_subdomains()`**\n Add `includeSubDomains`: apply the HSTS policy to all subdomains as well.\n\n- **`preload()`**\n Add `preload`: indicates intent to meet HSTS preload requirements. This library:\n - automatically enables `includeSubDomains`\n - enforces `max-age >= 31536000`\n\n- **`clear()`**\n Clear configured directives and reset back to the library default behavior.\n\n- **`value(str)` / `set(str)`**\n Escape hatch: set a raw header value (replaces any configured directives). The value must not contain CR/LF characters.\n\n## Example usage\n\nMinimal one-year HSTS:\n\n```python\nfrom secure import StrictTransportSecurity\n\nhsts = StrictTransportSecurity().max_age(31536000)\nprint(hsts.header_value) # 'max-age=31536000'\n```\n\nOne-year HSTS including subdomains:\n\n```python\nfrom secure import StrictTransportSecurity\n\nhsts = StrictTransportSecurity().max_age(31536000).include_subdomains()\nprint(hsts.header_value) # 'max-age=31536000; includeSubDomains'\n```\n\n## Resources\n\n- MDN Web Docs: Strict-Transport-Security\n [https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Strict-Transport-Security](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Strict-Transport-Security)\n- OWASP Secure Headers Project\n [https://owasp.org/www-project-secure-headers/](https://owasp.org/www-project-secure-headers/)\n- HSTS Preload List\n [https://hstspreload.org/](https://hstspreload.org/)\n\n## Attribution\n\nThis library implements security recommendations from trusted sources:\n\n- MDN Web Docs: Strict-Transport-Security (licensed under CC-BY-SA 2.5)\n [https://creativecommons.org/licenses/by-sa/2.5/](https://creativecommons.org/licenses/by-sa/2.5/)\n- OWASP Secure Headers Project (licensed under CC-BY-SA 4.0)\n [https://creativecommons.org/licenses/by-sa/4.0/](https://creativecommons.org/licenses/by-sa/4.0/)\n" }, { "path": "docs/headers/x-permitted-cross-domain-policies.md", "content": "# X-Permitted-Cross-Domain-Policies\n\n## What it does\n\n`X-Permitted-Cross-Domain-Policies` is a **response header** that sets a _meta-policy_ controlling whether site resources can be accessed cross-origin by documents running in legacy web clients (for example, Adobe Acrobat or Microsoft Silverlight).\n\nUsage is less common today because Flash/Silverlight have been deprecated, but many security testing tools still check for `X-Permitted-Cross-Domain-Policies: none` to reduce the risk of an overly-permissive cross-domain policy being present accidentally or maliciously.\n\n> This documentation format mirrors the style used in the existing header docs (e.g., Cache-Control).\n\n## Minimal example\n\n```python\nfrom secure import Secure, XPermittedCrossDomainPolicies\n\nsecure_headers = Secure(\n xpcdp=XPermittedCrossDomainPolicies().none()\n)\n```\n\n## Resulting header\n\n```http\nX-Permitted-Cross-Domain-Policies: none\n```\n\n## Practical note\n\nMost modern apps do not need this header, but security scanners still look for it. Add it when you want an explicit deny policy for legacy cross-domain policy files.\n\n## Default behavior\n\nIf you create `XPermittedCrossDomainPolicies()` and do not set a policy, it returns the library default value:\n\n- **Default header value:** `none`\n\nThis is the least permissive option and is the most common secure setting when you do not need legacy cross-domain policy behavior.\n\n## Using with `Secure`\n\nIf you don’t configure anything, the default value is emitted.\n`Preset.BASIC` includes `X-Permitted-Cross-Domain-Policies: none`; `Preset.BALANCED` and `Preset.STRICT` leave it out unless you add it explicitly.\n\n## Common recipes\n\n### 1) Disallow cross-domain policy files (recommended default)\n\n```python\nfrom secure import XPermittedCrossDomainPolicies\n\nxpcdp = XPermittedCrossDomainPolicies() # default: none\nprint(xpcdp.header_name) # X-Permitted-Cross-Domain-Policies\nprint(xpcdp.header_value) # none\n```\n\nMDN notes this is the typical configuration when you don’t need legacy clients.\n\n### 2) Allow only a master policy file\n\n```python\nxpcdp = XPermittedCrossDomainPolicies().master_only()\nprint(xpcdp.header_value) # master-only\n```\n\nThis allows cross-domain access to the master policy file defined on the same domain.\n\n### 3) Constrain policy files by content type (HTTP/HTTPS only)\n\n```python\nxpcdp = XPermittedCrossDomainPolicies().by_content_type()\nprint(xpcdp.header_value) # by-content-type\n```\n\nOnly policy files served with `Content-Type: text/x-cross-domain-policy` are allowed.\n\n### 4) Indicate this response should not be treated as a policy file\n\n```python\nxpcdp = XPermittedCrossDomainPolicies().none_this_response()\nprint(xpcdp.header_value) # none-this-response\n```\n\nThis directive is unique to the HTTP header and indicates the current document should not be used as a policy file.\n\n## Builder API\n\n### Policy directives (single value)\n\n- `.none()`\n- `.master_only()`\n- `.by_content_type()` (HTTP/HTTPS only)\n- `.by_ftp_filename()` (FTP only)\n- `.all()`\n- `.none_this_response()` (HTTP-header-only)\n\nThese map directly to the directive definitions described by MDN (and largely echoed by OWASP).\n\n### Typed helper\n\n- `.policy(\"none\" | \"master-only\" | \"by-content-type\" | \"by-ftp-filename\" | \"all\" | \"none-this-response\")`\n\nRaises `ValueError` for unsupported values (helps catch typos early).\n\n## Escape hatches\n\n### `.value(\"...\")`\n\nSet an explicit header value (replaces any configured directive):\n\n```python\nxpcdp = XPermittedCrossDomainPolicies().value(\"none\")\nprint(xpcdp.header_value) # none\n```\n\n### `.custom(\"token\")`\n\nAlias for `.value(...)` (use when you intentionally want a raw string value):\n\n```python\nxpcdp = XPermittedCrossDomainPolicies().custom(\"master-only\")\nprint(xpcdp.header_value) # master-only\n```\n\n### `.clear()`\n\nReset to the default:\n\n```python\nxpcdp = XPermittedCrossDomainPolicies().all().clear()\nprint(xpcdp.header_value) # none\n```\n\n## Deterministic output & safety\n\n- The header value is rendered as a **single directive token**, so output is inherently deterministic.\n- Raw setters (`.value(...)` / `.custom(...)`) normalize obvious header-splitting primitives (CR/LF) before serialization; stricter validation can be enforced via `Secure.validate_and_normalize_headers(...)`.\n\n## Attribution\n\nThis library implements security recommendations and behavior described by:\n\n- [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/X-Permitted-Cross-Domain-Policies) (licensed under [CC-BY-SA 2.5](https://creativecommons.org/licenses/by-sa/2.5/))\n- [OWASP Secure Headers Project](https://owasp.org/www-project-secure-headers/#x-permitted-cross-domain-policies) (licensed under [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/))\n" }, { "path": "docs/headers/x_content_type_options.md", "content": "# X-Content-Type-Options\n\n## What it does\n\nThe `X-Content-Type-Options` header tells browsers to **respect the MIME type declared in `Content-Type`** instead of trying to guess (\"sniff\") a different type.\n\nIn practice, setting `X-Content-Type-Options: nosniff` can cause browsers to **block**:\n\n- `style` requests not served as `text/css`\n- `script` requests not served with a JavaScript MIME type\n\nThis helps reduce the risk of content being interpreted as executable when it should not be.\n\n## Minimal example\n\n```python\nfrom secure import Secure, XContentTypeOptions\n\nsecure_headers = Secure(\n xcto=XContentTypeOptions().nosniff(),\n)\n```\n\n## Resulting header\n\n```http\nX-Content-Type-Options: nosniff\n```\n\n## Practical note\n\n`nosniff` can expose incorrect MIME types in your app or asset pipeline. If enabling it breaks assets, fix the response `Content-Type` rather than weakening the header.\n\n## Best Practices\n\n- **Set to `nosniff`** (recommended): This is the standard and widely supported directive.\n- **Use correct `Content-Type` values**: `nosniff` is most effective when your server sends accurate MIME types.\n\n## Configuration with `Secure`\n\nThe `XContentTypeOptions` class configures `X-Content-Type-Options`.\n\n**Default header value:** `nosniff`\nAll built-in presets include it.\n\n### Methods available\n\n- **`nosniff()`**: Sets the header to `nosniff`, which blocks certain `script`/`style` requests when MIME types are incorrect.\n- **`set(value)` / `value(value)`**: Sets a raw/custom header value (escape hatch). `value` is an alias for `set`.\n- **`clear()`**: Resets the header to the library default (`nosniff`).\n\n> Note: `set/value` are escape hatches. If you use `Secure.validate_and_normalize_headers(...)`, that layer is responsible for sanitization and safety checks.\n\n## Example usage\n\n```python\nfrom secure import XContentTypeOptions\n\nxcto = XContentTypeOptions().nosniff()\nprint(xcto.header_name) # 'X-Content-Type-Options'\nprint(xcto.header_value) # 'nosniff'\n```\n\nApply via `Secure`:\n\n```python\nfrom secure import Secure, XContentTypeOptions\n\nsecure_headers = Secure(xcto=XContentTypeOptions().nosniff())\n```\n\n## Resources\n\n- MDN Web Docs: X-Content-Type-Options\n [https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Content-Type-Options](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Content-Type-Options)\n- OWASP Secure Headers Project: X-Content-Type-Options\n [https://owasp.org/www-project-secure-headers/#x-content-type-options](https://owasp.org/www-project-secure-headers/#x-content-type-options)\n\n## Attribution\n\nThis library implements security recommendations from trusted sources:\n\n- MDN Web Docs (CC-BY-SA 2.5)\n [https://developer.mozilla.org/en-US/docs/MDN/Community/Roles_teams#contributor](https://developer.mozilla.org/en-US/docs/MDN/Community/Roles_teams#contributor)\n [https://creativecommons.org/licenses/by-sa/2.5/](https://creativecommons.org/licenses/by-sa/2.5/)\n- OWASP Secure Headers Project (CC-BY-SA 4.0)\n [https://creativecommons.org/licenses/by-sa/4.0/](https://creativecommons.org/licenses/by-sa/4.0/)\n" }, { "path": "docs/headers/x_frame_options.md", "content": "# X-Frame-Options\n\n## What it does\n\n`X-Frame-Options` is an HTTP **response header** that tells supporting browsers whether a page is allowed to render inside a ``, `