transcrypto 2.3.2__tar.gz → 2.5.0__tar.gz

{transcrypto-2.3.2 → transcrypto-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: transcrypto
-Version: 2.3.2
+Version: 2.5.0
 Summary: Basic crypto primitives, not intended for actual use, but as a companion to --Criptografia, Métodos e Algoritmos--
 License-Expression: Apache-2.0
 License-File: LICENSE
@@ -19,7 +19,7 @@ Requires-Dist: cryptography (>=46.0)
 Requires-Dist: gmpy2 (>=2.3)
 Requires-Dist: platformdirs (>=4.9)
 Requires-Dist: rich (>=14.3.3)
-Requires-Dist: typer (>=0.24)
+Requires-Dist: typer (>=0.24.1)
 Requires-Dist: zstandard (>=0.25)
 Project-URL: Changelog, https://github.com/balparda/transcrypto/blob/main/CHANGELOG.md
 Project-URL: Homepage, https://github.com/balparda/transcrypto
@@ -107,6 +107,7 @@ All that being said, extreme care was taken that this is a good library with a s
 ## CLI Apps
 
 - [TransCrypto/`transcrypto`](transcrypto.md): Does all the operations but allows you to shoot yourself in the foot;
+- [SafeTrans/`safetrans`](safetrans.md): Safer CLI version, if you want to actually use it for security, no raw operations, better defined interface;
 - [Profiler/`profiler`](profiler.md): Measure transcrypto performance.
 
 ## Programming API

{transcrypto-2.3.2 → transcrypto-2.5.0}/README.md

@@ -77,6 +77,7 @@ All that being said, extreme care was taken that this is a good library with a s
 ## CLI Apps
 
 - [TransCrypto/`transcrypto`](transcrypto.md): Does all the operations but allows you to shoot yourself in the foot;
+- [SafeTrans/`safetrans`](safetrans.md): Safer CLI version, if you want to actually use it for security, no raw operations, better defined interface;
 - [Profiler/`profiler`](profiler.md): Measure transcrypto performance.
 
 ## Programming API

{transcrypto-2.3.2 → transcrypto-2.5.0}/pyproject.toml

@@ -12,7 +12,7 @@ build-backend = "poetry.core.masonry.api"
 [project]
 
 name = "transcrypto"
-version = "2.3.2"  # also update src/transcrypto/__init__.py
+version = "2.5.0"  # also update src/transcrypto/__init__.py
 
 description = "Basic crypto primitives, not intended for actual use, but as a companion to --Criptografia, Métodos e Algoritmos--"
 license = "Apache-2.0"
@@ -59,7 +59,7 @@ license-files = [ "LICENSE" ]
 
 dependencies = [
 
-  "typer>=0.24",   # if this changes, also change: [tool.poetry.dependencies]
+  "typer>=0.24.1",   # if this changes, also change: [tool.poetry.dependencies]
   "rich>=14.3.3",  # 14.3.2 hangs GitHub CI pipeline
   "platformdirs>=4.9",
 
@@ -79,6 +79,7 @@ dependencies = [
 # if you change/add a line here also edit [tool.poetry.scripts] below and re-run `poetry sync`
 
 transcrypto = "transcrypto.transcrypto:Run"
+safetrans = "transcrypto.safetrans:Run"
 profiler = "transcrypto.profiler:Run"
 
 ####################################################################################################
@@ -88,6 +89,7 @@ profiler = "transcrypto.profiler:Run"
 # keep this in sync with [project.scripts] above
 
 transcrypto = "transcrypto.transcrypto:Run"
+safetrans = "transcrypto.safetrans:Run"
 profiler = "transcrypto.profiler:Run"
 
 ####################################################################################################
@@ -122,10 +124,10 @@ typer = { version = "^0.24", extras = ["all"] }
 [tool.poetry.group.dev.dependencies]
 
 # basic, all projects should have
-ruff = "~0.15.2"
-mypy = "~1.19.1"
+ruff = "^0.15.9"
+mypy = "^1.20"
 pytest = "^9.0"
-pytest-cov = "^7.0"
+pytest-cov = "^7.1"
 pytest-flakefinder = "^1.1"
 pyright = "^1.1"
 pre-commit = "^4.5"

{transcrypto-2.3.2 → transcrypto-2.5.0}/src/transcrypto/__init__.py

@@ -3,5 +3,5 @@
 """Basic cryptography primitives implementation."""
 
 __all__: list[str] = ['__author__', '__version__']
-__version__ = '2.3.2'  # remember to also update pyproject.toml
+__version__ = '2.5.0'  # remember to also update pyproject.toml
 __author__ = 'Daniel Balparda <balparda@github.com>'

transcrypto-2.5.0/src/transcrypto/cli/safeaeshash.py

@@ -0,0 +1,258 @@
+# SPDX-FileCopyrightText: Copyright 2026 Daniel Balparda <balparda@github.com>
+# SPDX-License-Identifier: Apache-2.0
+"""Balparda's TransCrypto safe CLI: AES and Hash commands."""
+
+from __future__ import annotations
+
+import pathlib
+import re
+
+import click
+import typer
+
+from transcrypto import safetrans
+from transcrypto.cli import clibase
+from transcrypto.core import aes, hashes
+from transcrypto.utils import base
+
+_HEX_RE = re.compile(r'^[0-9a-fA-F]+$')
+
+# =================================== "HASH" COMMAND ===============================================
+
+
+hash_app = typer.Typer(
+  no_args_is_help=True,
+  help='Cryptographic Hashing (SHA-256 / SHA-512 / file).',
+)
+safetrans.app.add_typer(hash_app, name='hash')
+
+
+@hash_app.command(
+  'sha256',
+  help='SHA-256 of input `data`.',
+  epilog=(
+    'Example:\n\n\n\n'
+    '$ poetry run safetrans -i bin hash sha256 xyz\n\n'
+    '3608bca1e44ea6c4d268eb6db02260269892c0b42b86bbf1e77a6fa16c3c9282\n\n'
+    '$ poetry run safetrans -i b64 hash sha256 -- eHl6  # "xyz" in base-64\n\n'
+    '3608bca1e44ea6c4d268eb6db02260269892c0b42b86bbf1e77a6fa16c3c9282'
+  ),
+)
+@clibase.CLIErrorGuard
+def Hash256(  # documentation is help/epilog/args # noqa: D103
+  *,
+  ctx: click.Context,
+  data: str = typer.Argument(..., help='Input data (raw text; or `--input-format <hex|b64|bin>`)'),
+) -> None:
+  config: safetrans.TransConfig = ctx.obj
+  bt: bytes = safetrans.BytesFromText(data, config.input_format)
+  config.console.print(safetrans.BytesToText(hashes.Hash256(bt), config.output_format))
+
+
+@hash_app.command(
+  'sha512',
+  help='SHA-512 of input `data`.',
+  epilog=(
+    'Example:\n\n\n\n'
+    '$ poetry run safetrans -i bin hash sha512 xyz\n\n'
+    '4a3ed8147e37876adc8f76328e5abcc1b470e6acfc18efea0135f983604953a5'
+    '8e183c1a6086e91ba3e821d926f5fdeb37761c7ca0328a963f5e92870675b728\n\n'
+    '$ poetry run safetrans -i b64 hash sha512 -- eHl6  # "xyz" in base-64\n\n'
+    '4a3ed8147e37876adc8f76328e5abcc1b470e6acfc18efea0135f983604953a5'
+    '8e183c1a6086e91ba3e821d926f5fdeb37761c7ca0328a963f5e92870675b728'
+  ),
+)
+@clibase.CLIErrorGuard
+def Hash512(  # documentation is help/epilog/args # noqa: D103
+  *,
+  ctx: click.Context,
+  data: str = typer.Argument(..., help='Input data (raw text; or `--input-format <hex|b64|bin>`)'),
+) -> None:
+  config: safetrans.TransConfig = ctx.obj
+  bt: bytes = safetrans.BytesFromText(data, config.input_format)
+  config.console.print(safetrans.BytesToText(hashes.Hash512(bt), config.output_format))
+
+
+@hash_app.command(
+  'file',
+  help='SHA-256/512 hash of file contents, defaulting to SHA-256.',
+  epilog=(
+    'Example:\n\n\n\n'
+    '$ poetry run safetrans hash file /etc/passwd --digest sha512\n\n'
+    '8966f5953e79f55dfe34d3dc5b160ac4a4a3f9cbd1c36695a54e28d77c7874df'
+    'f8595502f8a420608911b87d336d9e83c890f0e7ec11a76cb10b03e757f78aea'
+  ),
+)
+@clibase.CLIErrorGuard
+def HashFile(  # documentation is help/epilog/args # noqa: D103
+  *,
+  ctx: click.Context,
+  path: pathlib.Path = typer.Argument(  # noqa: B008
+    ...,
+    exists=True,
+    file_okay=True,
+    dir_okay=False,
+    readable=True,
+    resolve_path=True,
+    help='Path to existing file',
+  ),
+  digest: str = typer.Option(
+    'sha256',
+    '-d',
+    '--digest',
+    click_type=click.Choice(['sha256', 'sha512'], case_sensitive=False),
+    help='Digest type, SHA-256 ("sha256") or SHA-512 ("sha512")',
+  ),
+) -> None:
+  config: safetrans.TransConfig = ctx.obj
+  config.console.print(
+    safetrans.BytesToText(hashes.FileHash(str(path), digest=digest), config.output_format)
+  )
+
+
+# =================================== "AES" COMMAND ================================================
+
+
+aes_app = typer.Typer(
+  no_args_is_help=True,
+  help=(
+    'AES-256 operations (GCM/ECB) and key derivation. '
+    'No measures are taken here to prevent timing attacks.'
+  ),
+)
+safetrans.app.add_typer(aes_app, name='aes')
+
+
+@aes_app.command(
+  'key',
+  help=(
+    'Derive key from a password (PBKDF2-HMAC-SHA256) with custom expensive '
+    'salt and iterations. Very good/safe for simple password-to-key but not for '
+    'passwords databases (because of constant salt).'
+  ),
+  epilog=(
+    'Example:\n\n\n\n'
+    '$ poetry run safetrans -o b64 aes key "correct horse battery staple"\n\n'
+    'DbWJ_ZrknLEEIoq_NpoCQwHYfjskGokpueN2O_eY0es=\n\n'  # cspell:disable-line
+    '$ poetry run safetrans -p keyfile.out --protect hunter aes key '
+    '"correct horse battery staple"\n\n'
+    "AES key saved to 'keyfile.out'"
+  ),
+)
+@clibase.CLIErrorGuard
+def AESKeyFromPass(  # documentation is help/epilog/args # noqa: D103
+  *,
+  ctx: click.Context,
+  password: str = typer.Argument(..., help='Password (leading/trailing spaces ignored)'),
+) -> None:
+  config: safetrans.TransConfig = ctx.obj
+  aes_key: aes.AESKey = aes.AESKey.FromStaticPassword(password)
+  if config.key_path is not None:
+    safetrans.SaveObj(aes_key, str(config.key_path), config.protect)
+    config.console.print(f'AES key saved to {str(config.key_path)!r}')
+  else:
+    config.console.print(safetrans.BytesToText(aes_key.key256, config.output_format))
+
+
+@aes_app.command(
+  'encrypt',
+  help=(
+    'AES-256-GCM: safely encrypt `plaintext` with `-k`/`--key` or with '
+    '`-p`/`--key-path` keyfile. All inputs are raw, or you '
+    'can use `--input-format <hex|b64|bin>`. 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=(
+    'Example:\n\n\n\n'
+    '$ poetry run safetrans -i b64 -o b64 aes encrypt -k '
+    'DbWJ_ZrknLEEIoq_NpoCQwHYfjskGokpueN2O_eY0es= -- AAAAAAB4eXo=\n\n'  # cspell:disable-line
+    'F2_ZLrUw5Y8oDnbTP5t5xCUWX8WtVILLD0teyUi_37_4KHeV-YowVA==\n\n'  # cspell:disable-line
+    '$ poetry run safetrans -i b64 -o b64 aes encrypt -k '
+    'DbWJ_ZrknLEEIoq_NpoCQwHYfjskGokpueN2O_eY0es= -a eHl6 -- AAAAAAB4eXo=\n\n'  # cspell:disable-line
+    'xOlAHPUPpeyZHId-f3VQ_QKKMxjIW0_FBo9WOfIBrzjn0VkVV6xTRA=='  # cspell:disable-line
+  ),
+)
+@clibase.CLIErrorGuard
+def AESEncrypt(  # documentation is help/epilog/args # noqa: D103
+  *,
+  ctx: click.Context,
+  plaintext: str = typer.Argument(..., help='Input data to encrypt (PT)'),
+  key: str | None = typer.Option(
+    None, '-k', '--key', help="Key if `-p`/`--key-path` wasn't used (32 bytes)"
+  ),
+  aad: str = typer.Option(
+    '',
+    '-a',
+    '--aad',
+    help='Associated data (optional; has to be separately sent to receiver/stored)',
+  ),
+) -> None:
+  config: safetrans.TransConfig = ctx.obj
+  aes_key: aes.AESKey
+  if key:
+    key_bytes: bytes = safetrans.BytesFromText(key, config.input_format)
+    if len(key_bytes) != 32:  # noqa: PLR2004
+      raise base.InputError(f'invalid AES key size: {len(key_bytes)} bytes (expected 32)')
+    aes_key = aes.AESKey(key256=key_bytes)
+  elif config.key_path is not None:
+    aes_key = safetrans.LoadObj(str(config.key_path), config.protect, aes.AESKey)
+  else:
+    raise base.InputError('provide -k/--key or -p/--key-path')
+  aad_bytes: bytes | None = safetrans.BytesFromText(aad, config.input_format) if aad else None
+  pt: bytes = safetrans.BytesFromText(plaintext, config.input_format)
+  ct: bytes = aes_key.Encrypt(pt, associated_data=aad_bytes)
+  config.console.print(safetrans.BytesToText(ct, config.output_format))
+
+
+@aes_app.command(
+  'decrypt',
+  help=(
+    'AES-256-GCM: safely decrypt `ciphertext` with `-k`/`--key` or with '
+    '`-p`/`--key-path` keyfile. All inputs are raw, or you '
+    'can use `--input-format <hex|b64|bin>`. Attention: if you provided `-a`/`--aad` '
+    '(associated data, AAD) during encryption, you will need to provide the same AAD now!'
+  ),
+  epilog=(
+    'Example:\n\n\n\n'
+    '$ poetry run safetrans -i b64 -o b64 aes decrypt -k '
+    'DbWJ_ZrknLEEIoq_NpoCQwHYfjskGokpueN2O_eY0es= -- '  # cspell:disable-line
+    'F2_ZLrUw5Y8oDnbTP5t5xCUWX8WtVILLD0teyUi_37_4KHeV-YowVA==\n\n'  # cspell:disable-line
+    'AAAAAAB4eXo=\n\n'  # cspell:disable-line
+    '$ poetry run safetrans -i b64 -o b64 aes decrypt -k '
+    'DbWJ_ZrknLEEIoq_NpoCQwHYfjskGokpueN2O_eY0es= -a eHl6 -- '  # cspell:disable-line
+    'xOlAHPUPpeyZHId-f3VQ_QKKMxjIW0_FBo9WOfIBrzjn0VkVV6xTRA==\n\n'  # cspell:disable-line
+    'AAAAAAB4eXo='  # cspell:disable-line
+  ),
+)
+@clibase.CLIErrorGuard
+def AESDecrypt(  # documentation is help/epilog/args # noqa: D103
+  *,
+  ctx: click.Context,
+  ciphertext: str = typer.Argument(..., help='Input data to decrypt (CT)'),
+  key: str | None = typer.Option(
+    None, '-k', '--key', help="Key if `-p`/`--key-path` wasn't used (32 bytes)"
+  ),
+  aad: str = typer.Option(
+    '',
+    '-a',
+    '--aad',
+    help='Associated data (optional; has to be exactly the same as used during encryption)',
+  ),
+) -> None:
+  config: safetrans.TransConfig = ctx.obj
+  aes_key: aes.AESKey
+  if key:
+    key_bytes: bytes = safetrans.BytesFromText(key, config.input_format)
+    if len(key_bytes) != 32:  # noqa: PLR2004
+      raise base.InputError(f'invalid AES key size: {len(key_bytes)} bytes (expected 32)')
+    aes_key = aes.AESKey(key256=key_bytes)
+  elif config.key_path is not None:
+    aes_key = safetrans.LoadObj(str(config.key_path), config.protect, aes.AESKey)
+  else:
+    raise base.InputError('provide -k/--key or -p/--key-path')
+  # associated data, if any
+  aad_bytes: bytes | None = safetrans.BytesFromText(aad, config.input_format) if aad else None
+  ct: bytes = safetrans.BytesFromText(ciphertext, config.input_format)
+  pt: bytes = aes_key.Decrypt(ct, associated_data=aad_bytes)
+  config.console.print(safetrans.BytesToText(pt, config.output_format))

transcrypto-2.5.0/src/transcrypto/cli/safebidsecret.py

@@ -0,0 +1,220 @@
+# SPDX-FileCopyrightText: Copyright 2026 Daniel Balparda <balparda@github.com>
+# SPDX-License-Identifier: Apache-2.0
+"""Balparda's TransCrypto safe CLI: Bid secret and SSS commands."""
+
+from __future__ import annotations
+
+import glob
+
+import click
+import typer
+
+from transcrypto import safetrans
+from transcrypto.cli import clibase
+from transcrypto.core import bid, sss
+from transcrypto.utils import base
+
+# ================================== "BID" COMMAND =================================================
+
+
+bid_app = typer.Typer(
+  no_args_is_help=True,
+  help=(
+    'Bidding on a `secret` so that you can cryptographically convince a neutral '
+    'party that the `secret` that was committed to previously was not changed. '
+    'All methods require file key(s) as `-p`/`--key-path` (see provided examples). '
+    'All non-int inputs are raw, or you can use `--input-format <hex|b64|bin>`. '
+    'No measures are taken here to prevent timing attacks.'
+  ),
+)
+safetrans.app.add_typer(bid_app, name='bid')
+
+
+@bid_app.command(
+  'new',
+  help=('Generate the bid files for `secret`.'),
+  epilog=(
+    'Example:\n\n\n\n'
+    '$ poetry run safetrans -i bin -p my-bid bid new "tomorrow it will rain"\n\n'
+    "Bid private/public commitments saved to 'my-bid.priv/.pub'"
+  ),
+)
+@clibase.CLIErrorGuard
+def BidNew(  # documentation is help/epilog/args # noqa: D103
+  *,
+  ctx: click.Context,
+  secret: str = typer.Argument(..., help='Input data to bid to, the protected "secret"'),
+) -> None:
+  config: safetrans.TransConfig = ctx.obj
+  base_path: str = safetrans.RequireKeyPath(config, 'bid')
+  secret_bytes: bytes = safetrans.BytesFromText(secret, config.input_format)
+  bid_priv: bid.PrivateBid512 = bid.PrivateBid512.New(secret_bytes)
+  bid_pub: bid.PublicBid512 = bid.PublicBid512.Copy(bid_priv)
+  safetrans.SaveObj(bid_priv, base_path + '.priv', config.protect)
+  safetrans.SaveObj(bid_pub, base_path + '.pub', config.protect)
+  config.console.print(f'Bid private/public commitments saved to {base_path + ".priv/.pub"!r}')
+
+
+@bid_app.command(
+  'verify',
+  help=('Verify the bid files for correctness and reveal the `secret`.'),
+  epilog=(
+    'Example:\n\n\n\n'
+    '$ poetry run safetrans -o bin -p my-bid bid verify\n\n'
+    'Bid commitment: OK\n\n'
+    'Bid secret:\n\n'
+    'tomorrow it will rain'
+  ),
+)
+@clibase.CLIErrorGuard
+def BidVerify(*, ctx: click.Context) -> None:  # documentation is help/epilog/args # noqa: D103
+  config: safetrans.TransConfig = ctx.obj
+  base_path: str = safetrans.RequireKeyPath(config, 'bid')
+  bid_priv: bid.PrivateBid512 = safetrans.LoadObj(
+    base_path + '.priv', config.protect, bid.PrivateBid512
+  )
+  bid_pub: bid.PublicBid512 = safetrans.LoadObj(
+    base_path + '.pub', config.protect, bid.PublicBid512
+  )
+  bid_pub_expect: bid.PublicBid512 = bid.PublicBid512.Copy(bid_priv)
+  config.console.print(
+    'Bid commitment: '
+    + (
+      '[green]OK[/]'
+      if (
+        bid_pub.VerifyBid(bid_priv.private_key, bid_priv.secret_bid) and bid_pub == bid_pub_expect
+      )
+      else '[red]INVALID[/]'
+    )
+  )
+  config.console.print('Bid secret:')
+  config.console.print(safetrans.BytesToText(bid_priv.secret_bid, config.output_format))
+
+
+# ================================== "SSS" COMMAND =================================================
+
+
+sss_app = typer.Typer(
+  no_args_is_help=True,
+  help=(
+    'SSS (Shamir Shared Secret) secret sharing crypto scheme. '
+    'All methods require file key(s) as `-p`/`--key-path` (see provided examples). '
+    'All non-int inputs are raw, or you can use `--input-format <hex|b64|bin>`. '
+    'No measures are taken here to prevent timing attacks.'
+  ),
+)
+safetrans.app.add_typer(sss_app, name='sss')
+
+
+@sss_app.command(
+  'new',
+  help=(
+    'Generate the private keys with `bits` prime modulus size and so that at least a '
+    '`minimum` number of shares are needed to recover the secret. '
+    'This key will be used to generate the shares later (with the `shares` command).'
+  ),
+  epilog=(
+    'Example:\n\n\n\n'
+    '$ poetry run safetrans -p sss-key sss new 3 --bits 64  '
+    '# NEVER use such a small key: example only!\n\n'
+    "SSS private/public keys saved to 'sss-key.priv/.pub'"
+  ),
+)
+@clibase.CLIErrorGuard
+def SSSNew(  # documentation is help/epilog/args # noqa: D103
+  *,
+  ctx: click.Context,
+  minimum: int = typer.Argument(
+    ..., min=2, help='Minimum number of shares required to recover secret, ≥ 2'
+  ),
+  bits: int = typer.Option(
+    1024,
+    '-b',
+    '--bits',
+    min=16,
+    help=(
+      'Prime modulus (`p`) size in bits, ≥16; the default (1024) is a safe size ***IFF*** you '
+      'are protecting symmetric keys; the number of bits should be comfortably larger '
+      'than the size of the secret you want to protect with this scheme'
+    ),
+  ),
+) -> None:
+  config: safetrans.TransConfig = ctx.obj
+  base_path: str = safetrans.RequireKeyPath(config, 'sss')
+  sss_priv: sss.ShamirSharedSecretPrivate = sss.ShamirSharedSecretPrivate.New(minimum, bits)
+  sss_pub: sss.ShamirSharedSecretPublic = sss.ShamirSharedSecretPublic.Copy(sss_priv)
+  safetrans.SaveObj(sss_priv, base_path + '.priv', config.protect)
+  safetrans.SaveObj(sss_pub, base_path + '.pub', config.protect)
+  config.console.print(f'SSS private/public keys saved to {base_path + ".priv/.pub"!r}')
+
+
+@sss_app.command(
+  'shares',
+  help='Shares: Issue `count` private shares for a `secret`.',
+  epilog=(
+    'Example:\n\n\n\n'
+    '$ poetry run safetrans -i bin -p sss-key sss shares "abcde" 5\n\n'
+    "SSS 5 individual (private) shares saved to 'sss-key.share.1…5'\n\n"
+    '$ rm sss-key.share.2 sss-key.share.4  # this is to simulate only having shares 1,3,5'
+  ),
+)
+@clibase.CLIErrorGuard
+def SSSShares(  # documentation is help/epilog/args # noqa: D103
+  *,
+  ctx: click.Context,
+  secret: str = typer.Argument(..., help='Secret to be protected'),
+  count: int = typer.Argument(
+    ...,
+    help=(
+      'How many shares to produce; must be ≥ `minimum` used in `new` command or else the '
+      '`secret` would become unrecoverable'
+    ),
+  ),
+) -> None:
+  config: safetrans.TransConfig = ctx.obj
+  base_path: str = safetrans.RequireKeyPath(config, 'sss')
+  sss_priv: sss.ShamirSharedSecretPrivate = safetrans.LoadObj(
+    base_path + '.priv', config.protect, sss.ShamirSharedSecretPrivate
+  )
+  if count < sss_priv.minimum:
+    raise base.InputError(
+      f'count ({count}) must be >= minimum ({sss_priv.minimum}) to allow secret recovery'
+    )
+  pt: bytes = safetrans.BytesFromText(secret, config.input_format)
+  for i, data_share in enumerate(sss_priv.MakeDataShares(pt, count)):
+    safetrans.SaveObj(data_share, f'{base_path}.share.{i + 1}', config.protect)
+  config.console.print(
+    f'SSS {count} individual (private) shares saved to {base_path + ".share.1…" + str(count)!r}'
+  )
+
+
+@sss_app.command(
+  'recover',
+  help='Recover secret from shares; will use any available shares that were found.',
+  epilog=(
+    'Example:\n\n\n\n'
+    '$ poetry run safetrans -o bin -p sss-key sss recover\n\n'
+    "Loaded SSS share: 'sss-key.share.3'\n\n"
+    "Loaded SSS share: 'sss-key.share.5'\n\n"
+    "Loaded SSS share: 'sss-key.share.1'  # using only 3 shares: number 2/4 are missing\n\n"
+    'Secret:\n\n'
+    'abcde'
+  ),
+)
+@clibase.CLIErrorGuard
+def SSSRecover(*, ctx: click.Context) -> None:  # documentation is help/epilog/args # noqa: D103
+  config: safetrans.TransConfig = ctx.obj
+  base_path: str = safetrans.RequireKeyPath(config, 'sss')
+  subset: list[sss.ShamirSharePrivate] = []
+  data_share: sss.ShamirShareData | None = None
+  for fname in glob.glob(base_path + '.share.*'):  # noqa: PTH207
+    share: sss.ShamirSharePrivate = safetrans.LoadObj(fname, config.protect, sss.ShamirSharePrivate)
+    subset.append(share)
+    if isinstance(share, sss.ShamirShareData):
+      data_share = share
+    config.console.print(f'Loaded SSS share: {fname!r}')
+  if data_share is None:
+    raise base.InputError('no data share found among the available shares')
+  pt: bytes = data_share.RecoverData(subset)
+  config.console.print('Secret:')
+  config.console.print(safetrans.BytesToText(pt, config.output_format))

transcrypto-2.5.0/src/transcrypto/cli/safeintmath.py

@@ -0,0 +1,89 @@
+# SPDX-FileCopyrightText: Copyright 2026 Daniel Balparda <balparda@github.com>
+# SPDX-License-Identifier: Apache-2.0
+"""Balparda's TransCrypto safe CLI: Integer mathematics commands."""
+
+from __future__ import annotations
+
+import click
+import typer
+
+from transcrypto import safetrans
+from transcrypto.cli import clibase
+from transcrypto.core import modmath
+from transcrypto.utils import saferandom
+
+# ================================= "RANDOM" COMMAND ===============================================
+
+
+random_app = typer.Typer(
+  no_args_is_help=True,
+  help='Cryptographically secure randomness, from the OS CSPRNG.',
+)
+safetrans.app.add_typer(random_app, name='random')
+
+
+@random_app.command(
+  'bits',
+  help='Random integer with exact bit length = `bits` (MSB will be 1).',
+  epilog=('Example:\n\n\n\n$ poetry run safetrans random bits 16\n\n36650'),
+)
+@clibase.CLIErrorGuard
+def RandomBits(  # documentation is help/epilog/args # noqa: D103
+  *,
+  ctx: click.Context,
+  bits: int = typer.Argument(..., min=8, help='Number of bits, ≥ 8'),
+) -> None:
+  config: safetrans.TransConfig = ctx.obj
+  config.console.print(saferandom.RandBits(bits))
+
+
+@random_app.command(
+  'int',
+  help='Uniform random integer in `[min, max]` range, inclusive.',
+  epilog=('Example:\n\n\n\n$ poetry run safetrans random int 1000 2000\n\n1628'),
+)
+@clibase.CLIErrorGuard
+def RandomInt(  # documentation is help/epilog/args # noqa: D103
+  *,
+  ctx: click.Context,
+  min_: str = typer.Argument(..., help='Minimum, ≥ 0'),
+  max_: str = typer.Argument(..., help='Maximum, > `min`'),
+) -> None:
+  config: safetrans.TransConfig = ctx.obj
+  min_i: int = safetrans.ParseInt(min_, min_value=0)
+  max_i: int = safetrans.ParseInt(max_, min_value=min_i + 1)
+  config.console.print(saferandom.RandInt(min_i, max_i))
+
+
+@random_app.command(
+  'bytes',
+  help='Generates `n` cryptographically secure random bytes.',
+  epilog=(
+    'Example:\n\n\n\n'
+    '$ poetry run safetrans random bytes 32\n\n'
+    '6c6f1f88cb93c4323285a2224373d6e59c72a9c2b82e20d1c376df4ffbe9507f'
+  ),
+)
+@clibase.CLIErrorGuard
+def RandomBytes(  # documentation is help/epilog/args # noqa: D103
+  *,
+  ctx: click.Context,
+  n: int = typer.Argument(..., min=1, help='Number of bytes, ≥ 1'),
+) -> None:
+  config: safetrans.TransConfig = ctx.obj
+  config.console.print(safetrans.BytesToText(saferandom.RandBytes(n), config.output_format))
+
+
+@random_app.command(
+  'prime',
+  help='Generate a random prime with exact bit length = `bits` (MSB will be 1).',
+  epilog=('Example:\n\n\n\n$ poetry run safetrans random prime 32\n\n2365910551'),
+)
+@clibase.CLIErrorGuard
+def RandomPrime(  # documentation is help/epilog/args # noqa: D103
+  *,
+  ctx: click.Context,
+  bits: int = typer.Argument(..., min=11, help='Bit length, ≥ 11'),
+) -> None:
+  config: safetrans.TransConfig = ctx.obj
+  config.console.print(modmath.NBitRandomPrimes(bits).pop())