===============================================================================
 FlashScp — copy files and folders between computers, over SSH using scp
===============================================================================

 Programmer:  Stan Switaj
 Program:     FlashScp, for LinuxDoors
 Download:    https://LinuxDoors.com/downloads/FlashScp.AppImage
 Size:        48 MB   (single file, nothing to install)
 SHA256:      6d2197d48446edee63e85e8b1a13a8d281fcae34d7e063157442db4a64636427

 Written for LinuxDoors, though nothing in it is specific to LinuxDoors — it
 should run on Debian and Ubuntu type systems, and on any other Linux
 distribution that can run an AppImage.


-------------------------------------------------------------------------------
 WHAT IT IS
-------------------------------------------------------------------------------

 A two-pane file transfer window in the manner of FlashFXP, but where FlashFXP
 spoke FTP, FlashScp copies with scp over an SSH connection.

 Two computers side by side. Drag from one to the other. A queue underneath
 does the work and tells you how far along it is.

 Either side can be this computer or any machine you have saved, which turns
 three separate jobs into one gesture:

     local     ->  remote        sending files up to a server
     remote    ->  local         bringing files back down
     remote    ->  remote        moving files between two servers

 They are all the same thing: pick the two ends, drag, watch the queue.


-------------------------------------------------------------------------------
 HOW THE COPYING ACTUALLY HAPPENS — SCP, OVER SSH
-------------------------------------------------------------------------------

 This is worth being precise about, because the two names get used loosely.

     SSH is the connection.   It authenticates you to the far machine and
                              encrypts everything that travels between you.

     SCP is the copying.      It is the program that actually moves the bytes,
                              and it runs over the SSH connection that SSH
                              has established.

 So: FlashScp copies files over SSH using scp. SSH gets you securely to the
 machine; scp carries the file across that secure link. FlashScp does not
 invent its own protocol and does not carry its own SSH library — it drives
 the real `ssh` and `scp` programs that are already on your system, the same
 ones you would type in a terminal.

 That last point is the design of the whole program. Because it is the same
 ssh, everything ssh already knows about your machines stays true:

     - your private keys, and ~/.ssh/config
     - your ssh agent
     - your known_hosts file
     - ProxyJump, so you can copy through a bastion host
     - machines that demand a key AND a password (two-factor)

 Nothing here re-implements authentication, so nothing here can get it subtly
 wrong.


-------------------------------------------------------------------------------
 WHY SCP OVER SSH IS THE RIGHT WAY TO DO THIS
-------------------------------------------------------------------------------

 The honest comparison is against FTP, which is what this kind of program
 traditionally used.

 1. EVERYTHING IS ENCRYPTED.
    Your password, the file names, and the contents of the files all travel
    encrypted. Plain FTP sends your password across the network in clear text
    for anyone on the path to read. For a program whose entire job is carrying
    your files to your servers, that difference is the whole argument.

 2. ONE PORT, AND IT IS ALREADY OPEN.
    SSH is a single connection on port 22, which is already there because you
    administer the machine with it. FTP needs a control channel plus a second
    data channel on a port negotiated at the time — which is the thing that
    turns into a fight with NAT and firewall rules. With scp there is nothing
    extra to open and nothing extra to explain to a firewall.

 3. NOTHING TO INSTALL ON THE OTHER MACHINE.
    No FTP server, no daemon, no agent. If you can ssh into a machine, you can
    copy files to it. Every Linux and Unix system already has what is needed on
    the far end.

 4. KEYS INSTEAD OF PASSWORDS.
    You can authenticate with a key and send no password over the wire at all,
    and you can combine a key with a password where a machine demands both.

 5. YOU CAN TELL YOU ARE TALKING TO THE RIGHT MACHINE.
    SSH records each machine's host key the first time and refuses if it ever
    changes, so a substituted server is caught. FTP has no equivalent — you
    simply cannot know.

 6. CORRUPTION IN TRANSIT IS DETECTED.
    SSH authenticates every packet it carries, so a file cannot quietly arrive
    wrong because something along the way damaged it.

 7. PERMISSIONS AND TIMESTAMPS COME WITH THE FILE.
    Files arrive with their modification time and mode intact.


 WHAT SCP COSTS, SAID PLAINLY

 It is not free of trade-offs, and it is better to know them:

     - scp has no resume of its own, and no delta transfer. It cannot send only
       the changed part of a large file the way rsync can. FlashScp works
       around the first of these by walking the folder itself and skipping any
       file already complete at the far end, so an interrupted folder copy
       picks up where it stopped. It cannot work around the second.

     - scp has more per-file overhead than FTP, so thousands of small files are
       slower. FlashScp answers this by holding one connection open and sending
       several files at once — see below.

     - SSH has no directory listing protocol, so FlashScp reads folders by
       running `find` on the far machine, falling back to `ls` where `find` is
       not available.


