trueppm-api 0.4.0__py3-none-any.whl

trueppm_api/apps/projects/share_serializers.py

@@ -0,0 +1,142 @@
+"""Serializers for board share-link management (#283, ADR-0245).
+
+The public board snapshot is built as a plain dict by
+``share_services.serialize_public_board`` (a minimized, whitelisted shape), so it
+has no serializer here — these cover only the authenticated management surface.
+``token_hash`` is never exposed; only the non-revealing ``token_prefix`` is.
+"""
+
+from __future__ import annotations
+
+from datetime import timedelta
+from typing import Any
+
+from django.utils import timezone
+from drf_spectacular.utils import extend_schema_field
+from rest_framework import serializers
+
+from trueppm_api.apps.projects.models import ShareContentKind, ShareLink
+from trueppm_api.apps.projects.sharing_settings import (
+    default_share_link_expiry_days,
+)
+from trueppm_api.apps.workspace.serializers import display_name_for
+
+
+class ShareLinkSerializer(serializers.ModelSerializer[ShareLink]):
+    """Read serializer for a share link in the management list.
+
+    Deliberately omits ``token_hash`` (secret) — the raw token is only ever
+    returned once, in the create response, via ``ShareLinkCreateResponseSerializer``.
+    """
+
+    # ``created_by`` is the creator's integer user PK — the same wire meaning it has
+    # on every other schema — and ``created_by_name`` carries the display name, per
+    # the ``*_name`` convention. Both are null once the creator is deleted
+    # (``on_delete=SET_NULL``).
+    created_by: serializers.PrimaryKeyRelatedField[Any] = serializers.PrimaryKeyRelatedField(
+        read_only=True, allow_null=True
+    )
+    created_by_name = serializers.SerializerMethodField()
+    is_active = serializers.BooleanField(read_only=True)
+
+    class Meta:
+        model = ShareLink
+        fields = [  # noqa: RUF012
+            "id",
+            "content_kind",
+            "token_prefix",
+            "label",
+            "show_assignees",
+            "show_milestone_dates",
+            "created_by",
+            "created_by_name",
+            "created_at",
+            "expires_at",
+            "revoked_at",
+            "access_count",
+            "last_accessed_at",
+            "is_active",
+            "is_expired",
+        ]
+        read_only_fields = fields
+
+    @extend_schema_field(serializers.CharField(allow_null=True))
+    def get_created_by_name(self, obj: ShareLink) -> str | None:
+        user = obj.created_by
+        if user is None:
+            return None
+        return display_name_for(user.first_name, user.last_name, user.username)
+
+
+class ShareLinkCreateSerializer(serializers.Serializer[Any]):
+    """Write serializer for minting a link. All fields optional; safe defaults."""
+
+    # ``label`` shadows DRF's ``Field.label`` attribute; the stub flags the
+    # assignment though it is valid at runtime (same pattern as observability).
+    label = serializers.CharField(  # type: ignore[assignment]
+        max_length=120, required=False, allow_blank=True, default=""
+    )
+    show_assignees = serializers.BooleanField(required=False, default=False)
+    # Schedule links only (#2532). Defaults TRUE — omitting it must mint exactly the
+    # link a pre-#2532 client minted, so this is an opt-out, not an opt-in.
+    show_milestone_dates = serializers.BooleanField(required=False, default=True)
+    # Which view the link exposes; defaults to board for backward compatibility
+    # with pre-#1486 clients that never sent the field.
+    content_kind = serializers.ChoiceField(
+        choices=ShareContentKind.choices,
+        default=ShareContentKind.BOARD,
+    )
+    # Optional auto-expiry (#1486, #3177). An explicit ``null`` means never expires;
+    # OMITTING the field now means "the instance default" (90 days out of the box).
+    #
+    # No ``default=`` on purpose — that is what makes the two distinguishable. With a
+    # default, DRF materializes the key in ``validated_data`` whether the caller sent
+    # it or not, and "absent" and "explicit null" collapse into the same value. Absent
+    # is filled in ``validate()`` instead.
+    expires_at = serializers.DateTimeField(required=False, allow_null=True)
+
+    def validate_expires_at(self, value: Any) -> Any:
+        """Reject an expiry in the past — a link that is born already-gone is a
+        client bug, not a valid state, and would confusingly mint then 410."""
+        if value is not None and value <= timezone.now():
+            raise serializers.ValidationError("Expiry must be in the future.")
+        return value
+
+    def validate(self, attrs: dict[str, Any]) -> dict[str, Any]:
+        """Force ``show_milestone_dates`` back to True on a non-schedule link (#2532).
+
+        The board projection publishes milestone cards *with their due dates* and has
+        no notion of this flag, so persisting a client's ``false`` would store — and
+        echo back through the read serializer — a restriction the public board
+        endpoint does not apply. Rather than 400 on a field that is merely
+        inapplicable, normalize it, so the stored row can never claim a guarantee the
+        server is not keeping.
+        """
+        if attrs.get("content_kind") != ShareContentKind.SCHEDULE:
+            attrs["show_milestone_dates"] = True
+
+        # Absent (not null) → the instance default window (#3177). The web dialog always
+        # sends a value, so this is the path taken by every non-dialog caller: agent
+        # tokens, MCP clients, integrators, scripts. Those previously minted a permanent
+        # link by saying nothing, which is the one default a sharing feature should not
+        # have. An explicit null is left alone and still means never.
+        if "expires_at" not in attrs:
+            days = default_share_link_expiry_days()
+            attrs["expires_at"] = timezone.now() + timedelta(days=days) if days > 0 else None
+        return attrs
+
+
+class ShareLinkCreateResponseSerializer(ShareLinkSerializer):
+    """Create response: the full row plus the one-time raw token and its relative path.
+
+    ``token`` and ``share_path`` are present ONLY on this response and never again —
+    the web client composes the absolute URL from ``window.location.origin`` so the
+    API stays decoupled from the frontend origin.
+    """
+
+    token = serializers.CharField(read_only=True)
+    share_path = serializers.CharField(read_only=True)
+
+    class Meta(ShareLinkSerializer.Meta):
+        fields = [*ShareLinkSerializer.Meta.fields, "token", "share_path"]  # noqa: RUF012
+        read_only_fields = fields

