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

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

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric_service.py

@@ -314,6 +314,8 @@ from fabric_supervisors import (  # noqa: F401
     launchd_plist,
     _launchctl,
     _domain,
+    SYSTEM_DAEMONS,
+    launchd_domain,
     launchd_loaded,
     launchd_pid,
     fetch_well_known,

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric_supervisors.py

@@ -45,6 +45,10 @@ DEFAULT_EXIT_TIMEOUT = 15
 
 
 _LABEL = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,250}\Z")  # what launchd and the Node twin take as a label
+_USER_NAME = re.compile(r"^[a-z_][a-z0-9_.-]{0,31}\Z")  # a macOS short name, as a LaunchDaemon's UserName takes it
+
+#: Where a LaunchDaemon's plist lives: a job in launchd's system domain, started at boot with no GUI login (FAA-278).
+SYSTEM_DAEMONS = Path("/Library/LaunchDaemons")
 
 
 def _no_marker_argument(argv: Sequence[str]) -> None:
@@ -255,7 +259,7 @@ def task_uninstall(task: str, *, run: Callable[..., Any] = subprocess.run, syste
 
 def launchd_plist(label: str, program_arguments: Sequence[str], *, working_directory: Path,
                   stdout_path: Path, environment: Optional[Dict[str, str]] = None,
-                  exit_timeout: int = DEFAULT_EXIT_TIMEOUT) -> bytes:
+                  exit_timeout: int = DEFAULT_EXIT_TIMEOUT, user_name: Optional[str] = None) -> bytes:
     """RunAtLoad + KeepAlive true + ThrottleInterval 10; no secret may appear in `environment`.
 
     ``ExitTimeOut`` (15 s) sits above the drain and its hard exit (``Drain``: 8 + 2 s), so launchd's
@@ -264,7 +268,10 @@ def launchd_plist(label: str, program_arguments: Sequence[str], *, working_direc
 
     The same refusals as the Node twin (finding 10): a label launchd cannot name, no program, an ExitTimeOut that does
     not outlast the drain, an environment name ending TOKEN/SECRET/PASSWORD/KEY (a `*_FILE` path is fine), a value or
-    an argument shaped like a credential, and a control character in any string the plist carries."""
+    an argument shaped like a credential, and a control character in any string the plist carries.
+
+    ``user_name`` writes ``UserName``, the account a LaunchDaemon (system domain, FAA-278) runs as; it must be a macOS
+    short name, and it is meaningful only for a plist installed in ``/Library/LaunchDaemons``."""
     import fabric_secrets  # noqa: E402 - beside this file; the contract's detector (DEC-0044)
     if not _LABEL.match(str(label)):
         raise ServiceError("label must match %s" % _LABEL.pattern)
@@ -273,6 +280,8 @@ def launchd_plist(label: str, program_arguments: Sequence[str], *, working_direc
         raise ServiceError("A launchd job starts a program; ProgramArguments is empty.")
     if not exit_timeout > DRAIN_SECONDS:
         raise ServiceError("ExitTimeOut must outlast the %d s drain." % DRAIN_SECONDS)
+    if user_name is not None and not _USER_NAME.match(str(user_name)):
+        raise ServiceError("UserName must be a macOS short name matching %s" % _USER_NAME.pattern)
     env = dict(environment or {})
     for key, value in env.items():
         if re.search(r"(TOKEN|SECRET|PASSWORD|KEY)\Z", key) and not key.endswith("_FILE"):
@@ -303,6 +312,8 @@ def launchd_plist(label: str, program_arguments: Sequence[str], *, working_direc
         "StandardErrorPath": str(stdout_path),
         "EnvironmentVariables": env,
     }
+    if user_name is not None:
+        plist["UserName"] = str(user_name)
     return plistlib.dumps(plist)
 
 
@@ -317,16 +328,52 @@ def _domain() -> str:
     return "gui/%d" % os.getuid()
 
 
-def launchd_loaded(label: str) -> bool:
-    return _launchctl("print", "%s/%s" % (_domain(), label)).returncode == 0
+def launchd_domain(plist_path: Optional[Path] = None, domain: Optional[str] = None) -> str:
+    """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 (``fdesetup authrestart``) leaves with no GUI
+    session; a ``gui/<uid>`` job starts only while its user is logged in."""
+    if domain not in (None, "gui", "system"):
+        raise ServiceError("domain must be gui or system")
+    if domain is None and plist_path is not None:
+        folder = re.sub(r"^/{2,}", "/", str(Path(os.path.abspath(str(plist_path))).parent))  # POSIX keeps a leading //
+        domain = "system" if folder.lower() == str(SYSTEM_DAEMONS).lower() else "gui"  # APFS ignores case
+    if domain == "system":
+        if sys.platform != "darwin":
+            raise ServiceError("launchd is the supervisor on macOS only; use systemd_install on Linux and task_install on "
+                               "Windows.")
+        return "system"
+    return _domain()
+
+
+def _need_root(domain: str, label: str, plist_path: Path, install: bool) -> None:
+    """A system-domain job is installed and removed by root: refuse before anything is written (FAA-278)."""
+    if domain != "system" or os.geteuid() == 0:
+        return
+    if install:
+        raise ServiceError("A LaunchDaemon (launchd's system domain) is installed by root, and this process is not "
+                           "root: run launchd_install as root (the release, descriptor and token stay its UserName's, "
+                           "lifecycle reference, The system domain), or as root write %s and run "
+                           "`launchctl bootstrap system %s`. Status and pid read without root." % (plist_path, plist_path))
+    raise ServiceError("A LaunchDaemon (launchd's system domain) is removed by root, and this process is not root: run "
+                       "launchd_uninstall as root, or as root run `launchctl bootout system/%s`, remove %s and run "
+                       "`launchctl enable system/%s` (so a later install is not kept off). Status and pid read without "
+                       "root." % (label, plist_path, label))
+
+
+def launchd_loaded(label: str, domain: Optional[str] = None) -> bool:
+    """Whether launchd has the job ``label`` loaded in this user's ``gui/<uid>`` domain, or with ``domain="system"`` in
+    the system domain (FAA-278); reading needs no root."""
+    return _launchctl("print", "%s/%s" % (launchd_domain(domain=domain), label)).returncode == 0
 
 
 _PID_ROW = re.compile(r"^\s*pid\s*=\s*(\d+)\s*\Z")
 
 
-def launchd_pid(label: str) -> Optional[int]:
-    """The running pid of this account's launchd job ``label``, or None (not running, or not readable)."""
-    result = _launchctl("print", "%s/%s" % (_domain(), label))
+def launchd_pid(label: str, domain: Optional[str] = None) -> Optional[int]:
+    """The running pid of this account's launchd job ``label`` (with ``domain="system"``, of the LaunchDaemon), or
+    None (not running, or not readable). Reading needs no root."""
+    result = _launchctl("print", "%s/%s" % (launchd_domain(domain=domain), label))
     if result.returncode != 0:
         return None
     for line in (result.stdout or "").splitlines():
