@openparachute/vault 0.5.1-rc.2 → 0.5.2-rc.1

package/src/cli.ts

@@ -102,6 +102,13 @@ import { listTokens, revokeToken, migrateVaultKeys } from "./token-store.ts";
 import { VAULT_SCOPES } from "./scopes.ts";
 import { validateVaultName, decideInitVaultName } from "./vault-name.ts";
 import { getVaultStore } from "./vault-store.ts";
+import {
+  defaultMirrorConfig,
+  resolveMirrorPath,
+  writeMirrorConfigForVault,
+  type MirrorConfig,
+} from "./mirror-config.ts";
+import { bootstrapInternalMirror } from "./mirror-manager.ts";
 import { selfRegister } from "./self-register.ts";
 import {
   hasOwnerPassword,
@@ -814,11 +821,15 @@ async function cmdCreate(args: string[]) {
   // POST /vaults shells out to this CLI and parses stdout). Errors still go
   // to stderr as plain text and exit nonzero — callers branch on exit code.
   const jsonMode = args.includes("--json");
+  // `--no-mirror` opts THIS create out of the default internal live mirror
+  // even when the server-wide `default_mirror` knob is `internal`. Parity for
+  // operators who want one bare vault without flipping the global default.
+  const noMirror = args.includes("--no-mirror");
   // Greedy strip of any `--*` token to recover the positional vault name.
-  // Today only `--json` is recognized; any other `--foo` is silently dropped.
-  // If a future flag (e.g. `--force`, `--dry-run`) is added, the parsing
-  // here needs to whitelist it — otherwise an invalid flag becomes a silent
-  // no-op rather than a usage error.
+  // `--json` and `--no-mirror` are recognized; any other `--foo` is silently
+  // dropped. If a future flag (e.g. `--force`, `--dry-run`) is added, the
+  // parsing here needs to whitelist it — otherwise an invalid flag becomes a
+  // silent no-op rather than a usage error.
   const positional = args.filter((a) => !a.startsWith("--"));
   const name = positional[0];
   if (!name) {
@@ -826,8 +837,14 @@ async function cmdCreate(args: string[]) {
     process.exit(1);
   }
 
-  if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
-    console.error("Vault name must contain only letters, numbers, hyphens, and underscores.");
+  // Lowercase-only (security review — multi-user hardening). An uppercase
+  // vault name flips the audience case (`vault.<Name>` vs `vault.<name>`)
+  // and drifts from hub-side / init-path lowercasing, breaking JWT
+  // audience matching. `init` already enforces lowercase via
+  // `validateVaultName`; mirror that rule here so uppercase can't enter
+  // through `create` either.
+  if (!/^[a-z0-9_-]+$/.test(name)) {
+    console.error("Vault name must be lowercase alphanumeric with hyphens or underscores (no uppercase).");
     process.exit(1);
   }
   if (name === "list") {
@@ -846,7 +863,7 @@ async function cmdCreate(args: string[]) {
 
   ensureConfigDirSync();
   const wasFirst = listVaults().length === 0;
-  const credential = await createVault(name);
+  const credential = await createVault(name, noMirror ? { enableMirror: false } : {});
 
   // If this is the only vault now, make it the default so unscoped routes
   // (/mcp, /api/*, /oauth/*) target it. Avoids the "single vault named
@@ -2760,34 +2777,17 @@ async function cmdImport(args: string[]) {
     return;
   }
 
-  // Import into vault — use createNoteRaw to skip per-note wikilink sync,
-  // then do a single pass after all notes are imported (much faster for large vaults).
+  // Import into vault — use the shared `importObsidianNotes` adapter
+  // (obsidian.ts). It uses createNoteRaw to skip per-note wikilink sync,
+  // id-aware upsert with a path-conflict guard, intra-batch collision
+  // dedup, per-note error isolation, and timestamp preservation. The
+  // single wikilink pass runs below, after all notes exist.
+  const { importObsidianNotes } = await import("../core/src/obsidian.ts");
   const store = getVaultStore(vaultName);
-  let imported = 0;
-  let skipped = 0;
-
-  for (const note of notes) {
-    // Skip if a note with this path already exists
-    const existing = await store.getNoteByPath(note.path);
-    if (existing) {
-      skipped++;
-      continue;
-    }
-
-    // Build metadata from frontmatter (excluding tags, already extracted)
-    const metadata = Object.keys(note.frontmatter).length > 0 ? note.frontmatter : undefined;
-
-    await store.createNoteRaw(note.content, {
-      path: note.path,
-      tags: note.tags.length > 0 ? note.tags : undefined,
-      metadata: metadata as Record<string, unknown>,
-    });
-    imported++;
-  }
+  const { imported, skipped } = await importObsidianNotes(store, notes);
 
-  // Single-pass wikilink sync after all notes exist
   console.log(`\nImported ${imported} notes into vault "${vaultName}"`);
-  if (skipped > 0) console.log(`Skipped ${skipped} notes (path already exists)`);
+  if (skipped > 0) console.log(`Skipped ${skipped} notes (path already exists or conflict)`);
 
   if (imported > 0) {
     const linkResult = await store.syncAllWikilinks();
@@ -3350,7 +3350,59 @@ async function mintBootstrapCredential(name: string): Promise<VaultCredential> {
  * is reachable — vault#282 Stage 2). The DB is created lazily via
  * `getVaultStore` so migrations + schema run; we no longer write any pvt_* row.
  */
-async function createVault(name: string): Promise<VaultCredential> {
+interface CreateVaultOptions {
+  /**
+   * Override the server-wide `default_mirror` knob for this one create.
+   * `--no-mirror` on `parachute-vault create` sets this to `false` so the
+   * vault is created with no mirror config even when the knob is `internal`.
+   * Unset → fall back to the `default_mirror` global config knob (default
+   * `internal`).
+   */
+  enableMirror?: boolean;
+  /**
+   * Test seam threaded straight into `bootstrapInternalMirror` (default
+   * `Bun.which`). Inject a fn returning `null` to exercise the
+   * git-not-installed best-effort path without uninstalling git from the
+   * test host.
+   */
+  which?: (cmd: string) => string | null;
+}
+
+/**
+ * The History / "Live Mirror" preset, written at create time when the
+ * `default_mirror` knob resolves to `internal`. Matches the History preset
+ * the admin SPA's VaultMirror page applies:
+ *   `{enabled:true, location:internal, sync_mode:events, auto_commit:true,
+ *    auto_push:false}`.
+ * Built on top of `defaultMirrorConfig()` so the non-preset fields
+ * (commit_template, safety_net_seconds) stay canonical.
+ */
+function historyPresetMirrorConfig(): MirrorConfig {
+  return {
+    ...defaultMirrorConfig(),
+    enabled: true,
+    location: "internal",
+    sync_mode: "events",
+    auto_commit: true,
+    auto_push: false,
+  };
+}
+
+/**
+ * Resolve whether a freshly created vault should get the internal mirror.
+ * Precedence: explicit per-create override (`--no-mirror`) → server-wide
+ * `default_mirror` knob (default `internal`).
+ */
+function shouldEnableCreateTimeMirror(opts: CreateVaultOptions): boolean {
+  if (opts.enableMirror !== undefined) return opts.enableMirror;
+  // Default to "internal" when the knob is unset — backup-on-by-default.
+  return (readGlobalConfig().default_mirror ?? "internal") === "internal";
+}
+
+async function createVault(
+  name: string,
+  opts: CreateVaultOptions = {},
+): Promise<VaultCredential> {
   const config: VaultConfig = {
     name,
     api_keys: [],
@@ -3361,6 +3413,47 @@ async function createVault(name: string): Promise<VaultCredential> {
   // Touch the store so the vault's SQLite DB + schema are created. No token
   // row is written — vault is a pure hub resource-server post-0.5.0.
   getVaultStore(name);
+
+  // Default new vaults to an internal live mirror (local git backup of the
+  // markdown projection). Backup-on-by-default; GitHub off-site backup is an
+  // opt-in upgrade layered on top later. Opt out via the `default_mirror: off`
+  // global knob (operators on git-less / disk-constrained / cloud boxes) or
+  // the `--no-mirror` flag (this one create only).
+  //
+  // BEST-EFFORT, NON-FATAL: write the mirror config first (so the operator's
+  // intent persists even if git is absent), then attempt the bootstrap. A
+  // git-less box leaves the config written but inactive + logs an actionable
+  // hint — it must NEVER fail the vault create. Create-time ONLY: existing
+  // vaults are never retroactively migrated.
+  if (shouldEnableCreateTimeMirror(opts)) {
+    const mirrorConfig = historyPresetMirrorConfig();
+    writeMirrorConfigForVault(name, mirrorConfig);
+    const mirrorPath = resolveMirrorPath(vaultDir(name), mirrorConfig);
+    if (mirrorPath) {
+      try {
+        const result = await bootstrapInternalMirror(mirrorPath, opts.which);
+        if (!result.ok) {
+          // git-not-installed (or refuse-to-clobber) — config stays written,
+          // mirror just isn't active yet. Surface an actionable line; the
+          // vault create succeeds regardless.
+          console.error(
+            `Note: local git backup configured but not yet active — ${result.error} ` +
+              `Install git to activate; the backup turns on automatically on the next vault restart.`,
+          );
+        }
+      } catch (err) {
+        // Defense-in-depth: bootstrapInternalMirror already converts the
+        // git-missing case into a non-throwing { ok:false } result, but a
+        // truly unexpected throw must still not fail the create.
+        console.error(
+          `Note: local git backup configured but bootstrap hit an unexpected error ` +
+            `(${(err as Error).message ?? err}). The vault was still created; ` +
+            `the backup will retry on the next vault restart.`,
+        );
+      }
+    }
+  }
+
   return mintBootstrapCredential(name);
 }
 
@@ -3465,7 +3558,13 @@ Setup:
   parachute --version                      Print the installed version (alias: -v, version)
 
 Vaults:
-  parachute-vault create <name> [--json]   Create a new vault (--json: emit { name, token, paths, set_as_default })
+  parachute-vault create <name> [--json] [--no-mirror]
+                                           Create a new vault (--json: emit { name, token, paths, set_as_default }).
+                                           New vaults default to an internal live mirror — a local git backup of
+                                           the markdown projection (backup on by default; GitHub off-site is an
+                                           opt-in upgrade). --no-mirror creates a bare vault with no mirror config.
+                                           Operators can flip the server-wide default with 'default_mirror: off' in
+                                           config.yaml (recommended for cloud / disk-constrained boxes).
   parachute-vault list                     List all vaults
   parachute-vault remove <name> [--yes]    Remove a vault
   parachute-vault mcp-install [--mint|--token <t>]

package/src/config.test.ts

@@ -250,6 +250,22 @@ describe("config", () => {
     writeGlobalConfig({ port: 1940, autostart: false });
     expect(readGlobalConfig().autostart).toBe(false);
   });
+
+  test("round-trips default_mirror: internal|off", () => {
+    // Absent: createVault falls back to the in-code default ("internal" —
+    // backup-on-by-default). The knob is only persisted when explicitly set.
+    writeGlobalConfig({ port: 1940 });
+    expect(readGlobalConfig().default_mirror).toBeUndefined();
+
+    // Explicit internal — new vaults get the History-preset local git mirror.
+    writeGlobalConfig({ port: 1940, default_mirror: "internal" });
+    expect(readGlobalConfig().default_mirror).toBe("internal");
+
+    // Explicit off — the opt-out operators set on git-less / disk-constrained
+    // / cloud boxes so new vaults are created with no mirror config.
+    writeGlobalConfig({ port: 1940, default_mirror: "off" });
+    expect(readGlobalConfig().default_mirror).toBe("off");
+  });
 });
 
 // ---------------------------------------------------------------------------

package/src/config.ts

@@ -115,6 +115,17 @@ export function vaultConfigPath(name: string): string {
   return join(vaultDir(name), "vault.yaml");
 }
 
+/**
+ * Per-vault attachments directory: `<vaultDir>/assets`, or the `ASSETS_DIR`
+ * env override when set (single-assets-root deployments). Lives here next to
+ * the other path helpers — neutral ground that both `routes.ts` (upload/serve)
+ * and `usage.ts` (footprint dir-walk) import without a cycle. `routes.ts`
+ * re-exports it for the existing callers (mirror-deps, server, triggers, …).
+ */
+export function assetsDir(name: string): string {
+  return process.env.ASSETS_DIR ?? join(vaultDir(name), "assets");
+}
+
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
@@ -280,6 +291,29 @@ export interface GlobalConfig {
    * resolved path. See `./mirror-config.ts`.
    */
   mirror?: MirrorConfigType;
+  /**
+   * Server-wide DEFAULT for newly created vaults' backup posture. Decides
+   * whether `createVault` writes the History-preset internal mirror
+   * (local git backup of the markdown projection) at create time.
+   *
+   *   - `"internal"` (default) — new vaults get a local git mirror enabled
+   *     out of the box (backup-on-by-default). The History preset:
+   *     `{enabled:true, location:internal, sync_mode:events, auto_commit:true,
+   *     auto_push:false}`. GitHub off-site backup remains an opt-in upgrade.
+   *   - `"off"` — new vaults are created with no mirror config (the historical
+   *     pre-default behavior). The escape hatch for git-less / disk-constrained
+   *     boxes and cloud deploys, where doubling disk per vault is unwanted.
+   *     Cloud / container deploys SHOULD set this to `off`.
+   *
+   * Create-time ONLY — this knob does NOT retroactively enable mirrors on
+   * already-created vaults (that would ~double disk across every existing
+   * vault). Existing-vault opt-in is a separate, deliberate follow-up.
+   *
+   * The container/cloud first-boot auto-create path in `server.ts` does NOT
+   * funnel through `createVault`, so it is unaffected by this knob and stays
+   * mirror-off regardless — matching the recommended cloud posture.
+   */
+  default_mirror?: "internal" | "off";
   /**
    * Auto-transcribe configuration for the vault↔scribe handoff (vault#353,
    * design 2026-05-21 Part 2). When `enabled: true` AND scribe is discoverable
@@ -1162,6 +1196,7 @@ export function readGlobalConfig(): GlobalConfig {
       const totpSecretMatch = yaml.match(/^totp_secret:\s*"([^"]+)"/m);
       const discoveryMatch = yaml.match(/^discovery:\s*(enabled|disabled)/m);
       const autostartMatch = yaml.match(/^autostart:\s*(true|false)/m);
+      const defaultMirrorMatch = yaml.match(/^default_mirror:\s*(internal|off)/m);
       // auto_transcribe block — currently single boolean `enabled` (vault#353).
       // Parsed as a nested 2-space-indent block so future fields can grow under
       // it without breaking the regex; only `enabled` is read for v0.6.
@@ -1190,6 +1225,9 @@ export function readGlobalConfig(): GlobalConfig {
       if (autostartMatch) {
         config.autostart = autostartMatch[1]! === "true";
       }
+      if (defaultMirrorMatch) {
+        config.default_mirror = defaultMirrorMatch[1]! as "internal" | "off";
+      }
       if (autoTranscribeEnabled !== undefined) {
         config.auto_transcribe = { enabled: autoTranscribeEnabled };
       }
@@ -1259,6 +1297,7 @@ export function writeGlobalConfig(config: GlobalConfig): void {
   if (config.default_vault) lines.push(`default_vault: ${config.default_vault}`);
   if (config.discovery) lines.push(`discovery: ${config.discovery}`);
   if (config.autostart !== undefined) lines.push(`autostart: ${config.autostart}`);
+  if (config.default_mirror) lines.push(`default_mirror: ${config.default_mirror}`);
   if (config.owner_password_hash) {
     lines.push(`owner_password_hash: "${config.owner_password_hash}"`);
   }

package/src/mcp-tools.ts

@@ -7,6 +7,7 @@
 
 import { generateMcpTools } from "../core/src/mcp.ts";
 import type { McpToolDef } from "../core/src/mcp.ts";
+import type { Note } from "../core/src/types.ts";
 import {
   buildVaultProjection,
   projectionToMarkdown,
@@ -18,6 +19,7 @@ import { hasScopeForVault, parseScopes, validateMintedScopes } from "./scopes.ts
 import type { AuthResult } from "./auth.ts";
 import {
   expandTokenTagScope,
+  filterHydratedLinksByTagScope,
   noteWithinTagScope,
   tagsWithinScope,
 } from "./tag-scope.ts";
@@ -117,11 +119,30 @@ export function generateScopedMcpTools(
   callerBearer?: string | null,
 ): McpToolDef[] {
   const store = getVaultStore(vaultName);
-  const tools = generateMcpTools(store);
+
+  // Tag-scope confidentiality (security review): when the session is
+  // tag-scoped, build an expand-visibility predicate so `query-notes`'s
+  // `expand_links` inlining can't embed out-of-scope note content. The
+  // predicate reads from a SHARED holder that `applyTagScopeWrappers`
+  // populates with the resolved allowlist before core's execute runs the
+  // (synchronous) expansion — so by the time core calls `isVisible(note)`
+  // the allowlist is ready. Core stays scope-unaware: it only receives the
+  // plain closure. Unscoped sessions pass no predicate (unchanged path).
+  const scoped = Boolean(auth?.scoped_tags && auth.scoped_tags.length > 0);
+  const allowedHolder: { value: Set<string> | null } = { value: null };
+  const rawTags = scoped ? auth!.scoped_tags : null;
+  const expandVisibility = scoped
+    ? (note: Note) => noteWithinTagScope(note, allowedHolder.value, rawTags)
+    : undefined;
+
+  const tools = generateMcpTools(
+    store,
+    expandVisibility ? { expandVisibility } : undefined,
+  );
 
   overrideVaultInfo(tools, vaultName, auth);
   applyTagDependencyGuards(tools, vaultName);
-  applyTagScopeWrappers(tools, vaultName, auth);
+  applyTagScopeWrappers(tools, vaultName, auth, allowedHolder);
 
   // manage-token is server-only (needs token-store + auth context), so it
   // lives here rather than in core. Always appended to the surface; the
@@ -181,6 +202,7 @@ function applyTagScopeWrappers(
   tools: McpToolDef[],
   vaultName: string,
   auth: AuthResult | undefined,
+  allowedHolder?: { value: Set<string> | null },
 ): void {
   if (!auth || !auth.scoped_tags || auth.scoped_tags.length === 0) return;
   const store = getVaultStore(vaultName);
@@ -188,12 +210,40 @@ function applyTagScopeWrappers(
   let allowedPromise: Promise<Set<string> | null> | null = null;
   const getAllowed = (): Promise<Set<string> | null> => {
     if (!allowedPromise) {
-      allowedPromise = expandTokenTagScope(store, auth.scoped_tags);
+      allowedPromise = expandTokenTagScope(store, auth.scoped_tags).then((a) => {
+        // Publish the resolved allowlist into the shared holder so the
+        // expand-visibility predicate (wired in generateScopedMcpTools and
+        // baked into the query-notes expand context) sees the same set.
+        // The query-notes wrapper awaits getAllowed() before calling the
+        // core execute that runs expansion, so the holder is populated in
+        // time. Security review: closes the expand_links content leak.
+        if (allowedHolder) allowedHolder.value = a;
+        return a;
+      });
     }
     return allowedPromise;
   };
   const rawTags = auth.scoped_tags;
 
+  // Scrub a returned note's hydrated `links` array (present when the caller
+  // set `include_links`) so out-of-scope NEIGHBOR summaries (id/path/tags)
+  // don't leak — symmetric with the REST `include_links` fix. Mutates in
+  // place and returns the note for chaining. No-op when `links` is absent.
+  //
+  // Ordering invariant: reading `allowedHolder.value` here is safe ONLY
+  // because every wrapper that calls scrubNoteLinks first does
+  // `await getAllowed()` (which populates the holder) before `orig(params)`
+  // and before this scrub runs. So by the time we read `holder.value` it is
+  // the resolved allowlist, never the initial `null`. The `?? null` fallback
+  // is the unscoped/holder-absent path; `filterHydratedLinksByTagScope` then
+  // keys off `rawTags` (non-null here) for the actual scope check.
+  const scrubNoteLinks = (n: any): any => {
+    if (n && Array.isArray(n.links)) {
+      n.links = filterHydratedLinksByTagScope(n.links, allowedHolder?.value ?? null, rawTags);
+    }
+    return n;
+  };
+
   wrapReadTool(tools, "query-notes", async (orig, params) => {
     const allowed = await getAllowed();
     const result = await orig(params);
@@ -203,7 +253,9 @@ function applyTagScopeWrappers(
     //   - `{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));
+      return result
+        .filter((n: any) => noteWithinTagScope(n, allowed, rawTags))
+        .map(scrubNoteLinks);
     }
     if (
       result &&
@@ -214,13 +266,15 @@ function applyTagScopeWrappers(
     ) {
       const r = result as { notes: any[]; next_cursor: string | null };
       return {
-        notes: r.notes.filter((n: any) => noteWithinTagScope(n, allowed, rawTags)),
+        notes: r.notes
+          .filter((n: any) => noteWithinTagScope(n, allowed, rawTags))
+          .map(scrubNoteLinks),
         next_cursor: r.next_cursor,
       };
     }
     if (result && typeof result === "object" && "id" in result && "tags" in result) {
       return noteWithinTagScope(result as any, allowed, rawTags)
-        ? result
+        ? scrubNoteLinks(result)
         : { error: "Note not found", id: (result as any).id };
     }
     return result;