@openparachute/hub 0.6.3 → 0.6.4-rc.1

package/src/api-account.ts

@@ -49,6 +49,7 @@ import type { Database } from "bun:sqlite";
 import { hash as argonHash } from "@node-rs/argon2";
 import { type ChangePasswordMode, renderChangePassword } from "./account-change-password-ui.ts";
 import { renderAccountHome } from "./account-home-ui.ts";
+import { fetchVaultUsage, formatUsageStat } from "./account-usage.ts";
 import { POST_LOGIN_DEFAULT } from "./admin-handlers.ts";
 import { renderAdminError } from "./admin-login-ui.ts";
 import { CSRF_FIELD_NAME, ensureCsrfToken, verifyCsrfToken } from "./csrf.ts";
@@ -419,6 +420,16 @@ export async function handleAccountChangePasswordPost(
         )
         .run(passwordHash, stamp, user.id);
       if (result.changes === 0) throw new UserNotFoundError(user.id);
+      // Revoke the user's still-active tokens on a self-service password change
+      // (item F / hub#469). The admin-reset path already revokes
+      // (`resetUserPassword`, users.ts); applying the same on self-change closes
+      // the "mint a token under the admin's temp password, then rotate but keep
+      // the token" gap — any token minted before the rotation dies with it. The
+      // user re-mints under their own (now-rotated) password if they need one.
+      // Same transaction as the hash write so the two are atomic.
+      deps.db
+        .prepare("UPDATE tokens SET revoked_at = ? WHERE user_id = ? AND revoked_at IS NULL")
+        .run(stamp, user.id);
     })();
   } catch (err) {
     // The user row vanished between the session-resolve check above and
@@ -476,9 +487,24 @@ export async function handleAccountChangePasswordPost(
 export interface AccountHomeDeps extends ApiAccountDeps {
   /** Canonical hub origin for this request (e.g. `https://my-hub.example`). */
   hubOrigin: string;
+  /**
+   * Resolve a vault's loopback port from services.json, or `null` when no vault
+   * is mounted under that name. Threaded in by the route handler (which reads
+   * the manifest) so this module stays free of services.json plumbing. Absent
+   * in tests / older callers → usage surfacing is skipped (tiles render without
+   * the stat, same as a failed fetch).
+   */
+  resolveVaultPort?: (vaultName: string) => number | null;
+  /**
+   * Fetch one vault's usage stat, or `null` on any failure. Defaults to the
+   * real `fetchVaultUsage` (mints a read token + hits the vault's loopback
+   * usage endpoint). Injectable so tests assert the render without a live
+   * vault.
+   */
+  fetchUsage?: typeof fetchVaultUsage;
 }
 
-export function handleAccountHomeGet(req: Request, deps: AccountHomeDeps): Response {
+export async function handleAccountHomeGet(req: Request, deps: AccountHomeDeps): Promise<Response> {
   const session = findActiveSession(deps.db, req);
   if (!session) {
     return redirect(`/login?next=${encodeURIComponent("/account/")}`);
@@ -501,6 +527,32 @@ export function handleAccountHomeGet(req: Request, deps: AccountHomeDeps): Respo
     const verbs = vaultVerbsForUserVault(deps.db, user.id, v);
     if (verbs && verbs.length > 0) mintableVerbs[v] = verbs;
   }
+
+  // Per-vault usage stat ("X notes · Y MB"). Fetched concurrently across the
+  // user's assigned vaults via the read-scoped vault endpoint; each fetch is
+  // independently fault-tolerant (returns null → that tile renders without a
+  // stat). Skipped entirely when the route didn't wire a port resolver (tests /
+  // older callers). The READ scope means the user's own authority suffices.
+  const usageStats: Record<string, string> = {};
+  if (deps.resolveVaultPort && user.assignedVaults.length > 0) {
+    const fetchUsage = deps.fetchUsage ?? fetchVaultUsage;
+    const resolvePort = deps.resolveVaultPort;
+    await Promise.all(
+      user.assignedVaults.map(async (vaultName) => {
+        const port = resolvePort(vaultName);
+        if (port === null) return;
+        const stat = await fetchUsage(vaultName, {
+          db: deps.db,
+          hubOrigin: deps.hubOrigin,
+          vaultPort: port,
+          userId: user.id,
+          ...(deps.now !== undefined ? { now: deps.now } : {}),
+        });
+        if (stat) usageStats[vaultName] = formatUsageStat(stat);
+      }),
+    );
+  }
+
   return htmlResponse(
     renderAccountHome({
       username: user.username,
@@ -511,6 +563,7 @@ export function handleAccountHomeGet(req: Request, deps: AccountHomeDeps): Respo
       csrfToken: csrf.token,
       twoFactorEnabled: isTotpEnrolled(deps.db, user.id),
       mintableVerbs,
+      usageStats,
     }),
     200,
     extra,

package/src/api-invites.ts

@@ -0,0 +1,347 @@
+/**
+ * `/api/invites*` — admin endpoints for one-time invite links (design
+ * 2026-06-04-individual-users-and-vault-operations.md §7).
+ *
+ *   POST   /api/invites        create an invite → { invite, url } (host:admin)
+ *                              The `url` carries the raw token and is the ONLY
+ *                              time it's retrievable — the hub stores only its
+ *                              sha256.
+ *   GET    /api/invites        list invites with derived status (host:admin)
+ *   DELETE /api/invites/:id     revoke a pending invite by sha256 hash (host:admin)
+ *
+ * Auth: every endpoint requires a bearer carrying `parachute:host:admin` —
+ * the same gate as `/api/users` and `/vaults`. The SPA mints one via
+ * `/admin/host-admin-token` from the session cookie.
+ *
+ * Wire shape is snake_case (matches `/api/users`). An invite's raw token
+ * NEVER appears in a GET/list response — only in the POST-create `url`.
+ */
+import type { Database } from "bun:sqlite";
+import { type AdminAuthError, adminAuthErrorResponse, requireScope } from "./admin-auth.ts";
+import { HOST_ADMIN_SCOPE } from "./admin-vaults.ts";
+import { SERVICES_MANIFEST_PATH } from "./config.ts";
+import {
+  DEFAULT_INVITE_TTL_SECONDS,
+  type Invite,
+  type InviteStatus,
+  findInviteByHash,
+  inviteStatus,
+  issueInvite,
+  listInvites,
+  revokeInvite,
+} from "./invites.ts";
+import { VAULT_NAME_CHARSET_RE } from "./vault-name.ts";
+import { listVaultNamesFromPath } from "./vault-names.ts";
+
+export interface ApiInvitesDeps {
+  db: Database;
+  /** Hub origin — JWT `iss` validation AND the base for the redemption URL. */
+  issuer: string;
+  manifestPath?: string;
+  now?: () => Date;
+}
+
+/** Roles an invite may grant. `'write'` = owner (full vault admin); `'read'` = read-only (shared). */
+const ALLOWED_ROLES = new Set(["read", "write"]);
+/** Cap an invite TTL so a typo can't mint a ~forever link. 90 days. */
+const MAX_INVITE_TTL_SECONDS = 90 * 24 * 60 * 60;
+
+interface InviteWireShape {
+  /** sha256 hash — the stable id for list/revoke. NOT the raw token. */
+  id: string;
+  status: InviteStatus;
+  vault_name: string | null;
+  role: string;
+  provision_vault: boolean;
+  default_mirror: string | null;
+  expires_at: string;
+  used_at: string | null;
+  redeemed_user_id: string | null;
+  revoked_at: string | null;
+  created_at: string;
+}
+
+function toWire(invite: Invite, status: InviteStatus): InviteWireShape {
+  return {
+    id: invite.tokenHash,
+    status,
+    vault_name: invite.vaultName,
+    role: invite.role,
+    provision_vault: invite.provisionVault,
+    default_mirror: invite.defaultMirror,
+    expires_at: invite.expiresAt,
+    used_at: invite.usedAt,
+    redeemed_user_id: invite.redeemedUserId,
+    revoked_at: invite.revokedAt,
+    created_at: invite.createdAt,
+  };
+}
+
+function jsonError(status: number, error: string, description: string): Response {
+  return new Response(JSON.stringify({ error, error_description: description }), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+function redeemUrl(issuer: string, rawToken: string): string {
+  const base = issuer.replace(/\/$/, "");
+  return `${base}/account/setup/${rawToken}`;
+}
+
+interface CreateInviteBody {
+  vaultName: string | null;
+  role: string;
+  provisionVault: boolean;
+  defaultMirror: string | null;
+  expiresInSeconds: number;
+}
+
+interface ParseErr {
+  ok: false;
+  status: number;
+  error: string;
+  description: string;
+}
+
+async function parseCreateBody(
+  req: Request,
+): Promise<{ ok: true; body: CreateInviteBody } | ParseErr> {
+  const ctype = req.headers.get("content-type") ?? "";
+  // Allow an empty body — every field has a default. Only enforce JSON when
+  // a body is actually present.
+  let raw: unknown = {};
+  if (ctype.toLowerCase().includes("application/json")) {
+    try {
+      const text = await req.text();
+      raw = text.trim() === "" ? {} : JSON.parse(text);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return {
+        ok: false,
+        status: 400,
+        error: "invalid_request",
+        description: `invalid JSON body: ${msg}`,
+      };
+    }
+  }
+  if (!raw || typeof raw !== "object") {
+    return {
+      ok: false,
+      status: 400,
+      error: "invalid_request",
+      description: "request body must be a JSON object",
+    };
+  }
+  const obj = raw as Record<string, unknown>;
+
+  // vault_name — optional. null/omitted = redeemer names their own vault.
+  let vaultName: string | null = null;
+  const rawVault =
+    Object.hasOwn(obj, "vault_name") && obj.vault_name !== undefined
+      ? obj.vault_name
+      : Object.hasOwn(obj, "vaultName") && obj.vaultName !== undefined
+        ? obj.vaultName
+        : undefined;
+  if (rawVault !== undefined && rawVault !== null) {
+    if (typeof rawVault !== "string" || rawVault.length === 0) {
+      return {
+        ok: false,
+        status: 400,
+        error: "invalid_request",
+        description: '"vault_name" must be a non-empty string or null',
+      };
+    }
+    if (!VAULT_NAME_CHARSET_RE.test(rawVault)) {
+      return {
+        ok: false,
+        status: 400,
+        error: "invalid_request",
+        description:
+          "vault name must contain only lowercase letters, numbers, hyphens, and underscores",
+      };
+    }
+    vaultName = rawVault;
+  }
+
+  // role — default 'write' (owner).
+  let role = "write";
+  const rawRole = obj.role;
+  if (rawRole !== undefined && rawRole !== null) {
+    if (typeof rawRole !== "string" || !ALLOWED_ROLES.has(rawRole)) {
+      return {
+        ok: false,
+        status: 400,
+        error: "invalid_request",
+        description: '"role" must be "read" or "write"',
+      };
+    }
+    role = rawRole;
+  }
+
+  // provision_vault — default true (the primary flow).
+  let provisionVault = true;
+  const rawProvision =
+    Object.hasOwn(obj, "provision_vault") && obj.provision_vault !== undefined
+      ? obj.provision_vault
+      : Object.hasOwn(obj, "provisionVault") && obj.provisionVault !== undefined
+        ? obj.provisionVault
+        : undefined;
+  if (rawProvision !== undefined) {
+    if (typeof rawProvision !== "boolean") {
+      return {
+        ok: false,
+        status: 400,
+        error: "invalid_request",
+        description: '"provision_vault" must be a boolean',
+      };
+    }
+    provisionVault = rawProvision;
+  }
+
+  // default_mirror — optional 'internal' | 'off'.
+  let defaultMirror: string | null = null;
+  const rawMirror =
+    Object.hasOwn(obj, "default_mirror") && obj.default_mirror !== undefined
+      ? obj.default_mirror
+      : Object.hasOwn(obj, "defaultMirror") && obj.defaultMirror !== undefined
+        ? obj.defaultMirror
+        : undefined;
+  if (rawMirror !== undefined && rawMirror !== null) {
+    if (rawMirror !== "internal" && rawMirror !== "off") {
+      return {
+        ok: false,
+        status: 400,
+        error: "invalid_request",
+        description: '"default_mirror" must be "internal" or "off"',
+      };
+    }
+    defaultMirror = rawMirror;
+  }
+
+  // expires_in — seconds; default 7 days; capped at 90 days.
+  let expiresInSeconds = DEFAULT_INVITE_TTL_SECONDS;
+  const rawExpiry =
+    Object.hasOwn(obj, "expires_in") && obj.expires_in !== undefined
+      ? obj.expires_in
+      : Object.hasOwn(obj, "expiresIn") && obj.expiresIn !== undefined
+        ? obj.expiresIn
+        : undefined;
+  if (rawExpiry !== undefined && rawExpiry !== null) {
+    if (typeof rawExpiry !== "number" || !Number.isFinite(rawExpiry) || rawExpiry <= 0) {
+      return {
+        ok: false,
+        status: 400,
+        error: "invalid_request",
+        description: '"expires_in" must be a positive number of seconds',
+      };
+    }
+    if (rawExpiry > MAX_INVITE_TTL_SECONDS) {
+      return {
+        ok: false,
+        status: 400,
+        error: "invalid_request",
+        description: `"expires_in" must be ≤ ${MAX_INVITE_TTL_SECONDS} seconds (90 days)`,
+      };
+    }
+    expiresInSeconds = Math.floor(rawExpiry);
+  }
+
+  return { ok: true, body: { vaultName, role, provisionVault, defaultMirror, expiresInSeconds } };
+}
+
+/** POST /api/invites — create an invite, return the single-emit URL + token. */
+export async function handleCreateInvite(req: Request, deps: ApiInvitesDeps): Promise<Response> {
+  if (req.method !== "POST") return jsonError(405, "method_not_allowed", "use POST");
+  let authUserId: string;
+  try {
+    // `requireScope` returns the validated claims; the admin's `sub` is the
+    // `created_by` audit anchor (guaranteed present — it throws otherwise).
+    const auth = await requireScope(deps.db, req, HOST_ADMIN_SCOPE, deps.issuer);
+    authUserId = auth.sub;
+  } catch (err) {
+    return adminAuthErrorResponse(err as AdminAuthError);
+  }
+  const parsed = await parseCreateBody(req);
+  if (!parsed.ok) return jsonError(parsed.status, parsed.error, parsed.description);
+  const { vaultName, role, provisionVault, defaultMirror, expiresInSeconds } = parsed.body;
+
+  // A pinned vault_name with provision_vault=false means "assign an existing
+  // vault" — validate it exists. (provision_vault=true with a pinned name
+  // provisions THAT name; provision_vault=false without a name is account-only.)
+  if (vaultName !== null && !provisionVault) {
+    const manifestPath = deps.manifestPath ?? SERVICES_MANIFEST_PATH;
+    const known = new Set(listVaultNamesFromPath(manifestPath));
+    if (!known.has(vaultName)) {
+      return jsonError(
+        400,
+        "vault_not_found",
+        `vault "${vaultName}" is not registered in services.json`,
+      );
+    }
+  }
+
+  const issued = issueInvite(deps.db, {
+    createdBy: authUserId,
+    vaultName,
+    role,
+    provisionVault,
+    defaultMirror,
+    expiresInSeconds,
+    ...(deps.now !== undefined ? { now: deps.now } : {}),
+  });
+  const status = inviteStatus(issued.invite, (deps.now ?? (() => new Date()))());
+  return new Response(
+    JSON.stringify({
+      invite: toWire(issued.invite, status),
+      // Single-emit: the raw token only ever appears here.
+      token: issued.rawToken,
+      url: redeemUrl(deps.issuer, issued.rawToken),
+    }),
+    { status: 201, headers: { "content-type": "application/json", "cache-control": "no-store" } },
+  );
+}
+
+/** GET /api/invites — list invites, newest first, status-annotated. */
+export async function handleListInvites(req: Request, deps: ApiInvitesDeps): Promise<Response> {
+  if (req.method !== "GET") return jsonError(405, "method_not_allowed", "use GET");
+  try {
+    await requireScope(deps.db, req, HOST_ADMIN_SCOPE, deps.issuer);
+  } catch (err) {
+    return adminAuthErrorResponse(err as AdminAuthError);
+  }
+  const now = (deps.now ?? (() => new Date()))();
+  const invites = listInvites(deps.db, now).map((i) => toWire(i, i.status));
+  return new Response(JSON.stringify({ invites }), {
+    status: 200,
+    headers: { "content-type": "application/json", "cache-control": "no-store" },
+  });
+}
+
+/** DELETE /api/invites/:id — revoke a pending invite by its sha256 hash. */
+export async function handleRevokeInvite(
+  req: Request,
+  id: string,
+  deps: ApiInvitesDeps,
+): Promise<Response> {
+  if (req.method !== "DELETE") return jsonError(405, "method_not_allowed", "use DELETE");
+  try {
+    await requireScope(deps.db, req, HOST_ADMIN_SCOPE, deps.issuer);
+  } catch (err) {
+    return adminAuthErrorResponse(err as AdminAuthError);
+  }
+  const existing = findInviteByHash(deps.db, id);
+  if (!existing) return jsonError(404, "not_found", `no invite with id "${id}"`);
+  const now = (deps.now ?? (() => new Date()))();
+  const revoked = revokeInvite(deps.db, id, now);
+  if (!revoked) {
+    // Already redeemed or revoked — nothing to do, but report the terminal
+    // state so the SPA can refresh rather than silently swallowing.
+    const status = inviteStatus(existing, now);
+    return jsonError(409, "invite_not_pending", `invite is already ${status}`);
+  }
+  return new Response(JSON.stringify({ ok: true }), {
+    status: 200,
+    headers: { "content-type": "application/json", "cache-control": "no-store" },
+  });
+}

package/src/api-mint-token.ts

@@ -52,6 +52,7 @@ import {
   MINT_HOST_AUTH_SCOPE,
   canGrant,
   hasMintingAuthority,
+  isOperatorBearer,
 } from "./scope-attenuation.ts";
 import {
   isVaultAdminScope,
@@ -86,6 +87,21 @@ export interface ApiMintTokenDeps {
   db: Database;
   /** Hub origin — written into the JWT `iss` of minted tokens AND used to validate the bearer. */
   issuer: string;
+  /**
+   * Names of vault instances currently registered in services.json (item D /
+   * hub#450). When provided, a `vault:<name>:admin` mint whose `<name>` is not
+   * in this set is rejected with 400 — a typo'd name can no longer mint
+   * `vault:typo:admin` (an unusable token that authenticates against no real
+   * vault, only confusing automation that's debugging a typo). Mirrors the
+   * session-cookie path (`/admin/vault-admin-token/<name>`), which already
+   * 404s unknown vault names via `knownVaultNames.has`.
+   *
+   * Optional: when undefined the existence check is skipped (the documented
+   * "caller is responsible for a real vault name" fallback, and the shape used
+   * by unit tests that don't wire a manifest). Production wires it from
+   * services.json in hub-server.ts.
+   */
+  knownVaultNames?: ReadonlySet<string>;
   /** Test seam for time. */
   now?: () => Date;
 }
@@ -188,6 +204,56 @@ export async function handleApiMintToken(req: Request, deps: ApiMintTokenDeps):
     );
   }
 
+  // Item B / hub#451 — bare (unnamed) `vault:admin` is non-requestable on the
+  // HEADLESS mint path. The unnamed `vault:admin` form is a broad full-vault
+  // admin grant with no resource pin (`aud=vault`, `vault_scope=[]`); minting
+  // it via a host:auth bearer here would issue a surprising un-narrowed admin
+  // credential. Vault rejects broad `vault:admin` on hub-JWTs anyway (it forces
+  // resource-narrowing — `parachute-vault/src/auth.ts:428`), so the practical
+  // blast radius is low, but a headless caller should never be handed it.
+  //
+  // This is mint-side, NOT in the OAuth-shared `NON_REQUESTABLE_SCOPES`, on
+  // purpose: the public `/oauth/authorize` flow legitimately accepts an unnamed
+  // `vault:admin` and NARROWS it to `vault:<picked>:admin` via the vault picker
+  // (oauth-handlers.ts `narrowVaultScopes`) before any token is minted. Adding
+  // it to `NON_REQUESTABLE_SCOPES` would reject that narrowing flow (the
+  // requestability gate fires on the raw, pre-narrow scopes). Named
+  // `vault:<name>:admin` — the post-narrow form — stays mintable. `vault:read`
+  // / `vault:write` unnamed are unaffected (they carry no admin authority).
+  const bareVaultAdmin = scopes.filter((s) => s === "vault:admin");
+  if (bareVaultAdmin.length > 0) {
+    return jsonError(
+      400,
+      "invalid_scope",
+      "bare vault:admin is not mintable headlessly; request a resource-narrowed vault:<name>:admin instead",
+    );
+  }
+
+  // Item D / hub#450 — vault-existence check for `vault:<name>:admin` mints.
+  // The session-cookie path (`/admin/vault-admin-token/<name>`) already 404s an
+  // unknown vault name; this mirrors it for the bearer path so a typo can't mint
+  // `vault:typo:admin` — an unusable token (it authenticates against no real
+  // vault) that only confuses automation debugging a typo. Gated on `<name>:admin`
+  // (the one form #450 calls out); read/write are left alone (even more harmless,
+  // and the broad-requestable path). Skipped entirely when `knownVaultNames` is
+  // absent (the documented "caller responsible" fallback + unit-test shape).
+  if (deps.knownVaultNames !== undefined) {
+    const unknownAdminVaults = scopes.filter((s) => {
+      if (!isVaultAdminScope(s)) return false;
+      const name = vaultScopeName(s);
+      return name !== null && !deps.knownVaultNames!.has(name);
+    });
+    if (unknownAdminVaults.length > 0) {
+      return jsonError(
+        400,
+        "invalid_scope",
+        `no vault named ${unknownAdminVaults
+          .map((s) => `"${vaultScopeName(s)}"`)
+          .join(", ")} in this hub; create the vault before minting an admin token for it`,
+      );
+    }
+  }
+
   // Capability-attenuation guard: every requested scope must be a subset of
   // the bearer's own authority under `canGrant` (rules in the file docstring).
   // A `parachute:host:auth` bearer mints any requestable scope; a
@@ -235,6 +301,21 @@ export async function handleApiMintToken(req: Request, deps: ApiMintTokenDeps):
   if (body.subject === undefined) {
     subject = bearerSub;
   } else if (typeof body.subject === "string" && body.subject.length > 0) {
+    // Subject override is an OPERATOR-only capability (audit-attribution
+    // forgery otherwise). A host operator (`parachute:host:auth` /
+    // `parachute:host:admin`) may stamp a service-account `sub` other than its
+    // own — the documented service-account override. A merely vault-scoped
+    // bearer (`vault:<N>:admin` only, no host authority) has no business
+    // forging the minted token's subject: it would let a vault admin mint a
+    // token the registry + revocation list attribute to a foreign subject. So
+    // a non-operator bearer may only mint tokens carrying its OWN `sub`.
+    if (!isOperatorBearer(bearerScopes) && body.subject !== bearerSub) {
+      return jsonError(
+        403,
+        "insufficient_scope",
+        "non-operator bearers may not override subject; omit `subject` to mint under your own identity",
+      );
+    }
     subject = body.subject;
   } else {
     return jsonError(400, "invalid_request", "subject must be a non-empty string when present");