@easy-cms/core 0.42.0 → 0.44.0

package/dist/index.d.ts

@@ -6,8 +6,19 @@ interface AuthUser {
     readonly id: ID;
     readonly email: string;
     readonly role: Role;
+    /**
+     * Set by `onRequest` (e.g. a multi-tenant plugin) when `role` holds only in part of the site,
+     * such as one tenant: an `admin` there administers that part, not the whole system (Settings,
+     * backups, roles, other users' API keys).
+     */
+    readonly scoped?: boolean;
     readonly [field: string]: unknown;
 }
+/**
+ * An admin of the whole system: role `admin`, signed in (not an API key), and not an admin of a
+ * part only (`scoped`).
+ */
+declare const isSystemAdmin: (user: AuthUser | null | undefined) => boolean;
 interface WhereOperators {
     readonly equals?: unknown;
     readonly not_equals?: unknown;
@@ -26,9 +37,16 @@ type Where = {
 } & {
     readonly [field: string]: WhereOperators | readonly Where[] | undefined;
 };
+/**
+ * What a request is about besides its user, e.g. the site or tenant it works in: set by
+ * `onRequest` in the config (usually a plugin's), or passed to the Local API as `context`.
+ */
+type RequestContext = Readonly<Record<string, unknown>>;
 interface AccessArgs {
     /** `null` when the request is not logged in. */
     readonly user: AuthUser | null;
+    /** The request's context (`onRequest`), `{}` when there is none. */
+    readonly context?: RequestContext;
     readonly id?: ID;
     readonly data?: Readonly<Record<string, unknown>>;
 }
@@ -1191,6 +1209,11 @@ interface AccessOptions {
     readonly overrideAccess?: boolean;
     /** The user to check access for. `null` = not logged in. */
     readonly user?: AuthUser | null;
+    /**
+     * What the call is about besides its user, e.g. the tenant (see `onRequest`): given to access
+     * functions, hooks and `filterOptions`.
+     */
+    readonly context?: RequestContext;
 }
 interface DepthOptions extends AccessOptions {
     /** How many levels of relationships to populate. Default 1, maximum 3. */
@@ -1278,6 +1301,20 @@ declare class EasyCMS<C extends Config = Config> {
     private readonly webhooks;
     private readonly mailer;
     constructor(config: ResolvedConfig, db: Database, logger?: Logger, storage?: StorageAdapter, cwd?: string, privateStorage?: StorageAdapter | null);
+    /**
+     * The user and context of a request, as the REST API works them out: its session cookie or
+     * Bearer token, then `onRequest`. For framework routes and server code that act for a visitor;
+     * pass both to the Local API with `overrideAccess: false`.
+     */
+    forRequest(request: Request | Headers): Promise<{
+        user: AuthUser | null;
+        context: RequestContext;
+    }>;
+    /** @internal `onRequest` of the config, for a request whose user is known. */
+    applyOnRequest(headers: Headers, url: URL | undefined, user: AuthUser | null): Promise<{
+        user: AuthUser | null;
+        context: RequestContext;
+    }>;
     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?: {
@@ -1442,6 +1479,16 @@ declare class EasyCMS<C extends Config = Config> {
         transferTo?: ID | null;
     }): Promise<Doc<C, S>>;
     findGlobal<S extends GSlug<C>>(slug: S, options?: ReadOptions): Promise<GDoc<C, S>>;
+    /** A global as stored under `key` (see `globalKey`); empty when there is no key. */
+    private readGlobal;
+    /**
+     * Where a global is kept: its slug, or `<slug>@<scope>` for globals with `scope` (e.g. one per
+     * tenant). `null` when the call has no scope: reads give the global empty. `scope` is given by
+     * scheduled jobs, which have no request.
+     */
+    private globalKey;
+    /** `globalKey` for changes, which need a scope. */
+    private writeKey;
     updateGlobal<S extends GSlug<C>>(slug: S, data: GInput<C, S>, options?: DepthOptions): Promise<GDoc<C, S>>;
     /** Takes a global off the site (`status: 'draft'`). See `unpublish`. */
     unpublishGlobal<S extends GSlug<C>>(slug: S, options?: DepthOptions): Promise<GDoc<C, S>>;
@@ -1463,7 +1510,7 @@ declare class EasyCMS<C extends Config = Config> {
      * What `user` may do with one document. Resolves `where`-style access
      * against the document, so the admin UI can hide actions precisely.
      */
-    documentPermissions(collection: Slug<C>, id: ID, user: AuthUser | null): Promise<{
+    documentPermissions(collection: Slug<C>, id: ID, user: AuthUser | null, context?: RequestContext): Promise<{
         update: boolean;
         delete: boolean;
     }>;
@@ -1693,6 +1740,12 @@ interface BaseField<TType extends string, TValue> {
     readonly label?: Label;
     readonly required?: boolean;
     readonly unique?: boolean;
+    /**
+     * With `unique` (or on a slug field): the name of a sibling field (e.g. `parent` or `tenant`)
+     * whose documents only need to differ among themselves, so `/about/team` and `/careers/team`
+     * can both be `team`. A single, unlocalized relationship, select, text or number field.
+     */
+    readonly uniqueWithin?: string;
     readonly index?: boolean;
     readonly defaultValue?: TValue;
     readonly validate?: FieldValidate<TValue>;
@@ -1743,11 +1796,6 @@ interface SelectField extends BaseField<'select', string | readonly string[]> {
 interface SlugField extends BaseField<'slug', string> {
     /** Name of a sibling `text` field to generate the slug from. */
     readonly from?: string;
-    /**
-     * Name of a sibling field (e.g. `parent`): slugs then only need to differ among documents
-     * with the same value there, so `/about/team` and `/careers/team` can both be `team`.
-     */
-    readonly uniqueWithin?: string;
 }
 /** Tiptap / ProseMirror JSON document. */
 interface RichTextDocument {
@@ -1783,6 +1831,8 @@ interface FilterOptionsArgs {
     readonly id: ID | undefined;
     readonly user: AuthUser | null;
     readonly cms: EasyCMS;
+    /** The request's context (`onRequest`), `{}` when there is none. */
+    readonly context: RequestContext;
 }
 /**
  * Which documents a relationship may point to: a `where` on the target collection, or `true`
@@ -2170,6 +2220,8 @@ interface HookBase {
     readonly cms: EasyCMS;
     /** Slug of the collection or global. */
     readonly slug: string;
+    /** The request's context (`onRequest`, or `context` of a Local API call); `{}` when there is none. */
+    readonly context: RequestContext;
 }
 type BeforeValidateHook = (args: HookBase & {
     data: Data$1;
@@ -2307,6 +2359,15 @@ interface GlobalConfig {
     readonly preview?: PreviewURL;
     readonly access?: GlobalAccess;
     readonly hooks?: GlobalHooks;
+    /**
+     * One value per scope, e.g. per tenant (usually set by a plugin): the scope of a call, from its
+     * context (`onRequest`). A string keeps a value of its own; `undefined` the shared value; `null`
+     * means the call has none, so reads give the global empty and changes are refused.
+     */
+    readonly scope?: (args: {
+        readonly context: RequestContext;
+        readonly user: AuthUser | null;
+    }) => string | null | undefined;
     /** Custom admin components. */
     readonly admin?: ContainerAdmin;
 }
@@ -2382,6 +2443,23 @@ interface AdminConfig {
     readonly pages?: readonly AdminPage[];
     /** Panels on the dashboard, after the built-in ones. */
     readonly dashboard?: readonly DashboardWidget[];
+    /**
+     * A choice at the top of the menu that applies to everything in the admin, e.g. the tenant
+     * (usually set by a plugin). The choice is kept in a cookie, which every request of the admin
+     * sends; `onRequest` reads it.
+     */
+    readonly switcher?: AdminSwitcher | null;
+}
+/** See `AdminConfig.switcher`. */
+interface AdminSwitcher {
+    /** Cookie that keeps the choice, e.g. `ecms-tenant`. */
+    readonly cookie: string;
+    readonly label: Label;
+    /**
+     * Path under the API that lists the choices for the logged-in user:
+     * `{ options: [{ value, label }], all?: Label }`, with `all` to offer "all of them" (value `*`).
+     */
+    readonly options: string;
 }
 interface ImageSize {
     /** Key in `media.sizes`, e.g. `thumbnail`. */
@@ -2497,6 +2575,24 @@ interface AuthConfig {
         readonly passwordChanged?: PasswordEmailFn;
     };
 }
+/** What `onRequest` receives. */
+interface OnRequestArgs {
+    readonly headers: Headers;
+    /** The request's URL; `undefined` when only headers are known (`cms.forRequest(headers)`). */
+    readonly url: URL | undefined;
+    /** The user of the session or API key, before `onRequest` changes it; `null` when anonymous. */
+    readonly user: AuthUser | null;
+    readonly cms: EasyCMS;
+}
+/**
+ * Runs on each API request (REST, plugin endpoints, `cms.forRequest`) after the user is known:
+ * returns the request's `context` (e.g. the tenant it works in, from a header) and may change the
+ * user (e.g. their role in that tenant, `scoped`). Plugins that set it call the one before.
+ */
+type OnRequest = (args: OnRequestArgs) => MaybePromise<{
+    readonly user?: AuthUser | null;
+    readonly context?: RequestContext;
+} | undefined>;
 /** What an endpoint's handler receives. */
 interface EndpointRequest {
     readonly request: Request;
@@ -2505,6 +2601,8 @@ interface EndpointRequest {
     readonly params: Readonly<Record<string, string>>;
     /** The logged-in user (session cookie or Bearer token), or `null`. */
     readonly user: AuthUser | null;
+    /** The request's context (`onRequest`): pass it to the Local API with `user`. */
+    readonly context: RequestContext;
     /** The client's IP address, when the adapter knows it (e.g. to rate-limit a public form). */
     readonly ip: string | undefined;
     /** The Local API. Pass `{ user, overrideAccess: false }` to apply the user's access rules. */
@@ -2656,6 +2754,8 @@ interface Config {
     readonly endpoints?: readonly Endpoint[];
     /** Extra `easy-cms <name>` CLI commands, e.g. from plugins. */
     readonly commands?: readonly CliCommand[];
+    /** The request's context and user, worked out on each API request (usually by a plugin). */
+    readonly onRequest?: OnRequest;
     /**
      * Field types from packages, e.g. `color` from `@easy-cms/fields`: fields then use
      * `type: 'color'`. See `defineFieldType`.
@@ -2725,6 +2825,11 @@ interface ApiKeyPermissions {
      * or missing: every folder.
      */
     readonly folders?: readonly (string | number)[];
+    /**
+     * The context the key was created in (`onRequest`, e.g. its tenant), kept for good: requests
+     * with the key get it as `user.apiKey.permissions.context`. Set by Easy CMS, not by input.
+     */
+    readonly context?: RequestContext;
 }
 /** Set on `AuthUser.apiKey` when a request authenticated with an API key. */
 interface ApiKeyContext {
@@ -3167,6 +3272,8 @@ interface AdminWidgetRef {
 }
 interface AdminSchema {
     locale: AdminLocale;
+    /** A choice for the whole admin, e.g. the tenant (`admin.switcher`). */
+    switcher: AdminSwitcher | null;
     /** Admins can email users links to set their password (needs `email` and `serverURL`). */
     passwordLinks: boolean;
     /** Menu order of collections (`admin.menu`); unlisted ones follow. */
@@ -3330,4 +3437,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 ApiHandlerOptions, 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 DirectUpload, 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, createApiHandler, 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, sharedEasyCMS, 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 AdminSwitcher, type AdminViewAccess, type AdminWebhookDelivery, type AdminWidgetRef, type AfterChangeHook, type AfterDeleteHook, type AfterReadHook, type ApiHandlerOptions, 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 DirectUpload, 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 OnRequest, type OnRequestArgs, 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 RequestContext, 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, createApiHandler, createEasyCMS, createRestHandler, createRootEndpointHandler, defineConfig, defineFieldType, definePlugin, expandMimeTypes, fillMissing, findConfigFile, generateSlugs, generateTypes, hasRows, hashPassword, imageDimensions, importConfig, isAdmin, isHasMany, isLoggedIn, isSystemAdmin, keyAllows, loadConfig, localStorage, mergeForUpdate, mimeAllowed, mimeAllowedBy, parseId, populate, readCookie, resolveAdminModule, resolveConfig, rowFields, sharedEasyCMS, silentLogger, singularize, slugify, sniffMimeType, validateConfig, validateFields, verifyPassword, writeBackupFile };

package/dist/index.js

@@ -1,4 +1,5 @@
 // src/access.ts
+var isSystemAdmin = (user) => user?.role === "admin" && !user.apiKey && user.scoped !== true;
 var anyone = () => true;
 var isLoggedIn = ({ user }) => user !== null;
 var isAdmin = ({ user }) => user?.role === "admin";
@@ -41,8 +42,7 @@ function keyAllows(user, target, operation) {
   const allowed2 = key2.permissions.globals?.[target.global];
   return allowed2?.includes(operation) ?? false;
 }
-var isAdmin2 = (user) => user?.role === "admin";
-var ownKeys = ({ user }) => !user || user.apiKey ? false : isAdmin2(user) ? true : { user: { equals: user.id } };
+var ownKeys = ({ user }) => !user || user.apiKey ? false : isSystemAdmin(user) ? true : { user: { equals: user.id } };
 var system = { update: () => false };
 var apiKeysCollection = {
   slug: API_KEYS,
@@ -99,14 +99,17 @@ var apiKeysCollection = {
     { name: "keyHash", type: "text", hidden: true }
   ],
   hooks: {
-    // Only real collections, globals and operations are kept.
+    // Only real collections, globals and operations are kept. A key keeps the context it was
+    // created in (`createApiKey`), whatever its permissions are changed to.
     beforeChange: [
-      ({ data, cms }) => data.permissions === void 0 ? data : {
-        ...data,
-        permissions: cleanPermissions(data.permissions, {
+      ({ data, cms, operation, originalDoc }) => {
+        if (data.permissions === void 0) return data;
+        const context = operation === "create" ? data.permissions.context : originalDoc?.permissions?.context;
+        const permissions = cleanPermissions(data.permissions, {
           collections: cms.config.collections.map((c) => c.slug),
           globals: cms.config.globals.map((g) => g.slug)
-        })
+        });
+        return { ...data, permissions: context ? { ...permissions, context } : permissions };
       }
     ]
   }
@@ -183,11 +186,11 @@ function withCreatedBy(config) {
 }
 var adminOrSelf = ({ user }) => {
   if (!user) return false;
-  if (user.role === "admin") return true;
+  if (isSystemAdmin(user)) return true;
   return { id: { equals: user.id } };
 };
 var adminOnly = {
-  update: ({ user }) => user?.role === "admin"
+  update: ({ user }) => isSystemAdmin(user)
 };
 function userFields(roles, rbac) {
   const defaultRole = roles.includes("editor") ? "editor" : roles[roles.length - 1];
@@ -239,9 +242,9 @@ function withUsers(config) {
     fields: [...userFields(roles, config.auth?.rbac === true), ...custom?.fields ?? []],
     access: {
       read: isLoggedIn,
-      create: isAdmin,
+      create: ({ user }) => isSystemAdmin(user),
       update: adminOrSelf,
-      delete: isAdmin,
+      delete: ({ user }) => isSystemAdmin(user),
       ...custom?.access
     }
   };
@@ -421,13 +424,28 @@ function withMedia(config) {
       ]
     }
   };
-  const others = (config.collections ?? []).filter((c) => c.slug !== MEDIA);
+  const customFolders = config.collections?.find((c) => c.slug === MEDIA_FOLDERS);
+  const mediaFolders = customFolders ? {
+    ...mediaFoldersCollection,
+    fields: [...mediaFoldersCollection.fields, ...customFolders.fields],
+    access: { ...mediaFoldersCollection.access, ...customFolders.access },
+    hooks: {
+      ...customFolders.hooks,
+      afterRead: [
+        ...mediaFoldersCollection.hooks?.afterRead ?? [],
+        ...customFolders.hooks?.afterRead ?? []
+      ]
+    }
+  } : mediaFoldersCollection;
+  const others = (config.collections ?? []).filter(
+    (c) => c.slug !== MEDIA && c.slug !== MEDIA_FOLDERS
+  );
   return {
     ...config,
     collections: [
       ...others.slice(0, 1),
       media,
-      ...folders ? [mediaFoldersCollection] : [],
+      ...folders ? [mediaFolders] : [],
       ...others.slice(1)
     ]
   };
@@ -4079,7 +4097,7 @@ var Roles = class {
    * it; without roles, nobody else (`status`, `deliveries`) or everybody (plugin pages).
    */
   async canView(user, id) {
-    if (user.role === "admin" && !user.apiKey) return true;
+    if (isSystemAdmin(user)) return true;
     if (user.apiKey) return false;
     if (!this.enabled) return id.startsWith("page:") || id.startsWith("widget:");
     return (await this.permissionsOf(user.role)).admin?.includes(id) ?? false;
@@ -4866,6 +4884,14 @@ function validateAdmin(config, add) {
       "e.g. siteUrl: 'https://example.com'"
     );
   }
+  const switcher = admin.switcher;
+  if (switcher !== void 0 && switcher !== null) {
+    const { cookie: cookie2, options } = switcher;
+    if (typeof cookie2 !== "string" || !/^[A-Za-z0-9_-]+$/.test(cookie2))
+      add("admin.switcher.cookie", "must be a cookie name (letters, digits, - and _)");
+    if (typeof options !== "string" || !options.startsWith("/"))
+      add("admin.switcher.options", 'must be a path under the API starting with "/"');
+  }
   const modules = admin.modules;
   if (modules !== void 0) {
     if (!Array.isArray(modules)) {
@@ -5501,6 +5527,19 @@ function validateField(field, path, siblings, collectionSlugs, add) {
       if (cell !== void 0) validateComponent(cell, `${path}.admin.cell`, add);
     }
   }
+  if (field.uniqueWithin !== void 0) {
+    const scope = siblings.get(field.uniqueWithin);
+    if (!field.unique && field.type !== "slug") {
+      add(`${path}.uniqueWithin`, "needs `unique: true` (or a slug field)");
+    } else if (!scope || scope === field) {
+      add(`${path}.uniqueWithin`, `no sibling field named "${field.uniqueWithin}"`);
+    } else if (!["relationship", "select", "text", "number"].includes(scope.type) || "hasMany" in scope && scope.hasMany || scope.localized) {
+      add(
+        `${path}.uniqueWithin`,
+        `"${field.uniqueWithin}" must be a single, unlocalized relationship, select, text or number field`
+      );
+    }
+  }
   switch (field.type) {
     case "text":
     case "textarea":
@@ -5521,17 +5560,6 @@ function validateField(field, path, siblings, collectionSlugs, add) {
           add(`${path}.from`, `"${field.from}" must be a text field (got ${source.type})`);
         }
       }
-      if (field.uniqueWithin !== void 0) {
-        const scope = siblings.get(field.uniqueWithin);
-        if (!scope || scope === field) {
-          add(`${path}.uniqueWithin`, `no sibling field named "${field.uniqueWithin}"`);
-        } else if (!["relationship", "select", "text", "number"].includes(scope.type) || "hasMany" in scope && scope.hasMany || scope.localized) {
-          add(
-            `${path}.uniqueWithin`,
-            `"${field.uniqueWithin}" must be a single, unlocalized relationship, select, text or number field`
-          );
-        }
-      }
       break;
     case "relationship":
       if (typeof field.to !== "string" || !collectionSlugs.has(field.to)) {
@@ -5822,7 +5850,8 @@ async function resolveConfig(input) {
       menu: config.admin?.menu ?? [],
       modules: config.admin?.modules ?? [],
       pages: config.admin?.pages ?? [],
-      dashboard: config.admin?.dashboard ?? []
+      dashboard: config.admin?.dashboard ?? [],
+      switcher: config.admin?.switcher ?? null
     },
     upload: {
       dir: config.upload?.dir ?? "uploads",
@@ -5969,6 +5998,29 @@ var EasyCMS = class {
     );
     this.auth = new Auth(this);
   }
+  /**
+   * The user and context of a request, as the REST API works them out: its session cookie or
+   * Bearer token, then `onRequest`. For framework routes and server code that act for a visitor;
+   * pass both to the Local API with `overrideAccess: false`.
+   */
+  async forRequest(request) {
+    const headers = request instanceof Headers ? request : request.headers;
+    const url = request instanceof Headers ? void 0 : new URL(request.url);
+    return this.applyOnRequest(headers, url, await this.auth.userFromHeaders(headers));
+  }
+  /** @internal `onRequest` of the config, for a request whose user is known. */
+  async applyOnRequest(headers, url, user) {
+    const result = await this.config.onRequest?.({
+      headers,
+      url,
+      user,
+      cms: this
+    });
+    return {
+      user: result?.user !== void 0 ? result.user : user,
+      context: result?.context ?? NO_CONTEXT
+    };
+  }
   async find(collection2, options = {}) {
     const config = this.collection(collection2);
     const guard = guardOf(options);
@@ -6222,6 +6274,7 @@ var EasyCMS = class {
     await this.checkGrant(guard, { collection: MEDIA }, "create");
     const allowed2 = await evaluateAccess(this.collection(MEDIA).access?.create, {
       user: guard.user,
+      context: guard.context,
       data
     });
     if (allowed2 !== true) throw deny(guard.user);
@@ -6259,7 +6312,11 @@ var EasyCMS = class {
     const fromURL = this.config.upload.fromURL;
     if (guard.enforce) {
       await this.checkGrant(guard, { collection: MEDIA }, "create");
-      const allowed2 = await evaluateAccess(config.access?.create, { user: guard.user, data });
+      const allowed2 = await evaluateAccess(config.access?.create, {
+        user: guard.user,
+        context: guard.context,
+        data
+      });
       if (allowed2 !== true) throw deny(guard.user);
       if (!fromURL)
         throw new ValidationError(MEDIA, [
@@ -6291,7 +6348,10 @@ var EasyCMS = class {
     const config = this.collection(API_KEYS);
     const guard = guardOf(options);
     if (guard.enforce) {
-      const allowed2 = await evaluateAccess(config.access?.create, { user: guard.user });
+      const allowed2 = await evaluateAccess(config.access?.create, {
+        user: guard.user,
+        context: guard.context
+      });
       if (allowed2 !== true) throw deny(guard.user);
     }
     const owner = guard.enforce ? guard.user?.id : data.user;
@@ -6303,7 +6363,12 @@ var EasyCMS = class {
       config,
       {
         name: data.name,
-        permissions: data.permissions ?? {},
+        // The context it is created in (e.g. a tenant) stays with the key. Requests can't name
+        // one; trusted calls may.
+        permissions: {
+          ...withoutContext(data.permissions),
+          ...guard.enforce ? Object.keys(guard.context).length > 0 ? { context: guard.context } : {} : data.permissions?.context ? { context: data.permissions.context } : {}
+        },
         expiresAt: expiresAt ?? null,
         prefix,
         user: owner
@@ -6564,7 +6629,11 @@ var EasyCMS = class {
     if (id === null) {
       if (guard.enforce) {
         await this.checkGrant(guard, { collection: collection2 }, "create");
-        const allowed2 = await evaluateAccess(config.access?.create, { user: guard.user, data: raw });
+        const allowed2 = await evaluateAccess(config.access?.create, {
+          user: guard.user,
+          context: guard.context,
+          data: raw
+        });
         if (allowed2 !== true) throw deny(guard.user);
       }
     } else {
@@ -6620,8 +6689,9 @@ var EasyCMS = class {
       raw,
       await this.fieldChecker("update", guard, void 0, raw)
     );
-    const saved = await this.db.findGlobal({ slug: slug2 }) ?? {};
-    const current = await this.globalDraft(config, saved);
+    const key2 = this.globalKey(config, guard);
+    const saved = (key2 ? await this.db.findGlobal({ slug: key2 }) : null) ?? {};
+    const current = await this.globalDraft(config, saved, key2);
     const merged = generateSlugs(
       config.fields,
       applyDefaults(
@@ -6719,7 +6789,7 @@ var EasyCMS = class {
       "update",
       parsed,
       options,
-      guard.user
+      guard
     );
     prepared = await this.transform(
       config.hooks?.beforeChange,
@@ -6853,8 +6923,12 @@ var EasyCMS = class {
     const config = this.global(slug2);
     const guard = guardOf(options);
     await this.checkGlobalAccess(config, "read", guard);
-    const saved = await this.db.findGlobal({ slug: slug2 });
-    const stored = saved && options.draft ? await this.globalDraft(config, saved) : saved;
+    return this.readGlobal(config, this.globalKey(config, guard), guard, options);
+  }
+  /** A global as stored under `key` (see `globalKey`); empty when there is no key. */
+  async readGlobal(config, key2, guard, options) {
+    const saved = key2 ? await this.db.findGlobal({ slug: key2 }) : null;
+    const stored = saved && options.draft ? await this.globalDraft(config, saved, key2) : saved;
     const data = fillMissing(
       config.fields,
       applyDefaults(config.fields, stored ?? {}, this.config.localization)
@@ -6867,6 +6941,27 @@ var EasyCMS = class {
     const { id: _id, ...doc } = out;
     return doc;
   }
+  /**
+   * Where a global is kept: its slug, or `<slug>@<scope>` for globals with `scope` (e.g. one per
+   * tenant). `null` when the call has no scope: reads give the global empty. `scope` is given by
+   * scheduled jobs, which have no request.
+   */
+  globalKey(config, guard, scope) {
+    if (scope !== void 0) return `${config.slug}@${scope}`;
+    if (!config.scope) return config.slug;
+    const own = config.scope({ context: guard.context, user: guard.user });
+    if (own === void 0) return config.slug;
+    return own === null ? null : `${config.slug}@${own}`;
+  }
+  /** `globalKey` for changes, which need a scope. */
+  writeKey(config, guard, scope) {
+    const key2 = this.globalKey(config, guard, scope);
+    if (key2 === null)
+      throw new QueryError(
+        `"${config.slug}" has a value per scope (e.g. per tenant): choose one to change it`
+      );
+    return key2;
+  }
   async updateGlobal(slug2, data, options = {}) {
     return this.saveGlobal(slug2, asObject(data, slug2), options);
   }
@@ -6880,20 +6975,21 @@ var EasyCMS = class {
     const config = this.global(slug2);
     const guard = guardOf(options);
     await this.checkGlobalAccess(config, "update", guard);
-    const saved = await this.db.findGlobal({ slug: slug2 });
-    if (saved && await this.globalDraft(config, saved) !== saved) {
-      await this.saveVersion(config, globalParent(slug2), 0, saved, guard);
+    const key2 = this.writeKey(config, guard);
+    const saved = await this.db.findGlobal({ slug: key2 });
+    if (saved && await this.globalDraft(config, saved, key2) !== saved) {
+      await this.saveVersion(config, globalParent(key2), 0, saved, guard);
     }
     return this.findGlobal(slug2, { ...options, draft: true });
   }
   /** Saved versions of a global, newest first. Needs update access. */
   async findGlobalVersions(slug2, options = {}) {
-    await this.globalVersionTarget(slug2, options);
-    return this.versions.list(globalParent(slug2), 0, options.limit ?? 20, options.page ?? 1);
+    const { key: key2 } = await this.globalVersionTarget(slug2, options);
+    return this.versions.list(globalParent(key2), 0, options.limit ?? 20, options.page ?? 1);
   }
   async findGlobalVersion(slug2, versionId, options = {}) {
-    const config = await this.globalVersionTarget(slug2, options);
-    const version = await this.versions.get(globalParent(slug2), 0, versionId);
+    const { config, key: key2 } = await this.globalVersionTarget(slug2, options);
+    const version = await this.versions.get(globalParent(key2), 0, versionId);
     if (!version) return null;
     const data = fillMissing(
       config.fields,
@@ -6908,8 +7004,8 @@ var EasyCMS = class {
   }
   /** Makes an old version of a global current (as a draft when the global has drafts). */
   async restoreGlobalVersion(slug2, versionId, options = {}) {
-    const config = await this.globalVersionTarget(slug2, options);
-    const version = await this.versions.get(globalParent(slug2), 0, versionId);
+    const { config, key: key2 } = await this.globalVersionTarget(slug2, options);
+    const version = await this.versions.get(globalParent(key2), 0, versionId);
     if (!version) throw new NotFoundError(`${slug2} version`, versionId);
     const { status: _status, ...data } = version.data;
     return this.saveGlobal(
@@ -6922,20 +7018,22 @@ var EasyCMS = class {
   async globalVersionTarget(slug2, options) {
     const config = this.global(slug2);
     if (!versionLimit(config)) throw new QueryError(`"${slug2}" has no versions`);
-    await this.checkGlobalAccess(config, "update", guardOf(options));
-    return config;
+    const guard = guardOf(options);
+    await this.checkGlobalAccess(config, "update", guard);
+    return { config, key: this.writeKey(config, guard) };
   }
   /** The global's pending draft when it has one (see `withDrafts`), otherwise `saved`. */
-  async globalDraft(config, saved) {
-    if (!this.separateDrafts(config) || saved.status !== "published") return saved;
-    const version = (await this.versions.latest(globalParent(config.slug), [0])).get("0");
+  async globalDraft(config, saved, key2) {
+    if (!key2 || !this.separateDrafts(config) || saved.status !== "published") return saved;
+    const version = (await this.versions.latest(globalParent(key2), [0])).get("0");
     if (version?.status !== "draft") return saved;
     return { ...version.data, updatedAt: version.createdAt, status: "draft" };
   }
-  async saveGlobal(slug2, raw, options, mode = "save") {
+  async saveGlobal(slug2, raw, options, mode = "save", scope) {
     const config = this.global(slug2);
     const guard = guardOf(options);
     await this.checkGlobalAccess(config, "update", guard);
+    const key2 = this.writeKey(config, guard, scope);
     if (config.drafts && (mode === "unpublish" || raw.status === "published"))
       await this.checkGrant(guard, { global: slug2 }, "publish");
     const input = await filterInput(
@@ -6943,8 +7041,8 @@ var EasyCMS = class {
       raw,
       await this.fieldChecker("update", guard, void 0, raw)
     );
-    const existing = await this.db.findGlobal({ slug: slug2 }) ?? {};
-    const current = await this.globalDraft(config, existing);
+    const existing = await this.db.findGlobal({ slug: key2 }) ?? {};
+    const current = await this.globalDraft(config, existing, key2);
     const localized = mode === "restore" ? input : this.toMaps(config, input, current, options);
     const merged = generateSlugs(
       config.fields,
@@ -6957,7 +7055,7 @@ var EasyCMS = class {
     );
     if (config.drafts) merged.status = input.status ?? current.status ?? "draft";
     const base = this.hookArgs(config, guard);
-    let prepared = await this.prepare(config, merged, "update", void 0, options, guard.user);
+    let prepared = await this.prepare(config, merged, "update", void 0, options, guard);
     prepared = await this.transform(
       config.hooks?.beforeChange,
       "data",
@@ -6967,7 +7065,7 @@ var EasyCMS = class {
     const now = (/* @__PURE__ */ new Date()).toISOString();
     if (mode !== "unpublish" && this.separateDrafts(config) && existing.status === "published" && prepared.status === "draft") {
       const draft = { ...prepared, updatedAt: now };
-      await this.saveVersion(config, globalParent(slug2), 0, draft, guard);
+      await this.saveVersion(config, globalParent(key2), 0, draft, guard);
       await this.notify(config.hooks?.afterChange, "afterChange", slug2, {
         ...base,
         doc: draft,
@@ -6976,10 +7074,10 @@ var EasyCMS = class {
       });
       this.emit(config, "draft", draft);
       await this.audited(config, "draft", draft, current, guard, mode);
-      return this.findGlobal(slug2, { ...options, draft: true });
+      return this.readGlobal(config, key2, guard, { ...options, draft: true });
     }
-    const doc = await this.db.updateGlobal({ slug: slug2, data: { ...prepared, updatedAt: now } });
-    await this.saveVersion(config, globalParent(slug2), 0, doc, guard);
+    const doc = await this.db.updateGlobal({ slug: key2, data: { ...prepared, updatedAt: now } });
+    await this.saveVersion(config, globalParent(key2), 0, doc, guard);
     await this.notify(config.hooks?.afterChange, "afterChange", slug2, {
       ...base,
       doc,
@@ -6988,17 +7086,17 @@ var EasyCMS = class {
     });
     this.emit(config, "update", doc, existing.status);
     await this.audited(config, "update", doc, current, guard, mode);
-    return this.findGlobal(slug2, { ...options, draft: true });
+    return this.readGlobal(config, key2, guard, { ...options, draft: true });
   }
   /**
    * What `user` may do with one document. Resolves `where`-style access
    * against the document, so the admin UI can hide actions precisely.
    */
-  async documentPermissions(collection2, id, user) {
+  async documentPermissions(collection2, id, user, context = NO_CONTEXT) {
     const config = this.collection(collection2);
     const parsed = parseId(id);
     if (parsed === void 0) return { update: false, delete: false };
-    const guard = { enforce: true, user };
+    const guard = { enforce: true, user, context };
     const check2 = (operation) => this.checkDocumentAccess(config, operation, guard, parsed, void 0).then(
       () => true,
       (error) => {
@@ -7166,9 +7264,10 @@ var EasyCMS = class {
       const action = row.action;
       try {
         if (parent.startsWith("global:")) {
-          const slug2 = parent.slice("global:".length);
-          if (action === "publish") await this.saveGlobal(slug2, { status: "published" }, {});
-          else await this.saveGlobal(slug2, { status: "draft" }, {}, "unpublish");
+          const { slug: slug2, scope } = splitGlobalKey(parent.slice("global:".length));
+          if (action === "publish")
+            await this.saveGlobal(slug2, { status: "published" }, {}, "save", scope);
+          else await this.saveGlobal(slug2, { status: "draft" }, {}, "unpublish", scope);
         } else if (action === "publish") {
           await this.updateDocument(parent, row.doc, { status: "published" }, { depth: 0 });
         } else {
@@ -7213,16 +7312,16 @@ var EasyCMS = class {
     await this.removeJob(collection2, parsed, jobId);
   }
   async scheduleGlobal(slug2, job, options = {}) {
-    await this.globalScheduleTarget(slug2, options);
-    return this.addJob(`global:${slug2}`, 0, job, options);
+    const key2 = await this.globalScheduleTarget(slug2, options);
+    return this.addJob(`global:${key2}`, 0, job, options);
   }
   async scheduledGlobal(slug2, options = {}) {
-    await this.globalScheduleTarget(slug2, options);
-    return this.pendingJobs(`global:${slug2}`, 0);
+    const key2 = await this.globalScheduleTarget(slug2, options);
+    return this.pendingJobs(`global:${key2}`, 0);
   }
   async cancelGlobalSchedule(slug2, jobId, options = {}) {
-    await this.globalScheduleTarget(slug2, options);
-    await this.removeJob(`global:${slug2}`, 0, jobId);
+    const key2 = await this.globalScheduleTarget(slug2, options);
+    await this.removeJob(`global:${key2}`, 0, jobId);
   }
   async scheduleTarget(collection2, id, options) {
     const config = this.collection(collection2);
@@ -7237,8 +7336,10 @@ var EasyCMS = class {
   async globalScheduleTarget(slug2, options) {
     const config = this.global(slug2);
     if (!config.schedule) throw new QueryError(`"${slug2}" has no schedule`);
-    await this.checkGlobalAccess(config, "update", guardOf(options));
-    await this.checkGrant(guardOf(options), { global: slug2 }, "publish");
+    const guard = guardOf(options);
+    await this.checkGlobalAccess(config, "update", guard);
+    await this.checkGrant(guard, { global: slug2 }, "publish");
+    return this.writeKey(config, guard);
   }
   async addJob(parent, doc, job, options) {
     const runAt = new Date(job.at);
@@ -7295,9 +7396,16 @@ var EasyCMS = class {
       if (!guard.enforce) return true;
       const cached = allowed2.get(parent);
       if (cached !== void 0) return cached;
-      const config = parent.startsWith("global:") ? this.config.globals.find((g) => g.slug === parent.slice("global:".length)) : this.config.collections.find((c) => c.slug === parent);
-      const access = config ? await evaluateAccess(config.access?.update, { user: guard.user }) : false;
-      const target = parent.startsWith("global:") ? { global: parent.slice("global:".length) } : { collection: parent };
+      const global2 = parent.startsWith("global:") ? this.config.globals.find(
+        (g) => g.slug === splitGlobalKey(parent.slice("global:".length)).slug
+      ) : void 0;
+      if (global2 && this.globalKey(global2, guard) !== parent.slice("global:".length)) {
+        allowed2.set(parent, false);
+        return false;
+      }
+      const config = parent.startsWith("global:") ? global2 : this.config.collections.find((c) => c.slug === parent);
+      const access = config ? await evaluateAccess(config.access?.update, { user: guard.user, context: guard.context }) : false;
+      const target = parent.startsWith("global:") ? { global: splitGlobalKey(parent.slice("global:".length)).slug } : { collection: parent };
       const result = access !== false && await this.roles.allows(guard.user, target, "update") !== false;
       allowed2.set(parent, result);
       return result;
@@ -7306,7 +7414,7 @@ var EasyCMS = class {
     for (const row of rows.docs) {
       const parent = String(row.parent);
       if (!await may2(parent)) continue;
-      const target = parent.startsWith("global:") ? { global: parent.slice("global:".length) } : { collection: parent };
+      const target = parent.startsWith("global:") ? { global: splitGlobalKey(parent.slice("global:".length)).slug } : { collection: parent };
       jobs.push({ ...toJob(row), ...target, doc: row.doc });
       if (jobs.length === limit) break;
     }
@@ -7418,7 +7526,10 @@ var EasyCMS = class {
   async readWhere(config, guard, where) {
     if (!guard.enforce) return where;
     const own = await this.checkGrant(guard, { collection: config.slug }, "read");
-    const access = await evaluateAccess(config.access?.read, { user: guard.user });
+    const access = await evaluateAccess(config.access?.read, {
+      user: guard.user,
+      context: guard.context
+    });
     if (access === false) throw deny(guard.user);
     await this.checkQueryFields(config, guard, where);
     return andWhere(andWhere(where, access), own);
@@ -7428,6 +7539,7 @@ var EasyCMS = class {
     const own = await this.checkGrant(guard, { collection: config.slug }, operation);
     const allowed2 = await evaluateAccess(config.access?.[operation], {
       user: guard.user,
+      context: guard.context,
       id,
       ...data ? { data } : {}
     });
@@ -7445,7 +7557,10 @@ var EasyCMS = class {
   async checkGlobalAccess(config, operation, guard) {
     if (!guard.enforce) return;
     await this.checkGrant(guard, { global: config.slug }, operation);
-    const access = await evaluateAccess(config.access?.[operation], { user: guard.user });
+    const access = await evaluateAccess(config.access?.[operation], {
+      user: guard.user,
+      context: guard.context
+    });
     if (typeof access === "object")
       throw new QueryError(`${operation} access of global "${config.slug}" must return a boolean`);
     if (!access) throw deny(guard.user);
@@ -7456,6 +7571,7 @@ var EasyCMS = class {
       kind,
       {
         user: guard.user,
+        context: guard.context,
         ...id !== void 0 ? { id } : {},
         ...data ? { data } : {}
       },
@@ -7536,7 +7652,11 @@ var EasyCMS = class {
       await this.checkGrant(guard, { collection: collection2 }, "create");
       if (config.drafts && raw.status === "published")
         await this.checkGrant(guard, { collection: collection2 }, "publish");
-      const allowed2 = await evaluateAccess(config.access?.create, { user: guard.user, data: raw });
+      const allowed2 = await evaluateAccess(config.access?.create, {
+        user: guard.user,
+        context: guard.context,
+        data: raw
+      });
       if (typeof allowed2 === "object")
         throw new QueryError(`create access of "${collection2}" must return a boolean`);
       if (!allowed2) throw deny(guard.user);
@@ -7568,7 +7688,7 @@ var EasyCMS = class {
       "create",
       void 0,
       options,
-      (hookGuard ?? guard).user
+      hookGuard ?? guard
     );
     prepared = await this.transform(
       config.hooks?.beforeChange,
@@ -7706,7 +7826,12 @@ var EasyCMS = class {
     });
   }
   hookArgs(config, guard) {
-    return { user: guard.user, cms: this, slug: config.slug };
+    return {
+      user: guard.user,
+      cms: this,
+      slug: config.slug,
+      context: guard.context
+    };
   }
   /**
    * Runs hooks that may replace a value, passed as `data` (before hooks) or `doc` (afterRead).
@@ -7768,7 +7893,7 @@ var EasyCMS = class {
     return result;
   }
   /** Validates, checks uniqueness and references. Returns clean data or throws `ValidationError`. */
-  async prepare(config, data, operation, selfId, options = {}, user = null) {
+  async prepare(config, data, operation, selfId, options = {}, guard = { user: null, context: NO_CONTEXT }) {
     const isDraft = config.drafts === true && (data.status ?? "draft") === "draft";
     const locale = this.localeOf(options);
     const result = await validateFields(config.fields, data, {
@@ -7796,7 +7921,7 @@ var EasyCMS = class {
     }
     errors.push(...await this.checkReferences(result.references));
     if (errors.length === 0)
-      errors.push(...await this.checkFilterOptions(result.references, selfId, user));
+      errors.push(...await this.checkFilterOptions(result.references, selfId, guard));
     if (errors.length > 0) throw new ValidationError(config.slug, errors);
     return clean2;
   }
@@ -7855,9 +7980,10 @@ var EasyCMS = class {
         locale === this.config.localization?.defaultLocale ? field.name : `${field.name}.${locale}`,
         v
       ]) : [[field.name, field.name, value]];
+      const scope = field.uniqueWithin === void 0 ? void 0 : { [field.uniqueWithin]: { equals: data[field.uniqueWithin] ?? null } };
       for (const [path, errorField, v] of checks) {
         if (v === null || v === void 0) continue;
-        if (await this.isTaken(config.slug, path, v, selfId)) {
+        if (await this.isTaken(config.slug, path, v, selfId, scope)) {
           errors.push({ field: errorField, message: "must be unique" });
         }
       }
@@ -7875,14 +8001,16 @@ var EasyCMS = class {
     return await this.db.count({ collection: collection2, where }) > 0;
   }
   /** Each reference is one its relationship's `filterOptions` allow. */
-  async checkFilterOptions(references2, selfId, user) {
+  async checkFilterOptions(references2, selfId, guard) {
     const errors = [];
     const cms = this;
+    const { user, context } = guard;
     const allowed2 = /* @__PURE__ */ new Map();
     for (const ref of references2) {
       const filter = ref.filterOptions;
       if (!filter) continue;
-      if (!allowed2.has(filter)) allowed2.set(filter, await filter({ id: selfId, user, cms }));
+      if (!allowed2.has(filter))
+        allowed2.set(filter, await filter({ id: selfId, user, cms, context }));
       const where = allowed2.get(filter);
       if (where === true) continue;
       const target = this.config.collections.find((c) => c.slug === ref.collection);
@@ -7968,8 +8096,21 @@ function wherePaths(where) {
   }
   return out;
 }
+var NO_CONTEXT = Object.freeze({});
+function withoutContext(permissions) {
+  const { context: _context, ...rest } = permissions ?? {};
+  return rest;
+}
+function splitGlobalKey(key2) {
+  const at = key2.indexOf("@");
+  return at < 0 ? { slug: key2 } : { slug: key2.slice(0, at), scope: key2.slice(at + 1) };
+}
 function guardOf(options) {
-  return { enforce: options.overrideAccess === false, user: options.user ?? null };
+  return {
+    enforce: options.overrideAccess === false,
+    user: options.user ?? null,
+    context: options.context ?? NO_CONTEXT
+  };
 }
 function deny(user) {
   return user ? new ForbiddenError() : new UnauthorizedError();
@@ -8256,8 +8397,8 @@ function componentRef(component) {
   if (typeof component === "string") return { tag: component };
   return component.props ? { tag: component.tag, props: JSON.parse(JSON.stringify(component.props)) } : { tag: component.tag };
 }
-async function allowed(access, user) {
-  return await evaluateAccess(access, { user }) !== false;
+async function allowed(access, user, context) {
+  return await evaluateAccess(access, { user, context }) !== false;
 }
 async function serializeFields(fields, checks, localized, folderId) {
   const { update: update2 } = checks;
@@ -8339,21 +8480,21 @@ async function serializeFields(fields, checks, localized, folderId) {
   }
   return out;
 }
-async function checkers(cms, user) {
+async function checkers(cms, user, context) {
   const rules = await cms.roles.fieldRules(user);
   return {
-    update: new FieldAccessChecker("update", { user }, rules),
-    read: new FieldAccessChecker("read", { user }, rules)
+    update: new FieldAccessChecker("update", { user, context }, rules),
+    read: new FieldAccessChecker("read", { user, context }, rules)
   };
 }
-async function may(cms, access, user, target, operation) {
-  return await allowed(access, user) && await cms.roles.allows(user, target, operation) !== false;
+async function may(cms, access, user, target, operation, context) {
+  return await allowed(access, user, context) && await cms.roles.allows(user, target, operation) !== false;
 }
-async function collection(cms, config, user, localized, roles) {
+async function collection(cms, config, user, localized, roles, context) {
   const target = { collection: config.slug };
   const fields = await serializeFields(
     config.fields,
-    await checkers(cms, user),
+    await checkers(cms, user, context),
     localized,
     folderIds(cms)
   );
@@ -8372,11 +8513,11 @@ async function collection(cms, config, user, localized, roles) {
     schedule: config.schedule === true,
     fields,
     permissions: {
-      read: await may(cms, config.access?.read, user, target, "read"),
-      create: await may(cms, config.access?.create, user, target, "create"),
-      update: await may(cms, config.access?.update, user, target, "update"),
-      delete: await may(cms, config.access?.delete, user, target, "delete"),
-      publish: config.drafts === true && await may(cms, config.access?.update, user, target, "publish")
+      read: await may(cms, config.access?.read, user, target, "read", context),
+      create: await may(cms, config.access?.create, user, target, "create", context),
+      update: await may(cms, config.access?.update, user, target, "update", context),
+      delete: await may(cms, config.access?.delete, user, target, "delete", context),
+      publish: config.drafts === true && await may(cms, config.access?.update, user, target, "publish", context)
     }
   };
   if (config.labels) result.labels = config.labels;
@@ -8392,9 +8533,9 @@ async function collection(cms, config, user, localized, roles) {
     result.editIn = "drawer";
   return result;
 }
-async function global(cms, config, user, localized) {
+async function global(cms, config, user, localized, context) {
   const target = { global: config.slug };
-  const checks = await checkers(cms, user);
+  const checks = await checkers(cms, user, context);
   const result = {
     slug: config.slug,
     drafts: config.drafts === true,
@@ -8403,9 +8544,9 @@ async function global(cms, config, user, localized) {
     schedule: config.schedule === true,
     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"),
-      publish: config.drafts === true && await may(cms, config.access?.update, user, target, "publish")
+      read: await may(cms, config.access?.read, user, target, "read", context),
+      update: await may(cms, config.access?.update, user, target, "update", context),
+      publish: config.drafts === true && await may(cms, config.access?.update, user, target, "publish", context)
     }
   };
   if (config.label !== void 0) result.label = config.label;
@@ -8413,11 +8554,11 @@ async function global(cms, config, user, localized) {
   if (config.admin?.sidebar?.length) result.sidebar = config.admin.sidebar.map(componentRef);
   return result;
 }
-async function adminSchema(cms, user, origin) {
+async function adminSchema(cms, user, origin, context = {}) {
   const collections = cms.config.collections.filter((c) => !INTERNAL_COLLECTIONS.has(c.slug));
   const localization = cms.config.localization;
   const localized = localization !== null;
-  const admin = user.role === "admin" && !user.apiKey;
+  const admin = isSystemAdmin(user);
   const deliveries = cms.config.collections.some(
     (c) => c.slug === WEBHOOK_DELIVERIES || c.slug === EMAIL_DELIVERIES
   );
@@ -8433,13 +8574,16 @@ async function adminSchema(cms, user, origin) {
   const roles = await cms.roles.options();
   return {
     locale: cms.config.admin.locale,
+    switcher: cms.config.admin.switcher,
     passwordLinks: cms.auth.canSendPasswordLinks(origin),
     menu: [...cms.config.admin.menu],
     localization: localization ? { locales: [...localization.locales], defaultLocale: localization.defaultLocale } : null,
     collections: await Promise.all(
-      collections.map((c) => collection(cms, c, user, localized, roles))
+      collections.map((c) => collection(cms, c, user, localized, roles, context))
+    ),
+    globals: await Promise.all(
+      cms.config.globals.map((g) => global(cms, g, user, localized, context))
     ),
-    globals: await Promise.all(cms.config.globals.map((g) => global(cms, g, user, localized))),
     modules: adminModuleUrls(cms),
     uploadFromURL: cms.config.upload.fromURL !== void 0,
     upload: {
@@ -8504,7 +8648,7 @@ function folderIds(cms) {
 }
 
 // src/version.ts
-var VERSION = true ? "0.42.0" : "0.0.0-dev";
+var VERSION = true ? "0.44.0" : "0.0.0-dev";
 
 // src/rest/admin-status.ts
 var DAY2 = 864e5;
@@ -8592,7 +8736,7 @@ function fieldAt(fields, path) {
   }
   return found;
 }
-async function pickerFilter(cms, url, target, user) {
+async function pickerFilter(cms, url, target, user, context = {}) {
   const forCollection = url.searchParams.get("filterFor");
   const forGlobal = url.searchParams.get("filterForGlobal");
   const spec = forCollection ?? forGlobal;
@@ -8606,7 +8750,7 @@ async function pickerFilter(cms, url, target, user) {
   if (!field.filterOptions) return void 0;
   const rawId = url.searchParams.get("filterId");
   const id = rawId === null || rawId === "" ? void 0 : /^\d+$/.test(rawId) ? Number(rawId) : rawId;
-  const where = await field.filterOptions({ id, user, cms });
+  const where = await field.filterOptions({ id, user, cms, context });
   return where === true ? void 0 : where;
 }
 
@@ -8766,10 +8910,19 @@ async function respond(cms, request, url, path, root, options, production) {
     if (path === null) throw new HttpError("Not found", 404);
     const segments = pathSegments(path);
     const { token, via } = readToken(request);
-    const user = token ? await cms.auth.verify(token) : null;
-    if (!user && via === "bearer" && token?.startsWith("ecms_"))
+    const signedIn = token ? await cms.auth.verify(token) : null;
+    if (!signedIn && via === "bearer" && token?.startsWith("ecms_"))
       throw new UnauthorizedError("Invalid or expired API key");
-    const ctx = { request, url, user, via: user ? via : null, token, headers };
+    const { user, context } = await cms.applyOnRequest(request.headers, url, signedIn);
+    const ctx = {
+      request,
+      url,
+      user,
+      context,
+      via: signedIn ? via : null,
+      token,
+      headers
+    };
     const method = request.method.toUpperCase();
     if (method !== "GET" && method !== "HEAD") checkCsrf(cms, ctx);
     const audit = {
@@ -8833,6 +8986,7 @@ async function customEndpoint(cms, ctx, method, segments, root, options) {
       url: ctx.url,
       params,
       user: ctx.user,
+      context: ctx.context,
       ip: options.getClientIp?.(ctx.request),
       cms,
       json: () => readJson(ctx.request)
@@ -8859,7 +9013,12 @@ function matchPath(path, segments) {
 }
 async function route(cms, ctx, method, segments, options) {
   const [first, second, third] = segments;
-  const access = { overrideAccess: false, user: ctx.user, ...parseLocale(ctx.url) };
+  const access = {
+    overrideAccess: false,
+    user: ctx.user,
+    context: ctx.context,
+    ...parseLocale(ctx.url)
+  };
   const draft = ctx.user !== null && ctx.url.searchParams.get("draft") === "true";
   if (segments.length === 0) throw new HttpError("Not found", 404);
   if (first === "auth") return ssoRoute(cms, ctx, method, segments);
@@ -8957,14 +9116,14 @@ async function route(cms, ctx, method, segments, options) {
     const secret = cms.config.cronSecret ?? process.env.CRON_SECRET;
     const header = ctx.request.headers.get("authorization") ?? "";
     const byCron = !!secret && safeEqual(header, `Bearer ${secret}`);
-    if (!byCron && ctx.user?.role !== "admin") {
+    if (!byCron && !isSystemAdmin(ctx.user)) {
       throw ctx.user ? new HttpError("Forbidden", 403) : new UnauthorizedError();
     }
     return { body: await cms.runJobs() };
   }
   if (first === "admin" && second === "backups") {
     if (!ctx.user) throw new UnauthorizedError();
-    if (ctx.user.role !== "admin" || ctx.user.apiKey) throw new ForbiddenError();
+    if (!isSystemAdmin(ctx.user)) throw new ForbiddenError();
     const [, , id2, action, extra] = segments;
     if (extra !== void 0) throw new HttpError("Not found", 404);
     if (id2 === void 0) {
@@ -9006,7 +9165,7 @@ async function route(cms, ctx, method, segments, options) {
   }
   if (first === "admin" && second === "email") {
     if (!ctx.user) throw new UnauthorizedError();
-    if (ctx.user.role !== "admin" || ctx.user.apiKey) throw new ForbiddenError();
+    if (!isSystemAdmin(ctx.user)) throw new ForbiddenError();
     const [, , action, extra] = segments;
     if (extra !== void 0) throw new HttpError("Not found", 404);
     if (action === void 0) {
@@ -9025,7 +9184,7 @@ async function route(cms, ctx, method, segments, options) {
   }
   if (first === "admin" && second === "sso" && third === void 0) {
     if (!ctx.user) throw new UnauthorizedError();
-    if (ctx.user.role !== "admin" || ctx.user.apiKey) throw new ForbiddenError();
+    if (!isSystemAdmin(ctx.user)) throw new ForbiddenError();
     if (method !== "GET") throw methodNotAllowed(ctx, "GET");
     return { body: cms.auth.sso.settings(ctx.url.origin) };
   }
@@ -9066,7 +9225,7 @@ async function route(cms, ctx, method, segments, options) {
   }
   if (first === "admin" && second === "owned" && third !== void 0 && segments.length === 3) {
     if (!ctx.user) throw new UnauthorizedError();
-    if (ctx.user.role !== "admin" || ctx.user.apiKey) throw new ForbiddenError();
+    if (!isSystemAdmin(ctx.user)) throw new ForbiddenError();
     if (method !== "GET") throw methodNotAllowed(ctx, "GET");
     const parsed = parseId(third);
     if (parsed === void 0) throw new HttpError("Not found", 404);
@@ -9080,7 +9239,7 @@ async function route(cms, ctx, method, segments, options) {
   }
   if (first === "admin" && second === "roles") {
     if (!ctx.user) throw new UnauthorizedError();
-    if (ctx.user.role !== "admin" || ctx.user.apiKey) throw new ForbiddenError();
+    if (!isSystemAdmin(ctx.user)) throw new ForbiddenError();
     if (!cms.roles.enabled) throw new HttpError("Not found", 404);
     const [, , id2, action, extra] = segments;
     if (extra !== void 0) throw new HttpError("Not found", 404);
@@ -9166,7 +9325,7 @@ async function route(cms, ctx, method, segments, options) {
     if (method !== "GET") throw methodNotAllowed(ctx, "GET");
     if (!ctx.user) throw new UnauthorizedError();
     if (second === "schema" && third === void 0)
-      return { body: await adminSchema(cms, ctx.user, ctx.url.origin) };
+      return { body: await adminSchema(cms, ctx.user, ctx.url.origin, ctx.context) };
     if (second === "modules" && third !== void 0 && segments.length === 3) {
       const index = /^(\d+)\.js$/.exec(third)?.[1];
       const file = index === void 0 ? void 0 : await readAdminModule(cms, Number(index));
@@ -9186,13 +9345,19 @@ async function route(cms, ctx, method, segments, options) {
       return { body: await adminStatus(cms) };
     }
     if (second === "scheduled" && third === void 0)
-      return { body: await cms.upcomingJobs({ user: ctx.user, overrideAccess: false }) };
+      return {
+        body: await cms.upcomingJobs({
+          user: ctx.user,
+          context: ctx.context,
+          overrideAccess: false
+        })
+      };
     const [, , collection3, id2, extra] = segments;
     if (second === "access" && collection3 && id2 && extra === void 0) {
       if (INTERNAL_COLLECTIONS.has(collection3) || !cms.config.collections.some((c) => c.slug === collection3)) {
         throw new HttpError(`Unknown collection "${collection3}"`, 404);
       }
-      return { body: await cms.documentPermissions(collection3, id2, ctx.user) };
+      return { body: await cms.documentPermissions(collection3, id2, ctx.user, ctx.context) };
     }
     throw new HttpError("Not found", 404);
   }
@@ -9297,7 +9462,7 @@ async function route(cms, ctx, method, segments, options) {
   if (second === void 0) {
     if (method === "GET") {
       const query = parseListQuery(ctx.url);
-      const filter = await pickerFilter(cms, ctx.url, collection2, ctx.user);
+      const filter = await pickerFilter(cms, ctx.url, collection2, ctx.user, ctx.context);
       if (filter) query.where = query.where ? { and: [query.where, filter] } : filter;
       return { body: await cms.find(collection2, { ...access, ...query, draft }) };
     }
@@ -9342,12 +9507,17 @@ async function route(cms, ctx, method, segments, options) {
   throw methodNotAllowed(ctx, "GET, PATCH, DELETE");
 }
 async function documentAction(cms, ctx, method, collection2, id, path) {
-  const access = { overrideAccess: false, user: ctx.user, ...parseLocale(ctx.url) };
+  const access = {
+    overrideAccess: false,
+    user: ctx.user,
+    context: ctx.context,
+    ...parseLocale(ctx.url)
+  };
   const depth = parseDepth(ctx.url);
   const [action, versionId, extra] = path;
   if (collection2 === USERS && action === "password-link" && path.length === 1) {
     if (method !== "POST") throw methodNotAllowed(ctx, "POST");
-    if (ctx.user?.role !== "admin" || ctx.user.apiKey) throw new ForbiddenError();
+    if (!isSystemAdmin(ctx.user)) throw new ForbiddenError();
     const body = await readJson(ctx.request).catch(() => ({}));
     const sent = await cms.auth.sendPasswordLink(/^\d+$/.test(id) ? Number(id) : id, {
       origin: ctx.url.origin,
@@ -9400,7 +9570,12 @@ async function documentAction(cms, ctx, method, collection2, id, path) {
   throw new HttpError("Not found", 404);
 }
 async function globalAction(cms, ctx, method, slug2, path) {
-  const access = { overrideAccess: false, user: ctx.user, ...parseLocale(ctx.url) };
+  const access = {
+    overrideAccess: false,
+    user: ctx.user,
+    context: ctx.context,
+    ...parseLocale(ctx.url)
+  };
   const depth = parseDepth(ctx.url);
   const [action, versionId, extra] = path;
   if (action === "versions" && versionId === void 0) {
@@ -9563,6 +9738,7 @@ async function servePrivateFile(cms, ctx, key2, head) {
       limit: 5,
       depth: 0,
       user: ctx.user,
+      context: ctx.context,
       overrideAccess: false
     });
     const owns = found.docs.some(
@@ -9663,7 +9839,7 @@ async function ssoRoute(cms, ctx, method, segments) {
       if (method !== "GET") throw methodNotAllowed(ctx, "GET");
       const asked = ctx.url.searchParams.get("user");
       const target = asked === null ? ctx.user.id : parseId(asked) ?? asked;
-      if (String(target) !== String(ctx.user.id) && (ctx.user.role !== "admin" || ctx.user.apiKey))
+      if (String(target) !== String(ctx.user.id) && !isSystemAdmin(ctx.user))
         throw new ForbiddenError();
       return { body: await sso.identities(target) };
     }
@@ -10061,6 +10237,7 @@ export {
   isAdmin,
   isHasMany,
   isLoggedIn,
+  isSystemAdmin,
   keyAllows,
   loadConfig,
   localStorage,

package/package.json

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