trueppm-api 0.4.0b2__py3-none-any.whl

trueppm_api/apps/integrations/notification_channels.py

@@ -0,0 +1,57 @@
+"""OSS ``NOTIFICATION_CHANNELS`` registrations (ADR-0049 §1, ADR-0085 §2).
+
+Two channels ship in OSS: ``in_app`` (the durable inbox row) and ``email``
+(SMTP, opt-in). The registry's job is to (a) validate the ``channel`` field on
+``NotificationPreference`` rows against a known key set, and (b) be the seam
+Enterprise registers ``slack_dm`` / ``teams_dm`` / ``sms`` against without an
+OSS migration.
+
+OSS delivery does NOT go through ``handler.send()`` — fan-out is the bulk
+``notifications/services.py::create_event_notifications`` path (in-app row +
+``email_pending`` flag) drained by ``drain_notification_emails``. The ``send``
+stubs therefore raise ``NotImplementedError``; they exist so the registry has a
+concrete handler per key (mirrors the #637 ``TaskLinkProvider`` stubs). Enterprise
+channels implement a real ``send``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar
+
+from .registry import NotificationChannel
+
+
+class InAppNotificationChannel(NotificationChannel):
+    """The in-app inbox channel — the durable Notification row."""
+
+    key: ClassVar[str] = "in_app"
+    label: ClassVar[str] = "In-app"
+
+    def send(self, user: Any, event: Any) -> Any:
+        raise NotImplementedError(
+            "OSS in-app delivery is the Notification row created by "
+            "create_event_notifications; the registry entry is for channel "
+            "validation, not a per-event send."
+        )
+
+
+class EmailNotificationChannel(NotificationChannel):
+    """The email channel — SMTP via the existing notification email drain."""
+
+    key: ClassVar[str] = "email"
+    label: ClassVar[str] = "Email"
+
+    def send(self, user: Any, event: Any) -> Any:
+        raise NotImplementedError(
+            "OSS email delivery is the email_pending row drained by "
+            "drain_notification_emails; the registry entry is for channel "
+            "validation, not a per-event send."
+        )
+
+
+# Ordered tuple — apps.py iterates these in declaration order so OSS
+# registration order is deterministic for tests + the preferences UI.
+OSS_NOTIFICATION_CHANNELS: tuple[type[NotificationChannel], ...] = (
+    InAppNotificationChannel,
+    EmailNotificationChannel,
+)

trueppm_api/apps/integrations/opengraph.py

@@ -0,0 +1,229 @@
+"""OpenGraph / Twitter-Card scraping for cloud-file link previews (#571, ADR-0163).
+
+A cloud-file ``TaskLinkProvider`` fetches a pasted file URL through the
+SSRF-guarded :mod:`~trueppm_api.apps.integrations.http` helper and hands the
+(already size-capped, redirect-disabled) response body here. This module turns
+that HTML into a :class:`PreviewData` — the ``{title, description, thumbnail,
+preview_type}`` the preview card renders.
+
+Why the standard library and not BeautifulSoup/lxml: the job is "pull a handful
+of ``<meta>`` tags and ``<title>`` out of an already-bounded (256 KB) body."
+``html.parser.HTMLParser`` does that with zero new dependencies (no license/CVE
+audit) and has no entity-expansion ("billion laughs") exposure the way an XML
+parser would. The parser is deliberately lenient — malformed markup yields an
+empty :class:`PreviewData`, never an exception, matching ``fetch_metadata``'s
+"never raise for an unreachable/garbage provider" contract.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from html.parser import HTMLParser
+from urllib.parse import urljoin, urlparse
+
+from .registry import (
+    PREVIEW_TYPE_DOCUMENT,
+    PREVIEW_TYPE_FILE,
+    PREVIEW_TYPE_FOLDER,
+    PREVIEW_TYPE_IMAGE,
+    PREVIEW_TYPE_PDF,
+    PREVIEW_TYPE_PRESENTATION,
+    PREVIEW_TYPE_SPREADSHEET,
+)
+
+# Cap each scraped string so a hostile page can't bloat a synced row. The model
+# columns are 512 (title), 1024 (description), 2048 (thumbnail URL); trimming
+# here keeps the row small and the sync delta cheap even before the DB truncates.
+_MAX_TITLE = 512
+_MAX_DESCRIPTION = 1024
+
+
+@dataclass(frozen=True)
+class PreviewData:
+    """The scraped preview of a file URL.
+
+    Every field is best-effort: a page with no OpenGraph tags and no ``<title>``
+    yields ``PreviewData(None, None, None)`` and the caller still classifies a
+    ``preview_type`` from the URL shape.
+    """
+
+    title: str | None = None
+    description: str | None = None
+    thumbnail_url: str | None = None
+
+
+class _MetaCollector(HTMLParser):
+    """Collect ``<meta>`` property/name→content pairs and the ``<title>`` text.
+
+    Only the ``<head>`` carries the tags we want, but we don't hard-stop at
+    ``</head>`` — some providers emit OpenGraph tags late, and the body is
+    already capped at 256 KB upstream, so scanning all of it is bounded work.
+    """
+
+    def __init__(self) -> None:
+        super().__init__(convert_charrefs=True)
+        self.metas: dict[str, str] = {}
+        self.title: str | None = None
+        self._in_title = False
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        if tag == "title":
+            self._in_title = True
+            return
+        if tag != "meta":
+            return
+        attr = {k.lower(): (v or "") for k, v in attrs}
+        # OpenGraph uses ``property=``; Twitter Cards and the legacy description
+        # use ``name=``. Either key is fine — store under whichever is present.
+        key = (attr.get("property") or attr.get("name") or "").strip().lower()
+        content = attr.get("content")
+        if key and content and key not in self.metas:
+            # First occurrence wins — a page that repeats og:image keeps the first.
+            self.metas[key] = content.strip()
+
+    def handle_endtag(self, tag: str) -> None:
+        if tag == "title":
+            self._in_title = False
+
+    def handle_data(self, data: str) -> None:
+        if self._in_title and self.title is None:
+            text = data.strip()
+            if text:
+                self.title = text
+
+
+def _first(metas: dict[str, str], *keys: str) -> str | None:
+    """Return the first non-empty value among ``keys`` in priority order."""
+    for key in keys:
+        value = metas.get(key)
+        if value:
+            return value
+    return None
+
+
+def _safe_thumbnail(candidate: str | None, *, base_url: str) -> str | None:
+    """Resolve a candidate image URL against ``base_url`` and keep it only if https.
+
+    Relative ``og:image`` values are resolved against the page URL. We persist
+    **only** ``https://`` thumbnails (ADR-0163): the stored URL is rendered
+    client-side as ``<img src>``, so an ``http://`` value would be a mixed-content
+    / downgrade vector and a ``data:``/``javascript:`` value must never reach the
+    DOM. Anything that isn't https after resolution is dropped (the card falls
+    back to a type glyph).
+    """
+    if not candidate:
+        return None
+    resolved = urljoin(base_url, candidate.strip())
+    if urlparse(resolved).scheme != "https":
+        return None
+    return resolved[:2048]
+
+
+def parse_preview(body: bytes, *, base_url: str) -> PreviewData:
+    """Scrape ``{title, description, thumbnail_url}`` from an HTML ``body``.
+
+    Args:
+        body: The raw response bytes (already capped at 256 KB by ``http.get``).
+        base_url: The fetched URL — used to resolve a relative ``og:image``.
+
+    Returns:
+        A :class:`PreviewData`; any field the page doesn't provide is ``None``.
+        Never raises — malformed/binary bodies decode with replacement and yield
+        an empty result.
+    """
+    parser = _MetaCollector()
+    try:
+        parser.feed(body.decode("utf-8", errors="replace"))
+        parser.close()
+    except Exception:
+        # A broken/hostile page must degrade to an empty preview, never 500 a
+        # refresh — fetch_metadata's contract is "never raise for bad input".
+        return PreviewData()
+
+    metas = parser.metas
+    title = _first(metas, "og:title", "twitter:title") or parser.title
+    description = _first(metas, "og:description", "twitter:description", "description")
+    image = _first(metas, "og:image:secure_url", "og:image", "twitter:image")
+
+    return PreviewData(
+        title=title[:_MAX_TITLE].strip() if title else None,
+        description=description[:_MAX_DESCRIPTION].strip() if description else None,
+        thumbnail_url=_safe_thumbnail(image, base_url=base_url),
+    )
+
+
+# File extensions → preview type. Covers the common office/file shapes that
+# Dropbox/Box/OneDrive expose directly in the URL path.
+_EXT_TYPES: dict[str, str] = {
+    ".doc": PREVIEW_TYPE_DOCUMENT,
+    ".docx": PREVIEW_TYPE_DOCUMENT,
+    ".odt": PREVIEW_TYPE_DOCUMENT,
+    ".rtf": PREVIEW_TYPE_DOCUMENT,
+    ".txt": PREVIEW_TYPE_DOCUMENT,
+    ".md": PREVIEW_TYPE_DOCUMENT,
+    ".pages": PREVIEW_TYPE_DOCUMENT,
+    ".xls": PREVIEW_TYPE_SPREADSHEET,
+    ".xlsx": PREVIEW_TYPE_SPREADSHEET,
+    ".csv": PREVIEW_TYPE_SPREADSHEET,
+    ".ods": PREVIEW_TYPE_SPREADSHEET,
+    ".numbers": PREVIEW_TYPE_SPREADSHEET,
+    ".ppt": PREVIEW_TYPE_PRESENTATION,
+    ".pptx": PREVIEW_TYPE_PRESENTATION,
+    ".odp": PREVIEW_TYPE_PRESENTATION,
+    ".key": PREVIEW_TYPE_PRESENTATION,
+    ".pdf": PREVIEW_TYPE_PDF,
+    ".png": PREVIEW_TYPE_IMAGE,
+    ".jpg": PREVIEW_TYPE_IMAGE,
+    ".jpeg": PREVIEW_TYPE_IMAGE,
+    ".gif": PREVIEW_TYPE_IMAGE,
+    ".webp": PREVIEW_TYPE_IMAGE,
+    ".svg": PREVIEW_TYPE_IMAGE,
+    ".bmp": PREVIEW_TYPE_IMAGE,
+    ".heic": PREVIEW_TYPE_IMAGE,
+}
+
+# Google Docs editor path segments → preview type. Drive uses an editor host
+# path (``/spreadsheets/d/…``) rather than a file extension.
+_GOOGLE_PATH_TYPES: tuple[tuple[str, str], ...] = (
+    ("/spreadsheets/", PREVIEW_TYPE_SPREADSHEET),
+    ("/presentation/", PREVIEW_TYPE_PRESENTATION),
+    ("/document/", PREVIEW_TYPE_DOCUMENT),
+    ("/forms/", PREVIEW_TYPE_DOCUMENT),
+)
+
+
+def classify_preview_type(url: str, type_hint: str | None = None) -> str:
+    """Classify ``url`` onto one of :data:`PREVIEW_TYPE_VALUES`.
+
+    Resolution order, most specific first:
+
+    1. A folder path (``/folders/`` — Drive, ``/sh/`` Dropbox shared folders).
+    2. A Google Docs editor path segment (spreadsheets/presentation/document).
+    3. A known file extension on the URL path.
+    4. A ``type_hint`` of ``image``/``video`` — the caller passes the response
+       ``Content-Type`` (e.g. ``image/png``) or an OpenGraph ``og:type``; both
+       start with the class name, so a direct image URL with no path extension
+       still classes as an image.
+    5. The generic ``file`` fallback — a real file we just can't class further.
+
+    Args:
+        url: The file URL being classified.
+        type_hint: Optional response ``Content-Type`` or OpenGraph ``og:type``.
+    """
+    path = urlparse(url).path.lower()
+
+    if "/folders/" in path or path.endswith("/folder") or "/sh/" in path:
+        return PREVIEW_TYPE_FOLDER
+
+    for segment, ptype in _GOOGLE_PATH_TYPES:
+        if segment in path:
+            return ptype
+
+    for ext, ptype in _EXT_TYPES.items():
+        if path.endswith(ext):
+            return ptype
+
+    if type_hint and type_hint.lower().startswith("image"):
+        return PREVIEW_TYPE_IMAGE
+
+    return PREVIEW_TYPE_FILE

trueppm_api/apps/integrations/outgoing.py

@@ -0,0 +1,201 @@
+"""OSS ``OUTGOING_CHANNEL_PROVIDERS`` registrations (ADR-0049 §2, ADR-0083).
+
+Two providers ship in OSS:
+
+- ``generic`` — returns the event payload unchanged. This is the historical
+  behavior (the internal envelope POSTed as the raw body), so every existing
+  webhook row — which defaults to ``format="generic"`` — is byte-for-byte
+  unaffected by the format extension.
+- ``slack`` — renders a Slack incoming-webhook message (``text`` + a single
+  legacy ``attachments`` entry — not Block Kit). Discord and Mattermost incoming
+  webhooks accept the Slack attachment shape de-facto, so this one renderer covers
+  all three; ``blocks`` would only work on Slack.
+
+Enterprise registers richer providers (``slack_app`` OAuth, ``teams``, …)
+against the same registry from its own ``AppConfig.ready()`` — no OSS change.
+The provider only *renders*; ``apps/webhooks/tasks.py::deliver_webhook`` owns
+transport, HMAC signing, retries, and the sequence header (ADR-0083).
+"""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar
+
+from .registry import OutgoingChannelEvent, OutgoingChannelProvider
+
+# Slack attachment bar color per event family. Red for destructive/blocking
+# transitions, green for creation/assignment, neutral grey for the rest —
+# matches the design-system semantic palette so the Slack card reads at a glance.
+_SLACK_COLOR = "#1C6B3A"  # brand-primary (green)
+_SLACK_COLOR_CRITICAL = "#B91C1C"  # semantic-critical (red)
+_SLACK_COLOR_NEUTRAL = "#6B6965"  # text-secondary (grey)
+
+# Human-readable title + bar color for every OSS event type, plus the reserved
+# ``ping``. Kept as data (not branches) so the slack renderer stays a pure lookup;
+# an unmapped event still renders with a sensible fallback title rather than
+# raising. ``test_slack_meta_covers_every_event`` fails if a new WebhookEventType
+# lands without an entry — the gap this table had for eight real OSS events, which
+# made `risk.opened` post to Slack as `*risk.opened* — <uuid>` with no fields
+# (#2883).
+_SLACK_EVENT_META: dict[str, tuple[str, str]] = {
+    "task.created": ("Task created", _SLACK_COLOR),
+    "task.updated": ("Task updated", _SLACK_COLOR_NEUTRAL),
+    "task.deleted": ("Task deleted", _SLACK_COLOR_CRITICAL),
+    "task.assigned": ("Task assigned", _SLACK_COLOR),
+    "task.assignee_changed": ("Task reassigned", _SLACK_COLOR_NEUTRAL),
+    "task.mentioned": ("You were mentioned", _SLACK_COLOR),
+    "task.due_date_changed": ("Task date changed", _SLACK_COLOR_NEUTRAL),
+    "dependency.created": ("Dependency added", _SLACK_COLOR_NEUTRAL),
+    "dependency.deleted": ("Dependency removed", _SLACK_COLOR_NEUTRAL),
+    "schedule.recalculated": ("Schedule recalculated", _SLACK_COLOR_NEUTRAL),
+    "project.created": ("Project created", _SLACK_COLOR),
+    "sprint.activated": ("Sprint started", _SLACK_COLOR),
+    "sprint.closed": ("Sprint closed", _SLACK_COLOR_NEUTRAL),
+    "sprint.scope_changed": ("Sprint scope changed", _SLACK_COLOR_CRITICAL),
+    "risk.opened": ("Risk opened", _SLACK_COLOR_CRITICAL),
+    "risk.escalated": ("Risk escalated", _SLACK_COLOR_CRITICAL),
+    "risk.closed": ("Risk closed", _SLACK_COLOR),
+    "baseline.captured": ("Baseline captured", _SLACK_COLOR),
+    "comment.created": ("New comment", _SLACK_COLOR_NEUTRAL),
+    # Reserved, non-domain: the "Send test" ping now renders through this provider
+    # like any other delivery (#2884), so it needs a title an admin recognizes in
+    # the channel rather than a bare "ping".
+    "ping": ("Test ping", _SLACK_COLOR_NEUTRAL),
+}
+
+# The payload key each event family carries its human-readable name under. Task,
+# sprint, and baseline payloads use ``name``; a risk uses ``title``; a sprint
+# scope change is about the injected item, so ``item_name``. ``id`` is the last
+# resort (task.deleted carries only id + project).
+_SLACK_NAME_KEYS: tuple[str, ...] = ("name", "title", "item_name", "id")
+
+# Slack attachment field rows per event family — (label, payload key). The
+# extractor read only task keys (name/status/assignee/planned_start) before
+# #2883, which are absent from every sprint, risk, and baseline payload, so those
+# events rendered with an empty ``fields`` array.
+_SLACK_DEFAULT_FIELDS: tuple[tuple[str, str], ...] = (
+    ("Status", "status"),
+    ("Assignee", "assignee"),
+    ("Planned start", "planned_start"),
+)
+
+_SLACK_FIELDS_BY_FAMILY: dict[str, tuple[tuple[str, str], ...]] = {
+    "sprint": (
+        ("State", "state"),
+        ("Goal", "goal"),
+        ("Committed points", "committed_points"),
+        ("Start", "start_date"),
+        ("Finish", "finish_date"),
+    ),
+    "risk": (
+        ("Status", "status"),
+        ("Severity", "severity"),
+        ("Probability", "probability"),
+        ("Impact", "impact"),
+        ("Category", "category"),
+    ),
+    "baseline": (
+        ("Tasks captured", "task_count"),
+        ("Has CPM dates", "has_cpm_dates"),
+    ),
+    "comment": (
+        ("Author", "author_display"),
+        ("Status", "status"),
+        ("Assignee", "assignee"),
+    ),
+}
+
+# Event-level override, checked before the family table. sprint.scope_changed is
+# in the "sprint" family but its payload is about the injected item, not the
+# sprint's own plan fields.
+_SLACK_FIELDS_BY_EVENT: dict[str, tuple[tuple[str, str], ...]] = {
+    "sprint.scope_changed": (
+        ("Item", "item_name"),
+        ("Decision", "status"),
+        ("Goal impact", "goal_impact"),
+    ),
+}
+
+
+def _slack_field_specs(event_type: str) -> tuple[tuple[str, str], ...]:
+    """Return the (label, payload key) rows to surface for ``event_type``."""
+    if event_type in _SLACK_FIELDS_BY_EVENT:
+        return _SLACK_FIELDS_BY_EVENT[event_type]
+    family = event_type.split(".", 1)[0]
+    return _SLACK_FIELDS_BY_FAMILY.get(family, _SLACK_DEFAULT_FIELDS)
+
+
+class GenericOutgoingChannelProvider(OutgoingChannelProvider):
+    """Pass-through provider — the raw TruePPM event envelope, unchanged.
+
+    This preserves the pre-#638 behavior exactly: the payload built by the
+    dispatching view is what gets POSTed. Existing webhooks (``format="generic"``
+    by default) see no change.
+    """
+
+    key: ClassVar[str] = "generic"
+    label: ClassVar[str] = "Generic (JSON)"
+
+    def render(self, event: OutgoingChannelEvent) -> dict[str, Any]:
+        return event.payload
+
+
+class SlackOutgoingChannelProvider(OutgoingChannelProvider):
+    """Render a TruePPM event as a Slack incoming-webhook message.
+
+    Produces ``{"text": ..., "attachments": [{...}]}`` — the shape Slack,
+    Discord, and Mattermost incoming webhooks all accept. The attachment lists the
+    fields present in the payload as Slack ``fields`` so the message is skimmable
+    without opening TruePPM. Which fields those are is per event family
+    (:func:`_slack_field_specs`), because a sprint, a risk, and a baseline share
+    almost no keys with a task.
+
+    This is the legacy ``attachments`` shape, **not** Block Kit — deliberately, and
+    the reason one renderer covers Slack, Discord, and Mattermost (only Slack
+    understands ``blocks``). Migrating to Block Kit would drop the other two.
+    """
+
+    key: ClassVar[str] = "slack"
+    label: ClassVar[str] = "Slack"
+
+    def render(self, event: OutgoingChannelEvent) -> dict[str, Any]:
+        payload = event.payload
+        title, color = _SLACK_EVENT_META.get(
+            event.event_type, (event.event_type, _SLACK_COLOR_NEUTRAL)
+        )
+        subject = next(
+            (str(payload[key]) for key in _SLACK_NAME_KEYS if payload.get(key)),
+            "event",
+        )
+
+        # Only surface fields that are present — task.deleted carries just id +
+        # project, so we must not emit empty "Status"/"Assignee" rows for it. The
+        # check is against None/"" rather than truthiness so a genuine ``0``
+        # (committed_points on an empty sprint) or ``False`` (has_cpm_dates) still
+        # renders instead of vanishing.
+        fields = [
+            {"title": label, "value": str(payload[key]), "short": True}
+            for label, key in _slack_field_specs(event.event_type)
+            if payload.get(key) not in (None, "")
+        ]
+
+        return {
+            "text": f"*{title}* — {subject}",
+            "attachments": [
+                {
+                    "color": color,
+                    "title": subject,
+                    "fields": fields,
+                    "footer": "TruePPM",
+                    "mrkdwn_in": ["text"],
+                }
+            ],
+        }
+
+
+# Ordered tuple — apps.py iterates these in declaration order so OSS
+# registration order is deterministic for tests and the format-picker menu.
+OSS_OUTGOING_CHANNEL_PROVIDERS: tuple[type[OutgoingChannelProvider], ...] = (
+    GenericOutgoingChannelProvider,
+    SlackOutgoingChannelProvider,
+)