@underpostnet/cyberia 3.3.0 → 3.3.76

package/src/server/storage/zip.js

@@ -0,0 +1,153 @@
+/**
+ * ZIP archive helpers built on JSZip, shared by the file-storage CLI and the client builder.
+ * @module src/server/storage/zip.js
+ * @namespace Zip
+ */
+
+import JSZip from 'jszip';
+import * as dir from 'path';
+import fs from 'fs-extra';
+
+const ZIP_LOCAL_FILE_HEADER = Buffer.from([0x50, 0x4b, 0x03, 0x04]);
+
+/**
+ * Reports whether a buffer starts with the ZIP local file header signature.
+ * @function isZipBuffer
+ * @param {Buffer} buffer - Candidate archive bytes.
+ * @returns {boolean} True when the buffer looks like a ZIP archive.
+ * @memberof Zip
+ */
+const isZipBuffer = (buffer) => Buffer.isBuffer(buffer) && buffer.subarray(0, 4).equals(ZIP_LOCAL_FILE_HEADER);
+
+/**
+ * Loads a ZIP archive from a buffer or a local path.
+ * @function loadZip
+ * @param {Buffer|string} source - Archive bytes or a path to the archive.
+ * @returns {Promise<JSZip>} The loaded archive.
+ * @memberof Zip
+ */
+const loadZip = async (source) => JSZip.loadAsync(Buffer.isBuffer(source) ? source : fs.readFileSync(source));
+
+/**
+ * Resolves an archive entry by exact name, then by trailing path segment, then by
+ * falling back to the only entry of a single-file archive.
+ * @function findZipEntry
+ * @param {JSZip} zip - The loaded archive.
+ * @param {string} entryName - Entry name or basename to look up.
+ * @returns {object|null} The matching JSZip entry, or null when nothing matches.
+ * @memberof Zip
+ */
+const findZipEntry = (zip, entryName) => {
+  const files = Object.values(zip.files).filter((entry) => !entry.dir);
+  return (
+    files.find((entry) => entry.name === entryName) ??
+    files.find((entry) => entry.name.endsWith(`/${entryName}`)) ??
+    (files.length === 1 ? files[0] : null)
+  );
+};
+
+/**
+ * Reads a single entry out of an archive.
+ * @function readZipEntry
+ * @param {Buffer|string} source - Archive bytes or a path to the archive.
+ * @param {string} entryName - Entry name or basename to read.
+ * @returns {Promise<Buffer|null>} The entry contents, or null when the entry is absent.
+ * @memberof Zip
+ */
+const readZipEntry = async (source, entryName) => {
+  const entry = findZipEntry(await loadZip(source), entryName);
+  return entry ? await entry.async('nodebuffer') : null;
+};
+
+/**
+ * Builds an archive buffer from local files.
+ * @function zipFromLocalFiles
+ * @param {Array<{localPath: string, entryName: string}>} entries - Files to archive.
+ * @returns {Promise<Buffer>} The generated archive bytes.
+ * @memberof Zip
+ */
+const zipFromLocalFiles = async (entries) => {
+  const zip = new JSZip();
+  for (const { localPath, entryName } of entries) {
+    const stats = fs.statSync(localPath);
+    zip.file(entryName, fs.readFileSync(localPath), {
+      date: stats.mtime,
+      unixPermissions: stats.mode & 0o777,
+    });
+  }
+  return await zip.generateAsync({
+    type: 'nodebuffer',
+    platform: 'UNIX',
+    compression: 'DEFLATE',
+    compressionOptions: { level: 6 },
+  });
+};
+
+/**
+ * Resolves an entry name against an output directory, rejecting archive paths that
+ * escape it (zip slip).
+ * @function resolveEntryTarget
+ * @param {string} outputPath - Extraction root.
+ * @param {string} entryName - Entry name from the archive.
+ * @returns {string} The absolute target path.
+ * @throws {Error} When the entry resolves outside the extraction root.
+ * @memberof Zip
+ */
+const resolveEntryTarget = (outputPath, entryName) => {
+  const root = dir.resolve(outputPath);
+  const target = dir.resolve(root, entryName);
+  if (target !== root && !target.startsWith(root + dir.sep)) {
+    throw new Error(`Blocked zip entry outside extraction directory: ${entryName}`);
+  }
+  return target;
+};
+
+/**
+ * Extracts every entry of an archive into a directory.
+ * @function extractZipTo
+ * @param {Buffer|string} source - Archive bytes or a path to the archive.
+ * @param {string} outputPath - Extraction root; created when missing.
+ * @returns {Promise<string[]>} The written file paths.
+ * @memberof Zip
+ */
+const extractZipTo = async (source, outputPath) => {
+  const zip = await loadZip(source);
+  fs.mkdirSync(outputPath, { recursive: true });
+
+  const writtenPaths = [];
+  for (const entry of Object.values(zip.files)) {
+    const target = resolveEntryTarget(outputPath, entry.name);
+    if (entry.dir) {
+      fs.mkdirSync(target, { recursive: true });
+      continue;
+    }
+    fs.mkdirSync(dir.dirname(target), { recursive: true });
+    fs.writeFileSync(target, await entry.async('nodebuffer'));
+    if (entry.unixPermissions) fs.chmodSync(target, entry.unixPermissions & 0o777);
+    writtenPaths.push(target);
+  }
+  return writtenPaths;
+};
+
+/**
+ * Extracts a single archive entry into a directory, flattening its archive path.
+ * @function extractZipEntryTo
+ * @param {Buffer|string} source - Archive bytes or a path to the archive.
+ * @param {string} entryName - Entry name or basename to extract.
+ * @param {string} targetDir - Destination directory; created when missing.
+ * @returns {Promise<string>} The written file path.
+ * @throws {Error} When the entry is not present in the archive.
+ * @memberof Zip
+ */
+const extractZipEntryTo = async (source, entryName, targetDir) => {
+  const entry = findZipEntry(await loadZip(source), entryName);
+  if (!entry) throw new Error(`Zip entry not found: ${entryName}`);
+
+  const target = resolveEntryTarget(targetDir, dir.basename(entryName));
+  fs.mkdirSync(dir.dirname(target), { recursive: true });
+  fs.writeFileSync(target, await entry.async('nodebuffer'));
+  if (entry.unixPermissions) fs.chmodSync(target, entry.unixPermissions & 0o777);
+  return target;
+};
+
+export { isZipBuffer, loadZip, findZipEntry, readZipEntry, zipFromLocalFiles, extractZipTo, extractZipEntryTo };

