@openparachute/hub 0.7.3-rc.7 → 0.7.3-rc.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.7.3-rc.7",
+  "version": "0.7.3-rc.9",
   "description": "parachute — the local hub for the Parachute ecosystem (discovery, ports, lifecycle, soon OAuth).",
   "license": "AGPL-3.0",
   "publishConfig": {

package/src/__tests__/hub-origins-env-set.test.ts

@@ -0,0 +1,199 @@
+/**
+ * Multi-origin iss-set (onboarding-streamline 2026-06-25) — hub side.
+ *
+ * The hub publishes the SET of origins it legitimately answers on to its
+ * supervised resource servers via `PARACHUTE_HUB_ORIGINS` (comma-separated),
+ * alongside the single canonical `PARACHUTE_HUB_ORIGIN`. A resource server on
+ * scope-guard ≥0.5.0 widens its accepted-`iss` check to this set so a token
+ * minted under one URL of a multi-URL box validates via another URL of the
+ * SAME box.
+ *
+ * These tests pin two things:
+ *   1. The serialize/parse round-trip + the assembly from hub-controlled
+ *      inputs (issuer ∪ loopback aliases ∪ expose-state ∪ platform).
+ *   2. The SECURITY INVARIANT: the set is built ONLY from operator/hub config
+ *      and on-disk state — never from an unvalidated request `Host` /
+ *      `X-Forwarded-Host`. We feed an attacker-controlled "Host" through every
+ *      input channel a request could plausibly reach and assert it never lands
+ *      in the published set.
+ */
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { parseHubOrigins, serializeHubOrigins } from "../hub-origin.ts";
+import { buildHubOriginsEnvValue } from "../vault-hub-origin-env.ts";
+
+describe("serializeHubOrigins / parseHubOrigins round-trip", () => {
+  test("serialize dedupes, drops empties, strips trailing slashes", () => {
+    const v = serializeHubOrigins([
+      "https://a.example/",
+      "https://a.example",
+      "",
+      "https://b.example",
+    ]);
+    expect(v).toBe("https://a.example,https://b.example");
+  });
+
+  test("serialize returns undefined when nothing survives", () => {
+    expect(serializeHubOrigins([])).toBeUndefined();
+    expect(serializeHubOrigins(["", "  "])).toBeUndefined();
+  });
+
+  test("parse is the inverse — tolerant of whitespace + trailing slashes + empties", () => {
+    expect(parseHubOrigins("https://a.example, https://b.example/ ,,")).toEqual([
+      "https://a.example",
+      "https://b.example",
+    ]);
+  });
+
+  test("parse returns [] for absent/empty/garbage", () => {
+    expect(parseHubOrigins(undefined)).toEqual([]);
+    expect(parseHubOrigins("")).toEqual([]);
+    expect(parseHubOrigins(" , , ")).toEqual([]);
+  });
+
+  test("round-trips a real set", () => {
+    const origins = ["https://example.com", "http://127.0.0.1:1939", "http://localhost:1939"];
+    const wire = serializeHubOrigins(origins)!;
+    expect(parseHubOrigins(wire)).toEqual(origins);
+  });
+});
+
+describe("buildHubOriginsEnvValue — assembles the hub's legitimate-origin set", () => {
+  let dir: string;
+  const EXPOSE = () => join(dir, "expose-state.json");
+
+  /** Write a schema-valid expose-state.json carrying the given hubOrigin. */
+  function writeExposeState(hubOrigin: string): void {
+    writeFileSync(
+      EXPOSE(),
+      JSON.stringify({
+        version: 1,
+        layer: "public",
+        mode: "path",
+        canonicalFqdn: new URL(hubOrigin).host,
+        port: 1939,
+        funnel: true,
+        entries: [],
+        hubOrigin,
+      }),
+    );
+  }
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "hub-origins-set-"));
+    // No hub.port file in this fresh configDir → readHubPort falls back to
+    // HUB_UNIT_DEFAULT_PORT (1939), the deterministic value these cases assert.
+  });
+  afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+  test("issuer ∪ loopback aliases when no expose / platform origin", () => {
+    const v = buildHubOriginsEnvValue(dir, "https://example.com", {}, EXPOSE());
+    const set = parseHubOrigins(v);
+    expect(set).toContain("https://example.com");
+    expect(set).toContain("http://127.0.0.1:1939");
+    expect(set).toContain("http://localhost:1939");
+    expect(set).toHaveLength(3);
+  });
+
+  test("loopback aliases are ALWAYS present (the always-present invariant)", () => {
+    // Even with a public issuer, loopback must be in the set so the co-located
+    // CLI / loopback-proxied request path validates.
+    const set = parseHubOrigins(buildHubOriginsEnvValue(dir, "https://example.com", {}, EXPOSE()));
+    expect(set).toContain("http://127.0.0.1:1939");
+    expect(set).toContain("http://localhost:1939");
+  });
+
+  test("folds in the expose-state public origin", () => {
+    writeExposeState("https://box.sslip.io");
+    const set = parseHubOrigins(buildHubOriginsEnvValue(dir, "https://example.com", {}, EXPOSE()));
+    expect(set).toContain("https://example.com");
+    expect(set).toContain("https://box.sslip.io");
+  });
+
+  test("folds in the platform origin (RENDER_EXTERNAL_URL)", () => {
+    const set = parseHubOrigins(
+      buildHubOriginsEnvValue(
+        dir,
+        "https://example.com",
+        { RENDER_EXTERNAL_URL: "https://app.onrender.com" },
+        EXPOSE(),
+      ),
+    );
+    expect(set).toContain("https://app.onrender.com");
+  });
+
+  test("folds in the composed Fly default origin", () => {
+    const set = parseHubOrigins(
+      buildHubOriginsEnvValue(dir, "https://example.com", { FLY_APP_NAME: "myapp" }, EXPOSE()),
+    );
+    expect(set).toContain("https://myapp.fly.dev");
+  });
+
+  test("absent issuer → loopback-only set (still useful, never empty on a normal box)", () => {
+    const set = parseHubOrigins(buildHubOriginsEnvValue(dir, undefined, {}, EXPOSE()));
+    expect(set).toContain("http://127.0.0.1:1939");
+    expect(set).toContain("http://localhost:1939");
+    // The empty issuer "" is dropped by buildHubBoundOrigins' URL parse.
+    expect(set).not.toContain("");
+  });
+
+  test("a malformed expose-state.json never throws — falls back to issuer + loopback", () => {
+    writeFileSync(EXPOSE(), "{ not valid json");
+    const set = parseHubOrigins(buildHubOriginsEnvValue(dir, "https://example.com", {}, EXPOSE()));
+    expect(set).toContain("https://example.com");
+    expect(set).toContain("http://127.0.0.1:1939");
+  });
+
+  describe("SECURITY INVARIANT — request Host never enters the set", () => {
+    const ATTACKER = "https://attacker.evil";
+
+    test("an attacker Host smuggled via expose-state IS honored ONLY because it's operator-written on-disk state — but a Host passed nowhere never appears", () => {
+      // There is NO request input to buildHubOriginsEnvValue at all — it takes
+      // configDir + issuer + env + expose-state-path. None of those is a
+      // request header. We assert the function's surface offers no channel for
+      // a request Host: feeding the attacker value to the only inputs an
+      // attacker might influence (a stray env var, a header-shaped string)
+      // never reaches the set unless it's a legitimate operator-config var.
+      const set = parseHubOrigins(
+        buildHubOriginsEnvValue(
+          dir,
+          "https://example.com",
+          {
+            // Header-shaped env vars an attacker might hope are read — none are
+            // consulted by the assembler (only RENDER_EXTERNAL_URL / FLY_APP_NAME).
+            HTTP_HOST: ATTACKER,
+            HTTP_X_FORWARDED_HOST: ATTACKER,
+            X_FORWARDED_HOST: ATTACKER,
+            HOST: ATTACKER,
+          } as NodeJS.ProcessEnv,
+          EXPOSE(),
+        ),
+      );
+      expect(set).not.toContain(ATTACKER);
+      expect(set.some((o) => o.includes("attacker"))).toBe(false);
+    });
+
+    test("the set is exactly issuer ∪ loopback ∪ expose ∪ platform — no other source", () => {
+      writeExposeState("https://box.sslip.io");
+      const set = parseHubOrigins(
+        buildHubOriginsEnvValue(
+          dir,
+          "https://example.com",
+          { RENDER_EXTERNAL_URL: "https://app.onrender.com" },
+          EXPOSE(),
+        ),
+      );
+      // Every member is one of the four sanctioned sources; nothing else.
+      const sanctioned = new Set([
+        "https://example.com",
+        "http://127.0.0.1:1939",
+        "http://localhost:1939",
+        "https://box.sslip.io",
+        "https://app.onrender.com",
+      ]);
+      for (const o of set) expect(sanctioned.has(o)).toBe(true);
+    });
+  });
+});

