mip-wrapper 0.1.0__py3-none-any.whl

mip_wrapper/__init__.py

@@ -0,0 +1,47 @@
+"""MIP Wrapper: Python interface for Microsoft Information Protection decryption."""
+
+from mip_wrapper.client import MipClient
+from mip_wrapper.exceptions import (
+    AuthenticationError,
+    AuthorizationError,
+    CleanupError,
+    DecryptionError,
+    DestinationError,
+    InvalidConfigurationError,
+    MipError,
+    MissingRuntimeError,
+    NativeRuntimeError,
+    PermissionDeniedError,
+    ProtocolError,
+    UnsupportedFileTypeError,
+    UnsupportedProtectionError,
+)
+from mip_wrapper.auth import AuthBase, CertificateAuth, ClientSecretAuth
+from mip_wrapper.artifacts import DecryptedFile, FileInfo
+from mip_wrapper.version import PACKAGE_VERSION, PROTOCOL_VERSION
+
+__version__ = PACKAGE_VERSION
+
+__all__ = [
+    "MipClient",
+    "MipError",
+    "AuthenticationError",
+    "AuthorizationError",
+    "PermissionDeniedError",
+    "UnsupportedProtectionError",
+    "UnsupportedFileTypeError",
+    "InvalidConfigurationError",
+    "NativeRuntimeError",
+    "ProtocolError",
+    "DecryptionError",
+    "CleanupError",
+    "DestinationError",
+    "MissingRuntimeError",
+    "AuthBase",
+    "CertificateAuth",
+    "ClientSecretAuth",
+    "DecryptedFile",
+    "FileInfo",
+    "PACKAGE_VERSION",
+    "PROTOCOL_VERSION",
+]

mip_wrapper/artifacts.py

@@ -0,0 +1,82 @@
+"""Decrypted file artifacts."""
+
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+class DecryptedFile:
+    """Artifact representing a decrypted temporary file."""
+
+    def __init__(
+        self,
+        path: Path,
+        filename: str,
+        file_format: str,
+        size_bytes: int | None = None,
+        audit_metadata: dict[str, str] | None = None,
+    ) -> None:
+        """
+        Initialize decrypted file artifact.
+
+        Args:
+            path: Path to the decrypted file
+            filename: Original filename
+            file_format: File extension (.xlsx, .pdf, etc.)
+            size_bytes: Size of decrypted file (if known)
+            audit_metadata: Safe audit metadata
+        """
+        self.path = path
+        self.filename = filename
+        self.file_format = file_format
+        self.size_bytes = size_bytes
+        self.audit_metadata = audit_metadata or {}
+        self.decryption_timestamp = datetime.now(timezone.utc)
+
+    def __repr__(self) -> str:
+        return f"DecryptedFile(path={self.path}, filename={self.filename})"
+
+
+class FileInfo:
+    """Metadata about a protected file."""
+
+    def __init__(
+        self,
+        is_protected: bool,
+        label_id: str | None,
+        tenant_id: str | None,
+        file_format: str,
+        protection_type: str,
+        usage_rights: list[str],
+        can_decrypt: bool,
+        sdk_version: str,
+        helper_version: str,
+    ) -> None:
+        """
+        Initialize file info.
+
+        Args:
+            is_protected: Whether file is MIP-protected
+            label_id: Sensitivity label ID (if available)
+            tenant_id: Tenant ID where file is protected
+            file_format: File extension
+            protection_type: Type of protection (azure_rms, etc.)
+            usage_rights: Available rights for current user
+            can_decrypt: Whether current config can decrypt
+            sdk_version: MIP SDK version
+            helper_version: Helper version
+        """
+        self.is_protected = is_protected
+        self.label_id = label_id
+        self.tenant_id = tenant_id
+        self.file_format = file_format
+        self.protection_type = protection_type
+        self.usage_rights = usage_rights
+        self.can_decrypt = can_decrypt
+        self.sdk_version = sdk_version
+        self.helper_version = helper_version
+
+    def __repr__(self) -> str:
+        return (
+            f"FileInfo(protected={self.is_protected}, "
+            f"label={self.label_id}, rights={self.usage_rights})"
+        )

mip_wrapper/auth.py

