permissiondiff 0.1.0__py3-none-any.whl

permissiondiff/__init__.py

@@ -0,0 +1,23 @@
+"""Public PermissionDiff API."""
+
+from permissiondiff.models import (
+    Action,
+    AuthorizationCase,
+    ChangeType,
+    Context,
+    Decision,
+    Resource,
+    Subject,
+)
+
+__all__ = [
+    "Action",
+    "AuthorizationCase",
+    "ChangeType",
+    "Context",
+    "Decision",
+    "Resource",
+    "Subject",
+]
+
+__version__ = "0.1.0"

permissiondiff/__main__.py

@@ -0,0 +1,6 @@
+"""Run PermissionDiff as ``python -m permissiondiff``."""
+
+from permissiondiff.cli import app
+
+if __name__ == "__main__":
+    app()

permissiondiff/application.py

@@ -0,0 +1,102 @@
+"""Application orchestration composed from generation, evaluation, and pure logic."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+from permissiondiff.config import PermissionDiffConfig
+from permissiondiff.engine import (
+    compare_decisions,
+    comparison_findings,
+    invariant_findings,
+)
+from permissiondiff.evaluator import evaluate_cases
+from permissiondiff.generator import generate_cases, shrink_findings
+from permissiondiff.invariants import build_invariants
+from permissiondiff.models import AuthorizationCase, CaseEvaluation, ComparisonResult, Finding
+from permissiondiff.snapshot import Snapshot, load_snapshot, snapshot_from_evaluations
+
+
+@dataclass(frozen=True, slots=True)
+class RunResult:
+    """Semantic output shared by human and machine report renderers."""
+
+    cases_evaluated: int
+    findings: tuple[Finding, ...]
+
+
+def run_test(
+    config: PermissionDiffConfig,
+    *,
+    workdir: Path,
+    seed: int,
+    max_examples: int | None = None,
+) -> RunResult:
+    """Generate cases, evaluate the authorizer, and check all invariants."""
+    cases = generate_cases(config, seed=seed, max_examples=max_examples)
+    evaluations = _evaluate(config, cases, workdir)
+    invariants = build_invariants(config.invariants, workdir=workdir)
+    findings = shrink_findings(
+        invariant_findings(evaluations, invariants, minimize=False),
+        seed=seed,
+    )
+    return RunResult(len(cases), tuple(findings))
+
+
+def create_snapshot(
+    config: PermissionDiffConfig,
+    *,
+    workdir: Path,
+    seed: int,
+    max_examples: int | None = None,
+) -> Snapshot:
+    """Generate and evaluate the exact baseline case corpus."""
+    cases = generate_cases(config, seed=seed, max_examples=max_examples)
+    evaluations = _evaluate(config, cases, workdir)
+    return snapshot_from_evaluations(evaluations, seed=seed)
+
+
+def run_diff(
+    config: PermissionDiffConfig,
+    *,
+    workdir: Path,
+    baseline_path: Path,
+) -> RunResult:
+    """Replay every exact baseline case against the candidate authorizer."""
+    snapshot = load_snapshot(baseline_path)
+    cases = [snapshot_case.case for snapshot_case in snapshot.cases]
+    evaluations = _evaluate(config, cases, workdir)
+    comparisons: list[ComparisonResult] = []
+    for snapshot_case, evaluation in zip(snapshot.cases, evaluations, strict=True):
+        if evaluation.decision is not None:
+            comparisons.append(
+                compare_decisions(
+                    snapshot_case.case,
+                    snapshot_case.baseline_decision,
+                    evaluation.decision,
+                )
+            )
+    invariants = build_invariants(config.invariants, workdir=workdir)
+    findings = shrink_findings(
+        [
+            *comparison_findings(comparisons, minimize=False),
+            *invariant_findings(evaluations, invariants, minimize=False),
+        ],
+        seed=snapshot.seed,
+    )
+    return RunResult(len(cases), tuple(findings))
+
+
+def _evaluate(
+    config: PermissionDiffConfig,
+    cases: Sequence[AuthorizationCase],
+    workdir: Path,
+) -> list[CaseEvaluation]:
+    return evaluate_cases(
+        list(cases),
+        config.authorizer,
+        workdir=workdir,
+        timeout_seconds=config.execution.timeout_seconds,
+    )

permissiondiff/cli.py

@@ -0,0 +1,265 @@
+"""Thin Typer command layer for PermissionDiff workflows."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+
+from permissiondiff import __version__
+from permissiondiff.application import create_snapshot, run_diff, run_test
+from permissiondiff.config import PermissionDiffConfig, load_config
+from permissiondiff.errors import PermissionDiffError
+from permissiondiff.models import Finding
+from permissiondiff.report import (
+    assign_finding_ids,
+    explain_finding,
+    persist_findings,
+    render_terminal,
+    result_exit_code,
+)
+from permissiondiff.snapshot import write_snapshot
+
+app = typer.Typer(
+    help="Deterministic differential authorization regression testing.",
+    no_args_is_help=True,
+)
+console = Console()
+
+CONFIG_OPTION = Annotated[
+    Path,
+    typer.Option("--config", "-c", help="PermissionDiff YAML configuration."),
+]
+SEED_OPTION = Annotated[int, typer.Option("--seed", help="Case-corpus seed.")]
+DEBUG_OPTION = Annotated[bool, typer.Option("--debug", help="Show unexpected tracebacks.")]
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"permissiondiff {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: Annotated[
+        bool | None,
+        typer.Option("--version", callback=_version_callback, is_eager=True),
+    ] = None,
+) -> None:
+    """Expose global CLI options."""
+
+
+@app.command()
+def init(
+    directory: Annotated[Path, typer.Argument(help="Directory to initialize.")] = Path("."),
+    force: Annotated[
+        bool,
+        typer.Option("--force", help="Overwrite generated sample files."),
+    ] = False,
+) -> None:
+    """Create a runnable sample config and deliberately vulnerable authorizer."""
+    config_path = directory / "permissiondiff.yaml"
+    authorizer_path = directory / "permissiondiff_authorizer.py"
+    existing = [path for path in (config_path, authorizer_path) if path.exists()]
+    if existing and not force:
+        console.print(f"[red]Configuration error:[/red] {existing[0]} already exists")
+        raise typer.Exit(2)
+    directory.mkdir(parents=True, exist_ok=True)
+    config_path.write_text(_INIT_CONFIG, encoding="utf-8")
+    authorizer_path.write_text(_INIT_AUTHORIZER, encoding="utf-8")
+    console.print(f"Created {config_path} and {authorizer_path}")
+    console.print("Run [bold]permissiondiff test[/bold] to find the sample cross-tenant bug.")
+
+
+@app.command("test")
+def test_command(
+    config: CONFIG_OPTION = Path("permissiondiff.yaml"),
+    seed: SEED_OPTION = 42,
+    max_examples: Annotated[
+        int | None, typer.Option("--max-examples", min=1, help="Override corpus size.")
+    ] = None,
+    json_output: Annotated[
+        Path, typer.Option("--json-output", help="Machine-readable report path.")
+    ] = Path(".permissiondiff/report.json"),
+    failures_dir: Annotated[
+        Path, typer.Option("--failures-dir", help="Minimal reproduction directory.")
+    ] = Path(".permissiondiff/failures"),
+    debug: DEBUG_OPTION = False,
+) -> None:
+    """Generate cases and enforce configured invariants."""
+    try:
+        loaded = load_config(config)
+        result = run_test(
+            loaded,
+            workdir=config.resolve().parent,
+            seed=seed,
+            max_examples=max_examples,
+        )
+        _finish_run(loaded, result.cases_evaluated, result.findings, failures_dir, json_output)
+    except typer.Exit:
+        raise
+    except PermissionDiffError as exc:
+        _fail(exc, debug)
+    except Exception as exc:
+        _unexpected(exc, debug)
+
+
+@app.command()
+def snapshot(
+    output: Annotated[Path, typer.Option("--output", "-o", help="Baseline JSON path.")],
+    config: CONFIG_OPTION = Path("permissiondiff.yaml"),
+    seed: SEED_OPTION = 42,
+    max_examples: Annotated[
+        int | None, typer.Option("--max-examples", min=1, help="Override corpus size.")
+    ] = None,
+    debug: DEBUG_OPTION = False,
+) -> None:
+    """Record exact generated cases and baseline decisions."""
+    try:
+        loaded = load_config(config)
+        baseline = create_snapshot(
+            loaded,
+            workdir=config.resolve().parent,
+            seed=seed,
+            max_examples=max_examples,
+        )
+        write_snapshot(baseline, output)
+        console.print(f"Wrote {len(baseline.cases):,} exact baseline cases to {output}")
+    except typer.Exit:
+        raise
+    except PermissionDiffError as exc:
+        _fail(exc, debug)
+    except Exception as exc:
+        _unexpected(exc, debug)
+
+
+@app.command()
+def diff(
+    baseline: Annotated[Path, typer.Option("--baseline", help="Baseline snapshot path.")],
+    config: CONFIG_OPTION = Path("permissiondiff.yaml"),
+    json_output: Annotated[
+        Path, typer.Option("--json-output", help="Machine-readable report path.")
+    ] = Path(".permissiondiff/report.json"),
+    failures_dir: Annotated[
+        Path, typer.Option("--failures-dir", help="Minimal reproduction directory.")
+    ] = Path(".permissiondiff/failures"),
+    debug: DEBUG_OPTION = False,
+) -> None:
+    """Replay the exact baseline corpus against the candidate authorizer."""
+    try:
+        loaded = load_config(config)
+        result = run_diff(loaded, workdir=config.resolve().parent, baseline_path=baseline)
+        _finish_run(loaded, result.cases_evaluated, result.findings, failures_dir, json_output)
+    except typer.Exit:
+        raise
+    except PermissionDiffError as exc:
+        _fail(exc, debug)
+    except Exception as exc:
+        _unexpected(exc, debug)
+
+
+@app.command()
+def explain(
+    finding_id: Annotated[str, typer.Argument(help="Stable finding ID, e.g. PD-0001")],
+    failures_dir: Annotated[
+        Path, typer.Option("--failures-dir", help="Minimal reproduction directory.")
+    ] = Path(".permissiondiff/failures"),
+) -> None:
+    """Print a persisted minimal reproduction."""
+    path = failures_dir / f"{finding_id}.json"
+    try:
+        console.print_json(explain_finding(path))
+    except (OSError, ValueError) as exc:
+        console.print(f"[red]Configuration error:[/red] could not read {path}: {exc}")
+        raise typer.Exit(2) from exc
+
+
+def _finish_run(
+    config: PermissionDiffConfig,
+    cases_evaluated: int,
+    raw_findings: tuple[Finding, ...],
+    failures_dir: Path,
+    report_path: Path,
+) -> None:
+    findings = assign_finding_ids(raw_findings)
+    persist_findings(
+        findings,
+        failures_dir=failures_dir,
+        report_path=report_path,
+        cases_evaluated=cases_evaluated,
+    )
+    render_terminal(findings, cases_evaluated=cases_evaluated, failures_dir=failures_dir)
+    raise typer.Exit(result_exit_code(findings, config.fail_on))
+
+
+def _fail(error: PermissionDiffError, debug: bool) -> None:
+    if debug:
+        raise error
+    name = type(error).__name__
+    configuration_errors = {
+        "ConfigurationError",
+        "InvariantDefinitionError",
+        "SnapshotVersionError",
+    }
+    exit_code = 2 if name in configuration_errors else 3
+    console.print(f"[red]{name}:[/red] {error}")
+    raise typer.Exit(exit_code) from error
+
+
+def _unexpected(error: Exception, debug: bool) -> None:
+    if debug:
+        raise error
+    console.print(f"[red]Runtime error:[/red] {type(error).__name__}: {error}")
+    raise typer.Exit(3) from error
+
+
+_INIT_CONFIG = """authorizer: permissiondiff_authorizer:authorize
+
+subjects:
+  - {id: alice, tenant: acme, role: support}
+  - {id: bob, tenant: globex, role: support}
+  - {id: root, tenant: system, role: admin}
+
+resources:
+  - {id: invoice-acme, type: invoice, tenant: acme, owner_id: alice}
+  - {id: invoice-globex, type: invoice, tenant: globex, owner_id: bob}
+
+actions: [read_invoice, delete_account]
+
+contexts:
+  amounts: {min: 0, max: 1000, boundaries: [499, 500, 501]}
+
+invariants:
+  - tenant_isolation
+  - role_boundary: {action: delete_account, allowed_roles: [admin]}
+
+fail_on:
+  invariant_violation: true
+  newly_allowed: true
+  newly_denied: false
+
+generation: {max_examples: 32}
+execution: {timeout_seconds: 2}
+"""
+
+_INIT_AUTHORIZER = '''"""Deliberately vulnerable sample authorizer generated by PermissionDiff."""
+
+from permissiondiff import Action, Context, Decision, Resource, Subject
+
+
+def authorize(
+    subject: Subject,
+    action: Action,
+    resource: Resource,
+    context: Context,
+) -> Decision:
+    """Return a decision; this sample intentionally forgets tenant isolation."""
+    if subject.role == "admin":
+        return Decision.ALLOW
+    if subject.role == "support" and action.name == "read_invoice":
+        return Decision.ALLOW  # BUG: resource.tenant is never checked
+    return Decision.DENY
+'''

