@supacloud/admin 0.12.1 → 0.14.1

package/README.md

@@ -59,6 +59,30 @@ npx @supacloud/admin --env production ssh upgrade \
   --confirm-production host:production.example.com:2201
 ```
 
+Immutable prebuilt frontend releases use a content-addressed ZIP and an explicit
+compare-and-swap activation. Upload and activation are separate writes, and
+production requires the exact project ref confirmation:
+
+```bash
+supacloud-admin frontend list_releases --ref abc123 --id web
+supacloud-admin frontend get_release --ref abc123 --id web --release_id <sha256>
+supacloud-admin frontend upload_release --ref abc123 --id web \
+  --zip_path /secure/site.zip --confirm-production abc123
+supacloud-admin frontend activate_release --ref abc123 --id web \
+  --release_id <sha256> --expected_active_release_id absent \
+  --expected_activation_id absent --mutation_id <uuid-v4> \
+  --confirm-production abc123
+```
+
+The CLI reads the archive through a no-follow file descriptor, verifies its
+identity and SHA-256 before upload, validates bounded Management API receipts,
+and reads the immutable release or active inventory back before reporting
+success. Reuse the same `mutation_id` only when retrying the exact activation.
+Listing and release readback work on every Management API platform. Upload and
+activation mutations require the Linux held-directory-FD implementation; on
+other platforms, Management API returns HTTP 503 before it reads the upload
+body, creates release directories, or writes a mutation journal.
+
 SSH host keys are fail-closed: setting `SUPACLOUD_HOST` and credentials is not
 enough to enable SSH actions. Obtain the fingerprint through a trusted channel,
 compare it out of band, then set it explicitly. For example, the discovery
@@ -133,8 +157,9 @@ upload-drop paths for reconciliation. Inspect that evidence before retrying and
 do not retry blindly while the remote transaction may still be running.
 
 `--artifact_transport local` accepts only `--github_proxy direct` or `none` and
-clears proxy environment variables on both hosts. The legacy server-download
-path remains available as `--artifact_transport remote`.
+clears proxy environment variables on both hosts. The server-download path
+remains available as `--artifact_transport remote`; it verifies and executes
+the target Management release as the runner even for Management-only upgrades.
 
 With `--artifact_transport remote` (the default), omitting
 `--edge_runtime_version` retains the Management and Web Console-only upgrade
@@ -151,14 +176,10 @@ command may finish later and then run its own cleanup. Reconcile the reported
 helper and trusted-root paths and read back deployed versions before deciding
 whether to retry.
 
-After a capable Management release is active, an exact rollback can use that
-active upgrader with explicit older targets, for example:
-
-```bash
-npx @supacloud/admin ssh upgrade \
-  --version 0.50.26 \
-  --edge_runtime_version 0.16.6
-```
+Targets predating the target-bound systemd-unit helper identity command are
+rejected before mutation. A failed transaction still restores its exact frozen
+prior Management/helper/Web identities; an intentional downgrade to a legacy
+release requires a separately reviewed compatibility procedure.
 
 Project commands owned by this CLI:
 
@@ -249,6 +270,47 @@ The JSON receipt contains only the project ref, requested type, backup ID,
 database, timestamps, and size. `platform list_backups --ref abc123` applies the
 same strict, sanitized inventory validation without creating a backup.
 
+## Verified logical backups
+
+Use the official Admin CLI to list or create project-scoped verified logical
+backups:
+
+```bash
+supacloud-admin platform list_logical_backups --ref abc123
+supacloud-admin platform create_logical_backup --ref abc123
+```
+
+The create command reads the verified inventory before and after the one-shot
+request. It reports success only when the Management response and exactly one
+new inventory identity agree on the project, database, backup ID, kind,
+timestamps, byte count, and SHA-256. The fixed JSON projection never includes
+the server's receipt HMAC, archive path, subprocess output, or response-only
+fields. Do not retry an `OUTCOME_UNKNOWN` create until the inventory has been
+reconciled.
+
+Logical restore is destructive and Management also requires the project to be
+paused. Copy an exact identity from `list_logical_backups`, then bind all of its
+recovery-critical fields:
+
+```bash
+supacloud-admin platform restore_logical_backup \
+  --ref abc123 \
+  --backup_id logical-full_abc123_0123456789abcdef0123456789abcdef \
+  --expected_sha256 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \
+  --confirmation RESTORE_PROJECT:abc123:logical-full_abc123_0123456789abcdef0123456789abcdef:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+```
+
+Both create and restore are classified as remote writes. They require an
+explicit `SUPACLOUD_ENV`, honor `SUPACLOUD_READ_ONLY=true`, and in production
+also require the global exact project confirmation
+`--confirm-production abc123`. A timeout, transport loss, 5xx response, or
+malformed success receipt exits non-zero without reflecting the remote body.
+Logical mutation requests have a bounded 36-minute client deadline so the
+Management request has time to return a terminal response before the client
+gives up.
+Credentials remain environment-only; logical backup commands accept no token,
+password, or service-role flags.
+
 Gateway / Caddy commands (config is injected via the Caddy JSON Admin API; requires admin privileges):
 
 - `gateway routes` — list custom gateway routes

package/dist/index.js

@@ -4759,7 +4759,7 @@ var require_utils = __commonJS((exports, module) => {
 
 // node_modules/ssh2/lib/protocol/crypto/build/Release/sshcrypto.node
 var require_sshcrypto = __commonJS((exports, module) => {
-  module.exports = __require("./sshcrypto-8m50vnmb.node");
+  module.exports = __require("./sshcrypto-vd2k5hq9.node");
 });
 
 // node_modules/ssh2/lib/protocol/crypto/poly1305.js
@@ -12196,7 +12196,7 @@ var require_SFTP = __commonJS((exports, module) => {
   var fs = __require("fs");
   var { constants } = fs;
   var {
-    Readable: ReadableStream,
+    Readable: ReadableStream2,
     Writable: WritableStream
   } = __require("stream");
   var { inherits, types: { isDate } } = __require("util");
@@ -14807,7 +14807,7 @@ var require_SFTP = __commonJS((exports, module) => {
       options.highWaterMark = 64 * 1024;
     options.emitClose = false;
     options.autoDestroy = false;
-    ReadableStream.call(this, options);
+    ReadableStream2.call(this, options);
     this.path = path;
     this.flags = options.flags === undefined ? "r" : options.flags;
     this.mode = options.mode === undefined ? 438 : options.mode;
@@ -14839,7 +14839,7 @@ var require_SFTP = __commonJS((exports, module) => {
     if (!Buffer.isBuffer(this.handle))
       this.open();
   }
-  inherits(ReadStream, ReadableStream);
+  inherits(ReadStream, ReadableStream2);
   ReadStream.prototype.open = function() {
     if (this._opening)
       return;
@@ -15097,7 +15097,7 @@ var require_SFTP = __commonJS((exports, module) => {
 var require_Channel = __commonJS((exports, module) => {
   var {
     Duplex: DuplexStream,
-    Readable: ReadableStream,
+    Readable: ReadableStream2,
     Writable: WritableStream
   } = __require("stream");
   var {
@@ -15108,7 +15108,7 @@ var require_Channel = __commonJS((exports, module) => {
   var MAX_WINDOW = 2 * 1024 * 1024;
   var WINDOW_THRESHOLD = MAX_WINDOW / 2;
 
-  class ClientStderr extends ReadableStream {
+  class ClientStderr extends ReadableStream2 {
     constructor(channel, streamOpts) {
       super(streamOpts);
       this._channel = channel;
@@ -18848,7 +18848,7 @@ var require_lib3 = __commonJS((exports, module) => {
 });
 
 // src/index.ts
-import { resolve as resolve3 } from "node:path";
+import { resolve as resolve4 } from "node:path";
 import { fileURLToPath } from "node:url";
 import { realpathSync } from "node:fs";
 
@@ -25802,8 +25802,8 @@ var ACTION_POLICY = {
     write: ["create", "delete", "pause", "restore", "restart", "update_settings"]
   },
   platform: {
-    read: ["metrics", "list_backups", "network", "list_orgs", "get_org"],
-    write: ["create_backup", "update_network"]
+    read: ["metrics", "list_backups", "list_logical_backups", "network", "list_orgs", "get_org"],
+    write: ["create_backup", "create_logical_backup", "restore_logical_backup", "update_network"]
   },
   gateway: {
     read: ["routes", "get_certificate", "custom_hostname"],
@@ -25821,6 +25821,10 @@ var ACTION_POLICY = {
       "verify_custom_hostname"
     ]
   },
+  frontend: {
+    read: ["list_releases", "get_release"],
+    write: ["upload_release", "activate_release"]
+  },
   ssh: {
     read: [
       "ping",
@@ -25850,6 +25854,9 @@ var SSH_PROJECT_REF_ACTIONS = new Set(["tenant_manage", "tenant_inspect", "tenan
 var PLATFORM_PROJECT_REF_ACTIONS = new Set([
   "list_backups",
   "create_backup",
+  "list_logical_backups",
+  "create_logical_backup",
+  "restore_logical_backup",
   "network",
   "update_network"
 ]);
@@ -25898,7 +25905,7 @@ function requestedProjectRef(moduleName, action, args) {
   if (moduleName === "platform") {
     return PLATFORM_PROJECT_REF_ACTIONS.has(action) ? stringArgument(args, "ref") : null;
   }
-  return moduleName === "gateway" ? stringArgument(args, "ref") : null;
+  return ["gateway", "frontend"].includes(moduleName) ? stringArgument(args, "ref") : null;
 }
 function requiresProjectRef(moduleName, action) {
   return !REFLESS_WRITE_ACTIONS.has(`${moduleName}.${action}`);
@@ -26010,7 +26017,7 @@ function validateExecutionPolicyCoverage(tools) {
 
 // src/shared/transports/http.ts
 var DEFAULT_TIMEOUT = 30000;
-var MAX_POST_TIMEOUT_MS = 35 * 60000;
+var MAX_POST_TIMEOUT_MS = 36 * 60000;
 var MAX_RETRIES = 2;
 var RETRY_BASE_DELAY = 500;
 function isRetryableMethod(method) {
@@ -26206,14 +26213,59 @@ class HttpTransport {
   }
   async post(path, body, options) {
     const timeoutMs = validatedPostTimeout(options);
+    const maxJsonBytes = validatedStrictJsonLimit({ maxJsonBytes: options?.maxJsonBytes });
+    let response;
     try {
-      const res = await fetchWithRetry(`${this.baseUrl}${path}`, {
+      response = await fetchWithRetry(`${this.baseUrl}${path}`, {
         method: "POST",
         headers: this.headers(),
         body: body ? JSON.stringify(body) : undefined
       }, timeoutMs);
-      const data = await res.json().catch(() => null);
-      return { ok: res.ok, status: res.status, data };
+    } catch (error) {
+      return transportFailure(error);
+    }
+    if (maxJsonBytes !== undefined) {
+      try {
+        const data2 = await strictBoundedResponseJson(response, maxJsonBytes);
+        return { ok: response.ok, status: response.status, data: data2 };
+      } catch {
+        return responseBodyFailure(response.status);
+      }
+    }
+    const data = await response.json().catch(() => null);
+    return { ok: response.ok, status: response.status, data };
+  }
+  async postBinary(path, body, options) {
+    if (options.contentType !== "application/zip") {
+      throw new Error("Binary HTTP content type is invalid");
+    }
+    if (!Number.isSafeInteger(options.contentLength) || options.contentLength < 1 || options.contentLength !== body.byteLength) {
+      throw new RangeError("Binary HTTP body length is invalid");
+    }
+    if (!/^[0-9a-f]{64}$/u.test(options.contentSha256)) {
+      throw new Error("Binary HTTP body SHA-256 is invalid");
+    }
+    const maxJsonBytes = validatedStrictJsonLimit({ maxJsonBytes: options.maxJsonBytes });
+    const timeoutMs = validatedPostTimeout(options.timeoutMs === undefined ? undefined : { timeoutMs: options.timeoutMs });
+    try {
+      const request = {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${this.token}`,
+          "Content-Type": options.contentType,
+          "Content-Length": String(options.contentLength),
+          "x-supacloud-content-sha256": options.contentSha256
+        },
+        body: body.stream,
+        duplex: "half"
+      };
+      const response = await fetchWithRetry(`${this.baseUrl}${path}`, request, timeoutMs);
+      try {
+        const data = await strictBoundedResponseJson(response, maxJsonBytes);
+        return { ok: response.ok, status: response.status, data };
+      } catch {
+        return responseBodyFailure(response.status);
+      }
     } catch (error) {
       return transportFailure(error);
     }
