chore: ruff py313, conftest unification, audit log, app factory comune

- pyproject.toml: ruff target-version py311 → py313 (auto-fix 42 lint
  warnings via UP rules); aggiunto consider_namespace_packages = true
  che risolve la collisione conftest tra servizi e permette di lanciare
  pytest sull'intera suite cross-servizio.

- mcp_common.audit: nuovo helper audit_write_op() con logger dedicato
  mcp.audit. Wirato su tutti i write endpoint di deribit, bybit, alpaca
  e hyperliquid (place_order, place_combo_order, cancel_*, set_*,
  close_*, transfer_*, switch_*, amend_*) con principal + target +
  payload non-sensibile + result summarizzato.

- mcp_common.app_factory: ExchangeAppSpec + run_exchange_main()
  centralizza il boilerplate dei __main__.py (configure_root_logging,
  fail_fast_if_missing, summarize, load creds, resolve_environment,
  load token store, uvicorn). I 4 __main__.py exchange ridotti da ~60
  LOC ognuno a ~25 LOC dichiarativi. mcp_common.env_validation
  promosso da mcp_deribit (mantenuto re-export shim per back-compat
  test_env_validation).

- 8 test nuovi (4 audit + 4 app_factory). Suite full: 450/450 verdi.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

services/common/src/mcp_common/app_factory.py

@@ -0,0 +1,86 @@
+"""App factory comune per i servizi mcp-{exchange}.
+
+Centralizza il boilerplate dei `__main__.py`:
+- configure_root_logging (JSON)
+- fail_fast_if_missing su env mandatory
+- summarize env
+- load creds JSON
+- resolve_environment con default URLs
+- load token store
+- delega creazione client + app a callback per-servizio
+- uvicorn.run
+
+Ogni servizio invoca `run_exchange_main(spec)` con uno spec dichiarativo.
+"""
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+import uvicorn
+
+from mcp_common.auth import load_token_store_from_files
+from mcp_common.env_validation import fail_fast_if_missing, require_env, summarize
+from mcp_common.environment import EnvironmentInfo, resolve_environment
+from mcp_common.logging import configure_root_logging
+
+
+@dataclass(frozen=True)
+class ExchangeAppSpec:
+    exchange: str
+    creds_env_var: str
+    env_var: str  # es. "BYBIT_TESTNET", "ALPACA_PAPER"
+    flag_key: str  # campo nel secret JSON ("testnet" o "paper")
+    default_base_url_live: str
+    default_base_url_testnet: str
+    default_port: int
+    build_client: Callable[[dict, EnvironmentInfo], Any]
+    build_app: Callable[..., Any]
+    extra_summarize_envs: tuple[str, ...] = ()
+
+
+def run_exchange_main(spec: ExchangeAppSpec) -> None:
+    configure_root_logging()
+
+    fail_fast_if_missing([spec.creds_env_var])
+    summarize([
+        spec.creds_env_var,
+        "CORE_TOKEN_FILE",
+        "OBSERVER_TOKEN_FILE",
+        "PORT",
+        "HOST",
+        spec.env_var,
+        *spec.extra_summarize_envs,
+    ])
+
+    creds_file = require_env(spec.creds_env_var, f"{spec.exchange} credentials JSON path")
+    with open(creds_file) as f:
+        creds = json.load(f)
+
+    env_info = resolve_environment(
+        creds,
+        env_var=spec.env_var,
+        flag_key=spec.flag_key,
+        exchange=spec.exchange,
+        default_base_url_live=spec.default_base_url_live,
+        default_base_url_testnet=spec.default_base_url_testnet,
+    )
+
+    client = spec.build_client(creds, env_info)
+
+    token_store = load_token_store_from_files(
+        core_token_file=os.environ.get("CORE_TOKEN_FILE"),
+        observer_token_file=os.environ.get("OBSERVER_TOKEN_FILE"),
+    )
+
+    app = spec.build_app(client=client, token_store=token_store, creds=creds, env_info=env_info)
+
+    uvicorn.run(
+        app,
+        log_config=None,
+        host=os.environ.get("HOST", "0.0.0.0"),
+        port=int(os.environ.get("PORT", str(spec.default_port))),
+    )

services/common/src/mcp_common/audit.py

