nat-engine 1__py3-none-any.whl

mannf/product/billing/tenant_manager.py

@@ -0,0 +1,873 @@
+# Copyright (C) 2026 Brad Guider
+# This file is part of NAT (Neural Agent Testing Framework).
+# Licensed under the AGPL-3.0. See LICENSE for details.
+
+"""Centralised tenant management service.
+
+Used by both the ``nat-admin`` CLI and the ``/api/v1/admin/tenants`` API
+endpoints.  All operations gracefully raise :class:`RuntimeError` when no
+``DATABASE_URL`` is configured.
+"""
+
+from __future__ import annotations
+
+import logging
+import uuid
+from datetime import datetime, timezone
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+# Valid plan tiers (drives quota defaults)
+_VALID_PLANS = {"free", "pro", "team", "enterprise"}
+
+
+class TenantManager:
+    """Centralised tenant management — used by both CLI and admin API."""
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _require_db():
+        """Return (engine, session_factory) or raise RuntimeError."""
+        try:
+            from mannf.product.database import (  # noqa: PLC0415
+                _async_session_factory,
+                _build_engine,
+            )
+        except ImportError as exc:
+            raise RuntimeError("Database module not available") from exc
+
+        if _build_engine() is None or _async_session_factory is None:
+            raise RuntimeError(
+                "Database not configured — set DATABASE_URL and restart."
+            )
+        return _async_session_factory
+
+    @staticmethod
+    def _tenant_to_dict(tenant_obj) -> dict:
+        return {
+            "tenant_id": str(tenant_obj.id),
+            "name": tenant_obj.name,
+            "email": tenant_obj.email,
+            "plan": tenant_obj.plan_tier,
+            "monthly_scan_quota": tenant_obj.monthly_scan_quota,
+            "monthly_security_scan_quota": tenant_obj.monthly_security_scan_quota,
+            "max_concurrent_scans": getattr(tenant_obj, "max_concurrent_scans", 1),
+            "is_active": tenant_obj.is_active,
+            "created_at": tenant_obj.created_at.isoformat() if tenant_obj.created_at else None,
+            "updated_at": tenant_obj.updated_at.isoformat() if tenant_obj.updated_at else None,
+        }
+
+    # ------------------------------------------------------------------
+    # CRUD operations
+    # ------------------------------------------------------------------
+
+    async def create_tenant(
+        self,
+        name: str,
+        email: str,
+        plan_tier: str = "free",
+    ) -> dict:
+        """Create a new tenant with a default API key.
+
+        Returns a dict with: tenant_id, name, email, plan, api_key
+        (plaintext — shown once).
+
+        Raises:
+            RuntimeError: if the database is not configured.
+            ValueError: if the plan tier is unknown.
+        """
+        if plan_tier not in _VALID_PLANS:
+            raise ValueError(
+                f"Unknown plan tier {plan_tier!r}. "
+                f"Valid tiers: {sorted(_VALID_PLANS)}"
+            )
+
+        session_factory = self._require_db()
+
+        from mannf.product.billing.plans import get_plan  # noqa: PLC0415
+        from mannf.product.billing.stripe_billing import generate_api_key  # noqa: PLC0415
+        from mannf.product.models import ApiKey, Tenant  # noqa: PLC0415
+
+        plan = get_plan(plan_tier)
+        plaintext_key, key_hash, key_prefix = generate_api_key()
+
+        async with session_factory() as session:
+            tenant = Tenant(
+                id=uuid.uuid4(),
+                name=name,
+                email=email,
+                plan_tier=plan_tier,
+                monthly_scan_quota=plan.monthly_scan_quota,
+                monthly_security_scan_quota=plan.monthly_security_scan_quota,
+                max_concurrent_scans=plan.max_concurrent_scans,
+                is_active=True,
+            )
+            session.add(tenant)
+            await session.flush()
+
+            api_key_obj = ApiKey(
+                id=uuid.uuid4(),
+                tenant_id=tenant.id,
+                key_hash=key_hash,
+                key_prefix=key_prefix,
+                label="Default",
+                is_active=True,
+            )
+            session.add(api_key_obj)
+            await session.commit()
+
+        logger.info("Created tenant %s (%s, plan=%s)", tenant.id, email, plan_tier)
+        result = self._tenant_to_dict(tenant)
+        result["api_key"] = plaintext_key
+
+        # Audit log
+        from mannf.product.billing.audit import log_billing_event  # noqa: PLC0415
+        import asyncio  # noqa: PLC0415
+        asyncio.ensure_future(log_billing_event(
+            "tenant.created",
+            tenant_id=str(tenant.id),
+            source="admin",
+            details={"name": name, "email": email, "plan_tier": plan_tier},
+        ))
+
+        return result
+
+    async def list_tenants(
+        self,
+        plan_filter: Optional[str] = None,
+        active_only: bool = True,
+        limit: int = 100,
+    ) -> list[dict]:
+        """List tenants with optional filtering.
+
+        Args:
+            plan_filter: If set, only return tenants on this plan tier.
+            active_only: If True (default), exclude deactivated tenants.
+            limit: Maximum number of results to return.
+
+        Returns:
+            List of tenant dicts (without api_key — never returned in lists).
+        """
+        session_factory = self._require_db()
+
+        from sqlalchemy import select  # noqa: PLC0415
+        from mannf.product.models import Tenant  # noqa: PLC0415
+
+        async with session_factory() as session:
+            stmt = select(Tenant).order_by(Tenant.created_at.desc()).limit(limit)
+            if active_only:
+                stmt = stmt.where(Tenant.is_active.is_(True))
+            if plan_filter is not None:
+                stmt = stmt.where(Tenant.plan_tier == plan_filter)
+            result = await session.execute(stmt)
+            tenants = result.scalars().all()
+
+        return [self._tenant_to_dict(t) for t in tenants]
+
+    async def get_tenant(self, tenant_id: str) -> Optional[dict]:
+        """Get tenant details by ID.
+
+        Returns None if not found.
+        """
+        session_factory = self._require_db()
+
+        from mannf.product.models import Tenant  # noqa: PLC0415
+
+        try:
+            tid = uuid.UUID(tenant_id)
+        except ValueError:
+            return None
+
+        async with session_factory() as session:
+            tenant = await session.get(Tenant, tid)
+
+        if tenant is None:
+            return None
+        return self._tenant_to_dict(tenant)
+
+    async def update_tenant(
+        self,
+        tenant_id: str,
+        plan_tier: Optional[str] = None,
+        monthly_scan_quota: Optional[int] = None,
+        monthly_security_scan_quota: Optional[int] = None,
+        is_active: Optional[bool] = None,
+    ) -> dict:
+        """Update tenant settings.
+
+        Returns the updated tenant dict.
+
+        Raises:
+            KeyError: if the tenant is not found.
+            ValueError: if an invalid plan tier is supplied.
+        """
+        if plan_tier is not None and plan_tier not in _VALID_PLANS:
+            raise ValueError(
+                f"Unknown plan tier {plan_tier!r}. "
+                f"Valid tiers: {sorted(_VALID_PLANS)}"
+            )
+
+        session_factory = self._require_db()
+
+        from mannf.product.billing.plans import get_plan  # noqa: PLC0415
+        from mannf.product.models import Tenant  # noqa: PLC0415
+
+        try:
+            tid = uuid.UUID(tenant_id)
+        except ValueError as exc:
+            raise KeyError(f"Tenant not found: {tenant_id!r}") from exc
+
+        async with session_factory() as session:
+            tenant = await session.get(Tenant, tid)
+            if tenant is None:
+                raise KeyError(f"Tenant not found: {tenant_id!r}")
+
+            if plan_tier is not None:
+                tenant.plan_tier = plan_tier
+                plan = get_plan(plan_tier)
+                # Only update quotas from plan defaults if not explicitly overridden
+                if monthly_scan_quota is None:
+                    tenant.monthly_scan_quota = plan.monthly_scan_quota
+                if monthly_security_scan_quota is None:
+                    tenant.monthly_security_scan_quota = plan.monthly_security_scan_quota
+                tenant.max_concurrent_scans = plan.max_concurrent_scans
+            if monthly_scan_quota is not None:
+                tenant.monthly_scan_quota = monthly_scan_quota
+            if monthly_security_scan_quota is not None:
+                tenant.monthly_security_scan_quota = monthly_security_scan_quota
+            if is_active is not None:
+                tenant.is_active = is_active
+
+            tenant.updated_at = datetime.now(timezone.utc)
+            await session.commit()
+            await session.refresh(tenant)
+
+        logger.info("Updated tenant %s", tenant_id)
+        # Audit log
+        from mannf.product.billing.audit import log_billing_event  # noqa: PLC0415
+        import asyncio  # noqa: PLC0415
+        event_type = "tenant.deactivated" if is_active is False else "tenant.updated"
+        asyncio.ensure_future(log_billing_event(
+            event_type,
+            tenant_id=tenant_id,
+            source="admin",
+            details={
+                "plan_tier": plan_tier,
+                "is_active": is_active,
+            },
+        ))
+        return self._tenant_to_dict(tenant)
+
+    async def rotate_api_key(self, tenant_id: str) -> dict:
+        """Revoke the existing API key(s) and generate a fresh one.
+
+        Returns a dict with: tenant_id, api_key (new plaintext key).
+
+        Raises:
+            KeyError: if the tenant is not found.
+        """
+        session_factory = self._require_db()
+
+        from sqlalchemy import select  # noqa: PLC0415
+        from mannf.product.billing.stripe_billing import generate_api_key  # noqa: PLC0415
+        from mannf.product.models import ApiKey, Tenant  # noqa: PLC0415
+
+        try:
+            tid = uuid.UUID(tenant_id)
+        except ValueError as exc:
+            raise KeyError(f"Tenant not found: {tenant_id!r}") from exc
+
+        plaintext_key, key_hash, key_prefix = generate_api_key()
+
+        async with session_factory() as session:
+            tenant = await session.get(Tenant, tid)
+            if tenant is None:
+                raise KeyError(f"Tenant not found: {tenant_id!r}")
+
+            # Deactivate all current keys
+            stmt = select(ApiKey).where(
+                ApiKey.tenant_id == tid,
+                ApiKey.is_active.is_(True),
+            )
+            result = await session.execute(stmt)
+            for key_obj in result.scalars().all():
+                key_obj.is_active = False
+
+            # Insert the new key
+            new_key = ApiKey(
+                id=uuid.uuid4(),
+                tenant_id=tid,
+                key_hash=key_hash,
+                key_prefix=key_prefix,
+                label="Rotated",
+                is_active=True,
+            )
+            session.add(new_key)
+            await session.commit()
+
+        logger.info("Rotated API key for tenant %s", tenant_id)
+        # Audit log
+        from mannf.product.billing.audit import log_billing_event  # noqa: PLC0415
+        import asyncio  # noqa: PLC0415
+        asyncio.ensure_future(log_billing_event(
+            "api_key.rotated",
+            tenant_id=tenant_id,
+            source="admin",
+            details={"key_prefix": key_prefix},
+        ))
+        return {"tenant_id": tenant_id, "api_key": plaintext_key}
+
+    async def deactivate_tenant(self, tenant_id: str) -> dict:
+        """Soft-delete: mark tenant as inactive and revoke all API keys.
+
+        Returns the updated tenant dict.
+
+        Raises:
+            KeyError: if the tenant is not found.
+        """
+        session_factory = self._require_db()
+
+        from sqlalchemy import select  # noqa: PLC0415
+        from mannf.product.models import ApiKey, Tenant  # noqa: PLC0415
+
+        try:
+            tid = uuid.UUID(tenant_id)
+        except ValueError as exc:
+            raise KeyError(f"Tenant not found: {tenant_id!r}") from exc
+
+        async with session_factory() as session:
+            tenant = await session.get(Tenant, tid)
+            if tenant is None:
+                raise KeyError(f"Tenant not found: {tenant_id!r}")
+
+            tenant.is_active = False
+            tenant.updated_at = datetime.now(timezone.utc)
+
+            # Revoke all active API keys
+            stmt = select(ApiKey).where(
+                ApiKey.tenant_id == tid,
+                ApiKey.is_active.is_(True),
+            )
+            result = await session.execute(stmt)
+            for key_obj in result.scalars().all():
+                key_obj.is_active = False
+
+            await session.commit()
+            await session.refresh(tenant)
+
+        logger.info("Deactivated tenant %s", tenant_id)
+        # Audit log
+        from mannf.product.billing.audit import log_billing_event  # noqa: PLC0415
+        import asyncio  # noqa: PLC0415
+        asyncio.ensure_future(log_billing_event(
+            "tenant.deactivated",
+            tenant_id=tenant_id,
+            source="admin",
+            details={},
+        ))
+        return self._tenant_to_dict(tenant)
+
+    async def get_tenant_usage(self, tenant_id: str) -> dict:
+        """Get current month's usage statistics for a tenant.
+
+        Returns a dict with: tenant_id, period, scan_count, security_scan_count,
+        monthly_scan_quota, monthly_security_scan_quota.
+
+        Raises:
+            KeyError: if the tenant is not found.
+        """
+        session_factory = self._require_db()
+
+        from sqlalchemy import func, select  # noqa: PLC0415
+        from mannf.product.models import Tenant, UsageRecord  # noqa: PLC0415
+
+        try:
+            tid = uuid.UUID(tenant_id)
+        except ValueError as exc:
+            raise KeyError(f"Tenant not found: {tenant_id!r}") from exc
+
+        now = datetime.now(timezone.utc)
+
+        async with session_factory() as session:
+            tenant = await session.get(Tenant, tid)
+            if tenant is None:
+                raise KeyError(f"Tenant not found: {tenant_id!r}")
+
+            def _count_stmt(scan_type: str):
+                return (
+                    select(func.count())
+                    .select_from(UsageRecord)
+                    .where(UsageRecord.tenant_id == tid)
+                    .where(UsageRecord.scan_type == scan_type)
+                    .where(UsageRecord.period_year == now.year)
+                    .where(UsageRecord.period_month == now.month)
+                )
+
+            scan_count = (await session.execute(_count_stmt("scan"))).scalar() or 0
+            security_count = (
+                await session.execute(_count_stmt("security_scan"))
+            ).scalar() or 0
+
+        return {
+            "tenant_id": tenant_id,
+            "period": f"{now.year}-{now.month:02d}",
+            "scan_count": scan_count,
+            "security_scan_count": security_count,
+            "monthly_scan_quota": tenant.monthly_scan_quota,
+            "monthly_security_scan_quota": tenant.monthly_security_scan_quota,
+        }
+
+    # ------------------------------------------------------------------
+    # Static dict helpers for new models
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _workspace_to_dict(ws) -> dict:
+        return {
+            "workspace_id": str(ws.id),
+            "tenant_id": str(ws.tenant_id),
+            "name": ws.name,
+            "description": ws.description,
+            "is_active": ws.is_active,
+            "created_at": ws.created_at.isoformat() if ws.created_at else None,
+            "updated_at": ws.updated_at.isoformat() if ws.updated_at else None,
+        }
+
+    @staticmethod
+    def _project_to_dict(p) -> dict:
+        return {
+            "project_id": str(p.id),
+            "workspace_id": str(p.workspace_id),
+            "tenant_id": str(p.tenant_id),
+            "name": p.name,
+            "description": p.description,
+            "parent_project_id": str(p.parent_project_id) if p.parent_project_id else None,
+            "is_active": p.is_active,
+            "created_at": p.created_at.isoformat() if p.created_at else None,
+            "updated_at": p.updated_at.isoformat() if p.updated_at else None,
+        }
+
+    @staticmethod
+    def _user_to_dict(u, role: str | None = None) -> dict:
+        return {
+            "user_id": str(u.id),
+            "tenant_id": str(u.tenant_id),
+            "email": u.email,
+            "name": u.name,
+            "sso_subject": u.sso_subject,
+            "is_active": u.is_active,
+            "role": role,
+            "created_at": u.created_at.isoformat() if u.created_at else None,
+            "updated_at": u.updated_at.isoformat() if u.updated_at else None,
+        }
+
+    # ------------------------------------------------------------------
+    # Workspace CRUD
+    # ------------------------------------------------------------------
+
+    async def create_workspace(self, tenant_id: str, name: str, description: str | None = None) -> dict:
+        """Create a workspace for a tenant."""
+        session_factory = self._require_db()
+        from mannf.product.models import Tenant, Workspace  # noqa: PLC0415
+
+        try:
+            tid = uuid.UUID(tenant_id)
+        except ValueError as exc:
+            raise KeyError(f"Tenant not found: {tenant_id!r}") from exc
+
+        async with session_factory() as session:
+            tenant = await session.get(Tenant, tid)
+            if tenant is None or not tenant.is_active:
+                raise KeyError(f"Tenant not found: {tenant_id!r}")
+
+            ws = Workspace(
+                id=uuid.uuid4(),
+                tenant_id=tid,
+                name=name,
+                description=description,
+                is_active=True,
+            )
+            session.add(ws)
+            await session.commit()
+            await session.refresh(ws)
+
+        return self._workspace_to_dict(ws)
+
+    async def list_workspaces(self, tenant_id: str) -> list[dict]:
+        """List workspaces for a tenant."""
+        session_factory = self._require_db()
+        from sqlalchemy import select  # noqa: PLC0415
+        from mannf.product.models import Workspace  # noqa: PLC0415
+
+        try:
+            tid = uuid.UUID(tenant_id)
+        except ValueError as exc:
+            raise KeyError(f"Tenant not found: {tenant_id!r}") from exc
+
+        async with session_factory() as session:
+            stmt = select(Workspace).where(
+                Workspace.tenant_id == tid,
+                Workspace.is_active.is_(True),
+            )
+            result = await session.execute(stmt)
+            workspaces = result.scalars().all()
+
+        return [self._workspace_to_dict(ws) for ws in workspaces]
+
+    async def get_workspace(self, tenant_id: str, workspace_id: str) -> dict | None:
+        """Get a workspace by ID (scoped to tenant)."""
+        session_factory = self._require_db()
+        from mannf.product.models import Workspace  # noqa: PLC0415
+
+        try:
+            tid = uuid.UUID(tenant_id)
+            wid = uuid.UUID(workspace_id)
+        except ValueError:
+            return None
+
+        async with session_factory() as session:
+            ws = await session.get(Workspace, wid)
+            if ws is None or ws.tenant_id != tid or not ws.is_active:
+                return None
+
+        return self._workspace_to_dict(ws)
+
+    async def delete_workspace(self, tenant_id: str, workspace_id: str) -> dict:
+        """Delete (deactivate) a workspace."""
+        session_factory = self._require_db()
+        from mannf.product.models import Workspace  # noqa: PLC0415
+        from datetime import datetime, timezone  # noqa: PLC0415
+
+        try:
+            tid = uuid.UUID(tenant_id)
+            wid = uuid.UUID(workspace_id)
+        except ValueError as exc:
+            raise KeyError(f"Workspace not found: {workspace_id!r}") from exc
+
+        async with session_factory() as session:
+            ws = await session.get(Workspace, wid)
+            if ws is None or ws.tenant_id != tid:
+                raise KeyError(f"Workspace not found: {workspace_id!r}")
+
+            ws.is_active = False
+            ws.updated_at = datetime.now(timezone.utc)
+            await session.commit()
+            await session.refresh(ws)
+
+        return self._workspace_to_dict(ws)
+
+    # ------------------------------------------------------------------
+    # Project CRUD
+    # ------------------------------------------------------------------
+
+    async def create_project(
+        self,
+        tenant_id: str,
+        workspace_id: str,
+        name: str,
+        description: str | None = None,
+        parent_project_id: str | None = None,
+    ) -> dict:
+        """Create a project in a workspace."""
+        session_factory = self._require_db()
+        from mannf.product.models import Project, Workspace  # noqa: PLC0415
+
+        try:
+            tid = uuid.UUID(tenant_id)
+            wid = uuid.UUID(workspace_id)
+        except ValueError as exc:
+            raise KeyError(f"Workspace not found: {workspace_id!r}") from exc
+
+        parent_uuid: Optional[uuid.UUID] = None
+        if parent_project_id:
+            try:
+                parent_uuid = uuid.UUID(parent_project_id)
+            except ValueError as exc:
+                raise ValueError(f"Invalid parent_project_id: {parent_project_id!r}") from exc
+
+        async with session_factory() as session:
+            ws = await session.get(Workspace, wid)
+            if ws is None or ws.tenant_id != tid or not ws.is_active:
+                raise KeyError(f"Workspace not found: {workspace_id!r}")
+
+            proj = Project(
+                id=uuid.uuid4(),
+                workspace_id=wid,
+                tenant_id=tid,
+                name=name,
+                description=description,
+                parent_project_id=parent_uuid,
+                is_active=True,
+            )
+            session.add(proj)
+            await session.commit()
+            await session.refresh(proj)
+
+        return self._project_to_dict(proj)
+
+    async def list_projects(self, tenant_id: str, workspace_id: str) -> list[dict]:
+        """List projects in a workspace (tenant-scoped)."""
+        session_factory = self._require_db()
+        from sqlalchemy import select  # noqa: PLC0415
+        from mannf.product.models import Project  # noqa: PLC0415
+
+        try:
+            tid = uuid.UUID(tenant_id)
+            wid = uuid.UUID(workspace_id)
+        except ValueError as exc:
+            raise KeyError(f"Workspace not found: {workspace_id!r}") from exc
+
+        async with session_factory() as session:
+            stmt = select(Project).where(
+                Project.workspace_id == wid,
+                Project.tenant_id == tid,
+                Project.is_active.is_(True),
+            )
+            result = await session.execute(stmt)
+            projects = result.scalars().all()
+
+        return [self._project_to_dict(p) for p in projects]
+
+    async def get_project(self, tenant_id: str, project_id: str) -> dict | None:
+        """Get a project by ID (scoped to tenant)."""
+        session_factory = self._require_db()
+        from mannf.product.models import Project  # noqa: PLC0415
+
+        try:
+            tid = uuid.UUID(tenant_id)
+            pid = uuid.UUID(project_id)
+        except ValueError:
+            return None
+
+        async with session_factory() as session:
+            proj = await session.get(Project, pid)
+            if proj is None or proj.tenant_id != tid or not proj.is_active:
+                return None
+
+        return self._project_to_dict(proj)
+
+    async def delete_project(self, tenant_id: str, project_id: str) -> dict:
+        """Delete (deactivate) a project."""
+        session_factory = self._require_db()
+        from mannf.product.models import Project  # noqa: PLC0415
+        from datetime import datetime, timezone  # noqa: PLC0415
+
+        try:
+            tid = uuid.UUID(tenant_id)
+            pid = uuid.UUID(project_id)
+        except ValueError as exc:
+            raise KeyError(f"Project not found: {project_id!r}") from exc
+
+        async with session_factory() as session:
+            proj = await session.get(Project, pid)
+            if proj is None or proj.tenant_id != tid:
+                raise KeyError(f"Project not found: {project_id!r}")
+
+            proj.is_active = False
+            proj.updated_at = datetime.now(timezone.utc)
+            await session.commit()
+            await session.refresh(proj)
+
+        return self._project_to_dict(proj)
+
+    # ------------------------------------------------------------------
+    # User management
+    # ------------------------------------------------------------------
+
+    async def invite_user(self, tenant_id: str, email: str, name: str, role: str = "viewer") -> dict:
+        """Create a user record (invite). Enforces seat limit."""
+        session_factory = self._require_db()
+        from sqlalchemy import func, select  # noqa: PLC0415
+        from mannf.product.models import Tenant, User, UserRole  # noqa: PLC0415
+        from mannf.product.billing.plans import get_plan  # noqa: PLC0415
+
+        try:
+            tid = uuid.UUID(tenant_id)
+        except ValueError as exc:
+            raise KeyError(f"Tenant not found: {tenant_id!r}") from exc
+
+        async with session_factory() as session:
+            tenant = await session.get(Tenant, tid)
+            if tenant is None or not tenant.is_active:
+                raise KeyError(f"Tenant not found: {tenant_id!r}")
+
+            plan = get_plan(tenant.plan_tier)
+            max_seats = getattr(plan, "max_seats", 0)
+
+            if max_seats > 0:
+                count_stmt = select(func.count()).select_from(User).where(
+                    User.tenant_id == tid,
+                    User.is_active.is_(True),
+                )
+                current_count = (await session.execute(count_stmt)).scalar() or 0
+                if current_count >= max_seats:
+                    raise ValueError(
+                        f"SEAT_LIMIT_EXCEEDED: plan {tenant.plan_tier!r} allows {max_seats} seat(s), "
+                        f"currently {current_count} active user(s)."
+                    )
+
+            user_obj = User(
+                id=uuid.uuid4(),
+                tenant_id=tid,
+                email=email,
+                name=name,
+                sso_subject=None,
+                is_active=True,
+            )
+            session.add(user_obj)
+            await session.flush()
+
+            role_obj = UserRole(
+                id=uuid.uuid4(),
+                user_id=user_obj.id,
+                tenant_id=tid,
+                workspace_id=None,
+                role=role,
+            )
+            session.add(role_obj)
+            await session.commit()
+            await session.refresh(user_obj)
+
+        return self._user_to_dict(user_obj, role=role)
+
+    async def list_users(self, tenant_id: str) -> list[dict]:
+        """List users in a tenant."""
+        session_factory = self._require_db()
+        from sqlalchemy import select  # noqa: PLC0415
+        from mannf.product.models import User, UserRole  # noqa: PLC0415
+
+        try:
+            tid = uuid.UUID(tenant_id)
+        except ValueError as exc:
+            raise KeyError(f"Tenant not found: {tenant_id!r}") from exc
+
+        async with session_factory() as session:
+            stmt = select(User).where(
+                User.tenant_id == tid,
+                User.is_active.is_(True),
+            )
+            result = await session.execute(stmt)
+            users = result.scalars().all()
+
+            out = []
+            for u in users:
+                role_stmt = select(UserRole).where(
+                    UserRole.user_id == u.id,
+                    UserRole.tenant_id == tid,
+                    UserRole.workspace_id.is_(None),
+                )
+                role_result = await session.execute(role_stmt)
+                role_obj = role_result.scalars().first()
+                out.append(self._user_to_dict(u, role=role_obj.role if role_obj else None))
+
+        return out
+
+    async def get_user(self, tenant_id: str, user_id: str) -> dict | None:
+        """Get a user by ID (scoped to tenant)."""
+        session_factory = self._require_db()
+        from sqlalchemy import select  # noqa: PLC0415
+        from mannf.product.models import User, UserRole  # noqa: PLC0415
+
+        try:
+            tid = uuid.UUID(tenant_id)
+            uid = uuid.UUID(user_id)
+        except ValueError:
+            return None
+
+        async with session_factory() as session:
+            user_obj = await session.get(User, uid)
+            if user_obj is None or user_obj.tenant_id != tid or not user_obj.is_active:
+                return None
+
+            role_stmt = select(UserRole).where(
+                UserRole.user_id == uid,
+                UserRole.tenant_id == tid,
+                UserRole.workspace_id.is_(None),
+            )
+            role_result = await session.execute(role_stmt)
+            role_obj = role_result.scalars().first()
+
+        return self._user_to_dict(user_obj, role=role_obj.role if role_obj else None)
+
+    async def assign_role(
+        self,
+        tenant_id: str,
+        user_id: str,
+        role: str,
+        workspace_id: str | None = None,
+    ) -> dict:
+        """Assign or update a user's role (tenant-wide or workspace-scoped)."""
+        session_factory = self._require_db()
+        from sqlalchemy import select  # noqa: PLC0415
+        from mannf.product.models import User, UserRole  # noqa: PLC0415
+
+        try:
+            tid = uuid.UUID(tenant_id)
+            uid = uuid.UUID(user_id)
+        except ValueError as exc:
+            raise KeyError(f"User not found: {user_id!r}") from exc
+
+        wid: Optional[uuid.UUID] = None
+        if workspace_id:
+            try:
+                wid = uuid.UUID(workspace_id)
+            except ValueError as exc:
+                raise ValueError(f"Invalid workspace_id: {workspace_id!r}") from exc
+
+        async with session_factory() as session:
+            user_obj = await session.get(User, uid)
+            if user_obj is None or user_obj.tenant_id != tid:
+                raise KeyError(f"User not found: {user_id!r}")
+
+            role_stmt = select(UserRole).where(
+                UserRole.user_id == uid,
+                UserRole.tenant_id == tid,
+                UserRole.workspace_id == wid if wid else UserRole.workspace_id.is_(None),
+            )
+            role_result = await session.execute(role_stmt)
+            role_obj = role_result.scalars().first()
+
+            if role_obj is None:
+                role_obj = UserRole(
+                    id=uuid.uuid4(),
+                    user_id=uid,
+                    tenant_id=tid,
+                    workspace_id=wid,
+                    role=role,
+                )
+                session.add(role_obj)
+            else:
+                role_obj.role = role
+
+            await session.commit()
+            await session.refresh(user_obj)
+
+        return self._user_to_dict(user_obj, role=role)
+
+    async def remove_user(self, tenant_id: str, user_id: str) -> dict:
+        """Deactivate a user."""
+        session_factory = self._require_db()
+        from mannf.product.models import User  # noqa: PLC0415
+        from datetime import datetime, timezone  # noqa: PLC0415
+
+        try:
+            tid = uuid.UUID(tenant_id)
+            uid = uuid.UUID(user_id)
+        except ValueError as exc:
+            raise KeyError(f"User not found: {user_id!r}") from exc
+
+        async with session_factory() as session:
+            user_obj = await session.get(User, uid)
+            if user_obj is None or user_obj.tenant_id != tid:
+                raise KeyError(f"User not found: {user_id!r}")
+
+            user_obj.is_active = False
+            user_obj.updated_at = datetime.now(timezone.utc)
+            await session.commit()
+            await session.refresh(user_obj)
+
+        return self._user_to_dict(user_obj)