tabby-rdp 0.5.0 → 0.5.2

package/README.md

@@ -20,8 +20,8 @@ Linux and Windows, side by side, through the SSH connections you already have.
 ---
 
 tabby-rdp is a plugin for the [Tabby](https://tabby.sh) terminal. Press a key in an SSH tab and the machine's desktop
-appears in its place; press it again and you're back at the shell. Everything travels inside the SSH connection:
-nothing is opened on the network, and nothing has to be installed on the remote machine beforehand.
+appears in its place; press it again and you're back at the shell. SSH desktops use the connection you already have;
+remote desktop profiles can also connect directly or through an RD Gateway.
 
 - **Linux desktops without a monitor or a login.** The plugin starts a headless GNOME session for your SSH user with
   GNOME Remote Desktop, on the fly, without root. A server in a rack works as well as a workstation.
@@ -40,8 +40,8 @@ nothing is opened on the network, and nothing has to be installed on the remote
 - **`desk`:** type `desk` in the console and the same shell, with its history and running programs, moves into a
   terminal on the desktop.
 
-Everything is in **Settings › Remote Desktop**, in tabs: getting started and the shortcuts, the settings, the name
-overlay, the desktops and certificates the plugin keeps, saved accounts, and troubleshooting.
+Everything is in **Settings › Remote Desktop**: Getting started, Settings, Overlay, Desktops, Accounts and Updates.
+The **Troubleshooting** link at the top opens the [troubleshooting guide](TROUBLESHOOTING.md).
 
 The remote desktop itself is [IronRDP](https://github.com/Devolutions/IronRDP)'s web client, running inside Tabby.
 Making it work with GNOME took fixes in IronRDP, which we contribute upstream ([below](#built-on-ironrdp)).
@@ -49,11 +49,13 @@ Making it work with GNOME took fixes in IronRDP, which we contribute upstream ([
 ## Contents
 
 - [Install](#install)
+- [Versions and recovery](#versions-and-recovery)
 - [Use](#use)
 - [Features](#features)
 - [Windows and other desktops behind a host](#windows-and-other-desktops-behind-a-host)
 - [Remote desktop profiles](#remote-desktop-profiles)
 - [Saved accounts](#saved-accounts)
+- [Clipboard](#clipboard)
 - [Shared folders](#shared-folders)
 - [Several desktops in one tab](#several-desktops-in-one-tab)
 - [VMs on a host](#vms-on-a-host)
@@ -77,6 +79,24 @@ Or from a terminal, into Tabby's plugin folder (on macOS `~/Library/Application
 npm install tabby-rdp
 ```
 
+## Versions and recovery
+
+Open **Settings › Remote Desktop › Updates** to manage the installed version:
+
+- **Stable** is the default. **Preview** also offers beta releases and release candidates when available.
+- Automatic checks look for updates once a day. **Check now** checks manually; installation is always your choice.
+- Choose an exact compatible version, **Return to stable**, or **Restore previous version** after an installation
+  from this page. Version changes currently support **0.5.1 or newer**.
+- **Uninstall plugin…** removes the package. **Manage in Tabby…** opens Tabby's plugin controls to disable it.
+  Saved connections, settings, passwords and remote setup are kept.
+
+The confirmation dialog stays open during installation or removal and shows progress, elapsed time and the verified
+result. After success, close remote desktops and restart Tabby. Until then, Updates shows the running version and
+the installed version waiting for restart. Preferences and version history stay on this computer.
+
+See [troubleshooting and recovery](TROUBLESHOOTING.md#recovery) if the plugin cannot load or you want to clean up saved
+data or remote helpers.
+
 ## Use
 
 Open an SSH tab to a Linux machine with GNOME, and:
@@ -93,14 +113,22 @@ running in the background until you disconnect or close the tab.
 
 A machine without GNOME but with [xrdp](https://github.com/neutrinolabs/xrdp) running (the usual RDP server for KDE,
 XFCE, MATE and the rest) gets xrdp's desktop instead: sign in with your Linux password, which the plugin can remember
-in the system keychain. A machine with both keeps GNOME as the tab's desktop and, once that has been opened, also
+in the system keychain. xrdp takes the password without Network Level Authentication, and that the machine's desktop
+is xrdp is the machine's own word, so the first sign-in asks before the password goes; the answer is kept with that
+desktop's certificate. A machine with both keeps GNOME as the tab's desktop and, once that has been opened, also
 offers **Open \<host\> desktop (xrdp)** in its menus.
 
 It also works in a plain local terminal where you typed `ssh host` (macOS and Linux), as long as that host accepts
 your key without a password prompt. And in an SSH tab where you typed `ssh` on to another machine: **Desktop** there
 opens that machine's desktop, going through the first, as long as the first can log in to it by itself (a key there,
 or agent forwarding). So one pane of a split can show the first machine's desktop, and the other, after `ssh other`,
-that machine's.
+that machine's. Desktop asks which desktop you mean, the first machine's or that one's, this time or **from now on**:
+which `ssh` runs in a console is the first machine's to say. Chosen from now on, that machine's desktop opens at once
+the next times. A machine reached this way keeps its saved sign-in and certificate under the machine it goes through,
+apart from the same machine opened in a tab of its own, and only its own desktop opens that way (VMs aren't looked for
+there): desktops added behind a host open in tabs connected to that host. A "from now on" is taken back by removing its
+entry from `remoteDesktop.nestedSSH` in Tabby's config file (Settings › Config file): `via` is the tab's host,
+`destination` the name typed after `ssh`.
 
 One desktop per account: a second tab to the same `user@host` switches to the tab that has it open, rather than
 connecting again.
@@ -109,14 +137,14 @@ connecting again.
 
 | | |
 |---|---|
-| **Clipboard** | Copy and paste text and images in both directions. |
-| **Files** | Copy files or folders in Finder and press ⌘V on the desktop, or drop them onto it, or use **Remote Desktop › Send files…** in the pane's menu; they paste in Files or Explorer. Files copied on the remote offer **Save to Downloads**. |
+| **Clipboard** | Copy and paste text and images in both directions; or only from the remote desktop to this computer, or not at all, for every desktop or for some: [below](#clipboard). |
+| **Files** | Copy files or folders in Finder and press ⌘V on the desktop, or drop them onto it, or use **Remote Desktop › Send files…** in the pane's menu; they paste in Files or Explorer. A copied folder's links go along only when they lead somewhere inside it. Files copied on the remote offer **Save to Downloads**, which saves them there (never into a folder that was there before), marks them as downloaded, as a browser does (so macOS can ask before an app among them first opens), and takes invisible characters that could disguise a name out of it. They go the ways the [clipboard](#clipboard) does. |
 | **Shared folders** | Folders from this computer as drives on the remote desktop (`\\tsclient\<name>` in Explorer), read-write or read-only, for working with files in place: [below](#shared-folders). Windows (and xrdp with FUSE). |
 | **Several desktops in one tab** | Paste to all of them, type into all of them, and see which is which: [below](#several-desktops-in-one-tab). |
 | **RD Gateway** | Desktops behind a Remote Desktop Gateway: the profile names the gateway, and the connection goes through it over HTTPS: [below](#through-an-rd-gateway). |
 | **VMs on a host** | The host's VMs with a desktop, ready to open: [below](#vms-on-a-host). |
 | **Sound** | The remote desktop's sound plays locally. |
-| **Microphone** | Optional (off by default): an app on the remote desktop that records, such as a call, gets your microphone. It is only captured while the app records, with an indicator in the corner of the desktop. |
+| **Microphone** | Optional (off by default): an app on the remote desktop that records, such as a call, gets your microphone. It is only captured while the remote asks for it, with a red dot in the corner of the desktop and a red microphone in Tabby's header, which stays also while the desktop is hidden or its tab is in the background (in full screen, where Tabby hides its header, it shows at the top of the window, in the middle): click it to show that desktop, or to stop sending the microphone there. Stopped, a desktop gets it again only once **Send the microphone** is turned back on in its menu, or Tabby restarts, its reconnects included; the same switch keeps it from a desktop beforehand. A desktop that starts receiving it while it isn't showing also brings a note. |
 | **Resize** | The remote resolution follows the pane as you resize the window or split it. Or reconnect at the new size, or keep a fixed resolution, scaled to fit or at actual size with scroll bars. |
 | **Retina** | Optionally renders at device pixels, with the remote's UI scaled to match (GNOME and Windows alike), for sharp text. For all desktops, or only some. |
 | **Keyboard on macOS** | ⌘C, ⌘V, ⌘Z and the rest work as on a Mac; tapping ⌘ alone is the Windows key, and ⌃⌘ with a key is the Windows key with it (⌃⌘R for Win+R). Tabby's own shortcuts stay out of the way while a desktop is showing, except switching tabs and returning to the console. |
@@ -127,19 +155,24 @@ connecting again.
 | **Reconnecting** | After sleep or a network change, the desktop reconnects by itself once the connection is back. |
 | **Sign-in** | GNOME desktops need none: the plugin manages their credentials. Windows and xrdp desktops ask for the account once and can remember it, in Tabby's Vault when that is on and in the system keychain otherwise; **Sign in again…** in the menu replaces it. Desktops that share an account can use a [saved account](#saved-accounts), whose password is kept once. |
 | **Shortcuts** | Switching between the desktop and the console, view only, a screenshot, Ctrl+Alt+Del, typing into or pasting to all desktops of a tab, the connection status and Disconnect each have a hotkey, set on the settings page or in Tabby's Hotkeys. They work while the desktop has the keyboard; a key another hotkey has is refused. |
-| **Certificates** | GNOME desktops accept only the certificate the plugin made for them. Windows and xrdp desktops remember theirs on first use and ask before accepting a different one. |
-| **Passwords stay with servers that know them** | Windows signs in with Network Level Authentication: a proof both ways, where the password only reaches a server that knows it already. A Windows desktop whose server doesn't use it would get the password as it is, so the connection stops and asks first, before anything is sent. xrdp signs in that way by design, so desktops of the xrdp kind aren't asked about. |
+| **Certificates** | GNOME desktops accept only the certificate the plugin made for them. A desktop you connect to directly, and an RD Gateway, connect without a question when their certificate is valid for their name by the certificate authorities this computer trusts; any other is shown, with why it can't be verified, its fingerprint and what it says of itself (whom it was issued to and by, and its dates), and connected only once you trust it. What it says of itself is its own word, unless its chain leads to an authority this computer trusts (another machine's certificate then shows that machine's name) and the TLS library didn't refuse it for a reason of its own (a limit set on the authority, say): an issuer you would expect there proves nothing, since anyone can make a certificate that names it; only the fingerprint, checked with whoever runs the server some other way, does. Desktops behind an SSH host remember theirs on first use. A different certificate later stops the connection and asks, but for one an authority vouches for in place of one it vouched for (a renewal); and one remembered on an authority's word is asked about again once it no longer validates. |
+| **Passwords stay with servers that know them** | Windows signs in with Network Level Authentication: a proof both ways, where the password only reaches a server that knows it already. A Windows desktop whose server doesn't use it would get the password as it is, so the connection stops and asks first, before your password or user name is sent. xrdp signs in that way by design, so desktops you made xrdp ones aren't asked about; one that is xrdp only by a host's word (a VM it lists, a machine reached through it, the host's own desktop) is asked about once. The answer is kept with the certificate of the server you gave it for: another certificate, a new address or a forgotten certificate asks again. |
 
 <p align="center"><img src="docs/images/files.png" width="760" alt="A file copied on the remote desktop, offered for saving"></p>
 
 ## Windows and other desktops behind a host
 
 An SSH host can lead to other desktops it can reach, such as a Windows VM on the same machine. In that host's menu,
-choose **Desktops › Add a desktop behind \<host\>…** and enter a name, the address as seen from the host, and optionally the
-user name and domain. It opens right away, and from then on appears under **Desktops** in the host's menu.
-**Settings › Edit a desktop** changes one (its saved password, sharpness and remembered certificate
-follow a new address; a new user name forgets the saved password), and **Remove a desktop** removes one, along with
-its saved password and remembered certificate.
+choose **Desktops › Add a desktop behind \<host\>…** and enter a name, the address as seen from the host, and
+optionally the user name and domain. It opens right away, and from then on appears under **Desktops** in the host's
+menu. **Settings › Edit a desktop** changes one (its saved password, sharpness and remembered certificate follow a new
+address, unless a desktop there has its own, the certificate staying at the old address too; and where a desktop at the
+new address is known already, its certificate remembered, the saved password doesn't follow either, since that desktop
+would sign in with it unasked: the edited one asks; a saved password follows only along with its desktop's remembered
+certificate, and is forgotten without one; a new user name, domain, account or gateway forgets the saved password), and
+**Remove a desktop** removes one, along with its saved password and remembered certificate (a Hyper-V VM's are its
+host's, which its other VMs use, and stay). What is kept for a desktop is found by its address: an edit or a removal
+applies to what desktops at that address behind other hosts have too.
 
 <p align="center"><img src="docs/images/windows.png" width="760" alt="A Windows 11 desktop, reached through an SSH host, in a Tabby tab"></p>
 
@@ -149,23 +182,28 @@ In Tabby's config file, they look like this:
 remoteDesktop:
   desktops:
     - name: Windows VM
-      via: buildhost            # the SSH host: alias, hostname, user@hostname or user@hostname:port
+      via: buildhost            # the SSH host: alias, hostname, user@hostname or user@hostname:port (not a machine
+                                #   reached with ssh typed in another host's console)
       host: 192.168.122.20      # the RDP server as seen from that host
       port: 3389
       kind: windows             # or xrdp (a Linux desktop served by xrdp), or gnome
       username: alice           # optional; DOMAIN\user works too
       domain: CORP              # optional
       wake: { vm: win11 }       # optional: start it when it's off (see below)
+      clipboard: fromRemote     # optional: its own clipboard sharing, both, fromRemote or off (see Clipboard)
 ```
 
 The connection runs through the same SSH connection; the Windows machine needs Remote Desktop turned on, and nothing
 else.
 
-The first connection to a desktop remembers its TLS certificate, without asking (in Tabby's config, under
-`remoteDesktop.trustedCertificates`). If a later connection meets a different one, the plugin stops before signing in
+The first connection to a desktop behind a host remembers its TLS certificate, without asking (in Tabby's config,
+under `remoteDesktop.trustedCertificates`): the way there runs inside SSH. SSH vouches for the host, though, not for
+what answers behind it: a host you don't trust, or something on its network, could answer that first connection, so
+make it where you trust both. If a later connection meets a different certificate, the plugin stops before signing in
 and shows both fingerprints, with **Trust the new certificate** and **Cancel**. Reinstalling Windows or renewing its
 certificate changes it; if neither happened, something else is answering at that address. Automatic reconnects stop at
-the same question.
+the same question. A desktop allowed to sign in without Network Level Authentication is asked about that again once a
+new certificate is trusted, or its address changes.
 
 **An SSH host that is itself Windows** (with OpenSSH Server): its own desktop is Windows' Remote Desktop, at
 127.0.0.1:3389 as seen from the host. The plugin finds this out the first time you open the desktop there, and asks
@@ -196,15 +234,26 @@ keychain, certificates, resize, sharpness, clipboard, files, sound, microphone,
 and reconnecting work as in SSH tabs. After **Disconnect**, the tab offers **Connect**. In the profile selector you can
 also type `user@host:port` and pick **Quick connect (REMOTE DESKTOP (RDP))**.
 
-**Import an .rdp file…** (in the menu's **Settings**, or **Remote desktop: import an .rdp file…** in Tabby's
-command palette) makes such a profile from a file saved by Remote Desktop Connection or handed out by an admin: its
-address, port, user name and domain, named after the file, and its [RD Gateway](#through-an-rd-gateway) when it
-connects through one; a `desktopscalefactor` of 150 or more sets that desktop's sharpness to Retina. Settings the
-plugin doesn't apply (sound left on the remote, a fixed window size, drive or printer redirection, several monitors)
-are named in a note on import, so the desktop's behaviour isn't a surprise. Nothing in a file runs here, and a
-program it names to start on the remote isn't asked for. What a file does decide is where you connect, so importing
-asks first, naming the address, the gateway and the account it leads to: what you sign in with goes there, and once
-signed in that desktop gets the clipboard and the folders you share. **Add only** adds the profile without connecting.
+**Import an .rdp file…** (in the menu's **Settings**, or **Remote desktop: import an .rdp file…** in Tabby's command
+palette) makes such a profile from a file saved by Remote Desktop Connection or handed out by an admin: its address,
+port, user name and domain, named after the file, and its [RD Gateway](#through-an-rd-gateway) when it connects
+through one; a `desktopscalefactor` of 150 or more sets that desktop's sharpness to Retina, and
+`redirectclipboard:i:0` turns its [clipboard](#clipboard) off (a file can't turn it on). Settings the plugin doesn't
+apply (sound left on the remote, a fixed window size, drive or printer redirection, several monitors) are named in a
+note on import, so the desktop's behaviour isn't a surprise. Nothing in a file runs here, and a program it names to
+start on the remote isn't asked for. What a file does decide is where you connect, so importing asks first, naming the
+address, the gateway and the account it leads to: what you sign in with goes there, and once signed in that desktop
+gets the folders you share, the clipboard as far as its setting goes, and your microphone when it asks for it if that
+setting is on. When the file names a gateway, the note adds that the gateway is signed in to first and is given a
+proof of your password. An imported profile never takes a saved account by itself, whatever its group's defaults say,
+nor a gateway account (whose proof would go to the gateway the file named) or a kind (an xrdp one would get the
+password without Network Level Authentication, unasked): it is a Windows desktop that asks for its sign-in, unless a
+password was saved already for that address reached the same way (through the same gateway, or none; not one version
+0.5.0 saved there for a desktop reached through a gateway, which is forgotten). The address, gateway, user name and
+domain are shown faithfully (an international name as the punycode it resolves to, so a look-alike can't pose as a
+name you know; one with characters that don't show isn't imported). **Add only** adds the profile without connecting.
+A file whose address, user name, domain (in any case) and gateway a profile has already opens that profile instead; when
+the file turns the clipboard off and that profile shares it, you are asked first whether to turn it off there.
 
 Its **Connect** setting can name an SSH profile instead of connecting directly. The address is then as that host sees
 it, and opening the profile opens that SSH tab and shows the desktop over it once SSH is connected. Such a desktop is
@@ -225,11 +274,31 @@ profiles:
       via: ''                   # or the id of an SSH profile to go through
       gateway: ''               # or an RD Gateway to go through: rdgw.example.com, or host:port
       gatewayAccount: ''        # or a saved account's id, for a gateway that takes another account
+      clipboard: off            # optional: its own clipboard sharing, both, fromRemote or off; '' for the setting's.
+                                # Left out, its group's and Tabby's profile defaults decide (see Clipboard)
 ```
 
-A direct connection is a plain TCP connection from this computer, encrypted with TLS like any RDP client's. The
-server's certificate is remembered on the first connection and checked on every later one, as for desktops behind a
-host (above).
+A direct connection is a plain TCP connection from this computer, encrypted with TLS like any RDP client's, with nothing
+else between the desktop and the network on the way. So its certificate is checked as a browser checks a website's: one
+valid for the desktop's name (or address) by the certificate authorities this computer trusts connects without a
+question (an organisation's desktops often have one). Any other, such as the self-signed one most RDP servers make for
+themselves, is shown on the first connection before anything of your sign-in is sent: the address, why it can't be
+verified, its SHA-256 fingerprint and what it says of itself (whom it was issued to and by, and its dates), with **Trust
+the certificate** and **Cancel** (what Enter picks). Why it can't be verified is Tabby's own reading of the certificate
+(self-signed, from an authority this computer doesn't trust, issued for another name, expired, …), not only what the TLS
+library reported last, which whoever makes the certificate can choose. What it says of itself is its own word, which
+nothing has checked, unless its chain leads to an authority this computer trusts (where another machine's certificate
+shows that machine's name) and the TLS library didn't refuse it for a reason of its own (a limit set on the authority,
+say): an issuer you would expect there proves nothing. Check the fingerprint with whoever runs the desktop, some other
+way than this connection, before you trust it. For a server without Network Level Authentication, the question says that
+signing in would send it your password itself. Once trusted it is remembered, and a different
+certificate later stops the connection as above, whatever vouches for it. One an authority vouched for may be renewed: a
+replacement it vouches for too connects, and the desktop's log says so. The same one connects only while that holds:
+once it has expired, or its authority is gone from this computer's store, it is asked about as at first, since you never
+confirmed it. A certificate whose only use is Remote Desktop Authentication (as Active Directory's Remote Desktop
+templates issue them) isn't valid for a server by Tabby's rules, whatever issued it, so it is asked about too, and again
+when it is renewed. Trusting a certificate never allows signing in without Network Level Authentication, which is asked
+about on its own.
 
 ### Through an RD Gateway
 
@@ -239,17 +308,30 @@ isn't on 443. The profile's address is then the desktop as the gateway sees it (
 goes to the gateway over HTTPS, signs in there, and the gateway connects it on; the desktop then asks for its own
 sign-in as usual, inside that tunnel.
 
-- **One sign-in by default.** The account you enter for the desktop also signs in to the gateway, as with Remote
-  Desktop Connection's "use my RD Gateway credentials for the remote computer". A gateway that takes another account:
-  pick a [saved account](#saved-accounts) under **Gateway account**; its password is asked for once and kept with the
-  account.
+- **One sign-in by default.** The account you enter for the desktop also signs in to the gateway, as with Remote Desktop
+  Connection's "use my RD Gateway credentials for the remote computer". A gateway that takes another account: pick a
+  [saved account](#saved-accounts) under **Gateway account**; its password is asked for once and kept with the account.
+  A remembered desktop password is kept for the gateway it was entered for (whichever account signs in to the gateway),
+  so it is never sent through a different gateway named for the same address without asking; a new gateway, user name,
+  domain or account asks again, and a new address takes the password along, unless a desktop is known at that address
+  already. Version 0.5.0 kept such a password for the address alone, where a desktop at that address without a gateway
+  would find it: those of the desktops configured with a gateway by then are forgotten after the update, once in each
+  computer's keychain and once in Tabby's Vault, the first time a password is looked up, saved or forgotten there, and
+  both desktops ask once. Until that has been done (a keychain that doesn't answer, a Vault whose passphrase prompt was
+  cancelled), such a password isn't used. A [saved account](#saved-accounts) is one password for every desktop that
+  names it, wherever each of them goes.
 - **A refused sign-in says who refused it.** When it was the gateway (a wrong password, or its policy doesn't let the
   account in), the form comes back saying so, and nothing has gone to the desktop. A desktop the gateway's policy
   doesn't let the account reach, or that the gateway can't reach, is an error with that reason.
-- **The gateway's certificate** is accepted when it is valid for the gateway's name (issued by an authority this
-  computer trusts), and otherwise remembered on first use like a desktop's; either way a later change to one that
-  isn't valid stops the connection, before the sign-in goes out, until you trust the new one. Remembered ones are
-  listed under Settings › Remote Desktop › Certificates.
+- **The gateway's certificate** is checked as a direct desktop's is ([above](#remote-desktop-profiles)):
+  accepted when it is valid for the gateway's name by the certificate authorities this computer trusts (with a recent
+  Tabby, an organisation's own in the system's store counts); any other (self-signed, say) is shown on the first
+  connection and connected only after you confirm its fingerprint, because your sign-in reaches the gateway as a proof
+  of your password. A later change stops the connection, before the sign-in goes out, until you trust the new one,
+  unless an authority vouches for the new one and the one before wasn't one you trusted yourself (a gateway's
+  certificate remembered by 0.5.0 is replaced so too, whichever way it was remembered). The desktop beyond the gateway
+  has a certificate of its own: checked the same way for a remote desktop profile, remembered on first use behind an SSH
+  host. Remembered ones are listed under Settings › Remote Desktop › Certificates.
 - **Behind an SSH host too.** A desktop added behind an SSH host takes a gateway the same way (the **RD Gateway**
   field of its form): the gateway is then reached from that host.
 
@@ -272,9 +354,43 @@ Signing in with a saved account that has no password yet, or whose password a se
 form saves what you enter as the account's new password for every desktop. A refused password is not dropped by
 itself: one server refusing it doesn't make it wrong for the others. **Sign in again…** on such a desktop asks anew.
 
-The accounts' names and user names are in Tabby's config (`remoteDesktop.accounts`); the passwords are in Tabby's
-Vault when it is enabled (encrypted, and carried by Tabby's config sync), else in the system keychain. Removing an
-account removes its password and sets its desktops back to asking.
+The accounts' names and user names are in Tabby's config (`remoteDesktop.accounts`); the passwords are in Tabby's Vault
+when it is enabled (encrypted, and carried by Tabby's config sync), else in the system keychain. Removing an account
+removes its password and sets its desktops back to asking, a profile in a group with a default account included: it asks
+rather than take that default. A desktop's saved password that an edit or a removal forgets goes at once from each store
+that can be read, Tabby's Vault or the keychain. In one that can't be just then (the Vault locked and its prompt
+cancelled, the keychain not answering) it isn't used, and goes once that store can be read while the Tabby window is
+open; an edit or a removal says so. Should the window be closed before that, it is found again by a desktop at that
+address (**Sign in again…** in the desktop's menu replaces it). The desktop's remembered certificate stays too, so that
+the password goes only to the machine it was saved for: a removal keeps it (Settings › Remote Desktop › Certificates can
+forget it), and a new address leaves it at the old one too, as well as taking it along.
+
+## Clipboard
+
+While a desktop has the keyboard, what you copy here goes to it and what you copy there comes here: text, pictures and
+files. That is what makes it feel like part of this computer, and it also means that the desktop sees what is on your
+clipboard whenever it has the keyboard (what you copy while you work in it, and what you copied elsewhere before you
+clicked back into it), passwords from a password manager included, and can put anything on your clipboard, such as a
+command for you to paste into a terminal here. For a desktop you don't trust that far, **Settings › Remote Desktop ›
+Settings › Clipboard sharing** narrows it:
+
+- **Both ways**, the default.
+- **Only from the remote desktop to this computer:** what you copy here stays here, and a desktop connected this way
+  only ever gets an empty clipboard from this side; what you copy there still comes here, files included.
+- **Off:** the clipboard is left out of the connection altogether, files included.
+
+A desktop can have its own: **Clipboard** in its profile's settings (or its profile group's, or Tabby's defaults for
+remote desktop profiles), or in the form of a desktop added behind an SSH host (the host's own desktop follows the
+setting); the Clipboard menu on such a desktop says so. A desktop configured twice behind a host, as an entry and as an
+RDP profile at the same address, gets the narrower clipboard of the two, and a desktop opened with a narrower clipboard
+while it is open already (from another profile for it, say) narrows the open one until it is closed, its reconnects
+included, and when it is shown again after its server ended it; its Clipboard menu says so meanwhile. Changes apply on
+the next connection, Reconnect included. Narrowing the setting also stops anything more going from here right away to
+the open desktops that follow it, takes back the files offered to them, and stops a paste to all desktops or a save of
+several files that is under way before its next step. Narrowing applies in full only once they reconnect: reconnect a
+desktop you don't trust that far. **Paste to all desktops** leaves out the desktops that don't take this computer's
+clipboard and says which. Shared folders are a setting of their own, and screenshots and **Copy log** (Settings ›
+Remote Desktop › Desktops › Open desktops) still go to your clipboard: they are your own actions.
 
 ## Shared folders
 
@@ -291,8 +407,17 @@ Files are served through the RDP connection as the remote reads and writes them,
 documents in place; for moving large files, copying through the clipboard is just as quick. They are read and written
 in the background, so a slow disk or network folder slows the drive down, not Tabby.
 
-The remote gets the shared folder and nothing else: a symbolic link works when it points inside the folder, and one
-that leads out of it isn't shown, read or written through. Only files and folders are served (no devices or pipes).
+The remote gets the shared folder and nothing else: a symbolic link works when it points inside the folder, and one that
+leads out of it isn't shown, read or written through. Only files and folders are served (no devices or pipes). A file
+with more than one name (a hard link, as pnpm's `node_modules` and some backup tools make) is read-only from the remote
+(as its count of names is when it is opened), since the same file may be outside the folder too; the remote can still
+read it, as any file in the folder. A desktop can have up to 1,024 files open at once, and all the desktops in a Tabby
+window 2,048 together. On macOS and Windows a Tabby window may have far more open than that; on Linux it depends on the
+system's limit, and where that is 4,096 or less, these are half of it or more. The remote is shown 1 GB less free space
+than the disk has (on a disk under 20 GB, a twentieth of its size less), and can't take that by making a file larger
+than what it writes to it: a file grows beyond what is written to it only within the free space of the disk it is on (a
+disk mounted inside the folder has its own), less that much. Where files can have holes (APFS, ext4), each file can grow
+so, taking no space until it is written. What the remote writes takes space as any copy does.
 
 Windows mounts shared folders (tested); xrdp can when built with FUSE (under `~/thinclient_drives`); GNOME Remote
 Desktop doesn't serve drives, so there the clipboard is the way.
@@ -303,10 +428,13 @@ Split a tab (Tabby's **Split** in the tab's menu, or drag one tab onto another)
 machine's desktop next to another's, or next to its own console. Right-click any of them:
 
 - **Paste to all \<n\> desktops in this tab** pastes what's on your clipboard on every desktop in the tab, in whichever
-  window is active on each: text, a picture, or files and folders copied in Finder (or Explorer, or Files).
+  window is active on each: text, a picture, or files and folders copied in Finder (or Explorer, or Files). Desktops
+  that don't take this computer's [clipboard](#clipboard) are left out, and a note says which. So is a desktop whose
+  console is in front, or that is behind a pane maximized over it (Tabby's **Maximize the active pane**): only the
+  desktops showing get the paste, and the menu counts only those.
 - **Type into all \<n\> desktops in this tab** sends every key you type on one desktop to the others too, shortcuts and
   **Send keys** included, until you turn it off. An orange label on each desktop says so while it's on. The mouse stays
-  per desktop, and desktops in view-only mode are left out.
+  per desktop, and desktops in view-only mode, with their console in front or behind a maximized pane, are left out.
 - **Make panes even** evens out the split's panes, which Tabby does itself but offers nowhere else.
 
 As you click into a desktop, its name shows in its corner for a moment, like a TV naming its input ("BUILDBOX", or "WIN-11 ·
@@ -324,7 +452,14 @@ most once a minute; on a Windows host, [Hyper-V's](#hyper-v)) and lists the ones
 
 A Linux VM that runs GNOME is left out: its desktop is reached by SSH-ing to it (its own desktop, or `ssh` typed in a
 console on the host, [above](#use)). A VM found this way asks for its account the first time, like any Windows or xrdp
-desktop; **Save \<name\> to this host's desktops** in its menu keeps it, for a name of your own and other settings.
+desktop; one the host lists as Linux (xrdp) also asks once before your password goes to it without Network Level
+Authentication, since that it is xrdp is only the host's word. **Save \<name\> to this host's desktops** in its menu
+keeps it, for a name of your own and other settings; its kind stays the host's word, and asks the same way (a VM saved
+with an earlier version too), until you pick a kind for it in its edit form. VMs aren't looked for on a machine
+reached with `ssh` typed in another host's console. The menu lists 256 VMs at most, and says so when a host has more;
+add other libvirt VMs by their address with **Add a desktop behind \<host\>…**. Hyper-V VMs past the first 256 aren't
+offered in the menu: one opens from a `remoteDesktop.desktops` entry in Tabby's config file, with `via` and `hyperv:
+<its id>` (see [above](#windows-and-other-desktops-behind-a-host)).
 **Settings › Remote Desktop › Find virtual machines on SSH hosts** turns this off.
 
 A VM the plugin started can go back off by itself: **Settings › Remote Desktop › Shut down VMs it started** (5
@@ -366,10 +501,21 @@ Turn it on in the pane's menu under **Remote Desktop › Settings**, or in Setti
 your terminal's scrollback, colors and shortcuts stay as they are. Turning it off removes it again. Details:
 [docs/desk.md](docs/desk.md).
 
+Before it acts on what `desk` prints, Tabby checks three things: the key `desk` sends, which only your account on that
+machine can read and which Tabby learns when it opens the machine's desktop with `desk` on; that it is the key of the
+machine the pane is connected to (its SSH host, or the machine `ssh` typed there went to); and that the pane is the
+one you're in. So other output that only looks like what `desk` prints is ignored, and `desk` works on a machine once
+its desktop has been opened with `desk` on from this Tabby, or from one that shares its config through config sync
+(after updating from 0.5.0 or earlier, open it once again). The key tells `desk` apart from look-alikes, not from the
+machine itself, which can always send it, nor from a recording of `desk`'s output (a terminal log, `script`,
+asciinema), which holds it: shown again in that machine's pane while you're in it, it counts as `desk`. Open the
+desktop of a machine you don't trust with `desk` off, which also has Tabby forget a key it had for it.
+
 ## Settings
 
 Open **Settings › Remote Desktop** in Tabby, right-click the desktop button in Tabby's header, or open **Settings** in the Remote Desktop section of a terminal's or tab's menu.
-They are stored in Tabby's config under `remoteDesktop`:
+Desktop settings are stored in Tabby's config under `remoteDesktop`; update preferences and installation history
+are local to this computer:
 
 | Setting | Default | |
 |---|---|---|
@@ -379,23 +525,24 @@ They are stored in Tabby's config under `remoteDesktop`:
 | For *this desktop* only (`desktopSharpness`) | As above | In the menu of a tab with a desktop open: Standard or Retina for that desktop, whatever the default. Kept by desktop (`user@host`, `user@host#address` for one behind a host, or `rdp#address` for a remote desktop profile's own tab). |
 | Sound (`sound`) | On | Applies on the next connection. |
 | Video decoding (`h264`) | On | H.264 decoded by Tabby's browser engine (hardware-accelerated where available), for what the remote sends as video; applies on the next connection. |
-| Microphone (`microphone`) | Off | Send your microphone while an app on the remote desktop records. Applies on the next connection. |
+| Microphone (`microphone`) | Off | Send your microphone to a remote desktop that asks for it, as one does while an app there records. Turning it on applies on the next connection; turning it off stops it at once, also on a desktop still connecting. A desktop's menu can stop it for that desktop alone, until it is turned back on there or that Tabby window is closed. |
+| Clipboard sharing (`clipboard`) | Both ways (`both`) | Or only from the remote desktop to this computer (`fromRemote`), or off (`off`), for text, pictures and files alike; a desktop's own (`clipboard` in its profile or its `desktops` entry) takes its place ([Clipboard](#clipboard)). Applies in full on the next connection; narrowing it also stops the sending at once to open desktops that follow it. |
 | Shared folders (`sharedFolders`) | None | `[{ path, name, readOnly }]`: folders shared as drives with every remote desktop ([Shared folders](#shared-folders)). Applies on the next connection. |
 | Show connection status (`connectionStatus`) | Off | The indicator in the desktop's corner; fades when the pointer comes near. |
 | Mac shortcuts (`macShortcuts`) | On | macOS. Off: ⌘ is the Windows key. |
 | Send text as typed (`unicodeKeys`) | Off | Sends the characters the keyboard produces rather than key positions, so dead keys and a layout the remote doesn't have come out right; keys with Ctrl, Alt or ⌘ still go by position. Windows types any character; GNOME only those its own layout has (mutter has no keycode for the others). Input methods (CJK) are not supported yet. |
 | Shortcuts (`hotkeys.remote-desktop-*`) | ⌘⇧G / Ctrl+Shift+G for the switch; the rest unbound | Tabby's hotkeys: the switch between desktop and console, view only, screenshot, Ctrl+Alt+Del, type into all, paste to all, connection status, disconnect. Changed on the settings page (Getting started › Shortcuts) or in Settings › Hotkeys. |
 | Saved accounts (`accounts`) | None | `[{ id, name, username, domain }]`; see [Saved accounts](#saved-accounts). The passwords are in the Vault (encrypted, part of the config) or the keychain, never in plaintext in the config. |
-| Bring the console along with `desk` (`desk`) | Off | Installs `desk` and a login line on each machine you open a desktop on; applies on the next connection there. |
+| Bring the console along with `desk` (`desk`) | Off | Installs `desk` and a login line on each machine you open a desktop on; applies on the next connection there. The key each machine's `desk` sends is kept as a fingerprint (`deskKeys`), from a machine whose desktop was opened with this on, and forgotten when it is opened with this off. |
 | Session backend (`sessionBackend`) | `native` | For `desk`: `native` (trd-pty) or `tmux`. Config file only. |
 | Find virtual machines on SSH hosts (`discoverVMs`) | On | Lists a host's libvirt VMs with a desktop in its menu ([VMs on a host](#vms-on-a-host)). |
 | Shut down VMs it started (`shutDownIdle`) | Never | 5, 15 or 60: minutes without a desktop open after which a VM the plugin started is shut down again ([VMs on a host](#vms-on-a-host)). |
-| Tell me about new versions (`checkUpdates`) | On | Once a day, asks npm for the latest tabby-rdp (nothing else is sent), and says so in a note, the menus and the settings page when there's a newer one: Tabby itself shows plugin upgrades only on its Plugins page. |
-| Desktop name overlay (`osd`) | When it helps | `show` (`auto`, `always`, `off`), `font`, `size`, `position`, `color` (empty: white) and `seconds`; the settings page previews it, at a resolution you pick. |
+| Check for updates automatically (Updates tab) | On, Stable | Checks npm once a day; choose Stable or Preview, check manually, and install a compatible version explicitly. [Versions and recovery](#versions-and-recovery). |
+| Desktop name overlay (`osd`) | When it helps | `show` (`auto`, `always`, `off`), `font`, `size`, `position`, `color` (empty: white; else a color name, `#hex`, or a color function of numbers such as `rgb()`) and `seconds`; the settings page previews it, at a resolution you pick. |
 
 ## Requirements
 
-- **Tabby 1.0.236 or newer**, on macOS, Windows or Linux (tested with 1.0.236 and 1.0.237). On a fresh Windows, Tabby
+- **Tabby 1.0.236 or newer**, on macOS, Windows or Linux. On a fresh Windows, Tabby
   itself needs the [Microsoft Visual C++ Redistributable](https://learn.microsoft.com/cpp/windows/latest-supported-vc-redist)
   for SSH.
 - **Linux desktops:** GNOME Shell and GNOME Remote Desktop 46 or newer (Ubuntu 24.04, for example), a systemd user
@@ -409,7 +556,13 @@ They are stored in Tabby's config under `remoteDesktop`:
   host or running OpenSSH Server itself.
 
 Tested with Ubuntu 24.04 (GNOME Remote Desktop 46.3) and Windows 11 (Pro and Enterprise), from Tabby on macOS,
-Windows 11 and Ubuntu 24.04 (arm64).
+Windows 11 and Ubuntu 24.04 (arm64). Recent host compatibility tests cover official Tabby **1.0.238** on macOS
+with xterm 5, and upstream xterm 6 builds on macOS and Linux. The new package installation dialog is tested on
+macOS with Tabby 1.0.238; Windows qualification of these changes remains pending. See the
+[host test matrix](test/README.md#host-qualification) for the exact builds and coverage.
+
+The plugin checks the host's available features through a shared compatibility layer. Connection logs include the
+host and runtime versions, declared xterm dependency and observed capabilities to help diagnose forks and nightlies.
 
 ## Built on IronRDP
 
@@ -419,7 +572,9 @@ needed more: GNOME only speaks RDP's graphics pipeline, which IronRDP's web clie
 monitor in a way the web client didn't follow; and it depends on details of the sound and dynamic-channel protocols
 that IronRDP got slightly wrong. The web client also had no sound at all.
 
-tabby-rdp ships IronRDP with a short series of patches ([ironrdp/](ironrdp)). The fixes go upstream, one by one:
+tabby-rdp ships IronRDP with a short series of patches ([ironrdp/](ironrdp)). Before each release, CI rebuilds it
+from IronRDP's source and the patches, and the release goes out only if the two builds are identical, byte for byte
+([how](ironrdp/README.md#reproducing-vendor)). The fixes go upstream, one by one:
 
 | Change | Upstream |
 |---|---|
@@ -444,8 +599,10 @@ it, not just this plugin.
 ## Development
 
 ```sh
-npm install
+npm ci --ignore-scripts
 npm run build                # TypeScript to dist/
+npm run typecheck            # plugin and test TypeScript
+npm run test:unit            # standard unit suite; no remote machine needed
 scripts/sandbox.sh           # a separate Tabby with this plugin linked in (macOS), DevTools on port 9334
 npm test                     # end-to-end suites against a test machine: see test/README.md
 npm run build:ironrdp        # rebuild vendor/ from IronRDP and ironrdp/patches: see ironrdp/README.md
@@ -497,7 +654,8 @@ npm run build:ironrdp        # rebuild vendor/ from IronRDP and ironrdp/patches:
 
 Questions ("how do I…", "is this expected?") go to [Discussions › Q&A](https://github.com/meanaverage/tabby-rdp/discussions/categories/q-a);
 bugs and feature requests to the [issues](https://github.com/meanaverage/tabby-rdp/issues). A bug report is most useful
-with the connection log: **Settings › Remote Desktop › Troubleshooting › Open desktops › Copy log**.
+with the connection log: **Settings › Remote Desktop › Desktops › Open desktops › Copy log**.
+Start with the [troubleshooting guide](TROUBLESHOOTING.md) for common connection and installation problems.
 
 ## License
 

package/TROUBLESHOOTING.md

@@ -0,0 +1,77 @@
+# Troubleshooting
+
+For connection logs, open **Settings › Remote Desktop › Desktops › Open desktops**, then choose **Copy log**. In version 0.5.1, the list is in **Troubleshooting**. Review logs before sharing them.
+
+<a id="certificate"></a>
+
+## A certificate this computer can't verify, or one that has changed
+
+A desktop you connect to directly (a remote desktop profile, an imported file) and an RD Gateway connect without asking when their certificate is valid for their name by this computer's certificate authorities, as an organisation's own desktops and gateways often are. Any other is shown the first time, with why it can't be verified (most often: it is the server's own, self-signed) and its fingerprint, before anything of your sign-in is sent: check the fingerprint with whoever runs it, some other way than this connection (it is also in the desktop's connection log), then choose **Trust the certificate**. The question also says whom the certificate says it was issued to and by, and when it is valid: its own word, which nothing has checked, unless its chain leads to an authority this computer trusts (another machine's certificate then shows that machine's name) and the TLS library didn't refuse it for a reason of its own (a limit set on the authority, say). An issuer you wouldn't expect there (one that inspects your network's connections, say) is worth asking about before you trust it, but the one you would expect proves nothing: anyone can make a certificate that names it. Only the fingerprint, checked some other way, does. A desktop behind an SSH host remembers its certificate on first use without asking, since the way there runs inside SSH. When a remembered certificate differs later, the plugin stops before signing in, so nothing of your sign-in has gone to that server; only a certificate an authority vouched for is replaced without a question, by another it vouches for too. Reinstalling the machine or renewing its certificate changes it: then choose **Trust the new certificate**. If neither happened, something else is answering at that address. A GNOME desktop only ever accepts the certificate the plugin made for it; a different one there means another program listens on its port. Remembered certificates are in Settings › Remote Desktop › Desktops.
+
+<a id="sign-in"></a>
+
+## Wrong user name or password
+
+Windows and xrdp desktops sign in with an account on that machine (`DOMAIN\user` works). A saved password that no longer works is asked for again; **Sign in again…** in the tab's menu replaces it on purpose. xrdp doesn't refuse a wrong password: it shows its own login window instead. GNOME desktops never ask: the plugin manages their sign-in.
+
+<a id="no-desktop"></a>
+
+## No desktop found on a Linux host
+
+The plugin uses GNOME Remote Desktop 46 or newer (Ubuntu 24.04, for example), with no root and no login screen. For KDE, XFCE, MATE and others, install xrdp and a desktop for its sessions: on Debian and Ubuntu, `sudo apt install xrdp xfce4`. A GNOME session already shared from the machine's own screen (GNOME's Desktop Sharing) has to be turned off first.
+
+<a id="unreachable"></a>
+
+## Can't reach a Windows desktop
+
+Windows needs Remote Desktop turned on (Settings › System › Remote Desktop; Pro, Enterprise or Server). Behind an SSH host, the address is as that host sees it: from there, `nc -z <address> 3389` should succeed. For a VM or machine that may be off, give the desktop a VM name or MAC address in its edit form and it is started when opened.
+
+<a id="reconnecting"></a>
+
+## It keeps reconnecting
+
+After sleep or a network change the desktop reconnects by itself, with growing pauses, and waits while the SSH connection is down (**Reconnect SSH** hurries that along). It stops after a few tries or on **Stop**. If it drops again right after connecting, check the host's free memory and that the desktop's session is still running there.
+
+<a id="picture"></a>
+
+## The picture is blurry or slow
+
+**Sharpness › Retina** renders at your screen's device pixels, with the remote's scale set to match. Video (H.264) is used when the remote sends it: Windows does, GNOME only with a hardware encoder (VA-API or NVENC). **Show connection status** shows the frame rate, the round trip and how the picture comes.
+
+<a id="sound"></a>
+
+## No sound, or the microphone isn't heard
+
+Sound and microphone changes apply on the next connection. xrdp needs `pipewire-module-xrdp` or `pulseaudio-module-xrdp`. The microphone needs the system's permission here (macOS: System Settings › Privacy & Security › Microphone, then restart Tabby). On GNOME, apps record from "Remoteaudio Source"; on Windows, the machine must allow audio recording redirection. A desktop whose microphone was stopped (**Stop** in the microphone's menu in Tabby's header, or **Send the microphone** unchecked in the desktop's menu) gets none, its reconnects included, until **Send the microphone** is checked again in its menu or that Tabby window is closed.
+
+<a id="nested-ssh"></a>
+
+## I typed ssh to another machine in a terminal
+
+In an SSH tab (or a split pane) where you typed `ssh` on to another machine, **Desktop** opens that machine's desktop, going through the first one, and `desk` works there too. Desktop asks which desktop you mean, since which `ssh` runs there is the first machine's to say; pick the other machine's "from now on" to have it open at once the next times. Desktops you set up behind a host open in a tab connected to that host, not through another one. The first machine has to log in to the other by itself for this: with a key there, or agent forwarding, as `ssh -o BatchMode=yes` would. Tabby's **Reconnect** belongs to the tab: it reconnects the first machine and ends the ssh typed in it. To have both desktops side by side, open the first machine's desktop in one pane, and ssh on in the other.
+
+<a id="extra-monitor"></a>
+
+## The desktop is open somewhere else
+
+GNOME Remote Desktop's headless mode gives each connection a screen of its own: a second computer, or another Tabby window, connected to the same account gets an empty extra screen rather than the same one. So when the desktop is open somewhere else already, you choose. **Take it over** disconnects the other connection, as Windows does; the session and its apps carry on, on this screen. **Open a second screen** keeps both, each with a screen of its own. A desktop taken over from here doesn't take itself back: it says so, and offers the same two choices.
+
+<a id="recovery"></a>
+
+## Recover a version, disable the plugin, or remove it
+
+In **0.5.2 or newer**, open **Settings › Remote Desktop › Updates**. **Stable** is the default; **Preview** includes beta releases and release candidates when available. Choose an exact published version and confirm installation. **Return to stable** can install an older version. **Restore previous version** uses the version saved after the last successful installation from this page. On older releases, manage the package in **Tabby › Settings › Plugins**.
+
+The confirmation dialog stays open through progress and the verified result. If installation fails, the dialog shows the cause. After success, close remote desktops and restart Tabby; Updates shows the running version and the installed version waiting for restart until then.
+
+Use **0.5.1 or newer** with current account and certificate settings, and respect any higher minimum documented by a later data migration.
+
+If the plugin cannot load:
+
+1. Open **Tabby › Settings › Plugins**. Disable **tabby-rdp** to stop it loading, or uninstall and reinstall it there. Restart Tabby after changing plugins. Tabby’s [configuration locations](https://github.com/Eugeny/tabby/wiki/Config-file) help locate your profile when the application cannot open.
+2. For a specific known compatible version, open a terminal in **Tabby's plugin folder** (the folder containing the plugin installation's `package.json`, with `node_modules/tabby-rdp` below it). Run `npm install tabby-rdp@0.5.1`, replacing `0.5.1` with your known compatible exact version. Do not run this in the tabby-rdp source checkout, the application bundle, or inside `node_modules/tabby-rdp` itself. Fully quit and reopen Tabby afterwards.
+3. If a later version has migrated saved data, respect that version's documented minimum. Reinstall a compatible stable version or the last working preview; do not force an older version across a migration boundary.
+
+Disabling or uninstalling keeps desktops, profiles, settings, remembered certificates and saved credentials. It also leaves any remote helpers and remote applications in place. To remove saved entries, use **Remote Desktop › Desktops** and **Accounts**, and **Profiles & connections** for profiles, before uninstalling. Unlock the credential store first if required; check any reported failure rather than assuming a credential was deleted. Data synced to other computers may need attention there too.
+
+For the optional `desk` remote helper, turn **Settings › Remote Desktop › Settings › desk: bring the console along** off and reconnect to each host while the plugin is still installed. The next connection removes the helper's own files and login hook; an offline host cannot be cleaned this way until it returns. Read the [desk cleanup details](docs/desk.md) for manual removal and read-only startup files. End remote applications you no longer need separately. Uninstalling this plugin does not shut down remote hosts or erase their files.

package/dist/accountForm.js

@@ -87,4 +87,3 @@ function newAccountOption(select, label, save, onChange) {
         field('name').focus();
     });
 }
-//# sourceMappingURL=accountForm.js.map