terp-cap-tenancy 0.1.0__tar.gz

terp_cap_tenancy-0.1.0/.gitignore

@@ -0,0 +1,47 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+.venv-*/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# uv
+uv.lock
+
+# Node
+node_modules/
+.pnpm-store/
+*.tsbuildinfo
+
+# Playwright (conformance e2e) artifacts
+test-results/
+playwright-report/
+blob-report/
+playwright/.cache/
+.last-run.json
+
+# Local frontend template render checks
+apps/example/_frontend_tpl_check/
+
+# Editor / OS
+.DS_Store
+.idea/
+*.local
+
+# Local environment overrides — never commit (a real .env may hold SECRET_KEY).
+# The tracked template is `.env.example`.
+.env
+.env.*
+!.env.example
+!.env.example.jinja
+# Rendered app-declared variables (environment.schema.json) — may hold secrets.
+.app.env

terp_cap_tenancy-0.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: terp-cap-tenancy
+Version: 0.1.0
+Summary: Terp tenancy capability — tenant isolation by construction (session-level filter + insert stamp).
+License-Expression: Apache-2.0
+Requires-Python: >=3.13
+Requires-Dist: starlette>=0.37
+Requires-Dist: terp-core==0.1.0

terp_cap_tenancy-0.1.0/escape-hatch-budget.json

@@ -0,0 +1,3 @@
+{
+  "arch-allow-no-manual-scope-filtering": 1
+}

terp_cap_tenancy-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "terp-cap-tenancy"
+version = "0.1.0"
+description = "Terp tenancy capability — tenant isolation by construction (session-level filter + insert stamp)."
+requires-python = ">=3.13"
+license = "Apache-2.0"
+dependencies = [
+    "terp-core==0.1.0",
+    "starlette>=0.37",
+]
+
+# PEP 420 namespace package: this distribution owns only `terp.capabilities.tenancy`.
+[tool.hatch.build.targets.wheel]
+sources = ["src"]
+only-include = ["src/terp/capabilities/tenancy"]

terp_cap_tenancy-0.1.0/src/terp/capabilities/tenancy/__init__.py

@@ -0,0 +1,39 @@
+"""terp.capabilities.tenancy — tenant scoping as a capability (kernel stays agnostic).
+
+The kernel ships no tenant column, predicate, or scoping model. This capability
+adds them: a model becomes tenant-scoped by mixing in :class:`TenantScopedMixin`;
+the capability registers a **row-scope predicate** into the kernel's scope registry,
+so every read of a tenant-scoped model is filtered to the current tenant centrally
+(no ``base_query`` override, no ``super()``). Its service extends
+:class:`TenantScopedService`, which stamps ``tenant_id`` on create — no kernel change.
+
+The current tenant is held in a :class:`~contextvars.ContextVar` set via
+:func:`tenant_context`. In an HTTP app, :class:`TenantMiddleware` binds it once
+per request from the caller's verified token (the app supplies the resolver, e.g.
+``terp.capabilities.auth.tenant_from_bearer``); tests set it directly. A missing
+context fails closed: scoped reads return nothing and scoped writes raise
+:class:`TenantContextError`.
+"""
+
+from __future__ import annotations
+
+from terp.capabilities.tenancy.context import (
+    TenantContextError,
+    current_tenant_id,
+    require_tenant,
+    tenant_context,
+)
+from terp.capabilities.tenancy.middleware import TenantMiddleware, TenantResolver
+from terp.capabilities.tenancy.models import TenantScopedMixin
+from terp.capabilities.tenancy.service import TenantScopedService
+
+__all__ = [
+    "TenantContextError",
+    "TenantMiddleware",
+    "TenantResolver",
+    "TenantScopedMixin",
+    "TenantScopedService",
+    "current_tenant_id",
+    "require_tenant",
+    "tenant_context",
+]

terp_cap_tenancy-0.1.0/src/terp/capabilities/tenancy/context.py

