@underpostnet/cyberia 3.3.0 → 3.3.76

package/src/server/ops/event-notification.js

@@ -0,0 +1,284 @@
+import fs from 'fs-extra';
+import { resolveConfSecrets } from '../runtime/conf.js';
+import { loggerFactory } from './logger.js';
+import { MailerProvider } from '../../mailer/MailerProvider.js';
+
+/**
+ * The notification contract for operational events.
+ *
+ * Detection and remediation are declared in code because they are behaviour;
+ * who hears about them is deployment data, and lives in
+ * `engine-private/deploy/conf.event.json`. Adding a subscriber or repointing a
+ * transport is therefore a configuration change, and no recipient address or
+ * credential reaches the event registry, a rendered manifest, or this
+ * repository.
+ *
+ * @module src/server/ops/event-notification.js
+ * @namespace UnderpostEventNotification
+ */
+
+const logger = loggerFactory(import.meta);
+
+/**
+ * @constant EVENT_CONF_PATH
+ * @description The notification contract, read relative to the engine checkout
+ * every command already resolves its deploy configuration from.
+ * @memberof UnderpostEventNotification
+ */
+const EVENT_CONF_PATH = './engine-private/deploy/conf.event.json';
+
+const EMPTY_CONF = { 'notification-providers': {}, events: {} };
+
+/** What a rule writes where its declared threshold belongs. */
+const THRESHOLD_TOKEN = '<threshold>';
+
+/**
+ * @method readEventConf
+ * @description Parses the contract without resolving `env:` references.
+ *
+ * Structure and secrets are read apart so the shape can be listed, validated
+ * and tested on a machine that holds none of the credentials.
+ * @returns {{'notification-providers': object, events: object}} Parsed contract.
+ * @throws {Error} When the file exists but does not parse.
+ * @memberof UnderpostEventNotification
+ */
+const readEventConf = () => {
+  if (!fs.existsSync(EVENT_CONF_PATH)) return { ...EMPTY_CONF };
+  try {
+    const source = JSON.parse(fs.readFileSync(EVENT_CONF_PATH, 'utf8'));
+    return {
+      'notification-providers': source['notification-providers'] || {},
+      events: source.events || {},
+    };
+  } catch (error) {
+    throw new Error(`[event] invalid notification contract ${EVENT_CONF_PATH}: ${error.message}`);
+  }
+};
+
+const recipientFactory = (subscriber = {}) => {
+  const email = `${subscriber.email || ''}`.trim();
+  const name = `${subscriber.name || ''}`.trim();
+  return email ? { email, name, address: name ? `${name} <${email}>` : email } : undefined;
+};
+
+/**
+ * @constant NOTIFICATION_PROVIDER_TYPES
+ * @description The transports a notification route can name.
+ *
+ * `describe` renders the route for `--list` and validates it; `deliver` sends
+ * one rendered notification. A type is one entry here, so adding a transport
+ * never means editing the dispatcher.
+ * @memberof UnderpostEventNotification
+ */
+const NOTIFICATION_PROVIDER_TYPES = {
+  mailer: {
+    describe: (provider) => {
+      const transport = provider?.mailer?.transport || {};
+      const host = `${transport.host || ''}`.replace(/^env:.*/, '(env)');
+      if (!transport.host) throw new Error('mailer provider has no transport.host');
+      if (!provider?.mailer?.sender?.email) throw new Error('mailer provider has no sender.email');
+      return `smtp ${host}`;
+    },
+    deliver: async ({ providerId, provider, recipients, subject, text }) => {
+      const mailer = resolveConfSecrets(provider.mailer);
+      const port = Number(mailer.transport?.port) || 587;
+      const id = `event-notification:${providerId}`;
+
+      await MailerProvider.load({
+        id,
+        sender: { email: mailer.sender.email, name: mailer.sender.name || 'Underpost' },
+        transport: {
+          host: mailer.transport.host,
+          port,
+          secure: `${mailer.transport?.secure}` === 'true' || port === 465,
+          auth: { user: mailer.transport?.auth?.user || '', pass: mailer.transport?.auth?.pass || '' },
+        },
+        templates: {},
+      });
+
+      // Plain text by design: an operational alert must not depend on a client
+      // build being present on the host that dispatches it.
+      try {
+        const info = await MailerProvider.send({
+          id,
+          sendOptions: { to: recipients.map((recipient) => recipient.address).join(', '), subject, text },
+        });
+        return Boolean(info);
+      } finally {
+        // One delivery per dispatch: an open SMTP socket would outlive the
+        // command that sent it and keep the process from exiting.
+        MailerProvider.close(id);
+      }
+    },
+  },
+};
+
+/**
+ * @method eventNotificationRoutes
+ * @description Resolves where one event's notifications go.
+ *
+ * An unresolvable route is returned carrying its reason rather than thrown, so
+ * `--list` can show a broken contract before an outage does.
+ * @param {string} eventId - Registered event id.
+ * @param {object} [conf] - Parsed contract; read from disk when omitted.
+ * @returns {Array<{providerId: string, type: string, target: string, recipients: Array<object>, error?: string}>} Routes.
+ * @memberof UnderpostEventNotification
+ */
+const eventNotificationRoutes = (eventId, conf = readEventConf()) => {
+  const providers = conf['notification-providers'] || {};
+  const notifications = conf.events?.[eventId]?.notifications || [];
+
+  if (notifications.length === 0)
+    return [
+      {
+        providerId: '',
+        type: '',
+        target: '',
+        recipients: [],
+        error: `no notification is declared for '${eventId}' in ${EVENT_CONF_PATH}`,
+      },
+    ];
+
+  return notifications.map((notification) => {
+    const providerId = `${notification['notification-provider-id'] || ''}`;
+    const provider = providers[providerId];
+    const recipients = (notification.payload?.subscribers || []).map(recipientFactory).filter(Boolean);
+    const route = { providerId, type: `${provider?.type || ''}`, target: '', recipients };
+
+    if (!provider)
+      return { ...route, error: `notification-provider-id '${providerId}' is not declared in ${EVENT_CONF_PATH}` };
+    const type = NOTIFICATION_PROVIDER_TYPES[route.type];
+    if (!type) return { ...route, error: `unsupported notification provider type '${route.type}'` };
+    if (recipients.length === 0) return { ...route, error: `provider '${providerId}' has no subscriber with an email` };
+    try {
+      return { ...route, target: type.describe(provider), provider };
+    } catch (error) {
+      return { ...route, error: `provider '${providerId}': ${error.message}` };
+    }
+  });
+};
+
+/**
+ * @method assertNotificationRoutes
+ * @description Refuses a contract that cannot deliver.
+ *
+ * Detection without a route to a human is the failure mode this guards: the
+ * remediation runs, nobody learns it ran, and a repeated repair goes unnoticed.
+ * @param {Array<object>} routes - Resolved routes, keyed by event id.
+ * @returns {Array<object>} The same routes, when every one resolves.
+ * @throws {Error} Naming each unresolved route.
+ * @memberof UnderpostEventNotification
+ */
+const assertNotificationRoutes = (routes = []) => {
+  const unresolved = routes.filter((route) => route.error);
+  if (unresolved.length > 0)
+    throw new Error(
+      `[event] notification routes are unresolved:\n${unresolved.map((route) => `- ${route.error}`).join('\n')}`,
+    );
+  return routes;
+};
+
+/**
+ * @method deliverEventNotification
+ * @description Sends one rendered notification over every route the event declares.
+ *
+ * Routes are independent subscribers: one failing transport must not silence
+ * the rest, so each is attempted and reported separately.
+ * @param {object} params
+ * @param {string} params.eventId - Dispatched event id.
+ * @param {string} params.subject - Rendered subject.
+ * @param {string} params.text - Rendered body.
+ * @returns {Promise<{ok: boolean, delivered: Array<object>, failed: Array<object>}>} Per-route outcome.
+ * @memberof UnderpostEventNotification
+ */
+const deliverEventNotification = async ({ eventId, subject, text }) => {
+  const routes = eventNotificationRoutes(eventId);
+  const delivered = [];
+  const failed = [];
+
+  for (const route of routes) {
+    const recipients = route.recipients.map((recipient) => recipient.email);
+    if (route.error) {
+      failed.push({ providerId: route.providerId, recipients, error: route.error });
+      continue;
+    }
+    try {
+      const ok = await NOTIFICATION_PROVIDER_TYPES[route.type].deliver({
+        providerId: route.providerId,
+        provider: route.provider,
+        recipients: route.recipients,
+        subject,
+        text,
+      });
+      if (ok) delivered.push({ providerId: route.providerId, recipients });
+      else failed.push({ providerId: route.providerId, recipients, error: 'transport rejected the message' });
+    } catch (error) {
+      failed.push({ providerId: route.providerId, recipients, error: `${error?.message || error}` });
+    }
+  }
+
+  for (const route of failed) logger.error('Event notification not delivered', { eventId, ...route });
+  if (delivered.length > 0) logger.info('Event notification delivered', { eventId, subject, routes: delivered });
+
+  return { ok: failed.length === 0 && delivered.length > 0, delivered, failed };
+};
+
+/**
+ * @method eventSchedule
+ * @description When an event's probes run, and how long its condition must hold
+ * before an alert fires.
+ *
+ * Both are declared per event in the contract rather than in the registry: how
+ * often a subject is asked and how long it must stay wrong are operational
+ * decisions tuned per deployment, and they are the two numbers Prometheus needs
+ * to schedule a job and evaluate the rule that job feeds. Reading them from one
+ * place is what stops a probe period and its alert window from drifting apart.
+ * @param {string} eventId - Registered event id.
+ * @param {object} [conf] - Parsed contract; read from disk when omitted.
+ * @returns {{probeInterval: string, alertFor: string, threshold: string}} Declared schedule; empty when undeclared.
+ * @memberof UnderpostEventNotification
+ */
+const eventSchedule = (eventId, conf = readEventConf()) => {
+  const event = conf.events?.[eventId] || {};
+  return {
+    probeInterval: `${event.probeInterval || ''}`.trim(),
+    alertFor: `${event.alertFor || ''}`.trim(),
+    // A number the rule compares against: it belongs beside the cadence, not in
+    // an expression, because tuning it is a deployment decision.
+    threshold: `${event.threshold ?? ''}`.trim(),
+  };
+};
+
+/**
+ * @method assertEventSchedules
+ * @description Refuses to publish a rule whose cadence the contract does not declare.
+ *
+ * An undeclared period would silently inherit the global scrape interval and an
+ * undeclared window a hardcoded default — the second source of truth these
+ * attributes exist to remove.
+ * @param {Array<{id: string, schedule: object}>} [definitions] - Resolved definitions.
+ * @returns {Array<object>} The same definitions, when every schedule is declared.
+ * @throws {Error} Naming each event and the attribute it is missing.
+ * @memberof UnderpostEventNotification
+ */
+const assertEventSchedules = (definitions = []) => {
+  const missing = definitions.flatMap(({ id, alert = {}, schedule = {} }) =>
+    ['probeInterval', 'alertFor', ...(`${alert.expr || ''}`.includes(THRESHOLD_TOKEN) ? ['threshold'] : [])]
+      .filter((key) => !schedule[key])
+      .map((key) => `- ${id}: ${key}`),
+  );
+  if (missing.length > 0) throw new Error(`[event] undeclared in ${EVENT_CONF_PATH}:\n${missing.join('\n')}`);
+  return definitions;
+};
+
+export {
+  EVENT_CONF_PATH,
+  THRESHOLD_TOKEN,
+  assertEventSchedules,
+  eventSchedule,
+  NOTIFICATION_PROVIDER_TYPES,
+  assertNotificationRoutes,
+  deliverEventNotification,
+  eventNotificationRoutes,
+  readEventConf,
+};

