@indigoai-us/hq-cloud 6.14.6 → 6.14.8

package/src/object-io.test.ts

@@ -9,12 +9,17 @@
  */
 
 import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import * as http from "node:http";
+import { once } from "node:events";
+import { spawn } from "node:child_process";
 import {
   PresignObjectIO,
   S3SdkObjectIO,
   setObjectIOFactory,
+  setPresignedGetTransportForTesting,
   resolveObjectIO,
   presignObjectIOFactory,
+  type PresignedGetTransport,
   type PresignTransportClient,
 } from "./object-io.js";
 import type { EntityContext } from "./types.js";
@@ -23,6 +28,55 @@ import { isAccessDenied } from "./sync-core.js";
 
 const COMPANY = "cmp_test";
 
+function fetchBackedPresignedGetTransport(): PresignedGetTransport {
+  return {
+    async get(url, headers) {
+      const response = await fetch(url, { method: "GET", headers });
+      const body = response.body;
+      return {
+        status: response.status,
+        headers: response.headers,
+        body: body
+          ? (async function* (): AsyncIterable<Uint8Array> {
+              const reader = body.getReader();
+              let exhausted = false;
+              try {
+                while (true) {
+                  const { done, value } = await reader.read();
+                  if (done) {
+                    exhausted = true;
+                    return;
+                  }
+                  if (value.byteLength > 0) yield value;
+                }
+              } finally {
+                if (!exhausted) {
+                  try {
+                    await reader.cancel();
+                  } catch {
+                    // The response may already have been cancelled by destroy.
+                  }
+                }
+                reader.releaseLock();
+              }
+            })()
+          : undefined,
+        destroy: () => {
+          void body?.cancel().catch(() => undefined);
+        },
+      };
+    },
+  };
+}
+
+beforeEach(() => {
+  setPresignedGetTransportForTesting(fetchBackedPresignedGetTransport());
+});
+
+afterEach(() => {
+  setPresignedGetTransportForTesting(null);
+});
+
 function ctx(): EntityContext {
   return {
     uid: COMPANY,
@@ -506,6 +560,27 @@ describe("PresignObjectIO.getObject", () => {
     });
   });
 
+  it("drains the injected transport body instead of returning empty content", async () => {
+    const { vault, setPresign } = makeVault();
+    setPresign([{ key: "shared/a.md", op: "get", url: "https://s3/get" }]);
+    const transportGet = vi.fn(async () => ({
+      status: 200,
+      headers: new Headers({ "x-amz-meta-source": "transport" }),
+      body: (async function* (): AsyncIterable<Uint8Array> {
+        yield Buffer.from("transport-bytes");
+      })(),
+      destroy: () => undefined,
+    }));
+    setPresignedGetTransportForTesting({ get: transportGet });
+
+    const io = new PresignObjectIO(vault, COMPANY);
+    const res = await io.getObject("shared/a.md");
+
+    expect(res.body.toString("utf-8")).toBe("transport-bytes");
+    expect(res.metadata).toEqual({ source: "transport" });
+    expect(transportGet).toHaveBeenCalledWith("https://s3/get", undefined);
+  });
+
   it("throws a NotFound-named error on 404 (so s3.ts catch sites match)", async () => {
     const { vault, setPresign } = makeVault();
     setPresign([{ key: "gone", op: "get", url: "https://s3/get" }]);
@@ -1044,3 +1119,103 @@ describe("presignObjectIOFactory — personal vaults route to S3 SDK", () => {
     expect(personal).toBeInstanceOf(S3SdkObjectIO);
   });
 });
