authzlock 0.1.0__tar.gz

authzlock-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.eggs/
+
+# Environments
+.venv/
+venv/
+.nox/
+.tox/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Editors and OS
+.idea/
+.vscode/
+.DS_Store

authzlock-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,8 @@
+# Hooks for developing authzlock itself. Install once with `pre-commit install`.
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.9
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format

authzlock-0.1.0/.pre-commit-hooks.yaml

@@ -0,0 +1,23 @@
+# Hooks that other repositories can use to keep their authz.lock current.
+# Usage and configuration: docs/pre-commit.md.
+#
+# pre-commit runs hooks from the repository root. The entry `python -m authzlock` gets the
+# current directory on sys.path from the interpreter; the `authzlock` script would work as
+# well, since authzlock puts the current directory first on sys.path itself. Either way the
+# project's settings module can be imported without setting PYTHONPATH.
+- id: authzlock-check
+  name: authzlock check
+  description: Fail when authz.lock does not match the Django project's access rules.
+  entry: python -m authzlock check
+  language: python
+  pass_filenames: false
+  always_run: true
+  require_serial: true
+- id: authzlock-update
+  name: authzlock update
+  description: Rewrite authz.lock from the Django project; fails when the file changed.
+  entry: python -m authzlock update
+  language: python
+  pass_filenames: false
+  always_run: true
+  require_serial: true

authzlock-0.1.0/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to authzlock are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-02
+
+First release.
+
+### Added
+
+- Package skeleton with the `authzlock` command and `authzlock --version`.
+- Loading a Django project from `DJANGO_SETTINGS_MODULE`, with plain error messages when the
+  settings module is missing or fails to import.
+- Support for Python 3.10 to 3.13, Django 4.2, 5.1, 5.2, 6.0 and 6.1, and Django REST
+  Framework 3.14 and newer, tested in CI on every pull request.
+- Release workflow that publishes to PyPI from a version tag using trusted publishing.
+- `authzlock update` writes the project's access rules to `authz.lock`, a sorted YAML file
+  with schema version 1, and `authzlock check` exits 1 with a readable report when the
+  project and the lockfile differ. See `docs/lockfile.md` and `docs/cli.md`.
+- pre-commit hooks `authzlock-check` and `authzlock-update`. See `docs/pre-commit.md`.
+- `authzlock diff --base <ref>`: compares the lockfile committed at a git ref with the
+  current project and labels each route `loosened`, `tightened`, `added`, `removed` or
+  `changed-unknown`, as text or as markdown for a pull request comment, with
+  `--fail-on loosened` to fail only on loosened routes.
+- GitHub Action (`smhasan94/authzlock@v1`): runs `authzlock diff` on a pull request, keeps one
+  comment with the changes up to date across pushes, and fails the job when a route is
+  loosened (`fail-on-loosened`, default true). See `docs/github-action.md`.
+- Reference documentation indexed in `docs/index.md`, including
+  `docs/heuristics-and-limits.md` on what the heuristics cannot tell you, and a contributor
+  guide, `CONTRIBUTING.md`.
+
+### Fixed
+
+- `authzlock` now declares Django 4.2 or newer as a dependency, so `pip install authzlock`
+  followed by `authzlock --version` works in a fresh environment. DRF stays optional.
+- The `authzlock` command now finds the project's settings module when run from the project
+  root without `PYTHONPATH`: the current directory is put first on the import path, as
+  `manage.py` and `python -m authzlock` do.

