@easy-cms/core 0.34.0 → 0.36.0

package/dist/index.d.ts

@@ -56,29 +56,217 @@ declare const anyone: Access;
 declare const isLoggedIn: Access;
 declare const isAdmin: Access;
 
-/** What the email functions in `auth.emails` receive. */
-interface PasswordEmailArgs {
+/** What a preview token opens: one document of a collection, or one global. */
+type PreviewTarget = {
+    readonly collection: string;
+    readonly id: string;
+} | {
+    readonly global: string;
+};
+/** Why a password link was sent: a forgotten password, or an invitation to a new account. */
+type PasswordPurpose = 'reset' | 'invite';
+
+/** The cookie that carries a sign-in through the provider and back. */
+declare const SSO_COOKIE = "ecms-sso";
+/** A provider as the login page shows it (`GET <api>/users/init`). */
+interface SsoProviderRef {
+    id: string;
+    name: string;
+    icon: string;
+}
+/** Settings → SSO (`GET <api>/admin/sso`). */
+interface AdminSso {
+    providers: (SsoProviderRef & {
+        /** Give this to the provider as the redirect (callback) URL. */
+        callbackURL: string | null;
+        details: Record<string, string>;
+    })[];
+    /** Who may sign in with a password: everyone, or only admins. */
+    password: 'everyone' | 'admins';
+    /** Email domains whose people get an account when they first sign in. */
+    signUp: {
+        domains: string[];
+        role: string;
+    } | null;
+    /** Without `serverURL`, sign-in only works in development. */
+    serverURL: boolean;
+}
+/** An outside account a user signs in with (`GET <api>/auth/identities`). */
+interface UserIdentity {
+    id: ID;
+    provider: string;
+    /** The provider's name, e.g. `Google`. */
+    name: string;
+    email: string | null;
+    createdAt: string;
+    lastUsedAt: string | null;
+}
+/** Why a sign-in did not work, as `?sso=` on the page it ends on. */
+type SsoOutcome = 'linked' | 'cancelled' | 'expired' | 'failed' | 'no-account' | 'unverified' | 'inactive' | 'taken';
+/** Single sign-on with `auth.providers`. Available as `cms.auth.sso`. */
+declare class SingleSignOn {
+    private readonly cms;
+    constructor(cms: EasyCMS);
+    private get config();
+    get enabled(): boolean;
+    providers(): SsoProviderRef[];
+    /** Whether a user may sign in with a password (`auth.password: false` leaves only admins). */
+    passwordAllowed(user: {
+        readonly [key: string]: unknown;
+    }): boolean;
+    /** `<serverURL><api>/auth/<id>/callback`, or `null` without `serverURL` in production. */
+    callbackURL(provider: string, origin?: string): string | null;
+    /**
+     * Starts signing in (or, with `user`, linking an account): the provider's URL to send the
+     * browser to, and the sealed value of the cookie that must come back with it.
+     */
+    start(providerId: string, options: {
+        origin?: string;
+        redirect?: string | null;
+        user?: AuthUser;
+    }): Promise<{
+        url: string;
+        cookie: string;
+    }>;
+    /**
+     * Finishes at `<api>/auth/<id>/callback`: checks the response, finds (or makes) the user and
+     * starts a session. Returns where to send the browser; failures end on the login page (or the
+     * account page, when linking) with `?sso=<outcome>`.
+     */
+    finish(providerId: string, options: {
+        url: URL;
+        cookie: string | undefined;
+        origin?: string;
+        user: AuthUser | null;
+    }): Promise<{
+        redirect: string;
+        session?: Session;
+    }>;
+    /** A user's outside accounts. */
+    identities(userId: ID): Promise<UserIdentity[]>;
+    /**
+     * Unlinks an outside account: the user's own, or anyone's for admins. Refuses to unlink the
+     * last way a user has to sign in.
+     */
+    unlink(actor: AuthUser, identityId: ID): Promise<void>;
+    /** Forgets a deleted user's outside accounts. */
+    forget(userId: ID): Promise<void>;
+    settings(origin?: string): AdminSso;
+    private provider;
+    /** Only pages of the admin: anything else (another site) goes to the admin's home. */
+    private adminPage;
+    private identity;
+    private addIdentity;
+    private userByEmail;
+    /** A new account for people from `allowSignUp.domains`. */
+    private signUp;
+    private defaultRole;
+}
+
+interface LoginArgs {
+    readonly email: string;
+    readonly password: string;
+    /** Client IP, used together with the email for rate limiting. */
+    readonly ip?: string | undefined;
+}
+interface Session {
     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;
+    /** Signed session token, the value of the session cookie. */
+    readonly token: string;
+    /** Send back in the `X-CSRF-Token` header on cookie-authenticated writes. */
+    readonly csrfToken: string;
+    readonly expiresAt: string;
 }
-/** An email's content: a subject, and text and/or HTML. */
-interface PasswordEmail {
-    readonly subject: string;
-    readonly text: string;
-    readonly html?: string;
+/** Where a password link is opened from, and the language of its email. */
+interface PasswordLinkOptions {
+    /** The request's origin: used for the link only in development, when `serverURL` is not set. */
+    readonly origin?: string | undefined;
+    /** `en` or `th`. Default: `admin.locale`. */
+    readonly locale?: string | undefined;
+}
+/** Login, logout and session verification. Available as `cms.auth`. */
+declare class Auth {
+    private readonly cms;
+    /** Signing in with outside accounts (`auth.providers`). */
+    readonly sso: SingleSignOn;
+    constructor(cms: EasyCMS);
+    private get db();
+    private get config();
+    /** Checks credentials and starts a session. Throws `UnauthorizedError` or `TooManyRequestsError`. */
+    login(args: LoginArgs): Promise<Session>;
+    /** Creates the first admin. Only works while there are no users. */
+    registerFirstUser(args: {
+        email: string;
+        password: string;
+        name?: string;
+    }): Promise<Session>;
+    hasUsers(): Promise<boolean>;
+    /** Ends the session for a signed token. Unknown tokens are ignored. */
+    logout(signedToken: string): Promise<void>;
+    /**
+     * Returns the user for a signed session token, or for an API key (`ecms_…`, with `apiKey` set
+     * on the user), or `null` if it is invalid or expired.
+     */
+    verify(signedToken: string | undefined | null): Promise<AuthUser | null>;
+    /** The CSRF token clients must echo for a signed session token. */
+    csrfFor(signedToken: string): string | undefined;
+    /** Starts a new session for a user, e.g. after they changed their own password. */
+    createSession(userId: ID): Promise<Session>;
+    /** Signs a user out everywhere. */
+    revokeSessions(userId: ID): Promise<void>;
+    /**
+     * The origin password links point to: `serverURL`, or the request's origin in development. In
+     * production the request's Host can't be trusted (a forged one would send the link elsewhere).
+     */
+    passwordLinkBase(origin?: string): string | null;
+    /** Whether "forgot password" and invitations work: `email` is set and links have an origin. */
+    canSendPasswordLinks(origin?: string): boolean;
+    /**
+     * Emails a link to set a new password, if an active account has this email. Always resolves the
+     * same way, so callers can't tell whether the email has an account; extra requests within
+     * `lockWindow` are ignored.
+     */
+    requestPasswordReset(args: PasswordLinkOptions & {
+        email: string;
+        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.
+     */
+    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;
 }
-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;
-};
 
 interface Logger {
     info(message: string): void;
@@ -277,171 +465,6 @@ declare function consoleEmail(options?: {
     })[];
 };
 
-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;
-    readonly id: string;
-} | {
-    readonly global: string;
-};
-/** Why a password link was sent: a forgotten password, or an invitation to a new account. */
-type PasswordPurpose = 'reset' | 'invite';
-
-interface LoginArgs {
-    readonly email: string;
-    readonly password: string;
-    /** Client IP, used together with the email for rate limiting. */
-    readonly ip?: string | undefined;
-}
-interface Session {
-    readonly user: AuthUser;
-    /** Signed session token, the value of the session cookie. */
-    readonly token: string;
-    /** Send back in the `X-CSRF-Token` header on cookie-authenticated writes. */
-    readonly csrfToken: string;
-    readonly expiresAt: string;
-}
-/** Where a password link is opened from, and the language of its email. */
-interface PasswordLinkOptions {
-    /** The request's origin: used for the link only in development, when `serverURL` is not set. */
-    readonly origin?: string | undefined;
-    /** `en` or `th`. Default: `admin.locale`. */
-    readonly locale?: string | undefined;
-}
-/** Login, logout and session verification. Available as `cms.auth`. */
-declare class Auth {
-    private readonly cms;
-    constructor(cms: EasyCMS);
-    private get db();
-    private get config();
-    /** Checks credentials and starts a session. Throws `UnauthorizedError` or `TooManyRequestsError`. */
-    login(args: LoginArgs): Promise<Session>;
-    /** Creates the first admin. Only works while there are no users. */
-    registerFirstUser(args: {
-        email: string;
-        password: string;
-        name?: string;
-    }): Promise<Session>;
-    hasUsers(): Promise<boolean>;
-    /** Ends the session for a signed token. Unknown tokens are ignored. */
-    logout(signedToken: string): Promise<void>;
-    /**
-     * Returns the user for a signed session token, or for an API key (`ecms_…`, with `apiKey` set
-     * on the user), or `null` if it is invalid or expired.
-     */
-    verify(signedToken: string | undefined | null): Promise<AuthUser | null>;
-    /** The CSRF token clients must echo for a signed session token. */
-    csrfFor(signedToken: string): string | undefined;
-    /** Starts a new session for a user, e.g. after they changed their own password. */
-    createSession(userId: ID): Promise<Session>;
-    /** Signs a user out everywhere. */
-    revokeSessions(userId: ID): Promise<void>;
-    /**
-     * The origin password links point to: `serverURL`, or the request's origin in development. In
-     * production the request's Host can't be trusted (a forged one would send the link elsewhere).
-     */
-    passwordLinkBase(origin?: string): string | null;
-    /** Whether "forgot password" and invitations work: `email` is set and links have an origin. */
-    canSendPasswordLinks(origin?: string): boolean;
-    /**
-     * Emails a link to set a new password, if an active account has this email. Always resolves the
-     * same way, so callers can't tell whether the email has an account; extra requests within
-     * `lockWindow` are ignored.
-     */
-    requestPasswordReset(args: PasswordLinkOptions & {
-        email: string;
-        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.
-     */
-    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;
-}
-
 type Simplify<T> = {
     [K in keyof T]: T[K];
 } & {};
@@ -831,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.
@@ -1072,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;
@@ -1332,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;
@@ -1555,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];
@@ -1920,6 +2215,24 @@ interface AuthConfig {
     readonly resetPasswordExpiration?: number;
     /** How long an invitation link works, in seconds. Default 7 days. */
     readonly inviteExpiration?: number;
+    /**
+     * Signing in to the admin with outside accounts, e.g. `[google({ clientId, clientSecret })]`
+     * from `@easy-cms/auth-oauth`. Users are matched by their verified email.
+     */
+    readonly providers?: readonly AuthProvider[];
+    /**
+     * With `providers`: people from these email domains who sign in for the first time get an
+     * account with `role` (default: as new users). Without it, only existing users can sign in.
+     */
+    readonly allowSignUp?: {
+        readonly domains: readonly string[];
+        readonly role?: string;
+    };
+    /**
+     * `false`: only admins may sign in with a password (a way in when the provider is down);
+     * everyone else signs in with `providers`. Default `true`.
+     */
+    readonly password?: boolean;
     /** Your own text for the password emails, e.g. in your brand's voice. Default: English or Thai. */
     readonly emails?: {
         readonly resetPassword?: PasswordEmailFn;
@@ -2107,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;
@@ -2118,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[];
@@ -2567,9 +2887,13 @@ interface AdminSchema {
         backups: boolean;
         email: boolean;
         roles: boolean;
+        sso: boolean;
+        audit: boolean;
     };
     /** Roles from the admin are on (`auth.rbac`): documents have owners. */
     rbac: boolean;
+    /** Outside accounts users can sign in with and link (`auth.providers`). */
+    providers: SsoProviderRef[];
     /** Pages this user may open (`admin.pages`). */
     pages: AdminPageRef[];
     /** Dashboard panels this user may see (`admin.dashboard`). */
@@ -2607,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 {
@@ -2668,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 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 };
+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 };