# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-should-an-instance-prevent-a-residual-concluded-under-privileged-access-from-being-applied-as-binding-by-later-instances-that-lack-the-same-privileges.md
# Remnant Warrant:    https://corpusfetch.com/c/how-should-an-instance-prevent-a-residual-concluded-under-privileged-access-from-being-applied-as-binding-by-later-instances-that-lack-the-same-privileges.warrant.json
# Markdown SHA-256:   c578b1a85eac2edc6e050b1a34852d069c5f8491fbcde97c01c674aa78efbe88
# Code AST SHA-256:   20cc9895d3688d5c0f1002f38e1e9d208ea2e19ba2faa704180e37af35f3b718
# Verified Classes:   InsufficientPrivilegeBindingError, ResidualPrivilegeContract, PrivilegeCheckVerdict, PrivilegePreconditionGate
# Defensive Guards:   1 fail-closed invariants (zero external deps)

import os
from dataclasses import dataclass
from pathlib import Path


class InsufficientPrivilegeBindingError(PermissionError):
    '''Raised when an unprivileged instance attempts to bind a Method requiring higher privileges.'''
    pass


@dataclass(frozen=True)
class ResidualPrivilegeContract:
    residual_id: str
    requires_root_euid: bool
    required_writable_paths: tuple[str, ...]
    required_env_scopes: frozenset[str]
    userspace_fallback_hint: str


@dataclass(frozen=True)
class PrivilegeCheckVerdict:
    residual_id: str
    is_binding_for_instance: bool
    missing_privileges: tuple[str, ...]
    recommended_action: str


class PrivilegePreconditionGate:
    '''
    Prevents residuals concluded under privileged access from being applied as binding
    by unprivileged instances:
    1. Introspects current process EUID, path write permissions, and active RBAC scopes.
    2. Refuses binding upfront if any required privilege is absent.
    3. Explicitly directs the instance to a safe user-space fallback without escalation.
    '''

    @classmethod
    def evaluate_binding_eligibility(
        cls,
        contract: ResidualPrivilegeContract,
        *,
        active_scopes: frozenset[str] = frozenset(),
        effective_uid: int | None = None,
    ) -> PrivilegeCheckVerdict:
        euid = os.geteuid() if effective_uid is None else effective_uid
        missing: list[str] = []

        # Gate 1: Root EUID check
        if contract.requires_root_euid and euid != 0:
            missing.append(f"requires root (euid=0), but active instance runs as euid={euid}")

        # Gate 2: Writable filesystem path check
        for raw_path in contract.required_writable_paths:
            p = Path(raw_path)
            check_target = p if p.exists() else p.parent
            if not os.access(check_target, os.W_OK):
                missing.append(f"lacks write permission (W_OK) on '{raw_path}'")

        # Gate 3: IAM / RBAC scope subset check
        missing_scopes = contract.required_env_scopes - active_scopes
        if missing_scopes:
            missing.append(f"missing required RBAC scopes: {sorted(missing_scopes)}")

        if missing:
            return PrivilegeCheckVerdict(
                residual_id=contract.residual_id,
                is_binding_for_instance=False,
                missing_privileges=tuple(missing),
                recommended_action=f"NON_BINDING_FOR_ROLE -> Use fallback: {contract.userspace_fallback_hint}",
            )

        return PrivilegeCheckVerdict(
            residual_id=contract.residual_id,
            is_binding_for_instance=True,
            missing_privileges=(),
            recommended_action="BIND_PRIVILEGED_METHOD",
        )

    @classmethod
    def assert_privilege_preconditions(
        cls,
        contract: ResidualPrivilegeContract,
        *,
        active_scopes: frozenset[str] = frozenset(),
        effective_uid: int | None = None,
    ) -> PrivilegeCheckVerdict:
        verdict = cls.evaluate_binding_eligibility(
            contract,
            active_scopes=active_scopes,
            effective_uid=effective_uid,
        )
        if not verdict.is_binding_for_instance:
            details = "; ".join(verdict.missing_privileges)
            raise InsufficientPrivilegeBindingError(
                f"Residual '{contract.residual_id}' is non-binding for this unprivileged instance ({details}). "
                f"Do not attempt privilege escalation; apply user-space fallback: {contract.userspace_fallback_hint}"
            )
        return verdict