trueppm-api 0.4.0__py3-none-any.whl

trueppm_api/apps/access/signals.py

@@ -0,0 +1,171 @@
+"""Signals for the access app — real-time eviction on membership revocation (#813).
+
+The project WebSocket consumer checks ``ProjectMembership`` only at
+``websocket_connect``. Once accepted, a socket keeps receiving project events until it
+disconnects, so a user whose membership is soft-deleted or demoted below ``Role.MEMBER``
+would keep receiving real-time CPM/task/presence data for as long as the socket stayed
+open — the active-connection analog of #419 (which fixed the reconnect-time path).
+
+These signals detect a revocation transition on any ``ProjectMembership`` write — the
+viewset, the ownership-transfer service, and the workspace Group→project cascade all go
+through ``save()``/``delete()`` — and push a ``connection.evict`` to the project's WS
+groups so the affected user's live sockets close with code 4003 immediately.
+
+**Account deactivation is a second, independent revocation axis (#2850).** Workspace
+off-boarding writes ``WorkspaceMembership.status = DEACTIVATED`` and
+``User.is_active = False`` and **never touches ``ProjectMembership``**, so the
+membership receivers below never fired for it. Two prior fixes each closed one axis
+and neither closed the intersection: #813 closed revoke-while-connected for *project
+membership*, #888 closed the ``is_active`` gap at *connect time* — leaving an
+off-boarded member's already-open socket streaming until they closed the tab.
+
+The account-level receiver is bound to ``User`` rather than added as two calls in the
+off-boarding view precisely because that is what makes it cover the *class*: both
+off-boarding branches, the Django admin, a management command, and any future
+deactivation path all go through ``User.save()``.
+"""
+
+from __future__ import annotations
+
+from functools import partial
+from typing import Any
+
+from django.conf import settings
+from django.db import transaction
+from django.db.models.signals import post_delete, pre_save
+from django.dispatch import receiver
+
+from trueppm_api.apps.access.models import ProjectMembership, Role
+from trueppm_api.apps.access.permissions import role_can_subscribe_live
+from trueppm_api.apps.sync.broadcast import evict_project_connection
+
+
+def _schedule_evict(project_id: Any, user_id: Any) -> None:
+    """Defer the evict to commit so a rolled-back revocation evicts nobody."""
+    transaction.on_commit(partial(evict_project_connection, str(project_id), str(user_id)))
+
+
+def evict_all_live_project_sockets(user_id: Any) -> None:
+    """Schedule an evict for every project ``user_id`` holds a live membership in.
+
+    Shared by :func:`_evict_on_account_deactivation` and the password-reset confirm
+    view (#4462) — both revoke all of a user's standing authority in one stroke and
+    must close the same set of sockets a membership-by-membership revoke would
+    eventually reach. Live memberships only: a soft-deleted one already evicted via
+    :func:`_evict_on_revocation`, and the consumer would refuse the reconnect anyway.
+    """
+    project_ids = ProjectMembership.objects.filter(user_id=user_id, is_deleted=False).values_list(
+        "project_id", flat=True
+    )
+    for project_id in project_ids:
+        _schedule_evict(project_id, user_id)
+
+
+def _discard_active_timers_on_revocation(project_id: Any, user_id: Any) -> None:
+    """Delete the user's running timer(s) on this project's tasks (#4318).
+
+    **Discard, not finalize — the settled choice for #4318.** A member whose
+    ``ProjectMembership`` is revoked (removed, or demoted below ``Role.MEMBER``, so
+    ``can_log_time`` would now answer ``False``) can still have a live
+    ``ActiveTimer`` row ticking. Two options existed: auto-finalize it into a
+    ``TimeEntry`` at the moment of revocation, or drop it with no entry created.
+    Discard was chosen — auto-finalizing would silently attribute logged hours to a
+    project the user no longer belongs to, and the resulting entry would outlive
+    the membership that was supposed to authorize it. A dropped timer is simply
+    gone; a subsequent ``POST /me/timer/stop`` finds no row and answers the
+    existing ``409`` ("no active timer to stop"), not a new error shape.
+
+    Synchronous, inside the caller's transaction — unlike ``_schedule_evict``, this
+    is a same-database write with no external side effect, so it naturally rolls
+    back together with the membership change on a failed transaction; deferring it
+    to commit would buy nothing and would let a stopped-in-between request race the
+    delete.
+
+    Scoped to ``project_id`` (not every project the user belongs to): a revocation
+    on one project must not touch a running timer on another project the user is
+    still a live member of.
+    """
+    from trueppm_api.apps.timetracking.models import ActiveTimer
+
+    ActiveTimer.objects.filter(user_id=user_id, task__project_id=project_id).delete()
+
+
+@receiver(pre_save, sender=ProjectMembership, dispatch_uid="access_evict_on_membership_revocation")
+def _evict_on_revocation(sender: type, instance: ProjectMembership, **kwargs: Any) -> None:
+    """Evict live sockets and discard running timers when a membership is revoked.
+
+    Two independent checks, both also triggered by a soft-delete. Eviction fires
+    when the role stops clearing ``role_can_subscribe_live`` (the socket's own
+    connect floor, #4375). Timer discard fires on a demotion across the Member
+    time-logging floor. The two floors coincide today (Member), so e.g.
+    Admin -> Viewer triggers both and Admin -> Member triggers neither, but they
+    are separate rules and moving one must not move the other. See
+    :func:`_discard_active_timers_on_revocation` for why the timer is discarded
+    rather than finalized (#4318).
+    """
+    if instance.pk is None:
+        return  # brand-new membership — nothing to revoke
+    old = ProjectMembership.objects.filter(pk=instance.pk).only("role", "is_deleted").first()
+    if old is None:
+        return
+    became_deleted = not old.is_deleted and instance.is_deleted
+    # Eviction keys on the socket's OWN floor — the predicate the consumer's connect
+    # gate calls — so a socket is evicted exactly when a fresh connect would be
+    # refused, wherever that floor sits (#4375). An inline ordinal comparison here
+    # would drift silently if the floor moved.
+    lost_live_updates = role_can_subscribe_live(old.role) and not role_can_subscribe_live(
+        instance.role
+    )
+    if became_deleted or lost_live_updates:
+        _schedule_evict(instance.project_id, instance.user_id)
+    # Timers follow the time-logging floor (Member), a different rule that happens to
+    # share today's ordinal; keep it separate so moving one floor does not move the
+    # other. A demotion that stays at or above Member keeps the user able to log time.
+    demoted_below_member = old.role >= Role.MEMBER and instance.role < Role.MEMBER
+    if became_deleted or demoted_below_member:
+        _discard_active_timers_on_revocation(instance.project_id, instance.user_id)
+
+
+@receiver(
+    post_delete, sender=ProjectMembership, dispatch_uid="access_evict_on_membership_hard_delete"
+)
+def _evict_on_hard_delete(sender: type, instance: ProjectMembership, **kwargs: Any) -> None:
+    """Evict live sockets and discard running timers if a membership row is hard-deleted.
+
+    Cascade / admin only — the viewset's own removal path soft-deletes (see
+    :func:`_evict_on_revocation`). A cascaded *project* delete already removes any
+    ``ActiveTimer`` transitively (``Task`` -> ``Project`` is ``CASCADE``), so this
+    mainly covers a direct admin hard-delete of just the membership row, where the
+    project and its tasks are untouched (#4318).
+    """
+    _schedule_evict(instance.project_id, instance.user_id)
+    _discard_active_timers_on_revocation(instance.project_id, instance.user_id)
+
+
+@receiver(pre_save, sender=settings.AUTH_USER_MODEL, dispatch_uid="access_evict_on_deactivation")
+def _evict_on_account_deactivation(sender: type, instance: Any, **kwargs: Any) -> None:
+    """Evict every live project socket when an account is deactivated (#2850).
+
+    Authorization on both consumers runs exactly once, at connect, and ``is_active``
+    is read only there (``sync/ws_auth.py:_resolve_active_user``). So an off-boarded
+    member's open socket kept streaming ``task_created`` / ``task_dates_updated`` /
+    presence for the whole session — while their REST access died immediately,
+    because the JWT authenticator does honor ``is_active``.
+
+    Fires on the ``True -> False`` transition only. Reactivation grants nothing that
+    needs evicting, and firing on every ``User.save()`` would push an evict message
+    per project on unrelated profile edits.
+
+    Deferred to commit through ``_schedule_evict``, so a rolled-back deactivation
+    evicts nobody — the same contract the membership receivers above use.
+    """
+    if instance.pk is None:
+        return  # new account — nothing connected under it yet
+    if instance.is_active:
+        return  # not a deactivation; reactivation needs no evict
+    model = type(instance)
+    was_active = model.objects.filter(pk=instance.pk).values_list("is_active", flat=True).first()
+    if not was_active:
+        return  # already inactive — an unrelated save, not the transition
+
+    evict_all_live_project_sockets(instance.pk)

