review round 1: apply council (4 Claude + 4 Codex personas) + CodeRabbit findings

Security/correctness:
- sdk: proxy mode (baseUrl) never sends Authorization, even when apiKey
  is also passed — the documented contract now holds (cross-engine High)
- sdk: presigned-URL query strings (bearer-like signatures) redacted
  from rawFetch error messages; non-https upload_url refused
- proxy: reject empty path segments so matching always equals forwarding

API semantics (the one breaking-ish change, pre-publish):
- proxy: allowedPaths now REPLACES the defaults, exactly like
  allowedModels — spread DEFAULT_ALLOWED_PATHS to extend, [] to disable
  the asset routes (consensus P1: two opposite override semantics on one
  config object; forks could never turn the default uploads off)
- proxy: defaults gain GET /v1/assets/:id for rf.assets.get

Resilience (perf P1):
- sdk: rf.assets.upload retries transient failures (network/timeout/5xx,
  250/750ms) on all three legs — parity with the studio path it replaces
- sdk: PUT timeout scales with file size (2 Mbit/s floor, min 120s)

DX:
- sdk: rf.assets.get(id) re-mints expired signed urls; "store the id"
  documented; RunflowErrorCode union for autocompletable catch blocks
- proxy: 403/415 bodies carry actionable messages + machine codes
  (path_not_allowed, model_not_allowed, origin_not_allowed,
  json_content_type_required)
- studio: uploadFile defaults to the SDK presigned flow through
  runflowProxy (zero-config); hosts with an explicit urls.upload keep
  the legacy multipart path — ends the two-contradictory-upload-stories
  problem; READMEs aligned

Maintainability:
- studio: useShellConfig fallback warns once instead of silently serving
  built-ins; = WORKFLOWS default params removed; StudioShellProps
  documents mount-only source + stable-reference expectations
- studio: config memo keys on fields, not object identity — inline
  copy={{...}}/sentinel={{...}} no longer re-mint the context value
- studio: mask controller clamps brush size, warns once on
  unattached/unsynced use, willReadFrequently on CPU-read canvases;
  shell lazily inits the controller ref
- ci: biome warning-count ratchet (budget 45)

CodeRabbit CLI (3 of 8 taken; rest skipped with reasons in the PR):
- pin.ts boundary doc corrected (0.66 falls lower/right)
- unmount(): theme CSS variables cleared
- blob preview URLs revoked on unmount (GeneratePanel + StudioShell) via
  ref mirror — unmount-only, never revokes live previews

Tests: 72 → 84 (auth-mode pair; retry/4xx/https/redaction/assets.get;
replacement/spread/opt-out/empty-segment/coded-403 proxy coverage).

Author: miguelrisero

.changeset/proxy-allowed-paths.md

@@ -2,4 +2,4 @@
 "@runflow-io/proxy": minor
 ---
 
-Add `allowedPaths` — an extensible, strictly-matched route allow-list on top of the built-ins (dispatch, run polling, health). Defaults now include the asset-upload pair `rf.assets.upload` needs (`POST /v1/asset-uploads`, `POST /v1/asset-uploads/:id/confirmations`); customer rules are additive, support method arrays and `:param` segments, and reject traversal. Org-data reads (run listing, billing) remain strictly opt-in. The handler now also exposes `PUT`/`PATCH`/`DELETE` for framework route exports. `RateLimitResult`'s `void` member is now `undefined` (type-level only).
+Add `allowedPaths` — an extensible, strictly-matched route allow-list on top of the built-ins (dispatch, run polling, health). Defaults cover what `rf.assets.upload`/`rf.assets.get` need (`POST /v1/asset-uploads`, `POST /v1/asset-uploads/:id/confirmations`, `GET /v1/assets/:id`). Like `allowedModels`, a custom list **replaces** the defaults — spread the exported `DEFAULT_ALLOWED_PATHS` to extend, or pass `[]` to disable the asset routes. Rules support method arrays and `:param` segments, reject traversal (including percent-encoded) and empty segments. 403/415 bodies now carry actionable messages plus machine-readable `code`s (`path_not_allowed`, `model_not_allowed`, `origin_not_allowed`, `json_content_type_required`). The handler also exposes `PUT`/`PATCH`/`DELETE` for framework route exports. `RateLimitResult`'s `void` member is now `undefined` (type-level only).

