Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

43.5 KB
Raw Blame
"""
Facade API for access_control.

This is the module that other apps / the presentation layer should
import from. It accepts plain inputs and returns contract DTOs, never
ORM instances or QuerySets.

Responsibilities:
- Accept DTOs / primitive inputs
- Call domain logic / ORM
- Convert Django models to DTOs before returning
- Remain thin and stable

Do NOT:
- Import DRF / serializers / HTTP concerns here
- Return ORM instances or QuerySets
"""

from __future__ import annotations

from collections import defaultdict
from collections.abc import Callable, Collection, Sequence
from copy import copy
from typing import cast
from uuid import UUID

from django.db import transaction
from django.db.models import Q
from django.db.models.signals import post_delete, post_save, pre_delete
from django.http import Http404
from django.shortcuts import get_object_or_404
from django.utils import timezone

from posthog.hogql.property_access_types import RestrictedProperty

from posthog.constants import AvailableFeature
from posthog.dataclasses import frozen
from posthog.models import Organization, OrganizationMembership, Team
from posthog.models.activity_logging.activity_log import LogActivityEntry, bulk_log_activity
from posthog.models.activity_logging.model_activity import get_current_user, get_was_impersonated
from posthog.models.team.extensions import get_or_create_team_extension
from posthog.models.user import User
from posthog.scopes import API_SCOPE_OBJECTS, INTERNAL_API_SCOPE_OBJECTS, APIScopeObject

from products.access_control.backend.activity_logging import get_access_control_log_entry
from products.access_control.backend.models.role import Role, RoleMembership
from products.event_definitions.backend.models import PropertyDefinition, effective_project_id_expr

from ..models.access_control import AccessControl
from ..models.property_access_control import PropertyAccessControl
from ..models.team_access_control_config import TeamAccessControlConfig
from ..property_access_control import (
    get_restricted_properties_with_group_type_index_for_team as _get_restricted_properties_with_group_type_index_for_team,
    is_property_access_control_enabled,
)
from . import contracts
from .contracts import PropertyAccessLevel
from .enums import AI_EVENT_PROPERTY_CHOICES
from .user_access_control import (
    RESOURCE_INHERITANCE_MAP,
    RESOURCES_WITHOUT_RESOURCE_LEVEL_CONTROLS,
    AccessControlLevel,
    access_level_satisfied_for_resource,
    default_access_level,
    highest_access_level,
    minimum_access_level,
    ordered_access_levels,
)


class InvalidObjectAccessControlError(Exception):
    """Raised when an object access control rule names an unknown resource, an access level the
    resource does not support, or a subject outside the team's organization."""


class PropertyDefinitionNotFoundError(Exception):
    """Raised when the target property definition cannot be found for the team."""


class PropertyAccessControlRuleNotFoundError(Exception):
    """Raised when trying to delete a rule that does not exist."""


class InvalidPropertyAccessControlTargetError(Exception):
    """Raised when the rule target (role or organization member) does not
    belong to the same organization as the team."""


# --- Mappers (model -> DTO) ---


def _to_rule(rule: PropertyAccessControl) -> contracts.PropertyAccessControlRule:
    # The FK is nullable in the schema, but a rule is always attached to a property: the upsert
    # resolves a concrete definition before writing, and every read path filters null rows out
    assert rule.property_definition_id is not None
    return contracts.PropertyAccessControlRule(
        id=rule.id,
        property_definition_id=rule.property_definition_id,
        access_level=PropertyAccessLevel(rule.access_level),
        organization_member_id=rule.organization_member_id,
        role_id=rule.role_id,
        created_by_id=rule.created_by_id,
        created_at=rule.created_at,
        updated_at=rule.updated_at,
    )


def get_property_definition_labels(
    *, team_id: int, property_definition_ids: list[UUID]
) -> dict[UUID, contracts.PropertyDefinitionLabel]:
    return {
        definition.id: contracts.PropertyDefinitionLabel(
            id=definition.id,
            name=definition.name,
            is_person=definition.type == PropertyDefinition.Type.PERSON,
        )
        for definition in PropertyDefinition.objects.filter(team_id=team_id, id__in=property_definition_ids)
    }


def _get_property_definition(property_definition_id: str, team_id: int) -> PropertyDefinition:
    # Callers often send the property name. The pk is a UUID, and Django raises its own
    # ValidationError for any other string, which the API would turn into a 500.
    try:
        UUID(str(property_definition_id))
    except ValueError as exc:
        raise PropertyDefinitionNotFoundError(property_definition_id) from exc
    project_id = Team.objects.values_list("project_id", flat=True).get(id=team_id)
    try:
        return get_object_or_404(
            PropertyDefinition.objects.alias(effective_project_id=effective_project_id_expr()),
            effective_project_id=project_id,
            id=property_definition_id,
        )
    except Http404 as exc:
        # Normalize 404 -> domain error so presentation can translate without leaking ORM concerns.
        raise PropertyDefinitionNotFoundError(property_definition_id) from exc


