@eliware/vyops 1.0.13 → 2.1.0

package/README.md

@@ -4,7 +4,8 @@
 
 ## Features
 
-- SSH-key authentication via `ssh2`, with optional password bootstrap via stdin.
+- SSH-key authentication via the shared `@eliware/ssh-client` library, with
+  optional password bootstrap via stdin.
 - Native VyOS curly-brace configuration validation.
 - Candidate load, `compare`, `commit-confirm`, confirmation, and save.
 - Complete `scripts/` tree synchronization, including post-commit hooks,
@@ -27,7 +28,7 @@ npm install
 The package provides:
 
 ```text
-vyops   Deploy or dry-run a configuration.
+vyops   Preflight or release a configuration bundle.
 ```
 
 ## Configuration
@@ -35,42 +36,54 @@ vyops   Deploy or dry-run a configuration.
 | Variable | Required | Default | Purpose |
 |---|---|---|---|
 | `VYOPS_SSH_KEY` | No | `$HOME/.ssh/id_rsa` | Private SSH key path. |
-| `SSH_AUTH_SOCK` | No | unset | SSH agent socket passed to `ssh2`. |
+| `SSH_AUTH_SOCK` | No | unset | SSH agent socket passed to the shared SSH client. |
+| `SSH_KNOWN_HOSTS` | No | `~/.ssh/known_hosts` | Known-hosts file used for host verification. |
+| `SSH_HOST_CA` | No | unset | Trusted SSH host-CA public key for certificate verification. |
 | `LOG_LEVEL` | No | `info` | Winston log level (`error`, `warn`, `info`, `http`, `verbose`, `debug`, or `silly`). |
 
-The target must be supplied as `user@host`. The config must use native VyOS curly-brace syntax.
+The config must use native VyOS curly-brace syntax. The bundle's `system host-name`
+and single `system login user` entry provide the release target automatically.
 
 For a router that has not received its SSH key yet, provide the SSH password through stdin:
 
 ```sh
-printf '%s\n' "$VYOS_PASSWORD" | vyops --password-stdin vyos@new-router config.boot
+printf '%s\n' "$VYOS_PASSWORD" | vyops release --password-stdin /path/to/config.boot
 ```
 
 Password mode still requires the target host key to be present in `known_hosts`; it does not disable host verification. Passwords are not accepted as command-line arguments or written to logs.
 
 ## Usage
 
-Deploy:
+Preflight a bundle without connecting:
 
 ```sh
-./vyops.mjs vyos@core1 /path/to/config.boot
+vyops preflight /path/to/config.boot
+```
+
+Release a bundle:
+
+```sh
+vyops release /path/to/config.boot
 ```
 
 Console switches:
 
 ```sh
-./vyops.mjs --help
-./vyops.mjs --version
-./vyops.mjs --dry-run vyos@core1 /path/to/config.boot
-./vyops.mjs --force --debug vyos@core1 /path/to/config.boot
-./vyops.mjs --backup vyos@core1 /path/to/backup
+vyops --help
+vyops --version
+vyops --debug preflight /path/to/config.boot
+vyops release --force --debug /path/to/config.boot
+vyops backup vyos@core1 /path/to/backup
 ```
 
-`--backup` downloads the active `/config/config.boot` and the complete
+`backup` downloads the active `/config/config.boot` and the complete
 `/config/scripts` tree into the destination directory. It does not enter
 configuration mode or modify the router.
 
-`--dry-run` validates the config and skips SSH, commit, save, download, and Git pushback.
+`preflight` validates the config and recursively checks the `scripts/` tree before
+any SSH connection. Executable scripts must use LF line endings, a supported
+shell shebang, and valid executable intent. `release` runs the same checks before
+uploading or changing the router.
 
 The deployment workflow:
 

package/RELEASE_NOTES.md

@@ -1,12 +1,40 @@
 # Release Notes
 
