django-auth-headless 0.1.0__py3-none-any.whl

django_auth_headless/__init__.py

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

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/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"

django_auth_headless/conf.py

@@ -0,0 +1,180 @@
+"""Authentication configuration loaded from environment variables.
+
+This is the ONLY file in the authentication package that reads environment
+variables or loads .env files. All other modules import finished values from
+here or from the pure build() function.
+
+The build() function accepts an explicit mapping so tests can pass fake
+environments without mutating os.environ.
+"""
+
+import os
+from typing import Any, Mapping
+
+from .utils import (
+    env_bool,
+    env_int,
+    env_list,
+    env_str,
+    load_env_file,
+)
+
+AUTHENTICATION_PACKAGE = __package__
+
+
+# Provider configurations - defines required env vars per provider
+PROVIDER_CONFIGS = {
+    "google": {
+        "client_id_env": "DJANGO_GOOGLE_CLIENT_ID",
+        "client_secret_env": "DJANGO_GOOGLE_CLIENT_SECRET",
+        "scope": ["profile", "email"],
+        "auth_params": {"access_type": "online"},
+    },
+    "github": {
+        "client_id_env": "DJANGO_GITHUB_CLIENT_ID",
+        "client_secret_env": "DJANGO_GITHUB_CLIENT_SECRET",
+        "scope": ["user:email", "read:user"],
+        "auth_params": {},
+    },
+    "gitlab": {
+        "client_id_env": "DJANGO_GITLAB_CLIENT_ID",
+        "client_secret_env": "DJANGO_GITLAB_CLIENT_SECRET",
+        "scope": ["read_user", "email"],
+        "auth_params": {},
+    },
+    "microsoft": {
+        "client_id_env": "DJANGO_MICROSOFT_CLIENT_ID",
+        "client_secret_env": "DJANGO_MICROSOFT_CLIENT_SECRET",
+        "scope": ["User.Read", "email"],
+        "auth_params": {},
+    },
+}
+
+
+def build(env: Mapping[str, str] | None = None) -> dict[str, Any]:
+    """Build all authentication settings from an environment mapping.
+
+    Args:
+        env: Optional environment mapping. If None, uses os.environ after
+             loading the project's .env file.
+
+    Returns:
+        Dictionary of Django settings ready to use.
+    """
+    if env is None:
+        load_env_file()
+        env = dict(os.environ)
+
+    frontend_url = env_str("DJANGO_FRONTEND_URL", "", env).rstrip("/")
+
+    # Parse enabled providers from DJANGO_AUTH_PROVIDERS (comma-separated, default "google")
+    providers_str = env_str("DJANGO_AUTH_PROVIDERS", "google", env)
+    enabled_providers = [p.strip().lower() for p in providers_str.split(",") if p.strip()]
+
+    # Build SOCIALACCOUNT_PROVIDERS dynamically
+    socialaccount_providers = {}
+    for provider in enabled_providers:
+        if provider not in PROVIDER_CONFIGS:
+            continue
+        config = PROVIDER_CONFIGS[provider]
+        socialaccount_providers[provider] = {
+            "SCOPE": config["scope"],
+            "AUTH_PARAMS": config["auth_params"],
+        }
+
+    return {
+        "INSTALLED_APPS": [
+            "django.contrib.admin",
+            "django.contrib.auth",
+            "django.contrib.contenttypes",
+            "django.contrib.sessions",
+            "django.contrib.messages",
+            "django.contrib.staticfiles",
+            "django.contrib.sites",
+            "allauth",
+            "allauth.account",
+            "allauth.socialaccount",
+            "allauth.socialaccount.providers.google",
+            "allauth.socialaccount.providers.github",
+            "allauth.socialaccount.providers.gitlab",
+            "allauth.socialaccount.providers.microsoft",
+            "allauth.headless",
+            "corsheaders",
+            AUTHENTICATION_PACKAGE,
+        ],
+        "MIDDLEWARE": [
+            "corsheaders.middleware.CorsMiddleware",
+            "django.middleware.security.SecurityMiddleware",
+            "django.contrib.sessions.middleware.SessionMiddleware",
+            "django.middleware.common.CommonMiddleware",
+            "django.middleware.csrf.CsrfViewMiddleware",
+            "django.contrib.auth.middleware.AuthenticationMiddleware",
+            "allauth.account.middleware.AccountMiddleware",
+            "django.contrib.messages.middleware.MessageMiddleware",
+            "django.middleware.clickjacking.XFrameOptionsMiddleware",
+        ],
+        "AUTHENTICATION_BACKENDS": [
+            "django.contrib.auth.backends.ModelBackend",
+            "allauth.account.auth_backends.AuthenticationBackend",
+        ],
+        "SOCIALACCOUNT_ADAPTER": (
+            f"{AUTHENTICATION_PACKAGE}.adapters.AuthenticationSocialAccountAdapter"
+        ),
+        "SITE_ID": 1,
+        "HEADLESS_ONLY": True,
+        "HEADLESS_FRONTEND_URLS": {
+            "account_confirm_email": f"{frontend_url}/account/confirm-email/{{key}}",
+            "account_reset_password": f"{frontend_url}/account/password/reset",
+            "account_reset_password_from_key": (
+                f"{frontend_url}/account/password/reset/key/{{key}}"
+            ),
+            "account_signup": f"{frontend_url}/account/signup",
+            "socialaccount_login_error": f"{frontend_url}/account/social/login/error",
+        },
+        "CORS_ALLOWED_ORIGINS": env_list("DJANGO_CORS_ALLOWED_ORIGINS", env=env),
+        "CORS_ALLOW_CREDENTIALS": True,
+        "CSRF_TRUSTED_ORIGINS": env_list("DJANGO_CSRF_TRUSTED_ORIGINS", env=env),
+        "SESSION_COOKIE_SECURE": env_bool("DJANGO_SESSION_COOKIE_SECURE", env=env),
+        "CSRF_COOKIE_SECURE": env_bool("DJANGO_CSRF_COOKIE_SECURE", env=env),
+        "SESSION_COOKIE_HTTPONLY": True,
+        "CSRF_COOKIE_HTTPONLY": False,
+        "SESSION_COOKIE_SAMESITE": "Lax",
+        "CSRF_COOKIE_SAMESITE": "Lax",
+        "SECURE_CONTENT_TYPE_NOSNIFF": True,
+        "SECURE_SSL_REDIRECT": env_bool("DJANGO_SECURE_SSL_REDIRECT", env=env),
+        "SECURE_HSTS_SECONDS": env_int("DJANGO_SECURE_HSTS_SECONDS", env=env),
+        "SECURE_HSTS_INCLUDE_SUBDOMAINS": env_bool(
+            "DJANGO_SECURE_HSTS_INCLUDE_SUBDOMAINS", env=env
+        ),
+        "SECURE_HSTS_PRELOAD": env_bool("DJANGO_SECURE_HSTS_PRELOAD", env=env),
+        "SOCIALACCOUNT_PROVIDERS": socialaccount_providers,
+    }
+
+
+# Load .env and build the actual exported settings
+load_env_file()
+_settings = build()
+
+# Export everything so `from .conf import *` works
+INSTALLED_APPS = _settings["INSTALLED_APPS"]
+MIDDLEWARE = _settings["MIDDLEWARE"]
+AUTHENTICATION_BACKENDS = _settings["AUTHENTICATION_BACKENDS"]
+SOCIALACCOUNT_ADAPTER = _settings["SOCIALACCOUNT_ADAPTER"]
+SITE_ID = _settings["SITE_ID"]
+HEADLESS_ONLY = _settings["HEADLESS_ONLY"]
+HEADLESS_FRONTEND_URLS = _settings["HEADLESS_FRONTEND_URLS"]
+CORS_ALLOWED_ORIGINS = _settings["CORS_ALLOWED_ORIGINS"]
+CORS_ALLOW_CREDENTIALS = _settings["CORS_ALLOW_CREDENTIALS"]
+CSRF_TRUSTED_ORIGINS = _settings["CSRF_TRUSTED_ORIGINS"]
+SESSION_COOKIE_SECURE = _settings["SESSION_COOKIE_SECURE"]
+CSRF_COOKIE_SECURE = _settings["CSRF_COOKIE_SECURE"]
+SESSION_COOKIE_HTTPONLY = _settings["SESSION_COOKIE_HTTPONLY"]
+CSRF_COOKIE_HTTPONLY = _settings["CSRF_COOKIE_HTTPONLY"]
+SESSION_COOKIE_SAMESITE = _settings["SESSION_COOKIE_SAMESITE"]
+CSRF_COOKIE_SAMESITE = _settings["CSRF_COOKIE_SAMESITE"]
+SECURE_CONTENT_TYPE_NOSNIFF = _settings["SECURE_CONTENT_TYPE_NOSNIFF"]
+SECURE_SSL_REDIRECT = _settings["SECURE_SSL_REDIRECT"]
+SECURE_HSTS_SECONDS = _settings["SECURE_HSTS_SECONDS"]
+SECURE_HSTS_INCLUDE_SUBDOMAINS = _settings["SECURE_HSTS_INCLUDE_SUBDOMAINS"]
+SECURE_HSTS_PRELOAD = _settings["SECURE_HSTS_PRELOAD"]
+SOCIALACCOUNT_PROVIDERS = _settings["SOCIALACCOUNT_PROVIDERS"]

