kempo 4.7.0 → 4.8.0

package/server/utils/email/retryEmail.js

@@ -0,0 +1,21 @@
+import db from '../../db/index.js';
+import { email } from '../../db/schema.js';
+import { and, eq, inArray } from 'drizzle-orm';
+import dispatchEmail from './dispatchEmail.js';
+
+/*
+  Tries an email that did not go again, as if it were new: it gets the full number of tries once more. Only a `queued` or `failed`
+  email can be tried again (one that is `sent` or being sent is left alone). Resolves like sendEmail.
+*/
+export default async id => {
+  try {
+    const [row] = await db.update(email)
+      .set({ status: 'queued', attempts: 0, lastError: null, updatedAt: new Date() })
+      .where(and(eq(email.id, String(id ?? '')), inArray(email.status, ['queued', 'failed'])))
+      .returning({ id: email.id });
+    if(!row) return [{ code: 409, msg: 'Only an email that is waiting or failed can be tried again' }, null];
+  } catch {
+    return [{ code: 500, msg: 'Failed to retry the email' }, null];
+  }
+  return dispatchEmail(String(id));
+};

package/server/utils/email/saveEmailTemplate.js

@@ -0,0 +1,38 @@
+import { mkdir, readFile, rm, writeFile } from 'fs/promises';
+import { dirname } from 'path';
+import { locateTemplate } from './emailTemplatePaths.js';
+import renderEmailTemplate from './renderEmailTemplate.js';
+
+const MAX_SOURCE = 100000;
+
+/*
+  The site's own version of an email template, written to `templates/emails/` so it is used from the next email on (the packaged
+  one is never touched). Only a template that exists can be saved, so this cannot make up new names. The new version is rendered
+  once before it is kept, and the old one is put back when it does not render, so a typo cannot stop the site sending that email.
+  Resolves to [error, { template }].
+*/
+export default async ({ template, source } = {}) => {
+  const located = locateTemplate(template);
+  if(!located) return [{ code: 400, msg: 'Invalid email template name' }, null];
+  if(typeof source !== 'string' || !source.trim()) return [{ code: 400, msg: 'The template cannot be empty' }, null];
+  if(source.length > MAX_SOURCE) return [{ code: 400, msg: `The template can be at most ${MAX_SOURCE} characters` }, null];
+  if(source.includes('\u0000')) return [{ code: 400, msg: 'The template cannot contain null characters' }, null];
+
+  const [site, packaged] = await Promise.all([readFile(located.sitePath, 'utf8').catch(() => null), readFile(located.defaultPath, 'utf8').catch(() => null)]);
+  if(site === null && packaged === null) return [{ code: 404, msg: `Email template not found: ${template}` }, null];
+
+  try {
+    await mkdir(dirname(located.sitePath), { recursive: true });
+    await writeFile(located.sitePath, source);
+  } catch {
+    return [{ code: 500, msg: 'The template could not be saved' }, null];
+  }
+
+  const [renderError] = await renderEmailTemplate({ template, data: {} });
+  if(renderError){
+    if(site === null) await rm(located.sitePath, { force: true });
+    else await writeFile(located.sitePath, site);
+    return [{ code: 400, msg: `The template does not render, so it was not saved: ${renderError.msg}` }, null];
+  }
+  return [null, { template }];
+};

package/server/utils/email/sendEmail.js

@@ -1,48 +1,38 @@
-import { Resend } from 'resend';
+import crypto from 'crypto';
+import db from '../../db/index.js';
+import { email } from '../../db/schema.js';
+import getSenderFrom from './getSenderFrom.js';
+import dispatchEmail from './dispatchEmail.js';
 
 /*
-  Constructed on first send, not at import. The Resend constructor throws when the key is missing,
-  and this module is reachable from the server SDK, so building it at module scope made an unset
-  RESEND_API_KEY fail every route that transitively imports it rather than just disabling email.
-*/
-let resend = null;
-const client = () => (resend ??= new Resend(process.env.RESEND_API_KEY));
-
-export default async ({ to, subject, html }) => {
-  if(!process.env.RESEND_API_KEY){
-    return [{ code: 500, msg: 'RESEND_API_KEY not configured' }, null];
-  }
+  Asks for an email to be sent. Kempo does not send email itself: this saves the email in the log (the `email` table) and hands it to
+  whichever email extension is installed (kempo-resend, kempo-smtp...) through the `email:send` hook; see dispatchEmail.js.
 
+  `template` is the name of the template the email was made from, if any, and is its type in the log. It resolves to
+  `[null, { id, status: 'sent' }]` when a sender sent it, or `[{ code, msg, emailId }, null]` when none did: 503 when there is no email
+  extension installed, 502 when one tried and failed. Either way the email is in the log, and a failed one is tried again (see the
+  `email_max_retries` setting).
+*/
+export default async ({ to, subject, html, template = null } = {}) => {
   if(!to){
     return [{ code: 400, msg: 'Recipient email is required' }, null];
   }
-  
+
   if(!subject){
     return [{ code: 400, msg: 'Email subject is required' }, null];
   }
-  
+
   if(!html){
     return [{ code: 400, msg: 'Email content is required' }, null];
   }
 
-  const from = process.env.SMTP_FROM || 'onboarding@resend.dev';
-
+  const id = crypto.randomUUID();
+  const now = new Date();
   try {
-    const { data, error } = await client().emails.send({
-      from,
-      to,
-      subject,
-      html,
-    });
-
-    if(error){
-      console.error('Email send error:', error);
-      return [{ code: 500, msg: error.message || 'Failed to send email' }, null];
-    }
-
-    return [null, { success: true, messageId: data.id }];
-  } catch(error){
-    console.error('Email send error:', error);
-    return [{ code: 500, msg: 'Failed to send email' }, null];
+    await db.insert(email).values({ id, type: template || 'other', recipient: String(to), sender: await getSenderFrom(), subject: String(subject), html: String(html), status: 'queued', attempts: 0, createdAt: now, updatedAt: now });
+  } catch(error) {
+    return [{ code: 500, msg: 'The email could not be saved to send' }, null];
   }
+
+  return dispatchEmail(id);
 };

package/server/utils/email/sendEmailFromTemplate.js

@@ -3,7 +3,7 @@ import sendEmail from './sendEmail.js';
 
 /*
   `template` is a plain name for kempo's and the site's templates, or "owner/name" for an extension's;
-  see renderEmailTemplate.js.
+  see renderEmailTemplate.js. It is also the email's type in the log, which the retention settings go by.
 */
 export default async ({ to, subject, template, data = {} }) => {
   if(!to){
@@ -23,5 +23,5 @@ export default async ({ to, subject, template, data = {} }) => {
     return [error, null];
   }
 
-  return await sendEmail({ to, subject, html });
+  return await sendEmail({ to, subject, html, template });
 };

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,40 @@
+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' },
+];
+
+/* 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/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'
     ]
   }
 };
@@ -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/systemPermissions.js

@@ -0,0 +1,75 @@
+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: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];
+  }
+};