@openparachute/hub 0.5.7 → 0.5.10-rc.2

package/src/commands/serve.ts

@@ -0,0 +1,157 @@
+/**
+ * `parachute serve` — long-running hub HTTP server, foregrounded.
+ *
+ * The on-box CLI flow (`parachute expose`) spawns hub-server detached and
+ * tracks it via pidfile. Container hosts (Docker, Render) need the inverse
+ * shape: the hub process IS PID 1 of the container, lives in the
+ * foreground, and exits with the container.
+ *
+ * This subcommand wires that path:
+ *
+ *   - Reads `PORT` (default 1939) and `PARACHUTE_HUB_ORIGIN` (the canonical
+ *     public origin Render exposes via custom domain) from env.
+ *   - Auto-writes `hub.html` into `~/.parachute/well-known/` so `/` serves a
+ *     real discovery page on a fresh disk without the operator having to
+ *     run `parachute expose` first.
+ *   - Seeds an initial admin from `PARACHUTE_INITIAL_ADMIN_USERNAME` +
+ *     `PARACHUTE_INITIAL_ADMIN_PASSWORD` on first boot when no admin
+ *     exists, so the wizard isn't a hard precondition.
+ *   - Starts the hub-server fetch loop bound to `0.0.0.0` (container hosts
+ *     need to accept the platform's HTTP forwarder, not just localhost).
+ *
+ * Stays out of pidfile/log-rotation logic — those are for the detached
+ * `parachute start hub` flow. A container supervisor (Docker, systemd,
+ * Render) owns process lifecycle; this command only owns the fetch loop.
+ */
+
+import { existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+// NOTE: CONFIG_DIR/WELL_KNOWN_DIR are evaluated at import time from process.env.PARACHUTE_HOME.
+// The `env` parameter on `serve()` cannot reroute them — set PARACHUTE_HOME before importing for path isolation.
+import { CONFIG_DIR } from "../config.ts";
+import { hubDbPath, openHubDb } from "../hub-db.ts";
+import { hubFetch } from "../hub-server.ts";
+import { writeHubFile } from "../hub.ts";
+import { createUser, userCount } from "../users.ts";
+import { WELL_KNOWN_DIR } from "../well-known.ts";
+
+export interface ServeOpts {
+  /** Override PORT (test-only). Real callers thread env via process.env. */
+  port?: number;
+  /** Override PARACHUTE_HUB_ORIGIN (test-only). */
+  issuer?: string;
+  /** Override the env source (test-only). */
+  env?: NodeJS.ProcessEnv;
+  /** Logger seam (test-only). */
+  log?: (line: string) => void;
+}
+
+export interface ServeResult {
+  port: number;
+  issuer?: string;
+  /**
+   * "seeded" — initial admin created from env vars.
+   * "exists" — admin row already present, env vars ignored.
+   * "needs-setup" — no admin and no env-var seed; wizard mode (the
+   * setup-placeholder redirect in hub-server.ts takes over).
+   */
+  adminBootstrap: "seeded" | "exists" | "needs-setup";
+}
+
+const DEFAULT_PORT = 1939;
+
+function parsePort(raw: string | undefined): number | undefined {
+  if (raw === undefined || raw === "") return undefined;
+  const n = Number.parseInt(raw, 10);
+  if (!Number.isInteger(n) || n <= 0 || n > 65535) {
+    throw new Error(`PORT must be 1..65535, got "${raw}"`);
+  }
+  return n;
+}
+
+/**
+ * Seed the initial admin from env vars when no admin exists. Returns the
+ * bootstrap state so the caller can log it for operator visibility.
+ *
+ * Boot-time idempotent: if an admin already exists, we leave it alone —
+ * `PARACHUTE_INITIAL_ADMIN_*` is a first-boot seed, not a reset switch.
+ * That keeps a container restart with the env vars still set from
+ * clobbering an admin who has since rotated their password.
+ */
+export async function seedInitialAdminIfNeeded(
+  db: ReturnType<typeof openHubDb>,
+  env: NodeJS.ProcessEnv,
+  log: (line: string) => void = () => {},
+): Promise<"seeded" | "exists" | "needs-setup"> {
+  if (userCount(db) > 0) return "exists";
+  const username = env.PARACHUTE_INITIAL_ADMIN_USERNAME?.trim();
+  const password = env.PARACHUTE_INITIAL_ADMIN_PASSWORD;
+  if (!username || !password) return "needs-setup";
+  await createUser(db, username, password);
+  log(`parachute serve: seeded initial admin "${username}" from PARACHUTE_INITIAL_ADMIN_*`);
+  return "seeded";
+}
+
+/**
+ * Run the hub fetch loop in the foreground. Resolves when `Bun.serve` is
+ * bound; the returned `stop()` shuts the server down for tests.
+ *
+ * The CLI dispatcher calls this without awaiting completion — `Bun.serve`
+ * runs the listener and the runtime keeps the process alive until a
+ * signal. Tests pass `port: 0` so the kernel picks an ephemeral port.
+ */
+export async function serve(opts: ServeOpts = {}): Promise<{
+  result: ServeResult;
+  stop: () => Promise<void>;
+}> {
+  const env = opts.env ?? process.env;
+  const log = opts.log ?? ((line) => console.log(line));
+
+  const envPort = parsePort(env.PORT);
+  const port = opts.port ?? envPort ?? DEFAULT_PORT;
+  const issuer = (opts.issuer ?? env.PARACHUTE_HUB_ORIGIN)?.replace(/\/+$/, "") || undefined;
+  // Containers default to 0.0.0.0 so the platform's HTTP forwarder can
+  // reach us; the `--hostname` flag / PARACHUTE_BIND_HOST is the escape
+  // hatch for setups that want loopback-only inside a sidecar.
+  const hostname = env.PARACHUTE_BIND_HOST || "0.0.0.0";
+
+  // Ensure the well-known dir exists, and seed a static hub.html so `/`
+  // serves something coherent on a fresh disk (the dynamic path through
+  // `hubFetch` takes over once a DB row exists; the disk file is the
+  // signed-out fallback).
+  if (!existsSync(WELL_KNOWN_DIR)) mkdirSync(WELL_KNOWN_DIR, { recursive: true });
+  const hubHtmlPath = join(WELL_KNOWN_DIR, "hub.html");
+  if (!existsSync(hubHtmlPath)) writeHubFile(hubHtmlPath);
+
+  const dbPath = hubDbPath();
+  const db = openHubDb(dbPath);
+  const adminBootstrap = await seedInitialAdminIfNeeded(db, env, log);
+
+  if (adminBootstrap === "needs-setup") {
+    log(
+      "parachute serve: no admin account configured. Set PARACHUTE_INITIAL_ADMIN_USERNAME + PARACHUTE_INITIAL_ADMIN_PASSWORD, or visit /admin/setup once the hub is reachable.",
+    );
+  }
+
+  const server = Bun.serve({
+    port,
+    hostname,
+    fetch: hubFetch(WELL_KNOWN_DIR, {
+      getDb: () => db,
+      issuer,
+      loopbackPort: port,
+    }),
+  });
+
+  log(
+    `parachute serve: listening on http://${hostname}:${port} (PARACHUTE_HOME=${CONFIG_DIR}, db=${dbPath}, issuer=${issuer ?? "<request-origin>"}, admin=${adminBootstrap})`,
+  );
+
+  return {
+    result: { port, ...(issuer !== undefined ? { issuer } : {}), adminBootstrap },
+    stop: async () => {
+      await server.stop();
+      db.close();
+    },
+  };
+}

package/src/commands/status.ts

@@ -1,5 +1,12 @@
 import { CONFIG_DIR, SERVICES_MANIFEST_PATH } from "../config.ts";
 import { HUB_SVC, readHubPort } from "../hub-control.ts";
+import {
+  type DetectInstallSourceDeps,
+  detectHubInstallSource,
+  detectInstallSource,
+  formatInstallSourceLabel,
+  isStale,
+} from "../install-source.ts";
 import { type AliveFn, defaultAlive, formatUptime, processState } from "../process-state.ts";
 import { canonicalPortForManifest, getSpec, shortNameForManifest } from "../service-spec.ts";
 import { type ServiceEntry, readManifest } from "../services-manifest.ts";
@@ -14,6 +21,19 @@ export interface StatusOpts {
   configDir?: string;
   alive?: AliveFn;
   now?: () => Date;
+  /**
+   * Test seam for install-source detection. Production reads the filesystem
+   * + shells out to git; tests inject stubs so each case (npm / bun-linked /
+   * unknown / stale) is exercised deterministically without depending on
+   * the operator's actual bun globals.
+   */
+  installSourceDeps?: DetectInstallSourceDeps;
+  /**
+   * Directory containing the running hub source. Defaults to `import.meta.dir`
+   * (the directory of this file). Tests override so the hub row's install
+   * source classification doesn't depend on the test runner's location.
+   */
+  hubSrcDir?: string;
 }
 
 export interface ProbeResult {
@@ -71,6 +91,7 @@ interface StatusRow {
   uptimeLabel: string;
   healthLabel: string;
   latencyLabel: string;
+  sourceLabel: string;
   url: string | undefined;
   healthy: boolean;
   skipped: boolean;
@@ -82,6 +103,13 @@ interface StatusRow {
    * hard-erroring on a deliberate operator port change.
    */
   driftWarning?: string;
+  /**
+   * Version-drift indicator (hub#243). Set when a bun-linked service's
+   * `services.json.version` lags the live `package.json` version at its
+   * checkout. Surfaced as a continuation line so operators can spot a
+   * stale-after-rebuild row without comparing columns by eye.
+   */
+  staleNote?: string;
 }
 
 /**
@@ -98,7 +126,13 @@ function urlForEntry(entry: ServiceEntry, short: string | undefined): string | u
   return `http://127.0.0.1:${entry.port}${first}`;
 }
 
-function hubRow(configDir: string, alive: AliveFn, nowDate: Date): StatusRow | undefined {
+function hubRow(
+  configDir: string,
+  alive: AliveFn,
+  nowDate: Date,
+  hubSrcDir: string,
+  installSourceDeps: DetectInstallSourceDeps,
+): StatusRow | undefined {
   const proc = processState(HUB_SVC, configDir, alive);
   if (proc.status === "unknown") return undefined;
   const port = readHubPort(configDir);
@@ -107,15 +141,17 @@ function hubRow(configDir: string, alive: AliveFn, nowDate: Date): StatusRow | u
   const pidLabel = proc.status === "running" && proc.pid !== undefined ? String(proc.pid) : "-";
   const uptimeLabel =
     proc.status === "running" && proc.startedAt ? formatUptime(proc.startedAt, nowDate) : "-";
+  const source = detectHubInstallSource(hubSrcDir, installSourceDeps);
   return {
     service: "parachute-hub (internal)",
     port: portLabel,
-    version: "-",
+    version: source.livePackageVersion ?? "-",
     processLabel,
     pidLabel,
     uptimeLabel,
     healthLabel: "-",
     latencyLabel: "-",
+    sourceLabel: formatInstallSourceLabel(source),
     url: port !== undefined ? `http://127.0.0.1:${port}` : undefined,
     healthy: true,
     skipped: true,
@@ -130,6 +166,8 @@ export async function status(opts: StatusOpts = {}): Promise<number> {
   const configDir = opts.configDir ?? CONFIG_DIR;
   const alive = opts.alive ?? defaultAlive;
   const now = opts.now ?? (() => new Date());
+  const installSourceDeps = opts.installSourceDeps ?? {};
+  const hubSrcDir = opts.hubSrcDir ?? import.meta.dir;
 
   const manifest = readManifest(manifestPath);
   if (manifest.services.length === 0) {
@@ -178,6 +216,17 @@ export async function status(opts: StatusOpts = {}): Promise<number> {
           ? `canonical port is ${canonical}`
           : undefined;
 
+      // Install-source detection (hub#243). One filesystem walk + maybe one
+      // `git rev-parse` per row. Failures degrade silently to `unknown` —
+      // status output should never error out on a missing checkout dir.
+      const detectArgs: { entryName: string; installDir?: string } = { entryName: entry.name };
+      if (entry.installDir !== undefined) detectArgs.installDir = entry.installDir;
+      const source = detectInstallSource(detectArgs, installSourceDeps);
+      const sourceLabel = formatInstallSourceLabel(source);
+      const staleNote = isStale(entry.version, source)
+        ? `STALE: services.json cached ${entry.version}; live package.json ${source.livePackageVersion}`
+        : undefined;
+
       // Only skip probe when we know the process is dead (PID file was
       // present but kill(pid, 0) failed). "unknown" status (no PID file)
       // still probes — externally-managed services should report health.
@@ -191,10 +240,12 @@ export async function status(opts: StatusOpts = {}): Promise<number> {
           uptimeLabel,
           healthLabel: "-",
           latencyLabel: "-",
+          sourceLabel,
           url,
           healthy: false,
           skipped: true,
           driftWarning,
+          staleNote,
         };
       }
 
@@ -213,20 +264,32 @@ export async function status(opts: StatusOpts = {}): Promise<number> {
         uptimeLabel,
         healthLabel,
         latencyLabel: `${p.latencyMs}ms`,
+        sourceLabel,
         url,
         healthy: p.healthy,
         skipped: false,
         driftWarning,
+        staleNote,
       };
     }),
   );
 
   // Hub is an internal service — not in services.json, but users notice
   // when it's dead. Only show it if we've seen it run.
-  const hub = hubRow(configDir, alive, nowDate);
+  const hub = hubRow(configDir, alive, nowDate, hubSrcDir, installSourceDeps);
   if (hub) rows.push(hub);
 
-  const header = ["SERVICE", "PORT", "VERSION", "PROCESS", "PID", "UPTIME", "HEALTH", "LATENCY"];
+  const header = [
+    "SERVICE",
+    "PORT",
+    "VERSION",
+    "PROCESS",
+    "PID",
+    "UPTIME",
+    "HEALTH",
+    "LATENCY",
+    "SOURCE",
+  ];
   const textRows = rows.map((r) => [
     r.service,
     r.port,
@@ -236,14 +299,17 @@ export async function status(opts: StatusOpts = {}): Promise<number> {
     r.uptimeLabel,
     r.healthLabel,
     r.latencyLabel,
+    r.sourceLabel,
   ]);
   const widths = header.map((_, i) =>
     Math.max(header[i]?.length ?? 0, ...textRows.map((r) => r[i]?.length ?? 0)),
   );
   print(formatRow(header, widths));
-  // URL stays on a continuation line rather than a column. URLs are long
-  // (vault's MCP path runs ~40 chars), and a ninth column would push the
-  // table past 80 cols on every install. The "  → " prefix groups visually
+  // URL, drift, and stale notes stay on continuation lines rather than
+  // columns. URLs are long (vault's MCP path runs ~40 chars); SOURCE labels
+  // can be long for bun-linked rows. Spreading them across columns would
+  // push the table well past 80 cols on every install — continuation lines
+  // keep the table scannable. The "  → " / "  ! " prefixes group visually
   // with the row above without misleading the table widths.
   for (let i = 0; i < textRows.length; i++) {
     const cells = textRows[i];
@@ -251,10 +317,8 @@ export async function status(opts: StatusOpts = {}): Promise<number> {
     if (!cells || !row) continue;
     print(formatRow(cells, widths));
     if (row.url) print(`  → ${row.url}`);
-    // Drift warning rides as its own continuation line. Plain ASCII (no
-    // emoji / unicode glyphs) for terminal compatibility — the same
-    // surface that prints to scripts piping `parachute status`.
     if (row.driftWarning) print(`  ! ${row.driftWarning}`);
+    if (row.staleNote) print(`  ! ${row.staleNote}`);
   }
 
   /**

package/src/commands/upgrade.ts

@@ -38,6 +38,7 @@ import { existsSync, readFileSync, realpathSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { CONFIG_DIR, SERVICES_MANIFEST_PATH } from "../config.ts";
+import { HUB_PACKAGE, HUB_SVC } from "../hub-control.ts";
 import { ModuleManifestError } from "../module-manifest.ts";
 import {
   type ServiceSpec,
@@ -149,16 +150,38 @@ function resolve(opts: UpgradeOpts): Resolved {
   };
 }
 
+/**
+ * Synthetic services.json row for the hub. The hub isn't in services.json
+ * (it's an implementation detail of `parachute expose`, not a user-facing
+ * service), so callers passing `hub` as the upgrade target need a fabricated
+ * `ResolvedTarget`. Only `installDir` is read downstream — left undefined so
+ * `findGlobalInstall("@openparachute/hub")` is the sole locate path, which
+ * works the same for npm installs and `bun link` checkouts.
+ */
+function hubTarget(): ResolvedTarget {
+  const entry: ServiceEntry = {
+    name: HUB_PACKAGE,
+    port: 0,
+    paths: [],
+    health: "",
+    version: "",
+  };
+  return { short: HUB_SVC, entry, spec: undefined, packageName: HUB_PACKAGE };
+}
+
 async function resolveTargets(
   svc: string | undefined,
   manifestPath: string,
 ): Promise<{ targets: ResolvedTarget[] } | { error: string }> {
   const manifest = readManifest(manifestPath);
-  if (manifest.services.length === 0) {
-    return { error: "No services installed yet. Try: parachute install <service>" };
-  }
 
   if (svc !== undefined) {
+    if (svc === HUB_SVC) return { targets: [hubTarget()] };
+
+    if (manifest.services.length === 0) {
+      return { error: "No services installed yet. Try: parachute install <service>" };
+    }
+
     const firstPartySpec = getSpec(svc);
     if (firstPartySpec) {
       const entry = manifest.services.find((s) => s.name === firstPartySpec.manifestName);
@@ -183,10 +206,15 @@ async function resolveTargets(
         throw err;
       }
     }
-    return { error: `unknown service "${svc}". known: ${knownServices().join(", ")}` };
+    return {
+      error: `unknown service "${svc}". known: ${[HUB_SVC, ...knownServices()].join(", ")}`,
+    };
   }
 
-  const targets: ResolvedTarget[] = [];
+  // Sweep mode: hub first, then everything in services.json. Hub-first means a
+  // dispatcher upgrade can't be undermined mid-sweep by a service upgrade that
+  // restarts hub for reasons unrelated to its own code change.
+  const targets: ResolvedTarget[] = [hubTarget()];
   for (const entry of manifest.services) {
     const short = shortNameForManifest(entry.name);
     if (short) {
@@ -209,7 +237,6 @@ async function resolveTargets(
       }
     }
   }
-  if (targets.length === 0) return { error: "No upgradeable services in services.json." };
   return { targets };
 }
 

package/src/csrf.ts

@@ -19,9 +19,12 @@
  * pre-login and post-login forms, and it works no matter how many tabs the
  * operator has open.
  *
- * The cookie is HttpOnly (the form doesn't need JS to read it; the server
- * embeds the value at render time), SameSite=Lax (matches the session
- * cookie), Secure, and Path=/ (covers every admin form, OAuth or otherwise).
+ * The cookie is HttpOnly: consumers receive the token value via either the
+ * server-rendered HTML form (cookie + embedded value, classic double-submit)
+ * or via the JSON body of `/api/me` (cookie alongside body — same pattern,
+ * just JSON instead of HTML). Neither path needs JS to read the cookie
+ * directly. SameSite=Lax (matches the session cookie), Secure, and Path=/
+ * (covers every admin form, OAuth flow, and `/api/me` consumer).
  *
  * Token entropy: 32 random bytes, base64url-encoded — same shape as session
  * IDs. No HMAC needed: the value is opaque to the client and only ever

package/src/help.ts

@@ -17,6 +17,7 @@ Usage:
   parachute logs <service> [-f]     print service logs; -f to tail
   parachute expose tailnet [off]    HTTPS across your tailnet (supported)
   parachute expose public  [off]    HTTPS on the public internet (exploratory)
+  parachute serve                   run hub HTTP server foregrounded (for containers)
   parachute migrate [--dry-run]     archive legacy files at ecosystem root
   parachute auth <cmd>              identity (set password, manage 2FA)
   parachute vault <args...>         vault-specific ops (tokens, 2fa, config, init,
@@ -124,7 +125,7 @@ Examples:
 }
 
 export function statusHelp(): string {
-  return `parachute status — show installed services, process state, and health
+  return `parachute status — show installed services, process state, health, install source
 
 Usage:
   parachute status
@@ -133,22 +134,28 @@ What it does:
   Reads ~/.parachute/services.json. For each registered service:
     - checks PID file at ~/.parachute/<svc>/run/<svc>.pid → running/stopped
     - probes http://localhost:<port><health> (skipped for known-stopped processes)
+    - classifies the install source as bun-linked (local checkout) or npm
 
   Stopped services show "-" for health and don't count toward the exit
   code — they're an expected state after fresh install before \`parachute
   start\`. Running or externally-managed services that fail health checks
   do exit 1.
 
+  A "STALE: services.json cached … live package.json …" continuation line
+  appears under a row when a bun-linked service has been rebuilt but the
+  manifest's cached version hasn't caught up — re-install (\`parachute
+  install <pkg>\`) refreshes the row.
+
 Exit codes:
   0   all probed services healthy (or none running)
   1   one or more probed services unhealthy
 
 Example:
   $ parachute status
-  SERVICE          PORT  VERSION  PROCESS  PID    UPTIME  HEALTH  LATENCY
-  parachute-vault  1940  0.2.4    running  12345  2h 13m  ok      2ms
+  SERVICE          PORT  VERSION  PROCESS  PID    UPTIME  HEALTH  LATENCY  SOURCE
+  parachute-vault  1940  0.2.4    running  12345  2h 13m  ok      2ms      bun-linked → parachute-vault @ 8aa167b
     → http://127.0.0.1:1940/vault/default/mcp
-  parachute-notes  1942  0.0.1    stopped  -      -       -       -
+  parachute-notes  1942  0.0.1    stopped  -      -       -       -        npm (0.3.15-rc.1)
     → http://127.0.0.1:1942/notes
 `;
 }
@@ -342,8 +349,9 @@ What it does:
   Re-running on an up-to-date install is a fast no-op.
 
 Examples:
-  parachute upgrade                 sweep every installed service
+  parachute upgrade                 sweep hub + every installed service
   parachute upgrade vault           just vault
+  parachute upgrade hub             upgrade the dispatcher itself (closes #251)
   parachute upgrade vault --tag rc  pin the rc dist-tag (npm path only)
 `;
 }
@@ -363,6 +371,47 @@ If no log file exists yet, prints a hint to \`parachute start <service>\`.
 `;
 }
 
+export function serveHelp(): string {
+  return `parachute serve — run the hub HTTP server foregrounded
+
+Usage:
+  parachute serve
+
+The container shape. The on-box CLI flow (\`parachute expose\`) spawns the
+hub-server detached and tracks it via pidfile; \`parachute serve\` is the
+inverse — the hub IS the foreground process, lives as long as its
+supervisor wants it to, and exits on signal. Built for Docker / Render /
+systemd, but works fine for a foregrounded local debug too.
+
+Environment:
+  PORT                              bind port (default 1939). Render injects
+                                    this; honor it so the platform's HTTP
+                                    forwarder lands on the right socket.
+  PARACHUTE_HOME                    config root (default ~/.parachute).
+                                    Point at a persistent disk in containers.
+  PARACHUTE_HUB_ORIGIN              canonical https://… origin baked into
+                                    OAuth issuer + token aud claims. Set to
+                                    the public hostname Render / Cloudflare
+                                    serves.
+  PARACHUTE_INITIAL_ADMIN_USERNAME  on first boot when no admin row exists,
+  PARACHUTE_INITIAL_ADMIN_PASSWORD  seed an admin from these. Boot-time
+                                    idempotent — ignored once an admin
+                                    exists, so leaving them set across
+                                    restarts is safe.
+
+If no admin exists and the seed env vars aren't set, the hub still comes
+up — visit \`/admin/setup\` to bootstrap via the placeholder wizard.
+
+Examples:
+  parachute serve                          # foreground, defaults
+  PORT=8080 PARACHUTE_HOME=/parachute parachute serve
+  docker run -e PARACHUTE_INITIAL_ADMIN_USERNAME=ops \\
+             -e PARACHUTE_INITIAL_ADMIN_PASSWORD=… \\
+             -v parachute-data:/parachute \\
+             parachute-hub:0.5.10 serve
+`;
+}
+
 export function migrateHelp(): string {
   return `parachute migrate — archive legacy files at the ecosystem root
 

package/src/hub-control.ts

@@ -27,6 +27,7 @@ import { WELL_KNOWN_DIR } from "./well-known.ts";
  */
 
 export const HUB_SVC = "hub";
+export const HUB_PACKAGE = "@openparachute/hub";
 export const HUB_DEFAULT_PORT = 1939;
 /**
  * Default fallback range is 1 — the hub binds 1939 or fails. Walking up would

package/src/hub-db.ts

@@ -130,6 +130,69 @@ const MIGRATIONS: readonly Migration[] = [
       CREATE INDEX tokens_family ON tokens (family_id) WHERE family_id IS NOT NULL;
     `,
   },
+  {
+    version: 6,
+    sql: `
+      -- Token registry generalization (closes hub#212 Phase 1). Until v6 the
+      -- tokens table only held OAuth refresh tokens; v6 generalizes it to a
+      -- single registry across every issued JWT class (refresh, access,
+      -- operator, mint-token). Three structural changes:
+      --
+      --   1. user_id becomes NULLABLE. OAuth-issued rows still set it to the
+      --      caller's user (canonical identity field). CLI-minted /
+      --      operator-minted rows leave user_id NULL and put the operator/
+      --      service name in the new \`subject\` column.
+      --   2. Three new columns: \`permissions\` (JSON, custom claim per
+      --      auth-architecture-shape.md §11.3), \`created_via\` (provenance
+      --      tag: oauth_refresh / cli_mint / operator_mint), \`subject\`
+      --      (non-user identity for service / operator mints).
+      --   3. Existing rows backfill \`created_via='oauth_refresh'\` because
+      --      the table was OAuth-refresh-only before v6.
+      --
+      -- SQLite has no ALTER COLUMN to drop NOT NULL, so we use the
+      -- recreate-and-rename pattern. Inside the migration transaction the
+      -- whole swap is atomic; concurrent reads (there are none — hub is
+      -- single-writer) wouldn't see a half-state. FKs from tokens → users
+      -- stay enforced for non-NULL user_id values; nothing references
+      -- tokens, so the drop is safe.
+      CREATE TABLE tokens_new (
+        jti TEXT PRIMARY KEY,
+        user_id TEXT REFERENCES users(id),
+        client_id TEXT NOT NULL,
+        scopes TEXT NOT NULL,
+        refresh_token_hash TEXT,
+        family_id TEXT,
+        expires_at TEXT NOT NULL,
+        revoked_at TEXT,
+        created_at TEXT NOT NULL,
+        permissions TEXT,
+        created_via TEXT NOT NULL DEFAULT 'oauth_refresh',
+        subject TEXT
+      );
+      INSERT INTO tokens_new (
+        jti, user_id, client_id, scopes, refresh_token_hash, family_id,
+        expires_at, revoked_at, created_at,
+        permissions, created_via, subject
+      )
+      SELECT
+        jti, user_id, client_id, scopes, refresh_token_hash, family_id,
+        expires_at, revoked_at, created_at,
+        NULL, 'oauth_refresh', NULL
+      FROM tokens;
+      DROP TABLE tokens;
+      ALTER TABLE tokens_new RENAME TO tokens;
+      -- Recreate indexes (DROP TABLE took them with it).
+      CREATE INDEX tokens_user ON tokens (user_id) WHERE user_id IS NOT NULL;
+      CREATE INDEX tokens_active_refresh ON tokens (refresh_token_hash)
+        WHERE refresh_token_hash IS NOT NULL AND revoked_at IS NULL;
+      CREATE INDEX tokens_family ON tokens (family_id) WHERE family_id IS NOT NULL;
+      -- New: revocation list endpoint queries on (revoked_at, expires_at).
+      CREATE INDEX tokens_revoked ON tokens (revoked_at)
+        WHERE revoked_at IS NOT NULL;
+      -- Subject lookup for non-user mints (operator name, service name).
+      CREATE INDEX tokens_subject ON tokens (subject) WHERE subject IS NOT NULL;
+    `,
+  },
 ];
 
 export function openHubDb(path: string = hubDbPath()): Database {