spectro-kernel 0.1.3__tar.gz → 0.1.4__tar.gz

{spectro_kernel-0.1.3 → spectro_kernel-0.1.4}/CHANGELOG.md

@@ -6,6 +6,115 @@ Until `1.0.0` the public API may change between minor versions.
 
 ## [Unreleased]
 
+## [0.1.4] — 2026-06-10
+
+### Fixed — Lick atomic equivalent-width formula (CRITICAL)
+
+`embed_lick_indices` was computing
+``EW = (λ_hi − λ_lo) × (1 − mean(F/Fc))`` for atomic indices instead of
+the canonical Worthey-1994 form ``EW = ∫(1 − F/Fc) dλ``. The two only
+agree when pixel edges fall exactly on the band limits — which never
+happens on real data — so every atomic Lick value produced by ≤ 0.1.3
+was systematically **inflated by ~1–2 Å**. The molecular-magnitude form
+was correct.
+
+Algorithm version bumped 1.0.0 → 2.0.0; any indexed Lick embedding from
+≤ 0.1.3 should be **re-computed**. Companion fix in ``_band_mean_flux``:
+the band mean now uses the actual covered pixel span (not the nominal
+``hi − lo``) and refuses bands less than half-covered by the spectrum.
+
+### Fixed — SSRF on `load_spectrum` / `load_spectrum_from_url` (CRITICAL)
+
+The MCP file-loading tools forwarded the user-supplied URL directly to
+``urllib.request.urlretrieve`` with no host validation, no redirect
+control, no timeout and no size cap. An attacker could fetch instance
+metadata (``http://169.254.169.254/latest/meta-data/iam/...``), scan the
+VPC interior, or stream a 10 GB file to exhaust the worker.
+
+New module ``spectro_mcp/url_safety.py`` gates every URL coming from
+MCP through:
+- scheme allowlist (``http``/``https`` only);
+- ``localhost`` and DNS-resolved IP validation (refuses loopback,
+  RFC1918, link-local, multicast, reserved, unspecified);
+- a no-redirect HTTP handler (a friendly upstream can't 302 to
+  ``169.254.169.254`` after the hostname guard passes);
+- 60-second timeout plus 256 MiB byte cap on downloads.
+
+### Fixed — Path traversal on the HTTP MCP server (HIGH)
+
+``load_spectrum(session_id, path)`` accepted any local filesystem path,
+including ``/etc/passwd`` and ``/proc/self/environ`` (which leaks
+``SPECTRO_MCP_API_KEY``, ``AWS_*``, ``SPECTRO_MCP_REDIS_URL``, …).
+
+Local paths are now refused when the new env var
+``SPECTRO_MCP_DENY_LOCAL_PATHS=1`` is set, and the ``--http`` entry
+point sets it automatically. ``--stdio`` mode (the local default) is
+unaffected — the user's own machine is trusted by definition.
+
+### Fixed — Pickle deserialisation from Redis (HIGH)
+
+``RedisSessionManager.get()`` called ``pickle.loads`` on whatever
+arbitrary bytes Redis returned. Any path that lets an attacker write to
+the Redis backing store (compromised Redis, MITM with no TLS, leaked
+``SPECTRO_MCP_REDIS_URL``) → arbitrary code execution on the next
+``get``.
+
+Payloads are now wrapped with an HMAC-SHA256 signature derived from
+``SPECTRO_MCP_SESSION_SECRET`` (env). Without that env var the server
+generates a one-shot random secret at boot (sessions don't survive a
+restart in that case — a clear stderr warning is emitted). Unsigned or
+mis-signed blobs raise ``ValueError`` before ``pickle.loads`` runs.
+
+### Fixed — MCP stdio corruption from boot-time stdout prints (HIGH)
+
+In stdio mode, stdout is the JSON-RPC wire to the agent. Two paths
+emitted bytes on stdout that corrupted the very first handshake:
+
+1. Algorithm discovery imported ``astroquery`` (Gaia DR4 banner, ~390 B)
+   and ``easyspec`` (version banner, ~30 B). FD-level writes that
+   ``contextlib.redirect_stdout`` doesn't catch.
+2. ``configure_logger`` attached the audit handler to ``sys.stdout``;
+   every tool call therefore emitted a JSON record on the wire.
+
+Fix: a new ``_silence_fd_stdout`` context manager in ``__main__``
+``dup2``'s FD 1 to FD 2 for the boot phase (catches even C-level
+writes), and the audit logger now targets ``sys.stderr``. HTTP mode is
+unchanged.
+
+### Hardened — Dockerfile non-root user (MED)
+
+Default container user was root. The Dockerfile now creates an
+unprivileged ``app`` (UID 10001) and drops to it before ``CMD``. Any
+future vulnerability that reaches the filesystem is confined to the
+app user's home.
+
+### Hardened — Discovery silent error swallow (LOW)
+
+``registry.ensure_discovered`` silently dropped any submodule that
+failed to import. The intent (gracefully skip algorithms whose optional
+extra is missing) is preserved, but a bug-induced import failure used
+to vanish without trace. Discovery now logs every dropped submodule
+via the ``spectro_kernel.registry`` logger.
+
+### Added
+
+- ``tests/unit/test_mcp_security.py`` — 15 new tests covering every
+  v0.1.4 finding (SSRF target families, path-traversal env-var gate,
+  HMAC roundtrip + tamper + wrong-key, RedisSessionManager round-trip
+  via fakeredis, ``_resolve_redis_secret`` env-vs-random behaviour).
+- 2 new Lick regression tests (``test_lick_atomic_ew_matches_worthey_integral``,
+  ``test_lick_band_mean_uses_actual_pixel_span``).
+
+### Migration notes
+
+- Re-index any vectors produced by ``embed_lick_indices`` ≤ 0.1.3
+  (values changed by 1–2 Å on atomic indices).
+- For Redis-backed deployments: set ``SPECTRO_MCP_SESSION_SECRET`` to
+  a stable 32-byte secret in the environment. Otherwise sessions don't
+  survive a restart.
+- For HTTP deployments where you want users to send local paths anyway
+  (uncommon), unset ``SPECTRO_MCP_DENY_LOCAL_PATHS`` explicitly.
+
 ## [0.1.3] — 2026-06-09
 
 ### Fixed — circular import that prevented `from spectro_kernel.embeddings import …`

