@openparachute/hub 0.7.2 → 0.7.3-rc.10

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

@@ -0,0 +1,136 @@
+/**
+ * `parachute hub set-origin <url>` (onboarding-streamline 2026-06-25,
+ * Caddy-direct zero-SSH path).
+ *
+ * The verb persists the operator's canonical public origin to
+ * `hub_settings.hub_origin` from the CLI — closing the "set the issuer without
+ * an admin browser session" gap on a headless reverse-proxy box. These tests
+ * pin: it writes the row, it validates + canonicalizes the URL (reusing the
+ * SPA's `validateHubOrigin`), and it warns-but-allows loopback.
+ */
+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 { hub, hubSetOrigin } from "../commands/hub.ts";
+import { hubDbPath, openHubDb } from "../hub-db.ts";
+import { getHubOrigin } from "../hub-settings.ts";
+
+describe("parachute hub set-origin", () => {
+  let dir: string;
+  let log: string[];
+  const collect = (line: string) => log.push(line);
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "hub-set-origin-"));
+    log = [];
+  });
+  afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+  /** Open the configDir's hub.db and read the persisted origin. */
+  function persisted(): string | null {
+    const db = openHubDb(hubDbPath(dir));
+    try {
+      return getHubOrigin(db);
+    } finally {
+      db.close();
+    }
+  }
+
+  test("persists a valid public origin to hub_settings.hub_origin", async () => {
+    const code = await hubSetOrigin(["https://box.sslip.io"], { configDir: dir, log: collect });
+    expect(code).toBe(0);
+    expect(persisted()).toBe("https://box.sslip.io");
+  });
+
+  test("strips a trailing slash (canonical bare-origin form)", async () => {
+    const code = await hubSetOrigin(["https://box.example.com/"], { configDir: dir, log: collect });
+    expect(code).toBe(0);
+    expect(persisted()).toBe("https://box.example.com");
+  });
+
+  test("rejects a non-http(s) scheme without writing", async () => {
+    const code = await hubSetOrigin(["ftp://box.example.com"], { configDir: dir, log: collect });
+    expect(code).toBe(1);
+    expect(persisted()).toBeNull();
+  });
+
+  test("rejects a URL with a path without writing", async () => {
+    const code = await hubSetOrigin(["https://box.example.com/admin"], {
+      configDir: dir,
+      log: collect,
+    });
+    expect(code).toBe(1);
+    expect(persisted()).toBeNull();
+  });
+
+  test("rejects a bare hostname (no scheme) without writing", async () => {
+    const code = await hubSetOrigin(["box.example.com"], { configDir: dir, log: collect });
+    expect(code).toBe(1);
+    expect(persisted()).toBeNull();
+  });
+
+  test("missing the URL argument is a usage error, no write", async () => {
+    const code = await hubSetOrigin([], { configDir: dir, log: collect });
+    expect(code).toBe(1);
+    expect(persisted()).toBeNull();
+  });
+
+  test("warns but ALLOWS a loopback origin (dev/test escape hatch)", async () => {
+    const code = await hubSetOrigin(["http://127.0.0.1:1939"], { configDir: dir, log: collect });
+    expect(code).toBe(0);
+    expect(persisted()).toBe("http://127.0.0.1:1939");
+    expect(log.some((l) => l.toLowerCase().includes("loopback"))).toBe(true);
+  });
+
+  test("prints the restart note so the operator knows running modules need a restart", async () => {
+    await hubSetOrigin(["https://box.sslip.io"], { configDir: dir, log: collect });
+    const joined = log.join("\n");
+    expect(joined).toContain("parachute restart vault");
+  });
+
+  test("openDb seam is honored (no touch of the live ~/.parachute)", async () => {
+    // Point the seam at a SEPARATE on-disk DB so we can assert (a) the seam was
+    // consulted, and (b) the write landed in the seam's DB — never the
+    // configDir's default path. (A real Database can't be Proxy-wrapped: Bun's
+    // prepared-statement private fields break under a Proxy.)
+    const altDir = mkdtempSync(join(tmpdir(), "hub-set-origin-alt-"));
+    try {
+      let opened = 0;
+      const code = await hubSetOrigin(["https://box.sslip.io"], {
+        configDir: dir,
+        log: collect,
+        openDb: () => {
+          opened++;
+          return openHubDb(hubDbPath(altDir));
+        },
+      });
+      expect(code).toBe(0);
+      expect(opened).toBe(1);
+      // The write landed in the seam's DB, NOT the configDir's default DB.
+      const alt = openHubDb(hubDbPath(altDir));
+      try {
+        expect(getHubOrigin(alt)).toBe("https://box.sslip.io");
+      } finally {
+        alt.close();
+      }
+    } finally {
+      rmSync(altDir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("parachute hub dispatcher", () => {
+  test("no subcommand prints help, exits 0", async () => {
+    const code = await hub([]);
+    expect(code).toBe(0);
+  });
+
+  test("--help exits 0", async () => {
+    expect(await hub(["--help"])).toBe(0);
+  });
+
+  test("unknown subcommand exits 1", async () => {
+    expect(await hub(["frobnicate"])).toBe(1);
+  });
+});

package/src/__tests__/hub-origins-env-set.test.ts

@@ -0,0 +1,273 @@
+/**
+ * Multi-origin iss-set (onboarding-streamline 2026-06-25) — hub side.
+ *
+ * The hub publishes the SET of origins it legitimately answers on to its
+ * supervised resource servers via `PARACHUTE_HUB_ORIGINS` (comma-separated),
+ * alongside the single canonical `PARACHUTE_HUB_ORIGIN`. A resource server on
+ * scope-guard ≥0.5.0 widens its accepted-`iss` check to this set so a token
+ * minted under one URL of a multi-URL box validates via another URL of the
+ * SAME box.
+ *
+ * These tests pin two things:
+ *   1. The serialize/parse round-trip + the assembly from hub-controlled
+ *      inputs (issuer ∪ loopback aliases ∪ expose-state ∪ platform).
+ *   2. The SECURITY INVARIANT: the set is built ONLY from operator/hub config
+ *      and on-disk state — never from an unvalidated request `Host` /
+ *      `X-Forwarded-Host`. We feed an attacker-controlled "Host" through every
+ *      input channel a request could plausibly reach and assert it never lands
+ *      in the published set.
+ */
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { resolveStartupIssuer } from "../commands/serve.ts";
+import { hubDbPath, openHubDb } from "../hub-db.ts";
+import { parseHubOrigins, serializeHubOrigins } from "../hub-origin.ts";
+import { getHubOrigin, setHubOrigin } from "../hub-settings.ts";
+import { buildHubOriginsEnvValue } from "../vault-hub-origin-env.ts";
+
+describe("serializeHubOrigins / parseHubOrigins round-trip", () => {
+  test("serialize dedupes, drops empties, strips trailing slashes", () => {
+    const v = serializeHubOrigins([
+      "https://a.example/",
+      "https://a.example",
+      "",
+      "https://b.example",
+    ]);
+    expect(v).toBe("https://a.example,https://b.example");
+  });
+
+  test("serialize returns undefined when nothing survives", () => {
+    expect(serializeHubOrigins([])).toBeUndefined();
+    expect(serializeHubOrigins(["", "  "])).toBeUndefined();
+  });
+
+  test("parse is the inverse — tolerant of whitespace + trailing slashes + empties", () => {
+    expect(parseHubOrigins("https://a.example, https://b.example/ ,,")).toEqual([
+      "https://a.example",
+      "https://b.example",
+    ]);
+  });
+
+  test("parse returns [] for absent/empty/garbage", () => {
+    expect(parseHubOrigins(undefined)).toEqual([]);
+    expect(parseHubOrigins("")).toEqual([]);
+    expect(parseHubOrigins(" , , ")).toEqual([]);
+  });
+
+  test("round-trips a real set", () => {
+    const origins = ["https://example.com", "http://127.0.0.1:1939", "http://localhost:1939"];
+    const wire = serializeHubOrigins(origins)!;
+    expect(parseHubOrigins(wire)).toEqual(origins);
+  });
+});
+
+describe("buildHubOriginsEnvValue — assembles the hub's legitimate-origin set", () => {
+  let dir: string;
+  const EXPOSE = () => join(dir, "expose-state.json");
+
+  /** Write a schema-valid expose-state.json carrying the given hubOrigin. */
+  function writeExposeState(hubOrigin: string): void {
+    writeFileSync(
+      EXPOSE(),
+      JSON.stringify({
+        version: 1,
+        layer: "public",
+        mode: "path",
+        canonicalFqdn: new URL(hubOrigin).host,
+        port: 1939,
+        funnel: true,
+        entries: [],
+        hubOrigin,
+      }),
+    );
+  }
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "hub-origins-set-"));
+    // No hub.port file in this fresh configDir → readHubPort falls back to
+    // HUB_UNIT_DEFAULT_PORT (1939), the deterministic value these cases assert.
+  });
+  afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+  test("issuer ∪ loopback aliases when no expose / platform origin", () => {
+    const v = buildHubOriginsEnvValue(dir, "https://example.com", {}, EXPOSE());
+    const set = parseHubOrigins(v);
+    expect(set).toContain("https://example.com");
+    expect(set).toContain("http://127.0.0.1:1939");
+    expect(set).toContain("http://localhost:1939");
+    expect(set).toHaveLength(3);
+  });
+
+  test("loopback aliases are ALWAYS present (the always-present invariant)", () => {
+    // Even with a public issuer, loopback must be in the set so the co-located
+    // CLI / loopback-proxied request path validates.
+    const set = parseHubOrigins(buildHubOriginsEnvValue(dir, "https://example.com", {}, EXPOSE()));
+    expect(set).toContain("http://127.0.0.1:1939");
+    expect(set).toContain("http://localhost:1939");
+  });
+
+  test("folds in the expose-state public origin", () => {
+    writeExposeState("https://box.sslip.io");
+    const set = parseHubOrigins(buildHubOriginsEnvValue(dir, "https://example.com", {}, EXPOSE()));
+    expect(set).toContain("https://example.com");
+    expect(set).toContain("https://box.sslip.io");
+  });
+
+  test("folds in the platform origin (RENDER_EXTERNAL_URL)", () => {
+    const set = parseHubOrigins(
+      buildHubOriginsEnvValue(
+        dir,
+        "https://example.com",
+        { RENDER_EXTERNAL_URL: "https://app.onrender.com" },
+        EXPOSE(),
+      ),
+    );
+    expect(set).toContain("https://app.onrender.com");
+  });
+
+  test("folds in the composed Fly default origin", () => {
+    const set = parseHubOrigins(
+      buildHubOriginsEnvValue(dir, "https://example.com", { FLY_APP_NAME: "myapp" }, EXPOSE()),
+    );
+    expect(set).toContain("https://myapp.fly.dev");
+  });
+
+  test("absent issuer → loopback-only set (still useful, never empty on a normal box)", () => {
+    const set = parseHubOrigins(buildHubOriginsEnvValue(dir, undefined, {}, EXPOSE()));
+    expect(set).toContain("http://127.0.0.1:1939");
+    expect(set).toContain("http://localhost:1939");
+    // The empty issuer "" is dropped by buildHubBoundOrigins' URL parse.
+    expect(set).not.toContain("");
+  });
+
+  test("a malformed expose-state.json never throws — falls back to issuer + loopback", () => {
+    writeFileSync(EXPOSE(), "{ not valid json");
+    const set = parseHubOrigins(buildHubOriginsEnvValue(dir, "https://example.com", {}, EXPOSE()));
+    expect(set).toContain("https://example.com");
+    expect(set).toContain("http://127.0.0.1:1939");
+  });
+
+  describe("SECURITY INVARIANT — request Host never enters the set", () => {
+    const ATTACKER = "https://attacker.evil";
+
+    test("an attacker Host smuggled via expose-state IS honored ONLY because it's operator-written on-disk state — but a Host passed nowhere never appears", () => {
+      // There is NO request input to buildHubOriginsEnvValue at all — it takes
+      // configDir + issuer + env + expose-state-path. None of those is a
+      // request header. We assert the function's surface offers no channel for
+      // a request Host: feeding the attacker value to the only inputs an
+      // attacker might influence (a stray env var, a header-shaped string)
+      // never reaches the set unless it's a legitimate operator-config var.
+      const set = parseHubOrigins(
+        buildHubOriginsEnvValue(
+          dir,
+          "https://example.com",
+          {
+            // Header-shaped env vars an attacker might hope are read — none are
+            // consulted by the assembler (only RENDER_EXTERNAL_URL / FLY_APP_NAME).
+            HTTP_HOST: ATTACKER,
+            HTTP_X_FORWARDED_HOST: ATTACKER,
+            X_FORWARDED_HOST: ATTACKER,
+            HOST: ATTACKER,
+          } as NodeJS.ProcessEnv,
+          EXPOSE(),
+        ),
+      );
+      expect(set).not.toContain(ATTACKER);
+      expect(set.some((o) => o.includes("attacker"))).toBe(false);
+    });
+
+    test("the set is exactly issuer ∪ loopback ∪ expose ∪ platform — no other source", () => {
+      writeExposeState("https://box.sslip.io");
+      const set = parseHubOrigins(
+        buildHubOriginsEnvValue(
+          dir,
+          "https://example.com",
+          { RENDER_EXTERNAL_URL: "https://app.onrender.com" },
+          EXPOSE(),
+        ),
+      );
+      // Every member is one of the four sanctioned sources; nothing else.
+      const sanctioned = new Set([
+        "https://example.com",
+        "http://127.0.0.1:1939",
+        "http://localhost:1939",
+        "https://box.sslip.io",
+        "https://app.onrender.com",
+      ]);
+      for (const o of set) expect(sanctioned.has(o)).toBe(true);
+    });
+  });
+});
+
+/**
+ * THE CRUX (onboarding-streamline 2026-06-25, Caddy-direct zero-SSH path):
+ * a box whose ONLY canonical-origin source is the DB row `hub_settings.hub_origin`
+ * (no PARACHUTE_HUB_ORIGIN env, no expose-state, no RENDER/FLY platform var —
+ * the bare-droplet-behind-Caddy shape) MUST inject that public origin into the
+ * supervised modules' PARACHUTE_HUB_ORIGINS. Otherwise vault/scribe accept only
+ * loopback `iss` and reject every token the hub mints under the public origin
+ * (which the per-request resolveIssuer DOES stamp from the DB).
+ *
+ * These tests prove the full boot chain: DB row → `resolveStartupIssuer`
+ * (boot-time issuer seed) → `buildHubOriginsEnvValue` (the env injected at
+ * child spawn) CONTAINS the public origin.
+ */
+describe("DB hub_origin flows into the injected PARACHUTE_HUB_ORIGINS (Caddy-direct boot chain)", () => {
+  let dir: string;
+  const noExpose = (): string | undefined => undefined;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "hub-origins-db-"));
+  });
+  afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+  test("DB-persisted public origin lands in the assembled origin set", () => {
+    // Persist the Caddy public origin to the DB exactly as `hub set-origin` /
+    // `init --hub-origin` would.
+    const db = openHubDb(hubDbPath(dir));
+    setHubOrigin(db, "https://box.sslip.io");
+    db.close();
+
+    // Boot-time issuer resolution reads the DB row (passed as dbHubOrigin) —
+    // no env, no expose-state, no platform var (the bare-Caddy shape).
+    const dbOrigin = getHubOrigin(openHubDb(hubDbPath(dir))) ?? undefined;
+    const issuer = resolveStartupIssuer(
+      { ...(dbOrigin !== undefined ? { dbHubOrigin: dbOrigin } : {}) },
+      {},
+      noExpose,
+    );
+    expect(issuer).toBe("https://box.sslip.io");
+
+    // That issuer seeds the env injected into vault/scribe — the public origin
+    // MUST be in their accepted-`iss` set.
+    const set = parseHubOrigins(
+      buildHubOriginsEnvValue(dir, issuer, {}, join(dir, "expose-state.json")),
+    );
+    expect(set).toContain("https://box.sslip.io");
+    // Loopback aliases stay present (co-located CLI / loopback proxy path).
+    expect(set).toContain("http://127.0.0.1:1939");
+    expect(set).toContain("http://localhost:1939");
+  });
+
+  test("no DB origin AND nothing else → loopback-only (the regression this guards: no public origin would leak in)", () => {
+    // Fresh DB, no row, no env, no expose-state: the boot issuer is undefined
+    // and the set is loopback-only. Proves the fix doesn't fabricate an origin.
+    const dbOrigin = getHubOrigin(openHubDb(hubDbPath(dir))) ?? undefined;
+    const issuer = resolveStartupIssuer(
+      { ...(dbOrigin !== undefined ? { dbHubOrigin: dbOrigin } : {}) },
+      {},
+      noExpose,
+    );
+    expect(issuer).toBeUndefined();
+    const set = parseHubOrigins(
+      buildHubOriginsEnvValue(dir, issuer, {}, join(dir, "expose-state.json")),
+    );
+    // Loopback-only — no public origin fabricated. (Order is Set-insertion
+    // dependent; assert membership + size rather than a brittle exact array.)
+    expect(set).toContain("http://127.0.0.1:1939");
+    expect(set).toContain("http://localhost:1939");
+    expect(set).toHaveLength(2);
+  });
+});

