@openparachute/hub 0.6.5-rc.8 → 0.7.0

package/src/__tests__/admin-csrf-belt.test.ts

@@ -0,0 +1,346 @@
+/**
+ * CSRF belt on cookie-gated /admin/* JSON mutation endpoints (hub#632,
+ * 2026-06-09 hub-module-boundary Phase C1).
+ *
+ * Two layers:
+ *
+ *   1. Unit — `assertSameOriginForCookieMutation` semantics: which requests
+ *      the belt gates (cookie-authed mutations), which it waves through
+ *      (reads, Bearer-authed, cookie-less), and the two rejection codes
+ *      (`csrf_origin_required` / `csrf_origin_mismatch`).
+ *   2. Integration — the wiring in hub-server.ts dispatch for
+ *      `/admin/connections`: cross-origin cookie mutations 403 BEFORE the
+ *      operator gate; same-origin mutations reach the handler; GETs are
+ *      unaffected; Bearer-authed mutations skip the belt and land on the
+ *      endpoint's own gate. (The legacy `/admin/channels` wiring was belted
+ *      here too until boundary D1 retired the endpoint.)
+ *
+ * The canonical seam consumer is pinned here: channel's admin page POSTs
+ * `/admin/connections` as a same-origin `fetch()` with
+ * `credentials: "include"` (parachute-channel src/admin-ui.ts) — i.e.
+ * session cookie + browser-sent matching Origin. That shape must keep
+ * passing the belt without any token dance.
+ */
+import type { Database } from "bun:sqlite";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { hubDbPath, openHubDb } from "../hub-db.ts";
+import { hubFetch } from "../hub-server.ts";
+import { assertSameOriginForCookieMutation } from "../origin-check.ts";
+import { SESSION_TTL_MS, buildSessionCookie, createSession } from "../sessions.ts";
+import { createUser } from "../users.ts";
+
+const BOUND = ["https://hub.example", "http://localhost:1939", "http://127.0.0.1:1939"];
+const SESSION_COOKIE = "parachute_hub_session=abc123";
+
+function mutReq(opts: {
+  method?: string;
+  origin?: string;
+  cookie?: string;
+  authorization?: string;
+  url?: string;
+}): Request {
+  const headers: Record<string, string> = {};
+  if (opts.origin !== undefined) headers.origin = opts.origin;
+  if (opts.cookie !== undefined) headers.cookie = opts.cookie;
+  if (opts.authorization !== undefined) headers.authorization = opts.authorization;
+  return new Request(opts.url ?? "https://hub.example/admin/connections", {
+    method: opts.method ?? "POST",
+    headers,
+  });
+}
+
+async function errorCode(res: Response): Promise<string> {
+  const body = (await res.json()) as { error?: string };
+  return body.error ?? "";
+}
+
+describe("assertSameOriginForCookieMutation (unit)", () => {
+  test("cookie-authed POST with matching Origin passes", () => {
+    const res = mutReq({ cookie: SESSION_COOKIE, origin: "https://hub.example" });
+    expect(assertSameOriginForCookieMutation(res, BOUND)).toBeNull();
+  });
+
+  test("matching any bound origin passes (multi-origin hub: loopback alias)", () => {
+    const res = mutReq({
+      cookie: SESSION_COOKIE,
+      origin: "http://127.0.0.1:1939",
+      url: "http://127.0.0.1:1939/admin/connections",
+    });
+    expect(assertSameOriginForCookieMutation(res, BOUND)).toBeNull();
+  });
+
+  test("cookie-authed POST with cross-site Origin → 403 csrf_origin_mismatch", async () => {
+    const rejected = assertSameOriginForCookieMutation(
+      mutReq({ cookie: SESSION_COOKIE, origin: "https://evil.example" }),
+      BOUND,
+    );
+    expect(rejected).not.toBeNull();
+    expect(rejected?.status).toBe(403);
+    expect(await errorCode(rejected as Response)).toBe("csrf_origin_mismatch");
+  });
+
+  test("cookie-authed POST with NO Origin → 403 csrf_origin_required", async () => {
+    const rejected = assertSameOriginForCookieMutation(mutReq({ cookie: SESSION_COOKIE }), BOUND);
+    expect(rejected?.status).toBe(403);
+    expect(await errorCode(rejected as Response)).toBe("csrf_origin_required");
+  });
+
+  test("`Origin: null` (opaque origin) is a mismatch, NOT a pass — no Host fallback", async () => {
+    // The attacker form-post shape: referrer-policy no-referrer makes the
+    // browser send `Origin: null` on a navigation POST; Host always names
+    // the target. isSameOriginRequest's Host fallback would pass this —
+    // the belt must not (these JSON endpoints carry no double-submit token).
+    const rejected = assertSameOriginForCookieMutation(
+      mutReq({ cookie: SESSION_COOKIE, origin: "null" }),
+      BOUND,
+    );
+    expect(rejected?.status).toBe(403);
+    expect(await errorCode(rejected as Response)).toBe("csrf_origin_mismatch");
+  });
+
+  test("malformed Origin is a mismatch", async () => {
+    const rejected = assertSameOriginForCookieMutation(
+      mutReq({ cookie: SESSION_COOKIE, origin: "not a url" }),
+      BOUND,
+    );
+    expect(rejected?.status).toBe(403);
+    expect(await errorCode(rejected as Response)).toBe("csrf_origin_mismatch");
+  });
+
+  test("PUT / PATCH / DELETE are gated like POST", () => {
+    for (const method of ["PUT", "PATCH", "DELETE"]) {
+      const rejected = assertSameOriginForCookieMutation(
+        mutReq({ method, cookie: SESSION_COOKIE }),
+        BOUND,
+      );
+      expect(rejected?.status).toBe(403);
+    }
+  });
+
+  test("GET / HEAD / OPTIONS pass regardless of Origin", () => {
+    for (const method of ["GET", "HEAD", "OPTIONS"]) {
+      const res = mutReq({ method, cookie: SESSION_COOKIE, origin: "https://evil.example" });
+      expect(assertSameOriginForCookieMutation(res, BOUND)).toBeNull();
+    }
+  });
+
+  test("Bearer-authed mutation without Origin passes (API clients are CSRF-immune)", () => {
+    const res = mutReq({ authorization: "Bearer some-token" });
+    expect(assertSameOriginForCookieMutation(res, BOUND)).toBeNull();
+  });
+
+  test("Authorization present + cookie present passes — a custom header cannot ride a CSRF", () => {
+    // Cross-site pages cannot attach an Authorization header without a CORS
+    // preflight these routes never approve, so its presence proves this is
+    // not a browser-forged request. The endpoint's own gate still runs.
+    const res = mutReq({ authorization: "Bearer some-token", cookie: SESSION_COOKIE });
+    expect(assertSameOriginForCookieMutation(res, BOUND)).toBeNull();
+  });
+
+  test("no cookie + no Authorization passes through (endpoint's own 401 is the right answer)", () => {
+    const res = mutReq({});
+    expect(assertSameOriginForCookieMutation(res, BOUND)).toBeNull();
+  });
+
+  test("other cookies without the session cookie do not arm the belt", () => {
+    const res = mutReq({ cookie: "parachute_hub_csrf=tok; theme=dark" });
+    expect(assertSameOriginForCookieMutation(res, BOUND)).toBeNull();
+  });
+
+  test("empty bound-origin set fails closed for cookie-authed mutations", async () => {
+    const rejected = assertSameOriginForCookieMutation(
+      mutReq({ cookie: SESSION_COOKIE, origin: "https://hub.example" }),
+      [],
+    );
+    expect(rejected?.status).toBe(403);
+    expect(await errorCode(rejected as Response)).toBe("csrf_origin_mismatch");
+  });
+});
+
+// ===========================================================================
+// Integration — the dispatch wiring in hub-server.ts
+// ===========================================================================
+
+interface Harness {
+  dir: string;
+  db: Database;
+  cookie: string;
+  cleanup: () => void;
+}
+
+let h: Harness;
+
+beforeEach(async () => {
+  const dir = mkdtempSync(join(tmpdir(), "phub-csrf-belt-"));
+  const db = openHubDb(hubDbPath(dir));
+  const user = await createUser(db, "operator", "hunter2");
+  const session = createSession(db, { userId: user.id });
+  h = {
+    dir,
+    db,
+    cookie: buildSessionCookie(session.id, Math.floor(SESSION_TTL_MS / 1000)),
+    cleanup: () => {
+      db.close();
+      rmSync(dir, { recursive: true, force: true });
+    },
+  };
+});
+afterEach(() => h.cleanup());
+
+/** hubFetch with bound origins pinned to the request-derived issuer (no
+ * stored hub_origin, no configured issuer, no expose state). */
+function handler() {
+  return hubFetch(h.dir, {
+    getDb: () => h.db,
+    manifestPath: join(h.dir, "services.json"),
+    connectionsStorePath: join(h.dir, "connections.json"),
+    loadExposeHubOrigin: () => undefined,
+  });
+}
+
+const ORIGIN = "http://hub.test";
+
+function adminReq(
+  path: string,
+  opts: { method?: string; origin?: string; cookie?: string; auth?: string; body?: unknown } = {},
+): Request {
+  const headers: Record<string, string> = {};
+  if (opts.origin !== undefined) headers.origin = opts.origin;
+  if (opts.cookie !== undefined) headers.cookie = opts.cookie;
+  if (opts.auth !== undefined) headers.authorization = opts.auth;
+  if (opts.body !== undefined) headers["content-type"] = "application/json";
+  return new Request(`${ORIGIN}${path}`, {
+    method: opts.method ?? "POST",
+    headers,
+    ...(opts.body !== undefined ? { body: JSON.stringify(opts.body) } : {}),
+  });
+}
+
+describe("CSRF belt wiring — /admin/connections", () => {
+  test("cross-origin cookie POST /admin/connections → 403 csrf_origin_mismatch (even with a valid admin session)", async () => {
+    const res = await handler()(
+      adminReq("/admin/connections", {
+        cookie: h.cookie,
+        origin: "https://evil.example",
+        body: {},
+      }),
+    );
+    expect(res.status).toBe(403);
+    expect(await errorCode(res)).toBe("csrf_origin_mismatch");
+  });
+
+  test("missing-Origin cookie POST /admin/connections → 403 csrf_origin_required", async () => {
+    const res = await handler()(adminReq("/admin/connections", { cookie: h.cookie, body: {} }));
+    expect(res.status).toBe(403);
+    expect(await errorCode(res)).toBe("csrf_origin_required");
+  });
+
+  test("same-origin cookie POST /admin/connections passes the belt and reaches handler validation", async () => {
+    const res = await handler()(
+      adminReq("/admin/connections", { cookie: h.cookie, origin: ORIGIN, body: {} }),
+    );
+    // Past the belt: the handler's own body validation answers (400), not a
+    // csrf_* 403.
+    expect(res.status).toBe(400);
+    expect(await errorCode(res)).toBe("invalid_request");
+  });
+
+  test("seam pin — the channel link-vault shape (cookie + correct Origin, requestedBy: channel) passes the belt", async () => {
+    // parachute-channel/src/admin-ui.ts: fetch(window.location.origin +
+    // "/admin/connections", { method: "POST", credentials: "include" }) —
+    // same-origin fetch(), so the browser sends Origin = hub origin on the
+    // POST. With no modules installed in this harness the engine answers
+    // 400 unknown_module — i.e. the request cleared the belt AND the
+    // operator gate and reached catalog validation. The full provision flow
+    // is covered handler-level in admin-connections.test.ts.
+    const res = await handler()(
+      adminReq("/admin/connections", {
+        cookie: h.cookie,
+        origin: ORIGIN,
+        body: {
+          source: {
+            module: "vault",
+            vault: "main",
+            event: "note.created",
+            filter: { tags: ["channel-message/inbound"] },
+          },
+          sink: { module: "channel", action: "message.deliver", params: { channel: "tg" } },
+          requestedBy: "channel",
+        },
+      }),
+    );
+    expect(res.status).toBe(400);
+    expect(await errorCode(res)).toBe("unknown_module");
+  });
+
+  test("X-Forwarded-Proto public-origin case over the proxy passes", async () => {
+    // TLS terminates at the edge; hub sees plain http with
+    // X-Forwarded-Proto: https and the public Host preserved end-to-end.
+    // resolveIssuer derives https://<host> — the browser's Origin on a
+    // same-origin fetch is exactly that, so the belt matches.
+    const req = new Request("http://pub.example/admin/connections", {
+      method: "POST",
+      headers: {
+        cookie: h.cookie,
+        origin: "https://pub.example",
+        "x-forwarded-proto": "https",
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({}),
+    });
+    const res = await handler()(req);
+    expect(res.status).toBe(400); // handler validation, not the belt's 403
+    expect(await errorCode(res)).toBe("invalid_request");
+  });
+
+  test("GET /admin/connections with cookie and no Origin is unaffected", async () => {
+    const res = await handler()(
+      adminReq("/admin/connections", { method: "GET", cookie: h.cookie }),
+    );
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { ok: boolean; connections: unknown[] };
+    expect(body.ok).toBe(true);
+    expect(body.connections).toEqual([]);
+  });
+
+  test("Bearer-authed POST /admin/connections without Origin skips the belt; the endpoint's own gate answers", async () => {
+    const res = await handler()(
+      adminReq("/admin/connections", { auth: "Bearer junk-token", body: {} }),
+    );
+    // Cookie-gated endpoint: the operator gate 401s the Bearer-only caller.
+    // The point pinned here: NOT a 403 csrf_* rejection.
+    expect(res.status).toBe(401);
+    expect(await errorCode(res)).toBe("unauthenticated");
+  });
+
+  test("cross-origin cookie DELETE /admin/connections/<id> → 403 csrf_origin_mismatch", async () => {
+    const res = await handler()(
+      adminReq("/admin/connections/some-id", {
+        method: "DELETE",
+        cookie: h.cookie,
+        origin: "https://evil.example",
+      }),
+    );
+    expect(res.status).toBe(403);
+    expect(await errorCode(res)).toBe("csrf_origin_mismatch");
+  });
+
+  // The legacy `/admin/channels` cases lived here until boundary D1 retired
+  // the endpoint (superseded by /admin/connections, covered above). A POST
+  // there now falls through dispatch to the generic `/admin/*` SPA mount,
+  // which rejects non-GET (405) — the pin here is "no provisioning handler
+  // answers anymore", not the precise fallthrough status.
+  test("retired /admin/channels no longer provisions (D1) — falls through dispatch", async () => {
+    const res = await handler()(
+      adminReq("/admin/channels", {
+        cookie: h.cookie,
+        origin: ORIGIN,
+        body: { channelName: "x", vault: "main" },
+      }),
+    );
+    expect([404, 405]).toContain(res.status);
+  });
+});

package/src/__tests__/admin-module-token.test.ts

@@ -0,0 +1,311 @@
+/**
+ * Tests for the GENERIC per-module config-UI session→bearer mint endpoint
+ * (`GET /admin/module-token/<short>`, 2026-06-09 modular-UI architecture P3).
+ * Mirrors `admin-channel-token.test.ts` shape (single bare audience per
+ * module). Covers:
+ *   - 401 when no admin session cookie is present.
+ *   - 401 when the cookie names a deleted session.
+ *   - 405 on POST.
+ *   - 200 + JWT carrying `aud: "<short>"` and `<short>:admin` for known modules
+ *     (scribe / runner / surface).
+ *   - 400 for `vault` (per-instance — points at /admin/vault-admin-token/<name>).
+ *   - 404 for an unknown short.
+ *   - First-admin gate: 403 for a signed-in non-first-admin (friend).
+ *   - Self-registration gate (boundary C5): a genuinely third-party module
+ *     with a services.json row + readable module.json mints; a registered row
+ *     WITHOUT a readable manifest 404s.
+ */
+import type { Database } from "bun:sqlite";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { MODULE_TOKEN_TTL_SECONDS, handleModuleToken } from "../admin-module-token.ts";
+import { hubDbPath, openHubDb } from "../hub-db.ts";
+import { validateAccessToken } from "../jwt-sign.ts";
+import type { ServiceEntry } from "../services-manifest.ts";
+import { SESSION_TTL_MS, buildSessionCookie, createSession, deleteSession } from "../sessions.ts";
+import { rotateSigningKey } from "../signing-keys.ts";
+import { createUser } from "../users.ts";
+
+const ISSUER = "https://hub.test";
+
+interface Harness {
+  db: Database;
+  cleanup: () => void;
+}
+
+function makeHarness(): Harness {
+  const dir = mkdtempSync(join(tmpdir(), "phub-module-token-"));
+  const db = openHubDb(hubDbPath(dir));
+  return {
+    db,
+    cleanup: () => {
+      db.close();
+      rmSync(dir, { recursive: true, force: true });
+    },
+  };
+}
+
+let harness: Harness;
+beforeEach(() => {
+  harness = makeHarness();
+});
+afterEach(() => {
+  harness.cleanup();
+});
+
+async function withSession(): Promise<{ cookie: string; userId: string }> {
+  const user = await createUser(harness.db, "operator", "hunter2");
+  const session = createSession(harness.db, { userId: user.id });
+  const cookie = buildSessionCookie(session.id, Math.floor(SESSION_TTL_MS / 1000));
+  return { cookie, userId: user.id };
+}
+
+async function withAdminAndFriend(): Promise<{ friendCookie: string }> {
+  const admin = await createUser(harness.db, "admin", "admin-passphrase");
+  const friend = await createUser(harness.db, "alice", "alice-passphrase", { allowMulti: true });
+  createSession(harness.db, { userId: admin.id });
+  const friendSession = createSession(harness.db, { userId: friend.id });
+  return {
+    friendCookie: buildSessionCookie(friendSession.id, Math.floor(SESSION_TTL_MS / 1000)),
+  };
+}
+
+function urlFor(short: string): string {
+  return `${ISSUER}/admin/module-token/${short}`;
+}
+
+/** Default deps — no services.json rows (registry-only resolution). */
+function depsWith(services: ServiceEntry[] = []): {
+  db: Database;
+  issuer: string;
+  readServices: () => readonly ServiceEntry[];
+} {
+  return { db: harness.db, issuer: ISSUER, readServices: () => services };
+}
+
+describe("handleModuleToken", () => {
+  test("401 when no session cookie is present", async () => {
+    const req = new Request(urlFor("scribe"));
+    const res = await handleModuleToken(req, "scribe", depsWith());
+    expect(res.status).toBe(401);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toBe("unauthenticated");
+  });
+
+  test("401 when the cookie names a deleted session", async () => {
+    const { cookie } = await withSession();
+    const sid = cookie.match(/parachute_hub_session=([^;]+)/)?.[1] ?? "";
+    deleteSession(harness.db, sid);
+    const req = new Request(urlFor("scribe"), { headers: { cookie } });
+    const res = await handleModuleToken(req, "scribe", depsWith());
+    expect(res.status).toBe(401);
+  });
+
+  test("405 on POST", async () => {
+    const { cookie } = await withSession();
+    const req = new Request(urlFor("scribe"), { method: "POST", headers: { cookie } });
+    const res = await handleModuleToken(req, "scribe", depsWith());
+    expect(res.status).toBe(405);
+  });
+
+  // The known single-audience modules the generic mint serves. Each gets
+  // `<short>:admin` with `aud: <short>`.
+  for (const short of ["scribe", "runner", "surface", "channel"]) {
+    test(`200 mints a JWT carrying aud:${short} + ${short}:admin`, async () => {
+      const { cookie, userId } = await withSession();
+      rotateSigningKey(harness.db);
+      const req = new Request(urlFor(short), { headers: { cookie } });
+      const res = await handleModuleToken(req, short, depsWith());
+      expect(res.status).toBe(200);
+      expect(res.headers.get("cache-control")).toBe("no-store");
+
+      const body = (await res.json()) as { token: string; expires_at: string; scopes: string[] };
+      expect(body.scopes).toEqual([`${short}:admin`]);
+      expect(body.token.length).toBeGreaterThan(20);
+
+      const expMs = new Date(body.expires_at).getTime();
+      const skew = expMs - Date.now();
+      expect(skew).toBeGreaterThan((MODULE_TOKEN_TTL_SECONDS - 30) * 1000);
+      expect(skew).toBeLessThan((MODULE_TOKEN_TTL_SECONDS + 30) * 1000);
+
+      const validated = await validateAccessToken(harness.db, body.token, ISSUER);
+      expect(validated.payload.sub).toBe(userId);
+      expect(validated.payload.iss).toBe(ISSUER);
+      // Bare service audience — modules validate `aud === <short>`.
+      expect(validated.payload.aud).toBe(short);
+      const scopeClaim = (validated.payload as { scope?: string }).scope ?? "";
+      expect(scopeClaim.split(/\s+/)).toContain(`${short}:admin`);
+    });
+  }
+
+  test("400 use_vault_admin_token for vault (per-instance)", async () => {
+    const { cookie } = await withSession();
+    const req = new Request(urlFor("vault"), { headers: { cookie } });
+    const res = await handleModuleToken(req, "vault", depsWith());
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toBe("use_vault_admin_token");
+  });
+
+  test("404 for an unknown short", async () => {
+    const { cookie } = await withSession();
+    const req = new Request(urlFor("totally-made-up"), { headers: { cookie } });
+    const res = await handleModuleToken(req, "totally-made-up", depsWith());
+    expect(res.status).toBe(404);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toBe("not_found");
+  });
+
+  test("400 for an invalid identifier", async () => {
+    const { cookie } = await withSession();
+    const req = new Request(`${ISSUER}/admin/module-token/Not%20Valid`, { headers: { cookie } });
+    const res = await handleModuleToken(req, "Not Valid", depsWith());
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toBe("invalid_request");
+  });
+
+  test("403 not_admin when a signed-in non-first-admin (friend) hits the endpoint", async () => {
+    const { friendCookie } = await withAdminAndFriend();
+    rotateSigningKey(harness.db);
+    const req = new Request(urlFor("scribe"), { headers: { cookie: friendCookie } });
+    const res = await handleModuleToken(req, "scribe", depsWith());
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toBe("not_admin");
+  });
+
+  // -------------------------------------------------------------------------
+  // Self-registration gate (boundary C5). A genuinely third-party module —
+  // NOT in KNOWN_MODULES / FIRST_PARTY_FALLBACKS — mints when its
+  // services.json row's installDir carries a readable module.json. This is
+  // the charter's third-party test: zero hub code changes to get the mint.
+  // -------------------------------------------------------------------------
+
+  /** Write a real `.parachute/module.json` into a temp install dir. */
+  function writeManifestDir(name: string): string {
+    const dir = mkdtempSync(join(tmpdir(), "phub-module-token-installdir-"));
+    mkdirSync(join(dir, ".parachute"), { recursive: true });
+    writeFileSync(
+      join(dir, ".parachute", "module.json"),
+      JSON.stringify({
+        name,
+        manifestName: name,
+        port: 1947,
+        paths: [`/${name}`],
+        health: `/${name}/health`,
+      }),
+    );
+    return dir;
+  }
+
+  test("200 mints for a self-registered third-party module (row + readable module.json)", async () => {
+    const { cookie, userId } = await withSession();
+    rotateSigningKey(harness.db);
+    const installDir = writeManifestDir("widgets");
+    try {
+      const services: ServiceEntry[] = [
+        {
+          name: "widgets",
+          port: 1947,
+          paths: ["/widgets"],
+          health: "/widgets/health",
+          version: "1.0.0",
+          installDir,
+        },
+      ];
+      const req = new Request(urlFor("widgets"), { headers: { cookie } });
+      const res = await handleModuleToken(req, "widgets", depsWith(services));
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as { token: string; scopes: string[] };
+      expect(body.scopes).toEqual(["widgets:admin"]);
+      const validated = await validateAccessToken(harness.db, body.token, ISSUER);
+      expect(validated.payload.sub).toBe(userId);
+      expect(validated.payload.aud).toBe("widgets");
+    } finally {
+      rmSync(installDir, { recursive: true, force: true });
+    }
+  });
+
+  test("404 for a registered row whose installDir has NO readable module.json", async () => {
+    const { cookie } = await withSession();
+    rotateSigningKey(harness.db);
+    const emptyDir = mkdtempSync(join(tmpdir(), "phub-module-token-nomanifest-"));
+    try {
+      const services: ServiceEntry[] = [
+        {
+          name: "widgets",
+          port: 1947,
+          paths: ["/widgets"],
+          health: "/widgets/health",
+          version: "1.0.0",
+          installDir: emptyDir,
+        },
+      ];
+      const req = new Request(urlFor("widgets"), { headers: { cookie } });
+      const res = await handleModuleToken(req, "widgets", depsWith(services));
+      expect(res.status).toBe(404);
+      const body = (await res.json()) as { error: string };
+      expect(body.error).toBe("not_found");
+    } finally {
+      rmSync(emptyDir, { recursive: true, force: true });
+    }
+  });
+
+  test("404 for a registered row with no installDir at all", async () => {
+    const { cookie } = await withSession();
+    rotateSigningKey(harness.db);
+    const services: ServiceEntry[] = [
+      { name: "widgets", port: 1947, paths: ["/widgets"], health: "/widgets/health", version: "1" },
+    ];
+    const req = new Request(urlFor("widgets"), { headers: { cookie } });
+    const res = await handleModuleToken(req, "widgets", depsWith(services));
+    expect(res.status).toBe(404);
+  });
+
+  test("vault still 400-redirects even when a vault row is registered", async () => {
+    const { cookie } = await withSession();
+    const services: ServiceEntry[] = [
+      {
+        name: "parachute-vault",
+        port: 1940,
+        paths: ["/vault/default"],
+        health: "/vault/default/health",
+        version: "0.5.0",
+        installDir: "/tmp/nope",
+      },
+    ];
+    const req = new Request(urlFor("vault"), { headers: { cookie } });
+    const res = await handleModuleToken(req, "vault", depsWith(services));
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toBe("use_vault_admin_token");
+  });
+
+  test("first-party row resolves through the manifest-name map (parachute-channel ↔ channel)", async () => {
+    const { cookie } = await withSession();
+    rotateSigningKey(harness.db);
+    const installDir = writeManifestDir("channel");
+    try {
+      const services: ServiceEntry[] = [
+        {
+          name: "parachute-channel",
+          port: 1941,
+          paths: ["/channel"],
+          health: "/health",
+          version: "0.1.0",
+          installDir,
+        },
+      ];
+      const req = new Request(urlFor("channel"), { headers: { cookie } });
+      const res = await handleModuleToken(req, "channel", depsWith(services));
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as { scopes: string[] };
+      expect(body.scopes).toEqual(["channel:admin"]);
+    } finally {
+      rmSync(installDir, { recursive: true, force: true });
+    }
+  });
+});