@openparachute/hub 0.6.3 → 0.6.4-rc.10

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

@@ -0,0 +1,242 @@
+/**
+ * `POST /account/vault-admin-token/<name>` — friend-facing vault ADMIN deep-link.
+ *
+ * The non-admin sibling of `GET /admin/vault-admin-token/<name>`
+ * (`admin-vault-admin-token.ts`). Both mint a `vault:<name>:admin` JWT and
+ * hand it to the vault's own admin SPA via a `#token=<jwt>` URL fragment — the
+ * SPA reads `location.hash` on bootstrap, then strips it. The admin sibling is
+ * gated `isFirstAdmin` and returns JSON for the hub SPA's fetch; THIS surface
+ * is gated on ASSIGNMENT (an individual user holds `admin` on a vault they're
+ * assigned to) and is a server-rendered POST → 303 redirect, matching the
+ * no-JS posture of the rest of `/account/*`.
+ *
+ * Why this exists: an assigned user is ALREADY authorized for `vault:<name>:admin`
+ * (`vaultVerbsForUserVault` returns `["read","write","admin"]` for their vault,
+ * 2026-05-30; vault gates mirror/backup config + token rotation on that scope).
+ * The authority existed; the only missing piece was a friend-reachable HTTP
+ * unlock + a button. With this, an individual user can open their vault's admin
+ * SPA — token mint/revoke, **and the Git-backup / mirror config** — without
+ * host-admin. The deep-link lands on the vault admin home (`managementUrl`,
+ * `/admin/` by default), whose "Git backup →" link reaches `VaultMirror`.
+ *
+ * Authorization — the same three-gate spine as `/account/vault-token/<name>`
+ * (`account-vault-token.ts`), here pinned to the single `admin` verb:
+ *
+ *   1. **Session.** A valid hub session cookie (the user's). No session → 401.
+ *   2. **Assignment.** `<name>` MUST be one of the user's `user_vaults`
+ *      assignments AND that assignment's role must grant `admin`. Read via
+ *      `vaultVerbsForUserVault` (`null` for an unassigned vault → 403; a role
+ *      that doesn't grant `admin` → 403). The first admin (empty
+ *      `assignedVaults`, no `user_vaults` rows) gets `null` here too — by
+ *      design, the same as `/account/vault-token`: admins use the SPA's
+ *      `/admin/vault-admin-token` path, not this friend surface.
+ *
+ * CSRF: double-submit cookie, same `__csrf` field + `verifyCsrfToken` as
+ * `/account/vault-token`, `/account/change-password`, and `/logout`. A
+ * cross-site POST without the matching cookie/form token → 400.
+ *
+ * Force-change-password gate (item F / hub#469): if `!user.passwordChanged`,
+ * 303 → `/account/change-password` BEFORE minting — identical to the gate
+ * `/account/vault-token` applies post-#550. An admin-created/reset user lands
+ * with a temp password and `password_changed: false`; without this gate they
+ * could mint a `vault:<name>:admin` deep-link token (10-min TTL, but still) and
+ * keep using the temp password instead of rotating it. Placed AFTER the
+ * authority gates (so an unassigned/garbage request still gets its 403/400) and
+ * BEFORE the mint. This does NOT reintroduce the bypass #469 closed.
+ *
+ * Mint: `signAccessToken` (the same machinery the OAuth issuer + admin paths
+ * use) with `scopes: ["vault:<name>:admin"]`, `audience: "vault.<name>"`,
+ * `iss`: the hub origin, `sub`: the user id, `vaultScope: [<name>]`, and the
+ * SAME short 10-min TTL as the admin sibling (`VAULT_ADMIN_TOKEN_TTL_SECONDS`):
+ * this is a deep-link bootstrap token, not a long-lived headless credential
+ * (that's `/account/vault-token`). A `tokens` registry row records it
+ * (`created_via='cli_mint'`, `userId` = the user) so it's revocable.
+ *
+ * Response: 303 → `<vault-url><managementUrl>#token=<jwt>`. 303 (See Other) so
+ * the browser re-issues the navigation as GET. The token rides the URL
+ * fragment, which is never sent to the server — same contract the hub SPA's
+ * `VaultsList` "Manage" button uses (vault PR #219).
+ */
+import type { Database } from "bun:sqlite";
+import { renderAdminError } from "./admin-login-ui.ts";
+import { VAULT_ADMIN_TOKEN_TTL_SECONDS } from "./admin-vault-admin-token.ts";
+import { CSRF_FIELD_NAME, verifyCsrfToken } from "./csrf.ts";
+import { recordTokenMint, signAccessToken } from "./jwt-sign.ts";
+import { findActiveSession } from "./sessions.ts";
+import { getUserById, vaultVerbsForUserVault } from "./users.ts";
+import { VAULT_NAME_CHARSET_RE } from "./vault-name.ts";
+
+/** Lowercase-only vault-name charset — single source of truth in vault-name.ts. */
+const VAULT_NAME_RE = VAULT_NAME_CHARSET_RE;
+/** client_id stamped on the minted JWT + registry row. Matches the admin sibling. */
+const ACCOUNT_VAULT_ADMIN_CLIENT_ID = "parachute-hub-spa";
+
+export interface AccountVaultAdminTokenDeps {
+  db: Database;
+  /** Hub origin for this request — `iss` of the minted token + base of the redirect URL. */
+  hubOrigin: string;
+  /**
+   * The vault's declared `managementUrl` (from its `.parachute/module.json`),
+   * resolved by the route handler at request time. Either an absolute URL or a
+   * path relative to the vault's mounted URL. Defaults to `/admin/` (vault's
+   * canonical value) when the handler can't resolve one — that's where the
+   * admin sibling's deep-link lands too.
+   */
+  managementUrl?: string;
+  /** Test seam for the clock (mint). */
+  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 },
+  });
+}
+
+/**
+ * Resolve a vault's `managementUrl` against the vault's hub-mounted URL.
+ * Absolute URL → returned verbatim; path → joined onto the vault URL after
+ * trimming a trailing slash. Mirrors `resolveManagementUrl` in the SPA's
+ * `web/ui/src/lib/api.ts` so hub-server and SPA deep-links agree.
+ */
+function resolveManagementUrl(vaultUrl: string, managementUrl: string): string {
+  if (/^https?:\/\//i.test(managementUrl)) return managementUrl;
+  const base = vaultUrl.replace(/\/+$/, "");
+  const tail = managementUrl.startsWith("/") ? managementUrl : `/${managementUrl}`;
+  return `${base}${tail}`;
+}
+
+export async function handleAccountVaultAdminTokenPost(
+  req: Request,
+  vaultName: string,
+  deps: AccountVaultAdminTokenDeps,
+): Promise<Response> {
+  if (req.method !== "POST") {
+    return htmlResponse("method not allowed", 405);
+  }
+
+  // Gate 1 — session. No identity, no mint.
+  const session = findActiveSession(deps.db, req);
+  if (!session) {
+    return htmlResponse(
+      renderAdminError({
+        title: "Not signed in",
+        message: "Please sign in before opening your vault's admin tools.",
+      }),
+      401,
+    );
+  }
+  const user = getUserById(deps.db, session.userId);
+  if (!user) {
+    return htmlResponse(
+      renderAdminError({
+        title: "Account not found",
+        message: "The signed-in account no longer exists. Please sign in again.",
+      }),
+      401,
+    );
+  }
+
+  // CSRF — verify before any state change, same shape + 400 as the other
+  // `/account/*` POSTs.
+  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,
+    );
+  }
+
+  // Vault-name shape guard — reject anything that can't be a services.json key
+  // before any DB / authority work. Same posture as the other vault-token mints.
+  if (!VAULT_NAME_RE.test(vaultName)) {
+    return htmlResponse(
+      renderAdminError({
+        title: "Invalid vault name",
+        message: `"${vaultName}" is not a valid vault name.`,
+      }),
+      400,
+    );
+  }
+
+  // Gate 2 — assignment + admin-verb cap. `vaultVerbsForUserVault` returns:
+  //   - null  → no assignment for this vault → 403.
+  //   - [...] → the verbs the assignment role permits; must include `admin`.
+  // Assigned users hold read/write/admin on their vault (2026-05-30); the first
+  // admin has no `user_vaults` rows so gets `null` here and a 403 — by design,
+  // admins use the SPA path. This is the cap to the user's actual authority.
+  const allowed = vaultVerbsForUserVault(deps.db, user.id, vaultName);
+  if (allowed === null || !allowed.includes("admin")) {
+    return htmlResponse(
+      renderAdminError({
+        title: "Not your vault to manage",
+        message: `You don't have admin access to a vault named "${vaultName}". Ask the hub operator if you think this is wrong.`,
+      }),
+      403,
+    );
+  }
+
+  // Force-change-password gate (item F / hub#469). An admin-created/reset user
+  // with `password_changed: false` is sent to the change-password rail BEFORE
+  // minting — same gate `/account/vault-token` applies, so a temp-password
+  // handoff can't be parlayed into a vault-admin deep-link. Placed AFTER the
+  // authority gates (an unassigned/garbage request still gets its 403/400) and
+  // BEFORE the mint. 303 so the browser re-issues as GET. Does NOT reintroduce
+  // the bypass #469 closed.
+  if (!user.passwordChanged) {
+    return new Response(null, {
+      status: 303,
+      headers: { location: "/account/change-password", "cache-control": "no-store" },
+    });
+  }
+
+  // Mint the vault-admin deep-link token. Short TTL (10 min, matching the admin
+  // sibling) — it's a bootstrap token the vault SPA trades for its session, not
+  // a long-lived headless credential (that's `/account/vault-token`).
+  const scope = `vault:${vaultName}:admin`;
+  const audience = `vault.${vaultName}`;
+  const minted = await signAccessToken(deps.db, {
+    sub: user.id,
+    scopes: [scope],
+    audience,
+    clientId: ACCOUNT_VAULT_ADMIN_CLIENT_ID,
+    issuer: deps.hubOrigin,
+    ttlSeconds: VAULT_ADMIN_TOKEN_TTL_SECONDS,
+    vaultScope: [vaultName],
+    ...(deps.now !== undefined ? { now: deps.now } : {}),
+  });
+
+  recordTokenMint(deps.db, {
+    jti: minted.jti,
+    createdVia: "cli_mint",
+    subject: user.id,
+    // Anchor the registry row to the user's id so the operator's token registry
+    // + the revocation list attribute it correctly.
+    userId: user.id,
+    clientId: ACCOUNT_VAULT_ADMIN_CLIENT_ID,
+    scopes: [scope],
+    expiresAt: minted.expiresAt,
+    ...(deps.now !== undefined ? { now: deps.now } : {}),
+  });
+
+  // Build the redirect target: <vault-url><managementUrl>#token=<jwt>. The
+  // vault URL is the hub-mounted path (`<hubOrigin>/vault/<name>`); the
+  // managementUrl (default `/admin/`) is the vault admin SPA entry point. The
+  // JWT rides the URL fragment — never sent to the server — exactly as the hub
+  // SPA's "Manage" button does (vault PR #219).
+  const trimmedOrigin = deps.hubOrigin.replace(/\/+$/, "");
+  const vaultUrl = `${trimmedOrigin}/vault/${vaultName}`;
+  const target = resolveManagementUrl(vaultUrl, deps.managementUrl ?? "/admin/");
+  const sep = target.includes("#") ? "&" : "#";
+  const location = `${target}${sep}token=${minted.token}`;
+
+  return new Response(null, {
+    status: 303,
+    headers: { location, "cache-control": "no-store" },
+  });
+}

