@easy-cms/core 0.23.0 → 0.24.0

package/dist/index.d.ts

@@ -56,6 +56,30 @@ 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;
+}
+/** 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;
+};
+
 interface Logger {
     info(message: string): void;
     warn(message: string): void;
@@ -237,6 +261,8 @@ type PreviewTarget = {
 } | {
     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;
@@ -252,6 +278,13 @@ interface Session {
     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;
@@ -280,6 +313,48 @@ declare class Auth {
     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;
@@ -541,14 +616,17 @@ type StatusInput<T> = T extends {
 } ? {
     status?: 'draft' | 'published';
 } : unknown;
-/** Users are created with a password, which is hashed and never returned. */
+/**
+ * A user's password, hashed and never returned. Optional when creating: a user without one sets
+ * it from an invitation link.
+ */
 type PasswordInput<S, Required extends boolean> = S extends 'users' ? Required extends true ? {
     password: string;
 } : {
     password?: string;
 } : unknown;
 /** Data accepted by `create`, e.g. `CreateInput<typeof config, 'posts'>`. */
-type CreateInput<C extends Config, S extends CollectionSlug<C>> = Simplify<FieldsInput<CollectionBySlug<C, S>['fields']> & StatusInput<CollectionBySlug<C, S>> & PasswordInput<S, true>>;
+type CreateInput<C extends Config, S extends CollectionSlug<C>> = Simplify<FieldsInput<CollectionBySlug<C, S>['fields']> & StatusInput<CollectionBySlug<C, S>> & PasswordInput<S, false>>;
 /** Data accepted by `update`: any subset of `CreateInput`. */
 type UpdateInput<C extends Config, S extends CollectionSlug<C>> = Partial<CreateInput<C, S>>;
 /** Data accepted by `updateGlobal`. */
