kempo 4.2.39 → 4.3.0

package/server/utils/realtime/channels.js

@@ -0,0 +1,247 @@
+import { join, resolve, sep } from 'path';
+import { pathToFileURL } from 'url';
+import userHasPermission from '../permissions/userHasPermission.js';
+import { getEnabledExtensions } from '../extensions/scopeCache.js';
+import parseDuration from './duration.js';
+
+/*
+  Channels
+
+  A channel is named `<owner>:<name>`. The owner is an extension's package name (or `kempo` for core),
+  so two extensions cannot collide on a name and a channel always says who is responsible for it.
+
+  Channels are closed by default: one must be declared with a permission or an authorize function
+  before anyone can subscribe or publish. The one exception is a user's own `user:<id>` channel, which
+  is implicit and only that user may subscribe to.
+
+  A channel comes from one of two places. Code registers it with `registerChannel`, which only works
+  for something loaded at startup because nothing else runs before the first subscriber connects.
+  An extension instead declares it in its kempo-config.json under `realtime.channels`; that snapshot
+  is stored in the extension table when the extension is installed, so it is available to every
+  process with no file access and no load-order dependency, and disabling the extension closes its
+  channels.
+
+  A channel also says how it behaves:
+
+    scope            "cluster" (default) delivers through Postgres to subscribers on every process.
+                     "process" delivers in memory to subscribers on the process that publishes, never
+                     touching the database, for traffic too fast for the bus. It cannot persist.
+    onMessage        Who handles a message a client sends to the channel. A function when registered in
+                     code; for an extension, a path inside its own package, loaded once and kept in
+                     memory, since a lookup per message would put the database on the hot path.
+    dropIfBackedUp   Deliveries to a client that is already behind are skipped, for data where only the
+                     newest value matters.
+*/
+
+/*
+  State lives on a global keyed by Symbol.for rather than in module scope: kempo can be resolved twice
+  in one process (a symlinked checkout during development, a hoisted copy beside a nested one), and a
+  registration made through one copy would otherwise be invisible to the other.
+*/
+const REGISTRY = Symbol.for('kempo.realtime.channels');
+
+if(!globalThis[REGISTRY]){
+  globalThis[REGISTRY] = new Map();
+}
+
+const registry = () => globalThis[REGISTRY];
+
+export const DEFAULT_RETENTION_MS = 24 * 60 * 60 * 1000;
+export const USER_CHANNEL_PREFIX = 'user:';
+
+const RESERVED_OWNERS = new Set(['user']);
+const OWNER_PATTERN = /^(@[a-z0-9~][a-z0-9._~-]*\/)?[a-z0-9~][a-z0-9._~-]*$/;
+const NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+/*
+  Registration
+*/
+
+export const registerChannel = ({ owner, name, permission, authorize, persist = false, retention, scope = 'cluster', onMessage, dropIfBackedUp = false } = {}) => {
+  if(typeof owner !== 'string' || !OWNER_PATTERN.test(owner) || RESERVED_OWNERS.has(owner)){
+    return [{ code: 400, msg: 'Owner must be an extension package name (or "kempo" for core)' }, null];
+  }
+  if(typeof name !== 'string' || !NAME_PATTERN.test(name)){
+    return [{ code: 400, msg: 'Channel name may contain letters, numbers, dots, dashes and underscores' }, null];
+  }
+  if(!permission && typeof authorize !== 'function'){
+    return [{ code: 400, msg: 'A channel needs a permission or an authorize function, channels are closed by default' }, null];
+  }
+  if(permission !== undefined && (typeof permission !== 'string' || !permission)){
+    return [{ code: 400, msg: 'Permission must be a permission name' }, null];
+  }
+  if(authorize !== undefined && typeof authorize !== 'function'){
+    return [{ code: 400, msg: 'authorize must be a function' }, null];
+  }
+
+  const retentionMs = retention === undefined ? DEFAULT_RETENTION_MS : parseDuration(retention);
+  if(retentionMs === null){
+    return [{ code: 400, msg: 'Retention must be a positive number of milliseconds or a string like "24h"' }, null];
+  }
+  if(scope !== 'cluster' && scope !== 'process'){
+    return [{ code: 400, msg: 'Scope must be "cluster" or "process"' }, null];
+  }
+  if(persist && scope === 'process'){
+    return [{ code: 400, msg: 'A channel with scope "process" cannot persist, since nothing is stored' }, null];
+  }
+  if(onMessage !== undefined && typeof onMessage !== 'function'){
+    return [{ code: 400, msg: 'onMessage must be a function' }, null];
+  }
+
+  const channel = `${owner}:${name}`;
+  if(registry().has(channel)){
+    return [{ code: 409, msg: `Channel "${channel}" is already registered` }, null];
+  }
+
+  registry().set(channel, {
+    channel,
+    owner,
+    name,
+    permission: permission || null,
+    authorize: authorize || null,
+    persist: Boolean(persist),
+    retentionMs,
+    scope,
+    onMessage: onMessage || null,
+    handlerPath: null,
+    dropIfBackedUp: Boolean(dropIfBackedUp),
+    source: 'code'
+  });
+
+  return [null, { channel }];
+};
+
+export const unregisterChannel = (channel) => registry().delete(channel);
+
+/*
+  Resolution
+*/
+
+export const resolveChannel = async (channel) => {
+  if(typeof channel !== 'string' || !channel.includes(':')) return null;
+
+  if(channel.startsWith(USER_CHANNEL_PREFIX)){
+    const userId = channel.slice(USER_CHANNEL_PREFIX.length);
+    if(!userId) return null;
+    return { channel, owner: 'user', name: userId, userId, persist: false, retentionMs: DEFAULT_RETENTION_MS, scope: 'cluster', onMessage: null, handlerPath: null, dropIfBackedUp: false, source: 'implicit' };
+  }
+
+  const registered = registry().get(channel);
+  if(registered) return registered;
+
+  const separator = channel.indexOf(':');
+  const owner = channel.slice(0, separator);
+  const name = channel.slice(separator + 1);
+
+  const extensions = await getEnabledExtensions();
+  const declared = extensions.find(extension => extension.name === owner)?.kempo?.realtime?.channels;
+  if(!Array.isArray(declared)) return null;
+
+  const entry = declared.find(candidate => candidate && candidate.name === name);
+  // A declared channel with no permission is treated as undeclared, since channels are closed by default
+  if(!entry || typeof entry.permission !== 'string' || !entry.permission) return null;
+
+  const retentionMs = entry.retention === undefined ? DEFAULT_RETENTION_MS : parseDuration(entry.retention);
+  if(retentionMs === null) return null;
+
+  /*
+    Anything about the declaration that cannot be honoured closes the channel rather than quietly
+    opening it with different behaviour than the extension asked for.
+  */
+  const scope = entry.scope === undefined ? 'cluster' : entry.scope;
+  if(scope !== 'cluster' && scope !== 'process') return null;
+  if(entry.persist && scope === 'process') return null;
+
+  let handlerPath = null;
+  if(entry.onMessage !== undefined){
+    handlerPath = resolveHandlerPath(owner, entry.onMessage);
+    if(!handlerPath) return null;
+  }
+
+  return {
+    channel,
+    owner,
+    name,
+    permission: entry.permission,
+    authorize: null,
+    persist: Boolean(entry.persist),
+    retentionMs,
+    scope,
+    onMessage: null,
+    handlerPath,
+    dropIfBackedUp: Boolean(entry.dropIfBackedUp),
+    source: 'extension'
+  };
+};
+
+/*
+  Message handlers
+
+  An extension names its handler as a path inside its own package, like a hook callback. The path is
+  resolved against the package and refused if it leaves it, so a manifest cannot point the server at
+  arbitrary code elsewhere on disk.
+*/
+const resolveHandlerPath = (owner, relative) => {
+  if(typeof relative !== 'string' || !relative.startsWith('./')) return null;
+  const root = join(process.cwd(), 'node_modules', owner);
+  const full = resolve(root, relative);
+  return full.startsWith(root + sep) ? full : null;
+};
+
+const HANDLERS = Symbol.for('kempo.realtime.handlers');
+
+if(!globalThis[HANDLERS]){
+  globalThis[HANDLERS] = new Map();
+}
+
+export const clearMessageHandlerCache = () => globalThis[HANDLERS].clear();
+
+/*
+  Loaded once and kept, so handling a message never touches the database or the disk. Returns null for a
+  channel that accepts no messages; throws if a declared handler cannot be loaded, which the caller
+  reports rather than treating as "no handler".
+*/
+export const loadMessageHandler = async (config) => {
+  if(typeof config.onMessage === 'function') return config.onMessage;
+  if(!config.handlerPath) return null;
+
+  let handler = globalThis[HANDLERS].get(config.handlerPath);
+  if(!handler){
+    const module = await import(pathToFileURL(config.handlerPath).href);
+    handler = module.default || module;
+    if(typeof handler !== 'function'){
+      throw new Error(`${config.handlerPath} does not export a function`);
+    }
+    globalThis[HANDLERS].set(config.handlerPath, handler);
+  }
+  return handler;
+};
+
+/*
+  Authorization
+
+  Checked when a client subscribes. A permission granted or revoked afterwards does not affect a
+  subscription that already exists; a session ending does, and is enforced separately.
+*/
+
+export const authorizeSubscription = async ({ config, user }) => {
+  if(!user?.id) return [{ code: 401, msg: 'Authentication required' }, null];
+
+  if(config.source === 'implicit') return [null, config.userId === user.id];
+
+  if(config.permission){
+    const [error, allowed] = await userHasPermission(user.id, config.permission);
+    if(error) return [error, null];
+    if(!allowed) return [null, false];
+  }
+
+  if(config.authorize){
+    try {
+      if(!await config.authorize({ user, channel: config.channel })) return [null, false];
+    } catch(error) {
+      return [{ code: 500, msg: 'Channel authorization failed' }, null];
+    }
+  }
+
+  return [null, true];
+};

