hypermind 0.11.0__py3-none-any.whl

hypermind/crypto/kms_backends/__init__.py

@@ -0,0 +1,56 @@
+"""Cloud KMS backends for the v0.10.4 production profile (T6-03).
+
+Each backend implements :class:`hypermind.crypto.kms.Signer` and lives in
+its own module so the cloud SDK stays an *optional* import. Calling
+:class:`AWSKMSSigner` / :class:`GCPKMSSigner` / :class:`AzureKMSSigner` /
+:class:`VaultTransitSigner` without the matching extra installed raises
+:class:`KMSBackendNotInstalled` with the exact ``pip install`` invocation.
+
+Backends:
+
+* AWS    — ``hypermind[kms-aws]``    → ``boto3``
+* GCP    — ``hypermind[kms-gcp]``    → ``google-cloud-kms``
+* Azure  — ``hypermind[kms-azure]``  → ``azure-keyvault-keys``, ``azure-identity``
+* Vault  — ``hypermind[kms-vault]``  → ``hvac``
+
+Real cloud credentials are explicitly out of scope for v0.10.4 — see
+``§External & human deliverables`` in ROADMAP.md. Each backend raises
+``KMSCredentialsMissing`` early when the documented env vars are absent
+so production wiring fails fast and clearly.
+"""
+
+from __future__ import annotations
+
+
+class KMSBackendNotInstalled(RuntimeError):
+    """Raised when a cloud SDK extra is missing.
+
+    Inherits :class:`RuntimeError` (not :class:`ImportError`) so the
+    ``hypermind.crypto.kms_backends`` package itself imports cleanly even
+    when no cloud SDK is installed — only *use* of a backend fails.
+    """
+
+    def __init__(self, backend: str, extra: str) -> None:
+        super().__init__(
+            f"{backend} KMS backend requires an optional dependency; install via "
+            f"`pip install 'hypermind[{extra}]'` (or `pip install 'hypermind[kms-all]'`)"
+        )
+        self.backend = backend
+        self.extra = extra
+
+
+class KMSCredentialsMissing(RuntimeError):
+    """Raised when a backend is constructed without required credentials.
+
+    The message names the missing env var(s) so operators can self-resolve.
+    """
+
+    def __init__(self, backend: str, missing: list[str]) -> None:
+        super().__init__(
+            f"{backend} KMS backend missing required credentials: {', '.join(missing)}"
+        )
+        self.backend = backend
+        self.missing = missing
+
+
+__all__ = ["KMSBackendNotInstalled", "KMSCredentialsMissing"]

hypermind/crypto/kms_backends/aws.py

