@mriekki/project-forge 4.16.0 → 4.17.0

package/assets/components.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 2,
   "package": "@mriekki/project-forge",
-  "version": "4.16.0",
+  "version": "4.17.0",
   "defaultProfile": "greenfield-project",
   "profiles": {
     "greenfield-project": {
@@ -21,7 +21,7 @@
       "canonicalDescriptor": "distributions/greenfield-workspace.json"
     },
     "deployment": {
-      "revision": "f5325556e1ee1e256e3dfb426d91feb42cbdc2c3",
+      "revision": "f5f82c531da03f113209a795930db8444338c69e",
       "distribution": "greenfield-project",
       "descriptor": "assets/deployment/distribution.json",
       "sourceRoot": "assets/generated/deployment",

package/assets/deployment/distribution.json

@@ -33,6 +33,7 @@
     {"source": "src/project_forge_deployment/ingress_cli.py", "destination": "tools/project-forge-deployment/project_forge_deployment/ingress_cli.py"},
     {"source": "src/project_forge_deployment/keys.py", "destination": "tools/project-forge-deployment/project_forge_deployment/keys.py"},
     {"source": "src/project_forge_deployment/local_cli.py", "destination": "tools/project-forge-deployment/project_forge_deployment/local_cli.py"},
+    {"source": "src/project_forge_deployment/local_extensions.py", "destination": "tools/project-forge-deployment/project_forge_deployment/local_extensions.py"},
     {"source": "src/project_forge_deployment/local_runtime.py", "destination": "tools/project-forge-deployment/project_forge_deployment/local_runtime.py"},
     {"source": "src/project_forge_deployment/local_spec.py", "destination": "tools/project-forge-deployment/project_forge_deployment/local_spec.py"},
     {"source": "src/project_forge_deployment/local_sqlite.py", "destination": "tools/project-forge-deployment/project_forge_deployment/local_sqlite.py"},

package/assets/generated/ASSEMBLY.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 2,
   "package": "@mriekki/project-forge",
-  "version": "4.16.0",
+  "version": "4.17.0",
   "components": {
     "core": {
       "revision": "4c74c1801b82d3aa438447d392024d32ca5697b0",
@@ -361,7 +361,7 @@
       ]
     },
     "deployment": {
-      "revision": "f5325556e1ee1e256e3dfb426d91feb42cbdc2c3",
+      "revision": "f5f82c531da03f113209a795930db8444338c69e",
       "distribution": "greenfield-project",
       "files": [
         {
@@ -514,6 +514,11 @@
           "destination": "tools/project-forge-deployment/project_forge_deployment/local_cli.py",
           "sha256": "b0b99dc66a95a5f9cb386a15d7a32f3f935bf37be2cf06175ceb9cc2c9a479cd"
         },
+        {
+          "source": "src/project_forge_deployment/local_extensions.py",
+          "destination": "tools/project-forge-deployment/project_forge_deployment/local_extensions.py",
+          "sha256": "cf90ef1fc122c6626b7f53d8e9b1eb88c97f7f8106d248e5b04f25263184ca93"
+        },
         {
           "source": "src/project_forge_deployment/local_runtime.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/local_runtime.py",
@@ -592,12 +597,12 @@
         {
           "source": "src/project_forge_deployment/sqlite_adapter.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/sqlite_adapter.py",
-          "sha256": "ab0fe2a1009ac1883ee7c9344c84240051648ccd1f05df9166cd81f6a216f893"
+          "sha256": "781219312cb81ffb901dff8b8d04d0cf0511b5d37e86f9ad9024a73cba04d3b9"
         },
         {
           "source": "src/project_forge_deployment/sqlite_adapter_remote.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/sqlite_adapter_remote.py",
-          "sha256": "6c7ba2c49f8ae97a28927f694df23b7f18de1247aac4bc4dce858859fb2199ed"
+          "sha256": "32c319453add977de4e051ca9cadbffaa411adb26713c4a8731553d0d2d4adaf"
         },
         {
           "source": "src/project_forge_deployment/sqlite_cli.py",

package/assets/generated/deployment/src/project_forge_deployment/local_extensions.py

@@ -0,0 +1,123 @@
+"""Optional, loopback-only workstation bindings and scoped read-only material mounts.
+
+No material is provisioned by the Kit. Source directories belong to the Project
+and must already exist below its dedicated local-materials root.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import stat
+from pathlib import Path
+from typing import Any
+
+from .errors import DeploymentKitError
+from .profiles import config_root
+
+MATERIAL_TARGET_ROOT = "/run/project-forge/material"
+_SAFE_NAME = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.-]*$")
+MAX_ADDITIONAL_PORTS = 8
+
+
+def material_root(app_slug: str, environment: str) -> Path:
+    return config_root() / "local-materials" / app_slug / environment
+
+
+def bindings(spec: dict[str, Any]) -> list[dict[str, int]]:
+    return [{"hostPort": spec["hostPort"], "runtimePort": spec["runtimePort"]}, *spec.get("additionalPortBindings", [])]
+
+
+def normalize_bindings(primary_host: int, primary_runtime: int, values: object) -> list[dict[str, int]]:
+    if not isinstance(values, (list, tuple)) or len(values) > MAX_ADDITIONAL_PORTS:
+        raise DeploymentKitError("additionalPortBindings must be a list of at most eight TCP mappings.")
+    result = []
+    host_ports = {primary_host}
+    runtime_ports = {primary_runtime}
+    for item in values:
+        if not isinstance(item, dict) or set(item) != {"hostPort", "runtimePort"}:
+            raise DeploymentKitError("Additional port mapping requires hostPort and runtimePort.")
+        host, runtime = item["hostPort"], item["runtimePort"]
+        if any(type(port) is not int or not 1 <= port <= 65535 for port in (host, runtime)):
+            raise DeploymentKitError("Additional TCP ports must be integers from 1 through 65535.")
+        if host in host_ports or runtime in runtime_ports:
+            raise DeploymentKitError("All host ports and container runtime ports must be distinct.")
+        host_ports.add(host)
+        runtime_ports.add(runtime)
+        result.append({"hostPort": host, "runtimePort": runtime})
+    return sorted(result, key=lambda item: (item["hostPort"], item["runtimePort"]))
+
+
+def _absolute_path(value: object, field: str) -> Path:
+    if not isinstance(value, str) or not value or any(ch in value for ch in ("\x00", "\n", "\r", ",")):
+        raise DeploymentKitError(f"{field} must be a safe absolute path.")
+    value = value.replace("\\", "/") if os.name == "nt" else value
+    path = Path(value)
+    if not path.is_absolute() or any(part in (".", "..") for part in value.replace("\\", "/").split("/")):
+        raise DeploymentKitError(f"{field} must be an absolute path without traversal.")
+    return path
+
+
+def _no_symlink_components(path: Path) -> None:
+    for entry in (path, *path.parents):
+        if entry.is_symlink():
+            raise DeploymentKitError("External material paths cannot contain symbolic links.")
+
+
+def normalize_mounts(app_slug: str, environment: str, values: object, data_target: str | None) -> list[dict[str, str]]:
+    if not isinstance(values, (list, tuple)):
+        raise DeploymentKitError("readOnlyMounts must be a list.")
+    root = material_root(app_slug, environment)
+    result: list[dict[str, str]] = []
+    for item in values:
+        if not isinstance(item, dict) or set(item) != {"source", "target"}:
+            raise DeploymentKitError("readOnlyMounts entries require source and target.")
+        source = _absolute_path(item["source"], "material source")
+        _no_symlink_components(source)
+        try:
+            relative = source.relative_to(root)
+        except ValueError as error:
+            raise DeploymentKitError("Material source must be beneath the Project-scoped local-materials root.") from error
+        if not relative.parts or relative == Path("."):
+            raise DeploymentKitError("Mount a named material directory, not the Project-scoped root.")
+        target = item["target"]
+        if not isinstance(target, str) or not target.startswith(MATERIAL_TARGET_ROOT + "/"):
+            raise DeploymentKitError("Material targets must be under /run/project-forge/material/.")
+        parts = target[len(MATERIAL_TARGET_ROOT) + 1:].split("/")
+        if not all(_SAFE_NAME.fullmatch(part) and part not in {".", ".."} for part in parts):
+            raise DeploymentKitError("Material target must use safe nonempty path segments.")
+        target = MATERIAL_TARGET_ROOT + "/" + "/".join(parts)
+        if data_target and (target == data_target or target.startswith(data_target.rstrip("/") + "/") or data_target.startswith(target + "/")):
+            raise DeploymentKitError("Material target overlaps managed persistence.")
+        result.append({"source": str(source), "target": target})
+    for i, first in enumerate(result):
+        for second in result[i+1:]:
+            if any(a == b or a.startswith(b.rstrip("/") + "/") or b.startswith(a.rstrip("/") + "/")
+                   for a, b in ((first["target"], second["target"]), (first["source"], second["source"]))):
+                raise DeploymentKitError("Read-only material sources and targets cannot overlap.")
+    return sorted(result, key=lambda item: (item["target"], item["source"]))
+
+
+def snapshot_material(spec: dict[str, Any]) -> str | None:
+    """Non-secret metadata snapshot; detects many, but not all, concurrent changes."""
+    mounts = spec.get("readOnlyMounts", [])
+    if not mounts:
+        return None
+    entries: list[object] = []
+    for mount in mounts:
+        source = Path(mount["source"])
+        _no_symlink_components(source)
+        if not source.is_dir():
+            raise DeploymentKitError("External material source directory is missing.")
+        for path in [source, *sorted(source.rglob("*"))]:
+            _no_symlink_components(path)
+            try:
+                info = path.lstat()
+            except OSError as error:
+                raise DeploymentKitError("Cannot inspect external material source.") from error
+            if not (stat.S_ISDIR(info.st_mode) or stat.S_ISREG(info.st_mode)):
+                raise DeploymentKitError("Material directories may contain only regular files and directories.")
+            entries.append((mount["source"], str(path.relative_to(source)), info.st_dev, info.st_ino,
+                            info.st_mode, info.st_size, info.st_mtime_ns, info.st_ctime_ns))
+    return hashlib.sha256(json.dumps(entries, separators=(",", ":")).encode("utf-8")).hexdigest()

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

@@ -7,6 +7,7 @@ import hashlib
 import json
 import posixpath
 import re
+import shlex
 import subprocess
 from typing import Any, Iterable
 
@@ -332,7 +333,7 @@ def authorization_phrase(plan: dict[str, Any]) -> str:
     return prod if production else normal
 
 
-def apply_sqlite_operation(plan: dict[str, Any]) -> dict[str, Any]:
+def _validate_sqlite_plan(plan: dict[str, Any]) -> None:
     required = {
         "targetName", "action", "ownerRepo", "environment", "productionClassified", "appSlug", "image",
         "databaseFile", "runAs", "sourceDatabase", "firstInstall", "stopsManagedRuntime", "createsVerifiedBackup",
@@ -345,6 +346,10 @@ def apply_sqlite_operation(plan: dict[str, Any]) -> dict[str, Any]:
         raise DeploymentKitError("Literal production environment must remain Production-classified.")
     if plan["applicationRecoveryReadyAfterOperation"] is not False:
         raise DeploymentKitError("SQLite operations cannot claim application recovery readiness.")
+
+
+def apply_sqlite_operation(plan: dict[str, Any]) -> dict[str, Any]:
+    _validate_sqlite_plan(plan)
     _require_ready_platform(plan["targetName"])
     current = sqlite_inventory(plan["targetName"])
     if _snapshot(current) != plan["inventorySnapshot"]:
@@ -373,3 +378,46 @@ def assert_app_spec_matches_persistence(name: str, app_spec: dict[str, Any]) ->
         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.")
+
+
+def render_locked_sqlite_operation_stage(
+    plan: dict[str, Any], *, inherited_lock_fd: int, authorization: str,
+) -> dict[str, str]:
+    """Render a Kit-validated SQLite stage for an existing privileged remote lock scope.
+
+    This returns a Bash *stage*, not an SSH command and not an authorization to
+    run it. The caller must have obtained an exclusive non-blocking flock on
+    this exact app/environment lock in the SAME remote root shell; the Kit
+    verifies that inherited open file description before touching storage.
+
+    The caller retains the descriptor across its full-backup/current-storage
+    comparison, Kit migration, optional Kit rollback-check, and its durable
+    application-specific receipt write. Do not execute this stage via a fresh
+    SSH/sudo connection: the inherited descriptor cannot cross that boundary.
+    """
+    _validate_sqlite_plan(plan)
+    if plan["action"] not in {"migrate", "rollback-check"} or plan["firstInstall"]:
+        raise DeploymentKitError("Lock handoff is limited to existing-database migration and rollback-check.")
+    if type(inherited_lock_fd) is not int or not 3 <= inherited_lock_fd <= 256:
+        raise DeploymentKitError("Inherited remote lock descriptor must be an integer between 3 and 256.")
+    if authorization != authorization_phrase(plan):
+        raise DeploymentKitError("Exact reviewed SQLite operation authorization phrase is required.")
+
+    _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)
+    script = build_remote_script(plan["spec"])
+    delimiter = "PROJECT_FORGE_SQLITE_STAGE_" + hashlib.sha256(script.encode()).hexdigest()[:24]
+    if delimiter in script:
+        raise DeploymentKitError("Unsafe SQLite script delimiter collision.")
+    args = [plan["action"], plan["expectedReservationSha256"] or "NONE", profile["user"], str(inherited_lock_fd)]
+    command = "bash -s -- " + " ".join(shlex.quote(arg) for arg in args)
+    return {
+        "targetName": plan["targetName"],
+        "verifiedAddress": evidence["address"],
+        "action": plan["action"],
+        "script": f"{command} <<'{delimiter}'\n{script.rstrip()}\n{delimiter}\n",
+    }

package/assets/generated/deployment/src/project_forge_deployment/sqlite_adapter_remote.py

@@ -6,6 +6,9 @@ set -Eeuo pipefail
 ACTION="$1"
 EXPECTED_RESERVATION_SHA="${2:-}"
 DEPLOY_USER="${3:-}"
+# Optional Kit-verified handoff from an already-locked privileged remote session.
+# This is a remote file descriptor, not a workstation/SSH descriptor.
+HELD_LOCK_FD="${4:-}"
 APP_ROOT="__APP_ROOT__"
 SQLITE_SCHEMA_VERSION="__SQLITE_SCHEMA_VERSION__"
 OWNER_B64="__OWNER_B64__"
@@ -253,12 +256,52 @@ verify_reserved_dirs() {
     }
 }
 
+acquire_operation_lock() {
+    if [[ -z "$HELD_LOCK_FD" ]]; then
+        exec 9>>"$LOCK_FILE"
+        flock -n 9 || { echo "Another app/persistence operation holds the lock for $APP_SLUG--$ENVIRONMENT." >&2; exit 75; }
+        return 0
+    fi
+
+    # Never convert an untrusted flag into permission to skip the lock.
+    # Inherited lock sharing is limited to existing-reservation migration and
+    # compatibility verification; other mutations retain their own lock.
+    [[ "$ACTION" == migrate || "$ACTION" == rollback-check ]] && [[ "$FIRST_INSTALL" == false ]] || {
+        echo "An inherited lock is not supported for this SQLite action." >&2; exit 75;
+    }
+    [[ "$HELD_LOCK_FD" =~ ^[0-9]+$ ]] && (( 10#$HELD_LOCK_FD >= 3 && 10#$HELD_LOCK_FD <= 256 )) || {
+        echo "Inherited SQLite lock descriptor is invalid." >&2; exit 75;
+    }
+    [[ -f "$LOCK_FILE" && ! -L "$LOCK_FILE" ]] || {
+        echo "Inherited SQLite lock path is invalid." >&2; exit 75;
+    }
+    local inherited_inode expected_inode probe_fd
+    inherited_inode="$(stat -Lc '%d:%i' "/proc/self/fd/$HELD_LOCK_FD" 2>/dev/null || true)"
+    expected_inode="$(stat -Lc '%d:%i' "$LOCK_FILE" 2>/dev/null || true)"
+    [[ -n "$inherited_inode" && "$inherited_inode" == "$expected_inode" ]] || {
+        echo "Inherited SQLite lock descriptor does not match this app/environment." >&2; exit 75;
+    }
+    # Independent open descriptions must contend: prove the caller ALREADY
+    # holds the lock, not merely that it passed an unlocked file descriptor.
+    exec {probe_fd}>>"$LOCK_FILE"
+    if flock -n "$probe_fd"; then
+        flock -u "$probe_fd"
+        exec {probe_fd}>&-
+        echo "Inherited SQLite lock was not held before this operation." >&2; exit 75
+    fi
+    exec {probe_fd}>&-
+    # A successful flock on this inherited open description proves ownership,
+    # rather than unrelated contention on a different descriptor.
+    flock -n "$HELD_LOCK_FD" || {
+        echo "Inherited SQLite lock is owned by another operation." >&2; exit 75;
+    }
+}
+
 operate() {
     decode_spec
     configure_registry_auth
     set_paths
-    exec 9>>"$LOCK_FILE"
-    flock -n 9 || { echo "Another app/persistence operation holds the lock for $APP_SLUG--$ENVIRONMENT." >&2; exit 75; }
+    acquire_operation_lock
 
     local db="$DATA/$DATABASE_FILE" stamp backup_name source_real source_parent
     managed_runtime_info "$ROOT"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mriekki/project-forge",
-  "version": "4.16.0",
+  "version": "4.17.0",
   "description": "Public consumer distribution and updater for Project Forge engineering assets.",
   "type": "module",
   "bin": {