Recent commits to derivepassphrase.git (41029a5e6ef04a9870dcaf044b54a26af94260ab)

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 0123456789abcdef, 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>

Rename all stubbed test agents in a consistent manner

2025-12-25T12:31:13+01:00

All stubbed agents should either be named `stub_agent` or start with
`stub_agent_`.

Also, the test suite spawns the "stubbed agent with address and with
deterministic DSA support" as "the more complicated stub agent", and the
"stubbed agent with extensions" as "the plain stubbed agent".  The
parametrization keys however suggest otherwise, that the choice is
between the "stubbed agent with extensions" and the "base stubbed
agent".  Fix the keys, and the returned `RunningSSHAgentInfo` structure.

(The stubbed agent with extensions is the first agent to support
specifying the address to connect to, which the test suite realistically
needs to manipulate.  The base stubbed agent *is* tested directly,
however, for all functionality tests of the family of stubbed agents.)
</pre>

Fix some testing edge cases, formatting hiccups and missing debugging aids

2025-12-25T11:34:27+01:00

Fix some testing edge cases:

- When re-registering existing SSH agent socket provider names, we now
  explicitly ensure that the set of (automatically determined) names is
  actually non-empty.

- Using mangled `SSH_AUTH_SOCK` environment variables for test purposes
  requires `SSH_AUTH_SOCK` to actually be set.  We supply a default name
  that is also invalid as a (non-directory) filename.

Fix some unclear debugging aids:

- Mangling `SSH_AUTH_SOCK` is (anecdotally) better at detecting faulty
  test setups, relative to the "unset `SSH_AUTH_SOCK`" entry (because
  failures in the latter tend to be silent).  So, reorder the
  parametrizations to prioritize the former one over the latter one.

- The SSH agent socket provider system was printing distribution names
  without checking for `None` distributions.

- The `spawn_ssh_agent` fixture was printing exception messages
  directly, without the exception name, or the concrete parametrization.
  We now special-case `KeyError` instances (but not subclass instances).

Fix other phrasings and formattings:

- The skip message for SSH agents excluded via the `PERMITTED_AGENTS`
  environment variable was not a sentence, and just speaking of
  "agents", not "SSH agents".
</pre>

Fix some test names, import statements, and test formatting

2025-12-24T10:37:29+01:00

</pre>

Implement Windows named pipes on The Annoying OS

2025-12-17T14:14:03+01:00

Using the `ctypes` module, call into The Annoying OS's system libraries
and bind the functions necessary to create, read from/write to, and
close handles to existing Windows named pipes.  We also bind the
functions necessary to compute the pipe name for PuTTY/Pageant, and
provide convenience functions to connect to PuTTY/Pageant and to
OpenSSH, the de facto main SSH implementations on The Annoying OS.

One major design question remains: how to discover the (named pipe
address for) the SSH agent to use?  Tempting options are using
`SSH_AUTH_SOCK` again (whether literally or with special notation), and
listing the preferred agent addresses in the user configuration file.

For certain "well-known" addresses such as PuTTY/Pageant or OpenSSH, we
provide specific SSH agent socket provider registry entries that attempt
to connect to the respective agent. Other applications could easily
register a custom provider that respects their configuration if the
final socket (address) depends on external configuration.  It is thus
not clear to me if the system needs to be more flexible than it
currently is, e.g., if the SSH agent socket provider needs to accept
arguments that further configure the address or the connection options
to the socket or named pipe.

This commit contains no specific test code for this functionality; we
leave this to follow-up commits.  We provide three SSH agent socket
providers, two of which have hardcoded addresses (for PuTTY/Pageant and
OpenSSH, respectively).  For ease of integration with the existing test
suite, *as a temporary measure*, the third provider attempts to use
`SSH_AUTH_SOCK` directly as the named pipe's name (which will fail
unless specifically prepared).

Since many of the symbols are undefined on other operating systems, and
because the `ctypes` library relies on dynamically generated attributes
and is thus mostly invisible to static analysis tools, much of the code
needs type checking exemptions and extraneous explicit (C) casts at the
Python level.  Additionally, because our stub functions use the same
CamelCase naming as The Annoying OS's official documentation does, much
of the code also needs linting exceptions for the naming policy.
</pre>

Settle on the terminology "UNIX domain socket" and "Windows named pipe"

2025-12-17T14:04:14+01:00

The formal name for the named pipe facility on The Annoying OS is
"Windows named pipe", and this is the name other developers will expect.
Thus, for reasons of clarity, we now strictly refer to them as such,
i.e., refer to them as "Windows named pipes" and not "The Annoying OS
named pipes".  Old names still using the "Annoying OS named pipe"
moniker have been adapted accordingly; in particular, this includes the
former `WarnMsgTemplate.NO_ANNOYING_OS_NAMED_PIPES` symbol.

By a similar token, the machine-local network socket mechanism on POSIX
systems is formally called "UNIX domain sockets".  For reasons of
clarity, we now refer to them as such, and not by their C constant name
`AF_UNIX` (or "AfUnix", or similar).  Old names have been adapted
accordingly; in particular, this includes the former
`WarnMsgTemplate.NO_AF_UNIX` symbol.
</pre>

Merge topic branch 'fix-key_to_phrase-missing-callback' into master

2025-12-13T15:57:40+01:00

* fix-key_to_phrase-missing-callback:
  Add changelog entry for the `key_to_phrase` missing callback argument fix
  Add missing `warning_callback` argument to `key_to_phrase` call
</pre>