panda-crypto-py 0.1.0__py3-none-any.whl

panda/__init__.py

@@ -0,0 +1,62 @@
+"""
+PANDA - Private And Secure Data Access SDK for Python
+
+Field-level encryption and masking for sensitive personal data.
+"""
+
+__version__ = "0.1.0"
+
+from .crypto import (
+    FieldCipher,
+    Envelope,
+    LocalKeyProvider,
+    VaultKeyProvider,
+    InfisicalKeyProvider,
+    create_key_provider,
+    KeyNotFoundError,
+    AuthenticationFailedError,
+    EncryptionError
+)
+from .masking import Masker, MaskingConfig
+from .blind_index import BlindIndexer
+from .audit import AuditLogger, ConsoleAuditLogger, NullAuditLogger
+from .telemetry import TelemetryClient
+from .storage import TLSVerifier, MySqlAdapter, PostgresAdapter
+
+__all__ = [
+    # Version
+    "__version__",
+
+    # Core crypto
+    "FieldCipher",
+    "Envelope",
+    "LocalKeyProvider",
+    "VaultKeyProvider",
+    "InfisicalKeyProvider",
+    "create_key_provider",
+
+    # Errors
+    "KeyNotFoundError",
+    "AuthenticationFailedError",
+    "EncryptionError",
+
+    # Masking
+    "Masker",
+    "MaskingConfig",
+
+    # Blind Index
+    "BlindIndexer",
+
+    # Audit
+    "AuditLogger",
+    "ConsoleAuditLogger",
+    "NullAuditLogger",
+
+    # Telemetry
+    "TelemetryClient",
+
+    # Storage
+    "TLSVerifier",
+    "MySqlAdapter",
+    "PostgresAdapter",
+]

panda/audit/__init__.py

@@ -0,0 +1,23 @@
+"""
+Audit logging module for PANDA SDK.
+
+Provides structured logging of encryption/decryption events.
+"""
+
+from .logger import (
+    AuditLogger,
+    ConsoleAuditLogger,
+    FileAuditLogger,
+    NullAuditLogger,
+    EventType,
+    Outcome
+)
+
+__all__ = [
+    "AuditLogger",
+    "ConsoleAuditLogger",
+    "FileAuditLogger",
+    "NullAuditLogger",
+    "EventType",
+    "Outcome",
+]

panda/audit/logger.py

