humanoid-login 0.1.0__tar.gz

humanoid_login-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+.pytest_cache/
+.ruff_cache/
+__pycache__/
+*.py[cod]
+build/
+dist/
+*.egg-info/
+.coverage
+htmlcov/

humanoid_login-0.1.0/LICENSE

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

humanoid_login-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include LICENSE
+include README.md
+include humanoid_login/py.typed
+recursive-include humanoid_login *.py
+recursive-include tests *.py

humanoid_login-0.1.0/PKG-INFO

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: humanoid-login
+Version: 0.1.0
+Summary: Django REST Framework JWT authentication with HttpOnly cookies.
+Project-URL: Homepage, https://github.com/humanoid-ai/humanoid-login
+Project-URL: Documentation, https://github.com/humanoid-ai/humanoid-login#readme
+Project-URL: Repository, https://github.com/humanoid-ai/humanoid-login
+Project-URL: Issues, https://github.com/humanoid-ai/humanoid-login/issues
+Author: Fardin Ibrahimi
+Maintainer: Fardin Ibrahimi
+License-Expression: MIT
+License-File: LICENSE
+Keywords: authentication,cookies,django,django-rest-framework,httponly,jwt
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Framework :: Django :: 5.2
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: django>=5.0
+Requires-Dist: djangorestframework-simplejwt>=5.3
+Requires-Dist: djangorestframework>=3.15
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest-django>=4.8; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# humanoid_login
+
+**humanoid_login** provides production-ready JWT authentication for Django REST Framework using secure HttpOnly cookies. It wraps `djangorestframework-simplejwt` with ready-made login, logout, refresh, and current-user endpoints so applications can ship cookie-based authentication without duplicating boilerplate.
+
+Developed and maintained by **Fardin Ibrahimi**, CEO of **Humanoid**.
+
+## Installation
+
+```bash
+pip install humanoid-login
+```
+
+## Quick Start
+
+Add the app and authentication class:
+
+```python
+INSTALLED_APPS = [
+    "django.contrib.auth",
+    "django.contrib.contenttypes",
+    "rest_framework",
+    "humanoid_login",
+]
+
+REST_FRAMEWORK = {
+    "DEFAULT_AUTHENTICATION_CLASSES": [
+        "humanoid_login.authentication.CookieJWTAuthentication",
+    ],
+}
+```
+
+Include the URLs:
+
+```python
+from django.urls import include, path
+
+urlpatterns = [
+    path("", include("humanoid_login.urls")),
+]
+```
+
+Or import views directly:
+
+```python
+from humanoid_login.views import LoginView
+```
+
+## API Endpoints
+
+| Method | Path | Description |
+| --- | --- | --- |
+| `POST` | `/login/` | Authenticates credentials, returns user data, and sets access and refresh cookies. |
+| `POST` | `/logout/` | Deletes cookies and blacklists the refresh token when SimpleJWT blacklist support is enabled. |
+| `POST` | `/refresh/` | Reads the refresh cookie and issues a new access cookie. |
+| `GET` | `/me/` | Returns the authenticated user's compact profile. |
+
+## Login Example
+
+```http
+POST /login/
+Content-Type: application/json
+
+{
+  "email": "user@example.com",
+  "password": "correct-password"
+}
+```
+
+Successful responses set HttpOnly cookies and return:
+
+```json
+{
+  "detail": "Login successful.",
+  "user": {
+    "id": 1,
+    "email": "user@example.com",
+    "name": "John Doe",
+    "role": "admin"
+  }
+}
+```
+
+## Configuration
+
+Override defaults in Django settings:
+
+```python
+from datetime import timedelta
+
+HUMANOID_LOGIN = {
+    "ACCESS_COOKIE": "access_token",
+    "REFRESH_COOKIE": "refresh_token",
+    "COOKIE_HTTPONLY": True,
+    "COOKIE_SECURE": True,
+    "COOKIE_SAMESITE": "Lax",
+    "COOKIE_PATH": "/",
+    "COOKIE_DOMAIN": None,
+    "ACCESS_TOKEN_LIFETIME": timedelta(minutes=5),
+    "REFRESH_TOKEN_LIFETIME": timedelta(days=1),
+    "ROTATE_REFRESH_TOKENS": False,
+    "BLACKLIST_AFTER_ROTATION": True,
+    "USER_ROLE_ATTRIBUTE": "role",
+}
+```
+
+### Recommended Production Settings
+
+Use HTTPS and secure cookies in production:
+
+```python
+HUMANOID_LOGIN = {
+    "COOKIE_SECURE": True,
+    "COOKIE_SAMESITE": "Lax",
+    "COOKIE_HTTPONLY": True,
+}
+```
+
+If your frontend and API are on different sites, configure CORS and CSRF deliberately and choose `COOKIE_SAMESITE="None"` only with `COOKIE_SECURE=True`.
+
+## Authentication Flow
+
+1. `LoginView` validates email and password through `LoginSerializer`.
+2. `AuthService` authenticates with Django's configured authentication backends.
+3. SimpleJWT access and refresh tokens are generated.
+4. Tokens are stored in configured HttpOnly cookies.
+5. `CookieJWTAuthentication` reads the access cookie and validates it for DRF permissions.
+6. `RefreshView` reads the refresh cookie and issues a new access cookie.
+7. `LogoutView` removes cookies and blacklists refresh tokens when the blacklist app is installed.
+
+## Security Notes
+
+- Access and refresh tokens are never returned in response bodies.
+- Cookies default to `HttpOnly=True`.
+- Set `COOKIE_SECURE=True` in production.
+- Use short access-token lifetimes and rotate refresh tokens where appropriate.
+- Consider enabling SimpleJWT's blacklist app:
+
+```python
+INSTALLED_APPS = [
+    "rest_framework_simplejwt.token_blacklist",
+]
+```
+
+Run migrations after enabling blacklist support:
+
+```bash
+python manage.py migrate
+```
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+pytest
+python -m build
+```
+
+## Contributing
+
+Contributions are welcome. Please open an issue for larger changes, include tests for new behavior, and keep authentication changes small, explicit, and documented.
+
+## Changelog
+
+### 0.1.0
+
+- Initial public release.
+- Cookie-backed JWT login, logout, refresh, and current-user endpoints.
+- Typed package marker and pytest coverage.
+
+## About the Author
+
+**humanoid_login** is an open-source package developed and maintained by **Fardin Ibrahimi**, CEO of **Humanoid**, with the goal of making secure JWT cookie authentication effortless for Django REST Framework developers.
+
+---
+
+Documentation maintained by **Fardin Ibrahimi**, CEO of **Humanoid**.
+# humanoid-login

humanoid_login-0.1.0/README.md

@@ -0,0 +1,177 @@
+# humanoid_login
+
+**humanoid_login** provides production-ready JWT authentication for Django REST Framework using secure HttpOnly cookies. It wraps `djangorestframework-simplejwt` with ready-made login, logout, refresh, and current-user endpoints so applications can ship cookie-based authentication without duplicating boilerplate.
+
+Developed and maintained by **Fardin Ibrahimi**, CEO of **Humanoid**.
+
+## Installation
+
+```bash
+pip install humanoid-login
+```
+
+## Quick Start
+
+Add the app and authentication class:
+
+```python
+INSTALLED_APPS = [
+    "django.contrib.auth",
+    "django.contrib.contenttypes",
+    "rest_framework",
+    "humanoid_login",
+]
+
+REST_FRAMEWORK = {
+    "DEFAULT_AUTHENTICATION_CLASSES": [
+        "humanoid_login.authentication.CookieJWTAuthentication",
+    ],
+}
+```
+
+Include the URLs:
+
+```python
+from django.urls import include, path
+
+urlpatterns = [
+    path("", include("humanoid_login.urls")),
+]
+```
+
+Or import views directly:
+
+```python
+from humanoid_login.views import LoginView
+```
+
+## API Endpoints
+
+| Method | Path | Description |
+| --- | --- | --- |
+| `POST` | `/login/` | Authenticates credentials, returns user data, and sets access and refresh cookies. |
+| `POST` | `/logout/` | Deletes cookies and blacklists the refresh token when SimpleJWT blacklist support is enabled. |
+| `POST` | `/refresh/` | Reads the refresh cookie and issues a new access cookie. |
+| `GET` | `/me/` | Returns the authenticated user's compact profile. |
+
+## Login Example
+
+```http
+POST /login/
+Content-Type: application/json
+
+{
+  "email": "user@example.com",
+  "password": "correct-password"
+}
+```
+
+Successful responses set HttpOnly cookies and return:
+
+```json
+{
+  "detail": "Login successful.",
+  "user": {
+    "id": 1,
+    "email": "user@example.com",
+    "name": "John Doe",
+    "role": "admin"
+  }
+}
+```
+
+## Configuration
+
+Override defaults in Django settings:
+
+```python
+from datetime import timedelta
+
+HUMANOID_LOGIN = {
+    "ACCESS_COOKIE": "access_token",
+    "REFRESH_COOKIE": "refresh_token",
+    "COOKIE_HTTPONLY": True,
+    "COOKIE_SECURE": True,
+    "COOKIE_SAMESITE": "Lax",
+    "COOKIE_PATH": "/",
+    "COOKIE_DOMAIN": None,
+    "ACCESS_TOKEN_LIFETIME": timedelta(minutes=5),
+    "REFRESH_TOKEN_LIFETIME": timedelta(days=1),
+    "ROTATE_REFRESH_TOKENS": False,
+    "BLACKLIST_AFTER_ROTATION": True,
+    "USER_ROLE_ATTRIBUTE": "role",
+}
+```
+
+### Recommended Production Settings
+
+Use HTTPS and secure cookies in production:
+
+```python
+HUMANOID_LOGIN = {
+    "COOKIE_SECURE": True,
+    "COOKIE_SAMESITE": "Lax",
+    "COOKIE_HTTPONLY": True,
+}
+```
+
+If your frontend and API are on different sites, configure CORS and CSRF deliberately and choose `COOKIE_SAMESITE="None"` only with `COOKIE_SECURE=True`.
+
+## Authentication Flow
+
+1. `LoginView` validates email and password through `LoginSerializer`.
+2. `AuthService` authenticates with Django's configured authentication backends.
+3. SimpleJWT access and refresh tokens are generated.
+4. Tokens are stored in configured HttpOnly cookies.
+5. `CookieJWTAuthentication` reads the access cookie and validates it for DRF permissions.
+6. `RefreshView` reads the refresh cookie and issues a new access cookie.
+7. `LogoutView` removes cookies and blacklists refresh tokens when the blacklist app is installed.
+
+## Security Notes
+
+- Access and refresh tokens are never returned in response bodies.
+- Cookies default to `HttpOnly=True`.
+- Set `COOKIE_SECURE=True` in production.
+- Use short access-token lifetimes and rotate refresh tokens where appropriate.
+- Consider enabling SimpleJWT's blacklist app:
+
+```python
+INSTALLED_APPS = [
+    "rest_framework_simplejwt.token_blacklist",
+]
+```
+
+Run migrations after enabling blacklist support:
+
+```bash
+python manage.py migrate
+```
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+pytest
+python -m build
+```
+
+## Contributing
+
+Contributions are welcome. Please open an issue for larger changes, include tests for new behavior, and keep authentication changes small, explicit, and documented.
+
+## Changelog
+
+### 0.1.0
+
+- Initial public release.
+- Cookie-backed JWT login, logout, refresh, and current-user endpoints.
+- Typed package marker and pytest coverage.
+
+## About the Author
+
+**humanoid_login** is an open-source package developed and maintained by **Fardin Ibrahimi**, CEO of **Humanoid**, with the goal of making secure JWT cookie authentication effortless for Django REST Framework developers.
+
+---
+
+Documentation maintained by **Fardin Ibrahimi**, CEO of **Humanoid**.
+# humanoid-login

