derivepassphrase.git

@@ -1225,6 +1225,57 @@

     </label>

     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>

+        <li class="md-nav__item">

+  <a href="#v0.5" class="md-nav__link">

+    <span class="md-ellipsis">

+      0.5 (2025-06-14)

+    </span>

+  </a>

+  

+    <nav class="md-nav" aria-label="0.5 (2025-06-14)">

+      <ul class="md-nav__list">

+        

+          <li class="md-nav__item">

+  <a href="#removed-in-v0.5" class="md-nav__link">

+    <span class="md-ellipsis">

+      Removed

+    </span>

+  </a>

+  

+</li>

+        

+          <li class="md-nav__item">

+  <a href="#added-in-v0.5" class="md-nav__link">

+    <span class="md-ellipsis">

+      Added

+    </span>

+  </a>

+  

+</li>

+        

+          <li class="md-nav__item">

+  <a href="#changed-in-v0.5" class="md-nav__link">

+    <span class="md-ellipsis">

+      Changed

+    </span>

+  </a>

+  

+</li>

+        

+          <li class="md-nav__item">

+  <a href="#fixed-in-v0.5" class="md-nav__link">

+    <span class="md-ellipsis">

+      Fixed

+    </span>

+  </a>

+  

+</li>

+        

+      </ul>

+    </nav>

+  

+</li>

+      

         <li class="md-nav__item">

   <a href="#v0.4.0" class="md-nav__link">

     <span class="md-ellipsis">

@@ -1676,6 +1727,57 @@

     </label>

     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>

+        <li class="md-nav__item">

+  <a href="#v0.5" class="md-nav__link">

+    <span class="md-ellipsis">

+      0.5 (2025-06-14)

+    </span>

+  </a>

+  

+    <nav class="md-nav" aria-label="0.5 (2025-06-14)">

+      <ul class="md-nav__list">

+        

+          <li class="md-nav__item">

+  <a href="#removed-in-v0.5" class="md-nav__link">

+    <span class="md-ellipsis">

+      Removed

+    </span>

+  </a>

+  

+</li>

+        

+          <li class="md-nav__item">

+  <a href="#added-in-v0.5" class="md-nav__link">

+    <span class="md-ellipsis">

+      Added

+    </span>

+  </a>

+  

+</li>

+        

+          <li class="md-nav__item">

+  <a href="#changed-in-v0.5" class="md-nav__link">

+    <span class="md-ellipsis">

+      Changed

+    </span>

+  </a>

+  

+</li>

+        

+          <li class="md-nav__item">

+  <a href="#fixed-in-v0.5" class="md-nav__link">

+    <span class="md-ellipsis">

+      Fixed

+    </span>

+  </a>

+  

+</li>

+        

+      </ul>

+    </nav>

+  

+</li>

+      

         <li class="md-nav__item">

   <a href="#v0.4.0" class="md-nav__link">

     <span class="md-ellipsis">

@@ -2039,55 +2141,305 @@ Semantic Versioning and Keep a Changelog definitions.</p>

 </li>

 </ul>

 </details>

+<div class="admonition abstract inline end">

+<p class="admonition-title">Legend: symbols</p>

+<p><ul style="list-style-type: none;">

+<li><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M14 12h-4v-2h4m0 6h-4v-2h4m6-6h-2.81a6 6 0 0 0-1.82-1.96L17 4.41 15.59 3l-2.17 2.17a6 6 0 0 0-2.83 0L8.41 3 7 4.41l1.62 1.63C7.88 6.55 7.26 7.22 6.81 8H4v2h2.09c-.05.33-.09.66-.09 1v1H4v2h2v1c0 .34.04.67.09 1H4v2h2.81c1.04 1.79 2.97 3 5.19 3s4.15-1.21 5.19-3H20v-2h-2.09c.05-.33.09-.66.09-1v-1h2v-2h-2v-1c0-.34-.04-.67-.09-1H20z"/></svg></span> &mdash; a related bug entry from the wishlist page

+<li><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.06 1.93C7.17 1.92 5.33 3.74 6.17 6H3a2 2 0 0 0-2 2v2a1 1 0 0 0 1 1h9V8h2v3h9a1 1 0 0 0 1-1V8a2 2 0 0 0-2-2h-3.17C19 2.73 14.6.42 12.57 3.24L12 4l-.57-.78c-.63-.89-1.5-1.28-2.37-1.29M9 4c.89 0 1.34 1.08.71 1.71S8 5.89 8 5a1 1 0 0 1 1-1m6 0c.89 0 1.34 1.08.71 1.71S14 5.89 14 5a1 1 0 0 1 1-1M2 12v8a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2v-8h-9v8h-2v-8z"/></svg></span> &mdash; a related wishlist entry from the wishlist page

+</ul></p>

+</div>

 <aside>

 <p><small>

-(All entries are from the perspective of a user, not a developer.)

+(All entries are from the perspective of a user of the program or the API.

+As an exception, entries partaining to developers of <code>derivepassphrase</code> are

+specifically marked as such.)

 </small></p>

 </aside>

 <!-- scriv changelog start -->

+<h2 id="v0.5">0.5 (2025-06-14)<a class="headerlink" href="#v0.5" title="Permanent link">&para;</a></h2>

+<h3 id="removed-in-v0.5">Removed<a class="headerlink" href="#removed-in-v0.5" title="Permanent link">&para;</a></h3>

+<ul>

+<li>

+<p>For <a href="../reference/derivepassphrase.1/"><code>derivepassphrase</code></a>, remove <a href="#added-in-v0.4.0-color-support">support for (automatic) colored

+    output or output with embedded text styling, as introduced in

+    v0.4.0</a>.</p>

+<p>This is a stopgap measure.

+There exist pseudo-standards (the <code>NO_COLOR</code> and <code>FORCE_COLOR</code>

+environment variables) governing how to influence this automatic

+detection, but they are under-specified with regard to their interaction

+with each other.

+Until a consensus is reached and automatic colored/styled output can be

+requested or rejected reliably across different terminal programs, we

+will rather emit only uncolored, unstyled, lowest-common-denominator

+device-independent output.

+→<a href="../wishlist/conventional-configurable-text-styling/" title="Wish entry: “derivepassphrase vault should support conventional and configurable text styling”"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.06 1.93C7.17 1.92 5.33 3.74 6.17 6H3a2 2 0 0 0-2 2v2a1 1 0 0 0 1 1h9V8h2v3h9a1 1 0 0 0 1-1V8a2 2 0 0 0-2-2h-3.17C19 2.73 14.6.42 12.57 3.24L12 4l-.57-.78c-.63-.89-1.5-1.28-2.37-1.29M9 4c.89 0 1.34 1.08.71 1.71S8 5.89 8 5a1 1 0 0 1 1-1m6 0c.89 0 1.34 1.08.71 1.71S14 5.89 14 5a1 1 0 0 1 1-1M2 12v8a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2v-8h-9v8h-2v-8z"/></svg></span></a></p>

+</li>

+</ul>

+<h3 id="added-in-v0.5">Added<a class="headerlink" href="#added-in-v0.5" title="Permanent link">&para;</a></h3>

+<ul>

+<li>

+<p>For the <a class="autorefs autorefs-internal" title="            Vault" href="../reference/derivepassphrase.vault/#derivepassphrase.vault.Vault"><code>Vault</code></a> API, support reporting

+    on whether two master passphrases are interchangable with respect to the

+    service passphrases they can derive.

+    This is an artefact of how the master passphrase is converted to the

+    random bit sequence with which the service passphrases are generated.

+    See the corresponding <a href="../explanation/faq-vault-interchangable-passphrases/">FAQ entry: What are &ldquo;interchangable passphrases&rdquo;

