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

fdai_deployment_cli/license_issue.py

@@ -0,0 +1,239 @@
+"""Issue a short-lived deployment-bound capability token from an operator-held key."""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+import stat
+from datetime import UTC, datetime, timedelta
+from importlib.resources import files
+from pathlib import Path
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey,
+    Ed25519PublicKey,
+)
+from cryptography.hazmat.primitives.serialization import (
+    load_pem_private_key,
+    load_pem_public_key,
+)
+
+from fdai_deployment_cli.contracts import canonical_bytes
+from fdai_deployment_cli.license import (
+    INSTALLATION_ENTITLEMENT_SCHEMA,
+    inspect_installation_entitlement,
+    inspect_license,
+)
+from fdai_deployment_cli.private_output import read_private_bytes, write_private_output
+from fdai_deployment_cli.trust_roots import license_public_key_pem
+
+_ISSUER_KEY = Path("secrets/integrity-signing-key.pem")
+_MAX_KEY_BYTES = 65_536
+
+
+def discover_license_signing_key() -> Path | None:
+    """Return the checkout's upstream integrity key, or None to keep the Trial.
+
+    Only the fixed `secrets/integrity-signing-key.pem` of the working checkout is
+    considered. A present key that is not an owner-only regular file matching the
+    packaged public key raises instead of silently selecting the Trial.
+    """
+
+    path = Path.cwd() / _ISSUER_KEY
+    if not path.exists() and not path.is_symlink():
+        return None
+    _read_private_key(path)
+    return path
+
+
+def issue_deployment_license(
+    *,
+    private_key: Path,
+    image_digest: str,
+    deployment_binding: str,
+    license_id: str,
+    valid_days: int = 30,
+) -> str:
+    """Issue and reverify one complete-catalog token for an exact image and deployment."""
+
+    if not 1 <= valid_days <= 30:
+        raise ValueError("license validity must be from 1 through 30 days")
+    capabilities = _capabilities()
+    now = datetime.now(UTC).replace(microsecond=0)
+    payload: dict[str, object] = {
+        "schema_version": "fdai.license.v1",
+        "license_id": license_id,
+        "distribution_id": "fdai-upstream",
+        "capability_ids": list(capabilities),
+        "not_before": _moment(now),
+        "not_after": _moment(now + timedelta(days=valid_days)),
+        "image_digest": image_digest,
+        "tenant_binding": deployment_binding,
+    }
+    document = canonical_bytes(payload)
+    key = _read_private_key(private_key)
+    token = f"{_encode(document)}.{_encode(key.sign(document))}"
+    inspect_license(
+        token,
+        public_key_pem=license_public_key_pem(),
+        expected_image_digest=image_digest,
+        expected_tenant_binding=deployment_binding,
+    )
+    return token
+
+
+def write_license_token(path: Path, token: str) -> None:
+    """Write a verified token to a new private file for stdin-only handoff."""
+
+    inspect_license(token, public_key_pem=license_public_key_pem())
+    write_private_output(path, token)
+
+
+def deployment_license_token(
+    *,
+    trial_token: Path | None,
+    image_digest: str,
+    deployment_binding: str,
+    work_ref: str,
+    installation_binding: str | None = None,
+) -> str | None:
+    """Return the key holder's grant, a verified supplied token, or None for observation-only.
+
+    A key holder whose runtime supplies an installation binding receives the no-expiry
+    installation entitlement; otherwise the key holder keeps the 30-day v1 token.
+    """
+
+    issuer = discover_license_signing_key()
+    if issuer is not None and installation_binding is not None:
+        return issue_installation_entitlement(
+            private_key=issuer,
+            entitlement_id=f"ent-{work_ref}",
+            installation_binding=installation_binding,
+            deployment_binding=deployment_binding,
+        )
+    if issuer is not None:
+        return issue_deployment_license(
+            private_key=issuer,
+            image_digest=image_digest,
+            deployment_binding=deployment_binding,
+            license_id=f"lic-{work_ref}",
+        )
+    if trial_token is None:
+        return None
+    path = trial_token if trial_token.is_absolute() else Path.cwd() / trial_token
+    token = read_private_bytes(path, max_bytes=8192).decode("ascii")
+    inspect_license(
+        token,
+        public_key_pem=license_public_key_pem(),
+        expected_image_digest=image_digest,
+        expected_tenant_binding=deployment_binding,
+    )
+    return token
+
+
+def issue_installation_entitlement(
+    *,
+    private_key: Path,
+    entitlement_id: str,
+    installation_binding: str,
+    deployment_binding: str,
+) -> str:
+    """Issue and reverify one no-expiry, complete-catalog grant for one installation.
+
+    The document carries no image digest and no validity window, so upgrades and
+    restarts keep it valid; its exact installation and deployment digests are its
+    only limit, and it is useless anywhere else.
+    """
+
+    payload: dict[str, object] = {
+        "schema_version": INSTALLATION_ENTITLEMENT_SCHEMA,
+        "entitlement_id": entitlement_id,
+        "distribution_id": "fdai-upstream",
+        "installation_binding": installation_binding,
+        "deployment_binding": deployment_binding,
+        "issued_at": _moment(datetime.now(UTC).replace(microsecond=0)),
+    }
+    document = canonical_bytes(payload)
+    key = _read_private_key(private_key)
+    token = f"{_encode(document)}.{_encode(key.sign(document))}"
+    inspect_installation_entitlement(
+        token,
+        public_key_pem=license_public_key_pem(),
+        expected_installation_binding=installation_binding,
+        expected_deployment_binding=deployment_binding,
+    )
+    return token
+
+
+def _read_private_key(path: Path) -> Ed25519PrivateKey:
+    details = path.lstat()
+    if (
+        not stat.S_ISREG(details.st_mode)
+        or stat.S_IMODE(details.st_mode) != 0o600
+        or details.st_uid != os.geteuid()
+        or details.st_nlink != 1
+    ):
+        raise PermissionError("license signing key must be a current-UID mode-0600 regular file")
+    try:
+        key = load_pem_private_key(_read_key_bytes(path), password=None)
+        public = load_pem_public_key(license_public_key_pem())
+    except (TypeError, ValueError) as exc:
+        raise ValueError("license signing key is invalid") from exc
+    if not isinstance(key, Ed25519PrivateKey) or not isinstance(public, Ed25519PublicKey):
+        raise ValueError("license signing key must be Ed25519")
+    if key.public_key().public_bytes_raw() != public.public_bytes_raw():
+        raise ValueError("license signing key does not match the packaged public key")
+    return key
+
+
+def _read_key_bytes(path: Path) -> bytes:
+    """Read the key file under the same custody rule Core's issuer check applies.
+
+    The descriptor never follows a link or blocks on a special file. Unlike a
+    private deployment output, the key's directory needs no owner-only mode.
+    """
+
+    descriptor = os.open(path, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK)
+    with os.fdopen(descriptor, "rb") as stream:
+        details = os.fstat(stream.fileno())
+        if (
+            not stat.S_ISREG(details.st_mode)
+            or stat.S_IMODE(details.st_mode) != 0o600
+            or details.st_uid != os.geteuid()
+            or details.st_nlink != 1
+        ):
+            raise PermissionError(
+                "license signing key must be a current-UID mode-0600 regular file"
+            )
+        if not 0 < details.st_size <= _MAX_KEY_BYTES:
+            raise ValueError("license signing key is empty or exceeds 65536 bytes")
+        content = stream.read(_MAX_KEY_BYTES + 1)
+    if len(content) != details.st_size:
+        raise ValueError("license signing key changed while being read")
+    return content
+
+
+def _capabilities() -> tuple[str, ...]:
+    raw = (
+        files("fdai_deployment_cli")
+        .joinpath("trust", "capabilities.json")
+        .read_text(encoding="utf-8")
+    )
+    value = json.loads(raw)
+    if (
+        not isinstance(value, list)
+        or not value
+        or not all(isinstance(item, str) and item for item in value)
+        or value != sorted(set(value))
+    ):
+        raise ValueError("packaged capability inventory is invalid")
+    return tuple(value)
+
+
+def _encode(value: bytes) -> str:
+    return base64.urlsafe_b64encode(value).rstrip(b"=").decode("ascii")
+
+
+def _moment(value: datetime) -> str:
+    return value.astimezone(UTC).isoformat().replace("+00:00", "Z")

