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

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

@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+# 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. Standard library
@@ -31,7 +32,7 @@ CREDENTIAL_PAIRS: Dict[str, tuple] = {
 }
 #: ECMAScript's \s, as a character class body.
 JS_SPACE = "\t\n\x0b\x0c\r \xa0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff"
-_NOT_LINE_END = "[^\n\r\u2028\u2029]"  # ECMAScript's `.` without the s flag
+NOT_LINE_END = "[^\n\r\u2028\u2029]"  # ECMAScript's `.` without the s flag
 JWT_SHAPE = re.compile(r"eyJ[A-Za-z0-9_-]{2,}\.[A-Za-z0-9_-]{2,}\.[A-Za-z0-9_-]*")
 _URL_BASE64_RUN = re.compile(r"[A-Za-z0-9_-]*")
 
@@ -74,14 +75,17 @@ _PROVIDER_KEYS = (r"(?:sk-(?=[A-Za-z0-9_-]{0,255}?[0-9])(?:(?=[A-Za-z0-9_-]{0,25
 #: The contract's SECRET_VALUE at the pin (DEC-0151): `Bearer ` at a value's start in any case, or a provider key after a
 #: boundary. No case-insensitive flag; digits are ASCII. A match includes its boundary character: callers test, never
 #: read the matched text or its index.
-SECRET_VALUE = re.compile("(^[Bb][Ee][Aa][Rr][Ee][Rr][" + JS_SPACE + "]" + _NOT_LINE_END + "+|" + _KEY_BOUNDARY + _PROVIDER_KEYS + ")")
+SECRET_VALUE = re.compile("(^[Bb][Ee][Aa][Rr][Ee][Rr][" + JS_SPACE + "]" + NOT_LINE_END + "+|" + _KEY_BOUNDARY + _PROVIDER_KEYS + ")")
 _LONG_RUN = re.compile(r"[A-Za-z0-9+/=_-]{40,}")
-_BEARER_INSIDE = re.compile(r"(?<![A-Za-z0-9_])bearer[%s]+(?=[A-Za-z0-9._~+/-]*[0-9])[A-Za-z0-9._~+/-]{12,}=*" % JS_SPACE,
+BEARER_INSIDE = re.compile(r"(?<![A-Za-z0-9_])bearer[%s]+(?=[A-Za-z0-9._~+/-]*[0-9])[A-Za-z0-9._~+/-]{12,}=*" % JS_SPACE,
                             re.IGNORECASE | re.ASCII)
 _PATH_LIKE = re.compile(r"^(?:[/~.]|[A-Za-z]:[\\/]|[a-z][a-z0-9+.-]*://)", re.IGNORECASE | re.ASCII)
 _WORD_SPLIT = re.compile("[%s._-]+" % JS_SPACE)
 _ARGUMENT_SPLIT = re.compile("[%s=]" % JS_SPACE)
-_SCHEME = re.compile(r"^[A-Za-z][A-Za-z0-9+.-]*:")
+SCHEME = re.compile(r"^[A-Za-z][A-Za-z0-9+.-]*:")
+#: The names the check and older readers wrote before these became public (FAA-190 (2), (12)): kept so a module from
+#: an earlier version beside this one still loads.
+_BEARER_INSIDE, _SCHEME, _NOT_LINE_END = BEARER_INSIDE, SCHEME, NOT_LINE_END
 #: WHATWG's special schemes that carry an authority with user information (file has none).
 _SPECIAL = ("ftp", "http", "https", "ws", "wss")
 
@@ -108,13 +112,17 @@ def credential_name(name: str) -> bool:
     return any(word in words and any(p in words for p in partners) for word, partners in CREDENTIAL_PAIRS.items())
 
 
-def _long_secret(value: str) -> bool:
+def long_secret(value: str) -> bool:
+    """A run of 40 or more base64 characters mixing upper case, lower case and digits (the Node twin's longSecret)."""
     return any(re.search(r"[a-z]", run) and re.search(r"[A-Z]", run) and re.search(r"[0-9]", run) for run in _LONG_RUN.findall(value))
 
 
+_long_secret = long_secret  # its name before FAA-190 (2)
+
+
 def secret_value(value: str) -> bool:
     """A JWT anywhere, a provider key or `Bearer …`, or a long base64 run mixing upper case, lower case and digits."""
-    return bool(has_jwt(value) or SECRET_VALUE.search(value) or _long_secret(value))
+    return bool(has_jwt(value) or SECRET_VALUE.search(value) or long_secret(value))
 
 
 def _path_like(piece: str) -> bool:
@@ -126,13 +134,13 @@ def _path_like(piece: str) -> bool:
 def secret_argument(value: str) -> bool:
     """The same for a launch argument or a server's command and URL: a long run is looked for between path separators,
     so a folder path holding a session id is not taken for a key."""
-    if has_jwt(value) or SECRET_VALUE.search(value) or _BEARER_INSIDE.search(value):
+    if has_jwt(value) or SECRET_VALUE.search(value) or BEARER_INSIDE.search(value):
         return True
     for piece in _ARGUMENT_SPLIT.split(value):
         if _path_like(piece):
-            if any(_long_secret(part) for part in re.split(r"[\\/]", piece)):
+            if any(long_secret(part) for part in re.split(r"[\\/]", piece)):
                 return True
-        elif _long_secret(piece):
+        elif long_secret(piece):
             return True
     return False
 
@@ -421,7 +429,7 @@ def _url_credential(value: str, hosts: bool) -> bool:
     # What WHATWG URL parsing does first: trim C0 controls and space from the ends (never other Unicode spaces, which it
     # refuses), then remove every tab, CR and LF.
     value = re.sub(r"[\t\n\r]", "", value.strip(_C0_OR_SPACE))
-    if not _SCHEME.match(value):
+    if not SCHEME.match(value):
         return False  # not an absolute URL (WHATWG URL parsing refuses it)
     if hosts and url_refused(value):
         return False  # `new URL` refuses its host or port, so the Node twin reads it as an argument only (FAA-309)
@@ -442,7 +450,25 @@ _REPOSITORY_AUTHORITY = re.compile(r"[A-Za-z][A-Za-z0-9+.-]*://")
 #: boundary, so composed after a separator look-behind it would miss a key after `-`, `.` or `_`.
 _REPOSITORY_KEYS = r"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,}"
 _KEY_AT_A_WORD = re.compile(r"(?:\A|(?<=[._-]))(?:%s)" % _REPOSITORY_KEYS)
-_JWT_AT_A_WORD = re.compile(r"(?:\A|(?<=[._-]))%s" % JWT_SHAPE.pattern)
+
+
+def jwt_at_a_word(text: str) -> bool:
+    """Whether JWT_SHAPE matches at a word's start: the text's start, or after a `.`, `_` or `-` (FAA-321). Read in one
+    pass, as jwt_spans: the look-behind expression backtracked from every such `eyJ` of a long run, quadratic in it.
+    Every `eyJ` of one run shares that run's end and a shorter first segment, so only a run's first `eyJ` at a word's
+    start is tried; an `eyJ` that is not at one is passed over, since a later one of its run may be."""
+    at = text.find("eyJ")
+    while at >= 0:
+        if at and text[at - 1] not in "._-":
+            at = text.find("eyJ", at + 1)
+            continue
+        one = _URL_BASE64_RUN.match(text, at + 3).end()
+        if one - at - 3 >= 2 and text[one:one + 1] == ".":
+            two = _URL_BASE64_RUN.match(text, one + 1).end()
+            if two - one - 1 >= 2 and text[two:two + 1] == ".":
+                return True
+        at = text.find("eyJ", one)
+    return False
 
 
 def repository_name(piece: str) -> bool:
@@ -450,7 +476,7 @@ def repository_name(piece: str) -> bool:
     key's or JWT's shape (`sk-`, `ghp_`, `xoxb-`, `AKIA`, `eyJ`) at its start or after a `.`, `_` or `-` (0.62.0
     readings 9 and 10), so a letters-only key is still a key while `task-pipeline-dashboard`, which holds an `sk-` shape
     inside a word, is a name."""
-    return bool(_REPOSITORY_NAME.match(piece)) and not _KEY_AT_A_WORD.search(piece) and not _JWT_AT_A_WORD.search(piece)
+    return bool(_REPOSITORY_NAME.match(piece)) and not _KEY_AT_A_WORD.search(piece) and not jwt_at_a_word(piece)
 
 
 def ascii_decoded(text: str) -> str:

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

@@ -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: the facade.
 
 Since 0.40.0 (FAA-65) the kit is a set of modules, and this file re-exports every name it defined at 0.39.1, so

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

@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+# SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 """Share grants into an organization and their registrations (contract DEC-0086), the Python kit; the Node twin is
 fabric-share.mjs. Standard library only.
 

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

@@ -0,0 +1,391 @@
+# SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
+"""fabric_socket_proof: this OS account's own TCP sockets, read from its own processes (layer L0; DEC-0155 RT-2,
+FAA-292; FAA-272).
+
+macOS 27.2 shows an ad-hoc-signed interpreter (a Homebrew or uv CPython) only its own sockets in the host's socket
+table, 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 answers EPERM and is skipped, so a proof only
+ever says "this account's" or "not proved"; never another account's, the system's or nobody's.
+
+    accepted(server, client, wait=...) -> Proof   the socket at `server` connected to `client` is in one of this
+                                                  account's processes (`wait`: read again for ACCEPT_WAIT_SECONDS
+                                                  until the server has called accept())
+    own_listener(port) -> Proof                   a listener of this account on exactly 127.0.0.1:<port>
+
+Two readers, chosen by `method()`:
+
+- `libproc` (Python's): `proc_listpids(PROC_UID_ONLY)`, `proc_pidinfo(PROC_PIDLISTFDS)` and
+  `proc_pidfdinfo(PROC_PIDFDSOCKETINFO)` through ctypes, the records `lsof` itself reads, without a subprocess:
+  Project Observatory's `peer_owner` 1.3.1 reader (sha256 `b3831e5f...`, FAA-292). The `socket_fdinfo` layout is not
+  an API, so the first read in a process calibrates it on a connected pair of its own, as the sysctl reader does; a
+  layout that fails is never used again in this process, and a calibration that could not read at all is asked again.
+- `lsof` (the Node twin's, and Python's when libproc is unavailable or uncalibrated): `lsof -nP -a -u <uid>
+  -iTCP:<port> -sTCP:<state> -F pun`, the exact address pair and the numeric uid. 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 weaker than a table's `so_uid`: "a process of this uid holds the descriptor", not "the socket's
+credential is this uid". A socket another account accepted and passed with SCM_RIGHTS to a process of this uid would
+read as this account's; a caller that knows the server's pid closes that with `expect_pid`. One socket several of this
+account's processes hold (an inherited descriptor) is proved with pid None, reason `several-processes`. A process whose
+real and effective uids differ is refused (`setuid-context`): XNU lists and checks processes by the effective uid.
+Reasons, as DEC-0155 RT-1 spells them: `table-restricted` (read, and no socket of this account matches) or
+`table-restricted: <detail>` (the proof could not be read). Bounded by MAX_PIDS, MAX_FDS and TIMEOUT_SECONDS; nothing
+is cached across questions but the calibration verdict. Standard library only, no other kit module. Tests:
+`test/test_fabric_socket_proof.py`; the Node twin is `fabric-socket-proof.mjs`.
+"""
+from __future__ import annotations
+
+import ipaddress
+import os
+import socket
+import struct
+import subprocess
+import sys
+import threading
+import time
+from typing import Callable, List, NamedTuple, Optional, Tuple
+
+TABLE_RESTRICTED = "table-restricted"
+LIBPROC = "libproc"
+LSOF_METHOD = "lsof"
+LSOF = "/usr/sbin/lsof"
+#: Every read of one question is over within this many seconds (the accept wait included).
+TIMEOUT_SECONDS = 2.0
+#: How long `accepted(..., wait=True)` reads again for a server that has not called accept() yet.
+ACCEPT_WAIT_SECONDS = 0.5
+MAX_PIDS = 16384
+MAX_FDS = 65536
+MAX_OUTPUT_BYTES = 4 * 1024 * 1024
+
+#: macOS `sys/proc_info.h`: selectors and the `struct socket_fdinfo` offsets read here. The struct is 792 bytes:
+#: `proc_fileinfo` (24), then `socket_info`, whose `soi_so` is the kernel's socket (the same in every process that
+#: holds it) and whose `soi_proto.pri_tcp` starts with an `in_sockinfo` (ports as ints holding a network-order port,
+#: `insi_vflag`, the foreign and local `in4in6_addr`) and carries `tcpsi_state`.
+PROC_UID_ONLY = 4
+PROC_PIDLISTFDS = 1
+PROX_FDTYPE_SOCKET = 2
+PROC_PIDFDSOCKETINFO = 3
+SOCKINFO_TCP = 2
+SOCKET_FDINFO_SIZE = 792
+_SOI = 24                         # socket_fdinfo.psi
+_SOI_SO = _SOI + 136              # socket_info.soi_so
+_SOI_KIND = _SOI + 232            # socket_info.soi_kind
+_INI = _SOI + 240                 # soi_proto.pri_tcp.tcpsi_ini
+_INI_VFLAG = _INI + 24            # INI_IPV4 0x1, INI_IPV6 0x2
+_INI_FOREIGN = _INI + 32
+_INI_LOCAL = _INI + 48
+_TCPSI_STATE = _INI + 80          # TSI_S_CLOSED 0, TSI_S_LISTEN 1, TSI_S_TIME_WAIT 10
+_TSI_S_CLOSED = 0
+_TSI_S_LISTEN = 1
+_TSI_S_TIME_WAIT = 10
+
+Address = Tuple[str, int]
+# Real types, not postponed strings (as fabric_peer_owner's Owner): a NamedTuple's generated __new__ resolves its
+# annotations in a namespace of its own, where `Address` is no name.
+_SocketFields = NamedTuple("_SocketFields", [("local", Tuple[str, int]), ("remote", Tuple[str, int]),
+                                             ("listening", bool), ("pid", Optional[int])])
+_ProofFields = NamedTuple("_ProofFields", [("proved", bool), ("pid", Optional[int]), ("method", str),
+                                           ("reason", Optional[str])])
+
+
+class Socket(_SocketFields):
+    """One TCP socket of this account: `pid` is None when several of its processes hold it."""
+    __slots__ = ()
+
+
+class Proof(_ProofFields):
+    """Whether this account's process holds the socket asked about; `reason` says why not, or `several-processes`."""
+    __slots__ = ()
+
+
+class ProofUnreadable(Exception):
+    """This account's sockets could not be read; the message is the reason, never a socket's content."""
+
+
+def _host(host: str) -> str:
+    """One spelling per address, as fabric_peer_owner.norm_host (the same rule, kept here so this module stands alone):
+    an IPv4-mapped IPv6 address is its IPv4 form, an unspecified one `*`, `localhost` 127.0.0.1, and `[...]` loses its
+    brackets. Anything unparseable is returned unchanged (and matches only itself)."""
+    if host.startswith("[") and host.endswith("]"):
+        host = host[1:-1]
+    if host in ("*", ""):
+        return "*"
+    if host == "localhost":
+        return "127.0.0.1"
+    host = host.split("%", 1)[0]
+    try:
+        ip = ipaddress.ip_address(host)
+    except ValueError:
+        return host
+    if isinstance(ip, ipaddress.IPv6Address) and ip.ipv4_mapped is not None:
+        ip = ip.ipv4_mapped
+    return "*" if ip.is_unspecified else str(ip)
+
+
+def _digits(text: str) -> bool:
+    """`[0-9]+`, as the Node twin reads a number (`str.isdigit` also takes `٤`)."""
+    return text != "" and text.isascii() and text.isdigit()
+
+
+def loopback_host(host: str) -> bool:
+    """Whether a URL's host, as a URL parser leaves it (urlsplit's `hostname`, lower case, no brackets), names this
+    computer's loopback the way a WHATWG parser reads it: `localhost` or a name under `.localhost` (which resolves to
+    loopback), ::1, or an IPv4 address in 127/8 in any form `new URL` reads (`127.1`, `2130706433`, `0x7f.1`, one
+    trailing dot). Never an IPv4-mapped address (Node writes it in hex and refuses it), one with a zone, or whitespace.
+    The one rule fabric_http's check_url and fabric_delegation's key set source read (FAA-187 (15)); the Node twin's
+    `loopbackHost` reads `new URL`'s hostname."""
+    host = (host or "").lower()
+    if host == "localhost" or host.endswith(".localhost"):
+        return True
+    if not host or any(c.isspace() for c in host) or "%" in host:
+        return False
+    try:
+        address = ipaddress.ip_address(host)
+        return address.is_loopback and not getattr(address, "ipv4_mapped", None)
+    except ValueError:
+        pass
+    host = host[:-1] if host.endswith(".") else host
+    try:  # the short IPv4 forms a WHATWG URL also reads (127.1, 2130706433, 0x7f.1)
+        return socket.inet_aton(host)[0] == 127
+    except (OSError, ValueError):
+        return False
+
+
+# -- parsers: pure functions over captured records and text (test/fixtures/peer-owner/socket-proof-cases.json) -------
+
+def parse_socket_fdinfo(blob: bytes) -> Optional[Tuple[Address, Address, int, int]]:
+    """One `proc_pidfdinfo(PROC_PIDFDSOCKETINFO)` record: (local, remote, TCP state, socket handle) for a TCP socket,
+    None for any other kind. A short record is unreadable."""
+    if len(blob) < SOCKET_FDINFO_SIZE:
+        raise ProofUnreadable("libproc: short socket record")
+    if struct.unpack_from("<i", blob, _SOI_KIND)[0] != SOCKINFO_TCP:
+        return None
+    fport, lport = struct.unpack_from(">H", blob, _INI)[0], struct.unpack_from(">H", blob, _INI + 4)[0]
+    family, at = (socket.AF_INET, 12) if blob[_INI_VFLAG] & 0x1 else (socket.AF_INET6, 0)
+    size = 4 if family == socket.AF_INET else 16
+    foreign = socket.inet_ntop(family, bytes(blob[_INI_FOREIGN + at:_INI_FOREIGN + at + size]))
+    local = socket.inet_ntop(family, bytes(blob[_INI_LOCAL + at:_INI_LOCAL + at + size]))
+    state = struct.unpack_from("<i", blob, _TCPSI_STATE)[0]
+    return (_host(local), lport), (_host(foreign), fport), state, struct.unpack_from("<Q", blob, _SOI_SO)[0]
+
+
+def own_sockets(records: List[Tuple[int, Address, Address, int, int]]) -> List[Socket]:
+    """Sockets from this account's records (pid, local, remote, state, handle): one per handle, pid None when several
+    processes hold it. Closed and TIME_WAIT sockets are left out."""
+    by_handle: dict = {}
+    for pid, local, remote, state, handle in records:
+        if state in (_TSI_S_CLOSED, _TSI_S_TIME_WAIT):
+            continue
+        by_handle.setdefault(handle, (local, remote, state, []))[3].append(pid)
+    return [Socket(local, remote, state == _TSI_S_LISTEN, pids[0] if len(set(pids)) == 1 else None)
+            for local, remote, state, pids in by_handle.values()]
+
+
+def _lsof_address(text: str) -> Optional[Address]:
+    """`127.0.0.1:47311`, `[::1]:47070` or `*:47312`: the port after the last colon, ASCII digits only."""
+    host, sep, port = text.rpartition(":")
+    if not sep or not _digits(port) or int(port) > 65535:
+        return None
+    return _host(host), int(port)
+
+
+def parse_lsof_sockets(text: str, uid: int) -> List[Socket]:
+    """`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: TCP holds one connection per pair) is one
+    socket with pid None."""
+    found: dict = {}
+    pid = owner = None
+    for line in text.splitlines():
+        tag, value = line[:1], line[1:]
+        if tag == "p":
+            pid, owner = (int(value) if _digits(value) else None), None
+        elif tag == "u":
+            owner = int(value) if _digits(value) else None
+        elif tag == "n" and pid is not None and owner == uid:
+            local_text, arrow, remote_text = value.partition("->")
+            local = _lsof_address(local_text)
+            remote = _lsof_address(remote_text) if arrow else ("*", 0)
+            if local is None or remote is None:
+                continue
+            key = (local, remote, not arrow)
+            found.setdefault(key, []).append(pid)
+    return [Socket(local, remote, listening, pids[0] if len(set(pids)) == 1 else None)
+            for (local, remote, listening), pids in found.items()]
+
+
+def _proved(hits: List[Socket], how: str) -> Proof:
+    if not hits:
+        return Proof(False, None, how, TABLE_RESTRICTED)
+    pids = {s.pid for s in hits}
+    if len(pids) == 1 and None not in pids:
+        return Proof(True, pids.pop(), how, None)
+    return Proof(True, None, how, "several-processes")
+
+
+def accepted_in(sockets: List[Socket], server: Address, client: Address, how: str) -> Proof:
+    """RT-2 over this account's sockets: the one at `server` connected to `client`. Two different sockets with that
+    address pair cannot be told apart (`several-rows`)."""
+    hits = [s for s in sockets if not s.listening and s.local == server and s.remote == client]
+    if len(hits) > 1:
+        return Proof(False, None, how, "several-rows")
+    return _proved(hits, how)
+
+
+def listener_in(sockets: List[Socket], port: int, how: str) -> Proof:
+    """FAA-272 over this account's sockets: a listener bound exactly to 127.0.0.1:<port>. XNU refuses another ordinary
+    account that bind beside ours (`in_pcbbind`); our wildcard or ::1 listener, and root's, cannot be told from a
+    hidden one, so they prove nothing (DEC-0155 RT-4)."""
+    return _proved([s for s in sockets if s.listening and s.local == ("127.0.0.1", port)], how)
+
+
+# -- readers ----------------------------------------------------------------------------------------------------------
+
+_LOCK = threading.Lock()
+#: None until a calibration of the libproc layout reaches a verdict in this process, then True or False.
+_LIBPROC_OK: list = [None]
+
+
+def _run(argv: List[str]) -> str:
+    """One bounded run of lsof; its exit 1 with nothing printed is "no socket matched", not a failure."""
+    try:
+        done = subprocess.run(argv, capture_output=True, timeout=TIMEOUT_SECONDS, check=False, stdin=subprocess.DEVNULL)
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        raise ProofUnreadable("lsof: %s" % type(exc).__name__) from None
+    if done.returncode == 1 and not done.stdout.strip():
+        return ""
+    if done.returncode != 0:
+        raise ProofUnreadable("lsof: exit %d" % done.returncode)
+    if len(done.stdout) > MAX_OUTPUT_BYTES:
+        raise ProofUnreadable("lsof: output over %d bytes" % MAX_OUTPUT_BYTES)
+    return done.stdout.decode("utf-8", "replace")
+
+
+def _libproc_records(uid: int, deadline: float) -> List[Tuple[int, Address, Address, int, int]]:
+    """This uid's processes' TCP sockets, as (pid, local, remote, state, handle). A process that cannot be read (gone,
+    or EPERM) is skipped: it can only lose an answer, never make one."""
+    try:
+        import ctypes
+        lib = ctypes.CDLL("/usr/lib/libproc.dylib", use_errno=True)
+        lib.proc_listpids.argtypes = [ctypes.c_uint32, ctypes.c_uint32, ctypes.c_void_p, ctypes.c_int]
+        lib.proc_pidinfo.argtypes = [ctypes.c_int, ctypes.c_int, ctypes.c_uint64, ctypes.c_void_p, ctypes.c_int]
+        lib.proc_pidfdinfo.argtypes = [ctypes.c_int, ctypes.c_int, ctypes.c_int, ctypes.c_void_p, ctypes.c_int]
+    except (ImportError, OSError, TypeError, AttributeError) as exc:
+        raise ProofUnreadable("libproc: %s" % type(exc).__name__) from None
+    for fn in (lib.proc_listpids, lib.proc_pidinfo, lib.proc_pidfdinfo):
+        fn.restype = ctypes.c_int
+    need = lib.proc_listpids(PROC_UID_ONLY, uid, None, 0)
+    if need <= 0:
+        raise ProofUnreadable("libproc: errno %d" % ctypes.get_errno())
+    pids = (ctypes.c_int * min(need // 4 + 64, MAX_PIDS))()
+    got = lib.proc_listpids(PROC_UID_ONLY, uid, pids, ctypes.sizeof(pids))
+    if got <= 0:
+        raise ProofUnreadable("libproc: errno %d" % ctypes.get_errno())
+    if got // 4 >= MAX_PIDS:
+        raise ProofUnreadable("libproc: over %d processes" % MAX_PIDS)
+    record = ctypes.create_string_buffer(SOCKET_FDINFO_SIZE)
+    out = []
+    for pid in pids[:got // 4]:
+        if pid <= 0:
+            continue
+        if time.monotonic() > deadline:
+            raise ProofUnreadable("libproc: deadline")
+        size = lib.proc_pidinfo(pid, PROC_PIDLISTFDS, 0, None, 0)
+        if size <= 0:
+            continue
+        fds = ctypes.create_string_buffer(min(size + 32 * 8, MAX_FDS * 8))
+        size = lib.proc_pidinfo(pid, PROC_PIDLISTFDS, 0, fds, len(fds))
+        for i in range(max(size, 0) // 8):
+            fd, kind = struct.unpack_from("<iI", fds, i * 8)
+            if kind != PROX_FDTYPE_SOCKET:
+                continue
+            if lib.proc_pidfdinfo(pid, fd, PROC_PIDFDSOCKETINFO, record, SOCKET_FDINFO_SIZE) != SOCKET_FDINFO_SIZE:
+                continue
+            parsed = parse_socket_fdinfo(record.raw)
+            if parsed is not None:
+                out.append((pid,) + parsed)
+    return out
+
+
+def _calibrate_libproc() -> Optional[bool]:
+    """Whether the `socket_fdinfo` layout reads back a connected pair of this process's own (the listener and both
+    ends, each once, with their exact addresses and this pid); None when libproc could not be read at all, which the
+    caller does not keep (FAA-273 item 11: an unread calibration is not a verdict)."""
+    probe = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    client = taken = None
+    try:
+        probe.bind(("127.0.0.1", 0))
+        probe.listen(1)
+        client = socket.create_connection(probe.getsockname(), timeout=TIMEOUT_SECONDS)
+        taken, _ = probe.accept()
+        server, near = probe.getsockname()[:2], client.getsockname()[:2]
+        have = own_sockets(_libproc_records(os.getuid(), time.monotonic() + TIMEOUT_SECONDS))
+        me = os.getpid()
+        return all(len(hits) == 1 and hits[0].pid == me for hits in (
+            [s for s in have if s.listening and s.local == server],
+            [s for s in have if not s.listening and s.local == server and s.remote == near],
+            [s for s in have if not s.listening and s.local == near and s.remote == server]))
+    except (ProofUnreadable, OSError, struct.error, ValueError):
+        return None
+    finally:
+        for s in (client, taken, probe):
+            if s is not None:
+                s.close()
+
+
+def method(platform: Optional[str] = None) -> str:
+    """The reader the next question uses: libproc once its layout passed calibration, else lsof; none off macOS."""
+    if (platform or sys.platform) != "darwin":
+        return "none"
+    with _LOCK:
+        if _LIBPROC_OK[0] is None:
+            _LIBPROC_OK[0] = _calibrate_libproc()
+        return LIBPROC if _LIBPROC_OK[0] else LSOF_METHOD
+
+
+def _ask(port: int, state: str, pick: Callable[[List[Socket], str], Proof], wait: float, platform: Optional[str],
+         uid: Optional[int], euid: Optional[int], how: Optional[str], run: Optional[Callable[[List[str]], str]]) -> Proof:
+    start = time.monotonic()
+    if (platform or sys.platform) != "darwin":
+        return Proof(False, None, "none", "%s: unsupported-platform" % TABLE_RESTRICTED)
+    uid = os.getuid() if uid is None else uid
+    euid = os.geteuid() if euid is None else euid
+    if uid != euid:
+        return Proof(False, None, how or "none", "%s: setuid-context" % TABLE_RESTRICTED)
+    how = how or method(platform)
+    pause = 0.005
+    while True:
+        try:
+            if how == LIBPROC:
+                have = own_sockets(_libproc_records(uid, start + TIMEOUT_SECONDS))
+            else:
+                argv = [LSOF, "-nP", "-a", "-u", str(uid), "-iTCP:%d" % port, "-sTCP:%s" % state, "-F", "pun"]
+                have = parse_lsof_sockets((run or _run)(argv), uid)
+        except ProofUnreadable as exc:
+            return Proof(False, None, how, "%s: %s" % (TABLE_RESTRICTED, exc))
+        answer = pick(have, how)
+        if answer.proved or time.monotonic() + pause > start + min(wait, TIMEOUT_SECONDS):
+            return answer
+        time.sleep(pause)
+        pause = min(pause * 2, 0.05)
+
+
+def accepted(server: Address, client: Address, *, wait: bool = False, platform: Optional[str] = None,
+             uid: Optional[int] = None, euid: Optional[int] = None, how: Optional[str] = None,
+             run: Optional[Callable[[List[str]], str]] = None) -> Proof:
+    """RT-2: whether the socket at `server` connected to `client` (a client's own connection, seen from the server's
+    side) is in one of this account's processes. `wait`: a server end is read again for ACCEPT_WAIT_SECONDS, since a
+    client asks right after connect() and the server's accepted socket exists only once it calls accept().
+    `platform`, `uid`, `euid`, `how` and `run` are the tests'."""
+    server, client = (_host(str(server[0])), int(server[1])), (_host(str(client[0])), int(client[1]))
+    return _ask(server[1], "ESTABLISHED", lambda have, how_: accepted_in(have, server, client, how_),
+                ACCEPT_WAIT_SECONDS if wait else 0.0, platform, uid, euid, how, run)
+
+
+def own_listener(port: int, *, platform: Optional[str] = None, uid: Optional[int] = None, euid: Optional[int] = None,
+                 how: Optional[str] = None, run: Optional[Callable[[List[str]], str]] = None) -> Proof:
+    """FAA-272: whether one of this account's processes listens on exactly 127.0.0.1:<port>."""
+    return _ask(int(port), "LISTEN", lambda have, how_: listener_in(have, int(port), how_), 0.0, platform, uid, euid,
+                how, run)

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

@@ -1,3 +1,4 @@
+# SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 """Supervisors (DEC-0032, LC-14): launchd plists, systemd user units and Task Scheduler tasks, installed and
 removed without touching what the operator turned off; release pruning (LC-15). Part of the service kit
 (FAA-65, layer L3)."""
@@ -25,6 +26,7 @@ from pathlib import Path as _Path  # noqa: E402
 if str(_Path(__file__).resolve().parent) not in _sys.path:  # the kit loads from any working directory (FAA-65)
     _sys.path.insert(0, str(_Path(__file__).resolve().parent))
 import fabric_peer_owner as _po  # noqa: E402 - the listener's owner (DEC-0154 HA-2)
+import fabric_socket_proof as _sp  # noqa: E402 - the one loopback host rule (FAA-326)
 from fabric_base import (
     DRAIN_SECONDS,
     SUPERVISOR_ENV,
@@ -462,16 +464,20 @@ def launchd_pid(label: str, domain: Optional[str] = None) -> Optional[int]:
     return None
 
 
-def _loopback_host(host: Optional[str]) -> bool:
-    """Whether `host` (urlsplit's hostname: lower-case, no brackets) names this machine: localhost, 127/8 or ::1."""
-    if not host:
-        return False
-    if host == "localhost":
-        return True
+#: Whether urlsplit's hostname names this machine: the kit's one loopback rule (FAA-326), so 127.1, 2130706433 and a
+#: name under .localhost, which the Node twin's `new URL` reads as loopback, take the checked path here too.
+_loopback_host = _sp.loopback_host
+
+
+def _loopback_otherwise(host: Optional[str]) -> bool:
+    """A loopback address the kit's rule does not take: one with a zone (`::1%lo0`) or IPv4-mapped (`::ffff:127.0.0.1`).
+    urlopen reaches loopback through either, so it is refused unread, as Node refuses it (0.84.0 seam reading)."""
     try:
-        return ipaddress.ip_address(host).is_loopback
+        address = ipaddress.ip_address((host or "").split("%", 1)[0])
     except ValueError:
         return False
+    mapped = getattr(address, "ipv4_mapped", None)
+    return bool(address.is_loopback or (mapped and mapped.is_loopback))
 
 
 class ForeignUserAnswer:
@@ -498,7 +504,7 @@ def _read_well_known(origin: str, timeout: float = 2.0,
     except ValueError:  # a port out of range
         port = None
     if parts.scheme == "http" and port and _loopback_host(parts.hostname):
-        # every loopback spelling (127.0.0.1, another 127/8 address, localhost, [::1]) goes on a checked connection,
+        # 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)
         conn = _po.CheckedHTTPConnection(parts.hostname, port, timeout=timeout, vouch_pid=vouch_pid)
         try:
@@ -512,6 +518,8 @@ def _read_well_known(origin: str, timeout: float = 2.0,
             return None, None
         finally:
             conn.close()
+    if _loopback_otherwise(parts.hostname):
+        return None, None
     try:
         with urllib.request.urlopen(origin + "/.well-known/fabric-service", timeout=timeout) as response:
             return json.loads(response.read().decode()), None
@@ -522,14 +530,9 @@ def _read_well_known(origin: str, timeout: float = 2.0,
 def _job_listens(pid: int, port: int) -> bool:
     """Whether launchd's job `pid` listens on 127.0.0.1:<port> exactly (never the wildcard), asked of the process itself
     (`lsof -p`), which a restricted socket table does not hide. Used only for a LaunchDaemon root just bootstrapped,
-    whose pid launchd itself named (FAA-278)."""
-    if sys.platform != "darwin" or not isinstance(pid, int) or isinstance(pid, bool) or pid <= 1:
-        return False
-    try:
-        out = _po._run([_po.LSOF, "-nP", "-a", "-p", str(pid), "-i4TCP", "-sTCP:LISTEN", "-Fn"])
-    except _po.TableUnreadable:
-        return False
-    return any(host == "127.0.0.1" and p == port for host, p in _po.parse_lsof_listeners(out))  # exact bind, as RT-3
+    whose pid launchd itself named (FAA-278). The peer owner's one lsof reader, the uid left to the caller, which checks
+    the job's UserName itself (FAA-286 item 1)."""
+    return _po.pid_listens(pid, port, owner=None)
 
 
 def _account_uid(user_name: str) -> Optional[int]:

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

@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+# SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 """Who is calling an agent that sits behind `tailscale serve`, and what that person may open (FAA-297). Standard
 library only; the Node twin is fabric-tailnet.mjs, and both answer test/fixtures/tailnet/vectors.json alike.