# --- Read API ---


def get_restricted_properties_with_group_type_index_for_team(
    *, user: User | None, team_id: int
) -> set[RestrictedProperty]:
    """Return property restrictions for a user and team."""
    return _get_restricted_properties_with_group_type_index_for_team(user=user, team_id=team_id)


def split_restricted_property_names(restrictions: set[RestrictedProperty]) -> contracts.RestrictedPropertyNames:
    """Return restricted event and person property names."""
    return contracts.RestrictedPropertyNames(
        event=frozenset(
            restriction.name
            for restriction in restrictions
            if restriction.property_type == PropertyDefinition.Type.EVENT
        ),
        person=frozenset(
            restriction.name
            for restriction in restrictions
            if restriction.property_type == PropertyDefinition.Type.PERSON
        ),
    )


def get_property_access_state(
    *,
    team_id: int,
    property_definition_id: str,
) -> contracts.PropertyAccessControlState:
    """Return the full access-control state for a single property definition."""
    prop_def = _get_property_definition(property_definition_id, team_id)

    rules_qs = PropertyAccessControl.objects.filter(
        team_id=team_id,
        property_definition=prop_def,
    ).select_related("organization_member", "role", "created_by")
    rules = list(rules_qs)

    # The rule with null membership AND null role acts as the property-level default.
    default_rule = next(
        (r for r in rules if r.organization_member_id is None and r.role_id is None),
        None,
    )
    default_level = PropertyAccessLevel(default_rule.access_level) if default_rule else PropertyAccessLevel.READ_WRITE

    return contracts.PropertyAccessControlState(
        rules=[_to_rule(r) for r in rules],
        available_access_levels=list(PropertyAccessLevel),
        default_access_level=default_level,
    )


def list_property_access_controls(
    *,
    team_id: int,
    organization_member_id: UUID | None = None,
    role_id: UUID | None = None,
) -> list[contracts.PropertyAccessControlRule]:
    """All property rules belonging to one subject: a member, a role, or (both None) the project-wide default."""
    rules = PropertyAccessControl.objects.filter(
        team_id=team_id,
        organization_member_id=organization_member_id,
        role_id=role_id,  # type: ignore
        property_definition__isnull=False,
    )
    return [_to_rule(rule) for rule in rules]


def team_has_property_access_rules(*, team_id: int) -> bool:
    """Whether the team has any property-level access-control rules in effect.

    True only when the feature is available for the org AND at least one rule
    targeting a property definition exists. Callers that share results across
    users (e.g. userless precompute) use this to opt out entirely, since a
    result computed without a user cannot honor per-user property restrictions.
    """
    if not is_property_access_control_enabled(team_id=team_id):
        return False
    return PropertyAccessControl.objects.filter(team_id=team_id, property_definition__isnull=False).exists()


def person_property_names_with_access_rules(*, team_id: int) -> frozenset[str]:
    """Person properties with any access rule on the team, for callers that share a result across users."""
    return frozenset(
        PropertyAccessControl.objects.filter(
            team_id=team_id, property_definition__type=PropertyDefinition.Type.PERSON
        ).values_list("property_definition__name", flat=True)
    )


def team_has_public_sharing_access_rules(*, team_id: int) -> bool:
    return (
        AccessControl.objects.filter(
            team_id=team_id,
            resource__in=[
                "project",
                "dashboard",
                "notebook",
                "insight",
                "external_data_source",
                "warehouse_objects",
                "warehouse_table",
                "warehouse_view",
            ],
        ).exists()
        or PropertyAccessControl.objects.filter(team_id=team_id, property_definition__isnull=False).exists()
    )


def user_organizations_use_access_controls(*, user_id: int) -> bool:
    """Whether access rules can narrow what the user reaches in one of their organizations.

    True only when an organization the user belongs to has the access-control feature AND
    at least one rule exists in one of its projects.
    """
    entitled = [
        org.id
        for org in Organization.objects.filter(members=user_id)
        if org.is_feature_available(AvailableFeature.ACCESS_CONTROL)
    ]
    if not entitled:
        return False
    return AccessControl.objects.filter(team__organization_id__in=entitled).exists()


def can_write_access_rules(*, team_id: int, user_id: int) -> bool:
    """True when the lock is disabled, or when the user is the Terraform account. An enabled lock
    with no account refuses everyone until the first Terraform write. The check is on the user
    behind the request and never on a client header, because any client can send any header."""
    config = TeamAccessControlConfig.objects.filter(team_id=team_id, is_managed_by_terraform=True).first()
    if config is None:
        return True
    return config.terraform_managed_by is not None and config.terraform_managed_by.user_id == user_id


