django-auth-headless 0.1.0__tar.gz

django_auth_headless-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          version: latest
+      - run: uv run python manage.py test
+      - run: uv build

django_auth_headless-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+name: Publish package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/django-auth-headless
+    steps:
+      - name: Check out source
+        uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

django_auth_headless-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+.venv/
+.env
+.env.*
+!.env.example
+__pycache__/
+*.py[cod]
+*.sqlite3
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+build/
+dist/
+*.egg-info/

django_auth_headless-0.1.0/LICENSE

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

django_auth_headless-0.1.0/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.5
+Name: django-auth-headless
+Version: 0.1.0
+Summary: Reusable Django authentication with django-allauth Headless and OAuth providers.
+Author-email: Abel Mekonen <abelmekonen247@gmail.com>
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: django-allauth[headless,socialaccount]>=65.20.1
+Requires-Dist: django-cors-headers>=4.9.0
+Requires-Dist: django<7.0,>=6.1.2
+Requires-Dist: python-dotenv>=1.2.4
+Description-Content-Type: text/markdown
+
+# django-auth-headless
+
+Reusable Django authentication built on django-allauth Headless.
+
+The first release focuses on Google OAuth, session authentication, CSRF/CORS
+configuration, and setup and verification commands. The package is designed
+for Django projects using any browser frontend. It does not include a frontend
+or example application.
+
+The original learning project, including its React frontend, is available at
+https://github.com/bella-247/DjangoOAuth.
+
+## Install
+
+```bash
+pip install django-auth-headless
+# or
+uv add django-auth-headless
+```
+
+The package requires Django 6.1, django-allauth with the `headless` and
+`socialaccount` extras, django-cors-headers, and python-dotenv.
+
+## Configure Django
+
+In `settings.py`, import the package settings from `django_auth_headless.conf` and
+assign them to the corresponding Django settings:
+
+```python
+from django_auth_headless.conf import *
+```
+
+Keep project-specific `SECRET_KEY`, `DEBUG`, `DATABASES`, `TEMPLATES`,
+`ROOT_URLCONF`, `WSGI_APPLICATION`, `STATIC_URL`, `ALLOWED_HOSTS`, and email
+settings in your project.
+
+The exported `INSTALLED_APPS` already includes `django_auth_headless`, so Django
+discovers the package and its management commands. Do not add it a second
+time.
+
+Add the package URLs to your project URL configuration:
+
+```python
+from django_auth_headless.urls import urlpatterns as auth_urlpatterns
+
+urlpatterns = [
+    *auth_urlpatterns,
+]
+```
+
+Run migrations after installing and configuring the package:
+
+```bash
+python manage.py migrate
+```
+
+## Environment
+
+Create a `.env` file beside `manage.py`:
+
+```dotenv
+DJANGO_FRONTEND_URL=http://localhost:5173
+DJANGO_CORS_ALLOWED_ORIGINS=http://localhost:5173
+DJANGO_CSRF_TRUSTED_ORIGINS=http://localhost:5173
+DJANGO_AUTH_PROVIDERS=google
+DJANGO_GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
+DJANGO_GOOGLE_CLIENT_SECRET=your-client-secret
+```
+
+Security settings are also environment-driven:
+
+```dotenv
+DJANGO_SECURE_SSL_REDIRECT=False
+DJANGO_SECURE_HSTS_SECONDS=0
+DJANGO_SECURE_HSTS_INCLUDE_SUBDOMAINS=False
+DJANGO_SECURE_HSTS_PRELOAD=False
+DJANGO_SESSION_COOKIE_SECURE=False
+DJANGO_CSRF_COOKIE_SECURE=False
+DJANGO_EMAIL_BACKEND=django.core.mail.backends.console.EmailBackend
+```
+
+Use secure cookies, HTTPS redirect, HSTS, and a production email backend in
+production.
+
+## Management commands
+
+The commands are available after `django_auth_headless` is included through the
+exported `INSTALLED_APPS` list and migrations have been applied.
+
+### Configure a provider
+
+`setup_oauth` creates or updates the database-backed `SocialApp`, associates it
+with the configured Site, and can write credentials to an env file.
+
+```bash
+# Interactive
+python manage.py setup_oauth
+
+# Non-interactive
+python manage.py setup_oauth \
+  --provider google \
+  --client-id "$DJANGO_GOOGLE_CLIENT_ID" \
+  --client-secret "$DJANGO_GOOGLE_CLIENT_SECRET" \
+  --domain localhost:8000
+
+# Also update an env file
+python manage.py setup_oauth --env-file .env
+```
+
+Options: `--provider`, `--client-id`, `--client-secret`, `--domain`, `--name`,
+and `--env-file`.
+
+### Verify configuration
+
+```bash
+python manage.py verify_oauth
+```
+
+This checks the Site, database `SocialApp` records, provider environment
+variables, and the allauth Headless configuration endpoint.
+
+Provider credentials have one source of truth: the database `SocialApp`.
+Environment variables supply credentials to `setup_oauth`; they are not also
+registered as settings-backed provider applications.
+
+## Endpoints
+
+The package includes:
+
+- `/_allauth/browser/v1/` — django-allauth Headless endpoints.
+- `/accounts/` — provider callback routes.
+- `/api/me` — authenticated current-user response.
+
+`GET /api/me` returns:
+
+```json
+{
+  "status": 200,
+  "data": {
+    "user": {
+      "id": 1,
+      "username": "example",
+      "email": "example@example.com"
+    }
+  }
+}
+```
+
+Unauthenticated requests return HTTP 401.
+
+## Development
+
+```bash
+uv sync --group dev
+uv run python manage.py test
+uv build
+```
+
+## Publishing
+
+Releases are published to PyPI by the `Publish package` GitHub Actions
+workflow when a GitHub Release is published. Configure PyPI Trusted Publishing
+for the `bella-247/django-auth-headless` repository with:
+
+- Workflow: `.github/workflows/publish.yml`
+- Environment: `pypi`
+- PyPI project: `django-auth-headless`
+
+Update the version in `pyproject.toml`, push a matching tag, and publish a
+GitHub Release for that tag. PyPI versions are immutable, so each release must
+use a new version number.
+
+## Scope
+
+This is a Django-only package extracted from a Google OAuth learning project.
+Provider configuration is extensible, but Google OAuth is the documented and
+tested browser flow. The learning project is kept separate as an example.

