py2http 0.1.68__tar.gz → 0.1.70__tar.gz

{py2http-0.1.68 → py2http-0.1.70}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: py2http
-Version: 0.1.68
+Version: 0.1.70
 Summary: Declarative HTTP service entry point.
 Home-page: https://github.com/i2mint/py2http
 License: MIT

py2http-0.1.70/py2http/auth.py

@@ -0,0 +1,174 @@
+"""Framework-independent credential checks, shared by the aiohttp middleware
+(``py2http.middleware``) and the Bottle plugins (``py2http.bottle_plugins``), so that
+both refuse the same tokens and keys for the same reasons.
+
+>>> bearer_token('Bearer abc'), bearer_token('bearer abc'), bearer_token('Basic abc')
+('abc', 'abc', '')
+>>> key_matches('k-123', 'k-123'), key_matches('k-12', 'k-123'), key_matches(None, 'k')
+(True, False, False)
+"""
+
+import hmac
+import logging
+from collections.abc import Iterable, Mapping
+from typing import Optional
+
+logger = logging.getLogger("py2http")
+
+DFLT_JWT_ALGORITHMS = ("HS256",)
+# ``jwt.decode`` arguments the verification setup owns, so ``decode_kwargs`` can't
+_RESERVED_DECODE_KWARGS = frozenset({"jwt", "key", "algorithms", "options"})
+_BEARER_PREFIX = "bearer "
+
+
+class CredentialsRejected(Exception):
+    """A request's credentials were refused. The message is safe to show the client:
+    it never contains the token, nor anything about the server's key."""
+
+
+def _algorithm_family(algorithm: str) -> str:
+    """The key family an algorithm verifies with: a shared secret for ``HS*``, a
+    public key otherwise.
+
+    >>> _algorithm_family('HS512'), _algorithm_family('RS256'), _algorithm_family('ES256')
+    ('hmac', 'public-key', 'public-key')
+    """
+    return "hmac" if algorithm.upper().startswith("HS") else "public-key"
+
+
+def _names(name: str, value: Iterable[str]) -> list:
+    if isinstance(value, (str, bytes)):
+        raise TypeError(f"{name} must be a list of names, e.g. [{value!r}]")
+    return list(value)
+
+
+def jwt_algorithms(
+    secret,
+    *,
+    verify: bool = True,
+    algorithms: Iterable[str] = DFLT_JWT_ALGORITHMS,
+    allow_mixed_algorithm_families: bool = False,
+) -> list:
+    """Validate a JWT verification setup, returning the algorithms as a list.
+
+    Raises at construction time, rather than accepting forgeries at request time, when:
+
+    - ``algorithms`` is empty, a bare string, or names an unknown or unsigned (``none``)
+      algorithm (PyJWT names are case-sensitive);
+    - ``verify`` is True and ``secret`` is empty (an empty HMAC secret lets anyone sign
+      tokens), or an HMAC algorithm is asked for with a non-``str``/``bytes`` secret;
+    - ``verify`` is True and HMAC and public-key algorithms are mixed with one
+      ``secret`` (the classic algorithm-confusion setup), unless
+      ``allow_mixed_algorithm_families`` is True.
+
+    >>> jwt_algorithms('s3cret')
+    ['HS256']
+    >>> jwt_algorithms('', algorithms=['HS256'])
+    Traceback (most recent call last):
+      ...
+    ValueError: secret must be a non-empty key when verify=True
+    """
+    import jwt
+
+    algorithms = _names("algorithms", algorithms)
+    if not algorithms:
+        raise ValueError("algorithms must name at least one JWT algorithm")
+    known = set(jwt.algorithms.get_default_algorithms()) - {"none"}
+    if unknown := [a for a in algorithms if a not in known]:
+        raise ValueError(
+            f"Unknown or unsigned JWT algorithm(s) {unknown}; names are "
+            f"case-sensitive, choose from {sorted(known)}"
+        )
+    if verify and not secret:
+        raise ValueError("secret must be a non-empty key when verify=True")
+    families = {_algorithm_family(a) for a in algorithms}
+    if verify and "hmac" in families and not isinstance(secret, (str, bytes)):
+        raise TypeError(f"an HMAC secret must be str or bytes, got {type(secret)}")
+    if verify and len(families) > 1 and not allow_mixed_algorithm_families:
+        raise ValueError(
+            f"algorithms={algorithms} mixes HMAC and public-key algorithms with one "
+            "secret, which allows algorithm-confusion forgeries; use one family, or "
+            "pass allow_mixed_algorithm_families=True if you really mean it"
+        )
+    return algorithms
+
+
+def jwt_decode_kwargs(decode_kwargs: Optional[Mapping] = None) -> dict:
+    """Validate extra ``jwt.decode`` arguments (``audience``, ``issuer``,
+    ``leeway``...), refusing those the verification setup owns.
+
+    >>> jwt_decode_kwargs({'audience': 'my-api'})
+    {'audience': 'my-api'}
+    >>> jwt_decode_kwargs({'options': {'verify_signature': False}})
+    Traceback (most recent call last):
+      ...
+    ValueError: decode_kwargs may not set ['options']; use verify= and algorithms=
+    """
+    decode_kwargs = dict(decode_kwargs or {})
+    if reserved := sorted(_RESERVED_DECODE_KWARGS & set(decode_kwargs)):
+        raise ValueError(
+            f"decode_kwargs may not set {reserved}; use verify= and algorithms="
+        )
+    return decode_kwargs
+
+
+def bearer_token(authorization_header) -> str:
+    """The token of an ``Authorization: Bearer <token>`` header, or ``''``."""
+    header = authorization_header or ""
+    if header[: len(_BEARER_PREFIX)].lower() != _BEARER_PREFIX:
+        return ""
+    return header[len(_BEARER_PREFIX) :].strip()
+
+
+def decode_jwt(
+    token: str,
+    secret,
+    *,
+    algorithms: list,
+    verify: bool = True,
+    decode_kwargs: Optional[Mapping] = None,
+) -> dict:
+    """The claims of ``token``, or ``CredentialsRejected`` with a client-safe reason.
+
+    With ``verify=False`` neither the signature nor the claims (``exp``...) are checked.
+    ``decode_kwargs`` (``audience``, ``issuer``, ``leeway``...) go to ``jwt.decode``.
+    """
+    import jwt
+
+    try:
+        return jwt.decode(
+            token,
+            secret,
+            options={"verify_signature": verify},
+            algorithms=algorithms,
+            **(decode_kwargs or {}),
+        )
+    except jwt.InvalidTokenError as error:  # its text describes the token
+        raise CredentialsRejected(f"Invalid authentication token: {error}") from error
+    except (jwt.PyJWTError, UnicodeError) as error:
+        # a key unfit for the token's alg (InvalidKeyError...) describes the server's
+        # key, so it is logged rather than sent; a non-UTF-8 header is just refused
+        if not isinstance(error, UnicodeError):
+            logger.warning("JWT rejected for a server-side reason: %r", error)
+        raise CredentialsRejected(
+            "Invalid authentication token: not acceptable"
+        ) from error
+
+
+def required_key(key, *, name: str = "api_key"):
+    """``key``, refused when empty: an empty key would let a request with no
+    ``Authorization`` header through."""
+    if not key or not isinstance(key, (str, bytes)):
+        raise ValueError(f"{name} must be a non-empty str or bytes")
+    return key
+
+
+def key_matches(given, expected) -> bool:
+    """Whether the ``given`` credential equals ``expected``, in constant time."""
+    if not given or not expected:
+        return False
+
+    def _bytes(x):  # aiohttp keeps non-UTF-8 header bytes as surrogate escapes
+        return x.encode(errors="surrogateescape") if isinstance(x, str) else x
+
+    return hmac.compare_digest(_bytes(given), _bytes(expected))

