@jacebenson/jsn 4.3.7 → 4.3.8-dev.47

package/src/midserver-direct.js

@@ -0,0 +1,312 @@
+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;
+}
+
+// The vendor rotates agent0.log to agent0.log.0 (and upward), so the plain
+// name may not exist on a healthy install. Newest real file wins; links and
+// non-files are never followed.
+export function resolveDirectLogFile(installDir) {
+  const directory = path.join(installDir, 'agent', 'logs');
+  let names;
+  try { names = fs.readdirSync(directory); } catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+  const candidates = [];
+  for (const name of names) {
+    const agent = /^agent0\.log(\.\d+)?$/.test(name);
+    if (!agent && name !== 'wrapper.log') continue;
+    const full = path.join(directory, name);
+    const stat = fs.lstatSync(full);
+    if (!stat.isFile() || stat.isSymbolicLink()) continue;
+    candidates.push({ full, agent, mtime: stat.mtimeMs });
+  }
+  candidates.sort((a, b) => (b.agent - a.agent) || (b.mtime - a.mtime));
+  return candidates.length ? candidates[0].full : null;
+}
+
+/**
+ * Tail a direct install's agent log, following rotation.
+ *
+ * The vendor rotates by creating a new file, so the followed path can change
+ * between polls; a shrinking file is treated as truncation and re-read from
+ * the start. Each appended chunk is handed to `writer` unchanged.
+ */
+export async function followDirectLog(installDir, { writer = chunk => process.stdout.write(chunk), intervalMs = 1000, iterations = Infinity, sleep } = {}) {
+  const pause = sleep || (ms => new Promise(resolve => setTimeout(resolve, ms)));
+  let file = resolveDirectLogFile(installDir);
+  if (!file) throw new Error('No MID agent log yet; the installation may only be prepared');
+  let offset = fs.statSync(file).size;
+  for (let seen = 0; seen < iterations; seen++) {
+    await pause(intervalMs);
+    const next = resolveDirectLogFile(installDir) || file;
+    if (next !== file) { file = next; offset = 0; }
+    const stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink()) return;
+    if (stat.size < offset) offset = 0;
+    if (stat.size === offset) continue;
+    const length = stat.size - offset;
+    const buffer = Buffer.alloc(length);
+    const fd = fs.openSync(file, 'r');
+    try { fs.readSync(fd, buffer, 0, length, offset); } finally { fs.closeSync(fd); }
+    offset = stat.size;
+    writer(buffer.toString('utf8'));
+  }
+}
+
+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-install.js

