mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/signing.py

@@ -0,0 +1,101 @@
+"""Opaque signing boundary for trusted coordinator integrations."""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Protocol
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+_OPAQUE_HANDLE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$")
+
+
+class TrustedSigner(Protocol):
+    """A signer whose private key material never crosses the CLI boundary."""
+
+    def sign(self, data: bytes) -> bytes:
+        """Sign exact canonical bytes inside the trusted provider."""
+
+    def public_key(self) -> Ed25519PublicKey:
+        """Return only the public verification key."""
+
+
+class TrustedSignerProvider(Protocol):
+    """Resolve a non-secret opaque handle to an in-provider signer."""
+
+    def signer_for(self, opaque_handle: str) -> TrustedSigner:
+        """Return the signer represented by ``opaque_handle``."""
+
+
+class TrustedReviewAuthority(Protocol):
+    """Coordinator-owned enrollment for one exact review assignment.
+
+    Implementations may keep keys in a KMS, HSM, or isolated coordinator
+    process. Only signer capabilities and the non-secret enrolled assignment
+    cross this boundary; callers cannot substitute assignment or public-key
+    files.
+    """
+
+    def assignment_value(self) -> Any:
+        """Return the exact coordinator-enrolled assignment value."""
+
+    def reviewer_signer_for(self, reviewer_attempt: str) -> TrustedSigner:
+        """Return the signer enrolled for one exact reviewer attempt."""
+
+    def verifier_signer(self) -> TrustedSigner:
+        """Return the verifier signer enrolled for this assignment."""
+
+
+class TrustedReviewAuthorityProvider(Protocol):
+    """Resolve the role-scoped authority on one inherited coordinator session."""
+
+    def authority(self) -> TrustedReviewAuthority:
+        """Return the exact authority bound to the inherited session."""
+
+
+class SignerProviderError(RuntimeError):
+    """A trusted signer provider or opaque handle is unavailable."""
+
+
+def resolve_signer(
+    provider: TrustedSignerProvider | None,
+    opaque_handle: str,
+) -> TrustedSigner:
+    """Resolve one bounded opaque handle without reading private key bytes."""
+
+    if _OPAQUE_HANDLE.fullmatch(opaque_handle) is None:
+        raise SignerProviderError("signer handle is not a valid opaque identifier")
+    if provider is None:
+        raise SignerProviderError("trusted signer provider is unavailable")
+    try:
+        signer = provider.signer_for(opaque_handle)
+    except SignerProviderError:
+        raise
+    except Exception as exc:
+        raise SignerProviderError("trusted signer provider could not resolve the handle") from exc
+    if not callable(getattr(signer, "sign", None)) or not callable(
+        getattr(signer, "public_key", None)
+    ):
+        raise SignerProviderError("trusted signer provider returned an invalid signer")
+    return signer
+
+
+def resolve_review_authority(
+    provider: TrustedReviewAuthorityProvider | None,
+) -> TrustedReviewAuthority:
+    """Resolve one inherited review session without trusting CLI values."""
+
+    if provider is None:
+        raise SignerProviderError("trusted review authority provider is unavailable")
+    try:
+        authority = provider.authority()
+    except SignerProviderError:
+        raise
+    except Exception as exc:
+        raise SignerProviderError(
+            "trusted review authority provider could not resolve the handle"
+        ) from exc
+    required = ("assignment_value", "reviewer_signer_for", "verifier_signer")
+    if any(not callable(getattr(authority, name, None)) for name in required):
+        raise SignerProviderError("trusted review authority provider returned an invalid authority")
+    return authority