# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/when-must-an-instance-refuse-a-revoked-federated-agent-credential-propagated-across-an-aaif-trust-boundary.md
# Remnant Warrant:    https://corpusfetch.com/c/when-must-an-instance-refuse-a-revoked-federated-agent-credential-propagated-across-an-aaif-trust-boundary.warrant.json
# Markdown SHA-256:   b3fc6bea732546567ac41adda4992a61f58c18e1b8386fa08d34d28271fe4eea
# Code AST SHA-256:   9533eb3ad31de09095d3dcf99dde9435c2a06f00a5c53b33f9ba73105829253a
# Verified Classes:   RevocationStateError
# Defensive Guards:   5 fail-closed invariants (zero external deps)

class RevocationStateError(RuntimeError):
    """Raised when a federated credential's lifecycle state cannot be soundly resolved."""
    pass


def validate_federated_credential(
    cred: dict,
    revocation_list: dict,
    list_fetched_at: float,
    now: float,
    max_staleness: float,
    max_overlap: float,
) -> bool:
    """
    Returns True iff the credential may be honored.
    Raises RevocationStateError when the state is unresolvable.
    """
    jti = cred.get("jti")
    if not jti:
        raise RevocationStateError("credential missing jti; cannot resolve revocation state")

    if now > cred["notAfter"]:
        return False

    list_stale = (now - list_fetched_at) > max_staleness
    revoked_on_list = jti in revocation_list.get("revoked", set())

    if revoked_on_list:
        return False

    lifecycle = cred.get("lifecycle")
    if lifecycle is None:
        # No lifecycle claim: cannot distinguish rotation from revocation.
        if list_stale:
            raise RevocationStateError(
                f"credential {jti} has no lifecycle claim and revocation list is stale "
                f"({now - list_fetched_at:.0f}s > {max_staleness:.0f}s); refusing to infer intent"
            )
        return True

    state = lifecycle.get("state")
    if state == "revoked":
        return False
    if state == "active":
        return not list_stale or True  # active + fresh list is fine; stale list is still a gap
    if state == "rotating":
        overlap_until = lifecycle.get("overlap_until")
        successor = lifecycle.get("successor_jti")
        if not successor:
            raise RevocationStateError(
                f"credential {jti} claims rotating state without successor_jti"
            )
        if overlap_until is None or overlap_until > now + max_overlap:
            raise RevocationStateError(
                f"credential {jti} overlap_until={overlap_until} exceeds relying-party "
                f"maximum overlap {max_overlap}s from now={now}"
            )
        if now > overlap_until:
            return False
        return True

    raise RevocationStateError(f"credential {jti} has unknown lifecycle state {state!r}")