humanoid_login-0.1.0/humanoid_login/__init__.py

@@ -0,0 +1,10 @@
+"""JWT authentication for Django REST Framework using HttpOnly cookies."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+__author__ = "Fardin Ibrahimi"
+__maintainer__ = "Fardin Ibrahimi"
+__company__ = "Humanoid"
+
+default_app_config = "humanoid_login.apps.HumanoidLoginConfig"

humanoid_login-0.1.0/humanoid_login/apps.py

@@ -0,0 +1,13 @@
+"""Django application configuration for humanoid_login."""
+
+from __future__ import annotations
+
+from django.apps import AppConfig
+
+
+class HumanoidLoginConfig(AppConfig):
+    """Application metadata used by Django."""
+
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "humanoid_login"
+    verbose_name = "Humanoid Login"

humanoid_login-0.1.0/humanoid_login/authentication.py

@@ -0,0 +1,25 @@
+"""Cookie-backed JWT authentication for Django REST Framework."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from rest_framework.request import Request
+from rest_framework_simplejwt.authentication import JWTAuthentication
+
+from .settings import api_settings
+from .utils import get_request_cookie
+
+
+class CookieJWTAuthentication(JWTAuthentication):
+    """Authenticate requests using the configured access-token cookie."""
+
+    def authenticate(self, request: Request) -> tuple[Any, Any] | None:
+        """Return the authenticated user and validated token, if a cookie exists."""
+
+        raw_token = get_request_cookie(request, api_settings.ACCESS_COOKIE)
+        if raw_token is None:
+            return None
+
+        validated_token = self.get_validated_token(raw_token)
+        return self.get_user(validated_token), validated_token

