@openparachute/hub 0.7.0 → 0.7.2-rc.1

package/src/commands/vault-remove.ts

@@ -0,0 +1,361 @@
+/**
+ * `parachute vault remove <name>` — route the CLI vault-delete verb through the
+ * hub's identity cascade instead of the mechanics-only `parachute-vault remove`.
+ *
+ * ## Why this command exists (B3)
+ *
+ * The transparent `parachute vault <args>` passthrough (`commands/vault.ts`)
+ * forwards `remove <name>` verbatim to `parachute-vault remove` — which only
+ * does the MECHANICS of destruction (`rmSync` the vault dir + rewrite the vault
+ * module's own config). That path BYPASSES every hub-side identity artifact tied
+ * to the vault: live `vault:<name>:*` access tokens stay valid (and reachable
+ * via the polled revocation list), `user_vaults` rows linger, grants keep their
+ * `vault:<name>:*` entries, unredeemed invites pinned to the vault stay
+ * redeemable, and Connections that source/provision the vault keep their
+ * long-lived mints. Deleting a vault that way orphans all of it.
+ *
+ * The hub ALREADY ships the correct path: `DELETE /vaults/<name>`
+ * (`admin-vaults.ts:handleDeleteVault`) runs the full 7-step identity cascade
+ * (revoke tokens → rewrite grants → drop user_vaults → revoke invites → tear
+ * down connections → shell `parachute-vault remove` → restart vault) and is
+ * exactly what the vault-admin SPA drives. This command routes the CLI verb
+ * through that SAME endpoint over loopback, so `parachute vault remove` and the
+ * SPA delete are one code path.
+ *
+ * ## Credential + transport (reused from module-ops-client.ts)
+ *
+ * We drive the RUNNING hub over loopback — never open hub.db's vault registry
+ * directly (the daemon holds it). The bearer is the on-disk
+ * `~/.parachute/operator.token`, read (never minted) via
+ * `useOperatorTokenWithAutoRotate`. Its default `admin` scope-set carries
+ * `parachute:host:admin` — exactly the scope the endpoint gates on. This is the
+ * same read-never-mint credential path `parachute start/stop/restart <svc>` use.
+ *
+ * ## The 409 guardrail (load-bearing)
+ *
+ * On a `409 last_vault` the endpoint refuses (deleting the last vault would let
+ * vault's boot silently resurrect a fresh `default`). We print the endpoint's
+ * message + note the raw escape hatch (`parachute-vault remove <name> --yes`)
+ * which SKIPS the cascade, then return NON-ZERO. We MUST NOT fall through to
+ * spawning `parachute-vault` ourselves: a "helpful" fall-through would re-open
+ * the exact orphaning bug B3 closes. The test locks this invariant.
+ */
+
+import { CONFIG_DIR } from "../config.ts";
+import { readExposeState } from "../expose-state.ts";
+import { readHubPort } from "../hub-control.ts";
+import { hubDbPath, openHubDb } from "../hub-db.ts";
+import { HUB_UNIT_DEFAULT_PORT } from "../hub-unit.ts";
+import {
+  DEFAULT_HUB_BASE_URL,
+  ModuleOpHttpError,
+  NoOperatorTokenError,
+  OperatorTokenExpiredError,
+  resolveOperatorBearer,
+} from "../module-ops-client.ts";
+
+/**
+ * Injectable seams. Production wires the real operator-token bearer resolver +
+ * the global `fetch`; tests inject fakes to assert the request shape + lock the
+ * 409 guardrail without a live hub or a real socket.
+ */
+export interface VaultRemoveDeps {
+  /**
+   * Resolve the operator-token bearer to present to the loopback hub. Default
+   * opens hub.db, reads `~/.parachute/operator.token` (auto-rotating if near
+   * expiry), and returns the JWT. Throws {@link NoOperatorTokenError} /
+   * {@link OperatorTokenExpiredError} with already-actionable messages.
+   */
+  readonly resolveBearer?: () => Promise<string>;
+  /** fetch seam — `globalThis.fetch` in production; a recorder in tests. */
+  readonly fetch?: typeof fetch;
+  /** Loopback hub base URL. Defaults to {@link DEFAULT_HUB_BASE_URL}. */
+  readonly baseUrl?: string;
+  /** Output sink. Defaults to `console.log`. */
+  readonly log?: (line: string) => void;
+  /** Error sink. Defaults to `console.error`. */
+  readonly logError?: (line: string) => void;
+}
+
+/** Wire shape of the cascade summary nested under `cascade` in the 200 body. */
+interface CascadeSummaryWire {
+  tokens_revoked?: number;
+  grants_rewritten?: number;
+  grants_dropped?: number;
+  user_vaults_removed?: number;
+  invites_invalidated?: number;
+  connections_torn_down?: number;
+  orphaned_channels?: unknown;
+  vault_removed?: boolean;
+  module_restarted?: boolean;
+}
+
+interface DeleteVaultSuccessWire {
+  ok?: boolean;
+  name?: string;
+  cascade?: CascadeSummaryWire;
+  warnings?: unknown;
+}
+
+/**
+ * Resolve the hub origin the operator token's `iss` is validated against —
+ * mirrors `lifecycle.ts:resolveOperatorTokenIssuer`. Unlike the spawn-env
+ * derivation, the operator token always carries an `iss`, so we fall back to
+ * the canonical loopback origin (never `undefined`). The known-issuer SET inside
+ * `useOperatorTokenWithAutoRotate` also accepts the public `iss` from
+ * expose-state, so a seed of loopback still validates an exposed-origin token.
+ */
+function resolveOperatorTokenIssuer(configDir: string): string {
+  const state = readExposeState(`${configDir}/expose-state.json`);
+  if (state?.hubOrigin) return state.hubOrigin;
+  const port = readHubPort(configDir) ?? HUB_UNIT_DEFAULT_PORT;
+  return `http://127.0.0.1:${port}`;
+}
+
+/**
+ * Default bearer resolver: open hub.db, read+auto-rotate the operator token,
+ * return the JWT. Closes the db before returning. Read-never-mint — no second
+ * SQLite writer racing the running hub.
+ */
+async function defaultResolveBearer(configDir: string): Promise<string> {
+  const issuer = resolveOperatorTokenIssuer(configDir);
+  const db = openHubDb(hubDbPath(configDir));
+  try {
+    return await resolveOperatorBearer({ db, issuer, configDir });
+  } finally {
+    db.close();
+  }
+}
+
+function n(v: number | undefined): number {
+  return typeof v === "number" ? v : 0;
+}
+
+function asStringArray(v: unknown): string[] {
+  return Array.isArray(v) ? v.filter((x): x is string => typeof x === "string") : [];
+}
+
+/**
+ * Render the structured cascade summary the endpoint returns — the operator's
+ * proof every identity artifact was revoked, not just the vault dir removed.
+ */
+function renderCascadeSummary(
+  name: string,
+  body: DeleteVaultSuccessWire,
+  log: (line: string) => void,
+): void {
+  const c = body.cascade ?? {};
+  log(`Removed vault "${name}" with the full identity cascade:`);
+  log(`  tokens revoked:        ${n(c.tokens_revoked)}`);
+  log(`  grants rewritten:      ${n(c.grants_rewritten)}`);
+  log(`  grants dropped:        ${n(c.grants_dropped)}`);
+  log(`  user_vaults removed:   ${n(c.user_vaults_removed)}`);
+  log(`  invites invalidated:   ${n(c.invites_invalidated)}`);
+  log(`  connections torn down: ${n(c.connections_torn_down)}`);
+  log(`  vault removed:         ${c.vault_removed === true ? "yes" : "no"}`);
+  log(`  vault module restarted:${c.module_restarted === true ? " yes" : " no"}`);
+
+  const orphaned = asStringArray(c.orphaned_channels);
+  if (orphaned.length > 0) {
+    log("");
+    log(`WARNING: ${orphaned.length} vault-backed agent channel(s) still reference "${name}":`);
+    for (const ch of orphaned) log(`  - ${ch}`);
+    log("Remove them in the agent UI — the hub does not delete the agent's config.");
+  }
+
+  // Top-level warnings[] — each a { step, detail } the cascade recorded
+  // (e.g. daemon-restart skipped, a partial connection teardown).
+  const warnings = Array.isArray(body.warnings) ? body.warnings : [];
+  if (warnings.length > 0) {
+    log("");
+    log("Warnings:");
+    for (const w of warnings) {
+      const rec = (w ?? {}) as { step?: unknown; detail?: unknown };
+      const step = typeof rec.step === "string" ? rec.step : "warning";
+      const detail = typeof rec.detail === "string" ? rec.detail : JSON.stringify(w);
+      log(`  - [${step}] ${detail}`);
+    }
+  }
+}
+
+const USAGE = "usage: parachute vault remove <name> [--yes] [--hub-origin <url>]";
+
+/**
+ * Route `parachute vault remove <name>` (and the `rm` alias) through the hub's
+ * `DELETE /vaults/<name>` identity cascade. Returns the process exit code.
+ */
+export async function vaultRemove(args: string[], deps: VaultRemoveDeps = {}): Promise<number> {
+  const log = deps.log ?? ((line: string) => console.log(line));
+  const logError = deps.logError ?? ((line: string) => console.error(line));
+
+  // --- Parse args: positional <name> + flags (--yes/-y, --hub-origin <url>). --
+  let name: string | undefined;
+  let baseUrlOverride: string | undefined = deps.baseUrl;
+  // `--yes`/`-y` is accepted for parity with `parachute-vault remove --yes` and
+  // to telegraph non-interactive intent; the endpoint's confirm guard is
+  // satisfied from the name arg, so no extra prompt is shown either way. We
+  // parse it so it isn't mistaken for a positional, but the behaviour is the
+  // same with or without it (this is an admin op that already requires the
+  // operator token + a deliberate name retype on the wire).
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--yes" || a === "-y") continue;
+    if (a === "--hub-origin") {
+      const v = args[i + 1];
+      if (!v) {
+        logError("parachute vault remove: --hub-origin requires a URL argument");
+        return 1;
+      }
+      baseUrlOverride = v;
+      i++;
+      continue;
+    }
+    if (a?.startsWith("--hub-origin=")) {
+      baseUrlOverride = a.slice("--hub-origin=".length);
+      continue;
+    }
+    if (a?.startsWith("-")) {
+      logError(`parachute vault remove: unknown flag "${a}"`);
+      logError(USAGE);
+      return 1;
+    }
+    if (name === undefined) {
+      name = a;
+      continue;
+    }
+    logError(`parachute vault remove: unexpected argument "${a}"`);
+    logError(USAGE);
+    return 1;
+  }
+
+  if (!name) {
+    logError("parachute vault remove: a vault name is required");
+    logError(USAGE);
+    return 1;
+  }
+
+  // --- Resolve the operator-token bearer (read, never mint). ------------------
+  let bearer: string;
+  try {
+    bearer = deps.resolveBearer
+      ? await deps.resolveBearer()
+      : await defaultResolveBearer(CONFIG_DIR);
+  } catch (err) {
+    if (err instanceof NoOperatorTokenError || err instanceof OperatorTokenExpiredError) {
+      // Already-actionable ("run `parachute auth rotate-operator`") — surface
+      // verbatim, never a raw 401.
+      logError(`parachute vault remove: ${err.message}`);
+      return 1;
+    }
+    logError(`parachute vault remove: ${err instanceof Error ? err.message : String(err)}`);
+    return 1;
+  }
+
+  // --- DELETE /vaults/<name> with the confirm body. --------------------------
+  const doFetch = deps.fetch ?? fetch;
+  const baseUrl = (baseUrlOverride ?? DEFAULT_HUB_BASE_URL).replace(/\/+$/, "");
+  const url = `${baseUrl}/vaults/${encodeURIComponent(name)}`;
+
+  let res: Response;
+  try {
+    res = await doFetch(url, {
+      method: "DELETE",
+      headers: {
+        authorization: `Bearer ${bearer}`,
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({ confirm: name }),
+    });
+  } catch (err) {
+    // Loopback connection refused → the hub isn't running. The cascade needs
+    // the live hub; there's no DB-side fallback we'd take (that's the bug).
+    const msg = err instanceof Error ? err.message : String(err);
+    const refused = /econnrefused|connection refused|failed to fetch|unable to connect/i.test(msg);
+    if (refused) {
+      logError(
+        "parachute vault remove: the hub must be running to delete a vault with the identity cascade.",
+      );
+      logError("Run `parachute start`, then retry.");
+      logError(
+        `(The raw escape hatch \`parachute-vault remove ${name} --yes\` deletes the vault dir but SKIPS the cascade, leaving orphaned tokens.)`,
+      );
+      return 1;
+    }
+    logError(`parachute vault remove: request failed: ${msg}`);
+    return 1;
+  }
+
+  const body = await parseJsonSafe(res);
+
+  // --- Success: render the cascade summary. ----------------------------------
+  if (res.status === 200) {
+    renderCascadeSummary(name, (body ?? {}) as DeleteVaultSuccessWire, log);
+    return 0;
+  }
+
+  // --- Error mapping (actionable, never a raw status dump). -------------------
+  const { error, error_description } = asErrorBody(body, res.status);
+
+  if (res.status === 404 && error === "not_found") {
+    // Idempotent: a re-run after a successful delete lands here. Not scary.
+    log(`Vault "${name}" does not exist on this hub (already removed). Nothing to do.`);
+    return 0;
+  }
+
+  if (res.status === 409 && error === "last_vault") {
+    // CRITICAL GUARDRAIL: print + exit non-zero. Do NOT fall through to spawning
+    // `parachute-vault` — that would re-open the orphaned-identity bug B3 closes.
+    logError(`parachute vault remove: ${error_description}`);
+    logError("");
+    logError(
+      `The raw mechanics-only path \`parachute-vault remove ${name} --yes\` can delete the last vault,`,
+    );
+    logError(
+      "but it SKIPS the identity cascade — live tokens, grants, and user_vaults rows for that",
+    );
+    logError("vault would be left orphaned. Create another vault first if you can.");
+    return 1;
+  }
+
+  if (res.status === 400 && error === "confirm_mismatch") {
+    // Pass the hub's confirm message through.
+    logError(`parachute vault remove: ${error_description}`);
+    return 1;
+  }
+
+  if (res.status === 401 || res.status === 403) {
+    // The operator token was rejected by the hub — guide to re-mint rather than
+    // dumping the raw status (matches module-ops-client's posture).
+    logError(`parachute vault remove: the hub rejected the operator token (${error_description}).`);
+    logError("Run `parachute auth rotate-operator` to mint a fresh one, then retry.");
+    return 1;
+  }
+
+  // Any other non-2xx — name the failure class without a raw dump.
+  logError(`parachute vault remove: ${error}: ${error_description}`);
+  return 1;
+}
+
+async function parseJsonSafe(res: Response): Promise<unknown> {
+  try {
+    return await res.json();
+  } catch {
+    return undefined;
+  }
+}
+
+function asErrorBody(body: unknown, status: number): { error: string; error_description: string } {
+  const fallback = `hub returned HTTP ${status} with no error detail`;
+  if (body && typeof body === "object") {
+    const b = body as Record<string, unknown>;
+    const error = typeof b.error === "string" ? b.error : "error";
+    const error_description =
+      typeof b.error_description === "string" ? b.error_description : fallback;
+    return { error, error_description };
+  }
+  return { error: "error", error_description: fallback };
+}
+
+// Re-export so the test (and future CLI callers) can catch the typed errors
+// without a second import path.
+export { ModuleOpHttpError, NoOperatorTokenError, OperatorTokenExpiredError };

