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

transcrypto/__init__.py

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

transcrypto/cli/aeshash.py

@@ -10,8 +10,10 @@ import re
 import click
 import typer
 
-from transcrypto import aes, base, transcrypto
+from transcrypto import transcrypto
 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]+$')
 
@@ -44,7 +46,7 @@ def Hash256(  # documentation is help/epilog/args # noqa: D103
 ) -> None:
   config: transcrypto.TransConfig = ctx.obj
   bt: bytes = transcrypto.BytesFromText(data, config.input_format)
-  config.console.print(transcrypto.BytesToText(base.Hash256(bt), config.output_format))
+  config.console.print(transcrypto.BytesToText(hashes.Hash256(bt), config.output_format))
 
 
 @hash_app.command(
@@ -68,7 +70,7 @@ def Hash512(  # documentation is help/epilog/args # noqa: D103
 ) -> None:
   config: transcrypto.TransConfig = ctx.obj
   bt: bytes = transcrypto.BytesFromText(data, config.input_format)
-  config.console.print(transcrypto.BytesToText(base.Hash512(bt), config.output_format))
+  config.console.print(transcrypto.BytesToText(hashes.Hash512(bt), config.output_format))
 
 
 @hash_app.command(
@@ -104,7 +106,7 @@ def HashFile(  # documentation is help/epilog/args # noqa: D103
 ) -> None:
   config: transcrypto.TransConfig = ctx.obj
   config.console.print(
-    transcrypto.BytesToText(base.FileHash(str(path), digest=digest), config.output_format)
+    transcrypto.BytesToText(hashes.FileHash(str(path), digest=digest), config.output_format)
   )
 
 

transcrypto/cli/bidsecret.py

@@ -8,8 +8,10 @@ import glob
 
 import typer
 
-from transcrypto import base, sss, transcrypto
+from transcrypto import transcrypto
 from transcrypto.cli import clibase
+from transcrypto.core import bid, sss
+from transcrypto.utils import base
 
 # ================================== "BID" COMMAND =================================================
 
@@ -45,8 +47,8 @@ def BidNew(  # documentation is help/epilog/args # noqa: D103
   config: transcrypto.TransConfig = ctx.obj
   base_path: str = transcrypto.RequireKeyPath(config, 'bid')
   secret_bytes: bytes = transcrypto.BytesFromText(secret, config.input_format)
-  bid_priv: base.PrivateBid512 = base.PrivateBid512.New(secret_bytes)
-  bid_pub: base.PublicBid512 = base.PublicBid512.Copy(bid_priv)
+  bid_priv: bid.PrivateBid512 = bid.PrivateBid512.New(secret_bytes)
+  bid_pub: bid.PublicBid512 = bid.PublicBid512.Copy(bid_priv)
   transcrypto.SaveObj(bid_priv, base_path + '.priv', config.protect)
   transcrypto.SaveObj(bid_pub, base_path + '.pub', config.protect)
   config.console.print(f'Bid private/public commitments saved to {base_path + ".priv/.pub"!r}')
@@ -67,13 +69,13 @@ def BidNew(  # documentation is help/epilog/args # noqa: D103
 def BidVerify(*, ctx: typer.Context) -> None:  # documentation is help/epilog/args # noqa: D103
   config: transcrypto.TransConfig = ctx.obj
   base_path: str = transcrypto.RequireKeyPath(config, 'bid')
-  bid_priv: base.PrivateBid512 = transcrypto.LoadObj(
-    base_path + '.priv', config.protect, base.PrivateBid512
+  bid_priv: bid.PrivateBid512 = transcrypto.LoadObj(
+    base_path + '.priv', config.protect, bid.PrivateBid512
   )
-  bid_pub: base.PublicBid512 = transcrypto.LoadObj(
-    base_path + '.pub', config.protect, base.PublicBid512
+  bid_pub: bid.PublicBid512 = transcrypto.LoadObj(
+    base_path + '.pub', config.protect, bid.PublicBid512
   )
-  bid_pub_expect: base.PublicBid512 = base.PublicBid512.Copy(bid_priv)
+  bid_pub_expect: bid.PublicBid512 = bid.PublicBid512.Copy(bid_priv)
   config.console.print(
     'Bid commitment: '
     + (

transcrypto/cli/clibase.py

@@ -7,8 +7,6 @@ from __future__ import annotations
 import dataclasses
 import functools
 import logging
-import os
-import threading
 from collections import abc
 from typing import cast
 
@@ -16,139 +14,21 @@ import click
 import typer
 from click import testing as click_testing
 from rich import console as rich_console
-from rich import logging as rich_logging
 
-from transcrypto import base
+from transcrypto.utils import base
+from transcrypto.utils import logging as tc_logging
 
-# Logging
-_LOG_FORMAT_NO_PROCESS: str = '%(funcName)s: %(message)s'
-_LOG_FORMAT_WITH_PROCESS: str = '%(processName)s/' + _LOG_FORMAT_NO_PROCESS
-_LOG_FORMAT_DATETIME: str = '[%Y%m%d-%H:%M:%S]'  # e.g., [20240131-13:45:30]
-_LOG_LEVELS: dict[int, int] = {
-  0: logging.ERROR,
-  1: logging.WARNING,
-  2: logging.INFO,
-  3: logging.DEBUG,
-}
-_LOG_COMMON_PROVIDERS: set[str] = {
-  'werkzeug',
-  'gunicorn.error',
-  'gunicorn.access',
-  'uvicorn',
-  'uvicorn.error',
-  'uvicorn.access',
-  'django.server',
-}
 
-__console_lock: threading.RLock = threading.RLock()
-__console_singleton: rich_console.Console | None = None
-
-
-def Console() -> rich_console.Console:
-  """Get the global console instance.
-
-  Returns:
-    rich.console.Console: The global console instance.
-
-  """
-  with __console_lock:
-    if __console_singleton is None:
-      return rich_console.Console()  # fallback console if InitLogging hasn't been called yet
-    return __console_singleton
-
-
-def ResetConsole() -> None:
-  """Reset the global console instance."""
-  global __console_singleton  # noqa: PLW0603
-  with __console_lock:
-    __console_singleton = None
-
-
-def InitLogging(
-  verbosity: int,
-  /,
-  *,
-  include_process: bool = False,
-  soft_wrap: bool = False,
-  color: bool | None = False,
-) -> tuple[rich_console.Console, int, bool]:
-  """Initialize logger (with RichHandler) and get a rich.console.Console singleton.
-
-  This method will also return the actual decided values for verbosity and color use.
-  If you have a CLI app that uses this, its pytests should call `ResetConsole()` in a fixture, like:
-
-      from transcrypto import logging
-      @pytest.fixture(autouse=True)
-      def _reset_base_logging() -> Generator[None, None, None]:  # type: ignore
-        logging.ResetConsole()
-        yield  # stop
-
-  Args:
-    verbosity (int): Logging verbosity level: 0==ERROR, 1==WARNING, 2==INFO, 3==DEBUG
-    include_process (bool, optional): Whether to include process name in log output.
-    soft_wrap (bool, optional): Whether to enable soft wrapping in the console.
-        Default is False, and it means rich will hard-wrap long lines (by adding line breaks).
-    color (bool | None, optional): Whether to enable/disable color output in the console.
-        If None, respects NO_COLOR env var.
-
-  Returns:
-    tuple[rich_console.Console, int, bool]:
-        (The initialized console instance, actual log level, actual color use)
+@dataclasses.dataclass(kw_only=True, slots=True, frozen=True)
+class CLIConfig:
+  """CLI global context, storing the configuration.
 
-  Raises:
-    RuntimeError: if you call this more than once
+  Attributes:
+    console (rich_console.Console): Rich console instance for output
+    verbose (int): Verbosity level (0-3)
+    color (bool | None): Color preference (None=auto, True=force, False=disable)
 
   """
-  global __console_singleton  # noqa: PLW0603
-  with __console_lock:
-    if __console_singleton is not None:
-      raise RuntimeError(
-        'calling InitLogging() more than once is forbidden; '
-        'use Console() to get a console after first creation'
-      )
-    # set level
-    logging_level: int = _LOG_LEVELS.get(min(verbosity, 3), logging.ERROR)
-    # respect NO_COLOR unless the caller has already decided (treat env presence as "disable color")
-    no_color: bool = (
-      False
-      if (os.getenv('NO_COLOR') is None and color is None)
-      else ((os.getenv('NO_COLOR') is not None) if color is None else (not color))
-    )
-    # create console and configure logging
-    console = rich_console.Console(soft_wrap=soft_wrap, no_color=no_color)
-    logging.basicConfig(
-      level=logging_level,
-      format=_LOG_FORMAT_WITH_PROCESS if include_process else _LOG_FORMAT_NO_PROCESS,
-      datefmt=_LOG_FORMAT_DATETIME,
-      handlers=[
-        rich_logging.RichHandler(  # we show name/line, but want time & level
-          console=console,
-          rich_tracebacks=True,
-          show_time=True,
-          show_level=True,
-          show_path=True,
-        ),
-      ],
-      force=True,  # force=True to override any previous logging config
-    )
-    # configure common loggers
-    logging.captureWarnings(True)
-    for name in _LOG_COMMON_PROVIDERS:
-      log: logging.Logger = logging.getLogger(name)
-      log.handlers.clear()
-      log.propagate = True
-      log.setLevel(logging_level)
-    __console_singleton = console  # need a global statement to re-bind this one
-    logging.info(
-      f'Logging initialized at level {logging.getLevelName(logging_level)} / '
-      f'{"NO " if no_color else ""}COLOR'
-    )
-    return (console, logging_level, not no_color)
-
-
-@dataclasses.dataclass(kw_only=True, slots=True, frozen=True)
-class CLIConfig:
-  """CLI global context, storing the configuration."""
 
   console: rich_console.Console
   verbose: int
@@ -183,9 +63,9 @@ def CLIErrorGuard[**P](fn: abc.Callable[P, None], /) -> abc.Callable[P, None]:
           obj.console.print(str(err))  # print only error message
       # no context
       elif logging.getLogger().getEffectiveLevel() < logging.INFO:
-        Console().print(str(err))  # print only error message (DEBUG level is verbose already)
+        tc_logging.Console().print(str(err))  # print only error message (DEBUG is verbose already)
       else:
-        Console().print_exception()  # print full traceback (less verbose mode needs it)
+        tc_logging.Console().print_exception()  # print full traceback (less verbose mode needs it)
 
   return _Wrapper
 
@@ -267,7 +147,7 @@ def GenerateTyperHelpMarkdown(
     # build command path
     command_path: str = ' '.join([prog_name, *path]).strip()
     heading_prefix: str = '#' * max(1, heading_level + len(path))
-    ResetConsole()  # ensure clean state for each command (also it raises on duplicate loggers)
+    tc_logging.ResetConsole()  # ensure clean state for the command
     # invoke --help for this command path
     result: click_testing.Result = runner.invoke(
       click_root,

transcrypto/cli/intmath.py

@@ -6,8 +6,10 @@ from __future__ import annotations
 
 import typer
 
-from transcrypto import base, modmath, transcrypto
+from transcrypto import transcrypto
 from transcrypto.cli import clibase
+from transcrypto.core import modmath
+from transcrypto.utils import base, saferandom
 
 # =============================== "PRIME"-like COMMANDS ============================================
 
@@ -116,7 +118,7 @@ def GcdCLI(  # documentation is help/epilog/args # noqa: D103
   b_i: int = transcrypto.ParseInt(b, min_value=0)
   if a_i == 0 and b_i == 0:
     raise base.InputError("`a` and `b` can't both be zero")
-  config.console.print(base.GCD(a_i, b_i))
+  config.console.print(modmath.GCD(a_i, b_i))
 
 
 @transcrypto.app.command(
@@ -147,7 +149,7 @@ def XgcdCLI(  # documentation is help/epilog/args # noqa: D103
   b_i: int = transcrypto.ParseInt(b, min_value=0)
   if a_i == 0 and b_i == 0:
     raise base.InputError("`a` and `b` can't both be zero")
-  config.console.print(str(base.ExtendedGCD(a_i, b_i)))
+  config.console.print(str(modmath.ExtendedGCD(a_i, b_i)))
 
 
 # ================================= "RANDOM" COMMAND ===============================================
@@ -172,7 +174,7 @@ def RandomBits(  # documentation is help/epilog/args # noqa: D103
   bits: int = typer.Argument(..., min=8, help='Number of bits, ≥ 8'),
 ) -> None:
   config: transcrypto.TransConfig = ctx.obj
-  config.console.print(base.RandBits(bits))
+  config.console.print(saferandom.RandBits(bits))
 
 
 @random_app.command(
@@ -190,7 +192,7 @@ def RandomInt(  # documentation is help/epilog/args # noqa: D103
   config: transcrypto.TransConfig = ctx.obj
   min_i: int = transcrypto.ParseInt(min_, min_value=0)
   max_i: int = transcrypto.ParseInt(max_, min_value=min_i + 1)
-  config.console.print(base.RandInt(min_i, max_i))
+  config.console.print(saferandom.RandInt(min_i, max_i))
 
 
 @random_app.command(
@@ -209,7 +211,7 @@ def RandomBytes(  # documentation is help/epilog/args # noqa: D103
   n: int = typer.Argument(..., min=1, help='Number of bytes, ≥ 1'),
 ) -> None:
   config: transcrypto.TransConfig = ctx.obj
-  config.console.print(transcrypto.BytesToText(base.RandBytes(n), config.output_format))
+  config.console.print(transcrypto.BytesToText(saferandom.RandBytes(n), config.output_format))
 
 
 @random_app.command(

transcrypto/cli/publicalgos.py

@@ -6,8 +6,9 @@ from __future__ import annotations
 
 import typer
 
-from transcrypto import dsa, elgamal, rsa, transcrypto
+from transcrypto import transcrypto
 from transcrypto.cli import clibase
+from transcrypto.core import dsa, elgamal, rsa
 
 # ================================== "RSA" COMMAND =================================================
 

transcrypto/core/__init__.py

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

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

@@ -25,7 +25,8 @@ from cryptography.hazmat.primitives import hashes as hazmat_hashes
 from cryptography.hazmat.primitives.ciphers import algorithms, modes
 from cryptography.hazmat.primitives.kdf import pbkdf2 as hazmat_pbkdf2
 
-from . import base
+from transcrypto.core import hashes, key
+from transcrypto.utils import base, saferandom
 
 # these fixed salt/iterations are for password->key generation only; NEVER use them to
 # build a database of passwords because it would not be safe; NEVER change them or the
@@ -41,7 +42,7 @@ assert _PASSWORD_ITERATIONS == (6075308 + 1) // 3, 'should never happen: constan
 
 
 @dataclasses.dataclass(kw_only=True, slots=True, frozen=True, repr=False)
-class AESKey(base.CryptoKey, base.Encryptor, base.Decryptor):
+class AESKey(key.CryptoKey, key.Encryptor, key.Decryptor):
   """Advanced Encryption Standard (AES) 256 bits key (32 bytes).
 
   No measures are taken here to prevent timing attacks.
@@ -57,7 +58,7 @@ class AESKey(base.CryptoKey, base.Encryptor, base.Decryptor):
     """Check data.
 
     Raises:
-      InputError: invalid inputs
+      base.InputError: invalid inputs
 
     """
     if len(self.key256) != 32:  # noqa: PLR2004
@@ -70,7 +71,7 @@ class AESKey(base.CryptoKey, base.Encryptor, base.Decryptor):
       string representation of AESKey without leaking secrets
 
     """
-    return f'AESKey(key256={base.ObfuscateSecret(self.key256)})'
+    return f'AESKey(key256={hashes.ObfuscateSecret(self.key256)})'
 
   @classmethod
   def FromStaticPassword(cls, str_password: str, /) -> Self:
@@ -98,7 +99,7 @@ class AESKey(base.CryptoKey, base.Encryptor, base.Decryptor):
       AESKey crypto key to use (URL-safe base64-encoded 32-byte key)
 
     Raises:
-      InputError: empty password
+      base.InputError: empty password
 
     """
     str_password = str_password.strip()
@@ -112,7 +113,7 @@ class AESKey(base.CryptoKey, base.Encryptor, base.Decryptor):
     )
     return cls(key256=kdf.derive(str_password.encode('utf-8')))
 
-  class ECBEncoderClass(base.Encryptor, base.Decryptor):
+  class ECBEncoderClass(key.Encryptor, key.Decryptor):
     """The simplest encryption possible (UNSAFE if misused): 128 bit block AES-ECB, 256 bit key.
 
     Note: Due to ECB encoding, this class is only safe-ish for blocks of random-looking data,
@@ -162,7 +163,7 @@ class AESKey(base.CryptoKey, base.Encryptor, base.Decryptor):
         bytes: Ciphertext, a block of 128 bits (16 bytes)
 
       Raises:
-        InputError: invalid inputs
+        base.InputError: invalid inputs
 
       """
       if associated_data is not None:
@@ -189,7 +190,7 @@ class AESKey(base.CryptoKey, base.Encryptor, base.Decryptor):
         bytes: Decrypted plaintext, a block of 128 bits (16 bytes)
 
       Raises:
-        InputError: invalid inputs
+        base.InputError: invalid inputs
 
       """
       if associated_data is not None:
@@ -227,7 +228,7 @@ class AESKey(base.CryptoKey, base.Encryptor, base.Decryptor):
           str: encrypted hexadecimal block (length==64)
 
       Raises:
-          InputError: invalid inputs
+          base.InputError: invalid inputs
 
       """
       if len(plaintext_hex) != 64:  # noqa: PLR2004
@@ -262,7 +263,7 @@ class AESKey(base.CryptoKey, base.Encryptor, base.Decryptor):
           str: plaintext hexadecimal block (length==64)
 
       Raises:
-          InputError: invalid inputs
+          base.InputError: invalid inputs
 
       """
       if len(ciphertext_hex) != 64:  # noqa: PLR2004
@@ -297,7 +298,7 @@ class AESKey(base.CryptoKey, base.Encryptor, base.Decryptor):
       must encode it within the returned bytes (or document how to retrieve it)
 
     """
-    iv: bytes = base.RandBytes(16)
+    iv: bytes = saferandom.RandBytes(16)
     cipher: ciphers.Cipher[modes.GCM] = ciphers.Cipher(
       algorithms.AES256(self.key256), modes.GCM(iv)
     )
@@ -339,12 +340,14 @@ class AESKey(base.CryptoKey, base.Encryptor, base.Decryptor):
       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
 
     """
     if len(ciphertext) < 32:  # noqa: PLR2004
       raise base.InputError(f'AES256+GCM should have ≥32 bytes IV/CT/tag: {len(ciphertext)}')
+    iv: bytes
+    tag: bytes
     iv, tag = ciphertext[:16], ciphertext[-16:]
     decryptor: ciphers.CipherContext = ciphers.Cipher(
       algorithms.AES256(self.key256), modes.GCM(iv, tag)
@@ -354,19 +357,4 @@ class AESKey(base.CryptoKey, base.Encryptor, base.Decryptor):
     try:
       return decryptor.update(ciphertext[16:-16]) + decryptor.finalize()
     except crypt_exceptions.InvalidTag as err:
-      raise base.CryptoError('failed decryption') from err
-
-
-def _TestCryptoKeyEncoding(obj: base.CryptoKey, tp: type[base.CryptoKey]) -> None:  # pyright: ignore[reportUnusedFunction]
-  """Test encoding for a CryptoKey instance. Only for use from test modules."""
-  assert tp.FromJSON(obj.json) == obj  # noqa: S101
-  assert tp.FromJSON(obj.formatted_json) == obj  # noqa: S101
-  assert tp.Load(obj.blob) == obj  # noqa: S101
-  assert tp.Load(obj.encoded) == obj  # noqa: S101
-  assert tp.Load(obj.hex) == obj  # noqa: S101
-  assert tp.Load(obj.raw) == obj  # noqa: S101
-  key = AESKey(key256=b'x' * 32)
-  assert tp.Load(obj.Blob(key=key), key=key) == obj  # noqa: S101
-  assert tp.Load(obj.Encoded(key=key), key=key) == obj  # noqa: S101
-  assert tp.Load(obj.Hex(key=key), key=key) == obj  # noqa: S101
-  assert tp.Load(obj.Raw(key=key), key=key) == obj  # noqa: S101
+      raise key.CryptoError('failed decryption') from err

transcrypto/core/bid.py

@@ -0,0 +1,161 @@
+# SPDX-FileCopyrightText: Copyright 2026 Daniel Balparda <balparda@github.com>
+# SPDX-License-Identifier: Apache-2.0
+"""Balparda's TransCrypto bidding protocols."""
+
+from __future__ import annotations
+
+import dataclasses
+from typing import Self
+
+from transcrypto.core import hashes, key
+from transcrypto.utils import base, saferandom
+
+
+@dataclasses.dataclass(kw_only=True, slots=True, frozen=True, repr=False)
+class PublicBid512(key.CryptoKey):
+  """Public commitment to a (cryptographically secure) bid that can be revealed/validated later.
+
+  Bid is computed as: public_hash = Hash512(public_key || private_key || secret_bid)
+
+  Everything is bytes. The public part is (public_key, public_hash) and the private
+  part is (private_key, secret_bid). The whole computation can be checked later.
+
+  No measures are taken here to prevent timing attacks (probably not a concern).
+
+  Attributes:
+    public_key (bytes): 512-bits random value
+    public_hash (bytes): SHA-512 hash of (public_key || private_key || secret_bid)
+
+  """
+
+  public_key: bytes
+  public_hash: bytes
+
+  def __post_init__(self) -> None:
+    """Check data.
+
+    Raises:
+      base.InputError: invalid inputs
+
+    """
+    if len(self.public_key) != 64 or len(self.public_hash) != 64:  # noqa: PLR2004
+      raise base.InputError(f'invalid public_key or public_hash: {self}')
+
+  def __str__(self) -> str:
+    """Safe string representation of the PublicBid.
+
+    Returns:
+      string representation of PublicBid
+
+    """
+    return (
+      'PublicBid512('
+      f'public_key={base.BytesToEncoded(self.public_key)}, '
+      f'public_hash={base.BytesToHex(self.public_hash)})'
+    )
+
+  def VerifyBid(self, private_key: bytes, secret: bytes, /) -> bool:
+    """Verify a bid. True if OK; False if failed verification.
+
+    Args:
+      private_key (bytes): 512-bits private key
+      secret (bytes): Any number of bytes (≥1) to bid on (e.g., UTF-8 encoded string)
+
+    Returns:
+      True if bid is valid, False otherwise
+
+    """
+    try:
+      # creating the PrivateBid object will validate everything; InputError we allow to propagate
+      PrivateBid512(
+        public_key=self.public_key,
+        public_hash=self.public_hash,
+        private_key=private_key,
+        secret_bid=secret,
+      )
+      return True  # if we got here, all is good
+    except key.CryptoError:
+      return False  # bid does not match the public commitment
+
+  @classmethod
+  def Copy(cls, other: PublicBid512, /) -> Self:
+    """Initialize a public bid by taking the public parts of a public/private bid.
+
+    Args:
+        other (PublicBid512): the bid to copy from
+
+    Returns:
+        Self: an initialized PublicBid512
+
+    """
+    return cls(public_key=other.public_key, public_hash=other.public_hash)
+
+
+@dataclasses.dataclass(kw_only=True, slots=True, frozen=True, repr=False)
+class PrivateBid512(PublicBid512):
+  """Private bid that can be revealed and validated against a public commitment (see PublicBid).
+
+  Attributes:
+    private_key (bytes): 512-bits random value
+    secret_bid (bytes): Any number of bytes (≥1) to bid on (e.g., UTF-8 encoded string)
+
+  """
+
+  private_key: bytes
+  secret_bid: bytes
+
+  def __post_init__(self) -> None:
+    """Check data.
+
+    Raises:
+      base.InputError: invalid inputs
+      key.CryptoError: bid does not match the public commitment
+
+    """
+    super(PrivateBid512, self).__post_init__()
+    if len(self.private_key) != 64 or len(self.secret_bid) < 1:  # noqa: PLR2004
+      raise base.InputError(f'invalid private_key or secret_bid: {self}')
+    if self.public_hash != hashes.Hash512(self.public_key + self.private_key + self.secret_bid):
+      raise key.CryptoError(f'inconsistent bid: {self}')
+
+  def __str__(self) -> str:
+    """Safe (no secrets) string representation of the PrivateBid.
+
+    Returns:
+      string representation of PrivateBid without leaking secrets
+
+    """
+    return (
+      'PrivateBid512('
+      f'{super(PrivateBid512, self).__str__()}, '
+      f'private_key={hashes.ObfuscateSecret(self.private_key)}, '
+      f'secret_bid={hashes.ObfuscateSecret(self.secret_bid)})'
+    )
+
+  @classmethod
+  def New(cls, secret: bytes, /) -> Self:
+    """Make the `secret` into a new bid.
+
+    Args:
+      secret (bytes): Any number of bytes (≥1) to bid on (e.g., UTF-8 encoded string)
+
+    Returns:
+      PrivateBid object ready for use (use PublicBid.Copy() to get the public part)
+
+    Raises:
+      base.InputError: invalid inputs
+
+    """
+    # test inputs
+    if len(secret) < 1:
+      raise base.InputError(f'invalid secret length: {len(secret)}')
+    # generate random values
+    public_key: bytes = saferandom.RandBytes(64)  # 512 bits
+    private_key: bytes = saferandom.RandBytes(64)  # 512 bits
+    # build object
+    return cls(
+      public_key=public_key,
+      public_hash=hashes.Hash512(public_key + private_key + secret),
+      private_key=private_key,
+      secret_bid=secret,
+    )