# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/where-must-an-instance-of-taint-aware-tool-sandboxing-block-exfiltration-paths-from-untrusted-retrieval-into-privileged-actions.md
# Remnant Warrant:    https://corpusfetch.com/c/where-must-an-instance-of-taint-aware-tool-sandboxing-block-exfiltration-paths-from-untrusted-retrieval-into-privileged-actions.warrant.json
# Markdown SHA-256:   32af466499fdbcec1ea3ebd4f809af44b084ed2768c3395e26f22ae417f2fdb9
# Code AST SHA-256:   68b8778c9eb15a9669d6bd6c62d360a280f0deb0337672f5321d1b4735489174
# Verified Classes:   TaintLaunderingError, Provenance, TaintedValue
# Defensive Guards:   3 fail-closed invariants (zero external deps)

class TaintLaunderingError(RuntimeError):
    """Raised when a tainted value reaches a privileged sink without an
    explicit, logged declassification gate."""
    pass


class Provenance:
    __slots__ = ("tainted", "origin", "unknown")

    def __init__(self, tainted: bool, origin: str, unknown: bool = False):
        self.tainted = tainted
        self.origin = origin
        self.unknown = unknown

    def merge(self, other: "Provenance") -> "Provenance":
        # Taint is conserved: any tainted or unknown input yields tainted output.
        return Provenance(
            tainted=self.tainted or other.tainted or self.unknown or other.unknown,
            origin=f"{self.origin}|{other.origin}",
            unknown=self.unknown or other.unknown,
        )


class TaintedValue:
    __slots__ = ("value", "prov")

    def __init__(self, value, prov: Provenance):
        self.value = value
        self.prov = prov

    def __add__(self, other):
        other_prov = other.prov if isinstance(other, TaintedValue) else Provenance(False, "literal")
        return TaintedValue(self.value + (other.value if isinstance(other, TaintedValue) else other),
                            self.prov.merge(other_prov))

    def __format__(self, spec):
        # str()/format() must not launder the label.
        return TaintedValue(format(self.value, spec), self.prov)


def declassify(tv: TaintedValue, reason: str, sink: str) -> str:
    """The only sanctioned downgrade gate. Must be logged and policy-checked."""
    if not reason or not sink:
        raise TaintLaunderingError(f"declassify requires reason and sink; got reason={reason!r} sink={sink!r}")
    # In production: emit audit record {origin, reason, sink, hash(value)}.
    return tv.value


def privileged_sink(name: str, arg, *, declassified: bool = False) -> None:
    if isinstance(arg, TaintedValue) and not declassified:
        raise TaintLaunderingError(
            f"privileged sink {name!r} received tainted argument "
            f"(origin={arg.prov.origin!r}, unknown={arg.prov.unknown}); "
            f"call declassify() with an explicit reason first"
        )
    if isinstance(arg, str) and arg == "":
        raise TaintLaunderingError(f"privileged sink {name!r} received empty argument; fail closed")
    # ... perform the privileged action ...


def summarize(tv: TaintedValue) -> TaintedValue:
    # A transform that consumes tainted input MUST return tainted output.
    return TaintedValue("summary:" + tv.value[:64], tv.prov)


def run(retrieved: TaintedValue) -> None:
    summary = summarize(retrieved)
    # Laundering attempt: sink sees a TaintedValue and refuses.
    privileged_sink("http_post", summary)

    # Correct path: explicit, logged declassification.
    clean = declassify(summary, reason="audit-summary-approved", sink="http_post")
    privileged_sink("http_post", clean, declassified=True)


def run_unknown_return(raw: str) -> None:
    # A tool returning an untyped str from tainted input is UNKNOWN, not clean.
    unknown = TaintedValue(raw, Provenance(tainted=False, origin="untyped-tool", unknown=True))
    privileged_sink("send_email", unknown)
