@openparachute/hub 0.5.14-rc.2 → 0.5.14-rc.21

package/src/__tests__/proxy-state.test.ts

@@ -0,0 +1,192 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { writePid } from "../process-state.ts";
+import { type ClassifyOpts, classifyUpstream } from "../proxy-state.ts";
+import type { ModuleState, Supervisor } from "../supervisor.ts";
+
+/**
+ * Stub supervisor — only `get(short)` is exercised by `classifyUpstream`.
+ * We construct it directly instead of standing up a real `Supervisor`
+ * + driving the spawn lifecycle, so test cases stay focused on the
+ * classifier's per-status branching.
+ */
+function stubSupervisor(states: Record<string, ModuleState>): Supervisor {
+  return {
+    get: (short: string) => states[short],
+    list: () => Object.values(states),
+    // Unused by classifyUpstream — present to satisfy the Supervisor type.
+    start: async () => {
+      throw new Error("not implemented");
+    },
+    stop: async () => undefined,
+    restart: async () => undefined,
+  } as unknown as Supervisor;
+}
+
+function moduleState(partial: Partial<ModuleState> & { short: string }): ModuleState {
+  return {
+    status: "running",
+    restartsInWindow: 0,
+    ...partial,
+  };
+}
+
+describe("classifyUpstream — supervisor mode", () => {
+  test("status=starting → transient", () => {
+    const sup = stubSupervisor({
+      vault: moduleState({ short: "vault", status: "starting" }),
+    });
+    expect(classifyUpstream("vault", { supervisor: sup })).toBe("transient");
+  });
+
+  test("status=restarting → transient", () => {
+    const sup = stubSupervisor({
+      vault: moduleState({ short: "vault", status: "restarting" }),
+    });
+    expect(classifyUpstream("vault", { supervisor: sup })).toBe("transient");
+  });
+
+  test("status=crashed → persistent", () => {
+    const sup = stubSupervisor({
+      vault: moduleState({ short: "vault", status: "crashed" }),
+    });
+    expect(classifyUpstream("vault", { supervisor: sup })).toBe("persistent");
+  });
+
+  test("status=stopped → persistent", () => {
+    const sup = stubSupervisor({
+      vault: moduleState({ short: "vault", status: "stopped" }),
+    });
+    expect(classifyUpstream("vault", { supervisor: sup })).toBe("persistent");
+  });
+
+  test("status=running, inside boot window → transient", () => {
+    const now = 1_700_000_000_000;
+    const startedAt = new Date(now - 10_000).toISOString(); // 10s ago
+    const sup = stubSupervisor({
+      vault: moduleState({ short: "vault", status: "running", startedAt }),
+    });
+    expect(classifyUpstream("vault", { supervisor: sup, now: () => now })).toBe("transient");
+  });
+
+  test("status=running, outside boot window → persistent", () => {
+    const now = 1_700_000_000_000;
+    const startedAt = new Date(now - 60_000).toISOString(); // 60s ago
+    const sup = stubSupervisor({
+      vault: moduleState({ short: "vault", status: "running", startedAt }),
+    });
+    expect(classifyUpstream("vault", { supervisor: sup, now: () => now })).toBe("persistent");
+  });
+
+  test("status=running, exactly at boot-window boundary → persistent", () => {
+    // The check is strict-less-than, so exactly 30s falls into persistent.
+    const now = 1_700_000_000_000;
+    const startedAt = new Date(now - 30_000).toISOString();
+    const sup = stubSupervisor({
+      vault: moduleState({ short: "vault", status: "running", startedAt }),
+    });
+    expect(classifyUpstream("vault", { supervisor: sup, now: () => now })).toBe("persistent");
+  });
+
+  test("status=running, missing startedAt → persistent", () => {
+    // Can't classify a running module without a start time; safer to call
+    // persistent and let the operator hit refresh than to lie that it's
+    // booting.
+    const sup = stubSupervisor({
+      vault: moduleState({ short: "vault", status: "running" }),
+    });
+    expect(classifyUpstream("vault", { supervisor: sup })).toBe("persistent");
+  });
+
+  test("custom boot window honored", () => {
+    const now = 1_700_000_000_000;
+    const startedAt = new Date(now - 5_000).toISOString(); // 5s ago
+    const sup = stubSupervisor({
+      vault: moduleState({ short: "vault", status: "running", startedAt }),
+    });
+    expect(
+      classifyUpstream("vault", { supervisor: sup, now: () => now, bootWindowMs: 2_000 }),
+    ).toBe("persistent");
+    expect(
+      classifyUpstream("vault", { supervisor: sup, now: () => now, bootWindowMs: 10_000 }),
+    ).toBe("transient");
+  });
+
+  test("module not tracked → falls back to pidfile path", () => {
+    // Empty supervisor map. Classifier must call through to processState;
+    // we inject a stub via readProcessState.
+    const sup = stubSupervisor({});
+    const opts: ClassifyOpts = {
+      supervisor: sup,
+      readProcessState: () => ({ status: "unknown" }),
+    };
+    expect(classifyUpstream("vault", opts)).toBe("persistent");
+  });
+});
+
+describe("classifyUpstream — on-box CLI mode (no supervisor)", () => {
+  test("running pidfile inside boot window → transient", () => {
+    const now = 1_700_000_000_000;
+    const opts: ClassifyOpts = {
+      now: () => now,
+      readProcessState: () => ({
+        status: "running",
+        pid: 12345,
+        startedAt: new Date(now - 5_000), // 5s old pidfile
+      }),
+    };
+    expect(classifyUpstream("vault", opts)).toBe("transient");
+  });
+
+  test("running pidfile outside boot window → persistent", () => {
+    const now = 1_700_000_000_000;
+    const opts: ClassifyOpts = {
+      now: () => now,
+      readProcessState: () => ({
+        status: "running",
+        pid: 12345,
+        startedAt: new Date(now - 60_000),
+      }),
+    };
+    expect(classifyUpstream("vault", opts)).toBe("persistent");
+  });
+
+  test("stopped pidfile (stale) → persistent", () => {
+    const opts: ClassifyOpts = {
+      readProcessState: () => ({ status: "stopped", pid: 12345 }),
+    };
+    expect(classifyUpstream("vault", opts)).toBe("persistent");
+  });
+
+  test("no pidfile (unknown) → persistent", () => {
+    const opts: ClassifyOpts = {
+      readProcessState: () => ({ status: "unknown" }),
+    };
+    expect(classifyUpstream("vault", opts)).toBe("persistent");
+  });
+
+  test("readProcessState throws → persistent (defensive)", () => {
+    // pidfile read can race with cleanup. Don't blow up the proxy.
+    const opts: ClassifyOpts = {
+      readProcessState: () => {
+        throw new Error("ENOENT");
+      },
+    };
+    expect(classifyUpstream("vault", opts)).toBe("persistent");
+  });
+
+  test("integration with real processState — running pid is alive + fresh mtime", () => {
+    // Write a real pidfile pointing at this test process (always alive),
+    // so `defaultAlive` returns true. Pidfile mtime will be ~now, so it
+    // falls inside the boot window.
+    const dir = mkdtempSync(join(tmpdir(), "proxy-state-"));
+    try {
+      writePid("vault", process.pid, dir);
+      expect(classifyUpstream("vault", { configDir: dir })).toBe("transient");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/__tests__/resource-binding.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, test } from "bun:test";
+import { narrowResourceVaultScopes, resolveResourceVault } from "../resource-binding.ts";
+
+const ORIGIN = "https://hub.example";
+const BOUND = [ORIGIN, "http://127.0.0.1:1939"];
+
+describe("resolveResourceVault", () => {
+  test("resolves a per-vault MCP resource to the vault name", () => {
+    expect(resolveResourceVault(`${ORIGIN}/vault/jon/mcp`, BOUND)).toBe("jon");
+  });
+
+  test("tolerates a trailing slash on the MCP path", () => {
+    expect(resolveResourceVault(`${ORIGIN}/vault/jon/mcp/`, BOUND)).toBe("jon");
+  });
+
+  test("ignores query string + fragment", () => {
+    expect(resolveResourceVault(`${ORIGIN}/vault/jon/mcp?x=1#y`, BOUND)).toBe("jon");
+  });
+
+  test("resolves the PRM document URL to the vault name", () => {
+    expect(
+      resolveResourceVault(`${ORIGIN}/vault/jon/.well-known/oauth-protected-resource`, BOUND),
+    ).toBe("jon");
+  });
+
+  test("resolves against a non-issuer bound origin (loopback)", () => {
+    expect(resolveResourceVault("http://127.0.0.1:1939/vault/work/mcp", BOUND)).toBe("work");
+  });
+
+  test("returns null for an off-origin resource (not one we front)", () => {
+    expect(resolveResourceVault("https://evil.example/vault/jon/mcp", BOUND)).toBeNull();
+  });
+
+  test("returns null for a non-vault path", () => {
+    expect(resolveResourceVault(`${ORIGIN}/scribe/mcp`, BOUND)).toBeNull();
+    expect(resolveResourceVault(`${ORIGIN}/vault/jon`, BOUND)).toBeNull();
+    expect(resolveResourceVault(`${ORIGIN}/vault/jon/notes`, BOUND)).toBeNull();
+  });
+
+  test("returns null for absent / empty / malformed resource", () => {
+    expect(resolveResourceVault(null, BOUND)).toBeNull();
+    expect(resolveResourceVault(undefined, BOUND)).toBeNull();
+    expect(resolveResourceVault("", BOUND)).toBeNull();
+    expect(resolveResourceVault("not a url", BOUND)).toBeNull();
+  });
+
+  test("does not collapse a deeper vault sub-path into the MCP shape", () => {
+    // `/vault/jon/mcp/extra` is not the canonical MCP endpoint.
+    expect(resolveResourceVault(`${ORIGIN}/vault/jon/mcp/extra`, BOUND)).toBeNull();
+  });
+
+  test("rejects a vault segment that isn't a well-formed vault name (no junk mint)", () => {
+    // A crafted `resource=…/vault/%2F..%2Fadmin/mcp` decodes to `/../admin`,
+    // which is not `[a-zA-Z0-9_-]+`. Returning null falls through to the
+    // unbound flow — no narrowing, no token stamped `aud=vault./../admin`.
+    expect(resolveResourceVault(`${ORIGIN}/vault/%2F..%2Fadmin/mcp`, BOUND)).toBeNull();
+    // Spaces / dots / slashes in the decoded name are all out of shape.
+    expect(resolveResourceVault(`${ORIGIN}/vault/a.b/mcp`, BOUND)).toBeNull();
+  });
+
+  test("returns null for a malformed percent-escape in the vault segment (safeDecode catch path)", () => {
+    // `%GG` is not a valid percent-escape — `decodeURIComponent` throws; the
+    // helper must degrade to null rather than 500 the authorize handler.
+    expect(resolveResourceVault(`${ORIGIN}/vault/%GG/mcp`, BOUND)).toBeNull();
+  });
+});
+
+describe("narrowResourceVaultScopes", () => {
+  test("narrows unnamed vault verbs to the named form", () => {
+    expect(narrowResourceVaultScopes(["vault:read", "vault:write"], "jon")).toEqual([
+      "vault:jon:read",
+      "vault:jon:write",
+    ]);
+  });
+
+  test("leaves already-named scopes for other vaults untouched", () => {
+    expect(narrowResourceVaultScopes(["vault:other:read"], "jon")).toEqual(["vault:other:read"]);
+  });
+
+  test("passes non-vault scopes through unchanged", () => {
+    expect(narrowResourceVaultScopes(["scribe:transcribe", "vault:read"], "jon")).toEqual([
+      "scribe:transcribe",
+      "vault:jon:read",
+    ]);
+  });
+
+  test("narrows the admin verb too (gate happens downstream)", () => {
+    // narrowResourceVaultScopes only rewrites shape; the non-requestable gate
+    // (`vault:<name>:admin`) blocks it afterward.
+    expect(narrowResourceVaultScopes(["vault:admin"], "jon")).toEqual(["vault:jon:admin"]);
+  });
+
+  test("is idempotent over an already-narrowed list", () => {
+    const once = narrowResourceVaultScopes(["vault:read"], "jon");
+    expect(narrowResourceVaultScopes(once, "jon")).toEqual(once);
+  });
+});

package/src/__tests__/scope-explanations.test.ts

@@ -5,6 +5,7 @@ import {
   SCOPE_EXPLANATIONS,
   explainScope,
   isRequestableScope,
+  isWellFormedOrNonVaultScope,
   scopeIsAdmin,
 } from "../scope-explanations.ts";
 
@@ -59,10 +60,18 @@ describe("explainScope", () => {
     expect(explainScope("vault:*:write")?.level).toBe("write");
   });
 
-  test("doesn't promote a per-vault admin (vault:<name>:admin) into an explained scope", () => {
-    // vault:<name>:admin is NON_REQUESTABLE — never appears on the consent
-    // screen. Explicitly not in the verb-pattern, so explainScope returns null.
-    expect(explainScope("vault:default:admin")).toBeNull();
+  // Single-consent change (2026-05-29): vault:<name>:admin is now REQUESTABLE
+  // and reaches the consent screen, so explainScope MUST resolve it to the
+  // vault:admin explanation (level "admin"). This is load-bearing: it makes
+  // scopeIsAdmin("vault:<name>:admin") return true, which the same-hub and
+  // trust-by-name auto-mint gates rely on to keep admin consent-gated.
+  test("resolves a per-vault admin (vault:<name>:admin) to the vault:admin explanation", () => {
+    expect(explainScope("vault:default:admin")?.label).toBe(
+      SCOPE_EXPLANATIONS["vault:admin"]?.label,
+    );
+    expect(explainScope("vault:default:admin")?.level).toBe("admin");
+    expect(explainScope("vault:my-techne_2:admin")?.level).toBe("admin");
+    expect(explainScope("vault:*:admin")?.level).toBe("admin");
   });
 });
 
@@ -73,6 +82,17 @@ describe("scopeIsAdmin", () => {
     expect(scopeIsAdmin("parachute:host:admin")).toBe(true);
   });
 
+  // Single-consent change (2026-05-29): the named per-vault admin form must
+  // be recognized as admin. LOAD-BEARING — the same-hub auto-trust gate
+  // (`!hasAdminScope`) and the trust-by-client_name gate
+  // (`!requestedScopes.some(scopeIsAdmin)`) rely on this to keep a named admin
+  // grant consent-gated instead of silently auto-minting it.
+  test("true for named per-vault admin (vault:<name>:admin)", () => {
+    expect(scopeIsAdmin("vault:work:admin")).toBe(true);
+    expect(scopeIsAdmin("vault:default:admin")).toBe(true);
+    expect(scopeIsAdmin("vault:my-techne_2:admin")).toBe(true);
+  });
+
   test("false for non-admin and unknown scopes", () => {
     expect(scopeIsAdmin("vault:read")).toBe(false);
     expect(scopeIsAdmin("channel:send")).toBe(false);
@@ -119,17 +139,62 @@ describe("isRequestableScope", () => {
     expect(isRequestableScope("notes:something-new")).toBe(true);
   });
 
-  // Per-vault admin scopes are pattern-matched as non-requestable so the
-  // public OAuth flow can never mint vault:<name>:admin — only the local
-  // session-cookie endpoint at /admin/vault-admin-token/<name> can.
-  test("false for any vault:<name>:admin scope", () => {
-    expect(isRequestableScope("vault:default:admin")).toBe(false);
-    expect(isRequestableScope("vault:work:admin")).toBe(false);
-    expect(isRequestableScope("vault:my-techne_2:admin")).toBe(false);
+  // Single-consent change (2026-05-29): per-vault admin scopes are now
+  // requestable via the public OAuth flow. The anti-privesc cap at the mint
+  // choke-point (`capScopesToUserAuthority`) keeps a non-owner from actually
+  // being granted admin — but the scope is no longer rejected up front, so
+  // Claude MCP (consenting as the owner) can mint a vault admin token.
+  test("true for any vault:<name>:admin scope (single-consent change)", () => {
+    expect(isRequestableScope("vault:default:admin")).toBe(true);
+    expect(isRequestableScope("vault:work:admin")).toBe(true);
+    expect(isRequestableScope("vault:my-techne_2:admin")).toBe(true);
+  });
+
+  test("host-level operator scopes stay non-requestable", () => {
+    // The asymmetry the single-consent change preserved: per-vault admin is
+    // now requestable (capped at mint), but host-wide operator authority is
+    // still operator-only-mintable.
+    expect(isRequestableScope("parachute:host:admin")).toBe(false);
+    expect(isRequestableScope("parachute:host:auth")).toBe(false);
   });
 
-  test("vault:<name>:read|write stays requestable (only :admin is locked down)", () => {
+  test("vault:<name>:read|write stays requestable", () => {
     expect(isRequestableScope("vault:default:read")).toBe(true);
     expect(isRequestableScope("vault:work:write")).toBe(true);
   });
 });
+
+// Mint-time shape guard (defensive hygiene, audit 2026-05-28). Rejects only the
+// *named* three-segment vault shape when malformed; leaves the unnamed two-
+// segment forms and all non-vault scopes alone.
+describe("isWellFormedOrNonVaultScope", () => {
+  test("rejects the four audited malformed named-vault forms", () => {
+    expect(isWellFormedOrNonVaultScope("vault:work:ADMIN")).toBe(false); // uppercase verb
+    expect(isWellFormedOrNonVaultScope("vault::admin")).toBe(false); // empty name
+    expect(isWellFormedOrNonVaultScope("vault:work:read:admin")).toBe(false); // extra segment
+    expect(isWellFormedOrNonVaultScope("VAULT:work:admin")).toBe(false); // uppercase resource
+  });
+
+  test("admits well-formed named-vault scopes (all three verbs)", () => {
+    expect(isWellFormedOrNonVaultScope("vault:work:read")).toBe(true);
+    expect(isWellFormedOrNonVaultScope("vault:work:write")).toBe(true);
+    expect(isWellFormedOrNonVaultScope("vault:work:admin")).toBe(true);
+    expect(isWellFormedOrNonVaultScope("vault:my-techne_2:admin")).toBe(true);
+  });
+
+  test("admits the unnamed two-segment vault forms (out of remit)", () => {
+    expect(isWellFormedOrNonVaultScope("vault:read")).toBe(true);
+    expect(isWellFormedOrNonVaultScope("vault:write")).toBe(true);
+    expect(isWellFormedOrNonVaultScope("vault:admin")).toBe(true);
+    expect(isWellFormedOrNonVaultScope("vault")).toBe(true); // bare, no colon
+  });
+
+  test("admits all non-vault scopes unconditionally", () => {
+    expect(isWellFormedOrNonVaultScope("scribe:transcribe")).toBe(true);
+    expect(isWellFormedOrNonVaultScope("parachute:host:auth")).toBe(true);
+    expect(isWellFormedOrNonVaultScope("parachute:host:admin")).toBe(true);
+    expect(isWellFormedOrNonVaultScope("hub:admin")).toBe(true);
+    // A three-segment non-vault scope is not constrained even if malformed-looking.
+    expect(isWellFormedOrNonVaultScope("scribe:work:ADMIN")).toBe(true);
+  });
+});

package/src/__tests__/services-manifest.test.ts

@@ -6,9 +6,11 @@ import {
   type ServiceEntry,
   ServicesManifestError,
   type UiSubUnit,
+  clearStartError,
   findService,
   readManifest,
   readManifestLenient,
+  recordStartError,
   removeService,
   upsertService,
   writeManifest,
@@ -1410,9 +1412,27 @@ describe("readManifestLenient — skips bad entries instead of throwing (hub#406
         path,
         JSON.stringify({
           services: [
-            { name: "parachute-vault", port: 1940, paths: ["/vault/default"], health: "/vault/default/health", version: "0.4.8-rc.10" },
-            { name: "parachute-surface", port: 1946, paths: ["/surface"], health: "/surface/healthz", version: "0.2.0-rc.13" },
-            { name: "widget", port: 0, paths: ["/widget"], health: "/widget/health", version: "0.0.1" },
+            {
+              name: "parachute-vault",
+              port: 1940,
+              paths: ["/vault/default"],
+              health: "/vault/default/health",
+              version: "0.4.8-rc.10",
+            },
+            {
+              name: "parachute-surface",
+              port: 1946,
+              paths: ["/surface"],
+              health: "/surface/healthz",
+              version: "0.2.0-rc.13",
+            },
+            {
+              name: "widget",
+              port: 0,
+              paths: ["/widget"],
+              health: "/widget/health",
+              version: "0.0.1",
+            },
           ],
         }),
       );
@@ -1479,7 +1499,15 @@ describe("readManifestLenient — skips bad entries instead of throwing (hub#406
       writeFileSync(
         path,
         JSON.stringify({
-          services: [{ name: "widget", port: 0, paths: ["/widget"], health: "/widget/health", version: "0.0.1" }],
+          services: [
+            {
+              name: "widget",
+              port: 0,
+              paths: ["/widget"],
+              health: "/widget/health",
+              version: "0.0.1",
+            },
+          ],
         }),
       );
       expect(() => readManifest(path)).toThrow(ServicesManifestError);
@@ -1487,4 +1515,94 @@ describe("readManifestLenient — skips bad entries instead of throwing (hub#406
       cleanup();
     }
   });
+
+  describe("lastStartError", () => {
+    const wire = {
+      error_type: "missing_dependency",
+      error_description: "parachute-vault is required ...",
+      binary: "parachute-vault",
+      why: "run the Vault module Hub supervises",
+      docs_url: "https://parachute.computer",
+      install: { generic: "parachute install vault" },
+      sysadmin_hint: "Or ask your system administrator to install it for you.",
+    };
+
+    test("recordStartError persists the wire + stamps `at`", () => {
+      const { path, cleanup } = makeTempPath();
+      try {
+        upsertService(vault, path);
+        recordStartError("parachute-vault", wire, path);
+        const entry = readManifest(path).services.find((s) => s.name === "parachute-vault");
+        expect(entry?.lastStartError?.error_type).toBe("missing_dependency");
+        expect(entry?.lastStartError?.binary).toBe("parachute-vault");
+        expect(entry?.lastStartError?.install?.generic).toBe("parachute install vault");
+        expect(entry?.lastStartError?.at).toBeDefined();
+      } finally {
+        cleanup();
+      }
+    });
+
+    test("recordStartError is a no-op when the row is absent", () => {
+      const { path, cleanup } = makeTempPath();
+      try {
+        upsertService(vault, path);
+        recordStartError("parachute-scribe", wire, path);
+        const scribe = readManifest(path).services.find((s) => s.name === "parachute-scribe");
+        expect(scribe).toBeUndefined();
+      } finally {
+        cleanup();
+      }
+    });
+
+    test("clearStartError removes a recorded error", () => {
+      const { path, cleanup } = makeTempPath();
+      try {
+        upsertService(vault, path);
+        recordStartError("parachute-vault", wire, path);
+        clearStartError("parachute-vault", path);
+        const entry = readManifest(path).services.find((s) => s.name === "parachute-vault");
+        expect(entry?.lastStartError).toBeUndefined();
+      } finally {
+        cleanup();
+      }
+    });
+
+    test("lastStartError round-trips through validation", () => {
+      const { path, cleanup } = makeTempPath();
+      try {
+        const withErr: ServiceEntry = {
+          ...vault,
+          lastStartError: { ...wire, at: "2026-05-29T00:00:00Z" },
+        };
+        upsertService(withErr, path);
+        const entry = readManifest(path).services.find((s) => s.name === "parachute-vault");
+        expect(entry?.lastStartError).toEqual({ ...wire, at: "2026-05-29T00:00:00Z" });
+      } finally {
+        cleanup();
+      }
+    });
+
+    test("a malformed lastStartError is dropped, not thrown (diagnostic field)", () => {
+      const { path, cleanup } = makeTempPath();
+      try {
+        writeFileSync(
+          path,
+          JSON.stringify({
+            services: [
+              {
+                ...vault,
+                // missing error_description → invalid shape → dropped
+                lastStartError: { error_type: "missing_dependency" },
+              },
+            ],
+          }),
+        );
+        const entry = readManifest(path).services.find((s) => s.name === "parachute-vault");
+        expect(entry).toBeDefined();
+        expect(entry?.lastStartError).toBeUndefined();
+      } finally {
+        cleanup();
+      }
+    });
+  });
 });