trueppm_api/apps/projects/share_services.py

@@ -0,0 +1,373 @@
+"""Service layer for public read-only board share links (#283, ADR-0245).
+
+Keeps token hashing, minimization, and access metering in one auditable place so
+the views stay thin. Token handling mirrors the ``ApiToken`` / ``WorkspaceInvite``
+lineage: the raw token is returned once at mint and only its SHA-256 hash is
+persisted; lookup is O(1) on the unique hash index.
+"""
+
+from __future__ import annotations
+
+import logging
+import secrets
+from collections.abc import Callable
+from typing import Any, cast
+
+from django.conf import settings
+from django.core.cache import cache
+from django.db.models import F
+from django.utils import timezone
+
+from trueppm_api.apps.projects.authentication import sha256_hex
+from trueppm_api.apps.projects.models import (
+    BoardColumnConfig,
+    Dependency,
+    ShareContentKind,
+    ShareLink,
+    Task,
+    TaskStatus,
+)
+from trueppm_api.apps.workspace.serializers import display_name_for
+
+logger = logging.getLogger(__name__)
+
+# The board columns shown publicly when a project has no custom BoardColumnConfig:
+# the standard non-backlog workflow lane, in order. Backlog is deliberately never
+# published (ADR-0245) — a shared board is a delivery-status surface, not the intake
+# pool, and unrefined backlog items are the most likely to carry sensitive names.
+_PUBLIC_DEFAULT_STATUSES = (
+    TaskStatus.NOT_STARTED,
+    TaskStatus.IN_PROGRESS,
+    TaskStatus.REVIEW,
+    TaskStatus.COMPLETE,
+)
+
+
+def mint_share_link(
+    project: Any,
+    user: Any,
+    *,
+    label: str = "",
+    show_assignees: bool = False,
+    show_milestone_dates: bool = True,
+    content_kind: str = ShareContentKind.BOARD,
+    expires_at: Any = None,
+) -> tuple[ShareLink, str]:
+    """Create a share link and return ``(link, raw_token)``.
+
+    The raw token is non-enumerable (``secrets.token_urlsafe(32)`` ≈ 256 bits) and
+    is returned exactly once — only its hash is stored, so it can never be
+    retrieved again. ``expires_at`` (optional, #1486) auto-expires the link — after
+    it passes, the public endpoint returns 410 exactly like a revoked link.
+    ``show_milestone_dates`` (#2532, schedule links only) defaults **True** so a
+    caller that omits it mints exactly the link it minted before the flag existed.
+    """
+    raw = secrets.token_urlsafe(32)
+    link = ShareLink.objects.create(
+        project=project,
+        content_kind=content_kind,
+        token_prefix=raw[:12],
+        token_hash=sha256_hex(raw),
+        label=label,
+        show_assignees=show_assignees,
+        show_milestone_dates=show_milestone_dates,
+        expires_at=expires_at,
+        created_by=user if getattr(user, "is_authenticated", False) else None,
+    )
+    logger.info(
+        "share_link.minted id=%s project=%s kind=%s by=%s",
+        link.id,
+        project.id,
+        content_kind,
+        getattr(user, "id", None),
+    )
+    return link, raw
+
+
+def revoke_share_link(link: ShareLink, user: Any) -> None:
+    """Soft-revoke a link. Idempotent — re-revoking an already-revoked link is a no-op."""
+    if link.revoked_at is not None:
+        return
+    link.revoked_at = timezone.now()
+    link.revoked_by = user if getattr(user, "is_authenticated", False) else None
+    link.save(update_fields=["revoked_at", "revoked_by"])
+    logger.info(
+        "share_link.revoked id=%s project=%s by=%s",
+        link.id,
+        link.project_id,
+        getattr(user, "id", None),
+    )
+
+
+def resolve_share_link(token: str, content_kind: str) -> ShareLink | None:
+    """Return the ``ShareLink`` for a raw token (active *or* revoked), or ``None``.
+
+    Looks up by SHA-256 hash — O(1) on the unique index, no per-row compare, so
+    there is no timing-oracle to enumerate against. Filtered on ``content_kind`` so
+    a board token can never resolve a schedule view (forward-compat for #1486). The
+    caller distinguishes revoked (→ 410) from unknown (``None`` → 404).
+    """
+    if not token:
+        return None
+    return (
+        ShareLink.objects.filter(token_hash=sha256_hex(token), content_kind=content_kind)
+        .select_related("project", "created_by")
+        .first()
+    )
+
+
+def record_access(link: ShareLink) -> None:
+    """Bump the access meter with a single atomic UPDATE (no ``save()``, no history).
+
+    Mirrors ``ApiToken.last_used_at``. An ``F()`` increment is retry-safe; a rare
+    double-count on a client retry is acceptable for a view meter.
+    """
+    ShareLink.objects.filter(pk=link.pk).update(
+        access_count=F("access_count") + 1,
+        last_accessed_at=timezone.now(),
+    )
+
+
+# TTL matches the client-facing `Cache-Control: private, max-age=30` in
+# share_views.py (#4226) — a server-side cache hit is never staler than what a
+# browser already tolerates on a re-poll. Short on purpose: the projection changes
+# at most once a day (the demo reset job, or a real workspace's own edits), so a
+# bounded TTL is enough to collapse a burst of concurrent visitors on the same link
+# into one DB round trip without needing explicit invalidation on every write that
+# could touch the payload.
+SHARE_PAYLOAD_CACHE_TTL = 30
+
+
+def _share_payload_cache_key(link: ShareLink) -> str:
+    """Cache key for one link's built projection.
+
+    Keyed on pk, not token: the token is only ever hashed on the way in
+    (``resolve_share_link``), and by the time this key is built the caller already
+    holds the resolved row. ``content_kind`` is folded in even though a pk alone is
+    unique, purely so the key is self-describing in a cache dump.
+    """
+    return f"share-payload:{link.content_kind}:{link.pk}"
+
+
+def get_cached_public_payload(
+    link: ShareLink, serialize: Callable[[ShareLink], dict[str, Any]]
+) -> dict[str, Any]:
+    """Serve ``serialize(link)`` from Valkey when a recent build exists, else build and cache it.
+
+    Collapses concurrent visitors on the same share link into one DB-hitting build
+    per TTL window instead of one per request (#4226) — the projection queries
+    (``serialize_public_board`` / ``serialize_public_schedule``) previously ran on
+    every single request with no server-side cache in front of them, despite Valkey
+    already being deployed for every instance that serves this view.
+    """
+    key = _share_payload_cache_key(link)
+    payload = cache.get(key)
+    if payload is None:
+        payload = serialize(link)
+        cache.set(key, payload, timeout=SHARE_PAYLOAD_CACHE_TTL)
+        return payload
+    # cache.get()'s return type is untyped (Any) — cast rather than trust it, since
+    # this branch returns whatever a previous call stored under this key.
+    return cast("dict[str, Any]", payload)
+
+
+def _public_columns(project: Any) -> list[dict[str, str]]:
+    """Ordered ``[{key, label}]`` columns to publish (config order, backlog excluded)."""
+    try:
+        config = BoardColumnConfig.objects.get(project=project)
+        cols = config.columns or None
+    except BoardColumnConfig.DoesNotExist:
+        cols = None
+    if cols:
+        return [
+            {"key": c["status"], "label": c.get("label") or c["status"].replace("_", " ").title()}
+            for c in cols
+            if c.get("visible", True) and c["status"] != TaskStatus.BACKLOG.value
+        ]
+    return [{"key": s.value, "label": s.label} for s in _PUBLIC_DEFAULT_STATUSES]
+
+
+def _public_card(task: Task, show_assignees: bool) -> dict[str, Any]:
+    """Minimized, whitelisted card. Comments/notes/attachments/points are never emitted."""
+    due = task.early_finish or task.planned_start
+    card: dict[str, Any] = {
+        "short_id": task.short_id,
+        "name": task.name,
+        "status": task.status,
+        "is_milestone": task.is_milestone,
+        "percent_complete": task.percent_complete,
+        "due_date": due.isoformat() if due else None,
+        "assignee": None,
+    }
+    # Assignee identity is opt-in only (ADR-0245): a display name, never email/id/avatar.
+    assignee = task.assignee
+    if show_assignees and assignee is not None:
+        card["assignee"] = display_name_for(
+            assignee.first_name, assignee.last_name, assignee.username
+        )
+    return card
+
+
+def serialize_public_board(link: ShareLink) -> dict[str, Any]:
+    """Build the minimized, bounded public board snapshot for ``link``.
+
+    Excludes soft-deleted tasks and the backlog column; caps the payload at
+    ``SHARE_BOARD_MAX_CARDS`` and flags ``truncated`` rather than silently dropping
+    cards.
+    """
+    project = link.project
+    columns = _public_columns(project)
+    visible_statuses = [c["key"] for c in columns]
+    cap = int(getattr(settings, "SHARE_BOARD_MAX_CARDS", 1000))
+
+    qs = (
+        Task.objects.filter(
+            project=project,
+            is_deleted=False,
+            status__in=visible_statuses,
+        )
+        .select_related("assignee")
+        .order_by("status", "priority_rank", "name")
+    )
+    rows = list(qs[: cap + 1])
+    truncated = len(rows) > cap
+    rows = rows[:cap]
+
+    by_status: dict[str, list[dict[str, Any]]] = {c["key"]: [] for c in columns}
+    for task in rows:
+        by_status.setdefault(task.status, []).append(_public_card(task, link.show_assignees))
+
+    return {
+        "content_kind": link.content_kind,
+        "project": {"name": project.name, "short_id": project.code or ""},
+        "columns": [
+            {"key": c["key"], "label": c["label"], "cards": by_status.get(c["key"], [])}
+            for c in columns
+        ],
+        "show_assignees": link.show_assignees,
+        "truncated": truncated,
+    }
+
+
+def _public_schedule_task(task: Task, show_assignees: bool) -> dict[str, Any]:
+    """Minimized, whitelisted schedule row for the public timeline (#1486, ADR-0265).
+
+    Emits ONLY what a read-only Gantt needs to draw bars, structure, and the
+    critical path. Internal slack intelligence (``late_start``/``late_finish``/
+    ``total_float``/``free_float``), PERT/Monte Carlo durations and percentiles,
+    baseline overlay, cost, resource units, priority, and blocker fields are
+    excluded by omission — criticality is surfaced via the boolean ``is_critical``
+    flag, never the raw float. Assignee identity is opt-in only (a display name,
+    never email/id/avatar), matching the board projection.
+
+    ``scheduled_start`` (ADR-0752) is a **deliberate** widening of this
+    allow-list, not an incidental one: ``actual_start``/``actual_finish`` stay
+    withheld, but for an in-progress task ``scheduled_start`` *is*
+    ``actual_start`` (the span starts where work actually began). The public
+    Gantt needs the real span to draw a correct bar — an
+    ignore-``actual_start``, back-off-only span would silently draw a
+    *different* schedule than the authenticated product on the one surface
+    where trust matters most (ADR-0752 §8) — so the widening is accepted and
+    recorded here rather than left for a future reader to discover by diffing
+    field names. ``when work actually began`` is the same class of
+    delivery-status fact this projection already discloses via
+    ``percent_complete`` and ``planned_start``.
+    """
+    row: dict[str, Any] = {
+        "short_id": task.short_id,
+        "name": task.name,
+        # ltree value coerces to str ("1.2.3") for indent / summary structure.
+        "wbs_path": str(task.wbs_path) if task.wbs_path else "",
+        "duration": task.duration,
+        "planned_start": task.planned_start.isoformat() if task.planned_start else None,
+        "early_start": task.early_start.isoformat() if task.early_start else None,
+        "early_finish": task.early_finish.isoformat() if task.early_finish else None,
+        "scheduled_start": task.scheduled_start.isoformat() if task.scheduled_start else None,
+        "is_milestone": task.is_milestone,
+        # #4079: which edge of its day a milestone's diamond sits on. A pure
+        # rendering fact derived from the same dates already disclosed here.
+        "milestone_at_day_end": task.milestone_at_day_end,
+        "is_critical": bool(task.is_critical),
+        "percent_complete": task.percent_complete,
+        "status": task.status,
+        "assignee": None,
+    }
+    assignee = task.assignee
+    if show_assignees and assignee is not None:
+        row["assignee"] = display_name_for(
+            assignee.first_name, assignee.last_name, assignee.username
+        )
+    return row
+
+
+def serialize_public_schedule(link: ShareLink) -> dict[str, Any]:
+    """Build the minimized, bounded public schedule snapshot for ``link`` (#1486).
+
+    Mirrors :func:`serialize_public_board`: excludes soft-deleted tasks, caps the
+    payload at ``SHARE_SCHEDULE_MAX_TASKS`` (flagging ``truncated`` rather than
+    silently dropping), and emits dependency edges by ``short_id`` (never task
+    UUIDs) so the read-only renderer can draw links. All internal risk/float
+    intelligence is withheld — see :func:`_public_schedule_task`.
+    """
+    project = link.project
+    cap = int(getattr(settings, "SHARE_SCHEDULE_MAX_TASKS", 1000))
+
+    # Exclude the backlog exactly as the board projection does (ADR-0245): the
+    # intake pool is un-triaged and the most likely to carry sensitive raw names, so
+    # a shared schedule is a delivery-status surface, not the backlog. Backlog tasks
+    # are unscheduled anyway and would only render as "Unscheduled" noise.
+    qs = (
+        Task.objects.filter(project=project, is_deleted=False)
+        .exclude(status=TaskStatus.BACKLOG)
+        .select_related("assignee")
+        .order_by("wbs_path", "early_start", "name")
+    )
+    if not link.show_milestone_dates:
+        # Withheld in SQL, not filtered out of the page in Python (#2532): the row
+        # must never reach the response at all — the public renderer draws the
+        # diamond and its dated label straight from the payload — and excluding
+        # before the cap means hidden milestones can't consume the task budget and
+        # truncate real work away. Dropping the rows also drops their dependency
+        # edges below, since edges are bound to the published id set.
+        qs = qs.exclude(is_milestone=True)
+    rows = list(qs[: cap + 1])
+    truncated = len(rows) > cap
+    rows = rows[:cap]
+
+    published_ids = {task.id for task in rows}
+    tasks = [_public_schedule_task(task, link.show_assignees) for task in rows]
+
+    # One query for edges, both endpoints among the published (non-deleted) tasks,
+    # then map ids → short_ids in Python — no per-task/per-edge N+1. Edges to a
+    # task that was truncated away or soft-deleted are dropped so no dangling arrow
+    # is ever emitted.
+    id_to_short = {task.id: task.short_id for task in rows}
+    dependencies: list[dict[str, Any]] = []
+    # Bound the edge query to the published (capped, non-deleted) task set in SQL, so
+    # a project with far more edges than the task cap can't return rows we'd only
+    # discard in Python. The membership re-check below is then a no-op safety net.
+    edge_qs = Dependency.objects.filter(
+        is_deleted=False,
+        predecessor_id__in=published_ids,
+        successor_id__in=published_ids,
+    ).values_list("predecessor_id", "successor_id", "dep_type", "lag")
+    for pred_id, succ_id, dep_type, lag in edge_qs:
+        if pred_id in published_ids and succ_id in published_ids:
+            dependencies.append(
+                {
+                    "predecessor_short_id": id_to_short[pred_id],
+                    "successor_short_id": id_to_short[succ_id],
+                    "dep_type": dep_type,
+                    "lag": lag,
+                }
+            )
+
+    return {
+        "content_kind": link.content_kind,
+        "project": {"name": project.name, "short_id": project.code or ""},
+        "tasks": tasks,
+        "dependencies": dependencies,
+        "show_assignees": link.show_assignees,
+        "show_milestone_dates": link.show_milestone_dates,
+        "truncated": truncated,
+    }