@openparachute/vault 0.2.3 → 0.3.0-rc.1

package/src/scopes.test.ts

@@ -0,0 +1,136 @@
+/**
+ * Unit tests for scope primitives — parse, match, inheritance, legacy
+ * permission fallback. Integration tests for scope enforcement at the
+ * HTTP boundary live in routing.test.ts + vault.test.ts.
+ */
+
+import { describe, test, expect } from "bun:test";
+import {
+  SCOPE_READ,
+  SCOPE_WRITE,
+  SCOPE_ADMIN,
+  parseScopes,
+  hasScope,
+  scopeForMethod,
+  legacyPermissionToScopes,
+  serializeScopes,
+} from "./scopes.ts";
+
+describe("parseScopes", () => {
+  test("returns [] for null or empty input", () => {
+    expect(parseScopes(null)).toEqual([]);
+    expect(parseScopes(undefined)).toEqual([]);
+    expect(parseScopes("")).toEqual([]);
+    expect(parseScopes("   ")).toEqual([]);
+  });
+
+  test("splits on whitespace and trims", () => {
+    expect(parseScopes("vault:read vault:write")).toEqual([SCOPE_READ, SCOPE_WRITE]);
+    expect(parseScopes("  vault:read   vault:write  ")).toEqual([SCOPE_READ, SCOPE_WRITE]);
+    expect(parseScopes("vault:read\tvault:write\nvault:admin")).toEqual([
+      SCOPE_READ, SCOPE_WRITE, SCOPE_ADMIN,
+    ]);
+  });
+
+  test("collapses vault:<name>:<verb> synonym to vault:<verb>", () => {
+    expect(parseScopes("vault:journal:read")).toEqual([SCOPE_READ]);
+    expect(parseScopes("vault:journal:write vault:work:admin")).toEqual([
+      SCOPE_WRITE, SCOPE_ADMIN,
+    ]);
+  });
+
+  test("preserves unrecognized scopes verbatim", () => {
+    expect(parseScopes("profile email")).toEqual(["profile", "email"]);
+    expect(parseScopes("vault:unknown:frob")).toEqual(["vault:unknown:frob"]);
+  });
+
+  test("empty name segment does NOT collapse (vault::read stays literal)", () => {
+    // Guard against a hand-crafted DB row with `vault::read` satisfying a
+    // `vault:read` check by accident. Only reachable via direct DB write,
+    // not API input, but the parser stays honest.
+    expect(parseScopes("vault::read")).toEqual(["vault::read"]);
+    expect(hasScope(parseScopes("vault::read"), SCOPE_READ)).toBe(false);
+  });
+});
+
+describe("hasScope — inheritance admin ⊇ write ⊇ read", () => {
+  test("exact match succeeds", () => {
+    expect(hasScope([SCOPE_READ], SCOPE_READ)).toBe(true);
+    expect(hasScope([SCOPE_WRITE], SCOPE_WRITE)).toBe(true);
+    expect(hasScope([SCOPE_ADMIN], SCOPE_ADMIN)).toBe(true);
+  });
+
+  test("vault:write satisfies vault:read", () => {
+    expect(hasScope([SCOPE_WRITE], SCOPE_READ)).toBe(true);
+  });
+
+  test("vault:admin satisfies vault:read and vault:write", () => {
+    expect(hasScope([SCOPE_ADMIN], SCOPE_READ)).toBe(true);
+    expect(hasScope([SCOPE_ADMIN], SCOPE_WRITE)).toBe(true);
+  });
+
+  test("vault:read does NOT satisfy vault:write or vault:admin", () => {
+    expect(hasScope([SCOPE_READ], SCOPE_WRITE)).toBe(false);
+    expect(hasScope([SCOPE_READ], SCOPE_ADMIN)).toBe(false);
+  });
+
+  test("vault:write does NOT satisfy vault:admin", () => {
+    expect(hasScope([SCOPE_WRITE], SCOPE_ADMIN)).toBe(false);
+  });
+
+  test("empty granted list fails", () => {
+    expect(hasScope([], SCOPE_READ)).toBe(false);
+    expect(hasScope([], SCOPE_WRITE)).toBe(false);
+    expect(hasScope([], SCOPE_ADMIN)).toBe(false);
+  });
+
+  test("non-vault scopes require exact match — no inheritance", () => {
+    expect(hasScope(["profile"], "profile")).toBe(true);
+    expect(hasScope(["profile"], "email")).toBe(false);
+    expect(hasScope([SCOPE_ADMIN], "profile")).toBe(false);
+  });
+});
+
+describe("scopeForMethod", () => {
+  test("read methods → vault:read", () => {
+    expect(scopeForMethod("GET")).toBe(SCOPE_READ);
+    expect(scopeForMethod("HEAD")).toBe(SCOPE_READ);
+    expect(scopeForMethod("OPTIONS")).toBe(SCOPE_READ);
+    expect(scopeForMethod("get")).toBe(SCOPE_READ); // case-insensitive
+  });
+
+  test("write methods → vault:write", () => {
+    expect(scopeForMethod("POST")).toBe(SCOPE_WRITE);
+    expect(scopeForMethod("PATCH")).toBe(SCOPE_WRITE);
+    expect(scopeForMethod("PUT")).toBe(SCOPE_WRITE);
+    expect(scopeForMethod("DELETE")).toBe(SCOPE_WRITE);
+  });
+
+  test("unknown method falls back to vault:write (default-deny)", () => {
+    expect(scopeForMethod("TRACE")).toBe(SCOPE_WRITE);
+  });
+});
+
+describe("legacyPermissionToScopes", () => {
+  test("'read' → [vault:read]", () => {
+    expect(legacyPermissionToScopes("read")).toEqual([SCOPE_READ]);
+  });
+
+  test("'full' and anything else → [read, write, admin]", () => {
+    expect(legacyPermissionToScopes("full")).toEqual([SCOPE_READ, SCOPE_WRITE, SCOPE_ADMIN]);
+    expect(legacyPermissionToScopes("admin")).toEqual([SCOPE_READ, SCOPE_WRITE, SCOPE_ADMIN]);
+    expect(legacyPermissionToScopes("write")).toEqual([SCOPE_READ, SCOPE_WRITE, SCOPE_ADMIN]);
+  });
+});
+
+describe("serializeScopes — round-trips with parseScopes", () => {
+  test("joins with spaces", () => {
+    expect(serializeScopes([SCOPE_READ, SCOPE_WRITE])).toBe("vault:read vault:write");
+    expect(serializeScopes([])).toBe("");
+  });
+
+  test("serialize then parse is the identity (for known scopes)", () => {
+    const scopes = [SCOPE_READ, SCOPE_WRITE, SCOPE_ADMIN];
+    expect(parseScopes(serializeScopes(scopes))).toEqual(scopes);
+  });
+});

