@openparachute/hub 0.7.6-rc.1 → 0.7.6-rc.4

package/src/hub-instance.ts

@@ -0,0 +1,365 @@
+/**
+ * Hub instance identity + loopback-hijack detection (hub#737).
+ *
+ * ## The incident this defends against (2026-07-02 P0)
+ *
+ * The hub binds `*:1939` (INADDR_ANY / `0.0.0.0`). An OrbStack Linux machine
+ * auto-forwarded ITS port 1939 onto the host as a SPECIFIC bind on
+ * `127.0.0.1:1939` — and a specific loopback bind WINS over a wildcard bind for
+ * all loopback traffic. Every module's JWKS/API call to `127.0.0.1:1939`
+ * silently reached the WRONG hub (a fresh container DB → empty JWKS, no admin),
+ * so every hub-JWT validation failed `no applicable key found in the JWKS` and
+ * the ecosystem 401-looped for hours. `lsof -nP -i :1939` showed two LISTENs;
+ * the tell was `/health` reporting the container's version, not the checkout's.
+ *
+ * ## The primitive: a per-process instance nonce
+ *
+ * Each `parachute serve` process generates a random nonce at boot, (a) exposes
+ * it as `instance` in `/health`, and (b) writes it to
+ * `~/.parachute/hub-instance.json` (0644). That file is the linchpin: an
+ * EXTERNAL process (`parachute status`, `parachute doctor`) can learn THIS
+ * hub's true identity from disk WITHOUT traversing the (possibly hijacked)
+ * loopback — then compare it to what a loopback `GET /health` actually returns.
+ * A mismatch means another process owns `127.0.0.1:<port>`.
+ *
+ * The in-process self-probe (armed by `serve`) compares its own in-memory nonce
+ * to the loopback `/health` it fetches, logs loudly on mismatch, and records the
+ * verdict back into the same file's `selfProbe` field so external tools surface
+ * the serve process's own authoritative reading without re-probing.
+ *
+ * Every side effect (fs, network probe) is behind an injectable seam so the
+ * whole module runs deterministically in tests with no real network / disk.
+ */
+
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { CONFIG_DIR } from "./config.ts";
+
+/** The public incident reference operators grep for. */
+export const HIJACK_INCIDENT_REF = "hub#737 / team-vault Log/2026-07-02-port-exhaustion-incident";
+
+/** Self-probe verdicts. `ok` = loopback reaches us; `hijacked` = someone else owns loopback. */
+export type SelfProbeStatus = "ok" | "hijacked" | "unreachable";
+
+/**
+ * The serve process's own most-recent loopback self-probe reading, persisted
+ * into the instance file so external readers (`status`) see the authoritative
+ * verdict without re-probing the (possibly hijacked) loopback themselves.
+ */
+export interface SelfProbeState {
+  status: SelfProbeStatus;
+  /** ISO timestamp of the reading. */
+  checkedAt: string;
+  /** The `instance` the loopback `/health` actually returned (present on a `hijacked` reading). */
+  observedInstance?: string;
+  /** One-line human detail (loud message on a hijack; the probe error class on unreachable). */
+  detail?: string;
+}
+
+/** The `~/.parachute/hub-instance.json` record. */
+export interface HubInstanceRecord {
+  /** Per-process random nonce (`crypto.randomUUID`) minted at serve boot. */
+  instance: string;
+  /** The serve process PID (informational — helps an operator map the file to a process). */
+  pid: number;
+  /** The port this serve bound. */
+  port: number;
+  /** ISO timestamp of serve boot. */
+  startedAt: string;
+  /** Last self-probe reading, patched in by the running serve process. */
+  selfProbe?: SelfProbeState;
+}
+
+/** Mint a fresh per-process nonce. */
+export function generateInstanceNonce(): string {
+  return randomUUID();
+}
+
+/** Path to the instance file under a config dir (default `~/.parachute`). */
+export function hubInstancePath(configDir: string = CONFIG_DIR): string {
+  return join(configDir, "hub-instance.json");
+}
+
+/**
+ * Atomically write the instance record (tmp + rename, 0644). Best-effort: a
+ * write failure must NEVER take the hub down — the file is a diagnostic aid, not
+ * a load-bearing runtime dependency. Returns true on success.
+ */
+export function writeHubInstanceFile(
+  record: HubInstanceRecord,
+  opts: { configDir?: string; log?: (line: string) => void } = {},
+): boolean {
+  const path = hubInstancePath(opts.configDir);
+  const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+  try {
+    const dir = dirname(path);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    writeFileSync(tmp, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o644 });
+    renameSync(tmp, path);
+    return true;
+  } catch (err) {
+    // Don't leave a half-written tmp behind if the rename (or write) failed.
+    try {
+      if (existsSync(tmp)) rmSync(tmp, { force: true });
+    } catch {
+      // Best-effort cleanup — nothing more we can do.
+    }
+    opts.log?.(
+      `parachute serve: could not write ${path} (${err instanceof Error ? err.message : String(err)}); loopback-hijack detection for external tools is degraded, hub start continues.`,
+    );
+    return false;
+  }
+}
+
+/**
+ * Remove the instance file (best-effort). Called on graceful shutdown so a
+ * cleanly-stopped hub doesn't leave a stale identity/self-probe verdict on disk
+ * for `status` / `doctor` to read as a phantom. A hard kill (SIGKILL) can't run
+ * this — the readers additionally gate on live hub liveness, so a leftover file
+ * from a hard kill never surfaces as a false hijack.
+ */
+export function clearHubInstanceFile(configDir: string = CONFIG_DIR): void {
+  try {
+    rmSync(hubInstancePath(configDir), { force: true });
+  } catch {
+    // Best-effort — a missing / unremovable file is not worth surfacing.
+  }
+}
+
+/**
+ * Read + validate the instance file. Returns null on absence / unreadable /
+ * malformed — a missing file is the benign "no nonce-aware serve wrote one yet"
+ * state, never an error.
+ */
+export function readHubInstanceFile(configDir: string = CONFIG_DIR): HubInstanceRecord | null {
+  const path = hubInstancePath(configDir);
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+  if (!raw || typeof raw !== "object") return null;
+  const r = raw as Record<string, unknown>;
+  if (typeof r.instance !== "string" || r.instance.length === 0) return null;
+  if (typeof r.port !== "number") return null;
+  const rec: HubInstanceRecord = {
+    instance: r.instance,
+    pid: typeof r.pid === "number" ? r.pid : -1,
+    port: r.port,
+    startedAt: typeof r.startedAt === "string" ? r.startedAt : "",
+  };
+  const sp = r.selfProbe;
+  if (sp && typeof sp === "object") {
+    const s = sp as Record<string, unknown>;
+    if (s.status === "ok" || s.status === "hijacked" || s.status === "unreachable") {
+      const state: SelfProbeState = {
+        status: s.status,
+        checkedAt: typeof s.checkedAt === "string" ? s.checkedAt : "",
+      };
+      if (typeof s.observedInstance === "string") state.observedInstance = s.observedInstance;
+      if (typeof s.detail === "string") state.detail = s.detail;
+      rec.selfProbe = state;
+    }
+  }
+  return rec;
+}
+
+/** The result of probing a loopback `/health`. */
+export interface LoopbackProbe {
+  /** The socket answered at all (any HTTP status). */
+  reachable: boolean;
+  /** HTTP status, when reachable. */
+  status?: number;
+  /** The `instance` field of the JSON body, when present + parseable. */
+  instance?: string;
+  /** True when the body self-identifies as a parachute hub (`service: "parachute-hub"`). */
+  isHub?: boolean;
+}
+
+/**
+ * Probe `http://127.0.0.1:<port>/health` and extract the instance identity.
+ * Bounded (default 1.5s); never throws — a network error is `{ reachable: false }`.
+ */
+export async function probeLoopbackInstance(
+  port: number,
+  opts: { timeoutMs?: number; fetchFn?: typeof fetch } = {},
+): Promise<LoopbackProbe> {
+  const fetchFn = opts.fetchFn ?? fetch;
+  try {
+    const res = await fetchFn(`http://127.0.0.1:${port}/health`, {
+      signal: AbortSignal.timeout(opts.timeoutMs ?? 1500),
+    });
+    const out: LoopbackProbe = { reachable: true, status: res.status };
+    try {
+      const body = (await res.json()) as Record<string, unknown>;
+      if (typeof body.instance === "string") out.instance = body.instance;
+      if (body.service === "parachute-hub") out.isHub = true;
+    } catch {
+      // A non-JSON / unparseable body still counts as "reachable" — a foreign
+      // process answering the port with junk is exactly the hijack shape.
+    }
+    return out;
+  } catch {
+    return { reachable: false };
+  }
+}
+
+/**
+ * Classify a loopback probe against our TRUE nonce.
+ *   - not reachable                → `unreachable` (we bound, but loopback refused/timed out — suspicious but soft).
+ *   - reachable, instance === ours → `ok`.
+ *   - reachable, instance !== ours → `hijacked` (a DIFFERENT process owns loopback: another hub, or a foreign
+ *     server answering `/health` with no/other instance — the OrbStack-shadow class).
+ */
+export function classifyLoopback(ourNonce: string, probe: LoopbackProbe): SelfProbeStatus {
+  if (!probe.reachable) return "unreachable";
+  if (probe.instance === ourNonce) return "ok";
+  return "hijacked";
+}
+
+/**
+ * The LOUD, structured hijack alert. Names the class + the exact diagnosis
+ * commands + the incident reference so an operator scanning logs can act
+ * immediately. Repeated verbatim on every probe while mismatched (by design —
+ * a single line scrolls away; a hijack is a standing emergency).
+ */
+export function hijackAlertMessage(port: number, observedInstance?: string): string {
+  const observed = observedInstance
+    ? `a DIFFERENT hub (instance=${observedInstance})`
+    : "a foreign process (no hub instance nonce in its /health)";
+  return [
+    `parachute serve: LOOPBACK HIJACK on 127.0.0.1:${port} — this hub bound the port but loopback /health is answered by ${observed}.`,
+    "  Loopback traffic (module JWKS/API calls, CLI probes) is NOT reaching this hub — every hub-JWT validation downstream will fail.",
+    `  A specific 127.0.0.1:${port} bind (commonly an OrbStack/container port-forward) wins over this hub's wildcard bind.`,
+    `  Diagnose:  lsof -nP -iTCP:${port} -sTCP:LISTEN   (expect ONE listener — this hub)`,
+    `             orb list   (stop/delete any VM auto-forwarding ${port}, e.g. a leftover smoke-test machine)`,
+    `  Incident:  ${HIJACK_INCIDENT_REF}`,
+  ].join("\n");
+}
+
+/** The softer "we're listening but loopback didn't answer" note (logged once per state change). */
+export function unreachableNote(port: number): string {
+  return `parachute serve: loopback /health on 127.0.0.1:${port} did not answer, yet this hub is bound — transient, or another process is interfering with loopback. Watching (will re-probe).`;
+}
+
+// ---------------------------------------------------------------------------
+// Self-probe timer (armed by `serve` after the listener is up)
+// ---------------------------------------------------------------------------
+
+export interface HubSelfProbe {
+  /** Stop the interval. */
+  stop(): void;
+  /** Run exactly one probe now (used for the immediate startup check + tests). */
+  probeOnce(): Promise<SelfProbeStatus>;
+  /** The most recent in-memory verdict (tests). */
+  getState(): SelfProbeState | undefined;
+}
+
+export interface HubSelfProbeDeps<H = unknown> {
+  /** Poll cadence in ms. Default 300_000 (5 min) — a safety net, not a hot path. */
+  intervalMs?: number;
+  /** Loopback probe (default {@link probeLoopbackInstance}). */
+  probe?: (port: number) => Promise<LoopbackProbe>;
+  /** Persist the verdict (default: patch the instance file's `selfProbe`). */
+  writeState?: (state: SelfProbeState) => void;
+  /** Loud log sink (default `console.error`). */
+  log?: (line: string) => void;
+  /** Clock seam (default `() => new Date()`). */
+  now?: () => Date;
+  /** Injectable scheduler (default `setInterval`). Tests drive ticks manually. */
+  setIntervalFn?: (cb: () => void, ms: number) => H;
+  /** Injectable clear (default `clearInterval`). */
+  clearIntervalFn?: (handle: H) => void;
+}
+
+/**
+ * Arm the loopback self-probe. On each tick (and on the immediate startup
+ * `probeOnce`) it fetches loopback `/health`, compares the returned instance to
+ * OUR nonce, logs per the incident-severity rules, and persists the verdict:
+ *
+ *   - `hijacked`   → LOUD structured alert EVERY tick (standing emergency), verdict persisted.
+ *   - `unreachable`→ softer note, logged ONLY on a state change (avoid a spinning log on a flaky loopback).
+ *   - `ok`         → recovery line logged once when clearing a prior non-ok verdict.
+ *
+ * The verdict is written to the instance file's `selfProbe` field so external
+ * tools (`status`) read the authoritative reading without re-probing the
+ * hijacked loopback. Overlapping ticks are guarded (a slow probe never stacks).
+ * The interval is `unref`'d so it never keeps the event loop alive on its own.
+ */
+export function armHubSelfProbe<H = ReturnType<typeof setInterval>>(
+  args: { port: number; nonce: string; record: HubInstanceRecord; configDir?: string },
+  deps: HubSelfProbeDeps<H> = {},
+): HubSelfProbe {
+  const { port, nonce, record } = args;
+  const intervalMs = deps.intervalMs ?? 300_000;
+  const probe = deps.probe ?? probeLoopbackInstance;
+  const log = deps.log ?? ((line: string) => console.error(line));
+  const now = deps.now ?? (() => new Date());
+  const writeState =
+    deps.writeState ??
+    ((state: SelfProbeState) =>
+      writeHubInstanceFile(
+        { ...record, selfProbe: state },
+        { ...(args.configDir !== undefined ? { configDir: args.configDir } : {}), log },
+      ));
+  const setIntervalFn =
+    deps.setIntervalFn ?? ((cb: () => void, ms: number) => setInterval(cb, ms) as unknown as H);
+  const clearIntervalFn =
+    deps.clearIntervalFn ??
+    ((h: H) => clearInterval(h as unknown as ReturnType<typeof setInterval>));
+
+  let last: SelfProbeState | undefined;
+  let inFlight = false;
+
+  async function probeOnce(): Promise<SelfProbeStatus> {
+    if (inFlight) return last?.status ?? "ok";
+    inFlight = true;
+    try {
+      const result = await probe(port);
+      const status = classifyLoopback(nonce, result);
+      const state: SelfProbeState = { status, checkedAt: now().toISOString() };
+      if (status === "hijacked") {
+        if (result.instance !== undefined) state.observedInstance = result.instance;
+        state.detail = hijackAlertMessage(port, result.instance);
+        // LOUD every tick — a hijack is a standing emergency, not a one-shot notice.
+        log(state.detail);
+      } else if (status === "unreachable") {
+        state.detail = unreachableNote(port);
+        if (last?.status !== "unreachable") log(state.detail);
+      } else {
+        // ok — announce recovery once when clearing a prior non-ok verdict.
+        if (last && last.status !== "ok") {
+          log(
+            `parachute serve: loopback /health on 127.0.0.1:${port} is back to this hub (instance=${nonce}). Hijack cleared.`,
+          );
+        }
+      }
+      last = state;
+      try {
+        writeState(state);
+      } catch {
+        // Persisting the verdict is best-effort; the loud log already fired.
+      }
+      return status;
+    } finally {
+      inFlight = false;
+    }
+  }
+
+  const handle = setIntervalFn(() => {
+    void probeOnce();
+  }, intervalMs);
+  (handle as { unref?: () => void }).unref?.();
+
+  return {
+    stop() {
+      clearIntervalFn(handle);
+    },
+    probeOnce,
+    getState() {
+      return last;
+    },
+  };
+}