+    in vault?</a> for details, including the

+    practical security (non-)implications.</p>

+<p>The <a href="../reference/derivepassphrase-vault.1/"><code>derivepassphrase vault</code></a> command-line interface does

+not address this in any manner, mostly because the “non-standard”

+interchangable variants of a given master password tend to be ugly to

+type in, and because they do not have practical security implications.</p>

+</li>

+<li>

+<p>For the <a class="autorefs autorefs-internal" title="            Vault" href="../reference/derivepassphrase.vault/#derivepassphrase.vault.Vault"><code>Vault</code></a> API, accept arbitrary

+    <a class="autorefs autorefs-external" href="https://docs.python.org/3/library/collections.abc.html#collections.abc.Buffer">Buffer</a> objects as passphrases or service

+    names, beyond <a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#bytes"><code>bytes</code></a> and <a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#bytearray"><code>bytearray</code></a>.</p>

+</li>

+<li>

+<p>Expose <a class="autorefs autorefs-internal" title="            UUID

+

+

+  

+      class-attribute

+      instance-attribute

+  " href="../reference/derivepassphrase.vault/#derivepassphrase.vault.Vault.UUID">the vault UUID</a> and <a class="autorefs autorefs-internal" title="            CHARSETS

+

+

+  

+      class-attribute

+      instance-attribute

+  " href="../reference/derivepassphrase.vault/#derivepassphrase.vault.Vault.CHARSETS">the

+    character sets</a> as public

+    attributes.</p>

+</li>

+<li>

+<p>For <a href="../reference/derivepassphrase-vault.1/"><code>derivepassphrase vault</code></a>, support selecting the <a href="#changed-in-v0.5-editor-interface">editor

+    interface</a> when editing notes via the

+    <code>--modern-editor-interface</code> and <code>--vault-legacy-editor-interface</code>

+    options.</p>

+</li>

+<li>

+<p>For <a href="../reference/derivepassphrase-vault.1/"><code>derivepassphrase vault</code></a>, support printing the service

+    notes before the passphrase, as an alternative, instead of always

+    printing them <em>after</em> the passphrase.

+    →<a href="../wishlist/print-service-notes-above/" title="Wish entry: “derivepassphrase vault should be able to print service notes above the passphrase”"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.06 1.93C7.17 1.92 5.33 3.74 6.17 6H3a2 2 0 0 0-2 2v2a1 1 0 0 0 1 1h9V8h2v3h9a1 1 0 0 0 1-1V8a2 2 0 0 0-2-2h-3.17C19 2.73 14.6.42 12.57 3.24L12 4l-.57-.78c-.63-.89-1.5-1.28-2.37-1.29M9 4c.89 0 1.34 1.08.71 1.71S8 5.89 8 5a1 1 0 0 1 1-1m6 0c.89 0 1.34 1.08.71 1.71S14 5.89 14 5a1 1 0 0 1 1-1M2 12v8a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2v-8h-9v8h-2v-8z"/></svg></span></a></p>

+</li>

+<li>

+<p>In the <code>--version</code> option of <a href="../reference/derivepassphrase.1/"><code>derivepassphrase</code></a> and each

+    subcommand, additionally report build and environment information, such

+    as supported subcommands, derivation schemes, foreign configuration

+    formats and active <a href="https://peps.python.org/pep-0508/">PEP 508 extras</a>.

+    (Each subcommand only reports the items relevant to that subcommand.)

+    →<a href="../wishlist/report-build-flags-and-features/" title="Wish entry: “derivepassphrase should report its build flags and supported features”"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.06 1.93C7.17 1.92 5.33 3.74 6.17 6H3a2 2 0 0 0-2 2v2a1 1 0 0 0 1 1h9V8h2v3h9a1 1 0 0 0 1-1V8a2 2 0 0 0-2-2h-3.17C19 2.73 14.6.42 12.57 3.24L12 4l-.57-.78c-.63-.89-1.5-1.28-2.37-1.29M9 4c.89 0 1.34 1.08.71 1.71S8 5.89 8 5a1 1 0 0 1 1-1m6 0c.89 0 1.34 1.08.71 1.71S14 5.89 14 5a1 1 0 0 1 1-1M2 12v8a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2v-8h-9v8h-2v-8z"/></svg></span></a></p>

+</li>

+<li>

+<p>For developers: Rewrite the tests concerning <a href="../reference/derivepassphrase-vault.1/"><code>derivepassphrase

+    vault</code></a> and <code>--notes</code> usage into <a href="https://pypi.org/project/hypothesis/">hypothesis</a>-based tests

+    where feasible.</p>

+</li>

+<li>

+<p>For developers: Add scripts to the source tree to ensure consistent code

+    quality: automatic linting, formatting and type checking, and optional

+    running of the test suite and building of the documentation.

+    The master quality control script doubles as a servicable (but

+    heavyweight) &ldquo;pre-commit&rdquo; hook for git.</p>

+</li>

+</ul>

+<h3 id="changed-in-v0.5">Changed<a class="headerlink" href="#changed-in-v0.5" title="Permanent link">&para;</a></h3>

+<ul>

+<li>

+<p>Support a new, unified interface

+    <a class="autorefs autorefs-internal" title="            ExportVaultConfigDataFunction" href="../reference/derivepassphrase.exporter/#derivepassphrase.exporter.ExportVaultConfigDataFunction"><code>ExportVaultConfigDataFunction</code></a>

+    in the export handlers for “storeroom” and “vault-native” configuration

+    data,

+    <a class="autorefs autorefs-internal" title="            export_storeroom_data" href="../reference/derivepassphrase.exporter/#derivepassphrase.exporter.storeroom.export_storeroom_data"><code>export_storeroom_data</code></a>

+    and

+    <a class="autorefs autorefs-internal" title="            export_vault_native_data" href="../reference/derivepassphrase.exporter/#derivepassphrase.exporter.vault_native.export_vault_native_data"><code>export_vault_native_data</code></a>.

+    A new dispatch function

+    <a class="autorefs autorefs-internal" title="            export_vault_config_data" href="../reference/derivepassphrase.exporter/#derivepassphrase.exporter.export_vault_config_data"><code>export_vault_config_data</code></a>

+    automatically calls the correct backend, based on the requested format.</p>

+<p>This is a <strong>breaking API change</strong> due to the change in function

+parameter names and return types.</p>

+</li>

+<li>

+<p>Convert <code>KeyCommentPair</code> from <a class="autorefs autorefs-internal" title="            derivepassphrase._types" href="../reference/derivepassphrase._types/#derivepassphrase._types"><code>derivepassphrase._types</code></a>, and

+    <code>KeyPair</code> and <code>MasterKeys</code> from

+    <a class="autorefs autorefs-internal" title="            derivepassphrase.exporter.storeroom" href="../reference/derivepassphrase.exporter/#derivepassphrase.exporter.storeroom"><code>derivepassphrase.exporter.storeroom</code></a>, to

+    <a class="autorefs autorefs-external" href="https://docs.python.org/3/library/typing.html#typing.NamedTuple"><code>NamedTuple</code>s</a>. Also rename them to

+    <a class="autorefs autorefs-internal" title="            SSHKeyCommentPair" href="../reference/derivepassphrase._types/#derivepassphrase._types.SSHKeyCommentPair"><code>SSHKeyCommentPair</code></a>,

+    <a class="autorefs autorefs-internal" title="            StoreroomKeyPair" href="../reference/derivepassphrase._types/#derivepassphrase._types.StoreroomKeyPair"><code>StoreroomKeyPair</code></a> and

+    <a class="autorefs autorefs-internal" title="            StoreroomMasterKeys" href="../reference/derivepassphrase._types/#derivepassphrase._types.StoreroomMasterKeys"><code>StoreroomMasterKeys</code></a>,

