511 lines
21 KiB
Python
511 lines
21 KiB
Python
"""Inbound email webhook + admin mailbox CRUD endpoints.
|
|
|
|
The webhook is intentionally public (no auth). Trust rests on two checks, and
|
|
it takes both. The signature alone is not enough:
|
|
|
|
1. `verify_sns_message` proves the payload was signed by AWS SNS. That rules
|
|
out arbitrary JSON posted at the URL, but note what it does *not* prove:
|
|
anyone with an AWS account can create a topic, so a valid signature only
|
|
says the message came from *some* topic in *some* account.
|
|
2. The TopicArn pin (`InboundMailbox.topic_arn`) proves it came from *this
|
|
mailbox's* topic. Without it, anyone who learned a mailbox UUID could point
|
|
their own SNS topic here and have AWS sign forged mail for them, which,
|
|
because the pipeline threads replies onto existing cases, means injecting
|
|
messages into live customer conversations, not just spam tickets.
|
|
|
|
A mailbox gets its pin one of two ways. An admin enters the Topic ARN on the
|
|
mailbox, or, while it has none, a signature-verified SubscriptionConfirmation
|
|
pins its TopicArn, but only when that topic belongs to an AWS account listed in
|
|
the `INBOUND_SNS_ACCOUNT_IDS` setting. SNS lets any AWS account subscribe any
|
|
HTTPS endpoint to its own topic, so pinning whichever confirmation came first
|
|
handed the mailbox to whoever subscribed it first. With no pin and no allowed
|
|
account, every message is refused. Once pinned, only that exact ARN is accepted
|
|
and a confirmation never re-pins.
|
|
|
|
Neither check says the mail was meant for *this* mailbox. One topic may fan
|
|
out to many mailboxes (a platform-wide SES receipt rule, say, now that
|
|
`INBOUND_SNS_ACCOUNT_IDS` lets every mailbox pin a topic in the platform
|
|
account), so each would receive every org's mail. A notification is therefore
|
|
ingested only when the mailbox's address is one of its recipients, and is
|
|
otherwise acknowledged and discarded without writing anything in this org.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import base64
|
|
import binascii
|
|
import email.utils
|
|
import json
|
|
import logging
|
|
from datetime import timedelta
|
|
|
|
from django.conf import settings
|
|
from django.db.models import Count, Max
|
|
from django.utils import timezone
|
|
from drf_spectacular.utils import extend_schema, inline_serializer
|
|
from rest_framework import serializers, status
|
|
from rest_framework.permissions import AllowAny, IsAuthenticated
|
|
from rest_framework.response import Response
|
|
from rest_framework.views import APIView
|
|
|
|
from cases.inbound.parser import parse_raw_email
|
|
from cases.inbound.pipeline import ingest
|
|
from cases.inbound.sns import (
|
|
SNSVerificationError,
|
|
confirm_subscription,
|
|
topic_account_id,
|
|
verify_sns_message,
|
|
)
|
|
from cases.models import EmailMessage, InboundMailbox
|
|
from cases.serializer import InboundMailboxSerializer
|
|
from common.models import PortalAccessToken
|
|
from common.modules import module_is_available
|
|
from common.org_time import activate_org_timezone
|
|
from common.permissions import HasOrgContext, is_org_admin
|
|
from common.portal_tokens import resolve_portal_org
|
|
from common.tasks import set_rls_context
|
|
|
|
logger = logging.getLogger(__name__)
|
|
|
|
# Window the mailbox page reports ticket counts over.
|
|
MAILBOX_WINDOW_DAYS = 30
|
|
|
|
|
|
def _mailbox_analytics(org):
|
|
"""Per-mailbox ticket counts + last-received timestamp, plus an org total.
|
|
|
|
Both come from the ``EmailMessage.mailbox`` FK (set at ingest since the
|
|
migration): a message records exactly which inbound address it arrived
|
|
through, so these are attributed, not guessed.
|
|
|
|
- ``cases_last_30d`` per mailbox = distinct cases *created* in the last 30
|
|
days that have an inbound message through that mailbox (a reply arriving
|
|
at the address for an older case is not a new ticket, so we anchor on the
|
|
case's ``created_at``).
|
|
- ``last_received_at`` per mailbox = the newest inbound message's
|
|
``received_at`` (any message, including dropped ones, the address still
|
|
received mail).
|
|
- org ``cases_last_30d`` = distinct such cases across all mailboxes (not a
|
|
sum, so a case cross-posted to two addresses is not double counted).
|
|
|
|
All scoped to ``org`` explicitly (RLS is inert in dev/test).
|
|
"""
|
|
cutoff = timezone.now() - timedelta(days=MAILBOX_WINDOW_DAYS)
|
|
inbound = EmailMessage.objects.filter(
|
|
org=org, direction="inbound", mailbox__isnull=False
|
|
)
|
|
created = (
|
|
inbound.filter(case__isnull=False, case__created_at__gte=cutoff)
|
|
.values("mailbox_id")
|
|
.annotate(n=Count("case", distinct=True))
|
|
)
|
|
cases_by_mailbox = {str(row["mailbox_id"]): row["n"] for row in created}
|
|
last = inbound.values("mailbox_id").annotate(last=Max("received_at"))
|
|
last_by_mailbox = {str(row["mailbox_id"]): row["last"] for row in last}
|
|
total_cases = (
|
|
inbound.filter(case__isnull=False, case__created_at__gte=cutoff)
|
|
.values("case")
|
|
.distinct()
|
|
.count()
|
|
)
|
|
return cases_by_mailbox, last_by_mailbox, total_cases
|
|
|
|
|
|
def _admin_required():
|
|
return Response(
|
|
{"error": True, "errors": "Admin access required"},
|
|
status=status.HTTP_403_FORBIDDEN,
|
|
)
|
|
|
|
|
|
def _unwrap_sns_message(message):
|
|
"""Split an SNS Notification's `Message` into (raw email, recipients).
|
|
|
|
SES's SNS receipt action publishes a JSON notification: the raw email in
|
|
`content`, and in `receipt.recipients` the envelope RCPT TO addresses the
|
|
receipt rule matched. SES sets those, Bcc included, and the sender cannot
|
|
forge them. A `Message` that is not a JSON object is taken to be the raw
|
|
email itself, and the recipients come back as None: the caller then has
|
|
only the message's own headers to go on.
|
|
"""
|
|
try:
|
|
envelope = json.loads(message)
|
|
except (ValueError, TypeError):
|
|
return message, None
|
|
if not isinstance(envelope, dict):
|
|
return message, None
|
|
receipt = envelope.get("receipt")
|
|
recipients = receipt.get("recipients") if isinstance(receipt, dict) else None
|
|
if not isinstance(recipients, list):
|
|
recipients = []
|
|
content = envelope.get("content")
|
|
if not isinstance(content, str):
|
|
content = ""
|
|
# The SNS action's Encoding option may be Base64. A raw email always has a
|
|
# `Name: value` header, and ":" is outside the base64 alphabet, so content
|
|
# without one is the encoded form.
|
|
if content and ":" not in content:
|
|
try:
|
|
content = base64.b64decode("".join(content.split()), validate=True)
|
|
except (binascii.Error, ValueError):
|
|
pass
|
|
return content, [r for r in recipients if isinstance(r, str)]
|
|
|
|
|
|
def _addressed_to(mailbox, recipients):
|
|
"""Whether `mailbox.address` is one of `recipients`, ignoring case, spaces
|
|
and display names. Exact otherwise: `support+x@` is a different address."""
|
|
target = mailbox.address.strip().lower()
|
|
return any(
|
|
addr.strip().lower() == target
|
|
for _, addr in email.utils.getaddresses(recipients)
|
|
)
|
|
|
|
|
|
def _topic_rejected():
|
|
"""Deliberately as opaque as the signature failure. A caller probing the
|
|
webhook shouldn't learn whether a mailbox is pinned or to what."""
|
|
return Response(
|
|
{"error": True, "errors": "Signature verification failed"},
|
|
status=status.HTTP_403_FORBIDDEN,
|
|
)
|
|
|
|
|
|
class InboundMailboxWebhookView(APIView):
|
|
"""Public endpoint where AWS SNS POSTs for one configured mailbox.
|
|
|
|
URL: `/api/cases/inbound/<mailbox_id>/`. The mailbox lookup also acts as
|
|
the org boundary, the URL embeds the per-mailbox UUID so the webhook
|
|
can't be confused for one belonging to a different tenant.
|
|
|
|
The request is anonymous, so it carries no org, and `inbound_mailbox` is
|
|
org-scoped: under the non-superuser production role an empty RLS context
|
|
hides the very row that would name the org. The org therefore comes first
|
|
from the unscoped `PortalAccessToken` lookup (registered when the mailbox
|
|
is created, see cases/signals.py), then the context is set, and only then
|
|
is the mailbox read, within that org. `RequireOrgContext` exempts this one
|
|
route by name for the same reason.
|
|
"""
|
|
|
|
authentication_classes = ()
|
|
permission_classes = (AllowAny,)
|
|
|
|
@extend_schema(
|
|
tags=["InboundEmail"],
|
|
request=inline_serializer(
|
|
name="SNSInboundPayload",
|
|
fields={
|
|
"Type": serializers.CharField(),
|
|
"Message": serializers.CharField(),
|
|
"Signature": serializers.CharField(),
|
|
"SigningCertURL": serializers.CharField(),
|
|
},
|
|
),
|
|
responses={
|
|
200: inline_serializer(
|
|
name="InboundWebhookResponse",
|
|
fields={
|
|
"ok": serializers.BooleanField(),
|
|
"case_id": serializers.CharField(allow_null=True, required=False),
|
|
"dropped": serializers.BooleanField(required=False),
|
|
"reason": serializers.CharField(required=False),
|
|
},
|
|
)
|
|
},
|
|
)
|
|
def post(self, request, mailbox_id, *args, **kwargs):
|
|
# Don't leak which UUIDs exist: an unknown id, one whose mailbox is
|
|
# inactive or gone, and one in an org with Tickets off all get this 404.
|
|
not_found = Response(
|
|
{"error": True, "errors": "Mailbox not found"},
|
|
status=status.HTTP_404_NOT_FOUND,
|
|
)
|
|
# `mailbox_id` is already the canonical UUID string: the `uid` path
|
|
# converter normalises every form it accepts (any case, bare hex,
|
|
# braces, URN), and the lookup is keyed on that canonical form.
|
|
org_id = resolve_portal_org(mailbox_id, PortalAccessToken.INBOUND_MAILBOX)
|
|
if org_id is None:
|
|
return not_found
|
|
# No middleware sets a context for an anonymous request, so set it
|
|
# before any ORM read/write touches an org-scoped table.
|
|
set_rls_context(org_id)
|
|
mailbox = (
|
|
InboundMailbox.objects.filter(pk=mailbox_id, org_id=org_id, is_active=True)
|
|
.select_related("org")
|
|
.first()
|
|
)
|
|
if mailbox is None or not module_is_available(mailbox.org, "tickets"):
|
|
return not_found
|
|
|
|
# Likewise the org's day: the reopen window a reply is judged against
|
|
# counts days since close on the org's calendar, not UTC's.
|
|
# `GetProfileAndOrg` deactivates it when the request ends.
|
|
activate_org_timezone(mailbox.org)
|
|
|
|
if mailbox.provider != "ses":
|
|
# Other providers wired into the same URL space land here.
|
|
return Response(
|
|
{
|
|
"error": True,
|
|
"errors": f"Provider {mailbox.provider!r} not yet supported",
|
|
},
|
|
status=status.HTTP_501_NOT_IMPLEMENTED,
|
|
)
|
|
|
|
# SNS posts the JSON body in `request.body`. DRF may have parsed it.
|
|
try:
|
|
payload = (
|
|
request.data
|
|
if isinstance(request.data, dict)
|
|
else json.loads(request.body or b"{}")
|
|
)
|
|
except (ValueError, TypeError):
|
|
return Response(
|
|
{"error": True, "errors": "Body is not valid JSON"},
|
|
status=status.HTTP_400_BAD_REQUEST,
|
|
)
|
|
|
|
try:
|
|
verify_sns_message(payload)
|
|
except SNSVerificationError as exc:
|
|
logger.warning(
|
|
"SNS verification failed for mailbox=%s: %s", mailbox.id, exc
|
|
)
|
|
return Response(
|
|
{"error": True, "errors": "Signature verification failed"},
|
|
status=status.HTTP_403_FORBIDDEN,
|
|
)
|
|
|
|
# A valid signature only proves the message came from *some* SNS topic
|
|
# in *some* AWS account. Pin it to this mailbox's topic, or anyone who
|
|
# learns the mailbox UUID can have AWS sign forged mail for them.
|
|
msg_type = payload.get("Type")
|
|
topic_arn = payload.get("TopicArn") or ""
|
|
pinned = mailbox.topic_arn or ""
|
|
if pinned:
|
|
if topic_arn != pinned:
|
|
logger.warning(
|
|
"SNS TopicArn mismatch for mailbox=%s: got %r",
|
|
mailbox.id,
|
|
topic_arn,
|
|
)
|
|
return _topic_rejected()
|
|
elif (
|
|
msg_type == "SubscriptionConfirmation"
|
|
and topic_account_id(topic_arn) in settings.INBOUND_SNS_ACCOUNT_IDS
|
|
):
|
|
# No admin-entered ARN, and the topic belongs to an AWS account
|
|
# the operator allows. The confirmation is signature-verified
|
|
# above, so it really came from that account's topic. A topic in
|
|
# any other account pins nothing: SNS lets anyone subscribe this
|
|
# URL, and the first to do so would otherwise own the mailbox.
|
|
mailbox.topic_arn = topic_arn
|
|
mailbox.save(update_fields=["topic_arn"])
|
|
logger.info("Pinned mailbox=%s to TopicArn=%r", mailbox.id, topic_arn)
|
|
else:
|
|
# Unpinned mailbox, and this message can't establish a pin: it is
|
|
# a notification, or its topic is malformed or in an AWS account
|
|
# missing from INBOUND_SNS_ACCOUNT_IDS.
|
|
logger.warning(
|
|
"Rejecting SNS message for unpinned mailbox=%s (type=%r, topic=%r)",
|
|
mailbox.id,
|
|
msg_type,
|
|
topic_arn,
|
|
)
|
|
return _topic_rejected()
|
|
|
|
if msg_type == "SubscriptionConfirmation":
|
|
try:
|
|
confirm_subscription(payload)
|
|
except Exception:
|
|
logger.exception("SNS subscription confirmation failed")
|
|
return Response(
|
|
{"error": True, "errors": "SubscribeURL fetch failed"},
|
|
status=status.HTTP_502_BAD_GATEWAY,
|
|
)
|
|
return Response({"ok": True, "subscribed": True})
|
|
|
|
if msg_type == "UnsubscribeConfirmation": # pragma: no cover: informational
|
|
logger.info("SNS unsubscribe for mailbox=%s", mailbox.id)
|
|
return Response({"ok": True, "unsubscribed": True})
|
|
|
|
if msg_type != "Notification":
|
|
return Response(
|
|
{"error": True, "errors": f"Unsupported SNS Type: {msg_type!r}"},
|
|
status=status.HTTP_400_BAD_REQUEST,
|
|
)
|
|
|
|
# SES's SNS action sends a JSON notification carrying the raw email; a
|
|
# bare raw RFC 5322 string (another publisher on the pinned topic) is
|
|
# accepted too. See `_unwrap_sns_message`.
|
|
raw_message, recipients = _unwrap_sns_message(payload.get("Message") or "")
|
|
|
|
if not raw_message:
|
|
return Response(
|
|
{"error": True, "errors": "SNS Message body is empty"},
|
|
status=status.HTTP_400_BAD_REQUEST,
|
|
)
|
|
|
|
parsed = parse_raw_email(raw_message)
|
|
if recipients is None:
|
|
# No SES envelope, so fall back to the headers a relay stamps with
|
|
# the delivery address, then To and Cc.
|
|
recipients = [
|
|
*parsed.delivered_to,
|
|
*parsed.to_addresses,
|
|
*parsed.cc_addresses,
|
|
]
|
|
if not _addressed_to(mailbox, recipients):
|
|
# The topic also serves other mailboxes and this mail belongs to
|
|
# one of them. Storing anything here, even a dropped audit row,
|
|
# would copy another tenant's mail into this org. A 200 stops SNS
|
|
# retrying; the log names the mailbox only, never an address.
|
|
logger.warning(
|
|
"Dropping SNS notification not addressed to mailbox=%s", mailbox.id
|
|
)
|
|
return Response(
|
|
{"ok": True, "dropped": True, "reason": "not_addressed_to_mailbox"},
|
|
status=status.HTTP_200_OK,
|
|
)
|
|
result = ingest(parsed, mailbox)
|
|
|
|
return Response(
|
|
{
|
|
"ok": True,
|
|
"case_id": str(result.case.id) if result.case else None,
|
|
"dropped": result.dropped,
|
|
"reason": result.drop_reason,
|
|
"created_case": result.created_case,
|
|
},
|
|
status=status.HTTP_200_OK,
|
|
)
|
|
|
|
|
|
class InboundMailboxListCreateView(APIView):
|
|
permission_classes = (IsAuthenticated, HasOrgContext)
|
|
|
|
@extend_schema(
|
|
tags=["InboundEmail"], responses={200: InboundMailboxSerializer(many=True)}
|
|
)
|
|
def get(self, request, *args, **kwargs):
|
|
org = request.profile.org
|
|
qs = InboundMailbox.objects.filter(org=org).order_by("address")
|
|
mailboxes = InboundMailboxSerializer(
|
|
qs, many=True, context={"request": request}
|
|
).data
|
|
cases_by, last_by, total_cases = _mailbox_analytics(org)
|
|
active = 0
|
|
for mbx in mailboxes:
|
|
mid = str(mbx["id"])
|
|
mbx["cases_last_30d"] = cases_by.get(mid, 0)
|
|
received = last_by.get(mid)
|
|
mbx["last_received_at"] = received.isoformat() if received else None
|
|
if mbx["is_active"]:
|
|
active += 1
|
|
totals = {
|
|
"count": len(mailboxes),
|
|
"active": active,
|
|
"cases_last_30d": total_cases,
|
|
}
|
|
return Response({"mailboxes": mailboxes, "totals": totals})
|
|
|
|
@extend_schema(
|
|
tags=["InboundEmail"],
|
|
request=InboundMailboxSerializer,
|
|
responses={201: InboundMailboxSerializer},
|
|
)
|
|
def post(self, request, *args, **kwargs):
|
|
if not is_org_admin(request.profile):
|
|
return _admin_required()
|
|
org = request.profile.org
|
|
# No webhook secret is generated here. This used to mint a
|
|
# `secrets.token_urlsafe(32)` when the body carried none, and nothing
|
|
# ever compared the result: SES delivery is authenticated by the SNS
|
|
# signature plus the `topic_arn` pin, both handled in
|
|
# `InboundMailboxWebhookView.post`. Now that the field is write-only,
|
|
# a generated value could not be read back either, so every mailbox
|
|
# would carry a secret no one holds. An empty column reads honestly as
|
|
# "not configured", which is also what a future provider integration
|
|
# needs in order to tell configured mailboxes from unconfigured ones.
|
|
serializer = InboundMailboxSerializer(
|
|
data=request.data, context={"org": org, "request": request}
|
|
)
|
|
if not serializer.is_valid():
|
|
return Response(
|
|
{"error": True, "errors": serializer.errors},
|
|
status=status.HTTP_400_BAD_REQUEST,
|
|
)
|
|
serializer.save(org=org)
|
|
return Response(serializer.data, status=status.HTTP_201_CREATED)
|
|
|
|
|
|
class InboundMailboxDetailView(APIView):
|
|
permission_classes = (IsAuthenticated, HasOrgContext)
|
|
|
|
def _get_object(self, pk, org):
|
|
return InboundMailbox.objects.filter(pk=pk, org=org).first()
|
|
|
|
@extend_schema(tags=["InboundEmail"], responses={200: InboundMailboxSerializer})
|
|
def get(self, request, pk, *args, **kwargs):
|
|
obj = self._get_object(pk, request.profile.org)
|
|
if not obj:
|
|
return Response(
|
|
{"error": True, "errors": "Mailbox not found"},
|
|
status=status.HTTP_404_NOT_FOUND,
|
|
)
|
|
return Response(
|
|
InboundMailboxSerializer(obj, context={"request": request}).data
|
|
)
|
|
|
|
@extend_schema(
|
|
tags=["InboundEmail"],
|
|
request=InboundMailboxSerializer,
|
|
responses={200: InboundMailboxSerializer},
|
|
)
|
|
def put(self, request, pk, *args, **kwargs):
|
|
if not is_org_admin(request.profile):
|
|
return _admin_required()
|
|
org = request.profile.org
|
|
obj = self._get_object(pk, org)
|
|
if not obj:
|
|
return Response(
|
|
{"error": True, "errors": "Mailbox not found"},
|
|
status=status.HTTP_404_NOT_FOUND,
|
|
)
|
|
serializer = InboundMailboxSerializer(
|
|
obj,
|
|
data=request.data,
|
|
partial=True,
|
|
context={"org": org, "request": request},
|
|
)
|
|
if not serializer.is_valid():
|
|
return Response(
|
|
{"error": True, "errors": serializer.errors},
|
|
status=status.HTTP_400_BAD_REQUEST,
|
|
)
|
|
serializer.save()
|
|
return Response(serializer.data)
|
|
|
|
@extend_schema(
|
|
tags=["InboundEmail"],
|
|
responses={
|
|
200: inline_serializer(
|
|
name="MailboxDeleteResponse",
|
|
fields={
|
|
"error": serializers.BooleanField(),
|
|
"message": serializers.CharField(),
|
|
},
|
|
)
|
|
},
|
|
)
|
|
def delete(self, request, pk, *args, **kwargs):
|
|
if not is_org_admin(request.profile):
|
|
return _admin_required()
|
|
obj = self._get_object(pk, request.profile.org)
|
|
if not obj:
|
|
return Response(
|
|
{"error": True, "errors": "Mailbox not found"},
|
|
status=status.HTTP_404_NOT_FOUND,
|
|
)
|
|
obj.delete()
|
|
return Response({"error": False, "message": "Mailbox deleted"})
|