austial-tenancy 0.2.0__tar.gz

austial_tenancy-0.2.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+.venv/
+.env
+*.db
+.pytest_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+.DS_Store

austial_tenancy-0.2.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.5
+Name: austial-tenancy
+Version: 0.2.0
+Summary: Multi-tenant primitives -- request-scoped TenantContext, TenantGuard, Tenanted entity mixin, tenant-scope enforcement (mirrors @nestjs/microservices' scope patterns, adapted for HTTP).
+Requires-Python: >=3.11
+Requires-Dist: austial-auth
+Requires-Dist: austial-common
+Requires-Dist: austial-core
+Requires-Dist: austial-orm

austial_tenancy-0.2.0/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "austial-tenancy"
+dynamic = ["version"]
+description = "Multi-tenant primitives -- request-scoped TenantContext, TenantGuard, Tenanted entity mixin, tenant-scope enforcement (mirrors @nestjs/microservices' scope patterns, adapted for HTTP)."
+requires-python = ">=3.11"
+dependencies = [
+    "austial-common",
+    "austial-core",
+    "austial-auth",
+    "austial-orm",
+]
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/austial"]
+
+[tool.uv.sources]
+austial-common = { workspace = true }
+austial-core = { workspace = true }
+austial-auth = { workspace = true }
+austial-orm = { workspace = true }
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.version.raw-options]
+root = "../.."

austial_tenancy-0.2.0/src/austial/tenancy/__init__.py

@@ -0,0 +1,33 @@
+"""``austial.tenancy`` -- multi-tenant primitives.
+
+Provides ``TenantContext`` (request-scoped, backed by ``contextvars`` so it works with
+async and thread executors), ``TenantGuard`` (populates the context from the
+authenticated JWT's ``tenant`` claim and fails-closed on absence), the ``@Tenanted``
+entity mixin (adds a ``tenant_id`` column), and ``@RequireTenant`` (marker decorator
+that requires ``TenantGuard`` to have populated the context before the handler runs).
+
+The framework enforces the tenant boundary at the request perimeter; product code
+still writes ``.where(tenant_id=current)`` in queries or uses a scoped repository, so
+the tenant filter is explicit at the persistence boundary (visible in every query
+plan review) rather than magically injected.
+"""
+
+from austial.tenancy.decorators import REQUIRE_TENANT_METADATA, RequireTenant, is_tenant_required
+from austial.tenancy.errors import MissingTenantError, TenantMismatchError
+from austial.tenancy.tenancy_module import TenancyModule
+from austial.tenancy.tenant_context import TenantContext, TenantContextValue
+from austial.tenancy.tenant_guard import TenantGuard
+from austial.tenancy.tenanted import Tenanted
+
+__all__ = [
+    "MissingTenantError",
+    "REQUIRE_TENANT_METADATA",
+    "RequireTenant",
+    "TenancyModule",
+    "Tenanted",
+    "TenantContext",
+    "TenantContextValue",
+    "TenantGuard",
+    "TenantMismatchError",
+    "is_tenant_required",
+]

austial_tenancy-0.2.0/src/austial/tenancy/decorators.py

@@ -0,0 +1,29 @@
+"""``@RequireTenant`` -- marker decorator that ``TenantGuard`` checks.
+
+Apply at controller or handler level to require a populated ``TenantContext``.
+Requests without a tenant claim (or with a claim that fails product-level
+validation) are rejected with 403 before the handler runs.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from austial.core.metadata import get_metadata, set_metadata
+
+REQUIRE_TENANT_METADATA = "austial:tenancy:require"
+
+
+def RequireTenant() -> Callable:  # noqa: N802 - decorator naming
+    """Mark a controller or handler as requiring a tenant context."""
+
+    def decorator(target):
+        set_metadata(REQUIRE_TENANT_METADATA, True)(target)
+        return target
+
+    return decorator
+
+
+def is_tenant_required(target: Any) -> bool:
+    return bool(get_metadata(REQUIRE_TENANT_METADATA, target, False))

austial_tenancy-0.2.0/src/austial/tenancy/errors.py

@@ -0,0 +1,19 @@
+"""Tenancy-specific exceptions."""
+
+from __future__ import annotations
+
+from austial.common.exceptions import ForbiddenException
+
+
+class MissingTenantError(ForbiddenException):
+    """Raised when a request that requires a tenant lacks one."""
+
+    def __init__(self, message: str = "Tenant context is required"):
+        super().__init__(message)
+
+
+class TenantMismatchError(ForbiddenException):
+    """Raised when an operation targets a tenant other than the caller's."""
+
+    def __init__(self, expected: str, actual: str):
+        super().__init__(f"Tenant mismatch: expected {expected!r}, got {actual!r}")

