Source code for auth_middleware.authz.stores.dynamodb

"""DynamoDB assignment store, built on PynamoDB.

PynamoDB is synchronous, so every call runs in a worker thread
(``asyncio.to_thread``) and never blocks the event loop.

Single-table design (on-demand billing recommended):

=============  ============================  ================================
Attribute      Value                         Purpose
=============  ============================  ================================
``pk`` (HASH)  ``SCOPE#<kind>#<id>``         one partition per scope
``sk`` (RANGE) ``PRINCIPAL#<principal_id>``  one item per (scope, principal)
``gsi1pk``     ``PRINCIPAL#<principal_id>``  GSI ``by-principal`` HASH
``gsi1sk``     ``SCOPE#<kind>#<id>``         GSI ``by-principal`` RANGE
=============  ============================  ================================

Payload: ``principal_id``, ``scope_kind``, ``scope_id``, ``role``, ``status``,
``revision`` (N), ``created_at``, ``updated_at`` and ``attrs_json`` (a JSON
string, at most 4 KB, to avoid DynamoDB's float/Decimal map pitfalls).

Consistency: ``get_assignment`` (the guard path) uses ``ConsistentRead=True`` by
default so a just-revoked principal is never admitted. A GSI only supports
eventually consistent reads, so ``list_assignments`` ("my scopes") may lag by a
moment; the guard never uses it. Writes are conditional (optimistic ``revision``).
Use botocore retries (adaptive mode) for throttling; what still fails is raised as
``StoreUnavailableError``.
"""

from __future__ import annotations

import asyncio
import json
from collections.abc import Callable, Sequence
from concurrent.futures import ThreadPoolExecutor
from datetime import UTC, datetime
from typing import Any, Literal, TypeVar

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

try:
    from pynamodb.attributes import (
        NumberAttribute,
        UnicodeAttribute,
        UTCDateTimeAttribute,
    )
    from pynamodb.constants import PAY_PER_REQUEST_BILLING_MODE
    from pynamodb.exceptions import (
        DoesNotExist,
        PynamoDBConnectionError,
        PynamoDBException,
    )
    from pynamodb.indexes import AllProjection, GlobalSecondaryIndex
    from pynamodb.models import Model
except ImportError as exc:  # pragma: no cover - exercised without the extra
    raise ImportError(
        "the DynamoDB assignment store needs PynamoDB: "
        "pip install 'auth-middleware[dynamodb]'"
    ) from exc

DEFAULT_INDEX_NAME = "by-principal"
MAX_ATTRIBUTES_BYTES = 4096
_UNAVAILABLE_CODES = frozenset(
    {
        "ProvisionedThroughputExceededException",
        "ThrottlingException",
        "RequestLimitExceeded",
        "InternalServerError",
        "ServiceUnavailable",
    }
)
_CONDITIONAL = "ConditionalCheckFailedException"
T = TypeVar("T")


def _scope_key(scope: ScopeRef) -> str:
    return f"SCOPE#{scope.kind}#{scope.id}"


def _principal_key(principal_id: str) -> str:
    return f"PRINCIPAL#{principal_id}"


def _build_models(
    table_name: str, index_name: str, meta: dict[str, Any]
) -> tuple[Any, Any]:
    """Create the PynamoDB model classes bound to a runtime table name."""
    gsi_name = index_name

    class ByPrincipal(GlobalSecondaryIndex):  # type: ignore[type-arg,no-untyped-call,misc,unused-ignore]
        class Meta:
            index_name = gsi_name
            projection = AllProjection()

        gsi1pk = UnicodeAttribute(hash_key=True)
        gsi1sk = UnicodeAttribute(range_key=True)

    meta_attrs = {
        "table_name": table_name,
        "billing_mode": PAY_PER_REQUEST_BILLING_MODE,
    }
    meta_attrs.update(meta)
    meta_cls = type("Meta", (), meta_attrs)

    class Item(Model):  # type: ignore[misc,unused-ignore]
        Meta = meta_cls  # type: ignore[assignment,unused-ignore]
        pk = UnicodeAttribute(hash_key=True)
        sk = UnicodeAttribute(range_key=True)
        gsi1pk = UnicodeAttribute()
        gsi1sk = UnicodeAttribute()
        principal_id = UnicodeAttribute()
        scope_kind = UnicodeAttribute()
        scope_id = UnicodeAttribute()
        role = UnicodeAttribute()
        status = UnicodeAttribute()
        revision = NumberAttribute(default=0)
        created_at = UTCDateTimeAttribute()
        updated_at = UTCDateTimeAttribute()
        attrs_json = UnicodeAttribute(default="{}")
        by_principal = ByPrincipal()

    return Item, ByPrincipal


