simple-module-sharing 0.0.38__py3-none-any.whl

sharing/audience.py

@@ -0,0 +1,44 @@
+"""Which user ids a request may act on or name: the active tenant's members.
+
+On a multi-tenant app a grantee, and any user label shown, must belong to the
+active tenant; otherwise ``sharing`` would let a caller share with (and probe
+for) accounts in other tenants and read their directory labels. Membership is
+asked through ``simple_module_core.tenancy.tenant_member_ids`` (the
+``tenants`` module publishes it), so this module never imports ``tenants``.
+With no active tenant, or no membership store installed, nobody is in the
+audience (fail closed). A single-tenant app has no such boundary.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Collection
+from typing import Any
+
+from simple_module_core.tenancy import TenancyMode, tenant_member_ids
+from simple_module_db.tenancy import current_tenant_id
+from simple_module_hosting.tenancy import tenancy_mode
+
+
+class Audience:
+    """Filters user ids down to those the current request may see."""
+
+    def __init__(self, app: Any, db: Any) -> None:
+        self.app = app
+        self.db = db
+
+    async def visible(self, user_ids: Collection[str]) -> set[str]:
+        wanted = {uid for uid in user_ids if uid}
+        if not wanted or tenancy_mode(self.app) is not TenancyMode.MULTI:
+            return wanted
+        tenant_id = current_tenant_id.get()
+        if tenant_id is None:
+            return set()
+        members = await tenant_member_ids(self.app, self.db, tenant_id, wanted)
+        return members or set()
+
+
+class OpenAudience:
+    """Everyone is visible (single-tenant use, or tests without an app)."""
+
+    async def visible(self, user_ids: Collection[str]) -> set[str]:
+        return {uid for uid in user_ids if uid}

sharing/constants.py

@@ -0,0 +1,65 @@
+"""Stable identifiers for the sharing module."""
+
+from __future__ import annotations
+
+from typing import Final
+
+from simple_module_core.resources import ACTION_EDIT, ACTION_VIEW
+
+MODULE_NAME: Final = "Sharing"
+MODULE_PACKAGE: Final = "sharing"
+LOCALE_NAMESPACE: Final = "sharing"
+
+PERM_GROUP: Final = "Sharing"
+PERM_SHARE: Final = "sharing.share"
+"""Use the grant/revoke API at all; the resource's own policy still decides."""
+PERM_VIEW: Final = "sharing.view"
+"""See every share in the tenant (the admin page)."""
+PERM_MANAGE: Final = "sharing.manage"
+"""Revoke any share in the tenant."""
+USER_ROLE: Final = "user"
+
+PAGE_ADMIN: Final = "Sharing/Admin"
+
+API_PREFIX: Final = "/api/sharing"
+VIEW_PREFIX: Final = "/admin/sharing"
+# Trailing slash: the index route is registered at "/" under the prefix.
+ADMIN_URL: Final = f"{VIEW_PREFIX}/"
+AUDIT_URL_TEMPLATE: Final = f"{VIEW_PREFIX}/?share={{id}}"
+
+MENU_LABEL: Final = "Sharing"
+MENU_LABEL_KEY: Final = "sharing.nav.title"
+MENU_ICON: Final = "share"
+MENU_ORDER: Final = 60
+MENU_GROUP: Final = "Access"
+MENU_GROUP_KEY: Final = "ui.nav_groups.access"
+AUDIT_LABEL: Final = "Share"
+AUDIT_LABEL_KEY: Final = "sharing.audit.share"
+
+# Prefix is load-bearing: all modules share one schema.
+TABLE_SHARE: Final = "sharing_resource_share"
+UQ_SHARE: Final = "uq_sharing_resource_share_subject"
+IX_SHARE_RESOURCE: Final = "ix_sharing_resource_share_resource"
+
+RESOURCE_TYPE_MAX: Final = 100
+RESOURCE_ID_MAX: Final = 100
+SUBJECT_TYPE_MAX: Final = 16
+SUBJECT_ID_MAX: Final = 255
+ROLE_MAX: Final = 32
+
+SUBJECT_USER: Final = "user"
+"""The only subject kind so far; the column leaves room for groups or tenants."""
+
+# A role is the action it grants plus everything it implies.
+ROLE_IMPLIES: Final[dict[str, tuple[str, ...]]] = {
+    ACTION_VIEW: (ACTION_VIEW,),
+    ACTION_EDIT: (ACTION_VIEW, ACTION_EDIT),
+}
+
+ERR_UNKNOWN_TYPE: Final = "Unknown resource type"
+ERR_NOT_FOUND: Final = "Not found"
+ERR_FORBIDDEN: Final = "You may not share this resource"
+ERR_UNKNOWN_GRANTEE: Final = "Unknown user"
+ERR_BAD_ROLE: Final = "This role cannot be granted on this resource type"
+ERR_EXPIRED: Final = "expires_at must be in the future"
+ERR_SELF: Final = "You cannot share a resource with yourself"

sharing/contracts/__init__.py

@@ -0,0 +1,5 @@
+"""Sharing contracts — public interface for other modules."""
+
+from sharing.contracts.schemas import ShareGrant, ShareOut
+
+__all__ = ["ShareGrant", "ShareOut"]

sharing/contracts/schemas.py

