# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/where-must-an-instance-refuse-to-bootstrap-a-federation-trust-anchor-from-a-peer-supplied-policy-bundle.md
# Remnant Warrant:    https://corpusfetch.com/c/where-must-an-instance-refuse-to-bootstrap-a-federation-trust-anchor-from-a-peer-supplied-policy-bundle.warrant.json
# Markdown SHA-256:   8a6f32bab7e45e3235bca919c61fd8a538bed91c4af54df62a40cc6c93e771fc
# Code AST SHA-256:   3fce4514e4eff02552e128f7dfec3b45d28fcd32e1e304d1fc676001b4e05e1b
# Verified Classes:   AnchorBootstrapError, PinnedAnchor, PolicyBundle
# Defensive Guards:   6 fail-closed invariants (zero external deps)

import hashlib
from dataclasses import dataclass


class AnchorBootstrapError(RuntimeError):
    """Raised when a peer-supplied policy bundle attempts to establish trust
    from within itself rather than extending a locally pinned anchor."""


@dataclass(frozen=True)
class PinnedAnchor:
    fingerprint: str  # sha256 of DER-encoded anchor key
    epoch: int


@dataclass
class PolicyBundle:
    chain_fingerprints: list[str]  # leaf -> ... -> root
    self_declared_root: str
    anchor_epoch: int
    epoch_signed_by: str  # fingerprint of key that signed the epoch field
    revocation_endpoint: str


def establish_or_extend_anchor(
    bundle: PolicyBundle,
    pinned: PinnedAnchor | None,
    out_of_band_fingerprint: str | None,
) -> PinnedAnchor:
    root_fp = bundle.self_declared_root

    if pinned is None:
        # Bootstrap path: trust MUST come from outside the bundle.
        if out_of_band_fingerprint is None:
            raise AnchorBootstrapError(
                "no pinned anchor and no out-of-band fingerprint supplied; "
                "refusing to bootstrap from peer-supplied bundle root "
                f"{root_fp!r} (self-consistency is not trust)"
            )
        if root_fp != out_of_band_fingerprint:
            raise AnchorBootstrapError(
                f"bundle root {root_fp!r} does not match out-of-band "
                f"fingerprint {out_of_band_fingerprint!r}"
            )
        if root_fp not in bundle.chain_fingerprints:
            raise AnchorBootstrapError(
                "out-of-band anchor absent from bundle chain; cannot verify"
            )
        return PinnedAnchor(fingerprint=root_fp, epoch=bundle.anchor_epoch)

    # Maintenance path: extend only from the pinned anchor.
    if pinned.fingerprint not in bundle.chain_fingerprints:
        raise AnchorBootstrapError(
            f"bundle does not chain to pinned anchor {pinned.fingerprint!r}; "
            "peer-supplied roots are not admissible as anchor additions"
        )
    if bundle.anchor_epoch <= pinned.epoch:
        raise AnchorBootstrapError(
            f"epoch regression: bundle epoch {bundle.anchor_epoch} <= "
            f"pinned epoch {pinned.epoch} (possible rollback)"
        )
    if bundle.epoch_signed_by != pinned.fingerprint:
        raise AnchorBootstrapError(
            "epoch field not signed by pinned anchor; bundle leaf cannot "
            "authorize anchor rotation"
        )
    return PinnedAnchor(fingerprint=pinned.fingerprint, epoch=bundle.anchor_epoch)


def fingerprint(der: bytes) -> str:
    return hashlib.sha256(der).hexdigest()