platform-context 0.5.0__py3-none-any.whl

platform_context/__init__.py

@@ -0,0 +1,84 @@
+"""
+platform-context: Shared platform foundation for all Django projects.
+
+Provides:
+- Request context management (tenant, user, request_id)
+- Multi-tenancy middleware (subdomain-based)
+- Postgres RLS helpers
+- Audit event logging (model-agnostic)
+- Outbox pattern for reliable events
+- Exception hierarchy
+- Django template context processors
+- Shared test helpers (platform_context.testing)
+- Multi-tenancy utilities (platform_context.tenant_utils) — ADR-056
+- Temporal Client singleton (platform_context.temporal_client) — ADR-077
+
+Usage::
+
+    from platform_context import get_context, set_tenant, set_user_id
+    from platform_context.middleware import SubdomainTenantMiddleware
+    from platform_context.audit import emit_audit_event
+
+Test helpers (install with platform-context[testing])::
+
+    # conftest.py
+    from platform_context.testing.fixtures import user, admin_user, auth_client  # noqa: F401
+
+    # tests
+    from platform_context.testing.assertions import assert_htmx_fragment, assert_login_required
+
+Multi-tenancy utilities (ADR-056, requires django-tenants in consuming service)::
+
+    from platform_context.tenant_utils.http_client import TenantAwareHttpClient
+    from platform_context.tenant_utils.middleware import TenantPropagationMiddleware
+    from platform_context.tenant_utils.celery import TenantAwareTask, send_cross_service_task
+    from platform_context.tenant_utils.provisioning import provision_tenant
+
+    # In conftest.py:
+    from platform_context.tenant_utils.testing import tenant_a, tenant_b  # noqa: F401
+"""
+
+from platform_context.context import (
+    RequestContext,
+    clear_context,
+    get_context,
+    set_request_id,
+    set_tenant,
+    set_user_id,
+)
+from platform_context.db import get_db_tenant, set_db_tenant
+from platform_context.htmx import (
+    HtmxErrorMiddleware,
+    HtmxResponseMixin,
+    is_htmx_request,
+)
+
+__version__ = "0.5.0"
+
+__all__ = [
+    # Context
+    "RequestContext",
+    "clear_context",
+    "get_context",
+    "set_request_id",
+    "set_tenant",
+    "set_user_id",
+    # DB
+    "get_db_tenant",
+    "set_db_tenant",
+    # HTMX (ADR-048)
+    "HtmxErrorMiddleware",
+    "HtmxResponseMixin",
+    "is_htmx_request",
+    # Testing helpers (platform-context[testing])
+    # Import via: from platform_context.testing.assertions import ...
+    # Import via: from platform_context.testing.fixtures import ...
+    # Multi-tenancy utilities (ADR-056, requires django-tenants)
+    # Import via: from platform_context.tenant_utils.http_client import TenantAwareHttpClient
+    # Import via: from platform_context.tenant_utils.middleware import TenantPropagationMiddleware
+    # Import via: from platform_context.tenant_utils.celery import TenantAwareTask
+    # Import via: from platform_context.tenant_utils.provisioning import provision_tenant
+    # Import via: from platform_context.tenant_utils.testing import tenant_a, tenant_b
+    # Temporal Client (ADR-077, requires platform-context[temporal])
+    # Import via: from platform_context.temporal_client import get_temporal_client
+]

platform_context/apps.py

@@ -0,0 +1,11 @@
+"""Django app configuration for platform_context."""
+
+from django.apps import AppConfig
+
+
+class PlatformContextConfig(AppConfig):
+    """Django app config for platform-context."""
+
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "platform_context"
+    verbose_name = "Platform Context"

platform_context/audit.py