+    respectively, in the <a class="autorefs autorefs-internal" title="            derivepassphrase._types" href="../reference/derivepassphrase._types/#derivepassphrase._types"><code>derivepassphrase._types</code></a> module.</p>

+<p>This is a <strong>breaking API change</strong>.</p>

+</li>

+<li>

+<p>Move the non-essential content of the <a class="autorefs autorefs-internal" title="            derivepassphrase.cli" href="../reference/derivepassphrase.cli/#derivepassphrase.cli"><code>derivepassphrase.cli</code></a> module

+    into the &ldquo;internals&rdquo; subpackage.</p>

+<p>This is a <strong>breaking API change</strong> due to the removal of most functions

+from the <a class="autorefs autorefs-internal" title="            derivepassphrase.cli" href="../reference/derivepassphrase.cli/#derivepassphrase.cli"><code>derivepassphrase.cli</code></a> module.</p>

+</li>

+<li>

+<p>For <a href="../reference/derivepassphrase-vault.1/"><code>derivepassphrase vault</code></a>, change the handling of the

+    notes for better compatibility with <i>vault</i>(1) and for better

+    internal consistency:</p>

+<ol>

+<li>

+<p>Correctly require the <code>--config</code> option in addition to the <code>--notes</code>

+    option to request that the service notes be edited, for

+    compatibility with <i>vault</i>(1).

+    Issue a warning if <code>--notes</code> is used without <code>--config</code>.</p>

+</li>

+<li>

+<p><code>notes</code> is now also a valid setting name for <code>--unset</code> to take.</p>

+</li>

+<li>

+<p>Editing the notes successfully in any way, including no-op edits,

+    will register the service name as a known service to

+    <a href="../reference/derivepassphrase-vault.1/"><code>derivepassphrase vault</code></a>, even if the settings are

+    otherwise empty.</p>

+</li>

+</ol>

+</li>

+<li>

+<p>For <a href="../reference/derivepassphrase-vault.1/"><code>derivepassphrase vault</code></a>, by default, use an <b

+    id="changed-in-v0.5-editor-interface">editor interface</b> that matches

+    <i>vault</i>(1): the contents of the edited text file are used directly

+    as the service notes, without interpretation.</p>

+<p>Previously, we post-processed the text file to remove comments and our

+instruction texts, and interpreted an empty file as a request to abort

+the edit.

+These two editor interfaces (“legacy” and “modern”) can be explicitly

+selected, and for the legacy interface, which is less resilient against

+data entry or usage errors, a backup copy of the old notes content is

+made.</p>

+</li>

+<li>

+<p>For developers: Use a different feature matrix and different

+    <a href="https://pypi.org/project/hypothesis/">hypothesis</a> profiles in the test suite.

+    The slowdown caused by coverage measurement is now more accurately

+    estimated and adjusted for in the <a href="https://pypi.org/project/hypothesis/">hypothesis</a> settings.</p>

+</li>

+<li>

+<p>For developers: Clean up, partly reorganize, and document the test

+    suite, at least rudimentarily.

+    Also add several new <a href="https://pypi.org/project/hypothesis/">hypothesis</a>-based tests, particularly to test

+    the core assumptions of the <a class="autorefs autorefs-internal" title="            derivepassphrase.vault" href="../reference/derivepassphrase.vault/#derivepassphrase.vault">vault</a> derivation

+    scheme about sensitivity (or lack thereof) to its inputs and its input

+    formats.</p>

+</li>

+<li>

+<p>For developers: For <a href="../reference/derivepassphrase-vault.1/"><code>derivepassphrase vault</code></a>, store our

+    <code>vault.json</code> data file in pretty-printed form.

+    This is a stopgap measure to ease debugging and introspection until

+    better built-in query functionality for the effective configuration is

+    available, because users should not be rewarded for meddling around in

+    data files.

+    →<a href="../wishlist/pretty-print-json/" title="Wish entry: “derivepassphrase vault should store and export the vault configuration in pretty-printed JSON”"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.06 1.93C7.17 1.92 5.33 3.74 6.17 6H3a2 2 0 0 0-2 2v2a1 1 0 0 0 1 1h9V8h2v3h9a1 1 0 0 0 1-1V8a2 2 0 0 0-2-2h-3.17C19 2.73 14.6.42 12.57 3.24L12 4l-.57-.78c-.63-.89-1.5-1.28-2.37-1.29M9 4c.89 0 1.34 1.08.71 1.71S8 5.89 8 5a1 1 0 0 1 1-1m6 0c.89 0 1.34 1.08.71 1.71S14 5.89 14 5a1 1 0 0 1 1-1M2 12v8a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2v-8h-9v8h-2v-8z"/></svg></span></a></p>

+</li>

+</ul>

+<h3 id="fixed-in-v0.5">Fixed<a class="headerlink" href="#fixed-in-v0.5" title="Permanent link">&para;</a></h3>

+<ul>

+<li>

+<p>Fix the misbehaving shell completion for <code>zsh</code> in the presence of colons

+    in the completion item.

+    This was due to an overzealous workaround for

+    <a href="https://github.com/pallets/click/issues/2703"><code>pallets/click#2703</code></a>.</p>

+</li>

+<li>

+<p>For <a href="../reference/derivepassphrase-vault.1/"><code>derivepassphrase vault</code></a>, when exporting a vault

+    configuration, export a pretty-printed configuration, to ease debugging

+    and introspection.

+    →<a href="../wishlist/pretty-print-json/" title="Wish entry: “derivepassphrase vault should store and export the vault configuration in pretty-printed JSON”"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.06 1.93C7.17 1.92 5.33 3.74 6.17 6H3a2 2 0 0 0-2 2v2a1 1 0 0 0 1 1h9V8h2v3h9a1 1 0 0 0 1-1V8a2 2 0 0 0-2-2h-3.17C19 2.73 14.6.42 12.57 3.24L12 4l-.57-.78c-.63-.89-1.5-1.28-2.37-1.29M9 4c.89 0 1.34 1.08.71 1.71S8 5.89 8 5a1 1 0 0 1 1-1m6 0c.89 0 1.34 1.08.71 1.71S14 5.89 14 5a1 1 0 0 1 1-1M2 12v8a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2v-8h-9v8h-2v-8z"/></svg></span></a></p>

+</li>

+<li>

+<p>For <a href="../reference/derivepassphrase-vault.1/"><code>derivepassphrase vault</code></a>, also print the service notes

+    (if any) when deriving a service passphrase, just like <i>vault</i>(1)

+    does.

+    →<a href="../wishlist/print-service-notes/" title="Bug entry: “derivepassphrase vault does not print service notes”"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M14 12h-4v-2h4m0 6h-4v-2h4m6-6h-2.81a6 6 0 0 0-1.82-1.96L17 4.41 15.59 3l-2.17 2.17a6 6 0 0 0-2.83 0L8.41 3 7 4.41l1.62 1.63C7.88 6.55 7.26 7.22 6.81 8H4v2h2.09c-.05.33-.09.66-.09 1v1H4v2h2v1c0 .34.04.67.09 1H4v2h2.81c1.04 1.79 2.97 3 5.19 3s4.15-1.21 5.19-3H20v-2h-2.09c.05-.33.09-.66.09-1v-1h2v-2h-2v-1c0-.34-.04-.67-.09-1H20z"/></svg></span></a></p>

+</li>

+<li>

+<p>Lock our internals and their configuration against concurrent

+    modifications.

