@openparachute/vault 0.2.4 → 0.3.0

package/src/server.ts

@@ -4,21 +4,27 @@
  *
  * 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).
  */
 
 import { readVaultConfig, readGlobalConfig, writeGlobalConfig, writeVaultConfig, listVaults, DEFAULT_PORT, ensureConfigDirSync, loadEnvFile, generateApiKey, hashKey } from "./config.ts";
 import { migrateVaultKeys } from "./token-store.ts";
-import { getVaultStore } from "./vault-store.ts";
+import { getVaultStore, getVaultNameForStore } from "./vault-store.ts";
 import { defaultHookRegistry } from "../core/src/hooks.ts";
 import { registerTriggers } from "./triggers.ts";
 import { route } from "./routing.ts";
+import { startTranscriptionWorker, registerTranscriptionHook, type TranscriptionWorker } from "./transcription-worker.ts";
+import { assetsDir } from "./routes.ts";
+import { resolveScribeAuthToken } from "./scribe-env.ts";
+import { resolveBindHostname } from "./bind.ts";
 
 // Register webhook triggers from global config. Replaces the old hardcoded
 // tts-hook and transcription-hook with config-driven webhooks.
@@ -30,13 +36,67 @@ 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.`,
+        );
+      }
+    }
+  }
 }
 
-registerConfiguredTriggers();
+function safeHost(url: string): string | null {
+  try { return new URL(url).host; } catch { return null; }
+}
 
+// Load .env before anything reads process.env — otherwise SCRIBE_URL and
+// friends configured in ~/.parachute/vault/.env are invisible to the
+// transcription-worker check and the trigger double-fire warning below.
 ensureConfigDirSync();
 loadEnvFile();
 
+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,
+  });
+  // Event-driven hot path — the `attachment:created` hook fires the worker
+  // in a microtask instead of waiting for the 30s sweep.
+  registerTranscriptionHook(
+    defaultHookRegistry,
+    transcriptionWorker,
+    (store) => getVaultNameForStore(store as never),
+  );
+  console.log(`[transcribe] worker started → ${process.env.SCRIBE_URL}`);
+} else {
+  console.log("[transcribe] worker disabled (set SCRIBE_URL to enable)");
+}
+
 // Auto-init: create a default vault if none exist (first run in Docker)
 if (listVaults().length === 0) {
   const globalConfig = readGlobalConfig();
@@ -110,10 +170,11 @@ for (const vaultName of listVaults()) {
 
 const globalConfig = readGlobalConfig();
 const port = parseInt(process.env.PORT ?? "") || globalConfig.port || DEFAULT_PORT;
+const hostname = resolveBindHostname();
 
 const server = Bun.serve({
   port,
-  hostname: "0.0.0.0",
+  hostname,
   idleTimeout: 120, // seconds — webhook triggers can take a while
   async fetch(req, server) {
     const url = new URL(req.url);
@@ -159,18 +220,21 @@ const server = Bun.serve({
   },
 });
 
-console.log(`Parachute Vault server listening on http://0.0.0.0:${server.port}`);
+console.log(`Parachute Vault server listening on http://${hostname}:${server.port}`);
 
 // Graceful shutdown — best-effort drain of in-flight note-mutation hooks.
 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

package/src/token-store.ts

@@ -16,6 +16,11 @@
 import { Database } from "bun:sqlite";
 import crypto from "node:crypto";
 import { hashKey } from "./config.ts";
+import { legacyPermissionToScopes, parseScopes, serializeScopes } from "./scopes.ts";
+
+function scopesForMigratedPermission(permission: string): string {
+  return serializeScopes(legacyPermissionToScopes(permission));
+}
 
 // ---------------------------------------------------------------------------
 // Types
