derivepassphrase.git

Release 0.6
Parent 3e1de59
Marco Ricci

Marco Ricci commited on 2026-04-02 21:52:33
Zeige 12 geänderte Dateien mit 186 Einfügungen und 193 Löschungen.

docs/changelog.d/20250804_213557_the-13th-letter_ssh_agent_socket_providers.md
Zeige Datei @ 3e1de59
... ... 
@@ -1,24 +0,0 @@
1 
-### Added
2 
-
3 
-  - For `derivepassphrase vault`, in the SSH agent client, introduce a new
4 
-    abstraction layer responsible for establishing the connection to the SSH
5 
-    agent: "SSH agent socket providers".
6 
-    Reframe the existing code for connecting to SSH agents on UNIX as
7 
-    a standard socket provider, and reserve a second standard socket
8 
-    provider, yet to be written, for <abbr title="Microsoft Windows">The
9 
-    Annoying Operating System</abbr>.
10 
-
11 
-    (The system is based on Python package [entry
12 
-    points][importlib.metadata.entry_points], and is open for third-party
13 
-    developers to develop their own socket providers in case the standard
14 
-    socket providers are insufficient.)
15 
-
16 
-  - `derivepassphrase vault --version` now defers testing for SSH agent
17 
-    support (the "master SSH key" feature) to the SSH agent client
18 
-    constructor, instead of examining the environment itself and drawing its
19 
-    own conclusions.
20 
-
21 
-  - For developers: Feature flags and similar enum values are now
22 
-    self-testing, i.e., they include [their own code for testing whether they
23 
-    are active/enabled/supported][derivepassphrase._types.FeatureTestEnum].
24 
-
docs/changelog.d/20251130_100242_the-13th-letter_modularize_and_refactor_test_machinery.md
Zeige Datei @ 3e1de59
... ... 
@@ -1,11 +0,0 @@
1 
-### Fixed
2 
-
3 
-  - Officially and systematically test on Python 3.14.
4 
-
5 
-    Unofficial, non-systematic testing was already being done since v0.5.
6 
-
7 
-  - For developers: Refactor the test suite into more fine-grained modules,
8 
-    and deduplicate code in the test methods in favor of parametrization.
9 
-    Both measures should make the test suite easier to navigate and less
10 
-    prone to copy-and-paste and code desynchronization mistakes.
11 
-
docs/changelog.d/20251130_102427_the-13th-letter_ssh_agent_socket_providers.md
Zeige Datei @ 3e1de59
... ... 
@@ -1,28 +0,0 @@
1 
-### Changed
2 
-
3 
-  - The error message "Cannot connect to an SSH agent because this Python
4 
-    version does not support UNIX domain sockets." (code: `NO_AF_UNIX`) now
5 
-    reads "Cannot connect to an SSH agent because this Python version does
6 
-    not support communicating with it." and has a new code
7 
-    (`NO_AGENT_SUPPORT`).
8 
-    `derivepassphrase` may also try out certain communication channels
9 
-    (depending on the installation environment), and issue warnings relating
10 
-    to its failure to establish communication on those channels, before
11 
-    issuing the above error.
12 
-
13 
-    The `NO_AF_UNIX` code is reused by the new warning message "Cannot
14 
-    connect to an SSH agent via UNIX domain sockets because this Python
15 
-    version does not support them.", which is one of the aforementioned
16 
-    related warning messages.
17 
-
18 
-    The manpages document both the old and the new codes, with appropriate
19 
-    notices.
20 
-
21 
-### Fixed
22 
-
23 
-  - For developers: The manpage diagnostics helper scripts now explicitly
24 
-    support documentation of message codes that exist only as marks in the
25 
-    manpages, not in the program code.
26 
-    This allows documenting message codes that have since been removed from
27 
-    the program code.
28 
-
docs/changelog.d/20251213_154843_the-13th-letter_fix_key_to_phrase_missing_callback.md
Zeige Datei @ 3e1de59
... ... 
@@ -1,14 +0,0 @@
1 
-### Changed
2 
-
3 
-  - For developers: The internal helper function
4 
-    `derivepassphrase._internals.cli_helpers.key_to_phrase` now takes
5 
-    mandatory callback parameters to handle warning and error messages.
6 
-    This is a side-effect of the "SSH agent socket providers" system, which
7 
-    necessitates more complicated error and warning handling.
8 
-
9 
-    We considered making the callback parameters optional and supplying
10 
-    a default handler that suppress warnings and exit on error, but then we
11 
-    learned the hard way that those defaults make it too easy to suppress
12 
-    warnings *by accident*, just because we forgot to supply a certain
13 
-    function parameter.
14 
-
docs/changelog.d/20260322_222936_the-13th-letter_annoying_os_named_pipes.md
Zeige Datei @ 3e1de59
... ... 
@@ -1,104 +0,0 @@
1 
-### Added
2 
-
3 
-  - For `derivepassphrase vault`, support interacting with SSH agents on
4 
-    <abbr title="Microsoft Windows">The Annoying OS</abbr>, using Windows
5 
-    named pipes and the `SSH_AUTH_SOCK` environment variable.
6 
-    Also support the two major SSH agents Pageant ([PuTTY][]) and
7 
-    `ssh-agent` ([OpenSSH][]) specifically, without needing the user to
8 
-    specify the address of the Windows named pipe.
9 
-    [GnuPG][]'s `gpg-agent` (masquerading as OpenSSH's `ssh-agent`) is also
10 
-    known to work.
11 
-
12 
-    This support is based on the [`ctypes.WinDLL`][ctypes.WinDLL] interface,
13 
-    and requires access to the `kernel32.dll` library on <abbr
14 
-    title="Microsoft Windows">The Annoying OS</abbr> at runtime.
15 
-    `derivepassphrase vault --version` will reliably report whether this
16 
-    feature -- the `windows_named_pipe`, `pageant_on_windows` and
17 
-    `openssh_on_windows` SSH agent socket providers -- is available.
18 
-
19 
-    <b>Caveat</b>: On <abbr title="Microsoft Windows">The Annoying
20 
-    OS</abbr>, the user or developer should [mark all SSH agents as
21 
-    non-reentrant](#changed-in-v0.6-non-reentrant-ssh-agents) and run the
22 
-    test suite without parallelization, because the test suite cannot spawn
23 
-    isolated agents on <abbr title="Microsoft Windows">The Annoying
24 
-    OS</abbr>.
25 
-    The OpenSSH agent implementation interacts very badly with the feature
26 
-    detection logic from the test suite, because it shuts down the
27 
-    connection upon negative responses of any kind (in violation of the
28 
-    protocol); the user or developer may want to use GnuPG's emulation
29 
-    instead, or restrict themselves to PuTTY.
30 
-    →[:material-bug:][BUG_WINDOWS_SSH_AGENT_SUPPORT]
31 
-
32 
-  - For `derivepassphrase vault`, support specifying the desired SSH agent
33 
-    socket provider via the command-line option
34 
-    `--ssh-agent-socket-provider` and via the configuration option
35 
-    `ssh-agent-socket-provider` in the `vault` table.
36 
-    The list of available providers can be queried with `derivepassphrase
37 
-    vault --version`.
38 
-    The command-line option takes precedence over the configuration option.
39 
-
40 
-### Changed
41 
-
42 
-  - For developers: The test suite now distinguishes between
43 
-    <dfn>isolated</dfn> SSH agents (spawned and managed by the test suite)
44 
-    and non-isolated ones (spawned by the user, potentially in use by other
45 
-    programs).
46 
-
47 
-    All tests involving SSH agents are included in a separate group, so that
48 
-    the test harness distributes them to the same worker process.
49 
-
50 
-  - For developers: The test suite now supports <b
51 
-    id="changed-in-v0.6-selective-ssh-agent-testing">selectively enabling
52 
-    SSH agents to test with</b> via the `PERMITTED_SSH_AGENTS` environment
53 
-    variable, which takes a comma-separated list of internal IDs of known
54 
-    SSH agent implementations.
55 
-    (Invalid entries are silently ignored.)
56 
-    The test suite will only attempt to spawn or interface with agents of
57 
-    permitted types, and skip tests otherwise.
58 
-
59 
-    Intended to avoid spawning certain SSH agents just because they are
60 
-    installed, or spawning unrelated executables that are mistaken for
61 
-    the respective SSH agent due to identical executable names.
62 
-
63 
-  - For developers: The test suite now supports <b
64 
-    id="changed-in-v0.6-non-reentrant-ssh-agents">marking SSH agents as
65 
-    non-reentrant</b> via the `NON_REENTRANT_SSH_AGENTS` environment
66 
-    variable, which takes a comma-separated list of internal IDs of known
67 
-    SSH agent implementations.
68 
-    (Invalid entries are silently ignored.)
69 
-    The test suite will avoid constructing multiple SSH agent clients
70 
-    connecting to such an SSH agent by reusing client instances, or skipping
71 
-    the test altogether.
72 
-
73 
-    Intended to avoid deadlocks with shared agent instances that do not
74 
-    cleanly support multiple simultaneous clients.
75 
-
76 
-      - [GnuPG][] v2.4.8 appears to use a single thread to both accept
77 
-        incoming SSH agent client connections and service them;
78 
-        running two clients simultaneously blocks the second client from
79 
-        connecting until the first client disconnects.
80 
-        This precludes normal usage in the test suite, where the test suite
81 
-        keeps a client connection to the agent open for the duration of the
82 
-        test run (to upload test keys at the beginning and remove them at
83 
-        the end).
84 
-
85 
-      - Pageant principally supports multiple simultaneous clients.
86 
-        However, the test suite sporadically triggers errors where responses
87 
-        from Pageant contain extra blocks of NUL characters, confusing
88 
-        `derivepassphrase`.
89 
-        We have not observed any such errors yet when treating Pageant as
90 
-        non-reentrant.
91 
-
92 
-        (So far, we have *only* been able to trigger these errors during
93 
-        test suite runs, not during instrumented calls specifically
94 
-        attempting to trigger this behavior.
95 
-        We are also unsure if this is a bug in Pageant, a bug in
96 
-        `derivepassphrase`, a bug or a limitation in Python's [`ctypes`][]
97 
-        implementation, or a bug or a limitation of Windows named pipes, or
98 
-        perhaps some combination of the aforementioned.)
99 
-
100 
-[BUG_WINDOWS_SSH_AGENT_SUPPORT]: ../wishlist/windows-ssh-agent-support.md
101 
-
102 
-[OpenSSH]: https://www.openssh.org
103 
-[PuTTY]: https://putty.software
104 
-[GnuPG]: https://gnupg.org
docs/changelog.md
Zeige Datei @ 7a4a1d4
... ... 
@@ -51,6 +51,176 @@ specifically marked as such.)
51 51
52 52 
 <!-- scriv changelog start -->
