authzlock 0.1.0rc1__py3-none-any.whl

authzlock/__init__.py

@@ -0,0 +1,5 @@
+"""authzlock: an authorization lockfile for Django and Django REST Framework."""
+
+__version__ = "0.1.0rc1"
+
+__all__ = ["__version__"]

authzlock/__main__.py

@@ -0,0 +1,7 @@
+"""`python -m authzlock`: the same CLI as the `authzlock` console script."""
+
+from __future__ import annotations
+
+from authzlock.cli import app
+
+app(prog_name="authzlock")

authzlock/_dump.py

@@ -0,0 +1,29 @@
+"""Print the inventory of the configured Django project as JSON.
+
+Used by the test harness: `python -m authzlock._dump` with `DJANGO_SETTINGS_MODULE` set.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+from authzlock.django_loader import load_project
+from authzlock.errors import EXIT_ERROR, EXIT_OK, AuthzlockError
+from authzlock.extract import extract
+
+
+def main() -> int:
+    try:
+        load_project(None)
+        inventory = extract()
+    except AuthzlockError as exc:
+        print(f"authzlock: {exc}", file=sys.stderr)
+        return EXIT_ERROR
+    json.dump(inventory.to_dict(), sys.stdout, sort_keys=True, indent=2)
+    sys.stdout.write("\n")
+    return EXIT_OK
+
+
+if __name__ == "__main__":
+    sys.exit(main())

authzlock/_github.py

@@ -0,0 +1,201 @@
+"""Helpers the GitHub Action (`action.yml`) runs as `python -m authzlock._github`.
+
+Three subcommands, each reading the markdown report `authzlock diff --format markdown`
+wrote to a file:
+
+- `upsert-comment --repo OWNER/NAME --pr N --body-file PATH` posts the report as a pull
+  request comment, or updates the newest comment that starts with `MARKDOWN_MARKER`, so a
+  pull request keeps one authzlock comment however often it is pushed to. Older marker
+  comments are left as they are. It talks to GitHub only through `gh api`, which reads
+  the token from `GH_TOKEN`.
+- `outputs --report PATH` writes the `summary` and `loosened` step outputs.
+- `gate --report PATH --fail-on-loosened true|false` exits 1 when the flag is true and the
+  summary line counts at least one loosened route.
+
+Exit codes follow the CLI: 0 ok, 1 the gate failed, 2 error. This module is private: its
+interface is the action, not a public API.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import Any
+
+from authzlock.errors import EXIT_ERROR, EXIT_MISMATCH, EXIT_OK
+from authzlock.render import MARKDOWN_MARKER, SUMMARY_LABELS
+
+# GitHub rejects issue comments longer than 65536 characters.
+MAX_BODY = 65536
+HEADING = "### authzlock: access-control changes"
+NO_CHANGES_BODY = f"{MARKDOWN_MARKER}\n{HEADING}\n\nauthzlock found no access-control changes.\n"
+TRUNCATED = "\n\n_The report was truncated to fit in a comment; the full diff is in the job log._\n"
+SUMMARY_RE = re.compile(
+    r"^" + r", ".join(rf"(\d+) {re.escape(label)}" for label in SUMMARY_LABELS) + r"$",
+    re.MULTILINE,
+)
+
+
+class GithubError(Exception):
+    """A `gh` call failed or the report could not be used."""
+
+
+def comment_body(markdown: str) -> str:
+    """The comment text for a report: the report itself, marked and cut to GitHub's limit."""
+    if not markdown.strip():
+        return NO_CHANGES_BODY
+    body = markdown if markdown.startswith(MARKDOWN_MARKER) else f"{MARKDOWN_MARKER}\n{markdown}"
+    if len(body) > MAX_BODY:
+        body = body[: MAX_BODY - len(TRUNCATED)].rstrip() + TRUNCATED
+    return body
+
+
+def parse_summary(markdown: str) -> dict[str, int]:
+    """The five counts of the report's summary line, keyed by label."""
+    matches = SUMMARY_RE.findall(markdown)
+    if len(matches) != 1:
+        raise GithubError(
+            f"expected one summary line in the authzlock report, found {len(matches)}.\n"
+            "Check the output of `authzlock diff` above."
+        )
+    return {label: int(count) for label, count in zip(SUMMARY_LABELS, matches[0], strict=True)}
+
+
+def should_fail(*, fail_on_loosened: bool, loosened: int) -> bool:
+    """True when the job must fail: the flag is set and a route was loosened."""
+    return fail_on_loosened and loosened > 0
+
+
+def find_comment(comments: Sequence[Mapping[str, Any]]) -> int | None:
+    """Id of the newest comment whose body starts with the marker, or None.
+
+    "Starts with" rather than "contains" so that a reply quoting the comment is never
+    taken for it. Newest is by `created_at`, then by id.
+    """
+    marked = [c for c in comments if str(c.get("body", "")).lstrip().startswith(MARKDOWN_MARKER)]
+    if not marked:
+        return None
+    newest = max(marked, key=lambda c: (str(c.get("created_at", "")), int(c["id"])))
+    return int(newest["id"])
+
+
+def _gh_api(args: Sequence[str], payload: Mapping[str, Any] | None = None) -> Any:
+    command = ["gh", "api", *args]
+    try:
+        result = subprocess.run(
+            command,
+            input=json.dumps(payload) if payload is not None else None,
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except FileNotFoundError as exc:
+        raise GithubError(
+            "gh is not installed.\nThe action needs the GitHub CLI, which GitHub-hosted "
+            "runners provide."
+        ) from exc
+    if result.returncode != 0:
+        detail = result.stderr.strip() or result.stdout.strip()
+        raise GithubError(f"`gh api {' '.join(args)}` failed: {detail}")
+    return json.loads(result.stdout) if result.stdout.strip() else None
+
+
+def list_comments(repo: str, pr: int) -> list[dict[str, Any]]:
+    """Every comment on the pull request, across all pages."""
+    pages = _gh_api(["--paginate", "--slurp", f"repos/{repo}/issues/{pr}/comments"])
+    return [comment for page in pages or [] for comment in page]
+
+
+def upsert_comment(repo: str, pr: int, body: str) -> tuple[str, int]:
+    """Update the newest marker comment or create one; returns the action taken and the id."""
+    existing = find_comment(list_comments(repo, pr))
+    if existing is None:
+        created = _gh_api(
+            ["-X", "POST", f"repos/{repo}/issues/{pr}/comments", "--input", "-"], {"body": body}
+        )
+        return "created", int(created["id"])
+    _gh_api(
+        ["-X", "PATCH", f"repos/{repo}/issues/comments/{existing}", "--input", "-"],
+        {"body": body},
+    )
+    return "updated", existing
+
+
+def _read(path: Path) -> str:
+    try:
+        return path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise GithubError(f"cannot read {path}: {exc.strerror or exc}.") from exc
+
+
+def _flag(value: str) -> bool:
+    lowered = value.strip().lower()
+    if lowered not in {"true", "false"}:
+        raise GithubError(f"fail-on-loosened must be true or false, not {value!r}.")
+    return lowered == "true"
+
+
+def _write_outputs(values: Mapping[str, str]) -> None:
+    lines = "".join(f"{key}={value}\n" for key, value in values.items())
+    target = os.environ.get("GITHUB_OUTPUT")
+    if target:
+        with open(target, "a", encoding="utf-8") as fh:
+            fh.write(lines)
+    else:
+        sys.stdout.write(lines)
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="python -m authzlock._github")
+    commands = parser.add_subparsers(dest="command", required=True)
+    upsert = commands.add_parser("upsert-comment", help="Create or update the PR comment.")
+    upsert.add_argument("--repo", required=True)
+    upsert.add_argument("--pr", required=True, type=int)
+    upsert.add_argument("--body-file", required=True, type=Path)
+    outputs = commands.add_parser("outputs", help="Write the summary step outputs.")
+    outputs.add_argument("--report", required=True, type=Path)
+    gate = commands.add_parser("gate", help="Fail when a route is loosened.")
+    gate.add_argument("--report", required=True, type=Path)
+    gate.add_argument("--fail-on-loosened", required=True)
+    return parser
+
+
+def _run(args: argparse.Namespace) -> int:
+    if args.command == "upsert-comment":
+        action, comment_id = upsert_comment(args.repo, args.pr, comment_body(_read(args.body_file)))
+        print(f"authzlock: {action} comment {comment_id} on {args.repo}#{args.pr}")
+        return EXIT_OK
+    counts = parse_summary(_read(args.report))
+    if args.command == "outputs":
+        summary = ", ".join(f"{counts[label]} {label}" for label in SUMMARY_LABELS)
+        _write_outputs({"summary": summary, "loosened": str(counts["loosened"])})
+        return EXIT_OK
+    loosened = counts["loosened"]
+    if should_fail(fail_on_loosened=_flag(args.fail_on_loosened), loosened=loosened):
+        noun = "route" if loosened == 1 else "routes"
+        print(
+            f"::error::authzlock: {loosened} {noun} loosened. Review the access-control "
+            "changes, or set fail-on-loosened: false to report without failing."
+        )
+        return EXIT_MISMATCH
+    print(f"authzlock: {loosened} loosened; not failing")
+    return EXIT_OK
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    try:
+        return _run(args)
+    except GithubError as exc:
+        print(f"authzlock: {exc}", file=sys.stderr)
+        return EXIT_ERROR
+
+
+if __name__ == "__main__":
+    sys.exit(main())