package/server/utils/realtime/closeConnection.js

@@ -0,0 +1,4 @@
+import getHub from './getHub.js';
+
+// Only reaches a connection held by this process. To end a user's access everywhere, delete their sessions.
+export default ({ connectionId, code, reason } = {}) => getHub().closeConnection({ connectionId, code, reason });

package/server/utils/realtime/constants.js

@@ -0,0 +1,20 @@
+// The one Postgres NOTIFY channel every kempo process listens on. Kempo channel names travel inside the payload.
+export const BUS_CHANNEL = 'kempo_realtime';
+
+/*
+  NOTIFY payloads must be under 8000 bytes. A message on a channel that does not persist travels in the
+  notification itself, so it is capped a little under that; a persisted message sends only its id.
+*/
+export const MAX_INLINE_BYTES = 7900;
+export const MAX_PERSISTED_BYTES = 1000000;
+
+export const LOCK_PREFIX = 'kempo:realtime:';
+
+// In the 4000-4999 range reserved for applications. The browser client treats it as "do not reconnect".
+export const SESSION_CLOSE_CODE = 4401;
+
+// The user already holds as many connections as they are allowed. Retrying would be refused again, so the client stops.
+export const TOO_MANY_CONNECTIONS_CODE = 4429;
+
+// 1008, policy violation: the connection was sending far faster than a client should
+export const RATE_LIMIT_CLOSE_CODE = 1008;

