@openparachute/hub 0.5.14-rc.8 → 0.6.0

package/src/oauth-handlers.ts

@@ -23,6 +23,7 @@
  */
 import type { Database } from "bun:sqlite";
 import { AdminAuthError, adminAuthErrorResponse, requireScope } from "./admin-auth.ts";
+import { renderTotpChallenge } from "./admin-login-ui.ts";
 import {
   AuthCodeExpiredError,
   AuthCodeNotFoundError,
@@ -65,7 +66,9 @@ import {
   renderUnknownClient,
 } from "./oauth-ui.ts";
 import { isSameOriginRequest } from "./origin-check.ts";
+import { buildPendingLoginCookie, createPendingLogin } from "./pending-login.ts";
 import { isHttpsRequest } from "./request-protocol.ts";
+import { narrowResourceVaultScopes, resolveResourceVault } from "./resource-binding.ts";
 import { isNonRequestableScope, isRequestableScope, scopeIsAdmin } from "./scope-explanations.ts";
 import { findUnknownScopes, loadDeclaredScopes } from "./scope-registry.ts";
 import {
@@ -83,7 +86,14 @@ import {
   findSession,
   parseSessionCookie,
 } from "./sessions.ts";
-import { getUserById, getUserByUsername, isFirstAdmin, verifyPassword } from "./users.ts";
+import { isTotpEnrolled } from "./two-factor-store.ts";
+import {
+  getUserById,
+  getUserByUsername,
+  isFirstAdmin,
+  vaultVerbsForUserVault,
+  verifyPassword,
+} from "./users.ts";
 import { listVaultNames } from "./vault-names.ts";
 import { isVaultEntry, shortName, vaultInstanceNameFor } from "./well-known.ts";
 
@@ -460,6 +470,9 @@ function parseAuthorizeFormParams(url: URL): AuthorizeFormParams | { error: stri
     codeChallenge,
     codeChallengeMethod,
     state: url.searchParams.get("state"),
+    // RFC 8707 resource indicator (optional). When present and resolvable to
+    // a per-vault MCP resource, drives the narrow-consent + named-scope path.
+    resource: url.searchParams.get("resource"),
   };
 }
 
@@ -821,7 +834,7 @@ export function handleAuthorizeGet(db: Database, req: Request, deps: OAuthDeps):
       parsed.state,
     );
   }
