# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/in-what-scenarios-must-an-instance-refuse-to-honor-a-federated-capability-attestation-that-a-trusted-broker-has-signed.md
# Remnant Warrant:    https://corpusfetch.com/c/in-what-scenarios-must-an-instance-refuse-to-honor-a-federated-capability-attestation-that-a-trusted-broker-has-signed.warrant.json
# Markdown SHA-256:   1cafb01d39d7693b368fd23c953503f1e305d4c4d4e7d0fab9d42e85e623df98
# Code AST SHA-256:   0036291ae185953f26b3de626c285f847447733fab9257f7692f8b795c928aca
# Verified Classes:   FederationAttestationError, Attestation, LocalGrant
# Defensive Guards:   6 fail-closed invariants (zero external deps)

from dataclasses import dataclass
from typing import Optional


class FederationAttestationError(RuntimeError):
    """Raised when a signed attestation cannot be honored at the local boundary."""
    pass


@dataclass(frozen=True)
class Attestation:
    broker_id: str
    policy_id: str
    policy_version: int
    action: str
    resource: str
    signature_valid: bool
    expires_at: float


@dataclass(frozen=True)
class LocalGrant:
    broker_id: str
    policy_id: str
    policy_version: int
    issued_by: str          # must terminate at the local resource owner
    actions: frozenset
    resources: frozenset
    expires_at: float


def authorize(att: Attestation, grants: list[LocalGrant], local_root: str,
              now: float, honored_versions: frozenset) -> bool:
    if not att.signature_valid:
        raise FederationAttestationError(f"bad signature from {att.broker_id}")
    if now >= att.expires_at:
        raise FederationAttestationError(f"attestation expired for {att.broker_id}")

    # Condition 4: policy-path reachability. The grant must exist, be issued by
    # the local root, and reference the same policy id.
    path = [g for g in grants
            if g.broker_id == att.broker_id
            and g.policy_id == att.policy_id
            and g.issued_by == local_root
            and now < g.expires_at]
    if not path:
        raise FederationAttestationError(
            f"policy path for {att.policy_id} does not terminate at local root "
            f"{local_root}; refusing attestation from {att.broker_id}"
        )

    # Condition 5: version consistency. Do not silently fall back.
    if att.policy_version not in honored_versions:
        raise FederationAttestationError(
            f"policy version {att.policy_version} for {att.policy_id} is retired "
            f"locally; refusing rather than falling back"
        )

    grant = path[0]
    if grant.policy_version != att.policy_version:
        raise FederationAttestationError(
            f"version skew: attestation v{att.policy_version} vs local grant "
            f"v{grant.policy_version}"
        )

    # Condition 3: scope containment against the LOCAL grant, not the claim.
    if att.action not in grant.actions or att.resource not in grant.resources:
        raise FederationAttestationError(
            f"attested scope ({att.action}, {att.resource}) exceeds local grant "
            f"for {att.broker_id}"
        )
    return True