authzlock/classify.py

@@ -0,0 +1,370 @@
+"""Classification of route changes: loosened, tightened or changed-unknown.
+
+Rules R1 to R8 (agreed 2026-09-29, recorded on epic SHA-177) are evaluated in `RULES`
+order and the first rule that returns a `Classification` wins; R8 always matches. Every
+result names its rule and gives a one-line reason that starts with the rule id.
+
+The rules are conservative: a false `loosened` alarm is worse than `changed-unknown`. Only
+the four built-in DRF classes in `BUILTIN_RANK` are ranked. Every other permission entry is
+opaque: custom and third-party classes and the unranked built-ins (`DjangoModelPermissions`
+and the like) are only handled by the explicit removal and addition rules R2 to R4, and
+composed expressions such as `(a.X | b.Y)` and the `dynamic` sentinel are never labelled
+loosened or tightened. `docs/classification.md` lists the rules with one example each.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from authzlock.diff import Diff, FieldChange, RouteChange
+from authzlock.extract.custom import BUILTIN_MODULE
+from authzlock.extract.decorators import NON_LITERAL
+from authzlock.model import Route
+
+Label = Literal["added", "removed", "loosened", "tightened", "changed-unknown"]
+LABELS: tuple[Label, ...] = ("added", "removed", "loosened", "tightened", "changed-unknown")
+
+DYNAMIC = "dynamic"
+
+# DRF built-ins from weakest to strongest. A permission list is an AND, and each class
+# implies every class ranked below it, so a list of ranked classes is as strong as its
+# strongest member. An empty list allows anyone, like AllowAny.
+BUILTIN_RANK: Mapping[str, int] = {
+    f"{BUILTIN_MODULE}.AllowAny": 0,
+    f"{BUILTIN_MODULE}.IsAuthenticatedOrReadOnly": 1,
+    f"{BUILTIN_MODULE}.IsAuthenticated": 2,
+    f"{BUILTIN_MODULE}.IsAdminUser": 3,
+}
+IS_AUTHENTICATED = f"{BUILTIN_MODULE}.IsAuthenticated"
+IS_ADMIN_USER = f"{BUILTIN_MODULE}.IsAdminUser"
+
+# Django auth levels from weakest to strongest; see `_django_auth_level`.
+DJANGO_AUTH_RANK: Mapping[str, int] = {
+    "none": 0,
+    "login_required": 1,
+    "permission_required": 2,
+}
+
+# Fields that say where a rule came from or what a route is called, not who may call it.
+# They may change alongside the fields a rule covers without stopping that rule.
+NEUTRAL_FIELDS = frozenset({"name", "permission_source", "authentication_source"})
+# The django_auth leaves R6 understands; any other django_auth leaf change goes to R8.
+_DJANGO_AUTH_LEAVES = frozenset({"django_auth.login_required", "django_auth.permission_required"})
+
+
+@dataclass(frozen=True)
+class Classification:
+    """A label, the rule that produced it (None for added and removed routes) and why."""
+
+    label: Label
+    rule: str | None
+    reason: str
+
+
+ADDED = Classification("added", None, "route added")
+REMOVED = Classification("removed", None, "route removed")
+
+
+@dataclass(frozen=True)
+class Rule:
+    """One classification rule: an id, a one-line summary for docs and a check that
+    returns a `Classification` when the rule applies and None otherwise."""
+
+    id: str
+    summary: str
+    check: Callable[[RouteChange], Classification | None]
+
+
+@dataclass(frozen=True, kw_only=True)
+class ClassifiedRoute:
+    """One entry of a classified diff. `route` is the current route, or the base route
+    for a removed one; `change` is set for routes present on both sides."""
+
+    key: str
+    route: Route
+    classification: Classification
+    change: RouteChange | None = None
+
+
+def classify(change: RouteChange, rules: tuple[Rule, ...] | None = None) -> Classification:
+    """Classify one changed route with the first rule that applies."""
+    for rule in RULES if rules is None else rules:
+        result = rule.check(change)
+        if result is not None:
+            return result
+    return _r8_anything_else(change)
+
+
+def classify_diff(diff: Diff, rules: tuple[Rule, ...] | None = None) -> tuple[ClassifiedRoute, ...]:
+    """Every added, removed and changed route of `diff` with its label, sorted by route key."""
+    entries = [
+        *(
+            ClassifiedRoute(key=route.key(), route=route, classification=ADDED)
+            for route in diff.added
+        ),
+        *(
+            ClassifiedRoute(key=route.key(), route=route, classification=REMOVED)
+            for route in diff.removed
+        ),
+        *(
+            ClassifiedRoute(
+                key=change.key(),
+                route=change.current,
+                classification=classify(change, rules),
+                change=change,
+            )
+            for change in diff.changed
+        ),
+    ]
+    return tuple(
+        sorted(entries, key=lambda entry: (entry.key, LABELS.index(entry.classification.label)))
+    )
+
+
+# Helpers ---------------------------------------------------------------------------------
+
+
+def _changed(change: RouteChange) -> dict[str, FieldChange]:
+    """Changed fields by name, without the neutral ones."""
+    return {fc.field: fc for fc in change.fields if fc.field not in NEUTRAL_FIELDS}
+
+
+def _only(change: RouteChange, *names: str) -> FieldChange | None:
+    """The change to `names[0]` when it changed and nothing outside `names` did."""
+    changed = _changed(change)
+    if names[0] not in changed or not set(changed) <= set(names):
+        return None
+    return changed[names[0]]
+
+
+def _is_composed(entry: str) -> bool:
+    return entry.startswith("(")
+
+
+def _is_custom(entry: str) -> bool:
+    return entry.rsplit(".", 1)[0] != BUILTIN_MODULE
+
+
+@dataclass(frozen=True)
+class _Split:
+    """A permission list split into ranked built-ins and opaque single classes."""
+
+    ranked: frozenset[str]
+    opaque: frozenset[str]
+
+    @property
+    def strongest(self) -> int:
+        return max((BUILTIN_RANK[entry] for entry in self.ranked), default=0)
+
+
+def _split(value: Any) -> _Split | None:
+    """None when the list is not a plain list of classes (null, dynamic or composed)."""
+    if not isinstance(value, tuple) or any(_is_composed(entry) for entry in value):
+        return None
+    ranked = frozenset(entry for entry in value if entry in BUILTIN_RANK)
+    return _Split(ranked=ranked, opaque=frozenset(value) - ranked)
+
+
+def _permission_sets(change: RouteChange) -> tuple[_Split, _Split] | None:
+    """Old and new permission lists when only they (and neutral fields) changed and both
+    are plain lists of classes."""
+    fc = _only(change, "permission_classes")
+    if fc is None:
+        return None
+    old, new = _split(fc.old), _split(fc.new)
+    if old is None or new is None:
+        return None
+    return old, new
+
+
+def _rank_name(rank: int) -> str:
+    return next(name for name, value in BUILTIN_RANK.items() if value == rank)
+
+
+def _describe(entries: frozenset[str]) -> str:
+    return ", ".join(
+        f"{'custom' if _is_custom(entry) else 'unranked'} class {entry}"
+        for entry in sorted(entries)
+    )
+
+
+# Rules -----------------------------------------------------------------------------------
+
+
+def _r1_builtin_ranking(change: RouteChange) -> Classification | None:
+    sets = _permission_sets(change)
+    if sets is None:
+        return None
+    old, new = sets
+    if old.opaque or new.opaque or old.strongest == new.strongest:
+        return None
+    label: Label = "loosened" if new.strongest < old.strongest else "tightened"
+    return Classification(
+        label,
+        "R1",
+        f"R1: strongest built-in {_rank_name(old.strongest)} -> {_rank_name(new.strongest)}",
+    )
+
+
+def _r2_custom_removed(change: RouteChange) -> Classification | None:
+    sets = _permission_sets(change)
+    if sets is None:
+        return None
+    old, new = sets
+    # Any opaque class left in the new list could make up for the removal, so R2 never
+    # fires then; that is what guarantees a new custom class never yields `loosened`.
+    if not old.opaque or new.opaque:
+        return None
+    ceiling = max(old.strongest, BUILTIN_RANK[IS_AUTHENTICATED])
+    if new.strongest > ceiling:
+        return None
+    if new.ranked <= old.ranked:
+        detail = f"{_describe(old.opaque)} removed"
+    else:
+        detail = f"{_describe(old.opaque)} replaced by built-in {_rank_name(new.strongest)}"
+    return Classification("loosened", "R2", f"R2: {detail}")
+
+
+def _r3_custom_replaced(change: RouteChange) -> Classification | None:
+    sets = _permission_sets(change)
+    if sets is None:
+        return None
+    old, new = sets
+    removed, added = old.opaque - new.opaque, new.opaque - old.opaque
+    if not removed:
+        return None
+    if added:
+        detail = f"{_describe(removed)} replaced by {_describe(added)}"
+    elif not new.opaque and new.strongest == BUILTIN_RANK[IS_ADMIN_USER]:
+        detail = f"{_describe(removed)} replaced by built-in {IS_ADMIN_USER}"
+    else:
+        return None
+    return Classification("changed-unknown", "R3", f"R3: {detail}; cannot rank a custom class")
+
+
+def _r4_custom_added(change: RouteChange) -> Classification | None:
+    sets = _permission_sets(change)
+    if sets is None:
+        return None
+    old, new = sets
+    added = new.opaque - old.opaque
+    kept = old.ranked <= new.ranked and old.opaque <= new.opaque
+    if not added or not kept:
+        return None
+    return Classification(
+        "tightened", "R4", f"R4: {_describe(added)} added to the existing classes"
+    )
+
+
+def _r5_dynamic(change: RouteChange) -> Classification | None:
+    for fc in change.fields:
+        if DYNAMIC in (fc.old, fc.new):
+            detail = f"{fc.field} {_show(fc.old)} -> {_show(fc.new)}"
+            return Classification("changed-unknown", "R5", f"R5: {detail}; dynamic is not ranked")
+    return None
+
+
+def _show(value: Any) -> str:
+    if isinstance(value, tuple):
+        return f"[{', '.join(str(item) for item in value)}]"
+    return "null" if value is None else str(value)
+
+
+def _django_auth_level(auth: Mapping[str, Any]) -> int:
+    if auth.get("permission_required"):
+        return DJANGO_AUTH_RANK["permission_required"]
+    if auth.get("login_required"):
+        return DJANGO_AUTH_RANK["login_required"]
+    return DJANGO_AUTH_RANK["none"]
+
+
+def _r6_django_auth(change: RouteChange) -> Classification | None:
+    changed = _changed(change)
+    if not changed or not set(changed) <= _DJANGO_AUTH_LEAVES:
+        return None
+    old = dict(change.base.django_auth or {})
+    new = dict(change.current.django_auth or {})
+    # A custom test or an unreadable permission_required argument is opaque: leave it to R8.
+    for side in (old, new):
+        if side.get("user_passes_test") or NON_LITERAL in (side.get("unknown_decorators") or ()):
+            return None
+    old_level, new_level = _django_auth_level(old), _django_auth_level(new)
+    old_perms = frozenset(old.get("permission_required") or ())
+    new_perms = frozenset(new.get("permission_required") or ())
+    names = {value: name for name, value in DJANGO_AUTH_RANK.items()}
+    if old_level != new_level:
+        label: Label = "loosened" if new_level < old_level else "tightened"
+        detail = f"{names[old_level]} -> {names[new_level]}"
+    elif new_level == DJANGO_AUTH_RANK["permission_required"] and old_perms < new_perms:
+        label, detail = (
+            "tightened",
+            f"permission_required gained {', '.join(sorted(new_perms - old_perms))}",
+        )
+    elif new_level == DJANGO_AUTH_RANK["permission_required"] and new_perms < old_perms:
+        label, detail = (
+            "loosened",
+            f"permission_required lost {', '.join(sorted(old_perms - new_perms))}",
+        )
+    else:
+        return None
+    return Classification(label, "R6", f"R6: django_auth {detail}")
+
+
+def _r7_methods_gained(change: RouteChange) -> Classification | None:
+    fc = _only(change, "methods", "actions")
+    if fc is None:
+        return None
+    old, new = set(fc.old or ()), set(fc.new or ())
+    if not old < new:
+        return None
+    gained = ", ".join(sorted(new - old))
+    return Classification(
+        "changed-unknown", "R7", f"R7: methods gained {gained} with permissions unchanged"
+    )
+
+
+def _r8_anything_else(change: RouteChange) -> Classification:
+    fields = [fc.field for fc in change.fields]
+    perm = next((fc for fc in change.fields if fc.field == "permission_classes"), None)
+    if perm is not None and any(
+        isinstance(side, tuple) and any(_is_composed(entry) for entry in side)
+        for side in (perm.old, perm.new)
+    ):
+        detail = "composed permission expression is not ranked"
+    else:
+        detail = "no rule covers this change"
+    return Classification("changed-unknown", "R8", f"R8: {detail} ({', '.join(fields)})")
+
+
+RULES: tuple[Rule, ...] = (
+    Rule(
+        "R1",
+        "Both permission lists hold only ranked built-ins: compare the strongest class.",
+        _r1_builtin_ranking,
+    ),
+    Rule(
+        "R2",
+        "Custom class removed, or replaced by a built-in at or below IsAuthenticated: loosened.",
+        _r2_custom_removed,
+    ),
+    Rule(
+        "R3",
+        "Custom class replaced by IsAdminUser or another custom class: changed-unknown.",
+        _r3_custom_replaced,
+    ),
+    Rule("R4", "Custom class added to an otherwise unchanged list: tightened.", _r4_custom_added),
+    Rule("R5", "Either side of a changed field is dynamic: changed-unknown.", _r5_dynamic),
+    Rule(
+        "R6",
+        "login_required or permission_required gained: tightened; the reverse: loosened.",
+        _r6_django_auth,
+    ),
+    Rule(
+        "R7",
+        "Methods gained entries with permissions unchanged: changed-unknown.",
+        _r7_methods_gained,
+    ),
+    Rule("R8", "Anything else: changed-unknown.", _r8_anything_else),
+)