fdai_deployment_cli/lifecycle_authorization.py

@@ -0,0 +1,252 @@
+"""Local lifecycle authorization receipts and phase-fenced automatic apply guards."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Literal
+
+from fdai_deployment_cli.contracts import canonical_digest
+from fdai_deployment_cli.lifecycle_plan import LifecyclePlan, PlanAdmissionDecision
+
+LifecyclePhase = Literal["infrastructure", "workload"]
+
+_SUPPORTED_PHASES = frozenset({"infrastructure", "workload"})
+_PREFIXED_SHA256 = re.compile(r"sha256:[0-9a-f]{64}\Z", re.ASCII)
+_HEX_SHA256 = re.compile(r"[0-9a-f]{64}\Z", re.ASCII)
+
+
+def _require_aware(value: datetime, field: str) -> None:
+    if value.tzinfo is None or value.utcoffset() is None:
+        raise ValueError(f"{field} MUST include timezone information")
+
+
+def exact_plan_digest_for(plan: LifecyclePlan) -> str:
+    """Return the ``sha256:<hex>`` digest of a Plan's canonical signed payload bytes."""
+
+    if not plan.signed_payload:
+        raise ValueError("plan signed_payload MUST NOT be empty")
+    return f"sha256:{hashlib.sha256(plan.signed_payload).hexdigest()}"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class LifecyclePhaseCompletionReceipt:
+    """Recorded completion receipt for an earlier fenced Plan phase."""
+
+    plan_id: str
+    exact_plan_digest: str
+    fencing_generation: int
+    phase: LifecyclePhase
+    authorization_receipt_digest: str
+    completed_at: datetime
+
+    def __post_init__(self) -> None:
+        if not self.plan_id:
+            raise ValueError("plan_id MUST NOT be empty")
+        if _PREFIXED_SHA256.fullmatch(self.exact_plan_digest) is None:
+            raise ValueError("exact_plan_digest MUST be sha256:<64 hex>")
+        if (
+            isinstance(self.fencing_generation, bool)
+            or not isinstance(self.fencing_generation, int)
+            or self.fencing_generation < 1
+        ):
+            raise ValueError("fencing_generation MUST be a positive integer")
+        if self.phase not in _SUPPORTED_PHASES:
+            raise ValueError("phase is unsupported")
+        if _PREFIXED_SHA256.fullmatch(self.authorization_receipt_digest) is None:
+            raise ValueError("authorization_receipt_digest MUST be sha256:<64 hex>")
+        _require_aware(self.completed_at, "completed_at")
+
+    def to_mapping(self) -> dict[str, object]:
+        return {
+            "schema_version": "fdai.lifecycle-phase-completion-receipt.v1",
+            "plan_id": self.plan_id,
+            "exact_plan_digest": self.exact_plan_digest,
+            "fencing_generation": self.fencing_generation,
+            "phase": self.phase,
+            "authorization_receipt_digest": self.authorization_receipt_digest,
+            "completed_at": self.completed_at.isoformat(),
+        }
+
+    @property
+    def digest(self) -> str:
+        return f"sha256:{canonical_digest(self.to_mapping())}"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class LifecycleAuthorizationReceipt:
+    """Local lifecycle authorization receipt binding exact plan digest, inputs, and phase fence."""
+
+    plan_id: str
+    exact_plan_digest: str
+    fencing_generation: int
+    phase: LifecyclePhase
+    target_release_id: str
+    target_release_digest: str
+    configuration_revision_digest: str
+    window_starts_at: datetime
+    window_ends_at: datetime
+    issued_at: datetime
+    prerequisite_phase_receipt_digest: str | None = None
+
+    def __post_init__(self) -> None:
+        if not self.plan_id or not self.target_release_id:
+            raise ValueError("plan_id and target_release_id MUST NOT be empty")
+        if _PREFIXED_SHA256.fullmatch(self.exact_plan_digest) is None:
+            raise ValueError("exact_plan_digest MUST be sha256:<64 hex>")
+        if (
+            isinstance(self.fencing_generation, bool)
+            or not isinstance(self.fencing_generation, int)
+            or self.fencing_generation < 1
+        ):
+            raise ValueError("fencing_generation MUST be a positive integer")
+        if self.phase not in _SUPPORTED_PHASES:
+            raise ValueError("phase is unsupported")
+        if _HEX_SHA256.fullmatch(self.target_release_digest) is None:
+            raise ValueError("target_release_digest MUST be 64 lowercase hex characters")
+        if _HEX_SHA256.fullmatch(self.configuration_revision_digest) is None:
+            raise ValueError("configuration_revision_digest MUST be 64 lowercase hex characters")
+        if (
+            self.prerequisite_phase_receipt_digest is not None
+            and _PREFIXED_SHA256.fullmatch(self.prerequisite_phase_receipt_digest) is None
+        ):
+            raise ValueError("prerequisite_phase_receipt_digest MUST be sha256:<64 hex>")
+        _require_aware(self.window_starts_at, "window_starts_at")
+        _require_aware(self.window_ends_at, "window_ends_at")
+        _require_aware(self.issued_at, "issued_at")
+        if self.window_starts_at >= self.window_ends_at:
+            raise ValueError("window_starts_at MUST precede window_ends_at")
+
+    def to_mapping(self) -> dict[str, object]:
+        return {
+            "schema_version": "fdai.lifecycle-authorization-receipt.v1",
+            "plan_id": self.plan_id,
+            "exact_plan_digest": self.exact_plan_digest,
+            "fencing_generation": self.fencing_generation,
+            "phase": self.phase,
+            "target_release_id": self.target_release_id,
+            "target_release_digest": self.target_release_digest,
+            "configuration_revision_digest": self.configuration_revision_digest,
+            "window_starts_at": self.window_starts_at.isoformat(),
+            "window_ends_at": self.window_ends_at.isoformat(),
+            "issued_at": self.issued_at.isoformat(),
+            "prerequisite_phase_receipt_digest": self.prerequisite_phase_receipt_digest,
+        }
+
+    @classmethod
+    def from_mapping(cls, raw: Mapping[str, object]) -> LifecycleAuthorizationReceipt:
+        if raw.get("schema_version") != "fdai.lifecycle-authorization-receipt.v1":
+            raise ValueError("unsupported lifecycle authorization receipt schema")
+        prereq = raw.get("prerequisite_phase_receipt_digest")
+        if prereq is not None and not isinstance(prereq, str):
+            raise ValueError("prerequisite_phase_receipt_digest MUST be a string or null")
+        phase = raw.get("phase")
+        if phase not in ("infrastructure", "workload"):
+            raise ValueError("phase is unsupported")
+        fencing = raw.get("fencing_generation")
+        if isinstance(fencing, bool) or not isinstance(fencing, int):
+            raise ValueError("fencing_generation MUST be an integer")
+        return cls(
+            plan_id=str(raw["plan_id"]),
+            exact_plan_digest=str(raw["exact_plan_digest"]),
+            fencing_generation=fencing,
+            phase=phase,
+            target_release_id=str(raw["target_release_id"]),
+            target_release_digest=str(raw["target_release_digest"]),
+            configuration_revision_digest=str(raw["configuration_revision_digest"]),
+            window_starts_at=datetime.fromisoformat(str(raw["window_starts_at"])),
+            window_ends_at=datetime.fromisoformat(str(raw["window_ends_at"])),
+            issued_at=datetime.fromisoformat(str(raw["issued_at"])),
+            prerequisite_phase_receipt_digest=prereq,
+        )
+
+    @property
+    def digest(self) -> str:
+        return f"sha256:{canonical_digest(self.to_mapping())}"
+
+
+def issue_lifecycle_authorization_receipt(
+    plan: LifecyclePlan,
+    *,
+    phase: LifecyclePhase,
+    window_starts_at: datetime,
+    window_ends_at: datetime,
+    issued_at: datetime,
+    prerequisite_receipt: LifecyclePhaseCompletionReceipt | None = None,
+) -> LifecycleAuthorizationReceipt:
+    """Bind the exact signed Plan digest and optional earlier-phase receipt into a local receipt."""
+
+    return LifecycleAuthorizationReceipt(
+        plan_id=plan.plan_id,
+        exact_plan_digest=exact_plan_digest_for(plan),
+        fencing_generation=plan.fencing_generation,
+        phase=phase,
+        target_release_id=plan.target_release_id,
+        target_release_digest=plan.target_release_digest,
+        configuration_revision_digest=plan.configuration_revision_digest,
+        window_starts_at=window_starts_at,
+        window_ends_at=window_ends_at,
+        issued_at=issued_at,
+        prerequisite_phase_receipt_digest=(
+            None if prerequisite_receipt is None else prerequisite_receipt.digest
+        ),
+    )
+
+
+def evaluate_phase_authorization(
+    plan: LifecyclePlan,
+    *,
+    phase: LifecyclePhase,
+    authorization_receipt: LifecycleAuthorizationReceipt | None,
+    trusted_now: datetime,
+    require_earlier_phase: bool = False,
+    earlier_phase_receipt: LifecyclePhaseCompletionReceipt | None = None,
+) -> PlanAdmissionDecision:
+    """Verify local lifecycle authorization receipt binding and earlier-phase fencing."""
+
+    _require_aware(trusted_now, "trusted_now")
+    expected_plan_digest = exact_plan_digest_for(plan)
+    if require_earlier_phase:
+        if earlier_phase_receipt is None:
+            return PlanAdmissionDecision(
+                False, "earlier_phase_receipt_missing", ("infrastructure",)
+            )
+        if (
+            earlier_phase_receipt.plan_id != plan.plan_id
+            or earlier_phase_receipt.exact_plan_digest != expected_plan_digest
+            or earlier_phase_receipt.fencing_generation != plan.fencing_generation
+            or earlier_phase_receipt.phase != "infrastructure"
+        ):
+            return PlanAdmissionDecision(
+                False, "earlier_phase_receipt_mismatch", (earlier_phase_receipt.plan_id,)
+            )
+    if authorization_receipt is None:
+        return PlanAdmissionDecision(False, "authorization_receipt_missing", (plan.plan_id,))
+    if authorization_receipt.fencing_generation != plan.fencing_generation:
+        return PlanAdmissionDecision(
+            False, "phase_fencing_mismatch", (str(authorization_receipt.fencing_generation),)
+        )
+    if (
+        authorization_receipt.plan_id != plan.plan_id
+        or authorization_receipt.exact_plan_digest != expected_plan_digest
+        or authorization_receipt.phase != phase
+        or authorization_receipt.target_release_id != plan.target_release_id
+        or authorization_receipt.target_release_digest != plan.target_release_digest
+        or authorization_receipt.configuration_revision_digest != plan.configuration_revision_digest
+    ):
+        return PlanAdmissionDecision(False, "authorization_receipt_plan_mismatch", (plan.plan_id,))
+    if (
+        require_earlier_phase
+        and earlier_phase_receipt is not None
+        and authorization_receipt.prerequisite_phase_receipt_digest != earlier_phase_receipt.digest
+    ):
+        return PlanAdmissionDecision(False, "earlier_phase_receipt_mismatch", (plan.plan_id,))
+    if not (
+        authorization_receipt.window_starts_at <= trusted_now < authorization_receipt.window_ends_at
+        and trusted_now < plan.expires_at
+    ):
+        return PlanAdmissionDecision(False, "authorization_receipt_window_closed", (plan.plan_id,))
+    return PlanAdmissionDecision(True, "allowed", ())

