trueppm-api 0.4.0__py3-none-any.whl

trueppm_api/apps/workspace/signals.py

@@ -0,0 +1,37 @@
+"""Django signals for the workspace app.
+
+The ``audit_event_created`` signal is the OSS extension point for the Enterprise
+operational-audit layer (immutable/signed storage, retention policy, SOC-2
+export). Enterprise receivers connect via their own ``AppConfig.ready()`` without
+modifying OSS code — OSS never imports ``trueppm_enterprise`` (ADR-0157, #859).
+
+Usage (Enterprise side, never imported by OSS)::
+
+    # trueppm_enterprise/audit/apps.py
+    def ready(self):
+        from trueppm_api.apps.workspace.signals import audit_event_created
+        audit_event_created.connect(immutable_audit_receiver)
+
+.. warning::
+    The signal is emitted from ``transaction.on_commit()`` so a receiver only
+    ever sees a committed ``AuditEvent`` row (no phantom events on rollback).
+    Receivers that perform further I/O (HTTP calls, cross-DB writes) own the
+    durability of that downstream work.
+"""
+
+from __future__ import annotations
+
+import django.dispatch
+
+# Sent after an AuditEvent row is committed (ADR-0157, #859). This is the stable
+# seam Enterprise registers against to layer immutable/signed/SOC-2 storage on
+# top of the OSS event stream.
+#
+# Keyword arguments (payload schema is STABLE — do not change):
+#   sender       — the AuditEvent class
+#   audit_event  — the committed AuditEvent instance
+#
+# Fired via record_audit_event() using transaction.on_commit + send_robust, so a
+# raising enterprise receiver is swallowed-and-logged and can never break the OSS
+# write path. OSS connects no receiver.
+audit_event_created = django.dispatch.Signal()

trueppm_api/apps/workspace/tasks.py

