@easy-cms/core 0.39.0 → 0.40.0

package/dist/index.d.ts

@@ -538,6 +538,40 @@ interface BuiltinApiKeysCollection {
         }
     ];
 }
+/** The built-in media folders (`upload.folders: true`). */
+interface BuiltinMediaFoldersCollection {
+    readonly slug: 'media-folders';
+    readonly fields: readonly [
+        {
+            readonly name: 'name';
+            readonly type: 'text';
+            readonly required: true;
+        },
+        {
+            readonly name: 'parent';
+            readonly type: 'relationship';
+            readonly to: 'media-folders';
+        },
+        {
+            readonly name: 'key';
+            readonly type: 'text';
+        },
+        {
+            readonly name: 'private';
+            readonly type: 'boolean';
+        },
+        {
+            readonly name: 'permissions';
+            readonly type: 'json';
+        }
+    ];
+}
+/** `media-folders` when the config turns folders on. */
+type FoldersOf<C extends Config> = C extends {
+    readonly upload: {
+        readonly folders: true;
+    };
+} ? BuiltinMediaFoldersCollection : never;
 /** `api-keys` when the config turns API keys on. */
 type ApiKeysOf<C extends Config> = C extends {
     readonly apiKeys: true;
@@ -565,7 +599,7 @@ type WithPluginFields<C extends Config, T extends {
     readonly fields: readonly (T['fields'][number] | PluginFields<C, T['slug'], Key>)[];
 };
 /** Every collection of a config, including the built-in ones and those plugins add. */
-type AllCollections<C extends Config> = NonNullable<C['collections']>[number] | BuiltinUsersCollection | BuiltinMediaCollection | ApiKeysOf<C> | PluginCollections<C>;
+type AllCollections<C extends Config> = NonNullable<C['collections']>[number] | BuiltinUsersCollection | BuiltinMediaCollection | ApiKeysOf<C> | FoldersOf<C> | PluginCollections<C>;
 /** The built-in media collection; its documents are typed as `MediaDocument`. */
 interface BuiltinMediaCollection {
     readonly slug: 'media';
@@ -596,7 +630,11 @@ interface MediaDocument {
     width?: number | null;
     height?: number | null;
     alt?: string | null;
-    /** Public URL of the file. */
+    /** Its media folder (`upload.folders`), when it is in one. */
+    folder?: ID | null;
+    /** In a private folder: `url` needs a signed-in user who may see it, or `cms.signedMediaURL()`. */
+    private?: boolean | null;
+    /** URL of the file: public, or for private files the API's, which checks who asks. */
     url: string;
     /** Resized copies, when `upload.imageSizes` is set and sharp is installed. */
     sizes: Record<string, MediaSize>;
@@ -703,7 +741,7 @@ type InferGlobal<T extends FieldsOwner, C extends Config = Config> = Simplify<
 } ? {
     status: 'draft' | 'published';
 } : unknown) & FieldsValue<T['fields'], C>>;
-type CollectionSlug<C extends Config> = NonNullable<C['collections']>[number]['slug'] | 'users' | 'media' | ApiKeysOf<C>['slug'] | PluginCollections<C>['slug'];
+type CollectionSlug<C extends Config> = NonNullable<C['collections']>[number]['slug'] | 'users' | 'media' | ApiKeysOf<C>['slug'] | FoldersOf<C>['slug'] | PluginCollections<C>['slug'];
 type GlobalSlug<C extends Config> = NonNullable<C['globals']>[number]['slug'];
 /** Document type of a collection, e.g. `CollectionDocument<typeof config, 'posts'>`. */
 type CollectionDocument<C extends Config, S extends CollectionSlug<C>> = S extends 'media' ? MediaDocument : InferCollection<CollectionBySlug<C, S>, C>;
@@ -998,6 +1036,24 @@ declare class MediaFolders {
     private rows;
     /** A role's level in a folder (`null`: the top level): the nearest permissions up the tree. */
     private levelIn;
+    /** Whether files in a folder (`null`: the top level) are private: it or a folder above is. */
+    private privateIn;
+    /** Whether files put in this folder are private. */
+    isPrivate(id: ID | null): Promise<boolean>;
+    /** The folder and every folder inside it. */
+    private within;
+    /** Folders whose privacy follows this one: it and those inside, with their privacy now. */
+    subtree(id: ID): Promise<{
+        id: ID;
+        private: boolean;
+    }[]>;
+    /**
+     * The folder with this key (`folder: 'banners'` on upload fields), made at the top level when
+     * there is none yet.
+     */
+    keyed(key: string): Promise<ID>;
+    /** Whether a file in `folder` is in the folder with this key, or below it. */
+    inKeyed(key: string, folder: ID | null): Promise<boolean>;
     /** The user's level in a folder (`null`: the top level). */
     level(user: AuthUser | null, id: ID | null): Promise<FolderLevel | 'none'>;
     /**
@@ -1165,6 +1221,11 @@ declare class EasyCMS<C extends Config = Config> {
     readonly auth: Auth;
     /** Where uploaded files are stored. */
     readonly storage: StorageAdapter;
+    /**
+     * 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.
+     */
+    readonly privateStorage: StorageAdapter | null;
     /** Project root: relative paths in the config (e.g. `admin.modules`) start here. */
     readonly cwd: string;
     /** Roles and their permissions (`auth.rbac`, Settings → Roles). */
@@ -1176,7 +1237,7 @@ declare class EasyCMS<C extends Config = Config> {
     private readonly versions;
     private readonly webhooks;
     private readonly mailer;
-    constructor(config: ResolvedConfig, db: Database, logger?: Logger, storage?: StorageAdapter, cwd?: string);
+    constructor(config: ResolvedConfig, db: Database, logger?: Logger, storage?: StorageAdapter, cwd?: string, privateStorage?: StorageAdapter | null);
     find<S extends Slug<C>>(collection: S, options?: FindOptions): Promise<PaginatedDocs<Doc<C, S>>>;
     findById<S extends Slug<C>>(collection: S, id: ID, options?: ReadOptions): Promise<Doc<C, S> | null>;
     count<S extends Slug<C>>(collection: S, options?: {
@@ -1214,6 +1275,43 @@ declare class EasyCMS<C extends Config = Config> {
     }>;
     /** Public URL of a stored file. */
     mediaURL(key: string): string;
+    /**
+     * 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: {
+        filename?: unknown;
+        private?: unknown;
+        sizes?: unknown;
+    }, options?: {
+        expiresIn?: number | string;
+        size?: string;
+    }): string;
+    /** Whether a signed link to a private file is genuine and not expired. */
+    verifyMediaSignature(key: string, expires: string | null, signature: string | null): boolean;
+    private mediaSignature;
+    /**
+     * 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.
+     */
+    mediaUsage(ids: readonly ID[]): Promise<number>;
+    /** The storage for public files, or for private ones. */
+    storageFor(isPrivate: boolean): StorageAdapter;
+    /**
+     * 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.
+     */
+    private relocate;
+    /** A folder's name, parent and permissions; private only with somewhere private to keep files. */
+    private validateFolder;
+    /** After a folder became private or public (or moved): its files follow, in every subfolder. */
+    private settlePrivacy;
+    /** Files at the top level are public. */
+    private settleTopLevel;
+    private settleFiles;
     update<S extends Slug<C>>(collection: S, id: ID, data: Update<C, S>, options?: UpdateOptions): Promise<Doc<C, S>>;
     /**
      * Takes a document off the site: its status becomes `draft`. With versions and drafts, a plain
@@ -1600,6 +1698,14 @@ interface UploadField extends BaseField<'upload', never> {
      * offers only these, and saving refuses others.
      */
     readonly mimeTypes?: readonly string[];
+    /**
+     * With `upload.folders`: the `key` of the media folder this field's files go in, e.g.
+     * `'banners'`. Its picker opens there and its uploads land there; the folder is made when it
+     * is first needed.
+     */
+    readonly folder?: string;
+    /** With `folder`: only files in that folder (and its subfolders) may be chosen. */
+    readonly folderOnly?: boolean;
 }
 interface FilterOptionsArgs {
     /** The document being edited; `undefined` while it is being created. */
@@ -2248,6 +2354,13 @@ interface UploadConfig {
      * `auth.rbac`, admins can also choose which roles see and change each folder. Off by default.
      */
     readonly folders?: boolean;
+    /**
+     * Where files in private folders are kept: never served publicly, only through the API to
+     * users who may see them or with `cms.signedMediaURL()`. Default: `storage`, when it has no
+     * public URL (the local disk, Netlify Blobs); a storage with public URLs (S3 with `publicUrl`,
+     * a public Vercel Blob store) needs one, e.g. `vercelBlobStorage({ access: 'private' })`.
+     */
+    readonly privateStorage?: StorageAdapter;
 }
 interface RoutesConfig {
     /** Where the REST API is served. Default `/api/cms`. */
@@ -2507,7 +2620,7 @@ interface ResolvedConfig extends Omit<Config, 'cors' | 'localization' | 'routes'
     readonly localization: Required<LocalizationConfig> | null;
     readonly routes: Required<RoutesConfig>;
     readonly admin: Required<AdminConfig>;
-    readonly upload: Required<Omit<UploadConfig, 'storage' | 'fromURL'>> & Pick<UploadConfig, 'storage' | 'fromURL'>;
+    readonly upload: Required<Omit<UploadConfig, 'storage' | 'fromURL' | 'privateStorage'>> & Pick<UploadConfig, 'storage' | 'fromURL' | 'privateStorage'>;
     readonly auth: Required<AuthConfig>;
     /** `false` without an audit log. */
     readonly audit: Required<AuditConfig> | false;
@@ -2536,6 +2649,11 @@ type ApiKeyGlobalOperation = (typeof API_KEY_GLOBAL_OPERATIONS)[number];
 interface ApiKeyPermissions {
     readonly collections?: Readonly<Record<string, readonly ApiKeyOperation[]>>;
     readonly globals?: Readonly<Record<string, readonly ApiKeyGlobalOperation[]>>;
+    /**
+     * With `upload.folders`: the media folders (ids) the key may use, with their subfolders. Empty
+     * or missing: every folder.
+     */
+    readonly folders?: readonly (string | number)[];
 }
 /** Set on `AuthUser.apiKey` when a request authenticated with an API key. */
 interface ApiKeyContext {
@@ -2662,6 +2780,8 @@ interface Reference {
     readonly filterOptions?: FilterOptions;
     /** The upload's `mimeTypes`, checked when saving. */
     readonly mimeTypes?: readonly string[];
+    /** The upload's `folder` with `folderOnly`: the file must be in it, checked when saving. */
+    readonly folderOnly?: string;
 }
 interface ValidateOptions {
     readonly operation: 'create' | 'update';
@@ -2845,6 +2965,11 @@ interface AdminField {
     to?: string;
     /** An upload's allowed file types, e.g. `image/*`. */
     mimeTypes?: string[];
+    /** An upload's media folder (`folder`): where its picker opens; `only`: nowhere else. */
+    folder?: {
+        id: ID;
+        only: boolean;
+    };
     /** A relationship with `filterOptions`: the picker asks the server which documents fit. */
     filtered?: boolean;
     from?: string;
@@ -2971,6 +3096,7 @@ interface AdminSchema {
      */
     folders?: {
         permissions: boolean;
+        private: boolean;
     };
     /** Which saved deliveries the admin can show (webhooks, emails), for users who may see them. */
     deliveries?: {
@@ -3105,4 +3231,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, 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, MIME_GROUPS, 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, expandMimeTypes, 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 BuiltinMediaFoldersCollection, 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, MIME_GROUPS, 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, expandMimeTypes, 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

@@ -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 ?? []
@@ -1067,6 +1100,17 @@ function storageKey(originalName, type, random2) {
   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 +2850,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 +4548,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 +4583,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 +4611,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 +4860,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 +5146,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 +5250,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 +5363,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 +5403,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 +5425,83 @@ 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 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 +5512,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 +5537,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 +5908,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 +5937,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 +5953,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(
@@ -5895,17 +6081,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,7 +6116,7 @@ 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;
     }
@@ -5995,9 +6191,137 @@ 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"
+        }
+      ]);
+  }
+  /** 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 +6603,26 @@ 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);
+    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, {
@@ -6330,7 +6667,12 @@ var EasyCMS = class {
     }
     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 (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 +7416,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 +7576,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 +7594,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 +7763,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 +7837,15 @@ 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;
+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 +8094,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 +8147,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 +8162,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 +8186,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 +8236,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 +8281,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 +8334,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.40.0" : "0.0.0-dev";
 
 // src/rest/admin-status.ts
 var DAY2 = 864e5;
@@ -8533,6 +8908,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 +9060,10 @@ 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 === void 0 && method === "POST") {
     if ((ctx.request.headers.get("content-type") ?? "").toLowerCase().startsWith("application/json")) {
       const { url, ...data2 } = await readJson(ctx.request);
@@ -8978,6 +9363,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")) {

package/package.json

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