package/src/scopes.ts

@@ -0,0 +1,105 @@
+/**
+ * Scope primitives for Phase 2 enforcement.
+ *
+ * Tokens carry OAuth-standard whitespace-separated scopes. This module parses,
+ * normalizes, and matches them — including the `admin ⊇ write ⊇ read`
+ * inheritance rule and the `vault:<name>:<verb>` future-shape synonym
+ * (narrowed per-vault scopes are Phase 2+; today we treat them as equivalent
+ * to `vault:<verb>`).
+ *
+ * Legacy back-compat: tokens without any `vault:*` scope — but with a
+ * 0.2.x-era `permission = "full" | "read"` — are mapped to the appropriate
+ * scope set on the fly. `legacyPermissionToScopes` is marked deprecated and
+ * should be removed one release after enforcement lands.
+ */
+
+export const SCOPE_READ = "vault:read" as const;
+export const SCOPE_WRITE = "vault:write" as const;
+export const SCOPE_ADMIN = "vault:admin" as const;
+
+/** All first-class vault scopes in inheritance order (lowest → highest). */
+export const VAULT_SCOPES = [SCOPE_READ, SCOPE_WRITE, SCOPE_ADMIN] as const;
+export type VaultScope = (typeof VAULT_SCOPES)[number];
+
+/**
+ * Parse a whitespace-separated scope string into a normalized scope list.
+ *
+ * Normalization:
+ *   - Empty / null → []
+ *   - Trim + split on any whitespace
+ *   - `vault:<name>:<verb>` collapses to `vault:<verb>` (per-vault narrowing
+ *     is Phase 2+; today it's treated as a synonym)
+ *   - Unrecognized scopes are preserved as-is (they just won't match anything)
+ */
+export function parseScopes(raw: string | null | undefined): string[] {
+  if (!raw) return [];
+  return raw
+    .split(/\s+/)
+    .map((s) => s.trim())
+    .filter(Boolean)
+    .map((s) => normalizeScope(s));
+}
+
+function normalizeScope(scope: string): string {
+  // `vault:<name>:<verb>` → `vault:<verb>` (synonym collapse). Reject an empty
+  // name segment (`vault::read`) — preserve it as-is so it can't accidentally
+  // satisfy a `vault:read` check. Only reachable via direct DB write, but the
+  // one-liner keeps the parser honest.
+  const parts = scope.split(":");
+  if (parts.length === 3 && parts[0] === "vault" && parts[1].length > 0) {
+    const verb = parts[2];
+    if (verb === "read" || verb === "write" || verb === "admin") {
+      return `vault:${verb}`;
+    }
+  }
+  return scope;
+}
+
+/**
+ * Return true iff `granted` satisfies `required` under the inheritance rule
+ * `admin ⊇ write ⊇ read`. Exact-match required for non-vault scopes.
+ */
+export function hasScope(granted: string[], required: string): boolean {
+  if (granted.includes(required)) return true;
+
+  // Inheritance: admin ⊇ write ⊇ read
+  if (required === SCOPE_READ) {
+    return granted.includes(SCOPE_WRITE) || granted.includes(SCOPE_ADMIN);
+  }
+  if (required === SCOPE_WRITE) {
+    return granted.includes(SCOPE_ADMIN);
+  }
+  return false;
+}
+
+/**
+ * Pick the required scope for a given API request.
+ *   - GET/HEAD/OPTIONS → read
+ *   - POST/PATCH/PUT/DELETE → write
+ *
+ * Admin-gated endpoints (like `/.parachute/config`) don't go through this
+ * helper — they call `hasScope(auth.scopes, SCOPE_ADMIN)` directly.
+ */
+export function scopeForMethod(method: string): VaultScope {
+  const m = method.toUpperCase();
+  if (m === "GET" || m === "HEAD" || m === "OPTIONS") return SCOPE_READ;
+  return SCOPE_WRITE;
+}
+
+/**
+ * Map a 0.2.x legacy `permission` column value to scopes. Kept for back-compat
+ * during the one-release-cycle deprecation window — after that, every token
+ * row will carry an explicit `scopes` column and this can go.
+ *
+ * @deprecated Remove one release after v0.4 scope enforcement lands.
+ */
+export function legacyPermissionToScopes(permission: string): string[] {
+  // "full", "admin", "write" all historically meant unrestricted access
+  if (permission === "read") return [SCOPE_READ];
+  return [SCOPE_READ, SCOPE_WRITE, SCOPE_ADMIN];
+}
+
+/** Serialize a scope list to an OAuth-standard whitespace-separated string. */
+export function serializeScopes(scopes: string[]): string {
+  return scopes.join(" ");
+}

