@openparachute/vault 0.3.0-rc.1 → 0.3.0

package/src/cli.ts

@@ -79,6 +79,7 @@ import {
 import { confirm, ask, askPassword, choose } from "./prompt.ts";
 import { generateToken, createToken, listTokens, revokeToken, migrateVaultKeys } from "./token-store.ts";
 import type { TokenPermission } from "./token-store.ts";
+import { resolveCreateTokenFlags, VAULT_SCOPES } from "./scopes.ts";
 import { getVaultStore } from "./vault-store.ts";
 import { upsertService, ServicesManifestError } from "./services-manifest.ts";
 import {
@@ -135,7 +136,7 @@ if (!SKIP_MIGRATION.has(command)) {
 
 switch (command) {
   case "init":
-    await cmdInit();
+    await cmdInit(cmdArgs);
     break;
   case "create":
     cmdCreate(cmdArgs);
@@ -216,9 +217,16 @@ switch (command) {
 // Command implementations
 // ---------------------------------------------------------------------------
 
-async function cmdInit() {
+async function cmdInit(args: string[] = []) {
   ensureConfigDirSync();
 
+  // Flags: --mcp installs MCP in ~/.claude.json without prompting;
+  // --no-mcp skips it without prompting. If both passed, --no-mcp wins
+  // (safer default). Neither → prompt in a TTY, default-yes in a
+  // non-TTY for back-compat with existing piped install scripts.
+  const flagMcpOn = args.includes("--mcp");
+  const flagMcpOff = args.includes("--no-mcp");
+
   const isMac = process.platform === "darwin";
   const isLinux = process.platform === "linux";
   const isFirstRun = !existsSync(ENV_PATH);
@@ -341,9 +349,28 @@ async function cmdInit() {
   }
   console.log(`  Listening on http://0.0.0.0:${globalConfig.port || DEFAULT_PORT}`);
 
-  // 7. Install MCP for Claude Code (with token for auth)
-  installMcpConfig(apiKey);
-  console.log(`  MCP server added to ~/.claude.json`);
+  // 7. Install MCP for Claude Code (with token for auth) — user confirms
+  // unless --mcp / --no-mcp explicitly passed. Writing to ~/.claude.json
+  // is a side effect some users don't want; default-yes in a TTY since
+  // most users installing vault want Claude Code to see it, but ask.
+  let addMcp: boolean;
+  if (flagMcpOff) {
+    addMcp = false;
+  } else if (flagMcpOn) {
+    addMcp = true;
+  } else if (process.stdin.isTTY) {
+    addMcp = await confirm("Add Vault MCP to Claude Code (~/.claude.json)?", true);
+  } else {
+    addMcp = true; // non-interactive: preserve the installable-via-pipe default
+  }
+
+  if (addMcp) {
+    installMcpConfig(apiKey);
+    console.log(`  MCP server added to ~/.claude.json`);
+  } else {
+    console.log("  Skipped adding MCP to ~/.claude.json.");
+    console.log("  Run `parachute-vault mcp-install` later if you want it.");
+  }
 
   // 8. Summary
   console.log("\n---");
@@ -818,7 +845,8 @@ function cmdTokens(args: string[]) {
     return;
   }
 
-  // parachute-vault tokens create --vault <name> [--permission full|read]
+  // parachute-vault tokens create --vault <name>
+  //   [--scope vault:read,vault:write | --read | --permission full|read]
   //   [--expires <duration>] [--label <label>]
   if (subcmd === "create") {
     const vaultFlag = args.indexOf("--vault");
@@ -830,15 +858,17 @@ function cmdTokens(args: string[]) {
       process.exit(1);
     }
 
-    // --read shorthand or --permission full|read
-    const isReadShorthand = args.includes("--read");
-    const permFlag = args.indexOf("--permission");
-    const rawPerm = isReadShorthand ? "read" : (permFlag !== -1 ? args[permFlag + 1] : "full");
-    const permission: TokenPermission = rawPerm === "read" ? "read" : "full";
-    if (!["full", "read", "admin", "write"].includes(rawPerm)) {
-      console.error(`Invalid permission: ${rawPerm}. Must be full or read.`);
+    // Combining --scope / --read / --permission is always an error: a
+    // user minting a token expects exactly one narrowing signal, and
+    // silently picking one would mint the opposite of what the other
+    // reading intended. See resolveCreateTokenFlags.
+    const resolved = resolveCreateTokenFlags(args);
+    if (resolved.error) {
+      console.error(resolved.error);
       process.exit(1);
     }
+    const scopes = resolved.scopes;
+    const permission: TokenPermission = resolved.permission;
 
     const expiresFlag = args.indexOf("--expires");
     let expiresAt: string | null = null;
@@ -859,12 +889,15 @@ function cmdTokens(args: string[]) {
     createToken(store.db, fullToken, {
       label,
       permission,
+      scopes,
       expires_at: expiresAt,
     });
 
+    const displayScopes = scopes ?? [...VAULT_SCOPES];
     console.log(`Created token for vault "${vaultName}":`);
     console.log(`  Token:      ${fullToken}`);
     console.log(`  Permission: ${permission}`);
+    console.log(`  Scopes:     ${displayScopes.join(" ")}`);
     if (expiresAt) console.log(`  Expires:    ${expiresAt}`);
     console.log(`  Label:      ${label}`);
     console.log();
@@ -2031,7 +2064,7 @@ data, and debugging.
 ── Standard use ───────────────────────────────────────────────────────
 
 Setup:
-  parachute-vault init                     Set up everything (one command, idempotent)
+  parachute-vault init [--mcp | --no-mcp]  Set up everything (one command, idempotent)
   parachute-vault doctor                   Diagnose install/config issues
   parachute-vault uninstall [--wipe] [--yes]
                                            Remove daemon + MCP entry; --wipe also removes vaults, .env,
@@ -2050,7 +2083,11 @@ Tokens:
   parachute-vault tokens                          List all tokens
   parachute-vault tokens create                   Create a full-access token in the default vault
   parachute-vault tokens create --vault <name>    Create a token in a specific vault
-  parachute-vault tokens create --read            Read-only token
+  parachute-vault tokens create --read            Read-only token (shorthand for --scope vault:read)
+  parachute-vault tokens create --scope vault:write
+                                                  Narrow the token's scopes. Accepts a comma-separated
+                                                  list or repeated --scope flags. Valid scopes:
+                                                  vault:read, vault:write, vault:admin.
   parachute-vault tokens create --label x         Set a label
   parachute-vault tokens create --expires 30d     Expiring token
   parachute-vault tokens revoke <token-id>        Revoke a token (default vault)

package/src/scopes.test.ts

@@ -10,6 +10,8 @@ import {
   SCOPE_WRITE,
   SCOPE_ADMIN,
   parseScopes,
+  parseScopeFlags,
+  resolveCreateTokenFlags,
   hasScope,
   scopeForMethod,
   legacyPermissionToScopes,
@@ -123,6 +125,162 @@ describe("legacyPermissionToScopes", () => {
   });
 });
 
+describe("parseScopeFlags", () => {
+  test("returns null scopes when --scope is absent", () => {
+    expect(parseScopeFlags([])).toEqual({ scopes: null, error: null });
+    expect(parseScopeFlags(["--vault", "default", "--label", "x"]))
+      .toEqual({ scopes: null, error: null });
+  });
+
+  test("single --scope with one value", () => {
+    expect(parseScopeFlags(["--scope", "vault:read"]))
+      .toEqual({ scopes: [SCOPE_READ], error: null });
+  });
+
+  test("single --scope with comma-separated values", () => {
+    expect(parseScopeFlags(["--scope", "vault:read,vault:write"]))
+      .toEqual({ scopes: [SCOPE_READ, SCOPE_WRITE], error: null });
+  });
+
+  test("repeated --scope flags", () => {
+    expect(parseScopeFlags(["--scope", "vault:read", "--scope", "vault:write"]))
+      .toEqual({ scopes: [SCOPE_READ, SCOPE_WRITE], error: null });
+  });
+
+  test("dedupes while preserving first-occurrence order", () => {
+    expect(parseScopeFlags(["--scope", "vault:write,vault:read,vault:write"]))
+      .toEqual({ scopes: [SCOPE_WRITE, SCOPE_READ], error: null });
+  });
+
+  test("trims whitespace around each scope", () => {
+    expect(parseScopeFlags(["--scope", "  vault:read ,  vault:write  "]))
+      .toEqual({ scopes: [SCOPE_READ, SCOPE_WRITE], error: null });
+  });
+
+  test("rejects unknown scopes with a helpful error", () => {
+    const result = parseScopeFlags(["--scope", "vault:frob"]);
+    expect(result.scopes).toBeNull();
+    expect(result.error).toContain("Unknown scope");
+    expect(result.error).toContain("vault:frob");
+    expect(result.error).toContain("vault:read, vault:write, vault:admin");
+  });
+
+  test("rejects a mixed list with one invalid scope", () => {
+    const result = parseScopeFlags(["--scope", "vault:read,admin"]);
+    expect(result.scopes).toBeNull();
+    expect(result.error).toContain("admin");
+  });
+
+  test("rejects --scope with no value (end of argv)", () => {
+    const result = parseScopeFlags(["--scope"]);
+    expect(result.scopes).toBeNull();
+    expect(result.error).toContain("--scope requires a value");
+  });
+
+  test("rejects --scope followed by another flag", () => {
+    const result = parseScopeFlags(["--scope", "--label", "x"]);
+    expect(result.scopes).toBeNull();
+    expect(result.error).toContain("--scope requires a value");
+  });
+
+  test("rejects --scope with an empty value", () => {
+    const result = parseScopeFlags(["--scope", ""]);
+    expect(result.scopes).toBeNull();
+    expect(result.error).toContain("empty");
+  });
+
+  test("rejects --scope with only commas", () => {
+    const result = parseScopeFlags(["--scope", ",,"]);
+    expect(result.scopes).toBeNull();
+    expect(result.error).toContain("empty");
+  });
+});
+
+describe("resolveCreateTokenFlags", () => {
+  test("no flags → full scope, full permission (historical default)", () => {
+    expect(resolveCreateTokenFlags([]))
+      .toEqual({ scopes: undefined, permission: "full", error: null });
+  });
+
+  test("--read alone → [vault:read], read permission", () => {
+    expect(resolveCreateTokenFlags(["--read"]))
+      .toEqual({ scopes: [SCOPE_READ], permission: "read", error: null });
+  });
+
+  test("--scope vault:read alone → read permission", () => {
+    expect(resolveCreateTokenFlags(["--scope", "vault:read"]))
+      .toEqual({ scopes: [SCOPE_READ], permission: "read", error: null });
+  });
+
+  test("--scope vault:write,vault:read → full permission (any write surface → full)", () => {
+    expect(resolveCreateTokenFlags(["--scope", "vault:write,vault:read"]))
+      .toEqual({ scopes: [SCOPE_WRITE, SCOPE_READ], permission: "full", error: null });
+  });
+
+  test("--scope vault:admin alone → full permission", () => {
+    expect(resolveCreateTokenFlags(["--scope", "vault:admin"]))
+      .toEqual({ scopes: [SCOPE_ADMIN], permission: "full", error: null });
+  });
+
+  test("--permission read → no scopes (token-store default), read permission", () => {
+    expect(resolveCreateTokenFlags(["--permission", "read"]))
+      .toEqual({ scopes: undefined, permission: "read", error: null });
+  });
+
+  test("--permission full → no scopes, full permission", () => {
+    expect(resolveCreateTokenFlags(["--permission", "full"]))
+      .toEqual({ scopes: undefined, permission: "full", error: null });
+  });
+
+  test("--scope + --read errors and mentions both flags", () => {
+    const result = resolveCreateTokenFlags(["--scope", "vault:write", "--read"]);
+    expect(result.scopes).toBeUndefined();
+    expect(result.error).toContain("--scope");
+    expect(result.error).toContain("--read");
+    expect(result.error).toContain("cannot be combined");
+  });
+
+  test("--scope + --permission errors", () => {
+    const result = resolveCreateTokenFlags(["--scope", "vault:read", "--permission", "full"]);
+    expect(result.scopes).toBeUndefined();
+    expect(result.error).toContain("--scope");
+    expect(result.error).toContain("--permission");
+    expect(result.error).toContain("cannot be combined");
+  });
+
+  test("--read + --permission errors", () => {
+    const result = resolveCreateTokenFlags(["--read", "--permission", "full"]);
+    expect(result.scopes).toBeUndefined();
+    expect(result.error).toContain("--read");
+    expect(result.error).toContain("--permission");
+    expect(result.error).toContain("cannot be combined");
+  });
+
+  test("invalid --permission value errors with prefer-scope hint", () => {
+    const result = resolveCreateTokenFlags(["--permission", "admin"]);
+    expect(result.scopes).toBeUndefined();
+    expect(result.error).toContain("admin");
+    expect(result.error).toContain("full");
+    expect(result.error).toContain("read");
+    expect(result.error).toContain("--scope");
+  });
+
+  test("--permission with no value errors", () => {
+    expect(resolveCreateTokenFlags(["--permission"]).error).toContain("requires a value");
+    expect(resolveCreateTokenFlags(["--permission", "--label", "x"]).error).toContain("requires a value");
+  });
+
+  test("surfaces parseScopeFlags errors unchanged", () => {
+    const result = resolveCreateTokenFlags(["--scope", "vault:frob"]);
+    expect(result.error).toContain("Unknown scope");
+  });
+
+  test("ignores unrelated flags", () => {
+    const result = resolveCreateTokenFlags(["--vault", "journal", "--label", "r", "--read"]);
+    expect(result).toEqual({ scopes: [SCOPE_READ], permission: "read", error: null });
+  });
+});
+
 describe("serializeScopes — round-trips with parseScopes", () => {
   test("joins with spaces", () => {
     expect(serializeScopes([SCOPE_READ, SCOPE_WRITE])).toBe("vault:read vault:write");

package/src/scopes.ts

@@ -103,3 +103,151 @@ export function legacyPermissionToScopes(permission: string): string[] {
 export function serializeScopes(scopes: string[]): string {
   return scopes.join(" ");
 }
+
+/**
+ * Parse `--scope` flag values from an argv list into a validated scope list.
+ *
+ * Accepts repeatable `--scope vault:read --scope vault:write` and
+ * comma-separated `--scope vault:read,vault:write` (and a mix of the two).
+ * Scopes are validated against `VAULT_SCOPES` — we refuse to mint a token
+ * with a scope the server has no way to enforce.
+ *
+ * Return shape: `{scopes}` is `null` when no `--scope` appears anywhere, so
+ * the caller can distinguish "flag not set" from "flag set to empty." On
+ * validation failure, `error` is a human-readable message suitable for
+ * `console.error` + `process.exit(1)`.
+ */
+export function parseScopeFlags(
+  args: string[],
+): { scopes: string[] | null; error: string | null } {
+  const validList = VAULT_SCOPES.join(", ");
+  const raw: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] !== "--scope") continue;
+    const val = args[i + 1];
+    if (val === undefined || val.startsWith("--")) {
+      return { scopes: null, error: `--scope requires a value. Valid scopes: ${validList}` };
+    }
+    raw.push(val);
+    i++;
+  }
+  if (raw.length === 0) return { scopes: null, error: null };
+
+  const expanded = raw
+    .flatMap((v) => v.split(","))
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+  if (expanded.length === 0) {
+    return { scopes: null, error: `--scope value was empty. Valid scopes: ${validList}` };
+  }
+
+  const validSet = new Set<string>(VAULT_SCOPES);
+  const invalid = expanded.filter((s) => !validSet.has(s));
+  if (invalid.length > 0) {
+    return {
+      scopes: null,
+      error: `Unknown scope(s): ${invalid.join(", ")}. Valid scopes: ${validList}`,
+    };
+  }
+
+  const seen = new Set<string>();
+  const deduped: string[] = [];
+  for (const s of expanded) {
+    if (!seen.has(s)) {
+      seen.add(s);
+      deduped.push(s);
+    }
+  }
+  return { scopes: deduped, error: null };
+}
+
+/**
+ * Resolve `parachute vault tokens create` argv into a concrete scope set +
+ * legacy `permission` column value, or an actionable error.
+ *
+ * Precedence is **exclusive**: `--scope`, `--read`, and `--permission` all
+ * narrow the token, but combining them is always an error — a user who
+ * writes `--scope vault:write --read` almost certainly expects one of the
+ * two to win, and silently picking would mint the opposite of what at
+ * least one reading intended. Fail loud for anything token-minting.
+ *
+ * With no narrowing flag, falls back to a full-scope token for back-compat.
+ */
+export function resolveCreateTokenFlags(args: string[]): {
+  scopes: string[] | undefined;
+  permission: "full" | "read";
+  error: string | null;
+} {
+  const scopeResult = parseScopeFlags(args);
+  if (scopeResult.error) {
+    return { scopes: undefined, permission: "full", error: scopeResult.error };
+  }
+  const hasScopeFlag = scopeResult.scopes !== null;
+  const hasReadFlag = args.includes("--read");
+  const permIdx = args.indexOf("--permission");
+  const hasPermFlag = permIdx !== -1;
+
+  if (hasScopeFlag && hasReadFlag) {
+    return {
+      scopes: undefined,
+      permission: "full",
+      error:
+        "--scope and --read cannot be combined. Pick one:\n" +
+        "  --read                     # shorthand for --scope vault:read\n" +
+        "  --scope vault:read         # equivalent, explicit\n" +
+        "  --scope vault:write        # write scope",
+    };
+  }
+  if (hasScopeFlag && hasPermFlag) {
+    return {
+      scopes: undefined,
+      permission: "full",
+      error:
+        "--scope and --permission cannot be combined. --scope is the canonical way to narrow a token; --permission is legacy.",
+    };
+  }
+  if (hasReadFlag && hasPermFlag) {
+    return {
+      scopes: undefined,
+      permission: "full",
+      error: "--read and --permission cannot be combined. --read is a shorthand for --permission read.",
+    };
+  }
+
+  if (hasPermFlag) {
+    const rawPerm = args[permIdx + 1];
+    if (!rawPerm || rawPerm.startsWith("--")) {
+      return {
+        scopes: undefined,
+        permission: "full",
+        error: `--permission requires a value ("full" or "read"). Prefer --scope for new scripts.`,
+      };
+    }
+    if (!["full", "read"].includes(rawPerm)) {
+      return {
+        scopes: undefined,
+        permission: "full",
+        error: `Invalid --permission: ${rawPerm}. Must be "full" or "read". Prefer --scope for new scripts.`,
+      };
+    }
+  }
+
+  if (scopeResult.scopes) {
+    const scopes = scopeResult.scopes;
+    const permission: "full" | "read" =
+      scopes.includes(SCOPE_WRITE) || scopes.includes(SCOPE_ADMIN) ? "full" : "read";
+    return { scopes, permission, error: null };
+  }
+  if (hasReadFlag) {
+    return { scopes: [SCOPE_READ], permission: "read", error: null };
+  }
+  if (hasPermFlag) {
+    const rawPerm = args[permIdx + 1];
+    return {
+      scopes: undefined,
+      permission: rawPerm === "read" ? "read" : "full",
+      error: null,
+    };
+  }
+  return { scopes: undefined, permission: "full", error: null };
+}

package/src/server.ts

@@ -17,13 +17,14 @@
 
 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, type TranscriptionWorker } from "./transcription-worker.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.
@@ -59,6 +60,12 @@ 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();
 
 /**
@@ -78,14 +85,18 @@ if (process.env.SCRIBE_URL) {
     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)");
 }
 
-ensureConfigDirSync();
-loadEnvFile();
-
 // Auto-init: create a default vault if none exist (first run in Docker)
 if (listVaults().length === 0) {
   const globalConfig = readGlobalConfig();
@@ -159,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);
@@ -208,7 +220,7 @@ 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> {