oscura 0.1.2__py3-none-any.whl → 0.4.0__py3-none-any.whl

oscura/reporting/comparison.py

@@ -9,8 +9,6 @@ Example:
     >>> report = generate_comparison_report(baseline, current, "comparison.pdf")
 """
 
-from __future__ import annotations
-
 from typing import Any, Literal
 
 from oscura.reporting.core import Report, ReportConfig, Section

oscura/reporting/config.py

@@ -594,7 +594,7 @@ def get_available_analyses(input_type: InputType) -> list[AnalysisDomain]:
 
 
 # Type alias for progress callbacks
-ProgressCallback = Callable[[ProgressInfo], None]
+ProgressCallback = Callable[["ProgressInfo"], None]
 
 
 __all__ = [

oscura/reporting/formatting/emphasis.py

@@ -3,6 +3,8 @@
 Simple text formatting for terminal output.
 """
 
+from __future__ import annotations
+
 from enum import Enum
 
 

oscura/reporting/formatting/numbers.py

@@ -4,8 +4,6 @@ Provides comprehensive number formatting with SI prefixes, engineering notation,
 locale support, and specification comparison capabilities.
 """
 
-from __future__ import annotations
-
 import math
 from datetime import datetime
 from typing import ClassVar

oscura/reporting/output.py

@@ -4,8 +4,6 @@ This module provides directory structure and file management for analysis
 report outputs, including plots, JSON/YAML data exports, and logs.
 """
 
-from __future__ import annotations
-
 import json
 from datetime import datetime
 from pathlib import Path
@@ -14,7 +12,7 @@ from typing import Any
 import numpy as np
 import yaml
 
-from oscura.reporting.config import AnalysisDomain  # noqa: TC001
+from oscura.reporting.config import AnalysisDomain
 
 
 def _sanitize_for_serialization(obj: Any, max_depth: int = 10) -> Any:

oscura/reporting/sections.py

@@ -9,8 +9,6 @@ Example:
     >>> section = create_title_section("Signal Analysis Report", author="Engineer")
 """
 
-from __future__ import annotations
-
 from datetime import datetime
 from typing import Any
 

oscura/search/anomaly.py

@@ -4,6 +4,8 @@ This module provides automated detection of glitches, timing violations,
 and protocol errors with context extraction for debugging.
 """
 
+from __future__ import annotations
+
 from typing import Any
 
 import numpy as np

oscura/session/session.py

@@ -15,17 +15,25 @@ Example:
 from __future__ import annotations
 
 import gzip
+import hashlib
+import hmac
 import pickle
 from dataclasses import dataclass, field
 from datetime import datetime
 from pathlib import Path
-from typing import Any
+from typing import Any, cast
 
 import numpy as np
 
+from oscura.core.exceptions import SecurityError
 from oscura.session.annotations import AnnotationLayer
 from oscura.session.history import OperationHistory
 
+# Session file format constants
+_SESSION_MAGIC = b"OSC1"  # Magic bytes for new format with signature
+_SESSION_SIGNATURE_SIZE = 32  # SHA256 hash size in bytes
+_SECURITY_KEY = hashlib.sha256(b"oscura-session-v1").digest()
+
 
 @dataclass
 class Session:
@@ -273,7 +281,7 @@ class Session:
         include_traces: bool = True,
         compress: bool = True,
     ) -> Path:
-        """Save session to file.
+        """Save session to file with HMAC signature for integrity verification.
 
         Args:
             path: Output path (default: use existing or generate).
@@ -287,9 +295,10 @@ class Session:
             >>> session.save('analysis.tks')
 
         Security Note:
