@foldrun/core 8.0.1 → 9.0.0

package/src/notify.ts

@@ -34,7 +34,8 @@
 import crypto from "node:crypto";
 import { readAgentsMd } from "./runner.ts";
 import { accountDir, workspaceDir, runCost, readFlow, runVerdict, type RunRecord } from "./store.ts";
-import { getSecret } from "./secrets.ts";
+import { getSecret, secretSites } from "./secrets.ts";
+import { siteCovers } from "./network.ts";
 import { publicUrl } from "./webhook.ts";
 import { approveLinkPath, approveLinkTtlMs } from "./approvals.ts";
 import { noteSecretUse, healthKey } from "./secret-health.ts";
@@ -209,15 +210,80 @@ export function newDeliveryId(): string {
 }
 
 /** The URL with ${SECRET}s resolved, and how it may be shown: a Slack hook
- *  URL is itself a credential, so it is never echoed resolved. */
-export function webhookTarget(tenant: string, workspace: string, config: NotifyConfig | null = notifyConfig(tenant, workspace)): { url: string | null; shown: string } {
+ *  URL is itself a credential, so it is never echoed resolved.
+ *
+ *  A secret bound to sites (`foldrun secrets sites`) is filled only when the
+ *  resolved URL's host is one of them — the rule the egress proxy and the
+ *  tool tester keep (30 Oct 2026). Before, notify.url filled any secret into
+ *  any host, so an editor could write `https://their.server/?k=${STRIPE_KEY}`
+ *  and press Test. The host is read AFTER filling, because the usual shape is
+ *  the whole URL as one secret (`${SLACK_WEBHOOK_URL}`, bound to
+ *  hooks.slack.com). An unbound secret fills as it does for an agent's
+ *  `secrets:` and a tool test — workspace first, then the account — since
+ *  binding is how an account says where a value may go. `refused` says why
+ *  `url` is null when a binding stopped it; `filled` maps each value put
+ *  into the URL to its name, so an error that echoes the URL can be scrubbed. */
+export function webhookTarget(
+  tenant: string,
+  workspace: string,
+  config: NotifyConfig | null = notifyConfig(tenant, workspace),
+): { url: string | null; shown: string; refused?: string; filled: Record<string, string> } {
   const raw = config?.url ?? "";
+  const filled: Record<string, string> = {};
+  // Every name put in, kept apart from `filled` (value → name, for
+  // scrubbing): two secrets with the same value would otherwise leave only
+  // the last name there, and the first one's binding would go unchecked.
+  const used = new Set<string>();
   const url = raw.replace(/\$\{([A-Z][A-Z0-9_]*)\}/g, (whole, name) => {
     const hit = getSecret(tenant, name, workspace);
+    if (hit) {
+      filled[hit.value] = name;
+      used.add(name);
+    }
     return hit ? hit.value : whole;
   });
   const shown = raw.includes("${") ? raw : raw ? `${raw.slice(0, 40)}${raw.length > 40 ? "…" : ""}` : "none";
-  return { url: !url || url.includes("${") ? null : url, shown };
+  if (!url || url.includes("${")) return { url: null, shown, filled: {} };
+  const bound = secretSites(tenant, [...used], workspace);
+  if (Object.keys(bound).length) {
+    let host = "";
+    try {
+      host = new URL(url).hostname;
+    } catch {
+      // Not a URL: no host can be one of its sites.
+    }
+    const offSite = Object.entries(bound).filter(([, sites]) => !host || !sites.some((site) => siteCovers(site, host))).map(([n]) => n);
+    if (offSite.length) {
+      return {
+        url: null,
+        shown,
+        filled: {},
+        // The host is not echoed: it is read from the FILLED url, so
+        // `https://${KEY}.their.server/` would print the key back.
+        refused: `${offSite.join(", ")} ${offSite.length === 1 ? "is" : "are"} bound to other sites than notify.url's host — not sent`,
+      };
+    }
+  }
+  return { url, shown, filled };
+}
+
+/** An error about a request to a resolved notify.url, with every secret value
+ *  put back as its ${NAME} — a redirect refusal quotes the URL it was sent to,
+ *  and the delivery log that keeps it is read by every viewer. */
+function scrubTarget(text: string, filled: Record<string, string>): string {
+  let out = text;
+  // Longest first, so a value inside another is not half-replaced.
+  for (const value of Object.keys(filled).sort((a, b) => b.length - a.length)) {
+    if (!value) continue;
+    const variants = new Set([value]);
+    try {
+      variants.add(encodeURI(value)).add(encodeURIComponent(value));
+    } catch {
+      // A lone surrogate cannot be encoded, so it cannot appear encoded.
+    }
+    for (const v of variants) out = out.split(v).join(`\${${filled[value]}}`);
+  }
+  return out;
 }
 
 export interface WebhookAttempt {
@@ -252,10 +318,13 @@ export async function attemptWebhook(
   if (!config?.url) {
     return { ...base, ok: false, statusCode: null, durationMs: 0, response: null, error: "this workspace's notify: has no url any more" };
   }
-  const { url } = webhookTarget(tenant, workspace, config);
+  const { url, refused, filled } = webhookTarget(tenant, workspace, config);
   if (!url) {
-    return { ...base, ok: false, statusCode: null, durationMs: 0, response: null, error: "the secret named in notify.url is not in this account's vault" };
+    return { ...base, ok: false, statusCode: null, durationMs: 0, response: null, error: refused ?? "the secret named in notify.url is not in this account's vault" };
   }
+  // A URL that carries a secret is a credential: a redirect is followed only
+  // within the origin it was sent to, as the tool tester does.
+  const carriesSecret = Object.keys(filled).length > 0;
   try {
     const res = await fetchUntrusted(url, {
       method: "POST",
@@ -270,7 +339,7 @@ export async function attemptWebhook(
       },
       body: d.body,
       signal: AbortSignal.timeout(Number(process.env.FOLDRUN_WEBHOOK_TIMEOUT_MS) || 8000),
-    });
+    }, { sameOrigin: carriesSecret });
     const text = (await res.text().catch(() => "")).slice(0, 500);
     return {
       ...base,
@@ -282,7 +351,7 @@ export async function attemptWebhook(
     };
   } catch (err) {
     const why = err instanceof Error ? (err.name === "TimeoutError" ? "timed out" : err.message) : String(err);
-    return { ...base, ok: false, statusCode: null, durationMs: Date.now() - started, response: null, error: why.slice(0, 500) };
+    return { ...base, ok: false, statusCode: null, durationMs: Date.now() - started, response: null, error: scrubTarget(why, filled).slice(0, 500) };
   }
 }
 
@@ -486,9 +555,9 @@ export async function sendTestNotification(
   // The destination is echoed back with the secret still unresolved: a
   // Slack webhook URL is itself a credential, and a page that prints it is
   // a page that leaks it into a screenshot.
-  const { url, shown } = webhookTarget(tenant, workspace, config);
+  const { url, shown, refused } = webhookTarget(tenant, workspace, config);
   if (!url) {
-    return { ok: false, destination: shown, detail: `the secret named in notify.url is not in this account's vault` };
+    return { ok: false, destination: shown, detail: refused ?? `the secret named in notify.url is not in this account's vault` };
   }
   const payload = JSON.stringify({ text: `${headline} — ${detail}`, workspace, status: "test", summary: detail });
   // One attempt, recorded in the delivery log like any other — and the way
@@ -635,8 +704,9 @@ export async function sendRunNotification(
 
     // ${SECRET} so the Slack URL — itself a credential — can live in the
     // vault instead of in a file that gets committed.
-    if (!webhookTarget(tenant, workspace, config).url) {
-      console.error(`[foldrun] notify: secret in URL not set for ${tenant}/${workspace}`);
+    const target = webhookTarget(tenant, workspace, config);
+    if (!target.url) {
+      console.error(`[foldrun] notify: ${target.refused ?? "secret in URL not set"} for ${tenant}/${workspace}`);
       return false;
     }
     const event = blocked ? "blocked" : run.status;

package/src/runner.ts

@@ -90,6 +90,7 @@ import {
   STORAGE_DIR,
   adoptLegacyVersionKey,
   listAgents,
+  isOneSegment,
 } from "./store.ts";
 import { canReadBack } from "./tool-output.ts";
 import { PromptLayers, promptCacheKey } from "./prompt-layers.ts";
@@ -4926,8 +4927,12 @@ function driveRunInner(
           // finished steps to `failed`, destroying the history it was
           // resuming around.
           if (step.status !== "pending") continue;
-          const aDir = path.join(pDir, "agents", step.agent);
-          if (!fs.existsSync(path.join(aDir, "agent.md"))) {
+          // One folder under agents/, never a path (30 Oct 2026): an ad-hoc
+          // run's agent came from the URL, and `../../<tenant>/…` joined here
+          // ran another account's agent. Refused as not found, before the
+          // existence check could answer for a path outside.
+          const aDir = isOneSegment(step.agent) ? path.join(pDir, "agents", step.agent) : null;
+          if (!aDir || !fs.existsSync(path.join(aDir, "agent.md"))) {
             step.status = "failed";
             step.events.push({
               t: new Date().toISOString(),
@@ -5156,8 +5161,9 @@ function driveRunInner(
         // step of the flow (isSplicedRecord). It gets no delegateJob of its
         // own: depth one.
         const delegateFor = (parent: StepRecord) => async (agent: string, job: string, cancelled: () => boolean): Promise<DelegationResult> => {
-          const dir = path.join(pDir, "agents", agent);
-          if (!fs.existsSync(path.join(dir, "agent.md"))) return { status: "failed", result: `${agent} is not an agent in this workspace` };
+          // One folder under agents/, never a path — as the group check above.
+          const dir = isOneSegment(agent) ? path.join(pDir, "agents", agent) : null;
+          if (!dir || !fs.existsSync(path.join(dir, "agent.md"))) return { status: "failed", result: `${agent} is not an agent in this workspace` };
           // A stable id on both records: an index into run.steps moves when a
           // rescue or a fan-out is spliced in before the child.
           const id = `d_${crypto.randomBytes(5).toString("hex")}`;
@@ -5597,8 +5603,8 @@ function driveRunInner(
         };
         const rescueStep = async (step: StepRecord): Promise<void> => {
           if (!step.onFail) return;
-          const rescuerDir = path.join(pDir, "agents", step.onFail);
-          if (!fs.existsSync(path.join(rescuerDir, "agent.md"))) {
+          const rescuerDir = isOneSegment(step.onFail) ? path.join(pDir, "agents", step.onFail) : null;
+          if (!rescuerDir || !fs.existsSync(path.join(rescuerDir, "agent.md"))) {
             step.events.push({
               t: new Date().toISOString(),
               type: "error",

package/src/secrets.ts

@@ -291,7 +291,10 @@ export function setSecret(
   workspace?: string,
   kind?: SecretKind,
 ) {
-  if (!SECRET_NAME.test(name)) {
+  // A string, not anything that prints as one: RegExp.test and the vault's
+  // keys both coerce, so ["RESEND_API_KEY"] from a JSON body was stored as
+  // RESEND_API_KEY past a caller's check on the name (30 Oct 2026).
+  if (typeof name !== "string" || !SECRET_NAME.test(name)) {
     throw new Error(`secret name "${name}" must be UPPER_SNAKE_CASE`);
   }
   if (value.length > 8192) throw new Error("secret too long");
@@ -314,6 +317,8 @@ export function setSecret(
  * scheme, path or port. Returns the list as stored.
  */
 export function setSecretSites(tenant: string, name: string, sites: string[], workspace?: string): string[] {
+  // all[name] would find ["NAME"] as NAME: see setSecret.
+  if (typeof name !== "string") throw new Error("a secret's name is a string");
   const clean = [...new Set(sites.map((x) => x.trim().toLowerCase()).filter(Boolean))];
   for (const site of clean) {
     if (!SITE.test(site)) throw new Error(`"${site}" is not a site — a domain like api.example.com or *.example.com, no scheme, path or port`);
@@ -1157,7 +1162,7 @@ export function setClientCertSecret(tenant: string, name: string, config: Client
     ...(config.passphrase ? { passphrase: config.passphrase } : {}),
     ...(config.export ? { export: true } : {}),
   };
-  if (!SECRET_NAME.test(name)) throw new Error(`secret name "${name}" must be UPPER_SNAKE_CASE`);
+  if (typeof name !== "string" || !SECRET_NAME.test(name)) throw new Error(`secret name "${name}" must be UPPER_SNAKE_CASE`);
   const plainCert = CLIENT_CERT_PREFIX + JSON.stringify(stored);
   // Written under the vault's own lock, with the binding checked in the same
   // step: a value set over a secret keeps its site binding, and a wildcard

package/src/storage.ts

@@ -51,6 +51,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import crypto from "node:crypto";
+import { Readable } from "node:stream";
 import { dataRoot, singleWorkspace } from "./paths.ts";
 import { assertSafeName, workspaceDir, STORAGE_DIR, adoptLegacyFilesDir } from "./store.ts";
 
@@ -85,6 +86,30 @@ interface Index {
 const maxBytes = () => Number(process.env.FOLDRUN_STORAGE_MAX_MB ?? 512) * 1024 * 1024;
 const quotaBytes = () => Number(process.env.FOLDRUN_STORAGE_QUOTA_MB ?? 5120) * 1024 * 1024;
 
+/** The bytes a set of records occupies: distinct blobs, not records — two
+ *  names for identical bytes are one object. A size that is not a positive
+ *  number counts as nothing: indexes written before 30 Oct 2026 hold sizes a
+ *  browser claimed, and a negative one used to lower the total. */
+function bytesOf(files: Pick<FileRecord, "sha" | "size">[]): number {
+  const seen = new Map<string, number>();
+  for (const f of files) seen.set(f.sha, Number.isFinite(f.size) && f.size > 0 ? f.size : 0);
+  return [...seen.values()].reduce((a, b) => a + b, 0);
+}
+
+/**
+ * Refuse a workspace that is not there, as a 404 (30 Oct 2026).
+ *
+ * The store is keyed by workspace *name* and used to be created for any safe
+ * name on first write, so an editor got a fresh quota for every name they
+ * invented — stores no workspace list shows and no delete reaches. Every
+ * write here, and the routes that read, ask this first.
+ */
+export function requireWorkspace(tenant: string, workspace: string): void {
+  if (!fs.existsSync(workspaceDir(tenant, workspace))) {
+    throw Object.assign(new Error(`workspace ${workspace} not found`), { status: 404 });
+  }
+}
+
 // ---------- paths ----------
 
 /**
@@ -212,9 +237,7 @@ export function getFile(tenant: string, workspace: string, rel: string): FileRec
 export function usedBytes(tenant: string, workspace: string): number {
   // Distinct blobs, not records: two names for identical bytes occupy one
   // object, and billing the tenant twice for it would be a lie.
-  const seen = new Map<string, number>();
-  for (const f of readIndex(tenant, workspace).files) seen.set(f.sha, f.size);
-  return [...seen.values()].reduce((a, b) => a + b, 0);
+  return bytesOf(readIndex(tenant, workspace).files);
 }
 
 // ---------- the driver interface ----------
@@ -224,6 +247,15 @@ export interface Driver {
   put(key: string, body: Buffer, mime: string): Promise<void>;
   get(key: string): Promise<Buffer>;
   has(key: string): Promise<boolean>;
+  /** The object's real length, or null when there is none — what the store
+   *  holds, never what a browser said it sent (30 Oct 2026). */
+  size(key: string): Promise<number | null>;
+  /** The bytes as a stream, optionally one inclusive byte range — so a route
+   *  hands a file on without holding all of it in memory. */
+  open(key: string, range?: { start: number; end: number }): Promise<ReadableStream<Uint8Array>>;
+  /** Server-side copy to another key (s3 only — the fs driver's blobs move
+   *  with their directory). Used when a workspace is renamed. */
+  copy?(from: string, to: string): Promise<void>;
   remove(key: string): Promise<void>;
   /** A URL a browser can GET directly, or null when the driver has no such
    *  thing (fs) and the route must stream the bytes itself. */
@@ -232,7 +264,9 @@ export interface Driver {
   presignGet(key: string, filename: string, mime: string, ttlSec?: number, inlineType?: string): Promise<string | null>;
   /** A URL a browser can PUT directly to, so upload bytes never transit the
    *  dashboard process. Null on fs, where the route takes the body. */
-  presignPut(key: string, mime: string, ttlSec?: number): Promise<string | null>;
+  /** `size`: sign the length in, so the store refuses a PUT of any other
+   *  length (30 Oct 2026) — the per-file limit then holds at the bucket. */
+  presignPut(key: string, mime: string, ttlSec?: number, size?: number): Promise<string | null>;
 }
 
 // ---------- fs driver ----------
@@ -264,6 +298,18 @@ function fsDriver(tenant: string, workspace: string): Driver {
     async has(key) {
       return fs.existsSync(at(key));
     },
+    async size(key) {
+      try {
+        const st = fs.statSync(at(key));
+        return st.isFile() ? st.size : null;
+      } catch {
+        return null;
+      }
+    },
+    async open(key, range) {
+      const stream = fs.createReadStream(at(key), range ? { start: range.start, end: range.end } : {});
+      return Readable.toWeb(stream) as unknown as ReadableStream<Uint8Array>;
+    },
     async remove(key) {
       fs.rmSync(at(key), { force: true });
     },
@@ -435,10 +481,17 @@ function presign(
   ttlSec: number,
   extraQuery: Record<string, string> = {},
   now = new Date(),
+  extraHeaders: Record<string, string> = {},
 ): string {
   const { host, origin, canonicalUri } = target(cfg, key);
   const { amzDate, dateStamp } = stamps(now);
   const scope = `${dateStamp}/${cfg.region}/s3/aws4_request`;
+  // Headers the request must carry exactly as signed. `content-length` on an
+  // upload is the one that matters: the store then refuses a body of any
+  // other length, so a presigned PUT cannot be used to park 5 GB under a key
+  // that was asked for as 2 MB (30 Oct 2026).
+  const headers: Record<string, string> = { host, ...Object.fromEntries(Object.entries(extraHeaders).map(([k, v]) => [k.toLowerCase(), v])) };
+  const signed = Object.keys(headers).sort();
 
   const query: Record<string, string> = {
     ...extraQuery,
@@ -446,7 +499,7 @@ function presign(
     "X-Amz-Credential": `${creds.accessKeyId}/${scope}`,
     "X-Amz-Date": amzDate,
     "X-Amz-Expires": String(ttlSec),
-    "X-Amz-SignedHeaders": "host",
+    "X-Amz-SignedHeaders": signed.join(";"),
     // A role's credentials are only valid with their token, and the token
     // is part of what is signed.
     ...(creds.sessionToken ? { "X-Amz-Security-Token": creds.sessionToken } : {}),
@@ -460,8 +513,8 @@ function presign(
     method,
     canonicalUri,
     canonicalQuery,
-    `host:${host}\n`,
-    "host",
+    signed.map((h) => `${h}:${headers[h].trim()}\n`).join(""),
+    signed.join(";"),
     "UNSIGNED-PAYLOAD",
   ].join("\n");
 
@@ -483,6 +536,7 @@ async function s3Request(
   key: string,
   body?: Buffer,
   mime?: string,
+  extra: Record<string, string> = {},
 ): Promise<Response> {
   const creds = await credentials(cfg);
   const { host, origin, canonicalUri } = target(cfg, key);
@@ -496,6 +550,9 @@ async function s3Request(
     "x-amz-date": amzDate,
     ...(creds.sessionToken ? { "x-amz-security-token": creds.sessionToken } : {}),
     ...(mime ? { "content-type": mime } : {}),
+    // range on a streamed read, x-amz-copy-source on a copy. Lower-case,
+    // because the canonical form is.
+    ...Object.fromEntries(Object.entries(extra).map(([k, v]) => [k.toLowerCase(), v])),
   };
   const signed = Object.keys(headers).sort();
   const canonicalHeaders = signed.map((h) => `${h}:${headers[h].trim()}\n`).join("");
@@ -545,6 +602,27 @@ function s3Driver(cfg: S3Config): Driver {
       const res = await s3Request(cfg, "HEAD", key);
       return res.ok;
     },
+    async size(key) {
+      const res = await s3Request(cfg, "HEAD", key);
+      if (res.status === 404) return null;
+      if (!res.ok) await fail(res, "head");
+      const n = Number(res.headers.get("content-length"));
+      return Number.isSafeInteger(n) && n >= 0 ? n : null;
+    },
+    async open(key, range) {
+      const res = await s3Request(cfg, "GET", key, undefined, undefined, range ? { range: `bytes=${range.start}-${range.end}` } : {});
+      if (!res.ok || !res.body) await fail(res, "get");
+      return res.body as ReadableStream<Uint8Array>;
+    },
+    async copy(from, to) {
+      // CopyObject: the bytes move inside the store, never through here.
+      const res = await s3Request(cfg, "PUT", to, undefined, undefined, {
+        "x-amz-copy-source": `/${cfg.bucket}/${uriEncode(from, true)}`,
+      });
+      // S3 can answer 200 with an <Error> body when a copy fails part-way.
+      const text = res.ok ? await res.text() : "";
+      if (!res.ok || /<Error>/.test(text)) throw new Error(`s3 copy failed: ${res.status} ${text.slice(0, 300)}`);
+    },
     async remove(key) {
       const res = await s3Request(cfg, "DELETE", key);
       // 404 on delete is the desired end state, not an error.
@@ -560,8 +638,8 @@ function s3Driver(cfg: S3Config): Driver {
         "response-content-type": safe ?? mime,
       });
     },
-    async presignPut(key, _mime, ttlSec = 600) {
-      return presign(cfg, await credentials(cfg), "PUT", key, ttlSec);
+    async presignPut(key, _mime, ttlSec = 600, size) {
+      return presign(cfg, await credentials(cfg), "PUT", key, ttlSec, {}, new Date(), size === undefined ? {} : { "content-length": String(size) });
     },
   };
 }
@@ -619,6 +697,9 @@ export async function putFile(
   body: Buffer,
   by: string,
 ): Promise<FileRecord> {
+  // A person's upload. A run's harvest writes through putFileQuietly, into a
+  // workspace that was there when the run began.
+  requireWorkspace(tenant, workspace);
   const record = await putFileQuietly(tenant, workspace, rel, body, by);
   // A run's copy-back announces once, for all its files, from harvestFiles.
   if (!by.startsWith("run:")) await announceFiles(tenant, workspace, [record.path], by);
@@ -666,20 +747,29 @@ async function putFileQuietly(
 }
 
 /** Register bytes a browser PUT straight to the bucket. Same bookkeeping as
- *  putFile, minus the bytes — the platform never saw them. */
+ *  putFile, minus the bytes — the platform never saw them.
+ *
+ *  `_claimed` is the size the browser says it sent, kept for the callers that
+ *  pass it and never believed (30 Oct 2026): the record, the per-file limit
+ *  and the quota all use the length the store reports. It used to store the
+ *  claim, so an object registered as 0 bytes (or -1e12) sat outside every
+ *  limit and lowered the quota line for everything after it. */
 export async function registerUpload(
   tenant: string,
   workspace: string,
   rel: string,
   sha: string,
-  size: number,
+  _claimed: number,
   by: string,
 ): Promise<FileRecord> {
   const norm = assertFilePath(rel);
   if (!/^[0-9a-f]{64}$/.test(sha)) throw new Error("expected a sha256");
+  requireWorkspace(tenant, workspace);
   const driver = driverFor(tenant, workspace);
-  // Trust nothing the browser said about whether the PUT landed.
-  if (!(await driver.has(blobKey(tenant, workspace, sha)))) {
+  const key = blobKey(tenant, workspace, sha);
+  // Trust nothing the browser said: not that the PUT landed, not its size.
+  const size = await driver.size(key);
+  if (size === null) {
     throw new Error("no object at that key — the upload did not complete");
   }
   const index = readIndex(tenant, workspace);
@@ -692,10 +782,21 @@ export async function registerUpload(
     updatedAt: new Date().toISOString(),
     by,
   };
-  writeIndex(tenant, workspace, {
-    version: 1,
-    files: [...index.files.filter((f) => f.path !== norm), record],
-  });
+  const files = [...index.files.filter((f) => f.path !== norm), record];
+  // putFile's two limits, on the real length. A refused object is removed:
+  // nothing names it, so it would sit in the bucket unreachable and billed —
+  // unless a record already names these bytes, which are then not ours to drop.
+  const refuse = async (message: string): Promise<never> => {
+    if (!index.files.some((f) => f.sha === sha)) await driver.remove(key).catch(() => {});
+    throw new Error(message);
+  };
+  if (size > maxBytes()) {
+    await refuse(`${norm} is ${Math.round(size / 1e6)}MB — the limit is ${maxBytes() / 1e6}MB`);
+  }
+  if (bytesOf(files) > quotaBytes() && bytesOf(files) > bytesOf(index.files)) {
+    await refuse(`workspace file quota exceeded (${quotaBytes() / 1e6}MB)`);
+  }
+  writeIndex(tenant, workspace, { version: 1, files });
   if (previous && previous.sha !== sha) await collect(tenant, workspace, previous.sha);
   await announceFiles(tenant, workspace, [record.path], by);
   return record;
@@ -711,6 +812,36 @@ export async function readFileBytes(
   return driverFor(tenant, workspace).get(blobKey(tenant, workspace, record.sha));
 }
 
+/** A stored file's real length, from the store — a stat or a HEAD, never a
+ *  read. Null when there is no such record or no object behind it. */
+export async function storedSize(tenant: string, workspace: string, rel: string): Promise<number | null> {
+  const record = getFile(tenant, workspace, rel);
+  if (!record) return null;
+  return driverFor(tenant, workspace).size(blobKey(tenant, workspace, record.sha));
+}
+
+/**
+ * A stored file as a stream, with its real length — for a route that passes
+ * the bytes on (a download, a public link) rather than reading them whole
+ * into memory. Null when there is no such record or no object behind it.
+ * `range` is inclusive and must lie inside the file (storedSize first, then
+ * byteRange, when the caller honours a Range header).
+ */
+export async function openFile(
+  tenant: string,
+  workspace: string,
+  rel: string,
+  range?: { start: number; end: number } | null,
+): Promise<{ record: FileRecord; size: number; body: ReadableStream<Uint8Array> } | null> {
+  const record = getFile(tenant, workspace, rel);
+  if (!record) return null;
+  const driver = driverFor(tenant, workspace);
+  const key = blobKey(tenant, workspace, record.sha);
+  const size = await driver.size(key);
+  if (size === null) return null;
+  return { record, size, body: await driver.open(key, range ?? undefined) };
+}
+
 export async function deleteFile(tenant: string, workspace: string, rel: string): Promise<boolean> {
   const norm = assertFilePath(rel);
   const index = readIndex(tenant, workspace);
@@ -779,10 +910,83 @@ export async function uploadUrl(
   workspace: string,
   rel: string,
   sha: string,
+  size?: number,
 ): Promise<string | null> {
-  assertFilePath(rel);
+  const norm = assertFilePath(rel);
   if (!/^[0-9a-f]{64}$/.test(sha)) throw new Error("expected a sha256");
-  return driverFor(tenant, workspace).presignPut(blobKey(tenant, workspace, sha), mimeFor(rel));
+  requireWorkspace(tenant, workspace);
+  // The limits, before a byte moves, and the length signed into the URL so
+  // the bucket refuses any other (30 Oct 2026). registerUpload checks the
+  // real object again; this is what keeps an oversized one from ever landing
+  // — an object that is PUT and never registered was otherwise unbounded.
+  if (size !== undefined) {
+    if (!Number.isSafeInteger(size) || size <= 0) throw new Error("size must be the file's length in bytes, a whole number above 0");
+    if (size > maxBytes()) throw new Error(`${norm} is ${Math.round(size / 1e6)}MB — the limit is ${maxBytes() / 1e6}MB`);
+    const files = readIndex(tenant, workspace).files;
+    const next = [...files.filter((f) => f.path !== norm), { sha, size }];
+    if (bytesOf(next) > quotaBytes() && bytesOf(next) > bytesOf(files)) {
+      throw new Error(`workspace file quota exceeded (${quotaBytes() / 1e6}MB)`);
+    }
+  }
+  return driverFor(tenant, workspace).presignPut(blobKey(tenant, workspace, sha), mimeFor(norm), undefined, size);
+}
+
+// ---------- a workspace deleted or renamed ----------
+
+/** The store's directory for a name, without the workspace check —
+ *  for the two calls below, which run when the folder is gone or moving. */
+function storeDirOf(tenant: string, workspace: string): string | null {
+  if (!fileStoreEnabled()) return null;
+  return storeDir(tenant, workspace);
+}
+
+/**
+ * Drop everything a workspace stored: every object its index names, then the
+ * index (30 Oct 2026). Called when a workspace is deleted — the store is kept
+ * by name beside the folder, so it used to outlive it: the files stayed
+ * downloadable under the old name, public links kept serving them, and a new
+ * workspace given the same name inherited them. Best effort per object (a
+ * leaked object costs storage; the index going is what makes them
+ * unreachable), and a no-op when there is no store.
+ */
+export async function purgeWorkspaceStorage(tenant: string, workspace: string): Promise<void> {
+  const dir = storeDirOf(tenant, workspace);
+  if (!dir || !fs.existsSync(dir)) return;
+  const driver = driverFor(tenant, workspace);
+  if (driver.kind !== "fs") {
+    const shas = new Set(readIndex(tenant, workspace).files.map((f) => f.sha));
+    for (const sha of shas) await driver.remove(blobKey(tenant, workspace, sha)).catch(() => {});
+  }
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+/**
+ * Move a workspace's stored files to its new name (30 Oct 2026). A rename
+ * used to move the folder only: the renamed workspace lost its files, and
+ * the old name kept them for whoever took it next.
+ *
+ * On fs the blobs live under the store's directory, so moving the directory
+ * is the whole move. On s3 an object's key carries the workspace name, so
+ * every object is copied first; only once all copies landed does the index
+ * move and the old objects go. A copy that fails leaves the store under the
+ * old name, whole, and throws — the caller can put the folder back.
+ *
+ * Whatever a store under the new name held is dropped first: it belonged to a
+ * workspace of that name that no longer exists, never to this one.
+ */
+export async function moveWorkspaceStorage(tenant: string, from: string, to: string): Promise<void> {
+  const src = storeDirOf(tenant, from);
+  const dest = storeDirOf(tenant, to);
+  if (!src || !dest || src === dest) return;
+  if (fs.existsSync(dest)) await purgeWorkspaceStorage(tenant, to);
+  if (!fs.existsSync(src)) return;
+  const driver = driverFor(tenant, from);
+  const shas = driver.kind === "fs" ? [] : [...new Set(readIndex(tenant, from).files.map((f) => f.sha))];
+  if (shas.length && !driver.copy) throw new Error(`the ${driver.kind} store cannot move files to a new workspace name`);
+  for (const sha of shas) await driver.copy!(blobKey(tenant, from, sha), blobKey(tenant, to, sha));
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.renameSync(src, dest);
+  for (const sha of shas) await driver.remove(blobKey(tenant, from, sha)).catch(() => {});
 }
 
 // ---------- the run mirror ----------