@easy-cms/core 0.37.2 → 0.38.0

package/dist/index.d.ts

@@ -971,6 +971,61 @@ declare class Roles {
     private toRole;
 }
 
+/** What a role may do in a folder (`upload.folders` with `auth.rbac`), each including the last. */
+declare const FOLDER_LEVELS: readonly ["view", "edit", "manage"];
+/**
+ * `view`: see its files and use them in documents. `edit`: also upload, rename, move and delete
+ * files. `manage`: also create, rename, move and delete subfolders.
+ */
+type FolderLevel = (typeof FOLDER_LEVELS)[number];
+/** A folder's `permissions`: each role's level; roles not listed get nothing. */
+type FolderPermissions = Readonly<Record<string, FolderLevel>>;
+/**
+ * Folders of the media library and their permissions. A folder without its own permissions
+ * follows its parent; the top level is open to every role that may use `media`. Folder
+ * permissions only narrow what roles may do with `media`, for signed-in users (not API keys).
+ */
+declare class MediaFolders {
+    private readonly db;
+    private readonly roles;
+    readonly enabled: boolean;
+    private cache;
+    constructor(config: ResolvedConfig, db: Database, roles: Roles);
+    /** Whether folder permissions apply to this user. */
+    applies(user: AuthUser | null): user is AuthUser;
+    /** Forgets cached folders, after one changed. */
+    invalidate(): void;
+    private rows;
+    /** A role's level in a folder (`null`: the top level): the nearest permissions up the tree. */
+    private levelIn;
+    /** The user's level in a folder (`null`: the top level). */
+    level(user: AuthUser | null, id: ID | null): Promise<FolderLevel | 'none'>;
+    /**
+     * The constraint folder permissions add to an operation on files or folders, or `true` when
+     * they add none (no folder limits this user).
+     */
+    where(user: AuthUser | null, collection: string, operation: string): Promise<true | Where>;
+    /** Refuses putting a file (`media`) or a subfolder in a folder the user may not. */
+    checkTarget(user: AuthUser | null, collection: string, folder: ID | null): Promise<void>;
+    /**
+     * Checks a folder before it is saved: a name unique among its siblings (ignoring case), a
+     * parent that is not itself or inside it, and permissions for roles that exist.
+     */
+    validate(data: Record<string, unknown>, self: ID | undefined): Promise<void>;
+    /**
+     * Before a folder is deleted: its files and subfolders move up to its parent. Returns how many
+     * moved.
+     */
+    release(folder: {
+        id: ID;
+        parent?: unknown;
+    }): Promise<{
+        files: number;
+        folders: number;
+    }>;
+    private fresh;
+}
+
 interface StoredFile {
     readonly body: Uint8Array;
     readonly size: number;
@@ -1116,6 +1171,8 @@ declare class EasyCMS<C extends Config = Config> {
     readonly roles: Roles;
     /** Who did what (`audit`, Settings → Audit log). */
     readonly audit: AuditLog;
+    /** Folders of the media library and their permissions (`upload.folders`). */
+    readonly folders: MediaFolders;
     private readonly versions;
     private readonly webhooks;
     private readonly mailer;
@@ -2186,6 +2243,11 @@ interface UploadConfig {
     readonly imageSizes?: readonly ImageSize[];
     /** Lets users upload from a link. Off by default. */
     readonly fromURL?: UploadFromURLConfig;
+    /**
+     * Folders in the media library (`media-folders`; a file is in one folder at most). With
+     * `auth.rbac`, admins can also choose which roles see and change each folder. Off by default.
+     */
+    readonly folders?: boolean;
 }
 interface RoutesConfig {
     /** Where the REST API is served. Default `/api/cms`. */
@@ -2538,6 +2600,7 @@ interface AdminBackups {
 declare function writeBackupFile<C extends Config>(cms: EasyCMS<C>, file: string): Promise<void>;
 
 declare const MEDIA = "media";
+declare const MEDIA_FOLDERS = "media-folders";
 /** Collections Easy CMS uses internally. Not exposed over REST or in the admin UI. */
 declare const INTERNAL_COLLECTIONS: ReadonlySet<string>;
 
@@ -2886,6 +2949,13 @@ interface AdminSchema {
     modules: string[];
     /** Files can be uploaded from links (`upload.fromURL`). */
     uploadFromURL: boolean;
+    /**
+     * The media library has folders (`upload.folders`); `permissions`: this user may choose which
+     * roles use each folder (admins, with `auth.rbac`).
+     */
+    folders?: {
+        permissions: boolean;
+    };
     /** Which saved deliveries the admin can show (webhooks, emails), for users who may see them. */
     deliveries?: {
         webhook: boolean;
@@ -3019,4 +3089,4 @@ declare function validateConfig(config: Config): ConfigIssue[];
 /** The version of `@easy-cms/core`, set when the package is built. */
 declare const VERSION: string;
 
-export { ADMIN_ICONS, API_KEYS, API_KEY_GLOBAL_OPERATIONS, API_KEY_OPERATIONS, type Access, type AccessArgs, type AccessOptions, type AdminAttention, type AdminBackup, type AdminBackups, type AdminBrand, type AdminCollection, type AdminComponent, type AdminComponentRef, type AdminConfig, type AdminDeliveries, type AdminDelivery, type AdminEmail, type AdminEmailDelivery, type AdminField, type AdminGlobal, type AdminIcon, type AdminLocale, type AdminPage, type AdminPageRef, type AdminRole, type AdminRoleChange, type AdminRoleField, type AdminRoleTarget, type AdminRoleView, type AdminRoles, type AdminSchema, type AdminSso, type AdminStatus, type AdminViewAccess, type AdminWebhookDelivery, type AdminWidgetRef, type AfterChangeHook, type AfterDeleteHook, type AfterReadHook, type ApiKeyContext, type ApiKeyGlobalOperation, type ApiKeyOperation, type ApiKeyPermissions, type ArrayField, type AuditChange, type AuditConfig, type AuditEntry, AuditLog, type AuditPage, type AuditVerification, Auth, type AuthConfig, type AuthProvider, type AuthProviderProfile, type AuthProviderRequest, type AuthUser, BUILTIN_COLLECTIONS, type BackupState, type BackupsConfig, type BeforeChangeHook, type BeforeDeleteHook, type BeforeValidateHook, type Block, type BlocksField, type BooleanField, type BuiltinApiKeysCollection, type BuiltinMediaCollection, type BuiltinUsersCollection, type BundleHints, CONFIG_FILE_NAMES, CSRF_COOKIE, CSRF_HEADER, type CliCommand, type CollectionAccess, type CollectionAdmin, type CollectionConfig, type CollectionDocument, type CollectionHooks, type CollectionListAdmin, type CollectionSlug, type Config, ConfigError, type ConfigIssue, type ContainerAdmin, type CopyProgress, type CopyResult, type CreateEasyCMSOptions, type CreateInput, type CreateMigrationResult, type CustomField, type CustomFieldTypes, DEFAULT_ADMIN_PATH, DEFAULT_API_PATH, DEFAULT_DEPTH, DEFAULT_MAX_FILE_SIZE, DEFAULT_MAX_VERSIONS, DEFAULT_PASSWORD_EMAILS, DEFAULT_TOKEN_EXPIRATION, type DashboardWidget, type Database, type DatabaseAdapter, type DatabaseInitArgs, type DatabaseTransfer, type DateField, type DeliveryKind, type DeliveryState, type DepthOptions, type DocumentOf, EXTENSIONS, EasyCMS, EasyCMSError, type EmailAdapter, type EmailCheck, type EmailField, type EmailMessage, type EmailSetting, type Endpoint, type EndpointRequest, FIELD_TYPES, FIELD_TYPE_BASES, type Field, type FieldAccess, type FieldAccessFn, type FieldAdmin, type FieldError, type FieldRule, type FieldType, type FieldTypeBase, type FieldTypeDefinition, type FieldTypeValidateContext, type FieldValidate, type FieldValidateContext, type FieldValue, type FieldsInput, type FieldsValue, type FilterOptions, type FilterOptionsArgs, type FindArgs, type FindOptions, ForbiddenError, type GlobalAccess, type GlobalConfig, type GlobalDocument, type GlobalHooks, type GlobalInput, type GlobalSlug, type GroupField, type ID, INTERNAL_COLLECTIONS, type ImageSize, type InferCollection, type InferGlobal, type JsonField, type Label, type LivePreview, type LoadConfigOptions, type LocalStorageOptions, type LocalizationConfig, type Logger, type LoginArgs, MAX_DEPTH, MEDIA, MIN_PASSWORD_LENGTH, MIN_SECRET_LENGTH, type MediaDocument, type MediaSize, type MigrationInfo, NotFoundError, type NumberField, type Operation, type PaginatedDocs, type PasswordEmail, type PasswordEmailArgs, type PasswordEmailFn, type PasswordLinkOptions, PayloadTooLargeError, type Plugin, type PluginInfo, type PluginTypes, type PreviewTarget, type PreviewURL, QueryError, ROLE_OPERATIONS, type RawDocument, type ReadOptions, type RelationshipField, type ResolvedConfig, type RestHandler, type RestHandlerOptions, type RichTextDocument, type RichTextField, type Role, type RoleOperation, type RolePermissions, Roles, type RoutesConfig, SESSION_COOKIE, SSO_COOKIE, type ScheduledJob, SchemaError, type SchemaMode, type SelectField, type SelectOption, type Session, type SlugField, type SlugOf, type SsoOutcome, type SsoProviderRef, type StorageAdapter, type StoredFile, type TextField, type TextareaField, TooManyRequestsError, type TypedPlugin, UnauthorizedError, type UpdateInput, type UpdateOptions, type UploadConfig, type UploadField, type UploadFromURLConfig, type UserIdentity, VERSION, ValidationError, type Version, type VersionSummary, type VersionsConfig, WEBHOOK_EVENTS, type WebhookConfig, type WebhookEvent, type WebhookPayload, type Where, type WhereOperators, anyone, applyDefaults, applyPlugins, configSignature, consoleEmail, consoleLogger, copyDatabase, createEasyCMS, createRestHandler, createRootEndpointHandler, defineConfig, defineFieldType, definePlugin, fillMissing, findConfigFile, generateSlugs, generateTypes, hasRows, hashPassword, imageDimensions, importConfig, isAdmin, isHasMany, isLoggedIn, keyAllows, loadConfig, localStorage, mergeForUpdate, mimeAllowed, mimeAllowedBy, parseId, populate, readCookie, resolveAdminModule, resolveConfig, rowFields, silentLogger, singularize, slugify, sniffMimeType, validateConfig, validateFields, verifyPassword, writeBackupFile };
+export { ADMIN_ICONS, API_KEYS, API_KEY_GLOBAL_OPERATIONS, API_KEY_OPERATIONS, type Access, type AccessArgs, type AccessOptions, type AdminAttention, type AdminBackup, type AdminBackups, type AdminBrand, type AdminCollection, type AdminComponent, type AdminComponentRef, type AdminConfig, type AdminDeliveries, type AdminDelivery, type AdminEmail, type AdminEmailDelivery, type AdminField, type AdminGlobal, type AdminIcon, type AdminLocale, type AdminPage, type AdminPageRef, type AdminRole, type AdminRoleChange, type AdminRoleField, type AdminRoleTarget, type AdminRoleView, type AdminRoles, type AdminSchema, type AdminSso, type AdminStatus, type AdminViewAccess, type AdminWebhookDelivery, type AdminWidgetRef, type AfterChangeHook, type AfterDeleteHook, type AfterReadHook, type ApiKeyContext, type ApiKeyGlobalOperation, type ApiKeyOperation, type ApiKeyPermissions, type ArrayField, type AuditChange, type AuditConfig, type AuditEntry, AuditLog, type AuditPage, type AuditVerification, Auth, type AuthConfig, type AuthProvider, type AuthProviderProfile, type AuthProviderRequest, type AuthUser, BUILTIN_COLLECTIONS, type BackupState, type BackupsConfig, type BeforeChangeHook, type BeforeDeleteHook, type BeforeValidateHook, type Block, type BlocksField, type BooleanField, type BuiltinApiKeysCollection, type BuiltinMediaCollection, type BuiltinUsersCollection, type BundleHints, CONFIG_FILE_NAMES, CSRF_COOKIE, CSRF_HEADER, type CliCommand, type CollectionAccess, type CollectionAdmin, type CollectionConfig, type CollectionDocument, type CollectionHooks, type CollectionListAdmin, type CollectionSlug, type Config, ConfigError, type ConfigIssue, type ContainerAdmin, type CopyProgress, type CopyResult, type CreateEasyCMSOptions, type CreateInput, type CreateMigrationResult, type CustomField, type CustomFieldTypes, DEFAULT_ADMIN_PATH, DEFAULT_API_PATH, DEFAULT_DEPTH, DEFAULT_MAX_FILE_SIZE, DEFAULT_MAX_VERSIONS, DEFAULT_PASSWORD_EMAILS, DEFAULT_TOKEN_EXPIRATION, type DashboardWidget, type Database, type DatabaseAdapter, type DatabaseInitArgs, type DatabaseTransfer, type DateField, type DeliveryKind, type DeliveryState, type DepthOptions, type DocumentOf, EXTENSIONS, EasyCMS, EasyCMSError, type EmailAdapter, type EmailCheck, type EmailField, type EmailMessage, type EmailSetting, type Endpoint, type EndpointRequest, FIELD_TYPES, FIELD_TYPE_BASES, FOLDER_LEVELS, type Field, type FieldAccess, type FieldAccessFn, type FieldAdmin, type FieldError, type FieldRule, type FieldType, type FieldTypeBase, type FieldTypeDefinition, type FieldTypeValidateContext, type FieldValidate, type FieldValidateContext, type FieldValue, type FieldsInput, type FieldsValue, type FilterOptions, type FilterOptionsArgs, type FindArgs, type FindOptions, type FolderLevel, type FolderPermissions, ForbiddenError, type GlobalAccess, type GlobalConfig, type GlobalDocument, type GlobalHooks, type GlobalInput, type GlobalSlug, type GroupField, type ID, INTERNAL_COLLECTIONS, type ImageSize, type InferCollection, type InferGlobal, type JsonField, type Label, type LivePreview, type LoadConfigOptions, type LocalStorageOptions, type LocalizationConfig, type Logger, type LoginArgs, MAX_DEPTH, MEDIA, MEDIA_FOLDERS, MIN_PASSWORD_LENGTH, MIN_SECRET_LENGTH, type MediaDocument, MediaFolders, type MediaSize, type MigrationInfo, NotFoundError, type NumberField, type Operation, type PaginatedDocs, type PasswordEmail, type PasswordEmailArgs, type PasswordEmailFn, type PasswordLinkOptions, PayloadTooLargeError, type Plugin, type PluginInfo, type PluginTypes, type PreviewTarget, type PreviewURL, QueryError, ROLE_OPERATIONS, type RawDocument, type ReadOptions, type RelationshipField, type ResolvedConfig, type RestHandler, type RestHandlerOptions, type RichTextDocument, type RichTextField, type Role, type RoleOperation, type RolePermissions, Roles, type RoutesConfig, SESSION_COOKIE, SSO_COOKIE, type ScheduledJob, SchemaError, type SchemaMode, type SelectField, type SelectOption, type Session, type SlugField, type SlugOf, type SsoOutcome, type SsoProviderRef, type StorageAdapter, type StoredFile, type TextField, type TextareaField, TooManyRequestsError, type TypedPlugin, UnauthorizedError, type UpdateInput, type UpdateOptions, type UploadConfig, type UploadField, type UploadFromURLConfig, type UserIdentity, VERSION, ValidationError, type Version, type VersionSummary, type VersionsConfig, WEBHOOK_EVENTS, type WebhookConfig, type WebhookEvent, type WebhookPayload, type Where, type WhereOperators, anyone, applyDefaults, applyPlugins, configSignature, consoleEmail, consoleLogger, copyDatabase, createEasyCMS, createRestHandler, createRootEndpointHandler, defineConfig, defineFieldType, definePlugin, fillMissing, findConfigFile, generateSlugs, generateTypes, hasRows, hashPassword, imageDimensions, importConfig, isAdmin, isHasMany, isLoggedIn, keyAllows, loadConfig, localStorage, mergeForUpdate, mimeAllowed, mimeAllowedBy, parseId, populate, readCookie, resolveAdminModule, resolveConfig, rowFields, silentLogger, singularize, slugify, sniffMimeType, validateConfig, validateFields, verifyPassword, writeBackupFile };

package/dist/index.js

@@ -136,6 +136,7 @@ import { createHmac } from "crypto";
 // src/builtins.ts
 var USERS = "users";
 var MEDIA = "media";
+var MEDIA_FOLDERS = "media-folders";
 var SESSIONS = "sessions";
 var LOGIN_ATTEMPTS = "login-attempts";
 var VERSIONS = "document-versions";
@@ -285,15 +286,72 @@ 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 adminField = {
+  read: ({ user }) => user?.role === "admin" && !user.apiKey,
+  update: ({ user }) => user?.role === "admin" && !user.apiKey
+};
+var mediaFoldersCollection = {
+  slug: MEDIA_FOLDERS,
+  labels: {
+    singular: { en: "Folder", th: "\u0E42\u0E1F\u0E25\u0E40\u0E14\u0E2D\u0E23\u0E4C" },
+    plural: { en: "Folders", th: "\u0E42\u0E1F\u0E25\u0E40\u0E14\u0E2D\u0E23\u0E4C" }
+  },
+  icon: "folder",
+  useAsTitle: "name",
+  admin: { list: { tree: "parent", sort: "name" } },
+  access: { read: isLoggedIn, create: isLoggedIn, update: isLoggedIn, delete: isLoggedIn },
+  hooks: {
+    // What the reader may do here (`view`, `edit`, `manage`), for the admin's buttons.
+    afterRead: [
+      async ({ doc, user, cms }) => ({
+        ...doc,
+        level: await cms.folders.level(user, doc.id)
+      })
+    ]
+  },
+  fields: [
+    {
+      name: "name",
+      type: "text",
+      required: true,
+      maxLength: 120,
+      label: { en: "Name", th: "\u0E0A\u0E37\u0E48\u0E2D" }
+    },
+    {
+      name: "parent",
+      type: "relationship",
+      to: MEDIA_FOLDERS,
+      index: true,
+      label: { en: "In folder", th: "\u0E2D\u0E22\u0E39\u0E48\u0E43\u0E19\u0E42\u0E1F\u0E25\u0E40\u0E14\u0E2D\u0E23\u0E4C" }
+    },
+    // `null`: as the parent folder. Otherwise each role's level (`view`, `edit`, `manage`);
+    // roles not listed get nothing.
+    {
+      name: "permissions",
+      type: "json",
+      access: adminField,
+      label: { en: "Permissions", th: "\u0E2A\u0E34\u0E17\u0E18\u0E34\u0E4C\u0E40\u0E02\u0E49\u0E32\u0E16\u0E36\u0E07" }
+    }
+  ]
+};
+var folderField = {
+  name: "folder",
+  type: "relationship",
+  to: MEDIA_FOLDERS,
+  index: true,
+  position: "sidebar",
+  label: { en: "Folder", th: "\u0E42\u0E1F\u0E25\u0E40\u0E14\u0E2D\u0E23\u0E4C" }
+};
 function withMedia(config) {
   const custom = config.collections?.find((c) => c.slug === MEDIA);
+  const folders = config.upload?.folders === true;
   const media = {
     slug: MEDIA,
     labels: { singular: { en: "Media", th: "\u0E2A\u0E37\u0E48\u0E2D" }, plural: { en: "Media", th: "\u0E04\u0E25\u0E31\u0E07\u0E2A\u0E37\u0E48\u0E2D" } },
     icon: "image",
     useAsTitle: "filename",
     ...custom,
-    fields: [...mediaFields(), ...custom?.fields ?? []],
+    fields: [...mediaFields(), ...folders ? [folderField] : [], ...custom?.fields ?? []],
     access: {
       read: anyone,
       create: isLoggedIn,
@@ -331,7 +389,15 @@ function withMedia(config) {
     }
   };
   const others = (config.collections ?? []).filter((c) => c.slug !== MEDIA);
-  return { ...config, collections: [...others.slice(0, 1), media, ...others.slice(1)] };
+  return {
+    ...config,
+    collections: [
+      ...others.slice(0, 1),
+      media,
+      ...folders ? [mediaFoldersCollection] : [],
+      ...others.slice(1)
+    ]
+  };
 }
 var nobody = () => false;
 var internalCollections = [
@@ -3070,7 +3136,7 @@ var rolesCollection = {
   ]
 };
 function governed(slug2) {
-  return !INTERNAL_COLLECTIONS.has(slug2) && slug2 !== API_KEYS;
+  return !INTERNAL_COLLECTIONS.has(slug2) && slug2 !== API_KEYS && slug2 !== MEDIA_FOLDERS;
 }
 function ruleFields(fields) {
   return fields.filter((f) => !f.hidden && f.name !== "createdBy");
@@ -4293,6 +4359,8 @@ function validateUpload(config, add) {
   if (upload.dir !== void 0 && (typeof upload.dir !== "string" || upload.dir.length === 0)) {
     add("upload.dir", "must be a non-empty string");
   }
+  if (upload.folders !== void 0 && typeof upload.folders !== "boolean")
+    add("upload.folders", "must be true or false");
   const fromURL = upload.fromURL;
   if (fromURL === void 0) return;
   if (typeof fromURL !== "object" || fromURL === null) {
@@ -4837,6 +4905,7 @@ async function resolveConfig(input) {
       maxFileSize: config.upload?.maxFileSize ?? DEFAULT_MAX_FILE_SIZE,
       mimeTypes: config.upload?.mimeTypes ?? ["image/*", "application/pdf"],
       imageSizes: config.upload?.imageSizes ?? [],
+      folders: config.upload?.folders === true,
       ...config.upload?.storage ? { storage: config.upload.storage } : {},
       ...config.upload?.fromURL ? { fromURL: config.upload.fromURL } : {}
     },
@@ -5144,6 +5213,170 @@ function storageKey(originalName, type, random2) {
   return `${base}-${random2}.${EXTENSIONS[type] ?? "bin"}`;
 }
 
+// src/media-folders.ts
+var FOLDER_LEVELS = ["view", "edit", "manage"];
+var RANK = { none: 0, view: 1, edit: 2, manage: 3 };
+var TTL2 = 1e4;
+function needed(collection2, operation) {
+  if (operation === "read") return "view";
+  return collection2 === MEDIA ? "edit" : "manage";
+}
+var MediaFolders = class {
+  constructor(config, db, roles) {
+    this.db = db;
+    this.roles = roles;
+    this.enabled = config.upload.folders;
+  }
+  db;
+  roles;
+  enabled;
+  cache;
+  /** Whether folder permissions apply to this user. */
+  applies(user) {
+    return this.enabled && this.roles.enabled && !!user && user.role !== "admin" && !user.apiKey;
+  }
+  /** Forgets cached folders, after one changed. */
+  invalidate() {
+    this.cache = void 0;
+  }
+  async rows() {
+    if (this.cache && Date.now() - this.cache.at < TTL2) return this.cache.rows;
+    const found = await this.db.find({ collection: MEDIA_FOLDERS, sort: [], limit: 0, page: 1 });
+    const rows = /* @__PURE__ */ new Map();
+    for (const doc of found.docs) {
+      const permissions = doc.permissions;
+      rows.set(String(doc.id), {
+        id: doc.id,
+        parent: doc.parent ?? null,
+        name: String(doc.name ?? ""),
+        permissions: permissions && typeof permissions === "object" && !Array.isArray(permissions) ? permissions : null
+      });
+    }
+    this.cache = { at: Date.now(), rows };
+    return rows;
+  }
+  /** A role's level in a folder (`null`: the top level): the nearest permissions up the tree. */
+  levelIn(rows, role, id) {
+    const seen = /* @__PURE__ */ new Set();
+    let current = id === null ? void 0 : rows.get(String(id));
+    while (current && !seen.has(String(current.id))) {
+      seen.add(String(current.id));
+      if (current.permissions) {
+        const level = current.permissions[role];
+        return level && level in RANK ? level : "none";
+      }
+      current = current.parent === null ? void 0 : rows.get(String(current.parent));
+    }
+    return "manage";
+  }
+  /** The user's level in a folder (`null`: the top level). */
+  async level(user, id) {
+    if (!this.applies(user)) return "manage";
+    return this.levelIn(await this.rows(), user.role, id);
+  }
+  /**
+   * The constraint folder permissions add to an operation on files or folders, or `true` when
+   * 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 (operation === "create") return true;
+    const need = RANK[needed(collection2, operation)];
+    const rows = await this.rows();
+    const allowed2 = [];
+    let all = true;
+    for (const row of rows.values()) {
+      if (RANK[this.levelIn(rows, user.role, row.id)] >= need) allowed2.push(row.id);
+      else all = false;
+    }
+    if (all) return true;
+    if (collection2 === MEDIA_FOLDERS) return { id: { in: allowed2 } };
+    const outside = { folder: { exists: false } };
+    return allowed2.length === 0 ? outside : { or: [{ folder: { in: allowed2 } }, outside] };
+  }
+  /** Refuses putting a file (`media`) or a subfolder in a folder the user may not. */
+  async checkTarget(user, collection2, folder) {
+    if (!this.applies(user)) return;
+    const need = collection2 === MEDIA ? "edit" : "manage";
+    if (RANK[await this.level(user, folder)] < RANK[need])
+      throw new ForbiddenError("You may not add to this folder");
+  }
+  /**
+   * Checks a folder before it is saved: a name unique among its siblings (ignoring case), a
+   * parent that is not itself or inside it, and permissions for roles that exist.
+   */
+  async validate(data, self) {
+    const rows = await this.fresh();
+    const name = typeof data.name === "string" ? data.name.trim() : "";
+    const parent = data.parent ?? null;
+    const errors = [];
+    if (parent !== null && self !== void 0) {
+      let current = rows.get(String(parent));
+      const seen = /* @__PURE__ */ new Set();
+      while (current && !seen.has(String(current.id))) {
+        if (String(current.id) === String(self)) {
+          errors.push({ field: "parent", message: "cannot be the folder itself or inside it" });
+          break;
+        }
+        seen.add(String(current.id));
+        current = current.parent === null ? void 0 : rows.get(String(current.parent));
+      }
+    }
+    const taken = [...rows.values()].some(
+      (row) => String(row.id) !== String(self) && String(row.parent) === String(parent) && row.name.trim().toLocaleLowerCase() === name.toLocaleLowerCase()
+    );
+    if (name && taken) errors.push({ field: "name", message: "is already used in this folder" });
+    const permissions = data.permissions;
+    if (permissions !== null && permissions !== void 0) {
+      const roles = new Set((await this.roles.options()).map((r) => r.key));
+      if (typeof permissions !== "object" || Array.isArray(permissions))
+        errors.push({ field: "permissions", message: "must be null or roles with their levels" });
+      else
+        for (const [role, level] of Object.entries(permissions)) {
+          if (!roles.has(role))
+            errors.push({ field: "permissions", message: `"${role}" is not a role` });
+          else if (!FOLDER_LEVELS.includes(level))
+            errors.push({
+              field: "permissions",
+              message: `"${role}" must be one of ${FOLDER_LEVELS.join(", ")}`
+            });
+        }
+    }
+    if (errors.length > 0) throw new ValidationError(MEDIA_FOLDERS, errors);
+  }
+  /**
+   * Before a folder is deleted: its files and subfolders move up to its parent. Returns how many
+   * moved.
+   */
+  async release(folder) {
+    const parent = folder.parent ?? null;
+    const moved = { files: 0, folders: 0 };
+    for (const [collection2, field, key2] of [
+      [MEDIA, "folder", "files"],
+      [MEDIA_FOLDERS, "parent", "folders"]
+    ]) {
+      const found = await this.db.find({
+        collection: collection2,
+        where: { [field]: { equals: folder.id } },
+        sort: [],
+        limit: 0,
+        page: 1
+      });
+      for (const doc of found.docs) {
+        const { id, ...rest } = doc;
+        await this.db.update({ collection: collection2, id, data: { ...rest, [field]: parent } });
+        moved[key2]++;
+      }
+    }
+    this.invalidate();
+    return moved;
+  }
+  async fresh() {
+    this.invalidate();
+    return this.rows();
+  }
+};
+
 // src/populate.ts
 var DEFAULT_DEPTH = 1;
 var MAX_DEPTH = 3;
@@ -5461,6 +5694,8 @@ var EasyCMS = class {
   roles;
   /** Who did what (`audit`, Settings → Audit log). */
   audit;
+  /** Folders of the media library and their permissions (`upload.folders`). */
+  folders;
   versions;
   webhooks;
   mailer;
@@ -5478,6 +5713,7 @@ var EasyCMS = class {
       (entry) => this.audit.record(entry)
     );
     this.audit = new AuditLog(this);
+    this.folders = new MediaFolders(config, db, this.roles);
     this.webhooks = new Webhooks(
       config.webhooks ?? [],
       logger,
@@ -5572,6 +5808,7 @@ var EasyCMS = class {
       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));
     }
     const { maxFileSize, mimeTypes, imageSizes } = this.config.upload;
     if (file.data.byteLength > maxFileSize) {
@@ -5903,6 +6140,11 @@ var EasyCMS = class {
     const existing = parsed === void 0 ? null : await this.db.findById({ collection: collection2, id: parsed });
     if (!existing || parsed === void 0) throw new NotFoundError(collection2, id);
     await this.checkDocumentAccess(config, "update", guard, parsed, raw);
+    if (guard.enforce && inFolders(this.config, collection2)) {
+      const key2 = collection2 === MEDIA ? "folder" : "parent";
+      if (Object.hasOwn(raw, key2) && String(raw[key2] ?? null) !== String(existing[key2] ?? null))
+        await this.folders.checkTarget(guard.user, collection2, folderOf(collection2, raw));
+    }
     if (config.drafts && (mode === "unpublish" || raw.status === "published"))
       await this.checkDocumentGrant(guard, collection2, "publish", parsed);
     const [drafted] = await this.withDrafts(config, [existing]);
@@ -5968,11 +6210,13 @@ 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);
     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 (!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, {
@@ -6015,7 +6259,9 @@ var EasyCMS = class {
       await this.auth.revokeSessions(parsed);
       await this.auth.sso.forget(parsed);
     }
+    if (collection2 === MEDIA_FOLDERS) await this.folders.release(existing);
     await this.db.delete({ collection: collection2, id: parsed });
+    if (collection2 === MEDIA_FOLDERS) this.folders.invalidate();
     if (versionLimit(config)) await this.versions.deleteAll(collectionParent(collection2), parsed);
     if (config.schedule) {
       for (const job of await this.pendingJobs(collection2, parsed))
@@ -6585,11 +6831,16 @@ var EasyCMS = class {
   async checkGrant(guard, target, operation) {
     if (!guard.enforce) return true;
     const name = "collection" in target ? target.collection : target.global;
-    if (!keyAllows(guard.user, target, operation))
+    const folders = "collection" in target && target.collection === MEDIA_FOLDERS;
+    const granted = folders ? { collection: MEDIA } : target;
+    if (!keyAllows(guard.user, granted, operation))
       throw new ForbiddenError(`This API key may not ${operation} "${name}"`);
-    const role = await this.roles.allows(guard.user, target, operation);
+    let role = await this.roles.allows(guard.user, granted, operation);
     if (role === false) throw deny(guard.user);
-    return role;
+    if (folders && role !== true && guard.user) role = { createdBy: { equals: guard.user.id } };
+    const inFolder = await this.folders.where(guard.user, name, operation);
+    if (inFolder === true) return role;
+    return role === true ? inFolder : { and: [role, inFolder] };
   }
   /** The query constraint read access adds, or `undefined` when there is none. Throws when denied. */
   async readWhere(config, guard, where) {
@@ -6717,6 +6968,8 @@ var EasyCMS = class {
       if (typeof allowed2 === "object")
         throw new QueryError(`create access of "${collection2}" must return a boolean`);
       if (!allowed2) throw deny(guard.user);
+      if (inFolders(this.config, collection2))
+        await this.folders.checkTarget(guard.user, collection2, folderOf(collection2, raw));
     }
     const { input, password } = splitPassword(config, raw);
     const filtered = await filterInput(
@@ -6752,11 +7005,13 @@ var EasyCMS = class {
       prepared
     );
     if (password !== void 0) prepared.passwordHash = await hashPassword(password);
+    if (collection2 === MEDIA_FOLDERS) await this.folders.validate(prepared, void 0);
     const now = (/* @__PURE__ */ new Date()).toISOString();
     const doc = await this.db.create({
       collection: collection2,
       data: { ...prepared, createdAt: now, updatedAt: now }
     });
+    if (collection2 === MEDIA_FOLDERS) this.folders.invalidate();
     await this.saveVersion(config, collectionParent(collection2), doc.id, doc, guard);
     await this.notify(config.hooks?.afterChange, "afterChange", collection2, {
       ...base,
@@ -6845,7 +7100,9 @@ var EasyCMS = class {
   async audited(config, event, doc, previous, guard, mode = "save") {
     if (!this.audit.enabled) return;
     let action = event;
-    if (event === "update" || event === "draft") {
+    if (config.slug === MEDIA_FOLDERS && event === "update" && JSON.stringify(doc.permissions ?? null) !== JSON.stringify(previous?.permissions ?? null))
+      action = "folder.permissions";
+    else if (event === "update" || event === "draft") {
       const was = previous?.status;
       if (mode === "restore") action = "restore";
       else if (config.drafts && doc.status === "published" && was !== "published")
@@ -7154,6 +7411,13 @@ function asObject(data, name) {
   }
   return data;
 }
+function inFolders(config, collection2) {
+  return config.upload.folders && (collection2 === MEDIA || collection2 === MEDIA_FOLDERS);
+}
+function folderOf(collection2, data) {
+  const value = data[collection2 === MEDIA ? "folder" : "parent"];
+  return value === void 0 || value === "" ? null : value;
+}
 
 // src/rest/admin-modules.ts
 import { createHash as createHash3 } from "crypto";
@@ -7578,6 +7842,7 @@ async function adminSchema(cms, user, origin) {
     globals: await Promise.all(cms.config.globals.map((g) => global(cms, g, user, localized))),
     modules: adminModuleUrls(cms),
     uploadFromURL: cms.config.upload.fromURL !== void 0,
+    ...cms.folders.enabled ? { folders: { permissions: admin && cms.roles.enabled } } : {},
     views,
     rbac: cms.roles.enabled,
     providers: cms.auth.sso.providers(),
@@ -7626,7 +7891,7 @@ async function widgets(cms, user) {
 }
 
 // src/version.ts
-var VERSION = true ? "0.37.2" : "0.0.0-dev";
+var VERSION = true ? "0.38.0" : "0.0.0-dev";
 
 // src/rest/admin-status.ts
 var DAY2 = 864e5;
@@ -8974,12 +9239,15 @@ export {
   EasyCMSError,
   FIELD_TYPES,
   FIELD_TYPE_BASES,
+  FOLDER_LEVELS,
   ForbiddenError,
   INTERNAL_COLLECTIONS,
   MAX_DEPTH,
   MEDIA,
+  MEDIA_FOLDERS,
   MIN_PASSWORD_LENGTH,
   MIN_SECRET_LENGTH,
+  MediaFolders,
   NotFoundError,
   PayloadTooLargeError,
   QueryError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@easy-cms/core",
-  "version": "0.37.2",
+  "version": "0.38.0",
   "description": "Embedded, code-first headless CMS for Nuxt and Next.js",
   "license": "MIT",
   "type": "module",