simple-module-tenants 0.0.35__tar.gz

simple_module_tenants-0.0.35/.gitignore

@@ -0,0 +1,66 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+*.egg
+
+# UV
+uv.lock
+
+# Node
+node_modules/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Environment
+.env
+
+# Database
+*.db
+*.sqlite3
+
+# Module-managed runtime state (e.g. uploaded dataset files,
+# default storage_dir for SM_DATASETS_STORAGE_DIR).
+var/
+
+# file_storage filesystem backend default root (override via SM_FILE_STORAGE_FS_ROOT_PATH).
+uploads/
+
+# Vite
+host/static/dist/
+
+# VitePress (docs)
+docs/.vitepress/cache/
+docs/.vitepress/dist/
+
+# Auto-generated frontend module manifest (regenerated by the host at boot
+# or via `make gen-pages`).
+host/client_app/modules.manifest.json
+host/client_app/modules.generated.ts
+host/client_app/modules.generated.css
+host/client_app/modules.assets.json
+
+# Worktrees
+.worktrees/
+
+# Performance profiles
+.memray/
+.benchmarks/
+
+# OS
+.DS_Store
+Thumbs.db
+
+.playwright-cli/*
+.playwright-mcp/*
+host/client_app/.playwright-cli/*
+.superpowers/
+.qa/
+.verify/

simple_module_tenants-0.0.35/LICENSE

@@ -0,0 +1,19 @@
+MIT License
+
+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.

simple_module_tenants-0.0.35/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.5
+Name: simple_module_tenants
+Version: 0.0.35
+Summary: Organisations, memberships and tenant resolution for simple_module SaaS installs
+Project-URL: Homepage, https://github.com/antosubash/simple_module_python
+Project-URL: Repository, https://github.com/antosubash/simple_module_python
+Project-URL: Issues, https://github.com/antosubash/simple_module_python/issues
+Project-URL: Changelog, https://github.com/antosubash/simple_module_python/blob/main/CHANGELOG.md
+Author-email: Anto Subash <antosubash@live.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: simple-module,tenants
+Requires-Python: >=3.12
+Requires-Dist: cachetools>=5.3
+Requires-Dist: simple-module-auth==0.0.35
+Requires-Dist: simple-module-core==0.0.35
+Requires-Dist: simple-module-db==0.0.35
+Requires-Dist: simple-module-hosting==0.0.35
+Requires-Dist: simple-module-inertia==0.0.35
+Requires-Dist: simple-module-settings==0.0.35
+Description-Content-Type: text/markdown
+
+# simple_module_tenants
+
+Organisations for [simple_module](https://github.com/antosubash/simple_module_python)
+SaaS installs: tenants, many-to-many memberships with per-tenant roles,
+email-bound invitations, and the tenant resolver that scopes every request.
+
+## Install
+
+```bash
+pip install simple_module_tenants
+```
+
+Add `simple_module_tenants` to your host's dependencies, then turn on
+`multi_tenant` (Settings screen, or `SM_MULTI_TENANT=true`) and restart.
+Without `multi_tenant` the module manages organisations but requests are not
+scoped to them.
+
+## What it does
+
+- **Resolution.** Registers `app.state.tenant_resolver`. The session stores
+  the user's chosen tenant; every request re-validates it against a
+  membership (cached per process, dropped across workers through
+  `InvalidationBus`). Suspended tenants resolve to nothing.
+- **Per-tenant roles.** A membership role (`owner`, `admin`, `member`) is added
+  to the principal as `tenant:<role>` for the active tenant only, so tenant
+  roles never reach platform permissions.
+- **Fail-closed handling.** With `multi_tenant` on, a tenant-scoped query
+  with no tenant raises `TenantIsolationError`; this module turns that into a
+  redirect to `/tenants` (pages) or a `403 tenant_required` (API).
+
+## Usage
+
+| Route | Permission | Purpose |
+|---|---|---|
+| `GET /tenants/` | signed in | My organisations: switch, create |
+| `GET /tenants/members` | `tenants.members.view` | Members and invitations of the active tenant |
+| `GET /tenants/invitations/accept?token=` | signed in | Accept an invitation |
+| `GET /admin/tenants/` | `tenants.platform.view` | Platform list of all tenants |
+| `GET/POST /api/tenants/` | signed in | List mine / create |
+| `POST /api/tenants/{id}/switch` | member of `{id}` | Change the active tenant |
+| `/api/tenants/current/members[/{user_id}]` | `tenants.members.view` / `.manage` | List, change role, remove |
+| `DELETE /api/tenants/current/membership` | member | Leave (not the last owner) |
+| `/api/tenants/current/invitations[/{id}]` | `tenants.members.manage` | List, invite, revoke |
+| `POST /api/tenants/invitations/accept` | signed in as the invited email | Join |
+| `POST /api/tenants/admin/{id}/suspend` · `/reactivate` | `tenants.platform.manage` | Lifecycle |
+
+Tenant-level routes act on the *active* tenant (`/current`), never on an id
+from the URL.
+
+## Configuration
+
+DB-backed (Settings screen):
+
+- `allow_self_service` (default on) — any signed-in user may create an
+  organisation.
+- `invitation_ttl_hours` (default 72).
+- `subdomain_base` (default empty) — with `example.com`, `acme.example.com`
+  resolves to the tenant whose slug is `acme`. Members get their role there;
+  anonymous visitors and signed-in non-members get the tenant on **public
+  routes only**; an unknown or suspended subdomain resolves to nothing.
+- `public_base_url` (default empty) — origin invitation links are built on.
+  Empty makes them root-relative: they are never built from the request's
+  `Host` header, because the same link travels in `InvitationCreated` for a
+  mailer to send.
+
+Management routes need both the permission and an owner/admin role *in the
+active tenant*: a platform-wide grant does not make a plain member of a tenant
+its manager (`403 tenant_manager_required`).
+
+## Billing seams
+
+The module ships no billing, but a billing module needs nothing more from it:
+
+- `app.state.tenants.entitlements` — replace the default `UnlimitedEntitlements`
+  with an `EntitlementProvider` (`limit(tenant_id, key)`,
+  `has_feature(tenant_id, key)`). The module enforces `tenants.seats` on new
+  members and invitations; `EntitlementExceededError` maps to HTTP 402.
+- `TenantService.set_status(tenant_id, TenantStatus.SUSPENDED | ACTIVE)` for
+  dunning.
+- Events, published after commit: `TenantCreated`, `TenantStatusChanged`,
+  `MembershipAdded`, `MembershipRemoved`, `InvitationCreated` (also the hook a
+  mailer uses to deliver the invitation link).

simple_module_tenants-0.0.35/README.md

@@ -0,0 +1,82 @@
+# simple_module_tenants
+
+Organisations for [simple_module](https://github.com/antosubash/simple_module_python)
+SaaS installs: tenants, many-to-many memberships with per-tenant roles,
+email-bound invitations, and the tenant resolver that scopes every request.
+
+## Install
+
+```bash
+pip install simple_module_tenants
+```
+
+Add `simple_module_tenants` to your host's dependencies, then turn on
+`multi_tenant` (Settings screen, or `SM_MULTI_TENANT=true`) and restart.
+Without `multi_tenant` the module manages organisations but requests are not
+scoped to them.
+
+## What it does
+
+- **Resolution.** Registers `app.state.tenant_resolver`. The session stores
+  the user's chosen tenant; every request re-validates it against a
+  membership (cached per process, dropped across workers through
+  `InvalidationBus`). Suspended tenants resolve to nothing.
+- **Per-tenant roles.** A membership role (`owner`, `admin`, `member`) is added
+  to the principal as `tenant:<role>` for the active tenant only, so tenant
+  roles never reach platform permissions.
+- **Fail-closed handling.** With `multi_tenant` on, a tenant-scoped query
+  with no tenant raises `TenantIsolationError`; this module turns that into a
+  redirect to `/tenants` (pages) or a `403 tenant_required` (API).
+
+## Usage
+
+| Route | Permission | Purpose |
+|---|---|---|
+| `GET /tenants/` | signed in | My organisations: switch, create |
+| `GET /tenants/members` | `tenants.members.view` | Members and invitations of the active tenant |
+| `GET /tenants/invitations/accept?token=` | signed in | Accept an invitation |
+| `GET /admin/tenants/` | `tenants.platform.view` | Platform list of all tenants |
+| `GET/POST /api/tenants/` | signed in | List mine / create |
+| `POST /api/tenants/{id}/switch` | member of `{id}` | Change the active tenant |
+| `/api/tenants/current/members[/{user_id}]` | `tenants.members.view` / `.manage` | List, change role, remove |
+| `DELETE /api/tenants/current/membership` | member | Leave (not the last owner) |
+| `/api/tenants/current/invitations[/{id}]` | `tenants.members.manage` | List, invite, revoke |
+| `POST /api/tenants/invitations/accept` | signed in as the invited email | Join |
+| `POST /api/tenants/admin/{id}/suspend` · `/reactivate` | `tenants.platform.manage` | Lifecycle |
+
+Tenant-level routes act on the *active* tenant (`/current`), never on an id
+from the URL.
+
+## Configuration
+
+DB-backed (Settings screen):
+
+- `allow_self_service` (default on) — any signed-in user may create an
+  organisation.
+- `invitation_ttl_hours` (default 72).
+- `subdomain_base` (default empty) — with `example.com`, `acme.example.com`
+  resolves to the tenant whose slug is `acme`. Members get their role there;
+  anonymous visitors and signed-in non-members get the tenant on **public
+  routes only**; an unknown or suspended subdomain resolves to nothing.
+- `public_base_url` (default empty) — origin invitation links are built on.
+  Empty makes them root-relative: they are never built from the request's
+  `Host` header, because the same link travels in `InvitationCreated` for a
+  mailer to send.
+
+Management routes need both the permission and an owner/admin role *in the
+active tenant*: a platform-wide grant does not make a plain member of a tenant
+its manager (`403 tenant_manager_required`).
+
+## Billing seams
+
+The module ships no billing, but a billing module needs nothing more from it:
+
+- `app.state.tenants.entitlements` — replace the default `UnlimitedEntitlements`
+  with an `EntitlementProvider` (`limit(tenant_id, key)`,
+  `has_feature(tenant_id, key)`). The module enforces `tenants.seats` on new
+  members and invitations; `EntitlementExceededError` maps to HTTP 402.
+- `TenantService.set_status(tenant_id, TenantStatus.SUSPENDED | ACTIVE)` for
+  dunning.
+- Events, published after commit: `TenantCreated`, `TenantStatusChanged`,
+  `MembershipAdded`, `MembershipRemoved`, `InvitationCreated` (also the hook a
+  mailer uses to deliver the invitation link).

simple_module_tenants-0.0.35/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@simple-module-py/tenants",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Frontend assets for the Tenants module",
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "@inertiajs/react": "^3.7.0",
+    "@simple-module-py/ui": "*"
+  },
+  "devDependencies": {
+    "@simple-module-py/tsconfig": "*"
+  },
+  "dependencies": {
+    "lucide-react": "^1.43.0",
+    "sonner": "^2.0.8"
+  }
+}

simple_module_tenants-0.0.35/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "simple_module_tenants"
+version = "0.0.35"
+description = "Organisations, memberships and tenant resolution for simple_module SaaS installs"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+authors = [{ name = "Anto Subash", email = "antosubash@live.com" }]
+keywords = ["simple-module", "tenants"]
+dependencies = [
+    "simple_module_core==0.0.35",
+    "simple_module_db==0.0.35",
+    "simple_module_hosting==0.0.35",
+    "simple_module_inertia==0.0.35",
+    "simple_module_settings==0.0.35",
+    "simple_module_auth==0.0.35",
+    "cachetools>=5.3",
+]
+
+[project.entry-points.simple_module]
+tenants = "tenants.module:TenantsModule"
+
+[project.urls]
+Homepage = "https://github.com/antosubash/simple_module_python"
+Repository = "https://github.com/antosubash/simple_module_python"
+Issues = "https://github.com/antosubash/simple_module_python/issues"
+Changelog = "https://github.com/antosubash/simple_module_python/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+# The distribution name (simple_module_tenants) doesn't match the package
+# directory (tenants), so hatchling can't infer what to ship — without
+# this the wheel builds empty and the entry point fails to import.
+[tool.hatch.build.targets.wheel]
+packages = ["tenants"]
+
+# Ship the module-root package.json inside the wheel so the host can
+# discover JS deps via importlib.resources after a pip install.
+[tool.hatch.build.targets.wheel.force-include]
+"package.json" = "tenants/package.json"
+
+[tool.uv.sources]
+simple_module_core = { workspace = true }
+simple_module_db = { workspace = true }
+simple_module_hosting = { workspace = true }
+simple_module_inertia = { workspace = true }
+simple_module_settings = { workspace = true }
+simple_module_auth = { workspace = true }

simple_module_tenants-0.0.35/tenants/__init__.py

@@ -0,0 +1 @@
+"""Tenants module."""

simple_module_tenants-0.0.35/tenants/_owner_guard.py

@@ -0,0 +1,68 @@
+"""Owner-safe demotion and removal: the "at least one owner" rule, atomically.
+
+Counting owners and then writing is a check-then-act race: two owners
+demoting each other at once both see two owners and both succeed, leaving a
+tenant nobody can ever administer again. So the rule lives in the write
+itself — the UPDATE/DELETE only matches while *another* owner exists, and
+zero affected rows means "this was the last owner".
+
+On SQLite writers serialise and the condition is evaluated at write time,
+which settles it. On Postgres (READ COMMITTED) two writes to different rows
+would not block each other, so callers also hold the tenant row lock
+(``TenantService.lock``) — the second request waits for the first to commit
+and then evaluates the condition against it.
+"""
+
+from __future__ import annotations
+
+from simple_module_db.listeners import SESSION_HAS_WRITES_KEY
+from sqlalchemy import delete, exists, update
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import aliased
+
+from tenants.constants import MembershipRole
+from tenants.models import Membership
+
+
+def _another_owner(membership: Membership):
+    other = aliased(Membership)
+    return exists().where(
+        other.tenant_id == membership.tenant_id,
+        other.role == MembershipRole.OWNER,
+        other.id != membership.id,
+    )
+
+
+async def demote_owner(db: AsyncSession, membership: Membership, role: str) -> bool:
+    """Set ``role`` on an owner's membership unless they are the last owner."""
+    stmt = (
+        update(Membership)
+        .where(Membership.id == membership.id, _another_owner(membership))
+        .values(role=role)
+        .execution_options(synchronize_session=False)
+    )
+    applied = (await db.execute(stmt)).rowcount == 1
+    if applied:
+        _mark_written(db)
+        await db.refresh(membership)
+    return applied
+
+
+async def remove_owner(db: AsyncSession, membership: Membership) -> bool:
+    """Delete an owner's membership unless they are the last owner."""
+    stmt = (
+        delete(Membership)
+        .where(Membership.id == membership.id, _another_owner(membership))
+        .execution_options(synchronize_session=False)
+    )
+    applied = (await db.execute(stmt)).rowcount == 1
+    if applied:
+        _mark_written(db)
+        db.expunge(membership)
+    return applied
+
+
+def _mark_written(db: AsyncSession) -> None:
+    # A Core-style statement is not a flush, so the request session would
+    # otherwise roll it back as a read-only request (#336).
+    db.sync_session.info[SESSION_HAS_WRITES_KEY] = True

simple_module_tenants-0.0.35/tenants/components/AdminTenantsTable.tsx

@@ -0,0 +1,116 @@
+import { keys, useT } from '@simple-module-py/i18n';
+import { Badge } from '@simple-module-py/ui/components/ui/badge';
+import { Button } from '@simple-module-py/ui/components/ui/button';
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '@simple-module-py/ui/components/ui/table';
+import { useState } from 'react';
+import { toast } from 'sonner';
+import { useTenantErrors } from '../hooks/useTenantErrors';
+
+export interface AdminTenant {
+  id: string;
+  slug: string;
+  name: string;
+  status: 'active' | 'suspended';
+  created_at: string | null;
+  members: number;
+}
+
+interface Props {
+  tenants: AdminTenant[];
+  onChanged: () => void;
+}
+
+const STATUS_KEY = keys.tenants.status;
+
+/** The platform-wide organisation roster on the admin Browse page. */
+export function AdminTenantsTable({ tenants, onChanged }: Props) {
+  const { t } = useT();
+  const { describe } = useTenantErrors();
+  const [busyId, setBusyId] = useState<string | null>(null);
+
+  async function setStatus(tenant: AdminTenant, action: 'suspend' | 'reactivate') {
+    setBusyId(tenant.id);
+    try {
+      const response = await fetch(`/api/tenants/admin/${tenant.id}/${action}`, {
+        method: 'POST',
+        credentials: 'same-origin',
+      });
+      if (!response.ok) {
+        toast.error(await describe(response));
+        return;
+      }
+      toast.success(
+        action === 'suspend'
+          ? t(keys.tenants.admin.toast_suspended)
+          : t(keys.tenants.admin.toast_reactivated),
+      );
+      onChanged();
+    } catch {
+      toast.error(t(keys.tenants.admin.toast_action_failed));
+    } finally {
+      setBusyId(null);
+    }
+  }
+
+  return (
+    <Table>
+      <TableHeader>
+        <TableRow>
+          <TableHead>{t(keys.tenants.admin.table_name)}</TableHead>
+          <TableHead>{t(keys.tenants.admin.table_slug)}</TableHead>
+          <TableHead>{t(keys.tenants.admin.table_status)}</TableHead>
+          <TableHead>{t(keys.tenants.admin.table_members)}</TableHead>
+          <TableHead>{t(keys.tenants.admin.table_created)}</TableHead>
+          <TableHead className="text-right">{t(keys.tenants.admin.table_actions)}</TableHead>
+        </TableRow>
+      </TableHeader>
+      <TableBody>
+        {tenants.map((tenant) => (
+          <TableRow key={tenant.id}>
+            <TableCell className="font-medium">{tenant.name}</TableCell>
+            <TableCell className="text-muted-foreground">{tenant.slug}</TableCell>
+            <TableCell>
+              <Badge variant={tenant.status === 'active' ? 'secondary' : 'destructive'}>
+                {t(STATUS_KEY[tenant.status])}
+              </Badge>
+            </TableCell>
+            <TableCell>{tenant.members}</TableCell>
+            <TableCell className="text-muted-foreground">
+              {tenant.created_at ? new Date(tenant.created_at).toLocaleDateString() : '—'}
+            </TableCell>
+            <TableCell className="text-right">
+              {tenant.status === 'active' ? (
+                <Button
+                  variant="outline"
+                  size="sm"
+                  className="max-lg:min-h-11"
+                  disabled={busyId === tenant.id}
+                  onClick={() => setStatus(tenant, 'suspend')}
+                >
+                  {t(keys.tenants.admin.suspend_button)}
+                </Button>
+              ) : (
+                <Button
+                  variant="outline"
+                  size="sm"
+                  className="max-lg:min-h-11"
+                  disabled={busyId === tenant.id}
+                  onClick={() => setStatus(tenant, 'reactivate')}
+                >
+                  {t(keys.tenants.admin.reactivate_button)}
+                </Button>
+              )}
+            </TableCell>
+          </TableRow>
+        ))}
+      </TableBody>
+    </Table>
+  );
+}