austial_tenancy-0.2.0/src/austial/tenancy/tenancy_module.py

@@ -0,0 +1,19 @@
+"""``TenancyModule.for_root(...)`` -- provides ``TenantContext`` and ``TenantGuard``."""
+
+from __future__ import annotations
+
+from austial.common.decorators.modules import Module
+from austial.core.dynamic_module import DynamicModule
+from austial.tenancy.tenant_context import TenantContext
+from austial.tenancy.tenant_guard import TenantGuard
+
+
+@Module()
+class TenancyModule:
+    @staticmethod
+    def for_root(*, is_global: bool = True) -> DynamicModule:
+        return DynamicModule(
+            module=TenancyModule,
+            providers=[TenantContext, TenantGuard],
+            exports=[TenantContext, TenantGuard],
+        )

austial_tenancy-0.2.0/src/austial/tenancy/tenant_context.py

@@ -0,0 +1,70 @@
+"""``TenantContext`` -- request-scoped tenant id.
+
+Backed by ``contextvars.ContextVar`` so the value is isolated per request even
+across ``await`` points and threadpool executors. Set by ``TenantGuard`` at the
+perimeter; read by services, repositories and the ``@RequireTenant`` decorator.
+
+Two access styles are supported:
+
+- Injectable: ``TenantContext`` is a provider; inject and call ``current_id()``.
+- Direct: ``TenantContext.get()`` is a classmethod for places DI is inconvenient
+  (a mixin, a pure function, a background job that has been handed a snapshot).
+"""
+
+from __future__ import annotations
+
+import contextvars
+from dataclasses import dataclass
+from typing import Any
+
+from austial.common.decorators.injectable import Injectable
+
+_current_tenant: contextvars.ContextVar[TenantContextValue | None] = contextvars.ContextVar(
+    "austial.tenancy.tenant", default=None
+)
+
+
+@dataclass(frozen=True, slots=True)
+class TenantContextValue:
+    """Snapshot of the current tenant. ``metadata`` carries whatever the
+    ``TenantGuard`` chose to expose (e.g. tenant name, plan) for downstream code."""
+
+    tenant_id: str
+    metadata: dict[str, Any] | None = None
+
+
+@Injectable()
+class TenantContext:
+    """Injectable facade over the contextvar."""
+
+    @classmethod
+    def get(cls) -> TenantContextValue | None:
+        """Return the current value, or ``None`` if unset."""
+        return _current_tenant.get()
+
+    @classmethod
+    def require(cls) -> TenantContextValue:
+        """Return the current value, or raise ``MissingTenantError`` if unset."""
+        from austial.tenancy.errors import MissingTenantError
+
+        value = _current_tenant.get()
+        if value is None:
+            raise MissingTenantError()
+        return value
+
+    @classmethod
+    def set(cls, value: TenantContextValue | None) -> contextvars.Token:
+        """Set the current value; return a token the caller can use to reset."""
+        return _current_tenant.set(value)
+
+    @classmethod
+    def reset(cls, token: contextvars.Token) -> None:
+        _current_tenant.reset(token)
+
+    def current(self) -> TenantContextValue | None:
+        """Instance form for injected use."""
+        return _current_tenant.get()
+
+    def current_id(self) -> str:
+        """Instance form; raises ``MissingTenantError`` if unset."""
+        return self.__class__.require().tenant_id

austial_tenancy-0.2.0/src/austial/tenancy/tenant_guard.py

