fastplace-tenancy 0.1.0__tar.gz

fastplace_tenancy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Firoz Anam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fastplace_tenancy-0.1.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: fastplace-tenancy
+Version: 0.1.0
+Summary: First-party, opt-in multi-tenancy for Fastplace — company-scoped models, defense-in-depth isolation.
+Author: Firoz Anam
+License-Expression: MIT
+Project-URL: Homepage, https://fastplace.dev
+Project-URL: Repository, https://github.com/fastplace-dev/fastplace.dev
+Project-URL: Issues, https://github.com/fastplace-dev/fastplace.dev/issues
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastplace>=0.1.0
+Dynamic: license-file
+
+# fastplace-tenancy
+
+First-party, **opt-in** multi-tenancy for
+[Fastplace](https://fastplace.dev). The core framework stays tenant-agnostic;
+applications that need company scoping install this package and get the same
+class of guarantees the core gives soft deletes — invariants enforced by the
+framework, not by developer discipline.
+
+    pip install fastplace-tenancy
+
+## The isolation boundary
+
+Single database, company-scoped rows: `Account → Company → company_id →
+company-scoped records`. Every company-owned table carries a `company_id`
+column, and this package keeps that column meaningful at every layer a
+request touches (blueprint §8, "Multi-Tenant Data Architecture"):
+
+| Layer | Strategy |
+| :--- | :--- |
+| ORM | Automatic `company` global scope on `CompanyScopedModel` |
+| API | `CompanyContextMiddleware` binds the request to one company |
+| Authorization | Membership checks (`require_membership`) for services |
+| Database | PostgreSQL Row-Level Security helpers (`fastplace_tenancy.rls`) |
+| Cache | `company:{id}:…` key prefix (`CompanyCacheStore`) |
+| Queue | Company context carried in job metadata (`TenantQueue` + `@tenant_job`) |
+| Files | Company prefixes under `storage/` with traversal guards |
+| Search | Company filter applied over the active `SearchService` |
+| Vector store | Company filter on similarity results |
+| MongoDB | Automatic `company_id` filters (`CompanyDocument`) |
+
+## Automatic company scoping
+
+Company-owned models extend `CompanyScopedModel`; the package ships the
+tenant entities themselves:
+
+```python
+from fastplace_tenancy import Company, CompanyMembership, CompanyScopedModel
+
+
+class Project(CompanyScopedModel):
+    __tablename__ = "projects"
+    __unique_per_company__ = [("slug",)]  # UNIQUE(company_id, slug)
+
+    title: str
+    slug: str
+```
+
+Every read now receives the tenant filter — `SELECT … WHERE company_id = ?` —
+and every `create()` stamps the column from the active company context. The
+`company_id` column is guarded from mass assignment: a payload cannot move a
+row into (or read it as) another company.
+
+### Fail-closed by design
+
+Querying a `CompanyScopedModel` **without** a company context raises
+`MissingCompanyContext` — a missing tenant is a bug, not "return everything".
+Cross-company work (admin shells, exports) is an explicit escape:
+
+```python
+await Project.without_global_scope("company").where(...)  # this query only
+async with company_context(company.id):  # bind a context
+    await Project.all()
+```
+
+## Request binding
+
+```python
+# config/app.py
+MIDDLEWARE = [
+    "app.http.middleware.resolve_user.ResolveUserMiddleware",
+    "fastplace_tenancy.middleware.CompanyContextMiddleware",
+    "app.http.middleware.csrf.CsrfMiddleware",
+]
+```
+
+The middleware resolves the company for the authenticated user:
+
+1. a session `company_id` — **validated against membership**. The stored
+   value is a request, not a grant: it binds only when the user actually
+   holds a membership in that company, otherwise it is ignored;
+2. else the user's earliest membership (ordered by membership id — a
+   documented key, not whatever the query planner returns first);
+3. else nothing — the request stays unbound and company-scoped queries fail
+   closed.
+
+Controllers read the binding through the helper (there is no
+`request.state.company_id`):
+
+```python
+from fastplace_tenancy.middleware import request_company_id
+
+company_id = request_company_id(request)  # None when unbound
+```
+
+A company-switch endpoint should pair the session write with a membership
+check, so a forged or stale value never even reaches the middleware:
+
+```python
+async def switch(self, request):
+    body = await request.json()
+    await require_membership(request.user.id, body["company_id"])
+    request.session["company_id"] = body["company_id"]
+```
+
+Override `_resolve_company_id()` to source the company differently
+(subdomain, header, JWT claim).
+
+## Services check membership
+
+```python
+from fastplace_tenancy import require_membership
+
+
+async def invite(request, company_id: int):
+    await require_membership(request.user.id, company_id, roles={"owner", "admin"})
+    ...
+```
+
+## Queue jobs carry the company
+
+Wrap the driver once and decorate handlers; the context travels as job
+metadata and re-binds inside the worker. Install the wrapper as the
+process-wide queue so domain-event auto-dispatch flows through it too:
+
+```python
+from fastplace.queue import set_queue
+
+from fastplace_tenancy import TenantQueue, tenant_job
+
+set_queue(TenantQueue(existing_driver))
+
+
+@Job()
+@tenant_job
+async def rebuild_report(project_id: int): ...
+```
+
+`@tenant_job` requires an `async def` handler — a sync function fails at
+decoration with a `TypeError`, the same guard `@Job` itself applies.
+
+## Multi-tenant indexing & uniqueness
+
+High-volume company tables index with `company_id` first — the base model's
+`company_id` column is indexed; declare composites with
+`__index_per_company__`. Uniqueness distinguishes globally unique
+(`Field(unique=True)`) from unique-within-a-company
+(`__unique_per_company__` → `UNIQUE(company_id, …)`).
+
+## Row-Level Security (PostgreSQL)
+
+Where the backend supports native RLS (see the capability registry — MySQL
+and SQLite never claim it), `fastplace_tenancy.rls` can push the same policy
+into the database itself as defense-in-depth below the ORM scope:
+
+```python
+from fastplace_tenancy.rls import enable_company_rls, set_rls_company
+
+await enable_company_rls(Project)  # once, at migration time
+
+async with db.connection():  # per transaction
+    await set_rls_company(company.id)
+    ...
+```
+
+`set_rls_company` uses `SET LOCAL`, so the setting **dies with the
+transaction** — a pooled connection carries nothing into the next borrower's
+transaction. Deployment duties the DDL cannot do for you: the connecting role
+must not own the table or carry `BYPASSRLS` (owners bypass policies
+silently), and every transaction must set the company before touching
+company tables.
+
+## Tenant-isolation contract suite
+
+`tests/tenancy/` is the contract: two companies, one code path — cross-company
+reads come back empty, writes stamp the right tenant, cache keys never
+collide, jobs re-bind their company, and uniqueness is per-company. The suite
+runs on the same portable matrix as the core (SQLite always; PostgreSQL /
+MySQL when `TEST_*_URL` is set).

