feat(auth): add request authentication helper

Author: 1mpossible-code

server/auth.py

@@ -49,3 +49,19 @@ def extract_bearer_token(auth_header: str | None) -> str | None:
         return None
     token = auth_header.removeprefix("Bearer ").strip()
     return token or None
+
+
+def authenticate_request(
+    auth_header: str | None,
+    required_role: str | None = None,
+) -> dict[str, Any]:
+    """Validate a bearer token header and optionally enforce a role."""
+    token = extract_bearer_token(auth_header)
+    if token is None:
+        raise PermissionError("Missing or invalid bearer token")
+
+    payload = decode_access_token(token)
+    if required_role and payload.get("role") != required_role:
+        raise PermissionError(f"Role '{required_role}' is required")
+
+    return payload

server/tests/test_auth.py

@@ -3,6 +3,7 @@
 from server.auth import (
     ROLE_ADMIN,
     ROLE_USER,
+    authenticate_request,
     create_access_token,
     decode_access_token,
     extract_bearer_token,
@@ -50,3 +51,30 @@ def test_user_role_token_supported():
     token = create_access_token("bob", ROLE_USER, expires_hours=1)
     payload = decode_access_token(token)
     assert payload["role"] == ROLE_USER
+
+
+def test_authenticate_request_accepts_valid_bearer_token():
+    token = create_access_token("alice", ROLE_ADMIN, expires_hours=1)
+
+    payload = authenticate_request(f"Bearer {token}")
+
+    assert payload["sub"] == "alice"
+    assert payload["role"] == ROLE_ADMIN
+
+
+def test_authenticate_request_rejects_missing_bearer_token():
+    try:
+        authenticate_request(None)
+        assert False, "Expected PermissionError"
+    except PermissionError as exc:
+        assert "Missing or invalid bearer token" in str(exc)
+
+
+def test_authenticate_request_enforces_required_role():
+    token = create_access_token("bob", ROLE_USER, expires_hours=1)
+
+    try:
+        authenticate_request(f"Bearer {token}", required_role=ROLE_ADMIN)
+        assert False, "Expected PermissionError"
+    except PermissionError as exc:
+        assert "Role 'admin' is required" in str(exc)