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

package/src/scribe-discovery.ts

@@ -0,0 +1,91 @@
+/**
+ * Service discovery for the scribe transcription module.
+ *
+ * Per the 2026-05-21 vault↔scribe design (Part 2, design question 2), vault
+ * locates scribe via `~/.parachute/services.json` — the canonical hub-
+ * maintained registry. This module is the single read site so the
+ * resolution rule lives in one place.
+ *
+ * Resolution order (first hit wins):
+ *
+ *   1. `SCRIBE_URL` env var (operator override; useful for tests, Docker
+ *      compose, and any deploy where scribe runs at a non-loopback host).
+ *   2. Entry `name === "parachute-scribe"` in `~/.parachute/services.json`
+ *      → construct `http://127.0.0.1:<port>`.
+ *   3. `undefined` (auto-transcribe stays a no-op).
+ *
+ * The bearer token resolution stays in `./scribe-env.ts:resolveScribeAuthToken`.
+ * Service discovery is just about WHERE scribe lives; AUTH is a separate
+ * concern with its own env-var precedence (SCRIBE_AUTH_TOKEN over the legacy
+ * SCRIBE_TOKEN). When the v0.7 hub-issued-JWT path lands, the bearer source
+ * changes but the URL source stays the same — one file, one concern.
+ *
+ * v0.6 deploy is single-container (hub-as-supervisor) so loopback is fine.
+ * v0.7 cloud-multi-container will grow an `origin` field on the services.json
+ * entry; this resolver will honor it without API changes — `port` becomes
+ * a fallback when `origin` isn't set, no breaking change for v0.6 callers.
+ */
+
+import { readManifest, ServicesManifestError } from "./services-manifest.ts";
+
+/**
+ * Resolve the scribe base URL (no trailing slash) by consulting the env-var
+ * override first, then services.json. Returns `undefined` when scribe isn't
+ * configured — callers MUST treat that as "auto-transcribe disabled."
+ *
+ * The `env` + `readManifestImpl` parameters are injection seams for tests;
+ * production callers omit them and pick up `process.env` + the real
+ * `~/.parachute/services.json`.
+ */
+export function resolveScribeUrl(
+  env: NodeJS.ProcessEnv = process.env,
+  readManifestImpl: typeof readManifest = readManifest,
+  logger: { warn?: (...args: unknown[]) => void } = console,
+): string | undefined {
+  const override = env.SCRIBE_URL?.trim();
+  if (override) return override.replace(/\/$/, "");
+
+  let manifest;
+  try {
+    manifest = readManifestImpl();
+  } catch (err) {
+    if (err instanceof ServicesManifestError) {
+      logger.warn?.(`[scribe-discovery] services.json unreadable: ${err.message}`);
+    } else {
+      logger.warn?.(`[scribe-discovery] services.json read failed: ${err}`);
+    }
+    return undefined;
+  }
+  const entry = manifest.services.find((s) => s.name === "parachute-scribe");
+  if (!entry) return undefined;
+  // v0.6 loopback shape; v0.7 will add an explicit `origin` field on the
+  // service entry which wins over loopback when present.
+  const origin = (entry as { origin?: string }).origin;
+  if (typeof origin === "string" && origin.trim()) {
+    return origin.trim().replace(/\/$/, "");
+  }
+  return `http://127.0.0.1:${entry.port}`;
+}
+
+/**
+ * Process-lifetime cache. Computed at first call (typically during server
+ * boot), reused for every subsequent transcription request. Operators who
+ * change the scribe URL via `services.json` (re-install of scribe with a
+ * different port) need to restart vault; we deliberately don't watch the
+ * file because the v0.6 deploy model has a single restart-on-change story.
+ *
+ * Tests should pass an explicit `env` + `readManifestImpl` to `resolveScribeUrl`
+ * directly to bypass the cache.
+ */
+let cachedScribeUrl: string | undefined | null = null;
+
+export function getCachedScribeUrl(): string | undefined {
+  if (cachedScribeUrl === null) {
+    cachedScribeUrl = resolveScribeUrl();
+  }
+  return cachedScribeUrl;
+}
+
+export function clearScribeUrlCache(): void {
+  cachedScribeUrl = null;
+}

