stapel-core

The Django substrate every Stapel module sits on: comm (Action/Function/Task/Projection inter-module communication over a transactional outbox), the transport-agnostic bus, AppSettings namespaces, step-up verification, self-documenting flows, i18n catalogs, the media/netintel/eventstore/captcha/secrets seams, the privilege gateway, the staff mandate, DRF API conventions (StapelResponse, error registry, permission classes, presenters) and the URL-mount + cross-service navigation registries. No HTTP surface of its own worth cataloguing and no CTO-facing feature axes — the core is what the feature modules are made of.

Part of the Stapel framework — composable Django apps that deploy as a monolith or as microservices without changing module code.

Install

pip install stapel-core

At a glance

Documentation

capabilities.json · llms.txt (for agents)

Quick start for a new Django service

Add to INSTALLED_APPS:

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):

STAPEL_CAPTCHA = {
    'BACKEND': env.str('CAPTCHA_BACKEND', 'turnstile'),
    'SECRET': env.str('CAPTCHA_SECRET', None),  # absent → disabled
}

Auto-disable: if the secret is None or empty, build_verifier returns NoopVerifier regardless of backend. No separate toggle needed.

DRF integration (add mixin to any serializer):

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:

from stapel_core.captcha import CaptchaVerifier

class MyCaptchaVerifier(CaptchaVerifier):
    def verify(self, token: str, ip: str | None = None, *, level: str | None = None) -> bool:
        return my_service.check(token, self.secret)

# settings.py
STAPEL_CAPTCHA = {'BACKEND': 'myapp.captcha.MyCaptchaVerifier', 'SECRET': 'my-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):

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.

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).

residential is a claim that requires evidence, and MaxMindProvider has exactly one source of it: the Anonymous-IP database consulted and not listing the address. Configure MAXMIND_ANONYMOUS_DB or the kind stays unknown with confidence=None — a known ASN is not evidence of a residence, and the HOSTING_ASNS fallback list can promote an address to datacenter but never demote one to residential. asn/asn_org/country still travel with an unknown profile.

System checks (W-level, never blocking): stapel_core.netintel.W001 (PROVIDER unimportable), W002 (not a NetIntelProvider), W003 (the seam is configured or depended on, but PROVIDER is still the default NullProvider, so every rule keyed on network class is dead code).

stapel_core.django.jwt — JWT authentication

Unified JWT provider (singleton). Supports HS256 and RS256.

from stapel_core.django.jwt.provider import jwt_provider

access, refresh = jwt_provider.create_tokens(user)
payload = jwt_provider.validate_token(access_token)

Settings:

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.jwt.authentication — JWT cookie auth

JWTCookieAuthentication reads JWT from access_token cookie or Authorization: Bearer <token> header.

REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': [
        'stapel_core.django.jwt.authentication.JWTCookieAuthentication',
    ],
}

stapel_core.django.api — DRF utilities

stapel_core.bus — Event bus

Transport-agnostic event bus: in-memory backend for tests/dev, Kafka, NATS JetStream, or Redis Streams for production — pick one via STAPEL_BUS_BACKEND (or bring your own BusBackend subclass).

Publish (sync, fire-and-forget):

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:

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 env var or Django setting (shorthand memory / kafka / nats / redis_streams, or any dotted path). Default is memory (stapel_core.bus.backends.memory.MemoryBus); production picks one of stapel_core.bus.backends.kafka.KafkaBus, stapel_core.bus.backends.nats.NatsJetStreamBus, or stapel_core.bus.backends.redis_streams.RedisStreamsBus (needs pip install 'stapel-core[kafka]' / [nats] / [redis-bus] respectively — see MODULE.md for connection settings and delivery semantics).

stapel_core.notifications — Push notifications

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

cd iron-common-python
pip install -e '.[dev]'
pytest stapel_core/tests/ -v

License

MIT — see LICENSE.

_{This page is assembled by stapel-readme from docs/readme.md plus the contract artifacts in docs/. Edit the prose in docs/readme.md; the badges, facts and links above and below it are generated — do not hand-edit README.md.}