humanoid_login-0.1.0/humanoid_login/exceptions.py

@@ -0,0 +1,21 @@
+"""Package-specific exceptions."""
+
+from __future__ import annotations
+
+from rest_framework.exceptions import APIException
+
+
+class HumanoidLoginError(APIException):
+    """Base exception for package-specific API failures."""
+
+    status_code = 400
+    default_detail = "Authentication request could not be completed."
+    default_code = "humanoid_login_error"
+
+
+class MissingRefreshToken(HumanoidLoginError):
+    """Raised when a refresh cookie is required but missing."""
+
+    status_code = 401
+    default_detail = "Refresh token cookie is missing."
+    default_code = "missing_refresh_token"

humanoid_login-0.1.0/humanoid_login/permissions.py

@@ -0,0 +1,7 @@
+"""Permission aliases for projects that want package-local imports."""
+
+from __future__ import annotations
+
+from rest_framework.permissions import IsAuthenticated
+
+__all__ = ["IsAuthenticated"]

humanoid_login-0.1.0/humanoid_login/py.typed

@@ -0,0 +1 @@
+

humanoid_login-0.1.0/humanoid_login/serializers.py

@@ -0,0 +1,27 @@
+"""Serializers used by the public authentication views."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from rest_framework import serializers
+
+
+class LoginSerializer(serializers.Serializer[dict[str, str]]):
+    """Validate and normalize login credentials."""
+
+    email = serializers.EmailField(required=True, trim_whitespace=True)
+    password = serializers.CharField(
+        required=True,
+        trim_whitespace=False,
+        write_only=True,
+        style={"input_type": "password"},
+    )
+
+    def validate(self, attrs: dict[str, Any]) -> dict[str, str]:
+        """Return credentials in a predictable shape for the service layer."""
+
+        return {
+            "email": str(attrs["email"]).strip().lower(),
+            "password": str(attrs["password"]),
+        }

humanoid_login-0.1.0/humanoid_login/services.py

@@ -0,0 +1,152 @@
+"""Service layer for cookie-based JWT authentication."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from django.contrib.auth import authenticate, get_user_model
+from django.contrib.auth.models import AbstractBaseUser
+from django.utils.translation import gettext_lazy as _
+from rest_framework import status
+from rest_framework.exceptions import AuthenticationFailed
+from rest_framework.request import Request
+from rest_framework.response import Response
+from rest_framework_simplejwt.exceptions import TokenError
+from rest_framework_simplejwt.tokens import RefreshToken
+
+from .exceptions import MissingRefreshToken
+from .serializers import LoginSerializer
+from .settings import api_settings
+from .utils import delete_auth_cookies, get_request_cookie, serialize_user, set_auth_cookies
+
+
+class AuthService:
+    """Business logic for login, logout, refresh, and user responses."""
+
+    @classmethod
+    def login(cls, request: Request) -> Response:
+        """Validate credentials, authenticate the user, and set auth cookies."""
+
+        serializer = LoginSerializer(data=request.data)
+        serializer.is_valid(raise_exception=True)
+        user = cls.authenticate(request, serializer.validated_data)
+        access, refresh = cls.generate_tokens(user)
+
+        response = Response(
+            {
+                "detail": "Login successful.",
+                "user": serialize_user(user),
+            },
+            status=status.HTTP_200_OK,
+        )
+        set_auth_cookies(response, access, refresh)
+        return response
+
+    @staticmethod
+    def authenticate(request: Request, credentials: dict[str, str]) -> AbstractBaseUser:
+        """Authenticate credentials against Django's configured auth backends."""
+
+        email = credentials["email"]
+        password = credentials["password"]
+        UserModel = get_user_model()
+        username_field = UserModel.USERNAME_FIELD
+
+        user = authenticate(
+            request=request,
+            **{username_field: email, "password": password},
+        )
+        if user is None and username_field == "username":
+            username = AuthService.get_username_for_email(email)
+            if username:
+                user = authenticate(request=request, username=username, password=password)
+        elif user is None:
+            user = authenticate(request=request, username=email, password=password)
+        if user is None:
+            raise AuthenticationFailed(
+                _("Unable to log in with the provided credentials."),
+                code="invalid_credentials",
+            )
+        if not user.is_active:
+            raise AuthenticationFailed(_("User account is disabled."), code="inactive_user")
+        return user
+
+    @staticmethod
+    def get_username_for_email(email: str) -> str | None:
+        """Resolve Django's default username field from a unique email address."""
+
+        UserModel = get_user_model()
+        try:
+            user = UserModel._default_manager.get(email__iexact=email)
+        except (UserModel.DoesNotExist, UserModel.MultipleObjectsReturned):
+            return None
+        return str(user.get_username())
+
+    @staticmethod
+    def generate_tokens(user: AbstractBaseUser) -> tuple[Any, RefreshToken]:
+        """Create access and refresh tokens for a user."""
+
+        refresh = RefreshToken.for_user(user)
+        refresh.set_exp(lifetime=api_settings.REFRESH_TOKEN_LIFETIME)
+        access = refresh.access_token
+        access.set_exp(lifetime=api_settings.ACCESS_TOKEN_LIFETIME)
+        return access, refresh
+
+    @classmethod
+    def logout(cls, request: Request) -> Response:
+        """Delete authentication cookies and blacklist refresh token when possible."""
+
+        refresh_token = get_request_cookie(request, api_settings.REFRESH_COOKIE)
+        if refresh_token:
+            cls.blacklist_refresh_token(refresh_token)
+
+        response = Response({"detail": "Logout successful."}, status=status.HTTP_200_OK)
+        delete_auth_cookies(response)
+        return response
+
+    @staticmethod
+    def blacklist_refresh_token(refresh_token: str) -> None:
+        """Blacklist a refresh token when SimpleJWT's blacklist app is installed."""
+
+        try:
+            token = RefreshToken(refresh_token)
+            blacklist = getattr(token, "blacklist", None)
+            if callable(blacklist):
+                blacklist()
+        except TokenError:
+            return
+
+    @classmethod
+    def refresh(cls, request: Request) -> Response:
+        """Issue a new access cookie from the configured refresh-token cookie."""
+
+        refresh_token = get_request_cookie(request, api_settings.REFRESH_COOKIE)
+        if not refresh_token:
+            raise MissingRefreshToken()
+
+        try:
+            refresh = RefreshToken(refresh_token)
+        except TokenError as exc:
+            raise AuthenticationFailed(_("Refresh token is invalid or expired.")) from exc
+
+        access = refresh.access_token
+        access.set_exp(lifetime=api_settings.ACCESS_TOKEN_LIFETIME)
+        rotated_refresh = (
+            cls.rotate_refresh_token(refresh) if api_settings.ROTATE_REFRESH_TOKENS else None
+        )
+
+        response = Response({"detail": "Token refreshed."}, status=status.HTTP_200_OK)
+        set_auth_cookies(response, access, rotated_refresh)
+        return response
+
+    @staticmethod
+    def rotate_refresh_token(refresh: RefreshToken) -> RefreshToken:
+        """Rotate a refresh token using the same behavior as SimpleJWT serializers."""
+
+        if api_settings.BLACKLIST_AFTER_ROTATION:
+            blacklist = getattr(refresh, "blacklist", None)
+            if callable(blacklist):
+                blacklist()
+        refresh.set_jti()
+        refresh.set_iat()
+        refresh.set_exp(lifetime=api_settings.REFRESH_TOKEN_LIFETIME)
+        return refresh