@@ -27422,6 +27474,7 @@ function upgradeScriptExecution(paths, bundle, request) {
     'install -m 0755 "$RUNNER_ASSET" "$RUNNER"',
     `test "$(sha256sum "$RUNNER"|awk '{print $1}')" = "$(sha256sum "$RUNNER_ASSET"|awk '{print $1}')"`,
     '"$RUNNER" --version | grep -Eq "(^|[^0-9])${MANAGEMENT_VERSION//./\\.}([^0-9]|$)"',
+    `timeout 5s "$RUNNER" --systemd-unit-helper-sha256 | grep -Eq 'SupaCloud systemd-unit helper SHA-256: [0-9a-f]{64}'`,
     `env PATH="$VERIFIER_PATH:$PATH" "$RUNNER" upgrade --yes --target-version ${quoteShell2(request.managementVersion)} --edge-runtime-version ${quoteShell2(request.edgeRuntimeVersion)} --asset-bundle-dir "$BUNDLE"`
   ];
 }
@@ -28008,30 +28061,27 @@ function assertExactStableVersion2(value, fieldName) {
   }
   return value;
 }
-function upgradeEnvAssignments(request) {
+function upgradeTransactionEnvAssignments(request) {
   return [
-    request.version ? `SUPACLOUD_UPGRADE_TAG=${quoteEnvValue(request.version)}` : "",
+    'SUPACLOUD_UPGRADE_TAG="$TARGET_MANAGEMENT_VERSION"',
     request.edgeRuntimeVersion ? `SUPACLOUD_EDGE_RUNTIME_UPGRADE_TAG=${quoteEnvValue(request.edgeRuntimeVersion)}` : "",
     request.githubProxy ? `SUPACLOUD_GITHUB_PROXY=${quoteEnvValue(request.githubProxy)}` : ""
   ].filter(Boolean).join(" ");
 }
 function componentBootstrapCommands(request) {
-  if (!request.edgeRuntimeVersion)
-    return [`UPGRADE_RUNNER=${quoteEnvValue("/usr/local/bin/supacloud")}`];
   const managementVersion = request.version || "latest";
   return [
-    `ACTIVE_VERSION=$(/usr/local/bin/supacloud --version 2>&1 | grep -Eo '[0-9]+\\.[0-9]+\\.[0-9]+' | head -1 || true)`,
-    `UPGRADE_RUNNER=${quoteEnvValue("/usr/local/bin/supacloud")}`,
-    `if ! supacloud_version_at_least "$ACTIVE_VERSION" ${quoteEnvValue(MINIMUM_COMPONENT_UPGRADE_VERSION)}; then`,
-    `  case "$(uname -m)" in x86_64|amd64) MANAGEMENT_ASSET=supacloud-linux-amd64 ;; aarch64|arm64) MANAGEMENT_ASSET=supacloud-linux-arm64 ;; *) echo 'Unsupported Management architecture' >&2; exit 1 ;; esac`,
-    `  STAGED_MANAGEMENT=$(mktemp /tmp/supacloud-management-upgrade.XXXXXX)`,
-    `  MANAGEMENT_RELEASE=$(supacloud_fetch_component_release management-api ${quoteEnvValue(managementVersion)} "$MANAGEMENT_ASSET" web-console-build.tar.gz)`,
-    `  supacloud_download_release_asset "$MANAGEMENT_RELEASE" "$MANAGEMENT_ASSET" "$STAGED_MANAGEMENT" binary`,
-    `  chmod 0755 "$STAGED_MANAGEMENT"`,
-    `  STAGED_VERSION=$("$STAGED_MANAGEMENT" --version 2>&1 | grep -Eo '[0-9]+\\.[0-9]+\\.[0-9]+' | head -1 || true)`,
-    `  supacloud_version_at_least "$STAGED_VERSION" ${quoteEnvValue(MINIMUM_COMPONENT_UPGRADE_VERSION)} || { echo 'Target Management release lacks Edge Runtime transaction capability' >&2; exit 1; }`,
-    `  UPGRADE_RUNNER="$STAGED_MANAGEMENT"`,
-    "fi"
+    `case "$(uname -m)" in x86_64|amd64) MANAGEMENT_ASSET=supacloud-linux-amd64 ;; aarch64|arm64) MANAGEMENT_ASSET=supacloud-linux-arm64 ;; *) echo 'Unsupported Management architecture' >&2; exit 1 ;; esac`,
+    `STAGED_MANAGEMENT=$(mktemp /tmp/supacloud-management-upgrade.XXXXXX)`,
+    `MANAGEMENT_RELEASE=$(supacloud_fetch_component_release management-api ${quoteEnvValue(managementVersion)} "$MANAGEMENT_ASSET" web-console-build.tar.gz)`,
+    `supacloud_download_release_asset "$MANAGEMENT_RELEASE" "$MANAGEMENT_ASSET" "$STAGED_MANAGEMENT" binary`,
+    `chmod 0755 "$STAGED_MANAGEMENT"`,
+    `TARGET_MANAGEMENT_VERSION=$(jq -er '.tag_name | capture("^management-api-v(?<version>(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*))$").version' <<< "$MANAGEMENT_RELEASE")`,
+    `STAGED_VERSION=$("$STAGED_MANAGEMENT" --version 2>&1 | grep -Eo '[0-9]+\\.[0-9]+\\.[0-9]+' | head -1 || true)`,
+    `test "$STAGED_VERSION" = "$TARGET_MANAGEMENT_VERSION" || { echo 'Target Management binary version does not match its verified release' >&2; exit 1; }`,
+    `supacloud_version_at_least "$STAGED_VERSION" ${quoteEnvValue(MINIMUM_COMPONENT_UPGRADE_VERSION)} || { echo 'Target Management release lacks component transaction capability' >&2; exit 1; }`,
+    `"$STAGED_MANAGEMENT" --systemd-unit-helper-sha256 >/dev/null 2>&1 || { echo 'Target Management release lacks target-bound systemd-unit helper delivery' >&2; exit 1; }`,
+    `UPGRADE_RUNNER="$STAGED_MANAGEMENT"`
   ];
 }
 function componentPreflightCommands(request) {
@@ -28069,7 +28119,7 @@ function trustedRootPreflightCommands(helperPath) {
   ];
 }
 function buildRootUpgradeScript(request) {
-  const envAssignments = upgradeEnvAssignments(request);
+  const envAssignments = upgradeTransactionEnvAssignments(request);
   return [
     "set -euo pipefail",
     "umask 077",
@@ -28090,7 +28140,7 @@ function buildRootUpgradeScript(request) {
     "if ! supacloud_attestation_verifier_available; then supacloud_install_pinned_gh /usr/local/bin/gh; fi",
     "supacloud_attestation_verifier_available || { echo 'Pinned GitHub attestation verifier is unavailable' >&2; exit 1; }",
     ...componentBootstrapCommands(request),
-    `${envAssignments ? `env ${envAssignments} ` : ""}"$UPGRADE_RUNNER" upgrade --yes`
+    `env ${envAssignments} "$UPGRADE_RUNNER" upgrade --yes`
   ].join(`
 `);
 }
@@ -29224,6 +29274,238 @@ async function createFullPhysicalBackup(http, projectRef) {
   return reconciledCreationResponse(projectRef, beforeRead.inventory, creation, afterRead);
 }
 
+// src/shared/tools/logical-backup-control.ts
+var RELEASE_CONTROL_RESPONSE_SCHEMA = "supacloud.cli.release-control.v1";
+var SAFE_PROJECT_REF2 = /^[A-Za-z0-9_-]{1,64}$/;
+var BACKUP_ID = /^logical-full_[A-Za-z0-9_-]{1,64}_[a-f0-9]{32}$/;
+var BACKUP_ID_SUFFIX = /^[a-f0-9]{32}$/;
+var SHA256 = /^[a-f0-9]{64}$/;
+var SAFE_DATABASE = /^[^\u0000-\u001f\u007f]{1,128}$/;
+var LOGICAL_BACKUP_REQUEST_TIMEOUT_MS = 36 * 60000;
+var LOGICAL_BACKUP_INVENTORY_MAX_BYTES = 1024 * 1024;
+var LOGICAL_BACKUP_MUTATION_MAX_BYTES = 64 * 1024;
+function logicalBackupResponse(payload) {
+  return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
+}
+function logicalBackupSuccess(operation, payload) {
+  return logicalBackupResponse({
+    ...payload,
+    schema: RELEASE_CONTROL_RESPONSE_SCHEMA,
+    ok: true,
+    operation
+  });
+}
+function logicalBackupFailure(operation, code, httpStatus) {
+  return {
+    ...logicalBackupResponse({
+      schema: RELEASE_CONTROL_RESPONSE_SCHEMA,
+      ok: false,
+      operation,
+      error: { code, http_status: httpStatus }
+    }),
+    isError: true
+  };
+}
+function isPlainRecord(candidate) {
+  if (candidate === null || typeof candidate !== "object" || Array.isArray(candidate))
+    return false;
+  const prototype = Object.getPrototypeOf(candidate);
+  return prototype === Object.prototype || prototype === null;
+}
+function canonicalTimestamp(candidate) {
+  if (typeof candidate !== "string")
+    return false;
+  const timestamp = new Date(candidate);
+  return Number.isFinite(timestamp.valueOf()) && timestamp.toISOString() === candidate;
+}
+function backupBelongsToProject(backupId, projectRef) {
+  const prefix = `logical-full_${projectRef}_`;
+  return BACKUP_ID.test(backupId) && backupId.startsWith(prefix) && BACKUP_ID_SUFFIX.test(backupId.slice(prefix.length));
+}
+function validBackupProject(candidate, projectRef) {
+  return typeof candidate.backup_id === "string" && backupBelongsToProject(candidate.backup_id, projectRef) && candidate.project_ref === projectRef;
+}
+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();
+}
+function validBackupEvidence(candidate) {
+  return Number.isSafeInteger(candidate.bytes) && Number(candidate.bytes) > 0 && typeof candidate.sha256 === "string" && SHA256.test(candidate.sha256);
+}
+function logicalBackupIdentity(candidate, projectRef) {
+  if (!isPlainRecord(candidate))
+    return null;
+  if (!validBackupProject(candidate, projectRef) || !validBackupDatabase(candidate) || candidate.kind !== "logical-full" || !validBackupTimestamps(candidate) || !validBackupEvidence(candidate)) {
+    return null;
+  }
+  return {
+    backup_id: candidate.backup_id,
+    project_ref: projectRef,
+    database: candidate.database,
+    kind: "logical-full",
+    created_at: candidate.created_at,
+    completed_at: candidate.completed_at,
+    bytes: Number(candidate.bytes),
+    sha256: candidate.sha256
+  };
+}
+function logicalBackupInventory(payload, projectRef) {
+  if (!isPlainRecord(payload) || !Array.isArray(payload.backups))
+    return null;
+  const backups = payload.backups.map((candidate) => logicalBackupIdentity(candidate, projectRef));
+  if (backups.some((backup) => backup === null))
+    return null;
+  const inventory = backups;
+  if (new Set(inventory.map((backup) => backup.backup_id)).size !== inventory.length)
+    return null;
+  return inventory;
+}
+function assertProjectRef(projectRef) {
+  if (!SAFE_PROJECT_REF2.test(projectRef)) {
+    throw new Error("'ref' is invalid for verified logical backup");
+  }
+}
+function logicalBackupEndpoint(projectRef) {
+  assertProjectRef(projectRef);
+  return `/v1/projects/${encodeURIComponent(projectRef)}/database/backups/logical`;
+}
+async function readLogicalBackupInventory(http, projectRef) {
+  const response = await http.get(logicalBackupEndpoint(projectRef), {
+    maxJsonBytes: LOGICAL_BACKUP_INVENTORY_MAX_BYTES
+  });
+  return {
+    response,
+    inventory: response.ok ? logicalBackupInventory(response.data, projectRef) ?? undefined : undefined
+  };
+}
+function mutationFailureCode2(response) {
+  return response.transportError || response.responseError || response.status === 408 || response.status >= 500 ? "OUTCOME_UNKNOWN" : "HTTP_ERROR";
+}
+function identicalBackup(left, right) {
+  return left.backup_id === right.backup_id && left.project_ref === right.project_ref && left.database === right.database && left.kind === right.kind && left.created_at === right.created_at && left.completed_at === right.completed_at && left.bytes === right.bytes && left.sha256 === right.sha256;
+}
+function createdBackup(previous, current) {
+  const currentById = new Map(current.map((backup) => [backup.backup_id, backup]));
+  const previousIds = new Set;
+  for (const previousBackup of previous) {
+    previousIds.add(previousBackup.backup_id);
+    const currentBackup = currentById.get(previousBackup.backup_id);
+    if (!currentBackup || !identicalBackup(previousBackup, currentBackup))
+      return null;
+  }
+  const additions = current.filter((backup) => !previousIds.has(backup.backup_id));
+  return additions.length === 1 ? additions[0] : null;
+}
+function exactBackupEnvelope(payload, field, projectRef) {
+  return isPlainRecord(payload) ? logicalBackupIdentity(payload[field], projectRef) : null;
+}
+function inventoryReadFailure(operation, read) {
+  const { response, inventory } = read;
+  if (!response.ok || response.status !== 200) {
+    const code = response.ok || response.responseError ? "INVALID_RESPONSE" : "HTTP_ERROR";
+    const status = response.transportError ? null : response.status;
+    return logicalBackupFailure(operation, code, status);
+  }
+  return inventory ? null : logicalBackupFailure(operation, "INVALID_RESPONSE", response.status);
+}
+function createReceipt(projectRef, previous, mutation, afterRead) {
+  const operation = "platform.create_logical_backup";
+  if (!mutation.ok) {
+    const status = mutation.transportError ? null : mutation.status;
+    return logicalBackupFailure(operation, mutationFailureCode2(mutation), status);
+  }
+  if (mutation.status !== 200)
+    return logicalBackupFailure(operation, "OUTCOME_UNKNOWN", mutation.status);
+  const responseBackup = exactBackupEnvelope(mutation.data, "backup", projectRef);
+  const addedBackup = afterRead.response.ok && afterRead.response.status === 200 && afterRead.inventory ? createdBackup(previous, afterRead.inventory) : null;
+  if (!responseBackup || !addedBackup || !identicalBackup(responseBackup, addedBackup)) {
+    return logicalBackupFailure(operation, "OUTCOME_UNKNOWN", mutation.status);
+  }
+  return logicalBackupSuccess(operation, { project_ref: projectRef, backup: addedBackup });
+}
+async function listVerifiedLogicalBackups(http, projectRef) {
+  const operation = "platform.list_logical_backups";
+  const read = await readLogicalBackupInventory(http, projectRef);
+  const failure = inventoryReadFailure(operation, read);
+  return failure ?? logicalBackupSuccess(operation, {
+    project_ref: projectRef,
+    backups: read.inventory
+  });
+}
+async function createVerifiedLogicalBackup(http, projectRef) {
+  const operation = "platform.create_logical_backup";
+  const beforeRead = await readLogicalBackupInventory(http, projectRef);
+  const failure = inventoryReadFailure(operation, beforeRead);
+  if (failure)
+    return failure;
+  const mutation = await http.post(logicalBackupEndpoint(projectRef), {}, {
+    timeoutMs: LOGICAL_BACKUP_REQUEST_TIMEOUT_MS,
+    maxJsonBytes: LOGICAL_BACKUP_MUTATION_MAX_BYTES
+  });
+  const afterRead = await readLogicalBackupInventory(http, projectRef);
+  return createReceipt(projectRef, beforeRead.inventory, mutation, afterRead);
+}
+function expectedRestoreConfirmation(request) {
+  return [
+    "RESTORE_PROJECT",
+    request.projectRef,
+    request.backupId,
+    request.expectedSha256
+  ].join(":");
+}
+function assertRestoreRequest(request) {
+  assertProjectRef(request.projectRef);
+  if (!backupBelongsToProject(request.backupId, request.projectRef)) {
+    throw new Error("'backup_id' must belong to the requested project");
+  }
+  if (!SHA256.test(request.expectedSha256)) {
+    throw new Error("'expected_sha256' must be exactly 64 lowercase hexadecimal characters");
+  }
+  if (request.confirmation !== expectedRestoreConfirmation(request)) {
+    throw new Error("'confirmation' must exactly bind the project ref, backup ID, and SHA-256");
+  }
+}
+function restoreReceipt(request, requestedBackup, mutation) {
+  const operation = "platform.restore_logical_backup";
+  if (!mutation.ok) {
+    const status = mutation.transportError ? null : mutation.status;
+    return logicalBackupFailure(operation, mutationFailureCode2(mutation), status);
+  }
+  if (mutation.status !== 200)
+    return logicalBackupFailure(operation, "OUTCOME_UNKNOWN", mutation.status);
+  const restoredBackup = exactBackupEnvelope(mutation.data, "restored_backup", request.projectRef);
+  if (!restoredBackup || !identicalBackup(restoredBackup, requestedBackup)) {
+    return logicalBackupFailure(operation, "OUTCOME_UNKNOWN", mutation.status);
+  }
+  return logicalBackupSuccess(operation, {
+    project_ref: request.projectRef,
+    restored_backup: restoredBackup
+  });
+}
+async function restoreVerifiedLogicalBackup(http, request) {
+  const operation = "platform.restore_logical_backup";
+  assertRestoreRequest(request);
+  const beforeRead = await readLogicalBackupInventory(http, request.projectRef);
+  const failure = inventoryReadFailure(operation, beforeRead);
+  if (failure)
+    return failure;
+  const requestedBackup = beforeRead.inventory.find((backup) => backup.backup_id === request.backupId);
+  if (!requestedBackup || requestedBackup.sha256 !== request.expectedSha256) {
+    return logicalBackupFailure(operation, "INVALID_RESPONSE", beforeRead.response.status);
+  }
+  const mutation = await http.post(`${logicalBackupEndpoint(request.projectRef)}/restore`, {
+    backup_id: request.backupId,
+    expected_sha256: request.expectedSha256,
+    confirmation: request.confirmation
+  }, {
+    timeoutMs: LOGICAL_BACKUP_REQUEST_TIMEOUT_MS,
+    maxJsonBytes: LOGICAL_BACKUP_MUTATION_MAX_BYTES
+  });
+  return restoreReceipt(request, requestedBackup, mutation);
+}
+
 // src/shared/tools/advanced-tools.ts
 function registerAdvancedTools(server, http) {
   server.tool("edge_functions", `Edge Function management (Deno/Bun serverless). Server auto-bundles dependencies.
@@ -29367,11 +29649,14 @@ Actions: list, upsert, delete`, {
     return { content: [{ type: "text", text }] };
   });
   server.tool("platform", `Platform monitoring, backups, network, and organizations.
-Actions: metrics, list_backups, create_backup, network, update_network, list_orgs, get_org`, {
+Actions: metrics, list_backups, create_backup, list_logical_backups, create_logical_backup, restore_logical_backup, network, update_network, list_orgs, get_org`, {
     action: withDescription(stringEnum([
       "metrics",
       "list_backups",
       "create_backup",
+      "list_logical_backups",
+      "create_logical_backup",
+      "restore_logical_backup",
       "network",
       "update_network",
       "list_orgs",
@@ -29379,10 +29664,22 @@ Actions: metrics, list_backups, create_backup, network, update_network, list_org
     ]), "Action"),
     ref: optional(Type.String(), "[*] Project ref for project-scoped platform actions"),
     backup_type: optional(stringEnum(["full"]), "[create_backup] Explicit physical backup type"),
+    backup_id: optional(Type.String(), "[restore_logical_backup] Verified logical backup ID"),
+    expected_sha256: optional(Type.String(), "[restore_logical_backup] Exact lowercase backup SHA-256"),
+    confirmation: optional(Type.String(), "[restore_logical_backup] Exact RESTORE_PROJECT:<ref>:<backup_id>:<sha256> confirmation"),
     slug: optional(Type.String(), "[get_org] Organization slug"),
     allowed_cidrs: optional(Type.Array(Type.String()), "[update_network] Allowed CIDRs")
   }, async (args) => {
-    const { action, ref, backup_type, slug, allowed_cidrs } = args;
+    const {
+      action,
+      ref,
+      backup_type,
+      backup_id,
+      expected_sha256,
+      confirmation,
+      slug,
+      allowed_cidrs
+    } = args;
     const need = (f, v) => {
       if (!v)
         throw new Error(`'${f}' required for '${action}'`);
@@ -29400,6 +29697,23 @@ Actions: metrics, list_backups, create_backup, network, update_network, list_org
         need("backup_type", backup_type);
         return createFullPhysicalBackup(http, ref);
       }
+      case "list_logical_backups":
+        need("ref", ref);
+        return listVerifiedLogicalBackups(http, ref);
+      case "create_logical_backup":
+        need("ref", ref);
+        return createVerifiedLogicalBackup(http, ref);
+      case "restore_logical_backup":
+        need("ref", ref);
+        need("backup_id", backup_id);
+        need("expected_sha256", expected_sha256);
+        need("confirmation", confirmation);
+        return restoreVerifiedLogicalBackup(http, {
+          projectRef: ref,
+          backupId: backup_id,
+          expectedSha256: expected_sha256,
+          confirmation
+        });
       case "network":
         need("ref", ref);
         text = JSON.stringify((await http.get(`/v1/projects/${ref}/network-restrictions`)).data, null, 2);
@@ -29904,7 +30218,7 @@ function matchingText(candidate, maxLength, pattern) {
   const candidateText = boundedText(candidate, maxLength);
   return candidateText && pattern.test(candidateText) ? candidateText : null;
 }
-function canonicalTimestamp(candidate) {
+function canonicalTimestamp2(candidate) {
   const timestamp = boundedText(candidate, 64);
   if (!timestamp)
     return null;
@@ -29919,7 +30233,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: canonicalTimestamp(project.created_at),
+    created_at: canonicalTimestamp2(project.created_at),
     status: matchingText(project.status, 64, STATUS_PATTERN)
   };
   return Object.values(summary).every((field) => field !== null) ? summary : null;
@@ -30063,7 +30377,7 @@ function projectGetRead(response, expectedRef) {
 // src/shared/tools/project-runtime-snapshot.ts
 var RUNTIME_SNAPSHOT_SCHEMA = "supacloud.runtime-snapshot.v1";
 var ATTESTED_REVISION_PATTERN = /^hmac-sha256:[a-f0-9]{64}$/;
-var SAFE_PROJECT_REF2 = /^[a-z0-9-]{1,20}$/;
+var SAFE_PROJECT_REF3 = /^[a-z0-9-]{1,20}$/;
 var SNAPSHOT_KEYS = ["schema", "project_ref", "captured_at", "secrets", "postgrest"];
 var SECRETS_KEYS = [
   "desired_revision",
@@ -30200,7 +30514,7 @@ function hasCausalLoadTimestamps(snapshot) {
   return [snapshot.secrets.loaded_at, snapshot.postgrest.loaded_at].every((loadedAt) => loadedAt === null || Date.parse(loadedAt) <= capturedAt);
 }
 function parseProjectRuntimeSnapshot(payload, requestedProjectRef2) {
-  if (!SAFE_PROJECT_REF2.test(requestedProjectRef2) || !isRecord2(payload) || !hasExactKeys(payload, SNAPSHOT_KEYS) || payload.schema !== RUNTIME_SNAPSHOT_SCHEMA || payload.project_ref !== requestedProjectRef2 || !isIsoTimestampOrNull(payload.captured_at) || payload.captured_at === null || !isRuntimeSecretsSnapshot(payload.secrets) || !isPostgrestRuntimeSnapshot(payload.postgrest, requestedProjectRef2))
+  if (!SAFE_PROJECT_REF3.test(requestedProjectRef2) || !isRecord2(payload) || !hasExactKeys(payload, SNAPSHOT_KEYS) || payload.schema !== RUNTIME_SNAPSHOT_SCHEMA || payload.project_ref !== requestedProjectRef2 || !isIsoTimestampOrNull(payload.captured_at) || payload.captured_at === null || !isRuntimeSecretsSnapshot(payload.secrets) || !isPostgrestRuntimeSnapshot(payload.postgrest, requestedProjectRef2))
     return null;
   const snapshot = payload;
   return hasCausalLoadTimestamps(snapshot) ? sanitizedSnapshot(snapshot) : null;
@@ -30237,11 +30551,11 @@ var STUDIO_PROJECT_SERVICE_STATUSES = [
 ];
 var AUTH_RUNTIME_MANAGED_BY_OWNER = "AUTH_RUNTIME_MANAGED_BY_OWNER";
 var AUTH_SERVICE_HOST_SUFFIX = "-auth";
-var SAFE_PROJECT_REF3 = /^[a-z0-9-]{1,20}$/;
+var SAFE_PROJECT_REF4 = /^[a-z0-9-]{1,20}$/;
 var SAFE_AUTHORITY_PROJECT_REF = /^[A-Za-z0-9_-]{1,20}$/;
 var MAX_SERVICE_CONTROL_MESSAGE_LENGTH = 256;
 var MAX_RUNTIME_SNAPSHOT_BYTES = 64 * 1024;
-var RELEASE_CONTROL_RESPONSE_SCHEMA = "supacloud.cli.release-control.v1";
+var RELEASE_CONTROL_RESPONSE_SCHEMA2 = "supacloud.cli.release-control.v1";
 var PROJECT_CREATE_OPERATION = "project.create";
 var PROJECT_ENVIRONMENTS = ["test", "production"];
 var DNS_LABEL = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
@@ -30269,7 +30583,7 @@ function failedProjectServiceResponse(message) {
 function projectCreateReceipt(payload) {
   return {
     content: [{ type: "text", text: JSON.stringify({
-      schema: RELEASE_CONTROL_RESPONSE_SCHEMA,
+      schema: RELEASE_CONTROL_RESPONSE_SCHEMA2,
       ...payload
     }, null, 2) }]
   };
@@ -30454,7 +30768,7 @@ function projectServiceStatusOutput(status) {
 function projectServicesResponse(projectRef, response) {
   if (!response.ok)
     return failedProjectServiceHttpResponse(response);
-  if (!SAFE_PROJECT_REF3.test(projectRef) || !Array.isArray(response.data) || response.data.length !== 5) {
+  if (!SAFE_PROJECT_REF4.test(projectRef) || !Array.isArray(response.data) || response.data.length !== 5) {
     return failedProjectServiceResponse("Project service inventory response is invalid");
   }
   if (!response.data.every((service) => isProjectServiceStatus(service, projectRef))) {
@@ -31052,10 +31366,484 @@ Actions: routes, upsert_route, update_route, delete_route, config, get_certifica
     return { content: [{ type: "text", text }] };
   });
 }
+
+// src/shared/tools/frontend-release-control.ts
+import { createHash as createHash3 } from "node:crypto";
+import { constants as fsConstants2 } from "node:fs";
+import { open as open2 } from "node:fs/promises";
+import { resolve as resolve3 } from "node:path";
+var PROJECT_REF_PATTERN2 = /^[A-Za-z0-9_-]{1,20}$/u;
+var DEPLOYMENT_ID_PATTERN = /^[A-Za-z0-9_-]{1,128}$/u;
+var RELEASE_ID_PATTERN = /^[0-9a-f]{64}$/u;
+var MUTATION_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u;
+var TIMESTAMP_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/u;
+var ARCHIVE_MAX_BYTES = 100 * 1024 * 1024;
+var ARCHIVE_CHUNK_BYTES = 64 * 1024;
+var RESPONSE_MAX_BYTES = 1024 * 1024;
+var UPLOAD_REQUEST_TIMEOUT_MS = 10 * 60000;
+var RELEASE_LIST_LIMIT_MAX = 100;
+function toolResponse(payload) {
+  return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
+}
+function releaseFailure(operation, code, status) {
+  return {
+    isError: true,
+    content: [{
+      type: "text",
+      text: JSON.stringify({ ok: false, operation, error: { code, http_status: status } })
+    }]
+  };
+}
+function exactKeys(candidate, keys) {
+  const actual = Object.keys(candidate).sort();
+  const expected = [...keys].sort();
+  return actual.length === expected.length && actual.every((key, index) => key === expected[index]);
+}
+function releaseRecord(candidate) {
+  if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
+    return null;
+  const record = candidate;
+  const keys = [
+    "schema",
+    "project_ref",
+    "deployment_id",
+    "release_id",
+    "sha256",
+    "tree_sha256",
+    "size_bytes",
+    "file_count",
+    "created_at",
+    "kind"
+  ];
+  if (!exactKeys(record, keys) || record.schema !== "supacloud.frontend-release.v1" || typeof record.project_ref !== "string" || !PROJECT_REF_PATTERN2.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")
+    return null;
+  return {
+    project_ref: record.project_ref,
+    deployment_id: record.deployment_id,
+    release_id: record.release_id,
+    sha256: record.release_id,
+    tree_sha256: record.tree_sha256,
+    size_bytes: Number(record.size_bytes),
+    file_count: Number(record.file_count),
+    created_at: record.created_at,
+    kind: "prebuilt_static"
+  };
+}
+function releaseEnvelope(candidate, expected) {
+  if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
+    return null;
+  const envelope = candidate;
+  const release = exactKeys(envelope, ["project_ref", "deployment_id", "release"]) ? releaseRecord(envelope.release) : null;
+  if (!release || envelope.project_ref !== expected.projectRef || envelope.deployment_id !== expected.deploymentId || release.project_ref !== expected.projectRef || release.deployment_id !== expected.deploymentId || release.release_id !== expected.releaseId)
+    return null;
+  return release;
+}
+function canonicalTimestamp3(candidate) {
+  if (typeof candidate !== "string" || !TIMESTAMP_PATTERN.test(candidate))
+    return false;
+  const milliseconds = Date.parse(candidate);
+  return Number.isFinite(milliseconds) && new Date(milliseconds).toISOString() === candidate;
+}
+function nullableIdentity(candidate, pattern) {
+  if (candidate === null)
+    return null;
+  return typeof candidate === "string" && pattern.test(candidate) ? candidate : undefined;
+}
+function releaseInventory(candidate, expected) {
+  if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
+    return null;
+  const record = candidate;
+  const keys = [
+    "project_ref",
+    "deployment_id",
+    "active_release_id",
+    "active_activation_id",
+    "releases",
+    "next_cursor"
+  ];
+  if (!exactKeys(record, keys) || typeof record.project_ref !== "string" || !PROJECT_REF_PATTERN2.test(record.project_ref) || typeof record.deployment_id !== "string" || !DEPLOYMENT_ID_PATTERN.test(record.deployment_id) || !Array.isArray(record.releases))
+    return null;
+  const activeReleaseId = nullableIdentity(record.active_release_id, RELEASE_ID_PATTERN);
+  const activeActivationId = nullableIdentity(record.active_activation_id, MUTATION_ID_PATTERN);
+  const nextCursor = nullableIdentity(record.next_cursor, RELEASE_ID_PATTERN);
+  const releases = record.releases.map(releaseRecord);
+  if (activeReleaseId === undefined || activeActivationId === undefined || nextCursor === undefined || activeReleaseId === null !== (activeActivationId === null) || releases.some((release) => release === null))
+    return null;
+  const verified = releases;
+  if (new Set(verified.map((release) => release.release_id)).size !== verified.length || verified.some((release) => release.project_ref !== record.project_ref || release.deployment_id !== record.deployment_id) || expected && (record.project_ref !== expected.projectRef || record.deployment_id !== expected.deploymentId))
+    return null;
+  return {
+    project_ref: record.project_ref,
+    deployment_id: record.deployment_id,
+    active_release_id: activeReleaseId,
+    active_activation_id: activeActivationId,
+    releases: verified,
+    next_cursor: nextCursor
+  };
+}
+function releaseEndpoint(projectRef, deploymentId) {
+  if (!PROJECT_REF_PATTERN2.test(projectRef))
+    throw new Error("'ref' is invalid for frontend releases");
+  if (!DEPLOYMENT_ID_PATTERN.test(deploymentId))
+    throw new Error("'id' is invalid for frontend releases");
+  return `/v1/projects/${encodeURIComponent(projectRef)}/frontend/deployments/${encodeURIComponent(deploymentId)}/releases`;
+}
+function releasePath(projectRef, deploymentId, releaseId) {
+  if (!RELEASE_ID_PATTERN.test(releaseId))
+    throw new Error("'release_id' must be a SHA-256 digest");
+  return `${releaseEndpoint(projectRef, deploymentId)}/${releaseId}`;
+}
+function sameArchiveIdentity(left, right) {
+  return left.dev === right.dev && left.ino === right.ino && left.size === right.size && left.mtimeNs === right.mtimeNs && left.ctimeNs === right.ctimeNs;
+}
+async function archiveSha256(handle, sizeBytes) {
+  const hash2 = createHash3("sha256");
+  const chunk = new Uint8Array(Math.min(sizeBytes, ARCHIVE_CHUNK_BYTES));
+  for (let offset = 0;offset < sizeBytes; ) {
+    const requested = Math.min(chunk.byteLength, sizeBytes - offset);
+    const { bytesRead } = await handle.read(chunk, 0, requested, offset);
+    if (bytesRead < 1)
+      throw new Error("Frontend release archive changed while it was hashed");
+    hash2.update(chunk.subarray(0, bytesRead));
+    offset += bytesRead;
+  }
+  return hash2.digest("hex");
+}
+async function verifiedArchive(path2) {
+  const archivePath = resolve3(path2);
+  const handle = await open2(archivePath, fsConstants2.O_RDONLY | fsConstants2.O_NOFOLLOW);
+  try {
+    const before = await handle.stat({ bigint: true });
+    const sizeBytes = Number(before.size);
+    if (!before.isFile() || sizeBytes < 1 || sizeBytes > ARCHIVE_MAX_BYTES) {
+      throw new Error(`Frontend release archive must be a 1-${ARCHIVE_MAX_BYTES} byte regular file`);
+    }
+    const sha2562 = await archiveSha256(handle, sizeBytes);
+    const after = await handle.stat({ bigint: true });
+    if (!sameArchiveIdentity(before, after)) {
+      throw new Error("Frontend release archive identity changed while it was hashed");
+    }
+    return { handle, sizeBytes, sha256: sha2562 };
+  } catch (error) {
+    await handle.close();
+    throw error;
+  }
+}
+function archiveStream(archive) {
+  let offset = 0;
+  return new ReadableStream({
+    async pull(controller) {
+      if (offset === archive.sizeBytes) {
+        controller.close();
+        return;
+      }
+      const length = Math.min(ARCHIVE_CHUNK_BYTES, archive.sizeBytes - offset);
+      const chunk = new Uint8Array(length);
+      const { bytesRead } = await archive.handle.read(chunk, 0, length, offset);
+      if (bytesRead < 1)
+        throw new Error("Frontend release archive changed while it was uploaded");
+      offset += bytesRead;
+      controller.enqueue(bytesRead === length ? chunk : chunk.subarray(0, bytesRead));
+    }
+  });
+}
+function releaseReadFailure(operation, response) {
+  return releaseFailure(operation, response.ok ? "INVALID_RESPONSE" : "HTTP_ERROR", response.status);
+}
+async function listFrontendReleases(http, projectRef, deploymentId, cursor, limit = 50) {
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > RELEASE_LIST_LIMIT_MAX) {
+    throw new Error("'limit' must be 1-100");
+  }
+  if (cursor !== undefined && !RELEASE_ID_PATTERN.test(cursor))
+    throw new Error("'cursor' is invalid");
+  const query = new URLSearchParams({ limit: String(limit) });
+  if (cursor)
+    query.set("cursor", cursor);
+  const response = await http.get(`${releaseEndpoint(projectRef, deploymentId)}?${query}`, {
+    maxJsonBytes: RESPONSE_MAX_BYTES
+  });
+  const inventory = response.ok ? releaseInventory(response.data, { projectRef, deploymentId }) : null;
+  if (!inventory || inventory.releases.length > limit) {
+    return releaseReadFailure("frontend.list_releases", response);
+  }
+  return toolResponse(inventory);
+}
+async function getFrontendRelease(http, projectRef, deploymentId, releaseId) {
+  const response = await http.get(releasePath(projectRef, deploymentId, releaseId), {
+    maxJsonBytes: RESPONSE_MAX_BYTES
+  });
+  const release = response.ok ? releaseEnvelope(response.data, { projectRef, deploymentId, releaseId }) : null;
+  if (!release) {
+    return releaseReadFailure("frontend.get_release", response);
+  }
+  return toolResponse({ project_ref: projectRef, deployment_id: deploymentId, release });
+}
+async function uploadFrontendRelease(http, projectRef, deploymentId, archivePath) {
+  const endpoint = releaseEndpoint(projectRef, deploymentId);
+  const archive = await verifiedArchive(archivePath);
+  let response;
+  try {
+    response = await http.postBinary(endpoint, {
+      stream: archiveStream(archive),
+      byteLength: archive.sizeBytes
+    }, {
+      contentType: "application/zip",
+      contentLength: archive.sizeBytes,
+      contentSha256: archive.sha256,
+      maxJsonBytes: RESPONSE_MAX_BYTES,
+      timeoutMs: UPLOAD_REQUEST_TIMEOUT_MS
+    });
+  } finally {
+    await archive.handle.close();
+  }
+  const release = response.ok ? releaseEnvelope(response.data, { projectRef, deploymentId, releaseId: archive.sha256 }) : null;
+  if (!release) {
+    if (response.status >= 400 && response.status < 500 && response.status !== 408 && !response.transportError) {
+      return releaseFailure("frontend.upload_release", "HTTP_ERROR", response.status);
+    }
+    return uploadReadback(http, projectRef, deploymentId, archive.sha256, response.status);
+  }
+  const readback = await http.get(`${endpoint}/${release.release_id}`, { maxJsonBytes: RESPONSE_MAX_BYTES });
+  const verified = readback.ok ? releaseEnvelope(readback.data, { projectRef, deploymentId, releaseId: release.release_id }) : null;
+  if (!verified || verified.tree_sha256 !== release.tree_sha256) {
+    return releaseFailure("frontend.upload_release", "OUTCOME_UNKNOWN", readback.status);
+  }
+  return toolResponse({ project_ref: projectRef, deployment_id: deploymentId, release: verified });
+}
+async function uploadReadback(http, projectRef, deploymentId, releaseId, uploadStatus) {
+  const response = await http.get(releasePath(projectRef, deploymentId, releaseId), {
+    maxJsonBytes: RESPONSE_MAX_BYTES
+  });
+  const release = response.ok ? releaseEnvelope(response.data, { projectRef, deploymentId, releaseId }) : null;
+  if (!release) {
+    return releaseFailure("frontend.upload_release", "OUTCOME_UNKNOWN", uploadStatus);
+  }
+  return toolResponse({ project_ref: projectRef, deployment_id: deploymentId, release });
+}
+function stableJson(candidate) {
+  if (candidate === null || typeof candidate !== "object")
+    return JSON.stringify(candidate);
+  if (Array.isArray(candidate))
+    return `[${candidate.map(stableJson).join(",")}]`;
+  const record = candidate;
+  return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`).join(",")}}`;
+}
+function activationFingerprint(identity) {
+  return createHash3("sha256").update(stableJson({
+    project_ref: identity.projectRef,
+    deployment_id: identity.deploymentId,
+    release_id: identity.releaseId,
+    expected_active_release_id: identity.expectedActiveReleaseId,
+    activation_id: identity.mutationId,
+    expected_activation_id: identity.expectedActivationId
+  })).digest("hex");
+}
+function activationResourceKey(deploymentId) {
+  return `v1/frontend_release/${Buffer.from(deploymentId, "utf8").toString("base64url")}`;
+}
+function publicMutationReceipt(candidate, expected) {
+  if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
+    return null;
+  const envelope = candidate;
+  const mutation = envelope.mutation;
+  const expectedKeys = [
+    "project_ref",
+    "mutation_id",
+    "operation",
+    "resource_key",
+    "request_fingerprint",
+    "principal",
+    "status",
+    "checkpoint",
+    "receipt",
+    "response_status",
+    "failure_code",
+    "lease",
+    "completed_at",
+    "created_at",
+    "updated_at"
+  ];
+  if (!mutation || !exactKeys(envelope, ["project_ref", "mutation"]) || !exactKeys(mutation, expectedKeys) || envelope.project_ref !== expected.projectRef || mutation.project_ref !== expected.projectRef || mutation.mutation_id !== expected.mutationId || mutation.resource_key !== expected.resourceKey || mutation.request_fingerprint !== expected.requestFingerprint || typeof mutation.operation !== "string" || typeof mutation.status !== "string" || !(mutation.response_status === null || Number.isSafeInteger(mutation.response_status)) || !(mutation.failure_code === null || typeof mutation.failure_code === "string"))
+    return null;
+  return {
+    operation: mutation.operation,
+    status: mutation.status,
+    responseStatus: mutation.response_status,
+    failureCode: mutation.failure_code
+  };
+}
+function activationReceipt(candidate, input) {
+  if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
+    return null;
+  const record = candidate;
+  const release = releaseRecord(record.release);
+  const mutation = record.mutation;
+  if (!release || !mutation || !exactKeys(record, [
+    "project_ref",
+    "deployment_id",
+    "active_release_id",
+    "activation_id",
+    "release",
+    "mutation"
+  ]) || !exactKeys(mutation, ["mutation_id", "status", "replayed"]) || record.project_ref !== input.projectRef || record.deployment_id !== input.deploymentId || record.active_release_id !== input.releaseId || record.activation_id !== input.mutationId || release.project_ref !== input.projectRef || release.deployment_id !== input.deploymentId || release.release_id !== input.releaseId || mutation.mutation_id !== input.mutationId || mutation.status !== "succeeded" || typeof mutation.replayed !== "boolean")
+    return null;
+  return release;
+}
+async function activeReleaseReadback(http, identity) {
+  const endpoint = releaseEndpoint(identity.projectRef, identity.deploymentId);
+  const inventoryRead = await http.get(`${endpoint}?limit=${RELEASE_LIST_LIMIT_MAX}`, {
+    maxJsonBytes: RESPONSE_MAX_BYTES
+  });
+  const inventory = inventoryRead.ok ? releaseInventory(inventoryRead.data, {
+    projectRef: identity.projectRef,
+    deploymentId: identity.deploymentId
+  }) : null;
+  if (!inventory || inventory.releases.length > RELEASE_LIST_LIMIT_MAX || inventory.active_release_id !== identity.releaseId || inventory.active_activation_id !== identity.mutationId) {
+    return { release: null, status: inventoryRead.status };
+  }
+  const releaseRead = await http.get(releasePath(identity.projectRef, identity.deploymentId, identity.releaseId), { maxJsonBytes: RESPONSE_MAX_BYTES });
+  const release = releaseRead.ok ? releaseEnvelope(releaseRead.data, {
+    projectRef: identity.projectRef,
+    deploymentId: identity.deploymentId,
+    releaseId: identity.releaseId
+  }) : null;
+  return { release, status: releaseRead.status };
+}
+async function activateFrontendRelease(http, input) {
+  const mutationId = input.mutationId;
+  if (!MUTATION_ID_PATTERN.test(mutationId))
+    throw new Error("'mutation_id' must be a UUIDv4");
+  if (input.expectedActiveReleaseId !== "absent" && !RELEASE_ID_PATTERN.test(input.expectedActiveReleaseId)) {
+    throw new Error("'expected_active_release_id' is invalid");
+  }
+  if (input.expectedActivationId !== "absent" && !MUTATION_ID_PATTERN.test(input.expectedActivationId)) {
+    throw new Error("'expected_activation_id' is invalid");
+  }
+  const endpoint = `${releasePath(input.projectRef, input.deploymentId, input.releaseId)}/activate`;
+  const response = await http.post(endpoint, {
+    expected_active_release_id: input.expectedActiveReleaseId,
+    expected_activation_id: input.expectedActivationId,
+    mutation_id: mutationId
+  }, { maxJsonBytes: RESPONSE_MAX_BYTES });
+  const release = activationReceipt(response.data, { ...input, mutationId });
+  if (!response.ok || !release) {
+    if (response.status >= 400 && response.status < 500 && response.status !== 408 && !response.transportError) {
+      return releaseFailure("frontend.activate_release", "HTTP_ERROR", response.status);
+    }
+    return activationReadback(http, input, mutationId, response.status);
+  }
+  const readback = await activeReleaseReadback(http, { ...input, mutationId });
+  if (!readback.release || readback.release.tree_sha256 !== release.tree_sha256) {
+    return releaseFailure("frontend.activate_release", "OUTCOME_UNKNOWN", readback.status);
+  }
+  return toolResponse({
+    project_ref: input.projectRef,
+    deployment_id: input.deploymentId,
+    active_release_id: input.releaseId,
+    activation_id: mutationId,
+    release: readback.release
+  });
+}
+async function activationReadback(http, input, mutationId, activationStatus) {
+  const mutationRead = await http.get(`/v1/projects/${encodeURIComponent(input.projectRef)}/mutations/${mutationId}`, { maxJsonBytes: RESPONSE_MAX_BYTES });
+  const mutationEnvelope = mutationRead.data;
+  const mutation = mutationRead.ok ? publicMutationReceipt(mutationRead.data, {
+    projectRef: input.projectRef,
+    mutationId,
+    resourceKey: activationResourceKey(input.deploymentId),
+    requestFingerprint: activationFingerprint({ ...input, mutationId })
+  }) : null;
+  if (!mutation || mutationEnvelope?.project_ref !== input.projectRef || mutation.operation !== "frontend.release.activate" || mutation.status !== "succeeded" || mutation.responseStatus !== 200 || mutation.failureCode !== null) {
+    return releaseFailure("frontend.activate_release", "OUTCOME_UNKNOWN", activationStatus);
+  }
+  const readback = await activeReleaseReadback(http, { ...input, mutationId });
+  if (!readback.release) {
+    return releaseFailure("frontend.activate_release", "OUTCOME_UNKNOWN", activationStatus);
+  }
+  return toolResponse({
+    project_ref: input.projectRef,
+    deployment_id: input.deploymentId,
+    active_release_id: input.releaseId,
+    activation_id: mutationId,
+    release: readback.release
+  });
+}
+
+// src/shared/tools/frontend-tools.ts
+function registerFrontendTools(server, http) {
+  server.tool("frontend", `Immutable prebuilt frontend release control.
+Actions: list_releases, get_release, upload_release, activate_release`, {
+    action: withDescription(stringEnum([
+      "list_releases",
+      "get_release",
+      "upload_release",
+      "activate_release"
+    ]), "Action"),
+    ref: optional(Type.String(), "Project ref"),
+    id: optional(Type.String(), "Deployment ID"),
+    zip_path: optional(Type.String(), "[upload_release] Local ZIP file path"),
+    release_id: optional(Type.String(), "[get_release/activate_release] SHA-256 release ID"),
+    expected_active_release_id: optional(Type.String(), "[activate_release] Current release SHA-256 or absent"),
+    expected_activation_id: optional(Type.String(), "[activate_release] Current activation UUIDv4 or absent"),
+    mutation_id: optional(Type.String(), "[activate_release] Required retry-stable UUIDv4"),
+    cursor: optional(Type.String(), "[list_releases] Last release SHA-256 cursor"),
+    limit: optional(Type.Number(), "[list_releases] Page size, 1-100 (default 50)")
+  }, async (args) => {
+    const {
+      action,
+      ref,
+      id,
+      zip_path,
+      release_id,
+      expected_active_release_id,
+      expected_activation_id,
+      mutation_id,
+      cursor,
+      limit
+    } = args;
+    const need = (f, v) => {
+      if (!v)
+        throw new Error(`'${f}' required for '${action}'`);
+    };
+    switch (action) {
+      case "list_releases":
+        need("ref", ref);
+        need("id", id);
+        return listFrontendReleases(http, ref, id, cursor, limit);
+      case "get_release":
+        need("ref", ref);
+        need("id", id);
+        need("release_id", release_id);
+        return getFrontendRelease(http, ref, id, release_id);
+      case "upload_release":
+        need("ref", ref);
+        need("id", id);
+        need("zip_path", zip_path);
+        return uploadFrontendRelease(http, ref, id, zip_path);
+      case "activate_release":
+        need("ref", ref);
+        need("id", id);
+        need("release_id", release_id);
+        need("expected_active_release_id", expected_active_release_id);
+        need("expected_activation_id", expected_activation_id);
+        need("mutation_id", mutation_id);
+        return activateFrontendRelease(http, {
+          projectRef: ref,
+          deploymentId: id,
+          releaseId: release_id,
+          expectedActiveReleaseId: expected_active_release_id,
+          expectedActivationId: expected_activation_id,
+          mutationId: mutation_id
+        });
+      default:
+        throw new Error("Unknown immutable frontend release action");
+    }
+  });
+}
 // package.json
 var package_default = {
   name: "@supacloud/admin",
-  version: "0.12.1",
+  version: "0.14.1",
   description: "Platform administration CLI for SupaCloud operators",
   type: "module",
   main: "./dist/index.js",
@@ -31125,6 +31913,7 @@ function unavailableAdminSchemas() {
     project: captureTools((server) => registerAdminProjectCliTools(server, schemaOnlyHttp)).project.schema,
     platform: captureTools((server) => registerAdvancedTools(server, schemaOnlyHttp)).platform.schema,
     gateway: captureTools((server) => registerGatewayTools(server, schemaOnlyHttp)).gateway.schema,
+    frontend: captureTools((server) => registerFrontendTools(server, schemaOnlyHttp)).frontend.schema,
     ssh: captureTools((server) => registerSshTools(server, {})).ssh.schema
   };
 }
@@ -31134,6 +31923,7 @@ function registerUnavailableAdminTools(tools) {
   tools.platform = unavailableTool(schemas.platform, "⚠️ Platform commands require SUPACLOUD_API_URL and SUPACLOUD_API_TOKEN.");
   tools.ssh = unavailableTool(schemas.ssh, "⚠️ SSH commands require SUPACLOUD_HOST, SSH credentials, and SUPACLOUD_SSH_HOST_FINGERPRINT.");
   tools.gateway = unavailableTool(schemas.gateway, "⚠️ Gateway / Caddy commands require SUPACLOUD_API_URL and SUPACLOUD_API_TOKEN (admin privileges).");
+  tools.frontend = unavailableTool(schemas.frontend, "⚠️ Frontend commands require SUPACLOUD_API_URL and SUPACLOUD_API_TOKEN.");
 }
 function printHelp(context = resolveSupaCloudContext()) {
   console.error(`
@@ -31190,10 +31980,16 @@ EXAMPLES
   supacloud-admin project runtime_snapshot --ref abc123
   supacloud-admin project service_control --ref abc123 --service gotrue --service_action stop
   supacloud-admin platform metrics
+  supacloud-admin platform list_logical_backups --ref abc123
+  supacloud-admin platform create_logical_backup --ref abc123
+  supacloud-admin platform restore_logical_backup --ref abc123 --backup_id BACKUP_ID --expected_sha256 SHA256 --confirmation RESTORE_PROJECT:abc123:BACKUP_ID:SHA256
   supacloud-admin gateway routes --ref abc123
   supacloud-admin gateway upsert_route --ref abc123 --route_id webhook --hosts "api.example.com" --paths "/webhook/*" --upstream 10.0.0.5:8080
   supacloud-admin gateway config --ref abc123 --rate_limit_tier pro
   supacloud-admin gateway rebuild --ref abc123 --clean
+  supacloud-admin frontend list_releases --ref abc123 --id web
+  supacloud-admin frontend upload_release --ref abc123 --id web --zip_path /secure/site.zip
+  supacloud-admin frontend activate_release --ref abc123 --id web --release_id <sha256> --expected_active_release_id absent --expected_activation_id absent --mutation_id <uuid-v4>
 `);
 }
 function authorizedToolMap(tools, context, confirmProduction) {
@@ -31281,6 +32077,7 @@ function createAdminTools(context = resolveSupaCloudContext(), confirmProduction
     });
     Object.assign(tools, captureTools((server) => registerAdminProjectCliTools(server, http)));
     Object.assign(tools, captureTools((server) => registerGatewayTools(server, http)));
+    Object.assign(tools, captureTools((server) => registerFrontendTools(server, http)));
     const advancedTools = captureTools((server) => registerAdvancedTools(server, http));
     if (advancedTools.platform) {
       tools.platform = advancedTools.platform;
@@ -31331,17 +32128,17 @@ async function main() {
   }
   const cliTools = createAdminTools(context, globalOptions.confirmProduction);
   if (args.length === 1 && cliTools[args[0]]) {
-    const toolResponse = await cliTools[args[0]].callback({});
-    if (toolResponse?.content && Array.isArray(toolResponse.content)) {
-      for (const chunk of toolResponse.content) {
+    const toolResponse2 = await cliTools[args[0]].callback({});
+    if (toolResponse2?.content && Array.isArray(toolResponse2.content)) {
+      for (const chunk of toolResponse2.content) {
         if (chunk.type === "text") {
           console.log(chunk.text);
         }
       }
     } else {
-      console.log(JSON.stringify(toolResponse, null, 2));
+      console.log(JSON.stringify(toolResponse2, null, 2));
     }
-    if (cliToolResultIsError(toolResponse))
+    if (cliToolResultIsError(toolResponse2))
       process.exitCode = 1;
     return;
   }
@@ -31351,7 +32148,7 @@ function isDirectRun() {
   if (!process.argv[1])
     return false;
   try {
-    return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(resolve3(process.argv[1]));
+    return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(resolve4(process.argv[1]));
   } catch {
     return false;
   }

package/package.json

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