permissiondiff 0.1.0__py3-none-any.whl

permissiondiff/models.py

@@ -0,0 +1,278 @@
+"""Typed domain vocabulary for authorization evaluation and reporting."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field, replace
+from enum import StrEnum
+from typing import Any, Protocol
+
+JsonObject = dict[str, Any]
+
+
+class Decision(StrEnum):
+    """The only two valid authorization verdicts."""
+
+    ALLOW = "ALLOW"
+    DENY = "DENY"
+
+
+class ChangeType(StrEnum):
+    """Classification of one baseline/candidate decision pair."""
+
+    UNCHANGED_DENIED = "unchanged_denied"
+    UNCHANGED_ALLOWED = "unchanged_allowed"
+    NEWLY_ALLOWED = "newly_allowed"
+    NEWLY_DENIED = "newly_denied"
+
+
+class FindingKind(StrEnum):
+    """Kinds of actionable results PermissionDiff persists."""
+
+    CHANGE = "change"
+    INVARIANT_VIOLATION = "invariant_violation"
+    EVALUATION_ERROR = "evaluation_error"
+
+
+class Severity(StrEnum):
+    """Human-facing finding severity."""
+
+    CRITICAL = "critical"
+    WARNING = "warning"
+    ERROR = "error"
+
+
+@dataclass(frozen=True, slots=True)
+class Subject:
+    """A principal whose authority is being tested."""
+
+    id: str
+    tenant: str | None = None
+    role: str | None = None
+    attributes: JsonObject = field(default_factory=dict)
+
+    def to_dict(self) -> JsonObject:
+        """Return a JSON-compatible representation."""
+        return {
+            "id": self.id,
+            "tenant": self.tenant,
+            "role": self.role,
+            "attributes": self.attributes,
+        }
+
+    @classmethod
+    def from_dict(cls, data: JsonObject) -> Subject:
+        """Build a subject from serialized data."""
+        return cls(
+            id=str(data["id"]),
+            tenant=_optional_string(data.get("tenant")),
+            role=_optional_string(data.get("role")),
+            attributes=dict(data.get("attributes", {})),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class Resource:
+    """An application object an action may target."""
+
+    id: str
+    type: str
+    tenant: str | None = None
+    owner_id: str | None = None
+    attributes: JsonObject = field(default_factory=dict)
+
+    def to_dict(self) -> JsonObject:
+        """Return a JSON-compatible representation."""
+        return {
+            "id": self.id,
+            "type": self.type,
+            "tenant": self.tenant,
+            "owner_id": self.owner_id,
+            "attributes": self.attributes,
+        }
+
+    @classmethod
+    def from_dict(cls, data: JsonObject) -> Resource:
+        """Build a resource from serialized data."""
+        return cls(
+            id=str(data["id"]),
+            type=str(data["type"]),
+            tenant=_optional_string(data.get("tenant")),
+            owner_id=_optional_string(data.get("owner_id")),
+            attributes=dict(data.get("attributes", {})),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class Action:
+    """A named operation a subject may attempt."""
+
+    name: str
+
+    def __str__(self) -> str:
+        """Return the action name for concise authorizer code."""
+        return self.name
+
+
+@dataclass(frozen=True, slots=True)
+class Context:
+    """Additional deterministic inputs to an authorization decision."""
+
+    amount: int | float | None = None
+    attributes: JsonObject = field(default_factory=dict)
+
+    def to_dict(self) -> JsonObject:
+        """Return a JSON-compatible representation."""
+        return {"amount": self.amount, "attributes": self.attributes}
+
+    @classmethod
+    def from_dict(cls, data: JsonObject) -> Context:
+        """Build context from serialized data."""
+        amount = data.get("amount")
+        if amount is not None and not isinstance(amount, int | float):
+            raise ValueError("context.amount must be numeric or null")
+        return cls(amount=amount, attributes=dict(data.get("attributes", {})))
+
+
+@dataclass(frozen=True, slots=True)
+class AuthorizationCase:
+    """One complete, replayable authorization input."""
+
+    subject: Subject
+    action: Action
+    resource: Resource
+    context: Context = field(default_factory=Context)
+
+    def to_dict(self) -> JsonObject:
+        """Return canonical semantic case data."""
+        return {
+            "subject": self.subject.to_dict(),
+            "action": self.action.name,
+            "resource": self.resource.to_dict(),
+            "context": self.context.to_dict(),
+        }
+
+    @classmethod
+    def from_dict(cls, data: JsonObject) -> AuthorizationCase:
+        """Recreate an authorization case from serialized data."""
+        return cls(
+            subject=Subject.from_dict(_object(data["subject"])),
+            action=Action(str(data["action"])),
+            resource=Resource.from_dict(_object(data["resource"])),
+            context=Context.from_dict(_object(data.get("context", {}))),
+        )
+
+    @property
+    def fingerprint(self) -> str:
+        """Return a stable digest containing only semantic case fields."""
+        payload = json.dumps(self.to_dict(), sort_keys=True, separators=(",", ":"))
+        return hashlib.sha256(payload.encode()).hexdigest()
+
+
+class AuthorizationFunction(Protocol):
+    """Interface implemented by user authorization functions."""
+
+    def __call__(
+        self,
+        subject: Subject,
+        action: Action,
+        resource: Resource,
+        context: Context,
+    ) -> Decision: ...
+
+
+@dataclass(frozen=True, slots=True)
+class CaseEvaluation:
+    """A decision or explicit evaluation error for one case."""
+
+    case: AuthorizationCase
+    decision: Decision | None = None
+    error: str | None = None
+
+    def __post_init__(self) -> None:
+        """Require exactly one of decision and error."""
+        if (self.decision is None) == (self.error is None):
+            raise ValueError("evaluation must contain exactly one of decision or error")
+
+
+@dataclass(frozen=True, slots=True)
+class ComparisonResult:
+    """One baseline/candidate comparison over the same exact case."""
+
+    case: AuthorizationCase
+    baseline: Decision
+    candidate: Decision
+    change: ChangeType
+
+
+@dataclass(frozen=True, slots=True)
+class InvariantResult:
+    """Result of evaluating a deterministic invariant."""
+
+    name: str
+    passed: bool
+    message: str
+
+
+@dataclass(frozen=True, slots=True)
+class Finding:
+    """A stable, replayable issue found by evaluation or comparison."""
+
+    kind: FindingKind
+    severity: Severity
+    case: AuthorizationCase
+    message: str
+    finding_id: str = ""
+    baseline: Decision | None = None
+    candidate: Decision | None = None
+    change: ChangeType | None = None
+    invariant: str | None = None
+    error: str | None = None
+    equivalent_cases: int = 1
+
+    @property
+    def semantic_key(self) -> str:
+        """Return stable finding identity independent of display ID."""
+        payload = {
+            "kind": self.kind.value,
+            "case_fingerprint": self.case.fingerprint,
+            "baseline": self.baseline.value if self.baseline else None,
+            "candidate": self.candidate.value if self.candidate else None,
+            "change": self.change.value if self.change else None,
+            "invariant": self.invariant,
+            "error": self.error,
+        }
+        return json.dumps(payload, sort_keys=True, separators=(",", ":"))
+
+    def with_id(self, finding_id: str) -> Finding:
+        """Return this immutable finding with its stable display ID."""
+        return replace(self, finding_id=finding_id)
+
+    def to_dict(self) -> JsonObject:
+        """Return a machine-readable finding and reproduction."""
+        return {
+            "schema_version": 1,
+            "finding_id": self.finding_id,
+            "kind": self.kind.value,
+            "severity": self.severity.value,
+            "message": self.message,
+            "invariant": self.invariant,
+            "change": self.change.value if self.change else None,
+            "baseline": self.baseline.value if self.baseline else None,
+            "candidate": self.candidate.value if self.candidate else None,
+            "error": self.error,
+            "equivalent_cases": self.equivalent_cases,
+            "case_fingerprint": self.case.fingerprint,
+            "case": self.case.to_dict(),
+        }
+
+
+def _object(value: object) -> JsonObject:
+    if not isinstance(value, dict):
+        raise ValueError("expected an object")
+    return value
+
+
+def _optional_string(value: object) -> str | None:
+    return None if value is None else str(value)

permissiondiff/py.typed

@@ -0,0 +1 @@
+

permissiondiff/report.py

@@ -0,0 +1,121 @@
+"""Human presentation and canonical JSON persistence for findings."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from rich.console import Console
+from rich.table import Table
+
+from permissiondiff.config import FailOnConfig
+from permissiondiff.models import ChangeType, Finding, FindingKind, JsonObject, Severity
+
+REPORT_SCHEMA_VERSION = 1
+
+
+def assign_finding_ids(findings: list[Finding] | tuple[Finding, ...]) -> list[Finding]:
+    """Assign stable sequential IDs after deterministic semantic sorting."""
+    ordered = sorted(findings, key=lambda finding: finding.semantic_key)
+    return [finding.with_id(f"PD-{index:04d}") for index, finding in enumerate(ordered, 1)]
+
+
+def persist_findings(
+    findings: list[Finding],
+    *,
+    failures_dir: Path,
+    report_path: Path,
+    cases_evaluated: int,
+) -> None:
+    """Write canonical report JSON and one exact reproduction per finding."""
+    failures_dir.mkdir(parents=True, exist_ok=True)
+    for stale in failures_dir.glob("PD-*.json"):
+        stale.unlink()
+    for finding in findings:
+        destination = failures_dir / f"{finding.finding_id}.json"
+        _write_json(destination, finding.to_dict())
+    report: JsonObject = {
+        "schema_version": REPORT_SCHEMA_VERSION,
+        "cases_evaluated": cases_evaluated,
+        "finding_count": len(findings),
+        "findings": [finding.to_dict() for finding in findings],
+    }
+    _write_json(report_path, report)
+
+
+def render_terminal(
+    findings: list[Finding],
+    *,
+    cases_evaluated: int,
+    failures_dir: Path,
+    console: Console | None = None,
+) -> None:
+    """Render concise actionable findings without affecting semantics."""
+    output = console or Console()
+    output.print(f"[bold]PermissionDiff[/bold] evaluated {cases_evaluated:,} exact cases")
+    if not findings:
+        output.print("[green]PASS[/green] No authorization changes or invariant violations found.")
+        return
+
+    table = Table(show_header=True, header_style="bold")
+    table.add_column("ID")
+    table.add_column("Severity")
+    table.add_column("Result")
+    table.add_column("Minimal reproduction")
+    for finding in findings:
+        case = finding.case
+        path = failures_dir / f"{finding.finding_id}.json"
+        summary = (
+            f"{case.subject.role or case.subject.id}({case.subject.tenant or '-'}) "
+            f"→ {case.action.name} → {case.resource.type}({case.resource.tenant or '-'})"
+        )
+        decisions = ""
+        if finding.baseline and finding.candidate:
+            decisions = f" [{finding.baseline.value} → {finding.candidate.value}]"
+        elif finding.candidate:
+            decisions = f" [actual: {finding.candidate.value}]"
+        equivalent = (
+            f" ({finding.equivalent_cases} equivalent cases)"
+            if finding.equivalent_cases > 1
+            else ""
+        )
+        table.add_row(
+            finding.finding_id,
+            _severity_label(finding.severity),
+            f"{finding.message}\n{summary}{decisions}{equivalent}",
+            str(path),
+        )
+    output.print(table)
+
+
+def result_exit_code(findings: list[Finding], fail_on: FailOnConfig) -> int:
+    """Apply the documented CI exit-code contract."""
+    if any(finding.kind is FindingKind.EVALUATION_ERROR for finding in findings):
+        return 3
+    for finding in findings:
+        if finding.kind is FindingKind.INVARIANT_VIOLATION and fail_on.invariant_violation:
+            return 1
+        if finding.change is ChangeType.NEWLY_ALLOWED and fail_on.newly_allowed:
+            return 1
+        if finding.change is ChangeType.NEWLY_DENIED and fail_on.newly_denied:
+            return 1
+    return 0
+
+
+def explain_finding(path: Path) -> str:
+    """Return a persisted reproduction as readable canonical JSON."""
+    return json.dumps(json.loads(path.read_text(encoding="utf-8")), indent=2, sort_keys=True)
+
+
+def _write_json(path: Path, payload: JsonObject) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+
+def _severity_label(severity: Severity) -> str:
+    colors = {
+        Severity.CRITICAL: "[bold red]CRITICAL[/bold red]",
+        Severity.WARNING: "[yellow]WARNING[/yellow]",
+        Severity.ERROR: "[bold magenta]ERROR[/bold magenta]",
+    }
+    return colors[severity]