@@ -0,0 +1,53 @@
+"""The current-tenant context (a ``ContextVar`` + helpers)."""
+
+from __future__ import annotations
+
+import contextlib
+import uuid
+from collections.abc import Iterator
+from contextvars import ContextVar
+
+from terp.core import AppError
+
+_current_tenant: ContextVar[uuid.UUID | None] = ContextVar(
+    "terp_current_tenant", default=None
+)
+
+
+class TenantContextError(AppError):
+    """Raised when a tenant-scoped operation runs with no tenant in context."""
+
+    status_code = 500
+    code = "tenant_context_missing"
+    default_message = "No tenant is set for the current operation."
+
+
+def current_tenant_id() -> uuid.UUID | None:
+    """Return the tenant for the active operation, or ``None``."""
+    return _current_tenant.get()
+
+
+def require_tenant() -> uuid.UUID:
+    """Return the current tenant, or raise :class:`TenantContextError`."""
+    tenant = _current_tenant.get()
+    if tenant is None:
+        raise TenantContextError()
+    return tenant
+
+
+@contextlib.contextmanager
+def tenant_context(tenant_id: uuid.UUID | None) -> Iterator[None]:
+    """Bind *tenant_id* as the current tenant for the duration of the block."""
+    token = _current_tenant.set(tenant_id)
+    try:
+        yield
+    finally:
+        _current_tenant.reset(token)
+
+
+__all__ = [
+    "TenantContextError",
+    "current_tenant_id",
+    "require_tenant",
+    "tenant_context",
+]

terp_cap_tenancy-0.1.0/src/terp/capabilities/tenancy/middleware.py

@@ -0,0 +1,56 @@
+"""``TenantMiddleware`` — bind the per-request tenant from the caller's request.
+
+A **pure-ASGI** middleware (deliberately not ``BaseHTTPMiddleware``, which runs the
+downstream app in a separate task and so would not propagate a ``ContextVar`` set
+here to the endpoint). It calls an app-supplied ``resolve_tenant(request)`` — e.g.
+``terp.capabilities.auth.tenant_from_bearer`` — and runs the request inside
+:func:`~terp.capabilities.tenancy.tenant_context`, resetting it afterwards.
+
+The tenancy capability stays decoupled from auth: it knows *how* to bind a tenant
+per request, not *how* to read one. The app wires the two together through the
+sanctioned ``create_app`` middleware seam (ADR 0021) — never a bare
+``add_middleware`` (the ``no_adhoc_middleware`` rule forbids it)::
+
+    from starlette.middleware import Middleware
+    from terp.capabilities.auth import tenant_from_bearer
+
+    app = create_app(
+        specs,
+        principal_provider=get_principal,
+        middleware=[Middleware(TenantMiddleware, resolve_tenant=tenant_from_bearer)],
+    )
+
+Fail-closed: a request that resolves to no tenant runs with an empty context, so
+every ``TenantScopedService`` read returns nothing and writes raise.
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Callable
+
+from starlette.requests import Request
+from starlette.types import ASGIApp, Receive, Scope, Send
+
+from terp.capabilities.tenancy.context import tenant_context
+
+TenantResolver = Callable[[Request], uuid.UUID | None]
+
+
+class TenantMiddleware:
+    """ASGI middleware that binds ``tenant_context`` from *resolve_tenant* per request."""
+
+    def __init__(self, app: ASGIApp, *, resolve_tenant: TenantResolver) -> None:
+        self.app = app
+        self._resolve_tenant = resolve_tenant
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+        tenant = self._resolve_tenant(Request(scope))
+        with tenant_context(tenant):
+            await self.app(scope, receive, send)
+
+
+__all__ = ["TenantMiddleware", "TenantResolver"]

terp_cap_tenancy-0.1.0/src/terp/capabilities/tenancy/models.py

@@ -0,0 +1,48 @@
+"""``TenantScopedMixin`` — marks a table's rows as belonging to a tenant.
+
+Importing this mixin registers the tenancy row-scope predicate with the kernel's
+scope registry, so the runtime read-scope layer is installed as soon as a model opts
+into tenancy (ADR 0017). ``TenantScopedService`` still stamps ``tenant_id`` on
+create; the mixin owns the read predicate.
+"""
+
+from __future__ import annotations
+
+import uuid
+
+from sqlalchemy import false
+from sqlmodel import Field, SQLModel
+from sqlmodel.sql.expression import SelectOfScalar
+
+from terp.capabilities.tenancy.context import current_tenant_id
+from terp.core import register_scope_predicate
+
+
+class TenantScopedMixin(SQLModel):
+    """Mix into a ``BaseTable`` to scope its rows to a tenant.
+
+    Adds a non-null, indexed ``tenant_id``. The registered tenant predicate filters
+    every read by the current tenant, and ``TenantScopedService`` stamps it on insert,
+    so a model is tenant-scoped purely by inheriting this — the kernel needs no
+    tenant-specific import.
+    """
+
+    tenant_id: uuid.UUID = Field(index=True, nullable=False)
+
+
+def _tenant_scope_predicate(
+    model: type[SQLModel], query: SelectOfScalar
+) -> SelectOfScalar:
+    """Filter a tenant-scoped model's reads by the current tenant (registered centrally)."""
+    if issubclass(model, TenantScopedMixin):
+        tenant_id = current_tenant_id()
+        if tenant_id is None:
+            return query.where(false())
+        return query.where(model.tenant_id == tenant_id)  # type: ignore[attr-defined]  # arch-allow-no-manual-scope-filtering: this IS the central tenant predicate the rule points app modules to
+    return query
+
+
+register_scope_predicate(_tenant_scope_predicate)
+
+
+__all__ = ["TenantScopedMixin"]