@@ -0,0 +1,101 @@
+"""Authentication configuration."""
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+from mip_wrapper.exceptions import InvalidConfigurationError
+
+
+class AuthBase(ABC):
+    """Base class for authentication methods."""
+
+    tenant_id: str
+    client_id: str
+
+    @abstractmethod
+    def validate(self) -> None:
+        """Validate configuration is complete."""
+        pass
+
+
+class CertificateAuth(AuthBase):
+    """Certificate-based authentication (recommended)."""
+
+    def __init__(
+        self,
+        tenant_id: str,
+        client_id: str,
+        certificate_path: str,
+        certificate_password_path: str | None = None,
+    ) -> None:
+        """
+        Configure certificate-based authentication.
+
+        Args:
+            tenant_id: Azure AD tenant ID (UUID or domain)
+            client_id: App registration client ID (UUID)
+            certificate_path: Path to .pfx certificate file
+            certificate_password_path: Path to file containing certificate password
+                                       (optional if cert has no password)
+        """
+        self.tenant_id = tenant_id
+        self.client_id = client_id
+        self.certificate_path = certificate_path
+        self.certificate_password_path = certificate_password_path
+
+    def validate(self) -> None:
+        """Validate certificate paths exist."""
+        if not self.tenant_id or not self.client_id:
+            raise InvalidConfigurationError(
+                "tenant_id and client_id are required",
+                error_code="MissingAuth",
+            )
+
+        cert_path = Path(self.certificate_path)
+        if not cert_path.exists():
+            raise InvalidConfigurationError(
+                f"Certificate file not found: {self.certificate_path}",
+                error_code="CertificateNotFound",
+            )
+
+        if self.certificate_password_path:
+            pwd_path = Path(self.certificate_password_path)
+            if not pwd_path.exists():
+                raise InvalidConfigurationError(
+                    f"Certificate password file not found: {self.certificate_password_path}",
+                    error_code="PasswordFileNotFound",
+                )
+
+
+class ClientSecretAuth(AuthBase):
+    """Client secret authentication (less secure, for development)."""
+
+    def __init__(
+        self,
+        tenant_id: str,
+        client_id: str,
+        secret_provider: callable,
+    ) -> None:
+        """
+        Configure client secret authentication.
+
+        Args:
+            tenant_id: Azure AD tenant ID
+            client_id: App registration client ID
+            secret_provider: Callable that returns the client secret
+
+        Note:
+            Client secrets should be stored securely (Key Vault, etc.)
+            This method is less secure than certificate authentication.
+        """
+        self.tenant_id = tenant_id
+        self.client_id = client_id
+        self.secret_provider = secret_provider
+
+    def validate(self) -> None:
+        """Validate configuration."""
+        if not self.tenant_id or not self.client_id:
+            raise InvalidConfigurationError(
+                "tenant_id and client_id are required",
+                error_code="MissingAuth",
+            )

mip_wrapper/bridge/__init__.py

@@ -0,0 +1,17 @@
+"""Bridge between Python and .NET helper."""
+
+from mip_wrapper.bridge.client import HelperClient
+from mip_wrapper.bridge.protocol import (
+    DecryptResult,
+    InspectResult,
+    ProtocolRequest,
+    ProtocolResponse,
+)
+
+__all__ = [
+    "HelperClient",
+    "ProtocolRequest",
+    "ProtocolResponse",
+    "InspectResult",
+    "DecryptResult",
+]

mip_wrapper/bridge/client.py