def can_delete_role(*, role_id: UUID, user_id: int) -> bool:
    """False when the role has rules in a project that Terraform manages and the user is not the
    Terraform account. AccessControl.role cascades, so the delete would remove those rules without
    any rule endpoint running."""
    return not (
        TeamAccessControlConfig.objects.filter(
            is_managed_by_terraform=True,
            team_id__in=AccessControl.objects.filter(role_id=role_id).values("team_id"),
        )
        .exclude(terraform_managed_by__user_id=user_id)
        .exists()
    )


def get_terraform_lock(*, team_id: int) -> contracts.TerraformLock:
    config = TeamAccessControlConfig.objects.filter(team_id=team_id).first()
    return contracts.TerraformLock(
        managed=config is not None and config.is_managed_by_terraform,
        terraform_last_applied_at=config.terraform_last_applied_at if config else None,
        has_terraform_account=config is not None and config.terraform_managed_by_id is not None,
    )


def set_terraform_lock(*, team_id: int, enabled: bool, terraform_user_id: int | None = None) -> contracts.TerraformLock:
    """Enable or disable the lock.

    With terraform_user_id, a Terraform write made the call. The owner of that API key becomes the
    Terraform account of the project, and the write time is recorded. A different account replaces
    the stored one, so a rotated service account continues to work.

    Without terraform_user_id, an admin made the call. Disable keeps the account. Enable before the
    first Terraform write locks everyone out until that write."""
    team = get_object_or_404(Team, id=team_id)
    config = get_or_create_team_extension(team, TeamAccessControlConfig)
    if terraform_user_id is not None:
        membership = OrganizationMembership.objects.filter(
            organization_id=team.organization_id, user_id=terraform_user_id
        ).first()
        if membership is not None:
            config.terraform_managed_by = membership
        config.terraform_last_applied_at = timezone.now()
    config.is_managed_by_terraform = enabled
    config.save(update_fields=["terraform_managed_by", "terraform_last_applied_at", "is_managed_by_terraform"])
    return get_terraform_lock(team_id=team_id)


def _level_rank(levels: list[AccessControlLevel], level: str) -> int:
    """Position of `level` on the ladder, with an unrecognized level ranked below every real one."""
    return levels.index(cast(AccessControlLevel, level)) if level in levels else -1


def _grants_at_least(resource: APIScopeObject, level: str, required_level: AccessControlLevel) -> bool:
    """Whether `level` satisfies `required_level`, reading an unrecognized level as no grant.

    The access level of a row is an unvalidated string, so a value outside the ladder of the
    resource is possible. Comparing it would raise, so treat it as restricting instead."""
    if level not in ordered_access_levels(resource):
        return False
    return access_level_satisfied_for_resource(resource, cast(AccessControlLevel, level), required_level)


def every_member_has_resource_access(
    *, team_id: int, resource: APIScopeObject, required_level: AccessControlLevel
) -> bool:
    """Whether every member of the team resolves at least `required_level` on `resource`.

    For a caller that builds something without a request user and hands it to many readers at
    once — an AI-drafted ticket note, a userless precompute. Such a caller cannot honor a
    restriction on one member, so it asks whether any restriction exists at all and leaves the
    data out when one does.

    Deliberately conservative, and for that reason the same answer under both resolution orders:
    one restricting rule makes this False, including where highest-wins resolution would let a
    permissive default outrank it. Erring toward withholding keeps the answer stable when an
    organization moves to most-specific resolution.
    """
    team = Team.objects.select_related("organization").filter(id=team_id).first()
    if team is None:
        return False

    # Resolution reads the rows of the parent of an inheriting resource, never the child's own
    # resource-scope rows, so the parent is what to inspect.
    resource = RESOURCE_INHERITANCE_MAP.get(resource, resource)

    # With no rules in effect, every member sits at the built-in default for the resource.
    if resource in RESOURCES_WITHOUT_RESOURCE_LEVEL_CONTROLS or not team.organization.is_feature_available(
        AvailableFeature.ACCESS_CONTROL
    ):
        return _grants_at_least(resource, default_access_level(resource), required_level)

    rows = list(AccessControl.objects.filter(team_id=team_id, resource=resource, resource_id=None))
    everyone_rows = [row for row in rows if row.organization_member_id is None and row.role_id is None]
    subject_rows = [row for row in rows if row.organization_member_id is not None or row.role_id is not None]

    levels = ordered_access_levels(resource)
    floor = (
        max((row.access_level for row in everyone_rows), key=lambda level: _level_rank(levels, level))
        if everyone_rows
        else default_access_level(resource)
    )
    if not _grants_at_least(resource, floor, required_level):
        return False
    return all(_grants_at_least(resource, row.access_level, required_level) for row in subject_rows)