{spectro_kernel-0.1.3 → spectro_kernel-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spectro-kernel
-Version: 0.1.3
+Version: 0.1.4
 Summary: A shared catalogue of astronomical spectroscopy algorithms, composable into reproducible pipelines, usable as a Python library, a CLI, or an MCP server.
 Project-URL: Homepage, https://github.com/matthieulel/spectro-kernel
 Project-URL: Documentation, https://matthieulel.github.io/spectro-kernel/

{spectro_kernel-0.1.3 → spectro_kernel-0.1.4}/src/spectro_kernel/algorithms/embedding/embed_lick_indices.py

@@ -52,10 +52,29 @@ _LICK_DEFS: dict[str, tuple[float, float, float, float, float, float, str]] = {
 
 
 def _band_mean_flux(wave: np.ndarray, flux: np.ndarray, lo: float, hi: float) -> float:
+    """Mean flux inside ``[lo, hi]``; returns NaN if the band is essentially uncovered.
+
+    The denominator is the **actual wavelength span covered** by the pixels
+    that fell inside the band — not the nominal ``hi - lo``. Using the
+    nominal width biases the mean low when the spectrum doesn't reach the
+    band edges; using the actual covered span gives an unbiased estimate
+    at the cost of slightly less coverage near the spectrum boundary
+    (which is the right trade-off — biasing the continuum is much worse
+    than truncating it).
+
+    Returns NaN when fewer than 2 pixels fall in the band, or when the
+    spectrum covers less than half of the nominal band width — those
+    indicate a band that straddles the spectrum edge and shouldn't be
+    used for a Lick measurement.
+    """
     mask = (wave >= lo) & (wave <= hi)
     if mask.sum() < 2:
         return float("nan")
-    return float(_trapezoid(flux[mask], wave[mask]) / (hi - lo))
+    wmin, wmax = float(wave[mask][0]), float(wave[mask][-1])
+    span = wmax - wmin
+    if span < 0.5 * (hi - lo):
+        return float("nan")   # less than half of the band is in the spectrum
+    return float(_trapezoid(flux[mask], wave[mask]) / span)
 
 
 def _lick_index(
@@ -63,7 +82,14 @@ def _lick_index(
     bl: float, bh: float, fl: float, fh: float, rl: float, rh: float,
     kind: str,
 ) -> float:
-    """Compute one Lick index value (atomic = Å EW, molecular = magnitudes)."""
+    """Compute one Lick index value (atomic = Å EW, molecular = magnitudes).
+
+    Follows Worthey, Faber, González & Burstein 1994 (ApJS, 94, 687) and
+    Trager et al. 1998 (ApJS, 116, 1). The atomic-EW definition is
+    ``EW = ∫_F (1 - F(λ)/Fc(λ)) dλ`` with ``Fc`` the pseudo-continuum
+    straight-line interpolation between the mean fluxes of the blue and
+    red sidebands.
+    """
     blue_mid = 0.5 * (bl + bh)
     red_mid = 0.5 * (rl + rh)
     blue_flux = _band_mean_flux(wave, flux, bl, bh)
@@ -80,9 +106,20 @@ def _lick_index(
     ratio = flux[feature_mask] / pseudo_cont
 
     if kind == "atomic":
-        return float((fh - fl) * (1.0 - _trapezoid(ratio, wave[feature_mask]) / (fh - fl)))
+        # Canonical Worthey 1994 EW: ∫(1 - F/Fc) dλ — positive for an
+        # absorption line. NB: an earlier implementation used
+        # (fh - fl) * (1 - ∫(F/Fc)/(fh - fl)), which expands to
+        # (fh - fl) - ∫(F/Fc) — wrong by a constant offset whenever pixel
+        # edges don't fall exactly on fl/fh and biased systematically too
+        # high by ~1-2 Å.
+        return float(_trapezoid(1.0 - ratio, wave[feature_mask]))
     if kind == "molecular":
-        mean_ratio = float(_trapezoid(ratio, wave[feature_mask]) / (fh - fl))
+        # Molecular indices: band strength in magnitudes,
+        # -2.5 log10(<F/Fc>) with the average taken over the feature band.
+        feature_span = float(wave[feature_mask][-1] - wave[feature_mask][0])
+        if feature_span <= 0.0:
+            return float("nan")
+        mean_ratio = float(_trapezoid(ratio, wave[feature_mask]) / feature_span)
         if mean_ratio <= 0.0:
             return float("nan")
         return float(-2.5 * np.log10(mean_ratio))
@@ -92,7 +129,7 @@ def _lick_index(
 @register_algorithm(
     "embed_lick_indices",
     category=AlgorithmCategory.EMBEDDING,
-    version="1.0.0",
+    version="2.0.0",   # 2.0.0: fixed atomic-EW formula; values changed (cf. CHANGELOG v0.1.4)
 )
 class EmbedLickIndices(BaseAlgorithm):
     """Embed a spectrum as the canonical Lick/IDS line-strength indices.

{spectro_kernel-0.1.3 → spectro_kernel-0.1.4}/src/spectro_kernel/version.py

@@ -1,3 +1,3 @@
 """Single source of truth for the package version."""
 
-__version__ = "0.1.3"
+__version__ = "0.1.4"

{spectro_kernel-0.1.3 → spectro_kernel-0.1.4}/src/spectro_mcp/__main__.py

@@ -7,11 +7,39 @@ Claude Desktop) or over HTTP (for remote agents).
 from __future__ import annotations
 
 import argparse
+import os
 import sys
+from contextlib import contextmanager
 
 from spectro_kernel.version import __version__
 
 
+@contextmanager
+def _silence_fd_stdout():
+    """Redirect FD 1 (stdout) to FD 2 (stderr) at the OS level for the boot phase.
+
+    ``contextlib.redirect_stdout`` only rewires ``sys.stdout``, which is
+    enough for pure-Python ``print()`` but NOT for third-party libraries
+    that write via the C-level FD 1 directly (e.g. astroquery's
+    "In preparation for Gaia DR4…" banner, easyspec's version string).
+    Those would otherwise corrupt the very first MCP handshake on stdio.
+
+    We dup(2) the original stdout FD aside, point FD 1 at FD 2 (stderr)
+    for the duration of the block, then restore on exit. Both Python's
+    ``sys.stdout`` AND any C-level writer end up writing to stderr while
+    the block is active.
+    """
+    sys.stdout.flush()
+    saved_fd = os.dup(1)
+    try:
+        os.dup2(2, 1)   # FD 1 (stdout) now points at FD 2 (stderr)
+        yield
+    finally:
+        sys.stdout.flush()
+        os.dup2(saved_fd, 1)
+        os.close(saved_fd)
+
+
 def build_parser() -> argparse.ArgumentParser:
     """Construct the ``spectro-mcp`` argument parser."""
     parser = argparse.ArgumentParser(
@@ -36,22 +64,6 @@ def build_parser() -> argparse.ArgumentParser:
     return parser
 
 
-def main(argv: list[str] | None = None) -> int:
-    """Entry point for the ``spectro-mcp`` console script."""
-    args = build_parser().parse_args(argv)
-    try:
-        from .server import build_server
-    except ImportError as exc:
-        print(f"error: {exc}", file=sys.stderr)
-        return 2
-
-    server = build_server(ttl_seconds=args.ttl)
-    if args.http:
-        return _run_http(server, args)
-    server.run()  # stdio is FastMCP's default transport
-    return 0
-
-
 def _run_http(server, args) -> int:
     """Serve over HTTP, wiring optional API-key auth + rate-limit middleware."""
     import os
@@ -66,6 +78,13 @@ def _run_http(server, args) -> int:
     if api_key:
         app.add_middleware(ApiKeyMiddleware, expected=api_key)
         print("spectro-mcp: API-key auth enabled (header: X-API-Key).", file=sys.stderr)
+    else:
+        print(
+            "spectro-mcp: WARNING — no SPECTRO_MCP_API_KEY set; the server "
+            "will accept every request. This is fine for personal stdio "
+            "use but not for a shared deployment.",
+            file=sys.stderr,
+        )
 
     rate_per_min = int(os.environ.get("SPECTRO_MCP_RATE_PER_MINUTE", "0") or "0")
     if rate_per_min > 0:
@@ -76,5 +95,33 @@ def _run_http(server, args) -> int:
     return 0
 
 
+def main(argv: list[str] | None = None) -> int:
+    """Entry point for the ``spectro-mcp`` console script."""
+    args = build_parser().parse_args(argv)
+    try:
+        from .server import build_server
+    except ImportError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+    if args.http:
+        # In HTTP / shared-server mode, refuse local filesystem paths from
+        # MCP tool calls — they would otherwise be a path-traversal vector
+        # (load_spectrum("/etc/passwd"), …). Stdio mode leaves the flag
+        # unset because the server is a subprocess of the user's own
+        # Claude Desktop and the user's files are legitimate input.
+        os.environ.setdefault("SPECTRO_MCP_DENY_LOCAL_PATHS", "1")
+        server = build_server(ttl_seconds=args.ttl)
+        return _run_http(server, args)
+
+    # stdio: stdout is the JSON-RPC wire. Boot phase writes everything to
+    # stderr (FD-level redirect catches third-party banners that bypass
+    # sys.stdout); FastMCP then takes over stdout for the run loop.
+    with _silence_fd_stdout():
+        server = build_server(ttl_seconds=args.ttl)
+    server.run()  # stdio is FastMCP's default transport
+    return 0
+
+
 if __name__ == "__main__":  # pragma: no cover
     raise SystemExit(main())

{spectro_kernel-0.1.3 → spectro_kernel-0.1.4}/src/spectro_mcp/auto_tools.py

@@ -10,8 +10,6 @@ from __future__ import annotations
 import os
 import tempfile
 import time
-import urllib.parse
-import urllib.request
 import uuid
 from pathlib import Path
 from typing import Any
@@ -28,6 +26,13 @@ from spectro_kernel.registry import (
 
 from .observability import configure_logger, log_audit, record_tool_call
 from .session import SessionManager, SessionNotFoundError
+from .url_safety import (
+    PathNotAllowedError,
+    URLNotAllowedError,
+    open_safe_url,
+    validate_loadable_path,
+    validate_safe_url,
+)
 
 _LOGGER = configure_logger()
 
@@ -94,31 +99,55 @@ def _algo_description(meta: dict[str, Any]) -> str:
     return "\n".join(lines)
 
 
-def _load_spectrum(path: str) -> Any:
+def _load_spectrum_safe(path: str) -> Any:
+    """Load a spectrum from *path* after running every safety guard.
+
+    Local paths are refused when the server is in HTTP / shared mode
+    (``SPECTRO_MCP_DENY_LOCAL_PATHS=1``). URLs are first downloaded to a
+    temp file via :func:`_download_to_temp` (no redirects, no SSRF, size
+    cap) and the local copy is fed to the underlying reader. This way
+    the unsafe ``urllib.request.urlretrieve`` path inside
+    ``spectro_kernel.io.read_fits`` is never exercised from the MCP
+    surface.
+    """
+    validate_loadable_path(path)
+    if path.startswith(("http://", "https://")):
+        local = _download_to_temp(path)
+        try:
+            suffix = local.suffix.lower()
+            if suffix in _FITS_SUFFIXES:
+                return read_fits(str(local))
+            return read_ascii_spectrum(str(local))
+        finally:
+            local.unlink(missing_ok=True)
     suffix = Path(path).suffix.lower()
-    if suffix in _FITS_SUFFIXES or path.startswith(("http://", "https://")):
+    if suffix in _FITS_SUFFIXES:
         return read_fits(path)
     return read_ascii_spectrum(path)
 
 
 def _download_to_temp(url: str) -> Path:
-    """Download *url* to a temporary file, preserving the suffix and capping size."""
-    parsed = urllib.parse.urlparse(url)
-    if parsed.scheme not in ("http", "https"):
-        raise ValueError(f"Only http(s) URLs are accepted, got: {parsed.scheme!r}")
-    suffix = Path(parsed.path).suffix or ".dat"
+    """Download *url* to a temp file under SSRF + size + redirect guards.
+
+    Refuses non-public IPs (loopback / RFC1918 / link-local / multicast),
+    refuses HTTP redirects, applies a 60 s timeout and a 256 MiB cap.
+    """
+    validate_safe_url(url)
+    parsed_path = Path(url.split("?", 1)[0])
+    suffix = parsed_path.suffix or ".dat"
     fd, path = tempfile.mkstemp(suffix=suffix, prefix="spectro_upload_")
     written = 0
     try:
-        with urllib.request.urlopen(url, timeout=60) as resp, os.fdopen(fd, "wb") as f:
+        with open_safe_url(url, timeout=60.0) as resp, os.fdopen(fd, "wb") as f:
             while True:
                 chunk = resp.read(65536)
                 if not chunk:
                     break
                 written += len(chunk)
                 if written > _MAX_DOWNLOAD_BYTES:
-                    raise ValueError(
-                        f"Refusing to download more than {_MAX_DOWNLOAD_BYTES} bytes."
+                    raise URLNotAllowedError(
+                        f"refusing download from {url!r}: would exceed "
+                        f"the {_MAX_DOWNLOAD_BYTES} byte cap."
                     )
                 f.write(chunk)
     except Exception:
@@ -147,7 +176,10 @@ def register_transverse_tools(mcp: Any, sessions: SessionManager) -> None:
         The spectrum becomes the session's working spectrum, ready for the analysis tools.
         """
         ctx = sessions.get(session_id)
-        ctx.spectrum = _load_spectrum(path)
+        try:
+            ctx.spectrum = _load_spectrum_safe(path)
+        except (PathNotAllowedError, URLNotAllowedError) as exc:
+            return {"error": str(exc)}
         sessions.save(session_id, ctx)
         return {"loaded": True, "preview": ctx.spectrum.preview()}
 
@@ -283,7 +315,10 @@ def register_transverse_tools(mcp: Any, sessions: SessionManager) -> None:
         suffix; pass ``format_hint`` ("fits" or "ascii") to override.
         """
         ctx = sessions.get(session_id)
-        local = _download_to_temp(url)
+        try:
+            local = _download_to_temp(url)
+        except URLNotAllowedError as exc:
+            return {"error": str(exc)}
         try:
             hint = format_hint.lower()
             if hint == "fits" or (not hint and local.suffix.lower() in _FITS_SUFFIXES):

{spectro_kernel-0.1.3 → spectro_kernel-0.1.4}/src/spectro_mcp/observability.py

@@ -78,8 +78,15 @@ class _JsonFormatter(logging.Formatter):
 
 
 def configure_logger(name: str = "spectro_mcp", level: int = logging.INFO) -> logging.Logger:
-    """Configure structured JSON logging to stdout. Returns the configured logger."""
-    handler = logging.StreamHandler(sys.stdout)
+    """Configure structured JSON logging to **stderr**. Returns the configured logger.
+
+    Why stderr and not stdout: in stdio MCP mode, stdout is the
+    JSON-RPC wire to the agent. Any byte written to stdout that isn't a
+    well-formed JSON-RPC frame corrupts the protocol and crashes the
+    agent's parser. Audit logs MUST go to stderr; stdout is reserved.
+    HTTP mode is unaffected (uvicorn doesn't multiplex stdout).
+    """
+    handler = logging.StreamHandler(sys.stderr)
     handler.setFormatter(_JsonFormatter())
     logger = logging.getLogger(name)
     logger.handlers.clear()

{spectro_kernel-0.1.3 → spectro_kernel-0.1.4}/src/spectro_mcp/session.py

@@ -15,15 +15,68 @@ Use :func:`make_session_manager` to pick the right backend from configuration.
 
 from __future__ import annotations
 
+import hashlib
+import hmac
 import os
 import pickle
 import secrets
+import sys
 import time
 from dataclasses import dataclass, field
 from typing import Protocol
 
 from spectro_kernel.types import WorkContext
 
+# Length of the HMAC-SHA256 digest prefix we sign the pickle blob with.
+_HMAC_LEN = 32
+
+
+def _resolve_redis_secret() -> bytes:
+    """Return the secret key used to sign Redis-stored session payloads.
+
+    Strict order:
+    1. ``SPECTRO_MCP_SESSION_SECRET`` env var — use it as-is (UTF-8 encoded).
+       This is the only option that keeps sessions valid across restarts.
+    2. No env var → generate a fresh 32-byte random secret for this process.
+       Sessions written by another instance are unverifiable, so an attacker
+       who plants a malicious blob in Redis can't make us deserialise it,
+       but legitimate cross-instance sharing is also broken. Emit a
+       prominent warning so operators don't roll this out by accident.
+    """
+    raw = os.environ.get("SPECTRO_MCP_SESSION_SECRET", "").strip()
+    if raw:
+        return raw.encode("utf-8")
+    print(
+        "spectro-mcp: WARNING — SPECTRO_MCP_SESSION_SECRET is not set. "
+        "Generating a one-shot random session secret for this process; "
+        "Redis-backed sessions will not survive a restart. Set the env "
+        "var to a stable random string (32+ bytes) for a real deployment.",
+        file=sys.stderr,
+    )
+    return secrets.token_bytes(32)
+
+
+def _sign_payload(payload: bytes, key: bytes) -> bytes:
+    """Return ``HMAC-SHA256(key, payload) ‖ payload``."""
+    return hmac.new(key, payload, hashlib.sha256).digest() + payload
+
+
+def _verify_and_unpack(blob: bytes, key: bytes) -> bytes:
+    """Strip the HMAC prefix after verification; raise on mismatch."""
+    if len(blob) < _HMAC_LEN:
+        raise ValueError("session payload too short to carry an HMAC prefix")
+    sig, payload = blob[:_HMAC_LEN], blob[_HMAC_LEN:]
+    expected = hmac.new(key, payload, hashlib.sha256).digest()
+    if not hmac.compare_digest(sig, expected):
+        # NB: do NOT pickle.loads(payload) on failure — the whole point of
+        # this check is to refuse running attacker-controlled pickle.
+        raise ValueError(
+            "session payload HMAC mismatch: refusing to deserialise (the "
+            "blob in Redis was either written by another instance or has "
+            "been tampered with)."
+        )
+    return payload
+
 
 class SessionNotFoundError(KeyError):
     """Raised when a session id is unknown or has expired."""
@@ -119,11 +172,20 @@ class _SessionManagerProtocol(Protocol):
 
 
 class RedisSessionManager:
-    """Session storage backed by Redis — survives across instances and restarts."""
+    """Session storage backed by Redis — survives across instances and restarts.
+
+    Payloads are HMAC-signed with a key derived from
+    ``SPECTRO_MCP_SESSION_SECRET`` (env). Without signature verification,
+    an attacker with write access to Redis can inject a malicious pickle
+    blob and obtain RCE on the next ``get()`` — this class refuses any
+    blob whose HMAC doesn't match.
+    """
 
     _KEY_PREFIX = "sk:session:"
 
-    def __init__(self, url: str, ttl_seconds: float = 3600.0) -> None:
+    def __init__(
+        self, url: str, ttl_seconds: float = 3600.0, *, secret: bytes | None = None
+    ) -> None:
         try:
             import redis  # type: ignore[import-untyped]
         except ImportError as exc:  # pragma: no cover - optional dep
@@ -133,14 +195,25 @@ class RedisSessionManager:
             ) from exc
         self._redis = redis.Redis.from_url(url)
         self.ttl_seconds = ttl_seconds
+        # Per-instance key; resolved at construction so tests can inject one.
+        self._secret = secret if secret is not None else _resolve_redis_secret()
 
     def _key(self, session_id: str) -> str:
         return self._KEY_PREFIX + session_id
 
+    def _serialise(self, ctx: WorkContext) -> bytes:
+        return _sign_payload(pickle.dumps(ctx), self._secret)
+
+    def _deserialise(self, blob: bytes) -> WorkContext:
+        payload = _verify_and_unpack(blob, self._secret)
+        return pickle.loads(payload)
+
     def create(self) -> str:
         session_id = "s_" + secrets.token_urlsafe(8)
         self._redis.setex(
-            self._key(session_id), int(self.ttl_seconds), pickle.dumps(WorkContext())
+            self._key(session_id),
+            int(self.ttl_seconds),
+            self._serialise(WorkContext()),
         )
         return session_id
 
@@ -150,12 +223,14 @@ class RedisSessionManager:
             raise SessionNotFoundError(session_id)
         # touch TTL on every access
         self._redis.expire(self._key(session_id), int(self.ttl_seconds))
-        return pickle.loads(data)
+        return self._deserialise(data)
 
     def save(self, session_id: str, ctx: WorkContext) -> None:
         if not self._redis.exists(self._key(session_id)):
             raise SessionNotFoundError(session_id)
-        self._redis.setex(self._key(session_id), int(self.ttl_seconds), pickle.dumps(ctx))
+        self._redis.setex(
+            self._key(session_id), int(self.ttl_seconds), self._serialise(ctx)
+        )
 
     def has(self, session_id: str) -> bool:
         return bool(self._redis.exists(self._key(session_id)))