@@ -0,0 +1,74 @@
+"""``TenantGuard`` -- extracts tenant from the authenticated principal and
+populates ``TenantContext``.
+
+Runs after ``AuthGuard`` (which sets ``request.state.user``). Reads the
+``tenant`` claim from the principal, populates the context, and stores a
+reset token on ``request.state`` so the framework can tear the context down
+at end-of-request.
+
+On success the tenant id is published both on ``TenantContext`` (contextvar) and on
+``request.state.tenant`` (read by ``austial.audit`` so audit rows carry the tenant).
+
+Fails closed:
+
+- If the handler/controller carries ``@RequireTenant`` and the principal has
+  no ``tenant`` claim, raises ``MissingTenantError`` (403).
+- If the URL/body contains a ``tenant_id`` that disagrees with the claim,
+  raises ``TenantMismatchError`` (403). Product code opts in by overriding
+  ``read_body_tenant`` -- the base guard does not scan bodies to keep the
+  hot path fast.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from austial.common.decorators.injectable import Injectable
+from austial.common.guards.base import CanActivate, ExecutionContext
+from austial.tenancy.decorators import is_tenant_required
+from austial.tenancy.errors import MissingTenantError, TenantMismatchError
+from austial.tenancy.tenant_context import TenantContext, TenantContextValue
+
+
+@Injectable()
+class TenantGuard(CanActivate):
+    #: Treat every route as ``@RequireTenant`` (deny-by-default). Subclass and set ``True`` for a product
+    #: whose every non-public route is tenant-scoped, so a forgotten decorator cannot ship an endpoint
+    #: that runs without a tenant. The subclass is responsible for letting public routes through
+    #: *before* delegating here.
+    require_by_default: bool = False
+
+    async def can_activate(self, context: ExecutionContext) -> bool:
+        handler = context.get_handler()
+        controller = context.get_class()
+        required = self.require_by_default or is_tenant_required(handler) or is_tenant_required(controller)
+
+        request = context.get_request()
+        principal = getattr(request.state, "user", None)
+        claim = None
+        if principal is not None:
+            claim = principal.claims.get("tenant") if isinstance(principal.claims, dict) else None
+
+        if not claim:
+            if required:
+                raise MissingTenantError()
+            return True
+
+        path_tenant = request.path_params.get("tenant_id") if hasattr(request, "path_params") else None
+        if path_tenant is not None and str(path_tenant) != str(claim):
+            raise TenantMismatchError(str(claim), str(path_tenant))
+
+        token = TenantContext.set(TenantContextValue(tenant_id=str(claim)))
+        request.state.tenant_reset_token = token
+        # ``AuditedInterceptor`` reads the tenant from ``request.state.tenant``.
+        request.state.tenant = str(claim)
+        return True
+
+    def teardown(self, request: Any) -> None:
+        """Reset the contextvar after the response is sent. The framework's
+        request lifecycle should call this from a teardown hook; if it doesn't,
+        the contextvar is still request-scoped in async contexts and gets
+        released with the task."""
+        token = getattr(request.state, "tenant_reset_token", None)
+        if token is not None:
+            TenantContext.reset(token)

austial_tenancy-0.2.0/src/austial/tenancy/tenanted.py

@@ -0,0 +1,23 @@
+"""``Tenanted`` -- entity mixin adding a ``tenant_id`` column.
+
+Add to any entity that must be scoped to a tenant. The column is a required
+string (raises at flush time if unset) so a row without a tenant is a hard
+persistence error rather than a silent write to the wrong table.
+
+Product code sets ``tenant_id`` explicitly at insert (typically from
+``TenantContext.require().tenant_id`` in the service that creates the row),
+which keeps the write path auditable. On read, the repository or service
+filters by ``tenant_id`` -- ``TenantGuard`` guarantees the value exists.
+"""
+
+from __future__ import annotations
+
+from austial.orm.decorators.column import Column
+
+
+class Tenanted:
+    """Mixin -- inherit alongside your ``@Entity()``-decorated dataclass to add
+    a ``tenant_id`` column. Order matters: put ``Tenanted`` before other
+    mixins but after your primary-key column."""
+
+    tenant_id: str = Column(nullable=False, index=True)

austial_tenancy-0.2.0/test/tenancy_spec.py

@@ -0,0 +1,197 @@
+"""``austial.tenancy`` unit tests.
+
+Exercises the four load-bearing behaviours:
+
+- ``TenantContext`` is request-scoped: setting it in one task does not leak into
+  another; a reset restores the prior value.
+- ``TenantContext.require()`` raises when unset.
+- ``TenantGuard`` populates the context from the ``tenant`` claim of the
+  authenticated principal.
+- ``TenantGuard`` fails-closed on ``@RequireTenant`` handlers with no claim,
+  and fails-closed on a path-tenant that disagrees with the claim.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from types import SimpleNamespace
+
+import pytest
+
+from austial.common import ExecutionContext
+from austial.tenancy import (
+    MissingTenantError,
+    RequireTenant,
+    TenantContext,
+    TenantContextValue,
+    TenantGuard,
+    TenantMismatchError,
+)
+
+
+class _FakeExecutionContext(ExecutionContext):
+    def __init__(self, request, controller_class, handler):
+        self._request = request
+        self._controller_class = controller_class
+        self._handler = handler
+
+    def get_request(self):
+        return self._request
+
+    def get_class(self):
+        return self._controller_class
+
+    def get_handler(self):
+        return self._handler
+
+
+def _principal(tenant: str | None):
+    return SimpleNamespace(claims={"tenant": tenant} if tenant is not None else {})
+
+
+def _request(principal, path_params: dict | None = None):
+    return SimpleNamespace(
+        state=SimpleNamespace(user=principal),
+        path_params=path_params or {},
+    )
+
+
+# ---------------------------------------------------------------------------
+# TenantContext
+
+
+def test_context_starts_unset():
+    assert TenantContext.get() is None
+
+
+def test_context_require_raises_when_unset():
+    with pytest.raises(MissingTenantError):
+        TenantContext.require()
+
+
+def test_context_set_and_reset_round_trip():
+    token = TenantContext.set(TenantContextValue(tenant_id="acme"))
+    try:
+        assert TenantContext.require().tenant_id == "acme"
+    finally:
+        TenantContext.reset(token)
+    assert TenantContext.get() is None
+
+
+@pytest.mark.asyncio
+async def test_context_is_request_scoped_across_tasks():
+    # Two concurrent tasks set different tenants; neither should see the other's.
+    async def task(tenant: str):
+        token = TenantContext.set(TenantContextValue(tenant_id=tenant))
+        try:
+            await asyncio.sleep(0)  # yield to the scheduler
+            return TenantContext.require().tenant_id
+        finally:
+            TenantContext.reset(token)
+
+    seen = await asyncio.gather(task("acme"), task("initech"), task("hooli"))
+    assert sorted(seen) == ["acme", "hooli", "initech"]
+    # After all tasks complete, the outer context is still unset
+    assert TenantContext.get() is None
+
+
+# ---------------------------------------------------------------------------
+# TenantGuard
+
+
+@pytest.mark.asyncio
+async def test_guard_populates_context_from_claim():
+    guard = TenantGuard()
+
+    def handler():
+        pass
+
+    req = _request(_principal("acme"))
+    ctx = _FakeExecutionContext(req, object, handler)
+    assert await guard.can_activate(ctx) is True
+    assert TenantContext.require().tenant_id == "acme"
+    guard.teardown(req)
+
+
+@pytest.mark.asyncio
+async def test_guard_is_permissive_without_require_marker():
+    guard = TenantGuard()
+
+    def handler():
+        pass
+
+    # No principal at all: guard allows through so a @Public route can still run
+    req = _request(None)
+    ctx = _FakeExecutionContext(req, object, handler)
+    assert await guard.can_activate(ctx) is True
+    assert TenantContext.get() is None
+
+
+@pytest.mark.asyncio
+async def test_guard_rejects_missing_tenant_when_required():
+    guard = TenantGuard()
+
+    @RequireTenant()
+    def handler():
+        pass
+
+    req = _request(_principal(None))
+    ctx = _FakeExecutionContext(req, object, handler)
+    with pytest.raises(MissingTenantError):
+        await guard.can_activate(ctx)
+
+
+@pytest.mark.asyncio
+async def test_guard_rejects_tenant_path_mismatch():
+    guard = TenantGuard()
+
+    def handler():
+        pass
+
+    req = _request(_principal("acme"), path_params={"tenant_id": "hooli"})
+    ctx = _FakeExecutionContext(req, object, handler)
+    with pytest.raises(TenantMismatchError):
+        await guard.can_activate(ctx)
+
+
+@pytest.mark.asyncio
+async def test_guard_publishes_tenant_on_request_state_for_the_audit_interceptor():
+    guard = TenantGuard()
+
+    def handler():
+        pass
+
+    req = _request(_principal("acme"))
+    assert await guard.can_activate(_FakeExecutionContext(req, object, handler)) is True
+    assert req.state.tenant == "acme"
+    guard.teardown(req)
+
+
+@pytest.mark.asyncio
+async def test_require_by_default_subclass_rejects_undecorated_handler_without_tenant():
+    class StrictTenantGuard(TenantGuard):
+        require_by_default = True
+
+    def handler():
+        pass
+
+    with pytest.raises(MissingTenantError):
+        await StrictTenantGuard().can_activate(_FakeExecutionContext(_request(_principal(None)), object, handler))
+
+
+def test_tenanted_mixin_adds_a_required_indexed_tenant_id_column():
+    from austial.orm import Entity, PrimaryColumn
+    from austial.orm.decorators.entity import get_entity_metadata
+    from austial.orm.metadata.column_types import String
+    from austial.tenancy import Tenanted
+
+    @Entity("tenanted_widgets")
+    class Widget(Tenanted):
+        id: str = PrimaryColumn(type_=String(length=36))
+
+    column = get_entity_metadata(Widget).column("tenant_id")
+    assert column is not None and column.index is True and column.nullable is False
+    # mypy caveat (documented in content/techniques/multi-tenancy.mdx#tenanted-entities): `Tenanted`
+    # is a plain mixin, not itself part of the dataclass_transform chain, so mypy doesn't see
+    # `tenant_id` as a constructor parameter even though it works correctly at runtime.
+    assert Widget(id="w1", tenant_id="acme").tenant_id == "acme"  # type: ignore[call-arg]