def object_ids_restricted_from_any_member(
    *, team_id: int, resource: APIScopeObject, required_level: AccessControlLevel
) -> set[str]:
    """Ids of `resource` objects carrying a rule that gives somebody less than `required_level`.

    The object-level counterpart of `every_member_has_resource_access`, for the same kind of
    caller: one that builds something without a request user and hands it to many readers at
    once. It cannot tell those readers apart, so it leaves out every object that any rule
    withholds from any of them.

    Conservative in the same way. One restricting rule on an object is enough to name it, even
    where resolution would let a permissive rule outrank that one, so the answer does not change
    when an organization moves to most-specific resolution.
    """
    team = Team.objects.select_related("organization").filter(id=team_id).first()
    if team is None or not team.organization.is_feature_available(AvailableFeature.ACCESS_CONTROL):
        return set()

    # Object rows are written against the resource itself, never its parent, so an inheriting
    # resource is not mapped here the way a resource-scope lookup maps it.
    satisfying = [
        level for level in ordered_access_levels(resource) if _grants_at_least(resource, level, required_level)
    ]
    restricted = (
        AccessControl.objects.filter(team_id=team_id, resource=resource, resource_id__isnull=False)
        .exclude(access_level__in=satisfying)
        .values_list("resource_id", flat=True)
    )
    return {resource_id for resource_id in restricted if resource_id}


def object_ids_with_rules(*, team_id: int, resource: APIScopeObject) -> set[str]:
    """Ids of `resource` objects that carry any object-level rule, whatever its level.

    For a caller that copies an object into a new one that can't carry the same rules. It skips
    every object with a rule rather than judging which rules restrict, and it ignores whether
    the organization enforces rules today, because the rules apply again when it does.
    """
    resource_ids = AccessControl.objects.filter(
        team_id=team_id, resource=resource, resource_id__isnull=False
    ).values_list("resource_id", flat=True)
    return {resource_id for resource_id in resource_ids if resource_id}


def resource_has_rules(*, team_id: int, resource: APIScopeObject) -> bool:
    """Whether the team has any resource-level rule for `resource`, whatever its level.

    For a caller about to make objects inherit from `resource`, which changes what those rules
    reach. Like `object_ids_with_rules`, it ignores whether the organization enforces rules today.
    """
    return AccessControl.objects.filter(team_id=team_id, resource=resource, resource_id__isnull=True).exists()


def access_rules(*, team_id: int, resources: Collection[str]) -> list[contracts.AccessRule]:
    """Every rule of the team on these resources, object-level and resource-level, whatever its level.

    For a caller that must predict what resolution decides after it changes which rules reach an
    object. Like `object_ids_with_rules`, it ignores whether the organization enforces rules today,
    because the rules apply again when it does.
    """
    team = Team.objects.only("id", "organization_id").get(id=team_id)
    rows = AccessControl.objects.filter(team_id=team_id, resource__in=list(resources)).values_list(
        "resource",
        "resource_id",
        "access_level",
        "organization_member_id",
        "role_id",
        "organization_member__organization_id",
        "role__organization_id",
    )
    return [
        contracts.AccessRule(
            resource=resource,
            resource_id=resource_id,
            access_level=access_level,
            organization_member_id=member_id,
            role_id=role_id,
            # Resolution reads a member's rules only in the member's own organization, and a role's
            # rules only for a role of that organization (see UserAccessControl._filter_options).
            applies=(member_id is None or role_id is None)
            and (member_id is None or member_organization_id == team.organization_id)
            and (role_id is None or role_organization_id == team.organization_id),
        )
        for (
            resource,
            resource_id,
            access_level,
            member_id,
            role_id,
            member_organization_id,
            role_organization_id,
        ) in rows
    ]


def replace_object_access_rules(
    *, team_id: int, resource: str, resource_id: str, rules: Sequence[contracts.ObjectAccessRuleInput]
) -> None:
    """Make the rules on one object exactly `rules`, the object's default rule included.

    A rule that is already there stays. The others are created or deleted one at a time, so each
    change goes into the activity log. An empty `rules` removes every rule on the object. The
    caller decides whether the change is allowed.
    """
    team = Team.objects.only("id", "organization_id").get(id=team_id)
    wanted: dict[tuple[UUID | None, UUID | None], str] = {}
    for rule in rules:
        _validate_resource_access_level(resource, rule.access_level)
        key = (rule.organization_member_id, rule.role_id)
        if key in wanted:
            raise InvalidObjectAccessControlError("Provide each subject only once.")
        wanted[key] = rule.access_level
    member_ids = {member_id for member_id, _ in wanted if member_id is not None}
    role_ids = {role_id for _, role_id in wanted if role_id is not None}
    if member_ids != set(
        OrganizationMembership.objects.filter(organization_id=team.organization_id, id__in=member_ids).values_list(
            "id", flat=True
        )
    ):
        raise InvalidObjectAccessControlError("organization_member does not belong to this team's organization.")
    if role_ids != set(
        Role.objects.filter(organization_id=team.organization_id, id__in=role_ids).values_list("id", flat=True)
    ):
        raise InvalidObjectAccessControlError("role does not belong to this team's organization.")

    with transaction.atomic():
        kept: set[tuple[UUID | None, UUID | None]] = set()
        for existing in AccessControl.objects.select_for_update().filter(
            team_id=team_id, resource=resource, resource_id=resource_id
        ):
            key = (existing.organization_member_id, existing.role_id)
            if key not in kept and wanted.get(key) == existing.access_level:
                kept.add(key)
            else:
                existing.delete()
        for (member_id, role_id), access_level in wanted.items():
            if (member_id, role_id) not in kept:
                AccessControl.objects.create(
                    team_id=team_id,
                    resource=resource,
                    resource_id=resource_id,
                    access_level=access_level,
                    organization_member_id=member_id,
                    role_id=role_id,
                )


