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

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

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

{debug_control_plane-0.1.1 → debug_control_plane-0.4.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.4.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.4.0` — aligned with Kotlin/Dart/Flutter `0.4.0`, API unstable.
+`0.4.0` —— 与 Kotlin/Dart/Flutter `0.4.0` 对齐，API 不稳定。
 
 ## License / 许可证
 

{debug_control_plane-0.1.1 → debug_control_plane-0.4.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.4.0"

{debug_control_plane-0.1.1 → debug_control_plane-0.4.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
@@ -253,6 +279,11 @@ class BridgeClient:
         method: str,
         path: list[str],
         body: Any = None,
+        *,
+        capability_id: str | None = None,
+        scope: str | None = None,
+        page_id: str | None = None,
+        scope_revision: int | None = None,
     ) -> Any:
         """Forward ``method path body`` to the phone (byte-level pass-through).
 
@@ -269,6 +300,9 @@ class BridgeClient:
             body: request body. If it's a dict/list it's sent as JSON
                 (``json=``); otherwise it's sent raw (``content=``) and may
                 be ``None``.
+            capability_id/scope/page_id/scope_revision: optional R003
+                selector metadata forwarded as ``X-DCP-*`` headers. Omitted
+                values keep the legacy flat dispatch behavior.
 
         Returns:
             The phone's response body, parsed: dict/list for JSON, ``str``
@@ -282,26 +316,53 @@ class BridgeClient:
         """
         host = self.resolve(device_id)
         url = self._build_url(host, path)
+        headers = self._auth_headers(device_id)
+        headers.update(
+            selector_headers(
+                capability_id=capability_id,
+                scope=scope,
+                page_id=page_id,
+                scope_revision=scope_revision,
+            )
+        )
         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:
+    def read(
+        self,
+        device_id: str,
+        path: list[str],
+        *,
+        capability_id: str | None = None,
+        scope: str | None = None,
+        page_id: str | None = None,
+        scope_revision: int | None = None,
+    ) -> Any:
         """GET convenience for ``read_resource`` / ``get_state``.
 
         Equivalent to ``invoke(device_id, "GET", path, None)`` but signals
         intent at the call site. Returns the parsed phone body.
         """
-        return self.invoke(device_id, "GET", path, None)
+        return self.invoke(
+            device_id,
+            "GET",
+            path,
+            None,
+            capability_id=capability_id,
+            scope=scope,
+            page_id=page_id,
+            scope_revision=scope_revision,
+        )
 
     def hello(self, device_id: str) -> NetworkTarget:
         """Fetch ``/hello`` and parse to a typed :class:`NetworkTarget`.
@@ -317,12 +378,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 +432,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 +457,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}...``.
 
@@ -434,6 +564,26 @@ def _safe_body(resp: httpx.Response) -> Any:
         return resp.text
 
 
+def selector_headers(
+    *,
+    capability_id: str | None = None,
+    scope: str | None = None,
+    page_id: str | None = None,
+    scope_revision: int | None = None,
+) -> dict[str, str]:
+    """Build optional R003 selector headers for capability-scoped dispatch."""
+    headers: dict[str, str] = {}
+    if isinstance(capability_id, str) and capability_id:
+        headers["X-DCP-Capability-Id"] = capability_id
+    if scope in ("app", "page"):
+        headers["X-DCP-Capability-Scope"] = scope
+    if isinstance(page_id, str) and page_id:
+        headers["X-DCP-Page-Id"] = page_id
+    if isinstance(scope_revision, int) and not isinstance(scope_revision, bool):
+        headers["X-DCP-Scope-Revision"] = str(scope_revision)
+    return headers
+
+
 def _quote_segment(seg: str) -> str:
     """URL-encode a single path segment (preserving ``/`` within a segment).
 
@@ -512,14 +662,46 @@ 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",
+    "selector_headers",
     # AD-B9: DeviceUnreachable 已下沉 device_discovery.protocol,
     # 本模块 forward import(BF007),不 re-export。
 ]

{debug_control_plane-0.1.1 → debug_control_plane-0.4.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,
@@ -128,12 +129,21 @@ class CapabilitySchema:
         resources: declared REST resources (read side).
         commands: declared commands (write side).
         description: optional capability-level description (may be absent).
+        scope: ``app`` or ``page``; missing/malformed wire values downgrade
+            locally to ``app``.
+        page_id: optional business-provided page identity for page scope.
+        page_name: optional display metadata; never participates in tool names.
+        scope_revision: optional integer mirror revision for stale detection.
     """
 
     capability_id: str
     resources: tuple[ResourceDecl, ...] = ()
     commands: tuple[CommandDecl, ...] = ()
     description: str | None = None
+    scope: str = "app"
+    page_id: str | None = None
+    page_name: str | None = None
+    scope_revision: int | None = None
 
 
 # ---------------------------------------------------------------------------
@@ -248,6 +258,19 @@ _STATIC_META_TOOLS: tuple[ToolSpec, ...] = (
                     "description": "Request body (object) or null.",
                     "additionalProperties": True,
                 },
+                "scope": {
+                    "type": "string",
+                    "enum": ["app", "page"],
+                    "description": "Optional capability scope selector.",
+                },
+                "page_id": {
+                    "type": "string",
+                    "description": "Optional page id selector for page scope.",
+                },
+                "scope_revision": {
+                    "type": "integer",
+                    "description": "Optional scope revision selector.",
+                },
             },
             "required": ["device_id", "capability_id", "command_path"],
             "additionalProperties": False,
@@ -273,6 +296,19 @@ _STATIC_META_TOOLS: tuple[ToolSpec, ...] = (
                     "type": ["object", "null"],
                     "additionalProperties": True,
                 },
+                "scope": {
+                    "type": "string",
+                    "enum": ["app", "page"],
+                    "description": "Optional capability scope selector.",
+                },
+                "page_id": {
+                    "type": "string",
+                    "description": "Optional page id selector for page scope.",
+                },
+                "scope_revision": {
+                    "type": "integer",
+                    "description": "Optional scope revision selector.",
+                },
             },
             "required": ["device_id", "capability_id", "resource_path"],
             "additionalProperties": False,
@@ -397,6 +433,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 +472,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 +506,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)
     # ------------------------------------------------------------------
@@ -564,6 +630,10 @@ class CapabilityMirror:
                     resources=(),
                     commands=(),
                     description=None,
+                    scope="app",
+                    page_id=None,
+                    page_name=None,
+                    scope_revision=None,
                 )
                 for tag in target.capabilities
             ]
@@ -587,11 +657,19 @@ class CapabilityMirror:
         description = (
             description_raw if isinstance(description_raw, str) and description_raw else None
         )
+        scope = _parse_scope(cap.get("scope"))
+        page_id = _parse_optional_string(cap.get("pageId"))
+        page_name = _parse_optional_string(cap.get("pageName"))
+        scope_revision = _parse_scope_revision(cap.get("scopeRevision"))
         return CapabilitySchema(
             capability_id=cap_id,
             resources=resources,
             commands=commands,
             description=description,
+            scope=scope,
+            page_id=page_id,
+            page_name=page_name,
+            scope_revision=scope_revision,
         )
 
 
@@ -632,6 +710,23 @@ def _parse_decls(
     return tuple(out)  # type: ignore[return-value]
 
 
+def _parse_scope(raw: Any) -> str:
+    """Parse registeredCapabilities[].scope with legacy-safe downgrade."""
+    return raw if raw in ("app", "page") else "app"
+
+
+def _parse_optional_string(raw: Any) -> str | None:
+    """Return non-empty string metadata, otherwise local downgrade to None."""
+    return raw if isinstance(raw, str) and raw else None
+
+
+def _parse_scope_revision(raw: Any) -> int | None:
+    """Return real integer revisions only; bool/malformed values downgrade."""
+    if isinstance(raw, bool):
+        return None
+    return raw if isinstance(raw, int) else None
+
+
 __all__ = [
     "CapabilityMirror",
     "CapabilitySchema",