tina4-python 3.13.105__tar.gz → 3.13.107__tar.gz

{tina4_python-3.13.105 → tina4_python-3.13.107}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tina4-python
-Version: 3.13.105
+Version: 3.13.107
 Summary: Tina4 Python v3 — Zero-dependency, lightweight web framework
 Author-email: Andre van Zuydam <andrevanzuydam@gmail.com>
 License: MIT

{tina4_python-3.13.105 → tina4_python-3.13.107}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tina4-python"
-version = "3.13.105"
+version = "3.13.107"
 description = "Tina4 Python v3 — Zero-dependency, lightweight web framework"
 authors = [
     {name = "Andre van Zuydam", email = "andrevanzuydam@gmail.com"}

{tina4_python-3.13.105 → tina4_python-3.13.107}/tina4_python/__init__.py

@@ -51,7 +51,7 @@ def _resolve_version() -> str:
     #
     # test_version_constant.py now asserts this literal equals the pyproject
     # version, so the release bump cannot leave it behind again.
-    return "3.13.105"
+    return "3.13.107"
 
 
 __version__ = _resolve_version()
@@ -71,9 +71,14 @@ __version__ = _resolve_version()
 # ── CORE (always eager) — every app needs these to boot + serve ──
 from tina4_python.core.router import (  # noqa: E402, F401
     get, post, put, patch, delete, any_method,
-    noauth, secured, cached, middleware, template,
+    noauth, secured, role, can, cached, middleware, template,
     Router, RouteGroup,
 )
+# websocket is not in that tuple. The tina4_python.websocket *subpackage* is
+# itself callable (see tina4_python/websocket/__init__.py) so
+# `from tina4_python import websocket` reaches core.router.websocket without
+# turning `import tina4_python.websocket as ws` into a function. A re-export
+# here would do the latter.
 from tina4_python.core.constants import (  # noqa: E402, F401
     HTTP_OK, HTTP_CREATED, HTTP_ACCEPTED, HTTP_NO_CONTENT,
     HTTP_MOVED, HTTP_REDIRECT, HTTP_NOT_MODIFIED,

{tina4_python-3.13.105 → tina4_python-3.13.107}/tina4_python/core/router.py

@@ -50,6 +50,24 @@ class RouteRef:
         self._route["auth_required"] = False
         return self
 
+    def role(self, *names):
+        """Require the caller to hold ONE of the named roles (OR). Reads the
+        verified JWT ``roles`` claim. Implies auth (a guarded GET still needs a
+        token). Stack ``.role()``/``.can()`` for AND. Feature 138 / ADR-0058."""
+        if names:
+            self._route.setdefault("required_roles", []).append(tuple(names))
+            self._route["auth_required"] = True
+        return self
+
+    def can(self, *permissions):
+        """Require the caller to hold ONE of the named permissions (OR). Reads
+        the verified JWT ``permissions`` claim; granted-side wildcards (``posts.*``,
+        ``*``) satisfy a concrete requirement. Implies auth. Feature 138."""
+        if permissions:
+            self._route.setdefault("required_perms", []).append(tuple(permissions))
+            self._route["auth_required"] = True
+        return self
+
     def cache(self):
         """Mark this route as cacheable."""
         self._route["cached"] = True
@@ -371,6 +389,12 @@ class Router:
             auth_required = False
         elif hasattr(handler, "_secured"):
             auth_required = True
+        elif hasattr(handler, "_required_roles") or hasattr(handler, "_required_perms"):
+            # A role/permission guard (Feature 138) implies auth — a guarded GET
+            # still requires a token. This branch only fires in the unusual
+            # innermost-order case (guard BELOW @get); the documented order puts
+            # the guard ABOVE, where it flips auth_required via the RouteRef.
+            auth_required = True
         else:
             # GET, HEAD, OPTIONS, and ANY are public by default. HEAD and
             # OPTIONS are safe/idempotent introspection methods (RFC 9110
@@ -392,6 +416,11 @@ class Router:
             "module": getattr(handler, "__module__", ""),
             "middleware": effective_middleware,
             "auth_required": auth_required,
+            # RBAC guards (Feature 138): lists of OR-groups; AND across groups.
+            # Populated here for the innermost-order case, and appended to by the
+            # RouteRef.role()/.can() modifiers for the documented guard-above order.
+            "required_roles": list(getattr(handler, "_required_roles", []) or []),
+            "required_perms": list(getattr(handler, "_required_perms", []) or []),
             "cached": options.get("cached", False),
             "cache_max_age": options.get("cache_max_age", 60),
             "swagger_meta": swagger_meta or options.get("swagger_meta", {}),
@@ -862,6 +891,121 @@ def secured():
     return decorator
 
 
+# ── RBAC guards (Feature 138 / ADR-0058) ──────────────────────
+# Claim-first authorization on top of the JWT auth gate. @role reads the verified
+# `roles` claim, @can reads `permissions`. Multiple args are OR; stack guards for
+# AND. A guard implies @secured. Roles and permissions are independent claims;
+# the core never expands a role into permissions.
+
+def role(*names):
+    """Require the caller to hold ONE of the named roles (OR). Stack
+    ``@role``/``@can`` for AND. Reads the verified JWT ``roles`` claim (a legacy
+    singular ``role`` string is coerced). Implies ``@secured``."""
+    group = tuple(names)
+
+    def decorator(fn):
+        fn._required_roles = getattr(fn, "_required_roles", []) + [group]
+        if hasattr(fn, "_route_ref"):
+            route = fn._route_ref._route
+            route.setdefault("required_roles", []).append(group)
+            was_public = not route.get("auth_required", True)
+            route["auth_required"] = True
+            if was_public:
+                Log.debug(
+                    f"Route auth updated: {route['method']} {route['path']} "
+                    f"(auth=required via @role)"
+                )
+        return fn
+    return decorator
+
+
+def can(*permissions):
+    """Require the caller to hold ONE of the named permissions (OR). Stack
+    ``@role``/``@can`` for AND. Reads the verified JWT ``permissions`` claim;
+    granted-side wildcards (``posts.*``, ``*``) satisfy a concrete requirement.
+    Implies ``@secured``."""
+    group = tuple(permissions)
+
+    def decorator(fn):
+        fn._required_perms = getattr(fn, "_required_perms", []) + [group]
+        if hasattr(fn, "_route_ref"):
+            route = fn._route_ref._route
+            route.setdefault("required_perms", []).append(group)
+            was_public = not route.get("auth_required", True)
+            route["auth_required"] = True
+            if was_public:
+                Log.debug(
+                    f"Route auth updated: {route['method']} {route['path']} "
+                    f"(auth=required via @can)"
+                )
+        return fn
+    return decorator
+
+
+def _rbac_claim_list(subject, key, legacy=None):
+    """Read a claim as a list of strings from the VERIFIED payload. Coerces a
+    legacy singular string (``role`` -> ``["role"]``). Returns ``[]`` for a
+    missing/None subject or claim."""
+    if not isinstance(subject, dict):
+        return []
+    val = subject.get(key)
+    out = []
+    if isinstance(val, str) and val:
+        out = [val]
+    elif isinstance(val, (list, tuple)):
+        out = [str(x) for x in val if x is not None and str(x) != ""]
+    if not out and legacy:
+        lv = subject.get(legacy)
+        if isinstance(lv, str) and lv:
+            out = [lv]
+        elif isinstance(lv, (list, tuple)):
+            out = [str(x) for x in lv if x is not None and str(x) != ""]
+    return out
+
+
+def _rbac_perm_granted(granted, required):
+    """True if any GRANTED permission satisfies the concrete REQUIRED permission.
+    Wildcards live only on the granted side: ``*`` grants everything; ``posts.*``
+    grants ``posts.<anything...>`` on the dot boundary (never ``users.delete``)."""
+    for g in granted:
+        if g == "*" or g == required:
+            return True
+        if g.endswith(".*") and required.startswith(g[:-1]):
+            return True
+    return False
+
+
+def rbac_authorized(subject, required_roles, required_perms):
+    """Return True if the verified ``subject`` satisfies every guard group.
+
+    AND across groups, OR within a group. ``required_roles`` / ``required_perms``
+    are lists of OR-groups (each ``@role``/``@can`` adds one group). Roles read
+    the ``roles`` claim (legacy singular ``role`` coerced); permissions read
+    ``permissions`` with granted-side wildcards. A missing subject satisfies no
+    group. Feature 138 / ADR-0058."""
+    # NOTE: explicit loops, NOT any(...): this module shadows the builtin `any`
+    # (a route helper), so `any(...)` here would resolve to the wrong callable.
+    roles = _rbac_claim_list(subject, "roles", legacy="role")
+    for group in (required_roles or []):
+        matched = False
+        for r in group:
+            if r in roles:
+                matched = True
+                break
+        if not matched:
+            return False
+    perms = _rbac_claim_list(subject, "permissions")
+    for group in (required_perms or []):
+        matched = False
+        for req in group:
+            if _rbac_perm_granted(perms, req):
+                matched = True
+                break
+        if not matched:
+            return False
+    return True
+
+
 # ── Middleware Decorator ───────────────────────────────────────
 
 def middleware(*middleware_classes):

{tina4_python-3.13.105 → tina4_python-3.13.107}/tina4_python/core/server.py

@@ -1804,6 +1804,22 @@ def _check_auth(request: Request, response: Response, route: dict) -> bool:
             "status": 401,
         })
         return True
