@easy-cms/core 0.39.0 → 0.41.0

package/dist/index.js

@@ -123,9 +123,13 @@ function cleanPermissions(value, known) {
     }
     return out;
   };
+  const folders = Array.isArray(input.folders) ? input.folders.filter(
+    (f) => typeof f === "string" || typeof f === "number"
+  ) : [];
   return {
     collections: pick(input.collections, known.collections, API_KEY_OPERATIONS),
-    globals: pick(input.globals, known.globals, API_KEY_GLOBAL_OPERATIONS)
+    globals: pick(input.globals, known.globals, API_KEY_GLOBAL_OPERATIONS),
+    ...folders.length > 0 ? { folders } : {}
   };
 }
 
@@ -286,6 +290,14 @@ function mediaFields() {
     { name: "alt", type: "text", label: { en: "Alternative text", th: "\u0E02\u0E49\u0E2D\u0E04\u0E27\u0E32\u0E21\u0E41\u0E17\u0E19\u0E23\u0E39\u0E1B" } }
   ];
 }
+var privateField = {
+  name: "private",
+  type: "boolean",
+  index: true,
+  access: systemField,
+  position: "sidebar",
+  label: { en: "Private", th: "\u0E2A\u0E48\u0E27\u0E19\u0E15\u0E31\u0E27" }
+};
 var adminField = {
   read: ({ user }) => user?.role === "admin" && !user.apiKey,
   update: ({ user }) => user?.role === "admin" && !user.apiKey
@@ -324,6 +336,22 @@ var mediaFoldersCollection = {
       index: true,
       label: { en: "In folder", th: "\u0E2D\u0E22\u0E39\u0E48\u0E43\u0E19\u0E42\u0E1F\u0E25\u0E40\u0E14\u0E2D\u0E23\u0E4C" }
     },
+    // For code to find the folder (`folder: 'banners'` on upload fields); set when it is made.
+    {
+      name: "key",
+      type: "text",
+      unique: true,
+      maxLength: 60,
+      access: { update: ({ id }) => id === void 0 },
+      label: { en: "Key", th: "\u0E04\u0E35\u0E22\u0E4C" }
+    },
+    // Its files and subfolders are private: only for users who may see them, and signed links.
+    {
+      name: "private",
+      type: "boolean",
+      access: { update: adminField.update },
+      label: { en: "Private", th: "\u0E2A\u0E48\u0E27\u0E19\u0E15\u0E31\u0E27" }
+    },
     // `null`: as the parent folder. Otherwise each role's level (`view`, `edit`, `manage`);
     // roles not listed get nothing.
     {
@@ -351,7 +379,11 @@ function withMedia(config) {
     icon: "image",
     useAsTitle: "filename",
     ...custom,
-    fields: [...mediaFields(), ...folders ? [folderField] : [], ...custom?.fields ?? []],
+    fields: [
+      ...mediaFields(),
+      ...folders ? [folderField, privateField] : [],
+      ...custom?.fields ?? []
+    ],
     access: {
       read: anyone,
       create: isLoggedIn,
@@ -380,8 +412,9 @@ function withMedia(config) {
       afterDelete: [
         async ({ doc, cms }) => {
           const sizes = Object.values(doc.sizes ?? {});
+          const storage = cms.storageFor(doc.private === true);
           for (const key2 of [doc.filename, ...sizes.map((s) => s.filename)]) {
-            if (typeof key2 === "string") await cms.storage.delete(key2);
+            if (typeof key2 === "string") await storage.delete(key2);
           }
         },
         ...custom?.hooks?.afterDelete ?? []
@@ -1062,11 +1095,28 @@ function imageDimensions(data, type) {
   }
   return void 0;
 }
+function typeFromName(name) {
+  const extension = /\.([a-z0-9]+)$/i.exec(name)?.[1]?.toLowerCase();
+  if (!extension) return void 0;
+  if (extension === "jpeg") return "image/jpeg";
+  return Object.entries(EXTENSIONS).find(([, ext]) => ext === extension)?.[0];
+}
 function storageKey(originalName, type, random2) {
   const name = originalName.split(/[\\/]/).pop() ?? "";
   const base = name.replace(/(?<=.)\.[^.]*$/, "").normalize("NFKC").toLowerCase().replace(/[^\p{L}\p{M}\p{N}]+/gu, "-").replace(/^-+|-+$/g, "").slice(0, 60) || "file";
   return `${base}-${random2}.${EXTENSIONS[type] ?? "bin"}`;
 }
+function isPrivateKey(key2) {
+  return /\.private[.-]/.test(key2);
+}
+function withPrivacy(key2, isPrivate) {
+  const plain = key2.replace(/\.private(?=\.[^.]+$)/, "");
+  return isPrivate ? plain.replace(/\.([^.]+)$/, ".private.$1") : plain;
+}
+function sizeKey(filename, size) {
+  return filename.replace(/\.([^.]+)$/, `-${size}.$1`);
+}
+var PRIVATE_KEY = /^[\p{L}\p{M}\p{N}-]+\.private(-[\p{L}\p{N}_-]+)?\.[a-z0-9]+$/u;
 
 // src/fields.ts
 var isHasMany = (field) => (field.type === "select" || field.type === "relationship" || field.type === "upload") && field.hasMany === true;
@@ -2806,7 +2856,8 @@ async function normalizeValue(field, raw, path, options, fail, errors, reference
           collection: target,
           id,
           ...field.type === "relationship" && field.filterOptions ? { filterOptions: field.filterOptions } : {},
-          ...field.type === "upload" && field.mimeTypes ? { mimeTypes: field.mimeTypes } : {}
+          ...field.type === "upload" && field.mimeTypes ? { mimeTypes: field.mimeTypes } : {},
+          ...field.type === "upload" && field.folder && field.folderOnly ? { folderOnly: field.folder } : {}
         });
       }
       return many ? ids : ids[0];
@@ -4503,6 +4554,25 @@ function validateCors(cors, add) {
 }
 function validateUpload(config, add) {
   const upload = config.upload;
+  if (upload?.folders !== true) {
+    const walk = (fields, path) => {
+      for (const [i, field] of fields.entries()) {
+        const at = `${path}.fields[${i}]`;
+        if (field.type === "upload" && field.folder !== void 0)
+          add(`${at}.folder`, "needs upload.folders: true", "upload: { folders: true }");
+        if ((field.type === "group" || field.type === "array") && Array.isArray(field.fields))
+          walk(field.fields, at);
+        if (field.type === "blocks" && Array.isArray(field.blocks)) {
+          for (const [b, block] of field.blocks.entries())
+            if (Array.isArray(block?.fields)) walk(block.fields, `${at}.blocks[${b}]`);
+        }
+      }
+    };
+    for (const [i, c] of (config.collections ?? []).entries())
+      if (Array.isArray(c?.fields)) walk(c.fields, `collections[${i}]`);
+    for (const [i, g] of (config.globals ?? []).entries())
+      if (Array.isArray(g?.fields)) walk(g.fields, `globals[${i}]`);
+  }
   if (upload === void 0) return;
   if (upload.maxFileSize !== void 0 && !(Number.isInteger(upload.maxFileSize) && upload.maxFileSize > 0)) {
     add("upload.maxFileSize", "must be a positive integer (bytes)");
@@ -4519,6 +4589,9 @@ function validateUpload(config, add) {
     );
   if (upload.folders !== void 0 && typeof upload.folders !== "boolean")
     add("upload.folders", "must be true or false");
+  const privateStorage = upload.privateStorage;
+  if (privateStorage !== void 0 && (typeof privateStorage !== "object" || privateStorage === null || typeof privateStorage.get !== "function"))
+    add("upload.privateStorage", "must be a storage adapter", "e.g. s3Storage({ \u2026 })");
   const fromURL = upload.fromURL;
   if (fromURL === void 0) return;
   if (typeof fromURL !== "object" || fromURL === null) {
@@ -4544,6 +4617,7 @@ function validateUpload(config, add) {
   if (allowPrivate !== void 0 && typeof allowPrivate !== "boolean")
     add("upload.fromURL.allowPrivate", "must be true or false");
 }
+var FOLDER_KEY = /^[a-z0-9][a-z0-9_-]{0,59}$/;
 var MIME_PATTERN = /^([\w.+-]+\/(\*|[\w.+-]+)|documents|office|archives)$/i;
 var HOST_PATTERN = /^(\*|(\*\.)?[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*)$/i;
 function validateAudit(config, add) {
@@ -4792,6 +4866,14 @@ function validateField(field, path, siblings, collectionSlugs, add) {
       break;
     case "upload":
       validateManyRange(field, path, add);
+      if (field.folder !== void 0 && !FOLDER_KEY.test(String(field.folder)))
+        add(
+          `${path}.folder`,
+          'must be a folder key: lowercase letters, digits, "-" or "_"',
+          "e.g. folder: 'banners'"
+        );
+      if (field.folderOnly !== void 0 && field.folder === void 0)
+        add(`${path}.folderOnly`, "needs folder");
       if (field.mimeTypes !== void 0) {
         const types = field.mimeTypes;
         if (!Array.isArray(types) || types.length === 0 || !types.every((t) => typeof t === "string" && MIME_PATTERN.test(t))) {
@@ -5070,7 +5152,8 @@ async function resolveConfig(input) {
       imageSizes: config.upload?.imageSizes ?? [],
       folders: config.upload?.folders === true,
       ...config.upload?.storage ? { storage: config.upload.storage } : {},
-      ...config.upload?.fromURL ? { fromURL: config.upload.fromURL } : {}
+      ...config.upload?.fromURL ? { fromURL: config.upload.fromURL } : {},
+      ...config.upload?.privateStorage ? { privateStorage: config.upload.privateStorage } : {}
     },
     auth: {
       roles: config.auth?.roles ?? DEFAULT_ROLES,
@@ -5173,7 +5256,7 @@ async function loadConfig(options = {}) {
 }
 
 // src/local-api.ts
-import { randomBytes as randomBytes5 } from "crypto";
+import { createHmac as createHmac5, randomBytes as randomBytes5, timingSafeEqual as timingSafeEqual4 } from "crypto";
 
 // src/localization.ts
 var ALL_LOCALES = "all";
@@ -5286,6 +5369,14 @@ var silentLogger = { info() {
 var FOLDER_LEVELS = ["view", "edit", "manage"];
 var RANK = { none: 0, view: 1, edit: 2, manage: 3 };
 var TTL2 = 1e4;
+var PUBLIC_FILES = {
+  or: [{ private: { equals: false } }, { private: { exists: false } }]
+};
+function keyFolders(user) {
+  const key2 = user?.apiKey;
+  const folders = key2?.permissions?.folders;
+  return folders && folders.length > 0 ? folders : void 0;
+}
 function needed(collection2, operation) {
   if (operation === "read") return "view";
   return collection2 === MEDIA ? "edit" : "manage";
@@ -5318,6 +5409,8 @@ var MediaFolders = class {
         id: doc.id,
         parent: doc.parent ?? null,
         name: String(doc.name ?? ""),
+        key: typeof doc.key === "string" && doc.key ? doc.key : null,
+        private: doc.private === true,
         permissions: permissions && typeof permissions === "object" && !Array.isArray(permissions) ? permissions : null
       });
     }
@@ -5338,6 +5431,98 @@ var MediaFolders = class {
     }
     return "manage";
   }
+  /** Whether files in a folder (`null`: the top level) are private: it or a folder above is. */
+  privateIn(rows, id) {
+    const seen = /* @__PURE__ */ new Set();
+    let current = id === null ? void 0 : rows.get(String(id));
+    while (current && !seen.has(String(current.id))) {
+      if (current.private) return true;
+      seen.add(String(current.id));
+      current = current.parent === null ? void 0 : rows.get(String(current.parent));
+    }
+    return false;
+  }
+  /** Whether files put in this folder are private. */
+  async isPrivate(id) {
+    if (!this.enabled || id === null) return false;
+    return this.privateIn(await this.rows(), id);
+  }
+  /** The folder and every folder inside it. */
+  within(rows, ids) {
+    const out = new Set(ids.map(String));
+    let grew = true;
+    while (grew) {
+      grew = false;
+      for (const row of rows.values())
+        if (row.parent !== null && out.has(String(row.parent)) && !out.has(String(row.id))) {
+          out.add(String(row.id));
+          grew = true;
+        }
+    }
+    return [...rows.values()].filter((r) => out.has(String(r.id))).map((r) => r.id);
+  }
+  /** Folders whose privacy follows this one: it and those inside, with their privacy now. */
+  async subtree(id) {
+    const rows = await this.fresh();
+    return this.within(rows, [id]).map((f) => ({ id: f, private: this.privateIn(rows, f) }));
+  }
+  /**
+   * The privacy each folder of a subtree would have after a change to its top folder: made
+   * private or public, moved, or (as `private: false`) deleted with its contents moving up.
+   */
+  async privacyAfter(id, change) {
+    const rows = new Map(await this.fresh());
+    const row = rows.get(String(id));
+    if (!row) return [];
+    rows.set(String(id), {
+      ...row,
+      ...change.private !== void 0 ? { private: change.private } : {},
+      ...change.parent !== void 0 ? { parent: change.parent } : {}
+    });
+    return this.within(rows, [id]).map((f) => ({ id: f, private: this.privateIn(rows, f) }));
+  }
+  /**
+   * The folder with this key (`folder: 'banners'` on upload fields), made at the top level when
+   * there is none yet.
+   */
+  async keyed(key2) {
+    const find = async () => [...(await this.rows()).values()].find((r) => r.key === key2);
+    let found = await find();
+    if (!found) {
+      this.invalidate();
+      found = await find();
+    }
+    if (found) return found.id;
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    try {
+      const doc = await this.db.create({
+        collection: MEDIA_FOLDERS,
+        data: {
+          name: key2,
+          key: key2,
+          parent: null,
+          permissions: null,
+          private: false,
+          createdAt: now,
+          updatedAt: now
+        }
+      });
+      this.invalidate();
+      return doc.id;
+    } catch (error) {
+      this.invalidate();
+      const again = await find();
+      if (again) return again.id;
+      throw error;
+    }
+  }
+  /** Whether a file in `folder` is in the folder with this key, or below it. */
+  async inKeyed(key2, folder) {
+    if (folder === null) return false;
+    const rows = await this.rows();
+    const root = [...rows.values()].find((r) => r.key === key2);
+    return !!root && this.within(rows, [root.id]).some((id) => String(id) === String(folder));
+  }
   /** The user's level in a folder (`null`: the top level). */
   async level(user, id) {
     if (!this.applies(user)) return "manage";
@@ -5348,7 +5533,15 @@ var MediaFolders = class {
    * they add none (no folder limits this user).
    */
   async where(user, collection2, operation) {
-    if (collection2 !== MEDIA && collection2 !== MEDIA_FOLDERS || !this.applies(user)) return true;
+    if (!this.enabled || collection2 !== MEDIA && collection2 !== MEDIA_FOLDERS) return true;
+    if (!user) return collection2 === MEDIA ? PUBLIC_FILES : true;
+    const limited = keyFolders(user);
+    if (limited) {
+      const ids = this.within(await this.rows(), limited);
+      if (collection2 === MEDIA_FOLDERS) return { id: { in: ids } };
+      return operation === "create" ? true : { folder: { in: ids } };
+    }
+    if (!this.applies(user)) return true;
     if (operation === "create") return true;
     const need = RANK[needed(collection2, operation)];
     const rows = await this.rows();
@@ -5365,6 +5558,13 @@ var MediaFolders = class {
   }
   /** Refuses putting a file (`media`) or a subfolder in a folder the user may not. */
   async checkTarget(user, collection2, folder) {
+    const limited = keyFolders(user);
+    if (limited) {
+      const ids = this.within(await this.rows(), limited).map(String);
+      if (folder === null || !ids.includes(String(folder)))
+        throw new ForbiddenError("This API key may not add to this folder");
+      return;
+    }
     if (!this.applies(user)) return;
     const need = collection2 === MEDIA ? "edit" : "manage";
     if (RANK[await this.level(user, folder)] < RANK[need])
@@ -5729,6 +5929,7 @@ async function createEasyCMS(config, options = {}) {
   const cwd = options.cwd ?? process.cwd();
   const storage = resolved3.upload.storage ?? localStorage({ dir: resolved3.upload.dir });
   await storage.init?.({ cwd });
+  if (resolved3.upload.privateStorage) await resolved3.upload.privateStorage.init?.({ cwd });
   const db = await resolved3.db.init({
     config: resolved3,
     cwd,
@@ -5757,6 +5958,11 @@ var EasyCMS = class {
   auth;
   /** Where uploaded files are stored. */
   storage;
+  /**
+   * Where files in private folders are stored (`upload.privateStorage`, else `storage` when it has
+   * no public URLs); `null` when private folders can't be used.
+   */
+  privateStorage;
   /** Project root: relative paths in the config (e.g. `admin.modules`) start here. */
   cwd;
   /** Roles and their permissions (`auth.rbac`, Settings → Roles). */
@@ -5768,11 +5974,12 @@ var EasyCMS = class {
   versions;
   webhooks;
   mailer;
-  constructor(config, db, logger = consoleLogger, storage = localStorage({ dir: config.upload.dir }), cwd = process.cwd()) {
+  constructor(config, db, logger = consoleLogger, storage = localStorage({ dir: config.upload.dir }), cwd = process.cwd(), privateStorage) {
     this.config = config;
     this.db = db;
     this.logger = logger;
     this.storage = storage;
+    this.privateStorage = privateStorage !== void 0 ? privateStorage : config.upload.privateStorage ?? (typeof storage.url === "function" ? null : storage);
     this.cwd = cwd;
     this.versions = new VersionStore(db);
     this.roles = new Roles(
@@ -5873,12 +6080,7 @@ var EasyCMS = class {
   async upload(file, data = {}, options = {}) {
     const config = this.collection(MEDIA);
     const guard = guardOf(options);
-    if (guard.enforce) {
-      await this.checkGrant(guard, { collection: MEDIA }, "create");
-      const allowed2 = await evaluateAccess(config.access?.create, { user: guard.user, data });
-      if (allowed2 !== true) throw deny(guard.user);
-      await this.folders.checkTarget(guard.user, MEDIA, folderOf(MEDIA, data));
-    }
+    await this.checkUpload(guard, data, folderOf(MEDIA, data));
     const { maxFileSize, mimeTypes, imageSizes } = this.config.upload;
     if (file.data.byteLength > maxFileSize) {
       throw new PayloadTooLargeError(`File is larger than ${maxFileSize} bytes`);
@@ -5895,17 +6097,27 @@ var EasyCMS = class {
       ]);
     }
     const random2 = randomBytes5(4).toString("hex");
-    const filename = storageKey(file.name, mimeType, random2);
+    const isPrivate = await this.folders.isPrivate(folderOf(MEDIA, data));
+    const storage = this.storageFor(isPrivate);
+    const filename = withPrivacy(storageKey(file.name, mimeType, random2), isPrivate);
     const stored = [];
     try {
-      await this.storage.put(filename, file.data, { contentType: mimeType });
+      await storage.put(filename, file.data, { contentType: mimeType });
       stored.push(filename);
       const dimensions = imageDimensions(file.data, mimeType);
-      const sizes = await this.resizeImage(file.data, mimeType, filename, imageSizes, stored);
+      const sizes = await this.resizeImage(
+        file.data,
+        mimeType,
+        filename,
+        imageSizes,
+        stored,
+        storage
+      );
       const doc = await this.createDocument(
         config,
         {
           ...data,
+          ...this.folders.enabled ? { private: isPrivate } : {},
           filename,
           originalName: file.name.slice(0, 255),
           mimeType,
@@ -5920,11 +6132,155 @@ var EasyCMS = class {
       );
       return doc;
     } catch (error) {
-      for (const key2 of stored) await this.storage.delete(key2).catch(() => {
+      for (const key2 of stored) await storage.delete(key2).catch(() => {
       });
       throw error;
     }
   }
+  /**
+   * Starts an upload straight to the storage, for files too large to send through the server
+   * (`POST <api>/media/uploads`): checks who uploads what where, as `upload()` does, and returns
+   * a signed ticket and where to send the file. `upload` is `null` when the storage can't take
+   * files directly: send it to `upload()` instead. Then `completeUpload(ticket)`.
+   */
+  async createUpload(file, data = {}, options = {}) {
+    const guard = guardOf(options);
+    const folder = folderOf(MEDIA, data);
+    await this.checkUpload(guard, data, folder);
+    const { maxFileSize, mimeTypes } = this.config.upload;
+    const size = Number(file.size);
+    if (!Number.isInteger(size) || size <= 0)
+      throw new ValidationError(MEDIA, [{ field: "size", message: "must be the size in bytes" }]);
+    if (size > maxFileSize)
+      throw new PayloadTooLargeError(`File is larger than ${maxFileSize} bytes`);
+    const name = String(file.name ?? "").slice(0, 255);
+    const type = typeFromName(name) ?? file.type ?? "";
+    if (!EXTENSIONS[type] || !mimeAllowed(type, mimeTypes))
+      throw new ValidationError(MEDIA, [
+        {
+          field: "file",
+          message: `file type ${type || "unknown"} is not allowed (allowed: ${mimeTypes.join(", ")})`
+        }
+      ]);
+    const isPrivate = await this.folders.isPrivate(folder);
+    const storage = this.storageFor(isPrivate);
+    const key2 = withPrivacy(storageKey(name, type, randomBytes5(4).toString("hex")), isPrivate);
+    const upload = storage.uploadURL ? await storage.uploadURL(key2, { contentType: type, size, expiresIn: UPLOAD_URL_SECONDS }) : null;
+    const ticket = this.sign("upload", {
+      key: key2,
+      private: isPrivate,
+      name,
+      size,
+      type,
+      user: guard.user?.id ?? null,
+      expires: Math.floor(Date.now() / 1e3) + UPLOAD_TICKET_SECONDS,
+      data
+    });
+    return { ticket, upload };
+  }
+  /**
+   * Finishes an upload made with `createUpload()` (`POST <api>/media/uploads/complete`): checks
+   * the file in the storage like any upload (its size, and its type from its contents), then
+   * makes its media document. A file that fails is deleted.
+   */
+  async completeUpload(ticket, options = {}) {
+    const guard = guardOf(options);
+    const t = this.verify("upload", ticket);
+    if (!t || t.expires < Date.now() / 1e3)
+      throw new ValidationError(MEDIA, [
+        { field: "ticket", message: "is not valid or has expired" }
+      ]);
+    if (guard.enforce && String(guard.user?.id ?? null) !== String(t.user)) throw deny(guard.user);
+    await this.checkUpload(guard, t.data, folderOf(MEDIA, t.data));
+    if (await this.db.count({ collection: MEDIA, where: { filename: { equals: t.key } } }) > 0)
+      throw new ValidationError(MEDIA, [{ field: "ticket", message: "was used already" }]);
+    const storage = this.storageFor(t.private);
+    const start = storage.getStart ? await storage.getStart(t.key, SNIFF_BYTES) : await storage.get(t.key);
+    if (!start) throw new ValidationError(MEDIA, [{ field: "file", message: "was not uploaded" }]);
+    const refuse = async (message2) => {
+      await storage.delete(t.key).catch(() => {
+      });
+      throw new ValidationError(MEDIA, [{ field: "file", message: message2 }]);
+    };
+    if (start.size !== t.size) await refuse(`is ${start.size} bytes, not the ${t.size} announced`);
+    if (start.size > this.config.upload.maxFileSize)
+      await refuse(`is larger than ${this.config.upload.maxFileSize} bytes`);
+    const mimeType = sniffMimeType(start.body.subarray(0, SNIFF_BYTES), t.name);
+    if (mimeType !== t.type)
+      await refuse(`contains ${mimeType ?? "an unknown type"}, not ${t.type}`);
+    const stored = [];
+    try {
+      let dimensions;
+      let sizes = {};
+      if (t.type.startsWith("image/")) {
+        const whole = await storage.get(t.key);
+        if (whole) {
+          dimensions = imageDimensions(whole.body, t.type);
+          sizes = await this.resizeImage(
+            whole.body,
+            t.type,
+            t.key,
+            this.config.upload.imageSizes,
+            stored,
+            storage
+          );
+        }
+      }
+      const doc = await this.createDocument(
+        this.collection(MEDIA),
+        {
+          ...t.data,
+          ...this.folders.enabled ? { private: t.private } : {},
+          filename: t.key,
+          originalName: t.name,
+          mimeType: t.type,
+          filesize: start.size,
+          width: dimensions?.width ?? null,
+          height: dimensions?.height ?? null,
+          sizes
+        },
+        { ...options, overrideAccess: true },
+        guard
+      );
+      return doc;
+    } catch (error) {
+      for (const key2 of [t.key, ...stored]) await storage.delete(key2).catch(() => {
+      });
+      throw error;
+    }
+  }
+  /** Who may upload, and into which folder: `upload()` and direct uploads. */
+  async checkUpload(guard, data, folder) {
+    if (!guard.enforce) return;
+    await this.checkGrant(guard, { collection: MEDIA }, "create");
+    const allowed2 = await evaluateAccess(this.collection(MEDIA).access?.create, {
+      user: guard.user,
+      data
+    });
+    if (allowed2 !== true) throw deny(guard.user);
+    await this.folders.checkTarget(guard.user, MEDIA, folder);
+  }
+  /** A value with its HMAC (`secret`), for `purpose` only: `<base64url JSON>.<signature>`. */
+  sign(purpose, value) {
+    const payload = Buffer.from(JSON.stringify(value)).toString("base64url");
+    const mac = createHmac5("sha256", this.config.secret).update(`${purpose}:${payload}`);
+    return `${payload}.${mac.digest("base64url")}`;
+  }
+  /** The value of a token made by `sign`, or `undefined` when it isn't genuine. */
+  verify(purpose, token) {
+    const [payload, signature] = String(token).split(".");
+    if (!payload || !signature) return void 0;
+    const expected = Buffer.from(
+      createHmac5("sha256", this.config.secret).update(`${purpose}:${payload}`).digest("base64url")
+    );
+    const given = Buffer.from(signature);
+    if (expected.length !== given.length || !timingSafeEqual4(expected, given)) return void 0;
+    try {
+      return JSON.parse(Buffer.from(payload, "base64url").toString());
+    } catch {
+      return void 0;
+    }
+  }
   /**
    * Downloads a file from an `http(s)` link and uploads it like `upload()`. Private network
    * addresses are refused unless `upload.fromURL.allowPrivate`. Calls on behalf of a user (the
@@ -5995,9 +6351,159 @@ var EasyCMS = class {
   }
   /** Public URL of a stored file. */
   mediaURL(key2) {
+    const base = `${this.config.serverURL?.replace(/\/+$/, "") ?? ""}${this.config.routes.api}`;
+    if (isPrivateKey(key2)) return `${base}/media/private/${encodeURIComponent(key2)}`;
     const custom = this.storage.url?.(key2);
     if (custom) return custom;
-    return `${this.config.serverURL?.replace(/\/+$/, "") ?? ""}${this.config.routes.api}/media/file/${encodeURIComponent(key2)}`;
+    return `${base}/media/file/${encodeURIComponent(key2)}`;
+  }
+  /**
+   * A link to a private file that works without signing in until it expires: `expiresIn` in
+   * seconds or as `'30m'`, `'1h'` (the default), `'7d'` (the most). Public files get their usual
+   * URL. `size`: one of the file's resized copies. Links stop working when `secret` changes or
+   * the file stops being private.
+   */
+  signedMediaURL(doc, options = {}) {
+    const sizes = doc.sizes ?? {};
+    const key2 = options.size ? sizes[options.size]?.filename : doc.filename;
+    if (typeof key2 !== "string" || !key2)
+      throw new QueryError(
+        options.size ? `The file has no "${options.size}" size` : "The document is not a file"
+      );
+    if (!isPrivateKey(key2)) return this.mediaURL(key2);
+    const seconds = durationSeconds(options.expiresIn ?? "1h");
+    const expires = Math.floor(Date.now() / 1e3) + seconds;
+    return `${this.mediaURL(key2)}?expires=${expires}&signature=${this.mediaSignature(key2, expires)}`;
+  }
+  /** Whether a signed link to a private file is genuine and not expired. */
+  verifyMediaSignature(key2, expires, signature) {
+    const at = Number(expires);
+    if (!signature || !Number.isInteger(at) || at < Date.now() / 1e3) return false;
+    const expected = Buffer.from(this.mediaSignature(key2, at));
+    const given = Buffer.from(signature);
+    return expected.length === given.length && timingSafeEqual4(expected, given);
+  }
+  mediaSignature(key2, expires) {
+    return createHmac5("sha256", this.config.secret).update(`media:${key2}:${expires}`).digest("base64url");
+  }
+  /**
+   * How many documents use any of these files in a top-level upload field (rich text and fields
+   * inside groups, arrays and blocks are not counted). Drafts count too.
+   */
+  async mediaUsage(ids) {
+    if (ids.length === 0) return 0;
+    let count = 0;
+    for (const config of this.config.collections) {
+      if (INTERNAL_COLLECTIONS.has(config.slug)) continue;
+      for (const field of config.fields) {
+        if (field.type !== "upload") continue;
+        count += await this.db.count({
+          collection: config.slug,
+          where: { [field.name]: { in: [...ids] } }
+        });
+      }
+    }
+    return count;
+  }
+  /** The storage for public files, or for private ones. */
+  storageFor(isPrivate) {
+    if (!isPrivate) return this.storage;
+    if (!this.privateStorage)
+      throw new EasyCMSError(
+        "Private folders need upload.privateStorage: the storage has public URLs, so private files must be kept elsewhere",
+        500
+      );
+    return this.privateStorage;
+  }
+  /**
+   * Copies a file and its resized copies to the other storage under their new names (`.private`
+   * added or removed). Returns the fields to save, and `cleanUp` to delete the old copies once
+   * the document points to the new ones.
+   */
+  async relocate(doc, toPrivate) {
+    const from = this.storageFor(doc.private === true);
+    const to = this.storageFor(toPrivate);
+    const contentType = String(doc.mimeType ?? "application/octet-stream");
+    const filename = withPrivacy(String(doc.filename), toPrivate);
+    const old = [String(doc.filename)];
+    const copy = async (source, target) => {
+      const file = await from.get(source);
+      if (file) await to.put(target, file.body, { contentType });
+    };
+    await copy(String(doc.filename), filename);
+    const sizes = {};
+    for (const [name, size] of Object.entries(
+      doc.sizes ?? {}
+    )) {
+      const key2 = sizeKey(filename, name);
+      await copy(String(size.filename), key2);
+      old.push(String(size.filename));
+      sizes[name] = { ...size, filename: key2 };
+    }
+    return {
+      patch: { filename, sizes, private: toPrivate },
+      cleanUp: async () => {
+        for (const key2 of old) await from.delete(key2).catch(() => {
+        });
+      }
+    };
+  }
+  /** A folder's name, parent and permissions; private only with somewhere private to keep files. */
+  async validateFolder(data, self) {
+    await this.folders.validate(data, self);
+    if (data.private === true && !this.privateStorage)
+      throw new ValidationError(MEDIA_FOLDERS, [
+        {
+          field: "private",
+          message: "needs upload.privateStorage: the storage gives files public URLs, so private files must be kept elsewhere"
+        }
+      ]);
+  }
+  /**
+   * Refuses a change that would move more than 200 files between storages in one request: they
+   * are copied one by one, which could outlast a serverless function.
+   */
+  async checkMoveLimit(folders) {
+    let count = 0;
+    for (const f of folders)
+      count += await this.db.count({
+        collection: MEDIA,
+        where: andWhere(
+          { folder: { equals: f.id } },
+          f.private ? PUBLIC_FILES : { private: { equals: true } }
+        )
+      });
+    if (count > MAX_FILES_TO_MOVE)
+      throw new ValidationError(MEDIA_FOLDERS, [
+        {
+          field: "private",
+          message: `${count} files would move between public and private storage; move at most ${MAX_FILES_TO_MOVE} at a time (folder by folder)`
+        }
+      ]);
+  }
+  /** After a folder became private or public (or moved): its files follow, in every subfolder. */
+  async settlePrivacy(folder) {
+    for (const f of await this.folders.subtree(folder))
+      await this.settleFiles({ folder: { equals: f.id } }, f.private);
+  }
+  /** Files at the top level are public. */
+  async settleTopLevel() {
+    await this.settleFiles({ folder: { exists: false } }, false);
+  }
+  async settleFiles(where, isPrivate) {
+    const found = await this.db.find({
+      collection: MEDIA,
+      where: andWhere(where, isPrivate ? PUBLIC_FILES : { private: { equals: true } }),
+      sort: [],
+      limit: 0,
+      page: 1
+    });
+    for (const doc of found.docs) {
+      const moved = await this.relocate(doc, isPrivate);
+      const { id, ...rest } = doc;
+      await this.db.update({ collection: MEDIA, id, data: { ...rest, ...moved.patch } });
+      await moved.cleanUp();
+    }
   }
   async update(collection2, id, data, options = {}) {
     return await this.updateDocument(collection2, id, asObject(data, collection2), options);
@@ -6279,13 +6785,35 @@ var EasyCMS = class {
     }
     if (config.slug === USERS) await this.guardLastAdmin(parsed, existing, prepared);
     if (password !== void 0) prepared.passwordHash = await hashPassword(password);
-    if (collection2 === MEDIA_FOLDERS) await this.folders.validate(prepared, parsed);
+    if (collection2 === MEDIA_FOLDERS) {
+      await this.validateFolder(prepared, parsed);
+      if (prepared.private !== existing.private || String(prepared.parent ?? null) !== String(existing.parent ?? null))
+        await this.checkMoveLimit(
+          await this.folders.privacyAfter(parsed, {
+            private: prepared.private === true,
+            parent: prepared.parent ?? null
+          })
+        );
+    }
+    let moved;
+    if (collection2 === MEDIA && this.folders.enabled) {
+      const toPrivate = await this.folders.isPrivate(folderOf(MEDIA, prepared));
+      if (toPrivate !== (existing.private === true)) {
+        moved = await this.relocate(existing, toPrivate);
+        Object.assign(prepared, moved.patch);
+      }
+    }
     const doc = await this.db.update({
       collection: collection2,
       id: parsed,
       data: { ...prepared, createdAt: existing.createdAt, updatedAt: now }
     });
-    if (collection2 === MEDIA_FOLDERS) this.folders.invalidate();
+    if (moved) await moved.cleanUp();
+    if (collection2 === MEDIA_FOLDERS) {
+      this.folders.invalidate();
+      if (prepared.private !== existing.private || String(prepared.parent ?? null) !== String(existing.parent ?? null))
+        await this.settlePrivacy(parsed);
+    }
     if (!live) await this.saveVersion(config, collectionParent(collection2), parsed, doc, guard);
     if (password !== void 0) await this.auth.revokeSessions(parsed);
     await this.notify(config.hooks?.afterChange, "afterChange", config.slug, {
@@ -6328,9 +6856,17 @@ var EasyCMS = class {
       await this.auth.revokeSessions(parsed);
       await this.auth.sso.forget(parsed);
     }
-    if (collection2 === MEDIA_FOLDERS) await this.folders.release(existing);
+    if (collection2 === MEDIA_FOLDERS) {
+      await this.checkMoveLimit(await this.folders.privacyAfter(parsed, { private: false }));
+      await this.folders.release(existing);
+    }
     await this.db.delete({ collection: collection2, id: parsed });
-    if (collection2 === MEDIA_FOLDERS) this.folders.invalidate();
+    if (collection2 === MEDIA_FOLDERS) {
+      this.folders.invalidate();
+      const parent = existing.parent ?? null;
+      if (parent !== null) await this.settlePrivacy(parent);
+      else await this.settleTopLevel();
+    }
     if (versionLimit(config)) await this.versions.deleteAll(collectionParent(collection2), parsed);
     if (config.schedule) {
       for (const job of await this.pendingJobs(collection2, parsed))
@@ -7074,7 +7610,7 @@ var EasyCMS = class {
       prepared
     );
     if (password !== void 0) prepared.passwordHash = await hashPassword(password);
-    if (collection2 === MEDIA_FOLDERS) await this.folders.validate(prepared, void 0);
+    if (collection2 === MEDIA_FOLDERS) await this.validateFolder(prepared, void 0);
     const now = (/* @__PURE__ */ new Date()).toISOString();
     const doc = await this.db.create({
       collection: collection2,
@@ -7234,7 +7770,7 @@ var EasyCMS = class {
     }
   }
   /** Writes resized copies with sharp, when installed and configured. */
-  async resizeImage(data, mimeType, filename, sizes, stored) {
+  async resizeImage(data, mimeType, filename, sizes, stored, storage = this.storage) {
     if (sizes.length === 0 || !["image/png", "image/jpeg", "image/webp", "image/avif"].includes(mimeType))
       return {};
     const sharp = await loadSharp();
@@ -7252,8 +7788,8 @@ var EasyCMS = class {
         fit: size.fit ?? "cover",
         withoutEnlargement: true
       }).toBuffer({ resolveWithObject: true });
-      const key2 = filename.replace(/\.([^.]+)$/, `-${size.name}.$1`);
-      await this.storage.put(key2, new Uint8Array(out), { contentType: mimeType });
+      const key2 = sizeKey(filename, size.name);
+      await storage.put(key2, new Uint8Array(out), { contentType: mimeType });
       stored.push(key2);
       result[size.name] = {
         filename: key2,
@@ -7421,6 +7957,14 @@ var EasyCMS = class {
             message: images ? `must be an image (${doc.filename ?? ref.id} is ${type || "not one"})` : `must be ${ref.mimeTypes.join(", ")} (${doc.filename ?? ref.id} is ${type || "unknown"})`
           });
         }
+        if (ref.folderOnly && this.folders.enabled && !await this.folders.inKeyed(
+          ref.folderOnly,
+          doc.folder ?? null
+        ))
+          errors.push({
+            field: ref.field,
+            message: `must be a file from the "${ref.folderOnly}" folder (${doc.filename ?? ref.id} is not)`
+          });
       }
     }
     return errors;
@@ -7487,6 +8031,19 @@ function folderOf(collection2, data) {
   const value = data[collection2 === MEDIA ? "folder" : "parent"];
   return value === void 0 || value === "" ? null : value;
 }
+var MAX_LINK = 7 * 24 * 60 * 60;
+var UPLOAD_URL_SECONDS = 15 * 60;
+var UPLOAD_TICKET_SECONDS = 24 * 60 * 60;
+var SNIFF_BYTES = 64 * 1024;
+var MAX_FILES_TO_MOVE = 200;
+function durationSeconds(value) {
+  const match = typeof value === "string" ? /^(\d+)\s*([smhd])$/.exec(value.trim()) : null;
+  const seconds = typeof value === "number" ? value : match ? Number(match[1]) * { s: 1, m: 60, h: 3600, d: 86400 }[match[2]] : Number.NaN;
+  if (!Number.isFinite(seconds) || seconds <= 0)
+    throw new QueryError(`expiresIn must be seconds or like '30m', '1h', '7d' (got ${value})`);
+  if (seconds > MAX_LINK) throw new QueryError("expiresIn can be at most 7 days");
+  return Math.floor(seconds);
+}
 
 // src/rest/admin-modules.ts
 import { createHash as createHash3 } from "crypto";
@@ -7735,7 +8292,7 @@ function componentRef(component) {
 async function allowed(access, user) {
   return await evaluateAccess(access, { user }) !== false;
 }
-async function serializeFields(fields, checks, localized) {
+async function serializeFields(fields, checks, localized, folderId) {
   const { update: update2 } = checks;
   const out = [];
   for (const field of fields) {
@@ -7788,11 +8345,13 @@ async function serializeFields(fields, checks, localized) {
         if (field.minRows !== void 0) f.minRows = field.minRows;
         if (field.maxRows !== void 0) f.maxRows = field.maxRows;
         if (field.mimeTypes) f.mimeTypes = expandMimeTypes(field.mimeTypes);
+        if (field.folder && folderId)
+          f.folder = { id: await folderId(field.folder), only: field.folderOnly === true };
         break;
       case "array":
         if (field.minRows !== void 0) f.minRows = field.minRows;
         if (field.maxRows !== void 0) f.maxRows = field.maxRows;
-        f.fields = await serializeFields(field.fields, checks, localized);
+        f.fields = await serializeFields(field.fields, checks, localized, folderId);
         break;
       case "blocks":
         if (field.minRows !== void 0) f.minRows = field.minRows;
@@ -7801,12 +8360,12 @@ async function serializeFields(fields, checks, localized) {
           field.blocks.map(async (block) => ({
             slug: block.slug,
             ...block.labels ? { labels: block.labels } : {},
-            fields: await serializeFields(block.fields, checks, localized)
+            fields: await serializeFields(block.fields, checks, localized, folderId)
           }))
         );
         break;
       case "group":
-        f.fields = await serializeFields(field.fields, checks, localized);
+        f.fields = await serializeFields(field.fields, checks, localized, folderId);
         break;
     }
     out.push(f);
@@ -7825,7 +8384,12 @@ async function may(cms, access, user, target, operation) {
 }
 async function collection(cms, config, user, localized, roles) {
   const target = { collection: config.slug };
-  const fields = await serializeFields(config.fields, await checkers(cms, user), localized);
+  const fields = await serializeFields(
+    config.fields,
+    await checkers(cms, user),
+    localized,
+    folderIds(cms)
+  );
   if (config.slug === USERS && cms.roles.enabled) {
     const role = fields.find((f) => f.name === "role");
     if (role) {
@@ -7870,7 +8434,7 @@ async function global(cms, config, user, localized) {
     versions: Boolean(config.versions),
     preview: typeof config.preview === "function",
     schedule: config.schedule === true,
-    fields: await serializeFields(config.fields, checks, localized),
+    fields: await serializeFields(config.fields, checks, localized, folderIds(cms)),
     permissions: {
       read: await may(cms, config.access?.read, user, target, "read"),
       update: await may(cms, config.access?.update, user, target, "update"),
@@ -7915,7 +8479,13 @@ async function adminSchema(cms, user, origin) {
       maxFileSize: cms.config.upload.maxFileSize,
       mimeTypes: expandMimeTypes(cms.config.upload.mimeTypes)
     },
-    ...cms.folders.enabled ? { folders: { permissions: admin && cms.roles.enabled } } : {},
+    ...cms.folders.enabled ? {
+      folders: {
+        permissions: admin && cms.roles.enabled,
+        // Admins can make folders private when there is somewhere private to keep files.
+        private: admin && cms.privateStorage !== null
+      }
+    } : {},
     views,
     rbac: cms.roles.enabled,
     providers: cms.auth.sso.providers(),
@@ -7962,9 +8532,12 @@ async function widgets(cms, user) {
   }
   return out;
 }
+function folderIds(cms) {
+  return cms.folders.enabled ? (key2) => cms.folders.keyed(key2) : void 0;
+}
 
 // src/version.ts
-var VERSION = true ? "0.39.0" : "0.0.0-dev";
+var VERSION = true ? "0.41.0" : "0.0.0-dev";
 
 // src/rest/admin-status.ts
 var DAY2 = 864e5;
@@ -8533,6 +9106,12 @@ async function route(cms, ctx, method, segments, options) {
     if (parsed === void 0) throw new HttpError("Not found", 404);
     return { body: await cms.roles.owned(parsed) };
   }
+  if (first === "admin" && second === "media-usage" && segments.length === 2) {
+    if (!ctx.user || ctx.user.apiKey) throw new UnauthorizedError();
+    if (method !== "GET") throw methodNotAllowed(ctx, "GET");
+    const ids = (ctx.url.searchParams.get("ids") ?? "").split(",").map((id2) => parseId(id2)).filter((id2) => id2 !== void 0);
+    return { body: { count: await cms.mediaUsage(ids) } };
+  }
   if (first === "admin" && second === "roles") {
     if (!ctx.user) throw new UnauthorizedError();
     if (ctx.user.role !== "admin" || ctx.user.apiKey) throw new ForbiddenError();
@@ -8679,6 +9258,34 @@ async function route(cms, ctx, method, segments, options) {
     if (method !== "GET" && method !== "HEAD") throw methodNotAllowed(ctx, "GET, HEAD");
     return { body: await serveFile(cms, third, method === "HEAD") };
   }
+  if (first === MEDIA && second === "private" && third !== void 0 && segments.length === 3) {
+    if (method !== "GET" && method !== "HEAD") throw methodNotAllowed(ctx, "GET, HEAD");
+    return { body: await servePrivateFile(cms, ctx, third, method === "HEAD") };
+  }
+  if (first === MEDIA && second === "uploads" && segments.length <= 3) {
+    if (method !== "POST") throw methodNotAllowed(ctx, "POST");
+    const body = await readJson(ctx.request);
+    if (third === "complete" && segments.length === 3) {
+      if (typeof body.ticket !== "string" || body.ticket === "")
+        throw new ValidationError(MEDIA, [{ field: "ticket", message: "is required" }]);
+      return {
+        status: 201,
+        body: await cms.completeUpload(body.ticket, { ...access, ...parseDepth(ctx.url) })
+      };
+    }
+    if (third !== void 0) throw new HttpError("Not found", 404);
+    const { name, size, type, ...data } = body;
+    if (typeof name !== "string" || name === "")
+      throw new ValidationError(MEDIA, [{ field: "name", message: "is required" }]);
+    return {
+      status: 201,
+      body: await cms.createUpload(
+        { name, size: Number(size), ...typeof type === "string" ? { type } : {} },
+        data,
+        access
+      )
+    };
+  }
   if (first === MEDIA && second === void 0 && method === "POST") {
     if ((ctx.request.headers.get("content-type") ?? "").toLowerCase().startsWith("application/json")) {
       const { url, ...data2 } = await readJson(ctx.request);
@@ -8978,6 +9585,48 @@ async function serveFile(cms, key2, head) {
     }
   );
 }
+async function servePrivateFile(cms, ctx, key2, head) {
+  if (!PRIVATE_KEY.test(key2) || !cms.privateStorage) throw new HttpError("Not found", 404);
+  const query = ctx.url.searchParams;
+  const signed = cms.verifyMediaSignature(key2, query.get("expires"), query.get("signature"));
+  if (!signed) {
+    const token = /-([0-9a-f]{8})\.private[.-]/.exec(key2)?.[1];
+    if (!ctx.user || !token) throw new HttpError("Not found", 404);
+    const found = await cms.find(MEDIA, {
+      where: { filename: { like: `-${token}.private.` } },
+      limit: 5,
+      depth: 0,
+      user: ctx.user,
+      overrideAccess: false
+    });
+    const owns = found.docs.some(
+      (d) => d.filename === key2 || Object.values(d.sizes ?? {}).some(
+        (s) => s.filename === key2
+      )
+    );
+    if (!owns) throw new HttpError("Not found", 404);
+  }
+  const file = await cms.privateStorage.get(key2);
+  if (!file) throw new HttpError("Not found", 404);
+  const type = TYPE_BY_EXTENSION[key2.slice(key2.lastIndexOf(".") + 1)] ?? "application/octet-stream";
+  return new Response(
+    head ? null : file.body,
+    {
+      status: 200,
+      headers: {
+        "content-type": type,
+        "content-length": String(file.size),
+        // Not in shared caches; a short while in the browser.
+        "cache-control": "private, max-age=300",
+        "x-content-type-options": "nosniff",
+        ...type === "application/pdf" ? {} : {
+          "content-security-policy": "default-src 'none'; img-src 'self' data:; style-src 'unsafe-inline'; sandbox"
+        },
+        "cross-origin-resource-policy": "cross-origin"
+      }
+    }
+  );
+}
 async function readUpload(request, maxFileSize) {
   const type = request.headers.get("content-type") ?? "";
   if (!type.toLowerCase().startsWith("multipart/form-data")) {