Source code for auth_middleware.authz.stores.sql

"""SQLAlchemy assignment store (injected session, tenant-aware, optimistic writes)."""

from __future__ import annotations

from collections.abc import AsyncIterator, Awaitable, Callable, Sequence
from contextlib import asynccontextmanager
from datetime import UTC, datetime
from typing import Any

from auth_middleware.authz.errors import ConfigurationError, RevisionConflictError
from auth_middleware.authz.types import (
    Assignment,
    AssignmentStatus,
    NewAssignment,
    ScopeRef,
)

try:
    from ksuid import Ksuid
    from sqlalchemy import MetaData, Table, insert, select, update
    from sqlalchemy.exc import IntegrityError
    from sqlalchemy.ext.asyncio import AsyncSession
except ImportError as exc:  # pragma: no cover - exercised without the extra
    raise ImportError(
        "the SQL assignment store needs SQLAlchemy: "
        "pip install 'auth-middleware[sqlalchemy]'"
    ) from exc

from auth_middleware.authz.stores.sql_models import DEFAULT_TABLE_NAME, build_table

BeforeQuery = Callable[["AsyncSession", "ScopeRef | None"], Awaitable[None]]


def _is_duplicate_key(exc: IntegrityError) -> bool:
    """Whether an IntegrityError is a unique/duplicate-key violation (any backend)."""
    text = str(exc.orig).lower()
    return any(m in text for m in ("unique", "duplicate"))