53 53
54 
+## 0.6 (2026-04-02)  {#v0.6}
55 
+
56 
+### Added  {#added-in-v0.6}
57 
+
58 
+  - For `derivepassphrase vault`, in the SSH agent client, introduce a new
59 
+    abstraction layer responsible for establishing the connection to the SSH
60 
+    agent: "SSH agent socket providers".
61 
+    Reframe the existing code for connecting to SSH agents on UNIX as
62 
+    a standard socket provider, and reserve a second standard socket
63 
+    provider, yet to be written, for <abbr title="Microsoft Windows">The
64 
+    Annoying OS</abbr>.[^the-annoying-os]
65 
+
66 
+    (The system is based on Python package [entry
67 
+    points][importlib.metadata.entry_points], and is open for third-party
68 
+    developers to develop their own socket providers in case the standard
69 
+    socket providers are insufficient.)
70 
+
71 
+  - `derivepassphrase vault --version` now defers testing for SSH agent
72 
+    support (the "master SSH key" feature) to the SSH agent client
73 
+    constructor, instead of examining the environment itself and drawing its
74 
+    own conclusions.
75 
+
76 
+  - For `derivepassphrase vault`, support interacting with SSH agents on
77 
+    <abbr title="Microsoft Windows">The Annoying OS</abbr>, using Windows
78 
+    named pipes and the `SSH_AUTH_SOCK` environment variable.
79 
+    Also support the two major SSH agents Pageant ([PuTTY][]) and
80 
+    `ssh-agent` ([OpenSSH][]) specifically, without needing the user to
81 
+    specify the address of the Windows named pipe.
82 
+    [GnuPG][]'s `gpg-agent` (masquerading as OpenSSH's `ssh-agent`) is also
83 
+    known to work.
84 
+
85 
+    This support is based on the [`ctypes.WinDLL`][] interface, and requires
86 
+    access to the `kernel32.dll` library on <abbr title="Microsoft
87 
+    Windows">The Annoying OS</abbr> at runtime.
88 
+    `derivepassphrase vault --version` will reliably report whether this
89 
+    feature -- the `windows_named_pipe`, `pageant_on_windows` and
90 
+    `openssh_on_windows` SSH agent socket providers -- is available.
91 
+
92 
+    <b>Caveat</b>: On <abbr title="Microsoft Windows">The Annoying
93 
+    OS</abbr>, the user or developer should [mark all SSH agents as
94 
+    non-reentrant](#changed-in-v0.6-non-reentrant-ssh-agents) and run the
95 
+    test suite without parallelization, because the test suite cannot spawn
96 
+    isolated agents on <abbr title="Microsoft Windows">The Annoying
97 
+    OS</abbr>.
98 
+    The OpenSSH agent implementation interacts very badly with the feature
99 
+    detection logic from the test suite, because it shuts down the
100 
+    connection upon negative responses of any kind (in violation of the
101 
+    protocol); the user or developer may want to use GnuPG's emulation
102 
+    instead, or restrict themselves to PuTTY.
103 
+    →[:material-bug:][BUG_WINDOWS_SSH_AGENT_SUPPORT]
104 
+
105 
+  - For `derivepassphrase vault`, support specifying the desired SSH agent
106 
+    socket provider via the command-line option
107 
+    `--ssh-agent-socket-provider` and via the configuration option
108 
+    `ssh-agent-socket-provider` in the `vault` table.
109 
+    The list of available providers can be queried with `derivepassphrase
110 
+    vault --version`.
111 
+    The command-line option takes precedence over the configuration option.
112 
+
113 
+  - For developers: Feature flags and similar enum values are now
114 
+    self-testing, i.e., they include [their own code for testing whether they
115 
+    are active/enabled/supported][derivepassphrase._types.FeatureTestEnum].
116 
+
117 
+### Changed  {#changed-in-v0.6}
118 
+
119 
+  - The error message "Cannot connect to an SSH agent because this Python
120 
+    version does not support UNIX domain sockets." (code: `NO_AF_UNIX`) now
121 
+    reads "Cannot connect to an SSH agent because this Python version does
122 
+    not support communicating with it." and has a new code
123 
+    (`NO_AGENT_SUPPORT`).
124 
+    `derivepassphrase` may also try out certain communication channels
125 
+    (depending on the installation environment), and issue warnings relating
126 
+    to its failure to establish communication on those channels, before
127 
+    issuing the above error.
128 
+
129 
+    The `NO_AF_UNIX` code is reused by the new warning message "Cannot
130 
+    connect to an SSH agent via UNIX domain sockets because this Python
131 
+    version does not support them.", which is one of the aforementioned
132 
+    related warning messages.
133 
+
134 
+    The manpages document both the old and the new codes, with appropriate
135 
+    notices.
136 
+
137 
+  - For developers: The internal helper function
138 
+    `derivepassphrase._internals.cli_helpers.key_to_phrase` now takes
139 
+    mandatory callback parameters to handle warning and error messages.
140 
+    This is a side-effect of the "SSH agent socket providers" system, which
141 
+    necessitates more complicated error and warning handling.
142 
+
143 
+    We considered making the callback parameters optional and supplying
144 
+    a default handler that suppress warnings and exit on error, but then we
145 
+    learned the hard way that those defaults make it too easy to suppress
146 
+    warnings *by accident*, just because we forgot to supply a certain
147 
+    function parameter.
148 
+
149 
+  - For developers: The test suite now distinguishes between
150 
+    <dfn>isolated</dfn> SSH agents (spawned and managed by the test suite)
151 
+    and non-isolated ones (spawned by the user, potentially in use by other
152 
+    programs).
153 
+
154 
+    All tests involving SSH agents are included in a separate group, so that
155 
+    the test harness distributes them to the same worker process.
156 
+
157 
+  - For developers: The test suite now supports <b
158 
+    id="changed-in-v0.6-selective-ssh-agent-testing">selectively enabling
159 
+    SSH agents to test with</b> via the `PERMITTED_SSH_AGENTS` environment
160 
+    variable, which takes a comma-separated list of internal IDs of known
161 
+    SSH agent implementations.
162 
+    (Invalid entries are silently ignored.)
163 
+    The test suite will only attempt to spawn or interface with agents of
164 
+    permitted types, and skip tests otherwise.
165 
+
166 
+    Intended to avoid spawning certain SSH agents just because they are
167 
+    installed, or spawning unrelated executables that are mistaken for
168 
+    the respective SSH agent due to identical executable names.
169 
+
170 
+  - For developers: The test suite now supports <b
171 
+    id="changed-in-v0.6-non-reentrant-ssh-agents">marking SSH agents as
172 
+    non-reentrant</b> via the `NON_REENTRANT_SSH_AGENTS` environment
173 
+    variable, which takes a comma-separated list of internal IDs of known
174 
+    SSH agent implementations.
175 
+    (Invalid entries are silently ignored.)
176 
+    The test suite will avoid constructing multiple SSH agent clients
177 
+    connecting to such an SSH agent by reusing client instances, or skipping
178 
+    the test altogether.
179 
+
180 
+    Intended to avoid deadlocks with shared agent instances that do not
181 
+    cleanly support multiple simultaneous clients.
182 
+
183 
+      - [GnuPG][] v2.4.8 appears to use a single thread to both accept
184 
+        incoming SSH agent client connections and service them;
185 
+        running two clients simultaneously blocks the second client from
186 
+        connecting until the first client disconnects.
187 
+        This precludes normal usage in the test suite, where the test suite
188 
+        keeps a client connection to the agent open for the duration of the
189 
+        test run (to upload test keys at the beginning and remove them at
190 
+        the end).
191 
+
192 
+      - Pageant principally supports multiple simultaneous clients.
193 
+        However, the test suite sporadically triggers errors where responses
194 
+        from Pageant contain extra blocks of NUL characters, confusing
195 
+        `derivepassphrase`.
196 
+        We have not observed any such errors yet when treating Pageant as
197 
+        non-reentrant.
198 
+
199 
+        (So far, we have *only* been able to trigger these errors during
200 
+        test suite runs, not during instrumented calls specifically
201 
+        attempting to trigger this behavior.
202 
+        We are also unsure if this is a bug in Pageant, a bug in
203 
+        `derivepassphrase`, a bug or a limitation in Python's [`ctypes`][]
204 
+        implementation, or a bug or a limitation of Windows named pipes, or
205 
+        perhaps some combination of the aforementioned.)
206 
+
207 
+### Fixed  {#fixed-in-v0.6}
208 
+
209 
+  - Officially and systematically test on Python 3.14.
210 
+
211 
+    Unofficial, non-systematic testing was already being done since v0.5.
212 
+
213 
+  - For developers: Refactor the test suite into more fine-grained modules,
214 
+    and deduplicate code in the test methods in favor of parametrization.
215 
+    Both measures should make the test suite easier to navigate and less
216 
+    prone to copy-and-paste and code desynchronization mistakes.
217 
+
218 
+  - For developers: The manpage diagnostics helper scripts now explicitly
219 
+    support documentation of message codes that exist only as marks in the
220 
+    manpages, not in the program code.
221 
+    This allows documenting message codes that have since been removed from
222 
+    the program code.
223 
+
54 224 
 ## 0.5.2 (2025-08-03)  {#v0.5.2}
55 225
56 226 
 ### Fixed  {#fixed-in-v0.5.2}
... ... 
@@ -66,7 +236,7 @@ specifically marked as such.)
66 236 
   - For developers: Fix some errors in the test suite (both code and
67 237 
     dependency declaration) that cause the suite to fail to even start on
