orbithub/docs/PROGRESS.md

# OrbitHub Progress

## Milestone 0 - Restart in C++/Qt Widgets

Status: Completed

Delivered:
- Fresh C++17/Qt6 Widgets scaffold with CMake
- `ProfilesWindow` (`QMainWindow`) with search, profile list, and New/Edit/Delete controls
- Double-click in Profiles opens a `SessionWindow`
- `SessionWindow` (`QMainWindow`) with `QTabWidget`
- Placeholder tab content showing `OrbitHub Native Surface`
- `main.cpp` wiring for application startup
- Cross-platform build command guide in `docs/BUILDING.md`

Git:
- Tag: `v0-m0-done`

## Milestone 1 - Storage and CRUD

Status: Completed

Delivered:
- SQLite integration via Qt SQL (`QSQLITE`)
- Persistent profile database bootstrap (`profiles` table)
- Profiles CRUD (New / Edit / Delete) in `ProfilesWindow`
- Search-backed profile listing from storage
- Double-click connect opens `SessionWindow` tab with selected profile name

Git:
- Tag: `v0-m1-done`

## Milestone 2 - Profile Details and Connect Lifecycle

Status: Completed

Delivered:
- SQLite schema migration for profile details (`host`, `port`, `username`, `protocol`, `auth_mode`)
- New `ProfileDialog` form for New/Edit profile workflows
- Profiles list now shows endpoint metadata and supports search by name or host
- Connect now loads complete profile details into `SessionWindow`
- Session tab lifecycle status updates (`Connecting`, `Connected`, `Failed`) via non-blocking timer flow

Git:
- Tag: `v0-m2-done`

## Milestone 3 - Real SSH Backend and Session Controls

Status: Completed

Delivered:
- Backend architecture introduced (`SessionBackend` + protocol-specific implementations)
- Worker-thread backend execution for connection lifecycle operations
- Real SSH process backend (`ssh`) with connect/disconnect/reconnect
- Unsupported protocol backend with explicit not-implemented messaging (RDP/VNC)
- Session tab controls: `Connect`, `Disconnect`, `Reconnect`, `Copy Error`
- Connect-time credential flow (password prompt / private-key path selection)
- Session event log pane with timestamps and user-friendly error mapping
- SQLite profile schema migration for `private_key_path` and `known_hosts_policy`

Git:
- Tag: `v0-m3-done`

## Milestone 4 - Interactive SSH Session UX

Status: Completed

Delivered:
- Embedded interactive SSH terminal using `KodoTerm` + vendored `libvterm`
- Native in-terminal typing for SSH sessions (no separate input box)
- ANSI/color rendering with selectable terminal themes (`Dark`, `Light`, `Solarized Dark`)
- Cross-platform SSH auth path improvements (`ssh-askpass` handling and host-key policy wiring)
- Session UX simplification: auto-connect on tab open, disconnect on tab close
- Tab-state indicators via tab color and state suffix (`Connecting`, `Connected`, `Disconnected`, `Failed`)
- Right-click tab menu for `Disconnect`, `Reconnect`, `Theme`, and `Clear`
- Collapsible events panel retained as primary diagnostics surface; inline detail/status banners removed
- Terminal behavior polish: better fixed-width font selection, cursor visibility, backspace handling, and terminal-size negotiation stability

Git:
- Tag: `v0-m4-done`

## Milestone 5 - RDP Fully Working

Status: Completed

Delivered:
- Added `RdpSessionBackend` and wired protocol selection so `RDP` no longer routes to unsupported backend
- Pivoted RDP design to embedded-only integration (no external RDP process launches)
- Implemented embedded FreeRDP client thread with connect/disconnect lifecycle and event-loop handling
- Added in-window `RdpDisplayWidget` rendering surface with frame updates from FreeRDP GDI
- Wired direct keyboard/mouse input from the embedded RDP surface to the backend
- Added RDP connect-time password prompt flow and settings wiring (host/port/user/password, desktop size)
- Added explicit profile `Domain` support for RDP auth (with `DOMAIN\username` fallback parsing)
- Updated session tab/context-menu behavior so terminal-only actions are hidden on RDP tabs
- Implemented dynamic in-session RDP resolution renegotiation from viewport resize events
- Enabled minimal FreeRDP client-channel build (`drdynvc` + `disp`) and channel loading for runtime resize support
- Added RDP profile-level security mode and performance profile options, wired into FreeRDP connection settings
- Hardened RDP lifecycle handling for disconnect/reconnect/abort flows to avoid false failure states on user-initiated stops
- Expanded RDP error/disconnect diagnostics with richer FreeRDP code mapping and raw disconnect detail events
- Pulled FreeRDP source for integration planning and API review

