ps5dbg 0.1.0__py3-none-any.whl

ps5dbg/__init__.py

@@ -0,0 +1,39 @@
+"""ps5dbg — cross-platform Python client + CLI for the ps5debug-NG wire protocol.
+
+Public API:
+
+    from ps5dbg import PS5Debug
+
+    with PS5Debug("192.168.1.10") as ps5:    # your PS5's LAN IP
+        print(ps5.fw_version())          # -> 550
+        for p in ps5.procs():
+            print(p.pid, p.name)
+
+Host resolution: pass host= explicitly, OR set the PS5_HOST env var (then
+PS5Debug() with no argument uses it).
+"""
+from __future__ import annotations
+
+from .client import PS5Debug
+from .errors import (
+    AlreadyAttached,
+    AuthFailed,
+    BadStatus,
+    ConnectionLost,
+    PS5DbgError,
+    ProtocolError,
+    ScanAuthRequired,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "PS5Debug",
+    "PS5DbgError",
+    "ConnectionLost",
+    "ProtocolError",
+    "BadStatus",
+    "AuthFailed",
+    "ScanAuthRequired",
+    "AlreadyAttached",
+    "__version__",
+]

ps5dbg/__main__.py

@@ -0,0 +1,9 @@
+"""Allow ``python -m ps5dbg``."""
+from __future__ import annotations
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

ps5dbg/auth.py

@@ -0,0 +1,109 @@
+"""CMD_PROC_AUTH handshake for ps5debug-NG (PROTOCOL.md §1.8, auth.c).
+
+The server gates the stateful scan trio (SCAN_START/COUNT/GET) behind a
+global flag word ``g_proc_auth_state``. To set the scan-enabled bit, the
+client performs this handshake:
+
+  1. Client sends { u32 magic = 0xBB40E64D, u32 flags } (raw; magic not swapped).
+  2. Server validates magic (bitswap32(magic) == 0x7780D98E), replies CMD_SUCCESS.
+  3. Server sends u16 challenge_length (=64), then 64 challenge bytes, where
+     each challenge byte = (uint8_t)(r + r/255) and r is a 4-register LFSR
+     output (auth_lfsr_next).
+  4. Client XORs the challenge against a deterministic 256-byte keystream
+     (the same LFSR, seeded [200,300,400,500], low byte of each of the first
+     256 outputs) and sends 64 response bytes back.
+  5. On byte-exact match, server sets the flag (flags & 2 -> scan-enabled)
+     and replies CMD_SUCCESS; else CMD_DATA_NULL.
+
+This is NOT the classic xorshift128 — it is the custom 4-register LFSR in
+ps5debug-NG's auth.c. Ported bit-for-bit from that source.
+"""
+from __future__ import annotations
+
+import struct
+
+from .connection import Connection
+from .constants import CMD_PROC_AUTH_MAGIC, Cmd
+from .errors import AuthFailed
+from .wire import recv_status, recv_u16
+
+
+class _AuthLFSR:
+    """The 4-register LFSR from ps5debug-NG auth.c::auth_lfsr_next.
+
+    State: s1..s4 (u32 each). Each step applies a per-register
+    shift/mask/xor mix and returns s1 ^ s2 ^ s3 ^ s4.
+    """
+
+    __slots__ = ("s1", "s2", "s3", "s4")
+
+    def __init__(self, a: int = 200, b: int = 300, c: int = 400, d: int = 500) -> None:
+        self.s1 = a & 0xFFFFFFFF
+        self.s2 = b & 0xFFFFFFFF
+        self.s3 = c & 0xFFFFFFFF
+        self.s4 = d & 0xFFFFFFFF
+
+    def next(self) -> int:
+        s1 = self.s1
+        s2 = self.s2
+        s3 = self.s3
+        s4 = self.s4
+        # C operates in u32 throughout: every shift/xor result truncates to 32 bits.
+        # Python ints are arbitrary-precision, so we must mask the LEFT-shift
+        # operands to u32 BEFORE the xor/shift that follows, mirroring C overflow.
+        M = 0xFFFFFFFF
+        s1 = (((s1 << 18) & 0xFFF80000) ^ (((s1 ^ ((s1 << 6) & M)) & M) >> 13)) & M
+        s2 = (((s2 << 2) & 0xFFFFFFE0) ^ (((s2 ^ ((s2 << 2) & M)) & M) >> 27)) & M
+        s3 = (((s3 << 7) & 0xFFFFF800) ^ (((s3 ^ ((s3 << 13) & M)) & M) >> 21)) & M
+        s4 = (((s4 << 13) & 0xFFF00000) ^ (((s4 ^ ((s4 << 3) & M)) & M) >> 12)) & M
+        self.s1, self.s2, self.s3, self.s4 = s1, s2, s3, s4
+        return (s1 ^ s2 ^ s3 ^ s4) & M
+
+
+def build_keystream() -> bytes:
+    """Build the 256-byte keystream the server XORs challenges against.
+
+    Mirrors auth.c::auth_keystream_fill: seed [200,300,400,500], then the low
+    byte of each of the first 256 LFSR outputs.
+    """
+    lfsr = _AuthLFSR(200, 300, 400, 500)
+    return bytes(lfsr.next() & 0xFF for _ in range(256))
+
+
+def proc_auth(conn: Connection, flags: int = 2) -> None:
+    """Run the CMD_PROC_AUTH handshake.
+
+    Args:
+        conn: open Connection to the command server.
+        flags: bit field; bit 1 (value 2) enables stateful scans. Default 2.
+
+    Raises:
+        AuthFailed: if the server rejects the magic or the keystream answer.
+    """
+    body = struct.pack("<II", CMD_PROC_AUTH_MAGIC, flags)
+    conn.send_request(Cmd.PROC_AUTH, body)
+
+    # Step 2: server validates magic -> SUCCESS
+    st = recv_status(conn)
+    if not st.ok:
+        raise AuthFailed(f"server rejected auth magic (status {st.name})")
+
+    # Step 3: u16 challenge length (==64), then challenge bytes
+    chal_len = recv_u16(conn)
+    if chal_len != 64:
+        raise AuthFailed(f"unexpected challenge length {chal_len} (expected 64)")
+    challenge = conn.recv_exact(chal_len)
+
+    # Step 4: XOR challenge against the deterministic 256-byte keystream
+    # (auth.c::proc_auth_xor_keystream indexes keystream[i & 0xFF]).
+    keystream = build_keystream()
+    response = bytes(c ^ keystream[i & 0xFF] for i, c in enumerate(challenge))
+    conn._sendall(response)  # raw bytes after the initial body
+
+    # Step 5: server checks byte-exact -> SUCCESS or DATA_NULL
+    st = recv_status(conn)
+    if not st.ok:
+        raise AuthFailed(f"keystream answer rejected (status {st.name})")
+
+
+__all__ = ["build_keystream", "proc_auth"]