@openparachute/hub 0.5.10-rc.9 → 0.5.10

package/src/jwt-sign.ts

@@ -47,6 +47,20 @@ export interface SignAccessTokenOpts {
    * or thread it from `OAuthDeps.issuer`.
    */
   issuer: string;
+  /**
+   * Per-user vault pin — the multi-user Phase 1 (design
+   * [`2026-05-20-multi-user-phase-1.md`](https://parachute.computer/design/2026-05-20-multi-user-phase-1/))
+   * vault_scope claim. Non-empty for non-admin users (a single-element list
+   * naming their `assigned_vault`); empty `[]` for admin users (the "no
+   * per-user vault restriction" sentinel — admins can request any vault on
+   * the hub via the consent picker). Always emitted as a claim — defaults
+   * to `[]` when callers omit — so a downstream consumer (PR 5's
+   * scope-guard at vault / notes / scribe) can unambiguously read it
+   * without distinguishing "absent" from "empty." Phase 1 always has
+   * length ≤1; the list shape carries Phase 2 multi-vault forward without
+   * a wire-shape change.
+   */
+  vaultScope?: string[];
   /** Override the jti (defaults to random base64url(16)). Used by tests. */
   jti?: string;
   /**
@@ -60,7 +74,8 @@ export interface SignAccessTokenOpts {
    * `pa_scope_set` (which scope-set the token was minted under) so an
    * auto-rotation can preserve the operator's chosen narrowing across mints.
    * Reserved claims (`scope`, `client_id`, `sub`, `iss`, `iat`, `exp`, `aud`,
-   * `jti`) are owned by this function and overwritten if passed here.
+   * `jti`, `vault_scope`) are owned by this function and overwritten if
+   * passed here.
    */
   extraClaims?: Record<string, unknown>;
 }
@@ -85,6 +100,7 @@ export async function signAccessToken(
     ...(opts.extraClaims ?? {}),
     scope: opts.scopes.join(" "),
     client_id: opts.clientId,
+    vault_scope: opts.vaultScope ?? [],
   })
     .setProtectedHeader({ alg: SIGNING_ALGORITHM, kid: key.kid })
     .setSubject(opts.sub)

package/src/oauth-handlers.ts

@@ -62,6 +62,7 @@ import {
   renderConsent,
   renderError,
   renderLogin,
+  renderUnknownClient,
 } from "./oauth-ui.ts";
 import { isSameOriginRequest } from "./origin-check.ts";
 import { isHttpsRequest } from "./request-protocol.ts";
@@ -79,7 +80,8 @@ import {
   findSession,
   parseSessionCookie,
 } from "./sessions.ts";
-import { getUserByUsername, verifyPassword } from "./users.ts";
+import { getUserById, getUserByUsername, verifyPassword } from "./users.ts";
+import { listVaultNames } from "./vault-names.ts";
 import { isVaultEntry, shortName, vaultInstanceNameFor } from "./well-known.ts";
 
 /** Verbs whose unnamed `vault:<verb>` form needs picker disambiguation. */
@@ -95,26 +97,6 @@ function unnamedVaultVerbs(scopes: string[]): string[] {
   return verbs;
 }
 
