@passioncode-ai/fabric-agent-adapter 0.82.0 → 0.84.1

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

@@ -1,6 +1,9 @@
+// SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 // Which OS account owns each end of a loopback TCP connection (DEC-0154 HA-2, FAA-226, layer L0); the twin of
-// fabric_peer_owner.py, which is Project Observatory's peer_owner 1.1.0 vendored by commit. Node 18+, no dependency;
-// nothing here imports another kit module.
+// fabric_peer_owner.py, which is Project Observatory's peer_owner vendored by commit (its 1.3.1 line). Node 18+, no
+// dependency; the one kit module it may load is fabric-socket-proof.mjs beside it (DEC-0155 RT-2, FAA-292): on a
+// restricted macOS table a server end or listener one of this account's own processes holds is this account's, and
+// without that file this one answers as before.
 //
 // WHY. Loopback is one per computer, not one per OS account: every account's processes reach every listener on
 // 127.0.0.1, so a loopback socket proves nothing about who is on the other end. A client about to send a credential
@@ -47,7 +50,7 @@ import net from 'node:net';
 import os from 'node:os';
 import { fileURLToPath } from 'node:url';
 
-export const PEER_OWNER_VERSION = '1.2.0+kit.6'; // the Python twin's, Observatory's 1.2.0 with the kit's differences
+export const PEER_OWNER_VERSION = '1.3.1+kit.8'; // the Python twin's, Observatory's 1.3.1 line with the kit's differences
 export const THIS_ACCOUNT = 'this-account';
 export const ANOTHER_ACCOUNT = 'another-account';
 export const SYSTEM = 'system';
@@ -478,10 +481,36 @@ async function oneOwner(found, how, opts, noneReason = null) {
   return owner(UNKNOWN, { method: how, reason: 'several-rows' });
 }
 
+// fabric-socket-proof.mjs beside this file, loaded once (DEC-0155 RT-2, FAA-292); null when it is not there.
+let socketProof;
+
+// `fallback`, unless it is a restricted macOS table's unknown and fabric-socket-proof finds the socket (`accepted`) or
+// the 127.0.0.1 listener (`ownListener`, FAA-272) in this account's own processes; else it stands. A test that injects
+// a table (`read`, `run`) reaches this host's processes only through the `socketProof` it names.
+async function proved(ask, args, fallback, opts = {}) {
+  if (fallback.kind !== UNKNOWN || !String(fallback.reason ?? '').startsWith(TABLE_RESTRICTED)) return fallback;
+  if ((opts.platform ?? process.platform) !== 'darwin') return fallback;
+  let module = opts.socketProof;
+  if (module === undefined) {
+    if (opts.read || opts.run) return fallback;
+    if (socketProof === undefined) socketProof = await import('./fabric-socket-proof.mjs').catch(() => null);
+    module = socketProof;
+  }
+  let p = null;
+  try {
+    p = module ? await module[ask](...args) : null;
+  } catch {
+    p = null; // a proof that fails proves nothing; the table's answer stands (fail closed)
+  }
+  return p?.proved ? owner(THIS_ACCOUNT, { uid: opts.ownUid ?? ownUid(), pid: p.pid, method: p.method, reason: p.reason }) : fallback;
+}
+
 // The owner of the CLIENT socket of the connection between `server` and `client` ([host, port] each), as a server sees
 // them: the row whose local address is the client's and whose remote address is the server's.