permissiondiff/config.py

@@ -0,0 +1,163 @@
+"""YAML configuration models and validation."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, ValidationError, model_validator
+
+from permissiondiff.errors import ConfigurationError
+from permissiondiff.models import Resource, Subject
+
+
+class SubjectConfig(BaseModel):
+    """A meaningful subject declared by the application."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    id: str = Field(min_length=1)
+    tenant: str | None = None
+    role: str | None = None
+    attributes: dict[str, Any] = Field(default_factory=dict)
+
+    def to_domain(self) -> Subject:
+        """Convert boundary validation data into the core model."""
+        return Subject(
+            id=self.id,
+            tenant=self.tenant,
+            role=self.role,
+            attributes=self.attributes,
+        )
+
+
+class ResourceConfig(BaseModel):
+    """A meaningful resource declared by the application."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    id: str = Field(min_length=1)
+    type: str = Field(min_length=1)
+    tenant: str | None = None
+    owner_id: str | None = None
+    attributes: dict[str, Any] = Field(default_factory=dict)
+
+    def to_domain(self) -> Resource:
+        """Convert boundary validation data into the core model."""
+        return Resource(
+            id=self.id,
+            type=self.type,
+            tenant=self.tenant,
+            owner_id=self.owner_id,
+            attributes=self.attributes,
+        )
+
+
+class AmountDomain(BaseModel):
+    """Numeric context range plus security-relevant boundary values."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    min: int = 0
+    max: int = 1000
+    boundaries: list[int] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def validate_range(self) -> AmountDomain:
+        """Reject inverted amount ranges."""
+        if self.max < self.min:
+            raise ValueError("amounts.max must be greater than or equal to amounts.min")
+        return self
+
+    def interesting_values(self) -> tuple[int, ...]:
+        """Return sorted, unique values that emphasize range edges."""
+        candidates = {
+            self.min,
+            self.max,
+            self.min + 1 if self.min < self.max else self.min,
+            self.max - 1 if self.min < self.max else self.max,
+            *self.boundaries,
+        }
+        return tuple(sorted(candidates))
+
+
+class ContextDomains(BaseModel):
+    """Explicit context dimensions available to case generation."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    amounts: AmountDomain | None = None
+
+
+class GenerationConfig(BaseModel):
+    """Bounds for deterministic, lazy case-corpus generation."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    max_examples: int = Field(default=64, ge=1, le=10_000)
+
+
+class ExecutionConfig(BaseModel):
+    """Fault-isolation settings for the authorizer worker."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    timeout_seconds: float = Field(default=2.0, gt=0, le=300)
+
+
+class FailOnConfig(BaseModel):
+    """Controls which semantic results fail CI."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    invariant_violation: bool = True
+    newly_allowed: bool = True
+    newly_denied: bool = False
+
+
+class PermissionDiffConfig(BaseModel):
+    """Validated user-facing PermissionDiff configuration."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    authorizer: str = Field(min_length=3)
+    subjects: list[SubjectConfig] = Field(min_length=1)
+    resources: list[ResourceConfig] = Field(min_length=1)
+    actions: list[str] = Field(min_length=1)
+    contexts: ContextDomains = Field(default_factory=ContextDomains)
+    invariants: list[str | dict[str, Any]] = Field(default_factory=list)
+    fail_on: FailOnConfig = Field(default_factory=FailOnConfig)
+    generation: GenerationConfig = Field(default_factory=GenerationConfig)
+    execution: ExecutionConfig = Field(default_factory=ExecutionConfig)
+
+    @model_validator(mode="after")
+    def validate_domain_identity(self) -> PermissionDiffConfig:
+        """Require unique named entities and actions for stable fingerprints."""
+        _ensure_unique([subject.id for subject in self.subjects], "subject ids")
+        _ensure_unique([resource.id for resource in self.resources], "resource ids")
+        _ensure_unique(self.actions, "actions")
+        if any(not action.strip() for action in self.actions):
+            raise ValueError("actions must not be blank")
+        return self
+
+
+def load_config(path: Path) -> PermissionDiffConfig:
+    """Load and validate a PermissionDiff YAML file."""
+    try:
+        raw = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except FileNotFoundError as exc:
+        raise ConfigurationError(f"configuration file not found: {path}") from exc
+    except (OSError, yaml.YAMLError) as exc:
+        raise ConfigurationError(f"could not read configuration {path}: {exc}") from exc
+    if not isinstance(raw, dict):
+        raise ConfigurationError("configuration root must be a YAML mapping")
+    try:
+        return PermissionDiffConfig.model_validate(raw)
+    except ValidationError as exc:
+        raise ConfigurationError(str(exc)) from exc
+
+
+def _ensure_unique(values: list[str], label: str) -> None:
+    if len(values) != len(set(values)):
+        raise ValueError(f"{label} must be unique")