starlette-securecookies 1.0.2

Secure cookie middleware for Starlette applications.

starlette-securecookies

Customizable middleware for adding automatic cookie encryption and decryption to Starlette applications.

Tested support on Python 3.7, 3.8, 3.9, and 3.10 on macOS, Windows, and Linux.

How it works?

sequenceDiagram
    Browser->>+Middleware: Encrypted cookies
    Middleware->>+Application: Filtered / Decrypted cookies
    Application->>-Middleware: Plaintext cookies
    Middleware->>-Browser: Encrypted 'Set-Cookie' headers

For any incoming cookies:

1. Requests sent from the client's browser to your application are intercepted by SecureCookiesMiddleware.
2. All Cookie headers are parsed and filter. Only cookies in the included_cookies and excluded_cookies parameters are parsed. All cookies are included by default.
3. The cookies are decrypted. If cookie cannot be decrypted, or is otherwise invalid, it is discarded by default (discard_invalid=True).
4. Any included and valid encrypted cookies in the ASGI request scope are replaced by the decrypted ones.
5. The request scope is passed to any future middleware, and eventually your application. Cookies can be read normally anywhere downstream.

For any outgoing cookies:

7. Your application sets cookies with response.set_cookie as usual.
8. All responses returned by your application are intercepted by SecureCookiesMiddleware.
9. Cookies in the included_cookies and excluded_cookies parameters are re-encrypted, and their attributes (like "SameSite" and "HttpOnly") are overridden by the parameters set in SecureCookiesMiddleware.
10. The cookies in the response are replaced by the re-encrypted cookies, and the response is propagated to Starlette to return to the client's browser.

Installation

$ poetry add starlette-securecookies
# or
$ python -m pip install --user starlette-securecookies

Usage

This is a Starlette-based middleware, so it can be used in any Starlette application or Starlette-based application (like FastAPI or Starlite).

For example,

from starlette.applications import Starlette
from starlette.middleware import Middleware

from securecookies import SecureCookiesMiddleware

middleware = [
    Middleware(
        SecureCookiesMiddleware, secrets=["SUPER SECRET SECRET"]
    )
]

app = Starlette(routes=..., middleware=middleware)

License

This software is licensed under the BSD 3-Clause License.

This 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.