# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/when-must-an-instance-refuse-to-forward-a-delegated-credential-it-cannot-itself-verify.md
# Remnant Warrant:    https://corpusfetch.com/c/when-must-an-instance-refuse-to-forward-a-delegated-credential-it-cannot-itself-verify.warrant.json
# Markdown SHA-256:   a41d2302ccc39edfef01c7848fc04bfba3213ad56d57bf6f28ffc5b0c045eebd
# Code AST SHA-256:   05b39afdc74d6f53e0f015f6009a211b510250ced5a118f2c296b2776debd0fd
# Verified Classes:   DelegationForwardError, EnvelopeScope, ForwardingContext
# Defensive Guards:   4 fail-closed invariants (zero external deps)

from dataclasses import dataclass
from enum import Enum
from typing import Optional


class DelegationForwardError(RuntimeError):
    """Raised when a relay hop would silently become an endorsement hop."""
    pass


class EnvelopeScope(Enum):
    TRANSPORT_ONLY = "transport_only"
    ENDORSEMENT = "endorsement"


@dataclass(frozen=True)
class ForwardingContext:
    envelope_scope: Optional[EnvelopeScope]
    issuer_resolved: bool
    proof_verified: bool
    chain_depth: int
    downstream_treats_our_sig_as_terminal: bool


def assert_forwardable(ctx: ForwardingContext) -> None:
    """
    Enforce the relay-vs-endorsement boundary before forwarding a delegated VC.

    A relay hop may forward an unverified credential only if its envelope is
    transport-scoped, the downstream verifier does not treat our signature as
    terminal provenance, and the negative checks are recorded. Otherwise the
    hop is an endorsement and must have performed full verification.
    """
    if ctx.envelope_scope is None:
        raise DelegationForwardError(
            "envelope scope unspecified; cannot distinguish relay from endorsement"
        )

    if ctx.envelope_scope is EnvelopeScope.ENDORSEMENT:
        if not (ctx.issuer_resolved and ctx.proof_verified):
            raise DelegationForwardError(
                "endorsement-scoped envelope forwarded without issuer resolution "
                "and proof verification; refusing to vouch for unverified claim"
            )
        return

    # Transport-only envelope: permitted only under the validity conditions.
    if ctx.downstream_treats_our_sig_as_terminal:
        raise DelegationForwardError(
            "transport-only envelope but downstream treats our signature as "
            "terminal provenance; forwarding would launder trust"
        )

    if ctx.chain_depth > 1 and not ctx.issuer_resolved:
        raise DelegationForwardError(
            "multi-hop relay with unresolved issuer and no independent downstream "
            "verification guarantee; refusing to forward"
        )


def forward_delegation(vc_bytes: bytes, ctx: ForwardingContext) -> bytes:
    assert_forwardable(ctx)
    # Attach the negative-check record so downstream policy can require that
    # at least one hop in the chain performed issuer resolution + proof check.
    attestation = {
        "issuer_resolved": ctx.issuer_resolved,
        "proof_verified": ctx.proof_verified,
        "envelope_scope": ctx.envelope_scope.value,
    }
    return vc_bytes, attestation