package/src/scribe-env.test.ts

@@ -0,0 +1,49 @@
+import { describe, test, expect } from "bun:test";
+import { resolveScribeAuthToken } from "./scribe-env.ts";
+
+function captureWarn() {
+  const calls: unknown[][] = [];
+  return { logger: { warn: (...args: unknown[]) => calls.push(args) }, calls };
+}
+
+describe("resolveScribeAuthToken", () => {
+  test("returns SCRIBE_AUTH_TOKEN when set (canonical)", () => {
+    const { logger, calls } = captureWarn();
+    const token = resolveScribeAuthToken(
+      { SCRIBE_AUTH_TOKEN: "canonical-v1" } as NodeJS.ProcessEnv,
+      logger,
+    );
+    expect(token).toBe("canonical-v1");
+    // Canonical path is silent — no deprecation warning.
+    expect(calls.length).toBe(0);
+  });
+
+  test("prefers canonical over legacy when both set", () => {
+    const { logger, calls } = captureWarn();
+    const token = resolveScribeAuthToken(
+      { SCRIBE_AUTH_TOKEN: "new", SCRIBE_TOKEN: "old" } as NodeJS.ProcessEnv,
+      logger,
+    );
+    expect(token).toBe("new");
+    expect(calls.length).toBe(0);
+  });
+
+  test("falls back to SCRIBE_TOKEN with deprecation warning", () => {
+    const { logger, calls } = captureWarn();
+    const token = resolveScribeAuthToken(
+      { SCRIBE_TOKEN: "legacy-v0" } as NodeJS.ProcessEnv,
+      logger,
+    );
+    expect(token).toBe("legacy-v0");
+    expect(calls.length).toBe(1);
+    expect(String(calls[0][0])).toContain("SCRIBE_TOKEN is deprecated");
+    expect(String(calls[0][0])).toContain("SCRIBE_AUTH_TOKEN");
+  });
+
+  test("returns undefined when neither is set (loopback back-compat)", () => {
+    const { logger, calls } = captureWarn();
+    const token = resolveScribeAuthToken({} as NodeJS.ProcessEnv, logger);
+    expect(token).toBeUndefined();
+    expect(calls.length).toBe(0);
+  });
+});