package/server/utils/realtime/duration.js

@@ -0,0 +1,18 @@
+const UNITS = { ms: 1, s: 1000, m: 60 * 1000, h: 60 * 60 * 1000, d: 24 * 60 * 60 * 1000 };
+
+/*
+  Accepts a number of milliseconds or a string such as "30s", "15m", "24h" or "7d". Returns null for
+  anything else, including zero and negative values, so a caller can tell "invalid" from "no limit".
+*/
+export default (value) => {
+  if(typeof value === 'number'){
+    return Number.isFinite(value) && value > 0 ? value : null;
+  }
+  if(typeof value !== 'string') return null;
+
+  const match = value.trim().match(/^(\d+(?:\.\d+)?)(ms|s|m|h|d)$/);
+  if(!match) return null;
+
+  const milliseconds = Number(match[1]) * UNITS[match[2]];
+  return milliseconds > 0 ? milliseconds : null;
+};

package/server/utils/realtime/getHub.js

@@ -0,0 +1,15 @@
+import Hub from './Hub.js';
+
+/*
+  One hub per process, held on a Symbol.for global for the same reason as the channel registry: the
+  route that accepts a socket and an extension that publishes must reach the same instance even if
+  kempo was resolved twice.
+*/
+const HUB = Symbol.for('kempo.realtime.hub');
+
+export default () => {
+  if(!globalThis[HUB]){
+    globalThis[HUB] = new Hub();
+  }
+  return globalThis[HUB];
+};

