@openparachute/vault 0.4.7-rc.2 → 0.4.8-rc.6

package/src/cli.ts

@@ -103,7 +103,7 @@ import type { TokenPermission } from "./token-store.ts";
 import { resolveCreateTokenFlags, VAULT_SCOPES } from "./scopes.ts";
 import { validateVaultName, decideInitVaultName } from "./vault-name.ts";
 import { getVaultStore } from "./vault-store.ts";
-import { upsertService, ServicesManifestError } from "./services-manifest.ts";
+import { selfRegister } from "./self-register.ts";
 import {
   hasOwnerPassword,
   setOwnerPassword,
@@ -245,27 +245,6 @@ switch (command) {
 // Command implementations
 // ---------------------------------------------------------------------------
 
-/**
- * Compute the `paths` array for the parachute-vault entry in services.json.
- * One entry advertises every vault on this server; `paths[0]` is the
- * canonical mount the hub stamps into `.well-known/parachute.json`, so the
- * default vault sorts first when one is set. With no vaults yet, fall back
- * to "/" so an early-init registration is still well-formed.
- */
-function buildVaultServicePaths(
-  defaultVault: string | undefined,
-  vaults: string[],
-): string[] {
-  if (vaults.length === 0) return ["/"];
-  if (defaultVault && vaults.includes(defaultVault)) {
-    return [
-      `/vault/${defaultVault}`,
-      ...vaults.filter((v) => v !== defaultVault).map((v) => `/vault/${v}`),
-    ];
-  }
-  return vaults.map((v) => `/vault/${v}`);
-}
-
 async function cmdInit(args: string[] = []) {
   ensureConfigDirSync();
 
@@ -363,24 +342,24 @@ async function cmdInit(args: string[] = []) {
   // by name, preserving entries for other services. Non-fatal on failure —
   // init can complete without the manifest, just with a warning.
   //
+  // `selfRegister` stamps the full manifest-sourced row (displayName, tagline,
+  // stripPrefix, installDir) from `.parachute/module.json` — the same shape
+  // server boot writes via the self-registration pass (vault#266). Keeping
+  // the two write paths in lockstep means `parachute-vault init` and the
+  // first server boot agree on the row contents; without that, a re-init
+  // would silently lose the manifest fields the boot pass had added.
+  //
   // `paths[0]` is the canonical mount point — the hub uses it for the
   // `.well-known/parachute.json` URL and for `parachute expose`, so the
   // default vault always sorts first. Remaining vaults follow so the hub
   // well-known and paraclaw's attach picker see every vault on this server.
   // Re-running init re-registers the full set; that doubles as the
   // recovery path for installs whose services.json is stale (#208).
-  try {
-    upsertService({
-      name: "parachute-vault",
-      port: globalConfig.port || DEFAULT_PORT,
-      paths: buildVaultServicePaths(globalConfig.default_vault, allVaults),
-      health: "/health",
-      version: pkg.version,
-    });
-  } catch (err) {
-    const msg = err instanceof ServicesManifestError ? err.message : String(err);
-    console.error(`  Warning: could not update ~/.parachute/services.json: ${msg}`);
-  }
+  selfRegister({
+    version: pkg.version,
+    warn: (msg) => console.error(`  Warning: ${msg}`),
+    log: () => {}, // CLI init has its own status lines; suppress duplicate noise.
+  });
 
   // 2b. Migrate existing legacy keys into per-vault token tables
   for (const v of listVaults()) {
@@ -862,19 +841,16 @@ function cmdCreate(args: string[]) {
   // attach picker see this vault. cmdInit registers on first run; cmdCreate
   // adds the new path on every subsequent vault. Without this, vaults
   // created after init were invisible to the hub (#208).
-  // Warnings go to stderr to keep --json stdout clean for the orchestrator.
-  try {
-    upsertService({
-      name: "parachute-vault",
-      port: globalConfig.port || DEFAULT_PORT,
-      paths: buildVaultServicePaths(globalConfig.default_vault, listVaults()),
-      health: "/health",
-      version: pkg.version,
-    });
-  } catch (err) {
-    const msg = err instanceof ServicesManifestError ? err.message : String(err);
-    console.error(`Warning: could not update ~/.parachute/services.json: ${msg}`);
-  }
+  //
+  // Routed through `selfRegister` (vault#266) so the row carries the full
+  // manifest-sourced metadata (displayName, tagline, stripPrefix, installDir)
+  // — same shape server boot writes. Warnings go to stderr to keep --json
+  // stdout clean for the orchestrator.
+  selfRegister({
+    version: pkg.version,
+    warn: (msg) => console.error(`Warning: ${msg}`),
+    log: () => {}, // CLI create has its own status lines.
+  });
 
   if (jsonMode) {
     const payload = {
@@ -943,6 +919,11 @@ function takeArgValue(args: string[], name: string): { value?: string; missingVa
  * Targeting:
  *   --scope <verb>        vault:read | vault:write | vault:admin (default: vault:read).
  *                         For --mint, expands to vault:<vault-name>:<verb>.
+ *                         vault:admin requires --legacy-pat — hub policy makes
+ *                         per-vault admin non-requestable via mint-token (it's
+ *                         operator-only, minted only through the session-
+ *                         cookie-gated admin SPA endpoint), so --mint + admin
+ *                         is rejected pre-flight.
  *   --install-scope <s>   local (default) | user | project. local writes to
  *                         ~/.claude.json under projects[<cwd>].mcpServers
  *                         (private, this directory only — matches Claude
@@ -1331,6 +1312,28 @@ async function executeMcpInstall(opts: ExecuteMcpInstallOpts): Promise<void> {
     bearer = fullToken;
   } else {
     // mode === "mint"
+    // Pre-flight: hub policy rejects `vault:<name>:admin` via the public
+    // mint-token endpoint. Per-vault admin is operator-only, mintable
+    // only through the session-cookie-gated `/admin/vault-admin-token/:name`
+    // SPA path. Calling hub with admin would surface a 400:
+    //   "Hub mint-token rejected (HTTP 400, invalid_scope):
+    //    scope vault:default:admin is not requestable via mint-token;
+    //    use OAuth flow or operator rotation"
+    // Fail early with the actionable remediation rather than letting
+    // the operator chase the hub's wire-level error. See
+    // `parachute-hub/src/scope-explanations.ts` (VAULT_ADMIN_RE) and
+    // `parachute-hub/src/api-mint-token.ts` (non-requestable guard).
+    if (verb === "admin") {
+      console.error(
+        "Hub policy: vault:<name>:admin is not requestable via mint-token " +
+          "(per-vault admin is operator-only, minted only by the session-cookie-gated " +
+          "admin SPA at <hub>/admin/vaults/" + vaultName + ").\n" +
+          "  Fix: use `--legacy-pat --scope vault:admin` to mint a vault-DB pvt_* with admin scope " +
+          "(the right shape for an MCP entry needing schema management).\n" +
+          "  Or:  drop --scope to default to vault:read (least privilege), or use --scope vault:write.",
+      );
+      process.exit(1);
+    }
     const operatorToken = readOperatorToken();
     if (!operatorToken) {
       console.error(
@@ -3392,7 +3395,13 @@ Vaults:
                                             (any shape) instead of minting.
                                             --legacy-pat: mint a vault-DB pvt_*
                                             token (deprecated; for self-hosted-
-                                            without-hub setups).
+                                            without-hub setups). Also the only
+                                            path for --scope vault:admin — hub
+                                            policy reserves per-vault admin for
+                                            operator-only minting (the admin SPA
+                                            session-cookie path), so --mint
+                                            --scope vault:admin is rejected
+                                            pre-flight.
                                             --install-scope local (default) writes
                                             ~/.claude.json under
                                             projects[<cwd>].mcpServers (this

package/src/config.test.ts

@@ -1,9 +1,12 @@
 import { describe, test, expect } from "bun:test";
+import { statSync } from "fs";
+import { join } from "path";
 import {
   writeVaultConfig,
   readVaultConfig,
   writeGlobalConfig,
   readGlobalConfig,
+  writeEnvFile,
   generateApiKey,
   hashKey,
   verifyKey,
@@ -210,6 +213,29 @@ describe("config", () => {
     expect(reloaded.api_keys?.find((k) => k.id === "k_legacy")?.scope).toBe("write");
   });
 
+  test("writeEnvFile writes .env at 0600 (SCRIBE_AUTH_TOKEN secrecy)", () => {
+    // Regression for vault#354 reviewer finding: the .env holds
+    // SCRIBE_AUTH_TOKEN (the vault↔scribe loopback bearer). On a
+    // shared-user machine or a Docker image with a loose umask, a
+    // world-readable .env would leak the bearer to any local process.
+    //
+    // Resolve the path dynamically from PARACHUTE_HOME (not the
+    // module-load-time `ENV_PATH` constant) so this test is robust to
+    // earlier tests in the suite that mutate PARACHUTE_HOME — writeEnvFile
+    // itself resolves the path dynamically via `envFilePath()`.
+    const envPath = join(process.env.PARACHUTE_HOME!, "vault", ".env");
+    writeEnvFile({ SCRIBE_AUTH_TOKEN: "test-bearer-do-not-leak", PORT: "1940" });
+    const mode = statSync(envPath).mode & 0o777;
+    expect(mode).toBe(0o600);
+
+    // Existing-file branch: writeFileSync's `mode` only applies on
+    // create, so the defensive chmodSync must downgrade an existing
+    // (e.g. 0644-from-an-older-version) .env to 0600 on the next write.
+    writeEnvFile({ SCRIBE_AUTH_TOKEN: "rotated", PORT: "1940" });
+    const mode2 = statSync(envPath).mode & 0o777;
+    expect(mode2).toBe(0o600);
+  });
+
   test("round-trips autostart: true|false (#113)", () => {
     // Default: absent means autostart-on (init registers the daemon).
     writeGlobalConfig({ port: 1940 });

package/src/config.ts

@@ -277,6 +277,24 @@ export interface GlobalConfig {
    * resolved path. See `./mirror-config.ts`.
    */
   mirror?: MirrorConfigType;
+  /**
+   * Auto-transcribe configuration for the vault↔scribe handoff (vault#353,
+   * design 2026-05-21 Part 2). When `enabled: true` AND scribe is discoverable
+   * (`services.json` or `SCRIBE_URL` env), audio attachments uploaded to any
+   * vault are automatically sent to scribe and the resulting transcript lands
+   * as a sibling `<attachment-path>.transcript.md` note.
+   *
+   * URL + bearer are not stored here — URL is resolved per-process from
+   * `services.json` via `scribe-discovery.ts`, and bearer comes from the
+   * `SCRIBE_AUTH_TOKEN` env var (persisted in `~/.parachute/vault/.env`).
+   * The schema's `autoTranscribe.scribeUrl` / `autoTranscribe.scribeBearer`
+   * fields are projection of those resolved values (readOnly / writeOnly),
+   * not separate storage.
+   */
+  auto_transcribe?: {
+    /** Master toggle. Default false; the worker is a no-op when unset. */
+    enabled?: boolean;
+  };
 }
 
 // ---------------------------------------------------------------------------
@@ -1141,6 +1159,22 @@ 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);
+      // 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.
+      const autoTranscribeStart = yaml.match(/^auto_transcribe:\s*$/m);
+      let autoTranscribeEnabled: boolean | undefined;
+      if (autoTranscribeStart) {
+        const after = yaml.slice((autoTranscribeStart.index ?? 0) + autoTranscribeStart[0].length);
+        for (const line of after.split("\n")) {
+          if (line.match(/^\S/) && line.trim().length > 0) break; // next top-level key
+          const m = line.match(/^\s+enabled:\s*(true|false)/);
+          if (m) {
+            autoTranscribeEnabled = m[1]! === "true";
+            break;
+          }
+        }
+      }
       const config: GlobalConfig = {
         port: portMatch ? parseInt(portMatch[1]!, 10) : DEFAULT_PORT,
         default_vault: defaultVaultMatch?.[1],
@@ -1153,6 +1187,9 @@ export function readGlobalConfig(): GlobalConfig {
       if (autostartMatch) {
         config.autostart = autostartMatch[1]! === "true";
       }
+      if (autoTranscribeEnabled !== undefined) {
+        config.auto_transcribe = { enabled: autoTranscribeEnabled };
+      }
 
       // Parse backup_codes: a YAML list of quoted bcrypt hashes under
       //   backup_codes:
@@ -1297,6 +1334,13 @@ export function writeGlobalConfig(config: GlobalConfig): void {
     lines.push(...serializeMirrorSection(config.mirror));
   }
 
+  if (config.auto_transcribe) {
+    lines.push("auto_transcribe:");
+    if (config.auto_transcribe.enabled !== undefined) {
+      lines.push(`  enabled: ${config.auto_transcribe.enabled}`);
+    }
+  }
+
   // 0600 — owner read/write only. This file may contain the bcrypt password
   // hash and plaintext TOTP secret; it must not be world- or group-readable.
   writeFileSync(globalConfigPath(), lines.join("\n") + "\n", { mode: 0o600 });
@@ -1395,7 +1439,15 @@ export function writeEnvFile(env: Record<string, string>): void {
       lines.push(`${key}=${val}`);
     }
   }
-  writeFileSync(envFilePath(), lines.join("\n") + "\n");
+  // 0600 — owner read/write only. This file holds SCRIBE_AUTH_TOKEN (the
+  // vault↔scribe loopback bearer) and any other secrets the operator drops
+  // in via `parachute-vault config set`. It must not be world- or
+  // group-readable on shared-user machines or Docker images with a loose
+  // umask. Mirrors the writeGlobalConfig pattern above.
+  writeFileSync(envFilePath(), lines.join("\n") + "\n", { mode: 0o600 });
+  // writeFileSync's `mode` only applies on file creation, so chmod an existing
+  // file explicitly in case it was written by an older version at 0644.
+  try { chmodSync(envFilePath(), 0o600); } catch {}
 }
 
 /**

package/src/db.ts

@@ -4,11 +4,24 @@
 
 import { Database } from "bun:sqlite";
 import { vaultDbPath, vaultDir } from "./config.ts";
+import { applyConnectionPragmas } from "../core/src/schema.ts";
 import { mkdirSync } from "fs";
 
-/** Open (or create) a vault's SQLite database. */
+/**
+ * Open (or create) a vault's SQLite database with vault's standard
+ * connection pragmas (WAL + synchronous=NORMAL + foreign_keys=ON). Safe
+ * for both the in-process store and out-of-process consumers (CLI,
+ * parachute-runner, mirror tools) — pragmas are idempotent.
+ *
+ * The full schema migration runs separately when a `BunSqliteStore` is
+ * instantiated around the returned handle; callers that just want raw
+ * read access (auth probes, backup tooling) skip that and pay only the
+ * pragma cost.
+ */
 export function openVaultDb(name: string): Database {
   const dir = vaultDir(name);
   mkdirSync(dir, { recursive: true });
-  return new Database(vaultDbPath(name));
+  const db = new Database(vaultDbPath(name));
+  applyConnectionPragmas(db);
+  return db;
 }

package/src/mcp-install-interactive.test.ts

@@ -287,8 +287,23 @@ describe("runInteractiveInstall — decision tree", () => {
     expect(result.scope).toBe("vault:write");
   });
 
-  test("scope widening: typing 'admin' produces vault:admin mint", async () => {
-    const { io } = mockIO([
+  test("typing 'admin' auto-routes to legacy-pat with vault:admin scope (hub mint-token rejects admin)", async () => {
+    // Regression for the symptom Aaron hit on hub 0.5.12-rc.2 / vault
+    // 0.4.7-rc.1: picking "admin" in the mint prompt sent
+    // `vault:default:admin` to `POST /api/auth/mint-token`, which hub
+    // rejects by policy (per-vault admin is non-requestable; see
+    // `parachute-hub/src/scope-explanations.ts:VAULT_ADMIN_RE` and
+    // `api-mint-token.ts`'s non-requestable guard):
+    //
+    //   Hub mint-token rejected (HTTP 400, invalid_scope):
+    //   scope vault:default:admin is not requestable via mint-token;
+    //   use OAuth flow or operator rotation
+    //
+    // Fix: auto-route "admin" in the interactive prompt to legacy-pat
+    // mode (which mints a vault-DB pvt_* — the right shape for an MCP
+    // entry needing admin permissions), with a printed explanation so
+    // the switch isn't silent.
+    const { io, state } = mockIO([
       null,    // accept install-scope default
       "admin",
       true,
@@ -296,7 +311,13 @@ describe("runInteractiveInstall — decision tree", () => {
     const result = await runInteractiveInstall(baseCtx(), io);
     expect(result).not.toBe("abort");
     if (result === "abort") return;
+    expect(result.mode).toBe("legacy-pat");
     expect(result.scope).toBe("vault:admin");
+    // The auto-route must surface the reason — silent re-routing would
+    // mislead operators who specifically want a hub JWT.
+    const logged = state.logs.join("\n");
+    expect(logged).toMatch(/admin requires a vault-DB pvt_\*/);
+    expect(logged).toMatch(/hub policy/);
   });
 
   test("typing 'paste' at the auth prompt switches to token mode + asks for token", async () => {

package/src/mcp-install-interactive.ts

@@ -190,7 +190,9 @@ export async function runInteractiveInstall(
         "Choices:",
         "  Enter       → mint a hub JWT with vault:read scope (recommended).",
         "  write       → mint with vault:write (mutations).",
-        "  admin       → mint with vault:admin (schema management).",
+        "  admin       → mint a vault-DB pvt_* with vault:admin (schema management;",
+        "                hub policy reserves per-vault admin for operator-only paths,",
+        "                so this auto-routes to legacy-pat).",
         "  paste       → use an existing token instead of minting.",
         "  legacy      → mint a vault-DB pvt_* (self-hosted-without-hub).",
       ].join("\n"),
@@ -209,10 +211,27 @@ export async function runInteractiveInstall(
       // operator gets the same control they get when widening a hub
       // JWT's scope. (vault#292 review F2.)
       scope = await askScope(io);
+    } else if (answer === "admin") {
+      // `vault:<name>:admin` is non-requestable via hub mint-token by
+      // policy — only the session-cookie-gated `/admin/vault-admin-token/:name`
+      // endpoint can mint per-vault admin scopes (see
+      // `parachute-hub/src/scope-explanations.ts:VAULT_ADMIN_RE` and
+      // `api-mint-token.ts`'s non-requestable guard). Hub returns
+      // HTTP 400 invalid_scope: "scope vault:<name>:admin is not
+      // requestable via mint-token; use OAuth flow or operator rotation".
+      //
+      // Auto-route to legacy-pat which mints a vault-DB pvt_* with full
+      // permissions — that's the right shape for an operator who wants
+      // admin scope on a local MCP entry. Print a one-line explanation
+      // so the switch isn't silent.
+      io.log("  → admin requires a vault-DB pvt_* (hub policy: per-vault admin");
+      io.log("    is operator-only, not mintable via the public mint-token API).");
+      io.log("    Switching to legacy-pat mode with vault:admin scope.");
+      mode = "legacy-pat";
+      scope = "vault:admin";
     } else {
       mode = "mint";
       if (answer === "write") scope = "vault:write";
-      else if (answer === "admin") scope = "vault:admin";
     }
   } else {
     // No hub-mint path available — explain why and offer the alternatives.

package/src/mcp-install.test.ts

@@ -522,6 +522,46 @@ describe("mcp-install flag parsing", () => {
     expect(res.exitCode).toBe(1);
     expect(res.stderr).toMatch(/No hub origin configured/);
   });
+
+  test("rejects --mint --scope vault:admin pre-flight (hub policy: per-vault admin is non-requestable)", () => {
+    // Regression for the symptom Aaron hit on hub 0.5.12-rc.2 / vault
+    // 0.4.7-rc.1: `parachute vault mcp-install` with the "admin" mint
+    // option sent `vault:default:admin` to `POST /api/auth/mint-token`,
+    // and hub responded:
+    //
+    //   Hub mint-token rejected (HTTP 400, invalid_scope):
+    //   scope vault:default:admin is not requestable via mint-token;
+    //   use OAuth flow or operator rotation
+    //
+    // The combination is invalid by hub policy (see
+    // `parachute-hub/src/scope-explanations.ts:VAULT_ADMIN_RE` and
+    // `api-mint-token.ts`'s non-requestable guard) — per-vault admin
+    // is operator-only, mintable only through the session-cookie-gated
+    // `/admin/vault-admin-token/:name` SPA path.
+    //
+    // The fix rejects the combination pre-flight in vault's mcp-install
+    // with a clear remediation pointing at `--legacy-pat --scope vault:admin`
+    // (which mints a vault-DB pvt_* with admin scope — the right shape
+    // for a local MCP entry needing schema management).
+    setupBareVault(tmp, "default");
+    fs.writeFileSync(path.join(tmp, "operator.token"), "operator-bearer-stub");
+    const res = runCli(
+      ["mcp-install", "--mint", "--scope", "vault:admin"],
+      tmp,
+      { PARACHUTE_HUB_ORIGIN: "https://hub.example.org" },
+    );
+    expect(res.exitCode).toBe(1);
+    // Surface the policy reason so the operator knows why this combo is
+    // rejected (not a transient bug).
+    expect(res.stderr).toMatch(/not requestable via mint-token/);
+    // Point at the working remediation.
+    expect(res.stderr).toMatch(/--legacy-pat --scope vault:admin/);
+    // Pre-flight must fire BEFORE the operator-token / hub-origin checks
+    // pass the request to the network — no "Hub unreachable" / "No hub
+    // origin configured" leak.
+    expect(res.stderr).not.toMatch(/No hub origin configured/);
+    expect(res.stderr).not.toMatch(/Hub unreachable/);
+  });
 });
 
 // ---------------------------------------------------------------------------

package/src/mcp-tools.ts

@@ -178,10 +178,26 @@ function applyTagScopeWrappers(
     const allowed = await getAllowed();
     const result = await orig(params);
     if (!allowed) return result;
-    // Single-note shape (`{...note}` with `id`) vs list shape (array).
+    // Three possible response shapes:
+    //   - Array (legacy list, no cursor)
+    //   - `{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));
     }
+    if (
+      result &&
+      typeof result === "object" &&
+      "notes" in result &&
+      Array.isArray((result as any).notes) &&
+      "next_cursor" in result
+    ) {
+      const r = result as { notes: any[]; next_cursor: string | null };
+      return {
+        notes: r.notes.filter((n: any) => noteWithinTagScope(n, allowed, rawTags)),
+        next_cursor: r.next_cursor,
+      };
+    }
     if (result && typeof result === "object" && "id" in result && "tags" in result) {
       return noteWithinTagScope(result as any, allowed, rawTags)
         ? result

package/src/module-config.ts

@@ -15,15 +15,27 @@
  * PUT /.parachute/config is Phase 3 — not implemented here.
  *
  * Fields currently described:
- *   - audio_retention: per-vault enum, backed by VaultConfig.audio_retention.
- *   - scribe_url:      env var SCRIBE_URL (read-only for now — there is no
- *                      yaml slot yet, so PUT won't come online until Phase 3).
- *   - scribe_token:    env var SCRIBE_TOKEN, writeOnly (never returned).
- *   - port:            GlobalConfig.port, exposed read-only so the hub can
- *                      display it without round-tripping through /health.
+ *   - audio_retention:      per-vault enum, backed by VaultConfig.audio_retention.
+ *   - port:                 GlobalConfig.port, exposed read-only.
+ *   - autoTranscribe.*:     vault↔scribe handoff (vault#353, design 2026-05-21
+ *                           Part 2). Three nested fields per design Q4:
+ *       - enabled:          boolean toggle, default false (persisted in
+ *                           GlobalConfig.auto_transcribe.enabled).
+ *       - scribeUrl:        readOnly — resolved per-process from
+ *                           `~/.parachute/services.json` via
+ *                           `scribe-discovery.ts`. Operators can't point at an
+ *                           arbitrary scribe; the discovery layer is the gate.
+ *       - scribeBearer:     writeOnly — sourced from SCRIBE_AUTH_TOKEN env var.
+ *                           Hub install generates one at first boot
+ *                           (see scribe-env.ts:ensureScribeBearer); manual
+ *                           rotation is via `parachute-vault config set`.
+ *   - scribe_url / scribe_token (deprecated): kept under their legacy names
+ *                           through one release for the hub admin SPA's prior
+ *                           render path; new code should read autoTranscribe.*.
  */
 
 import type { VaultConfig, GlobalConfig } from "./config.ts";
+import { resolveScribeUrl } from "./scribe-discovery.ts";
 
 export interface ModuleConfigSchema {
   $schema: string;
@@ -49,20 +61,54 @@ export function buildConfigSchema(): ModuleConfigSchema {
         description:
           "What to do with audio attachments after transcription. `keep` leaves the file on disk; `until_transcribed` unlinks on successful transcribe (keeps on failure for retry); `never` unlinks on any terminal state (including failure — no retries).",
       },
+      autoTranscribe: {
+        type: "object",
+        title: "Auto-transcribe voice uploads",
+        description:
+          "When enabled, audio attachments (mime-type prefix `audio/`) are automatically sent to scribe and the resulting transcript lands as a sibling `<attachment-path>.transcript.md` note. Scribe must be reachable for transcription to succeed; failures are recorded as a transcript note with `transcript_status: failed`.",
+        properties: {
+          enabled: {
+            type: "boolean",
+            default: false,
+            title: "Enable auto-transcription",
+            description:
+              "Master toggle. When false, audio uploads land normally without any scribe interaction. Global — persisted in `GlobalConfig.auto_transcribe.enabled` and applies to every vault on this server. Per-vault control is a future enhancement when multi-vault deployments need it.",
+          },
+          scribeUrl: {
+            type: "string",
+            format: "uri",
+            readOnly: true,
+            title: "Scribe URL",
+            description:
+              "URL of the scribe service. Auto-populated from `~/.parachute/services.json` at vault startup (or from the SCRIBE_URL env var when set). Read-only — operators can't point at an arbitrary scribe.",
+          },
+          scribeBearer: {
+            type: "string",
+            writeOnly: true,
+            title: "Scribe auth bearer",
+            description:
+              "Shared bearer for the vault→scribe loopback contract. Hub install generates one at first boot. Write-only — never returned by GET.",
+          },
+        },
+      },
+      // Legacy aliases kept for back-compat with callers that read the
+      // pre-vault#353 shape. New consumers should read `autoTranscribe.*`.
       scribe_url: {
         type: "string",
         format: "uri",
-        title: "Scribe URL",
+        title: "Scribe URL (deprecated alias)",
         description:
-          "URL of the Scribe service for transcription. Empty disables the background worker. Currently sourced from the SCRIBE_URL env var; a PUT slot lands in Phase 3.",
+          "Legacy alias for `autoTranscribe.scribeUrl`. Will be removed in a future release.",
         readOnly: true,
+        deprecated: true,
       },
       scribe_token: {
         type: "string",
-        title: "Scribe auth token",
+        title: "Scribe auth token (deprecated alias)",
         description:
-          "Optional bearer token for Scribe. Stored in the SCRIBE_TOKEN env var today. Write-only — never returned by GET.",
+          "Legacy alias for `autoTranscribe.scribeBearer`. Will be removed in a future release.",
         writeOnly: true,
+        deprecated: true,
       },
       port: {
         type: "integer",
@@ -77,18 +123,28 @@ export function buildConfigSchema(): ModuleConfigSchema {
 }
 
 /**
- * Effective config values, with `writeOnly` fields stripped. `scribe_token` is
- * declared `writeOnly` and is never returned here, even when SCRIBE_TOKEN is
- * set in the environment.
+ * Effective config values, with `writeOnly` fields stripped. `scribeBearer`
+ * (and its legacy alias `scribe_token`) are declared `writeOnly` and never
+ * returned, even when set in the environment.
  */
 export function buildConfigValues(
   vaultConfig: VaultConfig,
   globalConfig: GlobalConfig,
   env: { SCRIBE_URL?: string | undefined } = process.env as { SCRIBE_URL?: string },
 ): Record<string, unknown> {
+  // Resolve scribe URL through the discovery layer so the GET shape reflects
+  // what the worker will actually use (services.json > SCRIBE_URL > unset).
+  // Pass env through so the test harness's override is honored.
+  const scribeUrl = resolveScribeUrl(env as NodeJS.ProcessEnv) ?? "";
   return {
     audio_retention: vaultConfig.audio_retention ?? "keep",
-    scribe_url: env.SCRIBE_URL ?? "",
+    autoTranscribe: {
+      enabled: globalConfig.auto_transcribe?.enabled ?? false,
+      scribeUrl,
+    },
+    // Legacy alias mirrors `autoTranscribe.scribeUrl` so hubs reading the
+    // pre-vault#353 shape don't regress.
+    scribe_url: scribeUrl,
     port: globalConfig.port,
   };
 }