package/src/scribe-env.ts

@@ -0,0 +1,33 @@
+/**
+ * Env-var plumbing for the scribe integration (transcription worker + triggers).
+ *
+ * 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.
+ */
+
+/**
+ * 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
+ * kept for one release — when only the legacy name is set, we warn once so
+ * users notice and rename.
+ *
+ * Returns `undefined` when neither is set; callers must treat that as "no
+ * Authorization header" (back-compat with loopback-trust deployments).
+ */
+export function resolveScribeAuthToken(
+  env: NodeJS.ProcessEnv = process.env,
+  logger: { warn: (...args: unknown[]) => void } = console,
+): string | undefined {
+  const canonical = env.SCRIBE_AUTH_TOKEN;
+  if (canonical) return canonical;
+  const legacy = env.SCRIBE_TOKEN;
+  if (legacy) {
+    logger.warn(
+      "[transcribe] SCRIBE_TOKEN is deprecated; rename to SCRIBE_AUTH_TOKEN. " +
+      "The legacy name will stop being read in the next release.",
+    );
+    return legacy;
+  }
+  return undefined;
+}

package/src/server.ts

@@ -4,11 +4,13 @@
  *
  * Routes:
  *   GET  /health                           — health check
- *   *    /mcp                              — unified MCP (all vaults, vault param)
- *   *    /vaults/{name}/mcp                — scoped MCP (single vault, no vault param)
  *   GET  /vaults                           — list vaults with metadata (authenticated)
  *   GET  /vaults/list                      — list vault names (public; disable via config.discovery)
- *   *    /vaults/{name}/api/...            — per-vault REST API
+ *   *    /vault/{name}/mcp                 — scoped MCP (per-vault session)
+ *   *    /vault/{name}/oauth/...           — per-vault OAuth flow
+ *   *    /vault/{name}/.well-known/...     — per-vault OAuth discovery
+ *   *    /vault/{name}/view/...            — auth-aware HTML note view
+ *   *    /vault/{name}/api/...             — per-vault REST API
  *
  * The request pipeline lives in ./routing.ts (exported for unit testing).
  */
@@ -19,6 +21,9 @@ import { getVaultStore } from "./vault-store.ts";
 import { defaultHookRegistry } from "../core/src/hooks.ts";
 import { registerTriggers } from "./triggers.ts";
 import { route } from "./routing.ts";
