veil-api-kit 0.10.0__py3-none-any.whl

veil_api_kit-0.10.0.dist-info/METADATA

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: veil-api-kit
+Version: 0.10.0
+Summary: Helpers for veil-api: cookies, sessions, CORS, security, static files, GraphQL, gRPC client, DI, tasks
+Author: aofusa
+License-Expression: Apache-2.0 OR MIT
+Project-URL: Documentation, https://veil-api.readthedocs.io
+Project-URL: Source, https://github.com/aofusa/veil-proxy
+Project-URL: Changelog, https://github.com/aofusa/veil-proxy/releases
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: veil-api==0.10.0
+Provides-Extra: jwt
+Requires-Dist: PyJWT>=2; extra == "jwt"
+Provides-Extra: graphql
+Requires-Dist: strawberry-graphql>=0.200; extra == "graphql"
+Provides-Extra: grpc
+Requires-Dist: protobuf>=4; extra == "grpc"
+Provides-Extra: grpcio
+Requires-Dist: grpcio; extra == "grpcio"
+Requires-Dist: grpcio-tools; extra == "grpcio"
+Requires-Dist: protobuf>=4; extra == "grpcio"
+Provides-Extra: redis
+Requires-Dist: redis>=4.2; extra == "redis"
+Provides-Extra: cron
+Requires-Dist: croniter; extra == "cron"
+Provides-Extra: all
+Requires-Dist: PyJWT>=2; extra == "all"
+Requires-Dist: strawberry-graphql>=0.200; extra == "all"
+Requires-Dist: protobuf>=4; extra == "all"
+Requires-Dist: grpcio; extra == "all"
+Requires-Dist: grpcio-tools; extra == "all"
+Requires-Dist: redis>=4.2; extra == "all"
+Requires-Dist: croniter; extra == "all"
+
+# veil-api-kit
+
+Helpers for [veil-api](https://pypi.org/project/veil-api/) applications (`import veil_kit`). It is a pure-Python
+package with the same version as `veil-api`. Optional dependencies come with extras:
+
+```sh
+pip install veil-api-kit                     # cookies, sessions, CORS, security, static files, DI, tasks
+pip install "veil-api-kit[jwt]"              # JWT (PyJWT)
+pip install "veil-api-kit[graphql]"          # GraphQL (strawberry)
+pip install "veil-api-kit[grpc]"             # gRPC client and server helpers (protobuf)
+pip install "veil-api-kit[grpcio]"           # + grpcio and grpcio-tools (code generation, grpc.RpcError)
+pip install "veil-api-kit[redis]"            # Redis session store
+pip install "veil-api-kit[cron]"             # croniter (more cron syntax)
+pip install "veil-api-kit[all]"
+```
+
+| Module | What it does |
+|---|---|
+| `veil_kit.cookies` | Signed cookies (itsdangerous-compatible format, key rotation) |
+| `veil_kit.sessions` | Cookie sessions (Starlette `SessionMiddleware` format) and server-side stores (memory, Redis) |
+| `veil_kit.cors` | `CORSMiddleware` with Starlette's arguments, answered natively by the server |
+| `veil_kit.security` | `HTTPBasic`, `HTTPBearer`, `APIKeyHeader`, `OAuth2PasswordBearer`, `OAuth2PasswordRequestForm`, `JWT` |
+| `veil_kit.redirects` | `safe_redirect`: redirect only to this site or to listed hosts |
+| `veil_kit.staticfiles` | `StaticFiles(directory=...)` served by the server's file backend (sendfile) |
+| `veil_kit.graphql` | strawberry schemas over HTTP, SSE and WebSocket, with GraphiQL |
+| `veil_kit.grpc` | A channel for `grpc_tools` stubs (sync and `grpc.aio` style), server helpers |
+| `veil_kit.di` | A dependency injection container (singleton, scoped, transient) |
+| `veil_kit.tasks` | Periodic, cron and resident tasks |
+| `veil_kit.testing` | `TestClient` and dependency overrides |
+
+## Example
+
+```python
+import veil
+from veil_kit.cors import CORSMiddleware
+from veil_kit.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm, JWT
+from veil_kit.staticfiles import StaticFiles
+
+app = veil.App()
+app.add_middleware(CORSMiddleware, allow_origins=["https://app.example.com"])
+app.mount("/static", StaticFiles(directory="public"))
+
+oauth2 = OAuth2PasswordBearer(tokenUrl="/token")
+tokens = JWT(secret="change-me")
+
+@app.post("/token")
+def token(form: OAuth2PasswordRequestForm = veil.Depends()):
+    if form.password != "secret":
+        raise veil.HTTPException(400, "bad credentials")
+    return {"access_token": tokens.encode({"sub": form.username}), "token_type": "bearer"}
+
+def current_user(token: str = veil.Depends(oauth2)):
+    return tokens.decode(token)["sub"]
+
+@app.get("/me")
+def me(user: str = veil.Depends(current_user)):
+    return {"user": user}
+
+app.run(listen_cleartext="127.0.0.1:8000")
+```
+
+Documentation: <https://veil-api.readthedocs.io> (the "Kit" and "FastAPI compatibility" pages).
+
+License: Apache-2.0 OR MIT.

veil_api_kit-0.10.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+veil_kit/__init__.py,sha256=W8SKuZsebVKp9PEt0bs-ppJCm0BR2eF8-eJ5irIWQUM,1132
+veil_kit/cookies.py,sha256=fckRTNRKqdAHahxsFfksCRQK-GcwmsFYWyA7MPQuJPM,5445
+veil_kit/cors.py,sha256=30Ba4xNTrqA6MgVOyHpWv87vDYF6kJ3pyQo5A8eUElU,1536
+veil_kit/di.py,sha256=LaZNOedUnbn5fnPl666d39mcYIavOWgR3_MR2LLjvaI,13240
+veil_kit/graphql.py,sha256=dUWBUBqV7cyaJ29pWwOjJqO5te5HWhzNbSnojvMDoNw,9561
+veil_kit/grpc.py,sha256=1C59xV2gsGySNfoc5fP5M2N6UKJv2LRiE61wACjjWd0,17468
+veil_kit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+veil_kit/redirects.py,sha256=pQ-76L-0sJfGHq_IJXAh06XhO5BdFpaiTOB1IwQkgPQ,1258
+veil_kit/security.py,sha256=f91cG7OoMbWlIp1mCAo2b8lkamWdv9wHcaIiCH3BO_E,14166
+veil_kit/sessions.py,sha256=TVXuY30W4WoknfRHtWCmBF96DDzwVIf5GO3BGU8yRQw,8326
+veil_kit/staticfiles.py,sha256=F3luFEUMbswyIKFXKPh02UG-UKYC5AGF0j4CoWaSGDM,1525
+veil_kit/tasks.py,sha256=KGoAi5hW_FVVCezYq6Sz2jhdLuxAuvd_KVyZtLW_4b0,7152
+veil_kit/testing.py,sha256=qR9HBxaIJaMNQArPd-zUsfBdh-ti0iWWq4M-EhAkwYc,783
+veil_api_kit-0.10.0.dist-info/METADATA,sha256=TotXcHXe7fWks4aJXZuYGS46O-dTyKVqKKpIAPNShzo,4454
+veil_api_kit-0.10.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+veil_api_kit-0.10.0.dist-info/top_level.txt,sha256=r5W7RUXJPq_6VTKI-FoF_E_Az6Ik-FjF2SC6afETDkY,9
+veil_api_kit-0.10.0.dist-info/RECORD,,

veil_api_kit-0.10.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

veil_api_kit-0.10.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+veil_kit

veil_kit/__init__.py

@@ -0,0 +1,21 @@
+"""Helpers for veil-api applications.
+
+Each module is imported on its own (``from veil_kit.security import OAuth2PasswordBearer``); optional
+dependencies are installed with extras (``pip install "veil-api-kit[jwt,graphql,grpc]"``):
+
+* ``veil_kit.cookies`` - signed cookies (itsdangerous-compatible format, key rotation)
+* ``veil_kit.sessions`` - cookie sessions (Starlette-compatible) and server-side stores (memory, Redis)
+* ``veil_kit.cors`` - ``CORSMiddleware`` on top of the native ``app.cors()``
+* ``veil_kit.security`` - HTTP Basic / Bearer / Digest, API keys, OAuth2, JWT (PyJWT)
+* ``veil_kit.redirects`` - ``safe_redirect`` to allowed hosts only
+* ``veil_kit.staticfiles`` - ``StaticFiles`` served natively (sendfile, no Python per request)
+* ``veil_kit.graphql`` - strawberry schemas over HTTP, SSE and WebSocket
+* ``veil_kit.grpc`` - a channel for ``grpc_tools`` stubs and the server helpers
+* ``veil_kit.di`` - a dependency injection container
+* ``veil_kit.tasks`` - periodic, cron and resident tasks
+* ``veil_kit.testing`` - ``TestClient`` and dependency overrides
+"""
+
+__version__ = "0.10.0"
+
+__all__ = ["__version__"]

veil_kit/cookies.py

@@ -0,0 +1,145 @@
+"""Signed cookies.
+
+:class:`Signer` produces and checks the format of itsdangerous' ``TimestampSigner`` (``value.timestamp.signature``,
+HMAC-SHA1 with the ``django-concat`` key derivation), so cookies written by Flask or Starlette's ``SessionMiddleware``
+with the same secret are accepted and the other way round. Several secrets rotate keys: the last one signs, all of them
+verify.
+
+.. code-block:: python
+
+    from veil_kit.cookies import SignedCookies
+
+    cookies = SignedCookies("change-me", max_age=3600)
+
+    @app.get("/login")
+    def login(response: veil.Response):
+        cookies.set(response, "user", "alice", httponly=True)
+        return "ok"
+
+    @app.get("/me")
+    def me(request: veil.Request):
+        return {"user": cookies.get(request, "user")}
+"""
+
+# F-268: itsdangerous の TimestampSigner と同じ形式（Starlette の SessionMiddleware の Cookie と互換）
+
+import base64
+import hashlib
+import hmac
+import time
+
+__all__ = ["Signer", "BadSignature", "SignatureExpired", "SignedCookies", "parse_cookies"]
+
+
+class BadSignature(Exception):
+    """The value was not signed with one of the secrets (or was changed)."""
+
+
+class SignatureExpired(BadSignature):
+    """The signature is valid but older than ``max_age``."""
+
+
+def _b64e(b):
+    return base64.urlsafe_b64encode(b).rstrip(b"=")
+
+
+def _b64d(b):
+    return base64.urlsafe_b64decode(b + b"=" * (-len(b) % 4))
+
+
+def _int_to_bytes(n):
+    return n.to_bytes((n.bit_length() + 7) // 8 or 1, "big")
+
+
+class Signer:
+    """Signs values with a timestamp (the format of itsdangerous' ``TimestampSigner``)."""
+
+    def __init__(self, secret_key, salt=b"itsdangerous.Signer", sep=b"."):
+        """``secret_key`` is a ``str`` / ``bytes`` or a list of them (oldest first)."""
+        keys = secret_key if isinstance(secret_key, (list, tuple)) else [secret_key]
+        if not keys:
+            raise ValueError("at least one secret key is needed")
+        salt = salt.encode() if isinstance(salt, str) else salt
+        self.sep = sep
+        # django-concat: sha1(salt + b"signer" + secret)
+        self._keys = [hashlib.sha1(salt + b"signer" + (k.encode() if isinstance(k, str) else k)).digest() for k in keys]
+
+    def _sig(self, key, value):
+        return _b64e(hmac.new(key, value, hashlib.sha1).digest())
+
+    def sign(self, value):
+        """Return ``value.timestamp.signature`` (``bytes``)."""
+        value = value.encode() if isinstance(value, str) else value
+        v = value + self.sep + _b64e(_int_to_bytes(int(time.time())))
+        return v + self.sep + self._sig(self._keys[-1], v)
+
+    def unsign(self, signed, max_age=None):
+        """Return the value of ``signed``; raise :class:`BadSignature` or :class:`SignatureExpired`."""
+        signed = signed.encode() if isinstance(signed, str) else signed
+        v, sep, sig = signed.rpartition(self.sep)
+        if not sep:
+            raise BadSignature("no separator")
+        if not any(hmac.compare_digest(self._sig(k, v), sig) for k in reversed(self._keys)):
+            raise BadSignature("signature does not match")
+        value, sep, ts = v.rpartition(self.sep)
+        if not sep:
+            raise BadSignature("no timestamp")
+        try:
+            t = int.from_bytes(_b64d(ts), "big")
+        except Exception:  # noqa: BLE001
+            raise BadSignature("bad timestamp")
+        if max_age is not None and time.time() - t > max_age:
+            raise SignatureExpired("signature expired")
+        return value
+
+
+def parse_cookies(header):
+    """Parse a ``Cookie`` header into a dict (the first value of a repeated name wins; quotes are removed)."""
+    out = {}
+    for part in (header or "").split(";"):
+        name, eq, value = part.partition("=")
+        if not eq:
+            continue
+        name = name.strip()
+        value = value.strip()
+        if len(value) >= 2 and value[0] == value[-1] == '"':
+            value = value[1:-1]
+        if name and name not in out:
+            out[name] = value
+    return out
+
+
+def _request_cookies(request):
+    c = getattr(request, "cookies", None)
+    if c is not None:
+        return c
+    return parse_cookies(", ".join(request.headers.getlist("cookie")).replace(", ", "; "))
+
+
+class SignedCookies:
+    """Reads and writes cookies signed by a :class:`Signer`."""
+
+    def __init__(self, secret_key, max_age=None, salt="veil_kit.cookies"):
+        """``max_age`` (seconds) rejects older signatures; ``salt`` separates the uses of one secret."""
+        self.signer = Signer(secret_key, salt=salt)
+        self.max_age = max_age
+
+    def get(self, request, name, default=None):
+        """The verified value of cookie ``name`` (``default`` when absent, unsigned, changed or expired)."""
+        raw = _request_cookies(request).get(name)
+        if raw is None:
+            return default
+        try:
+            return self.signer.unsign(raw, self.max_age).decode("utf-8")
+        except (BadSignature, UnicodeDecodeError):
+            return default
+
+    def set(self, response, name, value, **options):
+        """Set cookie ``name`` to the signed ``value`` (``options`` as for ``Response.set_cookie``)."""
+        if self.max_age is not None:
+            options.setdefault("max_age", int(self.max_age))
+        response.set_cookie(name, self.signer.sign(str(value)).decode("ascii"), **options)
+
+    def delete(self, response, name, **options):
+        """Delete cookie ``name``."""
+        response.delete_cookie(name, **options)

veil_kit/cors.py

@@ -0,0 +1,36 @@
+"""CORS with the arguments of Starlette's ``CORSMiddleware``.
+
+.. code-block:: python
+
+    from veil_kit.cors import CORSMiddleware
+
+    app.add_middleware(CORSMiddleware, allow_origins=["https://app.example.com"], allow_credentials=True)
+
+The headers are added by the server (Rust; the same implementation as the Rust ``veil-proxy-kit``): preflight requests
+are answered without calling Python, and the header values are built once at startup.
+"""
+
+# F-268: 中身は Rust（veil_kit::cors）。Python の層で要求ごとにヘッダを作らない。
+
+__all__ = ["CORSMiddleware"]
+
+
+class CORSMiddleware:
+    """Pass to ``app.add_middleware`` (or call ``app.cors(...)`` with the same keyword arguments).
+
+    ``allow_origins`` lists exact origins or ``https://*.example.com`` patterns (``["*"]`` allows any origin, not with
+    ``allow_credentials``); ``allow_methods`` defaults to ``["GET"]`` (``["*"]`` = all), ``allow_headers`` to none,
+    ``expose_headers`` to none and ``max_age`` to 600 seconds. ``prefix`` limits CORS to the routes below a path.
+    ``allow_origin_regex`` is not supported.
+    """
+
+    def __init__(self, app=None, **options):
+        self.options = options
+
+    @staticmethod
+    def _veil_install(app, **options):
+        """Called by ``app.add_middleware``."""
+        if options.get("allow_origin_regex"):
+            raise ValueError("allow_origin_regex is not supported; list the origins (\"https://*.example.com\" works)")
+        options.pop("allow_origin_regex", None)
+        app.cors(**options)