@@ -0,0 +1,76 @@
+"""
+Audit event logging for compliance.
+
+Provides structured audit trail for all risk-relevant mutations.
+Model-agnostic: configure PLATFORM_AUDIT_MODEL in Django settings.
+"""
+
+import logging
+from typing import Any
+from uuid import UUID
+
+from platform_context.context import get_context
+
+_logger = logging.getLogger(__name__)
+
+
+def emit_audit_event(
+    *,
+    tenant_id: UUID,
+    category: str,
+    action: str,
+    entity_type: str,
+    entity_id: UUID,
+    payload: dict[str, Any],
+) -> None:
+    """
+    Emit an audit event for a mutation.
+
+    The actor_user_id and request_id are automatically populated
+    from the current request context.
+
+    Requires PLATFORM_AUDIT_MODEL to be set in Django settings
+    (e.g., "bfagent_core.AuditEvent").
+
+    Args:
+        tenant_id: The tenant this event belongs to
+        category: Event category (e.g., "risk.assessment")
+        action: Action performed (e.g., "created", "approved")
+        entity_type: Full entity type (e.g., "risk.Assessment")
+        entity_id: UUID of the affected entity
+        payload: Additional data to store
+    """
+    from django.conf import settings
+
+    model_path = getattr(settings, "PLATFORM_AUDIT_MODEL", None)
+    if not model_path:
+        _logger.warning(
+            "PLATFORM_AUDIT_MODEL not configured, audit event dropped: "
+            "%s.%s on %s",
+            category,
+            action,
+            entity_type,
+        )
+        return
+
+    from django.apps import apps
+
+    try:
+        app_label, model_name = model_path.rsplit(".", 1)
+        AuditModel = apps.get_model(app_label, model_name)
+    except (LookupError, ValueError) as exc:
+        _logger.error("Cannot resolve PLATFORM_AUDIT_MODEL=%s: %s", model_path, exc)
+        return
+
+    ctx = get_context()
+
+    AuditModel.objects.create(
+        tenant_id=tenant_id,
+        actor_user_id=ctx.user_id,
+        category=category,
+        action=action,
+        entity_type=entity_type,
+        entity_id=entity_id,
+        payload=payload,
+        request_id=ctx.request_id,
+    )

platform_context/context.py

@@ -0,0 +1,79 @@
+"""
+Request context management using contextvars.
+
+Thread-safe context propagation for:
+- tenant_id / tenant_slug
+- user_id
+- request_id (correlation ID)
+"""
+
+import contextvars
+from dataclasses import dataclass
+from uuid import UUID
+
+_request_id: contextvars.ContextVar[str | None] = contextvars.ContextVar(
+    "request_id", default=None
+)
+_current_tenant_id: contextvars.ContextVar[UUID | None] = contextvars.ContextVar(
+    "tenant_id", default=None
+)
+_current_tenant_slug: contextvars.ContextVar[str | None] = contextvars.ContextVar(
+    "tenant_slug", default=None
+)
+_current_user_id: contextvars.ContextVar[UUID | None] = contextvars.ContextVar(
+    "user_id", default=None
+)
+
+
+@dataclass(frozen=True)
+class RequestContext:
+    """Immutable snapshot of the current request context."""
+
+    request_id: str | None
+    tenant_id: UUID | None
+    tenant_slug: str | None
+    user_id: UUID | None
+
+    @property
+    def is_authenticated(self) -> bool:
+        """Check if a user is set in context."""
+        return self.user_id is not None
+
+    @property
+    def has_tenant(self) -> bool:
+        """Check if a tenant is set in context."""
+        return self.tenant_id is not None
+
+
+def set_request_id(value: str | None) -> None:
+    """Set the request/correlation ID for the current context."""
+    _request_id.set(value)
+
+
+def set_tenant(tenant_id: UUID | None, tenant_slug: str | None) -> None:
+    """Set the current tenant for the context."""
+    _current_tenant_id.set(tenant_id)
+    _current_tenant_slug.set(tenant_slug)
+
+
+def set_user_id(value: UUID | None) -> None:
+    """Set the current user ID for the context."""
+    _current_user_id.set(value)
+
+
+def get_context() -> RequestContext:
+    """Get the current request context snapshot."""
+    return RequestContext(
+        request_id=_request_id.get(),
+        tenant_id=_current_tenant_id.get(),
+        tenant_slug=_current_tenant_slug.get(),
+        user_id=_current_user_id.get(),
+    )
+
+
+def clear_context() -> None:
+    """Clear all context variables. Useful for testing."""
+    _request_id.set(None)
+    _current_tenant_id.set(None)
+    _current_tenant_slug.set(None)
+    _current_user_id.set(None)