@@ -0,0 +1,128 @@
+"""AWS KMS Signer (T6-03).
+
+Lazy-imports ``boto3``. The HyperMind library MUST be importable without
+``boto3`` installed; only constructing :class:`AWSKMSSigner` triggers the
+import (and raises :class:`KMSBackendNotInstalled` if ``boto3`` is absent).
+
+Production wiring (real AWS credentials, KMS key ARN, signature DER
+unwrap) is out of scope for v0.10.4 — see ROADMAP §External & human
+deliverables. This file implements the contract and the fast-fail path
+so downstream code can program against the same Signer Protocol it uses
+for ``LocalSigner``.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from hypermind.crypto.kms_backends import (
+    KMSBackendNotInstalled,
+    KMSCredentialsMissing,
+)
+from hypermind.crypto.signing import ALG_ED25519
+
+
+def _try_import_boto3() -> Any:
+    try:
+        import boto3  # type: ignore[import-not-found]
+
+        return boto3
+    except ImportError as exc:
+        raise KMSBackendNotInstalled("AWS", "kms-aws") from exc
+
+
+class AWSKMSSigner:
+    """Signer backed by AWS KMS ``Sign`` API.
+
+    Construction parameters
+    -----------------------
+    key_id
+        AWS KMS Key ID or ARN (``arn:aws:kms:<region>:<acct>:key/<uuid>``).
+    published_kid
+        The 32-byte Ed25519 public-key half pinned at construction. Pulled
+        out-of-band from ``GetPublicKey`` and stored alongside the agent's
+        published identity. The Signer refuses to ``sign()`` if rotation
+        invalidates this pin.
+    region
+        Optional AWS region. Falls back to the standard boto3 resolution
+        chain (``AWS_REGION`` env var, ``~/.aws/config``).
+    boto3_session
+        Optional pre-built :class:`boto3.Session`; useful for tests and
+        for SDK consumers that already manage a session.
+
+    Required env vars (when no explicit session is supplied)
+    --------------------------------------------------------
+    Either ``AWS_ACCESS_KEY_ID`` + ``AWS_SECRET_ACCESS_KEY`` or
+    ``AWS_PROFILE``. ``KMSCredentialsMissing`` is raised at *first sign()*
+    when neither is configured — construction stays cheap so unit tests
+    can introspect the Signer without hitting AWS.
+    """
+
+    def __init__(
+        self,
+        *,
+        key_id: str,
+        published_kid: bytes,
+        region: str | None = None,
+        boto3_session: Any | None = None,
+        alg: int = ALG_ED25519,
+    ) -> None:
+        if len(published_kid) != 32:
+            raise ValueError("published_kid must be 32 bytes (Ed25519 public)")
+        self._key_id = key_id
+        self._kid = published_kid
+        self._alg = alg
+        self._region = region
+        self._session = boto3_session
+        self._client: Any | None = None
+
+    @property
+    def public_key(self) -> bytes:
+        return self._kid
+
+    @property
+    def kid(self) -> bytes:
+        return self._kid
+
+    @property
+    def alg(self) -> int:
+        return self._alg
+
+    def _client_or_create(self) -> Any:
+        if self._client is not None:
+            return self._client
+        boto3 = _try_import_boto3()
+        if self._session is None:
+            missing: list[str] = []
+            if not (
+                os.getenv("AWS_ACCESS_KEY_ID") and os.getenv("AWS_SECRET_ACCESS_KEY")
+            ) and not os.getenv("AWS_PROFILE"):
+                missing.append("AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY (or AWS_PROFILE)")
+            if missing:
+                raise KMSCredentialsMissing("AWS", missing)
+            self._session = boto3.Session(region_name=self._region)
+        self._client = self._session.client("kms")
+        return self._client
+
+    def sign(self, message: bytes) -> bytes:  # pragma: no cover  - real AWS path
+        client = self._client_or_create()
+        response = client.sign(
+            KeyId=self._key_id,
+            Message=message,
+            MessageType="RAW",
+            SigningAlgorithm="EDDSA",
+        )
+        sig = response["Signature"]
+        # AWS returns DER-wrapped ECDSA but raw Ed25519; defensive normalise.
+        if not isinstance(sig, (bytes, bytearray)):
+            raise RuntimeError("AWS KMS returned non-bytes Signature")
+        return bytes(sig)
+
+    def __repr__(self) -> str:
+        return (
+            f"AWSKMSSigner(key_id={self._key_id!r}, kid={self._kid.hex()[:16]}..., alg={self._alg})"
+        )
+
+
+__all__ = ["AWSKMSSigner"]

hypermind/crypto/kms_backends/azure.py

@@ -0,0 +1,114 @@
+"""Azure Key Vault Signer (T6-03).
+
+Lazy-imports ``azure-keyvault-keys`` and ``azure-identity``.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from hypermind.crypto.kms_backends import (
+    KMSBackendNotInstalled,
+    KMSCredentialsMissing,
+)
+from hypermind.crypto.signing import ALG_ED25519
+
+
+def _try_import_azure() -> tuple[Any, Any, Any]:
+    try:
+        from azure.identity import DefaultAzureCredential  # type: ignore[import-not-found]
+        from azure.keyvault.keys.crypto import (  # type: ignore[import-not-found]
+            CryptographyClient,
+            SignatureAlgorithm,
+        )
+
+        return DefaultAzureCredential, CryptographyClient, SignatureAlgorithm
+    except ImportError as exc:
+        raise KMSBackendNotInstalled("Azure", "kms-azure") from exc
+
+
+class AzureKMSSigner:
+    """Signer backed by Azure Key Vault ``sign`` operation.
+
+    Construction parameters
+    -----------------------
+    key_id
+        Full Azure Key Vault key identifier —
+        ``https://<vault>.vault.azure.net/keys/<name>/<version>``.
+    published_kid
+        Pinned 32-byte Ed25519 public-key half.
+
+    Required env vars
+    -----------------
+    Standard Azure auth chain — at least one of:
+      * ``AZURE_TENANT_ID`` + ``AZURE_CLIENT_ID`` + ``AZURE_CLIENT_SECRET``
+      * managed-identity / workload-identity environment
+    Validated at first ``sign()`` call.
+    """
+
+    def __init__(
+        self,
+        *,
+        key_id: str,
+        published_kid: bytes,
+        credential: Any | None = None,
+        alg: int = ALG_ED25519,
+    ) -> None:
+        if len(published_kid) != 32:
+            raise ValueError("published_kid must be 32 bytes (Ed25519 public)")
+        self._key_id = key_id
+        self._kid = published_kid
+        self._alg = alg
+        self._credential = credential
+        self._client: Any | None = None
+        self._sig_alg: Any | None = None
+
+    @property
+    def public_key(self) -> bytes:
+        return self._kid
+
+    @property
+    def kid(self) -> bytes:
+        return self._kid
+
+    @property
+    def alg(self) -> int:
+        return self._alg
+
+    def _client_or_create(self) -> Any:
+        if self._client is not None:
+            return self._client
+        DefaultAzureCredential, CryptographyClient, SignatureAlgorithm = _try_import_azure()
+        if self._credential is None:
+            if not (
+                os.getenv("AZURE_TENANT_ID")
+                or os.getenv("AZURE_CLIENT_ID")
+                or os.getenv("MSI_ENDPOINT")
+                or os.getenv("IDENTITY_ENDPOINT")
+            ):
+                raise KMSCredentialsMissing(
+                    "Azure",
+                    ["AZURE_TENANT_ID/AZURE_CLIENT_ID or managed-identity"],
+                )
+            self._credential = DefaultAzureCredential()
+        self._client = CryptographyClient(self._key_id, credential=self._credential)
+        # Azure exposes EdDSA via SignatureAlgorithm.eddsa.
+        self._sig_alg = getattr(SignatureAlgorithm, "eddsa", None)
+        return self._client
+
+    def sign(self, message: bytes) -> bytes:  # pragma: no cover  - real Azure path
+        client = self._client_or_create()
+        if self._sig_alg is None:
+            raise RuntimeError("Azure SDK does not expose SignatureAlgorithm.eddsa")
+        result = client.sign(self._sig_alg, message)
+        sig = result.signature
+        if not isinstance(sig, (bytes, bytearray)):
+            raise RuntimeError("Azure Key Vault returned non-bytes signature")
+        return bytes(sig)
+
+    def __repr__(self) -> str:
+        return f"AzureKMSSigner(key_id={self._key_id!r}, kid={self._kid.hex()[:16]}..., alg={self._alg})"
+
+
+__all__ = ["AzureKMSSigner"]

