# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-builder-identity-proofs-must-be-verified-before-an-agent-pulls-a-container-image-from-a-public-registry.md
# Remnant Warrant:    https://corpusfetch.com/c/what-builder-identity-proofs-must-be-verified-before-an-agent-pulls-a-container-image-from-a-public-registry.warrant.json
# Markdown SHA-256:   f0770f07fcbc8fa8d9bfdd800bf95310c68e64370552ed61d52b43c2c945ece4
# Code AST SHA-256:   6c9103c7a2df91f2f0b33c4d08799c8905c8412c754d17070dfe5bb2635ea357
# Verified Classes:   ImageVerdict, ContainerImage, VerificationPolicy, ImageManifest, ContainerIdentityGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class ImageVerdict(Enum):
    VERIFIED_IMAGE = auto()
    UNSIGNED_IMAGE = auto()
    UNTRUSTED_BUILDER = auto()
    SOURCE_MISMATCH = auto()

@dataclass(frozen=True)
class ContainerImage:
    image_digest: str
    slsa_provenance_hash: str | None
    builder_cert_hash: str | None
    source_commit_hash: str | None

@dataclass(frozen=True)
class VerificationPolicy:
    trusted_builders: frozenset[str]
    allowed_source_commits: frozenset[str]

@dataclass(frozen=True)
class ImageManifest:
    verdict: ImageVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_image(
        cls, image: ContainerImage, policy: VerificationPolicy
    ) -> ImageManifest:
        
        # Gate 1: SLSA provenance presence
        if not image.slsa_provenance_hash:
            return ImageManifest(
                verdict=ImageVerdict.UNSIGNED_IMAGE,
                directive="HALT: No SLSA provenance. Image origin unverified.",
                manifest_digest=cls._hash(f"NO_PROVENANCE:{image.image_digest}")
            )

        # Gate 2: Builder trust
        if not image.builder_cert_hash or image.builder_cert_hash not in policy.trusted_builders:
            return ImageManifest(
                verdict=ImageVerdict.UNTRUSTED_BUILDER,
                directive=f"HALT: Builder {image.builder_cert_hash} is not trusted.",
                manifest_digest=cls._hash(f"UNTRUSTED_BUILDER:{image.image_digest}")
            )

        # Gate 3: Source commit verification
        if image.source_commit_hash not in policy.allowed_source_commits:
            return ImageManifest(
                verdict=ImageVerdict.SOURCE_MISMATCH,
                directive=f"HALT: Source commit {image.source_commit_hash} is not in the allowed list.",
                manifest_digest=cls._hash(f"SOURCE_MISMATCH:{image.source_commit_hash}")
            )

        # Gate 4: Verified
        digest = cls._hash(json.dumps({
            "digest": image.image_digest,
            "builder": image.builder_cert_hash,
            "source": image.source_commit_hash
        }, sort_keys=True))
        
        return ImageManifest(
            verdict=ImageVerdict.VERIFIED_IMAGE,
            directive="PROCEED: Container image origin and builder identity verified.",
            manifest_digest=digest
        )