humanoid_login-0.1.0/humanoid_login/settings.py

@@ -0,0 +1,61 @@
+"""Runtime settings for humanoid_login.
+
+Configuration is read from ``settings.HUMANOID_LOGIN`` and merged with secure,
+documented defaults. Values are resolved lazily so Django tests and projects can
+override settings at runtime.
+"""
+
+from __future__ import annotations
+
+from datetime import timedelta
+from typing import Any, Final
+
+from django.conf import settings as django_settings
+
+DEFAULTS: Final[dict[str, Any]] = {
+    "ACCESS_COOKIE": "access_token",
+    "REFRESH_COOKIE": "refresh_token",
+    "COOKIE_HTTPONLY": True,
+    "COOKIE_SECURE": False,
+    "COOKIE_SAMESITE": "Lax",
+    "COOKIE_PATH": "/",
+    "COOKIE_DOMAIN": None,
+    "ACCESS_TOKEN_LIFETIME": timedelta(minutes=5),
+    "REFRESH_TOKEN_LIFETIME": timedelta(days=1),
+    "ROTATE_REFRESH_TOKENS": False,
+    "BLACKLIST_AFTER_ROTATION": True,
+    "USER_ROLE_ATTRIBUTE": "role",
+    "USER_NAME_ATTRIBUTES": ("get_full_name", "name", "first_name", "username"),
+}
+
+
+class HumanoidLoginSettings:
+    """Typed accessor for package settings."""
+
+    def __init__(self, user_settings: dict[str, Any] | None = None) -> None:
+        self._user_settings = user_settings
+
+    @property
+    def user_settings(self) -> dict[str, Any]:
+        """Return the current ``HUMANOID_LOGIN`` Django setting."""
+
+        if self._user_settings is not None:
+            return self._user_settings
+        value = getattr(django_settings, "HUMANOID_LOGIN", {})
+        if value is None:
+            return {}
+        if not isinstance(value, dict):
+            msg = "HUMANOID_LOGIN must be a dictionary."
+            raise TypeError(msg)
+        return value
+
+    def __getattr__(self, attr: str) -> Any:
+        """Resolve known settings with defaults."""
+
+        if attr not in DEFAULTS:
+            msg = f"Invalid humanoid_login setting: {attr}"
+            raise AttributeError(msg)
+        return self.user_settings.get(attr, DEFAULTS[attr])
+
+
+api_settings = HumanoidLoginSettings()