package/src/scribe-env.test.ts

@@ -1,5 +1,5 @@
 import { describe, test, expect } from "bun:test";
-import { resolveScribeAuthToken } from "./scribe-env.ts";
+import { resolveScribeAuthToken, generateScribeBearer, ensureScribeBearer } from "./scribe-env.ts";
 
 function captureWarn() {
   const calls: unknown[][] = [];
@@ -47,3 +47,68 @@ describe("resolveScribeAuthToken", () => {
     expect(calls.length).toBe(0);
   });
 });
+
+describe("generateScribeBearer (vault#353)", () => {
+  test("returns 32-byte base64url string (~43 chars, no padding)", () => {
+    const bearer = generateScribeBearer();
+    // 32 bytes base64url-encoded = 43 chars (no `=` padding in base64url).
+    expect(bearer.length).toBe(43);
+    expect(bearer).toMatch(/^[A-Za-z0-9_-]+$/);
+  });
+
+  test("each call yields a unique value", () => {
+    const a = generateScribeBearer();
+    const b = generateScribeBearer();
+    expect(a).not.toBe(b);
+  });
+});
+
+describe("ensureScribeBearer (vault#353)", () => {
+  test("generates + persists a bearer when neither env var is set", () => {
+    const env: Record<string, string> = {};
+    const writes: Array<[string, string]> = [];
+    const { created, token } = ensureScribeBearer(
+      () => ({ ...env }),
+      (k, v) => writes.push([k, v]),
+    );
+    expect(created).toBe(true);
+    expect(token.length).toBe(43);
+    expect(writes).toEqual([["SCRIBE_AUTH_TOKEN", token]]);
+  });
+
+  test("preserves existing SCRIBE_AUTH_TOKEN (idempotent)", () => {
+    const env: Record<string, string> = { SCRIBE_AUTH_TOKEN: "already-set" };
+    const writes: Array<[string, string]> = [];
+    const { created, token } = ensureScribeBearer(
+      () => ({ ...env }),
+      (k, v) => writes.push([k, v]),
+    );
+    expect(created).toBe(false);
+    expect(token).toBe("already-set");
+    expect(writes.length).toBe(0);
+  });
+
+  test("preserves legacy SCRIBE_TOKEN without rewriting it", () => {
+    const env: Record<string, string> = { SCRIBE_TOKEN: "legacy" };
+    const writes: Array<[string, string]> = [];
+    const { created, token } = ensureScribeBearer(
+      () => ({ ...env }),
+      (k, v) => writes.push([k, v]),
+    );
+    expect(created).toBe(false);
+    expect(token).toBe("legacy");
+    expect(writes.length).toBe(0);
+  });
+
+  test("treats whitespace-only env value as unset (generates fresh)", () => {
+    const env: Record<string, string> = { SCRIBE_AUTH_TOKEN: "   " };
+    const writes: Array<[string, string]> = [];
+    const { created, token } = ensureScribeBearer(
+      () => ({ ...env }),
+      (k, v) => writes.push([k, v]),
+    );
+    expect(created).toBe(true);
+    expect(token.length).toBe(43);
+    expect(writes[0]?.[0]).toBe("SCRIBE_AUTH_TOKEN");
+  });
+});

package/src/scribe-env.ts

@@ -3,9 +3,12 @@
  *
  * Lives in its own module so the boot-time token resolution in server.ts is
  * testable without running the rest of server.ts (which has side effects:
- * triggers, auto-init, Bun.serve). Keep this module pure and dependency-free.
+ * triggers, auto-init, Bun.serve). Keep this module pure and dependency-free
+ * (except for the `node:crypto` import used by bearer generation).
  */
 
