stapel-workspaces 0.3.1__py3-none-any.whl

stapel_workspaces/__init__.py

@@ -0,0 +1,54 @@
+"""Stapel Workspaces — team workspaces and RBAC Django app for Stapel.
+
+Public API (see ``__all__``):
+
+Service functions (``stapel_workspaces.services``):
+- ``create_workspace`` — create a workspace and seed the owner membership.
+- ``ensure_personal_workspace`` — get-or-create a user's personal workspace.
+- ``create_invitation`` — invite an email address to a workspace.
+- ``accept_invitation`` — resolve an invitation into a membership.
+
+comm Function provider (``stapel_workspaces.functions``):
+- ``CHECK_MEMBERSHIP`` — name of the ``workspaces.check_membership``
+  Function (call it via ``stapel_core.comm.call``).
+- ``check_membership`` — the provider itself.
+
+Events (``stapel_workspaces.events``):
+- ``EVENT_WORKSPACE_PERSONAL_CREATED`` — comm action name emitted when a
+  personal workspace is bootstrapped.
+
+GDPR:
+- ``WorkspacesGDPRProvider`` — export/delete provider for workspace data.
+
+Signal usage (``workspace_member_changed``) stays in ``stapel_core.signals``.
+
+All exports are lazily imported (PEP 562): importing ``stapel_workspaces``
+itself does not require Django to be configured.
+"""
+
+_EXPORTS = {
+    "create_workspace": ".services",
+    "ensure_personal_workspace": ".services",
+    "create_invitation": ".services",
+    "accept_invitation": ".services",
+    "CHECK_MEMBERSHIP": ".functions",
+    "check_membership": ".functions",
+    "EVENT_WORKSPACE_PERSONAL_CREATED": ".events",
+    "WorkspacesGDPRProvider": ".gdpr",
+}
+
+__all__ = list(_EXPORTS)
+
+
+def __getattr__(name):
+    if name in _EXPORTS:
+        import importlib
+
+        value = getattr(importlib.import_module(_EXPORTS[name], __name__), name)
+        globals()[name] = value  # cache for subsequent lookups
+        return value
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__():
+    return sorted(set(globals()) | set(__all__))

stapel_workspaces/actions.py

@@ -0,0 +1,23 @@
+"""Action subscriptions of the workspaces module.
+
+Handlers must be idempotent: delivery is at-least-once (outbox retries,
+broker redelivery).
+"""
+import logging
+
+from stapel_core.comm import on_action
+
+logger = logging.getLogger(__name__)
+
+
+@on_action("user.deleted")
+def handle_user_deleted(event):
+    """Erase this module's PII when an account deletion is executed."""
+    from .gdpr import WorkspacesGDPRProvider
+
+    user_id = event.payload.get("user_id")
+    if not user_id:
+        logger.error("user.deleted event without user_id: %s", event.event_id)
+        return
+    WorkspacesGDPRProvider().delete(user_id)
+    logger.info("workspaces data erased for deleted user %s", user_id)

stapel_workspaces/admin.py

@@ -0,0 +1,27 @@
+from django.contrib import admin
+
+from .models import Workspace, WorkspaceInvitation, WorkspaceMember
+
+
+@admin.register(Workspace)
+class WorkspaceAdmin(admin.ModelAdmin):
+    list_display = ["name", "slug", "type", "owner", "storage_used_bytes", "created_at"]
+    list_filter = ["type", "created_at"]
+    search_fields = ["name", "slug", "owner__email"]
+    readonly_fields = ["id", "created_at", "updated_at"]
+
+
+@admin.register(WorkspaceMember)
+class WorkspaceMemberAdmin(admin.ModelAdmin):
+    list_display = ["workspace", "user", "role", "invited_at", "accepted_at"]
+    list_filter = ["role"]
+    search_fields = ["workspace__name", "user__email"]
+    readonly_fields = ["id", "invited_at"]
+
+
+@admin.register(WorkspaceInvitation)
+class WorkspaceInvitationAdmin(admin.ModelAdmin):
+    list_display = ["workspace", "email", "role", "expires_at", "accepted_at", "revoked_at"]
+    list_filter = ["role", "accepted_at", "revoked_at"]
+    search_fields = ["workspace__name", "email"]
+    readonly_fields = ["id", "token", "created_at"]