humanoid_login-0.1.0/humanoid_login/urls.py

@@ -0,0 +1,16 @@
+"""URL routes provided by humanoid_login."""
+
+from __future__ import annotations
+
+from django.urls import path
+
+from .views import LoginView, LogoutView, MeView, RefreshView
+
+app_name = "humanoid_login"
+
+urlpatterns = [
+    path("login/", LoginView.as_view(), name="login"),
+    path("logout/", LogoutView.as_view(), name="logout"),
+    path("refresh/", RefreshView.as_view(), name="refresh"),
+    path("me/", MeView.as_view(), name="me"),
+]

humanoid_login-0.1.0/humanoid_login/utils.py

@@ -0,0 +1,110 @@
+"""Utility helpers for cookies, tokens, and user serialization."""
+
+from __future__ import annotations
+
+from datetime import timedelta
+from typing import Any
+
+from django.contrib.auth import get_user_model
+from django.contrib.auth.models import AbstractBaseUser, AnonymousUser
+from django.http import HttpRequest
+from django.utils.encoding import force_str
+from rest_framework.response import Response
+from rest_framework_simplejwt.tokens import Token
+
+from .settings import api_settings
+
+
+def lifetime_to_max_age(lifetime: timedelta | None) -> int | None:
+    """Convert a token lifetime to a cookie ``max_age`` value."""
+
+    if lifetime is None:
+        return None
+    return max(0, int(lifetime.total_seconds()))
+
+
+def set_cookie(
+    response: Response,
+    name: str,
+    value: str,
+    max_age: int | None,
+) -> None:
+    """Set a package-authentication cookie on a response."""
+
+    response.set_cookie(
+        key=name,
+        value=value,
+        max_age=max_age,
+        httponly=api_settings.COOKIE_HTTPONLY,
+        secure=api_settings.COOKIE_SECURE,
+        samesite=api_settings.COOKIE_SAMESITE,
+        path=api_settings.COOKIE_PATH,
+        domain=api_settings.COOKIE_DOMAIN,
+    )
+
+
+def set_auth_cookies(response: Response, access: Token, refresh: Token | None) -> None:
+    """Attach access and optional refresh cookies to a response."""
+
+    set_cookie(
+        response,
+        api_settings.ACCESS_COOKIE,
+        str(access),
+        lifetime_to_max_age(api_settings.ACCESS_TOKEN_LIFETIME),
+    )
+    if refresh is not None:
+        set_cookie(
+            response,
+            api_settings.REFRESH_COOKIE,
+            str(refresh),
+            lifetime_to_max_age(api_settings.REFRESH_TOKEN_LIFETIME),
+        )
+
+
+def delete_auth_cookies(response: Response) -> None:
+    """Delete access and refresh cookies using the configured cookie scope."""
+
+    for cookie_name in (api_settings.ACCESS_COOKIE, api_settings.REFRESH_COOKIE):
+        response.delete_cookie(
+            key=cookie_name,
+            path=api_settings.COOKIE_PATH,
+            domain=api_settings.COOKIE_DOMAIN,
+            samesite=api_settings.COOKIE_SAMESITE,
+        )
+
+
+def get_request_cookie(request: HttpRequest, cookie_name: str) -> str | None:
+    """Read a cookie value from a Django or DRF request."""
+
+    value = request.COOKIES.get(cookie_name)
+    return force_str(value) if value else None
+
+
+def get_user_display_name(user: AbstractBaseUser) -> str:
+    """Return a friendly display name for a user."""
+
+    for attribute in api_settings.USER_NAME_ATTRIBUTES:
+        value = getattr(user, attribute, None)
+        if callable(value):
+            value = value()
+        if value:
+            return str(value)
+    return ""
+
+
+def serialize_user(user: AbstractBaseUser | AnonymousUser) -> dict[str, Any]:
+    """Serialize a user object for authentication responses."""
+
+    if not user or isinstance(user, AnonymousUser):
+        return {}
+
+    email = getattr(user, "email", "") or ""
+    role = getattr(user, api_settings.USER_ROLE_ATTRIBUTE, None)
+    user_id = getattr(user, get_user_model()._meta.pk.attname)
+
+    return {
+        "id": user_id,
+        "email": str(email),
+        "name": get_user_display_name(user),
+        "role": role,
+    }

