trueppm-api 0.4.0__py3-none-any.whl

trueppm_api/core/password_reset.py

@@ -0,0 +1,513 @@
+"""Self-service password reset endpoints (#765, ADR-0209).
+
+Two unauthenticated (``AllowAny``) endpoints drive the forgot-password flow:
+
+- ``POST /api/v1/auth/password/reset/`` — accepts an email and, if it maps to an
+  account, emails a one-time reset link. The response is **identical** whether or
+  not the address exists, so it leaks no signal about which emails have accounts
+  (no user enumeration). Both branches return ``200`` with the same body.
+- ``POST /api/v1/auth/password/reset/confirm/`` — accepts ``uid`` + ``token`` +
+  ``new_password``, validates the stateless token, enforces the password policy,
+  sets the new password, and revokes every other session the account holds.
+
+Token scheme (ADR-0209): Django's built-in ``default_token_generator``
+(``PasswordResetTokenGenerator``) over a URL-safe-base64-encoded user PK — the same
+mechanism Django's own ``PasswordResetConfirmView`` uses. The token is a keyed HMAC
+that is stateless (no DB row), single-use by construction (it stops validating once
+the password hash changes), and expires after ``settings.PASSWORD_RESET_TIMEOUT``
+(30 minutes). We deliberately do not invent a bespoke token store.
+
+Both endpoints carry a dedicated ``password_reset`` throttle scope (5/min per IP),
+which is the primary defense against enumeration-by-probing and against looping the
+request endpoint to email-bomb a victim (ADR-0209).
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from django.conf import settings
+from django.contrib.auth import get_user_model
+from django.contrib.auth.password_validation import validate_password
+from django.contrib.auth.tokens import default_token_generator
+from django.core.exceptions import ValidationError as DjangoValidationError
+from django.core.mail import EmailMultiAlternatives
+from django.db import transaction
+from django.utils.encoding import force_bytes, force_str
+from django.utils.html import escape
+from django.utils.http import urlsafe_base64_decode, urlsafe_base64_encode
+from drf_spectacular.utils import OpenApiResponse, extend_schema
+from rest_framework import serializers, status
+from rest_framework.permissions import AllowAny
+from rest_framework.request import Request
+from rest_framework.response import Response
+from rest_framework.throttling import ScopedRateThrottle
+from rest_framework.views import APIView
+
+from trueppm_api.core.throttling import resolve_client_ip
+
+logger = logging.getLogger("trueppm.auth")
+
+User = get_user_model()
+
+# Minimum length surfaced in the UI requirements checklist ("At least 10
+# characters"). Enforced server-side here so the client checklist is advisory only
+# — the server is the authority (ADR-0209).
+_MIN_PASSWORD_LENGTH = 10
+
+# Identical success body for the request endpoint regardless of whether the address
+# has an account. Defined once so the two branches cannot drift apart and re-open an
+# enumeration signal.
+_REQUEST_OK_DETAIL = "If an account exists for that address, a password reset link is on its way."
+
+
+class PasswordResetRequestSerializer(serializers.Serializer):  # type: ignore[type-arg]
+    """Request body for the reset-link endpoint: a single email address."""
+
+    email = serializers.EmailField()
+
+
+class PasswordResetConfirmSerializer(serializers.Serializer):  # type: ignore[type-arg]
+    """Request body for the confirm endpoint: uid + token + the new password.
+
+    Field-level validation only checks *shape* (non-empty strings). The token
+    validity check and the user-dependent password policy run in the view so it can
+    return distinct, non-leaking error codes (``invalid_token`` vs
+    ``weak_password``) that the frontend maps to different screens.
+    """
+
+    uid = serializers.CharField(trim_whitespace=False)
+    token = serializers.CharField(trim_whitespace=False)
+    # trim_whitespace=False: a trailing/leading space is a legitimate part of a
+    # password and must not be silently stripped before hashing.
+    new_password = serializers.CharField(write_only=True, trim_whitespace=False)
+
+
+def enforce_reset_password_policy(new_password: str, user: Any) -> None:
+    """Validate ``new_password`` against the reset-flow policy (ADR-0209).
+
+    Aggregates every violation into one ``DjangoValidationError`` so the API can
+    return the full list at once (the frontend renders them as an inline checklist),
+    rather than surfacing one error per round-trip. Policy:
+
+    1. At least ``_MIN_PASSWORD_LENGTH`` (10) characters.
+    2. Contains at least one number OR one symbol (a non-alphanumeric character).
+    3. Passes Django's configured ``AUTH_PASSWORD_VALIDATORS`` (common-password,
+       numeric-only, and attribute-similarity checks — run with ``user`` so the
+       similarity validator can compare against the account's own attributes).
+    4. Is not identical to the account's current password ("not a previously used
+       password" in the UI — the migration-free interpretation: you cannot reset to
+       the password you already have; full N-hash history is a deferred follow-up).
+
+    Raises:
+        DjangoValidationError: with a ``messages`` list of all violations found.
+    """
+    errors: list[str] = []
+
+    if len(new_password) < _MIN_PASSWORD_LENGTH:
+        errors.append(f"Password must be at least {_MIN_PASSWORD_LENGTH} characters.")
+
+    if not any(c.isdigit() or not c.isalnum() for c in new_password):
+        errors.append("Password must include at least one number or symbol.")
+
+    try:
+        validate_password(new_password, user)
+    except DjangoValidationError as exc:
+        errors.extend(exc.messages)
+
+    # check_password is a constant-time-ish hash comparison; only meaningful when the
+    # account already has a usable password (it always does on this flow).
+    if user is not None and user.has_usable_password() and user.check_password(new_password):
+        errors.append("Your new password must be different from your current password.")
+
+    if errors:
+        # De-duplicate while preserving order — the min-length rule and Django's
+        # MinimumLengthValidator can both fire for a very short password.
+        seen: set[str] = set()
+        deduped = [m for m in errors if not (m in seen or seen.add(m))]  # type: ignore[func-returns-value]
+        raise DjangoValidationError(deduped)
+
+
+def _client_ip(request: Request) -> str | None:
+    """Best-effort client IP for the token-revocation audit rows (#2878).
+
+    **Validated, not merely extracted, and that is load-bearing here.** The value lands
+    in a ``GenericIPAddressField`` via ``bulk_create``, which does not run
+    ``full_clean``, inside the password-reset confirm transaction — and
+    ``ATOMIC_REQUESTS`` is on. An unparseable header therefore does not degrade to a
+    null column: it raises (``ValidationError`` from Django's IPv6 cleaner on
+    ``1.2.3.4:5678``, or a psycopg ``DataError`` on ``inet`` for RFC-7239's literal
+    ``unknown``), the whole request rolls back, and **the user's password is not
+    changed** — silently, only for users who happen to hold an active token, on a
+    deployment whose ingress is merely misconfigured. Account recovery is the last
+    thing that may be taken down by an audit field, so anything that is not an address
+    becomes ``None``.
+
+    ``None`` rather than a placeholder string for the same reason: ``"unknown"`` is not
+    a valid ``inet``.
+
+    The address the per-IP throttles key on (``core.throttling.resolve_client_ip``),
+    never the client-written left-most ``X-Forwarded-For`` entry. Recorded only,
+    never used for a security decision.
+    """
+    return resolve_client_ip(request)
+
+
+def _reset_link(uid: str, token: str) -> str:
+    """Build the absolute frontend confirm URL, or "" when the base URL is unset.
+
+    Mirrors the invite/notification/export idiom (``workspace/tasks.py``): read
+    ``FRONTEND_BASE_URL``, strip a trailing slash, and return "" when it is not
+    configured so the email builder can omit the link rather than emit a broken
+    relative URL.
+
+    The credential rides in the URL **fragment**, not the path (#3553). ``uid`` and
+    ``token`` together are a 30-minute bearer credential for the account, and a
+    path carrying them is exported by the SPA's telemetry envelope, by its
+    route-error boundary, and to any cross-origin destination as ``Referer``. A
+    fragment is never transmitted to any server at all, so none of the three can
+    see it — and neither can a path-logging proxy in front of the SPA.
+
+    The SPA route is ``/reset-password/confirm``; it reads ``uid``/``token`` from
+    ``window.location.hash`` (``packages/web/src/features/auth/passwordReset/resetLink.ts``).
+    """
+    base = (getattr(settings, "FRONTEND_BASE_URL", "") or "").rstrip("/")
+    if not base:
+        return ""
+    return f"{base}/reset-password/confirm#uid={uid}&token={token}"
+
+
+def _render_password_reset_email(user: Any, reset_url: str) -> tuple[str, str, str]:
+    """Render (subject, plain-text body, html body) for the reset email.
+
+    Follows the inline-render idiom used by invites/notifications/exports (no
+    templates directory exists in the API). Returns both a plain-text body and an
+    HTML alternative so the message is sent multipart. The reset link is included
+    only when configured; otherwise the copy tells the user to contact their admin
+    (matching how every other email degrades when ``FRONTEND_BASE_URL`` is unset).
+    """
+    subject = "Reset your TruePPM password"
+    greeting_name = user.get_short_name() or user.get_username()
+
+    if reset_url:
+        link_line_text = reset_url
+        # escape() defends against a display name / URL containing HTML-significant
+        # characters; the URL itself is server-built so it is trusted, but escaping
+        # is cheap insurance and keeps the HTML well-formed.
+        link_line_html = f'<a href="{escape(reset_url)}">Reset your password</a>'
+        cta_text = "Click the link below to choose a new password:"
+    else:
+        link_line_text = "Contact your workspace administrator to reset your password."
+        link_line_html = "Contact your workspace administrator to reset your password."
+        cta_text = "We could not build a reset link for this deployment."
+
+    text_body = "\n".join(
+        [
+            f"Hi {greeting_name},",
+            "",
+            "We received a request to reset the password for your TruePPM account.",
+            cta_text,
+            "",
+            link_line_text,
+            "",
+            "This link is valid for 30 minutes. For your security, using it will sign "
+            "you out of every other device.",
+            "",
+            "If you did not request a password reset, you can safely ignore this email "
+            "— your password will not change.",
+        ]
+    )
+
+    html_body = "".join(
+        [
+            f"<p>Hi {escape(greeting_name)},</p>",
+            "<p>We received a request to reset the password for your TruePPM account. "
+            f"{escape(cta_text)}</p>",
+            f"<p>{link_line_html}</p>",
+            "<p>This link is valid for <strong>30 minutes</strong>. For your security, "
+            "using it will sign you out of every other device.</p>",
+            "<p>If you did not request a password reset, you can safely ignore this "
+            "email — your password will not change.</p>",
+        ]
+    )
+    return subject, text_body, html_body
+
+
+def send_password_reset_email(user: Any) -> bool:
+    """Generate a reset token for ``user`` and email the link. Best-effort.
+
+    Synchronous by design (ADR-0209 §Durable Execution): the reset token is
+    stateless and fully re-requestable, so there is no persisted state to reconcile
+    if the send fails — the user simply clicks "Resend". A failed SMTP send is logged
+    and swallowed so it never turns into a 500 (which would itself leak that the
+    address exists). Returns True on a successful send, False otherwise; callers on
+    the request endpoint ignore the result to keep the response identical either way.
+    """
+    uid = urlsafe_base64_encode(force_bytes(user.pk))
+    token = default_token_generator.make_token(user)
+    reset_url = _reset_link(uid, token)
+
+    recipient = getattr(user, "email", "") or ""
+    if not recipient:
+        return False
+
+    subject, text_body, html_body = _render_password_reset_email(user, reset_url)
+    # Route through the workspace SMTP transport (#712, ADR-0213) so BYO-SMTP
+    # installs deliver reset mail on the same transport as everything else; a
+    # no-op fall back to the global backend when the workspace is unconfigured.
+    from trueppm_api.apps.notifications.delivery_limits import (
+        note_unbudgeted_send,
+        workspace_throttle_per_min,
+    )
+    from trueppm_api.apps.notifications.email_backend import (
+        resolve_email_connection,
+        resolve_from_email,
+        resolve_reply_to,
+    )
+
+    # A configured-but-unusable transport now raises rather than silently rerouting
+    # (#2886 item 2). Swallow it here for the same reason the send failure below is
+    # swallowed: a 500 on this endpoint would itself leak that the address exists.
+    try:
+        connection = resolve_email_connection()
+    except Exception:
+        logger.warning("password reset email: mail transport unusable")
+        return False
+
+    # This is one user-blocking transactional message, so it *charges* the shared
+    # per-minute delivery budget but is never refused by it (#2887 item 3). Refusing a
+    # reset because a batch of invites spent the minute would be a far worse failure
+    # than briefly exceeding a soft rate; charging it makes the queued drains yield.
+    note_unbudgeted_send(workspace_throttle_per_min())
+
+    msg = EmailMultiAlternatives(
+        subject=subject,
+        body=text_body,
+        from_email=resolve_from_email(),
+        to=[recipient],
+        reply_to=resolve_reply_to() or None,
+        connection=connection,
+    )
+    msg.attach_alternative(html_body, "text/html")
+    try:
+        msg.send(fail_silently=False)
+    except Exception:
+        # Best-effort: a lost email has no persisted state to reconcile (the token
+        # is stateless and re-requestable). Never re-raise — a 500 here would itself
+        # leak that the address exists.
+        # No secret logged: the only interpolated value is user.pk (a UUID); the
+        # literal merely contains the word "password", which trips the heuristic.
+        # nosemgrep: python-logger-credential-disclosure
+        logger.warning("password reset email failed for user %s", user.pk, exc_info=True)
+        return False
+    return True
+
+
+class PasswordResetRequestView(APIView):
+    """Request a password reset link. Always returns 200 (no user enumeration).
+
+    Unauthenticated (``AllowAny``) by design — a user who has forgotten their
+    password cannot authenticate. The response body is identical whether or not the
+    email maps to an account, so the endpoint reveals nothing about which addresses
+    have accounts. The residual timing signal (the exists branch does the extra work
+    of generating a token and sending mail) is accepted and bounded by the
+    ``password_reset`` throttle (ADR-0209).
+    """
+
+    permission_classes = [AllowAny]  # noqa: RUF012
+    authentication_classes: list[Any] = []  # noqa: RUF012
+    throttle_classes = [ScopedRateThrottle]  # noqa: RUF012
+    throttle_scope = "password_reset"
+
+    @extend_schema(
+        summary="Request a password reset link",
+        description=(
+            "Sends a one-time password reset link to the address if — and only if — "
+            "it belongs to an account. The response is identical whether or not the "
+            "address exists, so it never reveals which emails have accounts. Rate "
+            "limited (5/min per IP)."
+        ),
+        request=PasswordResetRequestSerializer,
+        responses={200: OpenApiResponse(description="Reset link sent if the account exists.")},
+        auth=[],
+        tags=["auth"],
+    )
+    def post(self, request: Request, *args: Any, **kwargs: Any) -> Response:
+        serializer = PasswordResetRequestSerializer(data=request.data)
+        serializer.is_valid(raise_exception=True)
+        email = serializer.validated_data["email"]
+
+        # Case-insensitive lookup: emails are stored lower-cased on create (invite
+        # accept lower-cases; SSO lower-cases), but match defensively either way.
+        # Only ACTIVE accounts with a usable password receive a reset link — an SSO-
+        # only account (unusable password) or a deactivated account gets the same
+        # silent 200, never a link. ``order_by("pk")`` makes the recipient
+        # deterministic (the oldest account) in the pathological case where two
+        # active accounts share an email case-insensitively — the stock User model
+        # does not enforce email uniqueness.
+        user = (
+            User.objects.filter(email__iexact=email, is_active=True)
+            .exclude(password="")
+            .order_by("pk")
+            .first()
+        )
+        if user is not None and user.has_usable_password():
+            send_password_reset_email(user)
+
+        return Response({"detail": _REQUEST_OK_DETAIL}, status=status.HTTP_200_OK)
+
+
+class PasswordResetConfirmView(APIView):
+    """Confirm a password reset: validate uid+token, set the password, revoke sessions.
+
+    Unauthenticated (``AllowAny``) — possession of a valid, unexpired token *is* the
+    authorization. Returns:
+
+    - ``200`` on success (password changed, all other sessions revoked, and the
+      account's Personal Access Tokens, public share links, and git-automation
+      webhook secret revoked/cleared — #4006).
+    - ``400 {"code": "invalid_token"}`` for any bad/unknown/expired uid+token — the
+      same shape for all three so confirm carries no enumeration signal either. The
+      frontend maps this to the "expired link" screen.
+    - ``400 {"code": "weak_password", "messages": [...]}`` when the new password
+      fails the policy. The frontend renders the messages inline.
+    """
+
+    permission_classes = [AllowAny]  # noqa: RUF012
+    authentication_classes: list[Any] = []  # noqa: RUF012
+    throttle_classes = [ScopedRateThrottle]  # noqa: RUF012
+    throttle_scope = "password_reset"
+
+    @extend_schema(
+        summary="Confirm a password reset",
+        description=(
+            "Validates the uid + token from the reset link and sets the new "
+            "password. On success, every other active session for the account is "
+            "revoked (all refresh tokens are blacklisted), the account's Personal "
+            "Access Tokens are revoked, and its public share links and "
+            "git-automation webhook secret are revoked/cleared. Returns 400 with "
+            "`code: invalid_token` for an invalid or expired link, or `code: "
+            "weak_password` with a `messages` list when the password fails policy."
+        ),
+        request=PasswordResetConfirmSerializer,
+        responses={
+            200: OpenApiResponse(
+                description="Password reset; sessions, PATs, and durable grants revoked."
+            ),
+            400: OpenApiResponse(description="Invalid/expired token or weak password."),
+        },
+        auth=[],
+        tags=["auth"],
+    )
+    def post(self, request: Request, *args: Any, **kwargs: Any) -> Response:
+        serializer = PasswordResetConfirmSerializer(data=request.data)
+        serializer.is_valid(raise_exception=True)
+        uid = serializer.validated_data["uid"]
+        token = serializer.validated_data["token"]
+        new_password = serializer.validated_data["new_password"]
+
+        user = self._resolve_user(uid)
+        # Constant error for every token-side failure (bad uid, unknown user, wrong
+        # or expired token) so the response never distinguishes them — no enumeration.
+        if user is None or not default_token_generator.check_token(user, token):
+            return Response(
+                {
+                    "code": "invalid_token",
+                    "detail": "This password reset link is invalid or has expired.",
+                },
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+
+        try:
+            enforce_reset_password_policy(new_password, user)
+        except DjangoValidationError as exc:
+            return Response(
+                {
+                    "code": "weak_password",
+                    "detail": "Password does not meet the requirements.",
+                    "messages": list(exc.messages),
+                },
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+
+        # Revoke every other session (ADR-0209): the confirm request itself is
+        # unauthenticated, so this signs the account out of every device where it was
+        # logged in. The password save and the session revocation run in one
+        # transaction so the account can never end up password-changed-but-sessions-
+        # live (or vice versa) — defense in depth that does not rely solely on the
+        # global ATOMIC_REQUESTS setting.
+        from trueppm_api.apps.access.services import (
+            revoke_all_personal_access_tokens,
+            revoke_all_refresh_tokens,
+            revoke_personal_durable_grants,
+        )
+        from trueppm_api.apps.access.signals import evict_all_live_project_sockets
+
+        with transaction.atomic():
+            # Password already validated above by enforce_reset_password_policy(),
+            # which runs django...validate_password(new_password, user) plus the
+            # reset-flow policy; set_password is only reached once that passed.
+            # nosemgrep: unvalidated-password
+            user.set_password(new_password)
+            user.save(update_fields=["password"])
+            revoke_all_refresh_tokens(user)
+            # A password change also invalidates the user's Personal Access Tokens
+            # (ADR-0214): a PAT bears the user's full authority, so a "my credentials
+            # may be compromised" reset must cut off long-lived personal credentials,
+            # not just live sessions. Project/program tokens are org assets and are
+            # deliberately left untouched. Same atomic block so password-changed and
+            # PAT-revoked commit together or not at all. Each revoked token now writes
+            # an ApiTokenAuditEntry (#2878) — `actor=user` because a reset is the
+            # account owner asserting compromise, even though the request itself is
+            # unauthenticated, and the source IP so an incident review can tell a
+            # self-service rotation from a takeover.
+            revoke_all_personal_access_tokens(
+                user,
+                actor=user,
+                reason="password_reset",
+                source_ip=_client_ip(request),
+            )
+            # A password reset is the same "my credentials are compromised" signal
+            # the off-boarding path acts on, but before #4006 it only revoked
+            # sessions and PATs — not the non-token durable grants that are
+            # "exactly as durable as a personal access token" per
+            # revoke_personal_durable_grants()'s own docstring: public share links
+            # this user minted, any git-automation webhook secret they configured,
+            # (#4461) any outgoing webhook they registered, and (#4589) any pending
+            # workspace invite they sent. Without this, an
+            # attacker who held a live session could mint a share link, rotate an
+            # automation secret, or keep an outgoing webhook delivering, and all
+            # three survived a reset untouched. Same atomic block as the other two
+            # revocations — `actor=user` for the same reason: the reset itself is
+            # unauthenticated, but it is the account owner asserting compromise.
+            revoke_personal_durable_grants(user, actor=user)
+            # A reset revokes every credential above, but a socket opened before the
+            # reset stays open until it disconnects on its own — the WS consumer
+            # resolves identity once, at connect, and never re-checks it (#4462,
+            # the #2850 class). Same eviction loop _evict_on_account_deactivation
+            # uses, deferred to commit the same way.
+            evict_all_live_project_sockets(user.pk)
+
+        return Response(
+            {"detail": "Your password has been reset. Please sign in with your new password."},
+            status=status.HTTP_200_OK,
+        )
+
+    @staticmethod
+    def _resolve_user(uid: str) -> Any | None:
+        """Decode the urlsafe-base64 uid to a user, or None on any decode/lookup miss.
+
+        A malformed uid, a uid that decodes to a non-existent PK, or a decode error
+        all resolve to None — the caller returns the same ``invalid_token`` response
+        for all of them, so a probing attacker cannot tell a bad uid from a valid uid
+        with a wrong token.
+        """
+        try:
+            pk = force_str(urlsafe_base64_decode(uid))
+        except (TypeError, ValueError, OverflowError, UnicodeDecodeError):
+            return None
+        try:
+            return User.objects.get(pk=pk, is_active=True)
+        except (User.DoesNotExist, User.MultipleObjectsReturned, ValueError, TypeError):
+            return None

trueppm_api/core/protect_conflict.py

@@ -0,0 +1,100 @@
+"""Shared rendering for ``PROTECT``-ed delete refusals (#2364).
+
+Django raises :class:`~django.db.models.ProtectedError` when a ``DELETE`` would
+orphan rows behind an ``on_delete=PROTECT`` foreign key. It is not an
+``APIException``, so DRF's stock handler returns ``None`` for it and the request
+escapes as an unhandled **500** — a server error for what is really a
+well-formed, authorized request that conflicts with current state. **409** is the
+honest status.
+
+Two layers use this module, and the split is deliberate:
+
+* :func:`protected_error_response` builds the *rich* body — a
+  ``reference_count`` plus a bounded ``references`` sample naming what still
+  points at the row — for the endpoints where a client can realistically act on
+  the list (detach the calendar, retag the resource). Views opt in per-endpoint
+  because only the view knows how to name a blocker usefully.
+* :func:`trueppm_exception_handler` falls back to a generic, **count-only** 409 for
+  every other ``PROTECT``-ed delete. That net is what stops the *next* ``PROTECT``
+  FK from reintroducing the 500 — the failure mode that produced this module, where
+  a delete path written against the FKs that existed at the time silently rotted as
+  new ones landed. It never names rows: it fires on paths that have not reasoned
+  about their permission gate at all, so it cannot know whether the caller is
+  authorized to see them.
+
+Responses are *returned*, never raised as an ``APIException``: DRF coerces every
+value in an exception ``detail`` to ``ErrorDetail`` (a ``str`` subclass), which
+would ship ``reference_count`` as ``"3"`` instead of ``3``. That is safe because
+``ProtectedError`` is raised while the collector walks the FKs, *before* any
+DELETE is issued — there is no partial state for ``ATOMIC_REQUESTS`` to roll back.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+
+from django.db import models
+from rest_framework import status
+from rest_framework.response import Response
+
+#: Cap on the referencing rows echoed back on a 409. A shared library row can be
+#: referenced by hundreds of others; the client needs enough to name the blockers,
+#: not the whole set.
+REFERENCE_SAMPLE_SIZE = 10
+
+
+def describe_reference(obj: models.Model) -> dict[str, str]:
+    """Render one ``PROTECT``-ing row as a ``{type, id, name}`` entry.
+
+    The default shape for any blocker a user can recognize by name. Views pass a
+    custom callable to :func:`protected_error_response` when the blocker is a join
+    row the user never sees and the actionable object is its parent.
+    """
+    return {
+        "type": obj._meta.model_name or "",
+        "id": str(obj.pk),
+        "name": str(getattr(obj, "name", "") or obj._meta.verbose_name),
+    }
+
+
+def protected_error_response(
+    protected_objects: Iterable[models.Model],
+    *,
+    detail: str,
+    code: str,
+    describe: Callable[[models.Model], dict[str, str]] | None = None,
+) -> Response:
+    """Build the 409 body for a refused delete.
+
+    ``describe`` is **opt-in on purpose**: naming the blocking rows discloses data,
+    and only the endpoint knows whether its permission gate authorizes the caller to
+    see those names. Omitting it returns the count alone — always safe, because a
+    caller who just tried the delete already knows the row exists, and a bare count
+    reveals nothing about *what* references it.
+
+    Args:
+        protected_objects: ``ProtectedError.protected_objects`` — the rows whose
+            ``PROTECT`` foreign keys blocked the delete.
+        detail: Human-readable refusal, shown to the user as-is.
+        code: Stable machine-readable slug the client branches on.
+        describe: Renders one blocker. Pass one only after confirming the endpoint's
+            permission gate authorizes the caller to see every name it can emit —
+            and have it drop or redact rows the caller cannot see. Omit to return
+            ``reference_count`` with no ``references`` key at all.
+
+    Returns:
+        A ``409`` response carrying ``detail``, ``code`` and an integer
+        ``reference_count``, plus — when ``describe`` is given — a ``references``
+        sample capped at :data:`REFERENCE_SAMPLE_SIZE`.
+    """
+    # Sort before sampling so the truncated list is deterministic — an arbitrary
+    # 10-of-200 that reshuffles per request makes the refusal impossible to act on.
+    blockers = sorted(protected_objects, key=lambda o: (o._meta.model_name or "", str(o.pk)))
+    body: dict[str, object] = {
+        "detail": detail,
+        "code": code,
+        "reference_count": len(blockers),
+    }
+    if describe is not None:
+        body["references"] = [describe(o) for o in blockers[:REFERENCE_SAMPLE_SIZE]]
+    return Response(body, status=status.HTTP_409_CONFLICT)