# Django Allauth (Headless) Skill

Headless authentication setup for Django backends that serve React/Vue/mobile frontends. Adds django-allauth with MFA, social login, CORS, and REST endpoints—no server-rendered auth pages.

## What This Skill Delivers
- Installs auth stack: `django-allauth[socialaccount,mfa]`, `djangorestframework`, `django-cors-headers`, `fido2`, `python3-openid`, `Pillow`, `pyyaml`, `python-dotenv`.
- Configures headless mode (`HEADLESS_ONLY = True`) with frontend redirect URLs for email verification, password reset, signup, and social errors.
- Enables MFA (TOTP + WebAuthn/passkeys + recovery codes) and Google OAuth example.
- Sets CORS/CSRF for a separate HTTPS frontend (`FRONTEND_URL`), uses session/JWT-friendly middleware ordering.
- Adds REST URL prefixes: `accounts/` (admin/backend) and `_allauth/` (headless API).
- Provides validation harness to run the official headless allauth tests (76 core cases) via `scripts/validate_allauth_tests.sh` and detailed coverage notes in `references/test-validation-guide.md`.

## Skill Contents
- `SKILL.md` — step-by-step build instructions (install deps → settings.py edits → .env → URLs → checks → migrations → tests).
- `scripts/validate_allauth_tests.sh` — helper to run core allauth tests after cloning `django-allauth`.
- `references/test-validation-guide.md` — explains test categories, required pytest versions, and troubleshooting.

## Prerequisites
- Existing Django project with virtualenv.
- `FRONTEND_URL` to point at your HTTPS SPA (e.g., `https://localhost:5173`).

## Setup Summary (see SKILL.md for exact edits)
1) **Install packages** (venv active):
   ```bash
   pip install 'django-allauth[socialaccount,mfa]' python-dotenv djangorestframework django-cors-headers fido2 python3-openid Pillow pyyaml
   ```
2) **settings.py changes:**
   - Load env vars: `from dotenv import load_dotenv; load_dotenv('.env.development')`.
   - Add CORS/CSRF hosts: `FRONTEND_URL`, `ALLOWED_HOSTS`, `CORS_ALLOWED_ORIGINS`, `CSRF_TRUSTED_ORIGINS`.
   - Ensure `django.template.context_processors.request` is in `TEMPLATES[0]['OPTIONS']['context_processors']`.
   - `INSTALLED_APPS` add: `corsheaders`, `rest_framework`, `allauth`, `allauth.account`, `allauth.socialaccount`, `allauth.socialaccount.providers.google`, `allauth.mfa`, `allauth.headless`, `allauth.usersessions`.
   - `MIDDLEWARE` order: keep `corsheaders.middleware.CorsMiddleware` after `SessionMiddleware`; add `allauth.account.middleware.AccountMiddleware` after `MessageMiddleware`.
   - Auth backends + headless/MFA/social/email settings appended at file end (see SKILL.md block).
3) **Environment file** `.env.development` in project root:
   ```
   GOOGLE_CLIENT_ID=
   GOOGLE_CLIENT_SECRET=
   ```
4) **URLs** in project `urls.py`:
   ```python
   path('accounts/', include('allauth.urls')),
   path('_allauth/', include('allauth.headless.urls')),
   ```
5) **Sanity checks & DB**:
   ```bash
   python manage.py check
   python manage.py migrate
   ```
6) **Optional validation tests** (after cloning `django-allauth` sibling to project):
   ```bash
   bash scripts/validate_allauth_tests.sh
   ```

## Outputs/Artifacts
- Headless auth APIs ready for SPA use.
- MFA-ready user flows (TOTP/WebAuthn/recovery codes).
- Dev email backend writes files to `sent_emails/` (adjust for production).
- Updated `requirements.txt` (after `pip freeze`).

## Notes & Gotchas
- Use pytest `<9.0` and `pytest-asyncio==0.23.8` for the provided test suite.
- Keep middleware order exact to avoid CORS/login issues.
- Set `MFA_WEBAUTHN_ALLOW_INSECURE_ORIGIN = True if DEBUG else False` so localhost HTTPS works during development.