django-admin-react 0.1.0a1__tar.gz

django_admin_react-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Martín Castro Álvarez and django-admin-react contributors
+
+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.

django_admin_react-0.1.0a1/PKG-INFO

@@ -0,0 +1,237 @@
+Metadata-Version: 2.3
+Name: django-admin-react
+Version: 0.1.0a1
+Summary: A drop-in React single-page admin for Django, driven entirely by ModelAdmin.
+License: MIT
+Keywords: django,admin,react,spa,tailwind
+Author: django-admin-react contributors
+Requires-Python: >=3.10,<4.0
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Framework :: Django :: 5.2
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Site Management
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: django (>=5.0,<6.0)
+Project-URL: Documentation, https://github.com/MartinCastroAlvarez/django-admin-react#readme
+Project-URL: Homepage, https://github.com/MartinCastroAlvarez/django-admin-react
+Project-URL: Repository, https://github.com/MartinCastroAlvarez/django-admin-react
+Description-Content-Type: text/markdown
+
+# django-admin-react
+
+A drop-in **React single-page admin** for any Django 5+ project. Same
+`pip install`, same `INSTALLED_APPS`, same `urls.py include()` — and
+your `ModelAdmin` classes drive everything. No React code on your side.
+
+> **Pre-alpha.** Not yet on PyPI. Install from source today (see below);
+> a `pip install django-admin-react` release will follow. Track progress
+> in [`PROGRESS.md`](PROGRESS.md).
+
+---
+
+## Install in your Django project
+
+### Option A — once on PyPI (planned)
+
+```bash
+pip install django-admin-react
+```
+
+```python
+# settings.py
+INSTALLED_APPS = [
+    "django.contrib.admin",
+    "django.contrib.auth",
+    "django.contrib.contenttypes",
+    "django.contrib.sessions",
+    "django.contrib.messages",
+    "django.contrib.staticfiles",
+    "django_admin_react",   # ← add this
+    # ... your own apps
+]
+```
+
+```python
+# urls.py
+from django.urls import include, path
+
+urlpatterns = [
+    path("admin/", include("django_admin_react.urls")),
+    # any prefix is fine:
+    # path("admin-react/", include("django_admin_react.urls")),
+    # path("staff/",       include("django_admin_react.urls")),
+]
+```
+
+That is the entire integration. Log in as a staff user → modern,
+Tailwind-styled SPA driven by your existing `ModelAdmin` classes.
+
+The wheel ships the **pre-built React bundle**. You do **not** need
+Node, pnpm, or any frontend toolchain to install or run.
+
+### Option B — install from source (today)
+
+```bash
+git clone https://github.com/MartinCastroAlvarez/django-admin-react.git
+cd django-admin-react
+./scripts/build.sh              # builds the SPA + Python wheel
+pip install dist/*.whl          # install into your venv
+```
+
+Then wire it into your project as in Option A.
+
+### Optional configuration
+
+All settings are optional. Defaults shown:
+
+```python
+DJANGO_ADMIN_REACT = {
+    "ADMIN_SITE": "django.contrib.admin.site",   # dotted path
+    "DEFAULT_PAGE_SIZE": 25,
+    "MAX_PAGE_SIZE": 200,
+    "ENABLE_PROFILING": False,
+}
+```
+
+---
+
+## Extend without writing React
+
+Just edit your `ModelAdmin` — the UI follows. No JS required.
+
+```python
+# yourapp/admin.py
+from django.contrib import admin
+from .models import Invoice
+
+@admin.register(Invoice)
+class InvoiceAdmin(admin.ModelAdmin):
+    list_display = ("number", "customer", "total", "issued_at")
+    search_fields = ("number", "customer__name")
+    readonly_fields = ("total",)            # ← UI hides the input
+    list_filter = ("status",)               # ← UI surfaces the filter
+
+    def has_add_permission(self, request):
+        return request.user.has_perm("billing.create_invoice")
+        #                                                     ↑
+        # UI hides the Add button automatically when this returns False.
+```
+
+Permissions, querysets, search, validation — all your `ModelAdmin`'s
+answers, surfaced verbatim in the React UI. The package never invents
+its own permission model.
+
+---
+
+## Screenshots
+
+> **Captured live** with `scripts/screenshots.sh` from
+> `examples/project/` — real pixels, not mockups. The React SPA
+> shell lands in PR #6 / #7; until then, the images below show the
+> **legacy HTML admin** running against the example apps — i.e.,
+> the experience `django-admin-react` modernises. Once the SPA
+> renders, this section regenerates from the same script. Tracked
+> in [`PROGRESS.md`](PROGRESS.md).
+
+| Login (the entry door)                            | Admin index (legacy)                                    |
+| ------------------------------------------------- | ------------------------------------------------------- |
+| ![Login](docs/screenshots/01-admin-login.png)     | ![Admin index](docs/screenshots/02-admin-index.png)     |
+
+| Library / Authors — list view                                  | Library / Author — detail view                                  |
+| -------------------------------------------------------------- | --------------------------------------------------------------- |
+| ![Author list](docs/screenshots/03-admin-library-list.png)     | ![Author detail](docs/screenshots/05-admin-library-detail.png)  |
+
+| Mobile (375 px)                                                       | API: `GET /api/v1/registry/` JSON                       |
+| --------------------------------------------------------------------- | ------------------------------------------------------- |
+| ![Mobile list](docs/screenshots/04-admin-library-list-mobile.png)     | ![Registry JSON](docs/screenshots/06-registry-api-json.png) |
+
+Every screenshot uses a deterministic synthetic seed (no real
+people, accounts, or PII). Regenerate with:
+
+```bash
+bash scripts/screenshots.sh
+```
+
+The script boots a one-off SQLite DB, seeds fixtures, captures via
+Playwright (Chromium), and writes the six PNGs above.
+
+---
+
+## What you get
+
+- **Plug-and-play**: works with any `ModelAdmin` you already have.
+- **Shared auth**: Django sessions, CSRF, staff permissions. No new
+  user model, no parallel permission system.
+- **Responsive, modern UI**: React + Tailwind + React Query, served
+  as a single bundle from `django_admin_react/static/admin_react/`.
+- **Extensible by editing `ModelAdmin`**, not React.
+- **Configurable URL prefix** — `/admin/`, `/admin-react/`, anywhere.
+- **Conservative & secure-by-default** — never exposes models the
+  admin doesn't already expose; never writes fields the admin form
+  excludes; CSRF on every unsafe method.
+- **Boring + auditable** — no parallel permission system, no
+  client-side workarounds for backend permissions, conservative
+  serializer with `str()` fallback.
+
+---
+
+## Documentation map
+
+| Doc                                                             | Topic                                       |
+| ---------------------------------------------------------------- | -------------------------------------------- |
+| [`PROGRESS.md`](PROGRESS.md)                                     | Live status of merged PRs / what's coming   |
+| [`ARCHITECTURE.md`](ARCHITECTURE.md)                             | Design contract                              |
+| [`PLAN.md`](PLAN.md)                                             | v1 scope, PR sequence, risks                 |
+| [`SECURITY.md`](SECURITY.md)                                     | Threat model, guarantees, required tests     |
+| [`CONTRIBUTING.md`](CONTRIBUTING.md)                             | Dev workflow                                 |
+| [`CLAUDE.md`](CLAUDE.md)                                         | Rules for AI contributors                    |
+| [`docs/api-contract.md`](docs/api-contract.md)                   | Full API spec                                |
+| [`docs/data-layer.md`](docs/data-layer.md)                       | `@dar/data` design (SWR + debounce)          |
+| [`docs/agents/pr-workflow.md`](docs/agents/pr-workflow.md)       | How agents send / review / merge PRs         |
+| [`docs/agents/autonomy-policy.md`](docs/agents/autonomy-policy.md) | What's auto-mergeable vs human-only        |
+| [`docs/agents/decisions.md`](docs/agents/decisions.md)           | Decisions log                                |
+| [`scripts/README.md`](scripts/README.md)                         | `lint.sh` / `build.sh` / `deploy.sh`         |
+| [`examples/README.md`](examples/README.md)                       | Demo Django apps                             |
+
+---
+
+## Developer scripts
+
+```bash
+./scripts/lint.sh        # ruff + black + isort + flake8 + pylint + mypy + bandit + prettier + tsc
+./scripts/build.sh       # pnpm install + vite build + poetry build (wheel ships pre-built SPA)
+./scripts/deploy.sh      # poetry publish to PyPI (requires POETRY_PYPI_TOKEN_PYPI)
+```
+
+The Merger runs `./scripts/lint.sh` before every merge — there is
+no CI in this repo by design.
+
+---
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).
+
+## Security
+
+Please report security issues privately. See
+[`SECURITY.md`](SECURITY.md) §4. Do **not** open a public issue.
+
+## Contributing
+
+Humans and AI agents both welcome. Start with
+[`CONTRIBUTING.md`](CONTRIBUTING.md). AI agents must also read
+[`CLAUDE.md`](CLAUDE.md), [`docs/agents/pr-workflow.md`](docs/agents/pr-workflow.md),
+and [`docs/agents/autonomy-policy.md`](docs/agents/autonomy-policy.md).
+