permissiondiff/snapshot.py

@@ -0,0 +1,138 @@
+"""Versioned, canonical snapshots containing exact cases and decisions."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from permissiondiff import __version__
+from permissiondiff.errors import EvaluationError, SnapshotVersionError
+from permissiondiff.models import AuthorizationCase, CaseEvaluation, Decision, JsonObject
+
+SNAPSHOT_SCHEMA_VERSION = 1
+
+
+@dataclass(frozen=True, slots=True)
+class SnapshotCase:
+    """An exact baseline input and its decision."""
+
+    case: AuthorizationCase
+    baseline_decision: Decision
+
+    def to_dict(self) -> JsonObject:
+        """Serialize the exact case, decision, and stable fingerprint."""
+        return {
+            "fingerprint": self.case.fingerprint,
+            "case": self.case.to_dict(),
+            "baseline_decision": self.baseline_decision.value,
+        }
+
+    @classmethod
+    def from_dict(cls, raw: JsonObject) -> SnapshotCase:
+        """Load and integrity-check one stored baseline case."""
+        try:
+            case = AuthorizationCase.from_dict(_object(raw["case"]))
+            decision = Decision(raw["baseline_decision"])
+            fingerprint = str(raw["fingerprint"])
+        except (KeyError, TypeError, ValueError) as exc:
+            raise SnapshotVersionError(f"invalid snapshot case: {exc}") from exc
+        if fingerprint != case.fingerprint:
+            raise SnapshotVersionError("snapshot case fingerprint does not match case content")
+        return cls(case=case, baseline_decision=decision)
+
+
+@dataclass(frozen=True, slots=True)
+class Snapshot:
+    """A complete, versioned baseline corpus."""
+
+    seed: int
+    cases: tuple[SnapshotCase, ...]
+    permissiondiff_version: str = __version__
+    schema_version: int = SNAPSHOT_SCHEMA_VERSION
+
+    def to_dict(self) -> JsonObject:
+        """Return canonical snapshot data with stable case ordering."""
+        return {
+            "schema_version": self.schema_version,
+            "permissiondiff_version": self.permissiondiff_version,
+            "seed": self.seed,
+            "cases": [case.to_dict() for case in sorted(self.cases, key=_fingerprint)],
+        }
+
+    @classmethod
+    def from_dict(cls, raw: JsonObject) -> Snapshot:
+        """Load a supported snapshot without reinterpreting its schema."""
+        schema_version = raw.get("schema_version")
+        if schema_version != SNAPSHOT_SCHEMA_VERSION:
+            raise SnapshotVersionError(
+                f"unsupported snapshot schema {schema_version!r}; "
+                f"expected {SNAPSHOT_SCHEMA_VERSION}"
+            )
+        raw_cases = raw.get("cases")
+        if not isinstance(raw_cases, list):
+            raise SnapshotVersionError("snapshot cases must be a list")
+        try:
+            return cls(
+                schema_version=SNAPSHOT_SCHEMA_VERSION,
+                permissiondiff_version=str(raw["permissiondiff_version"]),
+                seed=int(raw["seed"]),
+                cases=tuple(SnapshotCase.from_dict(_object(case)) for case in raw_cases),
+            )
+        except (KeyError, TypeError, ValueError) as exc:
+            raise SnapshotVersionError(f"invalid snapshot: {exc}") from exc
+
+
+def snapshot_from_evaluations(evaluations: list[CaseEvaluation], *, seed: int) -> Snapshot:
+    """Create a baseline only when every exact case has a decision."""
+    failures = [evaluation for evaluation in evaluations if evaluation.error is not None]
+    if failures:
+        raise EvaluationError(
+            f"cannot create snapshot: {len(failures)} case(s) failed evaluation; "
+            f"first error: {failures[0].error}"
+        )
+    return Snapshot(
+        seed=seed,
+        cases=tuple(
+            SnapshotCase(evaluation.case, _decision(evaluation)) for evaluation in evaluations
+        ),
+    )
+
+
+def write_snapshot(snapshot: Snapshot, path: Path) -> None:
+    """Write canonical, diff-friendly JSON with no volatile fields."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        json.dumps(snapshot.to_dict(), indent=2, sort_keys=True) + "\n",
+        encoding="utf-8",
+    )
+
+
+def load_snapshot(path: Path) -> Snapshot:
+    """Read a versioned snapshot and validate its exact-case fingerprints."""
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError as exc:
+        raise SnapshotVersionError(f"snapshot not found: {path}") from exc
+    except (OSError, json.JSONDecodeError) as exc:
+        raise SnapshotVersionError(f"could not read snapshot {path}: {exc}") from exc
+    if not isinstance(raw, dict):
+        raise SnapshotVersionError("snapshot root must be an object")
+    return Snapshot.from_dict(raw)
+
+
+def _decision(evaluation: CaseEvaluation) -> Decision:
+    if evaluation.decision is None:
+        raise EvaluationError(evaluation.error or "missing decision")
+    return evaluation.decision
+
+
+def _fingerprint(snapshot_case: SnapshotCase) -> str:
+    return snapshot_case.case.fingerprint
+
+
+def _object(value: object) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise SnapshotVersionError("expected a JSON object")
+    return value

