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

fdai_deployment_cli/lifecycle_configuration_artifact.py

@@ -0,0 +1,45 @@
+"""The existing local configuration container, without trust or filesystem decisions."""
+
+from __future__ import annotations
+
+import base64
+
+from fdai_deployment_cli.contracts import canonical_bytes
+from fdai_deployment_cli.lifecycle_configuration_package import SignedConfigurationPackage
+from fdai_deployment_cli.lifecycle_configuration_sealing import read_object
+
+CONFIGURATION_FILE_FORMAT = "fdai.lifecycle-configuration-file.v1"
+MAX_CONFIGURATION_ARTIFACT_BYTES = 2 * 1024 * 1024
+
+
+def configuration_artifact_bytes(package: SignedConfigurationPackage) -> bytes:
+    return canonical_bytes(
+        {
+            "format": CONFIGURATION_FILE_FORMAT,
+            "payload": base64.b64encode(package.payload).decode("ascii"),
+            "signature": base64.b64encode(package.signature).decode("ascii"),
+        }
+    )
+
+
+def read_configuration_artifact(content: bytes) -> SignedConfigurationPackage:
+    if len(content) > MAX_CONFIGURATION_ARTIFACT_BYTES:
+        raise ValueError("configuration artifact exceeds its byte bound")
+    document = read_object(content)
+    if set(document) != {"format", "payload", "signature"}:
+        raise ValueError("configuration input fields are invalid")
+    if document["format"] != CONFIGURATION_FILE_FORMAT:
+        raise ValueError("unsupported configuration artifact format")
+    payload_text, signature_text = document["payload"], document["signature"]
+    if (
+        not isinstance(payload_text, str)
+        or not payload_text
+        or not isinstance(signature_text, str)
+        or not signature_text
+    ):
+        raise ValueError("configuration field must be nonempty text")
+    payload = base64.b64decode(payload_text, validate=True)
+    signature = base64.b64decode(signature_text, validate=True)
+    if len(payload) > 1024 * 1024 or len(signature) != 64:
+        raise ValueError("configuration artifact payload or signature size is invalid")
+    return SignedConfigurationPackage(payload, signature)

fdai_deployment_cli/lifecycle_configuration_cli.py

