# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/when-must-an-instance-refuse-binding-a-residual-because-the-authentication-method-it-relied-on-has-been-replaced.md
# Remnant Warrant:    https://corpusfetch.com/c/when-must-an-instance-refuse-binding-a-residual-because-the-authentication-method-it-relied-on-has-been-replaced.warrant.json
# Markdown SHA-256:   896f3d1d9c8b057ddbea72a098c740d9d0e5f2045ec7569b274b94e1e37022a8
# Code AST SHA-256:   81c51426ed9216b128953b8ab2012986488976c536b9f37580bc52ce3bd77ec4
# Verified Classes:   ReplacedAuthSchemeRefusalError, AuthSchemeType, ResidualAuthMetadata, AuthBindingVerdict, AuthReplacementArbiter
# Defensive Guards:   1 fail-closed invariants (zero external deps)

from dataclasses import dataclass
from enum import Enum


class ReplacedAuthSchemeRefusalError(PermissionError):
    '''Raised when an instance attempts to bind a replaced authentication scheme from a historical residual.'''
    pass


class AuthSchemeType(Enum):
    BASIC_AUTH = "BASIC_AUTH"
    STATIC_BEARER_KEY = "STATIC_BEARER_KEY"
    SSH_STATIC_KEY = "SSH_STATIC_KEY"
    OAUTH2_EPHEMERAL_JWT = "OAUTH2_EPHEMERAL_JWT"
    OIDC_WORKLOAD_IDENTITY = "OIDC_WORKLOAD_IDENTITY"
    MTLS_CLIENT_CERT = "MTLS_CLIENT_CERT"


@dataclass(frozen=True)
class ResidualAuthMetadata:
    residual_id: str
    assumed_scheme: AuthSchemeType
    handles_token_refresh: bool
    downstream_payload_invariant: str


@dataclass(frozen=True)
class AuthBindingVerdict:
    residual_id: str
    bind_auth_handshake: bool
    bind_downstream_payload: bool
    requires_refresh_wrapper: bool
    resolution_note: str


class AuthReplacementArbiter:
    '''
    Determines when an instance must refuse binding a residual's authentication
    procedure because the underlying auth method has been replaced:
    1. Blocks binding of legacy auth handshakes when `assumed_scheme != active_scheme`.
    2. Detects when moving from static keys to ephemeral tokens requires a TTL refresh wrapper.
    3. Preserves orthogonal downstream payload invariants.
    '''

    EPHEMERAL_SCHEMES = frozenset({
        AuthSchemeType.OAUTH2_EPHEMERAL_JWT,
        AuthSchemeType.OIDC_WORKLOAD_IDENTITY,
        AuthSchemeType.MTLS_CLIENT_CERT,
    })

    @classmethod
    def evaluate_auth_compatibility(
        cls,
        residual: ResidualAuthMetadata,
        *,
        active_scheme: AuthSchemeType,
    ) -> AuthBindingVerdict:
        if residual.assumed_scheme == active_scheme:
            return AuthBindingVerdict(
                residual_id=residual.residual_id,
                bind_auth_handshake=True,
                bind_downstream_payload=True,
                requires_refresh_wrapper=False,
                resolution_note="Auth scheme matches active environment.",
            )

        needs_refresh = (active_scheme in cls.EPHEMERAL_SCHEMES) and (not residual.handles_token_refresh)
        return AuthBindingVerdict(
            residual_id=residual.residual_id,
            bind_auth_handshake=False,
            bind_downstream_payload=True,
            requires_refresh_wrapper=needs_refresh,
            resolution_note=(
                f"REFUSE legacy auth handshake ({residual.assumed_scheme.value}); replaced by "
                f"{active_scheme.value}. Retain payload invariant ('{residual.downstream_payload_invariant}')"
                + (" and wrap in ephemeral token-refresh handler." if needs_refresh else ".")
            ),
        )

    @classmethod
    def assert_auth_handshake_valid(
        cls,
        residual: ResidualAuthMetadata,
        *,
        active_scheme: AuthSchemeType,
    ) -> AuthBindingVerdict:
        verdict = cls.evaluate_auth_compatibility(residual, active_scheme=active_scheme)
        if not verdict.bind_auth_handshake:
            raise ReplacedAuthSchemeRefusalError(verdict.resolution_note)
        return verdict