pysigned 0.2.0__tar.gz → 0.2.2__tar.gz

{pysigned-0.2.0 → pysigned-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pysigned
-Version: 0.2.0
+Version: 0.2.2
 Summary: Sign and verify URLs with an expiry, using HMAC or Ed25519
 Author: Meg Hicks
 Author-email: Meg Hicks <meg.d.hicks@gmail.com>
@@ -43,7 +43,7 @@ that can't be altered without invalidating the signature.
 
 ## Installation
 
-Requires Python 3.13+.
+Requires Python 3.11+.
 
 ```sh
 uv add pysigned
@@ -162,6 +162,24 @@ pysigned-gen-key --hmac
 pysigned-gen-key --ed25519 --jwks   # wrap in a JWKS for KeySet.from_jwks
 ```
 
+### Loading keys from the environment
+
+`KeySet.from_env` reads a JWKS (as produced by `pysigned-gen-key --jwks`) from
+an environment variable, so secrets never touch disk as plain key bytes:
+
+```sh
+export APP_SIGNING_KEYS="$(pysigned-gen-key --ed25519 --jwks)"
+```
+
+```python
+from pysigned import KeySet, URLAuth
+
+keys = KeySet.from_env("APP_SIGNING_KEYS")
+signer = URLAuth(keys, ttl=60)
+```
+
+It raises `ValueError` if the variable is unset or empty.
+
 ## Examples
 
 A runnable demo of both backends lives in [examples/sign_urls.py](examples/sign_urls.py):
@@ -170,6 +188,47 @@ A runnable demo of both backends lives in [examples/sign_urls.py](examples/sign_
 uv run python examples/sign_urls.py
 ```
 
+## FastAPI extension
+
+`pysigned[fastapi]` adds `SignedRoute`, a FastAPI dependency that verifies a
+request's URL signature and raises `403 Forbidden` on failure:
+
+```sh
+uv add "pysigned[fastapi]"
+```
+
+```python
+from fastapi import Depends, FastAPI
+from pysigned import KeySet
+from pysigned.extensions.fastapi import SignedRoute
+
+keys = KeySet.from_env("APP_SIGNING_KEYS")
+verify_signature = SignedRoute(keyset=keys)
+
+app = FastAPI()
+
+
+@app.get("/download", dependencies=[Depends(verify_signature)])
+def download():
+    ...
+```
+
+If the keys aren't known until request time — e.g. looking them up per
+tenant — pass `keyset_getter` instead of `keyset`:
+
+```python
+async def keys_for_request(request) -> KeySet:
+    tenant = request.headers["x-tenant-id"]
+    return await load_keys_for_tenant(tenant)
+
+
+verify_signature = SignedRoute(keyset_getter=keys_for_request)
+```
+
+`signing_key_id`, `ignore_query_params`, and `ttl` are forwarded to the
+underlying `URLAuth`; `error_status` overrides the status code raised on a
+failed verification (default: 403).
+
 ## How it works
 
 `URLAuth.sign` builds a canonical byte string from the URL's scheme, host, path,

{pysigned-0.2.0 → pysigned-0.2.2}/README.md

@@ -16,7 +16,7 @@ that can't be altered without invalidating the signature.
 
 ## Installation
 
-Requires Python 3.13+.
+Requires Python 3.11+.
 
 ```sh
 uv add pysigned
@@ -135,6 +135,24 @@ pysigned-gen-key --hmac
 pysigned-gen-key --ed25519 --jwks   # wrap in a JWKS for KeySet.from_jwks
 ```
 
+### Loading keys from the environment
+
+`KeySet.from_env` reads a JWKS (as produced by `pysigned-gen-key --jwks`) from
+an environment variable, so secrets never touch disk as plain key bytes:
+
+```sh
+export APP_SIGNING_KEYS="$(pysigned-gen-key --ed25519 --jwks)"
+```
+
+```python
+from pysigned import KeySet, URLAuth
+
+keys = KeySet.from_env("APP_SIGNING_KEYS")
+signer = URLAuth(keys, ttl=60)
+```
+
+It raises `ValueError` if the variable is unset or empty.
+
 ## Examples
 
 A runnable demo of both backends lives in [examples/sign_urls.py](examples/sign_urls.py):
@@ -143,6 +161,47 @@ A runnable demo of both backends lives in [examples/sign_urls.py](examples/sign_
 uv run python examples/sign_urls.py
 ```
 
+## FastAPI extension
+
+`pysigned[fastapi]` adds `SignedRoute`, a FastAPI dependency that verifies a
+request's URL signature and raises `403 Forbidden` on failure:
+
+```sh
+uv add "pysigned[fastapi]"
+```
+
+```python
+from fastapi import Depends, FastAPI
+from pysigned import KeySet
+from pysigned.extensions.fastapi import SignedRoute
+
+keys = KeySet.from_env("APP_SIGNING_KEYS")
+verify_signature = SignedRoute(keyset=keys)
+
+app = FastAPI()
+
+
+@app.get("/download", dependencies=[Depends(verify_signature)])
+def download():
+    ...
+```
+
+If the keys aren't known until request time — e.g. looking them up per
+tenant — pass `keyset_getter` instead of `keyset`:
+
+```python
+async def keys_for_request(request) -> KeySet:
+    tenant = request.headers["x-tenant-id"]
+    return await load_keys_for_tenant(tenant)
+
+
+verify_signature = SignedRoute(keyset_getter=keys_for_request)
+```
+
+`signing_key_id`, `ignore_query_params`, and `ttl` are forwarded to the
+underlying `URLAuth`; `error_status` overrides the status code raised on a
+failed verification (default: 403).
+
 ## How it works
 
 `URLAuth.sign` builds a canonical byte string from the URL's scheme, host, path,

{pysigned-0.2.0 → pysigned-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pysigned"
-version = "0.2.0"
+version = "0.2.2"
 description = "Sign and verify URLs with an expiry, using HMAC or Ed25519"
 readme = "README.md"
 authors = [

{pysigned-0.2.0 → pysigned-0.2.2}/src/pysigned/extensions/fastapi.py

@@ -5,6 +5,8 @@ module is only imported by code that explicitly opts into it, so the core
 ``pysigned`` package stays installable without FastAPI.
 """
 
+import collections.abc
+
 from typing import Iterable, Protocol
 
 from fastapi import Request, status
@@ -21,7 +23,7 @@ class KeysetGetter(Protocol):
     per-request state, e.g. fetching keys for a tenant from a database.
     """
 
-    async def __call__(self, request: Request) -> KeySet:
+    async def __call__(self, request: Request) -> KeySet | Iterable:
         pass  # pragma: no cover
 
 
@@ -54,7 +56,7 @@ class SignedRoute:
     def __init__(
         self,
         *,
-        keyset: KeySet | None = None,
+        keyset: KeySet | collections.abc.Iterable | None = None,
         keyset_getter: KeysetGetter | None = None,
         signing_key_id: str = "",
         ignore_query_params: Iterable[str] | None = None,

{pysigned-0.2.0 → pysigned-0.2.2}/src/pysigned/signature.py

@@ -99,7 +99,7 @@ class URLAuth:
         Components are joined with a newline (a byte that cannot appear in a URL
         component) so that different field boundaries can never collide.
         """
-        pairs = [(k, v) for k, v in parse_qsl(parsed.query) if k not in self._excluded]
+        pairs = sorted((k, v) for k, v in parse_qsl(parsed.query) if k not in self._excluded)
         canonical = parsed._replace(query=urlencode(pairs))
         parts = (
             str(exp),