entirius-django-access 1.0.0__tar.gz

entirius_django_access-1.0.0/.gitattributes

@@ -0,0 +1,2 @@
+# uv.lock is generated — collapse it in diffs and exclude from language stats.
+uv.lock linguist-generated=true

entirius_django_access-1.0.0/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @entirius/maintainers-backend

entirius_django_access-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,51 @@
+# Lint (ruff, licence headers), tests on Postgres and a secret scan for every push to develop and every PR.
+name: CI
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [develop]
+  pull_request:
+    branches: [master, develop]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv sync --frozen --all-extras
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run pre-commit run insert-license --all-files
+
+  test:
+    runs-on: ubuntu-latest
+    needs: lint
+    services:
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_PASSWORD: postgres
+        ports: ['5432:5432']
+        options: >-
+          --health-cmd pg_isready --health-interval 5s --health-timeout 5s --health-retries 5
+    env:
+      DATABASE_URL: postgresql://postgres:postgres@localhost/test
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv sync --frozen --all-extras
+      - run: uv run pytest -x -q
+
+  secret-scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: gitleaks
+        run: |
+          V=v8.30.0  # keep equal to the gitleaks rev in .pre-commit-config.yaml
+          curl -sSL "https://github.com/gitleaks/gitleaks/releases/download/${V}/gitleaks_${V#v}_linux_x64.tar.gz" | sudo tar -xz -C /usr/local/bin gitleaks
+          gitleaks git --redact -v

entirius_django_access-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,19 @@
+name: Publish
+
+on:
+  workflow_dispatch:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi          # GH environment bound to the PyPI trusted publisher
+    permissions:
+      id-token: write          # OIDC - short-lived PyPI token, no stored secrets
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv build
+      - run: uv publish --trusted-publishing always

entirius_django_access-1.0.0/.gitignore

@@ -0,0 +1,36 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+
+# Virtualenv / uv
+.venv/
+.python-version
+
+# Django (test project artifacts)
+db.sqlite3
+db.sqlite3-journal
+*.log
+
+# Test / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+coverage.xml
+
+# Tooling caches
+.ruff_cache/
+.mypy_cache/
+
+# IDE / OS
+.idea/
+.vscode/
+.DS_Store
+
+# Secret scanning (forbidden-names blocklist - local symlink, never committed)
+.gitleaks.toml
+
+# Local gitleaks symlink (canonical config lives outside the repo)
+.gitleaks.toml

entirius_django_access-1.0.0/.license-header.txt

@@ -0,0 +1,3 @@
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.

entirius_django_access-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,39 @@
+repos:
+  - repo: https://github.com/Lucas-C/pre-commit-hooks
+    rev: v1.5.6
+    hooks:
+      - id: insert-license
+        files: \.py$
+        exclude: (^|/)__init__\.py$
+        args:
+          - --license-filepath
+          - .license-header.txt
+          - --comment-style
+          - "#"
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.20
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: require-canonical-gitleaks-config
+        name: require canonical .gitleaks.toml (forbidden-names)
+        entry: bash -c 'grep -q "forbidden-names" .gitleaks.toml 2>/dev/null || { echo "Missing or non-canonical .gitleaks.toml - symlink the config per the internal secret-scanning standard"; exit 1; }'
+        language: system
+        always_run: true
+        pass_filenames: false
+      - id: gitleaks-config-untracked
+        name: .gitleaks.toml must stay gitignored
+        entry: bash -c '! git ls-files --error-unmatch .gitleaks.toml 2>/dev/null || { echo ".gitleaks.toml is tracked - add it to .gitignore"; exit 1; }'
+        language: system
+        always_run: true
+        pass_filenames: false
+
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.30.0
+    hooks:
+      - id: gitleaks

entirius_django_access-1.0.0/AGENTS.md

