@supacloud/admin 0.15.1 → 0.15.3

package/README.md

@@ -124,8 +124,8 @@ external Edge Runtime as a single rollback-capable transaction:
 
 ```bash
 npx @supacloud/admin ssh upgrade \
-  --version 0.50.31 \
-  --edge_runtime_version 0.16.8 \
+  --version 0.61.4 \
+  --edge_runtime_version 0.18.2 \
   --artifact_transport local \
   --github_proxy direct
 ```
@@ -150,6 +150,43 @@ enabled state. Component upgrades require persisted `EDGE_RUNTIME_MODE=external`
 embedded mode is rejected before release artifacts or services are changed.
 Local, remote, and direct server upgrades share one nonblocking host-wide lock.
 
+Local artifact upgrades require Management 0.61.4 or newer. After stopping the
+old Management service and before writing runtime secrets or running
+`--init-db`, the target binary verifies that `DATABASE_URL` identifies the
+Management control-plane database, rejects a registered tenant database, and
+creates a verified custom-format PostgreSQL archive. Backups and their private
+receipts are stored under
+`/var/lib/supacloud/backups/control-plane-upgrades/<backup-id>/`; the five most
+recent trusted backups are retained.
+
+The inspection transaction remains open while `pg_dump` imports its exported
+snapshot, so a different PostgreSQL server cannot satisfy the dump step. The
+root process reserves the private archive first; the `postgres` identity receives
+only that inherited output descriptor and never gains path access to the
+root-only backup directory.
+
+The inspection transaction also keeps its exported snapshot alive until staged
+`--init-db` finishes. The child receives the database fingerprint and snapshot
+only in its process environment, imports that live snapshot, verifies the
+PostgreSQL cluster and database identity, and performs all initialization writes
+inside that same transaction. This keeps the writes on one PostgreSQL backend
+even when `DATABASE_URL` points through a transaction-pooling proxy. A copied
+data directory, promoted standby, restored disk snapshot, or other node cannot
+import the exporter-owned snapshot even when its static fingerprint matches.
+The guard is not persisted or printed. A guard rejection restores the previous
+runtime environment but leaves Management stopped for explicit reconciliation
+instead of reconnecting it to an unverified target.
+
+A committed transaction emits exactly one redacted
+`supacloud.control-plane-upgrade-safety.v1` receipt. It contains only the backup
+identifier and directory, byte count, SHA-256 digest, migration candidate
+counts, checkpoint state, and completion time. Admin validates the exact
+receipt schema before deleting the transient
+status and log records. A missing or malformed receipt leaves those records in
+place and requires reconciliation. Restoring a control-plane backup is a
+separate destructive operation and requires an explicit, independently reviewed
+recovery decision; the upgrade command never restores one automatically.
+
 Admin observes the remote transaction for up to 30 minutes. Reaching that
 deadline stops only local observation; it does not stop, clean up, or mark the
 remote transaction as failed. The CLI reports the unit, stage, status, log, and

package/dist/index.js

