permissiondiff 0.1.0__py3-none-any.whl

permissiondiff/engine.py

@@ -0,0 +1,155 @@
+"""Pure comparison, invariant evaluation, and finding minimization logic."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable
+from dataclasses import replace
+
+from permissiondiff.invariants import Invariant
+from permissiondiff.models import (
+    AuthorizationCase,
+    CaseEvaluation,
+    ChangeType,
+    ComparisonResult,
+    Decision,
+    Finding,
+    FindingKind,
+    Severity,
+)
+
+
+def classify_change(baseline: Decision, candidate: Decision) -> ChangeType:
+    """Classify one exhaustive pair of authorization decisions."""
+    mapping = {
+        (Decision.DENY, Decision.DENY): ChangeType.UNCHANGED_DENIED,
+        (Decision.ALLOW, Decision.ALLOW): ChangeType.UNCHANGED_ALLOWED,
+        (Decision.DENY, Decision.ALLOW): ChangeType.NEWLY_ALLOWED,
+        (Decision.ALLOW, Decision.DENY): ChangeType.NEWLY_DENIED,
+    }
+    return mapping[(baseline, candidate)]
+
+
+def compare_decisions(
+    case: AuthorizationCase,
+    baseline: Decision,
+    candidate: Decision,
+) -> ComparisonResult:
+    """Compare two decisions for one exact authorization case."""
+    return ComparisonResult(
+        case=case,
+        baseline=baseline,
+        candidate=candidate,
+        change=classify_change(baseline, candidate),
+    )
+
+
+def invariant_findings(
+    evaluations: Iterable[CaseEvaluation],
+    invariants: Iterable[Invariant],
+    *,
+    minimize: bool = True,
+) -> list[Finding]:
+    """Evaluate invariants and return minimized, deduplicated violations."""
+    findings: list[Finding] = []
+    invariant_list = list(invariants)
+    for evaluation in evaluations:
+        if evaluation.decision is None:
+            findings.append(
+                Finding(
+                    kind=FindingKind.EVALUATION_ERROR,
+                    severity=Severity.ERROR,
+                    case=evaluation.case,
+                    message="Authorizer evaluation failed",
+                    error=evaluation.error,
+                )
+            )
+            continue
+        for invariant in invariant_list:
+            result = invariant.evaluate(evaluation.case, evaluation.decision)
+            if not result.passed:
+                findings.append(
+                    Finding(
+                        kind=FindingKind.INVARIANT_VIOLATION,
+                        severity=Severity.CRITICAL,
+                        case=evaluation.case,
+                        message=result.message,
+                        candidate=evaluation.decision,
+                        invariant=result.name,
+                    )
+                )
+    return minimize_findings(findings) if minimize else findings
+
+
+def comparison_findings(
+    comparisons: Iterable[ComparisonResult], *, minimize: bool = True
+) -> list[Finding]:
+    """Convert changed decisions into minimized security findings."""
+    findings: list[Finding] = []
+    for comparison in comparisons:
+        if comparison.change is ChangeType.NEWLY_ALLOWED:
+            findings.append(
+                Finding(
+                    kind=FindingKind.CHANGE,
+                    severity=Severity.CRITICAL,
+                    case=comparison.case,
+                    message="Authorization path is newly allowed",
+                    baseline=comparison.baseline,
+                    candidate=comparison.candidate,
+                    change=comparison.change,
+                )
+            )
+        elif comparison.change is ChangeType.NEWLY_DENIED:
+            findings.append(
+                Finding(
+                    kind=FindingKind.CHANGE,
+                    severity=Severity.WARNING,
+                    case=comparison.case,
+                    message="Authorization path is newly denied",
+                    baseline=comparison.baseline,
+                    candidate=comparison.candidate,
+                    change=comparison.change,
+                )
+            )
+    return minimize_findings(findings) if minimize else findings
+
+
+def minimize_findings(findings: Iterable[Finding]) -> list[Finding]:
+    """Deduplicate equivalent failures and retain the smallest reproduction."""
+    groups: dict[tuple[object, ...], list[Finding]] = {}
+    for finding in findings:
+        groups.setdefault(finding_equivalence_key(finding), []).append(finding)
+
+    minimized: list[Finding] = []
+    for equivalents in groups.values():
+        smallest = min(equivalents, key=finding_case_complexity)
+        minimized.append(replace(smallest, equivalent_cases=len(equivalents)))
+    return sorted(minimized, key=lambda finding: finding.semantic_key)
+
+
+def finding_equivalence_key(finding: Finding) -> tuple[object, ...]:
+    """Group failures with the same security meaning before shrinking."""
+    case = finding.case
+    tenant_relation = (
+        "unknown"
+        if case.subject.tenant is None or case.resource.tenant is None
+        else "same"
+        if case.subject.tenant == case.resource.tenant
+        else "different"
+    )
+    return (
+        finding.kind,
+        finding.change,
+        finding.invariant,
+        finding.error,
+        case.action.name,
+        case.subject.role,
+        case.resource.type,
+        tenant_relation,
+    )
+
+
+def finding_case_complexity(finding: Finding) -> tuple[int, str]:
+    """Order reproductions by compact canonical case representation."""
+    serialized = json.dumps(finding.case.to_dict(), sort_keys=True, separators=(",", ":"))
+    return (len(serialized), serialized)

permissiondiff/errors.py

@@ -0,0 +1,25 @@
+"""Domain-specific exceptions exposed by PermissionDiff."""
+
+
+class PermissionDiffError(Exception):
+    """Base class for expected PermissionDiff failures."""
+
+
+class ConfigurationError(PermissionDiffError):
+    """Raised when configuration is missing or invalid."""
+
+
+class AdapterError(PermissionDiffError):
+    """Raised when an authorizer or custom invariant cannot be loaded."""
+
+
+class EvaluationError(PermissionDiffError):
+    """Raised when authorizer evaluation crashes, hangs, or returns invalid data."""
+
+
+class SnapshotVersionError(PermissionDiffError):
+    """Raised when a snapshot schema is unsupported."""
+
+
+class InvariantDefinitionError(PermissionDiffError):
+    """Raised when an invariant declaration is invalid."""

permissiondiff/evaluator.py

@@ -0,0 +1,86 @@
+"""Parent-side orchestration for subprocess authorizer evaluation."""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+from permissiondiff.models import AuthorizationCase, CaseEvaluation, Decision
+
+
+def evaluate_case(
+    case: AuthorizationCase,
+    authorizer_spec: str,
+    *,
+    workdir: Path,
+    timeout_seconds: float,
+) -> CaseEvaluation:
+    """Evaluate a case in a fresh worker process with a hard timeout."""
+    command = [sys.executable, "-m", "permissiondiff.worker", authorizer_spec]
+    payload = json.dumps(case.to_dict(), sort_keys=True, separators=(",", ":"))
+    environment = os.environ.copy()
+    package_root = str(Path(__file__).resolve().parents[1])
+    inherited_path = environment.get("PYTHONPATH")
+    environment["PYTHONPATH"] = os.pathsep.join(
+        [package_root, inherited_path] if inherited_path else [package_root]
+    )
+    try:
+        completed = subprocess.run(
+            command,
+            input=payload,
+            text=True,
+            capture_output=True,
+            cwd=workdir,
+            env=environment,
+            timeout=timeout_seconds,
+            check=False,
+        )
+    except subprocess.TimeoutExpired:
+        return CaseEvaluation(
+            case=case,
+            error=f"authorizer timed out after {timeout_seconds:g} seconds",
+        )
+    except OSError as exc:
+        return CaseEvaluation(case=case, error=f"could not start authorizer worker: {exc}")
+
+    if completed.returncode != 0:
+        detail = completed.stderr.strip() or completed.stdout.strip() or "no worker output"
+        return CaseEvaluation(
+            case=case,
+            error=f"authorizer worker exited with code {completed.returncode}: {detail}",
+        )
+    try:
+        result = json.loads(completed.stdout)
+    except json.JSONDecodeError:
+        return CaseEvaluation(case=case, error="authorizer worker returned invalid JSON")
+    if not isinstance(result, dict):
+        return CaseEvaluation(case=case, error="authorizer worker returned a non-object result")
+    if isinstance(result.get("error"), str):
+        return CaseEvaluation(case=case, error=result["error"])
+    try:
+        decision = Decision(result["decision"])
+    except (KeyError, TypeError, ValueError):
+        return CaseEvaluation(case=case, error="authorizer worker returned an invalid decision")
+    return CaseEvaluation(case=case, decision=decision)
+
+
+def evaluate_cases(
+    cases: list[AuthorizationCase] | tuple[AuthorizationCase, ...],
+    authorizer_spec: str,
+    *,
+    workdir: Path,
+    timeout_seconds: float,
+) -> list[CaseEvaluation]:
+    """Evaluate cases independently so a crash cannot corrupt parent state."""
+    return [
+        evaluate_case(
+            case,
+            authorizer_spec,
+            workdir=workdir,
+            timeout_seconds=timeout_seconds,
+        )
+        for case in cases
+    ]

permissiondiff/generator.py

@@ -0,0 +1,148 @@
+"""Bounded authorization-case generation over explicit application domains."""
+
+from __future__ import annotations
+
+import random
+from collections.abc import Callable, Iterable
+from dataclasses import replace
+
+from hypothesis import HealthCheck, Phase, find, given, settings
+from hypothesis import seed as hypothesis_seed
+from hypothesis import strategies as st
+from hypothesis.strategies import SearchStrategy
+
+from permissiondiff.config import PermissionDiffConfig
+from permissiondiff.engine import finding_case_complexity, finding_equivalence_key
+from permissiondiff.models import Action, AuthorizationCase, Context, Finding, Resource, Subject
+
+
+def case_strategy(config: PermissionDiffConfig) -> SearchStrategy[AuthorizationCase]:
+    """Build a Hypothesis strategy that combines only declared domain entities."""
+    subjects = [subject.to_domain() for subject in config.subjects]
+    resources = [resource.to_domain() for resource in config.resources]
+    actions = [Action(name) for name in config.actions]
+    amount_strategy: SearchStrategy[int | None]
+    if config.contexts.amounts is None:
+        amount_strategy = st.none()
+    else:
+        amount_domain = config.contexts.amounts
+        boundary_values = amount_domain.interesting_values()
+        amount_strategy = st.one_of(
+            st.sampled_from(boundary_values),
+            st.integers(min_value=amount_domain.min, max_value=amount_domain.max),
+        )
+    return st.builds(
+        AuthorizationCase,
+        subject=st.sampled_from(subjects),
+        action=st.sampled_from(actions),
+        resource=st.sampled_from(resources),
+        context=st.builds(Context, amount=amount_strategy),
+    )
+
+
+def generate_cases(
+    config: PermissionDiffConfig,
+    *,
+    seed: int,
+    max_examples: int | None = None,
+) -> list[AuthorizationCase]:
+    """Generate a stable, bounded corpus with relationship and numeric boundaries."""
+    limit = max_examples or config.generation.max_examples
+    if limit < 1:
+        raise ValueError("max_examples must be positive")
+
+    cases_by_fingerprint: dict[str, AuthorizationCase] = {}
+    coverage_budget = max(1, limit // 2)
+    for case in _coverage_cases(config):
+        cases_by_fingerprint.setdefault(case.fingerprint, case)
+        if len(cases_by_fingerprint) >= coverage_budget:
+            break
+
+    remaining = limit - len(cases_by_fingerprint)
+    if remaining:
+        strategy = case_strategy(config)
+
+        @hypothesis_seed(seed)
+        @settings(
+            max_examples=max(remaining * 3, remaining),
+            database=None,
+            deadline=None,
+            phases=(Phase.generate,),
+            suppress_health_check=(HealthCheck.filter_too_much,),
+        )
+        @given(strategy)
+        def collect(case: AuthorizationCase) -> None:
+            if len(cases_by_fingerprint) < limit:
+                cases_by_fingerprint.setdefault(case.fingerprint, case)
+
+        collect()
+
+    return sorted(cases_by_fingerprint.values(), key=lambda case: case.fingerprint)[:limit]
+
+
+def shrink_findings(findings: Iterable[Finding], *, seed: int) -> list[Finding]:
+    """Use Hypothesis shrinking to select one minimal exact-corpus reproduction."""
+    groups: dict[tuple[object, ...], list[Finding]] = {}
+    for finding in findings:
+        groups.setdefault(finding_equivalence_key(finding), []).append(finding)
+
+    minimized: list[Finding] = []
+    for index, equivalents in enumerate(groups.values()):
+        ordered = sorted(equivalents, key=finding_case_complexity)
+        smallest = find(
+            st.sampled_from(ordered),
+            equivalents.__contains__,
+            settings=settings(
+                max_examples=max(10, len(ordered) * 2),
+                database=None,
+                deadline=None,
+                phases=(Phase.generate, Phase.shrink),
+            ),
+            random=random.Random(seed + index),
+        )
+        minimized.append(replace(smallest, equivalent_cases=len(equivalents)))
+    return sorted(minimized, key=lambda finding: finding.semantic_key)
+
+
+def _coverage_cases(config: PermissionDiffConfig) -> Iterable[AuthorizationCase]:
+    """Yield a lazy spine covering same/cross-tenant and owner relationships."""
+    subjects = [subject.to_domain() for subject in config.subjects]
+    resources = [resource.to_domain() for resource in config.resources]
+    amounts: tuple[int | None, ...]
+    if config.contexts.amounts is None:
+        amounts = (None,)
+    else:
+        amounts = config.contexts.amounts.interesting_values()
+
+    index = 0
+    for action_name in config.actions:
+        for subject in subjects:
+            for resource in _relationship_resources(subject, resources):
+                amount = amounts[index % len(amounts)]
+                index += 1
+                yield AuthorizationCase(
+                    subject=subject,
+                    action=Action(action_name),
+                    resource=resource,
+                    context=Context(amount=amount),
+                )
+
+
+def _relationship_resources(subject: Subject, resources: list[Resource]) -> list[Resource]:
+    selected: list[Resource] = []
+    predicates: tuple[Callable[[Resource], bool], ...] = (
+        lambda resource: resource.owner_id == subject.id,
+        lambda resource: resource.tenant == subject.tenant,
+        lambda resource: (
+            subject.tenant is not None
+            and resource.tenant is not None
+            and resource.tenant != subject.tenant
+        ),
+    )
+    for predicate in predicates:
+        match = next((resource for resource in resources if predicate(resource)), None)
+        if match is not None and match not in selected:
+            selected.append(match)
+    if not selected:
+        selected.append(resources[0])
+    return selected

permissiondiff/invariants.py

@@ -0,0 +1,193 @@
+"""Deterministic built-in and custom authorization invariants."""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Protocol
+
+from permissiondiff.errors import InvariantDefinitionError
+from permissiondiff.loader import load_callable
+from permissiondiff.models import AuthorizationCase, Decision, InvariantResult
+
+
+class Invariant(Protocol):
+    """Interface shared by every deterministic invariant."""
+
+    @property
+    def name(self) -> str: ...
+
+    def evaluate(self, case: AuthorizationCase, decision: Decision) -> InvariantResult: ...
+
+
+@dataclass(frozen=True, slots=True)
+class TenantIsolationInvariant:
+    """Require cross-tenant authorization cases to be denied."""
+
+    name: str = "tenant_isolation"
+
+    def evaluate(self, case: AuthorizationCase, decision: Decision) -> InvariantResult:
+        """Check tenant isolation when both tenants are known and differ."""
+        applies = (
+            case.subject.tenant is not None
+            and case.resource.tenant is not None
+            and case.subject.tenant != case.resource.tenant
+        )
+        passed = not applies or decision is Decision.DENY
+        return InvariantResult(
+            name=self.name,
+            passed=passed,
+            message=(
+                "Cross-tenant access must be denied" if not passed else "Tenant isolation holds"
+            ),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class RoleBoundaryInvariant:
+    """Restrict selected actions to an explicit set of roles."""
+
+    actions: frozenset[str]
+    allowed_roles: frozenset[str]
+    name: str = "role_boundary"
+
+    def evaluate(self, case: AuthorizationCase, decision: Decision) -> InvariantResult:
+        """Require denial when a selected action is attempted by another role."""
+        applies = case.action.name in self.actions and case.subject.role not in self.allowed_roles
+        passed = not applies or decision is Decision.DENY
+        return InvariantResult(
+            name=self.name,
+            passed=passed,
+            message=(
+                f"Role {case.subject.role!r} must not perform {case.action.name!r}"
+                if not passed
+                else "Role boundary holds"
+            ),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class OwnershipInvariant:
+    """Require non-owners to be denied for selected actions."""
+
+    actions: frozenset[str]
+    name: str = "ownership"
+
+    def evaluate(self, case: AuthorizationCase, decision: Decision) -> InvariantResult:
+        """Check ownership only when the resource declares an owner."""
+        applies = (
+            case.action.name in self.actions
+            and case.resource.owner_id is not None
+            and case.subject.id != case.resource.owner_id
+        )
+        passed = not applies or decision is Decision.DENY
+        return InvariantResult(
+            name=self.name,
+            passed=passed,
+            message=(
+                "Non-owner access must be denied" if not passed else "Ownership boundary holds"
+            ),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class CustomInvariant:
+    """Adapter for a user-defined deterministic invariant callable."""
+
+    name: str
+    function: Callable[[AuthorizationCase, Decision], bool | InvariantResult]
+
+    def evaluate(self, case: AuthorizationCase, decision: Decision) -> InvariantResult:
+        """Validate and normalize the custom invariant result."""
+        try:
+            result = self.function(case, decision)
+        except Exception as exc:
+            raise InvariantDefinitionError(
+                f"custom invariant {self.name!r} crashed: {exc}"
+            ) from exc
+        if isinstance(result, InvariantResult):
+            return result
+        if isinstance(result, bool):
+            return InvariantResult(
+                name=self.name,
+                passed=result,
+                message=(
+                    f"Custom invariant {self.name!r} failed"
+                    if not result
+                    else f"Custom invariant {self.name!r} holds"
+                ),
+            )
+        raise InvariantDefinitionError(
+            f"custom invariant {self.name!r} returned {type(result).__name__}, expected bool"
+        )
+
+
+def build_invariants(declarations: list[str | dict[str, Any]], *, workdir: Path) -> list[Invariant]:
+    """Turn validated config declarations into core invariant objects."""
+    invariants: list[Invariant] = []
+    for declaration in declarations:
+        if isinstance(declaration, str):
+            if declaration != "tenant_isolation":
+                raise InvariantDefinitionError(f"unknown invariant {declaration!r}")
+            invariants.append(TenantIsolationInvariant())
+            continue
+        if len(declaration) != 1:
+            raise InvariantDefinitionError("invariant mappings must contain exactly one key")
+        name, raw_options = next(iter(declaration.items()))
+        options = _options(raw_options, name)
+        if name == "tenant_isolation":
+            invariants.append(TenantIsolationInvariant())
+        elif name == "role_boundary":
+            actions = _actions(options, name)
+            roles = options.get("allowed_roles")
+            if (
+                not isinstance(roles, list)
+                or not roles
+                or not all(isinstance(role, str) for role in roles)
+            ):
+                raise InvariantDefinitionError("role_boundary.allowed_roles must be a string list")
+            invariants.append(RoleBoundaryInvariant(actions, frozenset(roles)))
+        elif name == "ownership":
+            invariants.append(OwnershipInvariant(_actions(options, name)))
+        elif name == "custom":
+            spec = options.get("callable")
+            custom_name = options.get("name", spec)
+            if not isinstance(spec, str) or not isinstance(custom_name, str):
+                raise InvariantDefinitionError(
+                    "custom invariant requires callable and optional name"
+                )
+            invariants.append(CustomInvariant(custom_name, _load_from_workdir(spec, workdir)))
+        else:
+            raise InvariantDefinitionError(f"unknown invariant {name!r}")
+    return invariants
+
+
+def _actions(options: dict[str, Any], name: str) -> frozenset[str]:
+    raw = options.get("actions", options.get("action"))
+    if isinstance(raw, str):
+        return frozenset({raw})
+    if isinstance(raw, list) and raw and all(isinstance(action, str) for action in raw):
+        return frozenset(raw)
+    raise InvariantDefinitionError(f"{name}.actions must be a string or non-empty string list")
+
+
+def _options(value: object, name: str) -> dict[str, Any]:
+    if value is None:
+        return {}
+    if not isinstance(value, dict):
+        raise InvariantDefinitionError(f"{name} options must be a mapping")
+    return value
+
+
+def _load_from_workdir(spec: str, workdir: Path) -> Callable[..., Any]:
+    path = str(workdir.resolve())
+    added = path not in sys.path
+    if added:
+        sys.path.insert(0, path)
+    try:
+        return load_callable(spec)
+    finally:
+        if added:
+            sys.path.remove(path)

permissiondiff/loader.py

@@ -0,0 +1,27 @@
+"""Import helpers for user-provided authorizers and custom invariants."""
+
+from __future__ import annotations
+
+import importlib
+from collections.abc import Callable
+from typing import Any, cast
+
+from permissiondiff.errors import AdapterError
+
+
+def load_callable(spec: str) -> Callable[..., Any]:
+    """Load a callable from a strict ``module:attribute`` reference."""
+    module_name, separator, attribute_name = spec.partition(":")
+    if not separator or not module_name or not attribute_name:
+        raise AdapterError(f"invalid callable {spec!r}; expected 'module:function'")
+    try:
+        module = importlib.import_module(module_name)
+    except Exception as exc:
+        raise AdapterError(f"could not import module {module_name!r}: {exc}") from exc
+    try:
+        value = getattr(module, attribute_name)
+    except AttributeError as exc:
+        raise AdapterError(f"module {module_name!r} has no attribute {attribute_name!r}") from exc
+    if not callable(value):
+        raise AdapterError(f"{spec!r} does not reference a callable")
+    return cast("Callable[..., Any]", value)