@rubytech/create-maxy-code 0.1.458 → 0.1.459

package/payload/platform/lib/storage-broker/dist/index.js

@@ -22,6 +22,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./authorize.js"), exports);
+__exportStar(require("./object-limits.js"), exports);
 __exportStar(require("./registry.js"), exports);
 __exportStar(require("./house-credential.js"), exports);
 __exportStar(require("./cf-exec.js"), exports);

package/payload/platform/lib/storage-broker/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA,mEAAmE;AACnE,EAAE;AACF,+EAA+E;AAC/E,2EAA2E;AAC3E,2EAA2E;AAC3E,uEAAuE;AACvE,4DAA4D;;;;;;;;;;;;;;;;AAE5D,iDAA+B;AAC/B,gDAA8B;AAC9B,wDAAsC;AACtC,+CAA6B;AAC7B,0DAAwC;AACxC,6CAA2B;AAC3B,iDAA+B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA,mEAAmE;AACnE,EAAE;AACF,+EAA+E;AAC/E,2EAA2E;AAC3E,2EAA2E;AAC3E,uEAAuE;AACvE,4DAA4D;;;;;;;;;;;;;;;;AAE5D,iDAA+B;AAC/B,qDAAmC;AACnC,gDAA8B;AAC9B,wDAAsC;AACtC,+CAA6B;AAC7B,0DAAwC;AACxC,6CAA2B;AAC3B,iDAA+B"}

package/payload/platform/lib/storage-broker/dist/object-limits.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The byte cap on R2 object transfer, and the arithmetic the routes need to
+ * enforce it before they buffer anything.
+ *
+ * One number, one home (Task 1695). The storage-broker MCP tools and the house
+ * ui routes both read the cap from here, so the process that rejects a too-large
+ * file and the process that would otherwise buffer it cannot drift apart.
+ *
+ * Deliberately dependency-free: the MCP imports this module directly, without
+ * the rest of the lib (cf-exec, registry, audit, remediate), which it has no use
+ * for. The ui route reads it through the barrel.
+ */
+/**
+ * The maximum size, in bytes, of an object moved through storage-r2-object-get
+ * or storage-r2-object-put.
+ *
+ * Set independently of the email plugin's OUTBOUND_ATTACHMENT_MAX_BYTES (25 MiB)
+ * even though the payload class is the same. The two exist for different reasons
+ * and must be free to move for different reasons: email's tracks an SMTP-side
+ * rejection threshold, this one tracks house-process memory. Do not couple them.
+ *
+ * Not bounded by R2. A single-part upload may be up to 5 GiB (doc-confirmed:
+ * developers.cloudflare.com/r2/platform/limits/), roughly fifty times this, and
+ * the v4 REST API states no separate object-size limit. This cap is the only
+ * bound on either transfer.
+ *
+ * The bound is not small: at the cap a get still leaves the house process
+ * holding the object and its base64 form, roughly 2.4x the object. That cost was
+ * weighed and accepted when the number was chosen.
+ */
+export declare const R2_OBJECT_MAX_BYTES: number;
+/** base64 emits 4 characters per 3 input bytes, padded up to the next quantum. */
+export declare function base64Ceiling(bytes: number): number;
+/**
+ * The largest JSON body /r2/object/put can legitimately carry.
+ *
+ * This bounds house memory; it does not adjudicate the last kilobyte. The exact
+ * decoded-byte rule lives in the MCP, which knows the source's size exactly.
+ */
+export declare const R2_OBJECT_PUT_MAX_BODY_BYTES: number;
+/**
+ * The over-cap message, worded once so the MCP and the routes agree. Names the
+ * offending object and the limit, which is what makes the failure actionable
+ * rather than an opaque out-of-memory kill.
+ *
+ * Exact bytes accompany the MiB figures because MiB alone rounds: an object one
+ * byte over the cap reads "100.0 MiB, which exceeds the 100.0 MiB limit", which
+ * is a message that appears to contradict itself and invites the reader to treat
+ * the rejection as a bug. The bytes are what make it legible; the MiB is what
+ * makes it quick.
+ */
+export declare function tooLargeMessage(what: string, actualBytes: number): string;
+//# sourceMappingURL=object-limits.d.ts.map

package/payload/platform/lib/storage-broker/dist/object-limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"object-limits.d.ts","sourceRoot":"","sources":["../src/object-limits.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,mBAAmB,QAAoB,CAAC;AAErD,kFAAkF;AAClF,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnD;AAUD;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,QAC0B,CAAC;AAMpE;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAIzE"}

