@underpostnet/cyberia 3.2.90 → 3.3.73

package/src/cli/ssh.js

@@ -5,14 +5,146 @@
  */
 
 import { generateRandomPasswordSelection } from '../client/components/core/CommonJs.js';
-import { pbcopy, shellExec } from '../server/process.js';
-import { loggerFactory } from '../server/logger.js';
-import { waitForPort } from '../server/conf.js';
+import { shellExec } from '../server/runtime/process.js';
+import { loggerFactory, redactSensitiveText } from '../server/ops/logger.js';
+import { waitForPort } from '../server/runtime/conf.js';
+import {
+  runSELinuxCommands,
+  selinuxPackagesCommandFactory,
+  selinuxRestoreconCommandFactory,
+  selinuxSshContextCommandsFactory,
+  selinuxSshPortCommandsFactory,
+  shellArgumentFactory,
+} from '../server/security/selinux.js';
+import ContainerStorageService from '../server/security/container-storage.js';
 import fs from 'fs-extra';
 import Underpost from '../index.js';
 
 const logger = loggerFactory(import.meta);
 
+const shellExecRedacted = (command, options = {}) => {
+  const silent = options.silent === true;
+  try {
+    const result = shellExec(command, { ...options, silent: true });
+    if (!silent) {
+      if (result.stdout) process.stdout.write(redactSensitiveText(result.stdout));
+      if (result.stderr) process.stderr.write(redactSensitiveText(result.stderr));
+    }
+    return result.stdout;
+  } catch (error) {
+    error.stdout = redactSensitiveText(error.stdout || '');
+    error.stderr = redactSensitiveText(error.stderr || '');
+    error.message = redactSensitiveText(error.message || error);
+    if (!silent) {
+      if (error.stdout) process.stdout.write(error.stdout);
+      if (error.stderr) process.stderr.write(error.stderr);
+    }
+    throw error;
+  }
+};
+
+/**
+ * SSH users are cluster scoped: one registry and one key store serve every
+ * deploy id running on the cluster, so an account is provisioned once instead
+ * of once per app.
+ *
+ * A record is `{ user, password, groups, keyPath, pubKeyPath, hosts }`, where an
+ * empty password means key-only and `hosts` carries one connection per host:
+ *
+ *   hosts: [{ host: '10.0.0.2', port: 22 }, { host: '10.0.0.3', port: 22 }]
+ *
+ * One account reaches many hosts — the same operator account on every WireGuard
+ * spoke is the normal case — so the host cannot be a field of the record. It was,
+ * and registering that account for a second host silently replaced the first,
+ * leaving remediation unable to resolve a spoke it had just been given.
+ *
+ * The port belongs to the connection for the same reason: two hosts of one
+ * account can listen on different ports, and a single record-level port could
+ * only describe one of them.
+ */
+const USERS_CONF_PATH = './engine-private/deploy/conf.users.json';
+const USERS_KEYS_PATH = './engine-private/deploy/users';
+const DEFAULT_SSH_PORT = 22;
+/** The checkout's own key, and where a workload receives it instead: a projected Secret volume. */
+const HOST_KEY_PATH = './engine-private/deploy/id_rsa';
+const SECRET_KEY_PATH = '/etc/underpost/secrets/ssh/id_rsa';
+
+/**
+ * The private key this process authenticates with.
+ *
+ * One resolver for every SSH caller, because the answer differs by where the process runs and
+ * nothing else should have to know that. A pod has the key as a projected Secret and no checkout
+ * to read it from; the host CLI has the checkout and no mount. The mount is preferred over the
+ * checkout default but never over a caller's own path, because on a host the key is per target —
+ * the hub answers to a different one than the LAN nodes — and only the caller knows which.
+ * @param {string} [keyPath] - Explicit path, which always wins.
+ * @returns {string} Path to the private key.
+ * @memberof UnderpostSSH
+ */
+const sshKeyPathFactory = (keyPath = '') =>
+  `${keyPath || ''}`.trim() || (fs.existsSync(SECRET_KEY_PATH) ? SECRET_KEY_PATH : '') || HOST_KEY_PATH;
+
+/**
+ * @method hostNameFactory
+ * @description A host as the registry compares it: the bare address, so a value
+ * written with a prefix (`10.0.0.2/32`) matches one without.
+ * @param {string} host - Host or IP, with or without a CIDR suffix.
+ * @returns {string} Normalized host.
+ * @memberof UnderpostSSH
+ */
+const hostNameFactory = (host) => `${host || ''}`.trim().split('/')[0];
+
+/**
+ * @method connectionFactory
+ * @description Normalizes one connection entry.
+ * @param {object} [connection] - Raw connection entry.
+ * @returns {?{host: string, port: number}} Normalized connection, or null without a host.
+ * @memberof UnderpostSSH
+ */
+const connectionFactory = (connection = {}) => {
+  const host = hostNameFactory(connection.host);
+  return host ? { host, port: Number(connection.port) || DEFAULT_SSH_PORT } : null;
+};
+
+/**
+ * @method upsertConnection
+ * @description Adds a connection to a host list, replacing the entry for that
+ * host when one is already present.
+ *
+ * The one write path for `hosts`, so re-registering an account for a host it
+ * already reaches updates that connection instead of appending a duplicate the
+ * reverse lookup would then have to choose between.
+ * @param {Array<{host: string, port: number}>} [hosts] - Existing connections.
+ * @param {object} connection - Connection to add.
+ * @returns {Array<{host: string, port: number}>} Updated connections.
+ * @memberof UnderpostSSH
+ */
+const upsertConnection = (hosts = [], connection) => {
+  const entry = connectionFactory(connection);
+  if (!entry) return hosts;
+  return [...hosts.filter((existing) => existing.host !== entry.host), entry];
+};
+
+/**
+ * @method userRecordFactory
+ * @description Normalizes one registry entry, so every consumer reads one shape
+ * whether the file was written by hand, partially, or not at all.
+ * @param {object} [entry] - Raw registry entry.
+ * @returns {object} Normalized record.
+ * @memberof UnderpostSSH
+ */
+const userRecordFactory = (entry = {}) => ({
+  user: `${entry.user || ''}`.trim(),
+  password: `${entry.password ?? ''}`,
+  groups: `${entry.groups || ''}`,
+  keyPath: `${entry.keyPath || ''}`,
+  pubKeyPath: `${entry.pubKeyPath || ''}`,
+  hosts: (Array.isArray(entry.hosts) ? entry.hosts : []).reduce(
+    (hosts, connection) => upsertConnection(hosts, connection),
+    [],
+  ),
+});
+
 /**
  * @class UnderpostSSH
  * @description Manages SSH key generation and connection setup.
@@ -21,33 +153,103 @@ const logger = loggerFactory(import.meta);
 class UnderpostSSH {
   static API = {
     /**
-     * Loads configuration node from disk or returns default empty config.
+     * Path of the cluster users registry.
      * @method
-     * @function loadConfigNode
+     * @function usersConfPath
      * @memberof UnderpostSSH
-     * @param {string} deployId - Deployment ID for the config path
-     * @returns {{confNode: Object, confNodePath: string}} Configuration node and its file path
-     * @description Loads or creates a config node with users object structure
+     * @returns {string} Path to the users configuration file
      */