package/src/hub-server.ts

@@ -782,6 +782,52 @@ export function wsCapBucketKey(req: Request, peerAddr: string | null): string {
   return peer ?? WS_CAP_SHARED_BUCKET;
 }
 
+/**
+ * Hop-by-hop headers (RFC 9110 §7.6.1) — connection-scoped, meaningful only
+ * on a single transport hop. An intermediary MUST NOT forward them, and the
+ * hub is exactly such an intermediary between the client and each loopback
+ * module.
+ *
+ * Forwarding a client's `Connection: close` verbatim was the P0 amplifier in
+ * the 2026-07-02 port exhaustion (hub#738): Bun's fetch honors the forwarded
+ * `Connection: close` and opens a FRESH ephemeral socket per proxied request
+ * instead of reusing its per-origin keep-alive pool. A hot client loop then
+ * converts request volume 1:1 into 30s TIME_WAIT entries (macOS: ~16k
+ * ephemeral ports), exhausting the range and taking out all host outbound.
+ * With these stripped, Bun reuses a handful of pooled sockets to each 127.0.0.1
+ * upstream regardless of what the client sends.
+ */
+const HOP_BY_HOP_HEADERS = [
+  "connection",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "te",
+  "trailer",
+  "transfer-encoding",
+  "upgrade",
+] as const;
+
+/**
+ * Delete hop-by-hop headers from an outgoing proxy header bag (mutates in
+ * place). The `Connection` field-value can NAME further headers to drop
+ * (RFC 9110 §7.6.1 — e.g. `Connection: close, X-Custom`), so those tokens are
+ * collected and deleted before the standard set. WebSocket upgrades never
+ * reach the fetch-based proxy (the Bun-native bridge handles them before
+ * dispatch — see `proxyRequest`'s docstring), so dropping `Upgrade`/`Connection`
+ * here only ever touches non-declaring mounts, which see a plain request.
+ */
+export function stripHopByHopHeaders(headers: Headers): void {
+  const connectionValue = headers.get("connection");
+  if (connectionValue) {
+    for (const token of connectionValue.split(",")) {
+      const named = token.trim().toLowerCase();
+      if (named) headers.delete(named);
+    }
+  }
+  for (const name of HOP_BY_HOP_HEADERS) headers.delete(name);
+}
+
 /**
  * Forward a request to a loopback service on `127.0.0.1:<port>`. By default
  * the incoming pathname + query are preserved verbatim; pass `targetPath` to
@@ -847,6 +893,12 @@ async function proxyRequest(
   // Host comes from the requester (tailnet FQDN); the loopback target wants
   // its own. Bun's fetch fills it in when omitted.
   headers.delete("host");
+  // Strip hop-by-hop headers before forwarding (RFC 9110 §7.6.1). Critically
+  // this drops a client-supplied `Connection: close`, which Bun's fetch would
+  // otherwise honor by disabling keep-alive and burning a fresh ephemeral
+  // socket per request — the P0 amplifier in hub#738. Bun refills the
+  // connection framing for the upstream hop itself.
+  stripHopByHopHeaders(headers);
   // Force upstreams to reply with uncompressed bodies. The chrome-strip
   // injector (workstream G) buffers + TextDecoders the HTML response to
   // inject the persistent chrome; without this, a gzip- or br-compressed
@@ -887,6 +939,13 @@ async function proxyRequest(
     method: req.method,
     headers,
     redirect: "manual",
+    // Forward the incoming request's abort signal to the upstream hop. When a
+    // client hangs up mid-response, this aborts the loopback fetch so the
+    // upstream stops streaming to a gone client and its socket is released
+    // back to the pool (or closed) instead of running the full body out and
+    // holding the connection — a secondary socket-retention leak alongside the
+    // TIME_WAIT churn (hub#738). `req.signal` is present on Bun.serve requests.
+    signal: req.signal,
   };
   if (req.method !== "GET" && req.method !== "HEAD") {
     init.body = req.body;
@@ -895,6 +954,14 @@ async function proxyRequest(
   try {
     return await fetch(upstream, init);
   } catch (err) {
+    // Client hung up mid-flight: the upstream fetch was aborted via req.signal
+    // (forwarded above), not an upstream failure. The client is gone, so the
+    // response is discarded — don't run the boot-readiness classifier or
+    // render a "module unreachable" page that would misclassify a normal
+    // disconnect. 499 = client closed request (nginx convention).
+    if (req.signal?.aborted) {
+      return new Response(null, { status: 499 });
+    }
     const msg = err instanceof Error ? err.message : String(err);
     // Classify the failure (transient boot-window vs persistent crash) and
     // render either an HTML page or a JSON error per the request's Accept.
@@ -1261,6 +1328,17 @@ export interface HubFetchDeps {
    * rejected" because Origin ≠ tailnet issuer).
    */
   loopbackPort?: number;
