@mriekki/project-forge 4.16.1 → 4.18.0

package/assets/components.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 2,
   "package": "@mriekki/project-forge",
-  "version": "4.16.1",
+  "version": "4.18.0",
   "defaultProfile": "greenfield-project",
   "profiles": {
     "greenfield-project": {
@@ -21,7 +21,7 @@
       "canonicalDescriptor": "distributions/greenfield-workspace.json"
     },
     "deployment": {
-      "revision": "6da5b1591bf483cedc9c4b2b5fecfd5613d836f6",
+      "revision": "31985f3e24a3832391cfe873fbb3eab27d0fa9d4",
       "distribution": "greenfield-project",
       "descriptor": "assets/deployment/distribution.json",
       "sourceRoot": "assets/generated/deployment",

package/assets/generated/ASSEMBLY.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 2,
   "package": "@mriekki/project-forge",
-  "version": "4.16.1",
+  "version": "4.18.0",
   "components": {
     "core": {
       "revision": "4c74c1801b82d3aa438447d392024d32ca5697b0",
@@ -361,7 +361,7 @@
       ]
     },
     "deployment": {
-      "revision": "6da5b1591bf483cedc9c4b2b5fecfd5613d836f6",
+      "revision": "31985f3e24a3832391cfe873fbb3eab27d0fa9d4",
       "distribution": "greenfield-project",
       "files": [
         {
@@ -397,17 +397,17 @@
         {
           "source": "src/project_forge_deployment/app_deployment.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/app_deployment.py",
-          "sha256": "606d6a4793ac8c8a95da4cd4c61792c69f02ad86900be1944d2ed570dd71e73e"
+          "sha256": "aeecda05bd2f71276dd49f09fd599cf529ea9fe9b0aae7c1e26ab92bd57e7f22"
         },
         {
           "source": "src/project_forge_deployment/app_runtime.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/app_runtime.py",
-          "sha256": "5f7c6fdd2e84d1f239ceae605018b3c7b8a911aac442241b000333ffadf1fdeb"
+          "sha256": "73736aada7c3db0e2a7c74a3e88990316b89e6c34a71b4997cdc4c79c7e31708"
         },
         {
           "source": "src/project_forge_deployment/app_runtime_remote.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/app_runtime_remote.py",
-          "sha256": "f86defc9a0841deee40198c7acc3b25a093e514000f0bd08030cbb253f3fa6ee"
+          "sha256": "791cc7592cff93555f7b6facdd31fbe58de5e711732d9dfcb9321500a0d79cdf"
         },
         {
           "source": "src/project_forge_deployment/app_runtime_workstation.py",
@@ -597,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": "d60239f9b75cf688531319284f0123488f4f0ae812ac9982ce611320d8754793"
         },
         {
           "source": "src/project_forge_deployment/sqlite_cli.py",

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

@@ -14,6 +14,7 @@ from .app_runtime import PRODUCTION_APP_DEPLOY_WRITE_PHRASE
 from .app_runtime import apply_app_deploy as _apply_runtime_deploy
 from .app_runtime import deploy_write_phrase
 from .app_runtime import plan_app_deploy as _plan_runtime_deploy
+from .app_runtime import render_locked_app_deploy_stage as _render_locked_runtime_deploy_stage
 from .app_runtime_workstation import apply_app_deploy_with_preloaded_image
 from .environment_isolation import environment_isolation_preflight
 from .errors import DeploymentKitError
@@ -272,6 +273,30 @@ def apply_app_deploy(plan: dict[str, Any]) -> dict[str, Any]:
     return _apply_runtime_deploy(_runtime_plan(plan))
 
 
+def render_locked_app_deploy_stage(
+    plan: dict[str, Any], *, inherited_lock_fd: int, authorization: str,
+) -> dict[str, str]:
+    """Render a registry-backed deploy stage after isolation revalidation."""
+
+    runtime_plan = _runtime_plan(plan)
+    review = plan[ISOLATION_REVIEW_KEY]
+    if not isinstance(review, dict) or type(review.get("production")) is not bool:
+        raise DeploymentKitError("Application deployment plan has malformed Production classification.")
+    production = review["production"] or runtime_plan["environment"] == "production"
+    expected_authorization = (
+        PRODUCTION_APP_DEPLOY_WRITE_PHRASE if production else deploy_write_phrase(runtime_plan)
+    )
+    if authorization != expected_authorization:
+        raise DeploymentKitError("Exact reviewed application deployment authorization phrase is required.")
+    revalidate_app_isolation(plan)
+    return _render_locked_runtime_deploy_stage(
+        runtime_plan,
+        inherited_lock_fd=inherited_lock_fd,
+        authorization=authorization,
+        production=production,
+    )
+
+
 def apply_app_deploy_from_workstation(plan: dict[str, Any]) -> dict[str, Any]:
     """Transfer an exact image, then recheck isolation again before runtime mutation."""
 
@@ -291,4 +316,5 @@ __all__ = [
     "plan_app_deploy",
     "plan_app_rollout",
     "revalidate_app_isolation",
+    "render_locked_app_deploy_stage",
 ]

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

@@ -6,6 +6,7 @@ import base64
 import hashlib
 import json
 import re
+import shlex
 import subprocess
 from typing import Any, Iterable
 
@@ -394,6 +395,82 @@ def deploy_write_phrase(plan: dict[str, Any]) -> str:
     )
 
 
+def render_locked_app_deploy_stage(
+    plan: dict[str, Any], *, inherited_lock_fd: int, authorization: str, production: bool = False,
+) -> dict[str, str]:
+    """Render a Kit-validated deployment stage for an existing remote lock scope.
+
+    The returned Bash stage is not an SSH command or authorization to run it.
+    The caller must hold the exact app/environment lock in the same privileged
+    remote shell and keep it through its application-specific checks and this
+    stage. The remote script verifies the inherited descriptor before deploy.
+    """
+    required = {
+        "targetName",
+        "action",
+        "environment",
+        "appSlug",
+        "ownerRepo",
+        "containerName",
+        "image",
+        "runtimePort",
+        "healthPath",
+        "persistenceMode",
+        "changeType",
+        "previousImage",
+        "previousRelease",
+        "retainsPreviousRelease",
+        "publishesHostPort",
+        "attachesSharedNetwork",
+        "modifiesRoutes",
+        "persistentDataDeletion",
+        "inventorySnapshot",
+        "expectedSpecSha256",
+        "spec",
+    }
+    if not isinstance(plan, dict) or set(plan) != required or plan["action"] != "deploy":
+        raise DeploymentKitError("Malformed application deployment plan.")
+    if (plan["changeType"] != "update" or plan["retainsPreviousRelease"] is not True
+            or not isinstance(plan["expectedSpecSha256"], str)
+            or re.fullmatch(r"[0-9a-f]{64}", plan["expectedSpecSha256"]) is None):
+        raise DeploymentKitError("Lock handoff is limited to an existing application deployment update.")
+    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 type(production) is not bool:
+        raise DeploymentKitError("Production classification must be a boolean.")
+    expected_authorization = (
+        PRODUCTION_APP_DEPLOY_WRITE_PHRASE
+        if production or plan["environment"] == "production"
+        else APP_DEPLOY_WRITE_PHRASE
+    )
+    if authorization != expected_authorization:
+        raise DeploymentKitError("Exact reviewed application deployment authorization phrase is required.")
+
+    platform = platform_status(plan["targetName"])
+    if platform["state"] != "ready":
+        raise DeploymentKitError("Shared host platform is no longer ready; application deployment is blocked.")
+    current = app_inventory(plan["targetName"])
+    if _inventory_snapshot(current) != plan["inventorySnapshot"]:
+        raise DeploymentKitError(
+            "Application inventory 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_APP_DEPLOY_STAGE_" + hashlib.sha256(script.encode()).hexdigest()[:24]
+    if delimiter in script:
+        raise DeploymentKitError("Unsafe application deployment script delimiter collision.")
+    command = "bash -s -- " + shlex.join([
+        "deploy", plan["expectedSpecSha256"], profile["user"], str(inherited_lock_fd),
+    ])
+    return {
+        "targetName": plan["targetName"],
+        "verifiedAddress": evidence["address"],
+        "action": "deploy",
+        "script": f"{command} <<'{delimiter}'\n{script.rstrip()}\n{delimiter}\n",
+    }
+
+
 def apply_app_deploy(plan: dict[str, Any]) -> dict[str, Any]:
     required = {
         "targetName",

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

@@ -6,6 +6,7 @@ set -Eeuo pipefail
 ACTION="$1"
 EXPECTED_SPEC_SHA="${2:-}"
 DEPLOY_USER="${3:-}"
+HELD_LOCK_FD="${4:-}"
 APP_ROOT="__APP_ROOT__"
 APP_SCHEMA_VERSION="__APP_SCHEMA_VERSION__"
 NETWORK_NAME="__NETWORK_NAME__"
@@ -284,6 +285,43 @@ record_evidence() {
     chmod 0600 "$root/deployment-evidence.jsonl"
 }
 
+acquire_deployment_lock() {
+    local lock_file="$1"
+    if [[ -z "$HELD_LOCK_FD" ]]; then
+        exec 9>>"$lock_file"
+        flock -n 9 || {
+            echo "Another application deployment holds the lock for $D_APP--$D_ENV." >&2
+            exit 75
+        }
+        return 0
+    fi
+
+    [[ "$ACTION" == "deploy" && "$EXPECTED_SPEC_SHA" =~ ^[0-9a-f]{64}$ ]] || {
+        echo "An inherited lock is supported only for existing application deployments." >&2
+        exit 75
+    }
+    [[ "$HELD_LOCK_FD" =~ ^[0-9]+$ ]] && (( 10#$HELD_LOCK_FD >= 3 && 10#$HELD_LOCK_FD <= 256 )) || {
+        echo "Inherited application lock descriptor is invalid." >&2
+        exit 75
+    }
+    [[ -f "$lock_file" && ! -L "$lock_file" ]] || {
+        echo "Inherited application lock path is invalid." >&2
+        exit 75
+    }
+    local inherited_inode expected_inode
+    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 application lock descriptor does not match this app/environment." >&2
+        exit 75
+    }
+    grep -Eq '^lock:[[:space:]]+[0-9]+:[[:space:]]+FLOCK[[:space:]]+ADVISORY[[:space:]]+WRITE([[:space:]]|$)' \
+        "/proc/self/fdinfo/$HELD_LOCK_FD" || {
+        echo "Inherited application lock was not held by this descriptor." >&2
+        exit 75
+    }
+}
+
 deploy() {
     platform_ready || { echo "Kit shared platform is not ready." >&2; exit 34; }
     decode_desired
@@ -300,11 +338,7 @@ deploy() {
     release_dir="$releases/$release_id"
     release_file="$release_dir/release.env"
 
-    exec 9>>"$lock_file"
-    if ! flock -n 9; then
-        echo "Another application deployment holds the lock for $D_APP--$D_ENV." >&2
-        exit 75
-    fi
+    acquire_deployment_lock "$lock_file"
 
     for path in "$root" "$releases" "$state" "$root/data" "$root/deployment-evidence.jsonl"; do
         [[ ! -L "$path" ]] || { echo "Managed application path must not be a symbolic link: $path" >&2; exit 35; }

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,42 @@ 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
+    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;
+    }
+    grep -Eq '^lock:[[:space:]]+[0-9]+:[[:space:]]+FLOCK[[:space:]]+ADVISORY[[:space:]]+WRITE([[:space:]]|$)' \
+        "/proc/self/fdinfo/$HELD_LOCK_FD" || {
+        echo "Inherited SQLite lock was not held by this descriptor." >&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.1",
+  "version": "4.18.0",
   "description": "Public consumer distribution and updater for Project Forge engineering assets.",
   "type": "module",
   "bin": {