+import { randomBytes } from "node:crypto";
+
 /**
  * Resolve the scribe auth token. `SCRIBE_AUTH_TOKEN` is the canonical name
  * (matches the CLI's install-time auto-wire); `SCRIBE_TOKEN` is a legacy alias
@@ -31,3 +34,41 @@ export function resolveScribeAuthToken(
   }
   return undefined;
 }
+
+/**
+ * Generate a fresh shared bearer for the vault↔scribe loopback contract
+ * (design 2026-05-21 Part 2, design question 2). 32 random bytes → base64url
+ * encoded. The operator (or hub install) writes the result into vault's
+ * `~/.parachute/vault/.env` as `SCRIBE_AUTH_TOKEN` AND into scribe's config
+ * (via env propagation or the scribe admin endpoint).
+ *
+ * Generation is callable as a pure function so install code, tests, and any
+ * future "rotate scribe bearer" admin endpoint share the same length +
+ * encoding without copy-paste.
+ */
+export function generateScribeBearer(): string {
+  return randomBytes(32).toString("base64url");
+}
+
+/**
+ * Ensure a scribe bearer exists in the vault .env. Idempotent: if a value
+ * (canonical or legacy) is already set, returns `{ created: false, token: ... }`
+ * without touching the file. Otherwise generates a fresh bearer, persists it
+ * to the .env via the provided writer, and returns `{ created: true, token }`.
+ *
+ * The `envReader` + `envWriter` parameters are injection seams for tests; the
+ * production caller (`cli.ts` init flow) passes `readEnvFile` + `setEnvVar`.
+ */
+export function ensureScribeBearer(
+  envReader: () => Record<string, string>,
+  envWriter: (key: string, value: string) => void,
+): { created: boolean; token: string } {
+  const env = envReader();
+  const existing = env.SCRIBE_AUTH_TOKEN ?? env.SCRIBE_TOKEN;
+  if (existing && existing.trim()) {
+    return { created: false, token: existing };
+  }
+  const token = generateScribeBearer();
+  envWriter("SCRIBE_AUTH_TOKEN", token);
+  return { created: true, token };
+}

package/src/self-register.test.ts

