@easy-cms/core 0.32.0 → 0.34.0

package/dist/index.d.ts

@@ -741,6 +741,194 @@ type UpdateInput<C extends Config, S extends CollectionSlug<C>> = Partial<Create
 /** Data accepted by `updateGlobal`. */
 type GlobalInput<C extends Config, S extends GlobalSlug<C>> = Partial<Simplify<FieldsInput<GlobalBySlug<C, S>['fields']> & StatusInput<GlobalBySlug<C, S>>>>;
 
+/** What a role may do with a collection or global, ticked in Settings → Roles. */
+declare const ROLE_OPERATIONS: readonly ["read", "create", "update", "delete", "publish"];
+type RoleOperation = (typeof ROLE_OPERATIONS)[number];
+/** A field a role may only read, or not see at all; fields not listed follow the collection. */
+type FieldRule = 'read' | 'hidden';
+type FieldRules = Readonly<Record<string, Readonly<Record<string, FieldRule>>>>;
+/**
+ * Stored in a role's `permissions`. Anything not listed is not allowed. A slug listed with no
+ * operations has been looked at and given nothing (it is not "new" in Settings → Roles).
+ */
+interface RolePermissions {
+    readonly collections?: Readonly<Record<string, readonly RoleOperation[]>>;
+    readonly globals?: Readonly<Record<string, readonly RoleOperation[]>>;
+    /** Admin pages: `status`, `deliveries`, `page:<path>` (`admin.pages`), `widget:<tag>` (`admin.dashboard`). */
+    readonly admin?: readonly string[];
+    /** Operations of `collections` allowed only on the role's own documents (see `admin.ownerField`). */
+    readonly own?: Readonly<Record<string, readonly RoleOperation[]>>;
+    /** Top-level fields the role may only read or not see, by collection or global slug. */
+    readonly fields?: {
+        readonly collections?: FieldRules;
+        readonly globals?: FieldRules;
+    };
+}
+/** One role as Settings → Roles shows it (`GET <api>/admin/roles`). */
+interface AdminRole {
+    id: ID;
+    key: string;
+    /** The name shown in the admin; empty for roles from the config that were not renamed. */
+    name: string;
+    /** From `auth.roles`: can't be deleted. */
+    system: boolean;
+    /** Users with this role. */
+    users: number;
+    permissions: RolePermissions;
+    updatedAt: string;
+}
+/** A top-level field whose permission can be set per role. */
+interface AdminRoleField {
+    name: string;
+    label?: Label;
+    /** Required without a default value: roles that create documents must be able to fill it. */
+    required: boolean;
+    /** The collection's owner field (`admin.ownerField`). */
+    owner?: boolean;
+}
+/** A row of the permissions table. */
+interface AdminRoleTarget {
+    slug: string;
+    /** Operations that make sense here (`publish` with drafts). */
+    ops: RoleOperation[];
+    /** No role has been given anything here yet (added to the config since). */
+    new: boolean;
+    fields: AdminRoleField[];
+}
+/** A page or dashboard panel that can be given to roles. */
+interface AdminRoleView {
+    id: string;
+    /** For plugin pages and panels; the admin names `status` and `deliveries` itself. */
+    label?: Label;
+}
+/** Settings → Roles (`GET <api>/admin/roles`). */
+interface AdminRoles {
+    roles: AdminRole[];
+    collections: (AdminRoleTarget & {
+        /** Collections its relationship and upload fields point to. */
+        references: string[];
+        /** Can be limited to own documents: the field that names the owner (`createdBy` by default). */
+        owner?: string;
+    })[];
+    globals: AdminRoleTarget[];
+    views: AdminRoleView[];
+}
+/** One change to a role (`GET <api>/admin/roles/:id/history`). */
+interface AdminRoleChange {
+    id: ID;
+    /** Email of who saved it, or `null` when it was the system (first start). */
+    author: string | null;
+    createdAt: string;
+    name: string;
+    permissions: RolePermissions;
+}
+/**
+ * Roles and their permissions (`auth.rbac`), on top of access rules: an operation is allowed
+ * when both allow it. Admins may do everything; requests that are not logged in are left to
+ * access rules alone.
+ */
+declare class Roles {
+    private readonly config;
+    private readonly db;
+    private readonly log?;
+    readonly enabled: boolean;
+    private readonly versions;
+    private cache;
+    private synced;
+    constructor(config: ResolvedConfig, db: Database, log?: ((message: string) => void) | undefined);
+    /**
+     * Whether the user's role allows an operation: `true`, `false`, or for their own account
+     * (users without read or update on `users`) a constraint to it.
+     */
+    allows(user: AuthUser | null, target: {
+        collection: string;
+    } | {
+        global: string;
+    }, operation: RoleOperation): Promise<boolean | Where>;
+    /**
+     * Whether the user may open an admin page: admins always; with roles, those whose role has
+     * it; without roles, nobody else (`status`, `deliveries`) or everybody (plugin pages).
+     */
+    canView(user: AuthUser, id: string): Promise<boolean>;
+    /**
+     * The field that names a collection's owner, for "own documents only": `admin.ownerField`, or
+     * `createdBy`. `undefined` without roles, and for users and collections roles don't cover.
+     */
+    ownerOf(slug: string): string | undefined;
+    /**
+     * The user's field rules (top-level fields their role may only read, or not see), for field
+     * access checks. Roles that may update only their own documents can't change the owner field.
+     */
+    fieldRules(user: AuthUser | null): Promise<ReadonlyMap<Field, FieldRule> | undefined>;
+    /** A new document is its creator's: sets `createdBy`, and an empty owner field. */
+    fillOwner(slug: string, data: Record<string, unknown>, user: AuthUser | null): void;
+    /** Documents a user owns, by collection (`createdBy` and owner fields), for deleting them. */
+    owned(userId: ID): Promise<{
+        collection: string;
+        count: number;
+    }[]>;
+    /** Gives a deleted user's documents to another user, or to nobody (`null`). */
+    transfer(from: ID, to: ID | null): Promise<void>;
+    /** Forgets cached permissions, after a role changed. */
+    invalidate(): void;
+    /**
+     * Adds the roles of `auth.roles` that are missing; on the first start, gives them everything.
+     * Runs once, on first use (not on startup: `easy-cms migrate` opens the CMS before the table exists).
+     */
+    sync(): Promise<void>;
+    private addMissing;
+    /**
+     * Documents from before roles have no `createdBy`: it is filled from who saved their first
+     * version, for collections with versions. Only while no document of the collection has one,
+     * so it runs once (and finds nothing to do afterwards).
+     */
+    private backfillCreators;
+    /** Whether a role exists (users can only be given existing roles). */
+    exists(key: string): Promise<boolean>;
+    /** Roles a user can be given, those of `auth.roles` first; `name` may be empty. */
+    options(): Promise<{
+        key: string;
+        name: string;
+    }[]>;
+    list(): Promise<AdminRoles>;
+    create(input: {
+        key?: unknown;
+        name?: unknown;
+        permissions?: unknown;
+    }, author: AuthUser): Promise<AdminRole>;
+    update(id: ID, input: {
+        name?: unknown;
+        permissions?: unknown;
+    }, author: AuthUser): Promise<AdminRole>;
+    delete(id: ID): Promise<void>;
+    history(id: ID): Promise<AdminRoleChange[]>;
+    /** Pages and panels roles can be given. */
+    private views;
+    /** Every collection and global, and the plugin pages and panels: what roles had before roles. */
+    private everything;
+    /** Keeps only known collections, globals, operations and pages; `read` comes with the others. */
+    private clean;
+    /**
+     * Keeps rules for known top-level fields. A field that must be filled in (required, without a
+     * default) can't be read-only or hidden for a role that creates documents.
+     */
+    private cleanRules;
+    /** Fields that name a collection's owner (`createdBy`, and `admin.ownerField`). */
+    private ownerColumns;
+    /** Sets one field of every matching document, keeping the rest as stored. */
+    private setWhere;
+    private cleanName;
+    private permissionsOf;
+    private load;
+    private rows;
+    private row;
+    private users;
+    private insert;
+    /** Keeps the role as saved, for its history. */
+    private record;
+    private toRole;
+}
+
 interface StoredFile {
     readonly body: Uint8Array;
     readonly size: number;
@@ -882,6 +1070,8 @@ declare class EasyCMS<C extends Config = Config> {
     readonly storage: StorageAdapter;
     /** Project root: relative paths in the config (e.g. `admin.modules`) start here. */
     readonly cwd: string;
+    /** Roles and their permissions (`auth.rbac`, Settings → Roles). */
+    readonly roles: Roles;
     private readonly versions;
     private readonly webhooks;
     private readonly mailer;
@@ -974,7 +1164,13 @@ declare class EasyCMS<C extends Config = Config> {
     private previewURL;
     private versionTarget;
     private updateDocument;
-    delete<S extends Slug<C>>(collection: S, id: ID, options?: AccessOptions): Promise<Doc<C, S>>;
+    /**
+     * Deletes a document. Deleting a user with roles from the admin (`auth.rbac`): `transferTo`
+     * gives the documents they own to another user; without it they have no owner.
+     */
+    delete<S extends Slug<C>>(collection: S, id: ID, options?: AccessOptions & {
+        transferTo?: ID | null;
+    }): Promise<Doc<C, S>>;
     findGlobal<S extends GSlug<C>>(slug: S, options?: ReadOptions): Promise<GDoc<C, S>>;
     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`. */
@@ -1101,13 +1297,23 @@ declare class EasyCMS<C extends Config = Config> {
     /** @internal */
     collection(slug: string): CollectionConfig;
     private global;
-    /** Refuses what a request's API key does not allow (see `ApiKeyPermissions`). */
-    private checkKey;
+    /**
+     * Refuses what a request's API key (see `ApiKeyPermissions`) or the user's role (`auth.rbac`)
+     * does not allow. Returns a constraint when the role allows only the user's own account.
+     */
+    private checkGrant;
     /** The query constraint read access adds, or `undefined` when there is none. Throws when denied. */
     private readWhere;
     private checkDocumentAccess;
     private checkGlobalAccess;
     private fieldChecker;
+    /**
+     * Refuses filtering or sorting by fields the caller may not read: the results would tell
+     * their values. Checks each field along a dotted path, through groups, arrays and blocks.
+     */
+    private checkQueryFields;
+    /** `checkGrant` for one document: a role limited to its own documents must own it. */
+    private checkDocumentGrant;
     /** Runs afterRead hooks, populates relationships and removes what the caller may not see. */
     private output;
     /** Creates a document: access, input filtering, hooks, validation, then afterChange. */
@@ -1502,6 +1708,11 @@ interface CollectionAdmin extends ContainerAdmin {
      */
     readonly group?: 'settings';
     readonly list?: CollectionListAdmin;
+    /**
+     * With `auth.rbac`: the relationship field to `users` that names a document's owner, e.g.
+     * `author`, for roles given "own documents only". Default: who created it (`createdBy`).
+     */
+    readonly ownerField?: string;
 }
 interface CollectionListAdmin {
     /**
@@ -1603,6 +1814,8 @@ interface DashboardWidget {
     readonly component: AdminComponent;
     /** `half` (default): the side column, beside drafts and recent edits; `full`: below both. */
     readonly width?: 'half' | 'full';
+    /** Its name in Settings → Roles (`auth.rbac`). Default: the component's tag. */
+    readonly label?: Label;
     /** Who sees it. */
     readonly access?: AdminViewAccess;
 }
@@ -1679,8 +1892,16 @@ interface RoutesConfig {
     readonly api?: string;
 }
 interface AuthConfig {
-    /** Roles a user can have. Must include `admin`. Default `['admin', 'editor']`. */
+    /**
+     * Roles a user can have. Must include `admin`. Default `['admin', 'editor']`. With `rbac`, these
+     * are the roles that always exist; admins can add more in Settings → Roles.
+     */
     readonly roles?: readonly string[];
+    /**
+     * Roles and their permissions from the admin (Settings → Roles): admins tick what each role
+     * may do with each collection, global and admin page, on top of access rules. Default `false`.
+     */
+    readonly rbac?: boolean;
     /** Session lifetime in seconds. Default 7 days. */
     readonly tokenExpiration?: number;
     /** Failed logins allowed per email (and IP) within `lockWindow`. Default 5. */
@@ -2279,7 +2500,10 @@ interface AdminCollection {
         create: boolean;
         update: boolean;
         delete: boolean;
+        publish: boolean;
     };
+    /** With `auth.rbac`: the field naming a document's owner (`createdBy` or `admin.ownerField`). */
+    owner?: string;
 }
 interface AdminGlobal {
     slug: string;
@@ -2297,6 +2521,7 @@ interface AdminGlobal {
     permissions: {
         read: boolean;
         update: boolean;
+        publish: boolean;
     };
 }
 /** A page of its own in the admin (`admin.pages`) that this user may open. */
@@ -2330,11 +2555,21 @@ interface AdminSchema {
     modules: string[];
     /** Files can be uploaded from links (`upload.fromURL`). */
     uploadFromURL: boolean;
-    /** For admins: which saved deliveries the admin can show (webhooks, emails). */
+    /** Which saved deliveries the admin can show (webhooks, emails), for users who may see them. */
     deliveries?: {
         webhook: boolean;
         email: boolean;
     };
+    /** Admin pages this user may open: Settings → Backups, Email, Roles; deliveries; the status panel. */
+    views: {
+        status: boolean;
+        deliveries: boolean;
+        backups: boolean;
+        email: boolean;
+        roles: boolean;
+    };
+    /** Roles from the admin are on (`auth.rbac`): documents have owners. */
+    rbac: boolean;
     /** Pages this user may open (`admin.pages`). */
     pages: AdminPageRef[];
     /** Dashboard panels this user may see (`admin.dashboard`). */
@@ -2433,4 +2668,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 AdminSchema, type AdminStatus, type AdminViewAccess, type AdminWebhookDelivery, type AdminWidgetRef, type AfterChangeHook, type AfterDeleteHook, type AfterReadHook, type ApiKeyContext, type ApiKeyGlobalOperation, type ApiKeyOperation, type ApiKeyPermissions, type ArrayField, Auth, type AuthConfig, type AuthUser, BUILTIN_COLLECTIONS, type BackupState, type BackupsConfig, type BeforeChangeHook, type BeforeDeleteHook, type BeforeValidateHook, type Block, type BlocksField, type BooleanField, type BuiltinApiKeysCollection, type BuiltinMediaCollection, type BuiltinUsersCollection, type BundleHints, CONFIG_FILE_NAMES, CSRF_COOKIE, CSRF_HEADER, type CliCommand, type CollectionAccess, type CollectionAdmin, type CollectionConfig, type CollectionDocument, type CollectionHooks, type CollectionListAdmin, type CollectionSlug, type Config, ConfigError, type ConfigIssue, type ContainerAdmin, type CopyProgress, type CopyResult, type CreateEasyCMSOptions, type CreateInput, type CreateMigrationResult, type CustomField, type CustomFieldTypes, DEFAULT_ADMIN_PATH, DEFAULT_API_PATH, DEFAULT_DEPTH, DEFAULT_MAX_FILE_SIZE, DEFAULT_MAX_VERSIONS, DEFAULT_PASSWORD_EMAILS, DEFAULT_TOKEN_EXPIRATION, type DashboardWidget, type Database, type DatabaseAdapter, type DatabaseInitArgs, type DatabaseTransfer, type DateField, type DeliveryKind, type DeliveryState, type DepthOptions, type DocumentOf, EXTENSIONS, EasyCMS, EasyCMSError, type EmailAdapter, type EmailCheck, type EmailField, type EmailMessage, type EmailSetting, type Endpoint, type EndpointRequest, FIELD_TYPES, FIELD_TYPE_BASES, type Field, type FieldAccess, type FieldAccessFn, type FieldAdmin, type FieldError, type FieldType, type FieldTypeBase, type FieldTypeDefinition, type FieldTypeValidateContext, type FieldValidate, type FieldValidateContext, type FieldValue, type FieldsInput, type FieldsValue, type FilterOptions, type FilterOptionsArgs, type FindArgs, type FindOptions, ForbiddenError, type GlobalAccess, type GlobalConfig, type GlobalDocument, type GlobalHooks, type GlobalInput, type GlobalSlug, type GroupField, type ID, INTERNAL_COLLECTIONS, type ImageSize, type InferCollection, type InferGlobal, type JsonField, type Label, type LivePreview, type LoadConfigOptions, type LocalStorageOptions, type LocalizationConfig, type Logger, type LoginArgs, MAX_DEPTH, MEDIA, MIN_PASSWORD_LENGTH, MIN_SECRET_LENGTH, type MediaDocument, type MediaSize, type MigrationInfo, NotFoundError, type NumberField, type Operation, type PaginatedDocs, type PasswordEmail, type PasswordEmailArgs, type PasswordEmailFn, type PasswordLinkOptions, PayloadTooLargeError, type Plugin, type PluginInfo, type PluginTypes, type PreviewTarget, type PreviewURL, QueryError, type RawDocument, type ReadOptions, type RelationshipField, type ResolvedConfig, type RestHandler, type RestHandlerOptions, type RichTextDocument, type RichTextField, type Role, type RoutesConfig, SESSION_COOKIE, type ScheduledJob, SchemaError, type SchemaMode, type SelectField, type SelectOption, type Session, type SlugField, type SlugOf, type StorageAdapter, type StoredFile, type TextField, type TextareaField, TooManyRequestsError, type TypedPlugin, UnauthorizedError, type UpdateInput, type UpdateOptions, type UploadConfig, type UploadField, type UploadFromURLConfig, VERSION, ValidationError, type Version, type VersionSummary, type VersionsConfig, WEBHOOK_EVENTS, type WebhookConfig, type WebhookEvent, type WebhookPayload, type Where, type WhereOperators, anyone, applyDefaults, applyPlugins, configSignature, consoleEmail, consoleLogger, copyDatabase, createEasyCMS, createRestHandler, createRootEndpointHandler, defineConfig, defineFieldType, definePlugin, fillMissing, findConfigFile, generateSlugs, generateTypes, hasRows, hashPassword, imageDimensions, importConfig, isAdmin, isHasMany, isLoggedIn, keyAllows, loadConfig, localStorage, mergeForUpdate, mimeAllowed, mimeAllowedBy, parseId, populate, readCookie, resolveAdminModule, resolveConfig, rowFields, silentLogger, singularize, slugify, sniffMimeType, validateConfig, validateFields, verifyPassword, writeBackupFile };
+export { ADMIN_ICONS, API_KEYS, API_KEY_GLOBAL_OPERATIONS, API_KEY_OPERATIONS, type Access, type AccessArgs, type AccessOptions, type AdminAttention, type AdminBackup, type AdminBackups, type AdminBrand, type AdminCollection, type AdminComponent, type AdminComponentRef, type AdminConfig, type AdminDeliveries, type AdminDelivery, type AdminEmail, type AdminEmailDelivery, type AdminField, type AdminGlobal, type AdminIcon, type AdminLocale, type AdminPage, type AdminPageRef, type AdminRole, type AdminRoleChange, type AdminRoleField, type AdminRoleTarget, type AdminRoleView, type AdminRoles, type AdminSchema, type AdminStatus, type AdminViewAccess, type AdminWebhookDelivery, type AdminWidgetRef, type AfterChangeHook, type AfterDeleteHook, type AfterReadHook, type ApiKeyContext, type ApiKeyGlobalOperation, type ApiKeyOperation, type ApiKeyPermissions, type ArrayField, Auth, type AuthConfig, type AuthUser, BUILTIN_COLLECTIONS, type BackupState, type BackupsConfig, type BeforeChangeHook, type BeforeDeleteHook, type BeforeValidateHook, type Block, type BlocksField, type BooleanField, type BuiltinApiKeysCollection, type BuiltinMediaCollection, type BuiltinUsersCollection, type BundleHints, CONFIG_FILE_NAMES, CSRF_COOKIE, CSRF_HEADER, type CliCommand, type CollectionAccess, type CollectionAdmin, type CollectionConfig, type CollectionDocument, type CollectionHooks, type CollectionListAdmin, type CollectionSlug, type Config, ConfigError, type ConfigIssue, type ContainerAdmin, type CopyProgress, type CopyResult, type CreateEasyCMSOptions, type CreateInput, type CreateMigrationResult, type CustomField, type CustomFieldTypes, DEFAULT_ADMIN_PATH, DEFAULT_API_PATH, DEFAULT_DEPTH, DEFAULT_MAX_FILE_SIZE, DEFAULT_MAX_VERSIONS, DEFAULT_PASSWORD_EMAILS, DEFAULT_TOKEN_EXPIRATION, type DashboardWidget, type Database, type DatabaseAdapter, type DatabaseInitArgs, type DatabaseTransfer, type DateField, type DeliveryKind, type DeliveryState, type DepthOptions, type DocumentOf, EXTENSIONS, EasyCMS, EasyCMSError, type EmailAdapter, type EmailCheck, type EmailField, type EmailMessage, type EmailSetting, type Endpoint, type EndpointRequest, FIELD_TYPES, FIELD_TYPE_BASES, type Field, type FieldAccess, type FieldAccessFn, type FieldAdmin, type FieldError, type FieldRule, type FieldType, type FieldTypeBase, type FieldTypeDefinition, type FieldTypeValidateContext, type FieldValidate, type FieldValidateContext, type FieldValue, type FieldsInput, type FieldsValue, type FilterOptions, type FilterOptionsArgs, type FindArgs, type FindOptions, ForbiddenError, type GlobalAccess, type GlobalConfig, type GlobalDocument, type GlobalHooks, type GlobalInput, type GlobalSlug, type GroupField, type ID, INTERNAL_COLLECTIONS, type ImageSize, type InferCollection, type InferGlobal, type JsonField, type Label, type LivePreview, type LoadConfigOptions, type LocalStorageOptions, type LocalizationConfig, type Logger, type LoginArgs, MAX_DEPTH, MEDIA, MIN_PASSWORD_LENGTH, MIN_SECRET_LENGTH, type MediaDocument, type MediaSize, type MigrationInfo, NotFoundError, type NumberField, type Operation, type PaginatedDocs, type PasswordEmail, type PasswordEmailArgs, type PasswordEmailFn, type PasswordLinkOptions, PayloadTooLargeError, type Plugin, type PluginInfo, type PluginTypes, type PreviewTarget, type PreviewURL, QueryError, ROLE_OPERATIONS, type RawDocument, type ReadOptions, type RelationshipField, type ResolvedConfig, type RestHandler, type RestHandlerOptions, type RichTextDocument, type RichTextField, type Role, type RoleOperation, type RolePermissions, Roles, type RoutesConfig, SESSION_COOKIE, type ScheduledJob, SchemaError, type SchemaMode, type SelectField, type SelectOption, type Session, type SlugField, type SlugOf, type StorageAdapter, type StoredFile, type TextField, type TextareaField, TooManyRequestsError, type TypedPlugin, UnauthorizedError, type UpdateInput, type UpdateOptions, type UploadConfig, type UploadField, type UploadFromURLConfig, VERSION, ValidationError, type Version, type VersionSummary, type VersionsConfig, WEBHOOK_EVENTS, type WebhookConfig, type WebhookEvent, type WebhookPayload, type Where, type WhereOperators, anyone, applyDefaults, applyPlugins, configSignature, consoleEmail, consoleLogger, copyDatabase, createEasyCMS, createRestHandler, createRootEndpointHandler, defineConfig, defineFieldType, definePlugin, fillMissing, findConfigFile, generateSlugs, generateTypes, hasRows, hashPassword, imageDimensions, importConfig, isAdmin, isHasMany, isLoggedIn, keyAllows, loadConfig, localStorage, mergeForUpdate, mimeAllowed, mimeAllowedBy, parseId, populate, readCookie, resolveAdminModule, resolveConfig, rowFields, silentLogger, singularize, slugify, sniffMimeType, validateConfig, validateFields, verifyPassword, writeBackupFile };