trueppm_api/apps/access/tasks.py

@@ -0,0 +1,50 @@
+"""Celery tasks for the access app — JWT blacklist maintenance (#910)."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from django.apps import apps as django_apps
+from django.core.management import call_command
+from django.db import OperationalError
+
+from trueppm_api.core.idempotent import idempotent_task
+
+logger = logging.getLogger(__name__)
+
+_BLACKLIST_APP = "rest_framework_simplejwt.token_blacklist"
+
+
+@idempotent_task(
+    lock_key_template="flush_expired_blacklisted_tokens",
+    lock_ttl=300,
+    on_contention="skip",
+    name="access.flush_expired_blacklisted_tokens",
+    autoretry_for=(ConnectionError, OperationalError),
+    retry_backoff=60,
+    retry_backoff_max=600,
+    retry_jitter=True,
+    max_retries=3,
+    soft_time_limit=120,
+    time_limit=180,
+    acks_late=True,
+)
+def flush_expired_blacklisted_tokens(self: object) -> dict[str, Any]:
+    """Delete OutstandingToken/BlacklistedToken rows whose tokens have expired.
+
+    Registered in CELERY_BEAT_SCHEDULE to run nightly. Without it the blacklist
+    tables grow by one OutstandingToken per login for the life of the deployment;
+    flushing expired rows bounds them to roughly the active-session window.
+
+    Wraps simplejwt's ``flushexpiredtokens`` management command. No-ops when the
+    ``token_blacklist`` app is not installed (the lean-OSS opt-out described in
+    settings.SIMPLE_JWT) so the beat schedule entry is safe to ship unconditionally.
+    """
+    if not django_apps.is_installed(_BLACKLIST_APP):
+        logger.info("flush_expired_blacklisted_tokens: token_blacklist not installed, skipping")
+        return {"status": "skipped", "reason": "token_blacklist app not installed"}
+
+    call_command("flushexpiredtokens")
+    logger.info("flush_expired_blacklisted_tokens: flushed expired blacklist rows")
+    return {"status": "ok"}

trueppm_api/apps/access/throttles.py

@@ -0,0 +1,96 @@
+"""Per-token rate limits for the MCP read surface (ADR-0186, #1808 finding F4).
+
+Every view mixing in
+:class:`~trueppm_api.apps.access.permissions.McpReadableViewMixin` is additively
+reachable by a personal ``mcp:read`` API token. Those token-authenticated reads
+had no rate bound: an agent retry loop — or a hostile client holding a leaked
+read-only token — could hammer the surface, and the compute-heavy tools
+(``whatif``, ``monte-carlo/latest``, ``forecast``, ``sprint-forecast``) each
+trigger a CPM + Monte Carlo recompute per call, so an unbounded loop burns
+arbitrary CPU on a read-only credential.
+
+Two throttles bound the *token* caller only. :meth:`get_cache_key` returns
+``None`` for any non-token (human JWT/Session) request, which DRF treats as "not
+throttled" — so interactive human traffic on the same views is unaffected
+(#1808 scope: do not throttle human/session traffic). This is the OSS seed of the
+Phase-4 per-agent budget work; per-agent budgets and anomaly auto-suspend remain
+Enterprise.
+
+Keyed on the token's own id (not the owner user) so each minted token carries its
+own bucket: revoking or re-minting a token starts a fresh window, and two agents
+holding two distinct tokens neither share nor starve one budget.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from rest_framework.throttling import SimpleRateThrottle
+
+if TYPE_CHECKING:
+    from rest_framework.request import Request
+    from rest_framework.views import APIView
+
+
+class _McpTokenThrottle(SimpleRateThrottle):
+    """Base: throttle a request only when it is authenticated by an *agent* token.
+
+    A non-token caller (human JWT/Session) yields ``None`` from
+    :meth:`get_cache_key`, which DRF interprets as "skip this throttle entirely",
+    so the baseline ``user``/scoped throttles remain the only bound on human
+    traffic. An agent-token caller is bucketed on the token's own primary key.
+
+    A ``legacy:full`` personal access token also yields ``None`` (#2877). These are
+    *agent* budgets: ``mcp_read`` is 120/min and ``mcp_read_compute`` 12/min, against
+    1000/min on the ``user`` scope a session gets. Metering a person's own CI script
+    from the agent bucket capped it 8× tighter than the same person's browser — and
+    since ``get_throttles`` is method-agnostic, once #2877 let that token write, its
+    *writes* were being metered by a bucket named and sized for agent reads. Falling
+    through to the ``user`` scope keeps it bounded and keeps the promise that a PAT is
+    "governed exactly as your own session would be."
+    """
+
+    def get_cache_key(self, request: Request, view: APIView) -> str | None:
+        # Local import: the model layer is not import-safe at settings-load time.
+        from trueppm_api.apps.projects.models import is_agent_token
+
+        token = getattr(request, "auth", None)
+        if is_agent_token(token):
+            return self.cache_format % {"scope": self.scope, "ident": str(token.pk)}
+        return None  # human, or the owner's own full-access PAT — not an agent
+
+
+class McpTokenReadThrottle(_McpTokenThrottle):
+    """Baseline per-token cap applied across the whole MCP read surface."""
+
+    scope = "mcp_read"
+
+
+class McpTokenComputeThrottle(_McpTokenThrottle):
+    """Tighter per-token cap for the compute-heavy MCP tools.
+
+    Stacked on top of :class:`McpTokenReadThrottle` for the reads that trigger a
+    CPM or Monte Carlo recompute per call — whatif, monte-carlo/latest, forecast,
+    sprint-forecast, schedule derivation, and the program schedule action
+    (``mcp_compute_heavy`` / ``mcp_compute_heavy_actions``) — so a token loop that
+    could burn CPU is bounded well below the baseline read rate.
+
+    Unlike its base class, this one applies to **every** ``ApiToken`` regardless of
+    scope (#2877). The distinction is what each cap is *for*: ``mcp_read`` is an agent
+    budget, and metering a person's own CI script from it capped them 8× tighter than
+    their own browser. This cap is CPU protection, and CPU does not care which
+    credential class asked — an unattended loop against a Monte Carlo recompute is
+    equally expensive from a ``legacy:full`` script. Twelve recomputes a minute is far
+    above what any real automation needs (a nightly export reads each forecast once),
+    so keeping it credential-agnostic costs the legitimate case nothing.
+    """
+
+    scope = "mcp_read_compute"
+
+    def get_cache_key(self, request: Request, view: APIView) -> str | None:
+        from trueppm_api.apps.projects.models import ApiToken
+
+        token = getattr(request, "auth", None)
+        if isinstance(token, ApiToken):
+            return self.cache_format % {"scope": self.scope, "ident": str(token.pk)}
+        return None  # human JWT/Session — bounded by the account-level throttle

trueppm_api/apps/access/urls.py

@@ -0,0 +1,191 @@
+"""URL routing for the access app."""
+
+from __future__ import annotations
+
+from django.urls import path
+
+from trueppm_api.apps.access.views import (
+    ExternalStakeholderViewSet,
+    MeView,
+    ProgramMembershipViewSet,
+    ProgramUserDefinedMentionGroupViewSet,
+    ProjectMembershipViewSet,
+    UserDefinedMentionGroupViewSet,
+    UserSearchView,
+)
+from trueppm_api.apps.profiles.views import MyPinnedView, MyProfileView
+
+_members = ProjectMembershipViewSet.as_view(
+    {
+        "get": "list",
+        "post": "create",
+    }
+)
+_member_detail = ProjectMembershipViewSet.as_view(
+    {
+        "get": "retrieve",
+        "patch": "partial_update",
+        "delete": "destroy",
+    }
+)
+_program_members = ProgramMembershipViewSet.as_view(
+    {
+        "get": "list",
+        "post": "create",
+    }
+)
+_program_member_detail = ProgramMembershipViewSet.as_view(
+    {
+        "get": "retrieve",
+        "patch": "partial_update",
+        "delete": "destroy",
+    }
+)
+_mention_groups = UserDefinedMentionGroupViewSet.as_view(
+    {
+        "get": "list",
+        "post": "create",
+    }
+)
+_mention_group_detail = UserDefinedMentionGroupViewSet.as_view(
+    {
+        "get": "retrieve",
+        "patch": "partial_update",
+        "delete": "destroy",
+    }
+)
+_mention_group_add_member = UserDefinedMentionGroupViewSet.as_view({"post": "add_member"})
+_mention_group_remove_member = UserDefinedMentionGroupViewSet.as_view({"post": "remove_member"})
+_mention_group_mute = UserDefinedMentionGroupViewSet.as_view({"post": "mute"})
+_mention_group_unmute = UserDefinedMentionGroupViewSet.as_view({"post": "unmute"})
+_program_mention_groups = ProgramUserDefinedMentionGroupViewSet.as_view(
+    {
+        "get": "list",
+        "post": "create",
+    }
+)
+_program_mention_group_detail = ProgramUserDefinedMentionGroupViewSet.as_view(
+    {
+        "get": "retrieve",
+        "patch": "partial_update",
+        "delete": "destroy",
+    }
+)
+_program_mention_group_add_member = ProgramUserDefinedMentionGroupViewSet.as_view(
+    {"post": "add_member"}
+)
+_program_mention_group_remove_member = ProgramUserDefinedMentionGroupViewSet.as_view(
+    {"post": "remove_member"}
+)
+_program_mention_group_mute = ProgramUserDefinedMentionGroupViewSet.as_view({"post": "mute"})
+_program_mention_group_unmute = ProgramUserDefinedMentionGroupViewSet.as_view({"post": "unmute"})
+_program_external_stakeholders = ExternalStakeholderViewSet.as_view(
+    {
+        "get": "list",
+        "post": "create",
+    }
+)
+_program_external_stakeholder_detail = ExternalStakeholderViewSet.as_view(
+    {
+        "get": "retrieve",
+        "patch": "partial_update",
+        "delete": "destroy",
+    }
+)
+
+urlpatterns = [
+    path("auth/me/", MeView.as_view(), name="auth-me"),
+    path("auth/me/profile/", MyProfileView.as_view(), name="auth-me-profile"),
+    path("auth/me/pinned/", MyPinnedView.as_view(), name="auth-me-pinned"),
+    path("users/search/", UserSearchView.as_view(), name="user-search"),
+    path(
+        "projects/<uuid:project_pk>/members/",
+        _members,
+        name="project-members-list",
+    ),
+    path(
+        "projects/<uuid:project_pk>/members/<uuid:pk>/",
+        _member_detail,
+        name="project-members-detail",
+    ),
+    path(
+        "programs/<uuid:program_pk>/members/",
+        _program_members,
+        name="program-members-list",
+    ),
+    path(
+        "programs/<uuid:program_pk>/members/<uuid:pk>/",
+        _program_member_detail,
+        name="program-members-detail",
+    ),
+    path(
+        "projects/<uuid:project_pk>/mention-groups/",
+        _mention_groups,
+        name="project-mention-groups-list",
+    ),
+    path(
+        "projects/<uuid:project_pk>/mention-groups/<uuid:pk>/",
+        _mention_group_detail,
+        name="project-mention-groups-detail",
+    ),
+    path(
+        "projects/<uuid:project_pk>/mention-groups/<uuid:pk>/add-member/",
+        _mention_group_add_member,
+        name="project-mention-groups-add-member",
+    ),
+    path(
+        "projects/<uuid:project_pk>/mention-groups/<uuid:pk>/remove-member/",
+        _mention_group_remove_member,
+        name="project-mention-groups-remove-member",
+    ),
+    path(
+        "projects/<uuid:project_pk>/mention-groups/<uuid:pk>/mute/",
+        _mention_group_mute,
+        name="project-mention-groups-mute",
+    ),
+    path(
+        "projects/<uuid:project_pk>/mention-groups/<uuid:pk>/unmute/",
+        _mention_group_unmute,
+        name="project-mention-groups-unmute",
+    ),
+    path(
+        "programs/<uuid:program_pk>/mention-groups/",
+        _program_mention_groups,
+        name="program-mention-groups-list",
+    ),
+    path(
+        "programs/<uuid:program_pk>/mention-groups/<uuid:pk>/",
+        _program_mention_group_detail,
+        name="program-mention-groups-detail",
+    ),
+    path(
+        "programs/<uuid:program_pk>/mention-groups/<uuid:pk>/add-member/",
+        _program_mention_group_add_member,
+        name="program-mention-groups-add-member",
+    ),
+    path(
+        "programs/<uuid:program_pk>/mention-groups/<uuid:pk>/remove-member/",
+        _program_mention_group_remove_member,
+        name="program-mention-groups-remove-member",
+    ),
+    path(
+        "programs/<uuid:program_pk>/mention-groups/<uuid:pk>/mute/",
+        _program_mention_group_mute,
+        name="program-mention-groups-mute",
+    ),
+    path(
+        "programs/<uuid:program_pk>/mention-groups/<uuid:pk>/unmute/",
+        _program_mention_group_unmute,
+        name="program-mention-groups-unmute",
+    ),
+    path(
+        "programs/<uuid:program_pk>/external-stakeholders/",
+        _program_external_stakeholders,
+        name="program-external-stakeholders-list",
+    ),
+    path(
+        "programs/<uuid:program_pk>/external-stakeholders/<uuid:pk>/",
+        _program_external_stakeholder_detail,
+        name="program-external-stakeholders-detail",
+    ),
+]