@indigoai-us/hq-cloud 5.33.0 → 5.34.0

package/src/s3.ts

@@ -160,6 +160,28 @@ export function decodeSymlinkMetadataValue(value: string): string {
  */
 export const SYMLINK_BODY_PREFIX = "hq-symlink:";
 
+/**
+ * S3 user-metadata key carrying the source-side file mode (permission bits
+ * only — \`mode & 0o777\`) as an octal string ("755", "640", etc.). On
+ * download, downloadFile parses this with \`parseInt(value, 8)\` and chmods
+ * the file to the exact source mode after the byte write.
+ *
+ * Bug #5 in the 5.33.0 deep-test was originally reported as "exec bit lost
+ * on sync" but the verification report broadened it: ALL modes (0600 / 0640
+ * / 0700 / 0750 / 0755) collapsed to the receiver's umask default (0644)
+ * because no mode signal crossed the wire at all. Stamping the mode in
+ * metadata is the smallest schema change that preserves the full
+ * permission bitfield without a per-host umask negotiation.
+ *
+ * Symlinks: skipped at upload time (symlink mode is OS-controlled
+ * lrwxrwxrwx) and skipped on download (\`fs.chmodSync\` follows symlinks
+ * and would mutate the target's mode instead).
+ *
+ * Back-compat: legacy uploads have no \`hq-mode\` header — the receiver
+ * leaves the umask default in place, matching pre-fix behavior.
+ */
+export const FILE_MODE_META_KEY = "hq-mode";
+
 /**
  * Encode/decode the symlink wire body. Kept as exported helpers so the
  * format is centrally defined and tests can probe both sides without
@@ -178,6 +200,20 @@ export async function uploadFile(
   const client = buildClient(ctx);
   const body = fs.readFileSync(localPath);
 
+  // Capture source-side file mode (permission bits only) for Bug #5 — see
+  // FILE_MODE_META_KEY doc. Best-effort: lstat failure (raced rm, EPERM)
+  // falls through to "no mode header" and the receiver keeps its umask
+  // default — same as the legacy back-compat path.
+  let modeOctal: string | undefined;
+  try {
+    const lstat = fs.lstatSync(localPath);
+    if (!lstat.isSymbolicLink()) {
+      modeOctal = (lstat.mode & 0o777).toString(8);
+    }
+  } catch {
+    // Leave modeOctal undefined; receiver applies its umask default.
+  }
+
   // Preserve the original `created-at` across re-uploads when the object
   // already exists with author metadata — same convention the hq-console
   // upload route uses, so the NEW-pill ageing window doesn't reset on every
@@ -198,7 +234,10 @@ export async function uploadFile(
     }
   }
 
-  const Metadata = author ? buildAuthorMetadata(author, createdAt) : undefined;
+  const Metadata: Record<string, string> = {
+    ...(author ? buildAuthorMetadata(author, createdAt) : {}),
+    ...(modeOctal ? { [FILE_MODE_META_KEY]: modeOctal } : {}),
+  };
 
   const response = await client.send(
     new PutObjectCommand({
@@ -206,7 +245,7 @@ export async function uploadFile(
       Key: key,
       Body: body,
       ContentType: getMimeType(key),
-      ...(Metadata && Object.keys(Metadata).length > 0 ? { Metadata } : {}),
+      ...(Object.keys(Metadata).length > 0 ? { Metadata } : {}),
     }),
   );
 
@@ -404,6 +443,36 @@ export async function downloadFile(
     chunks.push(Buffer.from(chunk));
   }
   fs.writeFileSync(localPath, Buffer.concat(chunks));
+
+  // Bug #5 — apply source-side mode after the byte write. See
+  // FILE_MODE_META_KEY for the metadata contract. Parses defensively:
+  // a malformed value falls through with no chmod so the umask default
+  // applies, matching the legacy back-compat path. fs.chmodSync
+  // follows symlinks — that's fine here because we're on the regular-
+  // file branch (the symlink branch above already returned).
+  //
+  // Codex P2 (PR #24 round 3): strict octal-only regex BEFORE parseInt.
+  // parseInt(modeOctal, 8) accepts partial-prefix garbage — "755junk"
+  // parses to 0o755 instead of NaN — so tampered or malformed metadata
+  // could still change local permissions unexpectedly. The regex
+  // requires 1–4 pure octal digits (`[0-7]{1,4}$`), which matches what
+  // the upload side stamps (`(mode & 0o777).toString(8)` → at most
+  // three digits, all 0–7) and rejects everything else.
+  const modeOctal = response.Metadata?.[FILE_MODE_META_KEY];
+  if (typeof modeOctal === "string" && /^[0-7]{1,4}$/.test(modeOctal)) {
+    const parsed = parseInt(modeOctal, 8);
+    if (Number.isFinite(parsed) && parsed >= 0 && parsed <= 0o777) {
+      try {
+        fs.chmodSync(localPath, parsed);
+      } catch {
+        // chmod failure (read-only FS, EPERM) is non-fatal — the file
+        // is materialized, just with the umask default. Surface via
+        // S3-side metadata being present but the file not matching;
+        // a future operator-side audit can reconcile.
+      }
+    }
+  }
+
   return { metadata: response.Metadata };
 }