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

fdai_deployment_cli/installation_scope.py

@@ -0,0 +1,280 @@
+"""Collect immutable initial installation preferences without granting apply authority."""
+
+from __future__ import annotations
+
+import os
+import re
+import select
+import sys
+import time
+from dataclasses import asdict, dataclass
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+
+from fdai_service_contracts.product_profile import ProductAddOn
+
+from fdai_deployment_cli.contracts import canonical_bytes, canonical_digest, load_json_object
+from fdai_deployment_cli.private_output import read_private_bytes, write_private_bytes
+from fdai_deployment_cli.runtime_profile import RuntimeDeploymentProfile
+
+
+@dataclass(frozen=True, slots=True)
+class InstallationOptions:
+    """Requested cost, exposure and retention limits; no execution authorization."""
+
+    setup_cost_ceiling: int | None = None
+    console_access: str = "none"
+    allow_dedicated_identities: bool = False
+    cleanup_temporary_resources: bool = False
+
+    def __post_init__(self) -> None:
+        if self.setup_cost_ceiling is not None:
+            _budget(self.setup_cost_ceiling)
+        if self.console_access not in {"none", "public-https-entra", "private-https-entra"}:
+            raise ValueError("installation Console access is invalid")
+        if any(
+            type(value) is not bool
+            for value in (self.allow_dedicated_identities, self.cleanup_temporary_resources)
+        ):
+            raise ValueError("installation scope flags must be booleans")
+
+
+def confirm_installation_scope(
+    *,
+    work_dir: Path,
+    binding: dict[str, object],
+    runtime_profile: RuntimeDeploymentProfile,
+    options: InstallationOptions,
+    interactive: bool,
+    timeout_seconds: int,
+    now: datetime | None = None,
+) -> dict[str, object]:
+    """Confirm once before execution, or verify an unchanged unexpired retained scope.
+
+    Noninteractive, denied, legacy-started, changed and expired runs never prompt
+    later or renew consent. The record is not accepted as a Genesis approval.
+    """
+    _validate_binding(binding)
+    _validate_product_options(runtime_profile, options)
+    if runtime_profile.digest != binding["runtime_profile_digest"]:
+        raise ValueError("installation scope changed: runtime profile digest differs")
+    if type(timeout_seconds) is not int or not 1 <= timeout_seconds <= 86400:
+        raise ValueError("installation scope lifetime must be between 1 and 86400 seconds")
+    moment = now or datetime.now(UTC)
+    _utc(moment)
+    path = work_dir / "installation-scope.json"
+    try:
+        retained = load_json_object(
+            read_private_bytes(path, max_bytes=16384), label="installation scope"
+        )
+    except FileNotFoundError:
+        retained = None
+    if retained is not None:
+        expected = {
+            "schema_version",
+            "scope",
+            "confirmed_at",
+            "expires_at",
+            "apply_authorized",
+            "digest",
+        }
+        unsigned = {key: value for key, value in retained.items() if key != "digest"}
+        if (
+            set(retained) != expected
+            or retained["schema_version"] != "fdai.installation-scope.v1"
+            or retained["apply_authorized"] is not False
+            or retained["digest"] != canonical_digest(unsigned)
+        ):
+            raise ValueError("retained installation scope is invalid")
+        scope = retained["scope"]
+        if not isinstance(scope, dict):
+            raise ValueError("retained installation scope is invalid")
+        setup_cost = options.setup_cost_ceiling
+        if setup_cost is None:
+            setup_cost = _budget(scope.get("setup_cost_ceiling"))
+        if canonical_bytes(scope) != canonical_bytes(
+            _scope(binding, runtime_profile, options, setup_cost)
+        ):
+            raise ValueError(
+                "installation scope changed; preserve the run and review before restarting"
+            )
+        confirmed = _timestamp(retained["confirmed_at"])
+        expires = _timestamp(retained["expires_at"])
+        valid_window = confirmed <= moment < expires and timedelta(
+            0
+        ) < expires - confirmed <= timedelta(days=1)
+        if not valid_window and not started_installation_matches(work_dir, binding):
+            return _result("installation_scope_expired")
+        return _result("installation_scope_confirmed", str(retained["digest"]))
+    if (work_dir / "foundation/status.json").exists():
+        return _result("initial_confirmation_missing_for_started_run")
+    if not interactive:
+        return _result("initial_confirmation_required")
+    deadline = time.monotonic() + min(600, timeout_seconds)
+    setup_cost = options.setup_cost_ceiling
+    if setup_cost is None:
+        print(
+            "Initial setup cost estimate ceiling (USD, whole number): ",
+            end="",
+            file=sys.stderr,
+            flush=True,
+        )
+        answer = _read_initial_answer(deadline)
+        if re.fullmatch(r"[1-9][0-9]{0,6}", answer) is None:
+            return _result("initial_confirmation_denied")
+        setup_cost = _budget(int(answer))
+    scope = _scope(binding, runtime_profile, options, setup_cost)
+    print("Initial installation scope (not an exact-plan approval):", file=sys.stderr)
+    for key, value in scope.items():
+        print(f"  {key}: {value}", file=sys.stderr)
+    print(
+        "Estimates are not billing caps. Existing resources and runtime authority are excluded.\n"
+        "Later missing authority or evidence stops the run without another prompt.\n"
+        "Type install to confirm these settings, or anything else to stop: ",
+        end="",
+        file=sys.stderr,
+        flush=True,
+    )
+    if _read_initial_answer(deadline) != "install":
+        return _result("initial_confirmation_denied")
+    elapsed = min(600, timeout_seconds) - max(0.0, deadline - time.monotonic())
+    confirmed_at = moment + timedelta(seconds=elapsed)
+    if confirmed_at >= moment + timedelta(seconds=timeout_seconds):
+        return _result("installation_scope_expired")
+    record: dict[str, object] = {
+        "schema_version": "fdai.installation-scope.v1",
+        "scope": scope,
+        "confirmed_at": confirmed_at.isoformat(),
+        "expires_at": (moment + timedelta(seconds=timeout_seconds)).isoformat(),
+        "apply_authorized": False,
+    }
+    record["digest"] = canonical_digest(record)
+    write_private_bytes(path, canonical_bytes(record))
+    return _result("installation_scope_confirmed", str(record["digest"]))
+
+
+def _scope(
+    binding: dict[str, object],
+    runtime_profile: RuntimeDeploymentProfile,
+    options: InstallationOptions,
+    setup_cost: int,
+) -> dict[str, object]:
+    return {
+        **binding,
+        "runtime_profile": runtime_profile.to_mapping(),
+        **asdict(options),
+        "setup_cost_ceiling": setup_cost,
+        "resource_scope": "new-installation-only",
+        "retain_services": True,
+        "runtime_authority_change": False,
+    }
+
+
+def _result(reason: str, digest: str | None = None) -> dict[str, object]:
+    return {
+        "schema_version": "fdai.installation-scope-result.v1",
+        "state": "confirmed" if digest else "review",
+        "stage": "initial-confirmation",
+        "reason_code": reason,
+        "scope_digest": digest,
+        "apply_authorized": False,
+        "mutation_performed": False,
+        "deployment_ready": False,
+    }
+
+
+def started_installation_matches(
+    work_dir: Path,
+    binding: dict[str, object],
+) -> bool:
+    """Let an effected installation reuse its immutable preferences after their initial window."""
+    try:
+        status = load_json_object(
+            read_private_bytes(work_dir / "foundation/status.json", max_bytes=1024 * 1024),
+            label="Foundation status",
+        )
+        profile = load_json_object(
+            read_private_bytes(work_dir / "foundation/profile.json", max_bytes=16384),
+            label="Foundation profile",
+        )
+    except (FileNotFoundError, OSError, ValueError):
+        return False
+    return (
+        status.get("schema_version") == "fdai.genesis-orchestration-status.v2"
+        and status.get("mutation_performed") is True
+        and status.get("source_commit") == binding["source_commit"]
+        and profile.get("schema_version") == "fdai.provision-profile.v1"
+        and profile.get("target_binding") == binding["target_binding"]
+    )
+
+
+def _validate_product_options(
+    runtime_profile: RuntimeDeploymentProfile,
+    options: InstallationOptions,
+) -> None:
+    console_selected = runtime_profile.product_profile.selects(ProductAddOn.READ_ONLY_CONSOLE)
+    if console_selected and options.console_access == "none":
+        raise ValueError("selected read-only Console requires an explicit access profile")
+    if not console_selected and options.console_access != "none":
+        raise ValueError("Console access requires the read-only-console product add-on")
+
+
+def _validate_binding(binding: dict[str, object]) -> None:
+    if set(binding) != {
+        "source_commit",
+        "target_binding",
+        "preparation_digest",
+        "runtime_profile_digest",
+        "region",
+        "monthly_cost_ceiling",
+    }:
+        raise ValueError("installation scope binding fields are invalid")
+    for key in ("source_commit", "target_binding", "preparation_digest", "runtime_profile_digest"):
+        value = binding[key]
+        length = 40 if key == "source_commit" else 64
+        if not isinstance(value, str) or re.fullmatch(rf"[0-9a-f]{{{length}}}", value) is None:
+            raise ValueError("installation scope binding digest is invalid")
+    region = binding["region"]
+    if not isinstance(region, str) or re.fullmatch(r"[a-z][a-z0-9]{1,40}", region) is None:
+        raise ValueError("installation scope region is invalid")
+    _budget(binding["monthly_cost_ceiling"])
+
+
+def _budget(value: object) -> int:
+    if type(value) is not int or not 1 <= value <= 1000000:
+        raise ValueError(
+            "installation cost ceiling must be a whole USD amount between 1 and 1000000"
+        )
+    return value
+
+
+def _utc(value: datetime) -> None:
+    if value.tzinfo is None or value.utcoffset() != timedelta(0):
+        raise ValueError("installation scope timestamp must be UTC")
+
+
+def _timestamp(value: object) -> datetime:
+    if not isinstance(value, str):
+        raise TypeError("installation scope timestamp is invalid")
+    result = datetime.fromisoformat(value)
+    _utc(result)
+    return result
+
+
+def _read_initial_answer(deadline: float) -> str:
+    """Read one bounded TTY line without an unbounded readline after partial input."""
+    if not sys.stdin.isatty():
+        raise ValueError("initial confirmation requires an interactive terminal")
+    descriptor = sys.stdin.fileno()
+    answer = bytearray()
+    while len(answer) <= 64:
+        remaining = deadline - time.monotonic()
+        if remaining <= 0 or not select.select([descriptor], [], [], remaining)[0]:
+            raise TimeoutError("initial confirmation timed out; no consent was recorded")
+        chunk = os.read(descriptor, 1)
+        if not chunk:
+            raise ValueError("initial confirmation input closed; no consent was recorded")
+        if chunk == b"\n":
+            return answer.decode("ascii").strip()
+        answer.extend(chunk)
+    raise ValueError("initial confirmation input exceeds its limit")

