ios-decrypt-hub 0.2.0__py3-none-any.whl

idh/__init__.py

@@ -0,0 +1,3 @@
+"""IOSDecryptHub discovery and MCP gateway."""
+
+__version__ = "0.2.0"

idh/__main__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

idh/cli.py

@@ -0,0 +1,244 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+import webbrowser
+from collections.abc import Callable, Sequence
+
+from . import __version__
+from .discovery import DiscoveryRegistry, discover
+from .gateway import GatewayServer, TransparentProxy, inventory, resolve_target, serve_stdio
+from .models import AppEndpoint
+
+
+def _manual_endpoints(values: Sequence[str]) -> list[AppEndpoint]:
+    endpoints: list[AppEndpoint] = []
+    for value in values:
+        endpoints.append(AppEndpoint.from_url(value))
+    return endpoints
+
+
+def _add_discovery_options(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--endpoint",
+        action="append",
+        default=[],
+        metavar="URL",
+        help="手动加入 HTTP 地址，可重复使用",
+    )
+    parser.add_argument(
+        "--no-discovery", action="store_true", help="禁用 UDP 发现，仅使用 --endpoint"
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="idh", description="IOSDecryptHub 发现与 MCP 网关")
+    parser.add_argument("--version", action="version", version=f"idh {__version__}")
+    subparsers = parser.add_subparsers(dest="command")
+
+    devices = subparsers.add_parser("devices", help="列出局域网中的设备和 App")
+    devices.add_argument("--timeout", type=float, default=1.5, help="发现等待秒数，默认 1.5")
+    devices.add_argument("--json", action="store_true", help="输出 JSON")
+    _add_discovery_options(devices)
+
+    watch = subparsers.add_parser("watch", help="持续观察设备上下线")
+    watch.add_argument("--interval", type=float, default=0.5, help="刷新间隔秒数")
+    watch.add_argument("--json", action="store_true", help="逐行输出 JSON 事件")
+    _add_discovery_options(watch)
+
+    open_command = subparsers.add_parser("open", help="在浏览器中打开 App Web 面板")
+    open_command.add_argument("target", help="序号、Bundle ID、App 名称或服务名")
+    open_command.add_argument("--timeout", type=float, default=1.5)
+    _add_discovery_options(open_command)
+
+    mcp = subparsers.add_parser("mcp", help="启动 stdio MCP 网关")
+    mcp.add_argument("--target", help="透明代理到指定 App；省略时启动聚合网关")
+    mcp.add_argument("--startup-timeout", type=float, default=1.5, help="启动时发现等待秒数")
+    _add_discovery_options(mcp)
+
+    call = subparsers.add_parser("call", help="一次性调用指定 App 的 MCP 工具")
+    call.add_argument("target", help="优先使用 devices 返回的 target_id")
+    call.add_argument("tool_name", help="远端 MCP 工具名称")
+    call.add_argument("--arguments", default="{}", metavar="JSON", help="工具参数 JSON 对象")
+    call.add_argument("--allow-mutation", action="store_true", help="允许调用修改远端状态的工具")
+    call.add_argument("--timeout", type=float, default=1.5, help="发现等待秒数，默认 1.5")
+    call.add_argument("--json", action="store_true", help="输出完整 MCP 工具结果 JSON")
+    _add_discovery_options(call)
+    return parser
+
+
+def _normalize_argv(argv: Sequence[str]) -> list[str]:
+    values = list(argv)
+    if values and values[0] == "--devices":
+        return ["devices", *values[1:]]
+    if values and values[0] == "--watch":
+        return ["watch", *values[1:]]
+    return values
+
+
+def _print_inventory(data: dict[str, object]) -> None:
+    devices = data.get("devices", [])
+    if not devices:
+        print("未发现 IOSDecryptHub App")
+        return
+    for device in devices:
+        print(f"{device['name']}")
+        for app in device["apps"]:
+            status = app["properties"].get("status", "discovered")
+            bundle = app["bundle"] or "-"
+            print(f"  [{app['index']}] {app['app']}  {bundle}  :{app['port']}  {status}")
+            print(f"      Web: {app['web']}")
+            print(f"      MCP: {app['mcp']}")
+
+
+def _run_devices(args: argparse.Namespace) -> int:
+    endpoints = discover(
+        args.timeout,
+        manual_endpoints=_manual_endpoints(args.endpoint),
+        enable_bonjour=not args.no_discovery,
+    )
+    data = inventory(endpoints)
+    if args.json:
+        print(json.dumps(data, ensure_ascii=False, indent=2))
+    else:
+        _print_inventory(data)
+    return 0
+
+
+def _run_watch(args: argparse.Namespace) -> int:
+    registry = DiscoveryRegistry(manual_endpoints=_manual_endpoints(args.endpoint))
+    previous: dict[str, dict[str, object]] = {}
+    try:
+        registry.start(enable_bonjour=not args.no_discovery)
+        while True:
+            current = {item.key: item.as_dict() for item in registry.snapshot()}
+            for name in sorted(current.keys() - previous.keys()):
+                if args.json:
+                    print(
+                        json.dumps({"event": "add", "app": current[name]}, ensure_ascii=False),
+                        flush=True,
+                    )
+                else:
+                    print(f"+ {current[name]['app']}  {current[name]['web']}", flush=True)
+            for name in sorted(previous.keys() - current.keys()):
+                if args.json:
+                    print(
+                        json.dumps({"event": "remove", "app": previous[name]}, ensure_ascii=False),
+                        flush=True,
+                    )
+                else:
+                    print(f"- {previous[name]['app']}  {previous[name]['web']}", flush=True)
+            previous = current
+            time.sleep(max(0.1, args.interval))
+    except KeyboardInterrupt:
+        return 0
+    finally:
+        registry.close()
+
+
+def _run_open(args: argparse.Namespace) -> int:
+    endpoints = discover(
+        args.timeout,
+        manual_endpoints=_manual_endpoints(args.endpoint),
+        enable_bonjour=not args.no_discovery,
+    )
+    try:
+        endpoint = resolve_target(endpoints, args.target)
+    except LookupError as exc:
+        print(f"idh: {exc}", file=sys.stderr)
+        return 2
+    print(endpoint.panel_url)
+    return 0 if webbrowser.open(endpoint.panel_url) else 1
+
+
+def _target_ready(target: str) -> Callable[[list[AppEndpoint]], bool]:
+    def ready(endpoints: list[AppEndpoint]) -> bool:
+        try:
+            resolve_target(endpoints, target)
+        except LookupError:
+            return False
+        return True
+
+    return ready
+
+
+def _run_mcp(args: argparse.Namespace) -> int:
+    manual = _manual_endpoints(args.endpoint)
+    registry = DiscoveryRegistry(manual_endpoints=manual)
+    try:
+        registry.start(enable_bonjour=not args.no_discovery)
+        if args.target:
+            registry.wait(args.startup_timeout, predicate=_target_ready(args.target))
+            handler = TransparentProxy(registry.snapshot, args.target).handle
+        else:
+            registry.wait(args.startup_timeout)
+            handler = GatewayServer(registry.snapshot).handle
+        serve_stdio(handler)
+        return 0
+    finally:
+        registry.close()
+
+
+def _run_call(args: argparse.Namespace) -> int:
+    try:
+        tool_arguments = json.loads(args.arguments)
+    except json.JSONDecodeError as exc:
+        print(f"idh: --arguments 不是有效 JSON: {exc}", file=sys.stderr)
+        return 2
+    if not isinstance(tool_arguments, dict):
+        print("idh: --arguments 必须是 JSON 对象", file=sys.stderr)
+        return 2
+
+    registry = DiscoveryRegistry(manual_endpoints=_manual_endpoints(args.endpoint))
+    try:
+        registry.start(enable_bonjour=not args.no_discovery)
+        registry.wait(args.timeout, predicate=_target_ready(args.target))
+        gateway = GatewayServer(registry.snapshot)
+        response = gateway.handle(
+            {
+                "jsonrpc": "2.0",
+                "id": 1,
+                "method": "tools/call",
+                "params": {
+                    "name": "idh_call_tool",
+                    "arguments": {
+                        "target": args.target,
+                        "tool_name": args.tool_name,
+                        "tool_arguments": tool_arguments,
+                        "allow_mutation": args.allow_mutation,
+                    },
+                },
+            }
+        )
+    finally:
+        registry.close()
+    result = response.get("result", {}) if isinstance(response, dict) else {}
+    if args.json:
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+    else:
+        content = result.get("content", []) if isinstance(result, dict) else []
+        texts = [item.get("text") for item in content if isinstance(item, dict) and item.get("text")]
+        if texts:
+            print("\n".join(texts))
+        else:
+            print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 1 if isinstance(result, dict) and result.get("isError") else 0
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(_normalize_argv(sys.argv[1:] if argv is None else argv))
+    if args.command == "devices":
+        return _run_devices(args)
+    if args.command == "watch":
+        return _run_watch(args)
+    if args.command == "open":
+        return _run_open(args)
+    if args.command == "mcp":
+        return _run_mcp(args)
+    if args.command == "call":
+        return _run_call(args)
+    parser.print_help()
+    return 0

