derivepassphrase.git

1) # SPDX-FileCopyrightText: 2024 Marco Ricci <software@the13thletter.info>

2) #
3) # SPDX-License-Identifier: MIT
4) 

5) """Command-line interface for derivepassphrase."""

6) 
7) from __future__ import annotations
8) 

9) import base64
10) import collections
11) import contextlib

12) import copy

13) import importlib

14) import inspect
15) import json

16) import logging

17) import os
18) import socket

19) import unicodedata

20) from typing import (
21)     TYPE_CHECKING,

22)     Literal,

23)     NoReturn,

24)     TextIO,
25)     cast,

26) )

27) 
28) import click

29) from typing_extensions import (
30)     Any,
31)     assert_never,
32) )
33) 

34) import derivepassphrase as dpp

35) from derivepassphrase import _types, exporter, ssh_agent, vault

36) 
37) if TYPE_CHECKING:
38)     import pathlib

39)     import types

40)     from collections.abc import (
41)         Iterator,
42)         Sequence,
43)     )

44) 
45) __author__ = dpp.__author__
46) __version__ = dpp.__version__
47) 
48) __all__ = ('derivepassphrase',)
49) 

50) PROG_NAME = 'derivepassphrase'
51) KEY_DISPLAY_LENGTH = 30
52) 
53) # Error messages
54) _INVALID_VAULT_CONFIG = 'Invalid vault config'
55) _AGENT_COMMUNICATION_ERROR = 'Error communicating with the SSH agent'
56) _NO_USABLE_KEYS = 'No usable SSH keys were found'
57) _EMPTY_SELECTION = 'Empty selection'

58) 
59) 

60) # Top-level
61) # =========
62) 
63) 
64) @click.command(
65)     context_settings={
66)         'help_option_names': ['-h', '--help'],
67)         'ignore_unknown_options': True,
68)         'allow_interspersed_args': False,
69)     },
70)     epilog=r"""
71)         Configuration is stored in a directory according to the
72)         DERIVEPASSPHRASE_PATH variable, which defaults to
73)         `~/.derivepassphrase` on UNIX-like systems and
74)         `C:\Users\<user>\AppData\Roaming\Derivepassphrase` on Windows.

75)     """,

76) )
77) @click.version_option(version=dpp.__version__, prog_name=PROG_NAME)
78) @click.argument('subcommand_args', nargs=-1, type=click.UNPROCESSED)
79) def derivepassphrase(
80)     *,
81)     subcommand_args: list[str],
82) ) -> None:
83)     """Derive a strong passphrase, deterministically, from a master secret.
84) 
85)     Using a master secret, derive a passphrase for a named service,
86)     subject to constraints e.g. on passphrase length, allowed
87)     characters, etc.  The exact derivation depends on the selected
88)     derivation scheme.  For each scheme, it is computationally
89)     infeasible to discern the master secret from the derived passphrase.
90)     The derivations are also deterministic, given the same inputs, thus
91)     the resulting passphrases need not be stored explicitly.  The
92)     service name and constraints themselves also generally need not be
93)     kept secret, depending on the scheme.
94) 
95)     The currently implemented subcommands are "vault" (for the scheme
96)     used by vault) and "export" (for exporting foreign configuration
97)     data).  See the respective `--help` output for instructions.  If no
98)     subcommand is given, we default to "vault".
99) 
100)     Deprecation notice: Defaulting to "vault" is deprecated.  Starting
101)     in v1.0, the subcommand must be specified explicitly.\f
102) 
103)     This is a [`click`][CLICK]-powered command-line interface function,
104)     and not intended for programmatic use.  Call with arguments
105)     `['--help']` to see full documentation of the interface.  (See also
106)     [`click.testing.CliRunner`][] for controlled, programmatic
107)     invocation.)
108) 
109)     [CLICK]: https://click.palletsprojects.com/
110) 
111)     """  # noqa: D301
112)     if subcommand_args and subcommand_args[0] == 'export':
113)         return derivepassphrase_export.main(
114)             args=subcommand_args[1:],
115)             prog_name=f'{PROG_NAME} export',
116)             standalone_mode=False,
117)         )
118)     if not (subcommand_args and subcommand_args[0] == 'vault'):
119)         click.echo(
120)             (
121)                 f'{PROG_NAME}: Deprecation warning: A subcommand will be '
122)                 f'required in v1.0. See --help for available subcommands.'
123)             ),
124)             err=True,
125)         )
126)         click.echo(
127)             f'{PROG_NAME}: Warning: Defaulting to subcommand "vault".',
128)             err=True,
129)         )
130)     else:
131)         subcommand_args = subcommand_args[1:]
132)     return derivepassphrase_vault.main(
133)         args=subcommand_args,
134)         prog_name=f'{PROG_NAME} vault',
135)         standalone_mode=False,
136)     )
137) 
138) 
139) # Exporter
140) # ========
141) 
142) 
143) @click.command(
144)     context_settings={
145)         'help_option_names': ['-h', '--help'],
146)         'ignore_unknown_options': True,
147)         'allow_interspersed_args': False,
148)     }
149) )
150) @click.version_option(version=dpp.__version__, prog_name=PROG_NAME)
151) @click.argument('subcommand_args', nargs=-1, type=click.UNPROCESSED)
152) def derivepassphrase_export(
153)     *,
154)     subcommand_args: list[str],
155) ) -> None:
156)     """Export a foreign configuration to standard output.
157) 
158)     Read a foreign system configuration, extract all information from
159)     it, and export the resulting configuration to standard output.
160) 
161)     The only available subcommand is "vault", which implements the
162)     vault-native configuration scheme.  If no subcommand is given, we
163)     default to "vault".
164) 
165)     Deprecation notice: Defaulting to "vault" is deprecated.  Starting
166)     in v1.0, the subcommand must be specified explicitly.\f
167) 
168)     This is a [`click`][CLICK]-powered command-line interface function,
169)     and not intended for programmatic use.  Call with arguments
170)     `['--help']` to see full documentation of the interface.  (See also
171)     [`click.testing.CliRunner`][] for controlled, programmatic
172)     invocation.)
173) 
174)     [CLICK]: https://click.palletsprojects.com/
175) 
176)     """  # noqa: D301
177)     if not (subcommand_args and subcommand_args[0] == 'vault'):
178)         click.echo(
179)             (
180)                 f'{PROG_NAME}: Deprecation warning: A subcommand will be '
181)                 f'required in v1.0. See --help for available subcommands.'
182)             ),
183)             err=True,
184)         )
185)         click.echo(
186)             f'{PROG_NAME}: Warning: Defaulting to subcommand "vault".',
187)             err=True,
188)         )
189)     else:
190)         subcommand_args = subcommand_args[1:]
191)     return derivepassphrase_export_vault.main(
192)         args=subcommand_args,
193)         prog_name=f'{PROG_NAME} export vault',
194)         standalone_mode=False,
195)     )
196) 
197) 
198) def _load_data(
199)     fmt: Literal['v0.2', 'v0.3', 'storeroom'],
200)     path: str | bytes | os.PathLike[str],
201)     key: bytes,
202) ) -> Any:  # noqa: ANN401
203)     contents: bytes
204)     module: types.ModuleType
205)     match fmt:
206)         case 'v0.2':
207)             module = importlib.import_module(
208)                 'derivepassphrase.exporter.vault_native'
209)             )
210)             if module.STUBBED:
211)                 raise ModuleNotFoundError
212)             with open(path, 'rb') as infile:
213)                 contents = base64.standard_b64decode(infile.read())
214)             return module.export_vault_native_data(
215)                 contents, key, try_formats=['v0.2']
216)             )
217)         case 'v0.3':
218)             module = importlib.import_module(
219)                 'derivepassphrase.exporter.vault_native'
220)             )
221)             if module.STUBBED:
222)                 raise ModuleNotFoundError
223)             with open(path, 'rb') as infile:
224)                 contents = base64.standard_b64decode(infile.read())
225)             return module.export_vault_native_data(
226)                 contents, key, try_formats=['v0.3']
227)             )
228)         case 'storeroom':
229)             module = importlib.import_module(
230)                 'derivepassphrase.exporter.storeroom'
231)             )
232)             if module.STUBBED:
233)                 raise ModuleNotFoundError
234)             return module.export_storeroom_data(path, key)
235)         case _:  # pragma: no cover
236)             assert_never(fmt)
237) 
238) 
239) @click.command(
240)     context_settings={'help_option_names': ['-h', '--help']},
241) )
242) @click.option(
243)     '-f',
244)     '--format',
245)     'formats',
246)     metavar='FMT',
247)     multiple=True,
248)     default=('v0.3', 'v0.2', 'storeroom'),
249)     type=click.Choice(['v0.2', 'v0.3', 'storeroom']),
250)     help='try the following storage formats, in order (default: v0.3, v0.2)',
251) )
252) @click.option(
253)     '-k',
254)     '--key',
255)     metavar='K',
256)     help=(
257)         'use K as the storage master key '
258)         '(default: check the `VAULT_KEY`, `LOGNAME`, `USER` or '
259)         '`USERNAME` environment variables)'
260)     ),
261) )
262) @click.argument('path', metavar='PATH', required=True)
263) @click.pass_context
264) def derivepassphrase_export_vault(
265)     ctx: click.Context,
266)     /,
267)     *,
268)     path: str | bytes | os.PathLike[str],
269)     formats: Sequence[Literal['v0.2', 'v0.3', 'storeroom']] = (),
270)     key: str | bytes | None = None,
271) ) -> None:
272)     """Export a vault-native configuration to standard output.
273) 
274)     Read the vault-native configuration at PATH, extract all information
275)     from it, and export the resulting configuration to standard output.
276)     Depending on the configuration format, PATH may either be a file or
277)     a directory.  Supports the vault "v0.2", "v0.3" and "storeroom"
278)     formats.
279) 
280)     If PATH is explicitly given as `VAULT_PATH`, then use the
281)     `VAULT_PATH` environment variable to determine the correct path.
282)     (Use `./VAULT_PATH` or similar to indicate a file/directory actually
283)     named `VAULT_PATH`.)
284) 
285)     """
286)     logging.basicConfig()
287)     if path in {'VAULT_PATH', b'VAULT_PATH'}:
288)         path = exporter.get_vault_path()
289)     if key is None:
290)         key = exporter.get_vault_key()
291)     elif isinstance(key, str):  # pragma: no branch
292)         key = key.encode('utf-8')
293)     for fmt in formats:
294)         try:
295)             config = _load_data(fmt, path, key)
296)         except (
297)             IsADirectoryError,
298)             NotADirectoryError,
299)             ValueError,
300)             RuntimeError,
301)         ):
302)             logging.info('Cannot load as %s: %s', fmt, path)
303)             continue
304)         except OSError as exc:
305)             click.echo(
306)                 (
307)                     f'{PROG_NAME}: ERROR: Cannot parse {path!r} as '
308)                     f'a valid config: {exc.strerror}: {exc.filename!r}'
309)                 ),
310)                 err=True,
311)             )
312)             ctx.exit(1)
313)         except ModuleNotFoundError:
314)             # TODO(the-13th-letter): Use backslash continuation.
315)             # https://github.com/nedbat/coveragepy/issues/1836
316)             msg = f"""
317) {PROG_NAME}: ERROR: Cannot load the required Python module "cryptography".
318) {PROG_NAME}: INFO: pip users: see the "export" extra.
319) """.lstrip('\n')
320)             click.echo(msg, nl=False, err=True)
321)             ctx.exit(1)
322)         else:
323)             if not _types.is_vault_config(config):
324)                 click.echo(
325)                     f'{PROG_NAME}: ERROR: Invalid vault config: {config!r}',
326)                     err=True,
327)                 )
328)                 ctx.exit(1)
329)             click.echo(json.dumps(config, indent=2, sort_keys=True))
330)             break
331)     else:
332)         click.echo(
333)             f'{PROG_NAME}: ERROR: Cannot parse {path!r} as a valid config.',
334)             err=True,
335)         )
336)         ctx.exit(1)
337) 
338) 
339) # Vault
340) # =====
341) 
342) 