-## Unreleased
-
+## 2.1.0
+
+- **Breaking:** Replace the legacy positional deployment and `--dry-run`
+  workflows with the first-class `preflight`, `release`, and `backup`
+  commands.
+- Add bundle preflight validation for recursively synchronized scripts,
+  including CRLF detection, shell shebang validation, and executable intent.
+- Derive the release SSH target from the configuration's `system host-name`
+  and single `system login user` entry.
+- Normalize executable script deployment permissions to `0755` and clean up
+  script staging after post-commit synchronization failures.
+- Allow command switches such as `--debug` and `--password-stdin` before or
+  after the command name.
+
+## 2.0.0
+
+- **Breaking:** Replace the direct `ssh2` integration with the shared
+  `@eliware/ssh-client` library for SSH, SFTP, interactive sessions, and
+  SSH host-CA verification.
+- Update `@eliware/ssh-client` to 2.0.0 and `@eliware/test` to 2.0.0.
+- Add cross-platform Windows and Ubuntu CI validation, including package,
+  audit, lint, and CLI smoke checks.
 - Close SFTP channels after uploads and downloads to prevent SSH channel exhaustion during script synchronization.
 - Reconnect after interactive deployments before downloading live configuration and cleaning up remote files.
 - Make Git path handling and the `test:gaps` coverage command portable across Windows and Linux.
 - Expand Windows and real-VyOS integration coverage to maintain 100% statements, branches, functions, and lines coverage.
 
+Verification:
+
+- `npm test` (100% coverage across statements, branches, functions, and lines)
+- `npm run lint`
+- `npm audit --omit=dev --audit-level=moderate`
+- `npm run validate:package`
+- CLI smoke test on Ubuntu and Windows
+
 ## 1.0.11
 
 - Fix VyOS 1.5 `commit-confirm` handling by answering confirmation prompts

package/package.json

