trueppm-api 0.4.0b2__py3-none-any.whl

trueppm_api/apps/projects/share_views.py

@@ -0,0 +1,374 @@
+"""API views for public read-only board share links (#283, ADR-0245).
+
+Three authenticated management routes (Admin+, project-scoped) plus one public,
+unauthenticated, read-only board endpoint. The public view mirrors
+``InviteAcceptView``: ``AllowAny`` + no authentication + a dedicated anon throttle
++ enumeration-safe generic errors.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Callable
+from typing import Any
+
+from django.shortcuts import get_object_or_404
+from drf_spectacular.utils import OpenApiResponse, extend_schema
+from rest_framework import status
+from rest_framework.permissions import AllowAny, BasePermission, IsAuthenticated
+from rest_framework.request import Request
+from rest_framework.response import Response
+from rest_framework.throttling import AnonRateThrottle, BaseThrottle, UserRateThrottle
+from rest_framework.views import APIView
+
+from trueppm_api.apps.access.permissions import (
+    IsNotTokenAuthenticated,
+    IsProjectAdmin,
+    IsProjectNotArchived,
+)
+from trueppm_api.apps.idempotency.mixins import IdempotencyMixin
+from trueppm_api.apps.projects import share_services
+from trueppm_api.apps.projects.models import Project, ShareContentKind, ShareLink
+from trueppm_api.apps.projects.share_serializers import (
+    ShareLinkCreateResponseSerializer,
+    ShareLinkCreateSerializer,
+    ShareLinkSerializer,
+)
+from trueppm_api.apps.projects.sharing_settings import (
+    public_sharing_instance_enabled,
+    resolve_effective_sharing,
+)
+
+# Uniform 404 detail — the kill switch, an unknown token, and a policy-disabled
+# link must all be indistinguishable to the recipient.
+_LINK_UNAVAILABLE_DETAIL = "This share link isn't available."
+
+
+class ShareLinkMintThrottle(UserRateThrottle):
+    """Caps how fast one account can mint share links (bounds link-spraying)."""
+
+    scope = "share_mint"
+
+
+class ShareLinkAccessThrottle(AnonRateThrottle):
+    """Defense-in-depth rate limit on the unauthenticated public board endpoint.
+
+    The 256-bit token is already non-enumerable; this bounds scraping/abuse of a
+    legitimately-shared (or leaked) link so it can't become an unauthenticated,
+    unthrottled load source on a self-hosted box (Omar's VoC concern).
+    """
+
+    scope = "share_access"
+
+
+def _sharing_enabled() -> bool:
+    """Instance kill switch (ADR-0245). Operators disable public sharing org-wide."""
+    return public_sharing_instance_enabled()
+
+
+def _public_sharing_allowed(project: Project) -> bool:
+    """Effective public-sharing policy (ADR-0135) for ``project`` — resolved through
+    workspace → program → project inheritance, honoring any Enterprise org-wide
+    enforcement lock. This is the admin-level "Public sharing" toggle on the General
+    settings page; both minting and serving a public board link require it to be on,
+    layered on top of the operator-level instance kill switch above. Turning it off
+    therefore blocks new links AND immediately stops existing ones from resolving.
+    """
+    return resolve_effective_sharing(project, "public_sharing")
+
+
+class ProjectShareLinkListCreateView(IdempotencyMixin, APIView):
+    """GET/POST ``/api/v1/projects/{project_pk}/share-links/`` — Admin+ only.
+
+    GET lists the project's *active* links (revoked links drop out). POST mints a
+    new link and returns the raw token exactly once. Idempotency-Key support (ADR-0170)
+    protects the mint from a duplicate link on a client retry.
+    """
+
+    permission_classes = [IsAuthenticated, IsProjectAdmin]  # noqa: RUF012
+
+    def get_permissions(self) -> list[BasePermission]:
+        # Minting a new public link is a write, so block it on an archived
+        # (hard read-only) project — matching the ProjectApiToken convention.
+        # Listing stays allowed on an archived project (it is a read).
+        perms: list[BasePermission] = [IsAuthenticated(), IsProjectAdmin()]
+        if self.request.method == "POST":
+            perms.append(IsProjectNotArchived())
+            # IsNotTokenAuthenticated (#2939): minting a share link is minting a
+            # durable public-access grant, same shape as #2878's PAT-manages-PAT
+            # rule. Scoped to POST — GET only returns the ShareLinkSerializer's
+            # metadata (never the raw token), so listing isn't a reconnaissance
+            # step the way /me/api-tokens/'s GET is.
+            perms.append(IsNotTokenAuthenticated())
+        return perms
+
+    def get_throttles(self) -> list[BaseThrottle]:
+        # Only the mint (POST) is rate-limited; listing rides the default user rate.
+        if self.request.method == "POST":
+            return [ShareLinkMintThrottle()]
+        return super().get_throttles()
+
+    @extend_schema(
+        summary="List active board share links for a project",
+        responses={200: ShareLinkSerializer(many=True)},
+    )
+    def get(self, request: Request, project_pk: str) -> Response:
+        project = get_object_or_404(Project, pk=project_pk)
+        self.check_object_permissions(request, project)
+        links = project.share_links.filter(revoked_at__isnull=True)
+        return Response(ShareLinkSerializer(links, many=True).data)
+
+    @extend_schema(
+        summary="Create a board share link (returns the raw token once)",
+        request=ShareLinkCreateSerializer,
+        responses={
+            201: ShareLinkCreateResponseSerializer,
+            403: OpenApiResponse(description="Public board sharing is disabled on this instance."),
+        },
+    )
+    def post(self, request: Request, project_pk: str) -> Response:
+        project = get_object_or_404(Project, pk=project_pk)
+        self.check_object_permissions(request, project)
+        if not _sharing_enabled():
+            return Response(
+                {"detail": "Public board sharing is disabled on this instance."},
+                status=status.HTTP_403_FORBIDDEN,
+            )
+        if not _public_sharing_allowed(project):
+            # The admin-level "Public sharing" policy (ADR-0135) is off for this
+            # project (or an ancestor / an Enterprise org-wide lock) — respect it.
+            return Response(
+                {"detail": "Public sharing is turned off for this project."},
+                status=status.HTTP_403_FORBIDDEN,
+            )
+        write = ShareLinkCreateSerializer(data=request.data)
+        write.is_valid(raise_exception=True)
+        link, raw = share_services.mint_share_link(
+            project,
+            request.user,
+            label=write.validated_data["label"],
+            show_assignees=write.validated_data["show_assignees"],
+            show_milestone_dates=write.validated_data["show_milestone_dates"],
+            content_kind=write.validated_data["content_kind"],
+            expires_at=write.validated_data["expires_at"],
+        )
+        data: dict[str, Any] = dict(ShareLinkSerializer(link).data)
+        # One-time reveal: the raw token and its relative path exist only here. The
+        # web client composes the absolute URL from its own origin. The path segment
+        # mirrors content_kind (/share/board/… or /share/schedule/…), but the token's
+        # authority is bound to the (hash, content_kind) tuple, not the route.
+        data["token"] = raw
+        data["share_path"] = f"/share/{link.content_kind}/{raw}"
+        return Response(data, status=status.HTTP_201_CREATED)
+
+
+class ProjectShareLinkRevokeView(IdempotencyMixin, APIView):
+    """POST ``/api/v1/projects/{project_pk}/share-links/{link_id}/revoke/`` — Admin+.
+
+    Idempotent soft-revoke. Works regardless of the instance kill switch (an
+    operator disabling sharing should not strand an Admin from revoking an old link).
+    Also carries the Idempotency-Key mixin (ADR-0170) like every other unsafe-method
+    TruePPM view — mirrors ``ProjectApiTokenViewSet.destroy``, which is naturally
+    idempotent too but still opts in rather than claiming ``idempotency_exempt``.
+    """
+
+    permission_classes = [IsAuthenticated, IsProjectAdmin]  # noqa: RUF012
+    # Exempt from the archived-write invariant (#3414), for the same reason the kill
+    # switch does not block it: revocation REMOVES access, and an archived project's
+    # share links keep serving. `_serve_public_share` 410s a link whose project is in
+    # Trash, not one whose project is archived — so gating revoke would leave an Admin
+    # watching a live public link on a frozen plan with no way to kill it short of
+    # unarchiving. Minting a link IS gated: `ProjectShareLinkListCreateView` carries
+    # `IsProjectNotArchived`.
+    archived_write_exempt = (
+        "revocation only removes access; an archived project's links keep serving, so "
+        "blocking revoke would strand an Admin with a live public link"
+    )
+
+    @extend_schema(
+        summary="Revoke a board share link",
+        request=None,
+        responses={
+            200: ShareLinkSerializer,
+            404: OpenApiResponse(description="No such share link on this project."),
+        },
+    )
+    def post(self, request: Request, project_pk: str, link_id: str) -> Response:
+        project = get_object_or_404(Project, pk=project_pk)
+        self.check_object_permissions(request, project)
+        link = get_object_or_404(ShareLink, pk=link_id, project=project)
+        share_services.revoke_share_link(link, request.user)
+        link.refresh_from_db()
+        return Response(ShareLinkSerializer(link).data)
+
+
+def _serve_public_share(
+    request: Request,
+    token: str,
+    content_kind: str,
+    serialize: Callable[[ShareLink], dict[str, Any]],
+) -> Response:
+    """Shared serve path for a public read-only share token (#283, #1486).
+
+    Board and schedule expose different projections but share an identical security
+    envelope: instance kill switch → uniform ``404``; unknown/wrong-kind token →
+    ``404``; revoked / expired / project in Trash → ``410``; ADR-0135 policy off
+    → ``404``; otherwise a weak
+    ``ETag`` + ``private, max-age=30`` so embeds re-poll cheaply. The wrong-kind
+    firewall is the ``content_kind`` filter inside ``resolve_share_link``: a board
+    token resolved here as ``SCHEDULE`` (or vice-versa) returns ``None`` → ``404``.
+    """
+    # Kill switch → uniform 404 (do not reveal the feature exists, and
+    # retroactively disable every existing link while off).
+    if not _sharing_enabled():
+        return Response(
+            {"detail": _LINK_UNAVAILABLE_DETAIL},
+            status=status.HTTP_404_NOT_FOUND,
+        )
+
+    link = share_services.resolve_share_link(token, content_kind)
+    if link is None:
+        return Response(
+            {"detail": _LINK_UNAVAILABLE_DETAIL},
+            status=status.HTTP_404_NOT_FOUND,
+        )
+    if link.revoked_at is not None:
+        return Response(
+            {"detail": "This share link has been revoked."},
+            status=status.HTTP_410_GONE,
+        )
+    if link.is_expired:
+        # Expiry and revocation are both "intentionally gone" → 410 (not 404), so
+        # the recipient knows the link was real and asks the owner for a new one.
+        return Response(
+            {"detail": "This share link has expired."},
+            status=status.HTTP_410_GONE,
+        )
+    if link.project.is_deleted:
+        # Trash means gone, publicly too (#2607). Moving a project to Trash used
+        # to leave its public links serving, so an owner who "removed" a project
+        # was still publishing it to anyone holding a link.
+        #
+        # 410 rather than 404: this is the same "intentionally gone" family as
+        # revocation and expiry, and it reveals nothing — the recipient already
+        # held a valid link to this project.
+        #
+        # Checked at read time rather than by revoking the links on delete, so
+        # restoring from Trash restores exactly the link state the project had
+        # (a revoked link stays revoked, an active one resumes). A revoke-on-
+        # delete would have to remember which links it revoked in order to undo
+        # itself, and would get that wrong the first time someone revoked a link
+        # by hand while the project sat in Trash.
+        return Response(
+            {"detail": "This project has been moved to Trash."},
+            status=status.HTTP_410_GONE,
+        )
+    if not _public_sharing_allowed(link.project):
+        # The "Public sharing" policy (ADR-0135) was turned off for this project
+        # (or an ancestor) after the link was minted — stop resolving it.
+        #
+        # 410, not 404 (#2697): this is the same "intentionally gone" family as
+        # revocation, expiry and Trash above — the link was real and an admin
+        # deliberately withdrew it. 404 would tell the recipient "no such thing",
+        # which is the wrong thing to tell someone holding a link that worked
+        # yesterday, and it contradicted the workspace toggle's own help copy.
+        #
+        # It reveals nothing the sibling branches do not: reaching this line
+        # means the token already resolved, so the recipient demonstrably held a
+        # valid link to this project. The instance kill switch above stays 404
+        # because it answers *before* resolution and cannot distinguish a real
+        # token from a forged one.
+        return Response(
+            {"detail": "Public sharing has been turned off for this project."},
+            status=status.HTTP_410_GONE,
+        )
+
+    payload = serialize(link)
+    body = json.dumps(payload, sort_keys=True, separators=(",", ":"))
+    etag = 'W/"' + hashlib.sha256(body.encode()).hexdigest()[:32] + '"'
+
+    if request.headers.get("If-None-Match") == etag:
+        resp = Response(status=status.HTTP_304_NOT_MODIFIED)
+    else:
+        resp = Response(payload)
+        # Count a fresh delivery only; 304 re-polls of unchanged content don't
+        # inflate the "viewed N times" meter.
+        share_services.record_access(link)
+    resp["ETag"] = etag
+    # `private` (not `public`): a revoked link must stop resolving promptly, so a
+    # shared/CDN cache must never serve a since-revoked snapshot to another viewer.
+    # The per-viewer browser cache + ETag still make re-polls cheap.
+    resp["Cache-Control"] = "private, max-age=30"
+    # The token is a capability URL; keep it out of any Referer sent from the
+    # public page's subresource/outbound requests (defense-in-depth alongside the
+    # page's own <meta name="referrer">).
+    resp["Referrer-Policy"] = "no-referrer"
+    return resp
+
+
+class PublicBoardShareView(APIView):
+    """GET ``/api/v1/share/board/{token}/`` — public, unauthenticated, read-only.
+
+    Returns a minimized board snapshot. ``410`` for a revoked or expired link or a
+    Trashed project, ``404`` for an
+    unknown/invalid token or when the instance kill switch is off (uniform 404 hides
+    whether the feature or a given link exists). A weak ``ETag`` + short
+    ``Cache-Control`` lets embeds re-poll cheaply.
+    """
+
+    permission_classes = [AllowAny]  # noqa: RUF012
+    authentication_classes: list[Any] = []  # noqa: RUF012
+    throttle_classes = [ShareLinkAccessThrottle]  # noqa: RUF012
+    http_method_names = ["get"]  # noqa: RUF012
+
+    @extend_schema(
+        summary="Public read-only board snapshot for a share token",
+        responses={
+            200: OpenApiResponse(
+                description="Minimized board snapshot (columns + whitelisted cards)."
+            ),
+            404: OpenApiResponse(description="Unknown/invalid token, or sharing disabled."),
+            410: OpenApiResponse(
+                description="This share link has been revoked or has expired, "
+                "or the project was moved to Trash."
+            ),
+        },
+    )
+    def get(self, request: Request, token: str) -> Response:
+        return _serve_public_share(
+            request, token, ShareContentKind.BOARD, share_services.serialize_public_board
+        )
+
+
+class PublicScheduleShareView(APIView):
+    """GET ``/api/v1/share/schedule/{token}/`` — public, unauthenticated, read-only.
+
+    Sibling of :class:`PublicBoardShareView` for the schedule/Gantt projection
+    (#1486, ADR-0265). Same security envelope; only the resolved ``content_kind``
+    and the projection differ. A board token can never resolve here — the
+    ``content_kind`` discriminator in ``resolve_share_link`` returns ``None`` → 404.
+    """
+
+    permission_classes = [AllowAny]  # noqa: RUF012
+    authentication_classes: list[Any] = []  # noqa: RUF012
+    throttle_classes = [ShareLinkAccessThrottle]  # noqa: RUF012
+    http_method_names = ["get"]  # noqa: RUF012
+
+    @extend_schema(
+        summary="Public read-only schedule snapshot for a share token",
+        responses={
+            200: OpenApiResponse(
+                description="Minimized schedule snapshot (tasks + dependency edges)."
+            ),
+            404: OpenApiResponse(description="Unknown/invalid token, or sharing disabled."),
+            410: OpenApiResponse(
+                description="This share link has been revoked or has expired, "
+                "or the project was moved to Trash."
+            ),
+        },
+    )
+    def get(self, request: Request, token: str) -> Response:
+        return _serve_public_share(
+            request, token, ShareContentKind.SCHEDULE, share_services.serialize_public_schedule
+        )

trueppm_api/apps/projects/sharing_settings.py

@@ -0,0 +1,187 @@
+"""Workspace → Program → Project sharing-settings resolution (ADR-0135, #978).
+
+``public_sharing`` (anyone with the link can view, no sign-in) and ``allow_guests``
+(external collaborators) are set at the workspace by default and may be overridden
+per program/project. The *effective* value is resolved here, computed-on-read
+(ADR-0108) — there is no stored/denormalized effective column to keep in sync.
+Clients (web, mobile, MCP) read the serializer's ``effective_public_sharing`` /
+``effective_allow_guests``; they never re-implement this precedence.
+
+Precedence: project override → program override → workspace value.
+``inherited_*`` answers "what would I get if this scope's override were cleared?"
+(i.e. the parent's effective value) and drives the settings "Inherit (On/Off)"
+affordance.
+
+``ENFORCE`` (a workspace admin locking sharing so lower scopes cannot *loosen* it)
+is an Enterprise capability. OSS ships the neutral hook below and registers no
+provider, so ``ENFORCE`` degrades to ``SUGGEST`` (no lock) — a program/project may
+freely loosen or tighten. trueppm-enterprise registers a provider in its
+``AppConfig.ready()`` — the integrations-registry idiom (ADR-0029/0049), mirroring
+``iteration_label.register_terminology_enforcement_provider``. OSS never imports
+enterprise.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+from django.conf import settings
+
+from trueppm_api.core.extension_providers import guard_single_provider
+
+if TYPE_CHECKING:
+    from trueppm_api.apps.projects.models import Program, Project
+    from trueppm_api.apps.workspace.models import Workspace
+
+#: The two inheritable sharing booleans. The field name is identical on
+#: Workspace (non-null root), Program, and Project (nullable override), so the
+#: resolver below is field-agnostic.
+SHARING_FIELDS = ("public_sharing", "allow_guests")
+
+# Enterprise registers a zero-arg predicate that returns True when sharing
+# enforcement is licensed/active. OSS leaves it None → enforcement inactive, so
+# ENFORCE behaves as SUGGEST (no lock).
+_ENFORCEMENT_PROVIDER: Callable[[], bool] | None = None
+
+
+def register_sharing_enforcement_provider(provider: Callable[[], bool] | None) -> None:
+    """Register (or clear) the sharing-enforcement provider. Enterprise calls this."""
+    global _ENFORCEMENT_PROVIDER
+    _ENFORCEMENT_PROVIDER = guard_single_provider(
+        _ENFORCEMENT_PROVIDER, provider, "sharing enforcement"
+    )
+
+
+def sharing_enforcement_active() -> bool:
+    """True only when an enterprise provider is registered AND reports active.
+
+    OSS has no provider → always False, so a workspace ``ENFORCE`` policy never
+    locks downstream sharing overrides in the community edition.
+    """
+    return _ENFORCEMENT_PROVIDER is not None and bool(_ENFORCEMENT_PROVIDER())
+
+
+def public_sharing_instance_enabled() -> bool:
+    """Operator-level kill switch (ADR-0245) — public sharing org-wide, on or off.
+
+    This is a strictly *coarser* gate than :func:`resolve_effective_sharing`: it
+    answers "does this instance serve public links at all", before any
+    workspace/program/project policy is consulted. The share views check it first
+    and answer 404 (not 410) because it fires before token resolution and so
+    cannot distinguish a real token from a forged one.
+
+    It lives here rather than in the views because it is half of the answer to
+    "will a link I mint actually resolve?", and non-view callers need to ask that
+    question too — ``create_demo_share_link`` does, so it can refuse to print a
+    URL the instance will never serve (#2781).
+    """
+    return bool(getattr(settings, "TRUEPPM_PUBLIC_BOARD_SHARING_ENABLED", True))
+
+
+def default_share_link_expiry_days() -> int:
+    """Days a minted link lasts when the caller does not say (#3177).
+
+    Applies only when ``expires_at`` is **absent** from the request. An explicit
+    ``null`` still mints a link that never expires — a standing wallboard or embed is
+    a real use case and this is a default, not a ceiling.
+
+    Why a default at all: the share *serve* path is thorough — it re-checks the kill
+    switch, revocation, expiry, project Trash and the ADR-0135 policy on every read —
+    but all of that is someone remembering to act. A link nobody revokes serves
+    delivery status to whoever still holds the URL, including after they leave. The
+    web dialog already prefills a 30-day nudge, so this closes the gap for callers
+    that are not the dialog: agent tokens, MCP clients, integrators and scripts, which
+    previously minted a permanent link by saying nothing.
+
+    ``0`` or a negative value restores the pre-#3177 behavior (omitted means never)
+    for an operator who wants it.
+    """
+    return int(getattr(settings, "TRUEPPM_SHARE_LINK_DEFAULT_EXPIRY_DAYS", 90))
+
+
+def _enforced(workspace: Workspace) -> bool:
+    """Whether the workspace value is a hard ceiling (Enterprise lock active)."""
+    from trueppm_api.apps.workspace.models import TermOverridePolicy
+
+    return (
+        workspace.public_sharing_override_policy == TermOverridePolicy.ENFORCE
+        and sharing_enforcement_active()
+    )
+
+
+def resolve_effective_sharing(
+    obj: Program | Project,
+    field: str,
+    *,
+    workspace: Workspace | None = None,
+) -> bool:
+    """Resolve the effective value of ``field`` for a program or project.
+
+    ``workspace`` may be passed to avoid re-loading the singleton per object when
+    resolving a list (the serializer caches it once); otherwise it is loaded here.
+    """
+    from trueppm_api.apps.workspace.models import Workspace
+
+    if workspace is None:
+        workspace = Workspace.load()
+
+    ws_value = bool(getattr(workspace, field))
+    if _enforced(workspace):
+        # Enterprise lock: the workspace value wins regardless of lower overrides.
+        return ws_value
+
+    own = getattr(obj, field)  # nullable override on Program/Project
+    if own is not None:
+        return bool(own)
+    return _parent_value(obj, field, workspace=workspace)
+
+
+def resolve_inherited_sharing(
+    obj: Program | Project,
+    field: str,
+    *,
+    workspace: Workspace | None = None,
+) -> bool:
+    """Value ``obj`` would inherit if its own override were cleared.
+
+    Drives the settings "Inherit (On/Off)" affordance — it deliberately skips
+    ``obj``'s own override and resolves from the parent up. Under an active
+    Enterprise lock the inherited value is the (ceiling) workspace value.
+    """
+    from trueppm_api.apps.workspace.models import Workspace
+
+    if workspace is None:
+        workspace = Workspace.load()
+
+    if _enforced(workspace):
+        return bool(getattr(workspace, field))
+    return _parent_value(obj, field, workspace=workspace)
+
+
+def _parent_value(
+    obj: Program | Project,
+    field: str,
+    *,
+    workspace: Workspace,
+) -> bool:
+    """Resolve ``field`` from ``obj``'s parent scope up to the workspace.
+
+    A Program's parent is the workspace. A Project's parent is its program (whose
+    own override resolves up to the workspace) or, if standalone, the workspace.
+    """
+    # Local import keeps this module import-safe from migrations.
+    from trueppm_api.apps.projects.models import Program
+
+    # A Program's parent is the workspace (no intermediate scope); a Project's
+    # parent is its program, if it has one.
+    program: Program | None = None
+    if not isinstance(obj, Program) and obj.program_id:
+        program = obj.program
+
+    if program is not None:
+        program_override = getattr(program, field)
+        if program_override is not None:
+            return bool(program_override)
+
+    return bool(getattr(workspace, field))