Query Permission Patterns¶

Reference for how OpenContracts filters querysets by user permissions.

Architecture Overview¶

Permission-filtered access is organised in three tiers:

Tier 0  Model managers           user_can() / visible_to_user()
        (authorization           — single-object + queryset gates
         primitives)             — internal foundation, NOT a public entry

Tier 1  Service packages         opencontractserver/<app>/services/
        (THE public layer)       — get_* / list_* / create_* / update_* / delete_*
                                 — every user-context caller goes here
                                 — BaseService.{get_or_none, filter_visible,
                                                filter_visible_qs,
                                                require_permission, user_has}
                                   provides the generic surface

Tier 1.5  Optimizers             Private prefetch / bulk-permission helpers
        (internal detail)        — live INSIDE services; not referenced
                                   outside their owning service

Rule of thumb after Phase 6 (issue #1720): resolvers, MCP/LLM tools, REST views, and user-context Celery tasks never touch Tier 0 directly. They call Tier 1. The invariant is enforced for config/graphql/ by opencontractserver/tests/architecture/test_graphql_service_layer.py and should be extended to other consumer directories as they migrate.

Migration Recipes — "I just got an opencontracts.E001 error, what do I type?"¶

If you landed here from a Django manage.py error or a pytest failure mentioning opencontracts.E001 / "Tier-0 permission primitive", the recipe below is the answer. Both the test and the system check route through the same helper (opencontractserver.shared.architecture_audit. format_violation), so the failure output you saw is the same content as what follows — copy whichever recipe matches the identifier the scanner flagged.

In every recipe: add the import once at the top of the file:

from opencontractserver.shared.services.base import BaseService

And always pass request=info.context (or the request-equivalent your caller has) so the Tier-2 permission cache is shared across the request. (Caveat: the cache is keyed by single object, so request= only does anything on the single-object helpers — get_or_none / require_permission / user_has. On the queryset helpers filter_visible / filter_visible_qs it is accepted for API parity but is currently a no-op; pass it anyway for consistency.)

Recipe 1 — visible_to_user¶

# ❌ Forbidden
Model.objects.visible_to_user(user)
Model.objects.visible_to_user(user).get(pk=id)

# ✅ Listing visible rows (queryset, chainable like before)
BaseService.filter_visible(Model, user, request=info.context)

# ✅ IDOR-safe single-object fetch — returns None instead of raising;
#    collapses not-found and permission-denied into one branch
obj = BaseService.get_or_none(Model, pk, user, request=info.context)
if obj is None:
    return MyMutation(ok=False, message="Not found")

The "raises DoesNotExist on miss" form is intentionally gone. Returning None is the IDOR-safe contract — callers must surface a single generic error string for both "missing" and "forbidden" cases so the two branches stay indistinguishable to the client. If the surrounding code relied on DoesNotExist, replace the try/except with a if obj is None: branch returning the same error.

Recipe 2 — user_can¶

# ❌ Forbidden
if not obj.user_can(user, PermissionTypes.UPDATE):
    return MyMutation(ok=False, message="Denied")

# ✅ Fail-fast gate — returns "" on grant, error string on denial
error = BaseService.require_permission(
    obj, user, PermissionTypes.UPDATE, request=info.context
)
if error:
    return MyMutation(ok=False, message=error)

# ❌ Forbidden (boolean UI flag)
can_edit = obj.user_can(user, PermissionTypes.UPDATE)

# ✅ Boolean for UI-state fields (can_edit_summary, can_view_history, etc.)
can_edit = BaseService.user_has(
    obj, user, PermissionTypes.UPDATE, request=info.context
)

require_permission is for resolvers that need to abort with an error message. user_has is for resolvers that need a True/False to feed a UI-state GraphQL field. Don't reach for not BaseService.require_permission(...) when you can use BaseService.user_has(...) directly.

Recipe 3 — user_has_permission_for_obj¶

Same as user_can. Use BaseService.require_permission(...) for a gate or BaseService.user_has(...) for a boolean.

When the generic helpers aren't enough¶

If a dedicated per-app service method exists that matches your operation semantically (e.g. CorpusDocumentService.get_corpus_document_by_id, ConversationService.get_threads_for_corpus, AnnotationService.get_document_annotations), prefer it — it may layer prefetches, request-scoped caching, or extra domain logic on top of the generic BaseService.* call. The per-app service inventory below lists every one.

If your operation is a complex multi-object flow that doesn't fit either bucket, that's a signal to add a new method to the relevant per-app service rather than re-composing inline. The point of the rule is that permission-laden orchestration stops being "the same six lines copy-pasted everywhere" and starts being named, testable, importable operations.

The BaseService entry point¶

opencontractserver.shared.services.base.BaseService is the generic surface every per-app service inherits. It centralises the four cross-cutting operations that resolvers / tools used to inline against Tier 0:

Resolvers should always pass request=info.context so the Tier-2 permission cache (PermissionQueryOptimizer) is shared across the request. The cache is keyed by single object, so request= is only effective on the single-object helpers (get_or_none / require_permission / user_has); on filter_visible / filter_visible_qs it is accepted for API parity but is currently a no-op.

Tier-0 primitives (internal foundation)¶

visible_to_user(user) and user_can(user, instance, permission) live on managers/querysets. They are the source of truth for "can this user see / do this?", but they are not the recommended entry point for application code. They power BaseService.* and per-app service methods.

The single-object check is Model.objects.user_can(user, obj, permission) / obj.user_can(user, permission) — paired with visible_to_user and pinned to agree by opencontractserver/tests/permissioning/test_authorization_invariants.py.

Per-app service inventory (Tier 1)¶

Permission models by object type¶

Key patterns¶

MIN(document, corpus) Permission Inheritance¶

Annotations, relationships, and notes have no individual guardian permissions. Visibility is determined by the intersection of document and corpus visibility. Implementation: opencontractserver/shared/QuerySets.py (AnnotationQuerySet, NoteQuerySet).

Guardian Permission Table Lookup¶

For models with direct guardian permissions, query the {model}userobjectpermission table directly instead of using get_objects_for_user for better performance. Implementation: opencontractserver/shared/Managers.py, opencontractserver/shared/QuerySets.py.

Request-Level Caching¶

ConversationService and other Tier-1 services cache corpus and document visibility subqueries per request to avoid repeated permission checks.

Two-Tier user_can Caching (issue #1640)¶

Authorization checks via the centralized Manager.user_can / obj.user_can / _default_user_can API are cached at two layers so repeated checks within a single request collapse to one DB hit:

• Tier 1 — Per-instance memoization. get_users_permissions_for_obj caches its result on the instance as _oc_granted_perms_cache: dict, keyed by (user_id, include_group_permissions_bool) → frozenset[str]. Transparent to every caller of user_can.
• Tier 2 — Request-scoped optimizer. PermissionQueryOptimizer lives on the GraphQL request as request._permission_query_optimizer, keyed by (user_id, content_type_id, instance_pk, include_group_permissions). Engaged by passing request= (any BaseService method threads it through for you).

Invalidation contract: set_permissions_for_obj_to_user(..., request=...) clears both tiers for the affected (user, instance) pair when called inside the HTTP lifecycle. Out-of-band changes (raw assign_perm/remove_perm, migrations, Celery tasks reusing instances, group-permission changes) bypass this hook — callers must invalidate manually via delattr(instance, INSTANCE_PERMS_CACHE_ATTR) and/or get_request_optimizer(request).invalidate(user_id=..., instance=...).

Implementation: opencontractserver/utils/permission_optimizer.py, opencontractserver/utils/permissioning.py:get_users_permissions_for_obj, opencontractserver/utils/permissioning.py:_default_user_can.

Tests: opencontractserver/tests/permissioning/test_permission_optimizer.py.

Analysis/Extract Privacy Filtering¶

Annotations created by analyses or extracts inherit visibility from those parent objects. If a user cannot see the analysis/extract, they cannot see its annotations. Implementation: opencontractserver/shared/QuerySets.py (AnnotationQuerySet).

IDOR Protection¶

Mutations use BaseService.get_or_none with unified error messages to prevent object ID enumeration. The helper returns None for both not-found and not-permitted, so the caller surfaces a single string that does not leak which condition failed.

Structural Annotation Handling¶

Structural annotations (headers, sections) are always visible if the parent document is visible, regardless of creator. They are read-only for non-superusers. Implementation: opencontractserver/shared/QuerySets.py (AnnotationQuerySet visibility_filter).

Enforcement¶

See docs/development/architecture_invariants.md for the invariant index and the pattern for adding new ones.

Two independent layers point at the same scanner (opencontractserver/shared/architecture_audit.py) so a violation cannot slip through either:

1. Django system check (opencontractserver/shared/checks.py, registered via users/apps.py:ready()). Fires on every management command — manage.py runserver, migrate, shell, test, check --deploy. Emits opencontracts.E001 and blocks the command with a non-zero exit code on any inline Tier-0 use. This is the "fail on startup" guardrail — devs see violations immediately on the first manage.py invocation, not only when CI runs pytest.
2. Pytest invariant (opencontractserver/tests/architecture/test_graphql_service_layer.py). Runs in CI on every push, alongside test_authorization_invariants and test_security_hardening. Pins the same scanner plus a regression test that the Django check stays registered.

The allowlist (opencontractserver.shared.architecture_audit.ALLOWED_FILES) is empty. Every config/graphql/ module is scanned (recursively, including subpackages such as permissioning/permission_annotator/) — filters.py no longer needs an entry because its only remaining references to forbidden identifiers are inside comments (which the AST scanner already ignores).

Enforcement scope (important): both layers scan config/graphql/ only. The "always go through services" rule is policy for the other user-context surfaces — MCP tools (opencontractserver/mcp/), LLM tools (opencontractserver/llms/tools/), REST views, and user-context Celery tasks — but the scanner does not cover them yet, and they still contain correct-but-inline Tier-0 calls. A green opencontracts.E001 means "no inline Tier-0 in config/graphql/," not "none anywhere." Expanding the scan to those packages (after migrating their existing inline usage) is tracked as future work.

When you add a new resolver/mutation/MCP tool/REST view that needs permission-filtered access, either:

1. Call an existing dedicated service method (preferred when one matches your operation semantically).
2. Call BaseService.{get_or_none, filter_visible, filter_visible_qs, require_permission, user_has} directly for generic "list visible X" / "chain visibility onto an existing queryset" / "fetch X for user" / "gate write on X" / "boolean has-perm-on-X" operations.

Do not import Tier-0 identifiers into consumer code.

See Also¶

• docs/permissioning/consolidated_permissioning_guide.md — full permissioning architecture
• docs/architecture/sharing.md — object sharing patterns
• docs/refactor_plans/2026-05-19-service-layer-centralization-design.md — the design that produced this layering