package/src/server.js

@@ -1,14 +1,11 @@
 'use strict';
 
-// https://nodejs.org/api
-// https://expressjs.com/en/4x/api.html
-
 import dotenv from 'dotenv';
-import { loggerFactory } from './server/logger.js';
+import { loggerFactory } from './server/ops/logger.js';
 import { buildClient } from './client-builder/client-build.js';
-import { buildRuntime } from './server/runtime.js';
-import { ProcessController } from './server/process.js';
-import { Config } from './server/conf.js';
+import { buildRuntime } from './server/runtime/runtime.js';
+import { ProcessController } from './server/runtime/process.js';
+import { Config } from './server/runtime/conf.js';
 
 dotenv.config();
 

package/src/ws/IoInterface.js

@@ -4,7 +4,7 @@
  * @namespace SocketIoInterface
  */
 
-import { loggerFactory } from '../server/logger.js';
+import { loggerFactory } from '../server/ops/logger.js';
 import { Socket } from 'socket.io';
 
 const logger = loggerFactory(import.meta);

package/src/ws/IoServer.js

@@ -6,7 +6,7 @@
 'use strict';
 
 import { Server } from 'socket.io';
-import { loggerFactory } from '../server/logger.js';
+import { loggerFactory } from '../server/ops/logger.js';
 import Underpost from '../index.js';
 
 const logger = loggerFactory(import.meta);

package/src/ws/core/core.ws.connection.js

@@ -3,7 +3,7 @@
  * @module ws/core/core.ws.connection
  */
 
-import { loggerFactory } from '../../server/logger.js';
+import { loggerFactory } from '../../server/ops/logger.js';
 import { CoreWsChatChannel } from './channels/core.ws.chat.js';
 import { CoreWsMailerChannel } from './channels/core.ws.mailer.js';
 import { CoreWsStreamChannel } from './channels/core.ws.stream.js';

package/src/ws/core/core.ws.emit.js

@@ -3,7 +3,7 @@
  * @module ws/core/core.ws.emit
  */
 
-import { loggerFactory } from '../../server/logger.js';
+import { loggerFactory } from '../../server/ops/logger.js';
 
 const logger = loggerFactory(import.meta);
 

package/src/ws/core/core.ws.server.js

@@ -10,7 +10,7 @@ import { CoreWsConnectionHandler } from './core.ws.connection.js';
 import { CoreWsChatChannel } from './channels/core.ws.chat.js';
 import { CoreWsMailerChannel } from './channels/core.ws.mailer.js';
 import { CoreWsStreamChannel } from './channels/core.ws.stream.js';
-import { resolveHostKeyContext } from '../../server/conf.js';
+import { resolveHostKeyContext } from '../../server/runtime/conf.js';
 
 /**
  * @class CoreWsServer

package/src/ws/default/default.ws.connection.js

@@ -3,7 +3,7 @@
  * @module ws/default/default.ws.connection
  */
 
