@openparachute/hub 0.6.3 → 0.6.4-rc.10

package/src/account-mirror.ts

@@ -0,0 +1,126 @@
+/**
+ * Per-vault backup (mirror) status fetch for the friend-facing `/account/` home.
+ *
+ * Vault serves `GET /vault/<name>/.parachute/mirror` (ADMIN-scoped) returning
+ * the persisted mirror config + the runtime status the manager is tracking:
+ *   { config: { enabled, location, external_path, sync_mode, auto_push, ... },
+ *     status: { enabled, last_commit_sha, last_error, ... } }
+ *
+ * The `/account/` GET handler renders one tile per assigned vault; this module
+ * fetches each vault's mirror status so the tile can show a warm, plain-language
+ * backup line ("✓ Backed up — full version history", or "+ GitHub" when a push
+ * remote is configured). Backup is the local git version-history mirror vault
+ * stands up by default; the GitHub variant is the auto-push-to-a-remote setup.
+ *
+ * The endpoint gates on `vault:<name>:admin`, so this is only fetched for users
+ * who hold the admin verb on the vault (same gate as the "Advanced vault
+ * settings ↗" deep-link). We mint a short-lived `vault:<name>:admin` token —
+ * the same authority the OAuth issuer / admin path would grant them — and call
+ * the vault over loopback.
+ *
+ * Tolerant by design: any failure (vault down, endpoint absent on an older
+ * vault, mint failure, malformed JSON, insufficient scope) resolves to `null`
+ * so the tile simply omits the backup line rather than breaking the page —
+ * exactly the posture of `account-usage.ts`'s `fetchVaultUsage`.
+ *
+ * Injectable seams (`fetchImpl`, `signToken`) keep it unit-testable without a
+ * live vault or real signing key.
+ */
+import type { Database } from "bun:sqlite";
+import { signAccessToken } from "./jwt-sign.ts";
+
+/** The subset of vault's mirror report the `/account/` tile renders. */
+export interface VaultMirrorStat {
+  /** Backup is on — a version-history mirror is configured + bootstrapped. */
+  enabled: boolean;
+  /**
+   * Backup leaves the box — an auto-push remote (GitHub or any git remote) is
+   * configured (`config.auto_push`). Drives the "+ GitHub" line variant AND
+   * gates the "Back up to GitHub ↗" action (suppressed once already pushing).
+   * Threaded through as a proper boolean so the renderer never has to re-derive
+   * "are we pushing?" from display-string content.
+   */
+  backedUpToRemote: boolean;
+}
+
+/** Short TTL for the admin token — used immediately for one loopback call. */
+const MIRROR_READ_TOKEN_TTL_SECONDS = 60;
+
+export interface FetchVaultMirrorStatusDeps {
+  db: Database;
+  /** Hub origin — `iss` of the minted token. */
+  hubOrigin: string;
+  /** Loopback port the vault backend listens on (from services.json). */
+  vaultPort: number;
+  /** The user minting against their own admin authority — `sub` of the token. */
+  userId: string;
+  /** Test seam — `globalThis.fetch` in production. */
+  fetchImpl?: typeof fetch;
+  /** Test seam — defaults to the real `signAccessToken`. */
+  signToken?: typeof signAccessToken;
+  /** Test seam for the clock. */
+  now?: () => Date;
+}
+
+/**
+ * Fetch one vault's backup (mirror) status for the friend's tile, or `null` on
+ * any failure.
+ *
+ * Mints a `vault:<name>:admin` bearer for `userId` (capped to that one vault via
+ * `vaultScope`) and GETs the vault's loopback mirror endpoint. Never throws —
+ * the page renders without the backup line on any error.
+ *
+ * "Backed up" is true when the persisted config says `enabled` (a version-
+ * history mirror) — we read the persisted config, not just the runtime
+ * `status.enabled`, so a freshly-configured-but-not-yet-bootstrapped vault still
+ * reads as backed up. `backedUpToRemote` is true when an auto-push remote is
+ * configured (the GitHub variant of backup).
+ */
+export async function fetchVaultMirrorStatus(
+  vaultName: string,
+  deps: FetchVaultMirrorStatusDeps,
+): Promise<VaultMirrorStat | null> {
+  const fetchImpl = deps.fetchImpl ?? fetch;
+  const sign = deps.signToken ?? signAccessToken;
+  try {
+    const scope = `vault:${vaultName}:admin`;
+    const minted = await sign(deps.db, {
+      sub: deps.userId,
+      scopes: [scope],
+      audience: `vault.${vaultName}`,
+      clientId: "parachute-account",
+      issuer: deps.hubOrigin,
+      ttlSeconds: MIRROR_READ_TOKEN_TTL_SECONDS,
+      vaultScope: [vaultName],
+      ...(deps.now !== undefined ? { now: deps.now } : {}),
+    });
+    const url = `http://127.0.0.1:${deps.vaultPort}/vault/${vaultName}/.parachute/mirror`;
+    const res = await fetchImpl(url, {
+      headers: { authorization: `Bearer ${minted.token}`, accept: "application/json" },
+    });
+    if (!res.ok) return null;
+    const body = (await res.json()) as {
+      config?: { enabled?: unknown; auto_push?: unknown };
+    };
+    const enabled = body.config?.enabled;
+    if (typeof enabled !== "boolean") return null;
+    const backedUpToRemote = body.config?.auto_push === true;
+    return { enabled, backedUpToRemote };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Format a mirror stat as the warm, plain-language backup line the tile shows,
+ * or `null` when backup is off (the tile then omits the line entirely — we
+ * don't nag with a "not backed up" warning on the everyday home).
+ *
+ * Exported for direct unit testing + reuse by the renderer.
+ */
+export function formatMirrorLine(stat: VaultMirrorStat): string | null {
+  if (!stat.enabled) return null;
+  return stat.backedUpToRemote
+    ? "Backed up — version history + GitHub"
+    : "Backed up — full version history";
+}

package/src/account-setup.ts

@@ -0,0 +1,381 @@
+/**
+ * `/account/setup/<token>` — invite redemption (design
+ * 2026-06-04-individual-users-and-vault-operations.md §7).
+ *
+ * Server-rendered (NOT the SPA), mirroring `/login` + the setup wizard's
+ * account-claim flow (`setup-wizard.ts` `handleSetupAccountPost`). A brand-new
+ * invitee opens the link with no session and no JS:
+ *
+ *   GET  → render the "pick username + password (+ vault name)" form.
+ *   POST → redeem: look up the invite by sha256(token), validate it's still
+ *          redeemable, validate credentials, provision the vault, create the
+ *          user, stamp the invite used, mint a session, 302 → /account/.
+ *
+ * Redeem ORDERING (the re-usability guarantee, mirroring the wizard):
+ *   1. lookup + validate the invite (not-found/expired/used/revoked)
+ *   2. validate username/password (+ vault name)
+ *   3. provision the vault (must FRESHLY CREATE — reject a pre-existing name;
+ *      attaching the new user to someone else's vault is a cross-tenant breach)
+ *   4. createUser (the commit point)
+ *   5. consumeInvite — stamp used_at + redeemed_user_id ONLY AFTER (4) commits
+ *   6. createSession + cookie + 302
+ *
+ * Because the invite is consumed only after the user row commits, a
+ * createUser exception (UNIQUE collision, disk full, anything) leaves the
+ * invite re-usable — the invitee can simply retry. `consumeInvite`'s
+ * `used_at IS NULL` guard makes the stamp itself single-use / race-free.
+ *
+ * What an invite pre-authorizes: EXACTLY one account + the one named/created
+ * vault at the baked-in role — NEVER host:admin, NEVER another vault. The new
+ * user gets `assignedVaults:[that vault]` with the invite's role; nothing
+ * grants admin posture (the first-admin-by-earliest-row heuristic is
+ * untouched — an invited user is never the earliest row).
+ */
+import type { Database } from "bun:sqlite";
+import { renderAdminError, renderInviteSetup } from "./admin-login-ui.ts";
+import { type RunResult, provisionVault } from "./admin-vaults.ts";
+import { CSRF_FIELD_NAME, ensureCsrfToken, verifyCsrfToken } from "./csrf.ts";
+import {
+  InviteExpiredError,
+  InviteNotFoundError,
+  InviteRevokedError,
+  InviteUsedError,
+  assertInviteRedeemable,
+  consumeInvite,
+} from "./invites.ts";
+import { checkAndRecord, clientIpFromRequest } from "./rate-limit.ts";
+import { isHttpsRequest } from "./request-protocol.ts";
+import { SESSION_TTL_MS, buildSessionCookie, createSession } from "./sessions.ts";
+import {
+  PASSWORD_MAX_LEN,
+  UsernameTakenError,
+  createUser,
+  getUserByUsernameCI,
+  validatePassword,
+  validateUsername,
+} from "./users.ts";
+import { validateVaultName } from "./vault-name.ts";
+
+export interface AccountSetupDeps {
+  db: Database;
+  /** Hub origin — JWT `iss` for any vault bootstrap mint + the URL base. */
+  hubOrigin: string;
+  manifestPath?: string;
+  /** Test seam: vault provisioning shell-out. */
+  runCommand?: (cmd: readonly string[]) => Promise<RunResult>;
+  /** Test seam: clock for the rate limiter. */
+  now?: () => Date;
+}
+
+function htmlResponse(body: string, status = 200, extra: Record<string, string> = {}): Response {
+  return new Response(body, {
+    status,
+    headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-store", ...extra },
+  });
+}
+
+/**
+ * Map an invite-rejection error to a status + user-facing copy. Not-found →
+ * 404 (don't confirm the token shape); expired/used/revoked → 410 Gone (the
+ * link existed but is no longer redeemable).
+ */
+function rejectInvite(err: unknown): Response {
+  if (err instanceof InviteNotFoundError) {
+    return htmlResponse(
+      renderAdminError({
+        title: "Invite not found",
+        message:
+          "This invite link is not valid. Check that you copied the whole link, or ask your hub operator for a new one.",
+      }),
+      404,
+    );
+  }
+  if (err instanceof InviteExpiredError) {
+    return htmlResponse(
+      renderAdminError({
+        title: "Invite expired",
+        message: "This invite link has expired. Ask your hub operator for a new one.",
+      }),
+      410,
+    );
+  }
+  if (err instanceof InviteUsedError) {
+    return htmlResponse(
+      renderAdminError({
+        title: "Invite already used",
+        message:
+          "This invite link has already been used to create an account. If that wasn't you, contact your hub operator.",
+      }),
+      410,
+    );
+  }
+  if (err instanceof InviteRevokedError) {
+    return htmlResponse(
+      renderAdminError({
+        title: "Invite revoked",
+        message: "This invite link has been revoked by your hub operator. Ask them for a new one.",
+      }),
+      410,
+    );
+  }
+  // Unexpected — fail closed.
+  return htmlResponse(
+    renderAdminError({ title: "Invite error", message: "Could not process this invite link." }),
+    500,
+  );
+}
+
+/** GET /account/setup/<token> — render the claim form (or a rejection page). */
+export function handleAccountSetupGet(
+  req: Request,
+  rawToken: string,
+  deps: AccountSetupDeps,
+): Response {
+  const now = (deps.now ?? (() => new Date()))();
+  let invite: ReturnType<typeof assertInviteRedeemable>;
+  try {
+    invite = assertInviteRedeemable(deps.db, rawToken, now);
+  } catch (err) {
+    return rejectInvite(err);
+  }
+  const csrf = ensureCsrfToken(req);
+  const setCookie: Record<string, string> = csrf.setCookie ? { "set-cookie": csrf.setCookie } : {};
+  return htmlResponse(
+    renderInviteSetup({
+      token: rawToken,
+      csrfToken: csrf.token,
+      pinnedVaultName: invite.vaultName,
+      provisionVault: invite.provisionVault,
+    }),
+    200,
+    setCookie,
+  );
+}
+
+/** POST /account/setup/<token> — redeem the invite (see file docstring for ordering). */
+export async function handleAccountSetupPost(
+  req: Request,
+  rawToken: string,
+  deps: AccountSetupDeps,
+): Promise<Response> {
+  const now = (deps.now ?? (() => new Date()))();
+
+  // (1) Look up + validate the invite BEFORE any work.
+  let invite: ReturnType<typeof assertInviteRedeemable>;
+  try {
+    invite = assertInviteRedeemable(deps.db, rawToken, now);
+  } catch (err) {
+    return rejectInvite(err);
+  }
+
+  // CSRF — double-submit, same shape as /account/change-password + /login.
+  const form = await req.formData();
+  const formCsrf = form.get(CSRF_FIELD_NAME);
+  if (!verifyCsrfToken(req, typeof formCsrf === "string" ? formCsrf : null)) {
+    return htmlResponse(
+      renderAdminError({
+        title: "Invalid form submission",
+        message: "The form's CSRF token did not match. Reload the page and try again.",
+      }),
+      400,
+    );
+  }
+
+  // Rate limit — reuse the /login IP bucket so a redeem flood and a login
+  // flood share the same throttle. After CSRF (so a junk cross-site POST
+  // doesn't burn the bucket), before any account/vault work.
+  const clientIp = clientIpFromRequest(req);
+  const gate = checkAndRecord(clientIp, now);
+  if (!gate.allowed) {
+    return htmlResponse(
+      renderAdminError({
+        title: "Too many attempts",
+        message: `Please wait ${gate.retryAfterSeconds ?? 60} seconds and try again.`,
+      }),
+      429,
+    );
+  }
+
+  const username = String(form.get("username") ?? "").trim();
+  const password = String(form.get("password") ?? "");
+  const confirm = String(form.get("password_confirm") ?? "");
+
+  const csrf = ensureCsrfToken(req);
+  const setCookie: Record<string, string> = csrf.setCookie ? { "set-cookie": csrf.setCookie } : {};
+  // Re-render the form with an inline error, preserving what the invitee typed.
+  const rerender = (status: number, message: string, vaultNameEcho?: string): Response =>
+    htmlResponse(
+      renderInviteSetup({
+        token: rawToken,
+        csrfToken: csrf.token,
+        pinnedVaultName: invite.vaultName,
+        provisionVault: invite.provisionVault,
+        username,
+        ...(vaultNameEcho !== undefined ? { vaultName: vaultNameEcho } : {}),
+        errorMessage: message,
+      }),
+      status,
+      setCookie,
+    );
+
+  // (2) Validate credentials with the SAME validators as /api/users.
+  const u = validateUsername(username);
+  if (!u.valid) {
+    return rerender(
+      400,
+      "Username must be 2–32 lowercase letters, digits, _ or - (and not a reserved word).",
+    );
+  }
+  if (password.length > PASSWORD_MAX_LEN) {
+    return rerender(413, `Password must be ≤ ${PASSWORD_MAX_LEN} characters.`);
+  }
+  const p = validatePassword(password);
+  if (!p.valid) {
+    return rerender(400, "Password must be at least 12 characters.");
+  }
+  if (password !== confirm) {
+    return rerender(400, "The two passwords don't match.");
+  }
+  // Case-insensitive uniqueness — same gate as /api/users.
+  if (getUserByUsernameCI(deps.db, username) !== null) {
+    return rerender(409, `The username "${username}" is already taken. Pick another.`);
+  }
+
+  // Resolve the vault name: pinned by the invite, or chosen by the invitee.
+  // The invitee-chosen name goes through the FULL `validateVaultName` (the
+  // same 2–32 + charset + reserved contract vault's init enforces), not just
+  // the charset regex — otherwise a 33–64 char name slips past here and fails
+  // at the vault CLI with a generic provision error.
+  let vaultName: string | null = null;
+  if (invite.provisionVault) {
+    if (invite.vaultName !== null) {
+      vaultName = invite.vaultName;
+    } else {
+      // Unpinned name: the invitee names their own vault. The field is
+      // OPTIONAL (no-JS server-side default) — a blank submission defaults
+      // the vault name to the chosen username. Either way the resolved name
+      // runs through the full validator; a username that isn't a valid vault
+      // name (e.g. too long, disallowed chars) re-renders asking for an
+      // explicit vault name with the validator's error.
+      const submitted = String(form.get("vault_name") ?? "").trim();
+      const chosen = submitted === "" ? username : submitted;
+      const v = validateVaultName(chosen);
+      if (!v.ok) {
+        // Echo the resolved name only if the invitee typed one; a blank
+        // (username-derived) failure shouldn't pre-fill the vault box.
+        return rerender(400, v.error, submitted === "" ? undefined : submitted);
+      }
+      vaultName = v.name;
+    }
+  } else if (invite.vaultName !== null) {
+    // UNSUPPORTED shared-vault case: an account-only invite (provision_vault
+    // =false) that pins an EXISTING vault would assign the new user owner-
+    // admin on a pre-existing vault — a cross-tenant breach, and the owner-
+    // vs-shared role split isn't built. The admin API rejects creating such
+    // an invite (defense in depth); reject here too in case one slipped
+    // through. The legit account-only invite (vaultName === null) is unaffected.
+    return rerender(
+      400,
+      "This invite is not supported (shared-vault invites aren't available yet). Ask your hub operator for a new one.",
+    );
+  }
+
+  // (3) Provision the vault — must FRESHLY CREATE it (see the security
+  // invariant on the `!provisioned.created` check below). Routed through the
+  // SAME createVault path the wizard/SPA use, so the new vault gets the §3
+  // internal-live-mirror default for free. Done BEFORE createUser so a
+  // provisioning failure doesn't leave a vault-less account; the invite is
+  // still unconsumed at this point, so the invitee can retry.
+  if (invite.provisionVault && vaultName !== null) {
+    const provisioned = await provisionVault(vaultName, {
+      issuer: deps.hubOrigin,
+      ...(deps.manifestPath !== undefined ? { manifestPath: deps.manifestPath } : {}),
+      ...(deps.runCommand !== undefined ? { runCommand: deps.runCommand } : {}),
+      ...(invite.defaultMirror !== null ? { defaultMirror: invite.defaultMirror } : {}),
+    });
+    if (!provisioned.ok) {
+      return rerender(
+        provisioned.status === 400 ? 400 : 502,
+        provisioned.status === 400
+          ? provisioned.message
+          : "Could not provision your vault. Please try again, or ask your hub operator.",
+        invite.vaultName === null ? (vaultName ?? undefined) : undefined,
+      );
+    }
+    // SECURITY INVARIANT: an invite redeem may grant access ONLY to a vault
+    // that was FRESHLY CREATED during this redeem. `provisionVault` returns
+    // `created:true` (HTTP 201) for a new vault, `created:false` (HTTP 200)
+    // when the name ALREADY EXISTS — in which case it hands back SOMEONE
+    // ELSE'S vault. Attaching the new user there as owner would be a cross-
+    // tenant breach. Reject any non-created (already-existing) result; the
+    // invitee must choose a different, unused name. This also closes the
+    // concurrent-redeem race on a new name: first redeem 201, second 200 →
+    // second rejected.
+    if (!provisioned.created) {
+      return rerender(
+        409,
+        `A vault named "${vaultName}" already exists. Choose a different name.`,
+        // Echo the typed name only if the invitee chose it explicitly; a
+        // username-derived collision shouldn't pre-fill the vault box.
+        invite.vaultName === null && String(form.get("vault_name") ?? "").trim() !== ""
+          ? vaultName
+          : undefined,
+      );
+    }
+  }
+
+  // (4) Create the user + consume the invite ATOMICALLY — the COMMIT POINT.
+  // The invite is consumed INSIDE createUser's transaction (the `withinTx`
+  // hook), so the two single-use guarantees compose:
+  //
+  //   - Single-use under concurrency: two redeems of one invite both pass
+  //     `assertInviteRedeemable` above, but only one's `consumeInvite` UPDATE
+  //     (`used_at IS NULL AND revoked_at IS NULL`) changes a row. The loser's
+  //     hook throws `InviteUsedError`, which rolls back ITS user insert — no
+  //     orphan account. Exactly one account results.
+  //   - Re-usable on failure: if createUser throws (UNIQUE collision, etc.)
+  //     before the hook, the invite was never touched; if the hook itself
+  //     throws (lost race), the consume + the user insert roll back together.
+  //     Either way nothing commits, so the invite stays re-usable.
+  //
+  // passwordChanged: TRUE (the invitee chose their own password → no force-
+  // change). assignedVaults pins them to exactly their one vault at the
+  // invite's role. allowMulti because the first admin already exists.
+  let userId: string;
+  try {
+    const created = await createUser(deps.db, username, password, {
+      allowMulti: true,
+      passwordChanged: true,
+      assignedVaults: vaultName !== null ? [vaultName] : [],
+      role: invite.role,
+      withinTx: (newUserId) => {
+        if (!consumeInvite(deps.db, invite.tokenHash, newUserId, now)) {
+          // Lost the redeem race (or a concurrent revoke landed). Throw to
+          // roll back this user insert; surfaced as the used/410 path below.
+          throw new InviteUsedError();
+        }
+      },
+    });
+    userId = created.id;
+  } catch (err) {
+    if (err instanceof InviteUsedError) {
+      return rejectInvite(err);
+    }
+    if (err instanceof UsernameTakenError) {
+      return rerender(409, `The username "${username}" is already taken. Pick another.`);
+    }
+    const msg = err instanceof Error ? err.message : String(err);
+    console.warn(`[account-setup] createUser failed for "${username}": ${msg}`);
+    return rerender(500, "Could not create your account. Please try again.");
+  }
+
+  // (6) Sign the invitee in + land them on /account/.
+  const session = createSession(deps.db, { userId });
+  const sessionCookie = buildSessionCookie(session.id, Math.floor(SESSION_TTL_MS / 1000), {
+    secure: isHttpsRequest(req),
+  });
+  return new Response(null, {
+    status: 302,
+    headers: { location: "/account/", "cache-control": "no-store", "set-cookie": sessionCookie },
+  });
+}

package/src/account-usage.ts

@@ -0,0 +1,118 @@
+/**
+ * Per-vault usage fetch for the friend-facing `/account/` home.
+ *
+ * Vault serves `GET /vault/<name>/.parachute/usage` (read-scoped) returning a
+ * footprint report (vault#437):
+ *   { counts: { notes, attachments, links, tags },
+ *     bytes:  { content, db, assets, mirror?, total },
+ *     computedAt, cached }
+ *
+ * The `/account/` GET handler renders one tile per assigned vault; this module
+ * fetches each vault's usage so the tile can show a compact "X notes · Y MB"
+ * stat. The READ scope means the assigned user's OWN authority suffices — we
+ * mint a short-lived `vault:<name>:read` token (the same authority the OAuth
+ * issuer would grant them) and call the vault over loopback.
+ *
+ * Tolerant by design: any failure (vault down, endpoint absent on an older
+ * vault, mint failure, malformed JSON) resolves to `null` so the tile simply
+ * omits the stat rather than breaking the page. Usage is a nice-to-have on a
+ * friend's home, never load-bearing.
+ *
+ * Injectable seams (`fetchImpl`, `signToken`) keep it unit-testable without a
+ * live vault or real signing key.
+ */
+import type { Database } from "bun:sqlite";
+import { signAccessToken } from "./jwt-sign.ts";
+
+/** The subset of vault's usage report the `/account/` tile renders. */
+export interface VaultUsageStat {
+  notes: number;
+  /** Physical footprint bytes (`bytes.total` from the vault report). */
+  totalBytes: number;
+}
+
+/** Short TTL for the read token — it's used immediately for one loopback call. */
+const USAGE_READ_TOKEN_TTL_SECONDS = 60;
+
+export interface FetchVaultUsageDeps {
+  db: Database;
+  /** Hub origin — `iss` of the minted read token. */
+  hubOrigin: string;
+  /** Loopback port the vault backend listens on (from services.json). */
+  vaultPort: number;
+  /** The user minting against their own read authority — `sub` of the token. */
+  userId: string;
+  /** Test seam — `globalThis.fetch` in production. */
+  fetchImpl?: typeof fetch;
+  /** Test seam — defaults to the real `signAccessToken`. */
+  signToken?: typeof signAccessToken;
+  /** Test seam for the clock. */
+  now?: () => Date;
+}
+
+/**
+ * Fetch one vault's usage stat for the friend's tile, or `null` on any failure.
+ *
+ * Mints a `vault:<name>:read` bearer for `userId` (capped to that one vault via
+ * `vaultScope`) and GETs the vault's loopback usage endpoint. Never throws —
+ * the page renders without the stat on any error.
+ */
+export async function fetchVaultUsage(
+  vaultName: string,
+  deps: FetchVaultUsageDeps,
+): Promise<VaultUsageStat | null> {
+  const fetchImpl = deps.fetchImpl ?? fetch;
+  const sign = deps.signToken ?? signAccessToken;
+  try {
+    const scope = `vault:${vaultName}:read`;
+    const minted = await sign(deps.db, {
+      sub: deps.userId,
+      scopes: [scope],
+      audience: `vault.${vaultName}`,
+      clientId: "parachute-account",
+      issuer: deps.hubOrigin,
+      ttlSeconds: USAGE_READ_TOKEN_TTL_SECONDS,
+      vaultScope: [vaultName],
+      ...(deps.now !== undefined ? { now: deps.now } : {}),
+    });
+    const url = `http://127.0.0.1:${deps.vaultPort}/vault/${vaultName}/.parachute/usage`;
+    const res = await fetchImpl(url, {
+      headers: { authorization: `Bearer ${minted.token}`, accept: "application/json" },
+    });
+    if (!res.ok) return null;
+    const body = (await res.json()) as {
+      counts?: { notes?: unknown };
+      bytes?: { total?: unknown };
+    };
+    const notes = body.counts?.notes;
+    const totalBytes = body.bytes?.total;
+    if (typeof notes !== "number" || typeof totalBytes !== "number") return null;
+    return { notes, totalBytes };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Format a usage stat as the compact "X notes · Y MB" string the tile shows.
+ * Bytes render in the largest sensible unit (B / KB / MB / GB) with one
+ * decimal for MB+ and whole numbers below. Notes are pluralized.
+ *
+ * Exported for direct unit testing + reuse by the renderer.
+ */
+export function formatUsageStat(stat: VaultUsageStat): string {
+  const noteLabel = stat.notes === 1 ? "note" : "notes";
+  return `${stat.notes} ${noteLabel} · ${formatBytes(stat.totalBytes)}`;
+}
+
+/** Human-readable byte size — B / KB / MB / GB, one decimal for MB+. */
+export function formatBytes(bytes: number): string {
+  if (!Number.isFinite(bytes) || bytes < 0) return "0 B";
+  if (bytes < 1024) return `${Math.round(bytes)} B`;
+  const kb = bytes / 1024;
+  if (kb < 1024) return `${Math.round(kb)} KB`;
+  const mb = kb / 1024;
+  if (mb < 1024) return `${mb.toFixed(1)} MB`;
+  const gb = mb / 1024;
+  return `${gb.toFixed(1)} GB`;
+}