@passioncode-ai/fabric-agent-adapter 0.81.0 → 0.83.1

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

@@ -1,6 +1,8 @@
 // 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
@@ -40,12 +42,14 @@
 // privilege. The parsers are pure functions over captured text (test/fixtures/peer-owner/).
 
 import { execFile } from 'node:child_process';
+import { realpathSync } from 'node:fs';
 import { open } from 'node:fs/promises';
 import http from 'node:http';
 import net from 'node:net';
 import os from 'node:os';
+import { fileURLToPath } from 'node:url';
 
-export const PEER_OWNER_VERSION = '1.2.0+kit.5'; // the Python twin's, Observatory's 1.2.0 with the kit's differences
+export const PEER_OWNER_VERSION = '1.3.1+kit.7'; // 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';
@@ -62,6 +66,8 @@ export const LSOF = '/usr/sbin/lsof';
 // The reason a socket table hides other processes' sockets from this one (FAA-267): macOS 27.2 gives an ad-hoc-signed
 // runtime an empty netstat.
 export const TABLE_RESTRICTED = 'table-restricted';
+// A macOS table that lists sockets but not the reader's own connection (DEC-0155 RT-1, FAA-312).
+export const NO_ROW_RESTRICTED = `${TABLE_RESTRICTED}: no row for this connection`;
 export const SERVER_NOT_OWN = 'server-not-own';
 export const SERVER_UNVERIFIED = 'server-unverified';
 export const SERVER_NOT_THIS_WORKSPACE = 'server-not-this-workspace';
@@ -290,10 +296,10 @@ export function runProgram(file, args, timeout = TIMEOUT_MS) {
   });
 }
 
