derivepassphrase.git

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

     Attributes:

         REQUEST_IDENTITIES:

-            List identities.  Expecting `SSH_AGENT.IDENTITIES_ANSWER`.

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

+            [derivepassphrase._types.SSH_AGENT].

         SIGN_REQUEST:

-            Sign data.  Expecting `SSH_AGENT.SIGN_RESPONSE`.

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

+            [derivepassphrase._types.SSH_AGENT].

     """

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

         SUCCESS:

             Generic success code.

         IDENTITIES_ANSWER:

-            Successful answer to `SSH_AGENTC.REQUEST_IDENTITIES`.

+            Successful answer to [`SSH_AGENTC.REQUEST_IDENTITIES`]

+            [derivepassphrase._types.SSH_AGENTC].

         SIGN_RESPONSE:

-            Successful answer to `SSH_AGENTC.SIGN_REQUEST`.

+            Successful answer to [`SSH_AGENTC.SIGN_REQUEST`]

+            [derivepassphrase._types.SSH_AGENTC].

     """

@@ -393,7 +393,7 @@ def _load_config() -> _types.VaultConfig:

     Returns:

         The vault settings.  See

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

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

     Raises:

         OSError:

@@ -423,7 +423,7 @@ def _migrate_and_load_old_config() -> (

     Returns:

         The vault settings, and an optional exception encountered during

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

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

         details on the former.

     Raises:

@@ -485,7 +485,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

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

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

     Args:

         conn:

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

             SSH agent.

         RuntimeError:

             There was an error communicating with the SSH agent.

-        SSHAgentFailedError:

+        ssh_agent.SSHAgentFailedError:

             The agent failed to supply a list of loaded keys.

     """

@@ -629,8 +629,9 @@ def _select_ssh_key(

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

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

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

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

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

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

+    a selection.

     Args:

         conn:

@@ -17,10 +17,11 @@ __all__ = ()

 def get_vault_key() -> bytes:

-    """Automatically determine the vault master key/password.

+    """Automatically determine the vault(1) master key/password.

     Query the `VAULT_KEY`, `LOGNAME`, `USER` and `USERNAME` environment

-    variables, in that order.  This is the same algorithm as vault uses.

+    variables, in that order.  This is the same algorithm that vault

+    uses.

     Returns:

         The master key/password.  This is generally used as input to

@@ -46,10 +47,10 @@ def get_vault_key() -> bytes:

 def get_vault_path() -> str | bytes | os.PathLike:

-    """Automatically determine the vault configuration path.

+    """Automatically determine the vault(1) configuration path.

     Query the `VAULT_PATH` environment variable, or default to

-    `~/.vault`.  This is the same algorithm as vault uses.  If not

+    `~/.vault`.  This is the same algorithm that vault uses.  If not

     absolute, then `VAULT_PATH` is relative to the home directory.

     Returns:

@@ -285,21 +285,21 @@ class Sequin:

         take `k` numbers from the base `base` sequence (or bail if not

         possible).  If the resulting number `v` is out of range for

         base `n`, then push `v - n` onto the rejection queue for

-        base `r` = `base` ** `k` - `n`, and attempt to generate the

-        requested base `n` integer from the sequence of base `r` numbers

-        next.  (This recursion is not attempted if `r` = 1.)  Otherwise,

-        return the number.

+        base `r` (where `r = base ** k - n`), and attempt to generate

+        the requested base `n` integer from the sequence of base `r`

+        numbers next.  (This recursion is not attempted if `r` = 1.)

+        Otherwise, return the number.

         Args:

             n:

-                Generate numbers in the range 0, ..., `n` - 1.

+                Generate numbers in the range 0, ..., `n - 1`.

                 (Inclusive.)  Must be larger than 0.

             base:

                 Use the base `base` sequence as a source for

                 pseudorandom numbers.

         Returns:

-            A pseudorandom number in the range 0, ..., `n` - 1 if

+            A pseudorandom number in the range 0, ..., `n - 1` if

             possible, or `n` if the stream is exhausted.

         Raises:

@@ -377,7 +377,11 @@ class Sequin:

         return v

     def _stash(self, value: int, /, *, base: int = 2) -> None:

-        """Stash `value` on the base `base` sequence."""

+        """Stash `value` on the base `base` sequence.

+

+        Sets up the base `base` sequence if it does not yet exist.

+

+        """

         if base not in self.bases:

             self.bases[base] = collections.deque()

         self.bases[base].append(value)

@@ -10,6 +10,7 @@ import base64

 import collections

 import hashlib

 import math

+import types

 from collections.abc import Callable

 from typing import TypeAlias

@@ -20,24 +21,6 @@ from derivepassphrase import sequin, ssh_agent

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

-_CHARSETS = collections.OrderedDict([

-    ('lower', b'abcdefghijklmnopqrstuvwxyz'),

-    ('upper', b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'),

-    ('alpha', b''),  # Placeholder.

-    ('number', b'0123456789'),

-    ('alphanum', b''),  # Placeholder.

-    ('space', b' '),

-    ('dash', b'-_'),

-    ('symbol', b'!"#$%&\'()*+,./:;<=>?@[\\]^{|}~-_'),

-    ('all', b''),  # Placeholder.

-])

-_CHARSETS['alpha'] = _CHARSETS['lower'] + _CHARSETS['upper']

-_CHARSETS['alphanum'] = _CHARSETS['alpha'] + _CHARSETS['number']

-_CHARSETS['all'] = (

-    _CHARSETS['alphanum'] + _CHARSETS['space'] + _CHARSETS['symbol']

-)

-

-

 class Vault:

     """A work-alike of James Coglan's vault.

@@ -63,7 +46,51 @@ class Vault:

     _UUID = b'e87eb0f4-34cb-46b9-93ad-766c5ab063e7'

     """A tag used by vault in the bit stream generation."""

-    _CHARSETS = _CHARSETS

+    _CHARSETS = types.MappingProxyType(

+        collections.OrderedDict([

+            ('lower', b'abcdefghijklmnopqrstuvwxyz'),

+            ('upper', b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'),

+            (

+                'alpha',

+                (

+                    # _CHARSETS['lower']

+                    b'abcdefghijklmnopqrstuvwxyz'

+                    # _CHARSETS['upper']

+                    b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'

+                ),

+            ),

+            ('number', b'0123456789'),

+            (

+                'alphanum',

+                (

+                    # _CHARSETS['lower']

+                    b'abcdefghijklmnopqrstuvwxyz'

+                    # _CHARSETS['upper']

+                    b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'

+                    # _CHARSETS['number']

+                    b'0123456789'

+                ),

+            ),

+            ('space', b' '),

+            ('dash', b'-_'),

+            ('symbol', b'!"#$%&\'()*+,./:;<=>?@[\\]^{|}~-_'),

+            (

+                'all',

+                (

+                    # _CHARSETS['lower']

+                    b'abcdefghijklmnopqrstuvwxyz'

+                    # _CHARSETS['upper']

+                    b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'

+                    # _CHARSETS['number']

+                    b'0123456789'

+                    # _CHARSETS['space']

+                    b' '

+                    # _CHARSETS['symbol']

+                    b'!"#$%&\'()*+,./:;<=>?@[\\]^{|}~-_'

+                ),

+            ),

+        ])

+    )

     """

         Known character sets from which to draw passphrase characters.

         Relies on a certain, fixed order for their definition and their