@@ -364,6 +411,107 @@ def _read_well_known(origin: str, timeout: float = 2.0,
         return None, None
 
 
+def _job_listens(pid: int, port: int) -> bool:
+    """Whether launchd's job `pid` listens on 127.0.0.1:<port> exactly (never the wildcard), asked of the process itself
+    (`lsof -p`), which a restricted socket table does not hide. Used only for a LaunchDaemon root just bootstrapped,
+    whose pid launchd itself named (FAA-278)."""
+    if sys.platform != "darwin" or not isinstance(pid, int) or isinstance(pid, bool) or pid <= 1:
+        return False
+    try:
+        out = _po._run([_po.LSOF, "-nP", "-a", "-p", str(pid), "-i4TCP", "-sTCP:LISTEN", "-Fn"])
+    except _po.TableUnreadable:
+        return False
+    return any(host == "127.0.0.1" and p == port for host, p in _po.parse_lsof_listeners(out))  # exact bind, as RT-3
+
+
+def _account_uid(user_name: str) -> Optional[int]:
+    """The uid of account ``user_name`` on this machine, or None when it has no such account. Only a short name: macOS
+    getpwnam also answers an upper-case name or the full name, which launchd's UserName does not take."""
+    if not isinstance(user_name, str) or not _USER_NAME.match(user_name):
+        return None
+    try:
+        import pwd
+        return pwd.getpwnam(user_name).pw_uid
+    except (ImportError, KeyError, ValueError):
+        return None
+
+
+def _pid_uid(pid: int) -> Optional[int]:
+    """The uid process ``pid`` runs as (``ps -o uid= -p``), or None when it is gone or cannot be read."""
+    try:
+        return _po.parse_ps_uid(_po._run([_po.PS, "-o", "uid=", "-p", str(pid)]))
+    except _po.TableUnreadable:
+        return None
+
+
+def _positive(value: Any) -> bool:
+    return isinstance(value, int) and not isinstance(value, bool) and value >= 0
+
+
+class _JobConnection(http.client.HTTPConnection):
+    """A connection whose server end must be launchd's job `job_pid`, running as `job_uid`, its UserName's uid (a
+    LaunchDaemon runs as its UserName, so the installer, root, reads it as another account's: the job's own pid and
+    uid are the proof, FAA-278; contract DEC-0161, proposed: RT-3 extended to launchd's system domain)."""
+
+    def __init__(self, host: str, port: int, job_pid: int, timeout: float, job_uid: Optional[int] = None) -> None:
+        if not isinstance(job_pid, int) or isinstance(job_pid, bool) or job_pid <= 1:
+            raise ServiceError("A LaunchDaemon's answer is read only on its job's pid, a positive number.")
+        if not _positive(job_uid):
+            raise ServiceError("A LaunchDaemon's answer is read only from its UserName's uid, a number.")
+        super().__init__(host, port, timeout=timeout)
+        self.job_pid = job_pid
+        self.job_uid = job_uid
+
+    def connect(self) -> None:
+        super().connect()
+        owner = _po.server_end(self.sock)
+        restricted = owner.kind == _po.UNKNOWN and (owner.reason or "").startswith(_po.TABLE_RESTRICTED)
+        if owner.pid == self.job_pid and not _job_listens(self.job_pid, self.port):
+            self.close()
+            # The job's pid, but lsof did not show it bound to exactly 127.0.0.1:<port>: a wildcard is never vouched for.
+            raise _po.ListenerRefused(_po.SERVER_NOT_OWN, "the LaunchDaemon's pid %d is not shown listening on exactly "
+                                      "127.0.0.1:%d by lsof (a wildcard is never vouched for); nothing was sent"
+                                      % (self.job_pid, self.port))
+        if owner.pid == self.job_pid or (restricted and _job_listens(self.job_pid, self.port)):
+            runs_as = _pid_uid(self.job_pid)
+            if runs_as == self.job_uid:
+                return
+            self.close()
+            # Not the restricted owner: the pid was proved, only its uid is wrong, and the error says so.
+            raise _po.ListenerRefused(_po.SERVER_NOT_OWN, "the LaunchDaemon's pid %d runs as uid %s, not its UserName's "
+                                      "uid %d; nothing was sent" % (self.job_pid, runs_as, self.job_uid))
+        self.close()
+        raise _po.ListenerRefused(_po.SERVER_NOT_OWN, "the server on port %d is not the LaunchDaemon's pid %d (%s): "
+                                  "another process holds the port, or the job's program starts the server as a child "
+                                  "(start it with exec); nothing was sent"
+                                  % (self.port, self.job_pid, owner.reason or owner.kind), owner)
+
+
+def _read_job_well_known(origin: str, job_pid: int, job_uid: Optional[int] = None,
+                         timeout: float = 2.0) -> Tuple[Optional[Dict[str, Any]], Optional[str]]:
+    """As `_read_well_known`, for a LaunchDaemon: a loopback origin is read only when launchd's job `job_pid`, running as
+    `job_uid`, accepted the connection; (the answer or None, why the listener was refused or None)."""
+    try:
+        port = urllib.parse.urlsplit(origin).port
+    except ValueError:  # a port out of range
+        port = None
+    if not (port and 1 <= port <= 65535 and origin == "http://127.0.0.1:%d" % port):
+        raise ServiceError("A LaunchDaemon's answer is read only at http://127.0.0.1:<port>, where its job's pid and uid "
+                           "prove it; %s is not." % origin)
+    conn = _JobConnection("127.0.0.1", port, job_pid, timeout, job_uid)
+    try:
+        conn.request("GET", "/.well-known/fabric-service", headers={"Host": "127.0.0.1:%d" % port})
+        response = conn.getresponse()
+        return (json.loads(response.read().decode()) if response.status == 200 else None), None
+    except _po.ListenerRefused as exc:
+        restricted = exc.owner is not None and (exc.owner.reason or "").startswith(_po.TABLE_RESTRICTED)
+        return None, "%s: %s" % (_po.TABLE_RESTRICTED if restricted else "foreign-user", exc)
+    except (OSError, ValueError, http.client.HTTPException):
+        return None, None
+    finally:
+        conn.close()
+
+
 def fetch_well_known(origin: str, timeout: float = 2.0) -> Optional[Dict[str, Any]]:
     """The well-known answer at `origin`, or None: nothing answers, the answer is not JSON, or the listener is not this
     OS account's process (DEC-0154 HA-2)."""
@@ -373,13 +521,13 @@ def fetch_well_known(origin: str, timeout: float = 2.0) -> Optional[Dict[str, An
 _OVERRIDE_ROW = re.compile(r'^\s*"([^"]+)"\s*=>\s*(\S+)\s*\Z')
 
 
-def launchd_override(label: str) -> Optional[str]:
+def launchd_override(label: str, domain: Optional[str] = None) -> Optional[str]:
     """The operator's launchd override for ``label``: ``"disabled"``, ``"enabled"``, None when
     none is recorded (a first install), or ``"unknown"`` when the table cannot be read.
 
-    Reads ``launchctl print-disabled gui/<uid>``; macOS 14+ prints ``=> disabled|enabled``,
+    Reads ``launchctl print-disabled gui/<uid>`` (``system`` with ``domain="system"``); macOS 14+ prints ``=> disabled|enabled``,
     older releases ``=> true|false`` (true means disabled)."""
-    result = _launchctl("print-disabled", _domain())
+    result = _launchctl("print-disabled", launchd_domain(domain=domain))
     if result.returncode != 0:
         return "unknown"
     for line in result.stdout.splitlines():
@@ -389,9 +537,63 @@ def launchd_override(label: str) -> Optional[str]:
     return None
 
 
+_PATH_ROW = re.compile(r"^\s*path\s*=\s*(.+?)\s*\Z")
+
+
+def _plist_field(path: Path, key: str) -> Optional[str]:
+    try:
+        value = plistlib.loads(Path(path).read_bytes()).get(key)
+    except Exception:  # unreadable or not a plist: it claims nothing
+        return None
+    return value if isinstance(value, str) else None
+
+
+def _same_file(a: Any, b: Any) -> bool:
+    """One file, whatever the case of its path (APFS ignores case, realpath keeps it)."""
+    try:
+        return os.path.samefile(str(a), str(b))
+    except OSError:
+        return os.path.realpath(str(a)) == os.path.realpath(str(b))
+
+
+def _label_holders(label: str, plist_path: Path) -> List[Path]:
+    """Other plists that hold launchd label ``label`` in the system domain (FAA-278): the plist launchd loaded the job
+    from, when it is not ``plist_path``, and any plist of that label beside ``plist_path``. Reading needs no root."""
+    found: List[Path] = []
+    result = _launchctl("print", "system/%s" % label)
+    if result.returncode == 0:
+        for line in (result.stdout or "").splitlines():
+            hit = _PATH_ROW.match(line)
+            if hit:
+                found.append(Path(hit.group(1)))
+                break
+    try:
+        siblings = sorted(Path(plist_path).parent.glob("*.plist"))
+    except OSError:
+        siblings = []
+    found += [p for p in siblings if _plist_field(p, "Label") == label]
+    return [p for p in dict.fromkeys(found) if not _same_file(p, plist_path)]
+
+
+def _answers(doc: Any, service_id: str, instance: str) -> bool:
+    """Whether a well-known answer names this service and instance; any other JSON is no answer."""
+    service = doc.get("service") if isinstance(doc, dict) else None
+    return isinstance(service, dict) and service.get("id") == service_id and service.get("instance") == instance
+
+
+def _refuse_held_label(label: str, plist_path: Path) -> None:
+    holders = _label_holders(label, plist_path)
+    if holders:
+        owner = _plist_field(holders[0], "UserName")
+        raise ServiceError("Label %s is already held by %s%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."
+                           % (label, holders[0], " (%s's)" % owner if owner else ""))
+
+
 def launchd_install(label: str, plist_path: Path, plist_bytes: bytes, *, origin: str,
                     service_id: str, instance: str = "default", timeout: float = 40.0,
-                    force_enable: bool = False) -> Dict[str, Any]:
+                    force_enable: bool = False, domain: Optional[str] = None) -> Dict[str, Any]:
     """Write + lint the plist, bootout and WAIT for unload, bootstrap (retry EIO 5), then
     poll the well-known document until it answers with this identity.
 
@@ -399,38 +601,111 @@ def launchd_install(label: str, plist_path: Path, plist_bytes: bytes, *, origin:
     label. A label the 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"}`` instead of the well-known document.
-    ``force_enable`` is for an operator who asked for the service to be switched on."""
+    ``force_enable`` 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 (its ``UserName``, not the installer, owns it).
+    A ``gui/<uid>`` bootstrap with no GUI session (SSH, a headless Mac after a FileVault restart) says so."""
     plist_path = Path(plist_path)
+    dom = launchd_domain(plist_path, domain)
+    which = "system" if dom == "system" else None
+    _need_root(dom, label, plist_path, True)
+    if dom == "system":
+        try:
+            port = urllib.parse.urlsplit(origin).port
+        except ValueError:  # a port out of range
+            port = None
+        if not (port and 1 <= port <= 65535 and origin == "http://127.0.0.1:%d" % port):
+            raise 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); %s is not." % origin)
+        try:
+            named = plistlib.loads(plist_bytes).get("UserName")
+        except Exception:  # a plist that does not parse fails plutil -lint below
+            named = None
+        named = named if isinstance(named, str) else None  # a UserName that is not a string names no account
+        if named:
+            _refuse_held_label(label, plist_path)
+        if named and plist_path.exists():
+            installed_label = _plist_field(plist_path, "Label")
+            if installed_label is not None and installed_label != label:
+                raise ServiceError("%s holds launchd label %s, not %s: 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 "
+                                   "%s/%s.plist." % (plist_path, installed_label, label, SYSTEM_DAEMONS, label))
+            installed = _plist_field(plist_path, "UserName")
+            if installed and installed != named:
+                raise ServiceError("%s is %s'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." % (plist_path, installed))
+        if named and not _USER_NAME.match(named):
+            raise ServiceError("UserName %s is not a macOS short name (%s): launchd takes the account's short name."
+                               % (named, _USER_NAME.pattern))
+        job_uid = _account_uid(named) if named else None
+        if named and job_uid is None:
+            raise ServiceError("UserName %s is no account of this Mac: launchd would not start the job. Name the account "
+                               "whose Fabric and agents call the service." % named)
+        if job_uid == 0:
+            raise ServiceError("UserName %s 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." % named)
+        if not named:
+            raise 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 "
+                               "launchd_plist(..., user_name=<the account whose Fabric and agents call it>).")
     atomic_write(plist_path, plist_bytes, 0o644)
     lint = subprocess.run(["plutil", "-lint", str(plist_path)], capture_output=True, text=True)
     if lint.returncode != 0:
         raise ServiceError("plist failed plutil -lint: %s" % lint.stdout.strip())
-    target = "%s/%s" % (_domain(), label)
-    override = launchd_override(label)
+    target = "%s/%s" % (dom, label)
+    override = launchd_override(label, which)
     if force_enable or override is None:
         _launchctl("enable", target)
     elif override == "disabled":
-        return {"disabled": True, "label": label, "plist": str(plist_path), "loaded": launchd_loaded(label)}
+        return {"disabled": True, "label": label, "plist": str(plist_path), "loaded": launchd_loaded(label, which)}
     _launchctl("bootout", target)
     deadline = time.time() + 15
-    while launchd_loaded(label) and time.time() < deadline:
+    while launchd_loaded(label, which) and time.time() < deadline:
         time.sleep(0.25)
     last = ""
     for _ in range(5):
-        result = _launchctl("bootstrap", _domain(), str(plist_path))
+        result = _launchctl("bootstrap", dom, str(plist_path))
         if result.returncode == 0:
             break
         last = (result.stderr or result.stdout).strip()
         time.sleep(1.0)
     else:
+        if dom != "system" and re.search(r":\s*125:|Domain does not support|Could not find domain", last):
+            raise ServiceError("launchctl bootstrap failed: %s. This user has no GUI login session (an SSH session, or a "
+                               "headless Mac after a FileVault restart), so %s does not run jobs: remove the LaunchAgent "
+                               "this attempt wrote (launchd_uninstall), then install it as a LaunchDaemon in the system "
+                               "domain (a plist in %s with UserName, as root; FAA-278)." % (last, dom, SYSTEM_DAEMONS))
         raise ServiceError("launchctl bootstrap failed: %s" % last)
     deadline = time.time() + timeout
+    if dom == "system":
+        foreign = None
+        while time.time() < deadline:
+            job = launchd_pid(label, "system")
+            doc, why = _read_job_well_known(origin, job, job_uid) if job else (None, None)
+            foreign = why or foreign  # the last refusal stays the reason while launchd shows no pid
+            if _answers(doc, service_id, instance):
+                return doc
+            time.sleep(0.5)
+        loaded = ("; the job stays loaded and its plist starts it again at boot: as root, `launchctl bootout system/%s` "
+                  "and removing %s (or launchd_uninstall) take it away" % (label, plist_path))
+        if foreign and foreign.startswith(_po.TABLE_RESTRICTED):
+            raise ServiceError("%s could not be proved this LaunchDaemon's: %s; the job's pid did not show the listener: "
+                               "start the server with exec (no wrapper child), or read the job's log%s."
+                               % (origin, foreign, loaded))
+        if foreign:
+            raise ServiceError("%s is not this LaunchDaemon's: %s%s." % (origin, foreign, loaded))
+        raise ServiceError("%s did not answer as %s.%s within %.0f s; read its log%s."
+                           % (origin, service_id, instance, timeout, loaded))
     foreign = vouch = None
     while time.time() < deadline:
         doc, foreign = _read_well_known(origin, vouch_pid=vouch)
         if foreign and foreign.startswith(_po.TABLE_RESTRICTED):
             vouch = launchd_pid(label)  # only a restricted table needs the job's pid (FAA-267)
-        if doc and doc.get("service", {}).get("id") == service_id and doc.get("service", {}).get("instance") == instance:
+        if _answers(doc, service_id, instance):
             return doc
         time.sleep(0.5)
     if foreign:
@@ -445,20 +720,31 @@ def launchd_install(label: str, plist_path: Path, plist_bytes: bytes, *, origin:
 
 
 def launchd_uninstall(label: str, plist_path: Path, *, timeout: float = 30.0, purge: bool = False,
-                      service_id: Optional[str] = None, instance: str = "default") -> Dict[str, Any]:
+                      service_id: Optional[str] = None, instance: str = "default",
+                      domain: Optional[str] = None) -> Dict[str, Any]:
     """Symmetric with ``launchd_install`` (LC-14): bootout and WAIT until the job is gone, remove
     the plist, and reset the override to ``enabled`` — launchctl has no verb that deletes an
     override, and a leftover ``disabled`` would make a later fresh install stay off. Data stays
     unless ``purge`` (then ``service_id`` names whose data, logs and cache go, and ``instance`` which
     instance's: ``instance_dirs``, so one context's purge never reaches another's, FAA-125). A job still
-    loaded at ``timeout`` raises, leaving the plist and data in place."""
+    loaded at ``timeout`` raises, leaving the plist and 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: remove the data as that user (FAA-278)."""
     if purge and not service_id:
         raise ServiceError("purge needs the service id whose data, logs and cache to remove.")
+    dom = launchd_domain(Path(plist_path), domain)
+    which = "system" if dom == "system" else None
+    _need_root(dom, label, Path(plist_path), False)
+    if purge and dom == "system":
+        raise 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":
+        _refuse_held_label(label, Path(plist_path))  # a bootout would stop another plist's job (FAA-278)
     dirs = instance_dirs(str(service_id), instance) if purge else {}
-    target = "%s/%s" % (_domain(), label)
+    target = "%s/%s" % (dom, label)
     _launchctl("bootout", target)
     deadline = time.monotonic() + timeout
-    while launchd_loaded(label):
+    while launchd_loaded(label, which):
         if time.monotonic() >= deadline:
             raise ServiceError("launchd job %s is still loaded %.0f s after bootout; nothing was removed." % (label, timeout))
         time.sleep(0.1)