-    loadConfigNode: (deployId) => {
-      const confNodePath = `./engine-private/conf/${deployId}/conf.node.json`;
-      const confNode = fs.existsSync(confNodePath) ? JSON.parse(fs.readFileSync(confNodePath, 'utf8')) : { users: {} };
-      return { confNode, confNodePath };
-    },
+    usersConfPath: () => USERS_CONF_PATH,
+
+    /**
+     * Key store directory for a user.
+     * @method
+     * @function userKeyDir
+     * @memberof UnderpostSSH
+     * @param {string} user - SSH user name
+     * @returns {string} Directory holding `<dir>/id_rsa` and `<dir>/id_rsa.pub`
+     */
+    userKeyDir: (user) => `${USERS_KEYS_PATH}/${user}`,
+
+    /**
+     * Loads the cluster users registry from disk.
+     * @method
+     * @function loadUsers
+     * @memberof UnderpostSSH
+     * @returns {Array<Object>} Registered user records, empty when unregistered
+     */
+    loadUsers: () =>
+      (fs.existsSync(USERS_CONF_PATH) ? JSON.parse(fs.readFileSync(USERS_CONF_PATH, 'utf8')) : [])
+        .map(userRecordFactory)
+        .filter((entry) => entry.user),
 
     /**
-     * Saves configuration node to disk.
+     * Saves the cluster users registry to disk.
      * @method
-     * @function saveConfigNode
+     * @function saveUsers
      * @memberof UnderpostSSH
-     * @param {string} confNodePath - Path to the configuration file
-     * @param {Object} confNode - Configuration object to save
+     * @param {Array<Object>} users - User records to persist
      * @returns {void}
      */