terp_cap_tenancy-0.1.0/src/terp/capabilities/tenancy/service.py

@@ -0,0 +1,52 @@
+"""``TenantScopedService`` — write stamping for tenant-scoped models.
+
+The kernel stays tenancy-agnostic. A model becomes tenant-scoped by mixing in
+:class:`~terp.capabilities.tenancy.TenantScopedMixin`, which registers the
+**row-scope predicate** with the kernel's scope registry. Reads are therefore
+filtered centrally (no ``base_query`` override, no ``super()``, ADR 0017), and this
+service only stamps ``tenant_id`` on create (rejecting an absent context).
+"""
+
+from __future__ import annotations
+
+from typing import TypeVar
+
+from sqlmodel import Session, SQLModel
+
+from terp.capabilities.tenancy.context import require_tenant
+from terp.core import (
+    AuditAction,
+    BaseService,
+    BaseTable,
+    BaseUpdateSchema,
+)
+
+ModelT = TypeVar("ModelT", bound=BaseTable)
+CreateT = TypeVar("CreateT", bound=SQLModel)
+UpdateT = TypeVar("UpdateT", bound=BaseUpdateSchema)
+
+
+class TenantScopedService(BaseService[ModelT, CreateT, UpdateT]):
+    """A :class:`~terp.core.BaseService` whose model is tenant-scoped.
+
+    ``model`` must mix in :class:`~terp.capabilities.tenancy.TenantScopedMixin`.
+    Reads are filtered to ``current_tenant_id()`` by the registered scope predicate
+    (``None`` matches no rows, so a missing context fails closed); this service
+    stamps the required tenant on create.
+    """
+
+    def create(self, session: Session, data: CreateT) -> ModelT:
+        # Route through the audited chokepoint so a tenant-scoped create is audited,
+        # actor-stamped, event-hooked, and 409-mapped exactly like every other write.
+        # Strip framework-managed columns first (anti over-posting, like BaseService),
+        # then stamp the tenant from context -- never from the request body. Stripping
+        # tenant_id from the payload also avoids a duplicate-keyword collision with the
+        # context-derived value below.
+        entity = self.model(
+            **self._without_managed_columns(data.model_dump()),
+            tenant_id=require_tenant(),
+        )
+        return self._save(session, entity, AuditAction.CREATED)
+
+
+__all__ = ["TenantScopedService"]