sahra-shared 0.2.2__tar.gz

sahra_shared-0.2.2/.gitignore

@@ -0,0 +1,104 @@
+# Python Bytecode
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Virtual Environment
+venv/
+.env/
+.venv/
+env/
+ENV/
+*.venv
+
+# Development Tools
+.idea/
+.vscode/
+*.swp
+*.swo
+*.swn
+*.swm
+
+# Testing and Coverage
+htmlcov/
+.tox/
+.nox/
+*.coverage
+.coverage.*
+.cache/
+pytest_cache/
+tests/__pycache__/
+test-results/
+coverage.xml
+*.cover
+
+# Logs and Temporary Files
+*.log
+*.tmp
+*.temp
+*.pid
+*.bak
+*.old
+*.orig
+*.rej
+
+# Build Artifacts
+build/
+dist/
+*.egg-info/
+*.egg
+.installed.cfg
+eggs/
+sdist/
+wheels/
+share/python-wheels/
+
+# Type Checker Caches
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pytest_cache/
+.ruff_cache/
+.pyright/
+
+# IDE Configurations
+*.iml
+*.sublime-project
+*.sublime-workspace
+
+# System Files
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# Sensitive Data
+.secret/
+*.key
+*.pem
+.env
+.env.*
+!.env.example
+
+tmp/
+temp/
+
+# uv (Python package manager)
+.uv/
+# uv.lock is COMMITTED for this repository. It is the shared kernel: its
+# resolved dependency set is part of what a release tag means, and every one
+# of the 18 consumers resolves `sahra-shared` from a git revision of this
+# repo. An ignored lockfile made the release irreproducible, so it is tracked
+# deliberately. Do not re-add it here.
+
+# FastAPI / Alembic
+alembic/versions/*.pyc
+
+# Docker
+*.env.docker
+.dockerenv
+
+# Local agent/tooling state. Agent worktrees must NEVER be committed.
+# Note: the .claude/ rules already tracked in this repo stay tracked — gitignore
+# does not untrack existing files. Use `git add -f` to add a new one on purpose.
+.claude/
+.claude/worktrees/

sahra_shared-0.2.2/LICENSE

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

sahra_shared-0.2.2/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.5
+Name: sahra-shared
+Version: 0.2.2
+Summary: Sahra Trans — shared kernel library
+Project-URL: Homepage, https://github.com/Sahra-Trans/sahra-shared
+Project-URL: Repository, https://github.com/Sahra-Trans/sahra-shared
+Project-URL: Issues, https://github.com/Sahra-Trans/sahra-shared/issues
+Author: Hycind Santhibhavan
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: cryptography>=42.0.0
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: nats-py>=2.7.0
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.24.0
+Requires-Dist: opentelemetry-instrumentation-fastapi>=0.45b0
+Requires-Dist: opentelemetry-sdk>=1.24.0
+Requires-Dist: prometheus-client>=0.20.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyjwt[crypto]>=2.8.0
+Requires-Dist: sqlalchemy>=2.0.0
+Description-Content-Type: text/markdown
+
+# sahra-shared
+
+[![PyPI](https://img.shields.io/pypi/v/sahra-shared.svg)](https://pypi.org/project/sahra-shared/)
+[![Python](https://img.shields.io/pypi/pyversions/sahra-shared.svg)](https://pypi.org/project/sahra-shared/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](#license)
+
+**A reusable Python library — the shared kernel for Sahra Trans services.**
+
+`sahra-shared` is a *library*, not a service. It has **no HTTP server, no database, no
+port, no container and no entrypoint**. Nothing here starts; you `import` it. It is
+published to PyPI and consumed by the Sahra Trans services as an ordinary dependency.
+
+The import namespace is **`sahra_shared`**.
+
+## Install
+
+```bash
+uv add sahra-shared
+```
+
+## Use
+
+```python
+from sahra_shared.auth import Capability, CapabilityGuards
+from sahra_shared.events import NATSPublisher, SahraEvent
+from sahra_shared.http import ProblemDetail, make_health_router
+from sahra_shared.privacy import CountryPrivacyPolicy, PIIEmail
+from sahra_shared.telemetry import AppLogger, setup_otel
+from sahra_shared.tenancy import TenantScope, tenant_transaction
+```
+
+## What it provides
+
+| Sub-package | Surface |
+|---|---|
+| `sahra_shared.auth` | `TokenClaims`, RS256 JWT verification against JWKS, the closed `Capability` vocabulary and deny-by-default `CapabilityGuards` |
+| `sahra_shared.events` | `SahraEvent` (CloudEvents envelope), `NATSPublisher` / consumer helpers |
+| `sahra_shared.http` | `ProblemDetail` (RFC 7807) and `make_health_router` — a router **factory** a service mounts; this library serves nothing itself |
+| `sahra_shared.privacy` | PII types (`PIIEmail`, `PIIPhone`, …) and per-country privacy policies |
+| `sahra_shared.telemetry` | OpenTelemetry setup, structured logging, `call_service` (propagates `traceparent`) |
+| `sahra_shared.tenancy` | `TenantScope`, transaction-bound tenant context, row-level-security helpers |
+
+Sub-packages are independent: they do not import one another (only `telemetry` is
+depended upon in common). That boundary is enforced by
+`tests/test_import_boundaries.py`.
+
+## Requirements
+
+Python **>= 3.13**.
+
+## Development
+
+This repository is **uv-only**. Do not use `pip`, `venv`, Poetry or Twine.
+
+```bash
+uv sync --all-groups        # install dev + test dependency groups
+uv run pytest               # tests
+uv run ruff check .         # lint
+uv run ruff format --check .# format
+uv run ty check             # type-check
+uv build                    # build wheel + sdist
+```
+
+`uv.lock` is committed deliberately: the resolved dependency set is part of what a
+release tag means.
+
+## Documentation
+
+Design notes, the tenancy/RLS reference and the logging integration guide live
+in the project repository alongside the source, and are not shipped in the
+distribution.
+
+## Releasing
+
+Releases are built and published to PyPI by GitHub Actions using **Trusted
+Publishing (OIDC)**. There is no PyPI API token and no stored publishing
+credential. A `vX.Y.Z` tag builds, gates and publishes; a `vX.Y.Z-rc1` tag runs
+the identical gate and stops before publishing.
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

sahra_shared-0.2.2/README.md

@@ -0,0 +1,82 @@
+# sahra-shared
+
+[![PyPI](https://img.shields.io/pypi/v/sahra-shared.svg)](https://pypi.org/project/sahra-shared/)
+[![Python](https://img.shields.io/pypi/pyversions/sahra-shared.svg)](https://pypi.org/project/sahra-shared/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](#license)
+
+**A reusable Python library — the shared kernel for Sahra Trans services.**
+
+`sahra-shared` is a *library*, not a service. It has **no HTTP server, no database, no
+port, no container and no entrypoint**. Nothing here starts; you `import` it. It is
+published to PyPI and consumed by the Sahra Trans services as an ordinary dependency.
+
+The import namespace is **`sahra_shared`**.
+
+## Install
+
+```bash
+uv add sahra-shared
+```
+
+## Use
+
+```python
+from sahra_shared.auth import Capability, CapabilityGuards
+from sahra_shared.events import NATSPublisher, SahraEvent
+from sahra_shared.http import ProblemDetail, make_health_router
+from sahra_shared.privacy import CountryPrivacyPolicy, PIIEmail
+from sahra_shared.telemetry import AppLogger, setup_otel
+from sahra_shared.tenancy import TenantScope, tenant_transaction
+```
+
+## What it provides
+
+| Sub-package | Surface |
+|---|---|
+| `sahra_shared.auth` | `TokenClaims`, RS256 JWT verification against JWKS, the closed `Capability` vocabulary and deny-by-default `CapabilityGuards` |
+| `sahra_shared.events` | `SahraEvent` (CloudEvents envelope), `NATSPublisher` / consumer helpers |
+| `sahra_shared.http` | `ProblemDetail` (RFC 7807) and `make_health_router` — a router **factory** a service mounts; this library serves nothing itself |
+| `sahra_shared.privacy` | PII types (`PIIEmail`, `PIIPhone`, …) and per-country privacy policies |
+| `sahra_shared.telemetry` | OpenTelemetry setup, structured logging, `call_service` (propagates `traceparent`) |
+| `sahra_shared.tenancy` | `TenantScope`, transaction-bound tenant context, row-level-security helpers |
+
+Sub-packages are independent: they do not import one another (only `telemetry` is
+depended upon in common). That boundary is enforced by
+`tests/test_import_boundaries.py`.
+
+## Requirements
+
+Python **>= 3.13**.
+
+## Development
+
+This repository is **uv-only**. Do not use `pip`, `venv`, Poetry or Twine.
+
+```bash
+uv sync --all-groups        # install dev + test dependency groups
+uv run pytest               # tests
+uv run ruff check .         # lint
+uv run ruff format --check .# format
+uv run ty check             # type-check
+uv build                    # build wheel + sdist
+```
+
+`uv.lock` is committed deliberately: the resolved dependency set is part of what a
+release tag means.
+
+## Documentation
+
+Design notes, the tenancy/RLS reference and the logging integration guide live
+in the project repository alongside the source, and are not shipped in the
+distribution.
+
+## Releasing
+
+Releases are built and published to PyPI by GitHub Actions using **Trusted
+Publishing (OIDC)**. There is no PyPI API token and no stored publishing
+credential. A `vX.Y.Z` tag builds, gates and publishes; a `vX.Y.Z-rc1` tag runs
+the identical gate and stops before publishing.
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

sahra_shared-0.2.2/pyproject.toml

@@ -0,0 +1,196 @@
+# ======================================================================
+# PROJECT METADATA
+# ======================================================================
+[project]
+name = "sahra-shared"
+version = "0.2.2"
+description = "Sahra Trans — shared kernel library"
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Hycind Santhibhavan" }]
+dependencies = [
+    "fastapi>=0.115.0",
+    "pydantic>=2.0.0",
+    "nats-py>=2.7.0",
+    "PyJWT[crypto]>=2.8.0",
+    "opentelemetry-sdk>=1.24.0",
+    "opentelemetry-exporter-otlp-proto-grpc>=1.24.0",
+    "opentelemetry-instrumentation-fastapi>=0.45b0",
+    "prometheus-client>=0.20.0",
+    "httpx>=0.27.0",
+    "sqlalchemy>=2.0.0",
+    # Imported directly by sahra_shared/auth/dependencies.py to reject a JWKS entry that
+    # carries private key material. Already present transitively via PyJWT[crypto];
+    # declared so the import is not a hidden transitive dependency.
+    "cryptography>=42.0.0",
+]
+
+
+[project.urls]
+Homepage = "https://github.com/Sahra-Trans/sahra-shared"
+Repository = "https://github.com/Sahra-Trans/sahra-shared"
+Issues = "https://github.com/Sahra-Trans/sahra-shared/issues"
+
+
+# Dev and test tooling lives in [dependency-groups] only. A duplicate
+# [project.optional-dependencies] dev = [...] block used to shadow it; nothing
+# installed the extra (Makefile and both CI workflows use `uv sync --all-groups`)
+# while deptry read its entries as runtime dependencies and failed the build.
+[dependency-groups]
+dev = ["deptry", "ty", "ruff", "vulture", "bandit>=1.7.9", "pip-audit>=2.7.3", "pyright>=1.1.400"]
+test = ["pytest", "pytest-asyncio", "httpx"]
+
+# ======================================================================
+# BUILD SYSTEM
+# ======================================================================
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["sahra_shared"]
+
+# The default sdist is "everything git tracks". That shipped the internal agent
+# instructions (.clinerules/.cursorrules/.windsurfrules, CLAUDE.md, GEMINI.md,
+# QWEN.md, AGENTS.md), the git hooks and their tamper manifest, the GitHub and
+# GitLab CI configuration -- and, because hatchling does not consult .gitignore
+# for this, an untracked `.env` as well.
+#
+# So this is an ALLOWLIST, not a denylist: a new internal file is excluded by
+# default and has to be named here to ship. A denylist publishes whatever
+# nobody remembered to add to it.
+#
+# `docs/` and `tests/` are deliberately NOT shipped. `docs/migrations/` carries
+# the tenant row-level-security migration and `docs/TENANCY.md` the schema
+# design behind it; the tests reference internal endpoint paths and the scheme
+# that authenticates them. None of it is needed to build, install or verify the
+# library, and this is a public index. They remain in the repository, which is
+# where contributors read them.
+[tool.hatch.build.targets.sdist]
+# Patterns are gitignore-style, so they are root-anchored with a leading "/".
+# A bare "README.md" matches at ANY depth and dragged
+# tests/typecheck_violations/README.md into the sdist.
+include = [
+    "/sahra_shared/",
+    "/README.md",
+    "/LICENSE",
+    "/pyproject.toml",
+    "/uv.lock",
+]
+
+# ======================================================================
+# TY (Fast Type Checker)
+# ======================================================================
+[tool.ty.src]
+include = ["sahra_shared"]
+exclude = ["tests", ".venv"]
+respect-ignore-files = true
+
+[tool.ty.environment]
+python-version = "3.13"
+root = ["."]
+
+[tool.ty.analysis]
+allowed-unresolved-imports = []
+replace-imports-with-any = []
+respect-type-ignore-comments = true
+
+[tool.ty.rules]
+all = "warn"
+
+[tool.ty.terminal]
+output-format = "full"
+error-on-warning = false
+
+[[tool.ty.overrides]]
+include = ["tests/**", "**/test_*.py"]
+
+[tool.ty.overrides.rules]
+possibly-unresolved-reference = "ignore"
+
+# ======================================================================
+# PYRIGHT (Type Checker)
+# ======================================================================
+# The 18 services pin pythonVersion = "3.12" while declaring
+# requires-python = ">=3.13". The shared kernel targets 3.13, matching what it
+# actually declares and what its `requires-python` floor allows.
+[tool.pyright]
+include = ["sahra_shared"]
+exclude = [".venv", "**/__pycache__", "tests/typecheck_violations"]
+pythonVersion = "3.13"
+typeCheckingMode = "strict"
+reportMissingTypeStubs = false
+reportUnknownMemberType = false
+reportUnnecessaryIsInstance = false
+# FastAPI route handlers and exception handlers are registered by their
+# decorator and never referenced by name; strict mode reports every one of them
+# as unused. All current hits are of exactly that shape.
+reportUnusedFunction = false
+# Generic third-party models (nats, SahraEvent[Any]) resolve to partially
+# unknown types at their use sites; the annotations we control are explicit.
+reportUnknownVariableType = false
+
+# ======================================================================
+# DEPTRY (Dependency Checker)
+# ======================================================================
+[tool.deptry]
+ignore = []
+known_first_party = ["sahra_shared"]
+exclude = ["tests", "\\.venv", ".claude", "docs"]
+
+# ======================================================================
+# VULTURE (Find Dead Code)
+# ======================================================================
+[tool.vulture]
+paths = ["sahra_shared"]
+exclude = ["tests", "venv", ".venv"]
+min_confidence = 95
+sort_by_size = true
+
+# ======================================================================
+# PYTEST
+# ======================================================================
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+asyncio_mode = "auto"
+
+# ======================================================================
+# RUFF (Fast Linter/Formatter)
+# ======================================================================
+[tool.ruff]
+line-length = 180
+indent-width = 4
+target-version = "py313"
+src = ["sahra_shared"]
+extend-exclude = [".claude", "tests", "venv", ".venv", ".claude"]
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # Pyflakes
+    "C90", # McCabe complexity
+    "I",   # isort
+    "B",   # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "T20", # flake8-print
+    "S",   # flake8-bandit (security warnings)
+    "UP",  # pyupgrade
+    "N",   # pep8-naming
+]
+ignore = [
+    "UP006", # Dict vs dict
+    "UP007", # List vs list
+    "UP018", # Typing.List vs list
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["sahra_shared"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "auto"

sahra_shared-0.2.2/sahra_shared/auth/__init__.py

@@ -0,0 +1,53 @@
+from sahra_shared.auth.capabilities import (
+    FOREIGN_VOCABULARY,
+    ROLE_CAPABILITIES,
+    Capability,
+    RoleName,
+    capabilities_for_roles,
+)
+from sahra_shared.auth.claims import TokenClaims
+from sahra_shared.auth.coverage import (
+    RouteDeclaration,
+    UndeclaredRouteError,
+    assert_capability_coverage,
+    describe_routes,
+    enforce_capability_coverage,
+)
+from sahra_shared.auth.dependencies import (
+    ForeignVocabularyError,
+    make_auth_dependency,
+    require_role,
+)
+from sahra_shared.auth.guards import (
+    CapabilityGuards,
+    CapabilityRequirement,
+    declared_capabilities,
+    internal_endpoint,
+    internal_reason,
+    public_endpoint,
+    public_reason,
+)
+
+__all__ = [
+    "FOREIGN_VOCABULARY",
+    "ROLE_CAPABILITIES",
+    "Capability",
+    "CapabilityGuards",
+    "CapabilityRequirement",
+    "ForeignVocabularyError",
+    "RoleName",
+    "RouteDeclaration",
+    "TokenClaims",
+    "UndeclaredRouteError",
+    "assert_capability_coverage",
+    "capabilities_for_roles",
+    "declared_capabilities",
+    "describe_routes",
+    "enforce_capability_coverage",
+    "internal_endpoint",
+    "internal_reason",
+    "make_auth_dependency",
+    "public_endpoint",
+    "public_reason",
+    "require_role",
+]