-  const client = getClient(db, parsed.clientId);
+  let client = getClient(db, parsed.clientId);
   if (!client) {
     // Can't safely redirect — we don't trust the redirect_uri until we've
     // matched it against a registered client. Render an HTML error that
@@ -832,7 +845,71 @@ export function handleAuthorizeGet(db: Database, req: Request, deps: OAuthDeps):
     return unknownClientResponse(parsed.clientId, parsed.redirectUri, deps);
   }
   if (client.status !== "approved") {
-    return pendingClientResponse(db, req, client, url, deps);
+    // Single-consent change (2026-05-29): the separate operator "approve this
+    // client" gate is retired — the user's OAuth consent IS the authorization.
+    // A request carrying a valid session auto-approves the pending client and
+    // FALLS THROUGH into the normal consent path below (resource-narrow →
+    // non-requestable gate → skip-consent / same-hub → consent render). A
+    // session-less request still renders the unauth "App not yet approved"
+    // page (`pendingClientResponse`), whose sign-in CTA (`loginNextUrl`)
+    // round-trips back to this authorize URL; after login the user re-enters
+    // WITH a session → hits this auto-approve branch → consent.
+    //
+    // We resolve the session via the same `parseSessionCookie` + `findSession`
+    // pair the consent path uses below (not `findActiveSession`) so the
+    // auto-approve predicate and the consent render agree on session identity.
+    const earlySessionId = parseSessionCookie(req.headers.get("cookie"));
+    const earlySession = earlySessionId ? findSession(db, earlySessionId) : null;
+    if (!earlySession) {
+      return pendingClientResponse(db, req, client, url, deps);
+    }
+    console.log(
+      `[oauth] auto-approved client on user consent (single-consent) client_id=${client.clientId} user_id=${earlySession.userId} (2026-05-29)`,
+    );
+    approveClient(db, client.clientId);
+
+    // Trust-by-client_name carry-over (hub#409, preserved through the
+    // single-consent change). Notes/Claude DCR a fresh client_id per session;
+    // when the user has a prior grant under the SAME client_name that covers
+    // the requested scopes, re-link must stay SILENT. The skip-consent gate
+    // below keys on (user, client_id) and the fresh client_id has no grant
+    // yet — so we re-record that prior coverage onto the fresh client_id here.
+    // The mint downstream goes through `issueAuthCodeRedirect`, which caps to
+    // held authority, so this carry-over can never silently re-grant an
+    // un-held verb. Guarded identically to the in-`pendingClientResponse`
+    // block: same-origin + non-empty client_name + non-admin requested scopes
+    // (`scopeIsAdmin` recognizes the named admin form now — load-bearing) +
+    // prior-grant coverage. When it doesn't apply, fall through to the consent
+    // render (the single-consent payoff: one consent screen, then silent).
+    const earlyRequested = parsed.scope.split(" ").filter((s) => s.length > 0);
+    if (
+      isSameOriginRequest(req, resolveBoundOrigins(deps)) &&
+      client.clientName &&
+      earlyRequested.length > 0 &&
+      !earlyRequested.some(scopeIsAdmin) &&
+      isCoveredByGrantForClientName(db, earlySession.userId, client.clientName, earlyRequested)
+    ) {
+      console.log(
+        `[oauth] carried prior client_name trust onto fresh client_id=${client.clientId} client_name=${JSON.stringify(client.clientName)} user_id=${earlySession.userId} scopes=${earlyRequested.join(" ")} (hub#409)`,
+      );
+      recordGrant(
+        db,
+        earlySession.userId,
+        client.clientId,
+        earlyRequested,
+        deps.now?.() ?? new Date(),
+      );
+    }
+
+    // Re-fetch so `client.status` reflects `approved` for the rest of this
+    // function (the same-hub gate and consent props read `client`). Fall
+    // through on success; if the refresh somehow failed, render the unauth
+    // pending page defensively (should never happen given approveClient).
+    const refreshed = getClient(db, client.clientId);
+    if (!refreshed || refreshed.status !== "approved") {
+      return pendingClientResponse(db, req, client, url, deps);
+    }
+    client = refreshed;
   }
   try {
     requireRegisteredRedirectUri(client, parsed.redirectUri);
@@ -844,6 +921,41 @@ export function handleAuthorizeGet(db: Database, req: Request, deps: OAuthDeps):
     );
   }
 
+  // RFC 8707 resource binding. When the client named a per-vault MCP
+  // resource (`<origin>/vault/<name>/mcp` or its PRM URL), narrow the
+  // requested vault verbs to the named `vault:<name>:<verb>` form BEFORE any
+  // downstream processing. Two effects:
+  //
+  //   1. The consent screen shows ONLY that vault's scopes (the picker locks
+  //      to <name>) instead of the whole-hub catalog — a friend connecting to
+  //      one vault no longer sees `hub:admin`, `scribe:admin`, or every other
+  //      vault's verbs.
+  //   2. The minted token carries the named scope, so `inferAudience` stamps
+  //      `aud=vault.<name>` and a current-line vault accepts it (an unnamed
+  //      `vault:read` token is rejected by `findBroadVaultScopes`).
+  //
+  // Narrowing happens before the non-requestable gate (below) on purpose: if
+  // a resource-bound client somehow asked for `vault:admin`, narrowing makes
+  // it `vault:<name>:admin`, which IS non-requestable — so the gate correctly
+  // blocks it. Read/write narrow to the requestable named form. Non-vault
+  // scopes and already-named scopes for other vaults pass through unchanged.
+  //
+  // No resource, or a resource that isn't one of our per-vault MCP resources
+  // (off-origin, malformed, non-vault path) → `boundVault` is null and the
+  // flow is byte-for-byte the pre-#461 behavior (manual picker, etc.).
+  const boundVault = resolveResourceVault(parsed.resource, resolveBoundOrigins(deps));
+  if (boundVault) {
+    const narrowed = narrowResourceVaultScopes(
+      parsed.scope.split(" ").filter((s) => s.length > 0),
+      boundVault,
+    );
+    // Rewrite `parsed.scope` so the narrowed named scopes flow through every
+    // downstream consumer: the login-redirect query round-trip, the consent
+    // props + hidden inputs, the skip-consent grant lookup, and the
+    // auth-code mint.
+    parsed.scope = narrowed.join(" ");
+  }
+
   // Operator-only scope gate (#96). Reject any request that names a scope
   // we'll never mint via this flow — `parachute:host:admin` and friends.
   // Per RFC 6749 §4.1.2.1, errors that aren't redirect-uri-related are
