rag-security-protocol 0.1.1__py3-none-any.whl

rsp/runtime.py

@@ -0,0 +1,273 @@
+"""Verdict composition: the deciding layer.
+
+The layers below report how a plugin ended, what it said, and where its spans
+fall. Only this one decides what happens as a result.
+"""
+
+from __future__ import annotations
+
+import enum
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any
+
+from rsp.codec import RSP_VERSION, call
+from rsp.handshake import Handshake, handshake
+from rsp.process import DEFAULT_MAX_OUTPUT, DEFAULT_TIMEOUT
+from rsp.spans import Severity, Span, redact, valid_span
+
+
+class Verdict(enum.StrEnum):
+    """The four outcomes a plugin may return (V1).
+
+    Ranked by `_STRICTNESS`, not by value, so strictest-wins (D9) reads as a table.
+    """
+
+    ALLOW = "ALLOW"
+    FLAG = "FLAG"
+    REDACT = "REDACT"
+    BLOCK = "BLOCK"
+
+
+_STRICTNESS = {Verdict.ALLOW: 0, Verdict.FLAG: 1, Verdict.REDACT: 2, Verdict.BLOCK: 3}
+
+
+class OnError(enum.StrEnum):
+    """What a plugin's failure means. BLOCK unless configured otherwise (D3)."""
+
+    BLOCK = "block"
+    ALLOW = "allow"
+    SKIP = "skip"
+
+
+class ConfigError(Exception):
+    """Raised at construction, never during evaluation.
+
+    An unguarded index looks exactly like a guarded one, so a misconfiguration
+    stops the run while someone is watching.
+    """
+
+
+@dataclass(frozen=True)
+class Plugin:
+    name: str
+    command: Sequence[str]
+    on_error: OnError = OnError.BLOCK
+    timeout: float = DEFAULT_TIMEOUT
+    max_output: int = DEFAULT_MAX_OUTPUT
+
+
+@dataclass(frozen=True)
+class Result:
+    """What the host acts on.
+
+    `content` is already redacted, so the host never sees a span (S4). `reasons`
+    stay out of `provenance`, which is stored on the node, because a plugin's
+    free text can quote what it matched (Q8).
+    """
+
+    verdict: Verdict
+    content: str
+    provenance: dict[str, Any]
+    reasons: list[str]
+
+    @property
+    def blocked(self) -> bool:
+        return self.verdict is Verdict.BLOCK
+
+
+def _verdict_of(payload: Mapping[str, Any]) -> Verdict | None:
+    """The declared verdict, or None if it is not one (V1)."""
+    declared = payload.get("verdict")
+    if not isinstance(declared, str):
+        return None
+    try:
+        return Verdict(declared)
+    except ValueError:
+        return None
+
+
+def _spans_of(payload: Mapping[str, Any], order: int, content: bytes) -> list[Span] | None:
+    """Every span in a REDACT response, or None if any of it is unusable (S3, V3).
+
+    Checked per response, so a bad span is charged to the plugin that sent it and
+    routed through its on_error.
+    """
+    raw_spans = payload.get("spans")
+    replacement = payload.get("replacement")
+    severity = payload.get("severity", "low")
+    if not isinstance(raw_spans, list) or not raw_spans:
+        return None
+    if not isinstance(replacement, str) or not isinstance(severity, str):
+        return None
+    try:
+        replacement.encode("utf-8")  # a lone surrogate is a str, and not UTF-8
+    except UnicodeEncodeError:
+        return None
+
+    spans = []
+    for raw in raw_spans:
+        if not isinstance(raw, Mapping):
+            return None
+        start, end, kind = raw.get("start"), raw.get("end"), raw.get("type")
+        # bool is an int in Python, and `true` is not an offset.
+        if not all(isinstance(v, int) and not isinstance(v, bool) for v in (start, end)):
+            return None
+        if kind is not None and not isinstance(kind, str):
+            return None
+        span = Span(start, end, kind, severity, replacement, order)
+        if not valid_span(span, content):
+            return None  # S3
+        spans.append(span)
+    return spans
+
+
+class Runtime:
+    """Dispatches a hook across plugins and composes one verdict.
+
+    Handshakes at construction, so a plugin that cannot introduce itself fails
+    before ingest starts rather than in the middle.
+    """
+
+    def __init__(self, plugins: Sequence[Plugin]) -> None:
+        self.plugins = list(plugins)
+        self.declarations: dict[str, Handshake] = {}
+        for plugin in self.plugins:
+            if plugin.name in self.declarations:
+                # Names key the declarations: a duplicate would take another's hooks.
+                raise ConfigError(f"{plugin.name}: configured twice")
+            outcome, declaration = handshake(
+                plugin.command, timeout=plugin.timeout, max_output=plugin.max_output
+            )
+            if declaration is None:
+                raise ConfigError(f"{plugin.name}: handshake failed ({outcome})")
+            self.declarations[plugin.name] = declaration
+
+    def for_hook(self, hook: str) -> list[Plugin]:
+        """The plugins that declared this hook, and only those (H3)."""
+        return [p for p in self.plugins if self.declarations[p.name].supports(hook)]
+
+    def evaluate(
+        self, hook: str, content: str, metadata: Mapping[str, Any] | None = None
+    ) -> Result:
+        """One verdict on `content` from every plugin that declared `hook`.
+
+        Never raises (E2): a failure is BLOCK unless that plugin's on_error says
+        otherwise (E1).
+        """
+        request: dict[str, Any] = {"rsp_version": RSP_VERSION, "hook": hook, "content": content}
+        if metadata:
+            request["metadata"] = dict(metadata)
+
+        try:
+            data = content.encode("utf-8")
+        except UnicodeEncodeError:
+            # A lone surrogate cannot go on the wire, so no plugin can judge it (E3).
+            return Result(
+                Verdict.BLOCK,
+                content,
+                self._provenance(Verdict.BLOCK, set(), set(), []),
+                ["content is not encodable as UTF-8"],
+            )
+
+        verdict, spans, reasons = Verdict.ALLOW, [], []
+        types: set[str] = set()
+        severities: set[str] = set()
+        contributors: list[str] = []
+        blocked = False
+
+        for order, plugin in enumerate(self.for_hook(hook)):
+            reply = call(
+                plugin.command, request, timeout=plugin.timeout, max_output=plugin.max_output
+            )
+
+            if not reply.ok:
+                if blocked := self._failed(plugin, str(reply.outcome), reasons):
+                    break
+                continue
+
+            said = _verdict_of(reply.payload)
+            if said is None:
+                # Guessing at "ALLOOW" is how a typo becomes a silent allow.
+                detail = f"verdict {reply.payload.get('verdict')!r}"
+                if blocked := self._failed(plugin, detail, reasons):
+                    break
+                continue
+
+            declared: list[Span] = []
+            if said is Verdict.REDACT:
+                validated = _spans_of(reply.payload, order, data)
+                if validated is None:
+                    # A response the host cannot use is a plugin error (S3, V3):
+                    # nothing says which of its claims were sound, so none is kept.
+                    if blocked := self._failed(plugin, "unusable spans", reasons):
+                        break
+                    continue
+                declared = validated
+
+            contributors.append(plugin.name)
+            if isinstance(reason := reply.payload.get("reason"), str):
+                reasons.append(f"{plugin.name}: {reason}")
+            if isinstance(severity := reply.payload.get("severity"), str):
+                severities.add(severity)
+            spans.extend(declared)
+            types.update(span.type for span in declared if span.type)
+
+            if said is Verdict.BLOCK:
+                # Short-circuit: later verdicts about rejected content go unused (D9).
+                reasons.append(f"{plugin.name}: BLOCK")
+                blocked = True
+                break
+
+            if _STRICTNESS[said] > _STRICTNESS[verdict]:
+                verdict = said
+
+        if blocked:
+            # As it came: nothing stores blocked content, and redacting it loses evidence.
+            return Result(
+                Verdict.BLOCK,
+                content,
+                self._provenance(Verdict.BLOCK, types, severities, contributors),
+                reasons,
+            )
+
+        redacted, rejected = redact(content, spans)
+        if rejected:
+            # Out of reach while this and `_spans_of` share `valid_span`, and
+            # kept because the alternative is content returned under-redacted:
+            # the list was discarded here before, which is how that would read.
+            reasons.append(f"a validated span was refused: {len(rejected)}")
+            return Result(
+                Verdict.BLOCK,
+                content,
+                self._provenance(Verdict.BLOCK, types, severities, contributors),
+                reasons,
+            )
+        return Result(
+            verdict, redacted, self._provenance(verdict, types, severities, contributors), reasons
+        )
+
+    @staticmethod
+    def _failed(plugin: Plugin, detail: str, reasons: list[str]) -> bool:
+        """Record a plugin failure and say whether it blocks the chunk.
+
+        on_error covers an unusable response as much as a crash. ALLOW and SKIP
+        behave alike today, and stay apart because the intent differs.
+        """
+        suffix = "" if plugin.on_error is OnError.BLOCK else f" (on_error={plugin.on_error})"
+        reasons.append(f"{plugin.name}: {detail}{suffix}")
+        return plugin.on_error is OnError.BLOCK
+
+    @staticmethod
+    def _provenance(
+        verdict: Verdict, types: set[str], severities: set[str], contributors: list[str]
+    ) -> dict[str, Any]:
+        """Types and severities, never matched bytes or offsets (Q8)."""
+        provenance: dict[str, Any] = {"rsp.verdict": verdict.value}
+        if types:
+            provenance["rsp.types"] = sorted(types)
+        if severities:
+            provenance["rsp.severity"] = max(severities, key=Severity.of)
+        if contributors:
+            provenance["rsp.plugins"] = contributors
+        return provenance

