Files
SimpleRemoter/macos
yuanyuanxianganddeepseek-flash 06b93f7bdb Feat(client): complete the macOS feature set (phase 0 and 1)
Phase 0 makes implementations that already existed reachable. macOS now
declares TERMINAL, SCREEN_CLIPBOARD, PROCESS and C2C_RECV_ACK; PROCESS is a
new bit and Linux declares it too. SystemManager was dead code -- its
constructor took a second argument and it did not derive IOCPManager, so the
sub-connection skeleton could never instantiate it -- and now matches the
createHandler/OnReceive contract, so COMMAND_SYSTEM really spawns a
sub-connection (proc_listpids, SIGKILL). DataProcess always gets a NULL user,
so main.mm keeps a g_pMainClient handle and the V2 C2C receiver finally
answers TOKEN_C2C_RECV_RESULT. The server asks for SupportsTerminal() on MAC
for exec_command / terminal_* and for SupportsProcess() for kill_process, so
an old build gets "client is too old" instead of a command nobody answers;
kToolPlatforms and mcp/tools.json follow. http_probe stays win/lnx: the
terminal works on macOS, but the probe uses GNU-only base64 -w.

Phase 1 is POSIX parity. ScreenPreview captures through CGDisplayCreateImage,
scales and ships BGRX for the server to encode, and the capability is only
declared when preflight or a real capture says the display is readable.
ActivityHistory samples the frontmost layer-0 window once a second and prints
the same records as Windows and Linux. COMMAND_SCREEN_KEYFRAME_REQ is now
consumed by Linux (x264 IDR) and macOS (VideoToolbox force keyframe): the
receive thread raises a flag, the capture thread -- which owns the encoder --
consumes it and puts it back if the frame never went out. The macOS quality
level persists in NSUserDefaults because main.mm rewrites config.conf.

Linux client and Debug x64 server rebuild green; check_platform_table PASS.
Not built or run on a Mac.

Co-Authored-By: deepseek-flash
2026-11-14 13:30:50 +01:00
..

macOS Remote Desktop Client
===========================

Prerequisites:
  1. Xcode Command Line Tools: xcode-select --install
  2. CMake: brew install cmake
  3. OpenSSL (TLS transport): brew install openssl@3
     CMake 自动探测 /opt/homebrew/opt/openssl@3,也可用
     cmake .. -DOPENSSL_ROOT_DIR=/path/to/openssl 指定。

  构建目标是 Apple Silicon (arm64) 单架构:Homebrew 的 OpenSSL 只有本机架构,
  保留 x86_64 slice 会链接失败。Intel Mac 需另建 x86_64 的 OpenSSL 单独构建。

Build:
  chmod +x build.sh
  ./build.sh

Or manually:
  mkdir build && cd build
  cmake .. -DCMAKE_OSX_ARCHITECTURES=arm64 -DCMAKE_OSX_DEPLOYMENT_TARGET=11.0
  make

Run:
  ./build/bin/ghost

Configuration:
  Server address is configured in main.mm (g_SETTINGS variable).
  Modify before building if needed.

TLS Transport:
  Default is plaintext on first connect. The controller's host right-click menu
  ("TLS 传输") sends the trust anchor; the client stores it at
  ~/.config/ghost/yama-ca.pem, hot-reloads and reconnects over TLS 1.2
  (fail-closed, pinned to that anchor). "取消TLS" deletes the file and
  reconnects in plaintext. Existing sessions survive only if the transport does
  not change (replacing the certificate keeps TLS).

  Verify after building:
    otool -L build/bin/ghost | grep -i ssl   # 期望无输出:OpenSSL 已静态链接
    tail -f /tmp/ghost.log
  Startup prints one of:
    [TLS] transport on first connect: plaintext (no trust anchor)
    [TLS] transport on first connect: TLS (trust anchor present)
  Clicking "TLS 传输" should log "TLS transport switched to TLS, reconnecting";
  the host's TLS column in the online list then shows Y. "取消TLS" logs
  "switched to plaintext" and the column flips back to N.
  If the log says "trust anchor exists but failed to load", the client refuses
  to connect (fail-closed) until the anchor is fixed or removed.