platform_context/context_processors.py

@@ -0,0 +1,76 @@
+"""Django template context processors."""
+
+from django.http import HttpRequest
+
+from platform_context.context import get_context
+
+
+def tenant_context(request: HttpRequest) -> dict:
+    """
+    Add tenant information to template context.
+
+    Usage in settings.py:
+        TEMPLATES = [{
+            ...
+            "OPTIONS": {
+                "context_processors": [
+                    ...
+                    "platform_context.context_processors.tenant_context",
+                ],
+            },
+        }]
+
+    Available in templates:
+        {{ tenant_id }}
+        {{ tenant_slug }}
+        {{ request_id }}
+    """
+    ctx = get_context()
+    return {
+        "tenant_id": ctx.tenant_id,
+        "tenant_slug": ctx.tenant_slug,
+        "request_id": ctx.request_id,
+    }
+
+
+def platform_context(request: HttpRequest) -> dict:
+    """
+    Add platform context to templates (tenant, permissions, membership).
+
+    Usage in settings.py:
+        'platform_context.context_processors.platform_context',
+
+    Available in templates:
+        {{ tenant }}           - Tenant object (if in tenant context)
+        {{ tenant_id }}        - UUID
+        {{ tenant_slug }}      - String
+        {{ membership }}       - TenantMembership (if authenticated)
+        {{ permissions }}      - FrozenSet of permission codes
+        {{ user_role }}        - Role string (owner, admin, member, viewer)
+        {{ is_tenant_admin }}  - Bool: owner or admin
+        {{ request_id }}       - Correlation ID
+
+    Permission check in templates:
+        {% if 'stories.create' in permissions %}
+            <a href="...">Create Story</a>
+        {% endif %}
+    """
+    ctx = get_context()
+
+    result = {
+        "tenant_id": ctx.tenant_id,
+        "tenant_slug": ctx.tenant_slug,
+        "request_id": ctx.request_id,
+        "tenant": getattr(request, "tenant", None),
+        "membership": getattr(request, "membership", None),
+        "permissions": getattr(request, "permissions", frozenset()),
+        "user_role": None,
+        "is_tenant_admin": False,
+    }
+
+    membership = result["membership"]
+    if membership:
+        result["user_role"] = membership.role
+        result["is_tenant_admin"] = membership.role in ("owner", "admin")
+
+    return result

platform_context/db.py

@@ -0,0 +1,51 @@
+"""
+Database utilities for multi-tenancy.
+
+Provides Postgres RLS (Row Level Security) session variable management.
+"""
+
+from uuid import UUID
+
+
+def set_db_tenant(tenant_id: UUID | None) -> None:
+    """
+    Set Postgres session variable for RLS policies.
+
+    This sets `app.current_tenant` which RLS policies use:
+
+        CREATE POLICY tenant_isolation ON my_table
+        USING (tenant_id = current_setting('app.current_tenant')::uuid);
+
+    Args:
+        tenant_id: The tenant UUID, or None to clear access
+
+    Note:
+        - Call this in middleware after resolving tenant
+        - Uses SET LOCAL so it's transaction-scoped
+        - Empty string = no tenant access (safe default when RLS enabled)
+    """
+    from django.db import connection
+
+    value = "" if tenant_id is None else str(tenant_id)
+    with connection.cursor() as cursor:
+        cursor.execute("SELECT set_config('app.current_tenant', %s, true)", [value])
+
+
+def get_db_tenant() -> UUID | None:
+    """
+    Get the current tenant from Postgres session variable.
+
+    Returns:
+        The tenant UUID if set, None otherwise
+    """
+    from django.db import connection
+
+    with connection.cursor() as cursor:
+        cursor.execute("SELECT current_setting('app.current_tenant', true)")
+        result = cursor.fetchone()
+        if result and result[0]:
+            try:
+                return UUID(result[0])
+            except ValueError:
+                return None
+        return None

