@easy-cms/core 0.35.0 → 0.36.0

package/dist/index.d.ts

@@ -56,328 +56,6 @@ declare const anyone: Access;
 declare const isLoggedIn: Access;
 declare const isAdmin: Access;
 
-/** What the email functions in `auth.emails` receive. */
-interface PasswordEmailArgs {
-    readonly user: AuthUser;
-    /** The page that sets the password; absent for `passwordChanged`. */
-    readonly url?: string;
-    /** The admin language for the text: `en` or `th`. */
-    readonly locale: string;
-    /** When the link stops working. */
-    readonly expiresAt?: Date;
-    /**
-     * Invitations when passwords are off (`auth.password: false`): the providers to sign in with,
-     * e.g. `['Google']`; `url` is then the login page.
-     */
-    readonly sso?: readonly string[];
-}
-/** An email's content: a subject, and text and/or HTML. */
-interface PasswordEmail {
-    readonly subject: string;
-    readonly text: string;
-    readonly html?: string;
-}
-type PasswordEmailFn = (args: PasswordEmailArgs) => PasswordEmail | Promise<PasswordEmail>;
-/** The default emails, in English and Thai. */
-declare const DEFAULT_PASSWORD_EMAILS: {
-    resetPassword: PasswordEmailFn;
-    invite: PasswordEmailFn;
-    passwordChanged: PasswordEmailFn;
-};
-
-/**
- * Signing in to the admin with an outside account (`auth.providers`): Google, Microsoft, GitHub
- * or any OpenID Connect provider. `@easy-cms/auth-oauth` makes these; Easy CMS runs the rest
- * (the redirect, matching users, sessions).
- */
-/** Values bound to one sign-in, checked when the browser comes back. */
-interface AuthProviderRequest {
-    /** Where the provider sends the browser back: `<serverURL><api>/auth/<id>/callback`. */
-    readonly redirectUri: string;
-    readonly state: string;
-    /** For PKCE: the provider gets its S256 challenge. */
-    readonly codeVerifier: string;
-    /** For OpenID Connect: must come back in the ID token. */
-    readonly nonce: string;
-}
-/** Who signed in, as the provider says. */
-interface AuthProviderProfile {
-    /** The provider's stable id for the account (`sub`). */
-    readonly subject: string;
-    readonly email: string | null;
-    /** The provider vouches for the email. Only verified emails are matched to users. */
-    readonly emailVerified: boolean;
-    readonly name?: string | undefined;
-}
-interface AuthProvider {
-    /** In URLs and stored identities, e.g. `google`: lowercase letters, digits and `-`. */
-    readonly id: string;
-    /** On the sign-in button, e.g. `Google`. */
-    readonly name: string;
-    /** The button's icon in the admin. Default `key`. */
-    readonly icon?: 'google' | 'microsoft' | 'github' | 'key';
-    /** The provider's page to send the browser to. */
-    authorizationURL(request: AuthProviderRequest): Promise<URL>;
-    /**
-     * After the browser comes back to `redirectUri` (`url`, with its query): checks the response
-     * and exchanges the code. Throws when anything does not check out.
-     */
-    callback(request: AuthProviderRequest & {
-        readonly url: URL;
-    }): Promise<AuthProviderProfile>;
-    /** For Settings → SSO: what it connects to, never secrets. */
-    describe?(): Readonly<Record<string, string>>;
-}
-
-interface Logger {
-    info(message: string): void;
-    warn(message: string): void;
-    error(message: string): void;
-}
-declare const consoleLogger: Logger;
-declare const silentLogger: Logger;
-
-/** A document as stored: relationships and uploads are ids, never populated. */
-type RawDocument = Record<string, unknown> & {
-    id: ID;
-};
-interface PaginatedDocs<T> {
-    docs: T[];
-    totalDocs: number;
-    limit: number;
-    page: number;
-    totalPages: number;
-    hasNextPage: boolean;
-    hasPrevPage: boolean;
-}
-/**
- * How the adapter treats the database schema on startup.
- * - `push`: apply schema changes directly (development).
- * - `verify`: fail if migrations are pending or the config changed without a migration (production).
- * - `skip`: do nothing (used by the migration CLI).
- */
-type SchemaMode = 'push' | 'verify' | 'skip';
-interface DatabaseInitArgs {
-    readonly config: ResolvedConfig;
-    /** Project root; relative paths (database file, migrations) resolve from here. */
-    readonly cwd: string;
-    readonly schema: SchemaMode;
-    readonly logger: Logger;
-    /** Whether the process can prompt the user (the CLI in a terminal). */
-    readonly interactive?: boolean;
-}
-interface FindArgs {
-    readonly collection: string;
-    readonly where?: Where | undefined;
-    /** Field paths; prefix with `-` for descending. */
-    readonly sort: readonly string[];
-    /** `0` returns every matching document. */
-    readonly limit: number;
-    readonly page: number;
-}
-interface MigrationInfo {
-    readonly name: string;
-    readonly applied: boolean;
-}
-interface CreateMigrationResult {
-    readonly name: string;
-    readonly file: string;
-    readonly statements: readonly string[];
-}
-/** A connected database bound to one config. Returned by `DatabaseAdapter.init`. */
-interface Database {
-    find(args: FindArgs): Promise<PaginatedDocs<RawDocument>>;
-    findById(args: {
-        collection: string;
-        id: ID;
-    }): Promise<RawDocument | null>;
-    /** Documents of one collection by id, in any order. Used to populate relationships. */
-    findByIds(args: {
-        collection: string;
-        ids: readonly ID[];
-    }): Promise<RawDocument[]>;
-    count(args: {
-        collection: string;
-        where?: Where | undefined;
-    }): Promise<number>;
-    /** `data` holds every field, `createdAt` and `updatedAt`. Runs in one transaction. */
-    create(args: {
-        collection: string;
-        data: Record<string, unknown>;
-    }): Promise<RawDocument>;
-    /** `data` holds the whole document after merging. Runs in one transaction. */
-    update(args: {
-        collection: string;
-        id: ID;
-        data: Record<string, unknown>;
-    }): Promise<RawDocument>;
-    delete(args: {
-        collection: string;
-        id: ID;
-    }): Promise<void>;
-    findGlobal(args: {
-        slug: string;
-    }): Promise<Record<string, unknown> | null>;
-    updateGlobal(args: {
-        slug: string;
-        data: Record<string, unknown>;
-    }): Promise<Record<string, unknown>>;
-    /** Writes a migration file for the difference between the config and the latest migration. `null` when nothing changed. */
-    createMigration(args: {
-        name: string;
-    }): Promise<CreateMigrationResult | null>;
-    /** Applies pending migrations in order. Returns the names applied. */
-    migrate(): Promise<string[]>;
-    migrationStatus(): Promise<MigrationInfo[]>;
-    /**
-     * Copies the database to `file` (an absolute path) while it is in use, when the database can
-     * do that itself (SQLite). Others (Postgres) leave it out; use their own tools.
-     */
-    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>;
-}
-/**
- * Reads and writes stored rows as they are, ids and hidden fields included, bypassing validation
- * and hooks. Only for moving a database: `copyDatabase()`.
- */
-interface DatabaseTransfer {
-    /**
-     * Identifies the tables and columns the config produces, the same for every database kind.
-     * Two databases can be copied into each other when their hashes match.
-     */
-    readonly schemaHash: string;
-    /** Every table, in an order that is safe to write. */
-    tables(): string[];
-    count(table: string): Promise<number>;
-    /** Rows in a stable order (by primary key), `offset` and `limit` for batches. */
-    read(table: string, offset: number, limit: number): Promise<Record<string, unknown>[]>;
-    write(table: string, rows: readonly Record<string, unknown>[]): Promise<void>;
-    /** After all writes, e.g. moves id sequences past the copied ids so new documents fit. */
-    finish(): Promise<void>;
-}
-/** What `sqlite()` / `postgres()` return and what `config.db` holds. */
-interface DatabaseAdapter {
-    readonly name: string;
-    init(args: DatabaseInitArgs): Promise<Database>;
-    /** Hints for bundlers (Nitro, Next.js output tracing) about files static analysis cannot find. */
-    readonly bundle?: BundleHints;
-}
-interface BundleHints {
-    /** Absolute paths of files to ship with the server build, e.g. native binaries loaded dynamically. */
-    readonly traceInclude: readonly string[];
-}
-
-/** An email to send. Addresses may be `name <address>`. */
-interface EmailMessage {
-    readonly to: string | readonly string[];
-    readonly cc?: string | readonly string[];
-    readonly bcc?: string | readonly string[];
-    /** Default: the adapter's `from`. */
-    readonly from?: string;
-    readonly replyTo?: string;
-    readonly subject: string;
-    readonly html?: string;
-    readonly text?: string;
-}
-/**
- * Sends email for Easy CMS and its plugins (form notifications, and more later). Set one in
- * the config as `email`, e.g. `smtp()` from `@easy-cms/email-smtp`, or `consoleEmail()` in
- * development. Throw to report a failure: the message is retried later.
- */
-interface EmailAdapter {
-    /** What sends the email, e.g. `smtp`; shown to admins on the dashboard (System). */
-    readonly name?: string;
-    /** The sender when a message has none, e.g. `Easy CMS <no-reply@example.com>`. */
-    readonly from?: string | undefined;
-    send(message: EmailMessage & {
-        readonly from: string;
-    }): Promise<void>;
-    /**
-     * The settings in use, shown to admins on Settings → Email. Never return secrets: say whether
-     * a password is set, not what it is.
-     */
-    describe?(): readonly EmailSetting[];
-    /** Checks the connection without sending (Settings → Email); throws with the reason. */
-    verify?(): Promise<void>;
-}
-/** One setting an email adapter shows to admins (`describe()`). */
-interface EmailSetting {
-    /**
-     * `host`, `port`, `secure`, `user`, `password`, `from` and `delivery` (`log`: printed, not sent)
-     * are translated in the admin; others are shown as they are.
-     */
-    readonly key: string;
-    /** `null`: not set. */
-    readonly value: string | null;
-    /** Where it comes from, e.g. `SMTP_HOST` or `smtp({ host })`. */
-    readonly source?: string;
-}
-/** Prints emails to the log instead of sending them: for development and tests. */
-declare function consoleEmail(options?: {
-    from?: string;
-    log?: (text: string) => void;
-}): EmailAdapter & {
-    readonly sent: (EmailMessage & {
-        from: string;
-    })[];
-};
-
-interface ConfigIssue {
-    /** Where the problem is, e.g. `collections.posts.fields.slug.from`. */
-    readonly path: string;
-    readonly message: string;
-    /** How to fix it. */
-    readonly hint?: string;
-}
-declare class ConfigError extends Error {
-    readonly issues: readonly ConfigIssue[];
-    constructor(issues: readonly ConfigIssue[]);
-    static format(issues: readonly ConfigIssue[]): string;
-}
-/** Base class for errors that map to an HTTP status in the REST API. */
-declare class EasyCMSError extends Error {
-    readonly status: number;
-    constructor(message: string, status: number);
-}
-interface FieldError {
-    /** Dotted path, e.g. `links.0.url`. */
-    readonly field: string;
-    readonly message: string;
-}
-declare class ValidationError extends EasyCMSError {
-    readonly errors: readonly FieldError[];
-    constructor(collection: string, errors: readonly FieldError[]);
-}
-declare class NotFoundError extends EasyCMSError {
-    constructor(collection: string, id: unknown);
-}
-/** A bad `where`, `sort` or unknown collection/global. */
-declare class QueryError extends EasyCMSError {
-    constructor(message: string);
-}
-/** The database schema does not match the config (pending or missing migrations). */
-declare class SchemaError extends EasyCMSError {
-    constructor(message: string);
-}
-/** Not logged in, or the session is invalid. */
-declare class UnauthorizedError extends EasyCMSError {
-    constructor(message?: string);
-}
-/** Logged in, but not allowed to do this. */
-declare class ForbiddenError extends EasyCMSError {
-    constructor(message?: string);
-}
-declare class TooManyRequestsError extends EasyCMSError {
-    constructor(message: string);
-}
-declare class PayloadTooLargeError extends EasyCMSError {
-    constructor(message: string);
-}
-
 /** What a preview token opens: one document of a collection, or one global. */
 type PreviewTarget = {
     readonly collection: string;
@@ -553,42 +231,239 @@ declare class Auth {
         ip?: string | undefined;
     }): Promise<void>;
     /**
-     * Emails a user a link to set their password: an invitation if they have none yet, else a
-     * reset link. For admins (the REST API checks the role). Returns which one was sent.
+     * Emails a user a link to set their password: an invitation if they have none yet, else a
+     * reset link. For admins (the REST API checks the role). Returns which one was sent.
+     */
+    sendPasswordLink(userId: ID, options?: PasswordLinkOptions): Promise<PasswordPurpose>;
+    /** The user and purpose of a valid, unused password link, or `null`. */
+    checkPasswordToken(token: string): Promise<{
+        user: AuthUser;
+        purpose: PasswordPurpose;
+    } | null>;
+    /**
+     * Sets the password from a link, ends every session of the account and starts one here.
+     * Throws `ValidationError` when the link expired or was used, or the password is too short.
+     */
+    resetPassword(args: {
+        token: string;
+        password: string;
+        ip?: string | undefined;
+        locale?: string | undefined;
+    }): Promise<Session & {
+        purpose: PasswordPurpose;
+    }>;
+    private passwordTokenUser;
+    private mailPasswordLink;
+    private localeOf;
+    private findByEmail;
+    /** The owner of an API key, limited by the key; `null` when unknown, expired or disabled. */
+    private verifyApiKey;
+    private startSession;
+    private findSession;
+    private toAuthUser;
+    private deleteExpiredSessions;
+    private windowStart;
+    private checkRateLimit;
+    private recordFailure;
+    private clearFailures;
+}
+
+interface Logger {
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+}
+declare const consoleLogger: Logger;
+declare const silentLogger: Logger;
+
+/** A document as stored: relationships and uploads are ids, never populated. */
+type RawDocument = Record<string, unknown> & {
+    id: ID;
+};
+interface PaginatedDocs<T> {
+    docs: T[];
+    totalDocs: number;
+    limit: number;
+    page: number;
+    totalPages: number;
+    hasNextPage: boolean;
+    hasPrevPage: boolean;
+}
+/**
+ * How the adapter treats the database schema on startup.
+ * - `push`: apply schema changes directly (development).
+ * - `verify`: fail if migrations are pending or the config changed without a migration (production).
+ * - `skip`: do nothing (used by the migration CLI).
+ */
+type SchemaMode = 'push' | 'verify' | 'skip';
+interface DatabaseInitArgs {
+    readonly config: ResolvedConfig;
+    /** Project root; relative paths (database file, migrations) resolve from here. */
+    readonly cwd: string;
+    readonly schema: SchemaMode;
+    readonly logger: Logger;
+    /** Whether the process can prompt the user (the CLI in a terminal). */
+    readonly interactive?: boolean;
+}
+interface FindArgs {
+    readonly collection: string;
+    readonly where?: Where | undefined;
+    /** Field paths; prefix with `-` for descending. */
+    readonly sort: readonly string[];
+    /** `0` returns every matching document. */
+    readonly limit: number;
+    readonly page: number;
+}
+interface MigrationInfo {
+    readonly name: string;
+    readonly applied: boolean;
+}
+interface CreateMigrationResult {
+    readonly name: string;
+    readonly file: string;
+    readonly statements: readonly string[];
+}
+/** A connected database bound to one config. Returned by `DatabaseAdapter.init`. */
+interface Database {
+    find(args: FindArgs): Promise<PaginatedDocs<RawDocument>>;
+    findById(args: {
+        collection: string;
+        id: ID;
+    }): Promise<RawDocument | null>;
+    /** Documents of one collection by id, in any order. Used to populate relationships. */
+    findByIds(args: {
+        collection: string;
+        ids: readonly ID[];
+    }): Promise<RawDocument[]>;
+    count(args: {
+        collection: string;
+        where?: Where | undefined;
+    }): Promise<number>;
+    /** `data` holds every field, `createdAt` and `updatedAt`. Runs in one transaction. */
+    create(args: {
+        collection: string;
+        data: Record<string, unknown>;
+    }): Promise<RawDocument>;
+    /** `data` holds the whole document after merging. Runs in one transaction. */
+    update(args: {
+        collection: string;
+        id: ID;
+        data: Record<string, unknown>;
+    }): Promise<RawDocument>;
+    delete(args: {
+        collection: string;
+        id: ID;
+    }): Promise<void>;
+    findGlobal(args: {
+        slug: string;
+    }): Promise<Record<string, unknown> | null>;
+    updateGlobal(args: {
+        slug: string;
+        data: Record<string, unknown>;
+    }): Promise<Record<string, unknown>>;
+    /** Writes a migration file for the difference between the config and the latest migration. `null` when nothing changed. */
+    createMigration(args: {
+        name: string;
+    }): Promise<CreateMigrationResult | null>;
+    /** Applies pending migrations in order. Returns the names applied. */
+    migrate(): Promise<string[]>;
+    migrationStatus(): Promise<MigrationInfo[]>;
+    /**
+     * Copies the database to `file` (an absolute path) while it is in use, when the database can
+     * do that itself (SQLite). Others (Postgres) leave it out; use their own tools.
+     */
+    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>;
+}
+/**
+ * Reads and writes stored rows as they are, ids and hidden fields included, bypassing validation
+ * and hooks. Only for moving a database: `copyDatabase()`.
+ */
+interface DatabaseTransfer {
+    /**
+     * Identifies the tables and columns the config produces, the same for every database kind.
+     * Two databases can be copied into each other when their hashes match.
+     */
+    readonly schemaHash: string;
+    /** Every table, in an order that is safe to write. */
+    tables(): string[];
+    count(table: string): Promise<number>;
+    /** Rows in a stable order (by primary key), `offset` and `limit` for batches. */
+    read(table: string, offset: number, limit: number): Promise<Record<string, unknown>[]>;
+    write(table: string, rows: readonly Record<string, unknown>[]): Promise<void>;
+    /** After all writes, e.g. moves id sequences past the copied ids so new documents fit. */
+    finish(): Promise<void>;
+}
+/** What `sqlite()` / `postgres()` return and what `config.db` holds. */
+interface DatabaseAdapter {
+    readonly name: string;
+    init(args: DatabaseInitArgs): Promise<Database>;
+    /** Hints for bundlers (Nitro, Next.js output tracing) about files static analysis cannot find. */
+    readonly bundle?: BundleHints;
+}
+interface BundleHints {
+    /** Absolute paths of files to ship with the server build, e.g. native binaries loaded dynamically. */
+    readonly traceInclude: readonly string[];
+}
+
+/** An email to send. Addresses may be `name <address>`. */
+interface EmailMessage {
+    readonly to: string | readonly string[];
+    readonly cc?: string | readonly string[];
+    readonly bcc?: string | readonly string[];
+    /** Default: the adapter's `from`. */
+    readonly from?: string;
+    readonly replyTo?: string;
+    readonly subject: string;
+    readonly html?: string;
+    readonly text?: string;
+}
+/**
+ * Sends email for Easy CMS and its plugins (form notifications, and more later). Set one in
+ * the config as `email`, e.g. `smtp()` from `@easy-cms/email-smtp`, or `consoleEmail()` in
+ * development. Throw to report a failure: the message is retried later.
+ */
+interface EmailAdapter {
+    /** What sends the email, e.g. `smtp`; shown to admins on the dashboard (System). */
+    readonly name?: string;
+    /** The sender when a message has none, e.g. `Easy CMS <no-reply@example.com>`. */
+    readonly from?: string | undefined;
+    send(message: EmailMessage & {
+        readonly from: string;
+    }): Promise<void>;
+    /**
+     * The settings in use, shown to admins on Settings → Email. Never return secrets: say whether
+     * a password is set, not what it is.
      */
-    sendPasswordLink(userId: ID, options?: PasswordLinkOptions): Promise<PasswordPurpose>;
-    /** The user and purpose of a valid, unused password link, or `null`. */
-    checkPasswordToken(token: string): Promise<{
-        user: AuthUser;
-        purpose: PasswordPurpose;
-    } | null>;
+    describe?(): readonly EmailSetting[];
+    /** Checks the connection without sending (Settings → Email); throws with the reason. */
+    verify?(): Promise<void>;
+}
+/** One setting an email adapter shows to admins (`describe()`). */
+interface EmailSetting {
     /**
-     * Sets the password from a link, ends every session of the account and starts one here.
-     * Throws `ValidationError` when the link expired or was used, or the password is too short.
+     * `host`, `port`, `secure`, `user`, `password`, `from` and `delivery` (`log`: printed, not sent)
+     * are translated in the admin; others are shown as they are.
      */
-    resetPassword(args: {
-        token: string;
-        password: string;
-        ip?: string | undefined;
-        locale?: string | undefined;
-    }): Promise<Session & {
-        purpose: PasswordPurpose;
-    }>;
-    private passwordTokenUser;
-    private mailPasswordLink;
-    private localeOf;
-    private findByEmail;
-    /** The owner of an API key, limited by the key; `null` when unknown, expired or disabled. */
-    private verifyApiKey;
-    private startSession;
-    private findSession;
-    private toAuthUser;
-    private deleteExpiredSessions;
-    private windowStart;
-    private checkRateLimit;
-    private recordFailure;
-    private clearFailures;
+    readonly key: string;
+    /** `null`: not set. */
+    readonly value: string | null;
+    /** Where it comes from, e.g. `SMTP_HOST` or `smtp({ host })`. */
+    readonly source?: string;
 }
