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

oscura/analyzers/digital/timing.py

@@ -642,20 +642,33 @@ def recover_clock_fft(
     Detects the dominant frequency component in the signal using
     FFT analysis, suitable for periodic digital signals.
 
+    **Best for**: Long signals (>64 samples) with clear periodicity.
+    **Not recommended for**: Short random data, aperiodic signals.
+    For short signals, use recover_clock_edge() instead.
+
     Args:
-        trace: Input trace (analog or digital).
+        trace: Input trace (analog or digital). Should have at least
+            4-5 cycles of the clock signal for reliable detection.
         min_freq: Minimum frequency to consider (Hz). Default: sample_rate/1000.
         max_freq: Maximum frequency to consider (Hz). Default: sample_rate/2.
 
     Returns:
         ClockRecoveryResult with recovered frequency and confidence.
+        Confidence < 0.5 indicates unreliable detection (warning issued).
 
     Raises:
-        InsufficientDataError: If trace has fewer than 16 samples.
+        InsufficientDataError: If trace has fewer than 64 samples.
+        ValueError: If no frequency components found in specified range.
+
+    Warnings:
+        UserWarning: Issued when confidence < 0.5 (unreliable result).
 
     Example:
         >>> result = recover_clock_fft(trace)
-        >>> print(f"Clock: {result.frequency / 1e6:.3f} MHz")
+        >>> if result.confidence > 0.7:
+        ...     print(f"Clock: {result.frequency / 1e6:.3f} MHz")
+        >>> else:
+        ...     print("Low confidence - try edge-based recovery")
 
     References:
         IEEE 1241-2010 Section 4.1
@@ -665,12 +678,17 @@ def recover_clock_fft(
     n = len(data)
     sample_rate = trace.metadata.sample_rate
 
-    if n < 16:
+    # FFT requires sufficient samples for reliable frequency resolution
+    # Rule of thumb: At least 4-5 cycles of the signal for accurate peak detection
+    # With typical bit rates, this means ~100-200 samples minimum
+    min_samples = 64  # Increased from 16 for better frequency resolution
+    if n < min_samples:
         raise InsufficientDataError(
-            "FFT clock recovery requires at least 16 samples",
-            required=16,
+            f"FFT clock recovery requires at least {min_samples} samples for reliable frequency detection",
+            required=min_samples,
             available=n,
             analysis_type="clock_recovery_fft",
+            fix_hint="Use edge-based clock recovery for short signals or acquire more data",
         )
 
     # Set frequency range defaults
@@ -691,11 +709,11 @@ def recover_clock_fft(
     valid_indices = np.where(mask)[0]
 
     if len(valid_indices) == 0:
-        return ClockRecoveryResult(
-            frequency=np.nan,
-            period=np.nan,
-            method="fft",
-            confidence=0.0,
+        # No valid frequencies in range - signal may be DC or out of range
+        raise ValueError(
+            f"No frequency components found in range [{min_freq:.0f} Hz, {max_freq:.0f} Hz]. "
+            f"Signal may be constant (DC) or frequency is outside specified range. "
+            f"Adjust min_freq/max_freq or check signal integrity."
         )
 
     # Find peak in valid range
@@ -721,6 +739,18 @@ def recover_clock_fft(
 
     period = 1.0 / peak_freq if peak_freq > 0 else np.nan
 
+    # Warn on low confidence results (may be unreliable)
+    if confidence < 0.5:
+        import warnings
+
+        warnings.warn(
+            f"FFT clock recovery has low confidence ({confidence:.2f}). "
+            f"Detected frequency: {peak_freq / 1e6:.3f} MHz. "
+            f"Consider using longer signal, edge-based recovery, or verifying signal periodicity.",
+            UserWarning,
+            stacklevel=2,
+        )
+
     return ClockRecoveryResult(
         frequency=float(peak_freq),
         period=float(period),

oscura/analyzers/packet/payload_extraction.py

@@ -6,8 +6,6 @@ This module provides payload extraction from PCAP packets with metadata
 preservation, filtering, and multiple output formats.
 """
 
-from __future__ import annotations
-
 from collections.abc import Iterator, Sequence
 from dataclasses import dataclass
 from typing import Any, Literal
@@ -122,7 +120,7 @@ class PayloadExtractor:
         packets: Sequence[dict[str, Any] | bytes],
         protocol: str | None = None,
         port_filter: tuple[int | None, int | None] | None = None,
-    ) -> list[PayloadInfo]:
+    ) -> list["PayloadInfo"]:
         """Extract payloads from all packets with metadata.
 
         Implements RE-PAY-001: Batch payload extraction with metadata.
@@ -186,7 +184,7 @@ class PayloadExtractor:
     def iter_payloads(
         self,
         packets: Sequence[dict[str, Any] | bytes],
-    ) -> Iterator[PayloadInfo]:
+    ) -> Iterator["PayloadInfo"]:
         """Iterate over payloads for memory-efficient processing.
 
         Implements RE-PAY-001: Streaming payload iteration.

oscura/analyzers/packet/stream.py

@@ -22,11 +22,11 @@ from typing import TYPE_CHECKING, Any, BinaryIO, TypeVar
 
 from oscura.analyzers.packet.parser import BinaryParser
 
+T = TypeVar("T")
+
 if TYPE_CHECKING:
     from collections.abc import Callable, Iterator
 
-T = TypeVar("T")
-
 
 @dataclass
 class StreamPacket:
@@ -282,7 +282,7 @@ def pipeline(
     yield from result
 
 
-def batch[T](
+def batch(
     source: Iterator[T],
     size: int,
 ) -> Iterator[list[T]]:
@@ -311,7 +311,7 @@ def batch[T](
         yield current_batch
 
 
-def take[T](source: Iterator[T], n: int) -> Iterator[T]:
+def take(source: Iterator[T], n: int) -> Iterator[T]:
     """Take first n items.
 
     Args:
@@ -329,7 +329,7 @@ def take[T](source: Iterator[T], n: int) -> Iterator[T]:
         count += 1  # noqa: SIM113
 
 
-def skip[T](source: Iterator[T], n: int) -> Iterator[T]:
+def skip(source: Iterator[T], n: int) -> Iterator[T]:
     """Skip first n items.
 
     Args:

oscura/analyzers/patterns/__init__.py

@@ -22,6 +22,8 @@ Author: Oscura Development Team
 
 # Periodic pattern detection (PAT-001)
 # Pattern clustering (PAT-004)
+from __future__ import annotations
+
 from .clustering import (
     ClusteringResult,
     ClusterResult,
@@ -125,7 +127,7 @@ def find_motifs(
     return results
 
 
-def extract_motif(data: Any, start: int, length: int) -> "NDArray[np.generic]":
+def extract_motif(data: Any, start: int, length: int) -> NDArray[np.generic]:
     """Extract a motif from data.
 
     Args:
@@ -137,10 +139,9 @@ def extract_motif(data: Any, start: int, length: int) -> "NDArray[np.generic]":
         Extracted motif as numpy array.
     """
     import numpy as np
-    from numpy.typing import NDArray
 
     data_arr = np.asarray(data)
-    result: NDArray[np.generic] = data_arr[start : start + length]
+    result = data_arr[start : start + length]
     return result
 
 

oscura/analyzers/patterns/clustering.py

@@ -7,6 +7,8 @@ using various distance metrics and clustering approaches.
 Author: Oscura Development Team
 """
 
+from __future__ import annotations
+
 from dataclasses import dataclass
 from typing import Literal
 
@@ -984,7 +986,7 @@ class PatternClusterer:
 
     def fit(
         self, patterns: list[bytes | np.ndarray[tuple[int], np.dtype[np.uint8]]]
-    ) -> "PatternClusterer":
+    ) -> PatternClusterer:
         """Fit the clusterer to patterns (sklearn-style interface).
 
         Args:

oscura/analyzers/power/ac_power.py

@@ -11,8 +11,6 @@ Example:
     >>> print(f"Power factor: {pf:.3f}, Reactive power: {q:.2f} VAR")
 """
 
-from __future__ import annotations
-
 import numpy as np
 
 from oscura.analyzers.power.basic import average_power

oscura/analyzers/power/basic.py

@@ -11,8 +11,6 @@ Example:
     >>> print(f"Average: {stats['average']:.2f} W, Peak: {stats['peak']:.2f} W")
 """
 
-from __future__ import annotations
-
 from typing import Any
 
 import numpy as np

oscura/analyzers/power/ripple.py

@@ -9,8 +9,6 @@ Example:
     >>> print(f"Ripple: {r_pp*1e3:.2f} mV pp, {r_rms*1e3:.2f} mV rms")
 """
 
-from __future__ import annotations
-
 import numpy as np
 from scipy import signal
 

oscura/analyzers/side_channel/__init__.py

@@ -0,0 +1,52 @@
+"""Side-channel analysis module.
+
+This module provides research-grade implementations of side-channel analysis
+techniques including Differential Power Analysis (DPA), Correlation Power
+Analysis (CPA), and timing analysis.
+
+Example:
+    >>> from oscura.analyzers.side_channel import DPAAnalyzer, CPAAnalyzer
+    >>> # DPA attack
+    >>> dpa = DPAAnalyzer(target_bit=0)
+    >>> result = dpa.analyze(traces, plaintexts)
+    >>> print(f"Key byte guess: 0x{result.key_guess:02X}")
+    >>>
+    >>> # CPA attack
+    >>> cpa = CPAAnalyzer(leakage_model="hamming_weight")
+    >>> result = cpa.analyze(traces, plaintexts)
+    >>> print(f"Correlation: {result.max_correlation:.4f}")
+
+References:
+    Kocher et al. "Differential Power Analysis" (CRYPTO 1999)
+    Brier et al. "Correlation Power Analysis" (CHES 2004)
+"""
+
+from oscura.analyzers.side_channel.power import (
+    CPAAnalyzer,
+    CPAResult,
+    DPAAnalyzer,
+    DPAResult,
+    LeakageModel,
+    hamming_distance,
+    hamming_weight,
+)
+from oscura.analyzers.side_channel.timing import (
+    TimingAnalyzer,
+    TimingAttackResult,
+    TimingLeak,
+)
+
+__all__ = [
+    # Power analysis
+    "CPAAnalyzer",
+    "CPAResult",
+    "DPAAnalyzer",
+    "DPAResult",
+    "LeakageModel",
+    # Timing analysis
+    "TimingAnalyzer",
+    "TimingAttackResult",
+    "TimingLeak",
+    "hamming_distance",
+    "hamming_weight",
+]