derivepassphrase.git

@@ -9,7 +9,8 @@ derivepassphrase-vault – derive a passphrase using the vault derivation scheme

 <pre>

 <code><b>derivepassphrase vault</b> [--phrase | --key] [--length <var>n</var>] [--repeat <var>n</var>] [--lower <var>n</var>] [--upper <var>n</var>] [--number <var>n</var>] [--space <var>n</var>] [--dash <var>n</var>] [--symbol <var>n</var>] <var>SERVICE</var></code>

 <code><b>derivepassphrase vault</b> {--phrase | --key | … | --symbol <var>n</var>} … --config [--unset <var>setting</var> …] [--overwrite-existing | --merge-existing] [<var>SERVICE</var>]</code>

-<code><b>derivepassphrase vault</b> {--notes <var>SERVICE</var> | --delete <var>SERVICE</var> | --delete-globals | --clear}</code>

+<code><b>derivepassphrase vault</b> [--phrase | --key | … | --symbol <var>n</var>] … --config --notes [--unset <var>setting</var> …] [--overwrite-existing | --merge-existing] [--modern-editor-interface | --vault-legacy-editor-interface] <var>SERVICE</var></code>

+<code><b>derivepassphrase vault</b> {--delete <var>SERVICE</var> | --delete-globals | --clear}</code>

 <code><b>derivepassphrase vault</b> [--export-as {json | sh}] {--import <var>PATH</var> | --export <var>PATH</var>}</code>

 </pre>

@@ -30,7 +31,7 @@ In lieu of a master passphrase, a master SSH key can also be used if there is a

 The passphrase generation options can be divided into "passphrase source" options (`--phrase`, `--key`) and "passphrase constraint" options (all others).

 The passphrase source options are mutually exclusive --- you may only specify one of them --- while the passphrase constraint options may be combined in any way.

