@openparachute/hub 0.5.10-rc.6 → 0.5.10

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

@@ -2,7 +2,7 @@ import { describe, expect, test } from "bun:test";
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { hubDbPath, openHubDb } from "../hub-db.ts";
+import { hubDbPath, migrate, openHubDb } from "../hub-db.ts";
 
 interface Harness {
   configDir: string;
@@ -150,4 +150,129 @@ describe("openHubDb + migrate", () => {
       h.cleanup();
     }
   });
+
+  test("v8 adds password_changed + assigned_vault columns on a fresh DB", () => {
+    const h = makeHarness();
+    try {
+      const db = openHubDb(h.dbPath);
+      try {
+        const versions = (
+          db.query<{ version: number }, []>("SELECT version FROM schema_version").all() ?? []
+        ).map((r) => r.version);
+        expect(versions).toContain(8);
+        // PRAGMA table_info returns the column shape; we want both new
+        // columns present with the right defaults / nullability.
+        interface ColInfo {
+          name: string;
+          type: string;
+          notnull: number;
+          dflt_value: string | null;
+        }
+        const cols = db
+          .query<ColInfo, []>(
+            "SELECT name, type, \"notnull\", dflt_value FROM pragma_table_info('users')",
+          )
+          .all();
+        const byName = new Map(cols.map((c) => [c.name, c]));
+        const pc = byName.get("password_changed");
+        expect(pc).toBeDefined();
+        expect(pc?.type).toBe("INTEGER");
+        expect(pc?.notnull).toBe(1);
+        // Default literal — SQLite returns it as a string "0".
+        expect(pc?.dflt_value).toBe("0");
+        const av = byName.get("assigned_vault");
+        expect(av).toBeDefined();
+        expect(av?.type).toBe("TEXT");
+        expect(av?.notnull).toBe(0);
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("v8 backfills password_changed=1 for users that pre-date the migration", () => {
+    const h = makeHarness();
+    try {
+      // Stand up a DB at the v7 state by partially-applying migrations:
+      // open Database directly, call migrate after stripping the v8 entry
+      // would be invasive. Instead, drive the same migration shape by hand
+      // for v1-v7 then insert a row, then call migrate() to apply v8.
+      // Cleanest path: openHubDb runs everything, but we want a v7 snapshot.
+      // Approach: open with openHubDb (runs all migrations), drop the v8
+      // changes, mark v8 unapplied, insert a user with password_changed=0
+      // (simulating a row from before the backfill), then re-run migrate.
+      // SQLite doesn't have DROP COLUMN pre-3.35 universally, so we do the
+      // recreate-and-rename: drop v8's columns by recreating users without
+      // them, then delete the v8 schema_version row, then call migrate().
+      const db = openHubDb(h.dbPath);
+      try {
+        // Build a v7-shape users table and copy the v8-shape rows.
+        db.exec(`
+          CREATE TABLE users_v7 (
+            id TEXT PRIMARY KEY,
+            username TEXT UNIQUE NOT NULL,
+            password_hash TEXT NOT NULL,
+            created_at TEXT NOT NULL,
+            updated_at TEXT NOT NULL
+          );
+          INSERT INTO users_v7 (id, username, password_hash, created_at, updated_at)
+          SELECT id, username, password_hash, created_at, updated_at FROM users;
+          DROP TABLE users;
+          ALTER TABLE users_v7 RENAME TO users;
+        `);
+        db.exec("DELETE FROM schema_version WHERE version = 8");
+        // Insert a row that pre-dates v8 (no password_changed column yet).
+        db.prepare(
+          `INSERT INTO users (id, username, password_hash, created_at, updated_at)
+           VALUES (?, ?, ?, ?, ?)`,
+        ).run("legacy-user", "owner", "h", "2026-01-01", "2026-01-01");
+        // Now re-run migrations — v8 should ALTER the table and backfill.
+        migrate(db);
+        const row = db
+          .query<{ password_changed: number; assigned_vault: string | null }, [string]>(
+            "SELECT password_changed, assigned_vault FROM users WHERE id = ?",
+          )
+          .get("legacy-user");
+        expect(row).not.toBeNull();
+        expect(row?.password_changed).toBe(1);
+        expect(row?.assigned_vault).toBeNull();
+        const versions = (
+          db.query<{ version: number }, []>("SELECT version FROM schema_version").all() ?? []
+        ).map((r) => r.version);
+        expect(versions).toContain(8);
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("v8 — fresh inserts default password_changed=0 and assigned_vault NULL", () => {
+    const h = makeHarness();
+    try {
+      const db = openHubDb(h.dbPath);
+      try {
+        // Insert via the bare-columns SQL (mirrors what a pre-v8 caller
+        // would emit) to confirm the column DEFAULTs work.
+        db.prepare(
+          `INSERT INTO users (id, username, password_hash, created_at, updated_at)
+           VALUES (?, ?, ?, ?, ?)`,
+        ).run("u-default", "owner", "h", "2026-01-01", "2026-01-01");
+        const row = db
+          .query<{ password_changed: number; assigned_vault: string | null }, [string]>(
+            "SELECT password_changed, assigned_vault FROM users WHERE id = ?",
+          )
+          .get("u-default");
+        expect(row?.password_changed).toBe(0);
+        expect(row?.assigned_vault).toBeNull();
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
 });

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

@@ -165,6 +165,29 @@ describe("hubFetch routing", () => {
     }
   });
 
+  test("/.well-known/parachute.json sets cache-control: no-store (hub#268 Item 1)", async () => {
+    // The discovery page (/) fetches this doc and renders Service tiles
+    // from it. Without no-store, the browser HTTP cache returns the
+    // stale services list the next time the operator clicks back to /
+    // after installing a module via /admin/modules. The doc is built
+    // per-request anyway, so giving up cacheability has no real cost.
+    const h = makeHarness();
+    try {
+      writeManifest({ services: [] }, h.manifestPath);
+      const getRes = await hubFetch(h.dir, { manifestPath: h.manifestPath })(
+        req("/.well-known/parachute.json"),
+      );
+      expect(getRes.headers.get("cache-control")).toBe("no-store");
+      // Preflight gets the same header (same corsHeaders object).
+      const optRes = await hubFetch(h.dir, { manifestPath: h.manifestPath })(
+        req("/.well-known/parachute.json", { method: "OPTIONS" }),
+      );
+      expect(optRes.headers.get("cache-control")).toBe("no-store");
+    } finally {
+      h.cleanup();
+    }
+  });
+
   test("OPTIONS preflight on /.well-known/parachute.json returns 204 + CORS", async () => {
     const h = makeHarness();
     try {
@@ -1010,16 +1033,17 @@ describe("hubFetch routing", () => {
     }
   });
 
-  test("/admin/setup 301s to /login once admin + vault both exist (hub#259)", async () => {
+  test("/admin/setup 301s to /login once admin + vault + expose mode all exist (hub#259, hub#268)", async () => {
     const h = makeHarness();
     try {
       const db = openHubDb(hubDbPath(h.dir));
       try {
         await createUser(db, "owner", "pw");
-        // Seed the vault entry so the wizard's state derives as "done"
-        // and the GET 301s. Without this the wizard would still resume
-        // at the vault step.
+        // Seed the vault entry + expose-mode answer so the wizard's
+        // state derives as "done" and the GET 301s. Without expose
+        // (hub#268 Item 2) the wizard would resume on the expose step.
         const { writeManifest } = await import("../services-manifest.ts");
+        const { setSetting } = await import("../hub-settings.ts");
         const { join } = await import("node:path");
         writeManifest(
           {
@@ -1035,6 +1059,7 @@ describe("hubFetch routing", () => {
           },
           join(h.dir, "services.json"),
         );
+        setSetting(db, "setup_expose_mode", "localhost");
         const res = await hubFetch(h.dir, {
           getDb: () => db,
           manifestPath: join(h.dir, "services.json"),

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

@@ -0,0 +1,377 @@
+/**
+ * Tests for hub-local key/value settings (hub#268).
+ *
+ * Covers the bare KV API (get/set/delete) and the two domain helpers
+ * the wizard + oauth handlers consume: setup_expose_mode validation and
+ * the first-client auto-approve window (open + check + consume + clear).
+ */
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { hubDbPath, openHubDb } from "../hub-db.ts";
+import {
+  DEFAULT_MODULE_INSTALL_CHANNEL,
+  FIRST_CLIENT_AUTO_APPROVE_WINDOW_MS,
+  MODULE_INSTALL_CHANNELS,
+  PARACHUTE_MODULE_CHANNEL_ENV,
+  SETUP_EXPOSE_MODES,
+  consumeFirstClientAutoApproveWindow,
+  deleteSetting,
+  getModuleInstallChannel,
+  getSetting,
+  isFirstClientAutoApproveWindowOpen,
+  isModuleInstallChannel,
+  isSetupExposeMode,
+  openFirstClientAutoApproveWindow,
+  setModuleInstallChannel,
+  setSetting,
+} from "../hub-settings.ts";
+
+describe("hub-settings — bare KV", () => {
+  let dir: string;
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "hub-settings-"));
+  });
+  afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+  test("getSetting returns undefined for an absent key", () => {
+    const db = openHubDb(hubDbPath(dir));
+    try {
+      expect(getSetting(db, "setup_expose_mode")).toBeUndefined();
+    } finally {
+      db.close();
+    }
+  });
+
+  test("setSetting writes a value getSetting reads back", () => {
+    const db = openHubDb(hubDbPath(dir));
+    try {
+      setSetting(db, "setup_expose_mode", "tailnet");
+      expect(getSetting(db, "setup_expose_mode")).toBe("tailnet");
+    } finally {
+      db.close();
+    }
+  });
+
+  test("setSetting overwrites an existing value (UPSERT)", () => {
+    const db = openHubDb(hubDbPath(dir));
+    try {
+      setSetting(db, "setup_expose_mode", "tailnet");
+      setSetting(db, "setup_expose_mode", "public");
+      expect(getSetting(db, "setup_expose_mode")).toBe("public");
+    } finally {
+      db.close();
+    }
+  });
+
+  test("deleteSetting removes a row + idempotently no-ops on a missing key", () => {
+    const db = openHubDb(hubDbPath(dir));
+    try {
+      setSetting(db, "setup_expose_mode", "localhost");
+      deleteSetting(db, "setup_expose_mode");
+      expect(getSetting(db, "setup_expose_mode")).toBeUndefined();
+      // Second delete is a no-op.
+      deleteSetting(db, "setup_expose_mode");
+      expect(getSetting(db, "setup_expose_mode")).toBeUndefined();
+    } finally {
+      db.close();
+    }
+  });
+
+  test("setSetting updates the updated_at column on every write", () => {
+    const db = openHubDb(hubDbPath(dir));
+    try {
+      const t1 = new Date("2026-05-19T00:00:00.000Z");
+      const t2 = new Date("2026-05-19T00:01:00.000Z");
+      setSetting(db, "setup_expose_mode", "localhost", () => t1);
+      setSetting(db, "setup_expose_mode", "localhost", () => t2);
+      // Re-write with the same value still bumps updated_at — useful
+      // for operational polling that wants to distinguish stale vs
+      // fresh state.
+      const row = db
+        .query<{ updated_at: string }, []>(
+          "SELECT updated_at FROM hub_settings WHERE key = 'setup_expose_mode'",
+        )
+        .get();
+      expect(row?.updated_at).toBe(t2.toISOString());
+    } finally {
+      db.close();
+    }
+  });
+});
+
+describe("hub-settings — isSetupExposeMode", () => {
+  test("accepts the three canonical values", () => {
+    for (const m of SETUP_EXPOSE_MODES) {
+      expect(isSetupExposeMode(m)).toBe(true);
+    }
+  });
+
+  test("rejects anything else (typos, empty, non-string)", () => {
+    expect(isSetupExposeMode("local")).toBe(false);
+    expect(isSetupExposeMode("LOCALHOST")).toBe(false);
+    expect(isSetupExposeMode("")).toBe(false);
+    expect(isSetupExposeMode(null)).toBe(false);
+    expect(isSetupExposeMode(undefined)).toBe(false);
+    expect(isSetupExposeMode(42)).toBe(false);
+  });
+});
+
+describe("hub-settings — first-client auto-approve window", () => {
+  let dir: string;
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "hub-settings-"));
+  });
+  afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+  test("window is closed by default (no row)", () => {
+    const db = openHubDb(hubDbPath(dir));
+    try {
+      expect(isFirstClientAutoApproveWindowOpen(db)).toBe(false);
+    } finally {
+      db.close();
+    }
+  });
+
+  test("openFirstClientAutoApproveWindow opens a window 60 minutes long", () => {
+    const db = openHubDb(hubDbPath(dir));
+    try {
+      const now = new Date("2026-05-19T00:00:00.000Z");
+      openFirstClientAutoApproveWindow(db, () => now);
+      const stored = getSetting(db, "pending_first_client_auto_approve_until");
+      expect(stored).toBeDefined();
+      const parsed = new Date(stored ?? "");
+      expect(parsed.getTime() - now.getTime()).toBe(FIRST_CLIENT_AUTO_APPROVE_WINDOW_MS);
+    } finally {
+      db.close();
+    }
+  });
+
+  test("isFirstClientAutoApproveWindowOpen → true within window, false after expiry", () => {
+    const db = openHubDb(hubDbPath(dir));
+    try {
+      const t0 = new Date("2026-05-19T00:00:00.000Z");
+      openFirstClientAutoApproveWindow(db, () => t0);
+      // 30 minutes in → still open.
+      expect(
+        isFirstClientAutoApproveWindowOpen(db, () => new Date(t0.getTime() + 30 * 60 * 1000)),
+      ).toBe(true);
+      // 60 minutes + 1 ms in → closed.
+      expect(
+        isFirstClientAutoApproveWindowOpen(
+          db,
+          () => new Date(t0.getTime() + FIRST_CLIENT_AUTO_APPROVE_WINDOW_MS + 1),
+        ),
+      ).toBe(false);
+    } finally {
+      db.close();
+    }
+  });
+
+  test("consumeFirstClientAutoApproveWindow consumes the window once, then returns false", () => {
+    const db = openHubDb(hubDbPath(dir));
+    try {
+      const now = new Date("2026-05-19T00:00:00.000Z");
+      openFirstClientAutoApproveWindow(db, () => now);
+      // First call consumes.
+      expect(consumeFirstClientAutoApproveWindow(db, () => now)).toBe(true);
+      // Second call sees no window.
+      expect(consumeFirstClientAutoApproveWindow(db, () => now)).toBe(false);
+      // The row is cleared.
+      expect(getSetting(db, "pending_first_client_auto_approve_until")).toBeUndefined();
+    } finally {
+      db.close();
+    }
+  });
+
+  test("consume returns false when the window has expired (and clears nothing)", () => {
+    const db = openHubDb(hubDbPath(dir));
+    try {
+      const t0 = new Date("2026-05-19T00:00:00.000Z");
+      openFirstClientAutoApproveWindow(db, () => t0);
+      const past = new Date(t0.getTime() + FIRST_CLIENT_AUTO_APPROVE_WINDOW_MS + 1);
+      expect(consumeFirstClientAutoApproveWindow(db, () => past)).toBe(false);
+      // Row is still there (no implicit cleanup on expiry — the setting
+      // just stops being "open"). A future open() resets it.
+      expect(getSetting(db, "pending_first_client_auto_approve_until")).toBeDefined();
+    } finally {
+      db.close();
+    }
+  });
+
+  test("malformed timestamp string is treated as closed (not parseable → not open)", () => {
+    const db = openHubDb(hubDbPath(dir));
+    try {
+      setSetting(db, "pending_first_client_auto_approve_until", "not-a-date");
+      expect(isFirstClientAutoApproveWindowOpen(db)).toBe(false);
+      expect(consumeFirstClientAutoApproveWindow(db)).toBe(false);
+    } finally {
+      db.close();
+    }
+  });
+
+  test("reopening the window after consume restarts the 60-minute clock", () => {
+    const db = openHubDb(hubDbPath(dir));
+    try {
+      const t0 = new Date("2026-05-19T00:00:00.000Z");
+      openFirstClientAutoApproveWindow(db, () => t0);
+      consumeFirstClientAutoApproveWindow(db, () => t0);
+      // Re-open at t0 + 90min.
+      const t1 = new Date(t0.getTime() + 90 * 60 * 1000);
+      openFirstClientAutoApproveWindow(db, () => t1);
+      // The new window's expiry is t1 + 60min, not t0 + 60min.
+      const stored = getSetting(db, "pending_first_client_auto_approve_until");
+      const parsed = new Date(stored ?? "");
+      expect(parsed.getTime()).toBe(t1.getTime() + FIRST_CLIENT_AUTO_APPROVE_WINDOW_MS);
+    } finally {
+      db.close();
+    }
+  });
+});
+
+describe("hub-settings — isModuleInstallChannel", () => {
+  test("accepts the two canonical values", () => {
+    for (const c of MODULE_INSTALL_CHANNELS) {
+      expect(isModuleInstallChannel(c)).toBe(true);
+    }
+    expect(isModuleInstallChannel("latest")).toBe(true);
+    expect(isModuleInstallChannel("rc")).toBe(true);
+  });
+
+  test("rejects anything else (typos, empty, non-string, case-mismatch)", () => {
+    expect(isModuleInstallChannel("LATEST")).toBe(false);
+    expect(isModuleInstallChannel("Latest")).toBe(false);
+    expect(isModuleInstallChannel("stable")).toBe(false);
+    expect(isModuleInstallChannel("beta")).toBe(false);
+    expect(isModuleInstallChannel("")).toBe(false);
+    expect(isModuleInstallChannel(null)).toBe(false);
+    expect(isModuleInstallChannel(undefined)).toBe(false);
+    expect(isModuleInstallChannel(42)).toBe(false);
+  });
+});
+
+describe("hub-settings — module install channel bootstrap", () => {
+  let dir: string;
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "hub-settings-channel-"));
+  });
+  afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+  test("first read with no env + no row seeds + returns the default (latest)", () => {
+    const db = openHubDb(hubDbPath(dir));
+    try {
+      // Empty env — no PARACHUTE_MODULE_CHANNEL.
+      const channel = getModuleInstallChannel(db, { env: {} });
+      expect(channel).toBe(DEFAULT_MODULE_INSTALL_CHANNEL);
+      expect(channel).toBe("latest");
+      // The row is now seeded.
+      expect(getSetting(db, "module_install_channel")).toBe("latest");
+    } finally {
+      db.close();
+    }
+  });
+
+  test("first read with PARACHUTE_MODULE_CHANNEL=rc seeds with rc", () => {
+    const db = openHubDb(hubDbPath(dir));
+    try {
+      const channel = getModuleInstallChannel(db, {
+        env: { [PARACHUTE_MODULE_CHANNEL_ENV]: "rc" },
+      });
+      expect(channel).toBe("rc");
+      expect(getSetting(db, "module_install_channel")).toBe("rc");
+    } finally {
+      db.close();
+    }
+  });
+
+  test("first read with PARACHUTE_MODULE_CHANNEL=latest seeds with latest", () => {
+    const db = openHubDb(hubDbPath(dir));
+    try {
+      const channel = getModuleInstallChannel(db, {
+        env: { [PARACHUTE_MODULE_CHANNEL_ENV]: "latest" },
+      });
+      expect(channel).toBe("latest");
+      expect(getSetting(db, "module_install_channel")).toBe("latest");
+    } finally {
+      db.close();
+    }
+  });
+
+  test("invalid PARACHUTE_MODULE_CHANNEL warns + falls back to latest", () => {
+    const db = openHubDb(hubDbPath(dir));
+    try {
+      const warns: string[] = [];
+      const channel = getModuleInstallChannel(db, {
+        env: { [PARACHUTE_MODULE_CHANNEL_ENV]: "stable" },
+        warn: (msg) => warns.push(msg),
+      });
+      expect(channel).toBe("latest");
+      expect(getSetting(db, "module_install_channel")).toBe("latest");
+      expect(warns.length).toBe(1);
+      expect(warns[0]).toMatch(/PARACHUTE_MODULE_CHANNEL="stable"/);
+      expect(warns[0]).toMatch(/not a valid channel/);
+    } finally {
+      db.close();
+    }
+  });
+
+  test("empty PARACHUTE_MODULE_CHANNEL is treated as unset (no warn)", () => {
+    const db = openHubDb(hubDbPath(dir));
+    try {
+      const warns: string[] = [];
+      const channel = getModuleInstallChannel(db, {
+        env: { [PARACHUTE_MODULE_CHANNEL_ENV]: "" },
+        warn: (msg) => warns.push(msg),
+      });
+      expect(channel).toBe("latest");
+      expect(warns).toEqual([]);
+    } finally {
+      db.close();
+    }
+  });
+
+  test("once seeded, env var is ignored on subsequent reads", () => {
+    const db = openHubDb(hubDbPath(dir));
+    try {
+      // First read seeds with rc.
+      getModuleInstallChannel(db, { env: { [PARACHUTE_MODULE_CHANNEL_ENV]: "rc" } });
+      // Second read with a different env value still returns the seeded value.
+      const channel = getModuleInstallChannel(db, {
+        env: { [PARACHUTE_MODULE_CHANNEL_ENV]: "latest" },
+      });
+      expect(channel).toBe("rc");
+      // And with no env at all.
+      expect(getModuleInstallChannel(db, { env: {} })).toBe("rc");
+    } finally {
+      db.close();
+    }
+  });
+
+  test("setModuleInstallChannel persists the new value, subsequent reads return it", () => {
+    const db = openHubDb(hubDbPath(dir));
+    try {
+      // Seed with rc via env.
+      getModuleInstallChannel(db, { env: { [PARACHUTE_MODULE_CHANNEL_ENV]: "rc" } });
+      // Admin toggles to latest.
+      setModuleInstallChannel(db, "latest");
+      expect(getModuleInstallChannel(db, { env: {} })).toBe("latest");
+      // And back to rc — no env needed.
+      setModuleInstallChannel(db, "rc");
+      expect(getModuleInstallChannel(db, { env: {} })).toBe("rc");
+    } finally {
+      db.close();
+    }
+  });
+
+  test("corrupted row falls back to latest silently (no throw)", () => {
+    const db = openHubDb(hubDbPath(dir));
+    try {
+      // Simulate a manual sqlite edit / schema drift / external write.
+      setSetting(db, "module_install_channel", "bogus");
+      expect(getModuleInstallChannel(db, { env: {} })).toBe("latest");
+    } finally {
+      db.close();
+    }
+  });
+});

package/src/__tests__/hub.test.ts

@@ -103,6 +103,23 @@ describe("renderHub", () => {
     expect(html).toContain("Could not load services");
   });
 
+  test("discovery page fetches with cache: 'no-store' (hub#268 Item 1)", () => {
+    // Without `cache: 'no-store'` the browser's HTTP cache can return
+    // a stale services list when the operator clicks back to / after
+    // installing a module via /admin/modules. Server-side also sets
+    // cache-control: no-store on the well-known doc.
+    expect(html).toContain("cache: 'no-store'");
+  });
+
+  test("discovery page re-fetches on bfcache restore via pageshow (hub#268 Item 1)", () => {
+    // When the operator clicks back from /admin/modules to / the
+    // browser may restore the prior DOM without re-running the IIFE.
+    // The pageshow handler re-runs loadServices() when the page was
+    // restored from cache (`e.persisted === true`).
+    expect(html).toContain("addEventListener('pageshow'");
+    expect(html).toContain("e.persisted");
+  });
+
   test("does not retain the old aggregate-by-module-type code", () => {
     // The Vault collapse + per-module aggregation pattern is gone — Use
     // entries are direct service-path → label lookups; Admin is hardcoded.

package/src/__tests__/jwt-sign.test.ts

@@ -121,6 +121,65 @@ describe("signAccessToken", () => {
       cleanup();
     }
   });
+
+  // Multi-user Phase 1, PR 4 (design 2026-05-20-multi-user-phase-1.md):
+  // the `vault_scope` claim is emitted unconditionally so a downstream
+  // consumer (PR 5's scope-guard) doesn't have to distinguish "absent" from
+  // "empty." Callers pass `[]` for admin / unpinned, `[<assigned_vault>]`
+  // for non-admin pinned users.
+  test("vault_scope=[] is emitted as the empty-array claim", async () => {
+    const { db, cleanup } = makeDb();
+    try {
+      const { token } = await signAccessToken(db, {
+        sub: "admin-aaron",
+        scopes: ["vault:default:read"],
+        audience: "vault.default",
+        clientId: "c",
+        issuer: "https://hub.example",
+        vaultScope: [],
+      });
+      const payload = decodeJwt(token);
+      expect(payload.vault_scope).toEqual([]);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("vault_scope=['bob'] is emitted as the single-element claim", async () => {
+    const { db, cleanup } = makeDb();
+    try {
+      const { token } = await signAccessToken(db, {
+        sub: "bob",
+        scopes: ["vault:bob:read"],
+        audience: "vault.bob",
+        clientId: "c",
+        issuer: "https://hub.example",
+        vaultScope: ["bob"],
+      });
+      const payload = decodeJwt(token);
+      expect(payload.vault_scope).toEqual(["bob"]);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("vault_scope defaults to [] when caller omits the field (back-compat sentinel)", async () => {
+    const { db, cleanup } = makeDb();
+    try {
+      const { token } = await signAccessToken(db, {
+        sub: "operator",
+        scopes: ["parachute:host:admin"],
+        audience: "hub",
+        clientId: "c",
+        issuer: "https://hub.example",
+      });
+      const payload = decodeJwt(token);
+      // Claim is present (not undefined), set to the empty-array sentinel.
+      expect(payload.vault_scope).toEqual([]);
+    } finally {
+      cleanup();
+    }
+  });
 });
 
 describe("signRefreshToken", () => {