package/src/commands/wizard.ts

@@ -749,10 +749,10 @@ export async function runCliWizard(opts: RunCliWizardOpts): Promise<number> {
     state = await fetchWizardState(hubUrl, jar, fetchImpl);
   }
   // Done screen — fetch + show a brief summary. The browser wizard's
-  // done screen surfaces the MCP install command + auto-minted token;
-  // we mirror that by reading the same `setup_minted_token` row via
-  // the GET endpoint's JSON envelope. Best-effort: a missing token
-  // just means we point the operator at /admin/tokens instead.
+  // done screen surfaces the bare OAuth `claude mcp add` command (no
+  // token, no header — vault is OAuth-default per parachute-vault #491);
+  // the CLI path never minted a token, so we just point the operator at
+  // the admin SPA + /admin/tokens for the headless-client case.
   log("");
   log("✓ Setup complete.");
   log(`  Visit ${hubUrl}/admin/ to open the admin SPA.`);

package/src/connections-store.ts

@@ -35,7 +35,7 @@ export interface ConnectionSource {
 
 /** The sink side — an action a module accepts (the sink is ALWAYS an action). */
 export interface ConnectionSink {
-  /** Sink module short name, e.g. `channel`. */
+  /** Sink module short name, e.g. `agent`. */
   readonly module: string;
   /** Action key declared in the sink module's `module.json`, e.g. `message.deliver`. */
   readonly action: string;
@@ -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;
@@ -73,8 +103,8 @@ export interface ConnectionRecord {
   /**
    * 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
+   * operator's behalf (e.g. the agent module's admin page "link to a vault" flow)
+   * labels itself here (e.g. `"agent"`); 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