+  /**
+   * This serve process's per-boot instance nonce (hub#737). When present it's
+   * echoed as `instance` in `/health` so an external reader can tell whether a
+   * loopback `/health` actually reached THIS hub or a foreign process that has
+   * shadowed the port (the OrbStack loopback-hijack class). `serve` mints it,
+   * writes it to `~/.parachute/hub-instance.json`, and threads it here; absent
+   * on the DB-less / test / `bun src/hub-server.ts` paths, where `/health`
+   * simply omits the field (additive — no consumer parses `/health` for
+   * `instance` strictly).
+   */
+  instanceNonce?: string;
   /**
    * Test seam for reading `expose-state.json`'s `hubOrigin`. Production reads
    * the operator's `~/.parachute/expose-state.json` via `readExposeState`;
@@ -1341,7 +1419,7 @@ async function loadManagementUrls(
  * earlier "vaults browse via Notes — no tile" rule retired with PR 1 of
  * workstream C; operators administer per-vault tokens / config / MCP via
  * the vault admin SPA, which is a different audience from Notes' content
- * browse. See [`module-ui-declaration.md` §"Use vs admin"](https://github.com/ParachuteComputer/parachute-patterns/blob/main/patterns/module-ui-declaration.md#use-vs-admin--both-can-be-true).
+ * browse. See [`module-ui-declaration.md` §"Use vs admin"](https://github.com/ParachuteComputer/parachute-hub/blob/main/docs/contracts/module-ui-declaration.md#use-vs-admin--both-can-be-true).
  *
  * `loadManagementUrls` continues to handle vault's `managementUrl` for
  * the hub admin SPA's vault-list "Manage" link — a different surface
@@ -2314,7 +2392,17 @@ export function hubFetch(
           }
         }
         return new Response(
-          JSON.stringify({ status: "ok", service: "parachute-hub", version: pkg.version, db }),
+          JSON.stringify({
+            status: "ok",
+            service: "parachute-hub",
+            version: pkg.version,
+            db,
+            // Per-boot instance nonce (hub#737): lets an external reader detect a
+            // loopback hijack (foreign process shadowing 127.0.0.1:<port>) by
+            // comparing this to the nonce serve wrote to hub-instance.json.
+            // Omitted when unset (DB-less / test / dev-entrypoint paths).
+            ...(deps?.instanceNonce ? { instance: deps.instanceNonce } : {}),
+          }),
           {
             headers: {
               "content-type": "application/json",

package/src/hub.ts

@@ -484,7 +484,7 @@ const DISCOVERY_SCRIPT = `<script>
   // The previous SERVICE_LABELS / SERVICE_ORDER / isVaultName hardcoding
   // is retired: vault has no uiUrl, so the "skip vault" rule emerges
   // from data rather than a name check; ordering is alphabetical-by-
-  // displayName per the module-json-extensibility pattern doc.
+  // displayName per docs/contracts/module-json-extensibility.md.
 
   // Admin entries: always visible. Even a fresh hub with zero vaults wants
   // the operator to find /admin/vaults. Hardcoded — they live in the
@@ -617,7 +617,7 @@ const DISCOVERY_SCRIPT = `<script>
       });
     }
 
-    // Alphabetical-by-displayName per the module-json-extensibility pattern.
+    // Alphabetical-by-displayName per docs/contracts/module-json-extensibility.md.
     // Stable for shared-prefix labels (Notes, Notes-Lite would sort that way).
     const tiles = Array.from(byShort.values()).sort((a, b) =>
       a.title.localeCompare(b.title),
@@ -630,7 +630,7 @@ const DISCOVERY_SCRIPT = `<script>
       empty.innerHTML =
         'No services with a UI declared yet. Modules surface their UIs by ' +
         'declaring <code>uiUrl</code> in <code>module.json</code> ' +
-        '(see the module-json-extensibility pattern).';
+        '(see parachute-hub/docs/contracts/module-json-extensibility.md).';
       servicesGrid.appendChild(empty);
       return;
     }

package/src/module-manifest.ts

@@ -3,7 +3,7 @@
  * module. Author-controlled, shipped in the published artifact, read by the
  * CLI on `parachute install <package>`.
  *
- * The shape mirrors `parachute-patterns/patterns/module-json-extensibility.md`.
+ * The shape mirrors `docs/contracts/module-json-extensibility.md`.
  * Third-party modules are first-class: no `@openparachute/` scope or
  * `parachute-*` prefix required — `module.json` is what makes a package a
  * module. First-party modules will eventually ship their own `module.json`
@@ -271,7 +271,7 @@ export interface ModuleManifest {
   readonly configSchema?: ConfigSchema;
   /**
    * Where the module's admin UI lives. Hub renders a "Manage" link when set
-   * (see `parachute-patterns/patterns/module-json-extensibility.md`).
+   * (see `docs/contracts/module-json-extensibility.md`).
    *
    * Three shapes (unified URL-resolution semantics — B4 of the 2026-06-09
    * hub-module-boundary migration):
@@ -293,7 +293,7 @@ export interface ModuleManifest {
   /**
    * Where the module's primary user-facing UI lives. Hub renders a tile on
    * the discovery page (`/`) Services section when set (see
-   * `parachute-patterns/patterns/module-json-extensibility.md` and the
+   * `docs/contracts/module-json-extensibility.md` and the
    * `loadUiUrls` resolver in `hub-server.ts`).
    *
    * Two shapes — same rules as `managementUrl`:

package/src/resource-binding.ts

@@ -25,7 +25,7 @@
  * vault's named scopes, lock the picker to `<name>`, and mint named scopes so
  * `inferAudience` stamps `aud=vault.<name>`.
  *
- * Source of truth for scope shape: `parachute-patterns/patterns/oauth-scopes.md`.
+ * Source of truth for scope shape: `docs/contracts/oauth-scopes.md`.
  */
 
 import { VAULT_VERBS } from "./jwt-audience.ts";

