@openparachute/vault 0.5.1 → 0.5.2-rc.2

package/src/cli.ts

@@ -56,6 +56,7 @@ import {
   buildMcpConfigJson,
   buildMcpEntryPlan,
   chooseHubOrigin,
+  chooseMcpUrl,
   detectInstallContext,
   mintHubJwt,
   readOperatorToken,
@@ -102,6 +103,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,
@@ -471,11 +479,16 @@ async function cmdInit(args: string[] = []) {
     addMcp = true; // non-interactive: preserve the installable-via-pipe default
   }
 
-  // 7b. Surface an API token for other clients? (Codex, Goose, OpenCode,
-  // Cursor, Zed, Cline, scripts, curl.) Same flag/TTY precedence as MCP.
-  // Note: a token is always minted when addMcp is true (it gets baked into
-  // the ~/.claude.json entry); this prompt controls whether that token is
-  // printed prominently at the end so the user can paste it elsewhere.
+  // 7b. Mint an API token for the header-auth / script use case? (Codex,
+  // Goose, OpenCode, Cursor, Zed, Cline, scripts, curl.)
+  //
+  // vault#442: default vault auth is per-user OAuth — the Claude Code MCP entry
+  // is written WITHOUT a baked bearer, so the first connection does browser
+  // sign-in. We mint a token ONLY when the operator explicitly opts in
+  // (`--token`, or "yes" at the prompt), and then it's scope-narrow
+  // (`vault:<name>:read`), NEVER admin. `--no-token` (and the non-interactive
+  // default) skips minting entirely — no auto-mint, no noisy mint-failure on a
+  // fresh vault.
   let addToken: boolean;
   if (flagTokenOff) {
     addToken = false;
@@ -483,25 +496,22 @@ async function cmdInit(args: string[] = []) {
     addToken = true;
   } else if (process.stdin.isTTY) {
     addToken = await confirm(
-      "Generate an API token for other MCP clients (Codex, Goose, OpenCode, Cursor, Zed, Cline), scripts, or curl?",
-      true,
+      "Also mint a header-auth API token for non-OAuth clients / scripts (Codex, Goose, curl)? (OAuth works without one)",
+      false,
     );
   } else {
-    addToken = true; // non-interactive: default-yes matches addMcp default
+    addToken = false; // non-interactive default: OAuth-first, no auto-mint
   }
 
-  // Mint a token if we need one (for the claude.json entry and/or for
-  // prominent display) and don't already have one from vault creation —
-  // e.g. a re-run of init against an existing vault. vault#282 Stage 2: vault
-  // no longer mints pvt_* tokens, so this is a hub JWT via the operator.token
-  // → hub mint-token path (`mintBootstrapCredential`). When no hub is
-  // reachable, `apiKey` stays undefined and we carry the guidance to the
-  // summary — the operator runs `mcp-install` once a hub is up, or sets
-  // VAULT_AUTH_TOKEN.
+  // Mint a scope-narrow token ONLY when explicitly opted in and we don't
+  // already have one from vault creation. vault#282 Stage 2: vault no longer
+  // mints pvt_* tokens — this is a hub JWT via the operator.token → hub
+  // mint-token path (`mintBootstrapCredential`), scoped `vault:<name>:read`.
+  // When no hub is reachable, `apiKey` stays undefined and we carry the
+  // guidance to the summary. The default (OAuth) path never reaches here.
   const defaultVault = globalConfig.default_vault || "default";
-  const needToken = addMcp || addToken;
-  if (needToken && !apiKey) {
-    const credential = await mintBootstrapCredential(defaultVault);
+  if (addToken && !apiKey) {
+    const credential = await mintBootstrapCredential(defaultVault, "read");
     apiKey = credential.token ?? undefined;
     credentialGuidance = credential.guidance;
     if (!apiKey) console.log(`  ${credential.guidance}`);
@@ -510,10 +520,9 @@ async function cmdInit(args: string[] = []) {
   if (addMcp) {
     // Goes through `buildMcpEntryPlan` for entryKey + url so this path shares
     // the writer-side invariant with `executeMcpInstall` — a future URL-shape
-    // change can't drift between init and mcp-install. The bearer is the hub
-    // JWT minted above (omitted when no hub was reachable — the entry is then
-    // written unauthenticated, and the operator re-runs `mcp-install` once a
-    // hub is up).
+    // change can't drift between init and mcp-install. By default NO bearer is
+    // baked (vault#442 — OAuth on first connect); a bearer is embedded only
+    // when the operator explicitly opted into a scope-narrow token above.
     const target = resolveInstallTarget("user");
     const { entryKey, url, source } = buildMcpEntryPlan({
       vaultName: defaultVault,
@@ -528,6 +537,9 @@ async function cmdInit(args: string[] = []) {
     });
     console.log(`MCP URL: ${url} (${source})`);
     console.log(`  MCP server added to ~/.claude.json`);
+    if (!apiKey) {
+      console.log(`  No token baked in — you'll sign in via OAuth on first connect.`);
+    }
   } else {
     console.log("  Skipped adding MCP to ~/.claude.json.");
     console.log("  Run `parachute-vault mcp-install` later if you want it.");
@@ -544,6 +556,7 @@ async function cmdInit(args: string[] = []) {
     bindHost,
     port,
     mcpUrl,
+    vaultName: defaultVault,
     noTokenGuidance: credentialGuidance,
   });
   for (const line of lines) console.log(line);
@@ -814,20 +827,71 @@ 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");
-  // 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.
-  const positional = args.filter((a) => !a.startsWith("--"));
+  // `--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");
+
+  // --- Auth opt-in (vault#442). Default = per-user OAuth, NO token minted. ---
+  // `--mint` opts into a scope-narrow hub JWT for the header-auth / script
+  // use case; `--scope read|write` (default read) picks the verb. `:admin` is
+  // intentionally NOT accepted from the create flow. `--token <bearer>` is the
+  // paste path — use an existing bearer instead of minting. The two are
+  // mutually exclusive.
+  const wantMint = args.includes("--mint");
+  const createTokenArg = takeArgValue(args, "--token");
+  if (createTokenArg.missingValue) {
+    console.error("--token requires a value (the bearer token to embed).");
+    process.exit(1);
+  }
+  const pastedToken = createTokenArg.value;
+  if (wantMint && pastedToken !== undefined) {
+    console.error("--mint and --token are mutually exclusive.");
+    process.exit(1);
+  }
+  const createScopeArg = takeArgValue(args, "--scope");
+  if (createScopeArg.missingValue) {
+    console.error("--scope requires a value: read or write.");
+    process.exit(1);
+  }
+  const rawCreateVerb = createScopeArg.value ?? "read";
+  if (rawCreateVerb !== "read" && rawCreateVerb !== "write") {
+    console.error(
+      `--scope must be "read" or "write" for create (admin is minted out-of-band via \`mcp-install --scope vault:admin\`). Got: ${rawCreateVerb}.`,
+    );
+    process.exit(1);
+  }
+  const mintVerb: "read" | "write" | undefined = wantMint ? rawCreateVerb : undefined;
+
+  // Greedy strip of any `--*` token (and any `--flag value` pairs we consumed
+  // above) to recover the positional vault name. `--json`, `--no-mirror`,
+  // `--mint`, `--token <v>`, `--scope <v>` are recognized; any other `--foo` is
+  // silently dropped, and the value following a recognized value-flag is
+  // skipped so it can't be mistaken for the vault name.
+  const VALUE_FLAGS = new Set(["--token", "--scope"]);
+  const positional: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!;
+    if (a.startsWith("--")) {
+      if (VALUE_FLAGS.has(a)) i++; // skip the flag's value
+      continue;
+    }
+    positional.push(a);
+  }
   const name = positional[0];
   if (!name) {
     console.error("Usage: parachute-vault create <name> [--json]");
     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 +910,18 @@ async function cmdCreate(args: string[]) {
 
   ensureConfigDirSync();
   const wasFirst = listVaults().length === 0;
-  const credential = await createVault(name);
+  const credential = await createVault(name, {
+    ...(noMirror ? { enableMirror: false } : {}),
+    ...(mintVerb ? { mintVerb } : {}),
+  });
+
+  // `--token <bearer>` paste path: the operator supplied their own bearer
+  // instead of minting one. Surface it as the credential token so the
+  // downstream JSON / human / summary copy treats it the same as a minted one.
+  const effectiveToken = pastedToken ?? credential.token;
+  const effectiveGuidance = pastedToken
+    ? "Using the bearer you supplied via --token."
+    : credential.guidance;
 
   // If this is the only vault now, make it the default so unscoped routes
   // (/mcp, /api/*, /oauth/*) target it. Avoids the "single vault named
@@ -880,17 +955,19 @@ async function cmdCreate(args: string[]) {
     log: () => {}, // CLI create has its own status lines.
   });
 
+  const endpoint = chooseMcpUrl(name, globalConfig.port || DEFAULT_PORT).url;
+
   if (jsonMode) {
     // Contract (hub's admin-vaults.ts requires `typeof token === "string"`):
-    // emit the minted hub JWT when present. When no hub was reachable
-    // (standalone create — no operator.token / no hub origin), `token` is the
-    // empty string and `token_guidance` carries the operator's next step. Hub
-    // only shells out to `create --json` while IT is the orchestrator (a hub is
-    // running, operator.token present), so that path always mints a real JWT.
+    // emit a token string when one was minted/pasted. vault#442 default is
+    // per-user OAuth — no token is minted — so `token` is the empty string and
+    // `token_guidance` carries the OAuth-first connect path. (Hub's admin SPA
+    // already handles the empty-token case + has its own session-cookie admin
+    // mint path, so it doesn't depend on create minting a token.)
     const payload = {
       name,
-      token: credential.token ?? "",
-      token_guidance: credential.guidance,
+      token: effectiveToken ?? "",
+      token_guidance: effectiveGuidance,
       paths: {
         vault_dir: vaultDir(name),
         vault_db: vaultDbPath(name),
@@ -904,18 +981,20 @@ async function cmdCreate(args: string[]) {
 
   console.log(`Vault "${name}" created.`);
   console.log(`  Path: ${vaultDir(name)}`);
-  if (credential.token) {
-    console.log(`  API token: ${credential.token}`);
-    console.log(`  ${credential.guidance}`);
+  if (effectiveToken) {
+    console.log(`  API token: ${effectiveToken}`);
+    console.log(`  ${effectiveGuidance}`);
     console.log(`  Save this — it will not be shown again.`);
   } else {
-    console.log(`  ${credential.guidance}`);
+    console.log(`  ${effectiveGuidance}`);
   }
   if (defaultNote) {
     console.log(`  ${defaultNote}`);
   }
   console.log();
-  console.log(`To add MCP to Claude: parachute-vault mcp-install ${name}`);
+  console.log(`Connect your AI: claude mcp add --transport http parachute-${name} ${endpoint}`);
+  console.log(`  (no token needed — you'll sign in on first use)`);
+  console.log(`Need a header-auth token for a script? parachute auth mint-token --scope vault:${name}:read`);
 }
 
 function cmdList() {
@@ -3257,30 +3336,40 @@ async function firstChangedNoteTitle(
 /**
  * Outcome of bootstrapping a fresh vault's first credential (vault#282 Stage 2).
  *
- * Vault no longer mints `pvt_*` tokens. The first credential for a new vault is
- * a hub-issued JWT, minted via the same operator.token → hub mint-token path
- * `mcp-install --mint` uses (cli.ts ~`cmdMcpInstall`). When no hub is reachable
- * (standalone install, no operator.token, or no real hub origin), `token` is
- * null and `guidance` carries the operator's next step.
+ * Vault no longer mints `pvt_*` tokens. When a token IS minted (explicit opt-in
+ * only — vault#442), it's a hub-issued JWT scoped narrow (`vault:<name>:read`
+ * or `:write`, NEVER `:admin`), minted via the same operator.token → hub
+ * mint-token path `mcp-install --mint` uses (cli.ts ~`cmdMcpInstall`). When no
+ * hub is reachable (standalone install, no operator.token, or no real hub
+ * origin), `token` is null and `guidance` carries the operator's next step.
  */
 interface VaultCredential {
-  /** Hub-issued JWT scoped to `vault:<name>:admin`, or null when no hub is reachable. */
+  /** Hub-issued JWT scoped narrow (read/write), or null when not minted / no hub reachable. */
   token: string | null;
   /** Human-readable note: how the token was issued, or why it wasn't. */
   guidance: string;
 }
 
 /**
- * Mint the first credential for a freshly-created vault.
+ * Mint a scope-narrow credential for a vault (explicit opt-in — vault#442).
  *
- * Decision (vault#282 Stage 2): when a hub is reachable (operator.token present
- * AND a real hub origin resolves), mint a `vault:<name>:admin` hub JWT and
- * return it as the bootstrap credential — preserving the `create --json`
- * `token` string contract hub's admin-vaults.ts requires. When no hub is
+ * Default vault auth is per-user OAuth (browser sign-in on first MCP connect);
+ * tokens are only for the header-auth / script use case and are minted ONLY
+ * when explicitly requested. Decision (vault#442): the create/init flow NEVER
+ * auto-mints, and when a token IS requested it's scope-narrow — `verb` is
+ * `read` (default) or `write`, NEVER `admin`. (Admin tokens, when truly
+ * needed, are minted out-of-band via `mcp-install --scope vault:admin` against
+ * a hub running hub#449, or the hub admin SPA's own session-cookie path.)
+ *
+ * When a hub is reachable (operator.token present AND a real hub origin
+ * resolves), mint a `vault:<name>:<verb>` hub JWT and return it. When no hub is
  * reachable, return `token: null` plus explicit standalone guidance. There is
  * no local pvt_* fallback anymore.
  */
-async function mintBootstrapCredential(name: string): Promise<VaultCredential> {
+async function mintBootstrapCredential(
+  name: string,
+  verb: "read" | "write" = "read",
+): Promise<VaultCredential> {
   const operatorToken = readOperatorToken();
   if (!operatorToken) {
     return {
@@ -3305,7 +3394,7 @@ async function mintBootstrapCredential(name: string): Promise<VaultCredential> {
   const result = await mintHubJwt({
     hubOrigin: hub.url,
     operatorToken,
-    scope: `vault:${name}:admin`,
+    scope: `vault:${name}:${verb}`,
     subject: "parachute-vault-bootstrap",
   });
   if ("kind" in result) {
@@ -3316,7 +3405,7 @@ async function mintBootstrapCredential(name: string): Promise<VaultCredential> {
     return {
       token: null,
       guidance:
-        `No token issued — ${detail}. Verify the hub is running (hub#449 for vault:admin mint), ` +
+        `No token issued — ${detail}. Verify the hub is running, ` +
         "then run `parachute-vault mcp-install`, or set VAULT_AUTH_TOKEN.",
     };
   }
@@ -3327,13 +3416,76 @@ async function mintBootstrapCredential(name: string): Promise<VaultCredential> {
 }
 
 /**
- * Create a vault's config + DB and mint its first credential.
+ * Create a vault's config + DB.
  *
- * Returns the bootstrap credential (a hub JWT, or null + guidance when no hub
- * is reachable — vault#282 Stage 2). The DB is created lazily via
- * `getVaultStore` so migrations + schema run; we no longer write any pvt_* row.
+ * Default vault auth is per-user OAuth (vault#442) — create does NOT mint or
+ * bake in any token. Returns a `VaultCredential` whose `token` is null and
+ * whose `guidance` points at the OAuth-first connect path. A scope-narrow
+ * token is minted only when the caller passes `mintVerb` (the explicit
+ * header-auth / script opt-in: `read` default or `write`, NEVER `admin`). The
+ * DB is created lazily via `getVaultStore` so migrations + schema run; we never
+ * write any pvt_* row.
  */
-async function createVault(name: string): Promise<VaultCredential> {
+interface CreateVaultOptions {
+  /**
+   * Opt-in token mint (vault#442). Unset → no token is minted; the vault uses
+   * per-user OAuth on first MCP connect. Set to `read`/`write` → mint a
+   * scope-narrow `vault:<name>:<verb>` hub JWT for the header-auth / script
+   * use case. `admin` is intentionally NOT accepted here.
+   */
+  mintVerb?: "read" | "write";
+  /**
+   * 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: [],
@@ -3344,7 +3496,60 @@ 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);
-  return mintBootstrapCredential(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.`,
+        );
+      }
+    }
+  }
+
+  // vault#442: default to per-user OAuth — do NOT auto-mint or bake in a
+  // shared token. Only mint when the caller explicitly opted in (header-auth /
+  // script use case), and then scope-narrow (read/write, never admin).
+  if (opts.mintVerb) {
+    return mintBootstrapCredential(name, opts.mintVerb);
+  }
+  return {
+    token: null,
+    guidance:
+      "No token minted — this vault uses per-user OAuth (sign in on first connect). " +
+      "Need a header-auth token for a script? Run " +
+      `\`parachute auth mint-token --scope vault:${name}:read\` (or \`:write\`).`,
+  };
 }
 
 interface InstallMcpConfigOpts {
@@ -3426,9 +3631,11 @@ Setup:
   parachute-vault init [--mcp|--no-mcp] [--token|--no-token] [--vault-name <name>]
                        [--autostart|--no-autostart]
                                            Set up everything (one command, idempotent).
-                                           --mcp/--no-mcp controls the Claude Code MCP entry;
-                                           --token/--no-token controls whether an API token is
-                                           printed for pasting into other MCP clients / scripts.
+                                           --mcp/--no-mcp controls the Claude Code MCP entry (written
+                                           for per-user OAuth by default — no baked token; sign in on
+                                           first connect). --token opts into ALSO minting a scope-narrow
+                                           header-auth token (vault:<name>:read) for non-OAuth clients /
+                                           scripts; --no-token (the default) skips minting entirely.
                                            --vault-name skips the prompt and names the vault
                                            (lowercase alphanumeric, hyphens, underscores;
                                            omit to be prompted interactively, default "default").
@@ -3448,7 +3655,18 @@ 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] [--mint [--scope read|write]] [--token <bearer>]
+                                           Create a new vault (--json: emit { name, token, paths, set_as_default }).
+                                           Default auth is per-user OAuth — NO token is minted; connect with
+                                           "claude mcp add --transport http parachute-<name> <endpoint>" and sign in
+                                           on first use. --mint opts into a scope-narrow hub JWT for the header-auth /
+                                           script case (--scope read [default] | write — admin is NOT mintable from
+                                           create); --token <bearer> pastes an existing bearer instead of minting.
+                                           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}"`);
   }