@jacebenson/jsn 4.3.13 → 4.4.0

package/src/metadata/records.js

@@ -0,0 +1,249 @@
+import { assertSafeExactMatch } from '../helpers.js';
+import { errUsage, errAuth } from '../errors.js';
+
+const namePattern = /^[a-zA-Z0-9_]+$/;
+const raw = value => String(value && typeof value === 'object' ? value.value ?? '' : value ?? '');
+const field = (record, name) => raw(record?.[name]);
+const position = row => Number(field(row, 'position')) || 0;
+const ordered = rows => [...rows].sort((a, b) => position(a) - position(b));
+const reference = value => {
+  const text = raw(value);
+  assertSafeExactMatch(text);
+  return text;
+};
+const isName = value => typeof value === 'string' && namePattern.test(value);
+const chunks = values => Array.from({ length: Math.ceil(values.length / 100) }, (_, index) => values.slice(index * 100, (index + 1) * 100));
+
+function request(table, query, fields, limit = 1000) {
+  return { table, params: new URLSearchParams({
+    sysparm_query: query, sysparm_fields: fields, sysparm_limit: String(limit),
+    sysparm_display_value: 'all', sysparm_exclude_reference_link: 'true',
+  }) };
+}
+
+/** Invocation-scoped, SDK-bound metadata reader. No persistence across users. */
+export function createRecordMetadataReader(sdk, { limit = 1000, maxDepth = 32 } = {}) {
+  if (!Number.isInteger(limit) || limit < 1 || limit > 10000) throw errUsage('Metadata limit must be an integer from 1 to 10000');
+  if (!Number.isInteger(maxDepth) || maxDepth < 1 || maxDepth > 100) throw errUsage('Metadata inheritance depth must be an integer from 1 to 100');
+  const cache = new Map();
+  const reports = new Map();
+
+  async function reads(specs, warnings) {
+    const missing = specs.filter(spec => !cache.has(`${spec.table}?${spec.params}`));
+    // Reserve promises before transport so concurrent metadata requests share
+    // both successful reads and observed failures within this reader only.
+    const unique = [...new Map(missing.map(spec => [`${spec.table}?${spec.params}`, spec])).values()];
+    if (unique.length) {
+      const pending = (async () => {
+        if (unique.length > 1 && typeof sdk.batch === 'function') {
+          try {
+            const batch = await sdk.batch(unique.map((spec, index) => ({
+              id: `metadata-${index}`, method: 'GET', url: `/api/now/table/${spec.table}?${spec.params}`,
+            })), { fallback: true });
+            return unique.map((spec, index) => {
+              const item = batch.results?.find(result => result.id === `metadata-${index}`);
+              if (item?.status === 401) throw errAuth('Authentication failed while reading metadata');
+              if (!item?.ok) return { rows: [], error: item?.error?.message || `Metadata read failed (${item?.status || 'unknown status'})` };
+              return normalize(item.data?.result, spec);
+            });
+          } catch (error) {
+            if (error.code === 'auth_error' || error.status === 401) throw error;
+            // The batch provider owns unsupported-endpoint fallback. Never
+            // replay authentication/ACL/server failures through another path.
+            return unique.map(() => ({ rows: [], error: error.message || 'Metadata batch failed' }));
+          }
+        }
+        return Promise.all(unique.map(async spec => {
+          try { return normalize(await sdk.list(spec.table, spec.params), spec); }
+          catch (error) {
+            if (error.code === 'auth_error' || error.status === 401) throw error;
+            return { rows: [], error: error.message || 'Metadata read failed' };
+          }
+        }));
+      })();
+      unique.forEach((spec, index) => cache.set(`${spec.table}?${spec.params}`, pending.then(results => results[index])));
+    }
+    return Promise.all(specs.map(async spec => {
+      const result = await cache.get(`${spec.table}?${spec.params}`);
+      if (result.error) warnings.push({ source: spec.table, reason: result.error });
+      if (result.truncated) warnings.push({ source: spec.table, reason: `Metadata limit ${spec.params.get('sysparm_limit')} reached; results may be incomplete` });
+      return result.rows;
+    }));
+  }
+
+  function normalize(rows, spec) {
+    if (!Array.isArray(rows)) return { rows: [], error: 'Metadata response was not an array' };
+    return { rows, truncated: rows.length >= Number(spec.params.get('sysparm_limit')) };
+  }
+
+  async function read({ table, view = 'Default view' }) {
+    if (!isName(table)) throw errUsage('Metadata table must be a table name containing letters, numbers or underscores');
+    if (typeof view !== 'string' || !view) throw errUsage('Metadata view must be a nonempty name, title or sys_id');
+    assertSafeExactMatch(view);
+    const key = `${table}\0${view}`;
+    if (!reports.has(key)) reports.set(key, load(table, view));
+    // Protect cached objects from a consumer attaching record-specific hints.
+    return structuredClone(await reports.get(key));
+  }
+
+  async function load(table, view) {
+    const warnings = [];
+    const hierarchy = [];
+    const visited = new Set();
+    let next = request('sys_db_object', `name=${table}`, 'sys_id,name,super_class', 2);
+    for (let depth = 0; next && depth < maxDepth; depth++) {
+      const [rows] = await reads([next], warnings);
+      if (rows.length !== 1) {
+        warnings.push({ source: 'sys_db_object', reason: `Expected one visible table definition, found ${rows.length}; inheritance coverage is incomplete` });
+        break;
+      }
+      const row = rows[0];
+      const name = field(row, 'name');
+      const id = field(row, 'sys_id');
+      if (!isName(name) || visited.has(name)) {
+        warnings.push({ source: 'sys_db_object', reason: 'Invalid or cyclic table inheritance metadata' });
+        break;
+      }
+      visited.add(name);
+      hierarchy.push({ name, sys_id: id });
+      if (!Object.hasOwn(row, 'super_class')) warnings.push({ source: 'sys_db_object', reason: 'Parent metadata is not visible; inheritance coverage is incomplete' });
+      const parent = reference(row.super_class);
+      next = parent ? request('sys_db_object', `sys_id=${parent}`, 'sys_id,name,super_class', 2) : null;
+    }
+    if (next && hierarchy.length === maxDepth) warnings.push({ source: 'sys_db_object', reason: `Inheritance depth limit ${maxDepth} reached` });
+    if (!hierarchy.length) hierarchy.push({ name: table, sys_id: '' });
+    const names = hierarchy.map(item => item.name);
+    const defaultView = view === 'Default view' || view === 'default';
+    const viewQuery = defaultView ? 'name=^ORname=default^ORtitle=Default view' : `name=${view}^ORtitle=${view}^ORsys_id=${view}`;
+    const [views] = await reads([request('sys_ui_view', `${viewQuery}^userISEMPTY`, 'sys_id,name,title', limit)], warnings);
+    const byId = views.filter(row => field(row, 'sys_id') === view);
+    const byName = views.filter(row => field(row, 'name') === (defaultView ? '' : view));
+    const byTitle = views.filter(row => field(row, 'title') === view);
+    const byAlias = defaultView ? views.filter(row => field(row, 'name') === 'default') : [];
+    const candidates = byId.length ? byId : byName.length ? byName : byTitle.length ? byTitle : byAlias;
+    let viewId = '';
+    const viewCapped = views.length >= limit;
+    if (candidates.length === 1 && !viewCapped) {
+      viewId = reference(candidates[0].sys_id);
+      if (!viewId) warnings.push({ source: 'sys_ui_view', reason: 'View id is absent or not visible' });
+    } else if (candidates.length > 1 || viewCapped) warnings.push({ source: 'sys_ui_view', reason: 'View lookup is ambiguous or capped; no layout was selected' });
+    else if (!defaultView) warnings.push({ source: 'sys_ui_view', reason: 'Requested view is absent or not visible; no layout was selected' });
+    const canReadLayout = !viewCapped && candidates.length <= 1 && (defaultView || !!viewId);
+    const viewFilter = viewId ? `view=${viewId}${defaultView ? '^ORviewISEMPTY' : ''}` : 'viewISEMPTY';
+    const specs = [
+      request('sys_dictionary', `referenceIN${names.join(',')}^elementISNOTEMPTY`, 'sys_id,name,element,reference,column_label', limit),
+      request('sys_relationship', `basic_apply_toIN${names.join(',')}`, 'sys_id,name,basic_apply_to,basic_query_from,reference_field,simple_reference,advanced,query_with', limit),
+      ...(canReadLayout ? [
+        request('sys_ui_form', `nameIN${names.join(',')}^${viewFilter}^sys_userISEMPTY`, 'sys_id,name,view', limit),
+        request('sys_ui_related_list', `nameIN${names.join(',')}^${viewFilter}^sys_userISEMPTY`, 'sys_id,name,view', limit),
+      ] : []),
+    ];
+    const [dictionary, relationships, forms = [], containers = []] = await reads(specs, warnings);
+    const nearest = rows => {
+      for (const name of names) {
+        const candidates = rows.filter(row => field(row, 'name') === name);
+        const exact = viewId ? candidates.filter(row => field(row, 'view') === viewId) : [];
+        const preferred = exact.length ? exact : candidates;
+        if (preferred.length > 1) warnings.push({ source: 'layout', reason: `Ambiguous layout for ${name}; no layout was selected` });
+        if (preferred.length) {
+          if (!field(preferred[0], 'sys_id')) {
+            warnings.push({ source: 'layout', reason: `Layout id is absent or not visible for ${name}` });
+            return null;
+          }
+          return preferred.length === 1 ? preferred[0] : null;
+        }
+      }
+      return null;
+    };
+    const form = nearest(forms);
+    const container = nearest(containers);
+    const detailSpecs = [
+      ...(form ? [request('sys_ui_form_section', `sys_ui_form=${reference(form.sys_id)}^ORDERBYposition`, 'sys_id,sys_ui_form,sys_ui_section,position', limit)] : []),
+      ...(container ? [request('sys_ui_related_list_entry', `list_id=${reference(container.sys_id)}^ORDERBYposition`, 'sys_id,related_list,position,filter,order_by', limit)] : []),
+    ];
+    const details = await reads(detailSpecs, warnings);
+    const links = form ? details.shift() : [];
+    const entries = container ? details.shift() : [];
+    const sectionIds = [...new Set(links.map(link => reference(link.sys_ui_section)).filter(Boolean))];
+    const relationshipIds = entries.map(entry => field(entry, 'related_list')).filter(value => /^REL:[a-f0-9]{32}$/i.test(value)).map(value => value.slice(4));
+    const missingRelationships = relationshipIds.filter(id => !relationships.some(row => field(row, 'sys_id') === id));
+    const tailSpecs = [
+      ...chunks(sectionIds).flatMap(ids => [
+        { ...request('sys_ui_section', `sys_idIN${ids.join(',')}^sys_userISEMPTY`, 'sys_id,name,caption,header,title,view', limit), group: 'sections' },
+        { ...request('sys_ui_element', `sys_ui_sectionIN${ids.join(',')}^sys_userISEMPTY^ORDERBYposition`, 'sys_id,sys_ui_section,element,type,position', limit), group: 'elements' },
+      ]),
+      ...chunks([...new Set(missingRelationships)]).map(ids => ({
+        ...request('sys_relationship', `sys_idIN${ids.join(',')}`, 'sys_id,name,basic_apply_to,basic_query_from,reference_field,simple_reference,advanced,query_with', limit), group: 'relationships',
+      })),
+    ];
+    const tail = await reads(tailSpecs, warnings);
+    const group = name => tail.flatMap((rows, index) => tailSpecs[index].group === name ? rows : []);
+    const sections = group('sections');
+    const elements = group('elements');
+    relationships.push(...group('relationships'));
+    const sectionsOut = ordered(links).map(link => {
+      const id = field(link, 'sys_ui_section');
+      const section = sections.find(row => field(row, 'sys_id') === id);
+      if (!section) warnings.push({ source: 'sys_ui_section', reason: `A linked section is absent or not visible` });
+      return { sys_id: id, caption: field(section, 'caption'), position: position(link),
+        elements: ordered(elements.filter(row => field(row, 'sys_ui_section') === id)).map(row => ({
+          element: field(row, 'element'), type: field(row, 'type'), label: field(row, 'label'), position: position(row),
+        })) };
+    });
+    const relatedLists = buildRelationships({ entries, dictionary, relationships, sourceTable: container ? field(container, 'name') : '', names, warnings });
+    return {
+      table, requested_view: view, view_sys_id: viewId, hierarchy,
+      form: form ? { sys_id: field(form, 'sys_id'), table: field(form, 'name'), inherited: field(form, 'name') !== table, sections: sectionsOut } : null,
+      related_lists: relatedLists,
+      coverage: { state: warnings.length ? 'partial' : 'observed', scope: 'Visible shared layout metadata only; ACLs, personalization and advanced relationships may hide or change runtime results', warnings },
+    };
+  }
+
+  return { read, clear() { cache.clear(); reports.clear(); } };
+}
+
+function buildRelationships({ entries, dictionary, relationships, sourceTable, names, warnings }) {
+  const result = new Map();
+  for (const row of dictionary) {
+    const table = field(row, 'name');
+    const referenceField = field(row, 'element');
+    if (!isName(table) || !isName(referenceField)) {
+      warnings.push({ source: 'sys_dictionary', reason: 'Ignored an invalid reference definition' });
+      continue;
+    }
+    if (!names.includes(field(row, 'reference'))) warnings.push({ source: 'sys_dictionary', reason: 'A reference target is absent, unrelated, or not visible' });
+    const id = `${table}.${referenceField}`;
+    result.set(id, { id, kind: 'reference', table, reference_field: referenceField,
+      references: field(row, 'reference'), label: field(row, 'column_label'), configured: false,
+      query_status: names.includes(field(row, 'reference')) ? 'reference' : 'unavailable' });
+  }
+  for (const row of relationships) {
+    const id = `REL:${field(row, 'sys_id')}`;
+    if (!/^REL:[a-f0-9]{32}$/i.test(id)) continue;
+    const table = field(row, 'basic_query_from');
+    const referenceField = field(row, 'reference_field');
+    const queryable = field(row, 'advanced') !== 'true' && field(row, 'advanced') !== '1'
+      && names.includes(field(row, 'basic_apply_to'))
+      && ['true', '1'].includes(field(row, 'simple_reference')) && !field(row, 'query_with').trim()
+      && isName(table) && isName(referenceField);
+    result.set(id, { id, kind: 'relationship', relationship_sys_id: field(row, 'sys_id'),
+      table: isName(table) ? table : '', reference_field: queryable ? referenceField : '',
+      label: field(row, 'name'), configured: false, query_status: queryable ? 'reference' : 'platform_required',
+      ...(queryable ? {} : { reason: 'Custom/advanced relationship requires platform query logic; scripts are never executed by metadata discovery' }),
+    });
+  }
+  for (const entry of ordered(entries)) {
+    const id = field(entry, 'related_list');
+    const existing = result.get(id);
+    const descriptor = existing || { id, kind: 'unresolved', table: '', reference_field: '', query_status: 'unavailable',
+      reason: 'Configured related list metadata is absent, unsupported, or not visible' };
+    const filter = entry.filter;
+    const filterAvailable = Boolean(Object.hasOwn(entry, 'filter') && (filter === null || typeof filter === 'string'
+      || (filter && typeof filter === 'object' && Object.hasOwn(filter, 'value') && (filter.value === null || typeof filter.value === 'string'))));
+    if (!filterAvailable) warnings.push({ source: 'sys_ui_related_list_entry', reason: 'A configured filter is absent or not visible; do not assume an unfiltered list' });
+    result.set(id, { ...descriptor, configured: true, filter_available: filterAvailable, source_table: sourceTable, position: position(entry),
+      filter: field(entry, 'filter'), order_by: field(entry, 'order_by') });
+    if (!existing) warnings.push({ source: 'sys_ui_related_list_entry', reason: descriptor.reason });
+  }
+  return [...result.values()].sort((a, b) => Number(b.configured) - Number(a.configured) || (a.position || 0) - (b.position || 0));
+}

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