plain.auth 0.0.0__tar.gz

plain_auth-0.0.0/LICENSE

@@ -0,0 +1,61 @@
+## Plain is released under the BSD 3-Clause License
+
+BSD 3-Clause License
+
+Copyright (c) 2023, Dropseed, LLC
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
+## This package contains code forked from github.com/django/django
+
+Copyright (c) Django Software Foundation and individual contributors.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+    1. Redistributions of source code must retain the above copyright notice,
+       this list of conditions and the following disclaimer.
+
+    2. Redistributions in binary form must reproduce the above copyright
+       notice, this list of conditions and the following disclaimer in the
+       documentation and/or other materials provided with the distribution.
+
+    3. Neither the name of Django nor the names of its contributors may be used
+       to endorse or promote products derived from this software without
+       specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

plain_auth-0.0.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.1
+Name: plain.auth
+Version: 0.0.0
+Summary: 
+Author: Dave Gaeddert
+Author-email: dave.gaeddert@dropseed.dev
+Requires-Python: >=3.11,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12

plain_auth-0.0.0/plain/auth/README.md

@@ -0,0 +1,123 @@
+# plain-auth
+
+Add users to your app and define which views they can access.
+
+To log a user in, you'll want to pair this package with:
+
+- `plain-passwords`
+- `plain-oauth`
+- `plain-passkeys` (TBD)
+- `plain-passlinks` (TBD)
+
+## Installation
+
+```python
+# app/settings.py
+INSTALLED_PACKAGES = [
+    # ...
+    "plain.auth",
+    "plain.sessions",
+    "plain.passwords",
+]
+
+MIDDLEWARE = [
+    "plain.middleware.security.SecurityMiddleware",
+    "plain.assets.whitenoise.middleware.WhiteNoiseMiddleware",
+    "plain.sessions.middleware.SessionMiddleware",  # <--
+    "plain.middleware.common.CommonMiddleware",
+    "plain.csrf.middleware.CsrfViewMiddleware",
+    "plain.auth.middleware.AuthenticationMiddleware",  # <--
+    "plain.middleware.clickjacking.XFrameOptionsMiddleware",
+]
+
+AUTH_USER_MODEL = "users.User"
+AUTH_LOGIN_URL = "login"
+```
+
+Create your own user model (`plain create users`).
+
+```python
+# app/users/models.py
+from plain import models
+from plain.passwords.models import PasswordField
+
+
+class User(models.Model):
+    email = models.EmailField(unique=True)
+    password = PasswordField()
+    is_staff = models.BooleanField(default=False)
+    created_at = models.DateTimeField(auto_now_add=True)
+
+    def __str__(self):
+        return self.email
+```
+
+Define your URL/view where users can log in.
+
+```python
+# app/urls.py
+from plain.auth.views import LoginView, LogoutView
+from plain.urls import include, path
+from plain.passwords.views import PasswordLoginView
+
+
+class LoginView(PasswordLoginView):
+    template_name = "login.html"
+
+
+urlpatterns = [
+    path("logout/", LogoutView, name="logout"),
+    path("login/", LoginView, name="login"),
+]
+```
+
+
+## Checking if a user is logged in
+
+A `request.user` will either be `None` or point to an instance of a your `AUTH_USER_MODEL`.
+
+So in templates you can do:
+
+```html
+{% if request.user %}
+    <p>Hello, {{ request.user.email }}!</p>
+{% else %}
+    <p>You are not logged in.</p>
+{% endif %}
+```
+
+Or in Python:
+
+```python
+if request.user:
+    print(f"Hello, {request.user.email}!")
+else:
+    print("You are not logged in.")
+```
+
+
+## Restricting views
+
+Use the `AuthViewMixin` to restrict views to logged in users, staff users, or custom logic.
+
+```python
+from plain.auth.views import AuthViewMixin
+from plain.exceptions import PermissionDenied
+from plain.views import View
+
+
+class LoggedInView(AuthViewMixin, View):
+    login_required = True
+
+
+class StaffOnlyView(AuthViewMixin, View):
+    login_required = True
+    staff_required = True
+
+
+class CustomPermissionView(AuthViewMixin, View):
+    def check_auth(self):
+        super().check_auth()
+        if not self.request.user.is_special:
+            raise PermissionDenied("You're not special!")
+```

plain_auth-0.0.0/plain/auth/__init__.py

@@ -0,0 +1,3 @@
+from .sessions import get_user, get_user_model, login, logout
+
+__all__ = ["login", "logout", "get_user_model", "get_user"]

