@supacloud/admin 0.15.5 → 0.16.1

package/README.md

@@ -100,6 +100,7 @@ npx @supacloud/admin status
 npx @supacloud/admin ssh ping
 npx @supacloud/admin ssh versions
 npx @supacloud/admin ssh diagnose
+npx @supacloud/admin ssh upgrade_status --transaction_id 11111111-1111-4111-8111-111111111111
 npx @supacloud/admin project create --name my-app --domain example.com \
   --env_file /secure/path/.env.project-credentials.test --environment test
 npx @supacloud/admin project list
@@ -193,6 +194,33 @@ remote transaction as failed. The CLI reports the unit, stage, status, log, and
 upload-drop paths for reconciliation. Inspect that evidence before retrying and
 do not retry blindly while the remote transaction may still be running.
 
+When observation ends after 30 minutes, or to safely reconcile a retained
+local-artifact upgrade transaction, use the read-only `ssh upgrade_status`
+command:
+
+```bash
+npx @supacloud/admin ssh upgrade_status \
+  --transaction_id 11111111-1111-4111-8111-111111111111
+```
+
+`ssh upgrade_status` is classified as a read-only command and is permitted in
+read-only mode (`SUPACLOUD_READ_ONLY=true`). It requires a strict UUID v4
+transaction ID before performing any SSH access. It never deletes status, log,
+stage, or upload-drop records, and never mutates service state. The command emits
+a strict JSON projection (`supacloud.admin.upgrade-status.v1`) containing the
+normalized transaction ID, lifecycle state (`running`, `succeeded`, or
+`failed`), raw bounded status, systemd active/load states, boolean
+evidence-presence flags, and validated structured receipts:
+- Nonterminal (`running`): no receipts or failure evidence are included.
+- Succeeded: path-free projections of the validated control-plane preflight and
+  transaction safety receipts.
+- Failed: validated failure evidence with credentials and remote paths redacted.
+
+The command fails closed for missing or inconsistent terminal evidence, stopped
+nonterminal units, malformed or missing structured receipts, redacted or
+truncated SSH output, or unknown status, without emitting raw logs, remote
+filesystem paths, secrets, bearer material, env values, or customer data.
+
 `--artifact_transport local` accepts only `--github_proxy direct` or `none` and
 clears proxy environment variables on both hosts. The server-download path
 remains available as `--artifact_transport remote`; it verifies and executes

package/dist/index.js

@@ -25902,7 +25902,8 @@ var ACTION_POLICY = {
       "container_logs",
       "tenant_list",
       "tenant_inspect",
-      "tenant_diagnose"
+      "tenant_diagnose",
+      "upgrade_status"
     ],
     write: ["setup", "install", "upgrade", "tenant_migrate"]
   }
@@ -27393,6 +27394,34 @@ var UPGRADE_OBSERVATION_TIMEOUT_MS = 30 * 60000;
 
 class RemoteUpgradeReconciliationError extends AggregateError {
 }
