@openparachute/hub 0.5.10-rc.9 → 0.5.10

package/src/cors.ts

@@ -0,0 +1,263 @@
+/**
+ * CORS posture for the public OAuth + discovery surface.
+ *
+ * Background. Third-party SPAs (Aaron's Gitcoin Brain UI on
+ * `https://unforced-dev.github.io`, future user-built clients, OIDC libraries
+ * pulling discovery + JWKS) need to talk to a self-hosted hub from a foreign
+ * origin. The OAuth Dynamic Client Registration spec (RFC 7591) is *designed*
+ * for cross-origin use: any SPA registers itself, runs the auth-code flow,
+ * exchanges the code at `/oauth/token`. Without CORS headers on those
+ * endpoints, browser preflights fail and the entire third-party-SPA story is
+ * broken before it starts.
+ *
+ * The matrix:
+ *
+ *   in-scope (echo-origin + `Allow-Credentials: true` for browser callers,
+ *             wildcard `*` + `Allow-Credentials: false` for non-browser
+ *             callers without an Origin header):
+ *     /oauth/*                                — DCR, authorize, token, revoke
+ *
+ *   `/.well-known/*` handlers carry their own inline CORS posture in
+ *   `hub-server.ts` (a narrower `Allow-Methods: GET, OPTIONS` since they're
+ *   read-only) and aren't routed through this module.
+ *
+ *   out-of-scope (same-origin only, no CORS headers):
+ *     /api/*                                  — admin Bearer surface
+ *     /admin/*                                — admin SPA shell
+ *     /login, /logout, /account/*             — interactive session pages
+ *     /vault/*, /<service-mount>/*            — module-level content proxy
+ *
+ * Why echo the request Origin instead of `*`:
+ *
+ * The rc.17 posture used a static `Access-Control-Allow-Origin: *` +
+ * `Allow-Credentials: false`. That works for SPAs that fetch with
+ * `credentials: 'omit'`, but most SPA frameworks (the Gitcoin Brain UI's
+ * default among them) fetch with `credentials: 'include'`. Browsers reject
+ * any `*` ACAO response when the request was made with credentials mode
+ * `include` — even when the endpoint doesn't actually use cookies. The CORS
+ * spec requires an *explicit* origin echo paired with
+ * `Access-Control-Allow-Credentials: true` for that combination to work.
+ *
+ * Why this isn't a security regression vs `*`:
+ *
+ * Browsers already restrict the *response* readability by Origin under SOP —
+ * an attacker page at `evil.example` issuing a `fetch(hub, {credentials:
+ * 'include'})` only gets to *read* the response if the server says yes by
+ * echoing `evil.example` back in ACAO. Echoing back the same origin the
+ * browser already sent reveals nothing the attacker couldn't reach by
+ * standing up their own server. The protocol-level gates (PKCE +
+ * redirect_uri matching + the operator-driven approval flow) still bound
+ * what a malicious cross-origin caller can *do*. This is the canonical
+ * posture for OAuth authorization servers — see [Okta], [Auth0],
+ * [Keycloak] — for exactly this reason: OAuth endpoints are public by
+ * design, bearer-token-based not cookie-based, and an allowlist at this
+ * layer adds friction without preventing any attack the protocol doesn't
+ * already cover.
+ *
+ * Why fall back to `*` + `credentials: false` when there's no Origin:
+ *
+ * A request without an `Origin` header is a non-browser caller (`curl`
+ * without `-H Origin: …`, a server-side fetch). Echoing back nothing would
+ * leave the response with no ACAO at all — fine for non-browser callers
+ * since they don't enforce CORS, but breaks the contract that a
+ * curl-shaped probe to `/oauth/...` should still come back with a
+ * well-formed CORS preamble for diagnostic purposes. The wildcard +
+ * credentials:false branch matches the rc.17 shape exactly for that case.
+ *
+ * Why we don't allowlist per-Origin:
+ *
+ * For OAuth specifically: an allowlist defeats the purpose of an open
+ * identity provider. For the broader admin / API surface, an allowlist
+ * *is* the right shape — but that surface stays same-origin-only here and
+ * doesn't pass through this module.
+ *
+ * Header rationale:
+ *
+ *   Access-Control-Allow-Origin
+ *     The request's `Origin` header verbatim when present; `*` otherwise
+ *     (non-browser caller — see fallback note above).
+ *
+ *   Access-Control-Allow-Credentials
+ *     `true` when echoing a specific origin (required for browsers fetching
+ *     with `credentials: 'include'`); `false` on the `*` fallback (the
+ *     wildcard branch must pair with credentials:false per CORS spec).
+ *
+ *   Vary: Origin
+ *     Set on every echo-origin response. Without it, a response for
+ *     `evil.example` can be cached by the browser's HTTP cache (or a
+ *     downstream CDN) and reused for a subsequent `good.example` request,
+ *     leaking the wrong ACAO and breaking CORS in unpredictable ways.
+ *     Critical for cache correctness.
+ *
+ *   Access-Control-Allow-Methods: GET, POST, OPTIONS
+ *     The union of methods the in-scope route family supports. Per-route
+ *     could be narrower (e.g. /oauth/token is POST-only), but advertising
+ *     the union is the simpler shape and browsers don't enforce a per-route
+ *     check anyway — the *actual* request method gates execution at the
+ *     handler.
+ *
+ *   Access-Control-Allow-Headers: Authorization, Content-Type, X-Requested-With
+ *     The headers SPAs realistically send: bearer auth, JSON bodies, and the
+ *     X-Requested-With marker some HTTP clients add automatically. Anything
+ *     else (custom headers) lands in the preflight rejection at the browser,
+ *     which is the right shape — surface unexpected headers to the developer.
+ *
+ *   Access-Control-Max-Age: 86400
+ *     24h preflight cache. The route surface is stable (RFCs nailed down
+ *     years ago); long max-age cuts preflight chatter to ~1/day per SPA.
+ *
+ *   Access-Control-Expose-Headers: WWW-Authenticate
+ *     OAuth error responses ride in `WWW-Authenticate` (RFC 6750 §3); a
+ *     cross-origin SPA needs to read it to surface "invalid_token" /
+ *     "insufficient_scope" failure modes. Other headers (Content-Type,
+ *     Content-Length, Date, …) are CORS-safelisted by default — no need to
+ *     enumerate them.
+ *
+ * [Okta]: https://developer.okta.com/docs/concepts/api-access-management/#cors
+ * [Auth0]: https://auth0.com/docs/get-started/applications/configure-cors
+ * [Keycloak]: https://www.keycloak.org/docs/latest/server_admin/#con-web-origins-keycloak_server_administration_guide
+ */
+
+/**
+ * Static header set that's identical regardless of whether the caller had an
+ * Origin: the always-allow exposure of WWW-Authenticate so cross-origin
+ * SPAs can read RFC 6750 error responses.
+ *
+ * Origin / credentials / Vary are computed per-request in `applyCorsHeaders`
+ * + `corsPreflightResponse` because they depend on the request's Origin
+ * header.
+ */
+const CORS_STATIC_RESPONSE_HEADERS: Readonly<Record<string, string>> = {
+  "access-control-expose-headers": "WWW-Authenticate",
+};
+
+/**
+ * Static portion of the preflight headers — method/header allowlists +
+ * max-age. The dynamic Origin/credentials/Vary are computed in
+ * `corsPreflightResponse`.
+ */
+const CORS_STATIC_PREFLIGHT_HEADERS: Readonly<Record<string, string>> = {
+  "access-control-allow-methods": "GET, POST, OPTIONS",
+  "access-control-allow-headers": "Authorization, Content-Type, X-Requested-With",
+  "access-control-max-age": "86400",
+};
+
+/**
+ * Compute the per-request CORS origin + credentials + Vary triple.
+ *
+ * Browser caller (Origin header present): echo the origin, set
+ * `Allow-Credentials: true`, set `Vary: Origin` (cache correctness).
+ *
+ * Non-browser caller (no Origin): wildcard `*` + `Allow-Credentials: false`
+ * — safer when there's no specific origin to honor, matches the rc.17
+ * fallback shape for `curl`-style probes.
+ */
+function corsOriginHeaders(req: Request): Record<string, string> {
+  const origin = req.headers.get("origin");
+  if (origin) {
+    return {
+      "access-control-allow-origin": origin,
+      "access-control-allow-credentials": "true",
+      vary: "Origin",
+    };
+  }
+  return {
+    "access-control-allow-origin": "*",
+    "access-control-allow-credentials": "false",
+  };
+}
+
+/**
+ * Headers folded onto *actual* (non-preflight) responses for in-scope routes.
+ * Re-exported as a static lookup for tests + the rare caller that wants to
+ * spread the always-on subset (Expose-Headers) into a fresh Headers init.
+ *
+ * The dynamic Origin/Credentials/Vary triple is *not* here — it's a function
+ * of the incoming request's `Origin` header. Use `applyCorsHeaders(req,
+ * response)` to attach the full set.
+ */
+export const CORS_RESPONSE_HEADERS = CORS_STATIC_RESPONSE_HEADERS;
+
+/**
+ * Static portion of the preflight headers. Exported for tests that pin the
+ * method/header allowlist + max-age values. The per-request
+ * Origin/Credentials/Vary triple is computed in `corsPreflightResponse`.
+ */
+export const CORS_PREFLIGHT_HEADERS: Readonly<Record<string, string>> = {
+  ...CORS_STATIC_RESPONSE_HEADERS,
+  ...CORS_STATIC_PREFLIGHT_HEADERS,
+};
+
+/**
+ * Does this pathname participate in the public-CORS surface this module owns?
+ *
+ * Matches the OAuth surface (`/oauth/...`) only. The four `/.well-known/*`
+ * documents (oauth-authorization-server, parachute.json, jwks.json,
+ * parachute-revocation.json) are *also* part of the cross-origin contract,
+ * but they each carry their own CORS handling inline in `hub-server.ts` (a
+ * narrower `Allow-Methods: GET, OPTIONS` since they're read-only) and
+ * predate this module. Including them here would mean two CORS code paths
+ * disagreeing on the method list; leaving them in their existing block keeps
+ * one CORS posture per route family.
+ *
+ * Anything else — admin/API/content/login — stays same-origin-only and must
+ * NOT pass through this predicate.
+ *
+ * Prefix-match on `/oauth/` (with trailing slash) so the bare path `/oauth`
+ * doesn't match — there's no route at `/oauth` and the prefix would
+ * accidentally widen if anyone later mounts something there.
+ */
+export function isCorsAllowedRoute(pathname: string): boolean {
+  return pathname.startsWith("/oauth/");
+}
+
+/**
+ * 204 response for an OPTIONS preflight on an in-scope route.
+ *
+ * Browsers issue this before any non-simple cross-origin request (custom
+ * Content-Type, Authorization header, non-GET/POST/HEAD method). The response
+ * body is empty by spec; the browser only reads the headers.
+ *
+ * The Origin/Credentials/Vary triple is computed from the request's `Origin`
+ * header — see `corsOriginHeaders` for the per-request shape.
+ */
+export function corsPreflightResponse(req: Request): Response {
+  return new Response(null, {
+    status: 204,
+    headers: {
+      ...corsOriginHeaders(req),
+      ...CORS_STATIC_RESPONSE_HEADERS,
+      ...CORS_STATIC_PREFLIGHT_HEADERS,
+    },
+  });
+}
+
+/**
+ * Fold the CORS response headers onto an existing Response.
+ *
+ * Returns a *new* Response that shares the body but has the merged Headers.
+ * Existing headers on the input response take precedence — but the CORS
+ * headers don't typically collide with anything a handler would set, so in
+ * practice this just adds the three-to-four CORS headers.
+ *
+ * Why a new Response: Response.headers is immutable post-construction. We
+ * could mutate during the handler instead, but folding at the dispatcher
+ * level keeps the per-handler code free of CORS concerns and makes "which
+ * routes are CORS-friendly" a single-source-of-truth in `isCorsAllowedRoute`.
+ *
+ * The signature takes the request so the Origin echo + credentials posture
+ * can be computed per-call. The dispatcher in `hub-server.ts` already has
+ * the request in scope at every `applyCorsHeaders` call site.
+ */
+export function applyCorsHeaders(req: Request, response: Response): Response {
+  const merged = new Headers(response.headers);
+  const dynamic = corsOriginHeaders(req);
+  for (const [k, v] of Object.entries({ ...dynamic, ...CORS_STATIC_RESPONSE_HEADERS })) {
+    if (!merged.has(k)) merged.set(k, v);
+  }
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: merged,
+  });
+}

