Tighten source privacy gates to READ-codename grants (parity with user_can)

Review follow-up that turned out to be a real parity bug, not a docstring
question: the privacy-gate builders matched ANY guardian row on the
source analysis/extract, while user_can recursion resolves READ via the
read codename — so an update_analysis-only grantee saw private rows in
lists while user_can(READ) denied them (the same filter/check violation
class this PR closes elsewhere). visible_analyses_for /
visible_extracts_for now filter permission__codename=read_analysis /
read_extract on both the user- and group-level tables; pinned by
test_update_only_source_grant_does_not_unlock_lists.

Also from the review round:
- _source_privacy_recursion_passes docstring documents the
  deleted-source posture (created_by_* FKs are on_delete=SET_NULL, so
  deletion turns rows into normal rows; the is-None branch is a
  fail-closed race guard, not a permanent lock)
- ExtractManager.user_can carries an equivalence note for its
  None/anonymous guard vs the visible_to_user surface
- get_corpus_annotations privacy exclusion now explains at the call
  site why it is intentionally unconditional (old anonymous guard was
  the leak)
- changelog fragment updated for the grant-shape tightening

Author: claude

changelog.d/perm-audit-2026-06.security.md

@@ -1,4 +1,4 @@
 - **Relationship privacy recursion implemented (closes the Phase-C deferral from issue #1655).** `RelationshipManager.user_can` and `RelationshipManager.visible_to_user` (`opencontractserver/shared/Managers.py`) now enforce `created_by_analysis` / `created_by_extract` source permissions exactly like annotations: non-creators need the requested permission on the source Analysis/Extract in addition to the doc+corpus MIN. Previously a user with doc+corpus grants could see and write analysis-/extract-private relationships through the manager surfaces. The recursion logic is shared with `AnnotationManager` via the new module-level `_source_privacy_recursion_passes`. Parity pinned by new fixtures/tests in `opencontractserver/tests/permissioning/test_authorization_invariants.py` (`RelationshipAuthorizationInvariantsTestCase` — the old `test_no_privacy_widening_via_created_by_analysis` sentinel that documented the deferral is replaced by real privacy invariants) and `opencontractserver/tests/permissioning/test_relationship_privacy_scoping.py`.
 - **Extracts locked down to never be anonymous-visible.** `ExtractService.get_visible_extracts` / `check_extract_permission` (`opencontractserver/extracts/services/extract_service.py`) previously exposed `is_public` extracts in public corpora to anonymous callers (drift copied from the analysis service, reachable through the un-gated `extracts` GraphQL resolver), contradicting the documented "Extract — never" anonymous contract. A new `ExtractManager` (`opencontractserver/extracts/models.py`) denies anonymous users on both `visible_to_user` and `user_can` so the rule holds at the manager layer too (e.g. agent tools listing extracts). User-visible consequence: anonymous viewers of a public corpus now see `totalExtracts: 0` in `corpusStats` (the resolver's counts are per-viewer by contract). Two legacy tests that pinned the old semantic were updated to the agreed behavior: `test_query_optimizer_methods.py::test_get_visible_extracts_anonymous_only_public` (now `..._anonymous_sees_nothing`) and `test_stats.py::test_public_corpus_stats_query` (anonymous branch). New coverage: `opencontractserver/tests/permissioning/test_extract_anonymous_lockdown.py`.
-- **Group-granted analysis/extract permissions now unlock private rows in list queries.** The `created_by_*` privacy gates in `AnnotationQuerySet.visible_to_user` (`opencontractserver/shared/QuerySets.py`), `AnnotationService.get_document_annotations` / `get_corpus_annotations`, and `RelationshipService.get_document_relationships` consulted only the USER object-permission tables, so a viewer whose source grant arrived via a Django group passed `user_can` (which resolves group grants by default) but never saw the rows in lists — a filter/check parity drift. All gates now route through the new shared builders in `opencontractserver/utils/source_visibility.py`, which join the group object-permission tables. The same parity class also covered `Extract.is_public`: the inline gates omitted the flag for extracts (while honouring it for analyses) even though `user_can`'s recursion grants READ on public sources — `visible_extracts_for` now includes `is_public` on the authenticated branch (no practical exposure today: no user-facing flow sets the flag). Tests: `test_source_visibility_group_grants.py` + new invariant fixtures incl. `test_public_extract_source_passes_both_surfaces`.
+- **Group-granted analysis/extract permissions now unlock private rows in list queries.** The `created_by_*` privacy gates in `AnnotationQuerySet.visible_to_user` (`opencontractserver/shared/QuerySets.py`), `AnnotationService.get_document_annotations` / `get_corpus_annotations`, and `RelationshipService.get_document_relationships` consulted only the USER object-permission tables, so a viewer whose source grant arrived via a Django group passed `user_can` (which resolves group grants by default) but never saw the rows in lists — a filter/check parity drift. All gates now route through the new shared builders in `opencontractserver/utils/source_visibility.py`, which join the group object-permission tables. Two more drifts in the same parity class were closed in the builders: (a) `Extract.is_public` — the inline gates omitted the flag for extracts (while honouring it for analyses) even though `user_can`'s recursion grants READ on public sources; `visible_extracts_for` now includes `is_public` on the authenticated branch (no practical exposure today: no user-facing flow sets the flag); (b) grant shape — the inline gates matched ANY guardian row on the source, so an `update_analysis`-only grantee saw private rows in lists while failing `user_can(READ)` (which resolves the read codename); the builders now filter `permission__codename="read_analysis"` / `"read_extract"`. Tests: `test_source_visibility_group_grants.py` + new invariant fixtures incl. `test_public_extract_source_passes_both_surfaces` and `test_update_only_source_grant_does_not_unlock_lists`.
 - **Anonymous privacy leak in corpus-wide annotation listing fixed.** `AnnotationService.get_corpus_annotations` applied the `created_by_*` privacy exclusion only to authenticated users — anonymous viewers of a public corpus could see analysis-/extract-private annotations on public documents. The exclusion now applies unconditionally (anonymous resolves to public-analyses-only / no extracts via `source_visibility`).

opencontractserver/annotations/services/annotation_service.py

@@ -743,6 +743,12 @@ def get_corpus_annotations(
         # reach. The shared builders honour user- AND group-level guardian
         # grants (parity with ``user_can``'s privacy recursion) and encode
         # the anonymous rules (public analyses only; never extracts).
+        #
+        # Intentionally UNCONDITIONAL — no ``if not user.is_anonymous``
+        # guard. The old guard skipped privacy filtering entirely for
+        # anonymous viewers, leaking analysis-/extract-private annotations
+        # on public corpora (2026-06 audit). Anonymous handling lives inside
+        # the builders instead.
         from opencontractserver.utils.source_visibility import (
             visible_analyses_for,
             visible_extracts_for,

opencontractserver/extracts/models.py

@@ -224,6 +224,10 @@ def user_can(
             resolve_user_for_user_can,
         )
 
+        # Equivalent shape to the ``visible_to_user`` guard above: the
+        # resolver maps None / unresolvable ids to None and passes
+        # AnonymousUser through, so both surfaces deny exactly the same
+        # caller set (pinned by ExtractAuthorizationInvariantsTestCase).
         resolved = resolve_user_for_user_can(user)
         if resolved is None or getattr(resolved, "is_anonymous", True):
             return False

opencontractserver/shared/Managers.py

@@ -674,6 +674,13 @@ def _source_privacy_recursion_passes(
     ``and permission == READ`` for readability rather than relying on the
     flow-sensitive equivalence.
 
+    Deleted-source posture: both FKs are ``on_delete=SET_NULL``, so deleting
+    the source Analysis/Extract NULLs the FK and the row becomes a normal
+    (non-private) row — deletion does NOT permanently lock rows. The
+    ``source is None`` branches below fire only in the race window where the
+    id column is read before the SET_NULL lands; they fail closed for that
+    window, by design.
+
     Performance note: the FK descriptors (``instance.created_by_analysis``
     / ``created_by_extract``) hit the database once each per call when the
     relations aren't prefetched. Bulk callers SHOULD

opencontractserver/tests/permissioning/test_authorization_invariants.py

@@ -1667,6 +1667,43 @@ def test_public_extract_source_passes_both_surfaces(self):
             "(parity with user_can's recursion)",
         )
 
+    def test_update_only_source_grant_does_not_unlock_lists(self):
+        """An UPDATE-only grant on the source analysis must NOT clear the
+        privacy gate (2026-06 audit follow-up): ``user_can``'s recursion
+        resolves READ through the read codename, so the list gates must
+        match — the old any-permission-row match let an
+        ``update_analysis``-only grantee see private rows in lists while
+        ``user_can(READ)`` denied them (filter/check parity violation).
+        """
+        from opencontractserver.annotations.models import Annotation
+
+        update_only = User.objects.create_user(
+            username="ann_update_only", email="auo@inv.test", password="x"
+        )
+        set_permissions_for_obj_to_user(
+            update_only, self.corpus, [PermissionTypes.READ]
+        )
+        set_permissions_for_obj_to_user(
+            update_only, self.document, [PermissionTypes.READ]
+        )
+        # UPDATE-only on the source — deliberately NO READ.
+        set_permissions_for_obj_to_user(
+            update_only, self.analysis, [PermissionTypes.UPDATE]
+        )
+
+        fresh = Annotation.objects.get(pk=self.private_via_analysis.pk)
+        self.assertFalse(
+            fresh.user_can(update_only, PermissionTypes.READ),
+            "user_can(READ) must deny an UPDATE-only source grantee",
+        )
+        self.assertFalse(
+            Annotation.objects.visible_to_user(update_only)
+            .filter(pk=self.private_via_analysis.pk)
+            .exists(),
+            "list gate must NOT be cleared by a non-READ source grant "
+            "(parity with user_can's read-codename recursion)",
+        )
+
     def test_is_public_does_not_grant_writes(self):
         """SECURITY: ``is_public=True`` grants a non-creator READ but never
         UPDATE/DELETE — the write asymmetry must hold for Annotation."""

opencontractserver/utils/source_visibility.py

@@ -20,10 +20,15 @@
 - **extracts** — NONE. Extracts are never visible to anonymous users, at
   any layer (see ``ExtractManager`` and ``ExtractService``).
 
-Grant-shape note: a *any-permission-row* match on the guardian tables
-(rather than a ``read_*`` codename filter) is deliberately preserved from
-the original inline implementations — holders of any explicit grant on the
-source object clear the privacy gate.
+Grant-shape note: the gates match guardian rows carrying the ``read_*``
+codename specifically — NOT any-permission rows. The original inline
+implementations matched any grant, which was itself a parity drift:
+``user_can``'s privacy recursion resolves READ through
+``Analysis.objects.user_can`` / ``Extract.objects.user_can``, whose
+guardian branch checks the read codename — so an ``update_analysis``-only
+grantee cleared the old list gates while failing ``user_can(READ)``
+(2026-06 audit follow-up; pinned by
+``test_update_only_source_grant_does_not_unlock_lists``).
 """
 
 from __future__ import annotations
@@ -54,11 +59,12 @@ def visible_analyses_for(user: Any) -> QuerySet:
 
     visible = Analysis.objects.filter(Q(is_public=True) | Q(creator=user))
 
-    user_grant_ids = AnalysisUserObjectPermission.objects.filter(user=user).values_list(
-        "content_object_id", flat=True
-    )
+    user_grant_ids = AnalysisUserObjectPermission.objects.filter(
+        user=user, permission__codename="read_analysis"
+    ).values_list("content_object_id", flat=True)
     group_grant_ids = AnalysisGroupObjectPermission.objects.filter(
-        group_id__in=user.groups.values_list("id", flat=True)
+        group_id__in=user.groups.values_list("id", flat=True),
+        permission__codename="read_analysis",
     ).values_list("content_object_id", flat=True)
 
     return (
@@ -102,11 +108,12 @@ def visible_extracts_for(user: Any) -> QuerySet:
 
     visible = Extract.objects.filter(Q(creator=user) | Q(is_public=True))
 
-    user_grant_ids = ExtractUserObjectPermission.objects.filter(user=user).values_list(
-        "content_object_id", flat=True
-    )
+    user_grant_ids = ExtractUserObjectPermission.objects.filter(
+        user=user, permission__codename="read_extract"
+    ).values_list("content_object_id", flat=True)
     group_grant_ids = ExtractGroupObjectPermission.objects.filter(
-        group_id__in=user.groups.values_list("id", flat=True)
+        group_id__in=user.groups.values_list("id", flat=True),
+        permission__codename="read_extract",
     ).values_list("content_object_id", flat=True)
 
     return (