derivepassphrase.git

1) # Changelog for `derivepassphrase`
2) 
3) [![Keeping a changelog][CHANGELOG_BADGE]][KEEP_A_CHANGELOG]
4) [![Using Semantic Versioning][SEMVER_BADGE]][SEMANTIC_VERSIONING]
5) 
6)   [CHANGELOG_BADGE]: Keep_a_changelog-E05735.svg
7)   [SEMVER_BADGE]: SemVer-3F4551.svg
8)   [KEEP_A_CHANGELOG]: https://keepachangelog.com/en/1.1.0/ 'Keeping a changelog'
9)   [SEMANTIC_VERSIONING]: https://semver.org/ 'Using Semantic Versioning'
10) 
11) <aside markdown><small>
12) (All entries are from the perspective of a user, not a developer.
13) The <q>public API</q>, as defined by Semantic Versioning, is outlined in the
14) [Reference section][REFERENCE]: the set of documented modules, classes,
15) methods and functions, and the documented behavior, options and arguments of
16) the command-line tools.
17) As per the Semantic Versioning and the Keep a Changelog terminology,
18) <q>Fixed</q> entries justify a <q>patch</q> release,
19) <q>Added</q> and <q>Deprecated</q> entries a <q>minor</q> release,
20) and <q>Changed</q> and <q>Removed</q> entries a <q>major</q> release.
21) <q>Security</q> can justify any type of release;
22) if <q>major</q> or <q>minor</q>, these are accompanied by corresponding
23) entries of the respective types above.
24) Again as per Semantic Versioning, at major version zero, the above
25) justification is not yet binding, and <em>any</em> new release may
26) effectively constitute a new <q>major</q> release.)
27) </small></aside>
28) 

29)   [REFERENCE]: reference/index.md

30) 

31) <!-- scriv changelog start -->

32) 

33) ## 0.4.0 (2025-01-07)
34) 
35) ### Added
36) 
37)   - Both `derivepassphrase vault` and `derivepassphrase export vault` now
38)     support changing the amount of diagnostic output they emit via new
39)     command-line options `--debug`, `-v`/`--verbose` and `-q`/`--quiet`.
40)     Internally, this uses Python's standard [logging][] and [warnings][]
41)     systems.
42) 
43)   - `derivepassphrase` now uses a central configuration file, and additional
44)     data files, some of which are service-specific.  (The `vault.json`
45)     configuration file is now rebranded as a data file.)  The configuration
46)     files are user-editable, the data files are `derivepassphrase`-editable.
47) 
48)     The configuration files are in TOML format, so installing
49)     `derivepassphrase` on Python 3.10 and older requires the
50)     [`tomli`][tomli] package.
51) 
52)   - `derivepassphrase vault --config` now supports an `--unset` option which
53)     unsets any given named setting prior to applying any other configuration
54)     changes.
55) 
56)   - `derivepassphrase vault --export` can now also export the current
57)     configuration as a POSIX `sh` script, using the `--export-as=sh` option.
58)     The default (and previous behavior) is `--export-as=json`.
59) 
60)   - `derivepassphrase` now includes basic support for localization: if the
61)     necessary translations are installed, then the diagnostics and help
62)     texts can be emitted in different languages.  Internally, this uses
63)     Python's standard [`gettext`][] system.
64) 
65)     (As of this version, no translations have actually been prepared yet.)
66) 
67)   - `derivepassphrase` now explicitly supports shell completion, in
68)     particular filename and service name completion in the `export vault`
69)     and `vault` subcommands.
70) 
71)     However, because of restrictions regarding the exchange of data between
72)     `derivepassphrase` and the shell, `derivepassphrase` will not offer any
73)     service names containing ASCII control characters for completion, and
74)     a warning will be issued when importing or configuring such a service.
75)     They may still otherwise be used normally.
76) 
77)   - Support the semi-standard `NO_COLOR` and the `FORCE_COLOR` environment
78)     variables to suppress or force color output from `derivepassphrase`.
79)     (`FORCE_COLOR` overrides `NO_COLOR` if both are set.)
80) 
81) [tomli]: https://pypi.org/project/tomli/
82) 
83) ### Changed
84) 
85)   - Calling [`derivepassphrase_export`]
86)     [derivepassphrase.cli.derivepassphrase_export],
87)     [`derivepassphrase_export_vault`]
88)     [derivepassphrase.cli.derivepassphrase_export_vault] or
89)     [`derivepassphrase_vault`]
90)     [derivepassphrase.cli.derivepassphrase_vault], or calling
91)     [`derivepassphrase`] [derivepassphrase.cli.derivepassphrase] via its
92)     [`.main`][click.BaseCommand.main] method, causes those functions to use
93)     the standard Python [logging][] and [warnings][] facilities to issue
94)     diagnostic messages, without output to standard error.  (This includes
95)     using [`click.testing.CliRunner`][], which uses `.main` calls under the
96)     hood.)  Calling [`derivepassphrase`]
97)     [derivepassphrase.cli.derivepassphrase] directly as a function diverts
98)     diagnostic messages to standard error.
99) 
100)   - Unicode normalization settings for `vault` service names and stored
101)     passphrases are now stored in the central configuration file, instead of
102)     the `vault` data file.
103) 
104)   - `derivepassphrase` changed its license from [MIT][] to [zlib/libpng][].
105)     This should only make a difference to people redistributing altered
106)     versions of `derivepassphrase`; the basic freedoms, and the
107)     combinability of `derivepassphrase` with other software should be
108)     unaffected.
109) 
110) [MIT]: https://spdx.org/licenses/MIT.html
111) [zlib/libpng]: https://spdx.org/licenses/Zlib.html
112) 