+var UUID_V4_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+function assertValidTransactionId(transactionId) {
+  if (typeof transactionId !== "string" || !UUID_V4_PATTERN.test(transactionId)) {
+    throw new Error("Invalid 'transaction_id': must be a valid UUID v4");
+  }
+  return transactionId.toLowerCase();
+}
+function upgradeStatusControlPlaneEvidence(receipt) {
+  return {
+    backup_id: receipt.backup_id,
+    bytes: receipt.bytes,
+    candidate_counts: { ...receipt.candidate_counts },
+    completed_at: receipt.completed_at,
+    current_key_checkpoint_present: receipt.current_key_checkpoint_present,
+    receipt_schema: receipt.schema,
+    sha256: receipt.sha256
+  };
+}
+function redactRemotePaths(message) {
+  return message.replace(/\bhttps?:\/\/[^\s"'`,;)\]}]+/gi, "[REDACTED_URL]").replace(/\bfile:\/\/\/[^\s"'`,;)\]}]+/gi, "[REDACTED_PATH]").replace(/(^|[^A-Za-z0-9:/])\/(?!\/)[^\s"'`,;)\]}]+/g, "$1[REDACTED_PATH]");
+}
+function upgradeStatusFailureEvidence(receipt) {
+  return {
+    causes: receipt.causes.map(redactRemotePaths),
+    receipt_schema: receipt.schema,
+    summary: redactRemotePaths(receipt.summary)
+  };
+}
 function exactObjectKeys(candidate, expected) {
   const actual = Object.keys(candidate).sort();
   return actual.length === expected.length && actual.every((key, index) => key === [...expected].sort()[index]);
@@ -27704,6 +27733,16 @@ function shellArray(name, entries) {
 }
 function finishUpgradeFunction() {
   return [
+    "emit_wrapper_failure_receipt() {",
+    "  local code=$1 target_phase=${2:-${UPGRADE_PHASE:-}} phase",
+    `  if [ -n "\${LOG:-}" ] && ! grep -q '^SUPACLOUD_UPGRADE_FAILURE=' "$LOG" 2>/dev/null; then`,
+    '    case "$target_phase" in',
+    '      bootstrap|filesystem_checks|transfer_verification|verifier_setup|runner_preflight|runner_upgrade|cleanup|status_publish) phase="$target_phase" ;;',
+    '      *) phase="unknown" ;;',
+    "    esac",
+    `    printf 'SUPACLOUD_UPGRADE_FAILURE={"causes":["exit_code=%s","phase=%s"],"schema":"supacloud.upgrade-failure.v1","summary":"Remote upgrade execution failed during %s (exit code %s)"}\\n' "$code" "$phase" "$phase" "$code" >> "$LOG" || true`,
+    "  fi",
+    "}",
     "finish_upgrade() {",
     "  local code=$?",
     "  trap '' HUP INT TERM",
@@ -27711,15 +27750,27 @@ function finishUpgradeFunction() {
     "  set +e",
     '  if [ "$code" -ne 0 ]; then',
     '    write_status "FAILED:${code}:TRANSACTION" || true',
+    '    emit_wrapper_failure_receipt "$code"',
     '    if ! rm -rf -- "$STAGE"; then write_status "FAILED:${code}:TRANSACTION_AND_CLEANUP" || true; fi',
     '    exit "$code"',
     "  fi",
-    "  write_status CLEANING || { echo 'Unable to publish cleanup state' >&2; exit 1; }",
+    "  if ! write_status CLEANING; then",
+    "    echo 'Unable to publish cleanup state' >&2",
+    "    write_status 'FAILED:1:TRANSACTION' || true",
+    "    emit_wrapper_failure_receipt 1 status_publish",
+    `    if ! rm -rf -- "$STAGE"; then write_status 'FAILED:1:TRANSACTION_AND_CLEANUP' || true; fi`,
+    "    exit 1",
+    "  fi",
     '  if ! rm -rf -- "$STAGE"; then',
     "    write_status 'FAILED:1:CLEANUP_AFTER_TRANSACTION' || true",
+    "    emit_wrapper_failure_receipt 1 cleanup",
+    "    exit 1",
+    "  fi",
+    "  if ! write_status SUCCEEDED; then",
+    "    write_status 'FAILED:1:TRANSACTION' || true",
+    "    emit_wrapper_failure_receipt 1 status_publish",
     "    exit 1",
     "  fi",
-    "  write_status SUCCEEDED || exit 1",
     "  exit 0",
     "}"
   ].join(`
@@ -27739,6 +27790,7 @@ function upgradeScriptSetup(paths) {
     `BUNDLE=${quoteShell2(bundleDirectory)}`,
     `MANAGEMENT_DIR=${quoteShell2(`${bundleDirectory}/management-api`)}`,
     `EDGE_DIR=${quoteShell2(`${bundleDirectory}/edge-runtime`)}`,
+    "UPGRADE_PHASE=bootstrap",
     `write_status() { local next="\${STATUS}.next"; printf '%s\\n' "$1" > "$next"; chmod 600 "$next"; mv -f "$next" "$STATUS"; }`,
     finishUpgradeFunction(),
     "trap finish_upgrade EXIT",
@@ -27756,6 +27808,7 @@ function upgradeScriptFilesystemChecks(bundle) {
   const componentFiles = expectedComponentFiles(bundle);
   const stageEntries = ["bundle", "run.sh", ...bundle.verifierArchive ? ["verifier"] : []];
   const checks = [
+    "UPGRADE_PHASE=filesystem_checks",
     shellArray("MANAGEMENT_FILES", componentFiles.management),
     shellArray("EDGE_FILES", componentFiles.edge),
     `assert_directory() { local path=$1; test -d "$path" && test ! -L "$path"; test "$(stat -c '%u:%g' "$path")" = '0:0'; test "$(stat -c '%a' "$path")" = '700'; }`,
@@ -27783,6 +27836,7 @@ function upgradeScriptFilesystemChecks(bundle) {
 function upgradeScriptTransferVerification(bundle) {
   const files = [...bundle.files, ...bundle.verifierArchive ? [bundle.verifierArchive] : []];
   return [
+    "UPGRADE_PHASE=transfer_verification",
     `verify_transfer() { local relative=$1 expected_size=$2 expected_sha=$3; local path=$STAGE/$relative; test "$(stat -c '%s' "$path")" = "$expected_size"; test "$(sha256sum "$path" | awk '{print $1}')" = "$expected_sha"; }`,
     ...files.map((file) => `verify_transfer ${quoteShell2(file.relativePath)} ${file.size} ${quoteShell2(file.sha256)}`)
   ];
@@ -27795,6 +27849,7 @@ function upgradeScriptVerifier(paths, bundle, architecture) {
   ];
   const capabilityFlags = STRICT_GITHUB_CAPABILITY_FLAGS.join(" ");
   return [
+    "UPGRADE_PHASE=verifier_setup",
     ...setup,
     `GH_HELP=$(timeout 15s "$GH" attestation verify --help 2>&1) || { echo 'GitHub verifier capability check failed' >&2; exit 1; }`,
     `for flag in ${capabilityFlags}; do printf '%s\\n' "$GH_HELP" | grep -Eq -- "(^|[[:space:]])${"$"}{flag}([=[:space:]]|$)" || { echo "GitHub verifier lacks $flag" >&2; exit 1; }; done`,
@@ -27822,6 +27877,7 @@ function upgradeScriptExecution(paths, bundle, request) {
   const runner = `${paths.stage}/runner`;
   const preflight = 'CONTROL_PLANE_PREFLIGHT_RECEIPT=$(env PATH="$VERIFIER_PATH:$PATH" "$RUNNER" --control-plane-upgrade-preflight)';
   return [
+    "UPGRADE_PHASE=runner_preflight",
     `MANAGEMENT_VERSION=${quoteShell2(request.managementVersion)}`,
     `RUNNER_ASSET=${quoteShell2(runnerAsset)}`,
     `RUNNER=${quoteShell2(runner)}`,
@@ -27832,6 +27888,7 @@ function upgradeScriptExecution(paths, bundle, request) {
     `timeout 5s "$RUNNER" --systemd-unit-helper-sha256 | grep -Eq 'SupaCloud systemd-unit helper SHA-256: [0-9a-f]{64}'`,
     `timeout 5s "$RUNNER" --postgrest-launcher-sha256 | grep -Eq 'SupaCloud PostgREST launcher SHA-256: [0-9a-f]{64}'`,
     preflight,
+    "UPGRADE_PHASE=runner_upgrade",
     `env PATH="$VERIFIER_PATH:$PATH" "$RUNNER" upgrade --yes --target-version ${quoteShell2(request.managementVersion)} --edge-runtime-version ${quoteShell2(request.edgeRuntimeVersion)} --asset-bundle-dir "$BUNDLE"`,
     `printf '%s\\n' "$CONTROL_PLANE_PREFLIGHT_RECEIPT"`
   ];
@@ -28272,6 +28329,115 @@ async function executeLocalUpgradeTransfer(ssh, request) {
     }
   }
 }
+function upgradeStatusLifecycle(status) {
+  if (["PREPARED", "RUNNING", "CLEANING"].includes(status))
+    return "running";
+  if (status === "SUCCEEDED")
+    return "succeeded";
+  const failedStatus = status.match(/^FAILED:([1-9]\d{0,2}):(TRANSACTION|TRANSACTION_AND_CLEANUP|CLEANUP_AFTER_TRANSACTION)$/);
+  if (failedStatus && Number(failedStatus[1]) <= 255)
+    return "failed";
+  throw new Error("Remote upgrade status is unknown or invalid");
+}
+function upgradeStatusEvidence(state) {
+  return {
+    drop_exists: state.dropExists,
+    log_exists: state.logExists,
+    stage_exists: state.stageExists,
+    stage_is_directory: state.stageIsDirectory,
+    status_exists: state.statusExists,
+    unit_exists: state.unitExists
+  };
+}
+async function readUpgradeStatusState(ssh, paths) {
+  try {
+    return await readRemoteState(ssh, paths);
+  } catch {
+    throw new Error("Unable to read remote upgrade state safely");
+  }
+}
+async function readUpgradeStatusLog(ssh, paths) {
+  try {
+    return await remoteLogTail(ssh, paths);
+  } catch {
+    throw new Error("Remote upgrade retained log could not be read safely");
+  }
+}
+function assertUpgradeStatusTerminalEvidence(state, paths, lifecycle) {
+  try {
+    if (lifecycle === "succeeded")
+      assertSuccessfulUnitStoppedNormally(state, paths);
+    else
+      assertFailedUnitReachedTerminalState(state, paths);
+    assertTerminalEvidence(state, paths);
+  } catch {
+    throw new Error("Remote upgrade terminal evidence is incomplete or inconsistent");
+  }
+}
+function succeededUpgradeStatus(transactionId, state, log) {
+  let preflight;
+  let transaction;
+  try {
+    preflight = parseControlPlanePreflightEvidence(log);
+    transaction = parseControlPlaneSafetyEvidence(log);
+  } catch {
+    throw new Error("Remote upgrade safety receipts are missing or invalid");
+  }
+  return {
+    schema: "supacloud.admin.upgrade-status.v1",
+    transaction_id: transactionId,
+    lifecycle: "succeeded",
+    status: state.status,
+    service_state: state.serviceState,
+    unit_load_state: state.unitLoadState,
+    evidence: upgradeStatusEvidence(state),
+    preflight: upgradeStatusControlPlaneEvidence(preflight),
+    transaction: upgradeStatusControlPlaneEvidence(transaction)
+  };
+}
+function failedUpgradeStatus(transactionId, state, log) {
+  let failure;
+  try {
+    failure = parseUpgradeFailureEvidence(log);
+  } catch {
+    throw new Error("Remote upgrade failure receipt is missing or invalid");
+  }
+  return {
+    schema: "supacloud.admin.upgrade-status.v1",
+    transaction_id: transactionId,
+    lifecycle: "failed",
+    status: state.status,
+    service_state: state.serviceState,
+    unit_load_state: state.unitLoadState,
+    evidence: upgradeStatusEvidence(state),
+    failure: upgradeStatusFailureEvidence(failure)
+  };
+}
+function runningUpgradeStatus(transactionId, state) {
+  if (!unitIsRunning(state.serviceState) || state.unitLoadState !== "loaded" || !state.statusExists) {
+    throw new Error("Remote upgrade nonterminal state is inconsistent");
+  }
+  return {
+    schema: "supacloud.admin.upgrade-status.v1",
+    transaction_id: transactionId,
+    lifecycle: "running",
+    status: state.status,
+    service_state: state.serviceState,
+    unit_load_state: state.unitLoadState,
+    evidence: upgradeStatusEvidence(state)
+  };
+}
+async function inspectRemoteUpgradeStatus(ssh, transactionIdInput) {
+  const transactionId = assertValidTransactionId(transactionIdInput);
+  const paths = buildRemoteUpgradePaths(transactionId);
+  const state = await readUpgradeStatusState(ssh, paths);
+  const lifecycle = upgradeStatusLifecycle(state.status);
+  if (lifecycle === "running")
+    return runningUpgradeStatus(transactionId, state);
+  assertUpgradeStatusTerminalEvidence(state, paths, lifecycle);
+  const log = await readUpgradeStatusLog(ssh, paths);
+  return lifecycle === "succeeded" ? succeededUpgradeStatus(transactionId, state, log) : failedUpgradeStatus(transactionId, state, log);
+}
 
 // ../../scripts/lib/release_assets.sh
 var release_assets_default = '#!/usr/bin/env bash\n\nSUPACLOUD_GITHUB_REPOSITORY="${SUPACLOUD_GITHUB_REPOSITORY:-vibeunion/supacloud}"\nSUPACLOUD_RELEASES_API="${SUPACLOUD_RELEASES_API:-https://api.github.com/repos/${SUPACLOUD_GITHUB_REPOSITORY}/releases}"\nSUPACLOUD_ATTESTATION_SIGNER_WORKFLOW="${SUPACLOUD_ATTESTATION_SIGNER_WORKFLOW:-${SUPACLOUD_GITHUB_REPOSITORY}/.github/workflows/release-please.yml}"\nSUPACLOUD_GH_VERSION="${SUPACLOUD_GH_VERSION:-2.96.0}"\nSUPACLOUD_GH_MIN_VERSION="${SUPACLOUD_GH_MIN_VERSION:-2.68.0}"\nSUPACLOUD_GH_AMD64_SHA256="${SUPACLOUD_GH_AMD64_SHA256:-83d5c2ccad5498f58bf6368acb1ab32588cf43ab3a4b1c301bf36328b1c8bd60}"\nSUPACLOUD_GH_ARM64_SHA256="${SUPACLOUD_GH_ARM64_SHA256:-06f86ec7103d41993b76cd78072f43595c34aaa56506d971d9860e67140bf909}"\nSUPACLOUD_RELEASE_ASSETS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"\nSUPACLOUD_ATTESTATION_TRUSTED_ROOT_DEFAULT="${SUPACLOUD_RELEASE_ASSETS_DIR}/../../packages/management-api/src/assets/sigstore-public-good-trusted-root.jsonl"\nreadonly SUPACLOUD_ATTESTATION_TRUSTED_ROOT_SHA256="3c2cc7f357dc064ec527fdcd78da6e9245c21a381e1abaa0f2b62b186bcac1a1"\nreadonly SUPACLOUD_ATTESTATION_TRUSTED_ROOT_SIZE="5748"\n\nsupacloud_curl_release_json() {\n    local url="$1"\n    local output="$2"\n    curl -fsSL --proto \'=https\' --proto-redir \'=https\' \\\n        --retry 1 --retry-delay 2 --retry-max-time 60 \\\n        --connect-timeout 15 --max-time 30 --speed-limit 128 --speed-time 10 \\\n        -o "$output" "$url"\n}\n\nsupacloud_curl_release_asset() {\n    local url="$1"\n    local output="$2"\n    curl -fL --proto \'=https\' --proto-redir \'=https\' \\\n        --retry 1 --retry-delay 2 --retry-max-time 180 \\\n        --connect-timeout 15 --max-time 90 --speed-limit 128 --speed-time 60 \\\n        -o "$output" "$url"\n}\n\nsupacloud_component_tag() {\n    local component="$1"\n    local version="$2"\n    case "$version" in\n        "${component}-v"*) printf \'%s\' "$version" ;;\n        v*) printf \'%s-%s\' "$component" "$version" ;;\n        *) printf \'%s-v%s\' "$component" "$version" ;;\n    esac\n}\n\nsupacloud_select_release() {\n    local component="$1"\n    shift\n    local required_assets_json\n    [[ $# -gt 0 ]] || {\n        echo "at least one required release asset must be specified" >&2\n        return 1\n    }\n    required_assets_json=$(printf \'%s\\n\' "$@" | jq -Rsc \'split("\\n")[:-1]\')\n    jq -ce --arg prefix "${component}-v" --argjson required "$required_assets_json" \'\n        map(select(\n            (.draft | not)\n            and (.prerelease | not)\n            and (.tag_name | startswith($prefix))\n            and (. as $release | all($required[]; . as $asset | any($release.assets[]?; .name == $asset)))\n            and any(.assets[]?; .name == "SHA256SUMS")\n        ))\n        | first\n        // error("no matching component release contains all required assets and SHA256SUMS")\n    \'\n}\n\nsupacloud_fetch_component_release() {\n    local component="$1"\n    local version="${2:-latest}"\n    shift 2\n    local required_assets=("$@")\n    local required_assets_json\n    local response\n    [[ ${#required_assets[@]} -gt 0 ]] || {\n        echo "at least one required release asset must be specified" >&2\n        return 1\n    }\n    required_assets_json=$(printf \'%s\\n\' "${required_assets[@]}" | jq -Rsc \'split("\\n")[:-1]\')\n\n    if [[ -n "$version" && "$version" != "latest" ]]; then\n        local tag\n        tag=$(supacloud_component_tag "$component" "$version")\n        response=$(supacloud_fetch_release_json "${SUPACLOUD_RELEASES_API}/tags/${tag}") || return 1\n        jq -ce --argjson required "$required_assets_json" \'\n            select(\n                (.draft | not)\n                and (.prerelease | not)\n                and (. as $release | all($required[]; . as $asset | any($release.assets[]?; .name == $asset)))\n                and any(.assets[]?; .name == "SHA256SUMS")\n            )\n            // error("release does not contain all required assets and SHA256SUMS")\n        \' <<< "$response"\n        return\n    fi\n\n    response=$(supacloud_fetch_release_json "${SUPACLOUD_RELEASES_API}?per_page=100") || return 1\n    supacloud_select_release "$component" "${required_assets[@]}" <<< "$response"\n}\n\nsupacloud_fetch_release_json() (\n    local url="$1"\n    local response_file\n    response_file=$(mktemp) || return 1\n    trap \'rm -f "$response_file"\' EXIT\n    trap \'trap - EXIT HUP INT TERM; rm -f "$response_file"; exit 1\' HUP INT TERM\n    supacloud_download_release_metadata_url "$url" "$response_file" || return 1\n    cat "$response_file"\n)\n\nsupacloud_release_asset_url() {\n    local release_json="$1"\n    local asset_name="$2"\n    jq -er --arg asset "$asset_name" \'\n        first(.assets[]? | select(.name == $asset) | .browser_download_url)\n        // error("release asset URL is missing")\n    \' <<< "$release_json"\n}\n\nsupacloud_download_url() {\n    local url="$1"\n    local output="$2"\n    local proxy="${SUPACLOUD_GITHUB_PROXY:-${GH_PROXY:-}}"\n\n    if supacloud_curl_release_asset "$url" "$output"; then\n        return 0\n    fi\n    if [[ -n "$proxy" ]]; then\n        supacloud_curl_release_asset "${proxy%/}/${url}" "$output"\n        return\n    fi\n    return 1\n}\n\nsupacloud_download_release_metadata_url() {\n    local url="$1"\n    local output="$2"\n    local proxy="${SUPACLOUD_GITHUB_PROXY:-${GH_PROXY:-}}"\n\n    if supacloud_curl_release_json "$url" "$output"; then\n        return 0\n    fi\n    if [[ -n "$proxy" ]]; then\n        supacloud_curl_release_json "${proxy%/}/${url}" "$output"\n        return\n    fi\n    return 1\n}\n\nsupacloud_verify_checksum() {\n    local artifact_file="$1"\n    local asset_name="$2"\n    local checksum_file="$3"\n    local expected\n    expected=$(awk -v asset="$asset_name" \'$2 == asset || $2 == "*" asset { print $1; exit }\' "$checksum_file")\n    if [[ ! "$expected" =~ ^[0-9a-fA-F]{64}$ ]]; then\n        echo "SHA256SUMS does not contain a valid checksum for ${asset_name}" >&2\n        return 1\n    fi\n\n    local actual\n    actual=$(sha256sum "$artifact_file" | awk \'{print $1}\')\n    actual=$(printf \'%s\' "$actual" | tr \'[:upper:]\' \'[:lower:]\')\n    expected=$(printf \'%s\' "$expected" | tr \'[:upper:]\' \'[:lower:]\')\n    if [[ "$actual" != "$expected" ]]; then\n        echo "SHA256 mismatch for ${asset_name}" >&2\n        return 1\n    fi\n}\n\nsupacloud_validate_binary() {\n    local artifact_file="$1"\n    local asset_name="$2"\n    local description\n    description=$(file -b "$artifact_file")\n    if [[ "$description" != *ELF* ]]; then\n        echo "${asset_name} is not an ELF binary: ${description}" >&2\n        return 1\n    fi\n\n    case "$asset_name" in\n        *amd64)\n            [[ "$description" == *x86-64* || "$description" == *x86_64* ]] || {\n                echo "${asset_name} does not contain an x86-64 ELF binary" >&2\n                return 1\n            }\n            ;;\n        *arm64)\n            [[ "$description" == *aarch64* || "$description" == *ARM64* ]] || {\n                echo "${asset_name} does not contain an arm64 ELF binary" >&2\n                return 1\n            }\n            ;;\n    esac\n}\n\nsupacloud_install_pinned_tar_xz_binary() (\n    local archive="$1"\n    local member="$2"\n    local expected_sha256="$3"\n    local arch="$4"\n    local target="$5"\n    local actual_sha256 member_count member_details extract_dir candidate staged_target\n\n    actual_sha256=$(sha256sum "$archive" | awk \'{print $1}\')\n    actual_sha256=$(printf \'%s\' "$actual_sha256" | tr \'[:upper:]\' \'[:lower:]\')\n    expected_sha256=$(printf \'%s\' "$expected_sha256" | tr \'[:upper:]\' \'[:lower:]\')\n    if [[ ! "$expected_sha256" =~ ^[0-9a-f]{64}$ || "$actual_sha256" != "$expected_sha256" ]]; then\n        echo "SHA256 mismatch for pinned archive" >&2\n        return 1\n    fi\n\n    member_count=$(tar -tJf "$archive" | grep -Fxc "$member" || true)\n    if [[ "$member_count" != "1" ]]; then\n        echo "Pinned archive must contain the exact member once: $member" >&2\n        return 1\n    fi\n    member_details=$(tar -tvJf "$archive" "$member") || return 1\n    if [[ "${member_details:0:1}" != "-" ]]; then\n        echo "Pinned archive member is not a regular file: $member" >&2\n        return 1\n    fi\n\n    extract_dir=$(mktemp -d)\n    trap \'rm -rf "$extract_dir"; [[ -z "${staged_target:-}" ]] || rm -f "$staged_target"\' EXIT\n    trap \'trap - EXIT HUP INT TERM; rm -rf "$extract_dir"; [[ -z "${staged_target:-}" ]] || rm -f "$staged_target"; exit 1\' HUP INT TERM\n    if ! tar --no-same-owner --no-same-permissions -xJf "$archive" -C "$extract_dir" "$member"; then\n        return 1\n    fi\n    candidate="${extract_dir}/${member}"\n    supacloud_validate_binary "$candidate" "pinned-linux-${arch}" || return 1\n\n    mkdir -p "$(dirname "$target")"\n    staged_target=$(mktemp "${target}.tmp.XXXXXX")\n    install -m 0755 "$candidate" "$staged_target"\n    mv -f "$staged_target" "$target"\n    staged_target=""\n)\n\nsupacloud_version_at_least() {\n    local current="${1#v}"\n    local required="${2#v}"\n    local current_major=0 current_minor=0 current_patch=0\n    local required_major=0 required_minor=0 required_patch=0\n    [[ "$current" =~ ^[0-9]+\\.[0-9]+\\.[0-9]+(-.*)?$ ]] || return 1\n    [[ "$required" =~ ^[0-9]+\\.[0-9]+\\.[0-9]+(-.*)?$ ]] || return 1\n    IFS=. read -r current_major current_minor current_patch <<EOF\n${current%%-*}\nEOF\n    IFS=. read -r required_major required_minor required_patch <<EOF\n${required%%-*}\nEOF\n    current_major=${current_major:-0}; current_minor=${current_minor:-0}; current_patch=${current_patch:-0}\n    required_major=${required_major:-0}; required_minor=${required_minor:-0}; required_patch=${required_patch:-0}\n    if (( current_major != required_major )); then (( current_major > required_major )); return; fi\n    if (( current_minor != required_minor )); then (( current_minor > required_minor )); return; fi\n    (( current_patch >= required_patch ))\n}\n\nsupacloud_gh_version() {\n    gh --version 2>/dev/null | awk \'NR == 1 && $1 == "gh" && $2 == "version" { print $3; exit }\'\n}\n\nsupacloud_install_gh_archive() {\n    local archive="$1"\n    local version="$2"\n    local arch="$3"\n    local expected_sha256="$4"\n    local target="$5"\n    local member="gh_${version}_linux_${arch}/bin/gh"\n    local actual_sha256 member_count member_details extracted_dir candidate version_output\n\n    actual_sha256=$(sha256sum "$archive" | awk \'{print $1}\')\n    if [[ "$actual_sha256" != "$expected_sha256" ]]; then\n        echo "GitHub CLI archive SHA256 mismatch" >&2\n        return 1\n    fi\n\n    member_count=$(tar -tzf "$archive" | grep -Fxc "$member" || true)\n    if [[ "$member_count" != "1" ]]; then\n        echo "GitHub CLI archive does not contain the exact expected member: $member" >&2\n        return 1\n    fi\n    member_details=$(tar -tvzf "$archive" "$member") || return 1\n    if [[ "${member_details:0:1}" != "-" ]]; then\n        echo "GitHub CLI archive member is not a regular file: $member" >&2\n        return 1\n    fi\n\n    extracted_dir=$(mktemp -d)\n    candidate="${extracted_dir}/${member}"\n    if ! tar --no-same-owner --no-same-permissions -xzf "$archive" -C "$extracted_dir" "$member" \\\n        || ! supacloud_validate_binary "$candidate" "gh-linux-${arch}"; then\n        rm -rf "$extracted_dir"\n        return 1\n    fi\n    chmod 0755 "$candidate"\n    version_output=$("$candidate" --version 2>/dev/null | head -1) || {\n        rm -rf "$extracted_dir"\n        echo "GitHub CLI bootstrap binary failed its version check" >&2\n        return 1\n    }\n    if [[ "$version_output" != "gh version ${version}"* ]]; then\n        rm -rf "$extracted_dir"\n        echo "GitHub CLI bootstrap version mismatch: ${version_output}" >&2\n        return 1\n    fi\n    mkdir -p "$(dirname "$target")"\n    install -m 0755 "$candidate" "$target"\n    rm -rf "$extracted_dir"\n}\n\nsupacloud_install_pinned_gh() {\n    local target="${1:-/usr/local/bin/gh}"\n    local machine arch expected_sha256 asset url archive\n    machine=$(uname -m)\n    case "$machine" in\n        x86_64|amd64)\n            arch="amd64"\n            expected_sha256="$SUPACLOUD_GH_AMD64_SHA256"\n            ;;\n        aarch64|arm64)\n            arch="arm64"\n            expected_sha256="$SUPACLOUD_GH_ARM64_SHA256"\n            ;;\n        *)\n            echo "Unsupported architecture for GitHub CLI bootstrap: $machine" >&2\n            return 1\n            ;;\n    esac\n    asset="gh_${SUPACLOUD_GH_VERSION}_linux_${arch}.tar.gz"\n    url="https://github.com/cli/cli/releases/download/v${SUPACLOUD_GH_VERSION}/${asset}"\n    archive=$(mktemp)\n    if ! supacloud_download_url "$url" "$archive" \\\n        || ! supacloud_install_gh_archive "$archive" "$SUPACLOUD_GH_VERSION" "$arch" "$expected_sha256" "$target"; then\n        rm -f "$archive"\n        return 1\n    fi\n    rm -f "$archive"\n}\n\nsupacloud_validate_tar() {\n    local artifact_file="$1"\n    local entries\n    entries=$(tar -tzf "$artifact_file") || {\n        echo "Web Console archive is not a readable gzip tarball" >&2\n        return 1\n    }\n    if ! printf \'%s\\n\' "$entries" | awk \'\n        /^\\// { exit 1 }\n        /(^|\\/)\\.\\.($|\\/)/ { exit 1 }\n    \'; then\n        echo "Web Console archive contains an unsafe path" >&2\n        return 1\n    fi\n    if ! tar -tvzf "$artifact_file" | awk \'substr($1, 1, 1) != "-" && substr($1, 1, 1) != "d" { exit 1 }\'; then\n        echo "Web Console archive contains links or special files" >&2\n        return 1\n    fi\n    printf \'%s\\n\' "$entries" | grep -Eq \'(^|/)index\\.html$\' || {\n        echo "Web Console archive is invalid or does not contain index.html" >&2\n        return 1\n    }\n}\n\nsupacloud_record_integrity_mode() {\n    local mode="$1"\n    local record_file="${SUPACLOUD_INTEGRITY_MODE_RECORD:-/var/lib/supacloud/artifact-integrity-mode}"\n    mkdir -p "$(dirname "$record_file")" 2>/dev/null || return 0\n    printf \'%s\\n\' "$mode" > "$record_file" 2>/dev/null || return 0\n    chmod 600 "$record_file" 2>/dev/null || true\n}\n\nsupacloud_fetch_attestation_bundle() {\n    local artifact_file="$1"\n    local bundle_file="$2"\n    local digest response\n    digest=$(sha256sum "$artifact_file" | awk \'{print $1}\') || return 1\n    [[ "$digest" =~ ^[0-9a-fA-F]{64}$ ]] || {\n        echo "Unable to calculate the artifact digest for attestation lookup" >&2\n        return 1\n    }\n    digest=$(printf \'%s\' "$digest" | tr \'[:upper:]\' \'[:lower:]\')\n    response=$(supacloud_fetch_release_json \\\n        "https://api.github.com/repos/${SUPACLOUD_GITHUB_REPOSITORY}/attestations/sha256:${digest}") || {\n        echo "Unable to download the public GitHub artifact attestation bundle" >&2\n        return 1\n    }\n    if ! jq -ce \'\n        .attestations\n        | if type != "array" or length == 0 or any(.[]; (.bundle | type) != "object")\n          then error("no valid attestation bundles returned")\n          else .[].bundle\n          end\n    \' <<< "$response" > "$bundle_file"; then\n        echo "GitHub artifact attestation response did not contain a valid bundle" >&2\n        return 1\n    fi\n}\n\nsupacloud_attestation_trusted_root_available() {\n    local trusted_root="${SUPACLOUD_ATTESTATION_TRUSTED_ROOT:-$SUPACLOUD_ATTESTATION_TRUSTED_ROOT_DEFAULT}"\n    local actual_size actual_sha256\n    [[ "$trusted_root" == /* && -f "$trusted_root" && ! -L "$trusted_root" ]] || return 1\n    actual_size=$(wc -c < "$trusted_root" | tr -d \'[:space:]\') || return 1\n    [[ "$actual_size" == "$SUPACLOUD_ATTESTATION_TRUSTED_ROOT_SIZE" ]] || return 1\n    actual_sha256=$(sha256sum "$trusted_root" | awk \'{print $1}\') || return 1\n    [[ "$actual_sha256" == "$SUPACLOUD_ATTESTATION_TRUSTED_ROOT_SHA256" ]] || return 1\n    [[ "$(wc -l < "$trusted_root" | tr -d \'[:space:]\')" == "1" ]] || return 1\n    jq -e \'type == "object" and .mediaType == "application/vnd.dev.sigstore.trustedroot+json;version=0.1"\' \\\n        "$trusted_root" >/dev/null 2>&1\n}\n\nsupacloud_prepare_attestation_trusted_root() {\n    local destination="$1"\n    local trusted_root="${SUPACLOUD_ATTESTATION_TRUSTED_ROOT:-$SUPACLOUD_ATTESTATION_TRUSTED_ROOT_DEFAULT}"\n    supacloud_attestation_trusted_root_available || {\n        echo "Pinned Sigstore Public Good trusted root is missing or invalid" >&2\n        return 1\n    }\n    jq -ce . "$trusted_root" > "$destination" || return 1\n    chmod 600 "$destination"\n    [[ "$(wc -c < "$destination" | tr -d \'[:space:]\')" == "$SUPACLOUD_ATTESTATION_TRUSTED_ROOT_SIZE" ]] || return 1\n    [[ "$(sha256sum "$destination" | awk \'{print $1}\')" == "$SUPACLOUD_ATTESTATION_TRUSTED_ROOT_SHA256" ]]\n}\n\nsupacloud_verify_attestation() (\n    local artifact_file="$1"\n    if supacloud_attestation_verifier_available; then\n        local verification_output bundle_dir bundle_file trusted_root_file\n        bundle_dir=$(mktemp -d "${TMPDIR:-/tmp}/supacloud-attestation.XXXXXX") || return 1\n        trap \'rm -rf -- "$bundle_dir"\' EXIT\n        trap \'trap - EXIT HUP INT TERM; rm -rf -- "$bundle_dir"; exit 1\' HUP INT TERM\n        bundle_file="${bundle_dir}/bundle.jsonl"\n        trusted_root_file="${bundle_dir}/trusted_root.jsonl"\n        if ! supacloud_fetch_attestation_bundle "$artifact_file" "$bundle_file"; then\n            return 1\n        fi\n        supacloud_prepare_attestation_trusted_root "$trusted_root_file" || return 1\n        if ! verification_output=$(gh attestation verify "$artifact_file" \\\n            --bundle "$bundle_file" \\\n            --custom-trusted-root "$trusted_root_file" \\\n            --repo "$SUPACLOUD_GITHUB_REPOSITORY" \\\n            --signer-workflow "$SUPACLOUD_ATTESTATION_SIGNER_WORKFLOW" \\\n            --source-ref "refs/heads/main" \\\n            --deny-self-hosted-runners 2>&1); then\n            echo "GitHub artifact attestation verification failed: ${verification_output}" >&2\n            return 1\n        fi\n        supacloud_record_integrity_mode "github-attestation+same-release-sha256"\n        return\n    fi\n\n    if [[ "${SUPACLOUD_ALLOW_UNVERIFIED_RELEASE:-false}" == "true" ]]; then\n        echo "BREAK-GLASS LIMITED INTEGRITY MODE: artifact attestation verification is unavailable; only the same-release SHA256 checksum was verified." >&2\n        supacloud_record_integrity_mode "break-glass:same-release-sha256-only"\n        return 0\n    fi\n\n    echo "Artifact attestation verification is required, but gh attestation verify is unavailable. Install GitHub CLI or explicitly set SUPACLOUD_ALLOW_UNVERIFIED_RELEASE=true for emergency break-glass use." >&2\n    return 1\n)\n\nsupacloud_attestation_verifier_available() {\n    local version help\n    supacloud_attestation_trusted_root_available || return 1\n    command -v gh >/dev/null 2>&1 || return 1\n    version=$(supacloud_gh_version)\n    [[ -n "$version" ]] || return 1\n    supacloud_version_at_least "$version" "$SUPACLOUD_GH_MIN_VERSION" || return 1\n    help=$(gh attestation verify --help 2>&1) || return 1\n    grep -Eq -- \'(^|[[:space:]])--bundle([=[:space:]]|$)\' <<< "$help" || return 1\n    grep -Eq -- \'(^|[[:space:]])--signer-workflow([=[:space:]]|$)\' <<< "$help" || return 1\n    grep -Eq -- \'(^|[[:space:]])--source-ref([=[:space:]]|$)\' <<< "$help" || return 1\n    grep -Eq -- \'(^|[[:space:]])--custom-trusted-root([=[:space:]]|$)\' <<< "$help" || return 1\n    grep -Eq -- \'(^|[[:space:]])--deny-self-hosted-runners([=[:space:]]|$)\' <<< "$help"\n}\n\nsupacloud_download_release_asset() (\n    local release_json="$1"\n    local asset_name="$2"\n    local destination="$3"\n    local asset_kind="$4"\n    local asset_url checksum_url temporary_artifact temporary_checksums\n\n    asset_url=$(supacloud_release_asset_url "$release_json" "$asset_name") || return 1\n    checksum_url=$(supacloud_release_asset_url "$release_json" SHA256SUMS) || return 1\n    mkdir -p "$(dirname "$destination")"\n    temporary_artifact=$(mktemp "${destination}.tmp.XXXXXX")\n    temporary_checksums=$(mktemp "${destination}.SHA256SUMS.tmp.XXXXXX")\n    trap \'rm -f "${temporary_artifact:-}" "${temporary_checksums:-}"\' EXIT\n    trap \'trap - EXIT HUP INT TERM; rm -f "${temporary_artifact:-}" "${temporary_checksums:-}"; exit 1\' HUP INT TERM\n\n    if ! supacloud_download_url "$asset_url" "$temporary_artifact" \\\n        || ! supacloud_download_release_metadata_url "$checksum_url" "$temporary_checksums" \\\n        || ! supacloud_verify_checksum "$temporary_artifact" "$asset_name" "$temporary_checksums"; then\n        rm -f "$temporary_artifact" "$temporary_checksums"\n        return 1\n    fi\n\n    # Authenticate the digest before parsing archives or inspecting binaries.\n    if ! supacloud_verify_attestation "$temporary_artifact"; then\n        rm -f "$temporary_artifact" "$temporary_checksums"\n        return 1\n    fi\n\n    case "$asset_kind" in\n        binary) supacloud_validate_binary "$temporary_artifact" "$asset_name" ;;\n        tar) supacloud_validate_tar "$temporary_artifact" ;;\n        *)\n            echo "Unknown release asset kind: $asset_kind" >&2\n            rm -f "$temporary_artifact" "$temporary_checksums"\n            return 1\n            ;;\n    esac || {\n        rm -f "$temporary_artifact" "$temporary_checksums"\n        return 1\n    }\n\n    mv -f "$temporary_artifact" "$destination"\n    temporary_artifact=""\n    rm -f "$temporary_checksums"\n    temporary_checksums=""\n)\n';
@@ -29164,12 +29330,13 @@ function platformVersionsToolResult(report) {
 }
 function registerSshTools(server, ssh) {
   server.tool("ssh", `Server management via SSH. Available before & after SupaCloud installation.
-Actions: ping, setup, install, upgrade, versions, diagnose, exec, troubleshoot, container_logs, tenant_manage, tenant_list, tenant_inspect, tenant_diagnose, tenant_migrate`, {
+Actions: ping, setup, install, upgrade, upgrade_status, versions, diagnose, exec, troubleshoot, container_logs, tenant_manage, tenant_list, tenant_inspect, tenant_diagnose, tenant_migrate`, {
     action: withDescription(stringEnum([
       "ping",
       "setup",
       "install",
       "upgrade",
+      "upgrade_status",
       "versions",
       "diagnose",
       "exec",
@@ -29189,6 +29356,7 @@ Actions: ping, setup, install, upgrade, versions, diagnose, exec, troubleshoot,
     dashboard_password: optional(secretSchema("dashboard_password"), "[install] Console password"),
     edge_runtime: optional(stringEnum(["bun"]), "[install] Runtime (default: bun)"),
     storage_type: optional(stringEnum(["juicefs", "minio"]), "[install] Storage backend configurable through Admin"),
+    transaction_id: optional(Type.String(), "[upgrade_status] UUID v4 transaction ID of a retained local-artifact upgrade"),
     version: optional(Type.String(), "[upgrade] Specific version"),
     edge_runtime_version: optional(Type.String(), "[upgrade] Exact independent Edge Runtime version"),
     artifact_transport: optional(stringEnum(["local", "remote"]), "[upgrade] Download verified release assets locally or on the server (default: remote)"),
@@ -29347,6 +29515,14 @@ ${result.stderr.slice(-500)}`;
 ${upgradeExecution.stdout.slice(-300)}${edgeBoundary}`;
         break;
       }
+      case "upgrade_status": {
+        if (!args.transaction_id)
+          throw new Error("'transaction_id' required");
+        const transactionId = assertValidTransactionId(args.transaction_id);
+        const projection = await inspectRemoteUpgradeStatus(ssh, transactionId);
+        text = JSON.stringify(projection, null, 2);
+        break;
+      }
       case "versions": {
         return platformVersionsToolResult(await platformVersions(ssh));
       }
@@ -32366,7 +32542,7 @@ Actions: list_releases, get_release, upload_release, activate_release`, {
 // package.json
 var package_default = {
   name: "@supacloud/admin",
-  version: "0.15.5",
+  version: "0.16.1",
   description: "Platform administration CLI for SupaCloud operators",
   type: "module",
   main: "./dist/index.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supacloud/admin",
-  "version": "0.15.5",
+  "version": "0.16.1",
   "description": "Platform administration CLI for SupaCloud operators",
   "type": "module",
   "main": "./dist/index.js",