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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.5.2-rc.1",
+  "version": "0.5.2-rc.2",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",

package/src/cli.ts

@@ -56,6 +56,7 @@ import {
   buildMcpConfigJson,
   buildMcpEntryPlan,
   chooseHubOrigin,
+  chooseMcpUrl,
   detectInstallContext,
   mintHubJwt,
   readOperatorToken,
@@ -478,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;
@@ -490,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}`);
@@ -517,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,
@@ -535,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.");
@@ -551,6 +556,7 @@ async function cmdInit(args: string[] = []) {
     bindHost,
     port,
     mcpUrl,
+    vaultName: defaultVault,
     noTokenGuidance: credentialGuidance,
   });
   for (const line of lines) console.log(line);
@@ -825,12 +831,53 @@ async function cmdCreate(args: string[]) {
   // 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.
-  // `--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("--"));
+
+  // --- 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]");
@@ -863,7 +910,18 @@ async function cmdCreate(args: string[]) {
 
   ensureConfigDirSync();
   const wasFirst = listVaults().length === 0;
-  const credential = await createVault(name, noMirror ? { enableMirror: false } : {});
+  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
@@ -897,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),
@@ -921,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() {
@@ -3274,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).
+ *
+ * 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.)
  *
- * 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
+ * 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 {
@@ -3322,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) {
@@ -3333,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.",
     };
   }
@@ -3344,13 +3416,24 @@ 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.
  */
 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
@@ -3454,7 +3537,19 @@ async function createVault(
     }
   }
 
-  return mintBootstrapCredential(name);
+  // 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 {
@@ -3536,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").
@@ -3558,8 +3655,13 @@ Setup:
   parachute --version                      Print the installed version (alias: -v, version)
 
 Vaults:
-  parachute-vault create <name> [--json] [--no-mirror]
+  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.

package/src/init-summary.test.ts

@@ -13,6 +13,7 @@ const baseInput = {
   bindHost: "127.0.0.1",
   port: 1940,
   mcpUrl: "http://127.0.0.1:1940/vault/default/mcp",
+  vaultName: "default",
 };
 
 function lines(addMcp: boolean, addToken: boolean, apiKey: string | undefined) {
@@ -96,16 +97,70 @@ describe("buildInitSummaryLines", () => {
     });
   });
 
