adbproxy 0.1.0__py3-none-any.whl

adbproxy/protocols/payload/shell_v2.py

@@ -0,0 +1,28 @@
+"""Pure shell_v2 framing: [1B id][4B LE len][data]."""
+
+from __future__ import annotations
+
+import struct
+
+from adbproxy.config import MAX_V2_BUF
+
+
+def split_v2_frames(buf):
+    """切分 v2 帧 [1B id][4B LE len][data]。
+
+    返回 (frames:list[(id,payload)], leftover:bytearray, ok:bool)。
+    ok=False 表示遇到非法 len，调用方应降级为碎片流。
+    """
+    frames = []
+    pos = 0
+    n = len(buf)
+    while pos + 5 <= n:
+        id_ = buf[pos]
+        length = struct.unpack_from("<I", buf, pos + 1)[0]
+        if length > MAX_V2_BUF:
+            return (frames, bytearray(buf[pos:]), False)
+        if pos + 5 + length > n:
+            break  # 半包，等后续
+        frames.append((id_, bytes(buf[pos + 5 : pos + 5 + length])))
+        pos += 5 + length
+    return (frames, bytearray(buf[pos:]), True)

adbproxy/protocols/payload/sync.py

@@ -0,0 +1,180 @@
+"""Pure sync wire framing (file_sync_protocol.h shapes).
+
+No capture, no compression, no I/O. One SyncWireDecoder per direction.
+"""
+
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass
+
+from adbproxy.config import (
+    MAX_V2_BUF,
+    SYNC_DATA_MAX,
+    _DENT_V1_SIZE,
+    _DENT_V2_SIZE,
+    _RECV_V2_SIZE,
+    _SEND_V2_SIZE,
+    _STAT_V1_SIZE,
+    _STAT_V2_SIZE,
+)
+
+
+@dataclass(frozen=True)
+class SyncFrame:
+    """One complete sync frame (id + full raw frame bytes including id)."""
+
+    id: bytes
+    raw: bytes
+
+
+def plan_sync_frame(id_: bytes, side: str, awaiting_details: str | None):
+    """返回帧分帧方案：("var",) / ("fixed", n) / ("dent", header, namelen_off) / None(未知)。
+
+    依赖 (id, side, awaiting_details) 区分 SND2/RCV2 双发的 path 帧 vs details struct。
+    """
+    if side == "c":
+        # client→server：均为请求。路径请求类（8+path_length+path）
+        if id_ in (b"STA2", b"LST2", b"STAT", b"LIST", b"SEND", b"RECV"):
+            return ("var",)
+        if id_ == b"SND2":
+            # 双发第二帧 = sync_send_v2(12B 定长)；否则 = path 请求
+            if awaiting_details == "send":
+                return ("fixed", _SEND_V2_SIZE)
+            return ("var",)
+        if id_ == b"RCV2":
+            if awaiting_details == "recv":
+                return ("fixed", _RECV_V2_SIZE)
+            return ("var",)
+        if id_ == b"DATA":
+            return ("var",)
+        if id_ in (b"DONE", b"QUIT"):
+            return ("fixed", 8)
+        if id_ == b"FAIL":
+            return ("var",)
+        return None
+    else:  # server→client：均为响应
+        if id_ in (b"STA2", b"LST2"):
+            return ("fixed", _STAT_V2_SIZE)  # sync_stat_v2 定长
+        if id_ == b"STAT":
+            return ("fixed", _STAT_V1_SIZE)  # sync_stat_v1 定长
+        if id_ == b"DNT2":
+            return (
+                "dent",
+                _DENT_V2_SIZE,
+                _DENT_V2_SIZE - 4,
+            )  # 76B 头 + namelen name
+        if id_ == b"DENT":
+            return (
+                "dent",
+                _DENT_V1_SIZE,
+                _DENT_V1_SIZE - 4,
+            )  # 20B 头 + namelen name
+        if id_ == b"DATA":
+            return ("var",)
+        if id_ in (b"DONE", b"OKAY", b"QUIT"):
+            return ("fixed", 8)
+        if id_ == b"FAIL":
+            return ("var",)
+        return None
+
+
+class SyncWireDecoder:
+    """Incremental per-direction sync framer.
+
+    Prefer ``try_take_frame(plan_fn)`` so session can update ``awaiting_details``
+    between frames inside one TCP chunk (SND2/RCV2 dual-send).
+    """
+
+    def __init__(self):
+        self.buf = bytearray()
+        self.bypass = False
+        self.degrade_reason: str | None = None
+
+    def reset(self):
+        self.buf = bytearray()
+        self.bypass = False
+        self.degrade_reason = None
+
+    def extend(self, data: bytes | bytearray | memoryview) -> None:
+        if data and not self.bypass:
+            self.buf.extend(data)
+
+    def try_take_frame(self, plan_fn) -> SyncFrame | None:
+        """Extract at most one complete frame.
+
+        Returns SyncFrame when a full frame is available, None when more data is
+        needed. On framing errors sets ``bypass`` and returns None.
+        ``plan_fn(id_)`` must return plan_sync_frame-style plan or None.
+        """
+        if self.bypass:
+            return None
+        if len(self.buf) < 4:
+            return None
+        id_ = bytes(self.buf[:4])
+        plan = plan_fn(id_)
+        if plan is None:
+            self.bypass = True
+            self.degrade_reason = f"unknown id {id_!r}"
+            return None
+        kind = plan[0]
+        if kind == "var":
+            if len(self.buf) < 8:
+                return None
+            length = struct.unpack_from("<I", self.buf, 4)[0]
+            length_limit = SYNC_DATA_MAX if id_ == b"DATA" else MAX_V2_BUF
+            if length > length_limit:
+                self.bypass = True
+                self.degrade_reason = (
+                    f"var len too large id={id_!r} len={length} limit={length_limit}"
+                )
+                return None
+            if len(self.buf) < 8 + length:
+                return None
+            raw = bytes(self.buf[: 8 + length])
+            del self.buf[: 8 + length]
+            return SyncFrame(id=id_, raw=raw)
+        if kind == "fixed":
+            size = plan[1]
+            if len(self.buf) < size:
+                return None
+            raw = bytes(self.buf[:size])
+            del self.buf[:size]
+            return SyncFrame(id=id_, raw=raw)
+        # dent: header + namelen name
+        header_size = plan[1]
+        namelen_off = plan[2]
+        if len(self.buf) < header_size:
+            return None
+        namelen = struct.unpack_from("<I", self.buf, namelen_off)[0]
+        if namelen > MAX_V2_BUF:
+            self.bypass = True
+            self.degrade_reason = (
+                f"dent namelen too large id={id_!r} namelen={namelen}"
+            )
+            return None
+        if len(self.buf) < header_size + namelen:
+            return None
+        raw = bytes(self.buf[: header_size + namelen])
+        del self.buf[: header_size + namelen]
+        return SyncFrame(id=id_, raw=raw)
+
+    def feed(
+        self,
+        data: bytes | bytearray | memoryview,
+        side: str,
+        awaiting_details: str | None = None,
+    ) -> list[SyncFrame]:
+        """Append data and emit all complete frames under a fixed awaiting snapshot.
+
+        For dual-send mid-chunk plan flips, use try_take_frame with a live plan_fn.
+        """
+        self.extend(data)
+        frames: list[SyncFrame] = []
+        while True:
+            frame = self.try_take_frame(
+                lambda id_, s=side, a=awaiting_details: plan_sync_frame(id_, s, a)
+            )
+            if frame is None:
+                return frames
+            frames.append(frame)