package/src/scope-explanations.ts

@@ -18,7 +18,7 @@
  * hardcoded here.
  *
  * Source of truth for the scope shape:
- * `parachute-patterns/patterns/oauth-scopes.md`.
+ * `docs/contracts/oauth-scopes.md`.
  */
 
 export interface ScopeExplanation {

package/src/scope-registry.ts

@@ -7,7 +7,7 @@
  * downstream service should be rejected, but defense-in-depth says don't
  * sign claims you don't understand. This module is the gate.
  *
- * Source of truth for scope shape: `parachute-patterns/patterns/oauth-scopes.md`.
+ * Source of truth for scope shape: `docs/contracts/oauth-scopes.md`.
  *
  * Declared scopes come from two places:
  *   1. `FIRST_PARTY_SCOPES` — the canonical Parachute scopes hardcoded in

package/src/services-manifest.ts

@@ -25,8 +25,8 @@ export type PublicExposure = "allowed" | "loopback" | "auth-required";
 
 /**
  * Visible-to-discovery state of a UI sub-unit. Aligns with the four-state
- * supervisor vocabulary in [parachute-patterns/patterns/design-system.md
- * §6](../parachute-patterns/patterns/design-system.md) (workstream F).
+ * supervisor vocabulary in [docs/contracts/design-system.md
+ * §6](../docs/contracts/design-system.md) (workstream F).
  * Absent → hub treats the sub-unit as "active" (the discovery default).
  *
  *   "active"   — UI is installed, OAuth client is approved, ready to serve.
@@ -827,7 +827,7 @@ function dropLegacyShortNameRows(raw: unknown, where: string): { raw: unknown; c
   });
 
   console.error(
-    `${where}: dropped legacy short-name row(s) [${dropped.join(", ")}] in favor of same-port manifestName row(s). This is the parachute-app#13 / parachute-runner#4 self-register fixup. See parachute-patterns/patterns/services-json-row-conventions.md.`,
+    `${where}: dropped legacy short-name row(s) [${dropped.join(", ")}] in favor of same-port manifestName row(s). This is the parachute-app#13 / parachute-runner#4 self-register fixup. See parachute-hub/docs/contracts/services-json-row-conventions.md.`,
   );
 
   return {

package/src/well-known.ts

@@ -47,7 +47,7 @@ export interface WellKnownVaultEntry {
   version: string;
   /**
    * Where the vault's admin SPA lives. Path-or-URL per
-   * `parachute-patterns/patterns/module-json-extensibility.md`. Hub renders
+   * `docs/contracts/module-json-extensibility.md`. Hub renders
    * a "Manage" link when present. Sourced from the vault module's
    * `.parachute/module.json:managementUrl`.
    */