django_admin_react-0.1.0a1/README.md

@@ -0,0 +1,206 @@
+# django-admin-react
+
+A drop-in **React single-page admin** for any Django 5+ project. Same
+`pip install`, same `INSTALLED_APPS`, same `urls.py include()` — and
+your `ModelAdmin` classes drive everything. No React code on your side.
+
+> **Pre-alpha.** Not yet on PyPI. Install from source today (see below);
+> a `pip install django-admin-react` release will follow. Track progress
+> in [`PROGRESS.md`](PROGRESS.md).
+
+---
+
+## Install in your Django project
+
+### Option A — once on PyPI (planned)
+
+```bash
+pip install django-admin-react
+```
+
+```python
+# settings.py
+INSTALLED_APPS = [
+    "django.contrib.admin",
+    "django.contrib.auth",
+    "django.contrib.contenttypes",
+    "django.contrib.sessions",
+    "django.contrib.messages",
+    "django.contrib.staticfiles",
+    "django_admin_react",   # ← add this
+    # ... your own apps
+]
+```
+
+```python
+# urls.py
+from django.urls import include, path
+
+urlpatterns = [
+    path("admin/", include("django_admin_react.urls")),
+    # any prefix is fine:
+    # path("admin-react/", include("django_admin_react.urls")),
+    # path("staff/",       include("django_admin_react.urls")),
+]
+```
+
+That is the entire integration. Log in as a staff user → modern,
+Tailwind-styled SPA driven by your existing `ModelAdmin` classes.
+
+The wheel ships the **pre-built React bundle**. You do **not** need
+Node, pnpm, or any frontend toolchain to install or run.
+
+### Option B — install from source (today)
+
+```bash
+git clone https://github.com/MartinCastroAlvarez/django-admin-react.git
+cd django-admin-react
+./scripts/build.sh              # builds the SPA + Python wheel
+pip install dist/*.whl          # install into your venv
+```
+
+Then wire it into your project as in Option A.
+
+### Optional configuration
+
+All settings are optional. Defaults shown:
+
+```python
+DJANGO_ADMIN_REACT = {
+    "ADMIN_SITE": "django.contrib.admin.site",   # dotted path
+    "DEFAULT_PAGE_SIZE": 25,
+    "MAX_PAGE_SIZE": 200,
+    "ENABLE_PROFILING": False,
+}
+```
+
+---
+
+## Extend without writing React
+
+Just edit your `ModelAdmin` — the UI follows. No JS required.
+
+```python
+# yourapp/admin.py
+from django.contrib import admin
+from .models import Invoice
+
+@admin.register(Invoice)
+class InvoiceAdmin(admin.ModelAdmin):
+    list_display = ("number", "customer", "total", "issued_at")
+    search_fields = ("number", "customer__name")
+    readonly_fields = ("total",)            # ← UI hides the input
+    list_filter = ("status",)               # ← UI surfaces the filter
+
+    def has_add_permission(self, request):
+        return request.user.has_perm("billing.create_invoice")
+        #                                                     ↑
+        # UI hides the Add button automatically when this returns False.
+```
+
+Permissions, querysets, search, validation — all your `ModelAdmin`'s
+answers, surfaced verbatim in the React UI. The package never invents
+its own permission model.
+
+---
+
+## Screenshots
+
+> **Captured live** with `scripts/screenshots.sh` from
+> `examples/project/` — real pixels, not mockups. The React SPA
+> shell lands in PR #6 / #7; until then, the images below show the
+> **legacy HTML admin** running against the example apps — i.e.,
+> the experience `django-admin-react` modernises. Once the SPA
+> renders, this section regenerates from the same script. Tracked
+> in [`PROGRESS.md`](PROGRESS.md).
+
+| Login (the entry door)                            | Admin index (legacy)                                    |
+| ------------------------------------------------- | ------------------------------------------------------- |
+| ![Login](docs/screenshots/01-admin-login.png)     | ![Admin index](docs/screenshots/02-admin-index.png)     |
+
+| Library / Authors — list view                                  | Library / Author — detail view                                  |
+| -------------------------------------------------------------- | --------------------------------------------------------------- |
+| ![Author list](docs/screenshots/03-admin-library-list.png)     | ![Author detail](docs/screenshots/05-admin-library-detail.png)  |
+
+| Mobile (375 px)                                                       | API: `GET /api/v1/registry/` JSON                       |
+| --------------------------------------------------------------------- | ------------------------------------------------------- |
+| ![Mobile list](docs/screenshots/04-admin-library-list-mobile.png)     | ![Registry JSON](docs/screenshots/06-registry-api-json.png) |
+
+Every screenshot uses a deterministic synthetic seed (no real
+people, accounts, or PII). Regenerate with:
+
+```bash
+bash scripts/screenshots.sh
+```
+
+The script boots a one-off SQLite DB, seeds fixtures, captures via
+Playwright (Chromium), and writes the six PNGs above.
+
+---
+
+## What you get
+
+- **Plug-and-play**: works with any `ModelAdmin` you already have.
+- **Shared auth**: Django sessions, CSRF, staff permissions. No new
+  user model, no parallel permission system.
+- **Responsive, modern UI**: React + Tailwind + React Query, served
+  as a single bundle from `django_admin_react/static/admin_react/`.
+- **Extensible by editing `ModelAdmin`**, not React.
+- **Configurable URL prefix** — `/admin/`, `/admin-react/`, anywhere.
+- **Conservative & secure-by-default** — never exposes models the
+  admin doesn't already expose; never writes fields the admin form
+  excludes; CSRF on every unsafe method.
+- **Boring + auditable** — no parallel permission system, no
+  client-side workarounds for backend permissions, conservative
+  serializer with `str()` fallback.
+
+---
+
+## Documentation map
+
+| Doc                                                             | Topic                                       |
+| ---------------------------------------------------------------- | -------------------------------------------- |
+| [`PROGRESS.md`](PROGRESS.md)                                     | Live status of merged PRs / what's coming   |
+| [`ARCHITECTURE.md`](ARCHITECTURE.md)                             | Design contract                              |
+| [`PLAN.md`](PLAN.md)                                             | v1 scope, PR sequence, risks                 |
+| [`SECURITY.md`](SECURITY.md)                                     | Threat model, guarantees, required tests     |
+| [`CONTRIBUTING.md`](CONTRIBUTING.md)                             | Dev workflow                                 |
+| [`CLAUDE.md`](CLAUDE.md)                                         | Rules for AI contributors                    |
+| [`docs/api-contract.md`](docs/api-contract.md)                   | Full API spec                                |
+| [`docs/data-layer.md`](docs/data-layer.md)                       | `@dar/data` design (SWR + debounce)          |
+| [`docs/agents/pr-workflow.md`](docs/agents/pr-workflow.md)       | How agents send / review / merge PRs         |
+| [`docs/agents/autonomy-policy.md`](docs/agents/autonomy-policy.md) | What's auto-mergeable vs human-only        |
+| [`docs/agents/decisions.md`](docs/agents/decisions.md)           | Decisions log                                |
+| [`scripts/README.md`](scripts/README.md)                         | `lint.sh` / `build.sh` / `deploy.sh`         |
+| [`examples/README.md`](examples/README.md)                       | Demo Django apps                             |
+
+---
+
+## Developer scripts
+
+```bash
+./scripts/lint.sh        # ruff + black + isort + flake8 + pylint + mypy + bandit + prettier + tsc
+./scripts/build.sh       # pnpm install + vite build + poetry build (wheel ships pre-built SPA)
+./scripts/deploy.sh      # poetry publish to PyPI (requires POETRY_PYPI_TOKEN_PYPI)
+```
+
+The Merger runs `./scripts/lint.sh` before every merge — there is
+no CI in this repo by design.
+
+---
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).
+
+## Security
+
+Please report security issues privately. See
+[`SECURITY.md`](SECURITY.md) §4. Do **not** open a public issue.
+
+## Contributing
+
+Humans and AI agents both welcome. Start with
+[`CONTRIBUTING.md`](CONTRIBUTING.md). AI agents must also read
+[`CLAUDE.md`](CLAUDE.md), [`docs/agents/pr-workflow.md`](docs/agents/pr-workflow.md),
+and [`docs/agents/autonomy-policy.md`](docs/agents/autonomy-policy.md).

