npm - @openparachute/hub - Versions diffs - 0.5.14-rc.2 → 0.5.14-rc.21 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (106) hide show

package/README.md +109 -15
package/package.json +7 -3
package/src/__tests__/account-home-ui.test.ts +251 -15
package/src/__tests__/account-vault-token.test.ts +355 -0
package/src/__tests__/admin-vaults.test.ts +70 -4
package/src/__tests__/api-mint-token.test.ts +693 -5
package/src/__tests__/api-modules-config.test.ts +16 -10
package/src/__tests__/api-modules-ops.test.ts +45 -0
package/src/__tests__/api-modules.test.ts +92 -75
package/src/__tests__/api-ready.test.ts +135 -0
package/src/__tests__/api-revoke-token.test.ts +384 -0
package/src/__tests__/api-users.test.ts +7 -2
package/src/__tests__/auth.test.ts +157 -30
package/src/__tests__/cli.test.ts +44 -5
package/src/__tests__/cloudflare-detect.test.ts +60 -5
package/src/__tests__/expose-2fa-warning.test.ts +31 -17
package/src/__tests__/expose-auth-preflight.test.ts +71 -72
package/src/__tests__/expose-cloudflare.test.ts +582 -11
package/src/__tests__/expose-interactive.test.ts +10 -4
package/src/__tests__/expose-public-auto.test.ts +5 -1
package/src/__tests__/expose.test.ts +52 -2
package/src/__tests__/hub-server.test.ts +396 -10
package/src/__tests__/hub.test.ts +85 -6
package/src/__tests__/init.test.ts +928 -0
package/src/__tests__/lifecycle.test.ts +464 -2
package/src/__tests__/migrate.test.ts +433 -51
package/src/__tests__/oauth-handlers.test.ts +1252 -83
package/src/__tests__/oauth-ui.test.ts +12 -1
package/src/__tests__/operator-token-issuer-self-heal.test.ts +412 -0
package/src/__tests__/proxy-error-ui.test.ts +212 -0
package/src/__tests__/proxy-state.test.ts +192 -0
package/src/__tests__/resource-binding.test.ts +97 -0
package/src/__tests__/scope-explanations.test.ts +77 -12
package/src/__tests__/services-manifest.test.ts +122 -4
package/src/__tests__/setup-wizard.test.ts +633 -53
package/src/__tests__/status.test.ts +36 -0
package/src/__tests__/two-factor-flow.test.ts +602 -0
package/src/__tests__/two-factor.test.ts +183 -0
package/src/__tests__/upgrade.test.ts +78 -1
package/src/__tests__/users.test.ts +68 -0
package/src/__tests__/vault-auth-status.test.ts +312 -11
package/src/__tests__/vault-hub-origin-env.test.ts +263 -0
package/src/__tests__/wizard.test.ts +372 -0
package/src/account-home-ui.ts +488 -38
package/src/account-vault-token.ts +282 -0
package/src/admin-handlers.ts +159 -4
package/src/admin-login-ui.ts +49 -5
package/src/admin-vaults.ts +48 -15
package/src/api-account.ts +14 -0
package/src/api-mint-token.ts +132 -24
package/src/api-modules-ops.ts +49 -11
package/src/api-modules.ts +29 -12
package/src/api-ready.ts +102 -0
package/src/api-revoke-token.ts +107 -21
package/src/api-users.ts +29 -3
package/src/cli.ts +112 -25
package/src/clients.ts +18 -6
package/src/cloudflare/config.ts +10 -4
package/src/cloudflare/detect.ts +82 -20
package/src/commands/auth.ts +165 -24
package/src/commands/expose-2fa-warning.ts +34 -32
package/src/commands/expose-auth-preflight.ts +89 -78
package/src/commands/expose-cloudflare.ts +471 -16
package/src/commands/expose-interactive.ts +10 -11
package/src/commands/expose-public-auto.ts +6 -4
package/src/commands/expose.ts +8 -0
package/src/commands/init.ts +594 -0
package/src/commands/install.ts +33 -2
package/src/commands/lifecycle.ts +386 -17
package/src/commands/migrate.ts +293 -41
package/src/commands/status.ts +22 -0
package/src/commands/upgrade.ts +55 -11
package/src/commands/wizard.ts +847 -0
package/src/env-file.ts +10 -0
package/src/help.ts +157 -15
package/src/hub-db.ts +39 -1
package/src/hub-server.ts +119 -13
package/src/hub-settings.ts +11 -0
package/src/hub.ts +82 -14
package/src/oauth-handlers.ts +298 -21
package/src/oauth-ui.ts +10 -0
package/src/operator-token.ts +151 -0
package/src/pending-login.ts +116 -0
package/src/proxy-error-ui.ts +506 -0
package/src/proxy-state.ts +131 -0
package/src/rate-limit.ts +51 -0
package/src/resource-binding.ts +134 -0
package/src/scope-attenuation.ts +85 -0
package/src/scope-explanations.ts +131 -14
package/src/services-manifest.ts +112 -0
package/src/setup-wizard.ts +738 -125
package/src/tailscale/run.ts +28 -11
package/src/totp.ts +201 -0
package/src/two-factor-handlers.ts +287 -0
package/src/two-factor-store.ts +181 -0
package/src/two-factor-ui.ts +462 -0
package/src/users.ts +58 -0
package/src/vault/auth-status.ts +200 -25
package/src/vault-hub-origin-env.ts +163 -0
package/web/ui/dist/assets/index-BiBlvEaj.css +1 -0
package/web/ui/dist/assets/index-CIN3mnmf.js +61 -0
package/web/ui/dist/index.html +2 -2
package/src/__tests__/vault-tokens-create-interactive.test.ts +0 -183
package/src/commands/vault-tokens-create-interactive.ts +0 -143
package/web/ui/dist/assets/index-7DtAXz7y.css +0 -1
package/web/ui/dist/assets/index-tRmPbbC7.js +0 -61

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

@@ -23,6 +23,7 @@ import {
   getDefaultOperationsRegistry,
 } from "../api-modules-ops.ts";
 import { CSRF_COOKIE_NAME, CSRF_FIELD_NAME } from "../csrf.ts";
+import { type ExposeState, readExposeState, writeExposeState } from "../expose-state.ts";
 import { hubDbPath, openHubDb } from "../hub-db.ts";
 import { hubFetch } from "../hub-server.ts";
 import { getSetting, setSetting } from "../hub-settings.ts";
@@ -36,6 +37,7 @@ import {
   handleSetupGet,
   handleSetupInstallPost,
   handleSetupVaultPost,
+  postVaultImportImpl,
 } from "../setup-wizard.ts";
 import { Supervisor } from "../supervisor.ts";
 import { createUser, getUserByUsername, userCount } from "../users.ts";
@@ -43,6 +45,20 @@ import { createUser, getUserByUsername, userCount } from "../users.ts";
 interface Harness {
   dir: string;
   manifestPath: string;
+  /**
+   * Hermetic expose-state reader scoped to the harness's tmp dir. The
+   * production `readExposeState()` defaults to the operator's real
+   * `~/.parachute/expose-state.json` (a module-load constant), so a
+   * wizard test that omits an injected reader would auto-seed
+   * `setup_expose_mode` from the developer's LIVE exposure (hub#406) and
+   * flip expose-step assertions nondeterministically. Threading this
+   * harness reader keeps every wizard test isolated from the real
+   * filesystem — same isolation the harness already gives DB + manifest.
+   * Defaults to "no live exposure" (the tmp file doesn't exist) unless a
+   * test writes one via `writeExposeState(state, h.exposeStatePath)`.
+   */
+  exposeStatePath: string;
+  readExposeStateFn: () => ExposeState | undefined;
   cleanup: () => void;
 }
