Project category

mpcontribs-api/src/mpcontribs_api/api/v1/router.py

@@ -2,7 +2,9 @@
 
 from mpcontribs_api.domains.attachments.router import router as attachments_router
 from mpcontribs_api.domains.contributions.router import router as contributions_router
+from mpcontribs_api.domains.initiatives.router import router as initiatives_router
 from mpcontribs_api.domains.limits.router import router as limits_router
+from mpcontribs_api.domains.project_groups.router import router as project_groups_router
 from mpcontribs_api.domains.projects.router import router as projects_router
 from mpcontribs_api.domains.structures.router import router as structures_router
 from mpcontribs_api.domains.tables.router import router as tables_router
@@ -11,7 +13,9 @@
 
 router.include_router(attachments_router, prefix="/attachments", tags=["attachments"])
 router.include_router(contributions_router, prefix="/contributions", tags=["contributions"])
+router.include_router(initiatives_router, prefix="/initiatives", tags=["initiatives"])
 router.include_router(limits_router, prefix="/limits", tags=["limits"])
+router.include_router(project_groups_router, prefix="/project_groups", tags=["project_groups"])
 router.include_router(projects_router, prefix="/projects", tags=["projects"])
 router.include_router(structures_router, prefix="/structures", tags=["structures"])
 router.include_router(tables_router, prefix="/tables", tags=["tables"])

mpcontribs-api/src/mpcontribs_api/app.py

@@ -21,6 +21,8 @@
 from mpcontribs_api.domains.attachments.models import Attachment
 from mpcontribs_api.domains.contributions.models import Contribution
 from mpcontribs_api.domains.healthcheck.router import router as healthcheck_router
+from mpcontribs_api.domains.initiatives.models import Initiative
+from mpcontribs_api.domains.project_groups.models import ProjectGroup
 from mpcontribs_api.domains.projects.models import Project
 from mpcontribs_api.domains.structures.models import Structure
 from mpcontribs_api.domains.tables.models import Table