+import { startTranscriptionWorker, type TranscriptionWorker } from "./transcription-worker.ts";
+import { assetsDir } from "./routes.ts";
+import { resolveScribeAuthToken } from "./scribe-env.ts";
 
 // Register webhook triggers from global config. Replaces the old hardcoded
 // tts-hook and transcription-hook with config-driven webhooks.
@@ -30,10 +35,54 @@ function registerConfiguredTriggers(): void {
   }
   registerTriggers(defaultHookRegistry, config.triggers);
   console.log(`[triggers] registered ${config.triggers.length} trigger(s)`);
+
+  // Soft-deprecation warning: if the dedicated transcription worker is
+  // enabled AND a trigger points at what looks like the same scribe endpoint,
+  // both will process the same attachments. The trigger's `missing_metadata`
+  // guard keeps it idempotent once the worker marks `transcript` on the
+  // attachment, but the noise is worth flagging.
+  if (process.env.SCRIBE_URL) {
+    const scribeHost = safeHost(process.env.SCRIBE_URL);
+    for (const t of config.triggers) {
+      if (t.action.send !== "attachment") continue;
+      if (scribeHost && safeHost(t.action.webhook) === scribeHost) {
+        console.warn(
+          `[triggers] "${t.name}" points at scribe (${t.action.webhook}) and the dedicated worker is also enabled; ` +
+          `these may double-fire. Prefer the dedicated worker for /v1/audio/transcriptions and remove this trigger.`,
+        );
+      }
+    }
+  }
+}
+
+function safeHost(url: string): string | null {
+  try { return new URL(url).host; } catch { return null; }
 }
 
 registerConfiguredTriggers();
 
+/**
+ * Start the transcription worker if SCRIBE_URL is configured. The worker
+ * polls every vault for attachments with `metadata.transcribe_status = "pending"`
+ * and sends the audio to scribe. Absent SCRIBE_URL, the worker stays off
+ * — `{transcribe: true}` uploads still enqueue, they just wait.
+ */
+let transcriptionWorker: TranscriptionWorker | null = null;
+if (process.env.SCRIBE_URL) {
+  transcriptionWorker = startTranscriptionWorker({
+    vaultList: () => listVaults(),
+    getStore: (name) => getVaultStore(name),
+    scribeUrl: process.env.SCRIBE_URL,
+    scribeToken: resolveScribeAuthToken(),
+    resolveAssetsDir: (vault) => assetsDir(vault),
+    getAudioRetention: (vault) => readVaultConfig(vault)?.audio_retention ?? "keep",
+    getContextPredicates: (vault) => readVaultConfig(vault)?.transcription?.context,
+  });
+  console.log(`[transcribe] worker started → ${process.env.SCRIBE_URL}`);
+} else {
+  console.log("[transcribe] worker disabled (set SCRIBE_URL to enable)");
+}
+
 ensureConfigDirSync();
 loadEnvFile();
 
@@ -166,11 +215,14 @@ async function shutdown(signal: string): Promise<void> {
   console.log(`\n[${signal}] shutting down; in-flight hooks: ${defaultHookRegistry.inFlightCount}`);
   try {
     await Promise.race([
-      defaultHookRegistry.drain(),
+      Promise.all([
+        defaultHookRegistry.drain(),
+        transcriptionWorker?.stop() ?? Promise.resolve(),
+      ]),
       new Promise<void>((resolve) => setTimeout(resolve, 5000)),
     ]);
   } catch (err) {
-    console.error("[shutdown] hook drain error:", err);
+    console.error("[shutdown] drain error:", err);
   }
   process.exit(0);
 }

package/src/services-manifest.test.ts