@@ -51,9 +67,12 @@ function makeHarness(): Harness {
   writeFileSync(join(dir, "hub.html"), "<html>discovery</html>");
   const manifestPath = join(dir, "services.json");
   writeManifest({ services: [] }, manifestPath);
+  const exposeStatePath = join(dir, "expose-state.json");
   return {
     dir,
     manifestPath,
+    exposeStatePath,
+    readExposeStateFn: () => readExposeState(exposeStatePath),
     cleanup: () => rmSync(dir, { recursive: true, force: true }),
   };
 }
@@ -123,7 +142,11 @@ describe("deriveWizardState", () => {
   test("welcome step when no admin and no vault", () => {
     const db = openHubDb(hubDbPath(h.dir));
     try {
-      const s = deriveWizardState({ db, manifestPath: h.manifestPath });
+      const s = deriveWizardState({
+        db,
+        manifestPath: h.manifestPath,
+        readExposeStateFn: h.readExposeStateFn,
+      });
       expect(s.step).toBe("welcome");
       expect(s.hasAdmin).toBe(false);
       expect(s.hasVault).toBe(false);
@@ -136,7 +159,11 @@ describe("deriveWizardState", () => {
     const db = openHubDb(hubDbPath(h.dir));
     try {
       await createUser(db, "owner", "pw");
-      const s = deriveWizardState({ db, manifestPath: h.manifestPath });
+      const s = deriveWizardState({
+        db,
+        manifestPath: h.manifestPath,
+        readExposeStateFn: h.readExposeStateFn,
+      });
       expect(s.step).toBe("vault");
       expect(s.hasAdmin).toBe(true);
       expect(s.hasVault).toBe(false);
@@ -163,7 +190,11 @@ describe("deriveWizardState", () => {
         },
         h.manifestPath,
       );
-      const s = deriveWizardState({ db, manifestPath: h.manifestPath });
+      const s = deriveWizardState({
+        db,
+        manifestPath: h.manifestPath,
+        readExposeStateFn: h.readExposeStateFn,
+      });
       expect(s.step).toBe("expose");
       expect(s.hasAdmin).toBe(true);
       expect(s.hasVault).toBe(true);
@@ -200,7 +231,12 @@ describe("deriveWizardState", () => {
       );
       // Simulate Render env. detectAutoExposeMode reads RENDER_EXTERNAL_URL.
       const renderEnv = { RENDER_EXTERNAL_URL: "https://parachute-hub.onrender.com" };
-      const s = deriveWizardState({ db, manifestPath: h.manifestPath, env: renderEnv });
+      const s = deriveWizardState({
+        db,
+        manifestPath: h.manifestPath,
+        env: renderEnv,
+        readExposeStateFn: h.readExposeStateFn,
+      });
       expect(s.step).toBe("done");
       expect(s.hasExposeMode).toBe(true);
     } finally {
@@ -226,7 +262,12 @@ describe("deriveWizardState", () => {
         },
         h.manifestPath,
       );
-      const s = deriveWizardState({ db, manifestPath: h.manifestPath, env: {} });
+      const s = deriveWizardState({
+        db,
+        manifestPath: h.manifestPath,
+        env: {},
+        readExposeStateFn: h.readExposeStateFn,
+      });
       // Local install path — the operator still gets to choose
       expect(s.step).toBe("expose");
       expect(s.hasExposeMode).toBe(false);
@@ -235,6 +276,188 @@ describe("deriveWizardState", () => {
     }
   });
+  test("auto-seeds expose mode from a live `parachute expose tailnet` (hub#406 team-onboarding bug)", async () => {
+    // Team-onboarding bug: an operator ran `parachute expose tailnet`
+    // BEFORE opening the wizard. That writes expose-state.json
+    // (layer=tailnet) but never the `setup_expose_mode` hub_setting —
+    // the two are orthogonal axes. Pre-fix, the wizard consulted only
+    // the setting and re-rendered "How will this hub be reached?" though
+    // tailnet was already live. deriveWizardState now reads the live
+    // exposure layer and auto-seeds the setting, so the expose step is
+    // treated as satisfied and the wizard advances to done.
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      await createUser(db, "owner", "pw");
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-vault",
+              version: "0.1.0",
+              port: 1940,
+              paths: ["/vault/default"],
+              health: "/health",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      // Simulate `parachute expose tailnet`: write a real expose-state
+      // file (round-trips through readExposeState's validator) into the
+      // harness tmp path. No env signal (not Render/Fly), no setting.
+      writeExposeState(
+        {
+          version: 1,
+          layer: "tailnet",
+          mode: "path",
+          canonicalFqdn: "my-mac.tailnet-name.ts.net",
+          port: 1939,
+          funnel: false,
+          entries: [],
+        },
+        h.exposeStatePath,
+      );
+      const s = deriveWizardState({
+        db,
+        manifestPath: h.manifestPath,
+        env: {},
+        readExposeStateFn: h.readExposeStateFn,
+      });
+      expect(s.step).toBe("done");
+      expect(s.hasExposeMode).toBe(true);
+      // The setting was auto-seeded from the live exposure layer.
+      expect(getSetting(db, "setup_expose_mode")).toBe("tailnet");
+    } finally {
+      db.close();
+    }
+  });
+  test("auto-seeds expose mode = public from a live public exposure", async () => {
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      await createUser(db, "owner", "pw");
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-vault",
+              version: "0.1.0",
+              port: 1940,
+              paths: ["/vault/default"],
+              health: "/health",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      writeExposeState(
+        {
+          version: 1,
+          layer: "public",
+          mode: "path",
+          canonicalFqdn: "hub.example.com",
+          port: 1939,
+          funnel: true,
+          entries: [],
+        },
+        h.exposeStatePath,
+      );
+      const s = deriveWizardState({
+        db,
+        manifestPath: h.manifestPath,
+        env: {},
+        readExposeStateFn: h.readExposeStateFn,
+      });
+      expect(s.step).toBe("done");
+      expect(s.hasExposeMode).toBe(true);
+      expect(getSetting(db, "setup_expose_mode")).toBe("public");
+    } finally {
+      db.close();
+    }
+  });
+  test("still asks the expose step when no live exposure + no setting (unchanged)", async () => {
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      await createUser(db, "owner", "pw");
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-vault",
+              version: "0.1.0",
+              port: 1940,
+              paths: ["/vault/default"],
+              health: "/health",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      // No env signal, no expose-state file written (reader returns
+      // undefined), no setting → the operator still gets the expose step.
+      const s = deriveWizardState({
+        db,
+        manifestPath: h.manifestPath,
+        env: {},
+        readExposeStateFn: h.readExposeStateFn,
+      });
+      expect(s.step).toBe("expose");
+      expect(s.hasExposeMode).toBe(false);
+      expect(getSetting(db, "setup_expose_mode")).toBeUndefined();
+    } finally {
+      db.close();
+    }
+  });
+  test("an explicit setup_expose_mode wins over a live exposure (no clobber)", async () => {
+    // If the operator already answered the expose step (or it was seeded
+    // by a prior call), a later live-exposure read must not overwrite the
+    // recorded answer. Guards the `=== undefined` gate.
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      await createUser(db, "owner", "pw");
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-vault",
+              version: "0.1.0",
+              port: 1940,
+              paths: ["/vault/default"],
+              health: "/health",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      setSetting(db, "setup_expose_mode", "localhost");
+      writeExposeState(
+        {
+          version: 1,
+          layer: "public",
+          mode: "path",
+          canonicalFqdn: "hub.example.com",
+          port: 1939,
+          funnel: true,
+          entries: [],
+        },
+        h.exposeStatePath,
+      );
+      const s = deriveWizardState({
+        db,
+        manifestPath: h.manifestPath,
+        env: {},
+        readExposeStateFn: h.readExposeStateFn,
+      });
+      expect(s.step).toBe("done");
+      // Recorded answer is preserved, not overwritten by the live layer.
+      expect(getSetting(db, "setup_expose_mode")).toBe("localhost");
+    } finally {
+      db.close();
+    }
+  });
   test("done step once admin + vault + expose mode all exist", async () => {
     const db = openHubDb(hubDbPath(h.dir));
     try {
@@ -254,7 +477,11 @@ describe("deriveWizardState", () => {
         h.manifestPath,
       );
       setSetting(db, "setup_expose_mode", "localhost");
-      const s = deriveWizardState({ db, manifestPath: h.manifestPath });
+      const s = deriveWizardState({
+        db,
+        manifestPath: h.manifestPath,
+        readExposeStateFn: h.readExposeStateFn,
+      });
       expect(s.step).toBe("done");
       expect(s.hasAdmin).toBe(true);
       expect(s.hasVault).toBe(true);
@@ -282,6 +509,7 @@ describe("handleSetupGet", () => {
         db,
         manifestPath: h.manifestPath,
         configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
         issuer: "https://hub.example",
         registry: getDefaultOperationsRegistry(),
       });
@@ -303,6 +531,7 @@ describe("handleSetupGet", () => {
         db,
         manifestPath: h.manifestPath,
         configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
         issuer: "https://hub.example",
         registry: getDefaultOperationsRegistry(),
       });
@@ -353,6 +582,7 @@ describe("handleSetupGet", () => {
         db,
         manifestPath: h.manifestPath,
         configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
         issuer: "https://hub.example",
         registry: getDefaultOperationsRegistry(),
       });
@@ -385,6 +615,7 @@ describe("handleSetupGet", () => {
         db,
         manifestPath: h.manifestPath,
         configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
         issuer: "https://hub.example",
         registry: getDefaultOperationsRegistry(),
       });
@@ -433,6 +664,7 @@ describe("handleSetupGet", () => {
           db,
           manifestPath: h.manifestPath,
           configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
           issuer: "https://hub.example",
           registry: getDefaultOperationsRegistry(),
         },
@@ -482,6 +714,7 @@ describe("handleSetupGet", () => {
           db,
           manifestPath: h.manifestPath,
           configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
           issuer: "https://hub.example",
           registry: getDefaultOperationsRegistry(),
         },
@@ -523,6 +756,7 @@ describe("handleSetupGet", () => {
           db,
           manifestPath: h.manifestPath,
           configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
           issuer: "https://hub.example",
           registry: getDefaultOperationsRegistry(),
         },
@@ -547,6 +781,7 @@ describe("handleSetupGet", () => {
         db,
         manifestPath: h.manifestPath,
         configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
         issuer: "https://hub.example",
         registry: reg,
       });
@@ -576,6 +811,7 @@ describe("handleSetupGet", () => {
         db,
         manifestPath: h.manifestPath,
         configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
         issuer: "https://hub.example",
         registry: reg,
       });
@@ -607,6 +843,7 @@ describe("handleSetupAccountPost", () => {
         db,
         manifestPath: h.manifestPath,
         configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
         issuer: "https://hub.example",
         registry: getDefaultOperationsRegistry(),
       });
@@ -631,6 +868,7 @@ describe("handleSetupAccountPost", () => {
           db,
           manifestPath: h.manifestPath,
           configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
           issuer: "https://hub.example",
           registry: getDefaultOperationsRegistry(),
         },
@@ -659,6 +897,7 @@ describe("handleSetupAccountPost", () => {
         db,
         manifestPath: h.manifestPath,
         configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
         issuer: "https://hub.example",
         registry: getDefaultOperationsRegistry(),
       });
@@ -679,6 +918,7 @@ describe("handleSetupAccountPost", () => {
           db,
           manifestPath: h.manifestPath,
           configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
           issuer: "https://hub.example",
           registry: getDefaultOperationsRegistry(),
         },
@@ -711,6 +951,7 @@ describe("handleSetupAccountPost", () => {
           db,
           manifestPath: h.manifestPath,
           configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
           issuer: "https://hub.example",
           registry: getDefaultOperationsRegistry(),
         },
@@ -730,6 +971,7 @@ describe("handleSetupAccountPost", () => {
         db,
         manifestPath: h.manifestPath,
         configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
         issuer: "https://hub.example",
         registry: getDefaultOperationsRegistry(),
       });
@@ -750,6 +992,7 @@ describe("handleSetupAccountPost", () => {
           db,
           manifestPath: h.manifestPath,
           configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
           issuer: "https://hub.example",
           registry: getDefaultOperationsRegistry(),
         },
@@ -774,10 +1017,15 @@ describe("handleSetupVaultPost", () => {
   });
   afterEach(() => h.cleanup());
-  test("requires a supervisor (CLI mode rejects)", async () => {
+  test("requires a supervisor (CLI mode rejects create/import; allows skip — hub#168 Cut 2)", async () => {
     const db = openHubDb(hubDbPath(h.dir));
     try {
       await createUser(db, "owner", "pw");
+      // Bare POST (no CSRF, no session) still 400s, but on the new
+      // CSRF-first ordering it stops at the CSRF check rather than the
+      // supervisor check. That's correct posture — refuse the
+      // unauthenticated request before tendering an architectural
+      // explanation.
       const post = await handleSetupVaultPost(
         req("/admin/setup/vault", {
           method: "POST",
@@ -788,13 +1036,15 @@ describe("handleSetupVaultPost", () => {
           db,
           manifestPath: h.manifestPath,
           configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
           issuer: "https://hub.example",
           registry: getDefaultOperationsRegistry(),
         },
       );
       expect(post.status).toBe(400);
       const html = await post.text();
-      expect(html).toContain("supervisor unavailable");
+      // CSRF-first: the bare request bounces at the CSRF gate.
+      expect(html).toContain("Invalid form submission");
     } finally {
       db.close();
     }
@@ -808,6 +1058,7 @@ describe("handleSetupVaultPost", () => {
         db,
         manifestPath: h.manifestPath,
         configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
         issuer: "https://hub.example",
         registry: getDefaultOperationsRegistry(),
       });
@@ -827,6 +1078,7 @@ describe("handleSetupVaultPost", () => {
           db,
           manifestPath: h.manifestPath,
           configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
           issuer: "https://hub.example",
           supervisor: makeSupervisor(),
           registry: getDefaultOperationsRegistry(),
@@ -856,6 +1108,7 @@ describe("handleSetupVaultPost", () => {
         db,
         manifestPath: h.manifestPath,
         configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
         issuer: "https://hub.example",
         registry: getDefaultOperationsRegistry(),
       });
@@ -880,6 +1133,7 @@ describe("handleSetupVaultPost", () => {
           db,
           manifestPath: h.manifestPath,
           configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
           issuer: "https://hub.example",
           supervisor: makeSupervisor(),
           registry: getDefaultOperationsRegistry(),
@@ -933,6 +1187,7 @@ describe("handleSetupVaultPost", () => {
         db,
         manifestPath: h.manifestPath,
         configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
         issuer: "https://hub.example",
         registry: getDefaultOperationsRegistry(),
       });
@@ -959,6 +1214,7 @@ describe("handleSetupVaultPost", () => {
           db,
           manifestPath: h.manifestPath,
           configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
           issuer: "https://hub.example",
           supervisor: makeSupervisor(),
           registry: getDefaultOperationsRegistry(),
@@ -1002,6 +1258,7 @@ describe("handleSetupVaultPost", () => {
         db,
         manifestPath: h.manifestPath,
         configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
         issuer: "https://hub.example",
         registry: getDefaultOperationsRegistry(),
       });
@@ -1027,6 +1284,7 @@ describe("handleSetupVaultPost", () => {
           db,
           manifestPath: h.manifestPath,
           configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
           issuer: "https://hub.example",
           supervisor: makeSupervisor(),
           registry: getDefaultOperationsRegistry(),
@@ -1063,6 +1321,7 @@ describe("handleSetupVaultPost", () => {
         db,
         manifestPath: h.manifestPath,
         configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
         issuer: "https://hub.example",
         registry: getDefaultOperationsRegistry(),
       });
@@ -1092,6 +1351,7 @@ describe("handleSetupVaultPost", () => {
           db,
           manifestPath: h.manifestPath,
           configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
           issuer: "https://hub.example",
           supervisor,
           registry: getDefaultOperationsRegistry(),
@@ -1146,6 +1406,7 @@ describe("handleSetupVaultPost", () => {
         db,
         manifestPath: h.manifestPath,
         configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
         issuer: "https://hub.example",
         registry: getDefaultOperationsRegistry(),
       });
@@ -1171,6 +1432,7 @@ describe("handleSetupVaultPost", () => {
           db,
           manifestPath: h.manifestPath,
           configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
           issuer: "https://hub.example",
           supervisor: makeSupervisor(),
           registry: getDefaultOperationsRegistry(),
@@ -1425,6 +1687,7 @@ describe("handleSetupExposePost", () => {
       db,
       manifestPath: h.manifestPath,
       configDir: h.dir,
+      readExposeStateFn: h.readExposeStateFn,
       issuer: "https://hub.example",
       registry: getDefaultOperationsRegistry(),
     });
@@ -1453,6 +1716,7 @@ describe("handleSetupExposePost", () => {
           db,
           manifestPath: h.manifestPath,
           configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
           issuer: "https://hub.example",
           registry: getDefaultOperationsRegistry(),
         },
@@ -1488,6 +1752,7 @@ describe("handleSetupExposePost", () => {
           db,
           manifestPath: h.manifestPath,
           configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
           issuer: "https://hub.example",
           registry: getDefaultOperationsRegistry(),
         },
@@ -1526,6 +1791,7 @@ describe("handleSetupExposePost", () => {
           db,
           manifestPath: h.manifestPath,
           configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
           issuer: "https://hub.example",
           registry: getDefaultOperationsRegistry(),
         },
@@ -1560,6 +1826,7 @@ describe("handleSetupExposePost", () => {
           db,
           manifestPath: h.manifestPath,
           configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
           issuer: "https://hub.example",
           registry: getDefaultOperationsRegistry(),
         },
@@ -1596,6 +1863,7 @@ describe("handleSetupExposePost", () => {
           db,
           manifestPath: h.manifestPath,
           configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
           issuer: "https://hub.example",
           registry: getDefaultOperationsRegistry(),
         },
@@ -1646,6 +1914,7 @@ describe("done screen auto-minted token (hub#272 Item A)", () => {
       db,
       manifestPath: h.manifestPath,
       configDir: h.dir,
+      readExposeStateFn: h.readExposeStateFn,
       issuer: "https://hub.example",
       registry: getDefaultOperationsRegistry(),
     });
@@ -1674,6 +1943,7 @@ describe("done screen auto-minted token (hub#272 Item A)", () => {
           db,
           manifestPath: h.manifestPath,
           configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
           issuer: "https://hub.example",
           registry: getDefaultOperationsRegistry(),
         },
@@ -1720,6 +1990,7 @@ describe("done screen auto-minted token (hub#272 Item A)", () => {
           db,
           manifestPath: h.manifestPath,
           configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
           issuer: "https://hub.example",
           registry: getDefaultOperationsRegistry(),
         },
@@ -1785,16 +2056,21 @@ describe("done screen auto-minted token (hub#272 Item A)", () => {
           db,
           manifestPath: h.manifestPath,
           configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
           issuer: "https://hub.example",
           registry: getDefaultOperationsRegistry(),
         },
       );
       const html = await res.text();
       expect(html).toContain("claude mcp add --transport http parachute-default");
-      // The fallback explanatory text mentions `pvt_...` as a placeholder
-      // but the actual `--header` flag must NOT be appended to the
-      // command line itself.
-      expect(html).toContain("Bearer pvt_");
+      // The fallback explanatory text leads with the OAuth path (no token
+      // needed) and, for headless clients, references a hub JWT placeholder
+      // — NOT the retired `pvt_*` format (gap #4). The `--header` flag must
+      // also NOT be appended to the command line itself.
+      expect(html).toContain("browser OAuth");
+      expect(html).toContain("Bearer &lt;token&gt;");
+      expect(html).not.toContain("pvt_");
+      expect(html).toContain("parachute auth mint-token");
       expect(html).toContain("/admin/tokens");
       // Specifically no Copy button — that's a token-present surface.
       expect(html).not.toContain('id="mcp-cmd"');
@@ -1829,6 +2105,7 @@ describe("done screen auto-minted token (hub#272 Item A)", () => {
         db,
         manifestPath: h.manifestPath,
         configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
         issuer: "https://hub.example",
         registry: getDefaultOperationsRegistry(),
       };
@@ -1885,6 +2162,7 @@ describe("done screen auto-minted token (hub#272 Item A)", () => {
           db,
           manifestPath: h.manifestPath,
           configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
           issuer: "https://hub.example",
           registry: getDefaultOperationsRegistry(),
         },
@@ -1950,6 +2228,7 @@ describe("done screen auto-minted token (hub#272 Item A)", () => {
           db,
           manifestPath: h.manifestPath,
           configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
           issuer: "https://hub.example",
           registry: getDefaultOperationsRegistry(),
         },
@@ -2008,6 +2287,7 @@ describe("done screen auto-minted token (hub#272 Item A)", () => {
           db,
           manifestPath: h.manifestPath,
           configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
           issuer: "https://hub.example",
           registry: getDefaultOperationsRegistry(),
         },
@@ -2069,6 +2349,7 @@ describe("done screen auto-minted token (hub#272 Item A)", () => {
         db,
         manifestPath: h.manifestPath,
         configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
         issuer: "https://hub.example",
         registry: getDefaultOperationsRegistry(),
       });
@@ -2132,6 +2413,7 @@ describe("done screen install tiles (hub#272 Item B)", () => {
           db,
           manifestPath: h.manifestPath,
           configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
           issuer: "https://hub.example",
           registry: getDefaultOperationsRegistry(),
         },
@@ -2162,6 +2444,9 @@ describe("done screen install tiles (hub#272 Item B)", () => {
     const db = openHubDb(hubDbPath(h.dir));
     try {
       const user = await createUser(db, "owner", "pw");
+      // Seed services.json with `parachute-scribe` so the wizard's scribe
+      // install tile renders the already-installed shape. Post-2026-05-27
+      // CURATED trim scribe is the only non-vault install tile.
       writeManifest(
         {
           services: [
@@ -2172,15 +2457,12 @@ describe("done screen install tiles (hub#272 Item B)", () => {
               paths: ["/vault/default"],
               health: "/health",
             },
-            // hub#323: app replaces notes as the wizard's first install tile.
-            // Seeding services.json with `parachute-app` exercises the
-            // already-installed render path on the wizard's first tile.
             {
-              name: "parachute-surface",
-              version: "0.2.0",
-              port: 1946,
-              paths: ["/app", "/.parachute"],
-              health: "/surface/healthz",
+              name: "parachute-scribe",
+              version: "0.4.4",
+              port: 1943,
+              paths: ["/scribe"],
+              health: "/scribe/health",
             },
           ],
         },
@@ -2197,19 +2479,23 @@ describe("done screen install tiles (hub#272 Item B)", () => {
           db,
           manifestPath: h.manifestPath,
           configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
           issuer: "https://hub.example",
           registry: getDefaultOperationsRegistry(),
         },
       );
       const html = await res.text();
       expect(html).toContain("Already installed");
-      expect(html).toContain('action="/admin/setup/install/scribe"');
+      // The scribe tile rendered the installed shape, not the install form.
+      expect(html).not.toContain('action="/admin/setup/install/scribe"');
+      // "Manage in admin" is the secondary link on the already-installed tile.
+      expect(html).toContain("Manage in admin");
     } finally {
       db.close();
     }
   });
-  test("done screen renders op-poll panel when ?op_surface=<id> matches a registry op", async () => {
+  test("done screen renders op-poll panel when ?op_scribe=<id> matches a registry op", async () => {
     const db = openHubDb(hubDbPath(h.dir));
     try {
       const user = await createUser(db, "owner", "pw");
@@ -2229,21 +2515,23 @@ describe("done screen install tiles (hub#272 Item B)", () => {
       );
       setSetting(db, "setup_expose_mode", "localhost");
       const reg = getDefaultOperationsRegistry();
-      // hub#323: op-poll panel rides on the `app` tile now (app is the wizard's
-      // first install tile post-Notes-as-app-migration). Same shape as the
-      // pre-#324 `op_notes=<id>` flow.
-      const op = reg.create("install", "app");
-      reg.update(op.id, { status: "running" }, "running bun add -g @openparachute/app@latest");
+      // Post-2026-05-27 CURATED trim, scribe is the only non-vault wizard
+      // install tile, so it carries the op-poll panel. Same shape as the
+      // prior `op_app=<id>` / `op_notes=<id>` flows — the rendering code
+      // is per-`?op_<short>=<id>` query and tile-row agnostic.
+      const op = reg.create("install", "scribe");
+      reg.update(op.id, { status: "running" }, "running bun add -g @openparachute/scribe@latest");
       const { createSession } = await import("../sessions.ts");
       const session = createSession(db, { userId: user.id });
       const res = handleSetupGet(
-        req(`/admin/setup?just_finished=1&op_surface=${op.id}`, {
+        req(`/admin/setup?just_finished=1&op_scribe=${op.id}`, {
           headers: { cookie: `${SESSION_COOKIE_NAME}=${session.id}` },
         }),
         {
           db,
           manifestPath: h.manifestPath,
           configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
           issuer: "https://hub.example",
           registry: reg,
         },
@@ -2283,6 +2571,7 @@ describe("done screen install tiles (hub#272 Item B)", () => {
         db,
         manifestPath: h.manifestPath,
         configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
         issuer: "https://hub.example",
         registry: getDefaultOperationsRegistry(),
       });
@@ -2293,7 +2582,7 @@ describe("done screen install tiles (hub#272 Item B)", () => {
         return 0;
       };
       const post = await handleSetupInstallPost(
-        req("/admin/setup/install/notes", {
+        req("/admin/setup/install/scribe", {
           method: "POST",
           body: new URLSearchParams({ [CSRF_FIELD_NAME]: csrf }).toString(),
           headers: {
@@ -2301,11 +2590,12 @@ describe("done screen install tiles (hub#272 Item B)", () => {
             cookie: `${CSRF_COOKIE_NAME}=${csrf}; ${SESSION_COOKIE_NAME}=${session.id}`,
           },
         }),
-        "notes",
+        "scribe",
         {
           db,
           manifestPath: h.manifestPath,
           configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
           issuer: "https://hub.example",
           supervisor: makeSupervisor(),
           registry: getDefaultOperationsRegistry(),
@@ -2315,10 +2605,10 @@ describe("done screen install tiles (hub#272 Item B)", () => {
       );
       expect(post.status).toBe(303);
       const location = post.headers.get("location") ?? "";
-      expect(location).toMatch(/^\/admin\/setup\?just_finished=1&op_notes=/);
+      expect(location).toMatch(/^\/admin\/setup\?just_finished=1&op_scribe=/);
       await new Promise((r) => setTimeout(r, 50));
       expect(runCalls.length).toBeGreaterThan(0);
-      expect(runCalls[0]?.join(" ")).toContain("bun add -g @openparachute/notes@latest");
+      expect(runCalls[0]?.join(" ")).toContain("bun add -g @openparachute/scribe@latest");
     } finally {
       db.close();
     }
@@ -2334,6 +2624,7 @@ describe("done screen install tiles (hub#272 Item B)", () => {
         db,
         manifestPath: h.manifestPath,
         configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
         issuer: "https://hub.example",
         registry: getDefaultOperationsRegistry(),
       });
@@ -2352,6 +2643,7 @@ describe("done screen install tiles (hub#272 Item B)", () => {
           db,
           manifestPath: h.manifestPath,
           configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
           issuer: "https://hub.example",
           supervisor: makeSupervisor(),
           registry: getDefaultOperationsRegistry(),
@@ -2379,6 +2671,7 @@ describe("done screen install tiles (hub#272 Item B)", () => {
           db,
           manifestPath: h.manifestPath,
           configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
           issuer: "https://hub.example",
           supervisor: makeSupervisor(),
           registry: getDefaultOperationsRegistry(),
@@ -2400,12 +2693,13 @@ describe("done screen install tiles (hub#272 Item B)", () => {
         db,
         manifestPath: h.manifestPath,
         configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
         issuer: "https://hub.example",
         registry: getDefaultOperationsRegistry(),
       });
       const csrf = setCookie(get, CSRF_COOKIE_NAME) ?? "";
       const post = await handleSetupInstallPost(
-        req("/admin/setup/install/notes", {
+        req("/admin/setup/install/scribe", {
           method: "POST",
           body: new URLSearchParams({ [CSRF_FIELD_NAME]: csrf }).toString(),
           headers: {
@@ -2413,11 +2707,12 @@ describe("done screen install tiles (hub#272 Item B)", () => {
             cookie: `${CSRF_COOKIE_NAME}=${csrf}`,
           },
         }),
-        "notes",
+        "scribe",
         {
           db,
           manifestPath: h.manifestPath,
           configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
           issuer: "https://hub.example",
           supervisor: makeSupervisor(),
           registry: getDefaultOperationsRegistry(),
@@ -2446,6 +2741,7 @@ describe("done screen install tiles (hub#272 Item B)", () => {
           db,
           manifestPath: h.manifestPath,
           configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
           issuer: "https://hub.example",
           registry: getDefaultOperationsRegistry(),
         },
@@ -2479,6 +2775,7 @@ describe("typed vault name (hub#267)", () => {
         db,
         manifestPath: h.manifestPath,
         configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
         issuer: "https://hub.example",
         registry: getDefaultOperationsRegistry(),
       });
@@ -2521,6 +2818,7 @@ describe("typed vault name (hub#267)", () => {
           db,
           manifestPath: h.manifestPath,
           configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
           issuer: "https://hub.example",
           supervisor,
           registry: getDefaultOperationsRegistry(),
@@ -2554,6 +2852,7 @@ describe("typed vault name (hub#267)", () => {
         db,
         manifestPath: h.manifestPath,
         configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
         issuer: "https://hub.example",
         registry: getDefaultOperationsRegistry(),
       });
@@ -2574,6 +2873,7 @@ describe("typed vault name (hub#267)", () => {
           db,
           manifestPath: h.manifestPath,
           configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
           issuer: "https://hub.example",
           supervisor: makeSupervisor(),
           registry: getDefaultOperationsRegistry(),
@@ -2599,6 +2899,7 @@ describe("typed vault name (hub#267)", () => {
         db,
         manifestPath: h.manifestPath,
         configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
         issuer: "https://hub.example",
         registry: getDefaultOperationsRegistry(),
       });
@@ -2639,6 +2940,7 @@ describe("typed vault name (hub#267)", () => {
           db,
           manifestPath: h.manifestPath,
           configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
           issuer: "https://hub.example",
           supervisor,
           registry: getDefaultOperationsRegistry(),
@@ -2701,6 +3003,7 @@ describe("typed vault name (hub#267)", () => {
           db,
           manifestPath: h.manifestPath,
           configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
           issuer: "https://hub.example",
           registry: getDefaultOperationsRegistry(),
         },
@@ -2752,6 +3055,7 @@ describe("typed vault name (hub#267)", () => {
           db,
           manifestPath: h.manifestPath,
           configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
           issuer: "https://hub.example",
           registry: getDefaultOperationsRegistry(),
         },
@@ -2803,6 +3107,7 @@ describe("typed vault name (hub#267)", () => {
           db,
           manifestPath: h.manifestPath,
           configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
           issuer: "https://hub.example",
           registry: getDefaultOperationsRegistry(),
         },
@@ -2873,6 +3178,7 @@ describe("bootstrap token gate (handleSetupAccountPost)", () => {
         db,
         manifestPath: h.manifestPath,
         configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
         issuer: "https://hub.example",
         registry: getDefaultOperationsRegistry(),
       });
@@ -2897,6 +3203,7 @@ describe("bootstrap token gate (handleSetupAccountPost)", () => {
         db,
         manifestPath: h.manifestPath,
         configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
         issuer: "https://hub.example",
         registry: getDefaultOperationsRegistry(),
       });
@@ -2922,6 +3229,7 @@ describe("bootstrap token gate (handleSetupAccountPost)", () => {
         db,
         manifestPath: h.manifestPath,
         configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
         issuer: "https://hub.example",
         registry: getDefaultOperationsRegistry(),
       });
@@ -2943,6 +3251,7 @@ describe("bootstrap token gate (handleSetupAccountPost)", () => {
           db,
           manifestPath: h.manifestPath,
           configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
           issuer: "https://hub.example",
           registry: getDefaultOperationsRegistry(),
         },
@@ -2965,6 +3274,7 @@ describe("bootstrap token gate (handleSetupAccountPost)", () => {
         db,
         manifestPath: h.manifestPath,
         configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
         issuer: "https://hub.example",
         registry: getDefaultOperationsRegistry(),
       });
@@ -2986,6 +3296,7 @@ describe("bootstrap token gate (handleSetupAccountPost)", () => {
           db,
           manifestPath: h.manifestPath,
           configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
           issuer: "https://hub.example",
           registry: getDefaultOperationsRegistry(),
         },
@@ -3015,6 +3326,7 @@ describe("bootstrap token gate (handleSetupAccountPost)", () => {
         db,
         manifestPath: h.manifestPath,
         configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
         issuer: "https://hub.example",
         registry: getDefaultOperationsRegistry(),
       });
@@ -3036,6 +3348,7 @@ describe("bootstrap token gate (handleSetupAccountPost)", () => {
           db,
           manifestPath: h.manifestPath,
           configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
           issuer: "https://hub.example",
           registry: getDefaultOperationsRegistry(),
         },
@@ -3063,6 +3376,7 @@ describe("bootstrap token gate (handleSetupAccountPost)", () => {
         db,
         manifestPath: h.manifestPath,
         configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
         issuer: "https://hub.example",
         registry: getDefaultOperationsRegistry(),
       });
@@ -3084,6 +3398,7 @@ describe("bootstrap token gate (handleSetupAccountPost)", () => {
           db,
           manifestPath: h.manifestPath,
           configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
           issuer: "https://hub.example",
           registry: getDefaultOperationsRegistry(),
         },
@@ -3109,6 +3424,7 @@ describe("bootstrap token gate (handleSetupAccountPost)", () => {
         db,
         manifestPath: h.manifestPath,
         configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
         issuer: "https://hub.example",
         registry: getDefaultOperationsRegistry(),
       });
@@ -3129,6 +3445,7 @@ describe("bootstrap token gate (handleSetupAccountPost)", () => {
           db,
           manifestPath: h.manifestPath,
           configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
           issuer: "https://hub.example",
           registry: getDefaultOperationsRegistry(),
         },
@@ -3175,6 +3492,7 @@ describe("bootstrap token gate (handleSetupAccountPost)", () => {
         db,
         manifestPath: h.manifestPath,
         configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
         issuer: "https://hub.example",
         registry: getDefaultOperationsRegistry(),
       });
@@ -3196,6 +3514,7 @@ describe("bootstrap token gate (handleSetupAccountPost)", () => {
         db,
         manifestPath: h.manifestPath,
         configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
         issuer: "https://hub.example",
         registry: getDefaultOperationsRegistry(),
       };
@@ -3279,6 +3598,7 @@ describe("done screen — 'Start using your vault' tile (hub#342)", () => {
           db,
           manifestPath: h.manifestPath,
           configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
           issuer: "https://hub.example",
           registry: getDefaultOperationsRegistry(),
         },
@@ -3296,7 +3616,14 @@ describe("done screen — 'Start using your vault' tile (hub#342)", () => {
     }
   });
-  test("when app is also installed, the lead tile links to /surface/notes/", async () => {
+  test("lead tile always points at notes.parachute.computer (canonical hosted PWA) regardless of local module installs", async () => {
+    // Pre-2026-05-27 the lead tile flipped to `/surface/notes/` when the
+    // Surface module was installed locally. Aaron's launch-focus
+    // directive: notes.parachute.computer is the canonical user-facing
+    // UI, and the wizard should always point operators at it (rather
+    // than maybe-or-maybe-not-installed local Surface). This test pins
+    // that the lead tile is invariant under the install state of
+    // uncurated modules.
     const db = openHubDb(hubDbPath(h.dir));
     try {
       const user = await createUser(db, "owner", "pw");
@@ -3310,6 +3637,9 @@ describe("done screen — 'Start using your vault' tile (hub#342)", () => {
               paths: ["/vault/default"],
               health: "/health",
             },
+            // Even with parachute-surface installed locally (an uncurated
+            // module post-trim), the lead tile must NOT flip to a local
+            // path.
             {
               name: "parachute-surface",
               version: "0.2.0",
@@ -3332,21 +3662,34 @@ describe("done screen — 'Start using your vault' tile (hub#342)", () => {
           db,
           manifestPath: h.manifestPath,
           configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
           issuer: "https://hub.example",
           registry: getDefaultOperationsRegistry(),
         },
       );
       const html = await res.text();
       expect(html).toContain("Start using your vault");
-      // App installed → primary CTA links to Notes-as-UI inside App.
-      expect(html).toContain('href="/surface/notes/"');
+      // Lead CTA always targets the hosted PWA.
+      expect(html).toContain("https://notes.parachute.computer/add?url=");
       expect(html).toContain("Open Notes");
+      // The pre-trim local-surface fallback is gone — the lead tile does
+      // NOT link to /surface/notes/ anymore.
+      expect(html).not.toContain('href="/surface/notes/"');
     } finally {
       db.close();
     }
   });
-  test("succeeded install op renders a 'Use it now' link pointing at the module's surface", async () => {
+  test("succeeded install op renders 'Manage modules' link (no 'Use it now' for modules without a hosted surface)", async () => {
+    // Pre-2026-05-27 the surface module had a USE_IT_NOW_URLS entry
+    // pointing at `/surface/notes/`, so a succeeded surface install tile
+    // rendered a primary "Use it now" link. Post-trim only scribe + vault
+    // are curated; vault has its own lead tile (above the install row);
+    // scribe doesn't ship a user-facing landing surface today
+    // (scribe#53 tracks the eventual admin SPA), so USE_IT_NOW_URLS is
+    // empty and a succeeded scribe install renders only the "Manage
+    // modules" secondary affordance. Future per-module surfaces can
+    // re-add an entry to that map.
     const db = openHubDb(hubDbPath(h.dir));
     try {
       const user = await createUser(db, "owner", "pw");
@@ -3366,35 +3709,43 @@ describe("done screen — 'Start using your vault' tile (hub#342)", () => {
       );
       setSetting(db, "setup_expose_mode", "localhost");
       const reg = getDefaultOperationsRegistry();
-      const op = reg.create("install", "app");
-      reg.update(op.id, { status: "succeeded" }, "installed @openparachute/app");
+      const op = reg.create("install", "scribe");
+      reg.update(op.id, { status: "succeeded" }, "installed @openparachute/scribe");
       const { createSession } = await import("../sessions.ts");
       const session = createSession(db, { userId: user.id });
       const res = handleSetupGet(
-        req(`/admin/setup?just_finished=1&op_surface=${op.id}`, {
+        req(`/admin/setup?just_finished=1&op_scribe=${op.id}`, {
           headers: { cookie: `${SESSION_COOKIE_NAME}=${session.id}` },
         }),
         {
           db,
           manifestPath: h.manifestPath,
           configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
           issuer: "https://hub.example",
           registry: reg,
         },
       );
       const html = await res.text();
       expect(html).toContain("status: succeeded");
-      // Primary "Use it now" link goes to the app's surface; secondary
-      // "Manage modules" link still present.
-      expect(html).toContain(">Use it now<");
-      expect(html).toContain('href="/surface/notes/"');
+      // No "Use it now" — scribe has no entry in USE_IT_NOW_URLS today.
+      expect(html).not.toContain(">Use it now<");
+      // "Manage modules" secondary link is always present on a terminal-
+      // succeeded install tile.
       expect(html).toContain(">Manage modules<");
     } finally {
       db.close();
     }
   });
-  test("'Already installed' tile gains a 'Use it now' link too", async () => {
+  test("'Already installed' tile renders without a 'Use it now' link when the module has no hosted surface", async () => {
+    // Post-2026-05-27 CURATED trim, USE_IT_NOW_URLS is empty (scribe has
+    // no first-class user-facing landing surface yet; vault gets its
+    // own lead tile, not an install tile). The already-installed tile
+    // therefore renders only the "Manage in admin" secondary link. Pre-
+    // trim the surface module had a USE_IT_NOW_URLS entry that drove
+    // this surface, so the test now pins the absence rather than the
+    // presence.
     const db = openHubDb(hubDbPath(h.dir));
     try {
       const user = await createUser(db, "owner", "pw");
@@ -3409,11 +3760,11 @@ describe("done screen — 'Start using your vault' tile (hub#342)", () => {
               health: "/health",
             },
             {
-              name: "parachute-surface",
-              version: "0.2.0",
-              port: 1946,
-              paths: ["/surface"],
-              health: "/surface/healthz",
+              name: "parachute-scribe",
+              version: "0.4.4",
+              port: 1943,
+              paths: ["/scribe"],
+              health: "/scribe/health",
             },
           ],
         },
@@ -3430,14 +3781,17 @@ describe("done screen — 'Start using your vault' tile (hub#342)", () => {
           db,
           manifestPath: h.manifestPath,
           configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
           issuer: "https://hub.example",
           registry: getDefaultOperationsRegistry(),
         },
       );
       const html = await res.text();
       expect(html).toContain("Already installed");
-      // App's already-installed tile carries the Use it now link.
-      expect(html).toContain('href="/surface/notes/"');
+      // No "Use it now" on the scribe already-installed tile.
+      expect(html).not.toContain(">Use it now<");
+      // Secondary affordance still present.
+      expect(html).toContain("Manage in admin");
     } finally {
       db.close();
     }
@@ -3455,6 +3809,7 @@ describe("done screen — 'Start using your vault' tile (hub#342)", () => {
         db,
         manifestPath: h.manifestPath,
         configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
         issuer: "https://hub.example",
         registry: getDefaultOperationsRegistry(),
       });
@@ -3529,3 +3884,228 @@ describe("detectAutoExposeMode — Fly env detection (patterns#100)", () => {
     ).toBe("public");
   });
 });
+// hub#168 Cut 2/3: vault-step three branches (create/import/skip) + JSON
+// content-type acceptance. The handleSetupVaultPost handler is shared
+// between browser and CLI surfaces — branching is by mode field +
+// content-type. These tests drive the JSON surface directly to keep the
+// behavior locked.
+describe("setup-wizard JSON surface (hub#168 Cuts 2/3)", () => {
+  let h: Harness;
+  beforeEach(() => {
+    h = makeHarness();
+    _resetOperationsRegistryForTests();
+  });
+  afterEach(() => h.cleanup());
+  test("GET /admin/setup returns JSON envelope when Accept: application/json", () => {
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      const deps = {
+        db,
+        manifestPath: h.manifestPath,
+        configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
+        issuer: "http://127.0.0.1:1939",
+        registry: getDefaultOperationsRegistry(),
+      };
+      const res = handleSetupGet(
+        req("/admin/setup", { headers: { accept: "application/json" } }),
+        deps,
+      );
+      expect(res.status).toBe(200);
+      expect(res.headers.get("content-type")).toContain("application/json");
+    } finally {
+      db.close();
+    }
+  });
+  test("vault step skip mode short-circuits + persists setup_vault_skipped", async () => {
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      // Seed: admin exists so the wizard's vault step is reachable.
+      await createUser(db, "owner", "pw");
+      // Get a session cookie via a CSRF token GET first.
+      const supervisor = makeSupervisor();
+      const baseDeps = {
+        db,
+        manifestPath: h.manifestPath,
+        configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
+        issuer: "http://127.0.0.1:1939",
+        registry: getDefaultOperationsRegistry(),
+        supervisor,
+      };
+      const getRes = handleSetupGet(
+        req("/admin/setup", { headers: { accept: "application/json" } }),
+        baseDeps,
+      );
+      const csrf = setCookie(getRes, CSRF_COOKIE_NAME) ?? "";
+      const envelope = (await getRes.json()) as { csrfToken: string };
+      // Build a session for the operator (proxy what an account POST
+      // would do).
+      const { createSession, buildSessionCookie, SESSION_TTL_MS } = await import("../sessions.ts");
+      const user = (await import("../users.ts")).getUserByUsername(db, "owner");
+      if (!user) throw new Error("user missing");
+      const session = createSession(db, { userId: user.id });
+      const cookieHeader = `${SESSION_COOKIE_NAME}=${session.id}; ${CSRF_COOKIE_NAME}=${csrf}`;
+      const postRes = await handleSetupVaultPost(
+        req("/admin/setup/vault", {
+          method: "POST",
+          headers: {
+            accept: "application/json",
+            "content-type": "application/json",
+            cookie: cookieHeader,
+          },
+          body: JSON.stringify({
+            [CSRF_FIELD_NAME]: envelope.csrfToken,
+            mode: "skip",
+          }),
+        }),
+        baseDeps,
+      );
+      expect(postRes.status).toBe(200);
+      expect(postRes.headers.get("content-type")).toContain("application/json");
+      const body = (await postRes.json()) as { step: string };
+      expect(body.step).toBe("expose");
+      // The skip flag is persisted.
+      expect(getSetting(db, "setup_vault_skipped")).toBe("true");
+      // deriveWizardState advances past the vault step.
+      const s = deriveWizardState({
+        db,
+        manifestPath: h.manifestPath,
+        readExposeStateFn: h.readExposeStateFn,
+      });
+      expect(s.hasVault).toBe(true);
+      expect(s.step).toBe("expose");
+    } finally {
+      db.close();
+    }
+  });
+  test("vault step import mode requires remote_url (400 on empty)", async () => {
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      await createUser(db, "owner", "pw");
+      const supervisor = makeSupervisor();
+      const baseDeps = {
+        db,
+        manifestPath: h.manifestPath,
+        configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
+        issuer: "http://127.0.0.1:1939",
+        registry: getDefaultOperationsRegistry(),
+        supervisor,
+      };
+      const { createSession } = await import("../sessions.ts");
+      const user = (await import("../users.ts")).getUserByUsername(db, "owner");
+      if (!user) throw new Error("user missing");
+      const session = createSession(db, { userId: user.id });
+      // Need CSRF cookie value matching the body field. Pull a token
+      // through a GET first.
+      const getRes = handleSetupGet(
+        req("/admin/setup", { headers: { accept: "application/json" } }),
+        baseDeps,
+      );
+      const csrf = setCookie(getRes, CSRF_COOKIE_NAME) ?? "";
+      const envelope = (await getRes.json()) as { csrfToken: string };
+      const cookieHeader = `${SESSION_COOKIE_NAME}=${session.id}; ${CSRF_COOKIE_NAME}=${csrf}`;
+      const postRes = await handleSetupVaultPost(
+        req("/admin/setup/vault", {
+          method: "POST",
+          headers: {
+            accept: "application/json",
+            "content-type": "application/json",
+            cookie: cookieHeader,
+          },
+          body: JSON.stringify({
+            [CSRF_FIELD_NAME]: envelope.csrfToken,
+            mode: "import",
+            vault_name: "imported",
+            remote_url: "",
+          }),
+        }),
+        baseDeps,
+      );
+      expect(postRes.status).toBe(400);
+      const body = (await postRes.json()) as { error: string; message: string };
+      expect(body.error).toContain("Remote URL required");
+    } finally {
+      db.close();
+    }
+  });
+  // hub#168 fold (PR #447 reviewer): the import POST to vault MUST carry
+  // a Bearer — vault's `authenticateVaultRequest` rejects 401 before
+  // scope check on missing auth. Asserts the header is present, names
+  // the vault, and the body shape is intact.
+  test("postVaultImportImpl sends Authorization: Bearer + correct body to vault", async () => {
+    let capturedUrl: string | undefined;
+    let capturedHeaders: Headers | undefined;
+    let capturedBody: unknown;
+    const stubFetch = (async (input: string | URL | Request, init?: RequestInit) => {
+      capturedUrl = typeof input === "string" ? input : input.toString();
+      capturedHeaders = new Headers(init?.headers ?? {});
+      capturedBody = JSON.parse((init?.body as string) ?? "{}");
+      return new Response(
+        JSON.stringify({
+          notes_imported: 7,
+          tags_imported: 2,
+          attachments_imported: 0,
+          warnings: [],
+        }),
+        { status: 200, headers: { "content-type": "application/json" } },
+      );
+    }) as typeof fetch;
+    const result = await postVaultImportImpl({
+      vaultName: "imported",
+      vaultPort: 1940,
+      bearerToken: "stub-jwt-abc",
+      remoteUrl: "https://github.com/owner/repo.git",
+      mode: "merge",
+      pat: "ghp_stub",
+      fetcher: stubFetch,
+    });
+    expect(result.notes_imported).toBe(7);
+    expect(capturedUrl).toBe("http://127.0.0.1:1940/vault/imported/.parachute/mirror/import");
+    expect(capturedHeaders?.get("authorization")).toBe("Bearer stub-jwt-abc");
+    expect(capturedHeaders?.get("content-type")).toBe("application/json");
+    expect(capturedBody).toEqual({
+      remote_url: "https://github.com/owner/repo.git",
+      mode: "merge",
+      credentials: { kind: "pat", token: "ghp_stub" },
+    });
+  });
+  // No-PAT branch — public repo import. Sends `credentials: null`,
+  // which vault interprets as "use stored credentials" (or none).
+  // Reviewer-flagged coverage gap on the rc.8 fold.
+  test("postVaultImportImpl sends credentials: null when no PAT is provided", async () => {
+    let capturedBody: unknown;
+    const stubFetch = (async (_: string | URL | Request, init?: RequestInit) => {
+      capturedBody = JSON.parse((init?.body as string) ?? "{}");
+      return new Response(JSON.stringify({ notes_imported: 1 }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      });
+    }) as typeof fetch;
+    await postVaultImportImpl({
+      vaultName: "public-import",
+      vaultPort: 1940,
+      bearerToken: "stub",
+      remoteUrl: "https://github.com/owner/public.git",
+      mode: "replace",
+      fetcher: stubFetch,
+    });
+    expect(capturedBody).toEqual({
+      remote_url: "https://github.com/owner/public.git",
+      mode: "replace",
+      credentials: null,
+    });
+  });
+});