@passioncode-ai/fabric-agent-adapter 0.76.0 → 0.78.0

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-supervisors.mjs

@@ -9,8 +9,10 @@ import { DRAIN_SECONDS, SUPERVISOR_ENV, ServiceError, TASK, UNIT } from './fabri
 import { atomicWrite, instanceDirs } from './fabric-paths.mjs';
 import { SUPERVISOR_ARG, markerArguments } from './fabric-lock.mjs';
 import { URI } from './fabric-backups.mjs';
-import { CheckedAgent, ListenerRefused, TABLE_RESTRICTED } from './fabric-peer-owner.mjs';
+import { CheckedAgent, LSOF, ListenerRefused, PS, SERVER_NOT_OWN, TABLE_RESTRICTED, UNKNOWN, parseLsofListeners, parsePsUid,
+  runProgram, serverEnd } from './fabric-peer-owner.mjs';
 import http from 'node:http';
+import net from 'node:net';
 
 export const DEFAULT_EXIT_TIMEOUT = 15;
 
@@ -263,13 +265,15 @@ function plistValue(value, depth) {
  * FABRIC_SERVICE_SUPERVISOR=launchd tells the lock to back off instead of exiting into a respawn loop (DEC-0057).
  * No secret is written: an environment name ending TOKEN/SECRET/PASSWORD/KEY (a `*_FILE` path is fine), a value or an
  * argument shaped like a credential is refused. Returns the XML text, the same bytes Python's plistlib writes.
+ * `userName` writes UserName, the account a LaunchDaemon (launchd's system domain, FAA-278) runs as: a macOS short name.
  */
-export function launchdPlist(label, programArguments, { workingDirectory, stdoutPath, environment = {}, exitTimeout = DEFAULT_EXIT_TIMEOUT } = {}) {
+export function launchdPlist(label, programArguments, { workingDirectory, stdoutPath, environment = {}, exitTimeout = DEFAULT_EXIT_TIMEOUT, userName = null } = {}) {
   launchdLabel(label);
   const argv = programArguments.map(String);
   if (!argv.length) throw new ServiceError('A launchd job starts a program; ProgramArguments is empty.');
   if (!(exitTimeout > DRAIN_SECONDS)) throw new ServiceError(`ExitTimeOut must outlast the ${DRAIN_SECONDS} s drain.`);
   if (workingDirectory === undefined || stdoutPath === undefined) throw new ServiceError('A launchd job names its working directory and its log file.');
+  if (userName !== null && userName !== undefined && !USER_NAME.test(String(userName))) throw new ServiceError(`UserName must be a macOS short name matching ${USER_NAME.source}`);
   const env = { ...environment };
   for (const [name, value] of Object.entries(env)) {
     if (/(TOKEN|SECRET|PASSWORD|KEY)$/.test(name) && !name.endsWith('_FILE')) throw new ServiceError(`Environment variable ${name} looks like a secret; pass a *_FILE path instead.`);
@@ -295,25 +299,168 @@ export function launchdPlist(label, programArguments, { workingDirectory, stdout
     StandardErrorPath: String(stdoutPath),
     EnvironmentVariables: env,
   };
+  if (userName !== null && userName !== undefined) job.UserName = String(userName); // a LaunchDaemon's account (FAA-278)
   return '<?xml version="1.0" encoding="UTF-8"?>\n'
     + '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n'
     + `<plist version="1.0">\n${plistValue(job, 0)}</plist>\n`;
 }
 
-function launchdDomain(platform, uid) {
+function guiDomain(platform, uid) {
   // DEC-0032: launchd is macOS's supervisor; Linux has systemd and Windows Task Scheduler.
   if (platform !== 'darwin') throw new ServiceError('launchd is the supervisor on macOS only; use systemdInstall on Linux and taskInstall on Windows.');
   return `gui/${uid ?? process.getuid()}`;
 }
 
-/** True when launchd has the job loaded (`launchctl print gui/<uid>/<label>` answers). */
-export function launchdLoaded(label, { run = defaultRun, platform = process.platform, uid } = {}) {
-  return run(['launchctl', 'print', `${launchdDomain(platform, uid)}/${launchdLabel(label)}`])?.status === 0;
+/** Where a LaunchDaemon's plist lives: a job in launchd's system domain, started at boot with no GUI login (FAA-278). */
+export const SYSTEM_DAEMONS = '/Library/LaunchDaemons';
+const USER_NAME = /^[a-z_][a-z0-9_.-]{0,31}$/;
+
+/**
+ * The launchd domain a job lives in: `system` for a LaunchDaemon (`domain: 'system'`, or a plist in
+ * /Library/LaunchDaemons), else this user's `gui/<uid>` (FAA-278). A LaunchDaemon starts at boot, before any login, so it
+ * is the form for a headless Mac that a FileVault restart leaves with no GUI session.
+ */
+export function launchdDomain(plistPath = null, { domain = null, platform = process.platform, uid } = {}) {
+  if (![null, undefined, 'gui', 'system'].includes(domain)) throw new ServiceError('domain must be gui or system');
+  let which = domain;
+  if ((which === null || which === undefined) && plistPath !== null && plistPath !== undefined) {
+    const paths = platform === 'darwin' ? path.posix : path; // a macOS path, whatever host reads it
+    which = paths.dirname(paths.resolve(String(plistPath))).toLowerCase() === SYSTEM_DAEMONS.toLowerCase() ? 'system' : 'gui'; // APFS ignores case
+  }
+  if (which === 'system') {
+    if (platform !== 'darwin') throw new ServiceError('launchd is the supervisor on macOS only; use systemdInstall on Linux and taskInstall on Windows.');
+    return 'system';
+  }
+  return guiDomain(platform, uid);
+}
+
+// A system-domain job is installed and removed by root: refuse before anything is written (FAA-278).
+function needRoot(domain, label, plistPath, install, euid) {
+  if (domain !== 'system' || euid === 0) return;
+  if (install) {
+    throw new ServiceError(`A LaunchDaemon (launchd's system domain) is installed by root, and this process is not root: run launchdInstall as root (the release, descriptor and token stay its UserName's, lifecycle reference, The system domain), or as root write ${plistPath} and run \`launchctl bootstrap system ${plistPath}\`. Status and pid read without root.`);
+  }
+  throw new ServiceError(`A LaunchDaemon (launchd's system domain) is removed by root, and this process is not root: run launchdUninstall as root, or as root run \`launchctl bootout system/${label}\`, remove ${plistPath} and run \`launchctl enable system/${label}\` (so a later install is not kept off). Status and pid read without root.`);
+}
+
+// The top-level string values of an XML plist's dict, read as CoreFoundation does: comments, the prolog and DOCTYPE
+// skipped, entities, character references and CDATA decoded in keys and values, a repeated key's last value kept, a key
+// nested deeper (an EnvironmentVariables entry named UserName) never read. null when the text cannot be read so.
+const XML_ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'" };
+function decodeXml(text) {
+  return text.replace(/&(?:(amp|lt|gt|quot|apos)|#([0-9]+)|#x([0-9a-fA-F]+));/g, (_, e, d, h) => {
+    if (e) return XML_ENTITIES[e];
+    const code = d ? Number(d) : parseInt(h, 16);
+    // XML 1.0's Char, as expat (Python's plistlib) reads it: a reference outside it makes the file unreadable.
+    const xmlChar = code === 0x9 || code === 0xa || code === 0xd || (code >= 0x20 && code <= 0xd7ff)
+      || (code >= 0xe000 && code <= 0xfffd) || (code >= 0x10000 && code <= 0x10ffff);
+    if (!xmlChar) throw new RangeError('character reference outside XML 1.0');
+    return String.fromCodePoint(code);
+  });
+}
+function topStrings(text) {
+  const token = /<!--[\s\S]*?-->|<\?[\s\S]*?\?>|<!DOCTYPE[^>]*>|<!\[CDATA\[([\s\S]*?)\]\]>|<(\/?)([A-Za-z][\w.:-]*)\s*[^>]*?(\/?)>|([^<]+)/g;
+  const values = Object.create(null);
+  let depth = 0;
+  let key = null;
+  let capture = null;
+  let buffer = '';
+  try {
+    for (let m = token.exec(String(text ?? '')); m; m = token.exec(String(text ?? ''))) {
+      const [, cdata, closing, name, selfClosing, chars] = m;
+      if (cdata !== undefined || chars !== undefined) {
+        if (capture) buffer += cdata !== undefined ? cdata : decodeXml(chars);
+      } else if (name === 'dict' || name === 'array') {
+        if (selfClosing) {
+          if (depth === 1 && key !== null) { delete values[key]; key = null; }
+        } else if (closing) {
+          depth -= 1;
+        } else {
+          if (depth === 1 && key !== null) { delete values[key]; key = null; } // a container is this key's value
+          depth += 1;
+        }
+      } else if (name && depth === 1) {
+        if (selfClosing) {
+          if (key !== null) {
+            if (name === 'string') values[key] = '';
+            else delete values[key]; // <true/>, <false/>: the last value is not a string
+          }
+          key = name === 'key' ? '' : null;
+        } else if (!closing && (name === 'key' || name === 'string')) {
+          capture = name;
+          buffer = '';
+        } else if (closing && name === capture) {
+          if (capture === 'key') key = buffer;
+          else if (key !== null) { values[key] = buffer; key = null; }
+          capture = null;
+        } else if (closing) {
+          if (key !== null) delete values[key]; // another value (integer, date, data, real) replaces the earlier string
+          key = null;
+        }
+      }
+    }
+  } catch {
+    return null;
+  }
+  return values;
+}
+
+function topKey(text, key) {
+  const values = topStrings(text);
+  return values && Object.hasOwn(values, key) ? values[key] : null;
+}
+
+const topUserName = (text) => topKey(text, 'UserName');
+
+// A plist file's text as XML, a binary plist converted with plutil; null when it cannot be read.
+function plistXml(file, run) {
+  let text;
+  try { text = fs.readFileSync(file, 'latin1'); } catch { return null; }
+  if (!text.startsWith('bplist')) return Buffer.from(text, 'latin1').toString('utf8');
+  const converted = run(['plutil', '-convert', 'xml1', '-o', '-', String(file)]);
+  return converted?.status === 0 ? String(converted.stdout ?? '') : null;
+}
+
+// Other plists that hold launchd label `label` in the system domain (FAA-278): the plist launchd loaded the job from,
+// when it is not `plistPath`, and any plist of that label beside `plistPath`. Reading needs no root.
+function labelHolders(label, plistPath, run) {
+  const real = (p) => { try { return fs.realpathSync.native(p); } catch { return path.resolve(p); } }; // the case on disk
+  const own = real(String(plistPath));
+  const found = [];
+  const loaded = run(['launchctl', 'print', `system/${label}`]);
+  if (loaded?.status === 0) {
+    const hit = /^\s*path\s*=\s*(.+?)\s*$/m.exec(String(loaded.stdout ?? ''));
+    if (hit) found.push(hit[1]);
+  }
+  const folder = path.dirname(String(plistPath));
+  let names = [];
+  try { names = fs.readdirSync(folder).filter((name) => name.endsWith('.plist')).sort(); } catch { names = []; }
+  for (const name of names) {
+    const file = path.join(folder, name);
+    if (topKey(plistXml(file, run), 'Label') === label) found.push(file);
+  }
+  return [...new Set(found)].filter((file) => real(file) !== own);
 }
 
-// The running pid of this account's launchd job `label`, or null (not running, or not readable).
-export function launchdPid(label, { run = defaultRun, platform = process.platform, uid } = {}) {
-  const result = run(['launchctl', 'print', `${launchdDomain(platform, uid)}/${launchdLabel(label)}`]);
+function refuseHeldLabel(label, plistPath, run) {
+  const holders = labelHolders(label, plistPath, run);
+  if (holders.length) {
+    const owner = topUserName(plistXml(holders[0], run));
+    throw new ServiceError(`Label ${label} is already held by ${holders[0]}${owner ? ` (${owner}'s)` : ''}: the system domain is shared by every account of this Mac, so a label is the machine's and one plist holds it. Choose a label of your own (for example with the account in it), or remove that LaunchDaemon as root first.`);
+  }
+}
+
+const ownEuid = () => (typeof process.geteuid === 'function' ? process.geteuid() : null);
+
+/** True when launchd has the job loaded (`launchctl print gui/<uid>/<label>`, or `system/<label>` with domain 'system'). */
+export function launchdLoaded(label, { run = defaultRun, platform = process.platform, uid, domain = null } = {}) {
+  return run(['launchctl', 'print', `${launchdDomain(null, { domain, platform, uid })}/${launchdLabel(label)}`])?.status === 0;
+}
+
+// The running pid of this account's launchd job `label` (with domain 'system', of the LaunchDaemon), or null (not
+// running, or not readable). Reading needs no root.
+export function launchdPid(label, { run = defaultRun, platform = process.platform, uid, domain = null } = {}) {
+  const result = run(['launchctl', 'print', `${launchdDomain(null, { domain, platform, uid })}/${launchdLabel(label)}`]);
   if (result?.status !== 0) return null;
   const hit = /^\s*pid\s*=\s*([0-9]+)\s*$/m.exec(String(result.stdout ?? ''));
   return hit ? Number(hit[1]) : null;
@@ -325,8 +472,8 @@ const OVERRIDE_ROW = /^\s*"([^"]+)"\s*=>\s*(\S+)\s*$/;
  * The operator's launchd override for `label`: 'disabled', 'enabled', null when none is recorded (a first install), or
  * 'unknown' when the table cannot be read. macOS 14+ prints `=> disabled|enabled`, older releases `=> true|false`.
  */
-export function launchdOverride(label, { run = defaultRun, platform = process.platform, uid } = {}) {
-  const result = run(['launchctl', 'print-disabled', launchdDomain(platform, uid)]);
+export function launchdOverride(label, { run = defaultRun, platform = process.platform, uid, domain = null } = {}) {
+  const result = run(['launchctl', 'print-disabled', launchdDomain(null, { domain, platform, uid })]);
   if (result?.status !== 0) return 'unknown';
   for (const line of String(result.stdout ?? '').split('\n')) {
     const match = OVERRIDE_ROW.exec(line);
@@ -355,9 +502,14 @@ export async function wellKnownOf(origin, { vouchPid = null } = {}) {
   }
   // A CheckedAgent without keep-alive: the request goes on the very socket it checked, and the socket closes after the
   // answer, so a poll leaves no connection open behind it.
-  const agent = new CheckedAgent({ keepAlive: false, vouchPid });
+  return loopbackWellKnown(Number(m[1]), new CheckedAgent({ keepAlive: false, vouchPid }));
+}
+
+// The well-known answer at 127.0.0.1:<port> over `agent`, whose connections check their server end: null when nothing
+// answers or the answer is not JSON, a ForeignUserAnswer when the agent refused the listener.
+function loopbackWellKnown(port, agent) {
   return new Promise((resolve) => {
-    const req = http.request({ host: '127.0.0.1', port: Number(m[1]), path: '/.well-known/fabric-service', agent,
+    const req = http.request({ host: '127.0.0.1', port, path: '/.well-known/fabric-service', agent,
       timeout: 2000 }, (res) => {
       const chunks = [];
       res.on('data', (c) => chunks.push(c));
@@ -374,6 +526,95 @@ export async function wellKnownOf(origin, { vouchPid = null } = {}) {
   }).finally(() => agent.destroy());
 }
 
+// Whether launchd's job `pid` listens on exactly 127.0.0.1:<port>, never the wildcard, asked of the process itself (`lsof -p`),
+// which a restricted socket table does not hide. Only for a LaunchDaemon root bootstrapped, whose pid launchd named.
+async function jobListens(pid, port, run = runProgram) {
+  if (process.platform !== 'darwin' || !Number.isInteger(pid) || pid <= 1) return false;
+  try {
+    const out = await run(LSOF, ['-nP', '-a', '-p', String(pid), '-i4TCP', '-sTCP:LISTEN', '-Fn']);
+    return parseLsofListeners(out).some(([host, p]) => host === '127.0.0.1' && p === port); // exact bind, as RT-3
+  } catch {
+    return false;
+  }
+}
+
+// The uid account `name` has on this machine (`id -u`), or null when it has none.
+function accountUid(name, run) {
+  if (!USER_NAME.test(String(name))) return null; // `id -u 501` answers a uid, but launchd looks UserName up by name
+  const result = run(['id', '-u', String(name)]);
+  const uid = result?.status === 0 ? String(result.stdout ?? '').trim() : '';
+  return /^[0-9]+$/.test(uid) ? Number(uid) : null;
+}
+
+// An http.Agent whose connections must be accepted by launchd's job `jobPid`, running as `jobUid`, its UserName's uid: a
+// LaunchDaemon runs as its UserName, so the installer, root, reads it as another account's, and the job's own pid and
+// uid are the proof (FAA-278; contract DEC-0161, proposed: RT-3 extended to launchd's system domain).
+class JobAgent extends http.Agent {
+  constructor({ jobPid, jobUid, ask = {}, ...options } = {}) {
+    if (!Number.isInteger(jobPid) || jobPid <= 1) throw new ServiceError("A LaunchDaemon's answer is read only on its job's pid, a positive number.");
+    if (!Number.isInteger(jobUid) || jobUid < 0) throw new ServiceError("A LaunchDaemon's answer is read only from its UserName's uid, a number.");
+    super(options);
+    this.jobPid = jobPid;
+    this.jobUid = jobUid;
+    this.ask = ask;
+  }
+
+  createConnection(options, callback) {
+    const port = Number(options.port);
+    const socket = net.connect({ host: '127.0.0.1', port, noDelay: true });
+    const timer = setTimeout(() => socket.destroy(Object.assign(new Error('connect timeout'), { code: 'ETIMEDOUT' })), options.timeout ?? 10000);
+    socket.once('error', (err) => { clearTimeout(timer); callback(err); });
+    socket.once('connect', async () => {
+      clearTimeout(timer);
+      socket.pause();
+      let who;
+      try {
+        who = await serverEnd(socket, this.ask);
+      } catch (err) {
+        who = { kind: UNKNOWN, uid: null, pid: null, reason: `check: ${err?.name ?? 'Error'}` };
+      }
+      if (who.pid === this.jobPid && !await jobListens(this.jobPid, port, this.ask.run)) {
+        socket.destroy();
+        // The job's pid, but lsof did not show it bound to exactly 127.0.0.1:<port>: a wildcard is never vouched for.
+        callback(new ListenerRefused(SERVER_NOT_OWN, `the LaunchDaemon's pid ${this.jobPid} is not shown listening on exactly 127.0.0.1:${port} by lsof (a wildcard is never vouched for); nothing was sent`));
+        return;
+      }
+      const proved = who.pid === this.jobPid || (who.kind === UNKNOWN && String(who.reason ?? '').startsWith(TABLE_RESTRICTED)
+        && await jobListens(this.jobPid, port, this.ask.run));
+      if (!proved) {
+        socket.destroy();
+        callback(new ListenerRefused(SERVER_NOT_OWN, `the server on port ${port} is not the LaunchDaemon's pid ${this.jobPid} (${who.reason ?? who.kind}): another process holds the port, or the job's program starts the server as a child (start it with exec); nothing was sent`, who));
+        return;
+      }
+      let runsAs = null;
+      try { runsAs = parsePsUid(await (this.ask.run ?? runProgram)(PS, ['-o', 'uid=', '-p', String(this.jobPid)])); } catch { runsAs = null; }
+      if (runsAs !== this.jobUid) {
+        socket.destroy();
+        // Not the restricted owner: the pid was proved, only its uid is wrong, and the error says so.
+        callback(new ListenerRefused(SERVER_NOT_OWN, `the LaunchDaemon's pid ${this.jobPid} runs as uid ${runsAs}, not its UserName's uid ${this.jobUid}; nothing was sent`));
+        return;
+      }
+      socket.removeAllListeners('error');
+      socket.resume();
+      callback(null, socket);
+    });
+  }
+}
+
+// The port of exactly http://127.0.0.1:<port> (1 to 65535, no leading zero), else null.
+function loopbackPort(origin) {
+  const m = /^http:\/\/127\.0\.0\.1:([1-9][0-9]{0,4})$/.exec(String(origin));
+  return m && Number(m[1]) <= 65535 ? Number(m[1]) : null;
+}
+
+// As wellKnownOf, for a LaunchDaemon: a loopback origin is read only when launchd's job `jobPid`, running as `jobUid`,
+// accepted the connection.
+export async function jobWellKnownOf(origin, { jobPid, jobUid } = {}) {
+  const port = loopbackPort(origin);
+  if (port === null) throw new ServiceError(`A LaunchDaemon's answer is read only at http://127.0.0.1:<port>, where its job's pid and uid prove it; ${origin} is not.`);
+  return loopbackWellKnown(port, new JobAgent({ keepAlive: false, jobPid, jobUid }));
+}
+
 /**
  * Write and lint the plist, bootout and WAIT for the unload, bootstrap (retrying launchd's EIO 5 times), then poll the
  * well-known document until it answers with this identity; resolves to that document.
@@ -382,17 +623,52 @@ export async function wellKnownOf(origin, { vouchPid = null } = {}) {
  * operator disabled stays disabled and unloaded — the plist is still rewritten, so the new release is what starts once
  * they turn it back on — and the answer is {disabled: true, label, plist, loaded}. `forceEnable` is for an operator
  * who asked for the service to be switched on.
+ *
+ * A plist in /Library/LaunchDaemons (or `domain: 'system'`) is a LaunchDaemon in launchd's system domain, started at boot
+ * with no login (FAA-278): only root installs it, refused before anything is written otherwise, and the answer counts
+ * only when launchd's own job accepted the connection. A gui/<uid> bootstrap with no GUI session says so.
  */
 export async function launchdInstall(label, plistPath, plistText, { origin, serviceId, instance = 'default', timeout = 40, forceEnable = false,
-  run = defaultRun, platform = process.platform, uid, fetchWellKnown = wellKnownOf, sleep = pause } = {}) {
-  const domain = launchdDomain(platform, uid);
+  run = defaultRun, platform = process.platform, uid, domain = null, euid = ownEuid(), fetchWellKnown = wellKnownOf,
+  fetchJobWellKnown = jobWellKnownOf, sleep = pause } = {}) {
+  const dom = launchdDomain(plistPath, { domain, platform, uid });
   launchdLabel(label);
   if (!origin || !serviceId) throw new ServiceError('launchdInstall needs the origin and the service id it waits to see answer.');
-  const opts = { run, platform, uid };
+  needRoot(dom, label, plistPath, true, euid);
+  if (dom === 'system' && loopbackPort(origin) === null) {
+    throw new ServiceError(`A LaunchDaemon's origin is http://127.0.0.1:<port>: only there is its answer proved by the job's pid and uid (FAA-278); ${origin} is not.`);
+  }
+  const named = dom === 'system' ? topUserName(plistText) : null;
+  if (dom === 'system' && named) {
+    refuseHeldLabel(label, plistPath, run);
+    const installedText = plistXml(plistPath, run);
+    const installedLabel = topKey(installedText, 'Label');
+    if (installedLabel !== null && installedLabel !== label) {
+      throw new ServiceError(`${plistPath} holds launchd label ${installedLabel}, not ${label}: writing over it would leave that job loaded from a plist that no longer describes it. Uninstall it as root first, or write this one at /Library/LaunchDaemons/${label}.plist.`);
+    }
+    const installed = topUserName(installedText);
+    if (installed && installed !== named) {
+      throw new ServiceError(`${plistPath} is ${installed}'s LaunchDaemon: the system domain is shared by every account of this Mac, so a label is the machine's. Choose a label of your own (for example with the account in it), or uninstall that one as root first.`);
+    }
+  }
+  if (dom === 'system' && named && !USER_NAME.test(named)) {
+    throw new ServiceError(`UserName ${named} is not a macOS short name (${USER_NAME.source}): launchd takes the account's short name.`);
+  }
+  const jobUid = named ? accountUid(named, run) : null;
+  if (dom === 'system' && named && jobUid === null) {
+    throw new ServiceError(`UserName ${named} is no account of this Mac: launchd would not start the job. Name the account whose Fabric and agents call the service.`);
+  }
+  if (dom === 'system' && jobUid === 0) {
+    throw new ServiceError(`UserName ${named} is root: the job would run as root, keep its data in root's home, and every client refuses root's listener (DEC-0154 HA-2). Name the account whose Fabric and agents call the service.`);
+  }
+  if (dom === 'system' && !named) {
+    throw new ServiceError("A LaunchDaemon needs UserName: without it the job runs as root, keeps its data in root's home, and every client refuses root's listener (DEC-0154 HA-2). Write the plist with launchdPlist(..., { userName: <the account whose Fabric and agents call it> }).");
+  }
+  const opts = { run, platform, uid, domain: dom === 'system' ? 'system' : null };
   atomicWrite(plistPath, plistText, 0o644);
   const lint = run(['plutil', '-lint', String(plistPath)]);
   if (lint?.status !== 0) throw new ServiceError(`plist failed plutil -lint: ${String(lint?.stdout || lint?.stderr || '').trim().slice(0, 200)}`);
-  const target = `${domain}/${label}`;
+  const target = `${dom}/${label}`;
   const override = launchdOverride(label, opts);
   if (forceEnable || override === null) run(['launchctl', 'enable', target]);
   else if (override === 'disabled') return { disabled: true, label, plist: String(plistPath), loaded: launchdLoaded(label, opts) };
@@ -401,13 +677,33 @@ export async function launchdInstall(label, plistPath, plistText, { origin, serv
   while (launchdLoaded(label, opts) && Date.now() < unloaded) await sleep(250);
   let last = '';
   for (let attempt = 0; ; attempt += 1) {
-    const result = run(['launchctl', 'bootstrap', domain, String(plistPath)]);
+    const result = run(['launchctl', 'bootstrap', dom, String(plistPath)]);
     if (result?.status === 0) break;
     last = String(result?.stderr || result?.stdout || '').trim();
-    if (attempt === 4) throw new ServiceError(`launchctl bootstrap failed: ${last.slice(0, 200)}`);
+    if (attempt === 4) {
+      if (dom !== 'system' && /:\s*125:|Domain does not support|Could not find domain/.test(last)) {
+        throw new ServiceError(`launchctl bootstrap failed: ${last.slice(0, 200)}. This user has no GUI login session (an SSH session, or a headless Mac after a FileVault restart), so ${dom} does not run jobs: remove the LaunchAgent this attempt wrote (launchdUninstall), then install it as a LaunchDaemon in the system domain (a plist in ${SYSTEM_DAEMONS} with UserName, as root; FAA-278).`);
+      }
+      throw new ServiceError(`launchctl bootstrap failed: ${last.slice(0, 200)}`);
+    }
     await sleep(1000);
   }
   const deadline = Date.now() + timeout * 1000;
+  if (dom === 'system') {
+    let refused = null;
+    while (Date.now() < deadline) {
+      const jobPid = launchdPid(label, opts);
+      const doc = jobPid ? await fetchJobWellKnown(origin, { jobPid, jobUid }) : null;
+      const now = doc instanceof ForeignUserAnswer ? doc.reason : null;
+      refused = now ?? refused; // the last refusal stays the reason, but only this round's answer decides
+      if (!now && doc?.service?.id === serviceId && doc?.service?.instance === instance) return doc;
+      await sleep(500);
+    }
+    const loaded = `; the job stays loaded and its plist starts it again at boot: as root, \`launchctl bootout system/${label}\` and removing ${plistPath} (or launchdUninstall) take it away`;
+    if (refused?.startsWith(TABLE_RESTRICTED)) throw new ServiceError(`${origin} could not be proved this LaunchDaemon's: ${refused}; the job's pid did not show the listener: start the server with exec (no wrapper child), or read the job's log${loaded}.`);
+    if (refused) throw new ServiceError(`${origin} is not this LaunchDaemon's: ${refused}${loaded}.`);
+    throw new ServiceError(`${origin} did not answer as ${serviceId}.${instance} within ${timeout} s; read its log${loaded}.`);
+  }
   let foreign = null;
   let vouchPid = null;
   while (Date.now() < deadline) {
@@ -432,15 +728,20 @@ export async function launchdInstall(label, plistPath, plistText, { origin, serv
  * override to enabled — launchctl has no verb that deletes an override, and a leftover `disabled` would keep a later
  * fresh install off. Data stays unless `purge` (then `serviceId` names whose data, logs and cache go, and `instance` which
  * instance's, so one context's purge never reaches another's, FAA-125). A job still
- * loaded at `timeout` seconds throws, leaving the plist and the data in place.
+ * loaded at `timeout` seconds throws, leaving the plist and the data in place. A LaunchDaemon (a plist in
+ * /Library/LaunchDaemons, or `domain: 'system'`) is removed only by root, and its data belongs to its UserName, so
+ * `purge` is refused for it (FAA-278).
  */
-export async function launchdUninstall(label, plistPath, { timeout = 30, purge = false, serviceId, instance = 'default', run = defaultRun, platform = process.platform, uid, sleep = pause } = {}) {
-  const domain = launchdDomain(platform, uid);
+export async function launchdUninstall(label, plistPath, { timeout = 30, purge = false, serviceId, instance = 'default', run = defaultRun, platform = process.platform, uid, domain = null, euid = ownEuid(), sleep = pause } = {}) {
+  const dom = launchdDomain(plistPath, { domain, platform, uid });
   launchdLabel(label);
   if (purge && !serviceId) throw new ServiceError('purge needs the service id whose data, logs and cache to remove.');
+  needRoot(dom, label, plistPath, false, euid);
+  if (purge && dom === 'system') throw new ServiceError("A LaunchDaemon's data belongs to its UserName, not to root: uninstall without purge, then remove the data as that user.");
+  if (dom === 'system') refuseHeldLabel(label, plistPath, run); // a bootout would stop another plist's job (FAA-278)
   const dirs = purge ? instanceDirs(serviceId, instance, platform) : {}; // one instance's folders only (FAA-125)
-  const opts = { run, platform, uid };
-  const target = `${domain}/${label}`;
+  const opts = { run, platform, uid, domain: dom === 'system' ? 'system' : null };
+  const target = `${dom}/${label}`;
   run(['launchctl', 'bootout', target]);
   const deadline = Date.now() + timeout * 1000;
   while (launchdLoaded(label, opts)) {

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-tailnet.mjs

@@ -0,0 +1,198 @@
+// Who is calling an agent that sits behind `tailscale serve`, and what that person may open (FAA-297). The twin of
+// fabric_tailnet.py; both answer test/fixtures/tailnet/vectors.json alike. No dependencies beyond node:crypto and
+// node:net.
+//
+// The header `Tailscale-User-Login` is believed only on the agent's own serve listener (a loopback port or a Unix
+// socket that only serve reaches) and only from a loopback peer; on any other listener a request carrying it is
+// refused. What a person may open comes from a `tailnet-perimeter/1` file generated from the organization's access
+// registry (it names its source in `generatedFrom`); MCP also takes a personal key, stored as its SHA-256, owned by one
+// login and no wider than that login's groups. Refusals are 401 or 403 with a stable `code`.
+
+import { createHash, timingSafeEqual } from 'node:crypto';
+import { isIP } from 'node:net';
+
+export const PERIMETER_SCHEMA = 'tailnet-perimeter/1';
+export const IDENTITY_HEADER = 'tailscale-user-login';
+export const SERVE_HEADERS = Object.freeze(['tailscale-user-login', 'tailscale-user-name', 'tailscale-user-profile-pic']);
+export const LISTENER_SERVE = 'serve';
+export const SURFACES = Object.freeze(['dashboard', 'mcp']);
+
+const LOGIN = /^[A-Za-z0-9._%+-]{1,128}@[A-Za-z0-9.-]{1,125}$/;
+const NAME = /^[a-z][a-z0-9._:/-]{0,127}$/;
+const KEY_HASH = /^sha256:[0-9a-f]{64}$/;
+const KEY_ID = /^[A-Za-z0-9._-]{1,64}$/;
+
+export const REFUSALS = Object.freeze({
+  'serve-header-off-serve': 403,
+  'peer-not-loopback': 403,
+  'identity-missing': 401,
+  'identity-ambiguous': 401,
+  'identity-malformed': 401,
+  'not-in-perimeter': 403,
+  'dashboard-not-granted': 403,
+  'capability-not-granted': 403,
+  'key-required': 401,
+  'key-unknown': 401,
+  'key-not-yours': 403,
+  'key-wider-than-group': 403,
+});
+
+/** A perimeter or key list that cannot be used: `code` names why, `where` the place, never a value. */
+export class PerimeterError extends Error {
+  constructor(code, where = '') {
+    super(`${code}${where ? ` at ${where}` : ''}`);
+    this.name = 'PerimeterError';
+    this.code = code;
+    this.where = where;
+  }
+}
+
+/** The stored form of a personal key: `sha256:<hex>` of its UTF-8 bytes. */
+export function hashKey(value) {
+  if (typeof value !== 'string' || !value) throw new TypeError('a key is a non-empty string');
+  return `sha256:${createHash('sha256').update(value, 'utf8').digest('hex')}`;
+}
+
+const sortedSet = (values) => [...new Set(values)].sort();
+const isRecordValue = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const pyKeySort = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+
+function names(value, where) {
+  if (!Array.isArray(value) || !value.every((v) => typeof v === 'string' && NAME.test(v))) {
+    throw new PerimeterError('perimeter-invalid', where);
+  }
+  return sortedSet(value);
+}
+
+/** Check a parsed `tailnet-perimeter/1` document and answer its normalized form; throw PerimeterError otherwise. */
+export function loadPerimeter(doc) {
+  if (!isRecordValue(doc) || doc.schema !== PERIMETER_SCHEMA) throw new PerimeterError('perimeter-schema', 'schema');
+  const source = doc.generatedFrom;
+  if (!isRecordValue(source) || !['registry', 'revision', 'at'].every((k) => typeof source[k] === 'string' && source[k])) {
+    throw new PerimeterError('perimeter-not-generated', 'generatedFrom');
+  }
+  const groups = doc.groups;
+  if (!isRecordValue(groups) || Object.keys(groups).length === 0) throw new PerimeterError('perimeter-invalid', 'groups');
+  const out = {};
+  for (const name of Object.keys(groups).sort(pyKeySort)) {
+    const group = groups[name];
+    const where = NAME.test(name) ? `groups.${name}` : 'groups';
+    if (!NAME.test(name) || !isRecordValue(group)) throw new PerimeterError('perimeter-invalid', where);
+    const members = group.members;
+    if (!Array.isArray(members) || !members.every((m) => typeof m === 'string' && LOGIN.test(m))) {
+      throw new PerimeterError('perimeter-invalid', `${where}.members`);
+    }
+    out[name] = {
+      members: sortedSet(members.map((m) => m.toLowerCase())),
+      dashboards: names(group.dashboards ?? [], `${where}.dashboards`),
+      capabilities: names(group.capabilities ?? [], `${where}.capabilities`),
+    };
+  }
+  return {
+    schema: PERIMETER_SCHEMA,
+    generatedFrom: { registry: source.registry, revision: source.revision, at: source.at },
+    groups: out,
+  };
+}
+
+/** Check a list of personal keys `{id, login, sha256, capabilities}` (the hash only, never the key). */
+export function loadKeys(keys) {
+  if (!Array.isArray(keys)) throw new PerimeterError('keys-invalid', 'keys');
+  const out = [];
+  const seen = new Set();
+  keys.forEach((key, i) => {
+    const where = `keys[${i}]`;
+    if (!isRecordValue(key) || typeof key.id !== 'string' || !KEY_ID.test(key.id)
+        || typeof key.login !== 'string' || !LOGIN.test(key.login)
+        || typeof key.sha256 !== 'string' || !KEY_HASH.test(key.sha256)) {
+      throw new PerimeterError('keys-invalid', where);
+    }
+    if (seen.has(key.id) || out.some((k) => k.sha256 === key.sha256)) throw new PerimeterError('keys-duplicate', where);
+    seen.add(key.id);
+    out.push({ id: key.id, login: key.login.toLowerCase(), sha256: key.sha256,
+      capabilities: names(key.capabilities ?? [], `${where}.capabilities`) });
+  });
+  return out;
+}
+
+function headerValues(headers, name) {
+  // A list of pairs, a Map or a fetch Headers (anything with entries()), or a plain object such as Node's req.headers.
+  const plain = headers === null || headers === undefined || Object.getPrototypeOf(headers) === Object.prototype
+    || Object.getPrototypeOf(headers) === null;
+  const pairs = Array.isArray(headers) ? headers
+    : !plain && typeof headers.entries === 'function' ? [...headers.entries()]
+      : Object.entries(headers ?? {});
+  const found = [];
+  for (const [key, value] of pairs) {
+    if (typeof key === 'string' && key.toLowerCase() === name) found.push(...(Array.isArray(value) ? value : [value]));
+  }
+  return found.map((v) => (typeof v === 'string' ? v : ''));
+}
+
+function isLoopback(address) {
+  if (address === 'unix') return true;
+  if (typeof address !== 'string') return false;
+  const ip = address.split('%', 1)[0];
+  const family = isIP(ip);
+  if (family === 4) return ip.split('.')[0] === '127';
+  if (family !== 6) return false;
+  const host = new URL(`http://[${ip}]/`).hostname; // the canonical compressed form: [::1], [::ffff:7f00:1]
+  return host === '[::1]' || /^\[::ffff:7f[0-9a-f]{2}:[0-9a-f]{1,4}\]$/.test(host);
+}
+
+const refuse = (code, login = null, groups = []) => ({ allowed: false, status: REFUSALS[code], code, login, groups });
+
+function bearer(headers) {
+  const values = headerValues(headers, 'authorization');
+  if (values.length !== 1) return null;
+  const text = values[0].trim();
+  const space = text.indexOf(' ');
+  if (space < 0) return null;
+  const scheme = text.slice(0, space);
+  const rest = text.slice(space + 1).trim();
+  return scheme.toLowerCase() === 'bearer' && rest && !rest.includes(' ') ? rest : null;
+}
+
+function sameDigest(a, b) {
+  const x = Buffer.from(a, 'utf8');
+  const y = Buffer.from(b, 'utf8');
+  return x.length === y.length && timingSafeEqual(x, y);
+}
+
+/**
+ * Decide one request. `listener` is which of the agent's listeners took it (`serve` for serve's own); `peer` the
+ * connecting address (`unix` for a Unix socket); `perimeter` and `keys` as loadPerimeter and loadKeys answer;
+ * `surface` `dashboard` or `mcp`; `target` the dashboard's or the capability's name. Answers
+ * {allowed, status, code, login, groups}: status 200 with code `ok`, else 401 or 403 with the refusal's code.
+ */
+export function authorize({ listener, peer, headers, perimeter, surface, target, keys = null }) {
+  if (!SURFACES.includes(surface)) throw new TypeError(`surface is one of ${SURFACES.join(', ')}`);
+  if (listener !== LISTENER_SERVE) {
+    if (SERVE_HEADERS.some((h) => headerValues(headers, h).length)) return refuse('serve-header-off-serve');
+    throw new TypeError("authorize decides serve's listener; the Fabric listener keeps its session key");
+  }
+  if (!isLoopback(peer)) return refuse('peer-not-loopback');
+  const logins = headerValues(headers, IDENTITY_HEADER);
+  if (logins.length === 0) return refuse('identity-missing');
+  if (logins.length > 1) return refuse('identity-ambiguous');
+  let login = logins[0].trim();
+  if (!LOGIN.test(login)) return refuse('identity-malformed');
+  login = login.toLowerCase();
+  const groups = Object.keys(perimeter.groups).filter((n) => perimeter.groups[n].members.includes(login)).sort(pyKeySort);
+  if (groups.length === 0) return refuse('not-in-perimeter', login);
+  const dashboards = new Set(groups.flatMap((n) => perimeter.groups[n].dashboards));
+  const capabilities = new Set(groups.flatMap((n) => perimeter.groups[n].capabilities));
+  if (surface === 'dashboard') {
+    if (!dashboards.has(target)) return refuse('dashboard-not-granted', login, groups);
+    return { allowed: true, status: 200, code: 'ok', login, groups };
+  }
+  const presented = bearer(headers);
+  if (presented === null) return refuse('key-required', login, groups);
+  const digest = hashKey(presented);
+  const key = (keys ?? []).find((k) => sameDigest(k.sha256, digest));
+  if (!key) return refuse('key-unknown', login, groups);
+  if (key.login !== login) return refuse('key-not-yours', login, groups);
+  if (!key.capabilities.every((c) => capabilities.has(c))) return refuse('key-wider-than-group', login, groups);
+  if (!key.capabilities.includes(target)) return refuse('capability-not-granted', login, groups);
+  return { allowed: true, status: 200, code: 'ok', login, groups, key: key.id };
+}