@@ -47,6 +52,15 @@ export interface Token {
 
 export interface ResolvedToken {
   permission: TokenPermission;
+  /**
+   * Granted scopes, parsed from the token row's `scopes` column. Pre-v12
+   * tokens (where the column is NULL) fall back to the legacy permission
+   * → scopes mapping and `legacyDerived` is set true so callers can log
+   * a deprecation warning on first use.
+   */
+  scopes: string[];
+  /** True iff `scopes` was derived from the legacy `permission` column. */
+  legacyDerived: boolean;
 }
 
 // ---------------------------------------------------------------------------
@@ -65,6 +79,12 @@ export function createToken(
   opts: {
     label: string;
     permission?: TokenPermission;
+    /**
+     * Explicit OAuth-standard scopes to persist. If omitted, derived from
+     * `permission` (read → [vault:read], anything else → [vault:read,
+     * vault:write, vault:admin]). Written as a whitespace-separated string.
+     */
+    scopes?: string[];
     /** @deprecated Written to DB but not enforced at runtime. */
     scope_tag?: string | null;
     /** @deprecated Written to DB but not enforced at runtime. */
@@ -75,14 +95,17 @@ export function createToken(
   const tokenHash = hashKey(fullToken);
   const now = new Date().toISOString();
   const permission = opts.permission ?? "full";
+  const scopes = opts.scopes ?? legacyPermissionToScopes(permission);
+  const scopesStr = serializeScopes(scopes);
 
   db.prepare(`
-    INSERT INTO tokens (token_hash, label, permission, scope_tag, scope_path_prefix, expires_at, created_at)
-    VALUES (?, ?, ?, ?, ?, ?, ?)
+    INSERT INTO tokens (token_hash, label, permission, scopes, scope_tag, scope_path_prefix, expires_at, created_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
   `).run(
     tokenHash,
     opts.label,
     permission,
+    scopesStr,
     opts.scope_tag ?? null,
     opts.scope_path_prefix ?? null,
     opts.expires_at ?? null,
@@ -112,11 +135,12 @@ export function resolveToken(db: Database, providedToken: string): ResolvedToken
   const candidateHash = hashKey(providedToken);
 
   const row = db.prepare(`
-    SELECT token_hash, permission, expires_at
+    SELECT token_hash, permission, scopes, expires_at
     FROM tokens WHERE token_hash = ?
   `).get(candidateHash) as {
     token_hash: string;
     permission: string;
+    scopes: string | null;
     expires_at: string | null;
   } | null;
 
@@ -131,7 +155,13 @@ export function resolveToken(db: Database, providedToken: string): ResolvedToken
   db.prepare("UPDATE tokens SET last_used_at = ? WHERE token_hash = ?")
     .run(new Date().toISOString(), row.token_hash);
 
-  return { permission: normalizePermission(row.permission) };
+  const permission = normalizePermission(row.permission);
+  const parsed = parseScopes(row.scopes);
+  const hasVaultScope = parsed.some((s) => s.startsWith("vault:"));
+  const scopes = hasVaultScope ? parsed : legacyPermissionToScopes(permission);
+  const legacyDerived = !hasVaultScope;
+
+  return { permission, scopes, legacyDerived };
 }
 
 /**
@@ -203,13 +233,15 @@ export function migrateVaultKeys(
   for (const key of vaultKeys) {
     const exists = db.prepare("SELECT 1 FROM tokens WHERE token_hash = ?").get(key.key_hash);
     if (!exists) {
+      const permission = key.scope === "read" ? "read" : "full";
       db.prepare(`
-        INSERT INTO tokens (token_hash, label, permission, created_at, last_used_at)
-        VALUES (?, ?, ?, ?, ?)
+        INSERT INTO tokens (token_hash, label, permission, scopes, created_at, last_used_at)
+        VALUES (?, ?, ?, ?, ?, ?)
       `).run(
         key.key_hash,
         key.label,
-        key.scope === "read" ? "read" : "full",
+        permission,
+        scopesForMigratedPermission(permission),
         key.created_at,
         key.last_used_at ?? null,
       );
@@ -223,12 +255,13 @@ export function migrateVaultKeys(
       const exists = db.prepare("SELECT 1 FROM tokens WHERE token_hash = ?").get(key.key_hash);
       if (!exists) {
         db.prepare(`
-          INSERT INTO tokens (token_hash, label, permission, created_at, last_used_at)
-          VALUES (?, ?, ?, ?, ?)
+          INSERT INTO tokens (token_hash, label, permission, scopes, created_at, last_used_at)
+          VALUES (?, ?, ?, ?, ?, ?)
         `).run(
           key.key_hash,
           key.label,
           "full",
+          scopesForMigratedPermission("full"),
           key.created_at,
           key.last_used_at ?? null,
         );