Add an endpoint saying who a project's work may be assigned to (#373)

* Add an endpoint saying who a project's work may be assigned to

Nothing below super admin listed users, so a screen could only offer the
signed-in person to themselves. This returns the people the assignment save
accepts: on the team, active, not a service account.

An id and a display name, and nothing else. The admin team view carries an
email because an administrator auditing who can reach a team needs one; a
picker does not, and shipping it would make every project page somewhere
addresses can be collected from.

Addressed by project rather than by team, so a caller never needs a team id to
look work up by, and gated at developer to match the assignment it feeds.

The list and the write share one query. A shared condition was the first
shape, and the security review showed it compiles to a cross join when a
caller forgets to join memberships, returning every active person in the
deployment with no error and no warning. Returning the query carries the join
with it.

* Record the new route in the OpenAPI snapshot

The drift gate is a snapshot of the wire surface, so adding an endpoint has to
show as a reviewed line rather than as a passing test. One line added and
nothing else moved.

Author: haksungjang

CHANGELOG.md

@@ -9,6 +9,35 @@ and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.
 
 ### Added
 
+- **An endpoint that says who a project's work may be assigned to.** `GET
+  /v1/projects/{project_id}/assignable-members` returns the people the
+  assignment save accepts: members of the team that owns the project, active,
+  and not service accounts. Until now nothing below super admin listed users at
+  all, so a screen could only offer the signed-in person to themselves.
+
+  It returns an id and a display name, and nothing else. Not the email, which
+  the admin team view carries because an administrator auditing who can reach a
+  team needs one, and which would make every project page somewhere addresses
+  can be collected from. Not the role, which does not decide who may be named.
+  Service accounts are absent rather than labelled, because they cannot be
+  assigned, so what comes back is the set the write accepts rather than a
+  superset the caller has to filter.
+
+  Addressed by project rather than by team, so a caller never needs a team id
+  to look work up by, and gated at `developer` to match the assignment it
+  feeds: a caller who may perform an assignment has to be able to compose one.
+  A caller outside the owning team is refused by the project's own rule.
+
+  The list and the write are computed from one query. Two copies of three
+  conditions drift in a way that shows only from opposite ends: offering
+  somebody the save refuses is met immediately, and failing to offer somebody
+  it would accept is invisible, because the work goes to whoever is on the
+  list instead. A query rather than a shared condition, because a condition
+  leaves the join to the caller and a caller who forgets it gets a cross join
+  that returns every active person in the deployment, with no error and no
+  warning.
+
+
 - **The Helm chart can mount a file, so a private certificate authority works
   on Kubernetes too.** `env.extraVolumes` and `env.extraVolumeMounts` are raw
   lists appended to the backend, the scheduler and both workers, the same four

apps/backend/api/v1/projects.py

@@ -73,6 +73,7 @@
     SeveritySummary,
     SourceArchiveUploadResponse,
 )
+from schemas.vulnerability_detail import AssignableMember, AssignableMemberList
 from services.batch_service import create_projects_batch
 from services.dependency_graph_service import get_dependency_graph
 from services.project_detail_service import (
@@ -1247,6 +1248,86 @@ async def upload_source_archive_endpoint(
     )
 
 
+
+# ---------------------------------------------------------------------------
+# GET /v1/projects/{project_id}/assignable-members
+# ---------------------------------------------------------------------------
+
+
+@router.get(
+    "/{project_id}/assignable-members",
+    response_model=AssignableMemberList,
+    summary="People this project's work may be assigned to",
+    responses={
+        403: {
+            "description": (
+                "Caller is not on the team that owns the project. Matches the "
+                "project read above rather than the finding PATCH's 404: "
+                "reaching this needs a project id the caller already has."
+            )
+        },
+        404: {"description": "No such project."},
+    },
+)
+async def list_assignable_members_endpoint(
+    request: Request,
+    project_id: uuid.UUID,
+    session: AsyncSession = Depends(get_db),
+    actor: CurrentUser = Depends(require_role("developer")),
+) -> Response:
+    """Who may be named as the owner of a finding or an obligation here.
+
+    Addressed by project rather than by team because that is what a caller
+    holds: the screen is a project's finding list, and asking it for a team id
+    would mean handing out team ids to look work up by. The team is derived
+    here, and access is the project's own rule.
+
+    ``developer`` for the same reason the assignment PATCH is: a caller who may
+    perform an assignment has to be able to compose one, and a list gated
+    higher would leave the write reachable only by somebody who already knew
+    the id.
+
+    The set is exactly what ``services.assignee`` will accept, because both go
+    through one predicate rather than two copies of three conditions.
+
+    A premise that holds today and will not always
+    ---------------------------------------------
+    Deriving the team from the project is safe because reaching a project means
+    being on its team. Only ``visibility='team'`` is honoured
+    (``services.project_service``), so there is no other way in.
+
+    Organization-wide visibility would end that. Somebody on another team could
+    then read the project, and this route would hand them its members, which is
+    the enumeration the tests here refuse. Whoever enables it has to decide what
+    this endpoint does: most likely keep it on team membership rather than on
+    project access, since being allowed to read a project's findings is not the
+    same as being allowed to list the people on it.
+
+    ``core.authz.team_scope_filter`` carries a pointer back here, because that
+    is the file the change lands in.
+    """
+    from services.assignee import list_assignable_members
+
+    try:
+        project = await get_project(session, project_id=project_id, actor=actor)
+    except ProjectError as exc:
+        return _problem_for_project_error(request, exc)
+
+    rows = await list_assignable_members(session, project.team_id)
+    body = AssignableMemberList(
+        members=[
+            AssignableMember(user_id=user_id, full_name=full_name)
+            for user_id, full_name in rows
+        ],
+        total=len(rows),
+    )
+    return Response(
+        content=body.model_dump_json(),
+        status_code=status.HTTP_200_OK,
+        media_type="application/json",
+    )
+
+
 # slowapi's `@limiter.limit` wraps the endpoint with functools.wraps. The
 # wrapper inherits slowapi's module as its `__globals__`, so under
 # `from __future__ import annotations` FastAPI's `get_type_hints()` call on

apps/backend/core/authz.py

@@ -114,6 +114,13 @@ def team_scope_filter(actor: CurrentUser) -> ColumnElement[bool]:
     lives in exactly one place and a future tweak (org-wide viewer role, etc.)
     lands here only.
 
+    One caller does not go through this and would be widened by such a tweak
+    without touching it: ``GET /v1/projects/{project_id}/assignable-members``
+    derives a team from a project and lists its members, which is safe only
+    while reaching a project means being on its team. Enabling organization-wide
+    visibility makes project access a weaker statement than team membership, so
+    read that route before turning it on.
+
     Contract:
 
     - super-admin (``actor.is_superuser`` OR ``actor.role == "super_admin"``)

apps/backend/schemas/vulnerability_detail.py

@@ -880,6 +880,48 @@ class VulnerabilityDetailResponse(BaseModel):
 # ---------------------------------------------------------------------------
 
 
+class AssignableMember(BaseModel):
+    """One person who may be named as the owner of work in this project (ER65).
+
+    Two fields, and the omissions are the design. No email: the admin team view
+    carries one because an administrator auditing who can reach a team needs
+    it, and a picker does not, so a screen that only has to name colleagues
+    does not become a place addresses are collected from. No role, which does
+    not change who may be named. Service accounts are absent from the list
+    entirely rather than flagged, because they are not assignable.
+    """
+
+    user_id: uuid.UUID = Field(description="Pass this as `assignee_user_id`.")
+    full_name: str | None = Field(
+        default=None,
+        description=(
+            "Display name, or null. A name is optional at registration, so "
+            "some people have none. They are listed anyway: they are "
+            "assignable, and hiding them would make the write reachable only "
+            "by somebody who already knows the id. Render null as a "
+            "placeholder, and distinguish two of them by the id rather than "
+            "showing the same label twice."
+        ),
+    )
+
+
+class AssignableMemberList(BaseModel):
+    """The people this project's work may be assigned to."""
+
+    members: list[AssignableMember]
+    total: int = Field(
+        description=(
+            "Length of `members`. There is no paging and no cap: a team's "
+            "whole assignable membership comes back on every call. Stated "
+            "because a consumer would otherwise have to discover it. The "
+            "largest team in the reference deployment holds four people, so "
+            "this is a shape to know about rather than one to work around; a "
+            "deployment with very large teams should ask for a bound before "
+            "building on it."
+        )
+    )
+
+
 class VulnerabilityAssignmentUpdate(BaseModel):
     """PATCH body for /vulnerability_findings/{id}/assignment (ER28a).
 

apps/backend/services/assignee.py

@@ -14,12 +14,44 @@
 
 import uuid
 
-from sqlalchemy import select
+from sqlalchemy import Select, select
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from models import Membership, User
 
 
+def assignable_members_select(team_id: uuid.UUID) -> Select[tuple[uuid.UUID, str | None]]:
+    """Everyone who may be named as an owner of this team's work, as a query.
+
+    A statement rather than a bare predicate, and that is the point. The three
+    conditions live here once so the question "may this person be named?" and
+    the question "who may be named?" cannot drift; ER65 added the second caller,
+    and writing the conditions again there would have made a list that offers
+    people the write refuses, or hides people it would accept.
+
+    Returning the query carries the join with them. An earlier version exported
+    the ``and_(...)`` on its own, which compiles without complaint when a caller
+    forgets to join ``Membership``: the security review compiled
+    ``select(User.id).where(assignable_predicate(team))`` and got
+    ``FROM users, memberships``, a cross join that returns every active person
+    in the deployment rather than the team's. No error, no warning, and every
+    existing test still green, because the two call sites at the time happened
+    to write the join by hand. A helper whose reason to exist is future reuse
+    cannot rely on future callers remembering a rule its docstring states.
+
+    Callers narrow this rather than rebuild it: see the two below.
+    """
+    return (
+        select(User.id, User.full_name)
+        .join(Membership, Membership.user_id == User.id)
+        .where(
+            User.is_active.is_(True),
+            User.is_service_account.is_(False),
+            Membership.team_id == team_id,
+        )
+    )
+
+
 async def is_assignable_to_team(
     session: AsyncSession, user_id: uuid.UUID, team_id: uuid.UUID
 ) -> bool:
@@ -42,18 +74,44 @@ async def is_assignable_to_team(
     """
     member = (
         await session.execute(
-            select(User.id)
-            .join(Membership, Membership.user_id == User.id)
-            .where(
-                User.id == user_id,
-                User.is_active.is_(True),
-                User.is_service_account.is_(False),
-                Membership.team_id == team_id,
-            )
-            .limit(1)
+            assignable_members_select(team_id).where(User.id == user_id).limit(1)
         )
-    ).scalar_one_or_none()
+    ).first()
     return member is not None
 
 
-__all__ = ["is_assignable_to_team"]
+async def list_assignable_members(
+    session: AsyncSession, team_id: uuid.UUID
+) -> list[tuple[uuid.UUID, str | None]]:
+    """Everyone :func:`is_assignable_to_team` would accept for this team.
+
+    Returns ``(user_id, full_name)`` and nothing else. Not the email: the admin
+    team view carries one because an administrator auditing who can reach a
+    team needs it, and a picker does not. Not the role, which does not change
+    who may be named. Not service accounts, because they are not assignable, so
+    what comes back is exactly the set the write accepts rather than a
+    superset the caller has to filter.
+
+    ``full_name`` is nullable and optional at registration, so it can be None.
+    Dropping those people would be the same defect from the other side: they
+    are assignable, and a list that hides them makes the write reachable only
+    by somebody who already knows the id. The caller renders them.
+
+    Ordered by name so the list is stable between calls; the ones with no name
+    sort last together rather than being scattered through it.
+    """
+    rows = (
+        await session.execute(
+            assignable_members_select(team_id).order_by(
+                User.full_name.asc().nullslast(), User.id.asc()
+            )
+        )
+    ).all()
+    return [(row[0], row[1]) for row in rows]
+
+
+__all__ = [
+    "assignable_members_select",
+    "is_assignable_to_team",
+    "list_assignable_members",
+]