Files
SimpleRemoter/macos/README.txt
T
yuanyuanxianganddeepseek-flash c2b59f5d4a Feat(client): restart the macOS client once permissions are granted
macOS applies TCC grants per process, so ticking Screen Recording and
Accessibility in System Settings does nothing for a running client.
install.sh resets both with tccutil and re-signs the bundle ad-hoc, and a
rebuilt binary carries a new cdhash, so every update costs two rounds of
"grant one, kill the app, reopen it".

When a permission is missing at startup the client now starts a watcher
that polls CGPreflightScreenCaptureAccess and AXIsProcessTrusted -- only
for the permission that is actually missing, so a screen grant the startup
capture already proved is never re-judged by preflight, whose false
negatives after re-signing would otherwise block the restart forever.

Once everything reads granted the main loop disconnects and hands over to
a fresh process instead of exec'ing in place: TCC re-evaluates by pid, and
the child closes every fd above 2 before exec, so the old main and
sub-connection sockets cannot keep the server holding a dead host. The
parent exits only after the child starts; a child that dies on the spot
(exec failure, AMFI rejecting an un-re-signed binary, dyld abort) keeps
the current process alive instead, and a stop request during the hand-off
terminates it again. GHOST_AUTO_RELAUNCHED bounds this to one auto-restart
per launch, and the new process logs that it was started this way, which
is what the 运行日志 dialog shows.

Not built or run on a Mac yet.

Co-Authored-By: deepseek-flash
2026-11-14 12:52:48 +01:00

137 lines
6.3 KiB
Plaintext

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