@@ -991,10 +1103,13 @@ export function handleAuthorizeGet(db: Database, req: Request, deps: OAuthDeps):
     console.log(
       `[oauth] auto-approved same-hub client client_id=${client.clientId} user_id=${session.userId} scopes=${requestedScopes.join(" ")} (hub#312)`,
     );
-    // Record the grant so the next /authorize for this (user, client, scopes)
-    // hits the standard skip-consent path (#75) — keeps the audit story
-    // consistent between same-hub and externally-approved flows.
-    recordGrant(db, session.userId, client.clientId, requestedScopes);
+    // The grant is recorded INSIDE issueAuthCodeRedirect with the CAPPED
+    // scopes (single choke-point, single source of truth) so the next
+    // /authorize for this (user, client, scopes) hits the standard
+    // skip-consent path (#75) — and can never replay an un-held verb. The
+    // `!hasAdminScope` guard above already keeps admin scopes off this path
+    // (they fall through to consent), so the cap is a no-op here for the
+    // common case, but it still runs unconditionally for defense in depth.
     return issueAuthCodeRedirect(db, parsed, requestedScopes, session.userId, deps);
   }
 
@@ -1008,10 +1123,89 @@ export function handleAuthorizeGet(db: Database, req: Request, deps: OAuthDeps):
 }
 
 /**
- * Mint an auth code and redirect to the client's redirect_uri. Shared by
- * the consent-submit path (`handleConsentSubmit`) and the skip-consent path
- * in `handleAuthorizeGet` (#75). Caller is responsible for having already
- * validated the client + redirect_uri + scopes.
+ * Anti-privilege-escalation cap (THE security crux of the single-consent
+ * change, 2026-05-29). A user may only delegate authority they themselves
+ * hold: the OAuth consent that authorizes a client must never grant a named
+ * vault verb the consenting user doesn't actually hold on that vault.
+ *
+ * For each scope shaped `vault:<name>:<verb>` (verb ∈ VAULT_VERBS) when the
+ * user is NOT the hub owner, the verb is admitted only if it appears in
+ * `vaultVerbsForUserVault(db, userId, name)` (the verbs the user holds on
+ * that vault, derived from their `user_vaults` role). Otherwise the scope is
+ * DROPPED. Non-vault scopes and unnamed `vault:<verb>` (which never reach
+ * mint without picker-narrowing) pass through untouched.
+ *
+ * The owner (`isFirstAdmin`) bypasses the cap entirely — they hold admin on
+ * every vault by construction (admin posture is the unrestricted sentinel;
+ * see `vaultScopeForUser`). Owner=isFirstAdmin is the Phase-1 definition of
+ * "holds admin everywhere"; revisit when multi-admin lands.
+ *
+ * Security argument (documented at the call site too):
+ *   - The authority source of truth today is `isFirstAdmin` for owner-wide
+ *     authority and `user_vaults.role` (via `vaultVerbsForRole`) for assigned
+ *     users.
+ *   - `vaultVerbsForRole` provably never returns `admin` for an assigned user
+ *     (it maps write→[read,write], read→[read], unknown→[]), so this helper
+ *     drops `vault:<name>:admin` for every non-owner BY CONSTRUCTION — without
+ *     hardcoding "drop admin". It reads the held verb set and admits only
+ *     held verbs, so it's forward-compatible: if a future role ever granted
+ *     admin, the cap would admit it automatically.
+ *   - Applied inside `issueAuthCodeRedirect` (the single choke-point ALL mint
+ *     paths funnel through: consent-submit, skip-consent, and same-hub
+ *     auto-trust), the CAPPED set is what gets both recorded (`recordGrant`)
+ *     and minted (`issueAuthCode`). No mint path can bypass it, and a later
+ *     skip-consent flow can never replay an un-held admin verb because it was
+ *     never recorded.
+ */
+function capScopesToUserAuthority(
+  db: Database,
+  userId: string,
+  scopes: readonly string[],
+  opts: { userIsAdmin: boolean },
+): string[] {
+  if (opts.userIsAdmin) return [...scopes];
+  return scopes.filter((s) => {
+    const parts = s.split(":");
+    if (parts.length !== 3 || parts[0] !== "vault") return true; // non-named — pass through
+    const name = parts[1];
+    const verb = parts[2];
+    if (name === undefined || verb === undefined || !VAULT_VERBS.has(verb)) return true;
+    // Named vault verb requested by a non-owner: admit only if the user holds
+    // it. `vaultVerbsForUserVault` returns null for an unassigned vault (drop)
+    // or the held verb list (today read/write only — never admin).
+    const held = vaultVerbsForUserVault(db, userId, name);
+    return held !== null && (held as readonly string[]).includes(verb);
+  });
+}
+
+/**
+ * Mint an auth code and redirect to the client's redirect_uri. The SINGLE
+ * mint choke-point — shared by the consent-submit path (`handleConsentSubmit`),
+ * the skip-consent path (#75), and the same-hub auto-trust path (hub#312) in
+ * `handleAuthorizeGet`. Caller is responsible for having already validated the
+ * client + redirect_uri and for having narrowed unnamed `vault:<verb>` scopes
+ * to their named form (so the cap below sees final shapes).
+ *
+ * This is the single choke-point for two responsibilities, so NO mint path can
+ * bypass them:
+ *   1. Anti-privilege-escalation cap (`capScopesToUserAuthority`): a non-owner
+ *      can only delegate vault verbs they hold; un-held verbs (notably admin)
+ *      are dropped. An admin-only request from a non-owner caps to EMPTY → we
+ *      refuse with `invalid_scope` rather than mint a zero-scope token. EVERY
+ *      auth code is minted through here, so the cap runs before every mint —
+ *      even when a stale `grants` row already lists an un-held admin verb (the
+ *      cap, not the grant lookup, is what blocks the mint).
+ *   2. Grant recording (`recordGrant`) with the CAPPED scopes for THIS mint —
+ *      so a later skip-consent flow re-entering with the same (user, client)
+ *      can never replay an un-held verb. UNION semantics make this idempotent.
+ *
+ * Not the ONLY `recordGrant` call in this module, though: two other guarded
+ * fast-path records exist — the trust-by-client_name auto-promote in
+ * `pendingClientResponse` (~L585) and the auto-approve carry-over in
+ * `handleAuthorizeGet` (~L895). Both are gated by `!some(scopeIsAdmin)`, so
+ * neither can ever record an admin verb, and any mint they unlock still flows
+ * back through this function's cap. So the invariant "no minted token, and no
+ * grant row, ever carries an un-held admin verb" holds across all paths.
  */
 function issueAuthCodeRedirect(
   db: Database,
@@ -1020,11 +1214,37 @@ function issueAuthCodeRedirect(
   userId: string,
   deps: OAuthDeps,
 ): Response {
+  // Anti-privesc cap at the single choke-point. Runs AFTER any narrowing the
+  // callers did (unnamed `vault:admin` → `vault:<picked>:admin`), so it sees
+  // the final named shapes. Owner (isFirstAdmin) bypasses — holds admin
+  // everywhere by construction.
+  const userIsAdmin = isFirstAdmin(db, userId);
+  const cappedScopes = capScopesToUserAuthority(db, userId, scopes, { userIsAdmin });
+
+  // Drop-not-refuse UX, with one hard floor: if capping leaves an EMPTY set
+  // (e.g. a non-owner requested ONLY `vault:<name>:admin`, which they don't
+  // hold), never mint a zero-scope token — refuse with a clear invalid_scope.
+  // A request that started empty (no scopes at all) is a separate, legitimate
+  // "session token only" case the consent UI supports, so we only refuse when
+  // the cap itself removed every scope.
+  if (cappedScopes.length === 0 && scopes.length > 0) {
+    return oauthErrorRedirect(
+      params.redirectUri,
+      "invalid_scope",
+      "You can grant only the access you hold on this vault; an admin grant requires hub-owner authority.",
+      params.state,
+    );
+  }
+
+  // Record the grant with the CAPPED scopes (single source of truth) so
+  // skip-consent re-entry can never widen back to an un-held verb.
+  recordGrant(db, userId, params.clientId, cappedScopes, deps.now?.() ?? new Date());
+
   const code = issueAuthCode(db, {
     clientId: params.clientId,
     userId,
     redirectUri: params.redirectUri,
-    scopes,
+    scopes: cappedScopes,
     codeChallenge: params.codeChallenge,
     codeChallengeMethod: params.codeChallengeMethod,
     now: deps.now,
@@ -1100,17 +1320,49 @@ async function handleLoginSubmit(
       401,
     );
   }
+
+  // Where to land after a successful sign-in: back at GET /oauth/authorize
+  // with the original query string so the user resumes the OAuth flow on the
+  // consent screen with full params re-validated.
+  const authorizeReturnUrl = buildAuthorizeReturnUrl(params);
+
+  // 2FA gate (hub#473 — security fix). The OAuth login POST is the MORE-common
+  // sign-in path (every OAuth client: vault, notes-ui, `parachute auth login`).
+  // It must enforce the second factor exactly like `/login` does: after the
+  // password verifies, if the user has TOTP enrolled, do NOT mint a session.
+  // Stash a pending-login whose `next` is the FULL /oauth/authorize return URL
+  // (so the post-TOTP redirect resumes the OAuth flow), and render the TOTP
+  // challenge. The challenge form posts to `/login/2fa` — the shared
+  // completion path (`handleAdminLoginTotpPost`) — which verifies the factor,
+  // mints the session, and 302s to the stored `next`. The pending-login cookie
+  // is scoped `Path=/login`, so it rides the `/login/2fa` POST. Without this
+  // gate a 2FA-enrolled user could obtain a full session with password ONLY.
+  if (isTotpEnrolled(db, user.id)) {
+    const pendingToken = createPendingLogin(user.id, authorizeReturnUrl);
+    return htmlResponse(renderTotpChallenge({ next: authorizeReturnUrl, csrfToken }), 200, {
+      "set-cookie": buildPendingLoginCookie(pendingToken, req),
+    });
+  }
+
   const session = createSession(db, { userId: user.id });
   const cookie = buildSessionCookie(session.id, Math.floor(SESSION_TTL_MS / 1000), {
     secure: isHttpsRequest(req),
   });
-  // Redirect back to GET /oauth/authorize with the original query string so
-  // the user lands on the consent screen with full params re-validated.
+  return redirectResponse(authorizeReturnUrl, { "set-cookie": cookie });
+}
+
+/**
+ * Build the `/oauth/authorize?...` return URL (path + query, same-origin) that
+ * a successful sign-in redirects back to so the OAuth flow resumes on the
+ * consent screen. Shared by the password-only path and the post-TOTP path
+ * (the latter via the pending-login's `next`).
+ */
+function buildAuthorizeReturnUrl(params: AuthorizeFormParams): string {
   const u = new URL("/oauth/authorize", "http://placeholder");
   for (const [k, v] of Object.entries(authorizeParamsToQuery(params))) {
     u.searchParams.set(k, v);
   }
-  return redirectResponse(`${u.pathname}${u.search}`, { "set-cookie": cookie });
+  return `${u.pathname}${u.search}`;
 }
 
 async function handleConsentSubmit(
@@ -1121,6 +1373,21 @@ async function handleConsentSubmit(
   csrfToken: string,
 ): Promise<Response> {
   const params = paramsFromForm(form);
+  // RFC 8707 resource binding — defense-in-depth (mirror of the GET handler).
+  // The consent form's hidden inputs already carry the narrowed named scopes
+  // (the GET handler rewrote `parsed.scope` before rendering), but a hand-
+  // crafted POST could re-supply an unnamed `vault:read` alongside the
+  // `resource` field. Re-narrow here so the minted token is always named +
+  // correctly-audienced regardless of what the form body claims. Same
+  // semantics as the GET path: only when `resource` resolves to one of our
+  // per-vault MCP resources; no-op otherwise (manual-pick path unchanged).
+  const boundVault = resolveResourceVault(params.resource, resolveBoundOrigins(deps));
+  if (boundVault) {
+    params.scope = narrowResourceVaultScopes(
+      params.scope.split(" ").filter((s) => s.length > 0),
+      boundVault,
+    ).join(" ");
+  }
   const approve = String(form.get("approve") ?? "") === "yes";
   const sessionId = parseSessionCookie(req.headers.get("cookie"));
   const session = sessionId ? findSession(db, sessionId) : null;
@@ -1201,6 +1468,11 @@ async function handleConsentSubmit(
   const sessionUser = getUserById(db, session.userId);
   const assignedVaults: string[] = userIsAdmin ? [] : (sessionUser?.assignedVaults ?? []);
   const isPinned = assignedVaults.length > 0;
+  // By design: the resource-bound re-narrow above does NOT check the bound
+  // vault exists in services.json for the admin path — admin (isPinned=false)
+  // can already consent to any vault via the manual picker, so the asymmetry
+  // (named-scope mint against a possibly-missing vault) is deliberate, not an
+  // oversight. Non-admins still hit the assignment + stale-vault defenses below.
 
   // Zero-vault non-admin gate (Phase 2 PR 2 reviewer fold). A non-admin
   // user with no `user_vaults` rows is a known-but-not-yet-assigned
@@ -1362,12 +1634,12 @@ async function handleConsentSubmit(
     }
   }
 
-  // Record (or extend) the grant so the next /oauth/authorize for this
-  // (user, client) with these scopes — or any subset — can skip the consent
-  // screen (#75). UNION semantics: if the user previously granted [a, b, c]
-  // and now grants [a, d], the row becomes [a, b, c, d]. Subset re-flows
-  // still match.
-  recordGrant(db, session.userId, client.clientId, scopes, deps.now?.() ?? new Date());
+  // The grant is recorded (or extended) INSIDE issueAuthCodeRedirect with the
+  // CAPPED scopes — the single mint choke-point owns both the anti-privesc cap
+  // and the recordGrant so no path can record an un-held verb. UNION semantics
+  // there mean a subset re-flow still matches a prior grant, and an admin-only
+  // request from a non-owner caps to empty → refused (no zero-scope token).
+  // (#75 skip-consent depends on this recording.)
   return issueAuthCodeRedirect(db, params, scopes, session.userId, deps);
 }
 
@@ -1554,6 +1826,7 @@ function paramsFromForm(form: Awaited<ReturnType<Request["formData"]>>): Authori
     codeChallenge: String(form.get("code_challenge") ?? ""),
     codeChallengeMethod: String(form.get("code_challenge_method") ?? "S256"),
     state: (form.get("state") as string | null) ?? null,
+    resource: (form.get("resource") as string | null) ?? null,
   };
 }
 
@@ -1567,6 +1840,10 @@ function authorizeParamsToQuery(p: AuthorizeFormParams): Record<string, string>
     code_challenge_method: p.codeChallengeMethod,
   };
   if (p.state) q.state = p.state;
