Recent commits to derivepassphrase.git (5bcd2c39308880309286a2243e3795833817d1a5)

Add debugging attributes to `ssh_agent.TrailingDataError`

2025-12-27T14:43:35+01:00

The old implementation did not record *which* trailing data we were
seeing, on the grounds that well-behaved SSH agents would not send any
trailing data anyway (i.e., that this error condition was a failsafe).
However, while implementing Windows named pipe support, I observed
Pageant sporadically returning malformed responses that trigger this
error.  Without actually recording the trailing data, it is hard to
understand whether this is Pageant's fault (unlikely) or ours (more
likely), and specifically, whether we're implementing the protocol
incorrectly (unlikely), or rather the communication channel (much more
likely).  So the `TrailingDataError` class now optionally records the
actual raw response and the trailing data portion that caused the error,
to aid debugging.
</pre>

Reparametrize the `socketprovider.SocketProvider.register` decorator

2025-12-26T12:25:39+01:00

Use parametric types to allow better introspection into decorated
classes.
</pre>

Update the documentation on SSH agent support on Windows

2025-12-25T23:37:49+01:00

The how-to "How to set up derivepassphrase vault with an SSH key" and
the reference documentation "Prerequisites for using derivepassphrase
vault with an SSH key" include new sections on Pageant and OpenSSH on
Windows.  For the latter, the "prerequisites" document also includes
information on the deficiencies of the Windows port of OpenSSH, i.e.,
that the connection is aborted upon receiving unsupported requests (in
violation of the communication protocol) and that the port lacks the
features which normally distinguish OpenSSH from Pageant.

We also expand the section on GnuPG's OpenSSH emulation on Windows in
the "prerequisites" document: that the mode is untested because the
documentation is wrong, and that we're now waiting for feedback from the
GnuPG developers.
</pre>

Reformat some documentation to one-sentence-per-line

2025-12-25T16:51:03+01:00

</pre>

Use relative imports in conftest.py

2025-12-25T16:25:15+01:00

</pre>

Sanity-test the returned agent client with loaded test keys

2025-12-25T14:44:46+01:00

Add sanity checks for the constructed agent client with optimistically
loaded test keys.  The docstring asserts that the test fixture will skip
if no keys can be loaded, but that wasn't the case.  Furthermore, while
there is little point in sanity testing the client when it is first
received (from a different fixture, which does its own sanity checks),
it makes sense to sanity-test the client *after* attempting to load all
those test keys into the agent, because certain misbehaved agents
terminate upon encountering unsupported key formats (see inline
commentary), rendering the client non-functional.

However, do not check whether the stubbed test agent can load the test
keys.  The stubbed test agent accesses the test keys directly, and only
the test keys; whether the "load keys" operation succeeds or not is
completely irrelevant.  There is also little point in actually
implementing the load operation: it is just more code that needs
coverage, and dedicated tests.
</pre>

Introduce SSH agent interfacing on The Annoying OS in the test suite

2025-12-25T14:33:08+01:00

Introduce SSH agent spawning functions that interface with running SSH
agents on The Annoying OS.  Also officially activate interfacing with
the system SSH agent on The Annoying OS, now that there are working SSH
agent socket providers on The Annoying OS that do not require UNIX
domain socket support.  Because the socket provider registry drastically
changed shape since d675b049fd32c5a652f73467f9462f45ddb1ec89, also
update the tests referencing registry entries to use the correct
non-alias base entry, if needed.

The two most common agents on The Annoying OS, PuTTY/Pageant and OpenSSH
on Windows, do not support session- or subshell-scoped spawning as they
do on UNIX.  So technically, these new "spawning" functions are actually
"interfacing" functions.  Introduce a matching type
`SSHAgentInterfaceFunc` for these functions, as aluded to in a previous
commit.  Because the type does not return a process object, consumers of
`SSHAgentSpawnFunc | SSHAgentInterfaceFunc` need to be adapted
accordingly, leading to a couple of code changes.
</pre>

Move the dependent SSH agent spawn handler table closer to the original one

2025-12-25T14:13:42+01:00

In the testing machinery, move the "SSH agent spawn handler params"
table, closer to the "SSH agent spawn handlers" table.  The former is
used as a parametrization set for some pytest fixtures, and is further
filtered by both environment variables as well as pytest marks.  Keeping
these two tables closer together makes it easier to debug the SSH agent
spawning machinery.
</pre>

Rename testing symbols in anticipation of The Annoying OS support

2025-12-25T12:34:37+01:00

Rename the `pageant` spawn handler to `unix-pageant`, the `ssh-agent`
handler to `openssh`, and the `(system)` handler to `(system-agent)`.
Similarly, rename the `Pageant` known SSH agent type to `UNIXPageant`,
for the same reason.  Since Pageant on The Annoying OS is the common
configuration, and Pageant on UNIX is the exceptional configuration,
Pageant on UNIX gets a decoration (the `unix-` or `UNIX` prefix).
OpenSSH, on the other hand, has its default configuration on UNIX, and
so gets no such decoration.

Rename the `MANGLE_SSH_AUTH_SOCK` and `UNSET_SSH_AUTH_SOCK` socket
address actions into `MANGLE_ADDRESS` and `UNSET_ADDRESS`, and add some
minor additional documentation.  Also subsume the
`MANGLE_WINDOWS_NAMED_PIPE` and `UNSET_WINDOWS_NAMED_PIPE` actions,
which are so far unused.  The desire to mangle or unset the address for
testing purposes is independent of the actual technology used to connect
to the SSH agent, so it makes no sense to have separate symbols per
connection technology.

Rename the `SpawnFunc` type to `SSHAgentSpawnFunc`.  A matching
`SSHAgentInterfaceFunc` is soon to follow, which would have a very
uninformative name if only named "Interface Func".
</pre>

Formalize SSH agent spawn handlers (in testing) as a real type

2025-12-25T12:32:59+01:00

Introduce a proper formal type for SSH agent spawn handlers in the test
configuration (as a type-checked named tuple).  This alone increases
readability by removing the tuple indices (magic numbers) from the code.

Also use this opportunity to introduce a real label and an explicit key
for each entry, instead of (ab)using the executable name for these
purposes.  The executable name is no longer usable as a unique key if
the SSH agent behaves differently (with respect to spawning) on
different operating systems... as is the case for both PuTTY/Pageant and
OpenSSH.
</pre>