@@ -0,0 +1,271 @@
+"""Bridge client: Python process management of .NET helper."""
+
+import json
+import logging
+import queue
+import subprocess
+import sys
+import threading
+from pathlib import Path
+from typing import Any
+
+from mip_wrapper.exceptions import NativeRuntimeError, ProtocolError
+from mip_wrapper.bridge.protocol import (
+    DecryptResult,
+    InspectResult,
+    ProtocolRequest,
+    ProtocolResponse,
+)
+from mip_wrapper.version import check_helper_version, check_protocol_version
+
+logger = logging.getLogger(__name__)
+
+
+class HelperClient:
+    """Manages the .NET MipWrapper.Helper process."""
+
+    def __init__(self, helper_path: Path, timeout_seconds: int = 120) -> None:
+        """
+        Initialize helper client.
+
+        Args:
+            helper_path: Path to MipWrapper.Helper executable
+            timeout_seconds: Process timeout for operations
+        """
+        self.helper_path = helper_path
+        self.timeout_seconds = timeout_seconds
+        self._process: subprocess.Popen[str] | None = None
+        self._stdout_queue: queue.Queue[str | None] | None = None
+        logger.debug(f"HelperClient initialized: {helper_path}")
+
+    def _read_stdout(self, process: subprocess.Popen[str], output: queue.Queue[str | None]) -> None:
+        if process.stdout is None:
+            output.put(None)
+            return
+        try:
+            for line in iter(process.stdout.readline, ""):
+                if not isinstance(line, str):
+                    break
+                output.put(line)
+        finally:
+            output.put(None)
+
+    def _drain_stderr(self, process: subprocess.Popen[str]) -> None:
+        if process.stderr is None:
+            return
+        for line in iter(process.stderr.readline, ""):
+            if not isinstance(line, str):
+                break
+            sys.stderr.write(line)
+            sys.stderr.flush()
+
+    def _spawn_helper(self) -> subprocess.Popen[str]:
+        """Spawn helper process if not already running."""
+        if self._process is not None:
+            return self._process
+
+        try:
+            self._process = subprocess.Popen(
+                [str(self.helper_path)],
+                stdin=subprocess.PIPE,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+                bufsize=1,
+            )
+            self._stdout_queue = queue.Queue()
+            threading.Thread(target=self._read_stdout, args=(self._process, self._stdout_queue), daemon=True).start()
+            threading.Thread(target=self._drain_stderr, args=(self._process,), daemon=True).start()
+            logger.debug("Helper process spawned")
+        except FileNotFoundError as e:
+            raise NativeRuntimeError(
+                f"Helper executable not found: {self.helper_path}",
+                error_code="HelperNotFound",
+            ) from e
+        except Exception as e:
+            raise NativeRuntimeError(
+                f"Failed to spawn helper: {e}",
+                error_code="HelperSpawnFailed",
+            ) from e
+
+        return self._process
+
+    def _terminate_helper(self) -> None:
+        process = self._process
+        self._process = None
+        self._stdout_queue = None
+        if process is None:
+            return
+
+        try:
+            try:
+                process.terminate()
+            except Exception:
+                pass
+
+            try:
+                process.wait(timeout=2)
+            except Exception:
+                try:
+                    process.kill()
+                except Exception:
+                    pass
+                try:
+                    process.wait(timeout=2)
+                except Exception:
+                    pass
+        finally:
+            for pipe in (process.stdin, process.stdout, process.stderr):
+                if pipe is not None:
+                    try:
+                        pipe.close()
+                    except Exception:
+                        pass
+
+    def _send_request(self, request: ProtocolRequest) -> ProtocolResponse:
+        """Send request to helper and get response."""
+        process = self._spawn_helper()
+
+        if process.stdin is None or process.stdout is None:
+            raise NativeRuntimeError(
+                "Helper process pipes are not available",
+                error_code="HelperPipeFailed",
+            )
+
+        try:
+            request_json = request.to_json()
+            logger.debug(f"Sending request: {request.command}")
+            process.stdin.write(request_json + "\n")
+            process.stdin.flush()
+
+            if self._stdout_queue is None:
+                raise NativeRuntimeError(
+                    "Helper stdout reader is not available",
+                    error_code="HelperPipeFailed",
+                )
+
+            try:
+                response_json = self._stdout_queue.get(
+                    timeout=request.timeout_seconds or self.timeout_seconds
+                )
+            except queue.Empty as error:
+                self._terminate_helper()
+                raise NativeRuntimeError(
+                    f"Helper operation timed out: {request.command}",
+                    error_code="HelperTimeout",
+                ) from error
+
+            if response_json is None:
+                self._terminate_helper()
+                raise ProtocolError(
+                    f"Helper exited before responding to {request.command}",
+                    error_code="HelperTerminated",
+                )
+
+            if not response_json:
+                raise ProtocolError(
+                    "Helper process terminated without response",
+                    error_code="HelperTerminated",
+                )
+
+            logger.debug("Received response from helper")
+            response = ProtocolResponse.from_json(response_json)
+
+            # Validate protocol version
+            try:
+                check_protocol_version(response.protocol_version)
+            except ValueError as e:
+                raise ProtocolError(str(e), error_code="ProtocolVersionMismatch") from e
+
+            return response
+
+        except (BrokenPipeError, OSError) as e:
+            raise ProtocolError(
+                f"Communication with helper failed: {e}",
+                error_code="ProtocolFailed",
+            ) from e
+
+    def inspect(
+        self,
+        tenant_id: str,
+        client_id: str,
+        certificate_path: str,
+        authorization_mode: str,
+        delegated_user: str | None,
+        source_path: str,
+        timeout_seconds: int | None = None,
+        client_secret: str | None = None,
+    ) -> InspectResult:
+        """
+        Inspect file protection metadata.
+
+        Returns:
+            InspectResult with file metadata
+        """
+        request = ProtocolRequest(
+            command="inspect",
+            tenant_id=tenant_id,
+            client_id=client_id,
+            certificate_path=certificate_path,
+            authorization_mode=authorization_mode,
+            delegated_user=delegated_user,
+            source_path=source_path,
+            timeout_seconds=timeout_seconds or self.timeout_seconds,
+            client_secret=client_secret,
+        )
+
+        response = self._send_request(request)
+        data = response.ensure_success()
+        return InspectResult.from_response(data)
+
+    def decrypt(
+        self,
+        tenant_id: str,
+        client_id: str,
+        certificate_path: str,
+        authorization_mode: str,
+        delegated_user: str | None,
+        source_path: str,
+        output_path: str,
+        timeout_seconds: int | None = None,
+        client_secret: str | None = None,
+    ) -> DecryptResult:
+        """
+        Decrypt file to output path.
+
+        Returns:
+            DecryptResult with output path and size
+        """
+        request = ProtocolRequest(
+            command="decrypt",
+            tenant_id=tenant_id,
+            client_id=client_id,
+            certificate_path=certificate_path,
+            authorization_mode=authorization_mode,
+            delegated_user=delegated_user,
+            source_path=source_path,
+            output_path=output_path,
+            timeout_seconds=timeout_seconds or self.timeout_seconds,
+            client_secret=client_secret,
+        )
+
+        response = self._send_request(request)
+        data = response.ensure_success()
+        return DecryptResult.from_response(data)
+
+    def shutdown(self) -> None:
+        """Shutdown helper process gracefully."""
+        if self._process is None:
+            return
+
+        try:
+            request = ProtocolRequest(command="shutdown")
+            self._send_request(request)
+        except Exception as e:
+            logger.warning(f"Shutdown request failed: {e}")
+        finally:
+            self._terminate_helper()
+
+    def __del__(self) -> None:
+        """Cleanup on deletion."""
+        self.shutdown()

