@openparachute/hub 0.7.4-rc.8 → 0.7.4

package/src/api-me.ts

@@ -14,7 +14,12 @@
  * Response shape:
  *
  *   { hasSession: false }
- *   { hasSession: true, user: { id, displayName }, csrf: "<token>" }
+ *   { hasSession: true, user: { id, displayName }, csrf: "<token>",
+ *     two_factor_enabled: boolean }
+ *
+ * `two_factor_enabled` (hub#85) lets the SPA's "My account" page render the
+ * 2FA status without a separate read. It reflects `users.totp_secret` being
+ * set for the signed-in user.
  *
  * `displayName` is the user's `username` today — there's no separate
  * display-name field on the User shape. Surfaced under a different key
@@ -39,6 +44,7 @@
 import type { Database } from "bun:sqlite";
 import { ensureCsrfToken } from "./csrf.ts";
 import { findActiveSession } from "./sessions.ts";
+import { isTotpEnrolled } from "./two-factor-store.ts";
 import { getUserById } from "./users.ts";
 
 export interface ApiMeDeps {
@@ -59,7 +65,9 @@ interface SignedInUser {
  * that mixes states — e.g. `{ hasSession: false, user: staleUser }`
  * fails at the type-check, not just at code-review.
  */
-type ApiMeResponse = { hasSession: false } | { hasSession: true; user: SignedInUser; csrf: string };
+type ApiMeResponse =
+  | { hasSession: false }
+  | { hasSession: true; user: SignedInUser; csrf: string; two_factor_enabled: boolean };
 
 export function handleApiMe(req: Request, deps: ApiMeDeps): Response {
   if (req.method !== "GET") {
@@ -99,6 +107,7 @@ export function handleApiMe(req: Request, deps: ApiMeDeps): Response {
       displayName: user.username,
     },
     csrf: csrf.token,
+    two_factor_enabled: isTotpEnrolled(deps.db, user.id),
   };
   return new Response(JSON.stringify(body), { status: 200, headers });
 }

package/src/api-mint-token.ts

@@ -87,6 +87,17 @@ export interface ApiMintTokenDeps {
   db: Database;
   /** Hub origin — written into the JWT `iss` of minted tokens AND used to validate the bearer. */
   issuer: string;
+  /**
+   * SET of origins the hub legitimately answers on (loopback ∪ expose-state ∪
+   * platform ∪ per-request `issuer`), built via `buildHubBoundOrigins`. The
+   * caller's bearer `iss` is validated against THIS set rather than the single
+   * `issuer`, so a credential minted under a still-valid prior origin keeps
+   * minting across an origin switch (hub#516 parity — the live "mint refused"
+   * after `set-origin`). Minted tokens still carry the single canonical
+   * `issuer` as their `iss`. Absent → falls back to `[issuer]` (the prior
+   * strict per-request behavior; tests/non-HTTP callers unaffected).
+   */
+  knownIssuers?: readonly string[];
   /**
    * Names of vault instances currently registered in services.json (item D /
    * hub#450). When provided, a `vault:<name>:admin` mint whose `<name>` is not
@@ -133,7 +144,11 @@ export async function handleApiMintToken(req: Request, deps: ApiMintTokenDeps):
   let bearerSub: string;
   let bearerScopes: string[];
   try {
-    const validated = await validateAccessToken(deps.db, bearer, deps.issuer);
+    const validated = await validateAccessToken(
+      deps.db,
+      bearer,
+      deps.knownIssuers ?? [deps.issuer],
+    );
     const sub = validated.payload.sub;
     if (typeof sub !== "string" || sub.length === 0) {
       return jsonError(401, "unauthenticated", "bearer token has no sub claim");

package/src/api-modules.ts

@@ -42,6 +42,9 @@
  */
 
 import type { Database } from "bun:sqlite";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { compareVersions } from "./commands/upgrade.ts";
 import { validateHostAdminToken } from "./host-admin-token-validation.ts";
 import {
   type ModuleInstallChannel,
@@ -178,6 +181,40 @@ export interface ApiModulesDeps {
    * (hub#342 — drives the admin SPA Modules page's "Open" button).
    */
   readModuleManifest?: (installDir: string) => Promise<ModuleManifest | null>;
+  /**
+   * Read the LIVE installed version of a module from its install dir's
+   * `package.json` `version` (hub#243). The services.json `version` field is a
+   * CACHE the module writes on its own boot — on the bun-linked dev path it
+   * goes stale the moment the checkout is rebuilt to a newer version without a
+   * restart that re-stamps services.json. The admin Modules view reads
+   * `installed_version` straight from that cache, so it can show a stale version
+   * (the live symptom: services.json said 0.5.4-rc.15 while the linked checkout
+   * was already 0.6.4-rc.15). When this resolves a version, it WINS over the
+   * services.json cache for the `installed_version` field so the operator sees
+   * what's actually on disk. Returns null on any failure (no install dir,
+   * missing/unreadable package.json, no version) → fall back to the
+   * services.json cache, which is the only source for a not-yet-booted module.
+   *
+   * Production reads `<installDir>/package.json`; tests inject a fake.
+   */
+  readInstalledVersion?: (installDir: string) => string | null;
+}
+
+/**
+ * Default `readInstalledVersion`. Reads `<installDir>/package.json`'s `version`
+ * — the authoritative live version of a module's code on disk, which the
+ * bun-linked dev path keeps current while the services.json cache can lag
+ * (hub#243). Returns null on any failure so the caller falls back to the
+ * services.json `version`.
+ */
+export function defaultReadInstalledVersion(installDir: string): string | null {
+  try {
+    const raw = readFileSync(join(installDir, "package.json"), "utf8");
+    const parsed = JSON.parse(raw) as { version?: unknown };
+    return typeof parsed.version === "string" && parsed.version.length > 0 ? parsed.version : null;
+  } catch {
+    return null;
+  }
 }
 
 /**
@@ -239,6 +276,24 @@ interface ModuleWireShape {
   installed: boolean;
   installed_version: string | null;
   latest_version: string | null;
+  /**
+   * Whether the channel-resolved `latest_version` is a REAL upgrade — i.e.
+   * STRICTLY NEWER than `installed_version` under semver ordering (hub#243).
+   * Computed server-side via `compareVersions` so the rc/prerelease ordering is
+   * correct and there's ONE tested source of truth (the SPA used to derive this
+   * client-side with a string `!==`, which framed a *downgrade* as an upgrade:
+   * an rc operator on `0.6.4-rc.15` was offered an "upgrade" to the older
+   * `@latest` `0.6.3` purely because the two strings differed).
+   *
+   * `false` when: not installed · no `latest_version` (probe failed) · target ≤
+   * installed (same or older — incl. the rc→older-stable downgrade) · either
+   * version is unparseable (`compareVersions` returns null → fail-closed: don't
+   * offer a move we can't verify is forward). `true` ONLY when the target
+   * parses AND sorts strictly above installed — so `0.6.4-rc.15` → stable
+   * `0.6.4` IS an upgrade (stable > its own rc per semver §11.4.3), but
+   * `0.6.4-rc.15` → `0.6.3` is NOT.
+   */
+  upgrade_available: boolean;
   supervisor_status: ModuleState["status"] | null;
   pid: number | null;
   /**
@@ -451,6 +506,8 @@ export async function handleApiModules(req: Request, deps: ApiModulesDeps): Prom
   // Lenient read so a single bad row written by a buggy module install
   // (e.g. app@0.2.0-rc.4) doesn't take down /api/modules — see hub#406.
   const manifest = readManifestLenient(deps.manifestPath);
+  // Live on-disk version reader (hub#243) — see `defaultReadInstalledVersion`.
+  const readInstalledVersion = deps.readInstalledVersion ?? defaultReadInstalledVersion;
   const installedByShort = new Map<
     string,
     {
@@ -476,6 +533,18 @@ export async function handleApiModules(req: Request, deps: ApiModulesDeps): Prom
       uis?: Record<string, UiSubUnit>;
       mountPath?: string;
     } = { version: entry.version };
+    // Prefer the LIVE on-disk version over the services.json cache when we can
+    // read it (hub#243). `entry.version` is a cache the module stamps on its own
+    // boot; on the bun-linked dev path it lags after a rebuild-without-restart,
+    // so the admin view shows a stale "current" (the live symptom: cache said
+    // 0.5.4-rc.15 while the linked checkout was already 0.6.4-rc.15). The
+    // module's `<installDir>/package.json` `version` is authoritative for the
+    // code actually on disk. Falls back to the cache when there's no installDir
+    // or the package.json can't be read (e.g. a not-yet-booted seed row).
+    if (entry.installDir !== undefined) {
+      const live = readInstalledVersion(entry.installDir);
+      if (live !== null) value.version = live;
+    }
     if (entry.installDir !== undefined) value.installDir = entry.installDir;
     if (entry.uis !== undefined) value.uis = entry.uis;
     // First non-`.parachute` path is the module's user-facing mount
@@ -622,6 +691,10 @@ export async function handleApiModules(req: Request, deps: ApiModulesDeps): Prom
       installed: installed !== undefined,
       installed_version: installed?.version ?? null,
       latest_version: latestByShort.get(short) ?? null,
+      upgrade_available: isUpgradeAvailable(
+        installed?.version ?? null,
+        latestByShort.get(short) ?? null,
+      ),
       supervisor_status: state?.status ?? null,
       pid: state?.pid ?? null,
       supervisor_start_error: state?.startError ?? null,
@@ -644,6 +717,9 @@ export async function handleApiModules(req: Request, deps: ApiModulesDeps): Prom
 
   // Every supervised module's run-state — curated AND non-curated (hub#539).
   // Built from the same supervisor.list() snapshot already in `stateByShort`.
+  // `installed_version` here inherits the live-on-disk override already applied
+  // to `installedByShort[].version` in the manifest loop above (hub#243), so the
+  // `supervised` array reports the same corrected version as the `modules` rows.
   const supervised: SupervisedSnapshotWire[] = Array.from(stateByShort.values()).map((s) => ({
     short: s.short,
     installed: installedByShort.has(s.short),
@@ -683,6 +759,15 @@ export const API_MODULES_CHANNEL_REQUIRED_SCOPE = "parachute:host:admin";
 export interface ApiModulesChannelDeps {
   db: Database;
   issuer: string;
+  /**
+   * SET of origins the hub answers on (loopback ∪ expose-state ∪ platform ∪
+   * per-request `issuer`), built via `buildHubBoundOrigins` — same posture as
+   * {@link ApiModulesDeps.knownIssuers}. The bearer's `iss` is validated
+   * against THIS set rather than the single `issuer`, so the operator token
+   * (public `iss` after `expose`) is accepted on loopback. Absent → falls back
+   * to `[issuer]` (the prior strict per-request behavior).
+   */
+  knownIssuers?: readonly string[];
 }
 
 export async function handleApiModulesChannel(
@@ -705,7 +790,11 @@ export async function handleApiModulesChannel(
 
   // Bearer validation + scope check.
   try {
-    const validated = await validateAccessToken(deps.db, bearer, deps.issuer);
+    const validated = await validateAccessToken(
+      deps.db,
+      bearer,
+      deps.knownIssuers ?? [deps.issuer],
+    );
     if (typeof validated.payload.sub !== "string" || validated.payload.sub.length === 0) {
       return jsonError(401, "unauthenticated", "bearer token has no sub claim");
     }
@@ -842,6 +931,35 @@ function toUisWireShape(uis: Record<string, UiSubUnit> | undefined): UiSubUnitWi
   }));
 }
 
+/**
+ * Whether `latest` is a REAL upgrade over `installed` — strictly newer under
+ * semver ordering (hub#243). The single tested source of truth for the
+ * "upgrade available?" decision, shared by the wire shape's `upgrade_available`
+ * field and (transitively) the admin SPA's Upgrade button.
+ *
+ * Returns `false` unless BOTH versions parse AND `latest` sorts strictly above
+ * `installed`:
+ *   - no installed version (not installed) → false.
+ *   - no latest version (probe failed / unknown package) → false.
+ *   - `compareVersions` can't parse either side → false (FAIL-CLOSED: never
+ *     offer a move we can't prove is forward).
+ *   - target ≤ installed → false. This is the load-bearing downgrade guard:
+ *     an rc operator on `0.6.4-rc.15` whose channel resolves `latest_version`
+ *     to the OLDER `@latest` `0.6.3` is NOT offered an "upgrade" (the live bug
+ *     — a downgrade framed as an upgrade by the old string `!==`).
+ *
+ * Reuses `commands/upgrade.ts:compareVersions`, the same comparator the CLI
+ * `parachute upgrade` downgrade guard uses, so the SPA offer and the CLI guard
+ * can't disagree about rc/prerelease ordering. Note `0.6.4-rc.15` → stable
+ * `0.6.4` IS strictly-newer (stable > its own rc per semver §11.4.3), so a real
+ * rc→its-stable promotion still surfaces as an upgrade.
+ */
+export function isUpgradeAvailable(installed: string | null, latest: string | null): boolean {
+  if (installed === null || latest === null) return false;
+  const cmp = compareVersions(latest, installed);
+  return cmp !== null && cmp > 0;
+}
+
 /**
  * Reset the in-memory `latest_version` cache. Tests call this between
  * runs to prevent state leakage across test cases; production never

package/src/api-revoke-token.ts

@@ -73,6 +73,15 @@ export interface ApiRevokeTokenDeps {
   db: Database;
   /** Hub origin — used to validate the bearer's `iss`. */
   issuer: string;
+  /**
+   * SET of origins the hub answers on (loopback ∪ expose-state ∪ platform ∪
+   * per-request `issuer`), built via `buildHubBoundOrigins`. The bearer's
+   * `iss` is validated against THIS set rather than the single `issuer`, so a
+   * credential minted under a still-valid prior origin keeps working across an
+   * origin switch (hub#516 parity). Absent → falls back to `[issuer]` (the
+   * prior strict per-request behavior; tests/non-HTTP callers unaffected).
+   */
+  knownIssuers?: readonly string[];
   /** Test seam for time. */
   now?: () => Date;
 }
@@ -102,7 +111,11 @@ export async function handleApiRevokeToken(
   // 2. Bearer validation (signature, issuer, expiry, hub-side revocation).
   let bearerScopes: string[];
   try {
-    const validated = await validateAccessToken(deps.db, bearer, deps.issuer);
+    const validated = await validateAccessToken(
+      deps.db,
+      bearer,
+      deps.knownIssuers ?? [deps.issuer],
+    );
     if (typeof validated.payload.sub !== "string" || validated.payload.sub.length === 0) {
       return jsonError(401, "unauthenticated", "bearer token has no sub claim");
     }

package/src/api-settings-hub-origin.ts

@@ -47,6 +47,15 @@ export const API_SETTINGS_HUB_ORIGIN_REQUIRED_SCOPE = "parachute:host:admin";
 export interface ApiSettingsHubOriginDeps {
   db: Database;
   issuer: string;
+  /**
+   * SET of origins the hub answers on (loopback ∪ expose-state ∪ platform ∪
+   * per-request `issuer`), built via `buildHubBoundOrigins`. The bearer's
+   * `iss` is validated against THIS set rather than the single `issuer`, so a
+   * credential minted under a still-valid prior origin keeps working across an
+   * origin switch (hub#516 parity). Absent → falls back to `[issuer]` (the
+   * prior strict per-request behavior; tests/non-HTTP callers unaffected).
+   */
+  knownIssuers?: readonly string[];
   /**
    * The currently-resolved issuer + its source layer. Computed by the
    * dispatcher (which has the request + `configuredIssuer` already in
@@ -186,7 +195,11 @@ export async function handleApiSettingsHubOrigin(
 
   // Bearer validation + scope check.
   try {
-    const validated = await validateAccessToken(deps.db, bearer, deps.issuer);
+    const validated = await validateAccessToken(
+      deps.db,
+      bearer,
+      deps.knownIssuers ?? [deps.issuer],
+    );
     if (typeof validated.payload.sub !== "string" || validated.payload.sub.length === 0) {
       return jsonError(401, "unauthenticated", "bearer token has no sub claim");
     }

package/src/api-settings-root-redirect.ts

@@ -0,0 +1,201 @@
+/**
+ * `GET|PUT /api/settings/root-redirect` — operator-settable target for the
+ * bare-`/` 302.
+ *
+ * The hub's root (`/`) redirects to `/admin` by default. This endpoint lets an
+ * operator point it at a surface instead (e.g. a custom-domain hub fronting a
+ * team reading-room surface) without redeploying. The stored value resolves
+ * tier-1 in `resolveRootRedirect` (hub-settings.ts):
+ *
+ *   1. hub_settings.root_redirect (this endpoint writes here)
+ *   2. PARACHUTE_HUB_ROOT_REDIRECT env
+ *   3. `/admin` default (unchanged behavior)
+ *
+ * The endpoint surfaces both the stored value *and* the resolved value + source
+ * so the SPA can render "current: /surface/x (from env)" while the input shows
+ * the empty stored row — same separation rationale as `/api/settings/hub-origin`.
+ *
+ * OPEN-REDIRECT SAFETY is the highest-stakes part: the resolved value lands in a
+ * `Location:` header, so an off-origin value would be a textbook open redirect.
+ * PUT validation (and the read-time resolver) require a SAME-ORIGIN relative
+ * path via `isSafeRedirectPath` — must start with a single `/`, never `//` /
+ * `/\` / a scheme, no control chars / whitespace, and must not resolve back to
+ * `/` (redirect loop). Anything else is rejected (PUT 400 / resolver fallback to
+ * `/admin`).
+ *
+ * Bearer-gated on `parachute:host:admin`, mirroring `handleApiSettingsHubOrigin`
+ * — same Bearer parsing, scope-check posture, and error vocabulary.
+ */
+
+import type { Database } from "bun:sqlite";
+import {
+  type RootRedirectSource,
+  getRootRedirect,
+  isSafeRedirectPath,
+  resolveRootRedirectDetailed,
+  setRootRedirect,
+} from "./hub-settings.ts";
+import { validateAccessToken } from "./jwt-sign.ts";
+
+/** Scope required on the bearer token to call either endpoint. */
+export const API_SETTINGS_ROOT_REDIRECT_REQUIRED_SCOPE = "parachute:host:admin";
+
+export interface ApiSettingsRootRedirectDeps {
+  db: Database;
+  /** Issuer the bearer token must validate against (the hub's resolved issuer). */
+  issuer: string;
+  /**
+   * SET of origins the hub answers on (loopback ∪ expose-state ∪ platform ∪
+   * per-request `issuer`), built via `buildHubBoundOrigins`. The bearer's
+   * `iss` is validated against THIS set rather than the single `issuer`, so a
+   * credential minted under a still-valid prior origin keeps working across an
+   * origin switch (hub#516 parity). Absent → falls back to `[issuer]` (the
+   * prior strict per-request behavior; tests/non-HTTP callers unaffected).
+   */
+  knownIssuers?: readonly string[];
+  /**
+   * Env seam for the resolver's env layer. Defaults to `process.env`. Threaded
+   * so the dispatcher (and tests) can resolve `PARACHUTE_HUB_ROOT_REDIRECT`
+   * deterministically.
+   */
+  env?: NodeJS.ProcessEnv;
+}
+
+interface GetResponseBody {
+  /** Raw stored value from hub_settings.root_redirect, or null. */
+  root_redirect: string | null;
+  /** Resolved target applied to the bare-`/` 302 (precedence-aware, guarded). */
+  resolved: string;
+  /** Which precedence layer the resolved value came from. */
+  source: RootRedirectSource;
+}
+
+interface PutResponseBody {
+  /** Echo of the now-stored value (null if cleared). */
+  root_redirect: string | null;
+}
+
+/**
+ * Validation outcome. The "normalized" branch is what gets passed to
+ * setRootRedirect — string (a safe path) or null (clear the row).
+ */
+type ValidateOutcome = { ok: true; normalized: string | null } | { ok: false; description: string };
+
+/**
+ * Validate the body's `root_redirect` field. Accepts:
+ *   - `null` (or empty string) → clear the stored value, revert to env/default.
+ *   - A safe SAME-ORIGIN relative path per `isSafeRedirectPath`.
+ * Everything else → 400 with an operator-friendly description.
+ */
+export function validateRootRedirect(value: unknown): ValidateOutcome {
+  if (value === null) return { ok: true, normalized: null };
+  if (typeof value !== "string") {
+    return {
+      ok: false,
+      description: `root_redirect must be a string or null (got ${typeof value})`,
+    };
+  }
+  // Empty string is the canonical "clear" shape — store as null (mirrors
+  // setHubOrigin's footgun guard; an empty Location would be meaningless).
+  if (value.length === 0) return { ok: true, normalized: null };
+  if (!isSafeRedirectPath(value)) {
+    return {
+      ok: false,
+      description:
+        "root_redirect must be a same-origin relative path (start with a single `/`, no `//`/`/\\`/scheme, no whitespace, and not `/` itself)",
+    };
+  }
+  return { ok: true, normalized: value };
+}
+
+export async function handleApiSettingsRootRedirect(
+  req: Request,
+  deps: ApiSettingsRootRedirectDeps,
+): Promise<Response> {
+  if (req.method !== "GET" && req.method !== "PUT") {
+    return jsonError(405, "method_not_allowed", "use GET or PUT");
+  }
+
+  // Bearer presence + parsing — identical shape to api-settings-hub-origin
+  // for consistency across hub-internal admin endpoints.
+  const auth = req.headers.get("authorization");
+  if (!auth || !auth.startsWith("Bearer ")) {
+    return jsonError(401, "unauthenticated", "Authorization: Bearer <token> required");
+  }
+  const bearer = auth.slice("Bearer ".length).trim();
+  if (!bearer) {
+    return jsonError(401, "unauthenticated", "empty bearer token");
+  }
+
+  // Bearer validation + scope check.
+  try {
+    const validated = await validateAccessToken(
+      deps.db,
+      bearer,
+      deps.knownIssuers ?? [deps.issuer],
+    );
+    if (typeof validated.payload.sub !== "string" || validated.payload.sub.length === 0) {
+      return jsonError(401, "unauthenticated", "bearer token has no sub claim");
+    }
+    const scopes =
+      typeof validated.payload.scope === "string"
+        ? validated.payload.scope.split(/\s+/).filter((s) => s.length > 0)
+        : [];
+    if (!scopes.includes(API_SETTINGS_ROOT_REDIRECT_REQUIRED_SCOPE)) {
+      return jsonError(
+        403,
+        "insufficient_scope",
+        `bearer token lacks ${API_SETTINGS_ROOT_REDIRECT_REQUIRED_SCOPE}`,
+      );
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return jsonError(401, "unauthenticated", `bearer token invalid — ${msg}`);
+  }
+
+  if (req.method === "GET") {
+    const resolved = resolveRootRedirectDetailed(deps.db, { env: deps.env });
+    const body: GetResponseBody = {
+      root_redirect: getRootRedirect(deps.db),
+      resolved: resolved.value,
+      source: resolved.source,
+    };
+    return new Response(JSON.stringify(body), {
+      status: 200,
+      headers: { "content-type": "application/json" },
+    });
+  }
+
+  // PUT — parse + validate body.
+  let parsed: unknown;
+  try {
+    parsed = await req.json();
+  } catch {
+    return jsonError(400, "invalid_request", "request body must be JSON");
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    return jsonError(400, "invalid_request", "request body must be a JSON object");
+  }
+  if (!("root_redirect" in parsed)) {
+    return jsonError(400, "invalid_request", "request body must include a `root_redirect` field");
+  }
+  const result = validateRootRedirect((parsed as { root_redirect: unknown }).root_redirect);
+  if (!result.ok) {
+    return jsonError(400, "invalid_root_redirect", result.description);
+  }
+
+  setRootRedirect(deps.db, result.normalized);
+
+  const body: PutResponseBody = { root_redirect: result.normalized };
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+function jsonError(status: number, code: string, description: string): Response {
+  return new Response(JSON.stringify({ error: code, error_description: description }), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}

package/src/api-tokens.ts

@@ -67,6 +67,15 @@ export interface ApiTokensDeps {
   db: Database;
   /** Hub origin — used to validate the bearer's `iss`. */
   issuer: string;
+  /**
+   * SET of origins the hub answers on (loopback ∪ expose-state ∪ platform ∪
+   * per-request `issuer`), built via `buildHubBoundOrigins`. The bearer's
+   * `iss` is validated against THIS set rather than the single `issuer`, so a
+   * credential minted under a still-valid prior origin keeps working across an
+   * origin switch (hub#516 parity). Absent → falls back to `[issuer]` (the
+   * prior strict per-request behavior; tests/non-HTTP callers unaffected).
+   */
+  knownIssuers?: readonly string[];
 }
 
 interface TokenWireShape {
@@ -115,7 +124,11 @@ export async function handleApiTokens(req: Request, deps: ApiTokensDeps): Promis
   // 2. Bearer validation.
   let bearerScopes: string[];
   try {
-    const validated = await validateAccessToken(deps.db, bearer, deps.issuer);
+    const validated = await validateAccessToken(
+      deps.db,
+      bearer,
+      deps.knownIssuers ?? [deps.issuer],
+    );
     if (typeof validated.payload.sub !== "string" || validated.payload.sub.length === 0) {
       return jsonError(401, "unauthenticated", "bearer token has no sub claim");
     }

package/src/api-users.ts

@@ -69,6 +69,15 @@ export interface ApiUsersDeps {
   db: Database;
   /** Hub origin — JWT `iss` validation. */
   issuer: string;
+  /**
+   * SET of origins the hub answers on (loopback ∪ expose-state ∪ platform ∪
+   * per-request `issuer`), built via `buildHubBoundOrigins`. The bearer's
+   * `iss` is validated against THIS set rather than the single `issuer`, so a
+   * credential minted under a still-valid prior origin keeps working across an
+   * origin switch (hub#516 parity). Absent → falls back to `[issuer]` (the
+   * prior strict per-request behavior; tests/non-HTTP callers unaffected).
+   */
+  knownIssuers?: readonly string[];
   /** Override services.json path. Defaults to `~/.parachute/services.json`. */
   manifestPath?: string;
 }
@@ -118,7 +127,7 @@ export async function handleListUsers(req: Request, deps: ApiUsersDeps): Promise
     return jsonError(405, "method_not_allowed", "use GET");
   }
   try {
-    await requireScope(deps.db, req, HOST_ADMIN_SCOPE, deps.issuer);
+    await requireScope(deps.db, req, HOST_ADMIN_SCOPE, deps.knownIssuers ?? [deps.issuer]);
   } catch (err) {
     return adminAuthErrorResponse(err as AdminAuthError);
   }
@@ -262,7 +271,7 @@ export async function handleCreateUser(req: Request, deps: ApiUsersDeps): Promis
     return jsonError(405, "method_not_allowed", "use POST");
   }
   try {
-    await requireScope(deps.db, req, HOST_ADMIN_SCOPE, deps.issuer);
+    await requireScope(deps.db, req, HOST_ADMIN_SCOPE, deps.knownIssuers ?? [deps.issuer]);
   } catch (err) {
     return adminAuthErrorResponse(err as AdminAuthError);
   }
@@ -358,7 +367,7 @@ export async function handleDeleteUser(
     return jsonError(405, "method_not_allowed", "use DELETE");
   }
   try {
-    await requireScope(deps.db, req, HOST_ADMIN_SCOPE, deps.issuer);
+    await requireScope(deps.db, req, HOST_ADMIN_SCOPE, deps.knownIssuers ?? [deps.issuer]);
   } catch (err) {
     return adminAuthErrorResponse(err as AdminAuthError);
   }
@@ -441,7 +450,7 @@ export async function handleListVaults(req: Request, deps: ApiUsersDeps): Promis
     return jsonError(405, "method_not_allowed", "use GET");
   }
   try {
-    await requireScope(deps.db, req, HOST_ADMIN_SCOPE, deps.issuer);
+    await requireScope(deps.db, req, HOST_ADMIN_SCOPE, deps.knownIssuers ?? [deps.issuer]);
   } catch (err) {
     return adminAuthErrorResponse(err as AdminAuthError);
   }
@@ -571,7 +580,7 @@ export async function handleUpdateUserVaults(
     return jsonError(405, "method_not_allowed", "use PATCH");
   }
   try {
-    await requireScope(deps.db, req, HOST_ADMIN_SCOPE, deps.issuer);
+    await requireScope(deps.db, req, HOST_ADMIN_SCOPE, deps.knownIssuers ?? [deps.issuer]);
   } catch (err) {
     return adminAuthErrorResponse(err as AdminAuthError);
   }
@@ -760,7 +769,7 @@ export async function handleResetUserPassword(
     return jsonError(405, "method_not_allowed", "use POST");
   }
   try {
-    await requireScope(deps.db, req, HOST_ADMIN_SCOPE, deps.issuer);
+    await requireScope(deps.db, req, HOST_ADMIN_SCOPE, deps.knownIssuers ?? [deps.issuer]);
   } catch (err) {
     return adminAuthErrorResponse(err as AdminAuthError);
   }

package/src/api-vault-caps.ts

@@ -39,6 +39,15 @@ export interface ApiVaultCapsDeps {
   db: Database;
   /** Hub origin — JWT `iss` validation. */
   issuer: string;
+  /**
+   * SET of origins the hub answers on (loopback ∪ expose-state ∪ platform ∪
+   * per-request `issuer`), built via `buildHubBoundOrigins`. The bearer's
+   * `iss` is validated against THIS set rather than the single `issuer`, so a
+   * credential minted under a still-valid prior origin keeps working across an
+   * origin switch (hub#516 parity). Absent → falls back to `[issuer]` (the
+   * prior strict per-request behavior; tests/non-HTTP callers unaffected).
+   */
+  knownIssuers?: readonly string[];
   /** Override services.json path. Defaults to `~/.parachute/services.json`. */
   manifestPath?: string;
 }
@@ -71,7 +80,7 @@ export async function handleListVaultCaps(req: Request, deps: ApiVaultCapsDeps):
     return jsonError(405, "method_not_allowed", "use GET");
   }
   try {
-    await requireScope(deps.db, req, HOST_ADMIN_SCOPE, deps.issuer);
+    await requireScope(deps.db, req, HOST_ADMIN_SCOPE, deps.knownIssuers ?? [deps.issuer]);
   } catch (err) {
     return adminAuthErrorResponse(err as AdminAuthError);
   }
@@ -174,7 +183,7 @@ export async function handleSetVaultCap(
     return jsonError(405, "method_not_allowed", "use PUT");
   }
   try {
-    await requireScope(deps.db, req, HOST_ADMIN_SCOPE, deps.issuer);
+    await requireScope(deps.db, req, HOST_ADMIN_SCOPE, deps.knownIssuers ?? [deps.issuer]);
   } catch (err) {
     return adminAuthErrorResponse(err as AdminAuthError);
   }