debug-control-plane 0.4.0__tar.gz → 0.5.0__tar.gz

{debug_control_plane-0.4.0 → debug_control_plane-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: debug-control-plane
-Version: 0.4.0
+Version: 0.5.0
 Summary: Multi-product reusable debug control plane (device discovery + MCP adapter).
 Author: tangxiaolu
 License: MIT
@@ -62,7 +62,7 @@ python/
 ├── README.md                       # this file
 ├── LICENSE                         # MIT
 └── debug_control_plane/
-    ├── __init__.py                 # __version__ = "0.4.0"
+    ├── __init__.py                 # __version__ = "0.5.0"
     ├── device_discovery/           # USB/LAN device discovery + device pool
     │   ├── device_candidates.py
     │   ├── device_pool.py          # identity-keyed pool, TTL expiry / 身份键池，TTL 过期
@@ -92,8 +92,8 @@ Points at `debug_control_plane.mcp_plane.server:main` — a bare server (no busi
 
 ## Version / 版本
 
-`0.4.0` — aligned with Kotlin/Dart/Flutter `0.4.0`, API unstable.
-`0.4.0` —— 与 Kotlin/Dart/Flutter `0.4.0` 对齐，API 不稳定。
+`0.5.0` — aligned with Kotlin/Dart/Flutter `0.5.0`, API unstable.
+`0.5.0` —— 与 Kotlin/Dart/Flutter `0.5.0` 对齐，API 不稳定。
 
 ## License / 许可证
 

{debug_control_plane-0.4.0 → debug_control_plane-0.5.0}/README.md

@@ -43,7 +43,7 @@ python/
 ├── README.md                       # this file
 ├── LICENSE                         # MIT
 └── debug_control_plane/
-    ├── __init__.py                 # __version__ = "0.4.0"
+    ├── __init__.py                 # __version__ = "0.5.0"
     ├── device_discovery/           # USB/LAN device discovery + device pool
     │   ├── device_candidates.py
     │   ├── device_pool.py          # identity-keyed pool, TTL expiry / 身份键池，TTL 过期
@@ -73,8 +73,8 @@ Points at `debug_control_plane.mcp_plane.server:main` — a bare server (no busi
 
 ## Version / 版本
 
-`0.4.0` — aligned with Kotlin/Dart/Flutter `0.4.0`, API unstable.
-`0.4.0` —— 与 Kotlin/Dart/Flutter `0.4.0` 对齐，API 不稳定。
+`0.5.0` — aligned with Kotlin/Dart/Flutter `0.5.0`, API unstable.
+`0.5.0` —— 与 Kotlin/Dart/Flutter `0.5.0` 对齐，API 不稳定。
 
 ## License / 许可证
 

{debug_control_plane-0.4.0 → debug_control_plane-0.5.0}/debug_control_plane/__init__.py

@@ -4,4 +4,4 @@ Reusable across products: device discovery (USB/WiFi/identity) + MCP adapter
 (debug HTTP protocol → MCP tool surface). Extracted from an internal app
 (R019/R020, S2 Python slice, R021-BF004).
 """
-__version__ = "0.4.0"
+__version__ = "0.5.0"

{debug_control_plane-0.4.0 → debug_control_plane-0.5.0}/debug_control_plane/mcp_plane/server.py

@@ -87,6 +87,7 @@ from .bridge_client import (
 )
 from .capability_mirror import CapabilityMirror, CapabilitySchema, ToolSpec
 from .semantic_provider import SemanticProvider
+from .token_provider import FileTokenProvider
 
 # ★ BF008-010 (Contract §0.1 边界 1 收尾 + 方案 X): capability-specific semantic
 # sugar 已迁业务侧(强耦合产品 protocol,属业务知识)。平面 server 零业务依赖
@@ -256,7 +257,7 @@ class McpServer:
         pool: DevicePool,
         *,
         server_name: str = "mcp-debug-bridge",
-        server_version: str = "0.4.0",
+        server_version: str = "0.5.0",
         providers: list[SemanticProvider] | None = None,
         tool_handlers: dict[str, Any] | None = None,
     ) -> None:
@@ -1052,7 +1053,9 @@ def main() -> None:
         format="%(asctime)s %(name)s %(levelname)s %(message)s",
     )
     pool = DevicePool(persist_path=Path.home() / ".debug-control-plane" / "devices.json")
-    client = BridgeClient(pool=pool)
+    client = BridgeClient(
+        pool=pool, token_provider=FileTokenProvider()
+    )
     mirror = CapabilityMirror(client=client)
     server = McpServer(mirror=mirror, client=client, pool=pool)
     server.run_stdio()  # blocks; exits when the AI client closes stdin

debug_control_plane-0.5.0/debug_control_plane/mcp_plane/token_provider.py

@@ -0,0 +1,138 @@
+"""File-backed debug auth token provider (R004-BF001).
+
+FileTokenProvider is the production implementation of
+:class:`debug_control_plane.mcp_plane.bridge_client.DebugAuthTokenProvider`.
+It persists per-device bearer tokens to ``~/.debug-control-plane/tokens.json``
+so tokens survive python process restarts (design R004 §3.2).
+
+Schema (independent from devices.json — no shared structure or imports)::
+
+    {"version": 1, "tokens": {device_id: {"token": ..., "tokenId": ...,
+                                           "expiresAt": ...}}}
+
+Concurrency model: lazy-loaded, single-threaded. This provider assumes it is
+only used from the asyncio event-loop thread (the MCP server's threading
+model). No locking is performed — the design explicitly accepted this
+asyncio-single-thread assumption.
+
+Security: plaintext tokens on the developer machine with 0600 permissions
+(user-approved decision). The 0600 mode is guaranteed by creating the tmp
+file via ``os.open(..., 0o600)`` (bypassing umask, so no 0644 window exists)
+followed by an atomic ``os.replace``.
+
+Corruption policy: a corrupt file or an unknown ``version`` silently falls
+back to an empty store — tokens are regenerable and the server must not
+crash on load.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Mapping
+
+_SCHEMA_VERSION = 1
+_DEFAULT_PATH = Path.home() / ".debug-control-plane" / "tokens.json"
+
+
+def _is_expired(value: str) -> bool:
+    """Return True if ``value`` is a tz-aware ISO timestamp in the past.
+
+    Parse failures and naive timestamps are treated as *not* expired: the
+    phone's 401 is the final arbiter, and a parsing bug must not break the
+    auth chain (design §5). Evaluated at read time; never written back.
+    """
+    try:
+        parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except (ValueError, TypeError):
+        return False
+    if parsed.tzinfo is None:
+        return False
+    return parsed <= datetime.now(timezone.utc)
+
+
+class FileTokenProvider:
+    """File-backed token store implementing the DebugAuthTokenProvider protocol."""
+
+    def __init__(self, path: Path | None = None) -> None:
+        self._path = path or _DEFAULT_PATH
+        self._loaded = False
+        self._tokens: dict[str, dict[str, str]] = {}
+
+    # ------------------------------------------------------------------
+    # Protocol surface
+    # ------------------------------------------------------------------
+
+    def get_token(self, device_id: str) -> str | None:
+        """Return the stored token for ``device_id`` if present and unexpired."""
+        self._ensure_loaded()
+        row = self._tokens.get(device_id)
+        if row is None:
+            return None
+        expires_at = row.get("expiresAt", "")
+        if expires_at and _is_expired(expires_at):
+            return None
+        return row.get("token")
+
+    def save_token(
+        self, device_id: str, token: str, metadata: Mapping[str, Any]
+    ) -> None:
+        """Store ``token`` for ``device_id`` and persist (full file rewrite)."""
+        self._ensure_loaded()
+        row: dict[str, str] = {"token": token}
+        for key, value in metadata.items():
+            row[key] = value if isinstance(value, str) else str(value)
+        self._tokens[device_id] = row
+        self._flush()
+
+    def clear_token(self, device_id: str, reason: str) -> None:
+        """Drop the row for ``device_id`` and persist (rewrite without it)."""
+        self._ensure_loaded()
+        if device_id in self._tokens:
+            del self._tokens[device_id]
+            self._flush()
+
+    # ------------------------------------------------------------------
+    # Internals
+    # ------------------------------------------------------------------
+
+    def _ensure_loaded(self) -> None:
+        if self._loaded:
+            return
+        self._loaded = True
+        try:
+            data = json.loads(self._path.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            return  # missing or corrupt → silent empty fallback
+        if not isinstance(data, dict) or data.get("version") != _SCHEMA_VERSION:
+            return  # unknown schema → silent empty fallback
+        tokens = data.get("tokens")
+        if not isinstance(tokens, dict):
+            return
+        self._tokens = {
+            device_id: row
+            for device_id, row in tokens.items()
+            if isinstance(row, dict)
+        }
+
+    def _flush(self) -> None:
+        """Atomically write the store with 0600 permissions."""
+        payload = json.dumps(
+            {"version": _SCHEMA_VERSION, "tokens": self._tokens},
+            indent=2,
+            ensure_ascii=False,
+        )
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        tmp_path = self._path.with_name(self._path.name + ".tmp")
+        fd = os.open(tmp_path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as f:
+                f.write(payload)
+                f.flush()
+                os.fsync(f.fileno())
+        except BaseException:
+            tmp_path.unlink(missing_ok=True)
+            raise
+        os.replace(tmp_path, self._path)

{debug_control_plane-0.4.0 → debug_control_plane-0.5.0}/debug_control_plane.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: debug-control-plane
-Version: 0.4.0
+Version: 0.5.0
 Summary: Multi-product reusable debug control plane (device discovery + MCP adapter).
 Author: tangxiaolu
 License: MIT
@@ -62,7 +62,7 @@ python/
 ├── README.md                       # this file
 ├── LICENSE                         # MIT
 └── debug_control_plane/
-    ├── __init__.py                 # __version__ = "0.4.0"
+    ├── __init__.py                 # __version__ = "0.5.0"
     ├── device_discovery/           # USB/LAN device discovery + device pool
     │   ├── device_candidates.py
     │   ├── device_pool.py          # identity-keyed pool, TTL expiry / 身份键池，TTL 过期
@@ -92,8 +92,8 @@ Points at `debug_control_plane.mcp_plane.server:main` — a bare server (no busi
 
 ## Version / 版本
 
-`0.4.0` — aligned with Kotlin/Dart/Flutter `0.4.0`, API unstable.
-`0.4.0` —— 与 Kotlin/Dart/Flutter `0.4.0` 对齐，API 不稳定。
+`0.5.0` — aligned with Kotlin/Dart/Flutter `0.5.0`, API unstable.
+`0.5.0` —— 与 Kotlin/Dart/Flutter `0.5.0` 对齐，API 不稳定。
 
 ## License / 许可证
 

{debug_control_plane-0.4.0 → debug_control_plane-0.5.0}/debug_control_plane.egg-info/SOURCES.txt

@@ -24,6 +24,7 @@ debug_control_plane/mcp_plane/bridge_client.py
 debug_control_plane/mcp_plane/capability_mirror.py
 debug_control_plane/mcp_plane/semantic_provider.py
 debug_control_plane/mcp_plane/server.py
+debug_control_plane/mcp_plane/token_provider.py
 tests/test_acceptance_flutter_app_auth.py
 tests/test_bridge_client.py
 tests/test_capability_mirror.py
@@ -38,4 +39,5 @@ tests/test_discovery_vpn_immune.py
 tests/test_e2e_mock.py
 tests/test_endpoint.py
 tests/test_import_sanity.py
-tests/test_server.py
+tests/test_server.py
+tests/test_token_provider.py

{debug_control_plane-0.4.0 → debug_control_plane-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "debug-control-plane"
-version = "0.4.0"
+version = "0.5.0"
 description = "Multi-product reusable debug control plane (device discovery + MCP adapter)."
 readme = "README.md"
 requires-python = ">=3.10"

{debug_control_plane-0.4.0 → debug_control_plane-0.5.0}/tests/test_server.py

@@ -1313,7 +1313,7 @@ class TestMakeApp:
         srv = assembled[0]
         app = srv._make_app()  # noqa: SLF001
         assert app.name == "mcp-debug-bridge"
-        assert app.version == "0.4.0"
+        assert app.version == "0.5.0"
 
     def test_make_app_registers_stub_provider(self, assembled):
         """★ BF008-010 (A 类): assembled fixture 注入的 _StubProvider 已注册到

debug_control_plane-0.5.0/tests/test_token_provider.py

@@ -0,0 +1,168 @@
+"""Unit tests for FileTokenProvider (R004-BF001).
+
+Covers the 7 BF001-T scenarios from test §2:
+  1. roundtrip-cross-instance: save → new instance get hits disk.
+  2. 0600-permission: file mode == 0o600 after save.
+  3. expired-past-future-Z-invalid: expiresAt four-state judgement.
+  4. clear-deletes-row: clear_token rewrites file without the row.
+  5. corrupt-fallback: invalid JSON → silent empty fallback.
+  6. metadata-merge: metadata str values merged into the row.
+  7. version-mismatch: version != 1 → silent empty fallback.
+
+All tests use tmp_path — the real ~/.debug-control-plane/ is never touched.
+"""
+
+from __future__ import annotations
+
+import json
+import stat
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+from debug_control_plane.mcp_plane.token_provider import FileTokenProvider
+
+
+def _provider(tmp_path: Path) -> FileTokenProvider:
+    return FileTokenProvider(path=tmp_path / "tokens.json")
+
+
+def _write_raw(tmp_path: Path, payload: dict) -> Path:
+    p = tmp_path / "tokens.json"
+    p.write_text(json.dumps(payload), encoding="utf-8")
+    return p
+
+
+# ---------------------------------------------------------------------------
+# 1. roundtrip-cross-instance
+# ---------------------------------------------------------------------------
+
+def test_roundtrip_cross_instance(tmp_path: Path) -> None:
+    p1 = _provider(tmp_path)
+    p1.save_token(
+        "device-1",
+        "dcp_tok_1",
+        {"tokenId": "tid-1", "expiresAt": "2099-01-01T00:00:00+00:00"},
+    )
+    # A new instance must see the token (persistence, not memory).
+    p2 = _provider(tmp_path)
+    assert p2.get_token("device-1") == "dcp_tok_1"
+
+
+# ---------------------------------------------------------------------------
+# 2. 0600-permission
+# ---------------------------------------------------------------------------
+
+def test_file_mode_0600(tmp_path: Path) -> None:
+    provider = _provider(tmp_path)
+    provider.save_token("device-1", "dcp_tok_1", {"tokenId": "tid-1"})
+    mode = stat.S_IMODE(provider._path.stat().st_mode)  # noqa: SLF001
+    assert mode == 0o600
+
+
+# ---------------------------------------------------------------------------
+# 3. expired four states
+# ---------------------------------------------------------------------------
+
+def test_expired_past_returns_none(tmp_path: Path) -> None:
+    past = (datetime.now(timezone.utc) - timedelta(hours=1)).isoformat()
+    provider = _provider(tmp_path)
+    provider.save_token("d", "t", {"expiresAt": past})
+    assert provider.get_token("d") is None
+
+
+def test_not_expired_future(tmp_path: Path) -> None:
+    future = (datetime.now(timezone.utc) + timedelta(days=6)).isoformat()
+    provider = _provider(tmp_path)
+    provider.save_token("d", "t", {"expiresAt": future})
+    assert provider.get_token("d") == "t"
+
+
+def test_not_expired_z_suffix(tmp_path: Path) -> None:
+    future = (
+        datetime.now(timezone.utc) + timedelta(days=6)
+    ).strftime("%Y-%m-%dT%H:%M:%SZ")
+    provider = _provider(tmp_path)
+    provider.save_token("d", "t", {"expiresAt": future})
+    assert provider.get_token("d") == "t"
+
+
+def test_invalid_expiresat_treated_as_not_expired(tmp_path: Path) -> None:
+    provider = _provider(tmp_path)
+    provider.save_token("d", "t", {"expiresAt": "not-a-date"})
+    assert provider.get_token("d") == "t"
+
+
+def test_naive_expiresat_treated_as_not_expired(tmp_path: Path) -> None:
+    provider = _provider(tmp_path)
+    provider.save_token("d", "t", {"expiresAt": "2099-01-01T00:00:00"})
+    assert provider.get_token("d") == "t"
+
+
+# ---------------------------------------------------------------------------
+# 4. clear-deletes-row
+# ---------------------------------------------------------------------------
+
+def test_clear_deletes_row_on_disk(tmp_path: Path) -> None:
+    provider = _provider(tmp_path)
+    provider.save_token("d1", "t1", {"tokenId": "tid-1"})
+    provider.save_token("d2", "t2", {"tokenId": "tid-2"})
+    provider.clear_token("d1", reason="token_expired")
+    assert provider.get_token("d1") is None
+    assert provider.get_token("d2") == "t2"
+    # A fresh instance sees the same on-disk state.
+    assert _provider(tmp_path).get_token("d1") is None
+
+
+def test_clear_missing_device_is_noop(tmp_path: Path) -> None:
+    provider = _provider(tmp_path)
+    provider.clear_token("ghost", reason="token_expired")  # must not raise
+    assert provider.get_token("ghost") is None
+
+
+# ---------------------------------------------------------------------------
+# 5. corrupt-fallback
+# ---------------------------------------------------------------------------
+
+def test_corrupt_file_silent_fallback(tmp_path: Path) -> None:
+    p = tmp_path / "tokens.json"
+    p.write_text("{not valid json", encoding="utf-8")
+    provider = FileTokenProvider(path=p)
+    assert provider.get_token("d") is None  # no raise, empty
+    # After a save the file becomes valid again (self-heal).
+    provider.save_token("d", "t", {"tokenId": "tid"})
+    assert json.loads(p.read_text(encoding="utf-8"))["version"] == 1
+
+
+# ---------------------------------------------------------------------------
+# 6. metadata-merge
+# ---------------------------------------------------------------------------
+
+def test_metadata_merged_into_row(tmp_path: Path) -> None:
+    provider = _provider(tmp_path)
+    provider.save_token("d", "t", {"tokenId": "tid-1", "expiresAt": "x", "count": 3})
+    row = json.loads((tmp_path / "tokens.json").read_text(encoding="utf-8"))[
+        "tokens"
+    ]["d"]
+    assert row["token"] == "t"
+    assert row["tokenId"] == "tid-1"
+    assert row["expiresAt"] == "x"
+    # Non-str metadata values are stringified (schema keeps str values only).
+    assert isinstance(row["count"], str)
+
+
+# ---------------------------------------------------------------------------
+# 7. version-mismatch
+# ---------------------------------------------------------------------------
+
+def test_version_mismatch_fallback(tmp_path: Path) -> None:
+    _write_raw(
+        tmp_path,
+        {"version": 2, "tokens": {"d": {"token": "t", "tokenId": "tid"}}},
+    )
+    provider = _provider(tmp_path)
+    assert provider.get_token("d") is None
+    # Save under v1 schema after the fallback.
+    provider.save_token("d", "t2", {})
+    data = json.loads((tmp_path / "tokens.json").read_text(encoding="utf-8"))
+    assert data["version"] == 1
+    assert data["tokens"]["d"]["token"] == "t2"