secure 0.2.1__tar.gz → 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. {secure-0.2.1 → secure-1.0.0}/LICENSE +1 -1
  2. secure-1.0.0/MANIFEST.in +2 -0
  3. secure-1.0.0/PKG-INFO +348 -0
  4. secure-1.0.0/README.md +324 -0
  5. secure-1.0.0/pyproject.toml +37 -0
  6. secure-1.0.0/secure/__init__.py +29 -0
  7. secure-1.0.0/secure/headers/__init__.py +27 -0
  8. secure-1.0.0/secure/headers/base_header.py +120 -0
  9. secure-1.0.0/secure/headers/cache_control.py +257 -0
  10. secure-1.0.0/secure/headers/content_security_policy.py +305 -0
  11. secure-1.0.0/secure/headers/cross_origin_embedder_policy.py +100 -0
  12. secure-1.0.0/secure/headers/cross_origin_opener_policy.py +111 -0
  13. secure-1.0.0/secure/headers/custom_header.py +56 -0
  14. secure-1.0.0/secure/headers/permissions_policy.py +412 -0
  15. secure-1.0.0/secure/headers/referrer_policy.py +168 -0
  16. secure-1.0.0/secure/headers/server.py +59 -0
  17. secure-1.0.0/secure/headers/strict_transport_security.py +118 -0
  18. secure-1.0.0/secure/headers/x_content_type_options.py +76 -0
  19. secure-1.0.0/secure/headers/x_frame_options.py +89 -0
  20. secure-1.0.0/secure/py.typed +0 -0
  21. secure-1.0.0/secure/secure.py +283 -0
  22. secure-1.0.0/secure.egg-info/PKG-INFO +348 -0
  23. secure-1.0.0/secure.egg-info/SOURCES.txt +24 -0
  24. {secure-0.2.1 → secure-1.0.0}/secure.egg-info/top_level.txt +1 -0
  25. secure-0.2.1/MANIFEST.in +0 -1
  26. secure-0.2.1/PKG-INFO +0 -95
  27. secure-0.2.1/README.md +0 -76
  28. secure-0.2.1/secure/__init__.py +0 -1
  29. secure-0.2.1/secure/__version__.py +0 -3
  30. secure-0.2.1/secure/cookie.py +0 -56
  31. secure-0.2.1/secure/core.py +0 -5
  32. secure-0.2.1/secure/framework_cookie.py +0 -199
  33. secure-0.2.1/secure/framework_headers.py +0 -164
  34. secure-0.2.1/secure/headers.py +0 -191
  35. secure-0.2.1/secure/policies.py +0 -377
  36. secure-0.2.1/secure.egg-info/PKG-INFO +0 -95
  37. secure-0.2.1/secure.egg-info/SOURCES.txt +0 -16
  38. secure-0.2.1/setup.py +0 -130
  39. {secure-0.2.1 → secure-1.0.0}/secure.egg-info/dependency_links.txt +0 -0
  40. {secure-0.2.1 → secure-1.0.0}/setup.cfg +0 -0
@@ -1,6 +1,6 @@
1
1
  MIT License
2
2
 
