@jacebenson/jsn 4.3.13-dev.93.1 → 4.3.13-dev.95.1

package/README.md

@@ -78,3 +78,17 @@ npm test
 ## License
 
 MIT
+
+
+### Commands for the connected account
+
+Login and OAuth refresh check for the current account's `admin` role. Profiles
+without that role show a compact command list focused on tickets, generic
+records, people/groups, documentation, and connection management. If the role
+check is unavailable, the profile also uses compact help; this does not assert
+that the account lacks admin. Existing profiles keep full help until renewed.
+
+This applies to root help, root JSON, `discover`, and root shell completion.
+Use `jsn --all-commands --help` or `jsn discover --all-commands --json` to inspect
+every registered command. Explicit command paths remain available and ServiceNow
+ACLs decide access. Reauthenticate (or refresh OAuth) after roles change.

package/package.json

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

package/src/cli-adapter.js

@@ -332,6 +332,10 @@ export class LocalCLI {
   }
 
   _help(node, path = []) {
+    if (!path.length && this.rootHelpRenderer) {
+      process.stdout.write(this.rootHelpRenderer() + "\n");
+      return;
+    }
     const lines = [node.usageText || `Usage: ${this.script} ${path.join(' ') || '<command>'}`];
     if (node.definition.describe) lines.push(`\n${node.definition.describe}`);
     if (node.children.length) lines.push('\nCommands:\n' + node.children.filter((n) => n.name !== this.completionCommand).map((n) => `  ${n.definition.command}  ${n.definition.describe || ''}`).join('\n'));

package/src/cli.js

@@ -1,3 +1,4 @@
+import { visibleCommandRegistry } from './command-audience.js';
 // Root CLI using the local yargs-compatible adapter
 
 import yargs, { hideBin } from './cli-adapter.js';
@@ -148,6 +149,7 @@ export function buildCLI() {
       },
     ])
     .options({
+      'all-commands': { type: 'boolean', describe: 'Show the full command list, including admin and developer tools' },
       reason: { type: 'string', describe: 'Optional non-sensitive reason saved in local mutation history' },
 
       force: {
@@ -432,7 +434,7 @@ export function buildCLI() {
     .command(skillCmd(wrap))
     .command(docsCmd(wrap))
     .command(versionCmd(wrap))
-    .command(discoverCmd(wrap, () => cliInstance.commandRegistry()))
+    .command(discoverCmd(wrap, (argv) => visibleCommandRegistry(cliInstance.commandRegistry(), app.config, argv)))
     .demandCommand(1, 'You must specify a command')
     // Completion plumbing under a hidden command name, so the explicit
     // 'completion' command below owns the UX. (#176)
@@ -452,6 +454,12 @@ export function buildCLI() {
         if (current && !current.startsWith('-') && depth === 0) {
           out = [...new Set([...out, ...rootCommands])];
         }
+        const options = cliInstance.parseGlobalOptions(process.argv.slice(2));
+        const visible = visibleCommandRegistry(cliInstance.commandRegistry(), loadConfig(options), options);
+        if (!depth) {
+          const names = new Set(visible.commands.flatMap(command => [command.name, ...command.aliases]));
+          out = out.filter(value => value.startsWith('-') || names.has(value));
+        }
         done([...new Set(out)]);
       });
     })
@@ -557,7 +565,7 @@ export function buildCLI() {
           if (typeof formatArgv?.get === 'string' && formatArgv.get) {
             app.output.setJqFilter(formatArgv.get);
           }
-          const { commands } = cliInstance.commandRegistry();
+          const { commands } = visibleCommandRegistry(cliInstance.commandRegistry(), loadConfig(formatArgv), formatArgv);
           try {
             app.ok({ commands }, {
               summary: `${commands.length} registered commands — run "jsn <command> --json" for a command's subcommands.`,
@@ -567,7 +575,7 @@ export function buildCLI() {
           }
           process.exit(0);
         }
-        process.stdout.write(renderHelp(loadConfig(), cliInstance.commandRegistry()) + '\n');
+        process.stdout.write(renderHelp(loadConfig(formatArgv), visibleCommandRegistry(cliInstance.commandRegistry(), loadConfig(formatArgv), formatArgv)) + '\n');
         process.exit(0);
       }
       // Every other failure here (unknown command, missing required argument,
@@ -587,6 +595,12 @@ export function buildCLI() {
       exitWithError(new AppError(CodeUsage, msg, hint), { app });
     });
 
+  cliInstance.rootHelpRenderer = () => {
+    const options = cliInstance.parseGlobalOptions(process.argv.slice(2));
+    const config = loadConfig(options);
+    return renderHelp(config, visibleCommandRegistry(cliInstance.commandRegistry(), config, options));
+  };
+
   // Snapshot the root command names (plus aliases) for the completion
   // filter. Done before any parse — command builders mutate the registry.
   rootCommands = cliInstance.getInternalMethods().getCommandInstance().getCommands();

package/src/command-audience.js

@@ -0,0 +1,35 @@
+// Presentation policy only. ServiceNow ACLs still authorize every request.
+// Explicit command paths and --all-commands remain available to every account.
+const BASIC_COMMANDS = new Set([
+  'incidents', 'changes', 'requests', 'tasks', 'tickets', 'approvals', 'records',
+  'groups', 'groupmembers', 'grouproles', 'users', 'setup', 'auth', 'skill',
+  'version', 'docs', 'history', 'discover', 'completion',
+]);
+
+export async function detectCommandAudience(sdk, username, instanceURL = sdk?.baseURL) {
+  if (!username || typeof sdk?.listStrict !== 'function') return undefined;
+  try {
+    const roles = await sdk.listStrict('sys_user_has_role', {
+      sysparm_query: 'user=javascript:gs.getUserID()^role.name=admin',
+      sysparm_fields: 'sys_id', sysparm_limit: '1',
+    }, { touchLastSeen: false });
+    return { username, instance_url: instanceURL, mode: roles.length ? 'admin' : 'basic', role_check: 'verified' };
+  } catch {
+    // Missing role access must not expand help. This is a presentation fallback,
+    // not a claim that the role query succeeded or an authorization boundary.
+    return { username, instance_url: instanceURL, mode: 'basic', role_check: 'unavailable' };
+  }
+}
+
+export function commandAudience(config, { instance, allCommands = false } = {}) {
+  if (allCommands || instance) return 'all';
+  const name = config?.activeProfile || config?.defaultProfile;
+  const profile = config?.profiles?.[name];
+  const cached = profile?.command_audience;
+  return cached?.username === profile?.username && cached?.instance_url === profile?.instance_url && cached?.mode === 'basic' ? 'basic' : 'all';
+}
+
+export function visibleCommandRegistry(registry, config, options = {}) {
+  if (commandAudience(config, options) !== 'basic') return registry;
+  return { ...registry, commands: registry.commands.filter(command => BASIC_COMMANDS.has(command.name)) };
+}

package/src/commands/auth.js

@@ -1,3 +1,4 @@
+import { detectCommandAudience } from '../command-audience.js';
 import { getEffectiveInstance, normalizeInstanceURL, saveConfig, setActiveProfile } from '../config.js';
 import { errUsage, errUsageHint, errConfirmationRequired } from '../errors.js';
 import { canUsePicker, formatCommandList, quoteShellArg } from '../helpers.js';
@@ -710,6 +711,8 @@ Find your instance URL in your browser's address bar when logged into ServiceNow
   // profile exists; preserve it when verification is unavailable.
   username = username || targetUsername;
 
+  const commandAudience = await detectCommandAudience(app.sdk, username, instanceURL);
+
   // Save to profiles — deduplicate by instance URL
   if (!app.config.profiles) {
     app.config.profiles = {};
@@ -740,7 +743,9 @@ Find your instance URL in your browser's address bar when logged into ServiceNow
     read_only: preferences.read_only,
     skip_confirmations: preferences.skip_confirmations,
     include_counts: preferences.include_counts,
+    ...(commandAudience ? { command_audience: commandAudience } : {}),
   };
+  if (!commandAudience) delete app.config.profiles[profileName].command_audience;
   if (!targetProfile && interactive) {
     try {
       const domains = await import('./domains.js');
@@ -1050,12 +1055,22 @@ Examples:
     const name = target.name || app.config.activeProfile || app.config.defaultProfile;
     if (name && app.config.profiles[name] && app.config.profiles[name].instance_url === instanceURL) {
       app.config.profiles[name].domain_separation = hasDS;
+
       await saveConfig(app.config);
     }
   } catch {
     // Non-fatal — capability probe is best-effort
   }
 
+  const audienceName = target.name || app.config.activeProfile || app.config.defaultProfile;
+  const audienceProfile = app.config.profiles?.[audienceName];
+  if (audienceProfile?.instance_url === instanceURL) {
+    const sdk = app.getSDKForProfile
+      ? app.getSDKForProfile(instanceURL, { ...targetAuthOptions, profile: audienceProfile }) : app.sdk;
+    audienceProfile.command_audience = await detectCommandAudience(sdk, audienceProfile.username, instanceURL);
+    await saveConfig(app.config);
+  }
+
   app.ok({
     refreshed: true,
     instance: instanceURL,

package/src/commands/discover.js

@@ -35,7 +35,7 @@ export function discoverCmd(wrap, getRegistry) {
         'Use --json for structured results or --json --get data.commands for only matches.',
       ].join('\n')),
     handler: wrap(async (argv, app) => {
-      const commands = discoverCommands(getRegistry(), { query: argv.query, table: argv.table });
+      const commands = discoverCommands(getRegistry(argv), { query: argv.query, table: argv.table });
       const lines = commands.flatMap(command => [
         `${command.name}: ${command.description}`,
         ...(command.discovery ? [

package/src/commands/midservers.js

@@ -1,8 +1,13 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import process from 'node:process';
-import { input, password as passwordPrompt, select } from '../prompts.js';
+import { input, password as passwordPrompt, select, confirm } from '../prompts.js';
 import { confirmDelete, formatRecordForDisplay, getStringField, interactiveList, canPrompt, assertSafeExactMatch } from '../helpers.js';
+import { AppError, CodeConfirmationRequired } from '../errors.js';
+import { prepareRemoteMidServer, installRemoteMidServer, startRemoteMidServer, stopRemoteMidServer, logsRemoteMidServer, followRemoteMidServer, removeRemoteMidServer } from '../midserver-remote.js';
+import { prepareWindowsRemoteMidServer, installWindowsRemoteMidServer, startWindowsRemoteMidServer, stopWindowsRemoteMidServer, logsWindowsRemoteMidServer, removeWindowsRemoteMidServer } from '../midserver-windows-remote.js';
+import { prepareLinuxRemoteMidServer, installLinuxRemoteMidServer, startLinuxRemoteMidServer, stopLinuxRemoteMidServer, logsLinuxRemoteMidServer, removeLinuxRemoteMidServer } from '../midserver-linux-remote.js';
+import { downloadRemoteMidRecipe } from '../midserver-remote-recipe.js';
 import { FormatAuto } from '../output.js';
 import { declareCapabilities } from '../capabilities.js';
 import { resolveRecord, unwrapSysId } from '../resolve-record.js';
@@ -15,7 +20,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', 'start', 'stop'] });
+declareCapabilities('midservers', { mutationSubcommands: ['add', 'remove', 'execute', 'start', 'stop', 'validate'] });
 
 function agentName(record) {
   const name = getStringField(record, 'name');
@@ -274,6 +279,13 @@ export function assertMidServerReady(record) {
 }
 
 async function promptMidCredentials(app, argv) {
+  if (argv.passwordStdin) {
+    if (!argv.username) throw new Error('--password-stdin requires --username');
+    const password = fs.readFileSync(0, 'utf8').replace(/\r?\n$/, '');
+    if (!password || Buffer.byteLength(password) > 65536 || password.includes('\0')) throw new Error('Invalid password input');
+    const validation = await validateMidCredentials(app.getEffectiveInstance(), argv.username, password);
+    return { username: argv.username, password, releaseName: validation.releaseName };
+  }
   if (!canPrompt()) throw new Error('MID Server installation is interactive. Run it from a terminal.');
   let username = argv.username || '';
   while (true) {
@@ -344,7 +356,31 @@ function removeLocalMidServer(instanceURL, name, directory) {
   return true;
 }
 
+function remoteDirectory(app, argv, name) {
+  const directory = argv.directory || midInstallDirectory(app.getEffectiveInstance(), name);
+  const file = ['.jsn-mid-windows-remote.json', '.jsn-mid-linux-remote.json', '.jsn-mid-remote.json'].find(name => fs.existsSync(path.join(directory, name)));
+  if (!file) throw new Error('No owned remote MID metadata found');
+  const metadata = JSON.parse(fs.readFileSync(path.join(directory, file), 'utf8'));
+  if (metadata.target !== argv.ssh || metadata.instanceURL !== app.getEffectiveInstance().replace(/\/$/, '') || metadata.name !== name) {
+    throw new Error('Remote MID target, instance or name does not match owned local metadata');
+  }
+  return directory;
+}
+
+function nativeRemote(directory) {
+  if (fs.existsSync(path.join(directory, '.jsn-mid-windows-remote.json'))) return { start: startWindowsRemoteMidServer, stop: stopWindowsRemoteMidServer, logs: logsWindowsRemoteMidServer, remove: removeWindowsRemoteMidServer };
+  if (fs.existsSync(path.join(directory, '.jsn-mid-linux-remote.json'))) return { start: startLinuxRemoteMidServer, stop: stopLinuxRemoteMidServer, logs: logsLinuxRemoteMidServer, remove: removeLinuxRemoteMidServer };
+  return null;
+}
+
 async function showMidServerLogs(app, identifier, argv) {
+  if (argv.ssh) {
+    const directory = remoteDirectory(app, argv, identifier);
+    if (argv.follow && nativeRemote(directory)) throw new Error('Remote native logs currently support bounded --tail only');
+    if (argv.follow) return followRemoteMidServer({ directory, tail: argv.tail });
+    const text = (nativeRemote(directory)?.logs || logsRemoteMidServer)({ directory, tail: argv.tail });
+    return app.ok({ target: argv.ssh, text, _formatted: text }, { summary: 'Remote MID logs' });
+  }
   const installDir = argv.directory || midInstallDirectory(app.getEffectiveInstance(), identifier);
   const direct = readDirectInstallation(app.getEffectiveInstance(), identifier, argv.directory);
   if (direct) {
@@ -420,7 +456,8 @@ export function midserversCmd(wrap) {
         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('directory', { type: 'string', describe: 'Local installation directory override' }),
+          .option('directory', { type: 'string', describe: 'Local installation metadata directory override' })
+          .option('ssh', { type: 'string', describe: 'Configured SSH alias for the remote MID target' }),
         handler: wrap(async (argv, app) => {
           await showMidServerLogs(app, argv.identifier, argv);
         }),
@@ -431,16 +468,19 @@ export function midserversCmd(wrap) {
         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('directory', { type: 'string', describe: 'Local installation directory override' }),
+          .option('directory', { type: 'string', describe: 'Local installation metadata directory override' })
+          .option('ssh', { type: 'string', describe: 'Configured SSH alias for the remote MID target' }),
         handler: wrap(async (argv, app) => {
           await 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' }),
+        describe: 'Start an owned MID locally or over SSH (remote Windows uses a service)',
+        builder: b => b.option('directory', { type: 'string', describe: 'Installation directory override' })
+          .option('ssh', { type: 'string', describe: 'Configured SSH alias for the remote MID target' }),
         handler: wrap(async (argv, app) => {
+          if (argv.ssh) { const directory = remoteDirectory(app, argv, argv.identifier); return app.ok((nativeRemote(directory)?.start || startRemoteMidServer)({ directory }), { summary: 'Remote MID start command completed' }); }
           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');
@@ -450,9 +490,11 @@ export function midserversCmd(wrap) {
       })
       .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' }),
+        describe: 'Stop an owned MID locally or over SSH (local Windows console uses Ctrl+C)',
+        builder: b => b.option('directory', { type: 'string', describe: 'Installation directory override' })
+          .option('ssh', { type: 'string', describe: 'Configured SSH alias for the remote MID target' }),
         handler: wrap(async (argv, app) => {
+          if (argv.ssh) { const directory = remoteDirectory(app, argv, argv.identifier); return app.ok((nativeRemote(directory)?.stop || stopRemoteMidServer)({ directory }), { summary: 'Remote MID stop command completed' }); }
           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' });
@@ -463,13 +505,45 @@ export function midserversCmd(wrap) {
         describe: 'Install and verify a MID Server',
         builder: (b) => b
           .option('name', { type: 'string', describe: 'MID Server name (prompted when omitted)' })
-          .option('username', { type: 'string', describe: 'MID Server username (password is always prompted)' })
+          .option('username', { type: 'string', describe: 'MID Server username' })
+          .option('password-stdin', { type: 'boolean', describe: 'Read MID password from stdin instead of a terminal prompt' })
+          .option('ssh', { type: 'string', describe: 'Install MID on a configured SSH target (Docker, native Windows service or Linux background process)' })
+          .option('native-platform', { type: 'string', choices: ['windows', 'linux'], default: 'windows', describe: 'Remote direct ZIP platform (Linux uses a user background process and needs Python 3)' })
           .option('install-method', { type: 'string', choices: ['docker', 'direct'], describe: 'Installation method (prompted when omitted)' })
           .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) => {
           app.requireInstance();
+          if (argv.ssh) {
+            if (!argv.name) throw new Error('Remote installation requires --name');
+            const name = normalizeMidName(argv.name);
+            const existing = await app.sdk.list(AGENT_TABLE, new URLSearchParams({ sysparm_query: `name=${name}`, sysparm_limit: '1', sysparm_fields: 'sys_id' }));
+            if (existing.length) throw new Error('MID name already exists; refusing to adopt an existing MID');
+            const credentials = await promptMidCredentials(app, argv);
+            const directory = argv.directory || midInstallDirectory(app.getEffectiveInstance(), name);
+            fs.mkdirSync(path.dirname(directory), { recursive: true, mode: 0o700 });
+            const native = (argv.installMethod || argv['install-method']) === 'direct';
+            let installation;
+            if (native) {
+              const linux = argv.nativePlatform === 'linux';
+              const prepare = linux ? prepareLinuxRemoteMidServer : prepareWindowsRemoteMidServer;
+              const install = linux ? installLinuxRemoteMidServer : installWindowsRemoteMidServer;
+              const start = linux ? startLinuxRemoteMidServer : startWindowsRemoteMidServer;
+              prepare({ target: argv.ssh, instanceURL: app.getEffectiveInstance(), name, directory });
+              install({ directory, releaseName: credentials.releaseName, username: credentials.username, password: credentials.password });
+              installation = start({ directory });
+            } else {
+              prepareRemoteMidServer({ target: argv.ssh, instanceURL: app.getEffectiveInstance(), name, directory });
+              const context = await downloadRemoteMidRecipe(credentials.releaseName);
+              installation = installRemoteMidServer({ directory, context, username: credentials.username, password: credentials.password });
+            }
+            const kind = native ? (argv.nativePlatform === 'linux' ? 'remote-linux-background' : 'remote-windows-service') : 'remote-docker';
+            let record;
+            try { record = await waitForMidServerUp(app, name, Math.max(1, argv.waitTimeout), Math.max(500, argv.waitInterval)); }
+            catch { return app.ok({ installation: kind, target: argv.ssh, directory, name, registration: 'pending' }, { summary: 'Remote MID started; registration is pending. Runtime and ownership metadata retained for logs or explicit teardown.' }); }
+            return app.ok({ installation: kind, target: argv.ssh, directory, name, registration: 'up', validated: queueValue(record.validated) === 'true', record, runtime_state: installation.state }, { summary: 'Remote MID is Up; validation is a separate explicit operation' });
+          }
           const credentials = await promptMidCredentials(app, argv);
           const name = argv.name || (await input({
             message: 'MID Server name:',
@@ -580,8 +654,19 @@ export function midserversCmd(wrap) {
         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' })
-          .option('directory', { type: 'string', describe: 'Local installation directory override' }),
+          .option('directory', { type: 'string', describe: 'Local installation metadata directory override' })
+          .option('ssh', { type: 'string', describe: 'Configured SSH alias for the remote MID target' }),
         handler: wrap(async (argv, app) => {
+          if (argv.ssh) {
+            if (!argv.identifier) throw new Error('Remote removal requires the owned MID name');
+            const directory = remoteDirectory(app, argv, argv.identifier);
+            await confirmDelete(app, argv, `Remove owned MID '${argv.identifier}' from SSH target '${argv.ssh}' and delete its MID record`);
+            const removed = (nativeRemote(directory)?.remove || removeRemoteMidServer)({ directory });
+            const records = await app.sdk.list(AGENT_TABLE, new URLSearchParams({ sysparm_query: `name=${argv.identifier}`, sysparm_limit: '2', sysparm_fields: 'sys_id,name' }));
+            if (records.length > 1) throw new Error('Remote runtime removed; multiple MID records match. Inspect records before deleting any.');
+            if (records.length) await app.sdk.delete(AGENT_TABLE, unwrapSysId(records[0]));
+            return app.ok({ name: argv.identifier, target: argv.ssh, remote_runtime_removed: removed.state === 'removed', record_deleted: records.length === 1, metadata_directory: directory }, { summary: 'Owned remote MID runtime removed; nonsecret ownership receipt retained' });
+          }
           let record;
           if (argv.identifier) {
             try {
@@ -621,6 +706,28 @@ export function midserversCmd(wrap) {
           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({
+        command: 'validate <identifier>',
+        describe: 'Explicitly trust a MID through the platform Validate action; never writes the validated flag directly',
+        builder: b => b.option('timeout', { type: 'number', default: 300000, describe: 'Validation verification timeout in milliseconds' }),
+        handler: wrap(async (argv, app) => {
+          const record = await resolveMidServer(app.sdk, argv.identifier);
+          assertMidServerUp(record);
+          if (!argv.force) {
+            if (!canPrompt() || app.output.getFormat() !== FormatAuto) throw new AppError(CodeConfirmationRequired, 'MID trust validation requires approval.', 'After approval, rerun with --force.');
+            if (!await confirm({ message: `Trust MID '${getStringField(record, 'name')}' using the platform Validate action?`, default: false })) return;
+          }
+          const cookies = await app.sdk._warmSession(), csrf = await app.sdk._getScriptsPageCSRF(cookies);
+          await app.sdk.rawRequest(`${app.sdk.baseURL}/xmlhttp.do`, { method: 'POST', headers: { Cookie: cookies, 'X-UserToken': csrf }, body: new URLSearchParams({ sysparm_processor: 'MIDServerAjax', sysparm_name: 'validateMID', sysparm_agent: unwrapSysId(record), sysparm_ck: csrf }).toString() });
+          const started = Date.now();
+          while (Date.now() - started < argv.timeout) {
+            const current = await resolveMidServer(app.sdk, argv.identifier);
+            if (queueValue(current.validated) === 'true') return app.ok({ name: getStringField(current, 'name'), validated: true }, { summary: 'MID trust validation verified' });
+            await new Promise(resolve => setTimeout(resolve, 2000));
+          }
+          throw new Error('MID validation was requested but not verified; inspect MID issues before retrying');
+        }),
+      })
       .command({
         command: 'execute [identifier]',
         describe: 'Execute a shell command through a MID Server',

package/src/help.js

@@ -203,6 +203,8 @@ function renderFlags(options) {
 export function renderTips() {
   return `
 TIPS
+  Show every command, including admin and developer tools: "jsn --all-commands --help"
+  Command visibility follows the selected profile at authentication; explicit commands still use ServiceNow ACLs.
   Find commands by task words: "jsn discover catalog"; by configured table: "jsn discover --table incident"
   Cross-table task searches and custom tables: "jsn records list --help"
   Specialized commands offer configured columns, lookup, and table-specific views; inspect discovery results for details

package/src/midserver-linux-remote.js

@@ -0,0 +1,210 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { randomUUID } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { validateRemoteTarget } from './midserver-remote.js';
+import { buildMidZipUrl } from './midserver-direct.js';
+
+const FILE = '.jsn-mid-linux-remote.json';
+// Static program only in argv; all deployment data and credentials travel on stdin.
+const PROGRAM = String.raw`
+import os,sys,json,stat,platform,shutil,subprocess,time,zipfile,urllib.request,hashlib,re,xml.etree.ElementTree as ET
+p=json.load(sys.stdin)
+def fail(): raise RuntimeError('Remote native MID safety check failed')
+def result(v): print('JSN_RESULT:'+json.dumps(v))
+def private(d):
+ s=os.lstat(d)
+ if not stat.S_ISDIR(s.st_mode) or s.st_uid!=os.getuid() or s.st_mode&0o077: fail()
+def ancestors(d):
+ while d!='/':
+  s=os.lstat(d)
+  if not stat.S_ISDIR(s.st_mode) or (s.st_mode&0o022 and not s.st_mode&stat.S_ISVTX): fail()
+  d=os.path.dirname(d)
+def owned():
+ private(p['remoteDirectory']); ancestors(p['remoteDirectory'])
+ f=os.path.join(p['remoteDirectory'],'.jsn-owner.json'); s=os.lstat(f)
+ if not stat.S_ISREG(s.st_mode) or s.st_uid!=os.getuid() or s.st_mode&0o077: fail()
+ m=json.load(open(f))
+ if any(m.get(k)!=p.get(k) for k in ['owner','instanceURL','name','remoteDirectory']): fail()
+def processes():
+ found=[]; agent=os.path.join(p['remoteDirectory'],'agent')
+ for entry in os.listdir('/proc'):
+  if not entry.isdigit(): continue
+  try:
+   proc='/proc/'+entry
+   if os.stat(proc).st_uid!=os.getuid(): continue
+   exe=os.readlink(proc+'/exe'); cwd=os.readlink(proc+'/cwd')
+   if exe in [agent+'/bin/wrapper-linux-x86-64',agent+'/jre/bin/java'] and cwd==agent: found.append(int(entry))
+  except (FileNotFoundError,PermissionError,ProcessLookupError): continue
+ return found
+def safe_tree():
+ for root,dirs,files in os.walk(p['remoteDirectory'],followlinks=False):
+  for name in dirs+files:
+   s=os.lstat(os.path.join(root,name))
+   if not (stat.S_ISREG(s.st_mode) or stat.S_ISDIR(s.st_mode)) or s.st_uid!=os.getuid(): fail()
+def launcher(action):
+ owned(); safe_tree()
+ if action=='stop':
+  pidfile=os.path.join(p['remoteDirectory'],'agent','work','jsn_mid_'+p['owner'].replace('-','')+'.pid')
+  s=os.lstat(pidfile)
+  if not stat.S_ISREG(s.st_mode) or s.st_uid!=os.getuid() or s.st_size>64: fail()
+  value=open(pidfile).read().strip()
+  if not re.fullmatch('[1-9][0-9]*',value) or int(value) not in processes(): fail()
+ subprocess.run(['sh','bin/mid.sh',action],cwd=os.path.join(p['remoteDirectory'],'agent'),stdin=subprocess.DEVNULL,stdout=subprocess.DEVNULL,stderr=subprocess.DEVNULL,check=True,timeout=90,start_new_session=True)
+if platform.system()!='Linux' or platform.machine() not in ['x86_64','amd64'] or os.getuid()==0: fail()
+action=p['action']; d=p.get('remoteDirectory')
+if action=='prepare':
+ home=os.path.expanduser('~'); ancestors(home)
+ if os.lstat(home).st_uid!=os.getuid(): fail()
+ d=os.path.join(home,'.jsn-mid',p['owner'])
+ if os.path.lexists(d): fail()
+ result(dict(remoteDirectory=d,platform='linux-x64',elevated=False,requiresElevation=False,runtime='user-background',freeBytes=shutil.disk_usage(home).free,python=platform.python_version()))
+elif action=='install':
+ if os.path.lexists(d): fail()
+ parent=os.path.dirname(d)
+ if not os.path.exists(parent): os.mkdir(parent,0o700)
+ private(parent); ancestors(parent)
+ if shutil.disk_usage(parent).free<3*1024**3: fail()
+ os.mkdir(d,0o700); os.umask(0o077)
+ marker={k:p[k] for k in ['owner','instanceURL','name','remoteDirectory']}
+ with open(os.path.join(d,'.jsn-owner.json'),'x') as f: json.dump(marker,f)
+ archive=os.path.join(d,'.download.zip')
+ class NoRedirect(urllib.request.HTTPRedirectHandler):
+  def redirect_request(self,*args): fail()
+ opener=urllib.request.build_opener(NoRedirect)
+ total=0; digest=hashlib.sha256()
+ with opener.open(p['archiveURL'],timeout=600) as source,open(archive,'xb') as dest:
+  while True:
+   chunk=source.read(1024*1024)
+   if not chunk: break
+   total+=len(chunk)
+   if total>1024**3: fail()
+   digest.update(chunk); dest.write(chunk)
+ with zipfile.ZipFile(archive) as z:
+  entries=z.infolist(); seen=set(); expanded=0
+  if len(entries)>20000: fail()
+  for e in entries:
+   n=e.filename; parts=n.rstrip('/').split('/'); mode=e.external_attr>>16; kind=stat.S_IFMT(mode)
+   if not parts or parts[0] not in ['agent','META-INF'] or '\\' in n or any(x in ['','.','..'] or any(ord(c)<32 for c in x) for x in parts) or kind not in [0,stat.S_IFDIR,stat.S_IFREG]: fail()
+   if n.rstrip('/') in seen: fail()
+   seen.add(n.rstrip('/')); expanded+=e.file_size
+   if expanded>2*1024**3: fail()
+  for e in entries:
+   dest=os.path.join(d,e.filename)
+   if e.is_dir(): os.makedirs(dest,mode=0o700,exist_ok=True); continue
+   os.makedirs(os.path.dirname(dest),mode=0o700,exist_ok=True)
+   with z.open(e) as source,open(dest,'xb') as target: shutil.copyfileobj(source,target,1024*1024)
+   os.chmod(dest,0o700 if (e.external_attr>>16)&0o111 else 0o600)
+ agent=os.path.join(d,'agent')
+ for name in ['config.xml','conf/wrapper.conf','conf/wrapper-override.conf','bin/mid.sh','bin/wrapper-linux-x86-64','jre/bin/java']:
+  if not os.path.isfile(os.path.join(agent,name)): fail()
+ wrapper=open(os.path.join(agent,'conf/wrapper.conf')).read()
+ script=open(os.path.join(agent,'bin/mid.sh')).read()
+ if 'wrapper.java.command=jre/bin/java' not in wrapper or 'wrapper-override.conf' not in wrapper or 'SERVICE_MANAGEMENT_TOOL' not in script: fail()
+ config=os.path.join(agent,'config.xml'); tree=ET.parse(config,parser=ET.XMLParser(target=ET.TreeBuilder(insert_comments=True))); root=tree.getroot()
+ if root.tag!='parameters': fail()
+ for key,value in {'url':p['instanceURL']+'/','name':p['name'],'mid.instance.username':p['username'],'mid.instance.password':p['password']}.items():
+  nodes=[e for e in root.findall('parameter') if e.get('name')==key]
+  if len(nodes)>1: fail()
+  e=nodes[0] if nodes else ET.SubElement(root,'parameter',{'name':key}); e.set('value',value)
+  if key=='mid.instance.password': e.set('secure','true')
+ tree.write(config,encoding='utf-8',xml_declaration=True)
+ token='jsn_mid_'+p['owner'].replace('-','')
+ with open(os.path.join(agent,'conf/wrapper-override.conf'),'a') as f: f.write('\nwrapper.name='+token+'\nwrapper.displayname=ServiceNow MID '+token+'\n')
+ with open(os.path.join(agent,'bin/mid.shconf_override'),'a') as f: f.write('\nAPP_NAME="'+token+'"\nAPP_LONG_NAME="ServiceNow MID '+token+'"\nSERVICE_MANAGEMENT_TOOL=initd\n')
+ os.unlink(archive); result(dict(installed=True,archiveSha256=digest.hexdigest(),status='stopped'))
+else:
+ owned()
+ if action=='start':
+  if processes(): fail()
+  launcher('start'); time.sleep(2)
+  if not processes(): fail()
+ elif action=='stop':
+  if processes(): launcher('stop')
+  for attempt in range(60):
+   if not processes(): break
+   time.sleep(1)
+  if processes(): fail()
+ elif action=='remove':
+  if processes(): fail()
+  safe_tree(); shutil.rmtree(d); result(dict(removed=True)); sys.exit(0)
+ elif action=='logs':
+  safe_tree()
+  directory=os.path.join(d,'agent','logs'); candidates=[]
+  if os.path.isdir(directory):
+   for n in os.listdir(directory):
+    if re.fullmatch(r'agent0\.log(?:\.[0-9]+)?',n) or n=='wrapper.log':
+     f=os.path.join(directory,n); s=os.lstat(f)
+     if stat.S_ISREG(s.st_mode) and s.st_uid==os.getuid(): candidates.append((n!='wrapper.log',s.st_mtime,f))
+  text=''
+  if candidates:
+   with open(max(candidates)[2],'rb') as f:
+    f.seek(max(0,os.fstat(f.fileno()).st_size-1024*1024)); text=f.read().decode('utf-8','replace')
+  result(dict(logs='\n'.join(text.splitlines()[-p['tail']:]))); sys.exit(0)
+ elif action!='inspect': fail()
+ ids=processes(); result(dict(status='running' if ids else 'stopped',pids=ids,runtime='user-background',requiresElevation=False))
+`;
+
+function remote(target, payload, { run = execFileSync, timeout = 30000 } = {}) {
+  validateRemoteTarget(target);
+  const encoded = Buffer.from(PROGRAM).toString('base64');
+  const command = `python3 -c 'import base64;exec(base64.b64decode("${encoded}"))'`;
+  let output;
+  try { output = String(run('ssh', ['-T', '-o', 'BatchMode=yes', '-o', 'ConnectTimeout=10', '-o', 'RemoteCommand=none', '-o', 'RequestTTY=no', '--', target, command], { input: JSON.stringify(payload), timeout, encoding: 'utf8', maxBuffer: 4 * 1024 * 1024, stdio: ['pipe', 'pipe', 'pipe'] })); }
+  catch { throw new Error('Remote Linux MID operation failed; Python 3 and a non-root Linux x64 account are required. Inspect owned installation before retrying.'); }
+  const line = output.split(/\r?\n/).findLast(value => value.startsWith('JSN_RESULT:'));
+  try { if (!line) throw new Error(); return JSON.parse(line.slice(11)); }
+  catch { throw new Error('Remote Linux MID returned no verified result'); }
+}
+function save(directory, m) { fs.writeFileSync(path.join(directory, FILE), JSON.stringify(m, null, 2), { mode: 0o600 }); fs.chmodSync(path.join(directory, FILE), 0o600); }
+function load(directory) {
+  const dir = fs.lstatSync(directory), file = fs.lstatSync(path.join(directory, FILE));
+  if (!dir.isDirectory() || dir.isSymbolicLink() || !file.isFile() || file.isSymbolicLink() || (dir.mode & 0o077) || (file.mode & 0o077)) throw new Error('Linux MID metadata must be private');
+  const m = JSON.parse(fs.readFileSync(path.join(directory, FILE), 'utf8')); validateRemoteTarget(m.target);
+  if (m.version !== 1 || !/^[a-f0-9-]{36}$/.test(m.owner) || !m.remoteDirectory?.startsWith('/') || m.remoteDirectory !== path.posix.normalize(m.remoteDirectory) || !m.remoteDirectory.endsWith(`/.jsn-mid/${m.owner}`)) throw new Error('Invalid Linux MID ownership metadata');
+  return m;
+}
+export function prepareLinuxRemoteMidServer({ target, instanceURL, name, directory, platform = process.platform, ...options }) {
+  if (platform === 'win32') throw new Error('A POSIX controller is required for private local metadata');
+  validateRemoteTarget(target);
+  const url = new URL(instanceURL);
+  if (url.protocol !== 'https:' || url.username || url.password || url.pathname !== '/' || url.search || url.hash || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name || '')) throw new Error('Valid HTTPS origin and MID name required');
+  if (fs.existsSync(directory)) throw new Error('Local deployment directory exists; no adoption');
+  const owner = randomUUID();
+  const report = remote(target, { action: 'prepare', owner }, options);
+  if (report.platform !== 'linux-x64' || report.requiresElevation !== false || report.freeBytes < 3 * 1024 ** 3 || !report.remoteDirectory?.endsWith(`/.jsn-mid/${owner}`)) throw new Error('Linux preflight failed');
+  const m = { version: 1, target, owner, instanceURL: url.origin, name, ...report, state: 'prepared' };
+  fs.mkdirSync(directory, { mode: 0o700 }); fs.chmodSync(directory, 0o700); save(directory, m); return m;
+}
+export function installLinuxRemoteMidServer({ directory, releaseName, username, password, ...options }) {
+  const m = load(directory);
+  if (m.state !== 'prepared' || !username || !password || [...String(username) + String(password)].some(char => char.codePointAt(0) < 32 && !['\t', '\n', '\r'].includes(char))) throw new Error('Fresh deployment and valid credentials required');
+  const archiveURL = buildMidZipUrl(releaseName, 'linux');
+  m.state = 'installing'; save(directory, m);
+  try {
+    const result = remote(m.target, { ...m, action: 'install', archiveURL, username, password }, { ...options, timeout: 1200000 });
+    if (!result.installed || !/^[a-f0-9]{64}$/i.test(result.archiveSha256 || '')) throw new Error('Installation unverified');
+    Object.assign(m, { state: 'installed', releaseName, archiveSha256: result.archiveSha256 }); save(directory, m); return m;
+  } catch (error) { m.state = 'uncertain'; save(directory, m); throw error; }
+}
+function operation(action, { directory, ...options }) {
+  const m = load(directory);
+  try {
+    const result = remote(m.target, { ...m, action }, { ...options, timeout: action === 'start' || action === 'stop' ? 180000 : 30000 });
+    if ((action === 'start' && result.status !== 'running') || (action === 'stop' && result.status !== 'stopped')) throw new Error('Runtime state unverified');
+    if (action === 'remove' && result.removed !== true) throw new Error('Removal unverified');
+    m.state = action === 'remove' ? 'removed' : result.status; save(directory, m); return { ...m, ...result };
+  } catch (error) { m.state = 'uncertain'; save(directory, m); throw error; }
+}
+export const inspectLinuxRemoteMidServer = options => operation('inspect', options);
+export const startLinuxRemoteMidServer = options => operation('start', options);
+export const stopLinuxRemoteMidServer = options => operation('stop', options);
+export function removeLinuxRemoteMidServer(options) {
+  stopLinuxRemoteMidServer(options);
+  return operation('remove', options);
+}
+export function logsLinuxRemoteMidServer({ directory, tail = 100, ...options }) {
+  if (!Number.isInteger(tail) || tail < 1 || tail > 10000) throw new Error('Log tail must be 1–10000');
+  const m = load(directory); return remote(m.target, { ...m, action: 'logs', tail }, options).logs;
+}

package/src/midserver-remote-recipe.js

@@ -0,0 +1,49 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { buildMidRecipeUrl } from './midserver-install.js';
+import { inspectMidZip, extractMidZip } from './midserver-zip.js';
+
+const LIMIT = 64 * 1024 * 1024;
+export function recipeTar(directory) {
+  const chunks = [];
+  let total = 0;
+  function add(folder, prefix = '') {
+    for (const name of fs.readdirSync(folder).sort()) {
+      const filename = path.join(folder, name), relative = prefix + name, stat = fs.lstatSync(filename);
+      if (stat.isSymbolicLink() || (!stat.isFile() && !stat.isDirectory())) throw new Error('Recipe contains a link or special file');
+      if (stat.isDirectory()) { add(filename, `${relative}/`); continue; }
+      const split = relative.lastIndexOf('/');
+      const leaf = Buffer.byteLength(relative) <= 100 ? relative : relative.slice(split + 1);
+      const parent = Buffer.byteLength(relative) <= 100 ? '' : relative.slice(0, split);
+      if (Buffer.byteLength(leaf) > 100 || Buffer.byteLength(parent) > 155 || split < 0 && Buffer.byteLength(relative) > 100) throw new Error('Recipe path exceeds tar limits');
+      total += stat.size; if (total > LIMIT) throw new Error('MID recipe exceeds 64 MiB');
+      const header = Buffer.alloc(512);
+      const write = (value, offset, length) => header.write(String(value), offset, length, 'utf8');
+      const octal = (value, offset, length) => write(value.toString(8).padStart(length - 1, '0') + '\0', offset, length);
+      write(leaf, 0, 100); octal(stat.mode & 0o111 ? 0o755 : 0o644, 100, 8); octal(0, 108, 8); octal(0, 116, 8);
+      octal(stat.size, 124, 12); octal(0, 136, 12); header.fill(32, 148, 156); write('0', 156, 1); write('ustar\0', 257, 6); write('00', 263, 2); write(parent, 345, 155);
+      const checksum = header.reduce((sum, byte) => sum + byte, 0); write(checksum.toString(8).padStart(6, '0') + '\0 ', 148, 8);
+      chunks.push(header, fs.readFileSync(filename), Buffer.alloc((512 - stat.size % 512) % 512));
+    }
+  }
+  add(directory); chunks.push(Buffer.alloc(1024)); return Buffer.concat(chunks);
+}
+
+export async function downloadRemoteMidRecipe(releaseName, { fetchImpl = fetch } = {}) {
+  const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'jsn-mid-recipe-'));
+  try {
+    const response = await fetchImpl(buildMidRecipeUrl(releaseName), { redirect: 'error', signal: AbortSignal.timeout(300000) });
+    if (!response.ok || !response.body) throw new Error(`MID recipe download failed (HTTP ${response.status})`);
+    const archive = path.join(directory, 'recipe.zip'), fd = fs.openSync(archive, 'wx', 0o600); let bytes = 0;
+    try { for await (const chunk of response.body) { bytes += chunk.length; if (bytes > LIMIT) throw new Error('MID recipe download exceeds 64 MiB'); fs.writeSync(fd, chunk); } } finally { fs.closeSync(fd); }
+    const entries = inspectMidZip(archive, { allowedRoots: null });
+    if (entries.reduce((sum, entry) => sum + entry.uncompressedSize, 0) > LIMIT) throw new Error('Expanded MID recipe exceeds 64 MiB');
+    const recipe = path.join(directory, 'recipe'); await extractMidZip(archive, recipe, entries);
+    // Distribution archives can wrap the Dockerfile in one enclosing directory.
+    const candidates = [];
+    function find(folder) { for (const name of fs.readdirSync(folder)) { const file = path.join(folder, name); if (fs.statSync(file).isDirectory()) find(file); else if (name === 'Dockerfile') candidates.push(path.dirname(file)); } }
+    find(recipe); if (candidates.length !== 1) throw new Error('Official recipe must contain exactly one Dockerfile');
+    return recipeTar(candidates[0]);
+  } finally { fs.rmSync(directory, { recursive: true, force: true }); }
+}

package/src/midserver-remote.js

@@ -0,0 +1,221 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { execFileSync, spawn, spawnSync } from 'node:child_process';
+import process from 'node:process';
+
+const FILE = '.jsn-mid-remote.json';
+const PREFIX = 'io.jsn.mid';
+const SSH_OPTIONS = ['-T', '-o', 'BatchMode=yes', '-o', 'ConnectTimeout=10', '-o', 'RemoteCommand=none', '-o', 'RequestTTY=no', '--'];
+
+export function validateRemoteTarget(target) {
+  if (typeof target !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,252}$/.test(target)) throw new Error('Use a configured SSH alias containing only letters, numbers, dots, underscores or dashes');
+  return target;
+}
+
+function defaultRun(command, args, options) {
+  const { mergeStderr, ...settings } = options;
+  const execution = { ...settings, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'], maxBuffer: 4 * 1024 * 1024 };
+  if (!mergeStderr) return execFileSync(command, args, execution);
+  const result = spawnSync(command, args, execution);
+  if (result.error || result.status !== 0) throw new Error('Remote log snapshot failed');
+  return `${result.stdout || ''}${result.stderr || ''}`;
+}
+
+function sshArgs(target, args) {
+  validateRemoteTarget(target);
+  // OpenSSH joins the command for the remote shell. Every argument is constrained,
+  // including format expressions; secrets and manifests travel only on stdin.
+  if (args.some(arg => typeof arg !== 'string' || !/^[A-Za-z0-9_./:{}=,@+-]+$/.test(arg))) throw new Error('Unsafe remote Docker argument');
+  return [...SSH_OPTIONS, target, `docker ${args.join(' ')}`];
+}
+
+function docker(target, args, { run = defaultRun, input, timeout = 30000, signal, mergeStderr = false } = {}) {
+  const commandArgs = sshArgs(target, args);
+  try { return String(run('ssh', commandArgs, { input, timeout, signal, mergeStderr }) || '').trim(); }
+  catch { throw new Error(`Remote Docker ${args[0]} failed; inspect the selected target and retained local metadata`); }
+}
+
+function probe(target, options) {
+  const platform = docker(target, ['info', '--format', '{{.OSType}}/{{.Architecture}}'], options);
+  if (!/^linux\/(amd64|x86_64)$/.test(platform)) throw new Error('Remote MID containers require a Linux amd64 Docker engine');
+  docker(target, ['compose', 'version'], options);
+  const engineId = docker(target, ['info', '--format', '{{.ID}}'], options);
+  if (!engineId) throw new Error('Remote Docker did not report an engine ID');
+  return engineId;
+}
+
+function save(directory, metadata) {
+  fs.writeFileSync(path.join(directory, FILE), `${JSON.stringify(metadata, null, 2)}\n`, { mode: 0o600 });
+  fs.chmodSync(path.join(directory, FILE), 0o600);
+}
+
+function load(directory) {
+  const dir = fs.lstatSync(directory);
+  const file = fs.lstatSync(path.join(directory, FILE));
+  if (!dir.isDirectory() || dir.isSymbolicLink() || !file.isFile() || file.isSymbolicLink() || (dir.mode & 0o077) || (file.mode & 0o077)) throw new Error('Remote MID metadata directory and file must be private and must not be symlinks');
+  const metadata = JSON.parse(fs.readFileSync(path.join(directory, FILE), 'utf8'));
+  validateRemoteTarget(metadata.target);
+  if (metadata.version !== 1 || !/^[a-f0-9-]{36}$/.test(metadata.owner)) throw new Error('Invalid remote MID ownership metadata');
+  for (const key of ['project', 'container', 'volume', 'image', ...(metadata.network ? ['network'] : [])]) if (!/^[a-z0-9][a-z0-9_.:-]+$/.test(metadata[key])) throw new Error('Invalid remote MID resource metadata');
+  return metadata;
+}
+
+function labels(metadata) {
+  return { [`${PREFIX}.owner`]: metadata.owner, [`${PREFIX}.instance`]: metadata.instanceURL, [`${PREFIX}.target`]: metadata.target, [`${PREFIX}.name`]: metadata.name };
+}
+
+function checkEngine(metadata, options) {
+  if (probe(metadata.target, options) !== metadata.engineId) throw new Error('SSH target now selects a different Docker engine; refusing lifecycle operation');
+}
+
+function inspect(metadata, kind, resource, options) {
+  let value;
+  try { value = JSON.parse(docker(metadata.target, [kind, 'inspect', resource], options))[0]; } catch { throw new Error(`Cannot verify owned remote ${kind}; no destructive action taken`); }
+  const actual = value?.Config?.Labels || value?.Labels;
+  if (!actual || Object.entries(labels(metadata)).some(([key, expected]) => actual[key] !== expected)) throw new Error(`Remote ${kind} ownership mismatch; refusing operation`);
+  return value;
+}
+
+export function prepareRemoteMidServer({ target, instanceURL, name, directory, platform = process.platform, ...options }) {
+  if (platform === 'win32') throw new Error('Remote MID management requires a POSIX controller to enforce private local metadata permissions; Windows Docker hosts remain supported over SSH');
+  validateRemoteTarget(target);
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name || '')) throw new Error('Invalid MID Server name');
+  const url = new URL(instanceURL);
+  if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash || url.pathname !== '/') throw new Error('Use an HTTPS instance origin without credentials');
+  if (fs.existsSync(directory)) throw new Error('Remote MID local directory already exists; refusing to overwrite or adopt');
+  const owner = randomUUID();
+  const project = `jsn-mid-${owner}`;
+  const metadata = { version: 1, target, instanceURL: url.origin, name, owner, project, container: project, image: `${project}:local`, volume: `${project}-export`, network: `${project}-network`, engineId: probe(target, options), state: 'prepared' };
+  fs.mkdirSync(directory, { recursive: false, mode: 0o700 });
+  fs.chmodSync(directory, 0o700);
+  save(directory, metadata);
+  return metadata;
+}
+
+export function buildRemoteMidManifest(metadata, { username, password }) {
+  if (!username || !password) throw new Error('MID username and password are required');
+  const ownership = labels(metadata);
+  const literal = value => String(value).replaceAll('$', () => '$$');
+  return { services: { mid: { container_name: metadata.container, image: metadata.image, pull_policy: 'never', restart: 'unless-stopped', labels: ownership, environment: { MID_INSTANCE_URL: `${metadata.instanceURL}/`, MID_INSTANCE_USERNAME: literal(username), MID_INSTANCE_PASSWORD: literal(password), MID_SERVER_NAME: literal(metadata.name) }, volumes: [`${metadata.volume}:/opt/snc_mid_server/agent/export`], networks: ['mid'] } }, volumes: { [metadata.volume]: { name: metadata.volume, labels: ownership } }, networks: { mid: { name: metadata.network, labels: ownership } } };
+}
+
+function resources(metadata, options) {
+  const checks = [ ['container', ['container', 'ls', '-a', '--filter', `name=${metadata.container}`, '--format', '{{.Names}}'], metadata.container], ['volume', ['volume', 'ls', '--filter', `name=${metadata.volume}`, '--format', '{{.Name}}'], metadata.volume], ['image', ['image', 'ls', '--filter', `reference=${metadata.image}`, '--format', '{{.Repository}}:{{.Tag}}'], metadata.image] ];
+  if (metadata.network) checks.push(['network', ['network', 'ls', '--filter', `name=${metadata.network}`, '--format', '{{.Name}}'], metadata.network]);
+  return checks.filter(([, args, resource]) => docker(metadata.target, args, options).split(/\r?\n/).includes(resource)).map(([kind]) => kind);
+}
+
+function absent(metadata, options) {
+  if (resources(metadata, options).length) throw new Error('Remote resources already exist; refusing to overwrite or adopt');
+}
+
+export function installRemoteMidServer({ directory, context, username, password, ...options }) {
+  const metadata = load(directory);
+  if (metadata.state !== 'prepared') throw new Error('Install requires a fresh prepared deployment; retained partial deployments must be inspected and removed explicitly');
+  if (!Buffer.isBuffer(context) || context.length === 0) throw new Error('An official recipe tar build context is required');
+  const manifest = buildRemoteMidManifest(metadata, { username, password });
+  checkEngine(metadata, options);
+  absent(metadata, options);
+  metadata.state = 'building'; save(directory, metadata);
+  try {
+    const buildLabels = Object.entries(labels(metadata)).flatMap(([key, value]) => ['--label', `${key}=${value}`]);
+    docker(metadata.target, ['build', ...buildLabels, '--tag', metadata.image, '-'], { ...options, input: context, timeout: 1200000 });
+    inspect(metadata, 'image', metadata.image, options);
+    metadata.state = 'deploying'; save(directory, metadata);
+    docker(metadata.target, ['compose', '-p', metadata.project, '-f', '-', 'up', '-d'], { ...options, input: JSON.stringify(manifest), timeout: 300000 });
+    inspect(metadata, 'container', metadata.container, options);
+    inspect(metadata, 'volume', metadata.volume, options);
+    inspect(metadata, 'network', metadata.network, options);
+    metadata.state = 'running'; save(directory, metadata);
+    return metadata;
+  } catch (error) { metadata.state = 'uncertain'; save(directory, metadata); throw error; }
+}
+
+export function inspectRemoteMidServer({ directory, ...options }) {
+  const metadata = load(directory); checkEngine(metadata, options);
+  const container = inspect(metadata, 'container', metadata.container, options);
+  return { ...metadata, status: container.State?.Status || 'unknown' };
+}
+
+function lifecycle(operation, { directory, ...options }) {
+  const metadata = load(directory); checkEngine(metadata, options);
+  inspect(metadata, 'container', metadata.container, options);
+  try { docker(metadata.target, ['container', operation, metadata.container], options); }
+  catch (error) { metadata.state = 'uncertain'; save(directory, metadata); throw error; }
+  metadata.state = operation === 'start' ? 'running' : 'stopped'; save(directory, metadata);
+  return metadata;
+}
+export const startRemoteMidServer = options => lifecycle('start', options);
+export const stopRemoteMidServer = options => lifecycle('stop', options);
+
+export function logsRemoteMidServer({ directory, tail = 100, ...options }) {
+  if (!Number.isInteger(tail) || tail < 1 || tail > 10000) throw new Error('Log tail must be between 1 and 10000');
+  const metadata = load(directory); checkEngine(metadata, options);
+  inspect(metadata, 'container', metadata.container, options);
+  return docker(metadata.target, ['container', 'logs', '--tail', String(tail), metadata.container], { ...options, mergeStderr: true });
+}
+
+export async function followRemoteMidServer({ directory, tail = 100, spawnImpl = spawn, stdout = process.stdout, stderr = process.stderr, signalSource = process, ...options }) {
+  if (!Number.isInteger(tail) || tail < 1 || tail > 10000) throw new Error('Log tail must be between 1 and 10000');
+  const metadata = load(directory); checkEngine(metadata, options);
+  inspect(metadata, 'container', metadata.container, options);
+  const args = sshArgs(metadata.target, ['container', 'logs', '--follow', '--tail', String(tail), metadata.container]);
+  return new Promise((resolve, reject) => {
+    let child;
+    let cancelled = false;
+    let timer;
+    let settled = false;
+    const cleanup = () => {
+      signalSource.removeListener('SIGINT', cancel);
+      clearTimeout(timer);
+      child?.stdout?.unpipe(stdout);
+      child?.stderr?.unpipe(stderr);
+      child?.removeListener('error', failed);
+      child?.removeListener('close', closed);
+    };
+    const finish = error => {
+      if (settled) return;
+      settled = true; cleanup();
+      if (error) reject(new Error('Remote Docker log viewer failed; the container was not stopped'));
+      else resolve({ cancelled });
+    };
+    const failed = () => finish(true);
+    const closed = code => finish(!cancelled && code !== 0);
+    const cancel = () => {
+      if (cancelled || settled) return;
+      cancelled = true;
+      child.kill('SIGINT');
+      timer = setTimeout(() => { child.kill('SIGKILL'); finish(false); }, 2000);
+      timer.unref?.();
+    };
+    try {
+      child = spawnImpl('ssh', args, { stdio: ['ignore', 'pipe', 'pipe'] });
+      child.on('error', failed);
+      child.on('close', closed);
+      child.stdout?.pipe(stdout, { end: false });
+      child.stderr?.pipe(stderr, { end: false });
+      signalSource.on('SIGINT', cancel);
+    } catch { finish(true); }
+  });
+}
+
+export function removeRemoteMidServer({ directory, ...options }) {
+  const metadata = load(directory); checkEngine(metadata, options);
+  // A partial install may have only an image or volume. Verify every present
+  // resource before deleting any, and preserve metadata for retries/diagnosis.
+  const present = resources(metadata, options);
+  for (const kind of present) inspect(metadata, kind, metadata[kind], options);
+  metadata.state = 'removing'; save(directory, metadata);
+  try {
+    if (present.includes('container')) {
+      docker(metadata.target, ['container', 'stop', metadata.container], options);
+      docker(metadata.target, ['container', 'rm', metadata.container], options);
+    }
+    if (present.includes('volume')) docker(metadata.target, ['volume', 'rm', metadata.volume], options);
+    if (present.includes('network')) docker(metadata.target, ['network', 'rm', metadata.network], options);
+    if (present.includes('image')) docker(metadata.target, ['image', 'rm', metadata.image], options);
+  } catch (error) { metadata.state = 'uncertain'; save(directory, metadata); throw error; }
+  metadata.state = 'removed'; save(directory, metadata);
+  return metadata;
+}

package/src/midserver-windows-remote.js

@@ -0,0 +1,318 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { randomUUID } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { validateRemoteTarget } from './midserver-remote.js';
+import { buildMidZipUrl } from './midserver-direct.js';
+
+const FILE = '.jsn-mid-windows-remote.json';
+const SSH = ['-T', '-o', 'BatchMode=yes', '-o', 'ConnectTimeout=10', '-o', 'RemoteCommand=none', '-o', 'RequestTTY=no', '--'];
+const PHASES = new Set(['initialization', 'validate', 'reserve-directory', 'protect-directory', 'download', 'verify-archive', 'inspect-archive', 'extract', 'vendor-contract', 'configure', 'register-service', 'verify-service', 'enforce-permissions', 'remove-files', 'recover-file-acl', 'stop-owned-processes']);
+const HEADER = `$ErrorActionPreference='Stop'; $ProgressPreference='SilentlyContinue'; $phase='initialization';
+trap { [Console]::Error.WriteLine(('JSN_PHASE_FAILED:' + $phase)); exit 1 }
+$p=([Console]::In.ReadToEnd() | ConvertFrom-Json)
+function Result($v) { [Console]::Out.WriteLine(('JSN_RESULT:' + ($v | ConvertTo-Json -Compress -Depth 8))) }
+function Assert-Admin { if ($env:OS -ne 'Windows_NT') { throw 'Windows required' }; $i=[Security.Principal.WindowsIdentity]::GetCurrent(); $principal=New-Object Security.Principal.WindowsPrincipal($i); if (!$principal.IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)) { throw 'Elevated service installation rights required' } }
+function Assert-Owned {
+  Assert-Admin
+  if (!(Test-Path -LiteralPath $p.remoteDirectory -PathType Container)) { throw 'Owned directory missing' }
+  $item=Get-Item -LiteralPath $p.remoteDirectory
+  if ($item.Attributes -band [IO.FileAttributes]::ReparsePoint) { throw 'Reparse point forbidden' }
+  $marker=Get-Content -Raw -LiteralPath (Join-Path $p.remoteDirectory '.jsn-owner.json') | ConvertFrom-Json
+  if ($marker.owner -ne $p.owner -or $marker.serviceName -ne $p.serviceName -or $marker.instanceURL -ne $p.instanceURL -or $marker.name -ne $p.name) { throw 'Ownership mismatch' }
+}
+function Owned-Service {
+  $s=Get-CimInstance Win32_Service -Filter ('Name="' + $p.serviceName + '"')
+  if ($s) {
+    $expected=[IO.Path]::GetFullPath((Join-Path $p.remoteDirectory 'agent\\bin\\wrapper-windows-x86-64.exe'))
+    $command=[regex]::Match($s.PathName,'^\\s*(?:"([^"\\r\\n]+)"|(.+?\\.exe))(?:\\s|$)',[Text.RegularExpressions.RegexOptions]::IgnoreCase)
+    if (!$command.Success) { throw 'Service binary ownership mismatch' }
+    $binary=$command.Groups[1].Value; if (!$binary) { $binary=$command.Groups[2].Value }
+    if ([IO.Path]::GetFullPath($binary) -ne $expected) { throw 'Service binary ownership mismatch' }
+    if ($s.StartName -ne 'NT AUTHORITY\\LocalService' -and $s.StartName -ne 'LocalService') { throw 'Unexpected runtime service account' }
+  }
+  return $s
+}
+`;
+
+function remote(target, script, payload, { run = execFileSync, timeout = 30000 } = {}) {
+  validateRemoteTarget(target);
+  const bootstrap = `$ErrorActionPreference='Stop'; try { [Console]::InputEncoding=New-Object Text.UTF8Encoding($false); [Console]::OutputEncoding=New-Object Text.UTF8Encoding($false); $source=[Text.Encoding]::UTF8.GetString([Convert]::FromBase64String([Console]::In.ReadLine())); & ([ScriptBlock]::Create($source)) } catch { [Console]::Error.WriteLine('Remote MID bootstrap failed'); exit 1 }`;
+  const encoded = Buffer.from(bootstrap, 'utf16le').toString('base64');
+  const input = `${Buffer.from(HEADER + script, 'utf8').toString('base64')}\n${JSON.stringify(payload)}`;
+  let output;
+  try { output = String(run('ssh', [...SSH, target, `powershell.exe -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass -EncodedCommand ${encoded}`], { input, timeout, encoding: 'utf8', maxBuffer: 4 * 1024 * 1024, stdio: ['pipe', 'pipe', 'pipe'] })); }
+  catch (error) {
+    const candidate = String(error.stderr || '').split(/\r?\n/).findLast(line => /^JSN_PHASE_FAILED:[a-z-]+$/.test(line));
+    const phase = candidate?.slice('JSN_PHASE_FAILED:'.length);
+    const failure = new Error(`Remote Windows MID operation failed${PHASES.has(phase) ? ` during ${phase}` : ''}; inspect retained ownership metadata and service status`);
+    if (PHASES.has(phase)) failure.phase = phase;
+    throw failure;
+  }
+  const line = output.split(/\r?\n/).findLast(value => value.startsWith('JSN_RESULT:'));
+  if (!line) throw new Error('Remote Windows MID returned no verified result');
+  try { return JSON.parse(line.slice('JSN_RESULT:'.length)); } catch { throw new Error('Invalid remote Windows MID result'); }
+}
+
+function save(directory, metadata) {
+  fs.writeFileSync(path.join(directory, FILE), `${JSON.stringify(metadata, null, 2)}\n`, { mode: 0o600 });
+  fs.chmodSync(path.join(directory, FILE), 0o600);
+}
+function load(directory) {
+  const dir = fs.lstatSync(directory); const file = fs.lstatSync(path.join(directory, FILE));
+  if (!dir.isDirectory() || dir.isSymbolicLink() || !file.isFile() || file.isSymbolicLink() || (dir.mode & 0o077) || (file.mode & 0o077)) throw new Error('Windows MID local metadata must be private');
+  const m = JSON.parse(fs.readFileSync(path.join(directory, FILE), 'utf8'));
+  validateRemoteTarget(m.target);
+  if (m.version !== 1 || !/^[a-f0-9-]{36}$/.test(m.owner) || m.serviceName !== `jsn-mid-${m.owner}` || !/^[A-Z]:\\[A-Za-z0-9 _.-]+(?:\\[A-Za-z0-9 _.-]+)*$/i.test(m.remoteDirectory) || !m.remoteDirectory.endsWith(`\\${m.owner}`)) throw new Error('Invalid Windows MID ownership metadata');
+  return m;
+}
+
+export function prepareWindowsRemoteMidServer({ target, instanceURL, name, directory, platform = process.platform, ...options }) {
+  if (platform === 'win32') throw new Error('A POSIX controller is required for private local metadata');
+  validateRemoteTarget(target);
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name || '')) throw new Error('Invalid MID name');
+  const url = new URL(instanceURL);
+  if (url.protocol !== 'https:' || url.username || url.password || url.pathname !== '/' || url.search || url.hash) throw new Error('Use an HTTPS instance origin');
+  if (fs.existsSync(directory)) throw new Error('Local deployment directory already exists; no adoption or overwrite');
+  const owner = randomUUID(); const serviceName = `jsn-mid-${owner}`;
+  const probe = remote(target, `Assert-Admin
+if ([Environment]::Is64BitOperatingSystem -ne $true) { throw 'x64 Windows required' }
+$base=Join-Path $env:ProgramData 'jsn-mid'
+$remoteDirectory=Join-Path $base $p.owner
+if (Test-Path -LiteralPath $remoteDirectory) { throw 'Deployment directory exists' }
+if (Get-Service -Name $p.serviceName -ErrorAction SilentlyContinue) { throw 'Service already exists' }
+Result @{remoteDirectory=$remoteDirectory; elevated=$true; platform='windows-x64'}`, { owner, serviceName }, options);
+  if (!probe.elevated || probe.platform !== 'windows-x64' || !probe.remoteDirectory?.endsWith(`\\${owner}`)) throw new Error('Windows preflight failed');
+  const metadata = { version: 1, target, owner, serviceName, instanceURL: url.origin, name, remoteDirectory: probe.remoteDirectory, state: 'prepared', runtimeAccount: 'NT AUTHORITY\\LocalService' };
+  fs.mkdirSync(directory, { mode: 0o700 }); fs.chmodSync(directory, 0o700); save(directory, metadata);
+  return metadata;
+}
+
+const INSTALL = String.raw`$phase='validate'; Assert-Admin
+if (Get-Service -Name $p.serviceName -ErrorAction SilentlyContinue) { throw 'Service already exists; no adoption' }
+if (Test-Path -LiteralPath $p.remoteDirectory) { throw 'Directory already exists; no adoption' }
+$phase='reserve-directory'
+$parent=Split-Path -Parent $p.remoteDirectory
+if (!(Test-Path -LiteralPath $parent)) { $null=New-Item -ItemType Directory -Path $parent }
+$ancestor=Get-Item -LiteralPath $parent
+while ($ancestor) { if ($ancestor.Attributes -band [IO.FileAttributes]::ReparsePoint) { throw 'Reparse ancestor forbidden' }; $ancestor=$ancestor.Parent }
+$null=New-Item -ItemType Directory -Path $p.remoteDirectory
+$phase='protect-directory'
+$sid=[Security.Principal.WindowsIdentity]::GetCurrent().User
+$acl=New-Object Security.AccessControl.DirectorySecurity
+$acl.SetOwner($sid); $acl.SetAccessRuleProtection($true,$false)
+foreach ($id in @($sid.Value,'S-1-5-18','S-1-5-32-544') | Select-Object -Unique) {
+  $who=New-Object Security.Principal.SecurityIdentifier($id)
+  $acl.AddAccessRule((New-Object Security.AccessControl.FileSystemAccessRule($who,'FullControl','ContainerInherit,ObjectInherit','None','Allow')))
+}
+$localService=New-Object Security.Principal.SecurityIdentifier('S-1-5-19')
+$acl.AddAccessRule((New-Object Security.AccessControl.FileSystemAccessRule($localService,'Modify','ContainerInherit,ObjectInherit','None','Allow')))
+Set-Acl -LiteralPath $p.remoteDirectory -AclObject $acl
+$actual=Get-Acl -LiteralPath $p.remoteDirectory
+if (!$actual.AreAccessRulesProtected) { throw 'ACL protection failed' }
+$allowed=@($sid.Value,'S-1-5-18','S-1-5-32-544','S-1-5-19')
+foreach ($r in $actual.Access) { if ($r.AccessControlType -ne 'Allow' -or $r.IdentityReference.Translate([Security.Principal.SecurityIdentifier]).Value -notin $allowed) { throw 'Unexpected ACL rule' } }
+$marker=@{owner=$p.owner;serviceName=$p.serviceName;instanceURL=$p.instanceURL;name=$p.name}
+$marker | ConvertTo-Json -Compress | Set-Content -Encoding UTF8 -LiteralPath (Join-Path $p.remoteDirectory '.jsn-owner.json')
+$phase='download'
+$archive=Join-Path $p.remoteDirectory '.download.zip'
+if ($p.archivePath) { Copy-Item -LiteralPath $p.archivePath -Destination $archive } else { [Net.ServicePointManager]::SecurityProtocol=[Net.SecurityProtocolType]::Tls12; Invoke-WebRequest -UseBasicParsing -Uri $p.archiveURL -OutFile $archive -TimeoutSec 600 }
+$phase='verify-archive'
+if ((Get-Item -LiteralPath $archive).Length -gt 1GB) { throw 'Archive too large' }
+$archiveHash=(Get-FileHash -Algorithm SHA256 -LiteralPath $archive).Hash
+if ($p.archiveSha256 -and $archiveHash -ne $p.archiveSha256) { throw 'Archive hash mismatch' }
+$phase='inspect-archive'
+Add-Type -AssemblyName System.IO.Compression.FileSystem
+$zip=[IO.Compression.ZipFile]::OpenRead($archive)
+try {
+  if ($zip.Entries.Count -gt 20000) { throw 'Too many archive entries' }
+  $total=0; $seen=@{}
+  foreach ($entry in $zip.Entries) {
+    $entryName=$entry.FullName
+    if ($entryName.Contains('\') -or $entryName.StartsWith('/') -or $entryName.Contains(':')) { throw 'Unsafe archive path' }
+    $parts=$entryName.TrimEnd('/').Split('/')
+    if ($parts[0] -notin @('agent','META-INF')) { throw 'Unexpected archive root' }
+    foreach ($part in $parts) { if (!$part -or $part -eq '.' -or $part -eq '..' -or $part -match '[<>"|?*\x00-\x1f]' -or $part -match '[. ]$' -or $part -match '^(?i:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)') { throw 'Unsafe archive entry' } }
+    $key=$entryName.TrimEnd('/').ToLowerInvariant(); if ($seen.ContainsKey($key)) { throw 'Duplicate archive entry' }; $seen[$key]=$true
+    $mode=($entry.ExternalAttributes -shr 16) -band 0xF000
+    if ($mode -ne 0 -and $mode -ne 0x8000 -and $mode -ne 0x4000) { throw 'Archive links forbidden' }
+    $total+=$entry.Length; if ($total -gt 2GB) { throw 'Expanded archive too large' }
+  }
+} finally { $zip.Dispose() }
+$phase='extract'
+Expand-Archive -LiteralPath $archive -DestinationPath $p.remoteDirectory
+Remove-Item -LiteralPath $archive
+$phase='vendor-contract'
+$agent=Join-Path $p.remoteDirectory 'agent'
+foreach ($relative in @('config.xml','conf\wrapper.conf','conf\wrapper-override.conf','bin\mid.bat','bin\wrapper-windows-x86-64.exe','jre\bin\java.exe')) { if (!(Test-Path -LiteralPath (Join-Path $agent $relative) -PathType Leaf)) { throw 'Unsupported vendor ZIP layout' } }
+$batch=Get-Content -Raw -LiteralPath (Join-Path $agent 'bin\mid.bat')
+$wrapper=Get-Content -Raw -LiteralPath (Join-Path $agent 'conf\wrapper.conf')
+if ($batch -notmatch '\[install\]' -or $batch -notmatch '\[remove\]' -or $batch -notmatch '(?m)^\s*%_WRAPPER_EXE% -i ' -or $batch -notmatch '(?m)^\s*%_WRAPPER_EXE% -r ' -or $wrapper -notmatch '(?m)^wrapper.java.command=jre/bin/java' -or $wrapper -notmatch '(?m)^#include ../conf/wrapper-override.conf') { throw 'Unsupported vendor service contract' }
+$modules=@(Get-ChildItem -LiteralPath $agent -Filter 'EnforceFilePermissions.psm1' -File -Recurse)
+if ($modules.Count -ne 1 -or (Get-Content -Raw -LiteralPath $modules[0].FullName) -notmatch 'function\s+enforcePerms\s*\{') { throw 'Unsupported vendor permission enforcement contract' }
+$phase='configure'
+$config=Join-Path $agent 'config.xml'
+$xml=New-Object Xml.XmlDocument; $xml.XmlResolver=$null; $xml.PreserveWhitespace=$true; $xml.Load($config)
+if ($xml.DocumentElement.Name -ne 'parameters') { throw 'Unsupported configuration XML root' }
+$values=@{url=($p.instanceURL+'/');'mid.instance.username'=$p.username;'mid.instance.password'=$p.password;name=$p.name;'mid.windows_host.file_permissions.allow_list'='S-1-5-19'}
+foreach ($key in @($values.Keys)) {
+  $nodes=@($xml.SelectNodes('/parameters/parameter') | Where-Object { $_.GetAttribute('name') -eq $key })
+  if ($nodes.Count -gt 1) { throw 'Duplicate configuration parameter' }
+  if ($nodes.Count -eq 0) { $node=$xml.CreateElement('parameter'); $node.SetAttribute('name',$key); $null=$xml.DocumentElement.AppendChild($node) } else { $node=$nodes[0] }
+  if ($key -eq 'mid.windows_host.file_permissions.allow_list') {
+    $entries=@($node.GetAttribute('value').Split(',') | ForEach-Object { $_.Trim() } | Where-Object { $_ })
+    $values[$key]=(@($entries + 'S-1-5-19') | Select-Object -Unique) -join ','
+  }
+  $node.SetAttribute('value',[string]$values[$key])
+  if ($key -eq 'mid.instance.password' -and !$node.HasAttribute('secure')) { $node.SetAttribute('secure','true') }
+}
+$xml.Save($config)
+$override=Join-Path $agent 'conf\wrapper-override.conf'
+$text=Get-Content -Raw -LiteralPath $override
+$text=[regex]::Replace($text,'(?m)^wrapper\.(?:name|displayname|ntservice\.(?:account|account\.prompt|password|password\.prompt|starttype|permissions\.1\.(?:account|allow|service)))=.*\r?$','')
+$text+="
+wrapper.name=$($p.serviceName)
+wrapper.displayname=ServiceNow MID $($p.serviceName)
+wrapper.ntservice.account=NT AUTHORITY\LocalService
+wrapper.ntservice.password=
+wrapper.ntservice.account.prompt=FALSE
+wrapper.ntservice.password.prompt=FALSE
+wrapper.ntservice.starttype=AUTO_START
+wrapper.ntservice.permissions.1.account=NT AUTHORITY\LocalService
+wrapper.ntservice.permissions.1.allow=START, STOP
+wrapper.ntservice.permissions.1.service=$($p.serviceName)
+"
+[IO.File]::WriteAllText($override,$text,(New-Object Text.UTF8Encoding($false)))
+$phase='register-service'
+Push-Location $agent
+try { & cmd.exe /d /s /c 'bin\mid.bat install' 2>&1 | Out-Null; if ($LASTEXITCODE -ne 0) { throw 'Vendor install failed' } } finally { Pop-Location }
+$phase='verify-service'
+Assert-Owned; $s=Owned-Service; if (!$s) { throw 'Service registration missing' }
+if ($s.StartMode -ne 'Auto') { throw 'Service automatic startup was not configured' }
+$phase='enforce-permissions'
+Import-Module -Name $modules[0].FullName -Force -ErrorAction Stop
+$enforce=Get-Command -Name enforcePerms -CommandType Function -ErrorAction Stop
+if ($enforce.Module.Path -ne $modules[0].FullName) { throw 'Wrong enforcement module' }
+# The vendor allow-list includes a second service principal when USERDOMAIN
+# resolves it. Match the LocalService runtime context so its saved list/hash is
+# identical on startup; let the unmodified vendor module compute the hash.
+$previousUserDomain=$env:USERDOMAIN
+try {
+  $env:USERDOMAIN=($s.StartName -split '\\',2)[0]
+  enforcePerms -folder $agent -serviceName $p.serviceName -debug $false -additionWhiteListedGroups $values['mid.windows_host.file_permissions.allow_list'] | Out-Null
+} finally { $env:USERDOMAIN=$previousUserDomain }
+$serviceRules=@((Get-Acl -LiteralPath $agent).Access | Where-Object { $_.AccessControlType -eq 'Allow' -and $_.IdentityReference.Translate([Security.Principal.SecurityIdentifier]).Value -eq 'S-1-5-19' -and ($_.FileSystemRights -band [Security.AccessControl.FileSystemRights]::FullControl) -eq [Security.AccessControl.FileSystemRights]::FullControl })
+if (!$serviceRules.Count) { throw 'Runtime account lacks enforced permissions' }
+foreach ($receipt in @('fileperm.aclsave','fileperm.grphash')) { if (!(Test-Path -LiteralPath (Join-Path (Join-Path $agent 'etc') $receipt) -PathType Leaf)) { throw 'Vendor enforcement receipt missing' } }
+Result @{status=$s.State;runtimeAccount=$s.StartName;serviceRegistered=$true;archiveSha256=$archiveHash;startMode=$s.StartMode}
+`;
+
+export function installWindowsRemoteMidServer({ directory, releaseName, username, password, archivePath, archiveSha256, ...options }) {
+  const m = load(directory);
+  if (m.state !== 'prepared') throw new Error('Install requires a fresh prepared deployment');
+  if (!username || !password || [...String(username) + String(password)].some(char => char.codePointAt(0) < 32 && !['\t', '\n', '\r'].includes(char))) throw new Error('Valid MID credentials are required');
+  const archiveURL = buildMidZipUrl(releaseName, 'win32');
+  if (archiveSha256 && !/^[a-f0-9]{64}$/i.test(archiveSha256)) throw new Error('Invalid archive SHA256');
+  if (archivePath && (!archiveSha256 || !/^[A-Z]:\\[A-Za-z0-9 _.-]+(?:\\[A-Za-z0-9 _.-]+)*$/i.test(archivePath))) throw new Error('Cached remote archive requires an absolute safe path and inspected SHA256');
+  m.state = 'installing'; m.releaseName = releaseName; save(directory, m);
+  try {
+    const result = remote(m.target, INSTALL, { ...m, archiveURL, username, password, archivePath, archiveSha256 }, { ...options, timeout: 1200000 });
+    if (!result.serviceRegistered || !['NT AUTHORITY\\LocalService', 'LocalService'].includes(result.runtimeAccount)) throw new Error('Service installation was not verified under LocalService');
+    if (result.startMode !== 'Auto') throw new Error('Service automatic startup was not verified');
+    if (!/^[a-f0-9]{64}$/i.test(result.archiveSha256 || '')) throw new Error('Archive hash verification result missing');
+    m.startMode = result.startMode; m.archiveSha256 = result.archiveSha256.toLowerCase(); m.state = 'installed'; save(directory, m); return m;
+  } catch (error) { m.state = 'uncertain'; if (error.phase) m.failedPhase = error.phase; save(directory, m); throw error; }
+}
+
+export function removeWindowsRemoteMidServer({ directory, ...options }) {
+  const m = load(directory);
+  m.state = 'removing'; save(directory, m);
+  try {
+    remote(m.target, String.raw`Assert-Owned; $s=Owned-Service
+if ($s) {
+  Stop-Service -Name $p.serviceName -ErrorAction Stop
+  (Get-Service -Name $p.serviceName).WaitForStatus('Stopped',[TimeSpan]::FromSeconds(60))
+  $null=Owned-Service
+  $agent=Join-Path $p.remoteDirectory 'agent'
+  Push-Location $agent
+  try { & cmd.exe /d /s /c 'bin\mid.bat remove' 2>&1 | Out-Null; if ($LASTEXITCODE -ne 0) { throw 'Vendor removal failed' } } finally { Pop-Location }
+  $deadline=(Get-Date).AddSeconds(30)
+  while (Get-Service -Name $p.serviceName -ErrorAction SilentlyContinue) { if ((Get-Date) -gt $deadline) { throw 'Service still registered' }; Start-Sleep -Milliseconds 500 }
+}
+Assert-Owned
+$links=@(Get-ChildItem -LiteralPath $p.remoteDirectory -Force -Recurse | Where-Object { $_.Attributes -band [IO.FileAttributes]::ReparsePoint })
+if ($links.Count) { throw 'Refusing recursive cleanup through reparse points' }
+$phase='stop-owned-processes'
+if (Get-Service -Name $p.serviceName -ErrorAction SilentlyContinue) { throw 'Service still registered; refusing process cleanup' }
+$ownedBinaries=@('agent\bin\wrapper-windows-x86-64.exe','agent\bin\wrapper.exe','agent\jre\bin\java.exe') | ForEach-Object { [IO.Path]::GetFullPath((Join-Path $p.remoteDirectory $_)) }
+$candidates=@(Get-CimInstance Win32_Process | Where-Object { $_.ExecutablePath -and [IO.Path]::GetFullPath($_.ExecutablePath) -in $ownedBinaries })
+foreach ($candidate in $candidates) {
+  $current=Get-CimInstance Win32_Process -Filter ('ProcessId=' + [uint32]$candidate.ProcessId)
+  if (!$current) { continue }
+  if (!$current.ExecutablePath -or [IO.Path]::GetFullPath($current.ExecutablePath) -notin $ownedBinaries -or $current.ExecutablePath -ne $candidate.ExecutablePath -or $current.CreationDate -ne $candidate.CreationDate) { throw 'Owned process identity changed; refusing to kill reused PID' }
+  $process=Get-Process -Id $current.ProcessId -ErrorAction Stop
+  try {
+    $null=$process.Handle
+    if (!$process.Path -or [IO.Path]::GetFullPath($process.Path) -ne [IO.Path]::GetFullPath($current.ExecutablePath)) { throw 'Process executable changed' }
+    $process.Kill()
+    if (!$process.WaitForExit(30000)) { throw 'Owned process did not exit' }
+  } finally { $process.Dispose() }
+}
+$remaining=@(Get-CimInstance Win32_Process | Where-Object { $_.ExecutablePath -and [IO.Path]::GetFullPath($_.ExecutablePath) -in $ownedBinaries })
+if ($remaining.Count) { throw 'Owned runtime process remains; files retained' }
+function Remove-OwnedFiles {
+  # Keep the owner receipt until all other children are gone, allowing a failed
+  # teardown to be safely retried without adopting an unmarked directory.
+  Get-ChildItem -LiteralPath $p.remoteDirectory -Force | Where-Object { $_.Name -ne '.jsn-owner.json' } | ForEach-Object { Remove-Item -LiteralPath $_.FullName -Recurse -Force -ErrorAction Stop }
+  $receipt=Join-Path $p.remoteDirectory '.jsn-owner.json'
+  if (Test-Path -LiteralPath $receipt) { Remove-Item -LiteralPath $receipt -Force -ErrorAction Stop }
+  Remove-Item -LiteralPath $p.remoteDirectory -Force -ErrorAction Stop
+}
+$phase='remove-files'
+try { Remove-OwnedFiles } catch [UnauthorizedAccessException] {
+  $phase='recover-file-acl'
+  # Service absence and the full tree scan were verified above. Do not expand
+  # recovery to any parent, sibling, global policy or unowned service.
+  if (Get-Service -Name $p.serviceName -ErrorAction SilentlyContinue) { throw 'Service reappeared; refusing ACL recovery' }
+  $remainingLinks=@(Get-ChildItem -LiteralPath $p.remoteDirectory -Force -Recurse | Where-Object { $_.Attributes -band [IO.FileAttributes]::ReparsePoint })
+  if ($remainingLinks.Count) { throw 'Refusing ACL recovery through reparse points' }
+  & takeown.exe /F $p.remoteDirectory /R /D Y 2>&1 | Out-Null
+  if ($LASTEXITCODE -ne 0) { throw 'Scoped ownership recovery failed; localized takeown prompts may require manual recovery' }
+  $controllerSid=[Security.Principal.WindowsIdentity]::GetCurrent().User.Value
+  $grant='*' + $controllerSid + ':(OI)(CI)F'
+  & icacls.exe $p.remoteDirectory /grant $grant /T /C 2>&1 | Out-Null
+  if ($LASTEXITCODE -ne 0) { throw 'Scoped controller ACL recovery failed' }
+  $phase='remove-files'
+  Remove-OwnedFiles
+}
+if (Test-Path -LiteralPath $p.remoteDirectory) { throw 'Owned directory remains' }
+Result @{removed=$true}`, m, { ...options, timeout: 180000 });
+    m.state = 'removed'; save(directory, m); return m;
+  } catch (error) { m.state = 'uncertain'; if (error.phase) m.failedPhase = error.phase; save(directory, m); throw error; }
+}
+
+export function inspectWindowsRemoteMidServer({ directory, ...options }) {
+  const m = load(directory);
+  return { ...m, ...remote(m.target, `Assert-Owned; $s=Owned-Service; if (!$s) { throw 'Service missing' }; Result @{status=$s.State; runtimeAccount=$s.StartName; startMode=$s.StartMode}`, m, options) };
+}
+
+function lifecycle(operation, { directory, ...options }) {
+  const m = load(directory);
+  try {
+    remote(m.target, `Assert-Owned; $s=Owned-Service; if (!$s) { throw 'Service missing' }; ${operation}-Service -Name $p.serviceName -ErrorAction Stop
+(Get-Service -Name $p.serviceName).WaitForStatus('${operation === 'Start' ? 'Running' : 'Stopped'}',[TimeSpan]::FromSeconds(60))
+Result @{status='${operation === 'Start' ? 'Running' : 'Stopped'}'}`, m, { ...options, timeout: 90000 });
+    m.state = operation === 'Start' ? 'running' : 'stopped'; save(directory, m); return m;
+  } catch (error) { m.state = 'uncertain'; if (error.phase) m.failedPhase = error.phase; save(directory, m); throw error; }
+}
+export const startWindowsRemoteMidServer = options => lifecycle('Start', options);
+export const stopWindowsRemoteMidServer = options => lifecycle('Stop', options);
+
+export function logsWindowsRemoteMidServer({ directory, tail = 100, ...options }) {
+  if (!Number.isInteger(tail) || tail < 1 || tail > 10000) throw new Error('Log tail must be between 1 and 10000');
+  const m = load(directory);
+  return remote(m.target, `Assert-Owned; $null=Owned-Service
+$logs=@(Get-ChildItem -LiteralPath (Join-Path $p.remoteDirectory 'agent\\logs') -File | Where-Object { $_.Name -match '^agent.*\\.log(?:\\.[0-9]+)?$' } | Sort-Object LastWriteTime -Descending)
+$text=''; if ($logs.Count -gt 0) { $text=(Get-Content -LiteralPath $logs[0].FullName -Tail $p.tail) -join [Environment]::NewLine }; Result @{logs=$text}`, { ...m, tail }, options).logs;
+}

package/src/midserver-zip.js

@@ -17,7 +17,7 @@ function read(fd, size, offset) {
 
 // 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) {
+export function inspectMidZip(archive, { allowedRoots = ['agent', 'META-INF'] } = {}) {
   const fd = fs.openSync(archive, 'r');
   try {
     const size = fs.fstatSync(fd).size;
@@ -44,7 +44,7 @@ export function inspectMidZip(archive) {
       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');
+      if ((allowedRoots && !allowedRoots.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');