kempo 4.7.0 → 4.9.0

package/server/utils/extensions/writeSiteFile.js

@@ -0,0 +1,66 @@
+import { createHash } from 'crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { dirname, join, normalize, sep } from 'path';
+
+/*
+  For an extension that has to put a file into the site (a generated template, a starter page): writes it the way kempo's own
+  starter files are handled, so an update of the extension never overwrites what the owner changed.
+
+    not there, never written by this extension     written
+    not there, but this extension wrote it before  the owner deleted it, so it stays deleted
+    identical to what is being written             nothing to do
+    still exactly what this extension last wrote   never edited, so replaced
+    anything else                                  edited by the owner (or anyone), so kept
+
+  The extension's fingerprints are in .kempo/shipped/<owner>.json. `path` is relative to the site and must be inside public/
+  or templates/. Most extensions need none of this, because their own public/ is served from the package; this is for the
+  few that generate something into the site. Resolves to [error, { status }] where status is "written", "current", "kept"
+  or "deleted".
+*/
+const hashOf = content => createHash('sha256').update(content).digest('hex');
+
+export default ({ owner, path, content, cwd = process.cwd() } = {}) => {
+  if(typeof owner !== 'string' || !/^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/.test(owner)){
+    return [{ code: 400, msg: 'owner must be the extension name' }, null];
+  }
+  const relative = typeof path === 'string' ? normalize(path).split(sep).join('/') : '';
+  if(!relative || relative.startsWith('..') || relative.startsWith('/') || !/^(public|templates)\//.test(relative)){
+    return [{ code: 400, msg: 'path must be a file inside public/ or templates/' }, null];
+  }
+  if(typeof content !== 'string' && !Buffer.isBuffer(content)){
+    return [{ code: 400, msg: 'content must be text or a buffer' }, null];
+  }
+
+  const recordFile = join(cwd, '.kempo', 'shipped', `${owner.replace('/', '__')}.json`);
+  let files = {};
+  try {
+    files = JSON.parse(readFileSync(recordFile, 'utf8')).files ?? {};
+  } catch {
+    files = {};
+  }
+  const save = () => {
+    mkdirSync(dirname(recordFile), { recursive: true });
+    writeFileSync(recordFile, JSON.stringify({ files }, null, 2));
+  };
+
+  const target = join(cwd, relative);
+  const wanted = hashOf(content);
+
+  if(!existsSync(target)){
+    if(files[relative]) return [null, { status: 'deleted' }];
+  } else {
+    const here = hashOf(readFileSync(target));
+    if(here === wanted){
+      files[relative] = wanted;
+      save();
+      return [null, { status: 'current' }];
+    }
+    if(files[relative] !== here) return [null, { status: 'kept' }];
+  }
+
+  mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(target, content);
+  files[relative] = wanted;
+  save();
+  return [null, { status: 'written' }];
+};

package/server/utils/hooks/triggerHook.js

@@ -7,6 +7,13 @@ import { pathToFileURL } from 'url';
 
 const handlerCache = new Map();
 
