feat(auth): add requires_{auth,guest} decorators

These new decorators are meant to be used without any arguments
and provide aliases to auth_required:
- `auth_required(True) -> requires_auth`
- `auth_required(False) -> requires_guest`

These decorators should be used without arguments, e.g.:

    @router.get("/")
    @requires_guest
    async def my_route(request: Request):
        return HTMLResponse()

Signed-off-by: Kevin Morris <kevr@0cost.org>

aurweb/auth/__init__.py

@@ -2,6 +2,7 @@ import functools
 
 from datetime import datetime
 from http import HTTPStatus
+from typing import Callable
 
 import fastapi
 
@@ -129,10 +130,15 @@ class BasicAuthBackend(AuthenticationBackend):
         return (AuthCredentials(["authenticated"]), user)
 
 
-def auth_required(auth_goal: bool = True):
-    """ Enforce a user's authentication status, bringing them to the login page
+def _auth_required(auth_goal: bool = True):
+    """
+    Enforce a user's authentication status, bringing them to the login page
     or homepage if their authentication status does not match the goal.
 
+    NOTE: This function should not need to be used in downstream code.
+    See `requires_auth` and `requires_guest` for decorators meant to be
+    used on routes (they're a bit more implicitly understandable).
+
     :param auth_goal: Whether authentication is required or entirely disallowed
                       for a user to perform this request.
     :return: Return the FastAPI function this decorator wraps.
@@ -167,6 +173,24 @@ def auth_required(auth_goal: bool = True):
     return decorator
 
 
+def requires_auth(func: Callable) -> Callable:
+    """ Require an authenticated session for a particular route. """
+
+    @functools.wraps(func)
+    async def wrapper(*args, **kwargs):
+        return await _auth_required(True)(func)(*args, **kwargs)
+    return wrapper
+
+
+def requires_guest(func: Callable) -> Callable:
+    """ Require a guest (unauthenticated) session for a particular route. """
+
+    @functools.wraps(func)
+    async def wrapper(*args, **kwargs):
+        return await _auth_required(False)(func)(*args, **kwargs)
+    return wrapper
+
+
 def account_type_required(one_of: set):
     """ A decorator that can be used on FastAPI routes to dictate
     that a user belongs to one of the types defined in one_of.