austial-tenancy 0.2.0__py3-none-any.whl

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/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/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/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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+austial/tenancy/__init__.py,sha256=H9SN-6IJgBcsJyRFLm-k1DTwhKvXIiVr7S6_DHg5V7U,1428
+austial/tenancy/decorators.py,sha256=xOPk2k_GbhrMhfpn5BEArfmLhha4mdSYXAbkBagSCxI,887
+austial/tenancy/errors.py,sha256=BWA5M5o6-cUWRnGmH0nXj8AcYdKSHWjyVEkqjKiqjuU,610
+austial/tenancy/tenancy_module.py,sha256=XReXao8L269ArytkdeqL6OgnPrhoBamBqDBFRjjsZxE,632
+austial/tenancy/tenant_context.py,sha256=MUnpWVnE1Glg2czN9vb9_gR-WojySw_Q5i7NGWuYvIk,2362
+austial/tenancy/tenant_guard.py,sha256=4It_6wo6x50OlwHLv78kt6LQmkPx1TjkX3pG-mubdDU,3323
+austial/tenancy/tenanted.py,sha256=LToJwMv_0LlHgwMHx1utU9lLTCh4PLmzTfNRGSCBfgM,939
+austial_tenancy-0.2.0.dist-info/METADATA,sha256=cH0DG5Iripe4utb4rvunRYjHXLTRQYl4mkCel2SLjJQ,390
+austial_tenancy-0.2.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+austial_tenancy-0.2.0.dist-info/RECORD,,

austial_tenancy-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any