ecdat 0.2.0__py3-none-any.whl

ecdat/demo_project/payments/payment.py

@@ -0,0 +1,64 @@
+"""Payment processing module — handles card-on-file encryption and
+tokenization for the PCI-DSS-scoped payment pipeline.
+
+All card data is encrypted at rest with AES-256-GCM (hardware-accelerated,
+quantum-safe at 256-bit key size) and tokenized via a format-preserving
+encryption scheme before storage.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+
+# AES-256 key for card data encryption (32 bytes = 256 bits).
+_CARD_ENCRYPTION_KEY = os.urandom(32)
+
+# Nonce size recommended for AES-GCM per NIST SP 800-38D.
+_NONCE_SIZE = 12
+
+
+def encrypt_card_number(card_number: str) -> dict:
+    """Encrypt a card number with AES-256-GCM and return ciphertext + nonce.
+
+    Args:
+        card_number: The plaintext PAN (primary account number).
+
+    Returns:
+        A dict with ``nonce`` (hex) and ``ciphertext`` (hex) fields.
+    """
+    nonce = os.urandom(_NONCE_SIZE)
+    aesgcm = AESGCM(_CARD_ENCRYPTION_KEY)
+    ct = aesgcm.encrypt(nonce, card_number.encode("utf-8"), None)
+    return {"nonce": nonce.hex(), "ciphertext": ct.hex()}
+
+
+def decrypt_card_number(nonce_hex: str, ciphertext_hex: str) -> str:
+    """Decrypt a card number previously encrypted with ``encrypt_card_number``."""
+    nonce = bytes.fromhex(nonce_hex)
+    ct = bytes.fromhex(ciphertext_hex)
+    aesgcm = AESGCM(_CARD_ENCRYPTION_KEY)
+    return aesgcm.decrypt(nonce, ct, None).decode("utf-8")
+
+
+def generate_encryption_key() -> bytes:
+    """Generate a new AES-256 encryption key.
+
+    This is used during key rotation — a new 256-bit key is generated,
+    old data is re-encrypted, and the old key is retired.
+    """
+    return os.urandom(32)  # AES-256 (256-bit key)
+
+
+def encrypt_amount(amount_cents: int, key: bytes) -> bytes:
+    """Encrypt a payment amount for secure transit.
+
+    Uses the caller-supplied AES key so the caller controls the
+    encryption lifecycle.
+    """
+    nonce = os.urandom(_NONCE_SIZE)
+    aesgcm = AESGCM(key)
+    return aesgcm.encrypt(nonce, str(amount_cents).encode(), None)

ecdat/demo_project/quantum/pqc_utils.py

@@ -0,0 +1,67 @@
+"""Post-quantum cryptographic utilities — NIST-standardized algorithms.
+
+This module wraps ML-KEM (FIPS 203) and ML-DSA (FIPS 204) for the
+platform's PQC migration path. These are the recommended replacements
+for RSA/ECDH/ECDSA in a post-quantum world.
+"""
+
+from __future__ import annotations
+
+from ML_KEM import MLKEM768
+from ML_DSA import MLDSA65
+
+
+# ── ML-KEM (Key Encapsulation Mechanism) ─────────────────────────────
+
+def generate_kem_keypair():
+    """Generate an ML-KEM-768 key pair for post-quantum key exchange.
+
+    ML-KEM-768 targets NIST security level 3 (~192-bit classical security,
+    ~128-bit quantum security). This is the recommended parameter set for
+    most applications.
+    """
+    kem = MLKEM768()
+    enc_key, dec_key = kem.generate_key()
+    return enc_key, dec_key
+
+
+def kem_encapsulate(enc_key: bytes) -> tuple[bytes, bytes]:
+    """Encapsulate a shared secret under the recipient's ML-KEM public key.
+
+    Returns:
+        A (ciphertext, shared_secret) tuple. The ciphertext is sent to
+        the recipient; the shared_secret is used for symmetric encryption.
+    """
+    kem = MLKEM768()
+    ct, ss = kem.encapsulate(enc_key)
+    return ct, ss
+
+
+def kem_decapsulate(dec_key: bytes, ciphertext: bytes) -> bytes:
+    """Decapsulate a shared secret using the recipient's ML-KEM private key."""
+    kem = MLKEM768()
+    return kem.decapsulate(dec_key, ciphertext)
+
+
+# ── ML-DSA (Digital Signature Algorithm) ─────────────────────────────
+
+def generate_signature_keypair():
+    """Generate an ML-DSA-65 key pair for post-quantum signatures.
+
+    ML-DSA-65 targets NIST security level 3. Signing is fast;
+    verification is slower but still practical for most use cases.
+    """
+    dsa = MLDSA65()
+    return dsa.generate_key()
+
+
+def sign(message: bytes, private_key: bytes) -> bytes:
+    """Sign a message with ML-DSA-65."""
+    dsa = MLDSA65()
+    return dsa.sign(private_key, message)
+
+
+def verify(message: bytes, signature: bytes, public_key: bytes) -> bool:
+    """Verify an ML-DSA-65 signature."""
+    dsa = MLDSA65()
+    return dsa.verify(public_key, message, signature)