package/payload/platform/lib/storage-broker/dist/object-limits.js

@@ -0,0 +1,72 @@
+"use strict";
+/**
+ * The byte cap on R2 object transfer, and the arithmetic the routes need to
+ * enforce it before they buffer anything.
+ *
+ * One number, one home (Task 1695). The storage-broker MCP tools and the house
+ * ui routes both read the cap from here, so the process that rejects a too-large
+ * file and the process that would otherwise buffer it cannot drift apart.
+ *
+ * Deliberately dependency-free: the MCP imports this module directly, without
+ * the rest of the lib (cf-exec, registry, audit, remediate), which it has no use
+ * for. The ui route reads it through the barrel.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.R2_OBJECT_PUT_MAX_BODY_BYTES = exports.R2_OBJECT_MAX_BYTES = void 0;
+exports.base64Ceiling = base64Ceiling;
+exports.tooLargeMessage = tooLargeMessage;
+/**
+ * The maximum size, in bytes, of an object moved through storage-r2-object-get
+ * or storage-r2-object-put.
+ *
+ * Set independently of the email plugin's OUTBOUND_ATTACHMENT_MAX_BYTES (25 MiB)
+ * even though the payload class is the same. The two exist for different reasons
+ * and must be free to move for different reasons: email's tracks an SMTP-side
+ * rejection threshold, this one tracks house-process memory. Do not couple them.
+ *
+ * Not bounded by R2. A single-part upload may be up to 5 GiB (doc-confirmed:
+ * developers.cloudflare.com/r2/platform/limits/), roughly fifty times this, and
+ * the v4 REST API states no separate object-size limit. This cap is the only
+ * bound on either transfer.
+ *
+ * The bound is not small: at the cap a get still leaves the house process
+ * holding the object and its base64 form, roughly 2.4x the object. That cost was
+ * weighed and accepted when the number was chosen.
+ */
+exports.R2_OBJECT_MAX_BYTES = 100 * 1024 * 1024;
+/** base64 emits 4 characters per 3 input bytes, padded up to the next quantum. */
+function base64Ceiling(bytes) {
+    return 4 * Math.ceil(bytes / 3);
+}
+/**
+ * Room for the put envelope's bucket, key and JSON punctuation, so a legal
+ * at-cap put is not rejected by its own key. Far above any realistic bucket+key
+ * length and far below the cap, so it cannot smuggle a meaningfully larger
+ * object.
+ */
+const PUT_ENVELOPE_ALLOWANCE_BYTES = 64 * 1024;
+/**
+ * The largest JSON body /r2/object/put can legitimately carry.
+ *
+ * This bounds house memory; it does not adjudicate the last kilobyte. The exact
+ * decoded-byte rule lives in the MCP, which knows the source's size exactly.
+ */
+exports.R2_OBJECT_PUT_MAX_BODY_BYTES = base64Ceiling(exports.R2_OBJECT_MAX_BYTES) + PUT_ENVELOPE_ALLOWANCE_BYTES;
+function formatMiB(bytes) {
+    return (bytes / 1024 / 1024).toFixed(1);
+}
+/**
+ * The over-cap message, worded once so the MCP and the routes agree. Names the
+ * offending object and the limit, which is what makes the failure actionable
+ * rather than an opaque out-of-memory kill.
+ *
+ * Exact bytes accompany the MiB figures because MiB alone rounds: an object one
+ * byte over the cap reads "100.0 MiB, which exceeds the 100.0 MiB limit", which
+ * is a message that appears to contradict itself and invites the reader to treat
+ * the rejection as a bug. The bytes are what make it legible; the MiB is what
+ * makes it quick.
+ */
+function tooLargeMessage(what, actualBytes) {
+    return `${what} is ${formatMiB(actualBytes)} MiB (${actualBytes} bytes), which exceeds the ${formatMiB(exports.R2_OBJECT_MAX_BYTES)} MiB (${exports.R2_OBJECT_MAX_BYTES} bytes) R2 object limit.`;
+}
+//# sourceMappingURL=object-limits.js.map

