hjtdev-appkit 2.0.0__py3-none-any.whl

appkit/files.py

@@ -0,0 +1,302 @@
+"""Upload validation via magic-byte sniffing, plus image validation.
+
+Public surface (docs/CONTRACT.md §2.9):
+
+    @dataclass(frozen=True)
+    class ImageInfo:
+        width: int
+        height: int
+        format: str
+
+    def detect_mimetype(data: bytes) -> str: ...
+        # puremagic stays internal — no third-party type leaks into this signature.
+
+    def validate_upload(
+        file: UploadedFile, *, allowed_mimetypes: Iterable[str], max_bytes: int = UNSET
+    ) -> None: ...
+        # raises django.core.exceptions.ValidationError; must file.seek(0) in a finally.
+        # max_bytes accepts appkit.conf.UNSET, meaning "use APPKIT['MAX_UPLOAD_BYTES']".
+
+    def validate_image(
+        file: UploadedFile,
+        *,
+        max_bytes: int = UNSET,
+        max_dimensions: tuple[int, int] | None = None,
+        allow_svg: bool = False,
+    ) -> ImageInfo: ...
+        # Requires the `images` extra (Pillow) for anything beyond header-only dimension
+        # reads. SVG is rejected unless allow_svg=True — an XML script-execution vector
+        # otherwise.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+import puremagic
+from django.core.exceptions import ValidationError
+
+from appkit.conf import UNSET, _Unset, get_setting
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    from django.core.files.uploadedfile import UploadedFile
+
+__all__ = ["ImageInfo", "detect_mimetype", "validate_image", "validate_upload"]
+
+_INSTALL_HINT_IMAGES = (
+    'Install with: uv add "hjtdev-appkit[images]" (or: pip install "hjtdev-appkit[images]")'
+)
+
+# Explicit, hardcoded extension<->mimetype agreement table — never mimetypes.guess_extension,
+# whose answer depends on the host OS's /etc/mime.types and disagrees across systems for
+# exactly the formats this module exists to check (docs/CONTRACT.md §2.9).
+_EXTENSIONS_BY_MIMETYPE: dict[str, frozenset[str]] = {
+    "image/jpeg": frozenset({".jpg", ".jpeg"}),
+    "image/png": frozenset({".png"}),
+    "image/gif": frozenset({".gif"}),
+    "image/webp": frozenset({".webp"}),
+    "image/svg+xml": frozenset({".svg"}),
+    "application/pdf": frozenset({".pdf"}),
+    "text/plain": frozenset({".txt"}),
+    "application/zip": frozenset({".zip"}),
+    "application/json": frozenset({".json"}),
+    "video/mp4": frozenset({".mp4"}),
+    "audio/mpeg": frozenset({".mp3"}),
+}
+
+_IMAGE_MIMETYPES: frozenset[str] = frozenset({"image/jpeg", "image/png", "image/gif", "image/webp"})
+_SVG_MIMETYPE = "image/svg+xml"
+
+# SVG is plain XML — puremagic's magic-byte database won't identify it, so it needs an explicit
+# check ahead of the byte-sniffing path.
+_SVG_PROLOG_RE = re.compile(rb"<\?xml\b")
+_SVG_TAG_RE = re.compile(rb"<svg\b")
+_SVG_DIMENSION_RE = re.compile(rb'(width|height)\s*=\s*["\']?\s*([0-9.]+)')
+
+
+@dataclass(frozen=True)
+class ImageInfo:
+    """Header-derived image metadata returned by `validate_image`."""
+
+    width: int
+    height: int
+    format: str
+
+
+def _looks_like_svg(data: bytes) -> bool:
+    head = data[:2048].lstrip()
+    if _SVG_PROLOG_RE.match(head):
+        return bool(_SVG_TAG_RE.search(data[:4096]))
+    return bool(_SVG_TAG_RE.match(head))
+
+
+def detect_mimetype(data: bytes) -> str:
+    """Magic-byte sniffing via `puremagic` — never the client-supplied `Content-Type` header
+    and never the filename extension, both attacker-controlled and routinely wrong.
+
+    Returns `"application/octet-stream"` for anything unrecognised rather than raising, so a
+    caller decides what "unknown" means for its own upload policy.
+    """
+    if _looks_like_svg(data):
+        return _SVG_MIMETYPE
+    try:
+        mimetype = puremagic.from_string(data, mime=True)
+    except puremagic.PureError:
+        return "application/octet-stream"
+    return mimetype or "application/octet-stream"
+
+
+def _extension_of(filename: str) -> str:
+    dot = filename.rfind(".")
+    return filename[dot:].lower() if dot != -1 else ""
+
+
+def _check_extension_agreement(filename: str, mimetype: str) -> None:
+    valid_extensions = _EXTENSIONS_BY_MIMETYPE.get(mimetype)
+    if valid_extensions is None:
+        return  # no table entry for this mimetype — nothing to cross-check against
+    if _extension_of(filename) not in valid_extensions:
+        raise ValidationError(
+            f"File extension of {filename!r} does not match its detected type {mimetype!r}.",
+            code="appkit_extension_mismatch",
+        )
+
+
+def validate_upload(
+    file: UploadedFile[bytes],
+    *,
+    allowed_mimetypes: Iterable[str],
+    max_bytes: int | _Unset = UNSET,
+) -> None:
+    """Sniffs `file`, checking size, detected mimetype, and extension/mimetype agreement.
+
+    `max_bytes=UNSET` resolves to `APPKIT["MAX_UPLOAD_BYTES"]` — a semantic/business-rule
+    limit ("reject a 50 MB avatar"), not a DoS control; Django's own
+    `DATA_UPLOAD_MAX_MEMORY_SIZE`/`FILE_UPLOAD_MAX_MEMORY_SIZE` are the actual memory/disk
+    boundary, already enforced before this function ever runs.
+
+    Raises `django.core.exceptions.ValidationError` naming which check failed.
+
+    **The single most important line in this module:** sniffing consumes the file's read
+    position, so `file.seek(0)` runs in a `finally` regardless of outcome — without it,
+    whatever saves the file afterward (a serializer's `.save()`) would write a
+    truncated-to-empty file.
+    """
+    limit = get_setting("MAX_UPLOAD_BYTES") if isinstance(max_bytes, _Unset) else max_bytes
+    allowed = frozenset(allowed_mimetypes)
+    try:
+        file.seek(0)
+        size = getattr(file, "size", None)
+        if size is not None and size > limit:
+            raise ValidationError(
+                f"File is too large: {size} bytes exceeds the {limit} byte limit.",
+                code="appkit_file_too_large",
+            )
+
+        head = file.read(4096)
+        mimetype = detect_mimetype(head)
+        if mimetype not in allowed:
+            raise ValidationError(
+                f"File type {mimetype!r} is not an allowed upload type.",
+                code="appkit_mimetype_not_allowed",
+            )
+
+        _check_extension_agreement(getattr(file, "name", "") or "", mimetype)
+    finally:
+        file.seek(0)
+
+
+def _pil_image_module() -> Any:
+    """Lazily imports `PIL.Image`, behind the `images` extra.
+
+    A missing extra must fail with an actionable message, never a bare `ImportError` — this
+    path is unit-tested by simulating the import failure.
+    """
+    try:
+        from PIL import Image
+    except ImportError as exc:
+        raise ImportError(
+            "appkit.files.validate_image requires the 'Pillow' package for image dimension "
+            f"reading. {_INSTALL_HINT_IMAGES}"
+        ) from exc
+    return Image
+
+
+def _svg_image_info(
+    file: UploadedFile[bytes], *, max_dimensions: tuple[int, int] | None
+) -> ImageInfo:
+    """Reads `width`/`height` attributes off the SVG root element via a bounded regex scan —
+    never touches Pillow, which doesn't support SVG at all.
+
+    Neither attribute is guaranteed to be present on a valid SVG (viewBox-only documents are
+    legal); both default to `0` when absent or non-numeric, and `max_dimensions` is skipped
+    when either dimension is unknown rather than comparing against a meaningless `0`.
+    """
+    file.seek(0)
+    head = file.read(4096)
+    dimensions: dict[str, int] = {}
+    for match in _SVG_DIMENSION_RE.finditer(head):
+        key = match.group(1).decode()
+        try:
+            dimensions[key] = int(float(match.group(2)))
+        except ValueError:
+            continue
+
+    width = dimensions.get("width", 0)
+    height = dimensions.get("height", 0)
+    if max_dimensions is not None and width and height:
+        max_width, max_height = max_dimensions
+        if width > max_width or height > max_height:
+            raise ValidationError(
+                f"Image dimensions {width}x{height} exceed the maximum {max_width}x{max_height}.",
+                code="appkit_dimensions_too_large",
+            )
+    return ImageInfo(width=width, height=height, format="svg")
+
+
+def validate_image(
+    file: UploadedFile[bytes],
+    *,
+    max_bytes: int | _Unset = UNSET,
+    max_dimensions: tuple[int, int] | None = None,
+    allow_svg: bool = False,
+) -> ImageInfo:
+    """Everything `validate_upload` does, restricted to image mimetypes, plus a
+    decompression-bomb-aware dimension check.
+
+    **SVG is rejected unless `allow_svg=True`** — SVG is XML, and XML is a script-execution
+    vector (embedded `<script>`, external entity references) that magic-byte sniffing alone
+    happily approves as "a valid file of the claimed type." When allowed, SVG dimensions are
+    read without ever touching Pillow (see `_svg_image_info`).
+
+    For raster formats, **Pillow is the header reader**: `PIL.Image.open()` is lazy and yields
+    `.size`/`.format` from the header without decoding pixel data — this *is* the
+    decompression-bomb-safe read, and it requires the `images` extra. Missing the extra raises
+    the same actionable `ImportError` pattern as `appkit.crypto`.
+
+    `seek(0)` runs in a `finally`, same as `validate_upload`, for the same corruption reason.
+
+    Raises `django.core.exceptions.ValidationError` naming which check failed; `ImportError` if
+    the `images` extra is needed and absent.
+    """
+    limit = get_setting("MAX_UPLOAD_BYTES") if isinstance(max_bytes, _Unset) else max_bytes
+    allowed = set(_IMAGE_MIMETYPES)
+    if allow_svg:
+        allowed.add(_SVG_MIMETYPE)
+
+    try:
+        file.seek(0)
+        size = getattr(file, "size", None)
+        if size is not None and size > limit:
+            raise ValidationError(
+                f"File is too large: {size} bytes exceeds the {limit} byte limit.",
+                code="appkit_file_too_large",
+            )
+
+        head = file.read(4096)
+        mimetype = detect_mimetype(head)
+
+        if mimetype == _SVG_MIMETYPE:
+            if not allow_svg:
+                raise ValidationError(
+                    "SVG uploads are rejected by default (XML is a script-execution vector). "
+                    "Pass allow_svg=True to accept them.",
+                    code="appkit_svg_not_allowed",
+                )
+            return _svg_image_info(file, max_dimensions=max_dimensions)
+
+        if mimetype not in allowed:
+            raise ValidationError(
+                f"File type {mimetype!r} is not a supported image type.",
+                code="appkit_mimetype_not_allowed",
+            )
+
+        _check_extension_agreement(getattr(file, "name", "") or "", mimetype)
+
+        image_module = _pil_image_module()
+        file.seek(0)
+        try:
+            with image_module.open(file) as img:
+                width, height = img.size
+                image_format = (img.format or "").lower()
+        except image_module.UnidentifiedImageError as exc:
+            raise ValidationError(
+                f"Could not read image data: {exc}", code="appkit_unreadable_image"
+            ) from exc
+
+        if max_dimensions is not None:
+            max_width, max_height = max_dimensions
+            if width > max_width or height > max_height:
+                raise ValidationError(
+                    f"Image dimensions {width}x{height} exceed the maximum "
+                    f"{max_width}x{max_height}.",
+                    code="appkit_dimensions_too_large",
+                )
+
+        return ImageInfo(width=width, height=height, format=image_format)
+    finally:
+        file.seek(0)

appkit/locale/fa/LC_MESSAGES/django.po

@@ -0,0 +1,29 @@
+# Persian (fa) translation catalogue for appkit.
+# Copyright (C) 2026 Mohammad Hojjat Nikoobakht
+# This file is distributed under the same license as the appkit package (MIT).
+#
+msgid ""
+msgstr ""
+"Project-Id-Version: appkit 1.0.0\n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-08-26 00:22+0330\n"
+"PO-Revision-Date: 2026-08-26 00:22+0330\n"
+"Last-Translator: Mohammad Hojjat Nikoobakht\n"
+"Language-Team: Persian\n"
+"Language: fa\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Plural-Forms: nplurals=2; plural=(n > 1);\n"
+
+msgid "App Kit"
+msgstr "اپ‌کیت"
+
+msgid "Validation failed."
+msgstr "اعتبارسنجی ناموفق بود."
+
+msgid "Request failed."
+msgstr "درخواست ناموفق بود."
+
+msgid "Internal server error."
+msgstr "خطای داخلی سرور."

appkit/media.py

@@ -0,0 +1,102 @@
+"""File-location/URL formatting — absolutizing media URLs.
+
+Kept as a separate module from ``appkit.net`` despite both starting life as "URL-ish"
+(docs/CONTRACT.md §2 preamble). This is where the media-URL helper lives precisely *because*
+appkit ships no ``urlpatterns`` — see docs/CONTRACT.md §10; there is no ``appkit.urls``.
+
+Public surface (docs/CONTRACT.md §2.11):
+
+    def file_url(
+        value: FieldFile | str | None, *, request: HttpRequest | Request | None = None
+    ) -> str | None: ...
+
+    def absolute_url(
+        url: str | None, *, request: HttpRequest | Request | None = None
+    ) -> str | None: ...
+
+Both raise ImproperlyConfigured only when ``request is None`` AND ``APPKIT['SITE_URL']`` is
+unset — a host that never renders a media URL outside an active request cycle never needs
+SITE_URL at all.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+from urllib.parse import urlparse
+
+from django.core.exceptions import ImproperlyConfigured
+
+from appkit.conf import get_setting
+
+if TYPE_CHECKING:
+    from django.db.models.fields.files import FieldFile
+    from django.http import HttpRequest
+    from rest_framework.request import Request
+
+__all__ = ["absolute_url", "file_url"]
+
+
+def _is_absolute(url: str) -> bool:
+    parsed = urlparse(url)
+    return bool(parsed.scheme and parsed.netloc)
+
+
+def file_url(
+    value: FieldFile | str | None, *, request: HttpRequest | Request | None = None
+) -> str | None:
+    """Absolutizes a `FieldFile`/URL string, or `None` for an unset value.
+
+    `None` and an empty `FieldFile` (Django's own `FieldFile.url` raises `ValueError` on an
+    empty field — absorbed here) both return `None`, so a serializer calling this on every
+    optional `ImageField`/`FileField` doesn't need to guard the field itself. Never raises on
+    that path; see `absolute_url` for the one path that does.
+    """
+    if value is None:
+        return None
+    if isinstance(value, str):
+        if not value:
+            return None
+        return absolute_url(value, request=request)
+
+    try:
+        url = value.url
+    except ValueError:
+        return None
+    return absolute_url(url, request=request)
+
+
+def absolute_url(url: str | None, *, request: HttpRequest | Request | None = None) -> str | None:
+    """Absolutizes `url` against `request` (or `APPKIT["SITE_URL"]` when there is none).
+
+    `None`/`""` return `None`. An already-absolute URL (a non-empty `scheme` and `netloc`,
+    e.g. an S3/CDN-backed `FieldFile`, or an off-host `MEDIA_URL`) passes through unchanged —
+    never double-prefixed.
+
+    With `request`, uses `request.build_absolute_uri(...)`, which already respects Django's
+    `SECURE_PROXY_SSL_HEADER` handling — correct in dev, staging, and prod (behind
+    `--proxy-headers`) with zero extra configuration. Without `request` (a Celery task, a
+    management command, an email template), falls back to `APPKIT["SITE_URL"]`.
+
+    Raises:
+        ImproperlyConfigured: only when `request is None` **and** `APPKIT["SITE_URL"]` is
+            unset (the default, `""`) — naming `APPKIT["SITE_URL"]` as the fix. Silently
+            returning a relative URL in that case is exactly how a broken image link ends up in
+            a Celery-rendered email nobody notices until a customer complains.
+    """
+    if not url:
+        return None
+    if _is_absolute(url):
+        return url
+
+    if request is not None:
+        return request.build_absolute_uri(url)
+
+    site_url = get_setting("SITE_URL")
+    if not site_url:
+        raise ImproperlyConfigured(
+            "appkit.media needs APPKIT['SITE_URL'] set to absolutize a URL with no request in "
+            "scope (e.g. from a Celery task or management command). Add APPKIT['SITE_URL'] to "
+            "your settings, or call this with a request when one is available."
+        )
+    path = url if url.startswith("/") else f"/{url}"
+    return f"{site_url.rstrip('/')}{path}"

appkit/mixins.py

@@ -0,0 +1,68 @@
+"""DRF list-view response caching mixin.
+
+Public surface (docs/CONTRACT.md §2.2), implemented in a later phase:
+
+    class CachedListMixin:
+        cache_namespace: str    # REQUIRED — no default. Raises ImproperlyConfigured at first
+                                 # list() call if empty.
+        cache_timeout: int = UNSET   # appkit.conf.UNSET — falls back to APPKIT['CACHE_TIMEOUT']
+
+        def list(self, request, *args, **kwargs) -> Response: ...
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from django.core.exceptions import ImproperlyConfigured
+from rest_framework.response import Response
+
+from appkit.cache import _user_cache_token, build_cache_key, cached_call
+from appkit.conf import UNSET, _Unset
+
+__all__ = ["CachedListMixin"]
+
+
+class CachedListMixin:
+    """Caches a `ListAPIView`'s serialized data per user and querystring.
+
+    Set `cache_namespace` (required — no default) and optionally `cache_timeout` (seconds,
+    falls back to `APPKIT["CACHE_TIMEOUT"]` when left `UNSET`) on the view. Caches
+    `response.data`, not the `Response` object itself: a DRF `Response` carries
+    renderer/request state that isn't meant to be pickled into a cache backend, where a plain
+    list of serialized dicts is.
+
+    **`cache_namespace` has no class-name-derived fallback**, unlike the scaffold this is
+    ported from — two apps each shipping a `NotificationListView` would collide in the host's
+    one shared Redis instance, precisely the collision `APP-DESIGN.md` §1.3 exists to prevent.
+    Raises `ImproperlyConfigured` at first `list()` call if left empty.
+
+    Usage: `class MyListView(CachedListMixin, generics.ListAPIView): ...` — the mixin must
+    precede the generic view in the MRO so it wraps `list()`.
+    """
+
+    cache_namespace: str = ""  # REQUIRED — no default; empty raises at first list() call
+    cache_timeout: int | _Unset = UNSET
+
+    def _cache_key(self, request: Any) -> str:
+        if not self.cache_namespace:
+            raise ImproperlyConfigured(
+                f"{type(self).__name__}.cache_namespace is required and must be non-empty — "
+                "an unprefixed cache key is exactly the two-apps-collide scenario "
+                "APP-DESIGN.md §1.3 exists to prevent."
+            )
+        return build_cache_key(
+            self.cache_namespace,
+            _user_cache_token(request, per_user=True),
+            request.get_full_path(),
+        )
+
+    def list(self, request: Any, *args: Any, **kwargs: Any) -> Response:
+        def build() -> Any:
+            # This mixin is only ever combined with generics.ListAPIView (see the class
+            # docstring), which is where `list()` actually comes from — mypy can't see that
+            # from this class's own bases, since a plain mixin has none.
+            return super(CachedListMixin, self).list(request, *args, **kwargs).data  # type: ignore[misc]
+
+        data = cached_call(self._cache_key(request), self.cache_timeout, build)
+        return Response(data)

appkit/money.py

@@ -0,0 +1,69 @@
+"""Integer money parsing/formatting with fixed ASCII grouping.
+
+Flagged in docs/CONTRACT.md §11 as the contract's second-weakest module — deliberately thin
+(a handful of pure functions, zero dependencies) rather than grown into a currency/locale
+framework.
+
+Public surface (docs/CONTRACT.md §2.14):
+
+    def parse_amount(value: str | int) -> int: ...
+        # Rejects float outright, raising TypeError. Raises ValueError for non-integer
+        # strings. Strips , and ٬ thousands separators.
+
+    def format_amount(value: int, *, currency: str = "") -> str: ...
+        # Fixed ASCII "," thousands separator regardless of locale — the frontend half
+        # deliberately avoids Intl.NumberFormat for the same reason (its grouping character is
+        # locale-dependent). See tests/fixtures/money-vectors.json.
+"""
+
+from __future__ import annotations
+
+from appkit.text import to_english_digits
+
+__all__ = ["format_amount", "parse_amount"]
+
+_THOUSANDS_SEPARATORS = (",", "٬")
+
+
+def parse_amount(value: str | int) -> int:
+    """Parses a digit string or `int` into an `int` amount.
+
+    Accepts Persian/Arabic-Indic digits (normalised via `to_english_digits` first) and strips
+    thousands separators (`,`/`٬`) before parsing.
+
+    Raises:
+        TypeError: for a `float` (binary floating point can't represent most decimal currency
+            amounts exactly, so a float here is a defect in the caller, never a valid input
+            format this function should paper over) — and for a `bool`, which is an `int`
+            subclass in Python but is never a legitimate money amount (docs/CONTRACT.md §2.14
+            doesn't name `bool` explicitly; excluding it is the safer reading, since silently
+            accepting `True`/`False` as `1`/`0` would be a confusing surprise for any caller
+            that passes a boolean by mistake).
+        ValueError: for a string that isn't a valid integer after normalisation (letters,
+            multiple separators/decimal points, an empty string).
+    """
+    if isinstance(value, bool) or isinstance(value, float):
+        raise TypeError(
+            f"parse_amount() does not accept {type(value).__name__}; pass an int or a digit string."
+        )
+    if isinstance(value, int):
+        return value
+
+    normalized = to_english_digits(value)
+    for sep in _THOUSANDS_SEPARATORS:
+        normalized = normalized.replace(sep, "")
+    normalized = normalized.strip()
+    if not normalized or not normalized.lstrip("+-").isdigit():
+        raise ValueError(f"parse_amount() received a non-integer string: {value!r}")
+    return int(normalized)
+
+
+def format_amount(value: int, *, currency: str = "") -> str:
+    """Thousands-grouped string using a fixed ASCII `,` separator, regardless of locale.
+
+    `1000000` -> `"1,000,000"`, or `"1,000,000 IRT"` with `currency="IRT"`. Never raises for
+    any `int` input, including `0` and negative values (`-500` -> `"-500"`). Emits Latin digits
+    only — `to_persian_digits` is a caller's separate, explicit choice on the result.
+    """
+    formatted = f"{value:,}"
+    return f"{formatted} {currency}" if currency else formatted

appkit/net.py

@@ -0,0 +1,115 @@
+"""Trust-boundary parsing of proxy headers to resolve the real client IP.
+
+Public surface (docs/CONTRACT.md §2.10) — the module's only export:
+
+    def client_ip(request: HttpRequest | Request) -> str: ...
+        # Never raises. Uses APPKIT['TRUSTED_PROXY_COUNT'] to read X-Forwarded-For from the
+        # right (parts[-N]) — trusts only the proxy-appended entry, never the
+        # client-controlled leftmost value.
+
+**Why from the right, not `REMOTE_ADDR`:** verified directly against the installed
+`uvicorn` proxy-headers middleware, not assumed — with the base scaffold's documented prod
+command (`--proxy-headers --forwarded-allow-ips "*"`), uvicorn writes the *leftmost*
+(client-controlled) `X-Forwarded-For` entry into `scope["client"]`, i.e. into Django's own
+`request.META["REMOTE_ADDR"]`. `REMOTE_ADDR` is therefore spoofable end-to-end in that exact
+deployment, and this module never reads it for the answer — only as the degraded fallback when
+the header itself can't be trusted. nginx's `$proxy_add_x_forwarded_for` *appends* its own peer
+address to whatever it received, so with `N` trusted proxies in front, the real client is
+`parts[-N]`.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import logging
+from typing import TYPE_CHECKING
+
+from appkit.conf import get_setting
+
+if TYPE_CHECKING:
+    from django.http import HttpRequest
+    from rest_framework.request import Request
+
+__all__ = ["client_ip"]
+
+logger = logging.getLogger(__name__)
+
+
+def _normalize_candidate(raw: str) -> str | None:
+    """Validates a single `X-Forwarded-For` entry, stripping brackets/port where present.
+
+    Returns `None` for anything that isn't a valid IPv4/IPv6 address once normalised.
+    """
+    raw = raw.strip()
+    if not raw:
+        return None
+
+    if raw.startswith("["):
+        # IPv6 in bracket notation, optionally with a port: "[2001:db8::1]:443" or "[2001:db8::1]".
+        end = raw.find("]")
+        if end == -1:
+            return None
+        host = raw[1:end]
+    elif raw.count(":") == 1:
+        # Exactly one colon means "host:port" (IPv4) — a bare IPv6 address always has more than
+        # one colon (or the "::" shorthand), so this never misfires on an unbracketed IPv6
+        # literal.
+        host = raw.split(":", 1)[0]
+    else:
+        host = raw
+
+    try:
+        ipaddress.ip_address(host)
+    except ValueError:
+        return None
+    return host
+
+
+def client_ip(request: HttpRequest | Request) -> str:
+    """Resolves the real client IP, trusting only the proxy-appended `X-Forwarded-For` entry.
+
+    Reads `APPKIT["TRUSTED_PROXY_COUNT"]` (default `1`) trusted hops and returns the entry
+    `TRUSTED_PROXY_COUNT`-th from the **right** of the header — never the leftmost, which a
+    client can set (and pre-pend fake hops to) themselves. Never raises: an absent/empty
+    header, a header with fewer entries than `TRUSTED_PROXY_COUNT`, a malformed candidate, or a
+    non-positive `TRUSTED_PROXY_COUNT` (which would otherwise resolve `parts[-0] == parts[0]`,
+    the spoofable leftmost entry) all fall back to the connection's own remote address, with a
+    logged warning — degrading to "best available answer" rather than crashing the request.
+    """
+    trusted_proxy_count = get_setting("TRUSTED_PROXY_COUNT")
+    fallback = request.META.get("REMOTE_ADDR", "") or ""
+
+    header = request.META.get("HTTP_X_FORWARDED_FOR", "")
+    if not header or not header.strip():
+        return fallback
+
+    parts = [part.strip() for part in header.split(",")]
+
+    if trusted_proxy_count <= 0:
+        logger.warning(
+            "client_ip(): TRUSTED_PROXY_COUNT is not positive (%r); falling back to the "
+            "direct connection address.",
+            trusted_proxy_count,
+        )
+        return fallback
+
+    if len(parts) < trusted_proxy_count:
+        logger.warning(
+            "client_ip(): X-Forwarded-For has fewer entries (%d) than TRUSTED_PROXY_COUNT "
+            "(%d); falling back to the direct connection address.",
+            len(parts),
+            trusted_proxy_count,
+        )
+        return fallback
+
+    candidate = parts[-trusted_proxy_count]
+    normalized = _normalize_candidate(candidate)
+    if normalized is None:
+        logger.warning(
+            "client_ip(): X-Forwarded-For candidate %r is not a valid IP address; falling "
+            "back to the direct connection address.",
+            candidate,
+        )
+        return fallback
+
+    return normalized