-The <var>SERVICE</var> is mandatory (see synopsis #1), unless the `--config` option is specified (see synopsis #2).

+The <var>SERVICE</var> is mandatory (see synopsis #1 and #3), unless the `--config` option is specified and the `--notes` option is not (see synopsis #2).

 All character constraints refer to ASCII printable characters only (space (`U+0020`) to tilde (`U+007E`), excluding the grave accent (`U+0060`)).

 <b>-p</b>, <b>-</b><b>-phrase</b>

@@ -88,17 +89,20 @@ All character constraints refer to ASCII printable characters only (space (`U+00

 ### Configuration

 The configuration options directly modify the stored settings: default settings, known services, and service-specific settings.

-They are mutually exclusive; you may only specify one of them.

-The <var>SERVICE</var> is mandatory for `--notes` and `--delete`, optional for `--config`, and forbidden for `--delete-globals` and `--clear` (see synopsis #2 and synopsis #3).

+The `--notes` option requires the `--config` option, and modifies its operation.

+All others are mutually exclusive; you may only specify one of them.

+The <var>SERVICE</var> is mandatory for `--notes` and `--delete`, optional for `--config`, and forbidden for `--delete-globals` and `--clear` (see synopses #2, #3 and #4).

 <b>-n</b>, <b>-</b><b>-notes</b>

 :   Spawn an editor to edit notes for <var>SERVICE</var>.

     Use the `VISUAL` or `EDITOR` environment variables to configure the spawned editor.

+    Must be used together with `--config` to have any effect.

 <b>-c</b>, <b>-</b><b>-config</b>

 :   Save the given settings for <var>SERVICE</var> (if given), or save the given settings as global default settings.

-    See the ["Passphrase generation"](#passphrase-generation) and ["Compatibility and extension options"](#compatibility-and-extension-options) sections for other options compatible with `--config`.

+    The `--notes` option is compatible with `--config`.

+    See the ["Passphrase generation"](#passphrase-generation) and ["Compatibility and extension options"](#compatibility-and-extension-options) sections for other compatible options.

     !!! danger

@@ -156,6 +160,20 @@ The compatibility and extension options modify the behavior to enable additional

     (vault(1) behaves as if `--export-as json` were always given.)

+<b>-</b><b>-modern-editor-interface</b> | <b>-</b><b>-vault-legacy-editor-interface</b>

+:   When editing notes, use a modern editor interface similar to <i>git</i>(1), or use the <i>vault</i>(1) legacy editing interface.

+

+    The modern editor interface supports aborting the edit (i.e., leaving the stored notes (if any) unchanged) by leaving the edited file empty, and automatically removes the editing instructions text (which it inserts into the file prior to editing).

+    This is similar to how version-control systems/source code management systems such as <i>git</i>(1), <i>hg</i>(1) or <i>svn</i>(1) use text editors for commit messages.

+

+    The <i>vault</i>(1) legacy editing interface uses the file contents directly, including any leftover editing instructions, and does not support aborting the edit.

+    Its use is not recommended, unless required for compatibility.

+

+    <b>derivepassphrase vault</b> will use different editing instructions texts to reflect the editing interface in use.

+    Additionally, for the legacy editing interface, a backup of the old notes contents will be stored in the configuration directory if the new notes differ from the old notes, to mitigate the risk of data loss because the edit cannot be aborted.

+

+    (vault(1) behaves as if `--vault-legacy-editor-interface` were always given.)

+

 ### Other Options

 <b>-</b><b>-debug</b>

@@ -216,6 +234,9 @@ This is a property specific to the key type, and sometimes the agent used:

 :   The stored configuration for <b>derivepassphrase vault</b>: the default passphrase generation settings, the known service names, and the service-specific settings.

     This file is <em>not</em> intended for the user to edit.

+`$DERIVEPASSPHRASE_PATH/old-notes.txt`

+:   A backup copy of the old notes from the last successful notes editing operation, using the <i>vault</i>(1) legacy editor interface.

+

 ## SECURITY

 !!! danger

@@ -428,6 +449,15 @@ The <b>derivepassphrase vault</b> utility exits 0 on success, and >0 if an error

     A configuration file has been renamed.

     <b>derivepassphrase vault</b> will attempt to rename the file itself (`Successfully migrated to %s.`), or complain if it cannot rename it (`Failed to migrate to %s: %s`).

+??? warning "`Specifying --notes without --config is ineffective.`"

+

+    (Exactly what it says.)

+

+??? warning "`A backup copy of the notes was saved to %s.`"

+

+    The <i>vault</i>(1) legacy editor interface is in use, which carries a high risk of accidentally losing or corrupting the old notes because a notes editing session cannot be aborted mid-editing.

+    To guard against such accidental data loss, a backup copy of the old notes was saved to the <b>derivepassphrase</b> configuration directory.

+

 ## COMPATIBILITY

 ### With other software

@@ -31,10 +31,16 @@

 .Op Ar SERVICE

 .

 .Nm derivepassphrase vault

-.Bro

-.Fl \-notes

+.Op Fl \-phrase | \-key | No .\|.\|. | Fl \-symbol Ar n

+.No .\|.\|.

+.Fl \-config \-notes

+.Op Fl \-unset Ar setting No .\|.\|.

+.Op Fl \-overwrite\-existing | Fl \-merge\-existing

+.Op Fl \-modern\-editor\-interface | Fl \-vault-legacy-editor-interface

 .Ar SERVICE

-|

+.

+.Nm derivepassphrase vault

+.Bro

 .Fl \-delete

 .Ar SERVICE

 |

@@ -104,9 +110,11 @@ specify one of them \(em while the passphrase constraint options may be

 combined in any way.

 The

 .Ar SERVICE

-is mandatory (see synopsis\~#1), unless the

+is mandatory (see synopsis\~#1 and #3), unless the

 .Fl \-config

-option is specified (see synopsis\~#2).

+option is specified and the

+.Fl \-notes

+option is not (see synopsis\~#2).

 All character constraints refer to ASCII printable characters only (space

 .Pq Li U+0020

 to tilde

@@ -234,7 +242,12 @@ The default is to not constain the occurrences in any manner.

 .

 The configuration options directly modify the stored settings: default

 settings, known services, and service-specific settings.

-They are mutually exclusive; you may only specify one of them.

+The

+.Fl \-notes

+option requires the

+.Fl \-config

+option, and modifies its operation.

+All others are mutually exclusive; you may only specify one of them.

 The

 .Ar SERVICE

 is mandatory for

@@ -247,7 +260,7 @@ and forbidden for

 .Fl \-delete\-globals

 and

 .Fl \-clear

-(see synopsis\~#2 and synopsis\~#3).

+(see synopses\~#2, #3 and #4).

 .

 .Bl -tag -width ".Fl p , \-phrase"

 .

@@ -259,6 +272,9 @@ Use the

 or

 .Ev EDITOR

 environment variables to configure the spawned editor.

+Must be used together with

+.Fl \-config

+to have any effect.

 .

 .It Fl c , \-config

 Save the given settings for

@@ -266,12 +282,15 @@ Save the given settings for

 (if given), or save the given settings as global default settings.

 .Pp

 .

+The

+.Fl \-notes

+option is compatible with

+.Fl \-config .

 See the

 .Sx Passphrase generation

 and

 .Sx Compatibility and extension options

-sections for other options compatible with

-.Fl \-config .

+sections for other compatible options.

 .Pp

 .

 .Bf -symbolic

@@ -402,6 +421,48 @@ behaves as if

 .Fl \-export\-as Li json

 were always given.)

 .

+.It Fl \-modern\-editor\-interface | Fl \-vault\-legacy\-editor\-interface

+When editing notes, use a modern editor interface similar to

+.Xr git 1 ,

+or use the

+.Xr vault 1

+legacy editing interface.

+.Pp

+.

+The modern editor interface supports aborting the edit

+.Pq i.e., leaving the stored notes (if any) unchanged

+by leaving the edited file empty, and automatically removes the editing

+instructions text (which it inserts into the file prior to editing).

+This is similar to how version-control systems/source code management systems

+such as

+.Xr git 1 ,

+.Xr hg 1

+or

+.Xr svn 1

+use text editors for commit messages.

+.Pp

+.

+The

+.Xr vault 1

+legacy edititng interface uses the file contents directly, including any

+leftover editing instructions, and does not support aborting the edit.

+Its use is not recommended, unless required for compatibility.

+.Pp

+.

+.Nm derivepassphrase vault

+will use different editing instructions texts to reflect the editing

+interface in use.

+Additionally, for the legacy editing interface, a backup of the old notes

+contents will be stored in the configuration directory if the new notes differ

+from the old notes, to mitigate the risk of data loss because the edit cannot

+be aborted.

+.Pp

+.

+.Xr ( vault 1

+behaves as if

+.Fl \-vault\-legacy\-editor\-interface

+were always given.)

+.

 .El

 .

 .Ss Other options

@@ -548,6 +609,12 @@ This file is

 .Em not

 intended for the user to edit.

 .

+.It Ev $DERIVEPASSPHRASE_PATH Ns Pa /old-notes.txt

+A backup copy of the old notes from the last successful notes editing

+operation, using the

+.Xr vault 1

+legacy editor interface.

+.

 .El

 .

 .Sh SECURITY

@@ -871,6 +938,20 @@ will attempt to rename the file itself

 or complain if it cannot rename it

 .Pq Qq Li Failed to migrate to %s: %s .

 .

+.It Specifying \-\-notes without \-\-config is ineffective.

+(Exactly what it says.)

+.

+.It A backup copy of the notes was saved to %s.

+The

+.Xr vault 1

+legacy editor interface is in use, which carries a high risk of

+accidentally losing or corrupting the old notes because a notes editing

+session cannot be aborted mid-editing.

+To guard against such accidental data loss, a backup copy of the old

+notes was saved to the

+.Nm derivepassphrase

+configuration directory.

+.

 .El

 .

 .Sh COMPATIBILITY

@@ -828,9 +828,8 @@ class Label(enum.Enum):

     )

     """"""

     DERIVEPASSPHRASE_VAULT_NOTES_LEGACY_INSTRUCTION_TEXT = commented(

-        "This instruction text is shown above the user's old stored notes "

-        'for this service, if any, if the vault(1)-compatible '

-        '"legacy" editor interface is used.  '

+        'This instruction text is shown if the vault(1)-compatible '

+        '"legacy" editor interface is used and no previous notes exist.  '

         'The interface does not support commentary in the notes, '

         'so we fill this with obvious placeholder text instead.  '

         '(Please replace this with what *your* language/culture would '

@@ -1820,10 +1819,10 @@ class WarnMsgTemplate(enum.Enum):

         '',

     )(

         'Warning message',

-        'Using the vault(1)-compatible legacy editor interface, '

-        'which does not allow aborting mid-edit.  '

-        'A backup copy of the old notes was saved to {filename!r} '

-        'to guard against editing mistakes.',

+        'A backup copy of the old notes was saved to {filename!r}.  '

+        'This is a safeguard against editing mistakes, because the '

+        'vault(1)-compatible legacy editor interface does not allow '

+        'aborting mid-edit, and because the notes were actually changed.',

         flags='python-brace-format',

     )

     PASSPHRASE_NOT_NORMALIZED = commented(

@@ -1423,7 +1423,7 @@ def derivepassphrase_vault(  # noqa: C901,PLR0912,PLR0913,PLR0914,PLR0915

                         old_notes_value,

                     ])

                 else:

-                    text = str(notes_legacy_instructions)

+                    text = old_notes_value or str(notes_legacy_instructions)

                 notes_value = click.edit(text=text, require_save=False)

                 assert notes_value is not None

                 if (

@@ -2543,8 +2543,6 @@ class TestCLI:

             assert result.clean_exit(), 'expected clean exit'

             assert all(map(is_warning_line, result.stderr.splitlines(True)))

             assert modern_editor_interface or tests.warning_emitted(

-                'Using the vault(1)-compatible legacy editor interface, '

-                'which does not allow aborting mid-edit.  '

                 'A backup copy of the old notes was saved',

                 caplog.record_tuples,

             ), 'expected known warning message in stderr'

@@ -2737,8 +2735,6 @@ class TestCLI:

                 map(is_warning_line, result.stderr.splitlines(True))

             )

             assert not caplog.record_tuples or tests.warning_emitted(

-                'Using the vault(1)-compatible legacy editor interface, '

-                'which does not allow aborting mid-edit.  '

                 'A backup copy of the old notes was saved',

                 caplog.record_tuples,

             ), 'expected known warning message in stderr'