@openparachute/hub 0.7.7-rc.8 → 0.7.7

package/src/__tests__/api-modules.test.ts

@@ -175,6 +175,18 @@ describe("GET /api/modules", () => {
     expect(body.error).toBe("insufficient_scope");
   });
 
+  // H1.1 — Bearer scheme is case-insensitive per RFC 7235 (V1.4/C1.3 parity).
+  test("lowercase bearer scheme authenticates identically to canonical Bearer", async () => {
+    const bearer = await mintBearer(h, [API_MODULES_REQUIRED_SCOPE]);
+    const res = await handleApiModules(getReq({ authorization: `bearer ${bearer}` }), {
+      db: h.db,
+      issuer: ISSUER,
+      manifestPath: h.manifestPath,
+      fetchLatestVersion: async () => null,
+    });
+    expect(res.status).toBe(200);
+  });
+
   // hub#516: `parachute status` reads /api/modules on loopback presenting the
   // operator token, whose `iss` is the PUBLIC origin after `expose`. The
   // host-admin bearer's iss is validated against `knownIssuers` (loopback ∪
@@ -250,15 +262,11 @@ describe("GET /api/modules", () => {
     // The core tier leads, in the recommended install order (vault → scribe),
     // ahead of every experimental module, which lead the deprecated ones.
     expect(shorts.indexOf("vault")).toBeLessThan(shorts.indexOf("scribe"));
-    expect(shorts.indexOf("scribe")).toBeLessThan(shorts.indexOf("agent"));
-    // agent (experimental) sorts ahead of notes (deprecated).
-    expect(shorts.indexOf("agent")).toBeLessThan(shorts.indexOf("notes"));
-    // Every known module is discoverable — vault/scribe/surface (core),
-    // agent (experimental), notes (deprecated). runner is gone (2026-07-01
-    // registry removal) — a fresh box never sees it.
-    for (const s of ["vault", "scribe", "surface", "agent", "notes"]) {
+    expect(shorts.indexOf("scribe")).toBeLessThan(shorts.indexOf("notes"));
+    for (const s of ["vault", "scribe", "surface", "app", "notes"]) {
       expect(shorts).toContain(s);
     }
+    expect(shorts).not.toContain("agent");
     expect(shorts).not.toContain("runner");
     expect(shorts).not.toContain("parachute-runner");
     // Focus tier resolves from the default map.
@@ -266,7 +274,8 @@ describe("GET /api/modules", () => {
     expect(byShort.get("vault")?.focus).toBe("core");
     expect(byShort.get("scribe")?.focus).toBe("core");
     expect(byShort.get("surface")?.focus).toBe("core");
-    expect(byShort.get("agent")?.focus).toBe("experimental");
+    expect(byShort.get("app")?.focus).toBe("core");
+    expect(byShort.get("agent")).toBeUndefined();
     expect(byShort.get("notes")?.focus).toBe("deprecated");
     // `available` stays true for every known module (re-installable), but the
     // fresh-install OFFER (`available_to_install`) drops the deprecated tier —
@@ -275,7 +284,7 @@ describe("GET /api/modules", () => {
     expect(byShort.get("vault")?.available_to_install).toBe(true);
     expect(byShort.get("scribe")?.available_to_install).toBe(true);
     expect(byShort.get("surface")?.available_to_install).toBe(true);
-    expect(byShort.get("agent")?.available_to_install).toBe(true);
+    expect(byShort.get("app")?.available_to_install).toBe(true);
     expect(byShort.get("notes")?.available_to_install).toBe(false);
     expect(body.modules.every((m) => !m.installed)).toBe(true);
     expect(body.modules.every((m) => m.latest_version === "0.9.9")).toBe(true);
@@ -369,13 +378,7 @@ describe("GET /api/modules", () => {
     expect(scribe?.available).toBe(true);
   });
 
-  test("agent (running + self-registered) appears as installed + experimental — regression for the channel-not-installed bug", async () => {
-    // THE bug this PR fixes (2026-06-09 modular-UI architecture, P2): agent (renamed from channel 2026-06-17)
-    // was running, proxied, supervised, and self-registered in services.json
-    // yet invisible on the Modules screen — because the old CURATED_MODULES =
-    // ["vault","scribe"] whitelist gated discovery. Now discovery is driven by
-    // self-registration ∪ the known registries, so a self-registered agent
-    // row surfaces as installed, in the experimental tier, with its run-state.
+  test("retired Agent rows do not surface in the module catalog", async () => {
     writeManifest(h.manifestPath, [
       {
         name: "parachute-agent",
@@ -385,32 +388,16 @@ describe("GET /api/modules", () => {
         version: "0.3.1",
       },
     ]);
-    const { supervisor } = makeIdleSupervisor();
-    await supervisor.start({ short: "agent", cmd: ["parachute-agent"] });
-
     const bearer = await mintBearer(h, [API_MODULES_REQUIRED_SCOPE]);
     const res = await handleApiModules(getReq({ authorization: `Bearer ${bearer}` }), {
       db: h.db,
       issuer: ISSUER,
       manifestPath: h.manifestPath,
-      supervisor,
       fetchLatestVersion: async () => null,
     });
-    const body = (await res.json()) as {
-      modules: Array<{
-        short: string;
-        focus: "core" | "experimental";
-        installed: boolean;
-        installed_version: string | null;
-        supervisor_status: string | null;
-      }>;
-    };
-    const agent = body.modules.find((m) => m.short === "agent");
-    expect(agent).toBeDefined();
-    expect(agent?.installed).toBe(true);
-    expect(agent?.installed_version).toBe("0.3.1");
-    expect(agent?.focus).toBe("experimental");
-    expect(agent?.supervisor_status).toBe("running");
+    const body = (await res.json()) as { modules: Array<{ short: string }> };
+    expect(body.modules.find((m) => m.short === "agent")).toBeUndefined();
+    expect(body.modules.find((m) => m.short === "parachute-agent")).toBeUndefined();
   });
 
   test("every self-registered + known module appears in `modules` — no running-but-invisible class", async () => {
@@ -834,20 +821,15 @@ describe("GET /api/modules", () => {
     expect(vault?.management_url).toBe("/vault/default/admin");
   });
 
-  test("populates config_ui_url from a module's configUiUrl (2026-06-09 modular-UI P3)", async () => {
-    // Agent declares `configUiUrl: "/agent/admin"` (a single-instance,
-    // origin-absolute path) + `uiUrl: "/agent/ui"`. The hub surfaces
-    // both: `config_ui_url` drives the Modules page Configure action,
-    // `management_url` drives Open. configUiUrl resolves identically to
-    // managementUrl (same B4 unified semantics).
+  test("populates config_ui_url from a third-party module manifest", async () => {
     writeManifest(h.manifestPath, [
       {
-        name: "agent",
-        port: 1941,
-        paths: ["/agent"],
+        name: "widgets",
+        port: 1947,
+        paths: ["/widgets"],
         health: "/health",
         version: "0.1.0",
-        installDir: "/install/dir/agent",
+        installDir: "/install/dir/widgets",
       },
     ]);
     const bearer = await mintBearer(h, [API_MODULES_REQUIRED_SCOPE]);
@@ -857,17 +839,17 @@ describe("GET /api/modules", () => {
       manifestPath: h.manifestPath,
       fetchLatestVersion: async () => null,
       readModuleManifest: async (installDir) => {
-        if (installDir === "/install/dir/agent") {
+        if (installDir === "/install/dir/widgets") {
           return {
-            name: "agent",
-            manifestName: "parachute-agent",
-            displayName: "Agent",
+            name: "widgets",
+            manifestName: "widgets",
+            displayName: "Widgets",
             tagline: "",
-            port: 1941,
-            paths: ["/agent"],
+            port: 1947,
+            paths: ["/widgets"],
             health: "/health",
-            uiUrl: "/agent/ui",
-            configUiUrl: "/agent/admin",
+            uiUrl: "/widgets/ui",
+            configUiUrl: "/widgets/admin",
           } as unknown as Awaited<
             ReturnType<typeof import("../module-manifest.ts").readModuleManifest>
           >;
@@ -883,11 +865,9 @@ describe("GET /api/modules", () => {
         management_url: string | null;
       }>;
     };
-    const agent = body.modules.find((m) => m.short === "agent");
-    // Origin-absolute — verbatim, never double-prepends `/agent`.
-    expect(agent?.config_ui_url).toBe("/agent/admin");
-    // uiUrl (no managementUrl) drives the Open action's management_url.
-    expect(agent?.management_url).toBe("/agent/ui");
+    const widgets = body.modules.find((m) => m.short === "widgets");
+    expect(widgets?.config_ui_url).toBe("/widgets/admin");
+    expect(widgets?.management_url).toBe("/widgets/ui");
   });
 
   test("config_ui_url is null when the module declares no configUiUrl", async () => {
@@ -1498,6 +1478,18 @@ describe("PUT /api/modules/channel — hub#275 channel toggle", () => {
     expect(res.status).toBe(401);
   });
 
+  // H1.1 — Bearer scheme is case-insensitive per RFC 7235 (V1.4/C1.3 parity).
+  test("lowercase bearer scheme authenticates identically to canonical Bearer", async () => {
+    const bearer = await mintBearer(h, [API_MODULES_CHANNEL_REQUIRED_SCOPE]);
+    const res = await handleApiModulesChannel(
+      putReq({ channel: "rc" }, { authorization: `bearer ${bearer}` }),
+      { db: h.db, issuer: ISSUER },
+    );
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { channel: string };
+    expect(body.channel).toBe("rc");
+  });
+
   test("403 on bearer without parachute:host:admin", async () => {
     // `:host:auth` reads the GET catalog — it must NOT be allowed to
     // flip the install channel. Boundary matches install/upgrade/uninstall.

package/src/__tests__/api-revoke-token.test.ts

@@ -263,6 +263,29 @@ describe("POST /api/auth/revoke-token (closes hub#220)", () => {
     }
   });
 
+  // H1.1 — Bearer scheme is case-insensitive per RFC 7235 (V1.4/C1.3 parity).
+  test("lowercase bearer scheme authenticates identically to canonical Bearer", async () => {
+    const h = makeHarness();
+    try {
+      const { db, userId } = await bootstrap(h.dir);
+      try {
+        const op = await mintOperatorToken(db, userId, { issuer: ISSUER });
+        const jti = await seedToken(db, userId);
+        const resp = await handleApiRevokeToken(
+          jsonRequest({ jti }, { authorization: `bearer ${op.token}` }),
+          { db, issuer: ISSUER },
+        );
+        expect(resp.status).toBe(200);
+        const body = (await resp.json()) as { jti: string };
+        expect(body.jti).toBe(jti);
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
   test("idempotent: re-revoking returns 200 with the original revoked_at", async () => {
     const h = makeHarness();
     try {

package/src/__tests__/api-settings-hub-origin.test.ts

@@ -258,6 +258,18 @@ describe("GET /api/settings/hub-origin", () => {
     expect(body.resolved_issuer).toBe("http://localhost"); // request origin from getReq()
   });
 
+  // H1.1 — Bearer scheme is case-insensitive per RFC 7235 (V1.4/C1.3 parity).
+  test("lowercase bearer scheme authenticates identically to canonical Bearer", async () => {
+    const bearer = await mintBearer(h, [API_SETTINGS_HUB_ORIGIN_REQUIRED_SCOPE]);
+    const res = await handleApiSettingsHubOrigin(
+      getReq({ authorization: `bearer ${bearer}` }),
+      deps(h),
+    );
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { hub_origin: string | null };
+    expect(body.hub_origin).toBeNull();
+  });
+
   test("returns env source + env-resolved issuer when configuredIssuer is set", async () => {
     const bearer = await mintBearer(h, [API_SETTINGS_HUB_ORIGIN_REQUIRED_SCOPE]);
     const res = await handleApiSettingsHubOrigin(getReq({ authorization: `Bearer ${bearer}` }), {

package/src/__tests__/api-settings-root-redirect.test.ts

@@ -18,10 +18,11 @@ import { join } from "node:path";
 import {
   API_SETTINGS_ROOT_REDIRECT_REQUIRED_SCOPE,
   handleApiSettingsRootRedirect,
+  validateRootMode,
   validateRootRedirect,
 } from "../api-settings-root-redirect.ts";
 import { hubDbPath, openHubDb } from "../hub-db.ts";
-import { getRootRedirect, setRootRedirect } from "../hub-settings.ts";
+import { getRootMode, getRootRedirect, setRootMode, setRootRedirect } from "../hub-settings.ts";
 import { recordTokenMint, signAccessToken } from "../jwt-sign.ts";
 import { rotateSigningKey } from "../signing-keys.ts";
 import { createUser } from "../users.ts";
@@ -192,7 +193,33 @@ describe("GET /api/settings/root-redirect", () => {
     );
     expect(res.status).toBe(200);
     const body = (await res.json()) as Record<string, unknown>;
-    expect(body).toEqual({ root_redirect: null, resolved: "/admin", source: "default" });
+    expect(body).toEqual({
+      root_redirect: null,
+      resolved: "/admin",
+      source: "default",
+      root_mode: null,
+      resolved_mode: "redirect",
+      mode_source: "default",
+    });
+  });
+
+  // H1.1 — Bearer scheme is case-insensitive per RFC 7235 (V1.4/C1.3 parity).
+  test("lowercase bearer scheme authenticates identically to canonical Bearer", async () => {
+    const bearer = await mintBearer(h, [API_SETTINGS_ROOT_REDIRECT_REQUIRED_SCOPE]);
+    const res = await handleApiSettingsRootRedirect(
+      getReq({ authorization: `bearer ${bearer}` }),
+      deps(h),
+    );
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as Record<string, unknown>;
+    expect(body).toEqual({
+      root_redirect: null,
+      resolved: "/admin",
+      source: "default",
+      root_mode: null,
+      resolved_mode: "redirect",
+      mode_source: "default",
+    });
   });
 
   test("reflects a stored value with source=db", async () => {
@@ -207,6 +234,9 @@ describe("GET /api/settings/root-redirect", () => {
       root_redirect: "/surface/reading-room",
       resolved: "/surface/reading-room",
       source: "db",
+      root_mode: null,
+      resolved_mode: "redirect",
+      mode_source: "default",
     });
   });
 
@@ -221,6 +251,9 @@ describe("GET /api/settings/root-redirect", () => {
       root_redirect: null,
       resolved: "/surface/from-env",
       source: "env",
+      root_mode: null,
+      resolved_mode: "redirect",
+      mode_source: "default",
     });
   });
 });
@@ -239,7 +272,10 @@ describe("PUT /api/settings/root-redirect", () => {
       deps(h),
     );
     expect(put.status).toBe(200);
-    expect((await put.json()) as unknown).toEqual({ root_redirect: "/surface/reading-room" });
+    expect((await put.json()) as unknown).toEqual({
+      root_redirect: "/surface/reading-room",
+      root_mode: null,
+    });
     expect(getRootRedirect(h.db)).toBe("/surface/reading-room");
 
     const get = await handleApiSettingsRootRedirect(
@@ -282,7 +318,7 @@ describe("PUT /api/settings/root-redirect", () => {
     }
   });
 
-  test("400 on a body without a root_redirect field", async () => {
+  test("400 on a body with neither root_redirect nor root_mode", async () => {
     const bearer = await mintBearer(h, [API_SETTINGS_ROOT_REDIRECT_REQUIRED_SCOPE]);
     const res = await handleApiSettingsRootRedirect(
       putReq({ wrong: "x" }, { authorization: `Bearer ${bearer}` }),
@@ -300,3 +336,122 @@ describe("PUT /api/settings/root-redirect", () => {
     expect(res.status).toBe(400);
   });
 });
+
+describe("validateRootMode — pure validator", () => {
+  test("null + empty string → normalized null (clear)", () => {
+    expect(validateRootMode(null)).toEqual({ ok: true, normalized: null });
+    expect(validateRootMode("")).toEqual({ ok: true, normalized: null });
+  });
+
+  test("valid modes normalize verbatim", () => {
+    expect(validateRootMode("redirect")).toEqual({ ok: true, normalized: "redirect" });
+    expect(validateRootMode("serve-app")).toEqual({ ok: true, normalized: "serve-app" });
+  });
+
+  test("rejects unknown modes + non-strings", () => {
+    for (const bad of ["serveapp", "SERVE-APP", "app", 42, {}]) {
+      expect(validateRootMode(bad).ok).toBe(false);
+    }
+  });
+});
+
+describe("root_mode over the endpoint", () => {
+  let h: Harness;
+  beforeEach(async () => {
+    h = await makeHarness();
+  });
+  afterEach(() => h.cleanup());
+
+  test("GET reflects a stored serve-app mode with mode_source=db", async () => {
+    setRootMode(h.db, "serve-app");
+    const bearer = await mintBearer(h, [API_SETTINGS_ROOT_REDIRECT_REQUIRED_SCOPE]);
+    const res = await handleApiSettingsRootRedirect(
+      getReq({ authorization: `Bearer ${bearer}` }),
+      deps(h),
+    );
+    const body = (await res.json()) as Record<string, unknown>;
+    expect(body.root_mode).toBe("serve-app");
+    expect(body.resolved_mode).toBe("serve-app");
+    expect(body.mode_source).toBe("db");
+  });
+
+  test("GET surfaces an env-sourced mode while the stored row is null", async () => {
+    const bearer = await mintBearer(h, [API_SETTINGS_ROOT_REDIRECT_REQUIRED_SCOPE]);
+    const res = await handleApiSettingsRootRedirect(
+      getReq({ authorization: `Bearer ${bearer}` }),
+      deps(h, { env: { PARACHUTE_HUB_ROOT_MODE: "serve-app" } }),
+    );
+    const body = (await res.json()) as Record<string, unknown>;
+    expect(body.root_mode).toBeNull();
+    expect(body.resolved_mode).toBe("serve-app");
+    expect(body.mode_source).toBe("env");
+  });
+
+  test("PUT stores serve-app + GET reflects it on the next request (no restart)", async () => {
+    const bearer = await mintBearer(h, [API_SETTINGS_ROOT_REDIRECT_REQUIRED_SCOPE]);
+    const put = await handleApiSettingsRootRedirect(
+      putReq({ root_mode: "serve-app" }, { authorization: `Bearer ${bearer}` }),
+      deps(h),
+    );
+    expect(put.status).toBe(200);
+    expect((await put.json()) as unknown).toEqual({ root_redirect: null, root_mode: "serve-app" });
+    expect(getRootMode(h.db)).toBe("serve-app");
+  });
+
+  test("PUT redirect / null clears the row back to the default", async () => {
+    setRootMode(h.db, "serve-app");
+    const bearer = await mintBearer(h, [API_SETTINGS_ROOT_REDIRECT_REQUIRED_SCOPE]);
+    // Writing the default "redirect" deletes the row (footgun-guard parity).
+    const res = await handleApiSettingsRootRedirect(
+      putReq({ root_mode: "redirect" }, { authorization: `Bearer ${bearer}` }),
+      deps(h),
+    );
+    expect(res.status).toBe(200);
+    expect(getRootMode(h.db)).toBeNull();
+  });
+
+  test("PUT rejects an invalid mode with 400 + writes nothing", async () => {
+    const bearer = await mintBearer(h, [API_SETTINGS_ROOT_REDIRECT_REQUIRED_SCOPE]);
+    const res = await handleApiSettingsRootRedirect(
+      putReq({ root_mode: "serveapp" }, { authorization: `Bearer ${bearer}` }),
+      deps(h),
+    );
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as Record<string, unknown>;
+    expect(body.error).toBe("invalid_root_mode");
+    expect(getRootMode(h.db)).toBeNull();
+  });
+
+  test("PUT applies both root_mode + root_redirect in one call", async () => {
+    const bearer = await mintBearer(h, [API_SETTINGS_ROOT_REDIRECT_REQUIRED_SCOPE]);
+    const res = await handleApiSettingsRootRedirect(
+      putReq(
+        { root_mode: "serve-app", root_redirect: "/surface/fallback" },
+        { authorization: `Bearer ${bearer}` },
+      ),
+      deps(h),
+    );
+    expect(res.status).toBe(200);
+    expect((await res.json()) as unknown).toEqual({
+      root_redirect: "/surface/fallback",
+      root_mode: "serve-app",
+    });
+    expect(getRootMode(h.db)).toBe("serve-app");
+    expect(getRootRedirect(h.db)).toBe("/surface/fallback");
+  });
+
+  test("a rejected mode does NOT half-apply a valid redirect in the same call", async () => {
+    const bearer = await mintBearer(h, [API_SETTINGS_ROOT_REDIRECT_REQUIRED_SCOPE]);
+    const res = await handleApiSettingsRootRedirect(
+      putReq(
+        { root_mode: "bogus", root_redirect: "/surface/should-not-land" },
+        { authorization: `Bearer ${bearer}` },
+      ),
+      deps(h),
+    );
+    expect(res.status).toBe(400);
+    // Both-validated-before-either-applied: the redirect was NOT written.
+    expect(getRootRedirect(h.db)).toBeNull();
+    expect(getRootMode(h.db)).toBeNull();
+  });
+});

package/src/__tests__/api-tokens.test.ts

@@ -139,6 +139,50 @@ describe("GET /api/auth/tokens (admin token list — Phase 2 backend)", () => {
     }
   });
 
+  // H1.1 — Bearer scheme is case-insensitive per RFC 7235 (V1.4/C1.3 parity).
+  test("lowercase bearer scheme authenticates identically to canonical Bearer", async () => {
+    const h = makeHarness();
+    try {
+      const { db, userId } = await bootstrap(h.dir);
+      try {
+        const op = await mintOperatorToken(db, userId, { issuer: ISSUER });
+        const resp = await handleApiTokens(
+          getRequest("", { authorization: `bearer ${op.token}` }),
+          {
+            db,
+            issuer: ISSUER,
+          },
+        );
+        expect(resp.status).toBe(200);
+        const body = (await resp.json()) as { tokens: unknown[] };
+        expect(body.tokens).toHaveLength(1);
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("mixed-case bearer scheme (BeArEr) authenticates identically to canonical Bearer", async () => {
+    const h = makeHarness();
+    try {
+      const { db, userId } = await bootstrap(h.dir);
+      try {
+        const op = await mintOperatorToken(db, userId, { issuer: ISSUER });
+        const resp = await handleApiTokens(
+          getRequest("", { authorization: `BeArEr ${op.token}` }),
+          { db, issuer: ISSUER },
+        );
+        expect(resp.status).toBe(200);
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
   test("happy path: empty registry returns empty array", async () => {
     const h = makeHarness();
     try {

package/src/__tests__/audience-gate.test.ts

@@ -217,6 +217,30 @@ describe("audience gate matrix (H3)", () => {
     }
   });
 
+  // H1.1 — Bearer scheme is case-insensitive per RFC 7235 (V1.4/C1.3 parity).
+  test("audience: hub-users — lowercase/mixed-case bearer scheme authenticates identically to canonical Bearer", async () => {
+    const upstream = startEchoUpstream();
+    try {
+      writeServices(surfaceEntry(upstream.port, { audience: "hub-users" }));
+      const f = fetcher();
+      const bearer = await mintBearer(["vault:default:read", "vault:default:write"]);
+
+      const lower = await f(
+        req("/surface/notes/x", { headers: { authorization: `bearer ${bearer}` } }),
+        fakeServer("127.0.0.1"),
+      );
+      expect(lower?.status).toBe(200);
+
+      const mixed = await f(
+        req("/surface/notes/x", { headers: { authorization: `BeArEr ${bearer}` } }),
+        fakeServer("127.0.0.1"),
+      );
+      expect(mixed?.status).toBe(200);
+    } finally {
+      upstream.stop();
+    }
+  });
+
   test("audience: hub-users — Bearer with NON-satisfying scopes → 403; garbage Bearer → 401", async () => {
     const upstream = startEchoUpstream();
     try {

package/src/__tests__/bearer-scheme-casing.test.ts

@@ -0,0 +1,110 @@
+/**
+ * H1.1 (contracts-brief H1) — Bearer scheme-casing unification.
+ *
+ * RFC 7235 §2.1: the auth-scheme token ("Bearer") is case-insensitive; the
+ * credential (the token itself) is opaque and must be passed VERBATIM — never
+ * case-folded, never trimmed beyond surrounding whitespace. This mirrors
+ * parachute-vault's V1.4 (`BEARER_PREFIX`, case-insensitive) and
+ * parachute-cloud's C1.3 (`workers/vault/src/auth.ts:130-143`) — the other two
+ * door surfaces already converged on this shape; this file (plus the per-site
+ * tests below) closes the hub's half.
+ *
+ * Every converted call site (`src/api-hub-upgrade.ts`, `src/api-tokens.ts`,
+ * `src/api-revoke-token.ts`, `src/api-settings-root-redirect.ts`,
+ * `src/api-modules.ts` ×2, `src/api-modules-ops.ts`, `src/api-mint-token.ts`,
+ * `src/api-settings-hub-origin.ts`, `src/admin-surfaces.ts`,
+ * `src/admin-connections.ts` ×2, `src/audience-gate.ts`) uses the SAME
+ * two-step shape: a case-insensitive `/^Bearer\s+/i` scheme test, followed by
+ * the PRE-EXISTING `header.slice("Bearer ".length).trim()` extraction
+ * (unchanged — "Bearer ".length === "bearer ".length === 7, so the fixed-
+ * offset slice is casing-agnostic and the token substring is untouched).
+ * `src/admin-auth.ts`'s `extractBearerToken` (the documented shared helper,
+ * used by `requireScope` + several `/admin/*` and `/api/*` routes already)
+ * uses an equivalent `/^Bearer\s+(.+)$/i` regex. This file pins that shared
+ * pattern directly, independent of any one handler's DB/deps scaffolding.
+ *
+ * Live end-to-end coverage (a lowercase/mixed-case Authorization header
+ * reaching a real handler and authenticating) lives alongside each site's
+ * existing tests, NOT here:
+ *   - src/__tests__/api-hub-upgrade.test.ts
+ *   - src/__tests__/api-tokens.test.ts
+ *   - src/__tests__/api-revoke-token.test.ts
+ *   - src/__tests__/api-settings-root-redirect.test.ts
+ *   - src/__tests__/api-modules.test.ts (both handleApiModules + handleApiModulesChannel)
+ *   - src/__tests__/api-modules-ops.test.ts
+ *   - src/__tests__/api-mint-token.test.ts
+ *   - src/__tests__/api-settings-hub-origin.test.ts
+ *   - src/__tests__/admin-surfaces.test.ts
+ *   - src/__tests__/admin-connections-credentials.test.ts (renew + claim)
+ *   - src/__tests__/audience-gate.test.ts
+ */
+import { describe, expect, test } from "bun:test";
+import { extractBearerToken } from "../admin-auth.ts";
+
+/** The exact regex + slice shape used at all 12 converted call sites. */
+function siteShapeExtract(header: string | null): string | null {
+  if (!header || !/^Bearer\s+/i.test(header)) return null;
+  return header.slice("Bearer ".length).trim();
+}
+
+// A JWT-shaped token: base64url alphabet includes uppercase letters, so any
+// real access/operator token already exercises "verbatim, case preserved."
+// Use one explicitly so the pin doesn't depend on a real signer.
+const MIXED_CASE_TOKEN = "eyJhbGciOiJFZERTQSJ9.eyJzdWIiOiJBQkNkZWYxMjMifQ.SIGNATURE-Xyz";
+
+describe("H1.1 — site-shape extraction (regex test + fixed-offset slice)", () => {
+  test.each([
+    ["Bearer", `Bearer ${MIXED_CASE_TOKEN}`],
+    ["bearer", `bearer ${MIXED_CASE_TOKEN}`],
+    ["BEARER", `BEARER ${MIXED_CASE_TOKEN}`],
+    ["BeArEr", `BeArEr ${MIXED_CASE_TOKEN}`],
+    ["bEARER", `bEARER ${MIXED_CASE_TOKEN}`],
+  ])("scheme %s → token extracted verbatim, case preserved", (_label, header) => {
+    expect(siteShapeExtract(header)).toBe(MIXED_CASE_TOKEN);
+  });
+
+  test("wrong scheme keyword (not Bearer) → rejected regardless of case", () => {
+    expect(siteShapeExtract(`Basic ${MIXED_CASE_TOKEN}`)).toBeNull();
+    expect(siteShapeExtract(`Digest ${MIXED_CASE_TOKEN}`)).toBeNull();
+  });
+
+  test("missing header → rejected", () => {
+    expect(siteShapeExtract(null)).toBeNull();
+  });
+
+  test("scheme with no token → empty string (site's own 'empty bearer token' check catches this)", () => {
+    expect(siteShapeExtract("Bearer ")).toBe("");
+    expect(siteShapeExtract("bearer ")).toBe("");
+  });
+
+  test("extra internal whitespace after the scheme is tolerated (trim absorbs it), casing still ignored", () => {
+    expect(siteShapeExtract(`bearer   ${MIXED_CASE_TOKEN}`)).toBe(MIXED_CASE_TOKEN);
+    expect(siteShapeExtract(`Bearer\t${MIXED_CASE_TOKEN}`)).toBe(MIXED_CASE_TOKEN);
+  });
+});
+
+describe("H1.1 — admin-auth.ts extractBearerToken (the documented shared helper)", () => {
+  function reqWith(header: string | undefined): Request {
+    return new Request("http://127.0.0.1/admin/probe", {
+      headers: header !== undefined ? { authorization: header } : {},
+    });
+  }
+
+  test.each([
+    ["Bearer", `Bearer ${MIXED_CASE_TOKEN}`],
+    ["bearer", `bearer ${MIXED_CASE_TOKEN}`],
+    ["BeArEr", `BeArEr ${MIXED_CASE_TOKEN}`],
+  ])("scheme %s → extractBearerToken returns the token verbatim", (_label, header) => {
+    expect(extractBearerToken(reqWith(header))).toBe(MIXED_CASE_TOKEN);
+  });
+
+  test("missing Authorization header → AdminAuthError(401)", () => {
+    expect(() => extractBearerToken(reqWith(undefined))).toThrow(/missing Authorization header/);
+  });
+
+  test("non-Bearer scheme → AdminAuthError(401)", () => {
+    expect(() => extractBearerToken(reqWith(`Basic ${MIXED_CASE_TOKEN}`))).toThrow(
+      /Authorization header must be 'Bearer <token>'/,
+    );
+  });
+});