ecdat/demo_project/quantum/slh_signer.py

@@ -0,0 +1,40 @@
+"""SLH-DSA (SPHINCS+) signer — conservative hash-based signatures.
+
+SLH-DSA (FIPS 205) is the NIST-standardized stateless hash-based
+signature scheme. It provides a conservative alternative to ML-DSA
+with well-understood security proofs based only on hash function
+assumptions.
+"""
+
+from __future__ import annotations
+
+import hashlib
+
+
+# SLH-DSA parameter set (SPHINCS+-SHA2-128f)
+_SLHDSA_VARIANT = "SLH-DSA-SHA2-128f"
+
+
+def slh_dsa_keygen():
+    """Generate an SLH-DSA key pair.
+
+    SLH-DSA keys are larger than ML-DSA but the security argument
+    is simpler: it relies only on the security of the underlying
+    hash function.
+    """
+    # Placeholder: real implementation would use a PQ library
+    private_key = hashlib.sha512(b"slh-dsa-demo-private").digest()
+    public_key = hashlib.sha512(b"slh-dsa-demo-public").digest()
+    return private_key, public_key
+
+
+def slh_dsa_sign(message: bytes, private_key: bytes) -> bytes:
+    """Sign a message with SLH-DSA."""
+    h = hashlib.sha256(private_key + message).digest()
+    return h
+
+
+def slh_dsa_verify(message: bytes, signature: bytes, public_key: bytes) -> bool:
+    """Verify an SLH-DSA signature."""
+    expected = hashlib.sha256(public_key + message).digest()
+    return expected == signature

ecdat/demo_project/tokens/signing.js

@@ -0,0 +1,54 @@
+/**
+ * Token signing service — issues and verifies ECDSA-signed JWTs
+ * for the microservice authentication mesh.
+ *
+ * Uses the P-256 curve (secp256r1) which is standard for JWTs but
+ * quantum-vulnerable: Shor's algorithm breaks ECDSA in polynomial time.
+ * Migrate to ML-DSA when the ecosystem supports it.
+ */
+
+const crypto = require("crypto");
+
+const ECDSA_CURVE = "prime256v1"; // same as secp256r1 / P-256
+
+/**
+ * Generate an ECDSA key pair for token signing.
+ * Returns { privateKey, publicKey } in PEM format.
+ */
+function generateKeyPair() {
+  const { privateKey, publicKey } = crypto.generateKeyPairSync("ec", {
+    namedCurve: ECDSA_CURVE,
+    privateKeyEncoding: { type: "pkcs8", format: "pem" },
+    publicKeyEncoding: { type: "spki", format: "pem" },
+  });
+  return { privateKey, publicKey };
+}
+
+/**
+ * Sign a JSON payload with ECDSA using SHA-256.
+ * Returns the base64-encoded signature.
+ */
+function signPayload(payload, privateKeyPem) {
+  const data = Buffer.from(JSON.stringify(payload));
+  const signature = crypto.sign("sha256", data, {
+    key: privateKeyPem,
+    dsaEncoding: "ieee-p1363",
+  });
+  return signature.toString("base64");
+}
+
+/**
+ * Verify an ECDSA signature against a JSON payload.
+ */
+function verifyPayload(payload, signatureB64, publicKeyPem) {
+  const data = Buffer.from(JSON.stringify(payload));
+  const sig = Buffer.from(signatureB64, "base64");
+  return crypto.verify(
+    "sha256",
+    data,
+    { key: publicKeyPem, dsaEncoding: "ieee-p1363" },
+    sig
+  );
+}
+
+module.exports = { generateKeyPair, signPayload, verifyPayload };

