{"id":20207938,"url":"https://github.com/thearchitector/starlette-securecookies","last_synced_at":"2025-11-11T20:35:58.768Z","repository":{"id":57677748,"uuid":"488443694","full_name":"thearchitector/starlette-securecookies","owner":"thearchitector","description":"Secure cookie middleware for Starlette applications.","archived":false,"fork":false,"pushed_at":"2023-07-10T05:16:18.000Z","size":153,"stargazers_count":14,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-24T11:38:45.799Z","etag":null,"topics":["asgi","cookies","encryption","fastapi","middleware","poetry","starlette"],"latest_commit_sha":null,"homepage":"https://securecookies.thearchitector.dev","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thearchitector.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-05-04T03:47:57.000Z","updated_at":"2024-11-15T06:10:46.000Z","dependencies_parsed_at":"2024-11-14T05:33:32.441Z","dependency_job_id":"63a3d8cf-491e-47c8-8a8a-e395cd89427c","html_url":"https://github.com/thearchitector/starlette-securecookies","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thearchitector%2Fstarlette-securecookies","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thearchitector%2Fstarlette-securecookies/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thearchitector%2Fstarlette-securecookies/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thearchitector%2Fstarlette-securecookies/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thearchitector","download_url":"https://codeload.github.com/thearchitector/starlette-securecookies/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248221292,"owners_count":21067508,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asgi","cookies","encryption","fastapi","middleware","poetry","starlette"],"created_at":"2024-11-14T05:33:21.695Z","updated_at":"2025-11-11T20:35:53.737Z","avatar_url":"https://github.com/thearchitector.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# starlette-securecookies\n\n![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/thearchitector/starlette-securecookies/CI.yaml?label=tests\u0026style=flat-square)\n![PyPI - Downloads](https://img.shields.io/pypi/dw/starlette-securecookies?style=flat-square)\n![GitHub](https://img.shields.io/github/license/thearchitector/starlette-securecookies?style=flat-square)\n[![Buy a tree](https://img.shields.io/badge/Treeware-%F0%9F%8C%B3-lightgreen?style=flat-square)](https://ecologi.com/eliasgabriel?r=6128126916bfab8bd051026c)\n\nCustomizable middleware for adding automatic cookie encryption and decryption to Starlette applications.\n\nTested support on Python 3.7, 3.8, 3.9, and 3.10, 3.11 on macOS, Windows, and Linux.\n\n## How it works?\n\n```mermaid\nsequenceDiagram\n    Browser-\u003e\u003e+Middleware: Encrypted 'Cookie' headers\n    Middleware-\u003e\u003e+Application: Decrypted cookies\n    Application-\u003e\u003e-Middleware: Plaintext cookies\n    Middleware-\u003e\u003e-Browser: Encrypted 'Set-Cookie' headers\n    Note over Application: *The Application may be your service\u003cbr /\u003eor any additional middleware.\n```\n\nFor any incoming cookies:\n\n1. Requests sent from the client's browser to your application are intercepted by `SecureCookiesMiddleware`.\n2. All `Cookie` headers are filtered and parsed. Only cookies in the `included_cookies` and `excluded_cookies` parameters are parsed. All cookies are included by default.\n3. The cookies are decrypted. If a cookie cannot be decrypted, or is otherwise invalid, it is discarded by default (`discard_invalid=True`).\n4. Any included and valid encrypted cookies in the ASGI request scope are replaced by the decrypted ones.\n5. The request scope is passed to any future middleware, and eventually your application. Cookies can be read normally anywhere downstream.\n\nFor any outgoing cookies:\n\n7. Your application sets cookies with `response.set_cookie`, or by any other means of creating `Set-Cookie` headers.\n8. Other middleware run and add additional cookies, like [SessionMiddleware](https://www.starlette.io/middleware/#sessionmiddleware).\n9. All responses returned by your application are intercepted by `SecureCookiesMiddleware`.\n10. Cookies in the `included_cookies` and not in the `excluded_cookies` parameters are re-encrypted, and their attributes (like `\"SameSite\"` and `\"HttpOnly\"`) are overridden by any parameters set in `SecureCookiesMiddleware`.\n11. The cookies in the response are replaced by the re-encrypted cookies, and the response is eventually propagated to the client's browser.\n\n## Installation\n\n```sh\n$ pdm add starlette-securecookies\n# or\n$ python -m pip install --user starlette-securecookies\n```\n\n## Usage\n\nThis is a Starlette-based middleware, so it can be used in any Starlette application or Starlette-based framework (like [FastAPI](https://fastapi.tiangolo.com/advanced/middleware/)).\n\nFor example,\n\n```python\nfrom starlette.applications import Starlette\nfrom starlette.middleware import Middleware\n\nfrom securecookies import SecureCookiesMiddleware\n\nmiddleware = [\n    Middleware(\n        SecureCookiesMiddleware, secrets=[\"SUPER SECRET SECRET\"],\n        # your other middleware\n    )\n]\n\napp = Starlette(routes=..., middleware=middleware)\n```\n\nNote that if you're using another middleware that injects cookies into the response (such as [SessionMiddleware](https://www.starlette.io/middleware/#sessionmiddleware)), you have to make sure `SecureCookiesMiddleware` executes _after_ it so the cookie is present at encryption-time. Counter intuitively, in practice this means ensuring `SecureCookiesMiddleware` is _first_ in the list of middleware.\n\n### Extras\n\n`starlette-securecookies` provides some extras that introduce or patch secure cookie functionality into existing tools. They all reside in the `securecookies.extras` module. Currently there is only one, but more are welcome by recommendation or Pull Request!\n\n- **`csrf.SecureCSRFMiddleware`**: Adds compatibility to the CSRF middleware provided by [starlette_csrf](https://github.com/frankie567/starlette-csrf). To use it, simply add it to your list of middleware (keep in mind the ordering). If you don't want to specify `starlette_csrf` as a direct dependency, you can also install it through the `[csrf]` package extra.\n\n## License\n\nThis software is licensed under the [BSD 3-Clause License](LICENSE).\n\nThis package is Treeware. If you use it in production, consider buying the world a tree to thank me for my work. By contributing to my forest, you’ll be creating employment for local families and restoring wildlife habitats.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthearchitector%2Fstarlette-securecookies","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthearchitector%2Fstarlette-securecookies","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthearchitector%2Fstarlette-securecookies/lists"}