@underpostnet/cyberia 3.2.90 → 3.3.73

package/test/integration/infra/1-security/config-scope.test.js

@@ -0,0 +1,305 @@
+'use strict';
+
+/**
+ * @module config-scope.test
+ * @description Proves that a credential cannot cross the scope that owns it.
+ *
+ * The assertions here are mostly about absence, which is the half that matters: a projection that
+ * carries too much still passes every test written about what it carries. Each case names a real
+ * credential family and asserts the cron workloads cannot see it.
+ *
+ * Uses 'chai' for assertions.
+ */
+
+import { expect } from 'chai';
+import fs from 'fs-extra';
+import UnderpostCron, { cronJobYamlFactory, engineMirrorContentsFactory } from '../../../../src/server/ops/cron.js';
+import UnderpostSecret from '../../../../src/cli/secrets.js';
+import UnderpostHost from '../../../../src/cli/host.js';
+import {
+  CONFIG_OWNERSHIP,
+  CONFIG_SCOPES,
+  SCOPE_ENTITLEMENTS,
+  classifyConfigKeys,
+  configOwnershipFactory,
+  configRejectionFactory,
+  scopeReceivesKey,
+  scopeValuesFactory,
+} from '../../../../src/server/runtime/config-scope.js';
+
+// One representative credential per foreign scope, with the value a leak would expose.
+const FOREIGN_CREDENTIALS = {
+  DB_PASSWORD: 'app-database-secret',
+  JWT_SECRET: 'app-session-secret',
+  CLOUDINARY_API_SECRET: 'app-integration-secret',
+  MARIADB_PASSWORD: 'app-mariadb-secret',
+  WP_ADMIN_PASSWORD_SITE: 'app-wordpress-secret',
+  MAAS_API_KEY: 'baremetal-maas-secret',
+  DB_PG_MAAS_PASS: 'baremetal-postgres-secret',
+  NPM_TOKEN: 'publishing-npm-secret',
+  DOCKER_HUB_ACCESS_TOKEN: 'publishing-registry-secret',
+  POSTMAN_PASSWORD: 'publishing-postman-secret',
+  GF_SECURITY_ADMIN_PASSWORD: 'host-grafana-secret',
+  CLUSTER_MAILER_SMTP_AUTH_PASS: 'host-mailer-secret',
+  UNDERPOST_EVENT_TOKEN: 'host-dispatcher-secret',
+};
+
+const CRON_CREDENTIALS = {
+  VULTR_API_KEY: 'cron-vultr',
+  DDNS_API_KEY: 'cron-ddns',
+  GITHUB_TOKEN: 'cron-github',
+  DEFAULT_SSH_HOST: '10.0.0.1',
+  FORWARD_PROXY_API_KEY: 'cron-proxy',
+};
+
+// Entitled to no scope: consumed by nothing in a pod, and a projected key path would shadow the
+// Secret volume that holds the actual credential.
+const UNCONSUMED_BY_CRON = {
+  DEFAULT_SSH_KEY_PATH: '/home/dd/engine/engine-private/deploy/id_rsa',
+  VULTR_SSH_KEY_PATH: '/home/dd/engine/engine-private/deploy/id_rsa',
+  GITHUB_BACKUP_REPO: 'owner/backups',
+};
+
+describe('configuration scope ownership', () => {
+  it('places every key of the live host source, or names the ones it cannot', () => {
+    // Fail-closed is the whole contract: an unplaced key is reported for a decision rather than
+    // defaulted into a scope, because both wrong answers are silent.
+    const source = './engine-private/conf/dd-cron/.env.production';
+    if (!fs.existsSync(source)) return;
+    const values = Object.fromEntries(
+      fs
+        .readFileSync(source, 'utf8')
+        .split('\n')
+        .map((line) => line.match(/^([A-Za-z_][A-Za-z0-9_]*)=/)?.[1])
+        .filter(Boolean)
+        .map((key) => [key, '']),
+    );
+    expect(classifyConfigKeys(values).unclassified).to.deep.equal([]);
+  });
+
+  it('gives every key exactly one owner', () => {
+    for (const key of [...Object.keys(FOREIGN_CREDENTIALS), ...Object.keys(CRON_CREDENTIALS)]) {
+      const ownership = configOwnershipFactory(key);
+      expect(ownership, key).to.not.equal(null);
+      expect(Object.keys(CONFIG_SCOPES), key).to.include(ownership.owner);
+    }
+  });
+
+  it('reports an unknown key rather than placing it', () => {
+    expect(configOwnershipFactory('SOME_NEW_CREDENTIAL')).to.equal(null);
+    expect(classifyConfigKeys({ SOME_NEW_CREDENTIAL: 'x' }).unclassified).to.deep.equal(['SOME_NEW_CREDENTIAL']);
+    expect(scopeReceivesKey('SOME_NEW_CREDENTIAL', 'cron')).to.equal(false);
+  });
+
+  it('projects only by an explicit rule, never by inheritance', () => {
+    // A projection is an edit to the ownership table, so it is reviewable.
+    expect(configOwnershipFactory('GITHUB_TOKEN')).to.deep.equal({ owner: 'host', projectedTo: ['cron'] });
+    expect(configOwnershipFactory('GF_SECURITY_ADMIN_PASSWORD')).to.deep.equal({ owner: 'host', projectedTo: [] });
+    // Both are host-owned; only one reaches cron.
+    expect(scopeReceivesKey('GITHUB_TOKEN', 'cron')).to.equal(true);
+    expect(scopeReceivesKey('GF_SECURITY_ADMIN_PASSWORD', 'cron')).to.equal(false);
+  });
+
+  it('names a rejection without disclosing the value behind it', () => {
+    const line = configRejectionFactory({
+      domain: 'cron',
+      deployId: 'dd-cron',
+      env: 'production',
+      key: 'MAAS_API_KEY',
+      reason: 'key belongs to baremetal scope',
+    });
+    expect(line).to.equal(
+      'configuration source rejected: domain=cron deploy=dd-cron env=production key=MAAS_API_KEY ' +
+        'reason=key belongs to baremetal scope',
+    );
+    expect(line).to.not.include('baremetal-maas-secret');
+  });
+
+  it('orders the ownership table so a narrower rule is never shadowed', () => {
+    for (const [index, rule] of CONFIG_OWNERSHIP.entries()) {
+      const shadowed = CONFIG_OWNERSHIP.slice(0, index).find((earlier) => earlier.match.source === rule.match.source);
+      expect(shadowed, rule.match.source).to.equal(undefined);
+    }
+  });
+});
+
+describe('cron cannot see what it does not own', () => {
+  const environment = { ...FOREIGN_CREDENTIALS, ...UNCONSUMED_BY_CRON, ...CRON_CREDENTIALS };
+
+  it('entitles cron to its own scope and to nothing else', () => {
+    const entitled = scopeValuesFactory(environment, 'cron');
+    for (const key of Object.keys(CRON_CREDENTIALS)) expect(entitled, key).to.have.property(key);
+    for (const key of Object.keys(FOREIGN_CREDENTIALS)) expect(entitled, key).to.not.have.property(key);
+    for (const key of Object.keys(UNCONSUMED_BY_CRON)) expect(entitled, key).to.not.have.property(key);
+  });
+
+  it('keeps every foreign credential out of the projected Secret, by value as well as by key', () => {
+    const previous = { ...process.env };
+    try {
+      Object.assign(process.env, environment);
+      const projected = UnderpostSecret.API.seedEnvKeys('underpost-cron-env');
+      const rendered = JSON.stringify(projected);
+      for (const [key, value] of Object.entries({ ...FOREIGN_CREDENTIALS, ...UNCONSUMED_BY_CRON })) {
+        expect(projected, key).to.not.have.property(key);
+        expect(rendered, value).to.not.include(value);
+      }
+      for (const key of Object.keys(CRON_CREDENTIALS)) expect(projected, key).to.have.property(key);
+    } finally {
+      for (const key of Object.keys(environment)) {
+        if (previous[key] === undefined) delete process.env[key];
+        else process.env[key] = previous[key];
+      }
+    }
+  });
+
+  it('mirrors no deployment environment file into the shared tree', () => {
+    // The mirror carries the shared container label, so a single `.env.*` rule there hands every
+    // deployment's credentials to every container on the node.
+    const rules = engineMirrorContentsFactory();
+    expect(rules.at(-1)).to.equal('--exclude=*');
+    expect(rules.some((rule) => rule.includes('.env'))).to.equal(false);
+    for (const environmentName of ['production', 'development', 'test'])
+      expect(rules.join(' '), environmentName).to.not.include(`.env.${environmentName}`);
+  });
+
+  it('mirrors the configuration documents, which hold references rather than values', () => {
+    const rules = engineMirrorContentsFactory();
+    expect(rules).to.include('--include=/engine-private/conf/*/conf.*.json');
+    expect(rules).to.include('--include=/engine-private/deploy/dd.cron');
+    expect(rules).to.include('--include=/engine-private/deploy/dd.routes');
+  });
+
+  it('takes no environment from a file at runtime, so a mirrored one cannot be reintroduced', () => {
+    const manifest = cronJobYamlFactory({
+      name: 'dd-cron-vultr',
+      expression: '*/30 * * * *',
+      deployList: 'dd-cron',
+      jobList: 'vultr',
+      kubeadm: true,
+    });
+    expect(manifest).to.not.include('app load');
+    expect(manifest).to.include('node bin cron dd-cron vultr');
+    expect(manifest).to.include('secretRef:');
+    expect(manifest).to.include('name: underpost-cron-env');
+  });
+
+  it('renders the resolved environment into the manifest, where it wins over the projection', () => {
+    const render = (dev) =>
+      cronJobYamlFactory({ name: 'x', expression: '* * * * *', deployList: 'dd-cron', jobList: 'vultr', dev });
+    expect(render(false)).to.include('- name: NODE_ENV\n                  value: production');
+    expect(render(true)).to.include('- name: NODE_ENV\n                  value: development');
+  });
+
+  it('exposes the job handlers it is meant to, unchanged by the scoping', () => {
+    expect(Object.keys(UnderpostCron.JOB).sort()).to.deep.equal(['backup', 'dns', 'vultr']);
+  });
+});
+
+// Proves the finalized policy: ownership may be a family pattern, but what a workload may *read*
+// is an exact list. Without this, the next credential added to an owned family arrives in a pod
+// unreviewed, which is the failure mode the entitlement table exists to prevent.
+describe('scope entitlement is explicit, not inferred from naming', () => {
+  it('refuses a new member of an owned family, however it is named', () => {
+    for (const key of ['GITHUB_NEW_SENSITIVE_TOKEN', 'VULTR_NEW_SECRET', 'DDNS_NEW_SECRET']) {
+      expect(configOwnershipFactory(key), key).to.not.equal(null);
+      expect(scopeReceivesKey(key, 'cron'), key).to.equal(false);
+    }
+    // The named members it replaces stay entitled, so the narrowing is a policy and not an outage.
+    for (const key of ['GITHUB_TOKEN', 'VULTR_API_KEY', 'DDNS_API_KEY'])
+      expect(scopeReceivesKey(key, 'cron'), key).to.equal(true);
+  });
+
+  it('projects nothing a workload does not consume', () => {
+    // Regression: projecting a key path made the SSH resolver prefer a host path that does not
+    // exist in a pod over the Secret volume that holds the actual key.
+    for (const key of ['DEFAULT_SSH_KEY_PATH', 'VULTR_SSH_KEY_PATH', 'GITHUB_BACKUP_REPO', 'GITHUB_DNS_REPO'])
+      expect(scopeReceivesKey(key, 'cron'), key).to.equal(false);
+  });
+
+  it('names every entitled key in the table, so the policy reads without inference', () => {
+    for (const key of SCOPE_ENTITLEMENTS.cron) expect(configOwnershipFactory(key), key).to.not.equal(null);
+    expect(
+      Object.keys(scopeValuesFactory(Object.fromEntries(SCOPE_ENTITLEMENTS.cron.map((k) => [k, 'v'])), 'cron')),
+    ).to.have.lengthOf(SCOPE_ENTITLEMENTS.cron.length);
+  });
+});
+
+describe('the host domain has one durable source per scope', () => {
+  // A migrated node has no `engine-private` checkout to assert against in every environment this
+  // suite runs in (CI, a fresh clone), so the migrated state is a fixture rather than the real
+  // filesystem — the deterministic path the project's testing guidance asks for, and immune to
+  // whatever an operator has actually done to this box's private tree.
+  const SCOPES_DIR = './engine-private/deploy/scopes';
+  const LEGACY_SOURCE = './engine-private/conf/dd-cron/.env.production';
+
+  const migratedNodeFixture = () => {
+    const table = new Map([
+      [`${SCOPES_DIR}/host.env.production`, 'GITHUB_TOKEN=host-github\n'],
+      [`${SCOPES_DIR}/cron.env.production`, 'DDNS_API_KEY=cron-ddns\n'],
+      [`${SCOPES_DIR}/app.env.production`, 'DB_PASSWORD=app-secret\n'],
+    ]);
+    const modes = new Map([...table.keys()].map((path) => [path, 0o600]));
+    vi.spyOn(fs, 'existsSync').mockImplementation((filePath) => table.has(`${filePath}`));
+    vi.spyOn(fs, 'readFileSync').mockImplementation((filePath) => {
+      const key = `${filePath}`;
+      if (!table.has(key)) throw Object.assign(new Error(`ENOENT: ${key}`), { code: 'ENOENT' });
+      return table.get(key);
+    });
+    vi.spyOn(fs, 'writeFileSync').mockImplementation((filePath, value) => {
+      const key = `${filePath}`;
+      table.set(key, `${value}`);
+      if (!modes.has(key)) modes.set(key, 0o644);
+    });
+    vi.spyOn(fs, 'mkdirpSync').mockImplementation(() => undefined);
+    vi.spyOn(fs, 'chmodSync').mockImplementation((filePath, mode) => modes.set(`${filePath}`, mode));
+    vi.spyOn(fs, 'statSync').mockImplementation((filePath) => ({ mode: modes.get(`${filePath}`) ?? 0o644 }));
+    vi.spyOn(fs, 'removeSync').mockImplementation((filePath) => table.delete(`${filePath}`));
+    return { table, modes };
+  };
+
+  beforeEach(() => migratedNodeFixture());
+  afterEach(() => vi.restoreAllMocks());
+
+  it('reads the scoped sources and needs no unsplit file', () => {
+    // The migration has run in this tree: the scoped sources answer for the whole environment and
+    // the file they were split from is gone.
+    expect(UnderpostHost.API.hasDualSource('production')).to.equal(false);
+    expect(fs.existsSync(UnderpostHost.API.envPath('production'))).to.equal(false);
+    expect(UnderpostHost.API.scopedSources('production').length).to.be.greaterThan(0);
+    expect(Object.keys(UnderpostHost.API.read('production')).length).to.be.greaterThan(0);
+    expect(UnderpostHost.API.sourceLabel('production')).to.include('/scopes/');
+  });
+
+  it('keeps every scoped source unreadable to anyone but its owner', () => {
+    for (const { path } of UnderpostHost.API.scopedSources('production'))
+      expect(fs.statSync(path).mode & 0o777, path).to.equal(0o600);
+  });
+
+  it('retires nothing while an unsplit source is unaccounted for, and is idempotent once it is', () => {
+    expect(UnderpostHost.API.retireLegacySource({ env: 'production' })).to.include({ reason: 'already retired' });
+  });
+
+  // Regression: after retirement these read a file that no longer exists, so `host setup` — which
+  // composes them — threw on every migrated node. The finished state of a migration is not a
+  // broken configuration. Asserted on the two operations rather than through `setup`, whose
+  // `load` rewrites the host store once per key and belongs to no timing budget here.
+  it('reruns on a migrated node with the legacy source gone', () => {
+    expect(fs.existsSync(LEGACY_SOURCE)).to.equal(false);
+    expect(() => UnderpostHost.API.split({ env: 'production' })).to.not.throw();
+    expect(UnderpostHost.API.split({ env: 'production' }).written).to.deep.equal([]);
+    expect(UnderpostHost.API.verifySplit({ env: 'production' }).ok).to.equal(true);
+    expect(UnderpostHost.API.hasDualSource('production')).to.equal(false);
+  });
+
+  it('keeps 0600 across a re-split', () => {
+    UnderpostHost.API.split({ env: 'production' });
+    for (const { path } of UnderpostHost.API.scopedSources('production'))
+      expect(fs.statSync(path).mode & 0o777, path).to.equal(0o600);
+  });
+
+  it('refuses to place a key no scope claims rather than parking it somewhere', () => {
+    expect(() => UnderpostHost.API.writeScopes({ TOTALLY_NEW_CREDENTIAL: 'x' }, { dryRun: true })).to.throw(
+      'belong to no scope',
+    );
+  });
+});

