"""C10 Public-API Protocols.

- :class:`CacheProvisioner` (AZ-325, pending) — pre-flight orchestrator.
- :class:`ManifestSigner` (AZ-323) — Ed25519 detached signing surface
  consumed by :class:`ManifestBuilder`.

Concrete impl: engine compile + descriptors + manifest + content-hash gate. See
`_docs/02_document/components/11_c10_provisioning/`.
"""

from __future__ import annotations

from pathlib import Path
from typing import Protocol, runtime_checkable

from gps_denied_onboard._types.manifests import Manifest

__all__ = [
    "CacheProvisioner",
    "ManifestSigner",
    "SigningKeyHandle",
]


class CacheProvisioner(Protocol):
    """Pre-flight cache provisioning (engine compile + descriptor batch + manifest)."""

    def provision(self, flight_id: str, output_root: Path) -> Manifest: ...


class SigningKeyHandle(Protocol):
    """Opaque handle returned by :meth:`ManifestSigner.load_signing_key`.

    The Protocol intentionally exposes no methods — concrete signers
    (e.g. :class:`Ed25519ManifestSigner`) hold the actual key behind
    this marker so the caller can pass it back into :meth:`sign` /
    :meth:`public_key_fingerprint` without ever touching the secret
    material.
    """


@runtime_checkable
class ManifestSigner(Protocol):
    """Detached-signature provider for :class:`ManifestBuilder` (AZ-323).

    Default impl is :class:`Ed25519ManifestSigner` using
    ``cryptography.hazmat.primitives.asymmetric.ed25519``; tests
    inject a deterministic in-memory keypair.

    Contract:
    - :meth:`load_signing_key` takes a path to an operator-supplied
      PEM-encoded PKCS8 Ed25519 private key, returns an opaque
      :class:`SigningKeyHandle`. Format errors raise
      :class:`gps_denied_onboard.components.c10_provisioning.errors.ManifestWriteError`
      with the underlying ``cryptography`` exception chained via
      ``__cause__``.
    - :meth:`sign` produces a 64-byte raw Ed25519 signature over the
      payload bytes. Re-entry-safe; a single handle may be used to
      sign many payloads.
    - :meth:`public_key_fingerprint` returns the SHA-256 hex digest of
      the raw 32-byte public key (operator-mode allowlist key).
    """

    def load_signing_key(self, key_path: Path) -> SigningKeyHandle: ...

    def sign(self, key: SigningKeyHandle, payload_bytes: bytes) -> bytes: ...

    def public_key_fingerprint(self, key: SigningKeyHandle) -> str: ...