343) def _config_filename(
344)     subsystem: str | None = 'settings',
345) ) -> str | bytes | pathlib.Path:
346)     """Return the filename of the configuration file for the subsystem.
347) 
348)     The (implicit default) file is currently named `settings.json`,
349)     located within the configuration directory as determined by the
350)     `DERIVEPASSPHRASE_PATH` environment variable, or by
351)     [`click.get_app_dir`][] in POSIX mode.  Depending on the requested
352)     subsystem, this will usually be a different file within that
353)     directory.

354) 

355)     Args:
356)         subsystem:
357)             Name of the configuration subsystem whose configuration
358)             filename to return.  If not given, return the old filename
359)             from before the subcommand migration.  If `None`, return the
360)             configuration directory instead.
361) 
362)     Raises:
363)         AssertionError:
364)             An unknown subsystem was passed.
365) 
366)     Deprecated:
367)         Since v0.2.0: The implicit default subsystem and the old
368)         configuration filename are deprecated, and will be removed in v1.0.
369)         The subsystem will be mandatory to specify.

370) 
371)     """
372)     path: str | bytes | pathlib.Path

373)     path = os.getenv(PROG_NAME.upper() + '_PATH') or click.get_app_dir(
374)         PROG_NAME, force_posix=True
375)     )

376)     match subsystem:
377)         case None:
378)             return path
379)         case 'vault' | 'settings':
380)             filename = f'{subsystem}.json'
381)         case _:  # pragma: no cover
382)             msg = f'Unknown configuration subsystem: {subsystem!r}'
383)             raise AssertionError(msg)
384)     return os.path.join(path, filename)

385) 
386) 

387) def _load_config() -> _types.VaultConfig:

388)     """Load a vault(1)-compatible config from the application directory.
389) 
390)     The filename is obtained via
391)     [`derivepassphrase.cli._config_filename`][].  This must be an
392)     unencrypted JSON file.
393) 
394)     Returns:
395)         The vault settings.  See

396)         [`derivepassphrase._types.VaultConfig`][] for details.

397) 
398)     Raises:
399)         OSError:
400)             There was an OS error accessing the file.
401)         ValueError:
402)             The data loaded from the file is not a vault(1)-compatible
403)             config.
404) 
405)     """

406)     filename = _config_filename(subsystem='vault')

407)     with open(filename, 'rb') as fileobj:
408)         data = json.load(fileobj)

409)     if not _types.is_vault_config(data):

410)         raise ValueError(_INVALID_VAULT_CONFIG)

411)     return data
412) 
413) 