package/src/server/{logger.js → ops/logger.js}

@@ -1,6 +1,6 @@
 /**
  * Module for managing logger control and configuration
- * @module src/server/logger.js
+ * @module src/server/ops/logger.js
  * @namespace Logger
  */
 
@@ -11,7 +11,7 @@ import morgan from 'morgan';
 import { colorize, color } from 'json-colorizer';
 import colors from 'colors';
 import v8 from 'v8';
-import { clearTerminalStringColor, formatBytes } from '../client/components/core/CommonJs.js';
+import { clearTerminalStringColor, formatBytes } from '../../client/components/core/CommonJs.js';
 
 colors.enable();
 
@@ -34,6 +34,128 @@ const levels = {
  */
 const level = (logLevel = '') => logLevel || 'info';
 
+const REDACTED = '[REDACTED]';
+const CONFIG_NAME_SOURCE = '[A-Za-z_][A-Za-z0-9_.-]*';
+const SENSITIVE_VALUE_SOURCE = '(?:"[^"\\r\\n]*"|\'[^\'\\r\\n]*\'|[^\\s;&|]+)';
+const SENSITIVE_WORDS = new Set([
+  'authorization',
+  'cookie',
+  'credential',
+  'pass',
+  'passwd',
+  'password',
+  'secret',
+  'token',
+]);
+const SENSITIVE_COMPOUNDS = ['apikey', 'privatekey', 'accesskey', 'sessionid', 'mysqlpwd', 'mariadbpwd'];
+/**
+ * A value adjacent to a sensitive name, separated by nothing but whitespace, is only treated as
+ * the secret when it is shaped like one: long enough, and carrying a digit, a capital, or a
+ * separator. Prose reads the same way — `token verification failed` — and redacting the next
+ * word of every sentence would cost more than it protects.
+ */
+const CREDENTIAL_SHAPED = /^(?=.{12,}$)(?=.*[0-9A-Z_-])[A-Za-z0-9_-]+$/;
+const sensitiveField = (key) => {
+  const words = `${key || ''}`
+    .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter(Boolean);
+  const compact = words.join('');
+  return (
+    words.some((word) => SENSITIVE_WORDS.has(word)) ||
+    SENSITIVE_COMPOUNDS.some((compound) => compact.endsWith(compound))
+  );
+};
+
+/**
+ * Redacts a value that follows a sensitive name with nothing but whitespace between them.
+ *
+ * Service errors report credentials this way — `Invalid api_key 4778…` — so the pair reaches a
+ * log through a message rather than through a command or a structured field, which is what every
+ * other rule matches on. The candidate is looked ahead rather than consumed: a plain match would
+ * take `Invalid api_key` as its own name/value pair and advance past the real one behind it.
+ * @param {string} text - Text to scan.
+ * @returns {string} The text with adjacent credentials redacted.
+ * @memberof Logger
+ */
+const redactAdjacentCredentials = (text) => {
+  const pairs = new RegExp(`(${CONFIG_NAME_SOURCE})([ \\t]+)(?=([A-Za-z0-9_-]+)(?![\\w-]))`, 'g');
+  let out = '';
+  let cursor = 0;
+  for (const match of text.matchAll(pairs)) {
+    const [, key, separator, candidate] = match;
+    const valueStart = match.index + key.length + separator.length;
+    if (valueStart < cursor) continue;
+    if (!sensitiveField(key) || !CREDENTIAL_SHAPED.test(candidate)) continue;
+    out += text.slice(cursor, valueStart) + REDACTED;
+    cursor = valueStart + candidate.length;
+  }
+  return cursor === 0 ? text : out + text.slice(cursor);
+};
+
+const redactSensitiveText = (value = '') =>
+  redactAdjacentCredentials(
+    `${value ?? ''}`
+      .replace(/-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z0-9 ]*PRIVATE KEY-----/g, REDACTED)
+      .replace(
+        /\b(?:gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|glpat-[A-Za-z0-9_-]{20,}|xox[baprs]-[A-Za-z0-9-]{10,}|eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+)\b/g,
+        REDACTED,
+      )
+      .replace(/([a-z][a-z0-9+.-]*\\?:(?:\\?\/){2})(?:(?:\\.)|[^/\\\s@])+(\\?@)/gi, '$1***$2')
+      .replace(/\b(x-access-token\\?:)[^\s"']+?(?=\\?@github\.com\b)/gi, '$1***')
+      .replace(
+        /((?:"|')?(?:authorization|proxy-authorization)(?:"|')?\s*:\s*)(?:"[^"]*"|'[^']*'|(?:bearer|basic)\s+\S+|\S+)/gi,
+        `$1"${REDACTED}"`,
+      )
+      .replace(
+        new RegExp(
+          `(\\b(?:host|app|state|secret)\\s+set\\s+)(${CONFIG_NAME_SOURCE})(\\s+)(${SENSITIVE_VALUE_SOURCE})`,
+          'gi',
+        ),
+        (match, prefix, key, separator) => (sensitiveField(key) ? `${prefix}${key}${separator}${REDACTED}` : match),
+      )
+      .replace(
+        new RegExp(`(\\s--?)(${CONFIG_NAME_SOURCE})(=|\\s+)(${SENSITIVE_VALUE_SOURCE})`, 'gi'),
+        (match, prefix, key, separator) => (sensitiveField(key) ? `${prefix}${key}${separator}${REDACTED}` : match),
+      )
+      .replace(
+        new RegExp(`(^|\\s)(-p)(\\s*)(${SENSITIVE_VALUE_SOURCE})`, 'gi'),
+        (match, prefix, flag, separator, secret) =>
+          secret.startsWith('-') ? match : `${prefix}${flag}${separator}${REDACTED}`,
+      )
+      .replace(
+        new RegExp(`\\b(${CONFIG_NAME_SOURCE})(\\s*=\\s*)(${SENSITIVE_VALUE_SOURCE})`, 'gi'),
+        (match, key, separator) => (sensitiveField(key) ? `${key}${separator}${REDACTED}` : match),
+      )
+      .replace(
+        new RegExp(`((?:"|')?)(${CONFIG_NAME_SOURCE})((?:"|')?\\s*:\\s*)(${SENSITIVE_VALUE_SOURCE})`, 'gi'),
+        (match, quote, key, separator) => (sensitiveField(key) ? `${quote}${key}${separator}"${REDACTED}"` : match),
+      ),
+  );
+
+const serializeLogValue = (value) => {
+  const seen = new WeakSet();
+  const serialized = JSON.stringify(
+    value,
+    (key, current) => {
+      if (key && sensitiveField(key)) return REDACTED;
+      if (typeof current === 'string') return redactSensitiveText(current);
+      if (typeof current === 'bigint') return `${current}`;
+      if (typeof current === 'function') return `[Function: ${current.name || 'anonymous'}]`;
+      if (current instanceof Error)
+        return Object.fromEntries(Object.getOwnPropertyNames(current).map((name) => [name, current[name]]));
+      if (typeof current === 'object' && current !== null) {
+        if (seen.has(current)) return '[Circular]';
+        seen.add(current);
+      }
+      return current;
+    },
+    4,
+  );
+  return serialized === undefined ? redactSensitiveText(`${value ?? ''}`) : serialized;
+};
+
 // Define different colors for each level.
 // Colors make the log message more visible,
 // adding the ability to focus or ignore messages.
@@ -49,7 +171,7 @@ winston.addColors({
 });
 
 // Chose the aspect of your log customizing the log format.
-const format = (meta) =>
+const loggerFormatFactory = (meta) =>
   winston.format.combine(
     // winston.format.errors({ stack: true }),
     // Add the message timestamp with the preferred format
@@ -61,25 +183,13 @@ const format = (meta) =>
       const splatKey = Symbol.for('splat');
       const splat = info[splatKey];
       const hasSplat = Array.isArray(splat) && splat.length > 0 && splat[0] !== undefined;
-      let splatStr = '';
-      if (hasSplat) {
-        const seen = new WeakSet();
-        splatStr = JSON.stringify(
-          splat[0],
-          (key, value) => {
-            if (typeof value === 'function') return `[Function: ${value.name || 'anonymous'}]`;
-            if (typeof value === 'object' && value !== null) {
-              if (seen.has(value)) return '[Circular]';
-              seen.add(value);
-            }
-            return value;
-          },
-          4,
-        );
-      }
+      const splatStr = hasSplat ? serializeLogValue(splat[0]) : '';
+      const message = redactSensitiveText(
+        info.message instanceof Error ? info.message.stack || info.message.message : info.message,
+      );
       return `${`[${meta}]`.green} ${info.timestamp} ${info.level} ${
         hasSplat
-          ? `${clearTerminalStringColor(info.message)}: ${colorize(splatStr, {
+          ? `${clearTerminalStringColor(message)}: ${colorize(splatStr, {
               colors: {
                 StringKey: color.green,
                 StringLiteral: color.magenta,
@@ -88,7 +198,7 @@ const format = (meta) =>
                 NullLiteral: color.white,
               },
             })}`
-          : info.message
+          : message
       }`;
     }),
   );
@@ -158,7 +268,7 @@ const loggerFactory = (
     defaultMeta: meta,
     level: level(logLevel),
     levels,
-    format: format(meta),
+    format: loggerFormatFactory(meta),
     transports,
     // exceptionHandlers: [new winston.transports.File({ filename: 'exceptions.log' })],
     // rejectionHandlers: [new winston.transports.File({ filename: 'rejections.log' })],
@@ -226,4 +336,14 @@ const actionInitLog = () =>
 `,
   );
 
-export { loggerFactory, loggerMiddleware, setUpInfo, underpostASCII, actionInitLog };
+export {
+  REDACTED,
+  actionInitLog,
+  loggerFactory,
+  loggerFormatFactory,
+  loggerMiddleware,
+  redactSensitiveText,
+  serializeLogValue,
+  setUpInfo,
+  underpostASCII,
+};