derivepassphrase.git

@@ -78,6 +78,7 @@ plugins:

           separate_signature: true

           signature_crossrefs: true

           unwrap_annotated: true

+          scoped_crossrefs: true

         paths:

           - src

   mike:

@@ -190,11 +190,10 @@ class SSH_AGENTC(enum.Enum):  # noqa: N801

     Attributes:

         REQUEST_IDENTITIES:

-            List identities.  Expecting [`SSH_AGENT.IDENTITIES_ANSWER`]

-            [derivepassphrase._types.SSH_AGENT].

+            List identities.  Expecting

+            [`SSH_AGENT.IDENTITIES_ANSWER`][].

         SIGN_REQUEST:

-            Sign data.  Expecting [`SSH_AGENT.SIGN_RESPONSE`]

-            [derivepassphrase._types.SSH_AGENT].

+            Sign data.  Expecting [`SSH_AGENT.SIGN_RESPONSE`][].

         ADD_IDENTITY:

             Add an (SSH2) identity.

         REMOVE_IDENTITY:

@@ -225,11 +224,9 @@ class SSH_AGENT(enum.Enum):  # noqa: N801

         SUCCESS:

             Generic success code.

         IDENTITIES_ANSWER:

-            Successful answer to [`SSH_AGENTC.REQUEST_IDENTITIES`]

-            [derivepassphrase._types.SSH_AGENTC].

+            Successful answer to [`SSH_AGENTC.REQUEST_IDENTITIES`][].

         SIGN_RESPONSE:

-            Successful answer to [`SSH_AGENTC.SIGN_REQUEST`]

-            [derivepassphrase._types.SSH_AGENTC].

+            Successful answer to [`SSH_AGENTC.SIGN_REQUEST`][].

     """

@@ -387,13 +387,11 @@ def _config_filename(

 def _load_config() -> _types.VaultConfig:

     """Load a vault(1)-compatible config from the application directory.

-    The filename is obtained via

-    [`derivepassphrase.cli._config_filename`][].  This must be an

-    unencrypted JSON file.

+    The filename is obtained via [`_config_filename`][].  This must be

+    an unencrypted JSON file.

     Returns:

-        The vault settings.  See

-        [`derivepassphrase._types.VaultConfig`][] for details.

+        The vault settings.  See [`_types.VaultConfig`][] for details.

     Raises:

         OSError:

@@ -416,15 +414,14 @@ def _migrate_and_load_old_config() -> (

 ):

     """Load and migrate a vault(1)-compatible config.

-    The (old) filename is obtained via

-    [`derivepassphrase.cli._config_filename`][].  This must be an

-    unencrypted JSON file.  After loading, the file is migrated to the new

-    standard filename.

+    The (old) filename is obtained via [`_config_filename`][].  This

+    must be an unencrypted JSON file.  After loading, the file is

+    migrated to the new standard filename.

     Returns:

         The vault settings, and an optional exception encountered during

-        migration.  See [`derivepassphrase._types.VaultConfig`][] for

-        details on the former.

+        migration.  See [`_types.VaultConfig`][] for details on the

+        former.

     Raises:

         OSError:

@@ -451,9 +448,8 @@ def _migrate_and_load_old_config() -> (

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

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

-    The filename is obtained via

-    [`derivepassphrase.cli._config_filename`][].  The config will be

-    stored as an unencrypted JSON file.

+    The filename is obtained via [`_config_filename`][].  The config

+    will be stored as an unencrypted JSON file.

     Args:

         config:

@@ -485,7 +481,7 @@ def _get_suitable_ssh_keys(

     """Yield all SSH keys suitable for passphrase derivation.

     Suitable SSH keys are queried from the running SSH agent (see

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

+    [`ssh_agent.SSHAgentClient.list_keys`][]).

     Args:

         conn:

@@ -628,9 +624,8 @@ def _select_ssh_key(

     """Interactively select an SSH key for passphrase derivation.

     Suitable SSH keys are queried from the running SSH agent (see

-    [`derivepassphrase.ssh_agent.SSHAgentClient.list_keys`][]), then the

-    user is prompted interactively (see [`click.prompt`][]) for

-    a selection.

+    [`ssh_agent.SSHAgentClient.list_keys`][]), then the user is prompted

+    interactively (see [`click.prompt`][]) for a selection.

     Args:

         conn:

@@ -744,9 +739,8 @@ def _check_for_misleading_passphrase(

 class OptionGroupOption(click.Option):

     """A [`click.Option`][] with an associated group name and group epilog.

-    Used by [`derivepassphrase.cli.CommandWithHelpGroups`][] to print

-    help sections.  Each subclass contains its own group name and

-    epilog.

+    Used by [`CommandWithHelpGroups`][] to print help sections.  Each

+    subclass contains its own group name and epilog.

     Attributes:

         option_group_name:

@@ -759,7 +753,9 @@ class OptionGroupOption(click.Option):

     """

     option_group_name: str = ''

+    """"""

     epilog: str = ''

+    """"""

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

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

@@ -789,12 +785,12 @@ class CommandWithHelpGroups(click.Command):

         of the `formatter`.  We list all options (like the base

         implementation), but grouped into sections according to the

         concrete [`click.Option`][] subclass being used.  If the option

-        is an instance of some subclass `X` of

-        [`derivepassphrase.cli.OptionGroupOption`][], then the section

-        heading and the epilog are taken from `X.option_group_name` and

-        `X.epilog`; otherwise, the section heading is "Options" (or

-        "Other options" if there are other option groups) and the epilog

-        is empty.

+        is an instance of some subclass of [`OptionGroupOption`][], then

+        the section heading and the epilog are taken from the

+        [`option_group_name`] [OptionGroupOption.option_group_name] and

+        [`epilog`] [OptionGroupOption.epilog] attributes; otherwise, the

+        section heading is "Options" (or "Other options" if there are

+        other option groups) and the epilog is empty.

         Args:

             ctx:

@@ -12,12 +12,11 @@ table entry is separately encrypted and authenticated.  James Coglan

 designed this format to avoid concurrent write issues when updating or

 synchronizing the vault configuration with e.g. a cloud service.

-The public interface is the

-[`derivepassphrase.exporter.storeroom.export_storeroom_data`][]

-function.  Multiple *non-public* functions are additionally documented

-here for didactical and educational reasons, but they are not part of

-the module API, are subject to change without notice (including

-removal), and should *not* be used or relied on.

+The public interface is the [`export_storeroom_data`][] function.

+Multiple *non-public* functions are additionally documented here for

+didactical and educational reasons, but they are not part of the module

+API, are subject to change without notice (including removal), and

+should *not* be used or relied on.

 """

@@ -209,8 +208,7 @@ def decrypt_master_keys_data(data: bytes, keys: KeyPair) -> MasterKeys:

         keys:

             The encryption and signing keys for the master keys data.

             These should have previously been derived via the

-            [`derivepassphrase.exporter.storeroom.derive_master_keys_keys`][]

-            function.

+            [`derive_master_keys_keys`][] function.

     Returns:

         The master encryption, signing and hashing keys.

@@ -303,9 +301,7 @@ def decrypt_session_keys(data: bytes, master_keys: MasterKeys) -> KeyPair:

             The encrypted bucket item session key data.

         master_keys:

             The master keys.  Presumably these have previously been

-            obtained via the

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

-            function.

+            obtained via the [`decrypt_master_keys_data`][] function.

     Returns:

         The bucket item's encryption and signing keys.

@@ -414,8 +410,7 @@ def decrypt_contents(data: bytes, session_keys: KeyPair) -> bytes:

             The encrypted bucket item payload data.

         session_keys:

             The bucket item's session keys.  Presumably these have

-            previously been obtained via the

-            [`derivepassphrase.exporter.storeroom.decrypt_session_keys`][]

+            previously been obtained via the [`decrypt_session_keys`][]

             function.

     Returns:

@@ -494,9 +489,7 @@ def decrypt_bucket_item(bucket_item: bytes, master_keys: MasterKeys) -> bytes:

             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.

+            obtained via the [`decrypt_master_keys_data`][] function.

     Returns:

         The decrypted bucket item.

@@ -553,9 +546,7 @@ def decrypt_bucket_file(

             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.

+            obtained via the [`decrypt_master_keys_data`][] function.

         root_dir:

             The root directory of the data store.  The filename is

             interpreted relatively to this directory.

@@ -635,13 +626,12 @@ def export_storeroom_data(  # noqa: C901,PLR0912,PLR0914,PLR0915

     Args:

         storeroom_path:

             Path to the storeroom; usually `~/.vault`.  If not given,

-            then query [`derivepassphrase.exporter.get_vault_path`][]

-            for the value.

+            then query [`exporter.get_vault_path`][] for the value.

         master_keys_key:

             Encryption key/password for the master keys, usually the

             username, or passed via the `VAULT_KEY` environment

             variable.  If not given, then query

-            [`derivepassphrase.exporter.get_vault_key`][] for the value.

+            [`exporter.get_vault_key`][] for the value.

     Returns:

         The full configuration, as stored in the storeroom.

@@ -13,12 +13,11 @@ cryptographic weaknesses (API misuse of a key derivation function, and

 a low-entropy method of generating initialization vectors for CBC block

 encryption mode) and should thus be avoided if possible.

-The public interface is the

-[`derivepassphrase.exporter.vault_native.export_vault_native_data`][]

-function.  Multiple *non-public* classes are additionally documented

-here for didactical and educational reasons, but they are not part of

-the module API, are subject to change without notice (including

-removal), and should *not* be used or relied on.

+The public interface is the [`export_vault_native_data`][] function.

+Multiple *non-public* classes are additionally documented here for

+didactical and educational reasons, but they are not part of the module

+API, are subject to change without notice (including removal), and

+should *not* be used or relied on.

 """

@@ -108,8 +107,7 @@ class VaultNativeConfigParser(abc.ABC):

             password:

                 The vault master key/master passphrase the file is

                 encrypted with.  Must be non-empty.  See

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

-                details.

+                [`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.

@@ -403,8 +401,8 @@ def export_vault_native_data(

         contents:

             The binary encrypted contents of the vault configuration

             file.  If not given, then query

-            [`derivepassphrase.exporter.get_vault_path`][] for the

-            correct filename and read the contents from there.

+            [`exporter.get_vault_path`][] for the correct filename and

+            read the contents from there.

             Note: On disk, these are usually stored in base64-encoded

             form, not in the "raw" form as needed here.

@@ -412,7 +410,7 @@ def export_vault_native_data(

             Encryption key/password for the configuration file, usually

             the username, or passed via the `VAULT_KEY` environment

             variable.  If not given, then query

-            [`derivepassphrase.exporter.get_vault_key`][] for the value.

+            [`exporter.get_vault_key`][] for the value.

         try_formats:

             A sequence of formats to try out, in order.  Each key must

             be one of `v0.2` or `v0.3`.

@@ -14,8 +14,7 @@ deterministic, stateless password manager that recomputes passwords

 instead of storing them), and this reimplementation is used for

 a similar purpose.

-The main API is the [`Sequin`] [derivepassphrase.sequin.Sequin] class,

-which is thoroughly documented.

+The main API is the [`Sequin`][] class, which is thoroughly documented.

 """

@@ -61,11 +61,13 @@ class SSHAgentClient:

     The main use case is requesting the agent sign some data, after

     checking that the necessary key is already loaded.

-    The main fleshed out methods are `list_keys` and `sign`, which

-    implement the `REQUEST_IDENTITIES` and `SIGN_REQUEST` requests.  If

-    you *really* wanted to, there is enough infrastructure in place to

-    issue other requests as defined in the protocol---it's merely the

-    wrapper functions and the protocol numbers table that are missing.

+    The main fleshed out methods are [`list_keys`][] and [`sign`][],

+    which implement the [`REQUEST_IDENTITIES`]

+    [_types.SSH_AGENTC.REQUEST_IDENTITIES] and [`SIGN_REQUEST`]

+    [_types.SSH_AGENTC.SIGN_REQUEST] requests.  If you *really* wanted

+    to, there is enough infrastructure in place to issue other requests

+    as defined in the protocol---it's merely the wrapper functions and

+    the protocol numbers table that are missing.

     """

@@ -433,7 +435,7 @@ class SSHAgentClient:

         Args:

             key:

                 The public SSH key to sign the payload with, in the same

-                format as returned by, e.g., the `list_keys` method.

+                format as returned by, e.g., the [`list_keys`][] method.

                 The corresponding private key must have previously been

                 loaded into the agent to successfully issue a signature.

             payload:

@@ -445,7 +447,7 @@ class SSHAgentClient:

                 algorithms when signing with RSA keys.  (No such

                 real-world usage is currently implemented.)

             check_if_key_loaded:

-                If true, check beforehand (via `list_keys`) if the

+                If true, check beforehand (via [`list_keys`][]) if the

                 corresponding key has been loaded into the agent.

         Returns:

@@ -34,10 +34,9 @@ class Vault:

     detail][ALGORITHM] in his blog post on said topic: A principally

     infinite bit stream is obtained by running a key-derivation function

     on the master passphrase and the service name, then this bit stream

-    is fed into a [Sequin][derivepassphrase.sequin.Sequin] to generate

-    random numbers in the correct range, and finally these random

-    numbers select passphrase characters until the desired length is

-    reached.

+    is fed into a [sequin.Sequin][] to generate random numbers in the

+    correct range, and finally these random numbers select passphrase

+    characters until the desired length is reached.

     [vault]: https://www.npmjs.com/package/vault

     [ALGORITHM]: https://blog.jcoglan.com/2012/07/16/designing-vaults-generator-algorithm/

@@ -219,10 +218,10 @@ class Vault:

     ) -> int:

         """Estimate the sufficient hash length, given the current settings.

-        Using the entropy (via `_entropy`) and a safety factor, give an

-        initial estimate of the length to use for `create_hash` such

-        that using a `Sequin` with this hash will not exhaust it during

-        passphrase generation.

+        Using the entropy (via [`_entropy`][]) and a safety factor, give

+        an initial estimate of the length to use for [`create_hash`][]

+        such that using a [`sequin.Sequin`][] with this hash will not

+        exhaust it during passphrase generation.

         Args:

             safety_factor: The safety factor.  Must be at least 1.