py2http-0.1.70/py2http/bottle_plugins.py

@@ -0,0 +1,154 @@
+"""Plugins for adding middleware functionality to Bottle apps."""
+
+import json
+from functools import wraps
+from typing import Iterable
+from warnings import warn
+
+from bottle import request, response
+
+from py2http.auth import (
+    DFLT_JWT_ALGORITHMS,
+    CredentialsRejected,
+    bearer_token,
+    decode_jwt,
+    jwt_algorithms,
+    jwt_decode_kwargs,
+    key_matches,
+    required_key,
+)
+from py2http.constants import API_KEY_CHALLENGE, BEARER_CHALLENGE, JSON_CONTENT_TYPE
+
+OPTIONS = "OPTIONS"
+
+
+def _authorization_header() -> str:
+    """The request's ``Authorization`` header; ``''`` if it is not valid UTF-8 (Bottle
+    raises when decoding it), which every check then refuses."""
+    try:
+        return request.headers.get("Authorization", "")
+    except UnicodeError:
+        return ""
+
+
+def _unauthorized(message, challenge=BEARER_CHALLENGE):
+    response.status = 401
+    response.set_header("WWW-Authenticate", challenge)
+    response.content_type = JSON_CONTENT_TYPE
+    return json.dumps({"error": message})
+
+
+class JWTPlugin:
+    """A plugin for validating JWTs and extracting their payloads.
+
+    After optionally validating a JWT found in the request header, will assign a dict with the JWT claims
+    to request.token.
+    """
+
+    def __init__(
+        self,
+        secret: str = "",
+        verify: bool = True,
+        mapper: dict = None,
+        ignore_methods: Iterable[str] = None,
+        algorithms: Iterable[str] = None,
+        *,
+        allow_mixed_algorithm_families: bool = False,
+        decode_kwargs: dict = None,
+    ):
+        """Creates a new JWTPlugin instance.
+
+        :param secret: The JWT public key (RS256) or shared secret (HS256) used to
+            validate tokens. Required (non-empty) when ``verify`` is True.
+        :param verify: (Optional) If True, will verify JWT signatures against the provided secret,
+        and reject unverified requests.
+        :param mapper: (Optional) A dict that specifies how to map JWT claim value names in the output.
+        :param ignore_methods: (Optional) A list of method names for the plugin to ignore.
+        :param algorithms: (Optional) The algorithms a token may be signed with
+            (default ``("HS256",)``); validated as ``py2http.auth.jwt_algorithms``
+            describes, as is ``allow_mixed_algorithm_families``.
+        :param decode_kwargs: (Optional) Extra ``jwt.decode`` arguments, such as
+            ``audience``, ``issuer`` or ``leeway``.
+        """
+        self._secret = secret
+        self._verify = verify
+        self._mapper = mapper if mapper else {}
+        self._ignore_methods = ignore_methods if ignore_methods else []
+        self._algorithms = jwt_algorithms(
+            secret,
+            verify=verify,
+            algorithms=algorithms or DFLT_JWT_ALGORITHMS,
+            allow_mixed_algorithm_families=allow_mixed_algorithm_families,
+        )
+        self._decode_kwargs = jwt_decode_kwargs(decode_kwargs)
+
+    def _claims(self):
+        """The (renamed) claims of the request's token; raises ``CredentialsRejected``."""
+        decoded = decode_jwt(
+            bearer_token(_authorization_header()),
+            self._secret,
+            algorithms=self._algorithms,
+            verify=self._verify,
+            decode_kwargs=self._decode_kwargs,
+        )
+        for k, v in self._mapper.items():
+            if k in decoded:
+                decoded[v] = decoded.pop(k)
+        return decoded
+
+    def __call__(self, handler):
+        if getattr(handler, "method_name", None) in self._ignore_methods:
+            return handler
+
+        @wraps(handler)
+        def wrapped_handler(*args, **kwargs):
+            if request.method == OPTIONS:
+                return handler(*args, **kwargs)
+            try:
+                request.token = self._claims()
+            except CredentialsRejected as rejection:
+                if self._verify:
+                    return _unauthorized(str(rejection))
+                warn(f"Invalid JWT: {rejection.__cause__}")
+            return handler(*args, **kwargs)
+
+        return wrapped_handler
+
+
+class ApiKeyAuthPlugin:
+    """A plugin letting through only requests whose ``Authorization`` header is
+    exactly ``api_key`` (compared in constant time; an empty key is refused)."""
+
+    def __init__(self, api_key: str):
+        self._api_key = required_key(api_key)
+
+    def __call__(self, handler):
+        @wraps(handler)
+        def wrapped_handler(*args, **kwargs):
+            if key_matches(_authorization_header(), self._api_key):
+                return handler(*args, **kwargs)
+            return _unauthorized("invalid API key", API_KEY_CHALLENGE)
+
+        return wrapped_handler
+
+
+# from https://stackoverflow.com/questions/17262170/bottle-py-enabling-cors-for-jquery-ajax-requests
+# TODO: accept lists of headers and methods as init args
+class CorsPlugin:
+    def __init__(self, origins: str = "*"):
+        self._origins = origins
+
+    def __call__(self, handler):
+        @wraps(handler)
+        def wrapped_handler(*args, **kwargs):
+            response.headers["Access-Control-Allow-Origin"] = self._origins
+            response.headers["Access-Control-Allow-Methods"] = (
+                "GET, POST, PUT, DELETE, OPTIONS"
+            )
+            response.headers["Access-Control-Allow-Headers"] = (
+                "Origin, Accept, Content-Type, X-Requested-With, Authorization, X-api-key"
+            )
+            if request.method != OPTIONS:
+                return handler(*args, **kwargs)
+
+        return wrapped_handler

