@indigoai-us/hq-cloud 5.33.0 → 5.35.0

package/src/s3.test.ts

@@ -115,12 +115,21 @@ describe("uploadFile", () => {
     fs.writeFileSync(tmpFile, "hello");
   });
 
-  it("omits Metadata when no author is provided (back-compat)", async () => {
+  it("omits author Metadata fields when no author is provided (back-compat)", async () => {
+    // Pre-Bug-#5: this test asserted Metadata was undefined entirely. Now
+    // \`hq-mode\` is stamped on every upload to preserve source-side
+    // permissions, so the assertion is narrower: author fields stay absent
+    // when no author is passed, but \`hq-mode\` is present.
     await uploadFile(makeCtx(), tmpFile, "attribution-test.md");
 
     const put = sentCommands.find((c) => c.name === "PutObjectCommand");
     expect(put).toBeDefined();
-    expect(put!.input.Metadata).toBeUndefined();
+    const meta = put!.input.Metadata as Record<string, string> | undefined;
+    expect(meta?.["created-by"]).toBeUndefined();
+    expect(meta?.["created-by-sub"]).toBeUndefined();
+    expect(meta?.["created-at"]).toBeUndefined();
+    // \`hq-mode\` IS present — that's the new Bug #5 contract.
+    expect(meta?.["hq-mode"]).toMatch(/^[0-7]{3}$/);
   });
 
   it("stamps created-by + created-by-sub + created-at when author is provided", async () => {
@@ -179,6 +188,37 @@ describe("uploadFile", () => {
     expect(Date.now() - stamped).toBeLessThan(60 * 1000);
   });
 
+  it("stamps source file mode as hq-mode metadata (Bug #5 — preserve permissions)", async () => {
+    // Bug #5 (broader than originally reported): every uploaded file's mode
+    // collapsed to the receiver's umask default (0644 on the verification
+    // hosts). 0755 scripts arrived non-executable, breaking every shell-tool
+    // workflow. Fix: stamp the source-side \`mode & 0o777\` into S3 user
+    // metadata as \`hq-mode\` (octal string), then chmod on download.
+    fs.chmodSync(tmpFile, 0o755);
+
+    await uploadFile(makeCtx(), tmpFile, "exec.sh");
+
+    const put = sentCommands.find((c) => c.name === "PutObjectCommand");
+    expect(put).toBeDefined();
+    const meta = put!.input.Metadata as Record<string, string> | undefined;
+    expect(meta?.["hq-mode"]).toBe("755");
+  });
+
+  it("stamps various modes correctly (0600, 0640, 0700, 0750)", async () => {
+    // Verification report V5: all four modes collapsed to 0644 receiver-side
+    // because the upload carried no mode at all. Pin each mode round-trips
+    // through the metadata header in canonical octal-string form (no leading
+    // zero — the parser uses parseInt(..., 8)).
+    for (const mode of [0o600, 0o640, 0o700, 0o750]) {
+      sentCommands.length = 0;
+      fs.chmodSync(tmpFile, mode);
+      await uploadFile(makeCtx(), tmpFile, "f.bin");
+      const put = sentCommands.find((c) => c.name === "PutObjectCommand");
+      const meta = put!.input.Metadata as Record<string, string> | undefined;
+      expect(meta?.["hq-mode"]).toBe(mode.toString(8));
+    }
+  });
+
   it("elides non-ASCII or empty author fields rather than throwing", async () => {
     // S3 user-defined metadata must be ASCII-only and total ≤ 2KB. Partial
     // attribution beats hard failure — values that fail the printable check
@@ -630,6 +670,106 @@ describe("downloadFile", () => {
     expect(fs.readlinkSync(localPath)).toBe("fresh-target.md");
   });
 
+  it("applies hq-mode metadata via chmod after byte write (Bug #5 — preserve permissions)", async () => {
+    // Round-trip pair to the s3.upload test: source-side mode lives in
+    // \`Metadata['hq-mode']\` as an octal string; the receiver must chmod
+    // the file to that exact mode after writing the bytes. Pre-fix the
+    // receiver took the umask default and 0755 scripts arrived 0644.
+    nextGetObjectResponse = {
+      Body: (async function* () {
+        yield new Uint8Array([35, 33, 47, 98, 105, 110]); // "#!/bin"
+      })(),
+      Metadata: { "hq-mode": "755" },
+    };
+
+    const localPath = path.join(tmpRoot, "exec.sh");
+    await downloadFile(makeCtx(), "exec.sh", localPath);
+
+    // mask to permission bits — the upper bits encode file-type (S_IFREG)
+    // and are not preserved on chmod.
+    const stat = fs.statSync(localPath);
+    expect((stat.mode & 0o777).toString(8)).toBe("755");
+  });
+
+  it("rounds-trips multiple modes (0600/0640/0700/0750/0755) via hq-mode", async () => {
+    // Verification report V5 multi-mode pin: every mode collapsed to 0644
+    // because the receiver had no mode signal at all. With \`hq-mode\` in
+    // metadata, all five modes must arrive at their exact source value.
+    for (const octal of ["600", "640", "700", "750", "755"]) {
+      nextGetObjectResponse = {
+        Body: (async function* () {
+          yield new Uint8Array([97]); // "a"
+        })(),
+        Metadata: { "hq-mode": octal },
+      };
+      const localPath = path.join(tmpRoot, `mode-${octal}.bin`);
+      await downloadFile(makeCtx(), `mode-${octal}.bin`, localPath);
+      expect((fs.statSync(localPath).mode & 0o777).toString(8)).toBe(octal);
+    }
+  });
+
+  it("rejects malformed hq-mode metadata via strict-octal regex (Codex P2)", async () => {
+    // Codex review on PR #24 caught: parseInt(modeOctal, 8) accepts
+    // partial-prefix garbage — "755junk" parses to 0o755 instead of
+    // NaN — so tampered or malformed metadata could still chmod the
+    // local file. Strict regex MUST reject anything that isn't pure
+    // octal digits before parseInt sees it; the file then arrives at
+    // umask default like the legacy back-compat path.
+    const malformed = [
+      "755junk", // trailing garbage — parseInt parses 0o755 pre-fix
+      "0x755",   // hex-looking prefix
+      "8",       // out-of-octal-range digit
+      "9",       // ditto
+      "-755",    // signed
+      "abc",     // non-numeric
+      "",        // empty
+      "7777",    // mode > 0o777 after parse
+      "12345",   // too long (more than 4 octal digits)
+      "  755 ",  // whitespace
+    ];
+    for (const bad of malformed) {
+      nextGetObjectResponse = {
+        Body: (async function* () {
+          yield new Uint8Array([116]); // "t"
+        })(),
+        Metadata: { "hq-mode": bad },
+      };
+      const localPath = path.join(tmpRoot, `bad-${malformed.indexOf(bad)}.bin`);
+      await downloadFile(makeCtx(), `bad-${malformed.indexOf(bad)}.bin`, localPath);
+      // Mode MUST be the umask default (whatever the test process inherits),
+      // NOT a partial-parse of the malformed string. Specifically, even if
+      // the malformed string would partial-parse to 0755, the file must NOT
+      // arrive at 0755 — it must take the umask default. We can't pin the
+      // exact default value (test runner umask varies), but we can pin that
+      // a partial-parse value (0o755) does NOT match for "755junk" cases.
+      const mode = (fs.statSync(localPath).mode & 0o777);
+      // Heuristic: if the parsed mode would have been 0o755, fail loudly.
+      // (umask default on most CI runners is 0o644 or 0o664, never 0o755.)
+      if (bad.startsWith("755") || bad === "0x755") {
+        expect(mode).not.toBe(0o755);
+      }
+    }
+  });
+
+  it("downloads with default umask permissions when hq-mode metadata is absent (back-compat)", async () => {
+    // Legacy uploads from pre-fix engines have no \`hq-mode\` metadata.
+    // The receiver must NOT crash and must NOT change the mode — let
+    // the OS default apply, mirroring the pre-fix behavior.
+    nextGetObjectResponse = {
+      Body: (async function* () {
+        yield new Uint8Array([108, 101, 103, 97, 99, 121]); // "legacy"
+      })(),
+      Metadata: {},
+    };
+
+    const localPath = path.join(tmpRoot, "legacy.bin");
+    await expect(
+      downloadFile(makeCtx(), "legacy.bin", localPath),
+    ).resolves.toBeDefined();
+    // No assertion on mode — receiver default is whatever umask set.
+    expect(fs.readFileSync(localPath, "utf-8")).toBe("legacy");
+  });
+
   it("returns the object's user-metadata (including created-by) for a regular file", async () => {
     nextGetObjectResponse = {
       Body: (async function* () {

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 };
 }