Git:
- Tag: `v0-m5-done`

## Milestone 6 - VNC Working (initial scope)

Status: Completed (initial scope; see gaps below)

Delivered:
- `VncSessionBackend`: an original RFB (RFC 6143) client implementation
  against `QTcpSocket` -- no permissively licensed VNC client library
  exists to vendor the way FreeRDP was for RDP (LibVNCClient is GPLv2,
  gtk-vnc is LGPL but GTK-tied), so this is from-scratch protocol code,
  threaded like `SshSessionBackend` (a `QObject` on its own `QThread`
  driven by Qt's own async socket signals) rather than `RdpSessionBackend`'s
  manual worker-thread/blocking-loop pattern
- Full connect/disconnect/reconnect lifecycle, RFB protocol-version
  negotiation (3.3/3.7/3.8 handshake differences handled explicitly),
  VNC Authentication (DES challenge-response, using OpenSSL's classic DES
  API) and no-auth security types, Raw + CopyRect framebuffer decoding,
  keyboard (Qt key -> X11 keysym mapping) and mouse/wheel input forwarding
- `VncDisplayWidget` mirroring `RdpDisplayWidget`'s scale-to-fit rendering
  and input-forwarding shape
- 45 unit tests (`tests/test_vnc_session_backend.cpp`): pure-function
  coverage (DES key prep verified against an independently documented test
  vector, keysym mapping, socket-error mapping) plus state-machine
  coverage against a scripted in-process fake RFB server (all three
  protocol-version handshake shapes, auth success/failure, unsupported
  security types, pixel-accurate Raw/Hextile/ZRLE/Tight decoding including
  a ZRLE zlib-stream-persistence test across two separate
  `FramebufferUpdate` messages, a Tight stream-reset-flag test, cursor/
  clipboard round trips, both Apple auth schemes) -- caught and fixed a
  real re-entrancy bug (`abort()` synchronously re-firing `disconnected()`
  mid-`failConnection()`, silently overwriting a specific error with a
  generic one) and a real Apple-DH wire-order bug (see below)
- Verified live against a real, independently implemented VNC server
  (TightVNC on Windows): connect with VNC Authentication, correct
  framebuffer dimensions and pixel data, clean disconnect, reconnect,
  live cursor-shape and clipboard-send checks. That particular server
  consistently chose Raw for actual framebuffer content regardless of
  which compression encodings were announced, so Hextile/ZRLE/Tight's
  real-world decode path isn't independently confirmed live -- the unit
  tests are the primary correctness evidence for those
- Per-tab VNC-only display mode toggle (tab-bar right-click ->
  `Display Mode`): `Scale to Fit` (default, matches RDP's behavior) or
  `Actual Size (Scrollbars)` -- renders the remote framebuffer at its
  native pixel size inside a `QScrollArea` so text isn't shrunk, at the
  cost of needing to scroll to see the whole screen. Reuses
  `VncDisplayWidget::renderRect()`'s existing scale-to-fit math unchanged:
  it degenerates to an exact 1:1 mapping once the widget's own bounds are
  fixed to the remote's size, so no separate rendering path was needed.
  Persisted across sessions like the terminal theme preference.
- Fixed a real, separate bug found during Apple-auth live testing:
  `SessionTab::requestConnectOptions()` never prompted for a password on
  VNC profiles at all (only SSH/RDP), so every VNC connection went out
  with an empty password regardless of what the server needed. VNC now
  gets its own prompt, with an empty password allowed through (unlike
  RDP's hard requirement) since some VNC servers are no-auth and there's
  no way to know that before the server's security-type negotiation
- Profiles can now leave the username blank for every protocol (issue
  #21): SSH/RDP previously hard-required one at profile-save time; that
  validation is gone, and `SessionTab` now asks for it at connect time
  instead (reusing the existing password-prompt bar in unmasked mode),
  same as it already does for a blank password. VNC's username is only
  ever asked for if the server's negotiated auth method actually needs
  one -- plain VNC Authentication and no-auth never do, only the two
  Apple schemes (30/33) do -- which happens *mid-connection*, after the
  backend has already picked a security type, not before connecting like
  SSH/RDP. This needed a new async request/response pair on
  `SessionBackend` (`usernameRequested()` / `provideUsername()`,
  mirroring the existing SSH host-key-confirmation pattern):
  `VncSessionBackend` pauses its state machine mid-parse (without
  consuming the already-buffered response bytes) and emits the request,
  resuming once `SessionTab` answers; cancelling fails the connection
  cleanly rather than sending Apple auth a blank username. The value is
  kept on the tab's in-memory profile copy for its lifetime, not written
  back to the saved profile
- Robustness fix: an unrecognized `FramebufferUpdate` rectangle encoding
  used to abort the connection generically; `kAnnouncedEncodings` is now
  the single source of truth for what `SetEncodings` announces and what
  the rectangle-dispatch `switch` can decode, with a regression test
  pinning that every announced encoding has a working case
- Clipboard sync (`ServerCutText`/`ClientCutText`, Latin-1 only -- no
  Unicode extension) in both directions
- Remote cursor shape sync via RFB's Cursor pseudo-encoding, mirroring
  `RdpDisplayWidget`'s cursor handling in `VncDisplayWidget`
- Hextile, ZRLE, and Tight compression encodings, in addition to Raw +
  CopyRect -- meaningfully reduces bandwidth over slower links versus Raw
  alone; Tight in particular is the encoding most real VNC servers prefer
  when the client offers it. Pure tile/pixel decode logic (including
  Tight's three filters -- Copy, Palette, Gradient) lives in
  `src/vnc_pixel_codecs.h/.cpp`, kept separate from the wire-sequencing
  state machine so it's unit-testable without a socket. ZRLE and Tight's
  Basic mode share the same "persistent zlib stream(s), decompress
  in-memory, decode synchronously" approach (Tight has 4 independent
  streams selected per-rectangle, individually reset via the
  compression-control byte's low 4 bits). Tight's JPEG sub-mode decodes
  via libjpeg-turbo directly (`find_package(JPEG REQUIRED)` ->
  `JPEG::JPEG`), not `QImage`'s own JPEG plugin, to avoid a
  packaging-dependent runtime failure mode. ZRLE/Tight link `ZLIB::ZLIB`
  (found via a fresh top-level `find_package(ZLIB REQUIRED)`, independent
  of whether vendored FreeRDP's own internal zlib usage stays enabled)
- Apple Screen Sharing authentication: two schemes, both undocumented by
  Apple. Security type 30 (Diffie-Hellman + AES, `src/vnc_apple_dh_auth.h`)
  is implemented and its wire format is confirmed correct against an
  independent, authoritative source (`neatvnc`'s `rfb-proto.h` struct
  definitions plus its full server-side verification code, cross-checked
  field-by-field: generator/key-length framing, the
  credentials-before-public-key send order -- an actual ordering bug
  caught this way and fixed -- shared-secret derivation and padding, AES
  key derivation, and the credential buffer layout all match exactly).
  Security type 33 (RSA + AES, `src/vnc_apple_rsa_auth.h`) is also
  implemented, sourced from the `asyncvnc` PyPI package, as a fallback.
  Preference when both are offered: None > AppleDH(30) > AppleRSA(33) >
  VNCAuth(2). Covered by a DH round-trip test, fake-server integration
  tests for both schemes, a preference-order test, and a regression test
  built from real bytes captured off an actual macOS server

Known gaps and open issues (see issue #3 for follow-up tracking):
- **Apple auth not yet confirmed working end-to-end against a real
  server.** Live-tested against a macOS Tahoe (26.6.2) Screen Sharing
  server with Screen Sharing correctly enabled and the connecting account
  allowed: type 33 gets rejected by the server immediately after the
  client's initial host-key request (before any credentials are even
  sent), and type 30 -- despite matching the authoritative reference
  byte-for-byte, verified via multiple independent diagnostic scripts --
  still gets rejected with a generic "Authentication or authorization
  failure" from the server. macOS Tahoe was released after this
  assistant's knowledge cutoff, so there may be a protocol or permission-
  model change specific to that OS version neither reference source
  reflects; a `screensharingd` Console.app log from the moment of
  rejection would be the next diagnostic step whenever this is picked
  back up. Until this is resolved, treat both security types as
  implemented-and-tested-in-isolation but **not verified to actually
  authenticate against a real macOS server**
- Tight's Basic compression mode always assumes zlib-compressed payloads;
  the real protocol permits the server to skip compression for very small
  (filtered byte count under ~12) payloads, which this decoder doesn't
  special-case (the exact trigger/wire-signaling for that couldn't be
  verified with confidence against the RFC text alone). In practice this
  only affects rare, tiny rectangles -- solid or near-solid tiny areas are
  virtually always sent as Fill instead -- and fails that one rectangle's
  decode cleanly (disconnects with a clear error) rather than silently
  misinterpreting it
- Tight's Gradient filter is implemented from RFC 6143's description but
  is the least exercised/confirmed of the three filters against a real
  server in this pass (most real-world Tight traffic uses Copy or
  Palette)
- Packaging for the new `libjpeg-turbo` dependency: added to
  `docs/BUILDING.md` (apt/brew/vcpkg) and the `.deb` control file's
  `Depends:` (`libjpeg-turbo8`). The Windows Inno Setup script already
  wildcards `*.dll` so no change was needed there, and macOS's
  `macdeployqt`-based bundling picks up non-system dylibs automatically.
  The Flatpak manifests (`packaging/flatpak/*.yml`) were left unchanged on
  the assumption that `org.kde.Platform`/`Sdk` 6.11 already bundles
  libjpeg-turbo (a standard Qt JPEG-plugin dependency) -- worth confirming
  the next time a Flatpak build is actually run, since it wasn't
  independently verified here
- No dynamic resize (connects at the server's native resolution; the
  `Scale to Fit`/`Actual Size` toggle changes how that fixed resolution is
  displayed locally, not what resolution is requested from the guest --
  VNC has no equivalent of RDP's MS-RDPEDISP for that)

## Milestone 7 - Cross-Platform Protocol Hardening

Status: Completed

Delivered:
- Validated SSH and RDP workflows on Linux, macOS, and Windows 11 (VNC is out
  of scope while Milestone 6 remains deferred)
- Windows: validated the full `docs/BUILDING.md` toolchain end-to-end
  (Git/CMake/Ninja/VS Build Tools with the C++ workload/vcpkg for
  Qt6-OpenSSL-zlib); documented a VS Build Tools installer gotcha where the
  actual compiler is a "recommended", not "required", component of the
  VCTools workload
- Fixed RDP keyboard input misreading punctuation keys on Linux (X11 keycode
  numbering was being treated as a PC/AT scancode; now uses FreeRDP's
  authoritative X11-keycode-to-scancode table)
- Added RDP clipboard sync (bidirectional, plain text) and RDP cursor/pointer
  shape sync (resize handles, text I-beam, etc. instead of a static arrow)
- Fixed Tab/Shift+Tab being intercepted by local UI focus navigation instead
  of reaching SSH/RDP sessions
- Fixed RDP key auto-repeat being dropped, so holding a key only ever sent a
  single keystroke to the remote machine
- Windows-specific RDP fixes: a crash on every connect attempt (FreeRDP's
  signal-handling critical section was never initialized) and a host
  resolution failure on every connect, including literal IP addresses
  (Winsock was never initialized via `WSAStartup`)
- Windows: automatic build-time deployment of Qt's platform/SQL-driver
  plugins and their runtime DLL dependencies, and marked the executable as a
  GUI (`WIN32`) app to remove a stray console window behind the UI
- Windows and macOS: proper native app icon embedding (Windows `.rc`/`.ico`
  resource; macOS `.app` bundle with `.icns`), replacing the generic default
  icon previously shown for the built executable/bundle
- macOS: fixed Edit/New Profile dialog form fields collapsing to `sizeHint`
  width due to the platform-default `QFormLayout` field growth policy

Git:
- Tag: Pending user approval (`v0-m7-done`)

## Milestone 8 - Profile and Session UX Completion

Status: Completed

Delivered:
- Added profile `tags` field to storage + schema migration and profile editor UX
- Added profile `folder_path` field + nested folder/subfolder profile view mode
- Added profile tree context actions (`New Folder`, `New Connection`) and drag-to-folder profile moves with persistence
- Added `Help -> About OrbitHub` dialog with third-party library inventory and MIT/Apache-2.0 license links
- Extended profile search to include tags/folder path and added profile sort controls (`Name`, `Protocol`, `Host`)
- Persisted profile list UX preferences (`search text`, `view mode`, protocol/tag filters, `sort order`) across app restarts
- Added protocol-aware profile validation/normalization for SSH/RDP/VNC (repository + dialog)
- Improved profile form protocol UX hints and SSH private-key path validation
- Added session events filtering and tab-context actions (`Show/Hide Events`, `Copy Events`, `Clear Events`)
- Added session diagnostics QoL: severity quick-filter (`All/Warnings/Errors`) and `Export Events` action
- Persisted session UI defaults (`terminal theme`, `events panel visibility`) for new tabs/windows
- Added profile quick filters (`Protocol`, `Tag`) with persistence to speed profile browsing

Validation:
- Local build verification passed (`cmake --build build`)
- No automated tests are currently configured in CTest

Git:
- Tag: Pending user approval (`v0-m8-done`)

## Milestone 9 - Packaging and Distribution

Status: Completed

Delivered:
- Linux `.deb` (`packaging/linux/build-deb.sh`) and Flatpak (`packaging/flatpak/build-flatpak.sh`) packages, both verified installed and launched with working SSH/RDP
- Renamed the app's reverse-DNS identity from `io.orbithub.OrbitHub` to `org.darksingularity.OrbitHub` (desktop file, AppStream metainfo, Flatpak manifest, macOS bundle identifier) to reflect a domain actually owned by the project
- Fixed Linux taskbar/panel pin matching (`StartupWMClass`) so a pinned launcher merges with its running window instead of creating a duplicate entry
- Replaced the stale, mismatched hand-authored launcher SVG with PNG icons rendered directly from the app's own `createOrbitHubAppIcon()` at each hicolor theme size
- Windows installer via Inno Setup (`packaging/windows/orbithub.iss`, `packaging/windows/build-installer.ps1`), verified installed silently and launched cleanly with no crash events
- macOS `.dmg` via `cmake --install` + `macdeployqt` + `hdiutil` (`packaging/macos/build-dmg.sh`), verified installed and launched after fixing:
  - a launch crash caused by `macdeployqt` invalidating the code signature (fixed with ad hoc re-signing)
  - a missing-library crash caused by the Linux-only `$ORIGIN` rpath token and vendored dylibs installing outside the `.app` bundle (fixed with `APPLE`-specific `@executable_path`/`Contents/Frameworks` layout)
  - the dmg showing the generic disk icon instead of the app icon
- README and `docs/BUILDING.md` Packaging sections documented for all three platforms

Validation:
- All three installers built, installed, and launched successfully with working SSH/RDP sessions
- Code signing is ad hoc only (no purchased Apple Developer ID or Windows code-signing certificate), so macOS Gatekeeper and Windows SmartScreen still show first-run warnings by design

Git:
- Tag: `v0-m9-done`
- Release: [v2026.9.8](https://git.darksingularity.org/DarkSingularity/orbithub/releases/tag/v2026.9.8) (`v2026.9.8` tag, installers for Windows/Linux/macOS)
- Release: [v2026.9.8.2](https://git.darksingularity.org/DarkSingularity/orbithub/releases/tag/v2026.9.8.2) — same-day patch fixing RDP TLS certificate verification (was fully disabled) and preparing Flatpak packaging for Flathub submission
- Release: [v2026.9.8.3](https://git.darksingularity.org/DarkSingularity/orbithub/releases/tag/v2026.9.8.3) — same-day patch adding an in-app User Guide and standalone User Guide PDF
- Release: [v2026.9.14](https://git.darksingularity.org/DarkSingularity/orbithub/releases/tag/v2026.9.14) — fixes distorted RDP text on HiDPI monitors and reduces RDP resize-related display glitches
- Release: [v2026.9.14.2](https://git.darksingularity.org/DarkSingularity/orbithub/releases/tag/v2026.9.14.2) — same-day patch fixing RDP display corruption (missing/misplaced taskbar) after resizing the session window (the client never resized its own display buffer for channel-driven RDP resizes)
- Release: [v2026.9.15](https://git.darksingularity.org/DarkSingularity/orbithub/releases/tag/v2026.9.15) — adds Import/Export for profile lists (File menu)

## Milestone 10 - v1.0 Stabilization

Status: Planned

Planned Scope:
- Run final regression and acceptance testing across all protocols
- Resolve release-blocking defects
- Finalize docs and publish v1.0 release notes/checklist