stealth-message-cli 0.1.0__py3-none-any.whl

stealth_cli/config.py

@@ -0,0 +1,132 @@
+"""Configuration and key persistence (platformdirs-based).
+
+Directory layout (example on macOS):
+    ~/Library/Application Support/stealth-message/
+    ├── config.json          ← alias and settings
+    └── keys/
+        ├── private.asc      ← ASCII-armored private key  (mode 0600)
+        └── public.asc       ← ASCII-armored public key   (mode 0644)
+
+The private key file is stored with permissions 0600 so only the owning
+user can read it. The passphrase is NEVER persisted anywhere on disk.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+from pathlib import Path
+from typing import Optional
+
+from platformdirs import user_config_dir
+
+APP_NAME = "stealth-message"
+
+
+# --------------------------------------------------------------------------- #
+# Paths                                                                         #
+# --------------------------------------------------------------------------- #
+
+
+def _config_dir() -> Path:
+    return Path(user_config_dir(APP_NAME))
+
+
+def _keys_dir() -> Path:
+    return _config_dir() / "keys"
+
+
+def config_file() -> Path:
+    return _config_dir() / "config.json"
+
+
+def private_key_file() -> Path:
+    return _keys_dir() / "private.asc"
+
+
+def public_key_file() -> Path:
+    return _keys_dir() / "public.asc"
+
+
+# --------------------------------------------------------------------------- #
+# First-use detection                                                           #
+# --------------------------------------------------------------------------- #
+
+
+def is_first_use() -> bool:
+    """Return True if no saved keypair exists yet."""
+    return not (private_key_file().exists() and public_key_file().exists())
+
+
+# --------------------------------------------------------------------------- #
+# Persistence                                                                   #
+# --------------------------------------------------------------------------- #
+
+
+def save_keypair(
+    armored_private: str,
+    armored_public: str,
+    alias: str,
+) -> None:
+    """Persist the PGP keypair and alias to disk.
+
+    The private key is written with mode 0600 (owner read/write only).
+
+    Args:
+        armored_private: ASCII-armored PGP private key block.
+        armored_public:  ASCII-armored PGP public key block.
+        alias:           Human-readable name stored in config.json.
+    """
+    _config_dir().mkdir(parents=True, exist_ok=True)
+    _keys_dir().mkdir(parents=True, exist_ok=True)
+
+    # Write private key — restrictive permissions.
+    priv_path = private_key_file()
+    priv_path.write_text(armored_private, encoding="utf-8")
+    priv_path.chmod(stat.S_IRUSR | stat.S_IWUSR)  # 0600
+
+    # Write public key — readable by owner.
+    pub_path = public_key_file()
+    pub_path.write_text(armored_public, encoding="utf-8")
+    pub_path.chmod(stat.S_IRUSR | stat.S_IWUSR | stat.S_IRGRP | stat.S_IROTH)  # 0644
+
+    # Write config.
+    cfg = {"alias": alias}
+    config_file().write_text(json.dumps(cfg, indent=2), encoding="utf-8")
+
+
+def load_alias() -> Optional[str]:
+    """Load the stored alias from config.json, or None if not found."""
+    path = config_file()
+    if not path.exists():
+        return None
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        return str(data.get("alias", "")) or None
+    except (json.JSONDecodeError, OSError):
+        return None
+
+
+def load_armored_private() -> str:
+    """Read the ASCII-armored private key from disk.
+
+    Raises:
+        FileNotFoundError: If the key file does not exist (first use).
+        OSError: On permission or I/O errors.
+    """
+    return private_key_file().read_text(encoding="utf-8")
+
+
+def load_armored_public() -> str:
+    """Read the ASCII-armored public key from disk."""
+    return public_key_file().read_text(encoding="utf-8")
+
+
+def delete_keypair() -> None:
+    """Delete the stored keypair and config, reverting to first-use state."""
+    for path in (private_key_file(), public_key_file(), config_file()):
+        try:
+            path.unlink()
+        except FileNotFoundError:
+            pass

stealth_cli/crypto/keys.py

@@ -0,0 +1,120 @@
+"""PGP key generation, loading and fingerprint utilities.
+
+All public functions accept and return ``str`` (ASCII-armored PGP blocks).
+Internal conversion to/from binary is handled here; callers never touch bytes.
+
+Security notes:
+- Private keys returned by ``load_private_key`` are locked (protected).
+  Callers must use ``key.unlock(passphrase)`` as a context manager to perform
+  crypto operations, keeping the passphrase in memory only for the duration.
+- Passphrases are never logged, stored, or included in exceptions.
+"""
+
+import pgpy
+from pgpy.constants import (
+    CompressionAlgorithm,
+    HashAlgorithm,
+    KeyFlags,
+    PubKeyAlgorithm,
+    SymmetricKeyAlgorithm,
+)
+
+
+def generate_keypair(alias: str, passphrase: str) -> tuple[str, str]:
+    """Generate a passphrase-protected RSA-4096 keypair.
+
+    Args:
+        alias: Human-readable name embedded in the key UID (max 64 chars).
+        passphrase: Passphrase used to protect the private key.
+
+    Returns:
+        A ``(armored_private, armored_public)`` tuple of ASCII-armored strings.
+    """
+    key = pgpy.PGPKey.new(PubKeyAlgorithm.RSAEncryptOrSign, 4096)
+    uid = pgpy.PGPUID.new(alias)
+    key.add_uid(
+        uid,
+        usage={
+            KeyFlags.Sign,
+            KeyFlags.EncryptCommunications,
+            KeyFlags.EncryptStorage,
+        },
+        hashes=[HashAlgorithm.SHA512, HashAlgorithm.SHA384, HashAlgorithm.SHA256],
+        ciphers=[SymmetricKeyAlgorithm.AES256],
+        compression=[CompressionAlgorithm.ZLIB, CompressionAlgorithm.Uncompressed],
+    )
+    key.protect(passphrase, SymmetricKeyAlgorithm.AES256, HashAlgorithm.SHA256)
+
+    armored_private = str(key)
+    armored_public = str(key.pubkey)
+    return armored_private, armored_public
+
+
+def load_private_key(armored: str, passphrase: str) -> pgpy.PGPKey:
+    """Load and validate a passphrase-protected private key.
+
+    The returned key is locked. Use ``with key.unlock(passphrase)`` to
+    temporarily unlock it for crypto operations.
+
+    Args:
+        armored: ASCII-armored PGP private key block.
+        passphrase: Passphrase that protects the key.
+
+    Returns:
+        The loaded ``pgpy.PGPKey`` in locked (protected) state.
+
+    Raises:
+        ValueError: If ``armored`` does not contain a private key.
+        pgpy.errors.PGPDecryptionError: If ``passphrase`` is incorrect.
+    """
+    if "BEGIN PGP PRIVATE KEY BLOCK" not in armored:
+        raise ValueError("armored does not contain a private key")
+
+    key, _ = pgpy.PGPKey.from_blob(armored)
+
+    # Validate the passphrase immediately; raises PGPDecryptionError if wrong.
+    with key.unlock(passphrase):
+        pass
+
+    return key
+
+
+def load_public_key(armored: str) -> pgpy.PGPKey:
+    """Load a PGP public key from an ASCII-armored block.
+
+    Args:
+        armored: ASCII-armored PGP public key block.
+
+    Returns:
+        The loaded ``pgpy.PGPKey`` (public only).
+
+    Raises:
+        ValueError: If ``armored`` contains a private key instead of a public key.
+    """
+    if "BEGIN PGP PRIVATE KEY BLOCK" in armored:
+        raise ValueError(
+            "armored contains a private key; use load_private_key instead"
+        )
+
+    key, _ = pgpy.PGPKey.from_blob(armored)
+    return key
+
+
+def get_fingerprint(armored_public: str) -> str:
+    """Return the fingerprint of a public key formatted in groups of 4 characters.
+
+    Example output: ``"A1B2 C3D4 E5F6 7890 ABCD EF12 3456 7890 ABCD EF12"``
+
+    The grouped format is the standard presentation for manual out-of-band
+    verification between users (see docs/protocol.md §6).
+
+    Args:
+        armored_public: ASCII-armored PGP public key block.
+
+    Returns:
+        40-character hex fingerprint split into 10 groups of 4, separated
+        by single spaces (total length: 49 characters).
+    """
+    key = load_public_key(armored_public)
+    raw = str(key.fingerprint).upper()
+    return " ".join(raw[i : i + 4] for i in range(0, len(raw), 4))

stealth_cli/crypto/messages.py

@@ -0,0 +1,130 @@
+"""PGP message encryption and decryption (protocol.md §2.1).
+
+All public functions accept and return ``str``. Internal conversion between
+``str``, ``bytes`` and pgpy objects is handled here; callers never touch bytes.
+
+Caller contract:
+    The ``pgpy.PGPKey`` arguments must be **already unlocked** via
+    ``with key.unlock(passphrase)`` before calling these functions.
+    Managing the passphrase and the unlock lifetime is the UI layer's
+    responsibility (cli/stealth_cli/ui/), not this module's.
+
+Encoding pipeline (encrypt):
+    plaintext str
+        → pgpy.PGPMessage  (literal data packet)
+        → sign with sender's private key  (inline one-pass signature)
+        → encrypt with recipient's public key  (PGP encrypted message)
+        → ASCII-armored str
+        → Base64 URL-safe str  ← this is the JSON "payload" field
+
+Decoding pipeline (decrypt):
+    Base64 URL-safe str  (JSON "payload" field)
+        → ASCII-armored str
+        → pgpy encrypted message
+        → decrypt with recipient's private key
+        → verify inline signature with sender's public key
+        → plaintext str  (only if signature is valid)
+"""
+
+import base64
+
+import pgpy
+
+from stealth_cli.crypto.keys import load_public_key
+from stealth_cli.exceptions import SignatureError
+
+
+def encrypt(
+    plaintext: str,
+    recipient_pubkey: str,
+    sender_privkey: pgpy.PGPKey,
+) -> str:
+    """Encrypt and sign a plaintext message.
+
+    The output is suitable for use as the ``"payload"`` field in a
+    protocol.md §2.1 message JSON object.
+
+    Args:
+        plaintext: UTF-8 text to encrypt.
+        recipient_pubkey: ASCII-armored PGP public key of the recipient.
+        sender_privkey: Sender's private key, **already unlocked** by the
+            caller via ``with sender_privkey.unlock(passphrase)``.
+
+    Returns:
+        Base64 URL-safe string containing the ASCII-armored PGP encrypted
+        message (sign-then-encrypt).
+    """
+    pub = load_public_key(recipient_pubkey)
+
+    msg = pgpy.PGPMessage.new(plaintext)
+
+    # Sign with sender's private key (key must be unlocked by the caller).
+    msg |= sender_privkey.sign(msg)
+
+    # Encrypt with recipient's public key.
+    encrypted = pub.encrypt(msg)
+
+    # ASCII-armor → UTF-8 bytes → Base64 URL-safe string.
+    armored = str(encrypted)
+    return base64.urlsafe_b64encode(armored.encode("utf-8")).decode("ascii")
+
+
+def decrypt(
+    payload: str,
+    recipient_privkey: pgpy.PGPKey,
+    sender_pubkey: str,
+) -> str:
+    """Decrypt a payload and verify the sender's signature.
+
+    Implements the decryption and verification steps of protocol.md §2.1.
+    The message is returned **only** if the signature is valid; otherwise
+    ``SignatureError`` is raised so the caller can discard the message.
+
+    Args:
+        payload: Base64 URL-safe string from the ``"payload"`` JSON field.
+        recipient_privkey: Recipient's private key, **already unlocked** by
+            the caller via ``with recipient_privkey.unlock(passphrase)``.
+        sender_pubkey: ASCII-armored PGP public key of the sender.
+
+    Returns:
+        Decrypted plaintext as a UTF-8 string.
+
+    Raises:
+        SignatureError: If the signature is invalid, missing, or cannot be
+            verified with ``sender_pubkey``. Callers must never display the
+            plaintext when this exception is raised (protocol.md §2.1).
+    """
+    # Base64 URL-safe decode → ASCII-armored PGP message.
+    # Add padding so urlsafe_b64decode never fails on missing '=' chars.
+    armored = base64.urlsafe_b64decode(
+        payload.encode("ascii") + b"=="
+    ).decode("utf-8")
+
+    # PGPMessage.from_blob returns the message object directly (unlike
+    # PGPKey.from_blob which returns a (key, extras) tuple). Unpacking it
+    # would iterate over internal packets — use the raw return value.
+    result = pgpy.PGPMessage.from_blob(armored)
+    encrypted_msg = result[0] if isinstance(result, tuple) else result
+
+    # Decrypt (recipient_privkey must already be unlocked by the caller).
+    decrypted = recipient_privkey.decrypt(encrypted_msg)
+
+    # Verify the inline signature with the sender's public key.
+    # protocol.md §2.1: "If the signature is not valid, discard the message."
+    sender_pub = load_public_key(sender_pubkey)
+    try:
+        verification = sender_pub.verify(decrypted)
+        if not verification:
+            raise SignatureError(
+                "PGP signature is invalid — message discarded (protocol.md §2.1)"
+            )
+    except pgpy.errors.PGPError as exc:
+        raise SignatureError(
+            "PGP signature verification failed — message discarded (protocol.md §2.1)"
+        ) from exc
+
+    # Return plaintext as str; pgpy may give bytes for binary literal packets.
+    content = decrypted.message
+    if isinstance(content, (bytes, bytearray)):
+        return content.decode("utf-8")
+    return str(content)

stealth_cli/exceptions.py

@@ -0,0 +1,29 @@
+"""Custom exceptions for stealth-message CLI.
+
+All exceptions raised by stealth_cli modules are defined here.
+Network and protocol error codes follow docs/protocol.md §4.
+"""
+
+
+class StealthError(Exception):
+    """Base exception for all stealth-message errors."""
+
+
+class SignatureError(StealthError):
+    """Raised when a PGP signature is missing, invalid, or cannot be verified.
+
+    Callers receiving this exception must discard the message and notify the
+    user — never display plaintext from an unverified message (protocol.md §2.1).
+    """
+
+
+class ProtocolError(StealthError):
+    """Raised when a received WebSocket message violates the protocol spec.
+
+    Attributes:
+        code: Numeric error code defined in protocol.md §4.
+    """
+
+    def __init__(self, message: str, code: int) -> None:
+        super().__init__(message)
+        self.code = code