@@ -0,0 +1,36 @@
+"""Sharing DTOs — the module's public surface."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+
+from simple_module_core.resources import ACTION_VIEW
+from sqlmodel import Field, SQLModel
+
+from sharing.constants import RESOURCE_ID_MAX, RESOURCE_TYPE_MAX, ROLE_MAX, SUBJECT_ID_MAX
+
+
+class ShareGrant(SQLModel):
+    """Grant (or update) one user's access to one resource."""
+
+    resource_type: str = Field(min_length=1, max_length=RESOURCE_TYPE_MAX)
+    resource_id: str = Field(min_length=1, max_length=RESOURCE_ID_MAX)
+    subject_id: str = Field(min_length=1, max_length=SUBJECT_ID_MAX)
+    role: str = Field(default=ACTION_VIEW, max_length=ROLE_MAX)
+    expires_at: datetime | None = None
+
+
+class ShareOut(SQLModel):
+    id: uuid.UUID
+    resource_type: str
+    resource_id: str
+    subject_type: str
+    subject_id: str
+    subject_label: str | None = None
+    role: str
+    granted_by: str
+    granted_by_label: str | None = None
+    expires_at: datetime | None = None
+    expired: bool = False
+    created_at: datetime | None = None

sharing/deps.py

@@ -0,0 +1,31 @@
+"""FastAPI dependencies for the sharing module."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import Depends, HTTPException, Request
+from simple_module_core.user_directory import get_user_directory
+from simple_module_db.deps import get_db
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from sharing.audience import Audience
+from sharing.service import SharingError, SharingService
+
+
+async def get_sharing_service(
+    request: Request, db: AsyncSession = Depends(get_db)
+) -> SharingService:
+    return SharingService(
+        db,
+        request.app.state.sm.resource_types,
+        get_user_directory(request.app),
+        Audience(request.app, db),
+    )
+
+
+SharingServiceDep = Annotated[SharingService, Depends(get_sharing_service)]
+
+
+def http_error(exc: SharingError) -> HTTPException:
+    return HTTPException(status_code=exc.status_code, detail=exc.detail)

sharing/endpoints/api.py

@@ -0,0 +1,69 @@
+"""REST API for shares — mounted under ``/api/sharing``.
+
+Gated on ``sharing.share`` (so an API token scoped to it may call these);
+the resource's own policy then decides per row.
+"""
+
+from __future__ import annotations
+
+import uuid
+
+from fastapi import APIRouter, Depends, Request
+from simple_module_core.resources import ResourcePrincipal
+from simple_module_core.user_directory import get_user_directory
+from simple_module_hosting.permissions import RequiresPermission
+from simple_module_hosting.resource_deps import resource_principal
+
+from sharing.constants import PERM_SHARE
+from sharing.contracts.schemas import ShareGrant, ShareOut
+from sharing.deps import SharingServiceDep, http_error
+from sharing.present import present_shares
+from sharing.service import SharingError
+
+router = APIRouter(prefix="/shares", dependencies=[Depends(RequiresPermission(PERM_SHARE))])
+
+
+@router.get("", response_model=list[ShareOut])
+async def list_shares(
+    request: Request,
+    resource_type: str,
+    resource_id: str,
+    service: SharingServiceDep,
+    who: ResourcePrincipal = Depends(resource_principal),
+) -> list[ShareOut]:
+    try:
+        shares = await service.for_resource(who, resource_type, resource_id)
+    except SharingError as exc:
+        raise http_error(exc) from None
+    return await present_shares(
+        get_user_directory(request.app), service.db, shares, service.audience
+    )
+
+
+@router.post("", response_model=ShareOut, status_code=201)
+async def grant_share(
+    request: Request,
+    data: ShareGrant,
+    service: SharingServiceDep,
+    who: ResourcePrincipal = Depends(resource_principal),
+) -> ShareOut:
+    try:
+        share = await service.grant(who, data)
+    except SharingError as exc:
+        raise http_error(exc) from None
+    (out,) = await present_shares(
+        get_user_directory(request.app), service.db, [share], service.audience
+    )
+    return out
+
+
+@router.delete("/{share_id}", status_code=204)
+async def revoke_share(
+    share_id: uuid.UUID,
+    service: SharingServiceDep,
+    who: ResourcePrincipal = Depends(resource_principal),
+) -> None:
+    try:
+        await service.revoke(who, share_id)
+    except SharingError as exc:
+        raise http_error(exc) from None

sharing/endpoints/views.py

@@ -0,0 +1,75 @@
+"""The admin page — mounted under ``/admin/sharing``."""
+
+from __future__ import annotations
+
+import uuid
+
+from fastapi import APIRouter, Depends, Request
+from simple_module_core.resources import ResourcePrincipal
+from simple_module_core.user_directory import get_user_directory
+from simple_module_db import TenantIsolationError, paginate
+from simple_module_hosting.inertia_deps import InertiaDep
+from simple_module_hosting.pagination import LenientPageParamsDep
+from simple_module_hosting.permissions import RequiresPermission
+from simple_module_hosting.resource_deps import resource_principal
+from simple_module_inertia import InertiaResponse
+from sqlmodel import col, select
+from starlette.responses import RedirectResponse
+
+from sharing.constants import ADMIN_URL, PAGE_ADMIN, PERM_MANAGE, PERM_VIEW
+from sharing.deps import SharingServiceDep, http_error
+from sharing.models import ResourceShare
+from sharing.present import present_shares
+from sharing.service import SharingError
+
+router = APIRouter()
+
+
+@router.get("/", response_model=None, dependencies=[Depends(RequiresPermission(PERM_VIEW))])
+async def admin_index(
+    request: Request,
+    inertia: InertiaDep,
+    service: SharingServiceDep,
+    params: LenientPageParamsDep,
+    who: ResourcePrincipal = Depends(resource_principal),
+) -> InertiaResponse:
+    stmt = select(ResourceShare).order_by(
+        col(ResourceShare.created_at).desc(), col(ResourceShare.id)
+    )
+    try:
+        page = await paginate(service.db, stmt, params)
+        shares = await present_shares(
+            get_user_directory(request.app), service.db, page.items, service.audience
+        )
+        total, served, tenant_required = page.total, page.page, False
+    except TenantIsolationError:
+        # Strict tenancy with no active tenant: nothing to list.
+        shares, total, served, tenant_required = [], 0, 1, True
+    return await inertia.render(
+        PAGE_ADMIN,
+        {
+            "shares": [s.model_dump(mode="json") for s in shares],
+            "total": total,
+            "page": served,
+            "per_page": params.per_page,
+            "can_revoke": who.has(PERM_MANAGE),
+            "tenant_required": tenant_required,
+        },
+    )
+
+
+@router.post(
+    "/{share_id}/revoke",
+    response_model=None,
+    dependencies=[Depends(RequiresPermission(PERM_MANAGE))],
+)
+async def admin_revoke(
+    share_id: uuid.UUID,
+    service: SharingServiceDep,
+    who: ResourcePrincipal = Depends(resource_principal),
+) -> RedirectResponse:
+    try:
+        await service.revoke(who, share_id)
+    except SharingError as exc:
+        raise http_error(exc) from None
+    return RedirectResponse(ADMIN_URL, status_code=303)

sharing/locales/de.json

@@ -0,0 +1,33 @@
+{
+  "nav": {
+    "title": "Freigaben"
+  },
+  "permission_group": "Freigaben",
+  "audit": {
+    "share": "Freigabe"
+  },
+  "admin": {
+    "title": "Freigaben",
+    "description": "Wer in diesem Arbeitsbereich Zugriff auf welche Ressource erhalten hat.",
+    "tenant_required": "Wählen Sie einen Arbeitsbereich, um seine Freigaben zu sehen."
+  },
+  "list": {
+    "resource": "Ressource",
+    "subject": "Freigegeben für",
+    "role": "Rolle",
+    "granted_by": "Freigegeben von",
+    "expires": "Läuft ab",
+    "actions": "Aktionen",
+    "never": "Nie",
+    "expired": "Abgelaufen",
+    "revoke": "Widerrufen",
+    "empty_title": "Noch nichts freigegeben",
+    "empty_description": "Freigaben erscheinen hier, sobald jemand einer anderen Person Zugriff auf eine Ressource gibt."
+  },
+  "revoke": {
+    "title": "Diese Freigabe widerrufen?",
+    "description": "Die Person verliert sofort den Zugriff auf die Ressource.",
+    "confirm": "Widerrufen",
+    "cancel": "Abbrechen"
+  }
+}

sharing/locales/en.json

@@ -0,0 +1,33 @@
+{
+  "nav": {
+    "title": "Sharing"
+  },
+  "permission_group": "Sharing",
+  "audit": {
+    "share": "Share"
+  },
+  "admin": {
+    "title": "Shares",
+    "description": "Who has been given access to which resource in this workspace.",
+    "tenant_required": "Select a workspace to see its shares."
+  },
+  "list": {
+    "resource": "Resource",
+    "subject": "Shared with",
+    "role": "Role",
+    "granted_by": "Granted by",
+    "expires": "Expires",
+    "actions": "Actions",
+    "never": "Never",
+    "expired": "Expired",
+    "revoke": "Revoke",
+    "empty_title": "Nothing shared yet",
+    "empty_description": "Shares appear here when someone gives another user access to a resource."
+  },
+  "revoke": {
+    "title": "Revoke this share?",
+    "description": "The user loses access to the resource immediately.",
+    "confirm": "Revoke",
+    "cancel": "Cancel"
+  }
+}

sharing/models.py

@@ -0,0 +1,51 @@
+"""The generic share table (GH #526)."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+
+from simple_module_db.base import create_module_base
+from simple_module_db.mixins import AuditMixin, MultiTenantMixin
+from sqlalchemy import Index, UniqueConstraint
+from sqlmodel import Field
+
+from sharing.constants import (
+    IX_SHARE_RESOURCE,
+    RESOURCE_ID_MAX,
+    RESOURCE_TYPE_MAX,
+    ROLE_MAX,
+    SUBJECT_ID_MAX,
+    SUBJECT_TYPE_MAX,
+    SUBJECT_USER,
+    TABLE_SHARE,
+    UQ_SHARE,
+)
+
+Base = create_module_base("sharing")
+
+
+class ResourceShare(Base, MultiTenantMixin, AuditMixin, table=True):  # ty: ignore[unsupported-base]
+    """One subject's access to one resource.
+
+    ``resource_id`` is the canonical text of the row's key (a UUID's ``hex``,
+    an int's decimal), so the policy's ``EXISTS`` can compare it on any
+    database. Revoking deletes the row; expiry is checked in SQL.
+    """
+
+    __tablename__ = TABLE_SHARE
+    __table_args__ = (
+        UniqueConstraint(
+            "tenant_id", "resource_type", "resource_id", "subject_type", "subject_id", name=UQ_SHARE
+        ),
+        Index(IX_SHARE_RESOURCE, "tenant_id", "resource_type", "resource_id"),
+    )
+
+    id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
+    resource_type: str = Field(max_length=RESOURCE_TYPE_MAX)
+    resource_id: str = Field(max_length=RESOURCE_ID_MAX)
+    subject_type: str = Field(default=SUBJECT_USER, max_length=SUBJECT_TYPE_MAX)
+    subject_id: str = Field(max_length=SUBJECT_ID_MAX, index=True)
+    role: str = Field(max_length=ROLE_MAX)
+    granted_by: str = Field(max_length=SUBJECT_ID_MAX)
+    expires_at: datetime | None = Field(default=None)

sharing/module.py

@@ -0,0 +1,86 @@
+"""Sharing module: a generic share table for resource-scoped access (GH #526)."""
+
+from __future__ import annotations
+
+import importlib.resources
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from simple_module_core import ModuleBase, ModuleMeta
+from simple_module_core.audit_links import AuditLink
+from simple_module_core.menu import MenuItem, MenuRegistry, MenuSection
+from simple_module_core.module_settings import register_module_settings
+from simple_module_core.tenancy import TenantRole, tenant_role
+
+from sharing import constants as c
+
+if TYPE_CHECKING:
+    from fastapi import APIRouter, FastAPI
+    from simple_module_core.audit_links import AuditLinkRegistry
+    from simple_module_core.permissions import PermissionRegistry
+
+
+class SharingModule(ModuleBase):
+    meta = ModuleMeta(
+        name=c.MODULE_NAME,
+        route_prefix=c.API_PREFIX,
+        view_prefix=c.VIEW_PREFIX,
+    )
+
+    def register_settings(self, app: FastAPI) -> None:
+        from sharing.services import SharingServices
+        from sharing.settings import SharingSettings
+
+        register_module_settings(
+            app, c.MODULE_PACKAGE, SharingSettings, lambda s: SharingServices(settings=s)
+        )
+
+    def register_routes(self, api_router: APIRouter, view_router: APIRouter) -> None:
+        from sharing.endpoints.api import router as api
+        from sharing.endpoints.views import router as views
+
+        api_router.include_router(api)
+        view_router.include_router(views)
+
+    def register_menu_items(self, registry: MenuRegistry) -> None:
+        registry.add(
+            MenuItem(
+                label=c.MENU_LABEL,
+                label_key=c.MENU_LABEL_KEY,
+                url=c.ADMIN_URL,
+                icon=c.MENU_ICON,
+                order=c.MENU_ORDER,
+                section=MenuSection.ADMIN_SIDEBAR,
+                group=c.MENU_GROUP,
+                group_key=c.MENU_GROUP_KEY,
+                permissions=[c.PERM_VIEW],
+            )
+        )
+
+    def register_permissions(self, registry: PermissionRegistry) -> None:
+        registry.add_group(
+            c.PERM_GROUP,
+            [c.PERM_SHARE, c.PERM_VIEW, c.PERM_MANAGE],
+            label_key=f"{c.LOCALE_NAMESPACE}.permission_group",
+        )
+        # Sharing what you own is an ordinary user action; the resource's
+        # policy (``can("share")``) is what actually decides.
+        registry.map_role(c.USER_ROLE, [c.PERM_SHARE])
+        for role in TenantRole:
+            registry.map_role(tenant_role(role), [c.PERM_SHARE])
+
+    def register_audit_links(self, registry: AuditLinkRegistry) -> None:
+        from sharing.models import ResourceShare
+
+        registry.register(
+            AuditLink.for_model(
+                ResourceShare,
+                url_template=c.AUDIT_URL_TEMPLATE,
+                label=c.AUDIT_LABEL,
+                label_key=c.AUDIT_LABEL_KEY,
+            )
+        )
+
+    def locale_dirs(self) -> dict[str, Path]:
+        base = Path(str(importlib.resources.files(__package__) / "locales"))
+        return {c.LOCALE_NAMESPACE: base}

sharing/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@simple-module-py/sharing",
+  "version": "0.0.38",
+  "private": true,
+  "description": "Frontend assets for the Sharing 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"
+  }
+}