3
- Copyright (c) 2018 Caleb Kinney
3
+ Copyright (c) 2018-2024 Caleb Kinney
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
@@ -0,0 +1,2 @@
1
+ include LICENSE
2
+ exclude tests/*
secure-1.0.0/PKG-INFO ADDED
@@ -0,0 +1,348 @@
1
+ Metadata-Version: 2.1
2
+ Name: secure
3
+ Version: 1.0.0
4
+ Summary: A lightweight package that adds security headers for Python web frameworks.
5
+ Author-email: Caleb Kinney <caleb@typeerror.com>
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/TypeError/secure
8
+ Project-URL: Documentation, https://github.com/TypeError/secure/tree/main/docs
9
+ Project-URL: Repository, https://github.com/TypeError/secure
10
+ Project-URL: Issue-Tracker, https://github.com/TypeError/secure/issues
11
+ Keywords: security,headers,web,framework,HTTP
12
+ Classifier: Development Status :: 5 - Production/Stable
13
+ Classifier: License :: OSI Approved :: MIT License
14
+ Classifier: Programming Language :: Python :: 3.10
15
+ Classifier: Programming Language :: Python :: 3.11
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Typing :: Typed
18
+ Classifier: Operating System :: OS Independent
19
+ Classifier: Intended Audience :: Developers
20
+ Classifier: Topic :: Software Development :: Libraries
21
+ Requires-Python: >=3.10
22
+ Description-Content-Type: text/markdown
23
+ License-File: LICENSE
24
+
25
+ # secure.py
26
+
27
+ _A simple, yet powerful way to secure your Python web applications across multiple frameworks._
28
+
29
+ [![PyPI Version](https://img.shields.io/pypi/v/secure.svg)](https://pypi.org/project/secure/)
30
+ [![Python Versions](https://img.shields.io/pypi/pyversions/secure.svg)](https://pypi.org/project/secure/)
31
+ [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
32
+ [![Downloads](https://pepy.tech/badge/secure)](https://pepy.tech/project/secure)
33
+ [![License](https://img.shields.io/pypi/l/secure.svg)](https://github.com/TypeError/secure/blob/main/LICENSE)
34
+ [![GitHub Stars](https://img.shields.io/github/stars/TypeError/secure.svg)](https://github.com/TypeError/secure/stargazers)
35
+
36
+ ## **Introduction**
37
+
38
+ In today's web landscape, security is paramount. **secure.py** is a lightweight Python library designed to effortlessly add **security headers** to your web applications, protecting them from common vulnerabilities. Whether you're using **Django**, **Flask**, **FastAPI**, or any other popular framework, `secure.py` provides a unified API to enhance your application's security posture.
39
+
40
+ ---
41
+
42
+ ## **Why Use secure.py?**
43
+
44
+ - 🔒 **Apply Essential Security Headers**: Implement headers like CSP, HSTS, and more with minimal effort.
45
+ - 🛠️ **Consistent API Across Frameworks**: A unified approach for different web frameworks.
46
+ - ⚙️ **Customizable with Secure Defaults**: Start secure out-of-the-box and customize as needed.
47
+ - 🚀 **Easy Integration**: Compatible with Python's most-used frameworks.
48
+ - 🐍 **Modern Pythonic Design**: Leverages Python 3.10+ features for cleaner and more efficient code.
49
+
50
+ ---
51
+
52
+ ## **Supported Frameworks**
53
+
54
+ **secure.py** supports the following Python web frameworks:
55
+
56
+ | Framework | Documentation |
57
+ | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
58
+ | [aiohttp](https://docs.aiohttp.org) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#aiohttp) |
59
+ | [Bottle](https://bottlepy.org) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#bottle) |
60
+ | [CherryPy](https://cherrypy.dev/) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#cherrypy) |
61
+ | [Django](https://www.djangoproject.com) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#django) |
62
+ | [Falcon](https://falconframework.org) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#falcon) |
63
+ | [FastAPI](https://fastapi.tiangolo.com) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#fastapi) |
64
+ | [Flask](http://flask.pocoo.org) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#flask) |
65
+ | [Masonite](https://docs.masoniteproject.com/) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#masonite) |
66
+ | [Morepath](https://morepath.readthedocs.io) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#morepath) |
67
+ | [Pyramid](https://trypyramid.com) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#pyramid) |
68
+ | [Quart](https://quart.palletsprojects.com/en/latest/) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#quart) |
69
+ | [Responder](https://responder.kennethreitz.org/) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#responder) |
70
+ | [Sanic](https://sanicframework.org) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#sanic) |
71
+ | [Starlette](https://www.starlette.io/) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#starlette) |
72
+ | [Tornado](https://www.tornadoweb.org/) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#tornado) |
73
+ | [TurboGears](https://turbogears.org/) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#turbogears) |
74
+
75
+ ---
76
+
77
+ ## **Features**
78
+
79
+ - 🔒 **Secure Headers**: Automatically apply headers like `Strict-Transport-Security`, `X-Frame-Options`, and more.
80
+ - 🛠️ **Customizable Policies**: Flexibly build your own security policies using method chaining.
81
+ - 🌐 **Framework Integration**: Compatible with various frameworks, ensuring cross-compatibility.
82
+ - 🚀 **No External Dependencies**: Lightweight and easy to include in any project.
83
+ - 🧩 **Easy to Use**: Integrate security headers in just a few lines of code.
84
+ - ⚡ **Asynchronous Support**: Async support for modern frameworks like **FastAPI** and **Starlette**.
85
+ - 📝 **Enhanced Type Hinting**: Complete type annotations for better developer experience.
86
+ - 📚 **Attribution to Trusted Sources**: Implements recommendations from MDN and OWASP.
87
+
88
+ ---
89
+
90
+ ## **Requirements**
91
+
92
+ - **Python 3.10** or higher
93
+
94
+ This library leverages modern Python features introduced in Python 3.10 and 3.11, such as:
95
+
96
+ - **Union Type Operator (`|`)**: Simplifies type annotations.
97
+ - **Structural Pattern Matching (`match` statement)**: Enhances control flow.
98
+ - **Improved Type Hinting and Annotations**: Provides better code clarity and maintenance.
99
+ - **`cached_property`**: Optimize memory usage and performance.
100
+
101
+ **Note:** If you're using an older version of Python (3.6 to 3.9), please use version **0.3.0** of this library, which maintains compatibility with those versions.
102
+
103
+ - **Dependencies**
104
+
105
+ This library has no external dependencies outside of the Python Standard Library.
106
+
107
+ ---
108
+
109
+ ## **Installation**
110
+
111
+ You can install secure.py using pip, pipenv, or poetry:
112
+
113
+ **pip**:
114
+
115
+ ```bash
116
+ pip install secure
117
+ ```
118
+
119
+ **Pipenv**:
120
+
121
+ ```bash
122
+ pipenv install secure
123
+ ```
124
+
125
+ **Poetry**:
126
+
127
+ ```bash
128
+ poetry add secure
129
+ ```
130
+
131
+ ---
132
+
133
+ ## **Getting Started**
134
+
135
+ Once installed, you can quickly integrate `secure.py` into your project:
136
+
137
+ ### Synchronous Usage
138
+
139
+ ```python
140
+ import secure
141
+
142
+ # Initialize secure headers with default settings
143
+ secure_headers = secure.Secure.with_default_headers()
144
+
145
+ # Apply the headers to your framework response object
146
+ secure_headers.set_headers(response)
147
+ ```
148
+
149
+ ### Asynchronous Usage
150
+
151
+ For frameworks like **FastAPI** and **Starlette** that support asynchronous operations, use the async method:
152
+
153
+ ```python
154
+ import secure
155
+
156
+ # Initialize secure headers with default settings
157
+ secure_headers = secure.Secure.with_default_headers()
158
+
159
+ # Apply the headers asynchronously to your framework response object
160
+ await secure_headers.set_headers_async(response)
161
+ ```
162
+
163
+ ### **Example Usage**
164
+
165
+ ```python
166
+ import secure
167
+
168
+ # Create a Secure instance with default headers
169
+ secure_headers = secure.Secure.with_default_headers()
170
+
171
+ # Apply default secure headers to a response object
172
+ secure_headers.set_headers(response)
173
+ ```
174
+
175
+ ---
176
+
177
+ ## **Default Secure Headers**
178
+
179
+ By default, `secure.py` applies the following headers when using `with_default_headers()`:
180
+
181
+ ```http
182
+ Cache-Control: no-store
183
+ Cross-Origin-Opener-Policy: same-origin
184
+ Content-Security-Policy: default-src 'self'; script-src 'self'; style-src 'self'; object-src 'none'
185
+ Strict-Transport-Security: max-age=31536000
186
+ Permissions-Policy: geolocation=(), microphone=(), camera=()
187
+ Referrer-Policy: strict-origin-when-cross-origin
188
+ Server:
189
+ X-Content-Type-Options: nosniff
190
+ ```
191
+
192
+ ---
193
+
194
+ ## **Policy Builders**
195
+
196
+ `secure.py` allows you to customize headers such as **Content-Security-Policy** and **Permissions-Policy** with ease:
197
+
198
+ ### **Content-Security-Policy Example**
199
+
200
+ ```python
201
+ import secure
202
+
203
+ # Build a custom CSP policy
204
+ csp = (
205
+ secure.ContentSecurityPolicy()
206
+ .default_src("'self'")
207
+ .script_src("'self'", "cdn.example.com")
208
+ .style_src("'unsafe-inline'")
209
+ .img_src("'self'", "images.example.com")
210
+ .connect_src("'self'", "api.example.com")
211
+ )
212
+
213
+ # Apply it to secure headers
214
+ secure_headers = secure.Secure(csp=csp)
215
+ ```
216
+
217
+ **Resulting HTTP headers:**
218
+
219
+ ```http
220
+ Content-Security-Policy: default-src 'self'; script-src 'self' cdn.example.com; style-src 'unsafe-inline'; img-src 'self' images.example.com; connect-src 'self' api.example.com
221
+ ```
222
+
223
+ ### **Permissions-Policy Example**
224
+
225
+ ```python
226
+ import secure
227
+
228
+ # Build a custom Permissions Policy
229
+ permissions = (
230
+ secure.PermissionsPolicy()
231
+ .geolocation("'self'")
232
+ .camera("'none'")
233
+ .microphone("'none'")
234
+ )
235
+
236
+ # Apply it to secure headers
237
+ secure_headers = secure.Secure(permissions=permissions)
238
+ ```
239
+
240
+ **Resulting HTTP headers:**
241
+
242
+ ```http
243
+ Permissions-Policy: geolocation=('self'), camera=('none'), microphone=('none')
244
+ ```
245
+
246
+ ---
247
+
248
+ ## **Framework Examples**
249
+
250
+ ### **FastAPI**
251
+
252
+ ```python
253
+ from fastapi import FastAPI
254
+
255
+ from secure import Secure
256
+
257
+ app = FastAPI()
258
+ secure_headers = Secure.with_default_headers()
259
+
260
+
261
+ @app.middleware("http")
262
+ async def add_security_headers(request, call_next):
263
+ response = await call_next(request)
264
+ await secure_headers.set_headers_async(response)
265
+ return response
266
+
267
+
268
+ @app.get("/")
269
+ def read_root():
270
+ return {"Hello": "World"}
271
+ ```
272
+
273
+ ### Flask
274
+
275
+ ```python
276
+ from flask import Flask, Response
277
+
278
+ from secure import Secure
279
+
280
+ app = Flask(__name__)
281
+ secure_headers = Secure.with_default_headers()
282
+
283
+
284
+ @app.after_request
285
+ def add_security_headers(response: Response):
286
+ secure_headers.set_headers(response)
287
+ return response
288
+
289
+
290
+ @app.route("/")
291
+ def home():
292
+ return "Hello, world"
293
+
294
+
295
+ if __name__ == "__main__":
296
+ app.run()
297
+ ```
298
+
299
+ ---
300
+
301
+ ## **Documentation**
302
+
303
+ For more details, including advanced configurations and integration examples, please visit the **[full documentation](https://github.com/TypeError/secure/tree/main/docs)**.
304
+
305
+ ---
306
+
307
+ ## **Attribution**
308
+
309
+ This library implements security recommendations from trusted sources:
310
+
311
+ - [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/))
312
+ - [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/))
313
+
314
+ We have included attribution comments in the source code where appropriate.
315
+
316
+ ---
317
+
318
+ ## **Resources**
319
+
320
+ - [OWASP - Secure Headers Project](https://owasp.org/www-project-secure-headers/)
321
+ - [Mozilla Web Security Guidelines](https://infosec.mozilla.org/guidelines/web_security)
322
+ - [MDN Web Docs: Security Headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers#security)
323
+ - [web.dev: Security Best Practices](https://web.dev)
324
+ - [The World Wide Web Consortium (W3C)](https://www.w3.org)
325
+
326
+ ---
327
+
328
+ ### **License**
329
+
330
+ This project is licensed under the terms of the **[MIT License](https://opensource.org/licenses/MIT)**.
331
+
332
+ ---
333
+
334
+ ## **Contributing**
335
+
336
+ Contributions are welcome! If you'd like to contribute to `secure.py`, please feel free to open an issue or submit a pull request on **[GitHub](https://github.com/TypeError/secure)**.
337
+
338
+ ---
339
+
340
+ ## **Changelog**
341
+
342
+ For a detailed list of changes, please refer to the **[CHANGELOG](https://github.com/TypeError/secure/blob/main/CHANGELOG.md)**.
343
+
344
+ ---
345
+
346
+ ## **Acknowledgements**
347
+
348
+ We would like to thank the contributors of MDN Web Docs and OWASP Secure Headers Project for their invaluable resources and guidelines that help make the web a safer place.
secure-1.0.0/README.md ADDED
@@ -0,0 +1,324 @@
1
+ # secure.py
2
+
3
+ _A simple, yet powerful way to secure your Python web applications across multiple frameworks._
4
+
5
+ [![PyPI Version](https://img.shields.io/pypi/v/secure.svg)](https://pypi.org/project/secure/)
6
+ [![Python Versions](https://img.shields.io/pypi/pyversions/secure.svg)](https://pypi.org/project/secure/)
7
+ [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
8
+ [![Downloads](https://pepy.tech/badge/secure)](https://pepy.tech/project/secure)
9
+ [![License](https://img.shields.io/pypi/l/secure.svg)](https://github.com/TypeError/secure/blob/main/LICENSE)
10
+ [![GitHub Stars](https://img.shields.io/github/stars/TypeError/secure.svg)](https://github.com/TypeError/secure/stargazers)
11
+
12
+ ## **Introduction**
13
+
14
+ In today's web landscape, security is paramount. **secure.py** is a lightweight Python library designed to effortlessly add **security headers** to your web applications, protecting them from common vulnerabilities. Whether you're using **Django**, **Flask**, **FastAPI**, or any other popular framework, `secure.py` provides a unified API to enhance your application's security posture.
15
+
16
+ ---
17
+
18
+ ## **Why Use secure.py?**
19
+
20
+ - 🔒 **Apply Essential Security Headers**: Implement headers like CSP, HSTS, and more with minimal effort.
21
+ - 🛠️ **Consistent API Across Frameworks**: A unified approach for different web frameworks.
22
+ - ⚙️ **Customizable with Secure Defaults**: Start secure out-of-the-box and customize as needed.
23
+ - 🚀 **Easy Integration**: Compatible with Python's most-used frameworks.
24
+ - 🐍 **Modern Pythonic Design**: Leverages Python 3.10+ features for cleaner and more efficient code.
25
+
26
+ ---
27
+
28
+ ## **Supported Frameworks**
29
+
30
+ **secure.py** supports the following Python web frameworks:
31
+
32
+ | Framework | Documentation |
33
+ | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
34
+ | [aiohttp](https://docs.aiohttp.org) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#aiohttp) |
35
+ | [Bottle](https://bottlepy.org) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#bottle) |
36
+ | [CherryPy](https://cherrypy.dev/) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#cherrypy) |
37
+ | [Django](https://www.djangoproject.com) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#django) |
38
+ | [Falcon](https://falconframework.org) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#falcon) |
39
+ | [FastAPI](https://fastapi.tiangolo.com) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#fastapi) |
40
+ | [Flask](http://flask.pocoo.org) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#flask) |
41
+ | [Masonite](https://docs.masoniteproject.com/) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#masonite) |
42
+ | [Morepath](https://morepath.readthedocs.io) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#morepath) |
43
+ | [Pyramid](https://trypyramid.com) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#pyramid) |
44
+ | [Quart](https://quart.palletsprojects.com/en/latest/) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#quart) |
45
+ | [Responder](https://responder.kennethreitz.org/) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#responder) |
46
+ | [Sanic](https://sanicframework.org) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#sanic) |
47
+ | [Starlette](https://www.starlette.io/) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#starlette) |
48
+ | [Tornado](https://www.tornadoweb.org/) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#tornado) |
49
+ | [TurboGears](https://turbogears.org/) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#turbogears) |
50
+
51
+ ---
52
+
53
+ ## **Features**
54
+
55
+ - 🔒 **Secure Headers**: Automatically apply headers like `Strict-Transport-Security`, `X-Frame-Options`, and more.
56
+ - 🛠️ **Customizable Policies**: Flexibly build your own security policies using method chaining.
57
+ - 🌐 **Framework Integration**: Compatible with various frameworks, ensuring cross-compatibility.
58
+ - 🚀 **No External Dependencies**: Lightweight and easy to include in any project.
59
+ - 🧩 **Easy to Use**: Integrate security headers in just a few lines of code.
60
+ - ⚡ **Asynchronous Support**: Async support for modern frameworks like **FastAPI** and **Starlette**.
61
+ - 📝 **Enhanced Type Hinting**: Complete type annotations for better developer experience.
62
+ - 📚 **Attribution to Trusted Sources**: Implements recommendations from MDN and OWASP.
63
+
64
+ ---
65
+
66
+ ## **Requirements**
67
+
68
+ - **Python 3.10** or higher
69
+
70
+ This library leverages modern Python features introduced in Python 3.10 and 3.11, such as:
71
+
72
+ - **Union Type Operator (`|`)**: Simplifies type annotations.
73
+ - **Structural Pattern Matching (`match` statement)**: Enhances control flow.
74
+ - **Improved Type Hinting and Annotations**: Provides better code clarity and maintenance.
75
+ - **`cached_property`**: Optimize memory usage and performance.
76
+
77
+ **Note:** If you're using an older version of Python (3.6 to 3.9), please use version **0.3.0** of this library, which maintains compatibility with those versions.
78
+
79
+ - **Dependencies**
80
+
81
+ This library has no external dependencies outside of the Python Standard Library.
82
+
83
+ ---
84
+
85
+ ## **Installation**
86
+
87
+ You can install secure.py using pip, pipenv, or poetry:
88
+
89
+ **pip**:
90
+
91
+ ```bash
92
+ pip install secure
93
+ ```
94
+
95
+ **Pipenv**:
96
+
97
+ ```bash
98
+ pipenv install secure
99
+ ```
100
+
101
+ **Poetry**:
102
+
103
+ ```bash
104
+ poetry add secure
105
+ ```
106
+
107
+ ---
108
+
109
+ ## **Getting Started**
110
+
111
+ Once installed, you can quickly integrate `secure.py` into your project:
112
+
113
+ ### Synchronous Usage
114
+
115
+ ```python
116
+ import secure
117
+
118
+ # Initialize secure headers with default settings
119
+ secure_headers = secure.Secure.with_default_headers()
120
+
121
+ # Apply the headers to your framework response object
122
+ secure_headers.set_headers(response)
123
+ ```
124
+
125
+ ### Asynchronous Usage
126
+
127
+ For frameworks like **FastAPI** and **Starlette** that support asynchronous operations, use the async method:
128
+
129
+ ```python
130
+ import secure
131
+
132
+ # Initialize secure headers with default settings
133
+ secure_headers = secure.Secure.with_default_headers()
134
+
135
+ # Apply the headers asynchronously to your framework response object
136
+ await secure_headers.set_headers_async(response)
137
+ ```
138
+
139
+ ### **Example Usage**
140
+
141
+ ```python
142
+ import secure
143
+
144
+ # Create a Secure instance with default headers
145
+ secure_headers = secure.Secure.with_default_headers()
146
+
147
+ # Apply default secure headers to a response object
148
+ secure_headers.set_headers(response)
149
+ ```
150
+
151
+ ---
152
+
153
+ ## **Default Secure Headers**
154
+
155
+ By default, `secure.py` applies the following headers when using `with_default_headers()`:
156
+
157
+ ```http
158
+ Cache-Control: no-store
159
+ Cross-Origin-Opener-Policy: same-origin
160
+ Content-Security-Policy: default-src 'self'; script-src 'self'; style-src 'self'; object-src 'none'
161
+ Strict-Transport-Security: max-age=31536000
162
+ Permissions-Policy: geolocation=(), microphone=(), camera=()
163
+ Referrer-Policy: strict-origin-when-cross-origin
164
+ Server:
165
+ X-Content-Type-Options: nosniff
166
+ ```
167
+
168
+ ---
169
+
170
+ ## **Policy Builders**
171
+
172
+ `secure.py` allows you to customize headers such as **Content-Security-Policy** and **Permissions-Policy** with ease:
173
+
174
+ ### **Content-Security-Policy Example**
175
+
176
+ ```python
177
+ import secure
178
+
179
+ # Build a custom CSP policy
180
+ csp = (
181
+ secure.ContentSecurityPolicy()
182
+ .default_src("'self'")
183
+ .script_src("'self'", "cdn.example.com")
184
+ .style_src("'unsafe-inline'")
185
+ .img_src("'self'", "images.example.com")
186
+ .connect_src("'self'", "api.example.com")
187
+ )
188
+
189
+ # Apply it to secure headers
190
+ secure_headers = secure.Secure(csp=csp)
191
+ ```
192
+
193
+ **Resulting HTTP headers:**
194
+
195
+ ```http
196
+ Content-Security-Policy: default-src 'self'; script-src 'self' cdn.example.com; style-src 'unsafe-inline'; img-src 'self' images.example.com; connect-src 'self' api.example.com
197
+ ```
198
+
199
+ ### **Permissions-Policy Example**
200
+
201
+ ```python
202
+ import secure
203
+
204
+ # Build a custom Permissions Policy
205
+ permissions = (
206
+ secure.PermissionsPolicy()
207
+ .geolocation("'self'")
208
+ .camera("'none'")
209
+ .microphone("'none'")
210
+ )
211
+
212
+ # Apply it to secure headers
213
+ secure_headers = secure.Secure(permissions=permissions)
214
+ ```
215
+
216
+ **Resulting HTTP headers:**
217
+
218
+ ```http
219
+ Permissions-Policy: geolocation=('self'), camera=('none'), microphone=('none')
220
+ ```
221
+
222
+ ---
223
+
224
+ ## **Framework Examples**
225
+
226
+ ### **FastAPI**
227
+
228
+ ```python
229
+ from fastapi import FastAPI
230
+
231
+ from secure import Secure
232
+
233
+ app = FastAPI()
234
+ secure_headers = Secure.with_default_headers()
235
+
236
+
237
+ @app.middleware("http")
238
+ async def add_security_headers(request, call_next):
239
+ response = await call_next(request)
240
+ await secure_headers.set_headers_async(response)
241
+ return response
242
+
243
+
244
+ @app.get("/")
245
+ def read_root():
246
+ return {"Hello": "World"}
247
+ ```
248
+
249
+ ### Flask
250
+
251
+ ```python
252
+ from flask import Flask, Response
253
+
254
+ from secure import Secure
255
+
256
+ app = Flask(__name__)
257
+ secure_headers = Secure.with_default_headers()
258
+
259
+
260
+ @app.after_request
261
+ def add_security_headers(response: Response):
262
+ secure_headers.set_headers(response)
263
+ return response
264
+
265
+
266
+ @app.route("/")
267
+ def home():
268
+ return "Hello, world"
269
+
270
+
271
+ if __name__ == "__main__":
272
+ app.run()
273
+ ```
274
+
275
+ ---
276
+
277
+ ## **Documentation**
278
+
279
+ For more details, including advanced configurations and integration examples, please visit the **[full documentation](https://github.com/TypeError/secure/tree/main/docs)**.
280
+
281
+ ---
282
+
283
+ ## **Attribution**
284
+
285
+ This library implements security recommendations from trusted sources:
286
+
287
+ - [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/))
288
+ - [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/))
289
+
290
+ We have included attribution comments in the source code where appropriate.
291
+
292
+ ---
293
+
294
+ ## **Resources**
295
+
296
+ - [OWASP - Secure Headers Project](https://owasp.org/www-project-secure-headers/)
297
+ - [Mozilla Web Security Guidelines](https://infosec.mozilla.org/guidelines/web_security)
298
+ - [MDN Web Docs: Security Headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers#security)
299
+ - [web.dev: Security Best Practices](https://web.dev)
300
+ - [The World Wide Web Consortium (W3C)](https://www.w3.org)
301
+
302
+ ---
303
+
304
+ ### **License**
305
+
306
+ This project is licensed under the terms of the **[MIT License](https://opensource.org/licenses/MIT)**.
307
+
308
+ ---
309
+
310
+ ## **Contributing**
311
+
312
+ Contributions are welcome! If you'd like to contribute to `secure.py`, please feel free to open an issue or submit a pull request on **[GitHub](https://github.com/TypeError/secure)**.
313
+
314
+ ---
315
+
316
+ ## **Changelog**
317
+
318
+ For a detailed list of changes, please refer to the **[CHANGELOG](https://github.com/TypeError/secure/blob/main/CHANGELOG.md)**.
319
+
320
+ ---
321
+
322
+ ## **Acknowledgements**
323
+
324
+ We would like to thank the contributors of MDN Web Docs and OWASP Secure Headers Project for their invaluable resources and guidelines that help make the web a safer place.