@mriekki/lean 0.0.0-stage → 0.1.0

package/assets/generated/deployment/src/lean_poc_deployment/security.py

@@ -0,0 +1,290 @@
+"""Filesystem integrity checks for SSH identity and host-trust material."""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+import shutil
+import stat
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from .errors import DeploymentKitError
+
+
+WINDOWS_SID_RE = __import__("re").compile(r"^S-1-(?:[0-9]+-){1,15}[0-9]+$")
+HOST_KEY_TYPES = {"ssh-ed25519", "ecdsa-sha2-nistp256", "ssh-rsa"}
+
+
+def _valid_windows_sid(value: Any) -> bool:
+    if not isinstance(value, str) or WINDOWS_SID_RE.fullmatch(value) is None:
+        return False
+    components = value.split("-")
+    subauthorities = components[3:]
+    if not 1 <= len(subauthorities) <= 15:
+        return False
+
+    def within_bound(component: str, maximum: int) -> bool:
+        if component != "0" and component.startswith("0"):
+            return False
+        limit = str(maximum)
+        return len(component) < len(limit) or (len(component) == len(limit) and component <= limit)
+
+    return within_bound(components[2], 0xFFFFFFFFFFFF) and all(
+        within_bound(component, 0xFFFFFFFF) for component in subauthorities
+    )
+
+
+def validate_windows_acl_report(report: Any) -> None:
+    try:
+        if not isinstance(report, dict) or set(report) != {"currentUserSid", "entries"}:
+            raise ValueError("unexpected ACL report shape")
+        current_user = report["currentUserSid"]
+        entries = report["entries"]
+        if not _valid_windows_sid(current_user):
+            raise ValueError("invalid current-user SID")
+        if not isinstance(entries, list) or not entries:
+            raise ValueError("missing ACL entries")
+
+        trusted_sids = {current_user, "S-1-5-18", "S-1-5-32-544"}
+        write_rights = 2 | 4 | 16 | 64 | 256 | 65536 | 262144 | 524288
+        known_rights = (
+            1 | 2 | 4 | 8 | 16 | 32 | 64 | 128 | 256 |
+            65536 | 131072 | 262144 | 524288 | 1048576
+        )
+
+        for entry in entries:
+            if (
+                not isinstance(entry, dict)
+                or set(entry) != {"path", "ownerSid", "reparsePoint", "rules"}
+                or not isinstance(entry["path"], str)
+                or not entry["path"]
+                or not _valid_windows_sid(entry["ownerSid"])
+                or type(entry["reparsePoint"]) is not bool
+                or not isinstance(entry["rules"], list)
+            ):
+                raise ValueError("malformed ACL entry")
+            if entry["reparsePoint"] or entry["ownerSid"] not in trusted_sids:
+                raise DeploymentKitError(
+                    f"Windows SSH material has an untrusted owner or reparse point: {entry['path']}"
+                )
+            for rule in entry["rules"]:
+                if (
+                    not isinstance(rule, dict)
+                    or set(rule) != {"sid", "rights", "type"}
+                    or not _valid_windows_sid(rule["sid"])
+                    or rule["type"] not in {"Allow", "Deny"}
+                    or type(rule["rights"]) is not int
+                    or rule["rights"] < 0
+                    or rule["rights"] & ~known_rights
+                ):
+                    raise ValueError("malformed ACL rule")
+                if (
+                    rule["type"] == "Allow"
+                    and rule["sid"] not in trusted_sids
+                    and rule["rights"] & write_rights
+                ):
+                    raise DeploymentKitError(
+                        f"Windows SSH material grants write access to an untrusted principal: {entry['path']}"
+                    )
+    except (KeyError, TypeError, ValueError, json.JSONDecodeError) as error:
+        raise DeploymentKitError(
+            "Windows SSH-material ACL report was malformed; verification is blocked."
+        ) from error
+
+
+def _ssh_directory_for(path: Path) -> Path:
+    candidates = (path, *path.parents)
+    ssh_directory = next((candidate for candidate in candidates if candidate.name.lower() == ".ssh"), None)
+    if ssh_directory is None:
+        raise DeploymentKitError("SSH material is not inside the user's .ssh directory.")
+    return ssh_directory
+
+
+def _check_windows_acl(path: Path) -> None:
+    powershell = shutil.which("pwsh") or shutil.which("powershell")
+    if powershell is None:
+        raise DeploymentKitError(
+            "Cannot verify Windows SSH-material ACLs because PowerShell is unavailable."
+        )
+    ssh_directory = _ssh_directory_for(path)
+
+    checked_paths = [path]
+    directory = path.parent
+    while True:
+        checked_paths.append(directory)
+        if directory == ssh_directory.parent:
+            break
+        if directory != ssh_directory and ssh_directory not in directory.parents:
+            raise DeploymentKitError("SSH-material path escaped the user's .ssh directory.")
+        directory = directory.parent
+
+    serialized_paths = json.dumps([str(candidate) for candidate in dict.fromkeys(checked_paths)])
+    serialized_paths = serialized_paths.replace("'", "''")
+    script = f"""
+$ErrorActionPreference = 'Stop'
+[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
+$paths = @(ConvertFrom-Json -InputObject '{serialized_paths}')
+$userSid = [System.Security.Principal.WindowsIdentity]::GetCurrent().User.Value
+$entries = foreach ($candidate in $paths) {{
+    $item = Get-Item -LiteralPath $candidate -Force
+    $acl = Get-Acl -LiteralPath $candidate
+    $rules = foreach ($rule in $acl.GetAccessRules($true, $true, [System.Security.Principal.SecurityIdentifier])) {{
+        [ordered]@{{
+            sid = $rule.IdentityReference.Value
+            rights = [int]$rule.FileSystemRights
+            type = $rule.AccessControlType.ToString()
+        }}
+    }}
+    [ordered]@{{
+        path = $candidate
+        ownerSid = $acl.GetOwner([System.Security.Principal.SecurityIdentifier]).Value
+        reparsePoint = (($item.Attributes -band [System.IO.FileAttributes]::ReparsePoint) -ne 0)
+        rules = @($rules)
+    }}
+}}
+[ordered]@{{ currentUserSid = $userSid; entries = @($entries) }} | ConvertTo-Json -Depth 6 -Compress
+"""
+    result = subprocess.run(
+        [powershell, "-NoProfile", "-NonInteractive", "-Command", script],
+        check=False,
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+    )
+    if result.returncode != 0:
+        raise DeploymentKitError(
+            "Cannot verify Windows SSH-material ACLs; access verification is blocked."
+        )
+    try:
+        validate_windows_acl_report(json.loads(result.stdout))
+    except (TypeError, ValueError, json.JSONDecodeError) as error:
+        raise DeploymentKitError(
+            "Windows SSH-material ACL report was malformed; verification is blocked."
+        ) from error
+
+
+def _posix_directory_chain(path: Path) -> list[Path]:
+    ssh_directory = _ssh_directory_for(path)
+    directories: list[Path] = []
+    current = path.parent
+    while True:
+        directories.append(current)
+        if current == ssh_directory:
+            return directories
+        if current == current.parent:
+            raise DeploymentKitError("SSH-material path escaped the user's .ssh directory.")
+        current = current.parent
+
+
+def _check_posix_directories(path: Path) -> None:
+    for directory in _posix_directory_chain(path):
+        if directory.is_symlink() or not directory.is_dir():
+            raise DeploymentKitError(f"SSH directory must be a real directory: {directory}")
+        if directory.stat().st_mode & (stat.S_IRWXG | stat.S_IRWXO):
+            raise DeploymentKitError(f"SSH directory permissions are too broad: {directory}")
+
+
+def prepare_ssh_directory(path: Path) -> None:
+    """Create one SSH-material directory when absent, then verify its safety before secrets are written."""
+    _ssh_directory_for(path)
+    if path.exists():
+        if path.is_symlink() or not path.is_dir():
+            raise DeploymentKitError(f"SSH material directory is not a real directory: {path}")
+    else:
+        path.mkdir(parents=True, mode=0o700)
+    if os.name != "nt":
+        path.chmod(0o700)
+        _check_posix_directories(path / "placeholder")
+    else:
+        _check_windows_acl(path)
+
+
+def check_identity_security(identity: Path) -> None:
+    if not identity.is_file():
+        raise DeploymentKitError(f"Required SSH identity is missing: {identity}")
+    if identity.is_symlink():
+        raise DeploymentKitError(f"SSH material must not use symbolic links: {identity}")
+    if os.name == "nt":
+        _check_windows_acl(identity)
+    else:
+        _check_posix_directories(identity)
+        if identity.stat().st_mode & (stat.S_IRWXG | stat.S_IRWXO):
+            raise DeploymentKitError(f"Private key permissions are too broad: {identity}")
+
+
+def check_known_hosts_security(known_hosts: Path) -> None:
+    if not known_hosts.is_file():
+        raise DeploymentKitError(f"Required SSH trust file is missing: {known_hosts}")
+    if known_hosts.is_symlink():
+        raise DeploymentKitError(f"SSH material must not use symbolic links: {known_hosts}")
+    if os.name == "nt":
+        _check_windows_acl(known_hosts)
+    else:
+        _check_posix_directories(known_hosts)
+        if known_hosts.stat().st_mode & (stat.S_IWGRP | stat.S_IWOTH):
+            raise DeploymentKitError(f"Target trust file is writable by another principal: {known_hosts}")
+
+
+def check_ssh_material_security(identity: Path, known_hosts: Path) -> None:
+    check_identity_security(identity)
+    check_known_hosts_security(known_hosts)
+
+
+def known_hosts_token(profile: dict[str, Any]) -> str:
+    alias = profile["sshAlias"]
+    port = profile["port"]
+    return alias if port == 22 else f"[{alias}]:{port}"
+
+
+def validate_target_trust_file(
+    profile: dict[str, Any],
+    *,
+    allow_missing_or_empty: bool = False,
+) -> list[tuple[str, str]]:
+    """Validate that a target trust file contains only one exact stable-alias host key."""
+    path = Path(profile["knownHostsFile"])
+    if not path.exists():
+        if allow_missing_or_empty:
+            return []
+        raise DeploymentKitError(f"Target-specific trust file is missing: {path}")
+    if path.is_symlink() or not path.is_file():
+        raise DeploymentKitError(f"Target-specific trust file is not a real file: {path}")
+    try:
+        raw_lines = path.read_text(encoding="utf-8").splitlines()
+    except (OSError, UnicodeError) as error:
+        raise DeploymentKitError(f"Cannot read target-specific trust file {path}: {error}") from error
+
+    lines = [line.strip() for line in raw_lines if line.strip()]
+    if not lines:
+        if allow_missing_or_empty:
+            return []
+        raise DeploymentKitError(f"Target-specific trust file is empty: {path}")
+    if len(lines) != 1:
+        raise DeploymentKitError(
+            "Target-specific trust file must contain exactly one literal stable-alias host key."
+        )
+
+    fields = lines[0].split()
+    if len(fields) != 3:
+        raise DeploymentKitError("Target-specific trust entry must contain exactly host, key type, and key data.")
+    host_token, key_type, key_data = fields
+    expected = known_hosts_token(profile)
+    if host_token != expected:
+        raise DeploymentKitError(
+            f"Target-specific trust entry must use only the stable alias token '{expected}'."
+        )
+    if any(marker in host_token for marker in ("*", "?", ",", "|")) or host_token.startswith("@"):
+        raise DeploymentKitError("Wildcard, hashed, marked, or multi-host trust entries are not allowed.")
+    if key_type not in HOST_KEY_TYPES:
+        raise DeploymentKitError(f"Unsupported target host-key type in trust file: {key_type}")
+    try:
+        decoded = base64.b64decode(key_data.encode("ascii"), validate=True)
+    except (ValueError, UnicodeError) as error:
+        raise DeploymentKitError("Target-specific trust entry contains invalid key data.") from error
+    if not decoded:
+        raise DeploymentKitError("Target-specific trust entry contains empty key data.")
+    return [(key_type, key_data)]

