@openparachute/hub 0.6.5-rc.8 → 0.7.1

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,191 @@
+/**
+ * `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` or `credential`. */
+  readonly type: string;
+  /** The vault instance the trigger was registered on (vault-trigger), or
+   *  the vault a credential connection grants access to (credential). Either
+   *  way it's the field the vault-delete cascade matches on. */
+  readonly vault?: string;
+  /** The exact vault trigger name registered — DELETE removes this. */
+  readonly triggerName?: string;
+  /** Credential connections (H4): the exact scope minted, e.g.
+   *  `vault:default:read` — renewal re-mints THIS, never request input. */
+  readonly scope?: string;
+  /** Credential connections (H4): the tag allowlist baked into the minted
+   *  token's `permissions.scoped_tags`. Empty/absent = vault-wide (read
+   *  scopes only — writes always carry tags). */
+  readonly scopedTags?: readonly string[];
+  /** Credential connections (H4): the declared credential key. */
+  readonly credentialKey?: string;
+  /** Credential connections (H4): the module's daemon-root-relative delivery
+   *  endpoint — also the best-effort removal-notification target. */
+  readonly endpoint?: 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;
+  /**
+   * Connection kind discriminator (H4). Absent = the original event→action
+   * shape; `"credential"` = a standing tag-scoped vault credential held by a
+   * module (the source is the granting vault, the sink is the holding
+   * module). Optional for back-compat: pre-H4 records read back undefined.
+   */
+  readonly kind?: "credential";
+  /**
+   * Approval state (surface#113 claim/reconcile). Absent = active (every
+   * operator-provisioned record, and pre-claim records, read back undefined
+   * = active). `"pending"` = a module-initiated CLAIM for a directly-delivered
+   * credential, awaiting operator approval in the hub admin Connections view.
+   * A pending record grants nothing: renewal refuses it, and only the
+   * operator-gated approve endpoint flips it to active.
+   */
+  readonly status?: "pending";
+  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/help.ts

@@ -583,12 +583,19 @@ export function logsHelp(): string {
 Usage:
   parachute logs <service>          print the last 200 lines
   parachute logs <service> -f       tail the log (like \`tail -f\`)
-  parachute logs hub                logs for the internal hub
-
-Log file:
-  ~/.parachute/<service>/logs/<service>.log
-
-If no log file exists yet, prints a hint to \`parachute start <service>\`.
+  parachute logs hub                the full hub log (every module interleaved)
+
+Where logs live:
+  Supervised modules (the normal shape — hub-as-supervisor) write through
+  the hub: the supervisor multiplexes each child's output into
+  ~/.parachute/hub/logs/hub.log with a \`[<service>]\` line prefix.
+  \`parachute logs <service>\` reads that stream filtered to the service's
+  lines, prefix stripped (-n caps the MATCHING lines, not raw hub-log
+  lines; \`logs hub\` is unfiltered). A legacy per-service file
+  (~/.parachute/<service>/logs/<service>.log) is read instead when it is
+  fresher than the hub log — the pre-supervised install shape.
+
+If no log lines exist yet, prints a hint to \`parachute start <service>\`.
 `;
 }
 

package/src/host-admin-token-validation.ts

@@ -40,11 +40,15 @@
  * OAuth / access-token validation (vault / MCP tokens, `aud: "vault.<name>"`)
  * stays STRICT per-request-issuer and lives on entirely separate code paths
  * (the resource servers' own validators, hub's `/api/auth/*`, etc.). This
- * helper is invoked ONLY from the two loopback host-admin module surfaces
+ * helper is invoked from the two loopback host-admin module surfaces
  * (`/api/modules` GET — the `status` read; `/api/modules/:short/*` POST — the
  * lifecycle ops), both of which already gate on the non-requestable
  * `parachute:host:admin` / `parachute:host:auth` scopes that no OAuth token
- * can carry. The relaxation cannot reach an OAuth token's validation.
+ * can carry, and from the per-UI audience gate's Bearer branch
+ * (`src/audience-gate.ts`, H3) — same self-issued-token shape, same
+ * iss-∈-bound-origins need (a PWA's token carries the public origin while
+ * the proxied request resolves the loopback issuer), with the surface's
+ * declared `scopes_required` enforced by the gate on top.
  */
 import type { Database } from "bun:sqlite";
 import { type ValidatedAccessToken, validateAccessToken } from "./jwt-sign.ts";

package/src/hub-db.ts

@@ -4,7 +4,7 @@
  * issuer — signing keys (v1), users + opaque refresh tokens (v2), OAuth
  * clients + auth-codes + grants + browser sessions (v3), TOTP 2FA
  * enrollment on the users row (v11, hub#473), and one-time invite links
- * (v12, the `invites` table).
+ * (v12, the `invites` table; v13 adds the pre-named `username` column).
  *
  * Each open() runs `migrate()` to bring the schema up to date. A
  * `schema_version` table records every applied migration so re-opens are
@@ -426,6 +426,31 @@ const MIGRATIONS: readonly Migration[] = [
       CREATE INDEX invites_created_at ON invites (created_at);
     `,
   },
+  {
+    version: 13,
+    sql: `
+      -- Pre-named invites (Adam/Jonathan scenario). Adds an optional
+      -- \`username\` column to \`invites\`: when set, the invite pre-names
+      -- the account the redeemer gets — the redemption form shows the name
+      -- read-only and the redeem handler ENFORCES it (the form's username
+      -- field is ignored). NULL = the redeemer picks their own username
+      -- (every pre-v13 invite, and the default for new ones).
+      --
+      -- Enforced (not just pre-filled) because a pre-named invite is a
+      -- *named deliverable*: the admin mints "Jonathan's link" and hands it
+      -- to Jonathan; if the redeemer could pick a different name, the
+      -- link's identity binding would be decorative — the admin's audit
+      -- expectation ("this link = jonathan") and any vault assignment
+      -- story told against that name would silently break.
+      --
+      -- Stored as plain TEXT (already-validated lowercase [a-z0-9_-], the
+      -- users.username vocabulary). Mint-time validation rejects names
+      -- taken by an existing user or reserved by another pending invite;
+      -- the redeem path re-checks authoritatively. No backfill — every
+      -- existing invite predates pre-naming and keeps NULL.
+      ALTER TABLE invites ADD COLUMN username TEXT;
+    `,
+  },
 ];
 
 export function openHubDb(path: string = hubDbPath()): Database {