@kubilaycakmak/projectfreeze 0.0.0-stage → 0.1.0-dev.5

package/src/supervisors.js

@@ -0,0 +1,163 @@
+import { createHash } from 'node:crypto';
+import { lstat, readFile, realpath } from 'node:fs/promises';
+import { isAbsolute, join, relative, sep } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { fileURLToPath } from 'node:url';
+import { Fault } from './errors.js';
+import { command, control, matches, scan, windows } from './platform.js';
+
+const mac = process.platform === 'darwin';
+const launchLabel = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,119}$/;
+const taskPath = /^\\(?:[A-Za-z0-9][A-Za-z0-9_.-]{0,80}\\)*[A-Za-z0-9][A-Za-z0-9_.-]{0,80}$/;
+const ps = windows ? join(process.env.SystemRoot, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe') : '';
+const script = fileURLToPath(new URL('./windows-supervisors.ps1', import.meta.url));
+const ctl = (args, timeout) => command('/bin/launchctl', args, { timeout });
+const digest = value => createHash('sha256').update(value).digest('hex');
+const id = item => `${item.kind}:${windows ? item.name.toLowerCase() : item.name}`;
+
+export function supervisorPolicies(value) {
+  if (!Array.isArray(value) || value.length > 12 || value.some(item => !item || typeof item.name !== 'string' ||
+    typeof item.shared !== 'boolean' || !(
+      (mac && item.kind === 'launchd' && launchLabel.test(item.name) && typeof item.plist === 'string' && isAbsolute(item.plist) && !/[\r\n\0]/.test(item.plist)) ||
+      (windows && item.kind === 'scm' && launchLabel.test(item.name)) || (windows && item.kind === 'task' && taskPath.test(item.name))
+    )) || new Set(value.map(id)).size !== value.length) throw new Fault('USAGE', 'Supply exact supervisor identities and explicit sharing for this platform.');
+  return value.map(({ kind, name, shared, plist }) => ({ kind, name, shared, ...(kind === 'launchd' ? { plist } : {}) }));
+}
+
+async function projectFile(cwd, path) {
+  if (typeof path !== 'string' || !isAbsolute(path)) throw new Fault('DENIED', 'The supervisor must use an absolute executable or definition path.');
+  const real = await realpath(path).catch(() => '');
+  const rel = relative(cwd, real);
+  if (!real || !rel || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+    throw new Fault('DENIED', 'The supervisor definition or executable must be inside the project directory.');
+  }
+  const info = await lstat(real);
+  if (!info.isFile() || (!windows && (info.uid !== process.getuid() || (info.mode & 0o022)))) {
+    throw new Fault('DENIED', 'The supervisor definition must be an owner-controlled regular file.');
+  }
+  return real;
+}
+
+function property(output, name) {
+  return output.split('\n').map(line => line.match(new RegExp(`^\\s*${name} = (.+)$`))).find(Boolean)?.[1]?.trim();
+}
+
+async function launchdProbe(item, project) {
+  const plist = await projectFile(project.cwd, item.plist);
+  const json = JSON.parse(await command('/usr/bin/plutil', ['-convert', 'json', '-o', '-', '--', plist]));
+  const executable = json.Program ?? json.ProgramArguments?.[0];
+  if (json.Label !== item.name || typeof executable !== 'string' || !isAbsolute(executable) ||
+      await realpath(json.WorkingDirectory ?? '/').catch(() => '') !== project.cwd ||
+      ['UserName', 'GroupName', 'RootDirectory', 'Sockets', 'MachServices', 'WatchPaths', 'QueueDirectories', 'StartInterval',
+        'StartCalendarInterval', 'LaunchEvents', 'KeepAlive'].some(name => Object.hasOwn(json, name) && json[name] !== false)) {
+    throw new Fault('DENIED', 'Use a project-owned, single-process LaunchAgent with a matching working directory and no auto-activation.');
+  }
+  const domain = `gui/${process.getuid()}`;
+  const service = `${domain}/${item.name}`;
+  const output = await ctl(['print', service], 5000);
+  const actual = property(output, 'path');
+  if (!actual || await realpath(actual).catch(() => '') !== plist || property(output, 'program') !== executable) {
+    throw new Fault('DENIED', 'The loaded LaunchAgent path and executable must match the reviewed definition.');
+  }
+  return { fingerprint: digest(await readFile(plist)), service, pid: Number(property(output, 'pid') ?? 0), executable };
+}
+
+async function windowsProbe(item, action = 'probe', fingerprint = '-') {
+  try {
+    const env = { ...process.env };
+    for (const name of Object.keys(env)) if (name.toUpperCase() === 'PSMODULEPATH') delete env[name];
+    Object.assign(env, { PF_SUPERVISOR_SCRIPT: script, PF_SUPERVISOR_KIND: item.kind, PF_SUPERVISOR_NAME: item.name,
+      PF_SUPERVISOR_ACTION: action, PF_SUPERVISOR_FINGERPRINT: fingerprint });
+    const invoke = '& $env:PF_SUPERVISOR_SCRIPT -Kind $env:PF_SUPERVISOR_KIND -Name $env:PF_SUPERVISOR_NAME -Action $env:PF_SUPERVISOR_ACTION -Expected $env:PF_SUPERVISOR_FINGERPRINT; exit $LASTEXITCODE';
+    const encoded = Buffer.from(invoke, 'utf16le').toString('base64');
+    return JSON.parse(await command(ps, ['-NoLogo', '-NoProfile', '-NonInteractive', '-EncodedCommand', encoded], { env }));
+  } catch (error) {
+    if (error.details?.exit === 7) throw new Fault('PARTIAL', `The Windows supervisor did not complete ${action}. Inspect the exact configured service or task.`);
+    throw error;
+  }
+}
+
+async function probe(item, project) {
+  if (item.kind === 'launchd') return launchdProbe(item, project);
+  const state = await windowsProbe(item);
+  if (state.path.toLowerCase() !== item.name.toLowerCase()) throw new Fault('DENIED', 'The Windows supervisor returned a different identity.');
+  await projectFile(project.cwd, state.executable);
+  if (item.kind === 'task' && (typeof state.cwd !== 'string' || !isAbsolute(state.cwd) ||
+      (await realpath(state.cwd).catch(() => '')).toLowerCase() !== project.cwd.toLowerCase())) {
+    throw new Fault('DENIED', 'The scheduled task must use the registered project working directory.');
+  }
+  return state;
+}
+
+export async function supervisorTargets(project, all, enroll = false) {
+  const result = [];
+  for (const item of project.recipe?.supervisors ?? []) {
+    const key = id(item);
+    const shared = item.shared || all.some(other => other.id !== project.id && other.recipe?.supervisors?.some(s => id(s) === key));
+    if (shared) { result.push({ ...item, key, shared }); continue; }
+    const observed = await probe(item, project);
+    project.supervisorPins ??= {};
+    if (enroll && !project.supervisorPins[key]) project.supervisorPins[key] = observed.fingerprint;
+    if (project.supervisorPins[key] !== observed.fingerprint) throw new Fault('DENIED', `The reviewed definition of ${item.name} changed.`);
+    result.push({ ...item, ...observed, key, shared: false });
+  }
+  return result;
+}
+
+async function launchdProcess(target, rows, transition = false) {
+  if (!target.pid) return undefined;
+  const process = rows.find(row => row.pid === target.pid);
+  const executable = await realpath(target.executable).catch(() => '');
+  const observed = process?.image ? await realpath(process.image).catch(() => '') : '';
+  if (transition && (!observed || observed !== executable)) return undefined;
+  if (!observed || observed !== executable || rows.some(row => row.parent === target.pid)) {
+    throw new Fault('UNSUPPORTED', 'LaunchAgent control requires one observable process with the reviewed executable and no live children.');
+  }
+  return process;
+}
+
+export async function observeSupervisors(project, all, rows, transition = false) {
+  const targets = await supervisorTargets(project, all);
+  for (const target of targets.filter(t => !t.shared)) {
+    if (target.kind === 'launchd') {
+      target.process = await launchdProcess(target, rows, transition);
+      target.state = target.process?.state === 'T' ? 'Paused' : target.process ? 'Running' : target.pid ? 'Pending' : 'Stopped';
+    } else if (target.kind === 'scm' && target.pid) {
+      target.process = rows.find(row => row.pid === target.pid);
+    }
+  }
+  return targets;
+}
+
+export async function supervisorAction(action, target, project) {
+  if (target.shared) throw new Fault('DENIED', 'Shared supervisors are observational.');
+  const before = await probe(target, project);
+  if (before.fingerprint !== target.fingerprint) throw new Fault('DENIED', 'Supervisor scope changed before control.');
+  if (['pause', 'resume', 'stop'].includes(action) && (!target.pid || before.pid !== target.pid)) {
+    throw new Fault('DENIED', 'The supervisor process changed before control.');
+  }
+  const timeout = project.recipe?.timeout ?? 10000;
+  if (target.kind === 'launchd') {
+    if (action === 'start') {
+      if (!before.pid) await ctl(['kickstart', before.service], timeout);
+    } else {
+      const process = await launchdProcess(before, await scan(false));
+      if (!process || !matches(process, target.process)) throw new Fault('DENIED', 'The LaunchAgent process was replaced or could not be verified.');
+      await control(({ pause: 'freeze', resume: 'resume', stop: 'stop' })[action], process);
+    }
+  } else {
+    if (target.kind === 'scm' && ((action === 'pause' && !before.canPause) || (action === 'stop' && !before.canStop))) {
+      throw new Fault('UNSUPPORTED', 'The Windows service did not advertise this control.');
+    }
+    await windowsProbe(target, action, target.fingerprint);
+  }
+  const deadline = Date.now() + timeout;
+  do {
+    const [current] = await observeSupervisors({ ...project, recipe: { ...project.recipe, supervisors: [target] } }, [], await scan(false), true);
+    if (action === 'enable' ? current.enabled : action === 'disable' ? !current.enabled && !current.active :
+        current.state === ({ pause: 'Paused', resume: 'Running', start: 'Running', stop: 'Stopped' })[action] &&
+          (!['pause','resume'].includes(action) || current.pid === before.pid)) return;
+    await delay(125);
+  } while (Date.now() < deadline);
+  throw new Fault('PARTIAL', 'The supervisor did not reach the requested state before the deadline.');
+}

package/src/systemd.js

@@ -0,0 +1,104 @@
+import { lstat, realpath, readFile } from 'node:fs/promises';
+import { join, relative, isAbsolute, sep } from 'node:path';
+import { Fault } from './errors.js';
+import { command, linux } from './platform.js';
+
+const unitName = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,120}\.(service|timer)$/;
+const keys = ['Id', 'LoadState', 'ActiveState', 'FreezerState', 'FragmentPath', 'DropInPaths', 'WorkingDirectory',
+  'ControlGroup', 'TriggeredBy', 'Triggers', 'RequiredBy', 'WantedBy', 'BoundBy', 'PartOf', 'ConsistsOf',
+  'Restart', 'SendSIGKILL', 'RefuseManualStop', 'RefuseManualStart', 'KillMode'];
+
+export function validSystemd(policy) {
+  return Array.isArray(policy) && policy.length <= 24 && policy.every(item => item && typeof item.unit === 'string' &&
+    unitName.test(item.unit) && typeof item.shared === 'boolean') && new Set(policy.map(item => item.unit)).size === policy.length;
+}
+
+const systemctl = (args, options = {}) => {
+  if (!linux) throw new Fault('UNSUPPORTED', 'User systemd units require a Linux systemd user manager.');
+  return command('/usr/bin/systemctl', ['--user', '--no-pager', '--no-ask-password', ...args], options).catch(error => {
+    throw new Fault(error.code === 'UNAVAILABLE' ? 'UNAVAILABLE' : 'PARTIAL', 'The user systemd manager did not complete its command. Inspect unit status locally.');
+  });
+};
+
+function below(parent, path) {
+  const rel = relative(parent, path);
+  return Boolean(rel && !isAbsolute(rel) && rel !== '..' && !rel.startsWith(`..${sep}`));
+}
+
+async function approvedFile(path, cwd) {
+  try {
+    const actual = await realpath(path);
+    const file = await lstat(actual);
+    return below(cwd, actual) && file.isFile() && file.uid === process.getuid() && (file.mode & 0o022) === 0;
+  } catch { return false; }
+}
+
+export async function unitState(unit) {
+  if (!unitName.test(unit)) throw new Fault('USAGE', 'Use an exact systemd user service or timer name.');
+  const output = await systemctl(['show', ...keys.flatMap(key => ['-p', key]), '--', unit]);
+  const state = Object.fromEntries(output.trim().split('\n').map(line => {
+    const at = line.indexOf('=');
+    return [line.slice(0, at), line.slice(at + 1)];
+  }));
+  if (state.Id !== unit || state.LoadState !== 'loaded') throw new Fault('NOT_FOUND', `The exact user unit ${unit} is not loaded.`);
+  return state;
+}
+
+export async function serviceTargets(project, projects) {
+  const policies = project.recipe?.systemd ?? [];
+  if (!policies.length) return [];
+  const output = [];
+  for (const policy of policies) {
+    const shared = policy.shared || projects.some(other => other.id !== project.id && other.recipe?.systemd?.some(s => s.unit === policy.unit));
+    if (shared) { output.push({ ...policy, shared }); continue; }
+    const state = await unitState(policy.unit);
+    const timer = policy.unit.endsWith('.timer');
+    if (!await approvedFile(state.FragmentPath, project.cwd) || state.DropInPaths ||
+        (!timer && await realpath(state.WorkingDirectory).catch(() => '') !== project.cwd)) {
+      throw new Fault('DENIED', `The linked unit ${policy.unit} must use a user-owned fragment inside the project, with no drop-ins.`);
+    }
+    if (state.RefuseManualStop === 'yes' || state.RefuseManualStart === 'yes' ||
+        (!timer && (state.SendSIGKILL !== 'no' || !['control-group', 'mixed'].includes(state.KillMode)))) {
+      throw new Fault('UNSUPPORTED', `The unit ${policy.unit} needs manual start and stop, KillMode=control-group or mixed, and SendSIGKILL=no.`);
+    }
+    const linked = [state.TriggeredBy, state.Triggers, state.RequiredBy, state.BoundBy, state.PartOf, state.ConsistsOf]
+      .join(' ').trim().split(/\s+/).filter(Boolean);
+    if (linked.some(name => !policies.some(item => item.unit === name && !item.shared) ||
+        projects.some(other => other.id !== project.id && other.recipe?.systemd?.some(item => item.unit === name)))) {
+      throw new Fault('DENIED', `The unit ${policy.unit} has activation or lifecycle dependencies outside the exclusive reviewed scope.`);
+    }
+    const fragment = await realpath(state.FragmentPath);
+    const info = await lstat(fragment);
+    output.push({ ...policy, state, timer, definition: `${info.dev}:${info.ino}:${info.size}:${info.mtimeMs}` });
+  }
+  return output;
+}
+
+export async function serviceAction(action, target, timeout) {
+  if (!['freeze', 'thaw', 'stop', 'start'].includes(action) || target.shared) throw new Fault('DENIED', 'The unit is outside the approved action scope.');
+  const current = await unitState(target.unit);
+  const info = await lstat(await realpath(current.FragmentPath));
+  if (`${info.dev}:${info.ino}:${info.size}:${info.mtimeMs}` !== target.definition || current.FragmentPath !== target.state.FragmentPath ||
+      current.DropInPaths !== target.state.DropInPaths || current.TriggeredBy !== target.state.TriggeredBy ||
+      current.Triggers !== target.state.Triggers || current.SendSIGKILL !== target.state.SendSIGKILL) {
+    throw new Fault('DENIED', 'Systemd unit definition or activation metadata changed during the operation.');
+  }
+  if (action === 'freeze' && (!current.ControlGroup || current.ControlGroup === '/' || current.ActiveState !== 'active')) {
+    throw new Fault('BUSY', 'The unit no longer has an active dedicated cgroup.');
+  }
+  const options = ['start', 'stop'].includes(action) ? ['--job-mode=ignore-dependencies'] : [];
+  await systemctl([...options, action, '--', target.unit], { timeout });
+  const actual = await unitState(target.unit);
+  const valid = {
+    freeze: actual.FreezerState === 'frozen', thaw: actual.FreezerState === 'running',
+    start: actual.ActiveState === 'active', stop: ['inactive', 'failed'].includes(actual.ActiveState) && !actual.ControlGroup
+  }[action];
+  if (!valid) throw new Fault('PARTIAL', `The unit ${target.unit} did not reach the requested state.`);
+}
+
+export async function systemdPids(target) {
+  if (!linux || !target.state?.ControlGroup?.startsWith('/')) return [];
+  const path = join('/sys/fs/cgroup', target.state.ControlGroup, 'cgroup.procs');
+  const values = await readFile(path, 'utf8').catch(() => '');
+  return values.trim().split(/\s+/).filter(Boolean).map(Number);
+}