def role_belongs_to_organization(*, role_id: str | UUID, organization_id: UUID) -> bool:
    """Whether the role is a role of that organization.

    For a caller that accepts a role id from a request and must not let it name a role of
    another organization.
    """
    return Role.objects.filter(id=role_id, organization_id=organization_id).exists()


def valid_role_member_user_ids(*, role_id: str | UUID) -> list[int]:
    """Ids of the users the role grants access to.

    A membership whose organization member moved to another organization no longer grants
    anything, so it is left out.
    """
    return list(
        RoleMembership.objects.filter(role_id=role_id).valid_for_authorization().values_list("user_id", flat=True)
    )


# --- Write API ---


def _get_or_create_ai_property_definition(team_id: int, property_name: str) -> PropertyDefinition:
    project_id = Team.objects.values_list("project_id", flat=True).get(id=team_id)
    project_definitions = PropertyDefinition.objects.alias(effective_project_id=effective_project_id_expr()).filter(
        effective_project_id=project_id
    )
    definition, _ = project_definitions.get_or_create(
        name=property_name,
        type=PropertyDefinition.Type.EVENT,
        group_type_index=None,
        defaults={"team_id": team_id, "project_id": project_id},
    )
    return definition


def _validate_target_org(
    *,
    team_id: int,
    organization_member_id: UUID | None,
    role_id: UUID | None,
) -> None:
    """Ensure the rule target (role / organization member) belongs to the
    team's organization.

    Without this check, an org admin who is also a member of another
    organization could inject role or membership UUIDs from that other org
    into rules here — which would then either be silently inert or, worse,
    collide with intra-org IDs in audits and downstream logic.
    """
    if organization_member_id is None and role_id is None:
        return

    organization_id = Team.objects.filter(id=team_id).values_list("organization_id", flat=True).first()
    if organization_id is None:
        # Team doesn't exist — the upstream get_object lookup would have failed already,
        # but be defensive.
        raise InvalidPropertyAccessControlTargetError("Team not found.")

    if organization_member_id is not None:
        if not OrganizationMembership.objects.filter(
            id=organization_member_id, organization_id=organization_id
        ).exists():
            raise InvalidPropertyAccessControlTargetError(
                "organization_member does not belong to this team's organization."
            )

    if role_id is not None:
        if not Role.objects.filter(id=role_id, organization_id=organization_id).exists():
            raise InvalidPropertyAccessControlTargetError("role does not belong to this team's organization.")


def upsert_property_access_control(
    *,
    team_id: int,
    created_by_id: int | None,
    input: contracts.UpsertPropertyAccessControlInput,
) -> contracts.PropertyAccessControlRule:
    """Create or update a single access control rule."""
    if input.ai_property is not None and input.ai_property not in AI_EVENT_PROPERTY_CHOICES:
        raise InvalidPropertyAccessControlTargetError("Unknown AI event property.")
    _validate_target_org(
        team_id=team_id,
        organization_member_id=input.organization_member_id,
        role_id=input.role_id,
    )

    with transaction.atomic():
        if input.ai_property is not None:
            prop_def = _get_or_create_ai_property_definition(team_id, input.ai_property)
        else:
            assert input.property_definition_id is not None
            prop_def = _get_property_definition(input.property_definition_id, team_id)

        # `created_by_id` must only be set on creation — using `defaults` would
        # overwrite the original creator on every update. `create_defaults`
        # (Django 4.2+) is applied only when a new row is inserted.
        rule, _created = PropertyAccessControl.objects.update_or_create(
            team_id=team_id,
            property_definition=prop_def,
            organization_member_id=input.organization_member_id,
            role_id=input.role_id,  # type: ignore[misc]  # nullable FK; django-stubs drops None from *_id lookups
            defaults={
                "access_level": input.access_level.value,
            },
            create_defaults={
                "access_level": input.access_level.value,
                "created_by_id": created_by_id,
            },
        )
    return _to_rule(rule)


