@passioncode-ai/passioncode 0.2.17 → 0.2.19

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

@@ -0,0 +1,204 @@
+"""The probe's rules that read one thing and need no running service (FAA-65): a plist's marker and priority, the
+network guard's verdict, the board responder's fixture conversation, a session cookie's lifetime, a usage report, and
+whether two repository URLs name one repository. ``check_service.py`` runs them against a live service.
+Standard library only, Python 3.9+."""
+from __future__ import annotations
+
+import email.utils
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import fabric_service as fs  # noqa: E402 - beside this file
+
+
+def plist_problems(plist: dict, label: object, token: object = None) -> list:
+    """What makes a service's launchd job unfit to stay up: identity, restart, secrets."""
+    problems = []
+    if plist.get("Label") != label:
+        problems.append("Label %r" % plist.get("Label"))
+    if plist.get("RunAtLoad") is not True:
+        problems.append("RunAtLoad is not true")
+    if plist.get("KeepAlive") is not True:
+        problems.append("KeepAlive is %r, not true" % plist.get("KeepAlive"))
+    for key, value in (plist.get("EnvironmentVariables") or {}).items():
+        if re.search(r"(TOKEN|SECRET|PASSWORD|KEY)$", key) and not key.endswith("_FILE"):
+            problems.append("secret-like variable %s in the plist" % key)
+        if token and token in str(value):
+            problems.append("the service token itself is in the plist")
+    return problems
+
+
+def marker_problem(plist: dict) -> Optional[str]:
+    """What is wrong with the job's supervisor marker (DEC-0057; FAA-05), read the way the copy it starts reads it.
+
+    Without ``FABRIC_SERVICE_SUPERVISOR=launchd`` (or ``--fabric-supervisor launchd``) a copy that finds the
+    lock held exits 75 at once, and KeepAlive starts it again every ThrottleInterval."""
+    env = plist.get("EnvironmentVariables")
+    env = {str(k): str(v) for k, v in env.items()} if isinstance(env, dict) else {}
+    argv = plist.get("ProgramArguments")
+    argv = [str(a) for a in argv] if isinstance(argv, list) else []
+    marker = fs.supervisor_marker(env, argv)
+    if marker["kind"] == "supervised" and marker["manager"] == "launchd":
+        return None
+    fix = ("a copy that finds the lock held exits 75 at once and KeepAlive respawns it every ThrottleInterval; "
+           "regenerate the plist with launchd_plist / launchdPlist and reinstall")
+    if marker["kind"] == "conflict":
+        return "%s: %s" % (fs.marker_conflict_message(marker), fix)
+    if marker["kind"] == "supervised":
+        return "the marker names %s, not launchd: %s" % (marker["manager"], fix)
+    if marker.get("unreadable") is not None:
+        return "the marker %r names no supervisor: %s" % (marker["unreadable"], fix)
+    return "no %s=launchd: %s" % (fs.SUPERVISOR_ENV, fix)
+
+
+def priority_problems(plist: dict) -> list:
+    """A service that answers hosts and agents must not be scheduled as background work."""
+    out = []
+    if plist.get("ProcessType", "Standard") in ("Background", "Adaptive"):
+        out.append("ProcessType is %s" % plist.get("ProcessType"))
+    if isinstance(plist.get("Nice"), int) and plist["Nice"] > 0:
+        out.append("Nice is %d" % plist["Nice"])
+    if plist.get("LowPriorityIO") is True or plist.get("LowPriorityBackgroundIO") is True:
+        out.append("low-priority I/O")
+    return out
+
+
+# A platform router (Heroku, Fly, Render, a CDN) routes by Host, so a request naming a foreign
+# Host never reaches an online service: the router itself answers, typically 404 or 421. That is
+# still a refusal — the service disclosed nothing — so for a remote placement the host check
+# accepts it, as long as the body is not the well-known document. Every other guard request names
+# the right Host, reaches the service, and must be the service's own 403.
+PLATFORM_HOST_REFUSALS = (400, 404, 421)
+
+
+def guard_verdict(rule: str, remote: bool, status: int, body: bytes) -> Tuple[str, str]:
+    if status == 403:
+        return "PASS", "HTTP 403"
+    disclosed = b"fabric-service/" in (body or b"")
+    if rule == "network.host-check" and remote and status in PLATFORM_HOST_REFUSALS and not disclosed:
+        return "PASS", "HTTP %d from the platform router: a foreign Host never reaches the service" % status
+    return "FAIL", "HTTP %d%s" % (status, ", and the body is the well-known document" if disclosed else "")
+
+
+def board_responder_verdict(wk: Any, kit: Optional[str] = None) -> Tuple[str, str]:
+    """board.responder: NOT_RUN when the well-known document declares no fabric-project-comms revision; FAIL when it
+    declares one this kit does not read or the kit's fixture conversation finds a problem; PASS otherwise. `kit` is the
+    service's own copy (a .py or .mjs path); by default the kit beside this probe."""
+    protocols = wk.get("protocols") if isinstance(wk, dict) else None
+    declared = [p for p in protocols if isinstance(p, str) and p.startswith("fabric-project-comms/")] if isinstance(protocols, list) else []
+    if not declared:
+        return "NOT_RUN", "the service declares no board participation (no fabric-project-comms revision in protocols)"
+    accepted = fs.accepted_revisions("fabric-project-comms")
+    unread = [p for p in declared if "error" in fs.negotiate_revision(p, accepted)]
+    if unread:
+        return "FAIL", "declares %s, which this kit does not read (it reads %s)" % (", ".join(unread), ", ".join(accepted))
+    try:
+        if kit and kit.endswith(".mjs"):
+            if not shutil.which("node"):
+                return "NOT_RUN", "node is not installed to run %s's fixture conversation" % kit
+            url = Path(kit).resolve().as_uri()
+            out = subprocess.run(["node", "--input-type=module", "-e",
+                                  "import(process.env.FABRIC_BOARD_KIT).then(async (m) => console.log(JSON.stringify(await m.selfCheck())))"],
+                                 env=dict(os.environ, FABRIC_BOARD_KIT=url), capture_output=True, text=True, timeout=60)
+            problems = json.loads(out.stdout.strip().splitlines()[-1]) if out.returncode == 0 and out.stdout.strip() else ["the Node kit did not run: %s" % out.stderr.strip()[:200]]
+        else:
+            # A clean interpreter: the kit is several modules (FAA-65), and modules this probe already imported from
+            # beside it would stand in for the copy under test.
+            path = Path(kit) if kit else Path(__file__).resolve().parent / "fabric_board.py"
+            code = ("import json, sys; sys.path.insert(0, sys.argv[1]); import %s as board; "
+                    "print(json.dumps(board.self_check()))" % path.stem)
+            out = subprocess.run([sys.executable, "-E", "-s", "-c", code, str(path.resolve().parent)], capture_output=True,
+                                 text=True, timeout=60, cwd=str(path.resolve().parent))
+            problems = json.loads(out.stdout.strip().splitlines()[-1]) if out.returncode == 0 and out.stdout.strip() else ["the kit did not run: %s" % out.stderr.strip()[-200:]]
+    except Exception as exc:  # noqa: BLE001 - a kit that cannot run its conversation fails the rule
+        return "FAIL", "the kit's fixture conversation did not run: %s" % exc.__class__.__name__
+    if problems:
+        return "FAIL", "; ".join(problems)
+    return "PASS", "declares %s; the kit%s answers the fixture conversation (whole, fenced, no epoch)" % (
+        ", ".join(declared), " at %s" % kit if kit else " beside this probe")
+
+
+def session_lifetime_problem(set_cookie: str, now: Optional[float] = None) -> Optional[str]:
+    """DEC-0039: a session cookie set at sign-in lives at most 7 days. Max-Age wins over Expires (RFC 6265
+    §5.3); a cookie with neither ends with the browser session. None when it is within the bound."""
+    attrs = {}
+    for part in set_cookie.split(";")[1:]:
+        name, _, value = part.strip().partition("=")
+        attrs[name.strip().lower()] = value.strip()
+    bound = fs.OPERATOR_SESSION_MAX_SECONDS
+    if "max-age" in attrs:
+        if not re.fullmatch(r"-?\d+", attrs["max-age"]):
+            return "the session cookie's Max-Age %r is not a number" % attrs["max-age"]
+        if int(attrs["max-age"]) > bound:
+            return "the session cookie's Max-Age %s outlives 7 days (%d s, DEC-0039)" % (attrs["max-age"], bound)
+        return None
+    if "expires" in attrs:
+        try:
+            at = email.utils.parsedate_to_datetime(attrs["expires"]).timestamp()
+        except (TypeError, ValueError, IndexError, OverflowError):
+            return "the session cookie's Expires %r is not a date" % attrs["expires"]
+        if at - (time.time() if now is None else now) > bound:
+            return "the session cookie's Expires %s outlives 7 days (DEC-0039)" % attrs["expires"]
+    return None
+
+
+def _semver(text: str) -> Tuple[int, int, int]:
+    m = re.match(r"^(\d+)\.(\d+)\.(\d+)", text or "")
+    return (int(m.group(1)), int(m.group(2)), int(m.group(3))) if m else (0, 0, 0)
+
+
+def usage_problems(report: Any, service_id: str, instance: str) -> List[str]:
+    """What makes this not a DEC-0021 usage report of the service: shape, identity and the sums of
+    FAC-SEM-025. An unknown cost must be null; a day's totals are the sums of its models."""
+    if not isinstance(report, dict):
+        return ["not an object"]
+    out: List[str] = []
+    if report.get("protocol") != fs.PROTOCOL:
+        out.append("protocol is %r" % report.get("protocol"))
+    if report.get("service") != {"id": service_id, "instance": instance}:
+        out.append("reports for %r, not %s.%s" % (report.get("service"), service_id, instance))
+    if report.get("currency") != "USD":
+        out.append("currency is not USD")
+    days = report.get("days")
+    if not isinstance(days, list) or len(days) > fs.USAGE_DAYS:
+        return out + ["days is not a list of at most 31"]
+    # The arithmetic of FAC-SEM-025 is the kit's `usage_findings`, the contract's `usageRules` held to its vectors: one
+    # implementation, so the probe never disagrees with the kit and never throws on a count that is not a number.
+    for i, day in enumerate(days):
+        if not isinstance(day, dict):
+            out.append("days[%d]: not an object" % i)
+            continue
+        if not isinstance(day.get("byModel"), list):
+            out.append("days[%d]: byModel missing" % i)
+            continue
+        for row, at in [(day, "days[%d]" % i)] + [(m, "days[%d].byModel[%d]" % (i, j)) for j, m in enumerate(day["byModel"]) if isinstance(m, dict)]:
+            cost = row.get("costUsd")
+            if cost is not None and (isinstance(cost, bool) or not isinstance(cost, (int, float)) or cost < 0):
+                out.append("%s: costUsd is not a non-negative number" % at)
+        for j, m in enumerate(day["byModel"]):
+            # DEC-0046, DEC-0061: a row's route is a login in its vendor's runner, an issued key, or the platform's
+            # own metered models (a listing in the cloud).
+            if isinstance(m, dict) and "route" in m and m["route"] not in fs.USAGE_ROUTES:
+                out.append("days[%d].byModel[%d]: route %r is not subscription, key or platform-metered" % (i, j, m["route"]))
+    for finding in fs.usage_findings(report):
+        out.append("%s: %s" % (finding["instancePath"] or "/", finding["message"]))
+    return out
+
+
+def same_repository(a: str, b: str) -> bool:
+    """git@github.com:o/r.git, https://github.com/o/r and github.com/o/r are one repository."""
+    def norm(u: str) -> str:
+        u = u.strip().lower()
+        u = re.sub(r"^git@([^:]+):", r"\1/", u)
+        u = re.sub(r"^[a-z+]+://", "", u)
+        u = re.sub(r"^[^@/]+@", "", u)
+        return re.sub(r"\.git$", "", u).rstrip("/")
+    return bool(a and b) and norm(a) == norm(b)

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

