@ultimat3/storage 30.8.0 → 31.0.0

package/src/accept-stream.ts

@@ -0,0 +1,125 @@
+// Single responsibility: a signed upload taken as a STREAM — the head read and sniffed, the rest
+// piped into `disk.putStream`, so memory per upload is the sniff window, not the body. A body that
+// ends inside the window, an XML type or a head opening with `<` (a script can sit anywhere in
+// either), and a required checksum nobody declared are read whole by `acceptSignedUpload`'s rule.
+
+import { type AcceptSignedUploadInput, acceptSignedUpload, signedObjectPut } from './accept';
+import type { StorageObject } from './driver';
+import { checksumMismatch, tooLarge } from './errors';
+import {
+  isXmlType,
+  opensWithMarkup,
+  SNIFF_WINDOW_BYTES,
+  uploadPolicy,
+  validateStoredHead,
+} from './upload';
+
+export interface AcceptSignedUploadStreamInput extends Omit<AcceptSignedUploadInput, 'bytes'> {
+  /** The request's body; `null` is an empty one. Read once, never buffered past the window. */
+  readonly body: ReadableStream<Uint8Array> | null;
+}
+
+/** Chunks read until `window` bytes are in hand or the body ends; past `ceiling` it is refused. */
+async function readHead(
+  reader: ReadableStreamDefaultReader<Uint8Array>,
+  key: string,
+  window: number,
+  ceiling: number,
+): Promise<{ readonly chunks: Uint8Array[]; readonly size: number; readonly done: boolean }> {
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  while (size < window) {
+    const next = await reader.read();
+    if (next.done) return { chunks, size, done: true };
+    chunks.push(next.value);
+    size += next.value.byteLength;
+    if (size > ceiling) throw tooLarge(key, size, ceiling);
+  }
+  return { chunks, size, done: false };
+}
+
+/** The uploader's body, no longer wanted: cancelled so the socket stops, whatever cancel answers. */
+async function stopReading(reader: ReadableStreamDefaultReader<Uint8Array>): Promise<void> {
+  try {
+    await reader.cancel();
+  } catch {
+    // An already-errored body cannot be cancelled, and has stopped anyway.
+  }
+}
+
+const concat = (chunks: readonly Uint8Array[]): Uint8Array =>
+  new Uint8Array(Bun.concatArrayBuffers([...chunks]));
+
+/**
+ * `acceptSignedUpload` for a body that may not fit in memory: the same gates, in the same order,
+ * with the magic bytes judged on the head. Past the ceiling, or a declared checksum the bytes do
+ * not hash to, the stream errors and `putStream` abandons the write: the key is as it was.
+ */
+export async function acceptSignedUploadStream(
+  input: AcceptSignedUploadStreamInput,
+): Promise<StorageObject> {
+  const { key, contentType, maxBytes } = await signedObjectPut(input);
+  const policy = input.policy ?? uploadPolicy();
+  const ceiling = Math.min(policy.maxBytes, maxBytes ?? policy.maxBytes);
+  const reader = (input.body ?? new Blob([]).stream()).getReader();
+  let head: Awaited<ReturnType<typeof readHead>>;
+  try {
+    head = await readHead(reader, key, SNIFF_WINDOW_BYTES, ceiling);
+  } catch (error) {
+    await stopReading(reader);
+    throw error;
+  }
+  const whole =
+    head.done ||
+    isXmlType(contentType) ||
+    opensWithMarkup(concat(head.chunks)) ||
+    (policy.requireChecksum && input.checksum === undefined);
+  if (whole) {
+    const chunks = [...head.chunks];
+    let size = head.size;
+    try {
+      for (
+        let next = head.done ? undefined : await reader.read();
+        next !== undefined && !next.done;
+        next = await reader.read()
+      ) {
+        size += next.value.byteLength;
+        if (size > ceiling) throw tooLarge(key, size, ceiling);
+        chunks.push(next.value);
+      }
+    } finally {
+      await stopReading(reader);
+    }
+    return acceptSignedUpload({ ...input, bytes: concat(chunks) });
+  }
+  // The head says more follows: `size + 1` is "at least one byte past it", so an XML or a cut
+  // character is judged as a head, never as a whole body.
+  validateStoredHead(
+    { key, declaredContentType: contentType, head: concat(head.chunks), size: head.size + 1 },
+    policy,
+  );
+  const hasher = input.checksum === undefined ? undefined : new Bun.CryptoHasher('sha256');
+  let size = 0;
+  const counted = (chunk: Uint8Array): Uint8Array => {
+    size += chunk.byteLength;
+    if (size > ceiling) throw tooLarge(key, size, ceiling);
+    hasher?.update(chunk);
+    return chunk;
+  };
+  const queued = head.chunks.slice();
+  const body = new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      const first = queued.shift();
+      if (first !== undefined) return controller.enqueue(counted(first));
+      const next = await reader.read();
+      if (!next.done) return controller.enqueue(counted(next.value));
+      const actual = hasher?.digest('base64');
+      if (actual !== undefined && actual !== input.checksum) {
+        throw checksumMismatch(key, input.checksum ?? 'none', actual);
+      }
+      controller.close();
+    },
+    cancel: (reason) => reader.cancel(reason),
+  });
+  return input.disk.putStream(key, body, { maxBytes: ceiling, contentType });
+}