platform_context/exceptions.py

@@ -0,0 +1,159 @@
+"""
+Exception hierarchy for the platform.
+
+All platform exceptions inherit from PlatformError.
+"""
+
+
+class PlatformError(Exception):
+    """Base class for all platform errors."""
+    pass
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# TENANT ERRORS
+# ═══════════════════════════════════════════════════════════════════════════════
+
+class TenantError(PlatformError):
+    """Base for tenant-related errors."""
+    pass
+
+
+class TenantNotFoundError(TenantError):
+    """Tenant does not exist."""
+
+    def __init__(self, tenant_id):
+        super().__init__(f"Tenant not found: {tenant_id}")
+        self.tenant_id = tenant_id
+
+
+class TenantSlugExistsError(TenantError):
+    """Tenant slug already exists."""
+
+    def __init__(self, slug):
+        super().__init__(f"Tenant slug already exists: {slug}")
+        self.slug = slug
+
+
+class TenantSuspendedError(TenantError):
+    """Tenant is suspended."""
+
+    def __init__(self, tenant_id):
+        super().__init__(f"Tenant is suspended: {tenant_id}")
+        self.tenant_id = tenant_id
+
+
+class TenantDeletedError(TenantError):
+    """Tenant is deleted."""
+
+    def __init__(self, tenant_id):
+        super().__init__(f"Tenant is deleted: {tenant_id}")
+        self.tenant_id = tenant_id
+
+
+class TenantInactiveError(TenantError):
+    """Tenant is not active (suspended or deleted)."""
+
+    def __init__(self, tenant_id, status):
+        super().__init__(f"Tenant {tenant_id} is {status}")
+        self.tenant_id = tenant_id
+        self.status = status
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# MEMBERSHIP ERRORS
+# ═══════════════════════════════════════════════════════════════════════════════
+
+class MembershipError(PlatformError):
+    """Base for membership-related errors."""
+    pass
+
+
+class MembershipNotFoundError(MembershipError):
+    """Membership does not exist."""
+
+    def __init__(self, membership_id=None, tenant_id=None, user_id=None):
+        if membership_id:
+            msg = f"Membership not found: {membership_id}"
+        else:
+            msg = f"No membership for user {user_id} in tenant {tenant_id}"
+        super().__init__(msg)
+        self.membership_id = membership_id
+        self.tenant_id = tenant_id
+        self.user_id = user_id
+
+
+class MembershipExistsError(MembershipError):
+    """User is already a member of the tenant."""
+
+    def __init__(self, tenant_id, user_id):
+        super().__init__(f"User {user_id} is already member of tenant {tenant_id}")
+        self.tenant_id = tenant_id
+        self.user_id = user_id
+
+
+class InvitationExpiredError(MembershipError):
+    """Invitation has expired."""
+
+    def __init__(self, membership_id):
+        super().__init__(f"Invitation has expired: {membership_id}")
+        self.membership_id = membership_id
+
+
+class InvitationNotPendingError(MembershipError):
+    """Invitation is not in pending state."""
+
+    def __init__(self, membership_id, status):
+        super().__init__(f"Invitation {membership_id} is {status}, not pending")
+        self.membership_id = membership_id
+        self.status = status
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# PERMISSION ERRORS
+# ═══════════════════════════════════════════════════════════════════════════════
+
+class PermissionError(PlatformError):
+    """Base for permission-related errors."""
+    pass
+
+
+class PermissionDeniedError(PermissionError):
+    """User does not have required permission."""
+
+    def __init__(self, permission: str, message: str = None):
+        super().__init__(message or f"Permission denied: {permission}")
+        self.permission = permission
+
+
+class PermissionNotFoundError(PermissionError):
+    """Permission code does not exist."""
+
+    def __init__(self, permission_code):
+        super().__init__(f"Permission not found: {permission_code}")
+        self.permission_code = permission_code
+
+
+class RoleNotFoundError(PermissionError):
+    """Role does not exist."""
+
+    def __init__(self, role):
+        super().__init__(f"Role not found: {role}")
+        self.role = role
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# USER ERRORS
+# ═══════════════════════════════════════════════════════════════════════════════
+
+class UserError(PlatformError):
+    """Base for user-related errors."""
+    pass
+
+
+class UserNotFoundError(UserError):
+    """User does not exist."""
+
+    def __init__(self, user_id):
+        super().__init__(f"User not found: {user_id}")
+        self.user_id = user_id

