permissiondiff 0.1.0__tar.gz → 0.2.0__tar.gz

{permissiondiff-0.1.0 → permissiondiff-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: permissiondiff
-Version: 0.1.0
+Version: 0.2.0
 Summary: Deterministic differential authorization regression testing
 Keywords: authorization,ci,differential-testing,property-based-testing,security-testing
 Author: Abishek Giri
@@ -35,6 +35,7 @@ Description-Content-Type: text/markdown
 > **Prove your code didn't just hand the wrong person the keys.**
 
 [![CI](https://github.com/abishekgiri/permissiondiff/actions/workflows/ci.yml/badge.svg)](https://github.com/abishekgiri/permissiondiff/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/permissiondiff)](https://pypi.org/project/permissiondiff/)
 ![Python](https://img.shields.io/badge/python-3.12%E2%80%933.14-blue)
 ![License](https://img.shields.io/badge/license-Apache%202.0-green)
 [![Ruff](https://img.shields.io/badge/lint-ruff-000000)](https://github.com/astral-sh/ruff)
@@ -57,7 +58,14 @@ interfaces may evolve before 1.0. It supports Python 3.12, 3.13, and 3.14 and is
 
 ## Install
 
-Install the CLI with uv:
+Add the [published package](https://pypi.org/project/permissiondiff/) to an existing uv project:
+
+```bash
+uv add permissiondiff
+uv run permissiondiff --help
+```
+
+For a standalone CLI, install it with uv:
 
 ```bash
 uv tool install permissiondiff
@@ -69,11 +77,9 @@ Or install it in an active virtual environment with pip:
 python -m pip install permissiondiff
 ```
 
-To add PermissionDiff to an existing uv project instead, run `uv add permissiondiff`.
-
 ## Five-minute quickstart
 
-After installation:
+After standalone CLI installation (or use `uv run permissiondiff` inside a uv project):
 
 ```bash
 permissiondiff init demo
@@ -157,6 +163,28 @@ invariants:
 
 The callable receives `(AuthorizationCase, Decision)` and returns `bool` or `InvariantResult`.
 
+## Least-privilege review
+
+`mine` reports the authorizer's effective grant surface — each distinct role × action ×
+resource-type × tenant-relation × ownership pattern it allows — and flags **broad** grants (those
+crossing a tenant boundary or reaching a non-owned resource) for tightening:
+
+```bash
+uv run permissiondiff mine --config permissiondiff.yaml
+```
+
+## Policy engines and agents
+
+Wrap an external policy engine as the authorizer with the adapter toolkit in
+`permissiondiff.adapters` (`from_boolean`, `from_decision`, or `http_authorizer` for OPA-style
+endpoints); runnable example adapters for OPA, OpenFGA, Auth0 FGA, Cedar, and SpiceDB live under
+[`examples/adapters/`](https://github.com/abishekgiri/permissiondiff/tree/main/examples/adapters).
+Adapters make read-only decision calls — point them at a non-production policy instance.
+
+For agent / on-behalf-of principals, declare `delegated_by: [id, ...]` on a subject. PermissionDiff
+enforces the least-privilege intersection rule: a delegated principal allowed where any delegator
+is denied (on the identical case) is a critical privilege-escalation finding.
+
 ## Baseline and diff workflow
 
 Create a baseline on trusted code:
@@ -173,6 +201,13 @@ uv run permissiondiff diff --config permissiondiff.yaml \
   --baseline .permissiondiff/main.json
 ```
 
+Or skip the snapshot file entirely and diff against a git ref — PermissionDiff evaluates the
+baseline authorizer as it existed at that ref in a temporary, auto-removed worktree:
+
+```bash
+uv run permissiondiff diff --config permissiondiff.yaml --git-ref main
+```
+
 Classification is exhaustive:
 
 | Baseline | Candidate | Result |
@@ -212,6 +247,11 @@ The repository's thin composite action invokes the same CLI without duplicating
     baseline: .permissiondiff/main.json
 ```
 
+Check out the calling repository before this step and make sure the baseline is present in CI.
+Use `@v0.2.0` to pin the latest release; `@v0` follows compatible v0 releases. The
+[published-consumer smoke test](https://github.com/abishekgiri/permissiondiff/blob/main/.github/workflows/published-smoke.yml)
+exercises the PyPI package and the remote action in a fresh workspace without a source checkout.
+
 ## Security and limitations
 
 **Only point PermissionDiff at decision logic with no live side effects. Never use an authorizer that issues refunds, deletes data, sends messages, or contacts production.**

{permissiondiff-0.1.0 → permissiondiff-0.2.0}/README.md

@@ -3,6 +3,7 @@
 > **Prove your code didn't just hand the wrong person the keys.**
 
 [![CI](https://github.com/abishekgiri/permissiondiff/actions/workflows/ci.yml/badge.svg)](https://github.com/abishekgiri/permissiondiff/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/permissiondiff)](https://pypi.org/project/permissiondiff/)
 ![Python](https://img.shields.io/badge/python-3.12%E2%80%933.14-blue)
 ![License](https://img.shields.io/badge/license-Apache%202.0-green)
 [![Ruff](https://img.shields.io/badge/lint-ruff-000000)](https://github.com/astral-sh/ruff)
@@ -25,7 +26,14 @@ interfaces may evolve before 1.0. It supports Python 3.12, 3.13, and 3.14 and is
 
 ## Install
 
-Install the CLI with uv:
+Add the [published package](https://pypi.org/project/permissiondiff/) to an existing uv project:
+
+```bash
+uv add permissiondiff
+uv run permissiondiff --help
+```
+
+For a standalone CLI, install it with uv:
 
 ```bash
 uv tool install permissiondiff
@@ -37,11 +45,9 @@ Or install it in an active virtual environment with pip:
 python -m pip install permissiondiff
 ```
 
-To add PermissionDiff to an existing uv project instead, run `uv add permissiondiff`.
-
 ## Five-minute quickstart
 
-After installation:
+After standalone CLI installation (or use `uv run permissiondiff` inside a uv project):
 
 ```bash
 permissiondiff init demo
@@ -125,6 +131,28 @@ invariants:
 
 The callable receives `(AuthorizationCase, Decision)` and returns `bool` or `InvariantResult`.
 
+## Least-privilege review
+
+`mine` reports the authorizer's effective grant surface — each distinct role × action ×
+resource-type × tenant-relation × ownership pattern it allows — and flags **broad** grants (those
+crossing a tenant boundary or reaching a non-owned resource) for tightening:
+
+```bash
+uv run permissiondiff mine --config permissiondiff.yaml
+```
+
+## Policy engines and agents
+
+Wrap an external policy engine as the authorizer with the adapter toolkit in
+`permissiondiff.adapters` (`from_boolean`, `from_decision`, or `http_authorizer` for OPA-style
+endpoints); runnable example adapters for OPA, OpenFGA, Auth0 FGA, Cedar, and SpiceDB live under
+[`examples/adapters/`](https://github.com/abishekgiri/permissiondiff/tree/main/examples/adapters).
+Adapters make read-only decision calls — point them at a non-production policy instance.
+
+For agent / on-behalf-of principals, declare `delegated_by: [id, ...]` on a subject. PermissionDiff
+enforces the least-privilege intersection rule: a delegated principal allowed where any delegator
+is denied (on the identical case) is a critical privilege-escalation finding.
+
 ## Baseline and diff workflow
 
 Create a baseline on trusted code:
@@ -141,6 +169,13 @@ uv run permissiondiff diff --config permissiondiff.yaml \
   --baseline .permissiondiff/main.json
 ```
 
+Or skip the snapshot file entirely and diff against a git ref — PermissionDiff evaluates the
+baseline authorizer as it existed at that ref in a temporary, auto-removed worktree:
+
+```bash
+uv run permissiondiff diff --config permissiondiff.yaml --git-ref main
+```
+
 Classification is exhaustive:
 
 | Baseline | Candidate | Result |
@@ -180,6 +215,11 @@ The repository's thin composite action invokes the same CLI without duplicating
     baseline: .permissiondiff/main.json
 ```
 
+Check out the calling repository before this step and make sure the baseline is present in CI.
+Use `@v0.2.0` to pin the latest release; `@v0` follows compatible v0 releases. The
+[published-consumer smoke test](https://github.com/abishekgiri/permissiondiff/blob/main/.github/workflows/published-smoke.yml)
+exercises the PyPI package and the remote action in a fresh workspace without a source checkout.
+
 ## Security and limitations
 
 **Only point PermissionDiff at decision logic with no live side effects. Never use an authorizer that issues refunds, deletes data, sends messages, or contacts production.**

{permissiondiff-0.1.0 → permissiondiff-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "permissiondiff"
-version = "0.1.0"
+version = "0.2.0"
 description = "Deterministic differential authorization regression testing"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -57,7 +57,7 @@ dev = [
 ]
 
 [build-system]
-requires = ["uv_build>=0.11.1,<0.12.0"]
+requires = ["uv_build>=0.11.1,<0.13.0"]
 build-backend = "uv_build"
 
 [tool.ruff]

{permissiondiff-0.1.0 → permissiondiff-0.2.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "permissiondiff"
-version = "0.1.0"
+version = "0.2.0"
 description = "Deterministic differential authorization regression testing"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -55,7 +55,7 @@ dev = [
 ]
 
 [build-system]
-requires = ["uv_build>=0.11.1,<0.12.0"]
+requires = ["uv_build>=0.11.1,<0.13.0"]
 build-backend = "uv_build"
 
 [tool.ruff]

{permissiondiff-0.1.0 → permissiondiff-0.2.0}/src/permissiondiff/__init__.py

@@ -20,4 +20,4 @@ __all__ = [
     "Subject",
 ]
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"

permissiondiff-0.2.0/src/permissiondiff/adapters/__init__.py

@@ -0,0 +1,68 @@
+"""User-side toolkit for building a PermissionDiff authorizer from an external policy system.
+
+Adapters live **outside** the core engine (the core never imports this package). An adapter turns
+an external authorization decision -- a boolean check from a policy-engine SDK (OpenFGA, SpiceDB,
+Cedar, Auth0 FGA, ...) or a JSON response from an HTTP policy endpoint (OPA, ...) -- into the
+``authorize(subject, action, resource, context) -> Decision`` callable that PermissionDiff
+evaluates.
+
+Adapters make **read-only decision calls only**. As with any authorizer, point them at a
+non-production / test policy instance -- never at production data or anything with side effects.
+
+Most SDK-based engines reduce to a boolean check, so :func:`from_boolean` is usually all you need;
+:func:`from_decision` covers engines that already return an allow/deny verdict object. See
+``examples/adapters/`` for concrete per-engine wrappers.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from permissiondiff.adapters.http import http_authorizer
+from permissiondiff.models import (
+    Action,
+    AuthorizationFunction,
+    Context,
+    Decision,
+    Resource,
+    Subject,
+)
+
+BooleanCheck = Callable[[Subject, Action, Resource, Context], bool]
+
+__all__ = ["BooleanCheck", "from_boolean", "from_decision", "http_authorizer"]
+
+
+def from_boolean(check: BooleanCheck) -> AuthorizationFunction:
+    """Wrap a boolean allow/deny check (the shape of most SDK calls) as an authorizer."""
+
+    def _authorize(
+        subject: Subject, action: Action, resource: Resource, context: Context
+    ) -> Decision:
+        return Decision.ALLOW if check(subject, action, resource, context) else Decision.DENY
+
+    return _authorize
+
+
+def from_decision(
+    check: Callable[[Subject, Action, Resource, Context], bool | Decision],
+) -> AuthorizationFunction:
+    """Wrap a check that returns a bool or an actual ``Decision``.
+
+    Anything that is not a ``Decision`` or a ``bool`` raises ``TypeError`` so a misconfigured
+    adapter surfaces as an explicit evaluation error rather than a silent wrong verdict.
+    """
+
+    def _authorize(
+        subject: Subject, action: Action, resource: Resource, context: Context
+    ) -> Decision:
+        result = check(subject, action, resource, context)
+        if isinstance(result, Decision):
+            return result
+        if isinstance(result, bool):
+            return Decision.ALLOW if result else Decision.DENY
+        raise TypeError(
+            f"adapter check returned {type(result).__name__}, expected bool or Decision"
+        )
+
+    return _authorize

permissiondiff-0.2.0/src/permissiondiff/adapters/http.py

@@ -0,0 +1,57 @@
+"""Generic HTTP-JSON policy adapter (e.g. Open Policy Agent's data API), standard library only.
+
+This is user-side glue that the core engine never imports. It POSTs a JSON request built from the
+case to a policy endpoint and turns the JSON response into a ``Decision``. Point it at a
+non-production policy server; it performs a read-only decision query.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.request
+from collections.abc import Callable
+from typing import Any
+
+from permissiondiff.models import (
+    Action,
+    AuthorizationFunction,
+    Context,
+    Decision,
+    Resource,
+    Subject,
+)
+
+RequestBuilder = Callable[[Subject, Action, Resource, Context], dict[str, Any]]
+AllowedParser = Callable[[Any], bool]
+
+
+def http_authorizer(
+    endpoint: str,
+    *,
+    build_request: RequestBuilder,
+    parse_allowed: AllowedParser,
+    timeout: float = 5.0,
+) -> AuthorizationFunction:
+    """Build an authorizer that queries an HTTP-JSON policy endpoint.
+
+    ``build_request`` maps a case to the JSON body to POST; ``parse_allowed`` maps the decoded
+    JSON response to a boolean allow/deny. Network or parse failures propagate, so PermissionDiff
+    records them as explicit evaluation errors rather than guessing a verdict.
+    """
+
+    def _authorize(
+        subject: Subject, action: Action, resource: Resource, context: Context
+    ) -> Decision:
+        body = json.dumps(build_request(subject, action, resource, context)).encode("utf-8")
+        # The endpoint is operator-supplied configuration, not attacker-controlled case data.
+        request = urllib.request.Request(
+            endpoint,
+            data=body,
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            payload = json.loads(response.read().decode("utf-8"))
+        return Decision.ALLOW if parse_allowed(payload) else Decision.DENY
+
+    return _authorize

{permissiondiff-0.1.0 → permissiondiff-0.2.0}/src/permissiondiff/application.py

@@ -10,12 +10,20 @@ from permissiondiff.config import PermissionDiffConfig
 from permissiondiff.engine import (
     compare_decisions,
     comparison_findings,
+    delegation_findings,
     invariant_findings,
+    mine_grants,
 )
 from permissiondiff.evaluator import evaluate_cases
-from permissiondiff.generator import generate_cases, shrink_findings
+from permissiondiff.generator import generate_cases
 from permissiondiff.invariants import build_invariants
-from permissiondiff.models import AuthorizationCase, CaseEvaluation, ComparisonResult, Finding
+from permissiondiff.models import (
+    AuthorizationCase,
+    CaseEvaluation,
+    ComparisonResult,
+    Finding,
+    Grant,
+)
 from permissiondiff.snapshot import Snapshot, load_snapshot, snapshot_from_evaluations
 
 
@@ -27,6 +35,15 @@ class RunResult:
     findings: tuple[Finding, ...]
 
 
+@dataclass(frozen=True, slots=True)
+class MineResult:
+    """Effective grant surface plus any cases that could not be evaluated."""
+
+    cases_evaluated: int
+    grants: tuple[Grant, ...]
+    errors: tuple[CaseEvaluation, ...]
+
+
 def run_test(
     config: PermissionDiffConfig,
     *,
@@ -38,13 +55,28 @@ def run_test(
     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,
-    )
+    findings = [
+        *invariant_findings(evaluations, invariants),
+        *delegation_findings(evaluations),
+    ]
     return RunResult(len(cases), tuple(findings))
 
 
+def run_mine(
+    config: PermissionDiffConfig,
+    *,
+    workdir: Path,
+    seed: int,
+    max_examples: int | None = None,
+) -> MineResult:
+    """Generate cases, evaluate the authorizer, and mine its effective grant surface."""
+    cases = generate_cases(config, seed=seed, max_examples=max_examples)
+    evaluations = _evaluate(config, cases, workdir)
+    grants = mine_grants(evaluations)
+    errors = tuple(evaluation for evaluation in evaluations if evaluation.error is not None)
+    return MineResult(len(cases), tuple(grants), errors)
+
+
 def create_snapshot(
     config: PermissionDiffConfig,
     *,
@@ -63,9 +95,42 @@ def run_diff(
     *,
     workdir: Path,
     baseline_path: Path,
+) -> RunResult:
+    """Replay every exact baseline case (from a snapshot file) against the candidate."""
+    return _diff_against_snapshot(config, workdir=workdir, snapshot=load_snapshot(baseline_path))
+
+
+def run_git_diff(
+    config: PermissionDiffConfig,
+    *,
+    workdir: Path,
+    ref: str,
+    seed: int,
+    max_examples: int | None = None,
+) -> RunResult:
+    """Diff the candidate against the baseline authorizer as it existed at a git ref.
+
+    The ref is checked out into a temporary detached worktree; the candidate config's domain
+    generates the corpus, which is evaluated against the baseline authorizer code there. The
+    candidate then replays that exact corpus in the working tree.
+    """
+    from permissiondiff.gitref import baseline_worktree, repo_root
+
+    relative = workdir.resolve().relative_to(repo_root(workdir))
+    with baseline_worktree(workdir, ref) as tree:
+        baseline = create_snapshot(
+            config, workdir=tree / relative, seed=seed, max_examples=max_examples
+        )
+    return _diff_against_snapshot(config, workdir=workdir, snapshot=baseline)
+
+
+def _diff_against_snapshot(
+    config: PermissionDiffConfig,
+    *,
+    workdir: Path,
+    snapshot: Snapshot,
 ) -> 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] = []
@@ -79,13 +144,14 @@ def run_diff(
                 )
             )
     invariants = build_invariants(config.invariants, workdir=workdir)
-    findings = shrink_findings(
-        [
-            *comparison_findings(comparisons, minimize=False),
-            *invariant_findings(evaluations, invariants, minimize=False),
-        ],
-        seed=snapshot.seed,
-    )
+    # Comparison and invariant findings never share an equivalence key (their
+    # FindingKind differs), so minimizing each group independently is equivalent
+    # to minimizing the combined list, and it preserves equivalent-case counts.
+    findings = [
+        *comparison_findings(comparisons),
+        *invariant_findings(evaluations, invariants),
+        *delegation_findings(evaluations),
+    ]
     return RunResult(len(cases), tuple(findings))
 
 
@@ -99,4 +165,5 @@ def _evaluate(
         config.authorizer,
         workdir=workdir,
         timeout_seconds=config.execution.timeout_seconds,
+        mode=config.execution.worker,
     )

{permissiondiff-0.1.0 → permissiondiff-0.2.0}/src/permissiondiff/cli.py

@@ -9,14 +9,22 @@ import typer
 from rich.console import Console
 
 from permissiondiff import __version__
-from permissiondiff.application import create_snapshot, run_diff, run_test
+from permissiondiff.application import (
+    create_snapshot,
+    run_diff,
+    run_git_diff,
+    run_mine,
+    run_test,
+)
 from permissiondiff.config import PermissionDiffConfig, load_config
-from permissiondiff.errors import PermissionDiffError
+from permissiondiff.errors import ConfigurationError, EvaluationError, PermissionDiffError
 from permissiondiff.models import Finding
 from permissiondiff.report import (
     assign_finding_ids,
     explain_finding,
     persist_findings,
+    persist_grants,
+    render_grants,
     render_terminal,
     result_exit_code,
 )
@@ -107,6 +115,41 @@ def test_command(
         _unexpected(exc, debug)
 
 
+@app.command()
+def mine(
+    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 grant report path.")
+    ] = Path(".permissiondiff/grants.json"),
+    debug: DEBUG_OPTION = False,
+) -> None:
+    """Report the authorizer's effective grant surface for least-privilege review."""
+    try:
+        loaded = load_config(config)
+        result = run_mine(
+            loaded, workdir=config.resolve().parent, seed=seed, max_examples=max_examples
+        )
+        if result.errors:
+            # Never present a partial grant surface as complete.
+            raise EvaluationError(
+                f"{len(result.errors)} case(s) failed evaluation; "
+                f"first error: {result.errors[0].error}"
+            )
+        grants = list(result.grants)
+        persist_grants(grants, report_path=json_output, cases_evaluated=result.cases_evaluated)
+        render_grants(grants, cases_evaluated=result.cases_evaluated)
+    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.")],
@@ -138,8 +181,18 @@ def snapshot(
 
 @app.command()
 def diff(
-    baseline: Annotated[Path, typer.Option("--baseline", help="Baseline snapshot path.")],
+    baseline: Annotated[
+        Path | None, typer.Option("--baseline", help="Baseline snapshot path.")
+    ] = None,
+    git_ref: Annotated[
+        str | None,
+        typer.Option("--git-ref", help="Baseline git ref to evaluate in a temporary worktree."),
+    ] = None,
     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 (--git-ref).")
+    ] = None,
     json_output: Annotated[
         Path, typer.Option("--json-output", help="Machine-readable report path.")
     ] = Path(".permissiondiff/report.json"),
@@ -148,10 +201,23 @@ def diff(
     ] = Path(".permissiondiff/failures"),
     debug: DEBUG_OPTION = False,
 ) -> None:
-    """Replay the exact baseline corpus against the candidate authorizer."""
+    """Replay the exact baseline corpus against the candidate authorizer.
+
+    Provide exactly one baseline source: --baseline (a snapshot file) or --git-ref (a git ref
+    whose authorizer is evaluated in a temporary worktree).
+    """
     try:
+        if (baseline is None) == (git_ref is None):
+            raise ConfigurationError("provide exactly one of --baseline or --git-ref")
         loaded = load_config(config)
-        result = run_diff(loaded, workdir=config.resolve().parent, baseline_path=baseline)
+        workdir = config.resolve().parent
+        if git_ref is not None:
+            result = run_git_diff(
+                loaded, workdir=workdir, ref=git_ref, seed=seed, max_examples=max_examples
+            )
+        else:
+            assert baseline is not None
+            result = run_diff(loaded, workdir=workdir, baseline_path=baseline)
         _finish_run(loaded, result.cases_evaluated, result.findings, failures_dir, json_output)
     except typer.Exit:
         raise

{permissiondiff-0.1.0 → permissiondiff-0.2.0}/src/permissiondiff/config.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from pathlib import Path
-from typing import Any
+from typing import Any, Literal
 
 import yaml
 from pydantic import BaseModel, ConfigDict, Field, ValidationError, model_validator
@@ -21,6 +21,7 @@ class SubjectConfig(BaseModel):
     tenant: str | None = None
     role: str | None = None
     attributes: dict[str, Any] = Field(default_factory=dict)
+    delegated_by: list[str] = Field(default_factory=list)
 
     def to_domain(self) -> Subject:
         """Convert boundary validation data into the core model."""
@@ -29,6 +30,7 @@ class SubjectConfig(BaseModel):
             tenant=self.tenant,
             role=self.role,
             attributes=self.attributes,
+            delegated_by=tuple(self.delegated_by),
         )
 
 
@@ -104,6 +106,15 @@ class ExecutionConfig(BaseModel):
     model_config = ConfigDict(extra="forbid")
 
     timeout_seconds: float = Field(default=2.0, gt=0, le=300)
+    worker: Literal["persistent", "process_per_case"] = "persistent"
+    """How cases reach the authorizer.
+
+    ``persistent`` (default) imports the authorizer once in a long-lived worker and streams cases
+    over a line-delimited protocol, re-spawning on any crash or timeout so a bad case cannot
+    corrupt later cases -- far faster on large corpora. ``process_per_case`` spawns a fresh
+    interpreter per case (maximum isolation, no shared import state); use it if an authorizer
+    relies on process-global state and cannot tolerate a shared import.
+    """
 
 
 class FailOnConfig(BaseModel):