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