@@ -0,0 +1,324 @@
+"""Local-only configuration packaging; file inputs never establish operational trust."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from collections.abc import Sequence
+from pathlib import Path
+
+from cryptography.exceptions import UnsupportedAlgorithm
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey, Ed25519PublicKey
+from cryptography.hazmat.primitives.asymmetric.x25519 import X25519PublicKey
+
+from fdai_deployment_cli.cli_help import command, command_group
+from fdai_deployment_cli.lifecycle_configuration_artifact import (
+    configuration_artifact_bytes as _encode,
+    read_configuration_artifact as _decode,
+)
+from fdai_deployment_cli.lifecycle_configuration_entities import (
+    EntityConfigurationInput,
+    InstallationConfigurationInput,
+    validate_entity_ids,
+)
+from fdai_deployment_cli.lifecycle_configuration_package import (
+    ConfigurationPackageInput,
+    SignedConfigurationPackage,
+    build_configuration_package,
+    build_installation_configuration_package,
+    verify_configuration_package,
+    verify_installation_configuration_package,
+)
+from fdai_deployment_cli.lifecycle_configuration_publication_cli import (
+    register_publication_commands,
+)
+from fdai_deployment_cli.lifecycle_configuration_sealing import encryption_key_digest, read_object
+from fdai_deployment_cli.private_output import read_private_bytes, write_private_bytes
+
+_MAX_INPUT = 1024 * 1024
+_MAX_ARTIFACT = 2 * _MAX_INPUT
+_MAX_HISTORY = 256
+
+
+def register_configuration_commands(
+    commands: argparse._SubParsersAction[argparse.ArgumentParser],
+) -> None:
+    """Expose offline artifacts only, without enrollment, import, decryption or activation."""
+    group = command(
+        commands,
+        "configuration",
+        "Build, verify or publish local signed configuration packages",
+        epilog="Local files only. No trust registration, qualified Release or deployment is created.",
+    )
+    operations = command_group(group)
+    for operation in ("build", "verify"):
+        parser = command(
+            operations, operation, f"{operation.title()} one local configuration package"
+        )
+        for name, help_text in (
+            (
+                "release-input",
+                "Independent JSON Release/schema, sealed keys and optional opaque Entity selection",
+            ),
+            ("configuration-key", "Independently supplied Ed25519 verification key in PEM format"),
+            (
+                "installation-key",
+                "Explicitly supplied 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(
+            "--history",
+            type=Path,
+            action="append",
+            default=[],
+            metavar="ACCEPTED_PACKAGE",
+            help="Complete accepted chain, oldest first; repeat once per package (maximum 256)",
+        )
+        head = parser.add_mutually_exclusive_group(required=True)
+        head.add_argument(
+            "--initial-revision",
+            action="store_true",
+            help="Explicitly assert an empty accepted chain",
+        )
+        head.add_argument(
+            "--expected-predecessor", help="Independently retained accepted head SHA-256"
+        )
+        if operation == "build":
+            parser.add_argument(
+                "--input",
+                type=Path,
+                required=True,
+                metavar="PRIVATE_FILE",
+                help="Private JSON revision, environment, Entity override blocks and sealed identifiers",
+            )
+            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",
+            )
+            parser.add_argument(
+                "--destination",
+                type=Path,
+                required=True,
+                metavar="NEW_PRIVATE_FILE",
+                help="New absolute mode-0600 file in an existing private mode-0700 directory",
+            )
+        else:
+            parser.add_argument(
+                "--package",
+                type=Path,
+                required=True,
+                metavar="PRIVATE_FILE",
+                help="Existing signed configuration file to verify; no import or activation",
+            )
+        parser.add_argument("--output", choices=("text", "json"), default="text")
+        parser.set_defaults(handler=_run, configuration_operation=operation)
+    register_publication_commands(operations, _execute)
+
+
+def _run(args: argparse.Namespace) -> int:
+    """Suppress input-derived diagnostics; success follows independent reader verification."""
+    try:
+        package = _execute(args)
+    except (ValueError, TypeError, OSError, OverflowError, RecursionError, UnsupportedAlgorithm):
+        raise ValueError(
+            "configuration operation refused; check private file permissions, input shapes, "
+            "independent keys/Release inputs, complete history and a new destination"
+        ) from None
+    result = {
+        "operation": args.configuration_operation,
+        "package_digest": package.digest,
+        "verified": True,
+        "local_only": True,
+        "trust_registered": False,
+        "deployment_activated": False,
+        "production_release_eligibility": "unverified",
+    }
+    print(
+        json.dumps(result, sort_keys=True)
+        if args.output == "json"
+        else f"verified local configuration package sha256={package.digest}; no deployment or trust change"
+    )
+    return 0
+
+
+def _execute(
+    args: argparse.Namespace,
+    *,
+    retained_history: Sequence[SignedConfigurationPackage] | None = None,
+    retained_package: SignedConfigurationPackage | None = None,
+    persist_output: bool = True,
+) -> SignedConfigurationPackage:
+    release = read_object(_read(args.release_input))
+    multi_entity = "entity_ids" in release
+    _fields(
+        release,
+        {"release_version", "configuration_schema", "sealed_keys"}
+        | ({"entity_ids", "release_digest"} if multi_entity else set()),
+    )
+    version = _text(release["release_version"])
+    schema = _object(release["configuration_schema"])
+    keys = release["sealed_keys"]
+    if not isinstance(keys, list) or any(not isinstance(key, str) or not key for key in keys):
+        raise ValueError("sealed keys must be nonempty strings")
+    sealed_keys = frozenset(_text(key) for key in keys)
+    if len(sealed_keys) != len(keys):
+        raise ValueError("sealed keys must be unique")
+    entity_ids = _entity_ids(release["entity_ids"]) if multi_entity else frozenset()
+    public_key = serialization.load_pem_public_key(_read(args.configuration_key, limit=16384))
+    recipient = serialization.load_pem_public_key(_read(args.installation_key, limit=16384))
+    if not isinstance(public_key, Ed25519PublicKey) or not isinstance(recipient, X25519PublicKey):
+        raise ValueError("configuration signing and installation encryption key types are invalid")
+    if len(args.history) > _MAX_HISTORY:
+        raise ValueError("configuration history exceeds its bound")
+    history = (
+        list(retained_history)
+        if retained_history is not None
+        else [_decode(_read(path, limit=_MAX_ARTIFACT)) for path in args.history]
+    )
+    if len(history) > _MAX_HISTORY:
+        raise ValueError("configuration history exceeds its bound")
+    head = history[-1].digest if history else None
+    if args.initial_revision:
+        if history:
+            raise ValueError("initial revision cannot have accepted history")
+    elif head is None or args.expected_predecessor != head:
+        raise ValueError("accepted history does not match the independently retained head")
+    if args.configuration_operation == "build":
+        private_key = serialization.load_pem_private_key(
+            _read(args.signing_key, limit=16384), password=None
+        )
+        if not isinstance(private_key, Ed25519PrivateKey):
+            raise ValueError("configuration signing key must be Ed25519")
+        if private_key.public_key().public_bytes_raw() != public_key.public_bytes_raw():
+            raise ValueError("signing key does not match the independent verification key")
+        source = read_object(_read(args.input))
+        if multi_entity:
+            _fields(source, {"revision_id", "environment", "entities", "sealed"})
+            package = build_installation_configuration_package(
+                InstallationConfigurationInput(
+                    revision_id=_text(source["revision_id"]),
+                    release_version=version,
+                    release_digest=_text(release["release_digest"]),
+                    configuration_schema=schema,
+                    environment_config=_object(source["environment"]),
+                    entities=_entities(source["entities"]),
+                    sealed_values=_object(source["sealed"]),
+                    sealed_keys=sealed_keys,
+                ),
+                entity_ids=entity_ids,
+                signing_key=private_key,
+                installation_key=recipient,
+                history=history,
+            )
+        else:
+            _fields(source, {"revision_id", "environment", "entity_overrides", "sealed"})
+            package = build_configuration_package(
+                ConfigurationPackageInput(
+                    revision_id=_text(source["revision_id"]),
+                    release_version=version,
+                    configuration_schema=schema,
+                    environment_config=_object(source["environment"]),
+                    entity_overrides=_overrides(source["entity_overrides"]),
+                    sealed_values=_object(source["sealed"]),
+                    sealed_keys=sealed_keys,
+                ),
+                signing_key=private_key,
+                installation_key=recipient,
+                history=history,
+            )
+    else:
+        package = (
+            retained_package
+            if retained_package is not None
+            else _decode(_read(args.package, limit=_MAX_ARTIFACT))
+        )
+    if multi_entity:
+        verify_installation_configuration_package(
+            package,
+            configuration_key=public_key,
+            installation_key_digest=encryption_key_digest(recipient),
+            configuration_schema=schema,
+            sealed_keys=sealed_keys,
+            entity_ids=entity_ids,
+            release_version=version,
+            release_digest=_text(release["release_digest"]),
+            history=history,
+        )
+    else:
+        verify_configuration_package(
+            package,
+            configuration_key=public_key,
+            installation_key_digest=encryption_key_digest(recipient),
+            configuration_schema=schema,
+            sealed_keys=sealed_keys,
+            history=history,
+        )
+    if read_object(package.payload)["release_version"] != version:
+        raise ValueError("package does not match the expected Release")
+    if args.configuration_operation == "build" and persist_output:
+        content = _encode(package)
+        write_private_bytes(args.destination, content)
+        if read_private_bytes(args.destination, max_bytes=_MAX_ARTIFACT) != content:
+            raise ValueError("configuration artifact readback does not match")
+    return package
+
+
+def _read(path: Path, *, limit: int = _MAX_INPUT) -> bytes:
+    return read_private_bytes(path, max_bytes=limit)
+
+
+def _entity_ids(value: object) -> frozenset[str]:
+    if not isinstance(value, list):
+        raise ValueError("selected Entities must be an array")
+    ids = frozenset(_text(item) for item in value)
+    if len(ids) != len(value):
+        raise ValueError("selected Entities must be unique")
+    validate_entity_ids(ids)
+    return ids
+
+
+def _overrides(value: object) -> list[dict[str, object]]:
+    if not isinstance(value, list):
+        raise ValueError("entity overrides must be an array")
+    return [_object(block) for block in value]
+
+
+def _entities(value: object) -> list[EntityConfigurationInput]:
+    if not isinstance(value, list):
+        raise ValueError("Entities must be an array")
+    result = []
+    for raw in value:
+        entry = _fields(_object(raw), {"entity_id", "entity_overrides", "sealed"})
+        result.append(
+            EntityConfigurationInput(
+                entity_id=_text(entry["entity_id"]),
+                entity_overrides=_overrides(entry["entity_overrides"]),
+                sealed_values=_object(entry["sealed"]),
+            )
+        )
+    return result
+
+
+def _object(value: object) -> dict[str, object]:
+    if not isinstance(value, dict):
+        raise ValueError("configuration field must be an object")
+    return {str(key): item for key, item in value.items()}
+
+
+def _fields(document: dict[str, object], fields: set[str]) -> dict[str, object]:
+    if set(document) != fields:
+        raise ValueError("configuration input fields are invalid")
+    return document
+
+
+def _text(value: object) -> str:
+    if not isinstance(value, str) or not value:
+        raise ValueError("configuration field must be nonempty text")
+    return value

fdai_deployment_cli/lifecycle_configuration_document.py

@@ -0,0 +1,74 @@
+"""Shared complete-document validation for single and multi-Entity packages."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from fdai_deployment_cli.contracts import canonical_bytes
+from fdai_deployment_cli.lifecycle_configuration import (
+    LayerResolution,
+    resolve_configuration_layers,
+    validate_configuration_package_for_signing,
+    validate_release_configuration_schema,
+)
+
+
+def configuration_object(value: object) -> dict[str, object]:
+    """Require an object without coercing untrusted keys."""
+    if not isinstance(value, Mapping) or any(not isinstance(key, str) for key in value):
+        raise ValueError("configuration field must be an object")
+    return {str(key): item for key, item in value.items()}
+
+
+def validate_configuration_document(
+    configuration: Mapping[str, object],
+    schema: Mapping[str, object],
+    release_version: str,
+    sealed_keys: set[str],
+) -> LayerResolution:
+    """Validate every layer, including unused overrides, before resolving one Entity."""
+    if set(configuration) != {"schema", "environment", "entity_overrides"}:
+        raise ValueError("configuration document fields are invalid")
+    if canonical_bytes(configuration["schema"]) != canonical_bytes(schema):
+        raise ValueError("configuration schema does not match the trusted Release schema")
+    validate_release_configuration_schema(schema)
+    defaults = {
+        key: entry["default"]
+        for key, raw_entry in schema.items()
+        if "default" in (entry := configuration_object(raw_entry))
+    }
+    validate_configuration_package_for_signing(
+        {
+            "defaults": defaults,
+            "environment": configuration["environment"],
+            "entity_overrides": configuration["entity_overrides"],
+        }
+    )
+    overrides = configuration["entity_overrides"]
+    if not isinstance(overrides, list | tuple):
+        raise ValueError("configuration overrides must be a sequence")
+    blocks = [configuration_object(item) for item in overrides]
+    for block in blocks:
+        if set(block) != {"versions", "values"}:
+            raise ValueError("configuration override fields are invalid")
+        _reject_public_identifiers(block["values"], sealed_keys)
+    _reject_public_identifiers(defaults, sealed_keys)
+    _reject_public_identifiers(configuration["environment"], sealed_keys)
+    return resolve_configuration_layers(
+        release_version=release_version,
+        configuration_schema=schema,
+        environment_config=configuration_object(configuration["environment"]),
+        entity_overrides=blocks,
+        sealed_keys=sealed_keys,
+    )
+
+
+def _reject_public_identifiers(value: object, sealed_keys: set[str]) -> None:
+    if isinstance(value, Mapping):
+        if sealed_keys.intersection(value):
+            raise ValueError("sealed identifier belongs in the sealed section")
+        for item in value.values():
+            _reject_public_identifiers(item, sealed_keys)
+    elif isinstance(value, list | tuple):
+        for item in value:
+            _reject_public_identifiers(item, sealed_keys)