stapel_workspaces/apps.py

@@ -0,0 +1,22 @@
+from django.apps import AppConfig
+
+
+class WorkspacesConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "stapel_workspaces"
+    label = 'workspaces'
+    verbose_name = "Stapel Workspaces"
+
+    def ready(self):
+        from stapel_core.gdpr import gdpr_registry
+        from .gdpr import WorkspacesGDPRProvider
+        gdpr_registry.register(WorkspacesGDPRProvider())
+
+        # Action subscriptions (in-process in a monolith, bus consumer in
+        # microservices — same code, transport chosen by STAPEL_COMM).
+        from . import actions  # noqa: F401
+
+        # Function providers (workspaces.check_membership). register() is
+        # idempotent — ready() may run more than once.
+        from . import functions
+        functions.register()

stapel_workspaces/conftest.py

@@ -0,0 +1,90 @@
+import uuid
+
+import pytest
+
+
+def pytest_configure(config):
+    from django.conf import settings
+
+    if not settings.configured:
+        settings.configure(
+            SECRET_KEY="test-secret-key-not-for-production",
+            INSTALLED_APPS=[
+                "django.contrib.contenttypes",
+                "django.contrib.auth",
+                "django.contrib.sessions",
+                "django.contrib.messages",
+                "django.contrib.admin",
+                "stapel_core.django.users",
+                "rest_framework",
+                "stapel_workspaces",
+            ],
+            AUTH_USER_MODEL="users.User",
+            DATABASES={
+                "default": {
+                    "ENGINE": "django.db.backends.sqlite3",
+                    "NAME": ":memory:",
+                }
+            },
+            DEFAULT_AUTO_FIELD="django.db.models.BigAutoField",
+            USE_TZ=True,
+            APPEND_SLASH=False,
+            ROOT_URLCONF="stapel_workspaces.conftest_urls",
+            CACHES={
+                "default": {
+                    "BACKEND": "django.core.cache.backends.locmem.LocMemCache",
+                }
+            },
+            # In-memory bus — no Kafka/Redis broker needed
+            STAPEL_BUS_BACKEND="stapel_core.bus.backends.memory.MemoryBus",
+            # Synchronous in-process comm: no outbox table needed, emitted
+            # actions reach in-process subscribers immediately.
+            STAPEL_COMM={
+                "ACTION_TRANSPORT": "inprocess",
+                "FUNCTION_TRANSPORT": "inprocess",
+                "OUTBOX_ENABLED": False,
+                "VALIDATE_SCHEMAS": True,
+            },
+            SERVICE_NAME="workspaces",
+            FRONTEND_URL="https://app.example.com",
+            # Skip migrations — create tables directly from models
+            MIGRATION_MODULES={
+                "users": None,
+                "workspaces": None,
+            },
+        )
+
+
+@pytest.fixture
+def api_client():
+    from rest_framework.test import APIClient
+
+    return APIClient()
+
+
+@pytest.fixture
+def user(db):
+    from stapel_core.django.users.models import User
+
+    return User.objects.create_user(
+        username=f"u-{uuid.uuid4().hex[:8]}",
+        email=f"{uuid.uuid4().hex[:8]}@example.com",
+        password="testpass-1234",
+    )
+
+
+@pytest.fixture
+def other_user(db):
+    from stapel_core.django.users.models import User
+
+    return User.objects.create_user(
+        username=f"u-{uuid.uuid4().hex[:8]}",
+        email=f"{uuid.uuid4().hex[:8]}@example.com",
+        password="testpass-1234",
+    )
+
+
+@pytest.fixture
+def authed_client(api_client, user):
+    api_client.force_authenticate(user=user)
+    return api_client