package/src/__tests__/scribe-config.test.ts

@@ -3,10 +3,15 @@ import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "nod
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import {
+  MIN_RAM_MIB,
   SCRIBE_DEFAULT_PROVIDER,
   SCRIBE_PROVIDERS,
   apiKeyEnvFor,
+  clearScribeProvider,
+  decideLocalProvider,
   isKnownScribeProvider,
+  platformLocalProvider,
+  readAvailableRamMib,
   readScribeProviderState,
   scribeConfigPath,
   scribeEnvPath,
@@ -41,6 +46,118 @@ describe("provider catalog", () => {
   });
 });
 
+describe("platformLocalProvider — the Linux 'local' trap fix", () => {
+  test("macOS → parakeet-mlx", () => {
+    expect(platformLocalProvider("darwin")).toBe("parakeet-mlx");
+  });
+
+  test("Linux → onnx-asr (NOT the macOS-only parakeet-mlx)", () => {
+    expect(platformLocalProvider("linux")).toBe("onnx-asr");
+  });
+
+  test("unsupported platform → null (steer to cloud)", () => {
+    expect(platformLocalProvider("win32")).toBeNull();
+  });
+});
+
+describe("readAvailableRamMib", () => {
+  test("non-Linux returns a positive number (totalmem fallback) or null", () => {
+    const ram = readAvailableRamMib("darwin");
+    // On any real CI/dev box totalmem is well-defined + positive.
+    expect(ram === null || (typeof ram === "number" && ram > 0)).toBe(true);
+  });
+
+  test("Linux path reads /proc/meminfo (or null when unreadable)", () => {
+    const ram = readAvailableRamMib("linux");
+    // On macOS CI there's no /proc/meminfo → null; on Linux CI a positive MiB.
+    expect(ram === null || (typeof ram === "number" && ram > 0)).toBe(true);
+  });
+});
+
+describe("decideLocalProvider — the RAM/platform gate", () => {
+  test("Linux with ample RAM → ok, onnx-asr", () => {
+    const d = decideLocalProvider("linux", 4096);
+    expect(d.ok).toBe(true);
+    expect(d.provider).toBe("onnx-asr");
+  });
+
+  test("macOS with ample RAM → ok, parakeet-mlx", () => {
+    const d = decideLocalProvider("darwin", 16384);
+    expect(d.ok).toBe(true);
+    expect(d.provider).toBe("parakeet-mlx");
+  });
+
+  test("below the RAM floor → refused, steers to groq, carries a reason", () => {
+    const d = decideLocalProvider("linux", MIN_RAM_MIB - 1);
+    expect(d.ok).toBe(false);
+    expect(d.steerTo).toBe("groq");
+    expect(d.reason).toContain(String(MIN_RAM_MIB));
+  });
+
+  test("exactly at the floor is OK (>= floor)", () => {
+    expect(decideLocalProvider("linux", MIN_RAM_MIB).ok).toBe(true);
+  });
+
+  test("unknown RAM (null) does not refuse on a supported platform", () => {
+    expect(decideLocalProvider("linux", null).ok).toBe(true);
+  });
+
+  test("unsupported platform → refused regardless of RAM, steers to groq", () => {
+    const d = decideLocalProvider("win32", 99999);
+    expect(d.ok).toBe(false);
+    expect(d.steerTo).toBe("groq");
+  });
+});
+
+describe("clearScribeProvider", () => {
+  test("removes transcribe.provider, preserving other keys", () => {
+    const h = makeHarness();
+    try {
+      mkdirSync(join(h.dir, "scribe"), { recursive: true });
+      writeFileSync(
+        scribeConfigPath(h.dir),
+        JSON.stringify({
+          transcribe: { provider: "onnx-asr", language: "en" },
+          auth: { required_token: "keep" },
+        }),
+      );
+      clearScribeProvider(h.dir);
+      const parsed = JSON.parse(readFileSync(scribeConfigPath(h.dir), "utf8"));
+      expect(parsed.transcribe).toEqual({ language: "en" });
+      expect(parsed.auth).toEqual({ required_token: "keep" });
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("drops the transcribe block entirely when provider was its only key", () => {
+    const h = makeHarness();
+    try {
+      mkdirSync(join(h.dir, "scribe"), { recursive: true });
+      writeFileSync(
+        scribeConfigPath(h.dir),
+        JSON.stringify({ transcribe: { provider: "onnx-asr" }, auth: { required_token: "x" } }),
+      );
+      clearScribeProvider(h.dir);
+      const parsed = JSON.parse(readFileSync(scribeConfigPath(h.dir), "utf8"));
+      expect(parsed.transcribe).toBeUndefined();
+      expect(parsed.auth).toEqual({ required_token: "x" });
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("no-op when the file is absent", () => {
+    const h = makeHarness();
+    try {
+      // No file written.
+      expect(() => clearScribeProvider(h.dir)).not.toThrow();
+    } finally {
+      h.cleanup();
+    }
+  });
+});
+
 describe("readScribeProviderState", () => {
   test("missing file: configExists false, no provider", () => {
     const h = makeHarness();

package/src/__tests__/serve-boot.test.ts

@@ -125,6 +125,51 @@ describe("bootSupervisedModules", () => {
     expect(recorder.calls[0]?.env?.PARACHUTE_HUB_ORIGIN).toBe("https://hub.example");
   });
 
+  test("forwards PARACHUTE_HUB_ORIGINS (the multi-origin iss-set) alongside the single origin", async () => {
+    // Multi-origin iss-set (onboarding-streamline 2026-06-25): a resource
+    // server on scope-guard ≥0.5.0 widens its accepted-`iss` check to this set
+    // so a token minted under one URL of a multi-URL box validates via another.
+    // The set always carries the issuer + loopback aliases (the deterministic
+    // members); expose-state / platform members vary by box.
+    writeManifest({ services: [VAULT_ENTRY] }, h.manifestPath);
+    const recorder = makeRecorder();
+    const sup = new Supervisor({ spawnFn: recorder.spawn });
+
+    await bootSupervisedModules(sup, {
+      manifestPath: h.manifestPath,
+      configDir: h.dir,
+      hubOrigin: "https://hub.example",
+    });
+
+    const origins = recorder.calls[0]?.env?.PARACHUTE_HUB_ORIGINS;
+    expect(origins).toBeDefined();
+    const set = (origins ?? "").split(",");
+    expect(set).toContain("https://hub.example");
+    // SECURITY: the set is hub-controlled (issuer + loopback + expose +
+    // platform) — never a request Host. Loopback aliases are always present.
+    expect(set.some((o) => o.startsWith("http://127.0.0.1:"))).toBe(true);
+    expect(set.some((o) => o.startsWith("http://localhost:"))).toBe(true);
+    // And the single canonical origin is still written for back-compat.
+    expect(recorder.calls[0]?.env?.PARACHUTE_HUB_ORIGIN).toBe("https://hub.example");
+  });
+
+  test("no PARACHUTE_HUB_ORIGINS when hubOrigin is unset (no widening, single-origin only)", async () => {
+    // Back-compat: a boot with no hubOrigin neither sets PARACHUTE_HUB_ORIGIN
+    // nor the set — the child keeps its own loopback default + scope-guard's
+    // single-origin behavior.
+    writeManifest({ services: [VAULT_ENTRY] }, h.manifestPath);
+    const recorder = makeRecorder();
+    const sup = new Supervisor({ spawnFn: recorder.spawn });
+
+    await bootSupervisedModules(sup, {
+      manifestPath: h.manifestPath,
+      configDir: h.dir,
+    });
+
+    expect(recorder.calls[0]?.env?.PARACHUTE_HUB_ORIGIN).toBeUndefined();
+    expect(recorder.calls[0]?.env?.PARACHUTE_HUB_ORIGINS).toBeUndefined();
+  });
+
   test("sets PORT in child env from services.json entry (hub#357)", async () => {
     // Container deploys (Render etc.) set PORT in hub's process.env via
     // Dockerfile / platform injection. The supervisor's defaultSpawnFn

package/src/__tests__/setup-wizard.test.ts

@@ -1825,6 +1825,24 @@ describe("handleSetupVaultPost", () => {
     expect(cfg?.cleanup).toEqual({ provider: "anthropic", default: true });
     expect(cfg?.cleanupProviders).toEqual({ anthropic: { apiKey: "sk-ant-cleanup-key" } });
   });
+
+  test("scribe transcribe=local resolves to the host platform's backend (the Linux trap fix)", async () => {
+    // The bug: `local` mapped UNCONDITIONALLY to parakeet-mlx (macOS-only),
+    // silently broken on every Linux box. After the fix it resolves to the
+    // platform backend. We assert against the actual host so it's correct on
+    // both Mac (parakeet-mlx) and Linux CI (onnx-asr). The RAM gate only kicks
+    // in below 2 GB — CI/dev boxes clear it, so the choice stays `local`.
+    const { platformLocalProvider } = await import("../scribe-config.ts");
+    const expected = platformLocalProvider(process.platform);
+    const { response } = await postVaultWithFields(h, { scribe_provider: "local" });
+    expect(response.status).toBe(303);
+    const cfg = readScribeConfig(h.dir);
+    if (expected !== null) {
+      // On a supported platform with enough RAM, `local` resolves to the
+      // platform backend — NOT a hardcoded parakeet-mlx on Linux.
+      expect(cfg?.transcribe).toEqual({ provider: expected });
+    }
+  });
 });
 
 // --- end-to-end through hubFetch -----------------------------------------

package/src/__tests__/vault-hub-origin-env.test.ts

@@ -76,13 +76,29 @@ describe("persistVaultHubOrigin", () => {
     expect(existsSync(vaultEnv())).toBe(false);
   });
 
-  test("is idempotent — no rewrite when the value is already current", () => {
+  test("is idempotent — no rewrite when both the origin and the set are current", () => {
     const log: string[] = [];
     expect(persistVaultHubOrigin(dir, "https://hub.example.com", (l) => log.push(l))).toBe(true);
+    // First call wrote BOTH the single origin and the multi-origin set.
+    expect(
+      log.some((l) => /persisted PARACHUTE_HUB_ORIGIN=https:\/\/hub\.example\.com/.test(l)),
+    ).toBe(true);
+    expect(log.some((l) => /persisted PARACHUTE_HUB_ORIGINS=/.test(l))).toBe(true);
+    const writesAfterFirst = log.length;
+    // Second call is a no-op: both values already current → false, no new logs.
     expect(persistVaultHubOrigin(dir, "https://hub.example.com", (l) => log.push(l))).toBe(false);
-    // Only the first call logged.
-    expect(log).toHaveLength(1);
-    expect(log[0]).toMatch(/persisted PARACHUTE_HUB_ORIGIN=https:\/\/hub\.example\.com/);
+    expect(log).toHaveLength(writesAfterFirst);
+  });
+
+  test("writes PARACHUTE_HUB_ORIGINS (multi-origin iss-set) alongside the single origin", () => {
+    expect(persistVaultHubOrigin(dir, "https://hub.example.com", () => {})).toBe(true);
+    const values = readEnvFileValues(vaultEnv());
+    expect(values.PARACHUTE_HUB_ORIGIN).toBe("https://hub.example.com");
+    // The set carries the issuer + loopback aliases (always present).
+    const set = (values.PARACHUTE_HUB_ORIGINS ?? "").split(",");
+    expect(set).toContain("https://hub.example.com");
+    expect(set.some((o) => o.startsWith("http://127.0.0.1:"))).toBe(true);
+    expect(set.some((o) => o.startsWith("http://localhost:"))).toBe(true);
   });
 
   test("updates a stale origin in-place and preserves sibling keys", () => {
@@ -113,6 +129,24 @@ describe("clearVaultHubOrigin", () => {
     expect(values.SCRIBE_AUTH_TOKEN).toBe("secret");
   });
 
+  test("removes BOTH the single origin and the multi-origin set, leaving siblings", () => {
+    writeFileSync(
+      mkVaultDir(),
+      "SCRIBE_AUTH_TOKEN=secret\nPARACHUTE_HUB_ORIGIN=https://hub.example.com\nPARACHUTE_HUB_ORIGINS=https://hub.example.com,http://127.0.0.1:1939\n",
+    );
+    expect(clearVaultHubOrigin(dir, () => {})).toBe(true);
+    const values = readEnvFileValues(vaultEnv());
+    expect(values.PARACHUTE_HUB_ORIGIN).toBeUndefined();
+    expect(values.PARACHUTE_HUB_ORIGINS).toBeUndefined();
+    expect(values.SCRIBE_AUTH_TOKEN).toBe("secret");
+  });
+
+  test("clears a lone PARACHUTE_HUB_ORIGINS even if the single origin is absent", () => {
+    writeFileSync(mkVaultDir(), "PARACHUTE_HUB_ORIGINS=https://hub.example.com\n");
+    expect(clearVaultHubOrigin(dir, () => {})).toBe(true);
+    expect(readEnvFileValues(vaultEnv()).PARACHUTE_HUB_ORIGINS).toBeUndefined();
+  });
+
   test("no-op when no origin is present", () => {
     writeFileSync(mkVaultDir(), "SCRIBE_AUTH_TOKEN=secret\n");
     expect(clearVaultHubOrigin(dir, () => {})).toBe(false);