diff --git a/CMakeLists.txt b/CMakeLists.txt index 2e73207..a55f3ff 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,6 +1,6 @@ cmake_minimum_required(VERSION 3.21) -project(OrbitHub VERSION 2026.9.16.6 LANGUAGES CXX) +project(OrbitHub VERSION 2026.9.16.7 LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) diff --git a/README.md b/README.md index 9d08397..22bc0e6 100644 --- a/README.md +++ b/README.md @@ -15,16 +15,23 @@ OrbitHub is in active development. - Milestones completed: M0-M9 - Current milestone: Milestone 10 (v1.0 Stabilization) -- Latest checkpoint tag: `v2026.9.15` -- VNC (M6) covers standard VNC Authentication and no-auth servers; see - [docs/PROGRESS.md](docs/PROGRESS.md) for known gaps (Apple Screen - Sharing auth, compression encodings, resize, cursor sync, clipboard) +- Latest published release: `v2026.9.16`; a `v2026.9.16.6` release is + drafted with several post-`.16` fixes and is pending a macOS installer + before publishing +- VNC (M6) is fully built out: Raw/CopyRect/Hextile/ZRLE/Tight encodings, + bidirectional clipboard sync, remote cursor shape sync, and both + scale-to-fit and actual-size display modes. Standard VNC Authentication + and no-auth servers (TigerVNC, x11vnc, TightVNC, etc.) work end to end. + macOS's built-in Screen Sharing uses two undocumented, reverse-engineered + authentication schemes that are implemented but not yet confirmed working + against a real macOS server — see + [docs/PROGRESS.md](docs/PROGRESS.md) for details. Progress and milestone details: - [docs/PROGRESS.md](docs/PROGRESS.md) -Latest release (installers for Windows, Linux, and macOS): -- [v2026.9.15](https://git.darksingularity.org/DarkSingularity/orbithub/releases/tag/v2026.9.15) +Latest published release (installers for Windows, Linux, and macOS): +- [v2026.9.16](https://git.darksingularity.org/DarkSingularity/orbithub/releases/tag/v2026.9.16) User Guide: - [docs/USER_GUIDE.md](docs/USER_GUIDE.md) (also available as a PDF attached to each release, and in-app via `Help -> User Guide`) @@ -50,6 +57,8 @@ An embedded RDP session in a tab. - SQLite-backed profile storage - Create, edit, delete profiles - Protocol-aware profile validation (SSH/RDP/VNC) +- Username is optional on any protocol's profile — if left blank, OrbitHub + asks for one inline at connect time instead of requiring it up front - Profile search and sorting - Tags support - Folder/subfolder support @@ -58,13 +67,20 @@ An embedded RDP session in a tab. - New Folder - New Connection - Drag-and-drop profile moves between folders with persistence +- Import/Export of the whole profile list as JSON, and one-way import from + mRemoteNG connection XML files (passwords are never imported) ### Session Experience - Multi-tab session window - Auto-connect on tab open - Disconnect on tab close -- Session state indicators on tabs +- Session state indicators on tabs, colored distinctly per state + (connecting/connected/disconnected/failed) +- A tab awaiting a username/password prompt is clearly marked — its title + gets a "(Needs input)" suffix and its tab color changes — even when it + isn't the tab currently in view, and the inline prompt itself uses a + solid highlighted banner rather than blending into the rest of the tab - Timestamped event log with filtering and export ### SSH @@ -82,14 +98,36 @@ An embedded RDP session in a tab. - Domain-aware authentication support - RDP security/performance profile options +### VNC + +- Embedded in-window VNC rendering surface (no external launcher) +- Raw, CopyRect, Hextile, ZRLE, and Tight rectangle encodings +- Bidirectional clipboard sync +- Remote cursor shape sync +- Scale-to-fit and actual-size (scrollable) display modes, toggled + per-tab and remembered across sessions +- Standard VNC Authentication and no-auth servers (TigerVNC, x11vnc, + TightVNC, etc.) +- No dynamic remote-desktop resizing (VNC has no real equivalent of RDP's + MS-RDPEDISP) +- macOS Screen Sharing's two undocumented Apple auth schemes are + implemented but not yet confirmed working against a real macOS server — + see [docs/PROGRESS.md](docs/PROGRESS.md) + ### App UX - App icon and themed About dialog +- In-app User Guide (`Help -> User Guide`), matching + [docs/USER_GUIDE.md](docs/USER_GUIDE.md) - `File` menu: - New Profile - New Folder + - Import Profiles... + - Export Profiles... + - Import from mRemoteNG... - Quit - `Help` menu: + - User Guide - About OrbitHub ## Build and Run @@ -140,6 +178,9 @@ Core dependencies: - Qt 6 (Widgets, SQL) - CMake 3.21+ - C++17 toolchain +- OpenSSL (RDP/VNC transport security and Apple VNC auth) +- zlib (VNC's ZRLE and Tight encodings) +- libjpeg-turbo (VNC's Tight encoding's JPEG sub-mode) Protocol/runtime dependencies: - SSH client (`ssh`) available on `PATH` for SSH sessions @@ -176,12 +217,19 @@ See in-app `Help -> About OrbitHub` for license links and third-party inventory. - `src/` - application source code - `docs/` - build guide, spec, and progress tracking +- `packaging/` - per-platform installer/package build scripts +- `tests/` - CTest unit/integration tests and fixtures +- `tools/` - standalone build-time tools (e.g. the User Guide PDF generator) - `third_party/` - vendored third-party dependencies - `build/` - local build output (generated) +- `dist/` - packaged installer/deb/flatpak/dmg output (generated) ## Notes - Passwords are requested at connect time and are not stored in the profile database. +- A profile's username is optional for every protocol; if left blank, + OrbitHub asks for one inline the first time you connect that profile. - VNC support covers standard VNC Authentication and no-auth servers (e.g. TigerVNC, x11vnc, - TightVNC); it doesn't yet reach macOS's built-in Screen Sharing server, which uses a different - authentication scheme (see docs/PROGRESS.md, Milestone 6). + TightVNC). macOS's built-in Screen Sharing server uses two undocumented, reverse-engineered + authentication schemes that are implemented but not yet confirmed working against a real + macOS server (see docs/PROGRESS.md, Milestone 6). diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md index 8107f0c..d72db51 100644 --- a/docs/USER_GUIDE.md +++ b/docs/USER_GUIDE.md @@ -1,16 +1,19 @@ ## Introduction OrbitHub is a native desktop application for organizing connection profiles -and launching SSH and RDP sessions from one place, in a single tabbed +and launching SSH, RDP, and VNC sessions from one place, in a single tabbed window. It runs on Windows, Linux, and macOS. This guide covers everyday use: creating and organizing profiles, -connecting over SSH and RDP, managing active sessions, and what to do when -something goes wrong. It does not cover installation or building from +connecting over SSH, RDP, and VNC, managing active sessions, and what to do +when something goes wrong. It does not cover installation or building from source — see the project's `README.md` and `docs/BUILDING.md` for that. -VNC support is planned but not yet implemented; profiles can be tagged for -it, but connecting will show an "unsupported protocol" message for now. +VNC support covers standard VNC Authentication and no-auth servers +(TigerVNC, x11vnc, TightVNC, and similar). macOS's built-in Screen Sharing +server uses two undocumented, reverse-engineered authentication schemes +that are implemented but not yet confirmed working end to end against a +real macOS server — see [Connecting via VNC](#connecting-via-vnc). ## Getting Started @@ -43,15 +46,19 @@ A profile stores everything needed to reach one remote host. Open **New** - **Name** — a label for the profile; shown on its tab and in the list. - **Host** — hostname or IP address. -- **Port** — defaults to `22` for SSH, `3389` for RDP. -- **Username** — the account to log in as. +- **Port** — defaults to `22` for SSH, `3389` for RDP, `5900` for VNC. +- **Username** — the account to log in as. Optional for every protocol — + leave it blank and OrbitHub asks for one inline the first time you + connect that profile, the same way it already asks for a password. (VNC + servers mostly ignore username entirely; macOS Screen Sharing is the + exception and requires one — see + [Connecting via VNC](#connecting-via-vnc).) - **Domain** — Windows domain for RDP logins (leave blank for local/ - workgroup accounts or SSH profiles). + workgroup accounts, SSH, or VNC profiles). - **Tags** — free-form, comma-separated labels for filtering and grouping (e.g. `prod, linux, db`). - **Folder** — where the profile lives in the Folders view. -- **Protocol** — `SSH`, `RDP`, or `VNC` (VNC is accepted but not yet - connectable — see Introduction). +- **Protocol** — `SSH`, `RDP`, or `VNC`. Fields below Protocol change based on what you pick: @@ -63,6 +70,9 @@ policy means. **RDP**: **RDP Security** and **RDP Performance** — see [Connecting via RDP](#connecting-via-rdp). +**VNC** has no protocol-specific fields beyond Host/Port/Username above — +see [Connecting via VNC](#connecting-via-vnc). + Passwords are never saved in the profile — OrbitHub asks for them each time you connect (unless you've set up private-key SSH auth, which needs no password to be entered per-connection if the key itself has none). @@ -85,6 +95,24 @@ Combine both with the **Search** box (matches name, host, folder path, or tags) and the **Sort** control (Name / Protocol / Host) to find what you need quickly even with a large profile list. +## Importing and Exporting Profiles + +The **File** menu has three options for moving profiles in or out of +OrbitHub: + +- **Export Profiles...** — saves your entire profile list, including + folder structure and tags, to a JSON file. Passwords are never included, + since OrbitHub never stores them in the first place. +- **Import Profiles...** — reads that same JSON format back in, recreating + folders and profiles. Existing profiles aren't touched; entries missing + a name or host are skipped and reported in the summary. +- **Import from mRemoteNG...** — reads an mRemoteNG connections `.xml` + file and creates equivalent OrbitHub profiles. Passwords are never + imported — you'll be prompted the first time you connect each imported + profile, same as a new one. Connections using a protocol OrbitHub + doesn't support are skipped and listed in the import summary. This is a + one-way conversion; there's no export back to mRemoteNG's format. + ## Connecting via SSH Double-clicking an SSH profile opens a new tab with an embedded, fully @@ -93,6 +121,8 @@ emulator. A **theme** selector lets you switch between `Dark`, `Light`, and `Solarized Dark`; your choice is remembered for future sessions. **Authentication.** Set in the profile itself: +- **Username** — if left blank in the profile, OrbitHub asks for one + inline the first time you connect, right alongside the password prompt. - **Password** — OrbitHub prompts for a password each time you connect. It is never stored. - **Private Key** — point at a key file (via the profile's Browse button); @@ -105,7 +135,7 @@ silently impersonating a host you've connected to before: | Policy | Behavior | |---|---| | `Ask` | Prompts you to confirm trust the first time a host is seen, and on any later change. Recommended default. | -| `Accept-new` | Silently trusts a host the first time it's seen, but still stops and warns if a previously-trusted host's key later changes. | +| `Accept New` | Silently trusts a host the first time it's seen, but still stops and warns if a previously-trusted host's key later changes. | | `Strict` | Never trusts an unknown host automatically — the connection fails until you've manually confirmed the host key some other way. | | `Ignore` | Skips host-key checking entirely. Only use this for throwaway/test environments — it removes protection against on-path attacks. | @@ -123,7 +153,8 @@ window renegotiates the remote resolution to match. Clipboard content syncs between your machine and the remote session automatically. **Authentication** uses the profile's Username/Domain fields; OrbitHub -prompts for the password at connect time. +prompts for the password at connect time, and for a username too if the +profile's own Username field was left blank. **RDP Security** controls which transport-security layer is used to negotiate the connection: @@ -151,6 +182,51 @@ expected — you rotated the server's certificate yourself — reconnecting after clearing the old entry from FreeRDP's certificate store will trust the new one. +## Connecting via VNC + +VNC sessions render in an embedded display surface inside the tab, like +RDP — no external VNC client window opens. + +**Authentication.** VNC servers don't have a fixed username/password +convention the way SSH and RDP do, so OrbitHub always prompts for a +password at connect time (leave it blank if the server doesn't require +one — no-auth servers exist and are supported). Most VNC servers ignore +username entirely; the one common exception is **macOS's built-in Screen +Sharing**, which does require one — see the Apple Screen Sharing note +below if you're connecting to a Mac. + +**Display mode.** Right-click a VNC session's tab to choose: +- **Scale to Fit** (default) — the whole remote screen is scaled to fit + the tab, like RDP. +- **Actual Size (Scrollbars)** — renders at the remote's native pixel + size, with scrollbars for panning. Useful when scaling would make small + text illegible. + +Your choice is remembered across sessions. Unlike RDP, VNC has no way to +renegotiate the remote screen's resolution to match your window size — +resizing the OrbitHub window changes how much of a scaled-down remote +screen you can see, not the remote resolution itself. + +**Clipboard and cursor.** Clipboard content syncs between your machine and +the remote session in both directions, and the remote's cursor shape (not +just position) is mirrored locally when the server supports it. + +**Encodings.** OrbitHub negotiates whichever of Raw, CopyRect, Hextile, +ZRLE, or Tight the server prefers — this is automatic and requires no +configuration; more efficient encodings (Tight, ZRLE) simply mean better +performance over slower links. + +**Apple Screen Sharing (macOS).** macOS's built-in Screen Sharing server +doesn't use a standard, documented VNC authentication method — it uses two +undocumented schemes that OrbitHub implements based on reverse-engineering +work, but neither is yet confirmed to authenticate successfully against a +real macOS server. If you're connecting to a Mac's Screen Sharing and see +an authentication failure, this is the likely cause rather than a wrong +username or password; check +[docs/PROGRESS.md](https://git.darksingularity.org/DarkSingularity/orbithub/blob/main/docs/PROGRESS.md) +(Milestone 6) for the current status, or a VNC server you install yourself +on the Mac (e.g. TigerVNC) as a workaround in the meantime. + ## Managing Sessions Every open connection lives in its own tab in the same window, alongside @@ -158,6 +234,14 @@ the Profiles tab. A tab's title and a colored state indicator show whether it's connecting, connected, disconnected, or failed. Closing a tab disconnects that session; opening a profile again starts a fresh one. +**When OrbitHub needs a username or password from you**, the tab shows a +highlighted prompt bar with a Connect/Cancel pair — this happens for a +blank-username SSH/RDP profile, any RDP or SSH password prompt, and any +VNC connection (VNC always asks for a password, even if blank). If that +prompt appears on a tab you're not currently viewing, the tab's title +gets a `(Needs input)` suffix and its color changes so it's easy to spot +among several open sessions. + Each session tab includes a collapsible **event log** beneath the connection surface — a timestamped record of connection state changes, warnings, and errors for that session. Controls above the log let you: @@ -176,8 +260,9 @@ settings screen — they're saved automatically as you use the app: - Profile list: search text, view mode (List/Folders), Protocol/Tag filters, and sort order. -- Session tabs: terminal theme choice, and whether the events panel is - shown or hidden for new tabs. +- Session tabs: terminal theme choice, whether the events panel is shown + or hidden for new tabs, and VNC display mode (Scale to Fit / Actual + Size). Profile data itself (names, hosts, tags, folder structure, and so on) is stored in a local SQLite database — see the README for its exact path on @@ -209,10 +294,23 @@ certificate is replaced. **SSH: connection hangs at "Ask" waiting for host-key trust** — check that policy's behavior under -[Connecting via SSH](#connecting-via-ssh); switching to `Accept-new` avoids +[Connecting via SSH](#connecting-via-ssh); switching to `Accept New` avoids the prompt for genuinely new hosts while still protecting against a later key change. +**VNC: "Authentication or authorization failure"** — for most VNC +servers this means a wrong password. If you're connecting to **macOS +Screen Sharing** specifically, this is the expected result right now — see +the Apple Screen Sharing note under +[Connecting via VNC](#connecting-via-vnc). + +**VNC: connection closes immediately with no prompt** — some servers +(including macOS Screen Sharing in some configurations) close the +connection outright rather than negotiating; confirm the server is +actually running and reachable on the profile's port (default `5900`), +and that no allowlist on the server side is blocking your account or +machine. + If none of this covers what you're seeing, a session's exported event log (see Managing Sessions) is the most useful thing to include when asking for help or filing an issue.