trueppm-api 0.4.0__py3-none-any.whl

trueppm_api/apps/notifications/serializers.py

@@ -0,0 +1,1094 @@
+"""DRF serializers for the notifications app (ADR-0075)."""
+
+from __future__ import annotations
+
+import logging
+import re
+import zoneinfo
+from functools import partial
+from typing import Any, cast
+
+from drf_spectacular.utils import extend_schema_field
+from rest_framework import serializers
+
+from trueppm_api.apps.projects.schema_migrations import migrate_payload
+
+from .categories import category_for
+from .delivery_limits import EMAIL_MAX_BATCH_SIZE
+from .models import (
+    PROJECT_NOTIFICATION_DELIVERY_REPORTED_CHANNELS,
+    PROJECT_NOTIFICATION_DELIVERY_REPORTED_EVENTS,
+    EmailSecurity,
+    EmailTransportMode,
+    Mention,
+    Notification,
+    NotificationPreference,
+    ProjectNotificationChannel,
+    ProjectNotificationEventType,
+    ProjectNotificationPreference,
+    UserNotificationSettings,
+    WorkspaceEmailSettings,
+    project_notification_channel_delivery,
+    project_notification_event_delivery,
+)
+from .schema_migrations import SURFACE_PROJECT_NOTIFICATION_MATRIX
+from .services import (
+    QUIET_HOURS_TZ_SOURCE_FALLBACK,
+    QUIET_HOURS_TZ_SOURCE_PROJECT,
+    QUIET_HOURS_TZ_SOURCE_SERVER,
+    QUIET_HOURS_TZ_SOURCE_WORKSPACE,
+)
+
+logger = logging.getLogger(__name__)
+
+# DKIM selector: a single DNS label component set (letters, digits, dot, dash,
+# underscore), capped to the model's 63-char column. Restricting this prevents
+# DNS-name injection into the deliverability health lookup (security review M3).
+_DKIM_SELECTOR_RE = re.compile(r"^[A-Za-z0-9._-]{1,63}$")
+
+# Transports that require a stored/submitted credential. SMTP is the one
+# exception with a carve-out: it is the only transport that may run with NO
+# credential at all (see `_is_no_auth_smtp`, #4190) — an internal relay that
+# accepts unauthenticated connections (Postfix `mynetworks`, an in-cluster
+# relay), which the docs page has always named as a valid "Security: None"
+# use case without any in-app way to configure it. SendGrid and SES are
+# provider-issued credentials with no unauthenticated mode, so they keep
+# requiring one unconditionally.
+_CREDENTIAL_MODES = {
+    EmailTransportMode.SMTP,
+    EmailTransportMode.SENDGRID,
+    EmailTransportMode.SES,
+}
+# Transports where the admin supplies the relay host (SendGrid's host is fixed).
+_HOST_REQUIRED_MODES = {EmailTransportMode.SMTP, EmailTransportMode.SES}
+# Transports where the admin supplies the SMTP AUTH username. SendGrid is excluded
+# because its username is server-fixed to the literal "apikey" (the key travels as
+# the password), and CLOUD stores no credentials at all. SMTP's entry here is
+# skipped when `_is_no_auth_smtp` holds (#4190).
+_USERNAME_REQUIRED_MODES = {EmailTransportMode.SMTP, EmailTransportMode.SES}
+
+
+def _effective(attrs: dict[str, Any], instance: Any, field: str, default: Any = "") -> Any:
+    """Value ``field`` will hold after this write.
+
+    A PATCH only carries the fields being changed, so validation has to reason
+    about the *merged* record: incoming value if the request set one, otherwise
+    whatever is already stored.
+    """
+    if field in attrs:
+        return attrs[field]
+    return getattr(instance, field, default)
+
+
+def _is_no_auth_smtp(*, mode: Any, username: str, incoming_password: str) -> bool:
+    """True when this save is an explicit, credential-free SMTP config (#4190).
+
+    Only SMTP may run unauthenticated — a relay on a trusted network that
+    accepts unauthenticated connections (Postfix ``mynetworks``, an in-cluster
+    relay). Both ``username`` AND ``incoming_password`` must be blank.
+    ``incoming_password`` is deliberately the *submitted* value, not the
+    merged/effective one: password carries rotate-vs-keep secrecy (an
+    omitted/blank submission normally means "keep the stored secret"), so
+    reading the effective value here would read "I didn't touch the password
+    field" as "no auth" even when a credential is already stored under the
+    row — exactly the stale-secret survival this fix closes. ``username`` has
+    no such secrecy, so its merged/effective value is safe to use elsewhere in
+    this module; this function is the one place that must not.
+    """
+    return mode == EmailTransportMode.SMTP and not username and not incoming_password
+
+
+def _assert_transport_fields(
+    *,
+    mode: Any,
+    host: str,
+    username: str,
+    effective_pw: str,
+    needs_fresh_password: bool,
+    no_auth: bool,
+) -> None:
+    """Reject a transport config that is missing something the transport needs.
+
+    Runs before the live probe so a config that cannot possibly work is refused
+    without opening a connection. ``no_auth`` (#4190) short-circuits the
+    username/password checks for the one transport that may legitimately run
+    with neither: a Custom SMTP relay on a trusted network that accepts
+    unauthenticated connections. It is never true for SendGrid/SES, which keep
+    requiring a credential unconditionally.
+    """
+    # Reusing a stale secret across a transport switch is a footgun — a
+    # SendGrid API key is not an SES password (security review M2). Not
+    # applicable when switching *into* a no-auth SMTP config: there is no
+    # password to re-enter because none is being kept (validate() forces
+    # effective_pw to "" and update() clears the stored ciphertext).
+    if needs_fresh_password and mode in _CREDENTIAL_MODES:
+        raise serializers.ValidationError(
+            {"password": "Re-enter the password when changing the transport."}
+        )
+
+    if mode in _HOST_REQUIRED_MODES and not host:
+        raise serializers.ValidationError({"host": "Host is required for this transport."})
+
+    if no_auth:
+        # An explicit, unambiguous choice: both username and password are
+        # blank. Django's SMTP backend already skips login() when both are
+        # empty, so there is nothing further to validate — the probe below
+        # opens a plain unauthenticated connection.
+        return
+
+    # SMTP AUTH is a (username, password) pair, so a blank username paired
+    # with a non-blank password is not a weaker credential — it is a
+    # credential that can never be used (Django's SMTP backend calls login()
+    # only when both are truthy), so the probe would open an unauthenticated
+    # connection that succeeds and persist a config whose every real send then
+    # fails 530 Authentication Required. Requiring the pair here is what makes
+    # the validate-before-persist gate honest. (A blank username with a blank
+    # password is the `no_auth` branch above, not this one.)
+    if mode in _USERNAME_REQUIRED_MODES and not username:
+        hint = (
+            " Leave both Username and Password blank instead to use no "
+            "authentication (Custom SMTP only)."
+            if mode == EmailTransportMode.SMTP
+            else ""
+        )
+        raise serializers.ValidationError(
+            {
+                "username": (
+                    "A username is required for this transport — the mail server "
+                    "authenticates as this account. It is usually the full email "
+                    "address that owns the password or app password." + hint
+                )
+            }
+        )
+
+    if not effective_pw:
+        raise serializers.ValidationError(
+            {"password": "A password is required for this transport."}
+        )
+
+
+def _probe_or_raise(
+    *,
+    mode: Any,
+    host: str,
+    port: Any,
+    security: Any,
+    username: str,
+    password: str,
+) -> None:
+    """Validate-before-persist: open the candidate transport now.
+
+    Distinguishes an SSRF-egress-blocked host from every other connect failure
+    (#4189): the two used to share one generic "check the host, port, security,
+    and credentials" message, which sent an operator whose relay is simply on a
+    private network — and whose credentials are fine — looking in the wrong
+    place. ``EmailHostNotAllowedError``'s message is curated by
+    ``email_backend._assert_host_public`` to never leak the DNS-resolved
+    address, so it is safe to surface to the client verbatim. Every other
+    failure still gets the generic message only — never the underlying
+    smtplib exception (M1).
+    """
+    from .email_backend import EmailHostNotAllowedError, EmailTransportError, probe_transport
+
+    try:
+        probe_transport(
+            transport_mode=str(mode),
+            host=host,
+            port=int(port),
+            security=str(security),
+            username=username,
+            password=password,
+        )
+    except EmailHostNotAllowedError as exc:
+        logger.info(
+            "email transport probe blocked by egress guard (host=%s port=%s): %s",
+            host,
+            port,
+            exc,
+        )
+        raise serializers.ValidationError({"non_field_errors": [str(exc)]}) from exc
+    except EmailTransportError as exc:
+        # Curated message only — never surface the exception object. The
+        # SSRF-guarded host path can carry the DNS-resolved internal address
+        # (scrubbed from the client at email_backend._assert_host_public, and
+        # caught above before reaching here); log the detail server-side
+        # (CodeQL py/stack-trace-exposure).
+        logger.info("email transport probe failed (host=%s port=%s): %s", host, port, exc)
+        raise serializers.ValidationError(
+            {
+                "non_field_errors": [
+                    "Could not connect to the mail server with these settings. "
+                    "Check the host, port, security, and credentials."
+                ]
+            }
+        ) from exc
+
+
+class MentionAuthorSerializer(serializers.Serializer[Any]):
+    """Nested read-only user summary for Mention.mentioner / mentioned_user."""
+
+    id = serializers.UUIDField(read_only=True)
+    username = serializers.CharField(read_only=True)
+    display_name = serializers.SerializerMethodField()
+
+    def get_display_name(self, obj: Any) -> str:
+        name: str = obj.get_full_name() or obj.username
+        return name
+
+
+class MentionSerializer(serializers.ModelSerializer[Mention]):
+    """Read-only serializer for Mention.
+
+    Mentions are append-only — no write path through this serializer. Created
+    indirectly via TaskCommentSerializer.create + services.create_mention_notifications.
+    """
+
+    mentioner = MentionAuthorSerializer(read_only=True)
+    mentioned_user = MentionAuthorSerializer(read_only=True)
+
+    class Meta:
+        model = Mention
+        fields = [
+            "id",
+            "mentioner",
+            "mentioned_user",
+            "mentioned_group_key",
+            "scope",
+            "task_comment",
+            "created_at",
+        ]
+        read_only_fields = fields
+
+
+PROJECT_DELETED_EVENT = "project.deleted"
+
+
+def recipient_member_project_sets(user: Any) -> tuple[set[Any], set[Any]]:
+    """Return ``(live, including_trashed)`` project-id sets for ``user``'s memberships.
+
+    One query serves both: ``live`` floors out projects in Trash (#4577 — a trashed
+    project confers no role), ``including_trashed`` keeps them for the single event
+    (``project.deleted``) whose whole purpose is to tell the member about the trash.
+    Revoked memberships are excluded from both.
+    """
+    from trueppm_api.apps.access.models import ProjectMembership
+
+    live: set[Any] = set()
+    everything: set[Any] = set()
+    for project_id, trashed in ProjectMembership.objects.filter(
+        user=user, is_deleted=False
+    ).values_list("project_id", "project__is_deleted"):
+        everything.add(project_id)
+        if not trashed:
+            live.add(project_id)
+    return live, everything
+
+
+class NotificationSerializer(serializers.ModelSerializer[Notification]):
+    """Per-recipient inbox row.
+
+    Writes are limited to is_read / is_archived (PATCH-only on the viewset).
+    All other fields are read-only.
+    """
+
+    mention = MentionSerializer(read_only=True, allow_null=True)
+    snippet = serializers.SerializerMethodField()
+    task_id = serializers.SerializerMethodField()
+    # Derived read-only category (ADR-0216 §3) — mentions | tasks | signals |
+    # project. Sourced from categories.category_for so the field and the
+    # ?category= filter share one mapping and never drift.
+    category = serializers.SerializerMethodField()
+
+    def get_category(self, obj: Notification) -> str:
+        return category_for(obj)
+
+    def get_snippet(self, obj: Notification) -> str:
+        """Short preview of the source mention's body.
+
+        Truncated to 200 chars. Returns empty string if the source is
+        unavailable (e.g. comment soft-deleted).
+
+        Cross-project gate (#514): the snippet is a project member's-eyes view
+        of the source comment body, so it is returned ONLY to a recipient who
+        is a *current* member of the mention's source project. Program-scoped
+        auto-groups (`@program-*`) fan a mention out to members of sibling
+        projects who are NOT members of the source project — for them the row
+        still surfaces (they know they were pinged) but the body is redacted, so
+        a program ping never leaks one project's comment content to another
+        project's team. This also honors the standing rule that a departed
+        member no longer sees the body. Project membership is the read boundary
+        in OSS; the program is a coordination unit, not a shared-content unit.
+        """
+        mention = obj.mention
+        if mention is None:
+            return ""
+        comment = mention.task_comment
+        if comment is None or comment.is_deleted:
+            return ""
+        if not self._recipient_can_see_project(obj):
+            return ""
+        body = comment.body or ""
+        return body[:200]
+
+    def _recipient_can_see_project(self, obj: Notification) -> bool:
+        """True if the notification's recipient currently belongs to ``obj.project``.
+
+        Generalizes the mention-only #514 gate (formerly
+        ``_recipient_can_see_source``, keyed on ``mention.project_id``) to every
+        notification, mention- or event-sourced (#3510): ``Notification.project_id``
+        is set at dispatch for both — the event-sourced fan-outs in ``services.py``
+        write it directly, and the mention fan-out (``_build_mention_notification``)
+        writes the same ``project_id`` the mention's source project resolved to — so
+        one project-membership check now backs the mention ``snippet``
+        redaction, the ``subject``/``body``/``project`` redaction in
+        :meth:`to_representation`, and — since #3674 — the ``task_id`` /
+        ``mention.task_comment`` object-reference redaction alongside it. A
+        notification with no project at all (the
+        ADR-0663 account-scoped digest rows, which span the recipient's whole
+        membership set rather than one project) has no project boundary to check
+        against, so it is always visible.
+
+        The set of the recipient's member projects is resolved once per response
+        and memoized on the serializer context, so the inbox list stays O(1)
+        queries rather than one membership query per row. Falls open only when
+        there is no request/user context at all (e.g. a bare unit test
+        serializing without a request) — every real read path (the viewset)
+        supplies it.
+        """
+        project_id = obj.project_id
+        if project_id is None:
+            return True
+        member_project_ids = self.context.get("member_project_ids")
+        if member_project_ids is None:
+            request = self.context.get("request")
+            user = getattr(request, "user", None) if request is not None else None
+            if user is None or not getattr(user, "is_authenticated", False):
+                return True  # no user context to gate against — preserve behavior
+            member_project_ids, trashed_inclusive = recipient_member_project_sets(user)
+            # DRF's serializer context is a plain dict at runtime (typed Mapping
+            # in the stubs); memoize so the list path resolves membership once.
+            ctx = cast(dict[str, Any], self.context)
+            ctx["member_project_ids"] = member_project_ids
+            ctx["member_project_ids_incl_trashed"] = trashed_inclusive
+        if obj.event_type == PROJECT_DELETED_EVENT:
+            # The "project was deleted" notice is written *because* the project is
+            # now in Trash, so the trashed-project floor would blank the one message
+            # that tells the member where to restore it. The revoked-membership
+            # gate still applies to it.
+            return project_id in self.context.get(
+                "member_project_ids_incl_trashed", member_project_ids
+            )
+        return project_id in member_project_ids
+
+    def to_representation(self, instance: Notification) -> dict[str, Any]:
+        """Redact ``subject``/``body``/``project`` (#3510) + the source object refs (#3674).
+
+        ``subject`` and ``body`` are free text rendered from the project and task
+        names at dispatch time (see the ``Notification(...)`` fan-outs in
+        ``services.py``), and ``project`` is the FK to the row's source project.
+        All three are frozen at dispatch and, before this change, were served
+        unredacted forever after — including to a user removed from the project,
+        who kept an inbox that went on naming that project's tasks indefinitely.
+        ``snippet`` already redacted the same class of content one field over
+        (#514); this extends that same treatment to the rest of the row instead
+        of re-flooring the whole read against current membership.
+
+        Retention position (#3510): a delivered notification is a record of a
+        message that was sent, not a live view of the project — so the row is
+        kept and its content is redacted, matching ``snippet``'s existing
+        behavior. Redacted values reuse shapes the client already handles:
+        ``subject``/``body`` blank to ``""`` (their normal non-null default), and
+        ``project`` becomes ``None`` — already the shape of an ADR-0663
+        account-scoped digest row with no single owning project. No schema
+        change, no new client-side branch.
+
+        Object references (#3674). ``mention.task_comment`` — a raw comment UUID
+        — is redacted to ``None`` on the same gate, as is ``task_id`` (in
+        :meth:`get_task_id`). The rest of the nested ``mention`` object is
+        deliberately KEPT. The dividing line is not which population is reading
+        (see below) but what the field *is*:
+
+        * **Redacted — opaque handles into the source project's content graph.**
+          ``task_id`` and ``mention.task_comment`` are UUIDs. They say nothing to
+          a human and exist only to be handed back to another endpoint, which is
+          precisely the residual-IDOR surface #3674 was filed on. Nobody who
+          fails this gate can spend one: ``TaskViewSet`` and the comment routes
+          floor on current membership. So redacting them removes an object
+          reference and zero capability.
+        * **Kept — the "you were pinged" signal, which is not a project-content
+          reference.** ``mentioner`` is the author's username/display name;
+          ``mentioned_user`` is null (group mention) or the recipient themselves
+          (``_resolve_mention_recipients`` keys a direct mention by its own
+          target); ``mentioned_group_key`` is a group the recipient belongs to —
+          that is *how* they were reached; ``scope`` is a 3-value enum. None of
+          these name a task, a project, or a comment. ``mention.id`` is kept with
+          them: it is a handle, but to an object no endpoint serves, so keeping it
+          grants nothing.
+
+        Why this does NOT need to distinguish the two populations that reach this
+        branch. ``_recipient_can_see_project`` is one predicate over two groups:
+        a member whose access was revoked, and a sibling-project member pinged
+        through a ``@program-*`` auto-group who was never a member of the source
+        project and was never intentionally denied (the #514 population). They
+        differ in intent, but they are identical in capability — both are gated
+        out of every endpoint a task or comment UUID could be spent at — and the
+        fields where their intents *would* diverge are exactly the ones kept
+        above. So the honest #514 promise, "the row still surfaces, they know
+        they were pinged", survives intact: a redacted mention row still renders
+        "Authoria mentioned @program-pms". What it loses is a deep link that was
+        already dead for that reader (the client short-circuits on
+        ``project === null`` before it ever reads ``task_id``). Widening the
+        redaction to ``mentioner``/``mentioned_group_key`` WOULD reverse #514 —
+        it would leave a row that says only "something happened" — and would
+        need a discriminator this row does not carry; that is not done here and
+        is not needed for the leak #3674 names.
+        """
+        data = super().to_representation(instance)
+        if not self._recipient_can_see_project(instance):
+            data["subject"] = ""
+            data["body"] = ""
+            data["project"] = None
+            mention = data.get("mention")
+            if mention is not None:
+                # Reuses a shape the client already handles: a mention row whose
+                # source comment was soft-deleted serializes with a null FK and a
+                # blank snippet, which is exactly what a redacted row now looks
+                # like. No schema change, no new client-side branch.
+                mention["task_comment"] = None
+        return data
+
+    def get_task_id(self, obj: Notification) -> str | None:
+        # Deliberately comment-only, not a docstring: drf-spectacular publishes a
+        # SerializerMethodField's docstring as the field `description` in
+        # docs/api/openapi.json, which would put this internal reasoning (and
+        # issue numbers) in the public contract.
+        #
+        # Redacted on the same membership predicate as `snippet` (#514) and
+        # `subject`/`body`/`project` (#3510) — see `to_representation` for why a
+        # raw task UUID goes while the mention's identity fields stay. Checked
+        # before the FK is read so a redacted row costs no attribute walk.
+        if not self._recipient_can_see_project(obj):
+            return None
+        # Event-sourced rows (#497/#861) carry a direct deep-link FK; mention
+        # rows resolve their task through the source comment. Prefer the explicit
+        # FK so the inbox row links to the affected task/milestone either way.
+        if obj.task_id is not None:
+            return str(obj.task_id)
+        mention = obj.mention
+        if mention is None or mention.task_comment is None:
+            return None
+        return str(mention.task_comment.task_id)
+
+    class Meta:
+        model = Notification
+        # event_type/subject/body are the event-sourced inbox payload (#639,
+        # #497, #861). They were inbox-invisible before — a mention row leaves
+        # them blank and renders from `snippet`; an event row has no mention, so
+        # without these fields the client could not show its title/preview and
+        # fell back to "mentioned you / comment unavailable".
+        fields = [
+            "id",
+            "recipient",
+            "mention",
+            "event_type",
+            "subject",
+            "body",
+            "project",
+            "is_read",
+            "is_archived",
+            "snoozed_until",
+            "category",
+            "created_at",
+            "read_at",
+            "snippet",
+            "task_id",
+        ]
+        read_only_fields = [
+            "id",
+            "recipient",
+            "mention",
+            "event_type",
+            "subject",
+            "body",
+            "project",
+            # snoozed_until is written by the dedicated snooze action, never PATCH.
+            "snoozed_until",
+            "category",
+            "created_at",
+            "read_at",
+            "snippet",
+            "task_id",
+        ]
+
+
+class NotificationPreferenceSerializer(serializers.ModelSerializer[NotificationPreference]):
+    """Per-user (event_type, channel) toggle.
+
+    PATCH on the viewset only modifies `enabled` — event_type / channel /
+    user are immutable.
+    """
+
+    class Meta:
+        model = NotificationPreference
+        fields = ["id", "event_type", "channel", "enabled", "updated_at"]
+        read_only_fields = ["id", "event_type", "channel", "updated_at"]
+
+
+# ---------------------------------------------------------------------------
+# Project-scoped preferences (#522)
+# ---------------------------------------------------------------------------
+
+
+_VALID_EVENT_TYPES = {choice.value for choice in ProjectNotificationEventType}
+_VALID_CHANNELS = {choice.value for choice in ProjectNotificationChannel}
+
+
+#: The published shape of the notification matrix (#3364).
+#:
+#: A bare ``JSONField`` carries no schema hint, so drf-spectacular publishes it as
+#: ``{}`` — "any JSON at all". That is not a small imprecision on this field: it is
+#: the only thing ``PATCH .../notification-preferences/`` exists to write, and the
+#: field below rejects every key outside the two enumerations with a 400. Declaring
+#: the body while leaving its one field untyped would tell an integrator "send some
+#: JSON" and 400 on every guess — the same gap #3364 closes one level up.
+#:
+#: Derived from the enums rather than restated, so a new event type or channel
+#: reaches the published contract without a second edit that can be forgotten.
+#:
+#: ``propertyNames`` is JSON Schema, not OpenAPI 3.0 Schema Object — this project
+#: publishes ``openapi: 3.0.3`` (see ``docs/api/openapi.json``), whose meta-schema
+#: has no such keyword and rejects the whole object under ``additionalProperties``'
+#: ``oneOf`` the moment it appears anywhere in the tree. The two enumerations are
+#: small and closed, so each key is spelled out explicitly under ``properties``
+#: instead, with ``additionalProperties: False`` doing the same "no unknown key"
+#: rejection ``propertyNames`` would have — this is what "9×4 grid" means literally.
+_PROJECT_NOTIFICATION_MATRIX_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "description": (
+        "Per-event, per-channel routing grid. Keys are event types; each value is "
+        "an object of channel to boolean. A PATCH may send a partial grid — the "
+        "supplied cells are merged onto the stored ones, so a single toggle need "
+        "not repost the whole matrix. Any key outside these two enumerations, or "
+        "any non-boolean leaf, is rejected with a 400."
+    ),
+    "properties": {
+        event_type: {
+            "type": "object",
+            "properties": {channel: {"type": "boolean"} for channel in sorted(_VALID_CHANNELS)},
+            "additionalProperties": False,
+        }
+        for event_type in sorted(_VALID_EVENT_TYPES)
+    },
+    "additionalProperties": False,
+}
+
+
+@extend_schema_field(_PROJECT_NOTIFICATION_MATRIX_SCHEMA)
+class _ProjectNotificationMatrixField(serializers.JSONField):
+    """JSON matrix `{event_type: {channel: bool}}` with strict key validation.
+
+    Rejects unknown event types and channels at the serializer layer so a
+    typo in the client doesn't silently corrupt the stored matrix. Non-bool
+    leaves are also rejected — there is no "tri-state" toggle.
+    """
+
+    def to_internal_value(self, data: Any) -> dict[str, dict[str, bool]]:
+        value = super().to_internal_value(data)
+        if not isinstance(value, dict):
+            raise serializers.ValidationError("matrix must be a JSON object")
+        validated: dict[str, dict[str, bool]] = {}
+        for event_type, channels in value.items():
+            if event_type not in _VALID_EVENT_TYPES:
+                raise serializers.ValidationError(f"Unknown event_type: {event_type!r}")
+            if not isinstance(channels, dict):
+                raise serializers.ValidationError(
+                    f"matrix[{event_type!r}] must be an object of channel→bool"
+                )
+            row: dict[str, bool] = {}
+            for channel, enabled in channels.items():
+                if channel not in _VALID_CHANNELS:
+                    raise serializers.ValidationError(f"Unknown channel: {channel!r}")
+                if not isinstance(enabled, bool):
+                    raise serializers.ValidationError(
+                        f"matrix[{event_type!r}][{channel!r}] must be a boolean"
+                    )
+                row[channel] = enabled
+            validated[event_type] = row
+        return validated
+
+
+class ProjectNotificationPreferenceSerializer(
+    serializers.ModelSerializer[ProjectNotificationPreference]
+):
+    """Per-(project, user) notification preferences.
+
+    The full matrix and quiet-hours window are returned in one document; the
+    PATCH path merges the supplied matrix onto the stored one so a partial
+    toggle does not have to repost the full 9×4 grid.
+
+    On read, matrix is run through the forward-migration registry
+    (``schema_migrations.migrate_payload``, ADR-0086 / ADR-0204, #1916): a
+    stale stored payload is upgraded to the current shape before any client
+    sees it, mirroring ``BoardSavedViewSerializer``. The view layer's
+    ``_merge_matrix`` overlay still runs afterward (it also drops unknown
+    garbage keys, #675 — a distinct concern from the version upgrade), so this
+    is defense-in-depth for any caller that reads this serializer directly
+    rather than through ``ProjectNotificationPreferenceView``.
+    """
+
+    matrix = _ProjectNotificationMatrixField()
+    # The window is stored as a bare wall-clock range, so without these two the
+    # governed user cannot tell what "22:00" means (#3377). Workspace.timezone is
+    # itself member-readable (IsWorkspaceAdmin admits any role on safe methods), so
+    # this is not a disclosure question — it is that resolving the window client-side
+    # means re-implementing a four-tier chain across three models and keeping it in
+    # sync, and the winning *tier* is not derivable from the values at all. If
+    # GET /workspace/ is ever narrowed to IsWorkspaceAdminStrict (#1724), revisit
+    # whether these two should follow it; today they expose nothing new.
+    quiet_hours_timezone = serializers.SerializerMethodField()
+    quiet_hours_timezone_source = serializers.SerializerMethodField()
+
+    class Meta:
+        model = ProjectNotificationPreference
+        fields = [
+            "matrix",
+            "schema_version",
+            "paused",
+            "quiet_hours_enabled",
+            "quiet_hours_from",
+            "quiet_hours_until",
+            "quiet_hours_timezone",
+            "quiet_hours_timezone_source",
+            "updated_at",
+        ]
+        # quiet_hours_timezone* are SerializerMethodFields — inherently read-only, and
+        # DRF forbids naming a declared field here.
+        read_only_fields = ["schema_version", "updated_at"]
+
+    def _resolved_quiet_hours_tz(self, instance: ProjectNotificationPreference) -> tuple[str, str]:
+        """``(IANA name, tier)`` for this row's window, memoized per project.
+
+        Memoized because both method fields call it for the same row; keyed on the
+        project so a serializer instance reused across projects cannot report one
+        project's zone for another.
+
+        ``instance.project`` costs no query because the view primes the FK cache —
+        ``get_or_create`` populates ``fields_cache`` on its create branch but not on
+        the get branch, which is the common one.
+
+        The workspace tier is left to the resolver rather than pre-loaded into
+        ``context``. Pre-loading it would be wrong twice over on this endpoint: it
+        queries even when the project sets its own timezone and the chain never
+        reaches the workspace, and — because the natural pre-load is
+        ``Workspace.load()``, a get_or_create — a *read* of this endpoint on an
+        install with no singleton would create the row and then report
+        ``source="workspace"``, where the dispatcher (which never writes) would have
+        reported ``"server"``. The whole point of these fields is to say what dispatch
+        does. ``context["workspace"]`` is still honored for a caller that has one in
+        hand, matching ``projects.bulk_settings``.
+        """
+        from trueppm_api.apps.notifications.services import resolve_quiet_hours_timezone
+
+        cache: dict[Any, tuple[str, str]] = getattr(self, "_quiet_hours_tz_cache", {})
+        key = instance.project_id
+        if key not in cache:
+            zone, source = resolve_quiet_hours_timezone(
+                instance.project, workspace=self.context.get("workspace")
+            )
+            cache[key] = (zone.key, source)
+            self._quiet_hours_tz_cache = cache
+        return cache[key]
+
+    @extend_schema_field(serializers.CharField())
+    def get_quiet_hours_timezone(self, instance: ProjectNotificationPreference) -> str:
+        """IANA zone the stored ``quiet_hours_from``/``_until`` are interpreted in."""
+        return self._resolved_quiet_hours_tz(instance)[0]
+
+    @extend_schema_field(
+        serializers.ChoiceField(
+            choices=[
+                QUIET_HOURS_TZ_SOURCE_PROJECT,
+                QUIET_HOURS_TZ_SOURCE_WORKSPACE,
+                QUIET_HOURS_TZ_SOURCE_SERVER,
+                QUIET_HOURS_TZ_SOURCE_FALLBACK,
+            ]
+        )
+    )
+    def get_quiet_hours_timezone_source(self, instance: ProjectNotificationPreference) -> str:
+        """Which tier supplied it: ``project``, ``workspace``, ``server`` or ``fallback``.
+
+        Provenance, not decoration — ``project`` vs ``workspace`` is the difference
+        between "my project lead set this" and "the workspace admin did", and
+        ``fallback`` says the chain found nothing usable and landed on UTC.
+        """
+        return self._resolved_quiet_hours_tz(instance)[1]
+
+    def to_representation(self, instance: ProjectNotificationPreference) -> dict[str, Any]:
+        """Upgrade the stored matrix to the current shape on read.
+
+        The stored payload's version is the model's ``schema_version`` column
+        (rows predating the convention carry the migration default of 1 and
+        are already at the current 9-event shape, so the chain is a no-op for
+        them). Passing it explicitly keeps the column as the single source of
+        truth for "which shape is this" rather than sniffing the payload.
+        """
+        data = super().to_representation(instance)
+        matrix = data.get("matrix")
+        if isinstance(matrix, dict):
+            upgraded, version = migrate_payload(
+                SURFACE_PROJECT_NOTIFICATION_MATRIX,
+                matrix,
+                from_version=instance.schema_version,
+            )
+            # schema_version is exposed as a sibling metadata field, not mixed
+            # into the matrix event/channel grid — keep matrix the clean grid.
+            upgraded.pop("schema_version", None)
+            data["matrix"] = upgraded
+            data["schema_version"] = version
+        return data
+
+
+#: The published shape of ``event_delivery`` (#3396, #3399).
+#:
+#: Enumerated key-by-key rather than left as ``additionalProperties: {type: boolean}``
+#: because the key set is closed and derivable: it is exactly
+#: :data:`PROJECT_NOTIFICATION_DELIVERY_REPORTED_EVENTS`, the same tuple
+#: :func:`project_notification_event_delivery` iterates. Deriving it is the pin
+#: #3399 asked for — the declaration cannot report a different set of events than
+#: the classification does, because there is only one list. An open
+#: ``additionalProperties`` map would have typed the *values* and said nothing about
+#: which rows a client can expect, which is the half a client actually indexes into.
+#:
+#: The booleans themselves are deliberately NOT pinned to today's classification.
+#: Which rows are wired is runtime state that moves as dispatchers land
+#: (TODO(#3016)); baking ``comment_mention: true`` into the schema would turn the
+#: contract into a lie on the day the second dispatcher ships.
+#:
+#: ``propertyNames`` is JSON Schema and not OpenAPI 3.0 — see
+#: :data:`_PROJECT_NOTIFICATION_MATRIX_SCHEMA` for why this project cannot use it.
+_PROJECT_NOTIFICATION_EVENT_DELIVERY_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "description": (
+        "Which matrix rows are wired to a delivery path. `true` means toggling that "
+        "event's channels changes what gets delivered; `false` means the row is "
+        "rendered and stored but nothing dispatches it yet, so a client should label "
+        "it rather than imply a delivery that never happens. Reported as a server "
+        "fact so every client does not hard-code the same list and drift from it."
+    ),
+    "properties": {
+        event_type: {"type": "boolean"}
+        for event_type in PROJECT_NOTIFICATION_DELIVERY_REPORTED_EVENTS
+    },
+    "required": list(PROJECT_NOTIFICATION_DELIVERY_REPORTED_EVENTS),
+    "additionalProperties": False,
+}
+
+
+#: The published shape of ``channel_delivery`` (#3378).
+#:
+#: Same construction and the same reasoning as
+#: :data:`_PROJECT_NOTIFICATION_EVENT_DELIVERY_SCHEMA` one axis over: the key set is
+#: closed and derivable — it is exactly
+#: :data:`PROJECT_NOTIFICATION_DELIVERY_REPORTED_CHANNELS`, the tuple
+#: :func:`project_notification_channel_delivery` iterates — so the declaration
+#: cannot report a different set of channels than the matrix renders.
+#:
+#: The booleans are again NOT pinned to today's answer. Which channels deliver is
+#: runtime state that moves when an ADR-0049 ``NOTIFICATION_CHANNELS`` registration
+#: lands (TODO(#3252)); baking ``slack: false`` into the schema would turn the
+#: contract into a lie on the day one does.
+_PROJECT_NOTIFICATION_CHANNEL_DELIVERY_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "description": (
+        "Which matrix columns TruePPM has a delivery path for. `true` means an "
+        "enabled cell in that column can reach you once its event is also "
+        "dispatched; `false` means the "
+        "column is rendered and the preference stored, but nothing delivers on it "
+        "yet and no setting anywhere turns it on, so a client should label it "
+        "rather than imply a delivery that never happens. Orthogonal to "
+        "`event_delivery`: a cell is live only when its event is dispatched AND "
+        "its channel delivers. Server-global — it does not vary by user or project, "
+        "and rides on this per-user document only so a client can label the whole "
+        "grid in one render. Reported as a server fact so every client does not "
+        "hard-code the same list and drift from it."
+    ),
+    "properties": {
+        channel: {"type": "boolean"} for channel in PROJECT_NOTIFICATION_DELIVERY_REPORTED_CHANNELS
+    },
+    "required": list(PROJECT_NOTIFICATION_DELIVERY_REPORTED_CHANNELS),
+    "additionalProperties": False,
+}
+
+
+class ProjectNotificationPreferenceDocumentSerializer(ProjectNotificationPreferenceSerializer):
+    """What ``GET``/``PATCH .../notification-preferences/`` actually returns (#3396, #3399).
+
+    The stored row's fields **plus** ``event_delivery`` and ``channel_delivery``,
+    which the view adds on both methods and which are not model fields. Declaring
+    the plain serializer as the ``200`` would have been the obvious fix and a worse
+    one: the schema would be self-consistent, ``api:schema-drift`` would pass, and a
+    generated SDK would silently drop the two keys a client needs to label the rows
+    nothing dispatches and the columns nothing delivers on. A declared lie is more
+    dangerous than a declared absence.
+
+    Subclasses rather than restating the field list, so a field added to the parent
+    reaches the published response without a second edit. Only the two delivery maps
+    are named here, because only they are the difference.
+    """
+
+    event_delivery = serializers.SerializerMethodField()
+    channel_delivery = serializers.SerializerMethodField()
+
+    class Meta(ProjectNotificationPreferenceSerializer.Meta):
+        fields = [
+            *ProjectNotificationPreferenceSerializer.Meta.fields,
+            "event_delivery",
+            "channel_delivery",
+        ]
+
+    @extend_schema_field(_PROJECT_NOTIFICATION_EVENT_DELIVERY_SCHEMA)
+    def get_event_delivery(self, instance: ProjectNotificationPreference) -> dict[str, bool]:
+        """Row-independent: it reports server wiring, not this user's preferences."""
+        return project_notification_event_delivery()
+
+    @extend_schema_field(_PROJECT_NOTIFICATION_CHANNEL_DELIVERY_SCHEMA)
+    def get_channel_delivery(self, instance: ProjectNotificationPreference) -> dict[str, bool]:
+        """Column-independent, and row-independent: it reports which channels the
+        server delivers on at all, not anything about this user or project."""
+        return project_notification_channel_delivery()
+
+
+class UserNotificationSettingsSerializer(serializers.ModelSerializer[UserNotificationSettings]):
+    """Account-wide notification settings (#1707, ADR-0292; digest slot ADR-0663).
+
+    ``dnd_enabled`` plus the weekly digest slot (``digest_weekday`` /
+    ``digest_hour`` / ``digest_timezone``) are writable; ``updated_at`` is
+    read-only. The endpoint is self-scoped (the row is always the caller's own), so
+    there is no ``user`` field to expose or spoof.
+
+    The slot fields are range- and tz-validated rather than clamped: a bad value
+    must surface as a 400 the user can act on. Silently coercing hour 25 to 23
+    would leave someone waiting for a digest that arrives at the wrong time with no
+    indication anything was wrong.
+    """
+
+    class Meta:
+        model = UserNotificationSettings
+        fields = [
+            "dnd_enabled",
+            "digest_weekday",
+            "digest_hour",
+            "digest_timezone",
+            "updated_at",
+        ]
+        read_only_fields = ["updated_at"]
+
+    def validate_digest_weekday(self, value: int) -> int:
+        """0=Monday .. 6=Sunday, matching Python's ``date.weekday()``."""
+        if not 0 <= value <= 6:
+            raise serializers.ValidationError("Must be between 0 (Monday) and 6 (Sunday).")
+        return value
+
+    def validate_digest_hour(self, value: int) -> int:
+        """Local hour of day, 0-23."""
+        if not 0 <= value <= 23:
+            raise serializers.ValidationError("Must be between 0 and 23.")
+        return value
+
+    def validate_digest_timezone(self, value: str) -> str:
+        """An IANA key, or blank to use the server timezone.
+
+        Validated against the running interpreter's tz database so a typo is a 400
+        at save time rather than a digest that silently never fires.
+        """
+        if value and value not in zoneinfo.available_timezones():
+            raise serializers.ValidationError(f"Unknown timezone: {value!r}")
+        return value
+
+
+class WorkspaceEmailSettingsSerializer(serializers.ModelSerializer[WorkspaceEmailSettings]):
+    """Read/write serializer for the workspace SMTP singleton (#712, ADR-0213).
+
+    The password is **write-only** and never echoed — the response carries only
+    ``password_is_set``. On update, an omitted/blank ``password`` keeps the
+    stored secret (rotate-vs-keep); a non-empty value replaces it. The
+    validate-before-persist probe opens the candidate transport before ``save``
+    so a bad configuration cannot lock the workspace out of mail. All admin-
+    supplied network/header inputs are validated against SSRF and header
+    injection (security review H1/M2/M3).
+
+    Custom SMTP may be saved with **no authentication** — both ``username`` and
+    ``password`` blank (#4190) — for a relay on a trusted network that accepts
+    unauthenticated connections (Postfix ``mynetworks``, an in-cluster relay).
+    This is the in-app counterpart to the ``EMAIL_*`` env fallback, which has
+    always supported it. SendGrid and SES keep requiring a credential
+    unconditionally — they have no unauthenticated mode. See
+    ``_assert_transport_fields`` / the ``no_auth`` branch of ``validate()``.
+    """
+
+    # Write-only credential. required=False so other fields can be edited
+    # without re-submitting it; allow_blank so "" explicitly means "keep".
+    password = serializers.CharField(
+        write_only=True,
+        required=False,
+        allow_blank=True,
+        max_length=4096,
+        trim_whitespace=False,
+        style={"input_type": "password"},
+    )
+    password_is_set = serializers.BooleanField(read_only=True)
+
+    # Rows one drain tick may claim (#2860 rebound this from "addresses per message",
+    # which nothing implemented). The drain caps every tick at EMAIL_MAX_BATCH_SIZE
+    # regardless, because a tick runs under a 25 s soft time limit — so a larger value
+    # was accepted, persisted, echoed back and then silently discarded (#2887 item 2).
+    # Rejecting it out loud is the whole point: a control that reports a value it does
+    # not apply is the dead-control failure mode wearing a different hat. ``0`` means
+    # "no explicit cap" and falls back to EMAIL_MAX_BATCH_SIZE, which is why min_value
+    # is 0 rather than 1.
+    max_recipients = serializers.IntegerField(
+        required=False,
+        min_value=0,
+        max_value=EMAIL_MAX_BATCH_SIZE,
+        help_text=(
+            f"Queued emails one drain tick sends, 1-{EMAIL_MAX_BATCH_SIZE}. "
+            f"0 means no explicit cap ({EMAIL_MAX_BATCH_SIZE} per tick)."
+        ),
+    )
+
+    class Meta:
+        model = WorkspaceEmailSettings
+        fields = [
+            "transport_mode",
+            "host",
+            "port",
+            "security",
+            "username",
+            "password",
+            "password_is_set",
+            "from_name",
+            "from_email",
+            "reply_to",
+            "dkim_selector",
+            "max_recipients",
+            "throttle_per_min",
+            "updated_at",
+        ]
+        read_only_fields = ["updated_at"]
+
+    # -- field-level validation ------------------------------------------------
+
+    def validate_port(self, value: int) -> int:
+        if not (1 <= value <= 65535):
+            raise serializers.ValidationError("Port must be between 1 and 65535.")
+        return value
+
+    def validate_from_name(self, value: str) -> str:
+        # Header-injection guard: a CRLF in the From display name could inject
+        # extra headers. Django's sanitizer catches raw CRLF, but reject here
+        # for a clear message (security review M3).
+        if "\r" in value or "\n" in value:
+            raise serializers.ValidationError("From name must not contain line breaks.")
+        return value
+
+    def validate_dkim_selector(self, value: str) -> str:
+        if value and not _DKIM_SELECTOR_RE.match(value):
+            raise serializers.ValidationError(
+                "DKIM selector may contain only letters, digits, '.', '_', and '-'."
+            )
+        return value
+
+    # -- object-level validation + persist ------------------------------------
+
+    def validate(self, attrs: dict[str, Any]) -> dict[str, Any]:
+        instance = self.instance
+        # Bound rather than nested: a closure's own branching is charged to its
+        # enclosing function, and a module-level resolver is testable alone.
+        eff = partial(_effective, attrs, instance)
+
+        mode = eff("transport_mode", EmailTransportMode.CLOUD)
+        if mode == EmailTransportMode.CLOUD:
+            # Nothing to probe — fall back to the global backend at send time.
+            return attrs
+
+        host = (eff("host") or "").strip()
+        port = eff("port", 587)
+        security = eff("security", EmailSecurity.TLS)
+        username = (eff("username") or "").strip()
+
+        incoming_pw = attrs.get("password", "")
+        stored_pw = instance.get_password() if instance is not None else ""
+        mode_changed = instance is not None and instance.transport_mode != mode
+
+        # SMTP is the one transport that may run with no SMTP AUTH at all — a
+        # relay on a trusted network that accepts unauthenticated connections
+        # (Postfix `mynetworks`, an in-cluster relay), which the docs page has
+        # always named as a valid use for "Security: None" without any in-app
+        # way to configure it (#4190). A blank username carries no rotate-vs-
+        # keep secrecy (unlike password), so it always reflects what will
+        # actually be persisted — but password does, so the "no auth" signal
+        # has to be read off the *incoming* password, not the merged one: an
+        # operator who blanks the username while leaving password untouched
+        # (because a no-auth relay needs no password) must not have a stale
+        # credential from a previous auth-enabled config silently survive the
+        # switch. `_should_clear_password` tells `update()` to blank the
+        # stored ciphertext in that case even though no password was submitted
+        # this request — the alternative (leaving it in place) is exactly the
+        # "silently keep sending an old password" failure this closes.
+        no_auth = _is_no_auth_smtp(mode=mode, username=username, incoming_password=incoming_pw)
+        if no_auth:
+            effective_pw = ""
+            self._should_clear_password = bool(stored_pw)
+        else:
+            effective_pw = incoming_pw or stored_pw
+            self._should_clear_password = False
+
+        _assert_transport_fields(
+            mode=mode,
+            host=host,
+            username=username,
+            effective_pw=effective_pw,
+            needs_fresh_password=mode_changed and not incoming_pw and not no_auth,
+            no_auth=no_auth,
+        )
+        _probe_or_raise(
+            mode=mode,
+            host=host,
+            port=port,
+            security=security,
+            username=username,
+            password=effective_pw,
+        )
+
+        return attrs
+
+    def update(
+        self, instance: WorkspaceEmailSettings, validated_data: dict[str, Any]
+    ) -> WorkspaceEmailSettings:
+        password = validated_data.pop("password", None)
+        for field, value in validated_data.items():
+            setattr(instance, field, value)
+        # Rotate only when a non-empty password was submitted; blank keeps the
+        # stored ciphertext untouched (never overwrite with b"").
+        if password:
+            # This is a third-party SMTP relay credential (Fernet-encrypted at
+            # rest), not a Django auth password — validate_password() enforces
+            # user-account policy (min length, common-password blocklist) that is
+            # meaningless for a provider-issued secret the operator cannot change.
+            # nosemgrep: unvalidated-password
+            instance.set_password(password)
+        elif getattr(self, "_should_clear_password", False):
+            # The operator switched this SMTP transport to "no authentication"
+            # (#4190) without submitting a new password — clear whatever secret
+            # was stored under the previous auth-enabled config so it can never
+            # be silently reused if a username is added back later without also
+            # re-entering a password. Set in validate(), consumed once here.
+            # Same non-auth SMTP credential as the call above, so validate_password()
+            # does not apply; an empty value clears the stored ciphertext.
+            # nosemgrep: unvalidated-password
+            instance.set_password("")
+        request = self.context.get("request")
+        if request is not None and getattr(request, "user", None) is not None:
+            instance.updated_by = request.user
+        instance.save()
+        return instance