simple_module_tenants-0.0.35/tenants/components/CreateOrgForm.tsx

@@ -0,0 +1,90 @@
+import { keys, useT } from '@simple-module-py/i18n';
+import { Button } from '@simple-module-py/ui/components/ui/button';
+import { Card, CardContent, CardHeader, CardTitle } from '@simple-module-py/ui/components/ui/card';
+import { Input } from '@simple-module-py/ui/components/ui/input';
+import { Label } from '@simple-module-py/ui/components/ui/label';
+import type React from 'react';
+import { useState } from 'react';
+import { useTenantErrors } from '../hooks/useTenantErrors';
+
+interface Props {
+  /** Called after the API confirms creation, so the page can reload its props. */
+  onCreated: () => void;
+}
+
+/** The self-service "create an organisation" form on the Index page. */
+export function CreateOrgForm({ onCreated }: Props) {
+  const { t } = useT();
+  const { describe } = useTenantErrors();
+  const [name, setName] = useState('');
+  const [slug, setSlug] = useState('');
+  const [submitting, setSubmitting] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  async function handleSubmit(e: React.FormEvent) {
+    e.preventDefault();
+    setSubmitting(true);
+    setError(null);
+    try {
+      const response = await fetch('/api/tenants/', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        credentials: 'same-origin',
+        body: JSON.stringify({ name, slug: slug || undefined }),
+      });
+      if (!response.ok) {
+        setError(await describe(response));
+        return;
+      }
+      setName('');
+      setSlug('');
+      onCreated();
+    } catch {
+      setError(t(keys.tenants.errors.generic));
+    } finally {
+      setSubmitting(false);
+    }
+  }
+
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>{t(keys.tenants.index.create_title)}</CardTitle>
+      </CardHeader>
+      <CardContent>
+        <form onSubmit={handleSubmit} className="space-y-4">
+          <div className="space-y-1.5">
+            <Label htmlFor="org-name">{t(keys.tenants.index.create_name_label)}</Label>
+            <Input
+              id="org-name"
+              value={name}
+              onChange={(e) => setName(e.target.value)}
+              placeholder={t(keys.tenants.index.create_name_placeholder)}
+              required
+              maxLength={200}
+            />
+          </div>
+          <div className="space-y-1.5">
+            <Label htmlFor="org-slug">{t(keys.tenants.index.create_slug_label)}</Label>
+            <Input
+              id="org-slug"
+              value={slug}
+              onChange={(e) => setSlug(e.target.value.toLowerCase())}
+              placeholder={t(keys.tenants.index.create_slug_placeholder)}
+              maxLength={50}
+            />
+            <p className="text-xs text-muted-foreground">
+              {t(keys.tenants.index.create_slug_hint)}
+            </p>
+          </div>
+          {error && <p className="text-sm text-destructive">{error}</p>}
+          <Button type="submit" disabled={submitting || !name.trim()} className="max-lg:min-h-11">
+            {submitting
+              ? t(keys.tenants.index.create_submitting)
+              : t(keys.tenants.index.create_submit)}
+          </Button>
+        </form>
+      </CardContent>
+    </Card>
+  );
+}