package/payload/platform/lib/storage-broker/dist/object-limits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"object-limits.js","sourceRoot":"","sources":["../src/object-limits.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;;AAuBH,sCAEC;AAkCD,0CAIC;AA7DD;;;;;;;;;;;;;;;;;GAiBG;AACU,QAAA,mBAAmB,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,CAAC;AAErD,kFAAkF;AAClF,SAAgB,aAAa,CAAC,KAAa;IACzC,OAAO,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;AAClC,CAAC;AAED;;;;;GAKG;AACH,MAAM,4BAA4B,GAAG,EAAE,GAAG,IAAI,CAAC;AAE/C;;;;;GAKG;AACU,QAAA,4BAA4B,GACvC,aAAa,CAAC,2BAAmB,CAAC,GAAG,4BAA4B,CAAC;AAEpE,SAAS,SAAS,CAAC,KAAa;IAC9B,OAAO,CAAC,KAAK,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAC1C,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAgB,eAAe,CAAC,IAAY,EAAE,WAAmB;IAC/D,OAAO,GAAG,IAAI,OAAO,SAAS,CAAC,WAAW,CAAC,SAAS,WAAW,8BAA8B,SAAS,CACpG,2BAAmB,CACpB,SAAS,2BAAmB,0BAA0B,CAAC;AAC1D,CAAC"}

package/payload/platform/lib/storage-broker/src/__tests__/cf-exec.test.ts