414) def _migrate_and_load_old_config() -> (
415)     tuple[_types.VaultConfig, OSError | None]
416) ):
417)     """Load and migrate a vault(1)-compatible config.
418) 
419)     The (old) filename is obtained via
420)     [`derivepassphrase.cli._config_filename`][].  This must be an
421)     unencrypted JSON file.  After loading, the file is migrated to the new
422)     standard filename.
423) 
424)     Returns:
425)         The vault settings, and an optional exception encountered during

426)         migration.  See [`derivepassphrase._types.VaultConfig`][] for

427)         details on the former.
428) 
429)     Raises:
430)         OSError:
431)             There was an OS error accessing the old file.
432)         ValueError:
433)             The data loaded from the file is not a vault(1)-compatible
434)             config.
435) 
436)     """
437)     new_filename = _config_filename(subsystem='vault')
438)     old_filename = _config_filename()
439)     with open(old_filename, 'rb') as fileobj:
440)         data = json.load(fileobj)
441)     if not _types.is_vault_config(data):
442)         raise ValueError(_INVALID_VAULT_CONFIG)
443)     try:
444)         os.replace(old_filename, new_filename)
445)     except OSError as exc:
446)         return data, exc
447)     else:
448)         return data, None
449) 
450) 

451) def _save_config(config: _types.VaultConfig, /) -> None:

452)     """Save a vault(1)-compatible config to the application directory.

453) 
454)     The filename is obtained via
455)     [`derivepassphrase.cli._config_filename`][].  The config will be
456)     stored as an unencrypted JSON file.
457) 
458)     Args:
459)         config:
460)             vault configuration to save.
461) 
462)     Raises:
463)         OSError:
464)             There was an OS error accessing or writing the file.
465)         ValueError:
466)             The data cannot be stored as a vault(1)-compatible config.
467) 
468)     """

469)     if not _types.is_vault_config(config):

470)         raise ValueError(_INVALID_VAULT_CONFIG)

471)     filename = _config_filename(subsystem='vault')

472)     filedir = os.path.dirname(os.path.abspath(filename))
473)     try:
474)         os.makedirs(filedir, exist_ok=False)
475)     except FileExistsError:
476)         if not os.path.isdir(filedir):

477)             raise  # noqa: DOC501

478)     with open(filename, 'w', encoding='UTF-8') as fileobj:

479)         json.dump(config, fileobj)
480) 
481) 

482) def _get_suitable_ssh_keys(

483)     conn: ssh_agent.SSHAgentClient | socket.socket | None = None, /

484) ) -> Iterator[_types.KeyCommentPair]:

485)     """Yield all SSH keys suitable for passphrase derivation.
486) 
487)     Suitable SSH keys are queried from the running SSH agent (see

488)     [`derivepassphrase.ssh_agent.SSHAgentClient.list_keys`][]).

489) 
490)     Args:
491)         conn:
492)             An optional connection hint to the SSH agent; specifically,
493)             an SSH agent client, or a socket connected to an SSH agent.
494) 
495)             If an existing SSH agent client, then this client will be
496)             queried for the SSH keys, and otherwise left intact.
497) 
498)             If a socket, then a one-shot client will be constructed
499)             based on the socket to query the agent, and deconstructed
500)             afterwards.
501) 
502)             If neither are given, then the agent's socket location is
503)             looked up in the `SSH_AUTH_SOCK` environment variable, and
504)             used to construct/deconstruct a one-shot client, as in the
505)             previous case.
506) 
507)     Yields:
508)         :
509)             Every SSH key from the SSH agent that is suitable for
510)             passphrase derivation.
511) 
512)     Raises:

513)         KeyError:
514)             `conn` was `None`, and the `SSH_AUTH_SOCK` environment
515)             variable was not found.
516)         OSError:
517)             `conn` was a socket or `None`, and there was an error
518)             setting up a socket connection to the agent.

519)         LookupError:

520)             No keys usable for passphrase derivation are loaded into the
521)             SSH agent.

522)         RuntimeError:
523)             There was an error communicating with the SSH agent.

524)         ssh_agent.SSHAgentFailedError:

525)             The agent failed to supply a list of loaded keys.

526) 
527)     """

528)     client: ssh_agent.SSHAgentClient

529)     client_context: contextlib.AbstractContextManager[Any]

530)     match conn:

531)         case ssh_agent.SSHAgentClient():

532)             client = conn
533)             client_context = contextlib.nullcontext()
534)         case socket.socket() | None:

535)             client = ssh_agent.SSHAgentClient(socket=conn)

536)             client_context = client
537)         case _:  # pragma: no cover
538)             assert_never(conn)

539)             msg = f'invalid connection hint: {conn!r}'

540)             raise TypeError(msg)  # noqa: DOC501

541)     with client_context:
542)         try:
543)             all_key_comment_pairs = list(client.list_keys())
544)         except EOFError as e:  # pragma: no cover

545)             raise RuntimeError(_AGENT_COMMUNICATION_ERROR) from e
546)     suitable_keys = copy.copy(all_key_comment_pairs)

547)     for pair in all_key_comment_pairs:

548)         key, _comment = pair

549)         if vault.Vault._is_suitable_ssh_key(key):  # noqa: SLF001

550)             yield pair
551)     if not suitable_keys:  # pragma: no cover

552)         raise LookupError(_NO_USABLE_KEYS)

553) 
554) 
555) def _prompt_for_selection(

556)     items: Sequence[str | bytes],
557)     heading: str = 'Possible choices:',

558)     single_choice_prompt: str = 'Confirm this choice?',
559) ) -> int:
560)     """Prompt user for a choice among the given items.
561) 
562)     Print the heading, if any, then present the items to the user.  If
563)     there are multiple items, prompt the user for a selection, validate
564)     the choice, then return the list index of the selected item.  If
565)     there is only a single item, request confirmation for that item
566)     instead, and return the correct index.
567) 
568)     Args:

569)         items:
570)             The list of items to choose from.

571)         heading:
572)             A heading for the list of items, to print immediately
573)             before.  Defaults to a reasonable standard heading.  If
574)             explicitly empty, print no heading.
575)         single_choice_prompt:
576)             The confirmation prompt if there is only a single possible
577)             choice.  Defaults to a reasonable standard prompt.
578) 
579)     Returns:
580)         An index into the items sequence, indicating the user's
581)         selection.
582) 
583)     Raises:
584)         IndexError:
585)             The user made an invalid or empty selection, or requested an
586)             abort.
587) 
588)     """
589)     n = len(items)
590)     if heading:
591)         click.echo(click.style(heading, bold=True))
592)     for i, x in enumerate(items, start=1):
593)         click.echo(click.style(f'[{i}]', bold=True), nl=False)
594)         click.echo(' ', nl=False)
595)         click.echo(x)
596)     if n > 1:
597)         choices = click.Choice([''] + [str(i) for i in range(1, n + 1)])
598)         choice = click.prompt(
599)             f'Your selection? (1-{n}, leave empty to abort)',

600)             err=True,
601)             type=choices,
602)             show_choices=False,
603)             show_default=False,
604)             default='',
605)         )

606)         if not choice:

607)             raise IndexError(_EMPTY_SELECTION)

608)         return int(choice) - 1

609)     prompt_suffix = (
610)         ' ' if single_choice_prompt.endswith(tuple('?.!')) else ': '
611)     )

612)     try:

613)         click.confirm(
614)             single_choice_prompt,
615)             prompt_suffix=prompt_suffix,
616)             err=True,
617)             abort=True,
618)             default=False,
619)             show_default=False,
620)         )