idh/discovery.py

@@ -0,0 +1,231 @@
+"""UDP 广播信标发现 — 替代 Bonjour/zeroconf（注入场景无 plist/entitlement 条件）。"""
+
+from __future__ import annotations
+
+import json
+import socket
+import threading
+import time
+from collections.abc import Callable, Iterable
+
+from .models import AppEndpoint
+
+BEACON_PORT = 8089
+BEACON_MAGIC = "idh-beacon"
+BEACON_STALE_AFTER = 6.0
+BEACON_EXPIRE_AFTER = 10.0
+
+EndpointPredicate = Callable[[list[AppEndpoint]], bool]
+
+
+def _endpoint_from_beacon(data: dict, sender_ip: str) -> AppEndpoint | None:
+    """将 UDP 广播 JSON 包转换为 AppEndpoint。"""
+    if not isinstance(data, dict) or data.get("type") != BEACON_MAGIC:
+        return None
+    try:
+        port = int(data.get("port", 8088))
+    except (TypeError, ValueError):
+        return None
+    if not 1 <= port <= 65535:
+        return None
+
+    raw_id = data.get("id")
+    if raw_id is None:
+        raw_id = f"{sender_ip}:{port}:{data.get('bundle', '')}"
+    if not isinstance(raw_id, (str, int)):
+        return None
+    instance_id = str(raw_id).strip()
+    if not instance_id:
+        return None
+    service_name = f"idh-{instance_id[:8]}" if len(instance_id) >= 8 else f"idh-{instance_id}"
+    properties = {
+        "protocol": str(data.get("protocol", "2")),
+        "id": instance_id,
+        "app_name": str(data.get("app_name", "")),
+        "bundle": str(data.get("bundle", "")),
+        "app_version": str(data.get("app_version", "")),
+        "idh_version": str(data.get("idh_version", "")),
+        "mcp_path": str(data.get("mcp_path", "/api/mcp")),
+        "panel_path": str(data.get("panel_path", "/")),
+        "pid": str(data.get("pid", "")),
+    }
+    return AppEndpoint(
+        service_name=service_name,
+        server=sender_ip,
+        addresses=(sender_ip,),
+        port=port,
+        properties=properties,
+        source="udp",
+    )
+
+
+class DiscoveryRegistry:
+    """监听 UDP 8089 端口，收集 dylib 广播信标。"""
+
+    def __init__(
+        self,
+        *,
+        manual_endpoints: Iterable[AppEndpoint] = (),
+        on_change: Callable[[], None] | None = None,
+        stale_after: float = BEACON_STALE_AFTER,
+        expire_after: float = BEACON_EXPIRE_AFTER,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        if stale_after <= 0 or expire_after <= stale_after:
+            raise ValueError("expire_after 必须大于 stale_after，且两者都必须为正数")
+        manual = list(manual_endpoints)
+        self._lock = threading.Condition()
+        self._endpoints: dict[str, AppEndpoint] = {
+            endpoint.key: endpoint for endpoint in manual
+        }
+        self._manual_keys = {endpoint.key for endpoint in manual}
+        self._last_seen: dict[str, float] = {}
+        self._on_change = on_change
+        self._stale_after = stale_after
+        self._expire_after = expire_after
+        self._clock = clock
+        self._sock: socket.socket | None = None
+        self._thread: threading.Thread | None = None
+        self._running = False
+
+    def start(self, *, enable_bonjour: bool = True) -> None:
+        """启动 UDP 监听（参数名保留兼容，实际走 UDP）。"""
+        if self._running:
+            return
+        if not enable_bonjour:
+            return
+        self._running = True
+        self._sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        self._sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        if hasattr(socket, "SO_REUSEPORT"):
+            try:
+                self._sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEPORT, 1)
+            except OSError:
+                pass
+        self._sock.bind(("", BEACON_PORT))
+        self._sock.settimeout(0.5)
+        self._thread = threading.Thread(target=self._listen_loop, daemon=True, name="idh-udp-discovery")
+        self._thread.start()
+
+    def close(self) -> None:
+        self._running = False
+        if self._thread is not None:
+            self._thread.join(timeout=2.0)
+            self._thread = None
+        if self._sock is not None:
+            self._sock.close()
+            self._sock = None
+
+    def wait(self, timeout: float, *, predicate: EndpointPredicate | None = None) -> bool:
+        deadline = self._clock() + max(0.0, timeout)
+        with self._lock:
+            while True:
+                items = self._snapshot_locked(self._clock())
+                if items and (predicate is None or predicate(items)):
+                    return True
+                remaining = deadline - self._clock()
+                if remaining <= 0:
+                    return False
+                self._lock.wait(timeout=remaining)
+
+    def snapshot(self) -> list[AppEndpoint]:
+        with self._lock:
+            return self._snapshot_locked(self._clock())
+
+    def _snapshot_locked(self, now: float) -> list[AppEndpoint]:
+        self._prune_locked(now)
+        items: list[AppEndpoint] = []
+        for key, endpoint in self._endpoints.items():
+            if key in self._manual_keys:
+                items.append(endpoint)
+                continue
+            age = max(0.0, now - self._last_seen.get(key, now))
+            status = "stale" if age >= self._stale_after else "fresh"
+            items.append(
+                endpoint.with_properties(
+                    {"beacon_status": status, "last_seen_seconds": f"{age:.1f}"}
+                )
+            )
+        return sorted(
+            items,
+            key=lambda item: (item.device_key.casefold(), item.app_name.casefold(), item.port),
+        )
+
+    def _prune_locked(self, now: float) -> bool:
+        expired = [
+            key
+            for key, seen_at in self._last_seen.items()
+            if now - seen_at >= self._expire_after
+        ]
+        for key in expired:
+            self._last_seen.pop(key, None)
+            self._endpoints.pop(key, None)
+        return bool(expired)
+
+    def _remove_superseded_locked(self, endpoint: AppEndpoint) -> bool:
+        if not endpoint.bundle_id:
+            return False
+        superseded = [
+            key
+            for key, item in self._endpoints.items()
+            if key not in self._manual_keys
+            and key != endpoint.key
+            and item.server == endpoint.server
+            and item.bundle_id == endpoint.bundle_id
+        ]
+        for key in superseded:
+            self._last_seen.pop(key, None)
+            self._endpoints.pop(key, None)
+        return bool(superseded)
+
+    def _record_endpoint(self, endpoint: AppEndpoint) -> None:
+        with self._lock:
+            self._remove_superseded_locked(endpoint)
+            self._endpoints[endpoint.key] = endpoint
+            self._last_seen[endpoint.key] = self._clock()
+            self._lock.notify_all()
+        if self._on_change:
+            self._on_change()
+
+    def _listen_loop(self) -> None:
+        while self._running:
+            try:
+                raw, addr = self._sock.recvfrom(4096)
+            except TimeoutError:
+                with self._lock:
+                    changed = self._prune_locked(self._clock())
+                    if changed:
+                        self._lock.notify_all()
+                if changed and self._on_change:
+                    self._on_change()
+                continue
+            except OSError:
+                break
+            try:
+                data = json.loads(raw)
+            except (json.JSONDecodeError, UnicodeDecodeError):
+                continue
+            if not isinstance(data, dict):
+                continue
+            sender_ip = addr[0]
+            endpoint = _endpoint_from_beacon(data, sender_ip)
+            if endpoint is None:
+                continue
+            self._record_endpoint(endpoint)
+
+
+def discover(
+    timeout: float = 1.5,
+    *,
+    manual_endpoints: Iterable[AppEndpoint] = (),
+    enable_bonjour: bool = True,
+) -> list[AppEndpoint]:
+    """发现局域网中的 IOSDecryptHub 实例。"""
+    registry = DiscoveryRegistry(manual_endpoints=manual_endpoints)
+    try:
+        registry.start(enable_bonjour=enable_bonjour)
+        if enable_bonjour:
+            threading.Event().wait(max(0.0, timeout))
+        return registry.snapshot()
+    finally:
+        registry.close()