@@ -26,11 +26,18 @@ const throwingRun: RunFn = async () => {
 function recordingFetch(response: { ok: boolean; status: number; body: string }) {
   const calls: Array<{
     url: string;
-    init: { method: string; headers: Record<string, string>; body?: string };
+    init: { method: string; headers: Record<string, string>; body?: string | Uint8Array };
   }> = [];
   const fetchFn: FetchFn = async (url, init) => {
     calls.push({ url, init });
-    return { ok: response.ok, status: response.status, text: async () => response.body };
+    return {
+      ok: response.ok,
+      status: response.status,
+      text: async () => response.body,
+      // Task 1691 — r2ObjectGet reads the raw object body, so the seam carries
+      // arrayBuffer alongside text. The fake derives it from the same body.
+      arrayBuffer: async () => new TextEncoder().encode(response.body).buffer as ArrayBuffer,
+    };
   };
   return { fetchFn, calls };
 }
@@ -41,13 +48,18 @@ function recordingFetch(response: { ok: boolean; status: number; body: string })
 function sequenceFetch(responses: Array<{ ok: boolean; status: number; body: string }>) {
   const calls: Array<{
     url: string;
-    init: { method: string; headers: Record<string, string>; body?: string };
+    init: { method: string; headers: Record<string, string>; body?: string | Uint8Array };
   }> = [];
   const fetchFn: FetchFn = async (url, init) => {
     calls.push({ url, init });
     const r = responses[calls.length - 1];
     if (!r) throw new Error(`unexpected fetch call #${calls.length} to ${url}`);
-    return { ok: r.ok, status: r.status, text: async () => r.body };
+    return {
+      ok: r.ok,
+      status: r.status,
+      text: async () => r.body,
+      arrayBuffer: async () => new TextEncoder().encode(r.body).buffer as ArrayBuffer,
+    };
   };
   return { fetchFn, calls };
 }
@@ -99,7 +111,9 @@ test("d1Create creates the database via the D1 API with the house token, never w
   assert.equal(calls[0].init.method, "POST");
   assert.equal(calls[0].init.headers.Authorization, "Bearer cfat_x");
   assert.equal(calls[0].init.headers["Content-Type"], "application/json");
-  assert.deepEqual(JSON.parse(calls[0].init.body ?? ""), { name: "gls-new" });
+  // init.body widened to string | Uint8Array for the object-put path (Task
+  // 1691); d1Create still sends a JSON string.
+  assert.deepEqual(JSON.parse(String(calls[0].init.body ?? "")), { name: "gls-new" });
 });
 
 test("d1Create throws with the API error body on a non-2xx response", async () => {
@@ -338,3 +352,195 @@ test("makeHouseCfExec runs wrangler with the scoped token, not the minter", asyn
   await cf.d1List();
   assert.equal(sawToken, "scoped_tok", "wrangler saw the scoped token, not the minter");
 });
+
+// ---------------------------------------------------------------------------
+// Task 1691 — R2 object operations. Same discipline as r2List/d1Create: the
+// Cloudflare API behind an injectable fetch, wrangler never shelled (throwingRun
+// proves it), and every failure keeps its body.
+// ---------------------------------------------------------------------------
+
+function objectPage(keys: string[], opts: { cursor?: string; truncated?: boolean } = {}) {
+  return JSON.stringify({
+    success: true,
+    errors: [],
+    messages: [],
+    result: keys.map((key) => ({
+      key,
+      size: 10,
+      etag: "e1",
+      last_modified: "2026-01-01T00:00:00Z",
+    })),
+    result_info: { cursor: opts.cursor ?? "", is_truncated: opts.truncated ?? false },
+  });
+}
+
+test("r2ObjectList returns a single page and never shells wrangler", async () => {
+  const { fetchFn, calls } = recordingFetch({ ok: true, status: 200, body: objectPage(["a.jpg"]) });
+  const cf = makeCfExec(cred, throwingRun, fetchFn);
+  assert.deepEqual(await cf.r2ObjectList("acc-a-portal"), [
+    { key: "a.jpg", size: 10, etag: "e1", lastModified: "2026-01-01T00:00:00Z" },
+  ]);
+  assert.equal(calls.length, 1);
+  assert.equal(
+    calls[0].url,
+    "https://api.cloudflare.com/client/v4/accounts/acc-h/r2/buckets/acc-a-portal/objects",
+  );
+  assert.equal(calls[0].init.headers.Authorization, "Bearer cfat_x");
+});
+
+test("r2ObjectList never sends per_page", async () => {
+  const { fetchFn, calls } = recordingFetch({ ok: true, status: 200, body: objectPage([]) });
+  const cf = makeCfExec(cred, throwingRun, fetchFn);
+  await cf.r2ObjectList("b");
+  assert.equal(calls[0].url.includes("per_page"), false);
+});
+
+test("r2ObjectList passes prefix through, encoded", async () => {
+  const { fetchFn, calls } = recordingFetch({ ok: true, status: 200, body: objectPage([]) });
+  const cf = makeCfExec(cred, throwingRun, fetchFn);
+  await cf.r2ObjectList("b", "person a/");
+  assert.ok(calls[0].url.endsWith("/objects?prefix=person+a%2F"), calls[0].url);
+});
+
+test("r2ObjectList follows the cursor to exhaustion", async () => {
+  const { fetchFn, calls } = sequenceFetch([
+    { ok: true, status: 200, body: objectPage(["a.jpg"], { cursor: "c1", truncated: true }) },
+    { ok: true, status: 200, body: objectPage(["b.jpg"]) },
+  ]);
+  const cf = makeCfExec(cred, throwingRun, fetchFn);
+  assert.deepEqual((await cf.r2ObjectList("b")).map((o) => o.key), ["a.jpg", "b.jpg"]);
+  assert.equal(calls.length, 2);
+  assert.ok(calls[1].url.includes("cursor=c1"));
+});
+
+// is_truncated is the authoritative continuation signal, not the presence of a
+// cursor: a last page may still carry one.
+test("r2ObjectList stops when is_truncated is false even if a cursor is present", async () => {
+  const { fetchFn, calls } = sequenceFetch([
+    { ok: true, status: 200, body: objectPage(["a.jpg"], { cursor: "c1", truncated: false }) },
+  ]);
+  const cf = makeCfExec(cred, throwingRun, fetchFn);
+  await cf.r2ObjectList("b");
+  assert.equal(calls.length, 1);
+});
+
+// The response shape is doc-confirmed but never measured against a live account.
+// If it is not what we understand, that must be loud: a partial list is exactly
+// the bug this loop exists to prevent.
+test("r2ObjectList throws when truncated but no cursor is given, never a partial list", async () => {
+  const { fetchFn } = recordingFetch({
+    ok: true,
+    status: 200,
+    body: objectPage(["a.jpg"], { truncated: true }),
+  });
+  const cf = makeCfExec(cred, throwingRun, fetchFn);
+  await assert.rejects(() => cf.r2ObjectList("b"), /truncated but gave no pagination cursor/);
+});
+
+test("r2ObjectList throws on a repeated cursor", async () => {
+  const { fetchFn } = sequenceFetch([
+    { ok: true, status: 200, body: objectPage(["a"], { cursor: "c1", truncated: true }) },
+    { ok: true, status: 200, body: objectPage(["b"], { cursor: "c1", truncated: true }) },
+  ]);
+  const cf = makeCfExec(cred, throwingRun, fetchFn);
+  await assert.rejects(() => cf.r2ObjectList("b"), /repeated pagination cursor/);
+});
+
+test("r2ObjectList retains the body on a non-2xx", async () => {
+  const { fetchFn } = recordingFetch({ ok: false, status: 403, body: '{"errors":[{"code":10000}]}' });
+  const cf = makeCfExec(cred, throwingRun, fetchFn);
+  await assert.rejects(() => cf.r2ObjectList("b"), /10000/);
+});
+
+test("r2ObjectGet returns exact bytes and encodes the key segment-wise", async () => {
+  // Binary that is not valid UTF-8: proves the body never round-trips through
+  // text(), which would corrupt it.
+  const bytes = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x00, 0xff]);
+  const calls: string[] = [];
+  const fetchFn: FetchFn = async (url) => {
+    calls.push(url);
+    return {
+      ok: true,
+      status: 200,
+      text: async () => "unused",
+      arrayBuffer: async () => bytes.buffer.slice(0) as ArrayBuffer,
+    };
+  };
+  const cf = makeCfExec(cred, throwingRun, fetchFn);
+  const got = await cf.r2ObjectGet("b", "person a/photo 1.jpg");
+  assert.deepEqual(Array.from(got), Array.from(bytes));
+  // Separators stay separators; spaces are escaped.
+  assert.ok(calls[0].endsWith("/objects/person%20a/photo%201.jpg"), calls[0]);
+});
+
+test("r2ObjectGet retains the body on a non-2xx", async () => {
+  const { fetchFn } = recordingFetch({ ok: false, status: 404, body: "no such key" });
+  const cf = makeCfExec(cred, throwingRun, fetchFn);
+  await assert.rejects(() => cf.r2ObjectGet("b", "k"), /no such key/);
+});
+
+test("r2ObjectPut sends the bytes as the request body", async () => {
+  const { fetchFn, calls } = recordingFetch({
+    ok: true,
+    status: 200,
+    body: JSON.stringify({ success: true, errors: [], messages: [], result: {} }),
+  });
+  const cf = makeCfExec(cred, throwingRun, fetchFn);
+  const bytes = new Uint8Array([1, 2, 3]);
+  await cf.r2ObjectPut("b", "k.bin", bytes);
+  assert.equal(calls[0].init.method, "PUT");
+  assert.deepEqual(calls[0].init.body, bytes);
+  assert.equal(calls[0].init.headers.Authorization, "Bearer cfat_x");
+});
+
+test("r2ObjectPut retains the body on a non-success envelope", async () => {
+  const { fetchFn } = recordingFetch({
+    ok: true,
+    status: 200,
+    body: '{"success":false,"errors":[{"code":10001}]}',
+  });
+  const cf = makeCfExec(cred, throwingRun, fetchFn);
+  await assert.rejects(() => cf.r2ObjectPut("b", "k", new Uint8Array([1])), /10001/);
+});
+
+test("r2ObjectDelete issues a DELETE", async () => {
+  const { fetchFn, calls } = recordingFetch({
+    ok: true,
+    status: 200,
+    body: JSON.stringify({ success: true, errors: [], messages: [], result: {} }),
+  });
+  const cf = makeCfExec(cred, throwingRun, fetchFn);
+  await cf.r2ObjectDelete("b", "k");
+  assert.equal(calls[0].init.method, "DELETE");
+  assert.equal(calls[0].init.headers.Authorization, "Bearer cfat_x");
+});
+
+test("r2ObjectDelete retains the body on a non-2xx", async () => {
+  const { fetchFn } = recordingFetch({ ok: false, status: 500, body: "boom" });
+  const cf = makeCfExec(cred, throwingRun, fetchFn);
+  await assert.rejects(() => cf.r2ObjectDelete("b", "k"), /boom/);
+});
+
+// Code review — is_truncated is itself an unmeasured fact (no live credential
+// exists to confirm the envelope). Driving the loop solely on it means a
+// response that omits it while still paginating truncates SILENTLY, which is
+// the exact failure this loop exists to prevent, and it would also make
+// r2ObjectList disagree with r2List directly above it, which drives the same
+// envelope on cursor presence alone.
+test("r2ObjectList follows a cursor when is_truncated is absent, rather than truncating silently", async () => {
+  const pageWithoutTruncatedFlag = (keys: string[], cursor: string | null) =>
+    JSON.stringify({
+      success: true,
+      errors: [],
+      messages: [],
+      result: keys.map((key) => ({ key, size: 1, etag: "e", last_modified: "t" })),
+      result_info: cursor === null ? {} : { cursor },
+    });
+  const { fetchFn, calls } = sequenceFetch([
+    { ok: true, status: 200, body: pageWithoutTruncatedFlag(["a.jpg"], "c1") },
+    { ok: true, status: 200, body: pageWithoutTruncatedFlag(["b.jpg"], null) },
+  ]);
+  const cf = makeCfExec(cred, throwingRun, fetchFn);
+  assert.deepEqual((await cf.r2ObjectList("b")).map((o) => o.key), ["a.jpg", "b.jpg"]);
+  assert.equal(calls.length, 2);
+});