django_auth_headless/management/commands/setup_oauth.py

@@ -0,0 +1,96 @@
+"""Management command to configure OAuth provider credentials."""
+
+from django.core.management.base import BaseCommand, CommandError
+from django.contrib.sites.models import Site
+from allauth.socialaccount.models import SocialApp
+from getpass import getpass
+
+from ...site_helpers import ensure_site
+
+
+class Command(BaseCommand):
+    help = "Configure OAuth provider: prompts for credentials, updates .env, creates SocialApp"
+
+    def add_arguments(self, parser):
+        parser.add_argument(
+            "--provider",
+            default="google",
+            choices=["google", "github", "gitlab", "microsoft"],
+            help="OAuth provider to configure (default: google)",
+        )
+        parser.add_argument(
+            "--client-id",
+            help="OAuth client ID (skip interactive prompt)",
+        )
+        parser.add_argument(
+            "--client-secret",
+            help="OAuth client secret (skip interactive prompt)",
+        )
+        parser.add_argument(
+            "--domain",
+            default="localhost:8000",
+            help="Site domain for the OAuth callback (default: localhost:8000)",
+        )
+        parser.add_argument(
+            "--name",
+            help="Site display name (default: provider title + domain)",
+        )
+        parser.add_argument(
+            "--env-file",
+            help="Path to .env file to update (default: backend/.env)",
+        )
+
+    def handle(self, *args, **options):
+        provider = options["provider"]
+        client_id = options["client_id"] or input(f"{provider.title()} Client ID: ").strip()
+        client_secret = options["client_secret"] or getpass(f"{provider.title()} Client Secret: ")
+        domain = options["domain"]
+        name = options["name"] or f"{provider.title()} Auth ({domain})"
+        env_file = options["env_file"]
+
+        if not client_id or not client_secret:
+            raise CommandError("Client ID and secret are required")
+
+        # Ensure Site
+        site = ensure_site(domain, name)
+
+        # Create/update SocialApp
+        app, created = SocialApp.objects.update_or_create(
+            provider=provider,
+            defaults={
+                "name": f"{provider.title()} OAuth",
+                "client_id": client_id,
+                "secret": client_secret,
+            },
+        )
+        app.sites.add(site)
+
+        self.stdout.write(self.style.SUCCESS(f"Created {provider} SocialApp for site {domain}"))
+        self.stdout.write("Add these to your .env:")
+        self.stdout.write(f"  DJANGO_{provider.upper()}_CLIENT_ID={client_id}")
+        self.stdout.write(f"  DJANGO_{provider.upper()}_CLIENT_SECRET={client_secret}")
+
+        # Optionally update .env file
+        if env_file:
+            self._update_env_file(env_file, provider, client_id, client_secret)
+            self.stdout.write(self.style.SUCCESS(f"Updated {env_file}"))
+
+    def _update_env_file(self, env_file: str, provider: str, client_id: str, client_secret: str) -> None:
+        """Update .env file with provider credentials."""
+        from pathlib import Path
+
+        path = Path(env_file)
+        lines = []
+        if path.exists():
+            lines = path.read_text().splitlines()
+
+        # Remove existing provider credentials
+        client_id_key = f"DJANGO_{provider.upper()}_CLIENT_ID"
+        client_secret_key = f"DJANGO_{provider.upper()}_CLIENT_SECRET"
+        lines = [l for l in lines if not l.startswith(f"{client_id_key}=") and not l.startswith(f"{client_secret_key}=")]
+
+        # Add new credentials
+        lines.append(f"{client_id_key}={client_id}")
+        lines.append(f"{client_secret_key}={client_secret}")
+
+        path.write_text("\n".join(lines) + "\n")

