From b090c24d5994f5e748801208362b712c70947fd1 Mon Sep 17 00:00:00 2001 From: Randall Winkhart Date: Sat, 4 Mar 2023 15:05:29 -0500 Subject: [PATCH] Update documentation for release v1.4.0 Former-commit-id: 25559878dca6f91567805473078398b7b6728126 Former-commit-id: 1f88fe4849e4f0d26d32fa69a772ca9863d53c42 --- README.md | 25 ++++++-------- extra/changelog-total | 52 ++++++++++++++++++++++++++++++ extra/manpage | 2 +- lib/sshyp.py | 9 +++--- share/doc/sshyp/changelog | 68 +++++++++++++++++++++------------------ 5 files changed, 102 insertions(+), 54 deletions(-) diff --git a/README.md b/README.md index a0791bd..98df78a 100644 --- a/README.md +++ b/README.md @@ -12,8 +12,6 @@ sshyp is a very simple self-hosted, synchronized password manager for UNIX(-like sshyp is compatible with entries created by pass/password-store, as its original goal was to be like pass/password-store, but far more user-friendly to synchronize with a self-hosted server. -sshyp is (as of writing) the only password-store compatible CLI password manager available for Haiku. - sshyp makes use of a custom sftp wrapper, called sshync (ssh+sync), to reliably sync user entries with a local or remote server. The name "sshyp" is a combination of its syncing library, "sshync", and "passwords". @@ -33,26 +31,20 @@ What sshyp can do: - securely sync said passwords and notes seamlessly between devices (or just manage them offline) - utilize [extensions](https://github.com/rwinkhart/sshyp-labs) to interact with your entries is additional ways (such as generating TOTP keys or managing your entries in a GUI) - everything above with entries created by pass/password-store! -- everything above on Haiku, FreeBSD, Linux, and Termux (an Android terminal emulator)! - -What sshyp definitely won't do: - -- Non-UNIX(-like) support, e.g. Windows (I'd be happy to link to third-party ports, if someone were to make them) +- everything above on Haiku, FreeBSD, Linux, and Termux! # Installation Please see the [installation guide](https://github.com/rwinkhart/sshyp/wiki/Installation) in the sshyp wiki for directions specific to your distribution/OS. Pre-built packages exist for Haiku, FreeBSD, Alpine Linux, Arch Linux, Debian/Ubuntu Linux, Fedora Linux, and Termux. These can be downloaded from the releases page. -Requests for additional distribution/OS support can be filed as issues. +Support for additional environments, such as MacOS and OpenBSD, is coming soon. Extensions are available in the [sshyp-labs](https://github.com/rwinkhart/sshyp-labs) repository. Bash completions can be enabled by installing your distribution's "bash-completion" package and restarting your terminal. # Building -Since sshyp is written entirely in Python, it doesn't need to be compiled. It does, however, need to be packaged for installation. - A packaging script is included in the root directory of the repo in order to package sshyp for your distribution. To package sshyp from source, simply run: ``` @@ -61,11 +53,11 @@ cd sshyp ./package.sh [target] ``` -The packaging script has been tested on Arch Linux with "dpkg" as a dependency for Debian/Ubuntu and Termux packaging and "freebsd-pkg" as a dependency for FreeBSD packaging. +The packaging script has been tested on Arch Linux with "dpkg" as a dependency for Debian/Ubuntu/Termux packaging and "freebsd-pkg" as a dependency for FreeBSD packaging. Haiku and Fedora packaging must be done on their own respective distributions. -The AUR version and the packages attatched to the release tags were already packaged using this script. +The AUR version and the packages attached to the release tags were already packaged using this script. Currently, the script can create packages for Haiku, FreeBSD, Alpine Linux (APKBUILD), Arch Linux (PKGBUILD), Debian/Ubuntu Linux, Fedora Linux, Termux, and generic. @@ -78,15 +70,15 @@ sshyp tweak This command will allow you to configure the settings necessary for sshyp to function. To ensure configuration compatibility, it is a good idea to run 'sshyp tweak' after each major update. -Please note that decrypting and reading entries is disabled on server devices for security reasons. Only devices configured as clients can use the gpg key to decrypt entries. +Please note that decrypting and reading entries is disabled on server devices for security reasons. Only devices configured as clients can use the GPG key to decrypt entries. All available options can be found with: ``` -sshyp --help +sshyp help ``` -Or alternatively, in the manpage: +Or alternatively, in the man page: ``` man sshyp @@ -95,8 +87,9 @@ man sshyp # Roadmap Short-term Goals: +- MacOS support +- improved temporary directory security - a minimal GUI app - being made as an [extension](https://github.com/rwinkhart/sshyp-labs) -- improved extension integration (allow extensions to add new arguments) Long-term Goals: diff --git a/extra/changelog-total b/extra/changelog-total index f88bdee..e32ec47 100644 --- a/extra/changelog-total +++ b/extra/changelog-total @@ -1,3 +1,55 @@ +sshyp v1.4.0 + +the argumentative agronomist update + +this release overhauls sshyp's argument system and further streamlines +the experience with optimizations and the removal of legacy features + +compatibility-breaking changes: + +- there are no technical breaking changes, but the UX has changed significantly due to the new argument system (detailed below) + +user-facing features: + +- when typing an entry/folder name, it is now always the FIRST argument + ^ e.g. instead of "sshyp copy -p /example/test", it would now be "sshyp /example/test copy -p" + ^ this allows more easily editing the previous command to copy/edit a different field +- better extension integration + ^ extensions can now ship with a config file that sshyp can use to call them from standard sshyp arguments + ^ the first extension supporting this is sshyp-mfa + ^ if sshyp-mfa v1.4.0.1+ is installed, "sshyp /example/test copy -m" will copy MFA keys to your clipboard +- entry/folder names now MUST be specified as arguments + ^ there is no longer a separate input prompt if the entry/folder name is not provided as an argument + ^ the input prompt was a legacy feature from before arguments could specify entrys/folders with shell completion + ^ the entry list generated by entry_list_gen() is still present and can be viewed by running "sshyp" with no arguments +- better Bash completions + ^ now correctly places backslashes to escape spaces in entry/folder names + ^ slightly faster than the previous iteration +- IPv6 configuration support + +fixes/optimizations: + +- replaced "+=" with ".append" when extending lists to prevent creating an additional list +- optimized usage of "str.split()" and replaced it with "str.splitlines()" where applicable +- more concise "if... in ()" syntax replaces long "if" statement chains +- lists have been substituted with tuples where applicable +- entry_list_gen() has been re-written to be much smaller and faster +- os.path is now used in place of pathlib.Path in areas where it is faster +- the user's home directory is saved to a variable to prevent running expanduser() every time it is needed + +other notable changes: + +- removed some uncommonly used, redundant arguments + ^ e.g. "-rm", "-s", "delete" + ^ their functionality was NOT removed, just their redundant arguments, since "shear", "sync", and "del" are the accepted syntax +- errors containing entry/folder names reinforce correct syntax by adding leading/following slashes where necessary +- thanks to pull request #25, there are new error messages for the read shortcut + ^ includes when no entry name is provided or the entry name only refers to a directory +- directories provided in user input are no longer denoted by a following slash + ^ instead, os.path is used to determine if the user is referring to a file or directory + +<><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><> + sshyp v1.3.0 the serious shepherd update diff --git a/extra/manpage b/extra/manpage index db40e38..57db2ba 100644 --- a/extra/manpage +++ b/extra/manpage @@ -1,4 +1,4 @@ -.TH sshyp 1 "28 February 2023" "v1.4.0" "sshyp man page" +.TH sshyp 1 "04 March 2023" "v1.4.0" "sshyp man page" .SH NAME sshyp \- A very simple self-hosted, synchronized password manager for UNIX(-like) systems. Alternative to (and compatible with) pass/password-store. .SH SYNOPSIS diff --git a/lib/sshyp.py b/lib/sshyp.py index 9a6c552..4a35e92 100755 --- a/lib/sshyp.py +++ b/lib/sshyp.py @@ -318,8 +318,7 @@ def tweak(): # runs configuration wizard def print_info(): # prints help text based on argument if arguments[0] in ('version', '-v'): - print('\nsshyp is a simple, self-hosted, sftp-synchronized password manager\nfor unix(-like) systems (haiku/' - 'freebsd/linux/termux)\n\nsshyp is a viable alternative to (and compatible with) pass/password-store\n') + print('\nsshyp is a simple, self-hosted, sftp-synchronized\npassword manager for unix(-like) systems\n') print(" .. \u001b[38;5;9m♥♥ ♥♥\u001b[0m ..\n .''.''/()\\ \u001b[38;5;13m" "♥♥♥♥♥♥♥\u001b[0m /()\\''.''.\n * : \u001b[38;5;9m♥♥♥♥♥\u001b[0m : *" "\n `..'..' \u001b[38;5;13m♥♥♥\u001b[0m `..'..'\n // \\\\ " @@ -331,10 +330,10 @@ def print_info(): # prints help text based on argument 'randall winkhart\u001b[38;5;15;48;5;15m \u001b[38;5;7;48;5;8m/\u001b[0m') print('\u001b[38;5;7;48;5;8m/\u001b[38;5;15;48;5;15m ' '\u001b[38;5;7;48;5;8m/\u001b[0m') - print('\u001b[38;5;7;48;5;8m/\u001b[38;5;15;48;5;15m \u001b[38;5;15;48;5;8mversion 1.3.0' + print('\u001b[38;5;7;48;5;8m/\u001b[38;5;15;48;5;15m \u001b[38;5;15;48;5;8mversion 1.4.0' '\u001b[38;5;15;48;5;15m \u001b[38;5;7;48;5;8m/\u001b[0m') - print('\u001b[38;5;7;48;5;8m/\u001b[38;5;15;48;5;15m \u001b[38;5;15;48;5;8mthe serious shepherd ' - 'update\u001b[38;5;15;48;5;15m \u001b[38;5;7;48;5;8m/\u001b[0m') + print('\u001b[38;5;7;48;5;8m/\u001b[38;5;15;48;5;15m \u001b[38;5;15;48;5;8mthe argumentative ' + 'agronomist update\u001b[38;5;15;48;5;15m \u001b[38;5;7;48;5;8m/\u001b[0m') print('\u001b[38;5;7;48;5;8m/\u001b[38;5;15;48;5;15m ' '\u001b[38;5;7;48;5;8m/\u001b[0m') print('\u001b[38;5;7;48;5;8m<><><><><><><><><><><><><><><><><><><><><><><><><><><><>\u001b[0m\n') diff --git a/share/doc/sshyp/changelog b/share/doc/sshyp/changelog index 7694d3b..b642242 100644 --- a/share/doc/sshyp/changelog +++ b/share/doc/sshyp/changelog @@ -1,48 +1,52 @@ -sshyp v1.3.0 +sshyp v1.4.0 -the serious shepherd update +the argumentative agronomist update -this release ties up many of sshyp's loose ends where there was -room for major performance, compatibility, and security improvements +this release overhauls sshyp's argument system and further streamlines +the experience with optimizations and the removal of legacy features compatibility-breaking changes: -- due to a near full re-write of the syncing functionality, all clients and servers -must be updated to this release (v1.3.0 is not backwards compatible with any prior release) -- it is recommended to either delete the contents of ~/.config/sshyp/deleted (on the server-side) -or sync all of your clients before updating - ^ old entries in this folder will throw errors with v1.3.0 +- there are no technical breaking changes, but the UX has changed significantly due to the new argument system (detailed below) user-facing features: -- none - all changes were under-the-hood - the user experience should be -exactly the same as v1.2.0 - just faster, less buggy, and more secure +- when typing an entry/folder name, it is now always the FIRST argument + ^ e.g. instead of "sshyp copy -p /example/test", it would now be "sshyp /example/test copy -p" + ^ this allows more easily editing the previous command to copy/edit a different field +- better extension integration + ^ extensions can now ship with a config file that sshyp can use to call them from standard sshyp arguments + ^ the first extension supporting this is sshyp-mfa + ^ if sshyp-mfa v1.4.0.1+ is installed, "sshyp /example/test copy -m" will copy MFA keys to your clipboard +- entry/folder names now MUST be specified as arguments + ^ there is no longer a separate input prompt if the entry/folder name is not provided as an argument + ^ the input prompt was a legacy feature from before arguments could specify entrys/folders with shell completion + ^ the entry list generated by entry_list_gen() is still present and can be viewed by running "sshyp" with no arguments +- better Bash completions + ^ now correctly places backslashes to escape spaces in entry/folder names + ^ slightly faster than the previous iteration +- IPv6 configuration support -major fixes/optimizations: +fixes/optimizations: -- a near full re-write of the syncing functionality - ^ all syncing logic has been moved into sshync.py (from sshyp.py and sshypRemote.py) - ^ in my setup, a dry, local "sshyp sync" went from 2.00+ seconds (v1.2.0) to 0.36 seconds (v1.3.0) - ^ the performance improvements are even greater when syncing from outside your local network -- the following character sequences will no longer break the syncing logic: "@", "^&*", and "*&^" - ^ ASCII separator characters 29-31 are now used, instead -- os.system has been replaced with subprocess.run in all cases, shell=True is no longer used with subprocess.run - ^ this protects against shell escape attacks and potentially makes sshyp more compatible with some environments -- replaced shell commands with python built-in library functions where applicable - ^ this brings speed and compatibility improvements -- sshyp should no longer incorrectly assume an X11 environment when Wayland is in use - ^ this fixes clipboard support in some Wayland environments, such as Sway (Plasma/Gnome/Phosh were unaffected) -- sshyp now uses the default pinentry on Haiku thanks to haikuports/haikuports#7457 - ^ this brings the Haiku port in-line with the other sshyp packages in terms of security -- "python3" is now called over ssh, rather than "python" - ^ some environments do not have a "python" symlink, or it links to "python2" - changing this increases compatibility -- fixed an issue from v1.2.0 where renaming threw an error if not in offline mode +- replaced "+=" with ".append" when extending lists to prevent creating an additional list +- optimized usage of "str.split()" and replaced it with "str.splitlines()" where applicable +- more concise "if... in ()" syntax replaces long "if" statement chains +- lists have been substituted with tuples where applicable +- entry_list_gen() has been re-written to be much smaller and faster +- os.path is now used in place of pathlib.Path in areas where it is faster +- the user's home directory is saved to a variable to prevent running expanduser() every time it is needed other notable changes: -- quick-unlock password input is now hidden while the user is typing - ^ user input is now invisible to prevent snooping -- lots of smaller optimizations not listed here +- removed some uncommonly used, redundant arguments + ^ e.g. "-rm", "-s", "delete" + ^ their functionality was NOT removed, just their redundant arguments, since "shear", "sync", and "del" are the accepted syntax +- errors containing entry/folder names reinforce correct syntax by adding leading/following slashes where necessary +- thanks to pull request #25, there are new error messages for the read shortcut + ^ includes when no entry name is provided or the entry name only refers to a directory +- directories provided in user input are no longer denoted by a following slash + ^ instead, os.path is used to determine if the user is referring to a file or directory <><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><>