plain_auth-0.0.0/plain/auth/config.py

@@ -0,0 +1,5 @@
+from plain.packages import PackageConfig
+
+
+class AuthConfig(PackageConfig):
+    name = "plain.auth"

plain_auth-0.0.0/plain/auth/default_settings.py

@@ -0,0 +1,13 @@
+from importlib.util import find_spec
+
+AUTH_USER_MODEL: str
+AUTH_LOGIN_URL: str
+
+if find_spec("plain.passwords"):
+    # Automatically invalidate sessions on password field change,
+    # if the plain-passwords is installed. You can change this value
+    # if your password field is named differently, or you want
+    # to use a different field to invalidate sessions.
+    AUTH_USER_SESSION_HASH_FIELD: str = "password"
+else:
+    AUTH_USER_SESSION_HASH_FIELD: str = ""

plain_auth-0.0.0/plain/auth/middleware.py

@@ -0,0 +1,27 @@
+from plain import auth
+from plain.exceptions import ImproperlyConfigured
+from plain.utils.functional import SimpleLazyObject
+
+
+def get_user(request):
+    if not hasattr(request, "_cached_user"):
+        request._cached_user = auth.get_user(request)
+    return request._cached_user
+
+
+class AuthenticationMiddleware:
+    def __init__(self, get_response):
+        self.get_response = get_response
+
+    def __call__(self, request):
+        if not hasattr(request, "session"):
+            raise ImproperlyConfigured(
+                "The Plain authentication middleware requires session "
+                "middleware to be installed. Edit your MIDDLEWARE setting to "
+                "insert "
+                "'plain.sessions.middleware.SessionMiddleware' before "
+                "'plain.auth.middleware.AuthenticationMiddleware'."
+            )
+        request.user = SimpleLazyObject(lambda: get_user(request))
+        response = self.get_response(request)
+        return response

plain_auth-0.0.0/plain/auth/sessions.py