@@ -0,0 +1,140 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  type ServiceEntry,
+  ServicesManifestError,
+  readManifest,
+  upsertService,
+} from "./services-manifest.ts";
+
+function tempPath(): { path: string; cleanup: () => void } {
+  const dir = mkdtempSync(join(tmpdir(), "pvault-manifest-"));
+  const path = join(dir, "services.json");
+  return { path, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
+}
+
+const vault: ServiceEntry = {
+  name: "parachute-vault",
+  port: 1940,
+  paths: ["/"],
+  health: "/health",
+  version: "0.2.4",
+};
+
+const notes: ServiceEntry = {
+  name: "parachute-notes",
+  port: 5173,
+  paths: ["/notes"],
+  health: "/notes/health",
+  version: "0.0.1",
+};
+
+describe("services-manifest", () => {
+  test("readManifest returns empty when file missing", () => {
+    const { path, cleanup } = tempPath();
+    try {
+      expect(readManifest(path)).toEqual({ services: [] });
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("upsertService creates the file if missing", () => {
+    const { path, cleanup } = tempPath();
+    try {
+      const m = upsertService(vault, path);
+      expect(m.services).toEqual([vault]);
+      expect(readManifest(path)).toEqual({ services: [vault] });
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("upsertService updates by name and never duplicates", () => {
+    const { path, cleanup } = tempPath();
+    try {
+      upsertService(vault, path);
+      const updated = { ...vault, version: "0.3.0", port: 1941 };
+      upsertService(updated, path);
+      const m = readManifest(path);
+      expect(m.services).toHaveLength(1);
+      expect(m.services[0]).toEqual(updated);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("upsertService preserves entries written by other services", () => {
+    const { path, cleanup } = tempPath();
+    try {
+      writeFileSync(path, `${JSON.stringify({ services: [notes] }, null, 2)}\n`);
+      upsertService(vault, path);
+      const m = readManifest(path);
+      expect(m.services).toHaveLength(2);
+      expect(m.services.find((s) => s.name === "parachute-notes")).toEqual(notes);
+      expect(m.services.find((s) => s.name === "parachute-vault")).toEqual(vault);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("upsertService writes pretty-printed JSON with trailing newline", () => {
+    const { path, cleanup } = tempPath();
+    try {
+      upsertService(vault, path);
+      const raw = readFileSync(path, "utf8");
+      expect(raw).toBe(`${JSON.stringify({ services: [vault] }, null, 2)}\n`);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("readManifest throws ServicesManifestError on malformed JSON", () => {
+    const { path, cleanup } = tempPath();
+    try {
+      writeFileSync(path, "{ not json");
+      expect(() => readManifest(path)).toThrow(ServicesManifestError);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("readManifest throws ServicesManifestError on schema violation", () => {
+    const { path, cleanup } = tempPath();
+    try {
+      writeFileSync(path, JSON.stringify({ services: [{ name: "x" }] }));
+      expect(() => readManifest(path)).toThrow(ServicesManifestError);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("upsertService rejects invalid entry without touching the file", () => {
+    const { path, cleanup } = tempPath();
+    try {
+      writeFileSync(path, `${JSON.stringify({ services: [notes] }, null, 2)}\n`);
+      const bad = { ...vault, port: -1 };
+      expect(() => upsertService(bad as ServiceEntry, path)).toThrow(ServicesManifestError);
+      expect(readManifest(path)).toEqual({ services: [notes] });
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("default path honors PARACHUTE_HOME set at runtime", () => {
+    const dir = mkdtempSync(join(tmpdir(), "pvault-home-"));
+    const prior = process.env.PARACHUTE_HOME;
+    process.env.PARACHUTE_HOME = dir;
+    try {
+      upsertService(vault);
+      expect(readManifest()).toEqual({ services: [vault] });
+      expect(readManifest(join(dir, "services.json"))).toEqual({ services: [vault] });
+    } finally {
+      if (prior === undefined) delete process.env.PARACHUTE_HOME;
+      else process.env.PARACHUTE_HOME = prior;
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/services-manifest.ts

@@ -0,0 +1,99 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+
+// Resolve per-call so `PARACHUTE_HOME` set at runtime (Docker, tests) is
+// honored, matching the pattern in `config.ts`.
+function servicesManifestPath(): string {
+  const root = process.env.PARACHUTE_HOME ?? join(homedir(), ".parachute");
+  return join(root, "services.json");
+}
+
+export interface ServiceEntry {
+  name: string;
+  port: number;
+  paths: string[];
+  health: string;
+  version: string;
+}
+
+export interface ServicesManifest {
+  services: ServiceEntry[];
+}
+
+export class ServicesManifestError extends Error {
+  override name = "ServicesManifestError";
+}
+
+function validateEntry(raw: unknown, where: string): ServiceEntry {
+  if (!raw || typeof raw !== "object") {
+    throw new ServicesManifestError(`${where}: expected object, got ${typeof raw}`);
+  }
+  const e = raw as Record<string, unknown>;
+  const { name, port, paths, health, version } = e;
+  if (typeof name !== "string" || name.length === 0) {
+    throw new ServicesManifestError(`${where}: "name" must be a non-empty string`);
+  }
+  if (typeof port !== "number" || !Number.isInteger(port) || port <= 0 || port > 65535) {
+    throw new ServicesManifestError(`${where}: "port" must be an integer 1..65535`);
+  }
+  if (!Array.isArray(paths) || paths.some((p) => typeof p !== "string")) {
+    throw new ServicesManifestError(`${where}: "paths" must be an array of strings`);
+  }
+  if (typeof health !== "string" || !health.startsWith("/")) {
+    throw new ServicesManifestError(`${where}: "health" must be a path starting with "/"`);
+  }
+  if (typeof version !== "string") {
+    throw new ServicesManifestError(`${where}: "version" must be a string`);
+  }
+  return { name, port, paths: paths as string[], health, version };
+}
+
+function validateManifest(raw: unknown, where: string): ServicesManifest {
+  if (!raw || typeof raw !== "object") {
+    throw new ServicesManifestError(`${where}: root must be an object`);
+  }
+  const services = (raw as Record<string, unknown>).services;
+  if (!Array.isArray(services)) {
+    throw new ServicesManifestError(`${where}: "services" must be an array`);
+  }
+  return {
+    services: services.map((s, i) => validateEntry(s, `${where} services[${i}]`)),
+  };
+}
+
+export function readManifest(path: string = servicesManifestPath()): ServicesManifest {
+  if (!existsSync(path)) return { services: [] };
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(path, "utf8"));
+  } catch (err) {
+    throw new ServicesManifestError(
+      `failed to parse ${path}: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  return validateManifest(raw, path);
+}
+
+function writeManifest(manifest: ServicesManifest, path: string): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+  writeFileSync(tmp, `${JSON.stringify(manifest, null, 2)}\n`);
+  renameSync(tmp, path);
+}
+
+export function upsertService(
+  entry: ServiceEntry,
+  path: string = servicesManifestPath(),
+): ServicesManifest {
+  validateEntry(entry, "entry");
+  const current = readManifest(path);
+  const idx = current.services.findIndex((s) => s.name === entry.name);
+  if (idx >= 0) {
+    current.services[idx] = entry;
+  } else {
+    current.services.push(entry);
+  }
+  writeManifest(current, path);
+  return current;
+}

package/src/systemd.ts

@@ -2,7 +2,7 @@
  * Linux systemd service management for the vault daemon.
  *
  * Installs a user-level systemd service (~/.config/systemd/user/).
- * Uses EnvironmentFile to load ~/.parachute/.env.
+ * Uses EnvironmentFile to load ~/.parachute/vault/.env.
  */
 
 import { homedir } from "os";
@@ -10,7 +10,7 @@ import { join } from "path";
 import { writeFile, mkdir, unlink } from "fs/promises";
 import { existsSync } from "fs";
 import { $ } from "bun";
-import { CONFIG_DIR, LOG_PATH, ERR_PATH } from "./config.ts";
+import { VAULT_HOME, LOG_PATH, ERR_PATH } from "./config.ts";
 import { WRAPPER_PATH, writeDaemonWrapper } from "./daemon.ts";
 
 const SERVICE_NAME = "parachute-vault";
@@ -29,7 +29,7 @@ After=network.target
 
 [Service]
 Type=simple
-WorkingDirectory=${CONFIG_DIR}
+WorkingDirectory=${VAULT_HOME}
 ExecStart=/bin/bash ${WRAPPER_PATH}
 Restart=on-failure
 RestartSec=5