@@ -0,0 +1,380 @@
+import { describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { buildVaultServicePaths, selfRegister } from "./self-register.ts";
+import type { VaultModuleManifest } from "./module-manifest.ts";
+
+/**
+ * Spin up a fresh PARACHUTE_HOME tmpdir + restore the prior env on teardown.
+ * The self-register pass writes through to `~/.parachute/services.json` via
+ * the per-call path resolution in services-manifest.ts (which honors
+ * PARACHUTE_HOME), so this is the canonical isolation seam.
+ */
+function withParachuteHome(fn: (home: string) => void): void {
+  const home = mkdtempSync(join(tmpdir(), "pvault-self-register-"));
+  const prior = process.env.PARACHUTE_HOME;
+  process.env.PARACHUTE_HOME = home;
+  // Also override HOME so readGlobalConfig + listVaults don't fall through
+  // to the operator's real ~/.parachute.
+  const priorHome = process.env.HOME;
+  process.env.HOME = home;
+  try {
+    // Seed the config dir with an empty config.yaml so readGlobalConfig
+    // returns a clean state.
+    mkdirSync(join(home, "vault"), { recursive: true });
+    writeFileSync(join(home, "vault", "config.yaml"), "port: 1940\n");
+    fn(home);
+  } finally {
+    if (prior === undefined) delete process.env.PARACHUTE_HOME;
+    else process.env.PARACHUTE_HOME = prior;
+    if (priorHome === undefined) delete process.env.HOME;
+    else process.env.HOME = priorHome;
+    rmSync(home, { recursive: true, force: true });
+  }
+}
+
+const TEST_MANIFEST: VaultModuleManifest = {
+  name: "vault",
+  manifestName: "parachute-vault",
+  displayName: "Vault",
+  tagline: "Test tagline",
+  kind: "api",
+  port: 1940,
+  paths: ["/vault/default"],
+  health: "/vault/default/health",
+};
+
+function captureLogs(): {
+  log: (m: string) => void;
+  warn: (m: string) => void;
+  logs: string[];
+  warnings: string[];
+} {
+  const logs: string[] = [];
+  const warnings: string[] = [];
+  return {
+    log: (m: string) => logs.push(m),
+    warn: (m: string) => warnings.push(m),
+    logs,
+    warnings,
+  };
+}
+
+describe("self-register", () => {
+  test("buildVaultServicePaths — no vaults yet → manifest fallback", () => {
+    expect(buildVaultServicePaths(undefined, [], ["/vault/default"])).toEqual([
+      "/vault/default",
+    ]);
+  });
+
+  test("buildVaultServicePaths — default vault sorts first", () => {
+    expect(
+      buildVaultServicePaths("default", ["alpha", "default", "beta"], ["/"]),
+    ).toEqual(["/vault/default", "/vault/alpha", "/vault/beta"]);
+  });
+
+  test("buildVaultServicePaths — no default → map by listed order", () => {
+    expect(buildVaultServicePaths(undefined, ["alpha", "beta"], ["/"])).toEqual([
+      "/vault/alpha",
+      "/vault/beta",
+    ]);
+  });
+
+  test("buildVaultServicePaths — default points to missing vault → ignore default", () => {
+    expect(
+      buildVaultServicePaths("missing", ["alpha", "beta"], ["/"]),
+    ).toEqual(["/vault/alpha", "/vault/beta"]);
+  });
+
+  test("writes services.json with manifest-sourced fields + installDir", () => {
+    withParachuteHome((home) => {
+      const { log, warn, logs, warnings } = captureLogs();
+      const result = selfRegister({
+        version: "0.4.8-rc.3",
+        log,
+        warn,
+        readManifest: () => TEST_MANIFEST,
+        resolvePackageRoot: () => "/fake/install/dir",
+        listVaults: () => [],
+        readGlobalConfig: () => ({ port: 1940 }),
+      });
+      expect(result.status).toBe("registered");
+      expect(warnings).toEqual([]);
+      expect(logs[0]).toContain("registered parachute-vault");
+
+      const raw = readFileSync(join(home, "services.json"), "utf8");
+      const parsed = JSON.parse(raw) as { services: unknown[] };
+      expect(parsed.services).toHaveLength(1);
+      const row = parsed.services[0] as Record<string, unknown>;
+      expect(row.name).toBe("parachute-vault");
+      expect(row.port).toBe(1940);
+      expect(row.paths).toEqual(["/vault/default"]);
+      expect(row.health).toBe("/vault/default/health");
+      expect(row.version).toBe("0.4.8-rc.3");
+      expect(row.installDir).toBe("/fake/install/dir");
+      expect(row.displayName).toBe("Vault");
+      expect(row.tagline).toBe("Test tagline");
+    });
+  });
+
+  test("idempotent — re-running reports no changes", () => {
+    withParachuteHome(() => {
+      const { log, warn } = captureLogs();
+      const deps = {
+        version: "0.4.8-rc.3",
+        log,
+        warn,
+        readManifest: () => TEST_MANIFEST,
+        resolvePackageRoot: () => "/fake/install/dir",
+        listVaults: () => [],
+        readGlobalConfig: () => ({ port: 1940 }),
+      };
+      const first = selfRegister(deps);
+      expect(first.status).toBe("registered");
+      if (first.status === "registered") expect(first.changed).toBe(true);
+
+      const second = selfRegister(deps);
+      expect(second.status).toBe("registered");
+      if (second.status === "registered") expect(second.changed).toBe(false);
+    });
+  });
+
+  test("preserves hub-stamped fields on the row", () => {
+    withParachuteHome((home) => {
+      // Pre-existing row carries a hub-stamped field we don't write.
+      const servicesPath = join(home, "services.json");
+      writeFileSync(
+        servicesPath,
+        `${JSON.stringify(
+          {
+            services: [
+              {
+                name: "parachute-vault",
+                port: 1940,
+                paths: ["/vault/default"],
+                health: "/vault/default/health",
+                version: "0.4.7",
+                // Pretend hub stamped some custom field — should survive.
+                hubCustomField: "preserved",
+                installDir: "/some/prior/path",
+              },
+            ],
+          },
+          null,
+          2,
+        )}\n`,
+      );
+
+      const { log, warn } = captureLogs();
+      const result = selfRegister({
+        version: "0.4.8-rc.3",
+        log,
+        warn,
+        readManifest: () => TEST_MANIFEST,
+        resolvePackageRoot: () => "/new/install/dir",
+        listVaults: () => [],
+        readGlobalConfig: () => ({ port: 1940 }),
+      });
+      expect(result.status).toBe("registered");
+
+      const raw = readFileSync(servicesPath, "utf8");
+      const parsed = JSON.parse(raw) as { services: Record<string, unknown>[] };
+      const row = parsed.services[0]!;
+      // Vault-owned fields win.
+      expect(row.version).toBe("0.4.8-rc.3");
+      expect(row.installDir).toBe("/new/install/dir");
+      // Hub-stamped foreign field survives.
+      expect(row.hubCustomField).toBe("preserved");
+    });
+  });
+
+  test("preserves entries written by other modules", () => {
+    withParachuteHome((home) => {
+      const servicesPath = join(home, "services.json");
+      writeFileSync(
+        servicesPath,
+        `${JSON.stringify(
+          {
+            services: [
+              {
+                name: "parachute-scribe",
+                port: 1943,
+                paths: ["/scribe"],
+                health: "/scribe/health",
+                version: "0.3.0",
+              },
+            ],
+          },
+          null,
+          2,
+        )}\n`,
+      );
+
+      const { log, warn } = captureLogs();
+      selfRegister({
+        version: "0.4.8-rc.3",
+        log,
+        warn,
+        readManifest: () => TEST_MANIFEST,
+        resolvePackageRoot: () => "/fake/install/dir",
+        listVaults: () => [],
+        readGlobalConfig: () => ({ port: 1940 }),
+      });
+
+      const raw = readFileSync(servicesPath, "utf8");
+      const parsed = JSON.parse(raw) as { services: { name: string }[] };
+      expect(parsed.services).toHaveLength(2);
+      expect(parsed.services.find((s) => s.name === "parachute-scribe")).toBeDefined();
+      expect(parsed.services.find((s) => s.name === "parachute-vault")).toBeDefined();
+    });
+  });
+
+  test("skipped when manifest absent — never throws", () => {
+    withParachuteHome(() => {
+      const { log, warn, warnings } = captureLogs();
+      const result = selfRegister({
+        version: "0.4.8-rc.3",
+        log,
+        warn,
+        readManifest: () => null,
+        resolvePackageRoot: () => "/fake/install/dir",
+        listVaults: () => [],
+        readGlobalConfig: () => ({ port: 1940 }),
+      });
+      expect(result.status).toBe("skipped");
+      if (result.status === "skipped") expect(result.reason).toMatch(/manifest absent/);
+      expect(warnings).toEqual([]); // skipped is informational, not a warning
+    });
+  });
+
+  test("failed when manifest read throws — does not propagate", () => {
+    withParachuteHome(() => {
+      const { log, warn, warnings } = captureLogs();
+      const result = selfRegister({
+        version: "0.4.8-rc.3",
+        log,
+        warn,
+        readManifest: () => {
+          throw new Error("corrupt JSON");
+        },
+        resolvePackageRoot: () => "/fake/install/dir",
+        listVaults: () => [],
+        readGlobalConfig: () => ({ port: 1940 }),
+      });
+      expect(result.status).toBe("failed");
+      if (result.status === "failed") expect(result.reason).toContain("corrupt JSON");
+      expect(warnings.some((w) => w.includes("could not read"))).toBe(true);
+    });
+  });
+
+  test("failed when upsert throws — does not propagate", () => {
+    withParachuteHome(() => {
+      const { log, warn, warnings } = captureLogs();
+      const result = selfRegister({
+        version: "0.4.8-rc.3",
+        log,
+        warn,
+        readManifest: () => TEST_MANIFEST,
+        resolvePackageRoot: () => "/fake/install/dir",
+        listVaults: () => [],
+        readGlobalConfig: () => ({ port: 1940 }),
+        upsertService: () => {
+          throw new Error("disk full");
+        },
+      });
+      expect(result.status).toBe("failed");
+      if (result.status === "failed") expect(result.reason).toContain("disk full");
+      expect(warnings.some((w) => w.includes("services.json write failed"))).toBe(true);
+    });
+  });
+
+  test("multi-vault: default vault sorts first in paths", () => {
+    withParachuteHome((home) => {
+      const { log, warn } = captureLogs();
+      selfRegister({
+        version: "0.4.8-rc.3",
+        log,
+        warn,
+        readManifest: () => TEST_MANIFEST,
+        resolvePackageRoot: () => "/fake/install/dir",
+        listVaults: () => ["alpha", "default", "beta"],
+        readGlobalConfig: () => ({ port: 1940, default_vault: "default" }),
+      });
+
+      const raw = readFileSync(join(home, "services.json"), "utf8");
+      const parsed = JSON.parse(raw) as { services: Record<string, unknown>[] };
+      expect(parsed.services[0]!.paths).toEqual([
+        "/vault/default",
+        "/vault/alpha",
+        "/vault/beta",
+      ]);
+    });
+  });
+
+  test("uses globalConfig.port over DEFAULT_PORT when set", () => {
+    withParachuteHome((home) => {
+      const { log, warn } = captureLogs();
+      selfRegister({
+        version: "0.4.8-rc.3",
+        log,
+        warn,
+        readManifest: () => TEST_MANIFEST,
+        resolvePackageRoot: () => "/fake/install/dir",
+        listVaults: () => [],
+        readGlobalConfig: () => ({ port: 19999 }),
+      });
+
+      const raw = readFileSync(join(home, "services.json"), "utf8");
+      const parsed = JSON.parse(raw) as { services: Record<string, unknown>[] };
+      expect(parsed.services[0]!.port).toBe(19999);
+    });
+  });
+
+  test("stripPrefix flows from manifest to row when set", () => {
+    withParachuteHome((home) => {
+      const { log, warn } = captureLogs();
+      selfRegister({
+        version: "0.4.8-rc.3",
+        log,
+        warn,
+        readManifest: () => ({ ...TEST_MANIFEST, stripPrefix: true }),
+        resolvePackageRoot: () => "/fake/install/dir",
+        listVaults: () => [],
+        readGlobalConfig: () => ({ port: 1940 }),
+      });
+
+      const raw = readFileSync(join(home, "services.json"), "utf8");
+      const parsed = JSON.parse(raw) as { services: Record<string, unknown>[] };
+      expect(parsed.services[0]!.stripPrefix).toBe(true);
+    });
+  });
+
+  test("changed=true when installDir differs from prior row", () => {
+    withParachuteHome(() => {
+      const { log, warn } = captureLogs();
+      const baseDeps = {
+        version: "0.4.8-rc.3",
+        log,
+        warn,
+        readManifest: () => TEST_MANIFEST,
+        listVaults: () => [],
+        readGlobalConfig: () => ({ port: 1940 }),
+      };
+      const first = selfRegister({
+        ...baseDeps,
+        resolvePackageRoot: () => "/old/install/dir",
+      });
+      expect(first.status).toBe("registered");
+      if (first.status === "registered") expect(first.changed).toBe(true);
+
+      // Second call with a different installDir — should re-stamp.
+      const second = selfRegister({
+        ...baseDeps,
+        resolvePackageRoot: () => "/new/install/dir",
+      });
+      expect(second.status).toBe("registered");
+      if (second.status === "registered") expect(second.changed).toBe(true);
+    });
+  });
+});