purview-authz 0.1.0__tar.gz

purview_authz-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,53 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: purview_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    env:
+      UV_PYTHON: ${{ matrix.python-version }}
+      PURVIEW_TEST_POSTGRES_URL: postgresql+asyncpg://postgres:postgres@localhost:5432/purview_test
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Lint
+        run: uv run --extra dev ruff check .
+
+      - name: Type-check (strict)
+        run: uv run --extra dev mypy
+
+      - name: Test (SQLite + Postgres) with coverage gate
+        run: uv run --extra dev pytest --cov=purview --cov-report=term-missing --cov-fail-under=90

purview_authz-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,58 @@
+name: Release
+
+# Publishes to PyPI on a version tag (e.g. v0.1.0) via Trusted Publishing (OIDC) —
+# no API token is stored. See RELEASING.md for the one-time PyPI/GitHub setup.
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # hatch-vcs derives the version from tags/history
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+
+      - name: Verify (lint, type-check, tests)
+        run: |
+          uv run --extra dev ruff check .
+          uv run --extra dev mypy
+          uv run --extra dev pytest -q
+
+      - name: Build sdist + wheel
+        run: uv build
+
+      - name: Check metadata
+        run: uvx twine check dist/*
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/purview-authz
+    permissions:
+      id-token: write # required for Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

purview_authz-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+
+# Builds
+build/
+dist/
+
+# Environments
+.venv/
+venv/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml

purview_authz-0.1.0/.hypothesis/.gitignore

@@ -0,0 +1,9 @@
+# This .gitignore file was automatically created by Hypothesis. Hypothesis gitignores
+# .hypothesis by default, because we generally recommend that .hypothesis not be checked
+# into version control.
+#
+# If you *would* like to check .hypothesis into version control, you should delete this
+# file. Hypothesis will not re-create this .gitignore unless .hypothesis is deleted (and
+# if it does, that's a bug - please report it!)
+
+*

purview_authz-0.1.0/.hypothesis/constants/0491a2f633fabf1a

@@ -0,0 +1,4 @@
+# file: /home/runner/work/purview/purview/src/purview/fastapi/__init__.py
+# hypothesis_version: 6.155.1
+
+['authorize_or_403', 'context_binder', 'requires']

purview_authz-0.1.0/.hypothesis/constants/0cceecc88269056c

@@ -0,0 +1,4 @@
+# file: /home/runner/work/purview/purview/src/purview/sqlalchemy/__init__.py
+# hypothesis_version: 6.155.1
+
+['Purview', 'authorized_select', 'bind_context', 'bypass', 'context_of', 'install', 'is_bypassed']

purview_authz-0.1.0/.hypothesis/constants/10920446925b3c49

@@ -0,0 +1,4 @@
+# file: /home/runner/work/purview/purview/.venv/bin/pytest
+# hypothesis_version: 6.155.1
+
+['-script.pyw', '.exe', '__main__']

purview_authz-0.1.0/.hypothesis/constants/12edbb823e339999

@@ -0,0 +1,4 @@
+# file: /home/runner/work/purview/purview/src/purview/core/registry.py
+# hypothesis_version: 6.155.1
+
+[]

purview_authz-0.1.0/.hypothesis/constants/1efe0babaf0dad63

@@ -0,0 +1,4 @@
+# file: /home/runner/work/purview/purview/src/purview/core/combine.py
+# hypothesis_version: 6.155.1
+
+[]

purview_authz-0.1.0/.hypothesis/constants/3287b6f78b0466bd

@@ -0,0 +1,4 @@
+# file: /home/runner/work/purview/purview/src/purview/sqlalchemy/predicates.py
+# hypothesis_version: 6.155.1
+
+[]

purview_authz-0.1.0/.hypothesis/constants/49f91488b563af82

@@ -0,0 +1,4 @@
+# file: /home/runner/work/purview/purview/src/purview/fastapi/dependencies.py
+# hypothesis_version: 6.155.1
+
+[]

purview_authz-0.1.0/.hypothesis/constants/67b0a8ccf18bf5d2

@@ -0,0 +1,4 @@
+# file: /usr/lib/python3.12/sitecustomize.py
+# hypothesis_version: 6.155.1
+
+[]

purview_authz-0.1.0/.hypothesis/constants/73e1fa72b4f3b23f

@@ -0,0 +1,4 @@
+# file: /home/runner/work/purview/purview/src/purview/sqlalchemy/write_guard.py
+# hypothesis_version: 6.155.1
+
+[]

purview_authz-0.1.0/.hypothesis/constants/75add87656b58a41

@@ -0,0 +1,4 @@
+# file: /home/runner/work/purview/purview/src/purview/fastapi/errors.py
+# hypothesis_version: 6.155.1
+
+[403, 'detail', 'forbidden']

purview_authz-0.1.0/.hypothesis/constants/93b313a9c8da98f9

@@ -0,0 +1,4 @@
+# file: /home/runner/work/purview/purview/src/purview/sqlalchemy/enforcer.py
+# hypothesis_version: 6.155.1
+
+['before_flush', 'do_orm_execute', 'tenant_id']

purview_authz-0.1.0/.hypothesis/constants/9e7c9f6cf266c3e0

@@ -0,0 +1,4 @@
+# file: /home/runner/work/purview/purview/src/purview/core/types.py
+# hypothesis_version: 6.155.1
+
+['Context[Any, Any]']

purview_authz-0.1.0/.hypothesis/constants/9e8df1d173bc1388

@@ -0,0 +1,4 @@
+# file: /home/runner/work/purview/purview/src/purview/sqlalchemy/filtering.py
+# hypothesis_version: 6.155.1
+
+[]

purview_authz-0.1.0/.hypothesis/constants/a9f7838e55cc30ba

@@ -0,0 +1,4 @@
+# file: /home/runner/work/purview/purview/src/purview/fastapi/guards.py
+# hypothesis_version: 6.155.1
+
+['R']

purview_authz-0.1.0/.hypothesis/constants/bce7a709d8a6c54f

@@ -0,0 +1,4 @@
+# file: /home/runner/work/purview/purview/src/purview/sqlalchemy/bypass.py
+# hypothesis_version: 6.155.1
+
+['purview.bypass', 'purview_bypass']

purview_authz-0.1.0/.hypothesis/constants/c16d1e3f871ab3c2

@@ -0,0 +1,4 @@
+# file: /home/runner/work/purview/purview/src/purview/sqlalchemy/creating.py
+# hypothesis_version: 6.155.1
+
+[]

purview_authz-0.1.0/.hypothesis/constants/d2bddefade20f961

@@ -0,0 +1,4 @@
+# file: /home/runner/work/purview/purview/src/purview/exceptions.py
+# hypothesis_version: 6.155.1
+
+[]

purview_authz-0.1.0/.hypothesis/constants/e0ab8b84d69fb0f0

@@ -0,0 +1,4 @@
+# file: /home/runner/work/purview/purview/src/purview/__init__.py
+# hypothesis_version: 6.155.1
+
+['0.0.0+unknown', 'Action', 'CREATE', 'Context', 'CrossTenantWrite', 'DELETE', 'Policy', 'PurviewError', 'PurviewForbidden', 'READ', 'TenantMismatch', 'UPDATE', 'UnscopedModel', '__version__', 'purview-authz']

purview_authz-0.1.0/.hypothesis/constants/e286a1d7130798ef

@@ -0,0 +1,4 @@
+# file: /home/runner/work/purview/purview/src/purview/sqlalchemy/binding.py
+# hypothesis_version: 6.155.1
+
+['purview_context']

purview_authz-0.1.0/.hypothesis/constants/e9394f423b7d6fd0

@@ -0,0 +1,4 @@
+# file: /home/runner/work/purview/purview/src/purview/sqlalchemy/discovery.py
+# hypothesis_version: 6.155.1
+
+['mappers', 'registry']

purview_authz-0.1.0/.hypothesis/constants/eed7e26d6983f61b

@@ -0,0 +1,4 @@
+# file: /home/runner/work/purview/purview/src/purview/core/__init__.py
+# hypothesis_version: 6.155.1
+
+['Action', 'CREATE', 'Context', 'DELETE', 'Policy', 'READ', 'RuleFn', 'UPDATE', 'evaluate_predicate']

purview_authz-0.1.0/.hypothesis/constants/eedd831ee9ad9322

@@ -0,0 +1,4 @@
+# file: /home/runner/work/purview/purview/src/purview/sqlalchemy/read_guard.py
+# hypothesis_version: 6.155.1
+
+[]

purview_authz-0.1.0/.hypothesis/constants/f6a412b0488163fc

@@ -0,0 +1,4 @@
+# file: /home/runner/work/purview/purview/src/purview/core/actions.py
+# hypothesis_version: 6.155.1
+
+['create', 'delete', 'read', 'update']

purview_authz-0.1.0/.hypothesis/constants/fc154c4d6ab1ace6

@@ -0,0 +1,4 @@
+# file: /home/runner/work/purview/purview/src/purview/core/context.py
+# hypothesis_version: 6.155.1
+
+['T', 'U', 'roles']

purview_authz-0.1.0/.hypothesis/constants/fd12ac1cd14d2099

@@ -0,0 +1,4 @@
+# file: /home/runner/work/purview/purview/src/purview/sqlalchemy/checking.py
+# hypothesis_version: 6.155.1
+
+[]

purview_authz-0.1.0/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project adheres
+to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- **Core** (`purview.core`): `Context`, the `Policy` rule registry, and the
+  default-deny predicate combinator — framework-agnostic, no ORM-execution imports.
+- **SQLAlchemy engine** (`purview.sqlalchemy`): secure-by-default model discovery
+  with install-time validation; the `do_orm_execute` read guard (tenant scope +
+  fine-grained read predicates, propagating to lazy and eager relationship loads);
+  the `before_flush` write guard (tenant auto-stamp, forged-insert and
+  cross-tenant-move rejection); single and batch EXISTS checks; explicit
+  `authorized_select`; and the `bypass` escape hatch.
+- **FastAPI adapter** (`purview.fastapi`): `context_binder`, the `requires` route
+  guard, `authorize_or_403`, and a `PurviewForbidden`/`CrossTenantWrite` → 403
+  handler.
+- `install(..., strict=True)` for within-tenant default deny: a scoped model with
+  no read rule denies instead of defaulting to tenant-scope-only.
+- Test suite: unit (100% branch coverage on the combinator), integration
+  (parametrized over SQLite and Postgres), an adversarial leak suite, and a
+  runnable FastAPI example app.
+
+[Unreleased]: https://github.com/erichare/purview/commits/main

purview_authz-0.1.0/LICENSE

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

purview_authz-0.1.0/PKG-INFO

@@ -0,0 +1,239 @@
+Metadata-Version: 2.4
+Name: purview-authz
+Version: 0.1.0
+Summary: Row-level authorization and multi-tenancy for FastAPI + SQLAlchemy: define a policy once as column expressions and get both yes/no checks and query filtering from the same rule.
+Project-URL: Homepage, https://github.com/erichare/purview
+Project-URL: Repository, https://github.com/erichare/purview
+Project-URL: Issues, https://github.com/erichare/purview/issues
+Author: Eric Hare
+License-Expression: MIT
+License-File: LICENSE
+Keywords: abac,async,authorization,fastapi,multi-tenancy,rbac,row-level-security,sqlalchemy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: sqlalchemy[asyncio]<2.1,>=2.0
+Provides-Extra: dev
+Requires-Dist: aiosqlite>=0.20; extra == 'dev'
+Requires-Dist: asyncpg>=0.29; extra == 'dev'
+Requires-Dist: fastapi>=0.110; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: hypothesis>=6; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.110; extra == 'fastapi'
+Description-Content-Type: text/markdown
+
+# Purview
+
+**Row-level authorization and multi-tenancy for FastAPI + SQLAlchemy.** Define a
+policy once as SQLAlchemy column expressions and get both yes/no checks and query
+filtering from the same rule — so the check and the filter can never disagree.
+
+> Drift between "can this actor do this?" and "which rows can they see?" is a data
+> leak. Purview makes both come from one definition, so they cannot drift.
+
+```python
+@policy.rule(Post, "read")
+def read_post(ctx: Context) -> list[ColumnElement[bool]]:
+    rules = []
+    if ctx.has_role("author"):
+        rules.append(Post.author_id == ctx.user_id)   # authors see their own
+    if ctx.has_role("org_admin"):
+        rules.append(true())                           # admins see the whole tenant
+    return rules                                       # OR-combined; empty = deny
+```
+
+That one rule now powers a filtered `select(Post)` **and** an
+`authorize(session, "read", post)` check.
+
+## Why this exists
+
+Authentication generalizes; authorization does not, because it is welded to your
+domain model and data layer. The hard, valuable part is **data filtering**:
+shaping queries so a user only ever loads rows they're allowed to see, pushed into
+SQL rather than filtered in Python after the fact. [Oso](https://www.osohq.com/)
+solved this well and then deprecated its open-source library, leaving no idiomatic
+Python answer. Purview targets that gap for the FastAPI + SQLAlchemy stack
+specifically — in-process, async-first, no external policy service.
+
+## Install
+
+```bash
+pip install purview-authz            # core + SQLAlchemy
+pip install "purview-authz[fastapi]" # plus the FastAPI adapter
+```
+
+The distribution is `purview-authz`; the import package is `purview`. Requires
+Python 3.11+ and SQLAlchemy 2.0+.
+
+## Quickstart
+
+```python
+from sqlalchemy import true
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+from purview import Context, Policy, READ
+from purview.sqlalchemy import install
+
+class Base(DeclarativeBase): ...
+
+class Org(Base):                       # the tenant root — global
+    __tablename__ = "org"
+    id: Mapped[int] = mapped_column(primary_key=True)
+
+class Post(Base):                      # tenant-scoped (has the tenant column)
+    __tablename__ = "post"
+    id: Mapped[int] = mapped_column(primary_key=True)
+    org_id: Mapped[int] = mapped_column()
+    author_id: Mapped[int] = mapped_column()
+
+policy = Policy()
+policy.global_model(Org)               # opt Org out of tenant scoping
+
+@policy.rule(Post, READ)
+def read_post(ctx: Context):
+    return [Post.author_id == ctx.user_id] if ctx.has_role("author") else []
+
+pv = install(Base, policy, tenant_column="org_id")   # wires the guards; validates models
+```
+
+Bind a request's session to its actor, then query normally — reads are filtered
+automatically:
+
+```python
+async with async_session() as session:
+    pv.bind(session, Context(user_id=42, tenant_id=1, roles={"author"}))
+
+    posts = await session.scalars(select(Post))          # only org 1 + authored by 42
+    one   = await session.get(Post, 99)                  # None if not visible
+    ok    = await pv.authorize(session, "update", post)  # yes/no for one object
+    ids   = await pv.authorized_ids(session, "read", Post, [1, 2, 3])  # the allowed subset
+```
+
+## Core concepts
+
+**One definition, two forms.** A rule returns boolean `ColumnElement` predicates.
+As a `.where(...)` they filter a collection; wrapped in
+`EXISTS (SELECT 1 ... AND <predicate>)` they check a single object. The database
+evaluates both, so relationship and join predicates work without re-implementing
+SQL in Python.
+
+**Roles select predicates.** An actor's tenant-scoped roles decide which
+predicates apply for `(action, model)`. Grants are OR-combined; **no granting role
+means no rows — default deny.**
+
+**Tenancy is the session boundary.** One session is bound to exactly one tenant.
+A `do_orm_execute` hook scopes every read (including lazy and eager relationship
+loads) to that tenant; a `before_flush` hook auto-stamps the tenant on inserts and
+refuses writes that would cross the boundary.
+
+**Secure by default.** Every mapped model is tenant-scoped automatically. Opt a
+model out with `policy.global_model(...)`. `install()` **raises** if a non-global
+model lacks the tenant column — an unscoped table fails at startup, never leaks at
+runtime.
+
+**`read` drives filtering.** It is the action that shapes collections. Other
+actions are instance-level checks; `update`/`delete` reuse the `read` predicate
+unless you register a stricter rule for them.
+
+**Within-tenant default.** A scoped model with *no* read rule is visible
+tenant-wide (tenant isolation still applies). Pass `install(..., strict=True)` to
+flip this to within-tenant **default deny** — every model then needs an explicit
+rule to grant any access. The cross-tenant boundary is enforced identically in
+both modes.
+
+## The enforcement boundary
+
+Inside the boundary: ORM `select`s, `session.get`, relationship loads, and flushes
+on a bound session.
+
+Outside the boundary (documented, not enforced):
+
+- **Raw SQL and Core `text()`** — Purview shapes ORM statements, not hand-written SQL.
+- **Implicit lazy loads under async** — these raise `MissingGreenlet` in SQLAlchemy
+  regardless; use `selectinload(...)` or `await obj.awaitable_attrs.x`. Eager and
+  awaitable lazy loads *are* filtered.
+- **Unbound sessions** — a session with no bound context is not filtered (this is
+  how you seed and run migrations).
+
+### Escape hatch
+
+One loud, greppable bypass for admin tooling and migrations:
+
+```python
+from purview.sqlalchemy import bypass
+
+with bypass(reason="nightly billing rollup"):
+    ...   # enforcement stands down on this task; the reason is logged at WARNING
+```
+
+## FastAPI
+
+```python
+from purview.fastapi import context_binder, authorize_or_403, install_error_handlers
+
+install_error_handlers(app)                              # PurviewForbidden -> 403
+bound = context_binder(pv, get_session, get_context)     # binds the actor per request
+
+@app.get("/posts")
+async def list_posts(session: AsyncSession = Depends(bound)):
+    return (await session.scalars(select(Post))).all()   # auto-filtered
+
+@app.patch("/posts/{post_id}")
+async def edit(post_id: int, session: AsyncSession = Depends(bound)):
+    post = await session.get(Post, post_id)              # 404 if not visible
+    await authorize_or_403(pv, session, "update", post)  # 403 if not permitted
+    ...
+```
+
+See [`tests/examples/test_blog_app.py`](tests/examples/test_blog_app.py) for a
+complete, runnable app.
+
+## How it compares
+
+|                          | Purview | Oso (OSS) | Cerbos | Casbin |
+|--------------------------|:-------:|:---------:|:------:|:------:|
+| In-process (no network)  | ✅ | ✅ | ❌ service | ✅ |
+| SQL data filtering       | ✅ | ✅ | ✅ | ❌ |
+| One def → check + filter  | ✅ | ✅ | ➖ | ❌ |
+| SQLAlchemy 2.0 async     | ✅ | ❌ | ✅ adapter | ➖ |
+| Policy in native Python  | ✅ | Polar DSL | YAML | model+CSV |
+| Maintained               | ✅ | deprecated 2023 | ✅ | ✅ |
+
+## Scope (v1)
+
+**In:** row-level filtering, multi-tenancy as a structural concern, yes/no checks
+and query filtering from one definition, SQLAlchemy 2.0 async, FastAPI adapter.
+
+**Out (for now):** field-level authorization (belongs in serialization),
+non-SQLAlchemy ORMs, a hosted policy service, Postgres RLS as a compile target.
+
+## Development
+
+```bash
+uv run --extra dev pytest          # unit + integration + the example app
+uv run --extra dev mypy            # strict typing is a project invariant
+uv run --extra dev ruff check .
+```
+
+Postgres fidelity is exercised in CI; set `PURVIEW_TEST_POSTGRES_URL` to run the
+integration matrix against a local Postgres too.
+
+Releases publish to PyPI on a version tag via Trusted Publishing (no stored token);
+the version is derived from the tag. See [RELEASING.md](RELEASING.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE).