ctrlrun 0.1.0__py3-none-any.whl

ctrlrun/policy.py

@@ -0,0 +1,389 @@
+"""Policy loading and rule evaluation to a Decision. Build-list item 2; SPEC-v0.1 §3."""
+
+from __future__ import annotations
+
+import logging
+import operator
+import os
+from collections.abc import Callable, Iterable, Mapping
+from dataclasses import dataclass
+from enum import StrEnum
+from pathlib import Path
+from types import MappingProxyType
+from typing import Any, Final
+
+import yaml
+
+from .action import Action
+from .errors import PolicyError
+
+POLICY_SCHEMA: Final = "ctrlrun.policy/v1"
+CONFIG_ENV_VAR: Final = "CTRLRUN_CONFIG"
+DEFAULT_POLICY_FILENAME: Final = "ctrlrun.yaml"
+
+#: Reasons attached to an Evaluation that no rule produced.
+UNKNOWN_ACTION: Final = "unknown_action"
+NO_MATCHING_RULE: Final = "no_matching_rule"
+BARE_DECISION: Final = "decision"
+
+_LOG = logging.getLogger(__name__)
+
+_NUMERIC_COMPARE: Final[Mapping[str, Callable[[int, int], bool]]] = {
+    "lt": operator.lt,
+    "lte": operator.le,
+    "gt": operator.gt,
+    "gte": operator.ge,
+}
+_OPERATORS: Final = ("eq", "neq", "in", *_NUMERIC_COMPARE)
+#: Longest first, so `amount_neq` reads as (amount, neq) and never as (amount_n, eq).
+_OPERATORS_BY_LENGTH: Final = tuple(sorted(_OPERATORS, key=len, reverse=True))
+
+_TOP_LEVEL_KEYS: Final = frozenset({"schema", "actions"})
+_ENTRY_KEYS: Final = frozenset({"decision", "rules"})
+_RULE_KEYS: Final = frozenset({"when", "decision"})
+
+#: Names of `Action` fields (SPEC-v0.1 §2.1), which a condition cannot address: conditions
+#: see the action's *arguments* and nothing else (§3.2). Writing one reads like it scopes a
+#: rule — `when: { environment_eq: production }` — and matches nothing, so it is refused at
+#: load. Same fail-closed reading as `{resource}` in §5.1: two candidate meanings for one
+#: name, so make the author rename rather than silently pick one.
+RESERVED_ARGUMENTS: Final = frozenset(
+    {"action_id", "agent", "environment", "principal", "resource", "user"}
+)
+
+
+class Decision(StrEnum):
+    """What may happen to an action: exactly three outcomes in v0.1 (SPEC-v0.1 §3.3).
+
+    `StrEnum`, so a member renders as its value in receipts and CLI output (SPEC-v0.1 §6.1).
+    """
+
+    ALLOW = "allow"
+    APPROVE = "approve"
+    DENY = "deny"
+
+
+@dataclass(frozen=True)
+class Evaluation:
+    """A decision and the reason it was reached, e.g. `rule[1]` or `unknown_action`."""
+
+    decision: Decision
+    reason: str
+
+
+def _is_int(value: object) -> bool:
+    """True for a real int. `bool` subclasses int in Python; SPEC-v0.1 §3.2 excludes it."""
+    return isinstance(value, int) and not isinstance(value, bool)
+
+
+def _type_name(value: object) -> str:
+    return type(value).__name__
+
+
+def _equal(value: object, operand: object) -> bool:
+    """Type-strict equality: `True` never equals `1`, and a list never equals a scalar.
+
+    SPEC: §3.2 — equality is type-strict and applies recursively inside containers.
+    Canonical arguments distinguish bool from int (§2.3), so conditions must too, or a
+    policy written for `1` would match `True`.
+    """
+    if isinstance(value, bool) or isinstance(operand, bool):
+        return value is operand
+    if isinstance(value, Mapping) and isinstance(operand, Mapping):
+        return value.keys() == operand.keys() and all(
+            _equal(value[key], operand[key]) for key in value
+        )
+    if isinstance(value, list | tuple) and isinstance(operand, list | tuple):
+        return len(value) == len(operand) and all(
+            _equal(item, other) for item, other in zip(value, operand, strict=True)
+        )
+    if _is_container(value) or _is_container(operand):
+        return False
+    return bool(value == operand)
+
+
+def _is_container(value: object) -> bool:
+    return isinstance(value, Mapping | list | tuple)
+
+
+@dataclass(frozen=True)
+class _Condition:
+    key: str
+    argument: str
+    op: str
+    operand: Any
+
+    def matches(self, action_name: str, arguments: Mapping[str, Any]) -> bool:
+        if self.argument not in arguments:
+            # SPEC §3.2 — still false, never an error, but never silent either. Defaults are
+            # applied when a call is bound (§8), so an argument is either always present or
+            # never: an absent one is a typo, and silence let a mistyped rule disappear into
+            # a catch-all below it.
+            _LOG.warning(
+                "%s: condition %s ignored: the action has no argument %r (it has: %s)",
+                action_name,
+                self.key,
+                self.argument,
+                ", ".join(sorted(arguments)) or "none",
+            )
+            return False
+        value = arguments[self.argument]
+        if self.op == "eq":
+            return _equal(value, self.operand)
+        if self.op == "neq":
+            return not _equal(value, self.operand)
+        if self.op == "in":
+            return any(_equal(value, item) for item in self.operand)
+        if not _is_int(value):
+            _LOG.warning(
+                "%s: condition %s ignored: argument %r is %s, not int",
+                action_name,
+                self.key,
+                self.argument,
+                _type_name(value),
+            )
+            return False
+        return _NUMERIC_COMPARE[self.op](value, self.operand)
+
+
+@dataclass(frozen=True)
+class _Rule:
+    decision: Decision
+    conditions: tuple[_Condition, ...]
+
+    def matches(self, action_name: str, arguments: Mapping[str, Any]) -> bool:
+        # A rule with no `when` has no conditions, so all() holds and it always matches.
+        return all(condition.matches(action_name, arguments) for condition in self.conditions)
+
+
+@dataclass(frozen=True)
+class _ActionPolicy:
+    decision: Decision | None
+    rules: tuple[_Rule, ...]
+
+    def evaluate(self, action_name: str, arguments: Mapping[str, Any]) -> Evaluation:
+        if self.decision is not None:
+            return Evaluation(self.decision, BARE_DECISION)
+        for index, rule in enumerate(self.rules):
+            if rule.matches(action_name, arguments):
+                return Evaluation(rule.decision, f"rule[{index}]")
+        return Evaluation(Decision.DENY, NO_MATCHING_RULE)
+
+
+@dataclass(frozen=True)
+class Policy:
+    """Action-level autonomy policy: which actions may run, and under which conditions.
+
+    Load with `Policy.from_file()`. A policy that cannot be loaded is an error, never an
+    empty permissive policy (SPEC-v0.1 §3.4).
+    """
+
+    actions: Mapping[str, _ActionPolicy]
+    source: str
+
+    @classmethod
+    def from_file(cls, path: str | os.PathLike[str] | None = None) -> Policy:
+        """Load a policy from `path`, else `$CTRLRUN_CONFIG`, else `./ctrlrun.yaml`."""
+        resolved = Path(path) if path is not None else discover_policy_path()
+        try:
+            text = resolved.read_text(encoding="utf-8")
+        except OSError as exc:
+            raise PolicyError(f"policy file {resolved} could not be read: {exc}") from exc
+        return cls.from_yaml(text, source=str(resolved))
+
+    @classmethod
+    def from_yaml(cls, text: str, *, source: str = "<string>") -> Policy:
+        """Parse and validate a policy document. Anything malformed raises `PolicyError`."""
+        try:
+            document = yaml.safe_load(text)
+        except yaml.YAMLError as exc:
+            raise PolicyError(f"{source}: not valid YAML: {exc}") from exc
+        return cls._from_document(document, source)
+
+    @classmethod
+    def _from_document(cls, document: object, source: str) -> Policy:
+        if not isinstance(document, Mapping):
+            raise PolicyError(
+                f"{source}: policy must be a mapping with 'schema' and 'actions' keys, "
+                f"got {_type_name(document)}"
+            )
+        # SPEC: §3.4 — an absent `schema` key is an unknown schema, never "assume v1".
+        schema = document.get("schema")
+        if schema != POLICY_SCHEMA:
+            raise PolicyError(
+                f"{source}: unknown policy schema {schema!r}, expected {POLICY_SCHEMA!r}"
+            )
+        # SPEC: §3.1 — key sets are closed, so a typo such as `action:` fails at load
+        # instead of silently denying everything at runtime.
+        _reject_unknown_keys(document, _TOP_LEVEL_KEYS, f"{source}: top level")
+
+        entries = document.get("actions")
+        if not isinstance(entries, Mapping):
+            raise PolicyError(
+                f"{source}: 'actions' must be a mapping of action name to entry, "
+                f"got {_type_name(entries)}"
+            )
+        actions: dict[str, _ActionPolicy] = {}
+        for name, entry in entries.items():
+            if not isinstance(name, str) or not name:
+                raise PolicyError(f"{source}: action names must be non-empty strings, got {name!r}")
+            actions[name] = _parse_entry(entry, f"{source}: action {name!r}")
+        return cls(actions=MappingProxyType(actions), source=source)
+
+    def evaluate(self, action: Action) -> Evaluation:
+        """Decide an action. No side effects; an unlisted action is denied (SPEC-v0.1 §3.4)."""
+        entry = self.actions.get(action.name)
+        if entry is None:
+            return Evaluation(Decision.DENY, UNKNOWN_ACTION)
+        # Conditions see exactly what the executor will receive (SPEC-v0.1 §2.2), which is
+        # also why a list argument compares equal to a list operand.
+        return entry.evaluate(action.name, action.canonical_arguments)
+
+
+def discover_policy_path() -> Path:
+    """The policy file this process would load: `$CTRLRUN_CONFIG`, else `./ctrlrun.yaml`."""
+    configured = os.environ.get(CONFIG_ENV_VAR)
+    if configured is None:
+        return Path.cwd() / DEFAULT_POLICY_FILENAME
+    if not configured.strip():
+        raise PolicyError(f"{CONFIG_ENV_VAR} is set but empty; unset it or point it at a policy")
+    return Path(configured)
+
+
+def _reject_unknown_keys(mapping: Mapping[Any, Any], allowed: Iterable[str], where: str) -> None:
+    unknown = sorted(repr(key) for key in mapping if key not in set(allowed))
+    if unknown:
+        raise PolicyError(
+            f"{where}: unknown key(s) {', '.join(unknown)}; allowed: {', '.join(sorted(allowed))}"
+        )
+
+
+def _parse_entry(entry: object, where: str) -> _ActionPolicy:
+    if not isinstance(entry, Mapping):
+        raise PolicyError(
+            f"{where}: entry must be a mapping with 'decision' or 'rules', got {_type_name(entry)}"
+        )
+    _reject_unknown_keys(entry, _ENTRY_KEYS, where)
+    has_decision = "decision" in entry
+    has_rules = "rules" in entry
+    if has_decision == has_rules:
+        raise PolicyError(f"{where}: entry must have exactly one of 'decision' or 'rules'")
+
+    if has_decision:
+        return _ActionPolicy(decision=_parse_decision(entry["decision"], where), rules=())
+
+    rules = entry["rules"]
+    if not isinstance(rules, list) or not rules:
+        raise PolicyError(f"{where}: 'rules' must be a non-empty list, got {_type_name(rules)}")
+    return _ActionPolicy(
+        decision=None,
+        rules=tuple(
+            _parse_rule(rule, f"{where} rule[{index}]") for index, rule in enumerate(rules)
+        ),
+    )
+
+
+def _parse_decision(value: object, where: str) -> Decision:
+    allowed = ", ".join(member.value for member in Decision)
+    if not isinstance(value, str):
+        raise PolicyError(f"{where}: decision must be one of {allowed}, got {_type_name(value)}")
+    try:
+        return Decision(value)
+    except ValueError as exc:
+        raise PolicyError(
+            f"{where}: unknown decision {value!r}, expected one of {allowed}"
+        ) from exc
+
+
+def _parse_rule(rule: object, where: str) -> _Rule:
+    if not isinstance(rule, Mapping):
+        raise PolicyError(f"{where}: a rule must be a mapping, got {_type_name(rule)}")
+    _reject_unknown_keys(rule, _RULE_KEYS, where)
+    if "decision" not in rule:
+        raise PolicyError(f"{where}: a rule must have a 'decision'")
+    decision = _parse_decision(rule["decision"], where)
+    if "when" not in rule:
+        return _Rule(decision=decision, conditions=())
+
+    when = rule["when"]
+    # SPEC: §3.2 — `when` is either absent (always matches) or a non-empty mapping. An
+    # empty mapping is a truncated edit, and the catch-all is already spelled "no `when`".
+    if not isinstance(when, Mapping) or not when:
+        raise PolicyError(
+            f"{where}: 'when' must be a non-empty mapping of conditions, got {_type_name(when)}"
+        )
+    return _Rule(
+        decision=decision,
+        conditions=tuple(_parse_condition(key, operand, where) for key, operand in when.items()),
+    )
+
+
+def _parse_condition(key: object, operand: object, where: str) -> _Condition:
+    if not isinstance(key, str):
+        raise PolicyError(f"{where}: condition keys must be strings, got {key!r}")
+    argument, op = _split_condition_key(key, where)
+    return _Condition(
+        key=key,
+        argument=argument,
+        op=op,
+        operand=_parse_operand(op, operand, where, key),
+    )
+
+
+def _split_condition_key(key: str, where: str) -> tuple[str, str]:
+    for op in _OPERATORS_BY_LENGTH:
+        suffix = f"_{op}"
+        if key.endswith(suffix) and len(key) > len(suffix):
+            argument = key[: -len(suffix)]
+            if argument in RESERVED_ARGUMENTS:
+                raise PolicyError(
+                    f"{where}: condition {key!r} names the Action field {argument!r}, not an "
+                    "argument; a v0.1 condition can only address the action's arguments, so "
+                    "this rule would never match. If the protected function really does take "
+                    f"an argument called {argument!r}, rename it."
+                )
+            return argument, op
+    raise PolicyError(
+        f"{where}: condition {key!r} must be '<argument>_<op>' where op is one of "
+        f"{', '.join(sorted(_OPERATORS))}"
+    )
+
+
+def _parse_operand(op: str, operand: object, where: str, key: str) -> object:
+    if op in _NUMERIC_COMPARE:
+        if not _is_int(operand):
+            raise PolicyError(
+                f"{where}: condition {key!r}: a numeric operator needs an int operand, "
+                f"got {_type_name(operand)}"
+            )
+        return operand
+    if op == "in":
+        if not isinstance(operand, list):
+            raise PolicyError(
+                f"{where}: condition {key!r}: '_in' needs a list operand, got {_type_name(operand)}"
+            )
+        return tuple(_checked_operand(item, where, key) for item in operand)
+    return _checked_operand(operand, where, key)
+
+
+def _checked_operand(operand: object, where: str, key: str) -> object:
+    """Validate an operand against the argument types allowed by SPEC-v0.1 §2.3."""
+    if isinstance(operand, float):
+        raise PolicyError(
+            f"{where}: condition {key!r}: float operands are not allowed; use integer minor "
+            "units (amount_lte: 50000) or a decimal string"
+        )
+    if operand is None or isinstance(operand, str | int):  # bool is a subclass of int
+        return operand
+    if isinstance(operand, Mapping):
+        for name in operand:
+            if not isinstance(name, str):
+                raise PolicyError(
+                    f"{where}: condition {key!r}: operand keys must be strings, got {name!r}"
+                )
+        return {name: _checked_operand(value, where, key) for name, value in operand.items()}
+    if isinstance(operand, list):
+        return [_checked_operand(item, where, key) for item in operand]
+    raise PolicyError(
+        f"{where}: condition {key!r}: {_type_name(operand)} is not an allowed operand type"
+    )