+    # ── RBAC guards (Feature 138): authorization AFTER authentication ──
+    # Auth passed (401 already ruled out above). If the route carries role/
+    # permission guards, the verified payload (request.user) must satisfy them,
+    # else 403 — authenticated but forbidden. An API-key auth leaves request.user
+    # unset, so it carries no roles and is correctly forbidden from a guarded route.
+    _req_roles = route.get("required_roles") or []
+    _req_perms = route.get("required_perms") or []
+    if _req_roles or _req_perms:
+        from tina4_python.core.router import rbac_authorized
+        if not rbac_authorized(getattr(request, "user", None), _req_roles, _req_perms):
+            response.status(403).json({
+                "error": "Forbidden",
+                "message": "You do not have permission to access this resource",
+                "status": 403,
+            })
+            return True
     return False
 
 

{tina4_python-3.13.105 → tina4_python-3.13.107}/tina4_python/websocket/__init__.py

@@ -22,6 +22,8 @@ import os
 import uuid
 import time
 from typing import Callable
+import sys as _sys
+from types import ModuleType as _ModuleType
 
 MAGIC_STRING = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
 
@@ -961,3 +963,34 @@ __all__ = [
     "OP_TEXT", "OP_BINARY", "OP_CLOSE", "OP_PING", "OP_PONG",
     "CLOSE_NORMAL", "CLOSE_GOING_AWAY", "CLOSE_PROTOCOL_ERROR", "CLOSE_TOO_LARGE",
 ]