@@ -0,0 +1,160 @@
+"""
+Audit logging module for PANDA SDK.
+
+Provides structured logging of encryption/decryption events.
+"""
+
+import json
+import time
+from abc import ABC, abstractmethod
+from typing import Optional, Dict, Any
+from enum import Enum
+
+
+class EventType(Enum):
+    """Types of audit events."""
+    ENCRYPT = "encrypt"
+    DECRYPT_MASKED = "decrypt_masked"
+    DECRYPT_RAW = "decrypt_raw"
+    ROTATE = "rotate"
+    SHRED = "shred"
+
+
+class Outcome(Enum):
+    """Possible outcomes of an operation."""
+    SUCCESS = "success"
+    AUTH_FAILURE = "auth_failure"
+    MALFORMED_ENVELOPE = "malformed_envelope"
+    KEY_NOT_FOUND = "key_not_found"
+    ENCRYPTION_FAILED = "encryption_failed"
+    UNSUPPORTED_ENVELOPE_VERSION = "unsupported_envelope_version"
+    UNSUPPORTED_ALGORITHM = "unsupported_algorithm"
+
+
+class AuditLogger(ABC):
+    """
+    Abstract base class for audit loggers.
+
+    Audit loggers record encryption/decryption events for compliance
+    and security monitoring. All decrypt_raw() calls (full plaintext
+    exposure) are logged distinctly from masked decrypt operations.
+    """
+
+    @abstractmethod
+    def log(
+        self,
+        actor: str,
+        field: str,
+        kid: str,
+        event_type: EventType,
+        outcome: Outcome,
+        **extra
+    ) -> None:
+        """
+        Log an audit event.
+
+        Args:
+            actor: Identifier for the entity performing the action
+            field: Field name being accessed
+            kid: Key identifier used
+            event_type: Type of event
+            outcome: Outcome of the operation
+            **extra: Additional metadata to include in the log
+        """
+        pass
+
+
+class ConsoleAuditLogger(AuditLogger):
+    """Audit logger that writes to console (stdout/stderr)."""
+
+    def __init__(self, use_stderr: bool = False):
+        """
+        Initialize the console audit logger.
+
+        Args:
+            use_stderr: If True, write to stderr instead of stdout
+        """
+        import sys
+        self._output = sys.stderr if use_stderr else sys.stdout
+
+    def log(
+        self,
+        actor: str,
+        field: str,
+        kid: str,
+        event_type: EventType,
+        outcome: Outcome,
+        **extra
+    ) -> None:
+        """Log an audit event to console."""
+        event = {
+            "timestamp": time.time(),
+            "actor": actor,
+            "field": field,
+            "kid": kid,
+            "eventType": event_type.value if isinstance(event_type, EventType) else event_type,
+            "outcome": outcome.value if isinstance(outcome, Outcome) else outcome,
+            **extra
+        }
+        self._output.write(json.dumps(event) + "\n")
+
+
+class FileAuditLogger(AuditLogger):
+    """Audit logger that writes to a file."""
+
+    def __init__(self, file_path: str):
+        """
+        Initialize the file audit logger.
+
+        Args:
+            file_path: Path to the audit log file
+        """
+        self._file_path = file_path
+
+    def log(
+        self,
+        actor: str,
+        field: str,
+        kid: str,
+        event_type: EventType,
+        outcome: Outcome,
+        **extra
+    ) -> None:
+        """Log an audit event to file."""
+        event = {
+            "timestamp": time.time(),
+            "actor": actor,
+            "field": field,
+            "kid": kid,
+            "eventType": event_type.value if isinstance(event_type, EventType) else event_type,
+            "outcome": outcome.value if isinstance(outcome, Outcome) else outcome,
+            **extra
+        }
+
+        try:
+            with open(self._file_path, "a", encoding="utf-8") as f:
+                f.write(json.dumps(event) + "\n")
+        except IOError as e:
+            # Fail silently to avoid breaking the application
+            # In production, you might want to log to stderr or a fallback
+            pass
+
+
+class NullAuditLogger(AuditLogger):
+    """
+    No-op audit logger that discards all events.
+
+    Use this for development/testing or when audit logging is not required.
+    """
+
+    def log(
+        self,
+        actor: str,
+        field: str,
+        kid: str,
+        event_type: EventType,
+        outcome: Outcome,
+        **extra
+    ) -> None:
+        """Discard the log entry."""
+        pass

panda/blind_index/__init__.py

@@ -0,0 +1,11 @@
+"""
+Blind index module for PANDA SDK.
+
+Provides deterministic indexing for searchable encrypted fields.
+"""
+
+from .blind_index import BlindIndexer
+
+__all__ = [
+    "BlindIndexer",
+]

panda/blind_index/blind_index.py

