trueppm-api 0.4.0b2__py3-none-any.whl

trueppm_api/apps/notifications/email_backend.py

@@ -0,0 +1,330 @@
+"""Dynamic outbound-mail connection resolution (#712, ADR-0213).
+
+All transactional mail is sent through a connection returned by
+:func:`resolve_email_connection`, which reads the writable
+:class:`~trueppm_api.apps.notifications.models.WorkspaceEmailSettings` singleton
+and builds a ``django.core.mail`` SMTP connection from it — overriding the
+process-global ``EMAIL_BACKEND`` when a transport is configured. When the
+workspace transport is ``cloud`` (the unconfigured default) it falls back to the
+global backend, so a fresh install behaves exactly as it did before #712.
+
+Security posture (ADR-0213 §4, security review C1/H1/H2/M1):
+- The custom SMTP / SES host is SSRF-checked with ``assert_host_allowed`` both
+  at save (serializer) *and* here at send time — closing the DNS-rebinding
+  window where a host resolves public at save and private at send.
+- The Fernet-encrypted password is decrypted only here, server-side, never
+  logged and never returned by the API.
+- Connection-build failures raise :class:`EmailTransportError` carrying a
+  generic message; callers must not surface the underlying ``smtplib``
+  exception (which can echo credentials) to clients.
+
+Fail-closed on a configured-but-unusable transport (#2886 item 2). This module
+used to log a warning and fall back to the process-global ``EMAIL_BACKEND`` when
+the stored password would not decrypt or the stored host failed the egress guard.
+The intent — one corrupt row must not dead-letter a whole drain batch — was
+sound; the effect was that mail configured for the operator's relay went out over
+an entirely different transport (or into a console/dummy backend and nowhere at
+all) while the Email settings page still reported ``configured_via: "database"``
+and ``password_is_set: true``. Both faults now raise
+:class:`EmailTransportError`, and the queued drains catch it, log an ERROR, and
+leave their rows pending rather than burning retries on a configuration fault
+that an operator fix will clear. :func:`transport_status` exposes the same
+condition as a read-derived signal, which is what the System Health card and the
+``trueppm_email_transport_unavailable`` gauge report on — the fail-closed path is
+therefore observable rather than merely silent-but-safe.
+
+This matches ``apps.integrations.encryption``, which has always been fail-closed:
+``decrypt_secret`` raises ``CredentialEncryptionError`` rather than returning a
+usable-looking empty string. Falling open was this module's own deviation from
+the mechanism it borrows.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from django.conf import settings
+from django.core.mail import get_connection
+
+if TYPE_CHECKING:
+    from django.core.mail.backends.base import BaseEmailBackend
+
+    from .models import WorkspaceEmailSettings
+
+logger = logging.getLogger(__name__)
+
+_SMTP_BACKEND = "django.core.mail.backends.smtp.EmailBackend"
+
+# Provider-fixed relay parameters. SendGrid's SMTP relay uses a constant host and
+# the literal username "apikey" (the API key travels as the password); SES uses a
+# region-specific host that the UI composes into ``host`` (ADR-0213 §2). Both are
+# STARTTLS on 587, so 0.4 needs no backend class beyond Django's SMTP backend.
+SENDGRID_HOST = "smtp.sendgrid.net"
+SENDGRID_PORT = 587
+SENDGRID_USERNAME = "apikey"
+SES_PORT = 587
+
+
+class EmailTransportError(RuntimeError):
+    """A workspace mail transport could not be built or opened.
+
+    Carries a client-safe message only — never the underlying ``smtplib``
+    exception or the connection kwargs (which include the password).
+    """
+
+
+def _effective_smtp(
+    *,
+    transport_mode: str,
+    host: str,
+    port: int,
+    security: str,
+    username: str,
+) -> tuple[str, int, str, str]:
+    """Resolve (host, port, username, security) after applying provider defaults.
+
+    Each provider's fixed host/port/username is applied so the caller only ever
+    supplies the credential and (for SES) the region-composed host.
+    """
+    if transport_mode == "sendgrid":
+        return SENDGRID_HOST, SENDGRID_PORT, SENDGRID_USERNAME, "tls"
+    if transport_mode == "ses":
+        # host is the region relay (email-smtp.<region>.amazonaws.com), composed
+        # by the UI; only port/security are forced.
+        return host, SES_PORT, username, "tls"
+    return host, port, username, security
+
+
+def build_smtp_connection(
+    *,
+    transport_mode: str,
+    host: str,
+    port: int,
+    security: str,
+    username: str,
+    password: str,
+    validate_host: bool = True,
+) -> BaseEmailBackend:
+    """Build (but do not open) an SMTP connection for a non-cloud transport.
+
+    Used both by the serializer's validate-before-persist probe (with the
+    *incoming* candidate values) and by :func:`resolve_email_connection` (with
+    the persisted model values). Re-runs the SSRF host check unless a caller has
+    already validated the exact same host in the same request.
+
+    Raises:
+        EmailTransportError: The host resolves to a non-public address.
+    """
+    eff_host, eff_port, eff_username, eff_security = _effective_smtp(
+        transport_mode=transport_mode,
+        host=host,
+        port=port,
+        security=security,
+        username=username,
+    )
+    if validate_host:
+        _assert_host_public(eff_host, eff_port)
+    # Never enable smtplib debuglevel — it prints the base64 AUTH line
+    # (username + password) to stderr (security review M1).
+    conn = get_connection(
+        _SMTP_BACKEND,
+        host=eff_host,
+        port=eff_port,
+        username=eff_username,
+        password=password,
+        use_tls=eff_security == "tls",
+        use_ssl=eff_security == "ssl",
+        timeout=getattr(settings, "EMAIL_TIMEOUT", 10),
+    )
+    return conn
+
+
+def _assert_host_public(host: str, port: int) -> None:
+    """SSRF guard for the SMTP relay host (ADR-0213 §4). Blocks internal targets.
+
+    A DNS-resolution failure is allowed through (the host may resolve later and
+    the actual connect will fail cleanly), mirroring the webhook-URL validator;
+    a host that resolves to a private/loopback/link-local/metadata address is
+    rejected outright.
+    """
+    from trueppm_api.apps.integrations.http import (
+        EgressBlocked,
+        EgressError,
+        assert_host_allowed,
+    )
+
+    try:
+        assert_host_allowed(host, port)
+    except EgressBlocked as exc:
+        # Do NOT copy the EgressBlocked text into EmailTransportError: it can
+        # embed the DNS-resolved internal address, which the serializer would
+        # otherwise surface to the client (SSRF oracle). Log the detail, raise a
+        # curated message (security review M1; CodeQL py/stack-trace-exposure).
+        logger.info("SMTP host rejected by egress guard (host=%s port=%s): %s", host, port, exc)
+        raise EmailTransportError(
+            "The mail server host is not permitted — it resolves to a non-public address."
+        ) from exc
+    except EgressError:
+        # Unresolvable now; the connect attempt re-checks and fails cleanly.
+        return
+
+
+def probe_transport(
+    *,
+    transport_mode: str,
+    host: str,
+    port: int,
+    security: str,
+    username: str,
+    password: str,
+) -> None:
+    """Open and immediately close a candidate SMTP connection, or raise.
+
+    The validate-before-persist gate (ADR-0213 §3): a bad transport must be
+    rejected *before* the row is written so the workspace can't be locked out of
+    mail. Raises :class:`EmailTransportError` with a **generic** message on any
+    build or connect failure — the underlying ``smtplib`` exception (which can
+    echo credentials) is deliberately swallowed (security review M1).
+    """
+    try:
+        conn = build_smtp_connection(
+            transport_mode=transport_mode,
+            host=host,
+            port=port,
+            security=security,
+            username=username,
+            password=password,
+        )
+    except EmailTransportError:
+        raise
+    try:
+        conn.open()
+        conn.close()
+    except Exception as exc:
+        logger.info(
+            "probe_transport: connect failed (transport=%s host=%s port=%s)",
+            transport_mode,
+            host,
+            port,
+        )
+        raise EmailTransportError(
+            "Could not connect to the mail server. Check the host, port, security, and credentials."
+        ) from exc
+
+
+# Read-derived transport-status literals (#2886). Reported by the System Health
+# notification card and by the ``trueppm_email_transport_unavailable`` gauge.
+TRANSPORT_OK = "ok"
+TRANSPORT_GLOBAL = "global"  # cloud / unconfigured — the process-global backend
+TRANSPORT_UNDECRYPTABLE = "undecryptable"
+
+
+def resolve_email_connection(
+    settings_obj: WorkspaceEmailSettings | None = None,
+) -> BaseEmailBackend:
+    """Return the mail connection for the workspace's configured transport.
+
+    ``cloud`` / unconfigured → the process-global ``EMAIL_BACKEND`` (today's
+    behaviour). Otherwise an SMTP connection built from the singleton, with the
+    password decrypted here and the host SSRF-re-checked at send time.
+
+    Raises:
+        EmailTransportError: The workspace has a transport configured but it cannot
+            be built — the stored password will not decrypt (the encryption key
+            rotated out from under the row) or the stored host fails the egress
+            guard. This is deliberately **not** a fall back to the global backend:
+            sending the operator's mail over a transport they did not configure,
+            while the settings page reports the configured one, is a silent reroute
+            (#2886 item 2). Callers on a queued path catch this and leave their rows
+            pending; callers on a synchronous path surface a generic failure.
+    """
+    from .models import EmailTransportMode, WorkspaceEmailSettings
+
+    obj = settings_obj or WorkspaceEmailSettings.load()
+    if obj.transport_mode == EmailTransportMode.CLOUD:
+        return get_connection()
+
+    try:
+        password = obj.get_password()
+    except Exception as exc:
+        # ERROR, not WARNING: no mail leaves the workspace until an operator
+        # re-enters the password, so this is an outage rather than a degradation.
+        logger.error(
+            "resolve_email_connection: could not decrypt the stored SMTP password "
+            "(transport=%s host=%s) — refusing to send over a different transport. "
+            "The encryption key may have rotated; re-enter the password in "
+            "Workspace -> Email.",
+            obj.transport_mode,
+            obj.host,
+        )
+        raise EmailTransportError(
+            "The stored mail credential could not be decrypted. Re-enter the "
+            "password for this transport."
+        ) from exc
+
+    return build_smtp_connection(
+        transport_mode=str(obj.transport_mode),
+        host=obj.host,
+        port=obj.port,
+        security=str(obj.security),
+        username=obj.username,
+        password=password,
+    )
+
+
+def transport_status(settings_obj: WorkspaceEmailSettings | None = None) -> str:
+    """Classify whether the configured transport's credential can be used, on read.
+
+    The credential fault in :func:`resolve_email_connection` is a deterministic
+    function of committed state (the stored ciphertext) and live configuration (the
+    encryption key) — not of anything a worker writes. So the web process can evaluate
+    it directly, which is what makes this a *positive* health signal rather than an
+    inference from the absence of one: it is true at the instant the credential breaks,
+    with no row having to fail first and no window in which anything could clear it.
+
+    Deliberately does **not** re-run the egress guard. That check resolves DNS, and
+    this function is called on a polled health endpoint and a Prometheus scrape — a
+    lookup per poll is a real egress and latency cost for a fault the queued-backlog
+    signal already catches (a host the guard rejects makes every send raise, so rows
+    stay pending and the notification card's aging-backlog signal fires).
+
+    Returns one of :data:`TRANSPORT_OK`, :data:`TRANSPORT_GLOBAL` (no workspace
+    transport configured — the process-global backend is in use, which is the shipped
+    default and not a fault), or :data:`TRANSPORT_UNDECRYPTABLE`. Never raises: a
+    status probe that can throw is unusable in a health endpoint.
+    """
+    from .models import EmailTransportMode, WorkspaceEmailSettings
+
+    try:
+        obj = settings_obj or WorkspaceEmailSettings.load()
+        if obj.transport_mode == EmailTransportMode.CLOUD:
+            return TRANSPORT_GLOBAL
+        try:
+            obj.get_password()
+        except Exception:
+            return TRANSPORT_UNDECRYPTABLE
+    except Exception:  # pragma: no cover — guard, not behavior
+        logger.warning("transport_status: could not classify the mail transport", exc_info=True)
+        return TRANSPORT_OK
+    return TRANSPORT_OK
+
+
+def resolve_from_email(settings_obj: WorkspaceEmailSettings | None = None) -> str:
+    """Return the effective From header ("Name <addr>" or the settings default)."""
+    from .models import WorkspaceEmailSettings
+
+    obj = settings_obj or WorkspaceEmailSettings.load()
+    addr = obj.from_email.strip()
+    if not addr:
+        return getattr(settings, "DEFAULT_FROM_EMAIL", "notifications@trueppm.local")
+    name = obj.from_name.strip()
+    return f"{name} <{addr}>" if name else addr
+
+
+def resolve_reply_to(settings_obj: WorkspaceEmailSettings | None = None) -> list[str]:
+    """Return the reply-to list for outbound mail, or [] when unset."""
+    from .models import WorkspaceEmailSettings
+
+    obj = settings_obj or WorkspaceEmailSettings.load()
+    return [obj.reply_to.strip()] if obj.reply_to.strip() else []

trueppm_api/apps/notifications/email_health.py

@@ -0,0 +1,128 @@
+"""Deliverability (SPF / DKIM / DMARC) health checks for the From domain.
+
+Live DNS TXT lookups for the workspace From-address domain (#712, ADR-0213 §4).
+Bounded and defensive per the security review (M4): a short per-query timeout, a
+capped number of records, TXT-only lookups (never opens a connection to the
+domain), and the target domain is derived solely from the *persisted, validated*
+``from_email`` — never from request input. The endpoint is operator-gated and
+throttled by the caller.
+
+Each check returns ``pass`` / ``warn`` / ``fail``. When the DNS resolver is
+unavailable the whole surface degrades to ``available = False`` rather than
+erroring, so a resolver-less host shows "checks unavailable" instead of a
+failure.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TypedDict
+
+logger = logging.getLogger(__name__)
+
+# Bound every lookup: a slow/hostile authoritative resolver must not hang the
+# request, and an oversized TXT set must not balloon the response.
+_DNS_TIMEOUT_SECONDS = 3.0
+_MAX_TXT_RECORDS = 20
+
+
+class HealthResult(TypedDict):
+    available: bool
+    domain: str
+    spf: str
+    dkim: str
+    dmarc: str
+
+
+def _empty(domain: str, *, available: bool) -> HealthResult:
+    status = "unknown"
+    return {
+        "available": available,
+        "domain": domain,
+        "spf": status,
+        "dkim": status,
+        "dmarc": status,
+    }
+
+
+def _txt_records(name: str) -> list[str]:
+    """Return decoded TXT strings for ``name`` (bounded), or [] on any DNS miss."""
+    import dns.resolver  # local import: optional at runtime, degrades gracefully
+
+    resolver = dns.resolver.Resolver()
+    resolver.lifetime = _DNS_TIMEOUT_SECONDS
+    resolver.timeout = _DNS_TIMEOUT_SECONDS
+    try:
+        answer = resolver.resolve(name, "TXT")
+    except Exception:
+        # NXDOMAIN, timeout, no-answer, servfail — all mean "record not found".
+        return []
+    records: list[str] = []
+    for rdata in answer:
+        # Each TXT rdata is one or more byte strings; join then decode.
+        try:
+            value = b"".join(getattr(rdata, "strings", [])).decode("utf-8", "replace")
+        except Exception:  # pragma: no cover — defensive
+            continue
+        records.append(value)
+        if len(records) >= _MAX_TXT_RECORDS:
+            break
+    return records
+
+
+def check_deliverability(from_email: str, dkim_selector: str = "") -> HealthResult:
+    """Resolve SPF / DKIM / DMARC posture for the From domain.
+
+    ``from_email`` is the persisted, EmailField-validated address; the domain is
+    everything after the last ``@``. Returns ``available = False`` when there is
+    no From domain or the DNS resolver is not installed.
+    """
+    domain = from_email.rsplit("@", 1)[-1].strip().lower() if "@" in from_email else ""
+    if not domain:
+        return _empty(domain, available=False)
+
+    try:
+        import dns.resolver  # noqa: F401 — availability probe
+    except ImportError:  # pragma: no cover — dnspython is a hard dependency
+        logger.info("check_deliverability: dnspython not installed; degrading")
+        return _empty(domain, available=False)
+
+    # SPF: a v=spf1 TXT record on the apex.
+    spf_records = _txt_records(domain)
+    spf_terms = [r for r in spf_records if r.lower().startswith("v=spf1")]
+    if not spf_terms:
+        spf = "fail"
+    elif any("-all" in r for r in spf_terms):
+        spf = "pass"
+    else:
+        # ~all / ?all — present but not enforcing.
+        spf = "warn"
+
+    # DMARC: a v=DMARC1 TXT record at _dmarc.<domain>.
+    dmarc_records = [
+        r for r in _txt_records(f"_dmarc.{domain}") if r.lower().startswith("v=dmarc1")
+    ]
+    if not dmarc_records:
+        dmarc = "fail"
+    elif any("p=reject" in r.lower() or "p=quarantine" in r.lower() for r in dmarc_records):
+        dmarc = "pass"
+    else:
+        dmarc = "warn"  # p=none (monitoring only)
+
+    # DKIM: only checkable when a selector is configured; look up
+    # <selector>._domainkey.<domain> for a v=DKIM1 / k= record.
+    selector = dkim_selector.strip()
+    if not selector:
+        dkim = "warn"  # no selector configured — can't verify
+    else:
+        dkim_records = _txt_records(f"{selector}._domainkey.{domain}")
+        has_dkim = any("v=dkim1" in r.lower() or "k=" in r.lower() for r in dkim_records)
+        dkim = "pass" if has_dkim else "fail"
+
+    return {
+        "available": True,
+        "domain": domain,
+        "spf": spf,
+        "dkim": dkim,
+        "dmarc": dmarc,
+    }

trueppm_api/apps/notifications/migrations/0001_initial.py

@@ -0,0 +1,207 @@
+# Generated by Django 6.0.3 on 2026-05-20 02:41
+
+import uuid
+
+import django.db.models.deletion
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    initial = True
+
+    dependencies = [
+        ("projects", "0038_taskcomment_commentreaction_commentacknowledgement_and_more"),
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="Mention",
+            fields=[
+                (
+                    "id",
+                    models.UUIDField(
+                        default=uuid.uuid4, editable=False, primary_key=True, serialize=False
+                    ),
+                ),
+                ("mentioned_group_key", models.CharField(blank=True, default="", max_length=32)),
+                (
+                    "scope",
+                    models.CharField(
+                        choices=[
+                            ("project_visible", "Project visible"),
+                            ("team_only", "Team only"),
+                            ("private", "Private"),
+                        ],
+                        default="project_visible",
+                        max_length=32,
+                    ),
+                ),
+                ("created_at", models.DateTimeField(auto_now_add=True, db_index=True)),
+                (
+                    "mentioned_user",
+                    models.ForeignKey(
+                        blank=True,
+                        null=True,
+                        on_delete=django.db.models.deletion.SET_NULL,
+                        related_name="mentions_received",
+                        to=settings.AUTH_USER_MODEL,
+                    ),
+                ),
+                (
+                    "mentioner",
+                    models.ForeignKey(
+                        null=True,
+                        on_delete=django.db.models.deletion.SET_NULL,
+                        related_name="mentions_authored",
+                        to=settings.AUTH_USER_MODEL,
+                    ),
+                ),
+                (
+                    "project",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="mentions",
+                        to="projects.project",
+                    ),
+                ),
+                (
+                    "task_comment",
+                    models.ForeignKey(
+                        blank=True,
+                        null=True,
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="mentions",
+                        to="projects.taskcomment",
+                    ),
+                ),
+            ],
+            options={
+                "db_table": "notifications_mention",
+                "ordering": ["-created_at"],
+            },
+        ),
+        migrations.CreateModel(
+            name="Notification",
+            fields=[
+                (
+                    "id",
+                    models.UUIDField(
+                        default=uuid.uuid4, editable=False, primary_key=True, serialize=False
+                    ),
+                ),
+                ("is_read", models.BooleanField(db_index=True, default=False)),
+                ("is_archived", models.BooleanField(default=False)),
+                ("created_at", models.DateTimeField(auto_now_add=True, db_index=True)),
+                ("read_at", models.DateTimeField(blank=True, null=True)),
+                ("email_pending", models.BooleanField(db_index=True, default=False)),
+                ("email_sent_at", models.DateTimeField(blank=True, null=True)),
+                ("email_failed_at", models.DateTimeField(blank=True, null=True)),
+                ("email_attempts", models.PositiveIntegerField(default=0)),
+                (
+                    "mention",
+                    models.ForeignKey(
+                        blank=True,
+                        null=True,
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="notifications",
+                        to="notifications.mention",
+                    ),
+                ),
+                (
+                    "project",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="notifications",
+                        to="projects.project",
+                    ),
+                ),
+                (
+                    "recipient",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="notifications",
+                        to=settings.AUTH_USER_MODEL,
+                    ),
+                ),
+            ],
+            options={
+                "db_table": "notifications_notification",
+                "ordering": ["-created_at"],
+            },
+        ),
+        migrations.CreateModel(
+            name="NotificationPreference",
+            fields=[
+                (
+                    "id",
+                    models.BigAutoField(
+                        auto_created=True, primary_key=True, serialize=False, verbose_name="ID"
+                    ),
+                ),
+                ("event_type", models.CharField(max_length=64)),
+                ("channel", models.CharField(max_length=32)),
+                ("enabled", models.BooleanField()),
+                ("updated_at", models.DateTimeField(auto_now=True)),
+                (
+                    "user",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="notification_preferences",
+                        to=settings.AUTH_USER_MODEL,
+                    ),
+                ),
+            ],
+            options={
+                "db_table": "notifications_preference",
+            },
+        ),
+        migrations.AddIndex(
+            model_name="mention",
+            index=models.Index(
+                fields=["mentioned_user", "-created_at"], name="ix_mention_user_recent"
+            ),
+        ),
+        migrations.AddIndex(
+            model_name="mention",
+            index=models.Index(fields=["project", "-created_at"], name="ix_mention_project_recent"),
+        ),
+        migrations.AddConstraint(
+            model_name="mention",
+            constraint=models.CheckConstraint(
+                condition=models.Q(
+                    ("mentioned_user__isnull", False),
+                    models.Q(("mentioned_group_key", ""), _negated=True),
+                    _connector="OR",
+                ),
+                name="mention_must_have_target",
+            ),
+        ),
+        migrations.AddConstraint(
+            model_name="mention",
+            constraint=models.CheckConstraint(
+                condition=models.Q(("task_comment__isnull", False)), name="mention_must_have_source"
+            ),
+        ),
+        migrations.AddIndex(
+            model_name="notification",
+            index=models.Index(
+                fields=["recipient", "is_read", "-created_at"], name="ix_notif_unread"
+            ),
+        ),
+        migrations.AddIndex(
+            model_name="notification",
+            index=models.Index(
+                condition=models.Q(("email_pending", True)),
+                fields=["email_pending", "-created_at"],
+                name="ix_notif_email_pending",
+            ),
+        ),
+        migrations.AddConstraint(
+            model_name="notificationpreference",
+            constraint=models.UniqueConstraint(
+                fields=("user", "event_type", "channel"), name="uq_notifpref_user_event_channel"
+            ),
+        ),
+    ]