@sproutboat/wire 0.5.0 → 0.7.0

package/src/broker.ts

@@ -18,8 +18,9 @@
  * the only SSRF control today.
  */
 import { Database, type Statement } from "bun:sqlite";
-import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, rmSync, statSync } from "node:fs";
+import { createHash, randomBytes } from "node:crypto";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statfsSync, statSync, writeFileSync } from "node:fs";
+import { open } from "node:fs/promises";
 import { dirname, join, normalize, resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { resolveAssetKey, type AssetManifest } from "@sproutboat/assets";
@@ -84,6 +85,16 @@ export type BrokerOptions = {
    * data outlives a redeploy.
    */
   resourceDir?: string;
+  /** Account whose R2 resources this broker may mutate. */
+  ownerId?: string;
+  /** Account-wide R2 byte ceiling. Zero disables the ceiling for local development. */
+  r2QuotaBytes?: number;
+  /** Resource ids belonging to ownerId, used to seed the shared R2 usage ledger. */
+  r2ResourceIds?: string[];
+  /** Free disk capacity retained while direct R2 uploads are accepted. */
+  r2MinFreeBytes?: number;
+  /** Test hook for checking the filesystem capacity available to temporary uploads. */
+  freeBytes?: (path: string) => number;
   token?: string;
   bindings?: Partial<Bindings>;
   secrets?: Record<string, string>;
@@ -110,14 +121,33 @@ type D1Result = {
 };
 type R2Row = {
   key: string;
-  /** TEXT from a v0 write, BLOB from a v1 one; sqlite hands each back as-is. */
-  body: string | Uint8Array;
   size: number;
   etag: string;
   uploaded: string;
   http_json: string;
   custom_json: string;
+  blob_id: string | null;
 };
+type R2UploadRow = {
+  key: string;
+  uploaded: string;
+  http_json: string;
+  custom_json: string;
+};
+type R2PartRow = { part_number: number; size: number; etag: string };
+type R2UploadIdentity = { bucket: string; key: string; upload_id: string };
+type R2TransferRow = {
+  bucket: string;
+  key: string;
+  method: string;
+  expires: number;
+  max_bytes: number;
+  expected_sha256: string;
+  http_json: string;
+  custom_json: string;
+  used: number;
+};
+const MULTIPART_EXPIRY_MS = 7 * 24 * 60 * 60 * 1000;
 const isNumber = (v: JsonValue | undefined): v is number => Number.isFinite(v);
 const sqlParams = (v: JsonValue | undefined): SqlParam[] => {
   if (!Array.isArray(v)) return [];
@@ -146,6 +176,8 @@ export type Broker = {
    * negotiation.
    */
   handleFrame(payload: Buffer): Promise<Buffer>;
+  /** Serve one reserved direct R2 upload or download request. */
+  transfer(request: Request): Promise<Response>;
   close(): void;
 };
 
@@ -234,11 +266,35 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
     conn.exec(
       "CREATE TABLE IF NOT EXISTS kv (ns TEXT NOT NULL, key TEXT NOT NULL, value TEXT NOT NULL, PRIMARY KEY (ns, key))",
     );
+    // #56 — no `body` column: an object's bytes live in their own file under
+    // `r2Dir` (or an in-memory map for `:memory:`), never in the SQLite row.
+    // Doubling every object through SQLite's own page cache on top of the
+    // buffer it already arrived in was the real cost driving #56's "large
+    // uploads make memory skyrocket" complaint, not just the JSON-escaping
+    // #63 already fixed.
     conn.exec(
-      "CREATE TABLE IF NOT EXISTS r2 (bucket TEXT NOT NULL, key TEXT NOT NULL, body TEXT NOT NULL, size INTEGER NOT NULL, " +
+      "CREATE TABLE IF NOT EXISTS r2 (bucket TEXT NOT NULL, key TEXT NOT NULL, size INTEGER NOT NULL, " +
         "etag TEXT NOT NULL, uploaded TEXT NOT NULL, http_json TEXT NOT NULL DEFAULT '{}', custom_json TEXT NOT NULL DEFAULT '{}', " +
+        "blob_id TEXT, " +
         "PRIMARY KEY (bucket, key))",
     );
+    const r2Columns = conn.query<{ name: string }, []>("PRAGMA table_info(r2)").all();
+    if (!r2Columns.some((column) => column.name === "blob_id")) conn.exec("ALTER TABLE r2 ADD COLUMN blob_id TEXT");
+    conn.exec(
+      "CREATE TABLE IF NOT EXISTS r2_upload (bucket TEXT NOT NULL, key TEXT NOT NULL, upload_id TEXT NOT NULL, " +
+        "uploaded TEXT NOT NULL, http_json TEXT NOT NULL DEFAULT '{}', custom_json TEXT NOT NULL DEFAULT '{}', " +
+        "PRIMARY KEY (bucket, key, upload_id))",
+    );
+    conn.exec(
+      "CREATE TABLE IF NOT EXISTS r2_part (bucket TEXT NOT NULL, key TEXT NOT NULL, upload_id TEXT NOT NULL, " +
+        "part_number INTEGER NOT NULL, size INTEGER NOT NULL, etag TEXT NOT NULL, " +
+        "PRIMARY KEY (bucket, key, upload_id, part_number))",
+    );
+    conn.exec(
+      "CREATE TABLE IF NOT EXISTS r2_transfer (token TEXT PRIMARY KEY, bucket TEXT NOT NULL, key TEXT NOT NULL, " +
+        "method TEXT NOT NULL, expires INTEGER NOT NULL, max_bytes INTEGER NOT NULL, expected_sha256 TEXT NOT NULL DEFAULT '', " +
+        "http_json TEXT NOT NULL DEFAULT '{}', custom_json TEXT NOT NULL DEFAULT '{}', used INTEGER NOT NULL DEFAULT 0)",
+    );
     conn.exec(
       "CREATE TABLE IF NOT EXISTS mq (queue TEXT NOT NULL, id TEXT PRIMARY KEY, body TEXT NOT NULL, " +
         "visible_at INTEGER NOT NULL, attempts INTEGER NOT NULL DEFAULT 0, dead INTEGER NOT NULL DEFAULT 0)",
@@ -286,6 +342,121 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
     return conn;
   };
 
+  const quotaOwner = opts.ownerId;
+  const quotaBytes = opts.r2QuotaBytes && opts.r2QuotaBytes > 0 ? opts.r2QuotaBytes : null;
+  const quotaDirectory = resourceDir;
+  if (quotaOwner && quotaDirectory && quotaBytes) mkdirSync(quotaDirectory, { recursive: true });
+  // One ledger for every account, shared by the brokers of all its deployments.
+  // Ticket reservations are recorded before an upload begins, so four accepted
+  // requests cannot each independently decide that the same remaining bytes fit.
+  const quotaDb = quotaOwner && quotaDirectory && quotaBytes
+    ? new Database(join(quotaDirectory, "r2-quota.sqlite"), { create: true })
+    : null;
+  if (quotaDb) {
+    const owner = quotaOwner!;
+    quotaDb.exec("PRAGMA journal_mode = WAL");
+    quotaDb.exec(
+      "CREATE TABLE IF NOT EXISTS r2_account_quota (owner TEXT PRIMARY KEY, used_bytes INTEGER NOT NULL, reserved_bytes INTEGER NOT NULL)",
+    );
+    quotaDb.exec(
+      "CREATE TABLE IF NOT EXISTS r2_quota_reservation (token TEXT PRIMARY KEY, owner TEXT NOT NULL, bytes INTEGER NOT NULL, expires INTEGER NOT NULL)",
+    );
+    quotaDb.exec(
+      "CREATE TABLE IF NOT EXISTS r2_transfer_metric (owner TEXT PRIMARY KEY, tickets_issued INTEGER NOT NULL DEFAULT 0, rejected_quota INTEGER NOT NULL DEFAULT 0, rejected_disk INTEGER NOT NULL DEFAULT 0, rejected_size INTEGER NOT NULL DEFAULT 0)",
+    );
+    const existing = quotaDb.query<{ owner: string }, [string]>("SELECT owner FROM r2_account_quota WHERE owner = ?").get(owner);
+    if (!existing) {
+      quotaDb.query("INSERT INTO r2_account_quota (owner, used_bytes, reserved_bytes) VALUES (?1, 0, 0)").run(owner);
+    }
+    quotaDb.query("INSERT OR IGNORE INTO r2_transfer_metric (owner) VALUES (?)").run(owner);
+  }
+
+  const committedR2Bytes = (): number => {
+    if (!quotaDirectory) return 0;
+    let used = 0;
+    for (const id of opts.r2ResourceIds ?? []) {
+      // Open through resourceDb so older resource files gain the multipart
+      // tables before the aggregate is queried.
+      const store = resourceDb(id);
+      used += store.query<{ bytes: number }, []>(
+        "SELECT (SELECT COALESCE(SUM(size), 0) FROM r2) + (SELECT COALESCE(SUM(size), 0) FROM r2_part) AS bytes",
+      ).get()?.bytes ?? 0;
+    }
+    return used;
+  };
+
+  const availableBytes = (): number => {
+    if (!quotaDirectory) return Number.POSITIVE_INFINITY;
+    if (opts.freeBytes) return opts.freeBytes(quotaDirectory);
+    const stats = statfsSync(quotaDirectory);
+    return Number(stats.bavail) * Number(stats.bsize);
+  };
+
+  const releaseExpiredR2Reservations = (now = Date.now()): void => {
+    if (!quotaDb || !quotaOwner) return;
+    quotaDb.query("DELETE FROM r2_quota_reservation WHERE owner = ?1 AND expires < ?2").run(quotaOwner, now);
+    const reserved = quotaDb.query<{ bytes: number }, [string]>(
+      "SELECT COALESCE(SUM(bytes), 0) AS bytes FROM r2_quota_reservation WHERE owner = ?",
+    ).get(quotaOwner)?.bytes ?? 0;
+    quotaDb.query("UPDATE r2_account_quota SET reserved_bytes = ?1 WHERE owner = ?2").run(reserved, quotaOwner);
+  };
+
+  const reserveR2 = (token: string, bytes: number, expires: number): "ok" | "quota" | "disk" => {
+    if (!quotaDb || !quotaOwner || !quotaBytes) return "ok";
+    quotaDb.exec("BEGIN IMMEDIATE");
+    try {
+      releaseExpiredR2Reservations();
+      const used = committedR2Bytes();
+      const reserved = quotaDb.query<{ bytes: number }, [string]>(
+        "SELECT COALESCE(SUM(bytes), 0) AS bytes FROM r2_quota_reservation WHERE owner = ?",
+      ).get(quotaOwner)?.bytes ?? 0;
+      quotaDb.query("UPDATE r2_account_quota SET used_bytes = ?1, reserved_bytes = ?2 WHERE owner = ?3").run(used, reserved, quotaOwner);
+      if (used + reserved + bytes > quotaBytes) {
+        quotaDb.exec("ROLLBACK");
+        return "quota";
+      }
+      const floor = Math.max(opts.r2MinFreeBytes ?? 0, 0);
+      if (availableBytes() < bytes + floor) {
+        quotaDb.exec("ROLLBACK");
+        return "disk";
+      }
+      quotaDb.query("INSERT INTO r2_quota_reservation (token, owner, bytes, expires) VALUES (?1, ?2, ?3, ?4)").run(token, quotaOwner, bytes, expires);
+      quotaDb.query("UPDATE r2_account_quota SET reserved_bytes = ?1 WHERE owner = ?2").run(reserved + bytes, quotaOwner);
+      quotaDb.exec("COMMIT");
+      return "ok";
+    } catch (error) {
+      quotaDb.exec("ROLLBACK");
+      throw error;
+    }
+  };
+
+  const settleR2 = (token: string): void => {
+    if (!quotaDb || !quotaOwner) return;
+    quotaDb.exec("BEGIN IMMEDIATE");
+    try {
+      const reservation = quotaDb.query<{ bytes: number }, [string]>("SELECT bytes FROM r2_quota_reservation WHERE token = ?").get(token);
+      if (!reservation) {
+        quotaDb.exec("COMMIT");
+        return;
+      }
+      quotaDb.query("DELETE FROM r2_quota_reservation WHERE token = ?").run(token);
+      const used = committedR2Bytes();
+      const reserved = quotaDb.query<{ bytes: number }, [string]>(
+        "SELECT COALESCE(SUM(bytes), 0) AS bytes FROM r2_quota_reservation WHERE owner = ?",
+      ).get(quotaOwner)?.bytes ?? 0;
+      quotaDb.query("UPDATE r2_account_quota SET used_bytes = ?1, reserved_bytes = ?2 WHERE owner = ?3").run(used, reserved, quotaOwner);
+      quotaDb.exec("COMMIT");
+    } catch (error) {
+      quotaDb.exec("ROLLBACK");
+      throw error;
+    }
+  };
+
+  const recordR2TransferMetric = (field: "tickets_issued" | "rejected_quota" | "rejected_disk" | "rejected_size"): void => {
+    if (!quotaDb || !quotaOwner) return;
+    quotaDb.query(`UPDATE r2_transfer_metric SET ${field} = ${field} + 1 WHERE owner = ?`).run(quotaOwner);
+  };
+
   /**
    * Where a KV / R2 / queue binding stores: its resource's own file keyed by
    * `id` when the config bound it to one, else the per-broker `db` partitioned
@@ -414,15 +585,491 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
     return { path: dest, bytes: statSync(dest).size };
   };
 
-  /** An object body as bytes, whichever storage class it came back in. */
-  const r2Bytes = (body: string | Uint8Array): Uint8Array =>
-    body instanceof Uint8Array ? body : new TextEncoder().encode(body);
+  /**
+   * #56 — an object's bytes never enter SQLite; they live in their own file,
+   * named by a hash of bucket+key (so unicode keys and directory traversal
+   * are both non-issues), colocated with whichever store file holds that
+   * bucket's metadata — the main `db` for a bare-string binding, the
+   * resource's own file under `resourceDir` for an account-level one (#74) —
+   * so blobs persist across a redeploy exactly when that metadata does.
+   * `:memory:` stores (tests, `db: ":memory:"`) fall back to an in-memory map.
+   */
+  const r2MemBlobs = new Map<string, Uint8Array>();
+  const r2MemParts = new Map<string, Uint8Array>();
+  const r2BlobId = (bucketPart: string, key: string, generation?: string | null): string =>
+    createHash("sha256")
+      .update(generation ? `${bucketPart}\0${key}\0${generation}` : `${bucketPart}\0${key}`)
+      .digest("hex");
+  const r2BlobDir = (store: Database): string | null => {
+    const file = store.filename;
+    return file && file !== ":memory:" ? join(dirname(resolve(file)), "r2-blobs") : null;
+  };
+  const r2BlobPath = (store: Database, bucketPart: string, key: string, generation?: string | null): string | null => {
+    const dir = r2BlobDir(store);
+    return dir ? join(dir, `${r2BlobId(bucketPart, key, generation)}.blob`) : null;
+  };
+  const r2BlobMemKey = (bucketPart: string, key: string, generation?: string | null): string =>
+    generation ? `${bucketPart}\0${key}\0${generation}` : `${bucketPart}\0${key}`;
+  const r2WriteBlob = (
+    store: Database,
+    bucketPart: string,
+    key: string,
+    bytes: Uint8Array,
+    generation: string,
+  ): void => {
+    const path = r2BlobPath(store, bucketPart, key, generation);
+    if (!path) {
+      r2MemBlobs.set(r2BlobMemKey(bucketPart, key, generation), bytes);
+      return;
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    const temporary = `${path}.tmp`;
+    writeFileSync(temporary, bytes);
+    renameSync(temporary, path);
+  };
+  const r2ReadBlob = (
+    store: Database,
+    bucketPart: string,
+    key: string,
+    generation?: string | null,
+  ): Uint8Array | null => {
+    const path = r2BlobPath(store, bucketPart, key, generation);
+    if (!path) return r2MemBlobs.get(r2BlobMemKey(bucketPart, key, generation)) ?? null;
+    return existsSync(path) ? readFileSync(path) : null;
+  };
+  const r2DeleteBlob = (store: Database, bucketPart: string, key: string, generation?: string | null): void => {
+    const path = r2BlobPath(store, bucketPart, key, generation);
+    if (!path) {
+      r2MemBlobs.delete(r2BlobMemKey(bucketPart, key, generation));
+      return;
+    }
+    if (existsSync(path)) rmSync(path);
+  };
+  const r2PartId = (bucketPart: string, key: string, uploadId: string, partNumber: number): string =>
+    createHash("sha256").update(`${bucketPart}\0${key}\0${uploadId}\0${partNumber}`).digest("hex");
+  const r2PartPath = (
+    store: Database,
+    bucketPart: string,
+    key: string,
+    uploadId: string,
+    partNumber: number,
+  ): string | null => {
+    const file = store.filename;
+    if (!file || file === ":memory:") return null;
+    return join(dirname(resolve(file)), "r2-parts", `${r2PartId(bucketPart, key, uploadId, partNumber)}.part`);
+  };
+  const r2PartMemKey = (bucketPart: string, key: string, uploadId: string, partNumber: number): string =>
+    `${bucketPart}\0${key}\0${uploadId}\0${partNumber}`;
+  const r2WritePart = (
+    store: Database,
+    bucketPart: string,
+    key: string,
+    uploadId: string,
+    partNumber: number,
+    bytes: Uint8Array,
+  ): void => {
+    const path = r2PartPath(store, bucketPart, key, uploadId, partNumber);
+    if (!path) {
+      r2MemParts.set(r2PartMemKey(bucketPart, key, uploadId, partNumber), bytes);
+      return;
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    const temporary = `${path}.tmp`;
+    writeFileSync(temporary, bytes);
+    renameSync(temporary, path);
+  };
+  const r2ReadPart = (
+    store: Database,
+    bucketPart: string,
+    key: string,
+    uploadId: string,
+    partNumber: number,
+  ): Uint8Array | null => {
+    const path = r2PartPath(store, bucketPart, key, uploadId, partNumber);
+    if (!path) return r2MemParts.get(r2PartMemKey(bucketPart, key, uploadId, partNumber)) ?? null;
+    return existsSync(path) ? readFileSync(path) : null;
+  };
+  const r2DeletePart = (
+    store: Database,
+    bucketPart: string,
+    key: string,
+    uploadId: string,
+    partNumber: number,
+  ): void => {
+    const path = r2PartPath(store, bucketPart, key, uploadId, partNumber);
+    if (!path) {
+      r2MemParts.delete(r2PartMemKey(bucketPart, key, uploadId, partNumber));
+      return;
+    }
+    if (existsSync(path)) rmSync(path);
+  };
+
+  const requireMultipart = (store: Database, bucket: string, key: string, uploadId: string): R2UploadRow => {
+    const row = store
+      .query<R2UploadRow, [string, string, string]>(
+        "SELECT key, uploaded, http_json, custom_json FROM r2_upload WHERE bucket = ? AND key = ? AND upload_id = ?",
+      )
+      .get(bucket, key, uploadId);
+    if (!row) throw new Error("multipart upload not found");
+    return row;
+  };
+
+  const multipartParts = (store: Database, bucket: string, key: string, uploadId: string): R2PartRow[] =>
+    store
+      .query<R2PartRow, [string, string, string]>(
+        "SELECT part_number, size, etag FROM r2_part WHERE bucket = ? AND key = ? AND upload_id = ? ORDER BY part_number",
+      )
+      .all(bucket, key, uploadId);
+
+  const requestedParts = (value: JsonValue | undefined): Array<{ partNumber: number; etag: string }> => {
+    if (!Array.isArray(value) || value.length === 0) throw new Error("complete requires at least one uploaded part");
+    return value.map((part) => {
+      const parsed = jsonObject(part);
+      const partNumber = Number(parsed?.partNumber);
+      const etag = isString(parsed?.etag) ? parsed.etag : "";
+      if (!Number.isSafeInteger(partNumber) || partNumber < 1 || partNumber > 10000 || !etag) {
+        throw new Error("invalid uploaded part");
+      }
+      return { partNumber, etag };
+    });
+  };
+
+  const validateCompletedParts = (stored: R2PartRow[], requested: Array<{ partNumber: number; etag: string }>): void => {
+    if (stored.length !== requested.length) throw new Error("uploaded parts do not match");
+    for (let index = 0; index < stored.length; index++) {
+      const actual = stored[index];
+      const expected = requested[index];
+      if (actual.part_number !== expected.partNumber || actual.etag !== expected.etag) {
+        throw new Error("uploaded parts do not match");
+      }
+      if (index > 0 && expected.partNumber <= requested[index - 1].partNumber) {
+        throw new Error("uploaded parts must be ordered by partNumber");
+      }
+      if (index < stored.length - 1 && actual.size !== stored[0].size) {
+        throw new Error("all multipart parts except the last must have the same size");
+      }
+      if (index === stored.length - 1 && stored.length > 1 && actual.size > stored[0].size) {
+        throw new Error("the last multipart part cannot be larger than the others");
+      }
+    }
+  };
+
+  const deleteMultipart = (store: Database, bucket: string, key: string, uploadId: string): void => {
+    for (const part of multipartParts(store, bucket, key, uploadId)) {
+      r2DeletePart(store, bucket, key, uploadId, part.part_number);
+    }
+    store.query("DELETE FROM r2_part WHERE bucket = ? AND key = ? AND upload_id = ?").run(bucket, key, uploadId);
+    store.query("DELETE FROM r2_upload WHERE bucket = ? AND key = ? AND upload_id = ?").run(bucket, key, uploadId);
+  };
+
+  const cleanupExpiredMultipart = (store: Database): void => {
+    const cutoff = new Date(Date.now() - MULTIPART_EXPIRY_MS).toISOString();
+    const expired = store
+      .query<R2UploadIdentity, [string]>("SELECT bucket, key, upload_id FROM r2_upload WHERE uploaded < ?")
+      .all(cutoff);
+    for (const upload of expired) deleteMultipart(store, upload.bucket, upload.key, upload.upload_id);
+  };
+
+  const commitR2Metadata = (
+    store: Database,
+    bucket: string,
+    row: R2Row,
+    previous: Pick<R2Row, "blob_id"> | null,
+  ): void => {
+    try {
+      store
+        .query(
+          "INSERT INTO r2 (bucket, key, size, etag, uploaded, http_json, custom_json, blob_id) " +
+            "VALUES (?1,?2,?3,?4,?5,?6,?7,?8) " +
+            "ON CONFLICT (bucket, key) DO UPDATE SET size=?3, etag=?4, uploaded=?5, http_json=?6, " +
+            "custom_json=?7, blob_id=?8",
+        )
+        .run(bucket, row.key, row.size, row.etag, row.uploaded, row.http_json, row.custom_json, row.blob_id);
+    } catch (error) {
+      if (previous?.blob_id !== row.blob_id) r2DeleteBlob(store, bucket, row.key, row.blob_id);
+      throw error;
+    }
+    if (previous && previous.blob_id !== row.blob_id) r2DeleteBlob(store, bucket, row.key, previous.blob_id);
+  };
+
+  const putR2 = (
+    store: Database,
+    bucket: string,
+    key: string,
+    bytes: Uint8Array,
+    httpJson: string,
+    customJson: string,
+  ): R2Row => {
+    const previous = store
+      .query<Pick<R2Row, "blob_id">, [string, string]>("SELECT blob_id FROM r2 WHERE bucket = ? AND key = ?")
+      .get(bucket, key);
+    const etag = createHash("sha256").update(bytes).digest("hex");
+    const row: R2Row = {
+      key,
+      size: bytes.byteLength,
+      etag,
+      uploaded: new Date().toISOString(),
+      http_json: httpJson,
+      custom_json: customJson,
+      blob_id: etag,
+    };
+    r2WriteBlob(store, bucket, key, bytes, etag);
+    commitR2Metadata(store, bucket, row, previous);
+    return row;
+  };
+
+  const transferLimit = (): number => {
+    const configured = Number(process.env.SB_R2_TRANSFER_MAX_BYTES);
+    return Number.isSafeInteger(configured) && configured > 0 ? configured : 5 * 1024 * 1024 * 1024;
+  };
+  let activeUploads = 0;
+  const maxActiveUploads = 4;
+
+  const cleanupTransferTemps = (store: Database): void => {
+    const directory = r2BlobDir(store);
+    if (!directory || !existsSync(directory)) return;
+    const now = Date.now();
+    const cutoff = Date.now() - 24 * 60 * 60 * 1000;
+    for (const name of readdirSync(directory)) {
+      if (!/^[0-9a-f]{24}\.upload\.tmp$/.test(name)) continue;
+      const path = join(directory, name);
+      try {
+        const tokenValue = name.slice(0, 24);
+        const ticket = store.query<{ expires: number }, [string]>("SELECT expires FROM r2_transfer WHERE token = ?").get(tokenValue);
+        if (!ticket || ticket.expires < now || statSync(path).mtimeMs < cutoff) rmSync(path);
+      } catch (error) {
+        if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) throw error;
+      }
+    }
+  };
+
+  const transferPath = (binding: string, tokenValue: string): string =>
+    `/__sb/r2/transfer/${encodeURIComponent(binding)}/${tokenValue}`;
 
-  /** An object body as text, for the v0 reply shape that carries it in JSON.
-   *  A binary object stored by a v1 client cannot survive this, which is why
-   *  v1 exists — but returning a decoded string beats returning `{"0":...}`. */
-  const r2Text = (body: string | Uint8Array): string =>
-    body instanceof Uint8Array ? new TextDecoder().decode(body) : body;
+  const parseRange = (header: string | null, size: number): { start: number; end: number } | null => {
+    if (!header) return { start: 0, end: Math.max(0, size - 1) };
+    const match = /^bytes=(\d*)-(\d*)$/.exec(header.trim());
+    if (!match || size === 0) return null;
+    if (!match[1]) {
+      const suffix = Number(match[2]);
+      if (!Number.isSafeInteger(suffix) || suffix <= 0) return null;
+      return { start: Math.max(0, size - suffix), end: size - 1 };
+    }
+    const start = Number(match[1]);
+    const requestedEnd = match[2] ? Number(match[2]) : size - 1;
+    if (!Number.isSafeInteger(start) || !Number.isSafeInteger(requestedEnd) || start < 0 || start >= size || requestedEnd < start) return null;
+    return { start, end: Math.min(requestedEnd, size - 1) };
+  };
+
+  const transfer = async (request: Request): Promise<Response> => {
+    const url = new URL(request.url);
+    const match = /^\/__sb\/r2\/transfer\/([A-Z][A-Z0-9_]*)\/([0-9a-f]{24})$/.exec(url.pathname);
+    if (!match) return new Response("not found", { status: 404 });
+    let store: Database;
+    let bucket: string;
+    try {
+      ({ store, part: bucket } = storeFor("r2", requireR2(match[1])));
+    } catch {
+      return new Response("not found", { status: 404 });
+    }
+    const tokenValue = match[2];
+    const ticket = store
+      .query<R2TransferRow, [string]>(
+        "SELECT bucket, key, method, expires, max_bytes, expected_sha256, http_json, custom_json, used " +
+          "FROM r2_transfer WHERE token = ?",
+      )
+      .get(tokenValue);
+    const method = request.method.toUpperCase();
+    const allowedMethod = ticket?.method === "upload" ? "PUT" : ticket?.method === "download" ? "GET, HEAD" : "";
+    if (!ticket || ticket.bucket !== bucket || ticket.used || ticket.expires < Date.now()) {
+      return new Response("transfer ticket expired or already used", { status: 410 });
+    }
+    if ((ticket.method === "upload" && method !== "PUT") || (ticket.method === "download" && method !== "GET" && method !== "HEAD")) {
+      return new Response("method not allowed", { status: 405, headers: { allow: allowedMethod } });
+    }
+    if (ticket.method === "download") {
+      const row = store.query<R2Row, [string, string]>("SELECT * FROM r2 WHERE bucket = ? AND key = ?").get(bucket, ticket.key);
+      if (!row) return new Response("not found", { status: 404 });
+      const etag = `"${row.etag}"`;
+      if (request.headers.get("if-none-match") === etag) return new Response(null, { status: 304, headers: { etag } });
+      const rangeHeader = request.headers.get("range");
+      const range = parseRange(rangeHeader, row.size);
+      if (!range) {
+        return new Response(null, { status: 416, headers: { "content-range": `bytes */${row.size}`, etag } });
+      }
+      const path = r2BlobPath(store, bucket, ticket.key, row.blob_id);
+      if (!path || !existsSync(path)) return new Response("not found", { status: 404 });
+      const claimed = store.query("UPDATE r2_transfer SET used = 1 WHERE token = ? AND used = 0").run(tokenValue);
+      if (claimed.changes !== 1) return new Response("transfer ticket already used", { status: 410 });
+      const length = row.size === 0 ? 0 : range.end - range.start + 1;
+      const metadata = jsonObject(parseJsonValue(row.http_json));
+      const headers = new Headers({
+        "accept-ranges": "bytes",
+        "content-length": String(length),
+        etag,
+      });
+      if (isString(metadata?.contentType)) headers.set("content-type", metadata.contentType);
+      if (rangeHeader) headers.set("content-range", `bytes ${range.start}-${range.end}/${row.size}`);
+      const body = method === "HEAD" ? null : Bun.file(path).slice(range.start, range.start + length);
+      return new Response(body, { status: rangeHeader ? 206 : 200, headers });
+    }
+
+    const declared = request.headers.has("content-length") ? Number(request.headers.get("content-length")) : NaN;
+    if (request.headers.has("content-length") && (!Number.isSafeInteger(declared) || declared < 0)) {
+      return new Response("invalid content length", { status: 400 });
+    }
+    if (Number.isFinite(declared) && declared > ticket.max_bytes) return new Response("upload too large", { status: 413 });
+    const directory = r2BlobDir(store);
+    if (!directory) return new Response("direct transfers require a file-backed store", { status: 503 });
+    if (activeUploads >= maxActiveUploads) {
+      return new Response("too many active uploads", { status: 503, headers: { "retry-after": "5" } });
+    }
+    const claimed = store.query("UPDATE r2_transfer SET used = 1 WHERE token = ? AND used = 0").run(tokenValue);
+    if (claimed.changes !== 1) return new Response("transfer ticket already used", { status: 410 });
+    activeUploads++;
+    const temporary = join(directory, `${tokenValue}.upload.tmp`);
+    await (async () => {
+      mkdirSync(directory, { recursive: true });
+      const reservation = await open(temporary, "wx");
+      await reservation.close();
+    })().catch((error) => {
+      activeUploads--;
+      throw error;
+    });
+    const writer = Bun.file(temporary).writer({ highWaterMark: 64 * 1024 });
+    const hash = createHash("sha256");
+    let size = 0;
+    try {
+      if (request.body) {
+        for await (const chunk of request.body) {
+          size += chunk.byteLength;
+          if (size > ticket.max_bytes) throw new RangeError("upload too large");
+          const floor = Math.max(opts.r2MinFreeBytes ?? 0, 0);
+          if (floor > 0 && availableBytes() < chunk.byteLength + floor) {
+            const error = new Error("R2 storage is temporarily unavailable");
+            Object.assign(error, { code: "SB_R2_DISK_FLOOR" });
+            throw error;
+          }
+          hash.update(chunk);
+          const written = await writer.write(chunk);
+          if (written !== chunk.byteLength) throw new Error("upload write was incomplete");
+        }
+      }
+      await writer.end();
+      const persisted = await open(temporary, "r");
+      try {
+        await persisted.sync();
+      } finally {
+        await persisted.close();
+      }
+      const etag = hash.digest("hex");
+      if (ticket.expected_sha256 && ticket.expected_sha256 !== etag) {
+        rmSync(temporary);
+        settleR2(tokenValue);
+        return Response.json({ error: "sha256 mismatch", actual: etag }, { status: 422 });
+      }
+      const destination = r2BlobPath(store, bucket, ticket.key, etag)!;
+      renameSync(temporary, destination);
+      const previous = store
+        .query<Pick<R2Row, "blob_id" | "size">, [string, string]>("SELECT blob_id, size FROM r2 WHERE bucket = ? AND key = ?")
+        .get(bucket, ticket.key);
+      const row: R2Row = {
+        key: ticket.key,
+        size,
+        etag,
+        uploaded: new Date().toISOString(),
+        http_json: ticket.http_json,
+        custom_json: ticket.custom_json,
+        blob_id: etag,
+      };
+      commitR2Metadata(store, bucket, row, previous);
+      settleR2(tokenValue);
+      return Response.json({ object: r2Row(row) }, { status: 201, headers: { etag: `"${etag}"` } });
+    } catch (error) {
+      try {
+        await writer.end();
+      } catch {
+        // Preserve the original upload failure while releasing the file sink.
+      }
+      if (existsSync(temporary)) rmSync(temporary);
+      settleR2(tokenValue);
+      if (error instanceof RangeError) {
+        recordR2TransferMetric("rejected_size");
+        return new Response(error.message, { status: 413 });
+      }
+      if (error instanceof Error && "code" in error && (error.code === "ENOSPC" || error.code === "SB_R2_DISK_FLOOR")) {
+        recordR2TransferMetric("rejected_disk");
+        return new Response("R2 storage is temporarily unavailable", { status: 507 });
+      }
+      throw error;
+    } finally {
+      activeUploads--;
+    }
+  };
+
+  const completeMultipart = (
+    store: Database,
+    bucket: string,
+    key: string,
+    uploadId: string,
+    requested: Array<{ partNumber: number; etag: string }>,
+  ): ReturnType<typeof r2Row> => {
+    const upload = requireMultipart(store, bucket, key, uploadId);
+    const parts = multipartParts(store, bucket, key, uploadId);
+    validateCompletedParts(parts, requested);
+
+    const hash = createHash("sha256");
+    let size = 0;
+    const blobDirectory = r2BlobDir(store);
+    let inMemoryBody: Uint8Array | null = null;
+    let temporary: string | null = null;
+    if (blobDirectory) {
+      mkdirSync(blobDirectory, { recursive: true });
+      temporary = join(blobDirectory, `${uploadId}.tmp`);
+      writeFileSync(temporary, new Uint8Array(0));
+      try {
+        for (const part of parts) {
+          const bytes = r2ReadPart(store, bucket, key, uploadId, part.part_number);
+          if (!bytes || bytes.byteLength !== part.size) throw new Error(`multipart part ${part.part_number} is missing`);
+          appendFileSync(temporary, bytes);
+          hash.update(bytes);
+          size += bytes.byteLength;
+        }
+      } catch (error) {
+        if (existsSync(temporary)) rmSync(temporary);
+        throw error;
+      }
+    } else {
+      const chunks: Uint8Array[] = [];
+      for (const part of parts) {
+        const bytes = r2ReadPart(store, bucket, key, uploadId, part.part_number);
+        if (!bytes || bytes.byteLength !== part.size) throw new Error(`multipart part ${part.part_number} is missing`);
+        chunks.push(bytes);
+        hash.update(bytes);
+        size += bytes.byteLength;
+      }
+      inMemoryBody = Buffer.concat(chunks);
+    }
+
+    const etag = hash.digest("hex");
+    const previous = store
+      .query<Pick<R2Row, "blob_id">, [string, string]>("SELECT blob_id FROM r2 WHERE bucket = ? AND key = ?")
+      .get(bucket, key);
+    if (temporary) renameSync(temporary, r2BlobPath(store, bucket, key, etag)!);
+    else r2WriteBlob(store, bucket, key, inMemoryBody ?? new Uint8Array(0), etag);
+    const row: R2Row = {
+      key,
+      size,
+      etag,
+      uploaded: new Date().toISOString(),
+      http_json: upload.http_json,
+      custom_json: upload.custom_json,
+      blob_id: etag,
+    };
+    commitR2Metadata(store, bucket, row, previous);
+    deleteMultipart(store, bucket, key, uploadId);
+    return r2Row(row);
+  };
 
   const r2Row = (r: R2Row) => ({
     key: r.key,
@@ -617,40 +1264,129 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
 
       case "r2.put": {
         const { store, part: bucket } = storeFor("r2", requireR2(msg.bucket));
-        const body = str(msg.body);
-        const etag = createHash("sha256").update(body).digest("hex");
+        const key = str(msg.key);
+        const bytes = new TextEncoder().encode(str(msg.body));
+        return {
+          ok: true,
+          object: r2Row(
+            putR2(
+              store,
+              bucket,
+              key,
+              bytes,
+              JSON.stringify(msg.httpMetadata ?? {}),
+              JSON.stringify(msg.customMetadata ?? {}),
+            ),
+          ),
+        };
+      }
+      case "r2.multipart.create": {
+        const { store, part: bucket } = storeFor("r2", requireR2(msg.bucket));
+        cleanupExpiredMultipart(store);
+        const key = str(msg.key);
+        const uploadId = str(msg.uploadId) || newId();
+        const uploaded = new Date().toISOString();
         store
           .query(
-            "INSERT INTO r2 (bucket, key, body, size, etag, uploaded, http_json, custom_json) VALUES (?1,?2,?3,?4,?5,?6,?7,?8) " +
-              "ON CONFLICT (bucket, key) DO UPDATE SET body=?3, size=?4, etag=?5, uploaded=?6, http_json=?7, custom_json=?8",
+            "INSERT INTO r2_upload (bucket, key, upload_id, uploaded, http_json, custom_json) VALUES (?1,?2,?3,?4,?5,?6) " +
+              "ON CONFLICT (bucket, key, upload_id) DO NOTHING",
           )
           .run(
             bucket,
-            str(msg.key),
-            body,
-            Buffer.byteLength(body),
-            etag,
-            new Date().toISOString(),
+            key,
+            uploadId,
+            uploaded,
             JSON.stringify(msg.httpMetadata ?? {}),
             JSON.stringify(msg.customMetadata ?? {}),
           );
-        return {
-          ok: true,
-          object: { key: str(msg.key), size: Buffer.byteLength(body), etag, uploaded: new Date().toISOString() },
-        };
+        return { ok: true, key, uploadId };
+      }
+      case "r2.transfer.create": {
+        const binding = requireR2(msg.bucket);
+        const { store, part: bucket } = storeFor("r2", binding);
+        const key = str(msg.key);
+        const method = msg.method === "download" ? "download" : msg.method === "upload" ? "upload" : "";
+        if (!method) throw new Error("transfer method must be upload or download");
+        const expiresIn = Math.min(Math.max(Number(msg.expiresIn) || 900, 30), 3600);
+        const expires = Date.now() + expiresIn * 1000;
+        const maxBytes =
+          method === "upload"
+            ? Math.min(Math.max(Number(msg.maxBytes) || 100 * 1024 * 1024, 1), transferLimit())
+            : 0;
+        const expectedSha256 = str(msg.sha256).toLowerCase();
+        if (expectedSha256 && !/^[0-9a-f]{64}$/.test(expectedSha256)) {
+          throw new Error("sha256 must be 64 hexadecimal characters");
+        }
+        store.query("DELETE FROM r2_transfer WHERE expires < ? OR used = 1").run(Date.now());
+        cleanupTransferTemps(store);
+        const tokenValue = randomBytes(12).toString("hex");
+        const reservation = method === "upload" ? reserveR2(tokenValue, maxBytes, expires) : "ok";
+        if (reservation === "quota") {
+          recordR2TransferMetric("rejected_quota");
+          throw new Error("R2 account quota would be exceeded");
+        }
+        if (reservation === "disk") {
+          recordR2TransferMetric("rejected_disk");
+          throw new Error("R2 storage is temporarily unavailable");
+        }
+        try {
+          store
+            .query(
+              "INSERT INTO r2_transfer (token, bucket, key, method, expires, max_bytes, expected_sha256, http_json, custom_json) " +
+                "VALUES (?1,?2,?3,?4,?5,?6,?7,?8,?9)",
+            )
+            .run(
+              tokenValue,
+              bucket,
+              key,
+              method,
+              expires,
+              maxBytes,
+              expectedSha256,
+              JSON.stringify(msg.httpMetadata ?? {}),
+              JSON.stringify(msg.customMetadata ?? {}),
+            );
+        } catch (error) {
+          if (reservation === "ok" && method === "upload") settleR2(tokenValue);
+          throw error;
+        }
+        recordR2TransferMetric("tickets_issued");
+        return { ok: true, url: transferPath(binding, tokenValue), expiresAt: new Date(expires).toISOString() };
+      }
+      case "r2.multipart.complete": {
+        const { store, part: bucket } = storeFor("r2", requireR2(msg.bucket));
+        const key = str(msg.key);
+        const uploadId = str(msg.uploadId);
+        const object = completeMultipart(store, bucket, key, uploadId, requestedParts(msg.parts));
+        return { ok: true, object };
+      }
+      case "r2.multipart.abort": {
+        const { store, part: bucket } = storeFor("r2", requireR2(msg.bucket));
+        const key = str(msg.key);
+        const uploadId = str(msg.uploadId);
+        requireMultipart(store, bucket, key, uploadId);
+        deleteMultipart(store, bucket, key, uploadId);
+        return { ok: true };
       }
       case "r2.get":
       case "r2.head": {
         const { store, part: bucket } = storeFor("r2", requireR2(msg.bucket));
-        const row = store
-          .query<R2Row, [string, string]>("SELECT * FROM r2 WHERE bucket = ? AND key = ?")
-          .get(bucket, str(msg.key));
+        const key = str(msg.key);
+        const row = store.query<R2Row, [string, string]>("SELECT * FROM r2 WHERE bucket = ? AND key = ?").get(bucket, key);
         if (!row) return { ok: true, found: false };
-        return { ok: true, found: true, object: r2Row(row), body: msg.op === "r2.get" ? r2Text(row.body) : undefined };
+        const body = msg.op === "r2.get"
+          ? new TextDecoder().decode(r2ReadBlob(store, bucket, key, row.blob_id) ?? new Uint8Array(0))
+          : undefined;
+        return { ok: true, found: true, object: r2Row(row), body };
       }
       case "r2.delete": {
         const { store, part: bucket } = storeFor("r2", requireR2(msg.bucket));
-        store.query("DELETE FROM r2 WHERE bucket = ? AND key = ?").run(bucket, str(msg.key));
+        const key = str(msg.key);
+        const row = store
+          .query<Pick<R2Row, "blob_id">, [string, string]>("SELECT blob_id FROM r2 WHERE bucket = ? AND key = ?")
+          .get(bucket, key);
+        store.query("DELETE FROM r2 WHERE bucket = ? AND key = ?").run(bucket, key);
+        if (row) r2DeleteBlob(store, bucket, key, row.blob_id);
         return { ok: true };
       }
       case "r2.list": {
@@ -832,38 +1568,51 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
    */
   async function dispatchBinary(msg: Frame, binary: Uint8Array): Promise<{ reply: Frame; bytes?: Uint8Array }> {
     if (msg.op === "r2.put") {
-      // The body arrived as bytes; store it as a blob rather than a string, so
-      // a put costs one copy instead of an escape, a parse and a re-encode.
+      // The body arrived as bytes; write it straight to its own file rather
+      // than into SQLite (#56) — no escape, no parse, no re-encode, and no
+      // second full-object copy through the database's own page cache.
+      const { store, part: bucket } = storeFor("r2", requireR2(msg.bucket));
+      const key = str(msg.key);
+      const row = putR2(
+        store,
+        bucket,
+        key,
+        binary,
+        JSON.stringify(msg.httpMetadata ?? {}),
+        JSON.stringify(msg.customMetadata ?? {}),
+      );
+      return { reply: { ok: true, object: r2Row(row) } };
+    }
+
+    if (msg.op === "r2.multipart.put") {
       const { store, part: bucket } = storeFor("r2", requireR2(msg.bucket));
+      const key = str(msg.key);
+      const uploadId = str(msg.uploadId);
+      const partNumber = Number(msg.partNumber);
+      if (!Number.isSafeInteger(partNumber) || partNumber < 1 || partNumber > 10000) {
+        throw new Error("partNumber must be an integer between 1 and 10000");
+      }
+      requireMultipart(store, bucket, key, uploadId);
       const etag = createHash("sha256").update(binary).digest("hex");
-      const uploaded = new Date().toISOString();
+      r2WritePart(store, bucket, key, uploadId, partNumber, binary);
       store
         .query(
-          "INSERT INTO r2 (bucket, key, body, size, etag, uploaded, http_json, custom_json) VALUES (?1,?2,?3,?4,?5,?6,?7,?8) " +
-            "ON CONFLICT (bucket, key) DO UPDATE SET body=?3, size=?4, etag=?5, uploaded=?6, http_json=?7, custom_json=?8",
+          "INSERT INTO r2_part (bucket, key, upload_id, part_number, size, etag) VALUES (?1,?2,?3,?4,?5,?6) " +
+            "ON CONFLICT (bucket, key, upload_id, part_number) DO UPDATE SET size=?5, etag=?6",
         )
-        .run(
-          bucket,
-          str(msg.key),
-          binary,
-          binary.byteLength,
-          etag,
-          uploaded,
-          JSON.stringify(msg.httpMetadata ?? {}),
-          JSON.stringify(msg.customMetadata ?? {}),
-        );
-      return {
-        reply: { ok: true, object: { key: str(msg.key), size: binary.byteLength, etag, uploaded } },
-      };
+        .run(bucket, key, uploadId, partNumber, binary.byteLength, etag);
+      return { reply: { ok: true, part: { partNumber, etag } } };
     }
 
     if (msg.op === "r2.get") {
       const { store, part: bucket } = storeFor("r2", requireR2(msg.bucket));
-      const row = store
-        .query<R2Row, [string, string]>("SELECT * FROM r2 WHERE bucket = ? AND key = ?")
-        .get(bucket, str(msg.key));
+      const key = str(msg.key);
+      const row = store.query<R2Row, [string, string]>("SELECT * FROM r2 WHERE bucket = ? AND key = ?").get(bucket, key);
       if (!row) return { reply: { ok: true, found: false } };
-      return { reply: { ok: true, found: true, object: r2Row(row) }, bytes: r2Bytes(row.body) };
+      return {
+        reply: { ok: true, found: true, object: r2Row(row) },
+        bytes: r2ReadBlob(store, bucket, key, row.blob_id) ?? new Uint8Array(0),
+      };
     }
 
     if (msg.op === "assets.get") {
@@ -901,7 +1650,14 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
       if (!msg) throw new Error("request frame was not a JSON object");
       if (token && str(msg.token) !== token) return frameOf(encodeV1({ ok: false, error: "unauthorized" }));
       const binary = new Uint8Array(payload.subarray(5 + jsonLen));
+      const id = isSafeInteger(msg.id) ? msg.id : null;
+      const replayKey = id === null ? null : `${str(msg.op)}:${id}`;
+      if (replayKey && REPLAYABLE.has(str(msg.op))) {
+        const seen = replayed.get(replayKey);
+        if (seen) return frameOf(encodeV1(seen));
+      }
       const { reply, bytes } = await dispatchBinary(msg, binary);
+      if (replayKey && REPLAYABLE.has(str(msg.op))) rememberReplay(replayKey, reply);
       return frameOf(encodeV1(reply, bytes));
     } catch (e) {
       return frameOf(encodeV1({ ok: false, error: e instanceof Error ? e.message : String(e) }));
@@ -928,6 +1684,11 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
     "d1.backup",
     "ratelimit.check",
     "r2.put",
+    "r2.multipart.create",
+    "r2.multipart.put",
+    "r2.multipart.complete",
+    "r2.multipart.abort",
+    "r2.transfer.create",
     "r2.delete",
     "do.storage.put",
     "do.storage.delete",
@@ -941,6 +1702,14 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
    *  milliseconds, so this only has to outlive a reconnect, not a session. */
   const REPLAY_WINDOW = 256;
 
+  const rememberReplay = (key: string, reply: Frame): void => {
+    replayed.set(key, reply);
+    if (replayed.size > REPLAY_WINDOW) {
+      const oldest = replayed.keys().next().value;
+      if (oldest !== undefined) replayed.delete(oldest);
+    }
+  };
+
   /**
    * Run `msg`, or replay what it answered last time. Keyed by the id the sprout
    * put on the request; a request without one is always run.
@@ -953,12 +1722,7 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
     const seen = replayed.get(key);
     if (seen) return seen;
     const reply = await dispatch(msg);
-    replayed.set(key, reply);
-    // Insertion-ordered, so the oldest key is the first one out.
-    if (replayed.size > REPLAY_WINDOW) {
-      const oldest = replayed.keys().next().value;
-      if (oldest !== undefined) replayed.delete(oldest);
-    }
+    rememberReplay(key, reply);
     return reply;
   }
 
@@ -1105,6 +1869,7 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
     dispatch,
     handlePayload,
     handleFrame,
+    transfer,
     close: () => {
       for (const t of timers) clearInterval(t);
       for (const conn of d1Conns.values()) conn.close();
@@ -1192,17 +1957,33 @@ export function listen(broker: Broker, hostname: string, port: number): BrokerSe
       },
     },
   });
-  return { port: server.port, stop: () => server.stop(true) };
+  return { port: server.port ?? port, stop: () => server.stop(true) };
+}
+
+/** Start the HTTP listener that serves short-lived direct R2 transfer tickets. */
+export function listenTransfers(broker: Broker, hostname: string, port: number): BrokerServer {
+  const configured = Number(process.env.SB_R2_TRANSFER_MAX_BYTES);
+  const maxRequestBodySize = Number.isSafeInteger(configured) && configured > 0 ? configured : 5 * 1024 * 1024 * 1024;
+  const server = Bun.serve({ hostname, port, maxRequestBodySize, fetch(request, server) {
+    server.timeout(request, 255);
+    return broker.transfer(request);
+  } });
+  return { port: server.port ?? port, stop: () => server.stop(true) };
 }
 
 if (import.meta.main) {
   const { values } = parseArgs({
     options: {
       port: { type: "string" },
+      "transfer-port": { type: "string" },
       token: { type: "string" },
       db: { type: "string" },
       "data-dir": { type: "string" },
       "resource-dir": { type: "string" },
+      "owner-id": { type: "string" },
+      "r2-quota-bytes": { type: "string" },
+      "r2-resource-ids": { type: "string" },
+      "r2-min-free-bytes": { type: "string" },
       bindings: { type: "string" },
       secrets: { type: "string" },
       "sprout-url": { type: "string" },
@@ -1251,6 +2032,10 @@ if (import.meta.main) {
     db: values.db,
     dataDir: values["data-dir"],
     resourceDir: values["resource-dir"],
+    ownerId: values["owner-id"],
+    r2QuotaBytes: Number(values["r2-quota-bytes"] ?? process.env.SPROUTBOAT_R2_QUOTA_BYTES) || undefined,
+    r2ResourceIds: values["r2-resource-ids"] ? String(values["r2-resource-ids"]).split(",").filter(Boolean) : undefined,
+    r2MinFreeBytes: Number(values["r2-min-free-bytes"] ?? process.env.SPROUTBOAT_R2_MIN_FREE_BYTES) || undefined,
     token: values.token ?? process.env.SB_BROKER_TOKEN,
     bindings,
     secrets,
@@ -1261,7 +2046,9 @@ if (import.meta.main) {
     dispatchEnabled: () => dispatchEnabled,
   });
   const { port } = listen(broker, "127.0.0.1", Number(values.port ?? process.env.SB_BROKER_PORT ?? 0));
+  const transferPort = Number(values["transfer-port"] ?? process.env.SB_R2_TRANSFER_PORT ?? 0);
+  const transferServer = transferPort > 0 ? listenTransfers(broker, "127.0.0.1", transferPort) : null;
   console.log(
-    `sproutboat broker: 127.0.0.1:${port} db=${values.db ?? ":memory:"} sprout=${values["sprout-url"] ?? process.env.SB_SPROUT_URL ?? "(none)"} dispatch=${dispatchEnabled ? "enabled" : "disabled"}`,
+    `sproutboat broker: 127.0.0.1:${port} transfer=${transferServer?.port ?? "off"} db=${values.db ?? ":memory:"} sprout=${values["sprout-url"] ?? process.env.SB_SPROUT_URL ?? "(none)"} dispatch=${dispatchEnabled ? "enabled" : "disabled"}`,
   );
 }