@underpostnet/cyberia 3.3.73 → 3.3.77

package/src/server/network/underpost-gateway.js

@@ -957,6 +957,104 @@ const placeInstanceStaticAssets = ({ instances, options, label }) => {
   return assertStaticAssets({ records, hostRoot, label });
 };
 
+/**
+ * @method parseRawHttpResponse
+ * @description Splits a raw HTTP/1.x response into its status code and body. The body
+ * is everything after the first blank line, byte for byte, so it can be hashed against
+ * the document on disk.
+ * @param {string} raw - Response as read off the socket.
+ * @returns {{status: string, body: string}} Status code (empty when no status line) and body.
+ * @memberof UnderpostGateway
+ */
+const parseRawHttpResponse = (raw = '') => {
+  const status = /^HTTP\/[0-9.]+\s+([0-9]{3})/.exec(raw)?.[1] || '';
+  if (!status) return { status: '', body: '' };
+  const separator = raw.search(/\r?\n\r?\n/);
+  if (separator < 0) return { status, body: '' };
+  return { status, body: raw.slice(separator).replace(/^\r?\n\r?\n/, '') };
+};
+
+/**
+ * @method gatewayPodFetch
+ * @description One request against the gateway from inside its own pod, returning the
+ * status and the body even when the status is an error.
+ *
+ * Written on the socket with `nc` rather than fetched with `wget`: the image ships
+ * busybox, whose `wget` discards the body of any non-2xx response and exits — so a
+ * fallback document, which is by definition delivered with an upstream-failure status,
+ * could never be read through it. The probe that did so failed every attempt on a
+ * correct edge and looked like a hang. HTTP/1.0 keeps the reply unchunked, so the body
+ * is the document verbatim. Where `nc` is absent the `wget` pair still yields the status.
+ * @param {object} params
+ * @param {string} params.namespace - Namespace the gateway runs in.
+ * @param {string} params.host - Host header to present.
+ * @param {string} [params.path] - Request path.
+ * @returns {{status: string, body: string}} What the gateway answered.
+ * @memberof UnderpostGateway
+ */
+const gatewayPodFetch = ({ namespace, host, path = '/' }) => {
+  const exec = (script) =>
+    `${
+      shellExec(`kubectl exec -n ${namespace} deploy/${UNDERPOST_GATEWAY.name} -- sh -c "${script}"`, {
+        stdout: true,
+        silent: true,
+        silentOnError: true,
+        disableLog: true,
+      }) ?? ''
+    }`;
+  const request = path || '/';
+  const raw = exec(
+    `printf 'GET ${request} HTTP/1.0\\r\\nHost: ${host}\\r\\n\\r\\n' | nc -w 10 127.0.0.1 ${UNDERPOST_GATEWAY.port} 2>/dev/null || true`,
+  );
+  const parsed = parseRawHttpResponse(raw);
+  if (parsed.status) return parsed;
+  const url = `http://127.0.0.1${request}`;
+  const headers = exec(`wget -S -O /dev/null -T 10 --header 'Host: ${host}' ${url} 2>&1 || true`);
+  const status = [...headers.matchAll(/HTTP\/[0-9.]+\s+([0-9]{3})/g)].pop()?.[1] || '';
+  const body = exec(`wget -q -O - -T 10 --header 'Host: ${host}' ${url} 2>/dev/null || true`);
+  return { status, body };
+};
+
+/**
+ * @method gatewayFetch
+ * @description One request against the gateway, returning the status and the body
+ * even when the status is an error — the shape every fallback probe asserts on.
+ *
+ * Sent from this host with `curl` to the gateway Service first: the sync runs on the
+ * node that holds the gateway's volume, so the ClusterIP is reachable, and curl keeps
+ * the body of an error response. Only when that yields no status line does it fall back
+ * to {@link UnderpostGateway.gatewayPodFetch}, which needs nothing on the host at all.
+ * @param {object} params
+ * @param {string} params.namespace - Namespace the gateway runs in.
+ * @param {string} params.host - Host header to present.
+ * @param {string} [params.path] - Request path.
+ * @returns {{status: string, body: string, via: string}} What the gateway answered, and which way.
+ * @memberof UnderpostGateway
+ */
+const gatewayFetch = ({ namespace, host, path = '/' }) => {
+  const clusterIp = `${
+    shellExec(`kubectl get svc ${UNDERPOST_GATEWAY.serviceName} -n ${namespace} -o jsonpath='{.spec.clusterIP}'`, {
+      stdout: true,
+      silent: true,
+      silentOnError: true,
+      disableLog: true,
+    }) ?? ''
+  }`.trim();
+  if (/^[0-9a-f.:]+$/i.test(clusterIp)) {
+    const raw = `${
+      shellExec(
+        `curl -sS -i --noproxy '*' --max-time 10 -H 'Host: ${host}' http://${clusterIp}:${UNDERPOST_GATEWAY.port}${
+          path || '/'
+        } 2>/dev/null || true`,
+        { stdout: true, silent: true, silentOnError: true, disableLog: true },
+      ) ?? ''
+    }`;
+    const parsed = parseRawHttpResponse(raw);
+    if (parsed.status) return { ...parsed, via: 'host' };
+  }
+  return { ...gatewayPodFetch({ namespace, host, path }), via: 'pod' };
+};
+
 /**
  * @method gatewayFallbackProbeRunner
  * @description Proves the edge answers each configured fallback with the exact
@@ -1018,26 +1116,24 @@ const gatewayFallbackProbeRunner = async ({ checks, options, label, gatewayStatu
           silent: true,
           silentOnError: true,
         }).trim();
-      } else {
-        const request = `http://127.0.0.1${check.path || '/'}`;
-        body = shellExec(
-          `kubectl exec -n ${namespace} deploy/${UNDERPOST_GATEWAY.name} -- sh -c ` +
-            `"wget -q -O - -T 10 --header 'Host: ${check.host}' ${request} 2>/dev/null || true"`,
-          { stdout: true, silent: true, silentOnError: true },
-        );
-        const headers = shellExec(
-          `kubectl exec -n ${namespace} deploy/${UNDERPOST_GATEWAY.name} -- sh -c ` +
-            `"wget -S -O /dev/null -T 10 --header 'Host: ${check.host}' ${request} 2>&1 || true"`,
-          { stdout: true, silent: true, silentOnError: true },
-        );
-        status = [...headers.matchAll(/HTTP\/[0-9.]+\s+([0-9]{3})/g)].pop()?.[1] || '';
-      }
+      } else ({ status, body } = gatewayFetch({ namespace, host: check.host, path: check.path }));
       actualHash = crypto
         .createHash('sha256')
         .update(body || '')
         .digest('hex');
       passed = /^50[234]$/.test(status) && !!expectedHash && actualHash === expectedHash;
       if (passed) break;
+      // The first miss is reported as it happens: a probe that polls for minutes with
+      // nothing on the console reads as a hang, and what it saw is the whole diagnosis.
+      if (attempts === 1)
+        logger.warn(`[${label}] Fallback probe not yet satisfied; polling`, {
+          host: check.host,
+          path: check.path || '/',
+          status: status || '(none)',
+          bodyBytes: Buffer.byteLength(body || ''),
+          bodyMatchesConfiguredAsset: actualHash === expectedHash,
+          expectedAsset: expectedHash ? check.assetPath : '(missing on disk)',
+        });
       if (attempts < 30) await timer(2000);
     }
     const result = {
@@ -1059,6 +1155,8 @@ export {
   UNDERPOST_GATEWAY,
   assertStaticAssets,
   gatewayFallbackProbeRunner,
+  gatewayFetch,
+  gatewayPodFetch,
   gatewayStaticAssetExists,
   hostInstanceRegistryPathFactory,
   hostServerConfFactory,
@@ -1071,6 +1169,7 @@ export {
   kubernetesUpstreamFactory,
   underpostGatewayManifestsFactory,
   nginxConfFactory,
+  parseRawHttpResponse,
   seedDefaultStatusPage,
   staticLocationFactory,
   staticPathSegmentFactory,

package/src/server/ops/logger.js

@@ -48,6 +48,13 @@ const SENSITIVE_WORDS = new Set([
   'token',
 ]);
 const SENSITIVE_COMPOUNDS = ['apikey', 'privatekey', 'accesskey', 'sessionid', 'mysqlpwd', 'mariadbpwd'];
+/**
+ * A value adjacent to a sensitive name, separated by nothing but whitespace, is only treated as
+ * the secret when it is shaped like one: long enough, and carrying a digit, a capital, or a
+ * separator. Prose reads the same way — `token verification failed` — and redacting the next
+ * word of every sentence would cost more than it protects.
+ */
+const CREDENTIAL_SHAPED = /^(?=.{12,}$)(?=.*[0-9A-Z_-])[A-Za-z0-9_-]+$/;
 const sensitiveField = (key) => {
   const words = `${key || ''}`
     .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
@@ -61,43 +68,71 @@ const sensitiveField = (key) => {
   );
 };
 
