trueppm-api 0.4.0b2__py3-none-any.whl

trueppm_api/apps/integrations/git_automation_services.py

@@ -0,0 +1,231 @@
+"""Match a verified Git webhook to a task and move its card (#329, ADR-0158).
+
+The service is the second half of the OSS Git-event automation: given an already
+**verified** :class:`~trueppm_api.apps.integrations.git_webhook_auth.GitWebhookEnvelope`,
+it finds the task that carries the PR/MR as a ``TaskLink`` and advances that card's
+board status **forward only** through the canonical ``TaskSerializer`` write path.
+
+Three deliberate properties (all enforced here, none bypassable):
+
+- **Forward-only.** ``pr.opened`` moves a card to REVIEW only from
+  ``{BACKLOG, NOT_STARTED, IN_PROGRESS}``; ``pr.merged`` moves to COMPLETE only
+  from a non-COMPLETE state. A card already at/ahead of the target is a no-op —
+  automation never drags a card backward, and a redelivered webhook is idempotent
+  even if the Redis dedup layer is unavailable.
+- **No parallel transition path.** The status write goes through ``TaskSerializer``
+  exactly as a human board drag would, so every existing validation, actual-date
+  rule (ADR-0136), and the advisory WIP surface (ADR-0039) apply unchanged. The
+  automation neither adds nor circumvents a hard WIP block (there is none).
+- **Attributed but classified as automation.** The write is attributed to the
+  configuring admin (``configured_by``) for RBAC + history, while
+  ``history_change_reason`` tags it ``git:pr_*`` so the ADR-0096 activity timeline
+  shows it as an automated move, and the WS broadcast carries ``actor_id=None``
+  (ADR-0152 system write).
+"""
+
+from __future__ import annotations
+
+import functools
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from django.db import transaction
+
+from trueppm_api.apps.access.models import Role
+from trueppm_api.apps.projects.models import Task, TaskStatus
+
+from .git_webhook_auth import GIT_EVENT_PR_MERGED, GIT_EVENT_PR_OPENED, PROVIDER_GITHUB
+from .models import BoardAutomation, TaskLink
+from .providers import _parse_github_url, _parse_gitlab_url
+
+if TYPE_CHECKING:
+    from django.contrib.auth.models import AbstractBaseUser
+
+# pr.opened may advance a card to REVIEW only from these states — never from
+# REVIEW or COMPLETE (forward-only). pr.merged may advance to COMPLETE from any
+# non-COMPLETE state.
+_PR_OPENED_SOURCE_STATES = frozenset(
+    {TaskStatus.BACKLOG, TaskStatus.NOT_STARTED, TaskStatus.IN_PROGRESS}
+)
+
+_CHANGE_REASON = {
+    GIT_EVENT_PR_OPENED: "git:pr_opened",
+    GIT_EVENT_PR_MERGED: "git:pr_merged",
+}
+
+
+@dataclass(frozen=True)
+class GitAutomationResult:
+    """Outcome of applying one webhook, shaped for the receiver's JSON response."""
+
+    matched: bool
+    moved: bool
+    task_id: str | None = None
+    from_status: str | None = None
+    to_status: str | None = None
+    reason: str = ""
+
+
+class _SystemRequest:
+    """Minimal request stand-in for the serializer's ``context["request"]``.
+
+    The ``TaskSerializer`` only reads ``request.user`` (for role/history); a full
+    DRF request is unnecessary and would drag in middleware. ``caller_role`` is
+    passed alongside in context so role resolution never hits the DB for a user
+    who may since have been removed from the project.
+    """
+
+    def __init__(self, user: AbstractBaseUser | None) -> None:
+        self.user = user
+        self.method = "PATCH"
+
+
+def _pr_key(provider: str, url: str) -> tuple[Any, ...] | None:
+    """Parse a PR/MR URL into a comparable identity tuple, or ``None``.
+
+    Reuses the existing ``providers`` parsers. For GitHub the resource must be a
+    ``pull`` (issues share the URL shape but are not board-moving PRs); for GitLab
+    the parser already restricts to ``merge_requests``/``issues`` and we keep only
+    merge requests.
+    """
+    # Both providers return a ``(repo_path, ref)`` pair so the tuple shape is
+    # identical regardless of provider (GitHub owner/repo is folded into one
+    # path segment, mirroring GitLab's already-combined project path).
+    if provider == PROVIDER_GITHUB:
+        parsed = _parse_github_url(url)
+        if parsed is None:
+            return None
+        owner, repo, kind, ref = parsed
+        if kind != "pull":
+            return None
+        return (f"{owner.lower()}/{repo.lower()}", ref)
+    parsed_gl = _parse_gitlab_url(url)
+    if parsed_gl is None:
+        return None
+    project_path, kind, ref = parsed_gl
+    if kind != "merge_requests":
+        return None
+    return (project_path.lower(), ref)
+
+
+def _find_linked_task(project_id: Any, provider: str, pr_url: str) -> Task | None:
+    """Find the project task whose ``TaskLink`` points at ``pr_url``.
+
+    No normalized URL column exists (ADR-0158 §4), so this is parse-and-compare,
+    bounded to the project's own links — the candidate set is small. The first
+    matching link wins; a task linked to the same PR more than once is degenerate.
+    """
+    target = _pr_key(provider, pr_url)
+    if target is None:
+        return None
+    candidates = (
+        TaskLink.objects.filter(
+            task__project_id=project_id,
+            is_deleted=False,
+            task__is_deleted=False,
+        )
+        .select_related("task")
+        .only("url", "task")
+    )
+    for link in candidates:
+        if _pr_key(provider, link.url) == target:
+            return link.task
+    return None
+
+
+def _target_status(event: str, current: str) -> str | None:
+    """Resolve the forward-only target board status, or ``None`` for a no-op."""
+    if event == GIT_EVENT_PR_OPENED:
+        return TaskStatus.REVIEW if current in _PR_OPENED_SOURCE_STATES else None
+    if event == GIT_EVENT_PR_MERGED:
+        return TaskStatus.COMPLETE if current != TaskStatus.COMPLETE else None
+    return None
+
+
+def apply_git_event_to_card(
+    automation: BoardAutomation, provider: str, event: str, pr_url: str | None
+) -> GitAutomationResult:
+    """Apply one verified Git event to its linked card.
+
+    Args:
+        automation: the enabled ``BoardAutomation`` for the target project.
+        provider: ``"github"`` / ``"gitlab"`` (from the verified envelope).
+        event: ``pr.opened`` / ``pr.merged``.
+        pr_url: the PR/MR URL from the payload.
+
+    Returns:
+        A :class:`GitAutomationResult` describing what happened. Always a 200-shaped
+        result — "no link" and "already there" are normal, not errors.
+    """
+    if not pr_url:
+        return GitAutomationResult(matched=False, moved=False, reason="no_url")
+
+    task = _find_linked_task(automation.project_id, provider, pr_url)
+    if task is None:
+        return GitAutomationResult(matched=False, moved=False, reason="no_link")
+
+    current = task.status
+    target = _target_status(event, current)
+    if target is None:
+        # Forward-only no-op: the card is already at or ahead of the target.
+        return GitAutomationResult(
+            matched=True,
+            moved=False,
+            task_id=str(task.pk),
+            from_status=current,
+            to_status=current,
+            reason="noop_forward_only",
+        )
+
+    moved_task = _write_status(task, target, event, automation.configured_by)
+    return GitAutomationResult(
+        matched=True,
+        moved=True,
+        task_id=str(moved_task.pk),
+        from_status=current,
+        to_status=target,
+        reason="opened_review" if event == GIT_EVENT_PR_OPENED else "merged_complete",
+    )
+
+
+def _write_status(task: Task, target: str, event: str, actor: AbstractBaseUser | None) -> Task:
+    """Write the new status through the canonical serializer + broadcast the move.
+
+    Runs inside ``transaction.atomic`` so the status write and the deferred
+    broadcast commit together. ``_change_reason`` / ``_history_user`` are stamped
+    on the instance before ``save()`` so ``django-simple-history`` attributes the
+    edit to the configuring admin and classifies it as automation (ADR-0096).
+    """
+    # Imported lazily — the projects serializer module is heavy and importing it
+    # at module load would create an apps-not-ready risk during migrations.
+    from trueppm_api.apps.projects.serializers import TaskSerializer
+    from trueppm_api.apps.sync.broadcast import broadcast_task_updated
+
+    with transaction.atomic():
+        task._change_reason = _CHANGE_REASON[event]  # type: ignore[attr-defined]
+        task._history_user = actor  # type: ignore[attr-defined]
+        serializer = TaskSerializer(
+            instance=task,
+            data={"status": target},
+            partial=True,
+            context={"request": _SystemRequest(actor), "caller_role": Role.ADMIN},
+        )
+        serializer.is_valid(raise_exception=True)
+        updated: Task = serializer.save()
+
+        project_id_str = str(updated.project_id)
+        task_id_str = str(updated.pk)
+        version = updated.server_version
+        # actor_id=None — automation/system write (ADR-0152). Deferred to commit
+        # so a connected board refreshes the card without a manual refetch.
+        transaction.on_commit(
+            functools.partial(
+                broadcast_task_updated,
+                project_id_str,
+                task_id=task_id_str,
+                changed_fields=["status"],
+                version=version,
+                actor_id=None,
+            )
+        )
+    return updated

