@openparachute/hub 0.7.6 → 0.7.7-rc.13

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>'/,
+    );
+  });
+});

package/src/__tests__/chrome-strip.test.ts

@@ -99,6 +99,20 @@ describe("shouldInjectChrome", () => {
     expect(shouldInjectChrome("/surface/notes-archive/")).toBe(true);
   });
 
+  test("default: opts out the app's surface mount at /surface/parachute/* (W2-12)", () => {
+    expect(shouldInjectChrome("/surface/parachute")).toBe(false);
+    expect(shouldInjectChrome("/surface/parachute/")).toBe(false);
+    expect(shouldInjectChrome("/surface/parachute/index.html")).toBe(false);
+    expect(shouldInjectChrome("/surface/parachute/assets/index-XXX.js")).toBe(false);
+  });
+
+  test("the /surface/parachute/ opt-out does not over-match sibling paths", () => {
+    // `/surface/parachutes` must NOT match `/surface/parachute/` — the slash
+    // boundary check applies to the new entry the same as the legacy one.
+    expect(shouldInjectChrome("/surface/parachutes")).toBe(true);
+    expect(shouldInjectChrome("/surface/parachute-club/")).toBe(true);
+  });
+
   test("custom opt-out list is honored", () => {
     expect(shouldInjectChrome("/foo/bar", ["/foo/"])).toBe(false);
     expect(shouldInjectChrome("/baz", ["/foo/"])).toBe(true);
@@ -111,8 +125,11 @@ describe("shouldInjectChrome", () => {
     expect(shouldInjectChrome("/foo/bar", ["/foo"])).toBe(false);
   });
 
-  test("the canonical opt-out list contains /surface/notes/", () => {
+  test("the canonical opt-out list contains BOTH /surface/notes/ and /surface/parachute/", () => {
+    // W2-12 is additive: the legacy notes-ui mount keeps its opt-out for
+    // existing installs; the renamed app-surface mount gets its own.
     expect(CHROME_OPT_OUT_PREFIXES).toContain("/surface/notes/");
+    expect(CHROME_OPT_OUT_PREFIXES).toContain("/surface/parachute/");
   });
 });
 

package/src/__tests__/doctor.test.ts

@@ -502,7 +502,7 @@ describe("doctor — canonical-port-drift detection (read-only)", () => {
   test("a non-canonical port + a duplicate-port pair → port-drift WARNs naming the services", async () => {
     const h = makeHarness();
     try {
-      // scribe drifted off 1943 onto 1944; agent also squats 1944 (a collision).
+      // Scribe drifted off 1943 onto Surface's canonical 1946 (a collision).
       writeManifestRows(h.manifestPath, [
         {
           name: "parachute-vault",
@@ -511,21 +511,17 @@ describe("doctor — canonical-port-drift detection (read-only)", () => {
           health: "/h",
           version: "1",
         },
-        { name: "parachute-scribe", port: 1944, paths: ["/scribe"], health: "/h", version: "1" },
-        { name: "parachute-agent", port: 1944, paths: ["/agent"], health: "/h", version: "1" },
+        { name: "parachute-scribe", port: 1946, paths: ["/scribe"], health: "/h", version: "1" },
+        { name: "parachute-surface", port: 1946, paths: ["/surface"], health: "/h", version: "1" },
       ]);
       seedOperatorToken(h.configDir);
       const { code, checks } = await runDoctor(h, healthyDeps());
       const pd = byName(checks, "port-drift");
       expect(pd?.status).toBe("warn");
-      // Names the drifted service AND the colliding pair.
       expect(pd?.detail).toContain("scribe");
-      expect(pd?.detail).toContain("1944");
-      expect(pd?.detail).toContain("parachute-scribe + parachute-agent");
+      expect(pd?.detail).toContain("1946");
+      expect(pd?.detail).toContain("parachute-scribe + parachute-surface");
       expect(pd?.fix).toBe("parachute doctor --fix");
-      // Drift is advisory — exit stays 0 (a WARN, not a FAIL). The duplicate
-      // rows also trip modules-alive (both can't bind 1944) but that's expected
-      // for this fixture; we only assert on port-drift here.
       expect([0, 1]).toContain(code);
     } finally {
       h.cleanup();
@@ -732,22 +728,19 @@ describe("doctor --fix — canonical-port repair (confirm-gated, idempotent, non
   test("--fix reports a duplicate-port collision but does not auto-resolve it", async () => {
     const h = makeHarness();
     try {
-      // Two services collide on 1944; neither is on its canonical slot. The
-      // diff fixes the canonical drift; the collision is reported, not guessed.
+      // Two supported services collide on unassigned 1945; both are off canonical.
       writeManifestRows(h.manifestPath, [
-        { name: "parachute-scribe", port: 1944, paths: ["/scribe"], health: "/h", version: "1" },
-        { name: "parachute-agent", port: 1944, paths: ["/agent"], health: "/h", version: "1" },
+        { name: "parachute-scribe", port: 1945, paths: ["/scribe"], health: "/h", version: "1" },
+        { name: "parachute-surface", port: 1945, paths: ["/surface"], health: "/h", version: "1" },
       ]);
       const { code, lines } = await runFix(h, {}, { yes: true });
       const text = lines.join("\n");
       expect(text.toLowerCase()).toContain("shared by");
-      expect(text).toContain("parachute-scribe + parachute-agent");
-      // scribe → 1943 and agent → 1941 are both off 1944, so after the rewrite
-      // they no longer collide; fix applied, exit 0.
+      expect(text).toContain("parachute-scribe + parachute-surface");
       expect(code).toBe(0);
       const rows = readRows(h.manifestPath);
       expect(rows.find((r) => r.name === "parachute-scribe")?.port).toBe(1943);
-      expect(rows.find((r) => r.name === "parachute-agent")?.port).toBe(1941);
+      expect(rows.find((r) => r.name === "parachute-surface")?.port).toBe(1946);
     } finally {
       h.cleanup();
     }

package/src/__tests__/door-contract-parity.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, test } from "bun:test";
+import {
+  ACCESS_TOKEN_TTL_SECONDS as CONTRACT_ACCESS_TTL,
+  ACCOUNT_SELF_ADMIN_SCOPE as CONTRACT_ACCOUNT_ADMIN,
+  ACCOUNT_SELF_READ_SCOPE as CONTRACT_ACCOUNT_READ,
+  REFRESH_GRACE_MS as CONTRACT_REFRESH_GRACE,
+  REFRESH_TOKEN_TTL_MS as CONTRACT_REFRESH_TTL,
+  hasAccountScope,
+} from "@openparachute/door-contract";
+import { ACCESS_TOKEN_TTL_SECONDS, REFRESH_GRACE_MS, REFRESH_TOKEN_TTL_MS } from "../jwt-sign.ts";
+import { ACCOUNT_SELF_ADMIN_SCOPE, ACCOUNT_SELF_READ_SCOPE } from "../scope-explanations.ts";
+
+/**
+ * Drift detector for the shared door contract (Cloud+Hub shared-core campaign,
+ * parachute-cloud#116, Phase A). The hub's issuer constants + account-scope
+ * strings are duplicated in `@openparachute/door-contract` (the hosted cloud
+ * door duplicates them too). These assertions bind the hub's LIVE runtime values
+ * to the shared canon — no runtime code path is changed by this test, but any
+ * future divergence between the hub's issuer and the shared contract fails here,
+ * forcing the change through the shared package (and thus the cloud twin).
+ *
+ * When the hub adopts the contract at runtime (Phase B — `jwt-sign.ts` imports
+ * these constants instead of re-declaring them), these become identity checks;
+ * until then they are the guardrail.
+ */
+describe("door-contract parity — token constants", () => {
+  test("the hub's issuer TTL/grace equal the shared contract", () => {
+    expect(ACCESS_TOKEN_TTL_SECONDS).toBe(CONTRACT_ACCESS_TTL);
+    expect(REFRESH_TOKEN_TTL_MS).toBe(CONTRACT_REFRESH_TTL);
+    expect(REFRESH_GRACE_MS).toBe(CONTRACT_REFRESH_GRACE);
+  });
+});
+
+describe("door-contract parity — account scopes", () => {
+  test("the hub's account scope strings equal the shared contract", () => {
+    expect(ACCOUNT_SELF_ADMIN_SCOPE).toBe(CONTRACT_ACCOUNT_ADMIN);
+    expect(ACCOUNT_SELF_READ_SCOPE).toBe(CONTRACT_ACCOUNT_READ);
+  });
+
+  test("the shared checker agrees with the hub's admin⊇read intent", () => {
+    // The hub's `/account/*` gate treats `account:self:admin` as satisfying a
+    // read requirement (scope-explanations.ts). The shared checker must too.
+    expect(hasAccountScope([ACCOUNT_SELF_ADMIN_SCOPE], "self", "read")).toBe(true);
+    expect(hasAccountScope([ACCOUNT_SELF_READ_SCOPE], "self", "admin")).toBe(false);
+  });
+});

package/src/__tests__/hub-command.test.ts

@@ -12,9 +12,15 @@ import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { hub, hubSetOrigin, hubSetRootRedirect, rewriteCaddyfileHost } from "../commands/hub.ts";
+import {
+  hub,
+  hubSetOrigin,
+  hubSetRootMode,
+  hubSetRootRedirect,
+  rewriteCaddyfileHost,
+} from "../commands/hub.ts";
 import { hubDbPath, openHubDb } from "../hub-db.ts";
-import { getHubOrigin, getRootRedirect } from "../hub-settings.ts";
+import { getHubOrigin, getRootMode, getRootRedirect } from "../hub-settings.ts";
 import type { CommandResult } from "../tailscale/run.ts";
 
 describe("parachute hub set-origin", () => {
@@ -498,3 +504,65 @@ describe("parachute hub set-root-redirect", () => {
     expect(persisted()).toBe("/surface/via-dispatcher");
   });
 });
+
+describe("parachute hub set-root-mode", () => {
+  let dir: string;
+  let log: string[];
+  const collect = (line: string) => log.push(line);
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "hub-set-root-mode-"));
+    log = [];
+  });
+  afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+  function persisted(): string | null {
+    const db = openHubDb(hubDbPath(dir));
+    try {
+      return getRootMode(db);
+    } finally {
+      db.close();
+    }
+  }
+
+  test("persists serve-app to hub_settings.root_mode", async () => {
+    const code = await hubSetRootMode(["serve-app"], { configDir: dir, log: collect });
+    expect(code).toBe(0);
+    expect(persisted()).toBe("serve-app");
+    expect(log.join("\n")).toMatch(/serves the Parachute app/);
+  });
+
+  test("`redirect` stores as absence (the default), clearing any row", async () => {
+    await hubSetRootMode(["serve-app"], { configDir: dir, log: collect });
+    const code = await hubSetRootMode(["redirect"], { configDir: dir, log: collect });
+    expect(code).toBe(0);
+    expect(persisted()).toBeNull();
+  });
+
+  test("--clear deletes the row", async () => {
+    await hubSetRootMode(["serve-app"], { configDir: dir, log: collect });
+    const code = await hubSetRootMode(["--clear"], { configDir: dir, log: collect });
+    expect(code).toBe(0);
+    expect(persisted()).toBeNull();
+  });
+
+  test("rejects an unknown mode without writing", async () => {
+    for (const bad of ["serveapp", "SERVE-APP", "app", "/surface/x"]) {
+      const code = await hubSetRootMode([bad], { configDir: dir, log: collect });
+      expect(code).toBe(1);
+      expect(persisted()).toBeNull();
+    }
+  });
+
+  test("usage error (exit 1) when no mode + no --clear", async () => {
+    const code = await hubSetRootMode([], { configDir: dir, log: collect });
+    expect(code).toBe(1);
+    expect(persisted()).toBeNull();
+  });
+
+  test("routed through the `hub` dispatcher", async () => {
+    const code = await hub(["set-root-mode", "serve-app"], { configDir: dir, log: collect });
+    expect(code).toBe(0);
+    expect(persisted()).toBe("serve-app");
+  });
+});