velophex 0.2.0__py3-none-any.whl

velophex/signing.py

@@ -0,0 +1,425 @@
+"""Detached package signing: ``velophex/signature.json`` (ADR-P003).
+
+This is the Python twin of ``Velophex.Workflow.Security.Signing.DetachedPackageSigner``, and it
+exists so that a package the CLI publishes can be trusted by the same pinned-certificate check
+the Orchestrator and the Runner already apply to a Studio package. What it writes is read by
+``VeloPhex.Platform.Contracts.Packages.PackageSignatureVerifier``, which fails closed, so every
+detail here is a compatibility requirement rather than a choice:
+
+* The signed bytes are :func:`create_payload`, not the bare hash. Signing the package's identity
+  alongside the hash is what stops a valid signature being lifted onto another package.
+* The identity in the document comes from the manifest, never from a CLI argument: the verifier
+  refuses a document whose ``packageId``/``packageVersion`` differ from the manifest's, so an
+  argument could only ever produce a package that is refused on upload.
+* ECDSA signatures are IEEE P1363 (fixed-width ``r || s``), because that is what .NET's
+  ``ECDsa.VerifyData`` reads; :mod:`cryptography` produces DER and has to be converted.
+
+``cryptography`` is imported lazily and is an optional dependency (``velophex[signing]``). Only a
+publisher signs; a robot only ever verifies, and ADR-P008 keeps its environment minimal.
+
+The private key never leaves :class:`SigningKey`. Nothing in this module formats it, puts it in a
+message or lets a third-party exception carrying it escape.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import zipfile
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from io import BytesIO
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Any, Final
+
+from velophex import _json
+from velophex.contracts.package import PackageLayout
+from velophex.errors import VelophexError
+from velophex.packaging import ENTRY_TIMESTAMP
+
+__all__ = [
+    "CURRENT_FORMAT_VERSION",
+    "ECDSA_SHA512",
+    "FORMAT_NAME",
+    "MINIMUM_FORMAT_VERSION",
+    "RSA_PSS_SHA512",
+    "SIGNED_AT_FORMAT",
+    "SIGNING_EXTRA_HINT",
+    "SigningError",
+    "SigningKey",
+    "create_payload",
+    "create_signature_document",
+    "format_signed_at",
+    "load_signing_key",
+    "sign_package_bytes",
+    "sign_package_file",
+]
+
+FORMAT_NAME: Final = "velophex.package-signature"
+
+#: Format 2 signs the signing time (ADR-P012): the verifier checks the certificate as of
+#: ``signedAt`` instead of now, so the signature outlives the certificate. Format 1 is still
+#: verified everywhere but dies with its certificate; nothing writes it any more.
+CURRENT_FORMAT_VERSION: Final = 2
+MINIMUM_FORMAT_VERSION: Final = 1
+
+#: The one spelling of ``signedAt``: UTC to the second, ``Z`` suffix, no fraction, no offset.
+#: Byte for byte ``PackageSignature.SignedAtFormat``; the payload carries it verbatim.
+SIGNED_AT_FORMAT: Final = "%Y-%m-%dT%H:%M:%SZ"
+
+#: RSA with PSS padding over SHA-512; the salt is the hash length, as .NET's ``RSASignaturePadding.Pss``.
+RSA_PSS_SHA512: Final = "RSASSA-PSS-SHA512"
+
+#: ECDSA over SHA-512, signature in IEEE P1363 form.
+ECDSA_SHA512: Final = "ECDSA-SHA512"
+
+#: What a signature document larger than this is: not one of ours. Mirrors the verifier's limit.
+MAXIMUM_DOCUMENT_BYTES: Final = 64 * 1024
+
+#: The verifier refuses a larger certificate unread, so refuse it here rather than on upload.
+MAXIMUM_CERTIFICATE_BYTES: Final = 16 * 1024
+
+SIGNING_EXTRA_HINT: Final = (
+    "Signing needs the 'cryptography' package, which the plain SDK install deliberately leaves out. "
+    'Install it with: uv add "velophex[signing]"   (or: uv pip install "cryptography>=43,<47")'
+)
+
+
+class SigningError(VelophexError):
+    """Signing could not be completed.
+
+    Carries only what the operator has to act on. A password or a private key is never part of
+    the message, and a third-party exception that might quote one is never chained to it.
+    """
+
+
+@dataclass(frozen=True, slots=True)
+class SigningKey:
+    """A signer's certificate and the private key that goes with it.
+
+    Everything a caller needs for display or for a policy check is copied out at load time, so
+    the key object itself is only ever touched by :func:`_sign` and never reaches a ``repr``.
+    """
+
+    #: The certificate's DER bytes: what the document carries, Base64, and what is thumbprinted.
+    certificate_der: bytes
+
+    #: RFC 4514 subject, e.g. ``CN=VeloPhex Publisher``, for the line the CLI prints.
+    subject: str
+
+    not_before: datetime
+
+    not_after: datetime
+
+    #: :data:`RSA_PSS_SHA512` or :data:`ECDSA_SHA512`, decided by the key's type.
+    algorithm: str
+
+    private_key: Any = field(repr=False)
+
+    @property
+    def thumbprint(self) -> str:
+        """Upper-case hex SHA-256 of the DER bytes: the value a verifier pins."""
+        return hashlib.sha256(self.certificate_der).hexdigest().upper()
+
+    def is_valid_at(self, moment: datetime) -> bool:
+        """Whether *moment* falls inside the certificate's validity period.
+
+        The verifier rejects a signature from a certificate outside it, so a publisher is better
+        told before the package is uploaded than after.
+        """
+        return self.not_before <= moment <= self.not_after
+
+
+def format_signed_at(moment: datetime) -> str:
+    """*moment* in the one canonical spelling of ``signedAt``, UTC and truncated to the second.
+
+    Byte for byte ``PackageSignature.FormatSignedAt``. A naive datetime is taken as UTC.
+    """
+    return _utc(moment).replace(microsecond=0).strftime(SIGNED_AT_FORMAT)
+
+
+def create_payload(
+    package_id: str,
+    package_version: str,
+    manifest_sha512: str,
+    signed_at: datetime | None = None,
+) -> bytes:
+    """Build the exact bytes a signer signs and a verifier checks.
+
+    Byte for byte ``PackageSignature.CreatePayload``: a domain-separation prefix line, then the
+    id, the version and the manifest hash, one per line, lower-cased, LF separated, trailing LF.
+    The version is lower-cased and nothing more - versions are SemVer 2.0 without build metadata
+    (ADR-P011), so the text is already normalized and normalizing again here would sign bytes no
+    .NET verifier would reconstruct.
+
+    With *signed_at* the payload is **format 2**: the prefix says ``/2`` and a fifth line carries
+    the signing time as :func:`format_signed_at` writes it, verbatim (not lower-cased). Without it
+    the payload is format 1, which no signer writes any more and every verifier still reads.
+    """
+    for name, value in (
+        ("package id", package_id),
+        ("package version", package_version),
+        ("manifest hash", manifest_sha512),
+    ):
+        if not value or not value.strip():
+            raise SigningError(f"The {name} is required to sign a package.")
+
+    format_version = MINIMUM_FORMAT_VERSION if signed_at is None else CURRENT_FORMAT_VERSION
+    fifth_line = "" if signed_at is None else f"{format_signed_at(signed_at)}\n"
+
+    return (
+        f"{FORMAT_NAME}/{format_version}\n"
+        f"{package_id.lower()}\n"
+        f"{package_version.lower()}\n"
+        f"{manifest_sha512.lower()}\n"
+        f"{fifth_line}"
+    ).encode()
+
+
+def load_signing_key(pkcs12_path: str | Path, password: bytes | None) -> SigningKey:
+    """Load a signer from a PKCS#12 (``.pfx``/``.p12``) file.
+
+    *password* is ``None`` for an unprotected file. It is read by the caller from an environment
+    variable or from stdin - never from a command-line argument, which every process listing on
+    the machine can see.
+    """
+    crypto = _cryptography()
+    path = Path(pkcs12_path)
+
+    try:
+        payload = path.read_bytes()
+    except OSError as error:
+        raise SigningError(f"The signing key file '{path}' could not be read: {error.strerror}.") from None
+
+    try:
+        private_key, certificate, _ = crypto.pkcs12.load_key_and_certificates(payload, password)
+    except Exception:
+        # Never chain: the underlying exception is the only thing in this module that has ever
+        # been anywhere near the password, and a traceback in CI output is a disclosure.
+        raise SigningError(
+            f"'{path}' could not be opened as a PKCS#12 signing key. Check the file and the password."
+        ) from None
+
+    if certificate is None:
+        raise SigningError(f"'{path}' carries no certificate, so there is nothing to sign with.")
+
+    if isinstance(private_key, crypto.rsa.RSAPrivateKey):
+        algorithm = RSA_PSS_SHA512
+    elif isinstance(private_key, crypto.ec.EllipticCurvePrivateKey):
+        algorithm = ECDSA_SHA512
+    else:
+        raise SigningError(
+            f"'{path}' has no RSA or ECDSA private key; the platform signs with "
+            f"{RSA_PSS_SHA512} or {ECDSA_SHA512} only."
+        )
+
+    certificate_der = certificate.public_bytes(crypto.Encoding.DER)
+
+    if len(certificate_der) > MAXIMUM_CERTIFICATE_BYTES:
+        raise SigningError(
+            f"The signer certificate is {len(certificate_der)} bytes; verifiers refuse anything "
+            f"over {MAXIMUM_CERTIFICATE_BYTES}."
+        )
+
+    _require_may_sign(crypto, certificate, path)
+
+    return SigningKey(
+        certificate_der=certificate_der,
+        subject=certificate.subject.rfc4514_string(),
+        not_before=certificate.not_valid_before_utc,
+        not_after=certificate.not_valid_after_utc,
+        algorithm=algorithm,
+        private_key=private_key,
+    )
+
+
+def create_signature_document(
+    manifest_bytes: bytes,
+    key: SigningKey,
+    signed_at: datetime | None = None,
+) -> bytes:
+    """Sign *manifest_bytes* and return the format-2 ``velophex/signature.json`` document.
+
+    *manifest_bytes* must be ``velophex/package-manifest.json`` exactly as stored in the archive:
+    the verifier hashes what it reads out of the package, so anything re-serialized here would
+    hash to a different value. *signed_at* defaults to now; the document's ``signedAt`` member is
+    the same text the payload carries, so a verifier reconstructs the signed bytes exactly.
+    """
+    package_id, package_version = _read_identity(manifest_bytes)
+    manifest_sha512 = hashlib.sha512(manifest_bytes).hexdigest()
+    moment = datetime.now(UTC) if signed_at is None else _utc(signed_at)
+
+    if not key.is_valid_at(moment):
+        raise SigningError(
+            f"The signer certificate '{key.subject}' is not valid at {format_signed_at(moment)}; "
+            "a verifier would refuse the signature."
+        )
+
+    signature = _sign(create_payload(package_id, package_version, manifest_sha512, moment), key)
+
+    document = {
+        "format": FORMAT_NAME,
+        "formatVersion": CURRENT_FORMAT_VERSION,
+        "packageId": package_id,
+        "packageVersion": package_version,
+        "manifestSha512": manifest_sha512,
+        "algorithm": key.algorithm,
+        # The public certificate only. A PKCS#12 holds the private key too; it stops here.
+        "certificate": base64.b64encode(key.certificate_der).decode("ascii"),
+        "signedAt": format_signed_at(moment),
+        "signature": base64.b64encode(signature).decode("ascii"),
+    }
+
+    # Member order, indent and escaping of System.Text.Json with WriteIndented, in the order
+    # PackageSignature declares its members; the reserved timestampToken is not written.
+    return _json.dumps_document(document).encode("utf-8")
+
+
+def sign_package_bytes(package: bytes, key: SigningKey, signed_at: datetime | None = None) -> bytes:
+    """Return *package* with ``velophex/signature.json`` added.
+
+    The signature is appended as a new archive entry, which leaves every existing entry - the
+    manifest above all - byte for byte where it was. A signature that changed the bytes it
+    covers could never verify.
+    """
+    with zipfile.ZipFile(BytesIO(package)) as archive:
+        names = set(archive.namelist())
+
+        if PackageLayout.SIGNATURE_PATH in names:
+            raise SigningError("The package is already signed; build it again before signing.")
+
+        if PackageLayout.MANIFEST_PATH not in names:
+            raise SigningError(f"The package has no '{PackageLayout.MANIFEST_PATH}' to sign.")
+
+        manifest_bytes = archive.read(PackageLayout.MANIFEST_PATH)
+
+    document = create_signature_document(manifest_bytes, key, signed_at)
+
+    if len(document) > MAXIMUM_DOCUMENT_BYTES:
+        raise SigningError(f"The signature document is larger than {MAXIMUM_DOCUMENT_BYTES} bytes.")
+
+    buffer = BytesIO(package)
+
+    with zipfile.ZipFile(buffer, "a", compression=zipfile.ZIP_DEFLATED, compresslevel=9) as archive:
+        info = zipfile.ZipInfo(PackageLayout.SIGNATURE_PATH, date_time=ENTRY_TIMESTAMP)
+        info.compress_type = zipfile.ZIP_DEFLATED
+        info.external_attr = 0o600 << 16
+        archive.writestr(info, document)
+
+    return buffer.getvalue()
+
+
+def sign_package_file(package_path: str | Path, key: SigningKey) -> Path:
+    """Sign the ``.nupkg`` at *package_path* in place and return its path."""
+    path = Path(package_path)
+    path.write_bytes(sign_package_bytes(path.read_bytes(), key))
+    return path
+
+
+# --------------------------------------------------------------------------- internals
+
+
+def _utc(moment: datetime) -> datetime:
+    """*moment* as an aware UTC datetime; a naive one is taken as UTC already."""
+    return moment.replace(tzinfo=UTC) if moment.tzinfo is None else moment.astimezone(UTC)
+
+
+def _read_identity(manifest_bytes: bytes) -> tuple[str, str]:
+    """Read the package id and version the manifest itself declares.
+
+    Mirrors ``PackageManifestIdentity.TryRead``: only the identity is needed, and taking it from
+    the manifest is what makes the verifier's equality check pass.
+    """
+    try:
+        document = _json.loads(manifest_bytes)
+    except ValueError as error:
+        raise SigningError(f"The package manifest is not valid JSON: {error}") from None
+
+    if not isinstance(document, dict):
+        raise SigningError("The package manifest is not a JSON object.")
+
+    package_id = document.get("packageId")
+    package_version = document.get("packageVersion")
+
+    if not isinstance(package_id, str) or not isinstance(package_version, str):
+        raise SigningError("The package manifest has no 'packageId' and 'packageVersion' to sign.")
+
+    return package_id, package_version
+
+
+def _require_may_sign(crypto: SimpleNamespace, certificate: Any, path: Path) -> None:
+    """Refuse a certificate whose key usage forbids signing, as the verifier would.
+
+    A certificate with no key-usage extension is allowed: the verifier only enforces the
+    extension when it is there, and refusing more here would reject signers it accepts.
+    """
+    try:
+        usage = certificate.extensions.get_extension_for_class(crypto.x509.KeyUsage).value
+    except crypto.x509.ExtensionNotFound:
+        return
+
+    if not usage.digital_signature:
+        raise SigningError(
+            f"The certificate in '{path}' has a key usage that forbids digital signatures, "
+            "so every verifier would refuse its signature."
+        )
+
+
+def _sign(payload: bytes, key: SigningKey) -> bytes:
+    crypto = _cryptography()
+
+    if key.algorithm == RSA_PSS_SHA512:
+        return key.private_key.sign(
+            payload,
+            crypto.padding.PSS(
+                mgf=crypto.padding.MGF1(crypto.hashes.SHA512()),
+                # .NET's RSASignaturePadding.Pss salts with the hash length; a verifier that
+                # expects 64 bytes of salt will not accept any other length.
+                salt_length=crypto.hashes.SHA512.digest_size,
+            ),
+            crypto.hashes.SHA512(),
+        )
+
+    der = key.private_key.sign(payload, crypto.ec.ECDSA(crypto.hashes.SHA512()))
+
+    return _to_p1363(der, key.private_key.curve.key_size, crypto)
+
+
+def _to_p1363(der_signature: bytes, key_size_bits: int, crypto: SimpleNamespace) -> bytes:
+    """Convert a DER ``SEQUENCE { r, s }`` to the fixed-width ``r || s`` .NET reads.
+
+    ``ECDsa.VerifyData`` defaults to IEEE P1363, so a DER signature - which is what
+    :mod:`cryptography` returns - is simply not a signature as far as the verifier is concerned.
+    """
+    r, s = crypto.decode_dss_signature(der_signature)
+    width = (key_size_bits + 7) // 8
+
+    return r.to_bytes(width, "big") + s.to_bytes(width, "big")
+
+
+def _cryptography() -> SimpleNamespace:
+    """Import the pieces of ``cryptography`` signing needs, or say how to install it.
+
+    One import site, so the optional dependency turns into one actionable sentence instead of a
+    traceback from wherever it happened to be first touched.
+    """
+    try:
+        from cryptography import x509
+        from cryptography.hazmat.primitives import hashes
+        from cryptography.hazmat.primitives.asymmetric import ec, padding, rsa
+        from cryptography.hazmat.primitives.asymmetric.utils import decode_dss_signature
+        from cryptography.hazmat.primitives.serialization import Encoding, pkcs12
+    except ImportError:
+        raise SigningError(SIGNING_EXTRA_HINT) from None
+
+    return SimpleNamespace(
+        Encoding=Encoding,
+        decode_dss_signature=decode_dss_signature,
+        ec=ec,
+        hashes=hashes,
+        padding=padding,
+        pkcs12=pkcs12,
+        rsa=rsa,
+        x509=x509,
+    )

velophex/worker/__init__.py

@@ -0,0 +1,27 @@
+"""The VeloPhex Python executor: ``python -m velophex.worker``.
+
+The Runner (or Studio, or ``velophex run``) starts one worker process per automation run and
+talks to it over the process's stdin and stdout with the executor protocol (ADR-P005). stdout
+belongs to the protocol; everything a handler prints goes to stderr, which the parent captures
+as free-text diagnostics.
+
+Modules:
+
+* :mod:`velophex.worker.framing` - length-prefixed, HMAC-authenticated frames
+* :mod:`velophex.worker.outbox` - outgoing messages and the ``logging`` bridge
+* :mod:`velophex.worker.loader` - ``project.json`` to an imported handler
+* :mod:`velophex.worker.session` - the conversation itself
+"""
+
+from velophex.worker.framing import FrameReader, FrameWriter, take_session_key_from_environment
+from velophex.worker.outbox import ExecutorOutbox, WorkerLogHandler
+from velophex.worker.session import WorkerSession
+
+__all__ = [
+    "ExecutorOutbox",
+    "FrameReader",
+    "FrameWriter",
+    "WorkerLogHandler",
+    "WorkerSession",
+    "take_session_key_from_environment",
+]

velophex/worker/__main__.py

@@ -0,0 +1,118 @@
+"""``python -m velophex.worker`` - the process the Runner launches for a Python automation.
+
+Exit codes match the workflow executor: ``0`` the session ended, ``2`` a protocol violation,
+``3`` no session key. Anything else is a crash, which the parent reports as
+``Application / EXECUTOR_CRASHED``.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import sys
+from typing import BinaryIO
+
+from velophex import __version__
+from velophex.contracts.executor import SESSION_KEY_ENVIRONMENT_VARIABLE, ExecutorFrameDirection
+from velophex.worker.framing import FrameReader, FrameWriter, take_session_key_from_environment
+from velophex.worker.outbox import ExecutorOutbox
+from velophex.worker.session import EXIT_PROTOCOL_VIOLATION, WorkerSession
+
+EXIT_NO_SESSION_KEY = 3
+_STD_INPUT_HANDLE = -10
+_STD_OUTPUT_HANDLE = -11
+
+
+def _set_std_handle(which: int, fd: int) -> None:
+    """Point a Win32 standard handle at *fd*: ``dup2`` changes the CRT descriptor only."""
+    if sys.platform == "win32":
+        import ctypes
+        import msvcrt
+
+        ctypes.windll.kernel32.SetStdHandle(which, msvcrt.get_osfhandle(fd))
+
+
+def _take_command_stream() -> BinaryIO:
+    """Move the parent's frame pipe off standard input and give standard input the null device.
+
+    The same reasoning as :func:`_take_frame_stream`, in the other direction: a child process
+    inherits fd 0 / ``STD_INPUT_HANDLE``, and one that reads it (``input()`` in a subprocess, a
+    CLI prompting for a password) would consume the parent's frames - a stop request among
+    them. So the pipe moves to a private, non-inheritable descriptor, and anything the
+    automation or its children read from standard input gets end-of-file.
+    """
+    command_fd = os.dup(0)  # PEP 446: non-inheritable
+    null = os.open(os.devnull, os.O_RDONLY)
+    os.dup2(null, 0)
+    os.close(null)
+    _set_std_handle(_STD_INPUT_HANDLE, 0)
+    sys.stdin = open(os.devnull, encoding="utf-8")  # noqa: SIM115 - lives as long as the process
+
+    # Unbuffered: the listener thread stays blocked in a read after the session ends, and a
+    # BufferedReader's lock held by a daemon thread is a fatal error at interpreter shutdown.
+    return open(command_fd, "rb", buffering=0)
+
+
+def _take_frame_stream() -> BinaryIO:
+    """Move the frame pipe off standard output and point standard output at stderr.
+
+    Rebinding ``sys.stdout`` alone is not enough: a child process (``os.system``, ``subprocess``
+    without ``stdout=``), a C extension or a direct ``WriteFile`` on the standard handle writes
+    to fd 1 / ``STD_OUTPUT_HANDLE``, which would still be the frame pipe and corrupt the stream.
+    So the pipe moves to a private, non-inheritable descriptor, and fd 1 - plus the Win32
+    standard handle, which ``dup2`` does not touch - become stderr. A grandchild that outlives
+    the worker therefore cannot hold the pipe open either: the parent sees end-of-file when
+    the worker exits.
+    """
+    frame_fd = os.dup(1)  # PEP 446: non-inheritable
+
+    try:
+        os.dup2(2, 1)
+    except OSError:
+        # No usable stderr (pythonw launched without one): standard output goes nowhere.
+        null = os.open(os.devnull, os.O_WRONLY)
+        os.dup2(null, 1)
+        os.close(null)
+
+    _set_std_handle(_STD_OUTPUT_HANDLE, 1)
+
+    # Anything automation code prints goes to stderr, so a stray print() is diagnostics.
+    sys.stdout = sys.stderr
+    return open(frame_fd, "wb", buffering=0)
+
+
+def main() -> int:
+    """Serve one executor session on stdin and stdout."""
+    key = take_session_key_from_environment()
+
+    if key is None:
+        print(
+            f"{SESSION_KEY_ENVIRONMENT_VARIABLE} is missing or invalid; "
+            "the worker must be started by a VeloPhex parent.",
+            file=sys.stderr,
+        )
+        return EXIT_NO_SESSION_KEY
+
+    reader = FrameReader(_take_command_stream(), key, ExecutorFrameDirection.PARENT_TO_EXECUTOR)
+    writer = FrameWriter(_take_frame_stream(), key, ExecutorFrameDirection.EXECUTOR_TO_PARENT)
+
+    session = WorkerSession(
+        reader,
+        ExecutorOutbox(writer),
+        runtime_version=platform.python_version(),
+        worker_version=__version__,
+        diagnostics=sys.stderr,
+    )
+
+    try:
+        return session.run()
+    except KeyboardInterrupt:
+        return EXIT_PROTOCOL_VIOLATION
+    finally:
+        # The key protected this process only; it must not outlive the session in memory
+        # any longer than necessary.
+        del key
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())