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

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

@@ -38,13 +38,42 @@ 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_-]*/;
-/** A value that says it is a credential, or a provider key's shape. */
-export const SECRET_VALUE = /(^bearer\s.+|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,})/i;
+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,
+ * within 256 characters (the contract's SECRET_VALUE at the pin, DEC-0151). A match includes its boundary character:
+ * callers test, never read the matched text or its index. */
+export const SECRET_VALUE = /(^[Bb][Ee][Aa][Rr][Ee][Rr]\s.+|(?:^|[^A-Za-z0-9]|%[0-9A-Fa-f]{2}|\\[nrt"']|\\u[0-9A-Fa-f]{4}|\\x[0-9A-Fa-f]{2}|\\[bfv0ae]|\\[0-7]{1,3}|%25[0-9A-Fa-f]{2}|\x1b\[[0-9;:]*m|(?:\\u001[bB]|\\x1[bB]|\\e|\\033|\\33)\[[0-9;:]*m)(?:sk-(?=[A-Za-z0-9_-]{0,255}?\d)(?:(?=[A-Za-z0-9_-]{0,255}?[A-Z])[A-Za-z0-9_-]{16,}|[A-Za-z0-9_-]{32,})|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 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;
@@ -54,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; } };
@@ -91,7 +120,10 @@ export function secretUrl(value) {
 const REPOSITORY_URI = /^([A-Za-z][A-Za-z0-9+.-]*:(?:\/\/[^/?#]*)?)([^?#]*)([\s\S]*)$/;
 const REPOSITORY_NAME = /^(?:[a-z0-9._-]+|[A-Za-z._-]+)$/; // lower case, or letters with no digit (readings 8)
 const REPOSITORY_AUTHORITY = /^[A-Za-z][A-Za-z0-9+.-]*:\/\//;
-const KEY_AT_A_WORD = new RegExp(`(?:^|(?<=[._-]))(?:${SECRET_VALUE.source})`, 'i');
+// A repository name's own key shapes, boundary-free and case-sensitive (DEC-0151): SECRET_VALUE takes a consuming
+// 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}`);
 const SPECIAL_QUERY = /^(?:https?|wss?|ftp|file):/i; // whose query also encodes `'`, as the URL standard does
 
@@ -115,7 +147,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,
@@ -107,6 +110,10 @@ export {
   STATUSES,
   PLACEMENTS,
   MANAGERS,
+  PEER_CHECKS,
+  connectionRefusal,
+  connectionOwner,
+  loopbackServer,
   descriptorPath,
   readDescriptors,
   validateDescriptor,
@@ -185,6 +192,7 @@ export {
   taskUninstall,
   launchdPlist,
   SYSTEM_DAEMONS,
+  USER_NAME_RULE,
   launchdDomain,
   wellKnownOf,
   jobWellKnownOf,

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

@@ -343,6 +343,8 @@ function guiDomain(platform, uid) {
 /** Where a LaunchDaemon's plist lives: a job in launchd's system domain, started at boot with no GUI login (FAA-278). */
 export const SYSTEM_DAEMONS = '/Library/LaunchDaemons';
 const USER_NAME = /^[a-z_][a-z0-9_.-]{0,31}$/;
+/** The short-name rule in words, printed alike by both twins (FAA-286 item 13). */
+export const USER_NAME_RULE = 'a lower-case letter or _, then up to 31 lower-case letters, digits, _, . or -';
 
 /**
  * The launchd domain a job lives in: `system` for a LaunchDaemon (`domain: 'system'`, or a plist in
@@ -351,6 +353,9 @@ const USER_NAME = /^[a-z_][a-z0-9_.-]{0,31}$/;
  */
 export function launchdDomain(plistPath = null, { domain = null, platform = process.platform, uid } = {}) {
   if (![null, undefined, 'gui', 'system'].includes(domain)) throw new ServiceError('domain must be gui or system');
+  if (plistPath !== null && plistPath !== undefined && /^(?:system|gui)(?:\/[0-9]*)?$/.test(String(plistPath))) {
+    throw new ServiceError(`${plistPath} is a launchd domain, not a plist path: pass { domain: '${String(plistPath) === 'system' ? 'system' : 'gui'}' } (FAA-286)`);
+  }
   let which = domain;
   if ((which === null || which === undefined) && plistPath !== null && plistPath !== undefined) {
     const paths = platform === 'darwin' ? path.posix : path; // a macOS path, whatever host reads it
@@ -363,6 +368,34 @@ export function launchdDomain(plistPath = null, { domain = null, platform = proc
   return guiDomain(platform, uid);
 }
 
+// A domain the plist's folder contradicts (FAA-286 items 14 and 21): a system job in a LaunchAgents folder (launchd also
+// loads it into gui/<uid> at login), or a gui job in /Library/LaunchDaemons (launchd loads it at boot as root). Another
+// folder is allowed for a system job, as the tests' and a staging install's are.
+function pairProblem(plistPath, domain, platform) {
+  const paths = platform === 'darwin' ? path.posix : path;
+  const folder = paths.dirname(paths.resolve(String(plistPath)));
+  const parts = String(plistPath).split(/[\\/]+/); // the folder's own name, whatever separator a test's host path uses
+  if (domain === 'system' && String(parts[parts.length - 2] ?? '').toLowerCase() === 'launchagents') {
+    return `A LaunchDaemon's plist lives in ${SYSTEM_DAEMONS}: ${plistPath} is in a LaunchAgents folder, which launchd also loads into gui/<uid> at login, so the job would run twice.`;
+  }
+  if (domain === 'gui' && folder.toLowerCase() === SYSTEM_DAEMONS.toLowerCase()) {
+    return `${plistPath} is in ${SYSTEM_DAEMONS}, which launchd loads at boot as a LaunchDaemon: a gui/<uid> job's plist goes in ~/Library/LaunchAgents.`;
+  }
+  return null;
+}
+
+// A LaunchAgent of `label` in `userName`'s ~/Library/LaunchAgents, which would run a second copy at its login (FAA-286
+// item 6); null when there is none or the home cannot be read.
+function leftoverAgent(label, userName, run) {
+  const read = run(['dscl', '.', '-read', `/Users/${userName}`, 'NFSHomeDirectory']);
+  const home = read?.status === 0 ? /NFSHomeDirectory:\s*(\S.*?)\s*$/m.exec(String(read.stdout ?? ''))?.[1] : null;
+  if (!home) return null;
+  const folder = path.join(home, 'Library', 'LaunchAgents');
+  let names = [];
+  try { names = fs.readdirSync(folder).filter((n) => n.endsWith('.plist')).sort(); } catch { return null; }
+  return names.map((n) => path.join(folder, n)).find((file) => topKey(plistXml(file, run), 'Label') === label) ?? null;
+}
+
 // A system-domain job is installed and removed by root: refuse before anything is written (FAA-278).
 function needRoot(domain, label, plistPath, install, euid) {
   if (domain !== 'system' || euid === 0) return;
@@ -390,6 +423,9 @@ function decodeXml(text) {
 function topStrings(text) {
   const token = /<!--[\s\S]*?-->|<\?[\s\S]*?\?>|<!DOCTYPE[^>]*>|<!\[CDATA\[([\s\S]*?)\]\]>|<(\/?)([A-Za-z][\w.:-]*)\s*[^>]*?(\/?)>|([^<]+)/g;
   const values = Object.create(null);
+  // The open containers: only the root dict's own keys are read (FAA-286 item 10: a root <array> holding a
+  // <key>UserName</key> is no dict, as plistlib reads it).
+  const open = [];
   let depth = 0;
   let key = null;
   let capture = null;
@@ -398,17 +434,21 @@ function topStrings(text) {
     for (let m = token.exec(String(text ?? '')); m; m = token.exec(String(text ?? ''))) {
       const [, cdata, closing, name, selfClosing, chars] = m;
       if (cdata !== undefined || chars !== undefined) {
-        if (capture) buffer += cdata !== undefined ? cdata : decodeXml(chars);
+        // every character reference, at any depth and in any value, is checked as expat checks it (FAA-286 item 10)
+        const decoded = chars !== undefined ? decodeXml(chars) : cdata;
+        if (capture) buffer += decoded;
       } else if (name === 'dict' || name === 'array') {
         if (selfClosing) {
           if (depth === 1 && key !== null) { delete values[key]; key = null; }
         } else if (closing) {
           depth -= 1;
+          open.pop();
         } else {
           if (depth === 1 && key !== null) { delete values[key]; key = null; } // a container is this key's value
           depth += 1;
+          open.push(name);
         }
-      } else if (name && depth === 1) {
+      } else if (name && depth === 1 && open[0] === 'dict') {
         if (selfClosing) {
           if (key !== null) {
             if (name === 'string') values[key] = '';
@@ -431,6 +471,7 @@ function topStrings(text) {
   } catch {
     return null;
   }
+  if (key !== null || capture !== null || depth !== 0) return null; // a dangling <key> or an open element: unreadable
   return values;
 }
 
@@ -569,8 +610,8 @@ 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) {
-  if (process.platform !== 'darwin' || !Number.isInteger(pid) || pid <= 1) return false;
+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
@@ -600,7 +641,11 @@ class JobAgent extends http.Agent {
     this.ask = ask;
   }
 
-  createConnection(options, callback) {
+  createConnection(options, given) {
+    // One answer per connection (FAA-286 item 12): an error during the async owner, lsof and ps checks would reach the
+    // callback a second time, as CheckedAgent's checkedSocket guards it.
+    let answered = false;
+    const callback = (err, socket) => { if (!answered) { answered = true; given(err, socket); } };
     const port = Number(options.port);
     const socket = net.connect({ host: '127.0.0.1', port, noDelay: true });
     const timer = setTimeout(() => socket.destroy(Object.assign(new Error('connect timeout'), { code: 'ETIMEDOUT' })), options.timeout ?? 10000);
@@ -614,14 +659,14 @@ class JobAgent extends http.Agent {
       } catch (err) {
         who = { kind: UNKNOWN, uid: null, pid: null, reason: `check: ${err?.name ?? 'Error'}` };
       }
-      if (who.pid === this.jobPid && !await jobListens(this.jobPid, port, this.ask.run)) {
+      if (who.pid === this.jobPid && !await jobListens(this.jobPid, port, this.ask.run, this.ask.platform)) {
         socket.destroy();
         // The job's pid, but lsof did not show it bound to exactly 127.0.0.1:<port>: a wildcard is never vouched for.
         callback(new ListenerRefused(SERVER_NOT_OWN, `the LaunchDaemon's pid ${this.jobPid} is not shown listening on exactly 127.0.0.1:${port} by lsof (a wildcard is never vouched for); nothing was sent`));
         return;
       }
       const proved = who.pid === this.jobPid || (who.kind === UNKNOWN && String(who.reason ?? '').startsWith(TABLE_RESTRICTED)
-        && await jobListens(this.jobPid, port, this.ask.run));
+        && await jobListens(this.jobPid, port, this.ask.run, this.ask.platform));
       if (!proved) {
         socket.destroy();
         callback(new ListenerRefused(SERVER_NOT_OWN, `the server on port ${port} is not the LaunchDaemon's pid ${this.jobPid} (${who.reason ?? who.kind}): another process holds the port, or the job's program starts the server as a child (start it with exec); nothing was sent`, who));
@@ -649,11 +694,11 @@ function loopbackPort(origin) {
 }
 
 // As wellKnownOf, for a LaunchDaemon: a loopback origin is read only when launchd's job `jobPid`, running as `jobUid`,
-// accepted the connection.
-export async function jobWellKnownOf(origin, { jobPid, jobUid } = {}) {
+// accepted the connection. `ask` reaches the owner, lsof and ps readers (a test's fakes; `platform` for lsof's).
+export async function jobWellKnownOf(origin, { jobPid, jobUid, ask = {} } = {}) {
   const port = loopbackPort(origin);
   if (port === null) throw new ServiceError(`A LaunchDaemon's answer is read only at http://127.0.0.1:<port>, where its job's pid and uid prove it; ${origin} is not.`);
-  return loopbackWellKnown(port, new JobAgent({ keepAlive: false, jobPid, jobUid }));
+  return loopbackWellKnown(port, new JobAgent({ keepAlive: false, jobPid, jobUid, ask }));
 }
 
 /**
@@ -672,9 +717,15 @@ export async function jobWellKnownOf(origin, { jobPid, jobUid } = {}) {
 export async function launchdInstall(label, plistPath, plistText, { origin, serviceId, instance = 'default', timeout = 40, forceEnable = false,
   run = defaultRun, platform = process.platform, uid, domain = null, euid = ownEuid(), fetchWellKnown = wellKnownOf,
   fetchJobWellKnown = jobWellKnownOf, sleep = pause } = {}) {
+  const pair = pairProblem(plistPath, domain, platform);
+  if (pair) throw new ServiceError(pair);
   const dom = launchdDomain(plistPath, { domain, platform, uid });
   launchdLabel(label);
   if (!origin || !serviceId) throw new ServiceError('launchdInstall needs the origin and the service id it waits to see answer.');
+  if (/^bplist/.test(Buffer.isBuffer(plistText) ? plistText.toString('latin1', 0, 6) : String(plistText ?? '').slice(0, 6))) {
+    // named as what it is, never as a missing UserName (FAA-286 item 7): the text launchdPlist writes is XML
+    throw new ServiceError('The plist is a binary plist: pass the XML text launchdPlist writes (plutil -convert xml1 converts one).');
+  }
   needRoot(dom, label, plistPath, true, euid);
   if (dom === 'system' && loopbackPort(origin) === null) {
     throw new ServiceError(`A LaunchDaemon's origin is http://127.0.0.1:<port>: only there is its answer proved by the job's pid and uid (FAA-278); ${origin} is not.`);
@@ -693,7 +744,7 @@ export async function launchdInstall(label, plistPath, plistText, { origin, serv
     }
   }
   if (dom === 'system' && named && !USER_NAME.test(named)) {
-    throw new ServiceError(`UserName ${named} is not a macOS short name (${USER_NAME.source}): launchd takes the account's short name.`);
+    throw new ServiceError(`UserName ${named} is not a macOS short name (${USER_NAME_RULE}): launchd takes the account's short name.`);
   }
   const jobUid = named ? accountUid(named, run) : null;
   if (dom === 'system' && named && jobUid === null) {
@@ -705,7 +756,12 @@ export async function launchdInstall(label, plistPath, plistText, { origin, serv
   if (dom === 'system' && !named) {
     throw new ServiceError("A LaunchDaemon needs UserName: without it the job runs as root, keeps its data in root's home, and every client refuses root's listener (DEC-0154 HA-2). Write the plist with launchdPlist(..., { userName: <the account whose Fabric and agents call it> }).");
   }
+  if (dom === 'system') {
+    const leftover = leftoverAgent(label, named, run);
+    if (leftover) throw new ServiceError(`${leftover} is a LaunchAgent of label ${label}: it would start a second copy at ${named}'s login beside this LaunchDaemon. Remove it first (launchdUninstall as ${named}; lifecycle reference, The system domain).`);
+  }
   const opts = { run, platform, uid, domain: dom === 'system' ? 'system' : null };
+  const existed = fs.existsSync(plistPath);
   atomicWrite(plistPath, plistText, 0o644);
   const lint = run(['plutil', '-lint', String(plistPath)]);
   if (lint?.status !== 0) throw new ServiceError(`plist failed plutil -lint: ${String(lint?.stdout || lint?.stderr || '').trim().slice(0, 200)}`);
@@ -725,6 +781,11 @@ export async function launchdInstall(label, plistPath, plistText, { origin, serv
       if (dom !== 'system' && /:\s*125:|Domain does not support|Could not find domain/.test(last)) {
         throw new ServiceError(`launchctl bootstrap failed: ${last.slice(0, 200)}. This user has no GUI login session (an SSH session, or a headless Mac after a FileVault restart), so ${dom} does not run jobs: remove the LaunchAgent this attempt wrote (launchdUninstall), then install it as a LaunchDaemon in the system domain (a plist in ${SYSTEM_DAEMONS} with UserName, as root; FAA-278).`);
       }
+      if (dom === 'system') {
+        // a plist left in /Library/LaunchDaemons loads at the next boot (FAA-286 item 15): one this call wrote goes
+        if (!existed) { try { fs.unlinkSync(plistPath); } catch { /* named below */ } }
+        throw new ServiceError(`launchctl bootstrap failed: ${last.slice(0, 200)}; ${fs.existsSync(plistPath) ? `${plistPath} stays and loads at the next boot: remove it as root` : 'the plist this call wrote was removed'}`);
+      }
       throw new ServiceError(`launchctl bootstrap failed: ${last.slice(0, 200)}`);
     }
     await sleep(1000);
@@ -780,6 +841,10 @@ export async function launchdUninstall(label, plistPath, { timeout = 30, purge =
   needRoot(dom, label, plistPath, false, euid);
   if (purge && dom === 'system') throw new ServiceError("A LaunchDaemon's data belongs to its UserName, not to root: uninstall without purge, then remove the data as that user.");
   if (dom === 'system') refuseHeldLabel(label, plistPath, run); // a bootout would stop another plist's job (FAA-278)
+  const holds = fs.existsSync(plistPath) ? topKey(plistXml(plistPath, run), 'Label') : null;
+  if (holds !== null && holds !== label) { // FAA-286 item 9: booting out one job and unlinking another's plist
+    throw new ServiceError(`${plistPath} holds launchd label ${holds}, not ${label}: nothing was removed. Name the plist of ${label}, or uninstall ${holds} with its own label.`);
+  }
   const dirs = purge ? instanceDirs(serviceId, instance, platform) : {}; // one instance's folders only (FAA-125)
   const opts = { run, platform, uid, domain: dom === 'system' ? 'system' : null };
   const target = `${dom}/${label}`;

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

@@ -4,10 +4,7 @@
 `degraded[]`. Part of the service kit (FAA-62, layer L3). Standard library only."""
 from __future__ import annotations
 
-import bisect
-import ipaddress
 import re
-import unicodedata
 import urllib.parse
 from typing import Any, Dict, Iterable, List, Mapping, Optional, Sequence
 
@@ -18,7 +15,12 @@ if str(_Path(__file__).resolve().parent) not in _sys.path:  # the kit loads from
 
 from fabric_base import ServiceError  # noqa: E402
 from fabric_secrets import (  # noqa: E402
-    JWT_SHAPE, _BEARER_INSIDE as _BEARER, _long_secret, credential_name, raw_values, secret_argument, secret_value,
+    _BEARER_INSIDE as _BEARER, _long_secret, credential_name, has_jwt, raw_values, secret_argument, secret_value,
+)
+# The WHATWG host reading and its IDNA tables (FAA-98) live in fabric_secrets since FAA-309, where secret_url reads a
+# URL's host with them; the names stay here for code and tests that reached them.
+from fabric_secrets import (  # noqa: E402,F401
+    _FORBIDDEN_DOMAIN, _FORBIDDEN_HOST, _IDNA_DISALLOWED, _IDNA_IGNORED, _domain_ok, _idna_host, _ipv4_number, _ipv6_ok,
 )
 
 CONNECTIONS_EXTENSION_KEY = "https://fabric.passioncode.ai/agent-contract/extensions/connections/0.1"
@@ -171,153 +173,6 @@ _credential_name, _secret_value, _secret_argument = credential_name, secret_valu
 
 
 _SPECIAL = ("http", "https", "ws", "wss", "ftp", "file")
-_FORBIDDEN_HOST = set("\x00\t\n\r #/:<>?@[\\]^|")
-_FORBIDDEN_DOMAIN = _FORBIDDEN_HOST | set(chr(c) for c in range(0x20)) | {"%", "\x7f"}
-
-
-# FAA-98: UTS46 narrowed, not ported. A non-ASCII host is refused only where every Node from 20 to 26 refuses it, so
-# the doubt stays on the closed side (its URL's credentials are read). The two tables are measured by
-# test/fixtures/idna/make_idna_tables.mjs (idna-tables.json, held equal by test_the_idna_tables_are_the_measured_ones):
-# code points refused in every context, and code points removed between letters. The contextual rules read Unicode 3.2
-# classes (`unicodedata.ucd_3_2_0`) and skip what that Unicode does not know, since Node's own UTS46 data lags its
-# Unicode: an Arabic letter of Unicode 14 is no right-to-left letter to it.
-_IDNA_DISALLOWED = (
-    (0x80, 0xa0), (0xa8, 0xa8), (0xaf, 0xaf), (0xb4, 0xb4), (0xb8, 0xb8), (0x2d8, 0x2dd), (0x37a, 0x37a),
-    (0x384, 0x385), (0x600, 0x605), (0x61c, 0x61c), (0x6dd, 0x6dd), (0x70f, 0x70f), (0x890, 0x891), (0x8e2, 0x8e2),
-    (0x1680, 0x1680), (0x1fbd, 0x1fbd), (0x1fbf, 0x1fc1), (0x1fcd, 0x1fcf), (0x1fdd, 0x1fdf), (0x1fed, 0x1fee),
-    (0x1ffd, 0x1ffe), (0x2000, 0x200a), (0x200e, 0x200f), (0x2017, 0x2017), (0x2024, 0x2026), (0x2028, 0x202f),
-    (0x203e, 0x203e), (0x2047, 0x2049), (0x205f, 0x205f), (0x2066, 0x2069), (0x2100, 0x2101), (0x2105, 0x2106),
-    (0x2488, 0x249b), (0x2a74, 0x2a74), (0x2ff0, 0x3000), (0x309b, 0x309c), (0x31ef, 0x31ef), (0x33c2, 0x33c2),
-    (0x33c7, 0x33c7), (0x33d8, 0x33d8), (0xe000, 0xf8ff), (0xfc5e, 0xfc63), (0xfdfa, 0xfdfb), (0xfe12, 0xfe13),
-    (0xfe16, 0xfe16), (0xfe19, 0xfe19), (0xfe30, 0xfe30), (0xfe47, 0xfe4c), (0xfe52, 0xfe52), (0xfe55, 0xfe56),
-    (0xfe5f, 0xfe5f), (0xfe64, 0xfe65), (0xfe68, 0xfe68), (0xfe6a, 0xfe6b), (0xfe70, 0xfe70), (0xfe72, 0xfe72),
-    (0xfe74, 0xfe74), (0xfe76, 0xfe76), (0xfe78, 0xfe78), (0xfe7a, 0xfe7a), (0xfe7c, 0xfe7c), (0xfe7e, 0xfe7e),
-    (0xff03, 0xff03), (0xff05, 0xff05), (0xff0f, 0xff0f), (0xff1a, 0xff1a), (0xff1c, 0xff1c), (0xff1e, 0xff20),
-    (0xff3b, 0xff3e), (0xff5c, 0xff5c), (0xffe3, 0xffe3), (0xfff9, 0xfffd), (0x110bd, 0x110bd), (0x110cd, 0x110cd),
-    (0x13430, 0x1343f), (0x1f100, 0x1f100), (0xe0001, 0xe0001), (0xe0020, 0xe007f), (0xf0000, 0xffffd),
-    (0x100000, 0x10fffd),
-)
-_IDNA_IGNORED = (
-    (0xad, 0xad), (0x34f, 0x34f), (0x180b, 0x180d), (0x180f, 0x180f), (0x200b, 0x200b), (0x2060, 0x2060),
-    (0x2064, 0x2064), (0xfe00, 0xfe0f), (0xfeff, 0xfeff), (0x1bca0, 0x1bca3), (0xe0100, 0xe01ef),
-)
-_IDNA_DOTS = re.compile("[.\u3002\uff0e\uff61]")
-_U32 = unicodedata.ucd_3_2_0
-_RTL_OK = {"R", "AL", "AN", "EN", "ES", "CS", "ET", "ON", "BN", "NSM"}
-_JOINERS = "\u200c\u200d"
-
-
-def _in_ranges(ranges: Sequence[tuple], cp: int) -> bool:
-    i = bisect.bisect_right(ranges, (cp, 0x10ffff)) - 1
-    return i >= 0 and ranges[i][0] <= cp <= ranges[i][1]
-
-
-def _known(c: str) -> bool:
-    return _U32.category(c) != "Cn" and unicodedata.category(c) != "Cn"
-
-
-def _joiner_refused(label: str, i: int) -> bool:
-    """CheckJoiners as Node 20 to 26 all read it: they find a joining context, or a virama, anywhere in the label
-    (`\u0628a\u200c\u0627` and `\u0628\u200c\u0627\u200d` parse), so only a joiner with nothing but ASCII beside it
-    in its label has none for certain."""
-    return all(c.isascii() for j, c in enumerate(label) if j != i)
-
-
-def _bidi_refused(label: str) -> bool:
-    """RFC 5893 as Node 20 to 26 all read it: only a label holding R, AL or AN is judged, and its first code point is
-    not (Node 26 alone refuses a label opening with a digit or a hyphen)."""
-    if not label or not all(_known(c) for c in label) or any(c in _JOINERS for c in label):
-        return False  # Node 20 to 26 pass a label holding a joiner over (`\u05d0a\u094d\u200d` parses)
-    k = [_U32.bidirectional(c) for c in label]
-    if not any(x in ("R", "AL", "AN") for x in k):
-        return False
-    body = list(k)
-    while body and body[-1] == "NSM":
-        body.pop()
-    if not body or body[-1] not in ("R", "AL", "EN", "AN"):
-        return True
-    return k[0] in ("R", "AL") and (any(x not in _RTL_OK for x in k) or ("EN" in k and "AN" in k))
-
-
-def _idna_host(host: str) -> Optional[str]:
-    """None where WHATWG's domain-to-ASCII refuses a non-ASCII host for certain; else the host as UTS46 maps it, read
-    as NFKC with case folding (exact enough for the ASCII rules that follow, which read digits and dots)."""
-    if any(_in_ranges(_IDNA_DISALLOWED, ord(c)) for c in host):
-        return None
-    kept = "".join(c for c in host if not _in_ranges(_IDNA_IGNORED, ord(c)))
-    if kept == "":
-        return None  # nothing left: an empty host
-    if not all(_known(c) for c in kept):
-        return host  # a code point this Python's Unicode does not know: the contextual rules are not read
-    mapped = unicodedata.normalize("NFC", unicodedata.normalize("NFKC", unicodedata.normalize("NFKC", kept).casefold()))
-    for label in _IDNA_DOTS.split(mapped):
-        first = label[:1]
-        if first and first not in "\u17b4\u17b5" and _U32.category(first)[0] == "M" and unicodedata.category(first)[0] == "M":
-            return None  # a label opening with a mark (U+17B4 and U+17B5 are ignored by the newer Nodes)
-        if any(c in _JOINERS and _joiner_refused(label, i) for i, c in enumerate(label)):
-            return None
-        if _bidi_refused(label):
-            return None
-    return _IDNA_DOTS.sub(".", mapped)
-
-
-def _ipv4_number(part: str) -> Optional[int]:
-    if part == "":
-        return None  # an empty part fails WHATWG's IPv4 parser (`1..2`); `0x` alone is 0
-    base = 10
-    if part[:2].lower() == "0x":
-        part, base = part[2:], 16
-    elif len(part) > 1 and part[0] == "0":
-        part, base = part[1:], 8
-    if part == "":
-        return 0
-    digits = {10: "0123456789", 16: "0123456789abcdefABCDEF", 8: "01234567"}[base]
-    return int(part, base) if all(c in digits for c in part) else None
-
-
-def _domain_ok(host: str) -> bool:
-    """The WHATWG host parser on a special scheme's host, enough to know when `new URL` refuses it."""
-    if host.startswith("["):
-        return host.endswith("]") and _ipv6_ok(host[1:-1])
-    if re.search(r"%(?![0-9A-Fa-f]{2})", host) is None:
-        try:
-            host = urllib.parse.unquote_to_bytes(host).decode("utf-8")
-        except UnicodeDecodeError:
-            return False
-    if any(c in _FORBIDDEN_DOMAIN for c in host):
-        return False
-    # A non-ASCII host goes through UTS46 in WHATWG; this module reads it narrowly (_idna_host, FAA-98). When unsure,
-    # the host is taken as valid, so its URL's credentials are read: the doubt then hides a list rather than publish one
-    # (round-2 reading). A host UTS46 maps to ASCII is read by the ASCII rules below (`１２７.０.０.１` is an address).
-    if any(ord(c) > 0x7f for c in host):
-        mapped = _idna_host(host)
-        if mapped is None:
-            return False
-        if not mapped.isascii() or any(c in _FORBIDDEN_DOMAIN for c in mapped):
-            return True
-        host = mapped
-    labels = host.split(".")
-    if labels and labels[-1] == "" and len(labels) > 1:
-        labels = labels[:-1]
-    last = labels[-1] if labels else ""
-    if not (last and (last.isdigit() and last.isascii() or re.fullmatch(r"0[xX][0-9A-Fa-f]*", last))):
-        return host != ""
-    numbers = [_ipv4_number(label) for label in labels]
-    if len(numbers) > 4 or any(n is None for n in numbers):
-        return False
-    return all(n <= 255 for n in numbers[:-1]) and numbers[-1] < 256 ** (5 - len(numbers))
-
-
-def _ipv6_ok(text: str) -> bool:
-    if "%" in text:
-        return False  # a zone id: `ipaddress` takes one, WHATWG does not
-    try:
-        ipaddress.IPv6Address(text)
-        return True
-    except ValueError:
-        return False
-
-
 _SURROGATE = re.compile("[\ud800-\udfff]")
 _QUERY_ENCODE = set(chr(c) for c in range(0x21)) | set('"#<>')
 _FRAGMENT_ENCODE = set(chr(c) for c in range(0x21)) | set('"<>`')
@@ -388,7 +243,7 @@ def _whatwg_parts(value: str) -> Optional[Dict[str, str]]:
             return None
     elif any(c in _FORBIDDEN_HOST for c in host):
         return None
-    elif host == "" and ("@" in authority or port):
+    elif host == "" and ("@" in authority or ":" in hostport):
         return None
     return {"password": password, "query": query, "fragment": fragment}
 
@@ -424,7 +279,7 @@ def _secret_url(value: str) -> bool:
 
 
 def _credential(value: str, runs: bool) -> bool:
-    return bool(JWT_SHAPE.search(value) or _KEY_SHAPE.search(value) or _BEARER.search(value)
+    return bool(has_jwt(value) or _KEY_SHAPE.search(value) or _BEARER.search(value)  # has_jwt: one pass (FAA-313)
                 or (runs and _long_run(value)) or any(_secret_url(url) for url in _urls_in(value)))
 
 

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

@@ -5,12 +5,14 @@ from __future__ import annotations
 
 import hashlib
 import http.server
+import ipaddress
 import json
 import os
 import re
 import socket
 import socketserver
 import subprocess
+import threading
 import warnings
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Sequence, Tuple
@@ -53,7 +55,7 @@ from fabric_usage import (
 DASHBOARD_EXTENSION_KEY = "https://fabric.passioncode.ai/agent-contract/extensions/dashboard/0.1"
 
 
-DASHBOARD_KIT = "fabric-dashboard-kit@1.1.6"
+DASHBOARD_KIT = "fabric-dashboard-kit@1.1.7"
 
 
 REFERENCE_THEMES = ("graphite", "fabric", "paper", "forest", "ocean", "ember", "contrast")
@@ -88,19 +90,101 @@ _NOT_LAUNCHD = ("systemd", "task-scheduler", "node", "person")
 _AUTH_HEADER = re.compile(r"[A-Za-z][A-Za-z0-9-]{0,63}")
 
 
+#: How a loopback server treats the OS account of the process that connected (DEC-0154 HA-2's server side, HA-3;
+#: FAA-227): `refuse` (the default) closes a connection whose peer is another OS account's before reading a byte of
+#: it and serves the rest, labelled; `strict` also refuses a peer whose owner cannot be told and a system account
+#: other than root (uid 0, which can read every account's files and installs a LaunchDaemon); `off` reads no table.
+PEER_CHECKS = ("refuse", "strict", "off")
+
+
+def connection_refusal(owner: Any, mode: str = "refuse") -> Optional[str]:
+    """Why a server refuses the peer `owner` (a fabric_peer_owner.Owner) under `mode`, or None to serve it. The reason
+    is the owner's kind, or for `unknown` its reason; it names no address and nothing the peer sent."""
+    if mode not in PEER_CHECKS:
+        raise ValueError("peer_check must be one of %s" % ", ".join(PEER_CHECKS))
+    if mode == "off" or owner is None:
+        return None
+    kind = getattr(owner, "kind", fabric_peer_owner.UNKNOWN)
+    if kind == fabric_peer_owner.ANOTHER_ACCOUNT:
+        return kind
+    if mode == "strict" and kind != fabric_peer_owner.THIS_ACCOUNT:
+        if kind == fabric_peer_owner.SYSTEM and getattr(owner, "uid", None) == 0:
+            return None
+        return getattr(owner, "reason", None) or kind
+    return None
+
+
+def is_loopback_peer(client_address: Any) -> bool:
+    """Whether an accepted connection's peer address is a loopback one (127.0.0.0/8, ::1, or either IPv4-mapped): the
+    only peers whose owner can be another account of this computer (DEC-0154 HA-2). An address that cannot be read
+    counts as loopback, so its owner is still read from the table."""
+    try:
+        return ipaddress.ip_address(fabric_peer_owner.norm_host(str(client_address[0]))).is_loopback
+    except Exception:
+        return True
+
+
 class LoopbackHTTPServer(http.server.ThreadingHTTPServer):
     """ThreadingHTTPServer for a loopback service: threads are daemons, and the bind asks
     no resolver. HTTPServer.server_bind() calls socket.getfqdn() between bind() and listen();
     on a Mac with a slow resolver the port then stays bound but silent, so a host sees
-    neither an answer nor a refusal."""
+    neither an answer nor a refusal.
+
+    Each accepted connection's peer is told from the computer's socket table (`fabric_peer_owner.peer`) in the
+    connection's own thread, before the handler reads a byte (DEC-0154 HA-2's server side, FAA-227). `peer_check`
+    (`PEER_CHECKS`) decides which owners are closed unread; a served handler finds its peer's owner with
+    `self.server.peer_owner()`. A refusal writes one line to stderr with the owner's kind, uid and pid and nothing the
+    peer sent (`peer_refused`), and counts in `peer_refusals`. The check applies to loopback peers only: a peer at
+    another address (a service bound to 0.0.0.0) is no local account, so its table is not read and it is served under
+    `refuse` and `strict` alike, with `peer_owner()` None."""
 
     daemon_threads = True
+    peer_check = "refuse"
+    #: The reader of an accepted socket's peer; a test replaces it.
+    peer_reader = staticmethod(lambda sock: fabric_peer_owner.peer(sock))
+
+    def __init__(self, server_address: Any, handler: Any, bind_and_activate: bool = True, *,
+                 peer_check: Optional[str] = None) -> None:
+        mode = self.peer_check if peer_check is None else peer_check
+        connection_refusal(None, mode)  # refuses an unknown mode before the port is bound
+        self.peer_check = mode
+        self.peer_refusals = 0
+        self._peer = threading.local()
+        super().__init__(server_address, handler, bind_and_activate)
 
     def server_bind(self) -> None:
         socketserver.TCPServer.server_bind(self)
         host, port = self.server_address[:2]
         self.server_name, self.server_port = host, port
 
+    def peer_owner(self) -> Any:
+        """The owner of the peer this thread's handler serves (None under `peer_check="off"`)."""
+        return getattr(self._peer, "owner", None)
+
+    def finish_request(self, request: Any, client_address: Any) -> None:
+        owner = None
+        if self.peer_check != "off" and is_loopback_peer(client_address):
+            try:
+                owner = self.peer_reader(request)
+            except Exception as exc:  # a reader that fails is an owner nobody can tell, never a crash of the server
+                owner = fabric_peer_owner.Owner(fabric_peer_owner.UNKNOWN, None, None, "none",
+                                                "reader: %s" % type(exc).__name__)
+        reason = connection_refusal(owner, self.peer_check)
+        if reason is not None:
+            self.peer_refusals += 1
+            self.peer_refused(owner, reason)
+            return  # process_request_thread closes the socket unread (shutdown_request)
+        self._peer.owner = owner
+        try:
+            super().finish_request(request, client_address)
+        finally:
+            self._peer.owner = None
+
+    def peer_refused(self, owner: Any, reason: str) -> None:
+        """One line on stderr per refused connection; override to log it elsewhere. Never the peer's bytes."""
+        _sys.stderr.write("fabric: refused a loopback peer (%s, uid %s, pid %s) before reading it (DEC-0154)\n"
+                          % (reason, getattr(owner, "uid", None), getattr(owner, "pid", None)))
+
 
 def descriptor_path(service_id: str, instance: str = "default", directory: Optional[Path] = None) -> Path:
     return (directory or services_dir()) / ("%s.%s.json" % (service_id, instance))