package/src/account-vault-token.ts

@@ -69,15 +69,22 @@ import {
 } from "./account-home-ui.ts";
 import { renderAdminError } from "./admin-login-ui.ts";
 import { CSRF_FIELD_NAME, ensureCsrfToken, verifyCsrfToken } from "./csrf.ts";
+import { userHasExternalAiGrant } from "./grants.ts";
 import { inferAudience } from "./jwt-audience.ts";
 import { recordTokenMint, signAccessToken } from "./jwt-sign.ts";
 import { vaultTokenMintRateLimiter } from "./rate-limit.ts";
 import { findActiveSession } from "./sessions.ts";
 import { isTotpEnrolled } from "./two-factor-store.ts";
 import { type VaultVerb, getUserById, isFirstAdmin, vaultVerbsForUserVault } from "./users.ts";
+import { VAULT_NAME_CHARSET_RE } from "./vault-name.ts";
 
-/** Matches the manifest vault-name validator + `/admin/vault-admin-token`. */
-const VAULT_NAME_RE = /^[a-zA-Z0-9_-]+$/;
+/**
+ * Lowercase-only vault-name charset (item I) — single source of truth in
+ * vault-name.ts, matching what vault's init enforces. Was `[a-zA-Z0-9_-]`; the
+ * uppercase superset let a mint name drift from vault's lowercase URL-derived
+ * name, so the minted token's `vault.<Name>` audience wouldn't validate.
+ */
+const VAULT_NAME_RE = VAULT_NAME_CHARSET_RE;
 /** Verbs this surface will ever mint. `admin` is deliberately absent. */
 const ALLOWED_VERBS: readonly VaultVerb[] = ["read", "write", "admin"];
 /** client_id stamped on the minted JWT + registry row. */
