trueppm-api 0.4.0b2__py3-none-any.whl

trueppm_api/apps/sync/ws_auth.py

@@ -0,0 +1,193 @@
+"""Shared authentication for the WebSocket handshake (ADR-0141).
+
+Browsers cannot set an ``Authorization`` header on the WebSocket upgrade, so the
+credential has to ride in the URL. A raw JWT in the URL leaks into every access
+log (#818); the fix is a short-lived, single-use **ticket** (RFC 6750 §2.3):
+
+* :func:`issue_ticket` is called synchronously from the REST view that mints a
+  ticket for an already-authenticated user. The ticket is opaque and stored in
+  Redis with a 30-second TTL.
+* :func:`consume_ticket` is called from the async consumer at connect time. It
+  uses ``GETDEL`` so a ticket is valid exactly once — a ticket that later turns
+  up in a log is already spent.
+* :func:`authenticate_scope` is the single entry point both consumers use: it
+  prefers ``?ticket=``. The **deprecated** ``?token=<jwt>`` fallback is now gated
+  behind ``TRUEPPM_WS_LEGACY_TOKEN_AUTH_ENABLED`` (default off, #1723) — a raw JWT
+  in the URL leaks into every access log, so the fallback is opt-in for one last
+  release and removed next. When it is on and used, :func:`warn_if_legacy` logs it
+  (never the value) so operators can find stragglers before removal.
+
+The ticket carries authentication only. Each consumer still runs its own
+membership/role authorization gate after resolving the user.
+
+Redis is accessed directly via ``settings.REDIS_URL`` (sync client to write, the
+``redis.asyncio`` client to read) rather than through Django's cache framework:
+no ``CACHES`` backend is configured, so the default per-process ``LocMemCache``
+would be invisible to the separate Channels worker that runs the consumer.
+"""
+
+from __future__ import annotations
+
+import logging
+import secrets
+from dataclasses import dataclass
+from typing import Any
+
+from django.conf import settings
+
+logger = logging.getLogger(__name__)
+
+#: Single-use ticket lifetime. Generous for one REST round-trip before the
+#: socket opens, short enough that a leaked (already-consumed) ticket is useless.
+TICKET_TTL_SECONDS = 30
+
+_TICKET_PREFIX = "ws:ticket:"
+
+
+def _ticket_key(ticket: str) -> str:
+    return f"{_TICKET_PREFIX}{ticket}"
+
+
+def issue_ticket(user_id: str) -> str:
+    """Mint and store a single-use WebSocket ticket for ``user_id`` (sync).
+
+    Returns the opaque ticket string the client passes as ``?ticket=`` on the
+    WebSocket URL. The value is unguessable (256 bits of entropy) and expires
+    after :data:`TICKET_TTL_SECONDS`.
+    """
+    from trueppm_api.core import valkey
+
+    ticket = secrets.token_urlsafe(32)
+    client = valkey.client(valkey.DB_CELERY)
+    try:
+        client.set(_ticket_key(ticket), str(user_id), ex=TICKET_TTL_SECONDS)
+    finally:
+        client.close()
+    return ticket
+
+
+async def consume_ticket(ticket: str) -> str | None:
+    """Atomically read-and-delete a ticket, returning its ``user_id`` or ``None``.
+
+    ``GETDEL`` makes the ticket single-use: a concurrent or replayed consume sees
+    ``None``. ``None`` is also returned for an expired or never-issued ticket.
+    """
+    from trueppm_api.core import valkey
+
+    client = valkey.async_client(valkey.DB_CELERY, decode_responses=True)
+    try:
+        return await client.getdel(_ticket_key(ticket))  # type: ignore[no-any-return]
+    finally:
+        await client.aclose()
+
+
+@dataclass
+class WsAuthResult:
+    """Outcome of authenticating a WebSocket scope.
+
+    ``user`` is ``None`` when authentication failed (missing/invalid/spent
+    credential). ``via`` records which path resolved it so the consumer can warn
+    on the deprecated token path; it is ``None`` when no credential was supplied.
+    """
+
+    user: Any | None
+    via: str | None  # "ticket" | "token" | None
+
+
+def _parse_query(query_string: bytes) -> dict[bytes, bytes]:
+    return dict(pair.split(b"=", 1) for pair in query_string.split(b"&") if b"=" in pair)
+
+
+async def _resolve_active_user(user_id: str) -> Any | None:
+    """Return the active user for ``user_id``, or ``None``.
+
+    Mirrors the JWT path's ``is_active`` filter: a user deactivated inside the
+    ticket's short lifetime must not connect.
+    """
+    from channels.db import database_sync_to_async
+
+    @database_sync_to_async  # type: ignore[untyped-decorator]
+    def _query(uid: str) -> Any | None:
+        from django.contrib.auth import get_user_model
+
+        User = get_user_model()
+        try:
+            return User.objects.get(pk=uid, is_active=True)
+        except (User.DoesNotExist, ValueError, TypeError):
+            return None
+
+    return await _query(user_id)
+
+
+async def authenticate_token(token: str) -> Any | None:
+    """Validate a JWT access token and return the active user, or ``None``.
+
+    The legacy ``?token=`` handshake path (deprecated by ADR-0141). Kept as a
+    module function so both consumers share one implementation.
+    """
+    from channels.db import database_sync_to_async
+
+    @database_sync_to_async  # type: ignore[untyped-decorator]
+    def _validate(tok: str) -> Any | None:
+        from django.contrib.auth import get_user_model
+        from rest_framework_simplejwt.exceptions import InvalidToken, TokenError
+        from rest_framework_simplejwt.tokens import AccessToken
+
+        User = get_user_model()
+        try:
+            access = AccessToken(tok)  # type: ignore[arg-type]
+            # is_active filter (#888): a deactivated user may still hold a JWT
+            # that has not yet expired; treat it as a failed resolve (4001),
+            # mirroring DRF's JWTAuthentication.
+            return User.objects.get(pk=access["user_id"], is_active=True)
+        except (TokenError, InvalidToken, User.DoesNotExist):
+            return None
+
+    return await _validate(token)
+
+
+async def authenticate_scope(scope: dict[str, Any]) -> WsAuthResult:
+    """Resolve the connecting user from a Channels ``scope``.
+
+    Prefers the single-use ``?ticket=`` (ADR-0141). Falls back to the deprecated
+    ``?token=<jwt>`` **only** when ``TRUEPPM_WS_LEGACY_TOKEN_AUTH_ENABLED`` is set
+    (default off, #1723) — with the fallback disabled a ``?token=`` handshake is
+    treated as no credential at all, so a client cannot force a raw JWT into the
+    URL. The caller closes with code 4001 when ``user`` is ``None`` and applies its
+    own authorization gate otherwise.
+    """
+    params = _parse_query(scope.get("query_string", b""))
+
+    ticket_bytes = params.get(b"ticket")
+    if ticket_bytes:
+        user_id = await consume_ticket(ticket_bytes.decode("utf-8"))
+        user = await _resolve_active_user(user_id) if user_id else None
+        return WsAuthResult(user=user, via="ticket")
+
+    token_bytes = params.get(b"token")
+    if token_bytes and getattr(settings, "TRUEPPM_WS_LEGACY_TOKEN_AUTH_ENABLED", False):
+        user = await authenticate_token(token_bytes.decode("utf-8"))
+        return WsAuthResult(user=user, via="token")
+
+    return WsAuthResult(user=None, via=None)
+
+
+def warn_if_legacy(result: WsAuthResult, *, consumer: str, project_pk: str) -> None:
+    """Emit a deprecation warning when a socket authenticated via ``?token=``.
+
+    A WebSocket client cannot read handshake response headers, so a server-side
+    log is the dependable deprecation signal — it lets operators find clients
+    still on the legacy path before it is removed next release.
+    """
+    if result.via == "token":
+        # No secret logged: args are the consumer, project pk and user pk. The
+        # literal "token" is the deprecated query-param's *name*, never its value.
+        # nosemgrep: python-logger-credential-disclosure
+        logger.warning(
+            "Deprecated WebSocket auth: %s connected via ?token= (project %s, "
+            "user %s). Migrate to POST /api/v1/ws/ticket/ (ADR-0141); the token "
+            "query param is removed next release.",
+            consumer,
+            project_pk,
+            getattr(result.user, "pk", "?"),
+        )

