transcrypto 1.2.0__py3-none-any.whl → 1.4.0__py3-none-any.whl

transcrypto/sss.py

@@ -314,9 +314,7 @@ class ShamirSharedSecretPrivate(ShamirSharedSecretPublic):
     if bit_length < 10:
       raise base.InputError(f'invalid bit length: {bit_length=}')
     # make the primes
-    unique_primes: set[int] = set()
-    while len(unique_primes) < minimum_shares:
-      unique_primes.add(modmath.NBitRandomPrime(bit_length))
+    unique_primes: set[int] = modmath.NBitRandomPrimes(bit_length, n_primes=minimum_shares)
     # get the largest prime for the modulus
     ordered_primes: list[int] = list(unique_primes)
     modulus: int = max(ordered_primes)

transcrypto/transcrypto.py

@@ -10,13 +10,15 @@ Notes on the layout (quick mental model):
 
 isprime, primegen, mersenne
 gcd, xgcd, and grouped mod inv|div|exp|poly|lagrange|crt
-random bits|int|bytes|prime, hash sha256|sha512|file
+random bits|int|bytes|prime
+hash sha256|sha512|file
 aes key frompass, aes encrypt|decrypt (GCM), aes ecb encrypt|decrypt
 rsa new|encrypt|decrypt|sign|verify|rawencrypt|rawdecrypt|rawsign|rawverify
 elgamal shared|new|encrypt|decrypt|sign|verify|rawencrypt|rawdecrypt|rawsign|rawverify
 dsa shared|new|sign|verify|rawsign|rawverify
 bid new|verify
 sss new|shares|recover|rawshares|rawrecover|rawverify