django_auth_headless/management/commands/verify_oauth.py

@@ -0,0 +1,122 @@
+"""Management command to verify OAuth configuration."""
+
+from django.core.management.base import BaseCommand
+from django.conf import settings
+from django.contrib.sites.models import Site
+from allauth.socialaccount.models import SocialApp
+
+from ...conf import PROVIDER_CONFIGS, build
+from ...site_helpers import get_site
+
+
+class Command(BaseCommand):
+    help = "Verify OAuth configuration: Site, SocialApp, providers, env vars"
+
+    def handle(self, *args, **options):
+        self.stdout.write(self.style.NOTICE("=== OAuth Configuration Verification ===\n"))
+
+        all_ok = True
+
+        # 1. Check Site
+        all_ok &= self._check_site()
+
+        # 2. Check SocialApp(s)
+        all_ok &= self._check_social_apps()
+
+        # 3. Check env vars
+        all_ok &= self._check_env_vars()
+
+        # 4. Check allauth config endpoint
+        all_ok &= self._check_allauth_config()
+
+        # Summary
+        self.stdout.write("")
+        if all_ok:
+            self.stdout.write(self.style.SUCCESS("✓ All checks passed"))
+        else:
+            self.stdout.write(self.style.ERROR("✗ Some checks failed"))
+
+        return ""
+
+    def _check_site(self) -> bool:
+        self.stdout.write("1. Site Configuration:")
+        try:
+            site = get_site()
+            self.stdout.write(f"   ✓ Site ID {site.pk}: {site.domain} ({site.name})")
+            return True
+        except Site.DoesNotExist:
+            self.stdout.write(self.style.ERROR(f"   ✗ Site with ID {settings.SITE_ID} does not exist"))
+            return False
+        except Exception as e:
+            self.stdout.write(self.style.ERROR(f"   ✗ Error: {e}"))
+            return False
+
+    def _check_social_apps(self) -> bool:
+        self.stdout.write("\n2. Social Applications:")
+        providers = build()["SOCIALACCOUNT_PROVIDERS"]
+        if not providers:
+            self.stdout.write(self.style.WARNING("   ⚠ No providers configured in env"))
+            return True
+
+        all_ok = True
+        for provider_id, config in providers.items():
+            try:
+                app = SocialApp.objects.get(provider=provider_id)
+                sites = list(app.sites.values_list("domain", flat=True))
+                self.stdout.write(f"   ✓ {provider_id}: {app.name} (sites: {', '.join(sites) or 'none'})")
+            except SocialApp.DoesNotExist:
+                self.stdout.write(self.style.ERROR(f"   ✗ {provider_id}: SocialApp not found in database"))
+                all_ok = False
+            except Exception as e:
+                self.stdout.write(self.style.ERROR(f"   ✗ {provider_id}: Error - {e}"))
+                all_ok = False
+        return all_ok
+
+    def _check_env_vars(self) -> bool:
+        self.stdout.write("\n3. Environment Variables:")
+        all_ok = True
+        for provider_id, config in PROVIDER_CONFIGS.items():
+            client_id = config["client_id_env"]
+            client_secret = config["client_secret_env"]
+            has_id = bool(settings.__dict__.get(client_id) or getattr(settings, client_id, None))
+            has_secret = bool(settings.__dict__.get(client_secret) or getattr(settings, client_secret, None))
+
+            # Check actual env
+            import os
+            has_id = bool(os.getenv(client_id))
+            has_secret = bool(os.getenv(client_secret))
+
+            if has_id and has_secret:
+                self.stdout.write(f"   ✓ {provider_id}: {client_id}, {client_secret} present")
+            elif has_id or has_secret:
+                self.stdout.write(self.style.WARNING(f"   ⚠ {provider_id}: Only one of {client_id}/{client_secret} set"))
+                all_ok = False
+            else:
+                self.stdout.write(f"   ○ {provider_id}: Not configured (optional)")
+        return all_ok
+
+    def _check_allauth_config(self) -> bool:
+        self.stdout.write("\n4. Allauth Headless Config Endpoint:")
+        try:
+            from django.test import Client
+            client = Client(HTTP_HOST="localhost:8000")
+            response = client.get("/_allauth/browser/v1/config", HTTP_ORIGIN="http://localhost:5173")
+
+            if response.status_code != 200:
+                self.stdout.write(self.style.ERROR(f"   ✗ Config endpoint returned {response.status_code}"))
+                return False
+
+            data = response.json()
+            providers = data.get("data", {}).get("socialaccount", {}).get("providers", [])
+
+            if not providers:
+                self.stdout.write(self.style.WARNING("   ⚠ No providers in allauth config"))
+                return True
+
+            self.stdout.write(f"   ✓ Config endpoint accessible, {len(providers)} provider(s) found")
+            for p in providers:
+                self.stdout.write(f"      - {p['id']}: {p['name']} (flows: {', '.join(p['flows'])})")
+            return True
+        except Exception as e:
+            self.stdout.write(self.style.ERROR(f"   ✗ Config endpoint error: {e}"))
+            return False