113) ## 0.3.3 (2024-11-28)
114) 
115) ### Added
116) 
117)   - Checking whether an SSH key is suitable now also depends on the SSH
118)     agent in use.  API functions now optionally take an additional
119)     [`SSHAgentClient`][derivepassphrase.ssh_agent.SSHAgentClient] object to
120)     test agent-specific key suitability.  If not given, then the old
121)     behavior is retained: SSH keys are suitable if they are suitable under
122)     any (conforming) SSH agent.
123) 
124) ### Fixed
125) 
126)   - If the SSH agent supports deterministic DSA/ECDSA signatures (e.g.
127)     [RFC 6979][]), then mark DSA and ECDSA SSH keys as suitable.
128) 
129) [RFC 6979]: https://www.rfc-editor.org/rfc/rfc6979
130) 

131) ## 0.3.2 (2024-10-21)
132) 
133) ### Fixed
134) 
135)   - _*Actually* actually_ remove the `derivepassphrase_export` program, which was
136)     turned into a subcommand in v0.2.0 and supposed to have been removed in
137)     v0.3.1 already.  Removed on disk is not the same as removed in
138)     version control.
139) 

140) ## 0.3.1 (2024-10-21)
141) 
142) ### Fixed
143) 
144)   - Fix PyPI classification: Python 3.9 is supported.
145)   - *Actually* remove the `derivepassphrase_export` program, which was
146)     turned into a subcommand in v0.2.0.
147) 