-export function method() {
-  if (process.platform === 'darwin') return 'netstat';
-  if (process.platform === 'linux') return 'proc';
-  if (process.platform === 'win32') return 'netstat-windows';
+export function method(platform = process.platform) {
+  if (platform === 'darwin') return 'netstat';
+  if (platform === 'linux') return 'proc';
+  if (platform === 'win32') return 'netstat-windows';
   return 'none';
 }
 
@@ -319,9 +325,18 @@ async function readProc(name) {
   return Buffer.concat(chunks);
 }
 
-export async function readTable({ run = runProgram } = {}) {
-  const how = method();
-  if (how === 'netstat') return { rows: parseNetstat(await run(NETSTAT, ['-anv', '-p', 'tcp'])), how };
+export async function readTable({ run = runProgram, platform = process.platform } = {}) {
+  const how = method(platform);
+  if (how === 'netstat') {
+    let text;
+    try {
+      text = await run(NETSTAT, ['-anv', '-p', 'tcp']);
+    } catch (err) {
+      // A netstat that fails, exits non-zero or times out is a restricted table (DEC-0155 RT-1, FAA-312).
+      throw new TableUnreadable(`${TABLE_RESTRICTED}: ${err instanceof TableUnreadable ? err.message : `netstat: ${err?.name ?? 'error'}`}`);
+    }
+    return { rows: parseNetstat(text), how };
+  }
   if (how === 'proc') {
     const rows = [];
     for (const [name, family] of [['/proc/net/tcp', 4], ['/proc/net/tcp6', 6]]) {
@@ -387,6 +402,21 @@ export async function resolve(row, how, { run = runProgram, ownUid: mine, ownSid
 
 // -- the questions ----------------------------------------------------------------------------------------------------
 
+// DEC-0155 RT-1 (FAA-312): a macOS table holding no row of another uid (sysctl, the Python twin's, which carries uids)
+// or of another process (netstat, which carries pids) is restricted, and a missing row proves nothing. Never on Linux
+// or Windows, which carry the owner on each row.
+export function restricted(rows, how, { ownUid: mine, ownPid } = {}) {
+  if (how === 'sysctl') {
+    const own = mine ?? ownUid();
+    return !rows.some((r) => r.uid !== null && r.uid !== undefined && r.uid !== own);
+  }
+  if (how === 'netstat') {
+    const own = ownPid ?? process.pid;
+    return !rows.some((r) => r.pid !== null && r.pid !== undefined && r.pid !== own);
+  }
+  return false;
+}
+
 // The live connected rows with exactly this local and remote address: one, or the caller cannot tell.
 // A row printed twice is one socket: Linux resumes a /proc read that sockets came and went under by position, and can
 // print the same row again (0.74.0 seam reading 6); rows equal in every field count once.
@@ -414,7 +444,8 @@ async function ownerOf(local, remote, opts = {}, server = false) {
     // A /proc read under churn can skip a row or print one twice; one more read before answering unknown.
     if (table.how !== 'proc' || found.length === 1) break;
   }
-  if (found.length === 0) return owner(UNKNOWN, { method: table.how, reason: 'no-row' });
+  // A macOS table without the reader's own connection is restricted (DEC-0155 RT-1, FAA-312).
+  if (found.length === 0) return owner(UNKNOWN, { method: table.how, reason: ['sysctl', 'netstat'].includes(table.how) ? NO_ROW_RESTRICTED : 'no-row' });
   if (found.length > 1) return owner(UNKNOWN, { method: table.how, reason: 'several-rows' });
   if (table.how === 'proc' && server && found[0].uid === null) {
     // Linux: a connection not yet accept()ed is printed with uid 0 and inode 0; it belongs to the listener on its local
@@ -449,10 +480,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.
@@ -465,9 +522,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'];
@@ -491,23 +550,28 @@ export async function listener(port, opts = {}) {
   const at = now();
   const hit = injected ? undefined : listeners.get(port);
   if (hit && at - hit[0] < LISTENER_TTL_MS) return hit[1];
-  let found;
-  let how;
   let table;
   try {
     table = await (read ?? readTable)(opts);
-    how = table.how;
-    found = pickListener(table.rows, port);
   } 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 = await oneOwner(found, 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;
 }
 
+// DEC-0155 RT-4 (FAA-312): under a restricted table only this account's own bind on exactly 127.0.0.1 is its own; its
+// wildcard or ::1 listener, root's, and a port with no row are an owner that cannot be told.
+async function restrictedListener(rows, port, how, opts) {
+  const who = await oneOwner(rows.filter((r) => r.listening && r.local[0] === '127.0.0.1' && r.local[1] === port), how, opts);
+  if (who.kind === THIS_ACCOUNT) return who;
+  return owner(UNKNOWN, { method: how, reason: `${TABLE_RESTRICTED}: no listener of this account on exactly 127.0.0.1:${port}` });
+}
+
 // [code, why] when a client must not send on a connection whose server end is `who`, else null.
 export function refusal(who, port, expectPid = null) {
   if (who.kind === ANOTHER_ACCOUNT || who.kind === SYSTEM) return [SERVER_NOT_OWN, `the server on port ${port} belongs to ${who.kind}`];
@@ -518,16 +582,25 @@ export function refusal(who, port, expectPid = null) {
   return null;
 }
 
-// macOS, when the socket table is restricted (FAA-267): whether process `pid`, this account's, listens on 127.0.0.1:<port>
-// or the IPv4 wildcard (IPv4 alone: a v6-only wildcard never vouches for a 127.0.0.1 connection). `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.
-export async function pidListens(pid, port, { run = runProgram, platform = process.platform, ownUid: mine } = {}) {
+// 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 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 (want === THIS_ACCOUNT && effective !== real) return false;
   try {
-    const uid = parsePsUid(await run(PS, ['-o', 'uid=', '-p', String(pid)]));
-    if (uid === null || uid !== (mine ?? ownUid())) 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' || host === '*') && p === port);
+    return parseLsofListeners(out).some(([host, p]) => host === '127.0.0.1' && p === port);
   } catch {
     return false;
   }
@@ -553,8 +626,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' });
       }
@@ -587,3 +661,32 @@ export class CheckedAgent extends http.Agent {
       expectPid: this.expectPid, vouchPid: this.vouchPid, ...this.ask }).then((socket) => callback(null, socket), (err) => callback(err));
   }
 }
+
+const USAGE = 'usage: fabric-peer-owner.mjs listener <port> [--json]\n';
+
+// `listener <port> [--json]`: the kind of who listens on 127.0.0.1:<port>, which the dashboard link gate takes as
+// listener_owner (FAA-315), or the whole owner as JSON; 2 on a usage error. `listener` and `write` are the tests'.
+export async function main(argv, { listener: ask = listener, write = (text) => process.stdout.write(text) } = {}) {
+  const asJson = argv.length === 3 && argv[2] === '--json';
+  const port = Number(argv[1]);
+  if (argv.length !== 2 + Number(asJson) || argv[0] !== 'listener' || !/^[0-9]+$/.test(argv[1] ?? '') || port < 1 || port > 65535) {
+    process.stderr.write(USAGE);
+    return 2;
+  }
+  const who = await ask(port);
+  write(asJson ? `${JSON.stringify({ kind: who.kind, uid: who.uid, pid: who.pid, method: who.method, reason: who.reason })}\n` : `${who.kind}\n`);
+  return 0;
+}
+
+// Whether node was started on this file, by real paths (a symlinked install folder, as check_dashboard_layout.mjs).
+function startedDirectly() {
+  try {
+    return Boolean(process.argv[1]) && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+if (startedDirectly()) {
+  main(process.argv.slice(2)).then((code) => { process.exitCode = code; }, (err) => { process.stderr.write(`${err?.message ?? err}\n`); process.exitCode = 1; });
+}

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

@@ -38,6 +38,31 @@ export function credentialName(name) {
 
 /** A JWT or JWS anywhere in a value. */
 export const JWT_SHAPE = /eyJ[A-Za-z0-9_-]{2,}\.[A-Za-z0-9_-]{2,}\.[A-Za-z0-9_-]*/;
+const isUrlBase64 = (code) => (code >= 0x41 && code <= 0x5a) || (code >= 0x61 && code <= 0x7a) || (code >= 0x30 && code <= 0x39)
+  || code === 0x2d || code === 0x5f;
+const runEnd = (text, from) => { let end = from; while (end < text.length && isUrlBase64(text.charCodeAt(end))) end += 1; return end; };
+/** The spans JWT_SHAPE matches in a text, leftmost and not overlapping, read in one pass (the contract's jwtSpans,
+ * FAA-313): the regular expression backtracks from every `eyJ` of a long run, quadratic in it, while every `eyJ` of one
+ * run shares that run's end, so only its first is tried, and a match ends where its third segment's run ends. `first`
+ * stops at the first match. */
+export function jwtSpans(text, first = false) {
+  const spans = [];
+  let from = 0;
+  for (let at = text.indexOf('eyJ', from); at >= 0; at = text.indexOf('eyJ', from)) {
+    const one = runEnd(text, at + 3);
+    from = one;
+    if (one - at - 3 < 2 || text[one] !== '.') continue;
+    const two = runEnd(text, one + 1);
+    if (two - one - 1 < 2 || text[two] !== '.') continue;
+    const three = runEnd(text, two + 1);
+    spans.push([at, three]);
+    if (first) break;
+    from = three;
+  }
+  return spans;
+}
+/** Whether JWT_SHAPE matches anywhere in a text, read in one pass (the contract's hasJwt, FAA-313). */
+export const hasJwt = (text) => jwtSpans(text, true).length > 0;
 /** A value that says it is a credential (`Bearer ` at its start, in any case), or a provider key's shape with its prefix
  * in its canonical case only, at the start of a value, after a character that is no ASCII letter or digit, or after an
  * escape; an `sk-` key holds a digit and an upper-case letter with 16 or more characters, or a digit with 32 or more,
@@ -48,7 +73,7 @@ const LONG_RUN = /[A-Za-z0-9+/=_-]{40,}/g;
 export const longSecret = (value) => (value.match(LONG_RUN) ?? []).some((run) => /[a-z]/.test(run) && /[A-Z]/.test(run) && /[0-9]/.test(run));
 
 /** Whether a value could be a credential: a JWT anywhere, a provider key or `Bearer …`, or a long secret-shaped run. */
-export const secretValue = (value) => JWT_SHAPE.test(value) || SECRET_VALUE.test(value) || longSecret(value);
+export const secretValue = (value) => hasJwt(value) || SECRET_VALUE.test(value) || longSecret(value);
 
 export const BEARER_INSIDE = /\bbearer\s+(?=[A-Za-z0-9._~+/-]*\d)[A-Za-z0-9._~+/-]{12,}=*/i;
 const PATH_LIKE = /^(?:[/~.]|[A-Za-z]:[\\/]|[a-z][a-z0-9+.-]*:\/\/)/i;
@@ -58,7 +83,7 @@ const pathLike = (piece) =>
 
 /** The same for a launch argument or a server's command and URL: a long run is looked for between path separators. */
 export const secretArgument = (value) =>
-  JWT_SHAPE.test(value) || SECRET_VALUE.test(value) || BEARER_INSIDE.test(value) ||
+  hasJwt(value) || SECRET_VALUE.test(value) || BEARER_INSIDE.test(value) ||
   value.split(/[\s=]/).some((piece) => (pathLike(piece) ? piece.split(/[\\/]/).some((part) => longSecret(part)) : longSecret(piece)));
 
 const decodeKeepingPlus = (raw) => { try { return decodeURIComponent(raw); } catch { return raw; } };
@@ -99,12 +124,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)));
@@ -122,7 +160,8 @@ export function repositoryPassword(value) {
 
 // A repository's parameters, read as fabric_secrets.secret_url reads them, by hand: `new URL`
 // refuses a host it cannot parse and a special scheme written without `//` (`https:host/r?access_token=...`), where
-// the Python twin still reads them (0.62.0 readings 8 and 9, FAA-200 (17)).
+// the Python twin's repository_credential reads them too (0.62.0 readings 8 and 9, FAA-200 (17)); its secret_url, like
+// secretUrl, refuses such a URL since FAA-309.
 function repositoryParts(head, tail) {
   const text = tail.replace(/[\x00-\x20]+$/, '').replace(/[\t\n\r]/g, '');
   const hash = text.indexOf('#');

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

@@ -52,8 +52,11 @@ export {
   LOCK_WAIT_SUPERVISED_SECONDS,
   LOCK_BACKOFF_FIRST_SECONDS,
   LOCK_BACKOFF_MAX_SECONDS,
+  LOCK_WATCH_SECONDS,
   AlreadyRunning,
   InstanceLock,
+  lostLockMessage,
+  stopLostHolder,
   lockName,
   SUPERVISORS,
   SUPERVISOR_ARG,

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

@@ -0,0 +1,180 @@
+// 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

@@ -9,7 +9,7 @@ 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 http from 'node:http';
 import net from 'node:net';
@@ -60,7 +60,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);
@@ -609,16 +609,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) {