django_auth_headless-0.1.0/README.md

@@ -0,0 +1,177 @@
+# django-auth-headless
+
+Reusable Django authentication built on django-allauth Headless.
+
+The first release focuses on Google OAuth, session authentication, CSRF/CORS
+configuration, and setup and verification commands. The package is designed
+for Django projects using any browser frontend. It does not include a frontend
+or example application.
+
+The original learning project, including its React frontend, is available at
+https://github.com/bella-247/DjangoOAuth.
+
+## Install
+
+```bash
+pip install django-auth-headless
+# or
+uv add django-auth-headless
+```
+
+The package requires Django 6.1, django-allauth with the `headless` and
+`socialaccount` extras, django-cors-headers, and python-dotenv.
+
+## Configure Django
+
+In `settings.py`, import the package settings from `django_auth_headless.conf` and
+assign them to the corresponding Django settings:
+
+```python
+from django_auth_headless.conf import *
+```
+
+Keep project-specific `SECRET_KEY`, `DEBUG`, `DATABASES`, `TEMPLATES`,
+`ROOT_URLCONF`, `WSGI_APPLICATION`, `STATIC_URL`, `ALLOWED_HOSTS`, and email
+settings in your project.
+
+The exported `INSTALLED_APPS` already includes `django_auth_headless`, so Django
+discovers the package and its management commands. Do not add it a second
+time.
+
+Add the package URLs to your project URL configuration:
+
+```python
+from django_auth_headless.urls import urlpatterns as auth_urlpatterns
+
+urlpatterns = [
+    *auth_urlpatterns,
+]
+```
+
+Run migrations after installing and configuring the package:
+
+```bash
+python manage.py migrate
+```
+
+## Environment
+
+Create a `.env` file beside `manage.py`:
+
+```dotenv
+DJANGO_FRONTEND_URL=http://localhost:5173
+DJANGO_CORS_ALLOWED_ORIGINS=http://localhost:5173
+DJANGO_CSRF_TRUSTED_ORIGINS=http://localhost:5173
+DJANGO_AUTH_PROVIDERS=google
+DJANGO_GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
+DJANGO_GOOGLE_CLIENT_SECRET=your-client-secret
+```
+
+Security settings are also environment-driven:
+
+```dotenv
+DJANGO_SECURE_SSL_REDIRECT=False
+DJANGO_SECURE_HSTS_SECONDS=0
+DJANGO_SECURE_HSTS_INCLUDE_SUBDOMAINS=False
+DJANGO_SECURE_HSTS_PRELOAD=False
+DJANGO_SESSION_COOKIE_SECURE=False
+DJANGO_CSRF_COOKIE_SECURE=False
+DJANGO_EMAIL_BACKEND=django.core.mail.backends.console.EmailBackend
+```
+
+Use secure cookies, HTTPS redirect, HSTS, and a production email backend in
+production.
+
+## Management commands
+
+The commands are available after `django_auth_headless` is included through the
+exported `INSTALLED_APPS` list and migrations have been applied.
+
+### Configure a provider
+
+`setup_oauth` creates or updates the database-backed `SocialApp`, associates it
+with the configured Site, and can write credentials to an env file.
+
+```bash
+# Interactive
+python manage.py setup_oauth
+
+# Non-interactive
+python manage.py setup_oauth \
+  --provider google \
+  --client-id "$DJANGO_GOOGLE_CLIENT_ID" \
+  --client-secret "$DJANGO_GOOGLE_CLIENT_SECRET" \
+  --domain localhost:8000
+
+# Also update an env file
+python manage.py setup_oauth --env-file .env
+```
+
+Options: `--provider`, `--client-id`, `--client-secret`, `--domain`, `--name`,
+and `--env-file`.
+
+### Verify configuration
+
+```bash
+python manage.py verify_oauth
+```
+
+This checks the Site, database `SocialApp` records, provider environment
+variables, and the allauth Headless configuration endpoint.
+
+Provider credentials have one source of truth: the database `SocialApp`.
+Environment variables supply credentials to `setup_oauth`; they are not also
+registered as settings-backed provider applications.
+
+## Endpoints
+
+The package includes:
+
+- `/_allauth/browser/v1/` — django-allauth Headless endpoints.
+- `/accounts/` — provider callback routes.
+- `/api/me` — authenticated current-user response.
+
+`GET /api/me` returns:
+
+```json
+{
+  "status": 200,
+  "data": {
+    "user": {
+      "id": 1,
+      "username": "example",
+      "email": "example@example.com"
+    }
+  }
+}
+```
+
+Unauthenticated requests return HTTP 401.
+
+## Development
+
+```bash
+uv sync --group dev
+uv run python manage.py test
+uv build
+```
+
+## Publishing
+
+Releases are published to PyPI by the `Publish package` GitHub Actions
+workflow when a GitHub Release is published. Configure PyPI Trusted Publishing
+for the `bella-247/django-auth-headless` repository with:
+
+- Workflow: `.github/workflows/publish.yml`
+- Environment: `pypi`
+- PyPI project: `django-auth-headless`
+
+Update the version in `pyproject.toml`, push a matching tag, and publish a
+GitHub Release for that tag. PyPI versions are immutable, so each release must
+use a new version number.
+
+## Scope
+
+This is a Django-only package extracted from a Google OAuth learning project.
+Provider configuration is extensible, but Google OAuth is the documented and
+tested browser flow. The learning project is kept separate as an example.