stapel_workspaces/conftest_urls.py

@@ -0,0 +1,18 @@
+"""URL configuration used only during tests.
+
+Mounts the workspaces API at /workspaces/api/workspaces to match the test fixtures.
+Tests call paths without a trailing slash on the collection (/workspaces/api/workspaces)
+but with a slash before resource IDs (/workspaces/api/workspaces/{uuid}).
+Two separate includes cover both cases:
+  - path with '/' strips 'workspaces/api/workspaces/' → passes bare '{uuid}' to sub-patterns
+  - path without '/' strips 'workspaces/api/workspaces' → passes '' to sub-patterns (list)
+"""
+
+from django.urls import include, path
+
+urlpatterns = [
+    # Detail/invite routes: URL has slash before UUID, so this prefix strips correctly.
+    path("workspaces/api/workspaces/", include("stapel_workspaces.urls")),
+    # List/create route: URL has no trailing slash; this prefix matches and passes '' to sub-patterns.
+    path("workspaces/api/workspaces", include("stapel_workspaces.urls")),
+]

stapel_workspaces/dto.py

@@ -0,0 +1,141 @@
+"""Data Transfer Objects for workspaces API."""
+
+from dataclasses import dataclass, field
+from typing import List, Optional
+from uuid import UUID
+
+
+@dataclass
+class WorkspaceResponse:
+    """Workspace details.
+
+    Attributes:
+        id: Workspace UUID. Example: 0192f...
+        name: Display name. Example: Acme Engineering
+        slug: URL-safe identifier. Example: acme-eng
+        type: Workspace category. Example: work
+        owner_id: Owner user UUID. Example: 0192a...
+        settings: Workspace settings JSON.
+        storage_used_bytes: Bytes currently stored.
+        storage_limit_bytes: Plan-determined cap.
+        member_count: Number of members.
+        my_role: Role of the requesting user. Example: owner
+        created_at: ISO 8601 creation time. Example: 2026-05-20T10:00:00Z
+        updated_at: ISO 8601 last update time. Example: 2026-05-20T10:00:00Z
+    """
+
+    id: UUID
+    name: str
+    slug: str
+    type: str
+    owner_id: UUID
+    settings: dict
+    storage_used_bytes: int
+    storage_limit_bytes: int
+    member_count: int
+    my_role: Optional[str]
+    created_at: str
+    updated_at: str
+
+
+@dataclass
+class WorkspaceListResponse:
+    workspaces: List[WorkspaceResponse] = field(default_factory=list)
+
+
+@dataclass
+class WorkspaceCreateRequest:
+    """Create-workspace payload.
+
+    Attributes:
+        name: Display name. Example: Acme Engineering
+        slug: URL-safe identifier (auto-generated when omitted). Example: acme-eng
+        type: personal or work. Example: work
+    """
+
+    name: str
+    slug: Optional[str] = None
+    type: str = "work"
+
+
+@dataclass
+class WorkspaceUpdateRequest:
+    name: Optional[str] = None
+    slug: Optional[str] = None
+    settings: Optional[dict] = None
+
+
+@dataclass
+class MemberResponse:
+    """Workspace member.
+
+    Attributes:
+        id: Membership UUID. Example: 0192...
+        workspace_id: Workspace UUID.
+        user_id: User UUID.
+        email: User email (best-effort, from JWT claim cache).
+        role: owner / admin / member / viewer. Example: admin
+        invited_at: ISO 8601 invite timestamp.
+        accepted_at: ISO 8601 acceptance timestamp; null while pending.
+        last_accessed_at: ISO 8601 last access; null if never accessed.
+    """
+
+    id: UUID
+    workspace_id: UUID
+    user_id: UUID
+    email: Optional[str]
+    role: str
+    invited_at: str
+    accepted_at: Optional[str]
+    last_accessed_at: Optional[str]
+
+
+@dataclass
+class MemberListResponse:
+    members: List[MemberResponse] = field(default_factory=list)
+
+
+@dataclass
+class MemberInviteRequest:
+    """Invite payload.
+
+    Attributes:
+        emails: One or more emails to invite. Example: ["alice@example.com"]
+        role: Role to grant on acceptance. Example: member
+    """
+
+    emails: List[str]
+    role: str = "member"
+
+
+@dataclass
+class MemberInviteResponse:
+    invitations: List["InvitationResponse"] = field(default_factory=list)
+
+
+@dataclass
+class InvitationResponse:
+    id: UUID
+    workspace_id: UUID
+    email: str
+    role: str
+    expires_at: str
+    accepted_at: Optional[str]
+    revoked_at: Optional[str]
+    created_at: str
+
+
+@dataclass
+class InvitationAcceptRequest:
+    """Accept an invite.
+
+    Attributes:
+        token: Invite token from the email link.
+    """
+
+    token: str
+
+
+@dataclass
+class MemberUpdateRequest:
+    role: str