humanoid_login-0.1.0/humanoid_login/views.py

@@ -0,0 +1,60 @@
+"""Public Django REST Framework views exposed by humanoid_login."""
+
+from __future__ import annotations
+
+from typing import ClassVar
+
+from rest_framework.permissions import IsAuthenticated
+from rest_framework.request import Request
+from rest_framework.response import Response
+from rest_framework.views import APIView
+
+from .authentication import CookieJWTAuthentication
+from .services import AuthService
+from .utils import serialize_user
+
+
+class LoginView(APIView):
+    """Authenticate a user and set HttpOnly JWT cookies."""
+
+    permission_classes: ClassVar[list[type]] = []
+
+    def post(self, request: Request) -> Response:
+        """Handle login requests."""
+
+        return AuthService.login(request)
+
+
+class LogoutView(APIView):
+    """Clear JWT cookies and blacklist refresh tokens when available."""
+
+    authentication_classes: ClassVar[list[type]] = [CookieJWTAuthentication]
+    permission_classes: ClassVar[list[type]] = []
+
+    def post(self, request: Request) -> Response:
+        """Handle logout requests."""
+
+        return AuthService.logout(request)
+
+
+class RefreshView(APIView):
+    """Refresh access cookies using the refresh-token cookie."""
+
+    permission_classes: ClassVar[list[type]] = []
+
+    def post(self, request: Request) -> Response:
+        """Handle token refresh requests."""
+
+        return AuthService.refresh(request)
+
+
+class MeView(APIView):
+    """Return the currently authenticated user."""
+
+    authentication_classes: ClassVar[list[type]] = [CookieJWTAuthentication]
+    permission_classes: ClassVar[list[type]] = [IsAuthenticated]
+
+    def get(self, request: Request) -> Response:
+        """Return a compact user profile."""
+
+        return Response(serialize_user(request.user))

humanoid_login-0.1.0/pyproject.toml

@@ -0,0 +1,89 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "humanoid-login"
+version = "0.1.0"
+description = "Django REST Framework JWT authentication with HttpOnly cookies."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [
+  { name = "Fardin Ibrahimi" }
+]
+maintainers = [
+  { name = "Fardin Ibrahimi" }
+]
+keywords = [
+  "django",
+  "django-rest-framework",
+  "jwt",
+  "httponly",
+  "cookies",
+  "authentication",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Web Environment",
+  "Framework :: Django",
+  "Framework :: Django :: 5",
+  "Framework :: Django :: 5.0",
+  "Framework :: Django :: 5.1",
+  "Framework :: Django :: 5.2",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = [
+  "Django>=5.0",
+  "djangorestframework>=3.15",
+  "djangorestframework-simplejwt>=5.3",
+]
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2",
+  "pytest>=8.0",
+  "pytest-django>=4.8",
+  "ruff>=0.6",
+  "twine>=5.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/humanoid-ai/humanoid-login"
+Documentation = "https://github.com/humanoid-ai/humanoid-login#readme"
+Repository = "https://github.com/humanoid-ai/humanoid-login"
+Issues = "https://github.com/humanoid-ai/humanoid-login/issues"
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/humanoid_login",
+  "/tests",
+  "/README.md",
+  "/LICENSE",
+  "/MANIFEST.in",
+  "/pyproject.toml",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["humanoid_login"]
+
+[tool.pytest.ini_options]
+DJANGO_SETTINGS_MODULE = "tests.settings"
+python_files = ["test_*.py"]
+testpaths = ["tests"]
+addopts = "-ra"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]