+
+describe("PresignObjectIO — core HTTP presigned GET", () => {
+  function streamingVault(baseUrl: string): PresignTransportClient {
+    return {
+      presign: async (input) => ({
+        results: input.keys.map((key) => ({
+          key: key.key,
+          op: "get" as const,
+          url: `${baseUrl}/${key.key}`,
+        })),
+        expiresAt: "2099-01-01T00:00:00.000Z",
+      }),
+      listFiles: async () => ({ objects: [], cursor: null, truncated: false }),
+    };
+  }
+
+  it("destroys an early-exit response and rejects a FIN-short body", async () => {
+    setPresignedGetTransportForTesting(null);
+    let responseClosed: Promise<unknown> | undefined;
+    const server = http.createServer((req, res) => {
+      if (req.url === "/short") {
+        res.writeHead(200, { "content-length": "10" });
+        res.end("short");
+        return;
+      }
+
+      res.writeHead(200, { "content-length": "131072" });
+      res.write(Buffer.alloc(65_536, 1));
+      responseClosed = once(res, "close");
+      const finish = setTimeout(() => res.end(Buffer.alloc(65_536, 2)), 1_000);
+      res.once("close", () => clearTimeout(finish));
+    });
+    server.listen(0, "127.0.0.1");
+    await once(server, "listening");
+    const address = server.address();
+    if (!address || typeof address === "string") {
+      throw new Error("test server did not bind a TCP port");
+    }
+
+    try {
+      const io = new PresignObjectIO(
+        streamingVault(`http://127.0.0.1:${address.port}`),
+        COMPANY,
+      );
+      const streamed = await io.getObjectStream("large");
+      const iterator = streamed.body[Symbol.asyncIterator]();
+      expect((await iterator.next()).value).toBeInstanceOf(Uint8Array);
+      await iterator.return?.();
+      if (!responseClosed) throw new Error("response did not start streaming");
+      await expect(responseClosed).resolves.toBeDefined();
+
+      await expect(io.getObject("short")).rejects.toThrow(
+        /content-length mismatch/,
+      );
+    } finally {
+      server.close();
+      await once(server, "close");
+    }
+  });
+
+  it.runIf(
+    process.platform === "win32" && /^(22|24)\./.test(process.versions.node),
+  )("keeps a child FIN safe after the consumer has applied backpressure", async () => {
+    setPresignedGetTransportForTesting(null);
+    const child = spawn(process.execPath, [
+      "-e",
+      [
+        "const http = require('node:http');",
+        "const body = Buffer.alloc(524288, 7);",
+        "const server = http.createServer((_req, res) => {",
+        "  res.writeHead(200, { 'content-length': String(body.length) });",
+        "  for (let offset = 0; offset < body.length; offset += 16384) res.write(body.subarray(offset, offset + 16384));",
+        "  res.end();",
+        "});",
+        "server.listen(0, '127.0.0.1', () => process.stdout.write(String(server.address().port) + '\\n'));",
+        "process.on('SIGTERM', () => server.close(() => process.exit(0)));",
+      ].join("\n"),
+    ], { stdio: ["ignore", "pipe", "inherit"] });
+
+    const port = await new Promise<number>((resolve, reject) => {
+      child.once("error", reject);
+      child.stdout?.once("data", (data: Buffer) => resolve(Number(data.toString())));
+      child.once("exit", (code) => reject(new Error(`child server exited (${code})`)));
+    });
+
+    try {
+      const io = new PresignObjectIO(
+        streamingVault(`http://127.0.0.1:${port}`),
+        COMPANY,
+      );
+      const streamed = await io.getObjectStream("bulk");
+      await new Promise((resolve) => setTimeout(resolve, 40));
+      let bytes = 0;
+      for await (const chunk of streamed.body) bytes += chunk.byteLength;
+      expect(bytes).toBe(524_288);
+    } finally {
+      child.kill("SIGTERM");
+    }
+  });
+});

package/src/object-io.ts

@@ -13,8 +13,8 @@
  *   - `PresignObjectIO` — the presigned-URL path. The vault-service decides
  *     access as a runtime DDB check (no IAM policy ceiling) and hands back
  *     short-lived presigned GET/PUT/DELETE URLs + (for PUT) the exact headers
- *     to replay. The client never holds AWS credentials — it just `fetch`es
- *     the signed URLs.
+ *     to replay. The client never holds AWS credentials — it requests the
+ *     signed URLs directly.
  *
  * The seam is a per-EntityContext factory resolved INSIDE s3.ts, so every
  * existing call site (`uploadFile(ctx, …)`, `downloadFile(ctx, …)`, …) keeps
