@openparachute/hub 0.5.14-rc.17 → 0.5.14-rc.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.5.14-rc.17",
+  "version": "0.5.14-rc.18",
   "description": "parachute — the local hub for the Parachute ecosystem (discovery, ports, lifecycle, soon OAuth).",
   "license": "AGPL-3.0",
   "publishConfig": {

package/src/__tests__/lifecycle.test.ts

@@ -13,8 +13,16 @@ import {
 } from "../commands/lifecycle.ts";
 import { readEnvFileValues } from "../env-file.ts";
 import { writeHubPort } from "../hub-control.ts";
+import { hubDbPath, openHubDb } from "../hub-db.ts";
+import { validateAccessToken } from "../jwt-sign.ts";
+import {
+  OPERATOR_TOKEN_SCOPE_SET_CLAIM,
+  issueOperatorToken,
+  readOperatorTokenFile,
+} from "../operator-token.ts";
 import { ensureLogPath, logPath, readPid, writePid } from "../process-state.ts";
 import { upsertService } from "../services-manifest.ts";
+import { rotateSigningKey } from "../signing-keys.ts";
 
 interface Harness {
   configDir: string;
@@ -1525,6 +1533,149 @@ describe("parachute start|stop|restart hub", () => {
     }
   });
 
+  // hub#481 — `start hub` self-heals a stale operator-token issuer. Tests use
+  // the injectable `hub.selfHealOperatorToken` seam to assert the call happens
+  // (and to make it throw without failing start); a separate test drives the
+  // REAL self-heal against an on-disk operator token + hub.db.
+  test("start hub: invokes operator-token self-heal with the resolved issuer + configDir", async () => {
+    const h = makeHarness();
+    try {
+      const log: string[] = [];
+      const calls: Array<{ issuer: string; configDir: string }> = [];
+      const code = await start("hub", {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        hubOrigin: "https://hub.example.com",
+        hub: {
+          ensureRunning: async () => ({ pid: 4711, port: 1939, started: true }),
+          selfHealOperatorToken: async (args) => {
+            calls.push({ issuer: args.issuer, configDir: args.configDir });
+            return {
+              kind: "rotated",
+              path: "/x/operator.token",
+              scopeSet: "admin",
+              expiresAt: "z",
+            };
+          },
+        },
+        log: (l) => log.push(l),
+      });
+      expect(code).toBe(0);
+      expect(calls).toEqual([{ issuer: "https://hub.example.com", configDir: h.configDir }]);
+      // Rotation emits an operator-facing line.
+      expect(log.join("\n")).toMatch(
+        /refreshed operator\.token issuer → https:\/\/hub\.example\.com/,
+      );
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("start hub: skips operator-token self-heal when no hub origin is resolvable", async () => {
+    const h = makeHarness();
+    try {
+      let called = false;
+      // No hubOrigin override, no expose-state, no hub.port file → resolveHubOrigin
+      // yields undefined, so the self-heal seam must NOT be called.
+      const code = await start("hub", {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        hub: {
+          ensureRunning: async () => ({ pid: 4711, port: 1939, started: true }),
+          selfHealOperatorToken: async () => {
+            called = true;
+            return { kind: "absent" };
+          },
+        },
+        log: () => {},
+      });
+      expect(code).toBe(0);
+      expect(called).toBe(false);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("start hub: a thrown error inside operator-token self-heal does NOT fail start", async () => {
+    const h = makeHarness();
+    try {
+      const log: string[] = [];
+      const code = await start("hub", {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        hubOrigin: "https://hub.example.com",
+        hub: {
+          ensureRunning: async () => ({ pid: 4711, port: 1939, started: true }),
+          selfHealOperatorToken: async () => {
+            throw new Error("hub.db is locked");
+          },
+        },
+        log: (l) => log.push(l),
+      });
+      expect(code).toBe(0);
+      // Degrades to a brief note, not a hard failure.
+      expect(log.join("\n")).toMatch(
+        /operator\.token issuer self-heal skipped \(hub\.db is locked\)/,
+      );
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("start hub: real self-heal re-mints a stale-iss operator token on disk", async () => {
+    const h = makeHarness();
+    try {
+      // Seed signing keys + a stale-iss operator token in the harness configDir's
+      // hub.db / operator.token, then drive the production self-heal seam.
+      const db = openHubDb(hubDbPath(h.configDir));
+      try {
+        rotateSigningKey(db);
+        await issueOperatorToken(db, "user-abc", {
+          dir: h.configDir,
+          issuer: "http://127.0.0.1:1939",
+          scopeSet: "start",
+        });
+      } finally {
+        db.close();
+      }
+
+      const log: string[] = [];
+      const code = await start("hub", {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        hubOrigin: "https://gitcoin-parachute.unforced.dev",
+        // No selfHealOperatorToken override → exercises defaultSelfHealOperatorToken
+        // (opens hub.db at <configDir>/hub.db).
+        hub: {
+          ensureRunning: async () => ({ pid: 4711, port: 1939, started: true }),
+        },
+        log: (l) => log.push(l),
+      });
+      expect(code).toBe(0);
+      expect(log.join("\n")).toMatch(
+        /refreshed operator\.token issuer → https:\/\/gitcoin-parachute\.unforced\.dev/,
+      );
+
+      // The on-disk token now validates under the new issuer, scope-set preserved.
+      const verifyDb = openHubDb(hubDbPath(h.configDir));
+      try {
+        const onDisk = await readOperatorTokenFile(h.configDir);
+        expect(onDisk).not.toBeNull();
+        const validated = await validateAccessToken(
+          verifyDb,
+          onDisk as string,
+          "https://gitcoin-parachute.unforced.dev",
+        );
+        expect(validated.payload.iss).toBe("https://gitcoin-parachute.unforced.dev");
+        expect(validated.payload[OPERATOR_TOKEN_SCOPE_SET_CLAIM]).toBe("start");
+      } finally {
+        verifyDb.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
   test("stop hub: dispatches to stopHub, true → '✓ hub stopped'", async () => {
     const h = makeHarness();
     try {

package/src/__tests__/operator-token-issuer-self-heal.test.ts

@@ -0,0 +1,412 @@
+/**
+ * hub#481 — `selfHealOperatorTokenIssuer` re-mints a genuine-but-stale
+ * operator token under the hub's current issuer.
+ *
+ * Background: a box that ran init/setup at loopback and was LATER exposed
+ * publicly carries an `operator.token` whose `iss` (e.g. `http://127.0.0.1:1939`)
+ * no longer matches the hub's current issuer. The hub rejects it on every CLI
+ * auth flow. The self-heal re-issues the hub's OWN credential under the new
+ * issuer, preserving scope-set + sub, gated on the token's signature verifying
+ * against this hub's current keys (no privilege-escalation surface).
+ *
+ * Mirrors the existing `operator-token.test.ts` harness shape.
+ */
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { hubDbPath, openHubDb } from "../hub-db.ts";
+import { signAccessToken, validateAccessToken } from "../jwt-sign.ts";
+import {
+  OPERATOR_TOKEN_AUDIENCE,
+  OPERATOR_TOKEN_CLIENT_ID,
+  OPERATOR_TOKEN_FILENAME,
+  OPERATOR_TOKEN_SCOPE_SET_CLAIM,
+  issueOperatorToken,
+  operatorTokenPath,
+  readOperatorTokenFile,
+  selfHealOperatorTokenIssuer,
+  writeOperatorTokenFile,
+} from "../operator-token.ts";
+import { rotateSigningKey } from "../signing-keys.ts";
+
+interface Harness {
+  dir: string;
+  cleanup: () => void;
+}
+
+function makeHarness(): Harness {
+  const dir = mkdtempSync(join(tmpdir(), "phub-op-heal-"));
+  return { dir, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
+}
+
+const LOOPBACK_ISSUER = "http://127.0.0.1:1939";
+const PUBLIC_ISSUER = "https://gitcoin-parachute.unforced.dev";
+
+describe("selfHealOperatorTokenIssuer", () => {
+  test("stale-iss genuine token + non-loopback new issuer → rotated, scope-set preserved, valid under new issuer", async () => {
+    const h = makeHarness();
+    try {
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        rotateSigningKey(db);
+        // Mint at loopback issuer with a non-default scope-set ("start").
+        await issueOperatorToken(db, "user-abc", {
+          dir: h.dir,
+          issuer: LOOPBACK_ISSUER,
+          scopeSet: "start",
+        });
+
+        const status = await selfHealOperatorTokenIssuer(db, {
+          issuer: PUBLIC_ISSUER,
+          configDir: h.dir,
+        });
+        expect(status.kind).toBe("rotated");
+        if (status.kind === "rotated") {
+          expect(status.scopeSet).toBe("start");
+          expect(status.path).toBe(operatorTokenPath(h.dir));
+        }
+
+        // The on-disk token now has iss=PUBLIC_ISSUER, scope-set preserved,
+        // and validates under the new issuer.
+        const onDisk = await readOperatorTokenFile(h.dir);
+        expect(onDisk).not.toBeNull();
+        const validated = await validateAccessToken(db, onDisk as string, PUBLIC_ISSUER);
+        expect(validated.payload.iss).toBe(PUBLIC_ISSUER);
+        expect(validated.payload.sub).toBe("user-abc");
+        expect(validated.payload[OPERATOR_TOKEN_SCOPE_SET_CLAIM]).toBe("start");
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("iss already current → fresh, on-disk file byte-identical", async () => {
+    const h = makeHarness();
+    try {
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        rotateSigningKey(db);
+        await issueOperatorToken(db, "user-abc", {
+          dir: h.dir,
+          issuer: PUBLIC_ISSUER,
+          scopeSet: "admin",
+        });
+        const before = await readFile(operatorTokenPath(h.dir));
+
+        const status = await selfHealOperatorTokenIssuer(db, {
+          issuer: PUBLIC_ISSUER,
+          configDir: h.dir,
+        });
+        expect(status.kind).toBe("fresh");
+
+        const after = await readFile(operatorTokenPath(h.dir));
+        expect(after.equals(before)).toBe(true);
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("absent token file → absent, no throw", async () => {
+    const h = makeHarness();
+    try {
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        rotateSigningKey(db);
+        const status = await selfHealOperatorTokenIssuer(db, {
+          issuer: PUBLIC_ISSUER,
+          configDir: h.dir,
+        });
+        expect(status.kind).toBe("absent");
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("bad signature (corrupt token) → skipped:unverifiable, disk untouched", async () => {
+    const h = makeHarness();
+    try {
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        rotateSigningKey(db);
+        // Mint a real token at loopback, then corrupt its signature segment so
+        // it no longer verifies against the hub's keys.
+        const issued = await issueOperatorToken(db, "user-abc", {
+          dir: h.dir,
+          issuer: LOOPBACK_ISSUER,
+          scopeSet: "start",
+        });
+        const parts = issued.token.split(".");
+        const hdr = parts[0] ?? "";
+        const body = parts[1] ?? "";
+        const sig = parts[2] ?? "";
+        // Flip a character in the MIDDLE of the signature, keeping it
+        // base64url-shaped. Corrupting the last char is unreliable: the final
+        // base64url char of an RS256 signature encodes only padding bits, so a
+        // flip there can decode to identical bytes and leave the signature
+        // valid (~25% of mints). A mid-signature char sits in a full 4-char
+        // group with no padding, so any single-char change deterministically
+        // alters the decoded bytes and invalidates the signature.
+        const mid = Math.floor(sig.length / 2);
+        const flipped = sig[mid] === "A" ? "B" : "A";
+        const tampered = `${hdr}.${body}.${sig.slice(0, mid)}${flipped}${sig.slice(mid + 1)}`;
+        await writeOperatorTokenFile(tampered, h.dir);
+
+        const status = await selfHealOperatorTokenIssuer(db, {
+          issuer: PUBLIC_ISSUER,
+          configDir: h.dir,
+        });
+        expect(status.kind).toBe("skipped");
+        if (status.kind === "skipped") expect(status.reason).toBe("unverifiable");
+
+        const onDisk = await readOperatorTokenFile(h.dir);
+        expect(onDisk).toBe(tampered);
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("expired token (exp in the past) → skipped:unverifiable (jose throws), disk untouched", async () => {
+    const h = makeHarness();
+    try {
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        rotateSigningKey(db);
+        // Mint a token that expired in the past — jose's exp check throws on
+        // validate, so the self-heal must classify it unverifiable.
+        const issued = await issueOperatorToken(db, "user-abc", {
+          dir: h.dir,
+          issuer: LOOPBACK_ISSUER,
+          scopeSet: "start",
+          ttlSeconds: 60,
+          now: () => new Date("2026-01-01T00:00:00Z"),
+        });
+
+        const status = await selfHealOperatorTokenIssuer(db, {
+          issuer: PUBLIC_ISSUER,
+          configDir: h.dir,
+        });
+        expect(status.kind).toBe("skipped");
+        if (status.kind === "skipped") expect(status.reason).toBe("unverifiable");
+
+        const onDisk = await readOperatorTokenFile(h.dir);
+        expect(onDisk).toBe(issued.token);
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("aud != operator (aud=scribe, valid sig, stale iss) → skipped:aud-mismatch, untouched", async () => {
+    const h = makeHarness();
+    try {
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        rotateSigningKey(db);
+        // A hub-signed token with the WRONG audience must not be re-minted as
+        // an operator token (privilege guard).
+        const signed = await signAccessToken(db, {
+          sub: "user-abc",
+          scopes: ["scribe:transcribe"],
+          audience: "scribe",
+          clientId: OPERATOR_TOKEN_CLIENT_ID,
+          issuer: LOOPBACK_ISSUER,
+          extraClaims: { [OPERATOR_TOKEN_SCOPE_SET_CLAIM]: "admin" },
+        });
+        await writeOperatorTokenFile(signed.token, h.dir);
+
+        const status = await selfHealOperatorTokenIssuer(db, {
+          issuer: PUBLIC_ISSUER,
+          configDir: h.dir,
+        });
+        expect(status.kind).toBe("skipped");
+        if (status.kind === "skipped") expect(status.reason).toBe("aud-mismatch");
+
+        const onDisk = await readOperatorTokenFile(h.dir);
+        expect(onDisk).toBe(signed.token);
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("missing/invalid pa_scope_set (stale iss, aud=operator) → skipped:no-scope-set, NOT widened to admin", async () => {
+    const h = makeHarness();
+    try {
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        rotateSigningKey(db);
+        // aud=operator + stale iss + NO pa_scope_set claim. Falling back to a
+        // default scope-set would silently widen to admin (hub#224); refuse.
+        const signed = await signAccessToken(db, {
+          sub: "user-abc",
+          scopes: ["scribe:transcribe"],
+          audience: OPERATOR_TOKEN_AUDIENCE,
+          clientId: OPERATOR_TOKEN_CLIENT_ID,
+          issuer: LOOPBACK_ISSUER,
+        });
+        await writeOperatorTokenFile(signed.token, h.dir);
+
+        const status = await selfHealOperatorTokenIssuer(db, {
+          issuer: PUBLIC_ISSUER,
+          configDir: h.dir,
+        });
+        expect(status.kind).toBe("skipped");
+        if (status.kind === "skipped") expect(status.reason).toBe("no-scope-set");
+
+        // On-disk file unchanged — no widening occurred.
+        const onDisk = await readOperatorTokenFile(h.dir);
+        expect(onDisk).toBe(signed.token);
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("missing sub (stale iss, aud=operator, valid scope-set) → skipped:no-sub, untouched", async () => {
+    const h = makeHarness();
+    try {
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        rotateSigningKey(db);
+        // aud=operator + recognized scope-set + stale iss but NO sub — we can't
+        // re-mint a token we can't attribute.
+        const signed = await signAccessToken(db, {
+          sub: "",
+          scopes: ["parachute:host:start"],
+          audience: OPERATOR_TOKEN_AUDIENCE,
+          clientId: OPERATOR_TOKEN_CLIENT_ID,
+          issuer: LOOPBACK_ISSUER,
+          extraClaims: { [OPERATOR_TOKEN_SCOPE_SET_CLAIM]: "start" },
+        });
+        await writeOperatorTokenFile(signed.token, h.dir);
+
+        const status = await selfHealOperatorTokenIssuer(db, {
+          issuer: PUBLIC_ISSUER,
+          configDir: h.dir,
+        });
+        expect(status.kind).toBe("skipped");
+        if (status.kind === "skipped") expect(status.reason).toBe("no-sub");
+
+        const onDisk = await readOperatorTokenFile(h.dir);
+        expect(onDisk).toBe(signed.token);
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("target issuer loopback (public token on disk) → skipped:issuer-loopback, public token preserved", async () => {
+    const h = makeHarness();
+    try {
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        rotateSigningKey(db);
+        // A good PUBLIC-issuer token; calling self-heal with a loopback target
+        // must never downgrade it.
+        const issued = await issueOperatorToken(db, "user-abc", {
+          dir: h.dir,
+          issuer: PUBLIC_ISSUER,
+          scopeSet: "admin",
+        });
+
+        const status = await selfHealOperatorTokenIssuer(db, {
+          issuer: LOOPBACK_ISSUER,
+          configDir: h.dir,
+        });
+        expect(status.kind).toBe("skipped");
+        if (status.kind === "skipped") expect(status.reason).toBe("issuer-loopback");
+
+        const onDisk = await readOperatorTokenFile(h.dir);
+        expect(onDisk).toBe(issued.token);
+        // Still a public-issuer token.
+        const validated = await validateAccessToken(db, onDisk as string, PUBLIC_ISSUER);
+        expect(validated.payload.iss).toBe(PUBLIC_ISSUER);
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("scope-set preserved verbatim — 'auth' set stays 'auth', not widened to admin", async () => {
+    const h = makeHarness();
+    try {
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        rotateSigningKey(db);
+        await issueOperatorToken(db, "user-xyz", {
+          dir: h.dir,
+          issuer: LOOPBACK_ISSUER,
+          scopeSet: "auth",
+        });
+
+        const status = await selfHealOperatorTokenIssuer(db, {
+          issuer: PUBLIC_ISSUER,
+          configDir: h.dir,
+        });
+        expect(status.kind).toBe("rotated");
+        if (status.kind === "rotated") expect(status.scopeSet).toBe("auth");
+
+        const onDisk = await readOperatorTokenFile(h.dir);
+        const validated = await validateAccessToken(db, onDisk as string, PUBLIC_ISSUER);
+        expect(validated.payload[OPERATOR_TOKEN_SCOPE_SET_CLAIM]).toBe("auth");
+        // The minted scopes are the "auth" set, NOT the admin superset.
+        expect(validated.payload.scope).toBe("parachute:host:auth");
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("file path is the canonical operator.token under configDir", async () => {
+    const h = makeHarness();
+    try {
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        rotateSigningKey(db);
+        await issueOperatorToken(db, "user-abc", {
+          dir: h.dir,
+          issuer: LOOPBACK_ISSUER,
+          scopeSet: "start",
+        });
+        const status = await selfHealOperatorTokenIssuer(db, {
+          issuer: PUBLIC_ISSUER,
+          configDir: h.dir,
+        });
+        if (status.kind === "rotated") {
+          expect(status.path).toBe(join(h.dir, OPERATOR_TOKEN_FILENAME));
+        } else {
+          throw new Error(`expected rotated, got ${status.kind}`);
+        }
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+});

package/src/commands/lifecycle.ts

@@ -13,8 +13,10 @@ import {
   readHubPort,
   stopHub,
 } from "../hub-control.ts";
+import { hubDbPath, openHubDb } from "../hub-db.ts";
 import { HUB_ORIGIN_ENV, deriveHubOrigin } from "../hub-origin.ts";
 import { ModuleManifestError, readModuleManifest } from "../module-manifest.ts";
+import { type OperatorIssuerHealStatus, selfHealOperatorTokenIssuer } from "../operator-token.ts";
 import {
   type AliveFn,
   clearPid,
@@ -271,6 +273,18 @@ export interface LifecycleOpts {
   hub?: {
     ensureRunning?: (opts: EnsureHubOpts) => Promise<EnsureHubResult>;
     stop?: (opts: StopHubOpts) => Promise<boolean>;
+    /**
+     * Self-heal the operator token's stale `iss` after `start hub` (hub#481).
+     * Production opens hub.db at `<configDir>/hub.db` and delegates to
+     * `selfHealOperatorTokenIssuer`. Tests inject a stub to assert the call
+     * happens — or to make it throw and prove a self-heal failure never fails
+     * `start hub`.
+     */
+    selfHealOperatorToken?: (args: {
+      issuer: string;
+      configDir: string;
+      log: (line: string) => void;
+    }) => Promise<OperatorIssuerHealStatus>;
   };
 }
 
@@ -292,6 +306,35 @@ interface Resolved {
   hubOrigin: string | undefined;
   ensureHub: (opts: EnsureHubOpts) => Promise<EnsureHubResult>;
   stopHubFn: (opts: StopHubOpts) => Promise<boolean>;
+  selfHealOperatorTokenFn: (args: {
+    issuer: string;
+    configDir: string;
+    log: (line: string) => void;
+  }) => Promise<OperatorIssuerHealStatus>;
+}
+
+/**
+ * Production self-heal: open hub.db at `<configDir>/hub.db`, run
+ * `selfHealOperatorTokenIssuer`, and close the db. Derives the db path the
+ * same way the rest of the repo does (`hubDbPath(configDir)`); `openHubDb`
+ * runs migrations + WAL on open, matching `commands/auth.ts`. Tests override
+ * this whole seam, so the db-open only happens on the production path.
+ */
+async function defaultSelfHealOperatorToken(args: {
+  issuer: string;
+  configDir: string;
+  log: (line: string) => void;
+}): Promise<OperatorIssuerHealStatus> {
+  const db = openHubDb(hubDbPath(args.configDir));
+  try {
+    return await selfHealOperatorTokenIssuer(db, {
+      issuer: args.issuer,
+      configDir: args.configDir,
+      log: args.log,
+    });
+  } finally {
+    db.close();
+  }
 }
 
 function resolve(opts: LifecycleOpts): Resolved {
@@ -328,6 +371,7 @@ function resolve(opts: LifecycleOpts): Resolved {
     hubOrigin: resolveHubOrigin(opts.hubOrigin, configDir),
     ensureHub: opts.hub?.ensureRunning ?? ensureHubRunning,
     stopHubFn: opts.hub?.stop ?? stopHub,
+    selfHealOperatorTokenFn: opts.hub?.selfHealOperatorToken ?? defaultSelfHealOperatorToken,
   };
 }
 
@@ -774,6 +818,12 @@ async function startHubSvc(r: Resolved): Promise<number> {
     } else {
       r.log(`hub already running (pid ${result.pid}) on port ${result.port}.`);
     }
+    // Self-heal a stale operator-token issuer (hub#481). Runs whether the hub
+    // was freshly started OR already running — a token stamped at loopback
+    // before exposure must heal even when the hub is already up. The loopback /
+    // provenance guards live inside `selfHealOperatorTokenIssuer`, so the only
+    // gate here is "is there a real issuer to heal toward?".
+    await selfHealOperatorTokenOnStart(r);
     return 0;
   } catch (err) {
     r.log(`✗ hub failed to start: ${err instanceof Error ? err.message : String(err)}`);
@@ -781,6 +831,36 @@ async function startHubSvc(r: Resolved): Promise<number> {
   }
 }
 
+/**
+ * Re-issue the operator token under the hub's current origin when its `iss`
+ * went stale after an init-at-loopback → expose transition (hub#481). Mirrors
+ * `persistVaultHubOriginForStart`'s quiet style: emit a single line only when
+ * a rotation actually happens; stay silent for fresh / absent / skipped.
+ *
+ * The ENTIRE self-heal is wrapped here so it can NEVER block or fail
+ * `start hub` — a db-open error, a corrupt token, anything — degrades to a
+ * brief warning and `start hub` still returns 0.
+ */
+async function selfHealOperatorTokenOnStart(r: Resolved): Promise<void> {
+  if (!r.hubOrigin) return;
+  try {
+    const status = await r.selfHealOperatorTokenFn({
+      issuer: r.hubOrigin,
+      configDir: r.configDir,
+      log: r.log,
+    });
+    if (status.kind === "rotated") {
+      r.log(`  refreshed operator.token issuer → ${r.hubOrigin} (was stale after exposure)`);
+    }
+  } catch (err) {
+    r.log(
+      `  note: operator.token issuer self-heal skipped (${
+        err instanceof Error ? err.message : String(err)
+      })`,
+    );
+  }
+}
+
 /**
  * Stop the internal hub. `stopHub` returns false when nothing was running
  * (no pidfile, or stale pidfile cleared) — that's a clean no-op for the

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,
+  };
+}