@openparachute/vault 0.4.7-rc.2 → 0.4.8-rc.10

package/src/cli.ts

@@ -103,7 +103,7 @@ import type { TokenPermission } from "./token-store.ts";
 import { resolveCreateTokenFlags, VAULT_SCOPES } from "./scopes.ts";
 import { validateVaultName, decideInitVaultName } from "./vault-name.ts";
 import { getVaultStore } from "./vault-store.ts";
-import { upsertService, ServicesManifestError } from "./services-manifest.ts";
+import { selfRegister } from "./self-register.ts";
 import {
   hasOwnerPassword,
   setOwnerPassword,
@@ -245,27 +245,6 @@ switch (command) {
 // Command implementations
 // ---------------------------------------------------------------------------
 
-/**
- * Compute the `paths` array for the parachute-vault entry in services.json.
- * One entry advertises every vault on this server; `paths[0]` is the
- * canonical mount the hub stamps into `.well-known/parachute.json`, so the
- * default vault sorts first when one is set. With no vaults yet, fall back
- * to "/" so an early-init registration is still well-formed.
- */
-function buildVaultServicePaths(
-  defaultVault: string | undefined,
-  vaults: string[],
-): string[] {
-  if (vaults.length === 0) return ["/"];
-  if (defaultVault && vaults.includes(defaultVault)) {
-    return [
-      `/vault/${defaultVault}`,
-      ...vaults.filter((v) => v !== defaultVault).map((v) => `/vault/${v}`),
-    ];
-  }
-  return vaults.map((v) => `/vault/${v}`);
-}
-
 async function cmdInit(args: string[] = []) {
   ensureConfigDirSync();
 
@@ -363,24 +342,24 @@ async function cmdInit(args: string[] = []) {
   // by name, preserving entries for other services. Non-fatal on failure —
   // init can complete without the manifest, just with a warning.
   //
+  // `selfRegister` stamps the full manifest-sourced row (displayName, tagline,
+  // stripPrefix, installDir) from `.parachute/module.json` — the same shape
+  // server boot writes via the self-registration pass (vault#266). Keeping
+  // the two write paths in lockstep means `parachute-vault init` and the
+  // first server boot agree on the row contents; without that, a re-init
+  // would silently lose the manifest fields the boot pass had added.
+  //
   // `paths[0]` is the canonical mount point — the hub uses it for the
   // `.well-known/parachute.json` URL and for `parachute expose`, so the
   // default vault always sorts first. Remaining vaults follow so the hub
   // well-known and paraclaw's attach picker see every vault on this server.
   // Re-running init re-registers the full set; that doubles as the
   // recovery path for installs whose services.json is stale (#208).
-  try {
-    upsertService({
-      name: "parachute-vault",
-      port: globalConfig.port || DEFAULT_PORT,
-      paths: buildVaultServicePaths(globalConfig.default_vault, allVaults),
-      health: "/health",
-      version: pkg.version,
-    });
-  } catch (err) {
-    const msg = err instanceof ServicesManifestError ? err.message : String(err);
-    console.error(`  Warning: could not update ~/.parachute/services.json: ${msg}`);
-  }
+  selfRegister({
+    version: pkg.version,
+    warn: (msg) => console.error(`  Warning: ${msg}`),
+    log: () => {}, // CLI init has its own status lines; suppress duplicate noise.
+  });
 
   // 2b. Migrate existing legacy keys into per-vault token tables
   for (const v of listVaults()) {
@@ -409,17 +388,11 @@ async function cmdInit(args: string[] = []) {
     console.log();
   }
 
-  // 5b. Owner password is only needed for OAuth consent (browser-based
-  // clients like claude.ai / ChatGPT / Claude Desktop). Those paths are
-  // coming in the next few weeks; until then, skip the prompt. Users who
-  // want to expose the vault publicly today can set one manually via
-  // `parachute-vault set-password`.
-  if (!hasOwnerPassword()) {
-    console.log();
-    console.log("Public exposure + web-AI connectors (claude.ai, ChatGPT, etc.) are coming soon.");
-    console.log("  When you're ready to expose this vault publicly, run:");
-    console.log("    parachute-vault set-password    # required for OAuth consent");
-  }
+  // 5b. OAuth consent now runs on the hub (workstream E, 2026-05-25). Vault
+  // no longer renders its own consent page, so no owner-password prompt
+  // belongs in `vault init`. Operators who want to expose vault publicly to
+  // browser-based clients should run `parachute install hub`; the hub owns
+  // the consent surface, the sign-in flow, and the JWT issuance.
 
   // 6. Install daemon (platform-aware). Idempotent — safe to re-run after
   // a folder move; this refreshes ~/.parachute/server-path and bounces the
@@ -575,8 +548,8 @@ async function promptVaultName(): Promise<string> {
 
 async function promptForOwnerPassword(purpose: string): Promise<boolean> {
   console.log(`\n${purpose}`);
-  console.log("  Used on the OAuth consent page to authorize third-party clients");
-  console.log("  (Claude Web, Claude Desktop, etc.) to access this vault.");
+  console.log("  Legacy field — vault's standalone OAuth consent was retired in 0.4.x.");
+  console.log("  Stored in config.yaml for hub's expose-posture-check only.");
   console.log(`  Minimum 12 characters.\n`);
 
   while (true) {
@@ -605,6 +578,16 @@ async function promptForOwnerPassword(purpose: string): Promise<boolean> {
 }
 
 async function cmdSetPassword(args: string[]) {
+  // Legacy command (workstream E, 2026-05-25). Vault's standalone OAuth
+  // consent page was retired; this command now only writes the
+  // `owner_password_hash` field that hub's `expose public` posture-check
+  // reads. It no longer gates any auth flow inside vault. Set hub
+  // credentials with `parachute auth set-password`.
+  console.warn(
+    "[deprecated] vault's standalone OAuth consent was retired in 0.4.x; OAuth runs on the hub.\n" +
+      "             This command writes a legacy YAML field but no longer gates auth inside vault.\n" +
+      "             Set hub credentials with `parachute auth set-password`.\n",
+  );
   const wantsClear = args.includes("--clear") || args.includes("--unset");
   if (wantsClear) {
     if (!hasOwnerPassword()) {
@@ -615,7 +598,7 @@ async function cmdSetPassword(args: string[]) {
       ? " Note: 2FA management operations will require your authenticator app or a backup code instead."
       : "";
     const ok = await confirm(
-      `Remove the owner password? OAuth consent will fall back to vault-token auth.${twoFaNote}`,
+      `Remove the owner password? (Legacy field — vault's standalone OAuth consent was retired in 0.4.x; OAuth runs on the hub now.)${twoFaNote}`,
       false,
     );
     if (!ok) {
@@ -696,6 +679,16 @@ async function confirmForTwoFactor(purpose: string): Promise<boolean> {
 }
 
 async function cmd2fa(args: string[]) {
+  // Legacy command (workstream E, 2026-05-25). See cmdSetPassword for the
+  // full deprecation story. 2FA on vault used to layer on top of the
+  // owner-password gate for the standalone OAuth consent page; both have
+  // been retired. The CLI still manages the legacy YAML fields for
+  // back-compat.
+  console.warn(
+    "[deprecated] vault's standalone OAuth consent was retired in 0.4.x; OAuth runs on the hub.\n" +
+      "             This command writes legacy YAML fields but no longer gates auth inside vault.\n",
+  );
+
   const sub = args[0] ?? "status";
 
   if (sub === "status") {
@@ -763,7 +756,7 @@ async function cmd2fa(args: string[]) {
     for (const code of result.backupCodes) {
       console.log(`  ${code}`);
     }
-    console.log("\n2FA is now active for OAuth consent on this vault.");
+    console.log("\n2FA is now recorded in the legacy YAML field. (See deprecation note above.)");
     return;
   }
 
@@ -862,19 +855,16 @@ function cmdCreate(args: string[]) {
   // attach picker see this vault. cmdInit registers on first run; cmdCreate
   // adds the new path on every subsequent vault. Without this, vaults
   // created after init were invisible to the hub (#208).
-  // Warnings go to stderr to keep --json stdout clean for the orchestrator.
-  try {
-    upsertService({
-      name: "parachute-vault",
-      port: globalConfig.port || DEFAULT_PORT,
-      paths: buildVaultServicePaths(globalConfig.default_vault, listVaults()),
-      health: "/health",
-      version: pkg.version,
-    });
-  } catch (err) {
-    const msg = err instanceof ServicesManifestError ? err.message : String(err);
-    console.error(`Warning: could not update ~/.parachute/services.json: ${msg}`);
-  }
+  //
+  // Routed through `selfRegister` (vault#266) so the row carries the full
+  // manifest-sourced metadata (displayName, tagline, stripPrefix, installDir)
+  // — same shape server boot writes. Warnings go to stderr to keep --json
+  // stdout clean for the orchestrator.
+  selfRegister({
+    version: pkg.version,
+    warn: (msg) => console.error(`Warning: ${msg}`),
+    log: () => {}, // CLI create has its own status lines.
+  });
 
   if (jsonMode) {
     const payload = {
@@ -943,6 +933,11 @@ function takeArgValue(args: string[], name: string): { value?: string; missingVa
  * Targeting:
  *   --scope <verb>        vault:read | vault:write | vault:admin (default: vault:read).
  *                         For --mint, expands to vault:<vault-name>:<verb>.
+ *                         vault:admin requires --legacy-pat — hub policy makes
+ *                         per-vault admin non-requestable via mint-token (it's
+ *                         operator-only, minted only through the session-
+ *                         cookie-gated admin SPA endpoint), so --mint + admin
+ *                         is rejected pre-flight.
  *   --install-scope <s>   local (default) | user | project. local writes to
  *                         ~/.claude.json under projects[<cwd>].mcpServers
  *                         (private, this directory only — matches Claude
@@ -1331,6 +1326,28 @@ async function executeMcpInstall(opts: ExecuteMcpInstallOpts): Promise<void> {
     bearer = fullToken;
   } else {
     // mode === "mint"
+    // Pre-flight: hub policy rejects `vault:<name>:admin` via the public
+    // mint-token endpoint. Per-vault admin is operator-only, mintable
+    // only through the session-cookie-gated `/admin/vault-admin-token/:name`
+    // SPA path. Calling hub with admin would surface a 400:
+    //   "Hub mint-token rejected (HTTP 400, invalid_scope):
+    //    scope vault:default:admin is not requestable via mint-token;
+    //    use OAuth flow or operator rotation"
+    // Fail early with the actionable remediation rather than letting
+    // the operator chase the hub's wire-level error. See
+    // `parachute-hub/src/scope-explanations.ts` (VAULT_ADMIN_RE) and
+    // `parachute-hub/src/api-mint-token.ts` (non-requestable guard).
+    if (verb === "admin") {
+      console.error(
+        "Hub policy: vault:<name>:admin is not requestable via mint-token " +
+          "(per-vault admin is operator-only, minted only by the session-cookie-gated " +
+          "admin SPA at <hub>/admin/vaults/" + vaultName + ").\n" +
+          "  Fix: use `--legacy-pat --scope vault:admin` to mint a vault-DB pvt_* with admin scope " +
+          "(the right shape for an MCP entry needing schema management).\n" +
+          "  Or:  drop --scope to default to vault:read (least privilege), or use --scope vault:write.",
+      );
+      process.exit(1);
+    }
     const operatorToken = readOperatorToken();
     if (!operatorToken) {
       console.error(
@@ -3392,7 +3409,13 @@ Vaults:
                                             (any shape) instead of minting.
                                             --legacy-pat: mint a vault-DB pvt_*
                                             token (deprecated; for self-hosted-
-                                            without-hub setups).
+                                            without-hub setups). Also the only
+                                            path for --scope vault:admin — hub
+                                            policy reserves per-vault admin for
+                                            operator-only minting (the admin SPA
+                                            session-cookie path), so --mint
+                                            --scope vault:admin is rejected
+                                            pre-flight.
                                             --install-scope local (default) writes
                                             ~/.claude.json under
                                             projects[<cwd>].mcpServers (this
@@ -3449,12 +3472,18 @@ Tokens:
   parachute-vault tokens create --expires 30d     Expiring token
   parachute-vault tokens revoke <token-id>        Revoke a token (default vault)
 
-OAuth:
-  parachute-vault set-password             Set/change the owner password (for consent page)
+OAuth — owner password + 2FA (LEGACY):
+  Vault's standalone OAuth consent page was retired in 0.4.x (workstream E).
+  OAuth runs on the hub now. These commands still write the legacy YAML
+  fields (hub's \`expose public\` posture-check reads them), but they
+  don't gate any consent flow inside vault. Set hub credentials with
+  \`parachute auth set-password\`.
+
+  parachute-vault set-password             Set/change owner password (legacy YAML field)
   parachute-vault set-password --clear     Remove the owner password
   parachute-vault 2fa status               Show 2FA state
   parachute-vault 2fa enroll               Enable TOTP 2FA (QR + backup codes)
-  parachute-vault 2fa disable              Disable 2FA (requires password)
+  parachute-vault 2fa disable              Disable 2FA
   parachute-vault 2fa backup-codes         Regenerate backup codes
 
 Config:

package/src/config.test.ts

@@ -1,9 +1,12 @@
 import { describe, test, expect } from "bun:test";
+import { statSync } from "fs";
+import { join } from "path";
 import {
   writeVaultConfig,
   readVaultConfig,
   writeGlobalConfig,
   readGlobalConfig,
+  writeEnvFile,
   generateApiKey,
   hashKey,
   verifyKey,
@@ -210,6 +213,29 @@ describe("config", () => {
     expect(reloaded.api_keys?.find((k) => k.id === "k_legacy")?.scope).toBe("write");
   });
 
+  test("writeEnvFile writes .env at 0600 (SCRIBE_AUTH_TOKEN secrecy)", () => {
+    // Regression for vault#354 reviewer finding: the .env holds
+    // SCRIBE_AUTH_TOKEN (the vault↔scribe loopback bearer). On a
+    // shared-user machine or a Docker image with a loose umask, a
+    // world-readable .env would leak the bearer to any local process.
+    //
+    // Resolve the path dynamically from PARACHUTE_HOME (not the
+    // module-load-time `ENV_PATH` constant) so this test is robust to
+    // earlier tests in the suite that mutate PARACHUTE_HOME — writeEnvFile
+    // itself resolves the path dynamically via `envFilePath()`.
+    const envPath = join(process.env.PARACHUTE_HOME!, "vault", ".env");
+    writeEnvFile({ SCRIBE_AUTH_TOKEN: "test-bearer-do-not-leak", PORT: "1940" });
+    const mode = statSync(envPath).mode & 0o777;
+    expect(mode).toBe(0o600);
+
+    // Existing-file branch: writeFileSync's `mode` only applies on
+    // create, so the defensive chmodSync must downgrade an existing
+    // (e.g. 0644-from-an-older-version) .env to 0600 on the next write.
+    writeEnvFile({ SCRIBE_AUTH_TOKEN: "rotated", PORT: "1940" });
+    const mode2 = statSync(envPath).mode & 0o777;
+    expect(mode2).toBe(0o600);
+  });
+
   test("round-trips autostart: true|false (#113)", () => {
     // Default: absent means autostart-on (init registers the daemon).
     writeGlobalConfig({ port: 1940 });

package/src/config.ts

@@ -277,6 +277,24 @@ export interface GlobalConfig {
    * resolved path. See `./mirror-config.ts`.
    */
   mirror?: MirrorConfigType;
+  /**
+   * Auto-transcribe configuration for the vault↔scribe handoff (vault#353,
+   * design 2026-05-21 Part 2). When `enabled: true` AND scribe is discoverable
+   * (`services.json` or `SCRIBE_URL` env), audio attachments uploaded to any
+   * vault are automatically sent to scribe and the resulting transcript lands
+   * as a sibling `<attachment-path>.transcript.md` note.
+   *
+   * URL + bearer are not stored here — URL is resolved per-process from
+   * `services.json` via `scribe-discovery.ts`, and bearer comes from the
+   * `SCRIBE_AUTH_TOKEN` env var (persisted in `~/.parachute/vault/.env`).
+   * The schema's `autoTranscribe.scribeUrl` / `autoTranscribe.scribeBearer`
+   * fields are projection of those resolved values (readOnly / writeOnly),
+   * not separate storage.
+   */
+  auto_transcribe?: {
+    /** Master toggle. Default false; the worker is a no-op when unset. */
+    enabled?: boolean;
+  };
 }
 
 // ---------------------------------------------------------------------------
@@ -1141,6 +1159,22 @@ export function readGlobalConfig(): GlobalConfig {
       const totpSecretMatch = yaml.match(/^totp_secret:\s*"([^"]+)"/m);
       const discoveryMatch = yaml.match(/^discovery:\s*(enabled|disabled)/m);
       const autostartMatch = yaml.match(/^autostart:\s*(true|false)/m);
+      // auto_transcribe block — currently single boolean `enabled` (vault#353).
+      // Parsed as a nested 2-space-indent block so future fields can grow under
+      // it without breaking the regex; only `enabled` is read for v0.6.
+      const autoTranscribeStart = yaml.match(/^auto_transcribe:\s*$/m);
+      let autoTranscribeEnabled: boolean | undefined;
+      if (autoTranscribeStart) {
+        const after = yaml.slice((autoTranscribeStart.index ?? 0) + autoTranscribeStart[0].length);
+        for (const line of after.split("\n")) {
+          if (line.match(/^\S/) && line.trim().length > 0) break; // next top-level key
+          const m = line.match(/^\s+enabled:\s*(true|false)/);
+          if (m) {
+            autoTranscribeEnabled = m[1]! === "true";
+            break;
+          }
+        }
+      }
       const config: GlobalConfig = {
         port: portMatch ? parseInt(portMatch[1]!, 10) : DEFAULT_PORT,
         default_vault: defaultVaultMatch?.[1],
@@ -1153,6 +1187,9 @@ export function readGlobalConfig(): GlobalConfig {
       if (autostartMatch) {
         config.autostart = autostartMatch[1]! === "true";
       }
+      if (autoTranscribeEnabled !== undefined) {
+        config.auto_transcribe = { enabled: autoTranscribeEnabled };
+      }
 
       // Parse backup_codes: a YAML list of quoted bcrypt hashes under
       //   backup_codes:
@@ -1297,6 +1334,13 @@ export function writeGlobalConfig(config: GlobalConfig): void {
     lines.push(...serializeMirrorSection(config.mirror));
   }
 
+  if (config.auto_transcribe) {
+    lines.push("auto_transcribe:");
+    if (config.auto_transcribe.enabled !== undefined) {
+      lines.push(`  enabled: ${config.auto_transcribe.enabled}`);
+    }
+  }
+
   // 0600 — owner read/write only. This file may contain the bcrypt password
   // hash and plaintext TOTP secret; it must not be world- or group-readable.
   writeFileSync(globalConfigPath(), lines.join("\n") + "\n", { mode: 0o600 });
@@ -1395,7 +1439,15 @@ export function writeEnvFile(env: Record<string, string>): void {
       lines.push(`${key}=${val}`);
     }
   }
-  writeFileSync(envFilePath(), lines.join("\n") + "\n");
+  // 0600 — owner read/write only. This file holds SCRIBE_AUTH_TOKEN (the
+  // vault↔scribe loopback bearer) and any other secrets the operator drops
+  // in via `parachute-vault config set`. It must not be world- or
+  // group-readable on shared-user machines or Docker images with a loose
+  // umask. Mirrors the writeGlobalConfig pattern above.
+  writeFileSync(envFilePath(), lines.join("\n") + "\n", { mode: 0o600 });
+  // writeFileSync's `mode` only applies on file creation, so chmod an existing
+  // file explicitly in case it was written by an older version at 0644.
+  try { chmodSync(envFilePath(), 0o600); } catch {}
 }
 
 /**

package/src/db.ts

@@ -4,11 +4,24 @@
 
 import { Database } from "bun:sqlite";
 import { vaultDbPath, vaultDir } from "./config.ts";
+import { applyConnectionPragmas } from "../core/src/schema.ts";
 import { mkdirSync } from "fs";
 
-/** Open (or create) a vault's SQLite database. */
+/**
+ * Open (or create) a vault's SQLite database with vault's standard
+ * connection pragmas (WAL + synchronous=NORMAL + foreign_keys=ON). Safe
+ * for both the in-process store and out-of-process consumers (CLI,
+ * parachute-runner, mirror tools) — pragmas are idempotent.
+ *
+ * The full schema migration runs separately when a `BunSqliteStore` is
+ * instantiated around the returned handle; callers that just want raw
+ * read access (auth probes, backup tooling) skip that and pay only the
+ * pragma cost.
+ */
 export function openVaultDb(name: string): Database {
   const dir = vaultDir(name);
   mkdirSync(dir, { recursive: true });
-  return new Database(vaultDbPath(name));
+  const db = new Database(vaultDbPath(name));
+  applyConnectionPragmas(db);
+  return db;
 }

package/src/export-watch.test.ts

@@ -37,6 +37,25 @@ import {
 
 const CLI = path.resolve(import.meta.dir, "cli.ts");
 
+// Capture HOME / PARACHUTE_HOME at module load so `seedVaultWithNotes`'s
+// in-process env mutation (required for the deferred `vault-store.ts`
+// re-import to see PARACHUTE_HOME) can be reverted between tests. Without
+// this, the polluted HOME leaks into later tests in the same process — most
+// visibly into `resolveInstallTarget` (mcp-install.test.ts), which reads
+// `process.env.HOME` directly and would otherwise return paths under the
+// tmpdir. Linux-only failure because macOS BSD developers were less likely
+// to notice in dev; CI on Linux exposed it after the tag-triggered release
+// workflow landed (vault#361). See vault#363.
+const ORIG_HOME = process.env.HOME;
+const ORIG_PARACHUTE_HOME = process.env.PARACHUTE_HOME;
+
+function restoreHomeEnv(): void {
+  if (ORIG_HOME === undefined) delete process.env.HOME;
+  else process.env.HOME = ORIG_HOME;
+  if (ORIG_PARACHUTE_HOME === undefined) delete process.env.PARACHUTE_HOME;
+  else process.env.PARACHUTE_HOME = ORIG_PARACHUTE_HOME;
+}
+
 // ---------------------------------------------------------------------------
 // Shared test helpers
 // ---------------------------------------------------------------------------
@@ -439,6 +458,7 @@ describe("export CLI: single-shot", () => {
     clearVaultStoreCache();
     fs.rmSync(tmp, { recursive: true, force: true });
     fs.rmSync(exportDir, { recursive: true, force: true });
+    restoreHomeEnv();
   });
 
   test("--git-commit requires an initialized git repo (clear error)", () => {
@@ -702,6 +722,7 @@ describe("export CLI: --watch", () => {
     clearVaultStoreCache();
     fs.rmSync(tmp, { recursive: true, force: true });
     fs.rmSync(exportDir, { recursive: true, force: true });
+    restoreHomeEnv();
   });
 
   test(

package/src/mcp-install-interactive.test.ts

@@ -287,8 +287,23 @@ describe("runInteractiveInstall — decision tree", () => {
     expect(result.scope).toBe("vault:write");
   });
 
-  test("scope widening: typing 'admin' produces vault:admin mint", async () => {
-    const { io } = mockIO([
+  test("typing 'admin' auto-routes to legacy-pat with vault:admin scope (hub mint-token rejects admin)", async () => {
+    // Regression for the symptom Aaron hit on hub 0.5.12-rc.2 / vault
+    // 0.4.7-rc.1: picking "admin" in the mint prompt sent
+    // `vault:default:admin` to `POST /api/auth/mint-token`, which hub
+    // rejects by policy (per-vault admin is non-requestable; see
+    // `parachute-hub/src/scope-explanations.ts:VAULT_ADMIN_RE` and
+    // `api-mint-token.ts`'s non-requestable guard):
+    //
+    //   Hub mint-token rejected (HTTP 400, invalid_scope):
+    //   scope vault:default:admin is not requestable via mint-token;
+    //   use OAuth flow or operator rotation
+    //
+    // Fix: auto-route "admin" in the interactive prompt to legacy-pat
+    // mode (which mints a vault-DB pvt_* — the right shape for an MCP
+    // entry needing admin permissions), with a printed explanation so
+    // the switch isn't silent.
+    const { io, state } = mockIO([
       null,    // accept install-scope default
       "admin",
       true,
@@ -296,7 +311,13 @@ describe("runInteractiveInstall — decision tree", () => {
     const result = await runInteractiveInstall(baseCtx(), io);
     expect(result).not.toBe("abort");
     if (result === "abort") return;
+    expect(result.mode).toBe("legacy-pat");
     expect(result.scope).toBe("vault:admin");
+    // The auto-route must surface the reason — silent re-routing would
+    // mislead operators who specifically want a hub JWT.
+    const logged = state.logs.join("\n");
+    expect(logged).toMatch(/admin requires a vault-DB pvt_\*/);
+    expect(logged).toMatch(/hub policy/);
   });
 
   test("typing 'paste' at the auth prompt switches to token mode + asks for token", async () => {

package/src/mcp-install-interactive.ts

@@ -190,7 +190,9 @@ export async function runInteractiveInstall(
         "Choices:",
         "  Enter       → mint a hub JWT with vault:read scope (recommended).",
         "  write       → mint with vault:write (mutations).",
-        "  admin       → mint with vault:admin (schema management).",
+        "  admin       → mint a vault-DB pvt_* with vault:admin (schema management;",
+        "                hub policy reserves per-vault admin for operator-only paths,",
+        "                so this auto-routes to legacy-pat).",
         "  paste       → use an existing token instead of minting.",
         "  legacy      → mint a vault-DB pvt_* (self-hosted-without-hub).",
       ].join("\n"),
@@ -209,10 +211,27 @@ export async function runInteractiveInstall(
       // operator gets the same control they get when widening a hub
       // JWT's scope. (vault#292 review F2.)
       scope = await askScope(io);
+    } else if (answer === "admin") {
+      // `vault:<name>:admin` is non-requestable via hub mint-token by
+      // policy — only the session-cookie-gated `/admin/vault-admin-token/:name`
+      // endpoint can mint per-vault admin scopes (see
+      // `parachute-hub/src/scope-explanations.ts:VAULT_ADMIN_RE` and
+      // `api-mint-token.ts`'s non-requestable guard). Hub returns
+      // HTTP 400 invalid_scope: "scope vault:<name>:admin is not
+      // requestable via mint-token; use OAuth flow or operator rotation".
+      //
+      // Auto-route to legacy-pat which mints a vault-DB pvt_* with full
+      // permissions — that's the right shape for an operator who wants
+      // admin scope on a local MCP entry. Print a one-line explanation
+      // so the switch isn't silent.
+      io.log("  → admin requires a vault-DB pvt_* (hub policy: per-vault admin");
+      io.log("    is operator-only, not mintable via the public mint-token API).");
+      io.log("    Switching to legacy-pat mode with vault:admin scope.");
+      mode = "legacy-pat";
+      scope = "vault:admin";
     } else {
       mode = "mint";
       if (answer === "write") scope = "vault:write";
-      else if (answer === "admin") scope = "vault:admin";
     }
   } else {
     // No hub-mint path available — explain why and offer the alternatives.

package/src/mcp-install.test.ts

@@ -522,6 +522,46 @@ describe("mcp-install flag parsing", () => {
     expect(res.exitCode).toBe(1);
     expect(res.stderr).toMatch(/No hub origin configured/);
   });
+
+  test("rejects --mint --scope vault:admin pre-flight (hub policy: per-vault admin is non-requestable)", () => {
+    // Regression for the symptom Aaron hit on hub 0.5.12-rc.2 / vault
+    // 0.4.7-rc.1: `parachute vault mcp-install` with the "admin" mint
+    // option sent `vault:default:admin` to `POST /api/auth/mint-token`,
+    // and hub responded:
+    //
+    //   Hub mint-token rejected (HTTP 400, invalid_scope):
+    //   scope vault:default:admin is not requestable via mint-token;
+    //   use OAuth flow or operator rotation
+    //
+    // The combination is invalid by hub policy (see
+    // `parachute-hub/src/scope-explanations.ts:VAULT_ADMIN_RE` and
+    // `api-mint-token.ts`'s non-requestable guard) — per-vault admin
+    // is operator-only, mintable only through the session-cookie-gated
+    // `/admin/vault-admin-token/:name` SPA path.
+    //
+    // The fix rejects the combination pre-flight in vault's mcp-install
+    // with a clear remediation pointing at `--legacy-pat --scope vault:admin`
+    // (which mints a vault-DB pvt_* with admin scope — the right shape
+    // for a local MCP entry needing schema management).
+    setupBareVault(tmp, "default");
+    fs.writeFileSync(path.join(tmp, "operator.token"), "operator-bearer-stub");
+    const res = runCli(
+      ["mcp-install", "--mint", "--scope", "vault:admin"],
+      tmp,
+      { PARACHUTE_HUB_ORIGIN: "https://hub.example.org" },
+    );
+    expect(res.exitCode).toBe(1);
+    // Surface the policy reason so the operator knows why this combo is
+    // rejected (not a transient bug).
+    expect(res.stderr).toMatch(/not requestable via mint-token/);
+    // Point at the working remediation.
+    expect(res.stderr).toMatch(/--legacy-pat --scope vault:admin/);
+    // Pre-flight must fire BEFORE the operator-token / hub-origin checks
+    // pass the request to the network — no "Hub unreachable" / "No hub
+    // origin configured" leak.
+    expect(res.stderr).not.toMatch(/No hub origin configured/);
+    expect(res.stderr).not.toMatch(/Hub unreachable/);
+  });
 });
 
 // ---------------------------------------------------------------------------

package/src/mcp-tools.ts

@@ -178,10 +178,26 @@ function applyTagScopeWrappers(
     const allowed = await getAllowed();
     const result = await orig(params);
     if (!allowed) return result;
-    // Single-note shape (`{...note}` with `id`) vs list shape (array).
+    // Three possible response shapes:
+    //   - Array (legacy list, no cursor)
+    //   - `{notes, next_cursor}` (cursor mode, vault#313)
+    //   - `{...note}` with `id`+`tags` (single-note by id)
     if (Array.isArray(result)) {
       return result.filter((n: any) => noteWithinTagScope(n, allowed, rawTags));
     }
+    if (
+      result &&
+      typeof result === "object" &&
+      "notes" in result &&
+      Array.isArray((result as any).notes) &&
+      "next_cursor" in result
+    ) {
+      const r = result as { notes: any[]; next_cursor: string | null };
+      return {
+        notes: r.notes.filter((n: any) => noteWithinTagScope(n, allowed, rawTags)),
+        next_cursor: r.next_cursor,
+      };
+    }
     if (result && typeof result === "object" && "id" in result && "tags" in result) {
       return noteWithinTagScope(result as any, allowed, rawTags)
         ? result