adbproxy/protocols/smart_socket/__init__.py

@@ -0,0 +1,33 @@
+"""Smart-socket protocol primitives (wire / conversation / handshake)."""
+
+from adbproxy.protocols.smart_socket.classifier import ServiceClassifier
+from adbproxy.protocols.smart_socket.conversation import SmartEvent, SmartSocketConversation
+from adbproxy.protocols.smart_socket.handshake import HandshakeStatus, SmartSocketHandshake
+from adbproxy.protocols.smart_socket.wire import (
+    FAIL,
+    OKAY,
+    decode_hex4,
+    encode_hex4,
+    encode_protocol_string,
+    format_service_frame,
+    parse_status,
+    try_parse_hex4_length_prefix,
+    try_parse_status,
+)
+
+__all__ = [
+    "FAIL",
+    "OKAY",
+    "HandshakeStatus",
+    "ServiceClassifier",
+    "SmartEvent",
+    "SmartSocketConversation",
+    "SmartSocketHandshake",
+    "decode_hex4",
+    "encode_hex4",
+    "encode_protocol_string",
+    "format_service_frame",
+    "parse_status",
+    "try_parse_hex4_length_prefix",
+    "try_parse_status",
+]

adbproxy/protocols/smart_socket/classifier.py

@@ -0,0 +1,78 @@
+"""Service classification for smart-socket service strings.
+
+Pure helpers: no I/O. Used by server conversation policy, device open path,
+and observers. Install grammar lives in payload.install; classifier re-exports.
+"""
+
+from __future__ import annotations
+
+from adbproxy.protocols.payload.install import (
+    is_install_stream_service as _is_install_stream_service,
+)
+from adbproxy.protocols.payload.install import (
+    parse_install_size as _parse_install_size,
+)
+
+
+class ServiceClassifier:
+    """Classify adb smart-socket service strings (host / shell / sync / install)."""
+
+    @staticmethod
+    def parse_service(svc: str):
+        """拆 service 串 -> (kind, args_set, cmd)。
+
+        kind ∈ {"host","shell","sync","other"}；args_set 含 raw/pty/v2 等 flag；
+        cmd 为命令文本。shell 真实语法：shell[,args]:cmd（无 v1，v2 是 flag）。
+        """
+        if svc.startswith("host:"):
+            return ("host", set(), svc)
+        if svc.startswith("sync:") or svc == "sync":
+            return ("sync", set(), svc)
+        if svc.startswith("shell"):
+            rest = svc[len("shell") :]
+            if rest.startswith(":"):
+                return ("shell", set(), rest[1:])
+            if rest.startswith(","):
+                colon = rest.find(":")
+                if colon == -1:
+                    return ("shell", set(a for a in rest[1:].split(",") if a), "")
+                args = set(a for a in rest[1:colon].split(",") if a)
+                return ("shell", args, rest[colon + 1 :])
+            return ("shell", set(), "")
+        return ("other", set(), svc)
+
+    @staticmethod
+    def is_host_service(svc: str | None) -> bool:
+        # AOSP host-services 家族（host:xxx / host-serial: / host-internal: 等）
+        return svc is not None and (svc.startswith("host:") or svc.startswith("host-"))
+
+    @staticmethod
+    def host_response_kind(svc: str | None) -> str:
+        """按 AOSP host service 选择响应 wire shape。"""
+        if not ServiceClassifier.is_host_service(svc):
+            return "stream"
+        if ":track-devices" in svc:
+            return "track"
+        if svc.startswith("host:tport:"):
+            return "fixed8"
+        if ":forward:" in svc or ":killforward:" in svc:
+            return "forward"
+        if svc.startswith("host:transport") or svc == "host:kill":
+            return "status"
+        return "protocol_string"
+
+    @staticmethod
+    def is_shell_service(svc: str | None) -> bool:
+        return svc is not None and svc.startswith("shell")
+
+    @staticmethod
+    def is_sync_service(svc: str | None) -> bool:
+        return svc is not None and (svc.startswith("sync:") or svc == "sync")
+
+    @staticmethod
+    def is_install_stream_service(svc: str | None) -> bool:
+        return _is_install_stream_service(svc)
+
+    @staticmethod
+    def parse_install_size(svc: str | None) -> int | None:
+        return _parse_install_size(svc)