621)     except click.Abort:
622)         raise IndexError(_EMPTY_SELECTION) from None
623)     return 0

624) 
625) 
626) def _select_ssh_key(

627)     conn: ssh_agent.SSHAgentClient | socket.socket | None = None, /

628) ) -> bytes | bytearray:
629)     """Interactively select an SSH key for passphrase derivation.
630) 
631)     Suitable SSH keys are queried from the running SSH agent (see

632)     [`derivepassphrase.ssh_agent.SSHAgentClient.list_keys`][]), then the
633)     user is prompted interactively (see [`click.prompt`][]) for
634)     a selection.

635) 
636)     Args:
637)         conn:
638)             An optional connection hint to the SSH agent; specifically,
639)             an SSH agent client, or a socket connected to an SSH agent.
640) 
641)             If an existing SSH agent client, then this client will be
642)             queried for the SSH keys, and otherwise left intact.
643) 
644)             If a socket, then a one-shot client will be constructed
645)             based on the socket to query the agent, and deconstructed
646)             afterwards.
647) 
648)             If neither are given, then the agent's socket location is
649)             looked up in the `SSH_AUTH_SOCK` environment variable, and
650)             used to construct/deconstruct a one-shot client, as in the
651)             previous case.
652) 
653)     Returns:
654)         The selected SSH key.
655) 
656)     Raises:

657)         KeyError:
658)             `conn` was `None`, and the `SSH_AUTH_SOCK` environment
659)             variable was not found.
660)         OSError:
661)             `conn` was a socket or `None`, and there was an error
662)             setting up a socket connection to the agent.

663)         IndexError:
664)             The user made an invalid or empty selection, or requested an
665)             abort.

666)         LookupError:

667)             No keys usable for passphrase derivation are loaded into the
668)             SSH agent.

669)         RuntimeError:
670)             There was an error communicating with the SSH agent.

671)         SSHAgentFailedError:
672)             The agent failed to supply a list of loaded keys.

673)     """
674)     suitable_keys = list(_get_suitable_ssh_keys(conn))
675)     key_listing: list[str] = []

676)     unstring_prefix = ssh_agent.SSHAgentClient.unstring_prefix

677)     for key, comment in suitable_keys:
678)         keytype = unstring_prefix(key)[0].decode('ASCII')
679)         key_str = base64.standard_b64encode(key).decode('ASCII')

680)         key_prefix = (
681)             key_str
682)             if len(key_str) < KEY_DISPLAY_LENGTH + len('...')
683)             else key_str[:KEY_DISPLAY_LENGTH] + '...'
684)         )

685)         comment_str = comment.decode('UTF-8', errors='replace')
686)         key_listing.append(f'{keytype} {key_prefix} {comment_str}')
687)     choice = _prompt_for_selection(

688)         key_listing,
689)         heading='Suitable SSH keys:',
690)         single_choice_prompt='Use this key?',
691)     )

692)     return suitable_keys[choice].key
693) 
694) 
695) def _prompt_for_passphrase() -> str:
696)     """Interactively prompt for the passphrase.
697) 
698)     Calls [`click.prompt`][] internally.  Moved into a separate function
699)     mainly for testing/mocking purposes.
700) 
701)     Returns:
702)         The user input.
703) 
704)     """

705)     return cast(
706)         str,
707)         click.prompt(
708)             'Passphrase',
709)             default='',
710)             hide_input=True,
711)             show_default=False,
712)             err=True,
713)         ),

714)     )

715) 
716) 

717) def _check_for_misleading_passphrase(
718)     key: tuple[str, ...],
719)     value: dict[str, Any],
720)     *,
721)     form: Literal['NFC', 'NFD', 'NFKC', 'NFKD'] = 'NFC',
722) ) -> None:
723)     def is_json_identifier(x: str) -> bool:
724)         return not x.startswith(tuple('0123456789')) and not any(
725)             c.lower() not in set('0123456789abcdefghijklmnopqrstuvwxyz_')
726)             for c in x
727)         )
728) 
729)     if 'phrase' in value:
730)         phrase = value['phrase']
731)         if not unicodedata.is_normalized(form, phrase):
732)             key_path = '.'.join(
733)                 x if is_json_identifier(x) else repr(x) for x in key
734)             )
735)             click.echo(
736)                 (
737)                     f'{PROG_NAME}: Warning: the {key_path} passphrase '
738)                     f'is not {form}-normalized. Make sure to double-check '
739)                     f'this is really the passphrase you want.'
740)                 ),
741)                 err=True,
742)             )
743) 
744) 

745) class OptionGroupOption(click.Option):

746)     """A [`click.Option`][] with an associated group name and group epilog.
747) 
748)     Used by [`derivepassphrase.cli.CommandWithHelpGroups`][] to print
749)     help sections.  Each subclass contains its own group name and
750)     epilog.
751) 
752)     Attributes:
753)         option_group_name:
754)             The name of the option group.  Used as a heading on the help
755)             text for options in this section.
756)         epilog:
757)             An epilog to print after listing the options in this
758)             section.
759) 
760)     """

761) 

762)     option_group_name: str = ''
763)     epilog: str = ''
764) 

765)     def __init__(self, *args: Any, **kwargs: Any) -> None:  # noqa: ANN401

766)         if self.__class__ == __class__:  # type: ignore[name-defined]

767)             raise NotImplementedError
768)         super().__init__(*args, **kwargs)

769) 

770) 
771) class CommandWithHelpGroups(click.Command):

772)     """A [`click.Command`][] with support for help/option groups.
773) 
774)     Inspired by [a comment on `pallets/click#373`][CLICK_ISSUE], and
775)     further modified to support group epilogs.
776) 
777)     [CLICK_ISSUE]: https://github.com/pallets/click/issues/373#issuecomment-515293746
778) 
779)     """
780) 

781)     def format_options(

782)         self,
783)         ctx: click.Context,
784)         formatter: click.HelpFormatter,

785)     ) -> None:

786)         r"""Format options on the help listing, grouped into sections.
787) 

788)         This is a callback for [`click.Command.get_help`][] that
789)         implements the `--help` listing, by calling appropriate methods
790)         of the `formatter`.  We list all options (like the base
791)         implementation), but grouped into sections according to the
792)         concrete [`click.Option`][] subclass being used.  If the option
793)         is an instance of some subclass `X` of
794)         [`derivepassphrase.cli.OptionGroupOption`][], then the section
795)         heading and the epilog are taken from `X.option_group_name` and
796)         `X.epilog`; otherwise, the section heading is "Options" (or
797)         "Other options" if there are other option groups) and the epilog
798)         is empty.

799) 
800)         Args:
801)             ctx:
802)                 The click context.
803)             formatter:
804)                 The formatter for the `--help` listing.
805) 
806)         """

807)         help_records: dict[str, list[tuple[str, str]]] = {}
808)         epilogs: dict[str, str] = {}
809)         params = self.params[:]

810)         if (  # pragma: no branch
811)             (help_opt := self.get_help_option(ctx)) is not None
812)             and help_opt not in params
813)         ):

814)             params.append(help_opt)
815)         for param in params:
816)             rec = param.get_help_record(ctx)
817)             if rec is not None:
818)                 if isinstance(param, OptionGroupOption):
819)                     group_name = param.option_group_name
820)                     epilogs.setdefault(group_name, param.epilog)
821)                 else:
822)                     group_name = ''
823)                 help_records.setdefault(group_name, []).append(rec)
824)         default_group = help_records.pop('')