-            Session files use pickle serialization for flexibility. Share
-            session files only with trusted parties. For secure data exchange
-            with untrusted parties, use JSON or HDF5 export formats instead.
+            Session files now include HMAC signatures for integrity verification.
+            Files are still pickle-based - only load from trusted sources.
+            For secure data exchange with untrusted parties, use JSON or HDF5
+            export formats instead.
         """
         if path is None:
             path = self._file_path or Path(f"{self.name.replace(' ', '_')}.tks")
@@ -302,13 +311,23 @@ class Session:
         # Build session data
         data = self._to_dict(include_traces=include_traces)
 
-        # Serialize
+        # Serialize with pickle
+        serialized = pickle.dumps(data, protocol=pickle.HIGHEST_PROTOCOL)
+
+        # Compute HMAC signature
+        signature = hmac.new(_SECURITY_KEY, serialized, hashlib.sha256).digest()
+
+        # Write: magic bytes + signature + pickled data
         if compress:
             with gzip.open(path, "wb") as f:
-                pickle.dump(data, f)
+                f.write(_SESSION_MAGIC)
+                f.write(signature)
+                f.write(serialized)
         else:
             with open(path, "wb") as f:
-                pickle.dump(data, f)
+                f.write(_SESSION_MAGIC)
+                f.write(signature)
+                f.write(serialized)
 
         self.history.record("save", {"path": str(path)})
 
@@ -402,7 +421,10 @@ class Session:
 
 
 def load_session(path: str | Path) -> Session:
-    """Load session from file.
+    """Load session from file with HMAC signature verification.
+
+    Session files must be in the current OSC1 format with HMAC signature.
+    Legacy session files without signatures are not supported.
 
     Args:
         path: Path to session file (.tks).
@@ -410,6 +432,10 @@ def load_session(path: str | Path) -> Session:
     Returns:
         Loaded Session object.
 
+    Raises:
+        SecurityError: If signature verification fails or file is not in OSC1 format.
+        gzip.BadGzipFile: If file is neither valid gzip nor uncompressed session.
+
     Example:
         >>> session = load_session('debug_session.tks')
         >>> print(session.list_traces())
@@ -419,19 +445,68 @@ def load_session(path: str | Path) -> Session:
         trusted sources. Loading a malicious .tks file could execute arbitrary
         code. Never load session files from untrusted or unknown sources.
 
-        For secure data exchange, consider exporting to JSON or HDF5 formats
-        instead of using pickle-based session files.
+        All session files must include HMAC signatures for integrity verification.
+        For secure data exchange with untrusted parties, consider exporting to
+        JSON or HDF5 formats instead of using pickle-based session files.
     """
     path = Path(path)
 
+    def _load_with_verification(f: Any) -> dict[str, Any]:
+        """Load and verify session file with HMAC signature.
+
+        Args:
+            f: File object (gzip or regular).
+
+        Returns:
+            Deserialized session dictionary.
+
+        Raises:
+            SecurityError: If magic bytes or signature verification fails.
+        """
+        # Read magic bytes
+        magic = f.read(len(_SESSION_MAGIC))
+
+        if magic != _SESSION_MAGIC:
+            raise SecurityError(
+                "This is a legacy session file. Please re-save with current version.",
+                file_path=str(path),
+                check_type="Session format",
+                details="Expected OSC1 format with HMAC signature",
+            )
+
+        # Read signature and payload
+        signature = f.read(_SESSION_SIGNATURE_SIZE)
+        serialized = f.read()
+
+        if not signature or not serialized:
+            raise SecurityError(
+                "This is a legacy session file. Please re-save with current version.",
+                file_path=str(path),
+                check_type="Session format",
+                details="File is incomplete or corrupted",
+            )
+
+        # Verify HMAC signature
+        expected = hmac.new(_SECURITY_KEY, serialized, hashlib.sha256).digest()
+        if not hmac.compare_digest(signature, expected):
+            raise SecurityError(
+                "Session file signature verification failed",
+                file_path=str(path),
+                check_type="HMAC signature",
+                details="File may be corrupted or tampered with",
+            )
+
+        # Deserialize verified data
+        data = cast("dict[str, Any]", pickle.loads(serialized))
+        return data
+
+    # Try loading (compressed first, then uncompressed)
     try:
-        # Try gzip compressed first
         with gzip.open(path, "rb") as f:
-            data = pickle.load(f)
+            data = _load_with_verification(f)
     except gzip.BadGzipFile:
-        # Fall back to uncompressed
-        with open(path, "rb") as f:
-            data = pickle.load(f)
+        with open(path, "rb") as f:  # type: ignore[assignment]
+            data = _load_with_verification(f)
 
     session = Session._from_dict(data)
     session._file_path = path

oscura/sessions/__init__.py