68 238 
     <abbr title="Microsoft Windows">The Annoying
69 
-    OS</abbr>.[^the-annoying-os]
239 
+    OS</abbr>.
70 240 
     These mistakes were already present in v0.5.
71 241
72 242 
   - For developers: Fix a copy-and-paste error in the parsed data for the
... ... 
@@ -643,6 +813,10 @@ specifically marked as such.)
643 813
644 814 
 [RFC 6979]: https://www.rfc-editor.org/rfc/rfc6979
645 815
816 
+[OpenSSH]: https://www.openssh.org
817 
+[PuTTY]: https://putty.software
818 
+[GnuPG]: https://gnupg.org
819 
+
646 820 
 [CLI]: reference/derivepassphrase.1.md
647 821 
 [CLI_EXPORT]: reference/derivepassphrase-export.1.md
648 822 
 [CLI_EXPORT_VAULT]: reference/derivepassphrase-export-vault.1.md
pyproject.toml
Zeige Datei @ 7a4a1d4
... ... 
@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
6 6 
 name = "derivepassphrase"
7 7 
 description = "An almost faithful Python reimplementation of James Coglan's vault."
8 8 
 readme = "README.md"
9 
-version = "0.5.2"
9 
+version = "0.6"
10 10 
 requires-python = ">= 3.9"