sharing/pages/Admin.tsx

@@ -0,0 +1,100 @@
+import { Head, router } from '@inertiajs/react';
+import { keys, useT } from '@simple-module-py/i18n';
+import { ConfirmActionDialog } from '@simple-module-py/ui/components/ConfirmActionDialog';
+import { InlineBanner } from '@simple-module-py/ui/components/InlineBanner';
+import { PageShell } from '@simple-module-py/ui/components/PageShell';
+import { PaginationBar } from '@simple-module-py/ui/components/PaginationBar';
+import { AdminLayout } from '@simple-module-py/ui/layouts/AdminLayout';
+import { Building2, Trash2 } from 'lucide-react';
+import { useState } from 'react';
+import { ShareTable } from './components/ShareTable';
+import type { Share } from './types';
+
+interface Props {
+  shares: Share[];
+  total: number;
+  page: number;
+  per_page: number;
+  can_revoke: boolean;
+  tenant_required: boolean;
+}
+
+const BASE_URL = '/admin/sharing';
+
+/** Every share in the active tenant; admins may revoke any of them. */
+function Admin(props: Props) {
+  const { t } = useT();
+  const [pending, setPending] = useState<Share | null>(null);
+  const [busy, setBusy] = useState(false);
+  // An audit-log link lands here as ?share=<id>; mark that row.
+  const highlightId =
+    typeof window === 'undefined' ? null : new URLSearchParams(window.location.search).get('share');
+
+  function goTo(page: number) {
+    router.get(`${BASE_URL}/`, { page }, { preserveScroll: true });
+  }
+
+  function confirmRevoke() {
+    if (!pending) return;
+    setBusy(true);
+    router.post(
+      `${BASE_URL}/${pending.id}/revoke`,
+      {},
+      {
+        preserveScroll: true,
+        onFinish: () => {
+          setBusy(false);
+          setPending(null);
+        },
+      },
+    );
+  }
+
+  return (
+    <>
+      <Head title={t(keys.sharing.admin.title)} />
+      <PageShell
+        title={t(keys.sharing.admin.title)}
+        description={t(keys.sharing.admin.description)}
+      >
+        {props.tenant_required ? (
+          <InlineBanner
+            icon={Building2}
+            tone="warning"
+            title={t(keys.sharing.admin.tenant_required)}
+          />
+        ) : (
+          <>
+            <ShareTable
+              shares={props.shares}
+              canRevoke={props.can_revoke}
+              highlightId={highlightId}
+              onRevoke={setPending}
+            />
+            <PaginationBar
+              page={props.page}
+              perPage={props.per_page}
+              total={props.total}
+              onPageChange={goTo}
+              hideWhenSinglePage
+            />
+          </>
+        )}
+      </PageShell>
+      <ConfirmActionDialog
+        open={pending !== null}
+        onOpenChange={(open) => !open && setPending(null)}
+        icon={Trash2}
+        title={t(keys.sharing.revoke.title)}
+        description={t(keys.sharing.revoke.description)}
+        confirmLabel={t(keys.sharing.revoke.confirm)}
+        cancelLabel={t(keys.sharing.revoke.cancel)}
+        onConfirm={confirmRevoke}
+        busy={busy}
+      />
+    </>
+  );
+}
+
+Admin.layout = [AdminLayout];
+export default Admin;