permissiondiff/worker.py

@@ -0,0 +1,48 @@
+"""One-case subprocess worker for fault-isolated authorizer evaluation."""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+from permissiondiff.loader import load_callable
+from permissiondiff.models import AuthorizationCase, Decision
+
+
+def evaluate_payload(authorizer_spec: str, payload: dict[str, Any]) -> dict[str, str]:
+    """Evaluate one serialized case and return a serialized result."""
+    try:
+        authorizer = load_callable(authorizer_spec)
+        case = AuthorizationCase.from_dict(payload)
+        result = authorizer(case.subject, case.action, case.resource, case.context)
+        if not isinstance(result, Decision):
+            return {
+                "error": (
+                    "authorizer returned an invalid value; expected "
+                    f"Decision.ALLOW or Decision.DENY, got {result!r}"
+                )
+            }
+        return {"decision": result.value}
+    except BaseException as exc:  # worker must report SystemExit and user exceptions
+        return {"error": f"{type(exc).__name__}: {exc}"}
+
+
+def main() -> int:
+    """Read one case from stdin and write exactly one JSON result."""
+    if len(sys.argv) != 2:
+        print(json.dumps({"error": "worker requires one authorizer spec"}))
+        return 2
+    try:
+        payload = json.loads(sys.stdin.read())
+        if not isinstance(payload, dict):
+            raise ValueError("worker input must be an object")
+        result = evaluate_payload(sys.argv[1], payload)
+    except BaseException as exc:
+        result = {"error": f"worker input error: {type(exc).__name__}: {exc}"}
+    print(json.dumps(result, sort_keys=True, separators=(",", ":")))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())