package/test/integration/infra/1-security/container-storage.test.js

@@ -0,0 +1,356 @@
+'use strict';
+
+import { expect } from 'chai';
+import ContainerStorageService, {
+  absoluteStoragePaths,
+  assertSafeStoragePaths,
+  isSafeStoragePath,
+  containerStorageCommandsFactory,
+  containerStorageRootsFactory,
+  containerStorageSubtreeCommandsFactory,
+  coveringRootFactory,
+  ensureContainerStorage,
+  ensureContainerStorageSubtree,
+  localPathConfigCommandFactory,
+  localPathRootsFactory,
+  normalizeStorageRoots,
+  storageDirectoryCommandFactory,
+} from '../../../../src/server/security/container-storage.js';
+import { MongoBootstrap } from '../../../../src/db/mongo/MongoBootstrap.js';
+
+const collect = (paths, options = {}) => {
+  const executed = [];
+  ensureContainerStorage(paths, { execute: (command) => executed.push(command), ...options });
+  return executed;
+};
+
+const mappedRoots = (commands) =>
+  commands
+    .filter((command) => command.includes('semanage fcontext -a'))
+    .map((command) => /semanage fcontext -a -t \S+ '([^']+)\(\/\.\*\)\?'/.exec(command)[1]);
+
+const restoredPaths = (commands) => {
+  const restore = commands.find((command) => command.includes('restorecon'));
+  return restore ? [...restore.matchAll(/restorecon -RF '([^']+)'/g)].map((match) => match[1]) : [];
+};
+
+const createdPaths = (commands) =>
+  commands.filter((command) => command.startsWith('[ -d ')).map((command) => /^\[ -d '([^']+)'/.exec(command)[1]);
+
+describe('Container storage SELinux preparation', () => {
+  it('exposes one canonical class API with named factory aliases', () => {
+    expect(ContainerStorageService.containerStorageCommandsFactory).to.equal(containerStorageCommandsFactory);
+    expect(ContainerStorageService.SHARED_CONTAINER_TYPE).to.equal('container_file_t');
+  });
+
+  describe('path normalization', () => {
+    it('keeps only absolute paths, deduplicated and ordered parents first', () => {
+      expect(absoluteStoragePaths(['/data/mongodb', '/data', 'relative/path', '', '/data/', null])).to.deep.equal([
+        '/data',
+        '/data/mongodb',
+      ]);
+    });
+
+    it('collapses descendants into the covering root', () => {
+      expect(normalizeStorageRoots(['/data/mongodb/v0', '/data', '/opt/local-path-provisioner'])).to.deep.equal([
+        '/data',
+        '/opt/local-path-provisioner',
+      ]);
+    });
+
+    it('never collapses a sibling that merely shares a prefix', () => {
+      expect(normalizeStorageRoots(['/data', '/database'])).to.deep.equal(['/data', '/database']);
+    });
+
+    it('refuses to treat / as a storage root', () => {
+      expect(normalizeStorageRoots(['/'])).to.deep.equal([]);
+      expect(() => containerStorageCommandsFactory(['/'])).to.throw(TypeError);
+      expect(() => containerStorageCommandsFactory([])).to.throw(TypeError);
+    });
+
+    it('resolves the longest declared root covering a path', () => {
+      expect(coveringRootFactory('/data/mongodb/v0')).to.equal('/data');
+      expect(coveringRootFactory('/data/mongodb/v0', ['/data', '/data/mongodb'])).to.equal('/data/mongodb');
+      expect(coveringRootFactory('/srv/unmapped')).to.equal('/srv/unmapped');
+    });
+  });
+
+  describe('system path protection', () => {
+    it('refuses a directory that is a system location in its own right', () => {
+      for (const path of ['/', '/opt', '/usr', '/var', '/home', '/etc', '/var/lib'])
+        expect(isSafeStoragePath(path), path).to.equal(false);
+    });
+
+    it('refuses the CNI plugin directory, which a pod mounts but which holds executables', () => {
+      expect(isSafeStoragePath('/opt/cni/bin')).to.equal(false);
+      expect(isSafeStoragePath('/opt/cni')).to.equal(false);
+    });
+
+    it('refuses anything inside a tree that can never hold container storage', () => {
+      for (const path of ['/usr/bin', '/etc/passwd', '/lib64/x', '/proc/1', '/sys/fs', '/boot/grub'])
+        expect(isSafeStoragePath(path), path).to.equal(false);
+    });
+
+    it('allows a storage tree living under a system location', () => {
+      for (const path of ['/opt/local-path-provisioner', '/data', '/data/mongodb', '/home/dd/engine/volume/pv-x'])
+        expect(isSafeStoragePath(path), path).to.equal(true);
+    });
+
+    it('allows only the hardcoded kubeadm control-plane mounts to break the prefix rule', () => {
+      for (const path of ContainerStorageService.CONTROL_PLANE_MOUNT_PATHS)
+        expect(isSafeStoragePath(path), path).to.equal(true);
+      expect(isSafeStoragePath('/etc/kubernetes-other')).to.equal(false);
+    });
+
+    it('throws at the command boundary rather than emitting a relabel for a system path', () => {
+      expect(() => containerStorageCommandsFactory(['/data', '/opt/cni/bin'])).to.throw(RangeError, '/opt/cni/bin');
+      expect(() => containerStorageSubtreeCommandsFactory('/usr/bin')).to.throw(RangeError, '/usr/bin');
+      expect(() => assertSafeStoragePaths(['/opt'])).to.throw(RangeError);
+    });
+
+    it('refuses a safe subtree whose covering root is not itself safe', () => {
+      expect(() => containerStorageSubtreeCommandsFactory('/opt/cni/bin/plugins', { roots: ['/opt/cni'] })).to.throw(
+        RangeError,
+      );
+    });
+
+    it('keeps every declared platform root safe', () => {
+      for (const root of ContainerStorageService.PLATFORM_STORAGE_ROOTS)
+        expect(isSafeStoragePath(root), root).to.equal(true);
+      expect(isSafeStoragePath(ContainerStorageService.LOCAL_PATH_DEFAULT_ROOT)).to.equal(true);
+    });
+  });
+
+  describe('local-path provisioner discovery', () => {
+    it('reads the node roots out of a live provisioner config', () => {
+      const config = JSON.stringify({
+        nodePathMap: [
+          { node: 'DEFAULT_PATH_FOR_NON_LISTED_NODES', paths: ['/opt/local-path-provisioner'] },
+          { node: 'worker-1', paths: ['/srv/local-path', '/opt/local-path-provisioner'] },
+        ],
+      });
+      expect(localPathRootsFactory(config)).to.deep.equal(['/opt/local-path-provisioner', '/srv/local-path']);
+    });
+
+    it('reads a shared filesystem root', () => {
+      expect(localPathRootsFactory('{"sharedFileSystemPath":"/srv/shared"}')).to.deep.equal(['/srv/shared']);
+    });
+
+    it('degrades to an empty result rather than throwing on absent or malformed config', () => {
+      expect(localPathRootsFactory('')).to.deep.equal([]);
+      expect(localPathRootsFactory('not json')).to.deep.equal([]);
+      expect(localPathRootsFactory('{"nodePathMap":"unexpected"}')).to.deep.equal([]);
+    });
+
+    it('falls back to the upstream default root when discovery found nothing', () => {
+      expect(containerStorageRootsFactory()).to.include(ContainerStorageService.LOCAL_PATH_DEFAULT_ROOT);
+      expect(containerStorageRootsFactory({ localPathRoots: ['/srv/local-path'] })).to.include('/srv/local-path');
+      expect(containerStorageRootsFactory({ localPathRoots: ['/srv/local-path'] })).to.not.include(
+        ContainerStorageService.LOCAL_PATH_DEFAULT_ROOT,
+      );
+    });
+
+    it('includes the control-plane mount paths only when asked', () => {
+      expect(containerStorageRootsFactory()).to.not.include('/var/lib/etcd');
+      expect(containerStorageRootsFactory({ controlPlane: true })).to.include('/var/lib/etcd');
+    });
+
+    it('builds a namespace-scoped provisioner config lookup', () => {
+      expect(localPathConfigCommandFactory({ namespace: 'local-path-storage' })).to.include(
+        'kubectl get configmap local-path-config -n local-path-storage',
+      );
+      expect(() => localPathConfigCommandFactory({})).to.throw(TypeError);
+    });
+  });
+
+  describe('directory creation', () => {
+    it('creates a missing directory and leaves an existing one untouched', () => {
+      const command = storageDirectoryCommandFactory('/data/mysql');
+      expect(command).to.equal(`[ -d '/data/mysql' ] || sudo install -d -m 0755 '/data/mysql'`);
+    });
+
+    it('applies an explicit mode and owner only at creation time', () => {
+      expect(storageDirectoryCommandFactory('/data/x', { mode: '0700', owner: '999:999' })).to.equal(
+        `[ -d '/data/x' ] || sudo install -d -m 0700 -o '999' -g '999' '/data/x'`,
+      );
+    });
+
+    it('quotes paths containing shell metacharacters', () => {
+      expect(storageDirectoryCommandFactory("/data/o'hara")).to.include(`'/data/o'"'"'hara'`);
+    });
+
+    it('requires a path', () => {
+      expect(() => storageDirectoryCommandFactory('')).to.throw(TypeError);
+    });
+  });
+
+  describe('fresh deployment', () => {
+    const commands = collect(['/data', '/data/mongodb', '/data/mongodb/v0', '/opt/local-path-provisioner']);
+
+    it('creates every requested directory, including the nested volume directories', () => {
+      expect(createdPaths(commands)).to.deep.equal([
+        '/data',
+        '/data/mongodb',
+        '/data/mongodb/v0',
+        '/opt/local-path-provisioner',
+      ]);
+    });
+
+    it('registers one persistent mapping per covering root, not per volume', () => {
+      expect(mappedRoots(commands)).to.deep.equal(['/data', '/opt/local-path-provisioner']);
+    });
+
+    it('creates directories before labeling them, so nothing is relabeled out from under itself', () => {
+      const firstMapping = commands.findIndex((command) => command.includes('semanage fcontext'));
+      const lastCreate = commands.map((command) => command.startsWith('[ -d ')).lastIndexOf(true);
+      expect(lastCreate).to.be.lessThan(firstMapping);
+    });
+
+    it('restores the covering roots last, so the mapping is already in the store', () => {
+      expect(restoredPaths(commands)).to.deep.equal(['/data', '/opt/local-path-provisioner']);
+      expect(commands[commands.length - 1]).to.include('restorecon');
+    });
+
+    it('uses semanage rather than chcon, so the label survives a policy relabel', () => {
+      expect(commands.join('\n')).to.include('semanage fcontext');
+      expect(commands.join('\n')).to.not.include('chcon');
+    });
+
+    it('reports actionable remediation instead of silently skipping when semanage is absent', () => {
+      expect(commands.find((command) => command.includes('semanage fcontext'))).to.include(
+        'semanage is required for persistent file contexts',
+      );
+    });
+
+    it('no-ops entirely on a host without SELinux', () => {
+      for (const command of commands.filter((entry) => entry.includes('semanage')))
+        expect(command).to.include('selinuxenabled');
+      for (const command of commands.filter((entry) => entry.includes('restorecon')))
+        expect(command).to.include('command -v restorecon');
+    });
+  });
+
+  describe('redeployment', () => {
+    it('emits an identical command list on a repeat run', () => {
+      const first = collect(['/data', '/opt/local-path-provisioner']);
+      const second = collect(['/data', '/opt/local-path-provisioner']);
+      expect(second).to.deep.equal(first);
+    });
+
+    it('is order-independent, so a caller cannot change the applied state by reordering', () => {
+      expect(collect(['/opt/local-path-provisioner', '/data'])).to.deep.equal(
+        collect(['/data', '/opt/local-path-provisioner']),
+      );
+    });
+
+    it('adds the mapping when absent and amends it when present, never failing on either', () => {
+      const mapping = collect(['/data']).find((command) => command.includes('semanage fcontext'));
+      expect(mapping).to.include('semanage fcontext -a -t container_file_t');
+      expect(mapping).to.include('semanage fcontext -m -t container_file_t');
+    });
+  });
+
+  describe('existing persistent data', () => {
+    it('never re-modes, re-owns or removes a directory that already exists', () => {
+      const commands = collect(['/data/mongodb/v0']);
+      expect(commands.filter((command) => /(^|[^-])\bchmod\b/.test(command))).to.deep.equal([]);
+      expect(commands.filter((command) => /\bchown\b/.test(command))).to.deep.equal([]);
+      expect(commands.filter((command) => /\brm\b/.test(command))).to.deep.equal([]);
+      expect(commands.filter((command) => command.startsWith('[ -d '))).to.have.length(1);
+    });
+
+    it('relabels a data subtree without registering a mapping for it', () => {
+      const commands = containerStorageSubtreeCommandsFactory('/home/dd/engine/volume/pv-app-production-blue');
+      expect(mappedRoots(commands)).to.deep.equal(['/home/dd/engine/volume']);
+      expect(restoredPaths(commands)).to.deep.equal(['/home/dd/engine/volume/pv-app-production-blue']);
+      expect(createdPaths(commands)).to.deep.equal([]);
+    });
+
+    it('maps an uncovered subtree at its own path rather than leaving it unmapped', () => {
+      expect(mappedRoots(containerStorageSubtreeCommandsFactory('/srv/external-volume'))).to.deep.equal([
+        '/srv/external-volume',
+      ]);
+    });
+
+    it('collapses many volumes of one root into a single mapping and a single restore', () => {
+      const commands = containerStorageSubtreeCommandsFactory([
+        '/home/dd/engine/volume/pv-a',
+        '/home/dd/engine/volume/pv-b',
+        '/home/dd/engine/volume',
+      ]);
+      expect(mappedRoots(commands)).to.deep.equal(['/home/dd/engine/volume']);
+      expect(restoredPaths(commands)).to.deep.equal(['/home/dd/engine/volume']);
+    });
+
+    it('skips a restore whose target does not exist instead of failing the deploy', () => {
+      expect(restoredPaths(containerStorageSubtreeCommandsFactory('/data/absent'))).to.deep.equal(['/data/absent']);
+      const restore = containerStorageSubtreeCommandsFactory('/data/absent').find((command) =>
+        command.includes('restorecon'),
+      );
+      expect(restore).to.include(`[ ! -e '/data/absent' ] ||`);
+    });
+  });
+
+  describe('failure and recovery paths', () => {
+    it('requires an executor rather than silently doing nothing', () => {
+      expect(() => ensureContainerStorage('/data', {})).to.throw(TypeError);
+      expect(() => ensureContainerStorageSubtree('/data', {})).to.throw(TypeError);
+    });
+
+    it('rejects an empty or relative target', () => {
+      expect(() => containerStorageSubtreeCommandsFactory([])).to.throw(TypeError);
+      expect(() => containerStorageSubtreeCommandsFactory(['relative'])).to.throw(TypeError);
+    });
+
+    it('drops sudo when already running as root on the node', () => {
+      const commands = containerStorageCommandsFactory(['/data'], { sudo: false });
+      expect(commands.join('\n')).to.not.include('sudo ');
+    });
+
+    it('propagates an executor failure instead of reporting success', () => {
+      expect(() =>
+        ensureContainerStorage('/data', {
+          execute: () => {
+            throw new Error('semanage failed');
+          },
+        }),
+      ).to.throw('semanage failed');
+    });
+  });
+
+  describe('MongoDB replica data root', () => {
+    it('prepares the root and one directory per member', () => {
+      expect(MongoBootstrap.prepareReplicaDataRoot(3, { execute: () => {} })).to.deep.equal([
+        '/data/mongodb',
+        '/data/mongodb/v0',
+        '/data/mongodb/v1',
+        '/data/mongodb/v2',
+      ]);
+    });
+
+    it('creates every member directory but maps only /data', () => {
+      const executed = [];
+      MongoBootstrap.prepareReplicaDataRoot(3, { execute: (command) => executed.push(command) });
+      expect(createdPaths(executed)).to.deep.equal([
+        '/data/mongodb',
+        '/data/mongodb/v0',
+        '/data/mongodb/v1',
+        '/data/mongodb/v2',
+      ]);
+      expect(mappedRoots(executed)).to.deep.equal(['/data']);
+      expect(restoredPaths(executed)).to.deep.equal(['/data/mongodb']);
+    });
+
+    it('leaves ownership and mode of an existing member directory to the init container', () => {
+      const executed = [];
+      MongoBootstrap.prepareReplicaDataRoot(1, { execute: (command) => executed.push(command) });
+      expect(executed.join('\n')).to.not.include('chown');
+      expect(executed.join('\n')).to.not.match(/(^|\s)chmod\s/);
+    });
+
+    it('tolerates a zero or unparsable replica count without emitting a bad path', () => {
+      expect(MongoBootstrap.prepareReplicaDataRoot(0, { execute: () => {} })).to.deep.equal(['/data/mongodb']);
+      expect(MongoBootstrap.prepareReplicaDataRoot(undefined, { execute: () => {} })).to.deep.equal(['/data/mongodb']);
+    });
+  });
+});