trueppm-api 0.4.0__py3-none-any.whl

trueppm_api/apps/access/services.py

@@ -0,0 +1,878 @@
+"""Service-layer helpers for the access app.
+
+The service layer wraps multi-row transactions that must remain atomic — most
+importantly the Program create flow, which inserts a ``Program`` row and an
+OWNER ``ProgramMembership`` row in the same transaction so a Program can never
+exist in the database without at least one Owner.
+
+ADR-0070: see §Durable Execution §4 for the atomic-create rationale.
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Sequence
+from typing import Any
+
+from django.core.exceptions import ValidationError
+from django.db import models, transaction
+from django.utils import timezone
+
+from trueppm_api.apps.access.models import ProgramMembership, ProjectMembership, Role
+from trueppm_api.apps.projects.models import Methodology, Program, Project
+
+# Shared detail copy for "this user cannot be the transfer target" (#4575).
+#
+# Views that resolve a ``*_user_id`` payload field must return this exact
+# string — not a distinct "User not found." — for an unknown id, a real id
+# with no live membership, and a real id for a deactivated user alike. Prior
+# to #4575 the view returned a 404 "User not found."/"Lead user not found."
+# for an unresolvable id while the service raised a differently-worded 400
+# for a real-but-non-member id. That mismatch was itself an oracle: a caller
+# could distinguish "no such user" from "user exists but isn't a member" (or
+# "exists but is deactivated") by status code and message alone, without ever
+# seeing the target's email. Collapsing both failure modes onto one
+# constant — reused by both the service (which raises it) and the view
+# (which returns it directly when the id does not even resolve to a User) —
+# makes that distinction unobservable by construction instead of by
+# convention.
+PROJECT_OWNER_NOT_MEMBER_DETAIL = (
+    "The new owner must already be a member of this project. "
+    "Invite them first, then retry the transfer."
+)
+PROGRAM_OWNER_NOT_MEMBER_DETAIL = (
+    "The new sponsor must already be a member of this program. "
+    "Invite them first, then retry the transfer."
+)
+PROGRAM_LEAD_NOT_MEMBER_DETAIL = (
+    "The new lead must already be a member of this program. "
+    "Invite them first, then retry the transfer."
+)
+
+
+def _protecting_relations(model: type[models.Model]) -> list[Any]:
+    """Reverse relations into *model* whose FK is ``on_delete=PROTECT``.
+
+    Derived from ``_meta`` rather than hand-listed. Every hand-maintained version of
+    this list in the codebase went stale as new ``PROTECT`` FKs landed — three delete
+    paths were each written against the FKs that existed at the time and silently
+    started raising ``ProtectedError`` later (#2364). Reflection cannot drift.
+
+    ``include_hidden=True`` is load-bearing, not defensive: a FK declared with
+    ``related_name="+"`` is absent from ``_meta.related_objects`` but Django's
+    deletion collector still enforces its ``PROTECT``. Walking the public
+    ``related_objects`` would silently miss exactly those — reproducing the bug this
+    helper exists to prevent, just one layer down. ``Workspace.calendar`` is a live
+    example of a ``+``-named ``PROTECT`` FK in this codebase.
+
+    ``test_protect_relations_snapshot`` pins the resolved set, so adding a new
+    ``PROTECT`` FK fails a test and forces a deliberate call on whether a hard delete
+    should purge that child or refuse — rather than silently purging it here.
+    """
+    return [
+        rel
+        for rel in model._meta.get_fields(include_hidden=True)
+        if rel.is_relation
+        and rel.auto_created
+        and not rel.concrete
+        and getattr(rel, "on_delete", None) is models.PROTECT
+    ]
+
+
+def _purge_protecting_children(model: type[models.Model], pks: Sequence[Any]) -> None:
+    """Delete every ``PROTECT``-ing child of *pks* so the parent rows can be removed.
+
+    Only for paths where the caller has already confirmed a permanent, irreversible
+    delete (the archive → ``?force=true`` dialog, sample-data teardown, the retention
+    purge). Everywhere else a ``PROTECT`` FK should surface as a 409 refusal, not be
+    bulldozed — see :mod:`trueppm_api.core.protect_conflict`.
+    """
+    if not pks:
+        return
+    for rel in _protecting_relations(model):
+        rel.related_model._base_manager.filter(**{f"{rel.field.name}__in": pks}).delete()
+
+
+@transaction.atomic
+def hard_delete_projects(project_ids: Sequence[Any], *, broadcast: bool = False) -> int:
+    """Permanently delete projects and the rows whose ``PROTECT`` FKs block them.
+
+    Returns the number of ``Project`` rows removed. Authorization and audit events
+    remain the caller's responsibility, but the ``project_hard_deleted`` sync
+    broadcast does not: pass ``broadcast=True`` to have this helper schedule one
+    per deleted project via ``transaction.on_commit`` (deferred so a rollback never
+    advertises a delete that didn't happen). Every current caller needs this
+    broadcast, so it is opt-in rather than silently assumed — a caller that forgets
+    the flag gets no broadcast and no event, instead of the inverse bug this helper
+    used to invite (#4374): callers were "responsible for... sync broadcasts" in
+    name only, and one of five forgot.
+
+    ``project_ids`` are coerced to ``str`` before being used in the on_commit
+    closures, so each callback captures a plain string rather than a lazily
+    re-evaluated queryset or ORM instance.
+    """
+    if not project_ids:
+        return 0
+    ids = [str(pid) for pid in project_ids]
+    _purge_protecting_children(Project, ids)
+    _, by_model = Project.objects.filter(pk__in=ids).delete()
+    deleted = int(by_model.get(Project._meta.label, 0))
+    if broadcast and deleted:
+        # A direct, literal call rather than functools.partial: the #1019/#1381
+        # AST sweep that keeps FROZEN_WS_EVENT_TYPES honest
+        # (tests/apps/sync/ws_event_scan.py) only recognizes a literal event_type
+        # reaching broadcast_board_event() directly or through a one-level
+        # parameter-forwarding wrapper — partial(broadcast_board_event, ...) is
+        # neither, and would make "project_hard_deleted" invisible to that scan.
+        # A nested def with a typed default argument (not a bare lambda, which
+        # mypy --strict cannot infer a type for here, and not a closure over the
+        # bare loop variable, which would let every callback resolve to the last
+        # id once the loop finishes) is what keeps each callback bound to its own
+        # id.
+        from trueppm_api.apps.sync.broadcast import broadcast_board_event
+
+        for project_id in ids:
+
+            def _emit_hard_deleted(project_id: str = project_id) -> None:
+                broadcast_board_event(project_id, "project_hard_deleted", {"id": project_id})
+
+            transaction.on_commit(_emit_hard_deleted)
+    return deleted
+
+
+@transaction.atomic
+def hard_delete_program(program_id: uuid.UUID | str, *, broadcast: bool = False) -> int:
+    """Permanently delete a program, its projects, and all ``PROTECT``-ing children.
+
+    The program's projects are deleted outright rather than detached — the only
+    caller is sample-data teardown, where the whole subtree is disposable. Contrast
+    :func:`delete_program_cascade`, which *soft*-deletes a real program and detaches
+    its projects so they survive as standalone work.
+
+    Returns the number of ``Project`` rows removed. Pass ``broadcast=True`` to emit
+    the per-project ``project_hard_deleted`` sync broadcast via
+    :func:`hard_delete_projects` — the program itself has no deliverable WS channel
+    (#836), so a ``program_deleted`` event, if the caller also sends one, reaches no
+    client; the per-project broadcast is what lets an open tab on one of the deleted
+    projects learn it is gone.
+    """
+    project_ids = list(Project.objects.filter(program_id=program_id).values_list("pk", flat=True))
+    deleted = hard_delete_projects(project_ids, broadcast=broadcast)
+    _purge_protecting_children(Program, [program_id])
+    Program.objects.filter(pk=program_id).delete()
+    return deleted
+
+
+@transaction.atomic
+def create_program(
+    *,
+    name: str,
+    description: str,
+    methodology: str | Methodology,
+    created_by: Any,
+    lead: Any | None = None,
+    code: str | None = "",
+) -> Program:
+    """Create a ``Program`` and the creator's OWNER membership in one transaction.
+
+    Atomicity is the whole point of this helper — if the OWNER ``ProgramMembership``
+    INSERT were a second request (or a non-atomic follow-up), a crash between the
+    two writes would leave a Program with no Owner, which permission classes treat
+    as "nobody can manage this program." The ``@transaction.atomic`` wrapper makes
+    that orphan window impossible.
+
+    Args:
+        name: Display name (max 255). No uniqueness enforcement — two PMs can
+            both have a program called "Phase 2".
+        description: Optional rich text; empty string allowed.
+        methodology: One of ``Methodology`` values; default ``HYBRID``.
+        created_by: The user creating the program — recorded on the Program row
+            and inserted as the OWNER ``ProgramMembership``.
+        lead: Optional program lead (#2025). At create time the only member that
+            will exist is ``created_by`` (the OWNER row inserted below), so the
+            serializer only admits ``lead == created_by`` — the "lead must be a
+            member" invariant holds because the OWNER membership is written in the
+            same atomic transaction. Defaults to ``None`` (no lead).
+        code: The program key (ADR-1237), already validated by the caller.
+            ``""`` derives one from ``name``. ``None`` assigns no key at all —
+            only for the seed importer, which decides the key itself (a slug, a
+            suffixed slug, or keys adopted from the program it replaces) and
+            must not first burn a derived key into the never-reused namespace.
+
+    Returns:
+        The persisted ``Program``. The OWNER membership exists by the time the
+        function returns.
+    """
+    program = Program.objects.create(
+        name=name,
+        description=description,
+        methodology=methodology,
+        created_by=created_by,
+        lead=lead,
+    )
+    ProgramMembership.objects.create(
+        program=program,
+        user=created_by,
+        role=Role.OWNER,
+    )
+    if code is not None:
+        from trueppm_api.apps.projects.models import ObjectKeySource
+        from trueppm_api.apps.projects.services import assign_key, derive_key
+
+        source = ObjectKeySource.USER if code else ObjectKeySource.DERIVED
+        assign_key(program, code or derive_key(name, "program"), source=source, actor=created_by)
+    return program
+
+
+@transaction.atomic
+def delete_program_cascade(program_id: uuid.UUID | str) -> None:
+    """Soft-delete all memberships, detach all projects, soft-delete the program.
+
+    Three things must happen atomically:
+
+    1. **Memberships are soft-deleted.** ``ProgramMembership.program`` is ``PROTECT``,
+       so a naive ``program.delete()`` raises ``ProtectedError`` while any member
+       rows exist. The UX brief surfaces this as a combined "Remove all members
+       and delete" action; the cascade implements that intent server-side.
+    2. **Projects are detached.** Django's ``SET_NULL`` only fires on a hard DELETE,
+       not on our soft-delete (``is_deleted=True``). Without an explicit detach
+       step, ``Project.program_id`` would continue to reference a soft-deleted
+       Program — the UI would display "Phase 2 (deleted)" for those projects
+       and the program shell would still try to retrieve a 404'd parent. Setting
+       ``program=NULL`` here matches the dialog's promise that projects become
+       standalone after deletion.
+    3. **The program itself is soft-deleted.** This bumps ``server_version`` so
+       sync consumers can drop the row from their caches.
+
+    Args:
+        program_id: The program to delete.
+
+    Raises:
+        Program.DoesNotExist: if the program is missing or already soft-deleted.
+    """
+    # Local import: Project is in the projects app; importing at module top
+    # would create a circular dependency through the projects → access path.
+    from trueppm_api.apps.projects.models import Project
+
+    # Lock the program row so concurrent member-add / project-assign requests
+    # cannot land between the cascade steps and re-create a reference to the
+    # program we're about to mark deleted.
+    program = Program.objects.select_for_update().get(pk=program_id, is_deleted=False)
+
+    for membership in ProgramMembership.objects.select_for_update().filter(
+        program=program, is_deleted=False
+    ):
+        membership.soft_delete()
+
+    # Detach projects — they hold a SET_NULL FK, but SET_NULL only fires on
+    # hard delete. soft_delete() on the program would otherwise leave dangling
+    # references. We must go through ``Project.save()`` (not ``update()``) so
+    # ``server_version`` increments and mobile sync clients pick up the change.
+    for project in Project.objects.select_for_update().filter(program=program):
+        project.program = None
+        project.save(update_fields=["program"])
+
+    program.soft_delete()
+
+
+@transaction.atomic
+def transfer_project_ownership(
+    *,
+    project: Project,
+    new_owner: Any,
+    actor: Any,
+) -> ProjectMembership:
+    """Atomically promote a project member to OWNER, demote the actor to ADMIN.
+
+    Why the target must already be a member: requiring an existing membership
+    forces an explicit invite step and gives the audit trail a clean
+    "joined → promoted" sequence. Auto-creating membership on transfer would
+    surprise the target with admin authority on a project they were never
+    knowingly added to.
+
+    Args:
+        project: The project whose ownership is being transferred.
+        new_owner: The user who will become OWNER.
+        actor: The current OWNER initiating the transfer; will be downgraded
+            to ADMIN. May be the same user as ``new_owner`` — in that case
+            both upserts are no-ops and the function returns the actor's row.
+
+    Returns:
+        The new OWNER's ``ProjectMembership`` row.
+
+    Raises:
+        ValidationError: if ``new_owner`` has no existing active membership
+            on the project.
+    """
+    # Defense in depth — the view layer gates with ``IsProjectOwner``, but the
+    # service is reusable (management commands, signals, future endpoints). If
+    # the actor is not actually the OWNER, a naive ``.update()`` is a silent
+    # no-op that would promote the target without removing anyone — creating
+    # an unauthorized OWNER. Assert and fail loudly before any state changes.
+    try:
+        actor_row = ProjectMembership.objects.select_for_update().get(
+            project=project,
+            user=actor,
+            is_deleted=False,
+        )
+    except ProjectMembership.DoesNotExist as exc:
+        raise ValidationError("Only an existing project Owner can transfer ownership.") from exc
+    if actor_row.role != Role.OWNER:
+        raise ValidationError("Only an existing project Owner can transfer ownership.")
+
+    try:
+        # ``user__is_active=True`` closes the email-harvest class (#4575): a
+        # deactivated user must be refused identically to one who was never a
+        # member, not promoted to OWNER on an account nobody can log into.
+        target = ProjectMembership.objects.select_for_update().get(
+            project=project,
+            user=new_owner,
+            user__is_active=True,
+            is_deleted=False,
+        )
+    except ProjectMembership.DoesNotExist as exc:
+        raise ValidationError(PROJECT_OWNER_NOT_MEMBER_DETAIL) from exc
+
+    if new_owner == actor:
+        return target
+
+    # Demote the actor first so the OWNER count never exceeds the previous
+    # state mid-transaction — defensive against future single-owner constraints.
+    # role_changed_at is stamped alongside role on both rows so the per-project
+    # access-evidence timestamp (#590) stays accurate on this path too, not just
+    # on the partial_update endpoint.
+    now = timezone.now()
+    actor_row.role = Role.ADMIN
+    actor_row.role_changed_at = now
+    actor_row.save(update_fields=["role", "role_changed_at"])
+
+    target.role = Role.OWNER
+    target.role_changed_at = now
+    target.save(update_fields=["role", "role_changed_at"])
+    return target
+
+
+@transaction.atomic
+def transfer_program_sponsorship(
+    *,
+    program: Program,
+    new_owner: Any,
+    actor: Any,
+    new_lead: Any | None = None,
+) -> ProgramMembership:
+    """Atomically promote a program member to OWNER and optionally rotate the lead.
+
+    Programs carry both an OWNER membership (RBAC) and a ``lead`` FK (the
+    "Program Manager" displayed in the header). Both can move together in a
+    sponsorship transfer so the header chip and the access matrix stay in sync.
+
+    Args:
+        program: The program whose sponsorship is being transferred.
+        new_owner: The user who will become OWNER.
+        actor: The current OWNER initiating the transfer; will be downgraded
+            to ADMIN.
+        new_lead: Optional user to set as ``program.lead``. ``None`` leaves
+            the existing lead unchanged; pass ``new_owner`` explicitly to keep
+            owner+lead in lockstep.
+
+    Returns:
+        The new OWNER's ``ProgramMembership`` row.
+
+    Raises:
+        ValidationError: if ``new_owner`` has no existing active program
+            membership, or if ``new_lead`` is given and has no existing
+            active program membership (#4575).
+    """
+    # Defense in depth (see ``transfer_project_ownership`` for full rationale)
+    # — the actor must currently hold the OWNER row, otherwise the demote
+    # ``.update()`` is a no-op and the target gets promoted without anyone
+    # being removed.
+    try:
+        actor_row = ProgramMembership.objects.select_for_update().get(
+            program=program,
+            user=actor,
+            is_deleted=False,
+        )
+    except ProgramMembership.DoesNotExist as exc:
+        raise ValidationError("Only an existing Program Admin can transfer sponsorship.") from exc
+    if actor_row.role != Role.OWNER:
+        raise ValidationError("Only an existing Program Admin can transfer sponsorship.")
+
+    try:
+        # ``user__is_active=True`` closes the email-harvest class (#4575): a
+        # deactivated user must be refused identically to one who was never a
+        # member, not promoted to OWNER on an account nobody can log into.
+        target = ProgramMembership.objects.select_for_update().get(
+            program=program,
+            user=new_owner,
+            user__is_active=True,
+            is_deleted=False,
+        )
+    except ProgramMembership.DoesNotExist as exc:
+        raise ValidationError(PROGRAM_OWNER_NOT_MEMBER_DETAIL) from exc
+
+    # ``new_lead`` previously flowed straight into ``program.lead`` with no
+    # membership check at all — unlike ``new_owner`` above, which has always
+    # been membership-gated. That let any authenticated OWNER of ANY program
+    # (including a throwaway one they just created) set an arbitrary user id
+    # as lead and read their email back off ``lead_detail`` in the 200
+    # response: an email-harvest oracle over the full user-id space (#4575).
+    # Validate here, in the service, not only in the view — the view is not
+    # the only caller and the invariant belongs with the write.
+    if new_lead is not None:
+        lead_is_member = ProgramMembership.objects.filter(
+            program=program,
+            user=new_lead,
+            user__is_active=True,
+            is_deleted=False,
+        ).exists()
+        if not lead_is_member:
+            raise ValidationError(PROGRAM_LEAD_NOT_MEMBER_DETAIL)
+
+    if new_owner != actor:
+        # role_changed_at is stamped alongside role on both rows so the
+        # per-program access-evidence timestamp (#878) stays accurate on this
+        # path too, not just on the partial_update endpoint.
+        now = timezone.now()
+        actor_row.role = Role.ADMIN
+        actor_row.role_changed_at = now
+        actor_row.save(update_fields=["role", "role_changed_at"])
+
+        target.role = Role.OWNER
+        target.role_changed_at = now
+        target.save(update_fields=["role", "role_changed_at"])
+
+    if new_lead is not None:
+        program.lead = new_lead
+        program.save(update_fields=["lead"])
+
+    return target
+
+
+@transaction.atomic
+def split_program(
+    *,
+    program: Program,
+    splits: list[dict[str, Any]],
+    actor: Any,
+) -> list[Program]:
+    """Split a program into sub-programs and close the original (ADR-0156, #967).
+
+    For each entry in ``splits`` a new sub-program is created (owned by ``actor``,
+    methodology copied from the parent, all inheritable overrides left NULL so the
+    new program inherits workspace defaults), and the entry's projects are moved
+    under it. After every split is applied the original program is closed — it
+    becomes a read-only shell holding any projects that were not redistributed.
+
+    Only the ``Project.program`` FK moves; tasks, dependencies, baselines,
+    memberships, and history are untouched, so each project keeps its full
+    schedule and audit trail under its new program. Reassignment goes through
+    ``Project.save()`` (not ``.update()``) so ``server_version`` increments and
+    mobile sync clients pick up the move — same rationale as
+    ``delete_program_cascade``.
+
+    The whole operation is one transaction: either every sub-program, every
+    reassignment, and the parent close commit together, or nothing does. A bad
+    payload raises before any INSERT so the error message is precise.
+
+    Args:
+        program: The program being split. Must be open — callers gate on
+            ``IsProgramNotClosed``; once closed by this call a replayed request
+            is rejected by that gate, which is what makes a network retry safe.
+        splits: ``[{"name": str, "project_ids": [uuid]}, ...]``. Each entry
+            becomes one sub-program. ``project_ids`` may be empty (an empty
+            sub-program shell, symmetric with ``create_program``).
+        actor: The current OWNER initiating the split; becomes OWNER of every
+            sub-program.
+
+    Returns:
+        The created sub-programs, in input order.
+
+    Raises:
+        ValidationError: if a referenced project is not a live member of this
+            program, or if a project appears in more than one split.
+    """
+    # Lock the parent row so a concurrent project-assign / delete cannot land
+    # between validation and reassignment (mirrors delete_program_cascade).
+    program = Program.objects.select_for_update().get(pk=program.pk)
+
+    member_project_ids = {
+        str(pk)
+        for pk in Project.objects.filter(program=program, is_deleted=False).values_list(
+            "pk", flat=True
+        )
+    }
+
+    # Validate the full payload up front: every id must be a live member of this
+    # program, and no id may be claimed by two sub-programs.
+    seen: set[str] = set()
+    normalized: list[tuple[str, list[str]]] = []
+    for entry in splits:
+        name = entry["name"]
+        ids = [str(pid) for pid in entry["project_ids"]]
+        for pid in ids:
+            if pid not in member_project_ids:
+                raise ValidationError(f"Project {pid} is not a project of this program.")
+            if pid in seen:
+                raise ValidationError(f"Project {pid} is assigned to more than one sub-program.")
+            seen.add(pid)
+        normalized.append((name, ids))
+
+    sub_programs: list[Program] = []
+    for name, ids in normalized:
+        sub = create_program(
+            name=name,
+            description="",
+            methodology=program.methodology,
+            created_by=actor,
+        )
+        # Filter by program=program as well as pk so a project moved out by a
+        # racing request (despite the lock) is never silently captured.
+        for project in Project.objects.select_for_update().filter(
+            program=program, pk__in=ids, is_deleted=False
+        ):
+            project.program = sub
+            project.save(update_fields=["program"])
+        sub_programs.append(sub)
+
+    if not program.is_closed:
+        program.is_closed = True
+        program.closed_at = timezone.now()
+        program.closed_by = actor
+        program.save(update_fields=["is_closed", "closed_at", "closed_by"])
+
+    return sub_programs
+
+
+def revoke_all_refresh_tokens(user: Any) -> int:
+    """Blacklist every outstanding simplejwt refresh token for ``user``.
+
+    This is the "sign out every device" primitive (ADR-0209). A password reset
+    (and, later, any explicit account-security action) must invalidate all of the
+    user's existing sessions, not just the one that triggered the change. The
+    SPA's session lives entirely in a JWT access token (in-memory, 15-min TTL) plus
+    an httpOnly refresh cookie (#897), so revoking every *refresh* token is the
+    complete server-side session revocation: a blacklisted refresh token can no
+    longer be exchanged for a new access token, and the old access token self-
+    expires within its short TTL.
+
+    Django sessions are intentionally left untouched — the SPA never authenticates
+    via ``django.contrib.sessions`` (that framework backs only the admin site and
+    the DRF browsable API), so there is no app session to clear there.
+
+    Completeness depends on every live token having an ``OutstandingToken`` row.
+    simplejwt writes one only in ``RefreshToken.for_user`` (login); rotation mints a
+    new jti and records nothing, so before #2999 this function walked a set of
+    already-blacklisted rows and left the *live* session usable while returning a
+    plausible non-zero count. ``core.auth_views._record_outstanding`` now upserts the
+    row on both login and rotation, which is what makes this function's contract
+    true. **Tokens minted before that fix shipped still have no row and remain
+    unrevokable** — an operator needing a hard cut across those must rotate
+    ``JWT_SIGNING_KEY``.
+
+    Idempotent: ``get_or_create`` means re-running blacklists nothing twice, and a
+    row already blacklisted by rotation stays blacklisted. Safe to call inside the
+    reset transaction.
+
+    Args:
+        user: The account whose refresh tokens should all be revoked.
+
+    Returns:
+        The number of tokens newly blacklisted (already-blacklisted tokens are not
+        counted). Zero when the account had no outstanding tokens (e.g. it has
+        never logged in on this deployment).
+    """
+    # Local import: the blacklist app's models are only importable once apps are
+    # loaded, and keeping the import lazy lets a lean deploy that removes the
+    # token_blacklist app degrade gracefully (the ImportError is swallowed → the
+    # password is still reset, sessions just fall back to TTL-only expiry).
+    try:
+        from rest_framework_simplejwt.token_blacklist.models import (
+            BlacklistedToken,
+            OutstandingToken,
+        )
+    except ImportError:  # pragma: no cover - only when the app is uninstalled
+        return 0
+
+    revoked = 0
+    for token in OutstandingToken.objects.filter(user=user):
+        _, created = BlacklistedToken.objects.get_or_create(token=token)
+        if created:
+            revoked += 1
+    return revoked
+
+
+def revoke_all_personal_access_tokens(
+    user: Any,
+    *,
+    actor: Any = None,
+    reason: str = "",
+    source_ip: str | None = None,
+) -> int:
+    """Soft-revoke every active Personal Access Token owned by ``user`` (ADR-0214).
+
+    Why this exists: a Personal Access Token is a *full-authority* bearer of the
+    user's own credentials — a script authenticating with it acts exactly as the
+    user. A password change is the user asserting "my credentials may be
+    compromised; cut everything off," so it must invalidate not only live sessions
+    (``revoke_all_refresh_tokens``) but also every long-lived personal credential
+    they minted. Leaving PATs live after a reset would defeat the whole point of
+    the reset — an attacker who phished the old password could keep the account via
+    a PAT they created. This is the PAT analogue of the refresh-token revocation and
+    is called immediately after it in the same atomic block.
+
+    Scope discipline: only ``owner=user`` (personal) tokens are revoked. Project-
+    and program-scoped tokens are *org assets* minted by an Admin/PM — they are not
+    the user's personal credentials and are deliberately left untouched, so a
+    password reset never breaks a team's CI integration.
+
+    Idempotent: already-revoked tokens are filtered out, so re-running is a no-op.
+    Uses a bulk ``update()`` (not per-row ``save()``) because revocation is a
+    single indexed write with no ``server_version`` sync semantics on the audit
+    path — the tokens are not mobile-synced resources whose version consumers track.
+
+    **Every revoked token gets an** ``ApiTokenAuditEntry`` **row (#2878).** It did
+    not, and the trail was inverted: routine self-service revocation through
+    ``MyApiTokenViewSet.destroy`` was logged, while the two *security-relevant*
+    revocations — password reset and off-boarding, the two that answer "was this
+    account contained, and when?" — wrote nothing, on a feature page that promises
+    "every mint and revoke is written to an append-only audit log." The rows are
+    ``bulk_create``d from the ids the ``update()`` matched, so the cost stays two
+    queries regardless of token count and the audit is inside the caller's
+    transaction: it commits with the revocation or rolls back with it, never apart.
+
+    Args:
+        user: The account whose personal access tokens should all be revoked.
+        actor: The user who caused the revocation, for the audit row. The account
+            owner for a password reset; the acting admin for an off-boarding; ``None``
+            for an operator running the management command, which has no Django user.
+        reason: Short machine-readable cause recorded in ``detail["reason"]``
+            (``password_reset``, ``offboarding``, ``operator_bulk_revoke``). It is what
+            makes the trail answerable — "revoked" alone cannot distinguish routine
+            rotation from incident response.
+        source_ip: Client IP when one is available (a request-driven path); ``None``
+            from a management command.
+
+    Returns:
+        The number of tokens newly revoked (already-revoked tokens are excluded).
+    """
+    # Local import: the projects app imports from access, so importing ApiToken at
+    # module top would create a circular dependency through the access → projects
+    # path (mirrors delete_program_cascade's lazy Project import).
+    from trueppm_api.apps.projects.models import (
+        ApiToken,
+        ApiTokenAuditAction,
+        ApiTokenAuditEntry,
+    )
+
+    # Materialize before the update: after it, `revoked_at__isnull=True` no longer
+    # selects the rows this call is responsible for, and re-reading without the filter
+    # would also pick up tokens revoked earlier by someone else and double-audit them.
+    #
+    # `select_for_update()` is what keeps the split read/write as idempotent as the
+    # single `update()` it replaced. Without the row lock, a password reset racing an
+    # admin off-boarding both select the same rows, both write, and the second write
+    # moves `revoked_at` *forward* — misdating containment on the one field an auditor
+    # reads — while producing a second REVOKED row with a contradicting reason and an
+    # inflated return count. Holding the lock makes `doomed` exactly the set this call
+    # revokes, so the audit rows below cannot describe someone else's revocation. It
+    # requires an open transaction, which every caller has (ATOMIC_REQUESTS for the two
+    # request paths, an explicit `atomic()` in the management command); a caller without
+    # one gets a loud TransactionManagementError rather than a silent race.
+    #
+    # Expired tokens are excluded deliberately. An expired token already fails
+    # authentication (expiry is folded into the authenticator's hash lookup), so
+    # revoking it changes nothing — but auditing it would pad the trail with rows
+    # claiming N live credentials were contained when the real number was lower. This
+    # matches `ApiToken.active_personal_tokens_for`, the canonical definition of
+    # "active", which the 10-token cap already uses.
+    now = timezone.now()
+    doomed = list(
+        ApiToken.objects.select_for_update()
+        .filter(
+            models.Q(expires_at__isnull=True) | models.Q(expires_at__gt=now),
+            owner=user,
+            is_deleted=False,
+            revoked_at__isnull=True,
+        )
+        .only("pk", "token_prefix", "name")
+    )
+    if not doomed:
+        return 0
+
+    revoked = ApiToken.objects.filter(
+        pk__in=[token.pk for token in doomed], revoked_at__isnull=True
+    ).update(revoked_at=now)
+    ApiTokenAuditEntry.objects.bulk_create(
+        [
+            ApiTokenAuditEntry(
+                owner=user,
+                token=token,
+                token_prefix=token.token_prefix,
+                actor=actor,
+                action=ApiTokenAuditAction.REVOKED.value,
+                source_ip=source_ip,
+                detail={"name": token.name, "reason": reason} if reason else {"name": token.name},
+            )
+            for token in doomed
+        ]
+    )
+    return revoked
+
+
+def revoke_personal_durable_grants(user: Any = None, *, actor: Any = None) -> tuple[int, int, int]:
+    """Revoke the non-token durable grants a PAT (or a live session) can mint.
+
+    ``IsNotTokenAuthenticated`` (#2878) now blocks *minting* a ``ShareLink``,
+    rotating a ``BoardAutomation`` webhook secret, or registering/repointing an
+    outbound ``Webhook`` through a bearer token, but a grant minted **before**
+    that guard existed, or minted through a live session by someone who is now
+    being contained, is exactly as durable as a personal access token and sits
+    outside every existing revocation lever (``revoke_all_personal_access_tokens``,
+    password reset, off-boarding). This closes that gap for the three grants
+    #2939 and #4461 scoped: a project's public share links, its git-automation
+    webhook secret, and any outgoing webhook the user registered. It also revokes
+    the pending workspace invites the user sent (#4589, see
+    ``revoke_pending_workspace_invites``; not reflected in the returned tuple).
+
+    The webhook case is distinct from the other two: dispatch already stops for
+    an off-boarded *registrant* because it re-checks Admin+ membership on every
+    delivery (#4325/#4330) — ``created_by`` only, never the editors set below.
+    What that membership re-check cannot see at all is a *credential*
+    compromise — a leaked PAT or hijacked session belonging to a registrant who
+    is still an active Admin — and it cannot see an editor who is not the
+    registrant in any case, compromised or not. Deactivating the webhook here
+    is belt-and-suspenders for the registrant's own credential compromise, and
+    the *only* control that reaches an editor who never registered the row.
+
+    The webhook sweep matches ``created_by=user`` **or** ``user`` appearing in
+    ``webhook.editors`` (:class:`~trueppm_api.apps.webhooks.models.WebhookEditor`,
+    an additive, append-only record of every user who has ever set ``url`` or
+    ``secret`` on the row, or re-enabled it while disabled) — not ``created_by``
+    alone, and not a single mutable "last modified by" field either. A project
+    webhook's update has no
+    registrant check — any project Admin may repoint any project webhook's URL
+    or rotate its secret (``WebhookViewSet.perform_update``) — so a hijacked
+    session belonging to Admin B could repoint Admin A's webhook to an
+    attacker's host, and B's own password reset or off-boarding must still
+    catch that row even after a later, unrelated edit by A or anyone else. A
+    mutable field would lose B's attribution the moment someone else's edit
+    overwrote it (including a PUT that only changes ``events`` but still
+    carries the unchanged ``url`` in its body); an append-only membership does
+    not have that failure mode, because nothing removes a row from it. This is
+    exactly the "grant minted through a live session by someone who is now
+    being contained" case two paragraphs up, for an update rather than a
+    create. Program webhooks record an editor too, for symmetry, but it is
+    always the same user as ``created_by`` there because
+    ``ProgramWebhookViewSet`` already restricts update to the creator
+    (ADR-0076/#4310) — so this clause adds real coverage only on the
+    project-scoped path.
+
+    ``user=None`` means instance-wide — every active grant, not one person's —
+    which is what the ``revoke_api_tokens --all`` full-compromise lever needs;
+    a scoped ``user`` is the off-boarding / single-account case.
+
+    Revoking a share link is cheap for a team to recover from (an Admin mints a
+    new one); clearing a webhook secret degrades ``GitWebhookIngestView`` to its
+    existing "no secret set" 404 refusal (fail-closed by construction, not a new
+    code path) until an Admin rotates a fresh one; deactivating an outgoing
+    ``Webhook`` stops dispatch immediately (``dispatch_webhooks`` only fans out to
+    ``is_active=True`` rows) and an Admin re-enables it once the credential issue
+    is resolved, which also clears the delivery-health counters (see
+    ``WebhookSerializer.update``). All three are lower-disruption than the
+    project-/program-scoped *API tokens* this module deliberately leaves alone
+    on off-boarding (see ``_revoke_offboarded_credentials``) — those are shared
+    integration credentials embedded in other people's scripts and CI, not a
+    single admin's config action.
+
+    Returns ``(share_links_revoked, automation_secrets_cleared, webhooks_deactivated)``.
+    """
+    # Local import: projects/integrations/webhooks import from access, so importing
+    # these at module top would create a circular dependency (mirrors the ApiToken
+    # import above).
+    from trueppm_api.apps.integrations.models import BoardAutomation
+    from trueppm_api.apps.projects.models import ShareLink
+    from trueppm_api.apps.webhooks.models import Webhook
+
+    now = timezone.now()
+
+    links = ShareLink.objects.filter(revoked_at__isnull=True)
+    if user is not None:
+        links = links.filter(created_by=user)
+    links_revoked = links.update(revoked_at=now, revoked_by=actor)
+
+    secrets_qs = BoardAutomation.objects.exclude(secret_ciphertext=b"")
+    if user is not None:
+        secrets_qs = secrets_qs.filter(configured_by=user)
+    secrets_cleared = secrets_qs.update(secret_ciphertext=b"", secret_set_at=None)
+
+    webhooks_qs = Webhook.objects.filter(is_active=True)
+    if user is not None:
+        webhooks_qs = webhooks_qs.filter(models.Q(created_by=user) | models.Q(editors__user=user))
+    # Deliberately neutral: this fires whenever EITHER leg above matches, and the
+    # editors leg means the row's registrant may be a different, untouched account
+    # (#4461) — "the registrant's credentials were revoked" would misattribute the
+    # cause on exactly that path. The UI/docs tell the admin to verify url/secret
+    # before re-enabling regardless of which leg fired, so the reason does not need
+    # to (and cannot cheaply) distinguish them.
+    webhooks_deactivated = webhooks_qs.update(
+        is_active=False,
+        disabled_at=now,
+        disabled_reason="Deactivated: a security sweep revoked a credential tied to this webhook.",
+    )
+
+    # Pending workspace invites the user minted (#4589). Not part of the returned
+    # tuple (its shape is relied on by every caller); the sweep audits itself.
+    revoke_pending_workspace_invites(user, actor=actor)
+
+    return links_revoked, secrets_cleared, webhooks_deactivated
+
+
+def revoke_pending_workspace_invites(
+    user: Any = None, *, actor: Any = None, min_role: int | None = None
+) -> int:
+    """Revoke the not-yet-accepted ``WorkspaceInvite`` rows ``user`` minted (#4589).
+
+    An invite is a durable, role-carrying bearer grant (7-day token, role up to one
+    rank below the inviter) that works for an outside address with no session at
+    all. A contained Admin's off-boarding, password reset and
+    ``revoke_api_tokens`` all left it live, and ``resend`` could re-mint it.
+    ``FAILED`` (send-exhausted) invites are swept too because resend revives them;
+    ``REVOKED`` is terminal and never resendable.
+
+    ``min_role`` limits the sweep to invites granting at least that workspace role
+    (used on demotion: invites the sender can no longer vouch for).
+
+    ``user=None`` is instance-wide (``revoke_api_tokens --all``). One
+    ``INVITE_REVOKED`` audit row per invite, written in the caller's transaction.
+    Returns the number of invites revoked.
+    """
+    from trueppm_api.apps.workspace.models import AuditEventType, InviteStatus, WorkspaceInvite
+    from trueppm_api.apps.workspace.services import _actor_label, record_audit_event
+
+    qs = WorkspaceInvite.objects.select_for_update(of=("self",)).filter(
+        status__in=(InviteStatus.PENDING, InviteStatus.FAILED)
+    )
+    if user is not None:
+        qs = qs.filter(invited_by=user)
+    if min_role is not None:
+        qs = qs.filter(role__gte=min_role)
+    invites = list(qs.select_related("invited_by"))
+    for invite in invites:
+        invite.status = InviteStatus.REVOKED
+        invite.email_pending = False
+        invite.email_token = ""
+        invite.save(update_fields=["status", "email_pending", "email_token"])
+        record_audit_event(
+            event_type=AuditEventType.INVITE_REVOKED,
+            actor=actor,
+            target_type="invite",
+            target_id=invite.pk,
+            target_label=invite.email,
+            metadata={
+                "role": invite.get_role_display(),
+                "invited_by": _actor_label(invite.invited_by),
+                "reason": "security_sweep",
+            },
+        )
+    return len(invites)