derivepassphrase.git

@@ -189,27 +189,30 @@ quote-style = 'single'

 [tool.ruff.lint]

 ignore = [

     # Suggested ignore by ruff when also using ruff to format.  We *do*

-    # check for E501, because this usually only happens when there is a text

-    # string that should be manually broken.

-    'W191', 'E111', 'E114', 'E117', 'D206', 'D300', 'Q000', 'Q001', 'Q002',

-    'Q003', 'COM812', 'COM819', 'ISC001', 'ISC002',

+    # check for E501, because this usually only happens when there is

+    # a text string that should be manually broken.

+    'W191', 'E111', 'E114', 'E117', 'D206', 'D300', 'Q000', 'Q001',

+    'Q002', 'Q003', 'COM812', 'COM819', 'ISC001', 'ISC002',

     # We use `assert` regularly to appease the type checker, and because

     # it is the right language tool for this job.

     'S101',

     # The formatter takes care of trailing commas and docstring code

     # automatically.

     'COM812', 'W505',

-    # We document transitive exceptions as well (if we feel they would be

-    # surprising to the user otherwise).

+    # We document transitive exceptions as well (if we feel they would

+    # be surprising to the user otherwise).

     'DOC502',

-    # We currently don't have issues for every TODO.  Forcing an issue also

-    # goes against the philosophy of TODOs as low-overhead markers for

-    # future work; see

+    # We currently don't have issues for every TODO.  Forcing an issue

+    # also goes against the philosophy of TODOs as low-overhead markers

+    # for future work; see

     # https://gist.github.com/dmnd/ed5d8ef8de2e4cfea174bd5dafcda382 .

     'TD003',

-    # We somewhat regularly use loops where each iteration needs a separate

-    # try-except block.

+    # We somewhat regularly use loops where each iteration needs

+    # a separate try-except block.

     'PERF203',

+    # We do not currently use pathlib.  The PTH rules are unselected,

+    # but FURB includes several pathlib-related rules.

+    'FURB101', 'FURB103',

     # We catch type-ignore comments without specific code via the mypy

     # configuration, not via ruff.

     'PGH003',

@@ -226,13 +229,13 @@ select = [

     'INT', 'ARG',

     # We currently do not use pathlib. Disable 'PTH'.

     'TD',

-    # We use TODOs and FIXMEs as notes for later, and don't want the linter

-    # to nag about every occurrence.  Disable 'FIX'.

+    # We use TODOs and FIXMEs as notes for later, and don't want the

+    # linter to nag about every occurrence.  Disable 'FIX'.

     #

-    # The "eradicate" rule is prone to a lot of false positives, and it is

-    # unclear to me, and probably confusing to read, where to apply a noqa

-    # marker.  Instead, disable 'ERA', and if necessary, specify it on the

-    # command-line.

+    # The "eradicate" rule is prone to a lot of false positives, and it

+    # is unclear to me, and probably confusing to read, where to apply

+    # a noqa marker.  Instead, disable 'ERA', and if necessary, specify

+    # it on the command-line.

     'PD', 'PGH', 'PL', 'TRY', 'FLY', 'NPY', 'FAST',

     'AIR', 'PERF', 'FURB', 'DOC', 'RUF',

 ]

@@ -251,8 +254,9 @@ select = [

   'PLC1901',

   # Suggested by hatch, assumingly because tests may use "magic values".

   'PLR2004',

-  # Suggested by hatch, because tests are typically organized as classes and

-  # instance methods but may not really be using the `self` argument.

+  # Suggested by hatch, because tests are typically organized as classes

+  # and instance methods but may not really be using the `self`

+  # argument.

   'PLR6301',

   # Suggested by hatch, because these warnings may be precisely what the

   # tests are supposed to test.

@@ -274,8 +278,8 @@ select = [

   # Importing this from the tests directory would then automatically

   # trigger `PLC2701`.

   'PLC2701',

-  # Too many public methods/arguments/returns/branches/locals doesn't really

-  # apply here.

+  # Too many public methods/arguments/returns/branches/locals doesn't

+  # really apply here.

   'PLR0904', 'PLR0911', 'PLR0912', 'PLR0913', 'PLR0914', 'PLR0915',

   'PLR0916', 'PLR0917',

   # To fully test the `derivepassphrase.cli` module (and a couple other

@@ -2,7 +2,7 @@

 #

 # SPDX-License-Identifier: MIT

-"""Work-alike of vault(1) – a deterministic, stateless password manager"""  # noqa: RUF002

+"""Work-alike of vault(1) – a deterministic, stateless password manager"""  # noqa: D415,RUF002

 __author__ = 'Marco Ricci <m@the13thletter.info>'

 __version__ = '0.1.3'

@@ -114,7 +114,7 @@ class VaultConfig(TypedDict, _VaultConfig, total=False):

     services: Required[dict[str, VaultConfigServicesSettings]]

-def is_vault_config(obj: Any) -> TypeGuard[VaultConfig]:

+def is_vault_config(obj: Any) -> TypeGuard[VaultConfig]:  # noqa: ANN401,C901,PLR0911,PLR0912

     """Check if `obj` is a valid vault config, according to typing.

     Args:

@@ -123,7 +123,7 @@ def _save_config(config: _types.VaultConfig, /) -> None:

         os.makedirs(filedir, exist_ok=False)

     except FileExistsError:

         if not os.path.isdir(filedir):

-            raise

+            raise  # noqa: DOC501

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

         json.dump(config, fileobj)

@@ -186,7 +186,7 @@ def _get_suitable_ssh_keys(

         case _:  # pragma: no cover

             assert_never(conn)

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

-            raise TypeError(msg)

+            raise TypeError(msg)  # noqa: DOC501

     with client_context:

         try:

             all_key_comment_pairs = list(client.list_keys())

@@ -215,6 +215,8 @@ def _prompt_for_selection(

     instead, and return the correct index.

     Args:

+        items:

+            The list of items to choose from.

         heading:

             A heading for the list of items, to print immediately

             before.  Defaults to a reasonable standard heading.  If

@@ -408,7 +410,7 @@ class OptionGroupOption(click.Option):

     option_group_name: str = ''

     epilog: str = ''

-    def __init__(self, *args: Any, **kwargs: Any) -> None:

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

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

             raise NotImplementedError

         super().__init__(*args, **kwargs)

@@ -449,10 +451,6 @@ class CommandWithHelpGroups(click.Command):

             formatter:

                 The formatter for the `--help` listing.

-        Returns:

-            Nothing.  Output is generated by calling appropriate methods

-            on `formatter` instead.

-

         """

         help_records: dict[str, list[tuple[str, str]]] = {}

         epilogs: dict[str, str] = {}

@@ -519,9 +517,22 @@ class StorageManagementOption(OptionGroupOption):

 def _validate_occurrence_constraint(

     ctx: click.Context,

     param: click.Parameter,

-    value: Any,

+    value: Any,  # noqa: ANN401

 ) -> int | None:

-    """Check that the occurrence constraint is valid (int, 0 or larger)."""

+    """Check that the occurrence constraint is valid (int, 0 or larger).

+

+    Args:

+        ctx: The `click` context.

+        param: The current command-line parameter.

+        value: The parameter value to be checked.

+

+    Returns:

+        The parsed parameter value.

+

+    Raises:

+        click.BadParameter: The parameter value is invalid.

+

+    """

     del ctx  # Unused.

     del param  # Unused.

     if value is None:

@@ -543,9 +554,22 @@ def _validate_occurrence_constraint(

 def _validate_length(

     ctx: click.Context,

     param: click.Parameter,

-    value: Any,

+    value: Any,  # noqa: ANN401

 ) -> int | None:

-    """Check that the length is valid (int, 1 or larger)."""

+    """Check that the length is valid (int, 1 or larger).

+

+    Args:

+        ctx: The `click` context.

+        param: The current command-line parameter.

+        value: The parameter value to be checked.

+

+    Returns:

+        The parsed parameter value.

+

+    Raises:

+        click.BadParameter: The parameter value is invalid.

+

+    """

     del ctx  # Unused.

     del param  # Unused.

     if value is None:

@@ -729,7 +753,7 @@ DEFAULT_NOTES_MARKER = '# - - - - - >8 - - - - -'

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

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

 @click.pass_context

-def derivepassphrase(

+def derivepassphrase(  # noqa: C901,PLR0912,PLR0913,PLR0914,PLR0915

     ctx: click.Context,

     /,

     *,

@@ -807,13 +831,13 @@ def derivepassphrase(

             Command-line argument `--number`.  Same as `lower`, but for

             ASCII digits.

         space:

-            Command-line argument `--number`.  Same as `lower`, but for

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

             the space character.

         dash:

-            Command-line argument `--number`.  Same as `lower`, but for

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

             the hyphen-minus and underscore characters.

         symbol:

-            Command-line argument `--number`.  Same as `lower`, but for

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

             all other ASCII printable characters (except backquote).

         edit_notes:

             Command-line argument `-n`/`--notes`.  If given, spawn an

@@ -843,8 +867,7 @@ def derivepassphrase(

             a filename to open for reading.  Using `-` for standard

             input is supported.

-    """

-

+    """  # noqa: D301

     options_in_group: dict[type[click.Option], list[click.Option]] = {}

     params_by_str: dict[str, click.Parameter] = {}

     for param in ctx.command.params:

@@ -858,7 +881,7 @@ def derivepassphrase(

                 case StorageManagementOption():

                     group = StorageManagementOption

                 case OptionGroupOption():

-                    raise AssertionError(  # noqa: TRY003

+                    raise AssertionError(  # noqa: DOC501,TRY003

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

                     )

                 case _:

@@ -940,7 +963,7 @@ def derivepassphrase(

         if is_param_set(param) and not service:

             opt_str = param.opts[0]

             msg = f'{opt_str} requires a SERVICE'

-            raise click.UsageError(msg)

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

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

         if is_param_set(param) and not (

             service or is_param_set(params_by_str['--config'])

@@ -967,7 +990,7 @@ def derivepassphrase(

         ).get('notes', '')

         notes_value = click.edit(text=text)

         if notes_value is not None:

-            notes_lines = collections.deque(notes_value.splitlines(True))

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

             while notes_lines:

                 line = notes_lines.popleft()

                 if line.startswith(DEFAULT_NOTES_MARKER):

@@ -995,7 +1018,8 @@ def derivepassphrase(

         put_config({'services': {}})

     elif import_settings:

         try:

-            # TODO: keep track of auto-close; try os.dup if feasible

+            # TODO(the-13th-letter): keep track of auto-close; try

+            # os.dup if feasible

             infile = (

                 cast(TextIO, import_settings)

                 if hasattr(import_settings, 'close')

@@ -1032,7 +1056,8 @@ def derivepassphrase(

     elif export_settings:

         configuration = get_config()

         try:

-            # TODO: keep track of auto-close; try os.dup if feasible

+            # TODO(the-13th-letter): keep track of auto-close; try

+            # os.dup if feasible

             outfile = (

                 cast(TextIO, export_settings)

                 if hasattr(export_settings, 'close')

@@ -35,7 +35,7 @@ def _load_data(

     fmt: Literal['v0.2', 'v0.3', 'storeroom'],

     path: str | bytes | os.PathLike[str],

     key: bytes,

-) -> Any:

+) -> Any:  # noqa: ANN401

     contents: bytes

     module: types.ModuleType

     match fmt:

@@ -1,4 +1,8 @@

-#!/usr/bin/python3

+# SPDX-FileCopyrightText: 2024 Marco Ricci <m@the13thletter.info>

+#

+# SPDX-License-Identifier: MIT

+

+"""Exporter for the vault "storeroom" configuration format."""

 from __future__ import annotations

@@ -31,18 +35,18 @@ else:

         from cryptography.hazmat.primitives.kdf import pbkdf2

     except ModuleNotFoundError as exc:

-        class DummyModule:  # pragma: no cover

+        class _DummyModule:  # pragma: no cover

             def __init__(self, exc: type[Exception]) -> None:

                 self.exc = exc

-            def __getattr__(self, name: str) -> Any:

-                def func(*args: Any, **kwargs: Any) -> Any:  # noqa: ARG001

+            def __getattr__(self, name: str) -> Any:  # noqa: ANN401

+                def func(*args: Any, **kwargs: Any) -> Any:  # noqa: ANN401,ARG001

                     raise self.exc

                 return func

-        ciphers = hashes = hmac = padding = DummyModule(exc)

-        algorithms = modes = pbkdf2 = DummyModule(exc)

+        ciphers = hashes = hmac = padding = _DummyModule(exc)

+        algorithms = modes = pbkdf2 = _DummyModule(exc)

         STUBBED = True

     else:

         STUBBED = False

@@ -58,11 +62,36 @@ logger = logging.getLogger(__name__)

 class KeyPair(TypedDict):

+    """A pair of AES256 keys, one for encryption and one for signing.

+

+    Attributes:

+        encryption_key:

+            AES256 key, used for encryption with AES256-CBC (with PKCS#7

+            padding).

+        signing_key:

+            AES256 key, used for signing with HMAC-SHA256.

+

+    """

+

     encryption_key: bytes

     signing_key: bytes

 class MasterKeys(TypedDict):

+    """A triple of AES256 keys, for encryption, signing and hashing.

+

+    Attributes:

+        hashing_key:

+            AES256 key, used for hashing with HMAC-SHA256 to derive

+            a hash table slot for an item.

+        encryption_key:

+            AES256 key, used for encryption with AES256-CBC (with PKCS#7

+            padding).

+        signing_key:

+            AES256 key, used for signing with HMAC-SHA256.

+

+    """

+

     hashing_key: bytes

     encryption_key: bytes

     signing_key: bytes

@@ -94,7 +123,7 @@ def derive_master_keys_keys(password: str | bytes, iterations: int) -> KeyPair:

     if isinstance(password, str):

         password = password.encode('ASCII')

     master_keys_keys_blob = pbkdf2.PBKDF2HMAC(

-        algorithm=hashes.SHA1(),  # noqa: S303

+        algorithm=hashes.SHA1(),

         length=2 * KEY_SIZE,

         salt=STOREROOM_MASTER_KEYS_UUID,

         iterations=iterations,

@@ -157,6 +186,15 @@ def decrypt_master_keys_data(data: bytes, keys: KeyPair) -> MasterKeys:

     Returns:

         The master encryption, signing and hashing keys.

+    Raises:

+        cryptography.exceptions.InvalidSignature:

+            The data does not contain a valid signature under the given

+            key.

+        ValueError:

+            The format is invalid, in a non-cryptographic way.  (For

+            example, it contains an unsupported version marker, or

+            unexpected extra contents, or invalid padding.)

+

     """

     ciphertext, claimed_mac = struct.unpack(

         f'{len(data) - MAC_SIZE}s {MAC_SIZE}s', data

@@ -195,7 +233,7 @@ def decrypt_master_keys_data(data: bytes, keys: KeyPair) -> MasterKeys:

             f'Expecting 3 encrypted keys at {3 * KEY_SIZE} bytes total, '

             f'but found {len(plaintext)} instead'

         )

-        raise RuntimeError(msg)

+        raise ValueError(msg)

     hashing_key, encryption_key, signing_key = struct.unpack(

         f'{KEY_SIZE}s {KEY_SIZE}s {KEY_SIZE}s', plaintext

     )

@@ -238,8 +276,16 @@ def decrypt_session_keys(data: bytes, master_keys: MasterKeys) -> KeyPair:

     Returns:

         The bucket item's encryption and signing keys.

-    """

+    Raises:

+        cryptography.exceptions.InvalidSignature:

+            The data does not contain a valid signature under the given

+            key.

+        ValueError:

+            The format is invalid, in a non-cryptographic way.  (For

+            example, it contains an unsupported version marker, or

+            unexpected extra contents, or invalid padding.)

+    """

     ciphertext, claimed_mac = struct.unpack(

         f'{len(data) - MAC_SIZE}s {MAC_SIZE}s', data

     )

@@ -336,8 +382,16 @@ def decrypt_contents(data: bytes, session_keys: KeyPair) -> bytes:

     Returns:

         The bucket item's payload.

-    """

+    Raises:

+        cryptography.exceptions.InvalidSignature:

+            The data does not contain a valid signature under the given

+            key.

+        ValueError:

+            The format is invalid, in a non-cryptographic way.  (For

+            example, it contains an unsupported version marker, or

+            unexpected extra contents, or invalid padding.)

+    """

     ciphertext, claimed_mac = struct.unpack(

         f'{len(data) - MAC_SIZE}s {MAC_SIZE}s', data

     )

@@ -389,6 +443,30 @@ def decrypt_contents(data: bytes, session_keys: KeyPair) -> bytes:

 def decrypt_bucket_item(bucket_item: bytes, master_keys: MasterKeys) -> bytes:

+    """Decrypt a bucket item.

+

+    Args:

+        bucket_item:

+            The encrypted bucket item.

+        master_keys:

+            The master keys.  Presumably these have previously been

+            obtained via the

+            [`derivepassphrase.exporter.storeroom.decrypt_master_keys_data`][]

+            function.

+

+    Returns:

+        The decrypted bucket item.

+

+    Raises:

+        cryptography.exceptions.InvalidSignature:

+            The data does not contain a valid signature under the given

+            key.

+        ValueError:

+            The format is invalid, in a non-cryptographic way.  (For

+            example, it contains an unsupported version marker, or

+            unexpected extra contents, or invalid padding.)

+

+    """

     logger.debug(

         (

             'decrypt_bucket_item: data = bytes.fromhex(%s), '

@@ -408,7 +486,7 @@ def decrypt_bucket_item(bucket_item: bytes, master_keys: MasterKeys) -> bytes:

     )

     if data_version != 1:

         msg = f'Cannot handle version {data_version} encrypted data'

-        raise RuntimeError(msg)

+        raise ValueError(msg)

     session_keys = decrypt_session_keys(encrypted_session_keys, master_keys)

     return decrypt_contents(data_contents, session_keys)

@@ -419,6 +497,34 @@ def decrypt_bucket_file(

     *,

     root_dir: str | bytes | os.PathLike = '.',

 ) -> Iterator[bytes]:

+    """Decrypt a bucket item.

+

+    Args:

+        filename:

+            The bucket file's filename.

+        master_keys:

+            The master keys.  Presumably these have previously been

+            obtained via the

+            [`derivepassphrase.exporter.storeroom.decrypt_master_keys_data`][]

+            function.

+        root_dir:

+            The root directory of the data store.  The filename is

+            interpreted relatively to this directory.

+

+    Yields:

+        :

+            A decrypted bucket item.

+

+    Raises:

+        cryptography.exceptions.InvalidSignature:

+            The data does not contain a valid signature under the given

+            key.

+        ValueError:

+            The format is invalid, in a non-cryptographic way.  (For

+            example, it contains an unsupported version marker, or

+            unexpected extra contents, or invalid padding.)

+

+    """

     with open(

         os.path.join(os.fsdecode(root_dir), filename), 'rb'

     ) as bucket_file:

@@ -427,10 +533,10 @@ def decrypt_bucket_file(

             header = json.loads(header_line)

         except ValueError as exc:

             msg = f'Invalid bucket file: {filename}'

-            raise RuntimeError(msg) from exc

+            raise ValueError(msg) from exc

         if header != {'version': 1}:

             msg = f'Invalid bucket file: {filename}'

-            raise RuntimeError(msg) from None

+            raise ValueError(msg) from None

         for line in bucket_file:

             yield decrypt_bucket_item(

                 base64.standard_b64decode(line), master_keys

@@ -467,7 +573,7 @@ def store(config: dict[str, Any], path: str, json_contents: bytes) -> None:

         config[path_parts[-1]] = contents

-def export_storeroom_data(

+def export_storeroom_data(  # noqa: C901,PLR0912,PLR0914,PLR0915

     storeroom_path: str | bytes | os.PathLike | None = None,

     master_keys_key: str | bytes | None = None,

 ) -> dict[str, Any]:

@@ -1,4 +1,8 @@

-#!/usr/bin/python3

+# SPDX-FileCopyrightText: 2024 Marco Ricci <m@the13thletter.info>

+#

+# SPDX-License-Identifier: MIT

+

+"""Exporter for the vault native configuration format (v0.2 or v0.3)."""

 from __future__ import annotations

@@ -36,19 +40,19 @@ else:

         from cryptography.hazmat.primitives.kdf import pbkdf2

     except ModuleNotFoundError as exc:

-        class DummyModule:  # pragma: no cover

+        class _DummyModule:  # pragma: no cover

             def __init__(self, exc: type[Exception]) -> None:

                 self.exc = exc

-            def __getattr__(self, name: str) -> Any:

-                def func(*args: Any, **kwargs: Any) -> Any:  # noqa: ARG001

+            def __getattr__(self, name: str) -> Any:  # noqa: ANN401

+                def func(*args: Any, **kwargs: Any) -> Any:  # noqa: ANN401,ARG001

                     raise self.exc

                 return func

-        crypt_exceptions = crypt_utils = DummyModule(exc)

-        ciphers = hashes = hmac = padding = DummyModule(exc)

-        algorithms = modes = pbkdf2 = DummyModule(exc)

+        crypt_exceptions = crypt_utils = _DummyModule(exc)

+        ciphers = hashes = hmac = padding = _DummyModule(exc)

+        algorithms = modes = pbkdf2 = _DummyModule(exc)

         STUBBED = True

     else:

         STUBBED = False

@@ -61,26 +65,66 @@ def _h(bs: bytes | bytearray) -> str:

 class VaultNativeConfigParser(abc.ABC):

+    """A base parser for vault's native configuration format.

+

+    Certain details are specific to the respective vault versions, and

+    are abstracted out.  This class by itself is not instantiable

+    because of this.

+

+    """

+

     def __init__(self, contents: Buffer, password: str | Buffer) -> None:

+        """Initialize the parser.

+

+        Args:

+            contents:

+                The binary contents of the encrypted configuration file.

+

+                Note: On disk, these are usually stored in

+                base64-encoded form, not in the "raw" form as needed

+                here.

+

+            password:

+                The vault master key/master passphrase the file is

+                encrypted with.  Must be non-empty.  See

+                [`derivepassphrase.exporter.get_vault_key`][] for

+                details.

+

+                If this is a text string, then the UTF-8 encoding of the

+                string is used as the binary password.

+

+        """

         if not password:

             msg = 'Password must not be empty'

-            raise ValueError(msg)

+            raise ValueError(msg)  # noqa: DOC501

         self._contents = bytes(contents)

-        self.iv_size = 0

-        self.mac_size = 0

-        self.encryption_key = b''

-        self.encryption_key_size = 0

-        self.signing_key = b''

-        self.signing_key_size = 0

-        self.message = b''

-        self.message_tag = b''

-        self.iv = b''

-        self.payload = b''

+        self._iv_size = 0

+        self._mac_size = 0

+        self._encryption_key = b''

+        self._encryption_key_size = 0

+        self._signing_key = b''

+        self._signing_key_size = 0

+        self._message = b''

+        self._message_tag = b''

+        self._iv = b''

+        self._payload = b''

         self._password = password

         self._sentinel: object = object()

         self._data: Any = self._sentinel

-    def __call__(self) -> Any:

+    def __call__(self) -> Any:  # noqa: ANN401

+        """Return the decrypted and parsed vault configuration.

+

+        Raises:

+            cryptography.exceptions.InvalidSignature:

+                The encrypted configuration does not contain a valid

+                signature.

+            ValueError:

+                The format is invalid, in a non-cryptographic way.  (For

+                example, it contains an unsupported version marker, or

+                unexpected extra contents, or invalid padding.)

+

+        """

         if self._data is self._sentinel:

             self._parse_contents()

             self._derive_keys()

@@ -89,13 +133,13 @@ class VaultNativeConfigParser(abc.ABC):

         return self._data

     @staticmethod

-    def pbkdf2(

+    def _pbkdf2(

         password: str | Buffer, key_size: int, iterations: int

     ) -> bytes:

         if isinstance(password, str):

             password = password.encode('utf-8')

         raw_key = pbkdf2.PBKDF2HMAC(

-            algorithm=hashes.SHA1(),  # noqa: S303

+            algorithm=hashes.SHA1(),

             length=key_size // 2,

             salt=vault.Vault._UUID,  # noqa: SLF001

             iterations=iterations,

@@ -115,35 +159,35 @@ class VaultNativeConfigParser(abc.ABC):

     def _parse_contents(self) -> None:

         logger.info('Parsing IV, payload and signature from the file contents')

-        if len(self._contents) < self.iv_size + 16 + self.mac_size:

+        if len(self._contents) < self._iv_size + 16 + self._mac_size:

             msg = 'Invalid vault configuration file: file is truncated'

             raise ValueError(msg)

         def cut(buffer: bytes, cutpoint: int) -> tuple[bytes, bytes]:

             return buffer[:cutpoint], buffer[cutpoint:]

-        cutpos1 = len(self._contents) - self.mac_size

-        cutpos2 = self.iv_size

+        cutpos1 = len(self._contents) - self._mac_size

+        cutpos2 = self._iv_size

-        self.message, self.message_tag = cut(self._contents, cutpos1)

-        self.iv, self.payload = cut(self.message, cutpos2)

+        self._message, self._message_tag = cut(self._contents, cutpos1)

+        self._iv, self._payload = cut(self._message, cutpos2)

         logger.debug(

             'buffer %s = [[%s, %s], %s]',

             _h(self._contents),

-            _h(self.iv),

-            _h(self.payload),

-            _h(self.message_tag),

+            _h(self._iv),

+            _h(self._payload),

+            _h(self._message_tag),

         )

     def _derive_keys(self) -> None:

         logger.info('Deriving an encryption and signing key')

         self._generate_keys()

         assert (

-            len(self.encryption_key) == self.encryption_key_size

+            len(self._encryption_key) == self._encryption_key_size

         ), 'Derived encryption key is invalid'

         assert (

-            len(self.signing_key) == self.signing_key_size

+            len(self._signing_key) == self._signing_key_size

         ), 'Derived signing key is invalid'

     @abc.abstractmethod

@@ -152,16 +196,16 @@ class VaultNativeConfigParser(abc.ABC):

     def _check_signature(self) -> None:

         logger.info('Checking HMAC signature')

-        mac = hmac.HMAC(self.signing_key, hashes.SHA256())

+        mac = hmac.HMAC(self._signing_key, hashes.SHA256())

         mac_input = self._hmac_input()

         logger.debug(

             'mac_input = %s, expected_tag = %s',

             _h(mac_input),

-            _h(self.message_tag),

+            _h(self._message_tag),

         )

         mac.update(mac_input)

         try:

-            mac.verify(self.message_tag)

+            mac.verify(self._message_tag)

         except crypt_exceptions.InvalidSignature:

             msg = 'File does not contain a valid signature'

             raise ValueError(msg) from None

@@ -170,13 +214,13 @@ class VaultNativeConfigParser(abc.ABC):

     def _hmac_input(self) -> bytes:

         raise AssertionError

-    def _decrypt_payload(self) -> Any:

+    def _decrypt_payload(self) -> Any:  # noqa: ANN401

         decryptor = self._make_decryptor()

         padded_plaintext = bytearray()

-        padded_plaintext.extend(decryptor.update(self.payload))

+        padded_plaintext.extend(decryptor.update(self._payload))

         padded_plaintext.extend(decryptor.finalize())

         logger.debug('padded plaintext = %s', _h(padded_plaintext))

-        unpadder = padding.PKCS7(self.iv_size * 8).unpadder()

+        unpadder = padding.PKCS7(self._iv_size * 8).unpadder()

         plaintext = bytearray()

         plaintext.extend(unpadder.update(padded_plaintext))

         plaintext.extend(unpadder.finalize())

@@ -189,40 +233,52 @@ class VaultNativeConfigParser(abc.ABC):

 class VaultNativeV03ConfigParser(VaultNativeConfigParser):

+    """A parser for vault's native configuration format (v0.3).

+

+    This is the modern, pre-storeroom configuration format.

+

+    """

+

     KEY_SIZE = 32

-    def __init__(self, *args: Any, **kwargs: Any) -> None:

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

         super().__init__(*args, **kwargs)

-        self.iv_size = 16

-        self.mac_size = 32

+        self._iv_size = 16

+        self._mac_size = 32

-    def __call__(self) -> Any:

+    def __call__(self) -> Any:  # noqa: ANN401,D102

         if self._data is self._sentinel:

             logger.info('Attempting to parse as v0.3 configuration')

             return super().__call__()

         return self._data

     def _generate_keys(self) -> None:

-        self.encryption_key = self.pbkdf2(self._password, self.KEY_SIZE, 100)

-        self.signing_key = self.pbkdf2(self._password, self.KEY_SIZE, 200)

-        self.encryption_key_size = self.signing_key_size = self.KEY_SIZE

+        self._encryption_key = self._pbkdf2(self._password, self.KEY_SIZE, 100)

+        self._signing_key = self._pbkdf2(self._password, self.KEY_SIZE, 200)

+        self._encryption_key_size = self._signing_key_size = self.KEY_SIZE

     def _hmac_input(self) -> bytes:

-        return self.message.hex().lower().encode('ASCII')

+        return self._message.hex().lower().encode('ASCII')

     def _make_decryptor(self) -> ciphers.CipherContext:

         return ciphers.Cipher(

-            algorithms.AES256(self.encryption_key), modes.CBC(self.iv)

+            algorithms.AES256(self._encryption_key), modes.CBC(self._iv)

         ).decryptor()

 class VaultNativeV02ConfigParser(VaultNativeConfigParser):

-    def __init__(self, *args: Any, **kwargs: Any) -> None:

+    """A parser for vault's native configuration format (v0.3).

+

+    This is the modern, pre-storeroom configuration format.

+

+    """

+

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

         super().__init__(*args, **kwargs)

-        self.iv_size = 16

-        self.mac_size = 64

+        self._iv_size = 16

+        self._mac_size = 64

-    def __call__(self) -> Any:

+    def __call__(self) -> Any:  # noqa: ANN401,D102

         if self._data is self._sentinel:

             logger.info('Attempting to parse as v0.2 configuration')

             return super().__call__()

@@ -231,17 +287,17 @@ class VaultNativeV02ConfigParser(VaultNativeConfigParser):

     def _parse_contents(self) -> None:

         super()._parse_contents()

         logger.debug('Decoding payload (base64) and message tag (hex)')

-        self.payload = base64.standard_b64decode(self.payload)

-        self.message_tag = bytes.fromhex(self.message_tag.decode('ASCII'))

+        self._payload = base64.standard_b64decode(self._payload)

+        self._message_tag = bytes.fromhex(self._message_tag.decode('ASCII'))

     def _generate_keys(self) -> None:

-        self.encryption_key = self.pbkdf2(self._password, 8, 16)

-        self.signing_key = self.pbkdf2(self._password, 16, 16)

-        self.encryption_key_size = 8

-        self.signing_key_size = 16

+        self._encryption_key = self._pbkdf2(self._password, 8, 16)

+        self._signing_key = self._pbkdf2(self._password, 16, 16)

+        self._encryption_key_size = 8

+        self._signing_key_size = 16

     def _hmac_input(self) -> bytes:

-        return base64.standard_b64encode(self.message)

+        return base64.standard_b64encode(self._message)

     def _make_decryptor(self) -> ciphers.CipherContext:

         def evp_bytestokey_md5_one_iteration_no_salt(

@@ -268,7 +324,7 @@ class VaultNativeV02ConfigParser(VaultNativeConfigParser):

                     warnings.simplefilter(

                         'ignore', crypt_utils.CryptographyDeprecationWarning

                     )

-                    block = hashes.Hash(hashes.MD5())  # noqa: S303

+                    block = hashes.Hash(hashes.MD5())

                 block.update(last_block)

                 block.update(data)

                 block.update(salt)

@@ -284,7 +340,7 @@ class VaultNativeV02ConfigParser(VaultNativeConfigParser):

             )

             return bytes(buffer[:key_size]), bytes(buffer[key_size:total_size])

-        data = base64.standard_b64encode(self.iv + self.encryption_key)

+        data = base64.standard_b64encode(self._iv + self._encryption_key)

         encryption_key, iv = evp_bytestokey_md5_one_iteration_no_salt(

             data, key_size=32, iv_size=16

         )

@@ -64,7 +64,7 @@ class Sequin:

         /,

         *,

         is_bitstring: bool = False,

-    ):

+    ) -> None:

         """Initialize the Sequin.

         Args:

@@ -176,6 +176,9 @@ class Sequin:

             digits: A sequence of integers to evaluate.

             base: The number base to evaluate those integers in.

+        Returns:

+            The number value of the integer sequence.

+

         Raises:

             ValueError: `base` is an invalid base.

             ValueError: Not all integers are valid base `base` digits.

@@ -204,7 +207,7 @@ class Sequin:

             x = digits[i]

             if not isinstance(x, int):

                 msg = f'not an integer: {x!r}'

-                raise TypeError(msg)

+                raise TypeError(msg)  # noqa: DOC501

             if x not in allowed_range:

                 msg = f'invalid base {base!r} digit: {x!r}'

                 raise ValueError(msg)

@@ -387,5 +390,5 @@ class SequinExhaustedError(Exception):

     """

-    def __init__(self) -> None:

+    def __init__(self) -> None:  # noqa: D107

         super().__init__('Sequin is exhausted')

@@ -115,7 +115,12 @@ class SSHAgentClient:

             self._connection.connect(ssh_auth_sock)

     def __enter__(self) -> Self:

-        """Close socket connection upon context manager completion."""

+        """Close socket connection upon context manager completion.

+

+        Returns:

+            Self.

+

+        """

         self._connection.__enter__()

         return self

@@ -125,7 +130,18 @@ class SSHAgentClient:

         exc_val: BaseException | None,

         exc_tb: TracebackType | None,

     ) -> bool:

-        """Close socket connection upon context manager completion."""

+        """Close socket connection upon context manager completion.

+

+        Args:

+            exc_type: An optional exception type.

+            exc_val: An optional exception value.

+            exc_tb: An optional exception traceback.

+

+        Returns:

+            True if the exception was handled, false if it should

+            propagate.

+

+        """

         return bool(

             self._connection.__exit__(exc_type, exc_val, exc_tb)  # type: ignore[func-returns-value]

         )

@@ -173,7 +189,7 @@ class SSHAgentClient:

             ret.extend(payload)

         except Exception as e:

             msg = 'invalid payload type'

-            raise TypeError(msg) from e

+            raise TypeError(msg) from e  # noqa: DOC501

         return ret

     @classmethod

@@ -2,7 +2,7 @@

 #

 # SPDX-License-Identifier: MIT

-"""Python port of the vault(1) password generation scheme"""

+"""Python port of the vault(1) password generation scheme."""

 from __future__ import annotations

@@ -71,7 +71,7 @@ class Vault:

     """

-    def __init__(

+    def __init__(  # noqa: PLR0913

         self,

         *,

         phrase: bytes | bytearray | str = b'',

@@ -113,6 +113,11 @@ class Vault:

                 Same as `lower`, but for all other hitherto unlisted

                 ASCII printable characters (except backquote).

+        Raises:

+            ValueError:

+                Conflicting passphrase constraints.  Permit more

+                characters, or increase the desired passphrase length.

+

         """

         self._phrase = self._get_binary_string(phrase)

         self._length = length

@@ -204,10 +209,10 @@ class Vault:

             safety_factor = float(safety_factor)

         except TypeError as e:

             msg = f'invalid safety factor: not a float: {safety_factor!r}'

-            raise TypeError(msg) from e

+            raise TypeError(msg) from e  # noqa: DOC501

         if not math.isfinite(safety_factor) or safety_factor < 1.0:

             msg = f'invalid safety factor {safety_factor!r}'

-            raise ValueError(msg)

+            raise ValueError(msg)  # noqa: DOC501

         # Ensure the bound is strictly positive.

         entropy_bound = max(1, self._entropy())

         return int(math.ceil(safety_factor * entropy_bound / 8))

@@ -255,4 +255,4 @@ class TestVault:

         with pytest.raises(

             TypeError, match='invalid safety factor: not a float'

         ):

-            assert v._estimate_sufficient_hash_length(None)  # type: ignore

+            assert v._estimate_sufficient_hash_length(None)  # type: ignore[arg-type]

@@ -392,7 +392,7 @@ class TestCLI:

         key_index: int,

     ) -> None:

         def sign(

-            _, key: bytes | bytearray, message: bytes | bytearray

+            _: Any, key: bytes | bytearray, message: bytes | bytearray

         ) -> bytes:

             del message  # Unused.

             for value in tests.SUPPORTED_KEYS.values():

@@ -1299,7 +1299,7 @@ contents go here

                     'services': {

                         DUMMY_SERVICE: DUMMY_CONFIG_SETTINGS.copy(),

                         'weird entry name': {'phrase': 'D\u00fcsseldorf'},

-                    }

+                    },