@@ -0,0 +1,170 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+import { execFileSync } from 'node:child_process';
+
+const INSTALL_HOST = 'install.service-now.com';
+
+function defaultRun(command, args, options = {}) {
+  return execFileSync(command, args, {
+    cwd: options.cwd,
+    env: { ...process.env, ...(options.env || {}) },
+    encoding: 'utf8',
+    stdio: options.stdio || 'inherit',
+  });
+}
+
+function assertSafePart(value, label) {
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(value)) {
+    throw new Error(`${label} may contain only letters, numbers, dots, underscores, and dashes`);
+  }
+}
+
+export function normalizeMidName(name) {
+  const shortName = String(name || '').replace(/^mid\.server\./, '');
+  assertSafePart(shortName, 'MID Server name');
+  return shortName;
+}
+
+export function buildMidRecipeUrl(releaseName) {
+  const matches = [...String(releaseName).matchAll(/(\d{4})-(\d{2})-(\d{2})|(\d{2})-(\d{2})-(\d{4})/g)];
+  const match = matches.at(-1);
+  if (!match) throw new Error(`MID release name has no build date: ${releaseName}`);
+  const year = match[1] || match[6];
+  const month = match[2] || match[4];
+  const day = match[3] || match[5];
+  const filename = `mid-linux-container-recipe.${releaseName}.linux.x86-64.zip`;
+  return `https://${INSTALL_HOST}/glide/distribution/builds/package/app-signed/mid-linux-container-recipe/${year}/${month}/${day}/${filename}`;
+}
+
+export async function validateMidCredentials(instanceURL, username, password, fetchImpl = fetch) {
+  if (!username || !password) throw new Error('MID Server username and password are required');
+  const endpoint = `${String(instanceURL).replace(/\/$/, '')}/api/now/table/sys_properties?sysparm_query=name=mid.version&sysparm_fields=value&sysparm_limit=1`;
+  let response;
+  try {
+    response = await fetchImpl(endpoint, {
+      headers: {
+        Accept: 'application/json',
+        Authorization: `Basic ${Buffer.from(`${username}:${password}`).toString('base64')}`,
+      },
+    });
+  } catch {
+    throw new Error('Could not reach the ServiceNow instance to validate the MID Server credentials');
+  }
+  if (response.status === 401 || response.status === 403) {
+    throw new Error('The MID Server username or password was rejected by the ServiceNow instance');
+  }
+  if (!response.ok) {
+    throw new Error(`MID Server credential validation failed with HTTP ${response.status}`);
+  }
+  const body = await response.json();
+  const releaseName = body?.result?.[0]?.value;
+  if (!releaseName) throw new Error('Credential validation succeeded, but the instance returned no mid.version value');
+  return { releaseName };
+}
+
+export function detectDocker(run = defaultRun) {
+  const status = { installed: false, compose: false, daemon: false, available: false };
+  try { run('docker', ['--version'], { stdio: 'ignore' }); status.installed = true; } catch { return status; }
+  try { run('docker', ['compose', 'version'], { stdio: 'ignore' }); status.compose = true; } catch { return status; }
+  try { run('docker', ['info'], { stdio: 'ignore' }); status.daemon = true; } catch { return status; }
+  status.available = true;
+  return status;
+}
+
+export function dockerComposeAvailable(run = defaultRun) {
+  return detectDocker(run).available;
+}
+
+function composeFile({ serviceName }) {
+  return `services:\n  ${serviceName}:\n    container_name: ${serviceName}\n    build: ./recipe\n    image: ${serviceName}:\${MID_RELEASE}\n    restart: unless-stopped\n    volumes:\n      - ./export:/opt/snc_mid_server/agent/export\n    environment:\n      MID_INSTANCE_URL: \${MID_INSTANCE_URL}\n      MID_INSTANCE_USERNAME: \${MID_INSTANCE_USERNAME}\n      MID_INSTANCE_PASSWORD: \${MID_INSTANCE_PASSWORD}\n      MID_SERVER_NAME: \${MID_SERVER_NAME}\n`;
+}
+
+function envFile({ instanceURL, username, password, displayName, releaseName }) {
+  return `MID_RELEASE=${releaseName}\nMID_INSTANCE_URL=${String(instanceURL).replace(/\/$/, '')}/\nMID_INSTANCE_USERNAME=${username}\nMID_INSTANCE_PASSWORD=${password}\nMID_SERVER_NAME=${displayName}\n`;
+}
+
+function instanceName(instanceURL) {
+  const hostname = new URL(instanceURL).hostname;
+  return hostname.replace(/\.service-now\.com$|\.servicenowservices\.com$/i, '').replace(/[^A-Za-z0-9._-]/g, '_');
+}
+
+export function midInstallDirectory(instanceURL, name, homeDirectory = os.homedir()) {
+  const shortName = normalizeMidName(name);
+  return path.join(homeDirectory, '.servicenow', 'mids', instanceName(instanceURL), shortName);
+}
+
+export async function installDockerMidServer({
+  instanceURL,
+  username,
+  password,
+  name,
+  directory,
+  releaseName: suppliedReleaseName,
+  runNow = true,
+  fetchImpl = fetch,
+  run = defaultRun,
+}) {
+  const dockerAvailable = detectDocker(run).available;
+  const shortName = normalizeMidName(name);
+  const displayName = shortName;
+  const releaseName = suppliedReleaseName || (await validateMidCredentials(instanceURL, username, password, fetchImpl)).releaseName;
+  const recipeURL = buildMidRecipeUrl(releaseName);
+  const installDir = directory || midInstallDirectory(instanceURL, name);
+  fs.mkdirSync(installDir, { recursive: true, mode: 0o700 });
+  const exportDir = path.join(installDir, 'export');
+  fs.mkdirSync(exportDir, { recursive: true, mode: 0o777 });
+  fs.chmodSync(exportDir, 0o777);
+  const workDir = fs.mkdtempSync(path.join(os.tmpdir(), 'jsn-mid-'));
+  const filename = path.basename(recipeURL);
+  const archive = path.join(workDir, filename);
+  const recipeDir = path.join(workDir, 'recipe');
+  try {
+    run('curl', ['-fSL', '--connect-timeout', '10', '--max-time', '300', recipeURL, '-o', archive]);
+    fs.mkdirSync(recipeDir, { recursive: true, mode: 0o700 });
+    run('unzip', ['-q', archive, '-d', recipeDir]);
+    const composePath = path.join(installDir, 'docker-compose.yaml');
+    const persistedRecipeDir = path.join(installDir, 'recipe');
+    const serviceName = `jsn_mid_${shortName.replace(/[^A-Za-z0-9_.-]/g, '_')}`;
+    const env = {
+      MID_RELEASE: releaseName,
+      MID_INSTANCE_URL: `${String(instanceURL).replace(/\/$/, '')}/`,
+      MID_INSTANCE_USERNAME: username,
+      MID_INSTANCE_PASSWORD: password,
+      MID_SERVER_NAME: displayName,
+    };
+    fs.rmSync(persistedRecipeDir, { recursive: true, force: true });
+    fs.cpSync(recipeDir, persistedRecipeDir, { recursive: true });
+    fs.writeFileSync(composePath, composeFile({ serviceName }), { mode: 0o600 });
+    fs.chmodSync(composePath, 0o600);
+    const envPath = path.join(installDir, '.env');
+    fs.writeFileSync(envPath, envFile({ instanceURL, username, password, displayName, releaseName }), { mode: 0o600 });
+    fs.chmodSync(envPath, 0o600);
+    if (!dockerAvailable || !runNow) {
+      return {
+        name: displayName,
+        releaseName,
+        installDir,
+        composePath,
+        serviceName,
+        prepared: true,
+        runCommand: `docker compose --env-file ${envPath} -f ${composePath} up -d`,
+      };
+    }
+    run('docker', ['build', '--tag', `${serviceName}:${releaseName}`, persistedRecipeDir]);
+    run('docker', ['compose', '--env-file', envPath, '-f', composePath, 'up', '-d'], { cwd: installDir, env });
+    return {
+      name: displayName,
+      releaseName,
+      installDir,
+      composePath,
+      serviceName,
+      rollback: () => run('docker', ['compose', '--env-file', envPath, '-f', composePath, 'down'], { cwd: installDir, env }),
+    };
+  } finally {
+    fs.rmSync(workDir, { recursive: true, force: true });
+  }
+}
+
+export { defaultRun };

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');
+  }
+}

package/src/output.js

@@ -1,6 +1,7 @@
 // Output formatting: JSON, Markdown, Styled, Quiet
 
 import process from 'node:process';
+import { errExtractionNotFound } from './errors.js';
 
 export const FormatAuto = 'auto';
 export const FormatJSON = 'json';
@@ -125,9 +126,15 @@ export class OutputWriter {
     // --get extractor: resolve against the JSON envelope and print just that
     // value as JSON. Takes precedence over styling/table formats — a path
     // extract is inherently scriptable, not presentational.
+    //
+    // A path that does not resolve is an error, not a value. Stringifying
+    // `undefined` printed the literal token `undefined` and exited 0, so a
+    // typo looked like a successful empty result until the next tool in the
+    // pipeline failed to parse it. Present null/false/0/"" still print as-is.
     if (this.jqFilter) {
       const envelope = { ok: true, data, summary: opts.summary || '', breadcrumbs: opts.breadcrumbs || [] };
       const value = resolvePath(envelope, this.jqFilter);
+      if (value === undefined) throw errExtractionNotFound(this.jqFilter);
       this.writer.write(JSON.stringify(value, null, 2) + '\n');
       return;
     }