trueppm_api/apps/integrations/git_webhook_auth.py

@@ -0,0 +1,243 @@
+"""Inbound Git-webhook authentication + envelope parsing (#329, ADR-0158).
+
+This module is the security boundary of the OSS Git-event board-card automation.
+It has two jobs and nothing else:
+
+1. **Verify the per-provider signature** against the project's plaintext secret —
+   constant-time, before the payload is ever interpreted as a command. GitHub
+   recomputes ``HMAC-SHA256`` over the *raw* request body; GitLab compares the
+   ``X-Gitlab-Token`` header directly. A bad or missing signature is rejected with
+   the receiver's uniform 404 (see :class:`WebhookSignatureError`).
+
+2. **Normalize the payload** into a small :class:`GitWebhookEnvelope` — provider,
+   forward-only event (``pr.opened`` / ``pr.merged`` / ``None`` = ignore), the
+   PR/MR URL to match against a ``TaskLink``, and an idempotency ``delivery_key``.
+
+It deliberately does **not** touch the database, mutate any task, or call out to
+a provider — the receiver (``views.GitWebhookIngestView``) and the service
+(``git_automation_services``) own that. Keeping verification pure and side-effect
+free is what makes it cheap to test exhaustively (the bug class that matters here
+is "signature accepted when it should not have been").
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+from dataclasses import dataclass
+from typing import Any
+
+from trueppm_api.core.constant_time import constant_time_equal
+
+# Forward-only event vocabulary. Only these two map to a card move; every other
+# Git event resolves to ``None`` and the receiver returns a 200 "ignored".
+GIT_EVENT_PR_OPENED = "pr.opened"
+GIT_EVENT_PR_MERGED = "pr.merged"
+
+PROVIDER_GITHUB = "github"
+PROVIDER_GITLAB = "gitlab"
+
+# GitHub ``pull_request`` actions that mean "a review is now wanted". ``reopened``
+# and ``ready_for_review`` are included so a draft promoted to ready, or a closed
+# PR reopened, re-asserts the REVIEW intent (the forward-only guard still prevents
+# moving a card backward).
+_GITHUB_OPEN_ACTIONS = frozenset({"opened", "reopened", "ready_for_review"})
+# GitLab ``merge_request`` actions with the same meaning.
+_GITLAB_OPEN_ACTIONS = frozenset({"open", "reopen"})
+
+# ``GitWebhookEnvelope.ignored_reason`` value for a suppressed draft/WIP open.
+_IGNORED_DRAFT = "draft"
+
+
+@dataclass(frozen=True)
+class GitWebhookEnvelope:
+    """Provider-neutral view of a verified webhook, ready for matching."""
+
+    provider: str
+    # GIT_EVENT_PR_OPENED | GIT_EVENT_PR_MERGED | None (irrelevant event → ignore).
+    event: str | None
+    # The PR/MR URL to match against an existing TaskLink. None when the payload
+    # carries no usable URL (then there is nothing to match and we 200-ignore).
+    pr_url: str | None
+    # Stable per-delivery key for Redis dedup. Always non-empty.
+    delivery_key: str
+    # The provider's own event name (for the "ignored" response and logging).
+    raw_event_name: str
+    # Why an otherwise-actionable event resolved to ``event=None``. Empty for an
+    # event we never act on (a push, a comment); ``"draft"`` when the payload was a
+    # PR/MR *open* on a draft/WIP request, which deliberately does not promote the
+    # card (#2882). Surfaced in the receiver's 200 body and the delivery record so
+    # "why didn't my card move?" has an answer that is not "read the source".
+    ignored_reason: str = ""
+
+
+class WebhookSignatureError(Exception):
+    """Raised when a webhook signature is missing or does not verify.
+
+    Carries no provider/secret detail — the receiver maps it to the same bare 404 it
+    returns for "no automation configured", so a caller genuinely cannot distinguish
+    the two. It used to map to a 401, which *named* the distinction the 404 was
+    written to hide: 401 meant enabled-with-a-secret, 404 meant not configured, and
+    any project Viewer could read off admin-only state from a project UUID (#2881).
+    The reason a delivery was rejected is not lost — it lands in the structured
+    receiver log and on ``BoardAutomation.last_delivery_outcome``, both of which
+    require the caller to already be an admin of that project.
+    """
+
+
+def detect_provider(headers: Any) -> str | None:
+    """Return ``"github"`` / ``"gitlab"`` from the request headers, or ``None``.
+
+    Detection is by the provider's own event header, not a query param, so a
+    caller cannot spoof the provider to pick a weaker verification path —
+    each provider's branch only accepts its own signature header.
+    """
+    if headers.get("X-GitHub-Event"):
+        return PROVIDER_GITHUB
+    if headers.get("X-Gitlab-Event"):
+        return PROVIDER_GITLAB
+    return None
+
+
+def verify_signature(
+    provider: str,
+    secret_plaintext: str,
+    raw_body: bytes,
+    headers: Any,
+) -> None:
+    """Verify the provider signature in constant time, or raise.
+
+    GitHub: ``X-Hub-Signature-256`` must equal ``"sha256=" + HMAC_SHA256(secret,
+    raw_body)``. The raw body (not the parsed dict) is hashed because re-encoding
+    a parsed payload would not byte-match what the provider signed.
+
+    GitLab: ``X-Gitlab-Token`` must equal the shared secret. GitLab sends the
+    secret verbatim rather than an HMAC, so this is a direct constant-time compare.
+
+    Raises:
+        WebhookSignatureError: signature header absent, malformed, or mismatched.
+            No secret bytes leak in the message.
+    """
+    if not secret_plaintext:
+        # No secret configured → nothing can verify → treat as unauthenticated.
+        raise WebhookSignatureError("no secret configured")
+
+    if provider == PROVIDER_GITHUB:
+        provided = headers.get("X-Hub-Signature-256") or ""
+        digest = hmac.new(secret_plaintext.encode("utf-8"), raw_body, hashlib.sha256).hexdigest()
+        expected = f"sha256={digest}"
+        if not constant_time_equal(provided, expected):
+            raise WebhookSignatureError("github signature mismatch")
+        return
+
+    if provider == PROVIDER_GITLAB:
+        provided = headers.get("X-Gitlab-Token") or ""
+        if not constant_time_equal(provided, secret_plaintext):
+            raise WebhookSignatureError("gitlab token mismatch")
+        return
+
+    raise WebhookSignatureError(f"unsupported provider {provider!r}")
+
+
+def parse_envelope(provider: str, headers: Any, payload: Any) -> GitWebhookEnvelope:
+    """Normalize a verified webhook into a :class:`GitWebhookEnvelope`.
+
+    Never raises on an unrecognized event — an event we do not act on is normal
+    traffic (the provider sends every configured event), so it resolves to
+    ``event=None`` and the receiver returns 200. A malformed *body* (not a dict)
+    is the caller's concern; this function assumes ``payload`` is a parsed object.
+    """
+    if provider == PROVIDER_GITHUB:
+        return _parse_github(headers, payload)
+    if provider == PROVIDER_GITLAB:
+        return _parse_gitlab(payload)
+    return GitWebhookEnvelope(
+        provider=provider, event=None, pr_url=None, delivery_key="", raw_event_name=""
+    )
+
+
+def _github_event(action: str, pr: Any, is_draft: bool) -> tuple[str | None, str]:
+    """Resolve a GitHub ``pull_request`` action to ``(event, ignored_reason)``.
+
+    Both halves are returned together because they are one decision: an action we
+    act on yields an event and no reason, and a suppressed draft open yields no
+    event *plus* the reason it was suppressed. Anything else is normal traffic we
+    never act on — ``(None, "")``, with no reason to report.
+    """
+    if action in _GITHUB_OPEN_ACTIONS:
+        if is_draft:
+            return None, _IGNORED_DRAFT
+        return GIT_EVENT_PR_OPENED, ""
+    if action == "closed" and isinstance(pr, dict) and pr.get("merged") is True:
+        # A merged PR is never a draft; merge always completes the card.
+        return GIT_EVENT_PR_MERGED, ""
+    return None, ""
+
+
+def _parse_github(headers: Any, payload: dict[str, Any]) -> GitWebhookEnvelope:
+    event_name = headers.get("X-GitHub-Event") or ""
+    # X-GitHub-Delivery is a per-delivery UUID — the natural idempotency key.
+    delivery_key = headers.get("X-GitHub-Delivery") or ""
+    pr = payload.get("pull_request") if isinstance(payload, dict) else None
+    pr_url = pr.get("html_url") if isinstance(pr, dict) else None
+    action = payload.get("action") if isinstance(payload, dict) else None
+    # GitHub marks a draft PR with ``pull_request.draft``. A draft opened to run CI
+    # is not a request for review, and the forward-only rule means a card promoted
+    # by mistake can never come back — so a draft open is deliberately inert and
+    # the promotion happens on the ``ready_for_review`` action instead (#2882).
+    is_draft = bool(pr.get("draft")) if isinstance(pr, dict) else False
+
+    event: str | None = None
+    ignored_reason = ""
+    if event_name == "pull_request" and isinstance(action, str):
+        event, ignored_reason = _github_event(action, pr, is_draft)
+
+    return GitWebhookEnvelope(
+        provider=PROVIDER_GITHUB,
+        event=event,
+        # Narrowed for the same reason the GitLab arm below narrows: a signed but
+        # hostile/garbled payload can put any JSON type in ``html_url``, and every
+        # consumer downstream (``_pr_key`` → ``urlparse``) assumes ``str`` —
+        # ``html_url: 1`` raised AttributeError deep in the service (#2881 §3, the
+        # #2795 container-vs-value class).
+        pr_url=pr_url if isinstance(pr_url, str) else None,
+        delivery_key=delivery_key,
+        raw_event_name=event_name,
+        ignored_reason=ignored_reason,
+    )
+
+
+def _parse_gitlab(payload: dict[str, Any]) -> GitWebhookEnvelope:
+    object_kind = payload.get("object_kind") if isinstance(payload, dict) else None
+    attrs = payload.get("object_attributes") if isinstance(payload, dict) else None
+    attrs = attrs if isinstance(attrs, dict) else {}
+    action = attrs.get("action")
+    pr_url = attrs.get("url")
+    # GitLab's draft flag is ``work_in_progress``; newer versions also send
+    # ``draft``. Read both, exactly as the link-status parser at
+    # ``providers.GitLabProvider`` already does (#2882).
+    is_draft = bool(attrs.get("work_in_progress") or attrs.get("draft"))
+
+    event: str | None = None
+    ignored_reason = ""
+    if object_kind == "merge_request" and isinstance(action, str):
+        if action in _GITLAB_OPEN_ACTIONS:
+            if is_draft:
+                ignored_reason = _IGNORED_DRAFT
+            else:
+                event = GIT_EVENT_PR_OPENED
+        elif action == "merge":
+            event = GIT_EVENT_PR_MERGED
+
+    # GitLab has no delivery header — derive a stable key from the MR identity and
+    # action so a redelivery of the same state change dedups.
+    delivery_key = f"{object_kind}:{attrs.get('id')}:{action}"
+
+    return GitWebhookEnvelope(
+        provider=PROVIDER_GITLAB,
+        event=event,
+        pr_url=pr_url if isinstance(pr_url, str) else None,
+        delivery_key=delivery_key,
+        raw_event_name=str(object_kind or ""),
+        ignored_reason=ignored_reason,
+    )