825)         default_group_name = (
826)             'Other Options' if len(default_group) > 1 else 'Options'
827)         )

828)         help_records[default_group_name] = default_group
829)         for group_name, records in help_records.items():
830)             with formatter.section(group_name):
831)                 formatter.write_dl(records)
832)             epilog = inspect.cleandoc(epilogs.get(group_name, ''))
833)             if epilog:
834)                 formatter.write_paragraph()
835)                 with formatter.indentation():
836)                     formatter.write_text(epilog)
837) 

838) 

839) # Concrete option groups used by this command-line interface.
840) class PasswordGenerationOption(OptionGroupOption):

841)     """Password generation options for the CLI."""

842) 

843)     option_group_name = 'Password generation'

844)     epilog = """

845)         Use NUMBER=0, e.g. "--symbol 0", to exclude a character type
846)         from the output.

847)     """

848) 

849) 
850) class ConfigurationOption(OptionGroupOption):

851)     """Configuration options for the CLI."""

852) 

853)     option_group_name = 'Configuration'

854)     epilog = """

855)         Use $VISUAL or $EDITOR to configure the spawned editor.

856)     """

857) 

858) 
859) class StorageManagementOption(OptionGroupOption):

860)     """Storage management options for the CLI."""

861) 

862)     option_group_name = 'Storage management'

863)     epilog = """

864)         Using "-" as PATH for standard input/standard output is
865)         supported.

866)     """
867) 

868) 

869) def _validate_occurrence_constraint(

870)     ctx: click.Context,
871)     param: click.Parameter,

872)     value: Any,  # noqa: ANN401

873) ) -> int | None:

874)     """Check that the occurrence constraint is valid (int, 0 or larger).
875) 
876)     Args:
877)         ctx: The `click` context.
878)         param: The current command-line parameter.
879)         value: The parameter value to be checked.
880) 
881)     Returns:
882)         The parsed parameter value.
883) 
884)     Raises:
885)         click.BadParameter: The parameter value is invalid.
886) 
887)     """

888)     del ctx  # Unused.

889)     del param  # Unused.

890)     if value is None:
891)         return value
892)     if isinstance(value, int):
893)         int_value = value
894)     else:
895)         try:
896)             int_value = int(value, 10)
897)         except ValueError as e:

898)             msg = 'not an integer'
899)             raise click.BadParameter(msg) from e

900)     if int_value < 0:

901)         msg = 'not a non-negative integer'
902)         raise click.BadParameter(msg)

903)     return int_value
904) 

905) 
906) def _validate_length(

907)     ctx: click.Context,
908)     param: click.Parameter,

909)     value: Any,  # noqa: ANN401

910) ) -> int | None:

911)     """Check that the length is valid (int, 1 or larger).
912) 
913)     Args:
914)         ctx: The `click` context.
915)         param: The current command-line parameter.
916)         value: The parameter value to be checked.
917) 
918)     Returns:
919)         The parsed parameter value.
920) 
921)     Raises:
922)         click.BadParameter: The parameter value is invalid.
923) 
924)     """

925)     del ctx  # Unused.

926)     del param  # Unused.

927)     if value is None:
928)         return value
929)     if isinstance(value, int):
930)         int_value = value
931)     else:
932)         try:
933)             int_value = int(value, 10)
934)         except ValueError as e:

935)             msg = 'not an integer'
936)             raise click.BadParameter(msg) from e

937)     if int_value < 1:

938)         msg = 'not a positive integer'
939)         raise click.BadParameter(msg)

940)     return int_value
941) 

942) 
943) DEFAULT_NOTES_TEMPLATE = """\

944) # Enter notes below the line with the cut mark (ASCII scissors and
945) # dashes).  Lines above the cut mark (such as this one) will be ignored.
946) #
947) # If you wish to clear the notes, leave everything beyond the cut mark
948) # blank.  However, if you leave the *entire* file blank, also removing
949) # the cut mark, then the edit is aborted, and the old notes contents are
950) # retained.
951) #
952) # - - - - - >8 - - - - - >8 - - - - - >8 - - - - - >8 - - - - -

953) """

954) DEFAULT_NOTES_MARKER = '# - - - - - >8 - - - - -'
955) 
956) 

957) @click.command(

958)     # 'vault',
959)     # help="derivation scheme compatible with James Coglan's vault(1)",

960)     context_settings={'help_option_names': ['-h', '--help']},

961)     cls=CommandWithHelpGroups,

962)     epilog=r"""

963)         WARNING: There is NO WAY to retrieve the generated passphrases
964)         if the master passphrase, the SSH key, or the exact passphrase
965)         settings are lost, short of trying out all possible
966)         combinations.  You are STRONGLY advised to keep independent
967)         backups of the settings and the SSH key, if any.

968) 
969)         The configuration is NOT encrypted, and you are STRONGLY
970)         discouraged from using a stored passphrase.

971)     """,
972) )
973) @click.option(
974)     '-p',
975)     '--phrase',
976)     'use_phrase',
977)     is_flag=True,
978)     help='prompts you for your passphrase',
979)     cls=PasswordGenerationOption,
980) )
981) @click.option(
982)     '-k',
983)     '--key',
984)     'use_key',
985)     is_flag=True,
986)     help='uses your SSH private key to generate passwords',
987)     cls=PasswordGenerationOption,
988) )
989) @click.option(
990)     '-l',
991)     '--length',
992)     metavar='NUMBER',
993)     callback=_validate_length,
994)     help='emits password of length NUMBER',
995)     cls=PasswordGenerationOption,
996) )
997) @click.option(
998)     '-r',
999)     '--repeat',
1000)     metavar='NUMBER',
1001)     callback=_validate_occurrence_constraint,
1002)     help='allows maximum of NUMBER repeated adjacent chars',
1003)     cls=PasswordGenerationOption,
1004) )
1005) @click.option(
1006)     '--lower',
1007)     metavar='NUMBER',
1008)     callback=_validate_occurrence_constraint,
1009)     help='includes at least NUMBER lowercase letters',
1010)     cls=PasswordGenerationOption,
1011) )
1012) @click.option(
1013)     '--upper',
1014)     metavar='NUMBER',
1015)     callback=_validate_occurrence_constraint,
1016)     help='includes at least NUMBER uppercase letters',
1017)     cls=PasswordGenerationOption,
1018) )
1019) @click.option(
1020)     '--number',
1021)     metavar='NUMBER',
1022)     callback=_validate_occurrence_constraint,
1023)     help='includes at least NUMBER digits',
1024)     cls=PasswordGenerationOption,
1025) )
1026) @click.option(
1027)     '--space',
1028)     metavar='NUMBER',
1029)     callback=_validate_occurrence_constraint,
1030)     help='includes at least NUMBER spaces',
1031)     cls=PasswordGenerationOption,
1032) )
1033) @click.option(
1034)     '--dash',
1035)     metavar='NUMBER',
1036)     callback=_validate_occurrence_constraint,
1037)     help='includes at least NUMBER "-" or "_"',
1038)     cls=PasswordGenerationOption,
1039) )
1040) @click.option(
1041)     '--symbol',
1042)     metavar='NUMBER',
1043)     callback=_validate_occurrence_constraint,
1044)     help='includes at least NUMBER symbol chars',
1045)     cls=PasswordGenerationOption,
1046) )
1047) @click.option(
1048)     '-n',
1049)     '--notes',
1050)     'edit_notes',
1051)     is_flag=True,
1052)     help='spawn an editor to edit notes for SERVICE',
1053)     cls=ConfigurationOption,
1054) )
1055) @click.option(
1056)     '-c',
1057)     '--config',
1058)     'store_config_only',
1059)     is_flag=True,
1060)     help='saves the given settings for SERVICE or global',
1061)     cls=ConfigurationOption,
1062) )
1063) @click.option(
1064)     '-x',
1065)     '--delete',
1066)     'delete_service_settings',
1067)     is_flag=True,
1068)     help='deletes settings for SERVICE',
1069)     cls=ConfigurationOption,
1070) )
1071) @click.option(
1072)     '--delete-globals',
1073)     is_flag=True,
1074)     help='deletes the global shared settings',
1075)     cls=ConfigurationOption,
1076) )
1077) @click.option(
1078)     '-X',
1079)     '--clear',
1080)     'clear_all_settings',
1081)     is_flag=True,
1082)     help='deletes all settings',
1083)     cls=ConfigurationOption,
1084) )
1085) @click.option(
1086)     '-e',
1087)     '--export',
1088)     'export_settings',
1089)     metavar='PATH',
1090)     help='export all saved settings into file PATH',
1091)     cls=StorageManagementOption,
1092) )
1093) @click.option(
1094)     '-i',
1095)     '--import',
1096)     'import_settings',
1097)     metavar='PATH',
1098)     help='import saved settings from file PATH',
1099)     cls=StorageManagementOption,

