django-clerk-users 0.0.1__py3-none-any.whl → 0.1.0__py3-none-any.whl

django_clerk_users-0.1.0.dist-info/METADATA

@@ -0,0 +1,311 @@
+Metadata-Version: 2.4
+Name: django-clerk-users
+Version: 0.1.0
+Summary: Integrate Clerk with Django
+Project-URL: Changelog, https://github.com/jmitchel3/django-clerk-users
+Project-URL: Documentation, https://github.com/jmitchel3/django-clerk-users
+Project-URL: Funding, https://github.com/jmitchel3/django-clerk-users
+Project-URL: Repository, https://github.com/jmitchel3/django-clerk-users
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.12
+Requires-Dist: clerk-backend-api>=1.0.0
+Requires-Dist: django>=4.2
+Requires-Dist: svix>=1.0.0
+Provides-Extra: drf
+Requires-Dist: djangorestframework>=3.14; extra == 'drf'
+Description-Content-Type: text/markdown
+
+# Django Clerk Users
+
+Integrate [Clerk](https://clerk.com) authentication with Django.
+
+> **Note:** This package is in early development (v0.0.2). APIs may change.
+
+## Features
+
+- Custom user model (`ClerkUser`) with Clerk integration
+- JWT token validation via Clerk SDK
+- Session-based authentication middleware (validates once, caches in session)
+- Webhook handling with Svix signature verification
+- Optional organizations support (separate sub-app)
+- Django REST Framework authentication (optional)
+
+## Installation
+
+```bash
+pip install django-clerk-users
+```
+
+For Django REST Framework support:
+
+```bash
+pip install django-clerk-users[drf]
+```
+
+## Quick Start
+
+### 1. Add to installed apps
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "django_clerk_users",
+    # Optional: for organization support
+    # "django_clerk_users.organizations",
+]
+```
+
+### 2. Configure settings
+
+```python
+# Required
+CLERK_SECRET_KEY = "sk_live_..."  # From Clerk Dashboard
+CLERK_WEBHOOK_SIGNING_KEY = "whsec_..."  # From Clerk Webhooks
+CLERK_FRONTEND_HOSTS = ["https://your-app.com"]  # Your frontend URLs
+
+# Optional
+CLERK_SESSION_REVALIDATION_SECONDS = 300  # Re-validate JWT every 5 minutes
+CLERK_CACHE_TIMEOUT = 300  # Cache timeout for user lookups
+```
+
+### 3. Set the user model
+
+```python
+AUTH_USER_MODEL = "django_clerk_users.ClerkUser"
+```
+
+Or extend the abstract model for custom fields:
+
+```python
+# myapp/models.py
+from django_clerk_users.models import AbstractClerkUser
+
+class CustomUser(AbstractClerkUser):
+    company = models.CharField(max_length=255, blank=True)
+
+    class Meta(AbstractClerkUser.Meta):
+        swappable = "AUTH_USER_MODEL"
+
+# settings.py
+AUTH_USER_MODEL = "myapp.CustomUser"
+```
+
+### 4. Add middleware
+
+```python
+MIDDLEWARE = [
+    "django.middleware.security.SecurityMiddleware",
+    "django.contrib.sessions.middleware.SessionMiddleware",
+    "django.middleware.common.CommonMiddleware",
+    "django.middleware.csrf.CsrfViewMiddleware",
+    "django.contrib.auth.middleware.AuthenticationMiddleware",
+    "django_clerk_users.middleware.ClerkAuthMiddleware",  # Add after AuthenticationMiddleware
+    # ...
+]
+```
+
+### 5. Add authentication backend
+
+**For Clerk-only authentication:**
+
+```python
+AUTHENTICATION_BACKENDS = [
+    "django_clerk_users.authentication.ClerkBackend",
+]
+```
+
+**For hybrid authentication (Clerk + Django admin):**
+
+If you want to support both Clerk authentication (JWT) and traditional Django admin login (username/password), use both backends:
+
+```python
+AUTHENTICATION_BACKENDS = [
+    "django.contrib.auth.backends.ModelBackend",  # For Django admin
+    "django_clerk_users.authentication.ClerkBackend",  # For Clerk JWT
+]
+```
+
+This allows:
+- Admin users to log in via Django admin with username/password
+- Frontend users to authenticate via Clerk JWT tokens
+- The middleware automatically detects which authentication method was used
+
+### 6. Run migrations
+
+```bash
+python manage.py migrate
+```
+
+### 7. Configure webhooks
+
+Add the webhook URL to your `urls.py`:
+
+```python
+from django_clerk_users.webhooks import clerk_webhook_view
+
+urlpatterns = [
+    # ...
+    path("webhooks/clerk/", clerk_webhook_view, name="clerk_webhook"),
+]
+```
+
+Then configure your Clerk Dashboard to send webhooks to `https://your-app.com/webhooks/clerk/`.
+
+### 8. Create admin users (for hybrid authentication)
+
+If you're using hybrid authentication, create an admin user for Django admin access:
+
+```bash
+python manage.py createsuperuser
+```
+
+This creates a user with:
+- Username/password authentication (for Django admin)
+- No `clerk_id` (since they're not Clerk users)
+- Access to Django admin panel
+
+Note: Regular Clerk users are created automatically via webhooks when they sign up through your frontend.
+
+## Usage
+
+### Accessing the user in views
+
+```python
+def my_view(request):
+    if request.user.is_authenticated:
+        # Access Clerk user attributes
+        print(request.user.clerk_id)
+        print(request.user.email)
+        print(request.user.full_name)
+
+        # Access organization (if using organizations)
+        print(request.org)  # Organization ID from JWT
+```
+
+### Decorators
+
+```python
+from django_clerk_users.decorators import clerk_user_required
+
+@clerk_user_required
+def protected_view(request):
+    # Only authenticated Clerk users can access
+    return HttpResponse(f"Hello, {request.user.email}")
+```
+
+### Django REST Framework
+
+```python
+# settings.py
+REST_FRAMEWORK = {
+    "DEFAULT_AUTHENTICATION_CLASSES": [
+        "django_clerk_users.authentication.ClerkAuthentication",
+    ],
+}
+```
+
+## Hybrid Authentication (Clerk + Django Admin)
+
+The package supports hybrid authentication, allowing you to use both Clerk (JWT-based) authentication for your frontend users and traditional Django admin authentication for internal staff.
+
+### How it works
+
+1. **Frontend users**: Authenticate via Clerk JWT tokens (handled by `ClerkAuthMiddleware`)
+2. **Admin users**: Authenticate via username/password (handled by Django's `ModelBackend`)
+3. The middleware automatically detects which authentication method was used and respects existing sessions
+
+### Configuration
+
+```python
+# settings.py
+AUTHENTICATION_BACKENDS = [
+    "django.contrib.auth.backends.ModelBackend",  # For Django admin
+    "django_clerk_users.authentication.ClerkBackend",  # For Clerk JWT
+]
+```
+
+### Creating admin users
+
+Admin users don't need a `clerk_id` (it's optional in hybrid mode):
+
+```bash
+python manage.py createsuperuser
+# Email: admin@example.com
+# Password: ********
+```
+
+This creates a user with:
+- Username/password authentication (no Clerk integration)
+- Access to Django admin panel at `/admin/`
+- Standard Django permissions (is_staff, is_superuser)
+
+### Session handling
+
+- **Django admin sessions**: Traditional session cookies (set by Django's auth system)
+- **Clerk sessions**: JWT validated once, then cached in session with `last_clerk_check` marker
+- The middleware checks for `last_clerk_check` to distinguish between the two types
+
+### Use cases
+
+This is particularly useful when:
+- Your admin panel is on a different domain than your frontend
+- You want internal staff to access Django admin without Clerk accounts
+- You need traditional Django auth features (permissions, groups, etc.)
+- You're migrating from Django auth to Clerk gradually
+
+## Organizations (Optional)
+
+For Clerk organization support:
+
+```python
+# settings.py
+INSTALLED_APPS = [
+    # ...
+    "django_clerk_users",
+    "django_clerk_users.organizations",
+]
+
+MIDDLEWARE = [
+    # ...
+    "django_clerk_users.middleware.ClerkAuthMiddleware",
+    "django_clerk_users.organizations.middleware.ClerkOrganizationMiddleware",
+]
+```
+
+## Management Commands
+
+```bash
+# Sync users from Clerk
+python manage.py sync_clerk_users
+
+# Sync organizations from Clerk
+python manage.py sync_clerk_organizations
+```
+
+## Configuration Reference
+
+| Setting | Required | Default | Description |
+|---------|----------|---------|-------------|
+| `CLERK_SECRET_KEY` | Yes | - | Your Clerk secret key |
+| `CLERK_WEBHOOK_SIGNING_KEY` | Yes* | - | Webhook signing secret (*required for webhooks) |
+| `CLERK_FRONTEND_HOSTS` | Yes | `[]` | Authorized frontend URLs |
+| `CLERK_AUTH_PARTIES` | No | `[]` | Alias for `CLERK_FRONTEND_HOSTS` |
+| `CLERK_SESSION_REVALIDATION_SECONDS` | No | `300` | JWT revalidation interval (seconds) |
+| `CLERK_CACHE_TIMEOUT` | No | `300` | User cache timeout (seconds) |
+| `CLERK_ORG_CACHE_TIMEOUT` | No | `900` | Organization cache timeout (seconds) |
+| `CLERK_WEBHOOK_DEDUP_TIMEOUT` | No | `45` | Webhook deduplication cache timeout (seconds) |
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please open an issue or PR on [GitHub](https://github.com/jmitchel3/django-clerk-users).

django_clerk_users-0.1.0.dist-info/RECORD

@@ -0,0 +1,43 @@
+django_clerk_users/__init__.py,sha256=Ph93iT6_RNdZej3GM6cez-cJjiXw6w1V-u4GCnGP8TY,2287
+django_clerk_users/apps.py,sha256=upj0qWYVg4P2D6_Vt8QZWTfBpAdIP7EAQjVjEnfHLRA,729
+django_clerk_users/caching.py,sha256=QXRd9cFvvUucrnLBd7_PId3xDodqcessDMybkHyskkU,4651
+django_clerk_users/checks.py,sha256=gnHccAyXixtGToGhgWl4gfCY-qPB5ckimpDVadOP3E4,4191
+django_clerk_users/client.py,sha256=-nBXsPOibVwD7zXQ-Z-qTBb7NyPuUZpvlDcAlDVFUBA,815
+django_clerk_users/decorators.py,sha256=Hm86XIxNdSiuDmqT8tFRrz6sQR9IOxB7zfxfO8MeJLg,5011
+django_clerk_users/exceptions.py,sha256=nVTJR1d5PxuMqC8js1Sj-MRHJHkI4KUwphjuCEN4fiM,890
+django_clerk_users/managers.py,sha256=HvSkGeiQhjA6EFXrW4GTlxXtlRDtlT54BbwbvnNuOWg,3610
+django_clerk_users/models.py,sha256=DMcEnGNioGX5xsP4U47ich1L_UoZNAFEDb-vZVVV8Tk,5210
+django_clerk_users/settings.py,sha256=pRyt_kSPWOT8CkTvyce3sf0RxfIoG5DEwnGUT8bIDi8,1305
+django_clerk_users/testing.py,sha256=ZoYi7dG_HjSp19_c1AvILOoCfHlofs7LN-5ALS_UhDw,12160
+django_clerk_users/utils.py,sha256=bQWfPUKfVvXi69Ctny1T1Kxzk-qMDpXQBRVa6URH53I,5886
+django_clerk_users/authentication/__init__.py,sha256=PStQVzC-CA2Guyo4ksrxP58o93mfygW4qcJXWEjs6ak,614
+django_clerk_users/authentication/backends.py,sha256=We0P2AhMv_DB_ZwtFGmmjWKvT5Cewy441Iua2lAZZCg,2400
+django_clerk_users/authentication/drf.py,sha256=AqHvZTe9RnxN7FVzlSUXR72QBj2imGglkx9rpOrRDIk,3215
+django_clerk_users/authentication/utils.py,sha256=tpnRXQLbQPkosKV8OhxtXpapuema4c08g58YYmMl3js,5326
+django_clerk_users/management/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+django_clerk_users/management/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+django_clerk_users/management/commands/migrate_users_to_clerk.py,sha256=qjw4Q6pU7-4Tt7XourTzCw7IBm5kkOau4mPkW2Vz13E,8047
+django_clerk_users/management/commands/sync_clerk_organizations.py,sha256=G1kasAPvvwM-PPb5xXxKNlex_-gWyKDP2HLS5g8hVkk,6656
+django_clerk_users/management/commands/sync_clerk_users.py,sha256=hvWrvcqAkZHvjqQAOj3-e6pKx5TKtArmlsHDUottRMM,3755
+django_clerk_users/middleware/__init__.py,sha256=tnr4eBer0KGVBAZBgBQZVpcL7jf8t2_CBLsMnau5JW4,153
+django_clerk_users/middleware/auth.py,sha256=FLo4DHkiL3QnEPZsvJDGFIahfH1HUcqkBEzYXEx0fN0,8889
+django_clerk_users/migrations/0001_initial.py,sha256=tnPvGlLnWrItuhYS0s5mr3TJ8__2e_yNKJS4nsFuWhk,6246
+django_clerk_users/migrations/0002_make_clerk_id_nullable.py,sha256=OXad63KPFTMLn2lkwkuNkr8ZbM6BiNlsw6z72fhY-eU,640
+django_clerk_users/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+django_clerk_users/organizations/__init__.py,sha256=NZU2C8F4Trm63_qaUf78jROKz6XFnu36uREkw7g_yho,270
+django_clerk_users/organizations/admin.py,sha256=u7qHMgb11akHiJ2FCzqbSLQ3_TsTiejf0wH10f5_PPQ,1838
+django_clerk_users/organizations/apps.py,sha256=IgKNl5REkAgLDHC06GFI-a3x3Mi2HWN4L-El0Ef6CE8,252
+django_clerk_users/organizations/middleware.py,sha256=5Gvu28SCEqpuIjr2Fah5O85m0wnjMiDp4vxdvVzJh68,4129
+django_clerk_users/organizations/models.py,sha256=rGy3udfo2xO6XBMPHS7eTTk9meyxx_3GI9zL9lH-ScY,8602
+django_clerk_users/organizations/webhooks.py,sha256=zp16_vL5j7DEaVC5ZxgYwrE8zPpUsRIq8TGBd8SYhoo,14321
+django_clerk_users/organizations/migrations/0001_initial.py,sha256=NXZ63PLqkX0ebavvLk6aHOffiFDq0pZamEelb6PG4Yg,12625
+django_clerk_users/organizations/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+django_clerk_users/webhooks/__init__.py,sha256=XlpsPmc_lHQkZVMeuXce_2hsq7WZzXOXNy36kiQA5Lk,558
+django_clerk_users/webhooks/handlers.py,sha256=GnotJNhN809DsrbfZjtJD0KurThKyAXZS982a41ljwg,9457
+django_clerk_users/webhooks/security.py,sha256=Ig2ZxF8SxX5o-4bNRehFhip4hVvcQxoGsTj3sTY3WSU,3461
+django_clerk_users/webhooks/signals.py,sha256=bytshg7IMDnlvnCZ0_TGjUXZZLRNxtn2RSx97qacZ-w,1668
+django_clerk_users/webhooks/views.py,sha256=0-ilzzO7tBfc-pENMy0ZSSkQ4uPqH2QAt249EK2wQKA,2287
+django_clerk_users-0.1.0.dist-info/METADATA,sha256=JSE1da_-Xl_lXQimkztPbpz1bY4MF45wkQY2K49U75E,8687
+django_clerk_users-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+django_clerk_users-0.1.0.dist-info/licenses/LICENSE,sha256=X4PZDRQG4RmPhHU5c0G21Ki9LXWDCuLQ8W4mnED5RDU,1071
+django_clerk_users-0.1.0.dist-info/RECORD,,

{django_clerk_users-0.0.1.dist-info → django_clerk_users-0.1.0.dist-info}/WHEEL

@@ -1,5 +1,4 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: hatchling 1.28.0
 Root-Is-Purelib: true
 Tag: py3-none-any
-

django_clerk_users/main.py

@@ -1,2 +0,0 @@
-def hello_world():
-    return "Hello from django-clerk-users!"

django_clerk_users-0.0.1.dist-info/METADATA

@@ -1,24 +0,0 @@
-Metadata-Version: 2.4
-Name: django-clerk-users
-Version: 0.0.1
-Summary: Integrate Clerk with Django
-Project-URL: Changelog, https://github.com/jmitchel3/django-clerk-users
-Project-URL: Documentation, https://github.com/jmitchel3/django-clerk-users
-Project-URL: Funding, https://github.com/jmitchel3/django-clerk-users
-Project-URL: Repository, https://github.com/jmitchel3/django-clerk-users
-Classifier: Development Status :: 4 - Beta
-Classifier: Framework :: Django
-Classifier: Framework :: Django :: 4.2
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Requires-Python: >=3.12
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: django>=4.2
-Dynamic: license-file
-
-# Django Clerk Users
-
-Integrate Clerk with Django, coming soon.

django_clerk_users-0.0.1.dist-info/RECORD

@@ -1,7 +0,0 @@
-django_clerk_users/__init__.py,sha256=L_pMt2_tM2dlDpsSo12M-kG_qW6TlMCr-sk0KMfKAxE,549
-django_clerk_users/main.py,sha256=RfM09MvG3C2hmAH5l0RM-lbYatU_58RmkEpjrHtE2BM,63
-django_clerk_users-0.0.1.dist-info/licenses/LICENSE,sha256=X4PZDRQG4RmPhHU5c0G21Ki9LXWDCuLQ8W4mnED5RDU,1071
-django_clerk_users-0.0.1.dist-info/METADATA,sha256=S8sFVa0UAXvgXnLdmBLrD7QXzR7Tubn76v7cnqyrn3c,913
-django_clerk_users-0.0.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-django_clerk_users-0.0.1.dist-info/top_level.txt,sha256=m2CUZNVRrrVHorKdGlRLuGJbc0NFgx1f2GGjpTLuGXY,19
-django_clerk_users-0.0.1.dist-info/RECORD,,

django_clerk_users-0.0.1.dist-info/top_level.txt

@@ -1 +0,0 @@
-django_clerk_users