hypermind/crypto/kms_backends/gcp.py

@@ -0,0 +1,97 @@
+"""GCP Cloud KMS Signer (T6-03).
+
+Lazy-imports ``google-cloud-kms``. See ``aws.py`` for the lazy-import
+discipline rationale.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from hypermind.crypto.kms_backends import (
+    KMSBackendNotInstalled,
+    KMSCredentialsMissing,
+)
+from hypermind.crypto.signing import ALG_ED25519
+
+
+def _try_import_kms() -> Any:
+    try:
+        from google.cloud import kms  # type: ignore[import-not-found]
+
+        return kms
+    except ImportError as exc:
+        raise KMSBackendNotInstalled("GCP", "kms-gcp") from exc
+
+
+class GCPKMSSigner:
+    """Signer backed by GCP Cloud KMS ``AsymmetricSign`` RPC.
+
+    Construction parameters
+    -----------------------
+    key_uri
+        GCP key version resource name —
+        ``projects/<p>/locations/<l>/keyRings/<r>/cryptoKeys/<k>/cryptoKeyVersions/<v>``.
+    published_kid
+        Pinned 32-byte Ed25519 public-key half (see ``aws.py``).
+
+    Required env vars
+    -----------------
+    ``GOOGLE_APPLICATION_CREDENTIALS`` pointing at a service-account JSON,
+    or a workload-identity environment (GKE, Cloud Run). Validated at
+    first ``sign()`` call.
+    """
+
+    def __init__(
+        self,
+        *,
+        key_uri: str,
+        published_kid: bytes,
+        client: Any | None = None,
+        alg: int = ALG_ED25519,
+    ) -> None:
+        if len(published_kid) != 32:
+            raise ValueError("published_kid must be 32 bytes (Ed25519 public)")
+        self._key_uri = key_uri
+        self._kid = published_kid
+        self._alg = alg
+        self._client = client
+
+    @property
+    def public_key(self) -> bytes:
+        return self._kid
+
+    @property
+    def kid(self) -> bytes:
+        return self._kid
+
+    @property
+    def alg(self) -> int:
+        return self._alg
+
+    def _client_or_create(self) -> Any:
+        if self._client is not None:
+            return self._client
+        kms = _try_import_kms()
+        if not (os.getenv("GOOGLE_APPLICATION_CREDENTIALS") or os.getenv("GOOGLE_CLOUD_PROJECT")):
+            raise KMSCredentialsMissing(
+                "GCP",
+                ["GOOGLE_APPLICATION_CREDENTIALS or workload-identity (GOOGLE_CLOUD_PROJECT)"],
+            )
+        self._client = kms.KeyManagementServiceClient()
+        return self._client
+
+    def sign(self, message: bytes) -> bytes:  # pragma: no cover  - real GCP path
+        client = self._client_or_create()
+        response = client.asymmetric_sign(request={"name": self._key_uri, "data": message})
+        sig = response.signature
+        if not isinstance(sig, (bytes, bytearray)):
+            raise RuntimeError("GCP KMS returned non-bytes signature")
+        return bytes(sig)
+
+    def __repr__(self) -> str:
+        return f"GCPKMSSigner(key_uri={self._key_uri!r}, kid={self._kid.hex()[:16]}..., alg={self._alg})"
+
+
+__all__ = ["GCPKMSSigner"]

hypermind/crypto/kms_backends/vault.py

@@ -0,0 +1,120 @@
+"""HashiCorp Vault Transit Signer (T6-03).
+
+Lazy-imports ``hvac``. Uses the Transit Secrets Engine ``sign/<key>``
+endpoint with Ed25519 keys.
+"""
+
+from __future__ import annotations
+
+import base64
+import os
+from typing import Any
+
+from hypermind.crypto.kms_backends import (
+    KMSBackendNotInstalled,
+    KMSCredentialsMissing,
+)
+from hypermind.crypto.signing import ALG_ED25519
+
+
+def _try_import_hvac() -> Any:
+    try:
+        import hvac  # type: ignore[import-not-found]
+
+        return hvac
+    except ImportError as exc:
+        raise KMSBackendNotInstalled("Vault", "kms-vault") from exc
+
+
+class VaultTransitSigner:
+    """Signer backed by HashiCorp Vault Transit Secrets Engine.
+
+    Construction parameters
+    -----------------------
+    vault_addr
+        Vault server URL (``https://vault.internal:8200``). Falls back to
+        the ``VAULT_ADDR`` env var.
+    key_name
+        Transit key name (the ``<key>`` in ``transit/keys/<key>``).
+    published_kid
+        Pinned 32-byte Ed25519 public-key half.
+    transit_mount
+        Transit mount path (default: ``transit``).
+    token
+        Vault token. Falls back to ``VAULT_TOKEN``.
+
+    Required env vars (when not supplied via constructor)
+    -----------------------------------------------------
+    ``VAULT_ADDR`` and ``VAULT_TOKEN`` (or an AppRole / k8s auth token
+    pre-configured on the supplied ``hvac.Client``). Validated at first
+    ``sign()`` call.
+    """
+
+    def __init__(
+        self,
+        *,
+        key_name: str,
+        published_kid: bytes,
+        vault_addr: str | None = None,
+        transit_mount: str = "transit",
+        token: str | None = None,
+        client: Any | None = None,
+        alg: int = ALG_ED25519,
+    ) -> None:
+        if len(published_kid) != 32:
+            raise ValueError("published_kid must be 32 bytes (Ed25519 public)")
+        self._key_name = key_name
+        self._kid = published_kid
+        self._alg = alg
+        self._vault_addr = vault_addr
+        self._mount = transit_mount
+        self._token = token
+        self._client = client
+
+    @property
+    def public_key(self) -> bytes:
+        return self._kid
+
+    @property
+    def kid(self) -> bytes:
+        return self._kid
+
+    @property
+    def alg(self) -> int:
+        return self._alg
+
+    def _client_or_create(self) -> Any:
+        if self._client is not None:
+            return self._client
+        hvac = _try_import_hvac()
+        addr = self._vault_addr or os.getenv("VAULT_ADDR")
+        token = self._token or os.getenv("VAULT_TOKEN")
+        missing: list[str] = []
+        if not addr:
+            missing.append("VAULT_ADDR")
+        if not token:
+            missing.append("VAULT_TOKEN")
+        if missing:
+            raise KMSCredentialsMissing("Vault", missing)
+        self._client = hvac.Client(url=addr, token=token)
+        return self._client
+
+    def sign(self, message: bytes) -> bytes:  # pragma: no cover  - real Vault path
+        client = self._client_or_create()
+        response = client.secrets.transit.sign_data(
+            name=self._key_name,
+            hash_input=base64.b64encode(message).decode("ascii"),
+            mount_point=self._mount,
+        )
+        # Vault returns "vault:v1:<base64-sig>".
+        raw = response["data"]["signature"]
+        prefix, _, b64 = raw.rpartition(":")
+        if not prefix.startswith("vault:"):
+            raise RuntimeError(f"unexpected Vault signature envelope: {raw!r}")
+        return base64.b64decode(b64)
+
+    def __repr__(self) -> str:
+        return f"VaultTransitSigner(key={self._key_name!r}, kid={self._kid.hex()[:16]}..., alg={self._alg})"
+
+
+__all__ = ["VaultTransitSigner"]