fdai_deployment_cli/lifecycle_commands.py

@@ -0,0 +1,173 @@
+"""Lifecycle commands with mandatory expiry, authority-lowering bounds, and break-glass rules."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Literal
+
+from fdai_deployment_cli.contracts import canonical_bytes
+from fdai_deployment_cli.lifecycle_configuration import (
+    ConfigurationValidationError,
+    validate_configuration_package_for_signing,
+)
+from fdai_deployment_cli.lifecycle_plan import PlanAdmissionDecision
+
+LifecycleCommandKind = Literal["suppression-window", "authority-lowering", "break-glass"]
+BreakGlassBypass = Literal["maintenance-window", "suppression-window", "version-range"]
+
+_SUPPORTED_COMMAND_KINDS = frozenset({"suppression-window", "authority-lowering", "break-glass"})
+_ALLOWED_BREAK_GLASS_BYPASSES: frozenset[str] = frozenset(
+    {"maintenance-window", "suppression-window", "version-range"}
+)
+_ALLOWED_LOWERED_MODES = frozenset({"shadow"})
+_ALLOWED_LOWERED_AUTONOMY = frozenset({"shadow", "hil"})
+
+
+def _require_aware(value: datetime, field_name: str) -> None:
+    if value.tzinfo is None or value.utcoffset() is None:
+        raise ValueError(f"{field_name} MUST include timezone information")
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class LifecycleCommand:
+    """One time-bounded operator or break-glass command.
+
+    Every command requires an explicit ``expires_at`` after ``starts_at``. No command may
+    raise authority (promote an ActionType to ``enforce``, raise autonomy to ``auto``,
+    disengage the kill switch, or bypass signature, envelope, recall, schema, residency, or
+    destructive-change checks).
+    """
+
+    command_id: str
+    kind: LifecycleCommandKind
+    actor: str
+    reason: str
+    starts_at: datetime
+    expires_at: datetime | None = None
+    scope: str = "installation"
+    target_action_type: str | None = None
+    target_mode: str | None = None
+    target_autonomy: str | None = None
+    engage_kill_switch: bool = False
+    disengage_kill_switch: bool = False
+    bypass_scopes: frozenset[str] = field(default_factory=frozenset)
+    emergency_overrides: tuple[Mapping[str, object], ...] = ()
+    fresh_authenticated: bool = True
+
+    def is_active(self, now: datetime) -> bool:
+        _require_aware(now, "now")
+        if self.expires_at is None:
+            return False
+        return self.starts_at <= now < self.expires_at
+
+    def is_expired(self, now: datetime) -> bool:
+        _require_aware(now, "now")
+        if self.expires_at is None:
+            return False
+        return now >= self.expires_at
+
+
+def validate_lifecycle_command(
+    command: LifecycleCommand,
+    *,
+    trusted_now: datetime | None = None,
+) -> PlanAdmissionDecision:
+    """Validate mandatory expiry, kind-specific bounds, and the no-authority-raising invariant."""
+
+    if not command.command_id.strip() or not command.actor.strip() or not command.reason.strip():
+        return PlanAdmissionDecision(False, "command_metadata_missing", (command.command_id,))
+    if command.kind not in _SUPPORTED_COMMAND_KINDS:
+        return PlanAdmissionDecision(False, "command_kind_unsupported", (str(command.kind),))
+    _require_aware(command.starts_at, "starts_at")
+    if command.expires_at is None:
+        return PlanAdmissionDecision(False, "command_expiry_required", (command.command_id,))
+    _require_aware(command.expires_at, "expires_at")
+    if command.expires_at <= command.starts_at:
+        return PlanAdmissionDecision(False, "command_window_invalid", (command.command_id,))
+    if trusted_now is not None:
+        _require_aware(trusted_now, "trusted_now")
+        if command.expires_at <= trusted_now:
+            return PlanAdmissionDecision(False, "command_expired", (command.command_id,))
+
+    # Authority-raising checks apply across every command kind.
+    if command.disengage_kill_switch:
+        return PlanAdmissionDecision(False, "command_raises_authority", ("disengage_kill_switch",))
+    if command.target_mode is not None and command.target_mode not in _ALLOWED_LOWERED_MODES:
+        return PlanAdmissionDecision(
+            False, "command_raises_authority", (f"target_mode:{command.target_mode}",)
+        )
+    if (
+        command.target_autonomy is not None
+        and command.target_autonomy not in _ALLOWED_LOWERED_AUTONOMY
+    ):
+        return PlanAdmissionDecision(
+            False, "command_raises_authority", (f"target_autonomy:{command.target_autonomy}",)
+        )
+    forbidden_bypasses = sorted(command.bypass_scopes - _ALLOWED_BREAK_GLASS_BYPASSES)
+    if forbidden_bypasses:
+        return PlanAdmissionDecision(False, "command_raises_authority", tuple(forbidden_bypasses))
+
+    if command.kind == "suppression-window":
+        if (
+            command.target_mode is not None
+            or command.target_autonomy is not None
+            or command.engage_kill_switch
+            or command.bypass_scopes
+            or command.emergency_overrides
+        ):
+            return PlanAdmissionDecision(False, "command_scope_invalid", (command.command_id,))
+    elif command.kind == "authority-lowering":
+        if command.bypass_scopes or command.emergency_overrides:
+            return PlanAdmissionDecision(False, "command_raises_authority", (command.command_id,))
+        if not (
+            command.target_mode == "shadow"
+            or command.target_autonomy in _ALLOWED_LOWERED_AUTONOMY
+            or command.engage_kill_switch
+        ):
+            return PlanAdmissionDecision(
+                False, "command_lowering_effect_missing", (command.command_id,)
+            )
+    elif command.kind == "break-glass":
+        if not command.fresh_authenticated:
+            return PlanAdmissionDecision(
+                False, "break_glass_fresh_auth_required", (command.command_id,)
+            )
+        if not (command.bypass_scopes or command.emergency_overrides):
+            return PlanAdmissionDecision(False, "break_glass_effect_missing", (command.command_id,))
+        if command.emergency_overrides:
+            try:
+                validate_configuration_package_for_signing(
+                    {"overrides": command.emergency_overrides}
+                )
+            except ConfigurationValidationError as error:
+                return PlanAdmissionDecision(
+                    False, f"configuration_{error.code}", (command.command_id,)
+                )
+    return PlanAdmissionDecision(True, "allowed", ())
+
+
+def require_valid_lifecycle_command(
+    command: LifecycleCommand,
+    *,
+    trusted_now: datetime | None = None,
+) -> LifecycleCommand:
+    """Return ``command`` if valid, or raise ``ValueError`` with the rejection reason code."""
+
+    decision = validate_lifecycle_command(command, trusted_now=trusted_now)
+    if not decision.allowed:
+        raise ValueError(decision.reason_code)
+    return command
+
+
+def overrides_adopted(
+    emergency_overrides: tuple[Mapping[str, object], ...],
+    approved_overrides: tuple[Mapping[str, object], ...],
+) -> bool:
+    """Return whether every emergency override block is present in the approved overrides."""
+
+    if not emergency_overrides:
+        return True
+    approved_canonical = {canonical_bytes(block) for block in approved_overrides}
+    return all(canonical_bytes(block) in approved_canonical for block in emergency_overrides)