@underpostnet/cyberia 3.3.0 → 3.3.73

package/src/server/{dns.js → network/dns.js}

@@ -1,17 +1,17 @@
 /**
  * Provides a comprehensive set of DNS and IP management utilities,
  * primarily focused on dynamic DNS (DDNS) updates and network checks.
- * @module src/server/dns.js
+ * @module src/server/network/dns.js
  * @namespace UnderpostDns
  */
 import axios from 'axios';
 import validator from 'validator';
-import { loggerFactory } from './logger.js';
+import { loggerFactory } from '../ops/logger.js';
 import dns from 'node:dns';
 import os from 'node:os';
-import { shellExec, pbcopy } from './process.js';
-import Underpost from '../index.js';
-import { readConfJson } from './conf.js';
+import { shellExec, pbcopy } from '../runtime/process.js';
+import Underpost from '../../index.js';
+import { readConfJson } from '../runtime/conf.js';
 
 const logger = loggerFactory(import.meta);
 
@@ -276,7 +276,50 @@ class Dns {
    * @static
    * @memberof UnderpostDns
    */
+  static ensureFilterChains(chains = ['output', 'forward']) {
+    // A stock RHEL 9 host with firewalld keeps its rules in `inet firewalld`;
+    // there is no `inet filter` table, so every policy command below fails with
+    // "No such file or directory". They used to fail silently, which is the
+    // worst possible outcome for this subsystem: the caller logged a successful
+    // block, the bandwidth guard latched, and the overage it exists to stop
+    // kept accruing against a host that was never blocked.
+    //
+    // Creating our own base chains is additive rather than a firewalld
+    // takeover — nftables evaluates every table, so a drop here still wins.
+    const ran = (command) => shellExec(command, { silent: true, silentOnError: true })?.code === 0;
+    const chainExists = (chain) => ran(`sudo nft list chain inet filter ${chain}`);
+    const missing = chains.filter((chain) => !chainExists(chain));
+    if (missing.length === 0) return true;
+    if (!ran(`sudo nft add table inet filter`)) return false;
+    for (const chain of missing) {
+      const hook = chain === 'input' ? 'input' : chain;
+      if (!ran(`sudo nft add chain inet filter ${chain} '{ type filter hook ${hook} priority 0; policy accept; }'`))
+        return false;
+    }
+    return chains.every(chainExists);
+  }
+
+  /**
+   * Whether a chain currently carries the given policy.
+   * @static
+   * @param {string} chain - Chain name in `inet filter`.
+   * @param {string} policy - `accept` or `drop`.
+   * @returns {boolean} True when the chain reports that policy.
+   * @memberof UnderpostDns
+   */
+  static chainPolicyIs(chain, policy) {
+    const listing = shellExec(`sudo nft list chain inet filter ${chain}`, {
+      silent: true,
+      stdout: true,
+      silentOnError: true,
+    });
+    return `${listing || ''}`.includes(`policy ${policy}`);
+  }
+
   static blockAllEgress() {
+    if (!Dns.ensureFilterChains(['output', 'forward']))
+      throw new Error('[dns] could not create the inet filter chains; egress is NOT blocked');
+
     // Clear any existing egress rules.
     shellExec(`sudo nft flush chain inet filter output`, { silent: true });
     shellExec(`sudo nft flush chain inet filter forward`, { silent: true });
@@ -289,6 +332,12 @@ class Dns {
     shellExec(`sudo nft chain inet filter output '{ policy drop; }'`, { silent: true });
     shellExec(`sudo nft chain inet filter forward '{ policy drop; }'`, { silent: true });
 
+    // Read the policy back. The caller latches on this command's exit code, so
+    // reporting a block that did not land is what lets an overage run unbounded.
+    for (const chain of ['output', 'forward'])
+      if (!Dns.chainPolicyIs(chain, 'drop'))
+        throw new Error(`[dns] inet filter ${chain} is not 'policy drop'; egress is NOT blocked`);
+
     logger.info('All outbound traffic blocked.');
   }
 
@@ -299,6 +348,13 @@ class Dns {
    * @memberof UnderpostDns
    */
   static unblockAllEgress() {
+    // Nothing to restore when the chains were never created — that host was
+    // never blocked, and saying so beats failing on a missing table.
+    if (!Dns.ensureFilterChains(['output', 'forward'])) {
+      logger.info('No inet filter chains on this host; egress was never blocked.');
+      return;
+    }
+
     // Restore default chain policies to accept all traffic.
     shellExec(`sudo nft chain inet filter output '{ policy accept; }'`, { silent: true });
     shellExec(`sudo nft chain inet filter forward '{ policy accept; }'`, { silent: true });
@@ -307,9 +363,30 @@ class Dns {
     shellExec(`sudo nft flush chain inet filter output`, { silent: true });
     shellExec(`sudo nft flush chain inet filter forward`, { silent: true });
 
+    for (const chain of ['output', 'forward'])
+      if (!Dns.chainPolicyIs(chain, 'accept'))
+        throw new Error(`[dns] inet filter ${chain} is still not 'policy accept'; egress remains blocked`);
+
     logger.info('All outbound traffic unblocked and restored to default ACCEPT policy.');
   }
 
+  /**
+   * Ensures the chain every ingress rule is installed into exists.
+   *
+   * `inet filter` can be present with no `input` chain — a firewalld host keeps
+   * its rules in `inet firewalld` and never creates one — and every ingress
+   * command below then fails on a table that looks like it is there. Creating it
+   * with an accept policy and no rules changes nothing by itself.
+   * @static
+   * @memberof UnderpostDns
+   */
+  static ensureIngressChain() {
+    shellExec(`sudo nft add table inet filter`, { silent: true });
+    shellExec(`sudo nft add chain inet filter input '{ type filter hook input priority 0; policy accept; }'`, {
+      silent: true,
+    });
+  }
+
   /**
    * Blocks all new inbound traffic to this host, except for established/related connections.
    * This prevents any new incoming connections while keeping existing sessions (like SSH) alive.
@@ -317,6 +394,7 @@ class Dns {
    * @memberof UnderpostDns
    */
   static blockAllIngress() {
+    Dns.ensureIngressChain();
     // Clear any existing ingress rules.
     shellExec(`sudo nft flush chain inet filter input`, { silent: true });
 
@@ -330,6 +408,50 @@ class Dns {
     logger.info('All new inbound traffic blocked.');
   }
 
+  /**
+   * Blocks new inbound traffic to specific TCP ports, leaving every other port
+   * reachable.
+   *
+   * Unlike {@link UnderpostDns.blockAllIngress}, the management path survives:
+   * blocking the public edge ports takes published services down while the host
+   * can still be reached to put them back. That is the only form of induced
+   * ingress outage a remote operator can recover from.
+   * @static
+   * @param {string} ports - Comma-separated TCP ports.
+   * @memberof UnderpostDns
+   */
+  static blockIngressPort(ports) {
+    Dns.ensureIngressChain();
+    for (const port of Dns.portListFactory(ports))
+      shellExec(`sudo nft insert rule inet filter input tcp dport ${port} counter drop`, { silent: true });
+    logger.info('Inbound traffic blocked on ports', { ports: Dns.portListFactory(ports) });
+  }
+
+  /**
+   * Withdraws the port rules {@link UnderpostDns.blockIngressPort} installed.
+   * @static
+   * @param {string} ports - Comma-separated TCP ports.
+   * @memberof UnderpostDns
+   */
+  static unblockIngressPort(ports) {
+    Dns.ensureIngressChain();
+    for (const port of Dns.portListFactory(ports))
+      shellExec(
+        `sudo sh -c "nft -a list chain inet filter input | awk '/tcp dport ${port} .*drop/ {print \\$NF}' | ` +
+          `xargs -r -n1 nft delete rule inet filter input handle"`,
+        { silent: true },
+      );
+    logger.info('Inbound traffic unblocked on ports', { ports: Dns.portListFactory(ports) });
+  }
+
+  /** Parses a comma-separated port list, keeping only valid TCP ports. */
+  static portListFactory(ports = '') {
+    return `${ports || ''}`
+      .split(',')
+      .map((port) => Number(`${port}`.trim()))
+      .filter((port) => Number.isInteger(port) && port > 0 && port <= 65535);
+  }
+
   /**
    * Unblocks all inbound traffic to this host.
    * Restores default input chain policy to ACCEPT and clears ingress rules.
@@ -337,6 +459,7 @@ class Dns {
    * @memberof UnderpostDns
    */
   static unblockAllIngress() {
+    Dns.ensureIngressChain();
     // Restore default chain policy to accept all incoming traffic.
     shellExec(`sudo nft chain inet filter input '{ policy accept; }'`, { silent: true });
 
@@ -354,7 +477,7 @@ class Dns {
    * @memberof UnderpostDns
    * @param {string} deployList Comma-separated string of deployment IDs to process.
    * @returns {Promise<void>}
-  */
+   */
   static async callback(deployList) {
     const isOnline = await Dns.isInternetConnection();
 
@@ -368,11 +491,11 @@ class Dns {
       logger.error(error, { testIp, stack: error.stack });
     }
 
-    const currentIp = Underpost.env.get('ip');
+    const currentIp = Underpost.host.store.get('ip');
 
-    if (validator.isIP(testIp) && currentIp !== testIp) {
+    if (testIp && validator.isIP(testIp) && currentIp !== testIp) {
       logger.info(`New IP detected`, testIp);
-      Underpost.env.set('monitor-input', 'pause');
+      Underpost.host.store.set('monitor-input', 'pause');
 
       for (const _deployId of deployList.split(',')) {
         const deployId = _deployId.trim();
@@ -415,8 +538,8 @@ class Dns {
           logger.info(ipUrlTest + ' verify ip', verifyIp);
           if (verifyIp === testIp) {
             logger.info('IP updated successfully and verified', testIp);
-            Underpost.env.set('ip', testIp);
-            Underpost.env.delete('monitor-input');
+            Underpost.host.store.set('ip', testIp);
+            Underpost.host.store.delete('monitor-input');
           } else {
             logger.error('IP not updated or verification failed', { expected: testIp, received: verifyIp });
           }
@@ -517,6 +640,8 @@ class Dns {
    * @property {boolean} [options.unblockAllEgress=false] - Unblock all outbound traffic.
    * @property {boolean} [options.blockAllIngress=false] - Block all new inbound traffic to this host.
    * @property {boolean} [options.unblockAllIngress=false] - Unblock all inbound traffic.
+   * @property {string} [options.blockIngressPort=''] - Comma-separated TCP ports to block inbound.
+   * @property {string} [options.unblockIngressPort=''] - Comma-separated TCP ports to unblock inbound.
    * @property {boolean} [options.dhcp=false] - Get local DHCP IP instead of public IP.
    * @property {boolean} [options.copy=false] - Copy the public IP to clipboard.
    * @return {Promise<string|void>} The public IP if no ban/unban action is taken.
@@ -538,6 +663,8 @@ class Dns {
       unblockAllEgress: false,
       blockAllIngress: false,
       unblockAllIngress: false,
+      blockIngressPort: '',
+      unblockIngressPort: '',
       copy: false,
       dhcp: false,
     },
@@ -594,6 +721,12 @@ class Dns {
     if (options.unblockAllEgress) {
       return Dns.unblockAllEgress();
     }
+    if (options.blockIngressPort) {
+      return Dns.blockIngressPort(options.blockIngressPort);
+    }
+    if (options.unblockIngressPort) {
+      return Dns.unblockIngressPort(options.unblockIngressPort);
+    }
     if (options.blockAllIngress) {
       return Dns.blockAllIngress();
     }

package/src/server/{forward-proxy.js → network/forward-proxy.js}

@@ -1,6 +1,6 @@
 /**
  * Authenticated HTTP/HTTPS forward-proxy primitives.
- * @module src/server/forward-proxy.js
+ * @module src/server/network/forward-proxy.js
  * @namespace ForwardProxy
  */
 'use strict';
@@ -9,14 +9,15 @@ import http from 'node:http';
 import https from 'node:https';
 import net from 'node:net';
 import os from 'node:os';
-import { environmentValueFactory } from './environment.js';
-import { loggerFactory, loggerMiddleware } from './logger.js';
+import { environmentValueFactory } from '../runtime/environment.js';
+import { loggerFactory, loggerMiddleware } from '../ops/logger.js';
 import {
-  homeDirectoryPathFactory,
-  systemdRunCommandFactory,
+  nodeCandidatesFactory,
+  nodeProbeCommandFactory,
+  scriptProbeCommandFactory,
   systemdServiceCommandsFactory,
   systemdUnitFactory,
-} from './systemd.js';
+} from '../ops/systemd.js';
 
 const logger = loggerFactory(import.meta);
 const proxyLogger = loggerFactory(import.meta, 'debug');
@@ -181,11 +182,7 @@ const forwardProxyCommandFactory = ({ host, port, execPath = process.execPath, s
 const forwardProxyNodeCandidatesFactory = ({
   execPath = process.execPath,
   systemPaths = FORWARD_PROXY.nodePaths,
-} = {}) => {
-  const own = `${execPath || ''}`.trim();
-  const inHome = homeDirectoryPathFactory(own);
-  return [...new Set([...(own && !inHome ? [own] : []), ...systemPaths, ...(own && inHome ? [own] : [])])];
-};
+} = {}) => nodeCandidatesFactory({ execPath, systemPaths });
 
 /**
  * Builds a transient systemd command that probes a Node executable.
@@ -196,7 +193,7 @@ const forwardProxyNodeCandidatesFactory = ({
  * @memberof ForwardProxy
  */
 const forwardProxyNodeProbeCommandFactory = (nodePath, user = os.userInfo().username) =>
-  systemdRunCommandFactory({ command: `${nodePath} --version`, user, properties: { Type: 'oneshot' } });
+  nodeProbeCommandFactory(nodePath, user);
 
 /**
  * Builds a transient systemd command that probes the proxy entry script.
@@ -210,12 +207,7 @@ const forwardProxyStartProbeCommandFactory = ({
   scriptPath = process.argv[1],
   user = os.userInfo().username,
   workingDirectory = process.cwd(),
-}) =>
-  systemdRunCommandFactory({
-    command: `${nodePath} ${scriptPath} --version`,
-    user,
-    properties: { Type: 'oneshot', WorkingDirectory: workingDirectory },
-  });
+}) => scriptProbeCommandFactory({ nodePath, scriptPath, user, workingDirectory });
 
 /**
  * Renders the systemd unit used to supervise the forward proxy.

package/src/server/{middlewares.js → network/middlewares.js}

@@ -1,12 +1,12 @@
 /**
  * Express middleware and controller/router helpers for engine APIs.
  *
- * @module src/server/middlewares.js
+ * @module src/server/network/middlewares.js
  * @namespace Middlewares
  */
 
-import { loggerFactory } from './logger.js';
-import { moderatorGuard, adminGuard } from './auth.js';
+import { loggerFactory } from '../ops/logger.js';
+import { moderatorGuard, adminGuard } from '../security/auth.js';
 
 const logger = loggerFactory(import.meta);
 

package/src/server/network/node-capability.js

@@ -0,0 +1,98 @@
+/**
+ * What each node role is allowed to do, as one table the rest of the platform reads.
+ *
+ * The roles are the three the topology already defines — `hub`, `control`, `worker` — and this
+ * module adds no fourth. What it adds is a single answer to a question that was previously spread
+ * across the commands that happened to ask it: `wireguard` knew HAProxy is hub-only, `event` knew
+ * the dispatcher is control-only, and the sync steps knew cron publication is control-only, but
+ * nothing stated the boundary those three agree on.
+ *
+ * The distinction the table exists to hold is between a Kubernetes **node** and a Kubernetes
+ * **administrator**. A worker runs the kubelet and joins the cluster; that is node runtime, and it
+ * is not permission to administer the cluster it belongs to. Being managed by the host domain is
+ * not permission either — `underpost host` is node-level operational configuration, and every role
+ * has it.
+ *
+ * @module src/server/network/node-capability.js
+ * @namespace NodeCapability
+ */
+
+/**
+ * @constant NODE_CAPABILITIES
+ * @description Capabilities held by each role, derived from the operations the repository
+ * actually gates: HAProxy and the forward proxy refuse to configure themselves off the hub, the
+ * dispatcher refuses to install off a control node, and the sync sequence publishes CronJobs from
+ * the control node alone.
+ * @memberof NodeCapability
+ */
+const NODE_CAPABILITIES = Object.freeze({
+  hub: Object.freeze([
+    'host-configuration',
+    'wireguard-hub',
+    'haproxy',
+    'forward-proxy',
+    'edge-routing',
+    'node-metrics',
+  ]),
+  control: Object.freeze([
+    'host-configuration',
+    'wireguard-spoke',
+    'kubernetes-node',
+    'kubernetes-administration',
+    'cluster-secret-administration',
+    'cron-publication',
+    'event-service',
+    'node-metrics',
+  ]),
+  worker: Object.freeze(['host-configuration', 'wireguard-spoke', 'kubernetes-node', 'node-metrics']),
+});
+
+/** The roles the topology defines. Ordered hub-first, as every fleet listing is. */
+const NODE_ROLES = Object.freeze(Object.keys(NODE_CAPABILITIES));
+
+/**
+ * Capabilities that reach the Kubernetes API with cluster-wide authority.
+ *
+ * Named apart from the rest because they are the ones a role must never acquire by side effect:
+ * possessing `kubectl`, joining the cluster, or carrying the host environment are each a reason
+ * someone might assume these follow, and none of them is.
+ * @memberof NodeCapability
+ */
+const CLUSTER_ADMIN_CAPABILITIES = Object.freeze([
+  'kubernetes-administration',
+  'cluster-secret-administration',
+  'cron-publication',
+]);
+
+/**
+ * Whether a role holds a capability.
+ * @param {string} role - `hub`, `control` or `worker`.
+ * @param {string} capability - Capability name.
+ * @returns {boolean} True when the role holds it.
+ * @memberof NodeCapability
+ */
+const roleHasCapability = (role, capability) => (NODE_CAPABILITIES[role] || []).includes(capability);
+
+/**
+ * Refuses an operation the role does not hold the capability for.
+ *
+ * Fail-closed on an unknown role as well as an unheld capability: a node whose document names a
+ * role this table does not define has no capabilities, rather than the union of the ones it might
+ * have meant.
+ * @param {object} params - Assertion context.
+ * @param {string} params.role - Role of the node the operation would run on.
+ * @param {string} params.capability - Capability the operation requires.
+ * @param {string} params.operation - Operation being attempted, named in the refusal.
+ * @throws {Error} When the role does not hold the capability.
+ * @memberof NodeCapability
+ */
+const assertRoleCapability = ({ role, capability, operation }) => {
+  if (roleHasCapability(role, capability)) return;
+  const held = NODE_CAPABILITIES[role];
+  throw new Error(
+    `[capability] ${operation} requires '${capability}', which the '${role || '(unset)'}' role does not hold; ` +
+      (held ? `it holds ${held.join(', ')}` : `known roles are ${NODE_ROLES.join(', ')}`),
+  );
+};
+
+export { CLUSTER_ADMIN_CAPABILITIES, NODE_CAPABILITIES, NODE_ROLES, assertRoleCapability, roleHasCapability };

package/src/server/{peer.js → network/peer.js}

@@ -3,14 +3,14 @@
  * Initializes and configures the PeerJS server instance, typically running
  * alongside a main Node.js application.
  *
- * @module src/server/peer.js
+ * @module src/server/network/peer.js
  * @namespace Peer
  */
 
 import { PeerServer } from 'peer';
 import dotenv from 'dotenv';
-import { loggerFactory } from './logger.js';
-import Underpost from '../index.js';
+import { loggerFactory } from '../ops/logger.js';
+import Underpost from '../../index.js';
 
 /**
  * Logger instance for this module, utilizing the framework's factory.

package/src/server/{proxy.js → network/proxy.js}

@@ -1,26 +1,20 @@
 /**
  * Manages the creation and configuration of the reverse proxy server,
  * including handling HTTP/HTTPS listeners and routing based on host configuration.
- * @module src/server/proxy.js
+ * @module src/server/network/proxy.js
  * @namespace ProxyService
  */
 'use strict';
 
 import express from 'express';
 import { createProxyMiddleware } from 'http-proxy-middleware';
-import { loggerFactory, loggerMiddleware } from './logger.js';
-import {
-  buildPortProxyRouter,
-  buildProxyRouter,
-  etcHostFactory,
-  getTlsHosts,
-  isDevProxyContext,
-  isTlsDevProxy,
-} from './conf.js';
-
-import { shellExec } from './process.js';
+import { loggerFactory, loggerMiddleware } from '../ops/logger.js';
+import { etcHostFactory, getTlsHosts, isDevProxyContext, isTlsDevProxy } from '../runtime/conf.js';
+import { buildPortProxyRouter, buildProxyRouter } from './router.js';
+
+import { shellExec } from '../runtime/process.js';
 import fs from 'fs-extra';
-import Underpost from '../index.js';
+import Underpost from '../../index.js';
 
 const logger = loggerFactory(import.meta);