-    saveConfigNode: (confNodePath, confNode) => {
-      fs.outputFileSync(confNodePath, JSON.stringify(confNode, null, 4), 'utf8');
+    saveUsers: (users) => {
+      fs.outputFileSync(USERS_CONF_PATH, JSON.stringify(users.map(userRecordFactory), null, 2), 'utf8');
+    },
+
+    /**
+     * Looks up a registered user record.
+     * @method
+     * @function findUser
+     * @memberof UnderpostSSH
+     * @param {string} user - SSH user name
+     * @returns {Object|undefined} The record, or undefined when unregistered
+     */
+    findUser: (user) => Underpost.ssh.loadUsers().find((entry) => entry.user === user),
+
+    /**
+     * Resolves the connection an account uses to reach one host.
+     * @method
+     * @function resolveConnection
+     * @memberof UnderpostSSH
+     * @param {object} params
+     * @param {string} params.host - Host or IP the account was registered against.
+     * @param {string} [params.user] - Restrict the lookup to this account.
+     * @returns {Object|undefined} Flat connection `{ user, host, port, password, keyPath, pubKeyPath }`, or undefined
+     * @description
+     * The reverse of {@link UnderpostSSH.findUser}, for callers that know where
+     * they must act but not who acts there — remediation resolving a WireGuard
+     * spoke's tunnel address to the account that can repair it. Returns the flat
+     * view every SSH caller needs, so no consumer has to know the registry is
+     * keyed by host.
+     */
+    resolveConnection: ({ host, user = '' } = {}) => {
+      const target = hostNameFactory(host);
+      if (!target) return undefined;
+      for (const record of Underpost.ssh.loadUsers()) {
+        if (user && record.user !== user) continue;
+        const connection = record.hosts.find((entry) => entry.host === target);
+        if (!connection) continue;
+        return {
+          user: record.user,
+          host: connection.host,
+          port: connection.port,
+          password: record.password,
+          keyPath: record.keyPath,
+          pubKeyPath: record.pubKeyPath,
+        };
+      }
+      return undefined;
     },
 
+    /**
+     * Lists every host an account is registered for.
+     * @method
+     * @function userHosts
+     * @memberof UnderpostSSH
+     * @param {string} user - SSH user name
+     * @returns {Array<{host: string, port: number}>} Connection metadata per host
+     */
+    userHosts: (user) => Underpost.ssh.findUser(user)?.hosts || [],
+
     /**
      * Checks if a system user exists.
      * @method
@@ -57,7 +259,7 @@ class UnderpostSSH {
      * @returns {boolean} True if user exists, false otherwise
      */
     checkUserExists: (username) => {
-      const result = shellExec(`id -u ${username} 2>/dev/null || echo "not_found"`, {
+      const result = shellExec(`id -u ${shellArgumentFactory(username)} 2>/dev/null || echo "not_found"`, {
         silent: true,
         stdout: true,
       }).trim();
@@ -73,7 +275,7 @@ class UnderpostSSH {
      * @returns {string} User's home directory path
      */
     getUserHome: (username) => {
-      return shellExec(`getent passwd ${username} | cut -d: -f6`, {
+      return shellExec(`getent passwd ${shellArgumentFactory(username)} | cut -d: -f6`, {
         silent: true,
         stdout: true,
       }).trim();
@@ -90,11 +292,13 @@ class UnderpostSSH {
      * @returns {void}
      */
     createSystemUser: (username, password, groups) => {
-      shellExec(`useradd -m -s /bin/bash ${username}`);
-      shellExec(`echo "${username}:${password}" | chpasswd`);
+      if (!/^[a-z_][a-z0-9_-]*[$]?$/i.test(username)) throw new TypeError('Invalid system username');
+      shellExec(`useradd -m -s /bin/bash ${shellArgumentFactory(username)}`);
+      shellExec(`printf '%s\n' ${shellArgumentFactory(`${username}:${password}`)} | chpasswd`, { disableLog: true });
       if (groups) {
         for (const group of groups.split(',').map((g) => g.trim())) {
-          shellExec(`usermod -aG "${group}" "${username}"`);
+          if (!/^[a-z_][a-z0-9_-]*[$]?$/i.test(group)) throw new TypeError('Invalid system group');
+          shellExec(`usermod -aG ${shellArgumentFactory(group)} ${shellArgumentFactory(username)}`);
         }
       }
     },
@@ -109,8 +313,8 @@ class UnderpostSSH {
      */
     ensureSSHDirectory: (sshDir) => {
       if (!fs.existsSync(sshDir)) {
-        shellExec(`mkdir -p ${sshDir}`);
-        shellExec(`chmod 700 ${sshDir}`);
+        shellExec(`mkdir -p ${shellArgumentFactory(sshDir)}`);
+        shellExec(`chmod 700 ${shellArgumentFactory(sshDir)}`);
       }
     },
 
@@ -126,11 +330,12 @@ class UnderpostSSH {
      * @returns {void}
      */
     setSSHFilePermissions: (sshDir, username, keyPath, pubKeyPath) => {
-      shellExec(`chmod 600 ${sshDir}/authorized_keys`);
-      shellExec(`chmod 644 ${sshDir}/known_hosts`);
-      if (keyPath) shellExec(`chmod 600 ${keyPath}`);
-      if (pubKeyPath) shellExec(`chmod 644 ${pubKeyPath}`);
-      shellExec(`chown -R ${username}:${username} ${sshDir}`);
+      shellExec(`chmod 600 ${shellArgumentFactory(`${sshDir}/authorized_keys`)}`);
+      shellExec(`chmod 644 ${shellArgumentFactory(`${sshDir}/known_hosts`)}`);
+      if (keyPath) shellExec(`chmod 600 ${shellArgumentFactory(keyPath)}`);
+      if (pubKeyPath) shellExec(`chmod 644 ${shellArgumentFactory(pubKeyPath)}`);
+      shellExec(`chown -R ${shellArgumentFactory(`${username}:${username}`)} ${shellArgumentFactory(sshDir)}`);
+      runSELinuxCommands(selinuxSshContextCommandsFactory({ sshDirectory: sshDir }), { execute: shellExec });
     },
 
     /**
@@ -140,17 +345,16 @@ class UnderpostSSH {
      * @memberof UnderpostSSH
      * @param {string} sshDir - SSH directory path
      * @param {string} pubKeyPath - Public key file path
-     * @param {boolean} disablePassword - Whether to add no-forwarding restrictions
+     * @param {boolean} restrictForwarding - Whether to add no-forwarding restrictions
      * @returns {void}
      */
-    configureAuthorizedKeys: (sshDir, pubKeyPath, disablePassword) => {
-      if (disablePassword) {
-        shellExec(`cat >> ${sshDir}/authorized_keys <<EOF
-no-port-forwarding,no-X11-forwarding,no-agent-forwarding ${fs.readFileSync(pubKeyPath, 'utf8')}
-EOF`);
-      } else {
-        shellExec(`cat ${pubKeyPath} >> ${sshDir}/authorized_keys`);
-      }
+    configureAuthorizedKeys: (sshDir, pubKeyPath, restrictForwarding) => {
+      const key = fs.readFileSync(pubKeyPath, 'utf8').trim();
+      const entry = restrictForwarding ? `no-port-forwarding,no-X11-forwarding,no-agent-forwarding ${key}` : key;
+      const authorizedKeysPath = `${sshDir}/authorized_keys`;
+      shellExec(
+        `grep -qxF ${shellArgumentFactory(entry)} ${shellArgumentFactory(authorizedKeysPath)} || printf '%s\n' ${shellArgumentFactory(entry)} >> ${shellArgumentFactory(authorizedKeysPath)}`,
+      );
     },
 
     /**
@@ -164,27 +368,94 @@ EOF`);
      * @returns {void}
      */
     configureKnownHosts: (sshDir, port, host) => {
-      shellExec(`ssh-keyscan -p ${port} -H localhost >> ${sshDir}/known_hosts`);
-      shellExec(`ssh-keyscan -p ${port} -H 127.0.0.1 >> ${sshDir}/known_hosts`);
-      if (host) shellExec(`ssh-keyscan -p ${port} -H ${host} >> ${sshDir}/known_hosts`);
+      const sshPort = Number(port);
+      if (!Number.isInteger(sshPort) || sshPort < 1 || sshPort > 65535)
+        throw new RangeError('SSH port must be 1-65535');
+      const knownHostsPath = shellArgumentFactory(`${sshDir}/known_hosts`);
+      shellExec(`ssh-keyscan -p ${sshPort} -H localhost >> ${knownHostsPath}`);
+      shellExec(`ssh-keyscan -p ${sshPort} -H 127.0.0.1 >> ${knownHostsPath}`);
+      if (host) shellExec(`ssh-keyscan -p ${sshPort} -H ${shellArgumentFactory(host)} >> ${knownHostsPath}`);
     },
 
     /**
-     * Configures sudoers for passwordless sudo or sets user password.
+     * Grants passwordless sudo to a key-only account, or sets the user password.
      * @method
      * @function configureSudoAccess
      * @memberof UnderpostSSH
      * @param {string} username - Username to configure
-     * @param {string} password - User password
-     * @param {boolean} disablePassword - Whether to enable passwordless sudo
+     * @param {string} password - User password; empty means key-only
      * @returns {void}
      */
-    configureSudoAccess: (username, password, disablePassword) => {
-      if (disablePassword) {
-        shellExec(`echo '${username} ALL=(ALL) NOPASSWD: ALL' | sudo tee /etc/sudoers.d/90_${username}`);
+    configureSudoAccess: (username, password) => {
+      if (!password) {
+        if (!/^[a-z_][a-z0-9_-]*[$]?$/i.test(username)) throw new TypeError('Invalid sudo username');
+        const sudoersPath = `/etc/sudoers.d/90_${username}`;
+        const temporaryPath = `/tmp/underpost-sudoers-${process.pid}-${username}`;
+        const rule = `${username} ALL=(ALL) NOPASSWD: ALL`;
+        try {
+          shellExec(`printf '%s\n' ${shellArgumentFactory(rule)} > ${shellArgumentFactory(temporaryPath)}`);
+          shellExec(`sudo visudo -cf ${shellArgumentFactory(temporaryPath)}`);
+          shellExec(
+            `sudo install -m 0440 -o root -g root ${shellArgumentFactory(temporaryPath)} ${shellArgumentFactory(sudoersPath)}`,
+          );
+          runSELinuxCommands([selinuxRestoreconCommandFactory(sudoersPath, { recursive: false })], {
+            execute: shellExec,
+          });
+        } finally {
+          fs.removeSync(temporaryPath);
+        }
       } else {
-        shellExec(`echo "${username}:${password}" | sudo chpasswd`);
+        shellExec(`printf '%s\n' ${shellArgumentFactory(`${username}:${password}`)} | sudo chpasswd`, {
+          disableLog: true,
+        });
+      }
+    },
+
+    /**
+     * Initializes the default SSH files and credentials for a local SSH service.
+     * @method
+     * @function initializeDefaultSshConfig
+     * @memberof UnderpostSSH
+     * @param {object} params - SSH configuration values.
+     * @param {string} params.user - SSH user name.
+     * @param {string} params.password - SSH key passphrase and user password; empty means key-only.
+     * @param {string} params.host - Host used in the SSH key comment.
+     * @param {number} params.port - SSH port.
+     * @param {string} [params.controllerPubKeyPath='./engine-private/deploy/id_rsa.pub'] - Preferred controller public key to authorize.
+     * @returns {void}
+     */
+    initializeDefaultSshConfig: ({
+      user,
+      password,
+      host,
+      port,
+      controllerPubKeyPath = './engine-private/deploy/id_rsa.pub',
+    }) => {
+      const sshDir = `${Underpost.ssh.getUserHome(user)}/.ssh`;
+      const keyPath = `${sshDir}/id_rsa`;
+      const pubKeyPath = `${sshDir}/id_rsa.pub`;
+
+      Underpost.ssh.ensureSSHDirectory(sshDir);
+      fs.ensureFileSync(`${sshDir}/authorized_keys`);
+      fs.ensureFileSync(`${sshDir}/known_hosts`);
+
+      if (!fs.existsSync(keyPath)) {
+        shellExec(
+          `ssh-keygen -t ed25519 -f ${shellArgumentFactory(keyPath)} -N ${shellArgumentFactory(password)} -q -C ${shellArgumentFactory(`${user}@${host}`)}`,
+          { disableLog: true },
+        );
       }
+      if (!fs.existsSync(pubKeyPath))
+        shellExec(
+          `ssh-keygen -y -f ${shellArgumentFactory(keyPath)} -P ${shellArgumentFactory(password)} > ${shellArgumentFactory(pubKeyPath)}`,
+          { disableLog: true },
+        );
+
+      const authorizedKeyPath = fs.existsSync(controllerPubKeyPath) ? controllerPubKeyPath : pubKeyPath;
+      Underpost.ssh.configureAuthorizedKeys(sshDir, authorizedKeyPath, !password);
+      Underpost.ssh.configureKnownHosts(sshDir, port, host);
+      Underpost.ssh.configureSudoAccess(user, password);
+      Underpost.ssh.setSSHFilePermissions(sshDir, user, keyPath, pubKeyPath);
     },
 
     /**
@@ -193,11 +464,10 @@ EOF`);
      * @function callback
      * @memberof UnderpostSSH
      * @param {Object} options - Configuration options for SSH operations
-     * @param {string} [options.deployId=''] - Deployment ID context for SSH operations
      * @param {boolean} [options.generate=false] - Generate new SSH credentials
      * @param {string} [options.user=''] - SSH user name (defaults to 'root')
-     * @param {string} [options.password=''] - SSH user password (auto-generated if not provided, overridden by saved config if user exists)
-     * @param {string} [options.host=''] - SSH host address (defaults to public IP, overridden by saved config if user exists)
+     * @param {string} [options.password=''] - SSH user password (taken from the registry, else generated unless --disable-password)
+     * @param {string} [options.host=''] - SSH host address (taken from the registry, else the public IP)
      * @param {string} [options.filter=''] - Filter for user/group listings
      * @param {string} [options.groups=''] - Comma-separated list of groups for the user (defaults to 'wheel')
      * @param {number} [options.port=22] - SSH port number
@@ -208,24 +478,23 @@ EOF`);
      * @param {boolean} [options.reset=false] - Reset SSH configuration (clear authorized_keys and known_hosts)
      * @param {boolean} [options.keysList=false] - List authorized SSH keys
      * @param {boolean} [options.hostsList=false] - List known SSH hosts
-     * @param {boolean} [options.disablePassword=false] - If true, enable passwordless sudo and add SSH restrictions
+     * @param {boolean} [options.disablePassword=false] - Create the account key-only instead of generating a password
      * @param {boolean} [options.keyTest=false] - Test SSH key generation
      * @param {boolean} [options.stop=false] - Stop SSH service
      * @param {boolean} [options.status=false] - Check SSH service status
-     * @param {boolean} [options.connectUri=false] - Output SSH connection URI
-     * @param {boolean} [options.copy=false] - Copy SSH connection URI to clipboard
      * @returns {Promise<void>}
      * @description
-     * Handles various SSH operations:
+     * Handles SSH operations against the cluster users registry
+     * (`engine-private/deploy/conf.users.json`) and key store
+     * (`engine-private/deploy/users/<user>`):
      * - User creation with automatic key generation and backup
      * - User removal with key cleanup
-     * - Key import/export between SSH directory and private backup location
+     * - Key import/export between SSH directory and the key store
      * - SSH service initialization and hardening
      * - User and group listing with optional filtering
      */
     callback: async (
       options = {
-        deployId: '',
         generate: false,
         user: '',
         password: '',
@@ -244,62 +513,49 @@ EOF`);
         keyTest: false,
         stop: false,
         status: false,
-        connectUri: false,
-        copy: false,
       },
     ) => {
-      let confNode, confNodePath;
-
-      // Set defaults
       if (!options.user) options.user = 'root';
-      if (!options.host) options.host = await Underpost.dns.getPublicIp();
-      if (!options.password) options.password = options.disablePassword ? '' : generateRandomPasswordSelection(16);
-      if (!options.groups) options.groups = 'wheel';
-      if (!options.port) options.port = 22; // Handle connect uri
-
-      const userHome = Underpost.ssh.getUserHome(options.user);
-      options.userHome = userHome;
 
-      // Load config and override password and host if user exists in config
-      if (options.deployId) {
-        const config = Underpost.ssh.loadConfigNode(options.deployId);
-        confNode = config.confNode;
-        confNodePath = config.confNodePath;
-
-        if (confNode.users && confNode.users[options.user]) {
-          if (confNode.users[options.user].host) {
-            options.host = confNode.users[options.user].host;
-            logger.info(`Using saved host for user ${options.user}: ${options.host}`);
-          }
-          if (confNode.users[options.user].password === '') {
-            options.disablePassword = true;
-            options.password = '';
-            logger.info(`Using saved empty password for user ${options.user}`);
-          } else if (confNode.users[options.user].password) {
-            options.disablePassword = false;
-            options.password = confNode.users[options.user].password;
-            logger.info(`Using saved password for user ${options.user}`);
-          }
-          options.port = options.port || confNode.users[options.user].port || 22;
-        }
+      const users = Underpost.ssh.loadUsers();
+      const confUserIndex = users.findIndex((entry) => entry.user === options.user);
+      const confUser = users[confUserIndex];
+      const registeredHosts = confUser?.hosts || [];
+
+      // Explicit flags win; the registry fills in what was omitted, but only for
+      // the operations that act on one host. A single registered host is
+      // unambiguous and several are not — an account on many spokes must be told
+      // which one is meant rather than acting on whichever the registry lists
+      // first. Listing and removal are account-scoped and need no host at all.
+      const hostScoped = options.userAdd || options.start || options.keyTest || options.hostsList;
+      if (!options.host && hostScoped) {
+        if (registeredHosts.length > 1)
+          throw new Error(
+            `[ssh] user '${options.user}' is registered for several hosts ` +
+              `(${registeredHosts.map((entry) => entry.host).join(', ')}); pass --host to select one`,
+          );
+        options.host = registeredHosts[0]?.host || (await Underpost.dns.getPublicIp());
+      }
+      if (!options.port)
+        options.port =
+          registeredHosts.find((entry) => entry.host === hostNameFactory(options.host))?.port || DEFAULT_SSH_PORT;
+      if (!options.groups) options.groups = 'wheel';
+      if (!options.password) {
+        const generatePassword = !confUser && !options.disablePassword;
+        options.password = generatePassword ? generateRandomPasswordSelection(16) : confUser?.password || '';
       }
 
-      logger.info('options', options);
+      const keyDir = Underpost.ssh.userKeyDir(options.user);
+      const keyPath = confUser?.keyPath || `${keyDir}/id_rsa`;
+      const pubKeyPath = confUser?.pubKeyPath || `${keyDir}/id_rsa.pub`;
+      const sshDirFactory = () => `${Underpost.ssh.getUserHome(options.user)}/.ssh`;
 
-      // Handle connect uri
-      if (options.connectUri) {
-        const keyPath = `${userHome}/.ssh/id_rsa`;
-        const uri = `ssh ${options.user}@${options.host} -i ${keyPath} -p ${options.port}`;
-        if (options.copy) {
-          pbcopy(uri);
-        } else console.log(uri);
-        return;
-      }
+      logger.info('options', options);
 
-      // Handle reset operation
       if (options.reset) {
-        shellExec(`> ${userHome}/.ssh/authorized_keys`);
-        shellExec(`> ${userHome}/.ssh/known_hosts`);
+        const sshDir = sshDirFactory();
+        shellExec(`> ${sshDir}/authorized_keys`);
+        shellExec(`> ${sshDir}/known_hosts`);
       }
 
       if (options.userLs) {
@@ -318,36 +574,30 @@ EOF`);
         console.log('Users'.bold.blue);
         console.log(`user : x : UID : GID : GECOS : home_dir : shell`.blue);
         console.log(filter ? usersOut.replaceAll(filter, filter.red) : usersOut);
+        console.log('Registered cluster users'.bold.blue);
+        users.forEach((entry) =>
+          entry.hosts.forEach((connection) => console.log(`${entry.user}@${connection.host}:${connection.port}`)),
+        );
       }
 
-      // Handle user removal (works with or without deployId)
       if (options.userRemove) {
         const groups = shellExec(`id -Gn ${options.user}`, { silent: true, stdout: true }).trim().replace(/ /g, ', ');
         shellExec(`userdel -r ${options.user}`);
 
-        // Remove sudoers file if it exists
         const sudoersFile = `/etc/sudoers.d/90_${options.user}`;
         if (fs.existsSync(sudoersFile)) {
           shellExec(`sudo rm -f ${sudoersFile}`);
           logger.info(`Sudoers file removed: ${sudoersFile}`);
         }
 
-        // Remove the private key copy folder and update config only if deployId is provided
-        if (options.deployId) {
-          if (!confNode) {
-            const config = Underpost.ssh.loadConfigNode(options.deployId);
-            confNode = config.confNode;
-            confNodePath = config.confNodePath;
-          }
-
-          const privateCopyDir = `./engine-private/conf/${options.deployId}/users/${options.user}`;
-          if (fs.existsSync(privateCopyDir)) {
-            fs.removeSync(privateCopyDir);
-            logger.info(`Private key copy removed from ${privateCopyDir}`);
-          }
+        if (fs.existsSync(keyDir)) {
+          fs.removeSync(keyDir);
+          logger.info(`Key store removed from ${keyDir}`);
+        }
 
-          delete confNode.users[options.user];
-          Underpost.ssh.saveConfigNode(confNodePath, confNode);
+        if (confUser) {
+          users.splice(confUserIndex, 1);
+          Underpost.ssh.saveUsers(users);
         }
 
         logger.info(`User removed`);
@@ -355,145 +605,114 @@ EOF`);
         return;
       }
 
-      // Handle user addition (works with or without deployId)
       if (options.userAdd) {
-        let privateCopyDir, privateKeyPath, publicKeyPath, keysExistInBackup, userExistsInConfig;
-
-        // If deployId is provided, check for existing config and backup keys
-        if (options.deployId) {
-          if (!confNode) {
-            const config = Underpost.ssh.loadConfigNode(options.deployId);
-            confNode = config.confNode;
-            confNodePath = config.confNodePath;
-          }
-
-          userExistsInConfig = confNode.users && confNode.users[options.user];
-          privateCopyDir = `./engine-private/conf/${options.deployId}/users/${options.user}`;
-          privateKeyPath = `${privateCopyDir}/id_rsa`;
-          publicKeyPath = `${privateCopyDir}/id_rsa.pub`;
-          keysExistInBackup = fs.existsSync(privateKeyPath) && fs.existsSync(publicKeyPath);
-
-          // If user exists in config AND keys exist in backup, import those keys
-          if (userExistsInConfig && keysExistInBackup) {
-            logger.info(`User ${options.user} already exists in config. Importing existing keys...`);
-
-            // Create system user if it doesn't exist
-            const userExists = Underpost.ssh.checkUserExists(options.user);
-            if (!userExists) {
-              Underpost.ssh.createSystemUser(options.user, options.password, options.groups);
-            }
-
-            const userHome = Underpost.ssh.getUserHome(options.user);
-            const sshDir = `${userHome}/.ssh`;
-            Underpost.ssh.ensureSSHDirectory(sshDir);
+        if (!Underpost.ssh.checkUserExists(options.user))
+          Underpost.ssh.createSystemUser(options.user, options.password, options.groups);
 
-            const userKeyPath = `${sshDir}/id_rsa`;
-            const userPubKeyPath = `${sshDir}/id_rsa.pub`;
-
-            // Import keys from backup
-            fs.copyFileSync(privateKeyPath, userKeyPath);
-            fs.copyFileSync(publicKeyPath, userPubKeyPath);
-
-            Underpost.ssh.configureAuthorizedKeys(sshDir, userPubKeyPath, options.disablePassword);
-            Underpost.ssh.configureSudoAccess(options.user, options.password, options.disablePassword);
-            Underpost.ssh.configureKnownHosts(sshDir, options.port, options.host);
-            Underpost.ssh.setSSHFilePermissions(sshDir, options.user, userKeyPath, userPubKeyPath);
-
-            logger.info(`Keys imported from ${privateCopyDir} to ${sshDir}`);
-            logger.info(`User added with existing keys`);
-            return;
-          }
-        }
-
-        // New user or no existing keys - create new user and generate keys
-        Underpost.ssh.createSystemUser(options.user, options.password, options.groups);
-
-        const userHome = Underpost.ssh.getUserHome(options.user);
-        const sshDir = `${userHome}/.ssh`;
+        const sshDir = sshDirFactory();
         Underpost.ssh.ensureSSHDirectory(sshDir);
-
-        const keyPath = `${sshDir}/id_rsa`;
-        const pubKeyPath = `${sshDir}/id_rsa.pub`;
-
-        if (!fs.existsSync(keyPath)) {
+        const hostKeyPath = `${sshDir}/id_rsa`;
+        const hostPubKeyPath = `${sshDir}/id_rsa.pub`;
+
+        // A key already trusted cluster wide is reinstalled, never re-issued:
+        // regenerating it would invalidate every host that already holds it.
+        const storedKeys = fs.existsSync(keyPath) && fs.existsSync(pubKeyPath);
+        if (storedKeys) {
+          fs.copyFileSync(keyPath, hostKeyPath);
+          fs.copyFileSync(pubKeyPath, hostPubKeyPath);
+          logger.info(`Keys imported from ${keyDir} to ${sshDir}`);
+        } else if (!fs.existsSync(hostKeyPath)) {
           shellExec(
-            `ssh-keygen -t ed25519 -f ${keyPath} -N "${options.password}" -q -C "${options.user}@${options.host}"`,
+            `ssh-keygen -t ed25519 -f ${hostKeyPath} -N "${options.password}" -q -C "${options.user}@${options.host}"`,
+            { disableLog: true },
           );
+        } else if (!fs.existsSync(hostPubKeyPath)) {
+          shellExec(`ssh-keygen -y -f ${hostKeyPath} -P "${options.password}" > ${hostPubKeyPath}`, {
+            disableLog: true,
+          });
         }
 
-        Underpost.ssh.configureAuthorizedKeys(sshDir, pubKeyPath, options.disablePassword);
-        Underpost.ssh.configureSudoAccess(options.user, options.password, options.disablePassword);
+        Underpost.ssh.configureAuthorizedKeys(sshDir, hostPubKeyPath, !options.password);
+        Underpost.ssh.configureSudoAccess(options.user, options.password);
         Underpost.ssh.configureKnownHosts(sshDir, options.port, options.host);
-        Underpost.ssh.setSSHFilePermissions(sshDir, options.user, keyPath, pubKeyPath);
-
-        // Save a copy of the keys to the private folder only if deployId is provided
-        if (options.deployId) {
-          if (!privateCopyDir) privateCopyDir = `./engine-private/conf/${options.deployId}/users/${options.user}`;
-          fs.ensureDirSync(privateCopyDir);
-
-          const privateKeyCopyPath = `${privateCopyDir}/id_rsa`;
-          const publicKeyCopyPath = `${privateCopyDir}/id_rsa.pub`;
-
-          fs.copyFileSync(keyPath, privateKeyCopyPath);
-          fs.copyFileSync(pubKeyPath, publicKeyCopyPath);
-
-          logger.info(`Keys backed up to ${privateCopyDir}`);
-
-          confNode.users[options.user] = {
-            ...confNode.users[options.user],
-            ...options,
-            keyPath,
-            pubKeyPath,
-            privateKeyCopyPath,
-            publicKeyCopyPath,
-          };
-          Underpost.ssh.saveConfigNode(confNodePath, confNode);
-        }
-
-        logger.info(`User added`);
-        return;
-      }
+        Underpost.ssh.setSSHFilePermissions(sshDir, options.user, hostKeyPath, hostPubKeyPath);
 
-      // Handle config user listing (only with deployId)
-      if (options.deployId) {
-        if (!confNode) {
-          const config = Underpost.ssh.loadConfigNode(options.deployId);
-          confNode = config.confNode;
-          confNodePath = config.confNodePath;
+        if (!storedKeys) {
+          fs.ensureDirSync(keyDir);
+          fs.copyFileSync(hostKeyPath, keyPath);
+          fs.copyFileSync(hostPubKeyPath, pubKeyPath);
+          logger.info(`Keys backed up to ${keyDir}`);
         }
 
-        if (options.userLs && confNode && confNode.users) {
-          logger.info(`Users in config:`);
-          Object.keys(confNode.users).forEach((user) => {
-            logger.info(`- ${user}`);
-          });
-        }
+        // Additive: registering the account for another host adds that host,
+        // it does not replace the record. One operator account across several
+        // spokes is the normal case, and replacing here is what previously left
+        // remediation unable to resolve a spoke that had just been registered.
+        const record = {
+          ...(confUser || {}),
+          user: options.user,
+          password: options.password,
+          groups: options.groups,
+          keyPath,
+          pubKeyPath,
+          hosts: upsertConnection(registeredHosts, { host: options.host, port: options.port }),
+        };
+        if (confUser) users[confUserIndex] = record;
+        else users.push(record);
+        Underpost.ssh.saveUsers(users);
+
+        logger.info(`User added`, { user: options.user, hosts: record.hosts });
+        return;
       }
 
-      // Handle generate root keys
       if (options.generate)
         Underpost.ssh.generateKeys({ user: options.user, password: options.password, host: options.host });
 
-      // Handle list operations
-      if (options.keysList) shellExec(`cat ${userHome}/.ssh/authorized_keys`);
-      if (options.hostsList) shellExec(`cat ${userHome}/.ssh/known_hosts`);
+      if (options.keysList) shellExec(`cat ${sshDirFactory()}/authorized_keys`);
+      if (options.hostsList) shellExec(`cat ${sshDirFactory()}/known_hosts`);
 
-      // Handle key test
-      if (options.keyTest) {
-        const keyPath = `${userHome}/.ssh/id_rsa`;
-        shellExec(`ssh-keygen -y -f ${keyPath} -P "${options.password}"`);
-      }
+      if (options.keyTest) shellExec(`ssh-keygen -y -f ${keyPath} -P "${options.password}"`);
 
-      // Handle stop server
       if (options.stop) shellExec('service sshd stop');
 
-      // Handle start server
       if (options.start) {
-        Underpost.ssh.chmod({ user: options.user });
+        if (!confUser) {
+          Underpost.ssh.initializeDefaultSshConfig({
+            user: options.user,
+            password: options.password,
+            host: options.host,
+            port: options.port,
+          });
+        } else {
+          // Hardening sshd on a host where the account does not exist produces a
+          // daemon that starts cleanly and refuses the only user it was meant to
+          // admit. Nothing downstream reports that, so the run has to.
+          if (!Underpost.ssh.checkUserExists(options.user))
+            throw new Error(
+              `[ssh] user '${options.user}' does not exist on this host; ` +
+                `run: node bin ssh --user ${options.user} --user-add`,
+            );
+          // The registry records the key pair this cluster authenticates with, so
+          // a box whose authorized_keys was lost converges here rather than
+          // needing the key re-issued — which would invalidate every other host
+          // holding it.
+          if (fs.existsSync(pubKeyPath)) {
+            const sshDir = sshDirFactory();
+            Underpost.ssh.ensureSSHDirectory(sshDir);
+            fs.ensureFileSync(`${sshDir}/authorized_keys`);
+            Underpost.ssh.configureAuthorizedKeys(sshDir, pubKeyPath, !options.password);
+            logger.info(`Authorized key present for ${options.user}`, { source: pubKeyPath });
+          } else {
+            logger.warn('Registered public key is missing; authorized_keys left untouched', {
+              user: options.user,
+              expected: pubKeyPath,
+            });
+          }
+          Underpost.ssh.chmod({ user: options.user });
+        }
         Underpost.ssh.initService({ port: options.port });
       }
 
-      // Handle status server
       if (options.status) shellExec('service sshd status');
     },
 
@@ -515,9 +734,13 @@ EOF`);
      * @param {string} params.remoteDir - Destination directory on the node.
      * @param {number} [params.port=22] - SSH port.
      * @param {string} [params.user='root'] - SSH user (key-only).
-     * @param {string} [params.keyPath='./engine-private/deploy/id_rsa'] - Private key path.
+     * @param {string} [params.keyPath] - Private key path; resolved by {@link sshKeyPathFactory} when empty.
      * @param {string} [params.owner='1000:1000'] - chown target on the node (empty to skip).
      * @param {string} [params.mode='755'] - chmod mode on the node (empty to skip).
+     * @param {boolean} [params.containerStorage=false] - Give the destination tree the persistent
+     *   `container_file_t` mapping on the node. Required for a hostPath volume: the label has to
+     *   exist on the node that actually mounts it, and a directory created here by `mkdir -p`
+     *   otherwise inherits whatever the parent carries — which no unprivileged pod can read.
      * @returns {void}
      */
     copyDirToNode: ({
@@ -526,16 +749,18 @@ EOF`);
       remoteDir,
       port = 22,
       user = 'root',
-      keyPath = './engine-private/deploy/id_rsa',
+      keyPath = '',
       owner = '1000:1000',
       mode = '755',
+      containerStorage = false,
     }) => {
       if (!host) throw new Error('copyDirToNode requires a host');
       if (!localDir || !fs.existsSync(localDir)) throw new Error(`copyDirToNode: local dir not found: ${localDir}`);
       if (!remoteDir) throw new Error('copyDirToNode requires a remoteDir');
+      const key = sshKeyPathFactory(keyPath);
       try {
-        shellExec(`chmod 600 ${keyPath}`, { silent: true, silentOnError: true, disableLog: true });
-        const sshOpts = `-i ${keyPath} -o BatchMode=yes -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -p ${port}`;
+        shellExec(`chmod 600 ${key}`, { silent: true, silentOnError: true, disableLog: true });
+        const sshOpts = `-i ${key} -o BatchMode=yes -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -p ${port}`;
         shellExec(`ssh ${sshOpts} ${user}@${host} 'mkdir -p ${remoteDir}'`, {
           silent: true,
           disableLog: true,
@@ -551,12 +776,32 @@ EOF`);
             silent: true,
             disableLog: true,
           });
+        // After the fixups, so the restorecon pass covers the files tar just extracted. A no-op
+        // on a node without SELinux, and it never runs unless the caller asked for it.
+        if (containerStorage)
+          shellExec(
+            `ssh ${sshOpts} ${user}@${host} ${shellArgumentFactory(
+              ContainerStorageService.containerStorageSubtreeCommandsFactory(remoteDir, {
+                sudo: user !== 'root',
+              }).join('; '),
+            )}`,
+            { silent: true, disableLog: true },
+          );
       } catch (err) {
         logger.error(`copyDirToNode failed`);
         process.exit(1);
       }
     },
 
+    /**
+     * The private key this process authenticates with; see {@link sshKeyPathFactory}.
+     * @function keyPathFactory
+     * @param {string} [keyPath] - Explicit path, which always wins.
+     * @returns {string} Path to the private key.
+     * @memberof UnderpostSSH
+     */
+    keyPathFactory: sshKeyPathFactory,
+
     /**
      * Generic SSH remote command runner that SSH execution logic.
      * Executes arbitrary shell commands on a remote server via SSH with proper credential handling.
@@ -564,46 +809,68 @@ EOF`);
      * @function sshRemoteRunner
      * @param {string} remoteCommand - The command to execute on the remote server
      * @param {Object} options - Configuration options for SSH execution
-     * @param {string} [options.deployId] - Deployment ID for credential lookup
-     * @param {string} [options.user] - SSH user for credential lookup
+     * @param {string} [options.user] - SSH user for cluster credential lookup
+     * @param {string} [options.host] - Host to reach; selects the connection when the user has several
      * @param {boolean} [options.dev=false] - Development mode flag
      * @param {string} [options.cd='/home/dd/engine'] - Working directory on remote server
      * @param {boolean} [options.useSudo=true] - Whether to use sudo for command execution
-     * @param {boolean} [options.remote=true] - Whether to execute as remote command (if false, runs locally)
+     * @param {boolean} [options.remote=true] - Whether to execute as remote command (if false, runs locally in `cd`)
+     * @param {boolean} [options.silent=false] - Suppress the command's output; it is still returned to the caller
      * @returns {Promise<string>} Output from the shell execution
      * @memberof UnderpostSSH
      */
     sshRemoteRunner: async (remoteCommand, options = {}) => {
-      const { deployId = '', user = '', dev = false, cd = '/home/dd/engine', useSudo = true, remote = true } = options;
-
-      // If not executing remotely, just run locally
+      const {
+        user = '',
+        host = '',
+        dev = false,
+        cd = '/home/dd/engine',
+        useSudo = true,
+        remote = true,
+        silent = false,
+      } = options;
+
+      // Local execution still honours `cd`: the underpost CLI resolves its deploy
+      // configuration relative to the working directory, so running it from
+      // wherever the caller happened to start would act on a different cluster's
+      // config, or none. It honours it only when that directory exists — a checkout
+      // that lives elsewhere (a CI container, a developer tree) has no deploy path to
+      // enter, and chdir failing there turns a runnable local command into an error
+      // reported as a failed remediation.
+      // The generated wrapper is transport, not information: echoing it buries
+      // whatever the command actually said under a page of boilerplate.
       if (!remote) {
-        return shellExec(remoteCommand);
+        const cwd = cd && fs.existsSync(cd) ? cd : '';
+        return shellExecRedacted(remoteCommand, { ...(cwd ? { cwd } : {}), silent, disableLog: true });
       }
 
-      // Set up SSH credentials from config
-      if (deployId && user) {
-        await Underpost.ssh.setDefautlSshCredentials({ deployId, user });
-      }
+      // Set up SSH credentials from the cluster config
+      if (user) await Underpost.ssh.setDefautlSshCredentials({ user, host });
+
+      // The store holds the key `setDefautlSshCredentials` just resolved for this target, which is
+      // the only per-target answer; a pod has no such key on disk and takes its mount instead.
+      const sshKey = fs.existsSync(SECRET_KEY_PATH)
+        ? shellArgumentFactory(SECRET_KEY_PATH)
+        : '$(node bin host get --plain DEFAULT_SSH_KEY_PATH)';
 
-      // Build the complete SSH command
       const sshScript = `#!/usr/bin/env bash
 set -euo pipefail
 
-REMOTE_USER=$(node bin config get --plain DEFAULT_SSH_USER)
-REMOTE_HOST=$(node bin config get --plain DEFAULT_SSH_HOST)
-REMOTE_PORT=$(node bin config get --plain DEFAULT_SSH_PORT)
-SSH_KEY=$(node bin config get --plain DEFAULT_SSH_KEY_PATH)
+REMOTE_USER=$(node bin host get --plain DEFAULT_SSH_USER)
+REMOTE_HOST=$(node bin host get --plain DEFAULT_SSH_HOST)
+REMOTE_PORT=$(node bin host get --plain DEFAULT_SSH_PORT)
+SSH_KEY=${sshKey}
 
-chmod 600 "$SSH_KEY"
+# A projected Secret is read-only, and its mode is already restrictive enough for ssh.
+chmod 600 "$SSH_KEY" 2>/dev/null || true
 
-ssh -i "$SSH_KEY" -o BatchMode=yes -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null "$REMOTE_USER@$REMOTE_HOST" -p $REMOTE_PORT sh <<EOF
+ssh -i "$SSH_KEY" -o BatchMode=yes -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -o LogLevel=ERROR "$REMOTE_USER@$REMOTE_HOST" -p $REMOTE_PORT sh <<EOF
 ${cd ? `cd ${cd}` : ''}
 ${useSudo ? `sudo -n -- /bin/bash -lc "${remoteCommand}"` : remoteCommand}
 EOF
 `;
 
-      return shellExec(sshScript, { stdout: true });
+      return shellExecRedacted(sshScript, { silent, disableLog: true });
     },
 
     /**
@@ -651,7 +918,7 @@ EOF
      * @param {string} params.command - Remote command batch to execute.
      * @param {number} [params.port=22] - SSH port.
      * @param {string} [params.user='root'] - SSH user (key-only).
-     * @param {string} [params.keyPath] - Private key path (defaults to engine deploy key).
+     * @param {string} [params.keyPath] - Private key path; resolved by {@link sshKeyPathFactory} when empty.
      * @param {number} [params.connectTimeoutSec=15] - Per-attempt SSH connect timeout.
      * @param {number} [params.retries=3] - Auth/exec retry attempts.
      * @param {number} [params.retryDelayMs=5000] - Base backoff between retries.
@@ -663,7 +930,7 @@ EOF
       command,
       port = 22,
       user = 'root',
-      keyPath = './engine-private/deploy/id_rsa',
+      keyPath = '',
       connectTimeoutSec = 15,
       retries = 3,
       retryDelayMs = 5000,
@@ -677,10 +944,11 @@ EOF
         if (!reachable) return { ok: false, code: 255, stdout: '', stderr: 'ssh port unreachable', attempts: 0 };
       }
 
-      shellExec(`chmod 600 ${keyPath}`, { silent: true, silentOnError: true, disableLog: true });
+      const key = sshKeyPathFactory(keyPath);
+      shellExec(`chmod 600 ${key}`, { silent: true, silentOnError: true, disableLog: true });
 
       const sshOpts = [
-        `-i ${keyPath}`,
+        `-i ${key}`,
         `-o BatchMode=yes`,
         `-o PreferredAuthentications=publickey`,
         `-o PubkeyAuthentication=yes`,
@@ -756,7 +1024,7 @@ EOF
       remotePath = '/tmp/underpost-remote-script.sh',
       port = 22,
       user = 'root',
-      keyPath = './engine-private/deploy/id_rsa',
+      keyPath = '',
       retries = 3,
       waitForPortMs = 0,
     }) => {
@@ -779,25 +1047,73 @@ EOF
     },
 
     /**
-     * Loads saved SSH credentials from config and sets them in the UnderpostRootEnv API.
+     * Loads a user's SSH credentials for one host and sets them in the host
+     * configuration store.
+     *
+     * `host` is what selects the connection: an account registered for several
+     * hosts has several, and picking one without being told would send a repair
+     * to the wrong machine. Omitting it is only unambiguous for an account with
+     * exactly one registered host.
+     *
+     * A named host is resolved against the registry and nowhere else. The root
+     * env store is ambient — whatever the previous command left there — so
+     * substituting it for a host the registry does not know would silently point
+     * an operation at a different machine, which for remediation means repairing
+     * one host because another was unreachable. Its `DEFAULT_SSH_*` values are
+     * promoted only when no host was named, for a controller that dispatches
+     * work but was never itself provisioned by `--user-add`.
      * @async
      * @function setDefautlSshCredentials
      * @memberof UnderpostSSH
      * @param {Object} options - Options for setting default SSH credentials
-     * @param {string} options.deployId - Deployment ID for the config path
-     * @param {string} options.user - SSH user name
+     * @param {string} options.user - SSH user name registered at cluster scope
+     * @param {string} [options.host] - Host to connect to; required when the account has several
      * @returns {Promise<void>}
+     * @throws {Error} When a named host has no connection registered for that account.
      */
-    setDefautlSshCredentials: async (options = { deployId: '', user: '' }) => {
-      const confNodePath = `./engine-private/conf/${options.deployId}/conf.node.json`;
-      if (fs.existsSync(confNodePath)) {
-        const { users } = JSON.parse(fs.readFileSync(confNodePath, 'utf8'));
-        const { user, host, keyPath, port } = users[options.user];
-        Underpost.env.set('DEFAULT_SSH_USER', user);
-        Underpost.env.set('DEFAULT_SSH_HOST', host);
-        Underpost.env.set('DEFAULT_SSH_KEY_PATH', keyPath);
-        Underpost.env.set('DEFAULT_SSH_PORT', port);
-      } else logger.warn(`No SSH config found at ${confNodePath}`);
+    setDefautlSshCredentials: async (options = { user: '', host: '' }) => {
+      const hosts = Underpost.ssh.userHosts(options.user);
+      if (!options.host && hosts.length > 1)
+        throw new Error(
+          `[ssh] user '${options.user}' is registered for several hosts ` +
+            `(${hosts.map((entry) => entry.host).join(', ')}); the caller must name one`,
+        );
+
+      const registered = Underpost.ssh.resolveConnection({
+        user: options.user,
+        host: options.host || hosts[0]?.host,
+      });
+
+      if (!registered && options.host)
+        throw new Error(
+          `[ssh] no connection is registered for '${options.user}@${options.host}' in ${USERS_CONF_PATH}; ` +
+            `run: node bin ssh --user ${options.user} --host ${options.host} --user-add`,
+        );
+
+      const connection =
+        registered ||
+        (process.env.DEFAULT_SSH_USER && process.env.DEFAULT_SSH_HOST && process.env.DEFAULT_SSH_KEY_PATH
+          ? {
+              user: process.env.DEFAULT_SSH_USER,
+              host: process.env.DEFAULT_SSH_HOST,
+              keyPath: process.env.DEFAULT_SSH_KEY_PATH,
+              port: process.env.DEFAULT_SSH_PORT || DEFAULT_SSH_PORT,
+            }
+          : undefined);
+
+      if (!connection) {
+        logger.warn(`No SSH credentials for '${options.user}'`, {
+          host: options.host || '(unspecified)',
+          registry: USERS_CONF_PATH,
+        });
+        return;
+      }
+      if (!registered) logger.warn(`Using the deploy environment DEFAULT_SSH_* values`, { requested: options.user });
+
+      Underpost.host.store.set('DEFAULT_SSH_USER', connection.user);
+      Underpost.host.store.set('DEFAULT_SSH_HOST', connection.host);
+      Underpost.host.store.set('DEFAULT_SSH_KEY_PATH', connection.keyPath);
+      Underpost.host.store.set('DEFAULT_SSH_PORT', connection.port);
     },
 
     /**
@@ -848,12 +1164,26 @@ EOF
      * Sets ownership to specified user for ~/.ssh/ and contents.
      */
     chmod: ({ user }) => {
-      shellExec(`sudo chmod 700 ~/.ssh/`);
-      shellExec(`sudo chmod 600 ~/.ssh/authorized_keys`);
-      shellExec(`sudo chmod 644 ~/.ssh/known_hosts`);
-      shellExec(`sudo chmod 600 ~/.ssh/id_rsa`);
+      const sshDirectory = `${Underpost.ssh.getUserHome(user)}/.ssh`;
+      shellExec(`sudo chmod 700 ${shellArgumentFactory(sshDirectory)}`);
+      shellExec(
+        `if [ -f ${shellArgumentFactory(`${sshDirectory}/authorized_keys`)} ]; then sudo chmod 600 ${shellArgumentFactory(`${sshDirectory}/authorized_keys`)}; fi`,
+      );
+      shellExec(
+        `if [ -f ${shellArgumentFactory(`${sshDirectory}/known_hosts`)} ]; then sudo chmod 644 ${shellArgumentFactory(`${sshDirectory}/known_hosts`)}; fi`,
+      );
+      shellExec(
+        `if [ -f ${shellArgumentFactory(`${sshDirectory}/id_rsa`)} ]; then sudo chmod 600 ${shellArgumentFactory(`${sshDirectory}/id_rsa`)}; fi`,
+      );
       shellExec(`sudo chmod 600 /etc/ssh/ssh_host_ed25519_key`);
-      shellExec(`chown -R ${user}:${user} ~/.ssh`);
+      shellExec(`sudo chown -R ${shellArgumentFactory(`${user}:${user}`)} ${shellArgumentFactory(sshDirectory)}`);
+      runSELinuxCommands(
+        [
+          ...selinuxSshContextCommandsFactory({ sshDirectory }),
+          selinuxRestoreconCommandFactory('/etc/ssh/ssh_host_ed25519_key', { recursive: false }),
+        ],
+        { execute: shellExec },
+      );
     },
 
     /**
@@ -866,7 +1196,7 @@ EOF
      * @description
      * Configures SSH daemon with hardened security settings:
      * - Disables password authentication (key-only)
-     * - Disables root login
+     * - Allows key-only root login
      * - Enables ED25519 host key
      * - Disables X11 forwarding and TCP forwarding
      * - Sets client alive intervals to prevent ghost connections
@@ -878,69 +1208,57 @@ EOF
      * - Displays service status with colored output
      */
     initService: ({ port }) => {
-      shellExec(
-        `sudo tee /etc/ssh/sshd_config <<EOF
-# ==============================================================
-# RHEL Hardened SSHD Configuration
-# ==============================================================
-
-# --- Network Settings ---
-Port ${port ? port : '22'}
-# Explicitly listen on all interfaces (IPv4 and IPv6)
-
-# --- Host Keys ---
-# ED25519 is the modern standard (Fast & Secure)
+      const sshPort = Number(port || 22);
+      const portCommands = selinuxSshPortCommandsFactory({ port: sshPort });
+      const temporaryPath = `/tmp/underpost-sshd-config-${process.pid}`;
+      const configuration = `Port ${sshPort}
 HostKey /etc/ssh/ssh_host_ed25519_key
-# RSA is kept for compatibility with older clients (Optional)
-# HostKey /etc/ssh/ssh_host_rsa_key
-
-# --- Logging ---
 SyslogFacility AUTHPRIV
-# VERBOSE logs the key fingerprint used for login (Audit trail)
 LogLevel VERBOSE
-
-# --- Authentication & Security ---
-# STRICTLY KEY-BASED AUTHENTICATION
 PubkeyAuthentication yes
 PasswordAuthentication no
-ChallengeResponseAuthentication no
+KbdInteractiveAuthentication no
 PermitEmptyPasswords no
-
-# PREVENT ROOT LOGIN
-# Administrators should log in as a standard user and use 'sudo'
-PermitRootLogin no
-
-# Security checks on ownership of ~/.ssh/ files
+PermitRootLogin prohibit-password
 StrictModes yes
 MaxAuthTries 3
 LoginGraceTime 60
-
-# --- PAM (Pluggable Authentication Modules) ---
-# REQUIRED: Must be 'yes' on RHEL for proper session/SELinux handling.
-# Since PasswordAuthentication is 'no', PAM will not ask for passwords.
 UsePAM yes
-
-# --- Session & Network Health ---
-# Disconnect idle sessions after 5 minutes (300s * 0) to prevent ghost connections
 ClientAliveInterval 300
 ClientAliveCountMax 0
-
-# --- Feature Restrictions ---
-# Disable GUI forwarding unless explicitly needed
 X11Forwarding no
-# Disable DNS checks for faster logins (unless you use Host based auth)
 UseDNS no
-# Disable tunneling unless needed
 PermitTunnel no
 AllowTcpForwarding no
-
-# --- Subsystem ---
+Include /etc/ssh/sshd_config.d/*.conf
 Subsystem sftp /usr/libexec/openssh/sftp-server
-EOF`,
-        { disableLog: true },
-      );
-      shellExec(`sudo systemctl enable sshd`);
-      shellExec(`sudo systemctl restart sshd`);
+`;
+
+      fs.writeFileSync(temporaryPath, configuration, { mode: 0o600 });
+      try {
+        if (sshPort !== 22) {
+          shellExec(
+            `if command -v dnf >/dev/null 2>&1 && ! command -v semanage >/dev/null 2>&1; then ${selinuxPackagesCommandFactory()}; fi`,
+          );
+        }
+        runSELinuxCommands(portCommands, { execute: shellExec });
+        shellExec(`sudo ssh-keygen -A`);
+        shellExec(`sudo /usr/sbin/sshd -t -f ${shellArgumentFactory(temporaryPath)}`);
+        shellExec(`sudo install -m 0600 -o root -g root ${shellArgumentFactory(temporaryPath)} /etc/ssh/sshd_config`);
+        runSELinuxCommands(
+          [selinuxRestoreconCommandFactory(['/etc/ssh/sshd_config', '/etc/ssh/ssh_host_ed25519_key'])],
+          { execute: shellExec },
+        );
+        if (sshPort !== 22) {
+          shellExec(
+            `if command -v firewall-cmd >/dev/null 2>&1 && sudo firewall-cmd --state >/dev/null 2>&1; then sudo firewall-cmd --permanent --add-port=${sshPort}/tcp && sudo firewall-cmd --reload; fi`,
+          );
+        }
+        shellExec(`sudo systemctl enable sshd`);
+        shellExec(`sudo systemctl restart sshd`);
+      } finally {
+        fs.removeSync(temporaryPath);
+      }
 
       const status = shellExec(`sudo systemctl status sshd`, { silent: true, stdout: true });
       if (status.match('running')) console.log(status.replaceAll(`running`, `running`.green));
@@ -952,4 +1270,6 @@ EOF`,
   };
 }
 
+export { connectionFactory, hostNameFactory, upsertConnection, userRecordFactory };
+
 export default UnderpostSSH;