fastplace_tenancy-0.1.0/README.md

@@ -0,0 +1,178 @@
+# fastplace-tenancy
+
+First-party, **opt-in** multi-tenancy for
+[Fastplace](https://fastplace.dev). The core framework stays tenant-agnostic;
+applications that need company scoping install this package and get the same
+class of guarantees the core gives soft deletes — invariants enforced by the
+framework, not by developer discipline.
+
+    pip install fastplace-tenancy
+
+## The isolation boundary
+
+Single database, company-scoped rows: `Account → Company → company_id →
+company-scoped records`. Every company-owned table carries a `company_id`
+column, and this package keeps that column meaningful at every layer a
+request touches (blueprint §8, "Multi-Tenant Data Architecture"):
+
+| Layer | Strategy |
+| :--- | :--- |
+| ORM | Automatic `company` global scope on `CompanyScopedModel` |
+| API | `CompanyContextMiddleware` binds the request to one company |
+| Authorization | Membership checks (`require_membership`) for services |
+| Database | PostgreSQL Row-Level Security helpers (`fastplace_tenancy.rls`) |
+| Cache | `company:{id}:…` key prefix (`CompanyCacheStore`) |
+| Queue | Company context carried in job metadata (`TenantQueue` + `@tenant_job`) |
+| Files | Company prefixes under `storage/` with traversal guards |
+| Search | Company filter applied over the active `SearchService` |
+| Vector store | Company filter on similarity results |
+| MongoDB | Automatic `company_id` filters (`CompanyDocument`) |
+
+## Automatic company scoping
+
+Company-owned models extend `CompanyScopedModel`; the package ships the
+tenant entities themselves:
+
+```python
+from fastplace_tenancy import Company, CompanyMembership, CompanyScopedModel
+
+
+class Project(CompanyScopedModel):
+    __tablename__ = "projects"
+    __unique_per_company__ = [("slug",)]  # UNIQUE(company_id, slug)
+
+    title: str
+    slug: str
+```
+
+Every read now receives the tenant filter — `SELECT … WHERE company_id = ?` —
+and every `create()` stamps the column from the active company context. The
+`company_id` column is guarded from mass assignment: a payload cannot move a
+row into (or read it as) another company.
+
+### Fail-closed by design
+
+Querying a `CompanyScopedModel` **without** a company context raises
+`MissingCompanyContext` — a missing tenant is a bug, not "return everything".
+Cross-company work (admin shells, exports) is an explicit escape:
+
+```python
+await Project.without_global_scope("company").where(...)  # this query only
+async with company_context(company.id):  # bind a context
+    await Project.all()
+```
+
+## Request binding
+
+```python
+# config/app.py
+MIDDLEWARE = [
+    "app.http.middleware.resolve_user.ResolveUserMiddleware",
+    "fastplace_tenancy.middleware.CompanyContextMiddleware",
+    "app.http.middleware.csrf.CsrfMiddleware",
+]
+```
+
+The middleware resolves the company for the authenticated user:
+
+1. a session `company_id` — **validated against membership**. The stored
+   value is a request, not a grant: it binds only when the user actually
+   holds a membership in that company, otherwise it is ignored;
+2. else the user's earliest membership (ordered by membership id — a
+   documented key, not whatever the query planner returns first);
+3. else nothing — the request stays unbound and company-scoped queries fail
+   closed.
+
+Controllers read the binding through the helper (there is no
+`request.state.company_id`):
+
+```python
+from fastplace_tenancy.middleware import request_company_id
+
+company_id = request_company_id(request)  # None when unbound
+```
+
+A company-switch endpoint should pair the session write with a membership
+check, so a forged or stale value never even reaches the middleware:
+
+```python
+async def switch(self, request):
+    body = await request.json()
+    await require_membership(request.user.id, body["company_id"])
+    request.session["company_id"] = body["company_id"]
+```
+
+Override `_resolve_company_id()` to source the company differently
+(subdomain, header, JWT claim).
+
+## Services check membership
+
+```python
+from fastplace_tenancy import require_membership
+
+
+async def invite(request, company_id: int):
+    await require_membership(request.user.id, company_id, roles={"owner", "admin"})
+    ...
+```
+
+## Queue jobs carry the company
+
+Wrap the driver once and decorate handlers; the context travels as job
+metadata and re-binds inside the worker. Install the wrapper as the
+process-wide queue so domain-event auto-dispatch flows through it too:
+
+```python
+from fastplace.queue import set_queue
+
+from fastplace_tenancy import TenantQueue, tenant_job
+
+set_queue(TenantQueue(existing_driver))
+
+
+@Job()
+@tenant_job
+async def rebuild_report(project_id: int): ...
+```
+
+`@tenant_job` requires an `async def` handler — a sync function fails at
+decoration with a `TypeError`, the same guard `@Job` itself applies.
+
+## Multi-tenant indexing & uniqueness
+
+High-volume company tables index with `company_id` first — the base model's
+`company_id` column is indexed; declare composites with
+`__index_per_company__`. Uniqueness distinguishes globally unique
+(`Field(unique=True)`) from unique-within-a-company
+(`__unique_per_company__` → `UNIQUE(company_id, …)`).
+
+## Row-Level Security (PostgreSQL)
+
+Where the backend supports native RLS (see the capability registry — MySQL
+and SQLite never claim it), `fastplace_tenancy.rls` can push the same policy
+into the database itself as defense-in-depth below the ORM scope:
+
+```python
+from fastplace_tenancy.rls import enable_company_rls, set_rls_company
+
+await enable_company_rls(Project)  # once, at migration time
+
+async with db.connection():  # per transaction
+    await set_rls_company(company.id)
+    ...
+```
+
+`set_rls_company` uses `SET LOCAL`, so the setting **dies with the
+transaction** — a pooled connection carries nothing into the next borrower's
+transaction. Deployment duties the DDL cannot do for you: the connecting role
+must not own the table or carry `BYPASSRLS` (owners bypass policies
+silently), and every transaction must set the company before touching
+company tables.
+
+## Tenant-isolation contract suite
+
+`tests/tenancy/` is the contract: two companies, one code path — cross-company
+reads come back empty, writes stamp the right tenant, cache keys never
+collide, jobs re-bind their company, and uniqueness is per-company. The suite
+runs on the same portable matrix as the core (SQLite always; PostgreSQL /
+MySQL when `TEST_*_URL` is set).