django_auth_headless/site_helpers.py

@@ -0,0 +1,26 @@
+"""Site configuration helpers for django-allauth."""
+
+from django.conf import settings
+from django.contrib.sites.models import Site
+
+
+def get_site() -> Site:
+    """Get the current Site record for SITE_ID."""
+    return Site.objects.get(pk=settings.SITE_ID)
+
+
+def ensure_site(domain: str, name: str) -> Site:
+    """Create or update the Site record for SITE_ID.
+
+    Args:
+        domain: The domain for the site (e.g., "localhost:8000")
+        name: The display name for the site
+
+    Returns:
+        The created or updated Site instance
+    """
+    site, _ = Site.objects.update_or_create(
+        pk=settings.SITE_ID,
+        defaults={"domain": domain, "name": name},
+    )
+    return site

django_auth_headless/urls.py

@@ -0,0 +1,11 @@
+"""URL patterns for django-allauth headless and social authentication."""
+
+from django.urls import include, path
+
+from .views import current_user
+
+urlpatterns = [
+    path("accounts/", include("allauth.urls")),
+    path("_allauth/", include("allauth.headless.urls")),
+    path("api/me", current_user, name="current_user"),
+]

django_auth_headless/utils.py

@@ -0,0 +1,67 @@
+"""Utility functions for environment variable parsing."""
+
+import os
+from pathlib import Path
+from typing import Mapping
+
+
+def load_env_file(env_file: Path | None = None, env: Mapping[str, str] | None = None) -> None:
+    """Load .env file if it exists. Safe to call multiple times.
+
+    If `env` is provided, loads into that mapping instead of os.environ.
+    """
+    target = env if env is not None else os.environ
+
+    if env_file is None:
+        env_file = Path.cwd() / ".env"
+    if env_file.exists():
+        # Simple .env parser - no external dependency
+        for line in env_file.read_text().splitlines():
+            line = line.strip()
+            if not line or line.startswith("#") or "=" not in line:
+                continue
+            key, value = line.split("=", 1)
+            key = key.strip()
+            value = value.strip().strip('"').strip("'")
+            if key not in target:
+                target[key] = value
+
+
+def _get_env(name: str, env: Mapping[str, str] | None) -> str | None:
+    """Get value from env mapping or os.environ."""
+    if env is not None:
+        return env.get(name)
+    return os.getenv(name)
+
+
+def env_bool(name: str, default: bool = False, env: Mapping[str, str] | None = None) -> bool:
+    """Parse environment variable as boolean."""
+    value = _get_env(name, env)
+    if value is None:
+        return default
+    return value.strip().lower() in ("1", "true", "yes", "on")
+
+
+def env_list(name: str, default: list[str] | None = None, env: Mapping[str, str] | None = None) -> list[str]:
+    """Parse comma-separated environment variable as list."""
+    value = _get_env(name, env)
+    if not value:
+        return default or []
+    return [item.strip() for item in value.split(",") if item.strip()]
+
+
+def env_int(name: str, default: int = 0, env: Mapping[str, str] | None = None) -> int:
+    """Parse environment variable as integer."""
+    value = _get_env(name, env)
+    if value is None:
+        return default
+    try:
+        return int(value.strip())
+    except ValueError:
+        return default
+
+
+def env_str(name: str, default: str = "", env: Mapping[str, str] | None = None) -> str:
+    """Get environment variable as string."""
+    value = _get_env(name, env)
+    return value if value is not None else default