fdai_deployment_cli/license.py

@@ -0,0 +1,311 @@
+"""Offline capability-license inspection without runtime dependencies."""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import json
+import re
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+from cryptography.hazmat.primitives.serialization import load_pem_public_key
+
+from fdai_deployment_cli.contracts import canonical_bytes, load_json_object
+
+_B64URL = re.compile(r"^[A-Za-z0-9_-]+$")
+_ID = re.compile(r"^[a-z0-9][a-z0-9._-]{2,127}$")
+_DIGEST = re.compile(r"^[0-9a-f]{64}$")
+_MAX_CAPABILITIES = 512
+_MAX_VALIDITY = timedelta(days=30)
+
+
+class LicenseInspectionError(ValueError):
+    """A license token is malformed, untrusted, or inactive."""
+
+
+@dataclass(frozen=True, slots=True)
+class LicenseInspection:
+    """Sanitized active-license result."""
+
+    license_id: str
+    distribution_id: str
+    capability_ids: tuple[str, ...]
+    not_before: str
+    not_after: str
+    active: bool
+
+    def to_json(self) -> str:
+        """Return stable JSON without the bearer token."""
+
+        return json.dumps(
+            {
+                "schema_version": "fdai.license-inspection.v1",
+                "license_id": self.license_id,
+                "distribution_id": self.distribution_id,
+                "capability_ids": list(self.capability_ids),
+                "not_before": self.not_before,
+                "not_after": self.not_after,
+                "active": self.active,
+            },
+            sort_keys=True,
+            separators=(",", ":"),
+        )
+
+
+def inspect_license(
+    token: str,
+    *,
+    public_key_pem: bytes,
+    now: datetime | None = None,
+    expected_image_digest: str | None = None,
+    expected_tenant_binding: str | None = None,
+) -> LicenseInspection:
+    """Verify one signed canonical token and report active entitlement."""
+
+    if not token or len(token) > 8192:
+        raise LicenseInspectionError("license token is empty or exceeds its size limit")
+    parts = token.split(".")
+    if len(parts) != 2:
+        raise LicenseInspectionError("license token MUST contain document and signature")
+    document = _decode(parts[0], "document")
+    signature = _decode(parts[1], "signature")
+    if len(signature) != 64:
+        raise LicenseInspectionError("license signature MUST be 64 bytes")
+    _verify(public_key_pem, document, signature)
+    payload = load_json_object(document, label="license document", max_bytes=6144)
+    expected = {
+        "schema_version",
+        "license_id",
+        "distribution_id",
+        "capability_ids",
+        "not_before",
+        "not_after",
+        "image_digest",
+        "tenant_binding",
+    }
+    if set(payload) != expected or payload["schema_version"] != "fdai.license.v1":
+        raise LicenseInspectionError("license document schema does not match")
+    if canonical_bytes(payload) != document:
+        raise LicenseInspectionError("license document is not canonical")
+    not_before = _moment(payload, "not_before")
+    not_after = _moment(payload, "not_after")
+    if _text(payload, "not_before") != _canonical_moment(not_before) or _text(
+        payload, "not_after"
+    ) != _canonical_moment(not_after):
+        raise LicenseInspectionError("license timestamps are not canonically encoded")
+    if not_after <= not_before:
+        raise LicenseInspectionError("license validity window is invalid")
+    if not_after.astimezone(UTC) - not_before.astimezone(UTC) > _MAX_VALIDITY:
+        raise LicenseInspectionError("license validity MUST NOT exceed 30 elapsed UTC days")
+    evaluated = now or datetime.now(UTC)
+    if evaluated.tzinfo is None:
+        raise LicenseInspectionError("license evaluation time MUST be timezone-aware")
+    capabilities = payload["capability_ids"]
+    if (
+        not isinstance(capabilities, list)
+        or not capabilities
+        or not all(isinstance(item, str) and item for item in capabilities)
+    ):
+        raise LicenseInspectionError("license capability_ids are invalid")
+    if capabilities != sorted(set(capabilities)):
+        raise LicenseInspectionError("license capability_ids MUST be unique and sorted")
+    if len(capabilities) > _MAX_CAPABILITIES:
+        raise LicenseInspectionError("license capability_ids exceeds the supported count")
+    license_id = _text(payload, "license_id")
+    distribution_id = _text(payload, "distribution_id")
+    if _ID.fullmatch(license_id) is None or _ID.fullmatch(distribution_id) is None:
+        raise LicenseInspectionError("license identifiers MUST be lowercase stable identifiers")
+    if any(_ID.fullmatch(item) is None for item in capabilities):
+        raise LicenseInspectionError("license capability_ids MUST be lowercase stable identifiers")
+    _verify_optional_binding(
+        payload,
+        field="image_digest",
+        expected=expected_image_digest,
+    )
+    _verify_optional_binding(
+        payload,
+        field="tenant_binding",
+        expected=expected_tenant_binding,
+    )
+    active = not_before <= evaluated < not_after
+    if not active:
+        raise LicenseInspectionError("license is not active")
+    return LicenseInspection(
+        license_id=license_id,
+        distribution_id=distribution_id,
+        capability_ids=tuple(capabilities),
+        not_before=not_before.isoformat(),
+        not_after=not_after.isoformat(),
+        active=True,
+    )
+
+
+INSTALLATION_ENTITLEMENT_SCHEMA = "fdai.installation-entitlement.v1"
+_ENTITLEMENT_FIELDS = frozenset(
+    {
+        "schema_version",
+        "entitlement_id",
+        "distribution_id",
+        "installation_binding",
+        "deployment_binding",
+        "issued_at",
+    }
+)
+
+
+@dataclass(frozen=True, slots=True)
+class InstallationEntitlementInspection:
+    """Sanitized result for an exactly bound installation entitlement."""
+
+    entitlement_id: str
+    distribution_id: str
+    issued_at: str
+
+    def to_json(self) -> str:
+        """Return stable JSON without the bearer token or either binding digest."""
+
+        return json.dumps(
+            {
+                "schema_version": "fdai.installation-entitlement-inspection.v1",
+                "entitlement_id": self.entitlement_id,
+                "distribution_id": self.distribution_id,
+                "issued_at": self.issued_at,
+                "complete_catalog": True,
+                "expires": False,
+                "active": True,
+            },
+            sort_keys=True,
+            separators=(",", ":"),
+        )
+
+
+def signed_token_schema(token: str) -> str | None:
+    """Return the schema a token's document declares, without establishing trust."""
+
+    parts = token.split(".")
+    if len(parts) != 2 or len(token) > 8192:
+        return None
+    try:
+        payload = json.loads(_decode(parts[0], "document"))
+    except (LicenseInspectionError, UnicodeDecodeError, json.JSONDecodeError):
+        return None
+    schema = payload.get("schema_version") if isinstance(payload, dict) else None
+    return schema if isinstance(schema, str) else None
+
+
+def inspect_installation_entitlement(
+    token: str,
+    *,
+    public_key_pem: bytes,
+    expected_installation_binding: str,
+    expected_deployment_binding: str,
+) -> InstallationEntitlementInspection:
+    """Verify one installation entitlement against the exact bindings it must carry."""
+
+    for label, expected in (
+        ("installation binding", expected_installation_binding),
+        ("deployment binding", expected_deployment_binding),
+    ):
+        if _DIGEST.fullmatch(expected) is None:
+            raise LicenseInspectionError(f"expected {label} MUST be a lowercase SHA-256")
+    if not token or len(token) > 8192:
+        raise LicenseInspectionError("entitlement is empty or exceeds its size limit")
+    parts = token.split(".")
+    if len(parts) != 2:
+        raise LicenseInspectionError("entitlement MUST contain document and signature")
+    document = _decode(parts[0], "document")
+    signature = _decode(parts[1], "signature")
+    if len(signature) != 64:
+        raise LicenseInspectionError("entitlement signature MUST be 64 bytes")
+    _verify(public_key_pem, document, signature)
+    payload = load_json_object(document, label="entitlement document", max_bytes=2048)
+    if (
+        set(payload) != _ENTITLEMENT_FIELDS
+        or payload["schema_version"] != INSTALLATION_ENTITLEMENT_SCHEMA
+    ):
+        raise LicenseInspectionError("entitlement document schema does not match")
+    if canonical_bytes(payload) != document:
+        raise LicenseInspectionError("entitlement document is not canonical")
+    entitlement_id = _text(payload, "entitlement_id")
+    distribution_id = _text(payload, "distribution_id")
+    if _ID.fullmatch(entitlement_id) is None or _ID.fullmatch(distribution_id) is None:
+        raise LicenseInspectionError("entitlement identifiers MUST be lowercase stable identifiers")
+    issued_at = _moment(payload, "issued_at")
+    if _text(payload, "issued_at") != _canonical_moment(issued_at):
+        raise LicenseInspectionError("entitlement issued_at is not canonically encoded")
+    if _text(payload, "installation_binding") != expected_installation_binding:
+        raise LicenseInspectionError("entitlement installation binding does not match")
+    if _text(payload, "deployment_binding") != expected_deployment_binding:
+        raise LicenseInspectionError("entitlement deployment binding does not match")
+    return InstallationEntitlementInspection(
+        entitlement_id=entitlement_id,
+        distribution_id=distribution_id,
+        issued_at=issued_at.isoformat(),
+    )
+
+
+def _decode(value: str, label: str) -> bytes:
+    if _B64URL.fullmatch(value) is None:
+        raise LicenseInspectionError(f"license {label} is not canonical base64url")
+    try:
+        decoded = base64.urlsafe_b64decode(value + "=" * (-len(value) % 4))
+    except (ValueError, binascii.Error) as exc:
+        raise LicenseInspectionError(f"license {label} is not base64url") from exc
+    if base64.urlsafe_b64encode(decoded).rstrip(b"=").decode() != value:
+        raise LicenseInspectionError(f"license {label} is not canonical base64url")
+    return decoded
+
+
+def _verify_optional_binding(
+    payload: dict[str, object],
+    *,
+    field: str,
+    expected: str | None,
+) -> None:
+    value = payload[field]
+    if value is not None and (not isinstance(value, str) or _DIGEST.fullmatch(value) is None):
+        raise LicenseInspectionError(f"license {field} MUST be a lowercase SHA-256 or null")
+    if expected is not None and _DIGEST.fullmatch(expected) is None:
+        raise LicenseInspectionError(f"expected {field} MUST be a lowercase SHA-256")
+    if value is not None and expected is None:
+        raise LicenseInspectionError(f"license {field} requires an expected binding")
+    if expected is not None and value != expected:
+        raise LicenseInspectionError(f"license {field} does not match")
+
+
+def _verify(public_pem: bytes, document: bytes, signature: bytes) -> None:
+    try:
+        key = load_pem_public_key(public_pem)
+    except (TypeError, ValueError) as exc:
+        raise LicenseInspectionError("license public key is invalid") from exc
+    if not isinstance(key, Ed25519PublicKey):
+        raise LicenseInspectionError("license public key MUST be Ed25519")
+    try:
+        key.verify(signature, document)
+    except InvalidSignature as exc:
+        raise LicenseInspectionError("license signature is invalid") from exc
+
+
+def _moment(value: dict[str, object], field: str) -> datetime:
+    raw = _text(value, field)
+    try:
+        moment = datetime.fromisoformat(raw)
+    except ValueError as exc:
+        raise LicenseInspectionError(f"license {field} MUST be ISO 8601") from exc
+    if moment.tzinfo is None:
+        raise LicenseInspectionError(f"license {field} MUST be timezone-aware")
+    return moment
+
+
+def _canonical_moment(moment: datetime) -> str:
+    return moment.astimezone(UTC).isoformat().replace("+00:00", "Z")
+
+
+def _text(value: dict[str, object], field: str) -> str:
+    item = value[field]
+    if not isinstance(item, str) or not item:
+        raise LicenseInspectionError(f"license {field} MUST be text")
+    return item