django_admin_react-0.1.0a1/django_admin_react/README.md

@@ -0,0 +1,57 @@
+# django_admin_react/ — the Python package
+
+This directory **is** the artifact published to PyPI. Everything else
+in the repository supports it.
+
+## Layout
+
+```
+django_admin_react/
+├── __init__.py          # __version__ and AppConfig entry point
+├── apps.py              # Django AppConfig
+├── conf.py              # settings.DJANGO_ADMIN_REACT lazy loader
+├── urls.py              # mountable URL patterns (api/v1/ + SPA fallback)
+├── views.py             # SPA index view
+├── api/
+│   ├── __init__.py
+│   ├── urls.py          # API URL patterns
+│   ├── permissions.py   # IsStaffUser + ModelAdmin gates
+│   ├── registry.py      # AdminSite introspection helpers
+│   ├── serializers.py   # conservative field serialization
+│   └── views/           # one file per endpoint (registry/list/detail/...)
+├── templates/admin_react/
+│   └── index.html       # SPA shell template
+└── static/admin_react/  # built React bundle drops here
+```
+
+## Rules
+
+- This package may **not** import from `frontend/`, `examples/`, or
+  `tests/`. It is self-contained.
+- It may **not** import a consumer's models. All access goes through
+  `admin.site._registry` and `ModelAdmin` methods.
+- It may **not** hardcode example model names (`Account`, `Book`,
+  `Transaction`, …). If you see one, fix it.
+- Settings live under a single dict `settings.DJANGO_ADMIN_REACT`. Read
+  them through `django_admin_react.conf`, never via
+  `django.conf.settings.DJANGO_ADMIN_REACT` directly.
+
+## Implementation status
+
+| File                          | Status             | Lands in PR |
+| ----------------------------- | ------------------ | ----------- |
+| `__init__.py`, `apps.py`      | Stub               | #1          |
+| `conf.py`                     | Stub w/ defaults   | #1 → flesh out in #2 |
+| `urls.py`                     | Routes wired, views stubbed | #1 → #6 |
+| `views.py`                    | SpaIndexView stub  | #6          |
+| `api/permissions.py`          | Empty              | #3          |
+| `api/registry.py`             | Empty              | #3          |
+| `api/serializers.py`          | Empty              | #4          |
+| `api/views/registry.py`       | Empty              | #3          |
+| `api/views/list.py`           | Empty              | #4          |
+| `api/views/detail.py`         | Empty              | #4          |
+| `api/views/create.py`         | Empty              | #5          |
+| `api/views/update.py`         | Empty              | #5          |
+| `api/views/delete.py`         | Empty              | #5          |
+| `templates/admin_react/index.html` | Placeholder  | #6          |
+| `static/admin_react/`         | `.gitkeep`         | populated at build time |