platform_context/htmx.py

@@ -0,0 +1,107 @@
+"""HTMX utilities for Django views (ADR-048).
+
+Provides:
+- is_htmx_request(): Portable HTMX detection (no django_htmx dependency)
+- HtmxResponseMixin: CBV mixin for partial/full template switching
+- HtmxErrorMiddleware: Convert 4xx/5xx into HTMX-safe toast notifications
+
+All code uses raw header detection for portability across apps.
+Apps with django_htmx installed MAY use request.htmx in app-specific code,
+but shared middleware and mixins MUST NOT depend on it.
+"""
+
+import json
+from typing import Any
+
+from django.core.exceptions import ImproperlyConfigured
+from django.http import HttpRequest, HttpResponse
+
+
+def is_htmx_request(request: HttpRequest) -> bool:
+    """Portable HTMX detection. Works with or without django_htmx."""
+    return request.headers.get("HX-Request") == "true"
+
+
+class HtmxResponseMixin:
+    """Mixin for CBVs that return partials for HTMX requests.
+
+    Set ``partial_template_name`` to the HTMX partial template.
+    The full template is resolved via standard ``get_template_names()``.
+
+    Example::
+
+        class TripListView(HtmxResponseMixin, LoginRequiredMixin, ListView):
+            model = Trip
+            template_name = "trips/trip_list.html"
+            partial_template_name = "trips/partials/_trip_list.html"
+    """
+
+    partial_template_name: str = ""
+
+    def get_template_names(self) -> list[str]:
+        """Return partial template for HTMX requests, full otherwise."""
+        if is_htmx_request(self.request):
+            if not self.partial_template_name:
+                raise ImproperlyConfigured(
+                    f"{self.__class__.__name__} requires partial_template_name"
+                )
+            return [self.partial_template_name]
+        return super().get_template_names()
+
+
+ERROR_MESSAGES: dict[int, str] = {
+    400: "Bad request.",
+    403: "Permission denied.",
+    404: "Resource not found.",
+    405: "Method not allowed.",
+    409: "Conflict.",
+    429: "Too many requests. Please wait.",
+    500: "Internal server error. Please try again.",
+    502: "Service temporarily unavailable.",
+    503: "Service temporarily unavailable.",
+}
+
+
+class HtmxErrorMiddleware:
+    """Convert 4xx/5xx into HTMX-safe responses with toast notifications.
+
+    Works without django_htmx -- uses raw header detection.
+    Skips 422 responses (form validation errors, see HP-006).
+
+    Install AFTER TenantMiddleware and auth middleware::
+
+        MIDDLEWARE = [
+            "django.middleware.security.SecurityMiddleware",
+            "django.contrib.sessions.middleware.SessionMiddleware",
+            # ... auth middleware ...
+            "platform_context.middleware.SubdomainTenantMiddleware",
+            "platform_context.htmx.HtmxErrorMiddleware",
+            # ...
+        ]
+    """
+
+    def __init__(self, get_response: Any) -> None:
+        self.get_response = get_response
+
+    def __call__(self, request: HttpRequest) -> HttpResponse:
+        """Process request and intercept errors for HTMX requests."""
+        response = self.get_response(request)
+
+        if not is_htmx_request(request):
+            return response
+
+        if response.status_code == 422:
+            return response
+
+        if response.status_code >= 400:
+            response["HX-Reswap"] = "none"
+            response["HX-Trigger"] = json.dumps({
+                "showToast": {
+                    "level": "error" if response.status_code >= 500 else "warning",
+                    "message": ERROR_MESSAGES.get(
+                        response.status_code, "An error occurred."
+                    ),
+                }
+            })
+
+        return response