simple-module-sharing 0.0.38__tar.gz

simple_module_sharing-0.0.38/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+dist/
+build/
+*.db
+*.sqlite3
+.env
+
+# Built frontend assets — shipped inside the wheel via force-include but
+# NOT source-controlled. Re-run `smpy module build` before `uv build` to
+# repopulate.
+*/static/dist/
+
+# smpy module verify/build cache (throwaway scaffolded host)
+.smpy/

simple_module_sharing-0.0.38/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.

simple_module_sharing-0.0.38/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,54 @@
+# 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/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"
+  }
+}

simple_module_sharing-0.0.38/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "simple_module_sharing"
+version = "0.0.38"
+description = "Generic resource shares (owner / shared-with-user) for simple_module resource-scoped access"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+authors = [{ name = "Anto Subash", email = "antosubash@live.com" }]
+keywords = ["simple-module", "sharing", "permissions", "access-control"]
+dependencies = [
+    "simple_module_core==0.0.38",
+    "simple_module_db==0.0.38",
+    "simple_module_hosting==0.0.38",
+    "simple_module_inertia==0.0.38",
+]
+
+[project.entry-points.simple_module]
+sharing = "sharing.module:SharingModule"
+
+[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_sharing) doesn't match the package
+# directory (sharing), 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 = ["sharing"]
+
+# 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" = "sharing/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_sharing-0.0.38/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}

simple_module_sharing-0.0.38/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"

simple_module_sharing-0.0.38/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"]

simple_module_sharing-0.0.38/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

simple_module_sharing-0.0.38/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)

simple_module_sharing-0.0.38/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

simple_module_sharing-0.0.38/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)

simple_module_sharing-0.0.38/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"
+  }
+}

simple_module_sharing-0.0.38/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"
+  }
+}