package/assets/generated/deployment/src/lean_poc_deployment/sqlite_adapter.py

@@ -0,0 +1,335 @@
+"""SQLite persistence adapter for Kit-managed application runtimes."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import posixpath
+import re
+import subprocess
+from typing import Any, Iterable
+
+from .app_runtime import APP_ROOT
+from .box_platform import platform_status
+from .errors import DeploymentKitError
+from .profiles import load_profile
+from .sqlite_adapter_remote import REMOTE_SCRIPT
+from .ssh import ssh_args, verify_access
+
+SQLITE_SCHEMA_VERSION = 1
+SQLITE_IMPORT_WRITE_PHRASE = "[SQLITE IMPORT WRITE]"
+PRODUCTION_SQLITE_IMPORT_WRITE_PHRASE = "[PRODUCTION SQLITE IMPORT]"
+SQLITE_BACKUP_WRITE_PHRASE = "[SQLITE BACKUP WRITE]"
+PRODUCTION_SQLITE_BACKUP_WRITE_PHRASE = "[PRODUCTION SQLITE BACKUP]"
+SQLITE_MIGRATE_WRITE_PHRASE = "[SQLITE MIGRATE WRITE]"
+PRODUCTION_SQLITE_MIGRATE_WRITE_PHRASE = "[PRODUCTION SQLITE MIGRATE]"
+SQLITE_ROLLBACK_CHECK_PHRASE = "[SQLITE ROLLBACK CHECK]"
+PRODUCTION_SQLITE_ROLLBACK_CHECK_PHRASE = "[PRODUCTION SQLITE ROLLBACK CHECK]"
+
+_SLUG_RE = re.compile(r"^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$")
+_REPO_RE = re.compile(r"^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$")
+_IMAGE_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._/:+-]*@sha256:[0-9a-f]{64}$")
+_RUN_AS_RE = re.compile(r"^[0-9]+(?::[0-9]+)?$")
+_DB_FILE_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$")
+_ENV_KEY_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+_SOURCE_RE = re.compile(r"^/srv/[A-Za-z0-9._/+-]+$")
+
+
+def _slug(value: str, field: str) -> str:
+    if not isinstance(value, str) or _SLUG_RE.fullmatch(value) is None:
+        raise DeploymentKitError(f"{field} must use lowercase letters, digits, and internal hyphens.")
+    return value
+
+
+def _owner_repo(value: str) -> str:
+    if not isinstance(value, str) or _REPO_RE.fullmatch(value) is None:
+        raise DeploymentKitError("ownerRepo must use GitHub owner/repository form without URL syntax.")
+    return value
+
+
+def _image(value: str) -> str:
+    if not isinstance(value, str) or _IMAGE_RE.fullmatch(value) is None:
+        raise DeploymentKitError("image must be an immutable image reference ending in @sha256:<64 lowercase hex>.")
+    return value
+
+
+def _run_as(value: str) -> str:
+    if not isinstance(value, str) or _RUN_AS_RE.fullmatch(value) is None:
+        raise DeploymentKitError("runAs must be a numeric UID or UID:GID.")
+    return value
+
+
+def _database_file(value: str) -> str:
+    if not isinstance(value, str) or _DB_FILE_RE.fullmatch(value) is None or value in {".", ".."}:
+        raise DeploymentKitError("databaseFile must be a safe file name without path separators.")
+    return value
+
+
+def _source_database(value: str) -> str:
+    if not isinstance(value, str) or _SOURCE_RE.fullmatch(value) is None:
+        raise DeploymentKitError("sourceDatabase must be a safe absolute path under /srv.")
+    normalized = posixpath.normpath(value)
+    if normalized != value or "/../" in f"{value}/":
+        raise DeploymentKitError("sourceDatabase must not contain path traversal or normalization changes.")
+    if value.startswith(APP_ROOT + "/"):
+        raise DeploymentKitError("sourceDatabase must be outside the Kit-managed application root.")
+    return value
+
+
+def _normalize_env(items: dict[str, str] | Iterable[tuple[str, str]]) -> dict[str, str]:
+    pairs = items.items() if isinstance(items, dict) else items
+    result: dict[str, str] = {}
+    for key, value in pairs:
+        if not isinstance(key, str) or _ENV_KEY_RE.fullmatch(key) is None:
+            raise DeploymentKitError(f"Invalid maintenance environment variable name: {key!r}")
+        if key in result:
+            raise DeploymentKitError(f"Duplicate maintenance environment variable: {key}")
+        if not isinstance(value, str) or any(ch in value for ch in ("\x00", "\n", "\r")):
+            raise DeploymentKitError(f"Maintenance environment variable {key} contains unsupported control characters.")
+        result[key] = value
+    if not result:
+        raise DeploymentKitError("At least one maintenance environment value is required.")
+    return dict(sorted(result.items()))
+
+
+def reservation_sha(*, owner_repo: str, environment: str, app_slug: str, run_as: str, database_file: str) -> str:
+    value = {
+        "schemaVersion": SQLITE_SCHEMA_VERSION,
+        "adapter": "sqlite",
+        "ownerRepo": owner_repo,
+        "environment": environment,
+        "appSlug": app_slug,
+        "runAs": run_as,
+        "databaseFile": database_file,
+    }
+    return hashlib.sha256(json.dumps(value, sort_keys=True, separators=(",", ":")).encode()).hexdigest()
+
+
+def normalize_sqlite_request(
+    *, owner_repo: str, environment: str, app_slug: str, image: str,
+    maintenance_environment: dict[str, str] | Iterable[tuple[str, str]],
+    run_as: str | None = None, database_file: str | None = None,
+    source_database: str | None = None, first_install: bool = False,
+) -> dict[str, Any]:
+    request = {
+        "ownerRepo": _owner_repo(owner_repo),
+        "environment": _slug(environment, "environment"),
+        "appSlug": _slug(app_slug, "appSlug"),
+        "image": _image(image),
+        "maintenanceEnvironment": _normalize_env(maintenance_environment),
+        "firstInstall": bool(first_install),
+        "runAs": _run_as(run_as) if run_as is not None else None,
+        "databaseFile": _database_file(database_file) if database_file is not None else None,
+        "sourceDatabase": _source_database(source_database) if source_database is not None else None,
+    }
+    if request["sourceDatabase"] is not None:
+        if request["runAs"] is None or request["databaseFile"] is None:
+            raise DeploymentKitError("SQLite import requires runAs and databaseFile.")
+        if posixpath.basename(request["sourceDatabase"]) != request["databaseFile"]:
+            raise DeploymentKitError("sourceDatabase file name must match databaseFile.")
+    if request["firstInstall"] and (request["runAs"] is None or request["databaseFile"] is None):
+        raise DeploymentKitError("First-install SQLite migration requires runAs and databaseFile.")
+    return request
+
+
+def _b64(value: str) -> str:
+    return base64.b64encode(value.encode()).decode("ascii")
+
+
+def build_remote_script(spec: dict[str, Any] | None = None) -> str:
+    spec = spec or {}
+    env = spec.get("maintenanceEnvironment", {})
+    replacements = {
+        "__APP_ROOT__": APP_ROOT,
+        "__SQLITE_SCHEMA_VERSION__": str(SQLITE_SCHEMA_VERSION),
+        "__OWNER_B64__": _b64(spec.get("ownerRepo", "")),
+        "__ENV_B64__": _b64(spec.get("environment", "")),
+        "__APP_B64__": _b64(spec.get("appSlug", "")),
+        "__IMAGE_B64__": _b64(spec.get("image", "")),
+        "__RUN_AS_B64__": _b64(spec.get("runAs") or ""),
+        "__DB_FILE_B64__": _b64(spec.get("databaseFile") or ""),
+        "__SOURCE_DB_B64__": _b64(spec.get("sourceDatabase") or ""),
+        "__FIRST_INSTALL__": "true" if spec.get("firstInstall") else "false",
+        "__RESERVATION_SHA__": spec.get("reservationSha256", ""),
+        "__ENV_KEYS__": " ".join(f"'{_b64(k)}'" for k in env),
+        "__ENV_VALUES__": " ".join(f"'{_b64(v)}'" for v in env.values()),
+    }
+    script = REMOTE_SCRIPT
+    for placeholder, value in replacements.items():
+        script = script.replace(placeholder, value)
+    if "__" in script:
+        raise DeploymentKitError("Internal SQLite adapter script contains an unresolved placeholder.")
+    return script
+
+
+def _parse_inventory(output: str) -> dict[str, Any]:
+    summary: dict[str, str] = {}
+    adapters: list[dict[str, Any]] = []
+    for raw in output.splitlines():
+        if not raw:
+            continue
+        parts = raw.split("\t")
+        if parts[0] == "SUMMARY":
+            if len(parts) != 3 or parts[1] in summary:
+                raise DeploymentKitError("Malformed or duplicate SQLite inventory summary.")
+            summary[parts[1]] = parts[2]
+            continue
+        if parts[0] != "SQLITE" or len(parts) != 12:
+            raise DeploymentKitError("Malformed SQLite inventory record.")
+        if parts[7] not in {"true", "false"} or parts[10] not in {"true", "false"}:
+            raise DeploymentKitError("Malformed SQLite inventory boolean value.")
+        try:
+            database_bytes = int(parts[8]); backup_count = int(parts[9])
+        except ValueError as error:
+            raise DeploymentKitError("Malformed SQLite inventory numeric value.") from error
+        if re.fullmatch(r"[0-9a-f]{64}", parts[6]) is None:
+            raise DeploymentKitError("Malformed SQLite reservation fingerprint.")
+        adapters.append({
+            "ownerRepo": _owner_repo(parts[1]), "environment": _slug(parts[2], "environment"),
+            "appSlug": _slug(parts[3], "appSlug"), "runAs": _run_as(parts[4]),
+            "databaseFile": _database_file(parts[5]), "reservationSha256": parts[6],
+            "databasePresent": parts[7] == "true", "databaseBytes": database_bytes,
+            "backupCount": backup_count, "managedRuntimeRunning": parts[10] == "true",
+            "currentRuntimeImage": parts[11] or None,
+        })
+    if set(summary) != {"sqliteCount"}:
+        raise DeploymentKitError("SQLite inventory omitted sqliteCount.")
+    try:
+        count = int(summary["sqliteCount"])
+    except ValueError as error:
+        raise DeploymentKitError("Malformed SQLite inventory count.") from error
+    if count != len(adapters):
+        raise DeploymentKitError("SQLite inventory count does not match records.")
+    return {"sqlite": sorted(adapters, key=lambda item: (item["appSlug"], item["environment"]))}
+
+
+def _run_remote(profile: dict[str, Any], address: str, action: str, *, spec: dict[str, Any] | None = None, expected_reservation_sha: str = "") -> str:
+    if action not in {"inventory", "import", "backup", "migrate", "rollback-check"}:
+        raise DeploymentKitError(f"Unsupported SQLite adapter action: {action}")
+    args = [action]
+    if action != "inventory":
+        args.extend([expected_reservation_sha or "NONE", profile["user"]])
+    completed = subprocess.run(
+        ssh_args(profile, address, command="sudo -n bash -s -- " + " ".join(args)),
+        input=build_remote_script(spec).encode("utf-8"), check=False, capture_output=True,
+    )
+    stdout = completed.stdout.decode("utf-8", errors="replace")
+    stderr = completed.stderr.decode("utf-8", errors="replace")
+    if completed.returncode != 0:
+        detail = stderr.strip() or stdout.strip() or f"exit {completed.returncode}"
+        raise DeploymentKitError(f"Remote SQLite adapter {action} failed: {detail}")
+    return stdout
+
+
+def sqlite_inventory(name: str) -> dict[str, Any]:
+    profile = load_profile(name); evidence = verify_access(profile)
+    result = _parse_inventory(_run_remote(profile, evidence["address"], "inventory"))
+    result.update(targetName=name, verifiedAddress=evidence["address"], mutated=False)
+    return result
+
+
+def _snapshot(inventory: dict[str, Any]) -> str:
+    return hashlib.sha256(json.dumps({"sqlite": inventory["sqlite"]}, sort_keys=True, separators=(",", ":")).encode()).hexdigest()
+
+
+def _find(inventory: dict[str, Any], app_slug: str, environment: str) -> dict[str, Any] | None:
+    return next((item for item in inventory["sqlite"] if item["appSlug"] == app_slug and item["environment"] == environment), None)
+
+
+def _require_ready_platform(name: str) -> None:
+    state = platform_status(name)["state"]
+    if state != "ready":
+        raise DeploymentKitError(f"SQLite operation requires a ready shared platform; target '{name}' is '{state}'.")
+
+
+def _reservation_from_request(request: dict[str, Any]) -> dict[str, Any]:
+    if request["runAs"] is None or request["databaseFile"] is None:
+        raise DeploymentKitError("SQLite reservation requires runAs and databaseFile.")
+    return {
+        "runAs": request["runAs"], "databaseFile": request["databaseFile"],
+        "reservationSha256": reservation_sha(owner_repo=request["ownerRepo"], environment=request["environment"], app_slug=request["appSlug"], run_as=request["runAs"], database_file=request["databaseFile"]),
+    }
+
+
+def plan_sqlite_operation(name: str, action: str, request: dict[str, Any]) -> dict[str, Any]:
+    if action not in {"import", "backup", "migrate", "rollback-check"}:
+        raise DeploymentKitError("Unsupported SQLite plan action.")
+    _require_ready_platform(name)
+    inventory = sqlite_inventory(name)
+    existing = _find(inventory, request["appSlug"], request["environment"])
+    expected_sha = existing["reservationSha256"] if existing else ""
+    if existing and existing["ownerRepo"] != request["ownerRepo"]:
+        raise DeploymentKitError("SQLite reservation ownership does not match the requested repository.")
+    spec = dict(request)
+    if action == "import":
+        if request["sourceDatabase"] is None:
+            raise DeploymentKitError("SQLite import requires sourceDatabase.")
+        if existing:
+            raise DeploymentKitError("SQLite import requires an unreserved destination.")
+        spec.update(_reservation_from_request(request))
+    elif action == "migrate" and request["firstInstall"]:
+        if existing:
+            raise DeploymentKitError("First-install SQLite migration requires an unreserved destination.")
+        spec.update(_reservation_from_request(request))
+    else:
+        if existing is None:
+            raise DeploymentKitError(f"SQLite {action} requires an existing adapter reservation.")
+        if request["runAs"] is not None and request["runAs"] != existing["runAs"]:
+            raise DeploymentKitError("Requested runAs does not match the existing SQLite reservation.")
+        if request["databaseFile"] is not None and request["databaseFile"] != existing["databaseFile"]:
+            raise DeploymentKitError("Requested databaseFile does not match the existing SQLite reservation.")
+        spec.update(runAs=existing["runAs"], databaseFile=existing["databaseFile"], reservationSha256=existing["reservationSha256"])
+        if action in {"backup", "migrate", "rollback-check"} and not existing["databasePresent"]:
+            raise DeploymentKitError(f"SQLite {action} requires an existing database.")
+    return {
+        "targetName": name, "action": action, "ownerRepo": request["ownerRepo"],
+        "environment": request["environment"], "appSlug": request["appSlug"], "image": request["image"],
+        "databaseFile": spec["databaseFile"], "runAs": spec["runAs"],
+        "sourceDatabase": request["sourceDatabase"] if action == "import" else None,
+        "firstInstall": bool(request["firstInstall"] if action == "migrate" else False),
+        "stopsManagedRuntime": bool(action == "migrate" and existing and existing["managedRuntimeRunning"]),
+        "createsVerifiedBackup": bool(action == "backup" or (action == "migrate" and not request["firstInstall"])),
+        "inventorySnapshot": _snapshot(inventory), "expectedReservationSha256": expected_sha, "spec": spec,
+    }
+
+
+def authorization_phrase(plan: dict[str, Any]) -> str:
+    production = plan["environment"] == "production"
+    mapping = {
+        "import": (SQLITE_IMPORT_WRITE_PHRASE, PRODUCTION_SQLITE_IMPORT_WRITE_PHRASE),
+        "backup": (SQLITE_BACKUP_WRITE_PHRASE, PRODUCTION_SQLITE_BACKUP_WRITE_PHRASE),
+        "migrate": (SQLITE_MIGRATE_WRITE_PHRASE, PRODUCTION_SQLITE_MIGRATE_WRITE_PHRASE),
+        "rollback-check": (SQLITE_ROLLBACK_CHECK_PHRASE, PRODUCTION_SQLITE_ROLLBACK_CHECK_PHRASE),
+    }
+    normal, prod = mapping[plan["action"]]
+    return prod if production else normal
+
+
+def apply_sqlite_operation(plan: dict[str, Any]) -> dict[str, Any]:
+    required = {"targetName", "action", "ownerRepo", "environment", "appSlug", "image", "databaseFile", "runAs", "sourceDatabase", "firstInstall", "stopsManagedRuntime", "createsVerifiedBackup", "inventorySnapshot", "expectedReservationSha256", "spec"}
+    if not isinstance(plan, dict) or set(plan) != required:
+        raise DeploymentKitError("Malformed SQLite operation plan.")
+    _require_ready_platform(plan["targetName"])
+    current = sqlite_inventory(plan["targetName"])
+    if _snapshot(current) != plan["inventorySnapshot"]:
+        raise DeploymentKitError("SQLite state changed after the plan was reviewed; create and authorize a fresh plan.")
+    profile = load_profile(plan["targetName"]); evidence = verify_access(profile)
+    output = _run_remote(profile, evidence["address"], plan["action"], spec=plan["spec"], expected_reservation_sha=plan["expectedReservationSha256"])
+    result = sqlite_inventory(plan["targetName"])
+    result["mutated"] = True
+    result["operation"] = plan["action"]; result["operationOutput"] = output.strip()
+    return result
+
+
+def assert_app_spec_matches_persistence(name: str, app_spec: dict[str, Any]) -> None:
+    inventory = sqlite_inventory(name)
+    existing = _find(inventory, app_spec["appSlug"], app_spec["environment"])
+    if existing is None:
+        return
+    if existing["ownerRepo"] != app_spec["ownerRepo"]:
+        raise DeploymentKitError("Prepared SQLite persistence belongs to a different repository.")
+    if existing["runAs"] != app_spec["runAs"]:
+        raise DeploymentKitError("Application runAs does not match the prepared SQLite persistence reservation.")
+    if app_spec.get("persistence", {}).get("mode") != "directory":
+        raise DeploymentKitError("Prepared SQLite persistence requires directory application persistence.")