@@ -0,0 +1,151 @@
+from plain.csrf.middleware import rotate_token
+from plain.exceptions import ImproperlyConfigured
+from plain.packages import packages as plain_packages
+from plain.runtime import settings
+from plain.utils.crypto import constant_time_compare, salted_hmac
+
+from .signals import user_logged_in, user_logged_out
+
+USER_ID_SESSION_KEY = "_auth_user_id"
+USER_HASH_SESSION_KEY = "_auth_user_hash"
+
+
+def _get_user_id_from_session(request):
+    # This value in the session is always serialized to a string, so we need
+    # to convert it back to Python whenever we access it.
+    return get_user_model()._meta.pk.to_python(request.session[USER_ID_SESSION_KEY])
+
+
+def get_session_auth_hash(user):
+    """
+    Return an HMAC of the password field.
+    """
+    return _get_session_auth_hash(user)
+
+
+def get_session_auth_fallback_hash(user):
+    for fallback_secret in settings.SECRET_KEY_FALLBACKS:
+        yield _get_session_auth_hash(user, secret=fallback_secret)
+
+
+def _get_session_auth_hash(user, secret=None):
+    key_salt = "plain.auth.get_session_auth_hash"
+    return salted_hmac(
+        key_salt,
+        getattr(user, settings.AUTH_USER_SESSION_HASH_FIELD),
+        secret=secret,
+        algorithm="sha256",
+    ).hexdigest()
+
+
+def login(request, user):
+    """
+    Persist a user id and a backend in the request. This way a user doesn't
+    have to reauthenticate on every request. Note that data set during
+    the anonymous session is retained when the user logs in.
+    """
+    if settings.AUTH_USER_SESSION_HASH_FIELD:
+        session_auth_hash = get_session_auth_hash(user)
+    else:
+        session_auth_hash = ""
+
+    if USER_ID_SESSION_KEY in request.session:
+        if _get_user_id_from_session(request) != user.pk:
+            # To avoid reusing another user's session, create a new, empty
+            # session if the existing session corresponds to a different
+            # authenticated user.
+            request.session.flush()
+        elif session_auth_hash and not constant_time_compare(
+            request.session.get(USER_HASH_SESSION_KEY, ""), session_auth_hash
+        ):
+            # If the session hash does not match the current hash, reset the
+            # session. Most likely this means the password was changed.
+            request.session.flush()
+    else:
+        request.session.cycle_key()
+
+    request.session[USER_ID_SESSION_KEY] = user._meta.pk.value_to_string(user)
+    request.session[USER_HASH_SESSION_KEY] = session_auth_hash
+    if hasattr(request, "user"):
+        request.user = user
+    rotate_token(request)
+    user_logged_in.send(sender=user.__class__, request=request, user=user)
+
+
+def logout(request):
+    """
+    Remove the authenticated user's ID from the request and flush their session
+    data.
+    """
+    # Dispatch the signal before the user is logged out so the receivers have a
+    # chance to find out *who* logged out.
+    user = getattr(request, "user", None)
+    user_logged_out.send(sender=user.__class__, request=request, user=user)
+    request.session.flush()
+    if hasattr(request, "user"):
+        request.user = None
+
+
+def get_user_model():
+    """
+    Return the User model that is active in this project.
+    """
+    try:
+        return plain_packages.get_model(settings.AUTH_USER_MODEL, require_ready=False)
+    except ValueError:
+        raise ImproperlyConfigured(
+            "AUTH_USER_MODEL must be of the form 'package_label.model_name'"
+        )
+    except LookupError:
+        raise ImproperlyConfigured(
+            "AUTH_USER_MODEL refers to model '%s' that has not been installed"
+            % settings.AUTH_USER_MODEL
+        )
+
+
+def get_user(request):
+    """
+    Return the user model instance associated with the given request session.
+    If no user is retrieved, return None.
+    """
+    if USER_ID_SESSION_KEY not in request.session:
+        return None
+
+    user_id = _get_user_id_from_session(request)
+
+    UserModel = get_user_model()
+    try:
+        user = UserModel._default_manager.get(pk=user_id)
+    except UserModel.DoesNotExist:
+        return None
+
+    # If the user models defines a specific field to also hash and compare
+    # (like password), then we verify that the hash of that field is still
+    # the same as when the session was created.
+    #
+    # If it has changed (i.e. password changed), then the session
+    # is no longer valid and cleared out.
+    if settings.AUTH_USER_SESSION_HASH_FIELD:
+        session_hash = request.session.get(USER_HASH_SESSION_KEY)
+        if not session_hash:
+            session_hash_verified = False
+        else:
+            session_auth_hash = get_session_auth_hash(user)
+            session_hash_verified = constant_time_compare(
+                session_hash, session_auth_hash
+            )
+        if not session_hash_verified:
+            # If the current secret does not verify the session, try
+            # with the fallback secrets and stop when a matching one is
+            # found.
+            if session_hash and any(
+                constant_time_compare(session_hash, fallback_auth_hash)
+                for fallback_auth_hash in get_session_auth_fallback_hash(user)
+            ):
+                request.session.cycle_key()
+                request.session[USER_HASH_SESSION_KEY] = session_auth_hash
+            else:
+                request.session.flush()
+                user = None
+
+    return user

plain_auth-0.0.0/plain/auth/signals.py

@@ -0,0 +1,5 @@
+from plain.signals.dispatch import Signal
+
+user_logged_in = Signal()
+user_login_failed = Signal()
+user_logged_out = Signal()

plain_auth-0.0.0/plain/auth/utils.py

@@ -0,0 +1,43 @@
+from plain.urls import NoReverseMatch, reverse
+from plain.utils.functional import Promise
+
+
+def resolve_url(to, *args, **kwargs):
+    """
+    Return a URL appropriate for the arguments passed.
+
+    The arguments could be:
+
+        * A model: the model's `get_absolute_url()` function will be called.
+
+        * A view name, possibly with arguments: `urls.reverse()` will be used
+          to reverse-resolve the name.
+
+        * A URL, which will be returned as-is.
+    """
+    # If it's a model, use get_absolute_url()
+    if hasattr(to, "get_absolute_url"):
+        return to.get_absolute_url()
+
+    if isinstance(to, Promise):
+        # Expand the lazy instance, as it can cause issues when it is passed
+        # further to some Python functions like urlparse.
+        to = str(to)
+
+    # Handle relative URLs
+    if isinstance(to, str) and to.startswith(("./", "../")):
+        return to
+
+    # Next try a reverse URL resolution.
+    try:
+        return reverse(to, args=args, kwargs=kwargs)
+    except NoReverseMatch:
+        # If this is a callable, re-raise.
+        if callable(to):
+            raise
+        # If this doesn't "feel" like a URL, re-raise.
+        if "/" not in to and "." not in to:
+            raise
+
+    # Finally, fall back and assume it's a URL
+    return to

plain_auth-0.0.0/plain/auth/validators.py