authzlock-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,144 @@
+# Contributing to authzlock
+
+This page covers the development setup, the checks a change must pass, the branch and commit
+conventions, and how to add a fixture project. [DEVELOPMENT.md](DEVELOPMENT.md) holds the
+project brief and the same commands; `tests/test_docs.py` fails when the shell commands on
+the two pages differ, so change both together. [docs/index.md](docs/index.md) lists the
+reference pages.
+
+## Setup
+
+Python 3.10 or newer and git are needed. Set up a dev environment once:
+
+```sh
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pip install nox
+```
+
+## Checks
+
+Lint and format check (what CI runs):
+
+```sh
+nox -s lint
+# equivalent to:
+ruff check . && ruff format --check .
+```
+
+Auto-fix formatting and lint:
+
+```sh
+ruff format . && ruff check --fix .
+```
+
+Type check (mypy strict on the package):
+
+```sh
+nox -s typecheck
+# equivalent to:
+mypy src/authzlock
+```
+
+Tests, full matrix (Python 3.10-3.13 x Django 4.2/5.x):
+
+```sh
+nox -s tests
+```
+
+Tests, one interpreter and Django version:
+
+```sh
+nox -s "tests(python='3.12', django='5.2')"
+# or directly in the active venv:
+pytest
+```
+
+Tests against the oldest supported DRF (3.14, on Python 3.12 and Django 4.2):
+
+```sh
+nox -s tests_min_drf
+```
+
+Run everything CI runs:
+
+```sh
+nox
+```
+
+Session names are defined in `noxfile.py`. CI runs the same sessions on every pull request:
+`lint`, `typecheck`, eleven `tests (python=X, django=Y)` cells and the DRF 3.14 cell, plus
+the GitHub Action end-to-end jobs described in
+[docs/github-action.md](docs/github-action.md#testing-the-action).
+
+## Branches, commits and pull requests
+
+- Work happens on short-lived branches off `main`. A branch is named after its Linear
+  ticket: the lowercase identifier, a hyphen and a short slug of the title, for example
+  `sha-12-url-resolver-walk`.
+- Commits use conventional prefixes: `feat:`, `fix:`, `docs:`, `chore:`, `test:`, `ci:`.
+- Tests come first. Each test carries the ticket's T-case id in its name, for example
+  `test_t3_missing_module_raises_project_load_error`, and is committed before the change
+  that makes it pass.
+- Every code change goes through a pull request against `main`. It is merged once CI passes
+  and it has been reviewed. `docs/plans` and `docs/backlog.md` may be committed to `main`
+  directly.
+- A change is done when every T-case of its ticket passes in CI, ruff and mypy pass and the
+  docs are updated.
+- Add a line to the `## [Unreleased]` section of [CHANGELOG.md](CHANGELOG.md) for any change
+  a user would notice.
+
+Keep these rules from [DEVELOPMENT.md](DEVELOPMENT.md#working-rules) in mind: classification
+stays conservative (when unsure, `changed-unknown`), the package makes no network calls,
+lockfile output stays deterministic, and docs and messages use plain language.
+
+## Adding a fixture project
+
+Fixture projects under `tests/fixtures/` are small Django projects, one per view style.
+[tests/fixtures/README.md](tests/fixtures/README.md) describes their layout and how tests
+use them. To add one:
+
+1. Create `tests/fixtures/<style>/` with `settings.py` (`ROOT_URLCONF`, `INSTALLED_APPS`,
+   and `REST_FRAMEWORK` defaults where DRF is used), `urls.py` and one app package holding
+   only the views the tests assert on. The settings module is always `settings`.
+2. Write the tests first, using `run_extract("<style>")` from `tests/harness.py`. It runs
+   the extraction in a separate process, because Django can only be set up once per
+   process.
+3. Check the CLI against it from the repository root:
+
+   ```sh
+   DJANGO_SETTINGS_MODULE=settings PYTHONPATH=tests/fixtures/drf_viewsets \
+     authzlock check --lockfile tests/fixtures/drf_viewsets/authz.lock.expected
+   ```
+
+   (with your fixture's directory in place of `drf_viewsets`; for a new fixture, use
+   `authzlock update` with the same options to write its first lockfile).
+4. To have its lockfile compared byte for byte in every CI cell, add the fixture's name to
+   `DETERMINISM_FIXTURES` in `tests/test_determinism.py` and write its golden lockfile,
+   `authz.lock.expected`:
+
+   ```sh
+   pytest tests/test_determinism.py -k t5 --update-golden
+   ```
+
+   This rewrites the most specific golden file that exists for the installed Django and
+   DRF. If DRF 3.14 builds different routes for the fixture (the `tests_min_drf` session
+   fails), create `authz.lock.drf-3.14.expected` as a copy of `authz.lock.expected` and
+   rewrite it with `nox -s tests_min_drf -- tests/test_determinism.py -k t5 --update-golden`.
+   Read the generated files before committing them; they are the expected output from then
+   on.
+5. Describe the fixture under "Current fixtures" in `tests/fixtures/README.md`.
+
+## Generated docs
+
+The output blocks in [docs/scenario.md](docs/scenario.md) and the `diff` output in
+[README.md](README.md) are produced by the tests, which fail when they are stale. After a
+change to the output, rewrite them and review the diff:
+
+```sh
+pytest tests/test_scenario.py tests/test_readme.py --update-docs
+```
+
+`tests/test_docs.py` also checks that [docs/cli.md](docs/cli.md) lists exactly the options
+in `--help`, that relative links resolve and that no `authzlock` command in a code block uses
+an option that does not exist. Update the docs in the same pull request as the change.

authzlock-0.1.0/LICENSE

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

authzlock-0.1.0/PKG-INFO

@@ -0,0 +1,357 @@
+Metadata-Version: 2.5
+Name: authzlock
+Version: 0.1.0
+Summary: An authorization lockfile for Django and Django REST Framework.
+Project-URL: Homepage, https://github.com/smhasan94/authzlock
+Project-URL: Issues, https://github.com/smhasan94/authzlock/issues
+Author: Sharukh Hasan
+License-Expression: MIT
+License-File: LICENSE
+Keywords: authorization,django,drf,lockfile,permissions,security
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.1
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6.0
+Classifier: Framework :: Django :: 6.1
+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 :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: django>=4.2
+Requires-Dist: pyyaml>=6
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: django>=4.2; extra == 'dev'
+Requires-Dist: djangorestframework>=3.14; extra == 'dev'
+Requires-Dist: drf-nested-routers>=0.93; extra == 'dev'
+Requires-Dist: hatchling>=1.25; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: nox>=2024.4; extra == 'dev'
+Requires-Dist: pre-commit>=3.8; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff==0.16.9; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# authzlock
+
+[![CI](https://github.com/smhasan94/authzlock/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/smhasan94/authzlock/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/authzlock.svg)](https://pypi.org/project/authzlock/)
+
+An authorization lockfile for Django and Django REST Framework.
+
+In a Django project, the rules for who may call which endpoint are spread across
+`permission_classes` on views, `DEFAULT_PERMISSION_CLASSES` in settings, `get_permissions()`
+and `get_queryset()` overrides, and decorators such as `login_required`. A pull request can
+make an endpoint reachable by more users with a one-line change, and the reviewer sees the
+line, not the effect. authzlock reads those rules from the code, writes them for every route
+to a committed file, `authz.lock`, and on each pull request reports which routes changed and
+whether a change made access looser.
+
+**Status: pre-release.** The first release, 0.1.0, is not published yet. Until it is,
+`pip install authzlock`, the `smhasan94/authzlock@v1` action tag and the `v0.1.0` pre-commit
+rev below do not resolve; install from GitHub instead, as shown under Install.
+
+## Install
+
+```sh
+pip install authzlock
+```
+
+Install it into the same environment as your project, because authzlock imports your
+settings and URL configuration. Django 4.2 or newer is installed with it if missing; Django REST
+Framework is optional and only needed if your project uses it. Before the first release, install from the repository:
+
+```sh
+pip install git+https://github.com/smhasan94/authzlock
+```
+
+## Quickstart
+
+Run these from your project root, the directory that holds `manage.py`, inside a git
+repository. Replace `mysite.settings` with your settings module.
+
+```sh quickstart
+export DJANGO_SETTINGS_MODULE=mysite.settings
+authzlock update
+git add authz.lock
+git commit -m "Add authz.lock"
+authzlock check
+```
+
+`update` writes `authz.lock` and prints how many routes it recorded. `check` prints
+`authz.lock: up to date` and exits 0.
+
+Now change an access rule. In the example project used to test this README, an `@action`
+that only admins may call is opened to every signed-in user:
+
+```diff
+-    @action(detail=True, methods=["post"], permission_classes=[IsAdminUser])
++    @action(detail=True, methods=["post"], permission_classes=[IsAuthenticated])
+     def archive(self, request: Request, pk: Any = None) -> Response:
+```
+
+```sh quickstart
+authzlock check  # exits 1
+authzlock diff --base HEAD  # exits 1
+```
+
+`check` exits 1 and lists the routes whose rules no longer match `authz.lock`. `diff` compares
+the lockfile committed at `HEAD` with the code as it is now and labels each change. The
+action is served by three routes, and all three are `loosened`, because `IsAuthenticated`
+lets in more users than `IsAdminUser`:
+
+<!-- readme-diff:start -->
+```text
+loosened        POST ^invoices/(?P<pk>[^/.]+)/archive/$ -> billing.views.InvoiceViewSet  permission_classes: [rest_framework.permissions.IsAdminUser] -> [rest_framework.permissions.IsAuthenticated]  (R1: strongest built-in rest_framework.permissions.IsAdminUser -> rest_framework.permissions.IsAuthenticated)
+loosened        POST ^invoices/(?P<pk>[^/.]+)/archive\.(?P<format>[a-z0-9]+)/?$ -> billing.views.InvoiceViewSet  permission_classes: [rest_framework.permissions.IsAdminUser] -> [rest_framework.permissions.IsAuthenticated]  (R1: strongest built-in rest_framework.permissions.IsAdminUser -> rest_framework.permissions.IsAuthenticated)
+loosened        POST v2/^invoices/(?P<pk>[^/.]+)/archive/$ -> billing.views.InvoiceViewSet  permission_classes: [rest_framework.permissions.IsAdminUser] -> [rest_framework.permissions.IsAuthenticated]  (R1: strongest built-in rest_framework.permissions.IsAdminUser -> rest_framework.permissions.IsAuthenticated)
+
+3 loosened, 0 tightened, 0 added, 0 removed, 0 changed-unknown
+```
+<!-- readme-diff:end -->
+
+`diff` exits 1 whenever something changed; with `--fail-on loosened` it exits 1 only when a
+route is loosened. To accept the change, record it and commit it with the code:
+
+```sh quickstart
+authzlock update
+git commit -am "Let signed-in users archive invoices"
+authzlock check
+```
+
+`check` exits 0 again. In CI, run `check` to make sure `authz.lock` is current, and `diff`
+against the target branch to see what a pull request changes; the GitHub Action below does
+the second. [docs/scenario.md](docs/scenario.md) walks through a longer example.
+
+Exit codes for every command: 0 success, 1 the lockfile and the code differ, 2 error (the
+project could not be loaded, the lockfile could not be read, or git failed).
+
+## The lockfile
+
+`authz.lock` is YAML, sorted and stable, so the same code always gives the same bytes and a
+review diff shows only real changes. Do not edit it by hand; run `authzlock update`. Two of
+the routes from the example project:
+
+```yaml
+schema_version: 1
+routes:
+- path: ^customers/$
+  name: customer-list
+  view: billing.views.CustomerViewSet
+  methods:
+  - GET
+  actions:
+    GET: list
+  permission_classes:
+  - rest_framework.permissions.IsAuthenticated
+  permission_source: settings-default
+  authentication_classes:
+  - rest_framework.authentication.SessionAuthentication
+  authentication_source: settings-default
+  django_auth: null
+  object_scoping:
+    get_object:
+      overridden: false
+      references_request_user: null
+    get_queryset:
+      overridden: false
+      references_request_user: null
+    perform_create:
+      overridden: false
+      references_request_user: null
+- path: ^invoices/(?P<pk>[^/.]+)/archive/$
+  name: invoice-archive
+  view: billing.views.InvoiceViewSet
+  methods:
+  - POST
+  actions:
+    POST: archive
+  permission_classes:
+  - rest_framework.permissions.IsAdminUser
+  permission_source: action
+  authentication_classes:
+  - rest_framework.authentication.SessionAuthentication
+  authentication_source: settings-default
+  django_auth: null
+  object_scoping:
+    get_object:
+      overridden: false
+      references_request_user: null
+    get_queryset:
+      overridden: false
+      references_request_user: null
+    perform_create:
+      overridden: false
+      references_request_user: null
+custom_permissions: {}
+```
+
+Each route records its path, URL name, view, HTTP methods, the effective DRF permission and
+authentication classes and where they come from (`view`, `action` or `settings-default`),
+Django decorators for plain views, and whether the view overrides the hooks that scope
+objects to the caller. A `get_permissions()` override is recorded as `dynamic`. Custom
+permission classes are listed under `custom_permissions` with their docstring and the
+routes that use them. [docs/lockfile.md](docs/lockfile.md) describes every key.
+
+## How changes are classified
+
+`authzlock diff` gives every route that differs one label: `added`, `removed`, `loosened`,
+`tightened` or `changed-unknown`. For a route on both sides, the rules below run in order and
+the first that applies decides. Only DRF's built-in classes are ranked (`AllowAny` <
+`IsAuthenticatedOrReadOnly` < `IsAuthenticated` < `IsAdminUser`), and Django decorators
+(none < `login_required` < `permission_required`). A false `loosened` alarm is worse than
+`changed-unknown`, so authzlock never guesses what a custom, composed or `dynamic`
+permission does.
+
+| Rule | Applies when | Label | Example |
+|------|--------------|-------|---------|
+| R1 | Both lists hold only ranked built-ins and the strongest class differs | `loosened` if the strongest class is weaker, `tightened` if stronger | `[IsAuthenticated]` to `[AllowAny]` is `loosened` |
+| R2 | An unranked class is removed, the new list holds no unranked class, and the new strongest built-in is at most `IsAuthenticated` or at most the old strongest built-in | `loosened` | `[shop.permissions.IsOwner]` to `[IsAuthenticated]` is `loosened` |
+| R3 | An unranked class is replaced by another unranked class, or by `IsAdminUser` | `changed-unknown` | `[shop.permissions.IsOwner]` to `[IsAdminUser]` is `changed-unknown` |
+| R4 | An unranked class is added and every old entry is kept | `tightened` | `[IsAuthenticated]` to `[IsAuthenticated, shop.permissions.IsOwner]` is `tightened` |
+| R5 | Either side of a changed field is `dynamic` | `changed-unknown` | `dynamic` to `[IsAuthenticated]` is `changed-unknown` |
+| R6 | Only `django_auth.login_required` or `django_auth.permission_required` changed | `tightened` when the Django auth rank rises or `permission_required` gains entries; `loosened` for the reverse | `login_required` true to false is `loosened` |
+| R7 | Only `methods` (and `actions`) changed and `methods` gained entries | `changed-unknown` | `[DELETE, GET]` to `[DELETE, GET, PUT]` is `changed-unknown` |
+| R8 | Anything else | `changed-unknown` | `[(IsAuthenticated \| shop.permissions.IsOwner)]` to `[IsAuthenticated]` is `changed-unknown` |
+
+R1 to R4 apply only when `permission_classes` is the one access field that changed.
+[docs/classification.md](docs/classification.md) has the full rules, examples and the
+cases that are `changed-unknown` on purpose.
+
+## GitHub Action
+
+The action runs `authzlock diff` on a pull request against its base branch, posts the result
+as one comment that it updates on every push, and fails the job when a route is loosened.
+Save this as `.github/workflows/authzlock.yml`:
+
+```yaml
+name: authzlock
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  authzlock:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -r requirements.txt
+      - uses: smhasan94/authzlock@v1
+        with:
+          settings-module: mysite.settings
+          python-version: "3.12"
+```
+
+Install your project's dependencies before the action, in the Python version you give it.
+Inputs, outputs, fork pull requests and how to also run `check` are in
+[docs/github-action.md](docs/github-action.md).
+
+## pre-commit
+
+The `authzlock-check` hook fails a commit when `authz.lock` does not match the code. Add this
+to `.pre-commit-config.yaml` and run `pre-commit install`:
+
+```yaml
+repos:
+  - repo: https://github.com/smhasan94/authzlock
+    rev: v0.1.0
+    hooks:
+      - id: authzlock-check
+        args: ["--settings", "mysite.settings"]
+        additional_dependencies:
+          - "django==5.2.*"
+          - "djangorestframework==3.16.*"
+```
+
+The hook runs in its own virtualenv, so list every package your settings and URL
+configuration import under `additional_dependencies`, pinned like your project. The
+`authzlock-update` hook and the details are in [docs/pre-commit.md](docs/pre-commit.md).
+
+## What authzlock does not do
+
+- It does not support FastAPI or any framework other than Django and Django REST Framework.
+- It does not prove that custom permission logic is correct. A custom class such as
+  `IsOwner` is recorded by name with its docstring; its code is never run or judged.
+- It does not do black-box testing of a running app. It reads code and settings, sends no
+  HTTP requests and needs no users, roles file or seeded data.
+- It does not generate tests from the lockfile.
+
+Some of what it records comes from a heuristic, and the lockfile names it as such.
+`dynamic` means the view overrides `get_permissions()` and the classes are only known at
+request time. `object_scoping` records whether `get_object`, `get_queryset` and
+`perform_create` are overridden and whether the override reads `request.user` directly; it
+does not follow helper calls and does not show that the query is correct. Decorators are
+detected by reading the view's source, and ones authzlock cannot classify are listed under
+`unknown_decorators`. A green `check` means the lockfile matches the code, not that the
+rules are right. authzlock runs offline and sends nothing anywhere.
+[docs/heuristics-and-limits.md](docs/heuristics-and-limits.md) covers each heuristic and its
+limits.
+
+## Compatibility
+
+| Python | Django 4.2 | Django 5.1 | Django 5.2 | Django 6.0 | Django 6.1 |
+|--------|------------|------------|------------|------------|------------|
+| 3.10 | yes | yes | yes | no | no |
+| 3.11 | yes | yes | yes | no | no |
+| 3.12 | yes | yes | yes | yes | yes |
+| 3.13 | no | yes | yes | yes | yes |
+
+Django REST Framework 3.14 and newer. CI runs every cell above with DRF 3.16 or newer, and
+DRF 3.14 on Django 4.2 with Python 3.12. Routers from `drf-nested-routers` are supported.
+Django 4.2 does not support Python 3.13, and Django 6.0 and newer need Python 3.12.
+
+## Documentation
+
+[docs/index.md](docs/index.md) lists every page. The main ones:
+
+- [docs/cli.md](docs/cli.md): commands, options, output formats and exit codes.
+- [docs/lockfile.md](docs/lockfile.md): the lockfile format and its stability guarantees.
+- [docs/classification.md](docs/classification.md): the rules R1 to R8.
+- [docs/heuristics-and-limits.md](docs/heuristics-and-limits.md): what the heuristics can
+  and cannot tell you, and what a green `check` does not prove.
+- [docs/scenario.md](docs/scenario.md): a pull request that drops `IsOwner`, end to end.
+- [docs/github-action.md](docs/github-action.md): the GitHub Action.
+- [docs/pre-commit.md](docs/pre-commit.md): the pre-commit hooks.
+- [CHANGELOG.md](CHANGELOG.md): changes by release.
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the setup, conventions and how to add a test
+project, [DEVELOPMENT.md](DEVELOPMENT.md) for the project brief and development commands,
+[docs/requirements.md](docs/requirements.md) for the requirements and
+[docs/releasing.md](docs/releasing.md) for the release steps. The backlog lives in Linear and
+is mirrored in [docs/backlog.md](docs/backlog.md). `tests/test_readme.py` runs the quickstart
+above against the `drf_viewsets` test project and checks the lockfile excerpt, the rule table
+and the snippets against their sources; `pytest tests/test_readme.py --update-docs` rewrites
+the `diff` output shown above.
+
+Every pull request and every push to `main` runs `.github/workflows/ci.yml`: a `lint` job
+(ruff), a `typecheck` job (mypy strict) and one `tests (python=X, django=Y)` job per supported
+combination, eleven in all, plus `tests (python=3.12, django=4.2, drf=3.14)` against the
+oldest supported DRF. The jobs are the same nox sessions that `nox` runs locally with no
+arguments. Mark `lint`, `typecheck` and every `tests (...)` job as required status checks on
+`main` in the repository settings so a red check blocks merging.
+
+## License
+
+MIT. See [LICENSE](LICENSE).