import dataclasses
from abc import abstractmethod
from collections.abc import Mapping, Sequence
from http import HTTPStatus
from typing import (
TYPE_CHECKING,
Final,
Generic,
Literal,
Self,
TypeVar,
final,
overload,
)
from django.http import HttpRequest
from typing_extensions import override
from dmr.exceptions import NotAuthenticatedError
from dmr.headers import HeaderSpec, NewHeader
from dmr.internal.compat import frozen
from dmr.metadata import EndpointMetadata, ResponseSpec, ResponseSpecProvider
from dmr.semantic_schema import SecurityProvider
if TYPE_CHECKING:
from dmr.controller import Controller
from dmr.endpoint import Endpoint
from dmr.serializer import BaseSerializer
#: Name of the header that carries auth challenges in `401` responses:
_WWW_AUTHENTICATE: Final = 'WWW-Authenticate'
#: Header spec for the `_WWW_AUTHENTICATE` header:
_WWW_AUTHENTICATE_SPEC: Final = HeaderSpec(
description=(
'Challenges that the client can use to authenticate this request'
),
# A `401` can also be raised by hand from an endpoint body,
# and then we have no auth instance to build a challenge from.
# So, we document the header, but never enforce it in runtime.
skip_validation=True,
)
#: Headers that every view issuing or accepting credentials must return.
#: Responses of such views must never be written to any cache,
#: neither shared, nor local.
NO_STORE_HEADERS: Final = frozen({
'Cache-Control': NewHeader(
value='no-store',
description='Credentials must not be stored in any cache.',
),
})
[docs]
def unauth_response_spec(
controller_cls: type['Controller[BaseSerializer]'],
metadata: EndpointMetadata | None = None,
) -> ResponseSpec:
"""
Defines the default unauthed response spec.
When *metadata* is passed and its auth chain can produce
a ``WWW-Authenticate`` challenge, we also document that header.
"""
has_challenge = (
metadata is not None
and _combined_www_authenticate(metadata.auth) is not None
)
return ResponseSpec(
controller_cls.error_model,
status_code=NotAuthenticatedError.status_code,
description='Raised when auth was not successful',
headers=(
{_WWW_AUTHENTICATE: _WWW_AUTHENTICATE_SPEC}
if has_challenge
else None
),
)
[docs]
def add_www_authenticate(
exc: NotAuthenticatedError,
auth: Sequence['SyncAuth | AsyncAuth'] | None,
) -> None:
"""
Advertise *auth* in ``WWW-Authenticate`` on the ``401`` that *exc* returns.
:rfc:`9110#section-15.5.2` requires every ``401`` to carry at least one
challenge. Headers that *exc* already has always win, so an auth class
can raise with a challenge of its own.
"""
if exc.headers is not None:
return
challenge = _combined_www_authenticate(auth)
if challenge is not None:
exc.headers = {_WWW_AUTHENTICATE: challenge}
def _combined_www_authenticate(
auth: Sequence['SyncAuth | AsyncAuth'] | None,
) -> str | None:
"""
Join ``WWW-Authenticate`` challenges of *auth* into a single header value.
:rfc:`9110#section-11.6.1` allows a challenge list,
so an endpoint with several auth instances advertises all of them at once.
Returns ``None`` when no auth in the chain has a challenge to send.
"""
if not auth:
return None
all_challenges = [single.www_authenticate_challenge for single in auth]
# `dict.fromkeys` removes duplicates, but keeps the original order:
challenges = dict.fromkeys(
challenge for challenge in all_challenges if challenge
)
return ', '.join(challenges) or None
class _BaseAuth(ResponseSpecProvider, SecurityProvider):
"""
Base class for all auth instances.
.. note::
It is really important for this class to have stateless instances.
Not even locks can be shared, because these instances can
be global. It is possible to use them in settings or per controller.
No state allowed.
"""
__slots__ = ()
@property
@abstractmethod
def www_authenticate_challenge(self) -> str | None:
"""
Challenge to advertise in ``WWW-Authenticate`` on ``401`` responses.
:rfc:`9110#section-15.5.2` requires every ``401`` to carry at least
one challenge, but a challenge can only name an HTTP authentication
scheme that the client sends in the ``Authorization`` header.
Return ``None`` when there is nothing to advertise: auth that reads
credentials from a cookie or from a header of its own cannot
express itself as a challenge.
.. versionadded:: 0.15.0
"""
raise NotImplementedError
def validate(
self,
controller_cls: type['Controller[BaseSerializer]'],
metadata: EndpointMetadata,
) -> None:
"""
Validate auth configuration at import time.
.. versionadded:: 0.16.0
"""
@override
def provide_response_specs(
self,
metadata: EndpointMetadata,
controller_cls: type['Controller[BaseSerializer]'],
existing_responses: Mapping[HTTPStatus, ResponseSpec],
) -> list[ResponseSpec]:
"""Provides responses that can happen when user is not authed."""
return self._add_new_response(
unauth_response_spec(controller_cls, metadata),
existing_responses,
)
[docs]
class SyncAuth(_BaseAuth):
"""
Sync auth base class for sync endpoints.
All auth must support initialization without any required parameters.
Auth can have non-required parameters with defaults.
"""
__slots__ = ()
[docs]
@abstractmethod
def __call__(
self,
endpoint: 'Endpoint',
controller: 'Controller[BaseSerializer]',
) -> Self | None:
"""
Put your auth business logic here.
Return ``self`` if the login attempt was successful.
Return ``None`` if login attempt failed and we need
to try another authes.
Raise :exc:`dmr.exceptions.NotAuthenticatedError`
to immediately fail the login without trying other authes.
Raise :exc:`dmr.response.APIError`
if you want to change the return code, for example,
when some data is missing or has wrong format.
"""
[docs]
class AsyncAuth(_BaseAuth):
"""
Async auth base class for async endpoints.
All auth must support initialization without any required parameters.
Auth can have non-required parameters with defaults.
"""
__slots__ = ()
[docs]
@abstractmethod
async def __call__(
self,
endpoint: 'Endpoint',
controller: 'Controller[BaseSerializer]',
) -> Self | None:
"""
Put your auth business logic here.
Return ``self`` if the login attempt was successful.
Return ``None`` if login attempt failed and we need
to try another authes.
Raise :exc:`dmr.exceptions.NotAuthenticatedError`
to immediately fail the login without trying other authes.
Raise :exc:`dmr.response.APIError`
if you want to change the return code, for example,
when some data is missing or has wrong format.
"""
_SyncAuthT = TypeVar('_SyncAuthT', bound='SyncAuth')
_AsyncAuthT = TypeVar('_AsyncAuthT', bound='AsyncAuth')
[docs]
@final
@dataclasses.dataclass(slots=True, frozen=True)
class SyncOrAsyncAuth(Generic[_SyncAuthT, _AsyncAuthT]):
"""
Auth that selects between a sync and async instance.
Use in global settings to apply a single auth rule to both
sync and async endpoints. Not allowed on controller or endpoint level.
.. versionadded:: 0.11.0
.. versionchanged:: 0.16.0
Now it is generic.
"""
_sync_auth: _SyncAuthT
_async_auth: _AsyncAuthT
@overload
def resolve(self, *, is_async: Literal[True]) -> _AsyncAuthT: ...
@overload
def resolve(self, *, is_async: Literal[False]) -> _SyncAuthT: ...
@overload
def resolve(self, *, is_async: bool) -> _AsyncAuthT | _SyncAuthT: ...
[docs]
def resolve(
self,
*,
is_async: bool,
) -> _AsyncAuthT | _SyncAuthT:
"""
Return the auth instance matching *is_async* requirement.
.. versionchanged:: 0.16.0
Replaced *auth_cls* parameter with simpler *is_async*.
"""
if is_async:
return self._async_auth
return self._sync_auth
@overload
def request_auth(
request: HttpRequest,
*,
strict: Literal[True],
) -> SyncAuth | AsyncAuth: ...
@overload
def request_auth(
request: HttpRequest,
*,
strict: bool = False,
) -> SyncAuth | AsyncAuth | None: ...
[docs]
def request_auth(
request: HttpRequest,
*,
strict: bool = False,
) -> SyncAuth | AsyncAuth | None:
"""
Return the auth instance that was used to auth this request.
When *strict* is passed and *request* has no auth,
we raise :exc:`AttributeError`.
"""
auth = getattr(request, '__dmr_auth__', None)
if auth is None and strict:
raise AttributeError('__dmr_auth__')
return auth