-/**
- * Vault instance names registered on this host, derived from services.json.
- * Walks both manifest shapes — single-entry-multi-path (`paths: ["/vault/work",
- * "/vault/personal"]`) and per-vault entries (`parachute-vault-work`) — by
- * delegating each (name, path) pair to the canonical `vaultInstanceNameFor`
- * helper. Entries with no paths still resolve to a name via the helper's
- * manifest-suffix fallback (#143).
- */
-function listVaultNames(manifest: ServicesManifest): string[] {
-  const names = new Set<string>();
-  for (const svc of manifest.services) {
-    if (!isVaultEntry(svc)) continue;
-    const paths = svc.paths.length > 0 ? svc.paths : [undefined];
-    for (const path of paths) {
-      names.add(vaultInstanceNameFor(svc.name, path));
-    }
-  }
-  return Array.from(names).sort();
-}
-
 /** Rewrite each unnamed `vault:<verb>` to `vault:<picked>:<verb>`. */
 function narrowVaultScopes(scopes: string[], pickedVault: string): string[] {
   return scopes.map((s) => {
@@ -127,6 +109,34 @@ function narrowVaultScopes(scopes: string[], pickedVault: string): string[] {
   });
 }
 
+/**
+ * Derive the `vault_scope` claim value for a given hub user. Multi-user
+ * Phase 1 (design
+ * [`2026-05-20-multi-user-phase-1.md`](https://parachute.computer/design/2026-05-20-multi-user-phase-1/),
+ * §oauth-claim-shape).
+ *
+ *   - `userId` resolves to no row → `[]`. Defensive: the caller already
+ *     validated the user existed (auth-code redemption / refresh row's
+ *     user_id), but a delete-between-mint-and-now race shouldn't 500. Empty
+ *     is the safe sentinel — the scope-bearing `scope` claim is still the
+ *     gate.
+ *   - User exists with `assignedVault === null` → `[]`. Admin / unpinned
+ *     posture; the consent picker is the source of truth.
+ *   - User exists with `assignedVault === "name"` → `["name"]`. The Phase 1
+ *     single-vault pin; PR 5's scope-guard at vault/notes/scribe consumes
+ *     this to enforce that an assigned user can't request scope against any
+ *     vault other than their assigned one.
+ *
+ * Always returns an array (never undefined) so the JWT carries the claim
+ * unconditionally — readers don't have to distinguish "absent" from "empty."
+ */
+export function vaultScopeForUser(db: Database, userId: string): string[] {
+  const user = getUserById(db, userId);
+  if (!user) return [];
+  if (user.assignedVault === null) return [];
+  return [user.assignedVault];
+}
+
 export interface OAuthDeps {
   /** Hub origin used for `iss`, `authorization_endpoint`, etc. */
   issuer: string;
@@ -452,6 +462,7 @@ function pendingClientResponse(
         redirectUris: client.redirectUris,
         requestedScopes,
         ...(requestedVault !== undefined && { requestedVault }),
+        hubOrigin: deps.issuer,
         approveForm: { csrfToken: csrf.token, returnTo },
       }),
       403,
@@ -465,6 +476,7 @@ function pendingClientResponse(
       redirectUris: client.redirectUris,
       requestedScopes,
       ...(requestedVault !== undefined && { requestedVault }),
+      hubOrigin: deps.issuer,
     }),
     403,
     extra,