11 11 
 license = { text = "zlib/libpng" }
12 12 
 keywords = []
... ... 
@@ -113,7 +113,7 @@ Issues = "https://the13thletter.info/derivepassphrase/latest/wishlist/"
113 113 
 Source = "https://git.schokokeks.org/derivepassphrase.git"
114 114
115 115 
 [tool.bumpversion]
116 
-current_version = "0.5.2"
116 
+current_version = "0.6"
117 117 
 # As of bump-my-version 0.32.0, version components are strictly
118 118 
 # hierarchical in the order of occurrence, and there is no support for
119 119 
 # pre-release markers.  The documentation suggests a fake "dev/rc/final"
share/man/man1/derivepassphrase-export-vault.1
Zeige Datei @ 7a4a1d4
... ... 
@@ -1,6 +1,6 @@
1 
-.Dd 2025-08-03
1 
+.Dd 2026-04-02
2 2 
 .Dt DERIVEPASSPHRASE-EXPORT-VAULT 1
3 
-.Os derivepassphrase 0.5.2
3 
+.Os derivepassphrase 0.6
4 4 
 .
5 5 
 .Sh NAME
6 6 
 .
share/man/man1/derivepassphrase-export.1
Zeige Datei @ 7a4a1d4
... ... 
@@ -1,6 +1,6 @@
1 
-.Dd 2025-08-03
1 
+.Dd 2026-04-02
2 2 
 .Dt DERIVEPASSPHRASE-EXPORT 1
