flowspec2 1.0.0__py3-none-any.whl

flowspec2/authoring/detached_signature.py

@@ -0,0 +1,120 @@
+"""Internal detached Ed25519 signing and verification primitives."""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import hashlib
+from dataclasses import dataclass
+from typing import Final
+
+from cryptography.exceptions import InvalidSignature, UnsupportedAlgorithm
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey,
+    Ed25519PublicKey,
+)
+
+ED25519_SIGNATURE_BYTES: Final[int] = 64
+
+
+class DetachedEd25519KeyMismatchError(ValueError):
+    """A detached signature names a different trusted public key."""
+
+
+class DetachedEd25519VerificationError(ValueError):
+    """A detached signature does not authenticate its message."""
+
+
+@dataclass(frozen=True)
+class DetachedEd25519Signature:
+    """Canonical signature material produced by one Ed25519 private key."""
+
+    key_id: str
+    signature_base64: str
+
+
+def load_ed25519_private_key(private_key_pem: bytes) -> Ed25519PrivateKey:
+    """Load one unencrypted PKCS8 Ed25519 private key."""
+
+    try:
+        private_key = serialization.load_pem_private_key(private_key_pem, password=None)
+    except (TypeError, UnsupportedAlgorithm, ValueError) as key_error:
+        raise ValueError("private key must be unencrypted PKCS8 PEM") from key_error
+    if not isinstance(private_key, Ed25519PrivateKey):
+        raise ValueError("private key must use Ed25519")
+    return private_key
+
+
+def load_ed25519_public_key(public_key_pem: bytes) -> Ed25519PublicKey:
+    """Load one SubjectPublicKeyInfo Ed25519 public key."""
+
+    try:
+        public_key = serialization.load_pem_public_key(public_key_pem)
+    except (TypeError, UnsupportedAlgorithm, ValueError) as key_error:
+        raise ValueError("public key must be SubjectPublicKeyInfo PEM") from key_error
+    if not isinstance(public_key, Ed25519PublicKey):
+        raise ValueError("public key must use Ed25519")
+    return public_key
+
+
+def ed25519_public_key_id(public_key: Ed25519PublicKey) -> str:
+    """Return the lowercase SHA-256 identifier of a raw Ed25519 public key."""
+
+    public_key_bytes = public_key.public_bytes(
+        encoding=serialization.Encoding.Raw,
+        format=serialization.PublicFormat.Raw,
+    )
+    return hashlib.sha256(public_key_bytes).hexdigest()
+
+
+def canonical_ed25519_signature_bytes(signature_base64: str) -> bytes:
+    """Decode and validate one canonical base64 Ed25519 signature."""
+
+    try:
+        signature_bytes = base64.b64decode(signature_base64, validate=True)
+    except (binascii.Error, ValueError) as decoding_error:
+        raise ValueError("signature must be canonical base64") from decoding_error
+    if (
+        len(signature_bytes) != ED25519_SIGNATURE_BYTES
+        or base64.b64encode(signature_bytes).decode("ascii") != signature_base64
+    ):
+        raise ValueError("signature must be a canonical Ed25519 signature")
+    return signature_bytes
+
+
+def sign_detached_ed25519(
+    message: bytes,
+    private_key_pem: bytes,
+) -> DetachedEd25519Signature:
+    """Sign bytes and return canonical detached Ed25519 signature material."""
+
+    private_key = load_ed25519_private_key(private_key_pem)
+    signature_bytes = private_key.sign(message)
+    return DetachedEd25519Signature(
+        key_id=ed25519_public_key_id(private_key.public_key()),
+        signature_base64=base64.b64encode(signature_bytes).decode("ascii"),
+    )
+
+
+def verify_detached_ed25519(
+    message: bytes,
+    signature_base64: str,
+    public_key_pem: bytes,
+    *,
+    expected_key_id: str,
+) -> str:
+    """Authenticate bytes with the named trusted Ed25519 public key."""
+
+    signature_bytes = canonical_ed25519_signature_bytes(signature_base64)
+    public_key = load_ed25519_public_key(public_key_pem)
+    public_key_id = ed25519_public_key_id(public_key)
+    if public_key_id != expected_key_id:
+        raise DetachedEd25519KeyMismatchError("detached signature names a different public key")
+    try:
+        public_key.verify(signature_bytes, message)
+    except InvalidSignature as signature_error:
+        raise DetachedEd25519VerificationError(
+            "detached Ed25519 signature is invalid"
+        ) from signature_error
+    return public_key_id

flowspec2/authoring/evidence.py

