transcrypto 1.8.0__py3-none-any.whl → 2.0.3__py3-none-any.whl

transcrypto/{sss.py → core/sss.py}

@@ -12,14 +12,15 @@ import logging
 from collections import abc
 from typing import Self
 
-from . import aes, base, modmath
+from transcrypto.core import aes, hashes, key, modmath
+from transcrypto.utils import base, saferandom
 
 # fixed prefixes: do NOT ever change! will break all encryption and signature schemes
 _SSS_ENCRYPTION_AAD_PREFIX = b'transcrypto.SSS.Sharing.1.0\x00'
 
 
 @dataclasses.dataclass(kw_only=True, slots=True, frozen=True, repr=False)
-class ShamirSharedSecretPublic(base.CryptoKey):
+class ShamirSharedSecretPublic(key.CryptoKey):
   """Shamir Shared Secret (SSS) public part.
 
   No measures are taken here to prevent timing attacks.
@@ -38,7 +39,7 @@ class ShamirSharedSecretPublic(base.CryptoKey):
     """Check data.
 
     Raises:
-      InputError: invalid inputs
+      base.InputError: invalid inputs
 
     """
     if self.modulus < 2 or not modmath.IsPrime(self.modulus) or self.minimum < 2:  # noqa: PLR2004
@@ -82,8 +83,8 @@ class ShamirSharedSecretPublic(base.CryptoKey):
       no "excess" shares, there can be no way to know if the recovered secret is the correct one
 
     Raises:
-      InputError: invalid inputs
-      CryptoError: secret cannot be recovered (number of shares < `minimum`)
+      base.InputError: invalid inputs
+      key.CryptoError: secret cannot be recovered (number of shares < `minimum`)
 
     """
     # check that we have enough shares by de-duping them first
@@ -107,7 +108,7 @@ class ShamirSharedSecretPublic(base.CryptoKey):
       if force_recover and given_shares > 1:
         logging.error(f'recovering secret even though: {mess}')
       else:
-        raise base.CryptoError(f'unrecoverable secret: {mess}')
+        raise key.CryptoError(f'unrecoverable secret: {mess}')
     # do the math
     return modmath.ModLagrangeInterpolate(0, share_points, self.modulus)
 
@@ -147,7 +148,7 @@ class ShamirSharedSecretPrivate(ShamirSharedSecretPublic):
     """Check data.
 
     Raises:
-      InputError: invalid inputs
+      base.InputError: invalid inputs
 
     """
     super(ShamirSharedSecretPrivate, self).__post_init__()
@@ -172,7 +173,7 @@ class ShamirSharedSecretPrivate(ShamirSharedSecretPublic):
     return (
       'ShamirSharedSecretPrivate('
       f'{super(ShamirSharedSecretPrivate, self).__str__()}, '
-      f'polynomial=[{", ".join(base.ObfuscateSecret(i) for i in self.polynomial)}])'
+      f'polynomial=[{", ".join(hashes.ObfuscateSecret(i) for i in self.polynomial)}])'
     )
 
   def RawShare(self, secret: int, /, *, share_key: int = 0) -> ShamirSharePrivate:
@@ -192,7 +193,7 @@ class ShamirSharedSecretPrivate(ShamirSharedSecretPublic):
       ShamirSharePrivate object
 
     Raises:
-      InputError: invalid inputs
+      base.InputError: invalid inputs
 
     """
     # test inputs
@@ -202,7 +203,7 @@ class ShamirSharedSecretPrivate(ShamirSharedSecretPublic):
       if not share_key:  # default is zero, and that means we generate it here
         share_key = 0
         while not share_key or share_key in self.polynomial or share_key >= self.modulus:
-          share_key = base.RandBits(self.modulus.bit_length() - 1)
+          share_key = saferandom.RandBits(self.modulus.bit_length() - 1)
       else:
         raise base.InputError(f'invalid share_key: {share_key=}')
     # build object
@@ -229,7 +230,7 @@ class ShamirSharedSecretPrivate(ShamirSharedSecretPublic):
       ShamirSharePrivate object
 
     Raises:
-      InputError: invalid inputs
+      base.InputError: invalid inputs
 
     """
     # test inputs
@@ -246,7 +247,7 @@ class ShamirSharedSecretPrivate(ShamirSharedSecretPublic):
         or share_key in used_keys
         or share_key >= self.modulus
       ):