mip_wrapper/bridge/protocol.py

@@ -0,0 +1,159 @@
+"""Protocol v1.0: JSON communication between Python and .NET helper."""
+
+import json
+import uuid
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+
+PROTOCOL_VERSION = "1.0"
+
+
+@dataclass
+class ProtocolRequest:
+    """Request to send to helper."""
+
+    protocol_version: str = PROTOCOL_VERSION
+    request_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    command: str = ""
+    tenant_id: str = ""
+    client_id: str = ""
+    certificate_path: str = ""
+    authorization_mode: str = ""
+    delegated_user: str | None = None
+    source_path: str | None = None
+    output_path: str | None = None
+    timeout_seconds: int = 120
+    client_secret: str | None = None
+
+    def to_json(self) -> str:
+        """Serialize to JSON."""
+        data = asdict(self)
+        data = {k: v for k, v in data.items() if v is not None}
+        return json.dumps(data)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "ProtocolRequest":
+        """Create from dictionary."""
+        return cls(**{k: v for k, v in data.items() if k in cls.__dataclass_fields__})
+
+
+@dataclass
+class ProtocolResponse:
+    """Response from helper."""
+
+    protocol_version: str
+    request_id: str
+    success: bool
+    result: dict[str, Any] | None = None
+    error: dict[str, str] | None = None
+
+    @classmethod
+    def from_json(cls, json_str: str) -> "ProtocolResponse":
+        """Parse from JSON."""
+        try:
+            data = json.loads(json_str)
+        except json.JSONDecodeError as e:
+            raise ValueError(f"Invalid JSON response: {e}") from e
+
+        return cls(
+            protocol_version=data.get("protocol_version", ""),
+            request_id=data.get("request_id", ""),
+            success=data.get("success", False),
+            result=data.get("result"),
+            error=data.get("error"),
+        )
+
+    def validate_version(self) -> None:
+        """Validate protocol version matches."""
+        if self.protocol_version != PROTOCOL_VERSION:
+            raise ValueError(
+                f"Unsupported protocol version: {self.protocol_version} "
+                f"(expected {PROTOCOL_VERSION})"
+            )
+
+    def ensure_success(self) -> dict[str, Any]:
+        """Raise if not successful."""
+        if not self.success:
+            from mip_wrapper.exceptions import (
+                DecryptionError,
+                PermissionDeniedError,
+                UnsupportedFileTypeError,
+                UnsupportedProtectionError,
+                ProtocolError,
+                NativeRuntimeError,
+            )
+
+            error = self.error or {}
+            code = error.get("code", "UnknownError")
+            message = error.get("message", "Unknown error")
+
+            # Map error codes to typed exceptions
+            error_map = {
+                "PermissionDenied": PermissionDeniedError,
+                "Unauthorized": PermissionDeniedError,
+                "UnsupportedFormat": UnsupportedFileTypeError,
+                "UnsupportedProtectionType": UnsupportedProtectionError,
+                "ProtocolError": ProtocolError,
+                "DecryptionError": DecryptionError,
+                "FileNotFound": DecryptionError,
+                "CertificateNotFound": NativeRuntimeError,
+                "CertificateLoadError": NativeRuntimeError,
+                "TokenAcquisitionError": NativeRuntimeError,
+            }
+
+            exception_class = error_map.get(code, NativeRuntimeError)
+            raise exception_class(
+                message,
+                error_code=code,
+                audit_metadata={"helper_error": code},
+            )
+        return self.result or {}
+
+
+@dataclass
+class InspectResult:
+    """Result of inspect command."""
+
+    is_protected: bool
+    label_id: str | None
+    tenant_id: str | None
+    file_format: str
+    protection_type: str
+    usage_rights: list[str]
+    can_decrypt: bool
+    sdk_version: str
+    helper_version: str
+
+    @classmethod
+    def from_response(cls, data: dict[str, Any]) -> "InspectResult":
+        """Create from protocol response."""
+        return cls(
+            is_protected=data.get("is_protected", False),
+            label_id=data.get("label_id"),
+            tenant_id=data.get("tenant_id"),
+            file_format=data.get("file_format", ""),
+            protection_type=data.get("protection_type", ""),
+            usage_rights=data.get("usage_rights", []),
+            can_decrypt=data.get("can_decrypt", False),
+            sdk_version=data.get("sdk_version", ""),
+            helper_version=data.get("helper_version", ""),
+        )
+
+
+@dataclass
+class DecryptResult:
+    """Result of decrypt command."""
+
+    output_path: str
+    size_bytes: int
+    file_format: str
+
+    @classmethod
+    def from_response(cls, data: dict[str, Any]) -> "DecryptResult":
+        """Create from protocol response."""
+        return cls(
+            output_path=data.get("output_path", ""),
+            size_bytes=data.get("size_bytes", 0),
+            file_format=data.get("file_format", ""),
+        )