1100) )

1101) @click.version_option(version=dpp.__version__, prog_name=PROG_NAME)

1102) @click.argument('service', required=False)
1103) @click.pass_context

1104) def derivepassphrase_vault(  # noqa: C901,PLR0912,PLR0913,PLR0914,PLR0915

1105)     ctx: click.Context,
1106)     /,
1107)     *,

1108)     service: str | None = None,
1109)     use_phrase: bool = False,
1110)     use_key: bool = False,
1111)     length: int | None = None,
1112)     repeat: int | None = None,
1113)     lower: int | None = None,
1114)     upper: int | None = None,
1115)     number: int | None = None,
1116)     space: int | None = None,
1117)     dash: int | None = None,
1118)     symbol: int | None = None,
1119)     edit_notes: bool = False,
1120)     store_config_only: bool = False,
1121)     delete_service_settings: bool = False,
1122)     delete_globals: bool = False,
1123)     clear_all_settings: bool = False,
1124)     export_settings: TextIO | pathlib.Path | os.PathLike[str] | None = None,
1125)     import_settings: TextIO | pathlib.Path | os.PathLike[str] | None = None,

1126) ) -> None:

1127)     """Derive a passphrase using the vault(1) derivation scheme.

1128) 

1129)     Using a master passphrase or a master SSH key, derive a passphrase
1130)     for SERVICE, subject to length, character and character repetition
1131)     constraints.  The derivation is cryptographically strong, meaning
1132)     that even if a single passphrase is compromised, guessing the master
1133)     passphrase or a different service's passphrase is computationally
1134)     infeasible.  The derivation is also deterministic, given the same
1135)     inputs, thus the resulting passphrase need not be stored explicitly.
1136)     The service name and constraints themselves also need not be kept
1137)     secret; the latter are usually stored in a world-readable file.

1138) 
1139)     If operating on global settings, or importing/exporting settings,
1140)     then SERVICE must be omitted.  Otherwise it is required.\f
1141) 
1142)     This is a [`click`][CLICK]-powered command-line interface function,
1143)     and not intended for programmatic use.  Call with arguments

1144)     `['--help']` to see full documentation of the interface.  (See also
1145)     [`click.testing.CliRunner`][] for controlled, programmatic
1146)     invocation.)

1147) 
1148)     [CLICK]: https://click.palletsprojects.com/
1149) 
1150)     Parameters:
1151)         ctx (click.Context):
1152)             The `click` context.
1153) 
1154)     Other Parameters:

1155)         service:

1156)             A service name.  Required, unless operating on global
1157)             settings or importing/exporting settings.

1158)         use_phrase:

1159)             Command-line argument `-p`/`--phrase`.  If given, query the
1160)             user for a passphrase instead of an SSH key.

1161)         use_key:

1162)             Command-line argument `-k`/`--key`.  If given, query the
1163)             user for an SSH key instead of a passphrase.

1164)         length:

1165)             Command-line argument `-l`/`--length`.  Override the default
1166)             length of the generated passphrase.

1167)         repeat:

1168)             Command-line argument `-r`/`--repeat`.  Override the default
1169)             repetition limit if positive, or disable the repetition
1170)             limit if 0.

1171)         lower:

1172)             Command-line argument `--lower`.  Require a given amount of
1173)             ASCII lowercase characters if positive, else forbid ASCII
1174)             lowercase characters if 0.

1175)         upper:

1176)             Command-line argument `--upper`.  Same as `lower`, but for
1177)             ASCII uppercase characters.

1178)         number:

1179)             Command-line argument `--number`.  Same as `lower`, but for
1180)             ASCII digits.

1181)         space:

1182)             Command-line argument `--space`.  Same as `lower`, but for

1183)             the space character.

1184)         dash:

1185)             Command-line argument `--dash`.  Same as `lower`, but for

1186)             the hyphen-minus and underscore characters.

1187)         symbol:

1188)             Command-line argument `--symbol`.  Same as `lower`, but for

1189)             all other ASCII printable characters (except backquote).

1190)         edit_notes:

1191)             Command-line argument `-n`/`--notes`.  If given, spawn an
1192)             editor to edit notes for `service`.

1193)         store_config_only:

1194)             Command-line argument `-c`/`--config`.  If given, saves the
1195)             other given settings (`--key`, ..., `--symbol`) to the
1196)             configuration file, either specifically for `service` or as
1197)             global settings.

1198)         delete_service_settings:

1199)             Command-line argument `-x`/`--delete`.  If given, removes
1200)             the settings for `service` from the configuration file.

1201)         delete_globals:

1202)             Command-line argument `--delete-globals`.  If given, removes
1203)             the global settings from the configuration file.

1204)         clear_all_settings:

1205)             Command-line argument `-X`/`--clear`.  If given, removes all
1206)             settings from the configuration file.

1207)         export_settings:
1208)             Command-line argument `-e`/`--export`.  If a file object,
1209)             then it must be open for writing and accept `str` inputs.
1210)             Otherwise, a filename to open for writing.  Using `-` for
1211)             standard output is supported.
1212)         import_settings:
1213)             Command-line argument `-i`/`--import`.  If a file object, it
1214)             must be open for reading and yield `str` values.  Otherwise,
1215)             a filename to open for reading.  Using `-` for standard
1216)             input is supported.

1217) 

1218)     """  # noqa: D301

1219)     options_in_group: dict[type[click.Option], list[click.Option]] = {}
1220)     params_by_str: dict[str, click.Parameter] = {}

1221)     for param in ctx.command.params:
1222)         if isinstance(param, click.Option):
1223)             group: type[click.Option]

1224)             match param:
1225)                 case PasswordGenerationOption():
1226)                     group = PasswordGenerationOption
1227)                 case ConfigurationOption():
1228)                     group = ConfigurationOption
1229)                 case StorageManagementOption():
1230)                     group = StorageManagementOption
1231)                 case OptionGroupOption():

