@passioncode-ai/fabric-agent-adapter 0.73.0 → 0.74.0

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

@@ -8,6 +8,13 @@
            --board-kit PATH                       (board.responder: the service's own fabric_board.py or fabric-board.mjs)
            --repo PATH                            (dashboard.opens-in-host: the service's checkout)
 
+A local placement is read only when this OS account's process holds its port (DEC-0154 HA-2): `listener.owner`
+comes before every rule that reads the port, from the computer's socket table (fabric_peer_owner). Nothing listening is NOT_RUN (`down`, and
+`well-known.answers` fails as before); another OS account's, root's or SYSTEM's listener, or one whose owner cannot be
+told, FAILs as `foreign-user`, and then no rule reads the port and no credential is sent; one `port.rules` NOT_RUN
+line names the rules not read (as it does when the well-known document gives nothing to read). Every local
+connection, a reconnect included, is checked again before a byte goes out on it.
+
 A remote placement (DEC-0019 — an online agent or dashboard at an https origin) is probed over
 TLS with the certificate verified: the well-known document must refuse a request without the
 token (401 with none of the service's data: an empty body, or an identity proxy's page, DEC-0109), the guards must refuse a foreign Host/Origin and cross-site requests,
@@ -72,6 +79,8 @@ import fabric_service as fs  # noqa: E402
 import fabric_connections as fcn  # noqa: E402
 from check_service_rules import shown_repository  # noqa: E402 - a repository in evidence carries no userinfo or query
 import fabric_interop as fi  # noqa: E402
+import fabric_peer_owner as po  # noqa: E402 - DEC-0154 HA-2: the listener's owner before any credential
+from check_service_rules import ForeignUser, PORT_RULES_UNREAD, listener_owner_verdict  # noqa: E402 - DEC-0154 HA-2
 
 Result = Dict[str, str]
 
@@ -153,13 +162,16 @@ class Probe:
                 conn = http.client.HTTPSConnection(self.host_name, self.port, context=context, timeout=8)
             base = {"Host": self.netloc}
         else:
-            conn = http.client.HTTPConnection("127.0.0.1", self.port, timeout=5)
+            # DEC-0154 HA-2: every local connection, a reconnect included, is checked before a byte is sent on it.
+            conn = po.CheckedHTTPConnection("127.0.0.1", self.port, timeout=5)
             base = {"Host": "127.0.0.1:%d" % self.port}
         base.update(headers or {})
         try:
             conn.request(method, path, body=body, headers=base)
             resp = conn.getresponse()
             return resp.status, merge_headers(resp.getheaders()), resp.read()
+        except po.ListenerRefused as exc:
+            raise ForeignUser("foreign-user: %s" % exc) from None
         finally:
             conn.close()
 
@@ -168,6 +180,14 @@ class Probe:
         name, value = fs.token_header(self.d.get("auth"), self.token or "")
         return {name: value}
 
+    # the listener's owner (DEC-0154 HA-2) -------------------------------
+    def listener_rule(self) -> bool:
+        """DEC-0154 HA-2, `down` then `foreign-user` then the answer (check_service_rules.listener_owner_verdict). False
+        when the port must not be read (`foreign-user`)."""
+        verdict, evidence = listener_owner_verdict(self.port)
+        self.add("listener.owner", verdict, evidence)
+        return verdict != "FAIL"
+
     # descriptor ------------------------------------------------------------
     def descriptor_rules(self) -> None:
         problems = fs.validate_descriptor(self.d)
@@ -200,7 +220,7 @@ class Probe:
         elif "origin" not in self.d:
             unique = "an app's descriptor names no origin, so it claims no port (FAC-SEM-010)"
         else:
-            unique = "port %d is unique" % self.port
+            unique = "no other descriptor here declares port %d (HA-1's claim on the computer is FAA-225)" % self.port
         self.add("descriptor.port-claim", "FAIL" if clashes else "PASS", "; ".join(clashes) or unique)
         # FAA-198: the repository that links the agent to its project; a new install is refused without it, an installed one
         # is named here (NOT_RUN is no pass) until its owner adds it.
@@ -261,6 +281,12 @@ class Probe:
                 self.add_no_token(no_token, None)
             self.add("well-known.answers", "FAIL", "body is not JSON")
             return
+        if not isinstance(self.wk, dict):
+            self.wk = None
+            if self.remote:
+                self.add_no_token(no_token, None)
+            self.add("well-known.answers", "FAIL", "body is not a JSON object")
+            return
         if self.remote:
             self.add_no_token(no_token, self.wk)
         self.add("well-known.answers", "PASS", "HTTP 200")
@@ -899,8 +925,16 @@ class Probe:
             return self.results
         if not self.port:
             return self.results
+        if not self.remote and not self.listener_rule():
+            self.add("port.rules", "NOT_RUN", "not read: " + PORT_RULES_UNREAD + ", because the listener is not this OS "
+                     "account's (listener.owner FAIL, DEC-0154 HA-2)")
+            self.lifecycle_rules()
+            return self.results
         self.well_known_rules()
-        if self.wk is not None:
+        if self.wk is None:
+            self.add("port.rules", "NOT_RUN", "not read: " + PORT_RULES_UNREAD + ", because well-known.answers above "
+                     "got no document to read")
+        else:
             self.network_rules()
             self.auth_rules()
             self.usage_rules()

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

@@ -20,6 +20,44 @@ sys.path.insert(0, str(Path(__file__).resolve().parent))
 import fabric_service as fs  # noqa: E402 - beside this file
 from fabric_http import redact_url  # noqa: E402
 from fabric_secrets import ascii_decoded, repository_name, secret_argument  # noqa: E402
+import fabric_peer_owner as po  # noqa: E402 - DEC-0154 HA-2
+import socket  # noqa: E402
+
+
+# The rules that ask the service's port, named on one NOT_RUN line when none of them can be read (0.74.0 product
+# reading 8): a probe names what it could not check.
+PORT_RULES_UNREAD = ("every rule that reads the port (well-known, network, auth, usage, A2A, dashboard, login, "
+                     "interop, channel-agent, board)")
+
+
+class ForeignUser(ConnectionError):
+    """DEC-0154 HA-2: the server end of a local connection is not this OS account's process (`foreign-user`); nothing
+    was sent on it. A ConnectionError, so every rule that reads the port reports it as no answer."""
+
+
+def listener_owner_verdict(port: int) -> Tuple[str, str]:
+    """`listener.owner` for a local service: (verdict, evidence). `down`, then `foreign-user`, then everything the
+    listener answers: a local service is read only when this OS account's process holds its port. The owner is the
+    server end of a connection of the probe's own, on which nothing is sent (HA-2's source: the client's own connection;
+    two sockets of one account on one port, as SO_REUSEPORT workers hold, read as that account)."""
+    where = "127.0.0.1:%d" % port
+    try:
+        sock = socket.create_connection(("127.0.0.1", port), timeout=5)
+    except ConnectionRefusedError:
+        return "NOT_RUN", "nothing listens on %s (down)" % where
+    except OSError as exc:  # a full backlog, a timeout: the well-known rule reports what answers, each call checked
+        return "NOT_RUN", "could not connect to %s to tell its owner (%s)" % (where, type(exc).__name__)
+    try:
+        owner = po.server_end(sock)
+    finally:
+        sock.close()
+    if owner.kind == po.THIS_ACCOUNT:
+        return "PASS", "%s is held by this OS account's process (pid %s, read by %s)" % (
+            where, owner.pid if owner.pid is not None else "not shown", owner.method)
+    why = {po.ANOTHER_ACCOUNT: "another OS account's process", po.SYSTEM: "a system account's process"}.get(
+        owner.kind, "a process whose owner cannot be told (%s)" % owner.reason)
+    return "FAIL", ("foreign-user: %s is held by %s (read by %s); no credential was sent and nothing it answers is read "
+                    "as this service's" % (where, why, owner.method))
 
 _LOCAL_PATH = re.compile(r"[/~.\\]|[A-Za-z]:[/\\]")  # how a local path starts, never a user before an `@`
 _SCP_HOST = re.compile(r"[^@/:\\]+:")  # what follows the `@` of user[:password]@host:path

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

@@ -9,12 +9,17 @@
 // is safe: an idempotent method or an `Idempotency-Key` header; any other request only on 429. The wait before retry n
 // (from 0) is min(maxBackoffS, backoffBaseS * 2**n) * (0.5 + rand()); a `Retry-After` replaces it up to
 // maxRetryAfterS. A wait past the deadline is not taken. Plain http is refused unless the host is loopback or
-// `insecure`. An error names the method and the redacted URL, never a header or a body.
+// `insecure`. An error names the method and the redacted URL, never a header or a body. Before a byte goes to a plain
+// http loopback URL the server end of the connection is told from the socket table (DEC-0154 HA-2, FAA-226): not this
+// OS account's process, or an owner that cannot be told, is an HttpError of kind foreign-user, nothing sent, not retried.
 //
 // The transport is injected in tests: async ({ method, url, headers, body, timeoutS, maxBytes }) =>
 // { status, headers, body: Uint8Array }, throwing on a connection error (a `TimeoutError` name is a timeout) or an
 // HttpError. Node 20 or newer, no dependencies. Part of the service kit (FAA-65, layer L4).
 
+import http from 'node:http';
+import { CheckedAgent, ListenerRefused } from './fabric-peer-owner.mjs';
+
 export const RETRY_STATUSES = Object.freeze([408, 425, 429, 500, 502, 503, 504]);
 export const IDEMPOTENT_METHODS = Object.freeze(['GET', 'HEAD', 'OPTIONS', 'PUT', 'DELETE']);
 export const DEFAULT_MAX_BYTES = 8 * 1024 * 1024;
@@ -30,7 +35,7 @@ export class HttpError extends Error {
     this.attempts = attempts;
     this.retryAfterS = retryAfterS;
     this.body = body.slice(0, 2048);
-    this.kind = kind; // http, connection, timeout, too-large, refused
+    this.kind = kind; // http, connection, timeout, too-large, refused, foreign-user
   }
 }
 