mip_wrapper/client.py

@@ -0,0 +1,260 @@
+"""Main MIP Wrapper client."""
+
+import logging
+import os
+import shutil
+import tempfile
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Generator
+
+from mip_wrapper.artifacts import DecryptedFile, FileInfo
+from mip_wrapper.auth import AuthBase, CertificateAuth, ClientSecretAuth
+from mip_wrapper.bridge.client import HelperClient
+from mip_wrapper.exceptions import (
+    CleanupError,
+    InvalidConfigurationError,
+    MissingRuntimeError,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class MipClient:
+    """Client for MIP file operations."""
+
+    def __init__(
+        self,
+        auth: AuthBase,
+        authorization_mode: str,
+        delegated_user: str | None = None,
+        helper_path: str | None = None,
+        correlation_id: str | None = None,
+        timeout_seconds: int = 120,
+    ) -> None:
+        """
+        Initialize MipClient.
+
+        Args:
+            auth: Authentication configuration (CertificateAuth, ClientSecretAuth)
+            authorization_mode: "delegated_reader" or "super_user"
+            delegated_user: User UPN for delegated_reader mode (required if using that mode)
+            helper_path: Path to MipWrapper.Helper executable
+            correlation_id: Correlation ID for audit/logging
+            timeout_seconds: Operation timeout
+        """
+        auth.validate()
+
+        if authorization_mode != "delegated_reader":
+            raise InvalidConfigurationError(
+                f"Invalid authorization_mode: {authorization_mode}",
+                error_code="InvalidAuthMode",
+            )
+
+        if authorization_mode == "delegated_reader" and not delegated_user:
+            raise InvalidConfigurationError(
+                "delegated_user is required for delegated_reader mode",
+                error_code="MissingDelegatedUser",
+            )
+
+        self.auth = auth
+        self.authorization_mode = authorization_mode
+        self.delegated_user = delegated_user
+        self.correlation_id = correlation_id or ""
+        self.timeout_seconds = timeout_seconds
+
+        # Find helper executable
+        if helper_path:
+            self.helper_path = Path(helper_path)
+        else:
+            self.helper_path = self._find_helper()
+
+        self.helper = HelperClient(self.helper_path, timeout_seconds)
+        self._version_checked = False
+
+    def _check_version_compatibility(self, helper_version: str) -> None:
+        """Check helper version compatibility on first use."""
+        if self._version_checked:
+            return
+
+        from mip_wrapper.version import check_helper_version
+
+        try:
+            check_helper_version(helper_version)
+            self._version_checked = True
+            logger.info(f"Helper version {helper_version} is compatible")
+        except ValueError as e:
+            raise InvalidConfigurationError(
+                str(e),
+                error_code="VersionMismatch",
+            ) from e
+
+    def _find_helper(self) -> Path:
+        """
+        Find MipWrapper.Helper executable using search order:
+        1. MIP_WRAPPER_HELPER_PATH environment variable
+        2. Current working directory
+        3. Package installation directory (future)
+        """
+        # 1. Check environment variable
+        env_path = os.environ.get("MIP_WRAPPER_HELPER_PATH")
+        if env_path:
+            path = Path(env_path)
+            if path.exists():
+                logger.debug(f"Found helper via MIP_WRAPPER_HELPER_PATH: {path}")
+                return path
+            logger.warning(f"MIP_WRAPPER_HELPER_PATH set but file not found: {env_path}")
+
+        # 2. Try common locations
+        candidates = [
+            Path.cwd() / "MipWrapper.Helper",
+            Path.cwd() / "MipWrapper.Helper.exe",
+            Path.cwd() / "helper-bin" / "MipWrapper.Helper",
+            Path.cwd() / "helper-bin" / "MipWrapper.Helper.exe",
+            Path(__file__).parent.parent.parent / "helper-bin" / "MipWrapper.Helper",
+            Path(__file__).parent.parent.parent / "helper-bin" / "MipWrapper.Helper.exe",
+        ]
+
+        for candidate in candidates:
+            if candidate.exists():
+                logger.debug(f"Found helper at: {candidate}")
+                return candidate
+
+        # 3. Provide clear error with instructions
+        raise MissingRuntimeError(
+            "MipWrapper.Helper executable not found. "
+            "\n\nTo use mip_wrapper, you must:\n"
+            "1. Build the .NET helper:\n"
+            "   cd native/MipWrapper.Helper\n"
+            "   dotnet publish -c Release -o ../../helper-bin\n"
+            "\n2. Make it discoverable:\n"
+            "   - Set MIP_WRAPPER_HELPER_PATH=/path/to/MipWrapper.Helper\n"
+            "   - Or place in current directory or helper-bin/\n"
+            "   - Or pass helper_path parameter to MipClient()\n"
+            "\nSee BUILD_LOCALLY.md for detailed instructions.",
+            error_code="HelperNotFound",
+        )
+
+    def inspect(self, source_path: str) -> FileInfo:
+        """
+        Inspect file protection metadata.
+
+        Args:
+            source_path: Path to protected file
+
+        Returns:
+            FileInfo with metadata
+        """
+        logger.info(f"Inspecting file: {source_path}")
+
+        # Get client secret if using ClientSecretAuth
+        client_secret = None
+        if isinstance(self.auth, ClientSecretAuth):
+            client_secret = self.auth.secret_provider()
+
+        result = self.helper.inspect(
+            tenant_id=self.auth.tenant_id,
+            client_id=self.auth.client_id,
+            certificate_path=self.auth.certificate_path
+            if isinstance(self.auth, CertificateAuth)
+            else "",
+            authorization_mode=self.authorization_mode,
+            delegated_user=self.delegated_user,
+            source_path=source_path,
+            client_secret=client_secret,
+        )
+
+        # Check version compatibility on first use
+        self._check_version_compatibility(result.helper_version)
+
+        return FileInfo(
+            is_protected=result.is_protected,
+            label_id=result.label_id,
+            tenant_id=result.tenant_id,
+            file_format=result.file_format,
+            protection_type=result.protection_type,
+            usage_rights=result.usage_rights,
+            can_decrypt=result.can_decrypt,
+            sdk_version=result.sdk_version,
+            helper_version=result.helper_version,
+        )
+
+    @contextmanager
+    def decrypted_file(self, source_path: str) -> Generator[DecryptedFile, None, None]:
+        """
+        Context manager for temporary file decryption.
+
+        Automatically cleans up after use.
+
+        Args:
+            source_path: Path to protected file
+
+        Yields:
+            DecryptedFile artifact with temporary file path
+
+        Raises:
+            PermissionDeniedError: If user lacks Export right
+        """
+        temp_dir = None
+        try:
+            # Create secure temporary directory
+            temp_dir = tempfile.mkdtemp(prefix="mipwrapper_", dir=None)
+            logger.debug(f"Created temp directory: {temp_dir}")
+            temp_path = Path(temp_dir)
+            temp_path.chmod(0o700)
+
+            # Get source filename
+            source = Path(source_path)
+            output_filename = source.name
+            output_path = str(temp_path / output_filename)
+
+            # Decrypt
+            logger.info(f"Decrypting to temp: {source_path}")
+
+            # Get client secret if using ClientSecretAuth
+            client_secret = None
+            if isinstance(self.auth, ClientSecretAuth):
+                client_secret = self.auth.secret_provider()
+
+            result = self.helper.decrypt(
+                tenant_id=self.auth.tenant_id,
+                client_id=self.auth.client_id,
+                certificate_path=self.auth.certificate_path
+                if isinstance(self.auth, CertificateAuth)
+                else "",
+                authorization_mode=self.authorization_mode,
+                delegated_user=self.delegated_user,
+                source_path=source_path,
+                output_path=output_path,
+                client_secret=client_secret,
+            )
+
+            # Yield artifact
+            artifact = DecryptedFile(
+                path=Path(result.output_path),
+                filename=output_filename,
+                file_format=result.file_format,
+                size_bytes=result.size_bytes,
+                audit_metadata={
+                    "source": source_path,
+                    "authorization_mode": self.authorization_mode,
+                    "correlation_id": self.correlation_id,
+                },
+            )
+            yield artifact
+
+        except Exception as e:
+            logger.error(f"Decryption failed: {e}")
+            raise
+
+        finally:
+            # Cleanup
+            if temp_dir:
+                try:
+                    shutil.rmtree(temp_dir)
+                    logger.debug(f"Cleaned up temp directory: {temp_dir}")
+                except Exception as cleanup_error:
+                    raise CleanupError(
+                        f"Failed to remove temporary plaintext directory: {temp_dir}",
+                        error_code="CleanupFailed",
+                    ) from cleanup_error

mip_wrapper/exceptions.py

@@ -0,0 +1,90 @@
+"""MIP Wrapper exception hierarchy."""
+
+from typing import Any
+
+
+class MipError(Exception):
+    """Base exception for all MIP Wrapper errors."""
+
+    def __init__(
+        self,
+        message: str,
+        error_code: str | None = None,
+        audit_metadata: dict[str, str] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.error_code = error_code
+        self.audit_metadata = audit_metadata or {}
+
+
+class AuthenticationError(MipError):
+    """Authentication failed (certificate, token, etc.)."""
+
+    pass
+
+
+class AuthorizationError(MipError):
+    """Authorization check failed."""
+
+    pass
+
+
+class PermissionDeniedError(AuthorizationError):
+    """User lacks required usage right."""
+
+    pass
+
+
+class UnsupportedProtectionError(MipError):
+    """File protection type is not supported."""
+
+    pass
+
+
+class UnsupportedFileTypeError(MipError):
+    """File format is not supported."""
+
+    pass
+
+
+class InvalidConfigurationError(MipError):
+    """Configuration is invalid or incomplete."""
+
+    pass
+
+
+class NativeRuntimeError(MipError):
+    """Native helper (MipWrapper.Helper) error."""
+
+    pass
+
+
+class ProtocolError(NativeRuntimeError):
+    """Protocol communication or parsing error."""
+
+    pass
+
+
+class DecryptionError(NativeRuntimeError):
+    """File decryption failed."""
+
+    pass
+
+
+class CleanupError(NativeRuntimeError):
+    """Cleanup of temporary files failed."""
+
+    pass
+
+
+class DestinationError(MipError):
+    """Error uploading to destination."""
+
+    pass
+
+
+class MissingRuntimeError(MipError):
+    """MipWrapper.Helper or required runtime not available."""
+
+    pass

mip_wrapper/version.py

@@ -0,0 +1,55 @@
+"""Version information and compatibility checking."""
+
+from packaging import version as pkg_version
+
+# Package version
+PACKAGE_VERSION = "0.1.0"
+
+# Supported protocol version
+PROTOCOL_VERSION = "1.0"
+
+# Minimum helper version
+MIN_HELPER_VERSION = "1.0.0"
+
+# MIP SDK version we expect
+MIP_SDK_VERSION = "1.18.124"
+
+
+def check_helper_version(helper_version: str) -> None:
+    """
+    Check helper version compatibility.
+
+    Args:
+        helper_version: Version string from helper
+
+    Raises:
+        ValueError: If helper version is incompatible
+    """
+    try:
+        helper_v = pkg_version.parse(helper_version)
+        min_v = pkg_version.parse(MIN_HELPER_VERSION)
+
+        if helper_v < min_v:
+            raise ValueError(
+                f"Helper version {helper_version} is older than minimum "
+                f"required {MIN_HELPER_VERSION}. Please rebuild the helper."
+            )
+    except (ValueError, pkg_version.InvalidVersion) as e:
+        raise ValueError(f"Cannot parse helper version '{helper_version}': {e}") from e
+
+
+def check_protocol_version(protocol_version: str) -> None:
+    """
+    Check protocol version compatibility.
+
+    Args:
+        protocol_version: Version string from protocol
+
+    Raises:
+        ValueError: If protocol version is incompatible
+    """
+    if protocol_version != PROTOCOL_VERSION:
+        raise ValueError(
+            f"Protocol version mismatch: helper uses {protocol_version}, "
+            f"package expects {PROTOCOL_VERSION}"
+        )

mip_wrapper-0.1.0.dist-info/METADATA

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: mip-wrapper
+Version: 0.1.0
+Summary: Unofficial Python wrapper for Microsoft Information Protection file decryption
+License-Expression: MIT
+Project-URL: Repository, https://github.com/firaun2020/mip-wrapper
+Project-URL: Documentation, https://github.com/firaun2020/mip-wrapper/tree/main/docs
+Project-URL: Issues, https://github.com/firaun2020/mip-wrapper/issues
+Keywords: mip,information-protection,azure-rights-management,decryption
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: packaging>=21.0
+Dynamic: license-file
+
+# mip-wrapper
+
+Unofficial Python wrapper for inspecting and decrypting files protected by Microsoft Purview Information Protection. The Python package starts a local JSON subprocess bridge to a separately built .NET helper, which calls the Microsoft Information Protection File SDK.
+
+## Scope
+
+- Windows x64 only
+- Python 3.11 or newer
+- `delegated_reader` is the only supported authorization mode
+- Unattended client-secret authentication via MSAL
+- Local file inspection and temporary decryption
+- No DRM bypass: the delegated user must have the required document usage right
+
+The package does not bundle the .NET helper or Microsoft MIP SDK binaries. Build and install the helper separately, and ensure its Microsoft SDK licensing and redistribution terms are satisfied for your environment.
+
+## Installation
+
+```powershell
+python -m pip install mip-wrapper
+dotnet publish native/MipWrapper.Helper/MipWrapper.Helper.csproj -c Release -o helper-bin
+$env:MIP_WRAPPER_HELPER_PATH = (Resolve-Path helper-bin/MipWrapper.Helper.exe)
+```
+
+The helper requires the .NET runtime targeted by the project and the native Microsoft MIP SDK runtime available to it. `MIP_WRAPPER_HELPER_PATH` may point to the published helper executable. The source repository's `helper-bin/` directory is a local build output and is not part of the Python distribution.
+
+## Usage
+
+```python
+import os
+from mip_wrapper import MipClient
+from mip_wrapper.auth import ClientSecretAuth
+
+auth = ClientSecretAuth(
+    tenant_id=os.environ["MIP_TENANT_ID"],
+    client_id=os.environ["MIP_CLIENT_ID"],
+    secret_provider=lambda: os.environ["MIP_CLIENT_SECRET"],
+)
+
+client = MipClient(
+    auth=auth,
+    authorization_mode="delegated_reader",
+    delegated_user="reader@contoso.com",
+)
+
+info = client.inspect("protected.xlsx")
+print(info.is_protected, info.usage_rights)
+
+with client.decrypted_file("protected.xlsx") as file:
+    process(file.path)
+```
+
+The context manager creates a temporary directory, returns the committed plaintext path, and removes the directory on normal exit and exceptions. A cleanup failure raises `CleanupError`. The original protected file is not used as the output path.
+
+## Entra and document authorization
+
+The app registration must be configured for the Microsoft Information Protection resource and granted the application permission required by the MIP SDK's delegated-reader flow, documented by Microsoft as `Content.DelegatedReader`, with tenant-admin consent. `delegated_reader` is package configuration terminology, not an Entra permission. The delegated user must independently have `Export` or `Owner` usage rights on the protected file; neither the package mode nor the app permission grants document access by itself.
+
+The helper acquires app-only tokens with `AcquireTokenForClient`, using the tenant supplied by the request and the MIP SDK challenge resource as `{resource}/.default`. It does not perform an interactive delegated-user sign-in.
+
+## Security and operational limits
+
+- Do not put client secrets in source code, command-line arguments, logs, or protocol diagnostics. Supply them through a secret provider such as an environment-backed secret store.
+- Protected file contents are written temporarily in plaintext while inside the context manager. Restrict host access and process only authorized content.
+- The helper protocol is local and line-delimited JSON; it is not an authenticated network service.
+- The package does not download, install, or update the helper or Microsoft SDK runtime.
+- Real tenant credentials and protected files are required for integration testing. Unit tests use fake helper processes and do not prove tenant authorization or MIP service connectivity.
+
+## Development
+
+```powershell
+python -m pip install -e .
+python -m pytest
+dotnet build native/MipWrapper.Helper/MipWrapper.Helper.csproj -c Release
+```
+
+See [`BUILD_LOCALLY.md`](BUILD_LOCALLY.md) for the local helper workflow. See [`docs/distribution-and-licensing.md`](docs/distribution-and-licensing.md) for the unresolved Microsoft SDK distribution and licensing questions. This project is not affiliated with or endorsed by Microsoft.
+
+## License
+
+The wrapper source is MIT licensed. The Microsoft Information Protection SDK and its native runtime are separately licensed by Microsoft; this repository does not grant rights to redistribute them.

mip_wrapper-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+mip_wrapper/__init__.py,sha256=y1GJwzyWAkE2H3ut0fg_hM6J-O-s_Rit2v4dyyTQfdA,1223
+mip_wrapper/artifacts.py,sha256=iYWJYsS0Y4MDnKlHxWIwTv9CCQKJIjohxoATuWLQAB0,2540
+mip_wrapper/auth.py,sha256=cJUWRrN5wpgje7OOmboCvM5eXKHY5snXA4f-Y7y2PXg,3228
+mip_wrapper/client.py,sha256=Lii0d6TFv8c5G9wH2qqCgO9EY4q7RqUAk2U0jxY3Qe0,9261
+mip_wrapper/exceptions.py,sha256=SXhqXTYgqKKMM8XlXr5yMwPXPSXdtOoSHbtFp0I3bNg,1653
+mip_wrapper/version.py,sha256=9udX3ZkFDELKgSbn-rb0f7md6ZEVB8C-kqzaj7JduCg,1502
+mip_wrapper/bridge/__init__.py,sha256=Neq9dKafeP2fJTAwClycJZ_nmcxpcmqq-tUUCRTYktI,346
+mip_wrapper/bridge/client.py,sha256=CIZ97sbrWNObem5zXufjPnOiKM64WWBzIktcScx2S4g,8859
+mip_wrapper/bridge/protocol.py,sha256=5-UEyhrpOKFyHvVSeNCLuXz58bPvU1bRngw5lvPXbos,5037
+mip_wrapper-0.1.0.dist-info/licenses/LICENSE,sha256=BZRGkAz03UQb_T8zLONmY8OLAdiTLYiDiODVbOPci3w,1081
+mip_wrapper-0.1.0.dist-info/METADATA,sha256=-oEntHSmAUzbBL7TcRaXybBAUfTj6Hhm1mwsGcyahBA,5341
+mip_wrapper-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+mip_wrapper-0.1.0.dist-info/top_level.txt,sha256=PQ2If1wExSGG8gNokgUESVTcKOSnniabGTcyohL9Apw,12
+mip_wrapper-0.1.0.dist-info/RECORD,,

mip_wrapper-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mip_wrapper-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mip-wrapper contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mip_wrapper-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mip_wrapper