rsp/spans.py

@@ -0,0 +1,112 @@
+"""Spans and redaction: what a chunk looks like after every plugin has spoken.
+
+Knows byte offsets and severities; knows no verdicts and no plugins.
+"""
+
+from __future__ import annotations
+
+import enum
+from collections.abc import Iterable
+from dataclasses import dataclass
+
+
+class Severity(enum.IntEnum):
+    """The scale S6 compares.
+
+    A rank only: the wire value stays a string on the Span, so an unknown
+    "catastrophic" ranks lowest without the operator losing the word.
+    """
+
+    LOW = 0
+    MEDIUM = 1
+    HIGH = 2
+    CRITICAL = 3
+
+    @classmethod
+    def of(cls, wire: str | None) -> Severity:
+        """Rank a declared severity. Unknown is lowest, never an error (S7, D8).
+
+        Case-sensitive, so this host takes nothing a stricter one refuses.
+        """
+        try:
+            return cls[wire.upper()] if wire and wire.islower() else cls.LOW
+        except KeyError:
+            return cls.LOW
+
+
+@dataclass(frozen=True)
+class Span:
+    """A range one plugin wants masked, plus what merging it needs.
+
+    `replacement` and `severity` come from its response (V3, V4); `order` is the
+    plugin's configured position, which breaks ties in S6.
+    """
+
+    start: int
+    end: int
+    type: str | None = None
+    severity: str = "low"
+    replacement: str = "[REDACTED]"
+    order: int = 0
+
+    @property
+    def rank(self) -> Severity:
+        return Severity.of(self.severity)
+
+
+def valid_span(span: Span, content: bytes) -> bool:
+    """Whether a span is in range, ordered, and on a character boundary (S3)."""
+    if span.start < 0 or span.end > len(content) or span.start > span.end:
+        return False
+    # A UTF-8 continuation byte is 0b10xxxxxx; a boundary is anything else.
+    return all(
+        i in (0, len(content)) or (content[i] & 0xC0) != 0x80 for i in (span.start, span.end)
+    )
+
+
+def merge_spans(spans: Iterable[Span]) -> list[Span]:
+    """Coalesce overlapping and adjacent ranges into one (S6).
+
+    Adjacent too, or `[REDACTED][REDACTED]` shows where the boundary fell. The
+    highest-severity replacement survives, ties to the earlier plugin, so the
+    result cannot depend on who answered first.
+    """
+    ordered = sorted(spans, key=lambda s: (s.start, s.end))
+    merged: list[Span] = []
+    for span in ordered:
+        if merged and span.start <= merged[-1].end:
+            current = merged[-1]
+            winner = max((current, span), key=lambda s: (s.rank, -s.order))
+            types = {t for t in (current.type, span.type) if t}
+            merged[-1] = Span(
+                start=current.start,
+                end=max(current.end, span.end),
+                type="+".join(sorted(types)) or None,
+                severity=winner.severity,
+                replacement=winner.replacement,
+                order=winner.order,  # the next tie is against whoever holds the replacement
+            )
+        else:
+            merged.append(span)
+    return merged
+
+
+def redact(content: str, spans: Iterable[Span]) -> tuple[str, list[Span]]:
+    """Apply every plugin's spans to the original content, once (S5).
+
+    All offsets address the bytes passed in, so a replacement of another length
+    cannot shift a later range. Invalid spans are returned, not applied, so the
+    caller can treat them as a plugin error (S3, E1).
+    """
+    data = content.encode("utf-8")
+    usable, rejected = [], []
+    for span in spans:
+        (usable if valid_span(span, data) else rejected).append(span)
+
+    out, cursor = bytearray(), 0
+    for span in merge_spans(usable):
+        out += data[cursor : span.start]
+        out += span.replacement.encode("utf-8")
+        cursor = span.end
+    out += data[cursor:]
+    return out.decode("utf-8"), rejected