@openparachute/hub 0.6.3 → 0.6.4-rc.2

package/src/account-home-ui.ts

@@ -128,6 +128,15 @@ export interface RenderAccountHomeOpts {
    * branches, where no token-mint tile is shown.
    */
   mintableVerbs?: Record<string, VaultVerb[]>;
+  /**
+   * Per-vault usage stat (`"X notes · Y MB"`) for each assigned vault tile.
+   * Maps `vaultName` → the pre-formatted stat string. A vault absent from this
+   * map renders no stat — the page tolerates a vault whose usage endpoint
+   * failed / is unreachable / predates the feature (the `/account/` GET handler
+   * builds this map by fetching `/.parachute/usage` per vault and omitting any
+   * that don't resolve). Omitted entirely on the admin / no-vault branches.
+   */
+  usageStats?: Record<string, string>;
   /**
    * Set after a successful `POST /account/vault-token/<name>` to show the
    * freshly-minted token ONCE (the only time it's ever shown — the hub keeps
@@ -189,6 +198,7 @@ export function renderAccountHome(opts: RenderAccountHomeOpts): string {
     isFirstAdmin,
     csrfToken,
     mintableVerbs: opts.mintableVerbs ?? {},
+    usageStats: opts.usageStats ?? {},
   });
 
   const accountCard = renderAccountCard({
@@ -257,6 +267,8 @@ interface VaultCardOpts {
   isFirstAdmin: boolean;
   csrfToken: string;
   mintableVerbs: Record<string, VaultVerb[]>;
+  /** `vaultName` → pre-formatted usage stat ("X notes · Y MB"). */
+  usageStats: Record<string, string>;
 }
 
 /**
@@ -286,7 +298,8 @@ export function accountClaudeMcpAddCommand(trimmedOrigin: string, vaultName: str
 }
 
 function renderVaultCard(opts: VaultCardOpts): string {
-  const { assignedVaults, trimmedOrigin, isFirstAdmin, csrfToken, mintableVerbs } = opts;
+  const { assignedVaults, trimmedOrigin, isFirstAdmin, csrfToken, mintableVerbs, usageStats } =
+    opts;
 
   if (assignedVaults.length > 0) {
     // One vault tile per assignment (multi-user Phase 2 PR 2). Each tile
@@ -313,15 +326,25 @@ function renderVaultCard(opts: VaultCardOpts): string {
         const addCmd = accountClaudeMcpAddCommand(trimmedOrigin, vaultName);
         const safeEndpoint = escapeHtml(endpoint);
         const safeAddCmd = escapeHtml(addCmd);
-        const tokenMintBlock = renderTokenMintBlock(
-          vaultName,
-          safeVault,
-          mintableVerbs[vaultName] ?? [],
-          csrfToken,
-        );
+        const verbsForVault = mintableVerbs[vaultName] ?? [];
+        const tokenMintBlock = renderTokenMintBlock(vaultName, safeVault, verbsForVault, csrfToken);
+        // "Configure / back up this vault ↗" — only for users whose assignment
+        // grants `admin` (the verb the deep-link mints). Today every assigned
+        // user holds admin, but gate on the verb so the button never offers
+        // authority the POST handler would 403.
+        const manageBlock = verbsForVault.includes("admin")
+          ? renderVaultAdminLink(vaultName, csrfToken)
+          : "";
+        // Compact usage stat ("X notes · Y MB"), when the vault's usage endpoint
+        // resolved. Omitted gracefully otherwise.
+        const usageStat = usageStats[vaultName];
+        const usageLine = usageStat
+          ? `<p class="vault-usage" data-testid="vault-usage">${escapeHtml(usageStat)}</p>`
+          : "";
         return `
         <div class="vault-tile" data-testid="vault-tile" data-vault-name="${safeVault}">
           <p class="vault-name"><strong>${safeVault}</strong></p>
+          ${usageLine}
           <div class="mcp-connect" data-testid="mcp-connect">
             <p class="mcp-connect-label" data-testid="connect-ai-heading">Connect your AI
                assistant to this vault</p>
@@ -364,6 +387,7 @@ function renderVaultCard(opts: VaultCardOpts): string {
                capture in this vault — or jump straight to bulk-importing Markdown/Obsidian
                notes into it.</span>
           </p>
+          ${manageBlock}
           ${tokenMintBlock}
         </div>`;
       })
@@ -473,6 +497,34 @@ function renderTokenMintBlock(
           </details>`;
 }
 
+/**
+ * The "Configure / back up this vault ↗" affordance on a vault tile. A small
+ * POST form to `/account/vault-admin-token/<name>` that mints a
+ * `vault:<name>:admin` deep-link token and redirects into the vault's own admin
+ * SPA — where the assigned user can rotate vault tokens AND set up Git backup /
+ * mirror config. Shown only when the user's assignment grants `admin` (gated by
+ * the caller). A plain form button (no `<details>`) — this is a primary admin
+ * action for an individual user, more prominent than the headless-token mint
+ * below it.
+ *
+ * No-JS posture: a same-origin form POST that 303-redirects on success, same
+ * shape as the other `/account/*` forms. CSRF-gated via the hidden field.
+ */
+function renderVaultAdminLink(vaultName: string, csrfToken: string): string {
+  // Path segment is URL-encoded; the action attribute is HTML-escaped on top.
+  const action = escapeHtml(`/account/vault-admin-token/${encodeURIComponent(vaultName)}`);
+  return `
+          <form method="POST" action="${action}" class="vault-admin-link"
+                data-testid="vault-admin-form">
+            ${renderCsrfHiddenInput(csrfToken)}
+            <button type="submit" class="btn btn-secondary" data-testid="vault-admin-button">
+              Configure / back up this vault ↗
+            </button>
+            <span class="vault-admin-sub">Open this vault's admin tools — rotate access tokens,
+               and set up Git backup (mirror to a repository).</span>
+          </form>`;
+}
+
 /**
  * The show-once banner for a freshly-minted friend vault token. Rendered at
  * the top of `/account/` after a successful `POST /account/vault-token/<name>`.
@@ -717,6 +769,11 @@ const STYLES = `
     margin: 0 0 0.6rem;
   }
   .vault-name strong { color: ${PALETTE.fg}; font-weight: 600; }
+  .vault-usage {
+    font-size: 0.8rem;
+    color: ${PALETTE.fgMuted};
+    margin: 0 0 0.5rem;
+  }
   .vault-tiles {
     display: flex;
     flex-direction: column;
@@ -824,6 +881,21 @@ const STYLES = `
     margin: 0.4rem 0 0;
   }
 
+  .vault-admin-link {
+    margin: 0.9rem 0 0;
+    padding-top: 0.6rem;
+    border-top: 1px solid ${PALETTE.borderLight};
+    display: flex;
+    align-items: center;
+    flex-wrap: wrap;
+    gap: 0.4rem 0.75rem;
+  }
+  .vault-admin-sub {
+    font-size: 0.82rem;
+    color: ${PALETTE.fgMuted};
+    flex: 1 1 12rem;
+  }
+
   .token-mint {
     margin: 0.9rem 0 0;
     padding-top: 0.6rem;
@@ -981,13 +1053,14 @@ const STYLES = `
     h1, h2 { color: #f0ece4; }
     .subtitle, .kv dt, .mcp-field-label, .mcp-connect-hint,
     .mcp-connect-intro, .mcp-method-sub, .mcp-method-note,
-    .vault-notes-cta-sub { color: #a8a29a; }
+    .vault-notes-cta-sub, .vault-usage { color: #a8a29a; }
     .vault-name strong, .mcp-connect-label, .mcp-method-title { color: #f0ece4; }
     code { background: #1f1c18; color: #e8e4dc; }
     .copy-row code { background: transparent; }
     .section { border-top-color: #3a362f; }
     .mcp-method, .vault-notes-cta, .token-mint,
-    .account-security { border-top-color: #3a362f; }
+    .vault-admin-link, .account-security { border-top-color: #3a362f; }
+    .vault-admin-sub { color: #a8a29a; }
     .get-started h3 { color: #f0ece4; }
     .starter-tile { border-color: #3a362f; background: #1f1c18; }
     .starter-tile:hover { border-color: ${PALETTE.accent}; }

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`;
+}