[docs] class DynamoDbAssignmentStore: """``AssignmentStore`` + ``AssignmentAdmin`` over a single DynamoDB table. Args: table_name: Existing table (see :meth:`table_definition`). region: AWS region; default from the botocore chain. endpoint_url: Custom endpoint (DynamoDB Local, emulators, tests). index_name: Name of the by-principal GSI. consistent_read: Consistent reads on ``get_assignment`` (default, and required to never admit a just-revoked principal). Turning it off accepts staleness: only for callers that explicitly want it. connect_timeout_seconds: botocore connect timeout. read_timeout_seconds: botocore read timeout. max_retry_attempts: botocore retries (throttling backoff). aws_access_key_id: Explicit credentials, for tests only; otherwise the botocore credential chain is used (nothing is read from code). aws_secret_access_key: Explicit credentials, for tests only. max_workers: Size of a dedicated thread pool for the blocking PynamoDB calls. ``None`` uses the event loop's default executor, shared with the rest of the application. """ supports_attributes = True
[docs] def __init__( self, *, table_name: str, region: str | None = None, endpoint_url: str | None = None, index_name: str = DEFAULT_INDEX_NAME, consistent_read: bool = True, connect_timeout_seconds: int = 5, read_timeout_seconds: int = 10, max_retry_attempts: int = 5, aws_access_key_id: str | None = None, aws_secret_access_key: str | None = None, max_workers: int | None = None, ) -> None: meta: dict[str, Any] = { "connect_timeout_seconds": connect_timeout_seconds, "read_timeout_seconds": read_timeout_seconds, "max_retry_attempts": max_retry_attempts, } if region: meta["region"] = region if endpoint_url: meta["host"] = endpoint_url if aws_access_key_id: meta["aws_access_key_id"] = aws_access_key_id if aws_secret_access_key: meta["aws_secret_access_key"] = aws_secret_access_key # A dedicated, bounded pool keeps a slow DynamoDB from starving the other # users of the event loop's default executor (and bounds our own concurrency). self._executor = ( ThreadPoolExecutor(max_workers, thread_name_prefix="authz-dynamodb") if max_workers else None ) self.table_name = table_name self.index_name = index_name self.consistent_read = consistent_read self._item, self._gsi = _build_models(table_name, index_name, meta)
# ------------------------------------------------------------------ helpers @staticmethod def _encode_attributes(attributes: Any) -> str: data = json.dumps(dict(attributes), separators=(",", ":"), sort_keys=True) if len(data.encode("utf-8")) > MAX_ATTRIBUTES_BYTES: raise ValueError(f"attributes larger than {MAX_ATTRIBUTES_BYTES} bytes") return data async def _call(self, fn: Callable[[], T]) -> T: """Run a blocking PynamoDB call in a thread, mapping errors.""" try: if self._executor is None: return await asyncio.to_thread(fn) return await asyncio.get_running_loop().run_in_executor(self._executor, fn) except PynamoDBException as exc: code = getattr(exc, "cause_response_code", None) if code == _CONDITIONAL: raise RevisionConflictError("conditional check failed") from None if code in _UNAVAILABLE_CODES or isinstance(exc, PynamoDBConnectionError): # throttling, server errors, timeouts and unreachable endpoints raise StoreUnavailableError("DynamoDB is unavailable") from None raise def _to_assignment(self, item: Any) -> Assignment: return Assignment( principal_id=item.principal_id, scope=ScopeRef(item.scope_kind, item.scope_id), role=item.role, status=AssignmentStatus(item.status), revision=int(item.revision), created_at=item.created_at.astimezone(UTC), attributes=json.loads(item.attrs_json or "{}"), ) def _get(self, principal_id: str, scope: ScopeRef) -> Any | None: try: return self._item.get( _scope_key(scope), _principal_key(principal_id), consistent_read=self.consistent_read, ) except DoesNotExist: return None # --------------------------------------------------------------------- reads
[docs] async def get_assignment( self, principal_id: str, scope: ScopeRef ) -> Assignment | None: item = await self._call(lambda: self._get(principal_id, scope)) return None if item is None else self._to_assignment(item)
[docs] async def list_for_scope(self, scope: ScopeRef) -> Sequence[Assignment]: def run() -> list[Any]: return list( self._item.query( _scope_key(scope), self._item.sk.startswith("PRINCIPAL#"), consistent_read=True, ) ) return [self._to_assignment(i) for i in await self._call(run)]
[docs] async def list_assignments(self, principal_id: str) -> Sequence[Assignment]: """List a principal's scopes via the GSI (eventually consistent).""" def run() -> list[Any]: return list( self._item.by_principal.query( _principal_key(principal_id), self._item.gsi1sk.startswith("SCOPE#"), ) ) return [self._to_assignment(i) for i in await self._call(run)]
# -------------------------------------------------------------------- writes
[docs] async def assign(self, new: NewAssignment) -> Assignment: attrs = self._encode_attributes(new.attributes) existing = await self._call(lambda: self._get(new.principal_id, new.scope)) now = datetime.now(UTC) item_cls = self._item if existing is None: item = item_cls( _scope_key(new.scope), _principal_key(new.principal_id), gsi1pk=_principal_key(new.principal_id), gsi1sk=_scope_key(new.scope), 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, attrs_json=attrs, ) await self._call(lambda: item.save(condition=item_cls.pk.does_not_exist())) return self._to_assignment(item) if existing.status == AssignmentStatus.ACTIVE.value: raise RevisionConflictError("assignment already active") return await self._update( existing, expected=int(existing.revision), required_status=AssignmentStatus.REVOKED.value, actions=[ item_cls.role.set(new.role), item_cls.status.set(AssignmentStatus.ACTIVE.value), item_cls.attrs_json.set(attrs), ], )
async def _update( self, item: Any, *, expected: int, required_status: str, actions: list[Any] ) -> Assignment: item_cls = self._item condition = (item_cls.revision == expected) & ( item_cls.status == required_status ) actions = [ *actions, item_cls.revision.add(1), item_cls.updated_at.set(datetime.now(UTC)), ] await self._call(lambda: item.update(actions=actions, condition=condition)) return self._to_assignment(item) async def _mutate( self, principal_id: str, scope: ScopeRef, expected_revision: int, actions: list[Any], ) -> Assignment: item = await self._call(lambda: self._get(principal_id, scope)) if ( item is None or item.status != AssignmentStatus.ACTIVE.value or int(item.revision) != expected_revision ): raise RevisionConflictError("stale revision or no active assignment") return await self._update( item, expected=expected_revision, required_status=AssignmentStatus.ACTIVE.value, actions=actions, )
[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, [self._item.role.set(role)] )
[docs] async def revoke( self, principal_id: str, scope: ScopeRef, *, expected_revision: int ) -> Assignment: return await self._mutate( principal_id, scope, expected_revision, [self._item.status.set(AssignmentStatus.REVOKED.value)], )
# ---------------------------------------------------------------- operations
[docs] async def aclose(self) -> None: """Stop the dedicated worker pool, if any (PynamoDB manages its client).""" if self._executor is not None: self._executor.shutdown(wait=False)
[docs] @staticmethod def table_definition( table_name: str, *, billing: Literal["PAY_PER_REQUEST"] = "PAY_PER_REQUEST", index_name: str = DEFAULT_INDEX_NAME, ) -> dict[str, Any]: """Return ``boto3`` ``create_table`` keyword arguments for the table.""" return { "TableName": table_name, "BillingMode": billing, "AttributeDefinitions": [ {"AttributeName": "pk", "AttributeType": "S"}, {"AttributeName": "sk", "AttributeType": "S"}, {"AttributeName": "gsi1pk", "AttributeType": "S"}, {"AttributeName": "gsi1sk", "AttributeType": "S"}, ], "KeySchema": [ {"AttributeName": "pk", "KeyType": "HASH"}, {"AttributeName": "sk", "KeyType": "RANGE"}, ], "GlobalSecondaryIndexes": [ { "IndexName": index_name, "KeySchema": [ {"AttributeName": "gsi1pk", "KeyType": "HASH"}, {"AttributeName": "gsi1sk", "KeyType": "RANGE"}, ], "Projection": {"ProjectionType": "ALL"}, } ], }
[docs] async def create_table_if_missing(self) -> None: """Create the table (and GSI) if absent. Dev/tests only; never implicit.""" def run() -> None: if not self._item.exists(): self._item.create_table(wait=True) await self._call(run)
__all__ = ["DynamoDbAssignmentStore"]