def delete_property_access_control(
    *,
    team_id: int,
    input: contracts.DeletePropertyAccessControlInput,
) -> None:
    """Delete an override rule. Raises PropertyAccessControlRuleNotFoundError if nothing matched."""
    prop_def = _get_property_definition(input.property_definition_id, team_id)
    _validate_target_org(
        team_id=team_id,
        organization_member_id=input.organization_member_id,
        role_id=input.role_id,
    )

    deleted, _ = PropertyAccessControl.objects.filter(
        team_id=team_id,
        property_definition=prop_def,
        organization_member_id=input.organization_member_id,
        role_id=input.role_id,  # type: ignore
    ).delete()
    if not deleted:
        raise PropertyAccessControlRuleNotFoundError


# --- Object access controls ---


def _to_object_rule(rule: AccessControl) -> contracts.ObjectAccessControlRule:
    assert rule.resource_id is not None
    return contracts.ObjectAccessControlRule(
        id=rule.id,
        resource=rule.resource,
        resource_id=rule.resource_id,
        access_level=rule.access_level,
        organization_member_id=rule.organization_member_id,
        role_id=rule.role_id,
    )


def _validate_object_access_control_level(input: contracts.SetObjectAccessControlInput) -> APIScopeObject:
    return _validate_resource_access_level(input.resource, input.access_level)


def _validate_resource_access_level(resource: str, access_level: str | None) -> APIScopeObject:
    if resource not in API_SCOPE_OBJECTS or resource in INTERNAL_API_SCOPE_OBJECTS:
        raise InvalidObjectAccessControlError(f"{resource} is not an access controlled resource.")
    scoped_resource = cast(APIScopeObject, resource)

    if access_level is not None:
        levels = ordered_access_levels(scoped_resource)
        if access_level not in levels:
            raise InvalidObjectAccessControlError(
                f"Invalid access level for {resource}. Must be one of: {', '.join(levels)}."
            )
        # `ordered_access_levels` can include levels the settings UI never offers for a resource
        # (for example "none" on a project), so the bounds apply here as well as in the API.
        level_index = levels.index(cast(AccessControlLevel, access_level))
        if level_index < levels.index(minimum_access_level(scoped_resource)):
            raise InvalidObjectAccessControlError(f"Access level is below the minimum for {resource}.")
        if level_index > levels.index(highest_access_level(scoped_resource)):
            raise InvalidObjectAccessControlError(f"Access level is above the maximum for {resource}.")

    return scoped_resource


def _validate_object_access_control(
    *, organization_id: UUID, input: contracts.SetObjectAccessControlInput
) -> APIScopeObject:
    resource = _validate_object_access_control_level(input)
    if (
        input.organization_member_id is not None
        and not OrganizationMembership.objects.filter(
            id=input.organization_member_id, organization_id=organization_id
        ).exists()
    ):
        raise InvalidObjectAccessControlError("organization_member does not belong to this team's organization.")
    if (
        input.role_id is not None
        and not Role.objects.filter(id=input.role_id, organization_id=organization_id).exists()
    ):
        raise InvalidObjectAccessControlError("role does not belong to this team's organization.")
    return resource


@frozen
class _ObjectAccessControlKey:
    resource: str
    resource_id: str | None
    organization_member_id: UUID | None
    role_id: UUID | None


def _object_access_control_key(
    rule: contracts.SetObjectAccessControlInput | AccessControl,
) -> _ObjectAccessControlKey:
    return _ObjectAccessControlKey(
        resource=rule.resource,
        resource_id=rule.resource_id,
        organization_member_id=rule.organization_member_id,
        role_id=rule.role_id,
    )