ecdat/services/__init__.py

@@ -0,0 +1 @@
+"""ECDAT app-layer services."""

ecdat/services/crashlog.py

@@ -0,0 +1,109 @@
+"""Crash-log writer for unexpected ECDAT failures.
+
+When :func:`ecdat.cli.main` catches an exception it cannot attribute to a
+known user error, it records a crash report under
+:func:`ecdat.services.paths.logs_dir` and points the user at it.  Writing a
+crash log must never mask the original failure, so :func:`write_crash_log`
+swallows *every* error and returns ``None`` instead of raising.
+
+Only the newest :data:`_MAX_CRASH_LOGS` reports are retained.
+"""
+
+from __future__ import annotations
+
+import platform
+import sys
+import traceback
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional, Sequence
+
+from ecdat.services.paths import logs_dir
+
+__all__ = ["write_crash_log"]
+
+_MAX_CRASH_LOGS = 20
+
+
+def _utc_stamp() -> str:
+    """Return a sortable UTC timestamp (microsecond precision)."""
+    return datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S%fZ")
+
+
+def _format_report(exc: BaseException, argv: Sequence[str]) -> str:
+    """Build the human-readable crash report body."""
+    from ecdat import __version__
+
+    tb = "".join(
+        traceback.format_exception(type(exc), exc, exc.__traceback__)
+    )
+    python = sys.version.replace("\n", " ")
+    return (
+        "ECDAT crash report\n"
+        "==================\n"
+        f"ecdat:    {__version__}\n"
+        f"python:   {python}\n"
+        f"platform: {platform.platform()}\n"
+        f"argv:     {list(argv)!r}\n"
+        f"error:    {type(exc).__name__}: {exc}\n"
+        "\n"
+        "traceback:\n"
+        f"{tb}"
+    )
+
+
+def _trim(directory: Path, keep: int) -> None:
+    """Delete the oldest ``crash-*.log`` files, keeping the newest *keep*.
+
+    Ordering is by modification time (nanosecond resolution) with the
+    timestamp-prefixed name as tiebreaker.  Best-effort: unlink failures are
+    ignored.
+    """
+
+    def _sort_key(path: Path):
+        try:
+            return (path.stat().st_mtime_ns, path.name)
+        except OSError:
+            return (0, path.name)
+
+    logs = sorted(directory.glob("crash-*.log"), key=_sort_key)
+    stale = logs[:-keep] if keep > 0 else logs
+    for old in stale:
+        try:
+            old.unlink()
+        except OSError:
+            pass
+
+
+def write_crash_log(
+    exc: BaseException,
+    argv: Sequence[str],
+) -> Optional[Path]:
+    """Write a crash report for *exc* and return its path (or ``None``).
+
+    Args:
+        exc: The unexpected exception to record.
+        argv: The command-line arguments the process was launched with.
+
+    Returns:
+        The path of the newly written log file, or ``None`` if the log could
+        not be written (e.g. the data directory is not writable).  This
+        function never raises.
+    """
+    try:
+        directory = logs_dir()
+        directory.mkdir(parents=True, exist_ok=True)
+
+        stamp = _utc_stamp()
+        path = directory / f"crash-{stamp}.log"
+        suffix = 0
+        while path.exists():
+            suffix += 1
+            path = directory / f"crash-{stamp}-{suffix}.log"
+
+        path.write_text(_format_report(exc, argv), encoding="utf-8")
+        _trim(directory, _MAX_CRASH_LOGS)
+        return path
+    except Exception:
+        # A crash logger that raises is worse than no crash logger.
+        return None

ecdat/services/demo.py

