Release v0.1.6

src/govoplan_core/admin/common.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+import re
+
+_SLUG_RE = re.compile(r"[^a-z0-9]+")
+
+
+class AdminConflictError(ValueError):
+    pass
+
+
+class AdminValidationError(ValueError):
+    pass
+
+
+def slugify(value: str) -> str:
+    slug = _SLUG_RE.sub("-", value.strip().casefold()).strip("-")
+    if not slug:
+        raise AdminValidationError("A slug must contain at least one letter or number.")
+    return slug[:100]
+

src/govoplan_core/admin/governance.py

@@ -1,328 +0,0 @@
-from __future__ import annotations
-
-from dataclasses import dataclass
-
-from sqlalchemy.orm import Session
-
-from govoplan_core.admin.service import AdminConflictError, AdminValidationError, slugify
-from govoplan_core.core.optional import reraise_unless_missing_package
-from govoplan_core.db.models import (
-    ApiKey,
-    GovernanceTemplate,
-    GovernanceTemplateAssignment,
-    Group,
-    GroupRoleAssignment,
-    Role,
-    SystemSettings,
-    Tenant,
-    UserGroupMembership,
-    UserRoleAssignment,
-)
-from govoplan_core.security.permissions import validate_tenant_permissions
-
-SYSTEM_SETTINGS_ID = "global"
-TEMPLATE_KINDS = {"group", "role"}
-ASSIGNMENT_MODES = {"available", "required"}
-
-
-def _file_models():
-    try:
-        from govoplan_files.backend.db.models import FileAsset, FileFolder, FileShare
-    except ModuleNotFoundError as exc:
-        reraise_unless_missing_package(exc, "govoplan_files")
-        return None
-    return FileAsset, FileFolder, FileShare
-
-
-@dataclass(frozen=True)
-class EffectiveTenantGovernance:
-    allow_custom_groups: bool
-    allow_custom_roles: bool
-    allow_api_keys: bool
-
-
-def get_system_settings(session: Session) -> SystemSettings:
-    item = session.get(SystemSettings, SYSTEM_SETTINGS_ID)
-    if item is None:
-        item = SystemSettings(id=SYSTEM_SETTINGS_ID)
-        session.add(item)
-        session.flush()
-    return item
-
-
-def _narrowing_bool(system_allows: bool, tenant_override: bool | None) -> bool:
-    if not system_allows:
-        return False
-    return tenant_override is not False
-
-
-def effective_tenant_governance(session: Session, tenant: Tenant) -> EffectiveTenantGovernance:
-    defaults = get_system_settings(session)
-    return EffectiveTenantGovernance(
-        allow_custom_groups=_narrowing_bool(defaults.allow_tenant_custom_groups, tenant.allow_custom_groups),
-        allow_custom_roles=_narrowing_bool(defaults.allow_tenant_custom_roles, tenant.allow_custom_roles),
-        allow_api_keys=_narrowing_bool(defaults.allow_tenant_api_keys, tenant.allow_api_keys),
-    )
-
-
-def assert_tenant_governance_override_allowed(session: Session, *, field: str, value: bool | None) -> None:
-    if value is not True:
-        return
-    defaults = get_system_settings(session)
-    blocked = {
-        "allow_custom_groups": not defaults.allow_tenant_custom_groups,
-        "allow_custom_roles": not defaults.allow_tenant_custom_roles,
-        "allow_api_keys": not defaults.allow_tenant_api_keys,
-    }
-    if blocked.get(field):
-        raise AdminValidationError("Tenant governance cannot explicitly allow a capability denied by system settings.")
-
-
-def validate_template(kind: str, permissions: list[str]) -> list[str]:
-    if kind not in TEMPLATE_KINDS:
-        raise AdminValidationError("Template kind must be group or role.")
-    if kind == "group":
-        if permissions:
-            raise AdminValidationError("Group templates do not contain permissions; assign roles to groups inside each tenant.")
-        return []
-    try:
-        return validate_tenant_permissions(permissions)
-    except ValueError as exc:
-        raise AdminValidationError(str(exc)) from exc
-
-
-def create_template(
-    session: Session,
-    *,
-    kind: str,
-    slug: str,
-    name: str,
-    description: str | None,
-    permissions: list[str],
-    is_active: bool,
-    assignments: list[dict[str, str]],
-) -> GovernanceTemplate:
-    normalized_slug = slugify(slug)
-    permissions = validate_template(kind, permissions)
-    exists = session.query(GovernanceTemplate).filter(
-        GovernanceTemplate.kind == kind,
-        GovernanceTemplate.slug == normalized_slug,
-    ).first()
-    if exists:
-        raise AdminConflictError(f"A {kind} template with slug {normalized_slug!r} already exists.")
-    item = GovernanceTemplate(
-        kind=kind,
-        slug=normalized_slug,
-        name=name.strip(),
-        description=description,
-        permissions=permissions,
-        is_active=is_active,
-    )
-    session.add(item)
-    session.flush()
-    set_template_assignments(session, item, assignments)
-    return item
-
-
-def update_template(
-    session: Session,
-    item: GovernanceTemplate,
-    *,
-    name: str,
-    description: str | None,
-    permissions: list[str],
-    is_active: bool,
-    assignments: list[dict[str, str]],
-) -> GovernanceTemplate:
-    item.name = name.strip()
-    item.description = description
-    item.permissions = validate_template(item.kind, permissions)
-    item.is_active = is_active
-    set_template_assignments(session, item, assignments)
-    sync_template(session, item)
-    return item
-
-
-def set_template_assignments(
-    session: Session,
-    item: GovernanceTemplate,
-    assignments: list[dict[str, str]],
-) -> None:
-    desired: dict[str, str] = {}
-    for assignment in assignments:
-        tenant_id = assignment.get("tenant_id", "")
-        mode = assignment.get("mode", "available")
-        if mode not in ASSIGNMENT_MODES:
-            raise AdminValidationError("Template assignment mode must be available or required.")
-        tenant = session.get(Tenant, tenant_id)
-        if tenant is None:
-            raise AdminValidationError(f"Unknown tenant: {tenant_id}")
-        desired[tenant_id] = mode
-
-    existing = {
-        row.tenant_id: row
-        for row in session.query(GovernanceTemplateAssignment)
-        .filter(GovernanceTemplateAssignment.template_id == item.id)
-        .all()
-    }
-    for tenant_id, row in list(existing.items()):
-        if tenant_id in desired:
-            row.mode = desired[tenant_id]
-            continue
-        _remove_materialized_template(session, item, tenant_id)
-        session.delete(row)
-
-    for tenant_id, mode in desired.items():
-        if tenant_id not in existing:
-            session.add(GovernanceTemplateAssignment(template_id=item.id, tenant_id=tenant_id, mode=mode))
-    session.flush()
-    sync_template(session, item)
-
-
-def sync_template(session: Session, item: GovernanceTemplate) -> None:
-    assignments = session.query(GovernanceTemplateAssignment).filter(
-        GovernanceTemplateAssignment.template_id == item.id
-    ).all()
-    for assignment in assignments:
-        required = assignment.mode == "required"
-        if item.kind == "group":
-            group = session.query(Group).filter(
-                Group.tenant_id == assignment.tenant_id,
-                Group.system_template_id == item.id,
-            ).first()
-            if group is None:
-                group = Group(
-                    tenant_id=assignment.tenant_id,
-                    slug=_available_slug(session, Group, assignment.tenant_id, item.slug),
-                    name=item.name,
-                    description=item.description,
-                    is_active=item.is_active,
-                    system_template_id=item.id,
-                    system_required=required,
-                )
-                session.add(group)
-            else:
-                group.name = item.name
-                group.description = item.description
-                group.system_required = required
-                if required:
-                    group.is_active = item.is_active
-        else:
-            role = session.query(Role).filter(
-                Role.tenant_id == assignment.tenant_id,
-                Role.system_template_id == item.id,
-            ).first()
-            if role is None:
-                role = Role(
-                    tenant_id=assignment.tenant_id,
-                    slug=_available_slug(session, Role, assignment.tenant_id, item.slug),
-                    name=item.name,
-                    description=item.description,
-                    permissions=item.permissions,
-                    is_builtin=False,
-                    is_assignable=item.is_active,
-                    system_template_id=item.id,
-                    system_required=required,
-                )
-                session.add(role)
-            else:
-                role.name = item.name
-                role.description = item.description
-                role.permissions = item.permissions
-                role.system_required = required
-                if required:
-                    role.is_assignable = item.is_active
-    session.flush()
-
-
-
-def delete_template(session: Session, item: GovernanceTemplate) -> None:
-    assignments = session.query(GovernanceTemplateAssignment).filter(
-        GovernanceTemplateAssignment.template_id == item.id
-    ).all()
-    for assignment in assignments:
-        _remove_materialized_template(session, item, assignment.tenant_id)
-    session.delete(item)
-
-
-def _remove_materialized_template(session: Session, item: GovernanceTemplate, tenant_id: str) -> None:
-    if item.kind == "group":
-        group = session.query(Group).filter(
-            Group.tenant_id == tenant_id,
-            Group.system_template_id == item.id,
-        ).first()
-        if group is None:
-            return
-        membership_count = session.query(UserGroupMembership).filter(UserGroupMembership.group_id == group.id).count()
-        role_count = session.query(GroupRoleAssignment).filter(GroupRoleAssignment.group_id == group.id).count()
-        file_models = _file_models()
-        owned_asset_count = 0
-        owned_folder_count = 0
-        shared_asset_count = 0
-        if file_models is not None:
-            FileAsset, FileFolder, FileShare = file_models
-            owned_asset_count = session.query(FileAsset).filter(FileAsset.owner_group_id == group.id).count()
-            owned_folder_count = session.query(FileFolder).filter(FileFolder.owner_group_id == group.id).count()
-            shared_asset_count = session.query(FileShare).filter(
-                FileShare.target_type == "group", FileShare.target_id == group.id
-            ).count()
-        if membership_count or role_count or owned_asset_count or owned_folder_count or shared_asset_count:
-            raise AdminConflictError(
-                f"Cannot remove {item.name!r} from the tenant while its managed group has members, roles, files, folders or shares."
-            )
-        session.delete(group)
-        return
-
-    role = session.query(Role).filter(
-        Role.tenant_id == tenant_id,
-        Role.system_template_id == item.id,
-    ).first()
-    if role is None:
-        return
-    user_count = session.query(UserRoleAssignment).filter(UserRoleAssignment.role_id == role.id).count()
-    group_count = session.query(GroupRoleAssignment).filter(GroupRoleAssignment.role_id == role.id).count()
-    if user_count or group_count:
-        raise AdminConflictError(
-            f"Cannot remove {item.name!r} from the tenant while its managed role is assigned to users or groups."
-        )
-    session.delete(role)
-
-
-def _available_slug(session: Session, model: type[Group] | type[Role], tenant_id: str, base: str) -> str:
-    candidate = base
-    suffix = 2
-    while session.query(model).filter(model.tenant_id == tenant_id, model.slug == candidate).first():
-        candidate = f"{base}-{suffix}"
-        suffix += 1
-    return candidate
-
-
-def ensure_group_mutation_allowed(group: Group, *, requested_active: bool | None = None) -> None:
-    if group.system_template_id and group.system_required and requested_active is False:
-        raise AdminConflictError("This centrally required group cannot be deactivated by the tenant.")
-
-
-def ensure_role_mutation_allowed(role: Role, *, requested_assignable: bool | None = None) -> None:
-    if role.system_template_id:
-        if role.system_required and requested_assignable is False:
-            raise AdminConflictError("This centrally required role cannot be made unavailable by the tenant.")
-        raise AdminConflictError("Centrally managed role definitions can only be changed in System administration.")
-
-
-def assert_api_keys_allowed(session: Session, tenant: Tenant) -> None:
-    if not effective_tenant_governance(session, tenant).allow_api_keys:
-        raise AdminConflictError("API-key creation is disabled by system or tenant governance.")
-
-
-def assert_custom_groups_allowed(session: Session, tenant: Tenant) -> None:
-    if not effective_tenant_governance(session, tenant).allow_custom_groups:
-        raise AdminConflictError("Custom tenant groups are disabled by system or tenant governance.")
-
-
-def assert_custom_roles_allowed(session: Session, tenant: Tenant) -> None:
-    if not effective_tenant_governance(session, tenant).allow_custom_roles:
-        raise AdminConflictError("Custom tenant roles are disabled by system or tenant governance.")
-
-
-def active_api_key_count(session: Session, tenant_id: str) -> int:
-    return session.query(ApiKey).filter(ApiKey.tenant_id == tenant_id, ApiKey.revoked_at.is_(None)).count()

