keystonecrypto 0.1.0__py3-none-any.whl

keystonecrypto/__init__.py

@@ -0,0 +1,38 @@
+"""keystonecrypto — non-custodial HD wallet primitives for Python.
+
+This is the public API. Submodules are also importable directly for
+advanced users; the names below are the recommended entry points.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from keystonecrypto.derivation import DerivationPath, ExtendedPrivateKey, derive_from_seed
+from keystonecrypto.entropy import STRENGTH_BITS, generate_entropy
+from keystonecrypto.exceptions import KeystoneCryptoError
+from keystonecrypto.keystore import Keystore, Wallet
+from keystonecrypto.mnemonic import Mnemonic
+from keystonecrypto.secret_bytes import SecretBytes
+from keystonecrypto.signing import (
+    Ed25519Signer,
+    Secp256kSchnorrSigner,
+    Secp256kSigner,
+)
+
+__all__ = [
+    "__version__",
+    "KeystoneCryptoError",
+    "SecretBytes",
+    "Mnemonic",
+    "Keystore",
+    "Wallet",
+    "DerivationPath",
+    "ExtendedPrivateKey",
+    "derive_from_seed",
+    "STRENGTH_BITS",
+    "generate_entropy",
+    "Secp256kSigner",
+    "Secp256kSchnorrSigner",
+    "Ed25519Signer",
+]

keystonecrypto/aead.py

@@ -0,0 +1,55 @@
+"""AES-256-GCM authenticated encryption with associated data (AAD).
+
+AAD binds the ciphertext to a context (e.g. keystore version, chain
+identifier). Decryption with mismatched AAD fails the tag check, which
+prevents cross-context ciphertext replay attacks.
+
+Returns nonce separately from ciphertext so the caller can pack them
+into whatever envelope they need. The tag is appended to the
+ciphertext (cryptography's default).
+"""
+
+from __future__ import annotations
+
+import os
+
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+from keystonecrypto.exceptions import KeystoreDecryptionError
+from keystonecrypto.secret_bytes import SecretBytes
+
+__all__ = ["encrypt", "decrypt", "NONCE_LEN", "KEY_LEN"]
+
+NONCE_LEN: int = 12
+KEY_LEN:   int = 32
+
+
+def _as_key(key: SecretBytes) -> bytes:
+    raw = bytes(key)
+    if len(raw) != KEY_LEN:
+        raise ValueError(f"AES-256-GCM key must be {KEY_LEN} bytes, got {len(raw)}")
+    return raw
+
+
+def encrypt(key: SecretBytes, plaintext: bytes, aad: bytes = b"") -> tuple[bytes, bytes]:
+    """Encrypt `plaintext` under `key` with optional associated data.
+
+    Returns (nonce, ciphertext_plus_tag). The tag is appended to the
+    ciphertext per the `cryptography` library convention.
+    """
+    nonce = os.urandom(NONCE_LEN)
+    aes = AESGCM(_as_key(key))
+    ct = aes.encrypt(nonce, plaintext, aad)
+    return nonce, ct
+
+
+def decrypt(key: SecretBytes, nonce: bytes, ciphertext: bytes, aad: bytes = b"") -> bytes:
+    """Decrypt `ciphertext` under `key`. Raises on tag mismatch or wrong key."""
+    if len(nonce) != NONCE_LEN:
+        raise ValueError(f"nonce must be {NONCE_LEN} bytes, got {len(nonce)}")
+    aes = AESGCM(_as_key(key))
+    try:
+        return aes.decrypt(nonce, ciphertext, aad)
+    except Exception as e:
+        # Wrap so callers get a typed exception.
+        raise KeystoreDecryptionError(f"AES-GCM decryption failed: {e}") from e

keystonecrypto/derivation.py

@@ -0,0 +1,218 @@
+"""BIP-32 hierarchical key derivation + BIP-44 path parsing.
+
+Layer 2 module. The derivation primitive uses HMAC-SHA512 and secp256k1
+scalar addition via `coincurve` (so the math is libsecp256k1, not a
+hand-rolled implementation).
+
+Path syntax:
+    m              -> master
+    m/0            -> non-hardened child 0
+    m/0'           -> hardened child 0
+    m/44'/0'/0'/0  -> BIP-44 first receive address
+
+Hardened indices are >= 2^31 in raw form. We represent them as
+`(index, hardened)` pairs to keep the API unambiguous.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import struct
+from typing import Final
+
+from coincurve import PrivateKey
+from pydantic import BaseModel
+
+from keystonecrypto.exceptions import InvalidDerivationPathError
+from keystonecrypto.secret_bytes import SecretBytes
+
+__all__ = [
+    "DerivationPath",
+    "ExtendedPrivateKey",
+    "derive_from_seed",
+    "HARDENED_OFFSET",
+    "SECP256K1_N",
+]
+
+HARDENED_OFFSET: Final[int] = 0x80000000
+_MAX_CHILD_INDEX:  Final[int] = 0xFFFFFFFF
+
+# Order of the secp256k1 prime-order subgroup.
+SECP256K1_N: Final[int] = (
+    0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141
+)
+
+
+class DerivationPath(BaseModel):
+    """A parsed BIP-32 derivation path."""
+
+    model_config = {"frozen": True}
+
+    indices: tuple[tuple[int, bool], ...]  # (index, hardened) per component
+
+    @classmethod
+    def parse(cls, s: str) -> "DerivationPath":
+        s = s.strip()
+        if s in ("", "m"):
+            return cls(indices=())
+        if not s.startswith("m/"):
+            raise InvalidDerivationPathError(
+                f"path must start with 'm/', got {s!r}"
+            )
+        parts = s[2:].split("/")
+        out: list[tuple[int, bool]] = []
+        for part in parts:
+            hardened = part.endswith("'") or part.endswith("h")
+            num_str = part.rstrip("'h")
+            if not num_str.isdigit():
+                raise InvalidDerivationPathError(f"non-numeric component: {part!r}")
+            idx = int(num_str)
+            if idx < 0 or idx > 0x7FFFFFFF:
+                raise InvalidDerivationPathError(f"index out of range: {idx}")
+            out.append((idx, hardened))
+        return cls(indices=tuple(out))
+
+
+class ExtendedPrivateKey:
+    """A BIP-32 extended private key (xprv): key + chain code + metadata."""
+
+    __slots__ = ("_sk", "_cc", "_depth", "_pfp", "_child")
+
+    def __init__(
+        self,
+        secret_key: SecretBytes,
+        chain_code: SecretBytes,
+        depth: int,
+        parent_fingerprint: bytes,
+        child_number: int,
+    ) -> None:
+        self._sk = secret_key
+        self._cc = chain_code
+        self._depth = depth
+        self._pfp = parent_fingerprint
+        self._child = child_number
+
+    @classmethod
+    def master(cls, seed: SecretBytes) -> "ExtendedPrivateKey":
+        I = hmac.new(b"Bitcoin seed", bytes(seed), hashlib.sha512).digest()
+        IL, IR = I[:32], I[32:]
+        return cls(
+            secret_key=SecretBytes(IL),
+            chain_code=SecretBytes(IR),
+            depth=0,
+            parent_fingerprint=b"\x00\x00\x00\x00",
+            child_number=0,
+        )
+
+    @property
+    def private_key(self) -> SecretBytes:
+        return self._sk
+
+    @property
+    def chain_code(self) -> SecretBytes:
+        return self._cc
+
+    @property
+    def depth(self) -> int:
+        return self._depth
+
+    @property
+    def child_number(self) -> int:
+        return self._child
+
+    def fingerprint(self) -> bytes:
+        """BIP-32 key fingerprint = first 4 bytes of HASH160(pubkey)."""
+        pk = PrivateKey(bytes(self._sk)).public_key.format(compressed=True)
+        h160 = hashlib.new("ripemd160", hashlib.sha256(pk).digest()).digest()
+        return h160[:4]
+
+    @property
+    def parent_fingerprint(self) -> bytes:
+        return self._pfp
+
+    def derive(self, index: int, hardened: bool = False) -> "ExtendedPrivateKey":
+        if index < 0 or index > 0x7FFFFFFF:
+            raise ValueError(f"index out of range: {index}")
+        if hardened:
+            index += HARDENED_OFFSET
+        if index < 0 or index > _MAX_CHILD_INDEX:
+            raise ValueError(f"effective child index out of range: {index}")
+
+        if index >= HARDENED_OFFSET:
+            # Hardened: data = 0x00 || ser256(kpar) || ser32(i)
+            data = b"\x00" + bytes(self._sk) + struct.pack(">I", index)
+        else:
+            # Non-hardened: data = serP(Kpar) || ser32(i)
+            pub = PrivateKey(bytes(self._sk)).public_key.format(compressed=True)
+            data = pub + struct.pack(">I", index)
+
+        I = hmac.new(bytes(self._cc), data, hashlib.sha512).digest()
+        IL, IR = I[:32], I[32:]
+        # child_key = (IL + kpar) mod n
+        Il_int = int.from_bytes(IL, "big")
+        kpar_int = int.from_bytes(bytes(self._sk), "big")
+        if Il_int >= SECP256K1_N:
+            raise ValueError("derivation produced invalid child key (IL >= n)")
+        child_int = (Il_int + kpar_int) % SECP256K1_N
+        if child_int == 0:
+            raise ValueError("derivation produced zero child key")
+        child_key = child_int.to_bytes(32, "big")
+
+        return ExtendedPrivateKey(
+            secret_key=SecretBytes(child_key),
+            chain_code=SecretBytes(IR),
+            depth=self._depth + 1,
+            parent_fingerprint=self.fingerprint(),
+            child_number=index,
+        )
+
+    def to_base58(self, network: str = "mainnet") -> str:
+        """Serialize as a BIP-32 xprv (private key form)."""
+        version = {
+            "mainnet": b"\x04\x88\xad\xe4",
+            "testnet": b"\x04\x35\x83\x94",
+        }[network]
+        raw = (
+            version
+            + bytes([self._depth])
+            + self._pfp
+            + struct.pack(">I", self._child)
+            + bytes(self._cc)
+            + b"\x00"
+            + bytes(self._sk)
+        )
+        # Double-SHA256 checksum.
+        checksum = hashlib.sha256(hashlib.sha256(raw).digest()).digest()[:4]
+        return _b58encode(raw + checksum)
+
+
+def derive_from_seed(seed: SecretBytes, path: DerivationPath) -> ExtendedPrivateKey:
+    """Derive an extended private key from a seed and a BIP-32 path."""
+    key: ExtendedPrivateKey = ExtendedPrivateKey.master(seed)
+    for index, hardened in path.indices:
+        key = key.derive(index, hardened=hardened)
+    return key
+
+
+# --- base58 (minimal; avoids an extra dep for the core) ---
+
+_B58_ALPHABET = b"123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
+
+
+def _b58encode(data: bytes) -> str:
+    n = int.from_bytes(data, "big")
+    if n == 0:
+        return _B58_ALPHABET[0:1].decode()
+    out = bytearray()
+    while n:
+        n, r = divmod(n, 58)
+        out.append(_B58_ALPHABET[r])
+    # Preserve leading zero bytes.
+    for b in data:
+        if b == 0:
+            out.append(_B58_ALPHABET[0])
+        else:
+            break
+    out.reverse()
+    return out.decode()

keystonecrypto/entropy.py

@@ -0,0 +1,38 @@
+"""Cryptographically-secure entropy generation.
+
+Wraps `secrets.token_bytes` and returns a SecretBytes. Validates bit
+lengths to match the BIP-39 allowed strengths so the same module can
+feed both raw entropy generation and mnemonic generation.
+"""
+
+from __future__ import annotations
+
+import secrets
+
+from keystonecrypto.secret_bytes import SecretBytes
+
+__all__ = ["STRENGTH_BITS", "generate_entropy"]
+
+# BIP-39 § "Entropy" — allowed entropy sizes in bits.
+STRENGTH_BITS: tuple[int, ...] = (128, 160, 192, 224, 256)
+
+_MIN_BITS = min(STRENGTH_BITS)
+_MAX_BITS = max(STRENGTH_BITS)
+
+
+def generate_entropy(bits: int) -> SecretBytes:
+    """Generate `bits` bits of cryptographically-secure random data.
+
+    Returns: SecretBytes of length `bits // 8`.
+
+    Raises:
+        ValueError: if `bits` is not a multiple of 8 or is outside the
+            BIP-39 allowed range.
+    """
+    if bits % 8 != 0:
+        raise ValueError(f"bits must be a multiple of 8, got {bits}")
+    if bits < _MIN_BITS or bits > _MAX_BITS:
+        raise ValueError(
+            f"bits must be in [{_MIN_BITS}, {_MAX_BITS}], got {bits}"
+        )
+    return SecretBytes(secrets.token_bytes(bits // 8))

keystonecrypto/envelope.py

@@ -0,0 +1,210 @@
+"""Binary envelope for encrypted keystores (spec §6).
+
+Layout (big-endian, exact byte counts):
+
+    Header (66 bytes):
+        magic:        4   "KST1"
+        version:      1   0x01
+        kdf_id:       1   0x01 = Argon2id
+        kdf_params:  32   (time_cost:4 | memory_cost:4 |
+                           parallelism:4 | hash_len:4 |
+                           version:4  | reserved:12)
+        salt:        16
+        nonce:       12
+    Body (variable):
+        ciphertext:  N    (includes appended 16-byte GCM tag)
+
+Plaintext structure before encryption:
+
+        seed_length:  1
+        seed:         seed_length
+        created_at:   8   (BE unix timestamp)
+        flags:        1   (bit 0: has_passphrase)
+        reserved:     6   (zero)
+
+AAD = version || kdf_id. Decryption with mismatched AAD fails.
+"""
+
+from __future__ import annotations
+
+import secrets as _secrets
+import struct
+import time
+from typing import Final
+
+from pydantic import BaseModel
+
+from keystonecrypto.aead import NONCE_LEN, decrypt as _decrypt
+from keystonecrypto.aead import encrypt as _encrypt
+from keystonecrypto.exceptions import (
+    KeystoreDecryptionError,
+    KeystoreVersionError,
+)
+from keystonecrypto.kdf import Argon2Params, derive_key
+from keystonecrypto.secret_bytes import SecretBytes
+
+__all__ = [
+    "MAGIC",
+    "VERSION",
+    "Envelope",
+    "UnpackedKeystore",
+    "HEADER_LEN",
+]
+
+MAGIC:   Final[bytes] = b"KST1"
+VERSION: Final[int]   = 1
+
+_HEADER_LEN:        Final[int] = 4 + 1 + 1 + 32 + 16 + NONCE_LEN  # = 66
+_GCM_TAG_LEN:       Final[int] = 16
+_PLAINTEXT_OVERHEAD: Final[int] = 1 + 8 + 1 + 6                  # = 16 (excluding seed)
+
+HEADER_LEN: Final[int] = _HEADER_LEN
+
+# Offsets inside the header.
+_OFF_MAGIC:    Final[int] = 0
+_OFF_VERSION:  Final[int] = 4
+_OFF_KDF_ID:   Final[int] = 5
+_OFF_KDF:      Final[int] = 6
+_OFF_SALT:     Final[int] = 38
+_OFF_NONCE:    Final[int] = 54
+
+
+class UnpackedKeystore(BaseModel):
+    """Result of a successful envelope decryption."""
+
+    model_config = {"frozen": True}
+
+    seed:           SecretBytes
+    has_passphrase: bool
+    created_at:     int
+
+
+class Envelope:
+    """Static pack/unpack helpers for the keystore binary envelope."""
+
+    @staticmethod
+    def _pack_kdf_params(p: Argon2Params) -> bytes:
+        return struct.pack(
+            ">IIII I 12x",
+            p.time_cost, p.memory_cost, p.parallelism, p.hash_len,
+            p.version,
+        )
+
+    @staticmethod
+    def _unpack_kdf_params(blob: bytes) -> Argon2Params:
+        # Matches `_pack_kdf_params`: 5 unsigned ints (20 bytes) + 12 bytes reserved.
+        # Total 32 bytes.
+        if len(blob) != 32:
+            raise KeystoreDecryptionError(f"kdf_params section wrong size: {len(blob)} bytes")
+        (t, m, par, hl, v) = struct.unpack(">IIIII 12x", blob)
+        return Argon2Params.for_testing(
+            time_cost=t, memory_cost=m, parallelism=par,
+            hash_len=hl, salt_len=16, version=v,
+        )
+
+    @staticmethod
+    def _aad(version: int, kdf_id: int) -> bytes:
+        return bytes([version, kdf_id])
+
+    @staticmethod
+    def pack(
+        seed: SecretBytes,
+        password: SecretBytes,
+        params: Argon2Params,
+        kdf_id: int = 1,
+        has_passphrase: bool = False,
+        created_at: int | None = None,
+    ) -> bytes:
+        """Pack and encrypt a seed into a keystore blob.
+
+        The caller passes `password` here. If a BIP-39 passphrase is
+        used, the caller is expected to concatenate it with the
+        decryption password *before* calling pack; the envelope itself
+        is passphrase-agnostic.
+        """
+        if kdf_id != 1:
+            raise ValueError(f"unsupported kdf_id {kdf_id} (only 1 = Argon2id)")
+        if len(seed) > 255:
+            raise ValueError(f"seed too long: {len(seed)} > 255 bytes")
+        if params.hash_len != 32:
+            raise ValueError(f"envelope requires hash_len=32, got {params.hash_len}")
+
+        salt = _secrets.token_bytes(params.salt_len)
+        key, _salt = derive_key(password, params, salt=salt)
+        ts = int(created_at if created_at is not None else time.time())
+        flags = 0x01 if has_passphrase else 0x00
+        plaintext = (
+            bytes([len(seed)])
+            + bytes(seed)
+            + struct.pack(">q", ts)
+            + bytes([flags])
+            + b"\x00" * 6
+        )
+        nonce, ciphertext = _encrypt(key, plaintext, aad=Envelope._aad(VERSION, kdf_id))
+
+        return (
+            MAGIC
+            + bytes([VERSION, kdf_id])
+            + Envelope._pack_kdf_params(params)
+            + salt
+            + nonce
+            + ciphertext
+        )
+
+    @staticmethod
+    def unpack(blob: bytes, password: SecretBytes) -> UnpackedKeystore:
+        """Decrypt and validate a keystore blob."""
+        if len(blob) < _HEADER_LEN + _GCM_TAG_LEN:
+            raise KeystoreDecryptionError(f"blob too short: {len(blob)} bytes")
+
+        if blob[_OFF_MAGIC:_OFF_MAGIC + 4] != MAGIC:
+            raise KeystoreVersionError("bad magic; not a keystonecrypto keystore")
+
+        version = blob[_OFF_VERSION]
+        if version != VERSION:
+            raise KeystoreVersionError(
+                f"unsupported keystore version {version}; "
+                f"this build of keystonecrypto only supports version {VERSION}"
+            )
+
+        kdf_id = blob[_OFF_KDF_ID]
+
+        params = Envelope._unpack_kdf_params(blob[_OFF_KDF:_OFF_KDF + 32])
+        if params.hash_len != _GCM_TAG_LEN + _GCM_TAG_LEN:
+            pass  # hash_len != 32 will be caught at KDF time
+        salt = blob[_OFF_SALT:_OFF_SALT + 16]
+        nonce = blob[_OFF_NONCE:_OFF_NONCE + NONCE_LEN]
+        ciphertext = blob[_HEADER_LEN:]
+
+        # kdf_id bound into the AAD so tampering causes AEAD failure
+        # (KeystoreDecryptionError), not an early format rejection.
+        # We still surface an unsupported-kdf_id error if AEAD happens
+        # to succeed somehow (e.g. crafted blob).
+        key, _ = derive_key(password, params, salt=salt)
+
+        try:
+            plaintext = _decrypt(key, nonce, ciphertext,
+                                 aad=Envelope._aad(version, kdf_id))
+        except KeystoreDecryptionError:
+            raise
+
+        if kdf_id != 1:
+            raise KeystoreVersionError(f"unsupported kdf_id {kdf_id}")
+
+        return Envelope._unpack_plaintext(plaintext)
+
+    @staticmethod
+    def _unpack_plaintext(plaintext: bytes) -> UnpackedKeystore:
+        if len(plaintext) < 1 + 8 + 1 + 6:
+            raise KeystoreDecryptionError("plaintext too short")
+        seed_len = plaintext[0]
+        if len(plaintext) < 1 + seed_len + 8 + 1 + 6:
+            raise KeystoreDecryptionError("seed length inconsistent")
+        seed = SecretBytes(plaintext[1:1 + seed_len])
+        created_at = struct.unpack(">q", plaintext[1 + seed_len:1 + seed_len + 8])[0]
+        flags = plaintext[1 + seed_len + 8]
+        return UnpackedKeystore(
+            seed=seed,
+            has_passphrase=bool(flags & 0x01),
+            created_at=created_at,
+        )

keystonecrypto/exceptions.py

@@ -0,0 +1,41 @@
+"""Exception hierarchy for keystonecrypto."""
+
+from __future__ import annotations
+
+__all__ = [
+    "KeystoneCryptoError",
+    "InvalidMnemonicError",
+    "InvalidPassphraseError",
+    "InvalidDerivationPathError",
+    "KeystoreVersionError",
+    "KeystoreDecryptionError",
+    "SignatureError",
+]
+
+
+class KeystoneCryptoError(Exception):
+    """Base exception for all keystonecrypto errors."""
+
+
+class InvalidMnemonicError(KeystoneCryptoError):
+    """Mnemonic word, length, or checksum is invalid."""
+
+
+class InvalidPassphraseError(KeystoneCryptoError):
+    """BIP-39 passphrase is malformed (e.g. invalid UTF-8 after NFKD)."""
+
+
+class InvalidDerivationPathError(KeystoneCryptoError):
+    """BIP-32 derivation path cannot be parsed or is out of range."""
+
+
+class KeystoreVersionError(KeystoneCryptoError):
+    """Keystore envelope version is not supported by this library version."""
+
+
+class KeystoreDecryptionError(KeystoneCryptoError):
+    """Keystore decryption failed: wrong passphrase, tampered ciphertext, or corrupt header."""
+
+
+class SignatureError(KeystoneCryptoError):
+    """Signing operation failed or signature could not be verified."""