@@ -489,6 +501,70 @@ function pendingClientResponse(
  * strict spec-shaped handling. The extra fields are spec-permitted
  * extensions ("other parameters").
  */
+/**
+ * Render the "Unknown application" page surfaced by /oauth/authorize when
+ * `getClient(db, clientId)` returns null. Promotes the recovery affordance
+ * (a "Reset connection" button that clears `lens:dcr:*` localStorage on the
+ * hub's own origin) when the request's redirect_uri points at one of the
+ * hub's bound origins — that's the Notes-mounted-at-hub-origin case where
+ * we can safely run inline JS against the SPA's storage.
+ *
+ * Root-cause shape (rc.11 fresh-machine connect bug): an operator who wipes
+ * `~/.parachute/hub.db` between testing iterations strands their browser's
+ * cached client_id, and the SPA has no signal to clear it without
+ * operator action. The hub-side fix is to give the operator one click on
+ * the error page. See `renderUnknownClient` in oauth-ui.ts for the full
+ * design + the localStorage key the snippet clears.
+ *
+ * Cross-origin SPA redirect_uris fall back to the static error variant —
+ * we can't reach a third-party SPA's storage from this page. Malformed
+ * redirect_uris likewise fall back (we never trust an unparsed URL).
+ */
+function unknownClientResponse(
+  clientId: string,
+  redirectUri: string | null,
+  deps: OAuthDeps,
+): Response {
+  const selfOriginRedirectPath = resolveSelfOriginRedirectPath(redirectUri, deps);
+  return htmlResponse(
+    renderUnknownClient({
+      clientId,
+      selfOriginRedirectPath,
+    }),
+    400,
+  );
+}
+
+/**
+ * Parse a redirect_uri and return its pathname iff its origin is one the
+ * hub serves itself (any entry in `hubBoundOrigins`). Returns null when
+ * the URL is missing, malformed, or points at a non-hub origin — the
+ * caller falls back to a static error in those cases. The pathname is
+ * what the "Reset connection" button navigates to after clearing the
+ * SPA's cached client_id; e.g. for `http://localhost:1939/notes/oauth/callback`
+ * we return `/notes/oauth/callback`. The SPA then routes that internally
+ * (Notes' /oauth/callback handler harmlessly errors on missing code +
+ * state, and the user gets dropped onto the connect screen for a fresh
+ * DCR — that's the recovery path).
+ *
+ * Pathname-only (not the full URL) is deliberate: same-origin navigation
+ * is trivially safe, and we don't want to surface a redirect that
+ * leaves the hub's origin even when the redirect_uri claims it. If a
+ * future SPA needs different recovery semantics, this is the seam.
+ */
+function resolveSelfOriginRedirectPath(redirectUri: string | null, deps: OAuthDeps): string | null {
+  if (!redirectUri) return null;
+  let parsed: URL;
+  try {
+    parsed = new URL(redirectUri);
+  } catch {
+    return null;
+  }
+  const bound = resolveBoundOrigins(deps);
+  if (!bound.includes(parsed.origin)) return null;
+  return parsed.pathname || "/";
+}
+
 function pendingClientJson(clientId: string, issuer: string): Response {
   const base = issuer.replace(/\/$/, "");
   return jsonResponse(
@@ -588,8 +664,12 @@ export function handleAuthorizeGet(db: Database, req: Request, deps: OAuthDeps):
   const client = getClient(db, parsed.clientId);
   if (!client) {
     // Can't safely redirect — we don't trust the redirect_uri until we've
-    // matched it against a registered client. Render an HTML error.
-    return htmlError("Unknown application", "This client_id is not registered with this hub.", 400);
+    // matched it against a registered client. Render an HTML error that
+    // promotes a one-click recovery when the redirect_uri points at one
+    // of our own origins (the canonical fresh-machine repro: an operator
+    // wiped hub.db, the SPA still holds the old client_id in
+    // localStorage, the recovery is "clear that key and reload the SPA").
+    return unknownClientResponse(parsed.clientId, parsed.redirectUri, deps);
   }
   if (client.status !== "approved") {
     return pendingClientResponse(db, req, client, url, deps);
@@ -645,10 +725,19 @@ export function handleAuthorizeGet(db: Database, req: Request, deps: OAuthDeps):
     return issueAuthCodeRedirect(db, parsed, requestedScopes, session.userId, deps);
   }
 
+  // Multi-user Phase 1: non-admin users (with `assigned_vault !== null`) see
+  // the picker locked to their assigned vault — they can't pick a different
+  // one. Admin users (assigned_vault === null) see the full dropdown.
+  // Defensive null-coalesce: the session points at a deleted user shouldn't
+  // 500; treat as admin posture (the broader scope-validation gate will
+  // catch any actual privilege issue).
+  const user = getUserById(db, session.userId);
+  const lockedVault = user?.assignedVault ?? null;
+
   const manifest = (deps.loadServicesManifest ?? readServicesManifest)();
   const vaultNames = listVaultNames(manifest);
   return htmlResponse(
-    renderConsent(consentProps(client, parsed, vaultNames, csrf.token)),
+    renderConsent(consentProps(client, parsed, vaultNames, csrf.token, lockedVault)),
     200,
     extra,
   );
@@ -784,17 +873,25 @@ async function handleConsentSubmit(
   }
   const client = getClient(db, params.clientId);
   if (!client) {
-    return htmlError("Unknown application", "This client_id is not registered with this hub.", 400);
+    // Same shape as the GET handler — see the comment there. Reaching
+    // this branch on the consent POST means the client_id was deleted
+    // between render and submit (vanishingly rare) or the form was
+    // hand-crafted; the recovery affordance is still the right answer
+    // for both cases.
+    return unknownClientResponse(params.clientId, params.redirectUri, deps);
   }
   if (client.status !== "approved") {
     // Defensive: consent only renders for approved clients, so a non-approved
     // status here means the row was unapproved between render and submit (or
     // the form was hand-crafted). The approve UI requires a known authorize
     // URL to round-trip via `return_to`, which we don't reconstruct here —
-    // surface the static error and let the operator restart from the SPA.
+    // surface the static error pointing at the web approval path (the
+    // canonical recovery post-#277; rc.19 retired the CLI mention from
+    // every browser-visible surface so the path advertised here matches
+    // what the unauth GET-on-pending page now shows).
     return htmlError(
       "App not yet approved",
-      `This client_id is registered but has not been approved. Run \`parachute auth approve-client ${client.clientId}\` from a terminal, then try again.`,
+      `This client_id is registered but has not been approved. Sign in as admin and approve at /admin/approve-client/${client.clientId}, or send the link to your hub operator.`,
       403,
     );
   }
@@ -828,6 +925,19 @@ async function handleConsentSubmit(
       params.state,
     );
   }
+  // Multi-user Phase 1 (design 2026-05-20-multi-user-phase-1.md): non-admin
+  // users (`assigned_vault !== null`) are pinned to a single vault. The
+  // consent screen renders the picker locked to that vault and any named
+  // scopes (`vault:<name>:<verb>`) requested by the client must match. The
+  // server-side defense here refuses any mint where the user's submission
+  // disagrees — Aaron pinned this as "server-side defense refuses mints
+  // whose picked vault disagrees with assigned_vault" rather than silent
+  // overwrite, so a hand-crafted POST or a misbehaving SPA can't bypass the
+  // lock. Admin users (`assigned_vault === null`) keep the existing picker-
+  // as-source-of-truth behavior.
+  const sessionUser = getUserById(db, session.userId);
+  const assignedVault = sessionUser?.assignedVault ?? null;
+
   // Vault picker (Q1 of the vault-config-and-scopes design): an unnamed
   // `vault:<verb>` scope is ambiguous about which vault it grants access to.
   // Force the operator to pick before the JWT is minted, then rewrite the
@@ -852,8 +962,52 @@ async function handleConsentSubmit(
         400,
       );
     }
+    // Server-side defense: non-admin user submitted a vault that disagrees
+    // with their `assigned_vault`. The picker rendered as locked, so a UI-
+    // path user couldn't reach this — but a hand-crafted form bypassing the
+    // locked input lands here. Refuse the mint instead of silently
+    // overwriting; the explicit error tells the operator the assignment is
+    // load-bearing.
+    if (assignedVault !== null && pickedVault !== assignedVault) {
+      return htmlError(
+        "Vault assignment mismatch",
+        `vault_scope_mismatch: the picked vault "${pickedVault}" does not match your vault assignment. Ask the hub admin to update your assignment, or pick the vault shown on the consent screen.`,
+        400,
+      );
+    }
     scopes = narrowVaultScopes(scopes, pickedVault);
   }