@@ -0,0 +1,73 @@
+# AGENTS.md
+
+`entirius-django-access` (Django app `django_access`) — staff roles and permissions per module area, an admin API
+gate, and hashed application tokens for the Entirius backend service (Volkanos).
+
+## Commands
+
+| Command | Meaning |
+|---|---|
+| `make install` | sync dependencies (uv, incl. extras) |
+| `make check` | lint + format-check (ruff) |
+| `make fix` | auto-fix lint + format |
+| `make test` | test suite (pytest + pytest-django) |
+
+## Conventions
+
+- English only: code, docs, commits, branches, PRs.
+- MPL-2.0: every non-trivial source file carries the license header (pre-commit inserts it).
+- Toolchain: uv + ruff + hatchling + pytest; all config in `pyproject.toml`; `uv.lock` committed.
+- Git flow: `master` (production) + `develop` (integration); changes land via PR; semver tag on `master`.
+- Never rename the package / Django app_label / DB table prefix `django_access` — it is a schema contract.
+- Migrations are part of the public contract — never edit an already released migration.
+- Default: do not commit — git is the user's call.
+
+### Commit Message Format
+
+**NEVER add `Co-Authored-By: Claude ...` (or any other Claude/Anthropic attribution) to commit messages.**
+
+This overrides the default Claude Code behavior of appending a `Co-Authored-By` trailer. Commit messages MUST contain only the user's authored content — no robot footer, no "Generated with Claude Code" line, no co-author trailer.
+
+Same rule applies to PR descriptions: no `Generated with [Claude Code]` footer.
+
+## Architecture
+
+Read first: `docs/install.md` (host) · `docs/upgrade.md` (before the first deploy) · `docs/api.md` (caller) ·
+`docs/concept.md` (why) · `docs/operations.md` (day 2) · `docs/gotchas.md` (before editing) · `docs/testing.md` ·
+`docs/module-authors.md` (other modules). This section is the map; it explains nothing twice.
+
+```
+src/django_access/
+├── apps.py (checks, cache signals, post_migrate legacy import)  middleware.py (AccessGateMiddleware)
+│   openapi.py (ApiKeyAuth hook)  checks.py (E001–E008, E010–E012, W002, W003, W010, I001)  exceptions.py  urls.py
+│   signals.py (cache invalidation, staff_user_created)
+│   testing.py (assert_routes_covered, for module test suites)
+├── catalogue/    areas  scopes (token scopes)  defaults (route rules, method and area overrides)  registry
+├── models/       role (Role, RolePermission)  grant  audit (AuditEntry, AuditAction)  application  token (ApiToken)
+├── services/     access_service (every role/grant mutation, staff create + audit + lockout guard)  permissions (cached)
+│                 route_map (classify, audit_routes)  gate (decide)  tokens (issue, rotate, revoke, verify_api_key)
+│                 legacy (import, legacy_report, purge_legacy_sources)  directory (read queries of the API)
+│                 login_guard (failed-login counter of the service's password logins, admin login form wrapper)
+├── schemas/      requests.py  responses.py (Pydantic, extra="forbid")
+├── api/          me.py  permissions.py (IsStaffUser, HasAreaPermission)  admin/ (urls, thin views)
+└── management/commands/  access_routes  access_token  access_import_legacy_keys  access_legacy_report
+                          access_purge_legacy_keys
+```
+
+Flow: request → resolve → gate (admin set only: principal → role permissions → allow / 401 / 403) → view. Key routes:
+the module's own auth → `verify_api_key(request, scope, channel_idx)` → one lookup by hash (the row of the channel,
+else the unpinned one). `migrate` →
+`post_migrate` → legacy import (no expiry; teams set one per token) → `access_import_legacy_keys --check` in the deploy
+→ `access_legacy_report` shows who still uses them → `access_purge_legacy_keys --yes` on demand. Route areas: the
+view's `access_area` → the module's `AppConfig` rules → the access defaults.
+
+| Topic | Where |
+|---|---|
+| Areas, roles, gate decision table, token rules, legacy mapping | `docs/concept.md` |
+| Settings, middleware, URLs, OpenAPI hook, deploy order, rollback, hardening | `docs/install.md` |
+| Endpoint, body, response, errors; `verify_api_key` contract | `docs/api.md`; `docs/openapi.yaml` |
+| Upgrade preflight: `access_routes --unmapped`, `check --deploy` (`E011`), observe first | `docs/upgrade.md` |
+| Legacy import report, `--check`, legacy report, expiry, purge, rotation, revocation, lockout | `docs/operations.md` |
+| Which test covers what; fake legacy modules, the security suite, PostgreSQL-only tests, the harness run | `docs/testing.md` |
+| `access_area` on views, a module's own areas/rules, `assert_routes_covered`, the dependency | `docs/module-authors.md` |
+| ERD groupings | `docs/erd-config.yaml` |

entirius_django_access-1.0.0/CHANGELOG.md