[docs] class SqlAssignmentStore: """``AssignmentStore`` + ``AssignmentAdmin`` over a SQL table. Three ways to inject a session: 1. ``async_sessionmaker``: a short session per call (singleton store). 2. A callable returning an async context manager yielding a session. 3. An already open ``AsyncSession`` (per-request store built by a ``StoreFactory``): the store never commits, rolls back or closes it, so reads and writes happen in the caller's transaction. Args: session_provider: One of the three shapes above. table_name: Table name (a plain SQL identifier). before_query: Awaited before every statement with the session and the scope (``None`` for the cross-scope ``list_assignments``). This is where an application binds row-level security. Exceptions propagate. commit: Commit after writes when the store owns the session. Forced off for an injected open session. """ supports_attributes = True
[docs] def __init__( self, session_provider: Any, *, table_name: str = DEFAULT_TABLE_NAME, before_query: BeforeQuery | None = None, commit: bool = True, ) -> None: self._provider = session_provider self._table: Table = build_table(MetaData(), table_name) self._before = before_query self._injected = isinstance(session_provider, AsyncSession) if not commit and not self._injected: # An owned session that is never committed silently discards writes # (while ``assign`` would still return the re-read row). raise ConfigurationError( "commit=False only makes sense with an injected AsyncSession" ) self._commit = commit and not self._injected
@asynccontextmanager async def _session(self) -> AsyncIterator[AsyncSession]: provider = self._provider if isinstance(provider, AsyncSession): yield provider else: # async_sessionmaker or a callable returning an async context manager async with provider() as session: yield session async def _run( self, session: AsyncSession, scope: ScopeRef | None, stmt: Any ) -> Any: if self._before is not None: await self._before(session, scope) return await session.execute(stmt) def _where(self, principal_id: str, scope: ScopeRef) -> Any: t = self._table.c return ( (t.principal_id == principal_id) & (t.scope_kind == scope.kind) & (t.scope_id == scope.id) ) def _to_assignment(self, row: Any) -> Assignment: created = row.created_at if created is not None and created.tzinfo is None: created = created.replace(tzinfo=UTC) return Assignment( principal_id=row.principal_id, scope=ScopeRef(row.scope_kind, row.scope_id), role=row.role, status=AssignmentStatus(row.status), revision=row.revision, created_at=created, attributes=dict(row.attributes or {}), ) async def _fetch( self, session: AsyncSession, principal_id: str, scope: ScopeRef ) -> Any: stmt = select(self._table).where(self._where(principal_id, scope)) return (await self._run(session, scope, stmt)).first()
[docs] async def get_assignment( self, principal_id: str, scope: ScopeRef ) -> Assignment | None: async with self._session() as session: row = await self._fetch(session, principal_id, scope) return None if row is None else self._to_assignment(row)
[docs] async def list_assignments(self, principal_id: str) -> Sequence[Assignment]: async with self._session() as session: stmt = select(self._table).where(self._table.c.principal_id == principal_id) rows = (await self._run(session, None, stmt)).all() return [self._to_assignment(r) for r in rows]
[docs] async def list_for_scope(self, scope: ScopeRef) -> Sequence[Assignment]: async with self._session() as session: t = self._table.c stmt = select(self._table).where( (t.scope_kind == scope.kind) & (t.scope_id == scope.id) ) rows = (await self._run(session, scope, stmt)).all() return [self._to_assignment(r) for r in rows]
[docs] async def assign(self, new: NewAssignment) -> Assignment: async with self._session() as session: row = await self._fetch(session, new.principal_id, new.scope) now = datetime.now(UTC) if row is None: await self._insert(session, new, now) elif row.status == AssignmentStatus.ACTIVE: raise RevisionConflictError("assignment already active") else: await self._write( session, row, row.revision, role=new.role, status=AssignmentStatus.ACTIVE.value, attributes=dict(new.attributes), ) # Re-read inside the transaction, before committing: our row is locked by # our own write, so the result cannot show another writer's changes. result = await self._reload(session, new.principal_id, new.scope) await self._finish(session) return result
async def _insert( self, session: AsyncSession, new: NewAssignment, now: datetime ) -> None: stmt = insert(self._table).values( id=str(Ksuid()), principal_id=new.principal_id, scope_kind=new.scope.kind, scope_id=new.scope.id, role=new.role, status=AssignmentStatus.ACTIVE.value, revision=0, created_at=now, updated_at=now, attributes=dict(new.attributes), ) try: if self._injected: # A failed INSERT must not poison the caller's transaction. async with session.begin_nested(): await self._run(session, new.scope, stmt) else: await self._run(session, new.scope, stmt) except IntegrityError as exc: if not self._injected: await session.rollback() # Only a duplicate key is a revision conflict; a CHECK/NOT NULL/length # violation is a real error and must not be mislabelled. if not _is_duplicate_key(exc): raise raise RevisionConflictError("assignment already exists") from None async def _write( self, session: AsyncSession, row: Any, expected: int, **values: Any ) -> None: t = self._table.c stmt = ( update(self._table) .where((t.id == row.id) & (t.revision == expected)) .values(revision=expected + 1, updated_at=datetime.now(UTC), **values) ) result = await self._run(session, ScopeRef(row.scope_kind, row.scope_id), stmt) if result.rowcount != 1: raise RevisionConflictError("stale revision") async def _finish(self, session: AsyncSession) -> None: if self._commit: await session.commit() elif self._injected: await session.flush() async def _reload( self, session: AsyncSession, principal_id: str, scope: ScopeRef ) -> Assignment: row = await self._fetch(session, principal_id, scope) if row is None: # pragma: no cover - defensive raise RevisionConflictError("assignment vanished") return self._to_assignment(row) async def _mutate( self, principal_id: str, scope: ScopeRef, expected_revision: int, **values: Any, ) -> Assignment: async with self._session() as session: row = await self._fetch(session, principal_id, scope) if ( row is None or row.status != AssignmentStatus.ACTIVE or row.revision != expected_revision ): raise RevisionConflictError("stale revision or no active assignment") await self._write(session, row, expected_revision, **values) result = await self._reload(session, principal_id, scope) await self._finish(session) return result
[docs] async def change_role( self, principal_id: str, scope: ScopeRef, role: str, *, expected_revision: int ) -> Assignment: return await self._mutate(principal_id, scope, expected_revision, role=role)
[docs] async def revoke( self, principal_id: str, scope: ScopeRef, *, expected_revision: int ) -> Assignment: return await self._mutate( principal_id, scope, expected_revision, status=AssignmentStatus.REVOKED.value, )