stapel_workspaces/errors.py

@@ -0,0 +1,36 @@
+"""Custom error keys for the workspaces service."""
+
+from stapel_core.django.api.errors import ErrorKeysView, register_service_errors
+
+ERR_404_WORKSPACE_NOT_FOUND = "error.404.workspace_not_found"
+ERR_404_MEMBER_NOT_FOUND = "error.404.member_not_found"
+ERR_404_INVITATION_NOT_FOUND = "error.404.invitation_not_found"
+ERR_403_FORBIDDEN_WORKSPACE = "error.403.forbidden_workspace"
+ERR_403_LAST_OWNER = "error.403.last_owner_cannot_be_removed"
+ERR_400_SLUG_TAKEN = "error.400.workspace_slug_taken"
+ERR_400_ALREADY_MEMBER = "error.400.already_workspace_member"
+ERR_400_INVITATION_EXPIRED = "error.400.invitation_expired"
+ERR_400_INVITATION_ALREADY_USED = "error.400.invitation_already_used"
+ERR_400_INVITATION_REVOKED = "error.400.invitation_revoked"
+ERR_400_INVALID_ROLE = "error.400.invalid_role"
+
+WORKSPACES_ERRORS = {
+    ERR_404_WORKSPACE_NOT_FOUND: "Workspace not found",
+    ERR_404_MEMBER_NOT_FOUND: "Member not found in this workspace",
+    ERR_404_INVITATION_NOT_FOUND: "Invitation not found",
+    ERR_403_FORBIDDEN_WORKSPACE: "You do not have access to this workspace",
+    ERR_403_LAST_OWNER: "The last owner cannot be removed; transfer ownership first",
+    ERR_400_SLUG_TAKEN: "Workspace slug is already taken",
+    ERR_400_ALREADY_MEMBER: "User is already a member of this workspace",
+    ERR_400_INVITATION_EXPIRED: "Invitation has expired",
+    ERR_400_INVITATION_ALREADY_USED: "Invitation has already been used",
+    ERR_400_INVITATION_REVOKED: "Invitation has been revoked",
+    ERR_400_INVALID_ROLE: "Invalid role",
+}
+
+register_service_errors(WORKSPACES_ERRORS)
+
+
+class WorkspacesErrorKeysView(ErrorKeysView):
+    def get_service_errors(self):
+        return WORKSPACES_ERRORS

stapel_workspaces/events.py

@@ -0,0 +1,34 @@
+"""Events published by stapel-workspaces.
+
+Publishing goes through ``stapel_core.comm.emit`` (transactional outbox;
+in-process in a monolith, bus in microservices) — see services.py. The
+comm action name is ``workspace.personal.created``; its payload contract
+lives in schemas/emits/workspace.personal.created.json.
+"""
+from dataclasses import dataclass
+
+EVENT_WORKSPACE_PERSONAL_CREATED = "workspace.personal.created"
+
+# On the bus transport the topic is the action name. The old Kafka topic
+# ``stapel.workspaces.personal-created`` is retired; alias kept for any
+# importer still referencing the old name.
+TOPIC_WORKSPACE_PERSONAL_CREATED = EVENT_WORKSPACE_PERSONAL_CREATED
+
+
+@dataclass
+class WorkspacePersonalCreatedPayload:
+    """Payload for the workspace.personal.created event.
+
+    Fields:
+        user_id: UUID of the workspace owner.
+        workspace_id: UUID of the created personal workspace.
+    """
+
+    user_id: str
+    workspace_id: str
+
+
+EVENT_REGISTRY = {
+    EVENT_WORKSPACE_PERSONAL_CREATED: WorkspacePersonalCreatedPayload,
+    TOPIC_WORKSPACE_PERSONAL_CREATED: WorkspacePersonalCreatedPayload,
+}

stapel_workspaces/functions.py

@@ -0,0 +1,67 @@
+"""comm Function providers of the workspaces module.
+
+Other modules check membership by name — no import of this app, no HTTP
+client code (the transport is deployment configuration, see STAPEL_COMM):
+
+    from stapel_core.comm import call
+
+    result = call(
+        "workspaces.check_membership",
+        {"workspace_id": str(workspace_id), "user_id": str(user_id)},
+    )
+    # -> {"is_member": bool, "role": str | None}
+
+The provider mirrors the internal HTTP endpoint
+(:class:`stapel_workspaces.views.InternalMembershipView`): only *accepted*
+memberships count.
+"""
+
+from stapel_core.comm import register_function
+
+CHECK_MEMBERSHIP = "workspaces.check_membership"
+
+# Kept in sync with schemas/functions/workspaces.check_membership.json
+# (the schemas/ autoloader registers the file too; passing it here makes
+# validation work even without the autoloader).
+CHECK_MEMBERSHIP_SCHEMA = {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "title": CHECK_MEMBERSHIP,
+    "type": "object",
+    "required": ["workspace_id", "user_id"],
+    "properties": {
+        "workspace_id": {"type": "string", "format": "uuid"},
+        "user_id": {"type": "string", "format": "uuid"},
+    },
+    "additionalProperties": False,
+}
+
+
+def check_membership(payload: dict) -> dict:
+    """Provider for ``workspaces.check_membership``.
+
+    Payload: ``{"workspace_id": str, "user_id": str}``
+    Returns: ``{"is_member": bool, "role": str | None}``
+    """
+    from .models import WorkspaceMember
+
+    member = (
+        WorkspaceMember.objects.filter(
+            workspace_id=payload["workspace_id"],
+            user_id=payload["user_id"],
+            accepted_at__isnull=False,
+        )
+        .only("role")
+        .first()
+    )
+    if member is None:
+        return {"is_member": False, "role": None}
+    return {"is_member": True, "role": member.role}
+
+
+def register() -> None:
+    """Register this module's Function providers.
+
+    Idempotent: re-registering the *same* handler object is a no-op, so
+    AppConfig.ready() may run more than once without raising.
+    """
+    register_function(CHECK_MEMBERSHIP, check_membership, schema=CHECK_MEMBERSHIP_SCHEMA)

stapel_workspaces/gdpr.py

