cremalink 0.1.0b5__py3-none-any.whl

cremalink/local_server_app/api.py

@@ -0,0 +1,272 @@
+"""
+This module defines the FastAPI application for the local proxy server.
+It creates all the API endpoints, manages application state, and handles the
+startup and shutdown of background services.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Optional, AsyncIterator
+from contextlib import asynccontextmanager
+
+from fastapi import Depends, FastAPI, HTTPException, Response, status
+from fastapi.responses import JSONResponse, PlainTextResponse
+from fastapi.routing import APIRouter
+
+from cremalink.local_server_app.config import ServerSettings, get_settings
+from cremalink.local_server_app.device_adapter import DeviceAdapter
+from cremalink.local_server_app.jobs import (
+    JobManager,
+    monitor_job,
+    nudger_job,
+    rekey_job,
+)
+from cremalink.local_server_app.logging import create_logger
+from cremalink.local_server_app.models import (
+    CommandPollResponse,
+    CommandRequest,
+    ConfigureRequest,
+    EncPayload,
+    KeyExchangeRequest,
+    MonitorResponse,
+    PropertiesResponse,
+)
+from cremalink.local_server_app import protocol
+from cremalink.local_server_app.state import LocalServerState
+
+
+def create_app(
+    settings: Optional[ServerSettings] = None,
+    device_adapter: Optional[DeviceAdapter] = None,
+    logger=None,
+) -> FastAPI:
+    """
+    Application factory for the FastAPI server.
+
+    Initializes all components (state, settings, adapter, jobs) and wires up
+    the API routes, startup/shutdown events, and dependencies.
+
+    Returns:
+        A configured FastAPI application instance.
+    """
+    # Initialize core components, allowing for dependency injection in tests.
+    settings = settings or get_settings()
+    logger = logger or create_logger("local_server", settings.log_ring_size)
+    state = LocalServerState(settings, logger)
+    adapter = device_adapter or DeviceAdapter(settings, logger)
+    stop_event = asyncio.Event()
+    jobs = JobManager()
+
+    # Define the application lifespan context manager for startup/shutdown events.
+    @asynccontextmanager
+    async def lifespan(app_: FastAPI) -> AsyncIterator[None]:
+        await app_.router.startup()
+        try:
+            yield
+        finally:
+            await app_.router.shutdown()
+
+    app = FastAPI(title="cremalink Local Server", version="2.0.0")
+    app.state.local_state = state
+    app.state.settings = settings
+    app.state.adapter = adapter
+    app.state.jobs = jobs
+    app.state.stop_event = stop_event
+    app.state.logger = logger
+
+    router = APIRouter()
+
+    # --- Dependency Injection ---
+    async def get_state() -> LocalServerState:
+        return state
+
+    async def get_adapter() -> DeviceAdapter:
+        return adapter
+
+    @router.post("/configure")
+    async def configure(req: ConfigureRequest, st: LocalServerState = Depends(get_state)):
+        """Configures the server with device connection details."""
+        await st.configure(
+            dsn=req.dsn,
+            device_ip=req.device_ip,
+            lan_key=req.lan_key,
+            device_scheme=req.device_scheme,
+            monitor_property_name=req.monitor_property_name,
+        )
+        # Attempt an initial registration with the device.
+        try:
+            await adapter.register_with_device(st)
+        except Exception as exc:
+            st.log("local_reg_initial_failed", {"error": str(exc)})
+        return {"status": "configured", "dsn": req.dsn, "device_scheme": req.device_scheme}
+
+    @router.post("/command")
+    async def command(req: CommandRequest, st: LocalServerState = Depends(get_state), ad: DeviceAdapter = Depends(get_adapter)):
+        """Queues a command to be sent to the device."""
+        if not st.is_configured():
+            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Server not configured")
+        try:
+            await ad.register_with_device(st)
+            await st.queue_command(req.command)
+        except OverflowError as exc:
+            raise HTTPException(status_code=status.HTTP_429_TOO_MANY_REQUESTS, detail=str(exc))
+        except ConnectionError as exc:
+            raise HTTPException(status_code=status.HTTP_502_BAD_GATEWAY, detail=str(exc))
+        return {"status": "queued", "seq": st.seq}
+
+    @router.get("/get_monitor", response_model=MonitorResponse)
+    async def get_monitor(st: LocalServerState = Depends(get_state)):
+        """Gets the last known monitor status."""
+        return await st.snapshot_monitor()
+
+    @router.get("/refresh_monitor")
+    async def refresh_monitor(st: LocalServerState = Depends(get_state), ad: DeviceAdapter = Depends(get_adapter)):
+        """Queues a request to refresh the monitor status."""
+        try:
+            await ad.register_with_device(st)
+            await st.queue_monitor()
+        except ConnectionError as exc:
+            raise HTTPException(status_code=status.HTTP_502_BAD_GATEWAY, detail=str(exc))
+        return PlainTextResponse("queued monitor refresh")
+
+    @router.get("/get_properties", response_model=PropertiesResponse)
+    async def get_properties(st: LocalServerState = Depends(get_state), ad: DeviceAdapter = Depends(get_adapter)):
+        """Gets the last known device properties."""
+        try:
+            await ad.register_with_device(st)
+            await st.queue_properties()
+        except ConnectionError as exc:
+            raise HTTPException(status_code=status.HTTP_502_BAD_GATEWAY, detail=str(exc))
+        return await st.snapshot_properties()
+
+    @router.get("/properties/{property_name}")
+    async def get_property(property_name: str, st: LocalServerState = Depends(get_state)):
+        """Gets a single property value from the last known snapshot."""
+        value = await st.get_property_value(property_name)
+        if value is None:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Property not found")
+        return {"name": property_name, "value": value}
+
+    @router.get("/health")
+    async def health():
+        return PlainTextResponse("ok")
+
+    @router.get("/logs")
+    async def logs():
+        ring_handler = next((h for h in logger.handlers if hasattr(h, "get_events")), None)
+        events = ring_handler.__getattribute__("get_events") if ring_handler else []
+        return {"events": events, "last_command": state.last_command}
+
+    @router.get("/debug_queue")
+    async def debug_queue(st: LocalServerState = Depends(get_state)):
+        async with st.lock:  # type: ignore[attr-defined]
+            next_payload = st.command_queue[0] if st.command_queue else None
+            queued = len(st.command_queue)
+            seq = st.seq
+        return {"queued": queued, "next_payload": next_payload, "seq": seq}
+
+    @router.get("/monitor")
+    async def monitor(st: LocalServerState = Depends(get_state)):
+        async with st.lock:  # type: ignore[attr-defined]
+            return JSONResponse(st.last_monitor)
+
+    # --- Device-Facing API Endpoints (called by the coffee machine) ---
+
+    @router.post("/local_lan/key_exchange.json")
+    async def key_exchange(req: KeyExchangeRequest, st: LocalServerState = Depends(get_state)):
+        """Handles the cryptographic key exchange request from the device."""
+        if not st.lan_key:
+            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Server not configured")
+        exchange = req.key_exchange
+        await st.init_crypto(random_1=exchange.random_1, time_1=exchange.time_1)
+        st.log("key_exchange", {"random_1": exchange.random_1, "time_1": exchange.time_1})
+        return JSONResponse({"random_2": st.random_2, "time_2": int(st.time_2)}, status_code=status.HTTP_202_ACCEPTED)
+
+    async def serve_command_poll(st: LocalServerState) -> CommandPollResponse:
+        """Shared logic for serving the next command to the device."""
+        if not st.keys_ready():
+            st.log("command_poll_no_keys", {"queued": len(st.command_queue)})
+            return CommandPollResponse(enc="", sign="", seq=st.seq)
+
+        next_item = await st.next_command_payload()
+        payload, current_seq = next_item["payload"], next_item["seq"]
+        
+        enc, new_iv = protocol.encrypt_payload(payload, st.app_crypto_key, st.app_iv_seed)
+        st.app_iv_seed = new_iv
+        sign = protocol.sign_payload(payload, st.app_sign_key)
+        async with st.lock:
+            st.command_payload = protocol.build_empty_payload(st.seq)
+        st.log(
+            "command_served",
+            {"seq": current_seq, "queued_remaining": len(st.command_queue), "payload_size": len(payload)},
+        )
+        return CommandPollResponse(enc=enc, sign=sign, seq=current_seq)
+
+    @router.get("/local_lan/commands.json", response_model=CommandPollResponse)
+    async def poll_commands_get(st: LocalServerState = Depends(get_state)):
+        """Endpoint for the device to poll for commands (GET)."""
+        return await serve_command_poll(st)
+
+    @router.post("/local_lan/commands.json", response_model=CommandPollResponse)
+    async def poll_commands_post(st: LocalServerState = Depends(get_state)):
+        """Endpoint for the device to poll for commands (POST)."""
+        return await serve_command_poll(st)
+
+    @router.post("/local_lan/property/datapoint.json")
+    async def datapoint(payload: EncPayload, st: LocalServerState = Depends(get_state)):
+        """Endpoint for the device to push encrypted data to."""
+        if not st.dev_crypto_key or not st.dev_iv_seed:
+            raise HTTPException(status_code=status.HTTP_503_SERVICE_UNAVAILABLE, detail="Keys not initialized")
+        
+        decrypted_bytes, new_iv = protocol.decrypt_payload(payload.enc, st.dev_crypto_key, st.dev_iv_seed)
+        st.dev_iv_seed = new_iv
+        
+        try:
+            decoded = decrypted_bytes.decode("utf-8")
+            decoded_json = json.loads(decoded)
+        except UnicodeDecodeError:
+            st.log("datapoint_decode_failed_utf8", {"cipher": payload.enc[:32]})
+            async with st.lock:
+                st._monitor_request_pending = False
+                st._properties_request_pending = False
+            return Response(status_code=status.HTTP_200_OK)
+        except json.JSONDecodeError:
+            st.log("datapoint_decode_failed_json", {"decoded_prefix": decrypted_bytes[:64].decode('utf-8', 'ignore')})
+            async with st.lock:
+                st._monitor_request_pending = False
+                st._properties_request_pending = False
+            return Response(status_code=status.HTTP_200_OK)
+        
+        await st.handle_datapoint(decoded_json)
+        return {}
+
+    @router.get("/register")
+    async def register(st: LocalServerState = Depends(get_state), ad: DeviceAdapter = Depends(get_adapter)):
+        try:
+            await ad.register_with_device(st)
+        except Exception as exc:
+            st.log("internal_server_error", {"status_code": status.HTTP_500_INTERNAL_SERVER_ERROR, "error": str(exc)})
+            return PlainTextResponse(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR)
+        return PlainTextResponse("registered")
+
+    app.include_router(router)
+
+    async def startup_event():
+        if settings.enable_nudger_job:
+            jobs.start(nudger_job(state, adapter, settings, stop_event), name="nudger")
+        if settings.enable_monitor_job:
+            jobs.start(monitor_job(state, settings, stop_event), name="monitor")
+        if settings.enable_rekey_job:
+            jobs.start(rekey_job(state, adapter, settings, stop_event), name="rekey")
+
+    app.add_event_handler("startup", startup_event)
+
+    async def shutdown_event():
+        stop_event.set()
+        await jobs.stop()
+        await adapter.close()
+
+    app.add_event_handler("shutdown", shutdown_event)
+
+    return app

cremalink/local_server_app/config.py

@@ -0,0 +1,64 @@
+"""
+This module defines the configuration settings for the local server application
+using Pydantic's settings management.
+"""
+from functools import lru_cache
+from typing import Optional
+
+from pydantic import Field
+from pydantic_settings import SettingsConfigDict, BaseSettings
+
+
+class ServerSettings(BaseSettings):
+    """
+    Defines the application's settings, which can be loaded from environment
+    variables or a .env file. This provides a centralized and type-safe way
+    to configure the server's behavior.
+    """
+    # --- Server Network Settings ---
+    server_ip: str = Field("127.0.0.1", validation_alias="SERVER_IP", description="IP address for the server to bind to.")
+    server_port: int = Field(10280, validation_alias="SERVER_PORT", description="Port for the server to listen on.")
+
+    # --- Job Interval Settings ---
+    nudger_poll_interval: float = Field(1.0, validation_alias="NUDGER_POLL_INTERVAL", description="Interval in seconds for the 'nudger' job to poll for command responses.")
+    monitor_poll_interval: float = Field(5.0, validation_alias="MONITOR_POLL_INTERVAL", description="Interval in seconds for the monitor job to fetch device status.")
+    rekey_interval_seconds: float = Field(60.0, validation_alias="REKEY_INTERVAL_SECONDS", description="Interval in seconds to perform the authentication key exchange.")
+
+    # --- Buffer/Queue Size Settings ---
+    queue_max_size: int = Field(200, validation_alias="QUEUE_MAX_SIZE", description="Maximum size of the command queue.")
+    log_ring_size: int = Field(200, validation_alias="LOG_RING_SIZE", description="Maximum number of log entries to keep in the in-memory ring buffer.")
+
+    # --- Device Registration Settings ---
+    device_register_verify: bool = Field(False, validation_alias="DEVICE_REGISTER_VERIFY", description="Whether to verify SSL certificates during device registration.")
+    device_register_ca_path: Optional[str] = Field(None, validation_alias="DEVICE_REGISTER_CA_PATH", description="Path to a custom CA bundle for SSL verification.")
+    device_register_timeout: float = Field(10.0, validation_alias="DEVICE_REGISTER_TIMEOUT", description="Timeout in seconds for the device registration request.")
+    enable_device_register: bool = Field(True, validation_alias="ENABLE_DEVICE_REGISTER", description="Feature flag to enable the device registration process.")
+
+    # --- Job Feature Flags ---
+    enable_nudger_job: bool = Field(True, validation_alias="ENABLE_NUDGER_JOB", description="Feature flag to enable the command polling job.")
+    enable_monitor_job: bool = Field(True, validation_alias="ENABLE_MONITOR_JOB", description="Feature flag to enable the status monitoring job.")
+    enable_rekey_job: bool = Field(True, validation_alias="ENABLE_REKEY_JOB", description="Feature flag to enable the periodic re-keying job.")
+
+    # --- Testing / Determinism Hooks ---
+    # These fields allow for injecting fixed values during tests to make
+    # cryptographic operations deterministic.
+    fixed_random_2: Optional[str] = Field(None, validation_alias="FIXED_RANDOM_2")
+    fixed_time_2: Optional[str] = Field(None, validation_alias="FIXED_TIME_2")
+
+    # Pydantic settings configuration
+    model_config = SettingsConfigDict(
+        env_file=".env",                # Load settings from a .env file.
+        env_file_encoding="utf-8",
+        populate_by_name=True,          # Allow population by field name in addition to alias.
+        extra="ignore"                  # Ignore extra fields from the env file.
+    )
+
+
+@lru_cache
+def get_settings() -> ServerSettings:
+    """
+    Provides a cached, global instance of the ServerSettings.
+    Using lru_cache ensures that the settings are loaded from the environment
+    only once.
+    """
+    return ServerSettings()

cremalink/local_server_app/device_adapter.py

@@ -0,0 +1,96 @@
+"""
+This module provides an adapter for communicating directly with the coffee
+machine device on the local network. Its main purpose is to handle the
+device registration process.
+"""
+from typing import Optional
+
+import httpx
+
+from cremalink.local_server_app.config import ServerSettings
+from cremalink.local_server_app.state import LocalServerState
+
+
+class DeviceAdapter:
+    """
+    Handles direct HTTP communication with the physical coffee machine.
+
+    This class is responsible for the 'registration' step, where this local
+    proxy server informs the coffee machine of its presence, telling it where
+    to send data pushes.
+    """
+
+    def __init__(self, settings: ServerSettings, logger):
+        """
+        Initializes the DeviceAdapter.
+
+        Args:
+            settings: The application's configuration settings.
+            logger: The application's logger instance.
+        """
+        self.settings = settings
+        self.logger = logger
+        self._client: Optional[httpx.AsyncClient] = None
+
+    async def _get_client(self) -> httpx.AsyncClient:
+        """
+        Provides a singleton instance of an `httpx.AsyncClient`.
+
+        The client is configured with timeout and SSL verification settings
+        from the application configuration.
+        """
+        if self._client is None:
+            self._client = httpx.AsyncClient(
+                timeout=self.settings.device_register_timeout,
+                verify=self.settings.device_register_ca_path or self.settings.device_register_verify,
+            )
+        return self._client
+
+    async def register_with_device(self, state: LocalServerState) -> None:
+        """
+        Sends a registration request to the coffee machine.
+
+        This tells the device to send its data updates (like monitor status)
+        to this server's `/local_lan` endpoint.
+
+        Args:
+            state: The current server state, containing device IP and scheme.
+
+        Raises:
+            ValueError: If the device IP is not configured in the state.
+            ConnectionError: If the HTTP request to the device fails.
+        """
+        if not self.settings.enable_device_register:
+            self.logger.info("register_skipped", extra={"details": {"reason": "disabled"}})
+            return
+
+        if not state.device_ip:
+            raise ValueError("Device IP not configured")
+
+        api_url = f"{state.device_scheme}://{state.device_ip}/local_reg.json"
+        # The payload tells the device this server's IP, port, and notification endpoint.
+        payload = {
+            "local_reg": {
+                "ip": self.settings.server_ip,
+                "notify": 1,
+                "port": self.settings.server_port,
+                "uri": "/local_lan",
+            }
+        }
+        client = await self._get_client()
+        try:
+            resp = await client.put(api_url, json=payload)
+            resp.raise_for_status()
+        except httpx.HTTPError as exc:
+            await state.set_registered(False)
+            state.log("local_reg_failed", {"error": str(exc)})
+            raise ConnectionError(f"local_reg failed: {exc}") from exc
+        else:
+            await state.set_registered(True)
+            state.log("local_reg_ok", {"device_ip": state.device_ip, "scheme": state.device_scheme})
+
+    async def close(self) -> None:
+        """Closes the underlying httpx client if it exists."""
+        if self._client:
+            await self._client.aclose()
+            self._client = None

cremalink/local_server_app/jobs.py

@@ -0,0 +1,104 @@
+"""
+This module defines and manages the background jobs for the local server.
+These jobs run periodically in asyncio tasks to handle keep-alive, status
+monitoring, and re-keying operations.
+"""
+import asyncio
+from typing import List
+
+from cremalink.local_server_app.device_adapter import DeviceAdapter
+from cremalink.local_server_app.state import LocalServerState
+from cremalink.local_server_app.config import ServerSettings
+
+
+class JobManager:
+    """A simple manager for starting and stopping asyncio background tasks."""
+
+    def __init__(self):
+        self.tasks: List[asyncio.Task] = []
+
+    def start(self, coro, name: str):
+        """Creates an asyncio task from a coroutine and adds it to the manager."""
+        task = asyncio.create_task(coro, name=name)
+        self.tasks.append(task)
+
+    async def stop(self):
+        """Cancels and cleans up all managed tasks."""
+        for task in self.tasks:
+            task.cancel()
+        # Wait for all tasks to acknowledge cancellation
+        await asyncio.gather(*self.tasks, return_exceptions=True)
+        self.tasks.clear()
+
+
+async def nudger_job(st: LocalServerState, adapter: DeviceAdapter, settings: ServerSettings, stop_event: asyncio.Event):
+    """
+    Periodically "nudges" the device by sending a registration request.
+
+    This is a key part of the protocol. The device often needs to be prompted
+    to send data. This job ensures that registration is maintained, especially
+    if there are pending commands in the queue.
+    """
+    interval = settings.nudger_poll_interval
+    while not stop_event.is_set():
+        try:
+            # Nudge if there are commands waiting or if we aren't registered.
+            async with st.lock:
+                should_nudge = len(st.command_queue) > 0 or not st.registered
+            if should_nudge:
+                await adapter.register_with_device(st)
+        except Exception as exc:
+            st.log("local_reg_nudge_failed", {"error": str(exc)})
+            # If nudging fails, it might be a key issue, so trigger a rekey.
+            await st.rekey()
+        
+        try:
+            # Wait for the specified interval or until the stop event is set.
+            await asyncio.wait_for(stop_event.wait(), timeout=interval)
+        except asyncio.TimeoutError:
+            continue
+
+
+async def monitor_job(st: LocalServerState, settings: ServerSettings, stop_event: asyncio.Event):
+    """
+    Periodically queues a request to fetch the device's monitoring status.
+    """
+    interval = settings.monitor_poll_interval
+    while not stop_event.is_set():
+        try:
+            # Only queue a request if the server is configured and another request isn't already pending.
+            async with st.lock:
+                ready = st.is_configured() and not st._monitor_request_pending
+            if ready:
+                await st.queue_monitor()
+        except Exception as exc:
+            st.log("monitor_poll_failed", {"error": str(exc)})
+        
+        try:
+            await asyncio.wait_for(stop_event.wait(), timeout=interval)
+        except asyncio.TimeoutError:
+            continue
+
+
+async def rekey_job(state: LocalServerState, adapter: DeviceAdapter, settings: ServerSettings, stop_event: asyncio.Event):
+    """
+    Periodically triggers a full cryptographic re-keying process.
+
+    This enhances security by ensuring session keys are not long-lived.
+    """
+    interval = settings.rekey_interval_seconds
+    while not stop_event.is_set():
+        try:
+            # Wait for the rekey interval.
+            await asyncio.wait_for(stop_event.wait(), timeout=interval)
+            break
+        except asyncio.TimeoutError:
+            # Interval elapsed, proceed with re-keying.
+            pass
+        try:
+            state.log("rekey_triggered", {"interval": interval})
+            # Reset keys and re-register with the device.
+            await state.rekey()
+            await adapter.register_with_device(state)
+        except Exception as exc:
+            state.log("rekey_failed", {"error": str(exc)})

cremalink/local_server_app/logging.py

@@ -0,0 +1,116 @@
+"""
+This module provides custom logging setup for the local server application,
+including an in-memory ring buffer for recent log events and a redaction
+function for sensitive data.
+"""
+import logging
+import threading
+from collections import deque
+from typing import Deque, Dict, List, Optional
+
+
+class RingBufferHandler(logging.Handler):
+    """
+    A custom logging handler that stores the most recent log records in a
+    fixed-size in-memory deque (a ring buffer).
+
+    This is useful for exposing recent server activity via an API endpoint
+    without needing to read from a log file.
+    """
+
+    def __init__(self, max_entries: int = 200):
+        """
+        Initializes the handler.
+
+        Args:
+            max_entries: The maximum number of log entries to store.
+        """
+        super().__init__()
+        self.max_entries = max_entries
+        self._events: Deque[Dict] = deque(maxlen=max_entries)
+        self._lock = threading.Lock()  # Lock for thread-safe access to the deque.
+
+    def emit(self, record: logging.LogRecord) -> None:
+        """
+        Formats and adds a log record to the ring buffer.
+
+        Args:
+            record: The log record to be processed.
+        """
+        # Construct a dictionary from the log record for easy JSON serialization.
+        event = {
+            "event": record.getMessage(),
+            "level": record.levelname,
+            "ts": record.created,
+            "details": getattr(record, "details", {}),
+        }
+        with self._lock:
+            self._events.append(event)
+
+    def get_events(self) -> List[Dict]:
+        """
+        Retrieves a thread-safe copy of all events currently in the buffer.
+
+        Returns:
+            A list of log event dictionaries.
+        """
+        with self._lock:
+            return list(self._events)
+
+
+def create_logger(name: str, ring_size: int) -> logging.Logger:
+    """
+    Creates and configures a logger with the RingBufferHandler.
+
+    This function ensures that handlers are not added multiple times to the
+    same logger instance.
+
+    Args:
+        name: The name of the logger.
+        ring_size: The size of the ring buffer for the handler.
+
+    Returns:
+        A configured logging.Logger instance.
+    """
+    logger = logging.getLogger(name)
+    # If the logger already has handlers, assume it's already configured.
+    if logger.handlers:
+        return logger
+
+    logger.setLevel(logging.INFO)
+    handler = RingBufferHandler(max_entries=ring_size)
+    formatter = logging.Formatter("%(asctime)s %(levelname)s %(message)s")
+    handler.setFormatter(formatter)
+    logger.addHandler(handler)
+    # Stop log messages from propagating to the root logger.
+    logger.propagate = False
+    return logger
+
+
+def redact(details: Optional[dict]) -> dict:
+    """
+    Filters a dictionary, replacing values of sensitive keys with '***'.
+
+    This is a security measure to prevent secret keys, tokens, and other
+    sensitive data from being exposed in logs.
+
+    Args:
+        details: A dictionary that may contain sensitive data.
+
+    Returns:
+        A new dictionary with sensitive values redacted.
+    """
+    if not details:
+        return {}
+
+    redacted_keys = {
+        "lan_key", "app_crypto_key", "dev_crypto_key", "app_iv_seed",
+        "dev_iv_seed", "enc", "sign"
+    }
+    cleaned = {}
+    for key, value in details.items():
+        if key in redacted_keys:
+            cleaned[key] = "***"
+        else:
+            cleaned[key] = value
+    return cleaned