sprint1: entity_permissions table + owned_mixin + universal permission service + API + migrations 0049+0050

app/services/entity_permission_service.py

@@ -0,0 +1,648 @@
+"""Universal entity permission service — ACL management for ALL entities.
+
+This service handles:
+- CRUD for entity_permissions
+- Effective access resolution (owner → user → group → role → guest)
+- Batch resolution for list queries
+- Redis caching with bitmap optimization
+- Permission expiration checks
+- Audit logging for permission changes
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import uuid
+from datetime import datetime, UTC
+from typing import Any
+
+import redis.asyncio as aioredis
+from sqlalchemy import and_, func, or_, select, text
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.entity_permission import EntityPermission
+from app.models.group import Group, UserGroup
+from app.models.role import Role
+from app.models.user import User, UserTenant
+
+logger = logging.getLogger(__name__)
+
+# Permission hierarchy: higher = more access
+_PERM_RANK = {"none": 0, "read": 1, "write": 2, "admin": 3, "delete": 4, "owner": 5}
+
+CACHE_TTL = 300  # 5 minutes
+CACHE_PREFIX = "ep_vis"  # entity permission visibility
+
+
+def _rank(level: str) -> int:
+    return _PERM_RANK.get(level, 0)
+
+
+def _serialize_permission(p: EntityPermission, principal_name: str | None = None) -> dict:
+    return {
+        "id": str(p.id),
+        "entity_type": p.entity_type,
+        "entity_id": str(p.entity_id),
+        "principal_type": p.principal_type,
+        "principal_id": str(p.principal_id),
+        "principal_name": principal_name,
+        "permission_level": p.permission_level,
+        "expires_at": p.expires_at.isoformat() if p.expires_at else None,
+        "created_by": str(p.created_by) if p.created_by else None,
+        "created_at": p.created_at.isoformat() if p.created_at else None,
+    }
+
+
+async def _load_principal_names(
+    db: AsyncSession, perms: list[EntityPermission]
+) -> dict[uuid.UUID, str]:
+    """Batch-load names for all principals in a permission list."""
+    user_ids = [p.principal_id for p in perms if p.principal_type == "user"]
+    group_ids = [p.principal_id for p in perms if p.principal_type == "group"]
+    role_ids = [p.principal_id for p in perms if p.principal_type == "role"]
+
+    names: dict[uuid.UUID, str] = {}
+
+    if user_ids:
+        result = await db.execute(select(User.id, User.name).where(User.id.in_(user_ids)))
+        names.update({row[0]: row[1] for row in result})
+
+    if group_ids:
+        result = await db.execute(select(Group.id, Group.name).where(Group.id.in_(group_ids)))
+        names.update({row[0]: row[1] for row in result})
+
+    if role_ids:
+        result = await db.execute(select(Role.id, Role.name).where(Role.id.in_(role_ids)))
+        names.update({row[0]: row[1] for row in result})
+
+    return names
+
+
+async def list_permissions(
+    db: AsyncSession, tenant_id: uuid.UUID, entity_type: str, entity_id: str
+) -> list[dict]:
+    """List all permission entries for a specific entity."""
+    entity_uuid = uuid.UUID(entity_id)
+    result = await db.execute(
+        select(EntityPermission)
+        .where(EntityPermission.entity_type == entity_type)
+        .where(EntityPermission.entity_id == entity_uuid)
+        .where(EntityPermission.tenant_id == tenant_id)
+        .order_by(EntityPermission.created_at)
+    )
+    perms = result.scalars().all()
+
+    names = await _load_principal_names(db, perms)
+    return [_serialize_permission(p, names.get(p.principal_id)) for p in perms]
+
+
+async def create_permission(
+    db: AsyncSession,
+    tenant_id: uuid.UUID,
+    entity_type: str,
+    entity_id: str,
+    principal_type: str,
+    principal_id: str,
+    permission_level: str,
+    expires_at: datetime | None = None,
+    created_by: uuid.UUID | None = None,
+) -> dict:
+    """Create or update a permission entry (upsert)."""
+    entity_uuid = uuid.UUID(entity_id)
+    principal_uuid = uuid.UUID(principal_id)
+
+    # Check for existing entry (upsert)
+    existing_q = await db.execute(
+        select(EntityPermission)
+        .where(EntityPermission.entity_type == entity_type)
+        .where(EntityPermission.entity_id == entity_uuid)
+        .where(EntityPermission.principal_type == principal_type)
+        .where(EntityPermission.principal_id == principal_uuid)
+        .where(EntityPermission.tenant_id == tenant_id)
+    )
+    existing = existing_q.scalar_one_or_none()
+
+    if existing:
+        existing.permission_level = permission_level
+        existing.expires_at = expires_at
+        await db.commit()
+        await db.refresh(existing)
+        names = await _load_principal_names(db, [existing])
+        return _serialize_permission(existing, names.get(existing.principal_id))
+
+    perm = EntityPermission(
+        tenant_id=tenant_id,
+        entity_type=entity_type,
+        entity_id=entity_uuid,
+        principal_type=principal_type,
+        principal_id=principal_uuid,
+        permission_level=permission_level,
+        expires_at=expires_at,
+        created_by=created_by,
+    )
+    db.add(perm)
+    await db.commit()
+    await db.refresh(perm)
+
+    # Invalidate cache for this principal
+    if principal_type == "user":
+        await _invalidate_user_cache(None, tenant_id, principal_uuid, entity_type)
+    elif principal_type == "group":
+        # Invalidate for all group members
+        members_q = await db.execute(
+            select(UserGroup.user_id)
+            .where(UserGroup.group_id == principal_uuid)
+            .where(UserGroup.tenant_id == tenant_id)
+        )
+        for (uid,) in members_q:
+            await _invalidate_user_cache(None, tenant_id, uid, entity_type)
+
+    names = await _load_principal_names(db, [perm])
+    return _serialize_permission(perm, names.get(perm.principal_id))
+
+
+async def update_permission(
+    db: AsyncSession,
+    tenant_id: uuid.UUID,
+    permission_id: str,
+    permission_level: str,
+    expires_at: datetime | None = None,
+) -> dict:
+    """Update an existing permission entry."""
+    perm_uuid = uuid.UUID(permission_id)
+    result = await db.execute(
+        select(EntityPermission)
+        .where(EntityPermission.id == perm_uuid)
+        .where(EntityPermission.tenant_id == tenant_id)
+    )
+    perm = result.scalar_one_or_none()
+    if not perm:
+        raise ValueError("Permission not found")
+
+    old_principal_type = perm.principal_type
+    old_principal_id = perm.principal_id
+    old_entity_type = perm.entity_type
+
+    perm.permission_level = permission_level
+    if expires_at is not None:
+        perm.expires_at = expires_at
+
+    await db.commit()
+    await db.refresh(perm)
+
+    # Invalidate cache
+    if old_principal_type == "user":
+        await _invalidate_user_cache(None, tenant_id, old_principal_id, old_entity_type)
+    elif old_principal_type == "group":
+        members_q = await db.execute(
+            select(UserGroup.user_id)
+            .where(UserGroup.group_id == old_principal_id)
+            .where(UserGroup.tenant_id == tenant_id)
+        )
+        for (uid,) in members_q:
+            await _invalidate_user_cache(None, tenant_id, uid, old_entity_type)
+
+    names = await _load_principal_names(db, [perm])
+    return _serialize_permission(perm, names.get(perm.principal_id))
+
+
+async def delete_permission(
+    db: AsyncSession, tenant_id: uuid.UUID, permission_id: str
+) -> None:
+    """Delete a permission entry."""
+    perm_uuid = uuid.UUID(permission_id)
+    result = await db.execute(
+        select(EntityPermission)
+        .where(EntityPermission.id == perm_uuid)
+        .where(EntityPermission.tenant_id == tenant_id)
+    )
+    perm = result.scalar_one_or_none()
+    if not perm:
+        raise ValueError("Permission not found")
+
+    old_principal_type = perm.principal_type
+    old_principal_id = perm.principal_id
+    old_entity_type = perm.entity_type
+
+    await db.delete(perm)
+    await db.commit()
+
+    # Invalidate cache
+    if old_principal_type == "user":
+        await _invalidate_user_cache(None, tenant_id, old_principal_id, old_entity_type)
+    elif old_principal_type == "group":
+        members_q = await db.execute(
+            select(UserGroup.user_id)
+            .where(UserGroup.group_id == old_principal_id)
+            .where(UserGroup.tenant_id == tenant_id)
+        )
+        for (uid,) in members_q:
+            await _invalidate_user_cache(None, tenant_id, uid, old_entity_type)
+
+
+async def get_effective_access(
+    db: AsyncSession,
+    tenant_id: uuid.UUID,
+    user_id: uuid.UUID,
+    entity_type: str,
+    entity_id: uuid.UUID,
+) -> str:
+    """Get the effective access level for a user on a specific entity.
+
+    Resolution (highest wins):
+    1. System admin → 'delete' (full access)
+    2. Owner → 'owner' (from owner_id on the entity table)
+    3. Direct user permission
+    4. Group permission (via user_groups)
+    5. Role permission (via user_tenants.role_id)
+    6. owner_id IS NULL → 'read' (tenant-owned, visible to all with module permission)
+    7. No access → 'none'
+
+    Returns: 'none' | 'read' | 'write' | 'admin' | 'delete' | 'owner'
+    """
+    # Check system admin
+    user_q = await db.execute(
+        select(User.is_system_admin).where(User.id == user_id)
+    )
+    if user_q.scalar():
+        return "delete"
+
+    # Check ownership — load the entity's owner_id
+    # We use raw SQL to avoid importing every model
+    owner_q = await db.execute(
+        text(f"SELECT owner_id FROM {entity_type}s WHERE id = :eid AND tenant_id = :tid"),
+        {"eid": entity_id, "tid": tenant_id},
+    )
+    owner_row = owner_q.first()
+    if not owner_row:
+        return "none"
+
+    owner_id = owner_row[0]
+    if owner_id == user_id:
+        return "owner"
+
+    # Get user's groups and role
+    groups_q = await db.execute(
+        select(UserGroup.group_id)
+        .where(UserGroup.user_id == user_id)
+        .where(UserGroup.tenant_id == tenant_id)
+    )
+    group_ids = [row[0] for row in groups_q]
+
+    role_q = await db.execute(
+        select(UserTenant.role_id)
+        .where(UserTenant.user_id == user_id)
+        .where(UserTenant.tenant_id == tenant_id)
+    )
+    role_id = role_q.scalar_one_or_none()
+
+    # Build principal conditions
+    principal_conditions = [
+        and_(
+            EntityPermission.principal_type == "user",
+            EntityPermission.principal_id == user_id,
+        ),
+    ]
+    if group_ids:
+        principal_conditions.append(
+            and_(
+                EntityPermission.principal_type == "group",
+                EntityPermission.principal_id.in_(group_ids),
+            )
+        )
+    if role_id:
+        principal_conditions.append(
+            and_(
+                EntityPermission.principal_type == "role",
+                EntityPermission.principal_id == role_id,
+            )
+        )
+
+    # Query permissions
+    now = datetime.now(UTC)
+    perm_q = await db.execute(
+        select(EntityPermission.permission_level)
+        .where(EntityPermission.entity_type == entity_type)
+        .where(EntityPermission.entity_id == entity_id)
+        .where(EntityPermission.tenant_id == tenant_id)
+        .where(or_(*principal_conditions))
+        .where(
+            or_(
+                EntityPermission.expires_at.is_(None),
+                EntityPermission.expires_at > now,
+            )
+        )
+    )
+
+    best_level = "none"
+    for (level,) in perm_q:
+        if _rank(level) > _rank(best_level):
+            best_level = level
+
+    # If owner_id is NULL (tenant-owned), user with module permission gets at least 'read'
+    if best_level == "none" and owner_id is None:
+        return "read"
+
+    return best_level
+
+
+async def get_visible_ids(
+    db: AsyncSession,
+    tenant_id: uuid.UUID,
+    user_id: uuid.UUID,
+    entity_type: str,
+) -> tuple[set[uuid.UUID], dict[uuid.UUID, str]]:
+    """Get all visible entity IDs for a user and their access levels.
+
+    Returns (visible_ids, access_map) where access_map is
+    entity_id → access_level string.
+
+    Resolution:
+    1. System admin → all entities at 'delete' level
+    2. Owned entities → 'owner'
+    3. Entities with direct/group/role permissions → permission level
+    4. Tenant-owned entities (owner_id IS NULL) → 'read'
+    """
+    # Check system admin
+    user_q = await db.execute(
+        select(User.is_system_admin).where(User.id == user_id)
+    )
+    if user_q.scalar():
+        # Return all entity IDs
+        all_q = await db.execute(
+            text(f"SELECT id FROM {entity_type}s WHERE tenant_id = :tid AND deleted_at IS NULL"),
+            {"tid": tenant_id},
+        )
+        all_ids = {row[0] for row in all_q}
+        return all_ids, {eid: "delete" for eid in all_ids}
+
+    # Get user's groups and role
+    groups_q = await db.execute(
+        select(UserGroup.group_id)
+        .where(UserGroup.user_id == user_id)
+        .where(UserGroup.tenant_id == tenant_id)
+    )
+    group_ids = [row[0] for row in groups_q]
+
+    role_q = await db.execute(
+        select(UserTenant.role_id)
+        .where(UserTenant.user_id == user_id)
+        .where(UserTenant.tenant_id == tenant_id)
+    )
+    role_id = role_q.scalar_one_or_none()
+
+    # 1. Owned entities
+    owned_q = await db.execute(
+        text(f"SELECT id FROM {entity_type}s WHERE tenant_id = :tid AND owner_id = :uid AND deleted_at IS NULL"),
+        {"tid": tenant_id, "uid": user_id},
+    )
+    visible: set[uuid.UUID] = set()
+    access_map: dict[uuid.UUID, str] = {}
+    for (eid,) in owned_q:
+        visible.add(eid)
+        access_map[eid] = "owner"
+
+    # 2. Tenant-owned entities (owner_id IS NULL)
+    tenant_owned_q = await db.execute(
+        text(f"SELECT id FROM {entity_type}s WHERE tenant_id = :tid AND owner_id IS NULL AND deleted_at IS NULL"),
+        {"tid": tenant_id},
+    )
+    for (eid,) in tenant_owned_q:
+        if eid not in visible:
+            visible.add(eid)
+            access_map[eid] = "read"
+
+    # 3. Permission-based access
+    now = datetime.now(UTC)
+    principal_conditions = [
+        and_(
+            EntityPermission.principal_type == "user",
+            EntityPermission.principal_id == user_id,
+        ),
+    ]
+    if group_ids:
+        principal_conditions.append(
+            and_(
+                EntityPermission.principal_type == "group",
+                EntityPermission.principal_id.in_(group_ids),
+            )
+        )
+    if role_id:
+        principal_conditions.append(
+            and_(
+                EntityPermission.principal_type == "role",
+                EntityPermission.principal_id == role_id,
+            )
+        )
+
+    perm_q = await db.execute(
+        select(EntityPermission.entity_id, EntityPermission.permission_level)
+        .where(EntityPermission.entity_type == entity_type)
+        .where(EntityPermission.tenant_id == tenant_id)
+        .where(or_(*principal_conditions))
+        .where(
+            or_(
+                EntityPermission.expires_at.is_(None),
+                EntityPermission.expires_at > now,
+            )
+        )
+    )
+    for eid, level in perm_q:
+        if eid not in visible or _rank(level) > _rank(access_map.get(eid, "none")):
+            visible.add(eid)
+            access_map[eid] = level
+
+    return visible, access_map
+
+
+async def batch_get_effective_access(
+    db: AsyncSession,
+    tenant_id: uuid.UUID,
+    user_id: uuid.UUID,
+    entity_type: str,
+    entity_ids: list[uuid.UUID],
+) -> dict[uuid.UUID, str]:
+    """Batch resolution: get access levels for multiple entities at once.
+
+    Much more efficient than calling get_effective_access() in a loop.
+    """
+    if not entity_ids:
+        return {}
+
+    # Check system admin
+    user_q = await db.execute(
+        select(User.is_system_admin).where(User.id == user_id)
+    )
+    if user_q.scalar():
+        return {eid: "delete" for eid in entity_ids}
+
+    # Get user's groups and role
+    groups_q = await db.execute(
+        select(UserGroup.group_id)
+        .where(UserGroup.user_id == user_id)
+        .where(UserGroup.tenant_id == tenant_id)
+    )
+    group_ids = [row[0] for row in groups_q]
+
+    role_q = await db.execute(
+        select(UserTenant.role_id)
+        .where(UserTenant.user_id == user_id)
+        .where(UserTenant.tenant_id == tenant_id)
+    )
+    role_id = role_q.scalar_one_or_none()
+
+    result: dict[uuid.UUID, str] = {}
+
+    # 1. Check ownership
+    owner_q = await db.execute(
+        text(f"SELECT id, owner_id FROM {entity_type}s WHERE id = ANY(:ids) AND tenant_id = :tid AND deleted_at IS NULL"),
+        {"ids": [str(eid) for eid in entity_ids], "tid": tenant_id},
+    )
+    for eid, owner_id in owner_q:
+        if owner_id == user_id:
+            result[uuid.UUID(str(eid))] = "owner"
+        elif owner_id is None:
+            result[uuid.UUID(str(eid))] = "read"
+
+    # 2. Check permissions
+    now = datetime.now(UTC)
+    principal_conditions = [
+        and_(
+            EntityPermission.principal_type == "user",
+            EntityPermission.principal_id == user_id,
+        ),
+    ]
+    if group_ids:
+        principal_conditions.append(
+            and_(
+                EntityPermission.principal_type == "group",
+                EntityPermission.principal_id.in_(group_ids),
+            )
+        )
+    if role_id:
+        principal_conditions.append(
+            and_(
+                EntityPermission.principal_type == "role",
+                EntityPermission.principal_id == role_id,
+            )
+        )
+
+    perm_q = await db.execute(
+        select(EntityPermission.entity_id, EntityPermission.permission_level)
+        .where(EntityPermission.entity_type == entity_type)
+        .where(EntityPermission.entity_id.in_(entity_ids))
+        .where(EntityPermission.tenant_id == tenant_id)
+        .where(or_(*principal_conditions))
+        .where(
+            or_(
+                EntityPermission.expires_at.is_(None),
+                EntityPermission.expires_at > now,
+            )
+        )
+    )
+    for eid, level in perm_q:
+        current = result.get(eid, "none")
+        if _rank(level) > _rank(current):
+            result[eid] = level
+
+    # Fill in 'none' for entities not found
+    for eid in entity_ids:
+        if eid not in result:
+            result[eid] = "none"
+
+    return result
+
+
+async def _invalidate_user_cache(
+    redis: aioredis.Redis | None,
+    tenant_id: uuid.UUID,
+    user_id: uuid.UUID,
+    entity_type: str,
+) -> None:
+    """Invalidate the visibility cache for a user + entity type."""
+    if redis is None:
+        return
+    cache_key = f"{CACHE_PREFIX}:{user_id}:{tenant_id}:{entity_type}"
+    await redis.delete(cache_key)
+
+
+async def get_cached_visible_ids(
+    db: AsyncSession,
+    redis: aioredis.Redis,
+    tenant_id: uuid.UUID,
+    user_id: uuid.UUID,
+    entity_type: str,
+) -> tuple[set[uuid.UUID], dict[uuid.UUID, str]]:
+    """Get visible IDs from Redis cache or resolve from DB.
+
+    Cache key: ep_vis:{user_id}:{tenant_id}:{entity_type}
+    Cache value: JSON {visible_ids: [str], access_map: {str: str}}
+    TTL: 5 minutes
+    """
+    cache_key = f"{CACHE_PREFIX}:{user_id}:{tenant_id}:{entity_type}"
+
+    raw = await redis.get(cache_key)
+    if raw is not None:
+        data = json.loads(raw)
+        visible = {uuid.UUID(eid) for eid in data.get("visible_ids", [])}
+        access_map = {uuid.UUID(eid): level for eid, level in data.get("access_map", {}).items()}
+        return visible, access_map
+
+    # Cache miss — resolve from DB
+    visible, access_map = await get_visible_ids(db, tenant_id, user_id, entity_type)
+
+    # Store in cache
+    cache_data = {
+        "visible_ids": [str(eid) for eid in visible],
+        "access_map": {str(eid): level for eid, level in access_map.items()},
+    }
+    await redis.setex(cache_key, CACHE_TTL, json.dumps(cache_data))
+
+    return visible, access_map
+
+
+async def invalidate_all_user_entity_cache(
+    redis: aioredis.Redis,
+    tenant_id: uuid.UUID,
+    user_id: uuid.UUID,
+) -> None:
+    """Invalidate all entity permission caches for a user."""
+    pattern = f"{CACHE_PREFIX}:{user_id}:{tenant_id}:*"
+    batch_size = 200
+    cursor: int | bytes | str = 0
+    while True:
+        cursor, keys = await redis.scan(cursor=cursor, match=pattern, count=batch_size)
+        if keys:
+            await redis.delete(*keys)
+        if int(cursor) == 0:
+            break
+
+
+async def check_entity_access(
+    db: AsyncSession,
+    tenant_id: uuid.UUID,
+    user_id: uuid.UUID,
+    entity_type: str,
+    entity_id: uuid.UUID,
+    required_level: str = "read",
+) -> bool:
+    """Check if user has at least the required access level on an entity."""
+    access = await get_effective_access(db, tenant_id, user_id, entity_type, entity_id)
+    return _rank(access) >= _rank(required_level)
+
+
+async def cleanup_expired_permissions(db: AsyncSession) -> int:
+    """Delete all expired permission entries. Returns count deleted."""
+    now = datetime.now(UTC)
+    result = await db.execute(
+        select(EntityPermission).where(EntityPermission.expires_at < now)
+    )
+    expired = result.scalars().all()
+    count = len(expired)
+    for perm in expired:
+        await db.delete(perm)
+    if count > 0:
+        await db.commit()
+        logger.info("Cleaned up %d expired entity permissions", count)
+    return count