def bulk_set_object_access_controls(*, team_id: int, inputs: list[contracts.SetObjectAccessControlInput]) -> None:
    if not inputs:
        return
    team = Team.objects.only("id", "organization_id").get(id=team_id)
    requested = {_object_access_control_key(input): input for input in inputs}
    if len(requested) != len(inputs):
        raise InvalidObjectAccessControlError("Provide each object and subject only once.")
    for input in inputs:
        _validate_object_access_control_level(input)
    member_ids = {input.organization_member_id for input in inputs if input.organization_member_id is not None}
    role_ids = {input.role_id for input in inputs if input.role_id is not None}
    if member_ids != set(
        OrganizationMembership.objects.filter(organization_id=team.organization_id, id__in=member_ids).values_list(
            "id", flat=True
        )
    ):
        raise InvalidObjectAccessControlError("organization_member does not belong to this team's organization.")
    if role_ids != set(
        Role.objects.filter(organization_id=team.organization_id, id__in=role_ids).values_list("id", flat=True)
    ):
        raise InvalidObjectAccessControlError("role does not belong to this team's organization.")

    requested_pairs = Q()
    for key in requested:
        requested_pairs |= Q(
            resource=key.resource,
            resource_id=key.resource_id,
            organization_member_id=key.organization_member_id,
            role_id=key.role_id,
        )
    with transaction.atomic():
        existing: dict[_ObjectAccessControlKey, list[AccessControl]] = defaultdict(list)
        for existing_rule in (
            AccessControl.objects.select_for_update().filter(requested_pairs, team_id=team_id).order_by("id")
        ):
            existing[_object_access_control_key(existing_rule)].append(existing_rule)
        created: list[AccessControl] = []
        updated: list[AccessControl] = []
        deleted_ids: list[UUID] = []
        entries: list[LogActivityEntry] = []
        now = timezone.now()
        for key, input in requested.items():
            matching_rules: list[AccessControl | None] = [*existing.get(key, [])] or [None]
            for rule in matching_rules:
                before = copy(rule) if rule is not None else None
                if before is not None:
                    before.team = team
                if input.access_level is None:
                    if rule is None:
                        continue
                    deleted_ids.append(rule.id)
                    activity = "deleted"
                    rule = None
                elif rule is None:
                    rule = AccessControl(
                        team=team,
                        resource=input.resource,
                        resource_id=input.resource_id,
                        organization_member_id=input.organization_member_id,
                        role_id=input.role_id,
                        access_level=input.access_level,
                        created_by_id=input.created_by_id,
                    )
                    created.append(rule)
                    activity = "created"
                else:
                    if rule.access_level == input.access_level:
                        continue
                    rule.team = team
                    rule.access_level = input.access_level
                    rule.updated_at = now
                    updated.append(rule)
                    activity = "updated"
                entry = get_access_control_log_entry(
                    before_update=before,
                    after_update=rule,
                    activity=activity,
                    user=get_current_user(),
                    was_impersonated=get_was_impersonated(),
                )
                if entry is not None:
                    entries.append(entry)
        AccessControl.objects.bulk_create(created)
        AccessControl.objects.bulk_update(updated, ["access_level", "updated_at"])
        AccessControl.objects.filter(team_id=team_id, id__in=deleted_ids).delete()
        for rule in created:
            post_save.send(sender=AccessControl, instance=rule, created=True)
        for rule in updated:
            post_save.send(sender=AccessControl, instance=rule, created=False)
        bulk_log_activity(entries)


def set_object_access_control(
    *,
    team_id: int,
    input: contracts.SetObjectAccessControlInput,
) -> contracts.ObjectAccessControlRule | None:
    """Grant, change, or remove one subject's access to one object.

    This is the programmatic counterpart of the `PUT .../access_controls` endpoint, for product code
    that must keep a rule in step with its own state (for example, the assignee of a work item).
    It writes the rule only. The caller decides whether the actor may change access, and the
    caller owns the reverse write when its state changes again.

    A `UserAccessControl` built before this call still holds its preloaded rows. Build a new one
    or clear its cache before checking the object again in the same request.

    Returns the stored rule, or None when `access_level` is None and the rule was removed.
    """
    team = Team.objects.only("id", "organization_id").get(id=team_id)
    resource = _validate_object_access_control(organization_id=team.organization_id, input=input)
    if input.access_level is None:
        # Deleted one by one because a queryset delete writes no activity log row.
        for rule in AccessControl.objects.filter(
            team_id=team_id,
            resource=resource,
            resource_id=input.resource_id,
            organization_member_id=input.organization_member_id,
            role_id=cast(UUID | str, input.role_id),
        ):
            rule.delete()
        return None

    rule, _created = AccessControl.objects.update_or_create(
        team_id=team_id,
        resource=resource,
        resource_id=input.resource_id,
        organization_member_id=input.organization_member_id,
        role_id=cast(UUID | str, input.role_id),
        defaults={"access_level": input.access_level},
        create_defaults={"access_level": input.access_level, "created_by_id": input.created_by_id},
    )
    return _to_object_rule(rule)


# --- Convenience for external callers (avoids importing UUID type at call sites) ---


def available_access_levels() -> list[PropertyAccessLevel]:
    return list(PropertyAccessLevel)


_PROPERTY_LEVEL_ORDER = (PropertyAccessLevel.NONE, PropertyAccessLevel.READ, PropertyAccessLevel.READ_WRITE)