humanoid_login-0.1.0/tests/__init__.py

@@ -0,0 +1 @@
+

humanoid_login-0.1.0/tests/conftest.py

@@ -0,0 +1,28 @@
+"""Pytest fixtures for humanoid_login."""
+
+from __future__ import annotations
+
+import pytest
+from django.contrib.auth import get_user_model
+from rest_framework.test import APIClient
+
+
+@pytest.fixture
+def api_client() -> APIClient:
+    """Return a DRF API client."""
+
+    return APIClient()
+
+
+@pytest.fixture
+def user(db):
+    """Create a reusable active user."""
+
+    UserModel = get_user_model()
+    return UserModel.objects.create_user(
+        username="user@example.com",
+        email="user@example.com",
+        password="correct-password",
+        first_name="John",
+        last_name="Doe",
+    )

humanoid_login-0.1.0/tests/settings.py

@@ -0,0 +1,44 @@
+"""Django settings used by the humanoid_login test suite."""
+
+from __future__ import annotations
+
+SECRET_KEY = "humanoid-login-tests-secret-key-with-enough-entropy"
+DEBUG = True
+ROOT_URLCONF = "tests.urls"
+USE_TZ = True
+DEFAULT_AUTO_FIELD = "django.db.models.BigAutoField"
+
+INSTALLED_APPS = [
+    "django.contrib.auth",
+    "django.contrib.contenttypes",
+    "rest_framework",
+    "rest_framework_simplejwt.token_blacklist",
+    "humanoid_login",
+]
+
+DATABASES = {
+    "default": {
+        "ENGINE": "django.db.backends.sqlite3",
+        "NAME": ":memory:",
+    }
+}
+
+MIDDLEWARE: list[str] = []
+
+PASSWORD_HASHERS = [
+    "django.contrib.auth.hashers.MD5PasswordHasher",
+]
+
+AUTHENTICATION_BACKENDS = [
+    "django.contrib.auth.backends.ModelBackend",
+]
+
+REST_FRAMEWORK = {
+    "DEFAULT_AUTHENTICATION_CLASSES": [
+        "humanoid_login.authentication.CookieJWTAuthentication",
+    ],
+}
+
+HUMANOID_LOGIN = {
+    "COOKIE_SECURE": False,
+}

humanoid_login-0.1.0/tests/test_auth_flow.py