django_admin_react-0.1.0a1/django_admin_react/__init__.py

@@ -0,0 +1,10 @@
+"""django-admin-react — a React single-page admin for Django.
+
+The actual implementation lands across PRs #2-#7. This package is
+currently a skeleton that defines the layout and the Django AppConfig
+entry point only. See `ARCHITECTURE.md` for the design contract.
+"""
+
+__version__ = "0.0.0"
+
+default_app_config = "django_admin_react.apps.DjangoAdminReactConfig"

django_admin_react-0.1.0a1/django_admin_react/api/README.md

@@ -0,0 +1,31 @@
+# django_admin_react/api/
+
+JSON API package. See [`/docs/api-contract.md`](../../docs/api-contract.md)
+for the wire format and [`/ARCHITECTURE.md`](../../ARCHITECTURE.md) §4 for
+the design.
+
+## Rules
+
+- Every view consults `ModelAdmin` for permissions, queryset, form,
+  serialization. No exceptions.
+- No direct `Model.objects.all()` — start from
+  `ModelAdmin.get_queryset(request)`.
+- Client-provided `app_label`/`model_name` are resolved through
+  `admin.site._registry` only.
+- CSRF on unsafe methods. Never exempt yourself.
+- Conservative serializer with `str()` fallback (see
+  `serializers.py`).
+- A denylist of sensitive-shaped field names is applied on top of the
+  admin form's own exclusion (defense in depth).
+
+## Layout
+
+| File              | Purpose                                                      |
+| ----------------- | ------------------------------------------------------------ |
+| `urls.py`         | URL patterns for all API endpoints.                          |
+| `permissions.py`  | Staff + AdminSite.has_permission gate; per-op delegation.    |
+| `registry.py`     | AdminSite introspection helpers.                             |
+| `serializers.py`  | Conservative field serialization + denylist.                 |
+| `views/`          | One module per endpoint.                                     |
+
+Implementation status is tracked in `../README.md`.