@@ -408,7 +408,7 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
             for c in report["copies"]:
                 print("  %-8s %s (%s)" % (c["state"], c["path"], c["version"] or "no version marker"))
             if not report["copies"]:
-                print("  no kit copy" + (" — services %s declare a dashboard" % ", ".join(report["services"])
+                print("  no kit copy" + (" (services %s declare a dashboard)" % ", ".join(report["services"])
                                          if report["dashboard"] and report["services"] else ""))
             if report["services"]:
                 print("  services from this repository: %s" % ", ".join(report["services"]))

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

@@ -0,0 +1,286 @@
+// Who may call a service: the descriptor token, the network guard, the operator's one-time login and session, remote placement (DEC-0019), the feed client's token header.
+// Part of the Node service kit (FAA-65, layer L3); the twin of fabric_auth.py. Node 20+, no dependency.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { PROTOCOL, ServiceError, nowIso } from './fabric-base.mjs';
+import { tokenMatches, windowsTokenProblem } from './fabric-platform.mjs';
+import { atomicWrite, ensurePrivateDir, servicesDir } from './fabric-paths.mjs';
+import { isPlainObject } from './fabric-usage.mjs';
+import { validateDescriptor, writeDescriptor } from './fabric-descriptor.mjs';
+
+export const SESSION_COOKIE = 'fabric_session';
+
+// DEC-0019: a remote placement's cookie is host-bound and HTTPS-only.
+export const REMOTE_SESSION_COOKIE = '__Host-fabric_session';
+
+const CODE = /^[A-Za-z0-9_-]{16,256}$/;
+
+export function ensureToken(file) {
+  if (fs.existsSync(file)) return readToken(file);
+  ensurePrivateDir(path.dirname(file));
+  const token = crypto.randomBytes(32).toString('base64url');
+  atomicWrite(file, token, 0o600);
+  return token;
+}
+
+/**
+ * Refuse a symlink, a file owned by someone else, or one others can read. On Windows the rule is
+ * service.md "Windows token files" (DEC-0032, DEC-0033, DEC-0057): windowsTokenAclProblem over the
+ * file's flags, owner and ACEs; a refusal names the SID, never the contents.
+ */
+export function readToken(file) {
+  const info = fs.lstatSync(file);
+  if (info.isSymbolicLink()) throw new ServiceError(`Token file ${file} is a symlink; refusing it.`);
+  if (process.platform === 'win32') {
+    const problem = windowsTokenProblem(file, info);
+    if (problem) throw new ServiceError(problem);
+  } else {
+    if (typeof process.getuid === 'function' && info.uid !== process.getuid()) throw new ServiceError(`Token file ${file} belongs to another user.`);
+    if (info.mode & 0o077) throw new ServiceError(`Token file ${file} is readable by others; set mode 0600.`);
+  }
+  const token = fs.readFileSync(file, 'utf8').trim();
+  if (token.length < 16) throw new ServiceError(`Token file ${file} holds no usable token.`);
+  return token;
+}
+
+/**
+ * The one header a client sends the service token in, as the descriptor's `auth` declares it: `header` defaults
+ * to Authorization and `scheme` to Bearer; `none` carries the raw token. Never assume `Authorization: Bearer`.
+ */
+export function tokenHeader(auth, token) {
+  const declared = isPlainObject(auth) ? auth : {};
+  const name = typeof declared.header === 'string' ? declared.header : 'Authorization';
+  const scheme = typeof declared.scheme === 'string' ? declared.scheme : 'Bearer';
+  return { name, value: scheme === 'none' ? token : `Bearer ${token}` };
+}
+
+/** DEC-0039 (service.md "The session's lifetime"): the longest a service may keep an operator session. */
+export const OPERATOR_SESSION_IDLE_SECONDS = 12 * 60 * 60;
+
+export const OPERATOR_SESSION_MAX_SECONDS = 7 * 24 * 60 * 60;
+
+// Compare bytes, not UTF-16 units: a non-ASCII value of the right length must be a refusal, not a RangeError.
+const safeEqual = (a, b) => {
+  const x = Buffer.from(String(a)), y = Buffer.from(String(b));
+  return x.length === y.length && crypto.timingSafeEqual(x, y);
+};
+
+const sessionBound = (value, longest) => {
+  if (typeof value !== 'number' || !Number.isFinite(value)) throw new ServiceError('a session bound must be a finite number of seconds.');
+  return Math.min(Math.trunc(value), longest);
+};
+
+// Single-use login codes, and operator sessions with the DEC-0039 lifetime: a session ends 12 h after its
+// last use, 7 days after the code was redeemed, on logout, and when the descriptor token rotates. The server
+// enforces all four: the cookie carries a signed claim (session id, sign-in time, token revision) and the
+// code store keeps a record per session (last use, logout). Rotating the key with revokeAll() ends every one.
+export class LoginCodes {
+  // `stateDir` — a local service keeps codes, sessions and the session key in files. An online service
+  // (DEC-0019) usually has no durable disk: pass `stateDir = null` with `{ store, key }` — `store` like
+  // `new MemoryCodeStore()` and `key` a Buffer from a platform secret. A memory store forgets codes AND
+  // sessions on a restart, so a deploy signs the operator out (the host signs in again on the page's 401);
+  // pass a durable store to keep sessions. `token` is the descriptor token, or a function returning the
+  // current one: a session begun under one token is refused once it rotates. A service MAY shorten
+  // `idleSeconds` or `maxSeconds`, never lengthen them.
+  constructor(stateDir, ttlSeconds = 120, { store = null, key = null, token = null,
+    idleSeconds = OPERATOR_SESSION_IDLE_SECONDS, maxSeconds = OPERATOR_SESSION_MAX_SECONDS, clock = () => Date.now() / 1000 } = {}) {
+    this.ttl = Math.min(ttlSeconds, 120);
+    this.idleSeconds = sessionBound(idleSeconds, OPERATOR_SESSION_IDLE_SECONDS);
+    this.maxSeconds = sessionBound(maxSeconds, OPERATOR_SESSION_MAX_SECONDS);
+    this.store = store;
+    this.fixedKey = key;
+    this.token = token;
+    this.clock = clock;
+    if (stateDir) {
+      this.dir = ensurePrivateDir(stateDir);
+      this.keyPath = path.join(this.dir, 'session.key');
+      this.codesPath = path.join(this.dir, 'login-codes.json');
+    } else if (!store || !key) {
+      throw new ServiceError('LoginCodes without a state directory needs { store, key }.');
+    }
+    if (key && Buffer.from(key).length < 32) throw new ServiceError('the session key must be at least 32 bytes.');
+  }
+
+  key() {
+    if (this.fixedKey) return Buffer.from(this.fixedKey);
+    if (!fs.existsSync(this.keyPath)) atomicWrite(this.keyPath, crypto.randomBytes(32), 0o600);
+    return fs.readFileSync(this.keyPath);
+  }
+
+  load() {
+    if (this.store) return this.store.load();
+    try { return JSON.parse(fs.readFileSync(this.codesPath, 'utf8')); } catch { return {}; }
+  }
+
+  save(codes) {
+    const horizon = this.clock() - 3600;
+    const kept = Object.fromEntries(Object.entries(codes).filter(([, v]) => (v.expires ?? 0) > horizon));
+    if (this.store) { this.store.save(kept); return; }
+    atomicWrite(this.codesPath, JSON.stringify(kept), 0o600);
+  }
+
+  issue() {
+    const code = crypto.randomBytes(24).toString('base64url');
+    const expires = this.clock() + this.ttl;
+    const codes = this.load();
+    codes[crypto.createHash('sha256').update(code).digest('hex')] = { expires, used: false };
+    this.save(codes);
+    return { url: `/fabric/v1/login?code=${code}`, expiresAt: new Date(expires * 1000).toISOString().replace(/\.\d{3}Z$/, 'Z') };
+  }
+
+  // The code is recorded as used BEFORE it is honoured, and burned even when expired.
+  redeem(code) {
+    if (!code || !CODE.test(code)) return null;
+    const digest = crypto.createHash('sha256').update(code).digest('hex');
+    const codes = this.load();
+    const entry = codes[digest];
+    if (!entry || entry.used) return null;
+    entry.used = true;
+    this.save(codes);
+    const now = this.clock();
+    if (entry.expires < now) return null;
+    const session = crypto.randomBytes(18).toString('base64url');
+    const signedInAt = Math.trunc(now);
+    codes[LoginCodes.recordKey(session)] = { expires: signedInAt + this.maxSeconds, signedInAt, lastUsedAt: now };
+    this.save(codes);
+    const claim = `v2.${session}.${signedInAt}.${this.tokenRevision()}`;
+    return `${claim}.${this.mac(claim)}`;
+  }
+
+  /** True while the session is live; a use within the bounds refreshes the idle bound. */
+  sessionValid(value) {
+    const parsed = this.parse(value);
+    if (!parsed) return false;
+    const [session, signedInAt] = parsed;
+    const now = this.clock();
+    if (now >= signedInAt + this.maxSeconds) return false;
+    const codes = this.load();
+    const record = codes[LoginCodes.recordKey(session)];
+    if (!record || record.signedInAt !== signedInAt || record.loggedOutAt != null) return false;
+    const last = Number(record.lastUsedAt ?? 0);
+    if (now >= last + this.idleSeconds) return false;
+    if (now - last >= Math.min(60, Math.max(1, Math.trunc(this.idleSeconds / 10)))) {
+      record.lastUsedAt = now;
+      this.save(codes);
+    }
+    return true;
+  }
+
+  /** End this session on the server; clear the browser's copy with expiredSessionCookieHeader(). */
+  logout(value) {
+    const parsed = this.parse(value);
+    if (!parsed) return false;
+    const codes = this.load();
+    const record = codes[LoginCodes.recordKey(parsed[0])];
+    if (!record || record.signedInAt !== parsed[1] || record.loggedOutAt != null) return false;
+    record.loggedOutAt = this.clock();
+    this.save(codes);
+    return true;
+  }
+
+  parse(value) {
+    if (typeof value !== 'string' || !/^[\x21-\x7e]*$/.test(value)) return null;
+    const parts = value.split('.');
+    if (parts.length !== 5 || parts[0] !== 'v2' || !parts[1] || !/^\d+$/.test(parts[2])) return null;
+    if (!safeEqual(parts[4], this.mac(parts.slice(0, 4).join('.')))) return null;
+    if (!safeEqual(parts[3], this.tokenRevision())) return null;
+    return [parts[1], Number(parts[2])];
+  }
+
+  mac(claim) { return crypto.createHmac('sha256', this.key()).update(claim).digest('hex'); }
+
+  tokenRevision() {
+    const token = typeof this.token === 'function' ? this.token() : this.token;
+    if (!token) return '-';
+    return crypto.createHmac('sha256', this.key()).update(`token-revision\0${token}`).digest('hex').slice(0, 16);
+  }
+
+  static recordKey(session) { return `s:${crypto.createHash('sha256').update(session).digest('hex')}`; }
+
+  revokeAll() {
+    if (this.fixedKey) throw new ServiceError('a platform-held session key is rotated on the platform, not here.');
+    atomicWrite(this.keyPath, crypto.randomBytes(32), 0o600);
+  }
+}
+
+/** DEC-0019: a code store held in memory — for an online service with no durable disk. */
+export class MemoryCodeStore {
+  constructor() { this.codes = {}; }
+  load() { return JSON.parse(JSON.stringify(this.codes)); }
+  save(codes) { this.codes = JSON.parse(JSON.stringify(codes)); }
+}
+
+/** The cookie lives no longer than the absolute bound (DEC-0039); the server ends it sooner. */
+export const sessionCookieHeader = (value, maxAge = OPERATOR_SESSION_MAX_SECONDS) => `${SESSION_COOKIE}=${value}; Path=/; HttpOnly; SameSite=Strict; Max-Age=${maxAge}`;
+
+/** DEC-0019: the remote cookie — `__Host-` name, Secure, no Domain, Path=/. */
+export const remoteSessionCookieHeader = (value, maxAge = OPERATOR_SESSION_MAX_SECONDS) => `${REMOTE_SESSION_COOKIE}=${value}; Path=/; Secure; HttpOnly; SameSite=Strict; Max-Age=${maxAge}`;
+
+/** The header that clears the browser's session cookie, sent with a logout. */
+export const expiredSessionCookieHeader = (remote = false) => (remote ? remoteSessionCookieHeader : sessionCookieHeader)('', 0);
+
+/**
+ * DEC-0019: the request guard of an online service. `origin` is the service's own origin
+ * (`https://agent.example.com`). `forwardedProto` is the platform-set scheme where TLS ends
+ * before the process (`x-forwarded-proto`); pass `undefined` when the process terminates TLS.
+ * Returns the refusal sentence, or null.
+ */
+export function checkRemoteRequest(origin, host, requestOrigin, secFetchSite, forwardedProto) {
+  const own = new URL(origin);
+  if (String(host ?? '').toLowerCase() !== own.host) return `Host ${host} is not this service.`;
+  if (forwardedProto !== undefined && forwardedProto !== null && String(forwardedProto).split(',')[0].trim() !== 'https') return 'This service answers over https only.';
+  if (requestOrigin !== undefined && requestOrigin !== null && requestOrigin !== own.origin) return `Origin ${requestOrigin} is not this service.`;
+  if (secFetchSite === 'cross-site') return 'Cross-site requests are refused.';
+  return null;
+}
+
+/**
+ * DEC-0019: may this request read the well-known document? A local service answers anyone (the
+ * loopback guard already ran); a remote one only the bearer of the service token. A `false`
+ * answer is a `401` with an EMPTY body — nothing about the service is disclosed.
+ */
+export function wellKnownAllowed(placement, authorization, token, scheme = 'Bearer') {
+  return placement !== 'remote' || tokenMatches(authorization, token, scheme);
+}
+
+/** The token directory a host-side installer uses for remote services on this computer. */
+export function remoteTokenFile(id, instance = 'default', dir = servicesDir()) {
+  return path.join(path.dirname(dir), 'tokens', `${id}.${instance}.token`);
+}
+
+/**
+ * DEC-0019, installer side: register an online service on THIS computer. Writes the token file
+ * (0600, never printed) and the descriptor; the same token must be set on the hosting platform as
+ * a secret. Returns the descriptor path. `token` is read from the caller — a file or stdin —
+ * never from an argument vector.
+ */
+/**
+ * DEC-0019, installer side: register an online service on THIS computer — the token file (0600, never printed) and the
+ * descriptor. DEC-0061: `installedBy` defaults to `{by: 'person', role: 'operator', tool: 'fabric-service register-remote'}`
+ * (a person runs this); `runner` (`{kind?, credentialKind}`) says how its model calls sign in, as a kind and never a
+ * credential; `peer` (`{endpoint, custody, residency, maxDataClass}`) offers it to others and needs `runner`.
+ */
+export function registerRemote({ id, instance = 'default', name, summary, origin, token, doctor, dir = servicesDir(),
+  installedBy = { by: 'person', role: 'operator', tool: 'fabric-service register-remote' }, runner, peer }) {
+  if (!token || String(token).trim().length < 16) throw new ServiceError('the service token must be at least 16 characters.');
+  const tokenFile = remoteTokenFile(id, instance, dir);
+  const d = {
+    protocol: PROTOCOL, id, instance, name, ...(summary ? { summary } : {}), placement: 'remote', origin,
+    auth: { tokenFile }, lifecycle: { manager: 'none' }, ...(doctor ? { commands: { doctor } } : {}),
+    installedAt: nowIso(), installedBy, ...(runner ? { runner: { ...runner } } : {}), ...(peer ? { peer: { ...peer } } : {}),
+  };
+  const problems = validateDescriptor(d);
+  if (problems.length) throw new ServiceError(`Descriptor is invalid: ${problems.join('; ')}.`);
+  ensurePrivateDir(path.dirname(tokenFile));
+  atomicWrite(tokenFile, String(token).trim(), 0o600);
+  return writeDescriptor(d, dir);
+}
+
+export function cookieValue(header, name = SESSION_COOKIE) {
+  for (const part of String(header ?? '').split(';')) {
+    const [k, ...rest] = part.trim().split('=');
+    if (k === name) return rest.join('=');
+  }
+  return null;
+}