package/server/utils/realtime/index.js

@@ -0,0 +1,14 @@
+/*
+  The realtime surface for kempo (CMS) extensions and application code, exposed as `realtime` from
+  `server/sdk.js`. Everything else in this directory is the machinery behind it.
+
+  Whatever is described as "this process" reaches only the connections held by the process it runs in:
+  sockets belong to the process that accepted them.
+*/
+export { registerChannel } from './channels.js';
+export { default as publish } from './publish.js';
+export { default as sendToConnection } from './sendToConnection.js';
+export { default as closeConnection } from './closeConnection.js';
+export { default as listSubscribers } from './listSubscribers.js';
+export { default as listConnections } from './listConnections.js';
+export { default as pruneMessages } from './pruneMessages.js';

package/server/utils/realtime/listConnections.js

@@ -0,0 +1,4 @@
+import getHub from './getHub.js';
+
+// Only this process's connections: sockets are held by the process that accepted them.
+export default () => getHub().listConnections();

package/server/utils/realtime/listSubscribers.js

@@ -0,0 +1,4 @@
+import getHub from './getHub.js';
+
+// The subscribers of a channel that this process holds; other processes hold their own.
+export default ({ channel } = {}) => getHub().listSubscribers({ channel });

package/server/utils/realtime/pruneMessages.js

@@ -0,0 +1,45 @@
+import { and, eq, lt, sql } from 'drizzle-orm';
+import db from '../../db/index.js';
+import { realtimeMessage, realtimeChannel } from '../../db/schema.js';
+import { resolveChannel, DEFAULT_RETENTION_MS } from './channels.js';
+
+/*
+  Deletes persisted messages older than their channel's retention and records how far each channel has
+  been pruned, which is what lets a client that asks for a `since` below that point be told it missed
+  messages instead of quietly getting an incomplete history.
+
+  A channel that can no longer be resolved (its extension was uninstalled or disabled) falls back to
+  the default retention, so orphaned rows still age out.
+*/
+export default async ({ now = new Date() } = {}) => {
+  try {
+    const rows = await db.selectDistinct({ channel: realtimeMessage.channel }).from(realtimeMessage);
+    let deleted = 0;
+
+    for(const { channel } of rows){
+      const config = await resolveChannel(channel);
+      const cutoff = new Date(now.getTime() - (config?.retentionMs ?? DEFAULT_RETENTION_MS));
+
+      const removed = await db
+        .delete(realtimeMessage)
+        .where(and(eq(realtimeMessage.channel, channel), lt(realtimeMessage.createdAt, cutoff)))
+        .returning({ id: realtimeMessage.id });
+
+      if(!removed.length) continue;
+      deleted += removed.length;
+
+      const prunedThrough = Math.max(...removed.map(row => row.id));
+      await db
+        .insert(realtimeChannel)
+        .values({ channel, prunedThrough })
+        .onConflictDoUpdate({
+          target: realtimeChannel.channel,
+          set: { prunedThrough: sql`greatest(${realtimeChannel.prunedThrough}, ${prunedThrough})` }
+        });
+    }
+
+    return [null, { deleted }];
+  } catch(error) {
+    return [{ code: 500, msg: 'Failed to prune realtime messages' }, null];
+  }
+};

