platform-context 0.5.0__tar.gz

platform_context-0.5.0/.gitignore

@@ -0,0 +1,50 @@
+# Python
+__pycache__/
+*.py[cod]
+*\.class
+.venv/
+venv/
+*.egg-info/
+dist/
+build/
+# Django
+*.log
+db.sqlite3
+media/
+staticfiles/
+# Environment
+.env
+.env.local
+.env.prod
+
+# Secrets (ADR-045) — NEVER commit plaintext
+secrets.env
+!secrets.enc.env
+# IDE
+.idea/
+.vscode/
+*.swp
+# OS
+.DS_Store
+Thumbs.db
+# Large files
+*.sqlite3
+*.log
+output_batch/
+app_backup/
+docs_legacy/
+# Sphinx build output
+docs/_build/
+*:Zone.Identifier
+# Local Windsurf/MCP config — machine-specific, never commit
+.windsurf/mcp_config.json
+# Local infra plaintext secrets — NEVER commit
+infra/*.env
+infra/*.key
+# Validate-ports CI draft (not yet integrated)
+.github/workflows/validate-ports.yml
+# Markdownlint local config override
+.markdownlint.json
+# Concept review drafts (local working copies, not for VCS)
+docs/concepts/REVIEW-*
+env_loader.py

platform_context-0.5.0/.trigger-ci

@@ -0,0 +1 @@
+triggered at 2026-02-20T18:25

platform_context-0.5.0/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog — platform-context
+
+All notable changes to this package are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+---
+
+## [0.5.0] — current
+
+### Added
+- `temporal_client.py` — Temporal workflow engine client integration (ADR-079)
+- `tenant_utils/` — Shared tenant utility helpers
+- `testing/` — Shared test fixtures and helpers for downstream packages (ADR-084)
+- `outbox.py` — Transactional outbox pattern for reliable event publishing
+
+### Changed
+- `middleware.py` — RequestContextMiddleware now sets tenant context per request
+- `htmx.py` — HtmxErrorMiddleware hardened; handles non-HTMX requests gracefully
+- `exceptions.py` — Platform-wide exception hierarchy extended
+
+---
+
+## [0.4.x]
+
+### Added
+- `audit.py` — Shared audit log base model and mixin
+- `db.py` — Database utilities (connection helpers, vendor detection)
+- `context_processors.py` — Django context processors for platform-wide template vars
+- `context.py` — Request context holder (thread-local + async-safe)
+
+### Changed
+- `apps.py` — AppConfig registered as `platform_context`
+
+---
+
+## [0.3.x]
+
+### Added
+- Initial package structure with `src/` layout
+- Django 5.x compatibility (requires `Django>=5.0,<6.0`)
+- Optional extras: `tenants` (django-tenants), `temporal` (temporalio)
+
+---
+
+## [0.2.x]
+
+### Added
+- First stable release as shared foundation package
+- Extracted from bfagent monolith (ADR-028)
+
+---
+
+## [0.1.0]
+
+### Added
+- Initial extraction from bfagent-core (ADR-028: Platform Context Consolidation)

platform_context-0.5.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: platform-context
+Version: 0.5.0
+Summary: Shared platform foundation for all Django projects (Context, Tenancy, Audit, Outbox)
+Author-email: Achim Dehnert <achim@dehnert.com>
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Django :: 5.0
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Requires-Dist: django<6.0,>=5.0
+Provides-Extra: dev
+Requires-Dist: factory-boy>=3.3; extra == 'dev'
+Requires-Dist: pytest-django>=4.8; extra == 'dev'
+Requires-Dist: pytest-mock>=3.12; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: temporal
+Requires-Dist: temporalio>=1.7.0; extra == 'temporal'
+Provides-Extra: tenants
+Requires-Dist: django-tenants>=3.6; extra == 'tenants'
+Requires-Dist: httpx>=0.27; extra == 'tenants'
+Requires-Dist: tenant-schemas-celery>=2.0; extra == 'tenants'
+Provides-Extra: testing
+Requires-Dist: factory-boy>=3.3; extra == 'testing'
+Requires-Dist: pytest-django>=4.8; extra == 'testing'
+Requires-Dist: pytest-mock>=3.12; extra == 'testing'
+Requires-Dist: pytest>=8.0; extra == 'testing'
+Description-Content-Type: text/markdown
+
+# platform-context
+
+Shared platform foundation for all Django projects in the iil.pet ecosystem.
+
+## What it provides
+
+- **Request Context** — Thread-safe context propagation (tenant_id, user_id, request_id)
+- **Multi-Tenancy Middleware** — Subdomain-based tenant resolution + Postgres RLS
+- **Audit Event Logging** — Structured audit trail (model-agnostic)
+- **Outbox Pattern** — Reliable event publishing within transactions
+- **Exception Hierarchy** — Structured platform exceptions
+- **Template Context Processors** — Tenant/permission info in Django templates
+
+## Installation
+
+```bash
+pip install -e packages/platform-context
+```
+
+Add to `INSTALLED_APPS`:
+
+```python
+INSTALLED_APPS = [
+    ...
+    "platform_context",
+]
+```
+
+## Usage
+
+```python
+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
+from platform_context.exceptions import TenantNotFoundError
+```
+
+## Configuration
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `TENANT_BASE_DOMAIN` | `"localhost"` | Base domain for subdomain resolution |
+| `TENANT_MODEL` | `"tenancy.Organization"` | Dotted path to tenant model |
+| `TENANT_SLUG_FIELD` | `"slug"` | Field name for slug lookup |
+| `TENANT_ID_FIELD` | `"tenant_id"` | Field name for tenant_id |
+| `TENANT_ALLOW_LOCALHOST` | `False` | Allow admin access without tenant (dev) |
+| `PLATFORM_AUDIT_MODEL` | `None` | Dotted path to AuditEvent model |
+| `PLATFORM_OUTBOX_MODEL` | `None` | Dotted path to OutboxMessage model |
+
+## Relation to bfagent-core
+
+`platform-context` is the framework-agnostic foundation extracted from
+`bfagent-core` (see ADR-028). `bfagent-core` now depends on
+`platform-context` and re-exports its public API for backward compatibility.
+
+New projects should depend on `platform-context` directly.

platform_context-0.5.0/README.md

@@ -0,0 +1,56 @@
+# platform-context
+
+Shared platform foundation for all Django projects in the iil.pet ecosystem.
+
+## What it provides
+
+- **Request Context** — Thread-safe context propagation (tenant_id, user_id, request_id)
+- **Multi-Tenancy Middleware** — Subdomain-based tenant resolution + Postgres RLS
+- **Audit Event Logging** — Structured audit trail (model-agnostic)
+- **Outbox Pattern** — Reliable event publishing within transactions
+- **Exception Hierarchy** — Structured platform exceptions
+- **Template Context Processors** — Tenant/permission info in Django templates
+
+## Installation
+
+```bash
+pip install -e packages/platform-context
+```
+
+Add to `INSTALLED_APPS`:
+
+```python
+INSTALLED_APPS = [
+    ...
+    "platform_context",
+]
+```
+
+## Usage
+
+```python
+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
+from platform_context.exceptions import TenantNotFoundError
+```
+
+## Configuration
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `TENANT_BASE_DOMAIN` | `"localhost"` | Base domain for subdomain resolution |
+| `TENANT_MODEL` | `"tenancy.Organization"` | Dotted path to tenant model |
+| `TENANT_SLUG_FIELD` | `"slug"` | Field name for slug lookup |
+| `TENANT_ID_FIELD` | `"tenant_id"` | Field name for tenant_id |
+| `TENANT_ALLOW_LOCALHOST` | `False` | Allow admin access without tenant (dev) |
+| `PLATFORM_AUDIT_MODEL` | `None` | Dotted path to AuditEvent model |
+| `PLATFORM_OUTBOX_MODEL` | `None` | Dotted path to OutboxMessage model |
+
+## Relation to bfagent-core
+
+`platform-context` is the framework-agnostic foundation extracted from
+`bfagent-core` (see ADR-028). `bfagent-core` now depends on
+`platform-context` and re-exports its public API for backward compatibility.
+
+New projects should depend on `platform-context` directly.

platform_context-0.5.0/pyproject.toml

@@ -0,0 +1,61 @@
+[project]
+name = "platform-context"
+version = "0.5.0"
+description = "Shared platform foundation for all Django projects (Context, Tenancy, Audit, Outbox)"
+readme = "README.md"
+requires-python = ">=3.11"
+license = {text = "MIT"}
+authors = [
+    {name = "Achim Dehnert", email = "achim@dehnert.com"}
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: Django :: 5.0",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+dependencies = [
+    "Django>=5.0,<6.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-django>=4.8",
+    "pytest-mock>=3.12",
+    "factory-boy>=3.3",
+]
+testing = [
+    "pytest>=8.0",
+    "pytest-django>=4.8",
+    "pytest-mock>=3.12",
+    "factory-boy>=3.3",
+]
+tenants = [
+    "django-tenants>=3.6",
+    "tenant-schemas-celery>=2.0",
+    "httpx>=0.27",
+]
+temporal = [
+    "temporalio>=1.7.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/platform_context"]
+
+[tool.pytest.ini_options]
+DJANGO_SETTINGS_MODULE = "tests.settings"
+python_files = ["test_*.py"]
+pythonpath = ["."]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"

platform_context-0.5.0/src/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-0.5.0/src/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-0.5.0/src/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-0.5.0/src/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-0.5.0/src/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-0.5.0/src/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