package/src/hub-db.ts

@@ -217,6 +217,36 @@ const MIGRATIONS: readonly Migration[] = [
       );
     `,
   },
+  {
+    version: 8,
+    sql: `
+      -- Multi-user Phase 1 (hub#252, design 2026-05-20-multi-user-phase-1.md).
+      -- Two columns on \`users\`:
+      --
+      --   * password_changed (INTEGER 0/1) — tracks whether a user has
+      --     changed their password since account creation. The admin-creates-
+      --     user flow (PR 2) lands new accounts with 0; the user's forced
+      --     change-password flow (PR 3) flips it to 1. SQLite has no native
+      --     BOOL, so 0/1 + a TS helper in users.ts handles the translation.
+      --   * assigned_vault (TEXT, nullable) — the vault instance name the
+      --     user is pinned to (Phase 1 is single-vault-per-user). NULL means
+      --     "no per-vault restriction" — the wizard's first admin and any
+      --     other admin-role user. The OAuth issuer (PR 4) reads this at
+      --     mint time to narrow the token's vault scope. No FK: vault names
+      --     resolve through services.json, not a DB row.
+      --
+      -- Backfill: every existing user pre-dates this migration. The only
+      -- accounts that could exist are the wizard's first admin (chose their
+      -- own password via the wizard form) or env-seeded admins (operator
+      -- baked the password into PARACHUTE_INITIAL_ADMIN_PASSWORD). Both
+      -- already-chosen-by-the-account-holder paths, so flip every existing
+      -- row to password_changed=1 — no spurious force-change on first sign-
+      -- in for already-bootstrapped hubs.
+      ALTER TABLE users ADD COLUMN password_changed INTEGER NOT NULL DEFAULT 0;
+      ALTER TABLE users ADD COLUMN assigned_vault TEXT;
+      UPDATE users SET password_changed = 1;
+    `,
+  },
 ];
 
 export function openHubDb(path: string = hubDbPath()): Database {

package/src/hub-server.ts

@@ -42,9 +42,10 @@
  *   /admin/vault-admin-token/<n>  (GET)        → per-vault bearer mint (cookie-gated)
  *   /api/me                       (GET)        → who-am-I (session+CSRF or hasSession:false)
  *   /api/modules                  (GET)        → curated + installed module catalog (host:auth)
+ *   /api/modules/channel          (PUT)        → operator channel toggle (host:admin)
  *   /api/modules/:short/install   (POST)       → bun add + spawn (async op)
  *   /api/modules/:short/restart   (POST)       → supervisor restart (sync)
- *   /api/modules/:short/upgrade   (POST)       → bun add @latest + restart (async op)
+ *   /api/modules/:short/upgrade   (POST)       → bun add @<channel> + restart (async op)
  *   /api/modules/:short/uninstall (POST)       → stop child + bun remove + drop row (sync)
  *   /api/modules/operations/:id   (GET)        → poll async op status
  *   /api/auth/mint-token          (POST)       → CLI/automation token mint (bearer)
@@ -54,8 +55,15 @@
  *   /api/grants/<client_id>       (DELETE)     → revoke a single OAuth grant
  *   /api/oauth/clients/<id>       (GET)        → OAuth client details
  *   /api/oauth/clients/<id>/approve (POST)     → flip a pending client to approved
+ *   /api/users                    (GET + POST) → list / create user (host:admin)
+ *   /api/users/vaults             (GET)        → vault-name list for assigned-vault picker (host:admin)
+ *   /api/users/<id>               (DELETE)     → hard-delete user + revoke tokens (host:admin)
  *   /login                        (GET + POST) → operator password login
  *   /logout                       (POST)       → end admin session
+ *   /account/change-password      (GET + POST) → user self-service change-password
+ *                                                 (force-redirect target for users
+ *                                                 with password_changed=false; also
+ *                                                 reachable directly to rotate)
  *   /admin/config*                             → 301 → /admin/vaults (legacy
  *                                                portal retired post-SPA-rework)
  *
@@ -102,6 +110,7 @@ import {
 import { handleHostAdminToken } from "./admin-host-admin-token.ts";
 import { handleVaultAdminToken } from "./admin-vault-admin-token.ts";
 import { handleCreateVault } from "./admin-vaults.ts";
+import { handleAccountChangePasswordGet, handleAccountChangePasswordPost } from "./api-account.ts";
 import { handleApiMe } from "./api-me.ts";
 import { handleApiMintToken } from "./api-mint-token.ts";
 import {
@@ -113,11 +122,18 @@ import {
   handleUpgrade,
   parseModulesPath,
 } from "./api-modules-ops.ts";
-import { handleApiModules } from "./api-modules.ts";
+import { handleApiModules, handleApiModulesChannel } from "./api-modules.ts";
 import { REVOCATION_LIST_MOUNT, handleRevocationList } from "./api-revocation-list.ts";
 import { handleApiRevokeToken } from "./api-revoke-token.ts";
 import { handleApiTokens } from "./api-tokens.ts";
+import {
+  handleCreateUser,
+  handleDeleteUser,
+  handleListUsers,
+  handleListVaults,
+} from "./api-users.ts";
 import { CONFIG_DIR, SERVICES_MANIFEST_PATH } from "./config.ts";
+import { applyCorsHeaders, corsPreflightResponse, isCorsAllowedRoute } from "./cors.ts";
 import { ensureCsrfToken } from "./csrf.ts";
 import { readExposeState } from "./expose-state.ts";
 import { HUB_DEFAULT_PORT, HUB_SVC, clearHubPort, writeHubPort } from "./hub-control.ts";
@@ -964,6 +980,22 @@ export function hubFetch(
       });
     }
 
+    // CORS preflight for the public OAuth + discovery surface. Browsers
+    // issue OPTIONS before any non-simple cross-origin request — third-party
+    // SPAs hitting `/oauth/register` (RFC 7591 DCR), `/oauth/token`,
+    // `/.well-known/oauth-authorization-server`, etc. Handling this above
+    // the route table means an OPTIONS to e.g. `/oauth/register` doesn't
+    // hit the method-not-allowed branch in the handler — the preflight is a
+    // CORS-protocol artifact, not a "real" request to the endpoint. The
+    // single `isCorsAllowedRoute` predicate is the source of truth for
+    // which paths carry wildcard-CORS; see `src/cors.ts` for the rationale.
+    // Out-of-scope paths (`/api/*`, `/admin/*`, `/login`, `/account/*`,
+    // `/vault/*`, generic service proxy) fall through and OPTIONS reaches
+    // whatever default the downstream handler enforces (typically 405).
+    if (req.method === "OPTIONS" && isCorsAllowedRoute(pathname)) {
+      return corsPreflightResponse(req);
+    }
+
     // Platform health check (Render, Fly, Kubernetes, etc.). Plain JSON,
     // no DB required — the route reports liveness, not readiness. Anything
     // more invasive (DB ping, schema check) would let a transient lock turn
@@ -1243,11 +1275,22 @@ export function hubFetch(
       return new Response(res.body, { status: res.status, headers: merged });
     }
 
+    // OAuth surface — every handler return is wrapped in `applyCorsHeaders`
+    // so third-party SPAs can fetch these endpoints cross-origin (the entire
+    // point of OAuth DCR: arbitrary SPAs register → authorize → exchange
+    // tokens). Preflight OPTIONS already returned at the top of dispatch.
+    // See `src/cors.ts` for the wildcard-origin rationale.
     if (pathname === "/oauth/authorize") {
-      if (!getDb) return dbNotConfigured();
-      if (req.method === "GET") return handleAuthorizeGet(getDb(), req, oauthDeps(req));
-      if (req.method === "POST") return handleAuthorizePost(getDb(), req, oauthDeps(req));
-      return new Response("method not allowed", { status: 405 });
+      if (!getDb) return applyCorsHeaders(req, dbNotConfigured());
+      if (req.method === "GET") {
+        // handleAuthorizeGet is sync (returns Response, not Promise<Response>).
+        // handleAuthorizePost is async — keep the await on POST only.
+        return applyCorsHeaders(req, handleAuthorizeGet(getDb(), req, oauthDeps(req)));
+      }
+      if (req.method === "POST") {
+        return applyCorsHeaders(req, await handleAuthorizePost(getDb(), req, oauthDeps(req)));
+      }
+      return applyCorsHeaders(req, new Response("method not allowed", { status: 405 }));
     }
 
     // Inline approve form for the operator-driven pending-client flow (#208).
@@ -1255,27 +1298,35 @@ export function hubFetch(
     // by handleAuthorizeGet when the operator hits a pending client. Three
     // gates inside the handler: CSRF, active session, same-origin Origin.
     if (pathname === "/oauth/authorize/approve") {
-      if (!getDb) return dbNotConfigured();
-      if (req.method !== "POST") return new Response("method not allowed", { status: 405 });
-      return handleApproveClientPost(getDb(), req, oauthDeps(req));
+      if (!getDb) return applyCorsHeaders(req, dbNotConfigured());
+      if (req.method !== "POST") {
+        return applyCorsHeaders(req, new Response("method not allowed", { status: 405 }));
+      }
+      return applyCorsHeaders(req, await handleApproveClientPost(getDb(), req, oauthDeps(req)));
     }
 
     if (pathname === "/oauth/token") {
-      if (!getDb) return dbNotConfigured();
-      if (req.method !== "POST") return new Response("method not allowed", { status: 405 });
-      return handleToken(getDb(), req, oauthDeps(req));
+      if (!getDb) return applyCorsHeaders(req, dbNotConfigured());
+      if (req.method !== "POST") {
+        return applyCorsHeaders(req, new Response("method not allowed", { status: 405 }));
+      }
+      return applyCorsHeaders(req, await handleToken(getDb(), req, oauthDeps(req)));
     }
 
     if (pathname === "/oauth/register") {
-      if (!getDb) return dbNotConfigured();
-      if (req.method !== "POST") return new Response("method not allowed", { status: 405 });
-      return handleRegister(getDb(), req, oauthDeps(req));
+      if (!getDb) return applyCorsHeaders(req, dbNotConfigured());
+      if (req.method !== "POST") {
+        return applyCorsHeaders(req, new Response("method not allowed", { status: 405 }));
+      }
+      return applyCorsHeaders(req, await handleRegister(getDb(), req, oauthDeps(req)));
     }
 
     if (pathname === "/oauth/revoke") {
-      if (!getDb) return dbNotConfigured();
-      if (req.method !== "POST") return new Response("method not allowed", { status: 405 });
-      return handleRevoke(getDb(), req, oauthDeps(req));
+      if (!getDb) return applyCorsHeaders(req, dbNotConfigured());
+      if (req.method !== "POST") {
+        return applyCorsHeaders(req, new Response("method not allowed", { status: 405 }));
+      }
+      return applyCorsHeaders(req, await handleRevoke(getDb(), req, oauthDeps(req)));
     }
 
     if (pathname === "/vaults") {
@@ -1335,6 +1386,18 @@ export function hubFetch(
       return handleApiModules(req, modulesDeps);
     }
 
+    // Channel toggle (hub#275) — pre-empts the /api/modules/:short/*
+    // routes below so `/api/modules/channel` doesn't accidentally match
+    // `parseModulesPath` (which would reject it as a non-curated short
+    // anyway, but precedence makes the intent explicit).
+    if (pathname === "/api/modules/channel") {
+      if (!getDb) return dbNotConfigured();
+      return handleApiModulesChannel(req, {
+        db: getDb(),
+        issuer: oauthDeps(req).issuer,
+      });
+    }
+
     // Module operation poll surface — pre-empts the /api/modules/:short/*
     // routes below so `/api/modules/operations/<uuid>` doesn't accidentally
     // match a parseModulesPath("/operations") and fall through.
@@ -1472,6 +1535,45 @@ export function hubFetch(
       });
     }
 
+    // Multi-user Phase 1 admin endpoints (hub#252, design 2026-05-20).
+    // `/api/users` collection (GET list / POST create) and
+    // `/api/users/vaults` for the assigned-vault picker. Per-id route
+    // `/api/users/:id` (DELETE only — Phase 1 doesn't ship edit) is
+    // handled by the `startsWith("/api/users/")` branch below, with the
+    // `/api/users/vaults` sub-path pre-empted *before* the catch-all so
+    // a literal `vaults` segment can't be mistaken for a user id.
+    if (pathname === "/api/users") {
+      if (!getDb) return dbNotConfigured();
+      const usersDeps = {
+        db: getDb(),
+        issuer: oauthDeps(req).issuer,
+        manifestPath,
+      };
+      if (req.method === "GET") return handleListUsers(req, usersDeps);
+      if (req.method === "POST") return handleCreateUser(req, usersDeps);
+      return new Response("method not allowed", { status: 405 });
+    }
+    if (pathname === "/api/users/vaults") {
+      if (!getDb) return dbNotConfigured();
+      return handleListVaults(req, {
+        db: getDb(),
+        issuer: oauthDeps(req).issuer,
+        manifestPath,
+      });
+    }
+    if (pathname.startsWith("/api/users/")) {
+      if (!getDb) return dbNotConfigured();
+      const id = decodeURIComponent(pathname.slice("/api/users/".length));
+      if (!id || id.includes("/")) {
+        return new Response("not found", { status: 404 });
+      }
+      return handleDeleteUser(req, id, {
+        db: getDb(),
+        issuer: oauthDeps(req).issuer,
+        manifestPath,
+      });
+    }
+
     // Canonical login/logout. The handlers themselves are unchanged from
     // when they lived at /admin/login + /admin/logout; the rename surfaced
     // via #231-followup so the URL reflects the surface's actual scope
@@ -1491,6 +1593,24 @@ export function hubFetch(
       return handleAdminLogoutPost(getDb(), req);
     }
 
+    // Multi-user Phase 1 PR 3 — user self-service change-password surface
+    // (hub#252, design §sign-in flow change). Both GET (render form) and
+    // POST (apply change) require a session cookie. The handler itself
+    // does the session check + 302 to /login when missing — same posture
+    // as the rest of /account/* will use as Phase 2 broadens this prefix.
+    //
+    // This route is intentionally NOT gated by `password_changed === false`
+    // — that's only the *redirect* path from /login. A signed-in user with
+    // `password_changed: true` can still navigate here to rotate their
+    // password (design §"Direct navigation").
+    if (pathname === "/account/change-password") {
+      if (!getDb) return dbNotConfigured();
+      const accountDeps = { db: getDb() };
+      if (req.method === "GET") return handleAccountChangePasswordGet(req, accountDeps);
+      if (req.method === "POST") return handleAccountChangePasswordPost(req, accountDeps);
+      return new Response("method not allowed", { status: 405 });
+    }
+
     // Legacy `/admin/config` (server-rendered module-config portal, #46)
     // retired post-SPA-rework. 301 → the SPA home so any bookmark or stale
     // post-login redirect lands somewhere useful. The route stays here in

package/src/hub-settings.ts

@@ -41,7 +41,18 @@ export type HubSettingKey =
   // install-command snippet without re-deriving from services.json
   // (vault's first-boot may write its own paths shape that the wizard
   // can't trust to match `<name>` exactly until the spawn settles).
-  | "setup_vault_name";
+  | "setup_vault_name"
+  // hub#275: which dist-tag the runtime module installer uses
+  // (`bun add -g <pkg>@<channel>`). `"latest"` (default) tracks the
+  // stable channel; `"rc"` follows the release-candidate chain so
+  // operators on the rc cadence can pull pre-release builds without
+  // hand-editing the install command. Seeded from
+  // `PARACHUTE_MODULE_CHANNEL` on first read (operator can ship a fresh
+  // box with the env var set and have the row land with their preferred
+  // channel); after the first seed the row is source of truth and the
+  // env var is ignored — admin must use the SPA toggle (or
+  // `PUT /api/modules/channel`) to change channel.
+  | "module_install_channel";
 
 export type SetupExposeMode = "localhost" | "tailnet" | "public";
 
@@ -160,3 +171,89 @@ export function consumeFirstClientAutoApproveWindow(
   deleteSetting(db, "pending_first_client_auto_approve_until");
   return true;
 }
+
+// --- domain helpers: module install channel ------------------------------
+
+/**
+ * Which dist-tag `bun add -g <pkg>@<channel>` should use. `"latest"`
+ * tracks the stable channel; `"rc"` tracks pre-release builds. Exposed
+ * here (not buried in api-modules-ops) because the admin SPA reads it
+ * via `/api/modules` and writes it via `/api/modules/channel` — the
+ * setting is the cross-cutting source of truth, the install path is
+ * one consumer.
+ */
+export type ModuleInstallChannel = "latest" | "rc";
+
+/** Exported so the API handler + the SPA toggle can share validation. */
+export const MODULE_INSTALL_CHANNELS: readonly ModuleInstallChannel[] = ["latest", "rc"];
+
+export function isModuleInstallChannel(s: unknown): s is ModuleInstallChannel {
+  return typeof s === "string" && MODULE_INSTALL_CHANNELS.includes(s as ModuleInstallChannel);
+}
+
+/**
+ * Env var that seeds `module_install_channel` on first read. Read only
+ * when the hub_settings row is absent — once the row exists, the env
+ * var is ignored on subsequent boots (admin must use the SPA toggle or
+ * the API to change channel). Lets Aaron's fresh-machine deploys ship
+ * with `PARACHUTE_MODULE_CHANNEL=rc` baked into the platform's env
+ * config without baking the channel into the binary or first-boot.
+ */
+export const PARACHUTE_MODULE_CHANNEL_ENV = "PARACHUTE_MODULE_CHANNEL";
+
+/** Fallback when nothing else is set — the stable channel. */
+export const DEFAULT_MODULE_INSTALL_CHANNEL: ModuleInstallChannel = "latest";
+
+/**
+ * Read the configured module install channel. On first call (no row in
+ * hub_settings), seeds from `process.env.PARACHUTE_MODULE_CHANNEL` if
+ * valid, otherwise defaults to `"latest"` (an invalid env value warns
+ * + still falls back to "latest"). After that first seed, the
+ * hub_settings row is source of truth.
+ *
+ * The `env` + `warn` knobs are test seams — production uses
+ * `process.env` + `console.warn`. Tests inject a deterministic shape so
+ * the warn-on-invalid branch can be asserted without console-capture.
+ */
+export function getModuleInstallChannel(
+  db: Database,
+  opts: {
+    env?: NodeJS.ProcessEnv;
+    warn?: (msg: string) => void;
+  } = {},
+): ModuleInstallChannel {
+  const existing = getSetting(db, "module_install_channel");
+  if (existing !== undefined) {
+    // Row already seeded — trust it. If somehow corrupted (manual sqlite
+    // edit, schema drift), fall back to "latest" silently rather than
+    // crashing the install path. Re-seeding the row is left to the
+    // admin's explicit setModuleInstallChannel call.
+    if (isModuleInstallChannel(existing)) return existing;
+    return DEFAULT_MODULE_INSTALL_CHANNEL;
+  }
+  const env = opts.env ?? process.env;
+  const warn = opts.warn ?? ((msg: string) => console.warn(msg));
+  const fromEnv = env[PARACHUTE_MODULE_CHANNEL_ENV];
+  let seed: ModuleInstallChannel = DEFAULT_MODULE_INSTALL_CHANNEL;
+  if (typeof fromEnv === "string" && fromEnv.length > 0) {
+    if (isModuleInstallChannel(fromEnv)) {
+      seed = fromEnv;
+    } else {
+      warn(
+        `[hub-settings] ${PARACHUTE_MODULE_CHANNEL_ENV}="${fromEnv}" is not a valid channel — expected one of ${MODULE_INSTALL_CHANNELS.join(", ")}. Falling back to "${DEFAULT_MODULE_INSTALL_CHANNEL}".`,
+      );
+    }
+  }
+  setSetting(db, "module_install_channel", seed);
+  return seed;
+}
+
+/**
+ * Write the module install channel. Validated by the caller (the API
+ * handler + the SPA already constrain to the union); the function
+ * itself only accepts the typed shape, so a TypeScript-clean callsite
+ * can't write a malformed value.
+ */
+export function setModuleInstallChannel(db: Database, channel: ModuleInstallChannel): void {
+  setSetting(db, "module_install_channel", channel);
+}