+
+  // Server-side defense for named-vault scopes (`vault:<name>:<verb>`) too.
+  // A non-admin user can't request scope against any vault other than their
+  // assigned one — same invariant as the picker check above, applied to
+  // scopes that arrived already-named (e.g. a client that knows the user's
+  // vault and asked for `vault:bob:read` directly). Admins (assigned_vault
+  // null) skip this check.
+  if (assignedVault !== null) {
+    const mismatched: string[] = [];
+    for (const s of scopes) {
+      const parts = s.split(":");
+      if (
+        parts.length === 3 &&
+        parts[0] === "vault" &&
+        parts[1] &&
+        parts[2] &&
+        VAULT_VERBS.has(parts[2]) &&
+        parts[1] !== assignedVault
+      ) {
+        mismatched.push(s);
+      }
+    }
+    if (mismatched.length > 0) {
+      return htmlError(
+        "Vault assignment mismatch",
+        `vault_scope_mismatch: requested scopes ${mismatched.join(", ")} target a vault other than your vault assignment.`,
+        400,
+      );
+    }
+  }
+
   // Record (or extend) the grant so the next /oauth/authorize for this
   // (user, client) with these scopes — or any subset — can skip the consent
   // screen (#75). UNION semantics: if the user previously granted [a, b, c]