@@ -26367,7 +26367,7 @@ function quoteShell(shellText) {
 // src/shared/releases/local-upgrade-bundle.ts
 import { spawn } from "node:child_process";
 import { createHash as createHash2, randomUUID as randomUUID2 } from "node:crypto";
-import { accessSync, chmodSync as chmodSync2, constants as fsConstants, createWriteStream, lstatSync, mkdirSync, mkdtempSync as mkdtempSync2, readFileSync as readFileSync3, readdirSync, rmSync as rmSync2, statSync, writeFileSync as writeFileSync2 } from "node:fs";
+import { accessSync, chmodSync as chmodSync2, constants as fsConstants, createWriteStream, lstatSync, mkdirSync, mkdtempSync as mkdtempSync2, readFileSync as readFileSync3, readdirSync, renameSync, rmSync as rmSync2, statSync, writeFileSync as writeFileSync2 } from "node:fs";
 import { get } from "node:https";
 import { tmpdir as tmpdir2 } from "node:os";
 import { basename, delimiter, join } from "node:path";
@@ -26381,6 +26381,14 @@ var RELEASE_CHECKSUMS_NAME = "SHA256SUMS";
 var RELEASE_REPOSITORY = "vibeunion/supacloud";
 var RELEASE_SOURCE_REF = "refs/heads/main";
 var RELEASE_SIGNER_WORKFLOW = `${RELEASE_REPOSITORY}/.github/workflows/release-please.yml`;
+var LEGACY_EDGE_RUNTIME_RELEASE_IDENTITY = {
+  repository: "zuohuadong/supacloud",
+  workflow: "zuohuadong/supacloud/.github/workflows/release-please.yml",
+  component: "edge-runtime",
+  version: "0.18.2",
+  tag: "edge-runtime-v0.18.2",
+  sourceCommit: "c6a3a87cf4e41e0f3dafadb018dd0c7d5b99b7d9"
+};
 var MEBIBYTE = 1024 * 1024;
 var RELEASE_BUNDLE_SIZE_LIMITS = {
   manifest: MEBIBYTE,
@@ -26487,6 +26495,16 @@ function parseArtifacts(candidate, component) {
     throw new Error(`Release manifest artifact ${oversized.name} exceeds its size limit`);
   return artifacts;
 }
+function parseIdentity(manifest, source, release) {
+  const current = manifest.repository === RELEASE_REPOSITORY && manifest.workflow === RELEASE_SIGNER_WORKFLOW;
+  const legacyEdgeRuntime = manifest.repository === LEGACY_EDGE_RUNTIME_RELEASE_IDENTITY.repository && manifest.workflow === LEGACY_EDGE_RUNTIME_RELEASE_IDENTITY.workflow && release.component === LEGACY_EDGE_RUNTIME_RELEASE_IDENTITY.component && release.version === LEGACY_EDGE_RUNTIME_RELEASE_IDENTITY.version && release.tag === LEGACY_EDGE_RUNTIME_RELEASE_IDENTITY.tag && source.commit === LEGACY_EDGE_RUNTIME_RELEASE_IDENTITY.sourceCommit;
+  if (!current && !legacyEdgeRuntime)
+    throw new Error("Release manifest identity is invalid");
+  return {
+    repository: manifest.repository,
+    workflow: manifest.workflow
+  };
+}
 function parseReleaseManifest(text, expected) {
   let candidate;
   try {
@@ -26496,15 +26514,16 @@ function parseReleaseManifest(text, expected) {
   }
   const manifest = manifestObject(candidate, "Release manifest");
   assertExactKeys(manifest, ["schemaVersion", "repository", "source", "workflow", "release", "artifacts"], "Release manifest");
-  if (manifest.schemaVersion !== 1 || manifest.repository !== RELEASE_REPOSITORY || manifest.workflow !== RELEASE_SIGNER_WORKFLOW) {
+  if (manifest.schemaVersion !== 1)
     throw new Error("Release manifest identity is invalid");
-  }
+  const source = parseSource(manifest.source);
+  const release = parseRelease(manifest.release, expected);
+  const identity = parseIdentity(manifest, source, release);
   return {
     schemaVersion: 1,
-    repository: RELEASE_REPOSITORY,
-    source: parseSource(manifest.source),
-    workflow: RELEASE_SIGNER_WORKFLOW,
-    release: parseRelease(manifest.release, expected),
+    ...identity,
+    source,
+    release,
     artifacts: parseArtifacts(manifest.artifacts, expected.component)
   };
 }
@@ -26994,11 +27013,11 @@ function githubAttestationVerificationArguments(request) {
     "--bundle",
     request.bundlePath,
     "--repo",
-    RELEASE_REPOSITORY,
+    request.manifest.repository,
     "--signer-workflow",
-    RELEASE_SIGNER_WORKFLOW,
+    request.manifest.workflow,
     "--source-ref",
-    RELEASE_SOURCE_REF,
+    request.manifest.source.ref,
     "--source-digest",
     request.manifest.source.commit,
     "--deny-self-hosted-runners",
@@ -27041,13 +27060,27 @@ async function downloadReleaseMetadata(component, version, directory) {
     rmSync2(metadataPath, { force: true });
   }
 }
-async function downloadManifestAttestation(manifestPath, destination) {
+function manifestAttestationDownloadUrl(release, manifest, manifestDigest) {
+  if (manifest.repository === RELEASE_REPOSITORY) {
+    return `${ATTESTATIONS_API}/sha256:${manifestDigest}`;
+  }
+  if (manifest.repository === LEGACY_EDGE_RUNTIME_RELEASE_IDENTITY.repository) {
+    return releaseAssetUrl(release, RELEASE_ATTESTATION_NAME);
+  }
+  throw new Error("Release manifest repository is not supported");
+}
+async function downloadManifestAttestation(request) {
+  const { release, manifest, manifestPath, destination } = request;
   const responsePath = `${destination}.response`;
   try {
-    await downloadDirect(`${ATTESTATIONS_API}/sha256:${sha256File(manifestPath)}`, responsePath, RELEASE_BUNDLE_SIZE_LIMITS.attestation);
-    const bundles = serializeAttestationBundles(parseJsonFile(responsePath, "GitHub attestation response"));
-    writeFileSync2(destination, bundles, { mode: 384, flag: "wx" });
-    chmodSync2(destination, 384);
+    await downloadDirect(manifestAttestationDownloadUrl(release, manifest, sha256File(manifestPath)), responsePath, RELEASE_BUNDLE_SIZE_LIMITS.attestation);
+    if (manifest.repository === RELEASE_REPOSITORY) {
+      const bundles = serializeAttestationBundles(parseJsonFile(responsePath, "GitHub attestation response"));
+      writeFileSync2(destination, bundles, { mode: 384, flag: "wx" });
+      chmodSync2(destination, 384);
+    } else {
+      renameSync(responsePath, destination);
+    }
   } finally {
     rmSync2(responsePath, { force: true });
   }
@@ -27058,7 +27091,7 @@ async function downloadComponent(request) {
   const attestationPath = directChildPath(request.destination, RELEASE_ATTESTATION_NAME);
   await downloadDirect(releaseAssetUrl(release, RELEASE_MANIFEST_NAME), manifestPath, RELEASE_BUNDLE_SIZE_LIMITS.manifest);
   const manifest = parseReleaseManifest(readFileSync3(manifestPath, "utf8"), request);
-  await downloadManifestAttestation(manifestPath, attestationPath);
+  await downloadManifestAttestation({ release, manifest, manifestPath, destination: attestationPath });
   await verifyManifestAttestation({
     artifactPath: manifestPath,
     bundlePath: attestationPath,
@@ -27192,6 +27225,9 @@ var REMOTE_RUN_ROOT = "/var/lib/supacloud/upgrade-runs";
 var REMOTE_LOG_ROOT = "/var/log/supacloud";
 var REMOTE_UPLOAD_ROOT = "/var/tmp";
 var REMOTE_COMMAND_PATH = "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin";
+var CONTROL_PLANE_BACKUP_ROOT = "/var/lib/supacloud/backups/control-plane-upgrades";
+var CONTROL_PLANE_SAFETY_PREFIX = "SUPACLOUD_CONTROL_PLANE_UPGRADE_SAFETY=";
+var MINIMUM_CONTROL_PLANE_SAFETY_VERSION = [0, 61, 4];
 var POLL_INTERVAL_MS = 2000;
 var STATE_READ_ATTEMPTS = 3;
 var REMOTE_STATE_READ_TIMEOUT_MS = 15000;
@@ -27199,6 +27235,76 @@ var UPGRADE_OBSERVATION_TIMEOUT_MS = 30 * 60000;
 
 class RemoteUpgradeReconciliationError extends AggregateError {
 }
+function exactObjectKeys(candidate, expected) {
+  const actual = Object.keys(candidate).sort();
+  return actual.length === expected.length && actual.every((key, index) => key === [...expected].sort()[index]);
+}
+function nonNegativeIntegerRecord(candidate, expectedKeys) {
+  if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
+    return false;
+  const record = candidate;
+  return exactObjectKeys(record, expectedKeys) && Object.values(record).every((value) => Number.isSafeInteger(value) && Number(value) >= 0);
+}
+function canonicalTimestamp(candidate) {
+  if (typeof candidate !== "string")
+    return false;
+  const timestamp = new Date(candidate);
+  return Number.isFinite(timestamp.valueOf()) && timestamp.toISOString() === candidate;
+}
+function parseControlPlaneSafetyEvidence(log) {
+  const receiptLines = log.split(/\r?\n/).filter((line) => line.startsWith(CONTROL_PLANE_SAFETY_PREFIX));
+  if (receiptLines.length !== 1)
+    throw new Error("Remote upgrade did not emit one control-plane safety receipt");
+  let candidate;
+  try {
+    candidate = JSON.parse(receiptLines[0].slice(CONTROL_PLANE_SAFETY_PREFIX.length));
+  } catch {
+    throw new Error("Remote control-plane safety receipt is not valid JSON");
+  }
+  if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) {
+    throw new Error("Remote control-plane safety receipt is invalid");
+  }
+  const receipt = candidate;
+  const expectedKeys = [
+    "backup_id",
+    "backup_directory",
+    "bytes",
+    "candidate_counts",
+    "completed_at",
+    "current_key_checkpoint_present",
+    "schema",
+    "sha256"
+  ];
+  const candidateKeys = [
+    "deprecated_webhook_secrets",
+    "legacy_deployment_history_rows",
+    "legacy_project_config_rows",
+    "opaque_key_backfill_projects",
+    "stored_secret_values"
+  ];
+  const validBackupId = typeof receipt.backup_id === "string" && /^control-plane-\d{8}T\d{6}Z-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(receipt.backup_id);
+  const validDigest = typeof receipt.sha256 === "string" && /^[0-9a-f]{64}$/.test(receipt.sha256);
+  if (!exactObjectKeys(receipt, expectedKeys) || receipt.schema !== "supacloud.control-plane-upgrade-safety.v1" || !validBackupId || receipt.backup_directory !== `${CONTROL_PLANE_BACKUP_ROOT}/${receipt.backup_id}` || !Number.isSafeInteger(receipt.bytes) || Number(receipt.bytes) <= 0 || !canonicalTimestamp(receipt.completed_at) || typeof receipt.current_key_checkpoint_present !== "boolean" || !validDigest || !nonNegativeIntegerRecord(receipt.candidate_counts, candidateKeys)) {
+    throw new Error("Remote control-plane safety receipt is invalid");
+  }
+  return receipt;
+}
+function assertControlPlaneSafetyVersion(version) {
+  const match = version.match(/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/);
+  if (!match)
+    throw new Error("Management version must be an exact stable version");
+  const requested = match.slice(1).map(Number);
+  if (!requested.every(Number.isSafeInteger)) {
+    throw new Error("Management version must be an exact stable version");
+  }
+  for (let index = 0;index < requested.length; index += 1) {
+    if (requested[index] > MINIMUM_CONTROL_PLANE_SAFETY_VERSION[index])
+      return;
+    if (requested[index] < MINIMUM_CONTROL_PLANE_SAFETY_VERSION[index]) {
+      throw new Error("Local artifact upgrades require Management 0.61.4 or newer with control-plane backup safety");
+    }
+  }
+}
 function quoteShell2(shellText) {
   return `'${shellText.split("'").join("'\\''")}'`;
 }
@@ -27254,7 +27360,7 @@ function buildRemotePreflightScript() {
     "export PATH",
     trustedInstalledGithubFunction(),
     "test -d /run/systemd/system || { echo 'systemd is not the active init system' >&2; exit 1; }",
-    'for tool in systemctl systemd-run sha256sum stat realpath tar file find sort awk grep tail timeout flock install mktemp; do command -v "$tool" >/dev/null 2>&1 || { echo "Required local-upgrade tool is missing: $tool" >&2; exit 127; }; done',
+    'for tool in systemctl systemd-run sha256sum stat realpath tar file find sort awk grep tail timeout flock install mktemp setpriv id pg_dump pg_restore; do command -v "$tool" >/dev/null 2>&1 || { echo "Required local-upgrade tool is missing: $tool" >&2; exit 127; }; done',
     "tail -n 0 -- /dev/null >/dev/null 2>&1 || { echo 'A tail implementation with -n and -- support is required' >&2; exit 1; }",
     "systemd-run --help | grep -Eq -- '(^|[[:space:]])--collect([=[:space:]]|$)' || { echo 'systemd-run --collect is required' >&2; exit 1; }",
     "test -d /run/lock || { echo '/run/lock is unavailable' >&2; exit 1; }",
@@ -27839,12 +27945,19 @@ async function completedUpgradeOutput(ssh, paths) {
   } catch (error) {
     throw remoteReconciliationFailure("Upgrade succeeded but its retained log could not be read", [error], paths);
   }
+  let safetyEvidence;
+  try {
+    safetyEvidence = parseControlPlaneSafetyEvidence(log);
+  } catch (error) {
+    throw remoteReconciliationFailure("Upgrade succeeded but control-plane safety evidence is invalid", [error], paths);
+  }
   try {
     await cleanupRemoteRecords(ssh, paths);
   } catch (error) {
     throw remoteReconciliationFailure("Upgrade succeeded but remote evidence cleanup could not be confirmed", [error], paths);
   }
   return `✅ Upgrade done
+${JSON.stringify(safetyEvidence)}
 ${log.slice(-1500)}`;
 }
 async function throwRemoteUpgradeFailure(ssh, paths, status) {
@@ -27908,6 +28021,7 @@ async function awaitRemoteUpgrade(ssh, paths) {
   }
 }
 async function executeLocalUpgradeTransfer(ssh, request) {
+  assertControlPlaneSafetyVersion(request.managementVersion);
   const runId = randomUUID3();
   const paths = buildRemoteUpgradePaths(runId);
   const preflight = await remoteUpgradePreflight(ssh);
@@ -29367,7 +29481,7 @@ function isPlainRecord(candidate) {
   const prototype = Object.getPrototypeOf(candidate);
   return prototype === Object.prototype || prototype === null;
 }
-function canonicalTimestamp(candidate) {
+function canonicalTimestamp2(candidate) {
   if (typeof candidate !== "string")
     return false;
   const timestamp = new Date(candidate);
@@ -29384,7 +29498,7 @@ function validBackupDatabase(candidate) {
   return typeof candidate.database === "string" && SAFE_DATABASE.test(candidate.database);
 }
 function validBackupTimestamps(candidate) {
-  return canonicalTimestamp(candidate.created_at) && canonicalTimestamp(candidate.completed_at) && new Date(candidate.completed_at).valueOf() >= new Date(candidate.created_at).valueOf();
+  return canonicalTimestamp2(candidate.created_at) && canonicalTimestamp2(candidate.completed_at) && new Date(candidate.completed_at).valueOf() >= new Date(candidate.created_at).valueOf();
 }
 function validBackupEvidence(candidate) {
   return Number.isSafeInteger(candidate.bytes) && Number(candidate.bytes) > 0 && typeof candidate.sha256 === "string" && SHA256.test(candidate.sha256);
@@ -30273,7 +30387,7 @@ function matchingText(candidate, maxLength, pattern) {
   const candidateText = boundedText(candidate, maxLength);
   return candidateText && pattern.test(candidateText) ? candidateText : null;
 }
-function canonicalTimestamp2(candidate) {
+function canonicalTimestamp3(candidate) {
   const timestamp = boundedText(candidate, 64);
   if (!timestamp)
     return null;
@@ -30288,7 +30402,7 @@ function projectedSummary(project) {
     organization_slug: matchingText(project.organization_slug, 128, SAFE_IDENTIFIER_PATTERN),
     name: boundedText(project.name, 100),
     region: matchingText(project.region, 64, REGION_PATTERN),
-    created_at: canonicalTimestamp2(project.created_at),
+    created_at: canonicalTimestamp3(project.created_at),
     status: matchingText(project.status, 64, STATUS_PATTERN)
   };
   return Object.values(summary).every((field) => field !== null) ? summary : null;
@@ -31612,7 +31726,7 @@ function releaseRecord(candidate) {
     "created_at",
     "kind"
   ];
-  if (!exactKeys(record, keys) || record.schema !== "supacloud.frontend-release.v1" || typeof record.project_ref !== "string" || !PROJECT_REF_PATTERN3.test(record.project_ref) || typeof record.deployment_id !== "string" || !DEPLOYMENT_ID_PATTERN.test(record.deployment_id) || typeof record.release_id !== "string" || !RELEASE_ID_PATTERN.test(record.release_id) || record.sha256 !== record.release_id || typeof record.tree_sha256 !== "string" || !RELEASE_ID_PATTERN.test(record.tree_sha256) || !Number.isSafeInteger(record.size_bytes) || Number(record.size_bytes) < 1 || !Number.isSafeInteger(record.file_count) || Number(record.file_count) < 1 || !canonicalTimestamp3(record.created_at) || record.kind !== "prebuilt_static")
+  if (!exactKeys(record, keys) || record.schema !== "supacloud.frontend-release.v1" || typeof record.project_ref !== "string" || !PROJECT_REF_PATTERN3.test(record.project_ref) || typeof record.deployment_id !== "string" || !DEPLOYMENT_ID_PATTERN.test(record.deployment_id) || typeof record.release_id !== "string" || !RELEASE_ID_PATTERN.test(record.release_id) || record.sha256 !== record.release_id || typeof record.tree_sha256 !== "string" || !RELEASE_ID_PATTERN.test(record.tree_sha256) || !Number.isSafeInteger(record.size_bytes) || Number(record.size_bytes) < 1 || !Number.isSafeInteger(record.file_count) || Number(record.file_count) < 1 || !canonicalTimestamp4(record.created_at) || record.kind !== "prebuilt_static")
     return null;
   return {
     project_ref: record.project_ref,
@@ -31635,7 +31749,7 @@ function releaseEnvelope(candidate, expected) {
     return null;
   return release;
 }
-function canonicalTimestamp3(candidate) {
+function canonicalTimestamp4(candidate) {
   if (typeof candidate !== "string" || !TIMESTAMP_PATTERN.test(candidate))
     return false;
   const milliseconds = Date.parse(candidate);
@@ -32040,7 +32154,7 @@ Actions: list_releases, get_release, upload_release, activate_release`, {
 // package.json
 var package_default = {
   name: "@supacloud/admin",
-  version: "0.15.1",
+  version: "0.15.3",
   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.1",
+  "version": "0.15.3",
   "description": "Platform administration CLI for SupaCloud operators",
   "type": "module",
   "main": "./dist/index.js",