feat(tenancy): fail-closed isolation + tenants module (SaaS groundwork)

[antosubash]

Groundwork for running SaaS installs: tenant isolation now fails closed in the framework, and a new tenants module adds organisations, memberships (one user can belong to many) and invitations, plus the hooks a billing module will plug into. Billing itself is out of scope. Design: docs/plans/2026-09-27-saas-tenancy-design.md.

Closes #332, closes #343, closes #355, closes #356, closes #357, closes #358, closes #359, closes #363, closes #364, closes #365, closes #366.
Partly addresses #362 and #371 (details below).

Why

MultiTenantMixin existed, but tenancy was open by default:

• No model used the mixin.
• Queries with no tenant set returned every tenant's rows.
• ORM update()/delete() weren't tenant-scoped at all.
• A row could move to another tenant whenever no tenant was set.
• A signed-in user with no tenant could pick any tenant through the X-Tenant-ID header.
• Background jobs ran without a tenant.
• There was no tenant entity, and each user could belong to only one tenant.

Framework

• Strict isolation (MultiTenantMixin: reads with no tenant bound return every tenant's rows #355): strict mode is on whenever multi_tenant is on, and is stored per engine. A query or write on a tenant-scoped model with no tenant set raises MissingTenantError, a subclass of TenantIsolationError.
  • Code that deliberately spans tenants opts out with all_tenants() or execution_options(all_tenants=True).
  • Jobs and CLI commands act for one tenant with tenant_context(id). It takes effect even when nested inside all_tenants().
• Every statement shape is scoped (Soft-delete and tenant filters are silently skipped for selects that name no mapper (select(func.count()), subquery counts) #332):
  • Tenant criteria are attached for every tenant-scoped model, not only the one a query names, so joins, ORM exists()/in_()/scalar subqueries and count().select_from() are covered.
  • Core statements on Model.__table__ get an explicit predicate, and a bare Core exists().where(…) has its inner select rewritten.
  • With no tenant in strict mode, a direct reference raises and an indirect one matches nothing.
  • Behaviour change: soft-delete filtering now covers the same shapes. A soft-deleted row no longer shows up through a join, a subquery or a count. include_deleted=True still bypasses it.
• Every ORM write path is covered:
  • update() and delete() are tenant-scoped, and update().values(tenant_id=…) is refused.
  • insert(Model), bulk or with .values(), is stamped with the tenant and refused for a different tenant (MultiTenantMixin: bulk insert() is not stamped with tenant_id #357).
  • A flush that writes or deletes another tenant's object is refused. This covers objects returned from the session cache after a tenant switch.
• Tenant changes refused (MultiTenantMixin: unbound flush skips the tenant change check, letting a row move silently #356): changing a row's tenant_id is refused whether or not a tenant is set. Only code inside an all_tenants() block may move a row.
• Header rules (TenantMiddleware: header chooses the tenant for any authenticated user with no tenant #358, TenantMiddleware: the tenant header value is bound unvalidated, so an over-long or malformed header becomes a 500 on write #366): TenantMiddleware uses app.state.tenant_resolver when a module registers one. On the legacy path the header is honoured only for anonymous requests. Every tenant id taken from a request must match TENANT_ID_PATTERN.
• Single-tenant hosts (No default tenant setting or tenant_scope helper for MultiTenantMixin #359): HostSettings.default_tenant runs mixin tables as one tenant for requests and background tasks. It is ignored when multi_tenant is on.
• Deferred work (hosting: module middleware runs outside Tenant, so deferred work loses the tenant #364): db.on_commit callbacks and FastAPI BackgroundTasks already run inside the request's tenant (now tested). For work a module middleware defers past TenantMiddleware, bind_current_tenant(fn) captures the tenant when the work is queued and restores it when it runs. Middleware order is unchanged.
• background_tasks:
  • The enqueuing request's tenant is stamped on the Celery message and restored when the task runs. Request code cannot enqueue a task as another tenant.
  • The worker's sync session now has the tenant listeners and the host's multi_tenant setting (background_tasks: tenant-scope TaskExecution, and register the tenant listeners in the Celery worker process #371).
• Doctor check SM024: warns when a unique key on a tenant-scoped table doesn't include tenant_id.
• Postgres test runs (simple_module_test: fixtures hard-code in-memory SQLite, so a module suite cannot run on Postgres #343): SM_TEST_DATABASE_URL points the test fixtures at Postgres, and make test-py-pg runs the whole Python suite there. The schema is reset once per test, so app and db_session share the same data.

tenants module

• Tables: tenant, membership (unique on (tenant_id, user_id), role owner/admin/member) and invitation (stores only a SHA-256 of the token; can only be accepted by the invited email).
• Resolver: the session stores the preferred tenant, which is checked against a membership on every request.
  • The membership cache is dropped across workers through InvalidationBus, and a read already in flight cannot re-cache a removed member.
  • Suspended tenants resolve to no tenant, and the user is told which organisation was suspended.
  • The header selects a tenant only if the user is a member of it.
  • Subdomains (TenantMiddleware: anonymous tenant resolution is header only, no pluggable resolvers #363): with subdomain_base set, the tenant comes from the subdomain. It applies to anonymous visitors on public routes and to members, with their role, and never to a non-member on an authenticated route.
  • With tenants installed, a membership or role change applies on the next request, with no re-login (users: tenant changes are invisible until re login because UserContext is cached in the session #362).
• Per-tenant roles: the membership role becomes tenant:<role> for the active tenant only.
  • Management routes also require an owner or admin role in the active tenant, so a platform-wide permission alone doesn't make a plain member a manager.
  • Tenant-level routes always act on the active tenant, never on an id taken from the URL.
• Invariants that hold under concurrency:
  • The last-owner rule is enforced inside the UPDATE/DELETE itself, with a row lock on the tenant for Postgres.
  • Seat checks lock the tenant row.
  • Concurrent creates with the same slug, or accepts of the same invitation, return 409.
• Invitation links: built from the public_base_url setting, never from the Host header.
• Invitation rules: no accepting into a suspended tenant, and no re-inviting an existing member.
• Billing hooks: an EntitlementProvider (seat limits return 402), TenantService.set_status, and events published after commit.
• Pages: /tenants/, /tenants/members, /tenants/invitations/accept, /admin/tenants/.
• Migration: a new independent tenants branch.

QA

Five agents tested this in parallel. Each finding was verified before being fixed, and each fix has a regression test. 18 confirmed bugs, all fixed.

• Adversarial isolation: 10 bugs found and fixed:
  • tenant_context was ignored inside all_tenants().
  • update().values(tenant_id=…) could move rows to another tenant.
  • A cached object from another tenant could be written after a tenant switch.
  • The worker ran with no tenant enforcement.
  • A membership-cache race let a removed member keep access.
  • The last-owner and seat checks were check-then-act races.
  • Invitation links were built from the Host header.
  • A platform permission gave a plain member management rights in a tenant.
  • A second database connection setup turned strict mode off.
  • Invitations could be accepted into a suspended tenant.
• API functional (~100 cases): the slug format wasn't enforced, and concurrent writes returned 500s. The last-owner race was reproduced on a real SQLite file, which led to the atomic rule above.
• Browser E2E: 9 scenarios at desktop width and 375px. One bug: a suspended organisation was switched away from silently.
• Regression: full suite, all lint and typecheck gates, Alembic up/down/check, make doctor compared with main (no new warnings), production-mode boot with multi_tenant on and off, a real Celery run, and back-compat checks.
• Docs vs code: one wording fix.

Decisions for a reviewer

• Overlap with fix(db): close four silent data-correctness gaps in the DB layer (#332, #335, #336, #339) #344: both PRs restructure listeners.py, and fix(db): close four silent data-correctness gaps in the DB layer (#332, #335, #336, #339) #344 also fixes the soft-delete half of Soft-delete and tenant filters are silently skipped for selects that name no mapper (select(func.count()), subquery counts) #332, which this PR now covers too. Suggested order:
  1. Drop fix(db): close four silent data-correctness gaps in the DB layer (#332, #335, #336, #339) #344's Soft-delete and tenant filters are silently skipped for selects that name no mapper (select(func.count()), subquery counts) #332 part.
  2. Merge the rest of fix(db): close four silent data-correctness gaps in the DB layer (#332, #335, #336, #339) #344 (No supported way to hard-delete a SoftDeleteMixin row: session.delete() is silently rewritten to a soft delete, with no opt-out #335, get_db auto-commit ignores Core DML: a request whose only write is session.execute(update(...)) is rolled back at request end #336, SQLite engine is left at driver defaults: rollback journal, implicit 5 s busy timeout, foreign keys off #339).
  3. Merge main into this PR.
• Release: simple_module_tenants is added to the PyPI publish matrix.
• Behaviour change (strict mode): installs already running multi_tenant=True get strict mode. No bundled model uses the mixin.
• Behaviour change (soft delete): soft-deleted rows are hidden in joins, subqueries and counts, not only when a query names the model directly.
• Worker settings: the worker now resolves host settings with merge_host_settings() at start-up (scripts/run_worker.py).
• Filter overhead: measured at ~0.06–0.1 ms per query for tenant criteria on in-memory SQLite, plus ~10 µs for the exists() scan.

Not in this PR

• Module adoption:
  • Filed in this work: background_tasks: tenant-scope TaskExecution, and register the tenant listeners in the Celery worker process #371 (background_tasks, the model part), audit_log: tag AuditEntry with tenant_id and tenant-scope the browse/export screens #372 (audit_log), branding: no table to add a mixin to — it's a single process-global settings singleton that must become per-tenant lookup #373 (branding), dashboard: platform-wide stats cache and unscoped User counts need a tenant decision #374 (dashboard), feature_flags: tenant overrides already modeled, but no request-time dependency resolves the active tenant #375 (feature_flags), keycloak: stop hard-coding UserContext.tenant_id from the tenant_id JWT claim, and check register_setup_steps opt-out still holds #376 (keycloak), permissions: role→permission grants stay global, but must support mapping the synthetic tenant:<role> principal roles #377 (permissions), antosubash/smpy_modules#38 (pagebuilder), antosubash/smpy_modules#39 (news).
  • Already tracked before this: file_storage: StoredFile is not tenant scoped #361 (file_storage), users: no tenant management, UserCreate, UserUpdate and create_admin have no tenant_id #360 and users: tenant changes are invisible until re login because UserContext is cached in the session #362 (users), settings: on a multi-tenant host any tenant's admin can edit system-scope settings and any other tenant's tenant-scope settings #368 (settings).
• Postgres in CI: CI runs SQLite only; Postgres runs are local (make test-py-pg).
• Redundant markers: about 40 test files carry an unneeded @pytest.mark.anyio. Those markers are why make test-py-pg passes -p no:anyio; removing them is a separate cleanup.

Testing

• SQLite: 3,276 passed (CI green on 9eba456).
• Postgres 16: 3,277 passed, 0 failed via make test-py-pg.
  • The first Postgres run had 76 failures and errors, none from tenancy:
    • 73 were @pytest.mark.anyio tests running on a different event loop from their fixtures.
    • One was the fixture schema-reset bug fixed here.
    • Two were a test that relied on insert order.
• Concurrent last-owner test: 15/15 on file SQLite (was 4/12 before the fix) and 10/10 on Postgres.
• New tests:
  • DB: strict mode, DML scoping, statement shapes (joins, subqueries, counts, Core exists()), soft-delete shapes, the session cache, nested bypass blocks.
  • Middleware and header rules.
  • SM024.
  • Celery: tenant propagation and worker enforcement.
  • tenants: 42 tests, including subdomains and the concurrency test.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FB4wFRUXWGHY6qp8wtDJCE

[cloudflare-workers-and-pages]

Deploying simple-module-python with    Cloudflare Pages

Latest commit:	6741f8f
Status:	✅  Deploy successful!
Preview URL:	https://f7f4987d.simple-module-python.pages.dev
Branch Preview URL:	https://claude-saas-module-planning.simple-module-python.pages.dev

View logs