Initial commit

skills/django-allauth/README.md

@@ -0,0 +1,63 @@
+# 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.