-export function peerAt(server, client, opts) {
-  return ownerOf(address(client[0], client[1]), address(server[0], server[1]), opts);
+export async function peerAt(server, client, opts) {
+  const c = address(client[0], client[1]);
+  const s = address(server[0], server[1]);
+  return proved('accepted', [c, s, { wait: false }], await ownerOf(c, s, opts), opts);
 }
 
 // For a server's accepted socket: who connected. Reads nothing from the socket.
@@ -494,9 +523,11 @@ export function peer(socket, opts) {
 // address is this socket's own, the server process's accepted socket, so a listener swapped after listen cannot pass
 // for the one that answers. On Linux a connection not yet accept()ed has no owner of its own (inode 0): its listener
 // answers (the contract's CT-254, HA-2's Linux source).
-export function serverEnd(socket, opts) {
-  if (!socket.remoteAddress || !socket.localAddress) return Promise.resolve(owner(UNKNOWN, { reason: 'socket: not connected' }));
-  return ownerOf(address(socket.remoteAddress, socket.remotePort), address(socket.localAddress, socket.localPort), opts, true);
+export async function serverEnd(socket, opts) {
+  if (!socket.remoteAddress || !socket.localAddress) return owner(UNKNOWN, { reason: 'socket: not connected' });
+  const s = address(socket.remoteAddress, socket.remotePort);
+  const own = address(socket.localAddress, socket.localPort);
+  return proved('accepted', [s, own, { wait: true }], await ownerOf(s, own, opts, true), opts);
 }
 
 const LISTEN_ORDER = ['127.0.0.1', '*', '::1'];
@@ -524,12 +555,12 @@ export async function listener(port, opts = {}) {
   try {
     table = await (read ?? readTable)(opts);
   } catch (err) {
-    const who = owner(UNKNOWN, { method: method(), reason: err instanceof TableUnreadable ? err.message : `table: ${err.name}` });
+    const who = await proved('ownListener', [port], owner(UNKNOWN, { method: method(), reason: err instanceof TableUnreadable ? err.message : `table: ${err.name}` }), opts);
     if (!injected) listeners.set(port, [at, who]);
     return who;
   }
-  const who = restricted(table.rows, table.how, opts) ? await restrictedListener(table.rows, port, table.how, opts)
-    : await oneOwner(pickListener(table.rows, port), table.how, opts);
+  const who = await proved('ownListener', [port], restricted(table.rows, table.how, opts)
+    ? await restrictedListener(table.rows, port, table.how, opts) : await oneOwner(pickListener(table.rows, port), table.how, opts), opts);
   if (!injected) listeners.set(port, [at, who]);
   return who;
 }
@@ -552,18 +583,23 @@ export function refusal(who, port, expectPid = null) {
   return null;
 }
 
-// macOS, when the socket table is restricted (FAA-267, DEC-0155 RT-3): whether process `pid`, this account's, listens on
-// exactly 127.0.0.1:<port> (never the IPv4 wildcard, which lsof prints as it prints an IPv6-only one, nor ::1; FAA-312).
+// macOS, when the socket table is restricted (FAA-267, DEC-0155 RT-3): whether process `pid` listens on exactly
+// 127.0.0.1:<port> (never the IPv4 wildcard, which lsof prints as it prints an IPv6-only one, nor ::1; FAA-312).
 // `lsof -p` asks the process itself, which the restriction does not hide. Only a caller that started `pid` itself (a
-// launchd job it installed) may vouch with it, and never a set-uid one (its real and effective uid differ, DEC-0155).
-export async function pidListens(pid, port, { run = runProgram, platform = process.platform, ownUid: mine, ownEuid } = {}) {
+// launchd job it installed) may vouch with it, and never a set-uid one for this account (its real and effective uid
+// differ, DEC-0155). `owner`: the uid `pid` must run as, this account's by default, or null when the caller checks it
+// itself (a LaunchDaemon's UserName, FAA-286); anything else is a RangeError.
+export async function pidListens(pid, port, { run = runProgram, platform = process.platform, ownUid: mine, ownEuid, owner: want = THIS_ACCOUNT } = {}) {
+  if (want !== null && want !== THIS_ACCOUNT && !(Number.isInteger(want) && want >= 0)) throw new RangeError('owner is this-account, a uid or null');
   if (platform !== 'darwin' || !Number.isInteger(pid) || pid <= 1) return false;
   const real = mine ?? ownUid();
   const effective = ownEuid ?? (typeof process.geteuid === 'function' ? process.geteuid() : real);
-  if (effective !== real) return false;
+  if (want === THIS_ACCOUNT && effective !== real) return false;
   try {
-    const uid = parsePsUid(await run(PS, ['-o', 'uid=', '-p', String(pid)]));
-    if (uid === null || uid !== real) return false;
+    if (want !== null) {
+      const uid = parsePsUid(await run(PS, ['-o', 'uid=', '-p', String(pid)]));
+      if (uid === null || uid !== (want === THIS_ACCOUNT ? real : want)) return false;
+    }
     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);
   } catch {
@@ -591,8 +627,9 @@ export function checkedSocket(port, { host = '127.0.0.1', timeoutMs = 10000, exp
         // A reader that throws (an injected one; the readers themselves answer unknown) fails closed.
         who = owner(UNKNOWN, { method: method(), reason: `check: ${err?.name ?? 'Error'}` });
       }
+      // The vouch proves a listener on exactly 127.0.0.1, so only a connection that reached it (FAA-273 item 12).
       if (who.kind === UNKNOWN && String(who.reason ?? '').startsWith(TABLE_RESTRICTED) && vouchPid
-        && await pidListens(vouchPid, port, ask)) {
+        && normHost(socket.remoteAddress) === '127.0.0.1' && await pidListens(vouchPid, port, ask)) {
         // The table hides other processes (FAA-267); the process this caller started holds the listener.
         who = owner(THIS_ACCOUNT, { uid: ask.ownUid ?? ownUid(), pid: vouchPid, method: 'lsof-pid' });
       }

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

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 // Windows, where the kit needs it (DEC-0032): reading a file's ACL to refuse a token file others can read.
 // Part of the Node service kit (FAA-65, layer L1); the twin of fabric_platform.py. Node 20+, no dependency.
 import crypto from 'node:crypto';

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

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 // Runner and model profiles in the kit (Fabric Agent Contract DEC-0046, Fabric ADR-0147). A port of the contract's
 // `src/profile-rules.ts` at the pin — resolveModelProfile and the FAC-SEM-058…060 checks — held to the contract's own
 // answers by test/fixtures/contract/profile-vectors.json; plus the doctor's runner and model checks (runners.md C2) and

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

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 // Protocol revisions (DEC-0067) and an event's machine-readable data (DEC-0070, the feed-data protocols).
 // Part of the Node service kit (FAA-65, layer L3); the twin of fabric_protocols.py. Node 20+, no dependency.
 import { credentialName, secretArgument, secretUrl, secretValue } from './fabric-secrets.mjs';

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

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 // The contract's one credential detector (Fabric Agent Contract DEC-0044, `src/secret-shape.ts` at the pin): a name
 // that can only carry a credential, a value shaped like one, a launch argument that carries one, and a URL that does
 // (LC-21). A port held to the contract's own answers by test/fixtures/contract/profile-vectors.json. No dependencies.
@@ -124,12 +125,25 @@ const REPOSITORY_AUTHORITY = /^[A-Za-z][A-Za-z0-9+.-]*:\/\//;
 // boundary, so composed after a separator look-behind it would miss a key after `-`, `.` or `_`.
 const REPOSITORY_KEYS = 'sk-[A-Za-z0-9_-]{16,}|gh[pousr]_[A-Za-z0-9]{20,}|xox[abposr]-[A-Za-z0-9-]{10,}|AKIA[0-9A-Z]{16}|glpat-[A-Za-z0-9_-]{20,}';
 const KEY_AT_A_WORD = new RegExp(`(?:^|(?<=[._-]))(?:${REPOSITORY_KEYS})`);
-const JWT_AT_A_WORD = new RegExp(`(?:^|(?<=[._-]))${JWT_SHAPE.source}`);
+/** Whether JWT_SHAPE matches at a word's start: the text's start, or after a `.`, `_` or `-` (FAA-321), read in one
+ * pass as jwtSpans: only a run's first `eyJ` at a word's start is tried (fabric_secrets.jwt_at_a_word). */
+export function jwtAtAWord(text) {
+  for (let at = text.indexOf('eyJ'); at >= 0;) {
+    if (at > 0 && !'._-'.includes(text[at - 1])) { at = text.indexOf('eyJ', at + 1); continue; }
+    const one = runEnd(text, at + 3);
+    if (one - at - 3 >= 2 && text[one] === '.') {
+      const two = runEnd(text, one + 1);
+      if (two - one - 1 >= 2 && text[two] === '.') return true;
+    }
+    at = text.indexOf('eyJ', one);
+  }
+  return false;
+}
 const SPECIAL_QUERY = /^(?:https?|wss?|ftp|file):/i; // whose query also encodes `'`, as the URL standard does
 
 /** Whether a path segment reads as a repository's name: lower case, or letters with no digit, with no provider key's
  * or JWT's shape at its start or after a `.`, `_` or `-` (0.62.0 readings 9 and 10), so a letters-only key is a key. */
-export const repositoryName = (piece) => REPOSITORY_NAME.test(piece) && !KEY_AT_A_WORD.test(piece) && !JWT_AT_A_WORD.test(piece);
+export const repositoryName = (piece) => REPOSITORY_NAME.test(piece) && !KEY_AT_A_WORD.test(piece) && !jwtAtAWord(piece);
 
 /** Every `%XX` escape of an ASCII character decoded, the rest as written (fabric_secrets.ascii_decoded, readings 11). */
 export const asciiDecoded = (text) => text.replace(/%([0-7][0-9A-Fa-f])/g, (_, hex) => String.fromCharCode(parseInt(hex, 16)));

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

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 // Reference kit for the fabric-service/0.1 local service extension, Node: the facade (the twin of fabric_service.py).
 // Since 0.40.0 (FAA-65) the kit is a set of modules and this file re-exports everything it exported at 0.39.1, so
 // `import * as k from './fabric-service.mjs'` keeps working. Install it with `fabric_kit.py install <dir> --lang node`,

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

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 // Share grants into an organization and their registrations (contract DEC-0086), the Node kit; the twin of
 // fabric_share.py, answer for answer (test/fixtures/contract/share-vectors.json). Node built-ins only.
 // FAC-SEM-117 (a share grant's id, window and agentRef, with parent), FAC-SEM-118 (a share-registration/1 document) and

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

@@ -0,0 +1,181 @@
+// SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
+// This OS account's own TCP sockets, read from its own processes (layer L0; DEC-0155 RT-2, FAA-292; FAA-272); the twin
+// of fabric_socket_proof.py. Node 18+, no dependency; nothing here imports another kit module.
+//
+// macOS 27.2 shows an ad-hoc-signed runtime (Homebrew's Node) only its own sockets, so fabric-peer-owner reads such a
+// table as table-restricted and cannot tell who accepted a connection. The question can still be asked of this
+// account's own processes, which the restriction leaves readable: whether one of them holds the very socket that
+// accepted the connection (RT-2, the accepted-socket proof), or a listener bound exactly to 127.0.0.1:<port> (HA-2's
+// macOS row, FAA-272). Another account's process is not listed, so a proof only ever says "this account's" or "not
+// proved"; never another account's, the system's or nobody's.
+//
+//   await accepted(server, client, { wait })   the socket at `server` connected to `client` is in one of this
+//                                              account's processes (`wait`: read again for ACCEPT_WAIT_MS until the
+//                                              server has called accept())
+//   await ownListener(port)                    a listener of this account on exactly 127.0.0.1:<port>
+//
+// Node has no ctypes, so the twin reads RT-2's other named source, `lsof -nP -a -u <uid> -iTCP:<port> -sTCP:<state>
+// -F pun`, matching the exact address pair and the numeric uid, where the Python twin reads the same records through
+// libproc (lsof only when libproc is unavailable). The twins agree on answers, not on the program they run (DEC-0155
+// Compatibility); test/fixtures/peer-owner/socket-proof-cases.json holds both. The proof is "a process of this uid
+// holds the descriptor", weaker than a table's so_uid: a socket passed with SCM_RIGHTS to a process of this uid reads
+// as this account's, which a caller that knows the server's pid closes with expectPid. One socket several of this
+// account's processes hold is proved with pid null, reason several-processes. A process whose real and effective uids
+// differ is refused (setuid-context). Reasons: table-restricted (read, nothing of this account matches) or
+// `table-restricted: <detail>` (the proof could not be read). Bounded by TIMEOUT_MS and MAX_OUTPUT_BYTES.
+
+import { execFile } from 'node:child_process';
+import net from 'node:net';
+
+export const TABLE_RESTRICTED = 'table-restricted';
+export const LSOF_METHOD = 'lsof';
+export const LSOF = '/usr/sbin/lsof';
+export const TIMEOUT_MS = 2000;
+export const ACCEPT_WAIT_MS = 500;
+export const MAX_OUTPUT_BYTES = 4 * 1024 * 1024;
+
+const proof = (proved, pid, method, reason) => Object.freeze({ proved, pid, method, reason });
+const digits = (text) => /^[0-9]+$/.test(text);
+
+// One spelling per address, as fabric-peer-owner's normHost (the same rule, kept here so this module stands alone): an
+// IPv4-mapped IPv6 address is its IPv4 form, the unspecified address `*`, an IPv6 address RFC 5952's.
+function host(text) {
+  let h = String(text ?? '').replace(/^\[(.*)\]$/, '$1');
+  if (h === '*' || h === '') return '*';
+  if (h === 'localhost') return '127.0.0.1';
+  h = h.split('%', 1)[0];
+  if (net.isIPv4(h)) return h === '0.0.0.0' ? '*' : h.split('.').map((x) => String(Number(x))).join('.');
+  if (!net.isIPv6(h)) return h;
+  const t = new URL(`http://[${h}]/`).hostname.slice(1, -1);
+  if (t === '::') return '*';
+  const mapped = /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(t);
+  if (!mapped) return t;
+  const hi = parseInt(mapped[1], 16);
+  const lo = parseInt(mapped[2], 16);
+  const v4 = [hi >> 8, hi & 255, lo >> 8, lo & 255].join('.');
+  return v4 === '0.0.0.0' ? '*' : v4;
+}
+
+// Whether `new URL(...).hostname` names this computer's loopback: localhost or a name under .localhost, ::1, or an IPv4
+// address in 127/8 (new URL has already read 127.1, 2130706433, 0x7f.1 and a trailing dot as 127.x.y.z); never an
+// IPv4-mapped address, which new URL writes in hex. The one rule fabric-http's checkUrl and fabric-delegation's key set
+// source read (FAA-187 (15)); the twin of fabric_socket_proof.loopback_host.
+export function loopbackHost(hostname) {
+  const h = String(hostname ?? '').toLowerCase().replace(/^\[(.*)\]$/, '$1');
+  if (h === 'localhost' || h.endsWith('.localhost') || h === '::1') return true;
+  return /^127\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}$/.test(h) && h.split('.').every((x) => Number(x) <= 255);
+}
+
+function lsofAddress(text) {
+  const at = text.lastIndexOf(':');
+  if (at < 0) return null;
+  const port = text.slice(at + 1);
+  if (!digits(port) || Number(port) > 65535) return null;
+  return [host(text.slice(0, at)), Number(port)];
+}
+
+// `lsof -nP -a -u <uid> -iTCP:<port> -sTCP:<state> -F pun`: the `n` lines of every process block whose `u` line is
+// exactly `uid` (a block of another uid, or with no uid, is not read). A name with `->` is a connection, one without a
+// listener. The same socket listed by several processes (one address pair) is one socket with pid null.
+export function parseLsofSockets(text, uid) {
+  const found = new Map();
+  let pid = null;
+  let owner = null;
+  for (const line of String(text).split(/\r?\n/)) {
+    const tag = line.slice(0, 1);
+    const value = line.slice(1);
+    if (tag === 'p') {
+      pid = digits(value) ? Number(value) : null;
+      owner = null;
+    } else if (tag === 'u') {
+      owner = digits(value) ? Number(value) : null;
+    } else if (tag === 'n' && pid !== null && owner === uid) {
+      const arrow = value.indexOf('->');
+      const local = lsofAddress(arrow < 0 ? value : value.slice(0, arrow));
+      const remote = arrow < 0 ? ['*', 0] : lsofAddress(value.slice(arrow + 2));
+      if (!local || !remote) continue;
+      const key = JSON.stringify([local, remote, arrow < 0]);
+      if (!found.has(key)) found.set(key, { local, remote, listening: arrow < 0, pids: [] });
+      found.get(key).pids.push(pid);
+    }
+  }
+  return [...found.values()].map(({ local, remote, listening, pids }) => ({
+    local, remote, listening, pid: new Set(pids).size === 1 ? pids[0] : null,
+  }));
+}
+
+const same = (a, b) => a[0] === b[0] && a[1] === b[1];
+
+function proved(hits, how) {
+  if (hits.length === 0) return proof(false, null, how, TABLE_RESTRICTED);
+  const pids = new Set(hits.map((s) => s.pid));
+  if (pids.size === 1 && !pids.has(null)) return proof(true, hits[0].pid, how, null);
+  return proof(true, null, how, 'several-processes');
+}
+
+// RT-2 over this account's sockets: the one at `server` connected to `client`; two with that pair are several-rows.
+export function acceptedIn(sockets, server, client, how) {
+  const hits = sockets.filter((s) => !s.listening && same(s.local, server) && same(s.remote, client));
+  if (hits.length > 1) return proof(false, null, how, 'several-rows');
+  return proved(hits, how);
+}
+
+// FAA-272 over this account's sockets: a listener bound exactly to 127.0.0.1:<port> (DEC-0155 RT-4: our wildcard or
+// ::1 listener, and root's, cannot be told from a hidden one).
+export function listenerIn(sockets, port, how) {
+  return proved(sockets.filter((s) => s.listening && same(s.local, ['127.0.0.1', port])), how);
+}
+
+class ProofUnreadable extends Error {}
+
+// One bounded run of lsof; its exit 1 with nothing printed is "no socket matched", not a failure.
+export function runLsof(file, args, timeout = TIMEOUT_MS) {
+  return new Promise((resolve, reject) => {
+    execFile(file, args, { timeout, maxBuffer: MAX_OUTPUT_BYTES, encoding: 'utf8' }, (err, stdout) => {
+      if (!err) return resolve(stdout);
+      if (err.code === 1 && !String(stdout ?? '').trim()) return resolve('');
+      const why = typeof err.code === 'number' ? `exit ${err.code}` : (err.killed ? 'timeout' : (err.code ?? 'error'));
+      reject(new ProofUnreadable(`lsof: ${err.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER' ? `output over ${MAX_OUTPUT_BYTES} bytes` : why}`));
+    });
+  });
+}
+
+// The reader a question uses: lsof on macOS, none elsewhere.
+export const method = (platform = process.platform) => (platform === 'darwin' ? LSOF_METHOD : 'none');
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+async function ask(port, state, pick, waitMs, { platform = process.platform, uid, euid, run = runLsof, now = () => Date.now() } = {}) {
+  const start = now();
+  if (platform !== 'darwin') return proof(false, null, 'none', `${TABLE_RESTRICTED}: unsupported-platform`);
+  const real = uid ?? process.getuid();
+  const effective = euid ?? (typeof process.geteuid === 'function' ? process.geteuid() : real);
+  if (real !== effective) return proof(false, null, LSOF_METHOD, `${TABLE_RESTRICTED}: setuid-context`);
+  let pause = 5;
+  for (;;) {
+    let have;
+    try {
+      have = parseLsofSockets(await run(LSOF, ['-nP', '-a', '-u', String(real), `-iTCP:${port}`, `-sTCP:${state}`, '-F', 'pun']), real);
+    } catch (err) {
+      return proof(false, null, LSOF_METHOD, `${TABLE_RESTRICTED}: ${err?.message ?? 'lsof: error'}`);
+    }
+    const answer = pick(have);
+    if (answer.proved || now() + pause > start + Math.min(waitMs, TIMEOUT_MS)) return answer;
+    await sleep(pause);
+    pause = Math.min(pause * 2, 50);
+  }
+}
+
+// RT-2: whether the socket at `server` connected to `client` ([host, port] each) is in one of this account's processes.
+// `wait`: read again for ACCEPT_WAIT_MS, since the server's accepted socket exists only once it calls accept().
+// `platform`, `uid`, `euid`, `run` and `now` are the tests'.
+export function accepted(server, client, { wait = false, ...opts } = {}) {
+  const s = [host(server[0]), Number(server[1])];
+  const c = [host(client[0]), Number(client[1])];
+  return ask(s[1], 'ESTABLISHED', (have) => acceptedIn(have, s, c, LSOF_METHOD), wait ? ACCEPT_WAIT_MS : 0, opts);
+}
+
+// FAA-272: whether one of this account's processes listens on exactly 127.0.0.1:<port>.
+export function ownListener(port, opts = {}) {
+  return ask(Number(port), 'LISTEN', (have) => listenerIn(have, Number(port), LSOF_METHOD), 0, opts);
+}

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

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 // Supervisors (DEC-0032, LC-14): systemd user units, Task Scheduler tasks and launchd plists, installed and removed without touching what the operator turned off; release pruning (LC-11, LC-15).
 // Part of the Node service kit (FAA-65, layer L3); the twin of fabric_supervisors.py. Node 20+, no dependency.
 import fs from 'node:fs';
@@ -9,8 +10,9 @@ 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, LSOF, ListenerRefused, PS, SERVER_NOT_OWN, TABLE_RESTRICTED, UNKNOWN, parseLsofListeners, parsePsUid,
+import { CheckedAgent, ListenerRefused, PS, SERVER_NOT_OWN, TABLE_RESTRICTED, UNKNOWN, parsePsUid, pidListens,
   runProgram, serverEnd } from './fabric-peer-owner.mjs';
+import { loopbackHost } from './fabric-socket-proof.mjs';
 import http from 'node:http';
 import net from 'node:net';
 
@@ -60,7 +62,7 @@ function noMarkerArgument(argv) {
 // An environment value: read path-aware (secretArgument) only when it reads as a path (it starts as one, has at least two
 // separators and a lower-case word between them), so a release folder under Application Support is no key (FAA-266) while
 // a base64 key whose `/` splits it stays one; any other value keeps the strict secretValue.
-const secretEnvValue = (value) => {
+export const secretEnvValue = (value) => {
   const pieces = value.split(/[\\/]/);
   const path = /^(?:[/~.]|[A-Za-z]:[\\/])/.test(value) && pieces.length >= 3 && pieces.some((x) => /^[a-z][a-z0-9_-]{2,}$/.test(x));
   return path ? secretArgument(value) : secretValue(value);
@@ -560,20 +562,30 @@ export class ForeignUserAnswer {
 // The well-known answer at a loopback origin, read only on a connection whose server end is this OS account's process
 // (DEC-0154 HA-2): null when nothing answers or the answer is not JSON, a ForeignUserAnswer when the listener is another
 // account's or its owner cannot be told.
-// Every loopback spelling (127.0.0.1, another 127/8 address, localhost, [::1]) goes on a checked connection, never the
+// Every loopback spelling (127/8 in any form, localhost or a name under it, [::1]) goes on a checked connection, never the
 // unchecked way (FAA-257): the host, without brackets, and the port, or null.
 function loopbackOrigin(origin) {
   let url;
   try { url = new URL(String(origin)); } catch { return null; }
   const host = url.hostname.replace(/^\[|\]$/g, '');
-  const loop = host === 'localhost' || host === '::1' || (net.isIPv4(host) && host.startsWith('127.'));
-  if (url.protocol !== 'http:' || !loop) return null;
+  // the kit's one loopback rule (FAA-326): a name under .localhost too, as the Python twin reads it
+  if (url.protocol !== 'http:' || !loopbackHost(host)) return null;
   // new URL drops a default port: http://127.0.0.1:80 has port '', read as 80 as Python's urlsplit reads it (0.79.0 seam)
   return { host, port: Number(url.port || 80) };
 }
 
+// An IPv4-mapped 127/8 origin (`new URL` writes it ::ffff:7f00:1): loopback the kit's rule does not take, which fetch would
+// reach unchecked, so it is refused unread, as the Python twin refuses it (0.84.0 seam reading).
+function mappedLoopback(origin) {
+  let host;
+  try { host = new URL(String(origin)).hostname; } catch { return false; }
+  const m = /^\[::ffff:([0-9a-f]{1,4}):[0-9a-f]{1,4}\]$/i.exec(host);
+  return !!m && parseInt(m[1], 16) >> 8 === 127;
+}
+
 export async function wellKnownOf(origin, { vouchPid = null, ask = undefined } = {}) {
   const m = loopbackOrigin(origin);
+  if (!m && mappedLoopback(origin)) return null;
   if (!m) {
     try {
       const response = await fetch(`${origin}/.well-known/fabric-service`, { signal: AbortSignal.timeout(2000) });
@@ -609,16 +621,9 @@ function loopbackWellKnown(port, agent, host = '127.0.0.1') {
 }
 
 // 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, platform = process.platform) {
-  if (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;
-  }
-}
+// which a restricted socket table does not hide. Only for a LaunchDaemon root bootstrapped, whose pid launchd named. The
+// peer owner's one lsof reader, the uid left to the caller, which checks the job's UserName itself (FAA-286 item 1).
+const jobListens = (pid, port, run = runProgram, platform = process.platform) => pidListens(pid, port, { run, platform, owner: null });
 
 // The uid account `name` has on this machine (`id -u`), or null when it has none.
 function accountUid(name, run) {