+/**
+ * Redacts a value that follows a sensitive name with nothing but whitespace between them.
+ *
+ * Service errors report credentials this way — `Invalid api_key 4778…` — so the pair reaches a
+ * log through a message rather than through a command or a structured field, which is what every
+ * other rule matches on. The candidate is looked ahead rather than consumed: a plain match would
+ * take `Invalid api_key` as its own name/value pair and advance past the real one behind it.
+ * @param {string} text - Text to scan.
+ * @returns {string} The text with adjacent credentials redacted.
+ * @memberof Logger
+ */
+const redactAdjacentCredentials = (text) => {
+  const pairs = new RegExp(`(${CONFIG_NAME_SOURCE})([ \\t]+)(?=([A-Za-z0-9_-]+)(?![\\w-]))`, 'g');
+  let out = '';
+  let cursor = 0;
+  for (const match of text.matchAll(pairs)) {
+    const [, key, separator, candidate] = match;
+    const valueStart = match.index + key.length + separator.length;
+    if (valueStart < cursor) continue;
+    if (!sensitiveField(key) || !CREDENTIAL_SHAPED.test(candidate)) continue;
+    out += text.slice(cursor, valueStart) + REDACTED;
+    cursor = valueStart + candidate.length;
+  }
+  return cursor === 0 ? text : out + text.slice(cursor);
+};
+
 const redactSensitiveText = (value = '') =>
