@openparachute/hub 0.6.5-rc.7 → 0.7.0

package/src/api-tokens.ts

@@ -23,7 +23,7 @@
  *         "expires_at": "ISO-8601",
  *         "revoked_at": "ISO-8601" | null,
  *         "created_at": "ISO-8601",
- *         "created_via": "oauth_refresh" | "cli_mint" | "operator_mint",
+ *         "created_via": "oauth_refresh" | "cli_mint" | "operator_mint" | "connection_provision",
  *         "permissions": "<json-string>" | null
  *       }
  *     ],
@@ -45,8 +45,10 @@
  *   - `created_via=<value>` — narrow by mint provenance. One of
  *     `oauth_refresh` (OAuth refresh-token rotation), `operator_mint`
  *     (operator-token rotation via `parachute auth rotate-operator`),
- *     or `cli_mint` (CLI / `POST /api/auth/mint-token`). Powers the
- *     admin UI's "by source" filter pills (hub#212 Phase F).
+ *     `cli_mint` (CLI / `POST /api/auth/mint-token`), or
+ *     `connection_provision` (long-lived tokens the Connections engine
+ *     mints — see admin-connections.ts). Powers the admin UI's
+ *     "by source" filter pills (hub#212 Phase F).
  *
  * Why bearer-gated rather than session-cookie-gated: matches the rest
  * of `/api/auth/*` (mint-token, revoke-token), so an automation client
@@ -149,14 +151,15 @@ export async function handleApiTokens(req: Request, deps: ApiTokensDeps): Promis
   if (
     createdViaParam === "oauth_refresh" ||
     createdViaParam === "operator_mint" ||
-    createdViaParam === "cli_mint"
+    createdViaParam === "cli_mint" ||
+    createdViaParam === "connection_provision"
   ) {
     createdVia = createdViaParam;
   } else if (createdViaParam !== null) {
     return jsonError(
       400,
       "invalid_request",
-      "created_via must be one of: oauth_refresh | operator_mint | cli_mint",
+      "created_via must be one of: oauth_refresh | operator_mint | cli_mint | connection_provision",
     );
   }
   const cursor = url.searchParams.get("cursor");

package/src/commands/serve-boot.ts

@@ -22,11 +22,12 @@ import { HUB_ORIGIN_ENV } from "../hub-origin.ts";
 import { ModuleManifestError } from "../module-manifest.ts";
 import {
   type ServiceSpec,
+  canonicalPortForManifest,
   getSpec,
   getSpecFromInstallDir,
   shortNameForManifest,
 } from "../service-spec.ts";
-import { type ServiceEntry, readManifestLenient } from "../services-manifest.ts";
+import { type ServiceEntry, readManifestLenient, upsertService } from "../services-manifest.ts";
 import { enrichedPath } from "../spawn-path.ts";
 import type { Supervisor } from "../supervisor.ts";
 
@@ -69,6 +70,77 @@ export interface BuildSpawnRequestOpts {
   readonly extraEnv?: Record<string, string>;
 }
 
+/**
+ * Snap a fixed-port first-party module's services.json `port` back to its
+ * compiled-in canonical value when it has DRIFTED, and persist the correction.
+ * Returns the entry to spawn with — reconciled when a drift was repaired, the
+ * original otherwise.
+ *
+ * Why (channel#41): the hub is the port authority, and a first-party module
+ * with a compiled-in canonical port (`canonicalPortForManifest` ≠ undefined —
+ * vault / scribe / surface / channel / notes / runner) has exactly ONE correct
+ * port: its canonical one. The injected `PORT`, the supervisor's readiness
+ * probe, and the reverse-proxy target are ALL derived from the services.json
+ * row's `port`. So once a transiently-wrong port lands in that row (the channel
+ * row was observed live carrying `19415` instead of `1941`), it self-perpetuates:
+ * the supervisor probes/proxies the wrong port forever and `/channel/*` routes
+ * to a dead port. The canonical port is authoritative, so we reconcile the row
+ * before spawn rather than honoring the drift.
+ *
+ * Safety for the other fixed-port modules (vault / scribe / surface): the
+ * canonical value is exactly what each ALREADY self-registers, so on the
+ * common path `entry.port === canonical` and this is a no-op. There is no
+ * legitimate "first-party module intentionally on a non-canonical port" case —
+ * install-time `assignPort` only walks off canonical on a genuine collision,
+ * and that's a same-range fallback for a DIFFERENT module, never a steady state
+ * for the canonical owner. If another row genuinely already owns the canonical
+ * port we DON'T rewrite (it would trip the write-side duplicate-port guard and
+ * isn't ours to take) — we leave the drift in place and let the supervisor's
+ * port-squatter detection surface it. Third-party modules (no canonical) are
+ * never touched.
+ */
+export function reconcilePortToCanonical(
+  entry: ServiceEntry,
+  manifestPath: string,
+  log: (line: string) => void = () => {},
+): ServiceEntry {
+  const canonical = canonicalPortForManifest(entry.name);
+  if (canonical === undefined || entry.port === canonical) return entry;
+
+  // Don't steal a canonical port another row legitimately holds — that would
+  // trip `upsertService`'s duplicate-port guard. Re-read live so we see the
+  // current on-disk state (another module may have just registered).
+  const others = readManifestLenient(manifestPath).services.filter((s) => s.name !== entry.name);
+  if (others.some((s) => s.port === canonical)) {
+    log(
+      `[supervisor] ${entry.name}: services.json port ${entry.port} ≠ canonical ${canonical}, ` +
+        `but ${canonical} is held by another row — not reconciling; surfacing the drift.`,
+    );
+    return entry;
+  }
+
+  const reconciled: ServiceEntry = { ...entry, port: canonical };
+  try {
+    upsertService(reconciled, manifestPath);
+    log(
+      `[supervisor] ${entry.name}: reconciled drifted services.json port ${entry.port} → canonical ${canonical} (channel#41).`,
+    );
+    return reconciled;
+  } catch (err) {
+    // Best-effort: a failed reconcile must not block the boot. The write can
+    // fail for an I/O reason (permissions, races against an external writer) OR
+    // because `upsertService`'s duplicate-port guard tripped — e.g. another row
+    // raced onto the canonical port between the check above and this write.
+    // Either way, spawn with the canonical port in-memory so at least the child
+    // binds + the probe checks the right port this run; the proxy still reads
+    // the (stale) row until the next reconcile succeeds.
+    log(
+      `[supervisor] ${entry.name}: could not reconcile services.json port to canonical (${entry.port} → ${canonical}; write failed or canonical held): ${err} — spawning with canonical in-memory.`,
+    );
+    return reconciled;
+  }
+}
+
 /**
  * Build the `Supervisor.start` request for a single module, identically on
  * both the serve-boot path and the `POST /api/modules/:short/start` handler.
@@ -166,7 +238,12 @@ export async function bootSupervisedModules(
       continue;
     }
 
-    const cmd = spec.startCmd?.(entry);
+    // Snap a drifted fixed-port row back to canonical before we derive PORT /
+    // probe / proxy from it (channel#41). No-op on the common path where the
+    // module already sits on its canonical port.
+    const spawnEntry = reconcilePortToCanonical(entry, opts.manifestPath, log);
+
+    const cmd = spec.startCmd?.(spawnEntry);
     if (!cmd || cmd.length === 0) {
       log(`[supervisor] ${short}: spec resolved but no startCmd — skipping (CLI-only module).`);
       results.push({
@@ -182,7 +259,7 @@ export async function bootSupervisedModules(
     // .env merge, and PARACHUTE_HUB_ORIGIN propagation (hub#365) all live in the
     // shared `buildModuleSpawnRequest` so the `POST /api/modules/:short/start`
     // handler builds an identical request (design 2026-06-01 §3.3).
-    const req = buildModuleSpawnRequest(short, entry, cmd, {
+    const req = buildModuleSpawnRequest(short, spawnEntry, cmd, {
       configDir: opts.configDir,
       ...(opts.hubOrigin !== undefined ? { hubOrigin: opts.hubOrigin } : {}),
     });

package/src/commands/setup.ts

@@ -74,7 +74,7 @@ interface ServiceChoice {
   manifestName: string;
   /** Per-service URL composer used in the final-summary banner. Optional. */
   urlForEntry?: (entry: ServiceEntry) => string | undefined;
-  /** Full spec when available (FIRST_PARTY_FALLBACKS shorts: notes / channel). */
+  /** Full spec when available (FIRST_PARTY_FALLBACKS shorts: notes). */
   spec?: ServiceSpec;
 }
 