+  // Round-trip the RFC 8707 resource indicator through the login redirect so
+  // the resource-bound narrowing survives a sign-in (it re-enters GET
+  // /oauth/authorize with the original params).
+  if (p.resource) q.resource = p.resource;
   return q;
 }
 

package/src/oauth-ui.ts

@@ -62,6 +62,12 @@ export interface AuthorizeFormParams {
   codeChallenge: string;
   codeChallengeMethod: string;
   state: string | null;
+  /**
+   * RFC 8707 resource indicator. Carried through the login → consent →
+   * form-post round-trip so the resource-bound vault narrowing survives a
+   * sign-in redirect. Null when the client sent no `resource` param.
+   */
+  resource: string | null;
 }
 
 export interface LoginViewProps {
@@ -932,6 +938,10 @@ export function renderHiddenInputs(p: AuthorizeFormParams): string {
     ["code_challenge_method", p.codeChallengeMethod],
   ];
   if (p.state) fields.push(["state", p.state]);
+  // RFC 8707 resource indicator — round-tripped through the consent form so
+  // the resource-bound vault narrowing survives the POST (the consent submit
+  // path re-derives the bound vault from it).
+  if (p.resource) fields.push(["resource", p.resource]);
   return fields
     .map(([k, v]) => `<input type="hidden" name="${k}" value="${escapeHtml(v)}" />`)
     .join("\n        ");

package/src/operator-token.ts

@@ -31,6 +31,7 @@ import { promises as fs } from "node:fs";
 import { join } from "node:path";
 import { configDir } from "./config.ts";
 import { recordTokenMint, signAccessToken, validateAccessToken } from "./jwt-sign.ts";
+import { isLoopbackOrigin } from "./vault-hub-origin-env.ts";
 
 export const OPERATOR_TOKEN_FILENAME = "operator.token";
 /** Default operator-token lifetime — 90 days, was 365d through 0.5.7 (#213). */
@@ -462,3 +463,153 @@ export async function useOperatorTokenWithAutoRotate(
     status: { kind: "rotated" },
   };
 }
