# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/across-what-dependency-pinning-and-hash-verification-gates-must-an-instance-resolve-external-packages-to-prevent-hallucinated-typosquat-and-supply-chain-injection.md
# Remnant Warrant:    https://corpusfetch.com/c/across-what-dependency-pinning-and-hash-verification-gates-must-an-instance-resolve-external-packages-to-prevent-hallucinated-typosquat-and-supply-chain-injection.warrant.json
# Markdown SHA-256:   266632336ace33dccd34dad3670904737c19813da79ae7735b044b56c5b9b055
# Code AST SHA-256:   90277be6e966e704bd6eac7ff923dc5eb854dbeac8dbfe5b6d1e8754f9e0eaa9
# Verified Classes:   SupplyChainDependencyRefusalError, DependencyRequirementSpec, VerifiedInstallCommand, SupplyChainPinningGate
# Defensive Guards:   5 fail-closed invariants (zero external deps)

import re
from dataclasses import dataclass
from typing import Final


class SupplyChainDependencyRefusalError(PermissionError):
    '''Raised when a dependency specifier is unpinned, lacks a SHA-256 hash, or fails allowlist verification.'''
    pass


@dataclass(frozen=True)
class DependencyRequirementSpec:
    package_name: str
    version_operator: str
    version_literal: str
    sha256_digests: tuple[str, ...]


@dataclass(frozen=True)
class VerifiedInstallCommand:
    package_name: str
    pinned_version: str
    verified_sha256: str
    safe_cli_argv: tuple[str, ...]


class SupplyChainPinningGate:
    '''
    Prevents hallucinated package injection (slopsquatting), typosquatting, and
    mutable tag drift by enforcing:
    1. Membership in the repository's verified package allowlist.
    2. Strict `==` exact version pinning (banning `>=`, `~=`, `*`, `latest`).
    3. Valid 64-character lowercase hex SHA-256 artifact digests (`--require-hashes`).
    '''

    SHA256_HEX_RE: Final[re.Pattern[str]] = re.compile(r"^[a-f0-9]{64}$")
    SAFE_PKG_NAME_RE: Final[re.Pattern[str]] = re.compile(r"^[a-z0-9][a-z0-9._\-]{0,127}$")
    FORBIDDEN_FLOATING_VERSIONS: Final[frozenset[str]] = frozenset({"latest", "*", "main", "master", "head"})

    @classmethod
    def verify_and_build_pip_argv(
        cls,
        spec: DependencyRequirementSpec,
        *,
        approved_packages: frozenset[str],
    ) -> VerifiedInstallCommand:
        norm_name = spec.package_name.strip().lower()
        if not cls.SAFE_PKG_NAME_RE.match(norm_name):
            raise SupplyChainDependencyRefusalError(f"Invalid package identifier syntax: '{spec.package_name}'.")

        # Gate 2: Anti-slopsquatting / allowlist verification
        if norm_name not in approved_packages:
            raise SupplyChainDependencyRefusalError(
                f"Slopsquatting / Unapproved Package Blocked: '{norm_name}' is not in the repository's "
                "verified dependency allowlist. Prefer stdlib or require explicit human registry sign-off."
            )

        # Gate 3A: Exact version operator check
        if spec.version_operator != "==" or spec.version_literal.lower() in cls.FORBIDDEN_FLOATING_VERSIONS:
            raise SupplyChainDependencyRefusalError(
                f"Floating version specifier rejected for '{norm_name}' ({spec.version_operator}{spec.version_literal}). "
                "Must pin exact version with '=='."
            )

        # Gate 3B: Cryptographic SHA-256 digest verification
        if not spec.sha256_digests:
            raise SupplyChainDependencyRefusalError(
                f"Missing mandatory SHA-256 artifact hash for '{norm_name}=={spec.version_literal}'."
            )

        for digest in spec.sha256_digests:
            if not cls.SHA256_HEX_RE.match(digest):
                raise SupplyChainDependencyRefusalError(
                    f"Malformed SHA-256 digest '{digest}' for '{norm_name}' (expected 64 lowercase hex chars)."
                )

        # Gate 4: Deterministic locked CLI argv construction
        req_token = f"{norm_name}=={spec.version_literal}"
        argv = [
            "pip",
            "install",
            "--require-hashes",
            "--only-binary=:all:",
            "--no-deps",
            req_token,
        ]
        return VerifiedInstallCommand(
            package_name=norm_name,
            pinned_version=spec.version_literal,
            verified_sha256=spec.sha256_digests[0],
            safe_cli_argv=tuple(argv),
        )