sharing/pages/components/ShareTable.tsx

@@ -0,0 +1,86 @@
+import { keys, useT } from '@simple-module-py/i18n';
+import { EmptyState } from '@simple-module-py/ui/components/EmptyState';
+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 { formatDayMonthYear } from '@simple-module-py/ui/lib/date-format';
+import { Share2 } from 'lucide-react';
+import type { Share } from '../types';
+
+interface Props {
+  shares: Share[];
+  canRevoke: boolean;
+  highlightId?: string | null;
+  onRevoke: (share: Share) => void;
+}
+
+export function ShareTable({ shares, canRevoke, highlightId, onRevoke }: Props) {
+  const { t } = useT();
+  const never = t(keys.sharing.list.never);
+
+  if (shares.length === 0) {
+    return (
+      <EmptyState
+        icon={Share2}
+        title={t(keys.sharing.list.empty_title)}
+        description={t(keys.sharing.list.empty_description)}
+      />
+    );
+  }
+
+  return (
+    <div className="overflow-x-auto rounded-lg border">
+      <Table>
+        <TableHeader>
+          <TableRow>
+            <TableHead>{t(keys.sharing.list.resource)}</TableHead>
+            <TableHead>{t(keys.sharing.list.subject)}</TableHead>
+            <TableHead>{t(keys.sharing.list.role)}</TableHead>
+            <TableHead>{t(keys.sharing.list.granted_by)}</TableHead>
+            <TableHead>{t(keys.sharing.list.expires)}</TableHead>
+            {canRevoke && (
+              <TableHead className="text-right">{t(keys.sharing.list.actions)}</TableHead>
+            )}
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          {shares.map((share) => (
+            <TableRow key={share.id} data-state={highlightId === share.id ? 'selected' : undefined}>
+              <TableCell>
+                <div className="font-medium">{share.resource_type}</div>
+                <code className="text-xs text-muted-foreground">{share.resource_id}</code>
+              </TableCell>
+              <TableCell>{share.subject_label ?? share.subject_id}</TableCell>
+              <TableCell>
+                <Badge variant="secondary">{share.role}</Badge>
+              </TableCell>
+              <TableCell>{share.granted_by_label ?? share.granted_by}</TableCell>
+              <TableCell>
+                {formatDayMonthYear(share.expires_at, never)}
+                {share.expired && (
+                  <Badge variant="outline" className="ml-2">
+                    {t(keys.sharing.list.expired)}
+                  </Badge>
+                )}
+              </TableCell>
+              {canRevoke && (
+                <TableCell className="text-right">
+                  <Button variant="ghost" size="sm" onClick={() => onRevoke(share)}>
+                    {t(keys.sharing.list.revoke)}
+                  </Button>
+                </TableCell>
+              )}
+            </TableRow>
+          ))}
+        </TableBody>
+      </Table>
+    </div>
+  );
+}