+
+export interface SelfHealOperatorTokenOpts {
+  /**
+   * The hub's CURRENT issuer (its public origin once exposed). The stale
+   * on-disk token is re-minted under this value. Must be the resolved hub
+   * origin, never a raw flag — callers pass `r.hubOrigin` from lifecycle.
+   */
+  issuer: string;
+  /** configDir override (where operator.token lives). Defaults to `configDir()`. */
+  configDir?: string;
+  /** Operator-facing log sink. Defaults to a no-op (silent). */
+  log?: (line: string) => void;
+  /** Override the JWT-sign clock — tests pin time. Forwarded to `issueOperatorToken`. */
+  now?: () => Date;
+}
+
+/**
+ * Disambiguated outcome of {@link selfHealOperatorTokenIssuer}. Modelled on
+ * {@link RotationStatus} — a small discriminated union the caller logs and
+ * tests assert.
+ *
+ * - `absent` — no `operator.token` on disk; nothing to heal.
+ * - `fresh` — the token's `iss` already matches the current issuer; the file
+ *   is left byte-identical (no rewrite, no log).
+ * - `rotated` — the token was genuine-but-stale; re-minted under the current
+ *   issuer with the SAME scope-set + sub. `path` / `expiresAt` / `scopeSet`
+ *   describe the freshly-written token.
+ * - `skipped` — a guard fired; the on-disk file is left untouched. `reason`:
+ *     - `unverifiable`: the on-disk token's signature did NOT verify against
+ *       this hub's current keys (bad/unknown/expired kid, jose `exp` failure,
+ *       or a revoked jti). We must NOT resurrect or trust it — the operator
+ *       recovers via `parachute auth rotate-operator`.
+ *     - `aud-mismatch`: the token carries a non-operator audience. A
+ *       hand-stashed scope-narrow JWT must not be silently re-minted as a
+ *       full operator token (parallels the {@link useOperatorTokenWithAutoRotate}
+ *       privilege guard).
+ *     - `no-sub`: the token lacks a `sub` claim, so we can't re-mint (don't
+ *       know who it belongs to).
+ *     - `no-scope-set`: the token lacks (or has an unrecognized) `pa_scope_set`
+ *       claim. Falling back to a default would widen scope (hub#224 hardening);
+ *       refuse instead. Operator recovers via explicit rotate-operator.
+ *     - `issuer-loopback`: the TARGET issuer is loopback. Re-minting to a
+ *       loopback `iss` would downgrade a good public token; never do it.
+ */
+export type OperatorIssuerHealStatus =
+  | { kind: "absent" }
+  | { kind: "fresh" }
+  | { kind: "rotated"; path: string; scopeSet: OperatorScopeSet; expiresAt: string }
+  | {
+      kind: "skipped";
+      reason: "unverifiable" | "aud-mismatch" | "no-sub" | "no-scope-set" | "issuer-loopback";
+    };
+
+/**
+ * Self-heal the operator token's `iss` when the hub's origin changed after
+ * the token was minted.
+ *
+ * The bug this closes (hub#481, same family as the rc.17 Cloudflare 401 P0):
+ * `parachute init`/setup mints `~/.parachute/operator.token` stamped with the
+ * hub's origin-at-creation-time (`http://127.0.0.1:1939` on a box set up
+ * before exposure). After `parachute expose` brings the hub up on a public
+ * origin, on-box services validate incoming bearers' `iss` against the hub's
+ * CURRENT origin, so the stale-`iss` operator token is rejected on every CLI
+ * auth flow with `bearer token invalid — unexpected "iss" claim value`. That
+ * breaks `vault create`, `mcp-install`, and `/api/auth/mint-token`. The token
+ * is genuine — it just predates the origin change — so re-issuing it under the
+ * current issuer (preserving its scope-set + sub) is the right repair.
+ *
+ * Hooked into `parachute start hub` (parallel to how rc.17 hooked
+ * `selfHealVaultHubOrigin` into `start vault`): existing broken deploys
+ * self-correct on the next `start/restart hub`.
+ *
+ * ## Security invariant (reviewer: verify this holds)
+ *
+ * Re-mint is gated on `validateAccessToken(db, token)` succeeding WITHOUT an
+ * `expectedIssuer` argument — i.e. the on-disk token's SIGNATURE verifies
+ * against THIS hub's current public keys (by kid) and passes jose's `exp`
+ * check and the revocation check, while NOT pinning `iss`. An attacker cannot
+ * forge that signature, so the ONLY tokens that can ever be re-minted are ones
+ * this hub itself previously minted. There is no path to mint a token from an
+ * untrusted/forged input. Further:
+ *   - scope-set is preserved verbatim (`payload.pa_scope_set`) — no widening;
+ *   - expired tokens are refused (jose `exp` → `skipped: unverifiable`);
+ *   - revoked tokens are refused (validateAccessToken's revocation check);
+ *   - a non-operator audience is refused (`skipped: aud-mismatch`);
+ *   - a loopback TARGET issuer is refused (`skipped: issuer-loopback`) — never
+ *     downgrade a good public token back to loopback.
+ * This is strictly a re-issue of the hub's own still-valid credential under
+ * the hub's own new issuer.
+ */
+export async function selfHealOperatorTokenIssuer(
+  db: Database,
+  opts: SelfHealOperatorTokenOpts,
+): Promise<OperatorIssuerHealStatus> {
+  const dir = opts.configDir ?? configDir();
+  const token = await readOperatorTokenFile(dir);
+  if (!token) return { kind: "absent" };
+
+  // Target-issuer loopback guard FIRST. Re-minting to a loopback `iss` would
+  // downgrade a good public token to a non-reachable issuer, recreating the
+  // exact iss-mismatch this fix prevents (mirrors `isLoopbackOrigin`'s role in
+  // vault-hub-origin-env.ts). Never do it — bail before touching the token.
+  if (isLoopbackOrigin(opts.issuer)) return { kind: "skipped", reason: "issuer-loopback" };
+
+  // Verify the on-disk token WITHOUT pinning `iss`: this checks the signature
+  // against the hub's current keys (by kid) + jose's `exp` + revocation, but
+  // deliberately does NOT reject a stale issuer. A throw here means the token
+  // is unverifiable (bad/unknown/expired kid, expired-by-jose, revoked) — we
+  // must NOT resurrect or trust it. Leave the disk file untouched; the operator
+  // recovers via `parachute auth rotate-operator`.
+  let payload: Awaited<ReturnType<typeof validateAccessToken>>["payload"];
+  try {
+    ({ payload } = await validateAccessToken(db, token));
+  } catch {
+    return { kind: "skipped", reason: "unverifiable" };
+  }
+
+  // `iss` already current → no-op. Do NOT rewrite the file; it must stay
+  // byte-identical so repeated `start hub`s don't churn it.
+  if (payload.iss === opts.issuer) return { kind: "fresh" };
+
+  // `iss` differs → genuine-but-stale. Apply the same provenance guards
+  // `useOperatorTokenWithAutoRotate` uses before re-minting.
+  if (payload.aud !== OPERATOR_TOKEN_AUDIENCE) {
+    return { kind: "skipped", reason: "aud-mismatch" };
+  }
+  const sub = typeof payload.sub === "string" && payload.sub.length > 0 ? payload.sub : null;
+  if (!sub) return { kind: "skipped", reason: "no-sub" };
+  const claimedSet = payload[OPERATOR_TOKEN_SCOPE_SET_CLAIM];
+  if (!isOperatorScopeSet(claimedSet)) {
+    // No recognized scope-set → falling back to a default would widen scope
+    // (hub#224). Refuse; never widen.
+    return { kind: "skipped", reason: "no-scope-set" };
+  }
+
+  // Re-mint preserving scope-set + sub. `issueOperatorToken` writes the new
+  // token to disk atomically (mint → writeOperatorTokenFile).
+  const issued = await issueOperatorToken(db, sub, {
+    dir,
+    issuer: opts.issuer,
+    scopeSet: claimedSet,
+    ...(opts.now !== undefined ? { now: opts.now } : {}),
+  });
+  return {
+    kind: "rotated",
+    path: issued.path,
+    scopeSet: issued.scopeSet,
+    expiresAt: issued.expiresAt,
+  };
+}