trueppm_api/apps/taskruns/apps.py

@@ -0,0 +1,11 @@
+"""AppConfig for the taskruns app — long-running task progress tracking."""
+
+from __future__ import annotations
+
+from django.apps import AppConfig
+
+
+class TaskRunsConfig(AppConfig):
+    name = "trueppm_api.apps.taskruns"
+    verbose_name = "Task Runs"
+    default_auto_field = "django.db.models.BigAutoField"

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

@@ -0,0 +1,92 @@
+"""Initial migration for taskruns app."""
+
+from __future__ import annotations
+
+import uuid
+
+import django.db.models.deletion
+import django.utils.timezone
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    initial = True
+
+    dependencies = [
+        ("projects", "0013_task_planned_start"),
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="TaskRun",
+            fields=[
+                (
+                    "id",
+                    models.UUIDField(
+                        default=uuid.uuid4,
+                        editable=False,
+                        primary_key=True,
+                        serialize=False,
+                    ),
+                ),
+                ("task_name", models.CharField(max_length=255)),
+                ("celery_task_id", models.CharField(db_index=True, max_length=255)),
+                (
+                    "status",
+                    models.CharField(
+                        choices=[
+                            ("pending", "Pending"),
+                            ("running", "Running"),
+                            ("success", "Success"),
+                            ("failed", "Failed"),
+                            ("cancelled", "Cancelled"),
+                        ],
+                        db_index=True,
+                        default="pending",
+                        max_length=10,
+                    ),
+                ),
+                ("progress_pct", models.SmallIntegerField(blank=True, null=True)),
+                ("progress_msg", models.TextField(blank=True, default="")),
+                ("result_summary", models.JSONField(blank=True, null=True)),
+                ("error_detail", models.TextField(blank=True, default="")),
+                (
+                    "created_at",
+                    models.DateTimeField(auto_now_add=True),
+                ),
+                ("started_at", models.DateTimeField(blank=True, null=True)),
+                ("completed_at", models.DateTimeField(blank=True, null=True)),
+                (
+                    "project",
+                    models.ForeignKey(
+                        blank=True,
+                        null=True,
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="task_runs",
+                        to="projects.project",
+                    ),
+                ),
+                (
+                    "initiated_by",
+                    models.ForeignKey(
+                        blank=True,
+                        null=True,
+                        on_delete=django.db.models.deletion.SET_NULL,
+                        related_name="task_runs",
+                        to=settings.AUTH_USER_MODEL,
+                    ),
+                ),
+            ],
+            options={
+                "ordering": ["-created_at"],
+                "indexes": [
+                    models.Index(
+                        fields=["project", "status", "created_at"],
+                        name="taskrun_proj_status_idx",
+                    )
+                ],
+            },
+        ),
+    ]

