# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/where-must-an-instance-of-a2a-v1-0-agent-card-discovery-fail-closed-when-the-publisher-s-well-known-agent-json-advertises-a-capability-set-that-the-de.md
# Remnant Warrant:    https://corpusfetch.com/c/where-must-an-instance-of-a2a-v1-0-agent-card-discovery-fail-closed-when-the-publisher-s-well-known-agent-json-advertises-a-capability-set-that-the-de.warrant.json
# Markdown SHA-256:   4f5cb02302f7d80ff69ecbbac47ff8e535ba663a47cacecf80af2306ac009ad5
# Code AST SHA-256:   43d466be6b0f4281110e67cf13569e0b16133539794c1b6cc8cf7aff09739be1
# Verified Classes:   CardScopeMismatchError
# Defensive Guards:   3 fail-closed invariants (zero external deps)

import json
from typing import Any

CONSUMED_FIELDS = frozenset({"skills", "capabilities", "securitySchemes"})


class CardScopeMismatchError(RuntimeError):
    """Raised when an A2A v1.0 agent card's signature scope does not cover
    the fields the delegating runtime consumes for a task envelope."""


def validate_card_for_delegation(card: dict[str, Any], skill_id: str) -> None:
    signatures = card.get("signatures")
    if not signatures:
        # v1.0 permits unsigned cards; treat as advisory, require probe.
        raise CardScopeMismatchError(
            f"card for {card.get('name')!r} is unsigned; delegation to skill "
            f"{skill_id!r} requires out-of-band capability probe"
        )

    jws = signatures[0]
    protected = json.loads(_b64url_decode(jws["protected"]))
    critical = frozenset(protected.get("critical", []))

    uncovered = CONSUMED_FIELDS - critical
    if uncovered:
        raise CardScopeMismatchError(
            f"card signature scope {sorted(critical)} does not cover consumed "
            f"fields {sorted(uncovered)}; refusing delegation to skill {skill_id!r}"
        )

    declared_skills = {s["id"] for s in card.get("skills", [])}
    if skill_id not in declared_skills:
        raise CardScopeMismatchError(
            f"skill {skill_id!r} not present in signed skills set "
            f"{sorted(declared_skills)}"
        )


def _b64url_decode(s: str) -> bytes:
    import base64
    pad = "=" * (-len(s) % 4)
    return base64.urlsafe_b64decode(s + pad)