package/src/accept.ts

@@ -133,13 +133,21 @@ export async function signedUploadConstraints(
   return constraintsFor(input, 'PUT');
 }
 
+/** What a verified object PUT may store: the key, the type the grant signed, its ceiling. */
+export interface SignedObjectPut {
+  readonly key: string;
+  readonly contentType: string;
+  readonly maxBytes: number | undefined;
+}
+
 /**
- * Take a presigned PUT and write it, or refuse. Four gates the client cannot move because all
- * four are inside the signature or inside the bytes: the signature itself, the expiry, the byte
- * count against the signed ceiling, and the declared type against both the signature and the
- * magic bytes. `validateUpload` runs last because it is the only one that reads the whole body.
+ * Every gate a PUT passes before its body is read: the signature, the expiry, the tenant, the
+ * method, an OBJECT url (never a part's), and the declared type against the signed one. Shared by
+ * `acceptSignedUpload` and the streamed `acceptSignedUploadStream`, so the two are one rule.
  */
-export async function acceptSignedUpload(input: AcceptSignedUploadInput): Promise<StorageObject> {
+export async function signedObjectPut(
+  input: SignedRequestInput & { readonly declaredContentType?: string | undefined },
+): Promise<SignedObjectPut> {
   const constraints = await constraintsFor(input, 'PUT');
   const key = constraints.key;
   // A part URL writes one part of an open upload, never the object: `acceptSignedPart` takes it.
@@ -169,9 +177,19 @@ export async function acceptSignedUpload(input: AcceptSignedUploadInput): Promis
     );
   }
 