@@ -0,0 +1,70 @@
+"""Unified session management for Oscura.
+
+This module provides the AnalysisSession hierarchy - a unified pattern for
+interactive signal analysis across different domains.
+
+All analysis sessions (CAN, Serial, BlackBox, RF, etc.) inherit from
+AnalysisSession and provide consistent interfaces for:
+- Recording management (add, list, compare)
+- Differential analysis
+- Result export
+- Domain-specific analysis methods
+
+Example - Generic Session:
+    >>> from oscura.sessions import GenericSession
+    >>> from oscura.acquisition import FileSource
+    >>>
+    >>> session = GenericSession()
+    >>> session.add_recording("test", FileSource("capture.wfm"))
+    >>> results = session.analyze()
+    >>> print(results["summary"]["test"]["mean"])
+
+Example - Domain-Specific Session:
+    >>> from oscura.sessions import AnalysisSession
+    >>> from oscura.acquisition import FileSource
+    >>>
+    >>> class CANSession(AnalysisSession):
+    ...     def analyze(self):
+    ...         # CAN-specific signal discovery
+    ...         return self.discover_signals()
+    ...
+    ...     def discover_signals(self):
+    ...         # Extract CAN signals from recordings
+    ...         pass
+    >>>
+    >>> session = CANSession()
+    >>> session.add_recording("baseline", FileSource("idle.blf"))
+    >>> signals = session.analyze()
+
+Pattern Decision Table:
+    - Use GenericSession for general waveform analysis
+    - Extend AnalysisSession for domain-specific workflows
+    - Use existing session.Session for backward compatibility
+
+Architecture:
+    Layer 3 (High-Level API) - User-Facing
+    ├── AnalysisSession (ABC)
+    │   ├── GenericSession
+    │   ├── CANSession (Phase 1)
+    │   ├── SerialSession (Phase 1)
+    │   ├── BlackBoxSession (Phase 1)
+    │   └── [Future domain sessions]
+    └── [Workflows wrapping sessions]
+
+References:
+    Architecture Plan Phase 0.3: AnalysisSession Base Class
+    docs/architecture/api-patterns.md: When to use Sessions vs Workflows
+"""
+
+from oscura.sessions.base import AnalysisSession, ComparisonResult
+from oscura.sessions.blackbox import BlackBoxSession, FieldHypothesis, ProtocolSpec
+from oscura.sessions.generic import GenericSession
+
+__all__ = [
+    "AnalysisSession",
+    "BlackBoxSession",
+    "ComparisonResult",
+    "FieldHypothesis",
+    "GenericSession",
+    "ProtocolSpec",
+]

oscura/sessions/base.py

