fdai-deployment-cli 0.1.2__py3-none-any.whl

fdai_deployment_cli/lifecycle_configuration_publication.py

@@ -0,0 +1,277 @@
+"""Venue-scoped persistence, not Git review, Hub acceptance or a global publisher lease."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+import sqlite3
+import time
+from collections.abc import Callable, Iterator, Sequence
+from contextlib import contextmanager
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from uuid import uuid4
+
+from fdai_deployment_cli.contracts import canonical_bytes
+from fdai_deployment_cli.deployment_kit_cache import acquisition_lock, path_present
+from fdai_deployment_cli.lifecycle_configuration_artifact import (
+    MAX_CONFIGURATION_ARTIFACT_BYTES,
+    configuration_artifact_bytes,
+    read_configuration_artifact,
+)
+from fdai_deployment_cli.lifecycle_configuration_package import SignedConfigurationPackage
+from fdai_deployment_cli.lifecycle_configuration_sealing import read_object
+from fdai_deployment_cli.private_output import read_private_bytes, write_private_bytes
+
+MAX_PUBLICATIONS = 256
+MAX_PUBLICATION_BYTES = 16 * 1024 * 1024
+_DATABASE = "publication.sqlite3"
+_FORMAT = "fdai.configuration-publication-state.v1"
+_REVISION = re.compile(r"[0-9a-f]{40}")
+_SHA256 = re.compile(r"[0-9a-f]{64}")
+Build = Callable[[Sequence[SignedConfigurationPackage]], SignedConfigurationPackage]
+Verify = Callable[[Sequence[SignedConfigurationPackage], SignedConfigurationPackage], None]
+
+
+@dataclass(frozen=True, slots=True)
+class Publication:
+    venue_id: str
+    sequence: int
+    revision_id: str
+    created_at: str
+    package: SignedConfigurationPackage
+    artifact: bytes
+
+    @property
+    def artifact_name(self) -> str:
+        return f"{self.package.digest}.json"
+
+    def receipt(self) -> dict[str, object]:
+        value: dict[str, object] = {
+            "format": "fdai.configuration-publication-receipt.v1",
+            "venue_id": self.venue_id,
+            "sequence": self.sequence,
+            "revision_id": self.revision_id,
+            "predecessor_digest": read_object(self.package.payload)["predecessor_digest"],
+            "package_digest": self.package.digest,
+            "artifact_digest": hashlib.sha256(self.artifact).hexdigest(),
+            "artifact_name": self.artifact_name,
+            "created_at": self.created_at,
+        }
+        return {**value, "receipt_digest": hashlib.sha256(canonical_bytes(value)).hexdigest()}
+
+
+def _revision_id(value: str) -> str:
+    if _REVISION.fullmatch(value) is None:
+        raise ValueError("publication revision must be 40 lowercase hexadecimal characters")
+    return value
+
+
+@contextmanager
+def _connection(
+    venue: Path, *, initial: bool = False, readonly: bool = False
+) -> Iterator[sqlite3.Connection]:
+    database = venue / _DATABASE
+    new = not path_present(database)
+    if new:
+        if readonly or not initial or any(venue.iterdir()):
+            raise ValueError("publication state is absent; preserve the venue for review")
+        write_private_bytes(database, b"")
+    else:
+        snapshot = read_private_bytes(database, max_bytes=2 * MAX_PUBLICATION_BYTES)
+        if not snapshot.startswith(b"SQLite format 3\0") or snapshot[18:20] != b"\x01\x01":
+            raise ValueError("publication journal storage format is corrupt or unsupported")
+    if any(path_present(venue / (_DATABASE + suffix)) for suffix in ("-journal", "-wal", "-shm")):
+        raise ValueError(
+            "retained publication transaction sidecar requires review, not automatic recovery"
+        )
+    connection = sqlite3.connect(
+        database.as_uri() + "?mode=ro" if readonly else str(database),
+        uri=readonly,
+        timeout=0.1,
+        isolation_level=None,
+    )
+    deadline = time.monotonic() + 10
+    connection.set_progress_handler(lambda: int(time.monotonic() > deadline), 1000)
+    try:
+        if new:
+            connection.executescript(
+                "PRAGMA journal_mode=DELETE; PRAGMA synchronous=FULL; BEGIN IMMEDIATE;"
+                "CREATE TABLE metadata (id INTEGER PRIMARY KEY, format TEXT NOT NULL, venue_id TEXT NOT NULL);"
+                "CREATE TABLE packages (sequence INTEGER PRIMARY KEY, revision_id TEXT NOT NULL UNIQUE,"
+                "receipt BLOB NOT NULL, artifact BLOB NOT NULL);"
+            )
+            connection.execute("INSERT INTO metadata VALUES (1, ?, ?)", (_FORMAT, uuid4().hex))
+            connection.execute("PRAGMA user_version=1")
+            connection.commit()
+        if connection.execute("PRAGMA user_version").fetchone() != (1,):
+            raise ValueError("unsupported publication journal version")
+        if connection.execute("PRAGMA quick_check(1)").fetchone() != ("ok",):
+            raise ValueError("publication journal integrity check failed")
+        tables = {
+            row[0]
+            for row in connection.execute("SELECT name FROM sqlite_master WHERE type='table'")
+        }
+        if tables != {"metadata", "packages"}:
+            raise ValueError("publication journal schema is incomplete or unknown")
+        for table, columns in (
+            ("metadata", ("id", "format", "venue_id")),
+            ("packages", ("sequence", "revision_id", "receipt", "artifact")),
+        ):
+            actual = tuple(row[1] for row in connection.execute(f"PRAGMA table_info({table})"))  # noqa: S608
+            if actual != columns:
+                raise ValueError("publication journal columns are invalid")
+        if not readonly:
+            connection.execute("PRAGMA synchronous=FULL")
+        yield connection
+    finally:
+        connection.close()
+
+
+def _load(connection: sqlite3.Connection, venue: Path) -> tuple[str, list[Publication]]:
+    metadata = connection.execute("SELECT id, format, venue_id FROM metadata").fetchall()
+    if (
+        len(metadata) != 1
+        or metadata[0][0] != 1
+        or metadata[0][1] != _FORMAT
+        or not isinstance(metadata[0][2], str)
+        or re.fullmatch(r"[0-9a-f]{32}", metadata[0][2]) is None
+    ):
+        raise ValueError("publication venue binding is invalid")
+    venue_id = metadata[0][2]
+    count, total, receipt_size = connection.execute(
+        "SELECT COUNT(*), COALESCE(SUM(length(artifact)),0), COALESCE(MAX(length(receipt)),0) FROM packages"
+    ).fetchone()
+    if count > MAX_PUBLICATIONS or total > MAX_PUBLICATION_BYTES or receipt_size > 4096:
+        raise ValueError("retained publication history exceeds its bound")
+    result: list[Publication] = []
+    previous: str | None = None
+    for expected, row in enumerate(
+        connection.execute(
+            "SELECT sequence, revision_id, receipt, artifact FROM packages ORDER BY sequence"
+        ),
+        1,
+    ):
+        sequence, revision, receipt_bytes, artifact = row
+        if (
+            sequence != expected
+            or not isinstance(revision, str)
+            or not isinstance(receipt_bytes, bytes)
+            or not isinstance(artifact, bytes)
+        ):
+            raise ValueError("retained publication identity is invalid")
+        _revision_id(revision)
+        package = read_configuration_artifact(artifact)
+        payload = read_object(package.payload)
+        if (
+            payload.get("revision_id") != revision
+            or "predecessor_digest" not in payload
+            or payload["predecessor_digest"] != previous
+        ):
+            raise ValueError("retained publication chain is incomplete or forked")
+        receipt = read_object(receipt_bytes)
+        created = receipt.get("created_at")
+        if not isinstance(created, str) or datetime.fromisoformat(created).utcoffset() is None:
+            raise ValueError("publication receipt time is invalid")
+        record = Publication(venue_id, sequence, revision, created, package, artifact)
+        if receipt != record.receipt() or canonical_bytes(receipt) != receipt_bytes:
+            raise ValueError("publication receipt or artifact digest is inconsistent")
+        result.append(record)
+        _artifact_state(venue, record, materialize=False)
+        previous = package.digest
+    expected_names = {_DATABASE} | {r.artifact_name for r in result}
+    if any(path.name not in expected_names for path in venue.iterdir()):
+        raise ValueError("publication venue contains unbound or orphan artifacts")
+    return venue_id, result
+
+
+def _artifact_state(venue: Path, record: Publication, *, materialize: bool) -> str:
+    path = venue / record.artifact_name
+    if not path_present(path):
+        if not materialize:
+            return "missing"
+        write_private_bytes(path, record.artifact)
+    if read_private_bytes(path, max_bytes=MAX_CONFIGURATION_ARTIFACT_BYTES) != record.artifact:
+        raise ValueError("retained publication artifact conflicts; it will not be overwritten")
+    return "present"
+
+
+def publish(
+    venue: Path,
+    revision_id: str,
+    build: Build,
+    verify: Verify,
+    *,
+    initial: bool = False,
+    expected_head: str | None = None,
+) -> Publication:
+    """Trusted callbacks verify complete history and output; historical retry never rewinds it."""
+    _revision_id(revision_id)
+    if not venue.is_absolute() or initial == (expected_head is not None):
+        raise ValueError("select explicit initial publication or retained publication head")
+    if expected_head is not None and _SHA256.fullmatch(expected_head) is None:
+        raise ValueError("publication head must be a SHA-256 digest")
+    with acquisition_lock(venue), _connection(venue, initial=initial) as connection:
+        connection.execute("BEGIN IMMEDIATE")
+        venue_id, records = _load(connection, venue)
+        existing = next((r for r in records if r.revision_id == revision_id), None)
+        head = records[-1].package.digest if records else None
+        predecessor = (
+            read_object(existing.package.payload)["predecessor_digest"] if existing else head
+        )
+        if initial:
+            if records and (existing is None or existing.sequence != 1):
+                raise ValueError("initial publication cannot advance retained history")
+        elif expected_head not in {head, predecessor}:
+            raise ValueError("publication head changed; review retained evidence")
+        if existing is None and len(records) >= MAX_PUBLICATIONS:
+            raise ValueError("new publication exceeds its count bound")
+        if existing is not None and existing.sequence < len(records):
+            verify(tuple(r.package for r in records[:-1]), records[-1].package)
+            selected = records[: existing.sequence]
+        else:
+            selected = records
+        package = build(tuple(r.package for r in selected))
+        if read_object(package.payload).get("revision_id") != revision_id:
+            raise ValueError("publication input revision changed during validation")
+        if existing is not None:
+            if package != existing.package:
+                raise ValueError("the revision already has different retained publication bytes")
+            record = existing
+        else:
+            artifact = configuration_artifact_bytes(package)
+            if (
+                sum(len(r.artifact) for r in records) + len(artifact) > MAX_PUBLICATION_BYTES
+                or read_object(package.payload).get("predecessor_digest") != head
+            ):
+                raise ValueError("new publication exceeds history bounds or forks its head")
+            record = Publication(
+                venue_id,
+                len(records) + 1,
+                revision_id,
+                datetime.now(UTC).isoformat(),
+                package,
+                artifact,
+            )
+            connection.execute(
+                "INSERT INTO packages VALUES (?, ?, ?, ?)",
+                (record.sequence, revision_id, canonical_bytes(record.receipt()), artifact),
+            )
+        connection.commit()
+        _artifact_state(venue, record, materialize=True)
+        return record
+
+
+def inspect_publication(venue: Path, revision_id: str, verify: Verify) -> tuple[Publication, str]:
+    """Verify the entire retained chain with public inputs; never repair or create state."""
+    _revision_id(revision_id)
+    with acquisition_lock(venue), _connection(venue, readonly=True) as connection:
+        _, records = _load(connection, venue)
+        if not records:
+            raise ValueError("publication history is empty")
+        verify(tuple(r.package for r in records[:-1]), records[-1].package)
+        record = next((r for r in records if r.revision_id == revision_id), None)
+        if record is None:
+            raise ValueError("the revision has no retained publication")
+        return record, _artifact_state(venue, record, materialize=False)

fdai_deployment_cli/lifecycle_configuration_publication_cli.py

@@ -0,0 +1,191 @@
+"""Local publication commands with explicit unverified authority boundaries."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sqlite3
+from collections.abc import Sequence
+from functools import partial
+from pathlib import Path
+from typing import Protocol
+
+from cryptography.exceptions import UnsupportedAlgorithm
+
+from fdai_deployment_cli.cli_help import command
+from fdai_deployment_cli.lifecycle_configuration_package import SignedConfigurationPackage
+from fdai_deployment_cli.lifecycle_configuration_publication import inspect_publication, publish
+from fdai_deployment_cli.lifecycle_configuration_sealing import read_object
+from fdai_deployment_cli.private_output import read_private_bytes
+
+
+class ConfigurationExecutor(Protocol):
+    def __call__(
+        self,
+        args: argparse.Namespace,
+        *,
+        retained_history: Sequence[SignedConfigurationPackage] | None = None,
+        retained_package: SignedConfigurationPackage | None = None,
+        persist_output: bool = True,
+    ) -> SignedConfigurationPackage: ...
+
+
+def register_publication_commands(
+    commands: argparse._SubParsersAction[argparse.ArgumentParser],
+    execute: ConfigurationExecutor,
+) -> None:
+    for operation in ("publish", "inspect-publication"):
+        parser = command(
+            commands,
+            operation,
+            f"{operation.title()} venue-scoped configuration evidence",
+            epilog="Local custody only. Git review, global publisher identity and Hub acceptance are unverified.",
+        )
+        for name, help_text in (
+            (
+                "release-input",
+                "Independent JSON Release/schema and optional opaque Entity selection",
+            ),
+            ("configuration-key", "Independently supplied Ed25519 verification key in PEM format"),
+            ("installation-key", "Explicit installation X25519 public key in PEM format"),
+        ):
+            parser.add_argument(
+                f"--{name}", type=Path, required=True, metavar="PRIVATE_FILE", help=help_text
+            )
+        parser.add_argument(
+            "--state-dir",
+            type=Path,
+            required=True,
+            metavar="PRIVATE_DIRECTORY",
+            help="Existing absolute operator-owned mode-0700 venue; no reset or destructive recovery",
+        )
+        if operation == "publish":
+            parser.add_argument(
+                "--input",
+                type=Path,
+                required=True,
+                metavar="PRIVATE_JSON_FILE",
+                help="Private v1/v2 revision inputs; plaintext identifiers are sealed, not journaled",
+            )
+            parser.add_argument(
+                "--signing-key",
+                type=Path,
+                required=True,
+                metavar="PRIVATE_PEM_FILE",
+                help="Private unencrypted PKCS8 Ed25519 PEM file; never supply key bytes in argv",
+            )
+            head = parser.add_mutually_exclusive_group(required=True)
+            head.add_argument(
+                "--initial-publication",
+                action="store_true",
+                help="First publication in an empty local venue or its exact retained retry",
+            )
+            head.add_argument(
+                "--expected-publication-head", help="Retained local publication head SHA-256"
+            )
+        else:
+            parser.add_argument(
+                "--revision-id", required=True, help="Full lowercase source revision shape"
+            )
+        parser.add_argument(
+            "--output",
+            choices=("text", "json"),
+            default="text",
+            help="Render local evidence as readable text or a JSON object",
+        )
+        parser.set_defaults(
+            handler=partial(_run, execute=execute),
+            configuration_operation=operation,
+        )
+
+
+def _arguments(
+    args: argparse.Namespace,
+    operation: str,
+    history: Sequence[SignedConfigurationPackage],
+) -> argparse.Namespace:
+    return argparse.Namespace(
+        **{
+            **vars(args),
+            "configuration_operation": operation,
+            "history": [],
+            "initial_revision": not history,
+            "expected_predecessor": history[-1].digest if history else None,
+        }
+    )
+
+
+def _run(args: argparse.Namespace, *, execute: ConfigurationExecutor) -> int:
+    def verify(
+        history: Sequence[SignedConfigurationPackage],
+        package: SignedConfigurationPackage,
+    ) -> None:
+        execute(
+            _arguments(args, "verify", history),
+            retained_history=history,
+            retained_package=package,
+            persist_output=False,
+        )
+
+    try:
+        if args.configuration_operation == "publish":
+            source = read_object(read_private_bytes(args.input, max_bytes=1024 * 1024))
+            revision = source.get("revision_id")
+            if not isinstance(revision, str):
+                raise ValueError("publication revision is required")
+
+            def build(history: Sequence[SignedConfigurationPackage]) -> SignedConfigurationPackage:
+                return execute(
+                    _arguments(args, "build", history),
+                    retained_history=history,
+                    persist_output=False,
+                )
+
+            record = publish(
+                args.state_dir,
+                revision,
+                build,
+                verify,
+                initial=args.initial_publication,
+                expected_head=args.expected_publication_head,
+            )
+            artifact_state = "present"
+        else:
+            record, artifact_state = inspect_publication(args.state_dir, args.revision_id, verify)
+    except (
+        ValueError,
+        TypeError,
+        OSError,
+        OverflowError,
+        RecursionError,
+        UnsupportedAlgorithm,
+        sqlite3.Error,
+    ):
+        raise ValueError(
+            "configuration publication not confirmed; inspect retained evidence before retrying; "
+            "check the private venue, revision/head selection and independent keys/Release inputs"
+        ) from None
+    result = {
+        "operation": args.configuration_operation,
+        "receipt": record.receipt(),
+        "artifact_state": artifact_state,
+        "publication_confirmed": artifact_state == "present",
+        "verified": True,
+        "local_only": True,
+        "git_revision_existence": "unverified",
+        "git_review": "unverified",
+        "global_publisher_identity": "unverified",
+        "trust_registered": False,
+        "hub_accepted": False,
+        "deployment_activated": False,
+        "execution_authority": False,
+        "production_release_eligibility": "unverified",
+    }
+    print(
+        json.dumps(result, sort_keys=True)
+        if args.output == "json"
+        else f"verified retained configuration evidence sha256={record.package.digest}; artifact={artifact_state}; "
+        f"local publication confirmed={artifact_state == 'present'}; "
+        "no Git review, Hub acceptance or execution authority"
+    )
+    return 0