def stored_property_rule_floor(*, user: User, team_id: int) -> PropertyAccessLevel | None:
    """The lowest level the stored property rules can give ``user`` on one property of the team.

    The property-rule counterpart of ``UserAccessControl.stored_rule_floor``, with the same
    candidates per property: the user's member rows, else their role rows and the default rows.
    Rows match as ``_resolve_access_level`` matches them: a row naming the user's membership is
    a member row whatever its role, and a row naming one of the user's roles is a role row.
    It holds whether or not the organization is entitled to property access control or roles.
    ``None`` means no stored rule applies. This includes org admins, who bypass property rules.
    """
    organization_id = Team.objects.filter(id=team_id).values_list("organization_id", flat=True).first()
    if organization_id is None:
        return None
    membership = OrganizationMembership.objects.filter(user=user, organization_id=organization_id).first()
    if membership is None or membership.level >= OrganizationMembership.Level.ADMIN:
        return None
    role_ids = list(
        RoleMembership.objects.filter(user=user, role__organization_id=organization_id)
        .valid_for_authorization()
        .values_list("role_id", flat=True)
    )
    rows = PropertyAccessControl.objects.filter(team_id=team_id, property_definition__isnull=False).filter(
        Q(organization_member=None, role=None) | Q(organization_member_id=membership.id) | Q(role_id__in=role_ids)
    )
    rows_by_property: dict[UUID | None, list[PropertyAccessControl]] = {}
    for row in rows:
        rows_by_property.setdefault(row.property_definition_id, []).append(row)
    lowest: PropertyAccessLevel | None = None
    for property_rows in rows_by_property.values():
        member_rows = [row for row in property_rows if row.organization_member_id == membership.id]
        for row in member_rows or property_rows:
            # A level outside the order is unknown: count it as no access.
            level = next((known for known in _PROPERTY_LEVEL_ORDER if known.value == row.access_level), None)
            level = level or PropertyAccessLevel.NONE
            if lowest is None or _PROPERTY_LEVEL_ORDER.index(level) < _PROPERTY_LEVEL_ORDER.index(lowest):
                lowest = level
    return lowest


def connect_access_change_receivers(
    *,
    on_rule_change: Callable[[int, str], None],
    on_role_membership_change: Callable[[int, UUID], None],
    is_active: Callable[[], bool],
    dispatch_uid: str,
) -> None:
    """Call back when an access rule or a role membership is saved or deleted.

    ``on_rule_change(team_id, resource)`` runs after a rule is saved or deleted. A property rule
    comes in as the ``property_definition`` resource.
    ``on_role_membership_change(user_id, organization_id)`` runs after a role membership is
    saved or deleted. ``organization_id`` is the role's organization, read before a delete while
    the role is still there: most role memberships carry no organization membership.

    Neither runs while ``is_active()`` is false, so a disabled caller costs no role query.

    Both run inside the change's transaction: defer real work with ``transaction.on_commit``.
    Only ids cross this boundary, never the models.
    """

    def rule_changed(sender: object, instance: AccessControl, **kwargs: object) -> None:
        if is_active():
            on_rule_change(instance.team_id, instance.resource)

    def role_membership_changed(sender: object, instance: RoleMembership, **kwargs: object) -> None:
        if is_active():
            on_role_membership_change(instance.user_id, instance.role.organization_id)

    # Outside a transaction a callback's on_commit runs at once, so it must not run before the
    # delete: read the organization before it, and call back after it.
    pending_attr = f"_{dispatch_uid}_role_organization_id"

    def role_membership_deleting(sender: object, instance: RoleMembership, **kwargs: object) -> None:
        if is_active():
            setattr(instance, pending_attr, instance.role.organization_id)

    def role_membership_deleted(sender: object, instance: RoleMembership, **kwargs: object) -> None:
        organization_id = getattr(instance, pending_attr, None)
        if organization_id is not None:
            on_role_membership_change(instance.user_id, organization_id)

    # weak=False: the receivers are closures, and nothing else holds them.
    post_save.connect(rule_changed, sender=AccessControl, weak=False, dispatch_uid=f"{dispatch_uid}_rule_saved")
    post_delete.connect(rule_changed, sender=AccessControl, weak=False, dispatch_uid=f"{dispatch_uid}_rule_deleted")

    def property_rule_changed(sender: object, instance: PropertyAccessControl, **kwargs: object) -> None:
        if is_active():
            on_rule_change(instance.team_id, "property_definition")

    post_save.connect(
        property_rule_changed,
        sender=PropertyAccessControl,
        weak=False,
        dispatch_uid=f"{dispatch_uid}_property_rule_saved",
    )
    post_delete.connect(
        property_rule_changed,
        sender=PropertyAccessControl,
        weak=False,
        dispatch_uid=f"{dispatch_uid}_property_rule_deleted",
    )
    post_save.connect(
        role_membership_changed, sender=RoleMembership, weak=False, dispatch_uid=f"{dispatch_uid}_role_saved"
    )
    pre_delete.connect(
        role_membership_deleting, sender=RoleMembership, weak=False, dispatch_uid=f"{dispatch_uid}_role_deleting"
    )
    post_delete.connect(
        role_membership_deleted, sender=RoleMembership, weak=False, dispatch_uid=f"{dispatch_uid}_role_deleted"
    )


__all__ = [
    "connect_access_change_receivers",
    "stored_property_rule_floor",
    "InvalidPropertyAccessControlTargetError",
    "PropertyAccessControlRuleNotFoundError",
    "PropertyAccessLevel",
    "PropertyDefinitionNotFoundError",
    "available_access_levels",
    "delete_property_access_control",
    "get_property_access_state",
    "list_property_access_controls",
    "upsert_property_access_control",
]