# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-should-an-instance-detect-a-manifest-signature-that-verifies-but-was-signed-by-a-rotated-out-key-during-cross-org-agent-trust-bootstrapping.md
# Remnant Warrant:    https://corpusfetch.com/c/how-should-an-instance-detect-a-manifest-signature-that-verifies-but-was-signed-by-a-rotated-out-key-during-cross-org-agent-trust-bootstrapping.warrant.json
# Markdown SHA-256:   13c66bd823bd90a7f2a26a8eab4633c9b179c051687aaa75791954622e5b139e
# Code AST SHA-256:   bfb176d2d49ea121addd53608959b648e0c2e7b59d5d954bb9bf80046f49a4a6
# Verified Classes:   ManifestEpochError, KeyEpoch, Manifest
# Defensive Guards:   6 fail-closed invariants (zero external deps)

from dataclasses import dataclass
from datetime import datetime, timedelta


class ManifestEpochError(RuntimeError):
    """Raised when a manifest signature verifies under a key that was not
    authorized for manifest-signing at the manifest's claimed issued_at."""


@dataclass(frozen=True)
class KeyEpoch:
    kid: str
    purpose: str          # e.g. "manifest-signing" or "vc-verification"
    valid_from: datetime
    valid_until: datetime
    revoked: bool = False


@dataclass(frozen=True)
class Manifest:
    kid: str
    issued_at: datetime
    valid_from: datetime
    signature_ok: bool    # result of cryptographic verification only


CLOCK_SKEW = timedelta(minutes=5)
MAX_FRESHNESS = timedelta(hours=24)


def authorize_manifest(
    manifest: Manifest,
    key_epochs: list[KeyEpoch],
    now: datetime,
) -> None:
    if not manifest.signature_ok:
        raise ManifestEpochError("signature does not verify")

    matches = [k for k in key_epochs if k.kid == manifest.kid]
    if not matches:
        raise ManifestEpochError(f"unknown kid {manifest.kid!r}")

    # A key may have multiple epochs (e.g. re-issued for a new purpose).
    signing_epochs = [
        k for k in matches if k.purpose == "manifest-signing" and not k.revoked
    ]
    if not signing_epochs:
        raise ManifestEpochError(
            f"kid {manifest.kid!r} holds no live manifest-signing authority"
        )

    # The signature must verify under a key that was authorized for
    # manifest-signing AT issued_at -- not merely at verification time.
    epoch_ok = any(
        k.valid_from - CLOCK_SKEW <= manifest.issued_at <= k.valid_until + CLOCK_SKEW
        for k in signing_epochs
    )
    if not epoch_ok:
        raise ManifestEpochError(
            f"kid {manifest.kid!r} was not a manifest-signing key at "
            f"issued_at={manifest.issued_at.isoformat()}"
        )

    # Backdated issuance used to authorize future behavior.
    if manifest.valid_from < manifest.issued_at - CLOCK_SKEW:
        raise ManifestEpochError(
            "manifest valid_from precedes issued_at beyond clock skew"
        )

    # Freshness of the assertion itself.
    if now - manifest.issued_at > MAX_FRESHNESS:
        raise ManifestEpochError(
            f"manifest issued_at too old: {manifest.issued_at.isoformat()}"
        )


def bootstrap_trust(manifest: Manifest, jwks: list[KeyEpoch], now: datetime) -> str:
    authorize_manifest(manifest, jwks, now)
    return f"trust bootstrapped for kid={manifest.kid}"