3 
-.Os derivepassphrase 0.5.2
3 
+.Os derivepassphrase 0.6
4 4 
 .
5 5 
 .Sh NAME
6 6 
 .
share/man/man1/derivepassphrase-vault.1
Zeige Datei @ 7a4a1d4
... ... 
@@ -1,6 +1,6 @@
1 
-.Dd 2025-08-03
1 
+.Dd 2026-04-02
2 2 
 .Dt DERIVEPASSPHRASE-VAULT 1
3 
-.Os derivepassphrase 0.5.2
3 
+.Os derivepassphrase 0.6
4 4 
 .
5 5 
 .Sh NAME
6 6 
 .
share/man/man1/derivepassphrase.1
Zeige Datei @ 7a4a1d4
... ... 
@@ -1,6 +1,6 @@
1 
-.Dd 2025-08-03
1 
+.Dd 2026-04-02
2 2 
 .Dt DERIVEPASSPHRASE 1
3 
-.Os derivepassphrase 0.5.2
3 
+.Os derivepassphrase 0.6
4 4 
 .
5 5 
 .Sh NAME
6 6 
 .
src/derivepassphrase/__init__.py
Zeige Datei @ 7a4a1d4
... ... 
@@ -9,5 +9,5 @@ __distribution_name__ = "derivepassphrase"
9 9
10 10 
 # Automatically generated.  DO NOT EDIT! Use importlib.metadata instead
11 11 
 # to query the correct values.
12 
-__version__ = "0.5.2"
12 
+__version__ = "0.6"
13 13 
 # END automatically generated.
14 14