@@ -63,6 +65,8 @@ async def _setup_mongo(app: FastAPI, settings: Settings, stack: AsyncExitStack)
         database=client[settings.mongo.db_name],
         document_models=[
             Project,
+            ProjectGroup,
+            Initiative,
             Contribution,
             Attachment,
             Structure,

mpcontribs-api/src/mpcontribs_api/authz.py

@@ -33,6 +33,16 @@
 
 ADMIN_GROUP = settings.mongo.admin_group
 
+# prefix to user roles to disambiguate from project roles, which are bare ids
+INITIATIVE_ROLE_PREFIX = "initiative:"
+
+# prefix for project-group roles: a group's _id (an ObjectId hex string) is granted as ``project-group:<oid>``
+PROJECT_GROUP_ROLE_PREFIX = "project-group:"
+
+# A role carrying one of these prefixes is scoped to a non-project resource; a role with none of
+# them is a bare project id.
+_RESOURCE_ROLE_PREFIXES = (INITIATIVE_ROLE_PREFIX, PROJECT_GROUP_ROLE_PREFIX)
+
 
 class User(BaseModel):
     """User definition derived from request headers.
@@ -64,16 +74,59 @@ def is_anonymous(self) -> bool:
     def is_admin(self) -> bool:
         return (not self.is_anonymous) and (ADMIN_GROUP in self.groups)
 
-    def has_role(self, role: str) -> bool:
+    @property
+    def project_roles(self) -> list[str]:
+        """The project ids this user carries, from their bare (unprefixed) roles.
+
+        Resource-scoped roles (``initiative:``, ``project-group:``) and the admin sentinel are
+        excluded, leaving only bare project ids.
+        """
+        return [role for role in self.groups if role != ADMIN_GROUP and not role.startswith(_RESOURCE_ROLE_PREFIXES)]
+
+    @property
+    def initiative_roles(self) -> list[str]:
+        """The initiative slugs this user collaborates on, decoded from their ``initiative:<slug>`` roles."""
+        return [role[len(INITIATIVE_ROLE_PREFIX) :] for role in self.groups if role.startswith(INITIATIVE_ROLE_PREFIX)]
+
+    @property
+    def project_group_roles(self) -> list[str]:
+        """The project-group ids this user may access, decoded from their ``project-group:<oid>`` roles.
+
+        Values are the raw hex strings; callers that query by ``_id`` must convert them
+        """
+        return [
+            role[len(PROJECT_GROUP_ROLE_PREFIX) :] for role in self.groups if role.startswith(PROJECT_GROUP_ROLE_PREFIX)
+        ]
+
+    def has_role(self, role: str, *, resource: str | None = None) -> bool:
+        """Determine whether a user has a role assigned to them.
+
+        Specifying resource as:
+        - ``INITIATIVE_ROLE_PREFIX`` looks for roles scoped to initiatives
+        - "project" looks for bare (unprefixed) project roles
+        - None looks for roles by matching the entire string
+        """
+        if resource == INITIATIVE_ROLE_PREFIX[:-1]:
+            return role in self.initiative_roles
+        if resource == "project":
+            return role in self.project_roles
         return role in self.groups
 
     @property
     def writable_projects(self) -> frozenset[str]:
         """Projects this user may write to. Admins are unbounded (handled by can_write)"""
         if self.is_anonymous:
             return frozenset()
-        # exclude the admin sentinel so it never leaks into a $in / membership test
-        return frozenset(g for g in self.groups if g != ADMIN_GROUP)
+        # only bare project roles are writable projects; the admin sentinel and resource-scoped
+        # roles (initiative:/project-group:) must never leak into a $in / membership test
+        return frozenset(self.project_roles)
+
+    def can_manage(self, id: str, resource: str) -> bool:
+        """Determines whether a user can manage a resource.
+
+        If the user is known and either an admin or has a valid role assigned, they can manage
+        """
+        return (not self.is_anonymous) and (self.is_admin or self.has_role(role=id, resource=resource))
 
     def can_write(self, project: str) -> bool:
         """Single source of truth for write authorization."""

mpcontribs-api/src/mpcontribs_api/config.py

@@ -157,6 +157,26 @@ def _clamp_concurrency(self):
         return self
 
 
+class InitiativeSettings(BaseModel):
+    """Limits governing user-owned initiatives."""
+
+    max_unapproved_per_owner: int = Field(
+        default=3,
+        description="Maximum number of unapproved initiatives a single owner may have at once. Enforced on create.",
+    )
+    max_projects_per_unapproved: int = Field(
+        default=2,
+        description="Maximum number of projects that may be assigned to an unapproved initiative. Enforced when a "
+        "project's initiative is set via PATCH.",
+    )
+
+
+class DomainSettings(BaseModel):
+    """Settings to configure the domain logic of MPContribs"""
+
+    initiatives: InitiativeSettings = Field(default_factory=InitiativeSettings)
+
+
 class Settings(BaseSettings):
     model_config = SettingsConfigDict(
         env_file=".env",
@@ -179,6 +199,9 @@ class Settings(BaseSettings):
     # MPContribs_otel__*
     otel: ObservabilitySettings = Field(default_factory=ObservabilitySettings)
 
+    # MPContribs_domain_*
+    domain: DomainSettings = Field(default_factory=DomainSettings)
+
     # SMTP Settings
     mail_default_sender: str = Field(
         description="SMTP Server to send out notifications on new projects and other important moments"

mpcontribs-api/src/mpcontribs_api/dependencies.py

@@ -8,7 +8,7 @@
 from types_aiobotocore_s3 import S3Client
 
 from mpcontribs_api.authz import User
-from mpcontribs_api.exceptions import AuthenticationError
+from mpcontribs_api.exceptions import AuthenticationError, PermissionError
 
 
 def get_db(request: Request) -> AsyncDatabase:
@@ -72,3 +72,15 @@ def require_user(user: UserDep) -> User:
         raise AuthenticationError("authentication required")
     return user
 
+
+def require_writer(user: UserDep) -> User:
+    """Require an authenticated caller who can write to at least one project.
+
+    Controls access to creating components if you do not have contributions to attach them to.
+    Helps to limit orphanned components
+    """
+    if user.is_anonymous:
+        raise AuthenticationError("authentication required")
+    if not (user.is_admin or user.writable_projects):
+        raise PermissionError("write access to at least one project is required")
+    return user

mpcontribs-api/src/mpcontribs_api/domains/_shared/filters.py

@@ -2,6 +2,11 @@
 from typing import Any
 
 from fastapi_filter.contrib.beanie import Filter
+from fastapi_filter.contrib.beanie.filter import _odm_operator_transformer
+from pydantic import ValidationInfo, field_validator
+
+# Register a custom __contains filter suffix to search where lists are a superset of a provided list
+_odm_operator_transformer.setdefault("contains", lambda value: {"$all": value})
 
 
 class BaseFilter(Filter):
@@ -16,6 +21,20 @@ class BaseFilter(Filter):
     Domain filters should subclass this instead of fastapi-filter's ``Filter`` directly.
     """
 
+    @field_validator("*", mode="before")
+    @classmethod
+    def _split_contains(cls, value: str | None, field: ValidationInfo) -> list[str] | str | None:
+        """Split a comma-separated ``__contains`` query string into a list.
+
+        ``FilterDepends`` collapses list-typed filter fields to a single string query param and
+        relies on a before-validator to re-expand it. fastapi-filter only does this for ``__in``
+        and ``__nin``; mirror it here for the ``contains`` operator so ``?tags__contains=a,c``
+        parses into ``["a", "c"]``.
+        """
+        if field.field_name is not None and field.field_name.endswith("__contains") and isinstance(value, str):
+            return value.split(",") if value else []
+        return value
+
     def _get_filter_conditions(self, nesting_depth: int = 1) -> list[tuple[Mapping[str, Any], Mapping[str, Any]]]:
         return [
             ({"_id" if key == "id" else key: value for key, value in condition.items()}, options)

mpcontribs-api/src/mpcontribs_api/domains/_shared/models.py

@@ -5,7 +5,7 @@
 from typing import Annotated, Any, ClassVar, Self
 
 from beanie import Document, PydanticObjectId
-from pydantic import BaseModel, Field, model_validator
+from pydantic import BaseModel, ConfigDict, Field, model_validator
 from pymongo.results import DeleteResult
 
 from mpcontribs_api import pagination
@@ -27,6 +27,22 @@ class BaseDocumentWithInput[TId](Document):
     # Required, non-null, resource-specific id. Overrides Document's optional ``PydanticObjectId`` id.
     id: TId = Field(alias="_id")  # pyright: ignore[reportGeneralTypeIssues, reportIncompatibleVariableOverride]
 
+    @classmethod
+    def identifier_fields(cls) -> frozenset[str]:
+        """Field names that uniquely identify a document in this collection.
+
+        This is the natural/unique key a caller can supply without first knowing the Mongo ``_id``
+        (e.g. ``{"name", "owner"}`` for a project group). The repository pairs these names with
+        caller-supplied values to locate a single resource, and rejects any value dict whose keys
+        don't match this set. Defaults to the primary key; subclasses with a meaningful compound key
+        override it.
+        """
+        return frozenset({"id"})
+
+    def identifiers(self) -> dict[str, Any]:
+        """This document's identifier field values, keyed by :meth:`identifier_fields`."""
+        return {field: getattr(self, field) for field in self.identifier_fields()}
+
     @classmethod
     def from_input_model(cls, data: Any) -> Self:
         """Translate a validated input payload into a full stored document."""
@@ -43,8 +59,10 @@ class DocumentOut[TId](SparseFieldsModel):
 
     Mirrors :class:`BaseDocumentWithInput`: subclasses bind their id type as ``TId`` so each resource
     owns its id type, while the field (optional, since projections may omit it) and its alias wiring
-    are declared once here for the repository to read off any resource's output model.
-    """
+    are declared once here for the repository to read off any resource's output model."""
+
+    # lets POST/PUT responses correctly bring ``_id`` into ``id``, without it ``id`` ends up as None
+    model_config = ConfigDict(populate_by_name=True)
 
     id: Annotated[TId | None, Field(alias="_id", serialization_alias="id")] = None