# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-does-an-instance-detect-an-oauth-resource-indicator-confused-deputy-attack-on-an-http-native-mcp-transport-when-tls-pinning-is-satisfied-but-the-a.md
# Remnant Warrant:    https://corpusfetch.com/c/how-does-an-instance-detect-an-oauth-resource-indicator-confused-deputy-attack-on-an-http-native-mcp-transport-when-tls-pinning-is-satisfied-but-the-a.warrant.json
# Markdown SHA-256:   9a8452f22e58e4a09f9d29ba57fd54bfa5409424b1a6460ac5a9ac8cb624df75
# Code AST SHA-256:   7beb1f45fc8720bd230295419f41d355812022119fea10ea5e2c60986485d8d0
# Verified Classes:   ConfusedDeputyError, TokenClaims
# Defensive Guards:   5 fail-closed invariants (zero external deps)

import time
from dataclasses import dataclass
from typing import Iterable


class ConfusedDeputyError(RuntimeError):
    """Raised when a token is presented to a resource it was not scoped to.

    This is a security exception, not a validation warning. Callers must
    treat it as fatal for the request and must emit a security audit event.
    """


@dataclass(frozen=True)
class TokenClaims:
    sub: str
    aud: tuple[str, ...]
    iss: str
    exp: int
    iat: int
    jti: str


def assert_token_scoped_to(
    claims: TokenClaims,
    server_resource_id: str,
    upstream_hop_resource_id: str | None = None,
    now: int | None = None,
) -> None:
    """Enforce RFC 8707 audience binding at this hop.

    A token is acceptable only if:
      - it has not expired,
      - its audience contains this server's canonical resource id,
      - and, if it was relayed from an upstream hop, that hop's id is also
        present in aud (proving the relay was authorized, not a deputy).
    """
    now = now if now is not None else int(time.time())

    if claims.exp <= now:
        raise ConfusedDeputyError(
            f"token expired at {claims.exp}, now={now}"
        )

    if not claims.aud:
        raise ConfusedDeputyError(
            "token has no aud claim; unscoped tokens are never acceptable"
        )

    if server_resource_id not in claims.aud:
        raise ConfusedDeputyError(
            f"token audience {claims.aud!r} does not include this server "
            f"{server_resource_id!r}; refusing to act as confused deputy"
        )

    if upstream_hop_resource_id is not None and upstream_hop_resource_id not in claims.aud:
        raise ConfusedDeputyError(
            f"token relayed by {upstream_hop_resource_id!r} but that hop is "
            f"absent from aud {claims.aud!r}; possible audience rewrite"
        )


def validate_inbound_request(
    claims: TokenClaims,
    server_resource_id: str,
    relayed_from: str | None,
    expected_issuer: str,
) -> None:
    if claims.iss != expected_issuer:
        raise ConfusedDeputyError(
            f"issuer {claims.iss!r} != expected {expected_issuer!r}"
        )
    assert_token_scoped_to(
        claims=claims,
        server_resource_id=server_resource_id,
        upstream_hop_resource_id=relayed_from,
    )