fdai_deployment_cli/lifecycle_configuration_sealing.py

@@ -0,0 +1,127 @@
+"""Installation-only identifier encryption; no identity or enrollment authority."""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import hashlib
+import json
+import os
+from collections.abc import Mapping
+
+from cryptography.exceptions import InvalidTag
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.asymmetric.x25519 import X25519PrivateKey, X25519PublicKey
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+
+from fdai_deployment_cli.contracts import canonical_bytes
+from fdai_deployment_cli.lifecycle_configuration import validate_configuration_package_for_signing
+
+_ALGORITHM = "X25519-HKDF-SHA256-AES256GCM"
+_INFO = b"fdai.lifecycle-configuration.sealed.v1"
+
+
+def encryption_key_digest(key: X25519PublicKey) -> str:
+    """Identify an explicitly bound encryption key, never an Ed25519 identity key."""
+    return hashlib.sha256(key.public_bytes_raw()).hexdigest()
+
+
+def seal_identifiers(
+    values: Mapping[str, object], recipient: X25519PublicKey, *, context: bytes
+) -> dict[str, object]:
+    """Scan plaintext before encryption and bind ciphertext to the signed revision context."""
+    validate_configuration_package_for_signing(values)
+    plaintext = canonical_bytes(values)
+    ephemeral = X25519PrivateKey.generate()
+    nonce = os.urandom(12)
+    key = _derive_key(ephemeral, recipient, context)
+    ciphertext = AESGCM(key).encrypt(nonce, plaintext, context)
+    return {
+        "algorithm": _ALGORITHM,
+        "recipient_digest": encryption_key_digest(recipient),
+        "ephemeral_key": _encode(ephemeral.public_key().public_bytes_raw()),
+        "nonce": _encode(nonce),
+        "ciphertext": _encode(ciphertext),
+    }
+
+
+def validate_sealed_identifiers(envelope: Mapping[str, object], *, recipient_digest: str) -> None:
+    """Check the public envelope without decrypting or exposing identifier values."""
+    if set(envelope) != {"algorithm", "recipient_digest", "ephemeral_key", "nonce", "ciphertext"}:
+        raise ValueError("sealed identifier envelope fields are invalid")
+    if envelope["algorithm"] != _ALGORITHM or envelope["recipient_digest"] != recipient_digest:
+        raise ValueError("sealed identifier recipient or algorithm is invalid")
+    if len(_decode(envelope["ephemeral_key"])) != 32 or len(_decode(envelope["nonce"])) != 12:
+        raise ValueError("sealed identifier key or nonce length is invalid")
+    if len(_decode(envelope["ciphertext"])) < 16:
+        raise ValueError("sealed identifier ciphertext is invalid")
+
+
+def open_identifiers(
+    envelope: Mapping[str, object], recipient: X25519PrivateKey, *, context: bytes
+) -> dict[str, object]:
+    """Decrypt only inside the installation; a wrong key or changed revision fails closed."""
+    validate_sealed_identifiers(
+        envelope, recipient_digest=encryption_key_digest(recipient.public_key())
+    )
+    ephemeral = X25519PublicKey.from_public_bytes(_decode(envelope["ephemeral_key"]))
+    key = _derive_key(recipient, ephemeral, context)
+    try:
+        plaintext = AESGCM(key).decrypt(
+            _decode(envelope["nonce"]), _decode(envelope["ciphertext"]), context
+        )
+    except InvalidTag:
+        raise ValueError("sealed identifier authentication failed") from None
+    values = read_object(plaintext)
+    validate_configuration_package_for_signing(values)
+    return values
+
+
+def read_object(payload: bytes) -> dict[str, object]:
+    """Read strict JSON without duplicate fields, nonfinite numbers, or error-data leakage."""
+    try:
+        value: object = json.loads(
+            payload, object_pairs_hook=_unique_object, parse_constant=_invalid_constant
+        )
+    except (ValueError, UnicodeError, RecursionError):
+        raise ValueError("configuration package JSON is invalid") from None
+    if not isinstance(value, dict):
+        raise ValueError("configuration package JSON must be an object")
+    return {str(key): item for key, item in value.items()}
+
+
+def _unique_object(pairs: list[tuple[str, object]]) -> dict[str, object]:
+    result: dict[str, object] = {}
+    for key, item in pairs:
+        if key in result:
+            raise ValueError("duplicate JSON field")
+        result[key] = item
+    return result
+
+
+def _invalid_constant(value: str) -> object:
+    raise ValueError("nonfinite JSON number")
+
+
+def _derive_key(private: X25519PrivateKey, public: X25519PublicKey, context: bytes) -> bytes:
+    try:
+        shared = private.exchange(public)
+    except ValueError:
+        raise ValueError("installation encryption key is invalid") from None
+    return HKDF(
+        algorithm=hashes.SHA256(), length=32, salt=hashlib.sha256(context).digest(), info=_INFO
+    ).derive(shared)
+
+
+def _encode(value: bytes) -> str:
+    return base64.b64encode(value).decode("ascii")
+
+
+def _decode(value: object) -> bytes:
+    if not isinstance(value, str):
+        raise ValueError("sealed identifier encoding is invalid")
+    try:
+        return base64.b64decode(value, validate=True)
+    except (ValueError, binascii.Error):
+        raise ValueError("sealed identifier encoding is invalid") from None

