@openparachute/hub 0.7.0 → 0.7.1

package/src/commands/lifecycle.ts

@@ -1,4 +1,4 @@
-import { existsSync } from "node:fs";
+import { existsSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { rethrowIfMissing } from "@openparachute/depcheck";
 import { CONFIG_DIR, SERVICES_MANIFEST_PATH } from "../config.ts";
@@ -609,6 +609,74 @@ export interface LogsOpts {
    * Defaults to the group-aware `defaultAlive` (hub#88).
    */
   alive?: AliveFn;
+  /**
+   * Filtered-follow source seam (hub#652) — the byte stream of lines appended
+   * to the hub log from attach onward. The production default spawns
+   * `tail -n 0 -f <hub.log>` with piped stdout so the `[<svc>] ` filter runs
+   * in-process; tests inject a deterministic stream.
+   */
+  followStream?: (path: string) => ReadableStream<Uint8Array>;
+}
+
+/** Default `followStream`: tail the file from its end, stdout piped to us. */
+function defaultFollowStream(path: string): ReadableStream<Uint8Array> {
+  try {
+    // Inherit env so `tail` sees PATH, etc. Bun.spawn defaults to empty
+    // env — see api-modules-ops.ts:defaultRun.
+    const proc = Bun.spawn(["tail", "-n", "0", "-f", path], {
+      stdin: "ignore",
+      stdout: "pipe",
+      stderr: "inherit",
+      env: process.env,
+    });
+    return proc.stdout;
+  } catch (err) {
+    // A missing `tail` (minimal container without coreutils) surfaces the
+    // friendly install UX instead of a raw spawn throw (cli.ts top-level
+    // catch renders the MissingDependencyError).
+    rethrowIfMissing(err, "tail");
+    throw err;
+  }
+}
+
+/**
+ * Pump a byte stream line-by-line, emitting only lines that carry `prefix`
+ * (stripped). Line-buffered the same way the supervisor's `pumpLines` is, so
+ * chunk boundaries inside a line don't drop or split matches.
+ */
+async function pumpFilteredLines(
+  stream: ReadableStream<Uint8Array>,
+  prefix: string,
+  output: (line: string) => void,
+): Promise<void> {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let buf = "";
+  const emit = (line: string): void => {
+    if (line.startsWith(prefix)) output(line.slice(prefix.length));
+  };
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buf += decoder.decode(value, { stream: true });
+      let nl = buf.indexOf("\n");
+      while (nl !== -1) {
+        emit(buf.slice(0, nl));
+        buf = buf.slice(nl + 1);
+        nl = buf.indexOf("\n");
+      }
+    }
+    if (buf.length > 0) emit(buf);
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+/** Split a log file's content into lines, dropping the trailing newline. */
+function splitLogLines(content: string): string[] {
+  const trimmed = content.replace(/\n$/, "");
+  return trimmed === "" ? [] : trimmed.split("\n");
 }
 
 export async function logs(svc: string, opts: LogsOpts = {}): Promise<number> {
@@ -620,11 +688,12 @@ export async function logs(svc: string, opts: LogsOpts = {}): Promise<number> {
   const alive = opts.alive ?? defaultAlive;
 
   // logs only needs a valid short name to find the log file. First-party
-  // wins via the spec lookup; third-party rows match by `entry.name`; the
-  // internal hub is a known short outside of services.json. installDir is
-  // irrelevant here — the log file is keyed by short name and exists once
-  // the service has run, regardless of how it was registered. We just need
-  // to confirm the name maps to something the CLI manages.
+  // wins via the spec lookup; third-party rows match by `entry.name` (the
+  // same token the supervisor uses as its log prefix); the internal hub is
+  // a known short outside of services.json. installDir is irrelevant here —
+  // the log file is keyed by short name and exists once the service has
+  // run, regardless of how it was registered. We just need to confirm the
+  // name maps to something the CLI manages.
   const isFirstParty = getSpec(svc) !== undefined;
   if (!isFirstParty && svc !== HUB_SVC) {
     const entry = readManifest(manifestPath).services.find((s) => s.name === svc);
@@ -634,19 +703,111 @@ export async function logs(svc: string, opts: LogsOpts = {}): Promise<number> {
     }
   }
 
-  const path = logPathFor(svc, configDir);
-  if (!existsSync(path)) {
-    // Distinguish "daemon never started" from "daemon is running but the
-    // log file is missing" (hub#335). The latter shape surfaces when a
-    // module self-registers + spawns its own logger without going through
-    // `parachute start <svc>` (no hub-managed log file), or when an
-    // operator deletes the log mid-run. Previously both shapes printed the
-    // same `parachute start ${svc}` hint, leading operators to think their
-    // running daemon hadn't started.
+  // Per-file plain reader (the pre-#652 behavior): tail/print one log file.
+  const readPlain = async (path: string): Promise<number> => {
+    if (follow) {
+      const spawner = opts.tailSpawner ?? {
+        spawn(cmd) {
+          // Inherit env so `tail` sees PATH, etc. Bun.spawn defaults to empty
+          // env — see api-modules-ops.ts:defaultRun.
+          try {
+            const proc = Bun.spawn([...cmd], {
+              stdio: ["ignore", "inherit", "inherit"],
+              env: process.env,
+            });
+            return proc.pid;
+          } catch (err) {
+            // A missing `tail` (minimal container without coreutils) surfaces
+            // the friendly install UX instead of a raw spawn throw. The CLI
+            // top-level catch in cli.ts renders the MissingDependencyError.
+            rethrowIfMissing(err, "tail");
+            throw err;
+          }
+        },
+      };
+      spawner.spawn(["tail", "-n", String(lines), "-f", path], path);
+      // tail runs until user Ctrl-C; block this process until it exits.
+      // When called from the real CLI, process.exit wraps us; in tests a
+      // stub spawner returns immediately and we fall through.
+      return 0;
+    }
+    // Non-follow path: read last N lines synchronously for a clean one-shot.
+    const tail = splitLogLines(await Bun.file(path).text()).slice(-lines);
+    for (const line of tail) log(line);
+    return 0;
+  };
+
+  const legacyPath = logPathFor(svc, configDir);
+  const hubLogPath = logPathFor(HUB_SVC, configDir);
+  const legacyExists = svc !== HUB_SVC && existsSync(legacyPath);
+  const hubLogExists = existsSync(hubLogPath);
+
+  // Source selection (hub#652): under hub-as-supervisor (Phase 5b) a module's
+  // stdout/stderr is multiplexed into the HUB log with a `[<svc>] ` line
+  // prefix (supervisor.ts pipeOutput) — the per-service file stops advancing
+  // at the cutover. Prefer whichever file is fresher: a pre-supervised
+  // install is still actively writing the per-service file (it wins); on a
+  // supervised box the hub log is the live stream and the per-service file
+  // is a stale remnant (it loses). `logs hub` always reads the hub log
+  // unfiltered — the interleaved prefixed stream IS the hub's own log.
+  const useHubStream =
+    svc !== HUB_SVC &&
+    hubLogExists &&
+    (!legacyExists || statSync(hubLogPath).mtimeMs >= statSync(legacyPath).mtimeMs);
+
+  if (!useHubStream) {
+    if (!existsSync(legacyPath)) {
+      // Distinguish "daemon never started" from "daemon is running but the
+      // log file is missing" (hub#335). The latter shape surfaces when a
+      // module self-registers + spawns its own logger without going through
+      // the hub (no hub-managed log file), or when an operator deletes the
+      // log mid-run. Previously both shapes printed the same
+      // `parachute start ${svc}` hint, leading operators to think their
+      // running daemon hadn't started.
+      const state = processState(svc, configDir, alive);
+      if (state.status === "running") {
+        const whereabouts =
+          svc === HUB_SVC
+            ? `no log file at ${legacyPath}`
+            : `no log file at ${legacyPath} and no hub log at ${hubLogPath}`;
+        log(
+          `${svc} is running (pid ${state.pid}) but ${whereabouts}. The daemon may be writing logs elsewhere — check its stdout/stderr or its own log destination.`,
+        );
+        return 0;
+      }
+      log(`no logs yet for ${svc}. \`parachute start ${svc}\` to begin.`);
+      return 0;
+    }
+    return readPlain(legacyPath);
+  }
+
+  // Supervised path (hub#652): the service's lines in the hub log, prefix
+  // stripped. Stripped rather than kept: every line would otherwise repeat
+  // the name the operator just typed, while the module's own output shape
+  // (e.g. surface's `[app-dcr]` sub-prefixes) stays intact — the same shape
+  // its per-service file had pre-cutover.
+  const prefix = `[${svc}] `;
+  const matched = splitLogLines(await Bun.file(hubLogPath).text())
+    .filter((l) => l.startsWith(prefix))
+    .map((l) => l.slice(prefix.length));
+
+  if (matched.length === 0 && !follow) {
+    if (legacyExists) {
+      // Transitional shape: nothing for this service in the hub log, but a
+      // (staler) per-service file exists — e.g. the module last ran detached,
+      // pre-cutover. Show it, with a note so a stale file isn't mistaken for
+      // the live stream (the exact hub#652 trap).
+      log(
+        `note: no ${svc} lines in the hub log (${hubLogPath}); showing the per-service log at ${legacyPath}.`,
+      );
+      return readPlain(legacyPath);
+    }
+    // Keep the hub#335 shapes coherent with the hub-stream source: a live
+    // pidfile here means a daemon the hub isn't logging for.
     const state = processState(svc, configDir, alive);
     if (state.status === "running") {
       log(
-        `${svc} is running (pid ${state.pid}) but no log file at ${path}. The daemon may be writing logs elsewhere — check its stdout/stderr or its own log destination.`,
+        `${svc} is running (pid ${state.pid}) but has no lines in the hub log (${hubLogPath}) and no log file at ${legacyPath}. The daemon may be writing logs elsewhere — check its stdout/stderr or its own log destination.`,
       );
       return 0;
     }
@@ -654,38 +815,17 @@ export async function logs(svc: string, opts: LogsOpts = {}): Promise<number> {
     return 0;
   }
 
+  for (const line of matched.slice(-lines)) log(line);
+
   if (follow) {
-    const spawner = opts.tailSpawner ?? {
-      spawn(cmd) {
-        // Inherit env so `tail` sees PATH, etc. Bun.spawn defaults to empty
-        // env — see api-modules-ops.ts:defaultRun.
-        try {
-          const proc = Bun.spawn([...cmd], {
-            stdio: ["ignore", "inherit", "inherit"],
-            env: process.env,
-          });
-          return proc.pid;
-        } catch (err) {
-          // A missing `tail` (minimal container without coreutils) surfaces
-          // the friendly install UX instead of a raw spawn throw. The CLI
-          // top-level catch in cli.ts renders the MissingDependencyError.
-          rethrowIfMissing(err, "tail");
-          throw err;
-        }
-      },
-    };
-    spawner.spawn(["tail", "-n", String(lines), "-f", path], path);
-    // tail runs until user Ctrl-C; block this process until it exits.
-    // When called from the real CLI, process.exit wraps us; in tests a
-    // stub spawner returns immediately and we fall through.
-    return 0;
+    // Print the filtered backlog above, then follow new hub-log lines through
+    // the same filter. Runs until the tail is killed (Ctrl-C takes down the
+    // whole foreground process group); in tests the injected stream closes.
+    if (matched.length === 0) {
+      log(`(no prior ${svc} lines — waiting for new output…)`);
+    }
+    const source = opts.followStream ?? defaultFollowStream;
+    await pumpFilteredLines(source(hubLogPath), prefix, log);
   }
-
-  // Non-follow path: read last N lines synchronously for a clean one-shot.
-  const content = await Bun.file(path).text();
-  const trimmed = content.replace(/\n$/, "");
-  const allLines = trimmed === "" ? [] : trimmed.split("\n");
-  const tail = allLines.slice(-lines);
-  for (const line of tail) log(line);
   return 0;
 }

package/src/connections-store.ts

@@ -45,12 +45,26 @@ export interface ConnectionSink {
 
 /** What the provisioning engine actually wired, for teardown + display. */
 export interface ConnectionProvisioned {
-  /** How the action was provisioned, e.g. `vault-trigger`. */
+  /** How the action was provisioned, e.g. `vault-trigger` or `credential`. */
   readonly type: string;
-  /** The vault instance the trigger was registered on (vault-trigger). */
+  /** 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
@@ -66,6 +80,22 @@ export interface ConnectionProvisioned {
 
 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;

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 {