kempo 4.7.0 → 4.9.0

package/docker/entrypoint.mjs

@@ -0,0 +1,96 @@
+import { spawn, spawnSync } from 'child_process';
+import { createReadStream, existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { createGunzip } from 'zlib';
+import { pipeline } from 'stream/promises';
+import { countAttempt, paths, performSwitch, restoreFiles, rollBack, seedSite, shouldRollBack } from './siteLayout.js';
+
+/*
+  The image's startup script. It runs before the site, as the container's main process, and does what must not be left to
+  the site itself:
+
+    1. First start: fills the volume from the image (/seed) with the site as it was built.
+    2. A new version waiting (state/switch.json asked for it): moves its code into place, while nothing is running.
+    3. A new version that has not proved itself and keeps stopping, or says it failed: puts the previous code back,
+       the files an update changed, and the database too when the update changed data (from the backup it took first).
+    4. After a change of Node version: rebuilds the compiled modules (bcrypt) the volume was built with.
+    5. Starts the site, passes signals to it and ends with its exit code, so the container's restart policy sees what
+       the site did (the site ends with 75 to ask for a restart after an update).
+
+  Environment: KEMPO_SITE_ROOT (the volume, /site), KEMPO_SEED (the site as built, /seed), KEMPO_START_COMMAND (default
+  `npm start`, or a JSON array when a path has spaces), and DATABASE_URL, which a database restore needs.
+*/
+const siteRoot = process.env.KEMPO_SITE_ROOT || '/site';
+const seed = process.env.KEMPO_SEED || '/seed';
+const { app, state } = paths(siteRoot);
+
+const say = message => console.log(`[kempo] ${message}`);
+
+/* Puts a backup taken before a data-changing update back: a plain-SQL dump, gzipped, with its own DROP statements. */
+const restoreDatabase = async file => {
+  if(!file || !existsSync(file)) return false;
+  const psql = spawn('psql', ['-v', 'ON_ERROR_STOP=1', '-q', process.env.DATABASE_URL], { stdio: ['pipe', 'inherit', 'inherit'] });
+  const finished = new Promise((resolve, reject) => {
+    psql.on('error', reject);
+    psql.on('exit', code => (code === 0 ? resolve() : reject(new Error(`psql ended with ${code}`))));
+  });
+  await Promise.all([pipeline(createReadStream(file), createGunzip(), psql.stdin), finished]);
+  return true;
+};
+
+const goBack = async reason => {
+  say(`The new version of Kempo is not working (${reason}). Going back to the one before it.`);
+  const result = rollBack({ siteRoot, reason });
+  if(!result.ok){
+    say(result.reason);
+    return;
+  }
+  say(`Back on Kempo ${result.to}.`);
+  if(result.dbBackup){
+    try {
+      say('Restoring the database from the backup taken before the update.');
+      await restoreDatabase(result.dbBackup);
+    } catch(error) {
+      say(`The database could not be restored (${error.message}). The backup is at ${result.dbBackup}.`);
+    }
+  }
+};
+
+if(seedSite({ siteRoot, seed })) say('First start: the site was copied onto the volume.');
+
+const switched = performSwitch(siteRoot);
+if(switched){
+  say(`Kempo ${switched.from.version} -> ${switched.version}.`);
+  if(switched.kind === 'rollback'){
+    restoreFiles({ siteRoot, backup: switched.filesBackup });
+    if(switched.dbBackup){
+      try {
+        say('Restoring the database from the backup taken before the update.');
+        await restoreDatabase(switched.dbBackup);
+      } catch(error) {
+        say(`The database could not be restored (${error.message}). The backup is at ${switched.dbBackup}.`);
+      }
+    }
+  }
+}
+
+const counted = countAttempt(siteRoot);
+if(shouldRollBack(counted)) await goBack(counted.failed ? counted.failure || 'a data migration failed' : 'it stopped too many times');
+
+const nodeFile = join(state, 'node-version');
+const builtWith = existsSync(nodeFile) ? readFileSync(nodeFile, 'utf8').trim() : null;
+if(builtWith && builtWith !== process.version){
+  say(`Node changed from ${builtWith} to ${process.version}: rebuilding compiled modules.`);
+  spawnSync('npm', ['rebuild'], { cwd: app, stdio: 'inherit' });
+}
+mkdirSync(state, { recursive: true });
+writeFileSync(nodeFile, process.version);
+
+const startCommand = process.env.KEMPO_START_COMMAND || 'npm start';
+const [command, ...args] = startCommand.startsWith('[') ? JSON.parse(startCommand) : startCommand.split(' ');
+const site = spawn(command, args, { cwd: app, stdio: 'inherit', env: { ...process.env, KEMPO_SITE_ROOT: siteRoot } });
+
+for(const signal of ['SIGTERM', 'SIGINT']){
+  process.on(signal, () => site.kill(signal));
+}
+site.on('exit', (code, signal) => process.exit(code ?? (signal ? 1 : 0)));

package/middleware/kempo.js

@@ -13,6 +13,16 @@ import triggerHook from '../server/utils/hooks/triggerHook.js';
 import { ADMIN_GLOBALS_DIR } from '../server/utils/admin-global-content/helpers.js';
 import { startScheduler } from '../server/utils/scheduler/scheduler.js';
 import { ensureEncryptionKey } from '../server/utils/settings/ensureEncryptionKey.js';
+import syncCoreSchema from '../server/utils/setup/syncCoreSchema.js';
+import runUpgrades from '../server/utils/setup/runUpgrades.js';
+import seedIfNew from '../server/utils/setup/seedIfNew.js';
+import reconcileExtensions from '../server/utils/extensions/reconcileExtensions.js';
+import { flagFailed, markHealthy } from '../server/utils/updates/siteLayout.js';
+import notifySchemaAttention from '../server/utils/updates/notifySchemaAttention.js';
+import { ensureSystemSettings } from '../server/utils/settings/systemSettings.js';
+import { ensureSystemPermissions } from '../server/utils/setup/systemPermissions.js';
+import registerJobs from '../server/utils/scheduler/registerJobs.js';
+import '../server/utils/updates/runtime.js';
 import { resolveAlias } from '../server/utils/extensions/aliases.js';
 import { normalizeScopes } from '../server/utils/extensions/scopes.js';
 
@@ -184,6 +194,11 @@ const serveDir = async (dirPath, method, request, response, resolveDir, rootDir,
 export default config => {
   startScheduler();
 
+  /* A site that runs from a Docker volume has just switched to new code: once it has stayed up a minute the switch is final. */
+  if(process.env.KEMPO_SITE_ROOT && process.env.KEMPO_DB !== 'pglite'){
+    setTimeout(() => markHealthy(process.env.KEMPO_SITE_ROOT), 60000).unref();
+  }
+
   /*
     The key that encrypts stored credentials exists before any request needs it, generated into .env the
     first time when the site has none. Opt out with `autoEncryptionKey: false` in the server config or
@@ -194,6 +209,61 @@ export default config => {
     : ensureEncryptionKey().then(([error]) => {
       if(error) console.error(`[kempo] ${error.msg}`);
     });
+  /*
+    What kempo added in a later version appears on an older site at start: its tables and columns (additive only, see syncCoreSchema), its settings (so they show on the settings screen and can be
+    edited), its permissions, and its own scheduled jobs (the email retries and cleanup, and the check for a newer kempo). Only what is missing is added, and never in
+    the in-memory test database (nothing is set up there yet).
+  */
+  const systemSettingsReady = process.env.KEMPO_DB === 'pglite'
+    ? Promise.resolve()
+    : (async () => {
+      for(const [step, run] of [
+        ['schema', async () => {
+          const [error, result] = await syncCoreSchema();
+          if(result?.applied.length) console.log(`[kempo] Database brought up to date: ${result.applied.join('; ')}`);
+          for(const { change, reason } of result?.failed ?? []) console.error(`[kempo] Database change failed: ${change}: ${reason}`);
+          return [error];
+        }],
+        ['seed', async () => {
+          const [error, result] = await seedIfNew();
+          if(result?.seeded) console.log('[kempo] New database: its groups, permissions and settings were set up. Open /setup to create the first administrator.');
+          return [error];
+        }],
+        ['upgrades', async () => {
+          const [error, result] = await runUpgrades();
+          if(result?.ran.length) console.log(`[kempo] Data migrations run: ${result.ran.join(', ')}`);
+          if(error){
+            console.error(`[kempo] ${error.msg}`);
+            if(error.breaking && process.env.KEMPO_SITE_ROOT){
+              flagFailed({ siteRoot: process.env.KEMPO_SITE_ROOT, reason: error.msg });
+              process.exit(1);
+            }
+          }
+          return [null];
+        }],
+        ['settings', ensureSystemSettings],
+        ['permissions', ensureSystemPermissions],
+        ['extensions', async () => {
+          const [error, result] = await reconcileExtensions();
+          for(const { name, from, to } of result?.upgraded ?? []) console.log(`[kempo] Extension ${name} brought up to date: ${from} -> ${to}`);
+          for(const { name, from, to } of result?.reverted ?? []) console.log(`[kempo] Extension ${name} is back on ${to} (was ${from})`);
+          for(const { name, reason } of result?.failed ?? []) console.error(`[kempo] Extension ${name} could not be brought up to date: ${reason}`);
+          if(result?.failed.some(item => item.major) && process.env.KEMPO_SITE_ROOT){
+            flagFailed({ siteRoot: process.env.KEMPO_SITE_ROOT, reason: result.failed.filter(item => item.major).map(item => `${item.name}: ${item.reason}`).join('; ') });
+            process.exit(1);
+          }
+          return [error];
+        }],
+        ['schema notice', notifySchemaAttention],
+        ['jobs', () => registerJobs({ owner: 'kempo', jobs: [
+          { name: 'email-maintenance', every: '1m', callback: './server/utils/email/maintainEmails.js' },
+          { name: 'update-check', every: '12h', callback: './server/utils/updates/runUpdateCheck.js' },
+        ] })],
+      ]){
+        const [error] = await run();
+        if(error) console.error(`[kempo] System ${step}: ${error.msg}`);
+      }
+    })();
   const PROJECT_PUBLIC = config.rootPath || join(process.cwd(), 'public');
   const ADMIN_ROOT = resolveAdminRoot(config.adminRoot);
 
@@ -206,6 +276,7 @@ export default config => {
 
   return async (request, response, next) => {
     await encryptionKeyReady;
+    await systemSettingsReady;
     const { path } = request;
     const url = request.url.split('?')[0];
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kempo",
-  "version": "4.7.0",
+  "version": "4.9.0",
   "type": "module",
   "description": "A fullstack CMS framework for creating websites with user authentication",
   "scripts": {
@@ -33,6 +33,8 @@
     "server/utils",
     "server/db/index.js",
     "server/db/schema.js",
+    "server/db/upgrades",
+    "docker",
     "server/sdk.js",
     "middleware/kempo.js",
     "app-templates",
@@ -54,8 +56,7 @@
     "inquirer": "^14.0.2",
     "lexical": "0.43.0",
     "monaco-editor": "^0.56.0",
-    "postgres": "^3.4.7",
-    "resend": "^6.5.2"
+    "postgres": "^3.4.7"
   },
   "peerDependencies": {
     "kempo-css": ">=2.2.5",

package/server/db/schema.js

@@ -115,6 +115,18 @@ export const extension = pgTable('extension', {
   updatedAt: timestamp('updatedAt').notNull(),
 });
 
+/*
+  Which of kempo's own data migrations (server/db/upgrades/*.js) have run on this database. The additive changes to its
+  tables need no record, they are found by comparing; a migration that restructures data runs once and is recorded here.
+  The row with id 'baseline' marks the database as already holding what the shipped migrations produce.
+*/
+export const upgrade = pgTable('upgrade', {
+  id: text('id').primaryKey(),
+  description: text('description'),
+  breaking: boolean('breaking').notNull().default(false),
+  appliedAt: timestamp('appliedAt').notNull().defaultNow(),
+});
+
 /*
   Scheduled jobs: recurring work an extension declares in its kempo-config.json `jobs`. A row per job
   is the schedule and the lease: `nextRunAt` is when it is next due and `lockedUntil` is held while a
@@ -138,6 +150,38 @@ export const scheduledJob = pgTable('scheduledJob', {
   index('scheduledJob_next_idx').on(table.nextRunAt),
 ]);
 
+/*
+  Email
+
+  Every email kempo is asked to send is a row here before anything is sent, so there is always a record of what was
+  sent, to whom, and what happened. Kempo itself sends nothing: it fires the `email:send` hook and an email extension
+  (kempo-resend, kempo-smtp...) sends it.
+
+  `status` is `queued` (waiting for a sender, or for a retry), `sending` (a sender is working on it now), `sent` or
+  `failed` (no attempts left). `type` is the template it was made from (`verify-email`, `kempo-commerce/order-processing`)
+  or `other`, and is what the retention settings are keyed by. `html` is the whole email, which can hold links that
+  sign someone in or set a password, so reading the log needs its own permission.
+*/
+export const email = pgTable('email', {
+  id: text('id').primaryKey(),
+  type: text('type').notNull().default('other'),
+  recipient: text('recipient').notNull(),
+  sender: text('sender').notNull(),
+  subject: text('subject').notNull(),
+  html: text('html').notNull(),
+  status: text('status').notNull().default('queued'),
+  attempts: integer('attempts').notNull().default(0),
+  lastError: text('lastError'),
+  provider: text('provider'),
+  providerRef: text('providerRef'),
+  createdAt: timestamp('createdAt').notNull(),
+  updatedAt: timestamp('updatedAt').notNull(),
+  sentAt: timestamp('sentAt'),
+}, table => [
+  index('email_status_idx').on(table.status, table.updatedAt),
+  index('email_createdAt_idx').on(table.createdAt),
+]);
+
 /*
   Realtime System
 */

package/server/db/upgrades/README.md

@@ -0,0 +1,20 @@
+# Data migrations
+
+Additive changes to kempo's tables (new tables, columns, indexes) need nothing here: they are applied when the server starts.
+A change that restructures or moves data goes in a file in this folder, named so that they sort in the order they must run:
+
+    4.9.0-split-user-name.js
+
+```js
+export const meta = { description: 'Splits user.name into first and last', breaking: true };
+
+export const up = async ({ db, sql }) => {
+  await db.execute(sql`...`);
+};
+```
+
+- It runs once, inside a transaction, when the first server of the new version starts, and is recorded in the `upgrade` table.
+- `breaking: true` is for anything the previous version cannot run against (data moved or removed). The Updates screen warns
+  before such an update, kempo backs the database up first, and a failure puts the previous version and that backup back.
+- Add one only in a release whose version is higher than the first one that has this folder: a site's `upgrade` table starts with
+  every file that was here when it first started recorded as already run.

package/server/sdk.js

@@ -186,6 +186,11 @@ export { startScheduler, stopScheduler } from './utils/scheduler/scheduler.js';
 export { default as sendEmail } from './utils/email/sendEmail.js';
 export { default as sendEmailFromTemplate } from './utils/email/sendEmailFromTemplate.js';
 export { default as renderEmailTemplate } from './utils/email/renderEmailTemplate.js';
+export { default as getSenderEmail } from './utils/email/getSenderEmail.js';
+export { default as listEmails } from './utils/email/listEmails.js';
+export { default as getEmail } from './utils/email/getEmail.js';
+export { default as retryEmail } from './utils/email/retryEmail.js';
+export { default as pruneEmails } from './utils/email/pruneEmails.js';
 
 /*
   Filesystem Utilities
@@ -216,6 +221,9 @@ export { default as installExtension } from './utils/extensions/installExtension
 export { default as listExtensions } from './utils/extensions/listExtensions.js';
 export { default as uninstallExtension } from './utils/extensions/uninstallExtension.js';
 export { default as updateExtension } from './utils/extensions/updateExtension.js';
+export { default as upgradeExtension } from './utils/extensions/upgradeExtension.js';
+export { default as reconcileExtensions } from './utils/extensions/reconcileExtensions.js';
+export { default as writeSiteFile } from './utils/extensions/writeSiteFile.js';
 
 /*
   Notifications

package/server/utils/email/defaultSender.js

@@ -0,0 +1,2 @@
+/* The sender kempo uses until the site sets its own. Providers refuse it, so an email extension that knows a better one (the mailbox it signs in with) can use that instead, see `fromIsDefault`. */
+export default 'noreply@example.com';

package/server/utils/email/dispatchEmail.js

@@ -0,0 +1,56 @@
+import db from '../../db/index.js';
+import { email } from '../../db/schema.js';
+import { and, eq, sql } from 'drizzle-orm';
+import triggerHook from '../hooks/triggerHook.js';
+import emailSettings from './emailSettings.js';
+import defaultSender from './defaultSender.js';
+
+export const SEND_HOOK = 'email:send';
+
+/*
+  One try at sending a queued email.
+
+  The email is taken (queued -> sending, one conditional UPDATE, so of several processes only one sends it) and the `email:send`
+  hook is fired with `{ email }`. Each email extension answers with what it did, and the first to say it sent it ends the chain, so
+  with several installed only one sends and a failed one hands the email to the next:
+
+    export default async ({ email }) => ({ sent: true, provider: 'my-sender', messageId: 'abc' });   // it went
+    export default async ({ email }) => ({ sent: false, error: 'Mailbox full' });                    // it tried and could not (throwing says the same)
+    export default async ({ email }) => ({ sent: false, skipped: true, error: 'No API key is saved' }); // it is not set up, so it did not try
+
+  `email` is `{ id, to, from, fromIsDefault, subject, html, type, attempt }`; `fromIsDefault` says the site has not set its own sender, so
+  `from` is only a placeholder and a sender that knows a better one (the mailbox it signs in with) can use that. A handler sends the email and returns; it never touches the log, which
+  kempo keeps. After the chain the email is `sent`, or goes back to `queued` for a retry, or is `failed` when it has no tries left
+  (the first try plus `email_max_retries`). Resolves like sendEmail.
+*/
+const finish = async (id, changes) => {
+  const [row] = await db.update(email).set({ ...changes, updatedAt: new Date() }).where(eq(email.id, id)).returning();
+  return row;
+};
+
+export default async id => {
+  const [claimed] = await db.update(email)
+    .set({ status: 'sending', attempts: sql`${email.attempts} + 1`, updatedAt: new Date() })
+    .where(and(eq(email.id, id), eq(email.status, 'queued')))
+    .returning();
+  if(!claimed) return [{ code: 409, msg: 'That email is not waiting to be sent', emailId: id }, null];
+
+  const [hookError, fired] = await triggerHook(SEND_HOOK, { email: { id: claimed.id, to: claimed.recipient, from: claimed.sender, fromIsDefault: claimed.sender === defaultSender, subject: claimed.subject, html: claimed.html, type: claimed.type, attempt: claimed.attempts } }, { stopWhen: result => result?.sent === true });
+  const results = fired?.results ?? [];
+  const sent = results.find(entry => entry.result?.sent === true);
+
+  if(sent){
+    await finish(id, { status: 'sent', sentAt: new Date(), lastError: null, provider: String(sent.result.provider ?? sent.owner).slice(0, 100), providerRef: sent.result.messageId ? String(sent.result.messageId).slice(0, 200) : null });
+    return [null, { id, status: 'sent', provider: sent.result.provider ?? sent.owner }];
+  }
+
+  /* An extension that is not set up says so and is not counted as having tried: its reason is only shown when nothing else did. */
+  const said = entry => `${entry.owner}: ${entry.error ?? entry.result?.error ?? 'did not send it'}`;
+  const tried = results.filter(entry => !entry.result?.skipped);
+  const reasons = hookError ? [hookError.msg] : (tried.length ? tried : results).map(said);
+  const message = (tried.length || hookError ? reasons.join('; ') : results.length ? `No email extension is set up yet. ${reasons.join('; ')}` : '') || 'No email extension is installed to send email (install kempo-resend or kempo-smtp)';
+  const { maxRetries } = await emailSettings();
+  const final = claimed.attempts >= 1 + maxRetries;
+  await finish(id, { status: final ? 'failed' : 'queued', lastError: message.slice(0, 1000) });
+  return [{ code: tried.length ? 502 : 503, msg: message, emailId: id }, null];
+};

package/server/utils/email/emailSettings.js

@@ -0,0 +1,21 @@
+import getSetting from '../settings/getSetting.js';
+
+const DEFAULT_RETRIES = 1;
+const DEFAULT_RETENTION_DAYS = 30;
+
+const whole = (value, fallback) => (Number.isInteger(Number(value)) && value !== '' && value !== null && Number(value) >= 0 ? Number(value) : fallback);
+
+/*
+  What the email settings say, with a safe value for anything unreadable: `maxRetries` (tries after the first), `retentionDays` (0 keeps
+  forever) and `retentionByType` ({ type: days }), which wins over `retentionDays` for that kind of email.
+*/
+export default async () => {
+  const [, retries] = await getSetting('system', 'email_max_retries', DEFAULT_RETRIES);
+  const [, days] = await getSetting('system', 'email_retention_days', DEFAULT_RETENTION_DAYS);
+  const [, byType] = await getSetting('system', 'email_retention_by_type', {});
+  const retentionByType = {};
+  if(byType && typeof byType === 'object' && !Array.isArray(byType)){
+    for(const [type, value] of Object.entries(byType)) if(whole(value, null) !== null) retentionByType[type] = Number(value);
+  }
+  return { maxRetries: whole(retries, DEFAULT_RETRIES), retentionDays: whole(days, DEFAULT_RETENTION_DAYS), retentionByType };
+};

package/server/utils/email/emailTemplatePaths.js

@@ -0,0 +1,36 @@
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const PART = '[a-z0-9][a-z0-9-]*';
+const NAME = new RegExp(`^(?:(${PART})/)?(${PART})$`);
+
+/*
+  Where an email template lives, the same places renderEmailTemplate looks:
+
+    "owner/name"  the extension's own `node_modules/owner/emails/name.page.html`, which the site overrides at
+                  `templates/emails/owner/name.page.html`
+    "name"        kempo's own `app-templates/emails/name.page.html`, which the site overrides at
+                  `templates/emails/name.page.html`
+*/
+export const parseTemplateName = template => {
+  const match = typeof template === 'string' ? NAME.exec(template) : null;
+  return match ? { owner: match[1] ?? null, name: match[2] } : null;
+};
+
+export const siteEmailsDir = owner => (owner ? join(process.cwd(), 'templates/emails', owner) : join(process.cwd(), 'templates/emails'));
+
+export const defaultEmailsDir = owner => (owner ? join(process.cwd(), 'node_modules', owner, 'emails') : join(here, '../../../app-templates/emails'));
+
+export const locateTemplate = template => {
+  const parsed = parseTemplateName(template);
+  if(!parsed) return null;
+  return { ...parsed, template, sitePath: join(siteEmailsDir(parsed.owner), `${parsed.name}.page.html`), defaultPath: join(defaultEmailsDir(parsed.owner), `${parsed.name}.page.html`) };
+};
+
+export const isOwnerName = owner => new RegExp(`^${PART}$`).test(owner);
+
+/* The page's `title`, which is what a list shows as the email's name. */
+export const titleOf = source => /<page\b[^>]*\stitle="([^"]*)"/.exec(source)?.[1] ?? '';
+
+export const sameSource = (a, b) => String(a).replace(/\r\n/g, '\n').trim() === String(b).replace(/\r\n/g, '\n').trim();

package/server/utils/email/getEmail.js

@@ -0,0 +1,14 @@
+import db from '../../db/index.js';
+import { email } from '../../db/schema.js';
+import { eq } from 'drizzle-orm';
+
+/* One email of the log, with its whole body. Resolves to [error, email]. */
+export default async id => {
+  if(!id) return [{ code: 400, msg: 'An email id is required' }, null];
+  try {
+    const [row] = await db.select().from(email).where(eq(email.id, String(id))).limit(1);
+    return row ? [null, row] : [{ code: 404, msg: 'Email not found' }, null];
+  } catch {
+    return [{ code: 500, msg: 'Failed to read the email' }, null];
+  }
+};

package/server/utils/email/getSenderEmail.js

@@ -0,0 +1,11 @@
+import getSenderFrom from './getSenderFrom.js';
+
+/*
+  The bare address kempo sends its emails from (`shop@example.com`, out of `Shop <shop@example.com>`), for an extension that needs
+  one for the site, such as a shipping label's sender. It is the same address emails go out from (see getSenderFrom), so it is a
+  placeholder (noreply@example.com) until the site sets one. Resolves to the address, or null if there is none to find.
+*/
+export default async () => {
+  const from = (await getSenderFrom()).trim();
+  return (/<([^<>\s]+@[^<>\s]+)>/.exec(from) ?? /^([^<>\s]+@[^<>\s]+)$/.exec(from))?.[1] ?? null;
+};

package/server/utils/email/getSenderFrom.js

@@ -0,0 +1,18 @@
+import getSetting from '../settings/getSetting.js';
+import isValidSender from './isValidSender.js';
+import PLACEHOLDER from './defaultSender.js';
+
+/*
+  What kempo sends its emails from, as the email provider takes it. In order:
+
+    the `system:email_from` setting   edited on the admin Settings screen (it must be a valid address, or empty)
+    `EMAIL_FROM`                      the server environment; what the README and `kempo init` write
+    `SMTP_FROM`                       what the environment used to be called
+    a placeholder address (noreply@example.com), which most providers will refuse until the site sets its own
+
+  A value that is not an address is skipped rather than sent, so a bad environment value cannot stop every email.
+*/
+export default async () => {
+  const [, stored] = await getSetting('system', 'email_from', '');
+  return [stored, process.env.EMAIL_FROM, process.env.SMTP_FROM].map(value => String(value ?? '').trim()).find(isValidSender) ?? PLACEHOLDER;
+};

package/server/utils/email/isValidSender.js

@@ -0,0 +1,4 @@
+/* Whether text can be the address emails are sent from: `name@example.com` or `Shop Name <name@example.com>`, on one line. */
+export default value => typeof value === 'string'
+  && value.length <= 200
+  && /^(?:[^<>\r\n@]+<[^<>\s@]+@[^<>\s@]+\.[^<>\s@]+>|[^<>\s@]+@[^<>\s@]+\.[^<>\s@]+)$/.test(value.trim());

package/server/utils/email/listEmailTemplates.js

@@ -0,0 +1,23 @@
+import { readdir } from 'fs/promises';
+import { defaultEmailsDir, isOwnerName, siteEmailsDir } from './emailTemplatePaths.js';
+import readEmailTemplate from './readEmailTemplate.js';
+
+const SUFFIX = '.page.html';
+
+const namesIn = async dir => (await readdir(dir).catch(() => [])).filter(file => file.endsWith(SUFFIX)).map(file => file.slice(0, -SUFFIX.length));
+
+/*
+  The email templates of one extension (`owner`), or kempo's own and the site's (no owner): the packaged ones, and any the site has
+  added. Resolves to [error, [{ template, name, title, overridden, packaged }]] sorted by name.
+*/
+export default async ({ owner = null } = {}) => {
+  if(owner !== null && !isOwnerName(owner)) return [{ code: 400, msg: 'Invalid extension name' }, null];
+
+  const names = [...new Set([...await namesIn(defaultEmailsDir(owner)), ...await namesIn(siteEmailsDir(owner))])].sort();
+  const templates = [];
+  for(const name of names){
+    const [error, found] = await readEmailTemplate({ template: owner ? `${owner}/${name}` : name });
+    if(!error) templates.push({ template: found.template, name, title: found.title, overridden: found.overridden, packaged: found.defaultSource !== null });
+  }
+  return [null, templates];
+};

package/server/utils/email/listEmails.js

@@ -0,0 +1,35 @@
+import db from '../../db/index.js';
+import { email } from '../../db/schema.js';
+import { and, desc, eq, ilike, or, sql } from 'drizzle-orm';
+
+const STATUSES = ['queued', 'sending', 'sent', 'failed'];
+
+/*
+  The log, newest first, without the bodies (read one with getEmail). `status`, `type` and `search` (a part of the recipient or the
+  subject) narrow it. Resolves to [error, { emails, total, limit, offset }].
+*/
+export default async ({ status, type, search, limit = 50, offset = 0 } = {}) => {
+  try {
+    const conditions = [];
+    if(status){
+      if(!STATUSES.includes(status)) return [{ code: 400, msg: `Status must be one of ${STATUSES.join(', ')}` }, null];
+      conditions.push(eq(email.status, status));
+    }
+    if(type) conditions.push(eq(email.type, String(type)));
+    if(search){
+      const like = `%${String(search).replace(/[\\%_]/g, '\\$&')}%`;
+      conditions.push(or(ilike(email.recipient, like), ilike(email.subject, like)));
+    }
+    const where = conditions.length ? and(...conditions) : undefined;
+    const take = Math.min(Math.max(Number(limit) || 50, 1), 200);
+    const skip = Math.max(Number(offset) || 0, 0);
+    const emails = await db.select({
+      id: email.id, type: email.type, recipient: email.recipient, sender: email.sender, subject: email.subject, status: email.status, attempts: email.attempts,
+      lastError: email.lastError, provider: email.provider, createdAt: email.createdAt, updatedAt: email.updatedAt, sentAt: email.sentAt,
+    }).from(email).where(where).orderBy(desc(email.createdAt)).limit(take).offset(skip);
+    const [{ total }] = await db.select({ total: sql`count(*)::int` }).from(email).where(where);
+    return [null, { emails, total, limit: take, offset: skip }];
+  } catch {
+    return [{ code: 500, msg: 'Failed to read the email log' }, null];
+  }
+};

package/server/utils/email/maintainEmails.js

@@ -0,0 +1,46 @@
+import db from '../../db/index.js';
+import { email } from '../../db/schema.js';
+import { and, asc, eq, lt, or, gt, sql } from 'drizzle-orm';
+import dispatchEmail from './dispatchEmail.js';
+import emailSettings from './emailSettings.js';
+import pruneEmails from './pruneEmails.js';
+
+const MINUTE_MS = 60 * 1000;
+const STUCK_MS = 5 * MINUTE_MS;
+const BACKOFF_MS = MINUTE_MS;
+const TOO_OLD_MS = 24 * 60 * MINUTE_MS;
+const BATCH = 50;
+
+/*
+  The email job, run every minute by the scheduler (kempo registers it itself):
+
+    - a `sending` email that has not finished in five minutes (the process died) goes back to `queued`;
+    - a `queued` email with tries left is sent again, a minute after its last try at the earliest, up to 50 at a time;
+    - a `queued` email older than a day is marked `failed` instead, so a password-reset link is never sent a day late;
+    - emails older than the retention settings are deleted.
+*/
+export default async () => {
+  const now = Date.now();
+  const { maxRetries } = await emailSettings();
+
+  await db.update(email)
+    .set({ status: 'queued', lastError: 'The send did not finish' })
+    .where(and(eq(email.status, 'sending'), lt(email.updatedAt, new Date(now - STUCK_MS))));
+
+  await db.update(email)
+    .set({ status: 'failed', lastError: sql`coalesce(${email.lastError}, 'Never sent') || ' (too old to send now)'`, updatedAt: new Date() })
+    .where(and(eq(email.status, 'queued'), lt(email.createdAt, new Date(now - TOO_OLD_MS))));
+
+  const due = await db.select({ id: email.id }).from(email)
+    .where(and(
+      eq(email.status, 'queued'),
+      gt(email.createdAt, new Date(now - TOO_OLD_MS)),
+      lt(email.attempts, 1 + maxRetries),
+      or(eq(email.attempts, 0), lt(email.updatedAt, new Date(now - BACKOFF_MS))),
+    ))
+    .orderBy(asc(email.createdAt))
+    .limit(BATCH);
+  for(const { id } of due) await dispatchEmail(id);
+
+  await pruneEmails();
+};

package/server/utils/email/pruneEmails.js

@@ -0,0 +1,29 @@
+import db from '../../db/index.js';
+import { email } from '../../db/schema.js';
+import { and, lt, eq, notInArray } from 'drizzle-orm';
+import emailSettings from './emailSettings.js';
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/*
+  Deletes the emails that are older than the settings keep them. A kind of email in `email_retention_by_type` is kept that many days,
+  every other kind `email_retention_days`; 0 keeps it forever. Resolves to [error, { deleted }].
+*/
+export default async ({ now = new Date() } = {}) => {
+  try {
+    const { retentionDays, retentionByType } = await emailSettings();
+    const specific = Object.keys(retentionByType);
+    let deleted = 0;
+    for(const [type, days] of Object.entries(retentionByType)){
+      if(days === 0) continue;
+      deleted += (await db.delete(email).where(and(eq(email.type, type), lt(email.createdAt, new Date(now.getTime() - days * DAY_MS)))).returning({ id: email.id })).length;
+    }
+    if(retentionDays > 0){
+      const older = lt(email.createdAt, new Date(now.getTime() - retentionDays * DAY_MS));
+      deleted += (await db.delete(email).where(specific.length ? and(notInArray(email.type, specific), older) : older).returning({ id: email.id })).length;
+    }
+    return [null, { deleted }];
+  } catch {
+    return [{ code: 500, msg: 'Failed to delete old emails' }, null];
+  }
+};