+    →<a href="../wishlist/concurrency-audit/" title="Bug entry: “Audit derivepassphrase for concurrency/thread-safety issues”"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M14 12h-4v-2h4m0 6h-4v-2h4m6-6h-2.81a6 6 0 0 0-1.82-1.96L17 4.41 15.59 3l-2.17 2.17a6 6 0 0 0-2.83 0L8.41 3 7 4.41l1.62 1.63C7.88 6.55 7.26 7.22 6.81 8H4v2h2.09c-.05.33-.09.66-.09 1v1H4v2h2v1c0 .34.04.67.09 1H4v2h2.81c1.04 1.79 2.97 3 5.19 3s4.15-1.21 5.19-3H20v-2h-2.09c.05-.33.09-.66.09-1v-1h2v-2h-2v-1c0-.34-.04-.67-.09-1H20z"/></svg></span></a></p>

+</li>

+<li>

+<p>Test against PyPy 3.11.</p>

+</li>

+<li>

+<p>Test on <abbr title="Microsoft Windows">The Annoying

+    OS</abbr><sup id="fnref:the-annoying-os"><a class="footnote-ref" href="#fn:the-annoying-os">1</a></sup> in its baseline version, i.e., without SSH

+    agent functionality but with <code>cryptography</code> support.

+    Fix all incompatibilities in the test suite if essential and/or

+    feasible, otherwise document them as skips or expected failures.</p>

+<p>(The latter case currently only concerns one single test that is

+supposed to trigger OS errors while attempting to read the

+<code>derivepassphrase</code> configuration files.

+<abbr title="Microsoft Windows">The Annoying OS</abbr> happily returns

+an empty file instead.)</p>

+</li>

+<li>

+<p>For developers: Include build machinery to ensure consistency of our

+    version number and our diagnostic messages between the documentation and

+    the code, instead of having to check this by hand.</p>

+<p>(The canonical way to get the version number is the

+<a class="autorefs autorefs-external" href="https://docs.python.org/3/library/importlib.metadata.html#importlib.metadata.version"><code>importlib.metadata.version</code></a> standard library interface.)</p>

+</li>

+<li>

+<p>For developers: Test our locking implementation for correctness, on both

+    sides of the API.

+    Specifically, test that the respective platform-specific locking

+    primitives provide the requested mutual exclusion properties, and that

+    the locking system as a whole, when given functioning locking

+    primitives, correctly serializes access to the facilities it is supposed

+    to guard.

+    →<a href="../wishlist/concurrency-testing-in-test-suite/" title="Bug entry: “Test for concurrency and assert thread-safety in derivepassphrase's test suite”"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M14 12h-4v-2h4m0 6h-4v-2h4m6-6h-2.81a6 6 0 0 0-1.82-1.96L17 4.41 15.59 3l-2.17 2.17a6 6 0 0 0-2.83 0L8.41 3 7 4.41l1.62 1.63C7.88 6.55 7.26 7.22 6.81 8H4v2h2.09c-.05.33-.09.66-.09 1v1H4v2h2v1c0 .34.04.67.09 1H4v2h2.81c1.04 1.79 2.97 3 5.19 3s4.15-1.21 5.19-3H20v-2h-2.09c.05-.33.09-.66.09-1v-1h2v-2h-2v-1c0-.34-.04-.67-.09-1H20z"/></svg></span></a></p>

+</li>

+</ul>

 <h2 id="v0.4.0">0.4.0 (2025-01-07)<a class="headerlink" href="#v0.4.0" title="Permanent link">&para;</a></h2>

 <h3 id="added-in-v0.4.0">Added<a class="headerlink" href="#added-in-v0.4.0" title="Permanent link">&para;</a></h3>

 <ul>

 <li>

-<p>Both <code>derivepassphrase vault</code> and <code>derivepassphrase export vault</code> now

-    support changing the amount of diagnostic output they emit via new

-    command-line options <code>--debug</code>, <code>-v</code>/<code>--verbose</code> and <code>-q</code>/<code>--quiet</code>.

-    Internally, this uses Python&rsquo;s standard <a class="autorefs autorefs-external" href="https://docs.python.org/3/library/logging.html#module-logging">logging</a> and <a class="autorefs autorefs-external" href="https://docs.python.org/3/library/warnings.html#module-warnings">warnings</a>

+<p>For <a href="../reference/derivepassphrase-vault.1/"><code>derivepassphrase vault</code></a> and <a href="../reference/derivepassphrase-export-vault.1/"><code>derivepassphrase export

+    vault</code></a>, support changing the amount of diagnostic

+    output we emit via new command-line options <code>--debug</code>, <code>-v</code>/<code>--verbose</code>

+    and <code>-q</code>/<code>--quiet</code>.

+    Internally, we use Python&rsquo;s standard <a class="autorefs autorefs-external" href="https://docs.python.org/3/library/logging.html#module-logging">logging</a> and <a class="autorefs autorefs-external" href="https://docs.python.org/3/library/warnings.html#module-warnings">warnings</a>

     systems.</p>

 </li>

 <li>

-<p><code>derivepassphrase</code> now uses a central configuration file, and additional

-    data files, some of which are service-specific.

-    (The <code>vault.json</code>

-    configuration file is now rebranded as a data file.)

+<p>Use a central configuration file, and additional data files, some of

+    which are service-specific.

+    (The <code>vault.json</code> configuration file is now rebranded as a data file.)

     The configuration files are user-editable, the data files are

-    <code>derivepassphrase</code>-editable.</p>

+    <a href="../reference/derivepassphrase.1/"><code>derivepassphrase</code></a>-editable.</p>

 <p>The configuration files are in TOML format, so installing

 <code>derivepassphrase</code> on Python 3.10 and older requires the

 <a href="https://pypi.org/project/tomli/"><code>tomli</code></a> package.</p>

 </li>

 <li>

-<p><code>derivepassphrase vault --config</code> now supports an <code>--unset</code> option which

-    unsets any given named setting prior to applying any other configuration

-    changes.</p>

+<p>For <a href="../reference/derivepassphrase-vault.1/"><code>derivepassphrase vault --config</code></a>, support an <code>--unset</code>

+    option which unsets any given named setting prior to applying any other

+    configuration changes.</p>

 </li>

 <li>

-<p><code>derivepassphrase vault --export</code> can now also export the current

-    configuration as a POSIX <code>sh</code> script, using the <code>--export-as=sh</code> option.

-    The default (and previous behavior) is <code>--export-as=json</code>.</p>

+<p>For <a href="../reference/derivepassphrase-vault.1/"><code>derivepassphrase vault --export</code></a>, support exporting

+    the current configuration as a POSIX <code>sh</code> script, using the

+    <code>--export-as=sh</code> option.  The default (and previous behavior) is

+    <code>--export-as=json</code>.</p>

 </li>

 <li>

-<p><code>derivepassphrase</code> now includes basic support for localization: if the

-    necessary translations are installed, then the diagnostics and help

-    texts can be emitted in different languages.

-    Internally, this uses Python&rsquo;s standard <a class="autorefs autorefs-external" href="https://docs.python.org/3/library/gettext.html#module-gettext"><code>gettext</code></a> system.</p>

+<p>Include basic support for localization: if the necessary translations

+    are installed, then the diagnostics and help texts can be emitted in

+    different languages.

+    Internally, we use Python&rsquo;s standard <a class="autorefs autorefs-external" href="https://docs.python.org/3/library/gettext.html#module-gettext"><code>gettext</code></a> system.</p>

 <p>(As of this version, no translations have actually been prepared yet.)</p>

 </li>

 <li>

-<p><code>derivepassphrase</code> now explicitly supports shell completion, in

-    particular filename and service name completion in the <code>export vault</code>

-    and <code>vault</code> subcommands.</p>

+<p>For <a href="../reference/derivepassphrase.1/"><code>derivepassphrase</code></a>, explicitly support shell completion, in