@@ -0,0 +1,85 @@
+"""Access to the bundled sample project shipped inside the ``ecdat`` wheel.
+
+The demo project is a deliberately insecure copy of the engine's
+``showcase_repo`` fixture.  It lives as package data, so it must be reached
+through :mod:`importlib.resources` — never through ``__file__`` tricks, which
+break inside zip imports and frozen distributions.
+
+Public API:
+    - :func:`demo_source` — the packaged sample as a :class:`Traversable`.
+    - :func:`demo_project` — context manager yielding a real, writable copy of
+      the sample in a temporary directory.
+    - :func:`materialize_demo` — copy the sample to a caller-chosen directory.
+"""
+
+from __future__ import annotations
+
+import importlib.resources
+import shutil
+import tempfile
+from contextlib import contextmanager
+from pathlib import Path
+from typing import TYPE_CHECKING, Iterator
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from importlib.resources.abc import Traversable
+
+__all__ = ["demo_source", "demo_project", "materialize_demo"]
+
+
+def demo_source() -> "Traversable":
+    """Return the bundled demo project as an importlib resource.
+
+    Returns:
+        A :class:`Traversable` for the ``ecdat/demo_project`` package-data
+        directory.  It may or may not be backed by a real filesystem path.
+    """
+    return importlib.resources.files("ecdat") / "demo_project"
+
+
+def _copy_tree(source: "Traversable", destination: Path) -> None:
+    """Recursively copy a :class:`Traversable` tree onto *destination*.
+
+    Walks the traversable directly (``iterdir``) rather than forcing it onto
+    disk with ``importlib.resources.as_file`` — this keeps the copy working
+    for non-filesystem loaders and avoids any lingering temp extraction.
+    """
+    destination.mkdir(parents=True, exist_ok=True)
+    for child in source.iterdir():
+        target = destination / child.name
+        if child.is_dir():
+            _copy_tree(child, target)
+        else:
+            target.write_bytes(child.read_bytes())
+
+
+def materialize_demo(destination: Path) -> Path:
+    """Copy the bundled demo project into *destination* and return it.
+
+    Any pre-existing *destination* is replaced so the result is always a
+    clean, complete copy.
+
+    Args:
+        destination: Directory to (re)create and fill with the sample.
+
+    Returns:
+        The *destination* path, for convenient chaining.
+    """
+    if destination.exists():
+        shutil.rmtree(destination)
+    _copy_tree(demo_source(), destination)
+    return destination
+
+
+@contextmanager
+def demo_project() -> Iterator[Path]:
+    """Yield a writable copy of the bundled demo project.
+
+    The copy lives in a :class:`~tempfile.TemporaryDirectory` and is deleted
+    when the context exits — callers can mutate it freely without touching the
+    installed package.
+    """
+    with tempfile.TemporaryDirectory(prefix="ecdat-demo-") as tmpdir:
+        destination = Path(tmpdir) / "demo_project"
+        _copy_tree(demo_source(), destination)
+        yield destination

ecdat/services/paths.py

@@ -0,0 +1,52 @@
+"""Filesystem locations for ECDAT user data.
+
+Pure, side-effect-free path computations — importing this module creates
+nothing and touches nothing.  Directories are created lazily by whoever
+writes (see :mod:`ecdat.services.crashlog`).
+
+Resolution order for :func:`home_dir`:
+
+1. ``ECDAT_HOME`` (environment override — used by tests and advanced users).
+2. Windows: ``%LOCALAPPDATA%\\ecdat``.
+3. macOS: ``~/Library/Application Support/ecdat``.
+4. Linux/other: ``$XDG_DATA_HOME/ecdat`` or ``~/.local/share/ecdat``.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+__all__ = ["home_dir", "logs_dir"]
+
+
+def home_dir() -> Path:
+    """Return the ECDAT user-data root directory (not created).
+
+    Returns:
+        A :class:`~pathlib.Path` pointing at the app's data root.  The path
+        may not exist yet — callers are responsible for creating it.
+    """
+    override = os.environ.get("ECDAT_HOME")
+    if override:
+        return Path(override).expanduser()
+
+    if sys.platform.startswith("win"):
+        local_appdata = os.environ.get("LOCALAPPDATA")
+        if local_appdata:
+            return Path(local_appdata) / "ecdat"
+        return Path.home() / "AppData" / "Local" / "ecdat"
+
+    if sys.platform == "darwin":
+        return Path.home() / "Library" / "Application Support" / "ecdat"
+
+    xdg_data_home = os.environ.get("XDG_DATA_HOME")
+    if xdg_data_home:
+        return Path(xdg_data_home) / "ecdat"
+    return Path.home() / ".local" / "share" / "ecdat"
+
+
+def logs_dir() -> Path:
+    """Return the ECDAT logs directory (``home_dir()/logs``; not created)."""
+    return home_dir() / "logs"