django_auth_headless/views.py

@@ -0,0 +1,36 @@
+from django.http import JsonResponse
+from django.views.decorators.http import require_GET
+
+from allauth.socialaccount.models import SocialAccount
+
+
+@require_GET
+def current_user(request):
+    if not request.user.is_authenticated:
+        return JsonResponse(
+            {"detail": "Authentication credentials were not provided."},
+            status=401,
+        )
+
+    email = request.user.email
+    if not email:
+        provider_account = (
+            SocialAccount.objects.filter(user=request.user)
+            .exclude(extra_data__email="")
+            .first()
+        )
+        if provider_account:
+            email = provider_account.extra_data.get("email", "")
+
+    return JsonResponse(
+        {
+            "status": 200,
+            "data": {
+                "user": {
+                    "id": request.user.pk,
+                    "username": request.user.get_username(),
+                    "email": email,
+                }
+            },
+        }
+    )

django_auth_headless-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,16 @@
+django_auth_headless/__init__.py,sha256=6krsN0G89hBy1bcPP50ouT1tMppeLhOv5WvnWCSCMIg,52
+django_auth_headless/adapters.py,sha256=Fb6IdPWnl0Qpf6JrvBoi9vWb9zCYBe0tn4szU04NMmg,767
+django_auth_headless/apps.py,sha256=vJKY45i3BdHRdpqLiJG-bcUmosGtq9hT02T_qmP6N24,253
+django_auth_headless/conf.py,sha256=v5qqmCNJjb2nAJhwSpRvrEozBGlZoJudAr2zTILGX8c,7178
+django_auth_headless/site_helpers.py,sha256=5FTZtJXhYotxnHo42vHf_yTjbp-Z_OjO6EIh-cmFwIs,695
+django_auth_headless/urls.py,sha256=x19pZxrmMn2D2FnpYAKDi_5lgOhLDCqZNyt-xDEd5VU,324
+django_auth_headless/utils.py,sha256=OMNOznFUFNKud8clkXFr252z0CpYF7i9atMtT23svWs,2277
+django_auth_headless/views.py,sha256=204Ho-Y51Zc91PuRHHIQNBT7FjnfykkRvsFRCAnl5bs,973
+django_auth_headless/management/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+django_auth_headless/management/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+django_auth_headless/management/commands/setup_oauth.py,sha256=XIE3cA-DrBPTxZq840yspCDFAIyfpWD2EAaXnrQxPHI,3692
+django_auth_headless/management/commands/verify_oauth.py,sha256=lBRfcgcgza0-S3PNk29BG7suuOh4A6kqaY9bWDJnQWU,4969
+django_auth_headless-0.1.0.dist-info/METADATA,sha256=jklYx2wpzssLUovi_VofiYUOjvH3fdCWOYeD3Vq2QeQ,5218
+django_auth_headless-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+django_auth_headless-0.1.0.dist-info/licenses/LICENSE,sha256=LYJxC1x3a7xCAmNEpohrWFMJ6i8hqKtIBFGkGxuDejw,1069
+django_auth_headless-0.1.0.dist-info/RECORD,,

django_auth_headless-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

django_auth_headless-0.1.0.dist-info/licenses/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.