debug-control-plane 0.1.1__tar.gz → 0.3.0__tar.gz

{debug_control_plane-0.1.1 → debug_control_plane-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: debug-control-plane
-Version: 0.1.1
+Version: 0.3.0
 Summary: Multi-product reusable debug control plane (device discovery + MCP adapter).
 Author: tangxiaolu
 License: MIT
@@ -14,6 +14,7 @@ Provides-Extra: test
 Requires-Dist: pytest>=7; extra == "test"
 Requires-Dist: pytest-cov>=4; extra == "test"
 Requires-Dist: ruff>=0.4; extra == "test"
+Requires-Dist: pytest-asyncio>=0.23; extra == "test"
 Dynamic: license-file
 
 # debug-control-plane (Python)
@@ -61,7 +62,7 @@ python/
 ├── README.md                       # this file
 ├── LICENSE                         # MIT
 └── debug_control_plane/
-    ├── __init__.py                 # __version__ = "0.1.0"
+    ├── __init__.py                 # __version__ = "0.3.0"
     ├── device_discovery/           # USB/LAN device discovery + device pool
     │   ├── device_candidates.py
     │   ├── device_pool.py          # identity-keyed pool, TTL expiry / 身份键池，TTL 过期
@@ -91,7 +92,8 @@ Points at `debug_control_plane.mcp_plane.server:main` — a bare server (no busi
 
 ## Version / 版本
 
-`0.1.0` — initial release, API unstable. 首发，API 不稳定。
+`0.3.0` — aligned with Kotlin/Dart/Flutter `0.3.0`, API unstable.
+`0.3.0` —— 与 Kotlin/Dart/Flutter `0.3.0` 对齐，API 不稳定。
 
 ## License / 许可证
 

{debug_control_plane-0.1.1 → debug_control_plane-0.3.0}/README.md

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

{debug_control_plane-0.1.1 → debug_control_plane-0.3.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.1.0"
+__version__ = "0.3.0"

{debug_control_plane-0.1.1 → debug_control_plane-0.3.0}/debug_control_plane/mcp_plane/bridge_client.py

@@ -54,8 +54,8 @@ Refs:
 
 from __future__ import annotations
 
-from collections.abc import Iterator
-from typing import TYPE_CHECKING, Any
+from collections.abc import Iterator, Mapping
+from typing import TYPE_CHECKING, Any, Protocol
 
 import httpx
 
@@ -138,6 +138,30 @@ class DeviceHttpError(BridgeError):
         super().__init__(f"{prefix}{detail}")
 
 
+class DeviceAuthError(DeviceHttpError):
+    """The phone returned a stable debug auth failure code."""
+
+    def __init__(self, status_code: int, body: Any, code: str, message: str = "") -> None:
+        self.code = code
+        super().__init__(status_code, body, message or f" auth_code={code}")
+
+
+class DebugAuthTokenProvider(Protocol):
+    """Per-device debug auth token provider.
+
+    Implementations own storage. DevicePool remains identity-only and must not
+    be used to persist bearer tokens.
+    """
+
+    def get_token(self, device_id: str) -> str | None: ...
+
+    def save_token(
+        self, device_id: str, token: str, metadata: Mapping[str, Any]
+    ) -> None: ...
+
+    def clear_token(self, device_id: str, reason: str) -> None: ...
+
+
 # ---------------------------------------------------------------------------
 # Service
 # ---------------------------------------------------------------------------
@@ -181,6 +205,7 @@ class BridgeClient:
         client: httpx.Client | None = None,
         request_timeout: float = DEFAULT_REQUEST_TIMEOUT,
         stream_timeout: float = DEFAULT_STREAM_TIMEOUT,
+        token_provider: DebugAuthTokenProvider | None = None,
     ) -> None:
         self._pool = pool
         self._port = port
@@ -192,6 +217,7 @@ class BridgeClient:
             self._owns_client = True
         self._request_timeout = request_timeout
         self._stream_timeout = stream_timeout
+        self._token_provider = token_provider
 
     # ------------------------------------------------------------------
     # Lifecycle
@@ -282,17 +308,18 @@ class BridgeClient:
         """
         host = self.resolve(device_id)
         url = self._build_url(host, path)
+        headers = self._auth_headers(device_id)
         try:
             if isinstance(body, (dict, list)):
-                resp = self._client.request(method, url, json=body)
+                resp = self._client.request(method, url, json=body, headers=headers)
             else:
-                resp = self._client.request(method, url, content=body)
+                resp = self._client.request(method, url, content=body, headers=headers)
         except httpx.HTTPError as exc:
             # Connect refused / DNS / timeout / etc — surface as transport
             # failure so the caller catches a single exception type.
             raise DeviceHttpError(0, None, f"transport: {exc!s}") from exc
         if resp.status_code >= 400:
-            raise DeviceHttpError(resp.status_code, _safe_body(resp))
+            raise self._http_error(device_id, resp)
         return _safe_body(resp)
 
     def read(self, device_id: str, path: list[str]) -> Any:
@@ -317,12 +344,13 @@ class BridgeClient:
         """
         host = self.resolve(device_id)
         url = self._build_url(host, ["hello"])
+        headers = self._auth_headers(device_id)
         try:
-            resp = self._client.get(url)
+            resp = self._client.get(url, headers=headers)
         except httpx.HTTPError as exc:
             raise DeviceHttpError(0, None, f"transport: {exc!s}") from exc
         if resp.status_code != 200:
-            raise DeviceHttpError(resp.status_code, _safe_body(resp))
+            raise self._http_error(device_id, resp)
         data = resp.json()
         if not isinstance(data, dict):
             raise DeviceHttpError(
@@ -370,13 +398,16 @@ class BridgeClient:
         """
         host = self.resolve(device_id)
         url = self._build_url(host, ["events"])
+        headers = self._auth_headers(device_id)
         type_set = set(event_types) if event_types else None
         try:
-            with self._client.stream("GET", url, timeout=self._stream_timeout) as resp:
+            with self._client.stream(
+                "GET", url, headers=headers, timeout=self._stream_timeout
+            ) as resp:
                 if resp.status_code >= 400:
                     # Read the body so the caller sees the error payload.
                     resp.read()
-                    raise DeviceHttpError(resp.status_code, _safe_body(resp))
+                    raise self._http_error(device_id, resp)
                 for raw_data, _event_field in _iter_sse(resp):
                     try:
                         payload = _parse_json_object(raw_data)
@@ -392,10 +423,75 @@ class BridgeClient:
         except httpx.HTTPError as exc:
             raise DeviceHttpError(0, None, f"transport: {exc!s}") from exc
 
+    def auth_request(
+        self,
+        device_id: str,
+        client_nonce: str,
+        *,
+        client_label: str | None = None,
+        requested_method: str | None = None,
+        requested_path: str | None = None,
+    ) -> Any:
+        """Create a pending App-side authorization request."""
+        body: dict[str, Any] = {"clientNonce": client_nonce}
+        if client_label is not None:
+            body["clientLabel"] = client_label
+        if requested_method is not None:
+            body["requestedMethod"] = requested_method
+        if requested_path is not None:
+            body["requestedPath"] = requested_path
+        return self.invoke(device_id, "POST", ["auth", "request"], body)
+
+    def auth_status(self, device_id: str, request_id: str, client_nonce: str) -> Any:
+        """Poll App-side authorization status."""
+        return self.invoke(
+            device_id,
+            "POST",
+            ["auth", "status"],
+            {"requestId": request_id, "clientNonce": client_nonce},
+        )
+
+    def auth_claim(self, device_id: str, request_id: str, client_nonce: str) -> Any:
+        """Claim an approved App-side authorization token and save it if present."""
+        body = self.invoke(
+            device_id,
+            "POST",
+            ["auth", "claim"],
+            {"requestId": request_id, "clientNonce": client_nonce},
+        )
+        if isinstance(body, dict):
+            token = body.get("token")
+            if isinstance(token, str) and self._token_provider is not None:
+                metadata = {
+                    key: body[key]
+                    for key in ("tokenId", "expiresAt")
+                    if key in body
+                }
+                self._token_provider.save_token(device_id, token, metadata)
+        return body
+
     # ------------------------------------------------------------------
     # Internal helpers
     # ------------------------------------------------------------------
 
+    def _auth_headers(self, device_id: str) -> dict[str, str]:
+        provider = self._token_provider
+        if provider is None:
+            return {}
+        token = provider.get_token(device_id)
+        if not token:
+            return {}
+        return {"Authorization": f"Bearer {token}"}
+
+    def _http_error(self, device_id: str, resp: httpx.Response) -> DeviceHttpError:
+        body = _safe_body(resp)
+        code = _auth_error_code(resp.status_code, body)
+        if code is None:
+            return DeviceHttpError(resp.status_code, body)
+        if code in _CLEAR_TOKEN_AUTH_CODES and self._token_provider is not None:
+            self._token_provider.clear_token(device_id, reason=code)
+        return DeviceAuthError(resp.status_code, body, code=code)
+
     def _build_url(self, host: str, path: list[str]) -> str:
         """Assemble ``http://{host}:{port}/{seg1}/{seg2}...``.
 
@@ -512,12 +608,43 @@ def _parse_json_object(raw: str) -> dict[str, Any]:
     return parsed
 
 
+def _auth_error_code(status_code: int, body: Any) -> str | None:
+    if status_code not in (401, 403) or not isinstance(body, dict):
+        return None
+    code = body.get("code")
+    if isinstance(code, str) and code in _AUTH_ERROR_CODES:
+        return code
+    return None
+
+
+_AUTH_ERROR_CODES = frozenset(
+    {
+        "authorization_required",
+        "invalid_token",
+        "token_expired",
+        "token_revoked",
+        "authorization_denied",
+        "forbidden",
+    }
+)
+
+_CLEAR_TOKEN_AUTH_CODES = frozenset(
+    {
+        "invalid_token",
+        "token_expired",
+        "token_revoked",
+    }
+)
+
+
 __all__ = [
     "DEFAULT_PORT",
     "DEFAULT_REQUEST_TIMEOUT",
     "DEFAULT_STREAM_TIMEOUT",
     "BridgeClient",
     "BridgeError",
+    "DebugAuthTokenProvider",
+    "DeviceAuthError",
     "DeviceHttpError",
     "DeviceStale",
     # AD-B9: DeviceUnreachable 已下沉 device_discovery.protocol,

{debug_control_plane-0.1.1 → debug_control_plane-0.3.0}/debug_control_plane/mcp_plane/capability_mirror.py

@@ -78,6 +78,7 @@ from debug_control_plane.device_discovery.protocol import JsonMap, NetworkTarget
 from .bridge_client import (
     BridgeClient,
     BridgeError,
+    DeviceAuthError,
     DeviceHttpError,
     DeviceStale,
     DeviceUnreachable,
@@ -397,6 +398,12 @@ class CapabilityMirror:
         # (design §4.1 note: capability schema is CapabilityMirror's runtime
         # mirror, NOT a DeviceRecord field).
         self._cache: dict[str, list[CapabilitySchema]] = {}
+        # R001-BB001: per-device last auth error (DeviceAuthError). Auth
+        # failure ≠ offline — the schema cache is preserved and the signal is
+        # queryable via auth_error() instead of silently degrading. Cleared on
+        # the next successful refresh. GIL-guarded dict ops suffice (contract
+        # risk note).
+        self._auth_errors: dict[str, DeviceAuthError] = {}
 
     # ------------------------------------------------------------------
     # Provider registry (BF010 registration hook)
@@ -430,19 +437,31 @@ class CapabilityMirror:
             True iff the parsed schema differs from the cached snapshot
             (including "no cache → cache populated", which IS a change).
             False if /hello failed (cache cleared) or the schema is identical.
+            Auth errors (R001-BB001): cache is PRESERVED and False returned —
+            the phone is reachable, just unauthorized; see :meth:`auth_error`.
         """
         try:
             target = self._client.hello(device_id)
+        except DeviceAuthError as exc:
+            # R001-BB001: auth error ≠ offline. Preserve the schema cache
+            # (capabilities remain valid once authorized), record the auth
+            # failure for auth_error() queries, return False (no spurious
+            # list_changed). refresh stays poll-safe (never raises).
+            self._auth_errors[device_id] = exc
+            return False
         except (DeviceUnreachable, DeviceStale, DeviceHttpError, BridgeError):
-            # Any /hello failure → degrade. Clear cache so build_tools falls
-            # to static-only and a later successful refresh re-signals the
-            # transition back. We do NOT report a change here: list_changed
-            # signals "the manifest grew/shrank", and going from "had tools"
-            # to "static only" is a real change — but only if we actually had
-            # a non-empty manifest before. Reporting False on a cache→empty
-            # transition would be a lie, so we surface it honestly.
+            # Any non-auth /hello failure → degrade. Clear cache (and any
+            # stale auth state — an unreachable phone has no auth verdict)
+            # so build_tools falls to static-only and a later successful
+            # refresh re-signals the transition back. We do NOT report a
+            # change here: list_changed signals "the manifest grew/shrank",
+            # and going from "had tools" to "static only" is a real change —
+            # but only if we actually had a non-empty manifest before.
+            # Reporting False on a cache→empty transition would be a lie, so
+            # we surface it honestly.
             had_cache = device_id in self._cache
             self._cache.pop(device_id, None)
+            self._auth_errors.pop(device_id, None)
             # Transition from "had dynamic tools" to "static only" IS a change
             # the AI client needs to know about (its cached tools are stale).
             return had_cache
@@ -452,8 +471,20 @@ class CapabilityMirror:
         changed = old_schemas != new_schemas
         if changed:
             self._cache[device_id] = new_schemas
+        # Successful /hello means the device is authorized again.
+        self._auth_errors.pop(device_id, None)
         return changed
 
+    def auth_error(self, device_id: str) -> DeviceAuthError | None:
+        """Return the last :class:`DeviceAuthError` seen for ``device_id``.
+
+        R001-BB001: lets callers (h_list_capabilities) distinguish "auth
+        failed" from "offline degrade" without refresh raising. ``None`` when
+        the device is healthy or the last failure was non-auth (offline /
+        stale / HTTP). Cleared by the next successful refresh.
+        """
+        return self._auth_errors.get(device_id)
+
     # ------------------------------------------------------------------
     # Cache access (no I/O)
     # ------------------------------------------------------------------

{debug_control_plane-0.1.1 → debug_control_plane-0.3.0}/debug_control_plane/mcp_plane/server.py

@@ -80,6 +80,7 @@ from debug_control_plane.device_discovery.discovery.vpn_immune import VpnImmune
 from .bridge_client import (
     BridgeClient,
     BridgeError,
+    DeviceAuthError,
     DeviceHttpError,
     DeviceStale,
     DeviceUnreachable,
@@ -141,6 +142,34 @@ def _tool_spec_to_mcp(spec: ToolSpec) -> types.Tool:
 # ---------------------------------------------------------------------------
 
 
+# R001-BB001 (BB001.1/BB001.3): auth errors carry a stable ``code``
+# (PROTOCOL.md §2.4). Map each code to the user's next step — never a bare
+# "token validation failed". Token clearing already happened in BridgeClient
+# (BF009); the MCP layer only surfaces the hint, and the message must never
+# contain a plaintext token.
+_TOKEN_CLEARED_ACTION = (
+    " — the locally cached token was cleared; re-authorize on the App "
+    "(open the App and grant access again), then retry"
+)
+_DENIED_ACTION = (
+    " — the App denied or does not grant this access; do not retry "
+    "automatically (check the App's permission settings or ask the "
+    "user to allow this client)"
+)
+_AUTH_CODE_ACTIONS: dict[str, str] = {
+    "authorization_required": (
+        " — open the App on the device and approve the authorization request "
+        "(this client is not yet authorized; no token was sent or accepted)"
+    ),
+    # Token-family codes share one remediation.
+    **dict.fromkeys(
+        ("token_expired", "token_revoked", "invalid_token"), _TOKEN_CLEARED_ACTION
+    ),
+    # authorization_denied / forbidden: no automatic retry.
+    **dict.fromkeys(("authorization_denied", "forbidden"), _DENIED_ACTION),
+}
+
+
 def _bridge_error_to_mcp(exc: BridgeError | DeviceUnreachable) -> McpError:
     """Translate a :class:`BridgeError` into an MCP ``isError`` result.
 
@@ -158,7 +187,17 @@ def _bridge_error_to_mcp(exc: BridgeError | DeviceUnreachable) -> McpError:
     so AI clients that branch on the code treat it as a retryable user error
     rather than a fatal server fault.
     """
-    if isinstance(exc, DeviceHttpError):
+    if isinstance(exc, DeviceAuthError):
+        # MUST precede the DeviceHttpError branch: DeviceAuthError is a
+        # DeviceHttpError subclass, so isinstance order decides which branch
+        # fires. Unknown codes fall back to the deny-style hint (safe default:
+        # no automatic retry).
+        action = _AUTH_CODE_ACTIONS.get(exc.code, _DENIED_ACTION)
+        message = (
+            f"device authorization error: auth_code={exc.code} "
+            f"status={exc.status_code}{action}"
+        )
+    elif isinstance(exc, DeviceHttpError):
         hint = ""
         # 409 real_controller_active: the phone's contract says the real pad
         # wins; surface that as an actionable hint (analysis fault injection).
@@ -217,7 +256,7 @@ class McpServer:
         pool: DevicePool,
         *,
         server_name: str = "mcp-debug-bridge",
-        server_version: str = "0.1.0",
+        server_version: str = "0.3.0",
         providers: list[SemanticProvider] | None = None,
         tool_handlers: dict[str, Any] | None = None,
     ) -> None:
@@ -329,11 +368,19 @@ class McpServer:
             # list. We capture refresh's change signal here (one HTTP probe)
             # and feed it straight into ``_emit_list_changed`` below, rather
             # than re-probing via ``_maybe_emit_list_changed_for``.
+            # R001-BB001: refresh also stays non-raising for auth errors
+            # (recording them queryably instead); we surface them HERE as an
+            # MCP error so "unauthorized" is never silently degraded to an
+            # empty "no capabilities" answer.
             def _probe():
                 changed = mirror.refresh(device_id)
-                return mirror.schemas(device_id), changed
+                auth_err = mirror.auth_error(device_id)
+                return mirror.schemas(device_id), changed, auth_err
+
+            schemas, changed, auth_err = await anyio.to_thread.run_sync(_probe)
 
-            schemas, changed = await anyio.to_thread.run_sync(_probe)
+            if auth_err is not None:
+                raise _bridge_error_to_mcp(auth_err)
 
             # Drive list_changed from this request's context (session is
             # reachable here — see module docstring spike note). Best-effort:

{debug_control_plane-0.1.1 → debug_control_plane-0.3.0}/debug_control_plane.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: debug-control-plane
-Version: 0.1.1
+Version: 0.3.0
 Summary: Multi-product reusable debug control plane (device discovery + MCP adapter).
 Author: tangxiaolu
 License: MIT
@@ -14,6 +14,7 @@ Provides-Extra: test
 Requires-Dist: pytest>=7; extra == "test"
 Requires-Dist: pytest-cov>=4; extra == "test"
 Requires-Dist: ruff>=0.4; extra == "test"
+Requires-Dist: pytest-asyncio>=0.23; extra == "test"
 Dynamic: license-file
 
 # debug-control-plane (Python)
@@ -61,7 +62,7 @@ python/
 ├── README.md                       # this file
 ├── LICENSE                         # MIT
 └── debug_control_plane/
-    ├── __init__.py                 # __version__ = "0.1.0"
+    ├── __init__.py                 # __version__ = "0.3.0"
     ├── device_discovery/           # USB/LAN device discovery + device pool
     │   ├── device_candidates.py
     │   ├── device_pool.py          # identity-keyed pool, TTL expiry / 身份键池，TTL 过期
@@ -91,7 +92,8 @@ Points at `debug_control_plane.mcp_plane.server:main` — a bare server (no busi
 
 ## Version / 版本
 
-`0.1.0` — initial release, API unstable. 首发，API 不稳定。
+`0.3.0` — aligned with Kotlin/Dart/Flutter `0.3.0`, API unstable.
+`0.3.0` —— 与 Kotlin/Dart/Flutter `0.3.0` 对齐，API 不稳定。
 
 ## License / 许可证
 

{debug_control_plane-0.1.1 → debug_control_plane-0.3.0}/debug_control_plane.egg-info/SOURCES.txt

@@ -24,8 +24,10 @@ 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
+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_device_candidates.py
 tests/test_device_pool.py
 tests/test_discovery_cross_identify.py

{debug_control_plane-0.1.1 → debug_control_plane-0.3.0}/debug_control_plane.egg-info/requires.txt

@@ -6,3 +6,4 @@ anyio<5,>=4
 pytest>=7
 pytest-cov>=4
 ruff>=0.4
+pytest-asyncio>=0.23

{debug_control_plane-0.1.1 → debug_control_plane-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "debug-control-plane"
-version = "0.1.1"
+version = "0.3.0"
 description = "Multi-product reusable debug control plane (device discovery + MCP adapter)."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -17,7 +17,9 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
-test = ["pytest>=7", "pytest-cov>=4", "ruff>=0.4"]
+# CI 首跑暴露: test_server.py 用 @pytest.mark.asyncio(strict 模式), 本地全局环境
+# 碰巧装了 pytest-asyncio 所以七步门一直绿; runner 按 extras 声明装缺它 → async 测试全挂。
+test = ["pytest>=7", "pytest-cov>=4", "ruff>=0.4", "pytest-asyncio>=0.23"]
 
 [project.scripts]
 # R021-CLEANUP-P1(方案 X): console-script 冲突解决。
@@ -38,6 +40,9 @@ include = ["debug_control_plane*"]
 line-length = 100
 target-version = "py310"
 
+[tool.pytest.ini_options]
+asyncio_mode = "strict"
+
 [tool.ruff.lint]
 select = ["E", "F", "I", "W", "UP", "B"]
 ignore = ["E501"]