package/src/__tests__/init.test.ts

@@ -960,6 +960,154 @@ describe("hasNoDisplay heuristic (Fix 2 — headless browser-open guard)", () =>
   });
 });
 
+describe("init --hub-origin (Caddy-direct zero-SSH boot, onboarding-streamline 2026-06-25)", () => {
+  test("persists the origin BEFORE ensureHub so modules spawn with it in one pass", async () => {
+    const h = makeHarness();
+    try {
+      const order: string[] = [];
+      const code = await init({
+        configDir: h.configDir,
+        ensureHubVersion: async () => ({
+          outcome: "match" as const,
+          installedVersion: "test",
+          messages: [],
+        }),
+        manifestPath: h.manifestPath,
+        log: () => {},
+        alive: () => false,
+        hubOrigin: "https://box.sslip.io",
+        // The load-bearing ordering assertion: the origin write MUST happen
+        // before the hub unit starts (which boots + spawns vault/scribe), so
+        // the boot-time issuer + child env pick it up without a restart.
+        setHubOriginImpl: (_dir, origin) => {
+          order.push(`set-origin:${origin}`);
+        },
+        ensureHub: async () => {
+          order.push("ensureHub");
+          writeHubPort(1939, h.configDir);
+          return { pid: 5555, port: 1939, started: true };
+        },
+        readExposeStateFn: () => undefined,
+        isTty: false,
+        platform: "linux",
+        installVaultModuleImpl: noopVaultInstall,
+      });
+      expect(code).toBe(0);
+      expect(order).toEqual(["set-origin:https://box.sslip.io", "ensureHub"]);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("default impl writes hub_settings.hub_origin to the real DB", async () => {
+    const h = makeHarness();
+    try {
+      const code = await init({
+        configDir: h.configDir,
+        ensureHubVersion: async () => ({
+          outcome: "match" as const,
+          installedVersion: "test",
+          messages: [],
+        }),
+        manifestPath: h.manifestPath,
+        log: () => {},
+        alive: () => false,
+        hubOrigin: "https://box.sslip.io",
+        // No setHubOriginImpl override → exercise the production default
+        // (openHubDb + setHubOrigin) against the harness's temp configDir.
+        ensureHub: async () => {
+          writeHubPort(1939, h.configDir);
+          return { pid: 5555, port: 1939, started: true };
+        },
+        readExposeStateFn: () => undefined,
+        isTty: false,
+        platform: "linux",
+        installVaultModuleImpl: noopVaultInstall,
+      });
+      expect(code).toBe(0);
+      const { hubDbPath, openHubDb } = await import("../hub-db.ts");
+      const { getHubOrigin } = await import("../hub-settings.ts");
+      const db = openHubDb(hubDbPath(h.configDir));
+      try {
+        expect(getHubOrigin(db)).toBe("https://box.sslip.io");
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("no --hub-origin → no persistence call (laptop/loopback path unchanged)", async () => {
+    const h = makeHarness();
+    try {
+      let setCalls = 0;
+      const code = await init({
+        configDir: h.configDir,
+        ensureHubVersion: async () => ({
+          outcome: "match" as const,
+          installedVersion: "test",
+          messages: [],
+        }),
+        manifestPath: h.manifestPath,
+        log: () => {},
+        alive: () => false,
+        setHubOriginImpl: () => {
+          setCalls++;
+        },
+        ensureHub: async () => {
+          writeHubPort(1939, h.configDir);
+          return { pid: 5555, port: 1939, started: true };
+        },
+        readExposeStateFn: () => undefined,
+        isTty: false,
+        platform: "linux",
+        installVaultModuleImpl: noopVaultInstall,
+      });
+      expect(code).toBe(0);
+      expect(setCalls).toBe(0);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("a persistence failure is non-fatal — init still reaches the wizard", async () => {
+    const h = makeHarness();
+    try {
+      const logs: string[] = [];
+      const code = await init({
+        configDir: h.configDir,
+        ensureHubVersion: async () => ({
+          outcome: "match" as const,
+          installedVersion: "test",
+          messages: [],
+        }),
+        manifestPath: h.manifestPath,
+        log: (l) => logs.push(l),
+        alive: () => false,
+        hubOrigin: "https://box.sslip.io",
+        setHubOriginImpl: () => {
+          throw new Error("disk full");
+        },
+        ensureHub: async () => {
+          writeHubPort(1939, h.configDir);
+          return { pid: 5555, port: 1939, started: true };
+        },
+        readExposeStateFn: () => undefined,
+        isTty: false,
+        platform: "linux",
+        installVaultModuleImpl: noopVaultInstall,
+      });
+      expect(code).toBe(0);
+      const joined = logs.join("\n");
+      expect(joined).toContain("Couldn't persist the hub origin");
+      expect(joined).toContain("http://127.0.0.1:1939/admin/");
+    } finally {
+      h.cleanup();
+    }
+  });
+});
+
 describe("init exposure chain", () => {
   test("TTY + no exposure + no flags → prompt is shown", async () => {
     const h = makeHarness();

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

@@ -10,7 +10,9 @@ import {
   RefreshTokenInsertError,
   findRefreshToken,
   findTokenRowByJti,
+  linkRotation,
   listActiveRevocations,
+  liveFamilyRefreshRows,
   recordTokenMint,
   revokeTokenByJti,
   signAccessToken,
@@ -623,3 +625,80 @@ describe("token registry (hub#212 Phase 1)", () => {
     }
   });
 });
+
+// hub#685 — rotation-grace primitives. The grace decision in
+// `handleTokenRefresh` is built on these two helpers; unit-cover them
+// directly so the security-load-bearing predecessor check has a tight test.
+describe("rotation grace primitives (hub#685)", () => {
+  test("rotatedTo is null on a freshly minted row, set by linkRotation", async () => {
+    const { db, cleanup } = makeDb();
+    try {
+      rotateSigningKey(db);
+      const u = await createUser(db, "owner", "pw");
+      signRefreshToken(db, {
+        jti: "pred",
+        userId: u.id,
+        clientId: "parachute-hub",
+        scopes: ["vault:read"],
+        familyId: "fam-1",
+      });
+      expect(findTokenRowByJti(db, "pred")?.rotatedTo).toBeNull();
+
+      signRefreshToken(db, {
+        jti: "succ",
+        userId: u.id,
+        clientId: "parachute-hub",
+        scopes: ["vault:read"],
+        familyId: "fam-1",
+      });
+      linkRotation(db, "pred", "succ");
+      expect(findTokenRowByJti(db, "pred")?.rotatedTo).toBe("succ");
+      // Successor itself has not rotated yet.
+      expect(findTokenRowByJti(db, "succ")?.rotatedTo).toBeNull();
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("liveFamilyRefreshRows returns only un-revoked, un-expired refresh rows in the family", async () => {
+    const { db, cleanup } = makeDb();
+    try {
+      rotateSigningKey(db);
+      const u = await createUser(db, "owner", "pw");
+      const t0 = new Date("2026-06-24T00:00:00Z");
+      for (const jti of ["a", "b", "c"]) {
+        signRefreshToken(db, {
+          jti,
+          userId: u.id,
+          clientId: "parachute-hub",
+          scopes: ["vault:read"],
+          familyId: "fam-x",
+          now: () => t0,
+        });
+      }
+      // A different family — must never leak in.
+      signRefreshToken(db, {
+        jti: "other",
+        userId: u.id,
+        clientId: "parachute-hub",
+        scopes: ["vault:read"],
+        familyId: "fam-y",
+        now: () => t0,
+      });
+      // Revoke one of the three.
+      revokeTokenByJti(db, "b", t0);
+
+      const live = liveFamilyRefreshRows(db, "fam-x", t0)
+        .map((r) => r.jti)
+        .sort();
+      expect(live).toEqual(["a", "c"]);
+
+      // Evaluated PAST the 30-day TTL: every row in the family is expired,
+      // so none count as a live tip — the grace path can't rotate into one.
+      const afterExpiry = new Date(t0.getTime() + REFRESH_TOKEN_TTL_MS + 1);
+      expect(liveFamilyRefreshRows(db, "fam-x", afterExpiry)).toEqual([]);
+    } finally {
+      cleanup();
+    }
+  });
+});

package/src/__tests__/module-manifest.test.ts

@@ -277,11 +277,13 @@ describe("validateModuleManifest", () => {
   // --- 2026-06-09 modular-UI architecture P1 fields: focus / configUiUrl /
   //     adminCapabilities / events / actions. All optional + additive. ---
 
-  test("focus accepts core / experimental and rejects anything else", () => {
+  test("focus accepts core / experimental / deprecated and rejects anything else", () => {
     expect(validateModuleManifest({ ...VALID, focus: "core" }, "x").focus).toBe("core");
     expect(validateModuleManifest({ ...VALID, focus: "experimental" }, "x").focus).toBe(
       "experimental",
     );
+    // `deprecated` tier (2026-06-25) — a module can self-declare it.
+    expect(validateModuleManifest({ ...VALID, focus: "deprecated" }, "x").focus).toBe("deprecated");
     // Absent stays absent (hub falls back to its default map downstream).
     expect(validateModuleManifest(VALID, "x").focus).toBeUndefined();
     expect(() => validateModuleManifest({ ...VALID, focus: "headline" }, "x")).toThrow(/focus/);