@@ -0,0 +1,64 @@
+from stapel_core.gdpr import GDPRProvider
+
+
+class WorkspacesGDPRProvider(GDPRProvider):
+    section = 'workspaces'
+
+    def export(self, user_id: int) -> dict:
+        from .models import Workspace, WorkspaceInvitation, WorkspaceMember
+
+        memberships = list(WorkspaceMember.objects.filter(user_id=user_id).select_related('workspace').values(
+            'workspace__name', 'workspace__slug', 'workspace__type',
+            'role', 'invited_at', 'accepted_at', 'last_accessed_at',
+        ))
+
+        owned = list(Workspace.objects.filter(owner_id=user_id).values(
+            'name', 'slug', 'type', 'storage_used_bytes', 'created_at',
+        ))
+
+        sent_invitations = list(WorkspaceInvitation.objects.filter(invited_by_id=user_id).values(
+            'workspace__name', 'role', 'created_at', 'accepted_at',
+        ))
+
+        return {
+            'memberships':      _serialize_dates(memberships),
+            'owned_workspaces': _serialize_dates(owned),
+            'invitations_sent': _serialize_dates(sent_invitations),
+        }
+
+    def delete(self, user_id: int) -> None:
+        from .models import Workspace, WorkspaceInvitation, WorkspaceMember
+
+        # Remove memberships
+        WorkspaceMember.objects.filter(user_id=user_id).delete()
+
+        # Revoke pending invitations sent by this user
+        WorkspaceInvitation.objects.filter(
+            invited_by_id=user_id, accepted_at__isnull=True,
+        ).delete()
+
+        # Owned workspaces: soft-delete (mark deleted_at).
+        # Hard deletion of workspace content is out of scope here —
+        # the platform should handle workspace transfer/deletion separately.
+        from django.utils import timezone
+        Workspace.objects.filter(owner_id=user_id, deleted_at__isnull=True).update(
+            deleted_at=timezone.now(),
+        )
+
+    def anonymize(self, user_id: int) -> None:
+        from .models import WorkspaceInvitation
+
+        # Keep accepted invitation records but remove the invited_by link
+        WorkspaceInvitation.objects.filter(
+            invited_by_id=user_id, accepted_at__isnull=False,
+        ).update(invited_by=None)
+
+        # Membership records that need to stay (e.g. for workspace history)
+        # are already removed in delete(); nothing to anonymise here.
+
+
+def _serialize_dates(rows: list[dict]) -> list[dict]:
+    return [
+        {k: v.isoformat() if hasattr(v, 'isoformat') else v for k, v in row.items()}
+        for row in rows
+    ]

stapel_workspaces/management/commands/consume_auth_events.py

@@ -0,0 +1,43 @@
+"""Consume events published by stapel-auth."""
+import os
+
+from stapel_core.bus import BaseBusConsumerCommand, Event
+
+# stapel-auth emits the action through stapel_core.comm; on the bus transport
+# the topic is the action name. Override via env for legacy topic layouts.
+TOPIC_USER_REGISTERED = os.getenv("STAPEL_TOPIC_USER_REGISTERED", "user.registered")
+
+
+class Command(BaseBusConsumerCommand):
+    help = "Listen for auth events and react (e.g. bootstrap personal workspaces)"
+    topics = [TOPIC_USER_REGISTERED]
+    consumer_group = "workspaces-auth-events"
+
+    def handle_event(self, event: Event) -> None:
+        if event.event_type == "user.registered":
+            self._on_user_registered(event.payload)
+
+    def _on_user_registered(self, payload: dict) -> None:
+        user_id = payload.get("user_id")
+        if not user_id:
+            self.stderr.write(f"user.registered event missing user_id: {payload}")
+            return
+        try:
+            from stapel_core.django.users.models import User
+            user = User.objects.get(id=user_id)
+        except User.DoesNotExist:
+            self.stderr.write(f"user.registered: user {user_id} not found, skipping")
+            return
+        from stapel_workspaces.services import ensure_personal_workspace
+        from stapel_workspaces.events import EVENT_WORKSPACE_PERSONAL_CREATED
+        from stapel_core.bus import publish, Event as BusEvent
+        workspace = ensure_personal_workspace(user)
+        publish(EVENT_WORKSPACE_PERSONAL_CREATED, BusEvent(
+            event_type="workspace.personal.created",
+            service="workspaces",
+            payload={
+                "user_id": user_id,
+                "workspace_id": str(workspace.id),
+            },
+        ))
+        self.stdout.write(f"Bootstrapped personal workspace {workspace.id} for user {user_id}")