# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-must-an-instance-verify-the-cryptographic-identity-of-a-build-runner-before-consuming-its-sbom.md
# Remnant Warrant:    https://corpusfetch.com/c/how-must-an-instance-verify-the-cryptographic-identity-of-a-build-runner-before-consuming-its-sbom.warrant.json
# Markdown SHA-256:   19472b2a0b3ace1b028edecde0f07756a433a055ffe02f8e8d2514e2ecc5135d
# Code AST SHA-256:   387a53da0a65843fa38a2546158b240ac83a861848ca2d1284003639561215ab
# Verified Classes:   RunnerVerdict, RunnerIdentity, VerificationContext, RunnerManifest, BuildRunnerIdentityGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

from dataclasses import dataclass
from enum import Enum, auto
import hashlib
import json

class RunnerVerdict(Enum):
    VERIFIED_AUTHENTIC = auto()
    UNTRUSTED_ROOT_CA = auto()
    MISSING_HARDWARE_ATTESTATION = auto()
    EXPIRED_CERTIFICATE = auto()

@dataclass(frozen=True)
class RunnerIdentity:
    certificate_chain_hash: str
    root_ca_fingerprint: str
    enclave_attestation_hash: str | None
    certificate_expiration_epoch: float

@dataclass(frozen=True)
class VerificationContext:
    trusted_root_ca_fingerprint: str
    current_epoch: float
    require_hardware_enclave: bool

@dataclass(frozen=True)
class RunnerManifest:
    verdict: RunnerVerdict
    directive: str
    manifest_digest: str

class BuildRunnerIdentityGuard:
    @staticmethod
    def _hash(data: str) -> str:
        return hashlib.sha256(data.encode("utf-8")).hexdigest()

    @classmethod
    def verify_runner_identity(
        cls, identity: RunnerIdentity, ctx: VerificationContext
    ) -> RunnerManifest:
        
        # Gate 1: Verify the certificate chain
        if not identity.certificate_chain_hash.strip():
            return RunnerManifest(
                verdict=RunnerVerdict.UNTRUSTED_ROOT_CA,
                directive="HALT: No certificate chain provided.",
                manifest_digest=cls._hash("NO_CERT")
            )

        # Gate 2: Verify root CA match
        if identity.root_ca_fingerprint != ctx.trusted_root_ca_fingerprint:
            return RunnerManifest(
                verdict=RunnerVerdict.UNTRUSTED_ROOT_CA,
                directive=f"HALT: Runner root CA {identity.root_ca_fingerprint} does not match trusted {ctx.trusted_root_ca_fingerprint}.",
                manifest_digest=cls._hash("CA_MISMATCH")
            )

        # Gate 3: Check certificate expiration
        if identity.certificate_expiration_epoch < ctx.current_epoch:
            return RunnerManifest(
                verdict=RunnerVerdict.EXPIRED_CERTIFICATE,
                directive="HALT: Runner certificate has expired. Cannot verify identity.",
                manifest_digest=cls._hash("EXPIRED")
            )

        # Gate 4: Hardware attestation requirement
        if ctx.require_hardware_enclave and not identity.enclave_attestation_hash:
            return RunnerManifest(
                verdict=RunnerVerdict.MISSING_HARDWARE_ATTESTATION,
                directive="HALT: Hardware enclave attestation required but missing. Runner may be compromised.",
                manifest_digest=cls._hash("NO_ENCLAVE")
            )

        # Gate 5: Verified
        digest = cls._hash(json.dumps({
            "cert_hash": identity.certificate_chain_hash,
            "root_ca": identity.root_ca_fingerprint,
            "enclave": identity.enclave_attestation_hash or "NONE"
        }, sort_keys=True))
        
        return RunnerManifest(
            verdict=RunnerVerdict.VERIFIED_AUTHENTIC,
            directive="PROCEED: Runner identity and hardware integrity verified.",
            manifest_digest=digest
        )