@openparachute/hub 0.5.10-rc.6 → 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

@@ -193,6 +193,60 @@ const MIGRATIONS: readonly Migration[] = [
       CREATE INDEX tokens_subject ON tokens (subject) WHERE subject IS NOT NULL;
     `,
   },
+  {
+    version: 7,
+    sql: `
+      -- Hub-level key/value settings (hub#268). Used by:
+      --   * setup_expose_mode — operator's "how will this hub be reached?"
+      --     choice from the first-boot wizard expose step. Values:
+      --     'localhost' | 'tailnet' | 'public'.
+      --   * pending_first_client_auto_approve_until — ISO-8601 timestamp
+      --     set when the wizard finishes; first OAuth client registration
+      --     within the window is auto-approved + the row cleared (single
+      --     use). Absent / past-due means the standard pending-approval
+      --     flow applies.
+      --
+      -- Single-row-per-key schema. updated_at lets us age out stale
+      -- entries if a future pattern needs it; nothing currently relies on
+      -- it. Bare KV — no audit log, no history — these are hub-local
+      -- operator preferences, not user-facing data.
+      CREATE TABLE hub_settings (
+        key TEXT PRIMARY KEY,
+        value TEXT NOT NULL,
+        updated_at TEXT NOT NULL
+      );
+    `,
+  },
+  {
+    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";
@@ -149,7 +165,9 @@ import { findActiveSession } from "./sessions.ts";
 import {
   type SetupWizardDeps,
   handleSetupAccountPost,
+  handleSetupExposePost,
   handleSetupGet,
+  handleSetupInstallPost,
   handleSetupVaultPost,
 } from "./setup-wizard.ts";
 import { getAllPublicKeys } from "./signing-keys.ts";
@@ -962,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
@@ -1010,6 +1044,20 @@ export function hubFetch(
         if (req.method !== "POST") return new Response("method not allowed", { status: 405 });
         return handleSetupVaultPost(req, wizardDeps);
       }
+      if (pathname === "/admin/setup/expose") {
+        if (req.method !== "POST") return new Response("method not allowed", { status: 405 });
+        return handleSetupExposePost(req, wizardDeps);
+      }
+      // hub#272 Item B: post-wizard direct module-install POSTs from
+      // the done-screen "What's next?" tiles. Path shape is
+      // `/admin/setup/install/<short>`; the handler rejects on
+      // unknown shorts, on `vault` (the wizard's own step owns that),
+      // and on missing session/CSRF — same gates as the vault POST.
+      if (pathname.startsWith("/admin/setup/install/")) {
+        if (req.method !== "POST") return new Response("method not allowed", { status: 405 });
+        const short = pathname.slice("/admin/setup/install/".length);
+        return handleSetupInstallPost(req, short, wizardDeps);
+      }
       return new Response("not found", { status: 404 });
     }
 
@@ -1103,9 +1151,17 @@ export function hubFetch(
       // cross-origin from their own loopback port. Wildcard CORS is the
       // shape it needs. Browsers send an OPTIONS preflight when the request
       // adds non-simple headers; answer it with 204 + the same allow-list.
+      //
+      // `cache-control: no-store` matters here: the discovery page (`/`)
+      // fetches this doc and renders Service tiles from it; without
+      // no-store, the browser's HTTP cache returns the stale services list
+      // the next time the operator navigates back to `/` after installing
+      // a module via the admin SPA. The doc is small and built per-request
+      // anyway, so giving up cacheability has no real cost (hub#268 Item 1).
       const corsHeaders = {
         "access-control-allow-origin": "*",
         "access-control-allow-methods": "GET, OPTIONS",
+        "cache-control": "no-store",
       };
       if (req.method === "OPTIONS") {
         return new Response(null, { status: 204, headers: corsHeaders });
@@ -1219,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).
@@ -1231,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") {
@@ -1311,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.
@@ -1448,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
@@ -1467,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