sharing/pages/types.ts

@@ -0,0 +1,14 @@
+export interface Share {
+  id: string;
+  resource_type: string;
+  resource_id: string;
+  subject_type: string;
+  subject_id: string;
+  subject_label: string | null;
+  role: string;
+  granted_by: string;
+  granted_by_label: string | null;
+  expires_at: string | null;
+  expired: boolean;
+  created_at: string | null;
+}

sharing/policy.py

@@ -0,0 +1,109 @@
+"""Plug shares into a module's ``OwnedResourcePolicy`` (GH #526).
+
+::
+
+    from sharing.policy import share_exists_for
+
+    NOTE_POLICY = OwnedResourcePolicy(
+        Note.owner_id,
+        bypass_perm=PERM_NOTES_MANAGE,
+        share_exists=share_exists_for(NOTE_TYPE, Note.id),
+    )
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Callable
+from datetime import UTC, datetime
+from typing import Any
+
+from simple_module_core.resources import ResourcePrincipal
+from sqlalchemy import String, cast, func, inspect, or_
+from sqlmodel import exists, select
+
+from sharing.constants import ROLE_IMPLIES, SUBJECT_USER
+from sharing.models import ResourceShare
+
+
+def roles_granting(action: str) -> tuple[str, ...]:
+    """Every share role that implies *action*."""
+    return tuple(role for role, implied in ROLE_IMPLIES.items() if action in implied)
+
+
+def _is_uuid(column: Any) -> bool:
+    try:
+        return column.type.python_type is uuid.UUID
+    except (AttributeError, NotImplementedError):
+        return False
+
+
+def id_text(column: Any) -> Any:
+    """*column* rendered as the canonical text :func:`canonical_id` stores.
+
+    UUIDs become 32 lowercase hex digits on every dialect (Postgres casts with
+    hyphens, SQLite stores without), everything else its plain text.
+    """
+    text = cast(column, String)
+    if _is_uuid(column):
+        return func.replace(func.lower(text), "-", "")
+    return text
+
+
+def canonical_id(value: Any) -> str:
+    """The stored ``resource_id`` for a key value (matches :func:`id_text`)."""
+    if isinstance(value, uuid.UUID):
+        return value.hex
+    return str(value)
+
+
+def row_id(obj: Any) -> str:
+    """The canonical id of a loaded single-key row."""
+    identity = inspect(obj).identity
+    if not identity or len(identity) != 1:
+        raise ValueError("shared resources need a single-column primary key")
+    return canonical_id(identity[0])
+
+
+def active_share_clause(now: datetime | None = None) -> Any:
+    """Shares that have not expired, as of *now* (a bound value, not ``NOW()``)."""
+    moment = now or datetime.now(UTC)
+    return or_(ResourceShare.expires_at.is_(None), ResourceShare.expires_at > moment)
+
+
+def share_exists_for(
+    resource_type: str, id_col: Any
+) -> Callable[[ResourcePrincipal, str], Any | None]:
+    """A ``share_exists`` factory for ``OwnedResourcePolicy``.
+
+    Correlated on *id_col*; tenant scoping comes from the share table's
+    ``MultiTenantMixin`` filter, and expired shares never match.
+    """
+    key = id_text(id_col)
+
+    def share_exists(principal: ResourcePrincipal, action: str) -> Any | None:
+        roles = roles_granting(action)
+        if not roles or principal.user_id is None:
+            return None
+        return exists(
+            select(ResourceShare.id).where(
+                ResourceShare.resource_type == resource_type,
+                ResourceShare.resource_id == key,
+                ResourceShare.subject_type == SUBJECT_USER,
+                ResourceShare.subject_id == principal.user_id,
+                ResourceShare.role.in_(roles),
+                active_share_clause(),
+            )
+        )
+
+    return share_exists
+
+
+__all__ = [
+    "active_share_clause",
+    "canonical_id",
+    "id_text",
+    "roles_granting",
+    "row_id",
+    "share_exists_for",
+]

sharing/present.py

@@ -0,0 +1,49 @@
+"""Turn share rows into ``ShareOut`` with user labels from the directory."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from datetime import UTC, datetime
+from typing import Any
+
+from simple_module_core.user_directory import UserDirectory, resolve_user_labels
+
+from sharing.audience import Audience, OpenAudience
+from sharing.contracts.schemas import ShareOut
+from sharing.models import ResourceShare
+
+
+def _expired(share: ResourceShare, now: datetime) -> bool:
+    if share.expires_at is None:
+        return False
+    expires = share.expires_at
+    if expires.tzinfo is None:
+        expires = expires.replace(tzinfo=UTC)
+    return expires <= now
+
+
+async def present_shares(
+    directory: UserDirectory,
+    db: Any,
+    shares: Sequence[ResourceShare],
+    audience: Audience | OpenAudience,
+) -> list[ShareOut]:
+    """One batched directory lookup for every subject and granter on the page.
+
+    Only users in the request's *audience* (the active tenant's members) are
+    named; anyone else shows as their raw id, so no label crosses tenants.
+    """
+    ids = [s.subject_id for s in shares] + [s.granted_by for s in shares]
+    labels = await resolve_user_labels(directory, db, await audience.visible(ids))
+    now = datetime.now(UTC)
+    return [
+        ShareOut.model_validate(
+            share,
+            update={
+                "subject_label": labels.get(share.subject_id),
+                "granted_by_label": labels.get(share.granted_by),
+                "expired": _expired(share, now),
+            },
+        )
+        for share in shares
+    ]