fastplace_tenancy-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "fastplace-tenancy"
+version = "0.1.0"
+description = "First-party, opt-in multi-tenancy for Fastplace — company-scoped models, defense-in-depth isolation."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Firoz Anam" }]
+dependencies = [
+    "fastplace>=0.1.0",
+]
+
+[project.urls]
+Homepage = "https://fastplace.dev"
+Repository = "https://github.com/fastplace-dev/fastplace.dev"
+Issues = "https://github.com/fastplace-dev/fastplace.dev/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]

fastplace_tenancy-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

fastplace_tenancy-0.1.0/src/fastplace_tenancy/__init__.py

@@ -0,0 +1,78 @@
+"""fastplace-tenancy — opt-in company-scoped multi-tenancy for Fastplace.
+
+The core framework stays tenant-agnostic (ADR-005); installing this package
+adds the ``company`` global scope, request binding, membership authorization,
+and per-layer isolation (cache/queue/storage/search/vector/MongoDB/RLS).
+Import paths here are ``fastplace_tenancy.*`` — the package is a sibling
+distribution, never a ``fastplace.*`` submodule.
+"""
+
+from fastplace_tenancy.authorization import require_membership
+from fastplace_tenancy.cache import CompanyCacheStore
+from fastplace_tenancy.context import (
+    CompanyRoleRequired,
+    MissingCompanyContext,
+    NotCompanyMember,
+    RLSNotSupported,
+    TenancyError,
+    company_context,
+    current_company_id,
+    require_company_context,
+    reset_company_context,
+)
+from fastplace_tenancy.documents import CompanyDocument
+from fastplace_tenancy.middleware import CompanyContextMiddleware, request_company_id
+from fastplace_tenancy.models import Company, CompanyMembership, CompanyScopedModel
+from fastplace_tenancy.queue import TenantQueue, tenant_job
+from fastplace_tenancy.rls import (
+    clear_rls_company,
+    enable_company_rls,
+    set_rls_company,
+    supports_rls,
+)
+from fastplace_tenancy.search import TenantSearchService
+from fastplace_tenancy.storage import (
+    company_root,
+    company_storage_path,
+    ensure_company_path,
+)
+from fastplace_tenancy.vectors import TenantVectorStore
+
+__all__ = [
+    # context
+    "CompanyRoleRequired",
+    "MissingCompanyContext",
+    "NotCompanyMember",
+    "RLSNotSupported",
+    "TenancyError",
+    "company_context",
+    "current_company_id",
+    "require_company_context",
+    "reset_company_context",
+    # models + authorization
+    "Company",
+    "CompanyMembership",
+    "CompanyScopedModel",
+    "require_membership",
+    # middleware
+    "CompanyContextMiddleware",
+    "request_company_id",
+    # cache
+    "CompanyCacheStore",
+    # queue
+    "TenantQueue",
+    "tenant_job",
+    # storage
+    "company_root",
+    "company_storage_path",
+    "ensure_company_path",
+    # search / vectors / documents
+    "TenantSearchService",
+    "TenantVectorStore",
+    "CompanyDocument",
+    # RLS
+    "clear_rls_company",
+    "enable_company_rls",
+    "set_rls_company",
+    "supports_rls",
+]

