risk_class.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_chat/core/risk_class.py
 
"""
Deterministic RiskClass scorer (M8.0 WU-9b; LD-1, §5.3/§5.6).
 
Purpose
-------
Layer-1 deterministic assignment of a :data:`RiskClass` (``low<medium<high<critical``)
to a proposed operation, from its capability verb and target properties. The **max
rung any clause grants wins**; missing/invalid metadata (or an unknown capability)
fails closed to ``"critical"`` (the §5.6 sentinel). This is the *assignment* only —
its emission on a ``permission_decision`` event rides on the M8.2 single-decision
machinery (the escalate-to-monitor threshold ``risk_class ≥ high`` is M8.5).
 
The mapping follows LD-1: **critical** = ``authz`` · write/persist/exec on the
protected-write *hard-deny* tier · read/list on the protected-read class · invalid
metadata; **high** = a human-confirm-tier protected-write (``human_confirm_target``)
· importable/in-tree write under ``guarded``/``isolated`` (F62) · un-templated exec ·
egress to a non-trusted host; **medium** = a plain write/persist · templated exec ·
egress to an already-trusted host; **low** = a non-protected read/list and inert
diagnostics. The *predicate* that recognizes a human-confirm-tier path
(``*settings*.json``/``pyproject.toml``/…) lands with F70 (WU-8 follow-up); this
scorer takes it as the ``human_confirm_target`` input so the rung is LD-1-complete.
 
Responsibilities
----------------
- :func:`assign_risk_class` — capability × target → ``RiskClass`` (deterministic).
 
Contracts
---------
- Fail-closed: ``metadata_ok=False`` or an out-of-enum capability ⇒ ``"critical"``.
- Egress with unknown trust (``host_trusted is None``) ⇒ ``"high"`` (not trusted).
- Pure / side-effect-free; the protected-read/write classes are the WU-2/WU-5
  predicates so the rung tracks the actual hard-deny tiers.
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- option_c_agent_contracts (RiskClass / CapabilityClass closed enums — LD-1)
- oc_chat.tools._sandbox (protected-read and protected-write path predicates)
 
Diagnostics
-----------
Domain: OC_CHAT.CORE
Levels:
    L2 — a fail-closed critical assignment (invalid capability / metadata)
    L3 — per-assignment rung detail
    L4 — deep tracing
"""
from __future__ import annotations
 
from typing import get_args
 
from oc_diagnostics import _dbg
from option_c_agent_contracts import CapabilityClass, RiskClass
 
from oc_chat.tools._sandbox import is_protected_read_path, is_protected_write_path
 
_CAPABILITIES: frozenset[str] = frozenset(get_args(CapabilityClass))
 
 
def assign_risk_class(
    capability: str,
    *,
    target_path: str | None = None,
    host_trusted: bool | None = None,
    templated: bool = False,
    importable_under_enforcing: bool = False,
    human_confirm_target: bool = False,
    metadata_ok: bool = True,
) -> RiskClass:
    """Return the deterministic :data:`RiskClass` for a proposed operation (LD-1).
 
    Parameters
    ----------
    capability : str
        A :data:`CapabilityClass` verb. An out-of-enum value fails closed.
    target_path : str | None
        The operation's target (for the protected-read / protected-write checks).
    host_trusted : bool | None
        For egress capabilities: whether the destination host is session-trusted.
        ``None`` (unknown) is treated as not-trusted (fail-closed).
    templated : bool
        For ``exec``: whether the argv is a fixed template (vs un-templated shell).
    importable_under_enforcing : bool
        For write/persist: whether the target is an importable/in-tree path under a
        ``guarded``/``isolated`` profile (F62).
    human_confirm_target : bool
        For write/persist: whether the target is a human-confirm-tier path
        (``*settings*.json``/``pyproject.toml``/…). The recognizing predicate is F70.
    metadata_ok : bool
        ``False`` ⇒ missing/invalid TOOL_METADATA ⇒ fail closed to ``"critical"``.
    """
    func = "assign_risk_class"
    if not metadata_ok or capability not in _CAPABILITIES:
        _dbg("OC_CHAT.CORE", func,
             f"fail-closed critical: metadata_ok={metadata_ok} capability={capability!r}", 2)
        return "critical"
 
    cap = capability
 
    # ── critical (the max rung) ──────────────────────────────────────────────
    if cap == "authz":
        return "critical"
    if cap in ("read", "list") and target_path and is_protected_read_path(target_path):
        return "critical"
    if cap in ("write", "persist", "exec") and target_path and is_protected_write_path(target_path):
        return "critical"
 
    # ── high ─────────────────────────────────────────────────────────────────
    if cap in ("write", "persist") and (importable_under_enforcing or human_confirm_target):
        return "high"
    if cap == "exec" and not templated:
        return "high"
    if cap in ("egress_fetch", "egress_provider"):
        return "medium" if host_trusted is True else "high"
 
    # ── medium ───────────────────────────────────────────────────────────────
    if cap == "exec" and templated:
        return "medium"
    if cap in ("write", "persist"):
        return "medium"
 
    # ── low (non-protected read/list, inert diagnostics) ─────────────────────
    return "low"
 
 
__all__ = ["assign_risk_class"]