django_admin_react-0.1.0a1/django_admin_react/api/__init__.py

@@ -0,0 +1,5 @@
+"""JSON API for django_admin_react.
+
+See `docs/api-contract.md` for the wire contract. All endpoints live
+here; nothing in this subpackage may bypass ModelAdmin.
+"""

django_admin_react-0.1.0a1/django_admin_react/api/permissions.py

@@ -0,0 +1,80 @@
+"""Permission helpers.
+
+The package's default permission gate is:
+
+    user.is_authenticated and user.is_active and user.is_staff
+    and admin_site.has_permission(request)
+
+Per-operation gates always go through the relevant
+``ModelAdmin.has_*_permission(request, obj=None)`` method.
+
+See ``SECURITY.md`` §3 (rules 1 and 12) for the contract this enforces.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+from django.contrib.admin.sites import AdminSite
+from django.http import HttpRequest
+from django.http import HttpResponse
+from django.http import JsonResponse
+
+from django_admin_react.api.registry import get_admin_site
+
+
+def _user_is_active_staff(request: HttpRequest) -> bool:
+    """Return True iff the request user is authenticated, active, and staff.
+
+    The triple check is intentional and each part is load-bearing.
+
+    - ``is_authenticated`` rejects ``AnonymousUser``.
+    - ``is_active`` ensures a deactivated account loses access immediately;
+      relying on ``is_staff`` alone would still let a disabled superuser
+      through.
+    - ``is_staff`` is the standard Django admin gate.
+
+    ``getattr(user, "is_active", False)`` (rather than ``user.is_active``)
+    is defensive: a custom user model might omit the attribute, and the
+    safe default is "no".
+    """
+    user = getattr(request, "user", None)
+    return bool(
+        user is not None
+        and user.is_authenticated
+        and getattr(user, "is_active", False)
+        and getattr(user, "is_staff", False)
+    )
+
+
+def is_admin_user(request: HttpRequest, admin_site: AdminSite | None = None) -> bool:
+    """Return True iff the request may access the package's API.
+
+    The package's default policy is staff-only (rule 1 in ``SECURITY.md``
+    §3). ``AdminSite.has_permission`` is the consumer's escape hatch: if
+    a consumer's custom site allows non-staff users to access the admin,
+    this package follows that decision (`ARCHITECTURE.md` §4.2).
+    """
+    if not _user_is_active_staff(request):
+        return False
+    site = admin_site if admin_site is not None else get_admin_site()
+    return bool(site.has_permission(request))
+
+
+_FORBIDDEN_BODY: Final[dict[str, dict[str, str]]] = {
+    "error": {"code": "forbidden", "message": "You do not have permission."}
+}
+
+
+def forbidden_response() -> HttpResponse:
+    """Return the package's canonical 403 envelope.
+
+    The body never includes data identifying the resource (per ``SECURITY.md``
+    §3 rule 12). For unauthenticated requests, callers may also want to
+    redirect to ``settings.LOGIN_URL`` — that's a caller-level choice and
+    not encoded here.
+    """
+    response = JsonResponse(_FORBIDDEN_BODY, status=403)
+    # Discourage caching of a permission decision.
+    response["Cache-Control"] = "no-store"
+    return response