@@ -183,6 +190,14 @@ export async function handleAccountVaultTokenPost(
         csrfToken: csrf.token,
         twoFactorEnabled: isTotpEnrolled(deps.db, user.id),
         mintableVerbs: buildMintableVerbs(deps.db, user.id, user.assignedVaults),
+        // hub#583: "connected" means an EXTERNAL AI/MCP client (Claude, Cursor,
+        // …) was wired to a vault — NOT a first-party browser sign-in. Notes /
+        // the admin SPA are OAuth clients too and write vault-scoped grants, so
+        // the old `userHasVaultGrant` lit "✓ You're connected" the moment the
+        // user opened Notes. `userHasExternalAiGrant` filters those out.
+        connectedVault: user.assignedVaults.some((v) =>
+          userHasExternalAiGrant(deps.db, user.id, v),
+        ),
         ...extras,
       }),
       status,
@@ -233,6 +248,25 @@ export async function handleAccountVaultTokenPost(
     });
   }
 
+  // Force-change-password gate (item F / hub#469, NARROW). A user the admin
+  // created/reset lands with `password_changed: false` and an admin-known temp
+  // password. Without this gate an authorized friend could mint a LONG-LIVED
+  // vault token here and then keep using (or never rotate) the temp password —
+  // the token outlives any later rotation, defeating the "temp password is a
+  // one-time handoff" model. So an authorized-but-unrotated friend is sent to
+  // the change-password rail BEFORE minting anything. Placed AFTER the
+  // authority gates (so an unassigned/garbage request still gets its 403/400,
+  // preserving those semantics) and BEFORE the rate-limit + mint. 303 (See
+  // Other) so the browser re-issues as GET. Narrow #469 fix — gates
+  // token-minting specifically; the broad per-request /account/* wall is
+  // deferred to Aaron's design call.
+  if (!user.passwordChanged) {
+    return new Response(null, {
+      status: 303,
+      headers: { location: "/account/change-password", "cache-control": "no-store" },
+    });
+  }
+
   // Rate limit — after CSRF + authority shape, before the mint. Per-user.
   const rlNow = (deps.now ?? (() => new Date()))();
   const gate = vaultTokenMintRateLimiter.checkAndRecord(user.id, rlNow);