sharing/service.py

@@ -0,0 +1,165 @@
+"""Grant, revoke and list shares (GH #526).
+
+Every grant is checked three ways: the resource type is registered, the
+granter passes the owning module's policy for ``share`` on that row, and the
+grantee is someone the user directory knows. Rows are tenant-scoped by
+``MultiTenantMixin``; revoking hard-deletes.
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import UTC, datetime
+from typing import Any
+
+from simple_module_core.resources import (
+    ACTION_SHARE,
+    ResourcePrincipal,
+    ResourceType,
+    ResourceTypeRegistry,
+)
+from simple_module_core.user_directory import UserDirectory
+from simple_module_db.resource_policy import load_authorized
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlmodel import select
+
+from sharing.audience import Audience, OpenAudience
+from sharing.constants import (
+    ERR_BAD_ROLE,
+    ERR_EXPIRED,
+    ERR_FORBIDDEN,
+    ERR_NOT_FOUND,
+    ERR_SELF,
+    ERR_UNKNOWN_GRANTEE,
+    ERR_UNKNOWN_TYPE,
+    PERM_MANAGE,
+    SUBJECT_USER,
+)
+from sharing.contracts.schemas import ShareGrant
+from sharing.models import ResourceShare
+from sharing.policy import row_id
+
+
+class SharingError(Exception):
+    """A refused share operation, with the HTTP status it maps to."""
+
+    def __init__(self, status_code: int, detail: str) -> None:
+        super().__init__(detail)
+        self.status_code = status_code
+        self.detail = detail
+
+
+def _aware(value: datetime) -> datetime:
+    return value if value.tzinfo is not None else value.replace(tzinfo=UTC)
+
+
+class SharingService:
+    def __init__(
+        self,
+        db: AsyncSession,
+        registry: ResourceTypeRegistry,
+        directory: UserDirectory,
+        audience: Audience | OpenAudience | None = None,
+    ) -> None:
+        self.db = db
+        self.registry = registry
+        self.directory = directory
+        self.audience = audience or OpenAudience()
+
+    def _type(self, name: str) -> ResourceType:
+        resource_type = self.registry.get(name)
+        if resource_type is None:
+            raise SharingError(422, ERR_UNKNOWN_TYPE)
+        return resource_type
+
+    async def _authorize(
+        self, principal: ResourcePrincipal, resource_type: ResourceType, resource_id: str
+    ) -> Any:
+        """The resource row if *principal* may share it: 404 if invisible, 403 if not."""
+        try:
+            stmt = resource_type.select_by_id(resource_id)
+        except ValueError:
+            raise SharingError(404, ERR_NOT_FOUND) from None
+        row, allowed = await load_authorized(
+            self.db, resource_type.policy, principal, ACTION_SHARE, stmt
+        )
+        if row is None:
+            raise SharingError(404, ERR_NOT_FOUND)
+        if not allowed:
+            raise SharingError(403, ERR_FORBIDDEN)
+        return row
+
+    async def grant(self, principal: ResourcePrincipal, data: ShareGrant) -> ResourceShare:
+        resource_type = self._type(data.resource_type)
+        if data.role not in resource_type.shareable_actions:
+            raise SharingError(422, ERR_BAD_ROLE)
+        if data.expires_at is not None and _aware(data.expires_at) <= datetime.now(UTC):
+            raise SharingError(422, ERR_EXPIRED)
+        row = await self._authorize(principal, resource_type, data.resource_id)
+        grantee = (await self.directory.get_many(self.db, [data.subject_id])).get(data.subject_id)
+        # One error for "no such user" and "not in your tenant": no enumeration.
+        if grantee is None or grantee.id not in await self.audience.visible([grantee.id]):
+            raise SharingError(422, ERR_UNKNOWN_GRANTEE)
+        if grantee.id == principal.user_id:
+            raise SharingError(422, ERR_SELF)
+        resource_id = row_id(row)
+        share = await self._existing(data.resource_type, resource_id, grantee.id)
+        if share is None:
+            share = ResourceShare(
+                resource_type=data.resource_type,
+                resource_id=resource_id,
+                subject_type=SUBJECT_USER,
+                subject_id=grantee.id,
+                role=data.role,
+                granted_by=principal.user_id or "",
+            )
+            self.db.add(share)
+        share.role = data.role
+        share.expires_at = data.expires_at
+        share.granted_by = principal.user_id or ""
+        await self.db.flush()
+        return share
+
+    async def _existing(self, rtype: str, rid: str, subject_id: str) -> ResourceShare | None:
+        stmt = select(ResourceShare).where(
+            ResourceShare.resource_type == rtype,
+            ResourceShare.resource_id == rid,
+            ResourceShare.subject_type == SUBJECT_USER,
+            ResourceShare.subject_id == subject_id,
+        )
+        return (await self.db.execute(stmt)).scalars().first()
+
+    async def revoke(self, principal: ResourcePrincipal, share_id: uuid.UUID) -> None:
+        """Delete a share: an admin, its grantee (leaving), or whoever may share the row."""
+        share = (
+            (await self.db.execute(select(ResourceShare).where(ResourceShare.id == share_id)))
+            .scalars()
+            .first()
+        )
+        if share is None:
+            raise SharingError(404, ERR_NOT_FOUND)
+        if not principal.has(PERM_MANAGE) and share.subject_id != principal.user_id:
+            resource_type = self.registry.get(share.resource_type)
+            if resource_type is None:
+                raise SharingError(404, ERR_NOT_FOUND)
+            await self._authorize(principal, resource_type, share.resource_id)
+        await self.db.delete(share)
+        await self.db.flush()
+
+    async def for_resource(
+        self, principal: ResourcePrincipal, rtype: str, resource_id: str
+    ) -> list[ResourceShare]:
+        """Every share on one row (expired included), for whoever may share it."""
+        row = await self._authorize(principal, self._type(rtype), resource_id)
+        stmt = (
+            select(ResourceShare)
+            .where(
+                ResourceShare.resource_type == rtype,
+                ResourceShare.resource_id == row_id(row),
+            )
+            .order_by(ResourceShare.created_at)
+        )
+        return list((await self.db.execute(stmt)).scalars())
+
+
+__all__ = ["SharingError", "SharingService"]

sharing/services.py

@@ -0,0 +1,22 @@
+"""Module-scoped state container.
+
+Stored as ``app.state.sharing`` by
+:meth:`SharingModule.register_settings`.
+
+Not frozen — ``on_startup`` may set fields that depend on the DB or
+other framework services. Convention: set once during boot, treat as
+read-only after.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from sharing.settings import SharingSettings
+
+
+@dataclass
+class SharingServices:
+    """Sharing module singletons."""
+
+    settings: SharingSettings