-import { loggerFactory } from '../../server/logger.js';
+import { loggerFactory } from '../../server/ops/logger.js';
 import { DefaultWsMainChannel } from './channels/default.ws.main.js';
 
 const logger = loggerFactory(import.meta);

package/src/ws/default/default.ws.emit.js

@@ -1,4 +1,4 @@
-import { loggerFactory } from '../../server/logger.js';
+import { loggerFactory } from '../../server/ops/logger.js';
 
 const logger = loggerFactory(import.meta);
 

package/src/ws/default/default.ws.server.js

@@ -8,7 +8,7 @@
 import { IoServer } from '../IoServer.js';
 import { DefaultWsConnectionHandler } from './default.ws.connection.js';
 import { DefaultWsMainChannel } from './channels/default.ws.main.js';
-import { resolveHostKeyContext } from '../../server/conf.js';
+import { resolveHostKeyContext } from '../../server/runtime/conf.js';
 
 /**
  * @class DefaultWsServer

package/test/e2e/event-e2e-public-ingress-down.js

@@ -0,0 +1,45 @@
+import Underpost from '../../src/index.js';
+
+/** The ports HAProxy publishes on the hub; blocking these takes every host down. */
+const EDGE_PORTS = '80,443';
+
+/**
+ * End-to-end rehearsal for `public-ingress-down`.
+ *
+ * The outage is induced where the public edge actually terminates — the hub —
+ * by blocking inbound traffic on the published ports. That is the one fault
+ * that takes every host down at once, which is the condition this event
+ * remediates; stopping a workload would produce the partial state the handler
+ * deliberately refuses to act on.
+ *
+ * The block is scoped to those ports rather than to every port, because
+ * remediation reaches the hub over SSH: a total ingress block would drop the
+ * connection that repairs it and leave the edge unrecoverable from anywhere but
+ * the provider console. `--unblock-all-ingress`, which the handler runs, clears
+ * this block along with any other.
+ *
+ * @module test/event-e2e-public-ingress-down.js
+ */
+export default {
+  description: 'Blocks public ingress on each hub, then verifies the edge is restored and every host answers again.',
+
+  async subjects({ options }) {
+    return Underpost.event.subjectSelection('hub', options).map((hubHost) => {
+      const target = Underpost.event.hubTarget(hubHost);
+      return {
+        label: `ingress via ${target.nodeName || hubHost}`,
+        probes: Underpost.event.publicIngressUrls().map((entry) => ({ module: 'http_2xx', target: entry.url })),
+        dispatchOptions: { nodes: target.nodeName || hubHost },
+        remote: { user: target.user, host: target.host },
+      };
+    });
+  },
+
+  async break(context, subject) {
+    return await Underpost.event.runCommand(`node bin ip --block-ingress-port ${EDGE_PORTS}`, subject.remote);
+  },
+
+  async restore(context, subject) {
+    return await Underpost.event.runCommand(`node bin ip --unblock-ingress-port ${EDGE_PORTS}`, subject.remote);
+  },
+};

package/test/e2e/event-e2e-wireguard-server-down.js

@@ -0,0 +1,38 @@
+import Underpost from '../../src/index.js';
+
+/**
+ * End-to-end rehearsal for `wireguard-server-down`.
+ *
+ * Every registered hub is rehearsed, or those `--nodes` selects. A hub is
+ * taken down the only way an operator can reach it while its tunnel is dead —
+ * through the external SSH endpoint registered for it — which is also the path
+ * the remediation must use. Stopping the interface any other way would not
+ * exercise that dependency.
+ *
+ * @module test/event-e2e-wireguard-server-down.js
+ */
+export default {
+  description: 'Stops WireGuard on each hub over its registered management SSH, then verifies the repair.',
+
+  async subjects({ options }) {
+    return Underpost.event.subjectSelection('hub', options).map((hubHost) => {
+      const target = Underpost.event.hubTarget(hubHost);
+      if (!target.address)
+        throw new Error(`[event] the tunnel address of hub ${hubHost} is underivable; nothing can be probed`);
+      return {
+        label: `hub ${target.nodeName || hubHost}`,
+        probes: [{ module: 'icmp', target: target.address }],
+        dispatchOptions: { nodes: target.nodeName || hubHost },
+        remote: { user: target.user, host: target.host },
+      };
+    });
+  },
+
+  async break(context, subject) {
+    return await Underpost.event.runCommand('node bin wireguard --wireguard-stop', subject.remote);
+  },
+
+  async restore(context, subject) {
+    return await Underpost.event.runCommand('node bin wireguard --wireguard-start', subject.remote);
+  },
+};