-  describe("MCP=N + token=N (unreachable)", () => {
+  // vault#442: the DEFAULT init path — MCP wired, NO token minted (per-user
+  // OAuth). The summary must LEAD with the OAuth connect path, never mint, and
+  // never surface the old "no token issued" failure copy.
+  describe("MCP=Y + no token (vault#442 OAuth default)", () => {
+    const out = lines(true, false, undefined).join("\n");
+
+    test("leads with the OAuth connect message — no token needed", () => {
+      expect(out).toContain("no token needed, you'll sign in on first use");
+    });
+
+    test("tells the user Claude Code is already wired in", () => {
+      expect(out).toContain("Claude Code is already wired in");
+    });
+
+    test("shows the OAuth `claude mcp add` command for other clients", () => {
+      expect(out).toContain(
+        "claude mcp add --transport http parachute-vault http://127.0.0.1:1940/vault/default/mcp",
+      );
+    });
+
+    test("offers the scope-narrow opt-in mint for scripts (full vault:<name>:read, never admin)", () => {
+      // Must be the three-segment named-resource form the hub mint-token model
+      // requires — a bare `vault:read` would mint a malformed scope (vault#443).
+      expect(out).toContain("parachute auth mint-token --scope vault:default:read");
+      expect(out).not.toContain("--scope vault:read ");
+      expect(out).not.toMatch(/--scope vault:read$/m);
+      expect(out).not.toContain("vault:admin");
+    });
+
+    test("does NOT print or imply any minted token", () => {
+      expect(out).not.toContain("Your API token:");
+      expect(out).not.toContain("Baked into ~/.claude.json");
+      expect(out).not.toContain("Authorization: Bearer");
+    });
+
+    test("does NOT surface the old no-token-issued failure copy", () => {
+      expect(out).not.toContain("No token issued");
+    });
+
+    test("threads a non-default vault name into the mint-token scope", () => {
+      const out2 = buildInitSummaryLines({
+        ...baseInput,
+        vaultName: "journal",
+        mcpUrl: "http://127.0.0.1:1940/vault/journal/mcp",
+        addMcp: true,
+        addToken: false,
+        apiKey: undefined,
+      }).join("\n");
+      expect(out2).toContain("parachute auth mint-token --scope vault:journal:read");
+      expect(out2).not.toContain("vault:default:read");
+    });
+  });
+
+  describe("MCP=N + token=N (OAuth default, Claude Code not wired)", () => {
     const out = lines(false, false, undefined).join("\n");
 
-    test("warns the vault is unreachable", () => {
-      expect(out).toContain("your vault isn't reachable by any client");
+    test("frames skipping the MCP entry as OAuth-first, not 'unreachable'", () => {
+      expect(out).toContain("uses per-user OAuth, no token needed");
+      expect(out).not.toContain("your vault isn't reachable by any client");
     });
 
-    test("points to the mcp-install recovery path (hub JWT)", () => {
+    test("points to mcp-install (no token-minting framing)", () => {
       expect(out).toContain("parachute-vault mcp-install");
-      expect(out).toContain("mints a hub JWT");
+      expect(out).not.toContain("mints a hub JWT");
     });
 
     test("does not print any token", () => {
@@ -118,6 +173,23 @@ describe("buildInitSummaryLines", () => {
     });
   });
 
+  // Explicit opt-in but no hub reachable to mint (vault#282 Stage 2 path,
+  // reached only when the operator passes --token without a hub).
+  describe("MCP=N + token=Y but no hub (opt-in mint failed)", () => {
+    const out = buildInitSummaryLines({
+      ...baseInput,
+      addMcp: false,
+      addToken: true,
+      apiKey: undefined,
+      noTokenGuidance: "No token issued — hub unreachable.",
+    }).join("\n");
+
+    test("surfaces the no-token-issued guidance + recovery", () => {
+      expect(out).toContain("No token issued");
+      expect(out).toContain("parachute-vault mcp-install");
+    });
+  });
+
   test("always prints Config: and Server: lines", () => {
     for (const [addMcp, addToken] of [
       [true, true],

package/src/init-summary.ts

@@ -12,6 +12,13 @@ export type InitSummaryInput = {
   bindHost: string;
   port: number;
   mcpUrl: string;
+  /**
+   * The default vault's name — used to emit the three-segment
+   * `vault:<vaultName>:read` scope in the OAuth-first mint-token suggestion
+   * (the hub mint-token model requires the named-resource form;
+   * a bare `vault:read` would mint a malformed scope). vault#442/#443.
+   */
+  vaultName: string;
   /**
    * Guidance from the bootstrap-credential step when no token could be issued
    * (standalone install, no hub reachable — vault#282 Stage 2). Surfaced when
@@ -23,44 +30,54 @@ export type InitSummaryInput = {
 
 /**
  * Build the post-install summary lines for `vault init`, branched on the
- * (addMcp, addToken, apiKey) decision matrix. Post-0.5.0 the token is a
- * hub-issued JWT minted via operator.token; when no hub is reachable `apiKey`
- * is undefined even though the operator opted in (`addToken`/`addMcp`):
+ * (addMcp, addToken, apiKey) decision matrix.
+ *
+ * vault#442: the DEFAULT is per-user OAuth — no token is minted, and the
+ * Claude Code MCP entry is written without a baked bearer (browser sign-in on
+ * first connect). A token is minted only on explicit opt-in (`addToken`), and
+ * then scope-narrow. Branches:
  *
- *   addMcp,  addToken,  apiKey → token baked into claude.json + printed
- *   addMcp,  !addToken, apiKey → token baked into claude.json, hint
- *   !addMcp, addToken,  apiKey → token printed prominently
- *   wanted-token-but-no-hub    → guidance: no token issued, recovery paths
- *   !addMcp, !addToken         → warning: vault unreachable; recovery paths
+ *   addMcp,  !apiKey            → OAuth-first: connect, sign in on first use
+ *   addMcp,  addToken,  apiKey  → token baked into claude.json + printed
+ *   addMcp,  !addToken, apiKey  → token baked into claude.json, hint
+ *   !addMcp, addToken,  apiKey  → token printed prominently
+ *   !addMcp, addToken,  !apiKey → opted into a token but no hub reachable
+ *   !addMcp, !addToken          → OAuth-first: add Claude Code later
  */
 export function buildInitSummaryLines(input: InitSummaryInput): string[] {
-  const { addMcp, addToken, apiKey, configDir, bindHost, port, mcpUrl, noTokenGuidance } = input;
+  const { addMcp, addToken, apiKey, configDir, bindHost, port, mcpUrl, vaultName, noTokenGuidance } = input;
   const lines: string[] = [];
   lines.push("");
   lines.push("---");
 
-  const wantedToken = addMcp || addToken;
-
-  if (addMcp && addToken && apiKey) {
+  if (addMcp && apiKey && addToken) {
     lines.push("");
     lines.push(`Your API token: ${apiKey}`);
     lines.push(`  - Baked into ~/.claude.json for Claude Code ✓`);
     lines.push(`  - Paste into your other MCP client's config, or use as Authorization: Bearer <token>`);
     lines.push(`  - Won't be shown again — save it now.`);
-  } else if (addMcp && !addToken && apiKey) {
+  } else if (addMcp && apiKey && !addToken) {
     lines.push("");
     lines.push(
       "Token in ~/.claude.json; run `parachute-vault mcp-install` later if you need one for other clients.",
     );
+  } else if (addMcp && !apiKey) {
+    // vault#442 default: OAuth-first. The MCP entry is wired without a bearer —
+    // Claude Code signs in via browser OAuth on first connect. No token needed.
+    lines.push("");
+    lines.push("Connect your AI — no token needed, you'll sign in on first use:");
+    lines.push(`  Claude Code is already wired in (~/.claude.json) — just start a session.`);
+    lines.push(`  Other clients: claude mcp add --transport http parachute-vault ${mcpUrl}`);
+    lines.push(`  Need a header-auth token for a script? parachute auth mint-token --scope vault:${vaultName}:read`);
   } else if (!addMcp && addToken && apiKey) {
     lines.push("");
     lines.push(`Your API token: ${apiKey}`);
     lines.push(`  - Paste into your other MCP client's config, or use as Authorization: Bearer <token>`);
     lines.push(`  - Won't be shown again — save it now.`);
-  } else if (wantedToken && !apiKey) {
-    // Opted into a token but no hub was reachable to mint one (vault#282
-    // Stage 2 — vault no longer mints local pvt_* tokens). Surface why and
-    // the recovery paths.
+  } else if (!addMcp && addToken && !apiKey) {
+    // Explicitly opted into a token but no hub was reachable to mint one
+    // (vault#282 Stage 2 — vault no longer mints local pvt_* tokens). Surface
+    // why and the recovery paths.
     lines.push("");
     lines.push(
       noTokenGuidance ??
@@ -73,12 +90,13 @@ export function buildInitSummaryLines(input: InitSummaryInput): string[] {
       "  or set VAULT_AUTH_TOKEN for an operator-channel bearer.",
     );
   } else if (!addMcp && !addToken) {
+    // OAuth-first, but the operator skipped wiring Claude Code too.
     lines.push("");
     lines.push(
-      "You've skipped both MCP install and token generation — your vault isn't reachable by any client.",
+      "Skipped the Claude Code MCP entry. Add it anytime — it uses per-user OAuth, no token needed:",
     );
     lines.push(
-      "  Add Claude Code later with `parachute-vault mcp-install`, which mints a hub JWT (needs a hub running).",
+      "  parachute-vault mcp-install",
     );
   }
 

package/src/vault-create.test.ts

@@ -85,13 +85,15 @@ describe("vault create --json", () => {
     expect(lines).toHaveLength(1);
     const payload = JSON.parse(lines[0]!);
     expect(payload.name).toBe("myvault");
-    // vault#282 Stage 2: vault no longer mints pvt_* tokens. The contract
-    // hub's admin-vaults.ts requires still holds (`token` is a string). In
-    // this sandbox there's no hub/operator.token, so no token is issued: the
-    // token field is the empty string and `token_guidance` explains why.
+    // vault#442: default auth is per-user OAuth — `create` does NOT mint a
+    // token. The contract hub's admin-vaults.ts requires still holds (`token`
+    // is a string); it's the empty string and `token_guidance` carries the
+    // OAuth-first connect path (the hub SPA handles the empty-token case and
+    // mints admin via its own session-cookie path).
     expect(typeof payload.token).toBe("string");
     expect(payload.token).toBe("");
-    expect(payload.token_guidance).toContain("No token issued");
+    expect(payload.token_guidance).toContain("No token minted");
+    expect(payload.token_guidance).toContain("per-user OAuth");
     expect(payload.set_as_default).toBe(true);
     expect(payload.paths.vault_dir).toBe(join(home, "vault", "data", "myvault"));
     expect(payload.paths.vault_db).toBe(join(home, "vault", "data", "myvault", "vault.db"));
@@ -160,6 +162,95 @@ describe("vault create --json", () => {
   });
 });
 
+/**
+ * vault#442: default to per-user OAuth — `create` must NOT auto-mint or bake in
+ * a shared `vault:<name>:admin` token. Token-minting is explicit opt-in
+ * (`--mint`) and scope-narrow (read/write, NEVER admin); `--token <bearer>` is
+ * the paste path. These tests pin the behavioral contract.
+ */
+describe("vault create — OAuth-first auth (vault#442)", () => {
+  test("default create does NOT mint a token — empty token + OAuth guidance (--json)", () => {
+    const { exitCode, stdout } = runCli(["create", "oauthy", "--json"], {
+      PARACHUTE_HOME: home,
+    });
+    expect(exitCode).toBe(0);
+    const payload = JSON.parse(stdout.trim());
+    // No token baked in — OAuth on first connect.
+    expect(payload.token).toBe("");
+    expect(payload.token_guidance).toContain("No token minted");
+    expect(payload.token_guidance).toContain("per-user OAuth");
+    // Never the admin-mint failure copy.
+    expect(payload.token_guidance).not.toContain("No token issued");
+    expect(payload.token_guidance).not.toContain("admin");
+  });
+
+  test("default create leads the human summary with the OAuth connect command", () => {
+    const { exitCode, stdout } = runCli(["create", "connectme"], {
+      PARACHUTE_HOME: home,
+    });
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain(
+      "Connect your AI: claude mcp add --transport http parachute-connectme",
+    );
+    expect(stdout).toContain("no token needed");
+    // Scope-narrow opt-in pointer, never admin.
+    expect(stdout).toContain("parachute auth mint-token --scope vault:connectme:read");
+    expect(stdout).not.toContain("vault:connectme:admin");
+  });
+
+  test("--scope admin is rejected from the create flow (admin never mintable here)", () => {
+    const { exitCode, stdout, stderr } = runCli(
+      ["create", "noadmin", "--mint", "--scope", "admin", "--json"],
+      { PARACHUTE_HOME: home },
+    );
+    expect(exitCode).not.toBe(0);
+    expect(stdout).toBe("");
+    expect(stderr).toContain('--scope must be "read" or "write"');
+    // The vault must not have been created (rejected before createVault).
+    expect(existsSync(join(home, "vault", "data", "noadmin", "vault.db"))).toBe(false);
+  });
+
+  test("--mint and --token are mutually exclusive", () => {
+    const { exitCode, stderr } = runCli(
+      ["create", "conflict", "--mint", "--token", "abc.def.ghi", "--json"],
+      { PARACHUTE_HOME: home },
+    );
+    expect(exitCode).not.toBe(0);
+    expect(stderr).toContain("mutually exclusive");
+  });
+
+  test("--token <bearer> paste path surfaces the supplied bearer (no mint attempted)", () => {
+    const { exitCode, stdout } = runCli(
+      ["create", "pasted", "--token", "header.auth.bearer", "--json"],
+      { PARACHUTE_HOME: home },
+    );
+    expect(exitCode).toBe(0);
+    const payload = JSON.parse(stdout.trim());
+    // The pasted bearer is surfaced verbatim — vault never minted one.
+    expect(payload.token).toBe("header.auth.bearer");
+    expect(payload.token_guidance).toContain("--token");
+    // No admin scope, no mint-failure copy.
+    expect(payload.token_guidance).not.toContain("No token issued");
+  });
+
+  test("--mint (no hub reachable) opts in but mints scope-narrow read, never admin", () => {
+    // In this sandbox there's no hub/operator.token, so the mint can't complete
+    // — but the request is scope-narrow read by default and must NEVER ask for
+    // admin. We assert the create still succeeds and the guidance points at the
+    // mint-token recovery (the scope requested is read, per mintBootstrapCredential).
+    const { exitCode, stdout } = runCli(
+      ["create", "wantmint", "--mint", "--json"],
+      { PARACHUTE_HOME: home },
+    );
+    expect(exitCode).toBe(0);
+    const payload = JSON.parse(stdout.trim());
+    // No hub here → no token, but the guidance is the standalone mint path, not
+    // an admin grant.
+    expect(payload.token).toBe("");
+    expect(payload.token_guidance).not.toContain("admin");
+  });
+});
+
 /**
  * Regression tests for #208: `vault create` was not updating
  * `~/.parachute/services.json`, so vaults created after init were invisible
@@ -229,10 +320,14 @@ describe("vault create (human mode)", () => {
     );
     expect(exitCode).toBe(0);
     expect(stdout).toContain('Vault "human" created.');
-    // vault#282 Stage 2: with no hub reachable in this sandbox, no token is
-    // issued — the human output prints the guidance instead of "API token:".
-    expect(stdout).toContain("No token issued");
-    expect(stdout).toContain("Install the hub");
+    // vault#442: default auth is per-user OAuth — NO token is minted, even when
+    // a hub would have been reachable. The human output leads with the OAuth
+    // connect command and never prints an "API token:" line.
+    expect(stdout).toContain("No token minted");
+    expect(stdout).toContain("Connect your AI: claude mcp add --transport http parachute-human");
+    expect(stdout).not.toContain("API token:");
+    // The old admin auto-mint failure copy must NOT fire on a default create.
+    expect(stdout).not.toContain("No token issued");
     // Human output should NOT be valid JSON.
     expect(() => JSON.parse(stdout.trim())).toThrow();
   });