# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-happens-when-an-instance-advertises-a-push-notification-webhook-binding-on-an-agent-card-whose-tasks-pushnotificationconfig-capability-is-declare.md
# Remnant Warrant:    https://corpusfetch.com/c/what-happens-when-an-instance-advertises-a-push-notification-webhook-binding-on-an-agent-card-whose-tasks-pushnotificationconfig-capability-is-declare.warrant.json
# Markdown SHA-256:   f1c76959b87f4808524346deb4d2f2a40e7908f04a005fdc9b09dce81ac10dbd
# Code AST SHA-256:   60d94442fe74844017cbe12b93583ac14b12d66ec32371e6addd3242c5f8de2e
# Verified Classes:   UnauthenticatedWebhookBindingError, PushNotificationConfig, AgentCard
# Defensive Guards:   3 fail-closed invariants (zero external deps)

"""Guard: refuse to establish a webhook binding that would be unauthenticated
against a receiver whose ingress enforces auth. Run before message/send."""

from dataclasses import dataclass
from typing import Optional


class UnauthenticatedWebhookBindingError(RuntimeError):
    """Raised when a push-notification config would be unauthenticated
    against a receiver known to enforce ingress auth."""


@dataclass
class PushNotificationConfig:
    url: str
    authentication: Optional[dict] = None  # scheme, credentials, or token ref


@dataclass
class AgentCard:
    push_notifications: bool
    # True if the callee's delivery path requires a per-task auth object.
    requires_auth_on_delivery: bool


def establish_binding(card: AgentCard, config: PushNotificationConfig,
                      receiver_enforces_auth: bool) -> PushNotificationConfig:
    if not card.push_notifications:
        raise UnauthenticatedWebhookBindingError(
            f"callee does not advertise pushNotifications; url={config.url}"
        )
    if receiver_enforces_auth and config.authentication is None:
        raise UnauthenticatedWebhookBindingError(
            "refusing to bind unauthenticated webhook: receiver enforces auth "
            f"but config.authentication is null (url={config.url})"
        )
    if card.requires_auth_on_delivery and config.authentication is None:
        raise UnauthenticatedWebhookBindingError(
            "callee delivery path requires per-task authentication but config "
            f"omits it; set would succeed and deliveries would 401 (url={config.url})"
        )
    return config
