@indigoai-us/hq-cloud 6.8.0 → 6.9.0

package/src/object-io.test.ts

@@ -109,6 +109,30 @@ describe("factory selection", () => {
   });
 });
 
+describe("S3SdkObjectIO.putObject — conditional-write fence", () => {
+  it("maps ifMatch (re-quoted) and ifNoneMatch onto the PutObjectCommand", async () => {
+    const io = new S3SdkObjectIO(ctx());
+    const sent: Array<Record<string, unknown>> = [];
+    // Swap the private client for a recorder — the fence mapping is pure
+    // input-shaping, no wire needed.
+    (io as unknown as { client: { send: (c: { input: Record<string, unknown> }) => Promise<unknown> } }).client = {
+      send: async (cmd) => {
+        sent.push(cmd.input);
+        return { ETag: '"landed"' };
+      },
+    };
+    await io.putObject({ key: "a", body: Buffer.from("x"), contentType: "t", ifMatch: "abc" });
+    expect(sent[0].IfMatch).toBe('"abc"'); // stripped etags re-quoted for If-Match
+    await io.putObject({ key: "a2", body: Buffer.from("x"), contentType: "t", ifMatch: '"quoted"' });
+    expect(sent[1].IfMatch).toBe('"quoted"'); // already-quoted passes through
+    await io.putObject({ key: "b", body: Buffer.from("y"), contentType: "t", ifNoneMatch: "*" });
+    expect(sent[2].IfNoneMatch).toBe("*");
+    await io.putObject({ key: "c", body: Buffer.from("z"), contentType: "t" });
+    expect(sent[3].IfMatch).toBeUndefined(); // unfenced PUT stays unfenced
+    expect(sent[3].IfNoneMatch).toBeUndefined();
+  });
+});
+
 describe("PresignObjectIO.putObject", () => {
   let fetchMock: ReturnType<typeof vi.fn>;
   beforeEach(() => {
@@ -190,6 +214,58 @@ describe("PresignObjectIO.putObject", () => {
       io.putObject({ key: "k", body: Buffer.from("z"), contentType: "x" }),
     ).rejects.toThrow(/presigned PUT failed for k: 403/);
   });
+
+  it("forwards the conditional-write fence on the presign request (ifMatch stripped, ifNoneMatch verbatim)", async () => {
+    // The server signs If-Match/If-None-Match into the URL (hq-pro follow-up)
+    // and echoes the headers for replay; the client's job is to ASK. Servers
+    // that predate the fields ignore them — never broken, just unconditional.
+    const { vault, presignCalls, setPresign } = makeVault();
+    setPresign([{ key: "fenced.md", op: "put", url: "https://s3/put-url" }]);
+    fetchMock.mockResolvedValue(
+      new Response(null, { status: 200, headers: { etag: '"v2"' } }),
+    );
+    const io = new PresignObjectIO(vault, COMPANY);
+    await io.putObject({
+      key: "fenced.md",
+      body: Buffer.from("x"),
+      contentType: "text/markdown",
+      ifMatch: '"v1"',
+    });
+    expect(presignCalls[0].keys[0]).toMatchObject({
+      key: "fenced.md",
+      op: "put",
+      ifMatch: "v1", // quotes stripped on the wire; server re-quotes when signing
+    });
+
+    await io.putObject({
+      key: "fresh.md",
+      body: Buffer.from("y"),
+      contentType: "text/markdown",
+      ifNoneMatch: "*",
+    });
+    expect(presignCalls[1].keys[0]).toMatchObject({
+      key: "fresh.md",
+      op: "put",
+      ifNoneMatch: "*",
+    });
+  });
+
+  it("maps a 412 PUT response to name:PreconditionFailed (the fence fired — conflict, not failure)", async () => {
+    const { vault, setPresign } = makeVault();
+    setPresign([{ key: "raced.md", op: "put", url: "https://s3/put-url" }]);
+    fetchMock.mockResolvedValue(
+      new Response("PreconditionFailed", { status: 412 }),
+    );
+    const io = new PresignObjectIO(vault, COMPANY);
+    await expect(
+      io.putObject({
+        key: "raced.md",
+        body: Buffer.from("z"),
+        contentType: "text/plain",
+        ifMatch: "old-etag",
+      }),
+    ).rejects.toMatchObject({ name: "PreconditionFailed" });
+  });
 });
 
 describe("PresignObjectIO.getObject", () => {
@@ -354,13 +430,40 @@ describe("PresignObjectIO.headObject", () => {
     expect(await io.headObject("gone")).toBeNull();
   });
 
-  it("returns null when presign denies the key (no usable head)", async () => {
+  it("throws Forbidden when presign denies the key — denial is NOT absence", async () => {
+    // Regression: pre-fix this returned null ("absent"), which made
+    // share.ts's push guard (`if (remoteMeta)`) skip every conflict check
+    // and issue an unconditional PUT — a transient denial mid-pass silently
+    // clobbered newer remote bytes (2026-06-10..12 vault regression storm).
     const { vault, setPresign } = makeVault();
     setPresign([{ key: "secret/x", op: "get", error: "forbidden" }]);
     const io = new PresignObjectIO(vault, COMPANY);
-    expect(await io.headObject("secret/x")).toBeNull();
+    await expect(io.headObject("secret/x")).rejects.toMatchObject({
+      name: "Forbidden",
+    });
     expect(fetchMock).not.toHaveBeenCalled();
   });
+
+  it("throws Forbidden on a presigned-GET 403 — same SDK-parity contract", async () => {
+    // Expired presigned URL, expired signing creds, KMS or bucket-policy
+    // denial all surface as 403 on the signed GET. Unknown state — must
+    // never read as "object missing".
+    const { vault, setPresign } = makeVault();
+    setPresign([{ key: "shared/a.md", op: "get", url: "https://s3/get" }]);
+    fetchMock.mockResolvedValue(new Response("AccessDenied", { status: 403 }));
+    const io = new PresignObjectIO(vault, COMPANY);
+    await expect(io.headObject("shared/a.md")).rejects.toMatchObject({
+      name: "Forbidden",
+    });
+  });
+
+  it("still returns null on a definitive 404 (key truly absent)", async () => {
+    const { vault, setPresign } = makeVault();
+    setPresign([{ key: "gone2", op: "get", url: "https://s3/get" }]);
+    fetchMock.mockResolvedValue(new Response("", { status: 404 }));
+    const io = new PresignObjectIO(vault, COMPANY);
+    expect(await io.headObject("gone2")).toBeNull();
+  });
 });
 
 /**

package/src/object-io.ts

@@ -68,7 +68,29 @@ export interface PresignTransportClient {
 // Wire-primitive shapes
 // ---------------------------------------------------------------------------
 
-export interface PutObjectInput {
+/**
+ * Conditional-write fence for a PUT (S3 conditional writes, GA 2024-11).
+ *
+ * `ifMatch` — only land the PUT if the remote object's ETag still equals
+ * this value (the journal baseline / last-observed HEAD). `ifNoneMatch: "*"`
+ * — only land the PUT if NO object exists at the key (creation fence).
+ * Either mismatch makes S3 reject with 412 PreconditionFailed, which the
+ * push path surfaces as a conflict instead of a silent overwrite.
+ *
+ * This is the storage-level backstop for the entire stale-clobber class:
+ * a HEAD-then-PUT race, a transport bug that misreads remote state, or an
+ * outdated client mid-pass can no longer regress a newer remote object —
+ * S3 itself refuses. (The 2026-06-10..12 vault regression storm was this
+ * class: stale machine copies blind-PUT over newer objects.)
+ */
+export interface PutPrecondition {
+  /** Land only if the current remote ETag equals this (quotes optional). */
+  ifMatch?: string;
+  /** Land only if no object exists at the key. */
+  ifNoneMatch?: "*";
+}
+
+export interface PutObjectInput extends PutPrecondition {
   key: string;
   body: Buffer;
   contentType: string;
@@ -117,7 +139,12 @@ export interface ObjectIO {
   getObject(key: string): Promise<GetObjectResult>;
   listObjects(input: ListObjectsInput): Promise<ListObjectsResult>;
   deleteObject(key: string): Promise<void>;
-  /** Null when the key does not exist (404 / 403-as-absent). */
+  /**
+   * Null ONLY when the key definitively does not exist (404). Access denial
+   * (403 / per-key presign denial) THROWS a `name: "Forbidden"` error — it is
+   * unknown state, never "absent". Conflating the two disables push-side
+   * conflict guards and clobbers newer remote objects.
+   */
   headObject(key: string): Promise<HeadObjectResult | null>;
   /**
    * Optional batch pre-mint. Warms an internal URL cache for `keys` under `op`
@@ -192,6 +219,13 @@ export class S3SdkObjectIO implements ObjectIO {
         ...(input.metadata && Object.keys(input.metadata).length > 0
           ? { Metadata: input.metadata }
           : {}),
+        // Conditional-write fence. If-Match wants the quoted entity-tag form;
+        // callers hand us journal/HEAD etags that may be stripped — re-quote
+        // so both shapes fence identically. A mismatch surfaces as the SDK's
+        // name:"PreconditionFailed" (HTTP 412), which the push path maps to
+        // its conflict flow.
+        ...(input.ifMatch ? { IfMatch: quoteEtag(input.ifMatch) } : {}),
+        ...(input.ifNoneMatch ? { IfNoneMatch: input.ifNoneMatch } : {}),
       }),
     );
     return { etag: res.ETag || "" };
@@ -311,6 +345,44 @@ function notFoundError(key: string): Error {
   return Object.assign(new Error(`Not found: ${key}`), { name: "NotFound" });
 }
 
+/**
+ * An error shaped like the AWS SDK's HeadObject 403 (`name: "Forbidden"`) so
+ * presigned-transport denials route through the SAME catch sites as SDK ones
+ * (share.ts / sync.ts `isAccessDenied`: name === "AccessDenied" | "Forbidden").
+ * Critically this is NOT `null`: "can't read the key" must never be conflated
+ * with "the key does not exist" — that conflation let a transient 403 episode
+ * disable every push-side conflict guard and clobber newer remote objects.
+ */
+function accessDeniedError(key: string, detail: string): Error {
+  return Object.assign(
+    new Error(`Access denied for ${key}: ${detail}`),
+    { name: "Forbidden" },
+  );
+}
+
+/**
+ * An error shaped like the AWS SDK's 412 (`name: "PreconditionFailed"`) so
+ * presigned-transport conditional-write rejections route through the same
+ * catch sites as SDK ones. A 412 means the fence WORKED: the remote moved
+ * past the caller's baseline (If-Match) or the key already exists
+ * (If-None-Match) — surface as a conflict, never overwrite.
+ */
+function preconditionFailedError(key: string, detail: string): Error {
+  return Object.assign(
+    new Error(`Precondition failed for ${key}: ${detail}`),
+    { name: "PreconditionFailed" },
+  );
+}
+
+/**
+ * If-Match compares quoted entity-tags. Journal baselines store etags
+ * stripped (normalizeEtag) while SDK HEADs return them quoted — accept both
+ * and emit the canonical quoted form.
+ */
+function quoteEtag(etag: string): string {
+  return etag.startsWith('"') ? etag : `"${etag}"`;
+}
+
 /**
  * Max keys per presign request when priming — the server's hard batch cap
  * (hq-pro files-presign MAX_BATCH_KEYS = 1000). One presign call costs ONE
@@ -435,7 +507,13 @@ export class PresignObjectIO implements ObjectIO {
   private async resolveUrl(
     op: PresignOp,
     key: string,
-    extra?: { contentType?: string; metadata?: Record<string, string> },
+    extra?: {
+      contentType?: string;
+      metadata?: Record<string, string>;
+      /** Conditional-write fence for PUT presigns — see PutPrecondition. */
+      ifMatch?: string;
+      ifNoneMatch?: "*";
+    },
   ): Promise<{ url: string; headers?: Record<string, string> }> {
     const hit = this.cached(op, key);
     if (hit) return { url: hit.url, headers: hit.headers };
@@ -509,11 +587,23 @@ export class PresignObjectIO implements ObjectIO {
   }
 
   async putObject(input: PutObjectInput): Promise<{ etag: string }> {
+    // Conditional-write fields (ifMatch/ifNoneMatch) are forwarded on the
+    // presign request so the server can sign If-Match/If-None-Match into the
+    // URL and echo them via `headers` for replay. Until hq-pro's
+    // files-presign signs them (follow-up to this PR), the server ignores
+    // the fields and the returned header set carries no condition — the PUT
+    // stays unconditional on this transport, exactly today's behavior. We
+    // deliberately do NOT inject the header client-side: an unsigned
+    // conditional header breaks the SigV4 signature. Enforcement on this
+    // transport activates the moment the server starts signing; the SDK
+    // transport enforces immediately.
     const row = await this.resolveUrl("put", input.key, {
       contentType: input.contentType,
       ...(input.metadata && Object.keys(input.metadata).length > 0
         ? { metadata: input.metadata }
         : {}),
+      ...(input.ifMatch ? { ifMatch: stripQuotes(input.ifMatch) } : {}),
+      ...(input.ifNoneMatch ? { ifNoneMatch: input.ifNoneMatch } : {}),
     });
     // The server signs Content-Type, SSE-KMS, and every x-amz-meta-* into the
     // signature and returns them in `headers`; they MUST be replayed verbatim
@@ -523,6 +613,14 @@ export class PresignObjectIO implements ObjectIO {
       { method: "PUT", body: input.body, headers: row.headers ?? {} },
       `presigned PUT ${input.key}`,
     );
+    if (res.status === 412) {
+      // The signed conditional header fenced this write off: the remote
+      // moved past our baseline (If-Match) or the key already exists
+      // (If-None-Match). Same shape as the SDK's PreconditionFailed so the
+      // push path routes both transports through one conflict handler.
+      const detail = await safeText(res);
+      throw preconditionFailedError(input.key, detail);
+    }
     if (!res.ok) {
       const detail = await safeText(res);
       throw new Error(
@@ -607,18 +705,33 @@ export class PresignObjectIO implements ObjectIO {
       }
       const row = results[0];
       if (!row || row.error || !row.url) {
-        // A per-key denial here means the caller can't read the key — treat as
-        // absent for HEAD semantics (the SDK path would 403, which callers map
-        // to "no usable head"); they all tolerate null.
-        return null;
+        // A per-key denial means the caller can't READ the key — it says
+        // nothing about whether the object EXISTS. Pre-fix this returned
+        // null ("absent"), which made push call sites skip every conflict
+        // guard (`if (remoteMeta)`) and issue an UNCONDITIONAL PUT — a
+        // transient denial episode mid-pass silently clobbered newer remote
+        // bytes with this machine's stale copy (the 2026-06-10..12 vault
+        // regression storm). Throw the same access-denied shape the SDK
+        // transport raises so callers route through their existing
+        // isAccessDenied skip/defer paths instead of "object missing".
+        throw accessDeniedError(key, row?.error ?? "presign denied");
       }
       url = row.url;
     }
     const res = await fetchWithRetry(url, { method: "GET" }, `presigned HEAD ${key}`);
-    if (res.status === 404 || res.status === 403) {
+    if (res.status === 404) {
       await cancelBody(res);
       return null;
     }
+    if (res.status === 403) {
+      // 403 on the signed GET (expired URL, expired signing creds, KMS or
+      // bucket-policy denial) is UNKNOWN state, not absence — see the presign
+      // 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);
+      throw accessDeniedError(key, "presigned HEAD returned 403");
+    }
     if (!res.ok) {
       await cancelBody(res);
       const detail = await safeText(res);

package/src/s3.ts

@@ -9,7 +9,7 @@
 import * as fs from "fs";
 import * as path from "path";
 import type { EntityContext } from "./types.js";
-import { resolveObjectIO, type ObjectIO } from "./object-io.js";
+import { resolveObjectIO, type ObjectIO, type PutPrecondition } from "./object-io.js";
 
 // Byte/metadata transport is resolved per-call via resolveObjectIO(ctx) — the
 // default is the AWS S3 SDK over STS-vended credentials (S3SdkObjectIO), but a
@@ -427,6 +427,7 @@ export async function uploadFile(
   localPath: string,
   key: string,
   author?: UploadAuthor,
+  precondition?: PutPrecondition,
 ): Promise<{ etag: string }> {
   // Boundary guardrail: never store a non-POSIX key (see toPosixKey).
   key = toPosixKey(key);
@@ -438,7 +439,9 @@ export async function uploadFile(
   // send the body — putObject replays the cached headers (computed by the SAME
   // builders below, so identical). hasPrimedPut only reports true with >60s of
   // URL lifetime left, so the cache can't expire before the putObject below.
-  if (io.hasPrimedPut?.(key)) {
+  // Fenced PUTs bypass the fast path: a primed URL was signed WITHOUT the
+  // conditional header, so replaying it would silently drop the fence.
+  if (!precondition && io.hasPrimedPut?.(key)) {
     const primed = await io.putObject({
       key,
       body,
@@ -469,6 +472,7 @@ export async function uploadFile(
     body,
     contentType: getMimeType(key),
     metadata: Metadata,
+    ...(precondition ?? {}),
   });
 
   return { etag: response.etag };
@@ -491,6 +495,7 @@ export async function uploadSymlink(
   target: string,
   key: string,
   author?: UploadAuthor,
+  precondition?: PutPrecondition,
 ): Promise<{ etag: string }> {
   // Boundary guardrail: never store a non-POSIX key (see toPosixKey).
   key = toPosixKey(key);
@@ -498,8 +503,9 @@ export async function uploadSymlink(
   const symlinkBody = encodeSymlinkBody(target);
 
   // Fast path: primeUploads() already signed this symlink's metadata into a
-  // cached PUT URL — send the body, replay the cached headers.
-  if (io.hasPrimedPut?.(key)) {
+  // cached PUT URL — send the body, replay the cached headers. Fenced PUTs
+  // bypass it — the primed URL carries no conditional header (see uploadFile).
+  if (!precondition && io.hasPrimedPut?.(key)) {
     const primed = await io.putObject({
       key,
       body: symlinkBody,
@@ -533,6 +539,7 @@ export async function uploadSymlink(
     body: symlinkBody,
     contentType: "application/octet-stream",
     metadata: Metadata,
+    ...(precondition ?? {}),
   });
 
   return { etag: response.etag };

package/src/vault-client.ts

@@ -206,6 +206,15 @@ export interface PresignKeyInput {
   contentType?: string;
   /** Custom object metadata to sign into a PUT (x-amz-meta-*). */
   metadata?: Record<string, string>;
+  /**
+   * Conditional-write fence for a PUT presign (S3 conditional writes). When
+   * the server supports it (hq-pro files-presign follow-up), it signs
+   * `If-Match: "<etag>"` / `If-None-Match: *` into the URL and echoes the
+   * header in the result row's `headers` for verbatim replay. Servers that
+   * predate the field ignore it — the PUT stays unconditional, never broken.
+   */
+  ifMatch?: string;
+  ifNoneMatch?: "*";
 }
 
 /** One result row from POST /v1/files/presign (per key, request order). */