1232)                     raise AssertionError(  # noqa: DOC501,TRY003

1233)                         f'Unknown option group for {param!r}'  # noqa: EM102
1234)                     )

1235)                 case _:
1236)                     group = click.Option
1237)             options_in_group.setdefault(group, []).append(param)
1238)         params_by_str[param.human_readable_name] = param
1239)         for name in param.opts + param.secondary_opts:
1240)             params_by_str[name] = param
1241) 

1242)     def is_param_set(param: click.Parameter) -> bool:

1243)         return bool(ctx.params.get(param.human_readable_name))
1244) 

1245)     def check_incompatible_options(

1246)         param: click.Parameter | str,
1247)         *incompatible: click.Parameter | str,

1248)     ) -> None:

1249)         if isinstance(param, str):
1250)             param = params_by_str[param]
1251)         assert isinstance(param, click.Parameter)
1252)         if not is_param_set(param):

1253)             return
1254)         for other in incompatible:

1255)             if isinstance(other, str):

1256)                 other = params_by_str[other]  # noqa: PLW2901

1257)             assert isinstance(other, click.Parameter)
1258)             if other != param and is_param_set(other):
1259)                 opt_str = param.opts[0]
1260)                 other_str = other.opts[0]
1261)                 raise click.BadOptionUsage(

1262)                     opt_str, f'mutually exclusive with {other_str}', ctx=ctx
1263)                 )

1264) 

1265)     def err(msg: str) -> NoReturn:
1266)         click.echo(f'{PROG_NAME}: {msg}', err=True)
1267)         ctx.exit(1)
1268) 

1269)     def get_config() -> _types.VaultConfig:

1270)         try:
1271)             return _load_config()
1272)         except FileNotFoundError:

1273)             try:
1274)                 backup_config, exc = _migrate_and_load_old_config()
1275)             except FileNotFoundError:
1276)                 return {'services': {}}
1277)             old_name = os.path.basename(_config_filename())
1278)             new_name = os.path.basename(_config_filename(subsystem='vault'))
1279)             click.echo(
1280)                 (
1281)                     f'{PROG_NAME}: Using deprecated v0.1-style config file '
1282)                     f'{old_name!r}, instead of v0.2-style {new_name!r}.  '
1283)                     f'Support for v0.1-style config filenames will be '
1284)                     f'removed in v1.0.'
1285)                 ),
1286)                 err=True,
1287)             )
1288)             if isinstance(exc, OSError):
1289)                 click.echo(
1290)                     (
1291)                         f'{PROG_NAME}: Warning: Failed to migrate to '
1292)                         f'{new_name!r}: {exc.strerror}: {exc.filename!r}'
1293)                     ),
1294)                     err=True,
1295)                 )
1296)             else:
1297)                 click.echo(
1298)                     f'{PROG_NAME}: Successfully migrated to {new_name!r}.',
1299)                     err=True,
1300)                 )
1301)             return backup_config

1302)         except OSError as e:
1303)             err(f'Cannot load config: {e.strerror}: {e.filename!r}')

1304)         except Exception as e:  # noqa: BLE001

1305)             err(f'Cannot load config: {e}')
1306) 
1307)     def put_config(config: _types.VaultConfig, /) -> None:
1308)         try:
1309)             _save_config(config)

1310)         except OSError as exc:
1311)             err(f'Cannot store config: {exc.strerror}: {exc.filename!r}')

1312)         except Exception as exc:  # noqa: BLE001
1313)             err(f'Cannot store config: {exc}')

1314) 

1315)     configuration: _types.VaultConfig

1316) 
1317)     check_incompatible_options('--phrase', '--key')

1318)     for group in (ConfigurationOption, StorageManagementOption):

1319)         for opt in options_in_group[group]:
1320)             if opt != params_by_str['--config']:
1321)                 check_incompatible_options(

1322)                     opt, *options_in_group[PasswordGenerationOption]
1323)                 )

1324) 

1325)     for group in (ConfigurationOption, StorageManagementOption):

1326)         for opt in options_in_group[group]:
1327)             check_incompatible_options(

1328)                 opt,
1329)                 *options_in_group[ConfigurationOption],
1330)                 *options_in_group[StorageManagementOption],
1331)             )
1332)     sv_options = options_in_group[PasswordGenerationOption] + [
1333)         params_by_str['--notes'],
1334)         params_by_str['--delete'],
1335)     ]

1336)     sv_options.remove(params_by_str['--key'])
1337)     sv_options.remove(params_by_str['--phrase'])
1338)     for param in sv_options:
1339)         if is_param_set(param) and not service:
1340)             opt_str = param.opts[0]

1341)             msg = f'{opt_str} requires a SERVICE'

1342)             raise click.UsageError(msg)  # noqa: DOC501

1343)     for param in [params_by_str['--key'], params_by_str['--phrase']]:

1344)         if is_param_set(param) and not (
1345)             service or is_param_set(params_by_str['--config'])

1346)         ):
1347)             opt_str = param.opts[0]

1348)             msg = f'{opt_str} requires a SERVICE or --config'
1349)             raise click.UsageError(msg)

1350)     no_sv_options = [
1351)         params_by_str['--delete-globals'],
1352)         params_by_str['--clear'],
1353)         *options_in_group[StorageManagementOption],
1354)     ]

1355)     for param in no_sv_options:
1356)         if is_param_set(param) and service:
1357)             opt_str = param.opts[0]

1358)             msg = f'{opt_str} does not take a SERVICE argument'
1359)             raise click.UsageError(msg)

1360) 
1361)     if edit_notes:
1362)         assert service is not None
1363)         configuration = get_config()

1364)         text = DEFAULT_NOTES_TEMPLATE + configuration['services'].get(

1365)             service, cast(_types.VaultConfigServicesSettings, {})

1366)         ).get('notes', '')

1367)         notes_value = click.edit(text=text)
1368)         if notes_value is not None:

1369)             notes_lines = collections.deque(notes_value.splitlines(True))  # noqa: FBT003

1370)             while notes_lines:
1371)                 line = notes_lines.popleft()
1372)                 if line.startswith(DEFAULT_NOTES_MARKER):
1373)                     notes_value = ''.join(notes_lines)
1374)                     break
1375)             else:
1376)                 if not notes_value.strip():

1377)                     err('Not saving new notes: user aborted request')

1378)             configuration['services'].setdefault(service, {})['notes'] = (

1379)                 notes_value.strip('\n')
1380)             )

1381)             put_config(configuration)

1382)     elif delete_service_settings:
1383)         assert service is not None
1384)         configuration = get_config()
1385)         if service in configuration['services']:
1386)             del configuration['services'][service]

1387)             put_config(configuration)

1388)     elif delete_globals:
1389)         configuration = get_config()
1390)         if 'global' in configuration:
1391)             del configuration['global']

1392)             put_config(configuration)

1393)     elif clear_all_settings:

1394)         put_config({'services': {}})

1395)     elif import_settings:
1396)         try:

1397)             # TODO(the-13th-letter): keep track of auto-close; try
1398)             # os.dup if feasible

1399)             infile = (
1400)                 cast(TextIO, import_settings)
1401)                 if hasattr(import_settings, 'close')
1402)                 else click.open_file(os.fspath(import_settings), 'rt')
1403)             )

1404)             with infile:
1405)                 maybe_config = json.load(infile)
1406)         except json.JSONDecodeError as e:

1407)             err(f'Cannot load config: cannot decode JSON: {e}')

