@easy-cms/core 0.31.0 → 0.33.0

package/dist/index.d.ts

@@ -187,6 +187,8 @@ interface Database {
     readonly backup?: ((file: string) => Promise<void>) | undefined;
     /** Raw table access for copying a whole database to another (`easy-cms copy`). */
     readonly transfer?: DatabaseTransfer | undefined;
+    /** The prefix of its tables (`tablePrefix`), so a copy (a backup) can use the same. */
+    readonly tablePrefix?: string | undefined;
     destroy(): Promise<void>;
 }
 /**
@@ -739,6 +741,137 @@ 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];
+/**
+ * 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[];
+}
+/** 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 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;
+}
+/** 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[];
+    })[];
+    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;
+    readonly enabled: boolean;
+    private readonly versions;
+    private cache;
+    private synced;
+    constructor(config: ResolvedConfig, db: Database);
+    /**
+     * 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>;
+    /** 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;
+    /** 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;
+    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;
@@ -880,6 +1013,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;
@@ -1099,8 +1234,11 @@ 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;
@@ -1601,6 +1739,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;
 }
@@ -1677,8 +1817,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. */
@@ -1803,6 +1951,27 @@ type TypedPlugin<T extends PluginTypes> = Plugin & {
  * ```
  */
 declare function definePlugin<const T extends PluginTypes = Record<never, never>>(plugin: Plugin, info?: PluginInfo): TypedPlugin<T>;
+/** Database backups (Settings → Backups): one compressed SQLite file each. */
+interface BackupsConfig {
+    /** Back up automatically every day or week. Default: only by hand. */
+    readonly every?: 'day' | 'week';
+    /** When, as `HH:MM` in the server's time zone. Default `03:00`. */
+    readonly at?: string;
+    /** How many finished backups to keep; older ones are deleted. Default 7. */
+    readonly keep?: number;
+    /** Folder for the default local storage, from the project root. Default `backups`. Never served publicly. */
+    readonly dir?: string;
+    /** Where backups are stored instead, e.g. `s3Storage()` with a private bucket. */
+    readonly storage?: StorageAdapter;
+    /**
+     * For Postgres: the SQLite adapter that writes the backup file, `sqlite` from
+     * `@easy-cms/db-sqlite`. SQLite databases back themselves up and don't need it.
+     */
+    readonly sqlite?: (options: {
+        url: string;
+        tablePrefix?: string;
+    }) => DatabaseAdapter;
+}
 interface Config {
     /** Signs sessions. At least 32 characters; read it from `process.env.EASY_CMS_SECRET`. */
     readonly secret: string;
@@ -1858,6 +2027,11 @@ interface Config {
      * database and retried until sent.
      */
     readonly email?: EmailAdapter;
+    /**
+     * Database backups, made on a schedule and from the admin (Settings → Backups). Without
+     * `every`, admins can still back up by hand.
+     */
+    readonly backups?: BackupsConfig;
     readonly plugins?: readonly Plugin[];
 }
 /** The config after plugins ran, validation passed and defaults were applied. */
@@ -1917,6 +2091,46 @@ declare function hashPassword(password: string): Promise<string>;
 /** Checks a password against a hash in constant time. Malformed hashes never match. */
 declare function verifyPassword(password: string, stored: string): Promise<boolean>;
 
+type BackupState = 'pending' | 'running' | 'done' | 'failed';
+/** One backup as the admin shows it (`GET <api>/admin/backups`). */
+interface AdminBackup {
+    id: ID;
+    state: BackupState;
+    trigger: 'manual' | 'scheduled';
+    /** The file's name, e.g. `my-site-2026-10-04-0300.db.gz`. */
+    filename: string | null;
+    /** Bytes, compressed. */
+    size: number | null;
+    startedAt: string | null;
+    finishedAt: string | null;
+    error: string | null;
+    /** Who started it (manual backups). */
+    author: string | null;
+    downloadedBy: string | null;
+    downloadedAt: string | null;
+}
+/** Settings → Backups (`GET <api>/admin/backups`). */
+interface AdminBackups {
+    settings: {
+        every: 'day' | 'week' | null;
+        at: string;
+        keep: number;
+        /** The storage adapter's name, e.g. `local` or `s3`. */
+        storage: string;
+        /** The folder, for local storage. */
+        dir: string | null;
+        database: string;
+        /** Why backups can't be made with this setup, if they can't. */
+        unavailable: string | null;
+    };
+    backups: AdminBackup[];
+}
+/**
+ * Writes a consistent copy of the database to `file` as SQLite, while the CMS keeps running:
+ * SQLite copies itself; other databases are copied into a new SQLite file (`backups.sqlite`).
+ */
+declare function writeBackupFile<C extends Config>(cms: EasyCMS<C>, file: string): Promise<void>;
+
 declare const MEDIA = "media";
 /** Collections Easy CMS uses internally. Not exposed over REST or in the admin UI. */
 declare const INTERNAL_COLLECTIONS: ReadonlySet<string>;
@@ -2211,6 +2425,7 @@ interface AdminCollection {
         create: boolean;
         update: boolean;
         delete: boolean;
+        publish: boolean;
     };
 }
 interface AdminGlobal {
@@ -2229,6 +2444,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. */
@@ -2262,11 +2478,19 @@ 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;
+    };
     /** Pages this user may open (`admin.pages`). */
     pages: AdminPageRef[];
     /** Dashboard panels this user may see (`admin.dashboard`). */
@@ -2298,6 +2522,12 @@ type AdminAttention =
 /** In production without `serverURL`: links in emails can't be made. */
  | {
     id: 'no-server-url';
+}
+/** The last scheduled backup failed, or none finished in two periods (`backups.every`). */
+ | {
+    id: 'backups';
+    failed: boolean;
+    lastDone: string | null;
 };
 /** What the dashboard shows admins (`GET <api>/admin/status`). */
 interface AdminStatus {
@@ -2359,4 +2589,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 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 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 };
+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 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 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 };