@@ -31,6 +31,9 @@ import {
   DeleteObjectCommand,
   HeadObjectCommand,
 } from "@aws-sdk/client-s3";
+import * as http from "node:http";
+import * as https from "node:https";
+import type { IncomingMessage } from "node:http";
 import type { EntityContext } from "./types.js";
 import type {
   PresignOp,
@@ -344,6 +347,141 @@ function metaFromHeaders(headers: Headers): Record<string, string> {
   return meta;
 }
 
+/**
+ * Response shape shared by every presigned GET consumer. Unlike the runtime
+ * `fetch` response, its body is backed by Node's core HTTP client, so it never
+ * enters the runtime-bundled undici parser path.
+ */
+export interface PresignedGetResponse {
+  status: number;
+  headers: Headers;
+  body?: AsyncIterable<Uint8Array>;
+  destroy(): void;
+}
+
+/** Transport seam retained for deterministic wire-level regression tests. */
+export interface PresignedGetTransport {
+  get(
+    url: string,
+    headers: Record<string, string> | undefined,
+  ): Promise<PresignedGetResponse>;
+}
+
+function headersFromNode(
+  headers: IncomingMessage["headers"],
+): Headers {
+  const out = new Headers();
+  for (const [name, value] of Object.entries(headers)) {
+    if (value === undefined) continue;
+    out.set(name, Array.isArray(value) ? value.join(", ") : value);
+  }
+  return out;
+}
+
+function expectedContentLength(headers: Headers): number | undefined {
+  const value = headers.get("content-length");
+  if (value === null) return undefined;
+  if (!/^\d+$/.test(value)) {
+    throw new Error(`invalid presigned GET content-length: ${value}`);
+  }
+  const length = Number(value);
+  if (!Number.isSafeInteger(length)) {
+    throw new Error(`invalid presigned GET content-length: ${value}`);
+  }
+  return length;
+}
+
+function contentLengthError(expected: number, actual: number): Error {
+  return new Error(
+    `presigned GET content-length mismatch: expected ${expected} bytes, received ${actual}`,
+  );
+}
+
+async function* checkedNodeBody(
+  message: IncomingMessage,
+  expected: number | undefined,
+): AsyncIterable<Uint8Array> {
+  let received = 0;
+  let exhausted = false;
+  try {
+    try {
+      for await (const chunk of message) {
+        const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        received += bytes.byteLength;
+        if (expected !== undefined && received > expected) {
+          throw contentLengthError(expected, received);
+        }
+        yield bytes;
+      }
+    } catch (err) {
+      // A FIN before Node has received the declared bytes normally surfaces as
+      // an "aborted" stream error. Preserve the useful data-integrity cause.
+      if (expected !== undefined && received !== expected) {
+        throw contentLengthError(expected, received);
+      }
+      throw err;
+    }
+    exhausted = true;
+    if (expected !== undefined && received !== expected) {
+      throw contentLengthError(expected, received);
+    }
+  } finally {
+    // Consumers such as HEAD only inspect headers, and a caller can stop after
+    // a prefix. Destroying in both cases releases the socket immediately.
+    if (!exhausted) message.destroy();
+  }
+}
+
+function nodePresignedGet(
+  url: string,
+  headers: Record<string, string> | undefined,
+): Promise<PresignedGetResponse> {
+  const target = new URL(url);
+  return new Promise((resolve, reject) => {
+    const handleResponse = (message: IncomingMessage): void => {
+      const responseHeaders = headersFromNode(message.headers);
+      let expected: number | undefined;
+      try {
+        expected = expectedContentLength(responseHeaders);
+      } catch (err) {
+        message.destroy();
+        reject(err);
+        return;
+      }
+      resolve({
+        status: message.statusCode ?? 0,
+        headers: responseHeaders,
+        body: checkedNodeBody(message, expected),
+        destroy: () => message.destroy(),
+      });
+    };
+    const request = target.protocol === "https:"
+      ? https.request(target, { method: "GET", headers }, handleResponse)
+      : target.protocol === "http:"
+        ? http.request(target, { method: "GET", headers }, handleResponse)
+        : undefined;
+    if (!request) {
+      reject(new Error(`unsupported presigned GET protocol: ${target.protocol}`));
+      return;
+    }
+    request.once("error", reject);
+    request.end();
+  });
+}
+
+const NODE_PRESIGNED_GET_TRANSPORT: PresignedGetTransport = {
+  get: nodePresignedGet,
+};
+
+let presignedGetTransport: PresignedGetTransport = NODE_PRESIGNED_GET_TRANSPORT;
+
+/** Test-only override; production always uses Node's core HTTP(S) transport. */
+export function setPresignedGetTransportForTesting(
+  transport: PresignedGetTransport | null,
+): void {
+  presignedGetTransport = transport ?? NODE_PRESIGNED_GET_TRANSPORT;
+}
+
 /**
  * Per-key presign denial codes that are EXPECTED and must be reclassified as
  * skip-with-log — throwing the `name: "Forbidden"` shape (see
@@ -825,20 +963,21 @@ export class PresignObjectIO implements ObjectIO {
 
   async getObjectStream(key: string): Promise<GetObjectStreamResult> {
     const row = await this.resolveGetUrlForBody(key);
-    const res = await fetchWithRetry(row.url, { method: "GET" }, `presigned GET ${key}`);
+    const res = await presignedGetWithRetry(
+      row.url,
+      row.headers,
+      `presigned GET ${key}`,
+    );
     if (res.status === 404) {
-      await cancelBody(res);
+      res.destroy();
       throw notFoundError(key);
     }
-    if (!res.ok) {
-      const detail = await safeText(res);
+    if (res.status < 200 || res.status >= 300) {
+      const detail = await safePresignedGetText(res);
       throw new Error(`presigned GET failed for ${key}: ${res.status} ${detail}`);
     }
-    if (!res.body) {
-      return { body: (async function* () {})(), metadata: metaFromHeaders(res.headers) };
-    }
     return {
-      body: webReadableToAsyncIterable(res.body),
+      body: res.body ?? (async function* () {})(),
       metadata: metaFromHeaders(res.headers),
     };
   }
@@ -933,9 +1072,13 @@ export class PresignObjectIO implements ObjectIO {
       }
       url = row.url;
     }
-    const res = await fetchWithRetry(url, { method: "GET" }, `presigned HEAD ${key}`);
+    const res = await presignedGetWithRetry(
+      url,
+      undefined,
+      `presigned HEAD ${key}`,
+    );
     if (res.status === 404) {
-      await cancelBody(res);
+      res.destroy();
       return null;
     }
     if (res.status === 403) {
@@ -944,12 +1087,11 @@ export class PresignObjectIO implements ObjectIO {
       // denial branch above. The SDK transport throws name:"Forbidden" here;
       // mirror it so both transports agree and no caller mistakes a denial
       // for a missing object.
-      await cancelBody(res);
+      res.destroy();
       throw accessDeniedError(key, "presigned HEAD returned 403");
     }
-    if (!res.ok) {
-      await cancelBody(res);
-      const detail = await safeText(res);
+    if (res.status < 200 || res.status >= 300) {
+      const detail = await safePresignedGetText(res);
       throw new Error(`presigned HEAD failed for ${key}: ${res.status} ${detail}`);
     }
     const result: HeadObjectResult = {
@@ -958,7 +1100,7 @@ export class PresignObjectIO implements ObjectIO {
       size: Number(res.headers.get("content-length") ?? "0"),
       metadata: metaFromHeaders(res.headers),
     };
-    await cancelBody(res);
+    res.destroy();
     return result;
   }
 }
@@ -979,21 +1121,6 @@ async function cancelBody(res: Response): Promise<void> {
   }
 }
 
-async function* webReadableToAsyncIterable(
-  stream: ReadableStream<Uint8Array>,
-): AsyncIterable<Uint8Array> {
-  const reader = stream.getReader();
-  try {
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done) return;
-      if (value && value.byteLength > 0) yield value;
-    }
-  } finally {
-    reader.releaseLock();
-  }
-}
-
 function parseLastModified(value: string | null): Date {
   if (!value) return new Date();
   const d = new Date(value);
@@ -1023,6 +1150,60 @@ function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+/**
+ * Shared presigned-GET path for streaming reads and header-only probes.
+ *
+ * GET deliberately uses Node core HTTP(S), not global fetch: on affected
+ * Node/Windows builds the bundled undici parser can assert after a FIN arrives
+ * while the consumer is backpressured. Keep the retry budget identical to the
+ * PUT/DELETE fetch path below.
+ */
+async function presignedGetWithRetry(
+  url: string,
+  headers: Record<string, string> | undefined,
+  what: string,
+): Promise<PresignedGetResponse> {
+  let lastError: unknown;
+  for (let attempt = 0; attempt <= FETCH_MAX_RETRIES; attempt++) {
+    if (attempt > 0) {
+      const backoff = FETCH_BASE_DELAY_MS * 2 ** (attempt - 1);
+      const jitter = Math.floor(Math.random() * FETCH_BASE_DELAY_MS);
+      await sleep(backoff + jitter);
+    }
+    let res: PresignedGetResponse;
+    try {
+      res = await presignedGetTransport.get(url, headers);
+    } catch (err) {
+      lastError = err;
+      continue;
+    }
+    if (isTransientStatus(res.status) && attempt < FETCH_MAX_RETRIES) {
+      res.destroy();
+      lastError = new Error(`${what}: transient ${res.status}`);
+      continue;
+    }
+    return res;
+  }
+  throw lastError instanceof Error
+    ? lastError
+    : new Error(`${what}: failed after ${FETCH_MAX_RETRIES} retries`);
+}
+
+async function safePresignedGetText(res: PresignedGetResponse): Promise<string> {
+  try {
+    let text = "";
+    for await (const chunk of res.body ?? []) {
+      text += Buffer.from(chunk).toString("utf-8");
+      if (text.length >= 200) break;
+    }
+    return text.slice(0, 200);
+  } catch {
+    return "";
+  } finally {
+    res.destroy();
+  }
+}
+
 /**
  * `fetch` with bounded retry on network errors + transient 5xx. The presigned
  * URL is reusable until expiry and the bodies are in-memory Buffers, so a

package/src/s3.ts

@@ -764,6 +764,13 @@ export async function uploadSymlink(
  * return it to callers — e.g. the pull loop reads `created-by` to
  * attribute downloaded files to their author with zero extra network.
  */
+export interface DownloadModeWarning {
+  /** The mode guardrail that could not be applied exactly. */
+  reason: "missing-hq-mode" | "invalid-hq-mode" | "chmod-failed";
+  /** Legacy objects can retain a local file's known-good permission bits. */
+  fallback?: "preserved-local-mode" | "receiver-default";
+}
+
 export async function downloadFile(
   ctx: EntityContext,
   key: string,
@@ -772,6 +779,8 @@ export async function downloadFile(
   metadata?: Record<string, string>;
   contentHash?: string;
   contentSize?: number;
+  /** Non-fatal mode guardrail warnings for caller telemetry. */
+  modeWarnings?: DownloadModeWarning[];
 }> {
   const io = resolveObjectIO(ctx);
 
@@ -867,15 +876,25 @@ export async function downloadFile(
     return { metadata };
   }
   const tempPath = downloadTempPath(localPath);
+  // A legacy object has no hq-mode. If it is replacing a regular local file,
+  // that local mode is the only trustworthy signal we have — retaining it is
+  // strictly safer than replacing (for example) a 0755 hook with the receiver
+  // umask's usual 0644. Never inspect a symlink or infer intent from content.
+  let existingLocalMode: number | undefined;
+  try {
+    const existing = fs.lstatSync(localPath);
+    if (existing.isFile()) existingLocalMode = existing.mode & 0o777;
+  } catch {
+    // Fresh destination / inaccessible prior path: no local fallback.
+  }
   let tempReady = true;
   let streamed: { hash: string; size: number };
+  const modeWarnings: DownloadModeWarning[] = [];
   try {
     streamed = await streamRegularFileToTemp(tempPath, initialChunks, iterator);
 
     // 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. The staged path is a
+    // FILE_MODE_META_KEY for the metadata contract. The staged path is a
     // regular file, then it is atomically renamed over the destination.
     //
     // Codex P2 (PR #24 round 3): strict octal-only regex BEFORE parseInt.
@@ -886,17 +905,33 @@ export async function downloadFile(
     // the upload side stamps (`(mode & 0o777).toString(8)` → at most
     // three digits, all 0–7) and rejects everything else.
     const modeOctal = metadata?.[FILE_MODE_META_KEY];
+    let modeToApply: number | undefined;
     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(tempPath, 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.
-        }
+        modeToApply = parsed;
+      }
+    } else if (modeOctal === undefined) {
+      modeToApply = existingLocalMode;
+      modeWarnings.push({
+        reason: "missing-hq-mode",
+        fallback:
+          existingLocalMode === undefined
+            ? "receiver-default"
+            : "preserved-local-mode",
+      });
+    } else {
+      modeWarnings.push({ reason: "invalid-hq-mode", fallback: "receiver-default" });
+    }
+
+    if (modeToApply !== undefined) {
+      try {
+        fs.chmodSync(tempPath, modeToApply);
+      } catch {
+        // chmod failure (read-only FS, EPERM) is non-fatal — the file is
+        // materialized, but callers must receive a telemetry signal instead
+        // of silently believing the guardrail held.
+        modeWarnings.push({ reason: "chmod-failed" });
       }
     }
 
@@ -953,7 +988,21 @@ export async function downloadFile(
   // distinct creation time, so a future receiver upgrade picks it up
   // automatically without a server-side data migration.
 
-  return { metadata, contentHash: streamed.hash, contentSize: streamed.size };
+  if (modeWarnings.length > 0) {
+    for (const warning of modeWarnings) {
+      console.warn(
+        `[hq-sync] mode warning for ${key}: ${warning.reason}` +
+          (warning.fallback ? ` (${warning.fallback})` : ""),
+      );
+    }
+  }
+
+  return {
+    metadata,
+    contentHash: streamed.hash,
+    contentSize: streamed.size,
+    ...(modeWarnings.length > 0 ? { modeWarnings } : {}),
+  };
 }
 
 export interface RemoteFile {

package/src/scope-shrink.ts

@@ -40,6 +40,7 @@ import type {
   SyncJournal,
 } from "./types.js";
 import { hashFile, tombstoneEntry } from "./journal.js";
+import { localPathForVaultKey } from "./local-path-codec.js";
 import {
   isCoveredByAny,
   type ScopePrefixInput,
@@ -168,7 +169,7 @@ function classifyOrphan(
   entry: JournalEntry,
   hqRoot: string,
 ): OrphanClassification {
-  const absPath = path.join(hqRoot, relPath);
+  const absPath = localPathForVaultKey(hqRoot, relPath);
   let stat: fs.Stats;
   try {
     stat = fs.lstatSync(absPath);
@@ -436,9 +437,9 @@ export function applyScopeShrink(
   const dirtyKeptPaths: string[] = [];
 
   for (const orphan of plan.clean) {
-    const absPath = path.join(hqRoot, orphan.path);
+    const absPath = localPathForVaultKey(hqRoot, orphan.path);
     if (quarantining) {
-      const destAbs = path.join(input.quarantineRoot!, orphan.path);
+      const destAbs = localPathForVaultKey(input.quarantineRoot!, orphan.path);
       quarantineOrphan(absPath, destAbs);
       tombstoneEntry(journal, orphan.path, reason);
       cleanQuarantined++;