@openparachute/vault 0.4.7-rc.1 → 0.4.8-rc.4

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

package/src/module-config.ts

@@ -15,15 +15,27 @@
  * PUT /.parachute/config is Phase 3 — not implemented here.
  *
  * Fields currently described:
- *   - audio_retention: per-vault enum, backed by VaultConfig.audio_retention.
- *   - scribe_url:      env var SCRIBE_URL (read-only for now — there is no
- *                      yaml slot yet, so PUT won't come online until Phase 3).
- *   - scribe_token:    env var SCRIBE_TOKEN, writeOnly (never returned).
- *   - port:            GlobalConfig.port, exposed read-only so the hub can
- *                      display it without round-tripping through /health.
+ *   - audio_retention:      per-vault enum, backed by VaultConfig.audio_retention.
+ *   - port:                 GlobalConfig.port, exposed read-only.
+ *   - autoTranscribe.*:     vault↔scribe handoff (vault#353, design 2026-05-21
+ *                           Part 2). Three nested fields per design Q4:
+ *       - enabled:          boolean toggle, default false (persisted in
+ *                           GlobalConfig.auto_transcribe.enabled).
+ *       - scribeUrl:        readOnly — resolved per-process from
+ *                           `~/.parachute/services.json` via
+ *                           `scribe-discovery.ts`. Operators can't point at an
+ *                           arbitrary scribe; the discovery layer is the gate.
+ *       - scribeBearer:     writeOnly — sourced from SCRIBE_AUTH_TOKEN env var.
+ *                           Hub install generates one at first boot
+ *                           (see scribe-env.ts:ensureScribeBearer); manual
+ *                           rotation is via `parachute-vault config set`.
+ *   - scribe_url / scribe_token (deprecated): kept under their legacy names
+ *                           through one release for the hub admin SPA's prior
+ *                           render path; new code should read autoTranscribe.*.
  */
 
 import type { VaultConfig, GlobalConfig } from "./config.ts";
+import { resolveScribeUrl } from "./scribe-discovery.ts";
 
 export interface ModuleConfigSchema {
   $schema: string;
@@ -49,20 +61,54 @@ export function buildConfigSchema(): ModuleConfigSchema {
         description:
           "What to do with audio attachments after transcription. `keep` leaves the file on disk; `until_transcribed` unlinks on successful transcribe (keeps on failure for retry); `never` unlinks on any terminal state (including failure — no retries).",
       },
+      autoTranscribe: {
+        type: "object",
+        title: "Auto-transcribe voice uploads",
+        description:
+          "When enabled, audio attachments (mime-type prefix `audio/`) are automatically sent to scribe and the resulting transcript lands as a sibling `<attachment-path>.transcript.md` note. Scribe must be reachable for transcription to succeed; failures are recorded as a transcript note with `transcript_status: failed`.",
+        properties: {
+          enabled: {
+            type: "boolean",
+            default: false,
+            title: "Enable auto-transcription",
+            description:
+              "Master toggle. When false, audio uploads land normally without any scribe interaction. Global — persisted in `GlobalConfig.auto_transcribe.enabled` and applies to every vault on this server. Per-vault control is a future enhancement when multi-vault deployments need it.",
+          },
+          scribeUrl: {
+            type: "string",
+            format: "uri",
+            readOnly: true,
+            title: "Scribe URL",
+            description:
+              "URL of the scribe service. Auto-populated from `~/.parachute/services.json` at vault startup (or from the SCRIBE_URL env var when set). Read-only — operators can't point at an arbitrary scribe.",
+          },
+          scribeBearer: {
+            type: "string",
+            writeOnly: true,
+            title: "Scribe auth bearer",
+            description:
+              "Shared bearer for the vault→scribe loopback contract. Hub install generates one at first boot. Write-only — never returned by GET.",
+          },
+        },
+      },
+      // Legacy aliases kept for back-compat with callers that read the
+      // pre-vault#353 shape. New consumers should read `autoTranscribe.*`.
       scribe_url: {
         type: "string",
         format: "uri",
-        title: "Scribe URL",
+        title: "Scribe URL (deprecated alias)",
         description:
-          "URL of the Scribe service for transcription. Empty disables the background worker. Currently sourced from the SCRIBE_URL env var; a PUT slot lands in Phase 3.",
+          "Legacy alias for `autoTranscribe.scribeUrl`. Will be removed in a future release.",
         readOnly: true,
+        deprecated: true,
       },
       scribe_token: {
         type: "string",
-        title: "Scribe auth token",
+        title: "Scribe auth token (deprecated alias)",
         description:
-          "Optional bearer token for Scribe. Stored in the SCRIBE_TOKEN env var today. Write-only — never returned by GET.",
+          "Legacy alias for `autoTranscribe.scribeBearer`. Will be removed in a future release.",
         writeOnly: true,
+        deprecated: true,
       },
       port: {
         type: "integer",
@@ -77,18 +123,28 @@ export function buildConfigSchema(): ModuleConfigSchema {
 }
 
 /**
- * Effective config values, with `writeOnly` fields stripped. `scribe_token` is
- * declared `writeOnly` and is never returned here, even when SCRIBE_TOKEN is
- * set in the environment.
+ * Effective config values, with `writeOnly` fields stripped. `scribeBearer`
+ * (and its legacy alias `scribe_token`) are declared `writeOnly` and never
+ * returned, even when set in the environment.
  */
 export function buildConfigValues(
   vaultConfig: VaultConfig,
   globalConfig: GlobalConfig,
   env: { SCRIBE_URL?: string | undefined } = process.env as { SCRIBE_URL?: string },
 ): Record<string, unknown> {
+  // Resolve scribe URL through the discovery layer so the GET shape reflects
+  // what the worker will actually use (services.json > SCRIBE_URL > unset).
+  // Pass env through so the test harness's override is honored.
+  const scribeUrl = resolveScribeUrl(env as NodeJS.ProcessEnv) ?? "";
   return {
     audio_retention: vaultConfig.audio_retention ?? "keep",
-    scribe_url: env.SCRIBE_URL ?? "",
+    autoTranscribe: {
+      enabled: globalConfig.auto_transcribe?.enabled ?? false,
+      scribeUrl,
+    },
+    // Legacy alias mirrors `autoTranscribe.scribeUrl` so hubs reading the
+    // pre-vault#353 shape don't regress.
+    scribe_url: scribeUrl,
     port: globalConfig.port,
   };
 }

package/src/module-manifest.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { readSelfManifest, resolvePackageRoot } from "./module-manifest.ts";
+
+function withTempPackageRoot(
+  manifest: unknown | undefined,
+  fn: (root: string) => void,
+): void {
+  const root = mkdtempSync(join(tmpdir(), "pvault-manifest-"));
+  try {
+    if (manifest !== undefined) {
+      mkdirSync(join(root, ".parachute"), { recursive: true });
+      writeFileSync(
+        join(root, ".parachute", "module.json"),
+        typeof manifest === "string" ? manifest : JSON.stringify(manifest),
+      );
+    }
+    fn(root);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+describe("module-manifest", () => {
+  test("resolvePackageRoot returns the directory containing package.json", () => {
+    // In the test env, this module lives at <repo>/src/module-manifest.test.ts —
+    // so the resolved root is the repo root. We don't pin the exact path
+    // (tests run from various cwds); we just sanity-check it's an absolute
+    // directory ending in the vault repo's name.
+    const root = resolvePackageRoot();
+    expect(root.startsWith("/")).toBe(true);
+    expect(root.endsWith("/src")).toBe(false);
+  });
+
+  test("readSelfManifest returns null when .parachute/module.json is missing", () => {
+    withTempPackageRoot(undefined, (root) => {
+      expect(readSelfManifest(root)).toBeNull();
+    });
+  });
+
+  test("readSelfManifest parses a valid manifest", () => {
+    withTempPackageRoot(
+      {
+        name: "vault",
+        manifestName: "parachute-vault",
+        displayName: "Vault",
+        tagline: "Test tagline",
+        kind: "api",
+        port: 1940,
+        paths: ["/vault/default"],
+        health: "/vault/default/health",
+      },
+      (root) => {
+        const m = readSelfManifest(root);
+        expect(m).not.toBeNull();
+        expect(m?.name).toBe("vault");
+        expect(m?.manifestName).toBe("parachute-vault");
+        expect(m?.displayName).toBe("Vault");
+        expect(m?.kind).toBe("api");
+        expect(m?.port).toBe(1940);
+        expect(m?.paths).toEqual(["/vault/default"]);
+      },
+    );
+  });
+
+  test("readSelfManifest throws on malformed JSON", () => {
+    withTempPackageRoot("{ not valid json", (root) => {
+      expect(() => readSelfManifest(root)).toThrow();
+    });
+  });
+
+  test("readSelfManifest throws when required field missing", () => {
+    withTempPackageRoot(
+      { name: "vault" /* missing manifestName / port / paths / health / kind */ },
+      (root) => {
+        expect(() => readSelfManifest(root)).toThrow(/missing required/);
+      },
+    );
+  });
+
+  test("readSelfManifest reads the actual shipped manifest in the repo", () => {
+    // Smoke test the real shipped file — guards against ever shipping a
+    // malformed manifest. Uses the real resolvePackageRoot (which finds
+    // the repo root in tests).
+    const m = readSelfManifest();
+    expect(m).not.toBeNull();
+    expect(m?.manifestName).toBe("parachute-vault");
+    expect(m?.kind).toBe("api");
+    expect(m?.port).toBe(1940);
+  });
+});

package/src/module-manifest.ts

@@ -0,0 +1,94 @@
+/**
+ * Reader for the package's own `.parachute/module.json`.
+ *
+ * Vault ships `module.json` alongside `package.json` at the package root.
+ * This module locates the file via `import.meta.url` (which works for both
+ * `bun src/cli.ts …` dev runs and the published-package `parachute-vault`
+ * binary — the file ships in `package.json` `files` next to `src/`).
+ *
+ * Used by `self-register.ts` on server boot: vault reads its own manifest
+ * + computes the package's `installDir` so the services.json row carries
+ * the same metadata that hub's `FIRST_PARTY_FALLBACKS[vault]` provides
+ * today. The endgame is that hub's vendored fallback retires once every
+ * first-party module self-registers reliably — this is the POC for the
+ * pattern.
+ *
+ * Shape mirrors `parachute-hub/src/module-manifest.ts`. Kept narrow: we
+ * only consume the fields vault stamps onto services.json
+ * (displayName, tagline, stripPrefix). The full manifest validator lives
+ * on the hub side; vault treats its own manifest as authored-by-us +
+ * trusts the shape.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export type ModuleKind = "api" | "frontend" | "tool";
+
+/**
+ * Subset of the full manifest schema (see `parachute-hub/src/module-manifest.ts`)
+ * — only the fields vault's self-registration consumes today. Adding more is
+ * a one-line edit when the surface widens.
+ */
+export interface VaultModuleManifest {
+  readonly name: string;
+  readonly manifestName: string;
+  readonly displayName?: string;
+  readonly tagline?: string;
+  readonly kind: ModuleKind;
+  readonly port: number;
+  readonly paths: readonly string[];
+  readonly health: string;
+  readonly stripPrefix?: boolean;
+}
+
+/**
+ * Resolve the path to the package root — the directory containing both
+ * `package.json` and `.parachute/module.json`. Walks up from
+ * `import.meta.url` so the answer is correct under both:
+ *
+ *   - dev:  `bun src/cli.ts serve` → `src/module-manifest.ts` → parent = repo root
+ *   - prod: published package → `src/module-manifest.ts` → parent = installed
+ *           package dir (e.g. `~/.bun/install/global/node_modules/@openparachute/vault`)
+ *
+ * Exported for tests + the self-register flow that needs to stamp this as
+ * `installDir` on the services.json row.
+ */
+export function resolvePackageRoot(): string {
+  const here = dirname(fileURLToPath(import.meta.url));
+  // `src/module-manifest.ts` lives one level under the package root.
+  return resolve(here, "..");
+}
+
+/**
+ * Read `<packageRoot>/.parachute/module.json` if present. Returns null when
+ * the file is missing (e.g. during local dev before the file was committed)
+ * — callers treat that as "self-registration unavailable, log + continue."
+ *
+ * Throws on malformed JSON: a corrupt manifest is a deploy bug we want to
+ * surface, not silently swallow. The self-register caller catches + logs
+ * so a bad manifest doesn't crash server boot.
+ */
+export function readSelfManifest(
+  packageRoot: string = resolvePackageRoot(),
+): VaultModuleManifest | null {
+  const path = join(packageRoot, ".parachute", "module.json");
+  if (!existsSync(path)) return null;
+  const raw = readFileSync(path, "utf8");
+  const parsed = JSON.parse(raw) as Record<string, unknown>;
+  // Minimal shape validation. Only the fields we actually consume — anything
+  // else passes through untouched. Strict full-shape validation is the hub's
+  // job (it'll fail an install on a malformed manifest); vault treats its
+  // own shipped file as authored-by-us.
+  if (typeof parsed.name !== "string" || typeof parsed.manifestName !== "string") {
+    throw new Error(`${path}: manifest missing required "name" / "manifestName"`);
+  }
+  if (typeof parsed.port !== "number" || !Array.isArray(parsed.paths)) {
+    throw new Error(`${path}: manifest missing required "port" / "paths"`);
+  }
+  if (typeof parsed.health !== "string" || typeof parsed.kind !== "string") {
+    throw new Error(`${path}: manifest missing required "health" / "kind"`);
+  }
+  return parsed as unknown as VaultModuleManifest;
+}