guest role; guide section ticking

shopdb/utils/authz.py

@@ -10,13 +10,34 @@ or not a separate @jwt_required is also present. The admin role bypasses every
 permission check (see User.haspermission), so an admin never needs individual
 permissions granted.
 
+THE GUEST ROLE
+
+Somebody with no token is not nobody: they hold the `guest` role. If that role
+has been granted the permission a route asks for, the request proceeds; if it
+has not - and by default it holds nothing at all - the answer is 401, exactly
+as before.
+
+This replaced a growing pile of per-feature booleans (`securesend_allow_guests`,
+one per kiosk, one nearly written for guides). Every one of them answered the
+same question in its own vocabulary, in its own settings page, checked by its
+own hand-written branch inside a route. What a signed-out visitor may see is a
+permissions question, and this app already administers permissions per role.
+
+So: a site opens a door by ticking a box in the role grid, and a plugin needs
+no code at all to participate. A feature FLAG is still a flag - whether a kiosk
+screen exists at this site is not the same question as who may read it.
+
 Usage:
 
     @assets_bp.route('/<int:asset_id>', methods=['DELETE'])
-    @jwt_required()
     @require_permission('assets.delete')
     def delete_asset(asset_id):
         ...
+
+A separate @jwt_required() above these is redundant - they verify the request
+themselves - and it is actively wrong now: it refuses a request with no token
+before the guest role can be consulted, so a permission granted to guests would
+appear to do nothing.
 """
 
 from functools import wraps
@@ -26,6 +47,45 @@ from flask_jwt_extended import verify_jwt_in_request, current_user, get_jwt
 from shopdb.utils.responses import error_response, ErrorCodes
 
 
+def currentuser():
+    """The signed-in user, or None.
+
+    `current_user` is a LocalProxy: the proxy object exists whether or not
+    anybody is behind it, so `current_user is None` is False even for a request
+    with no token. Under a required JWT that never showed, because the request
+    was refused before reaching here. With optional verification it shows
+    immediately, as "'NoneType' object has no attribute 'haspermission'".
+    """
+    try:
+        return current_user._get_current_object()
+    except Exception:
+        return None
+
+
+def guestholds(permission_name: str) -> bool:
+    """Whether the guest role has been granted this permission.
+
+    Read every time, not cached. Revoking guest access is what somebody does the
+    moment they realise what they opened up, and it has to bite on the very next
+    request - a cache keyed to the app context outlives a request whenever one
+    is pushed around several (which is exactly how the test client behaves, and
+    how the revoke test caught it). One small indexed query on the rare path is
+    worth more than that risk.
+
+    A site with no guest role yet - an older database, seeded before this
+    existed - answers no, which is the behaviour it already had.
+    """
+    from shopdb.core.models import Role
+    try:
+        role = Role.guest()
+    except Exception:
+        # A database that cannot answer must not turn into an open door.
+        return False
+    if role is None:
+        return False
+    return any(p.name == permission_name for p in role.permissions)
+
+
 def require_permission(permission_name: str):
     """Gate a route behind a single permission. Admin role bypasses.
 
@@ -36,10 +96,15 @@ def require_permission(permission_name: str):
     def decorator(view_func):
         @wraps(view_func)
         def wrapper(*args, **kwargs):
-            # verify jwt first so current_user is loaded (idempotent if the
-            # route also has @jwt_required)
-            verify_jwt_in_request()
-            if current_user is None:
+            # Optional, so a request with no token reaches the guest check
+            # below rather than being refused by the JWT layer before this
+            # decorator can have an opinion. A request that DOES carry a token
+            # is still verified, and a bad one still fails here.
+            verify_jwt_in_request(optional=True)
+            user = currentuser()
+            if user is None:
+                if guestholds(permission_name):
+                    return view_func(*args, **kwargs)
                 return error_response(
                     ErrorCodes.UNAUTHORIZED,
                     'Authentication required',
@@ -53,7 +118,7 @@ def require_permission(permission_name: str):
                 # everything), so the scope list is the real limiter - the
                 # admin bypass is suspended.
                 allowed = (permission_name in patscopes
-                           and current_user.haspermission(permission_name))
+                           and user.haspermission(permission_name))
                 if not allowed:
                     return error_response(
                         ErrorCodes.FORBIDDEN,
@@ -61,7 +126,54 @@ def require_permission(permission_name: str):
                         http_code=403
                     )
                 return view_func(*args, **kwargs)
-            if not current_user.haspermission(permission_name):
+            if not user.haspermission(permission_name):
+                return error_response(
+                    ErrorCodes.FORBIDDEN,
+                    'You do not have permission to perform this action',
+                    http_code=403
+                )
+            return view_func(*args, **kwargs)
+        return wrapper
+    return decorator
+
+
+def require_any_permission(*permission_names):
+    """Gate a route behind ANY ONE of several permissions. Admin bypasses.
+
+    For a read that two different rights should reach. GE-Enforce and Slides
+    are the cases: a GET was gated on the MANAGE permission, because managing
+    was the only thing anybody did there. Splitting a read permission out would
+    have locked out every existing manager, so a read now accepts either, and
+    the read permission is the one a site can hand to a guest.
+
+    A scoped PAT must carry one of the names, and its owner must hold that same
+    one - the intersection rule of require_permission, applied per name.
+    """
+    def decorator(view_func):
+        @wraps(view_func)
+        def wrapper(*args, **kwargs):
+            verify_jwt_in_request(optional=True)
+            user = currentuser()
+            if user is None:
+                if any(guestholds(name) for name in permission_names):
+                    return view_func(*args, **kwargs)
+                return error_response(
+                    ErrorCodes.UNAUTHORIZED,
+                    'Authentication required',
+                    http_code=401
+                )
+            patscopes = get_jwt().get('patscopes')
+            if patscopes is not None:
+                allowed = any(name in patscopes and user.haspermission(name)
+                              for name in permission_names)
+                if not allowed:
+                    return error_response(
+                        ErrorCodes.FORBIDDEN,
+                        'This API token is not scoped for this action',
+                        http_code=403
+                    )
+                return view_func(*args, **kwargs)
+            if not any(user.haspermission(name) for name in permission_names):
                 return error_response(
                     ErrorCodes.FORBIDDEN,
                     'You do not have permission to perform this action',
@@ -83,7 +195,8 @@ def require_role(rolename: str):
         @wraps(view_func)
         def wrapper(*args, **kwargs):
             verify_jwt_in_request()
-            if current_user is None:
+            user = currentuser()
+            if user is None:
                 return error_response(
                     ErrorCodes.UNAUTHORIZED,
                     'Authentication required',
@@ -95,7 +208,7 @@ def require_role(rolename: str):
                     'Scoped API tokens cannot access role-gated endpoints',
                     http_code=403
                 )
-            if not current_user.hasrole(rolename):
+            if not user.hasrole(rolename):
                 return error_response(
                     ErrorCodes.FORBIDDEN,
                     f'{rolename.capitalize()} access required',