{py2http-0.1.68 → py2http-0.1.70}/py2http/constants.py

@@ -5,3 +5,11 @@ BINARY_CONTENT_TYPE = "application/octet-stream"
 FORM_CONTENT_TYPE = "multipart/form-data"
 RAW_CONTENT_TYPE = "text/plain"
 HTML_CONTENT_TYPE = "text/html"
+
+# ``WWW-Authenticate`` challenges sent with every 401 (RFC 7235 requires one): a JWT is
+# sent as ``Authorization: Bearer <token>``; an API key as the bare header value.
+BEARER_CHALLENGE = "Bearer"
+API_KEY_CHALLENGE = "ApiKey"
+#: Environment variable naming the challenge for a 401 a dispatched function raised
+#: (``AuthorizationError``); the deployment's auth decides it. Default: Bearer.
+WWW_AUTHENTICATE_ENV_VAR = "PY2HTTP_WWW_AUTHENTICATE"

{py2http-0.1.68 → py2http-0.1.70}/py2http/default_configs.py

@@ -15,6 +15,7 @@ up an HTTP service in Python using the py2http library."""
 from aiohttp import web
 from bottle import response
 import json
+import logging
 import os
 
 from i2.errors import (
@@ -28,7 +29,13 @@ from i2.errors import (
 
 from py2http.decorators import handle_json_req, send_json_resp, JsonRespEncoder
 from py2http.config import AIOHTTP, BOTTLE, FLASK
-from py2http.constants import JSON_CONTENT_TYPE
+from py2http.constants import (
+    BEARER_CHALLENGE,
+    JSON_CONTENT_TYPE,
+    WWW_AUTHENTICATE_ENV_VAR,
+)
+
+logger = logging.getLogger(__name__)
 
 DFLT_CONTENT_TYPE = JSON_CONTENT_TYPE
 
@@ -52,14 +59,41 @@ def bottle_output_mapper(output, **inputs):
     return json.dumps(output, cls=JsonRespEncoder)
 
 
-def _raise_http_client_error(error, message, reason=None):
+def _raise_http_client_error(error, message, reason=None, headers=None):
     raise error(
         text=json.dumps({"error": message}),
         content_type=JSON_CONTENT_TYPE,
         reason=reason,
+        headers=headers,
     )
 
 
+def www_authenticate_challenge() -> str:
+    """The ``WWW-Authenticate`` value of a 401 a dispatched function raised: the
+    ``PY2HTTP_WWW_AUTHENTICATE`` environment variable, else ``Bearer`` (also when the
+    variable holds a line break, which would make every 401 fail to send).
+
+    >>> os.environ.pop(WWW_AUTHENTICATE_ENV_VAR, None) and None
+    >>> www_authenticate_challenge()
+    'Bearer'
+    """
+    challenge = os.getenv(WWW_AUTHENTICATE_ENV_VAR)
+    if not challenge:
+        return BEARER_CHALLENGE
+    if any(c in challenge for c in "\r\n\0"):
+        logger.warning(
+            "%s holds a control character; sending %r instead",
+            WWW_AUTHENTICATE_ENV_VAR,
+            BEARER_CHALLENGE,
+        )
+        return BEARER_CHALLENGE
+    return challenge
+
+
+def _status_headers(status: int) -> dict:
+    return {"WWW-Authenticate": www_authenticate_challenge()} if status == 401 else {}
+
+
 # HTTP status of each client error, most specific class first. ``ForbiddenError`` and
 # ``OverwritesNotAllowed`` mean the client may not do this (403); any other
 # ``AuthorizationError`` means the request did not say who it is (401).
@@ -96,13 +130,20 @@ def aiohttp_error_handler(error: Exception):
     if status == 500:
         _raise_http_client_error(web.HTTPInternalServerError, "Internal server error")
     reason = type(error).__name__ if status == 400 else None
-    _raise_http_client_error(_AIOHTTP_ERRORS[status], str(error), reason=reason)
+    _raise_http_client_error(
+        _AIOHTTP_ERRORS[status],
+        str(error),
+        reason=reason,
+        headers=_status_headers(status) or None,
+    )
 
 
 def bottle_error_handler(error: Exception):
     message = str(error)
     status = error_status(error)
     response.status = f"400 {type(error).__name__}" if status == 400 else status
+    for header, value in _status_headers(status).items():
+        response.set_header(header, value)
     if status == 500 and os.getenv("OPAQUE_ERRORS", None):
         message = "Internal server error"
     return {"error": message}

py2http-0.1.70/py2http/middleware.py

@@ -0,0 +1,126 @@
+"""aiohttp middleware that guards every route of an app: ``mk_jwt_middleware``
+(a verified ``Authorization: Bearer`` JWT) and ``mk_superadmin_middleware`` (one
+shared key). The checks themselves live in ``py2http.auth``, shared with the Bottle
+plugins of ``py2http.bottle_plugins``."""
+
+import json
+from collections.abc import Iterable
+from warnings import warn
+
+from py2http.auth import (
+    DFLT_JWT_ALGORITHMS,
+    CredentialsRejected,
+    _algorithm_family,  # noqa: F401  (was defined here)
+    _names,
+    bearer_token,
+    decode_jwt,
+    jwt_algorithms,
+    jwt_decode_kwargs,
+    key_matches,
+    required_key,
+)
+from py2http.constants import API_KEY_CHALLENGE, BEARER_CHALLENGE, JSON_CONTENT_TYPE
+
+DFLT_PUBLIC_ROUTES = ("ping", "openapi")
+
+
+def _unauthorized(message, challenge=BEARER_CHALLENGE):
+    from aiohttp import web
+
+    return web.HTTPUnauthorized(
+        text=json.dumps({"error": message}),
+        content_type=JSON_CONTENT_TYPE,
+        headers={"WWW-Authenticate": challenge},
+    )
+
+
+def mk_jwt_middleware(
+    secret,
+    verify=True,
+    *,
+    algorithms: Iterable[str] = DFLT_JWT_ALGORITHMS,
+    public_routes: Iterable[str] = DFLT_PUBLIC_ROUTES,
+    allow_mixed_algorithm_families: bool = False,
+    decode_kwargs: dict = None,
+):
+    """Make an aiohttp middleware that requires a valid ``Authorization: Bearer``
+    JWT on every request, and puts the decoded claims on ``request.token``.
+
+    Args:
+        secret: The key tokens are verified with (an HMAC secret for ``HS*``
+            algorithms, a public key for ``RS*``/``ES*``/...).
+        verify: If False, signatures and claims (``exp``, ...) are NOT checked:
+            whatever a token says ends up on ``request.token``, and an
+            undecodable token only triggers a warning. For development only.
+            (Before, PyJWT 2 ignored the legacy option this passed, so
+            signatures were still checked even with ``verify=False``.)
+        algorithms: The algorithms a token may be signed with (PyJWT names,
+            case-sensitive; ``"none"`` is refused). Defaults to ``("HS256",)``,
+            as ``py2http.bottle_plugins.JWTPlugin`` does.
+        public_routes: Names of aiohttp routes (``name=`` in ``add_route``) that
+            need no token. Matched on the route name, not the handler's
+            ``__name__``, so a handler that happens to be called ``ping`` is not
+            public by accident. Route names are matched in sub-applications
+            too, so a sub-app route named ``ping`` is public as well.
+        allow_mixed_algorithm_families: Accepting an HMAC algorithm and a
+            public-key algorithm with one ``secret`` is the classic
+            algorithm-confusion setup (a token "signed" with HS256 using the
+            public key as the HMAC secret), so it raises ``ValueError`` unless
+            this is True. The middleware used to accept ``["HS256", "RS256"]``;
+            pass that list with this flag to restore it.
+        decode_kwargs: Extra ``jwt.decode`` arguments, such as ``audience``,
+            ``issuer`` or ``leeway`` (without them a token carrying an ``aud``
+            claim is always refused).
+    """
+    from aiohttp import web
+
+    algorithms = jwt_algorithms(
+        secret,
+        verify=verify,
+        algorithms=algorithms,
+        allow_mixed_algorithm_families=allow_mixed_algorithm_families,
+    )
+    decode_kwargs = jwt_decode_kwargs(decode_kwargs)
+    public_routes = frozenset(
+        name for name in _names("public_routes", public_routes) if name is not None
+    )
+
+    @web.middleware
+    async def middleware(req, handler):
+        route = req.match_info.route
+        if getattr(route, "name", None) in public_routes:
+            return await handler(req)
+        token = bearer_token(req.headers.get("Authorization"))
+        try:
+            req.token = decode_jwt(
+                token,
+                secret,
+                algorithms=algorithms,
+                verify=verify,
+                decode_kwargs=decode_kwargs,
+            )
+        except CredentialsRejected as rejection:
+            if verify:
+                raise _unauthorized(str(rejection)) from None
+            warn(f"Invalid JWT: {rejection.__cause__}")
+        return await handler(req)
+
+    return middleware
+
+
+def mk_superadmin_middleware(secret):
+    """Make an aiohttp middleware that only lets through requests whose
+    ``Authorization`` header is exactly ``secret`` (compared in constant time).
+    An empty ``secret`` is refused, since it would let header-less requests through.
+    """
+    from aiohttp import web
+
+    secret = required_key(secret, name="secret")
+
+    @web.middleware
+    async def middleware(req, handler):
+        if key_matches(req.headers.get("Authorization"), secret):
+            return await handler(req)
+        raise _unauthorized("invalid API key", API_KEY_CHALLENGE)
+
+    return middleware