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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: debug-control-plane
-Version: 0.4.0
+Version: 0.5.1
 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.1"
     ├── 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.1` — aligned with Kotlin/Dart/Flutter `0.5.1`, API unstable.
+`0.5.1` —— 与 Kotlin/Dart/Flutter `0.5.1` 对齐，API 不稳定。
 
 ## License / 许可证
 

{debug_control_plane-0.4.0 → debug_control_plane-0.5.1}/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.1"
     ├── 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.1` — aligned with Kotlin/Dart/Flutter `0.5.1`, API unstable.
+`0.5.1` —— 与 Kotlin/Dart/Flutter `0.5.1` 对齐，API 不稳定。
 
 ## License / 许可证
 

{debug_control_plane-0.4.0 → debug_control_plane-0.5.1}/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.1"

{debug_control_plane-0.4.0 → debug_control_plane-0.5.1}/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.1",
         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.1/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.1}/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.1
 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.1"
     ├── 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.1` — aligned with Kotlin/Dart/Flutter `0.5.1`, API unstable.
+`0.5.1` —— 与 Kotlin/Dart/Flutter `0.5.1` 对齐，API 不稳定。
 
 ## License / 许可证
 

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

@@ -24,10 +24,12 @@ 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
 tests/test_cross_lang_kotlin_plane.py
+tests/test_dart_plane_persistence.py
 tests/test_device_candidates.py
 tests/test_device_pool.py
 tests/test_discovery_cross_identify.py
@@ -38,4 +40,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.1}/pyproject.toml

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

debug_control_plane-0.5.1/tests/test_dart_plane_persistence.py

@@ -0,0 +1,217 @@
+"""R005-BF002 — dart plane token 持久化验收入口（pytest 侧子集）。
+
+消费「已在运行的 example app Dart plane endpoint」（R002-BF005 双通道：
+pytest ``--endpoint`` option 或 env ``ACCEPTANCE_ENDPOINT``；由
+``.dev-flow/R005/test-overrides/R005-BF002/run-integration.sh`` 驱动或
+操作者手动启动）。两者皆缺 → 每用例 ``pytest.skip(setup_required)``，
+绝不误报 pass。session 级健康探测 GET /hello 不可达 → 全部
+skip(setup_required: endpoint unreachable)。
+
+覆盖范围（明示）：
+  - 本文件只覆盖 I1/I4-TTL/I5 的 wire 子集 + I1 的 python 侧落盘断言。
+  - I2（冷重启）/ I3（损坏自愈）/ I4 的「篡改 app 沙箱文件 + simctl
+    terminate/relaunch」部分**仅在驱动脚本执行**（需要 simctl udid/bundle
+    与 driver 重启能力，pytest 会话内不掌握这些环境句柄），对应断言在
+    ``.dev-flow/R005/test-overrides/R005-BF002/ios-simulator-persistence.py``
+    （I1-I5 全量）。
+  - 全量执行入口：``bash .dev-flow/R005/test-overrides/R005-BF002/run-integration.sh``。
+
+Refs:
+  - tasks: .dev-flow/R005/dart-plane-token-persistence-tasks.md (R005-BF002)
+  - pattern: python/tests/test_acceptance_flutter_app_auth.py (R002-BF005)
+  - wire source: flutter_debug_control_plane/example/lib/src/acceptance_plane.dart
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+import tempfile
+import time
+import urllib.error
+import urllib.request
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+_ENDPOINT_ENV = "ACCEPTANCE_ENDPOINT"
+_REQUEST_TIMEOUT = 5.0
+_APPROVE_WAIT_TIMEOUT = 30.0
+_POLL_INTERVAL = 0.5
+
+
+def _get_pytest_endpoint(request: pytest.FixtureRequest) -> str | None:
+    """--endpoint option 优先，其次 ACCEPTANCE_ENDPOINT，皆缺返回 None。"""
+    option_value = request.config.getoption("--endpoint")
+    return option_value or os.environ.get(_ENDPOINT_ENV) or None
+
+
+def _http_json(endpoint: str, method: str, path: str,
+               body: dict[str, Any] | None = None, bearer: str | None = None,
+               timeout: float = _REQUEST_TIMEOUT) -> tuple[int, Any]:
+    url = endpoint.rstrip("/") + path
+    data = json.dumps(body or {}).encode()
+    req = urllib.request.Request(url, data=data, method=method)
+    req.add_header("Content-Type", "application/json")
+    if bearer:
+        req.add_header("Authorization", f"Bearer {bearer}")
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as r:
+            raw = r.read()
+            return r.status, (json.loads(raw) if raw else {})
+    except urllib.error.HTTPError as e:
+        raw = e.read()
+        try:
+            return e.code, (json.loads(raw) if raw else {})
+        except ValueError:
+            return e.code, raw.decode(errors="replace")
+
+
+class _EndpointUnreachable(Exception):
+    def __init__(self, reason: str) -> None:
+        super().__init__(reason)
+        self.reason = reason
+
+
+@pytest.fixture(scope="session")
+def plane_endpoint(request: pytest.FixtureRequest) -> str:
+    """endpoint 解析 + session 级健康探测；缺/不可达 → skip(setup_required)。
+
+    与 test_acceptance_flutter_app_auth.py 同模式：session fixture 内直接
+    pytest.skip，依赖用例呈现 skip 而非 error。
+    """
+    endpoint = _get_pytest_endpoint(request)
+    if not endpoint:
+        pytest.skip("setup_required: no endpoint (use --endpoint or ACCEPTANCE_ENDPOINT)")
+    try:
+        st, _ = _http_json(endpoint, "GET", "/hello", timeout=3.0)
+        if st != 200:
+            pytest.skip(f"setup_required: endpoint unreachable (/hello -> {st})")
+    except Exception as e:  # noqa: BLE001
+        pytest.skip(f"setup_required: endpoint unreachable ({type(e).__name__}: {e})")
+    return endpoint
+
+
+@pytest.fixture
+def endpoint_or_skip(plane_endpoint: str) -> str:
+    """session 探测通过的 endpoint（失败已在 session fixture skip）。"""
+    return plane_endpoint
+
+
+def _wait_approved(endpoint: str, rid: str, nonce: str,
+                   timeout: float = _APPROVE_WAIT_TIMEOUT) -> None:
+    """轮询等 driver（按 clientLabel 非 deny*/hold* 自动 approve）。"""
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        st, body = _http_json(endpoint, "POST", "/auth/status",
+                              {"requestId": rid, "clientNonce": nonce})
+        if st == 200 and isinstance(body, dict) and body.get("status") == "approved":
+            return
+        if st == 403:
+            raise AssertionError(f"denied: {body}")
+        time.sleep(_POLL_INTERVAL)
+    raise AssertionError(f"approve timeout for {rid}")
+
+
+def _auth_chain(endpoint: str, store: Path,
+                label: str) -> tuple[str, dict[str, Any]]:
+    """授权链（标准库 urllib 版，与 R002 模式一致）。"""
+    nonce = f"r005-py-{label}-{uuid.uuid4().hex[:8]}"
+    st, body = _http_json(endpoint, "POST", "/auth/request",
+                          {"clientLabel": f"r005-py-{label}", "clientNonce": nonce})
+    assert st in (200, 202), f"/auth/request: {st} {body!r:.60}"
+    rid = body["requestId"]
+    _wait_approved(endpoint, rid, nonce)
+    st, body = _http_json(endpoint, "POST", "/auth/claim",
+                          {"requestId": rid, "clientNonce": nonce})
+    assert st == 200 and isinstance(body.get("token"), str), \
+        f"/auth/claim: {st} {body!r:.60}"
+    # python 侧 FileTokenProvider 落盘（等价 R004 S1 语义）
+    row = {"token": body["token"], "tokenId": body.get("tokenId"),
+           "expiresAt": body.get("expiresAt"), "obtainedAt": datetime.now(timezone.utc).isoformat()}
+    store.parent.mkdir(parents=True, exist_ok=True)
+    store.write_text(json.dumps({"version": 1, "tokens": {"ios-sim": row}},
+                                indent=2), encoding="utf-8")
+    os.chmod(store, 0o600)
+    return body["token"], body
+
+
+@pytest.fixture
+def claimed(endpoint_or_skip: str, tmp_path: Path) -> tuple[str, dict[str, Any]]:
+    """session 内每用例独立授权链（新 nonce 新 token）。"""
+    return _auth_chain(endpoint_or_skip, tmp_path / "tokens.json", "case")
+
+
+# ---------------------------------------------------------------------------
+# 用例（I1/I4-TTL/I5 子集；I2/I3 仅驱动脚本执行，见模块 docstring）
+# ---------------------------------------------------------------------------
+
+def test_i1_first_auth_python_side(claimed: tuple[str, dict[str, Any]],
+                                   tmp_path: Path) -> None:
+    """I1 子集（python 侧）：claim 200 + token 落盘 0600 + expiresAt 在场。
+
+    I1 的 app 沙箱断言（Documents/debug_control_plane/debug_auth_tokens.json
+    存在/version==1/字节无明文）仅在驱动脚本执行（需 simctl 沙箱句柄）。
+    """
+    token, claim = claimed
+    assert token, "claim token 空"
+    store = tmp_path / "tokens.json"
+    data = json.loads(store.read_text(encoding="utf-8"))
+    row = data["tokens"]["ios-sim"]
+    assert row["token"] == token, "落盘 token 与 claim 不一致"
+    mode = stat.S_IMODE(store.stat().st_mode)
+    assert mode == 0o600, f"权限 {oct(mode)} != 0600"
+    assert row["tokenId"] and row["expiresAt"], f"metadata 未并入: {row!r}"
+
+
+def test_i4_ttl_window(claimed: tuple[str, dict[str, Any]]) -> None:
+    """I4 子集（TTL 窗口）：claim expiresAt - now ∈ [604790, 604810]s。
+
+    I4 的「篡改 app 沙箱 + 冷重启 → 401」部分仅在驱动脚本执行。
+    """
+    token, claim = claimed
+    exp = datetime.fromisoformat(claim["expiresAt"].replace("Z", "+00:00"))
+    delta = (exp - datetime.now(timezone.utc)).total_seconds()
+    assert 604790 <= delta <= 604810, f"expiresAt-now={delta:.0f}s 超出窗口"
+
+
+def test_i5_no_token_401(endpoint_or_skip: str) -> None:
+    """I5：无 Authorization → 敏感路由 401。"""
+    st, _ = _http_json(endpoint_or_skip, "POST", "/debug/secure-action",
+                       body={"via": "r005-py"})
+    assert st == 401, f"no-token: {st}"
+
+
+def test_i5_forged_401_invalid_token(endpoint_or_skip: str) -> None:
+    """I5：伪造 Bearer → 401 invalid_token。"""
+    st, body = _http_json(endpoint_or_skip, "POST", "/debug/secure-action",
+                          body={"via": "r005-py"}, bearer="tok-forged-r005")
+    assert st == 401 and body.get("code") == "invalid_token", \
+        f"forged: {st} {body!r:.60}"
+
+
+def test_i5_pending_claim_no_token_leak(endpoint_or_skip: str) -> None:
+    """I5：hold* 前缀保持 pending → claim 200 status=pending 且无 token。"""
+    nonce = f"r005-py-hold-{uuid.uuid4().hex[:8]}"
+    st, body = _http_json(endpoint_or_skip, "POST", "/auth/request",
+                          {"clientLabel": "hold-r005-py", "clientNonce": nonce})
+    rid = body.get("requestId")
+    assert st in (200, 202) and rid, f"/auth/request: {st} {body!r:.60}"
+    st, body = _http_json(endpoint_or_skip, "POST", "/auth/claim",
+                          {"requestId": rid, "clientNonce": nonce})
+    assert st == 200 and body.get("status") == "pending" and "token" not in body, \
+        f"pending claim: {st} {body!r:.60}"
+
+
+def test_i5_bearer_multi_capability(endpoint_or_skip: str,
+                                    claimed: tuple[str, dict[str, Any]]) -> None:
+    """I5：真 token Bearer 走 /debug/echo（capability 语义回归）。"""
+    token, _ = claimed
+    st, body = _http_json(endpoint_or_skip, "POST", "/debug/echo",
+                          body={"r005": "multi"}, bearer=token)
+    assert st == 200 and body.get("capability") == "debug.echo", \
+        f"echo: {st} {body!r:.60}"

{debug_control_plane-0.4.0 → debug_control_plane-0.5.1}/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.1"
 
     def test_make_app_registers_stub_provider(self, assembled):
         """★ BF008-010 (A 类): assembled fixture 注入的 _StubProvider 已注册到

debug_control_plane-0.5.1/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"