.changeset/sdk-assets-pin.md

@@ -2,6 +2,8 @@
 "@runflow-io/sdk": minor
 ---
 
-Add `rf.assets.upload(file)` — the browser-safe presigned upload flow (create session → PUT to storage → confirm), returning a model-ready signed HTTPS `url` plus the stable `runflow://assets/{id}` `ref`. Fixes the most common external-fork failure: browser file uploads ending up as `data:` URIs that models reject with a 422.
+Add `rf.assets.upload(file)` — the browser-safe presigned upload flow (create session → PUT to storage → confirm) with transient-failure retry and a size-scaled PUT timeout, returning a model-ready signed HTTPS `url` plus the stable `runflow://assets/{id}` `ref`. Fixes the most common external-fork failure: browser file uploads ending up as `data:` URIs that models reject with a 422. Add `rf.assets.get(id)` to re-mint an expired signed url (store the `id`, not the `url`).
 
 Export `composePinPrompt`, `composeRegionPrompt`, `pinRegion`, and `PinPoint` — the pin→region prompt convention (3×3 grid baked into the edit prompt) that previously existed only as private copies inside the studio bundle.
+
+Hardening: proxy mode (`baseUrl`) now never sends `Authorization`, even when `apiKey` is also passed (the documented contract); presigned-URL query strings are redacted from error messages; non-https `upload_url`s are refused. New `RunflowErrorCode` union for autocompletable `catch` handling.

.changeset/studio-props-mask.md

@@ -2,6 +2,8 @@
 "@runflow-io/studio": minor
 ---
 
-`<StudioShell>` accepts four optional customization props — `tools` (workflow catalogue), `source` (initial asset URL or sample list), `sentinel` (`{ enabled, taskDescription }`), and `copy` (brand/labels) — making vertical forks possible without rebuilding on `./headless`. Zero props renders exactly as before. `mount()` forwards them via the new `props` option.
+`<StudioShell>` accepts four optional customization props — `tools` (workflow catalogue), `source` (initial asset URL or sample list, read at mount), `sentinel` (`{ enabled, taskDescription }`), and `copy` (brand/labels) — making vertical forks possible without rebuilding on `./headless`. Zero props renders exactly as before. `mount()` forwards them via the new `props` option.
 
-`./headless` now exports `createMaskController` — the framework-free dual-canvas brush engine (stroke interpolation, coverage, full-resolution thresholded mask blob) the shell itself uses, so headless consumers get working mask creation for inpaint workflows without rebuilding it.
+`./headless` now exports `createMaskController` — the framework-free dual-canvas brush engine (stroke interpolation, coverage, full-resolution thresholded mask blob, guarded against unattached use and bad brush sizes) the shell itself uses, so headless consumers get working mask creation for inpaint workflows without rebuilding it.
+
+The shell's file uploads now default to the SDK's presigned flow through `runflowProxy` (zero-config — no separate `upload` endpoint needed); hosts that explicitly set `urls.upload` keep the legacy multipart path. `unmount()` now also clears theme CSS variables, and blob preview URLs are revoked on unmount.

.github/workflows/ci.yml

@@ -36,6 +36,21 @@ jobs:
       - name: Lint
         run: bun run lint
 
+      # Warning ratchet: biome warnings (mostly the studio components'
+      # downgraded a11y/hooks rules) must not grow past the checked-in
+      # budget. Lower the budget as warnings get fixed; raising it is a
+      # conscious review decision.
+      - name: Lint warning ratchet
+        run: |
+          BUDGET=45
+          count=$(bunx biome check . 2>&1 | grep -oE 'Found [0-9]+ warnings' | grep -oE '[0-9]+' | head -1)
+          count=${count:-0}
+          echo "biome warnings: $count (budget: $BUDGET)"
+          if [ "$count" -gt "$BUDGET" ]; then
+            echo "::error::Warning count $count exceeds the budget of $BUDGET — fix the new warnings or consciously raise the budget in ci.yml."
+            exit 1
+          fi
+
       # The live e2e proof (examples/e2e-proof) needs RUNFLOW_API_KEY and
       # spends real credits, so it stays a local/manual gate — see
       # `bun run proof`.