package/server/utils/realtime/publish.js

@@ -0,0 +1,86 @@
+import { sql } from 'drizzle-orm';
+import db from '../../db/index.js';
+import { realtimeMessage } from '../../db/schema.js';
+import { resolveChannel } from './channels.js';
+import getHub from './getHub.js';
+import { BUS_CHANNEL, MAX_INLINE_BYTES, MAX_PERSISTED_BYTES, LOCK_PREFIX } from './constants.js';
+
+/*
+  Every message travels through Postgres NOTIFY, including to subscribers held by this same process,
+  so there is a single delivery path and a publish behaves the same whichever process it runs in.
+
+  A channel that persists writes the message to a table first and notifies with only its id. The row
+  and the notification are one transaction, and NOTIFY is delivered on commit, so no listener can be
+  told about a row it cannot yet read. The transaction also takes a lock keyed on the channel: ids are
+  handed out at insert but become visible at commit, so without it two publishes could commit out of
+  order and a client replaying from the earlier id would skip the later-committing row for good.
+*/
+export default async ({ channel, data } = {}) => {
+  if(!channel){
+    return [{ code: 400, msg: 'Channel is required' }, null];
+  }
+  if(data === undefined || data === null){
+    return [{ code: 400, msg: 'Data is required' }, null];
+  }
+
+  const config = await resolveChannel(channel);
+  if(!config){
+    return [{ code: 404, msg: `Channel "${channel}" is not registered` }, null];
+  }
+
+  let serialized;
+  try {
+    serialized = JSON.stringify(data);
+  } catch(error) {
+    return [{ code: 400, msg: 'Data must be JSON-serializable' }, null];
+  }
+  if(serialized === undefined){
+    return [{ code: 400, msg: 'Data must be JSON-serializable' }, null];
+  }
+
+  /*
+    A channel with scope "process" never touches the database: the message is delivered in memory to the
+    subscribers this process holds. That is what makes it fast enough for traffic the bus cannot carry, and
+    it means a publish made in another process does not reach them, which is why the scope is a choice
+    the channel makes and not a default.
+  */
+  if(config.scope === 'process'){
+    if(Buffer.byteLength(serialized) > MAX_PERSISTED_BYTES){
+      return [{ code: 413, msg: `Message is larger than the ${MAX_PERSISTED_BYTES} byte limit` }, null];
+    }
+    return [null, { id: null, delivered: getHub().deliverLocal({ channel, data }) }];
+  }
+
+  if(config.persist){
+    if(Buffer.byteLength(serialized) > MAX_PERSISTED_BYTES){
+      return [{ code: 413, msg: `Message is larger than the ${MAX_PERSISTED_BYTES} byte limit` }, null];
+    }
+
+    try {
+      const id = await db.transaction(async transaction => {
+        await transaction.execute(sql`select pg_advisory_xact_lock(hashtext(${LOCK_PREFIX + channel}))`);
+        const [row] = await transaction
+          .insert(realtimeMessage)
+          .values({ channel, data, createdAt: new Date() })
+          .returning({ id: realtimeMessage.id });
+        await transaction.execute(sql`select pg_notify(${BUS_CHANNEL}, ${JSON.stringify({ c: channel, i: row.id })})`);
+        return row.id;
+      });
+      return [null, { id }];
+    } catch(error) {
+      return [{ code: 500, msg: 'Failed to publish message' }, null];
+    }
+  }
+
+  const payload = JSON.stringify({ c: channel, d: data });
+  if(Buffer.byteLength(payload) > MAX_INLINE_BYTES){
+    return [{ code: 413, msg: `Message is too large for a channel that does not persist (limit ${MAX_INLINE_BYTES} bytes); send less, or register the channel with persist: true` }, null];
+  }
+
+  try {
+    await db.execute(sql`select pg_notify(${BUS_CHANNEL}, ${payload})`);
+    return [null, { id: null }];
+  } catch(error) {
+    return [{ code: 500, msg: 'Failed to publish message' }, null];
+  }
+};