@@ -1370,6 +1448,19 @@ interface AuthConfig {
      * Needed when the admin or frontend is served from another origin, or behind a proxy that rewrites the host.
      */
     readonly trustedOrigins?: readonly string[];
+    /**
+     * How long a "forgot password" link works, in seconds. Default 1 hour. Links work once: setting
+     * the password ends them. Needs `email` and, in production, `serverURL` for the link.
+     */
+    readonly resetPasswordExpiration?: number;
+    /** How long an invitation link works, in seconds. Default 7 days. */
+    readonly inviteExpiration?: number;
+    /** Your own text for the password emails, e.g. in your brand's voice. Default: English or Thai. */
+    readonly emails?: {
+        readonly resetPassword?: PasswordEmailFn;
+        readonly invite?: PasswordEmailFn;
+        readonly passwordChanged?: PasswordEmailFn;
+    };
 }
 /** What an endpoint's handler receives. */
 interface EndpointRequest {
@@ -1838,6 +1929,8 @@ interface AdminGlobal {
 }
 interface AdminSchema {
     locale: AdminLocale;
+    /** Admins can email users links to set their password (needs `email` and `serverURL`). */
+    passwordLinks: boolean;
     /** Menu order of collections (`admin.menu`); unlisted ones follow. */
     menu: string[];
     /** Content locales, when the config has `localization`. */
@@ -1886,4 +1979,4 @@ declare const BUILTIN_COLLECTIONS: readonly ["users", "media"];
 /** Checks a config and returns every problem found. An empty array means it is valid. */
 declare function validateConfig(config: Config): ConfigIssue[];
 
-export { ADMIN_ICONS, API_KEYS, API_KEY_GLOBAL_OPERATIONS, API_KEY_OPERATIONS, type Access, type AccessArgs, type AccessOptions, type AdminBrand, type AdminCollection, type AdminComponent, type AdminComponentRef, type AdminConfig, type AdminField, type AdminGlobal, type AdminIcon, type AdminLocale, type AdminSchema, 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, DEFAULT_ADMIN_PATH, DEFAULT_API_PATH, DEFAULT_DEPTH, DEFAULT_MAX_FILE_SIZE, DEFAULT_MAX_VERSIONS, DEFAULT_TOKEN_EXPIRATION, type Database, type DatabaseAdapter, type DatabaseInitArgs, type DatabaseTransfer, type DateField, type DepthOptions, EXTENSIONS, EasyCMS, EasyCMSError, type EmailAdapter, type EmailField, type EmailMessage, type Endpoint, type EndpointRequest, FIELD_TYPES, type Field, type FieldAccess, type FieldAccessFn, type FieldAdmin, type FieldError, type FieldType, 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, PayloadTooLargeError, type Plugin, 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 StorageAdapter, type StoredFile, type TextField, type TextareaField, TooManyRequestsError, UnauthorizedError, type UpdateInput, type UpdateOptions, type UploadConfig, type UploadField, 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, 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 AdminBrand, type AdminCollection, type AdminComponent, type AdminComponentRef, type AdminConfig, type AdminField, type AdminGlobal, type AdminIcon, type AdminLocale, type AdminSchema, 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, DEFAULT_ADMIN_PATH, DEFAULT_API_PATH, DEFAULT_DEPTH, DEFAULT_MAX_FILE_SIZE, DEFAULT_MAX_VERSIONS, DEFAULT_PASSWORD_EMAILS, DEFAULT_TOKEN_EXPIRATION, type Database, type DatabaseAdapter, type DatabaseInitArgs, type DatabaseTransfer, type DateField, type DepthOptions, EXTENSIONS, EasyCMS, EasyCMSError, type EmailAdapter, type EmailField, type EmailMessage, type Endpoint, type EndpointRequest, FIELD_TYPES, type Field, type FieldAccess, type FieldAccessFn, type FieldAdmin, type FieldError, type FieldType, 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 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 StorageAdapter, type StoredFile, type TextField, type TextareaField, TooManyRequestsError, UnauthorizedError, type UpdateInput, type UpdateOptions, type UploadConfig, type UploadField, 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, 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 };

package/dist/index.js

@@ -560,6 +560,58 @@ var emailDeliveriesCollection = {
   ]
 };
 
+// src/auth/emails.ts
+var esc = (value) => value.replace(
+  /[&<>"']/g,
+  (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]
+);
+function email(subject, lines, button) {
+  const text = [...lines, ...button ? ["", button.url] : []].join("\n");
+  const html = `<div style="font-family:system-ui,sans-serif;font-size:15px;line-height:1.5;color:#1f2328">${lines.map((line) => `<p>${esc(line)}</p>`).join("")}${button ? `<p><a href="${esc(button.url)}" style="display:inline-block;padding:10px 18px;border-radius:8px;background:#2f6f5e;color:#fff;text-decoration:none;font-weight:600">${esc(button.label)}</a></p><p style="font-size:13px;color:#656d76">${esc(button.url)}</p>` : ""}</div>`;
+  return { subject, text, html };
+}
+var hours = (expiresAt) => Math.max(1, Math.round(((expiresAt?.getTime() ?? Date.now()) - Date.now()) / 36e5));
+var days = (expiresAt) => Math.max(1, Math.round(hours(expiresAt) / 24));
+var DEFAULT_PASSWORD_EMAILS = {
+  resetPassword: ({ url = "", locale, expiresAt }) => locale === "th" ? email(
+    "\u0E15\u0E31\u0E49\u0E07\u0E23\u0E2B\u0E31\u0E2A\u0E1C\u0E48\u0E32\u0E19\u0E43\u0E2B\u0E21\u0E48",
+    [
+      "\u0E21\u0E35\u0E04\u0E33\u0E02\u0E2D\u0E15\u0E31\u0E49\u0E07\u0E23\u0E2B\u0E31\u0E2A\u0E1C\u0E48\u0E32\u0E19\u0E43\u0E2B\u0E21\u0E48\u0E2A\u0E33\u0E2B\u0E23\u0E31\u0E1A\u0E1A\u0E31\u0E0D\u0E0A\u0E35\u0E02\u0E2D\u0E07\u0E04\u0E38\u0E13",
+      `\u0E25\u0E34\u0E07\u0E01\u0E4C\u0E19\u0E35\u0E49\u0E43\u0E0A\u0E49\u0E44\u0E14\u0E49\u0E04\u0E23\u0E31\u0E49\u0E07\u0E40\u0E14\u0E35\u0E22\u0E27\u0E20\u0E32\u0E22\u0E43\u0E19 ${hours(expiresAt)} \u0E0A\u0E31\u0E48\u0E27\u0E42\u0E21\u0E07 \u0E16\u0E49\u0E32\u0E04\u0E38\u0E13\u0E44\u0E21\u0E48\u0E44\u0E14\u0E49\u0E02\u0E2D \u0E44\u0E21\u0E48\u0E15\u0E49\u0E2D\u0E07\u0E17\u0E33\u0E2D\u0E30\u0E44\u0E23 \u0E23\u0E2B\u0E31\u0E2A\u0E1C\u0E48\u0E32\u0E19\u0E40\u0E14\u0E34\u0E21\u0E22\u0E31\u0E07\u0E43\u0E0A\u0E49\u0E44\u0E14\u0E49`
+    ],
+    { label: "\u0E15\u0E31\u0E49\u0E07\u0E23\u0E2B\u0E31\u0E2A\u0E1C\u0E48\u0E32\u0E19\u0E43\u0E2B\u0E21\u0E48", url }
+  ) : email(
+    "Reset your password",
+    [
+      "Someone asked to reset the password of your account.",
+      `The link works once, within ${hours(expiresAt)} hour(s). If it wasn't you, ignore this email: your password stays the same.`
+    ],
+    { label: "Set a new password", url }
+  ),
+  invite: ({ url = "", locale, expiresAt, user }) => locale === "th" ? email(
+    "\u0E04\u0E38\u0E13\u0E44\u0E14\u0E49\u0E23\u0E31\u0E1A\u0E40\u0E0A\u0E34\u0E0D\u0E43\u0E2B\u0E49\u0E43\u0E0A\u0E49\u0E07\u0E32\u0E19\u0E23\u0E30\u0E1A\u0E1A\u0E08\u0E31\u0E14\u0E01\u0E32\u0E23\u0E40\u0E19\u0E37\u0E49\u0E2D\u0E2B\u0E32",
+    [
+      `\u0E21\u0E35\u0E1A\u0E31\u0E0D\u0E0A\u0E35\u0E2A\u0E33\u0E2B\u0E23\u0E31\u0E1A ${user.email} \u0E23\u0E2D\u0E04\u0E38\u0E13\u0E2D\u0E22\u0E39\u0E48 \u0E15\u0E31\u0E49\u0E07\u0E23\u0E2B\u0E31\u0E2A\u0E1C\u0E48\u0E32\u0E19\u0E40\u0E1E\u0E37\u0E48\u0E2D\u0E40\u0E23\u0E34\u0E48\u0E21\u0E43\u0E0A\u0E49\u0E07\u0E32\u0E19`,
+      `\u0E25\u0E34\u0E07\u0E01\u0E4C\u0E19\u0E35\u0E49\u0E43\u0E0A\u0E49\u0E44\u0E14\u0E49\u0E20\u0E32\u0E22\u0E43\u0E19 ${days(expiresAt)} \u0E27\u0E31\u0E19`
+    ],
+    { label: "\u0E15\u0E31\u0E49\u0E07\u0E23\u0E2B\u0E31\u0E2A\u0E1C\u0E48\u0E32\u0E19", url }
+  ) : email(
+    "You're invited to the content admin",
+    [
+      `An account for ${user.email} is waiting for you. Set a password to start.`,
+      `The link works within ${days(expiresAt)} day(s).`
+    ],
+    { label: "Set your password", url }
+  ),
+  passwordChanged: ({ locale }) => locale === "th" ? email("\u0E23\u0E2B\u0E31\u0E2A\u0E1C\u0E48\u0E32\u0E19\u0E02\u0E2D\u0E07\u0E04\u0E38\u0E13\u0E16\u0E39\u0E01\u0E40\u0E1B\u0E25\u0E35\u0E48\u0E22\u0E19\u0E41\u0E25\u0E49\u0E27", [
+    "\u0E23\u0E2B\u0E31\u0E2A\u0E1C\u0E48\u0E32\u0E19\u0E02\u0E2D\u0E07\u0E1A\u0E31\u0E0D\u0E0A\u0E35\u0E04\u0E38\u0E13\u0E40\u0E1E\u0E34\u0E48\u0E07\u0E16\u0E39\u0E01\u0E40\u0E1B\u0E25\u0E35\u0E48\u0E22\u0E19 \u0E41\u0E25\u0E30\u0E17\u0E38\u0E01\u0E40\u0E04\u0E23\u0E37\u0E48\u0E2D\u0E07\u0E17\u0E35\u0E48 login \u0E2D\u0E22\u0E39\u0E48\u0E16\u0E39\u0E01\u0E2D\u0E2D\u0E01\u0E08\u0E32\u0E01\u0E23\u0E30\u0E1A\u0E1A\u0E41\u0E25\u0E49\u0E27",
+    "\u0E16\u0E49\u0E32\u0E04\u0E38\u0E13\u0E44\u0E21\u0E48\u0E44\u0E14\u0E49\u0E40\u0E1B\u0E25\u0E35\u0E48\u0E22\u0E19\u0E40\u0E2D\u0E07 \u0E43\u0E2B\u0E49\u0E02\u0E2D\u0E15\u0E31\u0E49\u0E07\u0E23\u0E2B\u0E31\u0E2A\u0E1C\u0E48\u0E32\u0E19\u0E43\u0E2B\u0E21\u0E48\u0E17\u0E31\u0E19\u0E17\u0E35\u0E41\u0E25\u0E30\u0E41\u0E08\u0E49\u0E07\u0E1C\u0E39\u0E49\u0E14\u0E39\u0E41\u0E25\u0E23\u0E30\u0E1A\u0E1A"
+  ]) : email("Your password was changed", [
+    "The password of your account was just changed, and every device that was logged in has been signed out.",
+    "If it wasn't you, reset your password now and tell your administrator."
+  ])
+};
+
 // src/auth/password.ts
 import { randomBytes as randomBytes2, scrypt, timingSafeEqual as timingSafeEqual2 } from "crypto";
 var MIN_PASSWORD_LENGTH = 8;
@@ -657,9 +709,38 @@ function verifyPreviewToken(secret, token, now = Date.now()) {
     return null;
   }
 }
+function passwordFingerprint(passwordHash) {
+  return createHash2("sha256").update(typeof passwordHash === "string" ? passwordHash : "no-password").digest("base64url").slice(0, 22);
+}
+function signPasswordToken(secret, args) {
+  const payload = Buffer.from(
+    JSON.stringify({ u: args.userId, p: args.purpose, e: args.expiresAt })
+  ).toString("base64url");
+  return `${payload}.${hmac(secret, `password:${payload}:${args.fingerprint}`)}`;
+}
+function readPasswordToken(token) {
+  const dot = token.lastIndexOf(".");
+  if (dot <= 0) return null;
+  const payload = token.slice(0, dot);
+  try {
+    const data = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+    if (typeof data.u !== "string" || typeof data.e !== "number") return null;
+    if (data.p !== "reset" && data.p !== "invite") return null;
+    return { userId: data.u, purpose: data.p, expiresAt: data.e, payload };
+  } catch {
+    return null;
+  }
+}
+function passwordTokenMatches(secret, token, fingerprint) {
+  const dot = token.lastIndexOf(".");
+  if (dot <= 0) return false;
+  const payload = token.slice(0, dot);
+  return safeEqual(token.slice(dot + 1), hmac(secret, `password:${payload}:${fingerprint}`));
+}
 
 // src/auth/auth.ts
 var INVALID = "Invalid email or password";
+var RESET_REQUESTS = 3;
 var Auth = class {
   constructor(cms) {
     this.cms = cms;
@@ -673,13 +754,13 @@ var Auth = class {
   }
   /** Checks credentials and starts a session. Throws `UnauthorizedError` or `TooManyRequestsError`. */
   async login(args) {
-    const email = typeof args.email === "string" ? args.email.trim().toLowerCase() : "";
+    const email2 = typeof args.email === "string" ? args.email.trim().toLowerCase() : "";
     const password = typeof args.password === "string" ? args.password : "";
-    const key2 = `${email}|${args.ip ?? ""}`;
+    const key2 = `${email2}|${args.ip ?? ""}`;
     await this.checkRateLimit(key2);
-    const [user] = email ? (await this.db.find({
+    const [user] = email2 ? (await this.db.find({
       collection: USERS,
-      where: { email: { equals: email } },
+      where: { email: { equals: email2 } },
       sort: [],
       limit: 1,
       page: 1
@@ -759,6 +840,131 @@ var Auth = class {
     for (const session of sessions.docs)
       await this.db.delete({ collection: SESSIONS, id: session.id });
   }
+  // --- Password links: forgotten passwords and invitations ------------------------------------
+  /**
+   * 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) {
+    const configured = this.config.serverURL;
+    if (configured) return configured.replace(/\/+$/, "");
+    if (process.env.NODE_ENV !== "production" && origin) return origin;
+    return null;
+  }
+  /** Whether "forgot password" and invitations work: `email` is set and links have an origin. */
+  canSendPasswordLinks(origin) {
+    return this.config.email !== void 0 && this.passwordLinkBase(origin) !== null;
+  }
+  /**
+   * 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.
+   */
+  async requestPasswordReset(args) {
+    const email2 = typeof args.email === "string" ? args.email.trim().toLowerCase() : "";
+    if (!email2 || !this.canSendPasswordLinks(args.origin)) return;
+    const key2 = `reset:${email2}|${args.ip ?? ""}`;
+    const recent = await this.db.count({
+      collection: LOGIN_ATTEMPTS,
+      where: { key: { equals: key2 }, createdAt: { gt: this.windowStart() } }
+    });
+    if (recent >= RESET_REQUESTS) return;
+    await this.recordFailure(key2);
+    const user = await this.findByEmail(email2);
+    if (!user || user.active === false) return;
+    await this.mailPasswordLink(user, user.passwordHash ? "reset" : "invite", args);
+  }
+  /**
+   * 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.
+   */
+  async sendPasswordLink(userId, options = {}) {
+    if (!this.canSendPasswordLinks(options.origin))
+      throw new QueryError(
+        "Password links need `email` in the config, and `serverURL` in production"
+      );
+    const user = await this.db.findById({ collection: USERS, id: userId });
+    if (!user) throw new NotFoundError(USERS, userId);
+    if (user.active === false) throw new QueryError("This user is deactivated");
+    const purpose = user.passwordHash ? "reset" : "invite";
+    await this.mailPasswordLink(user, purpose, options);
+    return purpose;
+  }
+  /** The user and purpose of a valid, unused password link, or `null`. */
+  async checkPasswordToken(token) {
+    const found = await this.passwordTokenUser(token);
+    return found ? { user: await this.toAuthUser(found.user), purpose: found.purpose } : 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.
+   */
+  async resetPassword(args) {
+    const key2 = `reset-token|${args.ip ?? ""}`;
+    await this.checkRateLimit(key2);
+    const found = await this.passwordTokenUser(String(args.token ?? ""));
+    if (!found) {
+      await this.recordFailure(key2);
+      throw new ValidationError(USERS, [
+        { field: "token", message: "This link has expired or was already used" }
+      ]);
+    }
+    await this.cms.update(USERS, found.user.id, { password: args.password });
+    await this.clearFailures(key2);
+    const user = await this.db.findById({ collection: USERS, id: found.user.id });
+    const session = await this.startSession(user);
+    if (found.purpose === "reset") {
+      const content = await (this.config.auth.emails.passwordChanged ?? DEFAULT_PASSWORD_EMAILS.passwordChanged)({
+        user: await this.toAuthUser(user),
+        locale: this.localeOf(args.locale)
+      });
+      await this.cms.sendEmail({ to: String(user.email), ...content });
+    }
+    return { ...session, purpose: found.purpose };
+  }
+  async passwordTokenUser(token) {
+    const claims = readPasswordToken(token);
+    if (!claims || claims.expiresAt <= Date.now()) return null;
+    const id = /^\d+$/.test(claims.userId) ? Number(claims.userId) : claims.userId;
+    const user = await this.db.findById({ collection: USERS, id });
+    if (!user || user.active === false) return null;
+    const fingerprint = passwordFingerprint(user.passwordHash);
+    if (!passwordTokenMatches(this.config.secret, token, fingerprint)) return null;
+    return { user, purpose: claims.purpose };
+  }
+  async mailPasswordLink(user, purpose, options) {
+    const base = this.passwordLinkBase(options.origin);
+    const seconds = purpose === "invite" ? this.config.auth.inviteExpiration : this.config.auth.resetPasswordExpiration;
+    const expiresAt = Date.now() + seconds * 1e3;
+    const token = signPasswordToken(this.config.secret, {
+      userId: String(user.id),
+      purpose,
+      expiresAt,
+      fingerprint: passwordFingerprint(user.passwordHash)
+    });
+    const url = `${base}${this.config.admin.path}/reset-password?token=${encodeURIComponent(token)}`;
+    const write = purpose === "invite" ? this.config.auth.emails.invite ?? DEFAULT_PASSWORD_EMAILS.invite : this.config.auth.emails.resetPassword ?? DEFAULT_PASSWORD_EMAILS.resetPassword;
+    const content = await write({
+      user: await this.toAuthUser(user),
+      url,
+      locale: this.localeOf(options.locale),
+      expiresAt: new Date(expiresAt)
+    });
+    await this.cms.sendEmail({ to: String(user.email), ...content });
+  }
+  localeOf(locale) {
+    return locale === "th" || locale === "en" ? locale : this.config.admin.locale;
+  }
+  async findByEmail(email2) {
+    const { docs } = await this.db.find({
+      collection: USERS,
+      where: { email: { equals: email2 } },
+      sort: [],
+      limit: 1,
+      page: 1
+    });
+    return docs[0];
+  }
   /** The owner of an API key, limited by the key; `null` when unknown, expired or disabled. */
   async verifyApiKey(token) {
     if (!this.cms.config.collections.some((c) => c.slug === API_KEYS)) return null;
@@ -1801,12 +2007,36 @@ function validateAuth(config, add) {
       add("auth.roles", 'must include "admin"', "e.g. roles: ['admin', 'editor']");
     }
   }
-  for (const key2 of ["tokenExpiration", "maxLoginAttempts", "lockWindow"]) {
+  for (const key2 of [
+    "tokenExpiration",
+    "maxLoginAttempts",
+    "lockWindow",
+    "resetPasswordExpiration",
+    "inviteExpiration"
+  ]) {
     const value = auth[key2];
     if (value !== void 0 && !(Number.isInteger(value) && value > 0)) {
       add(`auth.${key2}`, "must be a positive integer");
     }
   }
+  if (auth.emails !== void 0) {
+    const emails = auth.emails;
+    if (typeof emails !== "object" || emails === null) add("auth.emails", "must be an object");
+    else
+      for (const [name, fn] of Object.entries(emails)) {
+        if (!["resetPassword", "invite", "passwordChanged"].includes(name))
+          add(
+            `auth.emails.${name}`,
+            "unknown email",
+            "use resetPassword, invite or passwordChanged"
+          );
+        else if (typeof fn !== "function")
+          add(
+            `auth.emails.${name}`,
+            "must be a function ({ user, url, locale }) => { subject, text }"
+          );
+      }
+  }
   if (auth.trustedOrigins !== void 0) {
     for (const [i, origin] of auth.trustedOrigins.entries()) {
       if (typeof origin !== "string" || !/^https?:\/\/[^/]+$/.test(origin)) {
@@ -1898,8 +2128,8 @@ function validateLocalization(config, add) {
   for (const [i, g] of (config.globals ?? []).entries()) walk(g?.fields, `globals[${i}].fields`);
 }
 function validateWebhooks(config, add) {
-  const email = config.email;
-  if (email !== void 0 && (typeof email !== "object" || email === null || typeof email.send !== "function"))
+  const email2 = config.email;
+  if (email2 !== void 0 && (typeof email2 !== "object" || email2 === null || typeof email2.send !== "function"))
     add(
       "email",
       "must be an email adapter with a send() function",
@@ -2400,7 +2630,10 @@ async function resolveConfig(input) {
       tokenExpiration: config.auth?.tokenExpiration ?? DEFAULT_TOKEN_EXPIRATION,
       maxLoginAttempts: config.auth?.maxLoginAttempts ?? 5,
       lockWindow: config.auth?.lockWindow ?? 15 * 60,
-      trustedOrigins: config.auth?.trustedOrigins ?? []
+      trustedOrigins: config.auth?.trustedOrigins ?? [],
+      resetPasswordExpiration: config.auth?.resetPasswordExpiration ?? 60 * 60,
+      inviteExpiration: config.auth?.inviteExpiration ?? 7 * 24 * 60 * 60,
+      emails: config.auth?.emails ?? {}
     },
     collections: [
       ...config.collections ?? [],
@@ -3645,18 +3878,18 @@ var EasyCMS = class {
   /** Emails queued until sent, stored in `email-deliveries`. */
   emailQueue() {
     const collection2 = EMAIL_DELIVERIES;
-    const toRow = (email, createdAt) => {
+    const toRow = (email2, createdAt) => {
       const now = (/* @__PURE__ */ new Date()).toISOString();
-      return { ...email, createdAt: createdAt ?? now, updatedAt: now };
+      return { ...email2, createdAt: createdAt ?? now, updatedAt: now };
     };
     return {
-      add: async (email) => (await this.db.create({ collection: collection2, data: toRow(email) })).id,
-      update: async (id, email) => {
+      add: async (email2) => (await this.db.create({ collection: collection2, data: toRow(email2) })).id,
+      update: async (id, email2) => {
         const current = await this.db.findById({ collection: collection2, id });
         await this.db.update({
           collection: collection2,
           id,
-          data: toRow(email, current?.createdAt)
+          data: toRow(email2, current?.createdAt)
         });
       },
       remove: async (id) => {
@@ -4041,9 +4274,6 @@ var EasyCMS = class {
       if (!allowed2) throw deny(guard.user);
     }
     const { input, password } = splitPassword(config, raw);
-    if (config.slug === USERS && password === void 0) {
-      throw new ValidationError(collection2, [{ field: "password", message: "is required" }]);
-    }
     const filtered = await filterInput(
       config.fields,
       input,
@@ -4622,12 +4852,13 @@ async function global(config, user, localized) {
   if (config.admin?.sidebar?.length) result.sidebar = config.admin.sidebar.map(componentRef);
   return result;
 }
-async function adminSchema(cms, user) {
+async function adminSchema(cms, user, origin) {
   const collections = cms.config.collections.filter((c) => !INTERNAL_COLLECTIONS.has(c.slug));
   const localization = cms.config.localization;
   const localized = localization !== null;
   return {
     locale: cms.config.admin.locale,
+    passwordLinks: cms.auth.canSendPasswordLinks(origin),
     menu: [...cms.config.admin.menu],
     localization: localization ? { locales: [...localization.locales], defaultLocale: localization.defaultLocale } : null,
     collections: await Promise.all(collections.map((c) => collection(c, user, localized))),
@@ -4937,7 +5168,46 @@ async function route(cms, ctx, method, segments, options) {
         return { body: { user: ctx.user, ...csrfToken2 ? { csrfToken: csrfToken2 } : {} } };
       }
       case "GET init":
-        return { body: { hasUsers: await cms.auth.hasUsers() } };
+        return {
+          body: {
+            hasUsers: await cms.auth.hasUsers(),
+            // The login page offers "Forgot password?" only when the email can be sent.
+            passwordReset: cms.auth.canSendPasswordLinks(ctx.url.origin)
+          }
+        };
+      // Forgot password: the same answer whether or not the email has an account.
+      case "POST forgot-password": {
+        const body = await readJson(ctx.request);
+        await cms.auth.requestPasswordReset({
+          email: String(body.email ?? ""),
+          ip: options.getClientIp?.(ctx.request),
+          origin: ctx.url.origin,
+          locale: typeof body.locale === "string" ? body.locale : void 0
+        });
+        return { body: { message: "If an account has this email, a link is on its way." } };
+      }
+      // The page behind a password link: which account, and whether the link still works.
+      case "GET reset-password": {
+        const found = await cms.auth.checkPasswordToken(ctx.url.searchParams.get("token") ?? "");
+        if (!found)
+          throw new ValidationError(USERS, [
+            { field: "token", message: "This link has expired or was already used" }
+          ]);
+        return { body: { email: found.user.email, purpose: found.purpose } };
+      }
+      case "POST reset-password": {
+        const body = await readJson(ctx.request);
+        const session = await cms.auth.resetPassword({
+          token: String(body.token ?? ""),
+          password: String(body.password ?? ""),
+          ip: options.getClientIp?.(ctx.request),
+          locale: typeof body.locale === "string" ? body.locale : void 0
+        });
+        setSessionCookies(cms, ctx, session);
+        return {
+          body: { user: session.user, exp: session.expiresAt, csrfToken: session.csrfToken }
+        };
+      }
       case "POST first-register": {
         const body = await readJson(ctx.request);
         const session = await cms.auth.registerFirstUser({
@@ -4968,7 +5238,7 @@ async function route(cms, ctx, method, segments, options) {
     if (method !== "GET") throw methodNotAllowed(ctx, "GET");
     if (!ctx.user) throw new UnauthorizedError();
     if (second === "schema" && third === void 0)
-      return { body: await adminSchema(cms, ctx.user) };
+      return { body: await adminSchema(cms, ctx.user, ctx.url.origin) };
     if (second === "modules" && third !== void 0 && segments.length === 3) {
       const index = /^(\d+)\.js$/.exec(third)?.[1];
       const file = index === void 0 ? void 0 : await readAdminModule(cms, Number(index));
@@ -5104,6 +5374,16 @@ async function documentAction(cms, ctx, method, collection2, id, path) {
   const access = { overrideAccess: false, user: ctx.user, ...parseLocale(ctx.url) };
   const depth = parseDepth(ctx.url);
   const [action, versionId, extra] = path;
+  if (collection2 === USERS && action === "password-link" && path.length === 1) {
+    if (method !== "POST") throw methodNotAllowed(ctx, "POST");
+    if (ctx.user?.role !== "admin" || ctx.user.apiKey) throw new ForbiddenError();
+    const body = await readJson(ctx.request).catch(() => ({}));
+    const sent = await cms.auth.sendPasswordLink(/^\d+$/.test(id) ? Number(id) : id, {
+      origin: ctx.url.origin,
+      locale: typeof body.locale === "string" ? body.locale : void 0
+    });
+    return { body: { sent } };
+  }
   if (action === "versions" && versionId === void 0) {
     if (method !== "GET") throw methodNotAllowed(ctx, "GET");
     return { body: await cms.findVersions(collection2, id, { ...access, ...parsePage(ctx.url) }) };
@@ -5547,6 +5827,7 @@ export {
   DEFAULT_DEPTH,
   DEFAULT_MAX_FILE_SIZE,
   DEFAULT_MAX_VERSIONS,
+  DEFAULT_PASSWORD_EMAILS,
   DEFAULT_TOKEN_EXPIRATION,
   EXTENSIONS,
   EasyCMS,

package/package.json

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