django_auth_headless-0.1.0/manage.py

@@ -0,0 +1,10 @@
+#!/usr/bin/env python
+import os
+import sys
+
+
+if __name__ == "__main__":
+    os.environ.setdefault("DJANGO_SETTINGS_MODULE", "tests.settings")
+    from django.core.management import execute_from_command_line
+
+    execute_from_command_line(sys.argv)

django_auth_headless-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "django-auth-headless"
+version = "0.1.0"
+description = "Reusable Django authentication with django-allauth Headless and OAuth providers."
+readme = "README.md"
+requires-python = ">=3.13"
+license = { text = "MIT" }
+authors = [
+    { name = "Abel Mekonen", email = "abelmekonen247@gmail.com" },
+]
+dependencies = [
+    "django>=6.1.2,<7.0",
+    "django-allauth[headless,socialaccount]>=65.20.1",
+    "django-cors-headers>=4.9.0",
+    "python-dotenv>=1.2.4",
+]
+
+[dependency-groups]
+dev = [
+    "build>=1.2.2",
+]
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/django_auth_headless"]

django_auth_headless-0.1.0/src/django_auth_headless/__init__.py

@@ -0,0 +1 @@
+"""Reusable Django authentication configuration."""

django_auth_headless-0.1.0/src/django_auth_headless/adapters.py

@@ -0,0 +1,18 @@
+"""Custom django-allauth hooks for keeping local user data in sync."""
+
+from allauth.socialaccount.adapter import DefaultSocialAccountAdapter
+from allauth.socialaccount.models import SocialLogin
+
+
+class AuthenticationSocialAccountAdapter(DefaultSocialAccountAdapter):
+    """Fill missing local email addresses from the authenticated provider."""
+
+    def pre_social_login(self, request, sociallogin: SocialLogin) -> None:
+        user = sociallogin.user
+        provider_email = user.email or sociallogin.account.extra_data.get("email", "")
+
+        if not user.email and isinstance(provider_email, str) and provider_email:
+            user.email = provider_email
+            user.save(update_fields=["email"])
+
+        super().pre_social_login(request, sociallogin)

django_auth_headless-0.1.0/src/django_auth_headless/apps.py

@@ -0,0 +1,9 @@
+"""Django app configuration for the authentication module."""
+
+from django.apps import AppConfig
+
+
+class AuthenticationConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = __package__
+    verbose_name = "Authentication"