+doc md
 """
 
 from __future__ import annotations
@@ -27,7 +29,7 @@ import glob
 import logging
 # import pdb
 import sys
-from typing import Any, Iterable, Sequence
+from typing import Any, Iterable
 
 from . import base, modmath, rsa, sss, elgamal, dsa, aes
 
@@ -119,179 +121,6 @@ def _LoadObj(path: str, password: str | None, expect: type, /) -> Any:
   return obj
 
 
-def _FlagNames(a: argparse.Action, /) -> list[str]:
-  # Positional args have empty 'option_strings'; otherwise use them (e.g., ['-v','--verbose'])
-  if a.option_strings:
-    return list(a.option_strings)
-  if a.nargs:
-    if isinstance(a.metavar, str) and a.metavar:
-      # e.g., nargs=2, metavar='FILE'
-      return [a.metavar]
-    if isinstance(a.metavar, tuple):
-      # e.g., nargs=2, metavar=('FILE1', 'FILE2')
-      return list(a.metavar)
-  # Otherwise, it’s a positional arg with no flags, so return the destination name
-  return [a.dest]
-
-
-def _ActionIsSubparser(a: argparse.Action, /) -> bool:
-  return isinstance(a, argparse._SubParsersAction)  # type: ignore[attr-defined]  # pylint: disable=protected-access
-
-
-def _FormatDefault(a: argparse.Action, /) -> str:
-  if a.default is argparse.SUPPRESS:
-    return ''
-  if isinstance(a.default, bool):
-    return ' (default: on)' if a.default else ''
-  if a.default in (None, '', 0, False):
-    return ''
-  return f' (default: {a.default})'
-
-
-def _FormatChoices(a: argparse.Action, /) -> str:
-  return f' choices: {list(a.choices)}' if getattr(a, 'choices', None) else ''  # type:ignore
-
-
-def _FormatType(a: argparse.Action, /) -> str:
-  t: Any | None = getattr(a, 'type', None)
-  if t is None:
-    return ''
-  # Show clean type names (int, str, float); for callables, just say 'custom'
-  return f' type: {t.__name__ if hasattr(t, "__name__") else "custom"}'
-
-
-def _FormatNArgs(a: argparse.Action, /) -> str:
-  return f' nargs: {a.nargs}' if getattr(a, 'nargs', None) not in (None, 0) else ''
-
-
-def _RowsForActions(actions: Sequence[argparse.Action], /) -> list[tuple[str, str]]:
-  rows: list[tuple[str, str]] = []
-  for a in actions:
-    if _ActionIsSubparser(a):
-      continue
-    # skip the built-in help action; it’s implied
-    if getattr(a, 'help', '') == argparse.SUPPRESS or isinstance(a, argparse._HelpAction):  # type: ignore[attr-defined]  # pylint: disable=protected-access
-      continue
-    flags: str = ', '.join(_FlagNames(a))
-    meta: str = ''.join(
-        (_FormatType(a), _FormatNArgs(a), _FormatChoices(a), _FormatDefault(a))).strip()
-    desc: str = (a.help or '').strip()
-    if meta:
-      desc = f'{desc} [{meta}]' if desc else f'[{meta}]'
-    rows.append((flags, desc))
-  return rows
-
-
-def _MarkdownTable(
-    rows: Sequence[tuple[str, str]],
-    headers: tuple[str, str] = ('Option/Arg', 'Description'), /) -> str:
-  if not rows:
-    return ''
-  out: list[str] = ['| ' + headers[0] + ' | ' + headers[1] + ' |', '|---|---|']
-  for left, right in rows:
-    out.append(f'| `{left}` | {right} |')
-  return '\n'.join(out)
-
-
-def _WalkSubcommands(
-    parser: argparse.ArgumentParser, path: list[str] | None = None, /) -> list[
-    tuple[list[str], argparse.ArgumentParser, Any]]:
-  path = path or []
-  items: list[tuple[list[str], argparse.ArgumentParser, Any]] = []
-  # sub_action = None
-  name: str
-  sp: argparse.ArgumentParser
-  for action in parser._actions:  # type: ignore[attr-defined]  # pylint: disable=protected-access
-    if _ActionIsSubparser(action):
-      # sub_action = a  # type: ignore[assignment]
-      for name, sp in action.choices.items():              # type:ignore
-        items.append((path + [name], sp, action))          # type:ignore
-        items.extend(_WalkSubcommands(sp, path + [name]))  # type:ignore
-  return items
-
-
-def _HelpText(sub_parser: argparse.ArgumentParser, parent_sub_action: Any, /) -> str:
-  if parent_sub_action is not None:
-    for choice_action in parent_sub_action._choices_actions:  # type: ignore  # pylint: disable=protected-access
-      if choice_action.dest == sub_parser.prog.split()[-1]:
-        return choice_action.help or ''
-  return ''
-
-
-def _GenerateCLIMarkdown() -> str:  # pylint: disable=too-many-locals
-  """Return a Markdown doc section that reflects the current _BuildParser() tree.
-
-  Will treat epilog strings as examples, splitting on '$$' to get multiple examples.
-  """
-  parser: argparse.ArgumentParser = _BuildParser()
-  assert parser.prog == 'poetry run transcrypto', 'should never happen: module name changed?'
-  prog: str = 'transcrypto'  # no '.py' needed because poetry run has an alias
-  lines: list[str] = ['']
-  # Header + global flags
-  lines.append('## Command-Line Interface\n')
-  lines.append(
-      f'`{prog}` is a command-line utility that provides access to all core functionality '
-      'described in this documentation. It serves as a convenient wrapper over the Python APIs, '
-      'enabling **cryptographic operations**, **number theory functions**, **secure randomness '
-      'generation**, **hashing**, **AES**, **RSA**, **El-Gamal**, **DSA**, **bidding**, **SSS**, '
-      'and other utilities without writing code.\n')
-  lines.append('Invoke with:\n')
-  lines.append('```bash')
-  lines.append(f'poetry run {prog} <command> [sub-command] [options...]')
-  lines.append('```\n')
-  # Global options table
-  global_rows: list[tuple[str, str]] = _RowsForActions(parser._actions)  # type: ignore[attr-defined]  # pylint: disable=protected-access
-  if global_rows:
-    lines.append('### Global Options\n')
-    lines.append(_MarkdownTable(global_rows))
-    lines.append('')
-  # Top-level commands summary
-  lines.append('### Top-Level Commands\n')
-  # Find top-level subparsers to list available commands
-  top_subs: list[argparse.Action] = [a for a in parser._actions if _ActionIsSubparser(a)]  # type: ignore[attr-defined]  # pylint: disable=protected-access
-  for action in top_subs:
-    for name, sp in action.choices.items():  # type: ignore[union-attr]
-      help_text: str = (sp.description or ' '.join(i.strip() for i in sp.format_usage().splitlines())).strip()  # type:ignore
-      short: str = (sp.help if hasattr(sp, 'help') else '') or ''  # type:ignore
-      help_text = short or help_text                               # type:ignore
-      help_text = help_text.replace('usage: ', '').strip()  # type:ignore
-      lines.append(f'- **`{name}`** — `{help_text}`')
-  lines.append('')
-  if parser.epilog:
-    lines.append('```bash')
-    lines.append(parser.epilog)
-    lines.append('```\n')
-  # Detailed sections per (sub)command
-  for path, sub_parser, parent_sub_action in _WalkSubcommands(parser):
-    if len(path) == 1:
-      lines.append('---\n')  # horizontal rule between top-level commands
-    header: str = ' '.join(path)
-    lines.append(f'###{"" if len(path) == 1 else "#"} `{header}`')  # (header level 3 or 4)
-    # Usage block
-    help_text = _HelpText(sub_parser, parent_sub_action)
-    if help_text:
-      lines.append(f'\n{help_text}')
-    usage: str = sub_parser.format_usage().replace('usage: ', '').strip()
-    lines.append('\n```bash')
-    lines.append(str(usage))
-    lines.append('```\n')
-    # Options/args table
-    rows: list[tuple[str, str]] = _RowsForActions(sub_parser._actions)  # type: ignore[attr-defined]  # pylint: disable=protected-access
-    if rows:
-      lines.append(_MarkdownTable(rows))
-      lines.append('')
-    # Examples (if any) - stored in epilog argument
-    epilog: str = sub_parser.epilog.strip() if sub_parser.epilog else ''
-    if epilog:
-      lines.append('**Example:**\n')
-      lines.append('```bash')
-      for epilog_line in epilog.split('$$'):
-        lines.append(f'$ poetry run {prog} {epilog_line.strip()}')
-      lines.append('```\n')
-  # join all lines as the markdown string
-  return '\n'.join(lines)
-
-
 def _BuildParser() -> argparse.ArgumentParser:  # pylint: disable=too-many-statements,too-many-locals
   """Construct the CLI argument parser (kept in sync with the docs)."""
   # ========================= main parser ==========================================================
@@ -321,12 +150,12 @@ def _BuildParser() -> argparse.ArgumentParser:  # pylint: disable=too-many-state
           '  poetry run transcrypto mod crt 6 7 127 13\n\n'
           '  # --- Hashing ---\n'
           '  poetry run transcrypto hash sha256 xyz\n'
-          '  poetry run transcrypto --b64 hash sha512 eHl6\n'
+          '  poetry run transcrypto --b64 hash sha512 -- eHl6\n'
           '  poetry run transcrypto hash file /etc/passwd --digest sha512\n\n'
           '  # --- AES ---\n'
           '  poetry run transcrypto --out-b64 aes key "correct horse battery staple"\n'
-          '  poetry run transcrypto --b64 --out-b64 aes encrypt -k "<b64key>" "secret"\n'
-          '  poetry run transcrypto --b64 --out-b64 aes decrypt -k "<b64key>" "<ciphertext>"\n'
+          '  poetry run transcrypto --b64 --out-b64 aes encrypt -k "<b64key>" -- "secret"\n'
+          '  poetry run transcrypto --b64 --out-b64 aes decrypt -k "<b64key>" -- "<ciphertext>"\n'
           '  poetry run transcrypto aes ecb -k "<b64key>" encrypt "<128bithexblock>"\n'    # cspell:disable-line
           '  poetry run transcrypto aes ecb -k "<b64key>" decrypt "<128bithexblock>"\n\n'  # cspell:disable-line
           '  # --- RSA ---\n'
@@ -335,6 +164,10 @@ def _BuildParser() -> argparse.ArgumentParser:  # pylint: disable=too-many-state
           '  poetry run transcrypto -p rsa-key.priv rsa rawdecrypt <ciphertext>\n'
           '  poetry run transcrypto -p rsa-key.priv rsa rawsign <message>\n'
           '  poetry run transcrypto -p rsa-key.pub rsa rawverify <message> <signature>\n\n'
+          '  poetry run transcrypto --bin --out-b64 -p rsa-key.pub rsa encrypt -a <aad> <plaintext>\n'
+          '  poetry run transcrypto --b64 --out-bin -p rsa-key.priv rsa decrypt -a <aad> -- <ciphertext>\n'
+          '  poetry run transcrypto --bin --out-b64 -p rsa-key.priv rsa sign <message>\n'
+          '  poetry run transcrypto --b64 -p rsa-key.pub rsa verify -- <message> <signature>\n\n'
           '  # --- ElGamal ---\n'
           '  poetry run transcrypto -p eg-key elgamal shared --bits 2048\n'
           '  poetry run transcrypto -p eg-key elgamal new\n'
@@ -342,19 +175,27 @@ def _BuildParser() -> argparse.ArgumentParser:  # pylint: disable=too-many-state
           '  poetry run transcrypto -p eg-key.priv elgamal rawdecrypt <c1:c2>\n'
           '  poetry run transcrypto -p eg-key.priv elgamal rawsign <message>\n'
           '  poetry run transcrypto-p eg-key.pub elgamal rawverify <message> <s1:s2>\n\n'
+          '  poetry run transcrypto --bin --out-b64 -p eg-key.pub elgamal encrypt <plaintext>\n'
+          '  poetry run transcrypto --b64 --out-bin -p eg-key.priv elgamal decrypt -- <ciphertext>\n'
+          '  poetry run transcrypto --bin --out-b64 -p eg-key.priv elgamal sign <message>\n'
+          '  poetry run transcrypto --b64 -p eg-key.pub elgamal verify -- <message> <signature>\n\n'
           '  # --- DSA ---\n'
           '  poetry run transcrypto -p dsa-key dsa shared --p-bits 2048 --q-bits 256\n'
           '  poetry run transcrypto -p dsa-key dsa new\n'
           '  poetry run transcrypto -p dsa-key.priv dsa rawsign <message>\n'
           '  poetry run transcrypto -p dsa-key.pub dsa rawverify <message> <s1:s2>\n\n'
+          '  poetry run transcrypto --bin --out-b64 -p dsa-key.priv dsa sign <message>\n'
+          '  poetry run transcrypto --b64 -p dsa-key.pub dsa verify -- <message> <signature>\n\n'
           '  # --- Public Bid ---\n'
           '  poetry run transcrypto --bin bid new "tomorrow it will rain"\n'
           '  poetry run transcrypto --out-bin bid verify\n\n'
           '  # --- Shamir Secret Sharing (SSS) ---\n'
           '  poetry run transcrypto -p sss-key sss new 3 --bits 1024\n'
-          '  poetry run transcrypto -p sss-key sss rawshares <secret> 5\n'
+          '  poetry run transcrypto -p sss-key sss rawshares <secret> <n>\n'
           '  poetry run transcrypto -p sss-key sss rawrecover\n'
           '  poetry run transcrypto -p sss-key sss rawverify <secret>'
+          '  poetry run transcrypto --bin -p sss-key sss shares <secret> <n>\n'
+          '  poetry run transcrypto --out-bin -p sss-key sss recover\n'
       ),
       formatter_class=argparse.RawTextHelpFormatter)
   sub = parser.add_subparsers(dest='command')
@@ -368,7 +209,10 @@ def _BuildParser() -> argparse.ArgumentParser:  # pylint: disable=too-many-state
   # --hex/--b64/--bin for input mode (default hex)
   in_grp = parser.add_mutually_exclusive_group()
   in_grp.add_argument('--hex', action='store_true', help='Treat inputs as hex string (default)')
-  in_grp.add_argument('--b64', action='store_true', help='Treat inputs as base64url')
+  in_grp.add_argument(
+      '--b64', action='store_true',
+      help=('Treat inputs as base64url; sometimes base64 will start with "-" and that can '
+            'conflict with flags, so use "--" before positional args if needed'))
   in_grp.add_argument('--bin', action='store_true', help='Treat inputs as binary (bytes)')
 
   # --out-hex/--out-b64/--out-bin for output mode (default hex)
@@ -557,7 +401,7 @@ def _BuildParser() -> argparse.ArgumentParser:  # pylint: disable=too-many-state
       help='SHA-256 of input `data`.',
       epilog=('--bin hash sha256 xyz\n'
               '3608bca1e44ea6c4d268eb6db02260269892c0b42b86bbf1e77a6fa16c3c9282 $$'
-              '--b64 hash sha256 eHl6  # "xyz" in base-64\n'
+              '--b64 hash sha256 -- eHl6  # "xyz" in base-64\n'
               '3608bca1e44ea6c4d268eb6db02260269892c0b42b86bbf1e77a6fa16c3c9282'))
   p_h256.add_argument('data', type=str, help='Input data (raw text; or use --hex/--b64/--bin)')
 
@@ -568,7 +412,7 @@ def _BuildParser() -> argparse.ArgumentParser:  # pylint: disable=too-many-state
       epilog=('--bin hash sha512 xyz\n'
               '4a3ed8147e37876adc8f76328e5abcc1b470e6acfc18efea0135f983604953a5'
               '8e183c1a6086e91ba3e821d926f5fdeb37761c7ca0328a963f5e92870675b728 $$'
-              '--b64 hash sha512 eHl6  # "xyz" in base-64\n'
+              '--b64 hash sha512 -- eHl6  # "xyz" in base-64\n'
               '4a3ed8147e37876adc8f76328e5abcc1b470e6acfc18efea0135f983604953a5'
               '8e183c1a6086e91ba3e821d926f5fdeb37761c7ca0328a963f5e92870675b728'))
   p_h512.add_argument('data', type=str, help='Input data (raw text; or use --hex/--b64/--bin)')
@@ -614,10 +458,10 @@ def _BuildParser() -> argparse.ArgumentParser:  # pylint: disable=too-many-state
             'can use `--bin`/`--hex`/`--b64` flags. Attention: if you provide `-a`/`--aad` '
             '(associated data, AAD), you will need to provide the same AAD when decrypting '
             'and it is NOT included in the `ciphertext`/CT returned by this method!'),
-      epilog=('--b64 --out-b64 aes encrypt -k DbWJ_ZrknLEEIoq_NpoCQwHYfjskGokpueN2O_eY0es= '          # cspell:disable-line
+      epilog=('--b64 --out-b64 aes encrypt -k DbWJ_ZrknLEEIoq_NpoCQwHYfjskGokpueN2O_eY0es= -- '       # cspell:disable-line
               'AAAAAAB4eXo=\nF2_ZLrUw5Y8oDnbTP5t5xCUWX8WtVILLD0teyUi_37_4KHeV-YowVA== $$ '            # cspell:disable-line
               '--b64 --out-b64 aes encrypt -k DbWJ_ZrknLEEIoq_NpoCQwHYfjskGokpueN2O_eY0es= -a eHl6 '  # cspell:disable-line
-              'AAAAAAB4eXo=\nxOlAHPUPpeyZHId-f3VQ_QKKMxjIW0_FBo9WOfIBrzjn0VkVV6xTRA=='))              # cspell:disable-line
+              '-- AAAAAAB4eXo=\nxOlAHPUPpeyZHId-f3VQ_QKKMxjIW0_FBo9WOfIBrzjn0VkVV6xTRA=='))           # cspell:disable-line
   p_aes_enc.add_argument('plaintext', type=str, help='Input data to encrypt (PT)')
   p_aes_enc.add_argument(
       '-k', '--key', type=str, default='', help='Key if `-p`/`--key-path` wasn\'t used (32 bytes)')
@@ -632,10 +476,10 @@ def _BuildParser() -> argparse.ArgumentParser:  # pylint: disable=too-many-state
             '`-p`/`--key-path` keyfile. All inputs are raw, or you '
             'can use `--bin`/`--hex`/`--b64` flags. Attention: if you provided `-a`/`--aad` '
             '(associated data, AAD) during encryption, you will need to provide the same AAD now!'),
-      epilog=('--b64 --out-b64 aes decrypt -k DbWJ_ZrknLEEIoq_NpoCQwHYfjskGokpueN2O_eY0es= '      # cspell:disable-line
-              'F2_ZLrUw5Y8oDnbTP5t5xCUWX8WtVILLD0teyUi_37_4KHeV-YowVA==\nAAAAAAB4eXo= $$ '        # cspell:disable-line
-              '--b64 --out-b64 aes decrypt -k DbWJ_ZrknLEEIoq_NpoCQwHYfjskGokpueN2O_eY0es= '      # cspell:disable-line
-              '-a eHl6 xOlAHPUPpeyZHId-f3VQ_QKKMxjIW0_FBo9WOfIBrzjn0VkVV6xTRA==\nAAAAAAB4eXo='))  # cspell:disable-line
+      epilog=('--b64 --out-b64 aes decrypt -k DbWJ_ZrknLEEIoq_NpoCQwHYfjskGokpueN2O_eY0es= -- '      # cspell:disable-line
+              'F2_ZLrUw5Y8oDnbTP5t5xCUWX8WtVILLD0teyUi_37_4KHeV-YowVA==\nAAAAAAB4eXo= $$ '           # cspell:disable-line
+              '--b64 --out-b64 aes decrypt -k DbWJ_ZrknLEEIoq_NpoCQwHYfjskGokpueN2O_eY0es= '         # cspell:disable-line
+              '-a eHl6 -- xOlAHPUPpeyZHId-f3VQ_QKKMxjIW0_FBo9WOfIBrzjn0VkVV6xTRA==\nAAAAAAB4eXo='))  # cspell:disable-line
   p_aes_dec.add_argument('ciphertext', type=str, help='Input data to decrypt (CT)')
   p_aes_dec.add_argument(
       '-k', '--key', type=str, default='', help='Key if `-p`/`--key-path` wasn\'t used (32 bytes)')
@@ -724,8 +568,8 @@ def _BuildParser() -> argparse.ArgumentParser:  # pylint: disable=too-many-state
   p_rsa_dec_safe: argparse.ArgumentParser = rsa_sub.add_parser(
       'decrypt',
       help='Decrypt `ciphertext` with private key.',
-      epilog=('--b64 --out-bin -p rsa-key.priv rsa decrypt "AO6knI6xwq6TGR…Qy22jiFhXi1eQ==" '
-              '-a "eHl6"\nabcde'))
+      epilog=('--b64 --out-bin -p rsa-key.priv rsa decrypt -a eHl6 -- '
+              'AO6knI6xwq6TGR…Qy22jiFhXi1eQ==\nabcde'))
   p_rsa_dec_safe.add_argument('ciphertext', type=str, help='Ciphertext to decrypt')
   p_rsa_dec_safe.add_argument(
       '-a', '--aad', type=str, default='',
@@ -763,10 +607,10 @@ def _BuildParser() -> argparse.ArgumentParser:  # pylint: disable=too-many-state
   p_rsa_ver_safe: argparse.ArgumentParser = rsa_sub.add_parser(
       'verify',
       help='Verify `signature` for `message` with public key.',
-      epilog=('--b64 -p rsa-key.pub rsa verify "eHl6" '
-              '"91TS7gC6LORiL…6RD23Aejsfxlw=="\nRSA signature: OK $$ '     # cspell:disable-line
-              '--b64 -p rsa-key.pub rsa verify "eLl6" '
-              '"91TS7gC6LORiL…6RD23Aejsfxlw=="\nRSA signature: INVALID'))  # cspell:disable-line
+      epilog=('--b64 -p rsa-key.pub rsa verify -- eHl6 '
+              '91TS7gC6LORiL…6RD23Aejsfxlw==\nRSA signature: OK $$ '     # cspell:disable-line
+              '--b64 -p rsa-key.pub rsa verify -- eLl6 '
+              '91TS7gC6LORiL…6RD23Aejsfxlw==\nRSA signature: INVALID'))  # cspell:disable-line
   p_rsa_ver_safe.add_argument('message', type=str, help='Message that was signed earlier')
   p_rsa_ver_safe.add_argument('signature', type=str, help='Putative signature for `message`')
   p_rsa_ver_safe.add_argument(
@@ -814,7 +658,7 @@ def _BuildParser() -> argparse.ArgumentParser:  # pylint: disable=too-many-state
   p_eg_enc_safe: argparse.ArgumentParser = eg_sub.add_parser(
       'encrypt',
       help='Encrypt `message` with public key.',
-      epilog=(' --bin --out-b64 -p eg-key.pub elgamal encrypt "abcde" -a "xyz"\n'
+      epilog=('--bin --out-b64 -p eg-key.pub elgamal encrypt "abcde" -a "xyz"\n'
               'CdFvoQ_IIPFPZLua…kqjhcUTspISxURg=='))  # cspell:disable-line
   p_eg_enc_safe.add_argument('plaintext', type=str, help='Message to encrypt')
   p_eg_enc_safe.add_argument(
@@ -834,8 +678,8 @@ def _BuildParser() -> argparse.ArgumentParser:  # pylint: disable=too-many-state
   p_eg_dec_safe: argparse.ArgumentParser = eg_sub.add_parser(
       'decrypt',
       help='Decrypt `ciphertext` with private key.',
-      epilog=('--b64 --out-bin -p eg-key.priv elgamal decrypt '
-              '"CdFvoQ_IIPFPZLua…kqjhcUTspISxURg==" -a "eHl6"\nabcde'))  # cspell:disable-line
+      epilog=('--b64 --out-bin -p eg-key.priv elgamal decrypt -a eHl6 -- '
+              'CdFvoQ_IIPFPZLua…kqjhcUTspISxURg==\nabcde'))  # cspell:disable-line
   p_eg_dec_safe.add_argument('ciphertext', type=str, help='Ciphertext to decrypt')
   p_eg_dec_safe.add_argument(
       '-a', '--aad', type=str, default='',
@@ -877,9 +721,9 @@ def _BuildParser() -> argparse.ArgumentParser:  # pylint: disable=too-many-state
   p_eg_ver_safe: argparse.ArgumentParser = eg_sub.add_parser(
       'verify',
       help='Verify `signature` for `message` with public key.',
-      epilog=('--b64 -p eg-key.pub elgamal verify "eHl6" "Xl4hlYK8SHVGw…0fCKJE1XVzA=="\n'  # cspell:disable-line
+      epilog=('--b64 -p eg-key.pub elgamal verify -- eHl6 Xl4hlYK8SHVGw…0fCKJE1XVzA==\n'  # cspell:disable-line
               'El-Gamal signature: OK $$ '
-              '--b64 -p eg-key.pub elgamal verify "eLl6" "Xl4hlYK8SHVGw…0fCKJE1XVzA=="\n'  # cspell:disable-line
+              '--b64 -p eg-key.pub elgamal verify -- eLl6 Xl4hlYK8SHVGw…0fCKJE1XVzA==\n'  # cspell:disable-line
               'El-Gamal signature: INVALID'))
   p_eg_ver_safe.add_argument('message', type=str, help='Message that was signed earlier')
   p_eg_ver_safe.add_argument('signature', type=str, help='Putative signature for `message`')
@@ -956,9 +800,9 @@ def _BuildParser() -> argparse.ArgumentParser:  # pylint: disable=too-many-state
   p_dsa_verify_safe: argparse.ArgumentParser = dsa_sub.add_parser(
       'verify',
       help='Verify `signature` for `message` with public key.',
-      epilog=('--b64 -p dsa-key.pub dsa verify "eHl6" "yq8InJVpViXh9…BD4par2XuA="\n'
+      epilog=('--b64 -p dsa-key.pub dsa verify -- eHl6 yq8InJVpViXh9…BD4par2XuA=\n'
               'DSA signature: OK $$ '
-              '--b64 -p dsa-key.pub dsa verify "eLl6" "yq8InJVpViXh9…BD4par2XuA="\n'
+              '--b64 -p dsa-key.pub dsa verify -- eLl6 yq8InJVpViXh9…BD4par2XuA=\n'
               'DSA signature: INVALID'))
   p_dsa_verify_safe.add_argument('message', type=str, help='Message that was signed earlier')
   p_dsa_verify_safe.add_argument('signature', type=str, help='Putative signature for `message`')
@@ -1094,9 +938,7 @@ def _BuildParser() -> argparse.ArgumentParser:  # pylint: disable=too-many-state
   doc_sub.add_parser(
       'md',
       help='Emit Markdown docs for the CLI (see README.md section "Creating a New Version").',
-      epilog=('doc md > CLI.md\n'
-              '$ ./tools/inject_md_includes.py\n'
-              'inject: README.md updated with included content'))
+      epilog='doc md > transcrypto.md\n<<saves file>>')
 
   return parser
 
@@ -1544,7 +1386,7 @@ def main(argv: list[str] | None = None, /) -> int:  # pylint: disable=invalid-na
           case 'bytes':
             print(base.BytesToHex(base.RandBytes(args.n)))
           case 'prime':
-            print(modmath.NBitRandomPrime(args.bits))
+            print(modmath.NBitRandomPrimes(args.bits).pop())
           case _:
             raise NotImplementedError()
       case 'hash':
@@ -1589,7 +1431,14 @@ def main(argv: list[str] | None = None, /) -> int:  # pylint: disable=invalid-na
             args.doc_command.lower().strip() if getattr(args, 'doc_command', '') else '')
         match doc_command:
           case 'md':
-            print(_GenerateCLIMarkdown())
+            print(base.GenerateCLIMarkdown(
+                'transcrypto', _BuildParser(), description=(
+                    '`transcrypto` is a command-line utility that provides access to all core '
+                    'functionality described in this documentation. It serves as a convenient '
+                    'wrapper over the Python APIs, enabling **cryptographic operations**, '
+                    '**number theory functions**, **secure randomness generation**, **hashing**, '
+                    '**AES**, **RSA**, **El-Gamal**, **DSA**, **bidding**, **SSS**, '
+                    'and other utilities without writing code.')))
           case _:
             raise NotImplementedError()