package/payload/platform/lib/storage-broker/src/__tests__/object-limits.test.ts

@@ -0,0 +1,76 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import {
+  R2_OBJECT_MAX_BYTES,
+  R2_OBJECT_PUT_MAX_BODY_BYTES,
+  base64Ceiling,
+  tooLargeMessage,
+} from "../object-limits.js";
+
+test("the cap is 100 MiB", () => {
+  assert.equal(R2_OBJECT_MAX_BYTES, 100 * 1024 * 1024);
+});
+
+// The cap is set independently of email's 25 MiB. This pins that they are not
+// the same number, so a future edit that "unifies" them fails here and has to
+// read the design note rather than silently coupling two unrelated limits.
+test("the cap is not email's attachment cap", () => {
+  assert.notEqual(R2_OBJECT_MAX_BYTES, 25 * 1024 * 1024);
+});
+
+test("base64Ceiling matches base64's 4-out-per-3-in expansion, rounded up", () => {
+  assert.equal(base64Ceiling(0), 0);
+  assert.equal(base64Ceiling(1), 4);
+  assert.equal(base64Ceiling(3), 4);
+  assert.equal(base64Ceiling(4), 8);
+  assert.equal(base64Ceiling(6), 8);
+});
+
+// The ceiling must never sit below what a legal at-cap object actually encodes
+// to, or a legitimate put would be rejected by its own encoding.
+test("base64Ceiling is never below Node's own base64 length", () => {
+  for (const n of [0, 1, 2, 3, 4, 5, 100, 1023, 4096]) {
+    const encoded = Buffer.alloc(n).toString("base64").length;
+    assert.ok(
+      base64Ceiling(n) >= encoded,
+      `base64Ceiling(${n}) = ${base64Ceiling(n)} < ${encoded}`,
+    );
+  }
+});
+
+test("the put body ceiling admits a cap-sized object plus an envelope allowance", () => {
+  assert.equal(
+    R2_OBJECT_PUT_MAX_BODY_BYTES,
+    base64Ceiling(R2_OBJECT_MAX_BYTES) + 64 * 1024,
+  );
+  assert.ok(R2_OBJECT_PUT_MAX_BODY_BYTES > base64Ceiling(R2_OBJECT_MAX_BYTES));
+});
+
+// The allowance is for a key and JSON punctuation, not for smuggling a bigger
+// object: it must stay far below the cap it guards.
+test("the envelope allowance is negligible against the cap", () => {
+  const allowance = R2_OBJECT_PUT_MAX_BODY_BYTES - base64Ceiling(R2_OBJECT_MAX_BYTES);
+  assert.ok(allowance < R2_OBJECT_MAX_BYTES / 1000);
+});
+
+test("the over-cap message names the object and the limit", () => {
+  const msg = tooLargeMessage("photo.jpg", 150 * 1024 * 1024);
+  assert.match(msg, /photo\.jpg/);
+  assert.match(msg, /150\.0 MiB/);
+  assert.match(msg, /100\.0 MiB/);
+});
+
+// Code review — MiB alone rounds, so an object one byte over the cap rendered as
+// "100.0 MiB, which exceeds the 100.0 MiB limit": a message that contradicts
+// itself and reads as a bug rather than a rejection. The exact bytes are what
+// disambiguate it, so they are pinned rather than left to formatting taste.
+test("the message stays legible for an object one byte over the cap", () => {
+  const msg = tooLargeMessage("photo.jpg", R2_OBJECT_MAX_BYTES + 1);
+  assert.match(msg, /104857601 bytes/);
+  assert.match(msg, /104857600 bytes/);
+  assert.notEqual(
+    msg.match(/100\.0 MiB \(104857601 bytes\)/),
+    null,
+    "the actual size must carry its exact byte count",
+  );
+});