-------------------------------------------------------------------------------
 WHAT IS IN THE PROGRAM
-------------------------------------------------------------------------------

 MANAGER OF COMPUTERS
     Every machine you use, with its name, host, port, user, the path to your
     private key, an optional password, a starting folder and a note. A Test
     button proves a machine is reachable before you rely on it. Double-click
     a machine to connect to it; it opens on whichever side is free, and the
     Manager stays open with the reason if the connection fails.

 ONE CONNECTION PER MACHINE
     The first connection opens a shared channel and every listing, every file
     and every command afterwards travels down it. This makes repeat work far
     faster, but the real gain is on a machine that wants a password: it asks
     once, when you connect, instead of once per file. Copying a folder of
     forty files to such a machine is one prompt, not forty.

 THE QUEUE
     A dragged folder is walked first and queued a file at a time, rather than
     handed to scp whole. That buys three things: a progress figure that means
     something (bytes done of bytes known), several files travelling at once,
     and resume — a file already at the far end at the right size is skipped
     rather than sent again. You can cap the speed so a large copy does not
     take the whole link.

 COMPARE AND MIRROR
     Put a folder here beside a folder there, see what differs by size and
     modification time, and send only what changed.

 TERMINAL TAB
     Run a command on the selected machine without leaving the program — the
     chmod +x, the mkdir, the ls to confirm something landed.

 FULL FILE MANAGEMENT
     New folder, rename, permissions and delete, on both sides. A delete names
     exactly what it will remove and which machine it will remove it from, and
     waits for you to agree.

 LIGHT AND DARK
     A toggle in the top right, remembered between runs. Every colour was
     measured rather than chosen by eye: text meets the 4.5:1 contrast that
     WCAG asks for, and the outlines of controls meet 3:1. The program will
     check its own colours and tell you if any has slipped:

         FlashScp.AppImage --check-contrast

 KEEP-ALIVE
     The connection is checked every twenty seconds, so a link that has died is
     noticed in about a minute and reported, rather than leaving a transfer to
     hang for ever.


-------------------------------------------------------------------------------
 RUNNING IT
-------------------------------------------------------------------------------

 Download the AppImage, make it executable, and run it:

     chmod +x FlashScp.AppImage
     ./FlashScp.AppImage

 There is nothing to install. The AppImage carries its own Python and its own
 interface libraries, plus sshpass for machines that want a password. It
 deliberately does NOT carry its own ssh or scp: those must be the ones on your
 own machine, because they are what read your keys, your ~/.ssh/config and your
 known_hosts. Every Linux system already has them.

 Your saved machines and settings are kept in:

     ~/.config/FlashScp/FlashScp.save

 That file is created readable only by you. A password is only written there if
 you tick "Save the password for this machine", and it is scrambled so the file
 cannot be read at a glance — which is obfuscation, not encryption, and the
 program says so rather than pretending otherwise. Left unticked, a password is
 asked for once and kept in memory only until you close the program. Either
 way it is handed to ssh through the environment and never on a command line,
 where other users of the machine could see it.

===============================================================================