148) ## 0.3.0 (2024-10-15)
149) 
150) ### Added
151) 
152)   - Convert changelog management from towncrier to [scriv][].
153)   - Add SSH agent spawning support to the test suite.  Use this support to
154)     test the agent functionality on all known major SSH agent
155)     implementations automatically. ([#12])
156)   - Add [hypothesis][]-based tests to the test suite.
157)   - Update README to add explanations for virtual environments and package
158)     extras.
159)   - Update README to demonstrate configuration storing and SSH agent use.
160)     Include comments on Windows support for SSH agents.
161)   - Use cross-references in the documentation of function signatures.
162)   - Add proper support for Buffer types in the SSH agent client.  Any
163)     Python object supporting the buffer protocol can be used as input to
164)     a function of the client, and any output from the client is returned
165)     as bytes objects.  Because of the zero-copy semantics of the
166)     underlying data/memory block, this should stay relatively time- and
167)     space-efficient.
168)   - Add [hypothesis][]-based tests for serialization to and
169)     deserialization from the SSH agent wire format.
170)   - Support Python 3.9 and 3.13.
171) 
172) [#12]: https://github.com/the-13th-letter/derivepassphrase/issues/12
173) [hypothesis]: https://pypi.org/project/hypothesis/
174) [scriv]: https://pypi.org/project/scriv
175) 
176) ### Changed
177) 
178)   - Change links to point to public project repositories, if possible.  For
179)     legal reasons.
180) 
181)   - Use the same filename/URL convention for API reference as the Python
182)     standard library does.
183) 
184)   - Rewrite functionality for checking for valid vault(1) configurations:
185)     include an actual validation function which throws errors upon
186)     encountering format violations, and which allows specifying which types
187)     of extensions (unknown settings, `derivepassphrase`-only settings) to
188)     tolerate during validation.
189) 
190)     This is a **breaking API change** because the function return annotation
191)     changed, from [`typing.TypeGuard`][] to [`typing_extensions.TypeIs`][].
192)     These were the originally intended semantics, but when
193)     `derivepassphrase` was first designed, the Python type system did not
194)     support this kind of partial type narrowing.
195) 
196)   - Fail earlier, and more gracefully/specifically, when we cannot talk to
197)     the SSH agent because Python does not support UNIX domain sockets on
198)     this system.  In particular, this is the current situation on Windows.
199) 
200)     This adds another failure case to the `SSHAgentClient` constructor, and
201)     therefore constitutes a **breaking API change**.
202) 
203)   - In `derivepassphrase vault`, accept `key` and `phrase` entries just like
204)     vault(1) does: `key` always overrides `phrase` in the configuration, no
205)     matter the level.
206) 
207)     This is a command-line only change.
208) 
209)   - In `derivepassphrase vault`, when importing settings, accept falsy values
210)     everywhere `vault` does, with a warning.  Depending on the setting, they
211)     are equivalent to zero, the empty string, or "not set".  ([#17])
212) 
213)     This is a command-line only change, and only affects importing.  The API
214)     provides a new function to normalize falsy settings, but still otherwise
215)     requires settings to be of the correct type.  Storing a malformed
216)     configuration with such falsy values will still generate errors when
217)     `derivepassphrase vault` loads the settings from disk.
218) 
219)   - In `derivepassphrase vault`, when importing configurations,
220)     correctly merge them with the existing one, same as vault(1): keep
221)     all named services and their settings (and the global settings if
222)     applicable) that are not mentioned in the imported configuration.
223)     The import procedure is thus more akin to a section-wise import of
224)     the configurations, instead of a "full" import, and the resulting
225)     configuration generally is a merge of both inputs.  ([#16])
226) 
227)   - The following operations or configuration settings now raise
228)     warnings:
229) 
230)       * in imported configurations: using falsy values of the wrong type
231)       * in imported configurations: using falsy values with no practical
232)         effect
233)       * setting a passphrase in the configuration if a key is already
234)         set
235)       * using an empty service name on the command-line or in an
236)         imported configuration
237) 
238) [#16]: https://github.com/the-13th-letter/derivepassphrase/issues/16
239) [#17]: https://github.com/the-13th-letter/derivepassphrase/issues/17
240) 
241) ### Fixed
242) 
243)   - Fixed the textual description of the return value for
244)     [`SSHAgentClient.request`][derivepassphrase.ssh_agent.SSHAgentClient.request],
245)     which didn't match the declared type annotation.
246) 

247) ## 0.2.0 (2024-09-12)
248) 

249) ### Added

250) 

251)   - Support configuration data export from `vault` in v0.2, v0.3 and
252)     storeroom formats.

253) 
254)     This feature requires the `cryptography` Python module, but is available

255)     even if `vault` is not installed. ([#1])

256) 
257) [#1]: https://github.com/the-13th-letter/derivepassphrase/1
258) 