@@ -0,0 +1,74 @@
+"""Audit log strutturato per write endpoint MCP (place_order, cancel,
+set_*, close_*, transfer_*). Usa un logger dedicato `mcp.audit` su stream
+JSON: in deployment può essere redirezionato a file/syslog/SIEM separato.
+
+Logica:
+- `audit_write_op(principal, action, exchange, target, payload, result)`
+  emette UN record JSON per ogni operazione con esito (ok/error).
+- Payload sensibile (api_key, secret) già filtrato dal SecretsFilter
+  globale; qui non si include creds.
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from mcp_common.auth import Principal
+from mcp_common.logging import get_json_logger
+
+_logger = get_json_logger("mcp.audit", level=logging.INFO)
+
+
+def audit_write_op(
+    *,
+    principal: Principal | None,
+    action: str,
+    exchange: str,
+    target: str | None = None,
+    payload: dict[str, Any] | None = None,
+    result: dict[str, Any] | None = None,
+    error: str | None = None,
+) -> None:
+    """Emit a structured audit log record per write operation.
+
+    principal: chi ha invocato (None se anonimo, ma normalmente _check
+        impedisce di arrivare qui senza principal).
+    action: nome del tool (es. "place_order", "cancel_order").
+    exchange: identificatore servizio (deribit, bybit, alpaca, hyperliquid).
+    target: instrument/symbol/order_id su cui si agisce.
+    payload: input non-sensibile (qty, side, leverage, ecc.).
+    result: output del client (order_id, status, ecc.).
+    error: stringa errore se l'operazione ha fallito.
+    """
+    record: dict[str, Any] = {
+        "audit_event": "write_op",
+        "action": action,
+        "exchange": exchange,
+        "principal": principal.name if principal else None,
+        "target": target,
+        "payload": payload or {},
+    }
+    if result is not None:
+        record["result"] = _summarize_result(result)
+    if error is not None:
+        record["error"] = error
+        _logger.error("audit", extra=record)
+    else:
+        _logger.info("audit", extra=record)
+
+
+def _summarize_result(result: dict[str, Any]) -> dict[str, Any]:
+    """Estrae i campi rilevanti dal result (order_id, state, error code)
+    per evitare di loggare payload enormi.
+    """
+    keys = (
+        "order_id", "order_link_id", "combo_instrument", "state", "status",
+        "code", "error", "stop_price", "tp_price", "transfer_id",
+    )
+    out: dict[str, Any] = {}
+    for k in keys:
+        if k in result:
+            out[k] = result[k]
+    if "orders" in result:
+        out["orders_count"] = len(result["orders"])
+    return out

services/common/src/mcp_common/env_validation.py

@@ -0,0 +1,69 @@
+"""Env validation policy: fail-fast per mandatory, soft per optional.
+
+Usage al boot di ogni mcp `__main__.py`:
+
+    from mcp_common.env_validation import require_env, optional_env, summarize
+
+    creds_file = require_env("CREDENTIALS_FILE", "deribit credentials JSON path")
+    host = optional_env("HOST", default="0.0.0.0")
+    summarize(["CREDENTIALS_FILE", "HOST", "PORT"])
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+
+logger = logging.getLogger(__name__)
+
+
+class MissingEnvError(RuntimeError):
+    """Mandatory env var absent or empty."""
+
+
+def require_env(name: str, description: str = "") -> str:
+    val = (os.environ.get(name) or "").strip()
+    if not val:
+        msg = f"missing mandatory env var: {name}"
+        if description:
+            msg += f" ({description})"
+        logger.error(msg)
+        raise MissingEnvError(msg)
+    return val
+
+
+def optional_env(name: str, *, default: str = "") -> str:
+    val = (os.environ.get(name) or "").strip()
+    if not val:
+        if default:
+            logger.info("env %s not set, using default=%r", name, default)
+        return default
+    return val
+
+
+def summarize(names: list[str]) -> None:
+    sensitive_tokens = ("SECRET", "KEY", "TOKEN", "PASSWORD", "CREDENTIAL", "WALLET")
+    for n in names:
+        val = os.environ.get(n)
+        if val is None:
+            logger.info("env[%s]: <unset>", n)
+            continue
+        if any(t in n.upper() for t in sensitive_tokens):
+            logger.info("env[%s]: <set, %d chars>", n, len(val))
+        else:
+            logger.info("env[%s]: %s", n, val)
+
+
+def fail_fast_if_missing(names: list[str]) -> None:
+    missing: list[str] = []
+    for n in names:
+        if not (os.environ.get(n) or "").strip():
+            missing.append(n)
+    if missing:
+        logger.error("boot aborted: missing mandatory env vars: %s", missing)
+        print(
+            f"FATAL: missing mandatory env vars: {missing}",
+            file=sys.stderr,
+        )
+        sys.exit(2)

services/common/src/mcp_common/mcp_bridge.py

@@ -40,6 +40,7 @@ def _derive_input_schemas(app: FastAPI, tool_names: list[str]) -> dict[str, dict
     risolvibili vengono saltate: il chiamante userà un fallback.
     """
     import typing
+
     from pydantic import BaseModel
 
     names_set = set(tool_names)

services/common/src/mcp_common/server.py

@@ -4,10 +4,9 @@ import json
 import os
 import time
 import uuid
-from datetime import UTC, datetime
-
 from collections.abc import Callable
 from contextlib import AbstractAsyncContextManager
+from datetime import UTC, datetime
 
 from fastapi import FastAPI, HTTPException, Request
 from fastapi.exceptions import RequestValidationError