SessionSmith 2.0.0__tar.gz → 2.1.0__tar.gz

{sessionsmith-2.0.0 → sessionsmith-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: SessionSmith
-Version: 2.0.0
+Version: 2.1.0
 Summary: Git-style session management for Python. Save, restore, and track your variables with ease.
 Home-page: https://github.com/yut0takagi/SessionSmith
 Author: YutoTAKAGI
@@ -33,6 +33,15 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Provides-Extra: visualization
 Requires-Dist: matplotlib>=3.5.0; extra == "visualization"
+Provides-Extra: crypto
+Requires-Dist: cryptography>=3.4; extra == "crypto"
+Provides-Extra: s3
+Requires-Dist: boto3>=1.26; extra == "s3"
+Provides-Extra: gcs
+Requires-Dist: google-cloud-storage>=2.0; extra == "gcs"
+Provides-Extra: cloud
+Requires-Dist: boto3>=1.26; extra == "cloud"
+Requires-Dist: google-cloud-storage>=2.0; extra == "cloud"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
@@ -41,8 +50,12 @@ Requires-Dist: black>=23.0.0; extra == "dev"
 Requires-Dist: isort>=5.12.0; extra == "dev"
 Requires-Dist: mypy>=1.0.0; extra == "dev"
 Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: cryptography>=3.4; extra == "dev"
 Provides-Extra: all
 Requires-Dist: matplotlib>=3.5.0; extra == "all"
+Requires-Dist: cryptography>=3.4; extra == "all"
+Requires-Dist: boto3>=1.26; extra == "all"
+Requires-Dist: google-cloud-storage>=2.0; extra == "all"
 Dynamic: author
 Dynamic: home-page
 Dynamic: license-file
@@ -78,6 +91,9 @@ Dynamic: requires-python
 - 🚀 **拡張機能対応**: Cursor/VSCode拡張機能でコードを書かずに実行可能
 - 🌐 **多言語対応**: 日本語・英語のエラーメッセージに対応
 - 🛡️ **堅牢なエラーハンドリング**: リトライ、詳細なエラー情報、コンテキスト管理
+- ☁️ **クラウドリモート**（v2.1.0）: S3 / GCS / HTTP へ `push` / `pull`
+- 🔐 **暗号化・改ざん検出**（v2.1.0）: 認証付き暗号でのエクスポート、HMAC 署名による検証
+- 📝 **構造化ロギング**（v2.1.0）: ログレベル・ファイル出力・JSON ログ
 
 ## インストール
 
@@ -105,6 +121,18 @@ pip install SessionSmith[visualization]
 pip install matplotlib
 ```
 
+オプション機能（v2.1.0）:
+
+```bash
+pip install SessionSmith[crypto]   # 暗号化（cryptography）
+pip install SessionSmith[s3]       # S3 リモート（boto3）
+pip install SessionSmith[gcs]      # GCS リモート（google-cloud-storage）
+pip install SessionSmith[cloud]    # S3 + GCS
+pip install SessionSmith[all]      # すべて
+```
+
+> 署名（HMAC）・構造化ロギングは追加依存なしで利用できます。
+
 ## クイックスタート
 
 ### SSM - Git風セッション管理（推奨）
@@ -228,6 +256,61 @@ lang = get_language()  # 'ja' または 'en'
 エラーメッセージや情報メッセージが設定した言語で表示されます。
 SSMが初期化されている場合、言語設定は自動的に `.ssm/config` に保存されます。
 
+### クラウド / URL リモート（v2.1.0）
+
+```python
+from SessionSmith import ssm
+
+ssm.init()
+ssm.commit("experiment v1")
+
+# クラウドリモートを登録して push / pull
+ssm.remote_add("cloud", "s3://my-bucket/experiments")      # S3
+# ssm.remote_add("cloud", "gs://my-bucket/experiments")    # GCS
+# ssm.remote_add("cloud", "file:///shared/ssm-remote")     # 共有ディレクトリ
+ssm.push("cloud", "main")
+
+# 別マシン / 別リポジトリから取得
+ssm.pull("cloud", "main")
+
+# HTTP(S) 越しの読み取り（pull のみ）
+ssm.remote_add("mirror", "https://example.com/ssm-repo")
+ssm.pull("mirror", "main")
+```
+
+### 暗号化・改ざん検出（v2.1.0）
+
+```python
+from SessionSmith import ssm
+
+# --- 暗号化（要 pip install SessionSmith[crypto]）---
+ssm.export("backup.pkl", password="my-secret")          # 暗号化してエクスポート
+ssm.import_session("backup.pkl", password="my-secret")  # 復号してインポート
+ssm.push("cloud", "main", password="my-secret")         # リモート上のデータを暗号化
+
+# --- 改ざん検出（HMAC 署名・追加依存なし）---
+ssm.config("sign_key", "team-secret")  # 署名鍵を設定（環境変数 SESSIONSMITH_SIGN_KEY でも可）
+ssm.commit("signed snapshot")          # 以降のコミットに署名が付与される
+
+result = ssm.verify()  # 整合性（再ハッシュ）と署名を検証
+# {'integrity_ok': True, 'signed': True, 'signature_ok': True, 'issues': []}
+```
+
+### 構造化ロギング（v2.1.0）
+
+```python
+from SessionSmith import setup_logging, enable_debug, set_log_level
+
+setup_logging(level="INFO", log_file="ssm.log")  # ファイル出力（ローテーション付き）
+setup_logging(level="INFO", json_format=True)    # JSON 構造化ログ
+enable_debug()                                   # デバッグモード
+
+# 環境変数でも設定可能:
+#   SESSIONSMITH_LOG_LEVEL=DEBUG
+#   SESSIONSMITH_LOG_FILE=ssm.log
+#   SESSIONSMITH_LOG_JSON=1
+```
+
 ### レガシーAPI（後方互換性）
 
 > ⚠️ 以下のAPIは後方互換性のために残されています。新規開発では `ssm` の使用を推奨します。
@@ -407,6 +490,10 @@ SessionSmithには、Cursor/VSCode用の拡張機能が用意されています
 
 ### 機能
 
+- 🌳 **Session Graph（v0.2.0〜）**: `.ssm/` のコミット履歴を gitgraph 風に可視化。
+  ブランチのレーン色分け、マージの分岐・合流、ブランチ/タグ/HEADバッジ、コミット詳細
+  （変数一覧・署名状態）、GUI からの Checkout / Branch / Tag / Commit に対応
+- 🗂 **Sessions ビュー（v0.2.0〜）**: アクティビティバーにブランチ・タグ・コミットのツリー表示
 - ✅ **Save Session**: 現在のPythonセッション（変数）を保存
 - ✅ **Load Session**: セッションファイルを選択して変数を復元
 - ✅ **Show Session Info**: セッションファイルの情報を表示

{sessionsmith-2.0.0 → sessionsmith-2.1.0}/SessionSmith/__init__.py

@@ -39,6 +39,16 @@ from .compare import compare_sessions, print_comparison
 
 # 後方互換性のためのAPI（非推奨）
 from .core import load_session, save_session
+
+# セキュリティ（暗号化・署名）
+from .crypto import (
+    HAS_CRYPTOGRAPHY,
+    CryptoError,
+    decrypt_data,
+    encrypt_data,
+    sign_data,
+    verify_signature,
+)
 from .error_handling import (
     ErrorHandler,
     error_context,
@@ -76,6 +86,17 @@ from .exceptions import (
 )
 from .i18n import Language, get_language, set_language, t, translate
 from .info import get_session_info, list_session_variables, print_session_info
+
+# ロギング設定
+from .logging_config import (
+    configure_from_env as _configure_logging_from_env,
+)
+from .logging_config import (
+    enable_debug,
+    get_log_level,
+    set_log_level,
+    setup_logging,
+)
 from .manager import SessionManager
 from .serializers import CustomSerializer
 from .ssm import (
@@ -97,7 +118,13 @@ from .tracer import AlgorithmTracer
 from .utils import verify_session
 from .visualizer import print_trace_summary, visualize_algorithm_trace
 
-__version__ = "2.0.0"
+__version__ = "2.1.0"
+
+# 環境変数からロギングを自動設定（SESSIONSMITH_LOG_LEVEL / SESSIONSMITH_LOG_FILE）
+try:
+    _configure_logging_from_env()
+except Exception:  # pragma: no cover - ロギング設定失敗で import を妨げない
+    pass
 
 __all__ = [
     # 主要API（推奨）
@@ -134,6 +161,18 @@ __all__ = [
     "ErrorHandler",
     "set_default_error_handler",
     "get_default_error_handler",
+    # ロギング
+    "setup_logging",
+    "set_log_level",
+    "get_log_level",
+    "enable_debug",
+    # セキュリティ（暗号化・署名）
+    "encrypt_data",
+    "decrypt_data",
+    "sign_data",
+    "verify_signature",
+    "CryptoError",
+    "HAS_CRYPTOGRAPHY",
     # ブランチ・マージ・タグ・リモート機能
     "branch",
     "checkout_branch",

sessionsmith-2.1.0/SessionSmith/crypto.py

@@ -0,0 +1,205 @@
+"""
+暗号化・署名モジュール（セキュリティ機能）
+
+このモジュールは2つの独立した機能を提供します:
+
+1. **整合性・改ざん検出（署名）**: HMAC-SHA256 を使用。Python標準ライブラリ
+   のみで動作し、追加の依存関係は不要です。コミットやエクスポートしたデータの
+   改ざんを検出できます。
+
+2. **暗号化**: 認証付き暗号（Fernet / AES-128-CBC + HMAC）を使用。`cryptography`
+   パッケージが必要です（``pip install SessionSmith[crypto]``）。パスワードから
+   PBKDF2-HMAC-SHA256 で鍵を導出します。
+
+Note:
+    暗号化はエクスポート／インポートやリモートとの同期など、データが SessionSmith
+    の管理下を離れる「境界」での利用を想定しています。pickle ファイルを平文のまま
+    共有・バックアップするリスクを軽減します。
+"""
+
+import base64
+import hashlib
+import hmac
+import os
+import struct
+from typing import Optional
+
+# 暗号化用のオプショナル依存
+# ImportError だけでなく、ネイティブ拡張（cffi/rust）の読み込み失敗など
+# 環境依存の例外も握りつぶし、暗号化機能を無効化して degrade させる。
+try:
+    from cryptography.fernet import Fernet, InvalidToken
+
+    HAS_CRYPTOGRAPHY = True
+except BaseException:  # noqa: BLE001  # pragma: no cover - 依存がない/壊れている環境向け
+    # ImportError に加え、ネイティブ拡張（cffi/pyo3）の読み込み失敗による
+    # PanicException（BaseException 派生）等もここで握りつぶし degrade させる。
+    HAS_CRYPTOGRAPHY = False
+    Fernet = None  # type: ignore
+    InvalidToken = Exception  # type: ignore
+
+
+# 暗号化済みデータを識別するためのマジックヘッダー
+MAGIC = b"SSMENC01"
+# 鍵導出のデフォルト反復回数（PBKDF2）
+DEFAULT_ITERATIONS = 200_000
+# ソルト長（バイト）
+SALT_SIZE = 16
+
+
+class CryptoError(Exception):
+    """暗号化・復号・署名検証に関するエラー"""
+
+
+class CryptoDependencyError(CryptoError):
+    """暗号化に必要な依存パッケージが不足している場合のエラー"""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "Encryption requires the 'cryptography' package. "
+            "Install it with: pip install SessionSmith[crypto]"
+        )
+
+
+# ========== 署名（HMAC-SHA256, 標準ライブラリのみ） ==========
+
+
+def sign_data(data: bytes, key: str) -> str:
+    """
+    データに HMAC-SHA256 署名を付与します（改ざん検出用）。
+
+    Args:
+        data: 署名対象のバイト列
+        key: 署名鍵（秘密鍵）
+
+    Returns:
+        str: 16進数の署名文字列
+    """
+    if not isinstance(data, bytes):
+        raise TypeError("data must be bytes")
+    return hmac.new(key.encode("utf-8"), data, hashlib.sha256).hexdigest()
+
+
+def verify_signature(data: bytes, signature: str, key: str) -> bool:
+    """
+    HMAC-SHA256 署名を検証します（タイミング攻撃に耐性のある比較）。
+
+    Args:
+        data: 検証対象のバイト列
+        signature: 期待される署名（16進数文字列）
+        key: 署名鍵
+
+    Returns:
+        bool: 署名が一致すれば True
+    """
+    if not signature:
+        return False
+    expected = sign_data(data, key)
+    return hmac.compare_digest(expected, signature)
+
+
+# ========== 暗号化（Fernet, オプショナル） ==========
+
+
+def _derive_fernet_key(password: str, salt: bytes, iterations: int = DEFAULT_ITERATIONS) -> bytes:
+    """
+    パスワードから Fernet 用の鍵（url-safe base64 でエンコードされた32バイト）を導出します。
+
+    PBKDF2-HMAC-SHA256 を標準ライブラリで実行するため、cryptography の鍵導出機能には
+    依存しません。
+    """
+    dk = hashlib.pbkdf2_hmac("sha256", password.encode("utf-8"), salt, iterations, dklen=32)
+    return base64.urlsafe_b64encode(dk)
+
+
+def is_encrypted(blob: bytes) -> bool:
+    """データが SessionSmith により暗号化されたものか判定します。"""
+    return isinstance(blob, bytes) and blob[: len(MAGIC)] == MAGIC
+
+
+def encrypt_data(data: bytes, password: str, iterations: int = DEFAULT_ITERATIONS) -> bytes:
+    """
+    データを暗号化します（認証付き暗号）。
+
+    出力フォーマット::
+
+        MAGIC(8) | iterations(uint32 BE) | salt(16) | Fernet token(...)
+
+    Args:
+        data: 平文のバイト列
+        password: 暗号化パスワード
+        iterations: PBKDF2 の反復回数
+
+    Returns:
+        bytes: 暗号化されたバイト列（``is_encrypted`` が True を返す形式）
+
+    Raises:
+        CryptoDependencyError: cryptography パッケージが無い場合
+    """
+    if not HAS_CRYPTOGRAPHY:
+        raise CryptoDependencyError()
+    if not password:
+        raise CryptoError("Password must not be empty")
+    if not isinstance(data, bytes):
+        raise TypeError("data must be bytes")
+
+    salt = os.urandom(SALT_SIZE)
+    key = _derive_fernet_key(password, salt, iterations)
+    token = Fernet(key).encrypt(data)
+    header = MAGIC + struct.pack(">I", iterations) + salt
+    return header + token
+
+
+def decrypt_data(blob: bytes, password: str) -> bytes:
+    """
+    ``encrypt_data`` で暗号化されたデータを復号します。
+
+    Args:
+        blob: 暗号化されたバイト列
+        password: 復号パスワード
+
+    Returns:
+        bytes: 復号された平文
+
+    Raises:
+        CryptoDependencyError: cryptography パッケージが無い場合
+        CryptoError: フォーマット不正・パスワード誤り・改ざんを検出した場合
+    """
+    if not HAS_CRYPTOGRAPHY:
+        raise CryptoDependencyError()
+    if not is_encrypted(blob):
+        raise CryptoError("Data is not in SessionSmith encrypted format")
+
+    header_len = len(MAGIC) + 4 + SALT_SIZE
+    if len(blob) < header_len:
+        raise CryptoError("Encrypted data is truncated or corrupted")
+
+    iterations = struct.unpack(">I", blob[len(MAGIC) : len(MAGIC) + 4])[0]
+    salt = blob[len(MAGIC) + 4 : header_len]
+    token = blob[header_len:]
+
+    key = _derive_fernet_key(password, salt, iterations)
+    try:
+        return Fernet(key).decrypt(token)
+    except InvalidToken as e:
+        raise CryptoError(
+            "Failed to decrypt: wrong password or the data has been tampered with"
+        ) from e
+
+
+def maybe_decrypt(blob: bytes, password: Optional[str]) -> bytes:
+    """
+    暗号化されていれば復号し、そうでなければそのまま返します。
+
+    Args:
+        blob: 読み込んだバイト列
+        password: パスワード（None で暗号化されていない場合はそのまま）
+
+    Returns:
+        bytes: 平文のバイト列
+    """
+    if is_encrypted(blob):
+        if not password:
+            raise CryptoError("Data is encrypted but no password was provided")
+        return decrypt_data(blob, password)
+    return blob

sessionsmith-2.1.0/SessionSmith/logging_config.py

@@ -0,0 +1,194 @@
+"""
+構造化ロギング設定モジュール
+
+SessionSmith 全体のロガー（``SessionSmith`` 名前空間）を一元的に設定します。
+
+- コンソール／ファイルへの出力
+- ログレベルの設定
+- 通常形式 / JSON 形式（構造化ログ）の切り替え
+- ローテーション（サイズベース）
+- 環境変数による設定
+
+環境変数:
+    SESSIONSMITH_LOG_LEVEL  ログレベル（DEBUG/INFO/WARNING/ERROR/CRITICAL）
+    SESSIONSMITH_LOG_FILE   ログファイルの出力先パス
+    SESSIONSMITH_LOG_JSON   "1"/"true" で JSON 形式の構造化ログを有効化
+
+使用例:
+    >>> from SessionSmith import setup_logging, enable_debug
+    >>> setup_logging(level="INFO", log_file="ssm.log")
+    >>> enable_debug()  # デバッグモードを有効化
+"""
+
+import json
+import logging
+import logging.handlers
+import os
+from pathlib import Path
+from typing import Optional, Union
+
+# SessionSmith 全体のルートロガー
+ROOT_LOGGER_NAME = "SessionSmith"
+
+DEFAULT_FORMAT = "%(asctime)s [%(levelname)s] %(name)s: %(message)s"
+DEFAULT_DATE_FORMAT = "%Y-%m-%d %H:%M:%S"
+
+# setup_logging で追加したハンドラーを識別するためのマーカー属性
+_HANDLER_MARKER = "_sessionsmith_handler"
+
+_configured = False
+
+
+class JsonFormatter(logging.Formatter):
+    """ログレコードを JSON 1行で出力するフォーマッター（構造化ログ）。"""
+
+    def format(self, record: logging.LogRecord) -> str:
+        payload = {
+            "timestamp": self.formatTime(record, DEFAULT_DATE_FORMAT),
+            "level": record.levelname,
+            "logger": record.name,
+            "message": record.getMessage(),
+        }
+        if record.exc_info:
+            payload["exception"] = self.formatException(record.exc_info)
+        # 追加の文脈情報（extra=...）を含める
+        standard = set(logging.LogRecord("", 0, "", 0, "", (), None).__dict__)
+        standard.update({"message", "asctime"})
+        for key, value in record.__dict__.items():
+            if key not in standard and not key.startswith("_"):
+                payload[key] = value
+        return json.dumps(payload, ensure_ascii=False, default=str)
+
+
+def _normalize_level(level: Union[int, str]) -> int:
+    """ログレベルを int に正規化します。"""
+    if isinstance(level, int):
+        return level
+    resolved = logging.getLevelName(str(level).upper())
+    if not isinstance(resolved, int):
+        raise ValueError(f"Invalid log level: {level}")
+    return resolved
+
+
+def _remove_managed_handlers(logger: logging.Logger) -> None:
+    """setup_logging が以前に追加したハンドラーを取り除きます（多重設定防止）。"""
+    for handler in list(logger.handlers):
+        if getattr(handler, _HANDLER_MARKER, False):
+            logger.removeHandler(handler)
+            try:
+                handler.close()
+            except Exception:
+                pass
+
+
+def setup_logging(
+    level: Union[int, str] = "INFO",
+    log_file: Optional[Union[str, Path]] = None,
+    *,
+    console: bool = True,
+    json_format: bool = False,
+    fmt: str = DEFAULT_FORMAT,
+    max_bytes: int = 5 * 1024 * 1024,
+    backup_count: int = 3,
+) -> logging.Logger:
+    """
+    SessionSmith のロギングを設定します。
+
+    Args:
+        level: ログレベル（"DEBUG" 等の文字列または ``logging.DEBUG`` 等の int）
+        log_file: ログファイルの出力先（None でファイル出力なし）
+        console: コンソール（stderr）へ出力するか
+        json_format: JSON 形式の構造化ログを使用するか
+        fmt: 通常形式のフォーマット文字列
+        max_bytes: ログファイルのローテーション閾値（バイト）
+        backup_count: 保持するローテーションファイル数
+
+    Returns:
+        logging.Logger: 設定済みの SessionSmith ルートロガー
+    """
+    global _configured
+
+    logger = logging.getLogger(ROOT_LOGGER_NAME)
+    logger.setLevel(_normalize_level(level))
+    # ルートロガーへの伝播を止め、重複出力を防ぐ
+    logger.propagate = False
+
+    _remove_managed_handlers(logger)
+
+    formatter: logging.Formatter = JsonFormatter() if json_format else logging.Formatter(
+        fmt, datefmt=DEFAULT_DATE_FORMAT
+    )
+
+    if console:
+        stream_handler = logging.StreamHandler()
+        stream_handler.setFormatter(formatter)
+        setattr(stream_handler, _HANDLER_MARKER, True)
+        logger.addHandler(stream_handler)
+
+    if log_file is not None:
+        log_path = Path(log_file)
+        if log_path.parent and not log_path.parent.exists():
+            log_path.parent.mkdir(parents=True, exist_ok=True)
+        file_handler = logging.handlers.RotatingFileHandler(
+            str(log_path),
+            maxBytes=max_bytes,
+            backupCount=backup_count,
+            encoding="utf-8",
+        )
+        file_handler.setFormatter(formatter)
+        setattr(file_handler, _HANDLER_MARKER, True)
+        logger.addHandler(file_handler)
+
+    # ハンドラーが何も無い場合は NullHandler を入れて警告を抑制
+    if not logger.handlers:
+        logger.addHandler(logging.NullHandler())
+
+    _configured = True
+    return logger
+
+
+def set_log_level(level: Union[int, str]) -> None:
+    """SessionSmith ロガーのログレベルを変更します。"""
+    logging.getLogger(ROOT_LOGGER_NAME).setLevel(_normalize_level(level))
+
+
+def get_log_level() -> str:
+    """現在の SessionSmith ロガーのログレベル名を返します。"""
+    return logging.getLevelName(logging.getLogger(ROOT_LOGGER_NAME).level)
+
+
+def enable_debug(log_file: Optional[Union[str, Path]] = None) -> logging.Logger:
+    """
+    デバッグモードを有効化します（DEBUG レベル + コンソール出力）。
+
+    Args:
+        log_file: 併せてファイル出力する場合のパス
+
+    Returns:
+        logging.Logger: 設定済みのロガー
+    """
+    return setup_logging(level="DEBUG", log_file=log_file, console=True)
+
+
+def configure_from_env() -> Optional[logging.Logger]:
+    """
+    環境変数からロギングを設定します。
+
+    ``SESSIONSMITH_LOG_LEVEL`` または ``SESSIONSMITH_LOG_FILE`` のいずれかが
+    設定されている場合のみ設定を行います。
+
+    Returns:
+        logging.Logger or None: 設定した場合はロガー、未設定なら None
+    """
+    level = os.environ.get("SESSIONSMITH_LOG_LEVEL")
+    log_file = os.environ.get("SESSIONSMITH_LOG_FILE")
+    json_format = os.environ.get("SESSIONSMITH_LOG_JSON", "").lower() in ("1", "true", "yes")
+
+    if not level and not log_file:
+        return None
+
+    return setup_logging(
+        level=level or "INFO",
+        log_file=log_file,
+        json_format=json_format,
+    )