-        share_key = base.RandBits(self.modulus.bit_length() - 1)
+        share_key = saferandom.RandBits(self.modulus.bit_length() - 1)
       try:
         yield self.RawShare(secret, share_key=share_key)
         used_keys.add(share_key)
@@ -273,7 +274,7 @@ class ShamirSharedSecretPrivate(ShamirSharedSecretPublic):
       list[ShamirShareData]: the list of shares with encrypted data
 
     Raises:
-      InputError: invalid inputs
+      base.InputError: invalid inputs
 
     """
     if total_shares < self.minimum:
@@ -281,7 +282,7 @@ class ShamirSharedSecretPrivate(ShamirSharedSecretPublic):
     k: int = self.modulus_size
     if k <= 32:  # noqa: PLR2004
       raise base.InputError(f'modulus too small for key operations: {k} bytes')
-    key256: bytes = base.RandBytes(32)
+    key256: bytes = saferandom.RandBytes(32)
     shares: list[ShamirSharePrivate] = list(
       self.RawShares(base.BytesToInt(key256), max_shares=total_shares)
     )
@@ -290,7 +291,7 @@ class ShamirSharedSecretPrivate(ShamirSharedSecretPublic):
       + base.IntToFixedBytes(self.minimum, 8)
       + base.IntToFixedBytes(self.modulus, k)
     )
-    aead_key: bytes = base.Hash512(_SSS_ENCRYPTION_AAD_PREFIX + key256)
+    aead_key: bytes = hashes.Hash512(_SSS_ENCRYPTION_AAD_PREFIX + key256)
     ct: bytes = aes.AESKey(key256=aead_key[32:]).Encrypt(secret, associated_data=aad)
     return [
       ShamirShareData(
@@ -333,7 +334,7 @@ class ShamirSharedSecretPrivate(ShamirSharedSecretPublic):
       ShamirSharedSecretPrivate object ready for use
 
     Raises:
-      InputError: invalid inputs
+      base.InputError: invalid inputs
 
     """
     # test inputs
@@ -348,7 +349,7 @@ class ShamirSharedSecretPrivate(ShamirSharedSecretPublic):
     modulus: int = max(ordered_primes)
     ordered_primes.remove(modulus)
     # make polynomial be a random order
-    base.RandShuffle(ordered_primes)
+    saferandom.RandShuffle(ordered_primes)
     # build object
     return cls(minimum=minimum_shares, modulus=modulus, polynomial=ordered_primes)
 
@@ -373,7 +374,7 @@ class ShamirSharePrivate(ShamirSharedSecretPublic):
     """Check data.
 
     Raises:
-      InputError: invalid inputs
+      base.InputError: invalid inputs
 
     """
     super(ShamirSharePrivate, self).__post_init__()
@@ -390,8 +391,8 @@ class ShamirSharePrivate(ShamirSharedSecretPublic):
     return (
       'ShamirSharePrivate('
       f'{super(ShamirSharePrivate, self).__str__()}, '
-      f'share_key={base.ObfuscateSecret(self.share_key)}, '
-      f'share_value={base.ObfuscateSecret(self.share_value)})'
+      f'share_key={hashes.ObfuscateSecret(self.share_key)}, '
+      f'share_value={hashes.ObfuscateSecret(self.share_value)})'
     )
 
   @classmethod
@@ -433,7 +434,7 @@ class ShamirShareData(ShamirSharePrivate):
     """Check data.
 
     Raises:
-      InputError: invalid inputs
+      base.InputError: invalid inputs
 
     """
     super(ShamirShareData, self).__post_init__()
@@ -450,7 +451,7 @@ class ShamirShareData(ShamirSharePrivate):
     return (
       'ShamirShareData('
       f'{super(ShamirShareData, self).__str__()}, '
-      f'encrypted_data={base.ObfuscateSecret(self.encrypted_data)})'
+      f'encrypted_data={hashes.ObfuscateSecret(self.encrypted_data)})'
     )
 
   def RecoverData(self, other_shares: list[ShamirSharePrivate]) -> bytes:
@@ -467,8 +468,8 @@ class ShamirShareData(ShamirSharePrivate):
       bytes: Decrypted plaintext bytes
 
     Raises:
-      InputError: invalid inputs
-      CryptoError: internal crypto failures, authentication failure, key mismatch, etc
+      base.InputError: invalid inputs
+      key.CryptoError: internal crypto failures, authentication failure, key mismatch, etc
 
     """
     k: int = self.modulus_size
@@ -477,12 +478,12 @@ class ShamirShareData(ShamirSharePrivate):
     # recover secret; raise if shares are invalid
     secret: int = self.RawRecoverSecret([self, *other_shares])
     if not 0 <= secret < (1 << 256):
-      raise base.CryptoError('recovered key out of range for 256-bit key')
+      raise key.CryptoError('recovered key out of range for 256-bit key')
     key256: bytes = base.IntToFixedBytes(secret, 32)
     aad: bytes = (
       _SSS_ENCRYPTION_AAD_PREFIX
       + base.IntToFixedBytes(self.minimum, 8)
       + base.IntToFixedBytes(self.modulus, k)
     )
-    aead_key: bytes = base.Hash512(_SSS_ENCRYPTION_AAD_PREFIX + key256)
+    aead_key: bytes = hashes.Hash512(_SSS_ENCRYPTION_AAD_PREFIX + key256)
     return aes.AESKey(key256=aead_key[32:]).Decrypt(self.encrypted_data, associated_data=aad)

transcrypto/profiler.py

@@ -21,17 +21,29 @@ from __future__ import annotations
 import dataclasses
 from collections import abc
 
+import click
 import typer
 from rich import console as rich_console
 
 from transcrypto.cli import clibase
+from transcrypto.core import dsa, modmath
+from transcrypto.utils import human, timer
+from transcrypto.utils import logging as tc_logging
 
-from . import __version__, base, dsa, modmath
+from . import __version__
 
 
 @dataclasses.dataclass(kw_only=True, slots=True, frozen=True)
 class ProfilerConfig(clibase.CLIConfig):
-  """CLI global context, storing the configuration."""
+  """CLI global context, storing the configuration.
+
+  Attributes:
+    serial (bool): Whether to run profiling serially (vs parallel)
+    repeats (int): Number of repetitions for each profiling run
+    confidence (int): Confidence level percentage for statistical analysis
+    bits (tuple[int, int, int]): Bit sizes range (start, stop, step) for profiling
+
+  """
 
   serial: bool
   repeats: int
@@ -67,7 +79,7 @@ def Run() -> None:
 @clibase.CLIErrorGuard
 def Main(  # documentation is help/epilog/args # noqa: D103
   *,
-  ctx: typer.Context,  # global context
+  ctx: click.Context,  # global context
   version: bool = typer.Option(False, '--version', help='Show version and exit.'),
   verbose: int = typer.Option(
     0,
@@ -124,7 +136,9 @@ def Main(  # documentation is help/epilog/args # noqa: D103
   if version:
     typer.echo(__version__)
     raise typer.Exit(0)
-  console, verbose, color = clibase.InitLogging(
+  # initialize logging and get console
+  console: rich_console.Console
+  console, verbose, color = tc_logging.InitLogging(
     verbose,
     color=color,
     include_process=False,  # decide if you want process names in logs
@@ -160,7 +174,7 @@ def Main(  # documentation is help/epilog/args # noqa: D103
   ),
 )
 @clibase.CLIErrorGuard
-def Primes(*, ctx: typer.Context) -> None:  # documentation is help/epilog/args # noqa: D103
+def Primes(*, ctx: click.Context) -> None:  # documentation is help/epilog/args # noqa: D103
   config: ProfilerConfig = ctx.obj  # get application global config
   config.console.print(
     f'Starting [yellow]{"SERIAL" if config.serial else "PARALLEL"} regular primes[/] test'
@@ -190,7 +204,7 @@ def Primes(*, ctx: typer.Context) -> None:  # documentation is help/epilog/args
   ),
 )
 @clibase.CLIErrorGuard
-def DSA(*, ctx: typer.Context) -> None:  # documentation is help/epilog/args # noqa: D103
+def DSA(*, ctx: click.Context) -> None:  # documentation is help/epilog/args # noqa: D103
   config: ProfilerConfig = ctx.obj  # get application global config
   config.console.print(
     f'Starting [yellow]{"SERIAL" if config.serial else "PARALLEL"} DSA primes[/] test'
@@ -211,7 +225,7 @@ def DSA(*, ctx: typer.Context) -> None:  # documentation is help/epilog/args # n
 )
 @clibase.CLIErrorGuard
 def Markdown() -> None:  # documentation is help/epilog/args # noqa: D103
-  console: rich_console.Console = clibase.Console()
+  console: rich_console.Console = tc_logging.Console()
   console.print(clibase.GenerateTyperHelpMarkdown(app, prog_name='profiler'))
 
 
@@ -223,20 +237,20 @@ def _PrimeProfiler(
   confidence: float,
   /,
 ) -> None:
-  with base.Timer(emit_log=False) as total_time:
+  with timer.Timer(emit_log=False) as total_time:
     primes: dict[int, list[float]] = {}
     for n_bits in range(*n_bits_range):
       # investigate for size n_bits
       primes[n_bits] = []
       for _ in range(repeats):
-        with base.Timer(emit_log=False) as run_time:
+        with timer.Timer(emit_log=False) as run_time:
           pr: int = prime_callable(n_bits)
         assert pr  # noqa: S101
         assert pr.bit_length() == n_bits  # noqa: S101
         primes[n_bits].append(run_time.elapsed)
       # finished collecting n_bits-sized primes
-      measurements: str = base.HumanizedMeasurements(
-        primes[n_bits], parser=base.HumanizedSeconds, confidence=confidence
+      measurements: str = human.HumanizedMeasurements(
+        primes[n_bits], parser=human.HumanizedSeconds, confidence=confidence
       )
       console.print(f'{n_bits} → {measurements}')
   console.print(f'Finished in {total_time}')

transcrypto/transcrypto.py

@@ -97,14 +97,14 @@ import pathlib
 
 import click
 import typer
+from rich import console as rich_console
 
 from transcrypto.cli import clibase
+from transcrypto.core import aes, key
+from transcrypto.utils import base, human
+from transcrypto.utils import logging as tc_logging
 
-from . import (
-  __version__,
-  aes,
-  base,
-)
+from . import __version__
 
 
 class IOFormat(enum.Enum):
@@ -117,7 +117,15 @@ class IOFormat(enum.Enum):
 
 @dataclasses.dataclass(kw_only=True, slots=True, frozen=True)
 class TransConfig(clibase.CLIConfig):
-  """CLI global context, storing the configuration."""
+  """CLI global context, storing the configuration.
+
+  Attributes:
+    input_format (IOFormat): Input data format (hex, b64, bin)
+    output_format (IOFormat): Output data format (hex, b64, bin)
+    key_path (pathlib.Path | None): Path to key file for crypto operations
+    protect (str | None): Password protection for key operations
+
+  """
 
   input_format: IOFormat
   output_format: IOFormat
@@ -240,18 +248,18 @@ def BytesToText(b: bytes, fmt: IOFormat, /) -> str:
       return base.BytesToEncoded(b)
 
 
-def SaveObj(obj: base.CryptoKey, path: str, password: str | None, /) -> None:
+def SaveObj(obj: key.CryptoKey, path: str, password: str | None, /) -> None:
   """Save object.
 
   Args:
-      obj (base.CryptoKey): object
+      obj (cryptokey.CryptoKey): object
       path (str): path
       password (str | None): password
 
   """
-  key: aes.AESKey | None = aes.AESKey.FromStaticPassword(password) if password else None
-  blob: bytes = base.Serialize(obj, file_path=path, key=key)
-  logging.info('saved object: %s (%s)', path, base.HumanizedBytes(len(blob)))
+  encryption_key: aes.AESKey | None = aes.AESKey.FromStaticPassword(password) if password else None
+  blob: bytes = key.Serialize(obj, file_path=path, encryption_key=encryption_key)
+  logging.info('saved object: %s (%s)', path, human.HumanizedBytes(len(blob)))
 
 
 def LoadObj[T](path: str, password: str | None, expect: type[T], /) -> T:
@@ -269,8 +277,8 @@ def LoadObj[T](path: str, password: str | None, expect: type[T], /) -> T:
       T: loaded object
 
   """
-  key: aes.AESKey | None = aes.AESKey.FromStaticPassword(password) if password else None
-  obj: T = base.DeSerialize(file_path=path, key=key)
+  decryption_key: aes.AESKey | None = aes.AESKey.FromStaticPassword(password) if password else None
+  obj: T = key.DeSerialize(file_path=path, decryption_key=decryption_key)
   if not isinstance(obj, expect):
     raise base.InputError(
       f'Object loaded from {path} is of invalid type {type(obj)}, expected {expect}'
@@ -427,7 +435,9 @@ def Main(  # documentation is help/epilog/args # noqa: D103
   if version:
     typer.echo(__version__)
     raise typer.Exit(0)
-  console, verbose, color = clibase.InitLogging(
+  # initialize logging and get console
+  console: rich_console.Console
+  console, verbose, color = tc_logging.InitLogging(
     verbose,
     color=color,
     include_process=False,
@@ -452,7 +462,7 @@ def Main(  # documentation is help/epilog/args # noqa: D103
   ),
 )
 @clibase.CLIErrorGuard
-def Markdown(*, ctx: typer.Context) -> None:  # documentation is help/epilog/args # noqa: D103
+def Markdown(*, ctx: click.Context) -> None:  # documentation is help/epilog/args # noqa: D103
   config: TransConfig = ctx.obj
   config.console.print(clibase.GenerateTyperHelpMarkdown(app, prog_name='transcrypto'))
 

transcrypto/utils/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: Copyright 2026 Daniel Balparda <balparda@github.com>
+# SPDX-License-Identifier: Apache-2.0
+"""Utility modules."""

transcrypto/utils/base.py

@@ -0,0 +1,72 @@
+# SPDX-FileCopyrightText: Copyright 2026 Daniel Balparda <balparda@github.com>
+# SPDX-License-Identifier: Apache-2.0
+"""Balparda's TransCrypto base library."""
+
+from __future__ import annotations
+
+import base64
+import codecs
+from collections import abc
+
+# Data conversion utils
+
+# JSON types
+type JSONValue = bool | int | float | str | list[JSONValue] | dict[str, JSONValue] | None
+type JSONDict = dict[str, JSONValue]
+
+BytesToHex: abc.Callable[[bytes], str] = lambda b: b.hex()
+BytesToInt: abc.Callable[[bytes], int] = lambda b: int.from_bytes(b, 'big', signed=False)
+BytesToEncoded: abc.Callable[[bytes], str] = lambda b: base64.urlsafe_b64encode(b).decode('ascii')
+
+HexToBytes: abc.Callable[[str], bytes] = bytes.fromhex
+IntToFixedBytes: abc.Callable[[int, int], bytes] = lambda i, n: i.to_bytes(n, 'big', signed=False)
+IntToBytes: abc.Callable[[int], bytes] = lambda i: IntToFixedBytes(i, (i.bit_length() + 7) // 8)
+IntToEncoded: abc.Callable[[int], str] = lambda i: BytesToEncoded(IntToBytes(i))
+EncodedToBytes: abc.Callable[[str], bytes] = lambda e: base64.urlsafe_b64decode(e.encode('ascii'))
+
+PadBytesTo: abc.Callable[[bytes, int], bytes] = lambda b, i: b.rjust((i + 7) // 8, b'\x00')
+
+
+class Error(Exception):
+  """TransCrypto exception."""
+
+
+class InputError(Error):
+  """Input exception (TransCrypto)."""
+
+
+class ImplementationError(Error, NotImplementedError):
+  """Feature is not implemented yet (TransCrypto)."""
+
+
+def BytesToRaw(b: bytes, /) -> str:
+  r"""Convert bytes to double-quoted string with \\xNN escapes where needed.
+
+  1. map bytes 0..255 to same code points (latin1)
+  2. escape non-printables/backslash/quotes via unicode_escape
+
+  Args:
+    b (bytes): input
+
+  Returns:
+    str: double-quoted string with \\xNN escapes where needed
+
+  """
+  inner: str = b.decode('latin1').encode('unicode_escape').decode('ascii')
+  return f'"{inner.replace('"', r"\"")}"'
+
+
+def RawToBytes(s: str, /) -> bytes:
+  r"""Convert double-quoted string with \\xNN escapes where needed to bytes.
+
+  Args:
+    s (str): input (expects a double-quoted string; parses \\xNN, \n, \\ etc)
+
+  Returns:
+    bytes: data
+
+  """
+  if len(s) >= 2 and s[0] == s[-1] == '"':  # noqa: PLR2004
+    s = s[1:-1]
+  # decode backslash escapes to code points, then map 0..255 -> bytes
+  return codecs.decode(s, 'unicode_escape').encode('latin1')