package/src/admin-login-ui.ts

@@ -152,6 +152,127 @@ export function renderTotpChallenge(props: TotpChallengeProps): string {
   return baseDocument("Two-factor authentication — Parachute", body);
 }
 
+// --- invite redemption ( /account/setup/<token> ) --------------------------
+
+export interface InviteSetupProps {
+  /** The raw token from the URL — POSTs back to the same path. */
+  token: string;
+  csrfToken: string;
+  /**
+   * When the invite pins a vault name the redeemer can't choose one — we show
+   * it read-only. When null the redeemer names their own vault (a text field).
+   */
+  pinnedVaultName: string | null;
+  /** Whether redemption provisions a vault at all (shows the vault row iff true). */
+  provisionVault: boolean;
+  username?: string;
+  vaultName?: string;
+  errorMessage?: string;
+}
+
+/**
+ * Server-rendered "claim your invite" form for `/account/setup/<token>`.
+ * Stands alone without the SPA (same posture as `/login` + the setup wizard):
+ * a brand-new invitee hits this with no session and no JS. Posts back to the
+ * same `/account/setup/<token>` path. Reuses the shared login chrome.
+ */
+export function renderInviteSetup(props: InviteSetupProps): string {
+  const { token, csrfToken, pinnedVaultName, provisionVault, username, vaultName, errorMessage } =
+    props;
+  const error = errorMessage ? `<p class="error-banner">${escapeHtml(errorMessage)}</p>` : "";
+  const usernameAttr = username ? ` value="${escapeAttr(username)}"` : "";
+
+  // Vault row: shown only when the invite provisions a vault. Pinned → a
+  // read-only display of the name the admin chose (redeemer can't squat names).
+  // Unpinned → a text field the redeemer fills.
+  let vaultRow = "";
+  if (provisionVault) {
+    if (pinnedVaultName !== null) {
+      vaultRow = `
+        <label class="field">
+          <span class="field-label">Your vault</span>
+          <input type="text" value="${escapeAttr(pinnedVaultName)}" readonly disabled />
+          <span class="field-hint">Your hub operator named this vault for you.</span>
+        </label>`;
+    } else {
+      const vaultAttr = vaultName ? ` value="${escapeAttr(vaultName)}"` : "";
+      // OPTIONAL (not `required`): a blank submission defaults the vault name
+      // to the chosen username, resolved server-side (this form is no-JS, so
+      // the server is the source of truth). The inline script below is a
+      // progressive-enhancement pre-fill only.
+      vaultRow = `
+        <label class="field">
+          <span class="field-label">Name your vault</span>
+          <input type="text" name="vault_name" id="vault_name" autocomplete="off"
+            minlength="2" maxlength="32"
+            pattern="[a-z0-9_-]+" title="lowercase letters, digits, _ - (2–32 chars)"
+            spellcheck="false" autocapitalize="off"
+            placeholder="defaults to your username"${vaultAttr} />
+          <span class="field-hint">lowercase letters, digits, <code>_</code>, <code>-</code> (2–32 chars). Leave blank to use your username.</span>
+        </label>`;
+    }
+  }
+
+  // Progressive enhancement ONLY: mirror the username into the (empty) vault
+  // field as the user types, so they see the default before submitting. The
+  // server applies the same default with no JS (the field is optional), so
+  // this is purely cosmetic — it stops mirroring the moment the user edits the
+  // vault field directly. Shown only for the unpinned-provision case.
+  const vaultPrefillScript =
+    provisionVault && pinnedVaultName === null
+      ? `
+    <script>
+      (function () {
+        var u = document.getElementById("username");
+        var v = document.getElementById("vault_name");
+        if (!u || !v) return;
+        var dirty = v.value !== "";
+        v.addEventListener("input", function () { dirty = true; });
+        u.addEventListener("input", function () {
+          if (!dirty) v.value = u.value;
+        });
+      })();
+    </script>`
+      : "";
+
+  const body = `
+    <div class="card">
+      <div class="card-header">
+        ${header()}
+        <h1>Claim your invite</h1>
+        <p class="subtitle">Pick a username and password to create your Parachute account${
+          provisionVault ? " and your own vault" : ""
+        }.</p>
+      </div>
+      ${error}
+      <form method="POST" action="/account/setup/${escapeAttr(token)}" class="auth-form">
+        ${renderCsrfHiddenInput(csrfToken)}
+        <label class="field">
+          <span class="field-label">Username</span>
+          <input type="text" name="username" id="username" autocomplete="username" autofocus
+            required minlength="2" maxlength="32"
+            pattern="[a-z0-9_-]+" title="lowercase letters, digits, _ - (2–32 chars)"
+            spellcheck="false" autocapitalize="off"${usernameAttr} />
+          <span class="field-hint">lowercase letters, digits, <code>_</code>, <code>-</code></span>
+        </label>
+        <label class="field">
+          <span class="field-label">Password</span>
+          <input type="password" name="password" autocomplete="new-password"
+            required minlength="12" />
+          <span class="field-hint">at least 12 characters</span>
+        </label>
+        <label class="field">
+          <span class="field-label">Confirm password</span>
+          <input type="password" name="password_confirm" autocomplete="new-password"
+            required minlength="12" />
+        </label>
+        ${vaultRow}
+        <button type="submit" class="btn btn-primary">Create my account</button>
+      </form>
+    </div>${vaultPrefillScript}`;
+  return baseDocument("Claim your invite — Parachute", body);
+}
+
 // --- error page ------------------------------------------------------------
 
 export function renderAdminError(props: { title: string; message: string }): string {

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

@@ -28,13 +28,19 @@ import type { Database } from "bun:sqlite";
 import { signAccessToken } from "./jwt-sign.ts";
 import { findSession, parseSessionCookie } from "./sessions.ts";
 import { isFirstAdmin } from "./users.ts";
+import { VAULT_NAME_CHARSET_RE } from "./vault-name.ts";
 
 /** Short TTL — matches host-admin-token. SPA re-fetches on near-expiry. */
 export const VAULT_ADMIN_TOKEN_TTL_SECONDS = 10 * 60;
 const VAULT_ADMIN_CLIENT_ID = "parachute-hub-spa";
 
-/** Same shape as the manifest name validator — keeps URL-injection out. */
-const VAULT_NAME_RE = /^[a-zA-Z0-9_-]+$/;
+/**
+ * Lowercase-only vault-name charset (item I) — single source of truth in
+ * vault-name.ts, matching vault's init. Keeps URL-injection out AND closes the
+ * case-drift class (an uppercased name minting `vault.<Name>` audience that
+ * vault's lowercase URL-derived name would never validate).
+ */
+const VAULT_NAME_RE = VAULT_NAME_CHARSET_RE;
 
 export interface MintVaultAdminTokenDeps {
   db: Database;