sandloom-tenancy 0.7.0a1__tar.gz

sandloom_tenancy-0.7.0a1/.gitignore

@@ -0,0 +1,4 @@
+# Build artifacts from `uv build` — not committed.
+dist/
+build/
+*.egg-info/

sandloom_tenancy-0.7.0a1/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog — sandloom-tenancy
+
+All notable changes to the `sandloom-tenancy` distribution are documented here.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+Per-package entries are aggregated in the repository-level [docs/changelog.md](../../docs/changelog.md).
+
+## [Unreleased]
+
+## [0.7.0a1] — 2026-10-28
+
+Initial public alpha preparation; earlier version headings describe internal development.
+
+- Breaking (packaging): an ecosystem module distribution. The import package
+  is `sandloom_tenancy` (formerly `sandloom.tenancy`); it registers the
+  `sandloom.modules` entry point `tenancy = "sandloom_tenancy"` and depends on
+  `sandloom>=0.7,<0.8` instead of `sandloom-framework` + `sandloom-shared`.
+  Its contract DTOs, stubs and event schemas stay in `sandloom.shared`
+  (shipped with `sandloom`, SANDLOOM-C012).
+  `email-validator` is now its own dependency.
+
+## [0.7.0] — 2026-10-13
+
+First prepared release version; public publication is pending. While the framework is `0.x`, every Sandloom
+distribution is released in lockstep with the framework release line
+(see [Versioning & Stability](../../docs/contributing/versioning.md));
+the change list since 0.6.0 is in [CHANGELOG.md](../../CHANGELOG.md)
+and the current source API upgrade steps are in
+[Upgrading to Public API 1.0](../../docs/guides/upgrading-1.0.md).
+The historical 0.7 migration guide remains in the preparation archive.
+
+### Fixed
+- Source distributions include the package sources and build independently of the monorepo.
+
+### Added
+- Tenancy module: organizations, membership (owner/admin/member) and
+  invitations, shipped as a standalone wheel over `sandloom-framework` + `sandloom-shared`.

sandloom_tenancy-0.7.0a1/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

sandloom_tenancy-0.7.0a1/NOTICE

@@ -0,0 +1,8 @@
+Sandloom
+Copyright 2026 Vasyl Cherniavskyi
+
+The original Sandloom framework code, documentation and examples are licensed
+under the Apache License, Version 2.0. See LICENSE for the full terms.
+
+Third-party components and assets retain their own copyright notices and
+licenses. This notice does not replace or modify those terms.