package/test/e2e/event-e2e-wireguard-spoke-down.js

@@ -0,0 +1,40 @@
+import Underpost from '../../src/index.js';
+
+/**
+ * End-to-end rehearsal for `wireguard-spoke-down`.
+ *
+ * Every peer of this node's hub is rehearsed, or those `--nodes` /
+ * `--spoke` selects, one at a time. Each is taken down through the same
+ * identity chain the remediation resolves — locally for the selected control
+ * node, over LAN SSH for a worker — so a spoke that can be broken but not
+ * repaired fails the rehearsal rather than an outage.
+ *
+ * @module test/event-e2e-wireguard-spoke-down.js
+ */
+export default {
+  description: 'Stops WireGuard on each registered spoke, then verifies the repair of that spoke alone.',
+
+  async subjects({ options }) {
+    const hubAddress = Underpost.event.hubAddress();
+    return Underpost.event.subjectSelection('spoke', options).map((spokeId) => {
+      const spoke = Underpost.event.spokes().find((entry) => entry.id === spokeId);
+      const target = Underpost.event.spokeTarget(spokeId);
+      return {
+        label: `spoke ${spokeId}`,
+        // The local spoke is proved through the hub tunnel: its own 10.0.0.x stays
+        // reachable on the machine itself even when the tunnel carries nothing.
+        probes: [{ module: 'icmp', target: spoke.local ? hubAddress : spoke.address }],
+        dispatchOptions: { spoke: spokeId },
+        remote: { user: target.user, host: target.host },
+      };
+    });
+  },
+
+  async break(context, subject) {
+    return await Underpost.event.runCommand('node bin wireguard --wireguard-stop', subject.remote);
+  },
+
+  async restore(context, subject) {
+    return await Underpost.event.runCommand('node bin wireguard --wireguard-start', subject.remote);
+  },
+};

package/test/{api.test.js → integration/app/api.test.js}

@@ -1,29 +1,48 @@
 'use strict';
 
 import axios from 'axios';
-import dotenv from 'dotenv';
+import express from 'express';
 
 import { expect } from 'chai';
-import { loggerFactory } from '../src/server/logger.js';
-
-dotenv.config();
-
-const PORT = parseInt(process.env.PORT) + 1;
+import { TestRouter } from '../../../src/api/test/test.router.js';
+import { loggerFactory } from '../../../src/server/ops/logger.js';
 
 const logger = loggerFactory(import.meta);
 
 await logger.setUpInfo();
 
-const BASE_URL =
-  process.env.NODE_ENV === 'development'
-    ? `http://localhost:${PORT}/${process.env.BASE_API}`
-    : `https://www.nexodev.org/api`;
-
 describe(`GET 'Test' API Request `, async () => {
+  const app = express();
+  app.use('/api/test', TestRouter.router({ authMiddleware: (_req, _res, next) => next() }));
+
+  let server;
+  let baseUrl;
+
+  beforeAll(
+    () =>
+      new Promise((resolve, reject) => {
+        server = app.listen(0, '127.0.0.1', () => {
+          baseUrl = `http://127.0.0.1:${server.address().port}/api`;
+          resolve();
+        });
+        server.on('error', reject);
+      }),
+  );
+
+  afterAll(
+    () =>
+      new Promise((resolve, reject) =>
+        server.close((error) => {
+          if (error) reject(error);
+          else resolve();
+        }),
+      ),
+  );
+
   {
     const youtubeId = '2aib-pmgUdQ';
-    const url = `${BASE_URL}/test/youtube-id/?url=https://www.youtube.com/watch?v=${youtubeId}`;
     it(`youtube id from raw youtube url`, async () => {
+      const url = `${baseUrl}/test/youtube-id/?url=https://www.youtube.com/watch?v=${youtubeId}`;
       logger.info('request info', { url });
       const res = await axios.get(url);
       logger.info('response', res.data);
@@ -32,8 +51,8 @@ describe(`GET 'Test' API Request `, async () => {
   }
   {
     const email = 'test@gmail.com';
-    const url = `${BASE_URL}/test/verify-email/?email=${email}`;
     it(`valid format email`, async () => {
+      const url = `${baseUrl}/test/verify-email/?email=${email}`;
       logger.info('request info', { url });
       const res = await axios.get(url);
       logger.info('response', res.data);
@@ -42,8 +61,8 @@ describe(`GET 'Test' API Request `, async () => {
   }
   {
     const password = 'Password123!';
-    const url = `${BASE_URL}/test/is-strong-password/?password=${password}`;
     it(`valid password`, async () => {
+      const url = `${baseUrl}/test/is-strong-password/?password=${password}`;
       logger.info('request info', { url });
       const res = await axios.get(url);
       logger.info('response', res.data);