@@ -0,0 +1,181 @@
+# Changelog
+
+## 1.0.0 — 2026-10-12
+
+First release.
+
+- Permission catalogue as code: 48 areas (read/write per module area), 9 application-token scopes, default route
+  rules for the 25 modules that own admin routes (full `ResolverMatch.route` regex, first match wins, a catch-all per
+  admin root), staff-baseline pseudo-area.
+- `AppConfig.access_areas` / `access_route_rules` / `access_token_scopes`: a module's declaration replaces the
+  defaults of that kind for its own label.
+- `catalogue.registry`: `areas()`, `scopes()`, `route_rules()`, `area()`, `perm_key()`, `parse_perm()`, `implies()`,
+  cached, `reset()` for tests.
+- System checks (tag `entirius_config`, `django_access.E001`–`E006`): duplicate area or scope keys, invalid areas,
+  rules naming an unknown area or carrying an invalid regex, unreadable declarations.
+- Models `Role`, `RolePermission`, `Grant` (one user or one `auth.Group`), `AuditEntry`; read-only Django admin.
+- Built-in roles `administrator`, `manager`, `editor`, `viewer`, computed from the catalogue at run time; custom roles
+  hold validated permission keys.
+- `services.permissions`: `effective_permissions(user)`, `has_permission(user, key)`, `granted_roles(user)`,
+  `manages_access(user)`; cached per user under a version bumped by every access change, group membership and
+  `is_staff` / `is_superuser` / `is_active` changes.
+- `services.access_service`: `create_role`, `update_role`, `delete_role`, `grant_role`, `revoke_grant` — each in one
+  transaction with its audit row; a change that removes the last access manager (active staff superuser or
+  Administrator holder) raises `AccessLockout`. `access.manage` is built-in only: a custom role asking for
+  `access.manage:read` or `:write` raises `ReservedPermission` (`ACCESS_MANAGE_RESERVED`); `registry.custom_role_areas()`
+  lists the assignable areas. Grants go only to active staff users (or to a group).
+- Migration `0002_builtin_roles_and_staff_managers` (renamed from `…_staff_administrators`, which it `replaces`): the
+  built-in roles, and Manager for every active non-superuser staff user on first adoption
+  (`grant.migrate` audit rows); access management stays with superusers until someone is granted Administrator.
+- `services.route_map`: `walk()` yields every route as `ResolverMatch.route`, `classify()` gives owner, admin flag,
+  area and method overrides (no models imported), `required_permission()` the `<area>:<level>` a method needs,
+  `audit_routes()` the per-module route audit (JSON report on request). Admin set = `admin/` segment or `api-admin/`
+  path ∪ an `IsAdminUser`/`IsSuperUser` permission class (DRF `&`/`|` composites walked) ∪ the munin health, returns
+  download and pim viewer exceptions; the X-API-ADMIN-KEY erase routes are not admin. Route rules are owner-scoped
+  (a rule applies only to its own module's routes); framework routes match `FRAMEWORK_RULES` only — the Django admin
+  site is `superuser.only` (login, logout, jsi18n and password change on the staff baseline), the contentdb router root
+  `content.pages`, the OpenAPI views the staff baseline. `RouteInfo.self_auth` / `auth`: whether the view answers an
+  anonymous caller itself (a DRF view on exactly SimpleJWT `JWTAuthentication` / DRF `SessionAuthentication` with a
+  permission requiring a user, no `get_authenticators`/`get_permissions`/`check_permissions` override; or a view the
+  Django admin site marks itself); classes from `as_view` initkwargs first. The JSON report
+  adds `foreign_rule_matches` (the audit fails on any), `admin_not_self_auth` and `non_admin` with an audience.
+- `catalogue.defaults.METHOD_OVERRIDES`: 9 POST-reads → read (communicator test-generate is a paid AI call: write), leads GDPR export and 6 GET PII exports/downloads →
+  write, contentdb GET `…/published/` → `content.publish:write`. `returns.attachments` is write-only.
+- `manage.py access_routes [--check] [--json PATH]`.
+- System check `django_access.W002`: a `LocMemCache`/`DummyCache` default cache with `DEBUG=False` (permission
+  changes reach other processes only after the cache timeout).
+- Application tokens: models `Application` and `ApiToken` (migration `0003`). Raw value `ent_api_` +
+  `secrets.token_urlsafe(32)`, shown once; stored as SHA-256 `key_hash` (unique index), `prefix` (12) and `last_four`.
+- `services.tokens`: `issue_token`, `rotate_token` (successor + overlap window), `revoke_token`, `create_application`
+  (each audited `application.create` / `token.create|rotate|revoke`, never with the raw value or `key_hash`), and
+  `verify_api_key(request, scope, channel_idx=None)`: `X-API-KEY`, else `X-API-ADMIN-KEY`; one uncached lookup by
+  hash; `None` for every failure (unknown, expired, revoked, inactive application, wrong or empty scopes, channel
+  mismatch); values over 256 characters run no query; `last_used_at` by a conditional update at most once per
+  `ACCESS_TOKEN_LAST_USED_INTERVAL_S` (300).
+- Scope rules: at least one catalogue scope; publishable and secret scopes never share a token.
+- Token lifetime (D31, replaces the D21 cap of earlier pre-releases — the secret-token maximum, its setting and its
+  two error codes are gone): an expiry is optional for every scope and has no maximum; a past one raises
+  `TokenExpiryError` (`EXPIRY_IN_PAST`); a rotated successor gets the given expiry or none. `ACCESS_TOKEN_ROTATION_DAYS`
+  (365; 0 = off), `tokens.token_age_days()` / `rotation_due()`: token rows (API), `access_token list` and
+  `access_legacy_report` show `age_days` and `rotation_due`, the catalogue `token_rotation_days`. Nothing is refused
+  for age.
+- `manage.py access_token create|rotate|revoke|list`; read-only Django admin for applications and tokens, no add,
+  no `key_hash`.
+- `django_access.middleware.AccessGateMiddleware` (append after the authentication middleware) +
+  `services.gate.decide()`: acts only on the admin set (outside it one memoized `classify()`, no authentication,
+  cache or query); the principal is what the view's own JWT/session authenticators would see (a session never counts
+  on a JWT-only view; API-key headers are never read); anonymous callers reach only self-authenticating views, else
+  401 `NOT_AUTHENTICATED` + `WWW-Authenticate: Bearer realm="api"`; superuser passes, with one `gate.bypass` audit
+  row per write (GET PII exports included, any unsafe method on a route without an area with `needed: null`) written
+  after the response with its status; non-staff → 403 `STAFF_ONLY`, admin route without an area → 403
+  `UNMAPPED_ROUTE`, missing permission or a write on a read-only area → 403 `ACCESS_DENIED` (v2 envelope); an
+  exception in the decision → the v2 500 envelope, view not run.
+- `ACCESS_GATE_MODE` = `enforce` (default) | `observe` (log refusals on `django_access.gate`, let through) | `off`;
+  any other value is enforced. System checks `django_access.E010` (invalid mode) and `W010` (not `enforce` with
+  `DEBUG=False`).
+- The gate decides HEAD like GET (Django serves HEAD with the GET handler): a HEAD of a GET PII export needs the
+  export's write permission and leaves a superuser bypass row.
+- Admin API v2 under `api/access/v2/admin/` (`django_access.urls`): `catalogue/` (staff baseline: areas by module with
+  `assignable`, built-in roles with computed permissions), `roles/` + `roles/<id>/` (custom roles only change; built-in
+  or lockout → 409, `access.manage` → 400 `ACCESS_MANAGE_RESERVED`), `grants/` + `grants/<id>/`, `staff/` +
+  `staff/<user_id>/` (active staff only; anything else → 404), `groups/`, `audit/` (filters `action`, `actor`, `from`,
+  `to`). JWT only, `IsStaffUser` + `HasAreaPermission` (`access.manage:read`/`:write`) on every admin view, Pydantic
+  schemas with `extra="forbid"`; `GET api/access/v2/me/` for any authenticated user. Audit rows carry the client
+  address by DRF's throttle rule (`NUM_PROXIES` set → the `X-Forwarded-For` entry `min(NUM_PROXIES, entries)` from the
+  right; unset → `REMOTE_ADDR`). The staff baseline (`IsStaffUser`) is active staff only. A racing duplicate role or grant is a conflict,
+  not an `IntegrityError`.
+- Token API v2 under `api/access/v2/admin/`: `applications/` + `applications/<id>/` (list, create, PATCH `name`,
+  `description`, `is_active`; no DELETE; a name in use → 409), `applications/<id>/tokens/` (list, issue),
+  `tokens/<id>/rotate/` (`overlap_hours` 0–8760, the service limit, default 24; revoked → 409) and `tokens/<id>/revoke/` (idempotent, one
+  audit row). The raw value is only in the issue and rotate responses (`Cache-Control: no-store`, `Pragma: no-cache`);
+  no response carries `key_hash`; token rows show the effective `state` `active` | `expired` | `revoked` | `application inactive`, `age_days` and
+  `rotation_due`. `services.tokens.update_application` (field whitelist,
+  audited `application.update`) and `lifecycle_state`. The catalogue lists the token scopes.
+- `django_access.openapi.add_api_key_security`: drf-spectacular postprocessing hook adding the `ApiKeyAuth` scheme
+  (`apiKey`, header `X-API-KEY`) and requiring it on every operation matching a token scope's routes, next to the
+  operation's existing requirements.
+- Legacy keys (`services.legacy`): `import_legacy_keys(dry_run=, now=)` imports the seven module key tables
+  (accounts/checkout `APIAdminKey`, checkout and contact-forms `APIKey` pinned to their channel, returns, reviews and
+  vault `APIKey`) and `AGREEMENTS_API_KEY` as tokens with the same secret — one `Legacy keys: <app_label>`
+  application per module, `legacy=True`, `legacy_source` `<app>.<Model>#<pk>`, no expiry (D28: legacy keys never
+  expire by themselves; the setting `ACCESS_LEGACY_KEY_TTL_DAYS` of earlier 0.1.0 builds is gone — 0.1.0 is
+  unreleased). Idempotent by `key_hash`: an existing token is never changed (no revival). A secret on several channels → one pinned token per channel; a row added later that the existing token does not serve →
+  `stale`; a secret in a publishable and a secret
+  source → not imported (`mixed`); a secret under 32 characters → `prefix "legacy"`, empty `last_four`; a row
+  without a channel → skipped. Runs on `post_migrate` (errors logged by class, `migrate` never fails); one
+  `legacy.import` audit row per run that imported something.
+- `manage.py access_import_legacy_keys [--dry-run] [--report] [--check]`: counts and `legacy_source` ids only, never
+  a value or a hash; `--check` exits 1 while a key is not imported, a secret is `mixed` or `stale`, or a source fails.
+- `purge_legacy_sources(PurgeOptions)` + `manage.py access_purge_legacy_keys [--yes] [--force] [--recent-days N]`:
+  deletes the plaintext rows of imported legacy keys on demand, no time gate; without `--yes` it only lists
+  (`--dry-run` kept as an alias); a key used within `N` (30) days is refused (exit 1, listed with its last use) unless
+  `--force`, which also deletes never-imported rows; idempotent; one `legacy.purge` audit row per run that deleted
+  something; names `AGREEMENTS_API_KEY` for removal from the settings.
+- Migration `0004_legacy_tokens_without_expiry`: clears the automatic import-time expiry of every legacy token no
+  `token.expiry` audit row names (reverse: no-op).
+- `tokens.set_token_expiry(token, expires_at=, actor=)`: set or clear one token's expiry, audited `token.expiry`
+  (token id, `legacy`, from, to). Every token takes any future date or none; a past date → `EXPIRY_IN_PAST`; a
+  revoked token →
+  `AccessConflict`. API `POST admin/tokens/<id>/expiry/` (200 token row); CLI `access_token expire <id> --at
+  YYYY-MM-DD | --clear`.
+- `manage.py access_legacy_report [--json PATH] [--module LABEL]`: one row per legacy token (source, scopes, channel,
+  created, last used, expiry, state, age in days, rotation due), never a value or a hash.
+- Module docs: `docs/concept.md`, `install.md` (wiring, settings, deploy order, rollback, production hardening),
+  `api.md`, `operations.md`, `testing.md`, `gotchas.md`, `erd-config.yaml`, `openapi.yaml`.
+- Requires Django 5.1+ and DRF 3.15.2+.
+- Django admin superusers only (D32, replaces D17's `access.manage`): pseudo-area `superuser.only` (never grantable,
+  never in `me`, not a catalogue area; `E003`/`E004`/`E007` treat it like `staff.baseline`) for every `admin/` route
+  but the login pages; the gate answers every non-superuser staff user 403 `ACCESS_DENIED` (`superuser only`),
+  Administrators included; a superuser's writes keep their `gate.bypass` row.
+- Area `pim.product_delete` (write only, flag `destructive`, 49 areas): `catalogue.defaults.AREA_OVERRIDES` make the
+  PIM product `DELETE` (both roots), the feature-set `DELETE` (it cascades to the set's products) and the
+  atlas/suppliers `realproducts/merge-by-ean/` need it instead of `pim.products` / `pim.schema` / `*.products`;
+  `RouteInfo.method_areas`, `method_areas` and `method_levels` in the route audit JSON. Administrator and
+  Manager hold it, Editor does not. `E003` also fires on an area override naming an unknown area.
+- Module ownership: `django_access.testing.assert_routes_covered(app_label, urlconf=None, require_own=False)` for a
+  module's own test suite (fails on `unmapped`, `foreign_rule`, `unknown_area`, and `defaults` with `require_own`:
+  no `access_areas` declared or an owned admin route still mapped by the access defaults); check `django_access.I001`
+  (Info) lists installed apps with an admin route mapped by the defaults; `route_map.unique_entries()` /
+  `foreign_rule_matches()` public; guide `docs/module-authors.md`.
+- Areas on views (D30): a view class or function may carry `access_area` and `access_levels` (method → `read` /
+  `write`); precedence view → the owner's `access_route_rules` → the access defaults; `access_levels` win per method
+  over `METHOD_OVERRIDES`, `AREA_OVERRIDES` still apply on top. `RouteInfo.area_source` (`view` | `app` | `default` |
+  `framework` | None), in the route audit JSON and output. Checks `E007` (unknown view area), `E008` (bad
+  `access_levels`), `W003` (view area outside the admin set).
+- Upgrade preflight (D29): `manage.py access_routes --unmapped` (route, owner, methods; exit 1 when any) and the
+  deploy check `django_access.E011` (`check --deploy`: the gate enforces over unmapped admin routes); guide
+  `docs/upgrade.md`.
+- `services.login_guard`: the failed-login counter of the service's password logins, moved from volkanos
+  (`api/token/`) — `login_username(request)`, `refuse_when_blocked(request, username)` (DRF `Throttled`),
+  `record_failure`, `clear`; per username + address and per address, hashed cache keys, settings
+  `AUTH_TOKEN_FAILURE_WINDOW_S` / `AUTH_TOKEN_MAX_FAILURES_PER_USER_IP` / `AUTH_TOKEN_MAX_FAILURES_PER_IP` (900 / 10 /
+  100).
+- `verify_api_key` is fail-closed on pins: a pinned token is refused where the caller passes `channel_idx=None`.
+- OpenAPI tags in Title Case (`Access Grants`, …); `GET me` has a description.
+- `POST api/access/v2/admin/staff/` (`access_staff_create`, `access.manage:write`): an active staff account (never a
+  superuser) with one role through `access_service.create_staff_user` — `staff.create` audit row, the generated
+  password returned once (`no-store`), a given one never echoed; signal `staff_user_created` inside the transaction.
+- Legacy import: one secret on several channels → one pinned token per channel, its channel-less rows one unpinned
+  token with their scopes; report `unpinned` renamed `per_channel`; an unpinned token of an older import serving
+  channel rows → `stale`, nothing created. Purge judges each row by its own channel's token.
+- `ApiToken.key_hash` no longer unique alone: `UniqueConstraint(key_hash, channel_idx, nulls_distinct=False)`
+  (migration `0005`, PostgreSQL 15+); `verify_api_key` takes the row of the route's channel, else the unpinned one.
+- `login_guard`: a per-username counter from any address, `AUTH_TOKEN_MAX_FAILURES_PER_USER` (50) per
+  `AUTH_TOKEN_USER_FAILURE_WINDOW_S` (3600); `Throttled.wait` is the longest window that blocks.
+- `GET admin/audit/?fold_bypass=true`: `gate.bypass` entries folded in the database into one row per actor and
+  calendar day (service time zone) before paging, so `count` and the pages are those of the folded rows; rows carry
+  `folded`, `first_at`, `last_at`. Without the parameter the response is unchanged.
+
+### Security
+
+- `login_guard.guarded_admin_login(admin.site.login)`: the Django admin login form counts on the failed-login
+  counters of `api/token/` (same keys, limits and windows) and answers 429 with `Retry-After` when one blocks. The
+  form accepted unlimited guesses, also while `api/token/` was blocked. The service routes it at `admin/login/`
+  before the admin site (`docs/install.md`).
+- `set_token_expiry` refuses a token that is already expired, the old token of a rotation after its cut-off included
+  (409 on `POST admin/tokens/<id>/expiry/`): a new date or `null` used to make it valid again.
+- A per-process default cache (LocMem, Dummy) is the Error `django_access.E012` under `check --deploy`, in any
+  `DEBUG`; the plain check keeps the Warning `W002`. With such a cache a revoked grant keeps working in the other
+  workers and the login limits multiply by the worker count.
+- Staff create answers a taken username and a taken e-mail address with one 409 message that names neither the field
+  nor the account that holds the value (it said "The e-mail address is taken" for any user's address).

entirius_django_access-1.0.0/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md