@@ -114,9 +114,9 @@ function defaultAvailability(): InteractiveAvailability {
  * the service has a row in services.json.
  *
  * The full ServiceSpec is only available pre-install for FIRST_PARTY_FALLBACKS
- * shorts (notes / channel — they carry a vendored manifest). KNOWN_MODULES
- * shorts (vault / scribe / runner) ship `.parachute/module.json` and
- * self-register; pre-install we know manifestName + the urlForEntry quirk
+ * shorts (notes — it carries a vendored manifest). KNOWN_MODULES shorts
+ * (vault / scribe / runner / channel / surface) ship `.parachute/module.json`
+ * and self-register; pre-install we know manifestName + the urlForEntry quirk
  * from `KNOWN_MODULES[short].extras`, which is all the survey/summary needs.
  */
 function surveyServices(manifestPath: string): ServiceChoice[] {

package/src/connections-store.ts

@@ -0,0 +1,161 @@
+/**
+ * `connections.json` — the persisted registry of operator-created Connections
+ * (2026-06-09 modular-UI architecture, P5).
+ *
+ * A **connection** wires "when [EVENT] in [source module] (filter) → do [ACTION]
+ * in [sink module]". The hub is the only thing with cross-module authority
+ * (mint tokens, register vault triggers), so connections are hub-native + the
+ * record of what got provisioned lives here, in the hub state dir.
+ *
+ * One file, a flat array of records. Each record carries enough to (a) render
+ * the Connections list and (b) tear down what was provisioned — notably the
+ * `provisioned.triggerName` + `provisioned.vault` so DELETE can remove the exact
+ * vault trigger that was registered. We keep the store deliberately small +
+ * synchronous (Bun file I/O); the cardinality is "a handful of connections per
+ * hub", not a hot path.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+/** The source side — an event a module emits, with an operator-set filter. */
+export interface ConnectionSource {
+  /** Source module short name, e.g. `vault`. */
+  readonly module: string;
+  /** For vault events, which vault instance the event is scoped to. */
+  readonly vault?: string;
+  /** Event key declared in the source module's `module.json`, e.g. `note.created`. */
+  readonly event: string;
+  /**
+   * Operator-set filter, shaped by the event's `filterSchema`. For a vault
+   * event this maps to the trigger predicate (`tags` / `has_metadata` /
+   * `missing_metadata` / `has_content`).
+   */
+  readonly filter?: Record<string, unknown>;
+}
+
+/** The sink side — an action a module accepts (the sink is ALWAYS an action). */
+export interface ConnectionSink {
+  /** Sink module short name, e.g. `channel`. */
+  readonly module: string;
+  /** Action key declared in the sink module's `module.json`, e.g. `message.deliver`. */
+  readonly action: string;
+  /** Action params, shaped by the action's `inputSchema` (e.g. `{ channel }`). */
+  readonly params?: Record<string, unknown>;
+}
+
+/** What the provisioning engine actually wired, for teardown + display. */
+export interface ConnectionProvisioned {
+  /** How the action was provisioned, e.g. `vault-trigger`. */
+  readonly type: string;
+  /** The vault instance the trigger was registered on (vault-trigger). */
+  readonly vault?: string;
+  /** The exact vault trigger name registered — DELETE removes this. */
+  readonly triggerName?: string;
+  /**
+   * jtis of the LONG-LIVED tokens minted for this connection (the webhook
+   * bearer, and for a channel sink the vault-write reply token). Each is
+   * registered in the hub's tokens table (`created_via='connection_provision'`)
+   * at mint time so teardown can revoke them — an unregistered long-lived
+   * token is unrevocable by construction (hub-module-boundary charter,
+   * registered-mint rule). Records written before this field existed read back
+   * as `undefined`; their tokens were never registered and ride to expiry
+   * (surfaced as `legacy: true` in the list wire shape).
+   */
+  readonly mintedJtis?: readonly string[];
+}
+
+export interface ConnectionRecord {
+  readonly id: string;
+  readonly source: ConnectionSource;
+  readonly sink: ConnectionSink;
+  readonly provisioned: ConnectionProvisioned;
+  readonly createdAt: string;
+  /**
+   * Provenance — WHO requested this connection (modular-UI R2, module-initiated
+   * connections). A module-owned config UI that creates a connection on the
+   * operator's behalf (e.g. the channel admin page's "link to a vault" flow)
+   * labels itself here (e.g. `"channel"`); a connection built by hand in the
+   * hub's own Connections builder is `"custom"`. Lets the operator see which
+   * connections a module initiated vs which they wired themselves. Optional for
+   * back-compat: records written before R2 read back as `undefined`, which the
+   * SPA treats as `"custom"`.
+   */
+  readonly requestedBy?: string;
+}
+
+interface ConnectionsFile {
+  connections: ConnectionRecord[];
+}
+
+function emptyFile(): ConnectionsFile {
+  return { connections: [] };
+}
+
+/** Read the store. A missing/garbage file reads as empty (fresh hub). */
+export function readConnections(storePath: string): ConnectionRecord[] {
+  let buf: string;
+  try {
+    buf = readFileSync(storePath, "utf8");
+  } catch {
+    return [];
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(buf);
+  } catch {
+    return [];
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return [];
+  const arr = (parsed as { connections?: unknown }).connections;
+  if (!Array.isArray(arr)) return [];
+  // Lenient: drop any malformed row rather than failing the whole read, so one
+  // bad hand-edit doesn't take down the Connections view (mirrors the
+  // services.json lenient-read posture).
+  return arr.filter((r): r is ConnectionRecord => {
+    if (!r || typeof r !== "object") return false;
+    const rec = r as Record<string, unknown>;
+    return (
+      typeof rec.id === "string" &&
+      !!rec.source &&
+      typeof rec.source === "object" &&
+      !!rec.sink &&
+      typeof rec.sink === "object"
+    );
+  });
+}
+
+function writeAll(storePath: string, records: ConnectionRecord[]): void {
+  mkdirSync(dirname(storePath), { recursive: true });
+  const file: ConnectionsFile = { connections: records };
+  // Written WITHOUT 0o600 because this file holds NO secrets — the provisioned
+  // webhook bearer lives only in the vault trigger's row, never here; records
+  // carry source/sink/trigger-name metadata only. Consistent with the default
+  // perms on services.json / expose-state.json.
+  writeFileSync(storePath, `${JSON.stringify(file, null, 2)}\n`);
+}
+
+/** Upsert by id (replace an existing record with the same id, else append). */
+export function putConnection(storePath: string, record: ConnectionRecord): void {
+  const records = readConnections(storePath);
+  const idx = records.findIndex((r) => r.id === record.id);
+  if (idx >= 0) records[idx] = record;
+  else records.push(record);
+  writeAll(storePath, records);
+}
+
+/** Remove a connection by id. Returns the removed record, or null if absent. */
+export function removeConnection(storePath: string, id: string): ConnectionRecord | null {
+  const records = readConnections(storePath);
+  const idx = records.findIndex((r) => r.id === id);
+  if (idx < 0) return null;
+  const [removed] = records.splice(idx, 1);
+  writeAll(storePath, records);
+  return removed ?? null;
+}
+
+export function getConnection(storePath: string, id: string): ConnectionRecord | null {
+  return readConnections(storePath).find((r) => r.id === id) ?? null;
+}
+
+/** Re-export for the unused-import linter when only the type is consumed. */
+export const _emptyConnectionsFile = emptyFile;

package/src/grants.ts

@@ -26,6 +26,7 @@
  */
 
 import type { Database } from "bun:sqlite";
+import { vaultScopeName } from "./scope-explanations.ts";
 
 export interface Grant {
   userId: string;
@@ -324,3 +325,52 @@ export function revokeGrant(db: Database, userId: string, clientId: string): boo
     .run(userId, clientId);
   return res.changes > 0;
 }
+
+/**
+ * Vault-delete cascade step (B1, 2026-06-09 hub-module-boundary): REWRITE
+ * every grant whose scope list names the deleted vault, removing the
+ * `vault:<name>:<verb>` entries; DROP the row only when the rewrite leaves
+ * it empty.
+ *
+ * Rewrite-not-drop matters: a grant row is keyed (user, client) and its
+ * scope set spans every vault the user ever approved for that client —
+ * dropping the whole row over a single vault would silently revoke the
+ * client's consent on the user's OTHER vaults (over-revocation).
+ *
+ * Matching is the exact `vaultScopeName` segment comparison (regex on the
+ * `vault:<name>:<read|write|admin>` shape), never SQL LIKE — `_` in a vault
+ * name is a LIKE wildcard. Unnamed scopes (`vault:read`) and non-vault
+ * scopes are preserved.
+ */
+export function rewriteGrantsRemovingVault(
+  db: Database,
+  vaultName: string,
+): { rewritten: number; dropped: number } {
+  return db.transaction(() => {
+    const rows = db
+      .prepare("SELECT user_id, client_id, scopes, granted_at FROM grants")
+      .all() as GrantRow[];
+    let rewritten = 0;
+    let dropped = 0;
+    for (const row of rows) {
+      const scopes = row.scopes.split(" ").filter((s) => s.length > 0);
+      const kept = scopes.filter((s) => vaultScopeName(s) !== vaultName);
+      if (kept.length === scopes.length) continue; // doesn't name the vault
+      if (kept.length === 0) {
+        db.prepare("DELETE FROM grants WHERE user_id = ? AND client_id = ?").run(
+          row.user_id,
+          row.client_id,
+        );
+        dropped++;
+      } else {
+        db.prepare("UPDATE grants SET scopes = ? WHERE user_id = ? AND client_id = ?").run(
+          kept.join(" "),
+          row.user_id,
+          row.client_id,
+        );
+        rewritten++;
+      }
+    }
+    return { rewritten, dropped };
+  })();
+}

package/src/hub-db-liveness.ts

@@ -383,25 +383,41 @@ export function createDbHolder(initial: Database, deps: DbHolderDeps): DbHolder
       const verdict = classifyPathLiveness({ expected: currentInode, current: pathInode });
       if (verdict === "ok" || verdict === "unknown") return verdict;
 
-      // Genuine wipe signal: the on-disk DB the handle points at is gone
-      // ("gone") or was replaced underneath us ("replaced"). Trigger the SAME
-      // reopen-or-exit machinery. When the path is gone, reopen's SELECT-1
-      // verify fails → exit → platform manager restarts with a fresh on-disk
-      // handle (seconds, not "never"). When replaced, we adopt the fresh inode.
+      if (verdict === "gone") {
+        // The whole state dir was wiped under the running hub (`rm -rf
+        // ~/.parachute`). We must NOT reopen-in-place here: `reopen` is
+        // `openHubDb`, which `mkdirSync`'s the dir back + opens a fresh EMPTY db,
+        // so its SELECT-1 verify would PASS and we'd "heal" into a half-recovered
+        // hub — empty db, but stale in-memory state, wiped well-known files, and
+        // supervised modules whose own state dirs are gone yet never re-spawned
+        // (#619 follow-up). The correct recovery for a full wipe is a clean
+        // process exit so the platform manager (systemd / launchd / container)
+        // restarts `parachute serve`, which re-bootstraps everything (well-known,
+        // admin seed, supervisor re-spawn). This restores the #610 design intent
+        // ("we exit, letting the platform manager restart") that the shared
+        // reopen-or-exit path silently defeated via openHubDb's mkdir-recursive.
+        log(
+          `parachute hub: db path ${deps.dbPath} no longer exists (state dir wiped under a running hub, #610); exiting so the platform manager restarts the hub with a freshly bootstrapped state dir.`,
+        );
+        exit(1);
+        return verdict;
+      }
+
+      // "replaced": the db FILE was swapped underneath us (e.g. a restore copied
+      // a new file over the same path) while the rest of the state dir is intact.
+      // Adopting the fresh inode in-place via reopen-or-exit is correct here — a
+      // process restart would be heavier than needed.
       //
-      // ONE-TICK /health ANOMALY (intentional): on a "replaced" verdict the
-      // reopenOrExit below heals SYNCHRONOUSLY, but we still RETURN "replaced"
-      // for this one call — so the /health request that drove this probe reports
-      // `db:"error: path-replaced"` even though the handle is now healthy; the
-      // very next request reads `ok`. We don't mask it (returning "ok" here would
-      // hide that a heal just happened, which is exactly what monitoring wants to
-      // see). It's safe because #591's adoption probe checks only HTTP 200
-      // (`res.ok`), not the specific `db` string, so a single transient error
-      // string can't cascade.
+      // ONE-TICK /health ANOMALY (intentional): the reopenOrExit below heals
+      // SYNCHRONOUSLY, but we still RETURN "replaced" for this one call — so the
+      // /health request that drove this probe reports `db:"error: path-replaced"`
+      // even though the handle is now healthy; the very next request reads `ok`.
+      // We don't mask it (returning "ok" here would hide that a heal just
+      // happened, which is exactly what monitoring wants to see). It's safe
+      // because #591's adoption probe checks only HTTP 200 (`res.ok`), not the
+      // specific `db` string, so a single transient error string can't cascade.
       reopenOrExit(
-        verdict === "gone"
-          ? `db path ${deps.dbPath} no longer exists (state dir wiped under a running hub, #610)`
-          : `db path ${deps.dbPath} now resolves to a different inode (DB file replaced underneath the open handle, #610)`,
+        `db path ${deps.dbPath} now resolves to a different inode (DB file replaced underneath the open handle, #610)`,
       );
       return verdict;
     },