fastplace_tenancy-0.1.0/src/fastplace_tenancy/authorization.py

@@ -0,0 +1,52 @@
+"""Membership authorization — the service-layer tenant check.
+
+Services call :func:`require_membership` before touching company data; the
+errors are :class:`FastplaceError` subclasses, so the kernel answers with
+403 JSON instead of a traceback.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Collection
+from typing import Any
+
+from fastplace_tenancy.context import (
+    CompanyRoleRequired,
+    MissingCompanyContext,
+    NotCompanyMember,
+    require_company_context,
+)
+
+
+async def require_membership(
+    user_id: Any,
+    company_id: Any | None = None,
+    *,
+    roles: Collection[str] | None = None,
+) -> Any:
+    """Assert the actor belongs to the company; return the membership row.
+
+    ``company_id`` defaults to the bound company context. With ``roles``,
+    the membership's role must be one of them — possession of *a* role in
+    one company never authorizes the *other* company's resources.
+    """
+    if company_id is None:
+        company_id = require_company_context()
+
+    from fastplace_tenancy.models import CompanyMembership
+
+    membership = await CompanyMembership.where(
+        CompanyMembership.user_id == user_id,
+        CompanyMembership.company_id == company_id,
+    ).first()
+    if membership is None:
+        raise NotCompanyMember(f"user {user_id!r} has no membership in company {company_id!r}")
+    if roles is not None and membership.role not in roles:
+        raise CompanyRoleRequired(
+            f"membership role {membership.role!r} is not one of "
+            f"{sorted(roles)} — company {company_id!r} requires it"
+        )
+    return membership
+
+
+__all__ = ["require_membership", "MissingCompanyContext"]

fastplace_tenancy-0.1.0/src/fastplace_tenancy/cache.py

@@ -0,0 +1,55 @@
+"""Cache isolation — ``company:{id}:`` prefixed keys over any CacheStore.
+
+Wrap the application's store once (composition, not a subclass — the store
+ underneath can be Redis, memory, or anything implementing the protocol)::
+
+    cache = CompanyCacheStore(existing_store)
+
+Keys are prefixed with the bound company; without a bound company every
+operation fails closed. ``flush()`` is refused outright: a company-scoped
+wrapper cannot know what else lives in the shared physical store, and
+"forget everyone's cache" must never be one tenant's side effect.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastplace_tenancy.context import require_company_context
+
+
+class CompanyCacheStore:
+    """A CacheStore whose keys are namespaced to the bound company."""
+
+    def __init__(self, inner: Any) -> None:
+        self._inner = inner
+
+    def _key(self, key: str) -> str:
+        company_id = require_company_context()
+        return f"company:{company_id}:{key}"
+
+    async def get(self, key: str) -> Any:
+        return await self._inner.get(self._key(key))
+
+    async def put(self, key: str, value: Any, ttl: int | float | None = None) -> None:
+        await self._inner.put(self._key(key), value, ttl)
+
+    async def forget(self, key: str) -> None:
+        await self._inner.forget(self._key(key))
+
+    async def remember(
+        self,
+        key: str,
+        ttl: int | float | None = None,
+        factory: Any = lambda: None,
+    ) -> Any:
+        # Same optionality as the CacheStore protocol — remember(key) is a
+        # legal call and must stay one through the wrapper.
+        return await self._inner.remember(self._key(key), ttl, factory)
+
+    async def flush(self) -> None:
+        raise NotImplementedError(
+            "flush() is refused on a company-scoped store — it would clear "
+            "every tenant's entries in the shared physical store; flush the "
+            "underlying store explicitly if that is truly intended"
+        )