@@ -0,0 +1,311 @@
+"""Content-addressed evidence for externally authored benchmark runs."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from typing import Final
+
+from flowspec2.json_codec import strict_json_loads, validate_json_value
+
+from .benchmark import (
+    AuthoredSource,
+    AuthoringBenchmarkLimits,
+    AuthoringBenchmarkReport,
+    AuthoringRequest,
+)
+from .corpus import AuthoringCorpus
+
+AUTHORING_EVIDENCE_FORMAT: Final[str] = "flowspec2/authoring-benchmark-evidence@3"
+SOURCE_ADAPTER_CONTRACT: Final[dict[str, str]] = {
+    "format": "flowspec/2",
+    "implementation": "FlowSpec2JsonAdapter",
+    "version": "1",
+}
+
+_IDENTIFIER_PATTERN: Final[re.Pattern[str]] = re.compile(r"^[a-z0-9][a-z0-9_-]*$")
+_DIGEST_PATTERN: Final[re.Pattern[str]] = re.compile(r"^[0-9a-f]{64}$")
+_SECRET_KEY_PATTERN: Final[re.Pattern[str]] = re.compile(
+    r"(?:api[_-]?key|authorization|credential|password|secret|access[_-]?token)",
+    re.IGNORECASE,
+)
+
+
+def _canonical_json(json_document: object) -> str:
+    return json.dumps(
+        json_document,
+        ensure_ascii=False,
+        allow_nan=False,
+        separators=(",", ":"),
+        sort_keys=True,
+    )
+
+
+def _sha256(serialized_contract: str) -> str:
+    return hashlib.sha256(serialized_contract.encode("utf-8")).hexdigest()
+
+
+def _contains_secret_key(json_document: object) -> bool:
+    if isinstance(json_document, Mapping):
+        return any(
+            _SECRET_KEY_PATTERN.search(str(property_name)) is not None
+            or _contains_secret_key(property_value)
+            for property_name, property_value in json_document.items()
+        )
+    if isinstance(json_document, list):
+        return any(_contains_secret_key(element_value) for element_value in json_document)
+    return False
+
+
+@dataclass(frozen=True)
+class AuthoringCapture:
+    """The exact authored source returned for one benchmark attempt."""
+
+    case_identifier: str
+    correction_round: int
+    authored_source: str
+    source_sha256: str
+    effective_model_version: str | None = None
+
+    def __post_init__(self) -> None:
+        if not _IDENTIFIER_PATTERN.fullmatch(self.case_identifier):
+            raise ValueError("authoring capture case identifier is invalid")
+        if self.correction_round < 0:
+            raise ValueError("authoring capture correction round must not be negative")
+        if self.source_sha256 != _sha256(self.authored_source):
+            raise ValueError("authoring capture source digest does not match its source")
+        if self.effective_model_version is not None:
+            normalized_model_version = self.effective_model_version.strip()
+            if not normalized_model_version:
+                raise ValueError("authoring capture model version must be non-empty when present")
+            object.__setattr__(self, "effective_model_version", normalized_model_version)
+
+    @classmethod
+    def from_response(
+        cls,
+        case_identifier: str,
+        correction_round: int,
+        authored_response: AuthoredSource,
+    ) -> AuthoringCapture:
+        """Capture one response with its deterministic content identity."""
+
+        return cls(
+            case_identifier=case_identifier,
+            correction_round=correction_round,
+            authored_source=authored_response.source,
+            source_sha256=_sha256(authored_response.source),
+            effective_model_version=authored_response.effective_model_version,
+        )
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "case_identifier": self.case_identifier,
+            "correction_round": self.correction_round,
+            "authored_source": self.authored_source,
+            "source_sha256": self.source_sha256,
+            "effective_model_version": self.effective_model_version,
+        }
+
+
+class RecordingAuthor:
+    """Record exact model sources while preserving the benchmark author protocol."""
+
+    def __init__(self, author: Callable[[AuthoringRequest], AuthoredSource]) -> None:
+        self._author = author
+        self._captures: list[AuthoringCapture] = []
+        self._capture_keys: set[tuple[str, int]] = set()
+
+    def __call__(self, authoring_request: AuthoringRequest) -> AuthoredSource:
+        authored_response = self._author(authoring_request)
+        if not isinstance(authored_response, AuthoredSource):
+            raise TypeError("the recorded author must return AuthoredSource")
+        capture_key = (
+            authoring_request.task.identifier,
+            authoring_request.correction_round,
+        )
+        if capture_key in self._capture_keys:
+            raise ValueError(f"duplicate authoring capture: {capture_key!r}")
+        self._capture_keys.add(capture_key)
+        self._captures.append(
+            AuthoringCapture.from_response(
+                capture_key[0],
+                capture_key[1],
+                authored_response,
+            )
+        )
+        return authored_response
+
+    @property
+    def captures(self) -> tuple[AuthoringCapture, ...]:
+        return tuple(self._captures)
+
+
+@dataclass(frozen=True)
+class AuthoringProviderProvenance:
+    """Closed non-secret configuration for the model author boundary."""
+
+    identifier: str
+    model: str
+    sdk: str
+    sdk_version: str
+    prompt_format: str
+    prompt_digest: str
+    generation_configuration_json: str
+
+    def __post_init__(self) -> None:
+        if not _IDENTIFIER_PATTERN.fullmatch(self.identifier):
+            raise ValueError("authoring provider identifier is invalid")
+        for field_name, field_value in (
+            ("model", self.model),
+            ("sdk", self.sdk),
+            ("sdk_version", self.sdk_version),
+            ("prompt_format", self.prompt_format),
+        ):
+            if not field_value.strip():
+                raise ValueError(f"authoring provider {field_name} must be non-empty")
+        if not _DIGEST_PATTERN.fullmatch(self.prompt_digest):
+            raise ValueError("authoring provider prompt digest must be lowercase SHA-256")
+        generation_configuration = strict_json_loads(self.generation_configuration_json)
+        if not isinstance(generation_configuration, dict):
+            raise ValueError("authoring provider generation configuration must be an object")
+        validate_json_value(
+            generation_configuration,
+            boundary="authoring provider generation configuration",
+        )
+        if _canonical_json(generation_configuration) != self.generation_configuration_json:
+            raise ValueError("authoring provider generation configuration must be canonical JSON")
+        if _contains_secret_key(generation_configuration):
+            raise ValueError("authoring provider generation configuration contains a secret field")
+
+    @classmethod
+    def from_configuration(
+        cls,
+        *,
+        identifier: str,
+        model: str,
+        sdk: str,
+        sdk_version: str,
+        prompt_format: str,
+        prompt_digest: str,
+        generation_configuration: Mapping[str, object],
+    ) -> AuthoringProviderProvenance:
+        return cls(
+            identifier=identifier,
+            model=model,
+            sdk=sdk,
+            sdk_version=sdk_version,
+            prompt_format=prompt_format,
+            prompt_digest=prompt_digest,
+            generation_configuration_json=_canonical_json(dict(generation_configuration)),
+        )
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "identifier": self.identifier,
+            "model": self.model,
+            "sdk": self.sdk,
+            "sdk_version": self.sdk_version,
+            "prompt_format": self.prompt_format,
+            "prompt_digest": self.prompt_digest,
+            "generation_configuration": json.loads(self.generation_configuration_json),
+        }
+
+
+@dataclass(frozen=True)
+class AuthoringBenchmarkEvidence:
+    """Canonical report, captures, and provenance for one completed run."""
+
+    package_version: str
+    repository_revision: str
+    benchmark_limits: AuthoringBenchmarkLimits
+    corpus: AuthoringCorpus
+    profile_identifier: str
+    profile_digest: str
+    provider: AuthoringProviderProvenance
+    report: AuthoringBenchmarkReport
+    captures: tuple[AuthoringCapture, ...]
+
+    def __post_init__(self) -> None:
+        if not self.package_version.strip():
+            raise ValueError("authoring evidence package version must be non-empty")
+        if not self.repository_revision.strip():
+            raise ValueError("authoring evidence repository revision must be non-empty")
+        if self.profile_identifier != self.report.profile_identifier:
+            raise ValueError("authoring evidence profile identifier disagrees with report")
+        if any(
+            case_result.correction_rounds > self.benchmark_limits.max_correction_rounds
+            for case_result in self.report.case_results
+        ):
+            raise ValueError("authoring evidence report exceeds its correction-round limit")
+        if not _DIGEST_PATTERN.fullmatch(self.profile_digest):
+            raise ValueError("authoring evidence profile digest must be lowercase SHA-256")
+        report_case_identifiers = tuple(
+            case_result.case_identifier for case_result in self.report.case_results
+        )
+        corpus_case_identifiers = tuple(
+            benchmark_case.identifier for benchmark_case in self.corpus.cases
+        )
+        if report_case_identifiers != corpus_case_identifiers:
+            raise ValueError("authoring evidence report cases disagree with corpus")
+
+        expected_attempts = tuple(
+            (case_result.case_identifier, authoring_attempt)
+            for case_result in self.report.case_results
+            for authoring_attempt in case_result.attempts
+        )
+        actual_capture_keys = tuple(
+            (capture.case_identifier, capture.correction_round) for capture in self.captures
+        )
+        expected_capture_keys = tuple(
+            (case_identifier, authoring_attempt.correction_round)
+            for case_identifier, authoring_attempt in expected_attempts
+        )
+        if actual_capture_keys != expected_capture_keys:
+            raise ValueError("authoring evidence captures do not align with report attempts")
+        if any(
+            capture.source_sha256 != authoring_attempt.source_sha256
+            for capture, (_case_identifier, authoring_attempt) in zip(
+                self.captures,
+                expected_attempts,
+                strict=True,
+            )
+        ):
+            raise ValueError("authoring evidence capture digest disagrees with report")
+        if self.provider.identifier == "google_gemini" and any(
+            capture.effective_model_version is None for capture in self.captures
+        ):
+            raise ValueError("Gemini authoring evidence requires effective model versions")
+
+    def _unsigned_dict(self) -> dict[str, object]:
+        return {
+            "format": AUTHORING_EVIDENCE_FORMAT,
+            "package_version": self.package_version,
+            "repository_revision": self.repository_revision,
+            "benchmark": {
+                "max_correction_rounds": self.benchmark_limits.max_correction_rounds,
+            },
+            "corpus": self.corpus.metadata(),
+            "profile": {
+                "identifier": self.profile_identifier,
+                "digest": self.profile_digest,
+            },
+            "source_adapter": dict(SOURCE_ADAPTER_CONTRACT),
+            "provider": self.provider.to_dict(),
+            "captures": [capture.to_dict() for capture in self.captures],
+            "report": self.report.to_dict(),
+        }
+
+    @property
+    def digest(self) -> str:
+        return _sha256(_canonical_json(self._unsigned_dict()))
+
+    def to_dict(self) -> dict[str, object]:
+        evidence_document = self._unsigned_dict()
+        evidence_document["digest"] = self.digest
+        return evidence_document
+
+    def to_json(self) -> str:
+        return _canonical_json(self.to_dict())

flowspec2/authoring/evidence_signature.py

@@ -0,0 +1,187 @@
+"""Detached Ed25519 authentication for verified authoring evidence."""
+
+from __future__ import annotations
+
+import copy
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Final, cast
+
+import jsonschema
+
+from flowspec2.json_codec import strict_json_loads
+
+from .detached_signature import (
+    DetachedEd25519KeyMismatchError,
+    DetachedEd25519VerificationError,
+    canonical_ed25519_signature_bytes,
+    sign_detached_ed25519,
+    verify_detached_ed25519,
+)
+from .evidence_verification import (
+    AuthoringEvidenceVerification,
+    verify_authoring_evidence,
+)
+
+AUTHORING_EVIDENCE_SIGNATURE_FORMAT: Final[str] = "flowspec2/authoring-evidence-signature@1"
+AUTHORING_EVIDENCE_SIGNATURE_ALGORITHM: Final[str] = "ed25519"
+_SIGNATURE_SCHEMA_PATH: Final[Path] = Path(__file__).with_name(
+    "authoring-evidence-signature.schema.json"
+)
+_DIGEST_PATTERN: Final[re.Pattern[str]] = re.compile(r"^[0-9a-f]{64}$")
+_SIGNATURE_MESSAGE_PREFIX: Final[bytes] = b"flowspec2/authoring-evidence-signature@1\x00ed25519\x00"
+_signature_schema_cache: dict[str, Any] | None = None
+
+
+def _canonical_json(json_document: object) -> str:
+    return json.dumps(
+        json_document,
+        ensure_ascii=False,
+        allow_nan=False,
+        separators=(",", ":"),
+        sort_keys=True,
+    )
+
+
+def _signature_schema() -> dict[str, Any]:
+    global _signature_schema_cache
+    cached_schema = _signature_schema_cache
+    if cached_schema is None:
+        decoded_schema = strict_json_loads(_SIGNATURE_SCHEMA_PATH.read_text(encoding="utf-8"))
+        if not isinstance(decoded_schema, dict):
+            raise ValueError("authoring evidence signature schema must be a JSON object")
+        jsonschema.Draft202012Validator.check_schema(decoded_schema)
+        cached_schema = cast(dict[str, Any], decoded_schema)
+        _signature_schema_cache = cached_schema
+    return cached_schema
+
+
+def authoring_evidence_signature_schema() -> dict[str, Any]:
+    """Return an owned copy of the detached-signature schema."""
+
+    return copy.deepcopy(_signature_schema())
+
+
+def _signature_message(evidence_digest: str) -> bytes:
+    if not _DIGEST_PATTERN.fullmatch(evidence_digest):
+        raise ValueError("signed evidence digest must be lowercase SHA-256")
+    return _SIGNATURE_MESSAGE_PREFIX + evidence_digest.encode("ascii")
+
+
+@dataclass(frozen=True)
+class AuthoringEvidenceSignature:
+    """Canonical detached signature for one verified evidence digest."""
+
+    evidence_digest: str
+    key_id: str
+    signature_base64: str
+
+    def __post_init__(self) -> None:
+        if not _DIGEST_PATTERN.fullmatch(self.evidence_digest):
+            raise ValueError("signature evidence digest must be lowercase SHA-256")
+        if not _DIGEST_PATTERN.fullmatch(self.key_id):
+            raise ValueError("signature key identifier must be lowercase SHA-256")
+        canonical_ed25519_signature_bytes(self.signature_base64)
+
+    @property
+    def signature_bytes(self) -> bytes:
+        return canonical_ed25519_signature_bytes(self.signature_base64)
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "format": AUTHORING_EVIDENCE_SIGNATURE_FORMAT,
+            "algorithm": AUTHORING_EVIDENCE_SIGNATURE_ALGORITHM,
+            "evidence_digest": self.evidence_digest,
+            "key_id": self.key_id,
+            "signature": self.signature_base64,
+        }
+
+    def to_json(self) -> str:
+        return _canonical_json(self.to_dict())
+
+    @classmethod
+    def from_json(cls, serialized_signature: str) -> AuthoringEvidenceSignature:
+        """Parse one strict canonical detached signature."""
+
+        decoded_signature = strict_json_loads(serialized_signature)
+        jsonschema.Draft202012Validator(_signature_schema()).validate(decoded_signature)
+        if not isinstance(decoded_signature, dict):
+            raise AssertionError("the signature schema accepted a non-object document")
+        if serialized_signature.strip() != _canonical_json(decoded_signature):
+            raise ValueError("authoring evidence signature must use canonical compact JSON")
+        return cls(
+            evidence_digest=cast(str, decoded_signature["evidence_digest"]),
+            key_id=cast(str, decoded_signature["key_id"]),
+            signature_base64=cast(str, decoded_signature["signature"]),
+        )
+
+
+@dataclass(frozen=True)
+class AuthoringEvidenceAuthentication:
+    """A verified evidence report authenticated by one trusted public key."""
+
+    evidence: AuthoringEvidenceVerification
+    key_id: str
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "authenticated": True,
+            "algorithm": AUTHORING_EVIDENCE_SIGNATURE_ALGORITHM,
+            "key_id": self.key_id,
+            "evidence": self.evidence.to_dict(),
+        }
+
+
+def sign_authoring_evidence(
+    serialized_evidence: str,
+    private_key_pem: bytes,
+    *,
+    expected_repository_revision: str | None = None,
+) -> AuthoringEvidenceSignature:
+    """Verify evidence and create its deterministic detached signature."""
+
+    evidence_verification = verify_authoring_evidence(
+        serialized_evidence,
+        expected_repository_revision=expected_repository_revision,
+    )
+    detached_signature = sign_detached_ed25519(
+        _signature_message(evidence_verification.digest),
+        private_key_pem,
+    )
+    return AuthoringEvidenceSignature(
+        evidence_digest=evidence_verification.digest,
+        key_id=detached_signature.key_id,
+        signature_base64=detached_signature.signature_base64,
+    )
+
+
+def verify_authoring_evidence_signature(
+    serialized_evidence: str,
+    serialized_signature: str,
+    public_key_pem: bytes,
+    *,
+    expected_repository_revision: str | None = None,
+) -> AuthoringEvidenceAuthentication:
+    """Verify evidence and authenticate its digest with a trusted public key."""
+
+    evidence_verification = verify_authoring_evidence(
+        serialized_evidence,
+        expected_repository_revision=expected_repository_revision,
+    )
+    evidence_signature = AuthoringEvidenceSignature.from_json(serialized_signature)
+    if evidence_signature.evidence_digest != evidence_verification.digest:
+        raise ValueError("authoring evidence signature names a different evidence digest")
+    try:
+        public_key_id = verify_detached_ed25519(
+            _signature_message(evidence_verification.digest),
+            evidence_signature.signature_base64,
+            public_key_pem,
+            expected_key_id=evidence_signature.key_id,
+        )
+    except DetachedEd25519KeyMismatchError:
+        raise ValueError("authoring evidence signature names a different public key") from None
+    except DetachedEd25519VerificationError as signature_error:
+        raise ValueError("authoring evidence signature is invalid") from signature_error
+    return AuthoringEvidenceAuthentication(evidence=evidence_verification, key_id=public_key_id)