+
+
+# ── `@websocket("/path")` on the package name ───────────────────────────────
+# `tina4_python.websocket` is two things at once: this RFC 6455 subpackage,
+# and — to every reader of the docs — the route decorator beside @get/@post.
+# Python binds a submodule onto its parent as soon as the submodule loads, so
+#
+#     from tina4_python import websocket
+#     @websocket("/ws")            # TypeError: 'module' object is not callable
+#
+# died at decorate time and auto-discovery dropped every route from that line
+# onward.
+#
+# A re-export in tina4_python/__init__.py AFTER core.server has already loaded
+# this subpackage is stable (importlib setattr happens on first load only).
+# That still fails the other public surface: `import tina4_python.websocket as
+# ws` would then return the function, so `ws.WebSocketServer` breaks. Making
+# this module callable keeps both: the package name decorates, and the
+# subpackage stays a module. Forward *args/**kwargs so this spelling cannot
+# drift from core.router.websocket. Guard sys.modules — a loader that execs
+# this file without registering it must not KeyError.
+class _CallableWebSocketModule(_ModuleType):
+    def __call__(self, *args, **kwargs):
+        from tina4_python.core.router import websocket as _websocket_route
+
+        return _websocket_route(*args, **kwargs)
+
+
+_self = _sys.modules.get(__name__)
+if _self is not None:
+    _self.__class__ = _CallableWebSocketModule