package/payload/platform/lib/storage-broker/src/cf-exec.ts

@@ -14,14 +14,32 @@ export type RunFn = (
   env: Record<string, string>,
 ) => Promise<{ stdout: string }>;
 
-// The HTTP seam for the Cloudflare API. Injectable so r2List and d1Create are
+// The HTTP seam for the Cloudflare API. Injectable so the API-backed methods are
 // unit-testable without a network. Minimal subset of the global fetch: callers
 // read the body once via text() and branch on ok/status. `body` is set for the
-// POST paths (d1Create); GET paths (r2List) omit it.
+// POST/PUT paths (d1Create, r2ObjectPut); GET/DELETE paths omit it.
+//
+// Task 1691 widened both halves: `body` carries Uint8Array for the object-put
+// path, and `arrayBuffer` reads the raw object body for r2ObjectGet, which is
+// the one method whose response is not a JSON envelope. arrayBuffer is required
+// rather than optional: an optional member would force a fake-only fallback
+// branch in r2ObjectGet that never runs against a real fetch.
 export type FetchFn = (
   url: string,
-  init: { method: string; headers: Record<string, string>; body?: string },
-) => Promise<{ ok: boolean; status: number; text(): Promise<string> }>;
+  init: { method: string; headers: Record<string, string>; body?: string | Uint8Array },
+) => Promise<{
+  ok: boolean;
+  status: number;
+  text(): Promise<string>;
+  arrayBuffer(): Promise<ArrayBuffer>;
+}>;
+
+export interface R2Object {
+  key: string;
+  size: number;
+  etag: string;
+  lastModified: string;
+}
 
 export interface CfExec {
   d1List(): Promise<{ name: string; uuid: string }[]>;
@@ -29,9 +47,33 @@ export interface CfExec {
   d1Query(name: string, sql: string): Promise<unknown>;
   r2List(): Promise<{ name: string }[]>;
   r2Create(name: string): Promise<void>;
+  r2ObjectList(bucket: string, prefix?: string): Promise<R2Object[]>;
+  r2ObjectGet(bucket: string, key: string): Promise<Uint8Array>;
+  r2ObjectPut(bucket: string, key: string, body: Uint8Array): Promise<void>;
+  r2ObjectDelete(bucket: string, key: string): Promise<void>;
+}
+
+// An object key carries `/` as a real path separator (the data portal's
+// per-person prefixes), so it is encoded segment-wise rather than whole:
+// separators stay separators, and spaces and specials are escaped. This
+// encoding is not doc-confirmed; it is chosen so that a wrong guess surfaces as
+// a 404 carrying its body, never as a silently misfiled object.
+function encodeObjectKey(key: string): string {
+  return key.split("/").map(encodeURIComponent).join("/");
+}
+
+// The single-object endpoint, shared by get/put/delete so the three cannot drift
+// apart on encoding.
+function objectUrl(accountId: string, bucket: string, key: string): string {
+  return `https://api.cloudflare.com/client/v4/accounts/${accountId}/r2/buckets/${encodeURIComponent(bucket)}/objects/${encodeObjectKey(key)}`;
 }
 
-const defaultFetch: FetchFn = (url, init) => fetch(url, init);
+// The cast is confined to this adapter. A Uint8Array is a valid fetch body at
+// runtime, but the DOM lib's BodyInit does not admit TypeScript's generic
+// Uint8Array<ArrayBufferLike>, so consumers compiled against DOM typings (the
+// ui server) reject the call the Node typings accept. Casting here keeps the
+// seam's own type honest for every caller and test.
+const defaultFetch: FetchFn = (url, init) => fetch(url, init as RequestInit);
 
 const defaultRun: RunFn = (cmd, args, env) =>
   new Promise((resolve, reject) => {
@@ -62,7 +104,7 @@ function parseJson(raw: string, context: string): unknown {
 async function cfApiJson(
   fetchFn: FetchFn,
   url: string,
-  init: { method: string; headers: Record<string, string>; body?: string },
+  init: { method: string; headers: Record<string, string>; body?: string | Uint8Array },
   context: string,
 ): Promise<{ parsed: unknown; body: string }> {
   const res = await fetchFn(url, init);
@@ -182,6 +224,106 @@ export function makeCfExec(
     async r2Create(name) {
       await run("npx", ["wrangler", "r2", "bucket", "create", name], env);
     },
+
+    // --- R2 objects (Task 1691) -------------------------------------------
+    //
+    // The v4 REST API exposes the object surface under
+    // /accounts/{id}/r2/buckets/{bucket}/objects and accepts the same Bearer
+    // token as the bucket endpoints (account-level Workers R2 Storage Write).
+    // The r2/api/tokens/ note that "Object Read & Write" is S3-only constrains
+    // the bucket-item-scoped *permission types*, not these endpoints.
+    //
+    // Doc-confirmed, never measured: no house Cloudflare credential exists on
+    // the dev machine. The design keeps the unmeasured facts unable to affect
+    // correctness — per_page is never sent, and nothing fails silently.
+    async r2ObjectList(bucket, prefix) {
+      // Mirrors r2List: follow the cursor to exhaustion, never send per_page.
+      // A truncated object listing reads as "those objects are absent" to the
+      // data portal's standing audit, producing false phantom rows and hiding
+      // real orphans — the same bug r2List had, one endpoint over.
+      const base = `https://api.cloudflare.com/client/v4/accounts/${cred.accountId}/r2/buckets/${encodeURIComponent(bucket)}/objects`;
+      const objects: R2Object[] = [];
+      const seen = new Set<string>();
+      let cursor: string | undefined;
+      for (;;) {
+        const params = new URLSearchParams();
+        if (prefix !== undefined) params.set("prefix", prefix);
+        if (cursor !== undefined) params.set("cursor", cursor);
+        const qs = params.toString();
+        const { parsed, body } = await cfApiJson(
+          fetchFn,
+          qs ? `${base}?${qs}` : base,
+          { method: "GET", headers: { Authorization: `Bearer ${cred.apiToken}` } },
+          "r2 object list",
+        );
+        const page = parsed as {
+          result?: Array<{ key: string; size: number; etag: string; last_modified: string }>;
+          result_info?: { cursor?: string | null; is_truncated?: boolean };
+        };
+        for (const o of page.result ?? []) {
+          objects.push({ key: o.key, size: o.size, etag: o.etag, lastModified: o.last_modified });
+        }
+        const truncated = page.result_info?.is_truncated;
+        const next = page.result_info?.cursor;
+        // is_truncated is authoritative *when present*: a last page may still
+        // carry a cursor, and following it would issue a pointless request or
+        // trip the cycle guard below on a healthy response.
+        if (truncated === false) return objects;
+        // The API says there is more but names no cursor: the response is not
+        // the shape we understand. Surface it rather than return a partial
+        // list, which is the failure this loop exists to prevent.
+        if (truncated === true && !next) {
+          throw new Error(
+            `storage-broker: r2 object list reported truncated but gave no pagination cursor: ${body}`,
+          );
+        }
+        // is_truncated absent: it is itself an unmeasured fact, so it must not
+        // be what decides correctness. Fall back to cursor presence — the rule
+        // r2List uses on the same envelope — so an envelope without the flag
+        // paginates rather than truncating silently.
+        if (!next) return objects;
+        // A cursor seen before means the API is cycling rather than advancing:
+        // it would loop forever, re-appending the same objects each pass.
+        if (seen.has(next)) {
+          throw new Error(
+            `storage-broker: r2 object list returned a repeated pagination cursor: ${next}`,
+          );
+        }
+        seen.add(next);
+        cursor = next;
+      }
+    },
+    async r2ObjectGet(bucket, key) {
+      // The one method cfApiJson cannot wrap: get returns the raw object body,
+      // not a success envelope, so there is nothing to parse or assert
+      // success:true on. The error body is still retained on a non-2xx.
+      const res = await fetchFn(objectUrl(cred.accountId, bucket, key), {
+        method: "GET",
+        headers: { Authorization: `Bearer ${cred.apiToken}` },
+      });
+      if (!res.ok) {
+        throw new Error(
+          `storage-broker: r2 object get failed: ${res.status}\n${await res.text()}`,
+        );
+      }
+      return new Uint8Array(await res.arrayBuffer());
+    },
+    async r2ObjectPut(bucket, key, body) {
+      await cfApiJson(
+        fetchFn,
+        objectUrl(cred.accountId, bucket, key),
+        { method: "PUT", headers: { Authorization: `Bearer ${cred.apiToken}` }, body },
+        "r2 object put",
+      );
+    },
+    async r2ObjectDelete(bucket, key) {
+      await cfApiJson(
+        fetchFn,
+        objectUrl(cred.accountId, bucket, key),
+        { method: "DELETE", headers: { Authorization: `Bearer ${cred.apiToken}` } },
+        "r2 object delete",
+      );
+    },
   };
 }