@openparachute/hub 0.6.3 → 0.6.4-rc.1

package/src/__tests__/account-usage.test.ts

@@ -0,0 +1,137 @@
+/**
+ * Unit tests for the `/account/` per-vault usage fetch + formatting
+ * (`account-usage.ts`). The fetch mints a read token + hits the vault's loopback
+ * `/.parachute/usage` endpoint; it must be fault-tolerant (any failure → null)
+ * and shape-strict (a malformed body → null, not a render of `undefined`).
+ */
+import type { Database } from "bun:sqlite";
+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 {
+  type VaultUsageStat,
+  fetchVaultUsage,
+  formatBytes,
+  formatUsageStat,
+} from "../account-usage.ts";
+import { hubDbPath, openHubDb } from "../hub-db.ts";
+
+interface Harness {
+  db: Database;
+  cleanup: () => void;
+}
+
+function makeHarness(): Harness {
+  const dir = mkdtempSync(join(tmpdir(), "phub-account-usage-"));
+  const db = openHubDb(hubDbPath(dir));
+  return {
+    db,
+    cleanup: () => {
+      db.close();
+      rmSync(dir, { recursive: true, force: true });
+    },
+  };
+}
+
+let harness: Harness;
+beforeEach(() => {
+  harness = makeHarness();
+});
+afterEach(() => {
+  harness.cleanup();
+});
+
+/** A stub signer — no real key needed; the fetch only carries the token string. */
+const stubSign = async () => ({
+  token: "stub.jwt.token",
+  jti: "jti-1",
+  expiresAt: new Date(Date.now() + 60000).toISOString(),
+});
+
+function baseDeps(fetchImpl: typeof fetch) {
+  return {
+    db: harness.db,
+    hubOrigin: "https://hub.test",
+    vaultPort: 1940,
+    userId: "user-1",
+    fetchImpl,
+    signToken: stubSign as never,
+  };
+}
+
+describe("fetchVaultUsage", () => {
+  test("returns the stat on a well-formed usage report", async () => {
+    const fetchImpl = (async () =>
+      new Response(
+        JSON.stringify({
+          counts: { notes: 42, attachments: 3, links: 5, tags: 2 },
+          bytes: { content: 1000, db: 2048, assets: 4096, total: 6144 },
+          computedAt: new Date().toISOString(),
+          cached: false,
+        }),
+        { status: 200, headers: { "content-type": "application/json" } },
+      )) as unknown as typeof fetch;
+    const stat = await fetchVaultUsage("work", baseDeps(fetchImpl));
+    expect(stat).toEqual({ notes: 42, totalBytes: 6144 });
+  });
+
+  test("calls the vault's loopback usage endpoint with a Bearer", async () => {
+    let seenUrl = "";
+    let seenAuth = "";
+    const fetchImpl = (async (url: string, init?: RequestInit) => {
+      seenUrl = url;
+      seenAuth = (init?.headers as Record<string, string>)?.authorization ?? "";
+      return new Response(JSON.stringify({ counts: { notes: 1 }, bytes: { total: 10 } }), {
+        status: 200,
+      });
+    }) as unknown as typeof fetch;
+    await fetchVaultUsage("work", baseDeps(fetchImpl));
+    expect(seenUrl).toBe("http://127.0.0.1:1940/vault/work/.parachute/usage");
+    expect(seenAuth).toBe("Bearer stub.jwt.token");
+  });
+
+  test("returns null on a non-2xx response (vault down / 403 / 404)", async () => {
+    for (const status of [403, 404, 500]) {
+      const fetchImpl = (async () => new Response("nope", { status })) as unknown as typeof fetch;
+      const stat = await fetchVaultUsage("work", baseDeps(fetchImpl));
+      expect(stat).toBeNull();
+    }
+  });
+
+  test("returns null when the body is malformed (missing counts/bytes)", async () => {
+    const fetchImpl = (async () =>
+      new Response(JSON.stringify({ counts: {}, bytes: {} }), {
+        status: 200,
+      })) as unknown as typeof fetch;
+    const stat = await fetchVaultUsage("work", baseDeps(fetchImpl));
+    expect(stat).toBeNull();
+  });
+
+  test("returns null when fetch throws (network error)", async () => {
+    const fetchImpl = (async () => {
+      throw new Error("ECONNREFUSED");
+    }) as unknown as typeof fetch;
+    const stat = await fetchVaultUsage("work", baseDeps(fetchImpl));
+    expect(stat).toBeNull();
+  });
+});
+
+describe("formatUsageStat / formatBytes", () => {
+  test("pluralizes notes + renders the byte size", () => {
+    expect(formatUsageStat({ notes: 1, totalBytes: 1024 } as VaultUsageStat)).toBe("1 note · 1 KB");
+    expect(formatUsageStat({ notes: 42, totalBytes: 6 * 1024 * 1024 } as VaultUsageStat)).toBe(
+      "42 notes · 6.0 MB",
+    );
+    expect(formatUsageStat({ notes: 0, totalBytes: 0 } as VaultUsageStat)).toBe("0 notes · 0 B");
+  });
+
+  test("formatBytes picks the largest sensible unit", () => {
+    expect(formatBytes(0)).toBe("0 B");
+    expect(formatBytes(512)).toBe("512 B");
+    expect(formatBytes(2048)).toBe("2 KB");
+    expect(formatBytes(5 * 1024 * 1024)).toBe("5.0 MB");
+    expect(formatBytes(3 * 1024 * 1024 * 1024)).toBe("3.0 GB");
+    expect(formatBytes(-5)).toBe("0 B");
+  });
+});