trueppm_api/apps/taskruns/models.py

@@ -0,0 +1,68 @@
+"""Models for long-running task progress tracking."""
+
+from __future__ import annotations
+
+from uuid import uuid4
+
+from django.contrib.auth import get_user_model
+from django.db import models
+
+
+class TaskRunStatus(models.TextChoices):
+    PENDING = "pending", "Pending"
+    RUNNING = "running", "Running"
+    SUCCESS = "success", "Success"
+    FAILED = "failed", "Failed"
+    CANCELLED = "cancelled", "Cancelled"
+
+
+class TaskRun(models.Model):
+    """Persisted record of a single Celery task execution with live progress state.
+
+    Not extended from VersionedModel — this is a server-side audit record, not
+    synced to mobile. `result_summary` is a structured JSONField so Enterprise can
+    store workflow stage payloads here without a schema change.
+    """
+
+    id = models.UUIDField(primary_key=True, default=uuid4, editable=False)
+    task_name = models.CharField(max_length=255)
+    celery_task_id = models.CharField(max_length=255, db_index=True)
+    project = models.ForeignKey(
+        "projects.Project",
+        on_delete=models.CASCADE,
+        null=True,
+        blank=True,
+        related_name="task_runs",
+    )
+    initiated_by = models.ForeignKey(
+        get_user_model(),
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="task_runs",
+    )
+    status = models.CharField(
+        max_length=10,
+        choices=TaskRunStatus.choices,
+        default=TaskRunStatus.PENDING,
+        db_index=True,
+    )
+    progress_pct = models.SmallIntegerField(null=True, blank=True)
+    progress_msg = models.TextField(blank=True, default="")
+    result_summary = models.JSONField(null=True, blank=True)
+    error_detail = models.TextField(blank=True, default="")
+    created_at = models.DateTimeField(auto_now_add=True)
+    started_at = models.DateTimeField(null=True, blank=True)
+    completed_at = models.DateTimeField(null=True, blank=True)
+
+    class Meta:
+        indexes = [
+            models.Index(
+                fields=["project", "status", "created_at"],
+                name="taskrun_proj_status_idx",
+            ),
+        ]
+        ordering = ["-created_at"]
+
+    def __str__(self) -> str:
+        return f"TaskRun({self.task_name}, {self.status})"

trueppm_api/apps/taskruns/serializers.py