+/*
+  kempo-server's dev reload (`dev.reload`) counts how many times a server file has changed in
+  `globalThis.kempoDevGeneration`. A handler is loaded again when the count has moved on, so editing a hook file
+  in development needs no restart. In production it is never set, and a handler is loaded once.
+*/
+const generation = () => globalThis.kempoDevGeneration ?? 0;
+
 export const clearHandlerCache = () => handlerCache.clear();
 
 const resolveHandler = (owner, callback) => {
@@ -33,11 +40,15 @@ const resolveHandler = (owner, callback) => {
   write a response mid-flight. That needs no special mode here — only that ordering be predictable,
   hence the explicit `orderBy` below, since without it row order is whatever the database returns.
 
+  **Claiming** (`stopWhen`) — a function given each handler's result. When it returns true the chain stops there and the handlers
+  after it do not run. This is how only one of several handlers does a job: an email sender returns `{ sent: true }` and the
+  other senders never see that email, while one that failed returns something else and the next one gets its turn.
+
   Note that "notification" governs error handling, not timing: handlers are still awaited in
   sequence, so a handler doing slow work holds up whatever triggered the event. Such a handler
   should start its work and return rather than awaiting it here.
 */
-export default async (event, data = {}, { bail = false } = {}) => {
+export default async (event, data = {}, { bail = false, stopWhen = null } = {}) => {
   if(!event){
     return [{ code: 400, msg: 'Event is required' }, null];
   }
@@ -59,12 +70,13 @@ export default async (event, data = {}, { bail = false } = {}) => {
       const handlerPath = resolveHandler(h.owner, h.callback);
       if(!handlerPath) continue;
 
-      let handler = handlerCache.get(handlerPath);
+      const cacheKey = `${handlerPath}:${generation()}`;
+      let handler = handlerCache.get(cacheKey);
       if(!handler){
         try {
-          const mod = await import(pathToFileURL(handlerPath).href);
+          const mod = await import(pathToFileURL(handlerPath).href + (generation() ? `?dev=${generation()}` : ''));
           handler = mod.default || mod;
-          handlerCache.set(handlerPath, handler);
+          handlerCache.set(cacheKey, handler);
         } catch(err) {
           /*
             Never fail silently: a hook that cannot load is indistinguishable from one that
@@ -80,6 +92,7 @@ export default async (event, data = {}, { bail = false } = {}) => {
       try {
         const result = await handler(data);
         results.push({ hookId: h.id, owner: h.owner, result });
+        if(stopWhen && stopWhen(result)) break;
       } catch(err) {
         if(bail) throw err;
         /* A notification handler's failure stops nothing, but it must not vanish: nobody would ever know the extension broke. */

package/server/utils/settings/listSettings.js

@@ -1,23 +1,28 @@
 import db from '../../db/index.js';
 import { setting } from '../../db/schema.js';
-import { like, not, and, sql } from 'drizzle-orm';
+import { like, not, and, asc, sql } from 'drizzle-orm';
 import { SECRET_MASK } from './secretCrypto.js';
 
+/*
+  The settings of one owner, by name. `owner` is 'system', 'custom', 'extension' (every setting that is neither, whoever owns it),
+  or the name of one extension (`kempo-commerce`), which lists just its own. The owner is matched as a plain prefix, never as a
+  pattern, so a name with `_` or `%` in it cannot reach another owner's settings.
+*/
 export default async ({ owner, limit = 50, offset = 0 } = {}) => {
   try {
     let where;
-    if(owner === 'system' || owner === 'custom'){
-      where = like(setting.name, `${owner}:%`);
-    } else if(owner === 'extension'){
+    if(owner === 'extension'){
       where = and(
         not(like(setting.name, 'system:%')),
         not(like(setting.name, 'custom:%'))
       );
+    } else if(owner){
+      where = sql`left(${setting.name}, ${owner.length + 1}) = ${`${owner}:`}`;
     }
     const q = db.select().from(setting);
     const cq = db.select({ count: sql`count(*)` }).from(setting);
     if(where){ q.where(where); cq.where(where); }
-    const results = await q.limit(limit).offset(offset);
+    const results = await q.orderBy(asc(setting.name)).limit(limit).offset(offset);
     const [{ count }] = await cq;
 
     // Never send secret ciphertext to the admin UI, not even encrypted.

package/server/utils/settings/setSetting.js

@@ -3,12 +3,16 @@ import { setting } from '../../db/schema.js';
 import { eq } from 'drizzle-orm';
 import { serializeValue } from './helpers.js';
 import { SECRET_MASK } from './secretCrypto.js';
+import settingRule from './settingRules.js';
 
 export default async (owner, name, value, type = null, isPublic = false, description = null) => {
   if(!owner || !name){
     return [{ code: 400, msg: 'Both owner and name are required' }, null];
   }
 
+  const ruleError = settingRule(owner, name, value);
+  if(ruleError) return [ruleError, null];
+
   try {
     const fullName = `${owner}:${name}`;
     const detectedType = type || (typeof value === 'object' ? 'json' : typeof value);

package/server/utils/settings/settingRules.js

@@ -0,0 +1,21 @@
+import isValidSender from '../email/isValidSender.js';
+
+/*
+  Rules for particular settings, checked whenever one is saved (the admin screen, the API and the SDK alike), because a bad value of
+  these breaks something site-wide. Resolves to an `{ code, msg }` error, or null when the value is fine.
+*/
+const whole = (value, min, max) => Number.isInteger(Number(value)) && value !== '' && value !== null && Number(value) >= min && Number(value) <= max;
+
+const RULES = {
+  'system:email_max_retries': value => (whole(value, 0, 10) ? null : { code: 400, msg: 'Retries must be a whole number from 0 to 10' }),
+  'system:email_retention_days': value => (whole(value, 0, 3650) ? null : { code: 400, msg: 'Retention must be a whole number of days from 0 to 3650' }),
+  'system:email_retention_by_type': value => (value && typeof value === 'object' && !Array.isArray(value) && Object.values(value).every(days => whole(days, 0, 3650))
+    ? null
+    : { code: 400, msg: 'Give each kind of email a whole number of days from 0 to 3650, like { "verify-email": 7 }' }),
+  'system:email_from': value => (value === '' || isValidSender(value) ? null : { code: 400, msg: 'The sender must look like name@example.com or Shop Name <name@example.com>' }),
+};
+
+export default (owner, name, value) => {
+  const rule = Object.hasOwn(RULES, `${owner}:${name}`) ? RULES[`${owner}:${name}`] : null;
+  return rule ? rule(value) : null;
+};

package/server/utils/settings/systemSettings.js

@@ -0,0 +1,41 @@
+import db from '../../db/index.js';
+import { setting } from '../../db/schema.js';
+import { eq } from 'drizzle-orm';
+import setSetting from './setSetting.js';
+
+/*
+  The settings kempo itself owns, with their defaults. A new site gets them when it is set up (seedDatabase), and `ensureSystemSettings`
+  adds any that an older site is missing when the server starts, so a setting added in a later version shows on the settings screen
+  and can be edited like the rest. It only ever adds: a setting that exists is never touched, so nothing an admin chose is overwritten.
+*/
+export const SYSTEM_SETTINGS = [
+  { owner: 'system', name: 'site_name', value: 'Kempo Site', type: 'string', isPublic: true, description: 'The name of the website' },
+  { owner: 'system', name: 'session_duration_days', value: 7, type: 'number', isPublic: false, description: 'Session duration in days' },
+  { owner: 'system', name: 'allow_registration', value: true, type: 'boolean', isPublic: true, description: 'Allow new users to register' },
+  { owner: 'system', name: 'require_email_verification', value: false, type: 'boolean', isPublic: false, description: 'Require email verification before account access' },
+  { owner: 'system', name: 'verification_url', value: 'http://localhost:3000/verify-email/{{token}}', type: 'string', isPublic: false, description: 'Email verification URL template' },
+  { owner: 'system', name: 'notification_retention_days', value: 90, type: 'number', isPublic: false, description: 'Days to keep notifications before they are deleted (0 keeps them forever)' },
+  { owner: 'system', name: 'password_reset_url', value: 'http://localhost:3000/reset-password/{{token}}', type: 'string', isPublic: false, description: 'Password reset URL template' },
+  { owner: 'system', name: 'email_max_retries', value: 1, type: 'number', isPublic: false, description: 'How many times kempo tries again to send an email that could not be sent, after the first try (0 never retries)' },
+  { owner: 'system', name: 'email_retention_days', value: 30, type: 'number', isPublic: false, description: 'Days to keep the log of sent emails before it is deleted (0 keeps it forever)' },
+  { owner: 'system', name: 'email_retention_by_type', value: {}, type: 'json', isPublic: false, description: 'Days to keep a particular kind of email, instead of the number above, as { "verify-email": 7, "kempo-commerce/order-processing": 365 } (0 keeps that kind forever)' },
+  { owner: 'system', name: 'email_from', value: '', type: 'string', isPublic: false, description: 'The address emails are sent from, as name@example.com or Shop Name <name@example.com>. It must be on a domain verified with the email provider. Empty uses EMAIL_FROM from the server environment' },
+  { owner: 'system', name: 'update_check_enabled', value: true, type: 'boolean', isPublic: false, description: 'Check npm every 12 hours for a newer kempo and tell the people who can install it' },
+];
+
+/* Resolves to [error, { added: [names] }]. */
+export const ensureSystemSettings = async () => {
+  try {
+    const added = [];
+    for(const entry of SYSTEM_SETTINGS){
+      const [existing] = await db.select({ name: setting.name }).from(setting).where(eq(setting.name, `${entry.owner}:${entry.name}`)).limit(1);
+      if(existing) continue;
+      const [error] = await setSetting(entry.owner, entry.name, entry.value, entry.type, entry.isPublic, entry.description);
+      if(error) return [error, null];
+      added.push(entry.name);
+    }
+    return [null, { added }];
+  } catch {
+    return [{ code: 500, msg: 'The system settings could not be checked' }, null];
+  }
+};

package/server/utils/setup/runUpgrades.js

@@ -0,0 +1,70 @@
+import { existsSync, readdirSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath, pathToFileURL } from 'url';
+import { sql } from 'drizzle-orm';
+import db from '../../db/index.js';
+import { upgrade } from '../../db/schema.js';
+
+/*
+  Kempo's own data migrations: the files in server/db/upgrades, which restructure or move data that the additive sync of
+  the tables (syncCoreSchema) cannot. See that folder's README for how to write one.
+
+  They run in file-name order, each once, in a transaction, when the server starts and after the tables are in step. A
+  database that has never had the `upgrade` table is taken to already hold what the shipped migrations make (a new site,
+  or a site on its first version with this): they are recorded as run without being run, under a row called 'baseline'.
+*/
+export const DEFAULT_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'db', 'upgrades');
+
+const filesIn = dir => (existsSync(dir) ? readdirSync(dir).filter(name => name.endsWith('.js')).sort() : []);
+
+const load = (dir, file) => import(`${pathToFileURL(join(dir, file)).href}?t=${Date.now()}`);
+
+const appliedIds = async executor => new Set((await executor.select({ id: upgrade.id }).from(upgrade)).map(row => row.id));
+
+/*
+  What would run, in order, as [{ id, description, breaking }]. `dir` is another version's folder, to look ahead at an
+  update before it is switched to. Nothing is run or recorded.
+*/
+export const pendingUpgrades = async ({ dir = DEFAULT_DIR, executor = db } = {}) => {
+  const applied = await appliedIds(executor);
+  if(!applied.has('baseline')) return [];
+  const pending = [];
+  for(const file of filesIn(dir).filter(name => !applied.has(name))){
+    const { meta = {} } = await load(dir, file);
+    pending.push({ id: file, description: meta.description ?? '', breaking: Boolean(meta.breaking) });
+  }
+  return pending;
+};
+
+/*
+  Resolves to [error, { ran }]. An error is the first migration that failed, with `breaking` saying whether it was one the
+  previous version cannot run without; nothing after it runs, and what it did is rolled back.
+*/
+export default async ({ dir = DEFAULT_DIR, executor = db } = {}) => {
+  try {
+    const applied = await appliedIds(executor);
+    if(!applied.has('baseline')){
+      await executor.transaction(async tx => {
+        for(const id of [...filesIn(dir), 'baseline']) await tx.insert(upgrade).values({ id, description: id === 'baseline' ? 'Existing migrations were already part of this database' : 'Part of the baseline' }).onConflictDoNothing();
+      });
+      return [null, { ran: [] }];
+    }
+
+    const ran = [];
+    for(const file of filesIn(dir).filter(name => !applied.has(name))){
+      const { meta = {}, up } = await load(dir, file);
+      try {
+        await executor.transaction(async tx => {
+          await up({ db: tx, sql });
+          await tx.insert(upgrade).values({ id: file, description: meta.description ?? null, breaking: Boolean(meta.breaking) });
+        });
+        ran.push(file);
+      } catch(error) {
+        return [{ code: 500, msg: `The data migration ${file} failed: ${String(error.cause?.message || error.message).slice(0, 300)}`, breaking: Boolean(meta.breaking), id: file }, { ran }];
+      }
+    }
+    return [null, { ran }];
+  } catch(error) {
+    return [{ code: 500, msg: `The data migrations could not be checked: ${String(error.cause?.message || error.message).slice(0, 300)}`, breaking: false }, null];
+  }
+};

package/server/utils/setup/seedDatabase.js

@@ -2,54 +2,7 @@ import crypto from 'crypto';
 import db from '../../db/index.js';
 import { permission, group, groupPermission, setting, createSettingProtectionTrigger, createGroupProtectionTrigger, createPermissionProtectionTrigger } from '../../db/schema.js';
 import { eq, and, sql } from 'drizzle-orm';
-
-const DEFAULT_PERMISSIONS = [
-  { name: 'system:user:create', description: 'Create new users' },
-  { name: 'system:user:read', description: 'View users' },
-  { name: 'system:user:update', description: 'Edit users' },
-  { name: 'system:user:delete', description: 'Delete users' },
-  
-  { name: 'system:group:create', description: 'Create new groups' },
-  { name: 'system:group:read', description: 'View groups' },
-  { name: 'system:group:update', description: 'Edit groups and manage membership' },
-  { name: 'system:group:delete', description: 'Delete groups' },
-  
-  { name: 'system:permissions:read', description: 'View permissions for all users' },
-  { name: 'system:permissions:manage', description: 'Add or remove permissions' },
-  
-  { name: 'system:settings:read', description: 'View private settings' },
-  { name: 'system:settings:update', description: 'Update settings' },
-  { name: 'system:custom-settings:manage', description: 'Create and delete custom settings' },
-  
-  { name: 'system:pages:read', description: 'View pages in admin' },
-  { name: 'system:pages:create', description: 'Create new pages' },
-  { name: 'system:pages:update', description: 'Edit pages' },
-  { name: 'system:pages:delete', description: 'Delete pages' },
-  
-  { name: 'system:menus:create', description: 'Create new menus' },
-  { name: 'system:menus:read', description: 'View menus in admin' },
-  { name: 'system:menus:update', description: 'Edit menus and menu items' },
-  { name: 'system:menus:delete', description: 'Delete menus' },
-  
-  { name: 'system:fragments:read', description: 'View fragments in admin' },
-  { name: 'system:fragments:create', description: 'Create new fragments' },
-  { name: 'system:fragments:update', description: 'Edit fragments' },
-  { name: 'system:fragments:delete', description: 'Delete fragments' },
-  
-  { name: 'system:globals:read', description: 'View global content in admin' },
-  { name: 'system:globals:create', description: 'Create new global content' },
-  { name: 'system:globals:update', description: 'Edit global content' },
-  { name: 'system:globals:delete', description: 'Delete global content' },
-
-  { name: 'system:extensions:read', description: 'View installed extensions' },
-  { name: 'system:extensions:install', description: 'Install extensions' },
-  { name: 'system:extensions:uninstall', description: 'Uninstall extensions' },
-  { name: 'system:extensions:manage', description: 'Enable and disable extensions' },
-
-  { name: 'system:realtime:read', description: 'View realtime connections and channels' },
-
-  { name: 'system:admin:access', description: 'Access admin panel' },
-];
+import { SYSTEM_PERMISSIONS } from './systemPermissions.js';
 
 const DEFAULT_GROUPS = {
   'system:Users': {
@@ -69,7 +22,7 @@ const DEFAULT_GROUPS = {
       'system:fragments:read', 'system:fragments:create', 'system:fragments:update', 'system:fragments:delete',
       'system:globals:read', 'system:globals:create', 'system:globals:update', 'system:globals:delete',
       'system:extensions:read', 'system:extensions:install', 'system:extensions:uninstall', 'system:extensions:manage',
-      'system:realtime:read'
+      'system:realtime:read', 'system:emails:read', 'system:emails:manage', 'system:updates:manage'
     ]
   }
 };
@@ -88,7 +41,7 @@ const runScript = text => db.$client?.exec ? db.$client.exec(text) : db.execute(
 export default async ({ log = console.log } = {}) => {
   log('=== Seeding Permissions ===\n');
 
-  for(const perm of DEFAULT_PERMISSIONS) {
+  for(const perm of SYSTEM_PERMISSIONS) {
     const existing = await db.select()
       .from(permission)
       .where(eq(permission.name, perm.name))
@@ -167,18 +120,10 @@ export default async ({ log = console.log } = {}) => {
 
   log('\n=== Creating Default Settings ===\n');
 
-  const DEFAULT_SETTINGS = [
-    { owner: 'system', name: 'site_name', value: 'Kempo Site', type: 'string', isPublic: true, description: 'The name of the website' },
-    { owner: 'system', name: 'session_duration_days', value: 7, type: 'number', isPublic: false, description: 'Session duration in days' },
-    { owner: 'system', name: 'allow_registration', value: true, type: 'boolean', isPublic: true, description: 'Allow new users to register' },
-    { owner: 'system', name: 'require_email_verification', value: false, type: 'boolean', isPublic: false, description: 'Require email verification before account access' },
-    { owner: 'system', name: 'verification_url', value: 'http://localhost:3000/verify-email/{{token}}', type: 'string', isPublic: false, description: 'Email verification URL template' },
-    { owner: 'system', name: 'notification_retention_days', value: 90, type: 'number', isPublic: false, description: 'Days to keep notifications before they are deleted (0 keeps them forever)' },
-    { owner: 'system', name: 'password_reset_url', value: 'http://localhost:3000/reset-password/{{token}}', type: 'string', isPublic: false, description: 'Password reset URL template' },
-  ];
+  const { SYSTEM_SETTINGS } = await import('../settings/systemSettings.js');
 
   const { default: setSetting } = await import('../settings/setSetting.js');
-  for(const s of DEFAULT_SETTINGS){
+  for(const s of SYSTEM_SETTINGS){
     await setSetting(s.owner, s.name, s.value, s.type, s.isPublic, s.description);
     log(`✓ Created setting: ${s.owner}:${s.name} = ${s.value}`);
   }

package/server/utils/setup/seedIfNew.js

@@ -0,0 +1,21 @@
+import { eq } from 'drizzle-orm';
+import db from '../../db/index.js';
+import { group } from '../../db/schema.js';
+import seedDatabase from './seedDatabase.js';
+
+/*
+  A database with no Administrators group is a new one (the group cannot be deleted), so kempo's groups, permissions and
+  settings are put in it, which is what `scripts/init-db.js` does by hand. It is what lets a new site start from an empty
+  database with no command typed: the tables come from syncCoreSchema, this fills them, and the /setup page makes the
+  first administrator. A database that has the group is never touched.
+*/
+export default async () => {
+  try {
+    const [existing] = await db.select({ name: group.name }).from(group).where(eq(group.name, 'system:Administrators')).limit(1);
+    if(existing) return [null, { seeded: false }];
+    await seedDatabase({ log: () => {} });
+    return [null, { seeded: true }];
+  } catch(error) {
+    return [{ code: 500, msg: `A new database could not be set up: ${String(error.cause?.message || error.message).slice(0, 300)}` }, null];
+  }
+};

package/server/utils/setup/syncCoreSchema.js

@@ -0,0 +1,130 @@
+import { sql } from 'drizzle-orm';
+import db from '../../db/index.js';
+import * as coreSchema from '../../db/schema.js';
+
+/*
+  Brings kempo's own tables in step with the installed version of kempo, so an update never needs a command typed.
+  It runs when the server starts, before the site serves anything.
+
+  It only ever adds. It looks at which of the schema's tables, columns, indexes and constraints the database already
+  has, and asks drizzle-kit's migration generator (the one `drizzle-kit push` is built on) for the difference between
+  "what the database has" and "what the schema says", so the new indexes and foreign keys come out exactly as a push
+  would make them. What the database has is the schema with every missing piece cut out, so the difference can only
+  be additions: it can never contain a DROP or a TRUNCATE, and a table that an extension or the site made is never
+  looked at. A column that kempo no longer has stays where it is. A change to something that already exists (a new
+  type, a NOT NULL) is not detected here: that is what a release's own migration step is for.
+
+  Each statement is applied on its own, so one the database refuses (a new unique index over rows that already break
+  it, a NOT NULL column with no default on a table that has rows) is reported without holding back the rest. Several
+  processes starting together queue on an advisory lock, and the one after the first finds nothing left to do.
+
+  (drizzle-kit's `pushSchema` is not used: it drops the parameters of its own introspection queries, which fails on any
+  table with a composite key and then ends the process, and for a type change it proposes TRUNCATE ... CASCADE.)
+*/
+const LOCK_KEY = 'kempo:sync-core-schema';
+
+const ADDITIVE = [
+  /^CREATE TABLE /i,
+  /^CREATE (UNIQUE )?INDEX /i,
+  /^CREATE TYPE /i,
+  /^ALTER TABLE .+ ADD COLUMN /i,
+  /^ALTER TABLE .+ ADD CONSTRAINT /i,
+];
+
+/* A last check on what the generator produced: anything that is not an addition is never run. */
+export const isAdditive = statement => ADDITIVE.some(pattern => pattern.test(statement.trim()));
+
+/* One plain sentence for a statement, for the log and the Updates screen. */
+export const describe = statement => {
+  const text = statement.trim();
+  const named = (pattern, make) => {
+    const match = text.match(pattern);
+    return match ? make(...match.slice(1)) : null;
+  };
+  return named(/^CREATE TABLE "([^"]+)"/i, table => `Created table ${table}`)
+    ?? named(/^ALTER TABLE "([^"]+)" ADD COLUMN "([^"]+)"/i, (table, column) => `Added column ${table}.${column}`)
+    ?? named(/^CREATE (?:UNIQUE )?INDEX "([^"]+)"/i, index => `Created index ${index}`)
+    ?? named(/^ALTER TABLE "([^"]+)" ADD CONSTRAINT "([^"]+)"/i, (table, constraint) => `Added ${constraint} to ${table}`)
+    ?? text.replace(/\s+/g, ' ').slice(0, 120);
+};
+
+const rowsOf = result => (Array.isArray(result) ? result : result.rows);
+
+/* The names of what the database already has in the public schema. */
+const readDatabase = async executor => {
+  const names = async (query, field) => new Set(rowsOf(await executor.execute(query)).map(row => row[field]));
+  const columns = rowsOf(await executor.execute(sql`select table_name, column_name from information_schema.columns where table_schema = 'public'`));
+  return {
+    tables: await names(sql`select table_name from information_schema.tables where table_schema = 'public'`, 'table_name'),
+    columns: new Set(columns.map(row => `${row.table_name}.${row.column_name}`)),
+    indexes: await names(sql`select indexname from pg_indexes where schemaname = 'public'`, 'indexname'),
+    constraints: await names(sql`select conname from pg_constraint join pg_namespace on pg_namespace.oid = pg_constraint.connamespace where nspname = 'public'`, 'conname'),
+    enums: await names(sql`select typname from pg_type join pg_namespace on pg_namespace.oid = pg_type.typnamespace where typtype = 'e' and nspname = 'public'`, 'typname'),
+  };
+};
+
+/* The schema snapshot with everything the database lacks cut out: what drizzle-kit would see if it had introspected the database. */
+const withoutMissing = (snapshot, existing) => {
+  const prev = structuredClone(snapshot);
+  for(const key of Object.keys(prev.enums)){
+    if(!existing.enums.has(prev.enums[key].name)) delete prev.enums[key];
+  }
+  for(const [key, table] of Object.entries(prev.tables)){
+    if(!existing.tables.has(table.name)){
+      delete prev.tables[key];
+      continue;
+    }
+    for(const name of Object.keys(table.columns)){
+      if(!existing.columns.has(`${table.name}.${name}`)) delete table.columns[name];
+    }
+    for(const name of Object.keys(table.indexes)){
+      if(!existing.indexes.has(name)) delete table.indexes[name];
+    }
+    for(const group of [table.foreignKeys, table.uniqueConstraints, table.compositePrimaryKeys ?? {}]){
+      for(const id of Object.keys(group)){
+        if(!existing.constraints.has(group[id].name)) delete group[id];
+      }
+    }
+  }
+  return prev;
+};
+
+/* What the last run did, for the Updates screen. */
+let lastRun = { ran: false, applied: [], failed: [] };
+
+export const getSchemaSyncResult = () => lastRun;
+
+/*
+  Resolves to [error, { applied, failed }]: `applied` is a list of sentences, `failed` is { change, reason } for what
+  the database refused. `schema` and `executor` are for tests and extensions: other tables, in another database.
+*/
+export default async ({ schema = coreSchema, executor = db } = {}) => {
+  try {
+    const { generateDrizzleJson, generateMigration } = await import('drizzle-kit/api');
+    const wanted = generateDrizzleJson(schema);
+    const result = { applied: [], failed: [] };
+
+    await executor.transaction(async tx => {
+      await tx.execute(sql`select pg_advisory_xact_lock(hashtext(${LOCK_KEY}::text))`);
+      const statements = await generateMigration(withoutMissing(wanted, await readDatabase(tx)), wanted);
+
+      for(const statement of statements){
+        if(!isAdditive(statement)){
+          result.failed.push({ change: describe(statement), reason: 'Kempo only adds to its tables, so this was not run' });
+          continue;
+        }
+        try {
+          await tx.transaction(inner => inner.execute(sql.raw(statement)));
+          result.applied.push(describe(statement));
+        } catch(error) {
+          result.failed.push({ change: describe(statement), reason: String(error.cause?.message || error.message).slice(0, 300) });
+        }
+      }
+    });
+
+    if(schema === coreSchema) lastRun = { ran: true, ...result };
+    return [null, result];
+  } catch(error) {
+    return [{ code: 500, msg: `The database could not be checked against this version of kempo: ${String(error.cause?.message || error.message).slice(0, 300)}` }, null];
+  }
+};

package/server/utils/setup/systemPermissions.js

@@ -0,0 +1,77 @@
+import db from '../../db/index.js';
+import { permission } from '../../db/schema.js';
+import { eq } from 'drizzle-orm';
+
+/*
+  The permissions kempo itself defines. A new site gets them when it is set up (seedDatabase), and `ensureSystemPermissions` adds any
+  that an older site is missing when the server starts, so a permission added in a later version exists there too. It only adds: one
+  that exists is never touched. The Administrators group has every permission without being given each one.
+*/
+export const SYSTEM_PERMISSIONS = [
+  { name: 'system:user:create', description: 'Create new users' },
+  { name: 'system:user:read', description: 'View users' },
+  { name: 'system:user:update', description: 'Edit users' },
+  { name: 'system:user:delete', description: 'Delete users' },
+  
+  { name: 'system:group:create', description: 'Create new groups' },
+  { name: 'system:group:read', description: 'View groups' },
+  { name: 'system:group:update', description: 'Edit groups and manage membership' },
+  { name: 'system:group:delete', description: 'Delete groups' },
+  
+  { name: 'system:permissions:read', description: 'View permissions for all users' },
+  { name: 'system:permissions:manage', description: 'Add or remove permissions' },
+  
+  { name: 'system:settings:read', description: 'View private settings' },
+  { name: 'system:settings:update', description: 'Update settings' },
+  { name: 'system:custom-settings:manage', description: 'Create and delete custom settings' },
+  
+  { name: 'system:pages:read', description: 'View pages in admin' },
+  { name: 'system:pages:create', description: 'Create new pages' },
+  { name: 'system:pages:update', description: 'Edit pages' },
+  { name: 'system:pages:delete', description: 'Delete pages' },
+  
+  { name: 'system:menus:create', description: 'Create new menus' },
+  { name: 'system:menus:read', description: 'View menus in admin' },
+  { name: 'system:menus:update', description: 'Edit menus and menu items' },
+  { name: 'system:menus:delete', description: 'Delete menus' },
+  
+  { name: 'system:fragments:read', description: 'View fragments in admin' },
+  { name: 'system:fragments:create', description: 'Create new fragments' },
+  { name: 'system:fragments:update', description: 'Edit fragments' },
+  { name: 'system:fragments:delete', description: 'Delete fragments' },
+  
+  { name: 'system:globals:read', description: 'View global content in admin' },
+  { name: 'system:globals:create', description: 'Create new global content' },
+  { name: 'system:globals:update', description: 'Edit global content' },
+  { name: 'system:globals:delete', description: 'Delete global content' },
+
+  { name: 'system:extensions:read', description: 'View installed extensions' },
+  { name: 'system:extensions:install', description: 'Install extensions' },
+  { name: 'system:extensions:uninstall', description: 'Uninstall extensions' },
+  { name: 'system:extensions:manage', description: 'Enable and disable extensions' },
+
+  { name: 'system:realtime:read', description: 'View realtime connections and channels' },
+
+  { name: 'system:emails:read', description: 'View the log of emails, including what they said' },
+  { name: 'system:emails:manage', description: 'Send a test email and try failed emails again' },
+
+  { name: 'system:updates:manage', description: 'See, check for and install kempo updates, which restarts the server' },
+
+  { name: 'system:admin:access', description: 'Access admin panel' },
+];
+
+/* Resolves to [error, { added: [names] }]. */
+export const ensureSystemPermissions = async () => {
+  try {
+    const added = [];
+    for(const perm of SYSTEM_PERMISSIONS){
+      const [existing] = await db.select({ name: permission.name }).from(permission).where(eq(permission.name, perm.name)).limit(1);
+      if(existing) continue;
+      await db.insert(permission).values({ name: perm.name, description: perm.description, owner: 'system', createdAt: new Date() });
+      added.push(perm.name);
+    }
+    return [null, { added }];
+  } catch {
+    return [{ code: 500, msg: 'The system permissions could not be checked' }, null];
+  }
+};