fdai_deployment_cli/lifecycle_configuration_entities.py

@@ -0,0 +1,146 @@
+"""Full-revision Entity binding and isolation, without ownership or trust enrollment."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+
+from fdai_deployment_cli.contracts import canonical_bytes
+from fdai_deployment_cli.lifecycle_configuration import (
+    LayerResolution,
+    validate_configuration_package_for_signing,
+)
+from fdai_deployment_cli.lifecycle_configuration_document import (
+    configuration_object,
+    validate_configuration_document,
+)
+from fdai_deployment_cli.lifecycle_configuration_sealing import read_object
+
+INSTALLATION_CONFIGURATION_FORMAT = "fdai.lifecycle-configuration-package.v2"
+_ENTITY_ID = re.compile(r"[0-9a-f]{64}\Z", re.ASCII)
+_MAX_ENTITIES = 256
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class EntityConfigurationInput:
+    """One opaque binding with its own public overrides and private identifiers."""
+
+    entity_id: str
+    entity_overrides: Sequence[Mapping[str, object]]
+    sealed_values: Mapping[str, object]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class InstallationConfigurationInput:
+    """One complete customer Git revision; caller-owned selection is checked separately."""
+
+    revision_id: str
+    release_version: str
+    release_digest: str
+    configuration_schema: Mapping[str, object]
+    environment_config: Mapping[str, object]
+    sealed_values: Mapping[str, object]
+    sealed_keys: frozenset[str]
+    entities: Sequence[EntityConfigurationInput]
+
+
+@dataclass(frozen=True, slots=True)
+class InstallationLayerResolution:
+    """Public configuration resolved independently for every selected Entity."""
+
+    release_version: str
+    entities: dict[str, LayerResolution]
+
+
+def validate_entity_ids(entity_ids: frozenset[str]) -> None:
+    """Require bounded opaque bindings, never derive identity or permission from them."""
+    if not 1 <= len(entity_ids) <= _MAX_ENTITIES or any(
+        not isinstance(entity_id, str) or not _ENTITY_ID.fullmatch(entity_id)
+        for entity_id in entity_ids
+    ):
+        raise ValueError("selected Entity bindings must be bounded opaque identifiers")
+
+
+def prepare_installation_configuration(
+    source: InstallationConfigurationInput, *, entity_ids: frozenset[str]
+) -> tuple[dict[str, object], dict[str, object]]:
+    """Normalize complete inputs before signing; never discard an unknown or duplicate Entity."""
+    validate_entity_ids(entity_ids)
+    if not 1 <= len(source.entities) <= _MAX_ENTITIES:
+        raise ValueError("configuration Entity count is invalid")
+    ids = [entity.entity_id for entity in source.entities]
+    if len(set(ids)) != len(ids) or frozenset(ids) != entity_ids:
+        raise ValueError("configuration does not cover the exact selected Entity set")
+    if not set(source.sealed_values) <= source.sealed_keys:
+        raise ValueError("common sealed identifier keys are invalid")
+    validate_configuration_package_for_signing(source.sealed_values)
+    sealed: dict[str, object] = {}
+    for entity in source.entities:
+        if not set(entity.sealed_values) <= source.sealed_keys:
+            raise ValueError("Entity sealed identifier keys are invalid")
+        validate_configuration_package_for_signing(entity.sealed_values)
+        values = {**source.sealed_values, **entity.sealed_values}
+        if set(values) != source.sealed_keys:
+            raise ValueError("Entity sealed identifier coverage is incomplete")
+        sealed[entity.entity_id] = values
+    configuration = read_object(
+        canonical_bytes(
+            {
+                "schema": source.configuration_schema,
+                "environment": source.environment_config,
+                "entities": [
+                    {"entity_id": entity.entity_id, "entity_overrides": entity.entity_overrides}
+                    for entity in sorted(source.entities, key=lambda item: item.entity_id)
+                ],
+            }
+        )
+    )
+    resolve_installation_configuration(
+        configuration,
+        configuration_schema=source.configuration_schema,
+        release_version=source.release_version,
+        sealed_keys=source.sealed_keys,
+        entity_ids=entity_ids,
+    )
+    return configuration, read_object(canonical_bytes(sealed))
+
+
+def resolve_installation_configuration(
+    configuration: Mapping[str, object],
+    *,
+    configuration_schema: Mapping[str, object],
+    release_version: str,
+    sealed_keys: frozenset[str],
+    entity_ids: frozenset[str],
+) -> InstallationLayerResolution:
+    """Require exact coverage and canonical ordering, then run the canonical layer validator."""
+    validate_entity_ids(entity_ids)
+    if set(configuration) != {"schema", "environment", "entities"}:
+        raise ValueError("installation configuration fields are invalid")
+    entries = configuration["entities"]
+    if not isinstance(entries, list) or not 1 <= len(entries) <= _MAX_ENTITIES:
+        raise ValueError("configuration Entities must be a bounded nonempty array")
+    entities = [configuration_object(entry) for entry in entries]
+    ids: list[str] = []
+    resolutions: dict[str, LayerResolution] = {}
+    for entity in entities:
+        if set(entity) != {"entity_id", "entity_overrides"}:
+            raise ValueError("Entity configuration fields are invalid")
+        entity_id = entity["entity_id"]
+        if not isinstance(entity_id, str) or entity_id not in entity_ids:
+            raise ValueError("configuration names an unselected Entity")
+        ids.append(entity_id)
+        resolutions[entity_id] = validate_configuration_document(
+            {
+                "schema": configuration["schema"],
+                "environment": configuration["environment"],
+                "entity_overrides": entity["entity_overrides"],
+            },
+            configuration_schema,
+            release_version,
+            set(sealed_keys),
+        )
+    if ids != sorted(entity_ids):
+        raise ValueError("configuration Entity coverage or ordering is invalid")
+    return InstallationLayerResolution(release_version, resolutions)