@@ -0,0 +1,18 @@
+import re
+
+from plain import validators
+from plain.utils.deconstruct import deconstructible
+
+
+@deconstructible
+class ASCIIUsernameValidator(validators.RegexValidator):
+    regex = r"^[\w.@+-]+\Z"
+    message = "Enter a valid username. This value may contain only unaccented lowercase a-z and uppercase A-Z letters, numbers, and @/./+/-/_ characters."
+    flags = re.ASCII
+
+
+@deconstructible
+class UnicodeUsernameValidator(validators.RegexValidator):
+    regex = r"^[\w.@+-]+\Z"
+    message = "Enter a valid username. This value may contain only letters, numbers, and @/./+/-/_ characters."
+    flags = 0

plain_auth-0.0.0/plain/auth/views.py

@@ -0,0 +1,104 @@
+from urllib.parse import urlparse, urlunparse
+
+from plain.exceptions import PermissionDenied
+from plain.http import (
+    Http404,
+    QueryDict,
+    Response,
+    ResponseRedirect,
+)
+from plain.runtime import settings
+from plain.urls import reverse
+from plain.views import View
+
+from .sessions import logout
+from .utils import resolve_url
+
+
+class LoginRequired(Exception):
+    def __init__(self, login_url=None, redirect_field_name="next"):
+        self.login_url = login_url or settings.AUTH_LOGIN_URL
+        self.redirect_field_name = redirect_field_name
+
+
+class AuthViewMixin:
+    login_required = True
+    staff_required = False
+    login_url = None
+
+    def check_auth(self) -> None:
+        """
+        Raises either LoginRequired or PermissionDenied.
+        - LoginRequired can specify a login_url and redirect_field_name
+        - PermissionDenied can specify a message
+        """
+
+        if not hasattr(self, "request"):
+            raise AttributeError(
+                "AuthViewMixin requires the request attribute to be set."
+            )
+
+        if self.login_required and not self.request.user:
+            raise LoginRequired(login_url=self.login_url)
+
+        if impersonator := getattr(self.request, "impersonator", None):
+            # Impersonators should be able to view staff pages while impersonating.
+            # There's probably never a case where an impersonator isn't staff, but it can be configured.
+            if self.staff_required and not impersonator.is_staff:
+                raise PermissionDenied(
+                    "You do not have permission to access this page."
+                )
+        elif self.staff_required and not self.request.user.is_staff:
+            # Show a 404 so we don't expose staff urls to non-staff users
+            raise Http404()
+
+    def get_response(self) -> Response:
+        if not hasattr(self, "request"):
+            raise AttributeError(
+                "AuthViewMixin requires the request attribute to be set."
+            )
+
+        try:
+            self.check_auth()
+        except LoginRequired as e:
+            # Ideally this could be handled elsewhere... like PermissionDenied
+            # also seems like this code is used multiple places anyway...
+            # could be easier to get redirect query param
+            path = self.request.build_absolute_uri()
+            resolved_login_url = reverse(e.login_url)
+            # If the login url is the same scheme and net location then use the
+            # path as the "next" url.
+            login_scheme, login_netloc = urlparse(resolved_login_url)[:2]
+            current_scheme, current_netloc = urlparse(path)[:2]
+            if (not login_scheme or login_scheme == current_scheme) and (
+                not login_netloc or login_netloc == current_netloc
+            ):
+                path = self.request.get_full_path()
+            return redirect_to_login(
+                path,
+                resolved_login_url,
+                e.redirect_field_name,
+            )
+
+        return super().get_response()  # type: ignore
+
+
+class LogoutView(View):
+    def post(self):
+        logout(self.request)
+        return ResponseRedirect("/")
+
+
+def redirect_to_login(next, login_url=None, redirect_field_name="next"):
+    """
+    Redirect the user to the login page, passing the given 'next' page.
+    """
+    resolved_url = resolve_url(login_url or settings.AUTH_LOGIN_URL)
+
+    login_url_parts = list(urlparse(resolved_url))
+    if redirect_field_name:
+        querystring = QueryDict(login_url_parts[4], mutable=True)
+        querystring[redirect_field_name] = next
+        login_url_parts[4] = querystring.urlencode(safe="/")
+
+    return ResponseRedirect(urlunparse(login_url_parts))

plain_auth-0.0.0/pyproject.toml

@@ -0,0 +1,17 @@
+[tool.poetry]
+name = "plain.auth"
+packages = [
+    { include = "plain" },
+]
+version = "0.0.0"
+description = ""
+authors = ["Dave Gaeddert <dave.gaeddert@dropseed.dev>"]
+# readme = "README.md"
+
+[tool.poetry.dependencies]
+python = "^3.11"
+
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"