sillo-framework 0.2.0__tar.gz → 0.2.1__tar.gz

{sillo_framework-0.2.0 → sillo_framework-0.2.1}/CHANGELOG.md

@@ -5,6 +5,14 @@ All notable changes to Sillo are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.1] - 2026-08-19
+
+### Changed
+
+- Replaced `itsdangerous` with an internal `sillo.helpers.signing` implementation for CSRF tokens and signed session cookies.
+- Moved `sillo.utils` modules into `sillo.helpers`.
+- Fixed `typing-extensions` dependency marker to require the package on Python < 3.13.
+
 ## [Unreleased]
 
 ## [0.2.0] - 2026-08-18

{sillo_framework-0.2.0 → sillo_framework-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sillo-framework
-Version: 0.2.0
+Version: 0.2.1
 Summary: Python with the pieces already in place: an async web framework whose ORM, auth, admin, queues, scheduler and WebSockets share one configuration model.
 Project-URL: Homepage, https://github.com/sillohq/core
 Project-URL: Repository, https://github.com/sillohq/core
@@ -29,10 +29,9 @@ Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Requires-Dist: anyio==4.14.1
-Requires-Dist: itsdangerous>=2.1.2
 Requires-Dist: pydantic<3.0,>=2.0
 Requires-Dist: python-multipart>=0.0.6
-Requires-Dist: typing-extensions>=4.12.2; python_version < '3.10'
+Requires-Dist: typing-extensions>=4.12.2; python_version < '3.13'
 Requires-Dist: uvicorn>=0.27.0
 Provides-Extra: all
 Requires-Dist: argon2-cffi>=21.2.0; extra == 'all'

{sillo_framework-0.2.0 → sillo_framework-0.2.1}/docs/docs/src/content/docs/advanced/security.md

@@ -348,14 +348,14 @@ class CSRFConfig:
 
 ### Token Generation
 
-The middleware uses `itsdangerous.URLSafeSerializer` to sign tokens:
+The middleware uses an internal `URLSafeSerializer` to sign tokens:
 
 ```python
 def _generate_csrf_token(self) -> str:
     return self.serializer.dumps(secrets.token_urlsafe(32))
 ```
 
-A random token is generated with `secrets.token_urlsafe(32)`, then signed with itsdangerous. The signed token is stored in a cookie and must be submitted back in the `X-CSRFToken` header.
+A random token is generated with `secrets.token_urlsafe(32)`, then signed with HMAC-SHA256. The signed token is stored in a cookie and must be submitted back in the `X-CSRFToken` header.
 
 ### Double-Submit Cookie Pattern
 

{sillo_framework-0.2.0 → sillo_framework-0.2.1}/docs/docs/src/content/docs/advanced/sessions.md

@@ -303,12 +303,28 @@ Three methods control when a session expires:
 
 - **`set_expiration_time(expiration: datetime)`** (line 200): Explicit
   override.
-- **`get_expiration_time()`** (line 209): Resolution order:
+- **`get_expiration_time()`**: Resolution order:
   1. Explicit override from `set_expiration_time`
-  2. If `session_permanent` is `False`: `now(utc) + session_expiration_time`
-  3. If `session_permanent` is `True`: `datetime.max` (effectively never)
-  4. Fallback: 7 days if config is unreachable
-- **`has_expired()`** (line 251): `now(utc) > get_expiration_time()`
+  2. If `session_permanent` is `True` (the default):
+     `now(utc) + session_expiration_time`
+  3. If `session_permanent` is `False`: `None` — the cookie goes out with no
+     `Expires` at all, so the browser drops it when it closes
+  4. Fallback: `session_expiration_time`'s default of 86400 if config is
+     unreachable
+- **`has_expired()`**: `now(utc) > get_expiration_time()`, and `False` for a
+  session with no expiry
+
+This used to be inverted — a permanent session got `datetime.max`, so the
+**default** configuration issued a cookie that never expired, and
+`session_expiration_time` applied only to the non-permanent case that did not
+need it.
+
+:::caution[The cookie's expiry is not what protects you]
+`Expires` is a request to the browser. Anyone replaying a captured cookie
+simply does not honour it. For the signed-cookie backend the real bound is
+`SignedSessionManager.max_age`, which is checked against a timestamp inside
+the signature and defaults to `session_expiration_time`.
+:::
 
 ### should_set_cookie
 
@@ -495,11 +511,11 @@ def __init__(self, config=None, secret_key: str | None = None):
     )
 ```
 
-Uses `itsdangerous.URLSafeTimedSerializer` which:
+Uses an internal `URLSafeTimedSerializer` which:
 - Serialises the payload to JSON, then base64url-encodes it.
 - Appends a timestamp.
 - Signs the whole thing with HMAC-SHA256 using the secret key and salt.
-- The salt prevents signature reuse across different itsdangerous contexts.
+- The salt prevents signature reuse across different signing contexts.
 
 ### Signing and Verification
 
@@ -813,7 +829,7 @@ app.use(SessionMiddleware(secret_key="your-secret-key"))
 config = SessionConfig(
     session_cookie_name="app_session",
     session_expiration_time=3600,       # 1 hour
-    session_permanent=False,            # expires with expiration_time
+    session_permanent=False,            # browser-session cookie, no Expires
     session_refresh_each_request=False, # don't refresh on each request
     session_cookie_secure=True,         # HTTPS only
     session_cookie_httponly=True,       # no JavaScript access

{sillo_framework-0.2.0 → sillo_framework-0.2.1}/docs/docs/src/content/docs/guides/concurrency.md

@@ -14,7 +14,7 @@ head:
 
 #  Thread Pool
 
-`sillo.utils.concurrency` provides one utility: `run_in_threadpool`. It moves a synchronous function call to a shared thread pool so the event loop isn't blocked.
+`sillo.helpers.concurrency` provides one utility: `run_in_threadpool`. It moves a synchronous function call to a shared thread pool so the event loop isn't blocked.
 
 For all other async concurrency patterns (`asyncio.gather`,
 `asyncio.TaskGroup`, `asyncio.create_task`, `asyncio.Event`, `asyncio.Lock`)
@@ -26,7 +26,7 @@ already available.
 ##  run_in_threadpool
 
 ```python
-from sillo.utils.concurrency import run_in_threadpool
+from sillo.helpers.concurrency import run_in_threadpool
 ```
 
 Moves a blocking or CPU-intensive function to a background thread and returns the result as an awaitable. The thread pool is shared globally and reused across calls.
@@ -34,7 +34,7 @@ Moves a blocking or CPU-intensive function to a background thread and returns th
 ###  Basic usage
 
 ```python
-from sillo.utils.concurrency import run_in_threadpool
+from sillo.helpers.concurrency import run_in_threadpool
 
 def resize_image(image: bytes, width: int, height: int) -> bytes:
     # CPU-intensive work that would block the event loop
@@ -56,7 +56,7 @@ result = await run_in_threadpool(some_func, arg1, arg2, key="value")
 Exceptions from the sync function propagate normally:
 
 ```python
-from sillo.utils.concurrency import run_in_threadpool
+from sillo.helpers.concurrency import run_in_threadpool
 
 def risky() -> str:
     raise ValueError("boom")

{sillo_framework-0.2.0 → sillo_framework-0.2.1}/docs/docs/src/content/docs/guides/csrf.md

@@ -68,9 +68,12 @@ sillo provides flexible configuration to customize CSRF protection for your appl
   - **Recommended**: `True` in production environments
   - Example: `CSRFConfig(enabled=True)`
 
-- **`secret_key`** (string, required)
+- **`secret_key`** (string, required when `enabled=True`)
   - Cryptographic key used to sign CSRF tokens
-  - **Security Note**: Keep this secret and consistent across application restarts
+  - **Security Note**: Keep this secret and consistent across application restarts.
+    Changing it invalidates every token in flight, so the next request from each
+    open page is a 403 until it reloads.
+  - Enabling CSRF without one raises `ValueError` at startup
   - Example: `CSRFConfig(secret_key="your-secure-key-123")`
 
 ###  URL Configuration
@@ -83,7 +86,16 @@ sillo provides flexible configuration to customize CSRF protection for your appl
 - **`exempt_urls`** (list of strings, default: `[]`)
   - URL patterns excluded from CSRF protection
   - Takes precedence over `required_urls`
-  - Example: `["/api/public/*", "/webhooks/stripe"]`
+  - Patterns are regular expressions and must match the **whole** path, so
+    `/webhooks` does not exempt `/webhooks/stripe` — write `/webhooks/.*`
+  - Example: `["/api/public/.*", "/webhooks/stripe"]`
+
+- **`sensitive_cookies`** (list of strings, default: `[]`)
+  - Cookies that carry ambient authority, typically your session cookie
+  - When set, only requests presenting one of them are checked — which is what
+    lets an API authenticated by an `Authorization` header skip the token
+  - Naming none keeps the safe default of treating every request as sensitive
+  - Example: `CSRFConfig(sensitive_cookies=["session_id"])`
 
 ###  HTTP Methods
 
@@ -104,9 +116,14 @@ sillo provides flexible configuration to customize CSRF protection for your appl
   - **Security Best Practice**: Set to `True` in production
   - Example: `CSRFConfig(cookie_secure=True)`
 
-- **`cookie_httponly`** (boolean, default: `True`)
+- **`cookie_httponly`** (boolean, default: `False`)
   - Prevents JavaScript from accessing the cookie
-  - **Security Best Practice**: Keep this as `True`
+  - **Leave this off.** The double-submit pattern requires the page to read
+    this cookie and echo it back in `header_name`, which `HttpOnly` makes
+    impossible — an `HttpOnly` CSRF cookie cannot be used by any JavaScript
+    client. The token is not a credential: it is only useful to someone who
+    can already read the page. Turn it on only if every form is server-rendered
+    with `{{ csrf_token }}` and nothing submits over AJAX.
   - Example: `CSRFConfig(cookie_httponly=True)`
 
 - **`cookie_samesite`** (string, default: `"lax"`)
@@ -121,9 +138,12 @@ sillo provides flexible configuration to customize CSRF protection for your appl
   - HTTP header name for sending CSRF tokens in AJAX requests
   - Example: `CSRFConfig(header_name="X-CSRF-TOKEN")`
 
-- **`form_field`** (string, default: `"csrf_token"`)
+- **`form_field`** (string, default: `"csrftoken"`)
   - Form field name for CSRF tokens in HTML forms
   - Must match your form field names
+  - Read for both `application/x-www-form-urlencoded` and
+    `multipart/form-data` bodies, so file-upload forms — which cannot set a
+    header — can submit a token too
   - Example: `CSRFConfig(form_field="_csrf_token")`
 
 - **`cookie_path`** (string, default: `"/"`)

{sillo_framework-0.2.0 → sillo_framework-0.2.1}/docs/docs/src/content/docs/guides/sessions.md

@@ -112,12 +112,27 @@ because one of the two would otherwise have to win silently.
 | `session_cookie_secure`         | Send the cookie over HTTPS only                        | `True`                 |
 | `session_cookie_httponly`       | Keep the cookie out of reach of JavaScript             | `True`                 |
 | `session_cookie_samesite`       | SameSite attribute (`"lax"`, `"strict"`, or `"none"`)  | `"lax"`                |
-| `session_expiration_time`       | Session lifetime in seconds                            | `86400` (24 hours)     |
+| `session_expiration_time`       | Session lifetime in seconds, enforced in the signature  | `86400` (24 hours)     |
 | `session_permanent`             | Whether the cookie carries an expiry at all            | `True`                 |
 | `session_refresh_each_request`  | Re-send the cookie on every response, sliding expiry   | `True`                 |
 | `session_file_storage_path`     | Directory the file backend writes to                   | `None`                 |
 | `manager`                       | A session backend instance                             | `SignedSessionManager` |
 
+:::caution[The signed cookie is signed, not encrypted]
+With the default backend the session's contents travel in the cookie. Anyone
+holding it can base64-decode it and read every key — put identifiers in a
+session, not secrets.
+
+`session_expiration_time` is checked against a timestamp inside the signature,
+not just written to the cookie's `Expires`, so a captured cookie stops working
+once it lapses. Nothing else revokes one: there is no server-side record to
+delete, so signing out clears the browser's copy but cannot invalidate a copy
+someone else kept. Use a server-side backend where that matters.
+
+Browsers cap a cookie at about 4096 bytes and drop larger ones without saying
+so. Sillo warns when a session cookie crosses that line.
+:::
+
 :::caution
 **`session_cookie_secure` in local development.** It defaults to `True`, and a
 browser will not return a `Secure` cookie over plain `http://`. Serving over

{sillo_framework-0.2.0 → sillo_framework-0.2.1}/pyproject.toml

@@ -10,7 +10,7 @@ packages = ["sillo"]
 
 [project]
 name = "sillo-framework"
-version = "0.2.0"
+version = "0.2.1"
 description = "Python with the pieces already in place: an async web framework whose ORM, auth, admin, queues, scheduler and WebSockets share one configuration model."
 authors = [
     {name = "Chidebele Dunamis", email = "techwithdunamix@gmail.com"}
@@ -62,10 +62,9 @@ classifiers = [
 dependencies = [
     "uvicorn>=0.27.0",
     "anyio==4.14.1",
-    "itsdangerous>=2.1.2",
     "python-multipart>=0.0.6",
     "pydantic>=2.0,<3.0",
-    "typing-extensions>=4.12.2; python_version<'3.10'",
+    "typing-extensions>=4.12.2; python_version<'3.13'",
 ]
 
 # CORE: Only includes what's required for any sillo app (HTTP routing, config, password hashing)

{sillo_framework-0.2.0 → sillo_framework-0.2.1}/requirements.txt

@@ -1,6 +1,5 @@
 uvicorn>=0.27.0
 anyio==4.14.1
-itsdangerous>=2.1.2
 python-multipart>=0.0.6
 typing-extensions==4.16.0
 pydantic>=2.0,<3.0

{sillo_framework-0.2.0 → sillo_framework-0.2.1}/sillo/__init__.py

@@ -110,7 +110,7 @@ Common Patterns:
 
 from sillo.core.routing import Group, Route, Router, WebsocketRoute
 
-__version__: str = "0.2.0"
+__version__: str = "0.2.1"
 
 from sillo.core.dependencies import Depend
 

{sillo_framework-0.2.0 → sillo_framework-0.2.1}/sillo/core/http/response.py

@@ -51,6 +51,37 @@ Send = typing.Callable[[Message], typing.Awaitable[None]]
 
 JSONType = Union[str, int, float, bool, None, dict[str, Any], list[Any]]
 
+#: The expiry :meth:`BaseResponse.delete_cookie` sends. A fixed instant in the
+#: past, so it does not depend on the client's clock agreeing with the
+#: server's.
+_EXPIRED = "Thu, 01 Jan 1970 00:00:00 GMT"
+
+#: Punctuation a cookie value may carry unescaped: ``http.cookies._LegalChars``
+#: — anything outside it makes ``SimpleCookie`` fall back to backslash-quoting
+#: the whole value — less ``%``, which is spent on being the escape character.
+#: Alphanumerics are always left alone by ``quote``. Base64url tokens are made
+#: of ``-``, ``_``, ``.`` and alphanumerics, so they pass through untouched.
+_COOKIE_SAFE = "!#$&'*+-.:^_`|~"
+
+
+def _encode_cookie_value(value: str) -> str:
+    """Percent-encode *value* so it survives a round trip through a browser.
+
+    Handed a value it considers illegal, ``SimpleCookie`` wraps it in double
+    quotes and escapes the awkward characters as backslash-octal. Nothing
+    undoes that:
+    :func:`~sillo.core.http.cookies.parse_cookies` percent-decodes, as browsers
+    and ``document.cookie`` do, so ``set_cookie("flash", "a=b/c%20d")`` came
+    back as ``'"a=b/c d"'`` — quotes still attached and the escape decoded
+    that nobody wrote.
+
+    Percent-encoding here instead makes writing and reading each other's
+    inverse, and matches what ``encodeURIComponent`` produces on the client.
+    Ordinary values — base64url tokens, identifiers, numbers — contain nothing
+    outside the safe set and pass through untouched.
+    """
+    return quote(value, safe=_COOKIE_SAFE)
+
 
 class MalformedRangeHeader(Exception):
     """Exception raised when a Range header cannot be parsed.
@@ -367,7 +398,7 @@ class BaseResponse:
                 or ``"none"`` (case-insensitive).
         """
         cookie: http.cookies.BaseCookie[str] = http.cookies.SimpleCookie()
-        cookie[key] = value
+        cookie[key] = _encode_cookie_value(value)
         if max_age is not None:
             cookie[key]["max-age"] = max_age
         if expires is not None:
@@ -389,6 +420,15 @@ class BaseResponse:
                 "lax",
                 "none",
             ], "samesite must be either 'strict', 'lax' or 'none'"
+            if samesite.lower() == "none" and not secure:
+                # Browsers reject SameSite=None without Secure and drop the
+                # cookie without telling anyone, so the setting that was meant
+                # to allow cross-site use instead switches the cookie off.
+                raise ValueError(
+                    f"Cookie {key!r} sets samesite='none' without secure=True. "
+                    f"Browsers reject that combination and drop the cookie "
+                    f"silently. Pass secure=True, or use samesite='lax'."
+                )
             cookie[key]["samesite"] = samesite
         cookie_val = cookie.output(header="").strip()
         self.set_header("set-cookie", cookie_val)
@@ -396,14 +436,20 @@ class BaseResponse:
         return cookie
 
     def delete_cookie(
-        self, key: str, path: str = "/", domain: str | None = None
+        self,
+        key: str,
+        path: str = "/",
+        domain: str | None = None,
+        secure: bool | None = False,
+        httponly: bool | None = False,
+        samesite: typing.Literal["lax", "strict", "none"] | None = "lax",
     ) -> Any:
         """Delete a cookie by setting its expiration to the past.
 
-        Sends a ``Set-Cookie`` header with an empty value and zero expiration,
-        instructing the client to remove the specified cookie.  The path and
-        domain must match those used when the cookie was originally set for
-        the deletion to take effect.
+        Sends a ``Set-Cookie`` header with an empty value and an expiry in the
+        past, instructing the client to remove the specified cookie.  The path
+        and domain must match those used when the cookie was originally set
+        for the deletion to take effect.
 
         Args:
             key: The name of the cookie to delete.
@@ -411,6 +457,13 @@ class BaseResponse:
                 match the original cookie's path.  Defaults to ``"/"``.
             domain: The domain where the cookie was originally set.  Must
                 match the original cookie's domain.  Defaults to ``None``.
+            secure: Whether to repeat the ``Secure`` attribute.  Needed to
+                delete a cookie whose name carries the ``__Secure-`` or
+                ``__Host-`` prefix, since browsers reject a ``Set-Cookie`` for
+                one of those names that is not marked ``Secure`` — so without
+                it the deletion is ignored and the user stays signed in.
+            httponly: Whether to repeat the ``HttpOnly`` attribute.
+            samesite: Whether to repeat the ``SameSite`` attribute.
 
         Returns:
             The underlying ``SimpleCookie`` object for advanced manipulation.
@@ -418,8 +471,21 @@ class BaseResponse:
         Raises:
             None: This method does not raise exceptions.
         """
+        # A fixed date in the past, not `expires=0`. `SimpleCookie` reads a
+        # numeric expires as an offset from now, so `0` rendered as the current
+        # time -- which is only in the past if the client's clock agrees with
+        # the server's, and a client running a few seconds behind kept the
+        # cookie.
         cookie = self.set_cookie(
-            key=key, value="", max_age=0, expires=0, path=path, domain=domain
+            key=key,
+            value="",
+            max_age=0,
+            expires=_EXPIRED,
+            path=path,
+            domain=domain,
+            secure=secure,
+            httponly=httponly,
+            samesite=samesite,
         )
 
         return cookie
@@ -1838,12 +1904,23 @@ class Responder:
         key: str,
         path: str = "/",
         domain: str | None = None,
+        secure: bool | None = False,
+        httponly: bool | None = False,
+        samesite: typing.Literal["lax", "strict", "none"] | None = "lax",
     ):
-        """Delete a response cookie."""
+        """Delete a response cookie.
+
+        The security attributes have to match the ones the cookie was set with
+        closely enough for the browser to accept the deletion — see
+        :meth:`BaseResponse.delete_cookie`.
+        """
         self._response.delete_cookie(
             key=key,
             path=path,
             domain=domain,
+            secure=secure,
+            httponly=httponly,
+            samesite=samesite,
         )
 
         return self

{sillo_framework-0.2.0 → sillo_framework-0.2.1}/sillo/core/routing/router.py

@@ -51,7 +51,7 @@ from sillo.types import (
     Scope,
     Send,
 )
-from sillo.utils.concurrency import run_in_threadpool
+from sillo.helpers.concurrency import run_in_threadpool
 from sillo.validation import (
     RequestValidationError,
     ResponseModelValidator,

{sillo_framework-0.2.0 → sillo_framework-0.2.1}/sillo/helpers/crypto.py

@@ -212,8 +212,13 @@ def unsign_value(
             match the secret used during signing.
         algorithm: The hash algorithm name used for HMAC. Must match the
             algorithm used during signing. Defaults to ``"sha256"``.
-        max_age: Optional maximum age in seconds for the signed value.
-            Reserved for future use; currently not enforced.
+        max_age: Not supported. ``sign_value`` puts no timestamp in the token,
+            so there is nothing here to measure an age against. Passing it
+            raises rather than being quietly ignored, which is what this did
+            before — a caller who set it believed they had bounded the
+            token's life and had not. Use
+            :class:`sillo.helpers.signing.URLSafeTimedSerializer` when a signed
+            value needs to expire.
 
     Returns:
         The original plaintext string value that was signed.
@@ -221,7 +226,15 @@ def unsign_value(
     Raises:
         BadSignature: If the signature is invalid, the token format is
             malformed, or the secret does not match.
+        NotImplementedError: If *max_age* is given.
     """
+    if max_age is not None:
+        raise NotImplementedError(
+            "unsign_value() cannot enforce max_age: sign_value() writes no "
+            "timestamp into the token, so its age is unknowable. Use "
+            "sillo.helpers.signing.URLSafeTimedSerializer for values that expire."
+        )
+
     secret_bytes: bytes
     if isinstance(secret, str):
         secret_bytes = secret.encode()
@@ -229,14 +242,23 @@ def unsign_value(
         secret_bytes = secret
 
     try:
-        payload_b64, _, signature = signed.rpartition(".")
-        value = base64.urlsafe_b64decode(payload_b64 + "==").decode()
+        payload_b64, separator, signature = signed.rpartition(".")
+        if not separator:
+            raise BadSignature("Invalid signed value")
+
+        # Restore exactly the padding that was stripped. Appending a fixed
+        # "==" happened to decode for the lengths tried, but it is not the
+        # inverse of `rstrip("=")` and leaves the format resting on how
+        # leniently `b64decode` treats over-padding.
+        value = base64.urlsafe_b64decode(
+            payload_b64 + "=" * (-len(payload_b64) % 4)
+        ).decode()
 
         expected = _hmac.new(secret_bytes, value.encode(), algorithm).hexdigest()
         if not _hmac.compare_digest(expected, signature):
             raise BadSignature("Invalid signature")
     except Exception:
-        raise BadSignature("Invalid signed value")
+        raise BadSignature("Invalid signed value") from None
 
     return value