+  return { key, contentType: signed, maxBytes: constraints.maxBytes };
+}
+
+/**
+ * Take a presigned PUT and write it, or refuse. Four gates the client cannot move because all
+ * four are inside the signature or inside the bytes: the signature itself, the expiry, the byte
+ * count against the signed ceiling, and the declared type against both the signature and the
+ * magic bytes. `validateUpload` runs last because it is the only one that reads the whole body.
+ */
+export async function acceptSignedUpload(input: AcceptSignedUploadInput): Promise<StorageObject> {
+  const { key, contentType: signed, maxBytes } = await signedObjectPut(input);
   // The signed ceiling, checked before the policy's: the two can differ once a policy is edited
   // between the grant and the upload, and the narrower one is the one that was granted.
-  const maxBytes = constraints.maxBytes;
   const size = input.bytes.byteLength;
   if (maxBytes !== undefined && size > maxBytes) throw tooLarge(key, size, maxBytes);
 

package/src/adapter.ts

@@ -0,0 +1,46 @@
+// `@ultimat3/storage/adapter`: two ports as an adapter author needs them. `storage`: `StorageDriver`,
+// its shapes, errors and shared refusal helpers — no installer, the boot READS `runtime.ts`'s
+// driver as its default disk (`@ultimat3/cli`'s `runtime-storage-boot.ts`). `uploadScanner`:
+// `UploadScanner`, what it is asked and answers, and the boot's installer.
+
+export type {
+  ByteLimit,
+  CopyOptions,
+  ListOptions,
+  PutOptions,
+  ServerSideEncryption,
+  SignedUrlMethod,
+  SignedUrlOptions,
+  StorageBody,
+  StorageDriver,
+  StorageListEntry,
+  StorageObject,
+  StorageRead,
+  StreamOptions,
+} from './driver';
+export { assertPutOptions, etagOf, resolveListLimit, toBytes } from './driver';
+export type { LocalDriverOptions } from './driver-local';
+export type { MemoryStorageDriverOptions } from './driver-memory';
+export type { S3DriverOptions } from './driver-s3';
+export type { StorageErrorCode, StorageErrorInit } from './errors';
+export {
+  checksumMismatch,
+  deleteFailed,
+  getTooLarge,
+  isStorageError,
+  keyConflict,
+  listFailed,
+  objectNotFound,
+  pathUnsafe,
+  putFailed,
+  putTooLarge,
+  readFailed,
+  StorageError,
+} from './errors';
+export type { MultipartCapability } from './multipart';
+export type { ObjectLock, ObjectLockOptions } from './object-lock';
+export type { PutStreamOptions } from './put-stream';
+export type { ByteRange, GetOptions } from './range';
+export type { SignedPart, SignedUrlVerification } from './signed-url';
+export type { ScanInput, ScanVerdict, UploadScanner } from './upload-scanner';
+export { installUploadScanner, resetUploadScanner } from './upload-scanner';

package/src/attachment.ts

@@ -5,31 +5,18 @@
 // so the tenant prefix is a construction, not a check somebody remembered to write.
 
 import type { Clock } from '@ultimat3/core';
-import { assert, finiteCount, renderThrowable, systemClock } from '@ultimat3/core';
+import { assert, finiteCount, nanoid, renderThrowable, systemClock } from '@ultimat3/core';
 import type { StorageDriver, StorageListEntry, StorageObject } from './driver';
 import { objectNotFound, orgMismatch, tooLarge } from './errors';
-import { alreadyPromoted, notPending, objectChanged, quarantined } from './errors-promote';
+import { alreadyPromoted, notPending, objectChanged } from './errors-promote';
 import { assertSafeKey, isWithinOrg, orgPrefix, scopedKey } from './path';
 import type { UploadPolicy } from './upload';
 import { SNIFF_WINDOW_BYTES, validateStoredHead } from './upload';
+import { SCAN_SEGMENT, scanAttempt, scanning } from './upload-scan';
 
 /** The one segment an unattached upload lives under. `sweepOrphans` reads only this prefix. */
 export const PENDING_SEGMENT = 'pending';
 
-/**
- * One more segment inside `pending/`, and the whole of Ultimate's content-scanning mechanism.
- *
- * Magic-byte sniffing closes stored XSS; it is not malware scanning, and `application/zip` is
- * deliberately accepted as the OOXML container, so a macro-laden `.docx` passes `validateUpload`
- * exactly as a clean one does. Scanning is the APP's — a scanner is a business decision with a
- * vendor, a licence and a latency budget (axiom 8) — so what ships is the place to put one: an
- * upload granted with `quarantine: true` lands under this prefix, `promoteAttachment` REFUSES a
- * key that is still there (`X_STORAGE_QUARANTINED`), and the app's scan job calls
- * `releaseQuarantine` on a verdict of clean. Inside `pending/` on purpose: an upload nobody ever
- * scanned is still an orphan, so `sweepOrphans` collects it with no second prefix to walk.
- */
-export const QUARANTINE_SEGMENT = 'quarantine';
-
 export interface AttachmentTarget {
   /** Entity name as the app declares it — `post`, `user`. Exactly one key segment. */
   readonly entity: string;
@@ -78,48 +65,9 @@ export function attachmentKey(orgId: string, target: AttachmentTarget, name: str
   return scopedKey(orgId, target.entity, target.id, target.field, name);
 }
 
-/** `org/<orgId>/pending/quarantine/<name>` — uploaded, validated, and not yet cleared to use. */
-export function quarantineKey(orgId: string, name: string): string {
-  return scopedKey(orgId, PENDING_SEGMENT, QUARANTINE_SEGMENT, name);
-}
-
-export function quarantinePrefix(orgId: string): string {
-  return `${pendingPrefix(orgId)}${QUARANTINE_SEGMENT}/`;
-}
-
 export const isPendingKey = (key: string, orgId: string): boolean =>
   key.startsWith(pendingPrefix(orgId));
 
-/** True while nothing has cleared the key. `promoteAttachment` refuses exactly this. */
-export const isQuarantinedKey = (key: string, orgId: string): boolean =>
-  key.startsWith(quarantinePrefix(orgId));
-
-export interface ReleaseQuarantineInput {
-  readonly disk: StorageDriver;
-  /** A key under `quarantinePrefix(orgId)`. */
-  readonly key: string;
-  readonly orgId: string;
-}
-
-/**
- * The app's scan said clean: move the object out of quarantine and onto the ordinary `pending/`
- * key, which `promoteAttachment` will accept. Copy then delete, for the reason promotion does —
- * a delete that ran first loses the bytes on a failed write.
- *
- * Releasing a key that is not quarantined returns it untouched rather than copying it onto
- * itself: a scan job that retries after a crash must not be a second round trip, and a `pending/`
- * key is already the released state.
- */
-export async function releaseQuarantine(input: ReleaseQuarantineInput): Promise<string> {
-  if (!isWithinOrg(input.key, input.orgId)) throw orgMismatch(input.key, input.orgId);
-  if (!isQuarantinedKey(input.key, input.orgId)) return input.key;
-  const name = input.key.slice(input.key.lastIndexOf('/') + 1);
-  const released = pendingKey(input.orgId, name);
-  await input.disk.copy(input.key, released);
-  await input.disk.delete(input.key);
-  return released;
-}
-
 export interface PromoteAttachmentInput {
   readonly disk: StorageDriver;
   /** A key `grantUpload` minted with no `target`. */
@@ -197,6 +145,14 @@ async function assertCopyIsWhatWasJudged(
  * pending too. A ranged read because `maxGetBytes` bounds the range, never the object. An overwrite
  * after that read is `X_STORAGE_OBJECT_CHANGED`, or the copy itself is judged, and never lands.
  *
+ * SCANNED before it attaches, when `runtime.ts` installs an `uploadScanner`: on a per-attempt copy
+ * no presigned URL can rewrite (`scannedAttempt`), which is then what is attached. Infected is
+ * `X_STORAGE_UPLOAD_INFECTED` with attempt and upload deleted; no verdict is
+ * `X_STORAGE_SCAN_UNAVAILABLE` with the attempt deleted and the upload still pending, unless
+ * `policy.onScanUnavailable` accepts; a `hold` verdict (a review, an async vendor scan) is
+ * `X_STORAGE_QUARANTINED`, the upload pending, and no policy overrides it. None ever touches the
+ * row's key. This is the ONE scan path: the v30 `quarantine: true` segment is retired.
+ *
  * A source that is gone with the destination already there is `X_STORAGE_ALREADY_PROMOTED`
  * (409, `meta.attachedKey`), never the destination answered as if this call had moved it. 27.1.0
  * answered it: a confirm sent twice then inserted a second row for one key, that insert failed,
@@ -213,7 +169,6 @@ export async function promoteAttachment(input: PromoteAttachmentInput): Promise<
   // Pending, not merely in-org: an attached key a client sent back belongs to another row, and the
   // copy-then-delete below would move that row's file here and delete theirs.
   if (!isPendingKey(input.key, input.orgId)) throw notPending(input.key, input.orgId);
-  if (isQuarantinedKey(input.key, input.orgId)) throw quarantined(input.key, input.orgId);
   // The type says required; an untyped caller upgrading from the four-field call does not read
   // types, and `input.policy.maxBytes` on `undefined` is a bare `TypeError` two lines down.
   assert(
@@ -235,16 +190,43 @@ export async function promoteAttachment(input: PromoteAttachmentInput): Promise<
     throw tooLarge(input.key, pending.size, input.policy.maxBytes);
   }
   await judge(disk, pending, input.key, input.policy);
+  const scanned = scanning() ? await scannedAttempt(disk, pending, input, name) : undefined;
+  const source = scanned ?? pending;
   const object = await disk.copy(
-    input.key,
+    scanned?.key ?? input.key,
     attached,
-    pending.etag === '' ? undefined : { ifMatch: pending.etag },
+    source.etag === '' ? undefined : { ifMatch: source.etag },
   );
-  await assertCopyIsWhatWasJudged(disk, pending, object, input.policy);
+  await assertCopyIsWhatWasJudged(disk, source, object, input.policy);
+  // The attempt is this call's scratch: a delete that fails leaves an orphan the sweep collects,
+  // never a refusal of a promotion that already happened.
+  if (scanned !== undefined) await disk.delete(scanned.key).catch(() => undefined);
   await disk.delete(input.key);
   return object;
 }
 
+/**
+ * With an `uploadScanner` installed, what is attached is a copy THIS call made and scanned: under
+ * `pending/scan/`, server-named (no presigned URL rewrites it after the scan) and its own (a
+ * refusal deletes it and nothing a doubled confirm attached). Judged like any copy first.
+ */
+async function scannedAttempt(
+  disk: StorageDriver,
+  pending: StorageObject,
+  input: PromoteAttachmentInput,
+  name: string,
+): Promise<StorageObject> {
+  const key = scopedKey(input.orgId, PENDING_SEGMENT, SCAN_SEGMENT, `${nanoid()}-${name}`);
+  const attempt = await disk.copy(
+    input.key,
+    key,
+    pending.etag === '' ? undefined : { ifMatch: pending.etag },
+  );
+  await assertCopyIsWhatWasJudged(disk, pending, attempt, input.policy);
+  await scanAttempt({ disk, pendingKey: input.key, attempt, policy: input.policy });
+  return attempt;
+}
+
 export interface SweepOrphansInput {
   readonly disk: StorageDriver;
   readonly orgId: string;
@@ -277,8 +259,8 @@ export interface SweepResult {
 
 /**
  * Delete every unattached upload past the window, and answer with what went and what did not.
- * Scoped to one org and to the `pending/` prefix — quarantine included, since it lives inside
- * that prefix: a sweep that could reach an attached key is a job that deletes production data
+ * Scoped to one org and to the `pending/` prefix — a `hold` included, since a held upload is still
+ * pending: a sweep that could reach an attached key is a job that deletes production data
  * the first time an app forgets to promote something.
  *
  * A refusal is recorded and the sweep continues. Stopping at the first one would leave the caller

package/src/driver-local-list.ts

@@ -57,7 +57,7 @@ export async function listLocalPage(input: LocalListInput): Promise<Page<Storage
       'local',
       prefix,
       error,
-      `make the disk root readable by this process, then retry: ls -ld ${renderFixShellArg(root, "'<the disk root>'")}`,
+      `ls -ld ${renderFixShellArg(root, "'<the disk root>'")}   # make the disk root readable by this process, then retry`,
     );
   }
   keys.sort();

package/src/driver-local-open.ts

@@ -0,0 +1,112 @@
+// Single responsibility: the local disk's PINNED read — the file opened and its revision checked
+// against the etag, at the call and again at the first pull, so the bytes streamed are that
+// revision's or the read refuses.
+
+// why: Bun has no handle API — `Bun.file(path)` reopens the path at every read, which is the race
+// this file exists to close, and `Bun.file(fd)` has no positioned read nor a close.
+import { type FileHandle, open } from 'node:fs/promises';
+import { etagOfFile, headObject, refusedRead } from './driver-local-read';
+import { objectNotFound } from './errors';
+import { revisionChanged } from './errors-stream';
+import { type ByteRange, streamedRange } from './range';
+
+/** What one pull reads: big enough to amortise a syscall, small enough to never matter. */
+const CHUNK_BYTES = 256 * 1024;
+
+export interface PinnedRead {
+  readonly root: string;
+  readonly key: string;
+  readonly disk: string;
+  readonly etag: string;
+  readonly range?: ByteRange | undefined;
+}
+
+/** Closed, whatever the close says: a read that has its answer does not trade it for a close error. */
+const closeQuietly = async (handle: FileHandle | undefined): Promise<void> => {
+  try {
+    await handle?.close();
+  } catch {
+    // Already closed, or the OS refused: either way the descriptor is no longer this read's.
+  }
+};
+
+/**
+ * One open file, proved to be revision `etag`: opened FIRST, then described by path. A write landing
+ * in between leaves the handle on the old bytes and the description on the new ones, so it refuses
+ * — never serves a mismatch. A commit writes the sidecar before it renames the bytes, so a handle
+ * on new bytes always meets a description at least that new.
+ */
+async function openChecked(read: PinnedRead): Promise<{ handle: FileHandle; size: number }> {
+  const { root, key, disk, etag } = read;
+  const handle = await open(`${root}/${key}`, 'r').catch(refusedRead(root, key, disk));
+  try {
+    const entry = await headObject(root, key, () => etagOfFile(root, key, disk));
+    if (entry === undefined) throw objectNotFound(disk, key);
+    if (entry.etag !== etag) throw revisionChanged(disk, key, etag);
+    return { handle, size: (await handle.stat()).size };
+  } catch (error) {
+    await closeQuietly(handle);
+    throw error;
+  }
+}
+
+/**
+ * The object at `key` as revision `etag`, or `X_STORAGE_OBJECT_CHANGED`; `range` as `streamRange`.
+ * Checked NOW and closed again, so a stream nobody reads holds no descriptor; the first pull reopens
+ * and checks the ETAG again. Never the inode alone: ext4 hands a freed inode straight back, so two
+ * puts left v3 at v1's inode number and it was served under v1's etag.
+ */
+export async function streamPinned(read: PinnedRead): Promise<ReadableStream<Uint8Array>> {
+  const { key, range } = read;
+  const checked = await openChecked(read);
+  await closeQuietly(checked.handle);
+  const { size } = checked;
+  const [first, last] =
+    range === undefined ? [0, size - 1] : streamedRange('local', key, range, size);
+  // The same etag is the same bytes, so the same size: the etag check is the whole proof.
+  const reopen = async (): Promise<FileHandle> => (await openChecked(read)).handle;
+  return streamOf(reopen, first, last + 1);
+}
+
+/** `[first, end)` off one handle opened at the first pull, closed on the last byte, a cancel or a failure. */
+function streamOf(
+  opener: () => Promise<FileHandle>,
+  first: number,
+  end: number,
+): ReadableStream<Uint8Array> {
+  let position = first;
+  let handle: FileHandle | undefined;
+  const close = async (): Promise<void> => {
+    await closeQuietly(handle);
+    handle = undefined;
+  };
+  return new ReadableStream<Uint8Array>(
+    {
+      async pull(controller) {
+        try {
+          const want = Math.min(CHUNK_BYTES, end - position);
+          if (want <= 0) {
+            await close();
+            return controller.close();
+          }
+          handle ??= await opener();
+          const buffer = new Uint8Array(want);
+          const { bytesRead } = await handle.read(buffer, 0, want, position);
+          if (bytesRead === 0) {
+            await close();
+            return controller.close();
+          }
+          position += bytesRead;
+          controller.enqueue(bytesRead === want ? buffer : buffer.subarray(0, bytesRead));
+        } catch (error) {
+          await close();
+          controller.error(error);
+        }
+      },
+      cancel: close,
+    },
+    // Pulled only when read: the default high-water mark of 1 pulls once at construction, which
+    // opened a descriptor for a body nobody would ever read (a 304, a dropped client).
+    { highWaterMark: 0 },
+  );
+}

package/src/driver-local-read.ts

@@ -33,7 +33,7 @@ async function pendingEtag(root: string, key: string): Promise<string | undefine
  * that is simply gone — deleted between the `exists()` and the read — is "not found", as it
  * would have been one call earlier.
  */
-const refusedRead =
+export const refusedRead =
   (root: string, key: string, disk: string) =>
   (error: unknown): never => {
     if (isStorageError(error)) throw error;

package/src/driver-local-stream.ts

@@ -76,6 +76,13 @@ export const discardStaged = async (path: string): Promise<void> => {
     .catch(() => undefined);
 };
 
+/**
+ * What the writer holds before a flush: one per MiB, not one per chunk, so a 64 KiB-chunk sender
+ * pays a sixteenth of the syscalls and backpressure still holds at a MiB of heap. Measured
+ * 2026-11-09, 512 MiB in 64 KiB chunks: 2.72 s → 2.53 s (the hash is most of the rest).
+ */
+export const LOCAL_FLUSH_BYTES = 1024 * 1024;
+
 /** Backpressure is the `flush`: awaiting it is what keeps a fast sender from filling the heap. */
 export async function stageStream(input: StageStreamInput): Promise<StagedStream> {
   const { root, key, disk, body, maxBytes } = input;
@@ -84,12 +91,16 @@ export async function stageStream(input: StageStreamInput): Promise<StagedStream
   let sink: ReturnType<ReturnType<typeof Bun.file>['writer']> | undefined;
   try {
     await mkdir(`${root}/${STAGING_DIR}`, { recursive: true });
-    const open = Bun.file(path).writer();
+    const open = Bun.file(path).writer({ highWaterMark: LOCAL_FLUSH_BYTES });
     sink = open;
-    const size = await pumpBounded(body, streamLimit('local', key, maxBytes), async (chunk) => {
+    let buffered = 0;
+    const size = await pumpBounded(body, streamLimit('local', key, maxBytes), (chunk) => {
       hasher.update(chunk);
       open.write(chunk);
-      await open.flush();
+      buffered += chunk.byteLength;
+      if (buffered < LOCAL_FLUSH_BYTES) return;
+      buffered = 0;
+      return Promise.resolve(open.flush()).then(() => undefined);
     });
     await open.end();
     sink = undefined;