+    particular filename and service name completion in the <a href="../reference/derivepassphrase-export-vault.1/"><code>export

+    vault</code></a> and <a href="../reference/derivepassphrase-vault.1/"><code>vault</code></a> subcommands.</p>

 <p>However, because of restrictions regarding the exchange of data between

 <code>derivepassphrase</code> and the shell, <code>derivepassphrase</code> will not offer any

 service names containing ASCII control characters for completion, and

@@ -2095,9 +2447,10 @@ a warning will be issued when importing or configuring such a service.

 They may still otherwise be used normally.</p>

 </li>

 <li>

-<p>Support the semi-standard <code>NO_COLOR</code> and the <code>FORCE_COLOR</code> environment

-    variables to suppress or force color output from <code>derivepassphrase</code>.

-    (<code>FORCE_COLOR</code> overrides <code>NO_COLOR</code> if both are set.)</p>

+<p><b id="added-in-v0.4.0-color-support">Support the semi-standard

+    <code>NO_COLOR</code> and the <code>FORCE_COLOR</code> environment variables</b> to suppress

+    or force color output from <a href="../reference/derivepassphrase.1/"><code>derivepassphrase</code></a>.  (<code>FORCE_COLOR</code>

+    overrides <code>NO_COLOR</code> if both are set.)</p>

 </li>

 </ul>

 <h3 id="changed-in-v0.4.0">Changed<a class="headerlink" href="#changed-in-v0.4.0" title="Permanent link">&para;</a></h3>

@@ -2164,16 +2517,17 @@ They may still otherwise be used normally.</p>

 <h2 id="v0.3.0">0.3.0 (2024-10-15)<a class="headerlink" href="#v0.3.0" title="Permanent link">&para;</a></h2>

 <h3 id="added-in-v0.3.0">Added<a class="headerlink" href="#added-in-v0.3.0" title="Permanent link">&para;</a></h3>

 <ul>

-<li>Convert changelog management from towncrier to <a href="https://pypi.org/project/scriv">scriv</a>.</li>

+<li>Convert changelog management from towncrier to <a href="https://pypi.org/project/scriv/">scriv</a>.</li>

 <li>Add SSH agent spawning support to the test suite.

     Use this support to test the agent functionality on all known major SSH

     agent implementations automatically.