sharing/settings.py

@@ -0,0 +1,17 @@
+"""Sharing module settings (DB-backed).
+
+Values come from the pydantic defaults below at boot, then get hydrated from
+the settings table by the hosting lifespan before module ``on_startup`` runs
+(``register_module_settings`` in ``module.py`` records the class).
+``DbBackedSettings`` reads no environment variables: the DB is the only
+source. Add fields here as the module grows.
+"""
+
+from __future__ import annotations
+
+from pydantic_settings import SettingsConfigDict
+from simple_module_core.settings_base import DbBackedSettings
+
+
+class SharingSettings(DbBackedSettings):
+    model_config = SettingsConfigDict(extra="ignore")

simple_module_sharing-0.0.38.dist-info/METADATA

@@ -0,0 +1,73 @@
+Metadata-Version: 2.5
+Name: simple_module_sharing
+Version: 0.0.38
+Summary: Generic resource shares (owner / shared-with-user) for simple_module resource-scoped access
+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: access-control,permissions,sharing,simple-module
+Requires-Python: >=3.12
+Requires-Dist: simple-module-core==0.0.38
+Requires-Dist: simple-module-db==0.0.38
+Requires-Dist: simple-module-hosting==0.0.38
+Requires-Dist: simple-module-inertia==0.0.38
+Description-Content-Type: text/markdown
+
+# simple_module_sharing
+
+A generic share table for
+[simple_module](https://github.com/antosubash/simple_module_python) apps:
+give one user `view` or `edit` access to one row of another module, with an
+optional expiry, without that module shipping a bespoke share model. It plugs
+into the framework's resource-scoped access (`ResourcePolicy`,
+`OwnedResourcePolicy`, `RequiresResource`), so detail routes, lists and counts
+all honour a share in SQL.
+
+## Install
+
+```bash
+pip install simple_module_sharing
+```
+
+Add `simple_module_sharing` to your host's dependencies; the
+`[project.entry-points.simple_module]` entry point is discovered automatically
+at boot. Run `alembic upgrade heads` to create `sharing_resource_share`.
+
+## Usage
+
+Declare the resource type in the owning module and hand the policy a
+`share_exists` factory:
+
+```python
+from sharing.policy import share_exists_for
+
+NOTE_POLICY = OwnedResourcePolicy(
+    Note.owner_id,
+    bypass_perm=PERM_NOTES_MANAGE,
+    share_exists=share_exists_for("notes.note", Note.id),
+)
+
+
+def register_resource_types(self, registry):
+    registry.register(
+        ResourceType(name="notes.note", policy=NOTE_POLICY, select_by_id=select_by_id(Note))
+    )
+```
+
+| Route | Purpose | Permission |
+|---|---|---|
+| `POST /api/sharing/shares` | Grant or update a share | `sharing.share` + policy `can("share")` |
+| `GET /api/sharing/shares?resource_type=&resource_id=` | Shares on one row | `sharing.share` + policy `can("share")` |
+| `DELETE /api/sharing/shares/{id}` | Revoke (hard delete) | `sharing.share`; granter, grantee or `sharing.manage` |
+| `GET /admin/sharing/` | Admin list of every share in the tenant | `sharing.view` |
+
+Shares are tenant-scoped, expired shares never match, and grantees are
+validated through the user directory. See `docs/modules/sharing.md`.
+
+## License
+
+MIT