@@ -1155,6 +1309,13 @@ async function handleTokenAuthorizationCode(
     audience,
     clientId: redeemed.clientId,
     issuer: deps.issuer,
+    // vault_scope claim — Phase 1 per-user vault pin. Non-empty list for
+    // non-admin users with `assigned_vault` set; empty for admin / unpinned.
+    // The narrowing in `handleConsentSubmit` already rewrote `vault:<verb>` →
+    // `vault:<assigned_vault>:<verb>` for non-admin users, so the auth code's
+    // scopes are pre-aligned; this claim is the explicit "owned vault"
+    // signal PR 5 consumes downstream.
+    vaultScope: vaultScopeForUser(db, redeemed.userId),
     now: deps.now,
   });
   // Phase 1 (#212) registry exemption: code-grant access tokens piggyback
@@ -1268,6 +1429,14 @@ async function handleTokenRefresh(
     audience,
     clientId: row.clientId,
     issuer: deps.issuer,
+    // vault_scope claim — re-derived from the user's *current*
+    // `assigned_vault` at refresh time (not snapshotted onto the refresh-
+    // token row). An admin who changes a user's `assigned_vault` between
+    // mint and refresh sees the new value on the next refresh; existing
+    // access tokens carry their original claim until their 15-minute TTL
+    // elapses. Same posture as the design's "OAuth issuer reads
+    // `assigned_vault` at mint time, not at session-creation time" pin.
+    vaultScope: vaultScopeForUser(db, refreshUserId),
     now: deps.now,
   });
   let refresh: ReturnType<typeof signRefreshToken>;
@@ -1603,16 +1772,55 @@ function consentProps(
   params: AuthorizeFormParams,
   vaultNames: string[],
   csrfToken: string,
+  lockedVault: string | null,
 ) {
   const scopes = params.scope.split(" ").filter((s) => s.length > 0);
   const unnamedVerbs = unnamedVaultVerbs(scopes);
+  // Multi-user Phase 1 (design 2026-05-20-multi-user-phase-1.md, decision-pin
+  // "consent picker for non-admin users"): non-admin users (assigned_vault
+  // non-null) see the picker locked to their `assigned_vault` rather than a
+  // free dropdown. Phase 2 will hide other vaults entirely; Phase 1 ships
+  // lock-the-picker (the smallest diff that satisfies "user can't pick a
+  // vault they don't own"). Server-side defense in `handleConsentSubmit`
+  // refuses mints whose POST disagrees regardless of how the picker is
+  // rendered.
+  let vaultPicker: VaultPickerProps | undefined;
+  if (unnamedVerbs.length > 0) {
+    vaultPicker =
+      lockedVault !== null
+        ? { unnamedVerbs, availableVaults: vaultNames, lockedVault }
+        : { unnamedVerbs, availableVaults: vaultNames };
+  }
+  // Named-scope display: substitute unnamed `vault:<verb>` rows with the
+  // resolved form the operator will actually consent to.
+  //   - Non-admin (lockedVault set) → render `vault:<lockedVault>:<verb>`.
+  //   - Admin with exactly one vault available → render that vault's name;
+  //     the picker pre-checks it and a default-Approve mints scope against
+  //     it, so the displayed scope matches the next state of the form.
+  //   - Admin with multiple vaults / no vaults → null sentinel; render with
+  //     a `<TBD>` placeholder + a hint pointing at the picker. Once the
+  //     operator clicks a radio the JS-free form still posts the chosen
+  //     name; the displayed scope only changes after the next page render.
+  let displayVault: string | null = null;
+  if (lockedVault !== null) {
+    displayVault = lockedVault;
+  } else if (unnamedVerbs.length > 0 && vaultNames.length === 1) {
+    const only = vaultNames[0];
+    if (only) displayVault = only;
+  }
   return {
     params,
     clientId: client.clientId,
     clientName: client.clientName ?? client.clientId,
     scopes,
     csrfToken,
-    vaultPicker:
-      unnamedVerbs.length > 0 ? { unnamedVerbs, availableVaults: vaultNames } : undefined,
+    vaultPicker,
+    displayVault,
   };
 }
+
+interface VaultPickerProps {
+  unnamedVerbs: string[];
+  availableVaults: string[];
+  lockedVault?: string;
+}