src/govoplan_core/admin/models.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from typing import Any
+
+from sqlalchemy import Boolean, JSON, String
+from sqlalchemy.orm import Mapped, mapped_column
+
+from govoplan_core.db.base import Base, TimestampMixin
+
+
+class SystemSettings(Base, TimestampMixin):
+    __tablename__ = "system_settings"
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default="global")
+    default_locale: Mapped[str] = mapped_column(String(20), default="en", nullable=False)
+    allow_tenant_custom_groups: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
+    allow_tenant_custom_roles: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
+    allow_tenant_api_keys: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
+    settings: Mapped[dict[str, Any]] = mapped_column(JSON, default=dict, nullable=False)
+
+
+__all__ = ["SystemSettings"]
+

src/govoplan_core/admin/service.py

@@ -1,609 +0,0 @@
-from __future__ import annotations
-
-import re
-import secrets
-import string
-from collections.abc import Iterable
-from dataclasses import dataclass
-
-from sqlalchemy import func
-from sqlalchemy.orm import Session
-
-from govoplan_core.core.optional import reraise_unless_missing_package
-from govoplan_core.db.models import (
-    Account,
-    ApiKey,
-    Group,
-    GroupRoleAssignment,
-    Role,
-    SystemRoleAssignment,
-    Tenant,
-    User,
-    UserGroupMembership,
-    UserRoleAssignment,
-)
-from govoplan_core.security.passwords import hash_password
-from govoplan_core.security.permissions import (
-    DEFAULT_SYSTEM_ROLES,
-    DEFAULT_TENANT_ROLES,
-    normalize_email,
-    scopes_grant,
-    validate_system_permissions,
-    validate_tenant_permissions,
-)
-
-_SLUG_RE = re.compile(r"[^a-z0-9]+")
-_TEMP_PASSWORD_ALPHABET = string.ascii_letters + string.digits + "-_!@#"
-
-
-class AdminConflictError(ValueError):
-    pass
-
-
-
-
-class AdminValidationError(ValueError):
-    pass
-
-
-@dataclass(slots=True)
-class MembershipCreationResult:
-    user: User
-    account: Account
-    temporary_password: str | None = None
-    account_created: bool = False
-
-
-def slugify(value: str) -> str:
-    slug = _SLUG_RE.sub("-", value.strip().casefold()).strip("-")
-    if not slug:
-        raise AdminValidationError("A slug must contain at least one letter or number.")
-    return slug[:100]
-
-
-def generate_temporary_password(length: int = 20) -> str:
-    return "".join(secrets.choice(_TEMP_PASSWORD_ALPHABET) for _ in range(length))
-
-
-def ensure_default_roles(session: Session, tenant: Tenant | None = None) -> dict[str, Role]:
-    definitions = DEFAULT_TENANT_ROLES if tenant is not None else DEFAULT_SYSTEM_ROLES
-    roles: dict[str, Role] = {}
-    for slug, definition in definitions.items():
-        query = session.query(Role).filter(Role.slug == slug)
-        query = query.filter(Role.tenant_id == tenant.id) if tenant is not None else query.filter(Role.tenant_id.is_(None))
-        role = query.one_or_none()
-        if role is None:
-            role = Role(
-                tenant_id=tenant.id if tenant is not None else None,
-                slug=slug,
-                name=str(definition["name"]),
-                description=str(definition.get("description") or "") or None,
-                permissions=list(definition["permissions"]),
-                is_builtin=bool(definition.get("is_builtin", True)),
-                is_assignable=bool(definition.get("is_assignable", True)),
-            )
-            session.add(role)
-            session.flush()
-        else:
-            # Tenant built-ins and explicitly managed system roles remain
-            # code-defined. Seeded, non-protected system roles are only created
-            # here and can subsequently be administered in the System roles UI.
-            managed = tenant is not None or bool(definition.get("managed", False))
-            if managed:
-                role.name = str(definition["name"])
-                role.description = str(definition.get("description") or "") or None
-                role.permissions = list(definition["permissions"])
-                role.is_builtin = bool(definition.get("is_builtin", True))
-                role.is_assignable = bool(definition.get("is_assignable", True))
-                session.add(role)
-        roles[slug] = role
-    return roles
-
-
-def get_or_create_account(
-    session: Session,
-    *,
-    email: str,
-    display_name: str | None = None,
-    password: str | None = None,
-    password_reset_required: bool = False,
-) -> tuple[Account, bool, str | None]:
-    normalized = normalize_email(email)
-    if not normalized or "@" not in normalized:
-        raise AdminValidationError("Enter a valid email address.")
-    account = session.query(Account).filter(Account.normalized_email == normalized).one_or_none()
-    if account is not None:
-        if not account.is_active:
-            raise AdminConflictError(
-                "The global account is disabled. A system administrator must reactivate it before adding a tenant membership."
-            )
-        return account, False, None
-
-    temporary_password = password or generate_temporary_password()
-    account = Account(
-        email=email.strip(),
-        normalized_email=normalized,
-        display_name=display_name.strip() if display_name else None,
-        is_active=True,
-        auth_provider="local",
-        password_hash=hash_password(temporary_password),
-        password_reset_required=password_reset_required or password is None,
-    )
-    session.add(account)
-    session.flush()
-    return account, True, temporary_password
-
-
-def create_membership(
-    session: Session,
-    *,
-    tenant: Tenant,
-    email: str,
-    display_name: str | None = None,
-    password: str | None = None,
-    password_reset_required: bool = False,
-    is_active: bool = True,
-) -> MembershipCreationResult:
-    account, account_created, temporary_password = get_or_create_account(
-        session,
-        email=email,
-        display_name=display_name,
-        password=password,
-        password_reset_required=password_reset_required,
-    )
-    existing = (
-        session.query(User)
-        .filter(User.tenant_id == tenant.id, User.account_id == account.id)
-        .one_or_none()
-    )
-    if existing is not None:
-        raise AdminConflictError("This account already belongs to the tenant.")
-
-    user = User(
-        tenant_id=tenant.id,
-        account_id=account.id,
-        email=account.email,
-        display_name=display_name.strip() if display_name else account.display_name,
-        is_active=is_active,
-        is_tenant_admin=False,
-        auth_provider=account.auth_provider,
-        password_hash=account.password_hash,
-    )
-    session.add(user)
-    session.flush()
-    return MembershipCreationResult(
-        user=user,
-        account=account,
-        temporary_password=temporary_password if account_created else None,
-        account_created=account_created,
-    )
-
-
-
-def set_user_groups(session: Session, *, user: User, group_ids: Iterable[str]) -> None:
-    ids = sorted(set(group_ids))
-    groups = (
-        session.query(Group)
-        .filter(Group.tenant_id == user.tenant_id, Group.id.in_(ids))
-        .all()
-        if ids else []
-    )
-    if len(groups) != len(ids):
-        raise AdminValidationError("One or more selected groups do not belong to the tenant.")
-
-    session.query(UserGroupMembership).filter(
-        UserGroupMembership.tenant_id == user.tenant_id,
-        UserGroupMembership.user_id == user.id,
-    ).delete(synchronize_session=False)
-    for group in groups:
-        session.add(UserGroupMembership(tenant_id=user.tenant_id, user_id=user.id, group_id=group.id))
-    session.flush()
-
-
-def set_user_roles(session: Session, *, user: User, role_ids: Iterable[str]) -> None:
-    ids = sorted(set(role_ids))
-    roles = (
-        session.query(Role)
-        .filter(Role.tenant_id == user.tenant_id, Role.id.in_(ids), Role.is_assignable.is_(True))
-        .all()
-        if ids else []
-    )
-    if len(roles) != len(ids):
-        raise AdminValidationError("One or more selected roles are invalid or not assignable.")
-
-    session.query(UserRoleAssignment).filter(
-        UserRoleAssignment.tenant_id == user.tenant_id,
-        UserRoleAssignment.user_id == user.id,
-    ).delete(synchronize_session=False)
-    for role in roles:
-        session.add(UserRoleAssignment(tenant_id=user.tenant_id, user_id=user.id, role_id=role.id))
-    session.flush()
-
-
-def set_group_members(session: Session, *, group: Group, user_ids: Iterable[str]) -> None:
-    ids = sorted(set(user_ids))
-    users = (
-        session.query(User)
-        .filter(User.tenant_id == group.tenant_id, User.id.in_(ids))
-        .all()
-        if ids else []
-    )
-    if len(users) != len(ids):
-        raise AdminValidationError("One or more selected users do not belong to the tenant.")
-
-    session.query(UserGroupMembership).filter(
-        UserGroupMembership.tenant_id == group.tenant_id,
-        UserGroupMembership.group_id == group.id,
-    ).delete(synchronize_session=False)
-    for user in users:
-        session.add(UserGroupMembership(tenant_id=group.tenant_id, user_id=user.id, group_id=group.id))
-    session.flush()
-
-
-def set_group_roles(session: Session, *, group: Group, role_ids: Iterable[str]) -> None:
-    ids = sorted(set(role_ids))
-    roles = (
-        session.query(Role)
-        .filter(Role.tenant_id == group.tenant_id, Role.id.in_(ids), Role.is_assignable.is_(True))
-        .all()
-        if ids else []
-    )
-    if len(roles) != len(ids):
-        raise AdminValidationError("One or more selected roles are invalid or not assignable.")
-
-    session.query(GroupRoleAssignment).filter(
-        GroupRoleAssignment.tenant_id == group.tenant_id,
-        GroupRoleAssignment.group_id == group.id,
-    ).delete(synchronize_session=False)
-    for role in roles:
-        session.add(GroupRoleAssignment(tenant_id=group.tenant_id, group_id=group.id, role_id=role.id))
-    session.flush()
-
-
-def create_custom_role(
-    session: Session,
-    *,
-    tenant: Tenant,
-    slug: str,
-    name: str,
-    description: str | None,
-    permissions: Iterable[str],
-) -> Role:
-    normalized_slug = slugify(slug)
-    if session.query(Role).filter(Role.tenant_id == tenant.id, Role.slug == normalized_slug).count():
-        raise AdminConflictError("A role with this slug already exists in the tenant.")
-    try:
-        validated = validate_tenant_permissions(permissions)
-    except ValueError as exc:
-        raise AdminValidationError(str(exc)) from exc
-    role = Role(
-        tenant_id=tenant.id,
-        slug=normalized_slug,
-        name=name.strip(),
-        description=description.strip() if description else None,
-        permissions=validated,
-        is_builtin=False,
-        is_assignable=True,
-    )
-    session.add(role)
-    session.flush()
-    return role
-
-
-def update_custom_role(
-    session: Session,
-    *,
-    role: Role,
-    name: str,
-    description: str | None,
-    permissions: Iterable[str],
-    is_assignable: bool,
-) -> None:
-    if role.is_builtin:
-        raise AdminConflictError("Built-in roles are managed by the application and cannot be edited.")
-    try:
-        validated = validate_tenant_permissions(permissions)
-    except ValueError as exc:
-        raise AdminValidationError(str(exc)) from exc
-    role.name = name.strip()
-    role.description = description.strip() if description else None
-    role.permissions = validated
-    role.is_assignable = is_assignable
-    session.add(role)
-    session.flush()
-
-
-def delete_custom_role(session: Session, role: Role) -> None:
-    if role.is_builtin:
-        raise AdminConflictError("Built-in roles cannot be deleted.")
-    assigned = session.query(UserRoleAssignment).filter(UserRoleAssignment.role_id == role.id).count()
-    assigned += session.query(GroupRoleAssignment).filter(GroupRoleAssignment.role_id == role.id).count()
-    if assigned:
-        raise AdminConflictError("Remove all user and group assignments before deleting this role.")
-    session.delete(role)
-    session.flush()
-
-
-def create_system_role(
-    session: Session,
-    *,
-    slug: str,
-    name: str,
-    description: str | None,
-    permissions: Iterable[str],
-) -> Role:
-    normalized_slug = slugify(slug)
-    if session.query(Role).filter(Role.tenant_id.is_(None), Role.slug == normalized_slug).count():
-        raise AdminConflictError("A system role with this slug already exists.")
-    try:
-        validated = validate_system_permissions(permissions)
-    except ValueError as exc:
-        raise AdminValidationError(str(exc)) from exc
-    if "system:*" in validated:
-        raise AdminValidationError("Only the protected System owner role may contain system:*.")
-    role = Role(
-        tenant_id=None,
-        slug=normalized_slug,
-        name=name.strip(),
-        description=description.strip() if description else None,
-        permissions=validated,
-        is_builtin=False,
-        is_assignable=True,
-    )
-    session.add(role)
-    session.flush()
-    return role
-
-
-def update_system_role(
-    session: Session,
-    *,
-    role: Role,
-    name: str,
-    description: str | None,
-    permissions: Iterable[str],
-    is_assignable: bool,
-) -> None:
-    if role.tenant_id is not None:
-        raise AdminValidationError("This is not a system role.")
-    if role.slug == "system_owner":
-        raise AdminConflictError("The protected System owner role cannot be edited.")
-    try:
-        validated = validate_system_permissions(permissions)
-    except ValueError as exc:
-        raise AdminValidationError(str(exc)) from exc
-    if "system:*" in validated:
-        raise AdminValidationError("Only the protected System owner role may contain system:*.")
-    role.name = name.strip()
-    role.description = description.strip() if description else None
-    role.permissions = validated
-    role.is_assignable = is_assignable
-    role.is_builtin = False
-    session.add(role)
-    session.flush()
-
-
-def delete_system_role(session: Session, role: Role) -> None:
-    if role.tenant_id is not None:
-        raise AdminValidationError("This is not a system role.")
-    if role.slug == "system_owner":
-        raise AdminConflictError("The protected System owner role cannot be deleted.")
-    assigned = session.query(SystemRoleAssignment).filter(SystemRoleAssignment.role_id == role.id).count()
-    if assigned:
-        raise AdminConflictError("Remove all account assignments before deleting this system role.")
-    session.delete(role)
-    session.flush()
-
-
-def assert_can_delegate_system_permissions(actor_scopes: Iterable[str], permissions: Iterable[str]) -> None:
-    """Prevent a system administrator from defining stronger roles than they hold."""
-    from govoplan_core.security.permissions import delegateable_system_scopes
-
-    requested = set(validate_system_permissions(permissions))
-    if "system:*" in requested:
-        if not scopes_grant(actor_scopes, "system:*"):
-            raise AdminValidationError("Only a System owner may delegate full system access.")
-        return
-    allowed = delegateable_system_scopes(actor_scopes)
-    missing = sorted(scope for scope in requested if scope not in allowed)
-    if missing:
-        raise AdminValidationError("You cannot delegate system permissions you do not currently hold: " + ", ".join(missing))
-
-
-def assert_can_delegate_system_roles(
-    session: Session,
-    *,
-    actor_scopes: Iterable[str],
-    role_ids: Iterable[str],
-) -> None:
-    ids = sorted(set(role_ids))
-    if not ids:
-        return
-    roles = session.query(Role).filter(Role.tenant_id.is_(None), Role.id.in_(ids)).all()
-    if len(roles) != len(ids):
-        raise AdminValidationError("One or more selected system roles are invalid.")
-    for role in roles:
-        assert_can_delegate_system_permissions(actor_scopes, role.permissions or [])
-
-
-def set_system_roles(session: Session, *, account: Account, role_ids: Iterable[str]) -> None:
-    ids = sorted(set(role_ids))
-    roles = (
-        session.query(Role)
-        .filter(Role.tenant_id.is_(None), Role.id.in_(ids), Role.is_assignable.is_(True))
-        .all()
-        if ids else []
-    )
-    if len(roles) != len(ids):
-        raise AdminValidationError("One or more system roles are invalid or not assignable.")
-    for role in roles:
-        try:
-            validate_system_permissions(role.permissions or [])
-        except ValueError as exc:
-            raise AdminValidationError(str(exc)) from exc
-
-    session.query(SystemRoleAssignment).filter(SystemRoleAssignment.account_id == account.id).delete(synchronize_session=False)
-    for role in roles:
-        session.add(SystemRoleAssignment(account_id=account.id, role_id=role.id))
-    session.flush()
-    assert_system_owner_exists(session)
-
-
-def account_has_system_scope(session: Session, account: Account, required: str) -> bool:
-    roles = (
-        session.query(Role)
-        .join(SystemRoleAssignment, SystemRoleAssignment.role_id == Role.id)
-        .filter(SystemRoleAssignment.account_id == account.id, Role.tenant_id.is_(None))
-        .all()
-    )
-    return any(scopes_grant(role.permissions or [], required) for role in roles)
-
-
-def tenant_owner_user_ids(session: Session, tenant_id: str) -> set[str]:
-    """Return active tenant memberships that currently satisfy the operational-owner invariant."""
-
-    users = (
-        session.query(User)
-        .join(Account, Account.id == User.account_id)
-        .filter(
-            User.tenant_id == tenant_id,
-            User.is_active.is_(True),
-            Account.is_active.is_(True),
-        )
-        .all()
-    )
-    owner_ids: set[str] = set()
-    user_ids = [user.id for user in users]
-    if not user_ids:
-        return owner_ids
-
-    roles_by_user_id: dict[str, list[Role]] = {user_id: [] for user_id in user_ids}
-    direct_role_rows = (
-        session.query(UserRoleAssignment.user_id, Role)
-        .join(Role, UserRoleAssignment.role_id == Role.id)
-        .filter(
-            UserRoleAssignment.tenant_id == tenant_id,
-            UserRoleAssignment.user_id.in_(user_ids),
-            Role.tenant_id == tenant_id,
-        )
-        .all()
-    )
-    for user_id, role in direct_role_rows:
-        roles_by_user_id.setdefault(user_id, []).append(role)
-
-    group_role_rows = (
-        session.query(UserGroupMembership.user_id, Role)
-        .join(GroupRoleAssignment, UserGroupMembership.group_id == GroupRoleAssignment.group_id)
-        .join(Role, GroupRoleAssignment.role_id == Role.id)
-        .join(Group, Group.id == UserGroupMembership.group_id)
-        .filter(
-            UserGroupMembership.tenant_id == tenant_id,
-            UserGroupMembership.user_id.in_(user_ids),
-            Group.is_active.is_(True),
-            Role.tenant_id == tenant_id,
-        )
-        .all()
-    )
-    for user_id, role in group_role_rows:
-        roles_by_user_id.setdefault(user_id, []).append(role)
-
-    for user in users:
-        effective = [
-            scope
-            for role in roles_by_user_id.get(user.id, [])
-            for scope in (role.permissions or [])
-        ]
-        if scopes_grant(effective, "admin:roles:write") and scopes_grant(effective, "campaign:send"):
-            owner_ids.add(user.id)
-    return owner_ids
-
-
-def tenant_has_owner(session: Session, tenant_id: str) -> bool:
-    return bool(tenant_owner_user_ids(session, tenant_id))
-
-
-def assert_tenant_owner_exists(session: Session, tenant_id: str) -> None:
-    session.flush()
-    tenant = session.get(Tenant, tenant_id)
-    if tenant is not None and tenant.is_active and not tenant_has_owner(session, tenant_id):
-        raise AdminConflictError("An active tenant must retain at least one active owner or administrator with full operational access.")
-
-
-def assert_system_owner_exists(session: Session) -> None:
-    """Keep one active assignment of the protected System owner role.
-
-    Other roles may hold broad system permissions, but they are intentionally
-    not substitutes for the protected break-glass owner identity.
-    """
-    session.flush()
-    owner_role = (
-        session.query(Role)
-        .filter(Role.tenant_id.is_(None), Role.slug == "system_owner")
-        .one_or_none()
-    )
-    if owner_role is None:
-        raise AdminConflictError("The protected System owner role is missing.")
-    count = (
-        session.query(func.count(SystemRoleAssignment.id))
-        .join(Account, Account.id == SystemRoleAssignment.account_id)
-        .filter(SystemRoleAssignment.role_id == owner_role.id, Account.is_active.is_(True))
-        .scalar()
-    )
-    if not count:
-        raise AdminConflictError("At least one active account must retain the protected System owner role.")
-
-
-def role_assignment_counts(session: Session, role_id: str) -> tuple[int, int]:
-    return (
-        session.query(UserRoleAssignment).filter(UserRoleAssignment.role_id == role_id).count(),
-        session.query(GroupRoleAssignment).filter(GroupRoleAssignment.role_id == role_id).count(),
-    )
-
-
-def _optional_model(module_name: str, model_name: str):
-    try:
-        module = __import__(module_name, fromlist=[model_name])
-    except ModuleNotFoundError as exc:
-        reraise_unless_missing_package(exc, module_name.split(".", 1)[0])
-        return None
-    return getattr(module, model_name)
-
-
-def tenant_counts(session: Session, tenant_id: str) -> dict[str, int]:
-    Campaign = _optional_model("govoplan_campaign.backend.db.models", "Campaign")
-    FileAsset = _optional_model("govoplan_files.backend.db.models", "FileAsset")
-
-    return {
-        "users": session.query(User).filter(User.tenant_id == tenant_id).count(),
-        "active_users": session.query(User).filter(User.tenant_id == tenant_id, User.is_active.is_(True)).count(),
-        "groups": session.query(Group).filter(Group.tenant_id == tenant_id).count(),
-        "campaigns": session.query(Campaign).filter(Campaign.tenant_id == tenant_id).count() if Campaign is not None else 0,
-        "files": session.query(FileAsset).filter(FileAsset.tenant_id == tenant_id).count() if FileAsset is not None else 0,
-        "api_keys": session.query(ApiKey).filter(ApiKey.tenant_id == tenant_id, ApiKey.revoked_at.is_(None)).count(),
-    }
-
-
-def assert_can_delegate_tenant_permissions(actor_scopes: Iterable[str], permissions: Iterable[str]) -> None:
-    """Prevent administrators from defining or assigning roles beyond their own effective tenant powers."""
-    from govoplan_core.security.permissions import delegateable_tenant_scopes
-    requested = set(validate_tenant_permissions(permissions))
-    if "tenant:*" in requested:
-        # Only a tenant owner-equivalent can delegate the wildcard.
-        if not scopes_grant(actor_scopes, "tenant:*"):
-            raise AdminValidationError("You cannot delegate full tenant access unless you already have it.")
-        return
-    allowed = delegateable_tenant_scopes(actor_scopes)
-    missing = sorted(scope for scope in requested if scope not in allowed)
-    if missing:
-        raise AdminValidationError("You cannot delegate permissions you do not currently hold: " + ", ".join(missing))
-
-
-def assert_can_delegate_roles(session: Session, *, actor_scopes: Iterable[str], role_ids: Iterable[str], tenant_id: str) -> None:
-    ids = sorted(set(role_ids))
-    if not ids:
-        return
-    roles = session.query(Role).filter(Role.tenant_id == tenant_id, Role.id.in_(ids)).all()
-    if len(roles) != len(ids):
-        raise AdminValidationError("One or more selected roles do not belong to the tenant.")
-    for role in roles:
-        assert_can_delegate_tenant_permissions(actor_scopes, role.permissions or [])

src/govoplan_core/admin/settings.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from sqlalchemy.orm import Session
+
+from govoplan_core.admin.models import SystemSettings
+
+SYSTEM_SETTINGS_ID = "global"
+
+
+def get_system_settings(session: Session) -> SystemSettings:
+    item = session.get(SystemSettings, SYSTEM_SETTINGS_ID)
+    if item is None:
+        item = SystemSettings(id=SYSTEM_SETTINGS_ID)
+        session.add(item)
+        session.flush()
+    return item