@@ -0,0 +1,92 @@
+"""Serializers for TaskRun API."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from rest_framework import serializers
+
+from trueppm_api.apps.taskruns.models import TaskRun
+
+
+class TaskRunSerializer(serializers.ModelSerializer[TaskRun]):
+    """Read-only serializer for TaskRun progress records.
+
+    Exposes all fields needed to drive a progress indicator: status,
+    progress_pct, progress_msg, and timing fields for duration display.
+    All fields are read-only — TaskRun records are created and updated
+    by the Celery worker, never directly via the API.
+    """
+
+    class Meta:
+        model = TaskRun
+        fields = [
+            "id",
+            "task_name",
+            "celery_task_id",
+            "project",
+            "initiated_by",
+            "status",
+            "progress_pct",
+            "progress_msg",
+            "result_summary",
+            "error_detail",
+            "created_at",
+            "started_at",
+            "completed_at",
+        ]
+        read_only_fields = fields
+
+
+class SchedulerRunResultSummarySerializer(serializers.Serializer[Any]):
+    """Typed view over TaskRun.result_summary when task_name='scheduling.recalculate'.
+
+    The tracker writes ``{"project_finish": "YYYY-MM-DD", "critical_path": [uuid, ...],
+    "status_date": "YYYY-MM-DD"}`` from ``_run_schedule``. Fields are optional
+    because failed runs may never reach ``set_result()``.
+    """
+
+    project_finish = serializers.DateField(required=False, allow_null=True)
+    critical_path = serializers.ListField(
+        child=serializers.CharField(), required=False, allow_null=True
+    )
+    # The data date this run was actually computed against (ADR-0752 §4) — a
+    # REST fallback for a client that missed the live cpm_complete/
+    # task_run_completed broadcast, mirroring the MC status_date provenance
+    # convention (#2638). Always present on a successful run; absent on a
+    # dateless-but-settled result (``_settle_empty``), which never resolves one.
+    status_date = serializers.DateField(required=False, allow_null=True)
+
+
+class SchedulerRunSerializer(serializers.ModelSerializer[TaskRun]):
+    """Typed view over TaskRun records for scheduler recalculation runs.
+
+    Exposes ``initiated_by`` as a username string rather than a user UUID —
+    observability audit readers (Marcus/SOC 2) want a human-readable name, and
+    this avoids leaking user PKs to non-admin project members.
+    """
+
+    initiated_by_username = serializers.SerializerMethodField()
+    result_summary = SchedulerRunResultSummarySerializer(allow_null=True, required=False)
+
+    class Meta:
+        model = TaskRun
+        fields = [
+            "id",
+            "status",
+            "progress_pct",
+            "progress_msg",
+            "result_summary",
+            "error_detail",
+            "initiated_by_username",
+            "created_at",
+            "started_at",
+            "completed_at",
+        ]
+        read_only_fields = fields
+
+    def get_initiated_by_username(self, obj: TaskRun) -> str | None:
+        user = obj.initiated_by
+        if user is None:
+            return None
+        return getattr(user, "username", None) or getattr(user, "email", None)

trueppm_api/apps/taskruns/tasks.py

@@ -0,0 +1,60 @@
+"""Celery tasks for taskruns app."""
+
+from __future__ import annotations
+
+import logging
+from datetime import timedelta
+from typing import Any
+
+from celery import shared_task
+from django.utils import timezone
+
+logger = logging.getLogger(__name__)
+
+
+def _do_taskrun_purge(*, dry_run: bool = False, override_value: int | None = None) -> int:
+    """Business logic for purge_old_task_runs — extracted for testability.
+
+    Deletes terminal (SUCCESS/FAILED/CANCELLED) TaskRun rows older than the window
+    resolved by ``resolve_retention`` (operator override → the
+    TASK_RUN_RETENTION_DAYS default, ADR-0173); ``None`` disables the purge. Returns
+    rows deleted, or the eligible count when ``dry_run``; ``override_value`` forces
+    a hypothetical window.
+    """
+    from trueppm_api.apps.observability.retention import resolve_retention
+    from trueppm_api.apps.taskruns.models import TaskRun, TaskRunStatus
+
+    retention_days = (
+        override_value
+        if override_value is not None
+        else resolve_retention("TASK_RUN_RETENTION_DAYS")
+    )
+    if retention_days is None:
+        return 0
+
+    cutoff = timezone.now() - timedelta(days=retention_days)
+    qs = TaskRun.objects.filter(
+        status__in=[TaskRunStatus.SUCCESS, TaskRunStatus.FAILED, TaskRunStatus.CANCELLED],
+        completed_at__lt=cutoff,
+    )
+    if dry_run:
+        return qs.count()
+    deleted, _ = qs.delete()
+    logger.info("purge_old_task_runs: deleted %d records", deleted)
+    return deleted
+
+
+@shared_task(name="taskruns.purge_old_records")  # type: ignore[untyped-decorator]
+def purge_old_task_runs() -> dict[str, Any]:
+    """Delete completed/failed/cancelled TaskRun records older than the window.
+
+    Still dispatchable directly, but no longer on its own Beat schedule — the
+    consolidated retention coordinator owns scheduled purging (ADR-0173 §C).
+    Controlled by TASK_RUN_RETENTION_DAYS (default 30) plus any operator override;
+    a resolved window of None disables auto-purge.
+    """
+    from trueppm_api.apps.observability.retention import resolve_retention
+
+    if resolve_retention("TASK_RUN_RETENTION_DAYS") is None:
+        return {"deleted": 0, "skipped": "retention disabled"}
+    return {"deleted": _do_taskrun_purge()}