stapel-core 0.3.2__tar.gz

stapel_core-0.3.2/LICENSE

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

stapel_core-0.3.2/PKG-INFO

@@ -0,0 +1,294 @@
+Metadata-Version: 2.4
+Name: stapel-core
+Version: 0.3.2
+Summary: Core Django utilities for the Stapel framework
+License: MIT
+Keywords: django,stapel,auth,jwt
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.2
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Django>=5.1
+Requires-Dist: djangorestframework>=3.14
+Requires-Dist: djangorestframework-dataclasses>=1.2
+Requires-Dist: drf-spectacular>=0.27
+Requires-Dist: django-cors-headers>=4.3
+Requires-Dist: django-redis>=5.4
+Requires-Dist: PyJWT>=2.8
+Requires-Dist: cryptography>=41.0
+Requires-Dist: requests>=2.31
+Requires-Dist: phonenumbers>=8.13
+Provides-Extra: kafka
+Requires-Dist: confluent-kafka>=2.3; extra == "kafka"
+Provides-Extra: nats
+Requires-Dist: nats-py>=2.9; extra == "nats"
+Provides-Extra: sentry
+Requires-Dist: sentry-sdk>=1.40; extra == "sentry"
+Provides-Extra: netintel-maxmind
+Requires-Dist: geoip2>=4.7; extra == "netintel-maxmind"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: pytest-cov>=4.1; extra == "dev"
+Requires-Dist: celery>=5.3; extra == "dev"
+Provides-Extra: all
+Requires-Dist: stapel-core[kafka,nats,netintel-maxmind,sentry]; extra == "all"
+Dynamic: license-file
+
+# stapel_core
+
+[![CI](https://github.com/usestapel/stapel-core/actions/workflows/ci.yml/badge.svg)](https://github.com/usestapel/stapel-core/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/usestapel/stapel-core/graph/badge.svg)](https://codecov.io/gh/usestapel/stapel-core)
+
+Shared Python library for Stapel services. Provides JWT authentication, captcha
+verification, event bus, notifications, and Django utilities used across all
+backend services.
+
+Part of the [Stapel framework](https://github.com/usestapel).
+
+## Quick start for a new Django service
+
+```bash
+pip install -e ../iron-common-python
+```
+
+Add to `INSTALLED_APPS`:
+
+```python
+INSTALLED_APPS = [
+    ...
+    'stapel_core.django',
+    'stapel_core.django.users',   # if using the shared User model
+]
+```
+
+## Modules
+
+### `stapel_core.captcha` — Pluggable captcha verification
+
+Backend-agnostic captcha interface. Supports Cloudflare Turnstile, Google
+reCAPTCHA v2, hCaptcha, and custom backends.
+
+**Settings** (per service, in `settings/base.py`):
+
+```python
+CAPTCHA_BACKEND = env.str('CAPTCHA_BACKEND', 'turnstile')
+CAPTCHA_SECRET  = env.str('CAPTCHA_SECRET', None)  # absent → disabled
+```
+
+**Auto-disable**: if `CAPTCHA_SECRET` is `None` or empty, `build_verifier`
+returns `NoopVerifier` regardless of backend. No separate toggle needed.
+
+**DRF integration** (add mixin to any serializer):
+
+```python
+from stapel_core.django.captcha import CaptchaMixin
+
+class MySerializer(CaptchaMixin, serializers.Serializer):
+    captcha_token = serializers.CharField(required=False, allow_blank=True)
+
+    def validate(self, attrs):
+        self._require_captcha_if_configured(attrs)
+        return attrs
+```
+
+**Custom backend** — subclass `CaptchaVerifier` and point to it via a dotted
+import path:
+
+```python
+from stapel_core.captcha import CaptchaVerifier
+
+class MyCaptchaVerifier(CaptchaVerifier):
+    def verify(self, token: str, ip: str | None = None) -> bool:
+        return my_service.check(token, self.secret)
+```
+
+```python
+# settings.py
+CAPTCHA_BACKEND = 'myapp.captcha.MyCaptchaVerifier'
+CAPTCHA_SECRET  = 'my-secret'
+```
+
+The flat settings above keep working; the namespaced equivalent is
+`STAPEL_CAPTCHA = {"BACKEND": ..., "SECRET": ...}`.
+
+**Tiered challenge policy** — instead of a binary on/off, protect a view with
+a strictness level derived from the client's network class (via
+`stapel_core.netintel`):
+
+```python
+from stapel_core.django.captcha import captcha_protected
+
+class RegisterView(APIView):
+    @captcha_protected(action="register")
+    def post(self, request): ...
+```
+
+Levels: `none < invisible < interactive < interactive+ratelimit < block`.
+The default matrix (overridable via `STAPEL_CAPTCHA["CHALLENGE_MATRIX"]`,
+merged over the defaults) maps residential/unknown → invisible,
+datacenter/vpn → interactive, tor → interactive+ratelimit. Per-action
+overrides: `STAPEL_CAPTCHA["ACTION_OVERRIDES"] = {"register": "+1"}` (bump one
+level) or `{"payout": {"vpn": "block"}}`. The whole policy is swappable via
+`STAPEL_CAPTCHA["CHALLENGE_POLICY"]` (dotted path to a `ChallengePolicy`).
+`block` returns 403 `error.403.network_blocked`; rate limiting is not done
+here — middleware reads `request.stapel_challenge_level`. With no netintel
+provider configured every request classifies as `unknown` → behavior is
+identical to the classic binary captcha.
+
+---
+
+### `stapel_core.netintel` — IP intelligence (network class + geo)
+
+`classify_ip(ip) -> IpProfile{kind, asn, asn_org, country, confidence}` and
+`country_of(ip)`. Kind vocabulary: `residential | datacenter | vpn | tor |
+unknown`. Results are cached in the Django cache; provider errors fail open
+to `unknown` and never raise.
+
+```python
+STAPEL_NETINTEL = {
+    # dotted path / class / instance of a NetIntelProvider (replace seam)
+    "PROVIDER": "stapel_core.netintel.providers.MaxMindProvider",
+    "MAXMIND_ASN_DB": "/var/geoip/GeoLite2-ASN.mmdb",
+    "MAXMIND_COUNTRY_DB": "/var/geoip/GeoLite2-Country.mmdb",
+    "MAXMIND_ANONYMOUS_DB": "/var/geoip/GeoIP2-Anonymous-IP.mmdb",
+}
+```
+
+Built-in providers: `NullProvider` (default — always `unknown`),
+`MaxMindProvider` (offline mmdb, `pip install stapel-core[netintel-maxmind]`),
+`HttpJsonProvider` (ipinfo/IPQS-style HTTP APIs via `HTTP_URL_TEMPLATE` /
+`HTTP_API_KEY` / `HTTP_RESPONSE_MAPPER`). `client_ip(request)` honors
+`TRUSTED_PROXY_HEADER` (default: `REMOTE_ADDR` only — proxy headers are
+spoofable unless your edge overwrites them).
+
+---
+
+### `stapel_core.django.jwt` — JWT authentication
+
+Unified JWT provider (singleton). Supports HS256 and RS256.
+
+```python
+from stapel_core.django.jwt.provider import jwt_provider
+
+access, refresh = jwt_provider.create_tokens(user)
+payload = jwt_provider.validate_token(access_token)
+```
+
+**Settings**:
+
+```python
+JWT_ALGORITHM    = 'HS256'           # or 'RS256'
+JWT_SECRET_KEY   = 'your-secret'     # HS256
+JWT_PRIVATE_KEY  = '...'             # RS256
+JWT_PUBLIC_KEY   = '...'             # RS256
+JWT_ISSUER       = 'https://yourapp.com'
+JWT_AUDIENCE     = None
+JWT_ACCESS_TOKEN_LIFETIME  = 900     # seconds
+JWT_REFRESH_TOKEN_LIFETIME = 604800  # seconds
+```
+
+---
+
+### `stapel_core.django.authentication` — JWT cookie auth
+
+`JWTCookieAuthentication` reads JWT from `access_token` cookie or
+`Authorization: Bearer <token>` header.
+
+```python
+REST_FRAMEWORK = {
+    'DEFAULT_AUTHENTICATION_CLASSES': [
+        'stapel_core.django.authentication.JWTCookieAuthentication',
+    ],
+}
+```
+
+---
+
+### `stapel_core.django.api` — DRF utilities
+
+| Symbol | Purpose |
+|---|---|
+| `StapelDataclassSerializer` | Serializer that maps `@dataclass` fields |
+| `StapelResponse(serializer)` | Wraps `.data` automatically |
+| `StapelErrorResponse(status, ERR_KEY)` | Structured error response |
+| `StapelValidationError(ERR_KEY)` | Raises DRF validation error with error key |
+| `register_service_errors(dict)` | Registers error messages for a service |
+| `AnchorPagination` / `CreatedAtAnchorPagination` | Cursor-style paginators |
+
+---
+
+### `stapel_core.bus` — Event bus
+
+Kafka-backed event bus with an in-memory backend for tests.
+
+**Publish** (sync, fire-and-forget):
+
+```python
+from stapel_core.bus import publish, Event
+
+publish('user.created', Event(
+    event_type='user.created',
+    service='auth',
+    payload={'user_id': '...'},
+))
+```
+
+**Consume** by subclassing the management-command base:
+
+```python
+from stapel_core.bus import BaseBusConsumerCommand, Event
+
+class ConsumeUsers(BaseBusConsumerCommand):
+    topics = ['user.created']
+    consumer_group = 'notifications'
+
+    def handle_event(self, event: Event) -> None:
+        ...
+```
+
+Backend is selected via the `STAPEL_BUS_BACKEND` Django setting
+(`stapel_core.bus.backends.kafka.KafkaBus` in production,
+`stapel_core.bus.backends.memory.MemoryBus` in tests).
+
+---
+
+### `stapel_core.notifications` — Push notifications
+
+```python
+from stapel_core.notifications import request_notification
+
+request_notification(
+    notification_type='welcome',
+    user_id=str(user.id),
+    email=user.email,
+    variables={'name': user.username},
+    source_service='auth',
+)
+```
+
+---
+
+### `stapel_core.oauth` — OAuth provider registry
+
+Provider classes (`GoogleProvider`, `GitHubProvider`, etc.) and registry for
+OAuth consumer flows (when your service accepts OAuth logins from external
+providers).
+
+---
+
+### `stapel_core.gdpr` — GDPR utilities
+
+Account closure requests, data export, re-registration hashes.
+
+---
+
+## Running tests
+
+```bash
+cd iron-common-python
+pip install -e '.[dev]'
+pytest stapel_core/tests/ -v
+```

stapel_core-0.3.2/README.md

@@ -0,0 +1,255 @@
+# stapel_core
+
+[![CI](https://github.com/usestapel/stapel-core/actions/workflows/ci.yml/badge.svg)](https://github.com/usestapel/stapel-core/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/usestapel/stapel-core/graph/badge.svg)](https://codecov.io/gh/usestapel/stapel-core)
+
+Shared Python library for Stapel services. Provides JWT authentication, captcha
+verification, event bus, notifications, and Django utilities used across all
+backend services.
+
+Part of the [Stapel framework](https://github.com/usestapel).
+
+## Quick start for a new Django service
+
+```bash
+pip install -e ../iron-common-python
+```
+
+Add to `INSTALLED_APPS`:
+
+```python
+INSTALLED_APPS = [
+    ...
+    'stapel_core.django',
+    'stapel_core.django.users',   # if using the shared User model
+]
+```
+
+## Modules
+
+### `stapel_core.captcha` — Pluggable captcha verification
+
+Backend-agnostic captcha interface. Supports Cloudflare Turnstile, Google
+reCAPTCHA v2, hCaptcha, and custom backends.
+
+**Settings** (per service, in `settings/base.py`):
+
+```python
+CAPTCHA_BACKEND = env.str('CAPTCHA_BACKEND', 'turnstile')
+CAPTCHA_SECRET  = env.str('CAPTCHA_SECRET', None)  # absent → disabled
+```
+
+**Auto-disable**: if `CAPTCHA_SECRET` is `None` or empty, `build_verifier`
+returns `NoopVerifier` regardless of backend. No separate toggle needed.
+
+**DRF integration** (add mixin to any serializer):
+
+```python
+from stapel_core.django.captcha import CaptchaMixin
+
+class MySerializer(CaptchaMixin, serializers.Serializer):
+    captcha_token = serializers.CharField(required=False, allow_blank=True)
+
+    def validate(self, attrs):
+        self._require_captcha_if_configured(attrs)
+        return attrs
+```
+
+**Custom backend** — subclass `CaptchaVerifier` and point to it via a dotted
+import path:
+
+```python
+from stapel_core.captcha import CaptchaVerifier
+
+class MyCaptchaVerifier(CaptchaVerifier):
+    def verify(self, token: str, ip: str | None = None) -> bool:
+        return my_service.check(token, self.secret)
+```
+
+```python
+# settings.py
+CAPTCHA_BACKEND = 'myapp.captcha.MyCaptchaVerifier'
+CAPTCHA_SECRET  = 'my-secret'
+```
+
+The flat settings above keep working; the namespaced equivalent is
+`STAPEL_CAPTCHA = {"BACKEND": ..., "SECRET": ...}`.
+
+**Tiered challenge policy** — instead of a binary on/off, protect a view with
+a strictness level derived from the client's network class (via
+`stapel_core.netintel`):
+
+```python
+from stapel_core.django.captcha import captcha_protected
+
+class RegisterView(APIView):
+    @captcha_protected(action="register")
+    def post(self, request): ...
+```
+
+Levels: `none < invisible < interactive < interactive+ratelimit < block`.
+The default matrix (overridable via `STAPEL_CAPTCHA["CHALLENGE_MATRIX"]`,
+merged over the defaults) maps residential/unknown → invisible,
+datacenter/vpn → interactive, tor → interactive+ratelimit. Per-action
+overrides: `STAPEL_CAPTCHA["ACTION_OVERRIDES"] = {"register": "+1"}` (bump one
+level) or `{"payout": {"vpn": "block"}}`. The whole policy is swappable via
+`STAPEL_CAPTCHA["CHALLENGE_POLICY"]` (dotted path to a `ChallengePolicy`).
+`block` returns 403 `error.403.network_blocked`; rate limiting is not done
+here — middleware reads `request.stapel_challenge_level`. With no netintel
+provider configured every request classifies as `unknown` → behavior is
+identical to the classic binary captcha.
+
+---
+
+### `stapel_core.netintel` — IP intelligence (network class + geo)
+
+`classify_ip(ip) -> IpProfile{kind, asn, asn_org, country, confidence}` and
+`country_of(ip)`. Kind vocabulary: `residential | datacenter | vpn | tor |
+unknown`. Results are cached in the Django cache; provider errors fail open
+to `unknown` and never raise.
+
+```python
+STAPEL_NETINTEL = {
+    # dotted path / class / instance of a NetIntelProvider (replace seam)
+    "PROVIDER": "stapel_core.netintel.providers.MaxMindProvider",
+    "MAXMIND_ASN_DB": "/var/geoip/GeoLite2-ASN.mmdb",
+    "MAXMIND_COUNTRY_DB": "/var/geoip/GeoLite2-Country.mmdb",
+    "MAXMIND_ANONYMOUS_DB": "/var/geoip/GeoIP2-Anonymous-IP.mmdb",
+}
+```
+
+Built-in providers: `NullProvider` (default — always `unknown`),
+`MaxMindProvider` (offline mmdb, `pip install stapel-core[netintel-maxmind]`),
+`HttpJsonProvider` (ipinfo/IPQS-style HTTP APIs via `HTTP_URL_TEMPLATE` /
+`HTTP_API_KEY` / `HTTP_RESPONSE_MAPPER`). `client_ip(request)` honors
+`TRUSTED_PROXY_HEADER` (default: `REMOTE_ADDR` only — proxy headers are
+spoofable unless your edge overwrites them).
+
+---
+
+### `stapel_core.django.jwt` — JWT authentication
+
+Unified JWT provider (singleton). Supports HS256 and RS256.
+
+```python
+from stapel_core.django.jwt.provider import jwt_provider
+
+access, refresh = jwt_provider.create_tokens(user)
+payload = jwt_provider.validate_token(access_token)
+```
+
+**Settings**:
+
+```python
+JWT_ALGORITHM    = 'HS256'           # or 'RS256'
+JWT_SECRET_KEY   = 'your-secret'     # HS256
+JWT_PRIVATE_KEY  = '...'             # RS256
+JWT_PUBLIC_KEY   = '...'             # RS256
+JWT_ISSUER       = 'https://yourapp.com'
+JWT_AUDIENCE     = None
+JWT_ACCESS_TOKEN_LIFETIME  = 900     # seconds
+JWT_REFRESH_TOKEN_LIFETIME = 604800  # seconds
+```
+
+---
+
+### `stapel_core.django.authentication` — JWT cookie auth
+
+`JWTCookieAuthentication` reads JWT from `access_token` cookie or
+`Authorization: Bearer <token>` header.
+
+```python
+REST_FRAMEWORK = {
+    'DEFAULT_AUTHENTICATION_CLASSES': [
+        'stapel_core.django.authentication.JWTCookieAuthentication',
+    ],
+}
+```
+
+---
+
+### `stapel_core.django.api` — DRF utilities
+
+| Symbol | Purpose |
+|---|---|
+| `StapelDataclassSerializer` | Serializer that maps `@dataclass` fields |
+| `StapelResponse(serializer)` | Wraps `.data` automatically |
+| `StapelErrorResponse(status, ERR_KEY)` | Structured error response |
+| `StapelValidationError(ERR_KEY)` | Raises DRF validation error with error key |
+| `register_service_errors(dict)` | Registers error messages for a service |
+| `AnchorPagination` / `CreatedAtAnchorPagination` | Cursor-style paginators |
+
+---
+
+### `stapel_core.bus` — Event bus
+
+Kafka-backed event bus with an in-memory backend for tests.
+
+**Publish** (sync, fire-and-forget):
+
+```python
+from stapel_core.bus import publish, Event
+
+publish('user.created', Event(
+    event_type='user.created',
+    service='auth',
+    payload={'user_id': '...'},
+))
+```
+
+**Consume** by subclassing the management-command base:
+
+```python
+from stapel_core.bus import BaseBusConsumerCommand, Event
+
+class ConsumeUsers(BaseBusConsumerCommand):
+    topics = ['user.created']
+    consumer_group = 'notifications'
+
+    def handle_event(self, event: Event) -> None:
+        ...
+```
+
+Backend is selected via the `STAPEL_BUS_BACKEND` Django setting
+(`stapel_core.bus.backends.kafka.KafkaBus` in production,
+`stapel_core.bus.backends.memory.MemoryBus` in tests).
+
+---
+
+### `stapel_core.notifications` — Push notifications
+
+```python
+from stapel_core.notifications import request_notification
+
+request_notification(
+    notification_type='welcome',
+    user_id=str(user.id),
+    email=user.email,
+    variables={'name': user.username},
+    source_service='auth',
+)
+```
+
+---
+
+### `stapel_core.oauth` — OAuth provider registry
+
+Provider classes (`GoogleProvider`, `GitHubProvider`, etc.) and registry for
+OAuth consumer flows (when your service accepts OAuth logins from external
+providers).
+
+---
+
+### `stapel_core.gdpr` — GDPR utilities
+
+Account closure requests, data export, re-registration hashes.
+
+---
+
+## Running tests
+
+```bash
+cd iron-common-python
+pip install -e '.[dev]'
+pytest stapel_core/tests/ -v
+```

stapel_core-0.3.2/__init__.py

@@ -0,0 +1,101 @@
+"""Stapel Core — shared Django utilities for the Stapel framework.
+
+The building blocks every Stapel package sits on:
+
+- ``comm`` — Action/Function inter-module communication (``emit``,
+  ``on_action``, ``call``, ``function``) plus long-running tasks
+  (``start``, ``status``, ``task_handler``). Transports are deployment
+  configuration, not code.
+- ``bus`` — transport-agnostic message bus (``publish``, ``get_bus``,
+  ``Event``) with Kafka/NATS/in-memory backends.
+- ``conf.AppSettings`` — per-app settings namespaces (the DRF
+  ``api_settings`` pattern, generalized).
+- ``signals`` — in-process Django signals for business milestones.
+- ``django.api`` — API conventions: ``StapelResponse``,
+  ``StapelErrorResponse`` and ``StapelDataclassSerializer``.
+- ``gdpr`` — GDPR provider protocol and in-process registry.
+- ``netintel`` — IP intelligence seam (``classify_ip``, ``country_of``,
+  ``IpProfile``): pluggable provider, cached, fail-open.
+- ``django.users.AbstractStapelUser`` — base user model.
+- ``core`` — framework-agnostic JWT primitives (``JWTHandler``,
+  ``TokenManager``, ``TokenBlacklist``, ``JWTConfig``).
+
+All attributes are exported lazily (PEP 562), so importing
+``stapel_core`` stays cheap and never touches Django until a
+Django-dependent attribute is actually used.
+"""
+
+from importlib import import_module
+
+try:  # single source of truth: pyproject's version via package metadata
+    from importlib.metadata import version as _pkg_version
+
+    __version__ = _pkg_version("stapel-core")
+except Exception:  # editable/vendored checkout without dist-info
+    __version__ = "0.3.0"
+
+# Attribute name -> (relative module, attribute in that module).
+# An attribute of None means the module itself is the export.
+_LAZY_EXPORTS = {
+    # comm — Actions, Functions, long-running tasks
+    "emit": (".comm", "emit"),
+    "on_action": (".comm", "on_action"),
+    "call": (".comm", "call"),
+    "function": (".comm", "function"),
+    "start": (".comm", "start"),
+    "status": (".comm", "status"),
+    "task_handler": (".comm", "task_handler"),
+    # flows — self-documenting business scenarios
+    "Flow": (".flows", "Flow"),
+    "flow_step": (".flows", "flow_step"),
+    "flow_registry": (".flows", "flow_registry"),
+    # netintel — IP classification seam (provider dotted-path, cached, fail-open)
+    "classify_ip": (".netintel", "classify_ip"),
+    "country_of": (".netintel", "country_of"),
+    "IpProfile": (".netintel", "IpProfile"),
+    # verification — step-up (OTP/TOTP/passkey) on any endpoint
+    "requires_verification": (".verification", "requires_verification"),
+    "register_factor": (".verification", "register_factor"),
+    "VerificationFactor": (".verification", "VerificationFactor"),
+    "get_user_policy": (".verification", "get_user_policy"),
+    "invalidate_policy_cache": (".verification", "invalidate_policy_cache"),
+    # bus — transport-agnostic message bus
+    "publish": (".bus", "publish"),
+    "get_bus": (".bus", "get_bus"),
+    "Event": (".bus", "Event"),
+    # conf — per-app settings namespaces
+    "AppSettings": (".conf", "AppSettings"),
+    # signals — in-process business milestones (module export)
+    "signals": (".signals", None),
+    # API conventions — responses, errors, serializers
+    "StapelResponse": (".django.api.errors", "StapelResponse"),
+    "StapelErrorResponse": (".django.api.errors", "StapelErrorResponse"),
+    "StapelDataclassSerializer": (".django.api.serializers", "StapelDataclassSerializer"),
+    # GDPR — provider protocol + in-process registry
+    "GDPRProvider": (".gdpr", "GDPRProvider"),
+    "gdpr_registry": (".gdpr", "gdpr_registry"),
+    # Users — base user model
+    "AbstractStapelUser": (".django.users.models", "AbstractStapelUser"),
+    # Framework-agnostic JWT primitives (0.1.x root exports, kept stable)
+    "JWTHandler": (".core.jwt_handler", "JWTHandler"),
+    "TokenManager": (".core.token_manager", "TokenManager"),
+    "TokenBlacklist": (".core.token_blacklist", "TokenBlacklist"),
+    "JWTConfig": (".core.config", "JWTConfig"),
+}
+
+__all__ = sorted([*_LAZY_EXPORTS, "__version__"])
+
+
+def __getattr__(name):
+    try:
+        module_path, attr = _LAZY_EXPORTS[name]
+    except KeyError:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from None
+    module = import_module(module_path, __name__)
+    value = module if attr is None else getattr(module, attr)
+    globals()[name] = value  # cache so __getattr__ runs once per name
+    return value
+
+
+def __dir__():
+    return sorted(set(globals()) | set(_LAZY_EXPORTS))