-    (<a href="https://github.com/the-13th-letter/derivepassphrase/issues/12">#12</a>)</li>

+    →<a href="../wishlist/test-suite-isolated-ssh-agent/" title="Wish entry: “Support and isolate OpenSSH's ssh-agent and PuTTY's pageant in the test suite”"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.06 1.93C7.17 1.92 5.33 3.74 6.17 6H3a2 2 0 0 0-2 2v2a1 1 0 0 0 1 1h9V8h2v3h9a1 1 0 0 0 1-1V8a2 2 0 0 0-2-2h-3.17C19 2.73 14.6.42 12.57 3.24L12 4l-.57-.78c-.63-.89-1.5-1.28-2.37-1.29M9 4c.89 0 1.34 1.08.71 1.71S8 5.89 8 5a1 1 0 0 1 1-1m6 0c.89 0 1.34 1.08.71 1.71S14 5.89 14 5a1 1 0 0 1 1-1M2 12v8a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2v-8h-9v8h-2v-8z"/></svg></span></a></li>

 <li>Add <a href="https://pypi.org/project/hypothesis/">hypothesis</a>-based tests to the test suite.</li>

 <li>Update README to add explanations for virtual environments and package

     extras.</li>

 <li>Update README to demonstrate configuration storing and SSH agent use.

-    Include comments on Windows support for SSH agents.</li>

+    Include comments on Windows support for SSH agents.

+    →<a href="../wishlist/windows-ssh-agent-support/" title="Bug entry: “Support PuTTY/Pageant (and maybe OpenSSH/ssh-agent) on Windows”"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M14 12h-4v-2h4m0 6h-4v-2h4m6-6h-2.81a6 6 0 0 0-1.82-1.96L17 4.41 15.59 3l-2.17 2.17a6 6 0 0 0-2.83 0L8.41 3 7 4.41l1.62 1.63C7.88 6.55 7.26 7.22 6.81 8H4v2h2.09c-.05.33-.09.66-.09 1v1H4v2h2v1c0 .34.04.67.09 1H4v2h2.81c1.04 1.79 2.97 3 5.19 3s4.15-1.21 5.19-3H20v-2h-2.09c.05-.33.09-.66.09-1v-1h2v-2h-2v-1c0-.34-.04-.67-.09-1H20z"/></svg></span></a></li>

 <li>Use cross-references in the documentation of function signatures.</li>

 <li>Add proper support for Buffer types in the SSH agent client.

     Any Python object supporting the buffer protocol can be used as input to

@@ -2196,11 +2550,11 @@ They may still otherwise be used normally.</p>

     standard library does.</p>

 </li>

 <li>

-<p>Rewrite functionality for checking for valid vault(1) configurations:

-    include an actual validation function which throws errors upon

-    encountering format violations, and which allows specifying which types

-    of extensions (unknown settings, <code>derivepassphrase</code>-only settings) to

-    tolerate during validation.</p>

+<p>Rewrite functionality for checking for valid <i>vault</i>(1)

+    configurations: include an actual validation function which throws

+    errors upon encountering format violations, and which allows specifying

+    which types of extensions (unknown settings, <code>derivepassphrase</code>-only

+    settings) to tolerate during validation.</p>

 <p>This is a <strong>breaking API change</strong> because the function return annotation

 changed, from <a class="autorefs autorefs-external" href="https://docs.python.org/3/library/typing.html#typing.TypeGuard"><code>typing.TypeGuard</code></a> to <a class="autorefs autorefs-external" href="https://typing-extensions.readthedocs.io/en/latest/index.html#typing_extensions.TypeIs"><code>typing_extensions.TypeIs</code></a>.

 These were the originally intended semantics, but when

@@ -2211,38 +2565,40 @@ support this kind of partial type narrowing.</p>

 <p>Fail earlier, and more gracefully/specifically, when we cannot talk to

     the SSH agent because Python does not support UNIX domain sockets on

     this system.

-    In particular, this is the current situation on Windows.</p>

+    In particular, this is the current situation on Windows.

+    →<a href="../wishlist/fail-gracefully-without-af-unix/" title="Bug entry: “Fail gracefully if support for UNIX domain sockets is unavailable”"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M14 12h-4v-2h4m0 6h-4v-2h4m6-6h-2.81a6 6 0 0 0-1.82-1.96L17 4.41 15.59 3l-2.17 2.17a6 6 0 0 0-2.83 0L8.41 3 7 4.41l1.62 1.63C7.88 6.55 7.26 7.22 6.81 8H4v2h2.09c-.05.33-.09.66-.09 1v1H4v2h2v1c0 .34.04.67.09 1H4v2h2.81c1.04 1.79 2.97 3 5.19 3s4.15-1.21 5.19-3H20v-2h-2.09c.05-.33.09-.66.09-1v-1h2v-2h-2v-1c0-.34-.04-.67-.09-1H20z"/></svg></span></a>

+    <a href="../wishlist/windows-ssh-agent-support/" title="Bug entry: “Support PuTTY/Pageant (and maybe OpenSSH/ssh-agent) on Windows”"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M14 12h-4v-2h4m0 6h-4v-2h4m6-6h-2.81a6 6 0 0 0-1.82-1.96L17 4.41 15.59 3l-2.17 2.17a6 6 0 0 0-2.83 0L8.41 3 7 4.41l1.62 1.63C7.88 6.55 7.26 7.22 6.81 8H4v2h2.09c-.05.33-.09.66-.09 1v1H4v2h2v1c0 .34.04.67.09 1H4v2h2.81c1.04 1.79 2.97 3 5.19 3s4.15-1.21 5.19-3H20v-2h-2.09c.05-.33.09-.66.09-1v-1h2v-2h-2v-1c0-.34-.04-.67-.09-1H20z"/></svg></span></a></p>

 <p>This adds another failure case to the <code>SSHAgentClient</code> constructor, and

 therefore constitutes a <strong>breaking API change</strong>.</p>

 </li>

 <li>

-<p>In <code>derivepassphrase vault</code>, accept <code>key</code> and <code>phrase</code> entries just like

-    vault(1) does: <code>key</code> always overrides <code>phrase</code> in the configuration, no

-    matter the level.</p>

+<p>In <a href="../reference/derivepassphrase-vault.1/"><code>derivepassphrase vault</code></a>, accept <code>key</code> and <code>phrase</code>

+    entries just like <i>vault</i>(1) does: <code>key</code> always overrides <code>phrase</code>

+    in the configuration, no matter the level.</p>

 <p>This is a command-line only change.</p>

 </li>

 <li>

-<p>In <code>derivepassphrase vault</code>, when importing settings, accept falsy values

-    everywhere <code>vault</code> does, with a warning.

+<p>In <a href="../reference/derivepassphrase-vault.1/"><code>derivepassphrase vault</code></a>, when importing settings,

+    accept falsy values everywhere <code>vault</code> does, with a warning.

     Depending on the setting, they are equivalent to zero, the empty string,

     or “not set”.

-    (<a href="https://github.com/the-13th-letter/derivepassphrase/issues/17">#17</a>)</p>

+    →<a href="../wishlist/falsy-vault-config-values/" title="Bug entry: “derivepassphrase vault differs from vault(1) behavior with falsy stored configuration values”"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M14 12h-4v-2h4m0 6h-4v-2h4m6-6h-2.81a6 6 0 0 0-1.82-1.96L17 4.41 15.59 3l-2.17 2.17a6 6 0 0 0-2.83 0L8.41 3 7 4.41l1.62 1.63C7.88 6.55 7.26 7.22 6.81 8H4v2h2.09c-.05.33-.09.66-.09 1v1H4v2h2v1c0 .34.04.67.09 1H4v2h2.81c1.04 1.79 2.97 3 5.19 3s4.15-1.21 5.19-3H20v-2h-2.09c.05-.33.09-.66.09-1v-1h2v-2h-2v-1c0-.34-.04-.67-.09-1H20z"/></svg></span></a></p>

 <p>This is a command-line only change, and only affects importing.

 The API provides a new function to normalize falsy settings, but still

 otherwise requires settings to be of the correct type.

 Storing a malformed configuration with such falsy values will still

-generate errors when <code>derivepassphrase vault</code> loads the settings from

-disk.</p>

+generate errors when <a href="../reference/derivepassphrase-vault.1/"><code>derivepassphrase vault</code></a> loads the

+settings from disk.</p>

 </li>

 <li>

-<p>In <code>derivepassphrase vault</code>, when importing configurations,

-    correctly merge them with the existing one, same as vault(1): keep

-    all named services and their settings (and the global settings if

+<p>In <a href="../reference/derivepassphrase-vault.1/"><code>derivepassphrase vault</code></a>, when importing configurations,

+    correctly merge them with the existing one, same as <i>vault</i>(1):

+    keep all named services and their settings (and the global settings if

     applicable) that are not mentioned in the imported configuration.

     The import procedure is thus more akin to a section-wise import of

     the configurations, instead of a “full” import, and the resulting

     configuration generally is a merge of both inputs.

-    (<a href="https://github.com/the-13th-letter/derivepassphrase/issues/16">#16</a>)</p>

+    →<a href="../wishlist/amend-vault-config/" title="Bug entry: “derivepassphrase vault --import overwrites config instead of amending it”"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M14 12h-4v-2h4m0 6h-4v-2h4m6-6h-2.81a6 6 0 0 0-1.82-1.96L17 4.41 15.59 3l-2.17 2.17a6 6 0 0 0-2.83 0L8.41 3 7 4.41l1.62 1.63C7.88 6.55 7.26 7.22 6.81 8H4v2h2.09c-.05.33-.09.66-.09 1v1H4v2h2v1c0 .34.04.67.09 1H4v2h2.81c1.04 1.79 2.97 3 5.19 3s4.15-1.21 5.19-3H20v-2h-2.09c.05-.33.09-.66.09-1v-1h2v-2h-2v-1c0-.34-.04-.67-.09-1H20z"/></svg></span></a></p>

 </li>

 <li>

 <p>The following operations or configuration settings now raise

@@ -2272,12 +2628,12 @@ disk.</p>

     storeroom formats.</p>

 <p>This feature requires the <code>cryptography</code> Python module, but is available

 even if <code>vault</code> is not installed.

-(<a href="https://github.com/the-13th-letter/derivepassphrase/1">#1</a>)</p>

+→<a href="../wishlist/export-vault-formats/" title="Wish entry: “Support data export from vault v0.2, vault v0.3, and storeroom storage formats”"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.06 1.93C7.17 1.92 5.33 3.74 6.17 6H3a2 2 0 0 0-2 2v2a1 1 0 0 0 1 1h9V8h2v3h9a1 1 0 0 0 1-1V8a2 2 0 0 0-2-2h-3.17C19 2.73 14.6.42 12.57 3.24L12 4l-.57-.78c-.63-.89-1.5-1.28-2.37-1.29M9 4c.89 0 1.34 1.08.71 1.71S8 5.89 8 5a1 1 0 0 1 1-1m6 0c.89 0 1.34 1.08.71 1.71S14 5.89 14 5a1 1 0 0 1 1-1M2 12v8a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2v-8h-9v8h-2v-8z"/></svg></span></a></p>

 </li>

 </ul>

 <h3 id="fixed-in-v0.2.0">Fixed<a class="headerlink" href="#fixed-in-v0.2.0" title="Permanent link">&para;</a></h3>

 <ul>

-<li>Deploy versioned documentation with <a href="https://pypi.org/project/mike">mike</a>.

+<li>Deploy versioned documentation with <a href="https://pypi.org/project/mike/">mike</a>.

     Set up a &ldquo;latest&rdquo; tag and the &ldquo;0.<var>x</var>&rdquo; version of the

     documentation with the contents so far.</li>

 </ul>

@@ -2288,20 +2644,20 @@ even if <code>vault</code> is not installed.

     Further moved <code>derivepassphrase.Vault</code> and

     <code>derivepassphrase.AmbiguousByteRepresentation</code> into a new submodule

     <code>vault</code>, and renamed submodule <code>ssh_agent_client</code> to <code>ssh_agent</code>.

-    (<a href="https://github.com/the-13th-letter/derivepassphrase/3">#3</a>)</li>

+    →<a href="../wishlist/single-toplevel-module/" title="Bug entry: “Move sequin and ssh_agent_client modules into derivepassphrase package”"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M14 12h-4v-2h4m0 6h-4v-2h4m6-6h-2.81a6 6 0 0 0-1.82-1.96L17 4.41 15.59 3l-2.17 2.17a6 6 0 0 0-2.83 0L8.41 3 7 4.41l1.62 1.63C7.88 6.55 7.26 7.22 6.81 8H4v2h2.09c-.05.33-.09.66-.09 1v1H4v2h2v1c0 .34.04.67.09 1H4v2h2.81c1.04 1.79 2.97 3 5.19 3s4.15-1.21 5.19-3H20v-2h-2.09c.05-.33.09-.66.09-1v-1h2v-2h-2v-1c0-.34-.04-.67-.09-1H20z"/></svg></span></a></li>

 <li>Changed internal error handling and error messages, to better work in

     the context of a command-line tool.

-    (<a href="https://github.com/the-13th-letter/derivepassphrase/4">#4</a>)</li>

+    →<a href="../wishlist/better-error-messages/" title="Bug entry: “Improve common error messages in the command-line interface”"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M14 12h-4v-2h4m0 6h-4v-2h4m6-6h-2.81a6 6 0 0 0-1.82-1.96L17 4.41 15.59 3l-2.17 2.17a6 6 0 0 0-2.83 0L8.41 3 7 4.41l1.62 1.63C7.88 6.55 7.26 7.22 6.81 8H4v2h2.09c-.05.33-.09.66-.09 1v1H4v2h2v1c0 .34.04.67.09 1H4v2h2.81c1.04 1.79 2.97 3 5.19 3s4.15-1.21 5.19-3H20v-2h-2.09c.05-.33.09-.66.09-1v-1h2v-2h-2v-1c0-.34-.04-.67-.09-1H20z"/></svg></span></a></li>

 <li>Combine and consolidate <code>derivepassphrase.types</code> and

     <code>derivepassphrase.ssh_agent.types</code> into a new submodule

     <code>derivepassphrase._types</code>.

     Despite the name, the module is public.

-    (<a href="https://github.com/the-13th-letter/derivepassphrase/7">#7</a>)</li>

+    →<a href="../wishlist/no-stdlib-module-names/" title="Bug entry: “Rename types submodules to _types”"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M14 12h-4v-2h4m0 6h-4v-2h4m6-6h-2.81a6 6 0 0 0-1.82-1.96L17 4.41 15.59 3l-2.17 2.17a6 6 0 0 0-2.83 0L8.41 3 7 4.41l1.62 1.63C7.88 6.55 7.26 7.22 6.81 8H4v2h2.09c-.05.33-.09.66-.09 1v1H4v2h2v1c0 .34.04.67.09 1H4v2h2.81c1.04 1.79 2.97 3 5.19 3s4.15-1.21 5.19-3H20v-2h-2.09c.05-.33.09-.66.09-1v-1h2v-2h-2v-1c0-.34-.04-.67-.09-1H20z"/></svg></span></a></li>

 <li>Warn the user when entering (directly, or via configuration

     editing/importing) a passphrase that is not in the configured Unicode

     normalization form.

     (But don’t otherwise reject any textual master passphrases.)

-    (<a href="https://github.com/the-13th-letter/derivepassphrase/9">#9</a>)</li>

+    →<a href="../wishlist/allow-all-unicode-passphrases/" title="Bug entry: “Allow all Unicode text strings as master passphrases”"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M14 12h-4v-2h4m0 6h-4v-2h4m6-6h-2.81a6 6 0 0 0-1.82-1.96L17 4.41 15.59 3l-2.17 2.17a6 6 0 0 0-2.83 0L8.41 3 7 4.41l1.62 1.63C7.88 6.55 7.26 7.22 6.81 8H4v2h2.09c-.05.33-.09.66-.09 1v1H4v2h2v1c0 .34.04.67.09 1H4v2h2.81c1.04 1.79 2.97 3 5.19 3s4.15-1.21 5.19-3H20v-2h-2.09c.05-.33.09-.66.09-1v-1h2v-2h-2v-1c0-.34-.04-.67-.09-1H20z"/></svg></span></a></li>

 <li>

 <p>Move all existing functionality into a subcommand, in anticipation of

     other passphrase derivation schemes, with different settings.

@@ -2311,11 +2667,13 @@ even if <code>vault</code> is not installed.

 instead of globally.

 Automatically fall back to, and migrate, the old global settings file if

 no subsystem-specific configuration was found.

-(<a href="https://github.com/the-13th-letter/derivepassphrase/10">#10</a>)</p>

+→<a href="../wishlist/other-derivation-schemes/" title="Wish entry: “Consider implementing passphrase schemes other than vault's”"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.06 1.93C7.17 1.92 5.33 3.74 6.17 6H3a2 2 0 0 0-2 2v2a1 1 0 0 0 1 1h9V8h2v3h9a1 1 0 0 0 1-1V8a2 2 0 0 0-2-2h-3.17C19 2.73 14.6.42 12.57 3.24L12 4l-.57-.78c-.63-.89-1.5-1.28-2.37-1.29M9 4c.89 0 1.34 1.08.71 1.71S8 5.89 8 5a1 1 0 0 1 1-1m6 0c.89 0 1.34 1.08.71 1.71S14 5.89 14 5a1 1 0 0 1 1-1M2 12v8a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2v-8h-9v8h-2v-8z"/></svg></span></a>

+<a href="../wishlist/scheme-specific-cli-and-config/" title="Wish entry: “Move vault-specific command-line interface into a separate CLI subcommand and matching configuration file”"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.06 1.93C7.17 1.92 5.33 3.74 6.17 6H3a2 2 0 0 0-2 2v2a1 1 0 0 0 1 1h9V8h2v3h9a1 1 0 0 0 1-1V8a2 2 0 0 0-2-2h-3.17C19 2.73 14.6.42 12.57 3.24L12 4l-.57-.78c-.63-.89-1.5-1.28-2.37-1.29M9 4c.89 0 1.34 1.08.71 1.71S8 5.89 8 5a1 1 0 0 1 1-1m6 0c.89 0 1.34 1.08.71 1.71S14 5.89 14 5a1 1 0 0 1 1-1M2 12v8a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2v-8h-9v8h-2v-8z"/></svg></span></a></p>

 </li>

 <li>

-<p>Make <code>derivepassphrase_export</code> a subcommand: <code>derivepassphrase export</code>.

-    (<a href="https://github.com/the-13th-letter/derivepassphrase/11">#11</a>)</p>

+<p>Make <code>derivepassphrase_export</code> a subcommand: <a href="../reference/derivepassphrase-export.1/"><code>derivepassphrase

+    export</code></a>.

+    →<a href="../wishlist/exporter-script-as-subcommand/" title="Wish entry: “Make the exporter a subcommand of derivepassphrase”"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.06 1.93C7.17 1.92 5.33 3.74 6.17 6H3a2 2 0 0 0-2 2v2a1 1 0 0 0 1 1h9V8h2v3h9a1 1 0 0 0 1-1V8a2 2 0 0 0-2-2h-3.17C19 2.73 14.6.42 12.57 3.24L12 4l-.57-.78c-.63-.89-1.5-1.28-2.37-1.29M9 4c.89 0 1.34 1.08.71 1.71S8 5.89 8 5a1 1 0 0 1 1-1m6 0c.89 0 1.34 1.08.71 1.71S14 5.89 14 5a1 1 0 0 1 1-1M2 12v8a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2v-8h-9v8h-2v-8z"/></svg></span></a></p>

 </li>

 </ul>

 <h3 id="deprecated-in-v0.2.0">Deprecated<a class="headerlink" href="#deprecated-in-v0.2.0" title="Permanent link">&para;</a></h3>

@@ -2328,14 +2686,14 @@ no subsystem-specific configuration was found.

 <ul>

 <li>Do not crash upon selecting a key on the command-line if there already

     is a key stored in the configuration.

-    (<a href="https://github.com/the-13th-letter/derivepassphrase/5">#5</a>)</li>

+    →<a href="../wishlist/one-time-key-override-fails/" title="Bug entry: “derivepassphrase -k fails when overriding the chosen key on the command-line”"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M14 12h-4v-2h4m0 6h-4v-2h4m6-6h-2.81a6 6 0 0 0-1.82-1.96L17 4.41 15.59 3l-2.17 2.17a6 6 0 0 0-2.83 0L8.41 3 7 4.41l1.62 1.63C7.88 6.55 7.26 7.22 6.81 8H4v2h2.09c-.05.33-.09.66-.09 1v1H4v2h2v1c0 .34.04.67.09 1H4v2h2.81c1.04 1.79 2.97 3 5.19 3s4.15-1.21 5.19-3H20v-2h-2.09c.05-.33.09-.66.09-1v-1h2v-2h-2v-1c0-.34-.04-.67-.09-1H20z"/></svg></span></a></li>

 <li>Create the configuration directory upon saving, if it does not yet

     exist.

-    (<a href="https://github.com/the-13th-letter/derivepassphrase/6">#6</a>)</li>

+    →<a href="../wishlist/configuration-directory-must-exist/" title="Bug entry: “derivepassphrase --config requires configuration directory to exist”"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M14 12h-4v-2h4m0 6h-4v-2h4m6-6h-2.81a6 6 0 0 0-1.82-1.96L17 4.41 15.59 3l-2.17 2.17a6 6 0 0 0-2.83 0L8.41 3 7 4.41l1.62 1.63C7.88 6.55 7.26 7.22 6.81 8H4v2h2.09c-.05.33-.09.66-.09 1v1H4v2h2v1c0 .34.04.67.09 1H4v2h2.81c1.04 1.79 2.97 3 5.19 3s4.15-1.21 5.19-3H20v-2h-2.09c.05-.33.09-.66.09-1v-1h2v-2h-2v-1c0-.34-.04-.67-.09-1H20z"/></svg></span></a></li>

 <li>Isolate the tests properly and consistently from the user&rsquo;s

     configuration, so that user configuration problems do not cause

     unrelated test failures.

-    (<a href="https://github.com/the-13th-letter/derivepassphrase/8">#8</a>)</li>

+    →<a href="../wishlist/test-filesystem-isolation/" title="Bug entry: “Isolate tests properly from the filesystem”"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M14 12h-4v-2h4m0 6h-4v-2h4m6-6h-2.81a6 6 0 0 0-1.82-1.96L17 4.41 15.59 3l-2.17 2.17a6 6 0 0 0-2.83 0L8.41 3 7 4.41l1.62 1.63C7.88 6.55 7.26 7.22 6.81 8H4v2h2.09c-.05.33-.09.66-.09 1v1H4v2h2v1c0 .34.04.67.09 1H4v2h2.81c1.04 1.79 2.97 3 5.19 3s4.15-1.21 5.19-3H20v-2h-2.09c.05-.33.09-.66.09-1v-1h2v-2h-2v-1c0-.34-.04-.67-.09-1H20z"/></svg></span></a></li>

 <li>Add an alternate MkDocs configuration for building the documentation in

     offline mode.</li>

 <li>Fix typing issues according to <code>mypy</code>&rsquo;s strict mode.</li>

@@ -2347,14 +2705,12 @@ no subsystem-specific configuration was found.

     distributions.

     (Previously, <code>sdist</code> contained VCS artifacts, and <code>wheel</code> was missing

     some paths.)</li>

-<li>Lint and reformat all code using <a href="https://pypi.org/package/ruff/">ruff</a>.</li>

-<li>Mention

-    <a href="https://pypi.org/package/mkdocstrings-python/"><code>mkdocstrings-python</code></a>

-    in the documentation&rsquo;s page footer.</li>

+<li>Lint and reformat all code using <a href="https://pypi.org/project/ruff/">ruff</a>.</li>

+<li>Mention <a href="https://pypi.org/project/mkdocstrings-python/"><code>mkdocstrings-python</code></a> in the

+    documentation&rsquo;s page footer.</li>

 <li>Remove JavaScript and external font loading from documentation website,

     so that the site works even in restricted browser settings.</li>

-<li>Set up a changelog, using

-    <a href="https://pypi.org/package/towncrier">towncrier</a>.</li>

+<li>Set up a changelog, using <a href="https://pypi.org/project/towncrier/">towncrier</a>.</li>

 </ul>

 <h2 id="v0.1.1">0.1.1 (2024-07-14)<a class="headerlink" href="#v0.1.1" title="Permanent link">&para;</a></h2>

 <h3 id="fixed-in-v0.1.1">Fixed<a class="headerlink" href="#fixed-in-v0.1.1" title="Permanent link">&para;</a></h3>

@@ -2370,6 +2726,16 @@ no subsystem-specific configuration was found.

 <ul>

 <li>Initial release.</li>

 </ul>

+<div class="footnote">

+<hr />

+<ol>

+<li id="fn:the-annoying-os">

+<p>Hat tip&mdash;and apologies&mdash;to

+<a href="https://github.com/pawamoy/">Timothée Mazzucotelli (<code>@pawamoy</code>)</a> for

+the fitting terminology.&#160;<a class="footnote-backref" href="#fnref:the-annoying-os" title="Jump back to footnote 1 in the text">&#8617;</a></p>

+</li>

+</ol>

+</div>

@@ -2,206 +2,206 @@

 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/changelog/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/pycompatibility/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/upgrade-notes/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/explanation/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/explanation/faq-altered-versions/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/explanation/faq-vault-interchangable-passphrases/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/how-tos/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/how-tos/ssh-key/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/reference/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/reference/derivepassphrase-export-vault.1/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/reference/derivepassphrase-export.1/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/reference/derivepassphrase-vault.1/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/reference/derivepassphrase.1/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/reference/derivepassphrase._internals.cli_helpers/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/reference/derivepassphrase._internals.cli_machinery/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/reference/derivepassphrase._internals.cli_messages/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/reference/derivepassphrase._types/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/reference/derivepassphrase.cli/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/reference/derivepassphrase.exporter/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/reference/derivepassphrase.sequin/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/reference/derivepassphrase.ssh_agent/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/reference/derivepassphrase.vault/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/reference/prerequisites-ssh-key/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/tutorials/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/tutorials/basic-setup-passphrase/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/wishlist/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/wishlist/allow-all-unicode-passphrases/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/wishlist/amend-vault-config/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/wishlist/better-error-messages/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/wishlist/concurrency-audit/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/wishlist/concurrency-testing-in-test-suite/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/wishlist/configuration-directory-must-exist/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/wishlist/conventional-configurable-text-styling/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/wishlist/export-vault-formats/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/wishlist/exporter-script-as-subcommand/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/wishlist/fail-gracefully-without-af-unix/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/wishlist/falsy-vault-config-values/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/wishlist/no-stdlib-module-names/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/wishlist/one-time-key-override-fails/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/wishlist/other-derivation-schemes/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/wishlist/pretty-print-json/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/wishlist/print-service-notes-above/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/wishlist/print-service-notes/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/wishlist/remove-pageant-build-info-check/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/wishlist/report-build-flags-and-features/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/wishlist/scheme-specific-cli-and-config/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/wishlist/single-toplevel-module/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/wishlist/test-filesystem-isolation/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/wishlist/test-suite-isolated-ssh-agent/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

     <url>

          <loc>https://the13thletter.info/derivepassphrase/0.x/wishlist/windows-ssh-agent-support/</loc>

-         <lastmod>2025-06-14</lastmod>

+         <lastmod>2025-06-18</lastmod>

     </url>

 </urlset>

\ No newline at end of file

@@ -32,3 +32,12 @@ a.fixed {

     font-style: normal;

     text-decoration: line-through;

 }

+

+.md-typeset div.admonition.abstract .emojione,

+.md-typeset div.admonition.abstract .gemoji,

+.md-typeset div.admonition.abstract .twemoji,

+.md-typeset a[href^="wishlist/"] .emojione,

+.md-typeset a[href^="wishlist/"] .gemoji,

+.md-typeset a[href^="wishlist/"] .twemoji {

+    vertical-align: middle;

+}