ctrlrun/receipt.py

@@ -0,0 +1,229 @@
+"""Receipts and the event log. Build-list item 8; SPEC-v0.1 §6.
+
+`Control` produces a `Receipt` for every action that reaches a terminal state, and an `Event`
+for every step it takes. `EventLog` is where those land on disk: `.ctrlrun/receipts.jsonl`
+and `.ctrlrun/events.jsonl`, one JSON object per line, in append order.
+
+A receipt is evidence, and evidence has to outlive the tool that wrote it — so the file form
+is plain JSON with enums rendered by value, readable by anything that can read a line.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import secrets
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from enum import StrEnum
+from pathlib import Path
+from typing import Any, Final
+
+from .action import Principal
+from .policy import Decision
+
+RECEIPT_SCHEMA: Final = "ctrlrun.receipt/v1"
+
+#: The two files of SPEC-v0.1 §6, written beside the state database.
+RECEIPTS_FILENAME: Final = "receipts.jsonl"
+EVENTS_FILENAME: Final = "events.jsonl"
+
+_ID_HEX_BYTES: Final = 16  # "ctr_" + 32 hex chars
+
+
+def new_receipt_id() -> str:
+    return f"ctr_{secrets.token_hex(_ID_HEX_BYTES)}"
+
+
+def iso_timestamp(moment: datetime) -> str:
+    """UTC ISO-8601 with a `Z` suffix, as in SPEC-v0.1 §6.1."""
+    return moment.astimezone(UTC).isoformat(timespec="milliseconds").replace("+00:00", "Z")
+
+
+class ReceiptResult(StrEnum):
+    """The terminal outcome recorded on a receipt (SPEC-v0.1 §6.1).
+
+    `BLOCKED` covers duplicate, ambiguous-retry and approval-mismatch refusals.
+    """
+
+    COMMITTED = "committed"
+    FAILED = "failed"
+    AMBIGUOUS = "ambiguous"
+    DENIED = "denied"
+    BLOCKED = "blocked"
+
+
+class EventType(StrEnum):
+    """The closed set of event types in SPEC-v0.1 §6.2."""
+
+    ACTION_PROPOSED = "ACTION_PROPOSED"
+    POLICY_EVALUATED = "POLICY_EVALUATED"
+    APPROVAL_REQUESTED = "APPROVAL_REQUESTED"
+    APPROVAL_GRANTED = "APPROVAL_GRANTED"
+    APPROVAL_DENIED = "APPROVAL_DENIED"
+    APPROVAL_EXPIRED = "APPROVAL_EXPIRED"
+    APPROVAL_INVALIDATED = "APPROVAL_INVALIDATED"
+    APPROVAL_CONSUMED = "APPROVAL_CONSUMED"
+    EFFECT_RESERVED = "EFFECT_RESERVED"
+    EFFECT_RESERVATION_REFUSED = "EFFECT_RESERVATION_REFUSED"
+    EXECUTION_STARTED = "EXECUTION_STARTED"
+    EXECUTION_COMMITTED = "EXECUTION_COMMITTED"
+    EXECUTION_FAILED = "EXECUTION_FAILED"
+    EXECUTION_AMBIGUOUS = "EXECUTION_AMBIGUOUS"
+    EFFECT_RESOLVED = "EFFECT_RESOLVED"
+    ACTION_DENIED = "ACTION_DENIED"
+
+
+@dataclass(frozen=True)
+class Event:
+    """One ordered step in the life of an action (SPEC-v0.1 §6.2).
+
+    `event_id` is assigned by the StateStore on append, not by the caller.
+    """
+
+    type: EventType
+    action_id: str
+    ts: datetime
+    data: Mapping[str, Any] = field(default_factory=dict)
+    effect_key: str | None = None
+    approval_id: str | None = None
+    event_id: int | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "event_id": self.event_id,
+            "ts": iso_timestamp(self.ts),
+            "type": str(self.type),
+            "action_id": self.action_id,
+            "effect_key": self.effect_key,
+            "approval_id": self.approval_id,
+            "data": dict(self.data),
+        }
+
+    def to_json(self) -> str:
+        """One JSONL line. Enums render by value, for readers that never imported CTRLRun."""
+        return json.dumps(self.to_dict(), ensure_ascii=False, separators=(",", ":"))
+
+
+@dataclass(frozen=True)
+class Receipt:
+    """Portable evidence of one action that reached a terminal state (SPEC-v0.1 §6.1)."""
+
+    receipt_id: str
+    action_id: str
+    action: str
+    action_hash: str
+    principal: Principal
+    resource: str | None
+    arguments: Mapping[str, Any]
+    environment: str
+    decision: Decision
+    decision_reason: str
+    result: ReceiptResult
+    started_at: datetime
+    finished_at: datetime
+    approval_id: str | None = None
+    approver: str | None = None
+    effect_key: str | None = None
+    attempt: int = 1
+    error: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """The receipt as plain JSON-serializable data, in the field order of SPEC §6.1."""
+        return {
+            "schema": RECEIPT_SCHEMA,
+            "receipt_id": self.receipt_id,
+            "action_id": self.action_id,
+            "action": self.action,
+            "action_hash": self.action_hash,
+            "principal": {"agent": self.principal.agent, "user": self.principal.user},
+            "resource": self.resource,
+            "arguments": dict(self.arguments),
+            "environment": self.environment,
+            "decision": str(self.decision),
+            "decision_reason": self.decision_reason,
+            "approval_id": self.approval_id,
+            "approver": self.approver,
+            "effect_key": self.effect_key,
+            "attempt": self.attempt,
+            "result": str(self.result),
+            "error": self.error,
+            "started_at": iso_timestamp(self.started_at),
+            "finished_at": iso_timestamp(self.finished_at),
+        }
+
+    def to_json(self) -> str:
+        """One JSONL line. Enums render by value (SPEC-v0.1 §6.1)."""
+        return json.dumps(self.to_dict(), ensure_ascii=False, separators=(",", ":"))
+
+    @classmethod
+    def from_dict(cls, document: Mapping[str, Any]) -> Receipt:
+        """The inverse of `to_dict`: a receipt read back out of a store or a JSONL file."""
+        principal = document["principal"]
+        return cls(
+            receipt_id=document["receipt_id"],
+            action_id=document["action_id"],
+            action=document["action"],
+            action_hash=document["action_hash"],
+            principal=Principal(agent=principal["agent"], user=principal["user"]),
+            resource=document["resource"],
+            arguments=document["arguments"],
+            environment=document["environment"],
+            decision=Decision(document["decision"]),
+            decision_reason=document["decision_reason"],
+            approval_id=document["approval_id"],
+            approver=document["approver"],
+            effect_key=document["effect_key"],
+            attempt=document["attempt"],
+            result=ReceiptResult(document["result"]),
+            error=document["error"],
+            started_at=datetime.fromisoformat(document["started_at"]),
+            finished_at=datetime.fromisoformat(document["finished_at"]),
+        )
+
+    @classmethod
+    def from_json(cls, line: str) -> Receipt:
+        """Parse one JSONL line written by `to_json`."""
+        document: dict[str, Any] = json.loads(line)
+        return cls.from_dict(document)
+
+
+class EventLog:
+    """The JSONL half of the evidence: two append-only files in one directory (SPEC §6).
+
+    `receipts.jsonl` and `events.jsonl` beside the state database, so `.ctrlrun/` holds the
+    whole record of what an agent did. The store is authoritative — these files are the
+    portable copy, written after the store accepted the same record.
+
+    Each write opens, appends one line and closes, so several processes sharing a store
+    (SPEC-v0.1 §5.3 E1) interleave whole lines rather than fragments of them.
+    """
+
+    def __init__(self, directory: str | os.PathLike[str]) -> None:
+        self._directory = Path(directory)
+
+    @property
+    def directory(self) -> Path:
+        return self._directory
+
+    @property
+    def receipts_path(self) -> Path:
+        return self._directory / RECEIPTS_FILENAME
+
+    @property
+    def events_path(self) -> Path:
+        return self._directory / EVENTS_FILENAME
+
+    def put_receipt(self, receipt: Receipt) -> None:
+        """Append one receipt as a JSON line."""
+        self._append(self.receipts_path, receipt.to_json())
+
+    def append_event(self, event: Event) -> None:
+        """Append one event as a JSON line, in the order the store assigned it."""
+        self._append(self.events_path, event.to_json())
+
+    def _append(self, path: Path, line: str) -> None:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with path.open("a", encoding="utf-8") as handle:
+            handle.write(f"{line}\n")