mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/operator_setup.py

@@ -0,0 +1,239 @@
+"""Protected operator provisioning for installed local review.
+
+This module is intentionally installed but is not re-exported from the public package. It creates
+the trust material an operator distributes to independent review roles; it does not install the
+machine-global anchor, approve a Build, finalize review, or mint a release attestation.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import os
+import secrets
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+from mostlyright.data_harness.canonical import canonical_json_bytes
+from mostlyright.data_harness.offline import review_target_path
+from mostlyright.data_harness.pipeline import verify_candidate
+from mostlyright.data_harness.review import public_key_to_base64
+
+REVIEW_SETUP_SCHEMA_VERSION = "mr-data-review-setup.v1"
+
+
+@dataclass(frozen=True)
+class ProvisionedReviewSetup:
+    """Paths and separately distributable capabilities created by an operator."""
+
+    anchor_private_key: Ed25519PrivateKey
+    anchor_path: Path
+    sealed_enrollment_path: Path
+    key_bundle_path: Path
+    handles: dict[str, str]
+    token_paths: dict[str, Path]
+    sealed_enrollment: dict[str, Any]
+
+    def receipt(self) -> dict[str, Any]:
+        """Return only paths and authority disclaimers; never print handles or private keys."""
+
+        return {
+            "schema_version": REVIEW_SETUP_SCHEMA_VERSION,
+            "status": "review_setup_created",
+            "operator_anchor": os.fspath(self.anchor_path),
+            "sealed_enrollment": os.fspath(self.sealed_enrollment_path),
+            "key_bundle": os.fspath(self.key_bundle_path),
+            "role_token_files": {
+                role: os.fspath(path) for role, path in sorted(self.token_paths.items())
+            },
+            "approval_granted": False,
+            "release_attestation_minted": False,
+            "warning": (
+                "Protected operator material was created. This setup does not approve a Build or "
+                "mint a release attestation; distribute each token only to its named review role."
+            ),
+        }
+
+
+def provision_review_setup(
+    workspace: Path,
+    *,
+    operator_root: Path,
+    anchor_path: Path,
+) -> ProvisionedReviewSetup:
+    """Create Build-bound review material in new protected directories.
+
+    The returned anchor is an installation input. The coordinator deliberately reads its real
+    trust anchor only from the fixed machine-global path owned by root; no value here redirects
+    that path.
+    """
+
+    candidate = verify_candidate(review_target_path(workspace))
+    _require_new_output_parent(anchor_path.parent, "operator anchor directory")
+    _require_new_output_parent(operator_root, "operator material directory")
+
+    anchor_private_key = Ed25519PrivateKey.generate()
+    response_root_private_key = Ed25519PrivateKey.generate()
+    reviewer_private_keys = {
+        "question_source_fit": Ed25519PrivateKey.generate(),
+        "transformation_data_quality": Ed25519PrivateKey.generate(),
+    }
+    verifier_private_key = Ed25519PrivateKey.generate()
+    handles = {
+        "question_source_fit": f"h2q_{secrets.token_urlsafe(48)}",
+        "transformation_data_quality": f"h2t_{secrets.token_urlsafe(48)}",
+        "verifier": f"h2v_{secrets.token_urlsafe(48)}",
+    }
+    enrollment_id = secrets.token_hex(16)
+    body = {
+        "schema_version": "review-coordinator-sealed-enrollment.v1",
+        "enrollment_id": enrollment_id,
+        "candidate_digest": candidate.candidate_digest,
+        "validation_policy_digest": candidate.validation_policy_digest,
+        "cycle_lineage": "h2-initial-review",
+        "producer": {
+            "principal_id": candidate.producer_principal,
+            "attempt_id": candidate.producer_attempt,
+        },
+        "reviewers": [
+            {
+                "principal_id": "h2questionsourcereviewer",
+                "attempt_id": "h2questionsourcereviewattempt",
+                "lens": "question_source_fit",
+                "key_id": "h2questionsourcereviewerkey",
+                "public_key": public_key_to_base64(
+                    reviewer_private_keys["question_source_fit"].public_key()
+                ),
+                "handle_sha256": _handle_digest(handles["question_source_fit"]),
+            },
+            {
+                "principal_id": "h2transformationqualityreviewer",
+                "attempt_id": "h2transformationqualityreviewattempt",
+                "lens": "transformation_data_quality",
+                "key_id": "h2transformationqualityreviewerkey",
+                "public_key": public_key_to_base64(
+                    reviewer_private_keys["transformation_data_quality"].public_key()
+                ),
+                "handle_sha256": _handle_digest(handles["transformation_data_quality"]),
+            },
+        ],
+        "verifier": {
+            "principal_id": "h2independentverifier",
+            "public_key": public_key_to_base64(verifier_private_key.public_key()),
+            "handle_sha256": _handle_digest(handles["verifier"]),
+        },
+        "response_root_public_key": public_key_to_base64(response_root_private_key.public_key()),
+    }
+    sealed_enrollment = seal_enrollment(body, anchor_private_key)
+    key_bundle = {
+        "schema_version": "review-coordinator-key-bundle.v1",
+        "enrollment_id": enrollment_id,
+        "response_root_private_key": _private_key_text(response_root_private_key),
+        "reviewer_private_keys": {
+            lens: _private_key_text(private_key)
+            for lens, private_key in reviewer_private_keys.items()
+        },
+        "verifier_private_key": _private_key_text(verifier_private_key),
+    }
+
+    anchor_path.parent.mkdir(mode=0o700, parents=True)
+    operator_root.mkdir(mode=0o700, parents=True)
+    token_directory = operator_root / "role-tokens"
+    token_directory.mkdir(mode=0o700)
+    sealed_enrollment_path = operator_root / "sealed-enrollment.json"
+    key_bundle_path = operator_root / "coordinator-key-bundle.json"
+    token_paths = {role: token_directory / f"{role}.token" for role in handles}
+
+    _write_new_mode(
+        anchor_path,
+        {
+            "schema_version": "review-coordinator-anchor.v1",
+            "algorithm": "Ed25519",
+            "anchor_id": secrets.token_hex(16),
+            "public_key": public_key_to_base64(anchor_private_key.public_key()),
+        },
+        0o444,
+    )
+    _write_new_mode(sealed_enrollment_path, sealed_enrollment, 0o444)
+    _write_new_mode(key_bundle_path, key_bundle, 0o400)
+    for role, token_path in token_paths.items():
+        _write_new_bytes(token_path, f"{handles[role]}\n".encode("ascii"), 0o400)
+
+    return ProvisionedReviewSetup(
+        anchor_private_key=anchor_private_key,
+        anchor_path=anchor_path,
+        sealed_enrollment_path=sealed_enrollment_path,
+        key_bundle_path=key_bundle_path,
+        handles=handles,
+        token_paths=token_paths,
+        sealed_enrollment=sealed_enrollment,
+    )
+
+
+def seal_enrollment(
+    body: dict[str, Any],
+    anchor_private_key: Ed25519PrivateKey,
+) -> dict[str, Any]:
+    """Return the strict signed enrollment envelope issued by an operator."""
+
+    return {
+        "body": body,
+        "signature": base64.b64encode(anchor_private_key.sign(canonical_json_bytes(body))).decode(
+            "ascii"
+        ),
+    }
+
+
+def write_mode(path: Path, value: Any, mode: int) -> None:
+    """Rewrite a test-created canonical artifact while preserving its required mode."""
+
+    path.write_bytes(canonical_json_bytes(value))
+    os.chmod(path, mode, follow_symlinks=False)
+
+
+def _require_new_output_parent(path: Path, label: str) -> None:
+    if path.exists() or path.is_symlink():
+        raise FileExistsError(f"{label} already exists: {path}")
+
+
+def _write_new_mode(path: Path, value: Any, mode: int) -> None:
+    _write_new_bytes(path, canonical_json_bytes(value), mode)
+
+
+def _write_new_bytes(path: Path, value: bytes, mode: int) -> None:
+    flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL
+    if hasattr(os, "O_NOFOLLOW"):
+        flags |= os.O_NOFOLLOW
+    descriptor = os.open(path, flags, mode)
+    try:
+        offset = 0
+        while offset < len(value):
+            offset += os.write(descriptor, value[offset:])
+        os.fsync(descriptor)
+    finally:
+        os.close(descriptor)
+    os.chmod(path, mode, follow_symlinks=False)
+
+
+def _private_key_text(private_key: Ed25519PrivateKey) -> str:
+    raw = private_key.private_bytes(
+        serialization.Encoding.Raw,
+        serialization.PrivateFormat.Raw,
+        serialization.NoEncryption(),
+    )
+    return base64.b64encode(raw).decode("ascii")
+
+
+def _handle_digest(handle: str) -> str:
+    return hashlib.sha256(handle.encode("ascii")).hexdigest()
+
+
+__all__ = [
+    "REVIEW_SETUP_SCHEMA_VERSION",
+    "ProvisionedReviewSetup",
+    "provision_review_setup",
+]