@@ -147,8 +152,53 @@ function checkHeaders(headers) {
   return out;
 }
 
-// The default transport: fetch, no redirects followed, the body read to one byte past maxBytes.
+const LOOPBACK_AGENT = new CheckedAgent();
+
+// Plain http to a loopback host (DEC-0154 HA-2): node:http over a connection checked before a byte is written, no
+// redirect followed, the body read to one byte past maxBytes. fetch cannot hand its socket to the check.
+export function checkedLoopbackTransport({ method, url, headers, body, timeoutS, maxBytes, agent = LOOPBACK_AGENT }) {
+  const parts = new URL(url);
+  // A body goes with its Content-Length, as fetch sent it: a server that reads only Content-Length (the kit's
+  // sample_service, the stdlib handlers) would read a chunked body as empty (0.74.0 seam reading 1).
+  const sent = { ...headers };
+  if (body && !Object.keys(sent).some((k) => k.toLowerCase() === 'content-length')) sent['Content-Length'] = String(body.length);
+  return new Promise((resolve, reject) => {
+    const req = http.request({ host: parts.hostname.replace(/^\[|\]$/g, ''), port: Number(parts.port || 80),
+      path: parts.pathname + parts.search, method, headers: sent, agent }, (res) => {
+      const chunks = [];
+      let size = 0;
+      res.on('data', (c) => {
+        if (size <= maxBytes) { chunks.push(c); size += c.length; }
+        if (size > maxBytes) res.destroy();
+      });
+      res.on('close', () => {
+        clearTimeout(timer);
+        const all = Buffer.concat(chunks);
+        const got = Object.fromEntries(Object.entries(res.headers).map(([k, v]) => [k, Array.isArray(v) ? v.join(', ') : String(v)]));
+        if (!res.complete && size <= maxBytes) reject(Object.assign(new Error('the answer broke off'), { name: 'ConnectionError' }));
+        else resolve({ status: res.statusCode, headers: got, body: new Uint8Array(all.subarray(0, maxBytes + 1)) });
+      });
+    });
+    const timer = setTimeout(() => req.destroy(Object.assign(new Error('timed out'), { name: 'TimeoutError' })),
+      Math.max(1, Math.ceil(timeoutS * 1000)));
+    req.on('error', (err) => {
+      clearTimeout(timer);
+      if (err instanceof ListenerRefused) {
+        reject(new HttpError(`${method} ${redactUrl(url)}: foreign-user: ${err.message}`, { url: redactUrl(url), kind: 'foreign-user' }));
+      } else reject(err);
+    });
+    if (body) req.write(body);
+    req.end();
+  });
+}
+
+// The default transport: fetch, no redirects followed, the body read to one byte past maxBytes; plain http to a
+// loopback host goes through checkedLoopbackTransport.
 export async function fetchTransport({ method, url, headers, body, timeoutS, maxBytes }) {
+  const target = new URL(url);
+  if (target.protocol === 'http:' && isLoopback(target.hostname)) {
+    return checkedLoopbackTransport({ method, url, headers, body, timeoutS, maxBytes });
+  }
   const res = await fetch(url, { method, headers, body: body ?? undefined, redirect: 'manual',
     signal: AbortSignal.timeout(Math.max(1, Math.ceil(timeoutS * 1000))) });
   const chunks = [];

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

@@ -6,7 +6,9 @@
 //    $XDG_DATA_HOME/passioncode-fabric) the way Fabric's own locateHub does: a small regular file, never a link or a
 //    FIFO; protocol fabric-hub/0.1; origin exactly http://127.0.0.1:<port>; MCP at /mcp; a door token file inside the
 //    registry root; a pid that is alive. The port does not prove who holds it, so a binding credential is sent only
-//    after this check passes, done again before each send.
+//    after this check passes, done again before each send. The pid is never the proof (DEC-0154 HA-2): every
+//    connection to the door is checked from the socket table before a byte goes out (fabric-peer-owner.mjs), and a
+//    listener of another OS account, or one whose owner cannot be told, is HubError foreign-user with nothing sent.
 // 2. Ask once, keep the credential in a file: requestBoardAccess() asks for the board.respond grant through the door;
 //    pollAccess() writes the credential, shown once, to a 0600 file and answers without it. Tokens live in files and
 //    headers only — never argv, a URL, a log line or an error text.
@@ -25,6 +27,12 @@ import os from 'node:os';
 import path from 'node:path';
 import { atomicWrite, ensurePrivateDir, readToken } from './fabric-service.mjs';
 import { hubKeyCertified } from './fabric-estate.mjs';
+import { CheckedAgent, ListenerRefused } from './fabric-peer-owner.mjs';
+
+// DEC-0154 HA-2: every connection to the door is checked before a byte goes out; kept alive, so a busy session reads the
+// socket table once per connection, not once per call. A free socket is closed after 2 s idle, before a server's own
+// keep-alive timeout (5 s in Node) can close it under a request that reuses it.
+const HUB_AGENT = new CheckedAgent({ keepAlive: true, timeout: 2000 });
 
 export const HUB_PROTOCOL = 'fabric-hub/0.1';
 export const MCP_PROTOCOL_VERSION = '2025-06-18';
@@ -158,9 +166,10 @@ export function readCredential(file) {
 /**
  * One MCP request to <origin>/mcp with a bearer in the header; only http://127.0.0.1:<port>, no proxy. Answers
  * {status, headers, body} (body parsed JSON or null; an SSE answer read to its first data: line). A refused connection
- * is HubError hub-unavailable (retryable).
+ * is HubError hub-unavailable (retryable); a listener that is not this OS account's process is HubError foreign-user
+ * (retryable) before the bearer is sent (DEC-0154 HA-2): the connection is checked from the socket table first.
  */
-export function postMcp(origin, body, bearer, { session, timeout = 15000, method = 'POST', protocolVersion } = {}) {
+export function postMcp(origin, body, bearer, { session, timeout = 15000, method = 'POST', protocolVersion, agent = HUB_AGENT } = {}) {
   const m = LOOPBACK_ORIGIN.exec(origin);
   if (!m) return Promise.reject(new HubError('not-a-hub', 'Only the hub\'s loopback origin is used.'));
   const payload = method === 'DELETE' ? null : Buffer.from(JSON.stringify(body));
@@ -169,7 +178,7 @@ export function postMcp(origin, body, bearer, { session, timeout = 15000, method
   if (protocolVersion) headers['mcp-protocol-version'] = protocolVersion;
   if (payload) headers['content-length'] = String(payload.length);
   return new Promise((resolve, reject) => {
-    const req = http.request({ host: '127.0.0.1', port: Number(m[1]), path: '/mcp', method, headers, timeout, agent: false }, (res) => {
+    const req = http.request({ host: '127.0.0.1', port: Number(m[1]), path: '/mcp', method, headers, timeout, agent }, (res) => {
       const chunks = [];
       let size = 0;
       res.on('data', (c) => {
@@ -192,7 +201,9 @@ export function postMcp(origin, body, bearer, { session, timeout = 15000, method
       res.on('error', () => reject(new HubError('hub-unavailable', 'Fabric\'s hub did not answer (the answer broke off).', true)));
     });
     req.on('timeout', () => req.destroy(new Error('timeout')));
-    req.on('error', (e) => reject(new HubError('hub-unavailable', `Fabric's hub did not answer (${e.code ?? e.message}).`, true)));
+    req.on('error', (e) => reject(e instanceof ListenerRefused
+      ? new HubError('foreign-user', `The hub's port is not held by this OS account's process (${e.owner?.kind ?? e.code}); nothing was sent.`, true)
+      : new HubError('hub-unavailable', `Fabric's hub did not answer (${e.code ?? e.message}).`, true)));
     if (payload) req.write(payload);
     req.end();
   });