package/src/__tests__/account-vault-admin-token.test.ts

@@ -0,0 +1,301 @@
+/**
+ * Security tests for the friend-facing vault-ADMIN deep-link mint —
+ * `POST /account/vault-admin-token/<name>` (`handleAccountVaultAdminTokenPost`).
+ *
+ * The non-admin sibling of `/admin/vault-admin-token/<name>` (which is
+ * first-admin-gated). This one is gated on ASSIGNMENT: an assigned user holds
+ * `admin` on their vault (2026-05-30) and may bootstrap the vault's own admin
+ * SPA — token rotation + Git backup config. Authorization is tested
+ * adversarially. The spine:
+ *   - No session              → 401.
+ *   - Assigned vault          → 303 → <vault-url><managementUrl>#token=<jwt>,
+ *                               token carries `vault:<name>:admin`,
+ *                               `aud=vault.<name>`, `iss=<hub>`, sub=user.
+ *   - UNassigned vault        → 403 (cross-vault blocked).
+ *   - First admin             → 403 (no user_vaults rows → uses SPA path).
+ *   - Unrotated user (item F) → 303 → /account/change-password, NO mint
+ *                               (does not reintroduce the #469 bypass).
+ *   - CSRF missing/mismatch   → 400.
+ *   - Invalid vault name      → 400.
+ */
+import type { Database } from "bun:sqlite";
+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 { handleAccountVaultAdminTokenPost } from "../account-vault-admin-token.ts";
+import { VAULT_ADMIN_TOKEN_TTL_SECONDS } from "../admin-vault-admin-token.ts";
+import { CSRF_FIELD_NAME, buildCsrfCookie, generateCsrfToken } from "../csrf.ts";
+import { hubDbPath, openHubDb } from "../hub-db.ts";
+import { validateAccessToken } from "../jwt-sign.ts";
+import { SESSION_TTL_MS, buildSessionCookie, createSession } from "../sessions.ts";
+import { createUser } from "../users.ts";
+
+const ISSUER = "https://hub.test";
+
+interface Harness {
+  db: Database;
+  cleanup: () => void;
+}
+
+function makeHarness(): Harness {
+  const dir = mkdtempSync(join(tmpdir(), "phub-account-vault-admin-token-"));
+  const db = openHubDb(hubDbPath(dir));
+  return {
+    db,
+    cleanup: () => {
+      db.close();
+      rmSync(dir, { recursive: true, force: true });
+    },
+  };
+}
+
+let harness: Harness;
+beforeEach(() => {
+  harness = makeHarness();
+});
+afterEach(() => {
+  harness.cleanup();
+});
+
+const deps = (extra: { managementUrl?: string } = {}) => ({
+  db: harness.db,
+  hubOrigin: ISSUER,
+  ...extra,
+});
+
+/** A shared CSRF token + matching cookie value for the double-submit handshake. */
+function csrfPair(): { token: string; cookieFragment: string } {
+  const token = generateCsrfToken();
+  const cookie = buildCsrfCookie(token, { secure: false }).split(";")[0] ?? "";
+  return { token, cookieFragment: cookie };
+}
+
+/**
+ * First-admin operator + a friend assigned to `vaults`. `passwordChanged`
+ * defaults true (the precondition for minting now — item F gates an unrotated
+ * friend first). Pass `passwordChanged: false` to exercise the force-change gate.
+ */
+async function seedFriend(
+  vaults: string[],
+  opts: { passwordChanged?: boolean } = {},
+): Promise<{ friendId: string; cookie: string; csrfToken: string }> {
+  await createUser(harness.db, "operator", "operator-password-123");
+  const friend = await createUser(harness.db, "friend", "friend-password-123", {
+    assignedVaults: vaults,
+    allowMulti: true,
+    passwordChanged: opts.passwordChanged ?? true,
+  });
+  const session = createSession(harness.db, { userId: friend.id });
+  const { token, cookieFragment } = csrfPair();
+  const sessionCookie = buildSessionCookie(session.id, Math.floor(SESSION_TTL_MS / 1000));
+  const cookie = `${sessionCookie}; ${cookieFragment}`;
+  return { friendId: friend.id, cookie, csrfToken: token };
+}
+
+function mintReq(
+  vaultName: string,
+  opts: { cookie?: string; csrfToken?: string; omitCsrf?: boolean; method?: string } = {},
+): Request {
+  const body = new URLSearchParams();
+  if (!opts.omitCsrf && opts.csrfToken !== undefined) body.set(CSRF_FIELD_NAME, opts.csrfToken);
+  const headers: Record<string, string> = {
+    "content-type": "application/x-www-form-urlencoded",
+  };
+  if (opts.cookie) headers.cookie = opts.cookie;
+  return new Request(`${ISSUER}/account/vault-admin-token/${encodeURIComponent(vaultName)}`, {
+    method: opts.method ?? "POST",
+    headers,
+    body: body.toString(),
+  });
+}
+
+/** Pull the `#token=<jwt>` out of a 303 Location fragment. */
+function tokenFromLocation(location: string): string {
+  const m = location.match(/[#&]token=([^&]+)$/);
+  expect(m).not.toBeNull();
+  return m![1] as string;
+}
+
+describe("handleAccountVaultAdminTokenPost — happy path (assigned vault)", () => {
+  test("303 → vault admin SPA with #token carrying vault:<name>:admin", async () => {
+    const { friendId, cookie, csrfToken } = await seedFriend(["work"]);
+    const res = await handleAccountVaultAdminTokenPost(
+      mintReq("work", { cookie, csrfToken }),
+      "work",
+      deps(),
+    );
+    expect(res.status).toBe(303);
+    expect(res.headers.get("cache-control")).toBe("no-store");
+    const location = res.headers.get("location") ?? "";
+    // Default managementUrl is /admin/ → lands on the vault admin SPA home.
+    expect(location.startsWith(`${ISSUER}/vault/work/admin/#token=`)).toBe(true);
+
+    const token = tokenFromLocation(location);
+    const validated = await validateAccessToken(harness.db, token, ISSUER);
+    expect(validated.payload.sub).toBe(friendId);
+    expect(validated.payload.iss).toBe(ISSUER);
+    expect(validated.payload.aud).toBe("vault.work");
+    const scopeClaim = (validated.payload as { scope?: string }).scope ?? "";
+    expect(scopeClaim.split(/\s+/)).toEqual(["vault:work:admin"]);
+    expect((validated.payload as { vault_scope?: string[] }).vault_scope).toEqual(["work"]);
+
+    // Short TTL (10 min, deep-link bootstrap token — not the 90-day headless one).
+    const expMs = new Date((validated.payload.exp ?? 0) * 1000).getTime();
+    const skew = expMs - Date.now();
+    expect(skew).toBeGreaterThan((VAULT_ADMIN_TOKEN_TTL_SECONDS - 60) * 1000);
+    expect(skew).toBeLessThan((VAULT_ADMIN_TOKEN_TTL_SECONDS + 60) * 1000);
+
+    // A revocable registry row was written for the friend.
+    const rows = harness.db.query<{ n: number }, []>("SELECT COUNT(*) AS n FROM tokens").get();
+    expect(rows?.n).toBe(1);
+  });
+
+  test("honors a vault-declared managementUrl (e.g. a custom admin path)", async () => {
+    const { cookie, csrfToken } = await seedFriend(["work"]);
+    const res = await handleAccountVaultAdminTokenPost(
+      mintReq("work", { cookie, csrfToken }),
+      "work",
+      deps({ managementUrl: "/manage/" }),
+    );
+    expect(res.status).toBe(303);
+    const location = res.headers.get("location") ?? "";
+    expect(location.startsWith(`${ISSUER}/vault/work/manage/#token=`)).toBe(true);
+  });
+
+  test("a friend assigned to multiple vaults can deep-link each, never cross-vault", async () => {
+    const { cookie, csrfToken } = await seedFriend(["work", "home"]);
+    for (const v of ["work", "home"]) {
+      const res = await handleAccountVaultAdminTokenPost(
+        mintReq(v, { cookie, csrfToken }),
+        v,
+        deps(),
+      );
+      expect(res.status).toBe(303);
+      const token = tokenFromLocation(res.headers.get("location") ?? "");
+      const validated = await validateAccessToken(harness.db, token, ISSUER);
+      expect(validated.payload.aud).toBe(`vault.${v}`);
+    }
+    const res = await handleAccountVaultAdminTokenPost(
+      mintReq("secret", { cookie, csrfToken }),
+      "secret",
+      deps(),
+    );
+    expect(res.status).toBe(403);
+  });
+});
+
+describe("handleAccountVaultAdminTokenPost — authorization gates (adversarial)", () => {
+  test("401 when no session cookie is present", async () => {
+    const { token, cookieFragment } = csrfPair();
+    const res = await handleAccountVaultAdminTokenPost(
+      mintReq("work", { cookie: cookieFragment, csrfToken: token }),
+      "work",
+      deps(),
+    );
+    expect(res.status).toBe(401);
+  });
+
+  test("403 for a vault the friend is NOT assigned to (cross-vault)", async () => {
+    const { cookie, csrfToken } = await seedFriend(["work"]);
+    const res = await handleAccountVaultAdminTokenPost(
+      mintReq("other", { cookie, csrfToken }),
+      "other",
+      deps(),
+    );
+    expect(res.status).toBe(403);
+    // No token minted.
+    const rows = harness.db.query<{ n: number }, []>("SELECT COUNT(*) AS n FROM tokens").get();
+    expect(rows?.n).toBe(0);
+  });
+
+  test("403 — the first admin cannot deep-link here (no user_vaults rows; uses SPA path)", async () => {
+    // Mirrors `/admin/vault-admin-token` being friend-blocked: the inverse, this
+    // friend surface refuses the unrestricted admin. Admins use the SPA's
+    // first-admin-gated /admin/vault-admin-token instead.
+    const admin = await createUser(harness.db, "operator", "operator-password-123");
+    const session = createSession(harness.db, { userId: admin.id });
+    const { token, cookieFragment } = csrfPair();
+    const cookie = `${buildSessionCookie(session.id, Math.floor(SESSION_TTL_MS / 1000))}; ${cookieFragment}`;
+    const res = await handleAccountVaultAdminTokenPost(
+      mintReq("work", { cookie, csrfToken: token }),
+      "work",
+      deps(),
+    );
+    expect(res.status).toBe(403);
+  });
+
+  test("an invalid vault name is rejected before any mint", async () => {
+    const { cookie, csrfToken } = await seedFriend(["work"]);
+    for (const name of ["has..dots", "Work", "WORK"]) {
+      const res = await handleAccountVaultAdminTokenPost(
+        mintReq(name, { cookie, csrfToken }),
+        name,
+        deps(),
+      );
+      expect(res.status).toBe(400);
+    }
+  });
+
+  // Item F / hub#469 — force-change gate. An assigned user who has NOT rotated
+  // the admin-set temp password is redirected to change-password BEFORE minting,
+  // so the temp-password handoff can't be parlayed into a vault-admin deep-link.
+  // This is the SAME gate /account/vault-token applies (post-#550) — it does NOT
+  // reintroduce the bypass #469 closed. Fires AFTER authority (so an unassigned
+  // request still 403s) and BEFORE the mint.
+  test("authorized but unrotated user → 303 to /account/change-password, NO mint (item F)", async () => {
+    const { cookie, csrfToken } = await seedFriend(["work"], { passwordChanged: false });
+    const res = await handleAccountVaultAdminTokenPost(
+      mintReq("work", { cookie, csrfToken }),
+      "work",
+      deps(),
+    );
+    expect(res.status).toBe(303);
+    expect(res.headers.get("location")).toBe("/account/change-password");
+    // Critically: no token was minted and no deep-link token leaked.
+    const rows = harness.db.query<{ n: number }, []>("SELECT COUNT(*) AS n FROM tokens").get();
+    expect(rows?.n).toBe(0);
+  });
+
+  test("an UNASSIGNED unrotated user still 403s (authority precedes the force-change gate)", async () => {
+    const { cookie, csrfToken } = await seedFriend(["work"], { passwordChanged: false });
+    const res = await handleAccountVaultAdminTokenPost(
+      mintReq("other", { cookie, csrfToken }),
+      "other",
+      deps(),
+    );
+    expect(res.status).toBe(403);
+  });
+});
+
+describe("handleAccountVaultAdminTokenPost — CSRF + method", () => {
+  test("405 on non-POST", async () => {
+    const { cookie } = await seedFriend(["work"]);
+    const res = await handleAccountVaultAdminTokenPost(
+      mintReq("work", { cookie, method: "GET" }),
+      "work",
+      deps(),
+    );
+    expect(res.status).toBe(405);
+  });
+
+  test("400 when the CSRF token is missing", async () => {
+    const { cookie } = await seedFriend(["work"]);
+    const res = await handleAccountVaultAdminTokenPost(
+      mintReq("work", { cookie, omitCsrf: true }),
+      "work",
+      deps(),
+    );
+    expect(res.status).toBe(400);
+  });
+
+  test("400 when the CSRF form token does not match the cookie", async () => {
+    const { cookie } = await seedFriend(["work"]);
+    const res = await handleAccountVaultAdminTokenPost(
+      mintReq("work", { cookie, csrfToken: generateCsrfToken() }),
+      "work",
+      deps(),
+    );
+    expect(res.status).toBe(400);
+  });
+});

package/src/__tests__/account-vault-token.test.ts

@@ -73,14 +73,23 @@ function csrfPair(): { token: string; cookieFragment: string } {
   return { token, cookieFragment: cookie };
 }
 
-/** Build the first-admin operator + a friend assigned to `vaults`. */
+/**
+ * Build the first-admin operator + a friend assigned to `vaults`.
+ *
+ * `passwordChanged` defaults to true: the friend has already rotated the admin-
+ * set temp password, which is the precondition for minting a token now (item F
+ * / hub#469 — an unrotated friend is force-redirected before any mint). Pass
+ * `passwordChanged: false` to exercise the force-change gate.
+ */
 async function seedFriend(
   vaults: string[],
+  opts: { passwordChanged?: boolean } = {},
 ): Promise<{ friendId: string; cookie: string; csrfToken: string }> {
   await createUser(harness.db, "operator", "operator-password-123");
   const friend = await createUser(harness.db, "friend", "friend-password-123", {
     assignedVaults: vaults,
     allowMulti: true,
+    passwordChanged: opts.passwordChanged ?? true,
   });
   const session = createSession(harness.db, { userId: friend.id });
   const { token, cookieFragment } = csrfPair();
@@ -282,6 +291,49 @@ describe("handleAccountVaultTokenPost — authorization gates (adversarial)", ()
     );
     expect(res.status).toBe(400);
   });
+
+  // Item I — uppercase vault names are rejected at the hub edge (lowercase-only,
+  // matching vault's init; the old `[a-zA-Z0-9_-]` superset drifted from it).
+  test("an uppercase vault name is rejected (item I — lowercase-only)", async () => {
+    const { cookie, csrfToken } = await seedFriend(["work"]);
+    for (const name of ["Work", "WORK", "myVault"]) {
+      const res = await handleAccountVaultTokenPost(
+        mintReq(name, { cookie, csrfToken, verb: "read" }),
+        name,
+        deps(),
+      );
+      expect(res.status).toBe(400);
+    }
+  });
+
+  // Item F / hub#469 — force-change gate. An assigned friend who has NOT yet
+  // rotated the admin-set temp password is redirected to the change-password
+  // rail instead of minting a long-lived token (which would outlive the
+  // rotation). The gate fires AFTER the authority checks (so an unassigned
+  // request still 403s) and BEFORE the mint.
+  test("authorized but unrotated friend → 303 to /account/change-password, no mint (item F)", async () => {
+    const { cookie, csrfToken } = await seedFriend(["work"], { passwordChanged: false });
+    const res = await handleAccountVaultTokenPost(
+      mintReq("work", { cookie, csrfToken, verb: "read" }),
+      "work",
+      deps(),
+    );
+    expect(res.status).toBe(303);
+    expect(res.headers.get("location")).toBe("/account/change-password");
+    // No token row was written for the friend.
+    const rows = harness.db.query<{ n: number }, []>("SELECT COUNT(*) AS n FROM tokens").get();
+    expect(rows?.n).toBe(0);
+  });
+
+  test("an UNASSIGNED unrotated friend still 403s (authority precedes the force-change gate)", async () => {
+    const { cookie, csrfToken } = await seedFriend(["work"], { passwordChanged: false });
+    const res = await handleAccountVaultTokenPost(
+      mintReq("other", { cookie, csrfToken, verb: "read" }),
+      "other",
+      deps(),
+    );
+    expect(res.status).toBe(403);
+  });
 });
 
 describe("handleAccountVaultTokenPost — CSRF + method + rate limit", () => {

package/src/__tests__/admin-vault-admin-token.test.ts

@@ -121,6 +121,23 @@ describe("handleVaultAdminToken", () => {
     expect(res.status).toBe(400);
   });
 
+  // Item I — uppercase names are rejected at the hub edge (lowercase-only,
+  // matching vault's init). Rejected on shape (400) before the known-vault check.
+  test("400 when the vault name contains uppercase letters (item I)", async () => {
+    const { cookie } = await withSession();
+    for (const name of ["Work", "WORK", "myVault"]) {
+      const req = new Request(`${ISSUER}/admin/vault-admin-token/${name}`, {
+        headers: { cookie },
+      });
+      const res = await handleVaultAdminToken(req, name, {
+        db: harness.db,
+        issuer: ISSUER,
+        knownVaultNames: known(name, "work"),
+      });
+      expect(res.status).toBe(400);
+    }
+  });
+
   test("200 mints a JWT carrying vault:<name>:admin", async () => {
     const { cookie, userId } = await withSession();
     const req = new Request(`${ISSUER}/admin/vault-admin-token/work`, { headers: { cookie } });

package/src/__tests__/admin-vaults.test.ts

@@ -225,6 +225,26 @@ describe("POST /vaults — body validation", () => {
     }
   });
 
+  // Item I — uppercase is rejected at the hub edge (vault's init is
+  // lowercase-only `[a-z0-9_-]`; a hub `[a-zA-Z0-9_-]` superset drifted from it).
+  test("400 when name contains uppercase letters (item I — lowercase-only)", async () => {
+    const h = makeHarness();
+    try {
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        rotateSigningKey(db);
+        for (const name of ["Work", "MyVault", "FOO", "camelCase"]) {
+          const res = await call({ db, manifestPath: h.manifestPath, body: { name } });
+          expect(res.status).toBe(400);
+        }
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
   test('400 when name is the reserved "list"', async () => {
     const h = makeHarness();
     try {