259) ### Fixed
260) 
261)   - Deploy versioned documentation with [mike][].  Set up a "latest" tag and
262)     the "0.<var>x</var>" version of the documentation with the contents so
263)     far.
264) 
265) [mike]: https://pypi.org/project/mike
266) 
267) ### Changed
268) 
269)   - Changed `sequin` and `ssh_agent_client` to be submodules of
270)     `derivepassphrase`.  Further moved `derivepassphrase.Vault` and
271)     `derivepassphrase.AmbiguousByteRepresentation` into a new submodule
272)     `vault`, and renamed submodule `ssh_agent_client` to `ssh_agent`. ([#3])
273)   - Changed internal error handling and error messages, to better work in
274)     the context of a command-line tool. ([#4])
275)   - Combine and consolidate `derivepassphrase.types` and
276)     `derivepassphrase.ssh_agent.types` into a new submodule
277)     `derivepassphrase._types`.  Despite the name, the module is public.
278)     ([#7])
279)   - Warn the user when entering (directly, or via configuration
280)     editing/importing) a passphrase that is not in the configured Unicode
281)     normalization form. (But don't otherwise reject any textual master
282)     passphrases.) ([#9])
283)   - Move all existing functionality into a subcommand, in anticipation of
284)     other passphrase derivation schemes, with different settings.
285)     Automatically forward calls without a subcommand to the "vault"
286)     subcommand.

287) 
288)     Also store the settings in a file specific to the respective subsystem,

289)     instead of globally.  Automatically fall back to, and migrate, the old
290)     global settings file if no subsystem-specific configuration was found.
291)     ([#10])

292) 

293)   - Make `derivepassphrase_export` a subcommand: `derivepassphrase export`.
294)     ([#11])

295) 
296) [#3]: https://github.com/the-13th-letter/derivepassphrase/3
297) [#4]: https://github.com/the-13th-letter/derivepassphrase/4
298) [#7]: https://github.com/the-13th-letter/derivepassphrase/7
299) [#9]: https://github.com/the-13th-letter/derivepassphrase/9
300) [#10]: https://github.com/the-13th-letter/derivepassphrase/10
301) [#11]: https://github.com/the-13th-letter/derivepassphrase/11
302) 

303) ### Deprecated

304) 

305)   - Using the implied subcommand or the implied global configuration file is
306)     deprecated, and will be removed in v1.0.

307) 
308) 

309) ## 0.1.3 (2024-07-28)
310) 

311) ### Fixed

312) 

313)   - Do not crash upon selecting a key on the command-line if there already
314)     is a key stored in the configuration. ([#5])
315)   - Create the configuration directory upon saving, if it does not yet
316)     exist.  ([#6])
317)   - Isolate the tests properly and consistently from the user's
318)     configuration, so that user configuration problems do not cause
319)     unrelated test failures. ([#8])
320)   - Add an alternate MkDocs configuration for building the documentation in
321)     offline mode.
322)   - Fix typing issues according to `mypy`'s strict mode.

323) 
324) [#5]: https://github.com/the-13th-letter/derivepassphrase/5
325) [#6]: https://github.com/the-13th-letter/derivepassphrase/6
326) [#8]: https://github.com/the-13th-letter/derivepassphrase/8
327) 
328) 

329) ## 0.1.2 (2024-07-22)
330) 

331) ### Fixed

332) 

333)   - Include and exclude the correct files in the `sdist` and `wheel`
334)     distributions.  (Previously, `sdist` contained VCS artifacts, and
335)     `wheel` was missing some paths.)

336)   - Lint and reformat all code using [ruff](https://pypi.org/package/ruff/).
337)   - Mention
338)     [`mkdocstrings-python`](https://pypi.org/package/mkdocstrings-python/)

339)     in the documentation's page footer.
340)   - Remove JavaScript and external font loading from documentation website,
341)     so that the site works even in restricted browser settings.
342)   - Set up a changelog, using
343)     [towncrier](https://pypi.org/package/towncrier).

344) 
345) 

346) ## 0.1.1 (2024-07-14)
347) 

348) ### Fixed

349) 

350)   - Restore the `__version__` attribute in all top-level packages.
351)   - Declare compatibility with Python 3.10 in project metadata, and include
352)     necessary version-specific dependencies.
353)   - Publish the documentation online, and link to it in the repository
354)     metadata and the Python package metadata.

355) 
356) 
357) ## 0.1.0 (2024-07-14)
358) 

359) ### Added

360)