1408)         except OSError as e:

1409)             err(f'Cannot load config: {e.strerror}: {e.filename!r}')

1410)         if _types.is_vault_config(maybe_config):

1411)             form = cast(
1412)                 Literal['NFC', 'NFD', 'NFKC', 'NFKD'],
1413)                 maybe_config.get('global', {}).get(
1414)                     'unicode_normalization_form', 'NFC'
1415)                 ),
1416)             )
1417)             assert form in {'NFC', 'NFD', 'NFKC', 'NFKD'}
1418)             _check_for_misleading_passphrase(
1419)                 ('global',),
1420)                 cast(dict[str, Any], maybe_config.get('global', {})),
1421)                 form=form,
1422)             )
1423)             for key, value in maybe_config['services'].items():
1424)                 _check_for_misleading_passphrase(
1425)                     ('services', key),
1426)                     cast(dict[str, Any], value),
1427)                     form=form,
1428)                 )

1429)             put_config(maybe_config)

1430)         else:

1431)             err(f'Cannot load config: {_INVALID_VAULT_CONFIG}')

1432)     elif export_settings:
1433)         configuration = get_config()
1434)         try:

1435)             # TODO(the-13th-letter): keep track of auto-close; try
1436)             # os.dup if feasible

1437)             outfile = (
1438)                 cast(TextIO, export_settings)
1439)                 if hasattr(export_settings, 'close')
1440)                 else click.open_file(os.fspath(export_settings), 'wt')
1441)             )

1442)             with outfile:
1443)                 json.dump(configuration, outfile)
1444)         except OSError as e:

1445)             err(f'Cannot store config: {e.strerror}: {e.filename!r}')

1446)     else:
1447)         configuration = get_config()
1448)         # This block could be type checked more stringently, but this
1449)         # would probably involve a lot of code repetition.  Since we
1450)         # have a type guarding function anyway, assert that we didn't
1451)         # make any mistakes at the end instead.
1452)         global_keys = {'key', 'phrase'}

1453)         service_keys = {
1454)             'key',
1455)             'phrase',
1456)             'length',
1457)             'repeat',
1458)             'lower',
1459)             'upper',
1460)             'number',
1461)             'space',
1462)             'dash',
1463)             'symbol',
1464)         }

1465)         settings: collections.ChainMap[str, Any] = collections.ChainMap(

1466)             {
1467)                 k: v
1468)                 for k, v in locals().items()
1469)                 if k in service_keys and v is not None
1470)             },
1471)             cast(
1472)                 dict[str, Any],
1473)                 configuration['services'].get(service or '', {}),
1474)             ),

1475)             {},

1476)             cast(dict[str, Any], configuration.get('global', {})),

1477)         )
1478)         if use_key:
1479)             try:

1480)                 key = base64.standard_b64encode(_select_ssh_key()).decode(
1481)                     'ASCII'
1482)                 )

1483)             except IndexError:

1484)                 err('No valid SSH key selected')

1485)             except KeyError:

1486)                 err('Cannot find running SSH agent; check SSH_AUTH_SOCK')

1487)             except OSError as e:
1488)                 err(
1489)                     f'Cannot connect to SSH agent: {e.strerror}: '
1490)                     f'{e.filename!r}'
1491)                 )

1492)             except (
1493)                 LookupError,
1494)                 RuntimeError,
1495)                 ssh_agent.SSHAgentFailedError,
1496)             ) as e:

1497)                 err(str(e))

1498)         elif use_phrase:
1499)             maybe_phrase = _prompt_for_passphrase()
1500)             if not maybe_phrase:

1501)                 err('No passphrase given')

1502)             else:
1503)                 phrase = maybe_phrase
1504)         if store_config_only:
1505)             view: collections.ChainMap[str, Any]

1506)             view = (
1507)                 collections.ChainMap(*settings.maps[:2])
1508)                 if service
1509)                 else settings.parents.parents
1510)             )

1511)             if use_key:
1512)                 view['key'] = key
1513)                 for m in view.maps:
1514)                     m.pop('phrase', '')
1515)             elif use_phrase:

1516)                 _check_for_misleading_passphrase(
1517)                     ('services', service) if service else ('global',),
1518)                     {'phrase': phrase},
1519)                 )

1520)                 view['phrase'] = phrase
1521)                 for m in view.maps:
1522)                     m.pop('key', '')

1523)             if not view.maps[0]:
1524)                 settings_type = 'service' if service else 'global'

1525)                 msg = (

1526)                     f'Cannot update {settings_type} settings without '

1527)                     f'actual settings'
1528)                 )

1529)                 raise click.UsageError(msg)

1530)             if service:

1531)                 configuration['services'].setdefault(service, {}).update(view)  # type: ignore[typeddict-item]

1532)             else:

1533)                 configuration.setdefault('global', {}).update(view)  # type: ignore[typeddict-item]

1534)             assert _types.is_vault_config(

1535)                 configuration

1536)             ), f'Invalid vault configuration: {configuration!r}'

1537)             put_config(configuration)

1538)         else:
1539)             if not service:

1540)                 msg = 'SERVICE is required'
1541)                 raise click.UsageError(msg)

1542)             kwargs: dict[str, Any] = {
1543)                 k: v
1544)                 for k, v in settings.items()
1545)                 if k in service_keys and v is not None
1546)             }
1547) 

1548)             def key_to_phrase(
1549)                 key: str | bytes | bytearray,
1550)             ) -> bytes | bytearray:

1551)                 return vault.Vault.phrase_from_key(

1552)                     base64.standard_b64decode(key)
1553)                 )
1554) 

1555)             if use_phrase:
1556)                 form = cast(
1557)                     Literal['NFC', 'NFD', 'NFKC', 'NFKD'],
1558)                     configuration.get('global', {}).get(
1559)                         'unicode_normalization_form', 'NFC'
1560)                     ),
1561)                 )
1562)                 assert form in {'NFC', 'NFD', 'NFKC', 'NFKD'}
1563)                 _check_for_misleading_passphrase(
1564)                     ('interactive',), {'phrase': phrase}, form=form
1565)                 )
1566) 

1567)             # If either --key or --phrase are given, use that setting.
1568)             # Otherwise, if both key and phrase are set in the config,
1569)             # one must be global (ignore it) and one must be
1570)             # service-specific (use that one). Otherwise, if only one of
1571)             # key and phrase is set in the config, use that one.  In all
1572)             # these above cases, set the phrase via

1573)             # derivepassphrase.vault.Vault.phrase_from_key if a key is

1574)             # given. Finally, if nothing is set, error out.
1575)             if use_key or use_phrase:

1576)                 kwargs['phrase'] = key_to_phrase(key) if use_key else phrase

1577)             elif kwargs.get('phrase') and kwargs.get('key'):
1578)                 if any('key' in m for m in settings.maps[:2]):

1579)                     kwargs['phrase'] = key_to_phrase(kwargs['key'])

1580)             elif kwargs.get('key'):

1581)                 kwargs['phrase'] = key_to_phrase(kwargs['key'])

1582)             elif kwargs.get('phrase'):
1583)                 pass
1584)             else:

1585)                 msg = (

1586)                     'No passphrase or key given on command-line '

1587)                     'or in configuration'
1588)                 )

1589)                 raise click.UsageError(msg)

1590)             kwargs.pop('key', '')

1591)             result = vault.Vault(**kwargs).generate(service)

1592)             click.echo(result.decode('ASCII'))