@@ -0,0 +1,208 @@
+"""Integration tests for cookie-based JWT authentication."""
+
+from __future__ import annotations
+
+from datetime import timedelta
+
+import pytest
+from django.test import override_settings
+from rest_framework import status
+from rest_framework_simplejwt.tokens import RefreshToken
+
+from humanoid_login.authentication import CookieJWTAuthentication
+
+pytestmark = pytest.mark.django_db
+
+
+def test_login_success_returns_user_and_sets_http_only_cookies(api_client, user) -> None:
+    """A valid login returns user data and creates both auth cookies."""
+
+    response = api_client.post(
+        "/login/",
+        {"email": user.email, "password": "correct-password"},
+        format="json",
+    )
+
+    assert response.status_code == status.HTTP_200_OK
+    assert response.data["detail"] == "Login successful."
+    assert response.data["user"] == {
+        "id": user.id,
+        "email": "user@example.com",
+        "name": "John Doe",
+        "role": None,
+    }
+    assert "access_token" in response.cookies
+    assert "refresh_token" in response.cookies
+    assert response.cookies["access_token"]["httponly"] is True
+    assert response.cookies["refresh_token"]["httponly"] is True
+
+
+def test_login_failure_rejects_invalid_credentials(api_client, user) -> None:
+    """Invalid credentials return an authentication failure."""
+
+    response = api_client.post(
+        "/login/",
+        {"email": user.email, "password": "wrong-password"},
+        format="json",
+    )
+
+    assert response.status_code == status.HTTP_401_UNAUTHORIZED
+    assert "access_token" not in response.cookies
+    assert "refresh_token" not in response.cookies
+
+
+def test_login_supports_email_when_username_differs(api_client, django_user_model) -> None:
+    """Projects using Django's default username field can still log in by email."""
+
+    user = django_user_model.objects.create_user(
+        username="john",
+        email="john@example.com",
+        password="correct-password",
+    )
+
+    response = api_client.post(
+        "/login/",
+        {"email": user.email, "password": "correct-password"},
+        format="json",
+    )
+
+    assert response.status_code == status.HTTP_200_OK
+    assert response.data["user"]["email"] == "john@example.com"
+    assert "access_token" in response.cookies
+
+
+def test_cookie_jwt_authentication_allows_drf_permissions(api_client, user) -> None:
+    """The /me/ endpoint authenticates with only the access-token cookie."""
+
+    login_response = api_client.post(
+        "/login/",
+        {"email": user.email, "password": "correct-password"},
+        format="json",
+    )
+    api_client.cookies["access_token"] = login_response.cookies["access_token"].value
+
+    response = api_client.get("/me/")
+
+    assert response.status_code == status.HTTP_200_OK
+    assert response.data["email"] == user.email
+
+
+def test_authentication_class_returns_none_when_cookie_missing(api_client) -> None:
+    """Requests without access cookies are ignored by the package authenticator."""
+
+    request = api_client.get("/me/").wsgi_request
+
+    assert CookieJWTAuthentication().authenticate(request) is None
+
+
+def test_logout_deletes_cookies(api_client, user) -> None:
+    """Logout clears both configured authentication cookies."""
+
+    login_response = api_client.post(
+        "/login/",
+        {"email": user.email, "password": "correct-password"},
+        format="json",
+    )
+    api_client.cookies["access_token"] = login_response.cookies["access_token"].value
+    api_client.cookies["refresh_token"] = login_response.cookies["refresh_token"].value
+
+    response = api_client.post("/logout/")
+
+    assert response.status_code == status.HTTP_200_OK
+    assert response.cookies["access_token"]["max-age"] == 0
+    assert response.cookies["refresh_token"]["max-age"] == 0
+
+
+def test_refresh_issues_new_access_cookie(api_client, user) -> None:
+    """Refresh reads the refresh cookie and sets a new access cookie."""
+
+    login_response = api_client.post(
+        "/login/",
+        {"email": user.email, "password": "correct-password"},
+        format="json",
+    )
+    api_client.cookies["refresh_token"] = login_response.cookies["refresh_token"].value
+    api_client.cookies.pop("access_token", None)
+
+    response = api_client.post("/refresh/")
+
+    assert response.status_code == status.HTTP_200_OK
+    assert "access_token" in response.cookies
+    assert "refresh_token" not in response.cookies
+
+
+def test_refresh_rotates_refresh_cookie_when_enabled(api_client, user) -> None:
+    """Refresh rotation updates the refresh cookie when configured."""
+
+    login_response = api_client.post(
+        "/login/",
+        {"email": user.email, "password": "correct-password"},
+        format="json",
+    )
+    api_client.cookies["refresh_token"] = login_response.cookies["refresh_token"].value
+
+    with override_settings(HUMANOID_LOGIN={"ROTATE_REFRESH_TOKENS": True}):
+        response = api_client.post("/refresh/")
+
+    assert response.status_code == status.HTTP_200_OK
+    assert "access_token" in response.cookies
+    assert "refresh_token" in response.cookies
+
+
+def test_expired_access_token_is_rejected(api_client, user) -> None:
+    """Expired access tokens fail authentication."""
+
+    refresh = RefreshToken.for_user(user)
+    access = refresh.access_token
+    access.set_exp(lifetime=timedelta(seconds=-1))
+    api_client.cookies["access_token"] = str(access)
+
+    response = api_client.get("/me/")
+
+    assert response.status_code == status.HTTP_401_UNAUTHORIZED
+
+
+def test_invalid_access_token_is_rejected(api_client) -> None:
+    """Malformed access tokens fail authentication."""
+
+    api_client.cookies["access_token"] = "not-a-token"
+
+    response = api_client.get("/me/")
+
+    assert response.status_code == status.HTTP_401_UNAUTHORIZED
+
+
+def test_missing_refresh_cookie_is_rejected(api_client) -> None:
+    """Refresh requires a configured refresh cookie."""
+
+    response = api_client.post("/refresh/")
+
+    assert response.status_code == status.HTTP_401_UNAUTHORIZED
+
+
+def test_configuration_overrides_cookie_names_and_attributes(api_client, user) -> None:
+    """Django settings override cookie names, attributes, and lifetimes."""
+
+    with override_settings(
+        HUMANOID_LOGIN={
+            "ACCESS_COOKIE": "humanoid_access",
+            "REFRESH_COOKIE": "humanoid_refresh",
+            "COOKIE_SECURE": True,
+            "COOKIE_SAMESITE": "Strict",
+            "ACCESS_TOKEN_LIFETIME": timedelta(seconds=60),
+            "REFRESH_TOKEN_LIFETIME": timedelta(seconds=120),
+        }
+    ):
+        response = api_client.post(
+            "/login/",
+            {"email": user.email, "password": "correct-password"},
+            format="json",
+        )
+
+    assert response.status_code == status.HTTP_200_OK
+    assert "humanoid_access" in response.cookies
+    assert "humanoid_refresh" in response.cookies
+    assert response.cookies["humanoid_access"]["secure"] is True
+    assert response.cookies["humanoid_access"]["samesite"] == "Strict"
+    assert response.cookies["humanoid_access"]["max-age"] == 60
+    assert response.cookies["humanoid_refresh"]["max-age"] == 120

humanoid_login-0.1.0/tests/urls.py

@@ -0,0 +1,9 @@
+"""URL configuration for package tests."""
+
+from __future__ import annotations
+
+from django.urls import include, path
+
+urlpatterns = [
+    path("", include("humanoid_login.urls")),
+]