fastplace_tenancy-0.1.0/src/fastplace_tenancy/context.py

@@ -0,0 +1,87 @@
+"""The company context — one contextvar every isolation layer reads.
+
+The bound company is request-scoped state, exactly like the ORM's
+session scope: the middleware binds it per request, ``company_context()``
+binds it for scripts/tests/jobs, and everything else only *reads* it.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from contextvars import ContextVar, Token
+from typing import Any
+
+from fastplace.errors import FastplaceError
+
+_current_company_id: ContextVar[Any | None] = ContextVar("fastplace_company_id", default=None)
+
+
+def current_company_id() -> Any | None:
+    """The company bound to this task — ``None`` when no context is active."""
+    return _current_company_id.get()
+
+
+def require_company_context() -> Any:
+    """The bound company, or :class:`MissingCompanyContext` when absent.
+
+    Fail-closed is deliberate: a company-scoped query with no company bound
+    is a missing tenant, not "every tenant" — the latter is a data breach
+    wearing a default's clothing.
+    """
+    company_id = _current_company_id.get()
+    if company_id is None:
+        raise MissingCompanyContext(
+            "no company context is bound — wrap the work in company_context(id) "
+            "or register CompanyContextMiddleware"
+        )
+    return company_id
+
+
+@asynccontextmanager
+async def company_context(company_id: Any) -> AsyncIterator[None]:
+    """Bind ``company_id`` for the block; restore the previous binding on exit.
+
+    Nestable (an inner block shadows, the outer binding returns) and
+    exception-safe — a failing inner block never leak a stale binding.
+    """
+    token: Token[Any | None] = _current_company_id.set(company_id)
+    try:
+        yield
+    finally:
+        _current_company_id.reset(token)
+
+
+def reset_company_context() -> None:
+    """Clear any binding — test isolation and CLI/boot boundaries."""
+    _current_company_id.set(None)
+
+
+class TenancyError(FastplaceError):
+    """Base for package errors — rides the kernel's JSON error translation."""
+
+    status_code = 400
+
+
+class MissingCompanyContext(TenancyError):
+    """A company-scoped operation ran with no company bound."""
+
+    status_code = 400
+
+
+class NotCompanyMember(TenancyError):
+    """The actor has no membership in the target company."""
+
+    status_code = 403
+
+
+class CompanyRoleRequired(TenancyError):
+    """The actor's membership lacks the role the operation demands."""
+
+    status_code = 403
+
+
+class RLSNotSupported(TenancyError):
+    """The active backend has no native Row-Level Security (capability gate)."""
+
+    status_code = 400