@@ -0,0 +1,145 @@
+"""
+Blind index module for PANDA SDK.
+
+Provides deterministic hashing for searchable encrypted fields.
+"""
+
+import hmac
+import hashlib
+import base64
+from typing import Union
+
+
+class BlindIndexer:
+    """
+    Deterministic indexing for encrypted fields using HMAC-SHA256.
+
+    Blind indexes enable exact-match searches on encrypted fields
+    without storing searchable plaintext or using deterministic encryption.
+
+    The index is computed as: HMAC-SHA256(blind_index_key, normalize(plaintext))
+
+    Security Note: Blind indexes leak equality patterns. An attacker who
+    gains database access can determine which records have the same value
+    for a field. Use with caution on low-cardinality fields.
+    """
+
+    # Normalization modes
+    NORMALIZATION_DIGITS = "digits"
+    NORMALIZATION_LOWERCASE = "lowercase"
+    NORMALIZATION_EMAIL = "email"
+    NORMALIZATION_PHONE = "phone"
+    NORMALIZATION_NIK = "nik"
+    NORMALIZATION_TRIM = "trim"
+    NORMALIZATION_NONE = "none"
+    NORMALIZATION_RAW = "raw"
+
+    @staticmethod
+    def normalize(plaintext: str, normalization: str) -> str:
+        """
+        Normalize plaintext before generating blind index.
+
+        Normalization must be applied identically on both write and read paths
+        to ensure consistent index values.
+
+        Args:
+            plaintext: String to normalize
+            normalization: Normalization mode
+
+        Returns:
+            Normalized string
+
+        Examples:
+            >>> BlindIndexer.normalize("  Email@Example.COM  ", "lowercase")
+            'email@example.com'
+
+            >>> BlindIndexer.normalize("+62-812-3456-7890", "digits")
+            '6281234567890'
+        """
+        mode = normalization.lower()
+
+        if mode in (BlindIndexer.NORMALIZATION_DIGITS,
+                   BlindIndexer.NORMALIZATION_PHONE,
+                   BlindIndexer.NORMALIZATION_NIK):
+            # Extract only digits
+            import re
+            return re.sub(r"\D", "", plaintext)
+
+        elif mode in (BlindIndexer.NORMALIZATION_LOWERCASE,
+                     BlindIndexer.NORMALIZATION_EMAIL):
+            # Lowercase and trim whitespace
+            return plaintext.strip().lower()
+
+        elif mode == BlindIndexer.NORMALIZATION_TRIM:
+            # Only trim whitespace
+            return plaintext.strip()
+
+        elif mode in (BlindIndexer.NORMALIZATION_NONE,
+                     BlindIndexer.NORMALIZATION_RAW):
+            # No normalization
+            return plaintext
+
+        else:
+            # Default to no normalization for unknown modes
+            return plaintext
+
+    @staticmethod
+    def generate(
+        plaintext: str,
+        key: Union[str, bytes],
+        normalization: str = "lowercase"
+    ) -> str:
+        """
+        Generate a blind index for searchable encryption.
+
+        The blind index is a deterministic HMAC-SHA256 hash that can be
+        stored in a separate database column for exact-match queries.
+
+        Args:
+            plaintext: Value to generate index for
+            key: Blind index key (distinct from encryption key!)
+            normalization: Normalization mode to apply
+
+        Returns:
+            Base64-encoded HMAC-SHA256 hash
+
+        Examples:
+            >>> BlindIndexer.generate("user@example.com", "my-blind-index-key", "lowercase")
+            'abc123def456...'
+
+            >>> # To search: WHERE blind_index_column = BlindIndexer.generate(query_value, key, "lowercase")
+        """
+        # Normalize the plaintext
+        normalized = BlindIndexer.normalize(plaintext, normalization)
+
+        # Convert key to bytes if needed
+        if isinstance(key, str):
+            key_bytes = key.encode("utf-8")
+        else:
+            key_bytes = key
+
+        # Compute HMAC-SHA256
+        hmac_obj = hmac.new(key_bytes, normalized.encode("utf-8"), hashlib.sha256)
+        digest = hmac_obj.digest()
+
+        # Return base64-encoded digest
+        return base64.b64encode(digest).decode("ascii")
+
+    @staticmethod
+    def validate_key(key: Union[str, bytes]) -> bool:
+        """
+        Validate that a blind index key meets security requirements.
+
+        Args:
+            key: Key to validate
+
+        Returns:
+            True if key is valid, False otherwise
+        """
+        if isinstance(key, str):
+            key_bytes = key.encode("utf-8")
+        else:
+            key_bytes = key
+
+        # Key should be at least 16 bytes (128 bits)
+        return len(key_bytes) >= 16

panda/cli/__init__.py

@@ -0,0 +1,7 @@
+"""
+CLI module for PANDA SDK.
+
+Provides command-line interface for initialization and key management.
+"""
+
+__all__ = []