review:review-all is the explicit tag-scoping bypass, not read:read-all

Review feedback on #712 (peterrrock2): the *-all read/update/delete
scopes govern access across CMS authorship boundaries; letting
read:read-all also widen moderation reach conflated two axes. New
TokenScope.review_all_content is the only scope that lifts the
review_tags restriction, and read:read-all no longer does (covered by a
regression test).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: nofurtherinformation

backend/app/comments/main.py

@@ -569,15 +569,17 @@ def allowed_review_tags(auth_result: dict) -> list[str] | None:
     tags via ReviewTagAssignment rows, minted into the JWT as a `review_tags`
     claim (sorted list of tag slugs). Semantics:
 
-    - `read:read-all` in the token scopes → None (unrestricted): that scope
-      means unrestricted read everywhere, and the CMS strips it from
-      tag-scoped reviewers so it can act as the admin/superuser escape hatch.
+    - `review:review-all` in the token scopes → None (unrestricted): the
+      explicit tag-scoping bypass. The CMS never grants it to tag-scoped
+      reviewers, so it acts as the admin/superuser escape hatch. (read:read-all
+      deliberately does NOT bypass: the *-all read/update/delete scopes govern
+      CMS authorship boundaries, a different axis from moderation reach.)
     - `review_tags` claim absent → None (unrestricted): users with no
       assignments are unrestricted (back-compat for internal reviewers).
     - otherwise → the claim's list; an empty list allows nothing.
     """
     token_scopes = (auth_result.get("scope") or "").split()
-    if TokenScope.read_all_content in token_scopes:
+    if TokenScope.review_all_content in token_scopes:
         return None
     review_tags = auth_result.get("review_tags")
     if review_tags is None:

backend/app/core/security.py

@@ -29,6 +29,11 @@ class TokenScope:
     delete_all_content = "delete:delete-all"
 
     review_content = "create:content_review"
+    # Explicit bypass of per-reviewer tag scoping (the `review_tags` claim).
+    # Deliberately separate from read:read-all: the *-all read/update/delete
+    # scopes govern access across CMS authorship boundaries, while this one
+    # widens moderation reach.
+    review_all_content = "review:review-all"
 
 
 class UnauthorizedException(HTTPException):

backend/tests/test_auth_contract.py

@@ -157,8 +157,8 @@ def test_multiple_required_scopes(verifier, keypair, jwks):
 
 
 def test_review_tags_claim_round_trips(verifier, keypair, jwks):
-    """Tag-scoped reviewer token: the CMS strips read:read-all and mints a
-    sorted review_tags claim; the verifier must hand the claim through
+    """Tag-scoped reviewer token: the CMS withholds review:review-all and
+    mints a sorted review_tags claim; the verifier must hand the claim through
     unchanged for allowed_review_tags (app/comments/main.py) to enforce."""
     private_pem, _ = keypair
     kid = jwks["keys"][0]["kid"]
@@ -172,7 +172,7 @@ def test_review_tags_claim_round_trips(verifier, keypair, jwks):
     payload = run_verify(verifier, token, ["create:content_review"])
 
     assert payload["review_tags"] == ["environment", "schools"]
-    assert "read:read-all" not in payload["scope"].split()
+    assert "review:review-all" not in payload["scope"].split()
 
 
 def test_review_tags_claim_absent_by_default(verifier, keypair, jwks):

backend/tests/test_comments.py

@@ -1491,7 +1491,7 @@ class TestReviewTagScoping:
     """Per-user review scoping on the admin moderation endpoints.
 
     The CMS mints a `review_tags` claim for reviewers with
-    ReviewTagAssignments (and strips `read:read-all` from their scopes);
+    ReviewTagAssignments (and never grants them `review:review-all`);
     allowed_review_tags + apply_allowed_tags_filter in app/comments/main.py
     enforce it. The conftest client fixture overrides auth.verify with a
     payload dict, so each test injects the claim/scope combination it needs.
@@ -1560,7 +1560,9 @@ def test_unrestricted_without_claim_sees_all(self, client, tagged_comments):
         assert response.status_code == 200
         assert len(response.json()) == 3
 
-    def test_read_all_scope_overrides_claim(self, client, tagged_comments):
+    def test_read_all_scope_does_not_bypass_tag_scoping(self, client, tagged_comments):
+        # read:read-all governs authorship-boundary reads, not moderation
+        # reach — it must NOT widen a tag-scoped reviewer.
         self._set_auth(
             {
                 "sub": "42",
@@ -1570,6 +1572,18 @@ def test_read_all_scope_overrides_claim(self, client, tagged_comments):
         )
         response = client.get("/api/comments/admin/list")
         assert response.status_code == 200
+        assert [c["title"] for c in response.json()] == ["Environment Comment"]
+
+    def test_review_all_scope_lists_everything(self, client, tagged_comments):
+        self._set_auth(
+            {
+                "sub": "42",
+                "scope": "create:content_review review:review-all",
+                "review_tags": ["environment"],
+            }
+        )
+        response = client.get("/api/comments/admin/list")
+        assert response.status_code == 200
         assert len(response.json()) == 3
 
     def test_review_comment_in_scope_succeeds(self, client, tagged_comments):