adbproxy/protocols/smart_socket/conversation.py

@@ -0,0 +1,335 @@
+"""Server-side smart-socket conversation policy (pure bypass, no I/O).
+
+Incremental multi-shape request/response observation.
+
+Connection orchestration (not this module):
+- I2: service classify / set_mode / activate may run **pre-sendall** via
+  ``feed_request`` / ``try_parse_service_frame`` (parse single-source only).
+- I1/I3: ``sendall(original)`` must not be skipped on observe errors; payload
+  ``add_*`` runs **post-sendall** (fail-open).
+- Response path typically ``sendall`` then ``feed_response``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from adbproxy.protocols.smart_socket.classifier import ServiceClassifier
+from adbproxy.protocols.smart_socket.wire import FAIL, OKAY
+
+
+@dataclass(frozen=True)
+class SmartEvent:
+    """Observation event emitted by SmartSocketConversation."""
+
+    kind: str
+    # kind values:
+    #   service_request — svc=str, leftover=bytes
+    #   status — status=str (OKAY/FAIL)
+    #   fail_reason — reason=bytes
+    #   payload — data=bytes (host/shell/sync leftover after status strip)
+    #   host_payload — data=bytes (alias of payload for host multi-shape)
+    data: Any = None
+    leftover: bytes = b""
+    status: str | None = None
+    reason: bytes | None = None
+    svc: str | None = None
+
+
+class SmartSocketConversation:
+    """Per-TCP-connection pure smart-socket observer state.
+
+    Request path: reassemble ``<hex4><service>`` frames across TCP fragments.
+    Response path: multi-shape host policy + first-response OKAY/FAIL strip for
+    shell/sync streams. No sockets/threads/subprocess.
+    """
+
+    def __init__(self):
+        # client request reassembly
+        self._service_request_buf = bytearray()
+        # shell / sync first response (independent)
+        self._shell_first_response = self._new_first_response_state()
+        self._sync_first_response = self._new_first_response_state()
+        # host multi-shape SM
+        self.host_phase = "status"
+        self.host_status_buf = bytearray()
+        self.host_hex_buf = bytearray()
+        self.host_payload_remaining = 0
+        self.host_fixed_remaining = 0
+        self.host_track_active = False
+        self._last_host_svc = None
+        self.svc = None  # last observed service string (mirrors Connection.svc)
+        self._status_events: list[str] = []
+
+    @staticmethod
+    def _new_first_response_state():
+        return {"phase": "status", "buf": bytearray(), "remaining": 0}
+
+    def reset_host_state(self):
+        self.host_phase = "status"
+        self.host_status_buf = bytearray()
+        self.host_hex_buf = bytearray()
+        self.host_payload_remaining = 0
+        self.host_fixed_remaining = 0
+        self.host_track_active = False
+
+    def try_parse_service_frame(self, data: bytes):
+        """尝试解析一帧 4-hex 长度 + service 串（纯解析，无副作用除缓冲）。
+
+        返回 (svc:str, leftover:bytes) 或 None（数据不足/非协议）。
+        """
+        self._service_request_buf.extend(data)
+        if len(self._service_request_buf) < 4:
+            return None
+        try:
+            cmd_len = int(self._service_request_buf[:4].decode("ascii"), 16)
+        except ValueError:
+            # 非 smart-socket 数据不应长期占用观察缓冲
+            self._service_request_buf = bytearray()
+            return None
+        frame_size = 4 + cmd_len
+        if len(self._service_request_buf) < frame_size:
+            return None  # 半包
+        svc = self._service_request_buf[4:frame_size].decode("ascii", errors="ignore")
+        leftover = bytes(self._service_request_buf[frame_size:])
+        self._service_request_buf = bytearray()
+        self.svc = svc
+        return (svc, leftover)
+
+    def feed_request(self, data: bytes) -> list[SmartEvent]:
+        """Observe client→server bytes. Returns service_request events when a frame completes."""
+        events: list[SmartEvent] = []
+        parsed = self.try_parse_service_frame(data)
+        if parsed is not None:
+            svc, leftover = parsed
+            events.append(
+                SmartEvent(
+                    kind="service_request",
+                    svc=svc,
+                    leftover=leftover,
+                    data=svc,
+                )
+            )
+        return events
+
+    def feed_response(
+        self,
+        data: bytes,
+        *,
+        shell_active: bool = False,
+        shell_okay_consumed: bool = False,
+        sync_active: bool = False,
+        sync_okay_consumed: bool = False,
+        svc: str | None = None,
+    ) -> tuple[list[SmartEvent], bool]:
+        """Observe server→client bytes under current stream activation flags.
+
+        Returns ``(events, complete)`` where events may include status /
+        fail_reason / payload. Does not mutate sockets. Host status words are
+        both appended as status events and left in ``_status_events`` until the
+        connection drains that side-channel (S5).
+        """
+        if svc is not None:
+            self.svc = svc
+        events: list[SmartEvent] = []
+
+        if shell_active and not shell_okay_consumed:
+            complete, leftover = self.consume_first_response(
+                data, self._shell_first_response, emit=events
+            )
+            if complete and leftover:
+                events.append(SmartEvent(kind="payload", data=leftover))
+            return events, complete
+        if shell_active:
+            events.append(SmartEvent(kind="payload", data=data))
+            return events, True
+
+        if sync_active and not sync_okay_consumed:
+            complete, leftover = self.consume_first_response(
+                data, self._sync_first_response, emit=events
+            )
+            if complete and leftover:
+                events.append(SmartEvent(kind="payload", data=leftover))
+            return events, complete
+        if sync_active:
+            events.append(SmartEvent(kind="payload", data=data))
+            return events, True
+
+        # host / other
+        if ServiceClassifier.is_host_service(self.svc):
+            leftover = self.parse_host_response(data)
+            for st in self._status_events:
+                events.append(SmartEvent(kind="status", status=st, data=st))
+        else:
+            # Stateless first-status strip for non-host; mirror loggable status.
+            if data.startswith(OKAY) or data.startswith(FAIL):
+                status = data[:4].decode("ascii", errors="ignore")
+                events.append(SmartEvent(kind="status", status=status, data=status))
+            leftover = self.parse_server_first(data)
+        if leftover:
+            events.append(SmartEvent(kind="payload", data=leftover))
+        return events, True
+
+    def consume_first_response(self, data, state, emit: list[SmartEvent] | None = None):
+        """重组服务首响应，确保 OKAY/FAIL 及 FAIL protocol-string 不进入 payload。"""
+        buf = state["buf"]
+        buf.extend(data)
+        status_events = emit if emit is not None else []
+
+        while True:
+            if state["phase"] == "status":
+                if len(buf) < 4:
+                    return False, b""
+                status = bytes(buf[:4])
+                del buf[:4]
+                if status not in (OKAY, FAIL):
+                    payload = status + bytes(buf)
+                    buf.clear()
+                    state["phase"] = "done"
+                    return True, payload
+                status_events.append(
+                    SmartEvent(kind="status", status=status.decode("ascii"), data=status)
+                )
+                if status == OKAY:
+                    payload = bytes(buf)
+                    buf.clear()
+                    state["phase"] = "done"
+                    return True, payload
+                state["phase"] = "fail_length"
+            elif state["phase"] == "fail_length":
+                if len(buf) < 4:
+                    return False, b""
+                raw_length = bytes(buf[:4])
+                del buf[:4]
+                try:
+                    state["remaining"] = int(raw_length.decode("ascii"), 16)
+                except ValueError:
+                    payload = raw_length + bytes(buf)
+                    buf.clear()
+                    state["phase"] = "done"
+                    return True, payload
+                state["phase"] = "fail_reason"
+            elif state["phase"] == "fail_reason":
+                remaining = state["remaining"]
+                if len(buf) < remaining:
+                    return False, b""
+                reason = bytes(buf[:remaining])
+                del buf[:remaining]
+                status_events.append(SmartEvent(kind="fail_reason", reason=reason, data=reason))
+                payload = bytes(buf)
+                buf.clear()
+                state["phase"] = "done"
+                return True, payload
+            else:
+                payload = bytes(buf)
+                buf.clear()
+                return True, payload
+
+    def parse_server_first(self, data: bytes) -> bytes:
+        """非 host 服务的状态剥除（stateless 兜底）。"""
+        if not (data.startswith(OKAY) or data.startswith(FAIL)):
+            return data
+        # status word present; leftover may include host hex for host services
+        leftover = data[4:]
+        if ServiceClassifier.is_host_service(self.svc) and len(leftover) >= 4:
+            hex_str = leftover[:4].decode("ascii", errors="ignore")
+            if len(hex_str) == 4 and all(
+                c in "0123456789abcdefABCDEF" for c in hex_str
+            ):
+                leftover = leftover[4:]
+        return leftover
+
+    def parse_host_response(self, data: bytes) -> bytes:
+        """按 service wire shape 增量消费 host 响应，返回纯 payload bytes。
+
+        Status words consumed during this call are appended to ``_status_events``
+        for the connection logger (fail-open observer side-channel).
+        """
+        self._status_events = []
+        # host 服务 svc 变化时复位状态机
+        if self._last_host_svc != self.svc:
+            self.reset_host_state()
+            self._last_host_svc = self.svc
+        out = bytearray()
+        pos = 0
+        n = len(data)
+        response_kind = ServiceClassifier.host_response_kind(self.svc)
+        while pos < n:
+            if self.host_phase == "status":
+                need = 4 - len(self.host_status_buf)
+                take = min(need, n - pos)
+                self.host_status_buf.extend(data[pos : pos + take])
+                pos += take
+                if len(self.host_status_buf) < 4:
+                    return bytes(out)
+                status = bytes(self.host_status_buf).decode("ascii", errors="ignore")
+                self.host_status_buf = bytearray()
+                if status in ("OKAY", "FAIL"):
+                    self._status_events.append(status)
+                    self.host_track_active = status == "OKAY" and response_kind == "track"
+                    if status == "FAIL":
+                        self.host_phase = "hex"
+                    elif response_kind == "status":
+                        self.host_phase = "done"
+                    elif response_kind == "fixed8":
+                        self.host_fixed_remaining = 8
+                        self.host_phase = "fixed"
+                    elif response_kind == "forward":
+                        self.host_phase = "second_status"
+                    else:
+                        self.host_phase = "hex"
+                else:
+                    out.extend(status.encode("ascii", errors="ignore"))
+                    self.host_phase = "done"
+            elif self.host_phase == "second_status":
+                need = 4 - len(self.host_status_buf)
+                take = min(need, n - pos)
+                self.host_status_buf.extend(data[pos : pos + take])
+                pos += take
+                if len(self.host_status_buf) < 4:
+                    return bytes(out)
+                status = bytes(self.host_status_buf).decode("ascii", errors="ignore")
+                self.host_status_buf = bytearray()
+                if status in ("OKAY", "FAIL"):
+                    self._status_events.append(status)
+                    self.host_phase = "hex"
+                else:
+                    out.extend(status.encode("ascii", errors="ignore"))
+                    self.host_phase = "done"
+            elif self.host_phase == "fixed":
+                take = min(self.host_fixed_remaining, n - pos)
+                out.extend(data[pos : pos + take])
+                pos += take
+                self.host_fixed_remaining -= take
+                if self.host_fixed_remaining == 0:
+                    self.host_phase = "done"
+            elif self.host_phase == "hex":
+                need = 4 - len(self.host_hex_buf)
+                take = min(need, n - pos)
+                self.host_hex_buf.extend(data[pos : pos + take])
+                pos += take
+                if len(self.host_hex_buf) < 4:
+                    return bytes(out)
+                hex_str = bytes(self.host_hex_buf).decode("ascii", errors="ignore")
+                self.host_hex_buf = bytearray()
+                if all(c in "0123456789abcdefABCDEF" for c in hex_str):
+                    self.host_payload_remaining = int(hex_str, 16)
+                    self.host_phase = "payload"
+                else:
+                    out.extend(hex_str.encode("ascii", errors="ignore"))
+                    self.host_phase = "done"
+            elif self.host_phase == "payload":
+                if self.host_payload_remaining == 0:
+                    self.host_phase = "hex" if self.host_track_active else "status"
+                    continue
+                take = min(self.host_payload_remaining, n - pos)
+                out.extend(data[pos : pos + take])
+                pos += take
+                self.host_payload_remaining -= take
+                if self.host_payload_remaining == 0:
+                    self.host_phase = "hex" if self.host_track_active else "status"
+            else:  # "done"
+                out.extend(data[pos:])
+                pos = n
+        return bytes(out)