@jacebenson/jsn 4.3.7-dev.34 → 4.3.7-dev.36

package/README.md

@@ -31,6 +31,19 @@ npm install -g @jacebenson/jsn
 
 **Note:** git installs build `better-sqlite3` (docs search) from source, so the machine needs build tools (Python, make, a C++ compiler).
 
+## Direct MID installation
+
+```sh
+jsn midservers add --install-method direct --name worker1
+```
+
+Official x86-64 ZIPs for Linux and Windows, selected from the instance's
+`mid.version`. Credentials are prompted and validated before installation.
+Linux supports a user-owned background runtime. Windows currently prepares
+private files and offers a foreground console, not native service registration.
+See [direct MID installation](docs/mid-direct-install.md) for security boundaries,
+lifecycle commands and the untested Windows host phases. Docker remains available.
+
 ## Quick Start
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacebenson/jsn",
-  "version": "4.3.7-dev.34",
+  "version": "4.3.7-dev.36",
   "description": "A command-line interface for ServiceNow that follows the Unix philosophy: simple, composable, and scriptable.",
   "type": "module",
   "bin": {

package/src/commands/midservers.js

@@ -1,11 +1,13 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import process from 'node:process';
 import { input, password as passwordPrompt, select } from '@inquirer/prompts';
 import { confirmDelete, formatRecordForDisplay, getStringField, interactiveList, canPrompt, assertSafeExactMatch } from '../helpers.js';
 import { FormatAuto } from '../output.js';
 import { declareCapabilities } from '../capabilities.js';
 import { resolveRecord, unwrapSysId } from '../resolve-record.js';
-import { detectDocker, defaultRun, installDockerMidServer, midInstallDirectory, validateMidCredentials } from '../midserver-install.js';
+import { detectDocker, defaultRun, installDockerMidServer, midInstallDirectory, normalizeMidName, validateMidCredentials } from '../midserver-install.js';
+import { detectDirectPlatform, installDirectMidServer, readDirectInstallation, removeDirectInstallation, runDirectInstallation } from '../midserver-direct.js';
 
 const AGENT_TABLE = 'ecc_agent';
 const QUEUE_TABLE = 'ecc_queue';
@@ -13,7 +15,7 @@ const LIST_FIELDS = ['sys_id', 'name', 'status', 'host_name', 'ip_address', 'ver
 const DEFAULT_TIMEOUT = 120000;
 const DEFAULT_INTERVAL = 2000;
 
-declareCapabilities('midservers', { mutationSubcommands: ['add', 'remove', 'execute'] });
+declareCapabilities('midservers', { mutationSubcommands: ['add', 'remove', 'execute', 'start', 'stop'] });
 
 function agentName(record) {
   const name = getStringField(record, 'name');
@@ -170,6 +172,40 @@ function midDiagnosticsCommand(kind, wrap) {
   };
 }
 
+// Progress for long, otherwise-silent direct-install phases. Human terminals
+// only, and on stderr, so the stdout envelope and --json output stay clean.
+export function directProgress(app) {
+  const human = app.output?.getFormat() === FormatAuto && (canPrompt() || process.stderr.isTTY === true);
+  if (!human) return () => {};
+  const mib = bytes => (Number(bytes || 0) / (1024 * 1024)).toFixed(0);
+  return event => {
+    if (event.phase === 'download-start') {
+      process.stderr.write(`Downloading the official MID ZIP from ServiceNow (about 532 MiB).\n  ${event.archiveURL}\n`);
+    } else if (event.phase === 'download') {
+      const percent = event.total ? ` (${Math.floor((event.received / event.total) * 100)}%)` : '';
+      process.stderr.write(`\r  ${mib(event.received)} MiB${percent} downloaded...`);
+      if (event.done) process.stderr.write('\n');
+    } else if (event.phase === 'extract-start') {
+      process.stderr.write(`Extracting ${event.entries} files into ${event.installDir}...\n`);
+    } else if (event.phase === 'extract-done') {
+      process.stderr.write('Extraction complete. Configuring the MID Server...\n');
+    }
+  };
+}
+
+// A registration wait is minutes of silence otherwise; report elapsed progress.
+export function registrationProgress(app, timeoutMs) {
+  const human = app.output?.getFormat() === FormatAuto && (canPrompt() || process.stderr.isTTY === true);
+  if (!human) return undefined;
+  const seconds = Math.round(timeoutMs / 1000);
+  let lastReport = 0;
+  return elapsedMs => {
+    if (elapsedMs - lastReport < 15000) return;
+    lastReport = elapsedMs;
+    process.stderr.write(`Waiting for ServiceNow to register the MID Server... ${Math.round(elapsedMs / 1000)}s of ${seconds}s\n`);
+  };
+}
+
 async function listAgents(app, argv) {
   const columns = argv.columns
     ? [...new Set(argv.columns.split(',').map(column => column.trim()).filter(Boolean))]
@@ -231,7 +267,7 @@ export function assertMidServerReady(record) {
   const name = getStringField(record, 'name') || getStringField(record, 'sys_id') || 'MID Server';
   const validated = queueValue(record.validated).toLowerCase();
   if (validated !== 'true') {
-    const error = new Error(`MID Server '${name}' is not validated yet (validation: ${validated || 'unknown'}). Wait for ServiceNow validation to complete before executing a command.`);
+    const error = new Error(`MID Server '${name}' is not validated yet (validation: ${validated || 'unknown'}). Use the manual Validate action in ServiceNow before executing a command.`);
     error.code = 'midserver_not_validated';
     throw error;
   }
@@ -265,15 +301,16 @@ async function promptMidCredentials(app, argv) {
   }
 }
 
-export async function waitForMidServerUp(app, name, timeoutMs, intervalMs) {
+export async function waitForMidServerUp(app, name, timeoutMs, intervalMs, onWait) {
   const started = Date.now();
   const fullName = name;
   while (Date.now() - started <= timeoutMs) {
+    onWait?.(Date.now() - started);
     const params = new URLSearchParams({
       sysparm_query: `name=${fullName}`,
       sysparm_limit: '1',
       sysparm_display_value: 'all',
-      sysparm_fields: 'sys_id,name,status,host_name,version,last_heartbeat',
+      sysparm_fields: 'sys_id,name,status,validated,host_name,version,last_heartbeat',
     });
     const records = await app.sdk.list(AGENT_TABLE, params);
     if (records[0] && getStringField(records[0], 'status').toLowerCase() === 'up') return records[0];
@@ -282,11 +319,16 @@ export async function waitForMidServerUp(app, name, timeoutMs, intervalMs) {
   throw new Error(`MID Server '${fullName}' did not report Up within ${timeoutMs}ms`);
 }
 
-function removeLocalMidServer(instanceURL, name) {
-  const installDir = midInstallDirectory(instanceURL, name);
+function removeLocalMidServer(instanceURL, name, directory) {
+  const direct = readDirectInstallation(instanceURL, name, directory);
+  if (direct) { removeDirectInstallation(direct); return true; }
+  const installDir = directory || midInstallDirectory(instanceURL, name);
   const composePath = path.join(installDir, 'docker-compose.yaml');
   const envPath = path.join(installDir, '.env');
-  if (!fs.existsSync(composePath)) return false;
+  if (!fs.existsSync(composePath)) {
+    if (fs.existsSync(path.join(installDir, 'agent'))) throw new Error('Native MID directory exists without trustworthy ownership metadata; refusing removal');
+    return false;
+  }
   const composeArgs = ['compose', ...(fs.existsSync(envPath) ? ['--env-file', envPath] : []), '-f', composePath, 'down'];
   try {
     defaultRun('docker', composeArgs, { cwd: installDir });
@@ -303,7 +345,26 @@ function removeLocalMidServer(instanceURL, name) {
 }
 
 function showMidServerLogs(app, identifier, argv) {
-  const installDir = midInstallDirectory(app.getEffectiveInstance(), identifier);
+  const installDir = argv.directory || midInstallDirectory(app.getEffectiveInstance(), identifier);
+  const direct = readDirectInstallation(app.getEffectiveInstance(), identifier, argv.directory);
+  if (direct) {
+    if (!Number.isInteger(argv.tail) || argv.tail < 1 || argv.tail > 10000) throw new Error('Use --tail between 1 and 10000');
+    if (argv.follow) throw new Error('Direct log follow is not supported; read logs again or use the native host log viewer');
+    const logfile = path.join(installDir, 'agent', 'logs', 'agent0.log');
+    if (!fs.existsSync(logfile)) throw new Error('No MID agent log yet; the installation may only be prepared');
+    const stat = fs.lstatSync(logfile);
+    if (!stat.isFile() || stat.isSymbolicLink()) throw new Error('Untrusted MID log path');
+    const fd = fs.openSync(logfile, 'r');
+    let text;
+    try {
+      const length = Math.min(stat.size, 1024 * 1024);
+      const buffer = Buffer.alloc(length);
+      fs.readSync(fd, buffer, 0, length, stat.size - length);
+      text = buffer.toString('utf8').split('\n').slice(-argv.tail).join('\n');
+    } finally { fs.closeSync(fd); }
+    app.ok({ installation: 'direct', logfile, text, _formatted: `${text}\n` }, { summary: 'Local MID agent log (last 1 MiB maximum)' });
+    return;
+  }
   const composePath = path.join(installDir, 'docker-compose.yaml');
   const envPath = path.join(installDir, '.env');
   if (!fs.existsSync(composePath)) throw new Error(`No local Compose installation found for MID Server '${identifier}'`);
@@ -349,24 +410,48 @@ export function midserversCmd(wrap) {
       })
       .command({
         command: 'logs <identifier>',
-        describe: 'Show local Docker Compose logs for a MID Server',
+        describe: 'Show local native or Docker Compose MID logs',
         builder: (b) => b
           .option('tail', { type: 'number', default: 100, describe: 'Number of log lines' })
-          .option('follow', { type: 'boolean', default: false, describe: 'Follow the logs' }),
+          .option('follow', { type: 'boolean', default: false, describe: 'Follow the logs (Compose only)' })
+          .option('directory', { type: 'string', describe: 'Local installation directory override' }),
         handler: wrap(async (argv, app) => {
           showMidServerLogs(app, argv.identifier, argv);
         }),
       })
       .command({
         command: '<identifier> logs',
-        describe: 'Show local Docker Compose logs for a MID Server',
+        describe: 'Show local native or Docker Compose MID logs',
         builder: (b) => b
           .option('tail', { type: 'number', default: 100, describe: 'Number of log lines' })
-          .option('follow', { type: 'boolean', default: false, describe: 'Follow the logs' }),
+          .option('follow', { type: 'boolean', default: false, describe: 'Follow the logs (Compose only)' })
+          .option('directory', { type: 'string', describe: 'Local installation directory override' }),
         handler: wrap(async (argv, app) => {
           showMidServerLogs(app, argv.identifier, argv);
         }),
       })
+      .command({
+        command: 'start <identifier>',
+        describe: 'Start an owned direct MID (Windows: foreground console, no service)',
+        builder: b => b.option('directory', { type: 'string', describe: 'Installation directory override' }),
+        handler: wrap(async (argv, app) => {
+          const metadata = readDirectInstallation(app.getEffectiveInstance(), argv.identifier, argv.directory);
+          if (!metadata) throw new Error('No owned direct MID installation found');
+          if (metadata.state !== 'prepared') throw new Error('MID is already started or has an uncertain runtime state; stop it first');
+          const result = runDirectInstallation(metadata, 'start');
+          app.ok(result, { summary: result.platform === 'windows' ? 'Windows MID console exited; no service was registered' : 'MID start command completed; registration and manual validation must be checked in ServiceNow' });
+        }),
+      })
+      .command({
+        command: 'stop <identifier>',
+        describe: 'Stop an owned Linux direct MID; Windows console uses Ctrl+C',
+        builder: b => b.option('directory', { type: 'string', describe: 'Installation directory override' }),
+        handler: wrap(async (argv, app) => {
+          const metadata = readDirectInstallation(app.getEffectiveInstance(), argv.identifier, argv.directory);
+          if (!metadata) throw new Error('No owned direct MID installation found');
+          app.ok(runDirectInstallation(metadata, 'stop'), { summary: 'Owned native MID stop command completed' });
+        }),
+      })
       .command({
         command: 'add',
         describe: 'Install and verify a MID Server',
@@ -374,7 +459,7 @@ export function midserversCmd(wrap) {
           .option('name', { type: 'string', describe: 'MID Server name (prompted when omitted)' })
           .option('username', { type: 'string', describe: 'MID Server username (password is always prompted)' })
           .option('install-method', { type: 'string', choices: ['docker', 'direct'], describe: 'Installation method (prompted when omitted)' })
-          .option('directory', { type: 'string', describe: 'Docker installation directory' })
+          .option('directory', { type: 'string', describe: 'Installation directory (must not exist for direct ZIP)' })
           .option('wait-timeout', { type: 'number', default: 300000, describe: 'How long to wait for the MID Server to report Up' })
           .option('wait-interval', { type: 'number', default: 3000, describe: 'MID Server status polling interval in milliseconds' }),
         handler: wrap(async (argv, app) => {
@@ -395,20 +480,60 @@ export function midserversCmd(wrap) {
             choices: dockerAvailable
               ? [
                 { name: 'Docker (recommended)', value: 'docker' },
-                { name: 'Direct install (not available yet)', value: 'direct' },
+                { name: 'Direct ZIP install (native user-owned runtime)', value: 'direct' },
               ]
               : dockerStatus.installed && dockerStatus.compose
                 ? [
                   { name: 'Run with sudo', value: 'sudo' },
                   { name: 'Prepare files now, run Docker later', value: 'prepare' },
-                  { name: 'Direct install (not available yet)', value: 'direct' },
+                  { name: 'Direct ZIP install (native user-owned runtime)', value: 'direct' },
                 ]
               : [
                 { name: 'Prepare files now, run Docker later', value: 'prepare' },
-                { name: 'Direct install (not available yet)', value: 'direct' },
+                { name: 'Direct ZIP install (native user-owned runtime)', value: 'direct' },
               ],
           });
-          if (installMethod === 'direct') throw new Error('Direct MID Server installation is not implemented yet. Choose Docker.');
+          if (installMethod === 'direct') {
+            const native = detectDirectPlatform();
+            const decision = await select({
+              message: native === 'linux' ? 'No system service or elevation will be used. Choose runtime:' : 'Windows console runtime only; native service registration is not supported. Choose:',
+              choices: [
+                ...(native === 'linux' ? [{ name: 'Start user-owned background MID', value: 'start' }] : []),
+                { name: 'Prepare private files only (do not start)', value: 'prepare' },
+                { name: 'Cancel without downloading', value: 'cancel' },
+              ],
+            });
+            if (decision === 'cancel') return;
+            const shortName = normalizeMidName(name);
+            const existing = await app.sdk.list(AGENT_TABLE, new URLSearchParams({ sysparm_query: `name=${shortName}`, sysparm_fields: 'sys_id,name', sysparm_limit: '1' }));
+            if (existing.length) throw new Error(`MID '${shortName}' already exists in ServiceNow; choose a new name. Existing runtime and record were not changed.`);
+            const installation = await installDirectMidServer({
+              instanceURL: app.getEffectiveInstance(), ...credentials, name, directory: argv.directory,
+              runNow: decision === 'start', onProgress: directProgress(app),
+            });
+            if (installation.state === 'prepared') {
+              app.ok(installation, { summary: `Prepared native MID '${installation.name}' in ${installation.installDir}; not started or registered. Start with jsn midservers start ${installation.name}${argv.directory ? ' --directory ' + JSON.stringify(installation.installDir) : ''}. Windows start runs in the foreground console; no service is installed.` });
+              return;
+            }
+            let record;
+            const directWait = Math.max(1, argv['wait-timeout']);
+            const directInterval = Math.max(500, argv['wait-interval']);
+            const onWait = registrationProgress(app, directWait);
+            const started = Date.now();
+            try {
+              record = await waitForMidServerUp(app, installation.name, directWait, directInterval, onWait);
+              onWait?.(directWait);
+            }
+            catch {
+              onWait?.(Math.max(directWait, Date.now() - started));
+              app.ok({ ...installation, registration: 'pending', validated: false }, { summary: `Native MID start command completed; registration is pending. Runtime retained for diagnostics at ${installation.installDir}; no forced teardown.` });
+              return;
+            }
+            const validated = queueValue(record.validated).toLowerCase() === 'true';
+            const url = new URL(`/ecc_agent.do?sys_id=${encodeURIComponent(unwrapSysId(record))}`, app.getEffectiveInstance()).href;
+            app.ok({ ...installation, registration: 'up', validated, record, url }, { summary: validated ? `MID '${installation.name}' is Up and manually validated` : `MID '${installation.name}' is Up but pending manual validation. Use Validate in ServiceNow: ${url}` });
+            return;
+          }
 
           const installation = await installDockerMidServer({
             instanceURL: app.getEffectiveInstance(),
@@ -448,7 +573,8 @@ export function midserversCmd(wrap) {
         command: 'remove [identifier]',
         aliases: ['delete'],
         describe: 'Remove a MID Server record (interactive when no identifier is given)',
-        builder: (b) => b.option('force', { type: 'boolean', default: false, describe: 'Skip confirmation' }),
+        builder: (b) => b.option('force', { type: 'boolean', default: false, describe: 'Skip confirmation' })
+          .option('directory', { type: 'string', describe: 'Local installation directory override' }),
         handler: wrap(async (argv, app) => {
           let record;
           if (argv.identifier) {
@@ -456,8 +582,8 @@ export function midserversCmd(wrap) {
               record = await resolveMidServer(app.sdk, argv.identifier);
             } catch (error) {
               if (error.code !== 'not_found') throw error;
-              const localDir = midInstallDirectory(app.getEffectiveInstance(), argv.identifier);
-              if (!fs.existsSync(path.join(localDir, 'docker-compose.yaml'))) throw error;
+              const localDir = argv.directory || midInstallDirectory(app.getEffectiveInstance(), argv.identifier);
+              if (!readDirectInstallation(app.getEffectiveInstance(), argv.identifier, argv.directory) && !fs.existsSync(path.join(localDir, 'docker-compose.yaml'))) throw error;
               record = null;
             }
           } else {
@@ -483,9 +609,10 @@ export function midserversCmd(wrap) {
           const sysId = record ? unwrapSysId(record) : null;
           const name = getStringField(record, 'name') || argv.identifier || sysId;
           await confirmDelete(app, argv, `Remove MID Server '${name}'`);
-          const localRemoved = removeLocalMidServer(app.getEffectiveInstance(), name);
+          const direct = readDirectInstallation(app.getEffectiveInstance(), name, argv.directory);
+          const localRemoved = removeLocalMidServer(app.getEffectiveInstance(), name, argv.directory);
           if (record) await app.sdk.delete(AGENT_TABLE, sysId);
-          app.ok({ name, sys_id: sysId, deleted: Boolean(record), local_compose_removed: localRemoved }, { summary: `Removed MID Server '${name}'${localRemoved ? ' and its local Compose stack' : ''}` });
+          app.ok({ name, sys_id: sysId, deleted: Boolean(record), local_compose_removed: localRemoved && !direct, local_installation_removed: localRemoved, local_installation_type: direct ? 'direct' : 'docker' }, { summary: `Removed MID Server '${name}'${localRemoved ? ' and its owned local runtime' : ''}` });
         }),
       })
       .command({
@@ -563,7 +690,7 @@ export function midserversCmd(wrap) {
       console.log('  issues [name_or_sys_id]       Show unresolved issues (--all includes resolved)');
       console.log('  events [name_or_sys_id]       Show lifecycle history');
       console.log('  show <name_or_sys_id>        Show a MID Server');
-      console.log('  add --name <name>             Create a MID Server record');
+      console.log('  add --name <name>             Install a MID Server (Docker or direct ZIP)');
       console.log('  remove <name_or_sys_id>       Remove a MID Server record');
       console.log('  execute <name_or_sys_id>      Execute a shell command');
       console.log('');

package/src/midserver-direct.js

@@ -0,0 +1,263 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { midInstallDirectory, normalizeMidName, defaultRun, validateMidCredentials } from './midserver-install.js';
+import { extractMidZip, inspectMidZip } from './midserver-zip.js';
+
+const METADATA = '.jsn-mid-direct.json';
+const MAX_ARCHIVE = 1024 * 1024 * 1024;
+
+export function detectDirectPlatform(platform = process.platform, arch = process.arch) {
+  if (!['linux', 'win32'].includes(platform)) throw new Error('Direct MID installs require Linux and Windows');
+  if (arch !== 'x64') throw new Error('Direct MID ZIP installs require x86-64');
+  return platform === 'win32' ? 'windows' : 'linux';
+}
+
+export function buildMidZipUrl(releaseName, platform = process.platform) {
+  const native = detectDirectPlatform(platform, 'x64');
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(releaseName)) throw new Error('Invalid MID release name');
+  const match = [...releaseName.matchAll(/(\d{4})-(\d{2})-(\d{2})|(\d{2})-(\d{2})-(\d{4})/g)].at(-1);
+  if (!match) throw new Error('MID release name has no build date');
+  const year = match[1] || match[6], month = match[2] || match[4], day = match[3] || match[5];
+  const date = new Date(`${year}-${month}-${day}T00:00:00Z`);
+  if (Number.isNaN(date.valueOf()) || date.toISOString().slice(0, 10) !== `${year}-${month}-${day}`) throw new Error('Invalid MID build date');
+  return `https://install.service-now.com/glide/distribution/builds/package/app-signed/mid/${year}/${month}/${day}/mid.${releaseName}.${native}.x86-64.zip`;
+}
+
+function powershell(script, directory) {
+  return execFileSync('powershell.exe', ['-NoLogo', '-NoProfile', '-NonInteractive', '-EncodedCommand',
+    Buffer.from(`$ErrorActionPreference='Stop'; try {\n${script}\n} catch { exit 1 }`, 'utf16le').toString('base64')], {
+    env: { ...process.env, JSN_MID_DIRECTORY: directory }, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
+  });
+}
+
+// No chmod substitute on Windows: protect the DACL before any credential is written.
+function protectDirectory(directory, platform) {
+  if (platform === 'linux') { fs.chmodSync(directory, 0o700); return; }
+  powershell(`$sid=[System.Security.Principal.WindowsIdentity]::GetCurrent().User
+$acl=New-Object System.Security.AccessControl.DirectorySecurity
+$acl.SetOwner($sid)
+$acl.SetAccessRuleProtection($true,$false)
+$rule=New-Object System.Security.AccessControl.FileSystemAccessRule($sid,'FullControl','ContainerInherit,ObjectInherit','None','Allow')
+$acl.AddAccessRule($rule)
+Set-Acl -LiteralPath $env:JSN_MID_DIRECTORY -AclObject $acl
+$actual=Get-Acl -LiteralPath $env:JSN_MID_DIRECTORY
+if (!$actual.AreAccessRulesProtected) { throw 'MID directory ACL is not protected' }
+foreach($r in $actual.Access) { if($r.IdentityReference.Translate([System.Security.Principal.SecurityIdentifier]).Value -ne $sid.Value -or $r.AccessControlType -ne 'Allow') { throw 'Unexpected MID directory access rule' } }`, directory);
+  assertPrivateWindows(directory);
+}
+
+function assertPrivateWindows(directory) {
+  powershell(`$sid=[System.Security.Principal.WindowsIdentity]::GetCurrent().User
+$acl=Get-Acl -LiteralPath $env:JSN_MID_DIRECTORY
+if (!$acl.AreAccessRulesProtected -or @($acl.Access).Count -ne 1) { throw 'MID directory ACL must be private' }
+$r=@($acl.Access)[0]
+if ($r.IdentityReference.Translate([System.Security.Principal.SecurityIdentifier]).Value -ne $sid.Value -or $r.AccessControlType -ne 'Allow' -or $r.FileSystemRights -ne 'FullControl') { throw 'Unexpected MID directory access rule' }`, directory);
+}
+
+function checkParents(directory, platform) {
+  let current = path.dirname(directory);
+  while (true) {
+    if (fs.existsSync(current)) {
+      const st = fs.lstatSync(current);
+      if (st.isSymbolicLink() || !st.isDirectory()) throw new Error('Installation ancestors must be real directories');
+      if (platform === 'linux' && (st.mode & 0o022) && !(st.mode & 0o1000)) throw new Error('Installation ancestor is writable by other users');
+    }
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+}
+
+export async function downloadMidZip(url, archive, fetchImpl = fetch, onProgress) {
+  const response = await fetchImpl(url, { redirect: 'error', signal: AbortSignal.timeout(600000) });
+  if (!response.ok || !response.body) throw new Error(`MID ZIP download failed (HTTP ${response.status})`);
+  const length = Number(response.headers.get('content-length'));
+  if (length > MAX_ARCHIVE) throw new Error('MID ZIP exceeds 1 GiB download limit');
+  onProgress?.({ phase: 'download', received: 0, total: Number.isFinite(length) ? length : 0 });
+  const fd = fs.openSync(archive, 'wx', 0o600);
+  let size = 0;
+  let reported = 0;
+  const step = Math.max(4 * 1024 * 1024, Math.floor((Number.isFinite(length) ? length : MAX_ARCHIVE) / 100));
+  try {
+    for await (const chunk of response.body) {
+      size += chunk.length;
+      if (size > MAX_ARCHIVE) throw new Error('MID ZIP exceeds 1 GiB download limit');
+      fs.writeSync(fd, chunk);
+      if (onProgress && size - reported >= step) {
+        reported = size;
+        onProgress({ phase: 'download', received: size, total: Number.isFinite(length) ? length : 0 });
+      }
+    }
+    if (length && size !== length) throw new Error('Incomplete MID ZIP download');
+    onProgress?.({ phase: 'download', received: size, total: size, done: true });
+  } finally { fs.closeSync(fd); }
+}
+
+function xmlEscape(value) {
+  if ([...String(value)].some(char => char.codePointAt(0) < 32 && !['\t', '\n', '\r'].includes(char))) throw new Error('Invalid XML configuration character');
+  return String(value).replaceAll('&', '&amp;').replaceAll('"', '&quot;').replaceAll("'", '&apos;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('\r', '&#13;').replaceAll('\n', '&#10;').replaceAll('\t', '&#9;');
+}
+
+export function configureMidXml(template, values) {
+  // Work only on active parameter elements, never examples in template comments.
+  const comments = [];
+  let xml = template.replace(/<!--[\s\S]*?-->/g, comment => `<!--JSN_COMMENT_${comments.push(comment) - 1}-->`);
+  for (const [name, value] of Object.entries(values)) {
+    let found = 0;
+    xml = xml.replace(/<parameter\b[^>]*\/>/g, tag => {
+      if (!tag.match(/\bname\s*=\s*(["'])(.*?)\1/) || tag.match(/\bname\s*=\s*(["'])(.*?)\1/)[2] !== name) return tag;
+      found++;
+      const attribute = `value="${xmlEscape(value)}"`;
+      return /\bvalue\s*=/.test(tag) ? tag.replace(/\bvalue\s*=\s*(["'])[\s\S]*?\1/, attribute) : tag.replace(/\/>$/, ` ${attribute}/>`);
+    });
+    if (found > 1) throw new Error(`Duplicate MID configuration field ${name}`);
+    if (!found) {
+      if (!xml.includes('</parameters>')) throw new Error('Unrecognized vendor config.xml template');
+      xml = xml.replace('</parameters>', `  <parameter name="${name}" value="${xmlEscape(value)}"/>\n</parameters>`);
+    }
+  }
+  return xml.replace(/<!--JSN_COMMENT_(\d+)-->/g, (_, index) => comments[index]);
+}
+
+function nativeToken(origin, name, directory) {
+  return `jsn_mid_${createHash('sha256').update(`${origin}/${name}/${directory}`).digest('hex').slice(0, 20)}`;
+}
+
+function refuseNativeService(token) {
+  for (const filename of [`/etc/systemd/system/${token}.service`, `/run/systemd/system/${token}.service`, `/usr/lib/systemd/system/${token}.service`, `/etc/init/${token}.conf`, `/etc/init.d/${token}`, `/etc/rc.d/init.d/${token}`]) {
+    try { fs.lstatSync(filename); } catch (error) { if (error.code === 'ENOENT') continue; throw error; }
+    throw new Error('A native service already uses this MID identity; refusing to operate on it');
+  }
+}
+
+function save(metadata) {
+  fs.writeFileSync(path.join(metadata.installDir, METADATA), JSON.stringify(metadata, null, 2), { mode: 0o600 });
+}
+
+export function readDirectInstallation(instanceURL, name, directory) {
+  const installDir = path.resolve(directory || midInstallDirectory(instanceURL, name));
+  try { fs.lstatSync(path.join(installDir, METADATA)); } catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+  checkParents(installDir, process.platform === 'linux' ? 'linux' : 'windows');
+  const root = fs.lstatSync(installDir);
+  if (!root.isDirectory() || root.isSymbolicLink() || (process.platform === 'linux' && ((root.mode & 0o077) || root.uid !== process.getuid()))) throw new Error('Refusing an untrusted installation directory');
+  if (process.platform === 'win32') assertPrivateWindows(installDir);
+  const metaPath = path.join(installDir, METADATA);
+  const st = fs.lstatSync(metaPath);
+  if (!st.isFile() || st.isSymbolicLink() || (process.platform === 'linux' && ((st.mode & 0o077) || st.uid !== process.getuid()))) throw new Error('Untrusted MID installation metadata');
+  const metadata = JSON.parse(fs.readFileSync(metaPath, 'utf8'));
+  if (metadata.owner !== 'jsn-mid-direct-v1' || metadata.installDir !== installDir || metadata.instanceURL !== new URL(instanceURL).origin || metadata.name !== normalizeMidName(name) || metadata.platform !== detectDirectPlatform()) throw new Error('MID installation ownership does not match');
+  if (fs.lstatSync(path.join(installDir, 'agent')).isSymbolicLink()) throw new Error('Refusing symlink agent');
+  return metadata;
+}
+
+function uncertainState(metadata) {
+  return `MID '${metadata.name}' runtime state is uncertain after an interrupted lifecycle command. Confirm no vendor MID process from ${metadata.installDir} is running, then rerun; installed files are kept.`;
+}
+
+export function runDirectInstallation(metadata, action, run = defaultRun) {
+  const cwd = path.join(metadata.installDir, 'agent');
+  if (!['start', 'stop'].includes(action)) throw new Error('Unsupported MID runtime action');
+  if (metadata.state === 'uncertain') throw new Error(uncertainState(metadata));
+  if (metadata.runtime !== 'user-background') {
+    // Windows console runtime: never register a service, never guess at a state.
+    if (action === 'stop') {
+      throw new Error(metadata.state === 'console-running' ? 'Windows console MID: stop with Ctrl+C in its owning terminal before removal' : 'Windows console MID is not running');
+    }
+    if (metadata.state !== 'prepared') throw new Error('MID is already started; stop it before starting again');
+    metadata.state = 'console-running'; save(metadata);
+    try { run('cmd.exe', ['/d', '/s', '/c', 'bin\\mid.bat console'], { cwd }); }
+    catch { throw new Error('Windows MID console failed or was interrupted; runtime state is uncertain. Stop in its owning terminal; files retained.'); }
+    metadata.state = 'prepared'; save(metadata);
+    return metadata;
+  }
+  // Never guess at a state an interrupted Linux command left behind; make it explicit.
+  if (['starting', 'stopping', 'console-running'].includes(metadata.state)) {
+    metadata.state = 'uncertain'; save(metadata);
+    throw new Error(uncertainState(metadata));
+  }
+  // Call the native user-owned launcher, never install/register a system service.
+  if (process.getuid?.() === 0) throw new Error('Run native MID lifecycle commands as a non-root user');
+  refuseNativeService(nativeToken(metadata.instanceURL, metadata.name, metadata.installDir));
+  if (action === 'start' && metadata.state !== 'prepared') throw new Error('MID is already started; stop it before starting again');
+  if (action === 'stop' && metadata.state !== 'started') throw new Error('MID is not running');
+  metadata.state = action === 'start' ? 'starting' : 'stopping'; save(metadata);
+  try { run('sh', ['bin/mid.sh', action], { cwd, stdio: 'ignore' }); }
+  catch { throw new Error(`MID ${action} failed; installation retained at ${metadata.installDir}. Inspect local logs.`); }
+  metadata.state = action === 'start' ? 'started' : 'prepared'; save(metadata);
+  return metadata;
+}
+
+export function removeDirectInstallation(metadata, run = defaultRun) {
+  if (metadata.state === 'uncertain') throw new Error(`Refusing to remove '${metadata.name}': runtime state is uncertain. Inspect ${metadata.installDir} and stop any vendor MID process first.`);
+  if (metadata.state !== 'prepared') runDirectInstallation(metadata, 'stop', run);
+  fs.rmSync(metadata.installDir, { recursive: true });
+}
+
+export async function installDirectMidServer({ instanceURL, username, password, name, directory, releaseName: suppliedRelease,
+  runNow = false, platform = process.platform, arch = process.arch, fetchImpl = fetch, download = downloadMidZip, onProgress,
+  protect = protectDirectory, run = defaultRun }) {
+  const native = detectDirectPlatform(platform, arch);
+  if (native === 'linux' && process.getuid?.() === 0) throw new Error('Run direct MID installation as a non-root user');
+  if (native === 'windows' && runNow) throw new Error('Prepare Windows first, then start its console in an owning terminal; no implicit service registration');
+  const shortName = normalizeMidName(name);
+  const origin = new URL(instanceURL).origin;
+  if (!origin.startsWith('https://')) throw new Error('MID credentials require an HTTPS instance');
+  const installDir = path.resolve(directory || midInstallDirectory(origin, shortName));
+  checkParents(installDir, native);
+  if (native === 'linux') refuseNativeService(nativeToken(origin, shortName, installDir));
+  if (fs.existsSync(installDir)) throw new Error(`Refusing to overwrite existing installation: ${installDir}`);
+  const releaseName = suppliedRelease || (await validateMidCredentials(origin, username, password, fetchImpl)).releaseName;
+  const archiveURL = buildMidZipUrl(releaseName, platform);
+  // Validate all credential fields before creating files or downloading.
+  for (const value of [origin, username, password, shortName]) xmlEscape(value);
+  if (!username || !password) throw new Error('MID credentials are required');
+  let ancestor = path.dirname(installDir);
+  while (!fs.existsSync(ancestor)) ancestor = path.dirname(ancestor);
+  const disk = fs.statfsSync(ancestor);
+  if (disk.bavail * disk.bsize < 3 * MAX_ARCHIVE) throw new Error('Direct MID installation requires at least 3 GiB free disk space');
+  fs.mkdirSync(path.dirname(installDir), { recursive: true, mode: 0o700 });
+  fs.mkdirSync(installDir, { mode: 0o700 }); // atomic collision refusal
+  const archive = path.join(installDir, '.download.zip');
+  let prepared = false;
+  try {
+    protect(installDir, native);
+    onProgress?.({ phase: 'download-start', archiveURL, platform: native, installDir, name: shortName });
+    await download(archiveURL, archive, fetchImpl, onProgress);
+    const entries = inspectMidZip(archive);
+    onProgress?.({ phase: 'extract-start', entries: entries.length, installDir });
+    await extractMidZip(archive, installDir, entries);
+    onProgress?.({ phase: 'extract-done', entries: entries.length, installDir });
+    const agent = path.join(installDir, 'agent');
+    for (const filename of ['config.xml', 'conf/wrapper-override.conf', native === 'linux' ? 'bin/mid.sh' : 'bin/mid.bat']) {
+      if (!fs.statSync(path.join(agent, filename)).isFile()) throw new Error(`Vendor ZIP missing ${filename}`);
+    }
+    const config = path.join(agent, 'config.xml');
+    fs.writeFileSync(config, configureMidXml(fs.readFileSync(config, 'utf8'), {
+      url: `${origin}/`, 'mid.instance.username': username, 'mid.instance.password': password, name: shortName,
+    }), { mode: 0o600 });
+    const token = nativeToken(origin, shortName, installDir);
+    const override = path.join(agent, 'conf/wrapper-override.conf');
+    let text = fs.readFileSync(override, 'utf8').replace(/^wrapper\.(name|displayname)=.*\r?$/gm, '');
+    text += `\nwrapper.name=${token}\nwrapper.displayname=ServiceNow MID ${shortName}\n`;
+    fs.writeFileSync(override, text, { mode: 0o600 });
+    if (native === 'linux') {
+      fs.appendFileSync(path.join(agent, 'bin/mid.shconf_override'), `\nAPP_NAME="${token}"\nAPP_LONG_NAME="ServiceNow MID ${shortName}"\nSERVICE_MANAGEMENT_TOOL=initd\n`);
+    }
+    fs.rmSync(archive);
+    const metadata = { owner: 'jsn-mid-direct-v1', instanceURL: origin, name: shortName, releaseName, installDir, archiveURL, platform: native, runtime: native === 'linux' ? 'user-background' : 'console', state: 'prepared', serviceRegistered: false };
+    save(metadata);
+    prepared = true;
+    if (runNow) runDirectInstallation(metadata, 'start', run);
+    return metadata;
+  } catch (error) {
+    if (!prepared) fs.rmSync(installDir, { recursive: true, force: true });
+    // Do not expose nested process/fetch errors that could include credential-bearing content.
+    if (prepared) throw error;
+    // Do not retain raw causes, which can contain credentials.
+    // eslint-disable-next-line preserve-caught-error
+    throw new Error(`Direct MID preparation failed; owned files cleaned up (${error.code || 'preparation error'}). Check ZIP, disk, permissions and vendor layout.`);
+  }
+}

package/src/midserver-zip.js

@@ -0,0 +1,107 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createInflateRaw } from 'node:zlib';
+import { Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+
+const MAX_EXPANDED = 2 * 1024 * 1024 * 1024;
+const crcTable = Array.from({ length: 256 }, (_, n) => {
+  for (let i = 0; i < 8; i++) n = n & 1 ? 0xedb88320 ^ (n >>> 1) : n >>> 1;
+  return n >>> 0;
+});
+function read(fd, size, offset) {
+  const result = Buffer.alloc(size);
+  if (fs.readSync(fd, result, 0, size, offset) !== size) throw new Error('Truncated ZIP');
+  return result;
+}
+
+// Inspect every entry before extracting anything. ZIP64, split ZIPs, links and
+// Windows aliases are deliberately unsupported, not delegated to a shell tool.
+export function inspectMidZip(archive) {
+  const fd = fs.openSync(archive, 'r');
+  try {
+    const size = fs.fstatSync(fd).size;
+    if (size < 22) throw new Error('Invalid ZIP');
+    const tail = read(fd, Math.min(size, 65557), size - Math.min(size, 65557));
+    let end = -1;
+    for (let i = tail.length - 22; i >= 0; i--) {
+      if (tail.readUInt32LE(i) === 0x06054b50 && i + 22 + tail.readUInt16LE(i + 20) === tail.length) { end = i; break; }
+    }
+    if (end < 0) throw new Error('Missing ZIP directory');
+    const count = tail.readUInt16LE(end + 10), directorySize = tail.readUInt32LE(end + 12), offset = tail.readUInt32LE(end + 16);
+    if (tail.readUInt16LE(end + 4) || tail.readUInt16LE(end + 6) || tail.readUInt16LE(end + 8) !== count || count === 65535 || count > 20000 || directorySize > 16 * 1024 * 1024 || offset + directorySize > size - (tail.length - end)) throw new Error('Unsupported ZIP directory');
+    const directory = read(fd, directorySize, offset);
+    const entries = [], names = new Map();
+    let pos = 0, expanded = 0;
+    for (let i = 0; i < count; i++) {
+      if (pos + 46 > directory.length || directory.readUInt32LE(pos) !== 0x02014b50) throw new Error('Invalid ZIP entry');
+      const flags = directory.readUInt16LE(pos + 8), method = directory.readUInt16LE(pos + 10);
+      const compressedSize = directory.readUInt32LE(pos + 20), uncompressedSize = directory.readUInt32LE(pos + 24);
+      const nameLength = directory.readUInt16LE(pos + 28), extraLength = directory.readUInt16LE(pos + 30), commentLength = directory.readUInt16LE(pos + 32);
+      if (pos + 46 + nameLength + extraLength + commentLength > directory.length) throw new Error('Truncated ZIP entry');
+      const name = directory.subarray(pos + 46, pos + 46 + nameLength).toString('utf8');
+      const mode = directory.readUInt32LE(pos + 38) >>> 16;
+      const localOffset = directory.readUInt32LE(pos + 42);
+      const folder = name.endsWith('/');
+      const parts = name.replace(/\/$/, '').split('/');
+      if (!['agent', 'META-INF'].includes(parts[0]) || parts.some(part => !part || part === '.' || part === '..' || /[\\:<>"|?*]/.test(part) || [...part].some(char => char.codePointAt(0) < 32) || /[. ]$/.test(part) || /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(part))) throw new Error('Unsafe ZIP path');
+      const type = mode & 0o170000;
+      if (type && type !== 0o100000 && type !== 0o040000) throw new Error('ZIP links and special files are forbidden');
+      if ((flags & 1) || ![0, 8].includes(method) || compressedSize === 0xffffffff || uncompressedSize === 0xffffffff || localOffset === 0xffffffff) throw new Error('Unsupported ZIP encoding');
+      expanded += uncompressedSize;
+      if (expanded > MAX_EXPANDED) throw new Error('ZIP exceeds 2 GiB expanded limit');
+      const key = parts.join('/').toLowerCase();
+      if (names.has(key)) throw new Error('Duplicate ZIP path');
+      names.set(key, folder);
+      const header = read(fd, 30, localOffset);
+      if (header.readUInt32LE(0) !== 0x04034b50 || header.readUInt16LE(8) !== method || header.readUInt16LE(6) !== flags) throw new Error('ZIP header mismatch');
+      const localName = read(fd, header.readUInt16LE(26), localOffset + 30).toString('utf8');
+      if (localName !== name) throw new Error('ZIP path mismatch');
+      const dataOffset = localOffset + 30 + header.readUInt16LE(26) + header.readUInt16LE(28);
+      if (dataOffset + compressedSize > offset) throw new Error('Invalid ZIP data range');
+      entries.push({ name, folder, mode, method, compressedSize, uncompressedSize, dataOffset, crc: directory.readUInt32LE(pos + 16) });
+      pos += 46 + nameLength + extraLength + commentLength;
+    }
+    if (pos !== directory.length) throw new Error('Unexpected ZIP directory data');
+    for (const entry of entries) {
+      const parts = entry.name.replace(/\/$/, '').toLowerCase().split('/');
+      for (let i = 1; i < parts.length; i++) if (names.get(parts.slice(0, i).join('/')) === false) throw new Error('ZIP file/directory collision');
+    }
+    return entries;
+  } finally { fs.closeSync(fd); }
+}
+
+function privateDirectory(directory) {
+  try { fs.mkdirSync(directory, { mode: 0o700 }); } catch (error) { if (error.code !== 'EEXIST') throw error; }
+  const st = fs.lstatSync(directory);
+  if (!st.isDirectory() || st.isSymbolicLink()) throw new Error('Unsafe ZIP destination directory');
+}
+
+export async function extractMidZip(archive, destination, entries = inspectMidZip(archive)) {
+  privateDirectory(destination);
+  for (const entry of entries) {
+    const parts = entry.name.replace(/\/$/, '').split('/');
+    let parent = destination;
+    for (const part of parts.slice(0, entry.folder ? parts.length : -1)) {
+      parent = path.join(parent, part);
+      privateDirectory(parent);
+    }
+    const filename = path.join(destination, ...parts);
+    if (entry.folder) continue;
+    let size = 0, crc = 0xffffffff;
+    const verify = new Transform({ transform(chunk, _, callback) {
+      size += chunk.length;
+      if (size > entry.uncompressedSize) return callback(new Error('ZIP expanded size mismatch'));
+      for (const byte of chunk) crc = crcTable[(crc ^ byte) & 255] ^ (crc >>> 8);
+      callback(null, chunk);
+    } });
+    const output = fs.createWriteStream(filename, { flags: 'wx', mode: entry.mode & 0o111 ? 0o700 : 0o600 });
+    if (!entry.compressedSize) { output.end(); await new Promise((resolve, reject) => { output.on('close', resolve); output.on('error', reject); }); }
+    else {
+      const input = fs.createReadStream(archive, { start: entry.dataOffset, end: entry.dataOffset + entry.compressedSize - 1 });
+      if (entry.method === 8) await pipeline(input, createInflateRaw(), verify, output);
+      else await pipeline(input, verify, output);
+    }
+    if (size !== entry.uncompressedSize || ((crc ^ 0xffffffff) >>> 0) !== entry.crc) throw new Error('ZIP integrity check failed');
+  }
+}