fdai_deployment_cli/lifecycle_enrollment.py

@@ -0,0 +1,45 @@
+"""The one canonical installation enrollment signing implementation.
+
+The Lifecycle Hub's offline `sign-enrollment` and the Lifecycle Agent's online `enroll` both build
+the signed request here, so the two cannot drift: the Hub verifies exactly these bytes.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from base64 import b64encode
+from collections.abc import Mapping
+from datetime import datetime, timedelta
+
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+from fdai_deployment_cli.contracts import canonical_bytes
+
+# The Hub rejects a proof whose request time differs from its clock by more than this.
+ENROLLMENT_PROOF_WINDOW = timedelta(minutes=5)
+
+
+def raw_installation_public_key(key: Ed25519PrivateKey) -> bytes:
+    return key.public_key().public_bytes(serialization.Encoding.Raw, serialization.PublicFormat.Raw)
+
+
+def installation_key_id(public_key: bytes) -> str:
+    """The id an approver compares with the key the installation shows out of band."""
+
+    return "installation-" + hashlib.sha256(public_key).hexdigest()[:16]
+
+
+def sign_enrollment_payload(
+    template: Mapping[str, object], key: Ed25519PrivateKey, at: datetime
+) -> tuple[bytes, bytes]:
+    """Add the installation key and `at` to `template`, and return the payload and its proof."""
+
+    if at.tzinfo is None or at.utcoffset() is None:
+        raise ValueError("requested_at must be timezone-aware")
+    fields = {
+        "installation_key": b64encode(raw_installation_public_key(key)).decode("ascii"),
+        "requested_at": at.isoformat(),
+    }
+    payload = canonical_bytes({**template, **fields})
+    return payload, key.sign(payload)