sandloom_tenancy-0.7.0a1/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.5
+Name: sandloom-tenancy
+Version: 0.7.0a1
+Summary: Sandloom tenancy module: organizations, membership, invitations.
+Project-URL: Homepage, https://sandloom.dev/
+Project-URL: Documentation, https://sandloom.dev/docs/
+Project-URL: Repository, https://github.com/Sandloom-dev/sandloom
+Project-URL: Issues, https://github.com/Sandloom-dev/sandloom/issues
+Project-URL: Changelog, https://github.com/Sandloom-dev/sandloom/blob/main/packages/sandloom-tenancy/CHANGELOG.md
+Author: Vasyl Cherniavskyi
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Classifier: Development Status :: 3 - Alpha
+Requires-Python: >=3.11
+Requires-Dist: email-validator<3,>=2.3.0
+Requires-Dist: sandloom<0.8,>=0.7.0a1
+Description-Content-Type: text/markdown
+
+# sandloom-tenancy
+
+The Sandloom tenancy module: organizations, membership (owner/admin/member) and
+invitations. Import package `sandloom_tenancy`; it registers the
+`sandloom.modules` entry point `tenancy = "sandloom_tenancy"`, so its module
+name is `tenancy` (tables `tenancy_*`, migration chain
+`alembic_version_tenancy`, channels and contracts `tenancy.*`). Depends on
+`sandloom>=0.7.0a1,<0.8` and email-validator; on no other module.
+
+```bash
+pip install "sandloom[redis,celery]==0.7.0a1" sandloom-tenancy==0.7.0a1
+```
+
+`sandloom.main:app` composes it once installed; an app selects it with
+`SANDLOOM_MODULES=tenancy` (or `sandloom new <app> --with tenancy`). Other
+modules call it through its contracts; their DTOs, stubs and event schemas
+live in `sandloom.shared` and ship with `sandloom`.
+
+Source of truth lives in the monorepo at `src/sandloom_tenancy`; this package
+builds the wheel and source archive.
+
+## Project links
+
+[Source](https://github.com/Sandloom-dev/sandloom) ·
+[Documentation](https://sandloom.dev/docs/) ·
+[Changelog](https://github.com/Sandloom-dev/sandloom/blob/main/packages/sandloom-tenancy/CHANGELOG.md)
+
+This is the initial `0.7.0a1` alpha distribution. The canonical source
+repository is private and awaiting transfer; the documentation website is
+not deployed yet. The project links above are the planned public locations.
+
+## License
+
+Apache-2.0. Copyright 2026 Vasyl Cherniavskyi. See [LICENSE](LICENSE) and [NOTICE](NOTICE).

sandloom_tenancy-0.7.0a1/README.md

@@ -0,0 +1,34 @@
+# sandloom-tenancy
+
+The Sandloom tenancy module: organizations, membership (owner/admin/member) and
+invitations. Import package `sandloom_tenancy`; it registers the
+`sandloom.modules` entry point `tenancy = "sandloom_tenancy"`, so its module
+name is `tenancy` (tables `tenancy_*`, migration chain
+`alembic_version_tenancy`, channels and contracts `tenancy.*`). Depends on
+`sandloom>=0.7.0a1,<0.8` and email-validator; on no other module.
+
+```bash
+pip install "sandloom[redis,celery]==0.7.0a1" sandloom-tenancy==0.7.0a1
+```
+
+`sandloom.main:app` composes it once installed; an app selects it with
+`SANDLOOM_MODULES=tenancy` (or `sandloom new <app> --with tenancy`). Other
+modules call it through its contracts; their DTOs, stubs and event schemas
+live in `sandloom.shared` and ship with `sandloom`.
+
+Source of truth lives in the monorepo at `src/sandloom_tenancy`; this package
+builds the wheel and source archive.
+
+## Project links
+
+[Source](https://github.com/Sandloom-dev/sandloom) ·
+[Documentation](https://sandloom.dev/docs/) ·
+[Changelog](https://github.com/Sandloom-dev/sandloom/blob/main/packages/sandloom-tenancy/CHANGELOG.md)
+
+This is the initial `0.7.0a1` alpha distribution. The canonical source
+repository is private and awaiting transfer; the documentation website is
+not deployed yet. The project links above are the planned public locations.
+
+## License
+
+Apache-2.0. Copyright 2026 Vasyl Cherniavskyi. See [LICENSE](LICENSE) and [NOTICE](NOTICE).

sandloom_tenancy-0.7.0a1/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "sandloom-tenancy"
+version = "0.7.0a1"
+classifiers = ["Development Status :: 3 - Alpha"]
+description = "Sandloom tenancy module: organizations, membership, invitations."
+readme = "README.md"
+license = "Apache-2.0"
+license-files = ["LICENSE", "NOTICE"]
+authors = [{ name = "Vasyl Cherniavskyi" }]
+requires-python = ">=3.11"
+# An ecosystem module like any third party's: a compatible framework range,
+# never an exact pin. Contract calls to other modules are bound at runtime
+# and use the consumer's own generated stubs: no module depends on another.
+dependencies = [
+    "sandloom>=0.7.0a1,<0.8",
+    "email-validator>=2.3.0,<3",
+]
+
+[project.urls]
+Homepage = "https://sandloom.dev/"
+Documentation = "https://sandloom.dev/docs/"
+Repository = "https://github.com/Sandloom-dev/sandloom"
+Issues = "https://github.com/Sandloom-dev/sandloom/issues"
+Changelog = "https://github.com/Sandloom-dev/sandloom/blob/main/packages/sandloom-tenancy/CHANGELOG.md"
+
+# The module name (`tenancy`: tables, migration chain, channels, contracts) and
+# its import path; SANDLOOM_MODULES may name it by either.
+[project.entry-points."sandloom.modules"]
+tenancy = "sandloom_tenancy"
+
+[build-system]
+requires = [
+    "hatchling>=1.27",
+]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["sandloom_tenancy"]

sandloom_tenancy-0.7.0a1/sandloom_tenancy/__init__.py

@@ -0,0 +1,87 @@
+"""Tenancy module: organizations, membership, invitations.
+
+Registered via the core plugin system. Exposes the membership READ contract
+through the service registry as `tenancy.membership.v1`
+(:class:`~sandloom_tenancy.contracts.MembershipReadContract`: ``get_role``,
+``is_member``, ``has_role_at_least``, ``get_member_state``,
+``list_user_organization_ids``, ``list_member_user_ids``) so other
+modules can resolve membership without importing tenancy internals. The write
+side (add / change role / remove) is deliberately NOT part of any contract.
+
+Contract semantics: the methods take NO session — every call runs in tenancy's
+own read-only Unit of Work on tenancy's database, identically in-process and
+over internal RPC (``SERVICE_BINDINGS``). The ``tenant_ids`` claims contributor
+is likewise exposed as ``tenancy.claims.v1`` so an identity service deployed
+alone still mints tokens with the allowlist; it is critical, so if tenancy
+cannot answer, token issuance fails with 503 rather than minting a token
+without ``tenant_ids``.
+
+Staleness of the JWT ``tenant_ids`` allowlist
+---------------------------------------------
+The claims contributor embeds the user's organization ids in the access token
+at mint time. To stop a token minted before a member was removed / left (or
+before an org was deleted) from still selecting that tenant, tenancy calls the
+kernel's ``revoke_user_tokens_on_commit(user_id, reason=...,
+require_immediate=True)`` for every affected user (role changes and ownership
+transfers too) — the mark is written before the change commits, or the change
+is refused with 503 (same path identity uses): the
+framework token checks (``current_context`` / ``require(...)`` /
+``TenantScope``) then reject the stale access token with 401 and the client
+refreshes, receiving a token whose ``tenant_ids`` reflects the change. A
+request whose guards passed before the change committed still completes, so
+authorization that must observe a removal with certainty still uses the live
+contract — ``has_role_at_least`` / ``is_member`` (or the shared ``OrgRole``
+atom).
+
+A role CHANGE revokes the member's tokens too (owner decision): organization
+roles are not token claims today (the contributor embeds only ``tenant_ids``)
+and every role gate reads the role live, so a demotion is already effective on
+the next request — the revocation ends the stale session and keeps a future
+membership cache / role claims safe. The member re-authenticates.
+
+Consumers of the member events apply ``version``-ed events with a version
+guard and REFRESH on a version-less one (an instance from before the upgrade)
+via ``get_member_state`` — see :mod:`sandloom.shared.membership`.
+
+Member lifecycle events
+-----------------------
+Every way a member appears or changes is announced on the member channels —
+``tenancy.member_added.v1`` (``add_member``, accepting an invitation, the
+owner of a new organization), ``tenancy.member_role_changed.v1`` (role change,
+both sides of an ownership transfer), ``tenancy.member_removed.v1`` — written
+to the outbox in the change's own UoW. Each carries ``version``: a
+per-``(organization_id, user_id)`` counter (``tenancy_member_versions``),
+monotonic across removal and re-add, so consumers order and dedupe with a
+version guard (delivery has no ordering guarantee). It is an optional field
+added within v1 (additive; older version-less events still validate).
+"""
+
+from sandloom.sdk import define_module
+from sandloom.sdk.module import ModuleAPI
+
+from .claims import tenancy_claims
+from .services.operations import OPERATIONS
+
+MEMBERSHIP_SERVICE_V1 = "tenancy.membership.v1"
+
+
+def _setup(core: ModuleAPI) -> None:
+    # Tenant selection is authorization-sensitive: never mint an access token
+    # without the allowlist when the tenancy module is present.
+    core.add_claims_contributor(tenancy_claims, critical=True)
+    # Declared planner operations: planned (and their executor logged) at boot.
+    core.register_operations(*OPERATIONS)
+
+
+# Discovered (sandloom.sdk define_module): the routers of ``api.__all__``, the
+# producer classes of ``events`` and the read-only ``tenancy.membership.v1``
+# provider of ``contracts`` (never the full MembershipService: its write
+# methods would be callable by any module or internal RPC caller).
+register = define_module(
+    __name__,
+    version="1.0.0",
+    capabilities=["database", "eventbus"],
+    setup=_setup,
+)
+
+__all__ = ["register", "MEMBERSHIP_SERVICE_V1"]

sandloom_tenancy-0.7.0a1/sandloom_tenancy/access/__init__.py

@@ -0,0 +1,151 @@
+"""Tenancy access: organization-role enforcement.
+
+Authentication uses the canonical shared guard (`current_user_id`, a
+projection of `sandloom.shared.authz.current_context`); the org-role check goes through
+the
+`tenancy.membership.v1` service contract — the same path the shared `OrgRole`
+atom uses. `require_org_role` is kept as a dependency (rather than the
+`require(OrgRole(...))` atom) only because it returns **404** for non-members to
+avoid leaking organization existence — a distinction the single-boolean atom
+cannot express.
+
+The role is resolved LIVE from the membership table on every request (never
+from the JWT ``tenant_ids`` claim), so a removed member or a deleted
+organization is denied immediately.
+"""
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import get_args
+from uuid import UUID
+
+from fastapi import Depends, HTTPException, Request, status
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from sandloom.sdk.data import PlannedReads
+from sandloom.sdk.effects import sensitive_effect
+from sandloom.sdk.security import decode_token_cached
+from sandloom.sdk.web import DbSession, current_user_id
+from sandloom_tenancy.roles import role_at_least
+from sandloom_tenancy.services.membership_service import MembershipService
+from sandloom_tenancy.services.operations import member_role_in_active_org
+
+#: The request unit's session dependency: exactly ``DbSession``'s
+#: ``Depends`` (function scope), for guards whose session parameter follows
+#: parameters with defaults.
+_REQUEST_DB = get_args(DbSession)[1]
+
+__all__ = [
+    "require_org_role",
+    "require_org_role_reads",
+    "current_user_id",
+    "TokenEmail",
+    "get_token_email",
+]
+
+_bearer = HTTPBearer(auto_error=False)
+
+
+def _admin_tagged(
+    guard: Callable[..., Awaitable[UUID]], minimum: str
+) -> Callable[..., Awaitable[UUID]]:
+    """An admin-or-owner gate carries the admin risk (ADR-0009 item 6)."""
+    if minimum == "member":
+        return guard
+    return sensitive_effect("admin")(guard)
+
+
+def require_org_role(minimum: str) -> Callable[..., Awaitable[UUID]]:
+    """Dependency factory: caller must hold at least `minimum` role in the org.
+
+    Reads `org_id` from the path. Returns the caller's user id on success.
+    404 is returned for non-members (and for inactive organizations) to avoid
+    leaking organization existence.
+    """
+    # Validate eagerly: a typo'd role must fail at import, not grant access.
+    role_at_least(minimum, minimum)
+
+    async def _guard(
+        org_id: UUID,
+        user_id: UUID = Depends(current_user_id),
+        db: AsyncSession = _REQUEST_DB,
+    ) -> UUID:
+        role = await MembershipService.get_role(org_id, user_id, db)
+        if role is None:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="Organization not found",
+            )
+        if not role_at_least(role, minimum):
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="Insufficient organization role",
+            )
+        return user_id
+
+    return _admin_tagged(_guard, minimum)
+
+
+def require_org_role_reads(minimum: str) -> Callable[..., Awaitable[UUID]]:
+    """:func:`require_org_role` for a READ-ONLY route (``PlannedReads``).
+
+    The same check (404 for non-members / inactive organizations, 403 below
+    ``minimum``) through the declared ``member_role_in_active_org`` on the
+    route's own ``PlannedReads`` handle (FastAPI shares it with the handler),
+    so guard + handler reads share one read-only transaction on the general
+    executor, or run on the optimized one. No Unit of Work is opened.
+    """
+    role_at_least(minimum, minimum)
+
+    async def _guard(
+        org_id: UUID,
+        reads: PlannedReads,
+        user_id: UUID = Depends(current_user_id),
+    ) -> UUID:
+        found = await reads.one(
+            member_role_in_active_org, organization_id=org_id, user_id=user_id
+        )
+        if found is None:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="Organization not found",
+            )
+        if not role_at_least(found.role, minimum):
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="Insufficient organization role",
+            )
+        return user_id
+
+    return _admin_tagged(_guard, minimum)
+
+
+@dataclass(frozen=True, slots=True)
+class TokenEmail:
+    """The caller's e-mail as asserted by the (signature-verified) access token."""
+
+    email: str | None
+    #: ``None`` when the token does not carry an ``email_verified`` claim.
+    verified: bool | None
+
+
+async def get_token_email(
+    request: Request,
+    _user_id: UUID = Depends(current_user_id),
+    credentials: HTTPAuthorizationCredentials | None = Depends(_bearer),
+) -> TokenEmail:
+    """Read ``email`` / ``email_verified`` claims from the caller's access token.
+
+    Depends on ``current_user_id`` so the token is already authenticated
+    (and typed ``access``); the decode is cached per request.
+    """
+    payload = (
+        decode_token_cached(request, credentials.credentials) if credentials else None
+    ) or {}
+    email = payload.get("email")
+    verified = payload.get("email_verified")
+    return TokenEmail(
+        email=email if isinstance(email, str) and email else None,
+        verified=verified if isinstance(verified, bool) else None,
+    )