-  `${value ?? ''}`
-    .replace(/-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z0-9 ]*PRIVATE KEY-----/g, REDACTED)
-    .replace(
-      /\b(?:gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|glpat-[A-Za-z0-9_-]{20,}|xox[baprs]-[A-Za-z0-9-]{10,}|eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+)\b/g,
-      REDACTED,
-    )
-    .replace(/([a-z][a-z0-9+.-]*\\?:(?:\\?\/){2})(?:(?:\\.)|[^/\\\s@])+(\\?@)/gi, '$1***$2')
-    .replace(/\b(x-access-token\\?:)[^\s"']+?(?=\\?@github\.com\b)/gi, '$1***')
-    .replace(
-      /((?:"|')?(?:authorization|proxy-authorization)(?:"|')?\s*:\s*)(?:"[^"]*"|'[^']*'|(?:bearer|basic)\s+\S+|\S+)/gi,
-      `$1"${REDACTED}"`,
-    )
-    .replace(
-      new RegExp(
-        `(\\b(?:host|app|state|secret)\\s+set\\s+)(${CONFIG_NAME_SOURCE})(\\s+)(${SENSITIVE_VALUE_SOURCE})`,
-        'gi',
+  redactAdjacentCredentials(
+    `${value ?? ''}`
+      .replace(/-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z0-9 ]*PRIVATE KEY-----/g, REDACTED)
+      .replace(
+        /\b(?:gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|glpat-[A-Za-z0-9_-]{20,}|xox[baprs]-[A-Za-z0-9-]{10,}|eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+)\b/g,
+        REDACTED,
+      )
+      .replace(/([a-z][a-z0-9+.-]*\\?:(?:\\?\/){2})(?:(?:\\.)|[^/\\\s@])+(\\?@)/gi, '$1***$2')
+      .replace(/\b(x-access-token\\?:)[^\s"']+?(?=\\?@github\.com\b)/gi, '$1***')
+      .replace(
+        /((?:"|')?(?:authorization|proxy-authorization)(?:"|')?\s*:\s*)(?:"[^"]*"|'[^']*'|(?:bearer|basic)\s+\S+|\S+)/gi,
+        `$1"${REDACTED}"`,
+      )
+      .replace(
+        new RegExp(
+          `(\\b(?:host|app|state|secret)\\s+set\\s+)(${CONFIG_NAME_SOURCE})(\\s+)(${SENSITIVE_VALUE_SOURCE})`,
+          'gi',
+        ),
+        (match, prefix, key, separator) => (sensitiveField(key) ? `${prefix}${key}${separator}${REDACTED}` : match),
+      )
+      .replace(
+        new RegExp(`(\\s--?)(${CONFIG_NAME_SOURCE})(=|\\s+)(${SENSITIVE_VALUE_SOURCE})`, 'gi'),
+        (match, prefix, key, separator) => (sensitiveField(key) ? `${prefix}${key}${separator}${REDACTED}` : match),
+      )
+      .replace(
+        new RegExp(`(^|\\s)(-p)(\\s*)(${SENSITIVE_VALUE_SOURCE})`, 'gi'),
+        (match, prefix, flag, separator, secret) =>
+          secret.startsWith('-') ? match : `${prefix}${flag}${separator}${REDACTED}`,
+      )
+      .replace(
+        new RegExp(`\\b(${CONFIG_NAME_SOURCE})(\\s*=\\s*)(${SENSITIVE_VALUE_SOURCE})`, 'gi'),
+        (match, key, separator) => (sensitiveField(key) ? `${key}${separator}${REDACTED}` : match),
+      )
+      .replace(
+        new RegExp(`((?:"|')?)(${CONFIG_NAME_SOURCE})((?:"|')?\\s*:\\s*)(${SENSITIVE_VALUE_SOURCE})`, 'gi'),
+        (match, quote, key, separator) => (sensitiveField(key) ? `${quote}${key}${separator}"${REDACTED}"` : match),
       ),
-      (match, prefix, key, separator) => (sensitiveField(key) ? `${prefix}${key}${separator}${REDACTED}` : match),
-    )
-    .replace(
-      new RegExp(`(\\s--?)(${CONFIG_NAME_SOURCE})(=|\\s+)(${SENSITIVE_VALUE_SOURCE})`, 'gi'),
-      (match, prefix, key, separator) => (sensitiveField(key) ? `${prefix}${key}${separator}${REDACTED}` : match),
-    )
-    .replace(
-      new RegExp(`(^|\\s)(-p)(\\s*)(${SENSITIVE_VALUE_SOURCE})`, 'gi'),
-      (match, prefix, flag, separator, secret) =>
-        secret.startsWith('-') ? match : `${prefix}${flag}${separator}${REDACTED}`,
-    )
-    .replace(
-      new RegExp(`\\b(${CONFIG_NAME_SOURCE})(\\s*=\\s*)(${SENSITIVE_VALUE_SOURCE})`, 'gi'),
-      (match, key, separator) => (sensitiveField(key) ? `${key}${separator}${REDACTED}` : match),
-    )
-    .replace(
-      new RegExp(`((?:"|')?)(${CONFIG_NAME_SOURCE})((?:"|')?\\s*:\\s*)(${SENSITIVE_VALUE_SOURCE})`, 'gi'),
-      (match, quote, key, separator) => (sensitiveField(key) ? `${quote}${key}${separator}"${REDACTED}"` : match),
-    );
+  );
 
 const serializeLogValue = (value) => {
   const seen = new WeakSet();

package/src/server/runtime/conf.js

@@ -2986,8 +2986,10 @@ const syncPrivateConf = (deployId, extraPaths = []) => {
   if (fs.existsSync(replicaSrcDir))
     for (const entry of fs.readdirSync(replicaSrcDir))
       if (entry.match(deployId)) fs.copySync(`${replicaSrcDir}/${entry}`, `${privateRepoPath}/replica/${entry}`);
-
-  for (const extraPath of extraPaths) fs.copySync(`./engine-private/${extraPath}`, `${privateRepoPath}/${extraPath}`);
+  for (const extraPath of extraPaths) {
+    fs.removeSync(`${privateRepoPath}/${extraPath}`);
+    fs.copySync(`./engine-private/${extraPath}`, `${privateRepoPath}/${extraPath}`);
+  }
 
   shellExec(
     `cd ${privateRepoPath}` +
@@ -2999,14 +3001,41 @@ const syncPrivateConf = (deployId, extraPaths = []) => {
 };
 
 /**
- * Moves a deploy's public template sources into the engine working tree ahead of
- * the build copy step. Idempotent and safe to rerun: each move is guarded by
- * `existsSync`, so already-moved or absent sources are skipped rather than throwing.
- * The `[src, dest]` pairs come from the deploy's product catalog (passed in), so
- * this module stays product-agnostic.
+ * Mirrors a deploy's public template sources from the engine working tree to the source
+ * repo they came from. The engine ignores every one of these paths, so an edit made there
+ * never reaches a diff; the source repo is where it is reviewed and committed. Each path
+ * the engine holds is replaced wholesale there (removed, then copied) so the source repo's
+ * `git status` reads as exactly the engine tree's state, deletions included. The engine
+ * copies stay in place: this is a copy, not a move. A path the engine tree does not hold
+ * is left untouched in the source repo rather than deleted.
+ *
+ * @method syncDeployIdSourcesBack
+ * @param {Array<[string, string]>} [sourceMoves=[]] - Public `[src, dest]` pairs.
+ * @returns {string[]} The source paths that were mirrored.
+ * @memberof ServerConfBuilder
+ */
+const syncDeployIdSourcesBack = (sourceMoves = []) => {
+  const mirrored = [];
+  for (const [src, dest] of sourceMoves) {
+    if (!fs.existsSync(dest)) continue;
+    fs.removeSync(src);
+    fs.copySync(dest, src);
+    mirrored.push(src);
+  }
+  return mirrored;
+};
+
+/**
+ * Brings a deploy's public template sources into line ahead of the build copy step. The
+ * engine working tree is the working copy and the source repo its git view, so a path the
+ * engine already holds is mirrored out to the repo ({@link syncDeployIdSourcesBack}) and
+ * only a path the engine lacks is copied in. Nothing is moved: the repo's working tree
+ * keeps every file, so a build never leaves it reading as wholesale deletions, and an
+ * engine-side edit is never overwritten by the repo's copy. Safe to rerun: each step is
+ * guarded by `existsSync`.
  *
  * @method syncDeployIdSources
- * @param {Array<[string, string]>} [sourceMoves=[]] - Public `[src, dest]` move pairs.
+ * @param {Array<[string, string]>} [sourceMoves=[]] - Public `[src, dest]` pairs.
  * @returns {boolean} `true` when any sources were declared, else `false`.
  * @memberof ServerConfBuilder
  */
@@ -3014,7 +3043,8 @@ const syncDeployIdSources = (sourceMoves = []) => {
   if (!sourceMoves.length) return false;
   for (const dir of ['src/api', 'src/client/components', 'src/client/public', 'src/client/services'])
     fs.mkdirSync(dir, { recursive: true });
-  for (const [src, dest] of sourceMoves) if (fs.existsSync(src)) fs.moveSync(src, dest, { overwrite: true });
+  syncDeployIdSourcesBack(sourceMoves);
+  for (const [src, dest] of sourceMoves) if (!fs.existsSync(dest) && fs.existsSync(src)) fs.copySync(src, dest);
   return true;
 };
 
@@ -3446,6 +3476,7 @@ export {
   waitForPort,
   syncPrivateConf,
   syncDeployIdSources,
+  syncDeployIdSourcesBack,
   gitOriginRepositoryName,
   ensureTemplateCheckout,
   pruneTemplateWorkTree,

package/src/server/runtime/start.js

@@ -333,10 +333,19 @@ class UnderpostStartUp {
       const result = await awaitDeployMonitor(true);
       if (result === true) {
         // Withdraw every domain's local traces once the deployment is serving. Three calls
-        // rather than one cross-domain sweep: each domain owns what it put on disk.
+        // rather than one cross-domain sweep: each domain owns what it put on disk. Only the
+        // host domain is forced: its `--force` removes the ephemeral `engine-private` clone,
+        // which must not outlive the boot inside a container. For the other two, `--force`
+        // reaches into the cluster (the app Secret, secret purges) and is never wanted here.
         if (env === 'production' && Underpost.state.isInsideContainer())
           for (const domain of [Underpost.secret, Underpost.host, Underpost.app])
-            domain.clean({ env, namespace: 'default', args: {}, dryRun: false, force: false });
+            domain.clean({
+              env,
+              namespace: 'default',
+              args: {},
+              dryRun: false,
+              force: domain === Underpost.host,
+            });
         setTimeout(() => {
           setRuntimeStatus(deployId, env, RUNTIME_STATUS.RUNNING);
           setStartContainerStatus(deployId, env);

package/src/server/storage/data-query.js

@@ -15,6 +15,22 @@
  * @memberof DataQuery
  */
 class DataQuery {
+  /**
+   * Filter that addresses one document by its natural key.
+   *
+   * The natural key is the value people navigate by: an object layer item id, an
+   * instance code. A key shaped like a document id matches either field, so a
+   * document id still resolves.
+   *
+   * @param {string} field - Path of the natural key, e.g. 'data.item.id'.
+   * @param {string} key - The key taken from the request.
+   * @memberof DataQuery
+   * @returns {Object} A Mongoose filter selecting at most one document.
+   */
+  static naturalKeyFilter(field, key) {
+    return /^[0-9a-f]{24}$/i.test(String(key)) ? { $or: [{ [field]: key }, { _id: key }] } : { [field]: key };
+  }
+
   /**
    * Parse request query parameters into Mongoose query options
    * @param {Object} params - The request query parameters (req.query)

package/src/server/storage/downloader.js

@@ -31,31 +31,79 @@ class Downloader {
    * @memberof Downloader
    */
   static downloadFile(url, fullPath, options = { method: 'get', responseType: 'stream' }) {
-    return new Promise((resolve, reject) =>
+    /**
+     * Renders an error response body, whatever transport shape it arrived in, capped for a log
+     * line. A stream request carries even its errors as a stream, so the body has to be read
+     * before it can be reported.
+     */
+    const responseBody = async (data) => {
+      if (!data) return undefined;
+      try {
+        if (Buffer.isBuffer(data)) return data.toString('utf8').slice(0, 500);
+        if (typeof data === 'string') return data.slice(0, 500);
+        if (typeof data.on === 'function') {
+          let text = '';
+          for await (const chunk of data) {
+            text += chunk;
+            if (text.length > 500) break;
+          }
+          return text.slice(0, 500) || undefined;
+        }
+        return JSON.stringify(data).slice(0, 500);
+      } catch {
+        return undefined;
+      }
+    };
+
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      const fail = (error) => {
+        if (settled) return;
+        settled = true;
+        logger.error('Error downloading the file', { fullPath, error: error?.message });
+        // A partial file is worse than none: the caller cannot tell it apart from a whole one.
+        if (fs.existsSync(fullPath)) fs.unlinkSync(fullPath);
+        return reject(error);
+      };
+
       axios({
         url,
         ...options,
       })
         .then((response) => {
-          // Create a write stream to save the file to the specified path
           const writer = fs.createWriteStream(fullPath);
-          response.data.pipe(writer);
+          const expectedBytes = Number(response.headers?.['content-length'] ?? NaN);
+
+          // A response stream that ends early still ends, so the writer emits `finish` and the
+          // download reports success over a truncated file. The declared length is what proves
+          // the transfer whole — without this check a short part reached the caller intact-looking
+          // and only surfaced much later, as a corrupt archive assembled from it.
           writer.on('finish', () => {
-            logger.info('Download completet');
+            if (settled) return;
+            const receivedBytes = writer.bytesWritten;
+            if (Number.isFinite(expectedBytes) && receivedBytes !== expectedBytes)
+              return fail(new Error(`Truncated download: expected ${expectedBytes} bytes, received ${receivedBytes}`));
+            settled = true;
+            logger.info('Download complete', { fullPath, bytes: receivedBytes });
             return resolve(fullPath);
           });
-          writer.on('error', (error) => {
-            logger.error('Error downloading the file');
-            // Cleanup incomplete file if possible
-            if (fs.existsSync(fullPath)) fs.unlinkSync(fullPath);
-            return reject(error);
-          });
+          writer.on('error', fail);
+          response.data.on('error', fail);
+          response.data.pipe(writer);
         })
-        .catch((error) => {
-          logger.error('Error in the request');
+        .catch(async (error) => {
+          // The status alone names nothing. A storage service explains a refusal in the body —
+          // which delivery type it looked under, which id it could not find — and without it a
+          // caller sees `status code 400` and has to reproduce the request by hand to learn why.
+          logger.error('Error in the request', {
+            fullPath,
+            error: error?.message,
+            status: error?.response?.status,
+            body: await responseBody(error?.response?.data),
+          });
           return reject(error);
-        }),
-    );
+        });
+    });
   }
 }
 

package/src/server/storage/zip.js

@@ -0,0 +1,153 @@
+/**
+ * ZIP archive helpers built on JSZip, shared by the file-storage CLI and the client builder.
+ * @module src/server/storage/zip.js
+ * @namespace Zip
+ */
+
+import JSZip from 'jszip';
+import * as dir from 'path';
+import fs from 'fs-extra';
+
+const ZIP_LOCAL_FILE_HEADER = Buffer.from([0x50, 0x4b, 0x03, 0x04]);
+
+/**
+ * Reports whether a buffer starts with the ZIP local file header signature.
+ * @function isZipBuffer
+ * @param {Buffer} buffer - Candidate archive bytes.
+ * @returns {boolean} True when the buffer looks like a ZIP archive.
+ * @memberof Zip
+ */
+const isZipBuffer = (buffer) => Buffer.isBuffer(buffer) && buffer.subarray(0, 4).equals(ZIP_LOCAL_FILE_HEADER);
+
+/**
+ * Loads a ZIP archive from a buffer or a local path.
+ * @function loadZip
+ * @param {Buffer|string} source - Archive bytes or a path to the archive.
+ * @returns {Promise<JSZip>} The loaded archive.
+ * @memberof Zip
+ */
+const loadZip = async (source) => JSZip.loadAsync(Buffer.isBuffer(source) ? source : fs.readFileSync(source));
+
+/**
+ * Resolves an archive entry by exact name, then by trailing path segment, then by
+ * falling back to the only entry of a single-file archive.
+ * @function findZipEntry
+ * @param {JSZip} zip - The loaded archive.
+ * @param {string} entryName - Entry name or basename to look up.
+ * @returns {object|null} The matching JSZip entry, or null when nothing matches.
+ * @memberof Zip
+ */
+const findZipEntry = (zip, entryName) => {
+  const files = Object.values(zip.files).filter((entry) => !entry.dir);
+  return (
+    files.find((entry) => entry.name === entryName) ??
+    files.find((entry) => entry.name.endsWith(`/${entryName}`)) ??
+    (files.length === 1 ? files[0] : null)
+  );
+};
+
+/**
+ * Reads a single entry out of an archive.
+ * @function readZipEntry
+ * @param {Buffer|string} source - Archive bytes or a path to the archive.
+ * @param {string} entryName - Entry name or basename to read.
+ * @returns {Promise<Buffer|null>} The entry contents, or null when the entry is absent.
+ * @memberof Zip
+ */
+const readZipEntry = async (source, entryName) => {
+  const entry = findZipEntry(await loadZip(source), entryName);
+  return entry ? await entry.async('nodebuffer') : null;
+};
+
+/**
+ * Builds an archive buffer from local files.
+ * @function zipFromLocalFiles
+ * @param {Array<{localPath: string, entryName: string}>} entries - Files to archive.
+ * @returns {Promise<Buffer>} The generated archive bytes.
+ * @memberof Zip
+ */
+const zipFromLocalFiles = async (entries) => {
+  const zip = new JSZip();
+  for (const { localPath, entryName } of entries) {
+    const stats = fs.statSync(localPath);
+    zip.file(entryName, fs.readFileSync(localPath), {
+      date: stats.mtime,
+      unixPermissions: stats.mode & 0o777,
+    });
+  }
+  return await zip.generateAsync({
+    type: 'nodebuffer',
+    platform: 'UNIX',
+    compression: 'DEFLATE',
+    compressionOptions: { level: 6 },
+  });
+};
+
+/**
+ * Resolves an entry name against an output directory, rejecting archive paths that
+ * escape it (zip slip).
+ * @function resolveEntryTarget
+ * @param {string} outputPath - Extraction root.
+ * @param {string} entryName - Entry name from the archive.
+ * @returns {string} The absolute target path.
+ * @throws {Error} When the entry resolves outside the extraction root.
+ * @memberof Zip
+ */
+const resolveEntryTarget = (outputPath, entryName) => {
+  const root = dir.resolve(outputPath);
+  const target = dir.resolve(root, entryName);
+  if (target !== root && !target.startsWith(root + dir.sep)) {
+    throw new Error(`Blocked zip entry outside extraction directory: ${entryName}`);
+  }
+  return target;
+};
+
+/**
+ * Extracts every entry of an archive into a directory.
+ * @function extractZipTo
+ * @param {Buffer|string} source - Archive bytes or a path to the archive.
+ * @param {string} outputPath - Extraction root; created when missing.
+ * @returns {Promise<string[]>} The written file paths.
+ * @memberof Zip
+ */
+const extractZipTo = async (source, outputPath) => {
+  const zip = await loadZip(source);
+  fs.mkdirSync(outputPath, { recursive: true });
+
+  const writtenPaths = [];
+  for (const entry of Object.values(zip.files)) {
+    const target = resolveEntryTarget(outputPath, entry.name);
+    if (entry.dir) {
+      fs.mkdirSync(target, { recursive: true });
+      continue;
+    }
+    fs.mkdirSync(dir.dirname(target), { recursive: true });
+    fs.writeFileSync(target, await entry.async('nodebuffer'));
+    if (entry.unixPermissions) fs.chmodSync(target, entry.unixPermissions & 0o777);
+    writtenPaths.push(target);
+  }
+  return writtenPaths;
+};
+
+/**
+ * Extracts a single archive entry into a directory, flattening its archive path.
+ * @function extractZipEntryTo
+ * @param {Buffer|string} source - Archive bytes or a path to the archive.
+ * @param {string} entryName - Entry name or basename to extract.
+ * @param {string} targetDir - Destination directory; created when missing.
+ * @returns {Promise<string>} The written file path.
+ * @throws {Error} When the entry is not present in the archive.
+ * @memberof Zip
+ */
+const extractZipEntryTo = async (source, entryName, targetDir) => {
+  const entry = findZipEntry(await loadZip(source), entryName);
+  if (!entry) throw new Error(`Zip entry not found: ${entryName}`);
+
+  const target = resolveEntryTarget(targetDir, dir.basename(entryName));
+  fs.mkdirSync(dir.dirname(target), { recursive: true });
+  fs.writeFileSync(target, await entry.async('nodebuffer'));
+  if (entry.unixPermissions) fs.chmodSync(target, entry.unixPermissions & 0o777);
+  return target;
+};
+
+export { isZipBuffer, loadZip, findZipEntry, readZipEntry, zipFromLocalFiles, extractZipTo, extractZipEntryTo };