+/** Prints emails to the log instead of sending them: for development and tests. */
+declare function consoleEmail(options?: {
+    from?: string;
+    log?: (text: string) => void;
+}): EmailAdapter & {
+    readonly sent: (EmailMessage & {
+        from: string;
+    })[];
+};
 
 type Simplify<T> = {
     [K in keyof T]: T[K];
@@ -979,11 +854,25 @@ declare class Roles {
     private readonly config;
     private readonly db;
     private readonly log?;
+    /** Writes to the audit log (`audit`). */
+    private readonly audit?;
     readonly enabled: boolean;
     private readonly versions;
     private cache;
     private synced;
-    constructor(config: ResolvedConfig, db: Database, log?: ((message: string) => void) | undefined);
+    constructor(config: ResolvedConfig, db: Database, log?: ((message: string) => void) | undefined, 
+    /** Writes to the audit log (`audit`). */
+    audit?: ((entry: {
+        action: string;
+        target: string;
+        doc: ID;
+        title: string;
+        changes?: {
+            field: string;
+            before?: unknown;
+            after?: unknown;
+        }[];
+    }) => Promise<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.
@@ -1220,6 +1109,8 @@ declare class EasyCMS<C extends Config = Config> {
     readonly cwd: string;
     /** Roles and their permissions (`auth.rbac`, Settings → Roles). */
     readonly roles: Roles;
+    /** Who did what (`audit`, Settings → Audit log). */
+    readonly audit: AuditLog;
     private readonly versions;
     private readonly webhooks;
     private readonly mailer;
@@ -1480,6 +1371,11 @@ declare class EasyCMS<C extends Config = Config> {
     private withDrafts;
     /** Sends webhook events for a change; `before` is the stored status before it, if any. */
     private emit;
+    /**
+     * Writes the audit log entry for a change (`audit`): publishing, unpublishing and restoring
+     * are told apart from other saves.
+     */
+    private audited;
     /** Records a version after a save, when the collection or global keeps versions. */
     private saveVersion;
     private hookArgs;
@@ -1703,6 +1599,257 @@ type Field = CustomField | TextField | TextareaField | NumberField | BooleanFiel
 type FieldType = Field['type'];
 declare const FIELD_TYPES: readonly ["text", "textarea", "number", "boolean", "date", "email", "json", "select", "slug", "richText", "upload", "relationship", "array", "group", "blocks"];
 
+/** Audit log settings (`audit`). */
+interface AuditConfig {
+    /** Days to keep entries; older ones are deleted. `0`: keep them all. Default 365. */
+    readonly keep?: number;
+    /** Keep the values before and after a change, not only which fields changed. Default `true`. */
+    readonly values?: boolean;
+    /** Failed logins within an hour that the dashboard warns about. Default 20. */
+    readonly failedLogins?: number;
+}
+/** A field that changed: values before and after, unless they are not kept. */
+interface AuditChange {
+    field: string;
+    before?: unknown;
+    after?: unknown;
+}
+/** One entry (`GET <api>/admin/audit`). */
+interface AuditEntry {
+    id: ID;
+    /** When, as an ISO date. */
+    at: string;
+    /** E.g. `create`, `update`, `publish`, `delete`, `login`, `login.failed`, `role.update`. */
+    action: string;
+    /** A collection slug, `global:<slug>`, or an area such as `auth`, `roles`, `backups`. */
+    target: string | null;
+    /** The document's id. */
+    doc: string | null;
+    /** The document's title then (kept after it is deleted). */
+    title: string | null;
+    actor: {
+        id: string | null;
+        email: string | null;
+        /** `user` (admin or REST), `api-key`, `system` (code), `scheduler`. */
+        via: string;
+        ip: string | null;
+        userAgent: string | null;
+    };
+    changes: AuditChange[] | null;
+    detail: Record<string, unknown> | null;
+}
+/** `GET <api>/admin/audit`: a page of entries, newest first. */
+interface AuditPage {
+    docs: AuditEntry[];
+    page: number;
+    totalPages: number;
+    totalDocs: number;
+}
+interface AuditFilter {
+    action?: string | null;
+    target?: string | null;
+    doc?: string | null;
+    /** An email, or part of one. */
+    actor?: string | null;
+    /** ISO dates. */
+    from?: string | null;
+    to?: string | null;
+}
+/** `POST <api>/admin/audit/verify`. */
+interface AuditVerification {
+    checked: number;
+    /** Entries whose signature does not match: changed after they were written. */
+    invalid: ID[];
+    /** Missing ids between entries: deleted entries, or (rarely) inserts that failed. */
+    gaps: number;
+    at: string;
+}
+/**
+ * The audit log (`audit` in the config): who did what, when, from where. Entries can't be
+ * changed through Easy CMS; each is signed with the secret, so changes in the database show.
+ * Available as `cms.audit`.
+ */
+declare class AuditLog {
+    private readonly cms;
+    /** Entries that could not be written since the server started. */
+    failures: number;
+    constructor(cms: EasyCMS);
+    get enabled(): boolean;
+    private get settings();
+    /**
+     * Writes an entry. The user defaults to the request's. Never throws: a failure is logged and
+     * counted, and the dashboard says so.
+     */
+    record(entry: {
+        action: string;
+        target?: string | null;
+        doc?: ID | null;
+        title?: string | null;
+        user?: AuthUser | null;
+        /** Who it was when there is no user, e.g. the email of a failed login. */
+        email?: string | null;
+        changes?: AuditChange[] | null;
+        detail?: Record<string, unknown> | null;
+    }): Promise<void>;
+    /**
+     * A change to a document or global: what changed between `before` and `after`. Internal
+     * collections (sessions, versions…) are not logged.
+     */
+    content(config: CollectionConfig | GlobalConfig, global: boolean, action: string, after: Record<string, unknown> | undefined, before: Record<string, unknown> | undefined, user: AuthUser | null): Promise<void>;
+    /** Fields whose stored value changed. Hidden ones never (the password only as "changed"). */
+    diff(fields: readonly Field[], before: Record<string, unknown>, after: Record<string, unknown>): AuditChange[];
+    list(filter: AuditFilter, page?: number): Promise<AuditPage>;
+    /** The filtered entries as CSV (the newest 10,000). */
+    csv(filter: AuditFilter): Promise<string>;
+    /** Checks every entry's signature, and that no ids are missing. */
+    verify(): Promise<AuditVerification>;
+    /**
+     * Daily upkeep from `runJobs`: deletes entries older than `keep` days, then verifies the log.
+     * Runs when the last check is more than a day old.
+     */
+    upkeep(now?: Date): Promise<void>;
+    /** What the dashboard warns about: many failed logins, entries not written, a failed check. */
+    attention(now?: Date): Promise<({
+        id: 'failed-logins';
+        count: number;
+    } | {
+        id: 'audit-failures';
+        count: number;
+    } | {
+        id: 'audit-tampered';
+        invalid: number;
+        at: string;
+    })[]>;
+    private sign;
+    private lastVerification;
+    private where;
+}
+
+/** What the email functions in `auth.emails` receive. */
+interface PasswordEmailArgs {
+    readonly user: AuthUser;
+    /** The page that sets the password; absent for `passwordChanged`. */
+    readonly url?: string;
+    /** The admin language for the text: `en` or `th`. */
+    readonly locale: string;
+    /** When the link stops working. */
+    readonly expiresAt?: Date;
+    /**
+     * Invitations when passwords are off (`auth.password: false`): the providers to sign in with,
+     * e.g. `['Google']`; `url` is then the login page.
+     */
+    readonly sso?: readonly string[];
+}
+/** An email's content: a subject, and text and/or HTML. */
+interface PasswordEmail {
+    readonly subject: string;
+    readonly text: string;
+    readonly html?: string;
+}
+type PasswordEmailFn = (args: PasswordEmailArgs) => PasswordEmail | Promise<PasswordEmail>;
+/** The default emails, in English and Thai. */
+declare const DEFAULT_PASSWORD_EMAILS: {
+    resetPassword: PasswordEmailFn;
+    invite: PasswordEmailFn;
+    passwordChanged: PasswordEmailFn;
+};
+
+/**
+ * Signing in to the admin with an outside account (`auth.providers`): Google, Microsoft, GitHub
+ * or any OpenID Connect provider. `@easy-cms/auth-oauth` makes these; Easy CMS runs the rest
+ * (the redirect, matching users, sessions).
+ */
+/** Values bound to one sign-in, checked when the browser comes back. */
+interface AuthProviderRequest {
+    /** Where the provider sends the browser back: `<serverURL><api>/auth/<id>/callback`. */
+    readonly redirectUri: string;
+    readonly state: string;
+    /** For PKCE: the provider gets its S256 challenge. */
+    readonly codeVerifier: string;
+    /** For OpenID Connect: must come back in the ID token. */
+    readonly nonce: string;
+}
+/** Who signed in, as the provider says. */
+interface AuthProviderProfile {
+    /** The provider's stable id for the account (`sub`). */
+    readonly subject: string;
+    readonly email: string | null;
+    /** The provider vouches for the email. Only verified emails are matched to users. */
+    readonly emailVerified: boolean;
+    readonly name?: string | undefined;
+}
+interface AuthProvider {
+    /** In URLs and stored identities, e.g. `google`: lowercase letters, digits and `-`. */
+    readonly id: string;
+    /** On the sign-in button, e.g. `Google`. */
+    readonly name: string;
+    /** The button's icon in the admin. Default `key`. */
+    readonly icon?: 'google' | 'microsoft' | 'github' | 'key';
+    /** The provider's page to send the browser to. */
+    authorizationURL(request: AuthProviderRequest): Promise<URL>;
+    /**
+     * After the browser comes back to `redirectUri` (`url`, with its query): checks the response
+     * and exchanges the code. Throws when anything does not check out.
+     */
+    callback(request: AuthProviderRequest & {
+        readonly url: URL;
+    }): Promise<AuthProviderProfile>;
+    /** For Settings → SSO: what it connects to, never secrets. */
+    describe?(): Readonly<Record<string, string>>;
+}
+
+interface ConfigIssue {
+    /** Where the problem is, e.g. `collections.posts.fields.slug.from`. */
+    readonly path: string;
+    readonly message: string;
+    /** How to fix it. */
+    readonly hint?: string;
+}
+declare class ConfigError extends Error {
+    readonly issues: readonly ConfigIssue[];
+    constructor(issues: readonly ConfigIssue[]);
+    static format(issues: readonly ConfigIssue[]): string;
+}
+/** Base class for errors that map to an HTTP status in the REST API. */
+declare class EasyCMSError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+interface FieldError {
+    /** Dotted path, e.g. `links.0.url`. */
+    readonly field: string;
+    readonly message: string;
+}
+declare class ValidationError extends EasyCMSError {
+    readonly errors: readonly FieldError[];
+    constructor(collection: string, errors: readonly FieldError[]);
+}
+declare class NotFoundError extends EasyCMSError {
+    constructor(collection: string, id: unknown);
+}
+/** A bad `where`, `sort` or unknown collection/global. */
+declare class QueryError extends EasyCMSError {
+    constructor(message: string);
+}
+/** The database schema does not match the config (pending or missing migrations). */
+declare class SchemaError extends EasyCMSError {
+    constructor(message: string);
+}
+/** Not logged in, or the session is invalid. */
+declare class UnauthorizedError extends EasyCMSError {
+    constructor(message?: string);
+}
+/** Logged in, but not allowed to do this. */
+declare class ForbiddenError extends EasyCMSError {
+    constructor(message?: string);
+}
+declare class TooManyRequestsError extends EasyCMSError {
+    constructor(message: string);
+}
+declare class PayloadTooLargeError extends EasyCMSError {
+    constructor(message: string);
+}
+
 /** Built-in types a field type can be stored as. */
 declare const FIELD_TYPE_BASES: readonly ["text", "textarea", "email", "number", "boolean", "date", "json"];
 type FieldTypeBase = (typeof FIELD_TYPE_BASES)[number];
@@ -2273,10 +2420,15 @@ interface Config {
      * `every`, admins can still back up by hand.
      */
     readonly backups?: BackupsConfig;
+    /**
+     * The audit log (Settings → Audit log): who changed what and when, sign-ins, and admin
+     * actions, kept for `keep` days. `true` for the defaults.
+     */
+    readonly audit?: boolean | AuditConfig;
     readonly plugins?: readonly Plugin[];
 }
 /** The config after plugins ran, validation passed and defaults were applied. */
-interface ResolvedConfig extends Omit<Config, 'cors' | 'localization' | 'routes' | 'admin' | 'upload' | 'auth' | 'collections' | 'globals' | 'endpoints' | 'plugins'> {
+interface ResolvedConfig extends Omit<Config, 'cors' | 'localization' | 'routes' | 'admin' | 'upload' | 'auth' | 'collections' | 'globals' | 'endpoints' | 'plugins' | 'audit'> {
     readonly cors: readonly string[] | '*';
     /** `null` without localization. */
     readonly localization: Required<LocalizationConfig> | null;
@@ -2284,6 +2436,8 @@ interface ResolvedConfig extends Omit<Config, 'cors' | 'localization' | 'routes'
     readonly admin: Required<AdminConfig>;
     readonly upload: Required<Omit<UploadConfig, 'storage' | 'fromURL'>> & Pick<UploadConfig, 'storage' | 'fromURL'>;
     readonly auth: Required<AuthConfig>;
+    /** `false` without an audit log. */
+    readonly audit: Required<AuditConfig> | false;
     readonly collections: readonly CollectionConfig[];
     readonly globals: readonly GlobalConfig[];
     readonly endpoints: readonly Endpoint[];
@@ -2734,6 +2888,7 @@ interface AdminSchema {
         email: boolean;
         roles: boolean;
         sso: boolean;
+        audit: boolean;
     };
     /** Roles from the admin are on (`auth.rbac`): documents have owners. */
     rbac: boolean;
@@ -2776,6 +2931,22 @@ type AdminAttention =
     id: 'backups';
     failed: boolean;
     lastDone: string | null;
+}
+/** Many failed logins in the last hour (`audit.failedLogins`): someone may be guessing. */
+ | {
+    id: 'failed-logins';
+    count: number;
+}
+/** Audit log entries that could not be written since the server started. */
+ | {
+    id: 'audit-failures';
+    count: number;
+}
+/** The last check of the audit log found entries changed in the database. */
+ | {
+    id: 'audit-tampered';
+    invalid: number;
+    at: string;
 };
 /** What the dashboard shows admins (`GET <api>/admin/status`). */
 interface AdminStatus {
@@ -2837,4 +3008,4 @@ declare function validateConfig(config: Config): ConfigIssue[];
 /** The version of `@easy-cms/core`, set when the package is built. */
 declare const VERSION: string;
 
-export { ADMIN_ICONS, API_KEYS, API_KEY_GLOBAL_OPERATIONS, API_KEY_OPERATIONS, type Access, type AccessArgs, type AccessOptions, type AdminAttention, type AdminBackup, type AdminBackups, type AdminBrand, type AdminCollection, type AdminComponent, type AdminComponentRef, type AdminConfig, type AdminDeliveries, type AdminDelivery, type AdminEmail, type AdminEmailDelivery, type AdminField, type AdminGlobal, type AdminIcon, type AdminLocale, type AdminPage, type AdminPageRef, type AdminRole, type AdminRoleChange, type AdminRoleField, type AdminRoleTarget, type AdminRoleView, type AdminRoles, type AdminSchema, type AdminSso, type AdminStatus, type AdminViewAccess, type AdminWebhookDelivery, type AdminWidgetRef, type AfterChangeHook, type AfterDeleteHook, type AfterReadHook, type ApiKeyContext, type ApiKeyGlobalOperation, type ApiKeyOperation, type ApiKeyPermissions, type ArrayField, Auth, type AuthConfig, type AuthProvider, type AuthProviderProfile, type AuthProviderRequest, type AuthUser, BUILTIN_COLLECTIONS, type BackupState, type BackupsConfig, type BeforeChangeHook, type BeforeDeleteHook, type BeforeValidateHook, type Block, type BlocksField, type BooleanField, type BuiltinApiKeysCollection, type BuiltinMediaCollection, type BuiltinUsersCollection, type BundleHints, CONFIG_FILE_NAMES, CSRF_COOKIE, CSRF_HEADER, type CliCommand, type CollectionAccess, type CollectionAdmin, type CollectionConfig, type CollectionDocument, type CollectionHooks, type CollectionListAdmin, type CollectionSlug, type Config, ConfigError, type ConfigIssue, type ContainerAdmin, type CopyProgress, type CopyResult, type CreateEasyCMSOptions, type CreateInput, type CreateMigrationResult, type CustomField, type CustomFieldTypes, DEFAULT_ADMIN_PATH, DEFAULT_API_PATH, DEFAULT_DEPTH, DEFAULT_MAX_FILE_SIZE, DEFAULT_MAX_VERSIONS, DEFAULT_PASSWORD_EMAILS, DEFAULT_TOKEN_EXPIRATION, type DashboardWidget, type Database, type DatabaseAdapter, type DatabaseInitArgs, type DatabaseTransfer, type DateField, type DeliveryKind, type DeliveryState, type DepthOptions, type DocumentOf, EXTENSIONS, EasyCMS, EasyCMSError, type EmailAdapter, type EmailCheck, type EmailField, type EmailMessage, type EmailSetting, type Endpoint, type EndpointRequest, FIELD_TYPES, FIELD_TYPE_BASES, type Field, type FieldAccess, type FieldAccessFn, type FieldAdmin, type FieldError, type FieldRule, type FieldType, type FieldTypeBase, type FieldTypeDefinition, type FieldTypeValidateContext, type FieldValidate, type FieldValidateContext, type FieldValue, type FieldsInput, type FieldsValue, type FilterOptions, type FilterOptionsArgs, type FindArgs, type FindOptions, ForbiddenError, type GlobalAccess, type GlobalConfig, type GlobalDocument, type GlobalHooks, type GlobalInput, type GlobalSlug, type GroupField, type ID, INTERNAL_COLLECTIONS, type ImageSize, type InferCollection, type InferGlobal, type JsonField, type Label, type LivePreview, type LoadConfigOptions, type LocalStorageOptions, type LocalizationConfig, type Logger, type LoginArgs, MAX_DEPTH, MEDIA, MIN_PASSWORD_LENGTH, MIN_SECRET_LENGTH, type MediaDocument, type MediaSize, type MigrationInfo, NotFoundError, type NumberField, type Operation, type PaginatedDocs, type PasswordEmail, type PasswordEmailArgs, type PasswordEmailFn, type PasswordLinkOptions, PayloadTooLargeError, type Plugin, type PluginInfo, type PluginTypes, type PreviewTarget, type PreviewURL, QueryError, ROLE_OPERATIONS, type RawDocument, type ReadOptions, type RelationshipField, type ResolvedConfig, type RestHandler, type RestHandlerOptions, type RichTextDocument, type RichTextField, type Role, type RoleOperation, type RolePermissions, Roles, type RoutesConfig, SESSION_COOKIE, SSO_COOKIE, type ScheduledJob, SchemaError, type SchemaMode, type SelectField, type SelectOption, type Session, type SlugField, type SlugOf, type SsoOutcome, type SsoProviderRef, type StorageAdapter, type StoredFile, type TextField, type TextareaField, TooManyRequestsError, type TypedPlugin, UnauthorizedError, type UpdateInput, type UpdateOptions, type UploadConfig, type UploadField, type UploadFromURLConfig, type UserIdentity, VERSION, ValidationError, type Version, type VersionSummary, type VersionsConfig, WEBHOOK_EVENTS, type WebhookConfig, type WebhookEvent, type WebhookPayload, type Where, type WhereOperators, anyone, applyDefaults, applyPlugins, configSignature, consoleEmail, consoleLogger, copyDatabase, createEasyCMS, createRestHandler, createRootEndpointHandler, defineConfig, defineFieldType, definePlugin, fillMissing, findConfigFile, generateSlugs, generateTypes, hasRows, hashPassword, imageDimensions, importConfig, isAdmin, isHasMany, isLoggedIn, keyAllows, loadConfig, localStorage, mergeForUpdate, mimeAllowed, mimeAllowedBy, parseId, populate, readCookie, resolveAdminModule, resolveConfig, rowFields, silentLogger, singularize, slugify, sniffMimeType, validateConfig, validateFields, verifyPassword, writeBackupFile };
+export { ADMIN_ICONS, API_KEYS, API_KEY_GLOBAL_OPERATIONS, API_KEY_OPERATIONS, type Access, type AccessArgs, type AccessOptions, type AdminAttention, type AdminBackup, type AdminBackups, type AdminBrand, type AdminCollection, type AdminComponent, type AdminComponentRef, type AdminConfig, type AdminDeliveries, type AdminDelivery, type AdminEmail, type AdminEmailDelivery, type AdminField, type AdminGlobal, type AdminIcon, type AdminLocale, type AdminPage, type AdminPageRef, type AdminRole, type AdminRoleChange, type AdminRoleField, type AdminRoleTarget, type AdminRoleView, type AdminRoles, type AdminSchema, type AdminSso, type AdminStatus, type AdminViewAccess, type AdminWebhookDelivery, type AdminWidgetRef, type AfterChangeHook, type AfterDeleteHook, type AfterReadHook, type ApiKeyContext, type ApiKeyGlobalOperation, type ApiKeyOperation, type ApiKeyPermissions, type ArrayField, type AuditChange, type AuditConfig, type AuditEntry, AuditLog, type AuditPage, type AuditVerification, Auth, type AuthConfig, type AuthProvider, type AuthProviderProfile, type AuthProviderRequest, type AuthUser, BUILTIN_COLLECTIONS, type BackupState, type BackupsConfig, type BeforeChangeHook, type BeforeDeleteHook, type BeforeValidateHook, type Block, type BlocksField, type BooleanField, type BuiltinApiKeysCollection, type BuiltinMediaCollection, type BuiltinUsersCollection, type BundleHints, CONFIG_FILE_NAMES, CSRF_COOKIE, CSRF_HEADER, type CliCommand, type CollectionAccess, type CollectionAdmin, type CollectionConfig, type CollectionDocument, type CollectionHooks, type CollectionListAdmin, type CollectionSlug, type Config, ConfigError, type ConfigIssue, type ContainerAdmin, type CopyProgress, type CopyResult, type CreateEasyCMSOptions, type CreateInput, type CreateMigrationResult, type CustomField, type CustomFieldTypes, DEFAULT_ADMIN_PATH, DEFAULT_API_PATH, DEFAULT_DEPTH, DEFAULT_MAX_FILE_SIZE, DEFAULT_MAX_VERSIONS, DEFAULT_PASSWORD_EMAILS, DEFAULT_TOKEN_EXPIRATION, type DashboardWidget, type Database, type DatabaseAdapter, type DatabaseInitArgs, type DatabaseTransfer, type DateField, type DeliveryKind, type DeliveryState, type DepthOptions, type DocumentOf, EXTENSIONS, EasyCMS, EasyCMSError, type EmailAdapter, type EmailCheck, type EmailField, type EmailMessage, type EmailSetting, type Endpoint, type EndpointRequest, FIELD_TYPES, FIELD_TYPE_BASES, type Field, type FieldAccess, type FieldAccessFn, type FieldAdmin, type FieldError, type FieldRule, type FieldType, type FieldTypeBase, type FieldTypeDefinition, type FieldTypeValidateContext, type FieldValidate, type FieldValidateContext, type FieldValue, type FieldsInput, type FieldsValue, type FilterOptions, type FilterOptionsArgs, type FindArgs, type FindOptions, ForbiddenError, type GlobalAccess, type GlobalConfig, type GlobalDocument, type GlobalHooks, type GlobalInput, type GlobalSlug, type GroupField, type ID, INTERNAL_COLLECTIONS, type ImageSize, type InferCollection, type InferGlobal, type JsonField, type Label, type LivePreview, type LoadConfigOptions, type LocalStorageOptions, type LocalizationConfig, type Logger, type LoginArgs, MAX_DEPTH, MEDIA, MIN_PASSWORD_LENGTH, MIN_SECRET_LENGTH, type MediaDocument, type MediaSize, type MigrationInfo, NotFoundError, type NumberField, type Operation, type PaginatedDocs, type PasswordEmail, type PasswordEmailArgs, type PasswordEmailFn, type PasswordLinkOptions, PayloadTooLargeError, type Plugin, type PluginInfo, type PluginTypes, type PreviewTarget, type PreviewURL, QueryError, ROLE_OPERATIONS, type RawDocument, type ReadOptions, type RelationshipField, type ResolvedConfig, type RestHandler, type RestHandlerOptions, type RichTextDocument, type RichTextField, type Role, type RoleOperation, type RolePermissions, Roles, type RoutesConfig, SESSION_COOKIE, SSO_COOKIE, type ScheduledJob, SchemaError, type SchemaMode, type SelectField, type SelectOption, type Session, type SlugField, type SlugOf, type SsoOutcome, type SsoProviderRef, type StorageAdapter, type StoredFile, type TextField, type TextareaField, TooManyRequestsError, type TypedPlugin, UnauthorizedError, type UpdateInput, type UpdateOptions, type UploadConfig, type UploadField, type UploadFromURLConfig, type UserIdentity, VERSION, ValidationError, type Version, type VersionSummary, type VersionsConfig, WEBHOOK_EVENTS, type WebhookConfig, type WebhookEvent, type WebhookPayload, type Where, type WhereOperators, anyone, applyDefaults, applyPlugins, configSignature, consoleEmail, consoleLogger, copyDatabase, createEasyCMS, createRestHandler, createRootEndpointHandler, defineConfig, defineFieldType, definePlugin, fillMissing, findConfigFile, generateSlugs, generateTypes, hasRows, hashPassword, imageDimensions, importConfig, isAdmin, isHasMany, isLoggedIn, keyAllows, loadConfig, localStorage, mergeForUpdate, mimeAllowed, mimeAllowedBy, parseId, populate, readCookie, resolveAdminModule, resolveConfig, rowFields, silentLogger, singularize, slugify, sniffMimeType, validateConfig, validateFields, verifyPassword, writeBackupFile };