@@ -1,13 +1,12 @@
 {
     "name": "@eliware/vyops",
-    "version": "1.0.13",
-    "description": "Deploy native VyOS configuration files over SSH.",
+    "version": "2.1.0",
+    "description": "Preflight, release, and back up native VyOS configuration bundles over SSH.",
     "main": "vyops.mjs",
     "scripts": {
-        "lint": "npx oxlint .",
-        "test": "npx --node-options=\"--experimental-vm-modules --no-warnings\" jest --detectOpenHandles --silent --coverage",
-        "deploy": "./vyops.mjs",
-        "test:gaps": "node scripts/test-gaps.mjs",
+        "lint": "eliware-test --lint",
+        "test": "eliware-test",
+        "deploy": "node vyops.mjs",
         "pack": "npm pack --dry-run",
         "validate:package": "npm pack --dry-run --json | node scripts/validate-package.mjs",
         "audit": "node scripts/audit.mjs"
@@ -22,11 +21,10 @@
     "type": "module",
     "dependencies": {
         "@eliware/common": "^1.1.8",
-        "ssh2": "^1.17.0"
+        "@eliware/ssh-client": "^2.0.0"
     },
     "devDependencies": {
-        "jest": "^30.4.2",
-        "oxlint": "^1.79.0"
+        "@eliware/test": "^2.0.0"
     },
     "bin": {
         "vyops": "./bin/vyops"

package/src/args.mjs

@@ -1,16 +1,18 @@
 export const usage = `Usage:
-  vyops [--dry-run] [--force] [--debug] [--password-stdin] <user@hostname-or-ip> <config.boot>
-  vyops --backup [--debug] [--password-stdin] <user@hostname-or-ip> <destination-directory>
+  vyops preflight <config.boot>
+  vyops release [--force] [--debug] [--password-stdin] <config.boot>
+  vyops backup [--debug] [--password-stdin] <user@hostname-or-ip> <destination-directory>
   vyops --help
   vyops --version`;
 
 export function parseArgs(argv) {
   if (argv.length === 1 && argv[0] === '--help') return { help: true };
   if (argv.length === 1 && argv[0] === '--version') return { version: true };
-
+  const command = argv.find(value => !value.startsWith('--'));
+  if (!['preflight', 'release', 'backup'].includes(command)) throw new Error(usage);
   const options = new Set(argv.filter(value => value.startsWith('--')));
-  if ([...options].some(option => !['--dry-run', '--force', '--debug', '--backup', '--password-stdin'].includes(option))) throw new Error(usage);
-  const values = argv.filter(value => !value.startsWith('--'));
-  if (values.length !== 2) throw new Error(usage);
-  return { target: values[0], config: values[1], ...(options.has('--backup') ? { backup: true } : {}), ...(options.has('--dry-run') ? { dryRun: true } : {}), ...(options.has('--force') ? { force: true } : {}), ...(options.has('--debug') ? { debug: true } : {}), ...(options.has('--password-stdin') ? { passwordStdin: true } : {}) };
+  const values = argv.filter(value => !value.startsWith('--')).slice(1);
+  const allowed = command === 'release' ? ['--force', '--debug', '--password-stdin'] : ['--debug', '--password-stdin'];
+  if ([...options].some(option => !allowed.includes(option)) || values.length !== (command === 'backup' ? 2 : 1)) throw new Error(usage);
+  return { command, ...(command === 'backup' ? { target: values[0], config: values[1] } : { config: values[0] }), ...(options.has('--force') ? { force: true } : {}), ...(options.has('--debug') ? { debug: true } : {}), ...(options.has('--password-stdin') ? { passwordStdin: true } : {}) };
 }

package/src/bundle.mjs

@@ -0,0 +1,43 @@
+import { promises as fs } from 'node:fs';
+import { join, relative } from 'node:path';
+
+async function filesIn(directory, root = directory) {
+  const result = [];
+  let entries;
+  try { entries = await fs.readdir(directory, { withFileTypes: true }); }
+  catch (error) { if (error.code === 'ENOENT') return result; throw error; }
+  for (const entry of entries) {
+    const file = join(directory, entry.name);
+    if (entry.isDirectory()) result.push(...await filesIn(file, root));
+    else if (entry.isFile()) result.push({ file, name: relative(root, file).replaceAll('\\', '/') });
+  }
+  return result;
+}
+
+export function targetFromConfig(text) {
+  const host = text.match(/(?:^|\n)\s*host-name\s+(?:"([^"]+)"|'([^']+)'|(\S+))/)?.slice(1).find(Boolean);
+  const users = [...text.matchAll(/(?:^|\n)\s*user\s+([A-Za-z0-9._-]+)\s*\{/g)].map(match => match[1]);
+  if (!host) throw new Error('preflight failed: config does not define system host-name');
+  if (users.length !== 1) throw new Error(`preflight failed: expected exactly one system login user; found ${users.length}`);
+  return `${users[0]}@${host}`;
+}
+
+function scriptError(name, message) { throw new Error(`preflight failed: scripts/${name} ${message}`); }
+
+export async function validateBundle(config, text, { extractTarget = true } = {}) {
+  const scripts = await filesIn(join(config, '..', 'scripts'));
+  for (const { file, name } of scripts) {
+    const data = await fs.readFile(file);
+    const firstLine = data.toString('utf8').split(/\n/, 1)[0].replace(/\r$/, '');
+    const executable = firstLine.startsWith('#!') || /(?:\.sh|\.script)$/.test(name)
+      || /^(?:commit\/post-hooks\.d\/|vyos-(?:pre|post)config-bootup\.script$)/.test(name);
+    if (!executable) continue;
+    if (data.includes(13)) scriptError(name, 'uses CRLF line endings; convert to LF');
+    if (!firstLine.startsWith('#!')) scriptError(name, 'is executable but has no shebang');
+    const interpreter = firstLine.slice(2).trim().split(/\s+/, 1)[0];
+    if (!['/bin/sh', '/bin/bash', '/bin/vbash', '/usr/bin/env'].includes(interpreter)) {
+      scriptError(name, `uses unsupported interpreter ${interpreter}`);
+    }
+  }
+  return { ...(extractTarget ? { target: targetFromConfig(text) } : {}), scripts };
+}

package/src/deploy.mjs

@@ -1,4 +1,6 @@
 import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { readFile as readLocalFile } from 'node:fs/promises';
 import { fs, path as eliwarePath, log } from '@eliware/common';
 import { close, connect, download, exec, interactive, upload } from './ssh.mjs';
 
@@ -15,7 +17,7 @@ async function listScripts(directory, relative = '') {
   const entries = await fs.promises.readdir(directory, { withFileTypes: true });
   const files = [];
   for (const entry of entries) {
-    const path = relative ? eliwarePath(relative, entry.name) : entry.name;
+    const path = (relative ? eliwarePath(relative, entry.name) : entry.name).replaceAll(String.fromCharCode(92), '/');
     if (entry.isDirectory?.()) {
       files.push(...await listScripts(eliwarePath(directory, entry.name), path));
     } else if (entry.isFile?.()) {
@@ -49,14 +51,24 @@ async function installScripts(client, config, log, runId) {
       const remote = `${remoteDir}/${name}`;
       const installed = `${installDir}/${name}`;
       const backup = `${backupDir}/${name}`;
-      const parent = eliwarePath(name, '..');
-      const mode = (await fs.promises.stat(local)).mode & 0o777;
+      const parent = eliwarePath(name, '..').replaceAll(String.fromCharCode(92), '/');
+      let content = Buffer.alloc(0);
+      try { content = await readLocalFile(local); }
+      /* istanbul ignore next -- missing files are only possible with a mocked directory listing. */
+      catch (error) {
+        /* istanbul ignore next -- missing files are only possible with a mocked directory listing. */
+        if (error.code !== 'ENOENT') throw error;
+      }
+      const mode = content.toString('utf8').startsWith('#!') || /\.(?:sh|script)$/.test(name)
+        || /^(?:commit[/\\]post-hooks\.d[/\\])/.test(name)
+        ? 0o755
+        : (await fs.promises.stat(local)).mode & 0o777;
       const backedUp = await exec(client, `if sudo test -e ${JSON.stringify(installed)}; then sudo mkdir -p ${JSON.stringify(`${backupDir}/${parent}`)} && sudo cp -p -- ${JSON.stringify(installed)} ${JSON.stringify(backup)}; fi`);
       if (backedUp.code !== 0) throw new Error(`script backup failed (${name}): ${backedUp.stderr || backedUp.stdout}`.trim());
       if (parent !== '.') {
         const remoteParent = `${remoteDir}/${parent}`;
         const remoteParentResult = await exec(client, `mkdir -p ${JSON.stringify(remoteParent)}`);
-        if (remoteParentResult.code !== 0) throw new Error(`script upload directory setup failed (${name}): ${remoteParentResult.stderr || remoteParentResult.stdout}`.trim());
+        if (remoteParentResult.code !== 0) throw new Error(`script upload directory setup failed (${join(parent, name.slice(parent.length + 1))}): ${remoteParentResult.stderr || remoteParentResult.stdout}`.trim());
       }
       await upload(client, local, remote);
       const installedResult = await exec(client, `sudo mkdir -p ${JSON.stringify(`${installDir}/${parent}`)} && sudo install -m ${mode.toString(8)} ${JSON.stringify(remote)} ${JSON.stringify(installed)}`);
@@ -123,7 +135,10 @@ export async function deploy({ target, config, password }) {
     }
     return 0;
   } catch (error) {
-    if (finalizeHooks && !hooksFinalized && !deploymentCommitted) await finalizeHooks(false, client);
+    if (finalizeHooks && !hooksFinalized) {
+      await finalizeHooks(deploymentCommitted, client);
+      hooksFinalized = true;
+    }
     throw error;
   } finally {
     debugLog('cleaning up remote file');

package/src/git.mjs

@@ -1,5 +1,6 @@
 import { execFile } from 'node:child_process';
 import { promises as fs } from 'node:fs';
+import { relative, resolve } from 'node:path';
 import { promisify } from 'node:util';
 import { path } from '@eliware/common';
 
@@ -59,6 +60,14 @@ function configDirectory(config) {
   return path(config, '..');
 }
 
+async function relativeConfigPath(repo, config) {
+  const [canonicalRepo, canonicalConfig] = await Promise.all([
+    fs.realpath(repo),
+    fs.realpath(resolve(config)),
+  ]);
+  return relative(canonicalRepo, canonicalConfig);
+}
+
 async function repositoryRoot(config) {
   try {
     const { stdout } = await git(['rev-parse', '--show-toplevel'], configDirectory(config));
@@ -72,8 +81,8 @@ async function repositoryRoot(config) {
 export async function shouldSkip(config) {
   const repo = await repositoryRoot(config);
   if (!repo) return false;
-  const relative = config.startsWith(repo) ? config.slice(repo.length).replace(/^[/\\]/, '') : config;
-  const { stdout: status } = await git(['status', '--porcelain', '--', relative], repo);
+  const relativePath = await relativeConfigPath(repo, config);
+  const { stdout: status } = await git(['status', '--porcelain', '--', relativePath], repo);
   if (status.trim()) return false;
   const { stdout: subject } = await git(['log', '-1', '--format=%s'], repo);
   return subject.trim().startsWith('Pushback ');
@@ -83,12 +92,12 @@ export async function pushBack(config, { force = false } = {}) {
   const repo = await repositoryRoot(config);
   if (!repo) return false;
   return withRepositoryLock(repo, async () => {
-    const relative = config.startsWith(repo) ? config.slice(repo.length).replace(/^[/\\]/, '') : config;
-    const { stdout: diff } = await git(['diff', 'HEAD', '--', relative], repo);
+    const relativePath = await relativeConfigPath(repo, config);
+    const { stdout: diff } = await git(['diff', 'HEAD', '--', relativePath], repo);
     if (!diff) return false;
-    await git(['add', '--', relative], repo);
+    await git(['add', '--', relativePath], repo);
     const timestamp = new Date().toISOString().replace('T', ' ').slice(0, 19);
-    await git(['commit', '--only', '-m', `Pushback ${timestamp}`, '--', relative], repo);
+    await git(['commit', '--only', '-m', `Pushback ${timestamp}`, '--', relativePath], repo);
     await git(['push'], repo);
     return true;
   }, force);

package/src/main.mjs

@@ -3,6 +3,7 @@ import packageJson from '../package.json' with { type: 'json' };
 import { deploy } from './deploy.mjs';
 import { backup } from './backup.mjs';
 import { readAndValidateConfig } from './validate.mjs';
+import { validateBundle, targetFromConfig } from './bundle.mjs';
 import { pushBack, shouldSkip } from './git.mjs';
 import { closeAll } from './ssh.mjs';
 import { log, registerHandlers, registerSignals } from '@eliware/common';
@@ -31,18 +32,26 @@ try {
     args.password = await readPasswordStdin();
     if (!args.password) throw new Error('password-stdin received an empty password');
   }
-  if (args.backup) {
+  if (args.command === 'backup') {
     await backup(args);
     log.info(`Backup successful: ${args.config}`);
     process.exit(0);
   }
-  log.debug(`[vyops] validating config: ${args.config}`);
-  await readAndValidateConfig(args.config);
-  log.debug('[vyops] config validation complete');
-  if (args.dryRun) {
-    log.info(`Configuration valid; dry run for ${args.target}`);
+  if (args.command === 'preflight') {
+    const text = await readAndValidateConfig(args.config);
+    const { target, scripts } = await validateBundle(args.config, text);
+    log.info(`Preflight successful: ${target} (${scripts.length} script files)`);
     process.exit(0);
   }
+  if (args.command === 'release') {
+    const text = await readAndValidateConfig(args.config);
+    await validateBundle(args.config, text);
+    args.target = targetFromConfig(text);
+  }
+  log.debug(`[vyops] validating config: ${args.config}`);
+  const configText = await readAndValidateConfig(args.config);
+  if (args.command === 'release') await validateBundle(args.config, configText, { extractTarget: true });
+  log.debug('[vyops] config validation complete');
   if (!args.force && await shouldSkip(args.config)) {
     log.info('Latest commit is Pushback and config is unchanged; skipping deployment');
     process.exit(0);

package/src/ssh.mjs

@@ -1,8 +1,5 @@
-import { createHmac } from 'node:crypto';
 import { fs, log } from '@eliware/common';
-import ssh2 from 'ssh2';
-
-const { Client, utils } = ssh2;
+import { connect as sharedConnect } from '@eliware/ssh-client';
 
 const CONNECT_TIMEOUT = 30000;
 const OPERATION_TIMEOUT = 60000;
@@ -23,75 +20,17 @@ export function parseTarget(target) {
   return { username, host };
 }
 
-function wildcardMatch(pattern, value) {
-  const expression = `^${pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*').replace(/\?/g, '.')}$`;
-  return new RegExp(expression).test(value);
-}
-
-function hostMatches(pattern, hosts) {
-  if (pattern.startsWith('|1|')) {
-    const [, , salt, digest] = pattern.split('|');
-    if (!salt || !digest) return false;
-    return hosts.some(host => createHmac('sha1', Buffer.from(salt, 'base64')).update(host).digest('base64') === digest);
-  }
-  return hosts.some(host => wildcardMatch(pattern, host));
-}
-
-function keyMatches(expected, actual) {
-  try {
-    const parsed = utils.parseKey(`${expected.type} ${expected.data}`);
-    return parsed.getPublicSSH().equals(actual);
-  } catch {
-    return false;
-  }
-}
-
-function verifyKnownHost(host, key, knownHosts) {
-  const hosts = [host, `[${host}]:22`];
-  let matched = false;
-  for (const line of knownHosts.split(/\r?\n/)) {
-    const trimmed = line.trim();
-    if (!trimmed || trimmed.startsWith('#')) continue;
-    const fields = trimmed.split(/\s+/);
-    if (fields[0].startsWith('@')) {
-      if (fields[0] === '@revoked' && fields[1]?.split(',').some(pattern => hostMatches(pattern, hosts))) return false;
-      continue;
-    }
-    if (fields.length < 3) continue;
-    const [hostList, type, data] = fields;
-    const patterns = hostList.split(',');
-    if (patterns.some(pattern => pattern.startsWith('!') && hostMatches(pattern.slice(1), hosts))) return false;
-    if (patterns.some(pattern => !pattern.startsWith('!') && hostMatches(pattern, hosts))
-      && keyMatches({ type, data }, key)) matched = true;
-  }
-  return matched;
-}
-
 export async function connect(target, { password } = {}) {
   const { username, host } = parseTarget(target);
   log.debug(`[vyops] SSH connecting: ${username}@${host}`);
-  const privateKey = password === undefined
-    ? await fs.promises.readFile(process.env.VYOPS_SSH_KEY || `${process.env.HOME}/.ssh/id_rsa`)
-    : undefined;
-  const knownHostsPath = `${process.env.HOME}/.ssh/known_hosts`;
-  const knownHosts = await fs.promises.readFile(knownHostsPath, 'utf8');
-  return new Promise((resolve, reject) => {
-    const client = new Client();
-    client.once('ready', () => { log.debug(`[vyops] SSH connected: ${username}@${host}`); resolve(client); });
-    client.once('error', reject);
-    client.once('close', () => activeClients.delete(client));
-    activeClients.add(client);
-    client.connect({
-      host,
-      username,
-      agent: process.env.SSH_AUTH_SOCK,
-      privateKey,
-      ...(password === undefined ? {} : { password }),
-      hostVerifier: (key, callback) => callback(verifyKnownHost(host, key, knownHosts)),
-      readyTimeout: CONNECT_TIMEOUT,
-      authTimeout: CONNECT_TIMEOUT,
-    });
-  });
+  const connection = await sharedConnect({ host, username,
+    privateKeyPath: password === undefined ? (process.env.VYOPS_SSH_KEY || undefined) : undefined,
+    agent: process.env.SSH_AUTH_SOCK, knownHostsPath: process.env.SSH_KNOWN_HOSTS || '~/.ssh/known_hosts',
+    hostCaPath: process.env.SSH_HOST_CA, password, connectTimeout: CONNECT_TIMEOUT });
+  const client = connection.raw;
+  activeClients.add(client);
+  log.debug(`[vyops] SSH connected: ${username}@${host}`);
+  return client;
 }
 
 export function exec(client, command) {