simple_module_sharing-0.0.38.dist-info/RECORD

@@ -0,0 +1,28 @@
+sharing/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sharing/audience.py,sha256=4LciCzqPR_J9lp_lXVWP4lORciiPfKdSRktdQVzua-A,1709
+sharing/constants.py,sha256=Q7TFy72juCzKqT4rqKe3aKtpwzErkr8FuDFbrzHFfF4,2219
+sharing/deps.py,sha256=aPAQOkeDmnTCRwTuFYM0LV7c21XXkXVEJmBDodeZuiE,902
+sharing/models.py,sha256=x3UWtzWxSL9BRNo1tdYlTZnC-tB1UIRCCGPL_G-Wmt4,1701
+sharing/module.py,sha256=n2o8G5hKcUMOZbxZbHbvL4x_Ej1h1eTmQ6DPAXl_jsA,3070
+sharing/policy.py,sha256=faMtP7LU-_RZ6EALHCcZrZ7UPi2H9szreoguFJ76Wp8,3312
+sharing/present.py,sha256=mfcN0nZcz2hLal6DErKZbb5_Ud1AFwRJYaRHUGaPvBc,1597
+sharing/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sharing/service.py,sha256=Hy3Td_vjri9zFQdcQLpQSiPxljc5jmDNv81zfZCmSf4,6215
+sharing/services.py,sha256=wBRDJX0ZJF7M0Ma1OMxJmRfizARCth-U7exX95A49J4,493
+sharing/settings.py,sha256=DQrv2pUQvqbbHrbyNJRJWbx2cMn-eHosSYcUK4nbfFc,628
+sharing/contracts/__init__.py,sha256=u5thDI57rgS9D9l41aWzo0ty7CsIk_f8FMJ5-S53O7Q,162
+sharing/contracts/schemas.py,sha256=RsRb4PUuwQZOfqiAnsa2GC2Cqw-DzYtkbKfDODvcil8,1073
+sharing/endpoints/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sharing/endpoints/api.py,sha256=B2YK-rDmDZLvlDC6doINhuNyoow0z6ACEYUhC8Hqhho,2220
+sharing/endpoints/views.py,sha256=qXFylAQo5HcGS21DLUvm3hMv2nep21xLKk4quMH46HY,2681
+sharing/locales/de.json,sha256=28e-fBYtpu4W4nqbTc3OxTvTuSu9o51u0sl4xqG5Z9g,983
+sharing/locales/en.json,sha256=BL2M43fp5PYBBmvNBJo5rPtExJaKvZKDJYFEl3teElI,870
+sharing/pages/Admin.tsx,sha256=TMnd2RpsqBDFaRk5CXxbrsaZeIFMB_e4ojhCK8vjYVQ,3006
+sharing/pages/types.ts,sha256=a3q7_aDjgrTrfb7A2FgsxiTOmUp8yolFURHLSZc1UYk,318
+sharing/pages/components/ShareTable.tsx,sha256=a5_LTX47yI8sH-nhC8qrENO_jjIycyHDjUGp64TsSts,3018
+sharing/package.json,sha256=F0eA9FqGL6NdiNV3AKqME4bsoavJ8hdY3Hzv6m5WY4U,411
+simple_module_sharing-0.0.38.dist-info/METADATA,sha256=sQ1oAesbnX3UnwfmhbAn_JNHoQsfcioKlkf03oUV8NE,2714
+simple_module_sharing-0.0.38.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+simple_module_sharing-0.0.38.dist-info/entry_points.txt,sha256=W0KOCMGuWvijLrAew6EdMlW03zx_FsSfoxwgNw6KoSY,55
+simple_module_sharing-0.0.38.dist-info/licenses/LICENSE,sha256=Yn66lhLklsF5p7pa85_ksQrJ79Q-FgOaUAHevLBjer4,1068
+simple_module_sharing-0.0.38.dist-info/RECORD,,

simple_module_sharing-0.0.38.dist-info/WHEEL

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

simple_module_sharing-0.0.38.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[simple_module]
+sharing = sharing.module:SharingModule

simple_module_sharing-0.0.38.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anto Subash
+
+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.