examples/e2e-proof/run.ts

@@ -24,7 +24,7 @@ import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { runflowProxy } from "@runflow-io/proxy";
+import { DEFAULT_ALLOWED_PATHS, runflowProxy } from "@runflow-io/proxy";
 import { RunFailedError, Runflow, composePinPrompt } from "@runflow-io/sdk";
 import { buildSampleMask, fetchBytes } from "./fixtures.js";
 
@@ -165,8 +165,6 @@ async function main() {
     const start = Date.now();
     try {
       const dispatched = await rf.models.run(mod.model, mod.body);
-      const enrichedBody = { ...mod.body, client_ref: `e2e-${mod.modality}-${start}` };
-      void enrichedBody;
       const final = await rf.runs.wait(dispatched.id, {
         pollIntervalMs: 2_000,
         timeoutMs: mod.timeoutMs ?? 3 * 60_000,
@@ -310,7 +308,9 @@ async function main() {
     const mockProxy = runflowProxy({
       apiKey,
       basePath: "/api/runflow",
-      allowedPaths: [{ method: "GET", path: "/v1/runs" }],
+      // Replacement semantics (same as allowedModels): spread the
+      // defaults to extend them with a run-listing read.
+      allowedPaths: [...DEFAULT_ALLOWED_PATHS, { method: "GET", path: "/v1/runs" }],
       fetch: (async (input: RequestInfo | URL, init?: RequestInit) => {
         seen.push(new Request(input as RequestInfo, init).url);
         return new Response(JSON.stringify({ ok: true }), {
@@ -334,10 +334,32 @@ async function main() {
     if (refused.status !== 403) throw new Error(`expected 403 for billing, got ${refused.status}`);
     if (seen.length !== 2) throw new Error(`expected exactly 2 upstream calls, saw ${seen.length}`);
 
+    // A bare custom list REPLACES the defaults — forks can switch the
+    // asset routes off.
+    const optOutProxy = runflowProxy({
+      apiKey,
+      basePath: "/api/runflow",
+      allowedPaths: [],
+      fetch: (async () =>
+        new Response(JSON.stringify({ ok: true }), {
+          headers: { "Content-Type": "application/json" },
+        })) as typeof fetch,
+    });
+    const optedOut = await optOutProxy(
+      new Request("http://proof.local/api/runflow/v1/asset-uploads", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: "{}",
+      }),
+    );
+    if (optedOut.status !== 403) {
+      throw new Error(`allowedPaths: [] should disable uploads, got ${optedOut.status}`);
+    }
+
     const liveListProxy = runflowProxy({
       apiKey,
       basePath: "/api/runflow",
-      allowedPaths: [{ method: "GET", path: "/v1/runs" }],
+      allowedPaths: [...DEFAULT_ALLOWED_PATHS, { method: "GET", path: "/v1/runs" }],
     });
     const live = await liveListProxy(new Request("http://proof.local/api/runflow/v1/runs?limit=3"));
     if (live.status !== 200) {
@@ -427,9 +449,9 @@ async function main() {
   await log("");
 
   // ── Mask + reference (runflow/reference-inpaint) ────────────────────
-  // Mirrors the prototype's mask-ref flow: upload source + mask + ref to
-  // R2 (using the same Sig V4 path /demos/api/upload uses), then dispatch
-  // reference-inpaint with three URLs in the body.
+  // Uploads source + mask + reference as Runflow assets via
+  // rf.assets.upload (through the proxy's default allow-list), then
+  // dispatches reference-inpaint with the three signed URLs.
   await log("▶ mask + reference — reference-inpaint");
   const maskStart = Date.now();
   try {

packages/proxy/README.md

@@ -104,6 +104,7 @@ The proxy accepts these paths out of the box:
 | GET    | `/v1/health`                            | Public health.                   |
 | POST   | `/v1/asset-uploads`                     | Create a presigned upload.       |
 | POST   | `/v1/asset-uploads/{id}/confirmations`  | Confirm it (`rf.assets.upload`). |
+| GET    | `/v1/assets/{id}`                       | Re-sign an asset URL (`rf.assets.get`). |
 
 Everything else returns `403 Not allowed`. Run IDs are validated as
 UUIDv4-shape to block path traversal. Dispatch is additionally gated by
@@ -112,21 +113,29 @@ UUIDv4-shape to block path traversal. Dispatch is additionally gated by
 ### Extending the allow-list: `allowedPaths`
 
 ```ts
+import { DEFAULT_ALLOWED_PATHS, runflowProxy } from "@runflow-io/proxy";
+
 runflowProxy({
   apiKey: process.env.RUNFLOW_API_KEY!,
   allowedPaths: [
+    ...DEFAULT_ALLOWED_PATHS, // keep the rf.assets.upload/get routes
     { method: "GET", path: "/v1/runs" }, // run listing
     { method: "GET", path: "/v1/billing/balance" }, // billing read
   ],
 });
 ```
 
-Rules are additive over the defaults and matched strictly — full path,
-segment by segment, no prefixes or wildcards. A `:param` segment matches
-exactly one non-empty segment and rejects traversal (`.`, `..`,
+Like `allowedModels`, a custom list **replaces** the defaults — spread
+`DEFAULT_ALLOWED_PATHS` (exported) to extend them, as above, or pass
+`[]` to turn the asset routes off entirely. Matching is strict — full
+path, segment by segment, no prefixes or wildcards. A `:param` segment
+matches exactly one non-empty segment and rejects traversal (`.`, `..`,
 percent-encoded forms). `method` takes a string or an array
 (`["GET", "DELETE"]`); the handler also exports `PUT`/`PATCH`/`DELETE`
-for framework route files.
+for framework route files. Non-GET requests must send
+`Content-Type: application/json` (CSRF gate) even when bodyless, and
+upstream responses are fully buffered — avoid allowing large or binary
+endpoints.
 
 > **Security:** every matched request is forwarded with **your** API
 > key, so an allowed `GET /v1/runs` exposes org-wide run data to any

packages/proxy/src/defaults.ts

@@ -26,9 +26,12 @@ export const DEFAULT_ALLOWED_MODELS: ReadonlyArray<string> = [
 import type { AllowedPath } from "./types.js";
 
 /**
- * Extra upstream routes the proxy forwards out of the box — the
- * presigned-upload pair `rf.assets.upload(file)` calls. Customer
- * `allowedPaths` entries are additive over these.
+ * Extra upstream routes the proxy forwards out of the box: the
+ * presigned-upload pair `rf.assets.upload(file)` calls, plus the
+ * single-asset read `rf.assets.get(id)` uses to re-sign an expired
+ * asset URL. Like `allowedModels`, a customer-supplied `allowedPaths`
+ * REPLACES this list — spread `DEFAULT_ALLOWED_PATHS` to extend it, or
+ * pass `[]` to turn these routes off entirely.
  *
  * Deliberately NOT here: `GET /v1/runs` (org-wide run listing),
  * billing reads, account info. Those expose org data through the
@@ -37,6 +40,7 @@ import type { AllowedPath } from "./types.js";
 export const DEFAULT_ALLOWED_PATHS: ReadonlyArray<AllowedPath> = [
   { method: "POST", path: "/v1/asset-uploads" },
   { method: "POST", path: "/v1/asset-uploads/:id/confirmations" },
+  { method: "GET", path: "/v1/assets/:id" },
 ];
 
 export const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;

packages/proxy/src/handler.ts

@@ -51,7 +51,7 @@ function normalize(cfg: ProxyConfig): NormalizedConfig {
     upstreamTimeoutMs: cfg.upstreamTimeoutMs ?? DEFAULT_UPSTREAM_TIMEOUT_MS,
     fetcher: cfg.fetch ?? globalThis.fetch,
     allowedModelsFor,
-    allowedPaths: [...DEFAULT_ALLOWED_PATHS, ...(cfg.allowedPaths ?? [])],
+    allowedPaths: cfg.allowedPaths ?? DEFAULT_ALLOWED_PATHS,
     allowedOrigins: cfg.allowedOrigins ?? "same-origin",
     requireJsonContentType: cfg.requireJsonContentType ?? true,
     authenticate: cfg.authenticate,
@@ -150,21 +150,41 @@ async function handle(c: NormalizedConfig, req: Request): Promise<Response> {
     segments[0] === "v1" &&
     segments[1] === "health";
 
+  // Empty segments (`//`) would make the matched path differ from the
+  // forwarded one — refuse to match them at all.
+  const hasEmptySegments = /\/\//.test(upstreamPath);
   const isAllowedPath =
-    !isDispatch && !runId && !isHealth && matchAllowedPath(req.method, segments, c.allowedPaths);
+    !isDispatch &&
+    !runId &&
+    !isHealth &&
+    !hasEmptySegments &&
+    matchAllowedPath(req.method, segments, c.allowedPaths);
 
   if (!isDispatch && !runId && !isHealth && !isAllowedPath) {
-    return json({ error: "Not allowed" }, 403);
+    return json(
+      {
+        error: `Path not allowed: ${req.method} /${upstreamPath.slice(0, 120)}. The proxy forwards model dispatch, run polling, health, and the asset upload/read routes by default; add other upstream routes via the allowedPaths option.`,
+        code: "path_not_allowed",
+      },
+      403,
+    );
   }
 
   // CSRF gate — must run before any authenticate hook so a malicious
   // page can't drain cookie credentials into the customer's API key.
   if (req.method !== "GET" && req.method !== "HEAD") {
     if (!originAllowed(req, c.allowedOrigins)) {
-      return json({ error: "Origin not allowed" }, 403);
+      return json({ error: "Origin not allowed", code: "origin_not_allowed" }, 403);
     }
     if (c.requireJsonContentType && !jsonContentTypeOK(req)) {
-      return json({ error: "Content-Type must be application/json" }, 415);
+      return json(
+        {
+          error:
+            "Content-Type must be application/json (CSRF defense — required on every non-GET request through the proxy, including bodyless DELETEs)",
+          code: "json_content_type_required",
+        },
+        415,
+      );
     }
   }
 
@@ -184,7 +204,10 @@ async function handle(c: NormalizedConfig, req: Request): Promise<Response> {
   if (isDispatch && model) {
     const allowed = c.allowedModelsFor(auth);
     if (!allowed.includes(model)) {
-      return json({ error: "Model not allowed" }, 403);
+      return json(
+        { error: `Model not allowed: ${model.slice(0, 120)}`, code: "model_not_allowed" },
+        403,
+      );
     }
   }
 

packages/proxy/src/types.ts

@@ -83,15 +83,28 @@ export interface ProxyConfig {
   allowedModels?: ReadonlyArray<string> | ((auth: AuthResult | null) => ReadonlyArray<string>);
 
   /**
-   * Extra upstream routes to forward, additive over the defaults
-   * (`POST /v1/asset-uploads`, `POST /v1/asset-uploads/:id/confirmations`
-   * — what `rf.assets.upload` needs) and the always-on built-ins.
+   * Extra upstream routes to forward beyond the always-on built-ins
+   * (dispatch, run polling, health). Like `allowedModels`, passing a
+   * list REPLACES the defaults (`DEFAULT_ALLOWED_PATHS`: the asset
+   * upload pair + `GET /v1/assets/:id`, what `rf.assets.upload`/`get`
+   * need). Spread the exported defaults to extend them:
+   *
+   * ```ts
+   * allowedPaths: [...DEFAULT_ALLOWED_PATHS, { method: "GET", path: "/v1/runs" }]
+   * ```
+   *
+   * Pass `[]` to disable the asset routes entirely.
    *
    * SECURITY: every request that matches is forwarded with YOUR API key,
-   * so an allowed GET exposes that data to any logged-in (or, without an
-   * `authenticate` hook, any same-origin) browser session. Only allow
-   * reads like `GET /v1/runs` or `GET /v1/billing/balance` deliberately,
-   * and pair them with `authenticate` + `rateLimit` in production.
+   * so an allowed GET exposes that data to any same-origin browser
+   * session (the default upload routes included — pair the proxy with
+   * `authenticate` + `rateLimit` in production). Only allow reads like
+   * `GET /v1/runs` or `GET /v1/billing/balance` deliberately.
+   *
+   * Notes: upstream responses are fully buffered (no streaming) — avoid
+   * allowing large/binary endpoints; non-GET requests must send
+   * `Content-Type: application/json` (CSRF gate), including bodyless
+   * DELETE/PATCH/PUT.
    */
   allowedPaths?: ReadonlyArray<AllowedPath>;