@@ -0,0 +1,616 @@
+"""Celery tasks for the workspace app (ADR-0087 §Durable Execution).
+
+- ``drain_invite_emails`` — every 30 s, sends queued invite emails via the
+  transactional-outbox pattern (mirrors ``notifications.drain_notification_emails``).
+  A new invite is drain-eligible as soon as it commits and ``create_invite`` nudges
+  the drain from ``on_commit``, so first-send latency is seconds (#4191).
+- ``purge_stale_invites`` — nightly, marks expired pending invites and deletes
+  accepted/revoked/expired invites older than the retention window.
+- ``run_workspace_export`` — builds a full-workspace archive for one job and emails
+  the owner; idempotent + bounded retries (ADR-0174).
+- ``drain_workspace_exports`` — every 30 s, re-dispatches export jobs orphaned by a
+  broker outage at ``on_commit`` (5-min orphan window).
+- ``purge_expired_exports`` — nightly, deletes export jobs past their link expiry and
+  their stored archives.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import timedelta
+from typing import TYPE_CHECKING
+
+from celery import shared_task
+from celery.exceptions import SoftTimeLimitExceeded
+
+from trueppm_api.core.idempotent import idempotent_task
+
+if TYPE_CHECKING:
+    from django.core.mail.backends.base import BaseEmailBackend
+
+logger = logging.getLogger(__name__)
+
+EMAIL_MAX_RETRIES = 3
+# Minimum gap between a failed attempt and the next one (#4191). First sends are
+# immediate, but on_commit nudges run the drain far more often than the 30 s Beat
+# tick, so without this floor a short relay outage would burn all three attempts in
+# seconds and mark the invite FAILED. Keeps retries about one Beat tick apart.
+# Slightly under the 30 s tick so a Beat-only retry lands on the NEXT tick rather
+# racing it (a floor equal to the tick would skip one about half the time).
+EMAIL_RETRY_SPACING = timedelta(seconds=25)
+INVITE_RETENTION_DAYS = 30  # ADR-0087 §Durable item 6
+# Beat task name — also the key the per-minute throttle divisor is derived from
+# (#2887 item 4). This drain shares the workspace delivery limits with the
+# notification drain; it used to carry its own hardcoded EMAIL_BATCH_SIZE = 50 and
+# consult neither operator control, so an invite burst could double the configured
+# rate on the same 30 s cadence (#2887 item 3).
+DRAIN_TASK_NAME = "workspace.drain_invite_emails"
+
+EXPORT_MAX_RETRIES = 3  # ADR-0174 §Durable item 8
+EXPORT_ORPHAN_WINDOW_MINUTES = 5  # ADR-0174 §Durable item 3
+EXPORT_DRAIN_BATCH_SIZE = 10
+DEFAULT_EXPORT_RETENTION_DAYS = 7  # ADR-0174 §Durable item 6
+
+
+@idempotent_task(
+    lock_key_template="drain_invite_emails",
+    lock_ttl=60,
+    on_contention="skip",
+    soft_time_limit=25,
+    time_limit=30,
+    acks_late=True,
+    reject_on_worker_lost=True,
+    name="workspace.drain_invite_emails",
+)
+def drain_invite_emails(self: object) -> None:
+    """Send queued workspace-invite emails (runs every 30 s via Beat)."""
+    _do_drain_invite_emails()
+
+
+@idempotent_task(
+    lock_key_template="purge_stale_invites",
+    lock_ttl=120,
+    on_contention="skip",
+    soft_time_limit=55,
+    time_limit=90,
+    acks_late=True,
+    reject_on_worker_lost=True,
+    name="workspace.purge_stale_invites",
+)
+def purge_stale_invites(self: object) -> None:
+    """Expire overdue pending invites; delete terminal invites past retention."""
+    _do_purge_stale_invites()
+
+
+# ---------------------------------------------------------------------------
+# Drain — extracted for direct testability without Celery in the loop
+# ---------------------------------------------------------------------------
+
+
+def _do_drain_invite_emails() -> None:
+    from django.db.models import Q
+    from django.utils import timezone
+
+    from trueppm_api.apps.notifications.delivery_limits import (
+        EMAIL_MAX_BATCH_SIZE,
+        beat_ticks_per_minute,
+        per_tick_cap,
+        reserve_send_budget,
+    )
+    from trueppm_api.apps.notifications.email_backend import (
+        EmailTransportError,
+        resolve_email_connection,
+        resolve_from_email,
+    )
+    from trueppm_api.apps.notifications.models import WorkspaceEmailSettings
+
+    from .models import WorkspaceInvite
+
+    now = timezone.now()
+
+    # Same two-stage bound as the notification drain: a per-tick cap for smoothing,
+    # then a reservation against the per-minute budget every mail path shares.
+    email_settings = WorkspaceEmailSettings.load()
+    budget = reserve_send_budget(
+        int(email_settings.throttle_per_min or 0),
+        per_tick_cap(
+            email_settings,
+            ticks_per_minute=beat_ticks_per_minute(DRAIN_TASK_NAME),
+            fallback=EMAIL_MAX_BATCH_SIZE,
+        ),
+    )
+    granted = budget.granted
+    if granted <= 0:
+        return
+
+    pending = list(
+        WorkspaceInvite.objects.filter(
+            email_pending=True,
+            email_sent_at__isnull=True,
+            email_attempts__lt=EMAIL_MAX_RETRIES,
+            # No ``created_at`` age floor (#4191, ADR-0087 §Durable item 3 amendment).
+            # This drain is the only code that sends an invite, and overlapping drains
+            # are serialized by the singleton lock on ``drain_invite_emails`` — not by
+            # row age — so a 5-min floor excluded no in-flight owner and only delayed
+            # every first send. The drain cannot see an uncommitted row either way.
+        )
+        # Retries stay one tick apart even when nudges run the drain more often.
+        .filter(Q(email_failed_at__isnull=True) | Q(email_failed_at__lt=now - EMAIL_RETRY_SPACING))
+        .select_related("invited_by")
+        .order_by("created_at")[:granted]
+    )
+    budget.release(granted - len(pending))
+    if not pending:
+        return
+
+    # Resolve the transport ONCE per batch, and bail out without touching any row when
+    # it cannot be built (#2886 item 2). Resolving per invite would both re-connect N
+    # times and — now that an unusable transport raises rather than silently rerouting
+    # — burn all three retries on every queued invite and mark them FAILED for what is
+    # a configuration fault an operator fix clears.
+    try:
+        connection = resolve_email_connection(email_settings)
+    except EmailTransportError:
+        logger.error(
+            "drain_invite_emails: the configured mail transport is unusable — "
+            "%d invite(s) left pending, no retries burned. Fix the transport in "
+            "Workspace -> Email.",
+            len(pending),
+        )
+        budget.release(len(pending))
+        return
+    from_email = resolve_from_email(email_settings)
+
+    sent = 0
+    failed = 0
+    for invite in pending:
+        try:
+            ok = _send_invite_email(invite, connection=connection, from_email=from_email)
+        except SoftTimeLimitExceeded:
+            raise
+        except Exception:
+            logger.exception("drain_invite_emails: unexpected error for invite %s", invite.pk)
+            ok = False
+
+        if ok:
+            # Clearing email_token consumes the at-rest raw token — after a
+            # successful send only the SHA-256 hash remains (ADR-0087 §4).
+            WorkspaceInvite.objects.filter(pk=invite.pk).update(
+                email_pending=False,
+                email_sent_at=timezone.now(),
+                email_token="",
+            )
+            sent += 1
+        else:
+            from django.db.models import F
+
+            from .models import InviteStatus
+
+            new_attempts = invite.email_attempts + 1
+            update_fields: dict[str, object] = {
+                "email_attempts": F("email_attempts") + 1,
+                "email_failed_at": timezone.now(),
+            }
+            if new_attempts >= EMAIL_MAX_RETRIES:
+                # Terminal failure: stop draining, clear the raw token regardless so
+                # it does not linger at rest once the send path has given up, and
+                # mark the invite FAILED so it is visibly dead (an admin re-invites).
+                # The previous code left email_token populated forever on a row that
+                # would never send — exactly the at-rest retention the hash design
+                # exists to avoid (ADR-0087 §4).
+                update_fields["email_pending"] = False
+                update_fields["email_token"] = ""
+                update_fields["status"] = InviteStatus.FAILED
+            # Only a still-PENDING row: a concurrent revoke (#4589) must not be
+            # flipped back to FAILED, which is resendable.
+            WorkspaceInvite.objects.filter(pk=invite.pk, status=InviteStatus.PENDING).update(
+                **update_fields
+            )
+            failed += 1
+
+    logger.info("drain_invite_emails: sent=%d failed=%d candidates=%d", sent, failed, len(pending))
+
+
+# ---------------------------------------------------------------------------
+# Workspace export (ADR-0174, #641)
+# ---------------------------------------------------------------------------
+
+
+@shared_task(  # type: ignore[untyped-decorator]
+    bind=True,
+    max_retries=EXPORT_MAX_RETRIES,
+    soft_time_limit=600,
+    time_limit=660,
+    acks_late=True,
+    reject_on_worker_lost=True,
+    name="workspace.run_workspace_export",
+)
+def run_workspace_export(self: object, job_id: str) -> None:
+    """Build the full-workspace archive for ``job_id`` and email the owner.
+
+    Idempotent: claims the job under ``select_for_update`` and no-ops unless it is
+    ``pending``/``running``, so a duplicate delivery (broker retry, drain re-dispatch)
+    cannot produce two archives. Transient failures retry up to ``EXPORT_MAX_RETRIES``
+    (the job stays ``running`` so a retry is allowed); on exhaustion the job is marked
+    ``failed`` and the owner can request a fresh export.
+    """
+    # Claim the job (idempotency gate).
+    from django.db import transaction
+    from django.utils import timezone
+
+    from .export import build_and_store_archive
+    from .models import ExportJobStatus, WorkspaceExportJob
+
+    with transaction.atomic():
+        job = WorkspaceExportJob.objects.select_for_update().filter(pk=job_id).first()
+        if job is None:
+            logger.warning("run_workspace_export: job %s not found", job_id)
+            return
+        if job.status not in (ExportJobStatus.PENDING, ExportJobStatus.RUNNING):
+            logger.info("run_workspace_export: job %s already %s, skipping", job_id, job.status)
+            return
+        job.status = ExportJobStatus.RUNNING
+        job.started_at = timezone.now()
+        job.celery_task_id = getattr(getattr(self, "request", None), "id", "") or ""
+        job.save(update_fields=["status", "started_at", "celery_task_id"])
+
+    try:
+        storage_path, size = build_and_store_archive(job_id)
+    except Exception as exc:
+        retries = getattr(getattr(self, "request", None), "retries", 0)
+        if retries < EXPORT_MAX_RETRIES:
+            logger.warning("run_workspace_export: job %s failed, retrying", job_id, exc_info=True)
+            raise self.retry(exc=exc, countdown=10 * (2**retries)) from exc  # type: ignore[attr-defined]
+        logger.exception("run_workspace_export: job %s failed permanently", job_id)
+        WorkspaceExportJob.objects.filter(pk=job_id).update(
+            status=ExportJobStatus.FAILED,
+            error_detail=str(exc)[:2000],
+            completed_at=timezone.now(),
+        )
+        return
+
+    retention = _export_retention_days()
+    expires_at = timezone.now() + timedelta(days=retention) if retention is not None else None
+    WorkspaceExportJob.objects.filter(pk=job_id).update(
+        status=ExportJobStatus.SUCCESS,
+        file_path=storage_path,
+        file_size=size,
+        expires_at=expires_at,
+        completed_at=timezone.now(),
+        error_detail="",
+    )
+    _send_export_ready_email(job_id)
+
+
+@idempotent_task(
+    lock_key_template="drain_workspace_exports",
+    lock_ttl=60,
+    on_contention="skip",
+    soft_time_limit=25,
+    time_limit=30,
+    acks_late=True,
+    reject_on_worker_lost=True,
+    name="workspace.drain_workspace_exports",
+)
+def drain_workspace_exports(self: object) -> None:
+    """Re-dispatch export jobs stuck in ``pending`` (broker down at on_commit)."""
+    _do_drain_workspace_exports()
+
+
+@idempotent_task(
+    lock_key_template="purge_expired_exports",
+    lock_ttl=120,
+    on_contention="skip",
+    soft_time_limit=55,
+    time_limit=90,
+    acks_late=True,
+    reject_on_worker_lost=True,
+    name="workspace.purge_expired_exports",
+)
+def purge_expired_exports(self: object) -> None:
+    """Delete export jobs past their link expiry, and their stored archives."""
+    _do_purge_expired_exports()
+
+
+def _export_retention_days() -> int | None:
+    from django.conf import settings
+
+    return getattr(settings, "TRUEPPM_EXPORT_RETENTION_DAYS", DEFAULT_EXPORT_RETENTION_DAYS)
+
+
+def _do_drain_workspace_exports() -> None:
+    from django.utils import timezone
+
+    from .models import ExportJobStatus, WorkspaceExportJob
+
+    orphan_cutoff = timezone.now() - timedelta(minutes=EXPORT_ORPHAN_WINDOW_MINUTES)
+    stuck = list(
+        WorkspaceExportJob.objects.filter(
+            status=ExportJobStatus.PENDING,
+            celery_task_id="",
+            created_at__lt=orphan_cutoff,
+        ).order_by("created_at")[:EXPORT_DRAIN_BATCH_SIZE]
+    )
+    if not stuck:
+        return
+    for job in stuck:
+        try:
+            run_workspace_export.delay(str(job.id))
+        except SoftTimeLimitExceeded:
+            raise
+        except Exception:  # pragma: no cover - broker still down, next tick retries
+            logger.warning("drain_workspace_exports: broker still unavailable for %s", job.id)
+            break
+    logger.info("drain_workspace_exports: re-dispatched %d job(s)", len(stuck))
+
+
+def _do_purge_expired_exports() -> None:
+    from django.core.files.storage import default_storage
+    from django.utils import timezone
+
+    from .models import WorkspaceExportJob
+
+    retention = _export_retention_days()
+    if retention is None:  # retention disabled — keep archives indefinitely
+        return
+    expired = WorkspaceExportJob.objects.filter(expires_at__lt=timezone.now())
+    count = 0
+    for job in expired.iterator():
+        if job.file_path:
+            try:
+                default_storage.delete(job.file_path)
+            except OSError:  # pragma: no cover - storage drift, still drop the row
+                logger.warning("purge_expired_exports: could not delete file for %s", job.id)
+        job.delete()
+        count += 1
+    if count:
+        logger.info("purge_expired_exports: deleted %d expired export(s)", count)
+
+
+def _send_export_ready_email(job_id: str) -> bool:
+    """Notify the owner their export is ready. Best-effort (returns success).
+
+    Deactivated accounts are excluded (#3585). Off-boarding is a **second,
+    independent revocation axis** from membership (``access/signals.py``): it writes
+    ``WorkspaceMembership.status = DEACTIVATED`` and ``User.is_active = False`` and
+    touches neither the export job nor the project/program membership rows, so a job
+    queued while the requester was still active and completed after off-boarding kept
+    mailing them — announcing that a **full workspace data export** is ready to
+    download, at an address the account no longer controls. Every *credential* path
+    already closes on ``is_active`` (JWT, session, PAT, live sockets); this notice is
+    *pushed*, so nothing was closing it.
+
+    The floor deliberately sits **above** the transport and the budget, which is how
+    the terminal-state discipline of !2399 (#3523) maps onto this path. There is no
+    outbox row to retire here: the export notice is a single-shot send off the back of
+    ``run_workspace_export``, and its terminal state is the job's own ``SUCCESS``,
+    already written before this function is called. What carries over is the rule that
+    a *suppression must not be recorded as a delivery failure* — returning before
+    ``resolve_email_connection`` and ``note_unbudgeted_send`` means an off-boarding
+    logs no "mail transport unusable" warning, charges nothing against the shared
+    per-minute budget every mail rail draws on, and leaves the job ``SUCCESS`` with an
+    empty ``error_detail``. No operator-facing signal reports a personnel change as a
+    broken mail relay, and nothing re-queues, so the notice cannot retry forever.
+    """
+    from django.core.mail import EmailMessage
+
+    from .models import WorkspaceExportJob
+
+    job = WorkspaceExportJob.objects.select_related("requested_by").filter(pk=job_id).first()
+    if job is None or job.requested_by is None or not job.requested_by.email:
+        return False
+    if not job.requested_by.is_active:
+        logger.info("export ready email: recipient for job %s is deactivated, not sending", job_id)
+        return False
+
+    subject, body = _render_export_email(job)
+    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,
+    )
+
+    # Send on the workspace SMTP transport (#712, ADR-0213); no-op fall back to
+    # the global backend when unconfigured. A single transactional message, so it
+    # charges the shared per-minute budget without being refused by it (#2887 item 3)
+    # — the queued drains yield to it rather than the reverse.
+    try:
+        connection = resolve_email_connection()
+    except Exception:
+        logger.warning("export ready email: mail transport unusable for job %s", job_id)
+        return False
+    note_unbudgeted_send(workspace_throttle_per_min())
+    msg = EmailMessage(
+        subject=subject,
+        body=body,
+        from_email=resolve_from_email(),
+        to=[job.requested_by.email],
+        connection=connection,
+    )
+    try:
+        msg.send(fail_silently=False)
+    except Exception:
+        logger.warning("export ready email failed for job %s", job_id, exc_info=True)
+        return False
+    return True
+
+
+def _render_export_email(job: object) -> tuple[str, str]:
+    """Render the export-ready (subject, body). Degrades to prose, never a bad link.
+
+    When ``FRONTEND_BASE_URL`` is unset, a relative ``/settings/workspace/danger``
+    path is not a valid URL and resolves nowhere for a mail client — so it is
+    omitted rather than emitted, and the body instead tells the recipient where to
+    navigate once signed in. Unlike the invite email below, this degrades safely:
+    the recipient already has an account (this email addresses ``job.requested_by``,
+    ADR-0174), so "sign in and find it" is a real fallback rather than a dead end.
+    """
+    from django.conf import settings
+
+    from .models import Workspace
+
+    workspace_name = Workspace.load().name
+    base = (getattr(settings, "FRONTEND_BASE_URL", "") or "").rstrip("/")
+    subject = f"Your {workspace_name} export is ready"
+    if base:
+        # The link lands on the danger page, which fetches the job and offers an
+        # authenticated download — we never email a raw, unauthenticated archive URL.
+        download_lines = [
+            "Download it from the workspace danger zone:",
+            f"{base}/settings/workspace/danger",
+        ]
+    else:
+        download_lines = [
+            "Sign in to TruePPM and open Settings -> Workspace -> Danger Zone to download it.",
+        ]
+    body = "\n".join(
+        [
+            f"Your full export of {workspace_name} has finished and is ready to download.",
+            "",
+            *download_lines,
+            "",
+            "The download link expires after a few days; request a new export if it lapses.",
+        ]
+    )
+    return subject, body
+
+
+def _do_purge_stale_invites() -> None:
+    from django.utils import timezone
+
+    from .models import InviteStatus, WorkspaceInvite
+
+    now = timezone.now()
+    expired = WorkspaceInvite.objects.filter(
+        status=InviteStatus.PENDING, expires_at__lt=now
+    ).update(status=InviteStatus.EXPIRED, email_pending=False, email_token="")
+
+    cutoff = now - timedelta(days=INVITE_RETENTION_DAYS)
+    deleted, _ = WorkspaceInvite.objects.filter(
+        status__in=[
+            InviteStatus.ACCEPTED,
+            InviteStatus.REVOKED,
+            InviteStatus.EXPIRED,
+            InviteStatus.FAILED,
+        ],
+        created_at__lt=cutoff,
+    ).delete()
+    if expired or deleted:
+        logger.info("purge_stale_invites: expired=%d deleted=%d", expired, deleted)
+
+
+# ---------------------------------------------------------------------------
+# Email rendering
+# ---------------------------------------------------------------------------
+
+
+def _send_invite_email(
+    invite: object,
+    *,
+    connection: BaseEmailBackend | None = None,
+    from_email: str | None = None,
+) -> bool:
+    """Render and send the invitation email. Returns True on SMTP success.
+
+    The transport and From identity are resolved **once per drain batch** and passed
+    in; when omitted they are resolved here so a direct/one-off caller still works. A
+    caller that resolves them itself is also the one that can distinguish an unusable
+    transport (a configuration fault, no retries burned) from a failed send.
+
+    Deliberately **not** floored on ``User.is_active``, unlike
+    :func:`_send_export_ready_email` (#3585). An invite addresses
+    ``WorkspaceInvite.email``, a raw address for someone who by definition has no
+    account yet — there is no ``User`` row to read ``is_active`` from, so the account
+    axis is not the right one here. The invite's own revocation axis is its
+    ``status``/``expires_at``, enforced by the drain's candidate query and by
+    ``purge_stale_invites``. Adding an ``is_active`` check would either be dead code
+    or, worse, would silently drop invites to addresses that happen to collide with a
+    deactivated account's — re-inviting an off-boarded person is a legitimate act.
+    """
+    from django.core.mail import EmailMessage
+
+    from .models import WorkspaceInvite
+
+    inv: WorkspaceInvite = invite  # type: ignore[assignment]
+    if not inv.email or not inv.email_token:
+        return False
+
+    subject, body = _render_invite_email(inv)
+    from trueppm_api.apps.notifications.email_backend import (
+        resolve_email_connection,
+        resolve_from_email,
+    )
+
+    # Send on the workspace SMTP transport (#712, ADR-0213); no-op fall back to
+    # the global backend when unconfigured.
+    msg = EmailMessage(
+        subject=subject,
+        body=body,
+        from_email=resolve_from_email() if from_email is None else from_email,
+        to=[inv.email],
+        connection=resolve_email_connection() if connection is None else connection,
+    )
+    try:
+        msg.send(fail_silently=False)
+    # TODO(#4421): swallows SoftTimeLimitExceeded; the drain-loop guard
+    # is ineffective until this is fixed
+    except Exception:
+        logger.warning("drain_invite_emails: SMTP send failed for invite %s", inv.pk, exc_info=True)
+        return False
+    return True
+
+
+def _render_invite_email(invite: object) -> tuple[str, str]:
+    """Render the invite (subject, body). Degrades to prose, never a bad link.
+
+    When ``FRONTEND_BASE_URL`` is unset, a relative ``/invite/accept?token=...``
+    path is not a valid URL and resolves nowhere for a mail client, so it is
+    omitted rather than emitted. Unlike the export-ready email above, there is no
+    in-app fallback to point at: the recipient has no account yet, and the raw
+    token is cleared from ``email_token`` the moment this send is recorded as
+    successful (ADR-0087 §4) — so once this body goes out without the link, that
+    token cannot be recovered. The only path forward is fixing the setting and
+    resending (``WorkspaceInviteResendView`` mints a fresh token), which the copy
+    says explicitly.
+    """
+    from django.conf import settings
+
+    from .models import Workspace, WorkspaceInvite, WorkspaceRole
+
+    inv: WorkspaceInvite = invite  # type: ignore[assignment]
+    workspace_name = Workspace.load().name
+    base = (getattr(settings, "FRONTEND_BASE_URL", "") or "").rstrip("/")
+
+    inviter = inv.invited_by
+    inviter_name = (
+        (inviter.get_full_name() or inviter.username) if inviter is not None else "An admin"
+    )
+    role_label = WorkspaceRole(inv.role).label
+
+    subject = f"You've been invited to {workspace_name} on TruePPM"
+    if base:
+        accept_lines = [
+            "Accept your invitation:",
+            f"{base}/invite/accept?token={inv.email_token}",
+        ]
+    else:
+        accept_lines = [
+            "This TruePPM deployment has no public URL configured, so this email "
+            "cannot include an invitation link. Ask whoever invited you to set "
+            "TRUEPPM_FRONTEND_BASE_URL and resend the invitation.",
+        ]
+    body = "\n".join(
+        [
+            f"{inviter_name} has invited you to join {workspace_name} with the {role_label} role.",
+            "",
+            *accept_lines,
+            "",
+            f"This invitation expires on {inv.expires_at:%Y-%m-%d}.",
+            "",
+            "If you weren't expecting this, you can ignore this email.",
+        ]
+    )
+    return subject, body