Client Log:
  The controller's host right-click menu ("运行日志") sends COMMAND_QUERY_LOG;
  the client opens a sub-connection and reports its in-memory log ring
  (Logger, last 1000 lines) as TOKEN_REPORT_LOG. On macOS Mprintf (as defined
  by common/logger.h) writes that ring, and Logger mirrors the same line to
  stderr, so one Mprintf line reads identically in the dialog and in
  /tmp/ghost.log (same prefix and timestamp); content older than the
  1000-entry ring exists only in the file. main.mm logs startup, config,
  permissions, TLS, WS, connection and exit through Mprintf, so those lines
  are all visible in the dialog. The ObjC helper modules (ScreenHandler /
  H264Encoder / InputHandler / Permissions) still use NSLog, and the two
  "=== ghost ... started ===" banners are raw write(2) calls; all of those
  appear only in /tmp/ghost.log. Mprintf lines also no longer go to Apple's
  Unified Logging (NSLog in the helpers still does). The MCP tool
  get_client_log reads that same ring.

  Verify: open "运行日志" for the Mac host; the dialog should show startup
  lines such as "=== macOS Ghost Client ===", "Config loaded from ...",
  the permission results, "[TLS] transport on first connect: ...", plus
  command and heartbeat entries.

  Note: the POSIX client reports a snapshot once per connection (the Windows
  client keeps pushing increments every 3s). Closing and reopening "运行日志"
  takes a fresh snapshot.

Permissions Required:
  1. Screen Recording - System Settings > Privacy & Security > Screen Recording
  2. Accessibility - System Settings > Privacy & Security > Accessibility

  Both are TCC grants, and macOS applies them per process: a grant made while
  the app is running only takes effect after it restarts. install.sh also resets
  both (tccutil reset) and re-signs the bundle ad-hoc on every install, and a
  rebuilt binary has a new cdhash, so the old records would not match anyway --
  expect to re-grant after each update.

  When a permission is missing at startup the client requests both, and starts
  a watcher that polls CGPreflightScreenCaptureAccess / AXIsProcessTrusted --
  only for the permission that was actually missing; one that already passed
  the real capture check is not re-judged by preflight (it can report false
  negatives after re-signing). Once everything reads granted, the main loop
  disconnects and launches a fresh process ("Auto-restart: launching a fresh
  process ..."), so the new process starts with the grants in place: the old
  "grant one, kill, reopen" round trip twice becomes "tick both boxes and let
  it restart". The new process logs "(started by the auto-restart after
  permissions were granted)" at startup, and that line is what the 运行日志
  dialog shows, because the in-memory ring dies with the old process; the
  Auto-restart line itself stays in /tmp/ghost.log only. The watcher gives up
  after 15 minutes, and the auto-restart happens at most once per launch
  (guarded by GHOST_AUTO_RELAUNCHED), so if something still reports missing,
  restart manually as before. The restart disconnects first, so the controller
  sees a clean disconnect and reconnect, but any remote session in progress
  (screen, terminal, file transfer) is dropped when it happens.

Features:
  [x] Screen capture (CGDisplayCreateImage)
  [x] H264 video encoding (VideoToolbox)
  [x] Mouse control (move, click, drag, scroll)
  [x] Keyboard control (full VK code mapping)
  [x] Retina display support (coordinate scaling)
  [x] Network connection (IOCPClient)
  [x] LOGIN_INFOR (system info reporting)
  [x] Heartbeat with RTT estimation
  [x] Active window tracking
  [x] Quality level adjustment (FPS/algorithm)

Files:
  CMakeLists.txt      - Build configuration
  Permissions.h/mm    - macOS permission handling
  ScreenHandler.h/mm  - Screen capture and H264 encoding
  InputHandler.h/mm   - Mouse/keyboard simulation
  H264Encoder.h/mm    - VideoToolbox H264 encoder
  SystemManager.h/mm  - Process management
  main.mm             - Entry point, LOGIN_INFOR, heartbeat

Quality Levels:
  Level 0: 5 FPS,  Grayscale (emergency low bandwidth)
  Level 1: 10 FPS, RGB565
  Level 2: 15 FPS, H264 (default, office work)
  Level 3: 20 FPS, H264
  Level 4: 25 FPS, H264
  Level 5: 30 FPS, H264 (smooth)

Notes:
  - First frame is always raw bitmap (TOKEN_FIRSTSCREEN)
  - Subsequent frames use H264 encoding (TOKEN_NEXTSCREEN)
  - Coordinates are scaled for Retina displays automatically
  - Windows VK codes are mapped to macOS key codes