package/server/utils/realtime/sendToConnection.js

@@ -0,0 +1,4 @@
+import getHub from './getHub.js';
+
+// Connection ids belong to the process that holds the connection, so this only reaches one held by this process.
+export default ({ connectionId, data } = {}) => getHub().sendToConnection({ connectionId, data });

package/server/utils/routing/serveUnmatched.js

@@ -1,6 +1,7 @@
 import { join } from 'path';
 import { renderExternalPage } from 'kempo-server/templating';
 import triggerHook from '../hooks/triggerHook.js';
+import { extensionPublicDirs } from '../extensions/contentDirs.js';
 
 /*
   Imported only when a handler actually serves a file. `kempo-server/serve-static-file` is a newer
@@ -102,7 +103,13 @@ export default async (request, response, publicDir) => {
     because nothing served a body. The content type is applied last so it cannot be clobbered.
   */
   try {
-    const html = await renderExternalPage(join(publicDir, 'CATCH.page.html'), publicDir, resolveDir);
+    /*
+      The 404 is an ordinary public page, so it gets the same extension-contributed content every
+      other public page does — a site-wide banner pushed by an extension should not vanish on the
+      one page a lost visitor actually lands on.
+    */
+    const contentDirs = await extensionPublicDirs();
+    const html = await renderExternalPage(join(publicDir, 'CATCH.page.html'), publicDir, resolveDir, {}, {}, 10, contentDirs, contentDirs);
     response.writeHead(404, { ...draft.headers, 'Content-Type': 'text/html; charset=utf-8' });
     response.end(html);
   } catch {

package/server/utils/settings/getPublicSettings.js

@@ -1,14 +1,16 @@
 import db from '../../db/index.js';
 import { setting } from '../../db/schema.js';
-import { eq } from 'drizzle-orm';
+import { eq, and, ne } from 'drizzle-orm';
 import { convertValue } from './helpers.js';
 
 export default async () => {
   try {
+    // isPublic should never be true on a secret (setSetting forces it false), but this is the
+    // one unauthenticated endpoint in the settings system, so exclude 'secret' defensively too.
     const results = await db
       .select()
       .from(setting)
-      .where(eq(setting.isPublic, true));
+      .where(and(eq(setting.isPublic, true), ne(setting.type, 'secret')));
 
     const settings = {};
     for(const s of results){

package/server/utils/settings/getSettingWithMetadata.js

@@ -2,12 +2,13 @@ import db from '../../db/index.js';
 import { setting } from '../../db/schema.js';
 import { eq } from 'drizzle-orm';
 import { convertValue } from './helpers.js';
+import { SECRET_MASK } from './secretCrypto.js';
 
 export default async (owner, name) => {
   if(!owner || !name){
     return [{ code: 400, msg: 'Both owner and name are required' }, null];
   }
-  
+
   try {
     const fullName = `${owner}:${name}`;
     const [result] = await db
@@ -15,12 +16,18 @@ export default async (owner, name) => {
       .from(setting)
       .where(eq(setting.name, fullName))
       .limit(1);
-    
+
     if(!result) return [{ code: 404, msg: 'Setting not found' }, null];
-    
+
+    /*
+      This feeds the HTTP API (GET /kempo/api/settings/[owner]/[name]) — the decrypted value must
+      never travel over the wire, so a secret is masked here rather than passed through convertValue.
+    */
     return [null, {
       name: result.name,
-      value: convertValue(result.value, result.type),
+      value: result.type === 'secret'
+        ? (result.value === null ? null : SECRET_MASK)
+        : convertValue(result.value, result.type),
       type: result.type,
       isPublic: result.isPublic,
       description: result.description,

package/server/utils/settings/helpers.js

@@ -1,6 +1,8 @@
+import { encryptSecret, decryptSecret } from './secretCrypto.js';
+
 export const convertValue = (value, type) => {
   if(value === null) return null;
-  
+
   switch(type){
     case 'number':
       return Number(value);
@@ -8,6 +10,8 @@ export const convertValue = (value, type) => {
       return value === 'true';
     case 'json':
       return JSON.parse(value);
+    case 'secret':
+      return decryptSecret(value);
     case 'string':
     default:
       return value;
@@ -16,10 +20,12 @@ export const convertValue = (value, type) => {
 
 export const serializeValue = (value, type) => {
   if(value === null) return null;
-  
+
   switch(type){
     case 'json':
       return JSON.stringify(value);
+    case 'secret':
+      return encryptSecret(value);
     case 'number':
     case 'boolean':
     case 'string':

package/server/utils/settings/listSettings.js

@@ -1,6 +1,7 @@
 import db from '../../db/index.js';
 import { setting } from '../../db/schema.js';
 import { like, not, and, sql } from 'drizzle-orm';
+import { SECRET_MASK } from './secretCrypto.js';
 
 export default async ({ owner, limit = 50, offset = 0 } = {}) => {
   try {
@@ -16,8 +17,15 @@ export default async ({ owner, limit = 50, offset = 0 } = {}) => {
     const q = db.select().from(setting);
     const cq = db.select({ count: sql`count(*)` }).from(setting);
     if(where){ q.where(where); cq.where(where); }
-    const settings = await q.limit(limit).offset(offset);
+    const results = await q.limit(limit).offset(offset);
     const [{ count }] = await cq;
+
+    // Never send secret ciphertext to the admin UI, not even encrypted.
+    const settings = results.map(s => s.type === 'secret'
+      ? { ...s, value: s.value === null ? null : SECRET_MASK }
+      : s
+    );
+
     return [null, { settings, total: Number(count), limit, offset }];
   } catch(error){
     return [{ code: 500, msg: 'Failed to retrieve settings' }, null];

package/server/utils/settings/secretCrypto.js

@@ -0,0 +1,41 @@
+import crypto from 'crypto';
+
+/*
+  'secret' settings (API keys, webhook signing secrets, etc.) are encrypted at rest with
+  AES-256-GCM. SETTINGS_ENCRYPTION_KEY must be a 64-character hex string (32 bytes) — generate
+  one with `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`.
+
+  Losing or rotating this key makes every stored secret unrecoverable, so it belongs in the same
+  place as DATABASE_URL: set once per environment, backed up, never committed.
+*/
+
+export const SECRET_MASK = '••••••••';
+
+const getKey = () => {
+  const raw = process.env.SETTINGS_ENCRYPTION_KEY;
+  if(!raw){
+    throw new Error('SETTINGS_ENCRYPTION_KEY environment variable is required to store secret settings');
+  }
+  const key = Buffer.from(raw, 'hex');
+  if(key.length !== 32){
+    throw new Error('SETTINGS_ENCRYPTION_KEY must be a 64-character hex string (32 bytes)');
+  }
+  return key;
+};
+
+export const encryptSecret = value => {
+  const iv = crypto.randomBytes(12);
+  const cipher = crypto.createCipheriv('aes-256-gcm', getKey(), iv);
+  const ciphertext = Buffer.concat([cipher.update(String(value), 'utf8'), cipher.final()]);
+  return Buffer.concat([iv, cipher.getAuthTag(), ciphertext]).toString('base64');
+};
+
+export const decryptSecret = encoded => {
+  const data = Buffer.from(encoded, 'base64');
+  const iv = data.subarray(0, 12);
+  const authTag = data.subarray(12, 28);
+  const ciphertext = data.subarray(28);
+  const decipher = crypto.createDecipheriv('aes-256-gcm', getKey(), iv);
+  decipher.setAuthTag(authTag);
+  return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString('utf8');
+};