@@ -0,0 +1,323 @@
+"""Base class for analysis sessions.
+
+This module defines AnalysisSession - the abstract base class for all
+interactive analysis sessions in Oscura. It provides a unified pattern
+for domain-specific sessions (CAN, Serial, BlackBox, etc.).
+
+Example:
+    >>> from oscura.sessions import AnalysisSession
+    >>> from oscura.acquisition import FileSource, HardwareSource
+    >>>
+    >>> # Domain-specific sessions extend AnalysisSession
+    >>> class CANSession(AnalysisSession):
+    ...     def analyze(self):
+    ...         # CAN-specific analysis
+    ...         return self.discover_signals()
+    ...
+    ...     def discover_signals(self):
+    ...         # Extract CAN signals from recordings
+    ...         pass
+    >>>
+    >>> # Unified interface across all sessions
+    >>> session = CANSession()
+    >>> session.add_recording("baseline", FileSource("idle.blf"))
+    >>> session.add_recording("active", FileSource("running.blf"))
+    >>> diff = session.compare("baseline", "active")
+
+Pattern:
+    All domain-specific sessions (CAN, Serial, BlackBox, etc.) inherit
+    from AnalysisSession and provide:
+    - Recording management (add_recording, list_recordings)
+    - Comparison and differential analysis
+    - Result export (reports, specs, dissectors)
+    - Domain-specific analysis methods (abstract)
+
+Benefits:
+    - Consistent API across all analysis domains
+    - Polymorphic session handling
+    - Shared infrastructure (comparison, export, history)
+    - Domain-specific specialization via inheritance
+
+References:
+    Architecture Plan Phase 0.3: AnalysisSession Base Class
+    docs/architecture/api-patterns.md: When to use Sessions
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from oscura.acquisition import Source
+    from oscura.core.types import Trace
+
+
+@dataclass
+class ComparisonResult:
+    """Result of comparing two recordings.
+
+    Attributes:
+        recording1: Name of first recording.
+        recording2: Name of second recording.
+        changed_bytes: Number of bytes that differ.
+        changed_regions: List of (start, end, description) tuples.
+        similarity_score: Similarity metric (0.0 to 1.0).
+        details: Additional comparison details.
+
+    Example:
+        >>> result = session.compare("baseline", "stimulus")
+        >>> print(f"Changed bytes: {result.changed_bytes}")
+        >>> print(f"Similarity: {result.similarity_score:.2%}")
+    """
+
+    recording1: str
+    recording2: str
+    changed_bytes: int
+    changed_regions: list[tuple[int, int, str]] = field(default_factory=list)
+    similarity_score: float = 0.0
+    details: dict[str, Any] = field(default_factory=dict)
+
+
+class AnalysisSession(ABC):
+    """Abstract base class for all analysis sessions.
+
+    Provides unified interface for interactive signal analysis across
+    different domains (CAN, Serial, RF, BlackBox, etc.). All domain-specific
+    sessions extend this class.
+
+    Subclasses must implement:
+        - analyze(): Domain-specific analysis method
+
+    Subclasses may override:
+        - export_results(): Custom export formats
+        - compare(): Domain-specific comparison logic
+
+    Attributes:
+        name: Session name.
+        recordings: Dictionary mapping names to (source, trace) tuples.
+        metadata: Session metadata dictionary.
+        created_at: Session creation timestamp.
+        modified_at: Last modification timestamp.
+
+    Example:
+        >>> # Subclass for domain-specific analysis
+        >>> class SerialSession(AnalysisSession):
+        ...     def analyze(self):
+        ...         # Detect baud rate, decode UART
+        ...         baud = self.detect_baud_rate()
+        ...         frames = self.decode_uart(baud)
+        ...         return {"baud_rate": baud, "frames": frames}
+        ...
+        ...     def detect_baud_rate(self):
+        ...         # Domain-specific logic
+        ...         pass
+        >>>
+        >>> session = SerialSession()
+        >>> session.add_recording("capture", FileSource("uart.wfm"))
+        >>> results = session.analyze()
+    """
+
+    def __init__(self, name: str = "Untitled Session") -> None:
+        """Initialize analysis session.
+
+        Args:
+            name: Session name (default: "Untitled Session").
+
+        Example:
+            >>> session = CANSession(name="Vehicle Debug Session")
+        """
+        self.name = name
+        self.recordings: dict[str, tuple[Source, Trace | None]] = {}
+        self.metadata: dict[str, Any] = {}
+        self.created_at = datetime.now()
+        self.modified_at = datetime.now()
+
+    def add_recording(
+        self,
+        name: str,
+        source: Source,
+        *,
+        load_immediately: bool = True,
+    ) -> None:
+        """Add a recording to the session.
+
+        Args:
+            name: Name for this recording (e.g., "baseline", "stimulus1").
+            source: Source to acquire data from (FileSource, HardwareSource, etc.).
+            load_immediately: If True, load trace now. If False, defer loading.
+
+        Raises:
+            ValueError: If name already exists.
+
+        Example:
+            >>> from oscura.acquisition import FileSource
+            >>> session.add_recording("baseline", FileSource("idle.blf"))
+            >>> session.add_recording("active", FileSource("running.blf"))
+        """
+        if name in self.recordings:
+            raise ValueError(f"Recording '{name}' already exists in session")
+
+        # Load trace if requested
+        trace = source.read() if load_immediately else None
+
+        self.recordings[name] = (source, trace)
+        self.modified_at = datetime.now()
+
+    def get_recording(self, name: str) -> Trace:
+        """Get a recording by name, loading if necessary.
+
+        Args:
+            name: Recording name.
+
+        Returns:
+            Loaded trace.
+
+        Raises:
+            KeyError: If recording not found.
+
+        Example:
+            >>> trace = session.get_recording("baseline")
+            >>> print(f"Loaded {len(trace.data)} samples")
+        """
+        if name not in self.recordings:
+            available = list(self.recordings.keys())
+            raise KeyError(f"Recording '{name}' not found. Available: {available}")
+
+        source, trace = self.recordings[name]
+
+        # Load if not already loaded
+        if trace is None:
+            trace = source.read()
+            self.recordings[name] = (source, trace)
+
+        return trace
+
+    def list_recordings(self) -> list[str]:
+        """List all recording names in the session.
+
+        Returns:
+            List of recording names.
+
+        Example:
+            >>> session.list_recordings()
+            ['baseline', 'stimulus1', 'stimulus2']
+        """
+        return list(self.recordings.keys())
+
+    def compare(self, name1: str, name2: str) -> ComparisonResult:
+        """Compare two recordings (differential analysis).
+
+        Default implementation provides basic byte-level comparison.
+        Subclasses can override for domain-specific comparison logic.
+
+        Args:
+            name1: First recording name.
+            name2: Second recording name.
+
+        Returns:
+            ComparisonResult with differences.
+
+        Raises:
+            KeyError: If recordings not found.
+
+        Example:
+            >>> result = session.compare("baseline", "stimulus")
+            >>> print(f"Changed: {result.changed_bytes} bytes")
+            >>> print(f"Similarity: {result.similarity_score:.2%}")
+        """
+        trace1 = self.get_recording(name1)
+        trace2 = self.get_recording(name2)
+
+        # Basic comparison - count differing samples
+        import numpy as np
+
+        from oscura.core.types import IQTrace
+
+        # Handle IQTrace separately
+        if isinstance(trace1, IQTrace) or isinstance(trace2, IQTrace):
+            raise TypeError("IQTrace comparison not yet supported in base session")
+
+        min_len = min(len(trace1.data), len(trace2.data))
+        data1 = trace1.data[:min_len]
+        data2 = trace2.data[:min_len]
+
+        # For analog traces, use threshold comparison
+        threshold = 0.01  # 1% tolerance
+        changed = np.abs(data1 - data2) > threshold
+        changed_count = int(np.sum(changed))
+
+        # Similarity score
+        similarity = 1.0 - (changed_count / min_len)
+
+        return ComparisonResult(
+            recording1=name1,
+            recording2=name2,
+            changed_bytes=changed_count,
+            similarity_score=similarity,
+            details={
+                "trace1_length": len(trace1.data),
+                "trace2_length": len(trace2.data),
+                "compared_length": min_len,
+            },
+        )
+
+    def export_results(self, format: str, path: str | Path) -> None:
+        """Export analysis results to file.
+
+        Default implementation provides basic export. Subclasses should
+        override to support domain-specific formats (DBC, Wireshark, etc.).
+
+        Args:
+            format: Export format (e.g., "report", "json", "csv").
+            path: Output file path.
+
+        Raises:
+            ValueError: If format not supported.
+
+        Example:
+            >>> session.export_results("report", "analysis.txt")
+            >>> session.export_results("json", "results.json")
+        """
+        path = Path(path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+
+        if format == "report":
+            # Basic text report
+            with open(path, "w") as f:
+                f.write(f"Analysis Session: {self.name}\n")
+                f.write(f"Created: {self.created_at}\n")
+                f.write(f"Modified: {self.modified_at}\n\n")
+                f.write(f"Recordings: {len(self.recordings)}\n")
+                for name in self.list_recordings():
+                    f.write(f"  - {name}\n")
+        else:
+            raise ValueError(f"Unsupported export format: {format}")
+
+    @abstractmethod
+    def analyze(self) -> Any:
+        """Perform domain-specific analysis.
+
+        Subclasses must implement this method to provide domain-specific
+        analysis functionality (CAN signal discovery, UART decoding,
+        protocol reverse engineering, etc.).
+
+        Returns:
+            Analysis results (format depends on domain).
+
+        Example:
+            >>> class CANSession(AnalysisSession):
+            ...     def analyze(self):
+            ...         signals = self.discover_signals()
+            ...         return {"signals": signals}
+        """
+
+    def __repr__(self) -> str:
+        """String representation."""
+        return f"{self.__class__.__name__}(name={self.name!r}, recordings={len(self.recordings)})"
+
+
+__all__ = ["AnalysisSession", "ComparisonResult"]